الخطافات (Hooks): أتمتة المهام وضمان الحماية

📚 تنقل السلسلة: المقال السابق 32 أنماط ومخرجات الحديث (Output Styles) علمك كيفية تعديل شخصية ونبرة Claude لتناسب سيناريوهات عملك المختلفة. وينتقل هذا المقال لشرح نمط آخر من الأتمتة - لا يهدف لتعديل شخصيته، بل لتشغيل وإجراء مهام معينة تلقائياً وبشكل حتمي فور رصد حدث محدد: كتنسيق الملفات تلقائياً بعد تعديلها، أو حظر ومنع الأوامر الخطيرة مباشرة، أو إرسال تنبيهات لك عند انتهاء العمل. هذه البرمجيات تسمى الخطافات (Hooks).

تخيل هذا الرقم: خلال أسبوع واحد، أضطررت لتشغيل أمر تنسيق الكود يدوياً prettier --write بعد قيام Claude بالتعديل لـ 23 مرة.

23 مرة. تكرار نفس العملية والخطوات بشكل ميكانيكي وممل لـ 23 مرة. والأسوأ من ذلك هو نسيان تشغيل التنسيق لمرتين - ليتم رفض كود التعديل لاحقاً عند الرفع للمستودع بسبب أخطاء التنسيق، وتضطر لإعادة العملية من جديد.

وهنا يطرح السؤال: لماذا نعتمد على الذاكرة أو وعي Claude لتشغيل عملية متكررة ومطابقة في كل مرة؟ قد نكتب قاعدة "شغل prettier لتنسيق الملفات بعد تعديلها" في ملف CLAUDE.md ولكن Claude ينسى تشغيلها في ثلث الحالات - لكون هذه القاعدة تمثل طلب توصية فقط، وليست ضماناً برمجياً حتمياً.

وبتهيئة خطاف مخصص (Hook) بأسطر بسيطة، تنتهي المشكلة تماماً: فبمجرد قيام Claude بحفظ أي تعديل لملف، يتم تشغيل التنسيق تلقائياً في الخلفية، دون حاجة لتشغيله يدوياً أو القلق من رفض الأكواد لاحقاً. سنشرح في هذا المقال آليات عمل الخطافات وكيفية تهيئتها واستخدامها وتصحيح أخطائها.

بعد قراءة هذا المقال، ستحصل على:

• شرح مبسط لآلية عمل الخطافات والفرق الجوهري بينها وبين القواعد المكتوبة في CLAUDE.md.
• الأحداث واللحظات الأساسية المتاحة لتعليق الخطافات في دورة عمل الوكيل (PreToolUse و PostToolUse و Stop و SessionStart وغيرها).
• مسار كتابة وتهيئة الخطافات في ملف الإعدادات، واستخدام حقل matcher لحصر التشغيل على أحداث محددة (مثل تعديل الملفات فقط).
• ثلاثة أمثلة عملية جاهزة للاستخدام المباشر: التنسيق التلقائي بعد التعديل، وحظر الأوامر الخطيرة، وإرسال تنبيهات عند انتهاء العمل.
• قنوات الاتصال والتبادل البرمجى بين Claude والخطاف (قنوات stdin لبيانات JSON، وقيم مخارج الأخطاء exit codes، وقنوات stdout) - لفهم كيفية التحكم بالعمليات.
• خطوات فحص وتصحيح أخطاء الخطافات وتتبع أسباب توقفها عن العمل.

---

01 ما هو الخطاف (Hook) وبماذا يتميز؟

لنبدأ بالخلاصة: الخطاف (Hook) هو عبارة عن أمر أو نص برمجى يعمل تلقائياً وبشكل حتمي فور رصد حدث معين في المشروع - ولا يعتمد تشغيله على تفكير أو وعي Claude، بل يُنفذ برمجياً وبشكل مضمون. (ويدعم النظام تشغيل نصوص shell، أو إرسال طلبات HTTP، أو استدعاء أدوات الـ MCP، أو تمرير توجيهات لنماذج اللغة).

يعرف التوثيق الرسمي دور الخطافات كالتالي:

الخطافات (Hooks) هي أوامر shell يحددها المستخدم لتُنفذ في لحظات محددة من دورة عمل Claude Code 生命周期中的特定点执行。它们对 Claude Code 的行为提供确定性控制，确保某些操作始终发生，而不是依赖 LLM 选择运行它们。

ركز على كلمتي "تحكم برمجى حتمي" و "تُنفذ دائماً". فهما يمثلان سر كفاءة وقوة الخطافات.

تشبيه: قواعد الأتمتة المحددة في المنازل الذكية (عند حدوث X نفذ Y). ففي المنازل الذكية تقوم بتهيئة قواعد مثل "بمجرد فتح الباب، شغل الإضاءة" أو "بمجرد مغادرتي للمنزل، أغلق كافة الأجهزة". فبمجرد تحقق الشرط، تُنفذ العملية تلقائياً وحتماً دون حاجة لتذكرها. والخطافات تعمل بنفس الطريقة في Claude Code - حيث تحدد "بمجرد رصد هذا الحدث، شغل هذا الأمر"، ليعمل تلقائياً وفي كل مرة.

وهذا يوضح الفارق الجوهري بينها وبين خيارات التوسيع الأخرى: قواعد CLAUDE.md تمثل "توصيات ورغبات" يلتزم بها الوكيل غالباً ولكنه قد ينساها بالخطأ؛ بينما الخطافات تمثل "ضمانات برمجية حتمية" بمجرد رصد الحدث يُنفذ الكود مباشرة ولا علاقة لوعي Claude بالتشغيل. يذكر التوثيق:

القواعد المكتوبة في CLAUDE.md أو المهارات مثل "تجنب تعديل ملف .env نهائياً" تمثل توصيات وليست ضمانات حتمية. بينما استخدام خطاف PreToolUse لمنع تعديل الملف يمثل حظراً برمجياً صارماً وضماناً حتمياً.

وهذا يعالج مشكلة الـ 23 مرة لتنسيق الكود: كتابة "شغل prettier" في CLAUDE.md تمثل توصية قد يغفل عنها؛ وصياغتها كخطاف تضمن تشغيلها مع كل تعديل وبنسبة نجاح 100%.

أمثلة لحالات عملية تستفيد من كفاءة الخطافات:

• "نريد تنسيق الملفات وفحصها برمجياً فور تعديلها" ← لمنع رفع أكواد عشوائية دون فحص.
• "منع تشغيل أوامر الحذف أو تعديل قواعد البيانات الحساسة بشكل مؤكد" ← لحماية المشروع.
• "إرسال تنبيه لسطح المكتب بمجرد انتهاء الوكيل من العمل أو انتظار مدخلاتك" ← لتتمكن من العمل على مهام أخرى دون الحاجة لمراقبة الطرفية باستمرار.

💡 خلاصة سريعة: الخطاف هو عمل مبرمج يعمل تلقائياً عند رصد حدث معين؛ ويتميز بتحويل "التوصيات" لـ "ضمانات حتمية" لمنع الأخطاء وضمان تشغيل العمليات دائماً.

---

02 اللحظات والأحداث المتاحة لتعليق الخطافات

لا تعمل الخطافات في أوقات عشوائية، بل ترتبط بلحظات محددة في دورة عمل الوكيل تسمى الأحداث (events). وتحديد اللحظة المناسبة يمثل الخطوة الأولى لنجاح عمل الخطاف.

تذكر دورة عمل الوكيل (فكر ← تصرف ← لاحظ). تتوزع أحداث الخطافات في مسارات هذه الدورة. ويقسمها التوثيق إلى ثلاثة مستويات بناءً على معدل تكرار التشغيل:

• مرة واحدة لكل جلسة: حدث SessionStart (عند فتح أو استئناف الجلسة) وحدث SessionEnd (عند إغلاق الجلسة).
• مرة واحدة لكل سؤال وحوار: حدث UserPromptSubmit (بمجرد إرسال سؤالك وقبل بدء معالجته) وحدث Stop (عند انتهاء Claude من كتابة إجابته في هذه الجولة).
• عند كل استدعاء للأدوات: حدث PreToolUse (مباشرة قبل تشغيل الأداة) وحدث PostToolUse (مباشرة بعد نجاح تشغيل الأداة).

يوضح الشكل التالي لحظات تشغيل الأحداث الأساسية لتسهيل الفهم:

توضح الصورة مسارات الجلسة: تبدأ بـ SessionStart ثم إرسال السؤال UserPromptSubmit والدخول في دورة معالجة الأدوات - حيث يسبق عمل كل أداة حدث PreToolUse ويتلوها حدث PostToolUse؛ وتنتهي الجولة بـ Stop وتُغلق الجلسة بـ SessionEnd . تختار الحدث المخصص بناءً على اللحظة التي تريد تشغيل الكود فيها.

يدعم النظام عشرات الأحداث الفرعية الأخرى (مثل أحداث ضغط الذاكرة والملفات)، ولكن كخطوة أولى، يكفي التركيز على الأحداث الأربعة الأساسية التالية لتغطية غالبية احتياجاتك:

الحدث	لحظة وموعد التشغيل	استخدامات شائعة
PreToolUse	قبل بدء عمل الأداة مباشرة	لحظر الأوامر الخطيرة وحماية الملفات (يملك صلاحية إيقاف العملية)
PostToolUse	بعد نجاح عمل الأداة مباشرة	لتنسيق الملفات وتشغيل برامج التدقيق بعد التعديل
Stop	عند انتهاء Claude من إجابة الجولة الحالية	لتنبيهك بانتهاء العمل أو فحص التغييرات العامة للمشروع
SessionStart	عند بدء تشغيل أو استئناف الجلسة	لتزويد Claude بسياق ومعلومات إضافية للمشروع (مثل آخر الرفوعات)

تذكر قاعدة التسمية والتأثير: الخطاف المسبوق بـ Pre يعمل قبل العملية ويملك صلاحية إيقافها وحظرها؛ والخطاف المسبوق بـ Post يعمل بعد اكتمال العملية ولا يملك صلاحية إيقافها بل يختص بمعالجة النتائج وكتابة السجلات.

💡 خلاصة سريعة: ترتبط الخطافات بأحداث محددة في دورة الجلسة (لكل جلسة / لكل سؤال / عند استدعاء الأدوات)؛ والتركيز على الأحداث الأربعة (PreToolUse للحظر، و PostToolUse للمعالجة، و Stop لانتهاء الجولة، و SessionStart لبدء الجلسة) كافٍ لغالبية المهام.

---

03 كتابة وتهيئة الخطافات وحصر التشغيل بـ matcher

تُكتب إعدادات الخطافات وتُحفظ داخل ملفات التهيئة settings.json التي شرحناها في المقال 31. ويحدد مستوى حفظ الملف نطاق تأثير هذا الخطاف:

موقع حفظ الملف	نطاق التأثير والعمل	مشاركته مع الفريق
~/.claude/settings.json	كافة المشاريع وجلسات Claude على جهازك الحالي	لا، يخص جهازك فقط
.claude/settings.json (داخل المشروع)	للمشروع الحالي فقط لجميع أعضاء الفريق	نعم، يُرفع ويُشارك عبر git
.claude/settings.local.json (داخل المشروع)	للمشروع الحالي ويخص جهازك فقط	لا، يتم تجاهله بـ gitignore

القاعدة الذهبية للاختيار: الخطافات العامة للفريق (مثل تنسيق الأكواد) تُحفظ في مستوى المشروع .claude/settings.json لتُرفع للمستودع؛ والخطافات الشخصية الخاصة بك (مثل التنبيهات الصوتية) تُحفظ شخصياً في ~/.claude/settings.json.

هيكل كتابة الخطاف في الملف

تأمل هذا المثال العملي لتهيئة خطاف لتنسيق الملفات تلقائياً بمجرد تعديلها (كتابة الملف في مستوى المشروع .claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

يتكون هيكل الخطاف من ثلاثة مستويات متداخلة:

1. اسم الحدث (مثل "PostToolUse"): اللحظة والحدث المطلوب تعليق الخطاف عليه.
2. الـ "matcher" (مثل "Edit|Write"): لتحديد وحصر عمل الخطاف على أدوات معينة (في هذا المثال: يعمل بعد أدوات تعديل وحفظ الملفات Edit و Write فقط، ويتجاهل أدوات التشغيل الأخرى Bash أو القراءة Read).
3. مصفوفة الإجراءات "hooks": تضم الإجراءات المطلوب تنفيذها؛ حيث يحدد "type": "command" تشغيل أمر shell، ويحدد "command" سطر الأمر المطلوب تشغيله.

يُستخدم أمر jq في المثال لاستخراج مسارات الملفات من البيانات الممررة من Claude (يتوفر البرنامج كخيار افتراضي في غالبية الأنظمة، ويمكن تثبيته بـ brew install jq على نظام Mac أو apt-get install jq على نظام Ubuntu). وسنشرح دور هذا البرنامج وقنوات التبادل بالتفصيل في القسم القادم.

حصر تشغيل الخطافات باستخدام matcher

يمثل خيار matcher الأداة الأساسية لتنظيم وتحديد عمل الخطافات ومنع تشغيلها العشوائي المكرر.

تشبيه: بواب الشركة وتصاريح الدخول. فبدون خيار matcher سيعمل الخطاف مثل بواب يقوم بفحص وتسجيل كل زائر يدخل المبنى مما يعطل العمل ويسبب البطء؛ وباستخدام matcher يتم تنظيم الدخول "يتم إيقاف وفحص شركات الشحن والطرود فقط، ويمر بقية الموظفين مباشرة دون تأخير".

يعمل خيار matcher على مطابقة اسم الأداة المستدعاة في أحداث الأدوات (PreToolUse و PostToolUse). وتكتب قيم المطابقة بثلاث طرق:

صياغة matcher	نطاق عمل الخطاف	مثال واقعي للعمل
"Edit|Write"	مطابقة أدوات محددة (باستخدام الرمز | للفصل كأداة اختيار)	يعمل الخطاف بعد تشغيل أداة Edit أو Write فقط
"Bash"	مطابقة أداة واحدة محددة	يعمل الخطاف عند تشغيل أوامر Bash فقط
"" (أو تجاهل كتابته)	مطابقة كافة الأدوات	يعمل الخطاف عند تشغيل أي أداة في الجلسة دون تصفية

تنبيه هام: حروف قيم matcher حساسة لحالة الأحرف (case-sensitive)؛ فكتابة "edit" بالصغير لن تطابق أداة التعديل "Edit" ولن يعمل الخطاف. وهذا الخطأ يمثل سبباً شائعاً لتوقف الخطافات عن العمل.

ويرجى الانتباه لكون بعض الأحداث لا تدعم استخدام خيار matcher لعدم ارتباطها بأدوات معينة (مثل أحداث UserPromptSubmit أو Stop). وإضافة خيار matcher معها سيتم تجاهله تلقائياً ويعمل الخطاف مع كل تشغيل للحدث.

💡 خلاصة سريعة: تُكتب إعدادات الخطافات في ملفات settings.json؛ ويتكون الهيكل من ثلاثة أقسام (الحدث، الفلتر matcher، والإجراء)؛ ويستخدم matcher (الحساس لحالة الأحرف) لتصفية الأدوات ومنع التشغيل العشوائي.

---

04 قنوات الاتصال والتبادل البرمجى بين Claude والخطاف

يمثل فهم قنوات الاتصال مفتاح التعامل الاحترافي مع الخطافات لتصميم عمليات حظر ومعالجة دقيقة.

يتلخص التبادل في ثلاث قنوات اتصال أساسية لنظام التشغيل: يمرر Claude تفاصيل الحدث للخطاف كبيانات JSON عبر قناة stdin ← يقوم الخطاف بمعالجة البيانات ← ويرسل التوجيهات لـ Claude عبر قيم مخارج الأخطاء وقناة stdout.

1. بيانات الحدث الممررة عبر stdin

عند رصد الحدث وتفعيل الخطاف، يمرر Claude تفاصيل وبيانات الحدث لبرنامج الخطاف كبيانات بصيغة JSON عبر قناة المدخلات القياسية (stdin). ففي حدث PreToolUse لأداة Bash مثلاً، يستقبل الخطاف بيانات تشبه التالي:

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

تحتوي البيانات على تفاصيل دقيقة: معلمات الجلسة، ومجلد العمل الحالي، واسم الأداة، والأوامر المطلوب تشغيلها. وفي مثال التنسيق التلقائي، استخدمنا أمر jq -r '.tool_input.file_path' لاستخراج مسار الملف المعدل من حقل file_path وتمريره لبرنامج التنسيق مباشرة.

2. توجيه العمليات باستخدام قيم مخارج الأخطاء (exit codes)

بعد معالجة البيانات، كيف يخبر الخطاف Claude بقرار التشغيل؟ يتبع ذلك القواعد الصارمة التالية لقيم مخارج الأخطاء:

قيمة مخرج الخطأ	القرار البرمجى	النتيجة والتأثير
0	نجاح العملية ومتابعة العمل	تستمر الجلسة في العمل (في أحداث PreToolUse لا تعني الموافقة التلقائية بل يستمر الوكيل في مسار فحص الصلاحيات المعتاد)
2	حظر وإيقاف العملية فورا	يتم إلغاء تشغيل الأداة؛ وتُرسل النصوص المكتوبة في قناة الأخطاء stderr لـ Claude كخلفية ليتعلم منها ويعدل أوامره
قيم أخرى (مثل 1)	حدوث خطأ غير مانع للعمل	تستمر الجلسة في العمل مع إظهار تنبيه بوجود خطأ في الخطاف في الطرفية

التركيز على القيمة exit 2: فهي الوسيلة الوحيدة المعتمدة لإيقاف وحظر تشغيل الأدوات. ويرجى الانتباه لخطأ شائع يقع فيه مطورو الأنظمة:

بالنسبة لغالبية أحداث الخطافات، تمثل القيمة 2 فقط خيار الحظر والإيقاف. ويعامل النظام القيمة 1 كخطأ غير مانع للعمل ويستمر في التشغيل. وإذا كنت تريد حظر الأوامر الخطيرة بشكل صارم، فتأكد من إرسال مخرج الخطأ بقيمة exit 2.

فإذا كتبت نصاً برمجياً للحظر وجعلت مخرج الخطأ بقيمة exit 1 بالخطأ، فسيعرض البرنامج رسالة خطأ ويستمر في تشغيل الأمر الخطير.

تذكر أيضاً: تختص أحداث Pre فقط بالقدرة على حظر وإيقاف العمليات. فإرسال مخرج الخطأ بقيمة 2 في أحداث PostToolUse لن يمنع تشغيل الأداة لكونها قد اكتملت بالفعل، ويقتصر تأثيرها على عرض رسائل الأخطاء لـ Claude.

3. التحكم الدقيق باستخدام مخرجات stdout بصيغة JSON

إذا كنت تريد إجراء خيارات تحكم معقدة وتعديل معلمات التشغيل بدلاً من الاقتصار على خيار الحظر البسيط (نعم أو لا)، يمكنك إرسال مخرج الخطأ بقيمة exit 0 مع طباعة بيانات بصيغة JSON عبر قناة المخرجات القياسية (stdout).

تنبيه هام حول كتابة المخرجات:

استعين بقيم مخارج الأخطاء 2 وقناة stderr للحظر الصارم؛ أو بقناة stdout وبيانات JSON وقيمة الخطأ 0 لخيارات التحكم الدقيق. ولا تخلط بين الطريقتين في نفس الوقت: فعند إرسال قيمة مخرج الخطأ 2، سيتجاهل النظام بيانات JSON المكتوبة في stdout.

من أمثلة بيانات التحكم الدقيق في حدث PreToolUse:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "تحذير: يمنع تشغيل أوامر تعديل الجداول في بيئة الإنتاج"
  }
}

يحدد خيار permissionDecision قرار الصلاحيات للعملية ويقبل أربع قيم: "deny" (منع وتمرير السبب لـ Claude)، و "ask" (سؤال المستخدم وطلب موافقته الصريحة)، و "allow" (السماح المباشر بالتشغيل وتجاوز تنبيهات طلب الموافقة)، و "defer" (لتأجيل التنفيذ للعمليات غير التفاعلية التي تتطلب موافقة خارجية).

وهناك قاعدة أمان صارمة تمنع استغلال هذه الميزة لتجاوز الحماية (المقالات 20 و 21): إرسال قرار السماح "allow" في الخطاف لن يتجاوز قواعد الحظر المعينة في إعدادات المشروع. يذكر التوثيق:

يتيح خيار "allow" تجاوز التنبيهات التفاعلية للمستخدم فقط ولا يلغي قواعد الصلاحيات الصارمة المعينة في ملف الإعدادات. وإذا كان الأمر يتعارض مع قاعدة حظر صريحة، فسيتم إيقافه ومنعه برمجياً بالرغم من خيار السماح المكتوب في الخطاف.

وهذا يضمن عدم قدرة الخطافات الخارجية على تجاوز حمايتك البرمجية المطبقة. وتتميز الخطافات بقوة حظر عالية: حيث ينجح الخطاف في حظر العمليات حتى لو قمت بتشغيل الأداة مع خيار تجاوز الصلاحيات --dangerously-skip-permissions.

أما في أحداث SessionStart فتقبل قناة stdout نصوصاً عادية يتم دمجها مباشرة كخلفية لـ Claude في بداية الجلسة. كتشغيل أمر git log --oneline -5 لإرسال آخر 5 عمليات رفع لـ Claude تلقائياً عند بدء العمل:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git log --oneline -5"
          }
        ]
      }
    ]
  }
}

💡 خلاصة سريعة: قنوات التبادل - يستقبل الخطاف بيانات الحدث كـ JSON عبر stdin، ويوجه العمليات بقيم مخارج الأخطاء (exit 2 للحظر)، ويرسل توجيهات التحكم الدقيق كـ JSON عبر stdout؛ وتذكر أن قواعد الحظر في الإعدادات تفوز دائماً على خيارات السماح في الخطافات.

---

05 ثلاثة أمثلة عملية جاهزة للاستخدام المباشر

نعرض ثلاثة خطافات عملية شائعة وجاهزة للاستخدام في مشاريعك.

المثال الأول: التنسيق التلقائي للملفات بعد التعديل (حدث PostToolUse)

تنسيق تلقائي للملفات البرمجية فور تعديلها. يُنصح بحفظه في مستوى المشروع .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

طريقة العمل: بمجرد قيام Claude بتعديل ملف عبر أداة Edit أو Write ← يستخرج الخطاف مسار الملف المعدل من بيانات JSON ← ويمرره لبرنامج prettier --write ليقوم بتنسيقه تلقائياً. ويمكنك استبدال prettier بـ eslint --fix أو gofmt أو black حسب لغة المشروع.

المثال الثاني: حظر الأوامر الخطيرة (حدث PreToolUse مع نص برمجى)

منع تشغيل الأوامر التي تحتوي على كلمات خطيرة مثل rm -rf. ويُنصح بكتابة المعالجة في ملف مخصص لتسهيل القراءة وتفادي تعقيدات ملف JSON.

الخطوة الأولى: إنشاء ملف النص البرمجى وحفظه في .claude/hooks/block-dangerous.sh:

#!/bin/bash
# block-dangerous.sh: حظر أوامر rm -rf الخطيرة
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "rm -rf"; then
  echo "Blocked: 检测到 rm -rf，已拦截" >&2   # إرسال رسالة التوضيح لقناة الأخطاء لتمريرها لـ Claude
  exit 2                                       # مخرج الخطأ 2 للحظر والإيقاف
fi

exit 0   # السماح بمتابعة الأوامر الأخرى وفق قواعد الصلاحيات المعتادة

الخطوة الثانية: تزويد الملف بصلاحيات التشغيل (ضروري لأنظمة Mac و Linux):

chmod +x .claude/hooks/block-dangerous.sh

الخطوة الثالثة: تسجيل وتفعيل الخطاف في ملف إعدادات المشروع .claude/settings.json وربطه بأداة Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

ركز على استخدام متغير البيئة $CLAUDE_PROJECT_DIR الذي يوفره النظام للإشارة لمجلد المشروع الرئيسي - مما يضمن عمل الخطاف والعثور على النص البرمجى بغض النظر عن المجلد الحالي للتشغيل.

⚠️ تحذير أمني هام (المقال 21): تُنفذ الخطافات بصلاحيات المستخدم الكاملة على جهازك وتملك القدرة على تشغيل وتعديل وحذف الملفات. تأكد من مراجعة وتدقيق الأوامر والنصوص البرمجية جيداً قبل تفعيلها وتجنب نسخ نصوص برمجية مجهولة المصدر لملفات التهيئة.

المثال الثالث: إرسال تنبيه لسطح المكتب عند انتظار مدخلاتك (حدث Notification)

إرسال تنبيه بصري وصوتي لسطح المكتب بمجرد حاجة Claude لموافقتك أو إرساله لتنبيه. ويُنصح بحفظه شخصياً في ~/.claude/settings.json ليعمل في كافة مشاريعك:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code في انتظارك\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

أوامر التنبيه حسب نظام التشغيل:

نظام التشغيل	أمر التنبيه المعتمد
macOS	osascript -e 'display notification "..." with title "Claude Code"'
Linux	notify-send 'Claude Code' '...'
Windows	استدعاء صناديق الحوار بـ PowerShell (راجع التوثيق الرسمي للشفرة البرمجية المعتمدة)

في نظام macOS، إذا لم يظهر التنبيه، تحقق من تفعيل صلاحيات التنبيهات لبرنامج Script Editor في إعدادات النظام.

💡 خلاصة سريعة: أمثلة عملية - التنسيق التلقائي (PostToolUse للملفات)، وحظر الأوامر الخطيرة (PreToolUse مع مخرج الخطأ 2)، والتنبيهات البصرية (Notification حسب نظام التشغيل)؛ واستعين بـ $CLAUDE_PROJECT_DIR لتفادي مشاكل مسارات الملفات.

---

06 تطبيق عملي: كتابة خطاف وتتبع تشغيله

سنقوم الآن بتجربة عملية لكتابة خطاف يقوم بتسجيل وحفظ كافة الأوامر التي يشغلها Claude في ملف سجل مخصص، والتحقق من عمله بنجاح.

يتطلب هذا التطبيق توفر برنامج jq على جهازك (يمكنك تثبيته بـ brew install jq على نظام Mac أو sudo apt-get install jq على نظام Ubuntu).

الخطوة الأولى: إنشاء مجلد تجريبي وملف التهيئة

أنشئ مجلداً جديداً واكتب داخل ملف .claude/settings.json النص التالي (لتسجيل أوامر Bash وحفظها في ملف claude-bash-log.txt في دليلك الرئيسي):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/claude-bash-log.txt"
          }
        ]
      }
    ]
  }
}

طريقة عمل الخطاف: عند نجاح تشغيل أداة Bash ← يستخرج الخطاف قيمة الأمر المستدعى ← ويضيفه للملف النصي claude-bash-log.txt في دليلك الرئيسي.

الخطوة الثانية: تشغيل الجلسة والتحقق من تسجيل الخطاف

شغل Claude Code:

claude

بمجرد الدخول، اكتب:

/hooks

النتيجة المتوقعة: ستظهر واجهة تعرض الخطافات النشطة في الجلسة. تصفح القائمة للوصول لحدث PostToolUse لتشاهد الخطاف مضافاً بالاسم والـ matcher (Bash) ومصدر الحفظ ومحتوى الأمر. ظهوره في القائمة يؤكد تسجيل وتفعيل الخطاف بنجاح.

تذكر أن واجهة /hooks مخصصة للعرض والتدقيق فقط، وأي تعديل على الخطافات يتطلب تحرير ملف التهيئة يدوياً.

الخطوة الثالثة: تشغيل أمر لتفعيل الخطاف

اضغط على Esc للعودة للمحادثة واطلب منه تشغيل أمر بسيط:

أريد معرفة الملفات المتوفرة في المجلد الحالي باستخدام أمر ls

سيقوم Claude باستدعاء أداة Bash لتشغيل أمر ls. وعند نجاح التشغيل، سيتم تفعيل خطاف PostToolUse في الخلفية (ويعمل الخطاف بصمت دون إظهار تنبيهات في واجهة المحادثة).

الخطوة الرابعة: التحقق من كتابة السجل

افتح طرفية جديدة على جهازك واعرض محتويات ملف السجل:

cat ~/claude-bash-log.txt

النتيجة المتوقعة: ستشاهد أمر ls (وأي أوامر Bash أخرى تم تشغيلها في الجلسة) مسجلاً ومكتوباً داخل الملف بنجاح. وهذا يؤكد تفعيل وتشغيل الخطاف تلقائياً في الخلفية.

الخطوة الخامسة: حذف الملفات للتنظيف (اختياري)

يمكنك إلغاء وتفكيك الخطاف بحذف حقل hooks من ملف .claude/settings.json أو بحذف الملف بالكامل؛ وحذف ملف السجل المكتوب:

rm ~/claude-bash-log.txt

بإتمام هذه الخطوات، تكون قد أنشأت وفحصت وتتبعت دورة عمل الخطاف بالكامل بنجاح.

💡 خلاصة سريعة: خطوات التطبيق - كتابة خطاف تسجيل أوامر Bash في إعدادات المشروع ← فحص التسجيل بأمر /hooks ← تشغيل أمر Bash في المحادثة ← التحقق من كتابة السجل في الملف النصي للتأكد من العمل.

---

07 تتبع وتصحيح أخطاء الخطافات

عند توقف الخطافات عن العمل أو ظهور رسائل أخطاء، يمكنك تتبع المشكلة وتصحيحها باتباع القائمة التالية:

المشكلة والظاهرة	السبب المحتمل وطرق التصحيح
الخطاف لا يعمل إطلاقاً عند رصد الحدث	① شغل أمر /hooks وتأكد من تسجيله برمجياً؛ ② حروف matcher حساسة لحالة الأحرف (تأكد من كتابتها Edit أو Write بالصغير والكبير)؛ ③ فحص الحدث (أحداث PreToolUse للحظر، و PostToolUse للمعالجة).
الخطاف لا يظهر في قائمة /hooks	① خطأ في صياغة ملف التهيئة (تجنب كتابة تعليقات أو فواصل زائدة في JSON)； ② حفظ الملف في مجلد خاطئ (تأكد من حفظه باسم .claude/settings.json وتجنب حفظه باسم settings.json مباشرة).
ظهور رسالة خطأ hook error في الطرفية	توقف النص البرمجى للخطاف وإرجاعه مخرج خطأ غير صفرى. جرب تشغيل النص يدوياً للتأكد من سلامته؛ وتأكد من تثبيت الأدوات المستخدمة (مثل jq).
فشل تشغيل النص البرمجى للخطاف	في أنظمة Mac و Linux، تأكد من تزويد الملف بصلاحيات التشغيل باستخدام أمر chmod +x.
فشل حظر الأوامر بالرغم من توقف الخطاف	تأكد من إرجاع مخرج الخطأ بقيمة exit 2 بدلاً من القيمة 1 التي يعاملها النظام كخطأ غير مانع للعمل.

أدوات هامة لتسريع فحص وتصحيح الأخطاء:

أولاً: فحص وتجربة النص البرمجى يدوياً ببيانات افتراضية

قبل تعليق ودمج النص البرمجى مع Claude Code، يمكنك محاكاة عمله وتمرير بيانات افتراضية له عبر الطرفية للتأكد من قيمة مخرج الخطأ:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}' | ./block-dangerous.sh
echo $?   # فحص قيمة مخرج الخطأ: يجب أن تظهر القيمة 2 للحظر الصارم

تساعدك هذه الخطوة في التأكد من سلامة كود النص البرمجى بشكل مستقل وتفادي إضاعة الوقت في الجلسة.

ثانياً: تشغيل الجلسة مع خيار تفعيل سجلات التدقيق والتصحيح

لمعرفة تفاصيل استدعاء الخطافات والأدوات ومخرجات stderr و stdout للخطافات، شغل Claude Code مع خيار --debug (أو اكتب /debug في المحادثة):

claude --debug

سيقوم النظام بكتابة سجلات تفصيلية لعمليات الجلسة في مجلد ~/.claude/debug/. وستجد فيها أسطراً توضح تفاصيل تشغيل الخطافات:

[DEBUG] Executing hooks for PostToolUse:Bash
[DEBUG] Hook command completed with status 0

ولتوقيف وتعطيل كافة الخطافات مؤقتاً لتسهيل فحص الجلسة، يمكنك إضافة خيار "disableAllHooks": true في ملف التهيئة دون حاجة لحذف نصوص الخطافات.

💡 خلاصة سريعة: لتصحيح الأخطاء - تحقق من قائمة /hooks ← تأكد من حالة الأحرف لـ matcher ← جرب تشغيل النص يدوياً للتأكد من مخرج الخطأ بقيمة 2 ← شغل الجلسة بـ --debug لتصفح سجلات التشغيل التفصيلية.

---

08 ملخص

شرحنا في هذا المقال آليات عمل الخطافات (Hooks) وكيفية أتمتة المهام البرمجية وضمان حماية المشاريع.

لنراجع النقاط الأساسية معاً:

الهدف	الأداة والخطوات	نقاط هامة
أتمتة حتمية وحماية برمجية صارمة	تشغيل الخطافات (Hooks)	تحول "التوصيات" لـ "ضمانات حتمية" وتعمل تلقائياً عند رصد أحداث معينة.
تحديد اللحظة المناسبة	اختيار أحداث دورة الجلسة	PreToolUse للحظر، و PostToolUse للمعالجة، و Stop لانتهاء الجولة، و SessionStart لبدء العمل.
تنظيم نطاق التشغيل	استخدام خيار matcher	يحدد الأدوات المشمولة بالخطاف، وتذكر أن حروفه حساسة لحالة الأحرف.
توجيه وقرار العمليات	قيم مخارج الأخطاء (exit codes)	تذكر أن القيمة exit 2 هي الوحيدة المعتمدة لحظر وإيقاف تشغيل الأدوات.
تكامل الصلاحيات والأمان	توافق قواعد الحظر	تعمل الخطافات بصلاحيات المستخدم، ولا تملك صلاحية تجاوز قواعد الحظر الصارمة المعينة في الإعدادات.
فحص وتصحيح الأخطاء	أدوات /hooks و --debug	تصفح الخطافات النشطة بـ /hooks واستعن بـ --debug لتتبع سجلات الأخطاء والتشغيل.

يمكنك الآن: فهم دور الخطافات والفرق بينها وبين ملف CLAUDE.md وقواعد الصلاحيات، وتحديد الأحداث واللحظات المناسبة لتعليق الخطافات في دورة عمل الوكيل، وكتابة وتهيئة خطاف مخصص بالكامل وتصفية الأدوات بـ matcher بدقة، وتوجيه وإيقاف العمليات بقيم مخارج الأخطاء، وفحص وتصحيح أخطاء تشغيل الخطافات بنجاح. هذا يمنحك القدرة على أتمتة وحماية مشاريعك البرمجية وتفادي العمليات المكررة المملة.

تذكر دائماً مراجعة نصوص الخطافات البرمجية بعناية لدواعي الأمان قبل تشغيلها.

---

المقال القادم سنشرح 34 "CLI دليل المراجع: الأوامر والخيارات المتاحة" - حيث سنقوم بجمع وتبسيط كافة أوامر سطر الأوامر (CLI commands) والخيارات والمعلمات المتاحة لـ Claude Code وتصنيفها لتكون مرجعاً سهلاً ودليلاً سريعاً يسهل عليك الرجوع إليه في أي وقت لمعرفة دور وسلوك خيارات التشغيل المختلفة. سنشرح ذلك بالتفصيل في المقال القادم.

---

قراءات موصى بها

• الأمان وحماية الكود: حدود الأمان وصلاحيات التشغيل للأدوات
• الوكلاء الفرعيون (Subagents): تكليف مساعدين خلفيين بالمهام الجانبية
• متغيرات البيئة المعتمدة لتهيئة وتوجيه Claude Code