Стражи

Хук — страж на конкретной точке жизненного цикла. Разница с инструкцией в CLAUDE.md принципиальная: инструкция советует, хук выполняется. Он срабатывает в фиксированный момент независимо от того, что решила модель.

События

Полный перечень точек, к которым можно прицепиться:

SessionStart, Setup, UserPromptSubmit, UserPromptExpansion, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, PostToolBatch, Notification, MessageDisplay, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, DirectoryAdded, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, SessionEnd.

Где настраивается

Меню /hooks показывает всё настроенное, сгруппированное по событиям, — но оно только для чтения: правки делаются в JSON.

Форма записи

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

Каждое имя события — ключ внутри единственного объекта hooks. Если блок уже есть, добавляйте событие соседним ключом, а не заменяйте объект целиком.

Обработчик бывает пяти типов: command (команда оболочки), http (эндпоинт), mcp_tool (инструмент MCP-сервера), prompt (оценка моделью) и agent (субагент). Полезные поля: matcher (фильтр по инструменту, принимает регулярное выражение), if (фильтр в синтаксисе правил разрешений, например Bash(rm *)), timeout в секундах, statusMessage для строки состояния, async для фонового запуска, shell для выбора bash или powershell.

Таймауты по умолчанию: 10 минут для command, http и mcp_tool; 30 секунд для prompt; 60 секунд для agent. UserPromptSubmit понижает первые до 30 секунд, MessageDisplay — до 10.

Как хук отвечает

Через код выхода и стандартные потоки.

Структурированный ответ — объект hookSpecificOutput с полями permissionDecision (allow/deny), permissionDecisionReason, additionalContext, updatedInput, continue; на верхнем уровне доступны systemMessage и terminalSequence.

Ключевой факт про власть: PreToolUse срабатывает до проверки режима разрешений, в любом режиме, включая bypassPermissions. Хук, вернувший deny, блокирует инструмент даже там, где человек отключил все вопросы. Обратное не работает: allow не отменяет запрещающих правил. Хуки умеют ужесточать, но не ослаблять — Круг дозволенного.

Четыре рабочих сценария

Форматирование после правки. PostToolUse с матчером Edit|Write, команда вытаскивает путь из входного JSON и запускает форматтер.

Защита файлов. PreToolUse со скриптом, который сверяет путь со списком и выходит с кодом 2. Агент получает текст из stderr как объяснение и меняет подход.

Восстановление контекста после сжатия. SessionStart с матчером compact: то, что скрипт печатает в stdout, дописывается в контекст. Так переживают компакцию договорённости, которых нет в файлах (Котёл).

Ворота завершения. Stop-хук не даёт ходу закончиться, пока проверка не прошла. Предохранитель: после восьми блокировок подряд Claude Code перебивает хук — механика в Замкнутый цикл.

Что помнить

PostToolUse не может отменить действие — инструмент уже выполнен. Stop срабатывает на каждом завершении ответа, а не только по окончании задачи, и не срабатывает при вашем прерывании. Если несколько PreToolUse возвращают updatedInput, побеждает последний завершившийся, а порядок недетерминирован — не давайте двум хукам править вход одного инструмента.

Отдельная ловушка в рабочих копиях: ${CLAUDE_PROJECT_DIR} остаётся указывать на корень, где стартовала сессия, а актуальный каталог приходит полем cwd во входном JSON (Веер).

Хуки едут вместе с плагином и с чужим репозиторием — учитывайте это, раздавая настройку: Раздача артефактов.