# Система Hooks

Hooks позволяют вставлять собственную логику в ключевые точки жизненного цикла Claude Code — автоматически форматировать код, перехватывать опасные команды, отправлять уведомления, вести журнал аудита. Это один из самых мощных механизмов расширения Claude Code.

---

## 1. Основные понятия

Каждый hook состоит из трёх частей:

```
Событие (When)  →  Матчер (Which)      →  Обработчик (What)
PreToolUse         matcher: "Bash"        command: "check_safety.sh"
```

- **Событие**: когда срабатывает (например, `PreToolUse` — перед запуском инструмента)
- **Матчер**: необязательный фильтр по имени инструмента (только `Bash` или только `Write`)
- **Обработчик**: команда shell, внедрение промпта или субагент

---

## 2. Полный список событий

### Основные события

| Событие | Когда срабатывает | Может блокировать | Типичное применение |
|------|---------|--------|---------|
| **PreToolUse** | Перед запуском инструмента | Да (exit 2) | Перехват по безопасности, проверка аргументов |
| **PostToolUse** | После запуска инструмента | Нет | Автоформатирование, логирование |
| **Notification** | Claude отправляет уведомление | Нет | Оповещения в Slack / Feishu / DingTalk |
| **Stop** | Claude завершил ответ | Нет | Проверка качества, автокоммит |
| **UserPromptSubmit** | Пользователь отправил промпт | Да | Внедрение контекста, проверка политик |
| **SessionStart** | Старт сессии | Нет | Инициализация окружения, приветствие |

### Расширенные события (добавлены в 2026)

| Событие | Когда срабатывает | Может блокировать | Типичное применение |
|------|---------|--------|---------|
| **SubagentStop** | Субагент завершил работу | Нет | Сбор результатов субагента |
| **SubagentToolUse** | Субагент использует инструмент | Да | Ограничение прав субагента |
| **FileChanged** | Файл изменён | Нет | Автоматический lint, запуск сборки |
| **CwdChanged** | Смена рабочего каталога | Нет | Загрузка конфигурации для каталога |
| **ModelChange** | Переключение модели | Нет | Учёт использования моделей |
| **CompactComplete** | Завершение /compact | Нет | Обработка после сжатия контекста |
| **ToolError** | Ошибка инструмента | Нет | Сбор ошибок, логика повторов |

---

## 3. Типы обработчиков

### Тип 1: Command (команда shell)

Самый распространённый тип — выполняет команду shell:

```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**: скрипт hook также получает на **stdin** JSON с полями `session_id`, `tool_name` и `tool_input`. Когда нужны структурированные данные, читайте его — это надёжнее разбора переменных окружения.

**Коды возврата**:
- `0`: продолжить
- `2`: заблокировать операцию (только PreToolUse/UserPromptSubmit)
- прочие: считаются ошибкой, но не блокируют

### Тип 2: Prompt (внедрение промпта)

Добавляет текст в контекст Claude:

```json
{
  "type": "prompt",
  "prompt": "Помни: любые операции с базой данных должны выполняться в транзакции"
}
```

Когда пригодится: добавить дополнительные правила проекта на SessionStart.

### Тип 3: Subagent (субагент)

Порождает субагента для обработки события:

```json
{
  "type": "subagent",
  "prompt": "Проверь только что изменённый код на уязвимости безопасности"
}
```

Когда пригодится: автоматическое ревью качества кода после PostToolUse.

---

## 4. Настройка

Настраивается в `.claude/settings.json` (уровень проекта) или `~/.claude/settings.json` (уровень пользователя):

```json
{
  "hooks": {
    "ИмяСобытия": [
      {
        "matcher": "имя инструмента (необязательно, несколько через |)",
        "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 'опасная команда заблокирована' && 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 'доступ к чувствительному файлу заблокирован' && 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 завершена\"}'"
          }
        ]
      }
    ]
  }
}
```

### Рецепт 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 'менять существующую миграцию нельзя, создайте новую' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}
```

### Рецепт 10: внедрение контекста при старте сессии

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Важно: проект находится в процессе крупного рефакторинга до версии 3.0. Весь новый код должен использовать React Server Components, каталог pages/ больше не поддерживается."
          }
        ]
      }
    ]
  }
}
```

---

## 6. Корпоративные Hooks

### Конфигурация managed-settings.d/

Администратор организации может через каталог `managed-settings.d/` принудительно применить политику безопасности ко всей компании:

```bash
# Создаём файл политики в каталоге корпоративного управления
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. Отладка и диагностика

### Режим verbose

Нажмите `Ctrl+O`, чтобы включить режим verbose — в нём видно:
- когда сработал каждый hook
- вывод stdout/stderr скрипта hook
- код возврата hook

### Частые проблемы

| Проблема | Причина | Решение |
|------|------|---------|
| Hook не срабатывает | Опечатка в matcher | Проверьте регистр имён инструментов: `Bash`, `Write`, `Edit`, `Read` |
| Hook блокирует обычную работу | Неверная логика кода возврата | В штатном случае возвращайте `exit 0`, блокируйте только через `exit 2` |
| Hook работает медленно | Скрипт слишком долгий | Hook должен укладываться в 1–2 секунды; длинные задачи выносите в фон |
| Переменная окружения пустая | Событие её не предоставляет | Сверьтесь с таблицей выше — доступна ли переменная в этом событии |

### Тестирование скрипта hook

Проверьте вручную в терминале, прежде чем добавлять в конфигурацию:

```bash
# Имитируем переменные окружения PreToolUse
FILEPATH="src/main.ts" TOOL_INPUT="rm -rf /" bash -c 'echo $TOOL_INPUT | grep -qE "rm -rf" && echo "blocked" && exit 2 || exit 0'
```

---

## 8. Сравнение с Hooks в Codex

| Параметр | Claude Code Hooks | Codex Hooks |
|------|------------------|-------------|
| Количество событий | 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) — работа в headless-режиме
- [Приёмы работы в CLI](/docs/usage/cli-tips) — техники командной строки