Система Hooks

Полное освоение Hooks в Claude Code — 17 событий жизненного цикла, 3 типа обработчиков, более 10 практических рецептов и корпоративная конфигурация

Обновлено 2026-09-03

Содержание

1. Основные понятия
2. Полный список событий
- Основные события
- Расширенные события (добавлены в 2026)
3. Типы обработчиков
4. Настройка
5. Практические рецепты
6. Корпоративные Hooks
- Конфигурация managed-settings.d/
7. Отладка и диагностика
8. Сравнение с Hooks в Codex
Следующие шаги

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:

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

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

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

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

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

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

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

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

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

{
  "hooks": {
    "ИмяСобытия": [
      {
        "matcher": "имя инструмента (необязательно, несколько через |)",
        "hooks": [
          {
            "type": "command|prompt|subagent",
            "command": "..."
          }
        ]
      }
    ]
  }
}

5. Практические рецепты ¶

Рецепт 1: автоформатирование после сохранения файла ¶

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

Рецепт 2: перехват опасных команд shell ¶

{
  "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: защита чувствительных файлов ¶

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

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

Linux:

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

Рецепт 5: уведомление в Slack ¶

{
  "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 ¶

{
  "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: журнал аудита ¶

{
  "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: автоматический запуск тестов ¶

{
  "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: защита файлов миграций ¶

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo $FILEPATH | grep -qE 'migrations/|alembic/versions/' && echo 'менять существующую миграцию нельзя, создайте новую' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

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

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

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

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

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

# Создаём файл политики в каталоге корпоративного управления
mkdir -p /etc/claude-code/managed-settings.d/

// /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 ¶

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

# Имитируем переменные окружения 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 — более продвинутый механизм расширения
Серверы MCP — подключение внешних инструментов
Автоматизация и CI/CD — работа в headless-режиме
Приёмы работы в CLI — техники командной строки

← Предыдущая

Подробное руководство по режиму Plan

MCP-серверы

Система Hooks

Похожие документы