Хуки
Настройка и расширение поведения Claude Code с помощью регистрации команд оболочки
Введение
Хуки Claude Code — это пользовательские команды оболочки, которые выполняются в различные моменты жизненного цикла Claude Code. Хуки обеспечивают детерминированный контроль над поведением Claude Code, гарантируя, что определенные действия всегда выполняются, а не полагаются на то, что LLM решит их запустить.
Примеры использования:
- Уведомления: Настройте способ получения уведомлений, когда Claude Code ожидает вашего ввода или разрешения на выполнение чего-либо.
- Автоматическое форматирование: Запускайте
prettier
для файлов .ts,gofmt
для файлов .go и т.д. после каждого редактирования файла. - Логирование: Отслеживайте и подсчитывайте все выполненные команды для соответствия требованиям или отладки.
- Обратная связь: Предоставляйте автоматическую обратную связь, когда Claude Code создает код, который не соответствует соглашениям вашей кодовой базы.
- Пользовательские разрешения: Блокируйте изменения в производственных файлах или конфиденциальных каталогах.
Кодируя эти правила как хуки, а не инструкции в промптах, вы превращаете предложения в код уровня приложения, который выполняется каждый раз, когда это ожидается.
Хуки выполняют команды оболочки с вашими полными пользовательскими разрешениями без подтверждения. Вы несете ответственность за обеспечение безопасности ваших хуков. Anthropic не несет ответственности за любую потерю данных или повреждение системы в результате использования хуков. Ознакомьтесь с Соображениями безопасности.
Быстрый старт
В этом быстром старте вы добавите хук, который логирует команды оболочки, выполняемые Claude Code.
Предварительное требование: Установите jq
для обработки JSON в командной строке.
Шаг 1: Откройте конфигурацию хуков
Выполните слэш-команду /hooks
и выберите
событие хука PreToolUse
.
Хуки PreToolUse
запускаются перед вызовами инструментов и могут блокировать их, предоставляя
Claude обратную связь о том, что делать по-другому.
Шаг 2: Добавьте сопоставитель
Выберите + Add new matcher…
, чтобы запускать ваш хук только для вызовов инструмента Bash.
Введите Bash
в качестве сопоставителя.
Шаг 3: Добавьте хук
Выберите + Add new hook…
и введите эту команду:
Шаг 4: Сохраните конфигурацию
Для места хранения выберите User settings
, так как вы логируете в свой домашний
каталог. Этот хук будет применяться ко всем проектам, а не только к текущему
проекту.
Затем нажмите Esc, пока не вернетесь в REPL. Ваш хук теперь зарегистрирован!
Шаг 5: Проверьте ваш хук
Снова выполните /hooks
или проверьте ~/.claude/settings.json
, чтобы увидеть вашу конфигурацию:
Конфигурация
Хуки Claude Code настраиваются в ваших файлах настроек:
~/.claude/settings.json
- Пользовательские настройки.claude/settings.json
- Настройки проекта.claude/settings.local.json
- Локальные настройки проекта (не коммитятся)- Управляемые корпоративные настройки политики
Структура
Хуки организованы по сопоставителям, где каждый сопоставитель может иметь несколько хуков:
- matcher: Шаблон для сопоставления имен инструментов (применимо только для
PreToolUse
иPostToolUse
)- Простые строки сопоставляются точно:
Write
соответствует только инструменту Write - Поддерживает регулярные выражения:
Edit|Write
илиNotebook.*
- Если опущено или пустая строка, хуки запускаются для всех соответствующих событий
- Простые строки сопоставляются точно:
- hooks: Массив команд для выполнения при совпадении шаблона
type
: В настоящее время поддерживается только"command"
command
: Команда bash для выполненияtimeout
: (Необязательно) Время выполнения команды в секундах перед отменой всех выполняющихся хуков.
События хуков
PreToolUse
Запускается после того, как Claude создает параметры инструмента и перед обработкой вызова инструмента.
Распространенные сопоставители:
Task
- Задачи агентаBash
- Команды оболочкиGlob
- Сопоставление шаблонов файловGrep
- Поиск контентаRead
- Чтение файловEdit
,MultiEdit
- Редактирование файловWrite
- Запись файловWebFetch
,WebSearch
- Веб-операции
PostToolUse
Запускается сразу после успешного завершения инструмента.
Распознает те же значения сопоставителей, что и PreToolUse.
Notification
Запускается, когда Claude Code отправляет уведомления.
Stop
Запускается, когда основной агент Claude Code завершил ответ.
SubagentStop
Запускается, когда субагент Claude Code (вызов инструмента Task) завершил ответ.
Входные данные хука
Хуки получают данные JSON через stdin, содержащие информацию о сеансе и данные, специфичные для события:
Входные данные PreToolUse
Точная схема для tool_input
зависит от инструмента.
Входные данные PostToolUse
Точная схема для tool_input
и tool_response
зависит от инструмента.
Входные данные Notification
Входные данные Stop и SubagentStop
stop_hook_active
равно true, когда Claude Code уже продолжает работу в результате
хука остановки. Проверьте это значение или обработайте транскрипт, чтобы предотвратить
бесконечную работу Claude Code.
Выходные данные хука
Существует два способа возврата выходных данных хуками обратно в Claude Code. Выходные данные сообщают, следует ли блокировать, и любую обратную связь, которая должна быть показана Claude и пользователю.
Простой: Код выхода
Хуки сообщают статус через коды выхода, stdout и stderr:
- Код выхода 0: Успех.
stdout
показывается пользователю в режиме транскрипта (CTRL-R). - Код выхода 2: Блокирующая ошибка.
stderr
передается обратно Claude для автоматической обработки. См. поведение для каждого события хука ниже. - Другие коды выхода: Неблокирующая ошибка.
stderr
показывается пользователю и выполнение продолжается.
Напоминание: Claude Code не видит stdout, если код выхода равен 0.
Поведение кода выхода 2
Событие хука | Поведение |
---|---|
PreToolUse | Блокирует вызов инструмента, показывает ошибку Claude |
PostToolUse | Показывает ошибку Claude (инструмент уже выполнен) |
Notification | Неприменимо, показывает stderr только пользователю |
Stop | Блокирует остановку, показывает ошибку Claude |
SubagentStop | Блокирует остановку, показывает ошибку субагенту Claude |
Расширенный: Выход JSON
Хуки могут возвращать структурированный JSON в stdout
для более сложного управления:
Общие поля JSON
Все типы хуков могут включать эти необязательные поля:
Если continue
равно false, Claude прекращает обработку после выполнения хуков.
- Для
PreToolUse
это отличается от"decision": "block"
, который только блокирует конкретный вызов инструмента и предоставляет автоматическую обратную связь Claude. - Для
PostToolUse
это отличается от"decision": "block"
, который предоставляет автоматическую обратную связь Claude. - Для
Stop
иSubagentStop
это имеет приоритет над любым выходом"decision": "block"
. - Во всех случаях
"continue" = false
имеет приоритет над любым выходом"decision": "block"
.
stopReason
сопровождает continue
с причиной, показываемой пользователю, но не показываемой
Claude.
Управление решениями PreToolUse
Хуки PreToolUse
могут контролировать, продолжается ли вызов инструмента.
- “approve” обходит систему разрешений.
reason
показывается пользователю, но не Claude. - “block” предотвращает выполнение вызова инструмента.
reason
показывается Claude. undefined
приводит к существующему потоку разрешений.reason
игнорируется.
Управление решениями PostToolUse
Хуки PostToolUse
могут контролировать, продолжается ли вызов инструмента.
- “block” автоматически запрашивает Claude с
reason
. undefined
ничего не делает.reason
игнорируется.
Управление решениями Stop
/SubagentStop
Хуки Stop
и SubagentStop
могут контролировать, должен ли Claude продолжать.
- “block” предотвращает остановку Claude. Вы должны заполнить
reason
, чтобы Claude знал, как действовать дальше. undefined
позволяет Claude остановиться.reason
игнорируется.
Пример выхода JSON: Редактирование команд Bash
Работа с инструментами MCP
Хуки Claude Code бесшовно работают с инструментами Model Context Protocol (MCP). Когда серверы MCP предоставляют инструменты, они появляются со специальным шаблоном именования, который вы можете сопоставить в ваших хуках.
Именование инструментов MCP
Инструменты MCP следуют шаблону mcp__<server>__<tool>
, например:
mcp__memory__create_entities
- Инструмент создания сущностей сервера памятиmcp__filesystem__read_file
- Инструмент чтения файлов файловой системыmcp__github__search_repositories
- Инструмент поиска GitHub
Настройка хуков для инструментов MCP
Вы можете нацеливаться на конкретные инструменты MCP или целые серверы MCP:
Примеры
Форматирование кода
Автоматическое форматирование кода после изменения файлов:
Уведомление
Настройте уведомление, которое отправляется, когда Claude Code запрашивает разрешение или когда ввод промпта стал неактивным.
Соображения безопасности
Отказ от ответственности
ИСПОЛЬЗУЙТЕ НА СВОЙ СТРАХ И РИСК: Хуки Claude Code выполняют произвольные команды оболочки на вашей системе автоматически. Используя хуки, вы признаете, что:
- Вы несете единоличную ответственность за команды, которые вы настраиваете
- Хуки могут изменять, удалять или получать доступ к любым файлам, к которым имеет доступ ваша учетная запись пользователя
- Вредоносные или плохо написанные хуки могут привести к потере данных или повреждению системы
- Anthropic не предоставляет гарантий и не несет ответственности за любой ущерб, возникший в результате использования хуков
- Вы должны тщательно тестировать хуки в безопасной среде перед производственным использованием
Всегда просматривайте и понимайте любые команды хуков перед добавлением их в вашу конфигурацию.
Лучшие практики безопасности
Вот несколько ключевых практик для написания более безопасных хуков:
- Проверяйте и очищайте входные данные - Никогда не доверяйте входным данным слепо
- Всегда заключайте переменные оболочки в кавычки - Используйте
"$VAR"
, а не$VAR
- Блокируйте обход пути - Проверяйте наличие
..
в путях файлов - Используйте абсолютные пути - Указывайте полные пути для скриптов
- Пропускайте конфиденциальные файлы - Избегайте
.env
,.git/
, ключей и т.д.
Безопасность конфигурации
Прямые изменения хуков в файлах настроек не вступают в силу немедленно. Claude Code:
- Делает снимок хуков при запуске
- Использует этот снимок на протяжении всего сеанса
- Предупреждает, если хуки изменены извне
- Требует проверки в меню
/hooks
для применения изменений
Это предотвращает влияние вредоносных изменений хуков на ваш текущий сеанс.
Детали выполнения хуков
- Тайм-аут: Ограничение выполнения 60 секунд по умолчанию, настраивается для каждой команды.
- Если какая-либо отдельная команда превышает время ожидания, все выполняющиеся хуки отменяются.
- Параллелизация: Все соответствующие хуки выполняются параллельно
- Окружение: Запускается в текущем каталоге с окружением Claude Code
- Ввод: JSON через stdin
- Вывод:
- PreToolUse/PostToolUse/Stop: Прогресс показывается в транскрипте (Ctrl-R)
- Notification: Логируется только в отладке (
--debug
)
Отладка
Для устранения неполадок хуков:
- Проверьте, отображает ли меню
/hooks
вашу конфигурацию - Убедитесь, что ваши файлы настроек являются валидным JSON
- Протестируйте команды вручную
- Проверьте коды выхода
- Проверьте ожидания формата stdout и stderr
- Убедитесь в правильном экранировании кавычек
- Используйте
claude --debug
для отладки ваших хуков. Вывод успешного хука выглядит следующим образом.
Сообщения о прогрессе появляются в режиме транскрипта (Ctrl-R), показывая:
- Какой хук выполняется
- Выполняемая команда
- Статус успеха/неудачи
- Выходные данные или сообщения об ошибках