Справочник по 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. Выберите hook event для ответа, например PreToolUse или Stop
2. Добавьте matcher group для фильтрации срабатывания, например “только для инструмента Bash”
3. Определите один или несколько hook handlers для запуска при совпадении

​

Расположение hook

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

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

​

Matcher patterns

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

​

Match MCP tools

• mcp__memory__create_entities: инструмент create entities сервера Memory
• mcp__filesystem__read_file: инструмент 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"
          }
        ]
      }
    ]
  }
}

​

Hook handler fields

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

​

Common fields

​

Command hook fields

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

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

​

HTTP hook fields

{
  "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 tool hook fields

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

​

Prompt and agent hook fields

​

Reference scripts by path

• ${CLAUDE_PROJECT_DIR}: корень проекта, где сеанс начался. Claude Code также устанавливает эту переменную в окружении stdio MCP серверов и plugin LSP серверов.
• ${CLAUDE_PLUGIN_ROOT}: каталог установки плагина, для скриптов, поставляемых с плагином. См. plugin environment variables для того, как путь ведёт себя при обновлениях.
• ${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
          }
        ]
      }
    ]
  }
}

​

Hooks in skills and agents

• Subagent hooks: Claude Code запускает их только пока этот subagent работает и удаляет их, когда он завершается. Claude Code преобразует hook Stop здесь в SubagentStop, событие, которое срабатывает при завершении subagent.
• Skill hooks: Claude Code регистрирует их, когда вы или Claude вызываете skill, и продолжает запускать их для остатка сеанса, на ходах после собственного хода skill. Чтобы Claude Code удалил hook после его первого успешного запуска вместо этого, установите once: true на нём.

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

​

Меню /hooks

• User Settings: из ~/.claude/settings.json
• Project Settings: из .claude/settings.json
• Local Settings: из .claude/settings.local.json
• Plugin Hooks: из hooks/hooks.json плагина
• Session Hooks: зарегистрирован в памяти для текущего сеанса

​

Отключение или удаление hooks

​

Входные и выходные данные Hook

​

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

{
  "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..."
}

​

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

​

Exit code 0

• Начинается с { и заканчивается на }: Claude Code анализирует его как JSON. Когда выход состоит из двух или более строк, которые каждая анализируются как JSON самостоятельно, и ни одна строка не является объектом JSON output, который устанавливает поле, Claude Code рассматривает весь выход как простой текст. Когда одна из этих строк устанавливает поле, весь выход является ошибкой анализа, описанной ниже.
• Начинается с { но не заканчивается на }: Claude Code рассматривает это как простой текст.
• Начинается с чего-либо еще: Claude Code рассматривает это как простой текст, JSON массив или включенную строку JSON в кавычках.

​

Exit code 2

#!/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

​

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

• С проанализированным объектом, который проходит валидацию схемы, для событий, которые используют стандартную модель решения, Claude Code игнорирует код выхода и только JSON решает результат:
  • Каждое поле, которое событие поддерживает, учитывается, включая permissionDecision, additionalContext, updatedInput и systemMessage, и hook не сообщается как ошибка.
  • Decision control перечисляет поля решения для каждого события; универсальные поля, такие как systemMessage, следуют таблице JSON output.
• С проанализированным объектом, который не проходит валидацию схемы, для событий, которые используют стандартную модель решения, это то же самое неблокирующее ошибка, что и на exit 0: действие продолжается, и уведомление <hook name> hook error содержит сообщение валидации.
• С stdout, который Claude Code пытается анализировать как JSON и не может, Claude Code сообщает о той же неблокирующей ошибке, что и на exit 0 для событий, которые используют стандартную модель решения. Действие продолжается, и уведомление содержит сообщение анализа.
• С stdout, который Claude Code рассматривает как простой текст, или с пустым stdout, это неблокирующая ошибка для большинства hook событий: действие продолжается, и транскрипт показывает уведомление об ошибке <hook name> hook error, за которым следует первая строка stderr, с префиксом Failed with non-blocking status code:. Чтобы захватить полный stderr, включите debug logging.

​

Timeouts

• Истекший по времени hook command, http или mcp_tool не блокирует вызов инструмента. Вызов продолжается через нормальный поток разрешений, поэтому не рассчитывайте на зависший hook, чтобы действовать как ворота.
• Agent SDK callback hook, который превышает свой timeout, блокирует вызов инструмента.

​

Exit code 2 behavior per event

​

HTTP response handling

• 2xx с пустым телом: успех, эквивалентно exit code 0 без выхода
• 2xx с телом объекта JSON: анализируется с использованием той же схемы JSON output, что и hooks команд. Тело, которое не проходит валидацию схемы, является неблокирующей ошибкой
• 2xx с любым другим телом, таким как простой текст: неблокирующая ошибка, обрабатывается так же, как статус non-2xx. Claude Code не добавляет текст в контекст Claude
• Статус non-2xx: неблокирующая ошибка, выполнение продолжается
• Ошибка соединения: неблокирующая ошибка, выполнение продолжается
• Timeout: hook отменяется, как описано в разделе Timeouts

​

JSON output

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

• Универсальные поля, такие как continue, перечислены в таблице ниже. Каждое событие их принимает, но некоторые события игнорируют их или доставляют systemMessage в другое место, чем транскрипт. Каждый раздел события говорит об этом. terminalSequence работает на этих событиях также, с исключениями, перечисленными в разделе Emit terminal notifications.
• Top-level decision и reason используются некоторыми событиями для блокировки или предоставления обратной связи.
• hookSpecificOutput — это вложенный объект для событий, которым нужно более богатое управление. Он требует поле hookEventName, установленное на имя события.

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

​

Emit terminal notifications

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

• Claude Code выпускает последовательность только в интерактивном сеансе и только пока его интерфейс находится на экране. В неинтерактивном режиме с флагом -p и в Agent SDK он игнорирует поле.
• Hook команды WorktreeCreate не может вернуть JSON, потому что Claude Code читает его stdout как путь worktree. HTTP hook 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}'

​

Add context for 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 decision control
• PostModelSwitch: со следующим запросом после переключения. См. PostModelSwitch decision control для синхронизации

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

​

Decision control

• PreToolUse: updatedInput непосредственно под hookSpecificOutput заменяет аргументы инструмента перед его запуском. См. PreToolUse decision control
• PermissionRequest: updatedInput внутри объекта decision. См. PermissionRequest decision control
• PostToolUse: updatedToolOutput заменяет результат инструмента. См. PostToolUse decision control
• 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"
      }
    }
  }
}

​

События hooks

​

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

​

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

​

Ввод 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"
  }
}

​

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 расширяет ~ и относительные пути перед выполнением hooks, поэтому hook, который совпадает с путями, не может быть обойден через ~ или относительное написание одного пути
• На Windows путь прибывает с разделителями обратной косой черты, даже когда ваш hook выполняется под Git Bash, где $PWD выглядит как /c/project
• Сравнение, написанное с прямыми косыми чертами, такое как проверка /src/, никогда не совпадает с путем обратной косой черты, и вызов инструмента продолжается, как если бы hook не имел ничего для блокировки
• Нормализуйте разделители перед сравнением: 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": "..."
  },
  ...
}

• На Windows, везде, где включен инструмент PowerShell, Claude рассматривает PowerShell как основную оболочку и маршрутизирует команды оболочки через него.
• На Windows без Git Bash инструмент включен автоматически и Claude Code не регистрирует инструмент Bash вообще.
• Hook, который совпадает только с Bash, никогда не срабатывает там.

​

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

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

​

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

1. Claude вызывает AskUserQuestion. Срабатывает hook PreToolUse.
2. Hook возвращает permissionDecision: "defer". Инструмент не выполняется. Процесс выходит с stop_reason: "tool_deferred" и отложенный вызов инструмента сохраняется в транскрипте.
3. Вызывающий процесс читает deferred_tool_use из результата SDK, выводит вопрос в своем собственном UI и ждет ответа.
4. Вызывающий процесс запускает claude -p --resume <session-id> с тем же хостом разрешений. Тот же вызов инструмента срабатывает PreToolUse снова.
5. Hook возвращает 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"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

​

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"
      }
    }
  }
}

​

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

​

PostToolUse

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

​

Ввод PostToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

​

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

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

​

Аннотирование результата для классификатора режима auto

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

• Hooks, настроенные в Claude Code: для hooks из файлов параметров, плагинов, skills и frontmatter агента классификатор рассматривает заметку как непроверенный, предоставленный приложением контекст. Заметка никогда не устанавливает намерение пользователя, и если она утверждает, что вы одобрили или запросили что-то, классификатор проверяет это утверждение против ваших собственных сообщений в разговоре
• In-process callbacks Agent SDK: когда приложение, встраивающее Claude Code, регистрирует hook как callback TypeScript SDK и возвращает заметку во время живого сеанса, классификатор может взвесить утверждение пользователя, переданное в заметке, как намерение пользователя. Такое утверждение может удовлетворить требование согласия, которое классификатор принял бы из сообщения, которое вы отправляете, но оно никогда не снимает блокировку, которую ваше собственное сообщение не могло бы снять. После возобновления сеанса Claude Code рассматривает восстановленные заметки как непроверенный контекст. Когда hooks из обеих групп аннотируют один и тот же вызов, классификатор рассматривает объединенную заметку как непроверенный контекст

• Длина: Claude Code ограничивает заметки для одного вызова инструмента 2000 символами и усекает остальное. Ограничение делится между каждым hook, который отвечает на этот вызов
• Только синхронные ответы: Claude Code игнорирует поле в ответе hook, который выполняется в фоновом режиме, потому что этот ответ прибывает после того, как Claude Code записывает результат инструмента
• Вызовы, которые классификатор не записывает: транскрипт классификатора опускает поиски только для чтения, такие как чтение файлов и поиски. Claude Code отбрасывает заметку, прикрепленную к одному из этих вызовов
• Взаимодействие с переписыванием: когда заметка описывает вывод, который вы заменяете с помощью updatedToolOutput, верните оба поля в одном ответе hook. Claude Code отбрасывает заметку, если это переписывание отклонено или переписывание другого hook заменяет его. Claude Code доставляет заметку, которую вы возвращаете без переписывания, даже когда другой hook переписывает вывод

​

PostToolUseFailure

​

Ввод PostToolUseFailure

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

• Для Bash и PowerShell команда, которая выполнилась и вышла, создает первую строку Exit code N, затем любой вывод, который команда создала, как один блок с stdout и stderr перемешанными
• Полезная нагрузка также может нести сообщение об ошибке без строки кода выхода, когда Claude Code не мог запустить сам процесс оболочки
• Claude Code усекает длинные строки в середине вокруг маркера ... [N characters truncated] ... и может вставлять свои собственные строки, такие как Command timed out after 2m 0s

​

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

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

​

PostToolBatch

​

Ввод PostToolBatch