خطاطف Claude Code: دليل المستخدمين المتقدمين لأتمتة وكيلك
خطاطف Claude Code تُشغّل أوامرك تلقائيًا عند أحداث دورة الحياة — للتحقق، أو الفحص اللغوي، أو الحظر، أو التسجيل دون تدخّل منك. الأحداث، والتهيئة، وخمس وصفات جاهزة، وفخ رمز الخروج، وكيفية تشغيل Claude Code دون أي إعداد.
ملفات (hooks) في Claude Code هي أوامر يحددها المستخدم تعمل تلقائيًا في نقاط محددة من دورة حياة Claude Code — قبل استدعاء أداة، بعد تعديل، عند بدء جلسة، عند إنهاء Claude لدوره — لتتمكن من التحقق من الإجراءات أو تنسيقها أو تسجيلها أو حظرها دون الحاجة لأن تكون في الحلقة كل مرة. إنها الفارق بين وكيل ترميز مدعوم بالذكاء الاصطناعي يقترح ووكيل يتبع قواعدك بشكل حتمي. يشرح هذا الدليل ما هي الـ hooks، وكل الأحداث التي يمكن أن تُفعّل عليها، وكيفية تكوينها، وخمس وصفات عملية يمكنك نسخها، ومشكلة رمز الخروج (exit code) التي تعثر الجميع، وكيفية استخدام القوة الكاملة لـ Claude Code دون أي إعداد محلي.
ما هي ملفات hooks في Claude Code؟
الـ hook هو معالج (handler) — أمر شل، أو نقطة نهاية HTTP، أو استدعاء أداة MCP، أو حتى موجّه (prompt) للنموذج — يقوم Claude Code بتشغيله تلقائيًا عند حدوث حدث معين. يستقبل المعالج مدخلات مُنظّمة (على stdin بالنسبة لمعالجات الأوامر، أو كنص POST بالنسبة لمعالجات HTTP)، ويمكنه فحص ما يحدث، واتخاذ إجراء، واختياريًا إعادة قرار يغيّر ما يفعله Claude بعد ذلك.
هذا الجزء الأخير هو ما يجعل الـ hooks قوية وليست مجرد أداة مريحة. فالـ hook ليس مجرد إشعار — يمكنه حظر استدعاء أداة، أو إعادة كتابة مدخلات أو مخرجات أداة، أو إدخال سياق إضافي، أو إيقاف Claude تمامًا. بعبارة أخرى، تحوّل الـ hooks Claude Code من مساعد ذكي إلى مساعد قابل للبرمجة يفرض ضوابط فريقك بشكل حتمي، وليس فقط عندما يتذكرها النموذج بمحض الصدفة.
متى تُفعَّل الـ hooks: دورة الحياة
تُرفق الـ hooks بأحداث، ويعرض Claude Code عددًا كبيرًا منها. تُصنّف حسب التكرار: بعضها يُفعَّل مرة واحدة في كل جلسة، وبعضها مرة واحدة في كل دور، وبعضها عند كل استدعاء أداة.
أين تُفعَّل الـ hooks عبر جلسة Claude Code — من SessionStart إلى SessionEnd.
الأحداث التي ستستخدمها أكثر:
SessionStart/SessionEnd— مرة واحدة عند بدء الجلسة أو انتهائها. مثالية لتحميل السياق (المشكلات المفتوحة، معلومات الفرع، متغيرات البيئة) أو التنظيف.UserPromptSubmit— تُفعَّل عند إرسال موجّه (prompt)، قبل أن يعالجه Claude. يمكنك تصفية الموجّه أو تعزيزه.PreToolUse— قبل أي استدعاء أداة. هنا تحظر الإجراءات الخطيرة.PostToolUse(وPostToolUseFailure) — بعد نجاح استدعاء أداة (أو فشله). المكان المناسب للفحص اللغوي والتنسيق والتحقق.Stop/StopFailure— عند انتهاء استجابة Claude، أو انتهاء الدور بخطأ.Notification— عندما يصدر Claude Code إشعارًا (مفيد لتنبيهات سطح المكتب).
بالإضافة إلى ذلك، يُفعّل Claude Code أيضًا hooks للوكلاء الفرعيين (SubagentStart/SubagentStop)، والمهام (TaskCreated/TaskCompleted)، وضغط السياق (PreCompact/PostCompact)، وتغييرات دليل العمل (CwdChanged)، وتغييرات الملفات على القرص (FileChanged)، وتحميل التعليمات (InstructionsLoaded)، وغيرها. الاتساع هو المقصود: يمكنك إرفاق سياسة في أي لحظة تقريبًا في حلقة الوكيل.
الأنواع الخمسة من معالجات hook
يمكن لحدث hook أن يُفعّل خمسة أنواع مختلفة من المعالجات، وهذا ما يجعل النظام مرنًا:
command— يشغّل أمر شل؛ يقرأ المدخلات على stdin، ويشير إلى القرارات عبر رمز الخروج (exit code) و stdout.http— يرسل JSON الحدث عبر POST إلى عنوان URL ويقرأ استجابة JSON.mcp_tool— يستدعي أداة على خادم MCP متصل.prompt— تقييم نموذج بدور واحد يعيد قرار JSON بنعم/لا (مفيد للفحوصات غير الدقيقة).agent— يُنشئ وكيلًا فرعيًا (تجريبي).
بالنسبة لمعظم الفرق، تقوم معالجات command بـ 90% من العمل — سكريبت شل واحد كافٍ للفحص اللغوي أو الحظر أو التسجيل.
كيفية تكوين hook
تعيش الـ hooks في ملفات الإعدادات (وثائق Claude Code hooks الرسمية هي المرجع الأساسي)، والمكان الذي تضعها فيه يتحكم في نطاقها:
| الموقع | النطاق |
|---|---|
~/.claude/settings.json | جميع مشاريعك |
.claude/settings.json | مشروع واحد (قابل للالتزام (commit) — قابل للمشاركة مع فريقك) |
.claude/settings.local.json | مشروع واحد، محلي فقط (مستثنى من git) |
| إعدادات السياسة المُدارة | على مستوى المؤسسة (المسؤول) |
يتداخل الهيكل على ثلاثة مستويات: اختر حدثًا، وأضف مجموعة مطابقة (matcher)، ثم عرّف المعالجات. تحدد أدوات المطابقة أي استدعاءات أدوات ينطبق عليها الـ hook — "*" (أو حذفه) يطابق كل شيء، ومطابقة بسيطة مثل Edit|Write تطابق تلك الأدوات بالضبط، وأي شيء أكثر تعقيدًا يُعامل كتعبير نمطي (regular expression). (تطابق أدوات MCP النمط mcp__<server>__<tool>.)
هذا مثال على hook من نوع PostToolUse يشغّل فحصًا لغويًا (lint) بعد كل تعديل:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "/path/to/lint-check.sh" }]
}
]
}
}خمس وصفات عملية لـ hooks
هذه هي الأنماط التي تلجأ إليها الفرق أولاً:
- الفحص اللغوي أو التنسيق بعد كل تعديل. hook من نوع
PostToolUseمطابق لـEdit|Writeيشغّل أداة التنسيق أو الفحص اللغوي الخاصة بك، حتى يفي كود الوكيل دائمًا بقواعد أسلوبك. - حظر الأوامر المدمّرة. hook من نوع
PreToolUseمطابق لـBashيفحص الأمر ويحظرrm -rfوأمثاله قبل أن يعمل أبدًا. - إشعارات سطح المكتب. hook من نوع
Notificationينبّهك عندما يحتاج Claude إلى انتباهك أو ينهي مهمة طويلة. - تسجيل التدقيق (audit logging). hook من نوع
PostToolUse(أو موجّه لـ MCP) يسجّل كل استدعاء أداة للامتثال — ما تم تشغيله، ومتى، وبأي وسائط. - تحميل سياق المشروع عند البدء. hook من نوع
SessionStartيستدعي المشكلات المفتوحة، أو الفرع الحالي، أو متغيرات البيئة حتى يبدأ الوكيل كل جلسة موجّهًا مسبقًا.
خمس وصفات hook شائعة والأحداث التي تُرفق بها.
مشكلة رمز الخروج (Exit Code)
هذا هو التفصيل الذي يعثر الجميع، فاستوعبه جيدًا: بالنسبة لمعالجات command، فقط رمز الخروج 2 يحظر. يعني الخروج بـ 0 النجاح (ويُحلَّل stdout بحثًا عن أي قرار JSON). الخروج بـ 2 هو خطأ حاجب (blocking) — يُعاد stderr الخاص به إلى Claude. أي رمز آخر، بما في ذلك الخروج بـ 1، هو خطأ غير حاجب — يستمر Claude في عمله.
فإذا كتبت hook لـ "حظر هذا" وخرجت بـ exit 1، فلن يحظر — سيتقدم الإجراء. لفرض سياسة فعليًا من hook أمر، اخرج بـ exit 2. (يمكن لمعالجات الأمر أيضًا إعادة تحكم أغنى كـ JSON على stdout — permissionDecision: "deny" لـ PreToolUse، و updatedInput لإعادة كتابة الوسائط، و additionalContext لإدخال معلومات، و continue: false لإيقاف Claude تمامًا.)
مثال عملي: حظر rm -rf
لنبني حارس الأمر المدمّر من البداية للنهاية، لأنه يوضّح كل جزء متحرك. أولاً، التكوين — hook من نوع PreToolUse مطابق لـ Bash:
{ "hooks": { "PreToolUse": [{ "matcher": "Bash",
"hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh" }] }] } }ثم السكريبت، guard.sh. يرسل Claude Code الحدث كـ JSON على stdin، متضمنًا مدخلات الأداة؛ يقرأ السكريبت هذا، ويفحص الأمر، ويقرر:
#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
echo "Blocked: destructive command refused by policy." >&2
exit 2 # exit 2 blocks — exit 1 would NOT
fi
exit 0السطر الحاسم هو exit 2. أعِد 0 وسيُشغَّل الأمر؛ أعِد 1 و — بشكل غير متوقع — سيظل يُشغَّل كخطأ غير حاجب؛ فقط exit 2 يحظر ويعيد رسالة stderr الخاصة بك إلى Claude ليفهم السبب. اجعل السكريبت قابلًا للتنفيذ، والتزمه (commit) تحت .claude/hooks/، والآن يمرّ كل استدعاء Bash عبر حارسك — لفريقك بأكمله، بما أن settings.json الخاص بالمشروع قابل للمشاركة. للحصول على ضمان صارم بدلًا من شبكة أفضل مجهود، اقرنه بقواعد الأذونات في Claude Code؛ كشبكة أمان حتمية ومُتحكم بها بالإصدار، هذا الـ hook يقوم بالمهمة بالفعل.
متى لا تكون الـ hooks الحل
الـ hooks مخصصة للسياسات الحتمية والمتكررة — "افحص لغويًا دائمًا بعد تعديل"، "لا تشغّل rm -rf أبدًا." وهي الأداة الخاطئة للأشياء التي تحتاج إلى حكم (استخدم النموذج أو hook من نوع prompt للحالات الغامضة) وللضمانات الأمنية الصارمة (استخدم نظام الأذونات، إذ تفشل مرشحات if في معالج الأمر بشكل مفتوح). لا تفرط في استخدام الـ hooks أيضًا: يشغّل كل hook من نوع أمر عملية مع مهلة زمنية (timeout)، وحشد من الـ hooks البطيئة يضيف زمن انتقال إلى كل استدعاء أداة. حافظ عليها سريعة وقليلة العدد ومركّزة على القواعد التي تهم فعلاً.
ملاحظات أمان تستحق المعرفة
بعض الحقائق التي توضحها الوثائق بشكل صريح:
- يفشل مرشح
ifبشكل مفتوح. إذا استخدمت حقلifلتحديد نطاق hook لقاعدة إذن ولم يتمكن الأمر من التحليل (parse)، فسيعمل الـ hook مع ذلك. للفرض الصارم للسماح/الرفض، استخدم نظام الأذونات في Claude Code، وليس الـ hooks. - تعمل الـ hooks دون طرفية تحكم (controlling terminal) — لا يمكنها الطلب على
/dev/tty. استخدمsystemMessageأو مخرجاتterminalSequenceالمقيّدة للرسائل الموجهة للمستخدم. - يجب أن يكون stdout نظيفًا. يجب أن يكون كائن قرار JSON فقط موجودًا على stdout؛ يمكن لمخرجات ملف تعريف الشل الشاردة أن تكسر التحليل (parsing).
- تعامل مع السياق المُدرَج بعناية. يجب كتابة
additionalContextكعبارات واقعية، وليس أوامر إلزامية، للتوافق بشكل جيد مع دفاعات حقن الموجّهات (prompt-injection).
الـ Hooks هي هندسة الإطار (harness engineering) في صورة مصغّرة
خذ خطوة إلى الخلف وستجد أن الـ hooks مثال ملموس على فكرة أكبر: النموذج ليس الوكيل بأكمله — النظام المحيط به هو ما يهم. الـ hooks جزء من الإطار (harness) الذي يجعل وكيل الترميز موثوقًا، جنبًا إلى جنب مع الحلقة والأدوات والذاكرة والصندوق المعزول (sandbox). (نتعمق في هذا النموذج الذهني في هندسة الإطار (harness engineering).) عندما تكتب حظرًا في PreToolUse أو فاحصًا لغويًا في PostToolUse، فأنت تقوم بهندسة الإطار — تشكيل سلوك الوكيل بشكل حتمي بدلًا من الأمل في أن يتصرف النموذج بشكل صحيح.
يوضّح هذا التوصيف أيضًا متى تستحق الـ hooks الجهد المبذول: أي قاعدة كنت ستضطر لتذكير الوكيل بها كل مرة هي مرشحة لأن تكون hook.
استخدام القوة الكاملة لـ Claude Code دون إعداد محلي
تعيش الـ hooks في واجهة سطر أوامر (CLI) Claude Code، وهذا يعني أنك تحتاج إلى تثبيتها وتكوينها لاستخدامها — عقبة لأي شخص غير مُهيَّأ في طرفية، ومستحيلة لأعضاء الفريق غير المطورين. إذا كنت تريد إمكانيات الوكيل في Claude Code دون إدارة تثبيت محلي، يمكنك تشغيل Claude Code في متصفحك على Happycapy: يشغّل Claude Code في صندوق معزول (sandbox) سحابي مُدار حيث يكون الإطار (harness) — الحلقة والأدوات والذاكرة والعزل التي تتصل بها الـ hooks — موصولًا مسبقًا من أجلك. تصف مهمة وتشاهد الوكيل يعمل على سطح مكتب بصري، بدون حاجة إلى طرفية.
فكّر في الأمر بهذه الطريقة: الـ hooks تتيح للمستخدمين المتقدمين ضبط إطار (harness) Claude Code يدويًا؛ بينما توفّر Happycapy إطارًا مُدارًا جاهزًا للجميع. إذا كنت تريد تشغيل Claude Code ولكن إعداد CLI أوقفك، ابدأ مجانًا على happycapy.ai وشغّل مهمة حقيقية في متصفحك اليوم.
الأسئلة الشائعة
س: ما هي ملفات hooks في Claude Code؟
هي معالجات (handlers) يحددها المستخدم — أوامر شل، أو نقاط نهاية HTTP، أو استدعاءات أداة MCP، أو موجّهات نموذج — يشغّلها Claude Code تلقائيًا عند أحداث دورة الحياة مثل قبل استدعاء أداة (PreToolUse)، أو بعد تعديل (PostToolUse)، أو عند بدء الجلسة. يمكنها التحقق من الإجراءات أو تنسيقها أو تسجيلها أو حظرها أو إعادة كتابتها.
س: ما هي أحداث hook التي يدعمها Claude Code؟
كثيرة — بما فيها SessionStart/SessionEnd، و UserPromptSubmit، و PreToolUse، و PostToolUse (و PostToolUseFailure)، و Stop/StopFailure، و Notification، وأحداث الوكيل الفرعي والمهام، وأحداث الضغط. تُفعَّل مرة واحدة في كل جلسة، أو مرة واحدة في كل دور، أو عند كل استدعاء أداة.
س: كيف أجعل hook يحظر استدعاء أداة؟
بالنسبة لمعالجات الأمر، اخرج برمز 2 — فقط الخروج بـ 2 يحظر (الخروج بـ 1 لا يحظر). بالنسبة لـ PreToolUse، يمكنك أيضًا إعادة JSON مع permissionDecision: "deny". للفرض الصارم، يُفضَّل استخدام نظام الأذونات في Claude Code، إذ يفشل مرشح if للـ hook بشكل مفتوح.
س: أين أُكوِّن ملفات hooks في Claude Code؟
في ملفات الإعدادات: ~/.claude/settings.json (جميع المشاريع)، أو .claude/settings.json (مشروع واحد، قابل للمشاركة)، أو .claude/settings.local.json (محلي فقط). تختار حدثًا، وتضيف مطابقة (matcher)، وتعرّف المعالجات.
س: هل يمكنني استخدام hooks في Claude Code دون تثبيت CLI؟
تتطلب الـ hooks بنفسها واجهة سطر أوامر (CLI) Claude Code. إذا كان هدفك استخدام Claude Code دون إعداد محلي، شغّله في صندوق معزول (sandbox) سحابي مُدار مثل Happycapy، الذي يوفّر الوكيل وإطاره (harness) جاهزين للعمل — مثالي عندما لا تريد تثبيت CLI وتكوينها بنفسك.
س: ما هو أول hook جيد لإضافته؟
فاحص لغوي (linter) من نوع PostToolUse مطابق لـ Edit|Write — يشغّل أداة التنسيق الخاصة بك بعد كل تغيير في الكود، حتى تفي مخرجات الوكيل دائمًا بقواعد أسلوبك. منخفض الخطورة ومفيد فورًا.
