Agentic Coding Hooks: детерминированные ограждения для AI-агентов

AI-агенты управляются через AGENTS.md, правила, skills и промпты — и в большинстве случаев они слушаются. Проблема в том, что «большинство случаев» — это вероятность, а не гарантия. Некоторые действия не должны происходить никогда, независимо от того, как модель интерпретирует ваши инструкции в конкретной сессии. Решение — agent hooks: детерминированные ограждения, которые исполняются средой выполнения, а не моделью.

Проблема: инструкции для AI-агентов вероятностны

Всё, что вы передаёте LLM-агенту через контекстное окно — конвенции в CLAUDE.md, skills, промпты — в конечном счёте является лишь рекомендацией. Они конкурируют за внимание модели, и соблюдение инструкций tends to drop as sessions grow longer (падает по мере удлинения сессий). Для стиля кода это приемлемо, но становится реальной проблемой, когда инструкция защищает что-то критичное: папку с секретами, production-конфигурацию или CI/CD-стандарт, от которого зависит вся команда.

Можно подумать, что решение — просто писать лучшие инструкции, и отчасти это так. Ран Айзенберг в своей статье Claude Code Best Practices аргументирует, что кодирование доменной экспертизы в контекст агента — одна из самых высокоэффективных вещей. Но даже лучшие инструкции не детерминированы. Для правил, которые должны соблюдаться всегда, хуки добавляют детерминизм, который промпты и skills обеспечить не могут.

Что такое Agent Hooks

Хуки — это определяемые пользователем обработчики (обычно shell-скрипты), которые среда выполнения агента автоматически запускает в определённых точках своего жизненного цикла. Ключевое отличие: модель не решает, выполнять ли ваш код. Решает среда выполнения. Хук — это обычный код, он выполняется одинаково каждый раз, что делает его детерминированным противовесом недетерминированной природе агента.

Хук может быть реализован тремя способами:

• Shell-скрипт — запускается локально, максимальный контроль и надёжность. Рекомендуемый вариант для guardrails.
• HTTP-эндпоинт — получает событие по сети, зависит от сетевого вызова, может упасть по таймауту.
• LLM-промпт — быстрая модель оценивает условие на естественном языке. Не детерминирован по природе.

Shell-скрипты — лучший выбор для критичных ограждений: они работают локально и дают полный контроль.

Жизненный цикл хуков в Claude Code

Claude Code запускает хуки на трёх уровнях:

1. События сессии — SessionStart, SessionEnd (один раз за сессию).
2. События хода — UserPromptSubmit при отправке промпта, Stop при завершении ответа.
3. События инструментов — PreToolUse перед выполнением инструмента, PostToolUse после успешного выполнения.

PreToolUse — основной инструмент для guardrails. Хук получает полный вызов инструмента в JSON на stdin, включая точную Bash-команду или путь к файлу, до выполнения. Хук может: разрешить вызов, запретить с объяснением, запросить разрешение у пользователя или переписать входные данные.

Два способа принять решение:

• exit 2 — жёсткая блокировка. stderr передаётся модели как причина отказа. Работает надёжно (fail-closed).
• exit 0 + JSON hookSpecificOutput — более выразительный путь: permissionDecision может быть allow, deny или ask. Минус: ошибка в JSON (например, stray line из shell profile на stdout) приводит к тому, что вызов проходит (fail-open).

Для критичных случаев, где команда не должна выполниться никогда, Ран рекомендует exit 2.

Уровни размещения хуков

Хуки могут находиться на трёх уровнях:

• Пользовательский (~/.claude) — персональные правила, machine-wide.
• Проектный (.claude/settings.json) — коммитится в репозиторий, разделяется всей командой.
• Управляемые политики — контролируются администраторами на уровне организации.

Уровень определяет область действия: персональная страховка — на пользовательском уровне, командный CI-стандарт — в репозитории, организационный guardrail — в managed settings.

Практические сценарии использования

Самый популярный хук в сообществе — PostToolUse, запускающий форматтер и линтер после каждого редактирования файла, чтобы вывод агента всегда был чистым.

Более критичные сценарии:

• Блокировка опасных команд — PreToolUse сопоставляет Bash-команды с паттернами и блокирует деструктивные: рекурсивное удаление, команды, затрагивающие инфраструктуру. Один разработчик опубликовал коллекцию safety-хуков после того, как Claude Code попытался выполнить rm -rf ~/.
• Защита секретов — хуки файлового доступа не пускают агента в .env-файлы, секреты и production-конфигурацию. Другой разработчик наблюдал, как его агент скопировал production-credentials в файл, который ушёл в GitHub.

Хуки — это код, защищайте settings-файлы

Хук — не пассивная настройка. Это код, который среда выполнения исполняет с вашими правами. SessionStart-хук запускается в момент открытия проекта, до того как вы что-то напечатаете. Кто контролирует settings-файл — контролирует то, что выполняется на вашей машине.

В апреле 2026 года PyPI-червь внедрил вредоносный SessionStart-хук в настройки репозитория — простое открытие проекта запускало вредоносный код. Всё, что может писать в settings-файл — от плохой зависимости до непроверенного PR — может подложить хук, который агент выполнит за вас.

Правила безопасности:

• Рассматривайте .claude/settings.json как CI-конфигурацию: ревьюьте каждое изменение в PR.
• Проверяйте папку .claude любого клонируемого репозитория перед открытием.
• Пользовательские настройки в ~/.claude несут тот же уровень риска для вашей машины.

Индустрия сходится на хуках

Claude Code выпустил хуки раньше конкурентов и до сих пор имеет самую глубокую реализацию (30 событий), но концепция быстро распространилась:

• Cursor представил хуки в версии 1.7 с событиями preToolUse, beforeReadFile и совместимостью с конфигурацией Claude Code.
• OpenAI Codex добавил экспериментальные хуки за feature flag с пятью событиями.
• Gemini CLI и GitHub Copilot CLI выпустили собственные hook-системы.
• Дизайн Claude Code — JSON на stdin и exit 2 для блокировки — стал стандартом де-факто.

Используйте хуки экономно

После всего прочитанного может возникнуть желание обернуть каждое действие агента в хук. Ран советует этого не делать: хуки выполняются внутри agent loop, и каждый подходящий вызов инструмента платит ценой запуска вашего скрипта.

Правило большого пальца: оставьте хуки для критических немногих — деструктивные команды, секреты и чувствительные пути, и один-два CI/CD-стандарта, которые должны соблюдаться всегда. Всё остальное belongs in prompts and skills (принадлежит промптам и skills), где случайный промах — это неприятность, а не катастрофа. Цель хука — не контролировать агента, а сделать несколько нежелательных исходов невозможными, чтобы агент мог двигаться быстро.