Что такое хук в ИИ-агенте — правило, которое модель не может проигнорировать

Ты пишешь агенту в правилах: «никогда не запускай rm -rf». Крупно, капсом, три восклицательных знака.
А он однажды всё равно запускает. Не со зла. Просто правило — это текст, а текст модель может недочитать, забыть после сжатия контекста или решить, что «тут можно».
Смотри, у агентов есть штука, которая работает по-другому. Не просьба, а турникет. Называется хук.
Что такое хук
Хук — это твой скрипт, который агент обязан запустить в определённый момент своей работы. Перед командой. После правки файла. Когда закончил ответ.
Главное отличие от правил: хук запускает не модель, а сама программа-агент. Модель не решает, выполнять его или нет. Она даже не может «забыть».
Простая аналогия. Правило в AGENTS.md — это табличка «не входить». Хук — это дверь с замком. Табличку можно не заметить. Сквозь замок не пройдёшь.
Как это работает
Разберём на Claude Code — там хуки устроены нагляднее всего.
1. Событие
Агент работает по шагам. У каждого шага есть имя-событие. Самые полезные для старта:
- PreToolUse — перед тем как агент вызовет инструмент: запустит команду, изменит файл.
- PostToolUse — сразу после того, как инструмент отработал.
- Stop — когда агент закончил ответ.
- SessionStart — при старте сессии.
Всего событий больше тридцати, но эти четыре закрывают почти всё, что нужно новичку.
2. Настройка
Хуки прописывают в файле настроек. Для одного проекта — .claude/settings.json, для всех проектов — ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": ".claude/hooks/no-rm.sh" }
]
}
]
}
}
Читается так: «перед каждым вызовом инструмента Bash запусти мой скрипт». Поле matcher выбирает инструменты. Edit|Write — сразу два. Пустое или * — все.
3. Скрипт получает данные и отвечает кодом
Агент передаёт скрипту описание шага в формате JSON — через стандартный ввод. Там есть имя инструмента и его параметры. Например, сама команда лежит в tool_input.command.
А дальше скрипт отвечает кодом выхода:
#!/bin/bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -q 'rm -rf'; then
echo "rm -rf запрещён в этом проекте" >&2
exit 2
fi
exit 0
Код 2 — блок. Команда не выполнится. А текст из stderr агент передаст модели как причину. Модель увидит «rm -rf запрещён» и поищет другой путь.
Где подвох
Тут есть деталь, о которую спотыкаются почти все.
exit 0 — это не «разрешаю». Если скрипт молча вышел с нулём, агент просто идёт дальше обычным путём. Если команде нужно твоё разрешение — он всё равно спросит. Хук может запретить, но молчанием он ничего не одобряет.
Вторая деталь — про безопасность. Хук — это обычная команда в терминале. Она работает с твоими правами: видит твои файлы, ключи, сеть.
Значит, чужой репозиторий с файлом .claude/settings.json может принести с собой чужие хуки. В обычном режиме Claude Code в новой папке сначала спрашивает, доверяешь ли ты ей. А вот при запуске без интерфейса, через claude -p, такого вопроса нет — хуки проекта запустятся сразу. Флаг --bare отключает их загрузку полностью.
Правило простое: перед работой с незнакомым проектом загляни в его .claude/settings.json.
Зачем это тебе
Хуки — это способ перестать повторять агенту одно и то же. Три рецепта, которые окупаются в первый же день:
- Автоформат после правки. PostToolUse с матчером
Edit|Writeзапускает Prettier или Black. Агент больше никогда не оставит код с кривыми отступами — даже если «забыл». - Запрет на опасное. PreToolUse на Bash режет
rm -rf,git push --force, обращения к боевой базе. Это дополняет, а не заменяет вопросы агента перед действием. - Уведомление «готово». Stop-хук пищит или шлёт сообщение в Telegram, когда агент закончил. Можно спокойно уйти пить чай.
Частые вопросы
Хук тратит токены?
Сам по себе нет: скрипт работает на твоём компьютере, без модели. Токены уходят, только если хук возвращает текст, который агент передаёт модели, — как причину блокировки.
Есть ли хуки в других агентах, кроме Claude Code?
Похожие механизмы есть у Cursor, Codex и других, но события и формат настроек везде свои. Идея одна: программа запускает твой скрипт на шаге агента.
Что будет, если скрипт хука упадёт с ошибкой?
Любой код, кроме 0 и 2, агент считает сбоем самого хука: показывает ошибку, а действие всё равно выполняется. Даже привычный exit 1 — не блок. Чтобы запретить, нужен именно exit 2.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





