Хуки Claude Code: детерминированный контроль над действиями агента

Структура хука

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}

Три части: событие, условие сопоставления (регулярное выражение для имени инструмента в событиях инструментов; опустите его, чтобы обрабатывать всё) и одна или несколько команд. Команда получает через stdin объект JSON с описанием события — для событий инструментов он включает tool_name и tool_input, с помощью которого пример выше находит только что изменённый файл. Поместите его в .claude/settings.json , чтобы использовать совместно в репозитории, в ~/.claude/settings.json для личного использования, либо выполните /hooks и позвольте Claude Code записать его.

События

• PreToolUse — перед запуском инструмента. Единственное событие, которое может блокировать: код завершения 2 отменяет вызов, а Claude читает ваш stderr как объяснение причины.
• PostToolUse — после успешного выполнения инструмента. Форматирование, линтинг и проверка типов в изменённом файле.
• UserPromptSubmit — при отправке запроса; может добавлять контекст или отклонять запрос.
• Stop / SubagentStop — когда агент (или субагент) собирается завершить работу. Код завершения 2 здесь означает «ещё не закончено» — классический сценарий: запрет завершения работы, пока тесты не проходят.
• PreCompact — перед /compact; сохраните всё необходимое из полной истории диалога.
• SessionStart — при начале или возобновлении сессии; загрузка окружения, вывод напоминаний.
• Notification — когда Claude Code требуется ваше внимание (запрос разрешения, ожидание); подключите уведомления на рабочем столе или в Slack.

Блокировка опасных команд

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

Код завершения 2 задаёт поведение: вызов инструмента не выполняется, а всё, что хук вывел в stderr, становится объяснением, которое видит Claude, — так он может выбрать другой подход вместо повторения того же действия. Любой другой ненулевой код завершения записывается в журнал, но не блокирует вызов.

«Не завершай работу, пока тесты не пройдут»

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

Используйте вместе с ограничением --max-turns при запусках без интерфейса, чтобы ошибка, которую действительно невозможно исправить, не приводила к бесконечному циклу.

Хуки, CLAUDE.md и разрешения

CLAUDE.md содержит рекомендации, которые читает модель; /permissions — это список действий, которые она может выполнять без запроса разрешения; хуки — это код, который выполняется в любом случае. Используйте CLAUDE.md для стиля и контекста, разрешения — для определения того, что можно выполнять сразу, а что требует согласования, и хуки — для всего, что должно соблюдаться каждый раз: форматирования, поиска секретов, обязательных проверок тестов и журналов аудита. Они работают совместно: разрешение позволяет запускать Bash(git *) , а хук PreToolUse всё равно блокирует git push --force.

Хуки и шлюз

Хуки выполняются локально и никогда не обращаются к API, поэтому ничего не меняется, когда Claude Code направлен на ANTHROPIC_BASE_URL=https://aiprimetech.io. Полезное сочетание: хук Stop , который выводит /cost— статистику использования в таком формате на основе ваших журналов, чтобы команда с оплатой по мере использования видела стоимость каждой сессии при её завершении.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

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

AI Prime Tech — независимый API-шлюз, который не связан с Anthropic, не одобрен и не спонсируется этой компанией. «Claude» и «Claude Code» — товарные знаки Anthropic. Описанные здесь возможности Claude Code соответствуют публичной документации Anthropic на момент написания и часто меняются; цены и списки моделей на этой странице берутся из текущих настроек шлюза.