Хуки Claude Code: гид продвинутого пользователя по автоматизации агента

Хуки Claude Code — это пользовательские команды, которые автоматически запускаются в определённых точках жизненного цикла Claude Code — перед вызовом инструмента, после редактирования, при старте сессии, при завершении Claude очередного шага — так что вы можете проверять, форматировать, логировать или блокировать действия без необходимости постоянно находиться в цикле. Это разница между AI-агентом для написания кода, который предлагает, и агентом, который детерминированно следует вашим правилам. В этом руководстве объясняется, что такое хуки, на какие события они могут срабатывать, как их настраивать, приведены пять практических рецептов, которые можно скопировать, рассказано о ловушке с кодом выхода, в которую попадают все, и о том, как использовать всю мощь Claude Code без локальной настройки.

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

Хук — это обработчик: shell-команда, HTTP-эндпоинт, вызов инструмента MCP или даже промпт модели, — который Claude Code запускает автоматически при возникновении определённого события. Обработчик получает структурированные входные данные (через stdin для командных хуков или как POST-тело для HTTP-хуков), может анализировать происходящее, выполнять действие и опционально возвращать решение, которое меняет дальнейшие действия Claude.

Именно эта последняя возможность делает хуки мощным инструментом, а не просто удобным. Хук — это не только уведомление — он может блокировать вызов инструмента, перезаписывать входные или выходные данные инструмента, добавлять дополнительный контекст или полностью останавливать Claude. Иными словами, хуки превращают Claude Code из умного ассистента в программируемый инструмент, который детерминированно применяет ограничения вашей команды, а не только тогда, когда модель случайно вспоминает о них.

Когда срабатывают хуки: жизненный цикл

Хуки привязываются к событиям, и Claude Code предоставляет их немало. Они группируются по частоте: некоторые срабатывают один раз за сессию, некоторые — раз за шаг, а некоторые — при каждом вызове инструмента.

Где срабатывают хуки в течение сессии Claude Code — от SessionStart до SessionEnd.

Наиболее часто используемые события:

• SessionStart / SessionEnd — один раз при начале или завершении сессии. Отлично подходит для загрузки контекста (открытые задачи, информация о ветке, переменные окружения) или для очистки.
• UserPromptSubmit — срабатывает при отправке промпта, до того как Claude начнёт его обрабатывать. Можно фильтровать или дополнять промпт.
• PreToolUse — перед любым вызовом инструмента. Здесь вы блокируете опасные действия.
• PostToolUse (и PostToolUseFailure) — после успешного (или неудачного) вызова инструмента. Место для линтинга, форматирования и проверки.
• Stop / StopFailure — когда Claude завершает ответ или шаг заканчивается с ошибкой.
• Notification — когда Claude Code выдаёт уведомление (полезно для десктопных алертов).

Помимо этого, Claude Code также вызывает хуки для сабагентов (SubagentStart/SubagentStop), задач (TaskCreated/TaskCompleted), сжатия контекста (PreCompact/PostCompact), изменений рабочей директории (CwdChanged), изменений файлов на диске (FileChanged), загрузки инструкций (InstructionsLoaded) и других. Суть именно в широте охвата: почти в любой момент цикла работы агента можно прикрепить свою политику.

Пять типов обработчиков хуков

Событие хука может запускать пять разных типов обработчиков, что делает систему гибкой:

1. command — запускает shell-команду; читает входные данные через stdin, передаёт решения через код выхода и stdout.
2. http — отправляет JSON события по URL через POST и читает JSON-ответ.
3. mcp_tool — вызывает инструмент на подключённом MCP-сервере.
4. prompt — однопроходная оценка моделью, возвращающая JSON-решение да/нет (полезно для нечётких проверок).
5. agent — запускает сабагента (экспериментальная функция).

Для большинства команд хуки типа command выполняют 90% всей работы — shell-скрипта достаточно, чтобы линтить, блокировать или логировать.

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

Хуки находятся в файлах настроек (официальная документация Claude Code по хукам — каноничный источник), и место, куда вы их помещаете, определяет их область действия:

Структура состоит из трёх уровней вложенности: выбираете событие, добавляете группу matcher, затем определяете обработчики. Matcher-ы определяют, к каким вызовам инструментов применяется хук — "*" (или его отсутствие) соответствует всему, простое Edit|Write соответствует именно этим инструментам, а всё более сложное трактуется как регулярное выражение. (Инструменты MCP соответствуют шаблону mcp__<server>__<tool>.)

Вот хук PostToolUse, который запускает проверку линтером после каждого редактирования:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/path/to/lint-check.sh" }]
      }
    ]
  }
}

Пять практических рецептов хуков

Это паттерны, к которым команды обращаются первыми:

1. Линтинг или форматирование после каждого редактирования. Хук PostToolUse, привязанный к Edit|Write, который запускает ваш форматтер или линтер, чтобы код агента всегда соответствовал стилевым правилам.
2. Блокировка деструктивных команд. Хук PreToolUse, привязанный к Bash, который анализирует команду и блокирует rm -rf и подобные ей до того, как они выполнятся.
3. Десктопные уведомления. Хук Notification, который уведомляет вас, когда Claude нужно внимание или когда завершена долгая задача.
4. Аудит-логирование. Хук PostToolUse (или ориентированный на MCP), который логирует каждый вызов инструмента для целей соответствия требованиям — что было запущено, когда и с какими аргументами.
5. Загрузка контекста проекта при старте. Хук SessionStart, который подгружает открытые задачи, текущую ветку или переменные окружения, чтобы агент начинал каждую сессию уже ориентированным в контексте.

Пять распространённых рецептов хуков и события, к которым они привязаны.

Ловушка с кодом выхода

Это деталь, в которую попадают все, поэтому запомните её: для хуков типа command только код выхода 2 блокирует действие. Выход 0 означает успех (при этом stdout парсится на предмет любого JSON-решения). Выход 2 — это блокирующая ошибка — её stderr передаётся обратно Claude. Любой другой код, включая выход 1, является неблокирующей ошибкой — Claude продолжает работу.

Так что если вы напишете хук "заблокировать это" и сделаете exit 1, он не заблокирует действие — оно продолжится. Чтобы действительно применить политику через командный хук, нужно exit 2. (Командные хуки также могут возвращать более развёрнутое управление в виде JSON на stdout — permissionDecision: "deny" для PreToolUse, updatedInput для перезаписи аргументов, additionalContext для добавления информации и continue: false для полной остановки Claude.)

Разобранный пример: блокировка rm -rf

Давайте построим защиту от деструктивных команд от начала до конца, поскольку это показывает все составные части. Сначала конфигурация — хук PreToolUse, привязанный к Bash:

{ "hooks": { "PreToolUse": [{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh" }] }] } }

Затем сам скрипт, guard.sh. Claude Code отправляет событие в виде JSON через stdin, включая входные данные инструмента; скрипт считывает их, проверяет команду и принимает решение:

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
  echo "Blocked: destructive command refused by policy." >&2
  exit 2     # exit 2 blocks — exit 1 would NOT
fi
exit 0

Решающая строка — это exit 2. Вернёте 0 — команда выполнится; вернёте 1 — и, что противоинтуитивно, команда всё равно выполнится как неблокирующая ошибка; только exit 2 блокирует действие и передаёт ваше сообщение stderr обратно Claude, чтобы он понял причину. Сделайте скрипт исполняемым, закоммитьте его в .claude/hooks/, и теперь каждый вызов Bash проходит через вашу защиту — для всей вашей команды, поскольку проектный settings.json можно распространять совместно. Для жёсткой гарантии, а не решения "по лучшим усилиям", сочетайте это с правилами разрешений Claude Code; а как детерминированная, версионируемая защитная сетка этот хук уже выполняет свою задачу.

Когда хуки — не решение

Хуки предназначены для детерминированной, повторяемой политики — "всегда линтить после редактирования", "никогда не запускать rm -rf". Это неподходящий инструмент для задач, требующих суждения (используйте модель или хук prompt для нечётких проверок), и для жёстких гарантий безопасности (используйте систему разрешений, поскольку фильтры if в командных хуках не срабатывают надёжно при ошибке). Не переусердствуйте с хуками: каждый командный хук запускает процесс с таймаутом, и целая куча медленных хуков добавляет задержку к каждому вызову инструмента. Держите их быстрыми, немногочисленными и сосредоточенными на правилах, которые действительно важны.

Заметки о безопасности, которые стоит знать

Несколько особенностей, о которых документация говорит явно:

• Фильтр if не срабатывает надёжно при ошибке. Если вы используете поле if, чтобы привязать хук к правилу разрешений, и команду не удаётся разобрать, хук всё равно выполнится. Для жёсткого применения правил разрешения/запрета используйте систему разрешений Claude Code, а не хуки.
• Хуки выполняются без управляющего терминала — они не могут выводить запросы через /dev/tty. Используйте systemMessage или ограниченный вывод terminalSequence для сообщений, обращённых к пользователю.
• Stdout должен быть чистым. На stdout должен быть только объект JSON-решения; случайный вывод из shell-профиля может нарушить парсинг.
• Осторожно относитесь к внедряемому контексту. additionalContext следует писать как фактические утверждения, а не как императивные команды, чтобы это хорошо сочеталось с защитой от prompt-injection.

Хуки — это инженерия харнесса в миниатюре

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

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

Использование всей мощи Claude Code без локальной настройки

Хуки живут в CLI Claude Code, а значит, вам нужно установить и настроить его, чтобы их использовать, — это барьер для тех, кто не работает в терминале, и вовсе непреодолимое препятствие для не-разработчиков в команде. Если вы хотите получить возможности агента Claude Code без управления локальной установкой, вы можете запустить Claude Code в браузере на Happycapy: он запускает Claude Code в управляемой облачной песочнице, где харнесс — цикл работы, инструменты, память и изоляция, к которым подключаются хуки — уже настроен за вас. Вы описываете задачу и наблюдаете, как агент работает на визуальном рабочем столе, без необходимости открывать терминал.

Можно думать об этом так: хуки позволяют опытным пользователям вручную настраивать харнесс Claude Code; Happycapy же даёт каждому управляемый харнесс "из коробки". Если вы хотели заставить Claude Code работать на вас, но настройка CLI вас остановила, начните бесплатно на happycapy.ai и выполните настоящую задачу в браузере уже сегодня.

Часто задаваемые вопросы

Вопрос: Что такое хуки Claude Code?

Это пользовательские обработчики — shell-команды, HTTP-эндпоинты, вызовы инструментов MCP или промпты модели, — которые Claude Code автоматически запускает при событиях жизненного цикла, таких как перед вызовом инструмента (PreToolUse), после редактирования (PostToolUse) или при старте сессии. Они могут проверять, форматировать, логировать, блокировать или перезаписывать действия.

Вопрос: Какие события хуков поддерживает Claude Code?

Многие — включая SessionStart/SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse (и PostToolUseFailure), Stop/StopFailure, Notification, события сабагентов и задач, а также события сжатия контекста. Они срабатывают один раз за сессию, один раз за шаг или при каждом вызове инструмента.

Вопрос: Как заставить хук блокировать вызов инструмента?

Для командных хуков завершайтесь с кодом 2 — только выход 2 блокирует действие (выход 1 не блокирует). Для PreToolUse можно также вернуть JSON с permissionDecision: "deny". Для жёсткого применения предпочитайте систему разрешений Claude Code, поскольку фильтр if хука не срабатывает надёжно при ошибке.

Вопрос: Где настраиваются хуки Claude Code?

В файлах настроек: ~/.claude/settings.json (все проекты), .claude/settings.json (один проект, можно распространять), или .claude/settings.local.json (только локально). Вы выбираете событие, добавляете matcher и определяете обработчики.

Вопрос: Могу ли я использовать хуки Claude Code без установки CLI?

Сами хуки требуют CLI Claude Code. Если ваша цель — использовать Claude Code без локальной настройки, запустите его в управляемой браузерной песочнице, такой как Happycapy, которая предоставляет готового агента и его харнесс — идеальный вариант, когда вы не хотите самостоятельно устанавливать и настраивать CLI.

Вопрос: Какой хук лучше добавить первым?

Линтер PostToolUse, привязанный к Edit|Write — он запускает ваш форматтер после каждого изменения кода, чтобы вывод агента всегда соответствовал стилевым правилам. Это низкорисковый и сразу же полезный хук.

Похожие статьи

• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?