الخطافات (hooks) في Claude Code: فحص وتنسيق وتنبيهات تلقائية

الخطافات (hooks) في Claude Code أوامر يشغّلها Claude Code تلقائيًا عند نقاط محددة في الجلسة: قبل أن تعمل أداة، وبعد تعديل ملف، وحين ينهي Claude رده أو ينتظر ردك. وتعرّفها في ملف إعدادات، فيحدث التنسيق ومنع التعديلات والتنبيهات في كل مرة، دون أن تعتمد على أن يتذكرها Claude.

ما الخطافات في Claude Code؟#

تصف وثائق Anthropic الخطافات بأنها أوامر shell يحددها المستخدم، وتمنحك تحكمًا حتميًا (deterministic control): تحدث إجراءات معينة دائمًا، بدلًا من أن تعتمد على أن يختار النموذج تشغيلها. فالسطر المكتوب في CLAUDE.md يطلب من Claude أن يفعل شيئًا، أما الخطاف فيعمل سواء تذكّر Claude أم لم يتذكر.

ولكل خطاف نوع من خمسة أنواع:

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

وتقترح الوثائق خطافات prompt وagent للقرارات التي تحتاج إلى تقدير، لا إلى قواعد ثابتة.

على أي أحداث يعمل الخطاف؟#

في Claude Code أكثر من 30 حدثًا للخطافات، وأغلب الإعدادات تستخدم هذه الأحداث:

• `SessionStart`: تبدأ جلسة أو تُستأنف.
• `UserPromptSubmit`: ترسل موجّهًا، قبل أن يعالجه Claude.
• `PreToolUse`: قبل أن يعمل استدعاء أداة، ويستطيع الخطاف أن يمنعه.
• `PermissionRequest`: يحتاج استدعاء أداة إلى إذنك.
• `PostToolUse`: بعد أن ينجح استدعاء أداة.
• `Notification`: يرسل Claude Code إشعارًا.
• `Stop` و`SubagentStop`: ينهي Claude أو وكيل فرعي رده.
• `PreCompact` و`SessionEnd`: قبل ضغط المحادثة (compaction)، وعند انتهاء الجلسة.

ويحدد الحقل matcher متى يعمل الخطاف. ففي أحداث الأدوات يطابق اسم الأداة، مثل Bash أو Edit|Write أو mcp__github__.*، ويفرّق بين الأحرف الكبيرة والصغيرة. وفي SessionStart يطابق طريقة بدء الجلسة، مثل startup أو resume أو clear أو compact. أما UserPromptSubmit وStop فلا يأخذان matcher. وفي أحداث الأدوات يصفّي الحقل if حسب المدخلات أيضًا، فالقيمة "Bash(git *)" تشغّل الخطاف مع أوامر git وحدها.

كيف تُعدّ خطافًا؟#

تُكتب الخطافات تحت القسم hooks في ملف إعدادات، ويحدد الملف أين تعمل:

• `~/.claude/settings.json`: في كل المشاريع على جهازك.
• `.claude/settings.json`: في هذا المشروع. أضفه إلى المستودع ليستخدم فريقك الخطافات نفسها.
• `.claude/settings.local.json`: في هذا المشروع، على جهازك وحده.
• بيانات وكيل فرعي (frontmatter): أثناء عمل الوكيل فقط.
• بيانات مهارة (frontmatter): من لحظة استدعاء المهارة حتى نهاية الجلسة. وإذا ضبطت once: true في الخطاف، أزاله Claude Code بعد أول تشغيل ناجح.

وهذا خطاف يعرض إشعارًا على macOS حين يحتاج Claude Code إلى انتباهك:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

وعلى Linux، اجعل الأمر notify-send 'Claude Code' 'Claude Code needs your attention'. وإذا كان في الملف قسم hooks من قبل، فأضف الحدث داخله. واكتب /hooks لتعرض كل الخطافات المحمّلة ومصدر كل منها، واضبط "disableAllHooks": true لتوقفها كلها. ويمكنك أيضًا أن تطلب من Claude أن يكتب الخطاف لك.

بأي الخطافات تبدأ؟#

نسّق كل ملف يُعدَّل#

يشغّل خطاف PostToolUse هذا أداة Prettier على كل ملف يعدّله Claude أو يكتبه:

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

ولا يلتقط هذا الخطاف الملفات التي يغيّرها أمر Bash. ولهذه الملفات استخدم خطاف FileChanged، أو خطاف Stop يشغّل git status --porcelain.

امنع تعديل الملفات الحساسة#

احفظ هذا السكربت، ثم شغّل chmod +x .claude/hooks/protect-files.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

ثم سجّله ليعمل قبل كل تعديل:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

ويمنع رمز الخروج 2 التعديل، وتصل رسالة Blocked: إلى Claude ملاحظةً يعمل بها.

أعد القواعد بعد ضغط المحادثة#

يلخّص الضغط المحادثة الطويلة، وقد يُسقط بعض تفاصيلها. ويعيدها خطاف SessionStart قيمة matcher فيه هي compact، لأن Claude Code يضيف ما يطبعه الأمر إلى سياق Claude:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'" }
        ]
      }
    ]
  }
}

افحص العمل قبل أن يتوقف Claude#

يسأل خطاف prompt هذا، على الحدث Stop، نموذجًا عما إذا كانت كل المهام قد اكتملت:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

وإذا جاء الرد "ok": false، يواصل Claude العمل ويأخذ السبب تعليمته التالية. ويتجاوز Claude Code خطاف Stop بعد ثماني مرات منع متتالية لا يُستدعى بينها أي أداة، وعلى خطاف command أن يفحص stop_hook_active حتى لا يدخل في حلقة لا تنتهي.

كيف يسمح الخطاف بإجراء أو يمنعه؟#

يستقبل خطاف command الحدث بصيغة JSON عبر stdin، وفيه حقول مثل session_id وcwd وhook_event_name وtool_name وtool_input. ويحدد رمز خروجه ما يحدث بعد ذلك:

• الرمز 0: يمضي الإجراء. وفي SessionStart وUserPromptSubmit ينضم النص المطبوع إلى سياق Claude.
• الرمز 2: يمنع الإجراء، ويعيد نص stderr إلى Claude ملاحظةً. وبعض الأحداث، مثل SessionStart، لا يمكن منعها.
• أي رمز آخر: خطأ لا يمنع شيئًا، ويستمر الإجراء في أغلب الأحداث.

وللتحكم الأدق، اخرج بالرمز 0 واطبع JSON. ففي PreToolUse تأخذ hookSpecificOutput.permissionDecision إحدى القيم "allow" أو "deny" أو "ask" أو "defer"، ويُؤخذ بالجواب الأكثر تشددًا. وتمنع القيمة "deny" الأداة حتى مع --dangerously-skip-permissions، أما "allow" فتتخطى طلب الإذن فقط، وتبقى قواعد المنع والسؤال في إعداداتك سارية.

كيف تشغّل الخطافات بمفتاح من 5abeer؟#

لا تستدعي خطافات command وhttp وmcp_tool أي نموذج، فتعمل بالطريقة نفسها مع أي مفتاح. أما خطافات prompt وagent فترسل طلباتها عبر اتصال الجلسة، فإذا عمل Claude Code بمفتاح من 5abeer خُصمت هذه الطلبات من رصيدك:

1. 1

   اشحن رصيدك#

   ادفع بإحدى طرق الدفع. ويُخصم من هذا الرصيد كل طلب يرسله خطاف prompt أو agent.

2. 2

   أنشئ مفتاحًا لنماذج Claude#

   أنشئ مفتاحًا لمزوّد Anthropic كما في إنشاء مفتاح. وسمّه claude-code ليسهل عليك أن تجد استخدامه.

3. 3

   أضف الإعدادات#

   ضع هذه الإعدادات في ~/.claude/settings.json، وضع مفتاحك مكان النص YOUR_5ABEER_API_KEY. ويبقى القسم hooks في الملف نفسه بجوار القسم env:

   settings.jsonmacOS / LinuxWindows

   انسخ

   {
     "env": {
       "ANTHROPIC_BASE_URL": "https://api.5abeer.ai",
       "ANTHROPIC_AUTH_TOKEN": "YOUR_5ABEER_API_KEY",
       "ANTHROPIC_MODEL": "claude-sonnet-5.5"
     }
   }
   

   ~/.claude/settings.json

4. 4

   جرّب خطافًا#

   شغّل claude، واكتب /hooks لتتأكد أن خطافاتك حُمّلت، ثم اطلب من Claude أن يعدّل ملفًا وراقب الخطاف وهو يعمل.

والحقل model في خطاف prompt اختياري. فإذا لم تذكره، استخدم الخطاف النموذج الذي يشغّله Claude Code للأعمال الخلفية. وإذا فشل خطاف prompt بخطأ في النموذج، فاضبط model على معرّف يقدّمه مفتاحك. وهذه أحدث نماذج Claude في Claude Code، بسعرنا لكل مليون توكن:

ومع باقة من 5abeer تشمل Claude Code، يضبط تطبيق 5abeer AI برنامج Claude Code دون مفتاح، كما في إعداد Claude Code، وتعمل الخطافات ضمن حدود الباقة.

كم تكلّف الخطافات؟#

لا يستهلك تشغيل خطاف command أي توكنات، لكن ما يطبعه في السياق يستهلكها: فالنص الذي يضيفه خطاف SessionStart أو UserPromptSubmit يُرسل من جديد مع الطلبات اللاحقة، فاجعله قصيرًا.

وكل خطاف prompt طلب إلى النموذج، وقد يأخذ خطاف agent حتى 50 دورة يستخدم فيها الأدوات. ومثال ذلك خطاف prompt على الحدث Stop يعمل 200 مرة في اليوم، ويقرأ نحو 3,000 توكن في كل مرة ويرد باختصار، وقد ضبطت فيه model على نموذجنا الافتراضي:

فأعطِ Claude Code مفتاحًا خاصًا به عليه حد إنفاق، كما في تحكّم في كل مفتاح، وراجع استخدامه في تتبّع استخدامك. وسعرنا بجوار السعر الرسمي في صفحة Claude API، ويقارن دليل أرخص طريقة لاستخدام Claude Code بين المفتاح والباقة.

كيف تُبقي الخطافات آمنة؟#

تحذّر Anthropic من أن خطافات command تنفّذ أوامر shell بكامل صلاحيات حسابك على الجهاز. فتعامل مع كل خطاف كأنه سكربت تشغّله بنفسك:

• اختبره يدويًا: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh; echo $?.
• اقرأ خطافات المستودع قبل أن تثق به. فالتشغيل بالخيار -p وعبر SDK يتخطى نافذة الثقة بمجلد العمل، لذلك قبل أن تكتب سكربتًا يشغّل claude -p على كود لم تكتبه، استخدم --bare أو --settings '{"disableAllHooks": true}'.
• ضع المتغيرات بين علامتي تنصيص وافحص المسارات: اكتب "$VAR"، وأشر إلى السكربتات عبر $CLAUDE_PROJECT_DIR، وارفض المسارات التي تحتوي على ...
• أبقِ المفاتيح خارج أوامر الخطافات. فخطاف http لا يقرأ إلا المتغيرات المذكورة في allowedEnvVars.
• استخدم قواعد الأذونات للحدود الصارمة. فالوثائق تصف المرشّح if بأنه يعمل بأفضل جهد (best-effort).

الأخطاء الشائعة وحلولها#

إذا لم يعمل خطاف، فراجع /hooks وحالة الأحرف في matcher، وتأكد أن السكربت قابل للتنفيذ. ومع الخطأ command not found، استخدم مسارًا كاملًا أو $CLAUDE_PROJECT_DIR. ولترى رموز الخروج وناتج stderr، شغّل claude --debug-file /tmp/claude.log أو اكتب /debug.

وتستخدم خطافات prompt وagent مفتاح الجلسة، فقد تظهر لها الأخطاء نفسها التي تظهر في المحادثة الرئيسية:

• INVALID_API_KEY: المفتاح في ~/.claude/settings.json غير صحيح أو حُذف.
• MODEL_UNAVAILABLE: النموذج المذكور في الحقل model لخطاف غير متاح الآن. أعد المحاولة، أو اختر نموذجًا آخر يقدّمه مفتاحك.
• INSUFFICIENT_BALANCE: الرصيد لا يكفي لهذا الطلب. اشحن رصيدك ثم أعد المحاولة.
• API_KEY_QUOTA_EXHAUSTED: وصل المفتاح إلى حد إنفاقه، وكثيرًا ما يحدث ذلك حين يعمل خطاف prompt في كل دورة.

وكل رمز مشروح في الأخطاء وحلولها.

أسئلة شائعة#

هل يستطيع خطاف أن يوافق على طلبات الإذن بدلًا مني؟#

نعم. فخطاف PermissionRequest الذي يعيد "behavior": "allow" يجيب عنك. ومثال الوثائق لا يطابق إلا ExitPlanMode، فلا تنتظر الخطة المكتملة موافقتك، وتبقى طلبات الإذن الأخرى كما هي.

هل تعمل الخطافات على Windows؟#

نعم. تعمل خطافات command في Git Bash، أو في PowerShell إذا لم يكن Git Bash مثبّتًا. واضبط "shell": "powershell" لتستخدم PowerShell دائمًا.

هل يمكن أن تكون للوكيل الفرعي خطافات خاصة به؟#

نعم. فالخطافات المكتوبة في بيانات الوكيل الفرعي لا تعمل إلا أثناء عمله، وتعمل خطافات SubagentStart وSubagentStop مع كل وكيل فرعي. راجع الوكلاء الفرعيون في Claude Code.

هل يستطيع خطاف أن يلغي تعديلًا؟#

لا. يعمل PostToolUse بعد أن تنتهي الأداة. ولتوقف التعديل، امنعه في PreToolUse.

هل تعمل الخطافات على باقة من 5abeer؟#

نعم، إذا كانت باقتك تشمل Claude Code. وتُحسب طلبات خطافات prompt وagent ضمن حدود الباقة. راجع ما الذي تشغّله كل باقة وصفحة الأسعار.

هل 5abeer جزء من Anthropic؟#

لا. 5abeer خدمة مستقلة لا تتبع Anthropic.

المصادر#

راجعناها في 2026-11-01:

• وثائق Claude Code: Automate actions with hooks
• وثائق Claude Code: Hooks reference
• وثائق Claude Code: Model configuration

ابدأ#

احصل على تطبيق 5abeer AI لتشغّل Claude Code وخطافاته على باقتك، أو أنشئ مفتاحًا لنماذج Claude واتبع الخطوات السابقة.