# نظام الخطافات

تتيح لك الخطافات إدراج منطقك الخاص عند نقاط رئيسية في دورة حياة Claude Code — تنسيق الشيفرة تلقائيًا، وحظر الأوامر الخطرة، وإرسال الإشعارات، وكتابة سجلات التدقيق. تُعدّ الخطافات واحدة من أقوى آليات التوسعة في Claude Code.

---

## 1. المفاهيم الأساسية

تتكون كل خطافة من ثلاثة أجزاء:

```
Event (When)   →  Matcher (Which)     →  Handler (What)
PreToolUse        matcher: "Bash"        command: "check_safety.sh"
```

- **الحدث**: متى يُطلق (على سبيل المثال `PreToolUse` — قبل تشغيل أداة)
- **المطابق**: مرشّح اختياري لاسم الأداة (فقط `Bash`، أو فقط `Write`)
- **المعالج**: أمر صدفة، أو حقن prompt، أو وكيل فرعي

---

## 2. قائمة الأحداث الكاملة

### الأحداث الأساسية

| الحدث | يُطلق | يمكنه الحظر | الاستخدام النموذجي |
|------|---------|--------|---------|
| **PreToolUse** | قبل تشغيل أداة | نعم (رمز الخروج 2) | اعتراض أمني، التحقق من الوسائط |
| **PostToolUse** | بعد تشغيل أداة | لا | تنسيق تلقائي، تسجيل |
| **Notification** | يرسل Claude إشعارًا | لا | تنبيهات Slack / Feishu / DingTalk |
| **Stop** | ينتهي Claude من الرد | لا | فحوصات الجودة، إنشاء commit تلقائي |
| **UserPromptSubmit** | يرسل المستخدم prompt | نعم | حقن السياق، فحوصات السياسات |
| **SessionStart** | تبدأ الجلسة | لا | إعداد البيئة، رسالة ترحيب |

### الأحداث الموسعة (جديدة في 2026)

| الحدث | يُطلق | يمكنه الحظر | الاستخدام النموذجي |
|------|---------|--------|---------|
| **SubagentStop** | ينتهي وكيل فرعي | لا | جمع نتائج الوكيل الفرعي |
| **SubagentToolUse** | يستخدم وكيل فرعي أداة | نعم | تقييد أذونات الوكيل الفرعي |
| **FileChanged** | يُعدّل ملف | لا | فحص تلقائي للشيفرة، بدء عملية بناء |
| **CwdChanged** | يتغير دليل العمل | لا | تحميل إعدادات خاصة بالدليل |
| **ModelChange** | يتم تبديل النموذج | لا | تتبع استخدام النموذج |
| **CompactComplete** | ينتهي /compact | لا | معالجة ما بعد الضغط |
| **ToolError** | تحدث أخطاء في أداة | لا | جمع الأخطاء، منطق إعادة المحاولة |

---

## 3. أنواع المعالجات

### النوع 1: الأمر (أمر صدفة)

النوع الأكثر شيوعًا — يشغّل أمر صدفة:

```json
{
  "type": "command",
  "command": "npx prettier --write $FILEPATH"
}
```

**متغيرات البيئة**:

| المتغير | المعنى | متاح في |
|------|------|---------|
| `$FILEPATH` | مسار الملف الذي تجري عليه العملية | PreToolUse/PostToolUse |
| `$TOOL_INPUT` | إدخال الأداة بصيغة JSON | PreToolUse |
| `$TOOL_NAME` | اسم الأداة | PreToolUse/PostToolUse |
| `$SESSION_ID` | معرّف الجلسة | الكل |
| `$NOTIFICATION_MESSAGE` | نص الإشعار | Notification |

**إدخال stdin**: يتلقى سكربت الخطافة أيضًا حمولة JSON على **stdin** تتضمن `session_id` و`tool_name` و`tool_input`. اقرأها عندما تحتاج إلى بيانات منظمة — فهي أكثر موثوقية من تحليل متغيرات البيئة.

**رموز الخروج**:
- `0`: المتابعة
- `2`: حظر العملية (PreToolUse/UserPromptSubmit فقط)
- أي قيمة أخرى: تُعامل كخطأ لكنها لا تحظر

### النوع 2: Prompt (حقن prompt)

يحقن نصًا في سياق Claude:

```json
{
  "type": "prompt",
  "prompt": "Remember: every database operation must use a transaction"
}
```

مفيد في: حقن قواعد إضافية للمشروع عند SessionStart.

### النوع 3: الوكيل الفرعي

ينشئ وكيلًا فرعيًا لمعالجة الحدث:

```json
{
  "type": "subagent",
  "prompt": "Review the code that was just modified and check for security vulnerabilities"
}
```

مفيد في: مراجعة تلقائية لجودة الشيفرة بعد PostToolUse.

---
## 4. الإعداد

اضبط الإعدادات في `.claude/settings.json` (على مستوى المشروع) أو `~/.claude/settings.json` (على مستوى المستخدم):

```json
{
  "hooks": {
    "EventName": [
      {
        "matcher": "tool name (optional, | separates several)",
        "hooks": [
          {
            "type": "command|prompt|subagent",
            "command": "..."
          }
        ]
      }
    ]
  }
}
```

---

## 5. وصفات عملية

### الوصفة 1: تنسيق تلقائي بعد حفظ ملف

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 2: حظر أوامر shell الخطرة

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo $TOOL_INPUT | grep -qE 'rm -rf /|sudo rm|git push --force|DROP TABLE|DROP DATABASE' && echo 'dangerous command blocked' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 3: حماية الملفات الحساسة

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo $TOOL_INPUT | grep -qE '\\.env|\\.env\\.|credentials|secrets?\\.ya?ml|private.key' && echo 'access to a sensitive file blocked' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 4: إشعار النظام عند اكتمال مهمة

**macOS:**
```json
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"$NOTIFICATION_MESSAGE\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}
```

**Linux:**
```json
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' \"$NOTIFICATION_MESSAGE\""
          }
        ]
      }
    ]
  }
}
```

### الوصفة 5: إشعار Slack

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST https://hooks.slack.com/services/xxx/yyy/zzz -H 'Content-Type: application/json' -d '{\"text\": \"Claude Code task finished\"}'"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 6: الإصلاح التلقائي عبر ESLint

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $FILEPATH 2>/dev/null; npx prettier --write $FILEPATH 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 7: سجل التدقيق

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) | session=$SESSION_ID | tool=$TOOL_NAME | file=$FILEPATH\" >> ~/.claude/audit.log"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 8: تشغيل الاختبارات تلقائيًا

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo $FILEPATH | grep -qE '\\.(ts|tsx|js|jsx)$' && echo $FILEPATH | grep -qvE '\\.test\\.|\\.spec\\.' && npx vitest related $FILEPATH --run 2>/dev/null || exit 0"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 9: حماية ملفات الترحيل

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo $FILEPATH | grep -qE 'migrations/|alembic/versions/' && echo 'editing an existing migration is not allowed, create a new one' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}
```

### الوصفة 10: حقن السياق عند بدء الجلسة

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Important: this project is mid-way through a v3.0 rewrite. All new code must use React Server Components; the pages/ directory is no longer supported."
          }
        ]
      }
    ]
  }
}
```

---
## 6. خطافات المؤسسات

### إعداد managed-settings.d/

يمكن لمسؤولي المؤسسات فرض سياسة أمنية على مستوى المؤسسة عبر الدليل `managed-settings.d/`:

```bash
# Create a policy file in the enterprise management directory
mkdir -p /etc/claude-code/managed-settings.d/
```

```json
// /etc/claude-code/managed-settings.d/security.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/claude-policy/check_command.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/opt/claude-policy/audit_log.sh"
          }
        ]
      }
    ]
  }
}
```

**لا يمكن تجاوز سياسة المؤسسات بواسطة إعدادات على مستوى المستخدم أو المشروع**.

---

## 7. تصحيح الأخطاء

### الوضع المفصّل

اضغط `Ctrl+O` لتشغيل الوضع المفصّل، الذي يعرض:
- متى يُشغَّل كل خطاف
- مخرجات stdout/stderr الخاصة بسكربت الخطاف
- رمز الخروج الخاص بالخطاف

### مشكلات شائعة

| المشكلة | السبب | الحل |
|------|------|---------|
| لا يُشغَّل الخطاف أبدًا | خطأ مطبعي في matcher | تحقق من حالة أحرف أسماء الأدوات: `Bash`، `Write`، `Edit`، `Read` |
| يمنع الخطاف العمل الطبيعي | منطق رمز الخروج خاطئ | تأكد من أن المسار الطبيعي هو `exit 0` وأن الحجب يحدث فقط بـ `exit 2` |
| الخطاف بطيء | يستغرق السكربت وقتًا طويلًا | ينبغي أن ينتهي الخطاف خلال 1–2 ثانية؛ شغّل المهام الطويلة في الخلفية |
| متغير بيئة فارغ | ذلك الحدث لا يوفّره | راجع الجدول أعلاه لمعرفة المتغيرات التي يوفرها الحدث |

### اختبار سكربت الخطاف

اختبره يدويًا في الطرفية قبل وضعه في الإعدادات:

```bash
# Simulate the PreToolUse environment variables
FILEPATH="src/main.ts" TOOL_INPUT="rm -rf /" bash -c 'echo $TOOL_INPUT | grep -qE "rm -rf" && echo "blocked" && exit 2 || exit 0'
```

---

## 8. المقارنة مع خطافات Codex

| | خطافات Claude Code | خطافات Codex |
|------|------------------|-------------|
| عدد الأحداث | 17 | أقل |
| الإعدادات | settings.json | config.toml |
| أنواع المعالجات | command/prompt/subagent | command |
| إدارة المؤسسات | managed-settings.d/ | لا يوجد |
| الحجب | رمز الخروج 2 | محدود |

---

## الخطوات التالية

- [المهارات](/docs/advanced/skills) — آلية إضافة أكثر تقدمًا
- [خوادم MCP](/docs/advanced/mcp) — ربط الأدوات الخارجية
- [الأتمتة وCI/CD](/docs/advanced/headless) — استخدام الوضع بلا واجهة
- [نصائح CLI](/docs/usage/cli-tips) — تقنيات سطر الأوامر