Hooks в Claude Code: все события и их назначение

01Как устроен hook

Конфигурация hook состоит из трёх уровней:

1. Событие hook, например PreToolUse или Stop.
2. Группа matcher, которая определяет, когда он срабатывает, например «только для инструмента Bash».
3. Один или несколько обработчиков hook — то, что собственно выполняется.

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

Этот пример запускает скрипт линтинга после того, как Claude создаёт или редактирует файл. Чтобы добавить второе событие, добавьте соседний ключ в тот же объект hooks.

02Где хранятся hooks

Hooks из разных файлов суммируются, а не заменяют друг друга. Введите /hooks в Claude Code, чтобы увидеть все активные hooks и их источники.

В интерактивной сессии Claude Code не запускает hooks, даже Ваши собственные, пока Вы не подтвердите доверие к папке в диалоге workspace trust.

03Типы обработчиков

Большинство hooks имеют тип "type": "command" и запускают shell-команду. Есть ещё четыре типа:

• http: отправляет JSON события POST-запросом на URL и читает тело ответа.
• mcp_tool: вызывает инструмент на настроенном Вами MCP-сервере.
• prompt: задаёт модели Claude однократный вопрос и читает решение в формате JSON.
• agent: запускает субагента, который может прочитать файлы, прежде чем принять решение (экспериментально).

Command hooks выполняются с полными правами Вашего пользователя: через sh -c на macOS и Linux и через Git Bash (или PowerShell) на Windows. Добавьте "async": true, чтобы запускать hook в фоне; в этом случае он уже не сможет принимать решения.

04Matchers

matcher определяет, при каких вхождениях события запускается hook. С чем он сравнивается, зависит от события: с именем инструмента для событий инструментов, с типом уведомления для Notification, со способом запуска сессии для SessionStart и так далее.

• "*", "" или отсутствие matcher соответствуют всему.
• Буквы, цифры, _, -, пробелы, | и , трактуются как точные имена. Edit|Write соответствует любому из двух инструментов.
• Всё остальное считается регулярным выражением JavaScript, поэтому mcp__memory__.* соответствует всем инструментам одного MCP-сервера.

Matchers чувствительны к регистру. Некоторые события, в том числе Stop и UserPromptSubmit, игнорируют matchers. Для событий инструментов поле if с правилом разрешений, например "Bash(git *)", дополнительно сужает срабатывание отдельного обработчика.

05Входные данные: что получает hook

Каждый hook получает через stdin JSON с несколькими общими полями, включая session_id, transcript_path, cwd и hook_event_name, а также поля, специфичные для события. Например, hook PreToolUse для вызова Bash также получает tool_name и tool_input.command. Прочитать их можно с помощью jq или любого JSON-парсера:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06Выходные данные: коды выхода и JSON

Hook может ответить одним из двух способов.

Коды выхода. 0 означает успех. 2 — блокирующая ошибка: для событий, которые поддерживают блокировку, действие останавливается, а Ваш stderr становится его причиной. Любой другой код, включая привычный 1, — неблокирующая ошибка: действие выполняется, а Вы видите уведомление об ошибке hook. Если hook должен обеспечивать соблюдение правила, завершайте его с кодом 2, а не 1.

JSON в stdout. Для более тонкого управления завершитесь с кодом 0 и выведите один JSON-объект. Некоторые поля работают везде, например continue: false, чтобы полностью остановить Claude. Другие зависят от события: Stop использует decision: "block" вместе с reason, а PreToolUse и PermissionRequest передают решение внутри hookSpecificOutput. Больше ничего в stdout не выводите: случайная строка из профиля shell помешает Claude Code прочитать JSON.

07Все события hook

Anthropic периодически добавляет новые события, поэтому актуальный список и поля входных данных каждого события смотрите в справочнике по hooks.

08Какие события важны для уведомлений

Четыре события покрывают почти всё, о чём обычно хотят получать уведомления:

• Stop — «Claude закончил». См. руководство по Stop hook.
• Notification — «Claude ждёт Вас», с типами вроде permission_prompt и idle_prompt. См. руководство по Notification hook.
• PermissionRequest — чтобы сразу узнать о запросе разрешения или ответить на него. См. руководство по PermissionRequest.
• PreToolUse для инструмента AskUserQuestion — чтобы видеть вопросы Claude с вариантами ответа и отвечать на них. См. ответы на вопросы с телефона.

Готовую настройку для десктопа, которую можно просто вставить, ищите в статье как получить уведомление, когда Claude Code закончит работу.

09Место Claude Code Notifier

Claude Code Notifier целиком построен на этих hooks. Его бесплатная утилита командной строки ccn работает на Mac, Windows и Linux. При установке она добавляет в ~/.claude/settings.json семь записей hooks, каждая из которых запускает ccn hook, и один раз делает резервную копию файла. ccn работает несколько миллисекунд на событие и завершается, так что в фоне ничего не остаётся.

Сама по себе утилита показывает уведомления на рабочем столе. Если подключить приложение для iPhone или Android, те же hooks передают обратно Ваши ответы: разрешить или отклонить запрос, ответить на вопрос или отправить следующую инструкцию после остановки Claude. Это независимый продукт, не созданный Anthropic. Если Вам нужен только лог или линтинг, проще написать несколько строк самостоятельно. Подробности — на странице ccn.

10FAQ