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

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

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

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

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

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

Поле 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 }] }
  }
}

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

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

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

PermissionRequest

Выполняется, когда Claude Code собирается запросить у вас разрешение на использование инструмента. В сессиях, которые не могут показать запрос, например у фоновых субагентов в неинтерактивном режиме, Claude Code всё равно запускает эти хуки, и если ни один хук не вернёт решение, он запрещает вызов инструмента. Для вызова, который доходит до --permission-prompt-tool или callback canUseTool в Agent SDK, хуки выполняются параллельно с вашим хостом, и применяется то решение, которое принято первым. Используйте управление решениями PermissionRequest, чтобы разрешать или запрещать от имени пользователя.

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

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

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

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

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

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

Хуки PreToolUse выполняются перед каждым вызовом инструмента, независимо от того, нужно ли для него разрешение. Хуки 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

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

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

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

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

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

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

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

PostToolUse

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

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

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

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

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

Хуки 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

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

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

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

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

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

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

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

Какой вес классификатор придаёт заметке, зависит от того, где вы настроили хук:

• Хуки, настроенные в Claude Code: для хуков из файлов настроек, плагинов, скиллов и frontmatter агентов классификатор рассматривает заметку как непроверенный контекст, предоставленный приложением. Заметка никогда не устанавливает намерение пользователя, и если в ней утверждается, что вы что-то одобрили или запросили, классификатор сверяет это утверждение с вашими собственными сообщениями в диалоге
• Внутрипроцессные колбэки Agent SDK: когда приложение, встраивающее Claude Code, регистрирует хук как колбэк TypeScript SDK и возвращает заметку во время активной сессии, классификатор может учитывать переданное в заметке утверждение пользователя как намерение пользователя. Такое утверждение может удовлетворить требование согласия, которое классификатор принял бы из отправленного вами сообщения, но оно никогда не снимает блокировку, которую не смогло бы снять и ваше собственное сообщение. После возобновления сессии Claude Code рассматривает восстановленные заметки как непроверенный контекст. Когда хуки из обеих групп аннотируют один и тот же вызов, классификатор рассматривает объединённую заметку как непроверенную

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

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

PostToolUseFailure

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

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

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

Хуки 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 получает в качестве результата неудавшегося инструмента. Её формат зависит от инструмента и сбоя. Ориентируйте хук на tool_name, is_interrupt и первую строку Exit code N; остальную часть строки рассматривайте как отображаемый текст, а не как стабильный формат.

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

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

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

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

PostToolBatch

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

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

Помимо общих входных полей, хуки 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\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

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

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

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

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

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

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

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

Помимо общих входных полей, хуки 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

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

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

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

Claude Code игнорирует retry: true, когда классификатор не вынес вердикта по действию: его ответ не удалось разобрать, или проверка безопасности, отдельная от авторежима, отклонила собственный запрос классификатора. Для таких отказов Claude Code уже сообщает модели в сообщении об отклонении, следует ли повторить попытку позже или двигаться дальше.

Notification

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

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

Для типов quota_auto_resume_fired, quota_auto_resume_stale и quota_auto_resume_disabled требуется Claude Code v2.1.234 или новее.

В терминальных сессиях для permission_prompt при сетевом запросе команды в песочнице требуется Claude Code v2.1.246 или новее.

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

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

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

До v2.1.233 permission_prompt в таких сессиях не срабатывал.

Используйте отдельные matcher, чтобы запускать разные обработчики в зависимости от типа уведомления. Эта конфигурация запускает скрипт оповещения о разрешениях, когда 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

Помимо общих входных полей, хуки 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"
}

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

SubagentStart

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

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

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

Помимо общих входных полей, хуки 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"
}

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

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

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

SubagentStop

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

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

Помимо общих входных полей, хуки 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 содержит текстовое содержимое последнего ответа субагента, поэтому хуки могут получить к нему доступ без разбора файла транскрипта.

Не каждое событие SubagentStop исходит от субагента, созданного Claude. Claude Code также запускает внутренних агентов для некоторых собственных функций, таких как предложения промптов и побочные вопросы /btw, и SubagentStop срабатывает, когда завершается и один из них. Для таких событий agent_type — это имя агента, от имени которого работает сама сессия, например заданное с помощью --agent или настройки agent, и пустая строка, когда сессия работает без него.

matcher, называющий типы агентов, не совпадает с пустым agent_type. Хук, у которого matcher опущен, равен "" или "*" либо является регулярным выражением, совпадающим с пустой строкой, запускается и для событий с пустым agent_type.

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

Хуки SubagentStop также получают массивы background_tasks и session_crons, описанные в разделе Входные данные Stop. Оба массива относятся к родительской сессии, а не к субагенту.

{
  "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": []
}

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

TaskCreated

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

Хуки TaskCreated не поддерживают matcher и срабатывают при каждом возникновении события.

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

Помимо общих входных полей, хуки 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

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

• Код выхода 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 или когда участник команды агентов завершает свой ход с задачами в процессе выполнения. Используйте его для соблюдения критериев завершения, таких как прохождение тестов или проверок линтера, прежде чем задачу можно будет закрыть.

Хуки TaskCompleted не поддерживают matcher и срабатывают при каждом возникновении события.

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

Помимо общих входных полей, хуки 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

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

• Код выхода 2: задача не помечается как выполненная, а сообщение stderr передаётся модели в качестве обратной связи.
• JSON {"continue": false, "stopReason": "..."}: когда событие вызвано завершением хода участника команды, полностью останавливает участника команды, аналогично поведению хука 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

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

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

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

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

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

Этот пример показывает входные данные Stop с одной выполняющейся задачей оболочки и одним повторяющимся 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

Хуки Stop и SubagentStop могут управлять тем, продолжает ли Claude работу. Помимо полей вывода JSON, доступных всем хукам, ваш скрипт хука может возвращать следующие поля, специфичные для события:

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

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

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

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

StopFailure

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

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

Помимо общих входных полей, хуки 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"
}

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

TeammateIdle

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

Хуки TeammateIdle не поддерживают matcher и срабатывают при каждом возникновении события.

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

Помимо общих входных полей, хуки 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

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

• Код выхода 2: участник команды получает сообщение stderr в качестве обратной связи и продолжает работу вместо перехода в режим простоя.
• JSON {"continue": false, "stopReason": "..."}: полностью останавливает участника команды, аналогично поведению хука 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 запускает хуки ConfigChange, когда изменяется файл настроек, файл управляемой политики или файл скилла. Для управляемой политики он запускает их, только когда изменяется managed-settings.json или файл в managed-settings.d/. Настройки, управляемые сервером, и изменения управляемых настроек macOS или политики реестра Windows он применяет без запуска хуков. В WSL с wslInheritsWindowsSettings он также применяет изменённый файл управляемых настроек на стороне Windows при опросе политики, не запуская хуки.

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

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

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

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

Помимо общих входных полей, хуки 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

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

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

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

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

CwdChanged

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

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

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

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

Помимо общих входных полей, хуки 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

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

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

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

DirectoryAdded

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

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

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

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

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

Matcher фильтрует по способу добавления каталога:

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

Помимо общих входных полей, хуки 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"
}

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

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

FileChanged

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

matcher для этого события выполняет две роли:

• Построение списка наблюдения: значение разбивается по |, и каждый сегмент регистрируется как буквальное имя файла в рабочем каталоге, поэтому ".envrc|.env" отслеживает ровно эти два файла. Шаблоны регулярных выражений здесь бесполезны: значение вроде ^\.env будет отслеживать файл с буквальным именем ^\.env.
• Фильтрация запускаемых хуков: когда отслеживаемый файл изменяется, то же значение фильтрует, какие группы хуков запускаются, по стандартным правилам matcher применительно к базовому имени изменённого файла.

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

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

Хук считывает абсолютный путь изменённого файла из поля file_path входных данных JSON в stdin. Его защитная проверка grep ищет то же, что удаляет perl, — CR в конце строки, поэтому запуск после нормализации завершается, не трогая файл. Менее строгая проверка приводит к бесконечному циклу, потому что perl -i перезаписывает файл, даже если ничего не заменяет, а Claude Code снова запускает хук после каждой перезаписи. Сохраните этот скрипт по пути /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

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

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

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

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

Помимо общих входных полей, хуки 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

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

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

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

WorktreeCreate

Запускается при создании worktree — будь то из claude --worktree, из субагента, использующего isolation: "worktree", или для фоновой сессии, которую Claude Code изолирует в собственном worktree. По умолчанию Claude Code создаёт изолированную рабочую копию с помощью git worktree. Настройка хука WorktreeCreate заменяет это стандартное поведение Git, позволяя использовать другую систему контроля версий, например SVN, Perforce или Mercurial.

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

Хук должен вернуть путь к созданному каталогу worktree. Claude Code использует этот путь как рабочий каталог для изолированной сессии. О том, как каждый тип хука возвращает путь, см. в разделе Вывод WorktreeCreate.

Claude Code учитывает успешность хука и возвращённый путь и отбрасывает 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\"'"
          }
        ]
      }
    ]
  }
}

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

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

Помимо общих входных полей, хуки WorktreeCreate получают поле name. Это идентификатор-слаг для нового 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

Хуки WorktreeCreate не используют стандартную модель решений allow/block. Вместо этого результат определяется успехом или неудачей хука. Хук должен вернуть путь к созданному каталогу worktree:

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

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

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

Claude Code отклоняет абсолютный путь, содержащий сегменты . или .., а также любой путь, проходящий через символическую ссылку ниже корня репозитория, поскольку символическая ссылка, закоммиченная в репозиторий, могла бы перенаправить worktree за его пределы. В ошибке указывается отклонённый компонент. Возвращайте нормализованный путь, который не проходит через символическую ссылку внутри репозитория. До v2.1.216 создание worktree следовало по пути хука без этой проверки.

WorktreeRemove

Выполняется при удалении worktree. Это парный хук очистки для WorktreeCreate. Событие срабатывает, когда:

• вы выходите из сессии --worktree и выбираете её удаление
• завершается субагент с isolation: "worktree"
• вы удаляете фоновую сессию, worktree которой создал хук

Для worktree на основе git Claude Code выполняет очистку автоматически с помощью git worktree remove. Если вы настроили хук WorktreeCreate, добавьте к нему хук WorktreeRemove, чтобы управлять очисткой создаваемых им worktree:

• Нет хука WorktreeRemove: когда вы выходите из сессии --worktree и выбираете удаление, Claude Code использует как резервный вариант git worktree remove --force для пути, который вернул ваш хук WorktreeCreate, поэтому worktree, который распознаёт git, удаляется. Worktree, который git не распознаёт, например созданный вашим хуком с помощью системы контроля версий, отличной от git, остаётся на диске. О том, что происходит с созданным хуком worktree при удалении фоновой сессии, см. правила удаления в agent view.
• Хук завершается с кодом 0: worktree считается удалённым. Claude Code больше ничего не читает из хука, поэтому убедитесь, что ваш хук удалил каталог.
• Хук завершается с ненулевым кодом: удаление завершается ошибкой, если каталог по пути worktree_path после этого всё ещё существует, и worktree остаётся на диске без резервного варианта через git. Хук, удаливший каталог перед завершением с ненулевым кодом, считается выполнившим удаление. О том, как сообщается об ошибке, см. Входные данные WorktreeRemove.

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

Claude Code отбрасывает поля JSON-вывода хука WorktreeRemove, такие как systemMessage и continue.

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

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

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

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

Помимо общих полей входных данных, хуки 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"
}

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

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

PreCompact

Выполняется перед тем, как Claude Code собирается выполнить операцию сжатия контекста.

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

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

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

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

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

Помимо общих полей входных данных, хуки 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

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

Применяются те же значения matcher, что и для PreCompact:

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

Помимо общих полей входных данных, хуки PostCompact получают trigger и compact_summary. Поле compact_summary содержит сводку диалога, сгенерированную операцией сжатия.

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

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

PreModelSwitch

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

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

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

Claude Code не запускает хуки PreModelSwitch для переключений, которые он выполняет самостоятельно, например при автоматическом переключении на резервную модель или восстановлении модели при возобновлении сессии. Такие изменения доходят только до PostModelSwitch.

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

Когда Claude Code не может определить каноническое имя целевой модели, например для пользовательского идентификатора модели, известного только вашему LLM-шлюзу, он запускает каждый хук PreModelSwitch независимо от matcher. Поэтому блокирующий хук должен проверять to_model из своих входных данных, а не полагаться только на matcher.

Записывайте matcher как точное имя, список через |, например claude-opus-4-6|claude-opus-5, или регулярное выражение, например .*opus.*. Этот пример использует matcher с точным именем и также проверяет to_model из входных данных хука, поэтому он отклоняет переключение на 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

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

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

Помимо общих полей входных данных, хуки PreModelSwitch получают поля из этой таблицы. Последние пять описывают стоимость повторной отправки диалога новой модели, чтобы хук мог показать эту сумму до переключения.

Этот пример показывает входные данные для /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

Хуки 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?"
  }
}

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

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

Хук PreModelSwitch, который не отвечает до истечения таймаута, блокирует переключение. В PreToolUse, напротив, командный хук с истёкшим таймаутом позволяет вызову инструмента продолжиться. Таймаут по умолчанию для этого события — 30 секунд. PreModelSwitch запускает только хуки command, http и mcp_tool, поэтому значения по умолчанию для prompt и agent не применяются.

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

PostModelSwitch

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

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

• Переключение, запрошенное вами или клиентом
• Автоматическое переключение на резервную модель, которое меняет модель сессии
• Настройка, например opusplan, при входе в режим планирования или выходе из него
• Восстановление модели Claude Code при возобновлении сессии

Claude Code не запускает хуки PostModelSwitch, когда ход обслуживает модель из цепочки резервных моделей, поскольку такая замена длится один ход и оставляет модель сессии неизменной.

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.'"
          }
        ]
      }
    ]
  }
}

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

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

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

requested_model равно null, когда source равно "auto". Когда source равно "resume", это сохранённая настройка модели, которую восстановил Claude Code.

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

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

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

SessionEnd

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

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

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

Помимо общих полей входных данных, хуки SessionEnd получают поле reason, указывающее, почему завершилась сессия. Все значения см. в таблице причин выше.

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

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

Хуки SessionEnd имеют таймаут по умолчанию 1,5 секунды. Он применяется, когда вы выходите, выполняете /clear или переключаете сессии с помощью интерактивной /resume. Дать хуку больше времени можно двумя способами:

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

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

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

До v2.1.268 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS повышала только общий лимит, а хук без собственного timeout всё равно отменялся через 1,5 секунды.

Elicitation

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

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

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

Помимо общих полей входных данных, хуки Elicitation получают поля mcp_server_name, message и необязательные поля mode, url, elicitation_id и requested_schema.

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

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

Для elicitation в режиме 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

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

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

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

Claude Code использует hookSpecificOutput из JSON-вывода хука Elicitation и отбрасывает systemMessage и continue.

ElicitationResult

Выполняется после того, как пользователь отвечает на elicitation MCP. Хуки могут наблюдать, изменять или блокировать ответ до его отправки обратно MCP-серверу.

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

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

Помимо общих полей входных данных, хуки 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

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

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

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

Claude Code использует hookSpecificOutput из JSON-вывода хука 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
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest поддерживает command, http, mcp_tool и prompt hooks, но не agent hooks. Если вы настроите agent hook на этом событии, Claude Code пропустит его и поток разрешений продолжится без изменений. Чтобы разрешить или отклонить из hook, верните объект решения из command или HTTP hook.

События, которые поддерживают 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, по умолчанию той, которую Claude Code использует для фоновой функциональности
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, за исключением PermissionRequest.

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. Claude Code переписывает заполнители ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} и ${CLAUDE_PLUGIN_DATA} в команде PowerShell в форме shell в форму ${env:NAME} PowerShell, независимо от того, определён ли хук в settings.json, плагине или скилле. PowerShell затем разрешает значение из экспортированного окружения после анализа, поэтому заполнитель работает внутри строк в двойных кавычках, но не внутри строк в одинарных кавычках, где PowerShell никогда не расширяет переменные.

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

Пример ниже показывает хук в 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.