شرح hooks في Claude Code: كل حدث والغرض منه

01بنية الـ hook

يتكوّن إعداد الـ hook من ثلاثة مستويات:

1. حدث الـ hook، مثل PreToolUse أو Stop.
2. مجموعة matcher، وهي التي تحدد متى يُفعَّل، مثل "لأداة Bash فقط".
3. معالج hook واحد أو أكثر، وهو ما يُشغَّل فعليًا.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

يشغّل هذا المثال سكربت lint بعد أن يكتب Claude ملفًا أو يعدّله. لإضافة حدث ثانٍ، أضف مفتاحًا مجاورًا داخل كائن hooks نفسه.

02أين توجد الـ hooks

تتراكم الـ hooks القادمة من ملفات مختلفة ولا يستبدل بعضها بعضًا. اكتب /hooks في Claude Code لعرض كل الـ hooks النشطة ومصدر كل منها.

في الجلسة التفاعلية، يؤجّل Claude Code تشغيل الـ hooks، حتى الخاصة بك، إلى أن توافق على نافذة الثقة بمساحة العمل لهذا المجلد.

03أنواع المعالجات

معظم الـ hooks من النوع "type": "command"، الذي يشغّل أمر shell. وهناك أربعة أنواع أخرى:

• http: يرسل JSON الحدث بطلب POST إلى URL ويقرأ نص الاستجابة.
• mcp_tool: يستدعي أداة على خادم MCP قمت بإعداده.
• prompt: يطرح سؤالًا من دورة واحدة على نموذج Claude ويقرأ قرارًا بصيغة JSON.
• agent: يشغّل subagent يمكنه قراءة الملفات قبل اتخاذ القرار (تجريبي).

تعمل hooks الأوامر بكامل صلاحيات المستخدم، عبر sh -c على macOS وLinux، وعبر Git Bash (أو PowerShell) على Windows. أضف "async": true لتشغيل hook في الخلفية؛ لكنه حينها لن يستطيع اتخاذ قرارات.

04الـ Matchers

يحدد matcher أيّ مرات وقوع الحدث تشغّل الـ hook. وما يُطابَق عليه يعتمد على الحدث: اسم الأداة في أحداث الأدوات، ونوع الإشعار في Notification، وطريقة بدء الجلسة في SessionStart، وهكذا.

• القيمة "*" أو "" أو غياب matcher تمامًا تطابق كل شيء.
• الأحرف والأرقام و_ و- والمسافات و| و, تُعامَل كأسماء مطابقة تمامًا. فمثلًا Edit|Write يطابق أيًّا من الأداتين.
• أي شيء آخر يُعامَل كتعبير نمطي (regex) في JavaScript، لذا فإن mcp__memory__.* يطابق كل أدوات خادم MCP واحد.

الـ Matchers حساسة لحالة الأحرف. بعض الأحداث، ومنها Stop وUserPromptSubmit، تتجاهل الـ matchers. وفي أحداث الأدوات، يمكن لحقل if يحتوي قاعدة صلاحيات مثل "Bash(git *)" أن يضيّق نطاق معالج واحد أكثر.

05المدخلات: ما يتلقاه الـ hook

يتلقى كل hook بيانات JSON عبر stdin تتضمن بعض الحقول المشتركة، منها session_id وtranscript_path وcwd وhook_event_name، إضافةً إلى حقول خاصة بالحدث. فعلى سبيل المثال، يتلقى hook من نوع PreToolUse لاستدعاء Bash أيضًا tool_name وtool_input.command. اقرأها باستخدام jq أو أي محلل JSON:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06المخرجات: رموز الخروج وJSON

يتواصل الـ hook مع Claude Code بإحدى طريقتين.

رموز الخروج. الرمز 0 يعني النجاح. والرمز 2 خطأ مانع: في الأحداث التي تقبل المنع يتوقف الإجراء ويصبح محتوى stderr هو السبب. أما أي رمز آخر، بما فيه 1 المعتاد، فهو خطأ غير مانع، أي يستمر الإجراء وتظهر لك رسالة بخطأ في الـ hook. إذا كان الـ hook مخصصًا لفرض قاعدة، فاخرج بالرمز 2 وليس 1.

JSON على stdout. للتحكم بدقة أكبر، اخرج بالرمز 0 واطبع كائن JSON واحدًا. بعض الحقول تعمل في كل الأحداث، مثل continue: false لإيقاف Claude كليًا. وبعضها خاص بكل حدث: يستخدم Stop الحقل decision: "block" مع reason، بينما يضع PreToolUse وPermissionRequest قرارهما داخل hookSpecificOutput. لا تطبع أي شيء آخر على stdout: فسطر عابر من ملف إعدادات الـ shell يمنع Claude Code من قراءة الـ JSON.

07جميع أحداث الـ hook

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

08الأحداث المهمة للإشعارات

تغطي أربعة أحداث كل ما يريد الناس تقريبًا أن يُنبَّهوا إليه:

• Stop لحالة "انتهى Claude". راجع دليل Stop hook.
• Notification لحالة "Claude بانتظارك"، بأنواع مثل permission_prompt وidle_prompt. راجع دليل Notification hook.
• PermissionRequest لتُنبَّه أو تردّ فور الحاجة إلى إذن. راجع دليل PermissionRequest.
• PreToolUse على الأداة AskUserQuestion، لرؤية أسئلة Claude متعددة الخيارات أو الإجابة عنها. راجع الإجابة عن الأسئلة من هاتفك.

للحصول على إعداد جاهز لسطح المكتب، ابدأ بـكيفية تلقي إشعار عند انتهاء Claude Code.

09أين يأتي دور Claude Code Notifier

Claude Code Notifier مبني بالكامل على هذه الـ hooks. أداة سطر الأوامر المجانية الخاصة به، ccn، تعمل على Mac وWindows وLinux. يضيف تثبيتها سبعة إدخالات hook إلى ~/.claude/settings.json، يشغّل كلٌّ منها ccn hook، ويحتفظ بنسخة احتياطية من الملف لمرة واحدة. يعمل ccn بضعة أجزاء من الثانية لكل حدث ثم يخرج، فلا يبقى شيء قيد التشغيل.

بمفرده يعرض إشعارات سطح المكتب. وعند ربط تطبيق iPhone أو Android، تنقل الـ hooks نفسها ردودك: السماح بإذن أو رفضه، أو الإجابة عن سؤال، أو إرسال التعليمة التالية بعد توقف Claude. وهو مستقل وليس من إنتاج Anthropic. إن كنت تحتاج فقط إلى سجل أو خطوة lint، فبضعة أسطر من كتابتك أبسط. التفاصيل في صفحة ccn.

10الأسئلة الشائعة