Claude Code Hooks: إعدادات settings.json والـ 5 أحداث وحجب الـ exit code
الـ hooks هي الطبقة الحتمية في Claude Code: تعمل دائمًا دون مطالبة النموذج بشيء. يشرح هذا الدليل المصوّر، بلقطات من فيديو Anthropic الرسمي للـ hooks – الأحداث الخمسة، وسكربت حجب في PreToolUse، وJSON رفض منظم، وإعداد تنسيق كامل في PostToolUse.
خلاصة سريعة – ما هي الـ hooks في Claude Code
- الـ hooks حتمية: تعمل في نقاط ثابتة من دورة حياة Claude Code كل مرة بلا استثناء. تعليمة في CLAUDE.md مثل «شغّل Prettier بعد كل تعديل» تُنفَّذ غالب الوقت – أما الـ hook فيُنفَّذ دائمًا.
- هناك خمسة أحداث: UserPromptSubmit (قبل معالجة prompt الخاص بك)، وPreToolUse (قبل استدعاء أداة)، وPostToolUse (بعد اكتمال الأداة)، وNotification، وStop (عندما ينهي Claude إجابته).
- أي hook من نوع PreToolUse ينتهي بالخروج برمز 2 يحجب استدعاء الأداة، وتُمرَّر رسالة stderr إلى Claude ليعرف السبب. أما الخروج برمز 0 فيسمح بمتابعة الاستدعاء.
- تعيش الـ hooks في settings.json – حدث، ومطابِق أدوات اختياري، وأمر. احفظها في .claude/settings.json الخاص بالمشروع وارفعها للمستودع، فيرث فريقك بأكمله الضمانات نفسها.
Hooks in Claude Code
القناة:Claude (official Anthropic channel)3:22
Claude Code Hooks, Explained Simply
القناة:Agentic Lab8:32
Claude Code - Getting Started with Hooks
القناة:Greg Baugues11:53
Hooks reference — Claude Code documentation
الوثائق:code.claude.com
لقطات هذا الدليل مأخوذة من الفيديو التوضيحي الرسمي للـ hooks من Anthropic؛ ونص الجولة كُتب باستقلالية وقوبل بالمرجع الرسمي للـ hooks.
تبقى لقطات الشاشة ملكًا لصناعها وتُستخدم بإسناد المصدر بوصفها توثيقًا مرئيًا. وكل خطوة تتضمن رابطًا مباشرًا إلى اللحظة نفسها في الفيديو الأصلي.
إعداد Claude Code hooks خطوة بخطوة
1 · كيف تبدو الـ hooks في الواقع
- 1
شاهد hook يشتغل في نهاية الإجابة
يقرأ شريط الحالة «Running stop hook · 39s · 484 tokens» – ينهض Claude Code بتنفيذ stop hook قبل أن يعيد الدور إليك. هذه هي الفكرة كلها في لقطة واحدة: أمر سجلته يعمل في نقطة ثابتة من الدورة، عند كل حالة مطابقة، دون أي اعتماد على ذاكرة النموذج.
stop hook يعمل بعد إجابة Claude – بعد 39 ثانية، و484 توكنًا مستهلَكة.شاهد عند 0:10 - 2
تعرّف على أحداث الـ hooks الخمسة
يعمل UserPromptSubmit لحظة إرسال الـ prompt وقبل معالجة Claude له. وPreToolUse قبل كل استدعاء أداة. وPostToolUse بعد اكتمال الاستدعاء. ويشتغل Notification عندما يرسل Claude إشعارًا، وStop عندما ينهي إجابته. وكل hook تكتبه يتصل بواحدة من هذه النقاط الخمس بالتحديد.
الأحداث الخمسة من الفيديو الرسمي للـ hooks من Anthropic – كل ما عداها يتفرع من هذه القائمة.شاهد عند 1:04
2 · اكتب أول hooks لديك
- 3
أضف كتلة hooks إلى settings.json
الـ hook في settings.json ثلاثية: اسم الحدث، ومطابِق اختياري يحدد الأداة التي يخصها، والأمر المراد تنفيذه. في اللقطة يُستكمل مطابِق PreToolUse بالقيمة Edit – فلن يعمل هذا الـ hook إلا عند استدعاءات تعديل الملفات. وإذا كنت تكره تعديل JSON يدويًا فقائمة /hooks تحرّر الإعداد نفسه تفاعليًا.
الإكمال التلقائي يجعل المطابِق Edit، فيحصر الـ hook من نوع PreToolUse في تعديل الملفات فقط.شاهد عند 0:14 - 4
احجب الأوامر الخطرة برمز الخروج 2
يستقبل hook من نوع PreToolUse اسم الأداة ومدخلاتها كـ JSON على stdin. يمرّر هذا السكربت المدخلات عبر jq لالتقاط .tool_input.command، ثم يبحث بـ grep عن أنماط مدمرة – rm -rf وgit push --force – وعند أي تطابق يطبع السبب على stderr ويخرج برمز 2. ورمز 2 يحجب الاستدعاء؛ ويعاد نص stderr إلى Claude بوصفه تغذية راجعة، فيعرف النموذج سبب الحجب ويعدّل مساره.
jq يقرأ الأمر من stdin؛ وعند مطابقة rm -rf أو --force يُطبع على stderr ويخرج برمز 2.شاهد عند 2:02 - 5
أرسل رفضًا منظّمًا بدل رمز الخروج
لتحكم أدق، يمكن للـ hook أن يطبع قرارًا بصيغة JSON بدل الاعتماد على رموز الخروج. هنا يعترض hook من نوع PreToolUse أمر DROP TABLE، ويحمل hookSpecificOutput قيمة permissionDecision بقيمة «deny» مع سبب – «استخدم migration بدلًا من ذلك» – يصل مباشرة إلى سياق النموذج. الحماية القوية نفسها، لكن مع تعليمة قابلة للتنفيذ.
permissionDecision بقيمة deny يحجب أمر SQL ويخبر النموذج بما يفعله بدلًا منه.شاهد عند 2:16 - 6
احفظ الـ hooks في المستودع ليحصل عليها الفريق
الـ hooks المضبوطة في .claude/settings.json الخاص بالمشروع على مستوى المشروع وقابلة للرفع. كل من يستنسخ المستودع يشغّل الـ hooks نفسها تلقائيًا – ومنها أدوات الحجب. احفظ السكربتات المساعدة في .claude/hooks/ وأشر إليها بمتغير البيئة CLAUDE_PROJECT_DIR حتى تُحل المسارات مهما كان مجلد عمل Claude الحالي.
مجلد .claude في المشروع يضم settings.json إضافة إلى مجلد hooks/ للسكربتات المشتركة.شاهد عند 0:17 - 7
انسخ إعداد hooks كاملًا وجاهزًا
يؤدي هذا الإعداد وظيفتين معًا. كتلة PostToolUse تطابق Edit|Write|MultiEdit وتشغّل .claude/hooks/auto-format.sh بمهلة 30 ثانية، فيُنسّق كل ملف يلمسه Claude. وتحتها يطابق hook ثانٍ Bash ويسجّل كل أمر منفّذ – هذا نمط الامتثال. والحقلان timeout وasync يمنعان أدوات التنسيق البطيئة من تعطيل الجلسة.
تنسيق تلقائي عبر PostToolUse بمهلة 30 ثانية، مع hook لـ Bash يسجّل كل أمر.شاهد عند 2:46
3 · شغّلها بعقلية الفريق
- 8
احفظ اتفاقية رموز الخروج عن ظهر قلب
رمز الخروج 0 يعني المتابعة. ورمز 2 يعني الحجب – وتُمرَّر stderr إلى Claude بوصفها تغذية راجعة قابلة للتفعيل. وأي رمز آخر يعرض stderr لك أنت المستخدم لكن استدعاء الأداة يتابع؛ استخدمه للتحذيرات التي تريد رؤيتها دون حجب الوكيل حجبًا صارمًا.
- 9
سجّل الـ hooks من قائمة /hooks واختر وصفاتك
يفتح أمر /hooks الإعداد نفسه تفاعليًا – وهو مفيد للتحقق من الـ hooks المسجلة في كل نطاق. ومن هنا تأتي الوصفات الأربع الأكثر استخدامًا: تنسيق تلقائي بعد التعديل (PostToolUse)، وتسجيل كل الأوامر المنفذة (PostToolUse على Bash)، وحجب العمليات الخطرة (PreToolUse برمز خروج 2)، وإشعارك عند انتهاء Claude (Stop). القاعدة الذهبية: ما يجب أن يحدث كل مرة بلا فشل، لا تضعه في prompt – بل اجعله hook.
اتفاقية رموز الخروج في جدول واحد
يتواصل كل أمر hook عبر رمز خروجه. وثلاث حالات تغطي كل ما تحتاجه:
- exit 0المتابعة. يُنفَّذ استدعاء الأداة كالمعتاد، ويظهر stdout الخاص بالـ hook في وضع transcript (Ctrl-R).
- exit 2الحجب. يُرفض استدعاء الأداة وتُمرَّر stderr الخاصة بالـ hook إلى Claude بوصفها تغذية راجعة، فيستطيع النموذج تصحيح المسار – وهذا ما يجعل hooks رمز 2 تعليمية لا فادحة فحسب.
- exit 1أي رمز آخر: تحذير دون حجب. تُعرض stderr لك لكن الاستدعاء يتابع. استخدمه لhooks استشارية – «هذا الملف مولّد عادة، هل أنت متأكد؟»
وهناك مسار ترقية آخر: بدل رموز الخروج يمكن للـ hook أن يطبع قرار JSON (hookSpecificOutput مع permissionDecision) للرفض بسبب منظم، كما في الخطوة 5. رموز الخروج هي الاتفاقية البسيطة، وقرارات JSON هي المكتوبة بأنواع محددة.
أربع وصفات تستحق الرفع اليوم
يذكر الفيديو الرسمي أربع حالات استخدام؛ وإليكها بصياغة جاهزة للنسخ:
- 1تنسيق تلقائي بعد التعديل – hook من نوع PostToolUse يطابق Edit|MultiEdit ويتفقد امتداد الملف ويشغّل المنسق المناسب: Prettier لـ TypeScript وgofmt لـ Go وRuff لـ Python.
- 2تسجيل كل أمر منفّذ – hook من نوع PostToolUse على Bash يضيف كل أمر إلى ملف سجل. تحبه فرق الامتثال؛ وسيحبه أنت المستقبلي وأنت تتصيد أخطاء يوم الثلاثاء الماضي.
- 3حجب العمليات الخطرة – hook من نوع PreToolUse برمز خروج 2 يحمي مجلدات إعدادات الإنتاج وأنماط rm -rf والرفع إلى main. بهذه تتحول من «اقتراحات» إلى «ضمانات».
- 4إشعار عند انتهاء المهمة – hook من نوع Stop أو Notification يطلق إشعارًا على سطح المكتب أو صوتًا، فلا تحتاج إلى مراقبة جلسات الوكلاء الطويلة.
تتسع الوصفات الأربع في ملف .claude/settings.json واحد. ابدأ بالمنسق – إنه الـ hook الذي ستشعر به عند كل حفظ.