Справочник по hooks

Жизненный цикл hook

• один раз за сеанс: SessionStart и SessionEnd
• один раз за ход: UserPromptSubmit, Stop и StopFailure
• при каждом вызове инструмента внутри агентного цикла: PreToolUse и PostToolUse, за исключением вызовов EndConversation, которые пропускают оба

Как разрешается hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # no decision; normal permission flow applies
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          }
        ]
      }
    ]
  }
}

# .claude/hooks/block-rm.ps1
$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
$command = $callInput.tool_input.command

if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Destructive command blocked by hook"
    }
  } | ConvertTo-Json
} else {
  exit 0  # no decision; normal permission flow applies
}

{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

Конфигурация

1. Выберите событие хука, на которое нужно реагировать, например PreToolUse или Stop
2. Добавьте группу matcher, чтобы отфильтровать, когда он срабатывает, например «для инструмента Bash»
3. Определите один или несколько обработчиков хука, которые будут запускаться при совпадении

Расположение хуков

• Ваши пользовательские, проектные, локальные хуки и хуки плагинов блокируются. Исключение составляют хуки из плагинов, принудительно включённых в enabledPlugins управляемых настроек
• Claude Code также ограничивает ваши настройки statusLine и fileSuggestion управляемыми настройками
• Claude Code также отключает плагины с источником command, включая плагины, принудительно включённые в enabledPlugins управляемых настроек, если только disableCommandPluginSources явно не установлен в false. Источники command требуют Claude Code v2.1.229 или новее
• Claude Code также блокирует команды headersHelper маркетплейсов, если только disableCommandPluginSources явно не установлен в false, за исключением маркетплейса, который объявлен в самих управляемых настройках

• allowedHttpHookUrls: если задан на любом уровне настроек, Claude Code запускает обработчик HTTP-хука, только если его URL соответствует объединённому списку разрешённых
• httpHookAllowedEnvVars: если задан, Claude Code подставляет в заголовки хуков только переменные окружения из этого списка

Шаблоны matcher

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

Сопоставление MCP-инструментов

• mcp__memory__create_entities: инструмент создания сущностей сервера Memory
• mcp__filesystem__read_file: инструмент чтения файла сервера Filesystem
• mcp__github__search_repositories: инструмент поиска сервера GitHub

• mcp__memory__.* соответствует всем инструментам сервера memory
• mcp__brave-search__.* соответствует всем инструментам сервера, имя которого содержит дефис
• mcp__.*__write.* соответствует любому инструменту любого сервера, имя которого начинается с write

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

Сопоставление команд Monitor

• Matcher, включающий Monitor: с matcher, например Bash|Monitor или .*, или без matcher хук получает собственные входные данные вызова Monitor, и allow и updatedInput применяются. В if укажите Monitor, как в Monitor(tail *), который сопоставляется по тем же правилам, что и Bash(tail *). Если в его if указан Bash, хук всё равно получает входные данные вызова Monitor, но allow и updatedInput не действуют
• Matcher Bash: хук получает вызов Bash. В if укажите Bash, как в Bash(tail *). Хук не запускается, если в его if указан Monitor

Поля обработчика хука

• Командные хуки (type: "command"): запускают shell-команду. Ваш скрипт получает входные данные JSON события через stdin и сообщает результаты через коды выхода и stdout.
• HTTP-хуки (type: "http"): отправляют входные данные JSON события как HTTP POST-запрос на URL. Эндпоинт сообщает результаты через тело ответа, используя тот же формат вывода JSON, что и командные хуки.
• Хуки MCP-инструментов (type: "mcp_tool"): вызывают инструмент на настроенном MCP-сервере. Текстовый вывод инструмента обрабатывается так же, как stdout командного хука.
• Хуки с промптом (type: "prompt"): отправляют промпт модели Claude для однократной оценки. Модель возвращает своё решение в виде JSON. См. Хуки на основе промптов.
• Хуки агентов (type: "agent"): порождают субагента, который может использовать такие инструменты, как Read, Grep и Glob, чтобы проверить условия перед возвратом решения. Хуки агентов являются экспериментальными и могут измениться. См. Хуки на основе агентов.

Общие поля

Как шаблоны if сопоставляются с командами Bash

Поля командного хука

Форма exec и форма shell

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
}

{
  "type": "command",
  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
}

Поля HTTP-хука

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Поля хука MCP-инструмента

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": { "file_path": "${tool_input.file_path}" }
          }
        ]
      }
    ]
  }
}

Как читается результат инструмента

MCP tool "security_scan" on server "my_server" gave no answer that could be read, because a message from the server was too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.
MCP tool "security_scan" on server "my_server" answered without its text, which happens when a result is too large, so this hook gave no verdict. If this keeps happening, the tool must send a smaller answer.

Когда сервер ещё подключается

События, которые срабатывают до того, как MCP-серверы становятся доступны

Поля хуков с промптом и хуков агентов

Ссылки на скрипты по пути

• ${CLAUDE_PROJECT_DIR}: корень проекта, в котором началась сессия. Claude Code также задаёт эту переменную в окружении stdio MCP-серверов и LSP-серверов плагинов.
• ${CLAUDE_PLUGIN_ROOT}: каталог установки плагина, для скриптов, поставляемых с плагином. О том, как ведёт себя путь при обновлениях, см. переменные окружения плагинов.
• ${CLAUDE_PLUGIN_DATA}: каталог постоянных данных плагина, для зависимостей и состояния, которые должны сохраняться при обновлениях плагина.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Хуки в скиллах и агентах

• Хуки субагентов: Claude Code запускает их только во время работы этого субагента и удаляет, когда он завершается. Claude Code преобразует хук Stop здесь в SubagentStop — событие, которое срабатывает при завершении субагента.
• Хуки скиллов: Claude Code регистрирует их, когда вы или Claude вызываете скилл, и продолжает запускать их до конца сессии, в том числе на ходах после собственного хода скилла. Чтобы Claude Code вместо этого удалял хук после его первого успешного запуска, задайте для него once: true.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Ограничения хуков скиллов

• Блокировка «только плагины»: администратор вашей организации может ограничить хуки плагинами и управляемыми настройками с помощью управляемой настройки strictPluginOnlyCustomization. При такой блокировке скилл сохраняет свои хуки из frontmatter, только если это скилл плагина, встроенный скилл или скилл в каталоге управляемых настроек. Хуки в ваших собственных файлах настроек тоже не запускаются.
  • Проверка: введите /status в сессии Claude Code. Если строка Setting sources содержит Enterprise managed settings, спросите администратора, блокирует ли strictPluginOnlyCustomization хуки.
  • Исправление: перенесите скилл в плагин, поскольку скиллы плагинов сохраняют свои хуки из frontmatter. Добавьте плагин в маркетплейс, а затем установите его оттуда. Если Claude Code отклоняет маркетплейс с сообщением is blocked by enterprise policy, попросите администратора разрешить этот маркетплейс.
• Лимит хуков: в Claude Code v2.1.304 или новее у каждого источника скиллов есть собственный лимит на сессию. Ваш проект, ваша папка личных скиллов и каждый плагин считаются отдельными источниками. Скиллы из одного источника могут зарегистрировать не более 1 024 хуков. Matcher этих хуков в сумме могут содержать не более 16 384 символов. Matcher, под которым находится несколько хуков, учитывается один раз для каждого хука.
  • Проверка: повторите сессию, в которой хук не сработал, с включённым логированием отладки:
    1. Запустите новую сессию из оболочки с помощью claude --debug. Если вы не запускаете сессии из оболочки, вместо этого сначала введите /debug в новой сессии.
    2. Вызовите те же скиллы в том же порядке, включая те, которые вызывал Claude, поскольку оба итоговых значения накапливаются скилл за скиллом. Попросите Claude вызвать любой скилл, который вы не можете ввести как команду.
    3. Найдите в логе отладки registers none of its hooks. Строка с этим текстом называет скилл, который превысил лимит.
  • Исправление: объявите меньше хуков или более короткие matcher в этом скилле или в других скиллах из его источника, затем начните новую сессию. Если эти скиллы не ваши и вы не можете их редактировать, попросите их автора внести это изменение. До тех пор начинайте новую сессию и вызывайте нужный скилл раньше любого другого скилла из его источника.

Меню /hooks

Отключение или удаление хуков

Входные и выходные данные хуков

Общие поля входных данных

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

Вывод через код выхода

• Успех: ваш хук завершается с кодом 0. Claude Code применяет все поля вывода JSON, которые вывел ваш хук, и действие выполняется, если эти поля не блокируют и не отклоняют его. Исключение описано в разделе Хуки, запускающие фоновый процесс.
• Блокирующая ошибка: ваш хук завершается с кодом 2. Для событий, которые могут блокировать, Claude Code останавливает действие.
• Неблокирующая ошибка: ваш хук завершается с любым другим кодом или завершается сбоем иным образом, например не запускается или выводит некорректный JSON. Действие выполняется, за исключением хуков, сбой которых блокирует действие, например хука с onFailure, установленным в "block". Для таких событий, как PreToolUse, в транскрипте отображается уведомление <hook name> hook error.

• WorktreeCreate: любой ненулевой код выхода приводит к ошибке создания worktree, что бы ни содержал ваш JSON.
• WorktreeRemove: любой ненулевой код выхода приводит к ошибке удаления worktree, если каталог после этого всё ещё существует.
• Stop, SubagentStop, TaskCompleted и хук UserPromptSubmit плагина: если ваш хук завершается с кодом 2, ничего не выводит в stdout, а его stderr сообщает об отсутствии файла, например No such file or directory, Claude Code обрабатывает запуск как неблокирующую ошибку.
• Elicitation и ElicitationResult: Claude Code применяет ваш hookSpecificOutput, когда хук завершается с кодом 0, и игнорирует его при любом другом коде выхода.
• События, отбрасывающие вывод хука, такие как StopFailure: Claude Code игнорирует ваш JSON при любом коде выхода, за исключением полей с побочными эффектами, таких как terminalSequence, которые всё равно срабатывают.

Код выхода 0

• Вывод, который не начинается с { или начинается с {, но не заканчивается }: обычный текст. По этому правилу массив JSON и строка JSON в кавычках считаются обычным текстом.
• Две или более строк, каждая из которых по отдельности разбирается как JSON, причём первая начинается с {, а последняя заканчивается }: обычный текст, если ни одна строка не является объектом вывода JSON, задающим какое-либо поле. Если такая строка есть, вывод считается ошибкой разбора, поэтому выводите этот объект, не добавляя в stdout ничего другого.
• Всё остальное, что начинается с { и заканчивается }, но не является корректным JSON: ошибка разбора.

• UserPromptSubmit, UserPromptExpansion, SessionStart и PostModelSwitch: Claude Code добавляет обычный текст из stdout как контекст, который Claude может видеть и учитывать. Stdout, который ему не удалось разобрать, Claude Code не добавляет.
• PreCompact: ваш stdout становится инструкциями для сводки сжатия контекста

Код выхода 2

• JSON, прошедший проверку схемы: Claude Code по-прежнему читает поля вывода JSON, но они не могут переопределить блокировку. Даже permissionDecision со значением "allow" не пропускает действие. Для Elicitation и ElicitationResult поле hookSpecificOutput хука, завершившегося с кодом 2, игнорируется.
• JSON, не прошедший проверку схемы: хук всё равно блокирует. Claude Code использует ваш stderr как причину блокировки и записывает ошибку проверки в отладочный лог.

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed

Другие коды выхода

Failed with non-blocking status code: something broke

Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory

Таймауты

Хуки, запускающие фоновый процесс

• Запустите программу в фоновом режиме
• Перенаправьте её stdout и stderr. Например, команда Bash npm run dev > dev-server.log 2>&1 & направляет оба потока в файл. Если вы их не перенаправите, хуку, который не является асинхронным, требуется до 10 секунд, чтобы завершиться после выхода собственного процесса.

#!/bin/bash
"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $?
"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 &

• || exit $?: делает код выхода проверки собственным кодом выхода хука, поэтому проверка, завершающаяся с кодом 2 для отказа, по-прежнему блокирует. Иначе хук завершается с кодом последней строки, то есть 0.
• >/dev/null 2>&1 &: запускает upload-metrics.sh в фоновом режиме с перенаправленным выводом, чтобы он не удерживал вывод хука открытым.

Блокировка действия при сбое хука

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'

• Не удаётся запустить: командный хук не запускается, например потому что скрипт или исполняемый файл не существует
• Код выхода, отличный от 0 или 2: учитывается для командного хука, даже если он вывел JSON, разрешающий действие, например permissionDecision: "allow". Чтобы вернуть решение в JSON, завершитесь с кодом 0
• Ошибка HTTP: соединение HTTP-хука не удаётся установить, или статус ответа не 2xx
• Таймаут: хук достигает своего timeout
• Некорректный вывод: вывод JSON не удаётся разобрать или он не проходит проверку схемы. Для HTTP-хука сбоем также считается тело ответа 2xx, которое не является ни пустым, ни объектом JSON. Обычный текст в stdout командного хука сбоем не считается

• Хуки Stop, SubagentStop, TaskCompleted и TeammateIdle: код выхода 2 для этих событий отправляет Claude продолжать работу, а Claude не может исправить хук, который не запускается
• Фоновые командные хуки: командные хуки, в которых задано async или asyncRewake

Сбой хуков в Windows без Git Bash

blocking because Git Bash wasn't found, so only exit code 0 or 2 counts as this hook's verdict.

• Действие должно выполняться при сбое хука: добавьте в хук "onFailure": "continue"
• Хук завершается с кодом 1 для предупреждения, но должен блокировать при падении: с "onFailure": "continue" вызов выполняется при коде выхода 1 — как при предупреждении, так и при падении. Вместо этого добавьте "onFailure": "block" и завершайте скрипт с кодом 0 там, где он выдаёт предупреждение, чтобы такие вызовы выполнялись. Чтобы по-прежнему показывать предупреждение для PreToolUse, выведите его в stdout в поле systemMessage одного объекта JSON.
• Хук написан для Bash: без Git Bash хук в форме оболочки без заданного shell выполняется в PowerShell, где он может завершиться сбоем. Установите Git for Windows или задайте CLAUDE_CODE_GIT_BASH_PATH, если Git Bash установлен там, где Claude Code его не находит. Затем начните новую сессию.
• Хук запускает один файл .exe, а не файл .cmd или .bat: укажите программу в command, а её аргументы в args, чтобы использовать форму exec, и добавьте "onFailure": "block". Тогда Claude Code запускает программу без оболочки. Без "onFailure": "block" вызов может выполниться, если программа завершается сбоем, отсутствует или превышает таймаут
• Защитный хук PowerShell, который должен блокировать при сбое: при незаданном onFailure он перестаёт это делать, как только установлен Git for Windows и Claude Code находит Git Bash. Добавьте "onFailure": "block", чтобы сбой или таймаут блокировал вызов как с Git Bash, так и без него. Также задайте "shell": "powershell", чтобы хук и дальше выполнялся в PowerShell, а не в Git Bash

PowerShell started no program

• Чтобы вывести текст, например JSON: задайте "shell": "powershell", и хук завершится с кодом 0
• Чтобы запустить файл .ps1, .cmd или .bat либо .exe, путь к которому содержит переменную: задайте "shell": "powershell" и поставьте & перед путём в кавычках. Оставьте $HOME как есть, а переменные окружения записывайте так, как пример check.ps1 записывает $env:CLAUDE_PROJECT_DIR
• Чтобы запустить один .exe по пути без $: удалите внутренние кавычки из command, затем примените исправление для хука, запускающего один .exe, указав "args": [], если программа не принимает аргументов
• Чтобы запустить скрипт, написанный для Bash: примените исправление для хука, написанного для Bash

Поведение кода выхода 2 для каждого события

Обработка HTTP-ответов

• 2xx с пустым телом: успех, эквивалентно коду выхода 0 без вывода
• 2xx с телом в виде объекта JSON: разбирается по той же схеме вывода JSON, что и для командных хуков. Тело, не прошедшее проверку схемы, является неблокирующей ошибкой
• 2xx с любым другим телом, например обычным текстом: неблокирующая ошибка, обрабатывается так же, как статус не 2xx. Claude Code не добавляет текст в контекст Claude
• Статус не 2xx: неблокирующая ошибка
• Сбой соединения: неблокирующая ошибка
• Таймаут: хук отменяется, как описано в разделе Таймауты

Вывод JSON

• Область действия: Claude Code измеряет каждую строку отдельно, даже если для одного события выполняется несколько хуков. Для вывода JSON каждое поле измеряется отдельно; обычный stdout измеряется целиком.
• Превышение лимита: за исключением stdout хука PreCompact, Claude Code сохраняет вывод в файл в каталоге сессии. Он заменяет вывод путём к файлу и превью, содержащим до 2 000 первых символов. Большой корректный результат Bash обрабатывается так же, как описано в разделе Ограничения вывода. В отличие от этого ограничения Bash, у данного лимита нет настройки или переменной окружения, позволяющей его увеличить.
• Чтение файла: Claude Code не просит Claude прочитать файл, поэтому держите всё, что Claude должен видеть всегда, в пределах лимита.

• Универсальные поля, такие как continue, перечислены в таблице ниже. Их принимает каждое событие, но некоторые события отбрасывают их или доставляют systemMessage не в транскрипт, а в другое место. Раздел каждого события об этом сообщает. terminalSequence тоже работает для этих событий, с исключениями, перечисленными в разделе Вывод уведомлений терминала.
• decision и reason верхнего уровня используются некоторыми событиями для блокировки или предоставления обратной связи.
• hookSpecificOutput — вложенный объект для событий, которым требуется более развитое управление. Он требует поле hookEventName, установленное в имя события.

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

Вывод уведомлений терминала

• OSC 0, 1, 2: заголовки окна и значка
• OSC 9: уведомления iTerm2, ConEmu, Windows Terminal и WezTerm, включая индикатор прогресса на панели задач 9;4
• OSC 99: уведомления Kitty
• OSC 777: уведомления urxvt, Ghostty и Warp
• Одиночный BEL

• Claude Code записывает последовательность только в интерактивной сессии и только пока его интерфейс находится на экране. В неинтерактивном режиме с флагом -p и в Agent SDK он игнорирует это поле.
• Поле работает только в хуке, который не выполняется в фоновом режиме, поэтому не включайте async и asyncRewake.
• Командный хук WorktreeCreate не может возвращать JSON, потому что Claude Code читает его stdout как путь к worktree. HTTP-хук WorktreeCreate возвращает JSON и может включать это поле.

#!/bin/bash
# Notification hook: ping the desktop when Claude Code needs attention.
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Получение уведомлений терминала внутри tmux или GNU screen

• tmux 3.3 или новее: добавьте set -g allow-passthrough on в ~/.tmux.conf, затем выполните tmux source-file ~/.tmux.conf из оболочки. Параметр применяется ко всем программам в этих панелях, а не только к Claude Code. Со значением on отправлять их могут только панели, которые tmux показывает на экране. Чтобы их могли отправлять и другие панели в сессии, к которой вы подключены, используйте all вместо on в tmux 3.4 или новее.
• GNU screen: держите окно Claude Code отображаемым в screen, потому что последовательности из фонового окна не доходят до вашего терминального приложения

Добавление контекста для Claude

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

• SessionStart и SubagentStart: в начале диалога, перед первым промптом
• UserPromptSubmit и UserPromptExpansion: вместе с отправленным промптом
• PreToolUse, PostToolUse, PostToolUseFailure и PostToolBatch: рядом с результатом инструмента
• Stop и SubagentStop: в конце хода. Диалог продолжается, чтобы Claude мог отреагировать на обратную связь. Смотрите Управление решениями Stop
• PostModelSwitch: со следующим запросом после переключения. Смотрите Управление решениями PostModelSwitch, чтобы узнать о времени доставки

• Состояние окружения: текущая ветка, цель развёртывания или активные флаги функций
• Условные правила проекта: какая команда тестирования применима к только что отредактированному файлу, какие каталоги доступны только для чтения в этом worktree
• Внешние данные: открытые задачи, назначенные вам, недавние результаты CI, содержимое, полученное из внутреннего сервиса

Управление решениями

• PreToolUse: updatedInput непосредственно в hookSpecificOutput заменяет аргументы инструмента перед его запуском. Смотрите Управление решениями PreToolUse
• PermissionRequest: updatedInput внутри объекта decision. Смотрите Управление решениями PermissionRequest
• PostToolUse: updatedToolOutput заменяет результат инструмента. В облачной сессии Cowork Claude Code игнорирует updatedToolOutput, если инструментом является AskUserQuestion или ExitPlanMode, и Claude читает исходный ответ или план. Смотрите Управление решениями PostToolUse
• UserPromptSubmit: не может заменить промпт; он только внедряет additionalContext рядом с ним

{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

События хуков

SessionStart

Входные данные SessionStart

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "resume",
  "model": "claude-opus-5",
  "seconds_since_last_response": 5400,
  "context_tokens": 182340,
  "prompt_cache_likely_expired": true,
  "estimated_cache_write_usd": 1.1396
}

Управление решениями SessionStart

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
    "sessionTitle": "auth-refactor"
  }
}

Перезагрузка скиллов, которые устанавливает хук

#!/bin/bash

git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills

echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

Сохранение переменных окружения

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

Сохранённые переменные в командах PowerShell

• Пустая строка или комментарий #
• Одно присваивание в начале строки, записанное как export NAME=value, declare -x NAME=value или NAME=value, со значением, которое Bash использовал бы в точности как написано, составленным из любого сочетания следующих частей: текст без кавычек, использующий только буквы, цифры и символы _ @ % + = : , . / -, текст в одинарных кавычках и текст в двойных кавычках, где любые $, обратная кавычка или " внутри экранированы обратной косой чертой

Setup

Входные данные Setup

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Setup",
  "trigger": "init"
}

Управление решениями Setup

InstructionsLoaded

Входные данные InstructionsLoaded

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/Users/my-project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

Управление решениями InstructionsLoaded

UserPromptSubmit

• срабатывает запланированная задача на уровне сессии, включая итерацию /loop
• Фоновый субагент отчитывается перед сессией, которая его запустила
• Другая сессия отправляет сообщение в ваш основной диалог

Esc во время проверки промпта

Входные данные UserPromptSubmit

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

Управление решениями UserPromptSubmit

• Обычный текстовый stdout: Claude Code добавляет stdout, который он считает обычным текстом, в контекст Claude
• JSON с additionalContext: используйте формат JSON ниже для большего контроля. Поле additionalContext добавляется как контекст

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title",
    "suppressOriginalPrompt": true
  }
}

Что остаётся после заблокированного промпта

UserPromptExpansion

Входные данные UserPromptExpansion

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../00893aaf.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

Управление решениями UserPromptExpansion

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

MessageDisplay

• убирать markdown для минималистичного отображения
• преобразовывать текст, который приложение на Agent SDK показывает своим пользователям
• скрывать API-ключи или внутренние имена хостов из ответов Claude

Входные данные MessageDisplay

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "MessageDisplay",
  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
  "index": 0,
  "final": false,
  "delta": "Here is the plan:\n"
}

Вывод MessageDisplay

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
            ]
          }
        ]
      }
    ]
  }
}

$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
$text = $batch.delta -replace '\*\*', '' -replace '`', ''
@{
  hookSpecificOutput = @{
    hookEventName = "MessageDisplay"
    displayContent = $text
  }
} | ConvertTo-Json

PreToolUse

Входные данные PreToolUse

• Claude Code раскрывает ~ и относительные пути до выполнения хуков, поэтому хук, сопоставляющий пути, нельзя обойти через ~ или относительную запись того же пути
• В Windows путь поступает с обратными косыми чертами в качестве разделителей, даже если ваш хук выполняется в Git Bash, где $PWD выглядит как /c/project
• Сравнение, записанное с прямыми косыми чертами, например проверка /src/, никогда не совпадёт с путём с обратными косыми чертами, и вызов инструмента продолжится так, будто хуку нечего было блокировать
• Нормализуйте разделители перед сравнением: FILE_PATH="${FILE_PATH//\\//}" в Bash или file_path.replace("\\", "/") в Python, а затем сопоставляйте сегмент пути, например /src/, а не привязывайтесь к началу с помощью ^, поскольку путь абсолютный

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "C:\\project\\src\\index.ts",
    "content": "..."
  },
  ...
}

Bash

PowerShell

• В Windows везде, где включён инструмент PowerShell, Claude считает PowerShell основной оболочкой и направляет shell-команды через него.
• В Windows без Git Bash инструмент включается автоматически, и Claude Code вообще не регистрирует инструмент Bash.
• Хук, соответствующий только Bash, там никогда не срабатывает.

Write

Edit

Read

Glob

Grep

WebFetch

WebSearch

Agent

AskUserQuestion

ExitPlanMode

Управление решениями PreToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

updatedInput в PreToolUse в авторежиме

a hook changed this call's input after auto mode reviewed it

• Он может отклонить вызов или отправить его на запрос разрешения
• Любой возвращённый им updatedInput отбрасывается, поэтому выполняется то, что проверил сервер

Решения ask в PreToolUse в авторежиме

• Вызовы, которые также помечают собственные проверки Claude Code: к ним относятся запись в защищённые пути и команды, запрашивающие выполнение вне песочницы. Классификатор может отклонить такой вызов до появления какого-либо запроса. Если он одобряет, вызов обычно всё равно попадает в запрос.
• Вызовы SubagentHandback: этот инструмент передаёт отчёт субагента. Для него запрос не появляется, и вызов выполняется, даже если классификатор возражает.

Инструменты, требующие взаимодействия с пользователем

1. Считывает входные данные инструмента из stdin
2. Собирает ответ через ваш собственный интерфейс
3. Возвращает permissionDecision: "allow" вместе с updatedInput, содержащим ответ, чтобы инструмент выполнился без запроса

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "questions": [
        {
          "question": "Which framework?",
          "header": "Framework",
          "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}],
          "multiSelect": false
        }
      ],
      "answers": {"Which framework?": "React"}
    }
  }
}

Отложить вызов инструмента на потом

• В интерактивных сессиях: записывается предупреждение, а результат хука игнорируется
• Несколько вызовов инструментов одновременно: "defer" игнорируется с предупреждением, и инструмент проходит обычный процесс проверки разрешений

1. Claude вызывает AskUserQuestion. Срабатывает хук PreToolUse.
2. Хук возвращает permissionDecision: "defer". Инструмент не выполняется. Ход завершается результатом с stop_reason: "tool_deferred", а ожидающий вызов инструмента остаётся в транскрипте.
3. Вызывающий процесс читает deferred_tool_use из результата SDK, показывает вопрос в своём интерфейсе и ждёт ответа.
4. Вызывающий процесс выполняет claude -p --resume <session-id> с тем же хостом разрешений. Тот же вызов инструмента снова вызывает PreToolUse.
5. Хук возвращает permissionDecision: "allow" с ответом в updatedInput. Инструмент выполняется, и Claude продолжает работу.

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false }] }
  }
}

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

• Чтобы выполнить вызов: сделайте инструмент доступным и возобновите сессию снова.
• Чтобы отбросить вызов: возобновите сессию с промптом, установив CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL в 1. Claude получит ошибку в качестве результата вызова и ответит на ваш промпт. При следующем возобновлении ожидающих вызовов не будет.

PermissionRequest

Входные данные PermissionRequest

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

Управление решениями PermissionRequest

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

Записи обновления разрешений

• Bash(npm test): { "toolName": "Bash", "ruleContent": "npm test" }
• Bash или Bash(*): { "toolName": "Bash" }, потому что оба соответствуют всему инструменту
• mcp__github__get_issue: { "toolName": "mcp__github__get_issue" }

PostToolUse

• Чтобы запускать хук после успешного завершения любого инструмента, опустите matcher или установите его в "*". Тогда ваш хук может сам определить, что изменилось, например выполнив git status --porcelain, который также перечисляет неотслеживаемые файлы, пропускаемые git diff. Для вызовов инструментов, завершившихся с ошибкой, добавьте тот же хук в PostToolUseFailure.
• Чтобы запускать хук при изменении определённого файла на диске, независимо от того, кто его записал, используйте FileChanged. Claude Code не запускает хук PostToolUse с matcher Edit|Write, когда тот же файл перезаписывает команда Bash или процесс вне Claude Code.

PostToolUse после прерывания

• Ctrl+Enter: если нажатие завершает ход во время работы инструмента и инструмент завершается, ваши хуки PostToolUse выполняются на его результате, и у них есть 10 секунд на завершение. Клавиша действует как Esc, если вы поставили в очередь команду ! перед своими сообщениями или фоновые задачи отключены, например с помощью CLAUDE_CODE_DISABLE_BACKGROUND_TASKS.
• Enter: сообщение, поставленное в очередь с помощью Enter, не прерывает ход, поэтому хуки сохраняют свой обычный timeout.
• Esc: вы сразу отменяете хуки, поэтому отправляйте сообщение с помощью Enter или Ctrl+Enter, когда хуки должны выполниться.

Входные данные PostToolUse