Содержание

«Хочу автоформатирование после каждого редактирования». «Никогда не позволяй ничему переписывать .env или package-lock.json». «Останови опасные команды rm -rf». Способ сделать эти правила «это должно происходить всегда» реальными — не полагаясь на капризы ИИ — это хуки Claude Code. Хук — это shell-команда, которая автоматически запускается в определённых точках жизненного цикла Claude Code, и хуки также являются строительным блоком плагинов.

Эта статья на основе официальной документации разбирает что такое хуки, список событий, как их настроить, контракт ввода/вывода, сценарии применения и безопасность. Три ключевых момента сразу. ① Хук — это «детерминированная логика, которую запускает харнесс (сам Claude Code)» — он срабатывает наверняка, не дожидаясь, пока модель «решит» это сделать. ② Хуки вы описываете в settings.json как имя события → matcher → команда. ③ События вроде PreToolUse могут «заблокировать» через код выхода 2 или JSON — останавливая правки защищённых файлов или опасные команды.

CLAUDE CODE · ХУКИ

Срабатывает «наверняка» в ключевых точках жизненного цикла

— его запускает харнесс детерминированно, а не по усмотрению модели

SessionStart Начало сессии. Вывод внедряется как контекст
UserPromptSubmit При отправке промпта [может блокировать]
PreToolUse Прямо перед запуском инструмента = привратник [может блокировать]
PostToolUse После успеха инструмента = автоформат / аудит
Stop При завершении ответа = продолжать, пока не пройдут тесты, и т. д. [может блокировать]

В каждой точке запускается ваша shell-команда. Классика: PreToolUse, чтобы завернуть опасные действия у двери, PostToolUse, чтобы автоформатировать.

1. Что такое хуки Claude Code?

Официальное определение гласит: «Хуки — это определяемые пользователем shell-команды, которые выполняются в определённых точках жизненного цикла Claude Code. Они обеспечивают детерминированный контроль над поведением Claude Code, гарантируя, что определённые действия всегда происходят, а не полагаясь на то, что LLM решит их выполнить». Их используют, чтобы навязывать правила проекта, автоматизировать повторяющиеся задачи и интегрировать Claude Code с вашими существующими инструментами.

Суть — в детерминированности. Попросите Claude «запустить тесты» — и сделает ли он это, зависит от его «усмотрения». Но с хуком харнесс всегда их запускает — каприза тут нет. Помимо команд (command), теперь есть и типы обработчиков вроде HTTP, инструментов MCP, промптов LLM и проверки субагентом — но для начала достаточно думать о хуках как о «механизме, который всегда запускает shell-команду в ключевых точках».

2. События хуков

Событие обозначает «где в жизненном цикле оно срабатывает». Начните с девяти классических («может блокировать» = вы можете остановить это действие через код выхода 2 или JSON).

СобытиеСрабатывает, когдаБлок
SessionStartСессия начинается или возобновляется (stdout внедряется как контекст)Нет
UserPromptSubmitВы отправляете промпт, до того как Claude его обработаетДа
PreToolUseПрямо перед вызовом инструмента (основной привратник)Да
PostToolUseПосле успеха инструмента (само действие уже не отменить)Да
NotificationПри уведомлении (ожидание ввода/разрешения и т. д.)Нет
StopКогда Claude завершает ответ (блок = продолжать работу)Да
SubagentStopКогда субагент завершает работуДа
SessionEndКогда сессия завершаетсяНет
PreCompactПеред уплотнением контекстаДа

Документация 2026 года добавляет ещё много событий — PermissionRequest, PostToolUseFailure, ConfigChange, FileChanged, WorktreeCreate и другие. Но имена событий могут добавляться или меняться между версиями, поэтому эта статья опирается на стабильные девять классических плюс контракт из следующего раздела (полный актуальный список смотрите в официальной документации).

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

Хуки вы описываете под ключом "hooks" в settings.json. Расположение задаёт область видимости: пользователь (~/.claude/settings.json) / проект (.claude/settings.json, можно делиться через git) / локальный (.claude/settings.local.json) / управляемая политика (организация) / hooks/hooks.json плагина. Форма JSON выглядит так.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Структура такова: «hooks → имя события → массив { matcher, hooks:[...] } → у каждого хука есть type + command». matcher указывает целевое имя инструмента: "*" (или опущенное) совпадает со всеми, "Edit|Write" — это список через |, а прочие символы — регулярное выражение (например, mcp__memory__.*). Он чувствителен к регистру. Команда /hooks выводит список настроенных хуков, но только для чтения — чтобы добавить или изменить, редактируйте settings.json напрямую. Отключить все можно через "disableAllHooks": true.

4. Контракт ввода/вывода

Хук получает JSON на стандартном вводе (stdin) и возвращает результат через код выхода или JSON на стандартном выводе.

Ввод (stdin): общие поля включают session_id, transcript_path, cwd и hook_event_name. События инструментов добавляют tool_name и tool_input (например, {"command":"rm -rf /tmp/build"}); UserPromptSubmit добавляет prompt. Коды выхода: 0 = успех (для некоторых событий stdout добавляется в контекст — хотя выход 0 на PreToolUse не означает «одобрение»; обычный поток разрешений всё равно применяется), 2 = блок (stderr передаётся Claude как материал для корректировки, а JSON-вывод игнорируется).

# Пример: «deny» из PreToolUse через структурированный JSON-вывод (печатается в stdout)
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}
# Общие поля: continue (false = полностью остановить) / decision:"block"+reason /
#             additionalContext (добавляется для Claude) / updatedInput (переписать аргументы)

Самый важный принцип: «хуки могут ужесточать ограничения, но не ослаблять их». Возврат allow лишь пропускает запрос разрешения; правила deny в любой области (включая управляемые настройки) всегда имеют приоритет. Deny на PreToolUse блокирует даже при bypassPermissions / --dangerously-skip-permissions. О более широкой модели разрешений см. режимы разрешений и безопасность.

5. Примеры применения

Официальная классика в паре с её конфигурацией.

СЦЕНАРИИ

Классические автоматизации

Автоформат после правок
PostToolUse + Edit|Write автоматически запускает prettier / линтер.
Защита критичных файлов
PreToolUse блокирует (exit 2) правки .env, .git/ и т. п.
Остановка опасных команд
PreToolUse обнаруживает rm -rf и т. п. и возвращает deny.
Повторное внедрение контекста
stdout SessionStart каждый раз заново загружает соглашения и заметки (даже после уплотнения).
Уведомления и журнал аудита
Notification для оповещений на рабочем столе; PostToolUse для логирования истории команд.
Тесты перед остановкой
Stop не даёт Claude остановиться, пока тесты не пройдут (работать до зелёного).

Примечание: Claude также может менять файлы через Bash. Чтобы поймать каждое изменение, добавьте хук Stop, который раз за ход сканирует рабочее дерево.

6. Безопасность

Хуки мощны, но они автоматически выполняют произвольные shell-команды с вашими правами — не относитесь к этому легкомысленно.

⚠️ Официальное предупреждение

«Хуки автоматически выполняют произвольные shell-команды. Вы единолично отвечаете за безопасность хуков, которые настраиваете. ИСПОЛЬЗУЙТЕ НА СВОЙ РИСК». Хуки могут читать файлы, изменять вашу кодовую базу, выводить данные наружу или выполнять любую команду — настраивайте только те, которым полностью доверяете.

Снимок при запуске (ключевая защитная функция): конфигурация хуков фиксируется при старте сессии, поэтому изменения конфигурации в середине сессии не вступают в силу. Это не даёт вредоносному промпту или выводу инструмента переписать вашу конфигурацию хуков во время сессии. Применяйте изменения в новой сессии.

На практике: всегда проверяйте и заключайте входные данные в кавычки (извлекайте через jq; переменные без кавычек могут превратиться в лишние аргументы или синтаксис оболочки), используйте абсолютные пути и ${CLAUDE_PROJECT_DIR}, не трогайте чувствительные файлы вроде .env или .ssh и никогда не делайте eval вывода инструмента. Хуки запускаются без управляющего терминала (нет /dev/tty). В организациях администраторы могут ограничить хуки через allowManagedHooksOnly.

Итоги

Хуки Claude Code — это определяемые пользователем shell-команды, которые автоматически запускаются в ключевых точках жизненного цикла, делая «это должно происходить всегда» реальным и детерминированным, не завися от усмотрения модели. Классические события — это девять: SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Notification / Stop / SubagentStop / SessionEnd / PreCompact (PreToolUse и другие могут блокировать — останавливая правки защищённых файлов или опасные команды). Настраиваете вы их в settings.json под "hooks" как событие → matcher → type + command.

Ввод/вывод — это JSON на stdin, код выхода 0 (успех) / 2 (блок) или структурированный JSON на stdout. Принцип: «можно ужесточать, но не ослаблять ограничения» (deny всегда побеждает). Классические сценарии: автоформат, защита файлов, остановка опасных команд, повторное внедрение контекста, аудит, тесты перед остановкой. Но поскольку они выполняют произвольный код, будьте строги в том, чтобы доверять только безопасным хукам и проверять/заключать в кавычки входные данные, и понимайте, что конфигурация фиксируется при запуске. По теме: плагины, MCP, ошибки Claude Code.

FAQ

Q. Для чего нужны хуки?
A. Они детерминированно автоматизируют «это должно происходить всегда». Такие вещи, как «форматировать после правок», «никогда не давать переписывать защищённые файлы», «остановить опасный rm -rf» и «пройти тесты перед остановкой», наверняка запускаются харнессом, не полагаясь на усмотрение ИИ. Хук — это shell-команда, запускаемая в ключевых точках жизненного цикла, настраиваемая в settings.json.

Q. Какие есть события (моменты)?
A. Классических — девять: SessionStart (начало), UserPromptSubmit (при отправке), PreToolUse (прямо перед инструментом), PostToolUse (после инструмента), Notification, Stop (конец ответа), SubagentStop, SessionEnd (завершение), PreCompact (перед уплотнением). Из них PreToolUse, UserPromptSubmit, Stop, PreCompact и другие могут блокировать и остановить действие. Релиз 2026 года добавляет ещё много событий, но имена могут меняться между версиями, поэтому проверяйте актуальность в официальной документации.

Q. Можно ли остановить правки защищённых файлов или опасные команды?
A. Да — с помощью хука PreToolUse. Скрипт проверяет путь к файлу или команду в tool_input, и если совпадает с .env, rm -rf и т. п., возвращает код выхода 2 (или JSON с permissionDecision:"deny"), чтобы заблокировать. Важно, что deny всегда имеет приоритет и останавливает даже при bypassPermissions. Хуки работают только в направлении «ужесточения ограничений».

Q. Я изменил конфигурацию, но она не вступает в силу.
A. Это по замыслу (защитная функция). Конфигурация хуков фиксируется как снимок при старте сессии, поэтому изменения в середине сессии не применяются. Это не даёт вредоносному промпту или выводу инструмента незаметно переписать вашу конфигурацию хуков. Запустите новую сессию, чтобы применить. Учтите, что /hooks — это список только для чтения; добавляйте или меняйте хуки, редактируя settings.json напрямую.

Q. Безопасны ли хуки?
A. Не безусловно. Хуки выполняют произвольные shell-команды с вашими правами, поэтому документация говорит «используйте на свой риск». Настраивайте только хуки, которым доверяете, проверяйте и заключайте входные данные в кавычки через jq, используйте абсолютные пути и не трогайте .env / .ssh и никогда не делайте eval вывода инструмента. В организациях администраторы могут ограничить хуки через allowManagedHooksOnly.