ما هي خطافات Claude Code؟ تشغيل أوامر الشِل بشكل حتمي

"أريد تنسيقًا تلقائيًا بعد كل تعديل." "لا تدع أي شيء يعيد كتابة .env أو package-lock.json أبدًا." "أوقف أوامر rm -rf الخطيرة." إن طريقة جعل قواعد "يجب أن يحدث هذا دائمًا" حقيقية — دون الاعتماد على أهواء الذكاء الاصطناعي — هي خطافات Claude Code. الخطاف هو أمر شِل (shell) يُنفَّذ تلقائيًا عند نقاط محددة في دورة حياة Claude Code، كما أن الخطافات تُعد لبنة أساسية في الإضافات (plugins).

تعرض هذه المقالة، استنادًا إلى التوثيق الرسمي، ما هي الخطافات، وقائمة الأحداث، وكيفية إعدادها، وعقد الإدخال/الإخراج، وحالات الاستخدام، والأمان. ثلاث نقاط مسبقًا. ① الخطاف هو "منطق حتمي يُنفّذه إطار التشغيل (Claude Code نفسه)" — يُطلَق بشكل مؤكد، دون انتظار أن "يقرر" النموذج تنفيذه. ② تكتب الخطافات في settings.json على هيئة اسم الحدث ← matcher ← command. ③ أحداث مثل PreToolUse يمكنها "الحظر" عبر رمز الخروج 2 أو عبر JSON — موقِفةً تعديلات الملفات المحمية أو الأوامر الخطيرة.

1. ما هي خطافات Claude Code؟

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

الجوهر هو الحتمية. اطلب من Claude "تشغيل الاختبارات" وما إذا كان سيفعل ذلك يعتمد على "حكمه". لكن مع الخطاف، يُنفّذه إطار التشغيل دائمًا — دون أن يتدخل أي هوى. إلى جانب الأوامر (command)، باتت توجد الآن أيضًا أنواع معالِجات مثل HTTP، وأدوات MCP، ومطالبات نموذج اللغة، والتحقق عبر وكيل فرعي — لكن للبدء، يكفي اعتبار الخطافات "آليةً لتشغيل أمر شِل دائمًا عند النقاط الرئيسية".

2. أحداث الخطافات

يمثّل الحدث "أين في دورة الحياة يُطلَق". ابدأ بالتسعة الكلاسيكية ("يمكنه الحظر" = يمكنك إيقاف ذلك الإجراء عبر رمز الخروج 2 أو عبر JSON).

يضيف توثيق 2026 أحداثًا أكثر بكثير — PermissionRequest، PostToolUseFailure، ConfigChange، FileChanged، WorktreeCreate، وغيرها. لكن أسماء الأحداث قد تُضاف أو تتغير بين الإصدارات، لذا ترتكز هذه المقالة على التسعة الكلاسيكية المستقرة بالإضافة إلى العقد في القسم التالي (راجع التوثيق الرسمي للقائمة الكاملة الحالية).

3. كيفية إعداد الخطافات

تكتب الخطافات تحت مفتاح "hooks" في settings.json. يحدد الموقع النطاق: المستخدم (~/.claude/settings.json) / المشروع (.claude/settings.json، قابل للمشاركة عبر git) / المحلي (.claude/settings.local.json) / السياسة المُدارة (المؤسسة) / ملف hooks/hooks.json الخاص بإضافة. يبدو شكل JSON كما يلي.

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

البنية هي "hooks ← اسم الحدث ← مصفوفة من { matcher, hooks:[...] } ← كل خطاف يحتوي على type + command." يحدد matcher اسم الأداة المستهدفة: "*" (أو حذفه) يطابق الكل، و"Edit|Write" قائمة مفصولة بـ|، والأحرف الأخرى تعبير نمطي (regex) (مثل mcp__memory__.*). وهو حساس لحالة الأحرف. يسرد الأمر /hooks الخطافات المُعدّة لكنه للقراءة فقط — للإضافة أو التغيير، عدّل settings.json مباشرةً. عطّل الكل عبر "disableAllHooks": true.

4. عقد الإدخال/الإخراج

يتلقى الخطاف JSON على الإدخال القياسي (stdin) ويُرجع نتيجته عبر رمز الخروج أو JSON على الإخراج القياسي.

الإدخال (stdin): تشمل الحقول المشتركة session_id، وtranscript_path، وcwd، وhook_event_name. تضيف أحداث الأدوات tool_name وtool_input (مثل {"command":"rm -rf /tmp/build"})؛ ويضيف UserPromptSubmit الحقل prompt. رموز الخروج: 0 = نجاح (بالنسبة لبعض الأحداث، يُضاف stdout إلى السياق — مع أن الخروج 0 في PreToolUse ليس "موافقة"؛ إذ يظل تدفق الأذونات المعتاد ساريًا)، 2 = حظر (يُمرَّر stderr إلى Claude كمادة للتعديل، ويُتجاهَل إخراج JSON).

# مثال: "deny" من PreToolUse عبر إخراج JSON مُهيكَل (يُطبَع على stdout)
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}
# الحقول المشتركة: continue (false = إيقاف كامل) / decision:"block"+reason /
#                additionalContext (يُلحَق لأجل Claude) / updatedInput (إعادة كتابة الوسائط)

المبدأ الأهم: "يمكن للخطافات تشديد القيود لا تخفيفها." إن إرجاع allow يتخطى المطالبة فقط؛ أما قواعد deny في أي نطاق (بما في ذلك الإعدادات المُدارة) فلها الأسبقية دائمًا. ويُحظر PreToolUse deny حتى في وضع bypassPermissions / ‎--dangerously-skip-permissions. لمزيد عن نموذج الأذونات الأشمل، راجع أوضاع الأذونات والأمان.

5. أمثلة على حالات الاستخدام

الكلاسيكيات الرسمية، مقترنةً بإعدادها.

6. الأمان

الخطافات قوية، لكنها تشغّل أوامر شِل عشوائية تلقائيًا بصلاحياتك — لا تستهن بهذا.

عمليًا: تحقّق دائمًا من المدخلات واقتبسها بين علامتي تنصيص (استخرجها بـjq؛ فالمتغيرات غير المقتبسة قد تتحول إلى وسائط إضافية أو صياغة شِل)، استخدم المسارات المطلقة و${CLAUDE_PROJECT_DIR}، ولا تمسّ الملفات الحساسة مثل .env أو .ssh، ولا تستخدم eval أبدًا على مخرَج الأداة. تُشغَّل الخطافات دون طرفية متحكِّمة (لا /dev/tty). في المؤسسات، يمكن للمسؤولين تقييد الخطافات عبر allowManagedHooksOnly.

الخلاصة

خطافات Claude Code هي أوامر شِل يعرّفها المستخدم وتُنفَّذ تلقائيًا عند نقاط دورة الحياة الرئيسية، فتجعل قاعدة "يجب أن يحدث هذا دائمًا" حقيقية وحتمية دون الاعتماد على حكم النموذج. الأحداث الكلاسيكية تسعة: SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Notification / Stop / SubagentStop / SessionEnd / PreCompact (PreToolUse وغيره يمكنه الحظر — موقِفًا تعديلات الملفات المحمية أو الأوامر الخطيرة). تُعِدّها في settings.json تحت "hooks" على هيئة الحدث ← matcher ← type + command.

الإدخال/الإخراج هو JSON على stdin، ورمز الخروج 0 (نجاح) / 2 (حظر)، أو JSON مُهيكَل على stdout. المبدأ: "يمكنك التشديد لا التخفيف للقيود" (deny تفوز دائمًا). حالات الاستخدام الكلاسيكية: التنسيق التلقائي، وحماية الملفات، وإيقاف الأوامر الخطيرة، وإعادة حقن السياق، والتدقيق، والاختبار قبل التوقف. لكن لأنها تشغّل شفرة عشوائية، كن صارمًا في الثقة بالخطافات الآمنة فقط والتحقق من المدخلات واقتباسها، وافهم أن الإعداد يُلتقَط عند بدء التشغيل. ذات صلة: الإضافات، وMCP، وأخطاء Claude Code.

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

س. ما الغرض من الخطافات؟
ج. إنها تؤتمت بشكل حتمي ما "يجب أن يحدث دائمًا". أمور مثل "تنسيق بعد التعديلات"، و"عدم السماح أبدًا بإعادة كتابة الملفات المحمية"، و"إيقاف rm -rf الخطير"، و"اجتياز الاختبارات قبل التوقف" يُنفّذها إطار التشغيل بشكل مؤكد، دون الاعتماد على حكم الذكاء الاصطناعي. الخطاف هو أمر شِل يُنفَّذ عند نقاط دورة الحياة الرئيسية، ويُعدّ في settings.json.

س. ما الأحداث (التوقيتات) المتاحة؟
ج. الكلاسيكيات تسعة: SessionStart (البدء)، وUserPromptSubmit (عند الإرسال)، وPreToolUse (قُبيل أداة)، وPostToolUse (بعد أداة)، وNotification، وStop (انتهاء الرد)، وSubagentStop، وSessionEnd (الإنهاء)، وPreCompact (قبل الضغط). من بين هذه، PreToolUse، وUserPromptSubmit، وStop، وPreCompact، وغيرها يمكنها الحظر وإيقاف الإجراء. يضيف إصدار 2026 أحداثًا أكثر بكثير، لكن الأسماء قد تتغير بين الإصدارات، لذا راجع التوثيق الرسمي للأحدث.

س. هل يمكنني إيقاف تعديلات الملفات المحمية أو الأوامر الخطيرة؟
ج. نعم — عبر خطاف PreToolUse. يفحص سكربت مسار الملف أو الأمر في tool_input، وإذا طابق .env، أو rm -rf، إلخ، أرجع رمز الخروج 2 (أو JSON مع permissionDecision:"deny") لحظره. والأهم أن deny لها الأسبقية دائمًا وتوقف الإجراء حتى في وضع bypassPermissions. تعمل الخطافات فقط في اتجاه "تشديد القيود".

س. غيّرت إعدادي لكنه لا يسري.
ج. هذا بحسب التصميم (ميزة أمان). يُلتقَط إعداد الخطاف كلقطة عند بدء الجلسة، لذا فإن التغييرات في منتصف الجلسة لا تُطبَّق. وهذا يمنع أي طلب خبيث أو مخرَج أداة من إعادة كتابة إعداد خطافك بصمت. ابدأ جلسة جديدة لتطبيقه. لاحظ أن /hooks قائمة للقراءة فقط؛ أضِف الخطافات أو غيّرها بتعديل settings.json مباشرةً.

س. هل الخطافات آمنة؟
ج. ليست بلا شروط. تشغّل الخطافات أوامر شِل عشوائية بصلاحياتك، ولهذا يقول التوثيق "استخدمها على مسؤوليتك الخاصة". لا تُعِدّ سوى الخطافات التي تثق بها، وتحقّق من المدخلات واقتبسها بـjq، واستخدم المسارات المطلقة ولا تمسّ .env / .ssh، ولا تستخدم eval أبدًا على مخرَج الأداة. في المؤسسات، يمكن للمسؤولين تقييد الخطافات عبر allowManagedHooksOnly.