# سیستم هوک‌ها

هوک‌ها به شما اجازه می‌دهند در نقاط کلیدی چرخه عمر 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 پاسخ را تمام می‌کند | خیر | بررسی‌های کیفیت، کامیت خودکار |
| **UserPromptSubmit** | کاربر یک prompt ارسال می‌کند | بله | تزریق زمینه، بررسی سیاست‌ها |
| **SessionStart** | نشست آغاز می‌شود | خیر | راه‌اندازی محیط، پیام خوش‌آمدگویی |

### رویدادهای توسعه‌یافته (جدید در 2026)

| رویداد | زمان رخ دادن | امکان مسدودسازی | کاربرد معمول |
|------|---------|--------|---------|
| **SubagentStop** | یک زیرعامل تمام می‌شود | خیر | جمع‌آوری نتایج زیرعامل |
| **SubagentToolUse** | یک زیرعامل از یک ابزار استفاده می‌کند | بله | محدود کردن مجوزهای زیرعامل |
| **FileChanged** | یک فایل تغییر می‌کند | خیر | لینت خودکار، راه‌اندازی یک ساخت |
| **CwdChanged** | پوشه کاری تغییر می‌کند | خیر | بارگذاری پیکربندی مخصوص پوشه |
| **ModelChange** | مدل عوض می‌شود | خیر | ردیابی مصرف مدل |
| **CompactComplete** | /compact تمام می‌شود | خیر | پردازش پس از فشرده‌سازی |
| **ToolError** | یک ابزار خطا می‌دهد | خیر | جمع‌آوری خطاها، منطق تلاش مجدد |

---

## 3. انواع گرداننده

### نوع 1: Command (دستور شل)

رایج‌ترین نوع — یک دستور شل اجرا می‌کند:

```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: مسدودسازی دستورهای شل خطرناک

```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` را فشار دهید؛ این حالت نمایش می‌دهد:
- زمان فعال‌شدن هر هوک
- خروجی استاندارد/خطای استاندارد اسکریپت هوک
- کد خروج هوک

### مشکلات رایج

| مشکل | علت | راه‌حل |
|------|------|---------|
| هوک هرگز فعال نمی‌شود | اشتباه تایپی در 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 | محدود |

---

## گام‌های بعدی

- [Skills](/docs/advanced/skills) — سازوکار افزونه‌ای پیشرفته‌تر
- [سرورهای MCP](/docs/advanced/mcp) — اتصال ابزارهای خارجی
- [اتوماسیون و CI/CD](/docs/advanced/headless) — استفاده از حالت بدون رابط
- [نکات CLI](/docs/usage/cli-tips) — تکنیک‌های خط فرمان