Хуки Claude Code - это команды, которые среда запускает сама в заданный момент: перед вызовом инструмента, после правки файла, когда агент закончил ответ. Правило из CLAUDE.md агент читает и может не выполнить. Хук на событии «перед командой» проверяет каждую команду и останавливает запрещённую до того, как она выполнится, в любом режиме разрешений. Поэтому в хук переносят правила, нарушение которых трудно откатить.
Почему агент нарушает правило из CLAUDE.md?
Файл-память хорош для всего, что требует понимания: как называть файлы, где лежат материалы, что проверить перед сдачей. Подробнее о том, что писать в CLAUDE.md - в отдельном разборе. У файла есть предел. Это инструкция, которую агент учитывает вместе со всем остальным контекстом, и на сотой команде длинной сессии она может проиграть текущей задаче.
Вот как это выглядело у меня. 15 сентября я ввёл правило: при отправке кода на сервер агент увозит только коммиты своего чата, а коммиты соседних окон не трогает. Правило стояло в CLAUDE.md и в скилле завершения сессии. 16 сентября агент напечатал список того, что уедет, и следом выполнил push, не сверившись с этим списком. На сервер ушли два чужих коммита.
Текст в CLAUDE.md и скилле правило не удержал. 18 сентября его стал проверять хук.
На практике это значит: push, удаление, отправка данных наружу либо необратимы, либо дорого откатываются. Для них мало того, что агент обычно помнит правило. Почему параллельные окна вообще сталкиваются в одной папке, есть в статье про два окна агента.
Хук простыми словами: событие, фильтр, команда
Хуки живут в файле настроек Claude Code. Личный ~/.claude/settings.json действует во всех твоих проектах на этом компьютере. Файл .claude/settings.json в папке проекта работает только в ней и уезжает в репозиторий вместе с кодом, то есть достаётся всем, кто откроет проект.
Запись выглядит так:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "$HOME/.claude/hooks/stop-force-push.sh" }
]
}
]
}
}В ней три решения. PreToolUse - событие «до вызова инструмента». Bash - фильтр: хук срабатывает только на команды терминала, правки файлов и поиск идут мимо. Последняя строка - путь к скрипту, который получит описание команды.
Когда событие наступает, Claude Code передаёт скрипту JSON: какое событие, какой инструмент, с какими аргументами. Для команды терминала там лежит её полный текст. Скрипт его читает и отвечает кодом выхода. Код 0 означает «возражений нет», и дальше команда идёт обычным порядком разрешений. Код 2 означает «стоп»: команда не выполняется, а текст из потока ошибок уходит агенту как объяснение, почему.
Писать скрипт руками не обязательно. Документация прямо предлагает описать агенту, что нужно, и попросить его собрать хук. Твоя часть - сформулировать правило и проверить готовый хук до того, как ему довериться. ИИ-агент пишет скрипт за минуту, проверка занимает ещё пять.
Как хук останавливает опасную команду?
Обезличенный пример: хук, который не даёт агенту перезаписать историю на сервере командой push с принудительной перезаписью.
#!/bin/bash
# Хук PreToolUse (пример): ловит push с перезаписью истории в распространённых формах
command -v jq >/dev/null || { echo "Хук не может проверить команду: нет jq" >&2; exit 2; }
CMD=$(jq -r '.tool_input.command // ""')
# есть ли в команде git push, в том числе git -C <папка> push
echo "$CMD" | grep -qE '(^|[^[:alnum:]_-])git([[:space:]]+-[^[:space:]]+([[:space:]]+[^-[:space:]][^[:space:]]*)?)*[[:space:]]+push([[:space:]]|$)' || exit 0
# флаги силы: --force и его варианты, короткие флаги с f (-f, -fu), ветка с плюсом (+main)
if echo "$CMD" | grep -qE '[[:space:]](--force[^[:space:]]*|-[a-zA-Z]*f[a-zA-Z]*|\+[^[:space:]]+)([[:space:]]|$)'; then
echo "Стоп: push с перезаписью истории запрещён. Сделай обычный push или спроси меня." >&2
exit 2
fi
exit 0Скрипт проверен 1 ноября 2026 года на 18 командах, поданных вручную, без подключения к агенту. Код 2 и текст «Стоп» получили git push --force origin main, git push origin main --force, git push -f, git push -fu origin main, git push origin +main, git -C /repo push --force origin main, git push --force-with-lease origin main и cd /repo && git push -f origin main. Обычные git push origin main, git push -u origin main, git push origin feature-fix и ls -la прошли с кодом 0.
Это пример, а не защита. Хук читает текст команды, поэтому не видит того, чего в тексте нет. Проверено: git pf, если так назван псевдоним для force push, и bash ./deploy.sh с push внутри скрипта проходят с кодом 0. Страховка, которая от текста команды не зависит, - защита ветки на стороне сервера: по документации GitHub правило защиты ветки по умолчанию запрещает в неё force push. Хук ловит ошибку агента раньше и объясняет ему, что не так, а сервер держит то, что хук пропустил.
Третья строка скрипта отвечает на вопрос, что делать, если проверить нечем. Скрипт читает JSON утилитой jq. Если её нет, он не пропускает команду молча, а останавливает с объяснением. Этот случай тоже проверен: с пустым списком путей поиска программ скрипт вернул код 2.
Главное свойство такого хука: запрет на PreToolUse действует в каждом режиме разрешений, включая режим без подтверждений и запуск с флагом --dangerously-skip-permissions. Хук срабатывает раньше, чем Claude Code смотрит на режим.
Это видно и в живой работе. Агент в моей рабочей сессии работал без подтверждений. Когда он попытался одной командой рекурсивно удалить свою черновую папку, мой хук-сторож остановил её с объяснением: массовое удаление требует явного подтверждения. Агенту пришлось завести новую папку вместо чистки старой.
События: до команды, после правки, в конце ответа
Событий в документации больше тридцати, в ежедневной работе хватает четырёх. Так они распределены у меня:
| Событие | Когда срабатывает | Может остановить | Что на нём у меня |
|---|---|---|---|
| PreToolUse | перед вызовом инструмента | да | два хука на команды терминала: сторож секретов и проверка push |
| PostToolUse | после успешного вызова | нет, действие уже выполнено | сверка каталога правил и пересборка файла правил для второго агента |
| Stop | агент закончил ответ | может не дать агенту остановиться | звук |
| PermissionRequest | агент спрашивает разрешение | может отклонить запрос ответом deny в объекте решения, код 2 здесь не работает | звук |
| Notification | агент ждёт ответа | нет | звук |
Сторож секретов останавливает команды терминала, которые читают файлы с ключами, массово удаляют или отправляют данные наружу. Конкретные шаблоны, по которым он это узнаёт, остаются в моём файле. Проверка push перед каждой отправкой сверяет список коммитов, которые уедут на сервер, с коммитами этого чата и пускает push, только если чужих в списке нет.
PostToolUse полезен там, где после каждого изменения нужен порядок. В моей рабочей папке два агента, и у каждого свой файл правил. Хук после каждой правки собирает файл второго агента из первого, поэтому они не расходятся. Чем эти файлы отличаются, разобрано в статье AGENTS.md и правила для агента.
Звуковые хуки - самый простой вход в тему. На курсе по ИИ-агентам их ставят в первом модуле: звук, когда агент закончил задачу, и звук, когда он ждёт разрешения. Запреты на чтение файлов с ключами и на удаление папок там настраиваются следующим шагом, через правила разрешений. Если хочется пройти эти шаги на своём рабочем месте агента под присмотром, от звуковых хуков до правил разрешений, это программа обучения работе с ИИ-агентами.
Что будет, если хук сломается?
Это неочевидное место. Документация описывает его так: если хук завершился кодом, отличным от 0 и 2, не смог запуститься или вывел некорректный JSON, это неблокирующая ошибка, и действие выполняется. Хук-запрет с опечаткой в пути к скрипту молча пропускает всё подряд. То же с таймаутом: зависший PreToolUse вызов не блокирует.
Три способа закрыть эту дыру:
Сбой внутри скрипта ведёт к запрету
Предусмотри в скрипте ситуации, где проверить нельзя, и отвечай на них запретом, как пример выше без jq. У меня проверка push при любой собственной ошибке отправку не пускает, а сторож секретов отвечает запретом, если на компьютере нет jq.Поле onFailure
В свежих версиях у хука есть поле"onFailure": "block": если хук упал или не запустился, действие блокируется. По документации оно работает с версии 2.1.295. Свою версию покажет командаclaude --version.Первый запуск под присмотром
Документация советует при первом прогоне хука-политики следить за уведомлениемhook errorв транскрипте: опечатка в пути к скрипту означает, что хук не запускается вообще.
Как проверить, что хук работает?
Первая проверка делается до подключения, как в примере выше:
echo '{"tool_input":{"command":"git push -f"}}' | ./stop-force-push.sh; echo $?На запрещённой команде ждёшь 2, на обычной 0.
Вторая проверка - после подключения. Команда /hooks в Claude Code показывает все хуки по событиям. Если твоего там нет, проверь, что JSON в файле настроек правильный: лишняя запятая или комментарий его ломают. Сочетание Ctrl+O открывает транскрипт, где видно, сработал ли хук и что он ответил.
Третья - журнал. Моя проверка push пишет строку на каждое решение: репозиторий, ветка, сколько чужих коммитов нашлось и сколько коммитов разрешено явно. Чужим хук считает коммит, который уедет на сервер, но не создан в этом чате и не является копией своего.
С 18 сентября по 31 октября хук сделал 580 проверок push в рабочих репозиториях. В 100 из них в списке нашлись чужие коммиты, и push не пошёл. Ещё около 1300 строк журнала - проверки во временных копиях репозиториев: приёмка самого хука и отправки из чистых клонов.
Приёмка нашла дыру, которую автор хука не видел. Хук сверяет то, что уедет, по состоянию до команды. Если в одной команде с push стояла другая git-команда, которая меняет ветку, хук её результата не видел, и чужой коммит проскакивал. Теперь такие связки он не пускает: сначала одна команда, push следующей. Отчёт агента «хук настроен» этого не показал бы, показал только прогон. Как принимать работу агента по факту, есть в статье агент отчитался, а результата нет.
Границы: что оставить файлу и правилам разрешений
Перед тем как писать хук, задай себе два вопроса. Можно ли проверить правило по тексту команды или файла, не вникая в смысл? Дорого ли его нарушение? Если оба ответа «да», это хук. «Не пушь с --force» проверяется по тексту команды, с оговоркой из примера выше: псевдонимы и скрипты такой проверке не видны. «Пиши понятно для клиента» так не проверить, это остаётся файлу-памяти.
Для запретов вида «не читай этот файл» и «спрашивай перед удалением» в том же файле настроек есть правила разрешений. Они проще хука, но правка файла настроек сама по себе может уронить агента. Как вносить такие правки безопасно, разобрано в статье агент настроил себе защиту и перестал запускаться.
Для правил, где нужна оценка, документация описывает хуки с типом prompt: решение по действию принимает модель Claude. Это уже не детерминированная проверка, это вторая модель, которая смотрит на действие первой.
И последнее. Документация предупреждает, что хук выполняет команды с полными правами твоей учётной записи и может изменить, удалить или прочитать любой доступный тебе файл. Хук из чужого репозитория или плагина - это чужой код на твоём компьютере, читай его до подключения.
Частые вопросы
Частые вопросы
Главный вывод
Хук - узкая проверка на конкретном событии, которая не устаёт к концу сессии и не отвлекается на задачу. Поэтому он и держит то, что файл-память удержать не смог. Взамен он требует трёх вещей: при сбое запрещать, пройти ручной прогон до того, как ему доверятся, и честно знать свои слепые места. Для самого дорогого, вроде перезаписи истории на сервере, рядом нужна защита на стороне сервера.
Начать можно с одного хука на одно правило, которое агент уже нарушал. Описать его агенту, получить скрипт, прогнать вручную на двух командах, подключить и найти в /hooks.
Вспомни правило из своего CLAUDE.md, которое агент уже нарушал: его можно проверить по тексту команды или нет?
Источники
- Автоматизация действий с помощью hooks - руководство Claude Code
- Справочник по hooks: события, коды выхода, поле onFailure - документация Claude Code
- Файлы параметров Claude Code и их приоритет
- Как Claude запоминает проект: файлы CLAUDE.md - документация Claude Code
- About protected branches: правила защиты веток и запрет force push - документация GitHub
