دليل خطافات Claude Code

خطافات Claude Code (Claude Code Hooks) تُؤتمت سير عمل الذكاء الاصطناعي لديك. يغطي هذا الدليل أحداث PreToolUse وPostToolUse وSessionStart، وسكربتات الصدفة، ورموز الخروج، ومدخلات ومخرجات JSON.

خطافات Claude Code: ماذا ستتعلّم

في هذا الدليل حول خطافات Claude Code، ستمر عبر خطوات عملية تطبيقية مع أمثلة حقيقية. يُشرح هذا الموضوع من الأساس كي تستطيع تطبيقه فورًا في مشاريعك الخاصة.

الهذه الآلية هي سكربتات تعمل تلقائيًا عند وقوع أحداث محددة خلال جلسة Claude Code. تتلقى مدخلات JSON عبر stdin وتُبلّغ عن نتائجها من خلال رموز الخروج ومخرجات JSON. خطافات الأوامر حتمية (deterministic) وقابلة للتركيب والاختبار ومستقلة عن لغة البرمجة. أما هذا المفهوم الموجّهات (prompt) وخطافات الوكلاء (agent) فتستفيد من نموذج Claude في التقييم، ما يجعل سلوكها غير حتمي. تغطي هذه الوحدة نظام الهذه الأدوات والأحداث الرئيسية وكتابة خطافات مفيدة.

مثال تطبيقي: بناء أول خطاف تحقّق

لفهم خطافات Claude Code عمليًّا، ابنِ خطافًا واحدًا من الصفر بدل قراءة الوثائق فقط. ابدأ بمهمة بسيطة: منع Claude من تنفيذ أمر git push إلى الفرع الرئيسي مباشرة.

أنشئ أولًا دليل .claude/hooks/ في جذر مشروعك، ثم اكتب سكربت صدفة باسم block-main-push.sh. يقرأ السكربت مدخلات JSON من stdin، ويستخرج حقل command من كائن tool_input، ويتحقق بتعبير نمطي بسيط مما إذا كان الأمر يحتوي على git push origin main. إن تطابق النمط، يطبع رسالة تفسيرية إلى stderr ويخرج برمز 2 — وهو رمز الخروج الحاجب الذي يوقف Claude فورًا ويعرض الرسالة كخطأ.

بعد كتابة السكربت، سجّله في .claude/settings.json تحت مفتاح hooks، ضمن حدث PreToolUse، بمُطابِق (matcher) يستهدف Bash فقط — كي لا يعمل الخطاف إلا عند استدعاءات أداة الصدفة. اضبط له مهلة قصيرة، عشر ثوانٍ تكفي لفحص نمطي كهذا.

اختبر الخطاف بمعزل قبل أن يلمسه Claude فعليًا: مرّر له عيّنة JSON يدويًا عبر echo '{"tool_name": "Bash", "tool_input": {"command": "git push origin main"}}' | ./block-main-push.sh وتحقّق من رمز الخروج بالأمر echo $?. يجب أن يكون 2. جرّب أيضًا أمرًا غير خطر مثل git status للتأكد من أن الخطاف يسمح به (رمز الخروج 0).

بعد التأكد من عمل السكربت بمعزل، افتح جلسة Claude Code حقيقية واطلب منه تنفيذ git push origin main. سترى الخطاف يحجب الأمر ويعرض رسالتك. شغّل claude --debug إن أردت رؤية سجلّ إطلاق الخطافات بالتفصيل والتأكد من أن matcher وشرط if (إن استخدمته) يعملان كما تتوقع.

من هذه النقطة، وسّع المثال: أضف خطاف PostToolUse لتنسيق الشيفرة تلقائيًا بعد كل كتابة، ثم اجمع الخطافين في نفس ملف الإعداد. هذا هو النمط الذي تُبنى عليه معظم أنظمة الخطافات الإنتاجية — تحقّق قبل التنفيذ، وأتمتة بعده.

بنية الخطافات وإعدادها

تُعدّ الخطافات في ملفات الإعدادات تحت مفتاح hooks. لكل حدث مصفوفة من المُطابِقات (matchers)، ولكل مُطابِق مصفوفة من تعريفات الهذه الميزة. حقل matcher هو نمط تعبير نمطي (regex) يُطابَق مع اسم الأداة — فـ "Bash" يطابق تمامًا، و"Write|Edit" يطابق أيًّا منهما، و"*" يطابق جميع الأدوات، و"mcp__github__.*" يطابق جميع أدوات GitHub MCP.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

تدعم المُطابِقات أيضًا حقلًا شرطيًا if (الإصدار v2.1.85) يستخدم صياغة قواعد الأذونات لتصفية وقت إطلاق الخطاف بدقة أكبر. فبينما يختار matcher الأداة بالاسم، يضيّق if النطاق إلى استدعاءات محددة. هذا مفيد عندما تهتم فقط بمجموعة فرعية من استدعاءات أداة ما — مثل اعتراض أوامر git push دون التشغيل عند كل استدعاء لأداة Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "if": "Bash(git push*)",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/check-push.sh"
          }
        ]
      }
    ]
  }
}

يتبع نمط if الصياغة نفسها التي تتبعها قواعد الأذونات — فـ Bash(git *) يطابق أي أمر git، وWrite(src/**/test_*.py) يطابق كتابة ملفات الاختبار، وهكذا. الخطاف الذي يملك حقل if لا يُطلَق إلا عندما يتطابق كل من matcher وشرط if معًا.

يدعم Claude Code 30 حدثًا للخطافات. أكثرها فائدةً شائعةً هي PreToolUse (التحقق قبل تشغيل أداة، ويمكنه الحجب)، وPostToolUse (المراقبة أو التفاعل بعد التشغيل، ويمكنه إضافة سياق)، وUserPromptSubmit (اعتراض مدخل المستخدم قبل أن يعالجه Claude)، وStop (إجراء فحوص عندما ينتهي Claude من الرد). وتوجد أحداث إضافية لمعالجة الأذونات (PermissionRequest)، والإشعارات، ودورة حياة الوكيل الفرعي (SubagentStart وSubagentStop)، والإخفاقات (PostToolUseFailure وStopFailure)، وتغييرات الإعداد، ومراقبة الملفات (FileChanged)، وضغط السياق (PreCompact وPostCompact)، وإدارة أشجار العمل (worktree).

توسّع عدة أحداث أحدث ما يمكن للهذه الآلية التفاعل معه. فحدث CwdChanged (الإصدار v2.1.83) يُطلَق عند تغيّر دليل العمل، ما يتيح إدارة بيئة تفاعلية شبيهة بـ direnv — مثل التحميل التلقائي لمتغيرات البيئة عند دخول Claude إلى دليل مشروع. وحدث TaskCreated (الإصدار v2.1.84) يُطلَق عند استخدام أداة TaskCreate، بحيث يمكنك تسجيل المهام الجديدة أو التحقق منها فور إنشائها.

يُطلَق حدث WorktreeCreate (الإصدار v2.1.84) عند إنشاء وكيل شجرة عمل، ويدعم type: "http" للإشعارات البعيدة — وهو مفيد لتنبيه الخدمات الخارجية عند بدء عمل متوازٍ. ويُطلَق حدث Elicitation (الإصدار v2.1.76) عندما يطلب خادم MCP مدخلات منظّمة من المستخدم في منتصف المهمة عبر حوار تفاعلي، ويمكنه اعتراض الاستنباط (elicitation) وتعديله قبل عرضه على المستخدم. ويُطلَق حدث ElicitationResult (الإصدار v2.1.76) بعد رد المستخدم على استنباط MCP، ويمكنه اعتراض الرد وتجاوزه قبل إرساله مرة أخرى إلى خادم MCP.

يعمل PreCompact قبيل قيام Claude Code بضغط المحادثة لتحرير السياق، ويمكنه حجب حدوث الضغط — وهو مفيد عندما تريد التقاط لقطة من الحالة، أو تحذير المستخدم، أو رفض ضغط تلقائي قد يُسقط سياقًا حرجًا. ويميّز حقل matcher للحدث ما الذي أطلقه: "manual" عندما يشغّل المستخدم /compact، و"auto" عندما يضغط Claude Code تلقائيًا لأن السياق امتلأ. احجب باستخدام رمز الخروج 2 أو بحمولة قرار JSON:

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          { "type": "command", "command": "./scripts/snapshot-context.sh" }
        ]
      }
    ]
  }
}

أعِد {"decision": "block", "reason": "active refactor in flight"} من السكربت للإبقاء على المحادثة كما هي. ويُطلَق PostCompact بعد نجاح الضغط، وهو الموضع المناسب لإعادة إرفاق الملاحظات، أو إعادة استدعاء مهارة، أو تسجيل ما تم الحفاظ عليه.

تتلقى سكربتات الخطافات بيانات JSON عبر stdin، ولها وصول إلى عدة متغيرات بيئة يضبطها Claude Code تلقائيًا. ويحتوي المتغير CLAUDE_CODE_SESSION_ID على المعرّف الفريد للجلسة — استخدمه لربط سجلات الهذا المفهوم وبيانات القياس (telemetry) الخارجية بجلسة محددة.

يقرأ خطاف Python مدخلات JSON هكذا:

import json, sys, os
data = json.load(sys.stdin)
tool_name = data.get("tool_name", "")
tool_input = data.get("tool_input", {})
session_id = os.environ.get("CLAUDE_CODE_SESSION_ID", "")

رمز الخروج 0 يعني النجاح (حلّل JSON من stdout للحصول على المخرجات). ورمز الخروج 2 يعني خطأ حاجبًا — يتوقف Claude ويعرض رسالة stderr الخاصة بك. وأي رمز خروج آخر هو تحذير غير حاجب يظهر في الوضع المُسهَب (verbose).

تتضمن مدخلات الخطاف كائن effort الذي يحمل مستوى الجهد الفعّال: { "effort": { "level": "medium" } }. المستويات المتاحة هي low وmedium وhigh وxhigh وmax وauto. والقيمة نفسها متاحة أيضًا كمتغير بيئة $CLAUDE_EFFORT داخل سكربتات الخطافات، كما يمكن لأوامر أداة Bash التي تشغّلها الهذه الأدوات قراءتها:

import json, os, sys
data = json.load(sys.stdin)
effort_level = data.get("effort", {}).get("level", "medium")  # from JSON
effort_env = os.environ.get("CLAUDE_EFFORT", "medium")          # from env var

أنواع الخطافات وأنماطها الشائعة

تدعم هذه الميزة الأوامر شكلين. شكل الصدفة (Shell form) (الافتراضي) يمرر سلسلة command إلى الصدفة لتقسيمها إلى وحدات. أما شكل التنفيذ (Exec form) فيضبط مصفوفة args إلى جانب command، فيُولّد العملية مباشرةً دون صدفة — ما يتجنب مشكلات الهروب (escaping) في الصدفة ويكون أكثر أمانًا للأوامر ذات الوسائط المقدَّمة من المستخدم:

{
  "type": "command",
  "command": "node",
  "args": ["./scripts/validate.js", "--strict"]
}

يمكن للخطافات أن تعمل بخمس طرق. هذه الآلية command تنفّذ أوامر صدفة محلية. وخطافات prompt تطلب من Claude تقييم موجّه، عادةً عند Stop أو SubagentStop.

هذا المفهوم agent تُولّد وكيلًا فرعيًا للتحقق متعدد الخطوات. وخطافات http ترسل (POST) حمولة JSON نفسها إلى نقطة نهاية webhook، وهو مفيد للتسجيل البعيد أو خدمات السياسات — تدعم هذه الأدوات HTTP إدراج متغيرات البيئة (interpolation) في الترويسات، ويجب إدراج تلك المتغيرات صراحةً في قائمة السماح. وخطافات mcp_tool تستدعي أداة MCP مباشرةً — وهو مفيد عندما يحتاج الخطاف إلى استدعاء خدمة خارجية (مثل النشر في Slack أو إنشاء قضية في GitHub) دون الخروج إلى الصدفة.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "slack",
            "tool": "send_message",
            "input": { "channel": "#deploys", "text": "Claude finished the task" }
          }
        ]
      }
    ]
  }
}

تتضمن مدخلات خطافي PostToolUse وPostToolUseFailure حقل duration_ms الذي يحمل زمن تنفيذ الأداة بالميلي ثانية (باستثناء مطالبات الأذونات وهذه الميزة PreToolUse). استخدمه لتتبّع الأدوات البطيئة أو لإعداد تنبيهات عندما تتجاوز أداة عتبة معينة.

كما تحمل مدخلات خطافي Stop وSubagentStop الآن مصفوفتي background_tasks وsession_crons. تسرد background_tasks أوامر bash والوكلاء الفرعيين الذين لا يزالون يعملون في الخلفية عند انتهاء الدور؛ وتسرد session_crons المهام المجدولة المرتبطة بالجلسة. يمكن لخطاف بوابة إتمام (completion-gate) استخدام هذه المعطيات لإبقاء Claude يعمل حتى ينتهي كل شيء فعليًا:

import json, sys
data = json.load(sys.stdin)
pending_bg = [t for t in data.get("background_tasks", []) if t.get("status") in ("running", "starting")]
pending_cron = data.get("session_crons", [])
if pending_bg or pending_cron:
    print(json.dumps({
        "decision": "block",
        "reason": f"{len(pending_bg)} background task(s) and {len(pending_cron)} scheduled task(s) still active"
    }))
    sys.exit(0)

تُعدّ background_tasks مفيدة أيضًا في SubagentStop كي لا يعلن وكيل أب أنه انتهى بينما لا تزال مراقِبات bash التي ولّدها تعمل.

أنماط الخطافات الشائعة

التنسيق التلقائي عند حفظ الملف هو أحد أكثر الهذه الآلية فائدةً. خطاف PostToolUse على Write|Edit يشغّل مُنسّقك تلقائيًا، فتكون مخرجات Claude نظيفة دائمًا:

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))")
case "$FILE" in
  *.ts|*.tsx|*.js) prettier --write "$FILE" 2>/dev/null ;;
  *.py) black "$FILE" 2>/dev/null ;;
  *.go) gofmt -w "$FILE" 2>/dev/null ;;
esac
exit 0

يستخدم الفحص الأمني عند الكتابة خطاف PostToolUse مع مخرَج additionalContext لتحذير Claude بشأن أسرار محتملة كتبها للتو:

SECRET_PATTERNS = [
    (r"api[_-]?keys*=s*['"][^'"]+['"]", "Potential hardcoded API key"),
    (r"passwords*=s*['"][^'"]+['"]", "Potential hardcoded password"),
]
# ... check content, then:
output = {"hookSpecificOutput": {"hookEventName": "PostToolUse",
  "additionalContext": f"Security warnings: {'; '.join(warnings)}"}}
print(json.dumps(output))

يمكن لخطافات PostToolUse أيضًا استبدال مخرجات الأداة بالكامل عبر updatedToolOutput. فيرى Claude المحتوى المُستبدَل بدلًا من الأصلي. وهذا يعمل مع جميع الأدوات (وليس MCP فقط) اعتبارًا من الإصدار v2.1.121:

import json, sys
data = json.load(sys.stdin)
original = data.get("tool_result", "")
sanitized = original.replace("/home/user", "~")
output = {"hookSpecificOutput": {"updatedToolOutput": sanitized}}
print(json.dumps(output))

يستخدم حجب الأوامر الخطِرة خطاف PreToolUse مع فحص بتعبير نمطي ورمز الخروج 2:

BLOCKED = [(r"rms+-rfs+/", "Blocking dangerous rm -rf /")]
for pattern, message in BLOCKED:
    if re.search(pattern, command):
        print(message, file=sys.stderr)
        sys.exit(2)

متقدّم: خطافات الموجّهات ونطاق المكوّنات

بالنسبة لحدثي Stop وSubagentStop، يستخدم نوع الخطاف "prompt" نموذج لغة كبير (LLM) لتقييم إتمام المهمة. يقرأ النموذج المحادثة ويعيد قرارًا منظّمًا حول السماح لـ Claude بالتوقف أو متابعة العمل. وهذا قوي للمهام ذات معايير الإتمام الصريحة:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check: 1) Were all files modified? 2) Do tests pass? 3) Is the PR description updated? If anything is missing, explain what.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

يُولّد نوع الخطاف "agent" وكيلًا فرعيًا لإجراء التقييم — وعلى عكس خطافات الموجّهات (أحادية الدور)، يمكن لهذا المفهوم الوكلاء استخدام الأدوات وأداء استدلال متعدد الخطوات. استخدم هذا عندما يتطلب الفحص قراءة ملفات أو تشغيل أوامر.

يمكن أيضًا حصر الخطافات في مهارات ووكلاء أفراد باستخدام حقل hooks في الواجهة الأمامية (frontmatter). خطاف PreToolUse الموجود في frontmatter مهارة لا يُطلَق إلا أثناء تنفيذ تلك المهارة:

---
name: production-deploy
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/production-safety-check.sh"
          once: true
---

تشغّل الراية once: true الخطاف مرة واحدة فقط في كل جلسة بدلًا من تشغيله عند كل استخدام مطابق للأداة. وهذا مفيد لفحوص الإعداد التي لا تحتاج إلى الحدوث سوى مرة واحدة.

بالنسبة لهذه الأدوات PostToolUse، يغذّي خيار الإعداد continueOnBlock سبب رفض الخطاف إلى Claude بوصفه سياقًا ويواصل الدور بدلًا من إنهائه. فبدون continueOnBlock، يُنهي خطاف PostToolUse الحاجب الدور فورًا. ومعه، يرى Claude السبب ويمكنه تعديل نهجه — وهو مفيد لفحوص اللينت أو فرض الأسلوب حيث تريد أن يصحّح Claude نفسه بدلًا من التوقف.

تدعم الخطافات أيضًا حقل terminalSequence في مخرجات JSON الخاصة بها، ما يتيح للهذه الميزة إصدار إشعارات سطح المكتب، وعناوين النوافذ، وأجراس التنبيه دون الحاجة إلى طرفية مُتحكِّمة — وهو مفيد للجلسات بلا واجهة (headless) أو البعيدة.

أمثلة واقعية على الخطافات

المثال 1: تنسيق الشيفرة تلقائيًا بعد الكتابة (خطاف PostToolUse)

تشغيل المُنسّقات تلقائيًا عندما يكتب Claude ملفات:

#!/bin/bash
# Hook: PostToolUse:Write
# Reads the target file path from stdin JSON and runs the appropriate formatter

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"([^"]*)".*//p' | head -1)

if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then
  exit 0
fi

# Detect file type and format accordingly
case "$FILE_PATH" in
  *.js|*.jsx|*.ts|*.tsx)
    prettier --write "$FILE_PATH" 2>/dev/null ;;
  *.py)
    black "$FILE_PATH" 2>/dev/null ;;
  *.go)
    gofmt -w "$FILE_PATH" 2>/dev/null ;;
esac
exit 0

المثال 2: خطاف فاحص أمني (PostToolUse:Write)

افحص الملفات بحثًا عن أسرار مكتوبة بثبات بعد كل عملية كتابة وحذّر باستخدام additionalContext:

#!/bin/bash
# Hook: PostToolUse:Write — Scans for hardcoded secrets, API keys, and credentials

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path".*"(.*)".*//p')

ISSUES=""
# Check for hardcoded passwords
if grep -qiE '"password"[[:space:]]*:[[:space:]]*"[^"]+"' "$FILE_PATH" 2>/dev/null; then
  ISSUES="${ISSUES}- WARNING: Potential hardcoded password detectedn"
fi
# Check for private keys
if grep -q "BEGIN.*PRIVATE KEY" "$FILE_PATH" 2>/dev/null; then
  ISSUES="${ISSUES}- WARNING: Private key detectedn"
fi

# Output non-blocking warning via hookSpecificOutput
if [ -n "$ISSUES" ]; then
  printf '{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": "Security scan found issues:n%s"}}' "$ISSUES"
fi
exit 0

المثال 3: تسجيل جميع أوامر Bash (PostToolUse:Bash)

احتفظ بسجل تدقيق لكل أمر bash ينفّذه Claude:

#!/bin/bash
# Hook: PostToolUse:Bash — Log all bash commands to file

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"([^"]*)".*//p' | head -1)

if [ -z "$COMMAND" ]; then
  exit 0
fi

TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")
LOGFILE="$HOME/.claude/bash-commands.log"
mkdir -p "$(dirname "$LOGFILE")"
echo "[$TIMESTAMP] $COMMAND" >> "$LOGFILE"
exit 0

نصائح احترافية

• اقرأ JSON دائمًا من stdin، لا من وسائط الأمر أبدًا — تتلقى الهذه الآلية حمولتها عبر sys.stdin. استخدم json.load(sys.stdin) وتعامل مع الحقول المفقودة بلطف.
• استخدم $CLAUDE_PROJECT_DIR للمسارات القابلة للنقل — لا تثبّت أبدًا مسارًا مثل /Users/yourname/.... هذا يجعل الخطافات قابلة للمشاركة عبر فريقك من خلال git.
• اختبر الهذا المفهوم بمعزل قبل نشرها — مرّر عينة JSON إلى سكربتك: echo '{"tool_name": "Bash", "tool_input": {"command": "ls"}}' | python3 hook.py. وتحقق من رموز الخروج: 0 = سماح، 2 = حجب.
• اضبط مهلات مناسبة — ينبغي أن تكون لخطافات التحقق مهلات قصيرة (10 ثوانٍ)، بينما يمكن لهذه الأدوات التنسيق أو التحليل أن تسمح بمزيد (30-60 ثانية). الافتراضي 60 ثانية.
• ضع جميع متغيرات الصدفة بين علامتي اقتباس — استخدم "$VAR" لا $VAR، وتجاوز الملفات الحساسة مثل .env و.git/ ومفاتيح SSH في منطق خطافك.

تحدٍّ تطبيقي

ابنِ نظام خطافات يُؤتمت فرض الجودة ويمنحك رؤية آنية لجلساتك.

المهمة: أنشئ خط أنابيب هذه الميزة لما قبل الالتزام والأمان

أعدّ خطافات تتحقق تلقائيًا من جودة الشيفرة، وتبحث عن الأسرار، وتتتبّع استهلاك السياق — كلها تعمل دون تدخل يدوي.

الخطوات

1. أنشئ دليل .claude/hooks/ يحتوي على ثلاثة سكربتات: security-scan.sh وformat-code.sh وcontext-tracker.py.
2. اكتب خطاف PreToolUse لـ Bash يحجب الأوامر الخطِرة مثل rm -rf / وsudo rm باستخدام رمز الخروج 2.
3. اكتب خطاف PostToolUse لـ Write|Edit يشغّل prettier/black/gofmt بناءً على امتداد الملف ويبحث عن الأسرار المكتوبة بثبات (كلمات المرور، مفاتيح API).
4. اكتب زوج هذه الآلية UserPromptSubmit + Stop يتتبّع استهلاك الرموز (tokens) لكل طلب، مع الإبلاغ عن استهلاك السياق التقريبي.
5. اضبط جميع الخطافات في .claude/settings.json بمهلات مناسبة (10 ثوانٍ للتحقق، 30 ثانية للتنسيق).
6. اختبر كل خطاف على حدة بمدخل JSON عيّنة: echo '{"tool_name": "Bash", ...}' | python3 .claude/hooks/validate.py
7. شغّل claude --debug للتحقق من أن سجلات تنفيذ الهذا المفهوم تُظهر إطلاق جميع الخطافات بشكل صحيح.

النتيجة المتوقعة

عندما يكتب Claude ملفًا يحتوي على مفتاح API مكتوب بثبات، يُخرِج الفاحص الأمني تحذيرًا عبر additionalContext. وعندما يحاول Claude تنفيذ أمر bash خطِر، يُحجب قبل التنفيذ. وبعد كل تفاعل، ترى ملخّص استهلاك للسياق مثل “Context: ~45,000 tokens (35% used, ~83,000 remaining)”.

تلميح

تتلقى الهذه الأدوات JSON عبر stdin، لا عبر وسائط سطر الأوامر. استخدم دائمًا json.load(sys.stdin) في Python. استخدم رمز الخروج 0 للمتابعة، ورمز الخروج 2 للحجب (يظهر stderr كخطأ). اختبر الخطافات بـ echo '{...}' | python3 hook.py قبل النشر. استخدم $CLAUDE_PROJECT_DIR للمسارات القابلة للنقل.

اختبار المعرفة

اختبر فهمك لهذه الميزة Claude Code عبر هذه الأسئلة:

1. ما الأنواع الأربعة للخطافات في Claude Code؟
   أ) هذه الآلية Pre وPost وError وFilter | ب) خطافات Command وHTTP وPrompt وAgent | ج) هذا المفهوم Before وAfter وAround وThrough | د) خطافات Input وOutput وFilter وTransform
   الإجابة: ب — هذه الأدوات Command تشغّل سكربتات صدفة، وخطافات HTTP تستدعي نقاط نهاية webhook، وهذه الميزة Prompt تستخدم تقييم نموذج لغة أحادي الدور، وخطافات Agent تستخدم تحققًا قائمًا على وكيل فرعي.
2. يخرج سكربت خطاف برمز 2. ماذا يحدث؟
   أ) يُعرض تحذير غير حاجب | ب) خطأ حاجب — يُعرض stderr كخطأ لـ Claude، ويُمنع استخدام الأداة | ج) يُعاد محاولة الخطاف | د) تنتهي الجلسة
   الإجابة: ب — رمز الخروج 0 = نجاح/متابعة، ورمز الخروج 2 = خطأ حاجب (يُعرض stderr كخطأ)، وأي رمز آخر غير صفري = تحذير غير حاجب.
3. ما حقول JSON التي يتلقاها خطاف PreToolUse عبر stdin؟
   أ) tool_name وtool_output | ب) session_id وtool_name وtool_input وhook_event_name وcwd وغيرها | ج) tool_name فقط | د) سجل المحادثة الكامل
   الإجابة: ب — تتلقى الهذه الآلية كائن JSON عبر stdin يحتوي على session_id وtranscript_path وhook_event_name وtool_name وtool_input وtool_use_id وcwd وpermission_mode.
4. كيف يمكن لخطاف PreToolUse تعديل وسائط مدخلات الأداة قبل التنفيذ؟
   أ) إعادة JSON معدّل عبر stderr | ب) إعادة JSON يحتوي على حقل updatedInput عبر stdout (رمز الخروج 0) | ج) الكتابة إلى ملف مؤقت | د) لا تستطيع الخطافات تعديل المدخلات
   الإجابة: ب — يمكن لخطاف PreToolUse إخراج JSON يحتوي على "updatedInput": {...} عبر stdout (مع رمز الخروج 0) لتعديل وسائط الأداة قبل أن يستخدمها Claude.
5. أي حدث خطاف يدعم CLAUDE_ENV_FILE لاستبقاء متغيرات البيئة داخل الجلسة؟
   أ) PreToolUse | ب) UserPromptSubmit | ج) SessionStart | د) جميع الأحداث
   الإجابة: ج — هذا المفهوم SessionStart وحدها تستطيع استخدام CLAUDE_ENV_FILE لاستبقاء متغيرات البيئة داخل الجلسة.

مصادر إضافية

خطافات Claude Code: أخطاء شائعة يجب تجنّبها

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

• نسيان قراءة JSON من stdin بدلاً من افتراض أنه سيصل عبر وسائط سطر الأوامر — يفشل الخطاف بصمت.
• استخدام رمز خروج غير صحيح (مثلاً 1 بدلاً من 2) للحجب، فيمر الإجراء الخطر دون توقف فعلي.
• تثبيت مسارات مطلقة مثل /Users/yourname/... بدل $CLAUDE_PROJECT_DIR، فيتعطل الخطاف لدى بقية أعضاء الفريق.
• عدم اختبار الخطاف بمعزل (echo '{}' | script) قبل نشره، فتُكتشف الأخطاء فقط أثناء جلسة حقيقية.

خطافات Claude Code تمنحك سير عمل متينًا قابلًا للتكرار. ضع إشارة مرجعية لدليل خطافات Claude Code هذا وعُد إلى الخطوات كلما احتجت إليها.

خطافات Claude Code: أفضل الممارسات

• استخدم هذا المفهوم PreToolUse للتحقق من الإجراءات الخطِرة أو حجبها قبل تشغيلها.
• استخدم خطافات PostToolUse للتنسيق أو فحص اللينت أو التسجيل بعد حدوث تغيير.
• أبقِ سكربتات الهذه الأدوات سريعة؛ فالخطافات البطيئة تجعل كل إجراء يبدو متثاقلًا.
• أعِد JSON منظّمًا من الهذه الميزة عندما تحتاج إلى تمرير قرارات إلى المساعد.
• استخدم رموز الخروج بتعمّد كي يوقف خطاف فاشل سير العمل عندما ينبغي ذلك.

خطافات Claude Code: الأسئلة الشائعة

ما الأحداث التي يمكن للخطافات الإنصات إليها؟

تدعم خطافات Claude Code أحداثًا مثل PreToolUse وPostToolUse وSessionStart.

فيمَ تُستخدم الخطافات؟

التحقق من الإجراءات الخطِرة أو حجبها، والتنسيق، وفحص اللينت، والتسجيل، وأشكال أخرى من الأتمتة حول استخدام الأدوات.

كيف تتواصل الخطافات بالعودة؟

من خلال رموز الخروج ومدخلات ومخرجات JSON المنظّمة.

هل ستبطئني الخطافات؟

فقط إن كانت بطيئة — أبقِ سكربتات الخطافات سريعة كي يبقى كل إجراء سريع الاستجابة.

هل يمكن للخطافات تعديل مدخلات الأداة قبل التنفيذ؟

نعم — يمكن لخطاف PreToolUse إعادة JSON يحتوي حقل updatedInput عبر stdout مع رمز الخروج 0، فيرى Claude المدخل المعدَّل بدل الأصلي.