SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor

شرح Claude Code hooks: الأحداث وحالة الخروج 2

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

ما هو Claude Code hook

إنّ Claude Code hooks هي أوامر shell يشغّلها Claude Code تلقائياً عند نقاط محددة من دورة حياته. وهذا هو الفرق الكامل بين hook وملف القواعد. التعليمات الموجودة في CLAUDE.md هي إرشاد، ويوازنها النموذج مع كل ما هو موجود في سياقه. أمّا hook فهو كود، ويُشغَّل سواء وافق النموذج أم لا. إذا استمر وكيلك في تخطي formatter الذي أخبرته عنه مرتين، فلا تحتاج إلى تعليمات أكثر صرامة. بل تحتاج إلى hook.

الآلية بسيطة. تسجّل أمراً في ملف إعدادات تحت اسم حدث. عند وقوع الحدث، يشغّل Claude Code أمرك ويكتب بيانات الحدث إلى الإدخال القياسي (stdin) بصيغة JSON (ترميز كائنات JavaScript). يقرأ أمرك هذه البيانات، وينفّذ عمله، ثم يعيد رمز خروج. يؤدي الخروج بالرمز 2 من hook من نوع PreToolUse إلى إلغاء استدعاء الأداة قبل تشغيلها. ويعيد Claude Code إلى النموذج كل ما كتبه السكربت في الخطأ القياسي (stderr) باعتباره السبب، ما لم يطبع hook أيضاً JSON يتضمن قراراً بالحظر؛ عندها تكون علّة ذلك القرار هي المعتمدة.

تأتي أسماء الأحداث وحقول البيانات الواردة هنا من مرجع hooks في Claude Code، وقد جرى التحقق منها في November 12, 2026. تتغير هذه الواجهة بسرعة، لذلك راجع المرجع الخاص بإصدارك قبل نسخ JSON من أي تدوينة، بما في ذلك هذه التدوينة. اطبع نسختك باستخدام claude --version.

موضع إعدادات الـhook

الـhook عبارة عن كتلة JSON في ملف إعدادات. يمكن أن تحتوي عليه 6 مواضع، ويحدد نطاق الملف نطاق الـhook.

  • ~/.claude/settings.json: كل مشروع على جهازك، وليس على أجهزة الآخرين.
  • .claude/settings.json: مشروع واحد، ويُحفَظ في المستودع، لذلك يحصل عليه كل من ينسخ المستودع.
  • .claude/settings.local.json: مشروع واحد، وعلى جهازك فقط.
  • إعدادات السياسة المُدارة: على مستوى المؤسسة، ويحددها مسؤول.
  • hooks/hooks.json داخل plugin، وتبقى فعالة ما دام plugin مفعّلاً.
  • Frontmatter الخاص بـskill أو subagent. تبقى hooks الخاصة بـskill فعالة حتى نهاية الجلسة بعد استدعاء skill، بينما تبقى hooks الخاصة بـsubagent فعالة أثناء تشغيل ذلك subagent.

تُدمج إدخالات الـhook من هذه الملفات بدلاً من أن تستبدل بعضها بعضاً. يضيف ملف إعدادات المشروع hooks الخاصة به إلى hooks الموجودة في إعدادات المستخدم، ولا يستبدلها. لذلك يمكن أن يحتوي حدث واحد على عدة hooks من ملفات متعددة. يؤدي ضبط "disableAllHooks": true إلى إيقافها، مع استثناء واحد: تستمر hooks القادمة من إعدادات السياسة المُدارة في العمل ما لم يُطبَّق هذا الإعداد أيضاً في الإعدادات المُدارة.

شغّل /hooks داخل جلسة لعرض كل hook مسجّل حالياً، مجمّعة حسب الحدث، مع ملف المصدر وmatcher الخاص بكل منها. هذه القائمة للقراءة فقط، لذلك تغيّر hook بتحرير ملف الإعدادات. يلتقط file watcher التعديل عادةً من دون الحاجة إلى إعادة التشغيل.

أحداث خطافات Claude Code المتاحة

يسرد مرجع الخطافات ثلاثة وثلاثين حدثاً، بدءاً من SessionStart ووصولاً إلى SessionEnd، وتشمل ضغط السياق والوكلاء الفرعيين وworktrees وملفات الإعداد. يحتاج عمل الخادم إلى عدد محدود منها.

  • PreToolUse: قبل تنفيذ استدعاء أداة، باستثناء EndConversation. هذا هو الحدث الذي يمكنه حظر التنفيذ.
  • PostToolUse: بعد نجاح استدعاء أداة، باستثناء EndConversation. يُطلِق PostToolUseFailure الحدث عند فشل الاستدعاء بدلاً من ذلك، لذلك يحتاج الخطاف الذي يجب أن يرى كل نتيجة إلى كليهما.
  • PermissionRequest: عندما يحتاج استدعاء أداة إلى قرار صلاحية، أي في اللحظة التي يظهر فيها طلب الموافقة.
  • UserPromptSubmit: عند إرسال prompt، وقبل أن يعالجه Claude. تُضاف مخرجات stdout النصية العادية من الخطاف الناجح إلى سياق النموذج.
  • SessionStart وSessionEnd: عند كل نهاية لجلسة. يُطلِق SessionStart الحدث أيضاً بعد ضغط السياق، باستخدام قيمة المطابقة compact.
  • Stop: عندما ينتهي Claude من الرد. يحدث ذلك مرة واحدة لكل دور، وليس مرة واحدة لكل مهمة مكتملة.

في الأحداث التي تدعم المطابقات، يمكن أن تحمل المجموعة قيمة matcher تحدد الحالات التي تشغّل الخطاف. وفي أحداث الأدوات، تصفّي هذه القيمة الأحداث حسب اسم الأداة، ولذلك يُطلِق "Edit|Write" الخطاف عند تعديل الملفات فقط، ولا يطِلقه في أي حالة أخرى. المطابقات حساسة لحالة الأحرف. تُطلِق المطابقة الفارغة الخطاف عند كل حالة. تُسمّى الأدوات من خادم MCP (بروتوكول سياق النموذج) باستخدام mcp__<server>__<tool>، لذلك تلتقط مطابقة بقيمة "mcp__github__.*" أدوات خادم واحد وتستبعد الأدوات الأخرى.

تحتوي خطافات Stop على فخ يجب معرفته قبل كتابة أحدها. يعيد خطاف Stop الذي يحظر التنفيذ النموذج إلى العمل، ويتجاوز Claude Code افتراضياً الحظر التالي بعد ثماني مواصلات متتالية، ويُعاد ضبط العداد كلما استدعى Claude أداة. اقرأ الحقل stop_hook_active من مدخلات الخطاف، واخرج بالرمز 0 عندما تكون قيمته true، وإلا فقد يستمر الخطاف في إعادة Claude إلى العمل.

ما الذي يستلمه hook عبر stdin

عندما يستعد Claude لتشغيل npm test، يقرأ hook من نوع PreToolUse على Bash البيانات التالية عبر stdin:

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

تتضمن حقول الإدخال الشائعة session_id وcwd وtranscript_path وhook_event_name؛ ولا يُرسَل permission_mode مع كل حدث. وتضيف أحداث الأداة tool_name وtool_input وtool_use_id. أما الأحداث الأخرى فتحمل حقولها الخاصة: يحصل UserPromptSubmit على النص prompt، ويحصل SessionStart على source من startup أو resume أو clear أو compact أو fork.

يُعد jq الطريقة المعتادة لقراءة هذه البيانات داخل shell script، لكنه غير متوفر في صورة خادم مصغّرة. ثبّته أولاً باستخدام sudo apt install -y jq على Ubuntu وDebian.

ما الذي يفعله رمز الخروج باستدعاء الأداة الجاري تنفيذه

هناك ثلاث نتائج.

  • يعني Exit 0 النجاح، وتظل أي حقول قرار صالحة بتنسيق JSON سارية، بما في ذلك الحظر أو الرفض. في PreToolUse، لا يعني Exit 0 من دون قرار الموافقة، ويستمر تدفق الأذونات المعتاد. في UserPromptSubmit وUserPromptExpansion وSessionStart وPostModelSwitch، يُضاف خرج stdout النصي العادي إلى سياق النموذج. في معظم الأحداث الأخرى، يُرسَل stdout إلى سجل التصحيح فقط.
  • يحظر Exit 2 الإجراء في الأحداث التي يمكن حظرها، ومنها PreToolUse، ويصبح stderr الرسالة المرافقة للحظر، ما لم يتضمن خرج JSON قرار حظر؛ عندها تكون أسباب القرار هي المعتمدة. يعتمد قارئ هذه الرسالة على الحدث. في PreToolUse وStop، يراها النموذج بوصفها السبب. في UserPromptSubmit وPreModelSwitch، تُعرض لك ولا تُضاف إلى سياق النموذج. في PostToolUse وPostToolUseFailure، اللذين لا يمكن حظرهما، يُتجاهل الحظر، مع استمرار وصول stderr إلى النموذج بوصفه ملاحظات. في معظم الأحداث الأخرى التي لا يمكن حظرها، تُعرض stderr لك فقط أو يجري تجاهلها. في Stop وSubagentStop وTaskCompleted وhook UserPromptSubmit الخاص بأحد المكونات الإضافية، يُعامَل Exit 2 مع stdout فارغ وخطأ ملف مفقود في stderr على أنه خطأ غير حاجب.
  • يُعد أي رمز خروج آخر مع stdout نصي عادي أو فارغ خطأً غير حاجب عادةً. يعرض النص المنقول إشعاراً بخطأ hook يتضمن السطر الأول من stderr بعد النص Failed with non-blocking status code:. يظل بإمكان JSON الصالح تحديد النتيجة في أحداث مثل PreToolUse، ما لم يؤدِّ فشل hook إلى حظر الإجراء. يفشل WorktreeCreate عند أي خروج غير صفري، ويفشل WorktreeRemove عند الخروج غير الصفري إذا ظل الدليل موجوداً بعد ذلك.

إذا أردت تنفيذ شيء يتجاوز الحظر أو عدم إصدار أي إجراء، فاستخدم Exit 0 واطبع كائن JSON إلى stdout بدلاً من ذلك. يحدد hook PreToolUse القرار باستخدام permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

يتجاوز "allow" المطالبة التفاعلية عندما تسمح قواعد الأذونات ومتطلبات موافقة الأداة بذلك، ويلغي "deny" الاستدعاء ويرسل السبب إلى النموذج، ويطلب "ask" التأكيد. اختر أسلوباً واحداً لكل hook. يؤدي الجمع بين Exit 2 وقرار JSON في stdout إلى إبقاء الحظر، حتى إذا أشار JSON إلى "allow".

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

مثال 1: حظر أمر مدمّر قبل تنفيذه

احفظ هذا الملف باسم .claude/hooks/block-destructive.sh في مشروعك:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

اجعله قابلاً للتنفيذ، ثم سجّله في PreToolUse ضمن .claude/settings.json:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

اختبر البرنامج النصي يدوياً قبل الوثوق به، لأن hook يتعطل عند معالجة مدخلاته عادةً يسمح بالتنفيذ عند عدم ضبط onFailure. في Windows من دون Git Bash، يمكن أن يؤدي فشل hook للأوامر بصيغة shell من النوع PreToolUse أو PermissionRequest إلى حظر استدعاء الأداة بدلاً من ذلك:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

يجب أن ترى السطر Blocked by policy: في stderr ورمز خروج قيمته 2. مرّر إليه أمراً غير ضار، مثل ls -la، ويجب ألا ترى أي مخرجات، وأن يكون رمز الخروج 0. في الجلسة، يظهر الاستدعاء المحظور في السجل مع رسالتك بوصفها السبب، ويقرأ النموذج هذه الرسالة ويتصرف وفقاً لها.

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

كن واضحاً بشأن طبيعة هذا الإجراء. يمثّل مطابقة الأنماط في سلسلة الأمر وسيلةً وقائية ضد إهمال agent، لكنها لا تمثّل حداً أمنياً ضد agent يتصرف بذكاء، لأن الأمر نفسه قد يُكتب بصيغة لا يراها grep. يجب وضع القواعد الصارمة في نظام الصلاحيات وفي الحساب الذي تعمل العملية تحته.

مثال 2: التنسيق والتحقق بعد كل تعديل

يعمل PostToolUse مع مُطابِق Edit|Write بعد نجاح أي من أداتي تحرير الملفات. احفظه باسم .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

اطلب من Claude إضافة دالة ذات مسافات بادئة غير صحيحة إلى ملف Python، ثم افتح الملف. ستجده منسقاً. هذا يؤكد أن الـhook عمل، لأن الـhook الناجح لا يعرض شيئاً في المحادثة.

لا يؤدي exit 2 هنا إلى التراجع عن أي شيء. يعمل PostToolUse بعد تنفيذ الأداة بالفعل، لذلك يبقى التعديل على القرص في كلتا الحالتين. ما يتيحه exit 2 هو وصول مخرجات ruff check إلى النموذج كملاحظات، فيصحح الخطأ الذي أدخله للتو بدلاً من المتابعة. هذا هو الفرق بين فشل lint تكتشفه وقت commit وفشل يصلحه الوكيل في الجولة نفسها.

هناك حدّان مهمان للمطابِق. لا يرى Edit|Write الملفات التي غيّرها أمر shell، ويكتب Claude الملفات عبر Bash بما يكفي لجعل هذه الفجوة مؤثرة. لتغطية كل استدعاء، طابق Bash أيضاً، واجعل البرنامج النصي يسرد الملفات التي تغيّرت باستخدام git status --porcelain. وللتغطية مرة واحدة في كل جولة، ضع الفحص في hook من نوع Stop بدلاً من ذلك.

مثال 3: تسجيل كل استدعاء لأداة لأغراض التدقيق

يعمل المطابق الفارغ في PostToolUse مع كل استدعاء ناجح لأداة، باستثناء EndConversation. إن إرسال السجل إلى سجل النظام بدلاً من ملف في الدليل الرئيسي لا يمنع وكيل shell من الوصول إليه؛ إذ يعتمد الوصول على أذونات الحساب. يمكن للمستخدمين قراءة سجلاتهم الخاصة لكل مستخدم، كما يمكن لـ root وأعضاء systemd-journal وadm أو wheel قراءة جميع ملفات السجل:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

اقرأ السجل باستخدام journalctl -t claude-code -o cat | tail -n 5. عند امتلاك أذونات قراءة السجلات، ينبغي أن ترى سطراً واحداً بتنسيق JSON لكل استدعاء ناجح لأداة، باستثناء EndConversation، مع ظهور الأحدث أخيراً. إذا لم يظهر شيء، فتحقق من الوصول إلى السجل ومن تشغيل الـhook؛ يشرح قسم استكشاف الأخطاء وإصلاحها أدناه آلية عمل الـhook.

أضف الكتلة نفسها تحت PostToolUseFailure لالتقاط الاستدعاءات التي فشلت، لأن PostToolUse يعمل عند النجاح فقط، بينما يكون الأمر الفاشل هو الحالة الأهم عادةً. والسبب في استخدام logger بدلاً من الإلحاق بملف في الدليل الرئيسي هو الملكية: يعمل الـhook بالمستخدم نفسه الذي يعمل به shell الخاص بالوكيل، ولذلك فإن كل ما يستطيع ذلك المستخدم الإلحاق به يستطيع أيضاً تفريغه. يكتب systemd-journald السجل؛ لكن حمايته من الحذف تظل تعتمد على امتيازات حساب الوكيل.

المدة التي يمكن أن يعمل فيها الـhook

رسم بيانيDefault hook timeout in seconds, by hook type and event
البيانات وراء هذا الرسم البياني
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

تعمل command hook لمدة 600 ثانية افتراضياً، أي عشر دقائق. وتفرض بعض الأحداث مدة أقصر بكثير. تتشارك hooks من نوع SessionEnd مهلة قدرها 1.5 ثانية فيما بينها، لذلك يجب أن تكون عملية التنظيف عند نهاية الجلسة سريعة. لكن ضبط timeout أطول على hook في ملفات الإعداد يرفع هذه المهلة المشتركة إلى القيمة نفسها، بحد أقصى 60 ثانية.

إذا تجاوزت synchronous command أو HTTP أو MCP tool hook مهلة التنفيذ، تُلغى ولا تُصدر عادةً قراراً. في حالة PreModelSwitch، تمنع المهلة التبديل. أما في حالة PreToolUse من نوع guardrail، فتسمح المهلة عادةً بمتابعة استدعاء الأداة ضمن مسار الصلاحيات المعتاد، مع استثناء Windows المذكور أعلاه عندما تكون onFailure غير مضبوطة. لذلك اجعل guardrail scripts صغيرة. منذ الإصدار 2.1.295، يمكنك عكس هذا السلوك الافتراضي في hook من نوع command أو http باستخدام "onFailure": "block". يؤدي ذلك إلى اعتبار انتهاء المهلة أو تعطل العملية أو خروجها برمز غير متوقع حالة حظر. لكنه لا يؤثر في Stop أو SubagentStop أو TaskCompleted أو TeammateIdle أو background command hooks. بالنسبة إلى الأعمال البطيئة التي لا ينتظرها أحد، مثل إرسال سجل إلى مكان آخر، اضبط "async": true، وستعمل الـhook في الخلفية من دون تعطيل استدعاء الأداة.

الـHooks وملفات القواعد والمهارات وخوادم MCP

تختلط أربعة أشياء معاً لأنها تغيّر جميعاً سلوك الـagent. لكن واحداً منها فقط لا يبقى مجرد اقتراح.

ملف القواعد (CLAUDE.md، أو ملف ضمن .claude/rules/) هو نص يُحمَّل إلى سياق النموذج. وهو يوجّه السلوك، لكنه لا يفرض شيئاً. عند وضعه في مواجهة محادثة طويلة، وdiff كبير، وطلب جديد من المستخدم، قد يفقد سطر واحد منه أولوية التنفيذ. وهذه هي الآلية المعتادة وراء تجاهل الـagents للتعليمات التي كتبتها.

المهارة هي مجلد يضم تعليماتاً وscripts، ويحمّله النموذج عندما يقرر أن المهارة ذات صلة. هذا القرار هو جوهر المهارة، وهو أيضاً حدّها: فما زال النموذج هو من يقرر. يمكنك رؤية الجانبين في مهارة مثل Ponytail، التي تدفع الـagent نحو أصغر تغيير ينجح، لأنها تشكّل طريقة التعامل مع المهمة بأكملها بأسلوب لا يستطيع أي hook تقديمه، وذلك فقط عندما يختار النموذج تحميلها.

يوفّر خادم MCP (model context protocol) للنموذج أدوات جديدة لاستدعائها. وهو يوسّع نطاق ما يستطيع الـagent الوصول إليه. لكنه لا يجعله يستخدم أي أداة، كما أنه عملية منفصلة يجب عليك تشغيلها وإدارتها، وهذا عمل مستقل بحد ذاته: راجع تشغيل خوادم MCP على VPS.

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

الـplugin هو طريقة لتجميع المكونات، وليس آلية خامسة. فهو يجمع hooks مع مهارات في وحدة واحدة قابلة للتثبيت، وهي الطريقة التي يوزّع بها الفريق وسيلة الحماية نفسها على كل machine: راجع كيفية عمل plugins في Claude Code.

قرار الأمان على VPS مشترك

الـhook هو كود يشغّله الوكيل، ويعمل باسم المستخدم الذي بدأ Claude Code. ويرث صلاحيات الملفات والبيئة الخاصة بذلك المستخدم. على الحاسوب المحمول، هذه مسألة تتعلق بسير العمل. أمّا على VPS الذي يعمل فيه وكيل دون مراقبة، فهي مسألة أمان تتكون عملياً من أربعة أجزاء.

الـhook الموجود في مستودع هو كود لم تكتبه أنت. إنّ .claude/settings.json مُدرج في المستودع، لذلك يمكن لاستنساخ مستودع وبدء جلسة داخله أن يسجّل hooks جاءت مع المستودع. في الجلسة التفاعلية، يضع Claude Code hooks الخاصة بالمشروع خلف مربع حوار الثقة بمساحة العمل لذلك المجلد. وهذا يعني أنّ قبول الثقة هو اللحظة التي تقرر فيها تشغيلها. اقرأ كتلة hooks أولاً. أمّا جلسة claude -p أو SDK، وهي الطريقة المعتادة لتشغيل وكيل دون مراقبة، فلا تعرض مربع الحوار أبداً وتتعامل مع المجلد باعتباره موثوقاً، لذلك تعمل hooks الخاصة بالمستودع دون طلب موافقة. راجع ملفات .claude/ الخاصة به قبل كتابة سكربتات تعتمد عليه، أو شغّله باستخدام --settings '{"disableAllHooks": true}'.

يرى الـhook كامل إدخال الأداة. يكتب hook تدقيق يسجّل tool_input كل وسيط لكل أمر في سجل، بما في ذلك أي token صادف وجوده في سطر الأوامر. ويحتاج ذلك السجل إلى الحماية نفسها التي يحتاج إليها السر، وهذا جزء من المشكلة الأوسع المتمثلة في إبعاد الأسرار عن متناول وكيل الذكاء الاصطناعي.

يمكن للـhook الكتابة في سياق النموذج. تُضاف مخرجات stdout النصية العادية من hook ناجح من نوع SessionStart أو UserPromptSubmit إلى المحادثة. والـhook الذي يمرر نصاً من مصدر خارجي، أو من متعقب مشكلات، أو من ملف سجل، يسلّم نصاً غير موثوق إلى النموذج كما لو كنت قد كتبته بنفسك. والـhook الذي يمرر ملاحظة من جلسة Claude Code أخرى على VPS نفسه يفعل الشيء نفسه. ولا تستحق مخرجات وكيل ثقة أكبر من مخرجات متعقب المشكلات. تعامل مع stdout هذا باعتباره إدخالاً لا مخرجات.

الامتياز هو عنصر التحكم الفعلي. شغّل الوكيل باسم مستخدم مخصص غير متمتع بالامتيازات، ولا تمنحه إلا قواعد sudo التي يحتاج إليها. وجود منع PreToolUse مفيد، لكنه مصمم ليكون إجراءً لأفضل جهد: ويذكر المرجع الأمر نفسه بشأن مرشح if، ويوصي باستخدام نظام الصلاحيات عندما تحتاج إلى منع صارم. فقواعد الصلاحيات والحساب الذي تعمل العملية باسمه هما العنصران اللذان يصمدان تحت الضغط.

توجد خاصية واحدة في كل أوضاع الصلاحيات. تعمل hooks من نوع PreToolUse قبل التحقق من وضع الصلاحيات في كل وضع، لذلك يمنع hook الذي يعيد deny الأداة حتى مع bypassPermissions. يمكن للـhooks تشديد ما تسمح به قواعد الصلاحيات. لكنها لا تستطيع تخفيفه. والاستثناء هو mod. على جهاز لا يحتوي على إعدادات مُدارة ولا ملف managed-mcp.json، وفي جلسة لم تُسجّل الدخول فيها عبر /login إلى خطة Team أو Enterprise، يمكن لـmod مثبت يتعامل مع tool.check أن يوافق على استدعاء منعه hook من نوع PreToolUse. عند وجود إعدادات مُدارة، أو ملف managed-mcp.json، أو اعتماد جلسة من نوع /login لخطة Team أو Enterprise، يبقى الاستدعاء الذي منعه hook من نوع PreToolUse محظوراً افتراضياً، بصرف النظر عن ملف الإعدادات الذي جاء منه hook. وتُعد الجلسة التي تعمل باستخدام API key أو CLAUDE_CODE_OAUTH_TOKEN طويل الأجل، وهي طريقة تشغيل كثير من الخوادم لها، غير مسجّلة الدخول حتى عند تخزين بيانات تسجيل الدخول. تحقّق مما يمكن أن تغيّره Claude Code mods قبل تثبيت mod على خادم.

لماذا لا يتم تشغيل hook الخاص بي؟

اتبع هذه الخطوات بالترتيب. توضّح كل خطوة العَرَض الذي ستراه فعلياً.

  • شغّل /hooks وتحقق من ظهور hook ضمن الحدث المتوقع. يعني غياب hook من القائمة عادةً وجود خطأ في صياغة JSON داخل ملف الإعدادات، لأن الفواصل الزائدة والتعليقات غير مسموح بها، أو يعني أن الملف ليس في أحد المواقع الستة المذكورة أعلاه.
  • طابق matcher مع اسم الأداة حرفياً. تكون المطابقات حساسة لحالة الأحرف، لذلك لا يطابق "bash" أداة Bash مطلقاً.
  • شغّل script يدوياً باستخدام إدخال نموذجي، كما في المثال 1 أعلاه. إذا كان رمز الخروج غير متوقع، فهناك خطأ في script؛ افحص stdout أيضاً، لأن JSON صالحاً يمكن أن يقدّم قراراً بشأن أحداث مثل PreToolUse.
  • تعني الرسالة jq: command not found أن jq مفقود على ذلك الجهاز. ويعني ظهور command not found للـscript الخاص بك أن المسار لم يُحلّ، لذلك استخدم ${CLAUDE_PROJECT_DIR} أو مساراً مطلقاً. إذا لم يُشغّل script مطلقاً، فمن المحتمل أنه غير قابل للتنفيذ.
  • يطبع hook JSON صالحاً، لكن لا يحدث شيء. على macOS وLinux، يعمل hook بصيغة shell عبر sh -c داخل shell غير تفاعلي، لكن بعض الإعدادات تستدعي profile أيضاً، مثل BASH_ENV الذي يشير إلى ~/.bashrc. إذا طبع ذلك profile رسالة ترحيبية، فستُضاف الرسالة قبل JSON. ولن يبدأ stdout عندئذٍ بـ {، لذلك يقرأ Claude Code المحتوى كله كنص عادي ويتجاهل القرار. وبما أن hook خرج بالرمز 0، فلن يظهر خطأ في transcript. في معظم الأحداث، يُرسل ذلك النص إلى سجل التصحيح فقط، بينما يُضاف في UserPromptSubmit وUserPromptExpansion وSessionStart وPostModelSwitch إلى سياق النموذج، بما في ذلك رسالة الترحيب. ضع أي echo في profile داخل شرط بحيث لا يُشغّل إلا في shells التفاعلية.
  • إذا استمرت المشكلة، فابدأ الجلسة باستخدام claude --debug-file /tmp/claude.log وشغّل tail -f /tmp/claude.log في طرفية ثانية. يسجّل سجل التصحيح أي hooks تطابقت، ورمز الخروج الذي أعاده كل منها، وكل ما كتبته إلى stdout وstderr.

FAQ

ما الفرق بين hook في Claude Code وتعليمة CLAUDE.md؟

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

كيف أوقف Claude Code عن تشغيل أمر shell محدد؟

سجّل hook من النوع PreToolUse مع matcher من النوع Bash يقرأ الأمر من .tool_input.command، ويكتب سبب الرفض إلى stderr، ثم يخرج بالحالة 2. يلغي Claude Code الاستدعاء ويعرض السبب للنموذج. ويحدث ذلك قبل فحص وضع الأذونات، لذلك يظل الرفض سارياً حتى في وضع bypassPermissions. يُعدّ مطابقة نمط في سلسلة الأمر وسيلة حماية، وليس حداً أمنياً، لأن الأمر نفسه يمكن كتابته بصيغة لا يطابقها النمط. لذلك ادعمها بقواعد الأذونات وبحساب غير متمتع بالامتيازات.

يطبع hook لدي JSON صالحاً، لكن لا يحدث شيء. لماذا؟

افحص ملف تعريف shell بحثاً عن نص يُطبع قبل JSON. في macOS وLinux، يمر hook الذي لا يحتوي على الحقل args عبر sh -c. وفي الإعدادات التي لا تزال تستدعي ملف تعريف shell، مثل BASH_ENV الذي يشير إلى ~/.bashrc، يضع ملف التعريف الذي يطبع banner هذا النص في stdout قبل JSON. ولأن الناتج لم يعد يبدأ بـ{، يتعامل Claude Code مع الناتج كله كنص عادي ويتجاهل القرار. ولأن hook خرج بالحالة 0، لا يظهر أي خطأ في السجل. ضع أي echo في ملف التعريف ضمن اختبار للـshell التفاعلي، ثم تأكد من الإصلاح بقراءة سجل التصحيح من claude --debug-file /tmp/claude.log.

هل من الآمن تشغيل hooks الخاصة بـClaude Code على خادم مشترك؟

تعمل hooks بحساب المستخدم الذي بدأ Claude Code وبصلاحيات ملفاته، ولذلك يمكن لـhook تنفيذ أي إجراء يستطيع ذلك الحساب تنفيذه. يغطي أسلوبان معظم المخاطر: شغّل الوكيل بحساب مخصص غير متمتع بالامتيازات مع سياسة sudo محدودة، واقرأ كتلة hooks في أي مستودع قبل قبول نافذة حوار الثقة بمساحة العمل أو تشغيل claude -p فيه، لأن hooks الخاصة بالمشروع تأتي ضمن .claude/settings.json، ولأن وضع -p لا يعرض نافذة الحوار تلك مطلقاً. اضبط "disableAllHooks": true في ملف الإعدادات لتعطيل hooks، باستثناء hooks المُدارة التي تتطلب ضبط هذا الإعداد على مستوى الإدارة. ويمكن لإعداد مشروع بقيمة false أن يتجاوز إعداد مستخدم بقيمة true.

هل كان هذا المقال مفيدًا؟