В non-interactive mode с флагом -p, Claude Code предлагает AskUserQuestion и ExitPlanMode только, когда запуск имеет permission host для получения подсказки, такой как callback Agent SDK canUseTool. Эти инструменты требуют взаимодействия с пользователем. Возврат permissionDecision: "allow" вместе с updatedInput удовлетворяет это требование: hook читает ввод инструмента из stdin, собирает ответ через ваш собственный UI и возвращает его в updatedInput, чтобы инструмент выполнялся без подсказки. Возврат только "allow" недостаточен для этих инструментов. Для AskUserQuestion, повторите исходный массив questions и добавьте объект answers, отображающий текст каждого вопроса на выбранный ответ.

Начиная с версии 2.1.199, инструмент MCP, чей сервер отмечает его с помощью _meta["anthropic/requiresUserInteraction"], более строг: hook не может пропустить его подсказку одобрения с "allow", с updatedInput или без него, потому что Claude Code не может подтвердить, что hook собрал взаимодействие, которое требует инструмент.

Defer a tool call for later

"defer" предназначен для интеграций, которые запускают claude -p как подпроцесс и читают его JSON вывод, такие как приложение Agent SDK или пользовательский UI, построенный на основе Claude Code. Это позволяет этому вызывающему процессу приостановить Claude при вызове инструмента, собрать ввод через его собственный интерфейс и возобновить с того же места. Claude Code соблюдает это значение только в non-interactive mode с флагом -p. В интерактивных сеансах он логирует предупреждение и игнорирует результат hook.

Типичный случай — инструмент AskUserQuestion: Claude хочет что-то спросить у пользователя, но нет терминала для ответа. Запуск -p предлагает AskUserQuestion только, когда он имеет permission host, такой как инструмент MCP, который вы передаете с --permission-prompt-tool, поэтому запустите запуск с одним. Круговой путь работает так:

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> с тем же permission host. Тот же вызов инструмента срабатывает PreToolUse снова.
5. Hook возвращает permissionDecision: "allow" с ответом в updatedInput. Инструмент выполняется и Claude продолжает.

Поле deferred_tool_use несет id, name и input инструмента. input — это параметры, которые 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 }] }
  }
}

Нет timeout или лимита повторных попыток. Сеанс остается на диске до возобновления, подлежит retention sweep rules cleanupPeriodDays, которая удаляет файлы сеанса через 30 дней по умолчанию. Если ответ не готов при возобновлении, hook может вернуть "defer" снова и процесс выходит так же. Вызывающий процесс управляет тем, когда разорвать цикл, в конечном итоге возвращая "allow" или "deny" из hook.

"defer" работает только, когда Claude делает один вызов инструмента в ходе. Если Claude делает несколько вызовов инструментов одновременно, "defer" игнорируется с предупреждением и инструмент проходит через нормальный поток разрешений. Ограничение существует, потому что возобновление может повторно запустить только один инструмент: нет способа отсрочить один вызов из партии без оставления других неразрешенными.

Если отсроченный инструмент больше не доступен при возобновлении, процесс выходит с stop_reason: "tool_deferred_unavailable" и is_error: true перед срабатыванием hook. Это происходит, когда сервер MCP, который предоставил инструмент, не подключен для возобновленного сеанса. Полезная нагрузка deferred_tool_use все еще включена, чтобы вы могли определить, какой инструмент исчез.

PermissionRequest

Запускается, когда Claude Code собирается попросить у вас разрешение на использование инструмента. В сеансах, которые не могут показать подсказку, такие как фоновые подагенты в non-interactive mode, Claude Code все еще запускает эти hooks, и если ни один hook не возвращает решение, он отказывает вызову инструмента. Используйте PermissionRequest decision control для разрешения или отказа от имени пользователя.

Используйте это событие, когда вам нужен сигнал в момент, когда Claude просит разрешение на использование инструмента. Claude Code запускает Notification hook с типом permission_prompt только после того, как подсказка ждала около шести секунд.

Claude Code не запускает hooks PermissionRequest для network request изолированной команды. Чтобы получить сигнал для этой подсказки, используйте тип уведомления permission_prompt.

Совпадает с именем инструмента, те же значения, что и PreToolUse.

PermissionRequest input

Hooks PermissionRequest получают поля tool_name и tool_input, как hooks PreToolUse, но без tool_use_id. Для инструмента MCP они также получают объект mcp_server. Опциональный массив permission_suggestions содержит permission updates, которые Claude Code предлагает для этого запроса, такие как добавление правила разрешения или изменение режима разрешений.

Массив permission_suggestions не является точным списком опций, которые вы видите, потому что каждый диалог разрешений строит свои собственные опции. Некоторые диалоги, такие как для редактирования файлов, вообще не читают массив и получают свои опции из самого запроса. Диалог, который читает его, все еще может удержать опцию, чье предложение остается в массиве, например, когда allowManagedPermissionRulesOnly скрывает опции сохранения правил. Он также может предложить опции, которые не имеют записи предложения, такие как Yes, and switch to auto mode, которая изменяет режим разрешений напрямую, а не через обновление разрешений.

Hooks PreToolUse запускаются перед каждым вызовом инструмента, независимо от того, нужно ли ему разрешение. Hooks PermissionRequest запускаются только, когда Claude Code собирается попросить у вас разрешение, или когда он в противном случае автоматически отказал бы вызову, который не может подсказать. Ни одно событие не срабатывает для EndConversation.

{
  "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 decision control

Hooks PermissionRequest могут разрешить или отказать запросы разрешений. Помимо JSON output fields, доступных всем hooks, ваш скрипт hook может вернуть объект decision с этими полями, специфичными для события:

Hook, который выходит 2 без объекта decision, оставляет поток разрешений неизменным, и его stderr отбрасывается. Только объект decision может предоставить или отказать в запросе.

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

Permission update entries

Поле вывода updatedPermissions и поле ввода permission_suggestions оба используют один и тот же массив объектов записей. Каждая запись имеет type, который определяет ее другие поля, и destination, который управляет тем, где записывается изменение.

Поле destination на каждой записи определяет, остается ли изменение в памяти или сохраняется в файл настроек.

Hook может повторить один из permission_suggestions, которые он получил, как свой собственный вывод updatedPermissions.

PostToolUse

Запускается сразу после успешного завершения инструмента.

Совпадает с именем инструмента, те же значения, что и PreToolUse.

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

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

PostToolUse input

Hooks PostToolUse срабатывают после того, как инструмент уже выполнился успешно. Ввод включает как tool_input, аргументы, отправленные инструменту, так и tool_response, результат, который он вернул. Точная схема для обоих зависит от инструмента. Пути инструментов файлов tool_input приходят в том же формате, что и для PreToolUse: всегда абсолютные, с собственными разделителями платформы, поэтому обратные косые черты на Windows. Для инструмента MCP ввод также несет объект mcp_server.

{
  "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 decision control

Hooks PostToolUse могут предоставить обратную связь Claude после выполнения инструмента. Помимо JSON output fields, доступных всем hooks, ваш скрипт hook может вернуть эти поля, специфичные для события:

Пример ниже заменяет вывод вызова Bash. Значение замены совпадает с формой вывода инструмента Bash:

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

Annotate a result for the auto mode classifier

Верните classifierContext для отправки краткой заметки об этом результате вызова инструмента auto mode классификатору, а не Claude. Классификатор никогда не получает результаты инструментов сами, поэтому это поле — поддерживаемый способ сказать ему что-то о том, что вернул вызов, перед тем как он проверит более поздние действия. Поле требует Claude Code v2.1.236 или позже.

Пример ниже говорит классификатору, откуда пришел вывод запроса:

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

Сколько веса классификатор дает заметке, зависит от того, где вы настроили hook:

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

Claude Code применяет эти ограничения при доставке заметки:

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

PostToolUseFailure

Запускается, когда инструмент, который начал выполняться, не удается: инструмент выбросил ошибку или инструмент MCP вернул результат ошибки. Используйте это для логирования сбоев, отправки оповещений или предоставления исправляющей обратной связи Claude.

Совпадает с именем инструмента, те же значения, что и PreToolUse.

PostToolUseFailure input

Hooks PostToolUseFailure получают те же поля tool_name и tool_input, что и PostToolUse, вместе с информацией об ошибке как полями верхнего уровня. Для инструмента MCP они также получают объект mcp_server. Например, неудачная команда npm test может доставить:

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

Строка error обычно является тем же текстом, который Claude получает как результат неудачного инструмента. Его формат варьируется по инструменту и сбою. Ключ вашего hook на tool_name, is_interrupt и первой строке Exit code N; рассматривайте остальную строку как текст отображения, а не стабильный формат.

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

PostToolUseFailure decision control

Hooks PostToolUseFailure могут предоставить контекст Claude после сбоя инструмента. Помимо JSON output fields, доступных всем hooks, ваш скрипт hook может вернуть эти поля, специфичные для события:

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

PostToolBatch

Запускается один раз после того, как каждый вызов инструмента в партии разрешится, перед отправкой Claude Code следующего запроса модели. PostToolUse срабатывает один раз на инструмент, что означает, что он срабатывает одновременно, когда Claude делает параллельные вызовы инструментов. PostToolBatch срабатывает ровно один раз со всей партией, поэтому это правильное место для внедрения контекста, который зависит от набора инструментов, которые выполнились, а не от любого одного инструмента. Нет matcher для этого события.

PostToolBatch input

Помимо common input fields, hooks PostToolBatch получают tool_calls, массив, описывающий каждый вызов инструмента в партии:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

tool_response содержит то же содержимое, которое модель получает в соответствующем блоке tool_result. Значение — это сериализованная строка или массив блоков содержимого, ровно как инструмент выдал его. Для Read это означает текст с префиксом номера строки, а не исходное содержимое файла. Ответы могут быть большими, поэтому анализируйте только нужные вам поля.

PostToolBatch decision control

Hooks PostToolBatch могут внедрить контекст для Claude. Помимо JSON output fields, доступных всем hooks, ваш скрипт hook может вернуть эти поля, специфичные для события:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

Возврат decision: "block" или continue: false останавливает агентский цикл перед следующим вызовом модели. Сообщение блокировки поступает из JSON reason или stopReason или из stderr при выходе 2. Вы видите его как предупреждение в транскрипте, и оно остается в разговоре, поэтому Claude видит его при продолжении разговора.

PermissionDenied

Запускается, когда auto mode отказывает в вызове инструмента, включая когда он отказывает без вердикта классификатора, потому что проверка безопасности, отдельная от auto mode, отказала в запросе классификатора или его ответ не был проанализирован. Этот hook срабатывает только в режиме auto: он не запускается, когда вы вручную отказываете диалогу разрешений, когда hook PreToolUse блокирует вызов или когда совпадает правило deny. Используйте его для логирования отказов, корректировки конфигурации или сообщения модели, что она может повторить вызов инструмента.

Совпадает с именем инструмента, те же значения, что и PreToolUse.

PermissionDenied input

Помимо common input fields, hooks PermissionDenied получают tool_name, tool_input, tool_use_id и reason. Для инструмента MCP они также получают объект mcp_server.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

PermissionDenied decision control

Hooks PermissionDenied могут сказать модели, что она может повторить отклоненный вызов инструмента. Верните JSON объект с hookSpecificOutput.retry, установленным на true:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

Когда retry имеет значение true, Claude Code добавляет сообщение в разговор, говорящее модели, что она может повторить вызов инструмента. Claude Code не отменяет сам отказ. Если ваш hook не возвращает JSON или возвращает retry: false, отказ остается и модель получает исходное сообщение отказа.

Claude Code игнорирует retry: true, когда классификатор создал no verdict on the action: его ответ не был проанализирован или проверка безопасности, отдельная от auto mode, отказала в запросе классификатора. Для этих отказов Claude Code уже говорит модели в сообщении отказа, повторить ли позже или продолжить.

Notification

Запускается, когда Claude Code отправляет уведомления. Совпадает с типом уведомления. Опустите matcher для запуска hooks для всех типов уведомлений.

Вы получаете эти события hook даже с отключенными уведомлениями рабочего стола: параметр preferredNotifChannel, включая notifications_disabled, изменяет только то, как вы получаете оповещение, а не срабатывает ли ваш hook.

Типы agent_needs_input и agent_completed требуют Claude Code v2.1.198 или позже.

Типы quota_auto_resume_fired, quota_auto_resume_stale и quota_auto_resume_disabled требуют Claude Code v2.1.234 или позже.

В сеансах терминала, permission_prompt для network request изолированной команды требует Claude Code v2.1.246 или позже.

agent_needs_input для вопроса настройки терминала товарища по команде требует Claude Code v2.1.248 или позже.

Claude Code рассчитывает permission_prompt по-другому в сеансах, где он отправляет запросы разрешений на callback Agent SDK canUseTool, что является тем, как Claude Desktop и расширение VS Code размещают Claude Code:

• Ожидайте permission_prompt около шести секунд после того, как Claude просит разрешение. Claude Code не откладывает его, пока вы печатаете.
• Если вы или hook PermissionRequest ответите раньше, Claude Code не запускает permission_prompt.
• Установите CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS на 1 для отключения permission_prompt в этих сеансах.

До версии 2.1.233, permission_prompt не срабатывал в этих сеансах.

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

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Notification input

Помимо common input fields, hooks Notification получают message с текстом уведомления, опциональный title и notification_type, указывающий, какой тип срабатывает.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Hooks Notification не могут блокировать или изменять уведомления. Claude Code отбрасывает их поля systemMessage и continue, но все еще выдает terminalSequence, на которое полагается пример уведомления рабочего стола. Hooks Notification предназначены для побочных эффектов, таких как пересылка уведомления во внешний сервис.

SubagentStart

Запускается, когда Claude порождает подагента с инструментом Agent, когда Claude возобновляет подагента и каждый раз, когда товарищ по команде agent team в процессе обрабатывает новое сообщение. Поддерживает matchers для фильтрации по имени типа агента. Для встроенных агентов это имя агента, такое как general-purpose, Explore или Plan. Для custom subagents, это поле name из frontmatter агента, а не имя файла.

Для подагентов, поставляемых plugin, тип агента — это идентификатор с областью действия plugin, такой как my-plugin:reviewer, а не голое имя frontmatter. Двоеточие помещает имя с областью действия plugin на путь регулярного выражения, поэтому якорьте matcher с ^ и $ для точного совпадения: ^my-plugin:reviewer$.

SubagentStart input

Помимо common input fields, hooks SubagentStart получают agent_id с уникальным идентификатором для подагента и agent_type с именем агента, который matcher фильтрует.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

Hooks SubagentStart не могут блокировать создание подагента, но они могут внедрить контекст в подагента. Помимо JSON output fields, доступных всем hooks, вы можете вернуть:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

Когда hook запускается снова для того же подагента, Claude Code внедряет возвращенный контекст только, когда контекст подагента уже не содержит копию из более раннего запуска. Копия, внедренная при запуске, остается на месте, оставляя prompt cache подагента нетронутым. После auto-compaction отбрасывает эту копию, Claude Code внедряет контекст следующего запуска снова.

SubagentStop

Запускается, когда подагент Claude Code закончил отвечать. Совпадает с типом агента, те же значения, что и SubagentStart.

SubagentStop input

Помимо common input fields, hooks SubagentStop получают stop_hook_active, agent_id, agent_type, agent_transcript_path и last_assistant_message. Поле agent_type — это значение, используемое для фильтрации matcher. transcript_path — это транскрипт основного сеанса, в то время как agent_transcript_path — это собственный транскрипт подагента, хранящийся в вложенной папке subagents/. Поле last_assistant_message содержит текстовое содержимое финального ответа подагента, поэтому hooks могут получить доступ к нему без анализа файла транскрипта.

На Claude Code v2.1.271 или позже подагент, который выполняется с инструментом SubagentHandback, доставляет свой отчет через этот инструмент перед остановкой. Поле last_assistant_message затем содержит закрывающий текст подагента, если есть, который не является доставленным отчетом. Отчет — это ввод message этого вызова, который hook PreToolUse или PostToolUse, совпадающий на SubagentHandback, получает как tool_input.message.

Hooks SubagentStop также получают массивы background_tasks и session_crons, описанные в Stop input. Оба массива ограничены родительским сеансом, а не подагентом.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

Hooks SubagentStop используют тот же формат управления решением, что и Stop hooks, включая hookSpecificOutput.additionalContext с hookEventName, установленным на "SubagentStop", для обратной связи без ошибок, которая держит подагента работающим. Возврат decision: "block" с reason держит подагента работающим и доставляет reason подагенту как его следующую инструкцию. Hook, который блокирует выходом 2, доставляет его сообщение stderr так же. Чтобы внедрить контекст в родительский сеанс после возврата подагента, используйте hook PostToolUse на инструменте Agent вместо этого.

TaskCreated

Запускается, когда задача создается через инструмент TaskCreate. Используйте это для применения соглашений об именовании, требования описаний задач или предотвращения создания определенных задач. В сеансе без инструментов Task, это событие не срабатывает.

Hooks TaskCreated не поддерживают matchers и срабатывают при каждом возникновении.

TaskCreated input

Помимо common input fields, hooks TaskCreated получают task_id, task_subject и опционально task_description, teammate_name и team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCreated decision control

Hook TaskCreated может заблокировать создание двумя способами. В любом случае Claude Code удаляет задачу и возвращает ваше сообщение Claude как ошибку инструмента. Claude Code игнорирует continue: false из этого события и Claude продолжает работать.

• Exit code 2: Claude Code возвращает текст stderr как сообщение.
• JSON {"decision": "block", "reason": "..."}: Claude Code возвращает reason как сообщение.

Этот пример блокирует задачи, чьи названия не следуют требуемому формату:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

Запускается, когда задача отмечается как завершенная. Это срабатывает в двух ситуациях: когда любой агент явно отмечает задачу как завершенную через инструмент TaskUpdate или когда товарищ по команде agent team завершает свой ход с выполняющимися задачами. Используйте это для применения критериев завершения, таких как прохождение тестов или проверок lint, перед закрытием задачи.

Hooks TaskCompleted не поддерживают matchers и срабатывают при каждом возникновении.

TaskCompleted input

Помимо common input fields, hooks TaskCompleted получают task_id, task_subject и опционально task_description, teammate_name и team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCompleted decision control

Hooks TaskCompleted поддерживают два способа управления завершением задачи:

• Exit code 2: задача не отмечается как завершенная и сообщение stderr передается обратно модели как обратная связь.
• JSON {"continue": false, "stopReason": "..."}: когда событие запустил товарищ по команде, завершающий свой ход, полностью останавливает товарища по команде, совпадая с поведением hook Stop. stopReason показывается пользователю. Когда событие запустил инструмент TaskUpdate, Claude Code игнорирует continue: false; выход 2 все еще блокирует завершение.

Этот пример запускает тесты и блокирует завершение задачи, если они не проходят:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

Запускается, когда основной агент Claude Code закончил отвечать. Не запускается, если остановка произошла из-за прерывания пользователем. Ошибки API срабатывают StopFailure вместо этого.

Stop input

Помимо common input fields, hooks Stop получают stop_hook_active, last_assistant_message, background_tasks и session_crons. Поле stop_hook_active имеет значение true, когда Claude Code уже продолжает в результате hook stop. Проверьте это значение или обработайте транскрипт, чтобы избежать блокирования на условии, которое никогда не разрешится. Claude Code переопределяет hook и заканчивает ход после 8 последовательных блокировок.

Поле last_assistant_message содержит текстовое содержимое финального ответа Claude, поэтому hooks могут получить доступ к нему без анализа файла транскрипта. Для hooks, которые действуют на только что завершенный ход, такие как hooks чтения вслух или уведомления, используйте это поле, а не читайте transcript_path: файл транскрипта не гарантируется включать финальное сообщение в момент Stop на всех версиях.

Массивы background_tasks и session_crons позволяют hooks различать "сеанс завершен" от "сеанс приостановлен в ожидании фоновой работы для пробуждения его обратно". Оба массива присутствуют, когда реестр задач доступен и пусты, когда ничего не выполняется или не запланировано.

Каждая запись в background_tasks описывает одну выполняющуюся задачу и использует эти поля:

Каждая запись в session_crons описывает одно запланированное пробуждение с областью действия сеанса, полученное из CronCreate, ScheduleWakeup и /loop:

Этот пример показывает ввод Stop с одной выполняющейся задачей shell и одним повторяющимся cron:

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Stop decision control

Hooks Stop и SubagentStop могут управлять тем, продолжает ли Claude. Помимо JSON output fields, доступных всем hooks, ваш скрипт hook может вернуть эти поля, специфичные для события:

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

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

Используйте additionalContext, когда hook работает как задумано и дает Claude руководство, такое как "запустить набор тестов перед завершением". Это держит разговор идущим через те же защиты цикла, что и decision: "block", а именно ввод stop_hook_active и ограничение 8 последовательных продолжений, но транскрипт помечает его как Stop hook feedback и никакое уведомление об ошибке hook не показывается:

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

Запускается вместо Stop, когда ход заканчивается из-за ошибки API. Claude Code игнорирует вывод и код выхода hook, кроме terminalSequence. Используйте это для логирования сбоев, отправки оповещений или принятия действий восстановления, когда Claude не может завершить ответ из-за ограничений скорости, проблем аутентификации или других ошибок API.

StopFailure input

Помимо common input fields, hooks StopFailure получают error, опциональный error_details и опциональный last_assistant_message. Поле error определяет тип ошибки и используется для фильтрации matcher.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

Hooks StopFailure не имеют управления решением. Они запускаются только в целях уведомления и логирования.

TeammateIdle

Запускается, когда товарищ по команде agent team собирается перейти в режим ожидания после завершения своего хода. Используйте это для применения шлюзов качества перед остановкой товарища по команде, такие как требование прохождения проверок lint или проверка существования выходных файлов.

Hooks TeammateIdle не поддерживают matchers и срабатывают при каждом возникновении.

TeammateIdle input

Помимо common input fields, hooks TeammateIdle получают teammate_name и team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

TeammateIdle decision control

Hooks TeammateIdle поддерживают два способа управления поведением товарища по команде:

• Exit code 2: товарищ по команде получает сообщение stderr как обратную связь и продолжает работать вместо перехода в режим ожидания.
• JSON {"continue": false, "stopReason": "..."}: полностью останавливает товарища по команде, совпадая с поведением hook Stop. stopReason показывается пользователю.

Этот пример проверяет, что артефакт сборки существует перед разрешением товарищу по команде перейти в режим ожидания:

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

Запускается, когда файл конфигурации изменяется во время сеанса. Используйте это для аудита изменений настроек, применения политик безопасности или блокирования несанкционированных изменений файлов конфигурации.

Claude Code запускает hooks ConfigChange, когда файл настроек, файл управляемой политики или файл skill изменяется. Для управляемой политики он запускает их только, когда managed-settings.json или файл в managed-settings.d/ изменяется. Он применяет server-managed settings и изменения в macOS управляемых предпочтениях или политике реестра Windows без запуска их. На WSL с wslInheritsWindowsSettings, он также применяет измененный файл управляемых настроек Windows на его опросе политики без запуска их.

Matcher фильтрует по источнику конфигурации:

Этот пример логирует все изменения конфигурации для аудита безопасности:

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

ConfigChange input

Помимо common input fields, hooks ConfigChange получают source и опционально file_path. Поле source указывает, какой тип конфигурации изменился, и file_path предоставляет путь к конкретному файлу, который был изменен.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

ConfigChange decision control

Hooks ConfigChange могут заблокировать изменения конфигурации от вступления в силу. Используйте выход 2 или JSON decision для предотвращения изменения. При блокировании новые настройки не применяются к работающему сеансу.

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

Изменения policy_settings не могут быть заблокированы. Hooks все еще срабатывают для источников policy_settings, когда файл управляемых настроек на машине изменяется, поэтому вы можете использовать их для логирования этих редактирований, но любое решение блокировки игнорируется. Это гарантирует, что параметры, управляемые предприятием, всегда вступают в силу. Claude Code не запускает hooks ConfigChange, когда server-managed settings приходят или обновляются.

Claude Code действует на решение блокировки из JSON вывода hook ConfigChange и отбрасывает systemMessage и continue. Заблокированное изменение не выводит никакого сообщения вам или Claude, независимо от того, блокируете ли вы с reason или с stderr при выходе 2. Claude Code только пишет строку в debug log.

CwdChanged

Запускается, когда команда shell в основном разговоре изменяет рабочую директорию, например когда Claude выполняет команду cd. Используйте это для реакции на изменения директории: перезагрузка переменных окружения, активация цепочек инструментов, специфичных для проекта, или автоматический запуск скриптов настройки. Пары с FileChanged для инструментов, таких как direnv, которые управляют окружением для каждой директории.

Hooks CwdChanged имеют доступ к CLAUDE_ENV_FILE. Переменные, записанные в этот файл, сохраняются в последующих командах Bash до следующего события CwdChanged, когда Claude Code очищает их.

CwdChanged не поддерживает matchers и срабатывает при каждом возникновении.

CwdChanged input

Помимо common input fields, hooks CwdChanged получают old_cwd и new_cwd.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

CwdChanged output

Помимо JSON output fields, доступных всем hooks, hooks CwdChanged могут вернуть watchPaths для динамической установки того, какие пути файлов FileChanged наблюдает:

Hooks CwdChanged не имеют управления решением. Они не могут заблокировать изменение директории.

Claude Code читает watchPaths и systemMessage из их JSON вывода и отбрасывает continue. В интерактивных сеансах он показывает systemMessage как краткое уведомление терминала. Сообщение не достигает потока сообщений SDK.

DirectoryAdded

Запускается после добавления рабочей директории во время сеанса с командой /add-dir или после добавления SDK клиентом с запросом управления register_repo_root. Используйте это для подготовки вновь добавленного репозитория, например установкой его зависимостей.

Claude Code не срабатывает это событие, когда:

• Вы передаете директорию с флагом запуска --add-dir; SessionStart охватывает эти директории
• Вы добавляете директорию на вкладку /permissions Workspace
• Вы добавляете директорию, которая уже является рабочей директорией или находится внутри одной

Claude Code срабатывает DirectoryAdded после обновления состояния sandbox и разрешений, поэтому изолированные инструменты уже видят новую директорию, когда выполняется ваш hook. Команды hook сами выполняются неизолированными.

Claude Code не ждет hook: добавление завершается немедленно, и hook выполняется в фоне с стандартным timeout 600 секунд.

Matcher фильтрует по тому, как была добавлена директория:

DirectoryAdded input

Помимо common input fields, hooks DirectoryAdded получают directory и source.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

Hooks DirectoryAdded не имеют управления решением. Они не могут заблокировать добавление, которое уже завершилось, когда выполняется hook. Claude Code отбрасывает поле continue из их JSON вывода и выводит остальное по-другому в зависимости от источника:

• slash_command: Claude Code доставляет вывод systemMessage hook Claude как контекст на следующем ходе разговора, а не показывает вам. Количество неудачных hooks появляется в транскрипте. Полный вывод сбоя идет в debug log
• register_repo_root: Claude Code пишет вывод systemMessage и вывод сбоя в debug log только

FileChanged

Запускается, когда наблюдаемый файл изменяется на диске. Claude Code обнаруживает изменения с помощью наблюдателя файловой системы, а не путем проверки вызовов инструментов, поэтому он запускает hook независимо от того, что изменило файл: вызов инструмента Edit или Write, скрипт, который Claude запускает с Bash, или процесс вне Claude Code. Обычное использование — перезагрузка переменных окружения, когда изменяются файлы конфигурации проекта.

matcher для этого события служит двум целям:

• Build the watch list: значение разделяется на | и каждый сегмент регистрируется как буквальное имя файла в рабочей директории, поэтому ".envrc|.env" наблюдает ровно эти два файла. Шаблоны regex не полезны здесь: значение, такое как ^\.env, наблюдало бы файл буквально названный ^\.env.
• Filter which hooks run: когда наблюдаемый файл изменяется, то же значение фильтрует, какие группы hook запускаются, используя стандартные matcher rules против базового имени измененного файла.

Этот пример нормализует окончания строк в data.csv после любого изменения, включая вызов инструмента Bash или внешний скрипт, переписывающий файл:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

Hook читает абсолютный путь измененного файла из поля file_path JSON input на stdin. Его guard grep тестирует то же самое, что perl удаляет, CR в конце строки, поэтому запуск после нормализации выходит без касания файла. Более слабый guard зацикливается навсегда, потому что perl -i переписывает файл даже когда он ничего не подставляет и Claude Code запускает hook снова после каждой переписи. Сохраните этот скрипт в /path/to/normalize-line-endings.sh и сделайте его исполняемым:

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

Чтобы подтвердить, что hook работает, попросите Claude добавить строку CRLF в data.csv с командой Bash. Claude Code запускает hook и файл заканчивается с окончаниями LF.

Чтобы наблюдать файлы, которые вы не можете назвать заранее, верните watchPaths из hook для динамического обновления списка наблюдения. Claude Code запускает наблюдатель только, когда что-то называет файл для наблюдения, поэтому посейте список с группой FileChanged, чей matcher называет по крайней мере один файл, или с hook SessionStart или CwdChanged, который возвращает watchPaths. Matcher все еще фильтрует, какие группы hook запускаются, когда наблюдаемый файл изменяется, поэтому дайте группе, которая обрабатывает динамические пути, опущенный matcher, который совпадает с каждым наблюдаемым файлом и ничего не добавляет в список наблюдения. Matcher "*" также совпадает с каждым файлом, но Claude Code регистрирует его в списке наблюдения, как любое другое значение, как буквальный файл названный *.

Hooks FileChanged имеют доступ к CLAUDE_ENV_FILE. Переменные, записанные в этот файл, сохраняются в последующих командах Bash до следующего события CwdChanged, когда Claude Code очищает их.

FileChanged input

Помимо common input fields, hooks FileChanged получают file_path и event.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

FileChanged output

Помимо JSON output fields, доступных всем hooks, hooks FileChanged могут вернуть watchPaths для динамического обновления того, какие пути файлов наблюдаются:

Hooks FileChanged не имеют управления решением. Они не могут заблокировать изменение файла от возникновения.

Claude Code читает watchPaths и systemMessage из их JSON вывода и отбрасывает continue. В интерактивных сеансах он показывает systemMessage как краткое уведомление терминала. Сообщение не достигает потока сообщений SDK.

WorktreeCreate

Запускается, когда создается worktree, будь то из claude --worktree, из subagent using isolation: "worktree" или для background session, которую Claude Code изолирует в своем собственном worktree. По умолчанию Claude Code создает изолированную рабочую копию с git worktree. Настройка hook WorktreeCreate заменяет это поведение git по умолчанию, позволяя вам использовать другую систему контроля версий, такую как SVN, Perforce или Mercurial.

Поскольку hook заменяет поведение по умолчанию полностью, .worktreeinclude не обрабатывается. Если вам нужно скопировать локальные файлы конфигурации, такие как .env, в новый worktree, сделайте это внутри вашего скрипта hook.

Hook должен вернуть путь к созданной директории worktree. Claude Code использует этот путь как рабочую директорию для изолированного сеанса. См. WorktreeCreate output для того, как каждый тип hook возвращает путь.

Claude Code действует на успех hook и возвращенный путь и отбрасывает systemMessage и continue.

Этот пример создает рабочую копию SVN и выводит путь для использования Claude Code. Замените URL репозитория на свой собственный:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Hook читает имя worktree name из JSON ввода на stdin, проверяет свежую копию в новую директорию и выводит путь директории. echo на последней строке — это то, что Claude Code читает как путь worktree. Перенаправьте любой другой вывод в stderr, чтобы он не мешал пути.

WorktreeCreate input

Помимо common input fields, hooks WorktreeCreate получают поле name. Это идентификатор slug для нового worktree, либо указанный пользователем, либо автоматически сгенерированный, например bold-oak-a3f2.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

WorktreeCreate output

Hooks WorktreeCreate не используют стандартную модель решения разрешить/заблокировать. Вместо этого успех или сбой hook определяет результат. Hook должен вернуть путь к созданной директории worktree:

• Command hooks (type: "command"): выведите путь как последнюю непустую строку stdout. Claude Code удаляет коды ANSI перед чтением этой строки, поэтому баннеры запуска shell, выведенные перед вашим echo, игнорируются. Перенаправьте любой другой вывод hook в stderr.
• HTTP hooks (type: "http"): верните { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } в теле ответа.

Если hook не удается или не создает путь, создание worktree не удается с ошибкой.

Claude Code разрешает относительный путь против директории, в которой выполнялся hook, свернув любые сегменты . или .. в нем. Если результирующий путь не является директорией, которую Claude Code может ввести, сеанс выводит ошибку, называющую путь, и выходит с кодом 1.

Claude Code отказывает абсолютному пути, который содержит сегменты . или .., и любому пути, который проходит через symlink ниже корня репозитория, потому что symlink, зафиксированный в репозитории, может перенаправить worktree вне его. Ошибка называет отклоненный компонент. Верните нормализованный путь, который не проходит через symlink внутри репозитория. До версии 2.1.216 создание worktree следовало пути hook без этого скрининга.

WorktreeRemove

Запускается, когда worktree удаляется. Это очистка, соответствующая WorktreeCreate. Событие срабатывает, когда:

• вы выходите из сеанса --worktree и выбираете его удаление
• подагент с isolation: "worktree" завершается
• вы удаляете background session, чей worktree создал hook

Для git-based worktrees Claude Code обрабатывает очистку автоматически с git worktree remove. Если вы настроили hook WorktreeCreate для системы контроля версий, не основанной на git, соедините его с hook WorktreeRemove для обработки очистки. Без него директория worktree остается на диске.

Claude Code отбрасывает JSON output fields hook WorktreeRemove, такие как systemMessage и continue.

Для удаления сеанса фонового плана Claude Code проверяет сохраненный путь worktree перед запуском hook и отказывает пути, который является symlink или проходит через один ниже корня репозитория. Hook запускается для worktree, который все еще содержит файлы только, когда вы подтверждаете удаление в agent view; для такого worktree, claude rm сохраняет сеанс и worktree вместо этого. До версии 2.1.216 hook запускался на сохраненном пути без этих проверок.

Claude Code передает путь, возвращенный WorktreeCreate, как worktree_path в ввод hook. Этот пример читает этот путь и удаляет директорию:

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

WorktreeRemove input

Помимо common input fields, hooks WorktreeRemove получают поле worktree_path, которое является абсолютным путем к удаляемому worktree.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

Код выхода hook WorktreeRemove определяет результат. Когда hook выходит с ненулевым кодом и директория в worktree_path все еще существует после этого, удаление не удается:

• Worktree остается на диске, и команда hook и stderr идут в debug log.
• Если вы удаляли фоновый сеанс, сеанс также остается. Сообщение отказа в agent view сообщает, как закончился hook, такой как exited 1, цитирует начало его stderr и говорит, удаляет ли удаление сеанса снова директорию в любом случае.

PreCompact

Запускается перед тем, как Claude Code собирается запустить операцию compact.

Значение matcher указывает, было ли сжатие запущено вручную или автоматически:

Выход с кодом 2 для блокирования сжатия. Для ручного /compact, сообщение stderr показывается пользователю. Вы также можете заблокировать, возвращая JSON с "decision": "block".

Блокирование автоматического сжатия имеет разные эффекты в зависимости от того, когда оно срабатывает. Если сжатие было запущено упреждающе перед пределом контекста, Claude Code пропускает его и разговор продолжается несжатым. Если сжатие было запущено для восстановления от ошибки лимита контекста, уже возвращенной API, основная ошибка выводится и текущий запрос не удается.

Claude Code отбрасывает поля systemMessage и continue hook PreCompact.

PreCompact input

Помимо common input fields, hooks PreCompact получают trigger и custom_instructions. Для manual, custom_instructions содержит то, что пользователь передает в /compact и имеет значение null, когда они ничего не передают. Для auto, custom_instructions имеет значение null.

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

PostCompact

Запускается после завершения операции compact Claude Code. Используйте это событие для реакции на новое сжатое состояние, например для логирования сгенерированной сводки или обновления внешнего состояния. Claude Code отбрасывает поля systemMessage и continue hook PostCompact.

Те же значения matcher применяются, как для PreCompact:

PostCompact input

Помимо common input fields, hooks PostCompact получают trigger и compact_summary. Поле compact_summary содержит сводку разговора, сгенерированную операцией compact.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

Hooks PostCompact не имеют управления решением. Они не могут влиять на результат сжатия, но могут выполнять последующие задачи.

PreModelSwitch

Запускается перед применением переключения модели, которое вы или клиент запросили. Используйте это для блокирования переключения, требования подтверждения или показа стоимости переключения перед его выполнением.

PreModelSwitch требует Claude Code v2.1.251 или позже. Claude Code запускает его для этих запросов:

• /model <name> и средство выбора /model
• Средство выбора модели Option+P или Alt+P
• Параметр Model в /config
• Включение fast mode, когда это изменяет модель сеанса
• Запрос set_model или изменение модели в запросе apply_flag_settings от хоста Agent SDK или Remote Control

Claude Code не запускает hooks PreModelSwitch для переключений, которые он делает самостоятельно, такие как automatic model fallback или восстановление модели при возобновлении сеанса. Эти изменения достигают PostModelSwitch только.

Claude Code сравнивает matcher против канонического имени модели, на которую сеанс переключается, игнорируя любой суффикс [1m]. Alias, такой как opus, датированный ID модели и ID, специфичный для поставщика, такой как ID модели Amazon Bedrock, все совпадают с одним каноническим именем, на которое они разрешаются, поэтому claude-opus-5 охватывает каждое написание Opus 5.

Когда Claude Code не может определить каноническое имя для цели, например пользовательский ID модели, который знает только ваш LLM gateway, он запускает каждый hook PreModelSwitch независимо от matcher. Hook, который блокирует, должен поэтому проверить to_model из своего ввода, а не полагаться только на matcher.

Напишите matcher как точное имя, список, разделенный |, такой как claude-opus-4-6|claude-opus-5, или регулярное выражение, такое как .*opus.*. Этот пример использует matcher точного имени и также проверяет to_model из ввода hook, поэтому он отказывает переключению на Opus 4.6 выходом 2 и позволяет любой другой цели пройти:

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

Чтобы подтвердить, что hook работает, запустите /model claude-opus-4-6 из сеанса, работающего на другой модели. Claude Code сохраняет текущую модель и сообщает, что hook PreModelSwitch заблокировал переключение, с вашим сообщением как причиной.

PreModelSwitch input

Помимо common input fields, hooks PreModelSwitch получают поля в этой таблице. Последние пять описывают, что стоит повторная отправка разговора на новую модель, поэтому hook может показать эту цифру перед переключением.

Этот пример показывает ввод для /model opus в сеансе, работающем на Sonnet 5:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

PreModelSwitch decision control

Hooks PreModelSwitch могут отменить переключение, попросить пользователя подтвердить его или позволить ему продолжить. Выход 2 или decision: "block" верхнего уровня отменяет переключение.

Для более тонкого контроля, верните permissionDecision и permissionDecisionReason в объекте hookSpecificOutput, как на PreToolUse. PreModelSwitch принимает "allow", "deny" и "ask". Он не принимает "defer", updatedInput или additionalContext. Таблица ниже описывает оба поля:

Только /model в интерактивном сеансе может показать подсказку "ask". На каждой другой поверхности, включая неинтерактивный режим с флагом -p, /config и запросы set_model, Claude Code рассматривает "ask" как отказ.

Этот пример просит пользователя подтвердить и цитирует количество токенов из context_tokens:

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

Когда несколько hooks PreModelSwitch возвращают разные решения, приоритет — deny > ask > allow.

Claude Code показывает пользователю любой systemMessage, который возвращает ваш hook, независимо от решения, поэтому hook отчета стоимости может вернуть {"systemMessage": "..."} и выход 0.

Hook PreModelSwitch, который не отвечает перед своим timeout, блокирует переключение. На PreToolUse, напротив, hook command, который истекает timeout, позволяет вызову инструмента продолжить. Стандартный timeout для этого события составляет 30 секунд. PreModelSwitch запускает только hooks command, http и mcp_tool, поэтому стандартные значения prompt и agent не применяются.

Hook, который выходит с кодом, отличным от 0 или 2, и не выводит JSON решение, не блокирует: Claude Code показывает его stderr и применяет переключение, как описано в Other exit codes.

PostModelSwitch

Запускается после изменения модели сеанса. Используйте это для предоставления руководства, специфичного для модели, без редактирования каждого CLAUDE.md, например инструкции на уровне организации, которая применяется на определенных моделях.

PostModelSwitch требует Claude Code v2.1.251 или позже. Он не может блокировать, потому что модель уже изменилась. Claude Code запускает hooks PostModelSwitch после любого из этих изменений:

• Переключение, которое вы или клиент запросили
• Automatic model fallback, которое изменяет модель сеанса
• Параметр, такой как opusplan, входящий или выходящий из режима плана
• Claude Code восстанавливает модель при возобновлении сеанса

Claude Code не запускает hooks PostModelSwitch, когда модель из fallback model chain служит ходу, потому что это замещение длится один ход и оставляет модель сеанса неизменной.

Matcher следует тем же правилам, что и PreModelSwitch: Claude Code сравнивает его против канонического имени модели, на которую переключился сеанс.

Этот пример добавляет руководство, когда модель сеанса изменяется на любую модель Opus:

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

Чтобы подтвердить, что hook работает, переключитесь на модель Opus из сеанса, работающего на другой модели, например запустите /model opus из сеанса Sonnet, затем попросите Claude, какое руководство оно имеет о текущей модели.

PostModelSwitch input

Hooks PostModelSwitch получают те же поля, что и PreModelSwitch, с hook_event_name, установленным на "PostModelSwitch", и двумя дополнительными значениями source: "auto" для автоматического fallback или другого изменения, которое Claude Code сделал самостоятельно, и "resume" для модели, восстановленной при возобновлении сеанса.

requested_model имеет значение null, когда source имеет значение "auto". Когда source имеет значение "resume", это сохраненный параметр модели, который Claude Code восстановил.

PostModelSwitch decision control

Claude Code берет ваш вывод hook plain-text stdout при выходе 0 или additionalContext из JSON вывода и доставляет его Claude со следующим запросом после переключения. Помимо JSON output fields, доступных всем hooks, вы можете вернуть:

Если hook не завершится в течение пяти секунд после отправки следующей подсказки, Claude Code отправляет этот запрос без вывода и прикрепляет его к следующему запросу вместо этого. Если модель изменяется несколько раз перед следующим запросом, Claude Code доставляет только вывод для последнего переключения целевой модели.

SessionEnd

Запускается, когда сеанс Claude Code заканчивается. Полезно для задач очистки, логирования статистики сеанса или сохранения состояния сеанса. Поддерживает matchers для фильтрации по причине выхода.

Поле reason в ввод hook указывает, почему сеанс закончился:

SessionEnd input

Помимо common input fields, hooks SessionEnd получают поле reason, указывающее, почему сеанс закончился. См. таблицу reason выше для всех значений.

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

Hooks SessionEnd не имеют управления решением. Они не могут заблокировать завершение сеанса, но могут выполнять задачи очистки. Claude Code отбрасывает их JSON output fields, такие как systemMessage.

Hooks SessionEnd имеют стандартный timeout 1.5 секунды. Он применяется, когда вы выходите, запускаете /clear или переключаете сеансы с интерактивным /resume. Вы можете дать hook больше времени двумя способами:

• Per-hook timeout: установите timeout в конфигурации этого hook. Общий бюджет автоматически повышается, чтобы совпадать с наивысшим timeout для каждого hook в ваших файлах настроек, до 60 секунд. Если вы повышаете бюджет таким образом, hook без своего собственного timeout все еще сохраняет стандартный. Timeouts, установленные на hooks, предоставленные plugin, не повышают бюджет.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS: установите эту переменную окружения в миллисекундах для явного переопределения бюджета. Значение, которое вы установили, также становится timeout для каждого hook без своего собственного timeout.

Этот пример устанавливает бюджет на 5 секунд:

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

До версии 2.1.268, CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS повышал только общий бюджет, и hook без своего собственного timeout все еще отменялся после 1.5 секунды.

Elicitation

Запускается, когда сервер MCP запрашивает ввод пользователя во время задачи. По умолчанию Claude Code показывает интерактивный диалог для ответа пользователя. Hooks могут перехватить этот запрос и ответить программно, полностью пропустив диалог.

Поле matcher совпадает с именем сервера MCP.

Elicitation input

Помимо common input fields, hooks Elicitation получают mcp_server_name, message и опциональные поля mode, url, elicitation_id и requested_schema.

Для запроса в режиме формы, наиболее распространенный случай:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

Для запроса в режиме URL, используемого для аутентификации на основе браузера:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Elicitation output

Чтобы ответить программно без показа диалога, верните JSON объект с hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

Выход 2 отклоняет запрос. Claude Code не показывает ваше сообщение stderr нигде.

Claude Code действует на hookSpecificOutput из JSON вывода hook Elicitation и отбрасывает systemMessage и continue.

ElicitationResult

Запускается после ответа пользователя на запрос MCP. Hooks могут наблюдать, изменять или блокировать ответ перед его отправкой обратно на сервер MCP.

Поле matcher совпадает с именем сервера MCP.

ElicitationResult input

Помимо common input fields, hooks ElicitationResult получают mcp_server_name, action и опциональные поля mode, elicitation_id и content.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

ElicitationResult output

Чтобы переопределить ответ пользователя, верните JSON объект с hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

Выход 2 блокирует ответ, изменяя эффективное действие на decline. Claude Code не показывает ваше сообщение stderr нигде.

Claude Code действует на hookSpecificOutput из JSON вывода hook ElicitationResult и отбрасывает systemMessage и continue.

Prompt-based hooks

В дополнение к command, HTTP и MCP tool hooks, Claude Code поддерживает prompt-based hooks (type: "prompt"), которые используют LLM для оценки разрешения или блокировки действия, и agent hooks (type: "agent"), которые порождают агентного верификатора с доступом к инструментам. Не все события поддерживают каждый тип hook.

События, которые поддерживают все пять типов hook (command, http, mcp_tool, prompt и agent):

• PermissionDenied
• PermissionRequest
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

События, которые поддерживают command, http и mcp_tool hooks, но не prompt или agent:

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart и Setup поддерживают command и mcp_tool hooks, и MCP tool hook fields описывает, когда их mcp_tool hooks запускаются. Они не поддерживают http, prompt или agent hooks.

How prompt-based hooks work

Вместо выполнения команды Bash, prompt-based hooks:

1. Отправляют входные данные hook и вашу подсказку модели Claude, Haiku по умолчанию
2. LLM отвечает структурированным JSON, содержащим решение
3. Claude Code автоматически обрабатывает решение

Prompt hook configuration

Установите type на "prompt" и предоставьте строку prompt вместо command. Используйте заполнитель $ARGUMENTS для внедрения данных JSON входа hook в текст вашей подсказки.

Этот hook Stop просит LLM оценить, должен ли Claude остановиться перед разрешением Claude закончить:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

Response schema

LLM должен ответить JSON, содержащим:

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

Что происходит при ok: false, зависит от события:

• Stop и SubagentStop: причина передаётся обратно Claude как его следующая инструкция и ход продолжается, если только ответ также не устанавливает impossible: true, в этом случае Claude Code позволяет остановке и ход заканчивается
• PreToolUse: вызов инструмента отклоняется; по умолчанию ход заканчивается и причина отказа появляется в чате как строка предупреждения. Установите continueOnBlock: true для возврата причины Claude как ошибки инструмента, чтобы он мог скорректировать и продолжить, эквивалентно permissionDecision: "deny" из command hook. До v2.1.210 причина отказа возвращалась Claude как ошибка инструмента и ход продолжался
• PostToolUse: по умолчанию ход заканчивается и причина появляется в чате как строка предупреждения. Установите continueOnBlock: true для передачи причины обратно Claude и продолжения хода вместо этого
• PostToolBatch, UserPromptSubmit и UserPromptExpansion: ход заканчивается и причина появляется как строка предупреждения. Эти события заканчивают ход на decision: "block" независимо от continue
• PostToolUseFailure и TaskCreated: причина возвращается Claude как ошибка инструмента и ход продолжается, независимо от continueOnBlock
• TaskCompleted: когда он срабатывает, потому что задача отмечена как завершённая во время хода, причина возвращается Claude как ошибка инструмента и ход продолжается, независимо от continueOnBlock. Когда он срабатывает, потому что товарищ по команде останавливается, он ведёт себя как TeammateIdle и останавливает товарища по команде по умолчанию
• TeammateIdle: по умолчанию товарищ по команде останавливается и причина появляется как строка предупреждения. Установите continueOnBlock: true для передачи причины обратно товарищу по команде и продолжения его работы вместо этого
• PermissionRequest: ok: false не имеет эффекта. Чтобы отклонить одобрение из hook, используйте command hook, возвращающий hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied: ok: false не имеет эффекта, потому что отказ уже произошёл. Единственный результат, который это событие читает, это hookSpecificOutput.retry, который prompt и agent hooks не могут установить. Они запускаются на этом событии, но их результат отбрасывается. Используйте command hook для возврата retry

Если вам нужен более точный контроль над любым событием, используйте command hook с полями для каждого события, описанными в Decision control.

Check multiple conditions before stopping

Этот hook Stop использует подробную подсказку для проверки трёх условий перед разрешением Claude остановиться. Hooks SubagentStop используют тот же формат для оценки, должен ли subagent остановиться. Если модель возвращает "ok": false, потому что условие ещё не выполнено, Claude продолжает работать с предоставленной причиной как своей следующей инструкцией:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Agent-based hooks

Agent-based hooks (type: "agent") похожи на prompt-based hooks, но с многооборотным доступом к инструментам. Вместо одного вызова LLM, agent hook порождает subagent, который может читать файлы, искать код и проверять кодовую базу для проверки условий. Agent hooks поддерживают те же события, что и prompt-based hooks.

How agent hooks work

Когда срабатывает agent hook:

1. Claude Code порождает subagent с вашей подсказкой и JSON входом hook
2. Subagent может использовать инструменты, такие как Read, Grep и Glob, для исследования
3. После до 50 оборотов subagent возвращает структурированное решение { "ok": true/false }
4. Claude Code разрешает действие, если ok имеет значение true. Если ok имеет значение false, Claude Code обрабатывает блокировку так же, как prompt hook с continueOnBlock: true на этом событии, как указано в разделе Response schema

Agent hooks полезны, когда проверка требует проверки фактических файлов или выхода тестов, а не только оценки данных входа hook.

Agent hook configuration

Установите type на "agent" и предоставьте строку prompt, используя $ARGUMENTS как заполнитель для JSON входа hook. Поля конфигурации те же, что и prompt hooks, за исключением того, что agent hooks имеют более длинный таймаут по умолчанию в 60 секунд и не имеют поля continueOnBlock.

Схема ответа — это { "ok": true } для разрешения или { "ok": false, "reason": "..." } для блокировки. При ok: false, Claude Code обрабатывает agent hook так же, как он обрабатывает prompt hook с continueOnBlock: true на том же событии; agent hooks не имеют поля continueOnBlock и не поддерживают поле impossible из prompt hook.

Этот hook Stop проверяет, что все модульные тесты проходят перед разрешением Claude закончить:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Запуск hooks в фоне

По умолчанию hooks блокируют выполнение Claude до их завершения. Для долгоживущих задач, таких как развёртывания, наборы тестов или вызовы внешних API, установите "async": true для запуска hook в фоне, пока Claude продолжает работать. Асинхронные hooks не могут блокировать или управлять поведением Claude: поля ответа, такие как decision, permissionDecision и continue, не имеют эффекта, потому что действие, которое они контролировали, уже завершено.

Настройка асинхронного hook

Добавьте "async": true к конфигурации command hook для запуска его в фоне без блокировки Claude. Это поле доступно только на hooks type: "command".

Этот hook запускает скрипт тестирования после каждого вызова инструмента Write. Claude продолжает работать немедленно, пока run-tests.sh выполняется. Когда скрипт завершается, его выход доставляется на следующий ход разговора:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Как только асинхронный hook запущен в фоне, Claude Code не применяет timeout к нему. Claude Code по-прежнему применяет timeout к hook, который вы запускаете с asyncRewake.

Claude Code доставляет результаты асинхронного hook только во время работы сеанса:

• В неинтерактивном режиме с флагом -p Claude Code завершает любой асинхронный hook, который всё ещё работает при завершении, и завершает его с результатом cancelled
• Если работа вашего hook должна пережить сеанс claude -p, запустите полностью отделённый процесс из него

Как выполняются асинхронные hooks

Когда срабатывает асинхронный hook, Claude Code запускает процесс hook и немедленно продолжает без ожидания его завершения. Hook получает те же JSON входные данные через stdin, что и синхронный hook.

После выхода фонового процесса Claude Code доставляет поля additionalContext и systemMessage из JSON ответа hook к Claude на следующем ходу разговора. В отличие от systemMessage синхронного hook, ни одно из этих полей не показывается вам.

Claude Code проверяет, что JSON ответ соответствует той же схеме выходных данных, что и синхронные hooks, и отбрасывает любое поле, значение которого имеет неправильный тип, например systemMessage, который не является строкой, вместо его доставки. Запустите с --debug для просмотра предупреждения, называющего каждое отброшенное поле. До версии v2.1.202 неправильно сформированный JSON выход из асинхронного hook мог привести к сбою сеанса, и сбой повторялся каждый раз при возобновлении сеанса.

Уведомления о завершении асинхронного hook подавляются по умолчанию. Чтобы их увидеть, включите подробный режим с помощью Ctrl+O или запустите Claude Code с --verbose.

Запуск тестов после изменения файлов

Этот hook запускает набор тестов в фоне всякий раз, когда Claude пишет файл, затем сообщает результаты обратно Claude при завершении тестов. Сохраните этот скрипт в .claude/hooks/run-tests-async.sh в вашем проекте и сделайте его исполняемым с помощью chmod +x:

#!/bin/bash
# run-tests-async.sh

# Read hook input from stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Only run tests for source files
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Run tests and report results to Claude via additionalContext
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

Затем добавьте эту конфигурацию в .claude/settings.json в корне вашего проекта. Флаг async: true позволяет Claude продолжать работу, пока тесты запускаются:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

Ограничения

Асинхронные hooks имеют дополнительные ограничения по сравнению с синхронными hooks:

• Выход hook доставляется на следующий ход разговора. Если сеанс неактивен, ответ ждёт до следующего взаимодействия пользователя. Исключение: hook asyncRewake, который выходит с кодом 2, пробуждает Claude немедленно даже когда сеанс неактивен.
• Каждое выполнение создаёт отдельный фоновый процесс. Нет дедупликации между несколькими срабатываниями одного и того же асинхронного hook.

Соображения безопасности

Отказ от ответственности

Доверие рабочей области

Claude Code проверяет доверие рабочей области перед запуском любого hook из файла параметров. Что считается доверенным, зависит от типа сеанса:

• Интерактивный сеанс: Claude Code удерживает hooks из каждого файла параметров, включая ваш собственный ~/.claude/settings.json, пока вы не примете диалог доверия рабочей области для папки или для родительского каталога, чьё доверие распространяется на неё
• Сеанс -p или SDK: Claude Code никогда не показывает диалог и рассматривает папку как доверенную, поэтому hooks, зафиксированные в .claude/settings.json репозитория, запускаются в папке, которой вы никогда не доверяли

Перед тем как запустить claude -p над репозиторием, который вы не писали, проверьте его файлы параметров .claude/, начните с --bare или отключите hooks для этого запуска с помощью --settings '{"disableAllHooks": true}'. Frontmatter hooks в проектном подагенте следуют более строгому правилу, чем hooks файлов параметров. Что запускается перед доверием папке перечисляет каждый вид содержимого репозитория по типу сеанса.

Лучшие практики безопасности

Помните об этих практиках при написании hooks:

• Проверяйте и санитизируйте входные данные: никогда не доверяйте входным данным вслепую
• Всегда заключайте переменные оболочки в кавычки: используйте "$VAR" не $VAR
• Блокируйте обход пути: проверяйте наличие .. в путях файлов
• Используйте абсолютные пути: указывайте полные пути для скриптов. В форме exec используйте ${CLAUDE_PROJECT_DIR} и путь не требует кавычек. В форме shell оберните его в двойные кавычки
• Пропускайте чувствительные файлы: избегайте .env, .git/, ключей и т. д.

Windows PowerShell tool

На Windows вы можете запустить отдельные hooks в PowerShell, установив "shell": "powershell" на command hook. Claude Code автоматически обнаруживает pwsh.exe, исполняемый файл PowerShell 7 и более поздних версий, и переходит на powershell.exe для Windows PowerShell 5.1.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

Чтобы ссылаться на корневой каталог проекта из команды PowerShell в форме shell, напишите ${CLAUDE_PROJECT_DIR} или $env:CLAUDE_PROJECT_DIR. Начиная с версии 2.1.198, Claude Code переписывает заполнители ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} и ${CLAUDE_PLUGIN_DATA} в команде PowerShell в форме shell в форму ${env:NAME} PowerShell, независимо от того, определён ли hook в settings.json, плагине или навыке. PowerShell затем разрешает значение из экспортированного окружения после анализа, поэтому заполнитель работает внутри строк в двойных кавычках, но не внутри строк в одинарных кавычках, где PowerShell никогда не расширяет переменные.

До версии 2.1.198 эта переписка применялась только к plugin hooks. В более ранних версиях hook в settings.json требует формы $env: или exec form, где ${CLAUDE_PROJECT_DIR} подставляется в каждый элемент args независимо от того, где определён hook.

Не пишите простое написание $CLAUDE_PROJECT_DIR в hook PowerShell. PowerShell анализирует его как неопределённую локальную переменную и разрешает её в $null, что оставляет путь скрипта без префикса корневого каталога проекта. Claude Code не переписывает эту форму; вместо этого она регистрирует предупреждение в debug log.

Пример ниже показывает hook в settings.json, который запускает скрипт проекта с формой $env:, которая работает на каждой версии:

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

Debug hooks

Детали выполнения hooks записываются в файл отладочного журнала. Запустите Claude Code с claude --debug-file <path> для записи журнала в известное расположение, или запустите claude --debug и прочитайте журнал в ~/.claude/debug/<session-id>.txt. Флаг --debug не выводит на терминал.

Например, hook PostToolUse на Write, чья команда выводит hook-ran, создаёт записи вроде:

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

Для более детальной информации о совпадении hooks установите CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose для просмотра дополнительных строк логирования, таких как количество совпадений фильтра hook и совпадение запроса.

Для устранения неполадок распространённых проблем, таких как hooks, которые не срабатывают, Stop hooks, которые продолжают блокировать, или ошибки конфигурации, см. Limitations and troubleshooting в руководстве. Для более широкого диагностического пошагового руководства, охватывающего /context, /doctor и приоритет параметров, см. Debug your config.