Claude Code Hooks

Коротко: Команды оболочки (или промпты/агенты), которые Claude Code автоматически выполняет в определённые моменты рабочего процесса — например, перед запуском инструмента, после того как Claude закончил отвечать, или когда сеанс начинается или заканчивается.

Подробнее: Хуки настраиваются в settings.json по событиям (например, Stop, PreToolUse, SessionEnd) и, при желании, с «матчером» (например, только для определённых инструментов). Важно: Stop срабатывает после каждого хода ответа, а не один раз в конце всего разговора — для «один раз за сеанс» предназначен SessionEnd.

Наш контекст: В качестве теста мы сделали хук Stop, который после каждого ответа выгружал полную стенограмму JSONL 1:1 в заметку Obsidian — но затем отказались от него, потому что вы хотели структурированные заметки по содержанию, а не сырой текст. Теперь я пишу глоссарные статьи вроде этой вживую по ходу разговора.

Подробности

Конфигурация и матчеры

Хуки настраиваются по событиям в settings.json (или в settings.local.json для локальных, не попадающих в коммит переопределений). Типичное определение выглядит так:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo 'Bash is being run' >> log.txt" }]
      }
    ]
  }
}

matcher отфильтровывает, для каких инструментов/событий хук вообще срабатывает — без матчера он выполняется при каждом событии этой категории. На одно событие можно зарегистрировать несколько хуков; они затем выполняются друг за другом.

Доступные типы событий

Помимо PreToolUse/PostToolUse (до и после каждого выполнения инструмента) и Stop (после каждого хода ответа), есть, среди прочего, SessionStart/SessionEnd (один раз в начале/конце сеанса), UserPromptSubmit (когда пользователь отправляет сообщение, до его обработки Claude) и PreCompact (перед сжатием контекста). Каждый тип события получает через stdin разные структурированные данные (например, для PreToolUse — имя инструмента и его входные параметры в виде JSON) — скрипт хука может прочитать эти данные и на их основе решить, реагировать ли и как.

Блокировка вызовов инструментов

Хук PreToolUse может даже заблокировать выполнение инструмента (ответив определённым кодом завершения или определённым выводом), что можно использовать, например, для собственных правил безопасности — скажем, чтобы полностью запретить определённые команды Bash независимо от собственного суждения Claude. Это важное отличие от простых инструкций в CLAUDE.md: хук — это жёсткое правило, обеспечиваемое самой обвязкой (harness), которое нельзя обойти хитрой формулировкой промпта, тогда как текстовые инструкции в принципе всегда лишь рекомендации по поведению, которым следует модель.

Команды оболочки и промпты/агенты

Помимо простых команд оболочки хуки могут запускать и более сложные промпты или специальных агентов, а не только однострочные скрипты. Это позволяет, например, сделать хук Stop, который после каждого ответа автоматически направляет агента-ревьюера на последние изменённые файлы, или хук SessionEnd, создающий сводку сеанса — значительно мощнее простого скрипта оболочки, но и с соответственно более высоким расходом ресурсов, так как добавляется ещё один вызов LLM.

Важные различия между похожими по звучанию событиями

Stop срабатывает после каждого хода ответа, а не один раз в конце всего разговора — легко упускаемая ловушка, если на самом деле нужно «один раз за сеанс». Для этой цели предназначен SessionEnd; он действительно срабатывает только когда заканчивается весь сеанс. Кто путает их, рискует получить либо хук, который излишне часто выполняется на каждом ходе ответа, либо такой, который не реагирует в настоящем конце, как задумано.

См. также: JSONL