Hooks: автоматические проверки и защитные барьеры

Краткий ответ

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

Основные моменты жизненного цикла

PreToolUse срабатывает до инструмента и может разрешить, запретить или изменить запрос в поддерживаемом формате. PostToolUse запускается после успешного действия, но уже не способен отменить случившийся эффект. Stop срабатывает, когда Claude завершает ответ, а не только когда вся бизнес-задача действительно готова.

Выбирайте событие исходя из момента, когда решение ещё может повлиять на безопасность.

Command, prompt и agent hooks

Command hook запускает процесс и общается через stdin, stdout, stderr и exit code. Prompt hook просит модель принять решение по данным события. Agent hook подходит, когда для проверки нужно исследовать реальное состояние репозитория, например запустить тесты и изучить результат.

Чем сложнее hook, тем важнее таймаут, наблюдаемость и предсказуемое поведение при ошибке.

Пример защитной конфигурации

Официальная схема позволяет сопоставить PreToolUse с Edit и Write и вызвать проектный скрипт:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Сам скрипт должен разбирать JSON-вход, корректно экранировать данные и возвращать документированный результат.

Hooks не заменяют все уровни защиты

Permission rules остаются основным способом контроля инструментов, sandbox ограничивает Bash на уровне ОС, а CI проверяет результат независимо от локального сеанса. Hook дополняет эту систему: например, запрещает редактировать generated-файл или автоматически запускает formatter.

Проверить найденные hooks можно командой /hooks. Matchers чувствительны к регистру и должны совпадать с именем инструмента.

Упражнение: спроектируйте hook до кода

Опишите требование «не разрешать менять миграции после их публикации»:

1. Какое событие нужно перехватить? 2. Какие пути считать защищёнными? 3. Откуда взять факт публикации? 4. Что вернуть агенту при запрете? 5. Как не заблокировать создание новой миграции? 6. Какая CI-проверка продублирует правило?

Реализовывать hook стоит только после ответов.

Частые вопросы

Может ли PostToolUse отменить изменение?

Нет. Он запускается после инструмента. Для блокировки до действия используйте PreToolUse.

Почему Stop hook иногда запускается раньше ожидаемого?

Потому что событие означает завершение ответа Claude, а не доказанное завершение всей пользовательской задачи.

Где диагностировать неработающий hook?

Откройте /hooks, проверьте событие, точное имя matcher, права скрипта, JSON-ввод, stderr и таймаут.

Что важно запомнить

Событие hook нужно выбирать по моменту необходимого контроля.
PreToolUse способен предотвратить действие, PostToolUse — только отреагировать.
Hooks дополняют permissions, sandbox и CI.
Любой hook требует негативных тестов и понятной диагностики.

https://yadro-code.ru/lessons/without-university/claude-code-workflows/claude-code-12