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

> ما الخطافات (hooks) في Claude Code، وعلى أي أحداث تعمل، وأمثلة جاهزة للنسخ، وكيف تشغّلها بأمان بمفتاح API.

آخر تحديث: 2026-11-01

الخطافات (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 إلى انتباهك:

```json
{
  "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 أو يكتبه:

```json
{
  "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`:

```bash
#!/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
```

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

```json
{
  "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:

```json
{
  "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`، نموذجًا عما إذا كانت كل المهام قد اكتملت:

```json
{
  "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. اشحن رصيدك

ادفع بإحدى [طرق الدفع](https://5abeer.ai/ar/docs/start/payment.md). ويُخصم من هذا الرصيد كل طلب يرسله خطاف `prompt` أو `agent`.

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

أنشئ مفتاحًا لمزوّد Anthropic كما في [إنشاء مفتاح](https://5abeer.ai/ar/docs/start/keys.md#create). وسمّه `claude-code` ليسهل عليك أن تجد استخدامه.

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

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

`~/.claude/settings.json`

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

### 4. جرّب خطافًا

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

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

| النموذج | المعرّف | الإدخال (سعرنا) | الإخراج (سعرنا) | السياق |
| --- | --- | --- | --- | --- |
| Claude Sonnet 5.5 | `claude-sonnet-5.5` | 0.60 US$ | 3 US$ | 1M |
| Claude Opus 5.5 | `claude-opus-5.5` | 1.20 US$ | 6 US$ | 1M |
| Claude Fable 5.1 | `claude-fable-5.1` | 3 US$ | 15 US$ | — |

ومع باقة من 5abeer تشمل Claude Code، يضبط تطبيق 5abeer AI برنامج Claude Code دون مفتاح، كما في [إعداد Claude Code](https://5abeer.ai/ar/docs/apps/claude-code.md#easy)، وتعمل الخطافات ضمن حدود الباقة.

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

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

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

مثال: 600,000 توكن إدخال و20,000 توكن إخراج على Claude Sonnet 5.5 (`claude-sonnet-5.5`) تكلّف 0.42 US$ بسعرنا مقابل 1.40 US$ بالسعر الرسمي (أقل بنسبة 70%). آخر مراجعة للسعر الرسمي: 19 أكتوبر 2026.

فأعطِ Claude Code مفتاحًا خاصًا به عليه حد إنفاق، كما في [تحكّم في كل مفتاح](https://5abeer.ai/ar/docs/start/keys.md#controls)، وراجع استخدامه في [تتبّع استخدامك](https://5abeer.ai/ar/docs/start/pricing.md#usage). وسعرنا بجوار السعر الرسمي في [صفحة Claude API](https://5abeer.ai/ar/api/claude)، ويقارن دليل [أرخص طريقة لاستخدام Claude Code](https://5abeer.ai/ar/guides/claude-code-cheapest-way) بين المفتاح والباقة.

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

تحذّر 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`](https://5abeer.ai/ar/docs/help/errors.md#INVALID_API_KEY): المفتاح في `~/.claude/settings.json` غير صحيح أو حُذف.
- [`MODEL_UNAVAILABLE`](https://5abeer.ai/ar/docs/help/errors.md#MODEL_UNAVAILABLE): النموذج المذكور في الحقل `model` لخطاف غير متاح الآن. أعد المحاولة، أو اختر نموذجًا آخر يقدّمه مفتاحك.
- [`INSUFFICIENT_BALANCE`](https://5abeer.ai/ar/docs/help/errors.md#INSUFFICIENT_BALANCE): الرصيد لا يكفي لهذا الطلب. اشحن رصيدك ثم أعد المحاولة.
- [`API_KEY_QUOTA_EXHAUSTED`](https://5abeer.ai/ar/docs/help/errors.md#API_KEY_QUOTA_EXHAUSTED): وصل المفتاح إلى حد إنفاقه، وكثيرًا ما يحدث ذلك حين يعمل خطاف `prompt` في كل دورة.

وكل رمز مشروح في [الأخطاء وحلولها](https://5abeer.ai/ar/docs/help/errors.md).

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

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

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

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

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

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

نعم. فالخطافات المكتوبة في بيانات الوكيل الفرعي لا تعمل إلا أثناء عمله، وتعمل خطافات `SubagentStart` و`SubagentStop` مع كل وكيل فرعي. راجع [الوكلاء الفرعيون في Claude Code](https://5abeer.ai/ar/guides/claude-code-subagents).

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

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

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

نعم، إذا كانت باقتك تشمل Claude Code. وتُحسب طلبات خطافات `prompt` و`agent` ضمن حدود الباقة. راجع [ما الذي تشغّله كل باقة](https://5abeer.ai/ar/docs/subscriptions/plan-apps.md#claude-code) و[صفحة الأسعار](https://5abeer.ai/ar/pricing).

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

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

## المصادر

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

- وثائق Claude Code: [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide)
- وثائق Claude Code: [Hooks reference](https://code.claude.com/docs/en/hooks)
- وثائق Claude Code: [Model configuration](https://code.claude.com/docs/en/model-config)

## ابدأ

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