Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Хуки жизненного цикла

Статус: действует
Область: текущее состояние
Последняя проверка: 2026-08-23 Владелец: среда выполнения ax-code

Хуки жизненного цикла позволяют запускать команды оболочки на событиях агента без пересборки среды выполнения. Они дополняют правила прав и песочницу изоляции: хуки — детерминированные побочные эффекты («всегда форматировать», «никогда не делать force-push»), а промпты остаются рекомендацией.

События

Событие	Когда	Может блокировать?
PreToolUse	До выполнения инструмента	Да (`blockOnFailure: true`)
PostToolUse	После завершения инструмента (`args`: аргументы инструмента). Ограниченный stdout или структурированная обратная связь добавляется к результату инструмента, который видит модель; см. ниже	Нет
PostToolUseFailure	После исключения инструмента (`args`: `{ args, error }`, текст ошибки обрезан до 4 000 символов). Отправил и забыл; ошибка всё равно доходит до модели без изменений	Нет
Stop	Когда ход сеанса завершается (пакеты могут запускаться при остановке через автоматизацию)	Нет
UserPromptSubmit	Когда отправлен промпт пользователя, до сохранения сообщения	Да (`blockOnFailure: true`)
PreCompact	До запуска сжатия сеанса (`args`: `{ auto, overflow }`)	Нет
SubagentStop	Когда субагент `task` заканчивает (`args`: `{ agent, status }`)	Нет
SessionStart	Когда создаётся сеанс верхнего уровня (`args`: `{ sessionID, title, time }`)	Нет
SessionEnd	Когда сеанс удаляют или архивируют (`args`: `{ sessionID, reason }`, `reason` равен `"remove"` или `"archive"`)	Нет
PostCompact	После успешного сжатия сеанса (`args`: `{ sessionID, reason }`, `reason` равен `"auto"` или `"manual"`; не срабатывает, если сжатие прерывается, например при переполнении контекста)	Нет
Interrupt	Когда пользователь или оператор явно отменяет идущий ход (`args`: `{ sessionID }`; не срабатывает при обычном завершении хода или внутренней очистке)	Нет

Четыре события жизненного цикла сеанса (SessionStart, SessionEnd, PostCompact, Interrupt) и PostToolUseFailure только наблюдают: они срабатывают и забываются, никогда не блокируют путь жизненного цикла, а их нагрузки несут только идентификаторы, причины и метки времени — никогда текст разговора, сводки или вывод инструментов. Сеансы субагентов не вызывают SessionStart (они уже видны через SubagentStop). SubagentStop срабатывает для потомков, запущенных и task, и task_parallel.

Обратная связь PostToolUse доходит до модели

Хук PostToolUse может вернуть текст модели. Он добавляется к результату инструмента внутри блока <hook_feedback event="PostToolUse">, после собственного вывода инструмента. Он не заменяет вывод и не блокирует.

Устаревшие записи (без protocol): обрезанный stdout хука, завершившегося с кодом 0.
Записи protocol: "claude-code": hookSpecificOutput.additionalContext, reason вердикта {"decision": "block", "reason": "..."} или stderr, когда хук завершается с кодом 2. Другие ненулевые коды ничего не добавляют.

Обратная связь ограничена 4 000 символов на хук и 8 000 символов на вызов инструмента, чтобы шумный хук не затопил контекст. Поэтому пакет format-after-edit полезен: его напоминание теперь попадает в следующий ход модели, а не только в журнал.

Эти имена соответствуют внутренним триггерам плагинов AX Code (tool.execute.before / tool.execute.after) плюс хукам промпта, сжатия, субагента и остановки на уровне сеанса. Синтетические промпты продолжения (внутренние промпты agentRouting: "preserve") не вызывают UserPromptSubmit.

Включение пакетов

Хуки и плагины проекта выполняют код под контролем репозитория, поэтому .ax-code/hooks.json, .ax-code/plugin/ и плагины, настроенные проектом, по умолчанию выключены. После рецензии включите их вне репозитория при запуске AX Code:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Затем создайте .ax-code/hooks.json в проекте:

{
  "packs": ["format-after-edit", "block-force-push", "require-tests-on-stop", "protect-env-files", "log-bash-commands"]
}

Официальные пакеты (≥5)

Пакет	События	Описание
`format-after-edit`	PostToolUse	Напоминает агенту форматировать после правок
`block-force-push`	PreToolUse	Блокирует `git push --force` / `-f`
`require-tests-on-stop`	Stop	Напоминает проверить после изменений
`protect-env-files`	PreToolUse	Предупреждает, когда инструменты касаются `.env`
`log-bash-commands`	PreToolUse	Журналирует команды bash для аудита

Пользовательские хуки:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "echo running bash",
      "blockOnFailure": false
    }
  ]
}

Проводной протокол Claude Code (включается явно)

Если у вас уже есть хуки, написанные для Claude Code, запись может включить проводной протокол Claude Code через "protocol": "claude-code":

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "my-claude-code-hook.sh",
      "protocol": "claude-code"
    }
  ]
}

Для блокируемых событий (PreToolUse, UserPromptSubmit) включённые записи разбираются по семантике Claude Code вместо проверки blockOnFailure:

Код 2 блокирует действие. Stderr хука показывается как причина. Повреждённый stdout тоже блокирует (безопасный отказ).
Код 0 со stdout JSON {"permissionDecision": "allow"|"deny"|"ask", "reason"?}: allow продолжает; deny блокирует с reason; ask ставит вызов инструмента на паузу на интерактивном запросе права hook, который показывает причину (по умолчанию "hook requested user confirmation"). Запрос только интерактивный: ни правило always, ни шаблонное разрешение, ни автоодобрение автономного режима не могут на него ответить, а неинтерактивный прогон его отвергает, и модель видит это как обычный отказ в праве. Более поздний хук, который отвечает deny, побеждает более ранний ask. У UserPromptSubmit нет вызова инструмента, к которому прикрепить запрос, поэтому ask там всё ещё блокирует. Вложенная форма Claude Code {"hookSpecificOutput": {"permissionDecision": "...", "permissionDecisionReason": "..."}} принимается как псевдоним.
Любой другой код — неблокирующая ошибка (записывается в журнал, действие продолжается).

События только для наблюдения полностью игнорируют декодер: они никогда не могут блокировать. Записи без поля protocol ведут себя точно как раньше.

Переменные окружения, доступные командам хуков:

HOOK_EVENT — PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit, PreCompact, SubagentStop, SessionStart, SessionEnd, PostCompact, Interrupt
HOOK_TOOL — идентификатор инструмента
HOOK_SESSION_ID
HOOK_ARGS_JSON — аргументы инструмента в JSON
HOOK_ARGS_STDIN=1 — полные аргументы JSON всегда доступны на stdin; HOOK_ARGS_JSON пуст для нагрузок больше 32 КиБ
HOOK_PACK — имя пакета, когда оно применимо

Дочерние процессы хуков наследуют очищенную версию окружения AX Code. AX Code сохраняет обычные переменные платформы и инструментов, но убирает имена, похожие на секреты, URL с учётными данными, помощников учётных данных вроде SSH_AUTH_SOCK и переменные внедрения в процесс вроде NODE_OPTIONS. Переменные протокола HOOK_* выше добавляются после очистки и всегда доступны.

Полностью доверенные устаревшие хуки, которым нужны окружающие учётные данные, могут вернуть прежнее поведение вне репозитория:

AX_CODE_HOOKS_FULL_ENV=1 AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Этот запасной люк открывает каждую переменную окружения каждому включённому хуку. Репозиторий не может запросить его через .ax-code/hooks.json. Используйте его только после рецензии всех хуков и пакетов.

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

Связь с изоляцией

Хуки не заменяют песочницу. Используйте:

Изоляцию приложения для переносимых границ записи и сети
Изоляцию ОС (сервер по умолчанию "auto") для песочницы bash, проводимой ядром, когда она доступна
Хуки для побочных эффектов политики и жёстких блокировок вроде force-push

См. режим песочницы и SECURITY.md.