Хуки (hooks) в Claude Code

Что означают хуки в Claude Code

Официальный список событий насчитывает 31 точку. Самые ходовые: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd. Есть и узкие: SubagentStop, PreCompact, FileChanged, WorktreeCreate

Ключевая механика - код выхода. Выход с кодом 2 означает блокирующую ошибку: Claude Code игнорирует то, что хук напечатал в stdout, а текст из stderr отдаёт модели как сообщение об ошибке. На событии PreToolUse это отменяет вызов инструмента, на UserPromptSubmit отклоняет сам промпт, на Stop не даёт закончить ход

Отсюда разница с обычной инструкцией. Строка в файле памяти - контекст, модель может её не выполнить. Хук - внешняя программа, которая ничего не просит

Как настроить хук

Хуки описываются в тех же файлах настроек, что и остальное поведение Claude Code

1. Личные настройки на все проекты:

   ~/.claude/settings.json

2. Проектные и локальные:

   .claude/settings.json
   .claude/settings.local.json

3. Блок в файле настроек:

   {
     "hooks": {
       "PreToolUse": [
         { "matcher": "Bash",
           "hooks": [{ "type": "command",
                       "command": "~/.claude/hooks/my-guard.sh" }] }
       ]
     }
   }

4. Проверить, что скрипт исполняемый:

   chmod +x ~/.claude/hooks/my-guard.sh

Полное описание событий, формата JSON и кодов выхода - в разделе Hooks reference

Когда нужны хуки, а когда нет

Не нужны для вкуса и смысла: тон текста, выбор формулировки, оценку качества автоматически не проверить, там работает инструкция в файле памяти

Нужны там, где ошибка проверяется машинно и уже случалась. В моей рабочей системе на этом принципе стоит 87 скриптов-хуков в папке ~/.claude/hooks/, разведённых по 6 событиям в settings.json: часть запрещает опасные команды, часть не даёт закончить ход без прогона проверок

Правило отбора простое: проверяется регулярным выражением или кодом возврата и нарушалось хотя бы раз - поднимаем до хука. Всё остальное остаётся текстом

Связанные гайды