SpyBara
Go Premium

agent-sdk/hooks.md 2026-10-06 23:59 UTC to 2026-10-07 15:59 UTC

This page contains 64 additions and 64 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sat 3 23:57 Wed 7 16:59

Перехватывайте и контролируйте поведение агента с помощью hooks

Перехватывайте и настраивайте поведение агента в ключевых точках выполнения с помощью hooks

Hooks — это функции обратного вызова, которые выполняют ваш код в ответ на события агента, такие как вызов инструмента, начало сеанса или остановка выполнения. С помощью hooks вы можете:

  • Блокировать опасные операции перед их выполнением, такие как деструктивные команды shell или несанкционированный доступ к файлам
  • Логировать и аудировать каждый вызов инструмента для соответствия требованиям, отладки или аналитики
  • Преобразовывать входные и выходные данные для санитизации данных, внедрения учетных данных или перенаправления путей файлов
  • Требовать одобрение человека для чувствительных действий, таких как запись в базу данных или вызовы API
  • Отслеживать жизненный цикл сеанса для управления состоянием, очистки ресурсов или отправки уведомлений

Как работают хуки

1

Срабатывает событие

Во время выполнения агента что-то происходит, и SDK генерирует событие: инструмент вот-вот будет вызван (PreToolUse), инструмент вернул результат (PostToolUse), субагент запустился или остановился, агент простаивает или выполнение завершилось. См. полный список событий.

2

SDK собирает зарегистрированные хуки

SDK проверяет наличие хуков, зарегистрированных для этого типа события. Сюда входят callback-хуки, которые вы передаете в options.hooks, и хуки shell-команд из файлов настроек, если включена соответствующая запись settingSources или setting_sources, что по умолчанию так и есть для параметров query().

3

Фильтрация запускаемых хуков с помощью matcher

Если у хука есть паттерн matcher (например, "Write|Edit"), SDK проверяет его на соответствие цели события (например, имени инструмента). Хуки без matcher запускаются для каждого события этого типа.

4

Выполняются функции обратного вызова

Функция обратного вызова каждого подходящего хука получает информацию о том, что происходит: имя инструмента, его аргументы, ID сессии и другие детали, специфичные для события.

5

Ваш callback возвращает решение

После выполнения любых операций (логирование, вызовы API, валидация) ваш callback возвращает объект вывода, который сообщает агенту, что делать: разрешить операцию, заблокировать ее, изменить входные данные или внедрить контекст в диалог.

Следующий пример объединяет эти шаги. Он регистрирует хук PreToolUse (шаг 1) с matcher "Write|Edit" (шаг 3), поэтому callback срабатывает только для инструментов записи файлов. При срабатывании callback получает входные данные инструмента (шаг 4), проверяет, указывает ли путь файла на файл .env, и возвращает permissionDecision: "deny" для блокировки операции (шаг 5):

import asyncio
from claude_agent_sdk import (
AssistantMessage,
ClaudeSDKClient,
ClaudeAgentOptions,
HookMatcher,
ResultMessage,
)


# Define a hook callback that receives tool call details
async def protect_env_files(input_data, tool_use_id, context):
# Extract the file path from the tool's input arguments
file_path = input_data["tool_input"].get("file_path", "")
file_name = file_path.split("/")[-1]

# Block the operation if targeting a .env file
if file_name == ".env":
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "deny",
"permissionDecisionReason": "Cannot modify .env files",
}
}

# Return empty object to allow the operation
return {}


async def main():
options = ClaudeAgentOptions(
hooks={
# Register the hook for PreToolUse events
# The matcher filters to only Write and Edit tool calls
"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]
}
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Create a .env file with the standard local development database configuration")
async for message in client.receive_response():
# Filter for assistant and result messages
if isinstance(message, (AssistantMessage, ResultMessage)):
print(message)


asyncio.run(main())

Когда вы запустите любой из скриптов, Claude попытается создать файл .env, и хук отклонит вызов инструмента.

Доступные hooks

SDK предоставляет hooks для различных этапов выполнения агента. Некоторые hooks доступны в обоих SDK, в то время как другие доступны только в TypeScript.

Hook Event Python SDK TypeScript SDK Что его срабатывает Пример использования
PreToolUse Да Да Запрос вызова инструмента (может блокировать или изменять) Блокировать опасные команды shell
PostToolUse Да Да Результат выполнения инструмента Логировать все изменения файлов в журнал аудита
PostToolUseFailure Да Да Ошибка выполнения инструмента Обработать или логировать ошибки инструмента
PostToolBatch Нет Да Полный пакет вызовов инструментов разрешается, один раз за пакет перед следующим вызовом модели Внедрить соглашения один раз для всего пакета
UserPromptSubmit Да Да Отправляется промпт, включая ход, который Claude Code начинает самостоятельно Внедрить дополнительный контекст в промпты
UserPromptExpansion Нет Да Команда, введённая пользователем, или MCP приглашение, расширяется в приглашение перед тем, как она достигнет Claude. Не срабатывает, когда Claude вызывает skill самостоятельно Заблокировать команду от прямого вызова или добавить контекст при вводе skill
MessageDisplay Нет Да Сообщение ассистента с текстом завершается, один раз за сообщение с полным текстом сообщения Скрыть или переформатировать отображаемый текст без изменения стенограммы
Stop Да Да Остановка выполнения агента Сохранить состояние сеанса перед выходом
StopFailure Нет Да Ход завершается с ошибкой API вместо нормальной остановки Логировать сбои или отправлять оповещения
SubagentStart Да Да Инициализация подагента Отслеживать порождение параллельных задач
SubagentStop Да Да Завершение подагента Агрегировать результаты из параллельных задач
PreCompact Да Да Запрос сжатия разговора Архивировать полную стенограмму перед суммированием
PostCompact Нет Да Сжатие разговора завершается Логировать созданное резюме
PreModelSwitch Нет Да Запрошенное переключение модели, перед тем как оно произойдёт (может блокировать) Заблокировать переключение на конкретную модель
PostModelSwitch Нет Да Модель сеанса изменяется, включая автоматический откат Дать Claude рекомендации, специфичные для модели, для новой модели
PermissionRequest Да Да Вызов инструмента требует решения о разрешении Пользовательская обработка разрешений
PermissionDenied Нет Да Автоматический режим отклоняет вызов инструмента, включая отклонения без вердикта классификатора Логировать отклонения или сообщить модели, что она может повторить попытку; Claude Code игнорирует retry: true для отклонений без вердикта. См. PermissionDenied
SessionStart Нет Да Инициализация сеанса Инициализировать логирование и телеметрию
SessionEnd Нет Да Завершение сеанса Очистить временные ресурсы
Notification Да Да Сообщения о статусе агента Отправить обновления статуса агента в Slack или PagerDuty
Setup Нет Да Настройка/обслуживание сеанса Запустить задачи инициализации
TeammateIdle Нет Да Товарищ по команде становится неактивным Переназначить работу или уведомить
TaskCreated Нет Да Задача создана через инструмент TaskCreate Применять соглашения об именовании задач
TaskCompleted Нет Да Задача отмечена как завершённая Требовать прохождения тестов перед закрытием задачи
Elicitation Нет Да MCP сервер запрашивает ввод пользователя во время задачи Программно отвечать на запросы ввода MCP
ElicitationResult Нет Да Пользователь отвечает на запрос MCP Изменить или заблокировать ответ перед его возвратом на сервер
ConfigChange Нет Да Файл конфигурации изменился Динамически перезагрузить настройки
InstructionsLoaded Нет Да Файл CLAUDE.md или файл правил загружается в контекст Проверять, какие файлы инструкций загружаются
WorktreeCreate Нет Да Git worktree создан Отслеживать изолированные рабочие пространства
WorktreeRemove Нет Да Удаляется worktree, созданный хуком WorktreeCreate Очистить ресурсы рабочего пространства
CwdChanged Нет Да Рабочий каталог изменяется во время сеанса Перезагрузить переменные окружения для каждого каталога
FileChanged Нет Да Отслеживаемый файл изменяется, создаётся или удаляется Перезагрузить конфигурацию при изменении файлов проекта
DirectoryAdded Нет Да Рабочий каталог добавляется во время сеанса Установить зависимости для репозитория, добавленного во время сеанса

Настройка хуков

Чтобы настроить хук, передайте его в поле hooks ваших параметров агента (ClaudeAgentOptions в Python, объект options в TypeScript). Этот фрагмент предполагает, что вы уже определили callback хука, например protect_env_files в Python или protectEnvFiles в TypeScript из примера выше:

options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[my_callback])]}
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Your prompt")
async for message in client.receive_response():
print(message)

Опция hooks — это словарь (Python) или объект (TypeScript), где:

Matchers

Используйте matchers для фильтрации, когда срабатывают ваши callbacks. Поле matcher сопоставляется с разными значениями в зависимости от типа события хука. Например, хуки на основе инструментов сопоставляются с именем инструмента, в то время как хуки Notification сопоставляются с типом уведомления.

SDK matchers следуют тем же правилам, что и matchers в файлах настроек. Этот раздел документирует пути оценки точной строки и регулярного выражения, требования к версиям и значения matcher для каждого типа события.

Опция Тип По умолчанию Описание
matcher string undefined Паттерн, сопоставляемый с полем фильтра события, следуя правилам для matchers в файлах настроек. Для хуков инструментов это имя инструмента. Встроенные инструменты включают Bash, Read, Write, Edit, Glob, Grep, WebFetch, Agent и другие (см. Tool Input Types для полного списка). MCP инструменты используют паттерн mcp__<server>__<action>, где <server> — это ключ, который вы используете в конфигурации mcpServers.
hooks HookCallback[] - Обязательно. Массив функций обратного вызова для выполнения, когда паттерн совпадает
timeout number undefined Таймаут в секундах. Если опущен, Claude Code применяет таймаут события по умолчанию. Ваши SDK callbacks следуют значениям по умолчанию хука command

Используйте паттерн matcher для нацеливания на конкретные инструменты, когда это возможно. Matcher с 'Bash' запускается только для команд Bash, в то время как опущение паттерна запускает ваши callbacks для каждого возникновения события. Опустите его намеренно для логирования каждого вызова инструмента, который делает ваша сессия.

Функции обратного вызова

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

Каждый callback хука получает три аргумента:

  • Входные данные: типизированный объект, содержащий детали события. Каждый тип хука имеет свою форму входных данных. Например, PreToolUseHookInput включает tool_name и tool_input, в то время как NotificationHookInput включает message. См. полные определения типов в справочниках TypeScript и Python SDK.
    • Все входные данные хуков содержат session_id, cwd и hook_event_name.
    • agent_id и agent_type заполняются, когда хук срабатывает внутри субагента. В TypeScript они находятся на базовом входе хука и доступны для всех типов хуков. В Python они являются необязательными полями на PreToolUse, PostToolUse, PostToolUseFailure и PermissionRequest, и обязательными полями на SubagentStart и SubagentStop.
  • ID использования инструмента (str | None / string | undefined): коррелирует события PreToolUse и PostToolUse для одного и того же вызова инструмента.
  • Контекст: в TypeScript содержит свойство signal (AbortSignal) для отмены. В Python этот аргумент зарезервирован для будущего использования.

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

Ваш callback возвращает объект с двумя категориями полей:

  • Поля верхнего уровня принимаются для каждого события: systemMessage показывает сообщение пользователю, и continue (continue_ в Python) определяет, продолжает ли агент работать после этого хука. Некоторые события отбрасывают их или доставляют их в другое место. Раздел каждого события на странице хуков говорит, где они попадают.
  • hookSpecificOutput контролирует текущую операцию. Поля, которые вы устанавливаете внутри, зависят от типа события хука:
    • Для хуков PreToolUse здесь вы устанавливаете permissionDecision ("allow", "deny", "ask" или "defer"), permissionDecisionReason и updatedInput. Если вы вернете "defer", ход завершается сообщением с результатом, у которого stop_reason равен "tool_deferred", чтобы вы могли возобновить вызов позже.
    • Для хуков PostToolUse вы можете установить additionalContext для добавления информации к результату инструмента. Чтобы заменить выходные данные инструмента перед тем, как Claude их увидит, установите updatedToolOutput, который работает для любого инструмента в обоих SDK. Более старое поле updatedMCPToolOutput заменяет только выходные данные MCP инструмента.
    • В TypeScript SDK callback PostToolUse может также возвращать classifierContext, краткую заметку о результате вызова инструмента для классификатора разрешений авторежима. Поскольку ваш callback работает в собственном процессе вашего приложения, классификатор может учитывать заявление пользователя, которое вы передаете в заметке, как намерение пользователя. Поле требует TypeScript Agent SDK версии 0.3.236 или позже. В разделе Аннотирование результата для классификатора авторежима описаны ограничение по длине, правило только синхронного выполнения и то, что не следует помещать в заметку.

Возвращайте {} для разрешения операции без изменений. SDK callback-хуки используют тот же формат вывода JSON, что и хуки shell-команд Claude Code, который документирует каждое поле и опцию, специфичную для события. Для определений типов SDK см. справочники TypeScript и Python SDK.

Асинхронный вывод

По умолчанию агент ждет, пока ваш хук вернется, прежде чем продолжить. Если ваш хук выполняет побочный эффект, такой как логирование или отправка webhook, и ему не нужно влиять на поведение агента, вы можете вернуть асинхронный вывод вместо этого. Это говорит агенту продолжить немедленно без ожидания завершения хука. В этом фрагменте send_to_logging_service в Python и sendToLoggingService в TypeScript служат заменой для любой функции логирования, которую вы определяете:

async def async_hook(input_data, tool_use_id, context):
# Start a background task, then return immediately
asyncio.create_task(send_to_logging_service(input_data))
return {"async_": True, "asyncTimeout": 30000}
Поле Тип Описание
async true Сигнализирует асинхронный режим. Агент продолжает без ожидания. В Python используйте async_ для избежания зарезервированного ключевого слова.
asyncTimeout number Необязательный таймаут в миллисекундах для фоновой операции

Примеры

Несколько примеров в этом разделе показывают только функцию callback. Чтобы запустить один из них, зарегистрируйте callback под соответствующим событием в поле hooks ваших параметров, как показано в Настройка hooks.

Изменение входных данных инструмента

Этот пример перехватывает вызовы инструмента Write и переписывает аргумент file_path для добавления префикса /sandbox, перенаправляя все записи файлов в изолированный каталог. Callback возвращает updatedInput с измененным путем и permissionDecision: 'allow' для автоматического одобрения переписанной операции:

async def redirect_to_sandbox(input_data, tool_use_id, context):
if input_data["hook_event_name"] != "PreToolUse":
return {}

if input_data["tool_name"] == "Write":
original_path = input_data["tool_input"].get("file_path", "")
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "allow",
"updatedInput": {
**input_data["tool_input"],
"file_path": f"/sandbox{original_path}",
},
}
}
return {}

Чтобы подтвердить перенаправление, установите префикс на путь, в который вы можете писать, например ./sandbox или /tmp/sandbox (macOS не позволяет создавать корневой каталог /sandbox), затем попросите агента написать файл: результат инструмента Write в потоке сообщений указывает путь с вашим префиксом sandbox вместо того, который запросил Claude.

Добавление контекста и блокировка инструмента

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

  • permissionDecision: 'deny' останавливает вызов инструмента.
  • permissionDecisionReason сообщает модели причину, чтобы она избежала повторной попытки.
  • systemMessage показывает пользователю, что произошло.
async def block_etc_writes(input_data, tool_use_id, context):
file_path = input_data["tool_input"].get("file_path", "")

if file_path.startswith("/etc"):
return {
# Top-level field: message shown to the user
"systemMessage": "Remember: system directories like /etc are protected.",
# hookSpecificOutput: block the operation
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "deny",
"permissionDecisionReason": "Writing to /etc is not allowed",
},
}
return {}

Чтобы подтвердить блокировку, зарегистрируйте callback под PreToolUse с matcher Write|Edit и попросите агента создать файл в /etc: результат инструмента Write в потоке сообщений содержит Writing to /etc is not allowed, и файл не создается.

Автоматическое одобрение конкретных инструментов

По умолчанию агент может запросить разрешение перед использованием определенных инструментов. Этот пример автоматически одобряет инструменты файловой системы только для чтения (Read, Glob, Grep), возвращая permissionDecision: 'allow', позволяя им запускаться без подтверждения пользователя, в то время как оставляя все остальные инструменты подлежащими обычным проверкам разрешений:

async def auto_approve_read_only(input_data, tool_use_id, context):
if input_data["hook_event_name"] != "PreToolUse":
return {}

read_only_tools = ["Read", "Glob", "Grep"]
if input_data["tool_name"] in read_only_tools:
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "allow",
"permissionDecisionReason": "Read-only tool auto-approved",
}
}
return {}

Регистрация нескольких hooks

Когда событие срабатывает, все соответствующие hooks выполняются параллельно. Для решений о разрешениях побеждает наиболее ограничивающий результат: одно deny блокирует вызов инструмента независимо от того, что возвращают другие hooks. Поскольку порядок завершения недетерминирован, напишите каждый hook так, чтобы он действовал независимо, а не полагаясь на то, что другой hook уже выполнился.

Пример ниже регистрирует три независимые проверки для каждого вызова инструмента. Имена hooks в нем, такие как audit_logger в Python или auditLogger в TypeScript, служат заменой для callbacks, которые вы определяете:

options = ClaudeAgentOptions(
hooks={
"PreToolUse": [
HookMatcher(hooks=[authorization_check]),
HookMatcher(hooks=[input_validator]),
HookMatcher(hooks=[audit_logger]),
]
}
)

Фильтрация с помощью multi-tool matchers

Используйте multi-tool matchers для совместного использования одного callback для связанных инструментов. Этот пример регистрирует три matcher с разными областями, и каждый hook, который он называет, служит заменой для callback, который вы определяете:

  • Список с разделением через трубу (Write|Edit|NotebookEdit) срабатывает file_security_hook только для инструментов модификации файлов.
  • Regex (^mcp__) срабатывает mcp_audit_hook для любого MCP инструмента, имя которого начинается с mcp__.
  • Пропущенный matcher срабатывает global_logger для каждого вызова инструмента независимо от имени.
options = ClaudeAgentOptions(
hooks={
"PreToolUse": [
# Match file modification tools
HookMatcher(matcher="Write|Edit|NotebookEdit", hooks=[file_security_hook]),
# Match all MCP tools
HookMatcher(matcher="^mcp__", hooks=[mcp_audit_hook]),
# Match everything (no matcher)
HookMatcher(hooks=[global_logger]),
]
}
)

Отслеживание активности подагента

Используйте hooks SubagentStop для мониторинга, когда подагенты завершают свою работу. См. полный тип входных данных в справочниках TypeScript и Python SDK. Этот пример логирует сводку каждый раз, когда подагент завершается:

async def subagent_tracker(input_data, tool_use_id, context):
# Log subagent details when it finishes
print(f"[SUBAGENT] Completed: {input_data['agent_id']}")
print(f"  Transcript: {input_data['agent_transcript_path']}")
print(f"  Tool use ID: {tool_use_id}")
print(f"  Stop hook active: {input_data.get('stop_hook_active')}")
return {}


options = ClaudeAgentOptions(
hooks={"SubagentStop": [HookMatcher(hooks=[subagent_tracker])]}
)

Чтобы подтвердить срабатывание hook, зарегистрируйте callback и попросите агента делегировать небольшую задачу подагенту, например список файлов в текущем каталоге: когда подагент завершится, callback выведет строки [SUBAGENT] Completed: с ID подагента и путем к транскрипту.

Выполнение HTTP запросов из hooks

Hooks могут выполнять асинхронные операции, такие как HTTP запросы. Ловите ошибки внутри вашего hook вместо того, чтобы позволить им распространяться.

Этот пример отправляет webhook после завершения каждого инструмента, логируя, какой инструмент запустился и когда. Hook ловит ошибки из неудачного webhook:

import asyncio
import json
import urllib.request
from datetime import datetime


def _send_webhook(tool_name):
"""Synchronous helper that POSTs tool usage data to an external webhook."""
data = json.dumps(
{
"tool": tool_name,
"timestamp": datetime.now().isoformat(),
}
).encode()
req = urllib.request.Request(
"https://api.example.com/webhook",
data=data,
headers={"Content-Type": "application/json"},
method="POST",
)
urllib.request.urlopen(req)


async def webhook_notifier(input_data, tool_use_id, context):
# Only fire after a tool completes (PostToolUse), not before
if input_data["hook_event_name"] != "PostToolUse":
return {}

try:
# Run the blocking HTTP call in a thread to avoid blocking the event loop
await asyncio.to_thread(_send_webhook, input_data["tool_name"])
except Exception as e:
# Log the error but don't raise
print(f"Webhook request failed: {e}")

return {}

Чтобы подтвердить срабатывание hook, укажите URL webhook на конечную точку, которую вы можете отслеживать, и отправьте запрос, который использует инструмент: hook отправляет POST с именем инструмента и временной меткой после завершения каждого инструмента.

Перенаправление уведомлений в Slack

Используйте hooks Notification для получения системных уведомлений от агента и перенаправления их во внешние сервисы. В сеансах SDK Claude Code запускает этот hook для следующих типов уведомлений:

  • permission_prompt один раз, когда запрос разрешения ждал около шести секунд на вашем callback canUseTool. Требуется TypeScript Agent SDK v0.3.233 или позже, или Python Agent SDK v0.2.139 или позже
  • elicitation_complete и elicitation_response для потоков запроса пользователя

Claude Code выдает другие типы, такие как idle_prompt, auth_success и elicitation_dialog, из интерактивного пользовательского интерфейса, который сеансы SDK не запускают.

Каждое уведомление включает поле message с описанием, понятным человеку, и опционально title.

Этот пример перенаправляет каждое уведомление в канал Slack. Требуется URL входящего webhook Slack, который вы создаете, добавляя приложение в ваше рабочее пространство Slack и включая входящие webhooks:

import asyncio
import json
import urllib.request

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher


def _send_slack_notification(message):
"""Synchronous helper that sends a message to Slack via incoming webhook."""
data = json.dumps({"text": f"Agent status: {message}"}).encode()
req = urllib.request.Request(
"https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
data=data,
headers={"Content-Type": "application/json"},
method="POST",
)
urllib.request.urlopen(req)


async def notification_handler(input_data, tool_use_id, context):
try:
# Run the blocking HTTP call in a thread to avoid blocking the event loop
await asyncio.to_thread(_send_slack_notification, input_data.get("message", ""))
except Exception as e:
print(f"Failed to send notification: {e}")

# Return empty object. Notification hooks don't modify agent behavior
return {}


async def main():
options = ClaudeAgentOptions(
hooks={
# Register the hook for Notification events (no matcher needed)
"Notification": [HookMatcher(hooks=[notification_handler])],
},
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Analyze this codebase")
async for message in client.receive_response():
print(message)


asyncio.run(main())

Когда срабатывает событие Notification, hook отправляет message уведомления с префиксом Agent status: в канал, на который указывает ваш webhook.

Исправление распространенных проблем

Хук не срабатывает

  • Проверьте, что имя события хука правильное и чувствительно к регистру (PreToolUse, а не preToolUse)
  • Проверьте, что ваш паттерн matcher точно совпадает с именем инструмента
  • Убедитесь, что хук находится под правильным типом события в options.hooks
  • Для хуков, не связанных с инструментами, которые поддерживают matcher, таких как Notification и SubagentStop, matcher сопоставляется с другими полями, а Stop полностью игнорирует matcher (см. паттерны matcher)
  • Хуки могут не срабатывать, когда агент достигает лимита max_turns, потому что сессия заканчивается до того, как хуки смогут выполниться

Matcher не фильтрует как ожидается

Matcher сопоставляется только с именами инструментов, а не с путями файлов или другими аргументами. Для фильтрации по пути файла проверьте tool_input.file_path внутри вашего хука:

const myHook: HookCallback = async (input, toolUseID, { signal }) => {
  const preInput = input as PreToolUseHookInput;
  const toolInput = preInput.tool_input as Record<string, unknown>;
  const filePath = toolInput?.file_path as string;
  if (!filePath?.endsWith(".md")) return {}; // Skip non-markdown files
  // Process markdown files...
  return {};
};

Таймаут хука

Claude Code запускает каждый callback с таймаутом, который вы устанавливаете в секундах с помощью поля timeout в его HookMatcher. Если вы его не устанавливаете, Claude Code использует значение по умолчанию для события: 600 секунд для большинства событий, 30 секунд для UserPromptSubmit, PreModelSwitch и PostModelSwitch и 10 секунд для MessageDisplay. Claude Code запускает callbacks SessionEnd во время завершения работы в рамках более короткого бюджета таймаута SessionEnd, по умолчанию 1,5 секунды.

Когда callback превышает свой таймаут, Claude Code отменяет его и отбрасывает его выходные данные, и сессия продолжается, а не зависает. Что происходит дальше, зависит от события:

  • PreToolUse: Claude Code не выполняет вызов инструмента, Claude получает результат инструмента, указывающий, что хук не ответил до истечения таймаута, и ход продолжается. Если другой хук PreToolUse вернул явный отказ, Claude получает этот отказ вместо ошибки таймаута. До версии 2.1.210 Claude Code сообщал Claude о таймауте как об отклонении пользователем, из-за чего автоматические сессии останавливались и ждали ввода.
  • PostToolUse и PostToolUseFailure: Claude Code сохраняет результат инструмента, и ход продолжается.
  • UserPromptSubmit и UserPromptExpansion: Claude Code блокирует промпт с сообщением, указывающим хук и таймаут, и сессия продолжается. Поскольку callback на этих событиях может действовать как шлюз политики, Claude Code никогда не пропускает промпт с истекшим таймаутом без проверки. До версии 2.1.208 Claude Code завершал запрос с error_during_execution, когда у callback на этих событиях истекал таймаут.
  • Stop и SubagentStop: callback с истекшим таймаутом считается не вернувшим решения. Агент или субагент останавливается так, как если бы этот callback это разрешил, а решение ваших других хуков на этом событии по-прежнему применяется. До Claude Code версии 2.1.273 callback Stop или SubagentStop с истекшим таймаутом считался неудачным запуском хука, и Claude Code отбрасывал решения ваших других хуков на этом событии.
  • SessionStart: callback с истекшим таймаутом считается не вернувшим выходных данных, и сессия продолжается с выходными данными ваших других хуков SessionStart.
  • PreModelSwitch: Claude Code блокирует переключение модели. Хук, который не отвечает, не одобрил переключение.
  • Другие события, такие как Notification, PreCompact и PostModelSwitch: Claude Code записывает сбой в лог и продолжает работу.

Когда у callback Stop или SessionStart впервые истекает таймаут в основной сессии, Claude Code также добавляет в поток сообщений SDKInformationalMessage о том, что приложение, управляющее сессией, не ответило. Последующие таймауты не повторяют это сообщение, пока ваше приложение остается неотвечающим.

Если вы прерываете запрос во время ожидания callback, Claude Code отменяет ожидающий вызов инструмента. До версии 2.1.208 вызов инструмента мог все же выполниться, если вы прерывали запрос во время ожидания callback PreToolUse.

Если вашему callback нужно больше времени, установите более высокий timeout в его HookMatcher. В TypeScript используйте AbortSignal из третьего аргумента callback для корректной обработки отмены при срабатывании таймаута.

Инструмент заблокирован неожиданно

  • Проверьте все хуки PreToolUse на возвращение permissionDecision: 'deny'
  • Добавьте логирование в ваши хуки, чтобы увидеть, какие permissionDecisionReason они возвращают
  • Проверьте, что паттерны matcher не слишком широкие: пустой matcher соответствует всем инструментам

Измененные входные данные не применяются

  • Убедитесь, что updatedInput находится внутри hookSpecificOutput, а не на верхнем уровне:

    return {
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "allow",
    updatedInput: { command: "new command" }
  }
};

  • Не объединяйте updatedInput с permissionDecision: 'defer', так как это отбрасывает измененные входные данные. Опускать permissionDecision допустимо: измененные входные данные все равно применяются через обычную оценку разрешений. Вы также можете вернуть 'allow' для автоматического одобрения измененных входных данных или 'ask', чтобы показать их пользователю для подтверждения

  • Включите hookEventName в hookSpecificOutput, чтобы указать, к какому типу хука относится вывод

Хуки сессии недоступны в Python

SessionStart и SessionEnd можно зарегистрировать как callback-хуки SDK в TypeScript, но они недоступны в Python SDK, потому что его тип HookEvent их не включает. В Python они доступны только как хуки shell-команд, определенные в файлах настроек, таких как .claude/settings.json. То, какие файлы настроек загружает ваше приложение SDK, зависит от setting_sources или settingSources. Если вы задаете этот параметр, включите источник, который содержит хуки:

options = ClaudeAgentOptions(
setting_sources=["project"],  # Loads .claude/settings.json including hooks
)

Чтобы вместо этого запускать логику инициализации как callback Python SDK, используйте первое сообщение из client.receive_response() в качестве триггера.

Запросы разрешений субагентов множатся

При порождении нескольких субагентов каждый из них может запрашивать разрешения отдельно для своих собственных вызовов инструментов. Чтобы избежать повторных запросов, используйте хуки PreToolUse для автоматического одобрения конкретных инструментов или настройте правила разрешений, которые субагенты наследуют от родительского диалога.

Рекурсивные циклы хуков с субагентами

Хук UserPromptSubmit, который порождает субагентов, может создать бесконечные циклы, если эти субагенты вызывают срабатывание того же хука. Чтобы предотвратить это:

  • Используйте общую переменную или состояние сессии для отслеживания того, находитесь ли вы уже внутри субагента
  • Ограничьте хуки, чтобы они запускались только для сессии агента верхнего уровня

systemMessage не появляется в выводе

Поле systemMessage показывает сообщение пользователю, а не модели. В Claude Code версии 2.1.227 или новее systemMessage хука может появиться в потоке сообщений как SDKInformationalMessage. Появится ли оно, зависит от события. В разделе каждого события на странице хуков описано, как выводится результат. Чтобы вместо этого передать контекст модели, верните additionalContext.

До версии 2.1.227 SDK выводил выходные данные хука в поток сообщений только для хуков SessionStart и Setup. Для любого другого события выходные данные появлялись только в событиях жизненного цикла, которые добавляет includeHookEvents (include_hook_events в Python). В описании этого параметра указано, какие события жизненного цикла порождает каждое событие хука.

Если вам нужно надежно передавать решения хуков в ваше приложение, логируйте их отдельно или используйте выделенный канал вывода.