يربط الـ hook حدثًا في الجلسة بأمر. سنبني hook للإشعارات، ثم hook ينسّق ملف Python بعد تعديله. وخلال ذلك سنقرأ الإعدادات ونفحص بيانات الحدث.
قبل أن تربطوا أي شيء بالوكيل، شغّلوا الأمر بأنفسكم. على سطح مكتب Linux، يوجد أمر قياسي اسمه notify-send يُظهر إشعارًا منبثقًا. وعلى WSL، اطلبوا من الوكيل أن يكتب سكربتًا صغيرًا لذلك. يمكن للسكربت تشغيل PowerShell من داخل WSL وإظهار نافذة إشعار في Windows. وعلى Mac، يستطيع الوكيل كتابة سكربت أيضًا. أيًّا كان الأمر، تحقّقوا أولًا من أنه يعمل وحده، خارج الـ hook.
سيشغّل أول hook لنا هذا الأمر عندما يُصدر Claude Code إشعار طلب إذن. فينبّهنا بينما نافذة أخرى في المقدّمة.
هذه هي الإعدادات كلها، في الملف .claude/settings.json. يحتوي البند الخارجي hooks على إعدادات الـ hook الخاص بنا. الحدث هو Notification. وهو يخبر الـ harness بالنقطة التي تهمّنا في الجلسة.
يختار الـ matcher الحالات التي نريدها. هنا نختار إشعارات طلب الإذن، بكتابة permission_prompt في الـ matcher. لا حاجة إلى أن نستجيب لكل نوع من الإشعارات لمجرّد أنه يأتي عبر الحدث نفسه.
يحتوي الـ handler على «type: command»، ويليه الأمر الذي سيُنفَّذ. وهذا هو الأمر الذي اختبرناه يدويًا. اقرؤوا هذا البند كثلاثة قرارات. الحدث يحدّد متى يمكن أن يُشغَّل الـ hook، والـ matcher يحدّد الحالات المطابقة، والـ handler يحدّد ماذا نشغّل.
تتيح لنا قائمة /hooks أن نفحص الـ hooks المُعَدّة وأحداثها. تحقّقوا من تحميل hook الإشعارات هذا. ثم شغّلوا إجراءً غير ضارّ يحتاج إلى إذن وفق إعدادات هذه الجلسة.
وبينما نافذة أخرى في المقدّمة، يخبرنا الإشعار على سطح المكتب بأن الجلسة تحتاج إلى انتباهنا. أما طلب الإذن الأصلي فما زال ينتظر. بهذا يكتمل المثال الأول. وقع حدث مطابق، فشغّل الـ harness الأمر، ورأينا أثره.
مثالنا الثاني هو hook ينسّق ملف Python مباشرةً بعد أن يعدّله الوكيل. وهكذا يحافظ الكود الذي يكتبه الوكيل على تنسيق المشروع، ولا يحتاج أحد إلى تشغيل أداة التنسيق يدويًا. لهذا الغرض، يجب أن يعرف الـ hook أي ملف عُدِّل. والـ harness يخبره. فهو يرسل كائن JSON يصف الحدث إلى الإدخال القياسي للبرنامج. ويذكر الكائن اسم الحدث، ومجلد العمل، والأداة، ومُدخَلات الأداة. ونعرض هنا الحقول التي يحتاجها هذا المثال فقط.
مسار الملف داخل مُدخَلات الأداة يخبر الـ handler أي ملف عُدِّل. ولكل نوع من الأحداث حقوله الخاصة. ابحثوا عنها في التوثيق، أو ببساطة اسألوا الوكيل عنها.
الآن نضيف hook التنسيق إلى الإعدادات. ويستخدم بنية الإعدادات نفسها التي رأيناها في مثال الإشعارات. الحدث هو PostToolUse، ويقع بعد أن تنجح أداة ما. والـ matcher يختار الأداتين Edit وWrite.
يشغّل الأمر مفسِّر Python الخاص بالمشروع على سكربت الـ handler. كلا المسارين بين علامتي تنصيص، ويبدآن من مجلد المشروع. يحمل المتغيّر CLAUDE_PROJECT_DIR مسار هذا المجلد، وعلامات التنصيص تُبقي كل مسار قطعة واحدة حتى لو كان فيه مسافة. وفي ملف الإعدادات، تُسبق علامات التنصيص الداخلية هذه بشرطة مائلة عكسية.
الـ matcher لا يمرّر إلا أحداث Edit وWrite. ثم يقرأ السكربت مسار الملف ويتحقّق إن كان ملف Python. فنحن نريد تنسيق ملفات Python فقط.
تعديل ملف Python يصل إلى أداة التنسيق. أما تعديل ملف README فيجتاز الـ matcher، لكن السكربت يتجاهله. كثيرًا ما يغيّر الوكلاء الملفات بأمر Bash بدلًا من أداة Edit، مثلًا باستخدام sed أو سكربت صغير. هذا التغيير لا يطابق Edit أو Write، فلا يُشغَّل هذا الـ hook إطلاقًا. ولتغطية ذلك، يمكننا مطابقة أداة Bash أيضًا، وجعل السكربت يتحقّق مما إذا كان الأمر قد عدّل ملفات Python.
توجد ملفات الإعدادات في عدة أماكن، ويمكنكم إضافة الـ hook إلى أيٍّ منها. إعدادات المستخدم تسري على كل مشاريعكم. وإعدادات المشروع تنتقل مع المستودع عندما تسجّلونها في commit. أما إعدادات المشروع المحلية فتُبقي تغييرًا خاصًا بكم على حاسوبكم. اختاروا المكان حسب مَن يجب أن يستخدم الـ hook.
مشاركة الإعدادات ليست إلا جزءًا من مشاركة الـ hook. يجب أن يتوفّر أيضًا السكربت الذي يشغّله والأدوات التي يحتاجها. ضعوا الـ handler في مسار نسبي داخل المشروع، ووثّقوا طريقة تثبيت البيئة التي يحتاجها. أما مسار داخل مجلدكم الرئيسي الشخصي فلن يعمل على حاسوب شريككم.
يشغّل الـ hook كودًا بصلاحيات الوصول التي يملكها الحساب الذي يشغّل الوكيل. اقرؤوا هذا الكود قبل تفعيله. تعاملوا مع نص الحدث كبيانات، ومرّروا المسارات بأمان، واختبروا مسارًا فيه مسافات. واختبروا أيضًا ملفًا يجب أن يتجاهله الـ handler. تبيّن لنا هذه الفحوصات هل تتصرّف الأتمتة الصغيرة كما أردنا، قبل أن تُشغَّل مرارًا دون أن ننتبه لها.
باختصار، يجمع الـ hook من نوع command بين برنامج صغير وحدث يشغّله. ابدؤوا بأمر يعمل، واربطوه بالحدث المقصود، ثم اختبروا العملية كلها. بهذا تحصلون على أتمتة تعمل في اللحظة المناسبة، دون أن تشغّلوها بأنفسكم.
عندما يكون لديكم hook للإشعارات، يمكنكم الابتعاد قليلًا وإعداد فنجان قهوة بينما يعمل الوكيل. وإذا احتاج إليكم، فسيُنبّهكم. للأسف، لا يوجد حدث hook يُحضر القهوة إلى مكتبكم. نراكم في الفيديو التالي.