在使用 -p 标志的非交互模式下，只有当运行具有接收提示的权限宿主（例如 Agent SDK 的 canUseTool 回调）时，Claude Code 才会提供 AskUserQuestion 和 ExitPlanMode。这些工具需要用户交互。同时返回 permissionDecision: "allow" 和 updatedInput 即可满足这一要求：hook 从 stdin 读取工具的输入，通过您自己的 UI 收集答案，并在 updatedInput 中返回，使工具无需提示即可运行。对于这些工具，仅返回 "allow" 是不够的。对于 AskUserQuestion，请回传原始的 questions 数组，并添加一个 answers 对象，将每个问题的文本映射到所选答案。

对于其服务器使用 _meta["anthropic/requiresUserInteraction"] 标记的 MCP 工具，要求更为严格：hook 无法通过 "allow" 跳过其批准提示，无论是否带有 updatedInput，因为 Claude Code 无法确认 hook 是否收集了该工具所需的交互。

延迟工具调用以便稍后处理

"defer" 适用于将 claude -p 作为子进程运行并读取其 JSON 输出的集成，例如 Agent SDK 应用或基于 Claude Code 构建的自定义 UI。它允许调用进程在工具调用处暂停 Claude，通过自己的界面收集输入，然后从中断处恢复。Claude Code 仅在使用 -p 标志的非交互模式下遵守此值。在交互式会话中，它会记录一条警告并忽略该 hook 结果。

AskUserQuestion 工具是典型场景：Claude 想向用户提问，但没有可以作答的终端。-p 运行只有在具有权限宿主（例如通过 --permission-prompt-tool 传入的 MCP 工具）时才会提供 AskUserQuestion，因此请使用权限宿主启动运行。完整的往返流程如下：

1. Claude 调用 AskUserQuestion。PreToolUse hook 触发。
2. hook 返回 permissionDecision: "defer"。工具不会执行。进程以 stop_reason: "tool_deferred" 退出，待处理的工具调用保留在会话记录中。
3. 调用进程从 SDK 结果中读取 deferred_tool_use，在自己的 UI 中呈现问题，并等待答案。
4. 调用进程使用相同的权限宿主运行 claude -p --resume <session-id>。同一个工具调用会再次触发 PreToolUse。
5. hook 返回 permissionDecision: "allow"，并在 updatedInput 中提供答案。工具执行，Claude 继续。

deferred_tool_use 字段携带工具的 id、name 和 input。input 是 Claude 为该工具调用生成的参数，在执行之前捕获：

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

没有超时或重试次数限制。会话会保留在磁盘上直到您恢复它，但受 cleanupPeriodDays 保留期清理的约束，该清理默认在 30 天后删除会话文件，遵循保留期清理规则。如果恢复时答案尚未就绪，hook 可以再次返回 "defer"，进程会以相同方式退出。调用进程通过最终从 hook 返回 "allow" 或 "deny" 来控制何时跳出该循环。

"defer" 仅在 Claude 在该轮次中只进行单个工具调用时有效。如果 Claude 同时进行多个工具调用，"defer" 会被忽略并发出警告，工具将按正常权限流程继续。存在此限制是因为恢复时只能重新运行一个工具：无法在不让其他调用悬而未决的情况下延迟一批调用中的某一个。

如果恢复时被延迟的工具已不可用，进程会在 hook 触发之前以 stop_reason: "tool_deferred_unavailable" 和 is_error: true 退出。当提供该工具的 MCP 服务器在恢复的会话中未连接时，就会发生这种情况。deferred_tool_use 数据仍会包含在内，以便您识别是哪个工具缺失了。

PermissionRequest

在 Claude Code 即将请求您授予使用某个工具的权限时运行。在无法显示提示的会话中，例如非交互模式下的后台子代理，Claude Code 仍会运行这些 hook，如果没有 hook 返回决策，它会拒绝该工具调用。对于到达 --permission-prompt-tool 或 Agent SDK 的 canUseTool 回调的调用，hook 会与您的宿主并行运行，以先做出决策者为准。 使用 PermissionRequest 决策控制代表用户允许或拒绝。

当您需要在 Claude 请求使用工具的权限时立即获得信号，请使用此事件。Claude Code 仅在提示等待约六秒后才会运行 permission_prompt 类型的 Notification hook。

对于沙箱中命令的网络请求，Claude Code 不会运行 PermissionRequest hook。要获得该提示的信号，请使用 permission_prompt 通知类型。

针对工具名称进行匹配，取值与 PreToolUse 相同。

PermissionRequest 输入

PermissionRequest hook 会像 PreToolUse hook 一样接收 tool_name 和 tool_input 字段，但没有 tool_use_id。对于 MCP 工具，它们还会接收 mcp_server 对象。可选的 permission_suggestions 数组包含 Claude Code 针对此请求建议的权限更新，例如添加允许规则或更改权限模式。

permission_suggestions 数组并不是您所看到选项的精确列表，因为每个权限对话框都会构建自己的选项。有些对话框（例如用于文件编辑的对话框）根本不读取该数组，而是从请求本身派生其选项。读取该数组的对话框仍可能隐藏某个建议仍保留在数组中的选项，例如当 allowManagedPermissionRulesOnly 隐藏保存规则的选项时。它也可能提供没有对应建议条目的选项，例如 Yes, and switch to auto mode，它直接更改权限模式，而不是通过权限更新。

PreToolUse hook 在每次工具调用之前运行，无论是否需要权限。PermissionRequest hook 仅在 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 hook 可以允许或拒绝权限请求。除了所有 hook 都可用的 JSON 输出字段之外，您的 hook 脚本还可以返回一个包含以下特定于事件字段的 decision 对象：

以退出码 2 退出但没有 decision 对象的 hook 不会改变权限流程，其 stderr 会被丢弃。只有 decision 对象才能授予或拒绝请求。

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

权限更新条目

updatedPermissions 输出字段和 permission_suggestions 输入字段都使用相同的条目对象数组。每个条目都有一个决定其其他字段的 type，以及一个控制更改写入位置的 destination。

每个条目上的 destination 字段决定该更改是仅保留在内存中，还是持久化到设置文件。

hook 可以将其收到的某个 permission_suggestions 原样作为自己的 updatedPermissions 输出返回。

PostToolUse

在工具成功完成后立即运行。

按工具名称匹配，取值与 PreToolUse 相同。

当工具名称不是合适的过滤条件时，可以进行更宽泛的匹配：

• 要在任意工具成功完成后运行 hook，请省略 matcher 或将其设为 "*"。然后您的 hook 可以自行发现发生了哪些更改，例如运行 git status --porcelain，它还会列出 git diff 遗漏的未跟踪文件。对于失败的工具调用，请在 PostToolUseFailure 下添加相同的 hook。
• 要在特定文件在磁盘上发生更改时运行 hook（无论是由什么写入的），请使用 FileChanged。当 Bash 命令或 Claude Code 之外的进程重写同一文件时，Claude Code 不会运行匹配 Edit|Write 的 PostToolUse hook。

PostToolUse 输入

PostToolUse hook 在工具已成功执行后触发。输入同时包含 tool_input（发送给工具的参数）和 tool_response（工具返回的结果）。两者的确切 schema 取决于具体工具。文件工具的 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 hook 可以在工具执行后向 Claude 提供反馈。除了所有 hook 都可用的 JSON 输出字段之外，您的 hook 脚本还可以返回以下特定于事件的字段：

以下示例替换了一次 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."
  }
}

分类器对该说明的重视程度取决于您在何处配置了该 hook：

• 在 Claude Code 中配置的 hook：对于来自设置文件、插件、skill 和 Agent frontmatter 的 hook，分类器将该说明视为未经验证的、由应用程序提供的上下文。该说明永远不能确立用户意图；如果它声称您批准或请求了某事，分类器会将该声明与您在对话中发送的消息进行核对
• 进程内 Agent SDK 回调：当嵌入 Claude Code 的应用程序将该 hook 注册为 TypeScript SDK 回调并在实时会话期间返回该说明时，分类器可能会将说明中转述的用户陈述视为用户意图。此类陈述可以满足分类器原本会从您发送的消息中接受的同意要求，但它永远不能解除您自己的消息也无法解除的阻止。会话恢复后，Claude Code 会将恢复的说明视为未经验证的上下文。当两类 hook 都对同一调用添加注释时，分类器会将合并后的说明视为未经验证的内容

Claude Code 在传递说明时会应用以下限制：

• 长度：Claude Code 将单次工具调用的说明上限设为 2,000 个字符，并截断其余部分。该上限由响应该调用的所有 hook 共享
• 仅限同步响应：对于在后台运行的 hook，Claude Code 会忽略其响应中的该字段，因为该响应在 Claude Code 记录工具结果之后才到达
• 分类器不记录的调用：分类器的会话记录会省略只读查找，例如文件读取和搜索。附加到这些调用上的说明会被 Claude Code 丢弃
• 与重写的交互：当说明描述的是您正在用 updatedToolOutput 替换的输出时，请在同一个 hook 响应中同时返回这两个字段。如果该重写被拒绝或被另一个 hook 的重写替换，Claude Code 会丢弃该说明。即使另一个 hook 重写了输出，Claude Code 仍会传递您在没有重写的情况下返回的说明

PostToolUseFailure

当已开始执行的工具失败时运行：工具抛出了错误，或 MCP 工具返回了错误结果。可用于记录失败、发送警报或向 Claude 提供纠正性反馈。

按工具名称匹配，取值与 PreToolUse 相同。

PostToolUseFailure 输入

PostToolUseFailure hook 接收与 PostToolUse 相同的 tool_name 和 tool_input 字段，以及作为顶层字段的错误信息。对于 MCP 工具，它们还会接收 mcp_server 对象。例如，一次失败的 npm test 命令可能会传递：

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

error 字符串通常与 Claude 作为失败工具结果收到的文本相同。其格式因工具和失败类型而异。请让您的 hook 基于 tool_name、is_interrupt 以及第一行的 Exit code N 进行判断；将字符串的其余部分视为显示文本，而非稳定的格式。

• 对于 Bash 和 PowerShell，已运行并退出的命令会生成第一行 Exit code N，随后是命令产生的所有输出，作为一个整体块，其中 stdout 和 stderr 交错排列
• 当 Claude Code 无法启动 shell 进程本身时，负载也可能只携带一条没有退出码行的失败消息
• Claude Code 会对长字符串进行中间截断，并插入 ... [N characters truncated] ... 标记，还可能插入自己的行，例如 Command timed out after 2m 0s

PostToolUseFailure 决策控制

PostToolUseFailure hook 可以在工具失败后向 Claude 提供上下文。除了所有 hook 都可用的 JSON 输出字段之外，您的 hook 脚本还可以返回以下特定于事件的字段：

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

PostToolBatch

在一批中的每个工具调用都已完成后、Claude Code 向模型发送下一个请求之前运行一次。PostToolUse 对每个工具触发一次，这意味着当 Claude 进行并行工具调用时它会并发触发。PostToolBatch 针对整个批次只触发一次，因此适合注入依赖于已运行工具集合而非单个工具的上下文。此事件没有匹配器。

PostToolBatch 输入

除了通用输入字段之外，PostToolBatch hook 还会接收 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 hook 可以为 Claude 注入上下文。除了所有 hook 都可用的 JSON 输出字段之外，您的 hook 脚本还可以返回以下特定于事件的字段：

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

返回 decision: "block" 或 continue: false 会在下一次模型调用之前停止智能体循环。阻止消息来自 JSON 中的 reason 或 stopReason，或退出码 2 时的 stderr。您会在会话记录中看到它显示为警告，并且它会保留在对话中，因此当对话继续时 Claude 会看到它。

PermissionDenied

当自动模式拒绝工具调用时运行，包括在没有分类器判定的情况下拒绝——原因是独立于自动模式的安全检查拒绝了分类器自身的请求，或其响应无法解析。此 hook 仅在自动模式下触发：当您手动拒绝权限对话框、PreToolUse hook 阻止调用或 deny 规则匹配时，它不会运行。可用于记录拒绝、调整配置，或告诉模型它可以重试该工具调用。

按工具名称匹配，取值与 PreToolUse 相同。

PermissionDenied 输入

除了通用输入字段之外，PermissionDenied hook 还会接收 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 hook 可以告诉模型它可以重试被拒绝的工具调用。返回一个 hookSpecificOutput.retry 设为 true 的 JSON 对象：

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

当 retry 为 true 时，Claude Code 会向对话中添加一条消息，告诉模型它可以重试该工具调用。Claude Code 本身不会撤销该拒绝。如果您的 hook 没有返回 JSON，或返回 retry: false，拒绝将保持有效，模型会收到原始的拒绝消息。

当分类器未对该操作作出判定时（其响应无法解析，或独立于自动模式的安全检查拒绝了分类器自身的请求），Claude Code 会忽略 retry: true。对于这些拒绝，Claude Code 已经在拒绝消息中告诉模型是稍后重试还是继续其他工作。

Notification

当 Claude Code 发送通知时运行。按通知类型匹配。省略匹配器即可为所有通知类型运行 hook。

即使关闭了桌面通知，您也会收到这些 hook 事件：preferredNotifChannel 设置（包括 notifications_disabled）只改变提醒您的方式，而不影响您的 hook 是否运行。

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 将权限请求发送给 Agent SDK 的 canUseTool 回调的会话中（Claude Desktop 和 VS Code 扩展就是以这种方式托管 Claude Code 的），Claude Code 对 permission_prompt 的计时方式有所不同：

• 预期 permission_prompt 会在 Claude 请求权限约六秒后出现。在您输入时，Claude Code 不会推迟它。
• 如果您或 PermissionRequest hook 提前作出回应，Claude Code 不会运行 permission_prompt。
• 将 CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS 设为 1，即可在这些会话中关闭 permission_prompt。

在 v2.1.233 之前，permission_prompt 不会在这些会话中触发。

使用不同的匹配器，可以根据通知类型运行不同的处理程序。以下配置会在 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 hook 还会接收包含通知文本的 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 hook 无法阻止或修改通知。Claude Code 会丢弃它们的 systemMessage 和 continue 字段，但仍会发出 terminalSequence，桌面通知示例正是依赖于此。Notification hook 旨在用于副作用，例如将通知转发到外部服务。

SubagentStart

当 Claude 使用 Agent 工具生成子代理、当 Claude 恢复子代理，以及每次进程内 agent team 队友处理新消息时运行。支持使用匹配器按 Agent 类型名称进行过滤。对于内置 Agent，这是 Agent 名称，例如 general-purpose、Explore 或 Plan。对于自定义子代理，这是 Agent frontmatter 中的 name 字段，而不是文件名。

对于由插件提供的子代理，Agent 类型是插件范围的标识符，例如 my-plugin:reviewer，而不是单纯的 frontmatter 名称。冒号会使插件范围的名称走正则表达式匹配路径，因此请用 ^ 和 $ 锚定匹配器以进行精确匹配：^my-plugin:reviewer$。

SubagentStart 输入

除了通用输入字段之外，SubagentStart hook 还会接收包含子代理唯一标识符的 agent_id，以及包含匹配器所过滤的 Agent 名称的 agent_type。

{
  "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 hook 无法阻止子代理的创建，但可以向子代理注入上下文。除了所有 hook 都可用的 JSON 输出字段之外，您还可以返回：

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

当 hook 针对同一子代理再次运行时，仅当子代理的上下文中尚未包含先前运行注入的副本时，Claude Code 才会注入返回的上下文。启动时注入的副本会保留在原位，从而使子代理的提示缓存保持完整。在自动压缩丢弃该副本后，Claude Code 会再次注入下一次运行的上下文。

SubagentStop

当 Claude Code 子代理完成回复时运行。按 Agent 类型匹配，取值与 SubagentStart 相同。

SubagentStop 输入

除了通用输入字段之外，SubagentStop hook 还会接收 stop_hook_active、agent_id、agent_type、agent_transcript_path 和 last_assistant_message。agent_type 字段是用于匹配器过滤的值。transcript_path 是主会话的会话记录，而 agent_transcript_path 是存储在嵌套 subagents/ 文件夹中的子代理自身的会话记录。last_assistant_message 字段包含子代理最终回复的文本内容，因此 hook 无需解析会话记录文件即可访问它。

并非每个 SubagentStop 事件都来自 Claude 生成的子代理。Claude Code 还会为其自身的某些功能运行内部 Agent，例如提示词建议和 /btw 旁支问题，当这些 Agent 之一完成时，SubagentStop 也会触发。对于这些事件，agent_type 是会话本身运行所用的 Agent 名称，例如通过 --agent 或 agent 设置设定的名称；当会话未使用 Agent 运行时则为空字符串。

指定了 Agent 类型的 matcher 不会匹配空的 agent_type。匹配器被省略、为 "" 或 "*"，或者是能匹配空字符串的正则表达式的 hook，也会针对 agent_type 为空的事件运行。

在 Claude Code v2.1.271 或更高版本中，使用 SubagentHandback 工具运行的子代理会在停止之前通过该工具传递其报告。此时 last_assistant_message 字段保存的是子代理的结束文本（如果有），而不是所传递的报告。报告是该调用的 message 输入，匹配 SubagentHandback 的 PreToolUse 或 PostToolUse hook 会以 tool_input.message 的形式收到它。

SubagentStop hook 还会接收 Stop 输入中描述的 background_tasks 和 session_crons 数组。这两个数组的范围是父会话，而不是子代理。

{
  "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 hook 使用与 Stop hook 相同的决策控制格式，包括将 hookEventName 设为 "SubagentStop" 的 hookSpecificOutput.additionalContext，用于提供让子代理继续运行的非错误反馈。返回带有 reason 的 decision: "block" 会让子代理继续运行，并将 reason 作为下一条指令传递给子代理。通过退出码 2 进行阻止的 hook 会以同样方式传递其 stderr 消息。要在子代理返回后向父会话注入上下文，请改为在 Agent 工具上使用 PostToolUse hook。

TaskCreated

当通过 TaskCreate 工具创建任务时运行。可用于强制执行命名约定、要求提供任务描述或阻止创建某些任务。在没有 Task 工具的会话中，此事件不会触发。

TaskCreated hook 不支持匹配器，每次发生时都会触发。

TaskCreated 输入

除了通用输入字段之外，TaskCreated hook 还会接收 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 hook 可以通过两种方式阻止创建。无论哪种方式，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

当任务被标记为已完成时运行。它会在两种情况下触发：任何 Agent 通过 TaskUpdate 工具显式将任务标记为已完成时，或 agent team 队友在仍有进行中任务的情况下结束其轮次时。可用于在任务关闭之前强制执行完成标准，例如测试通过或 lint 检查通过。

TaskCompleted hook 不支持匹配器，每次发生时都会触发。

TaskCompleted 输入

除了通用输入字段之外，TaskCompleted hook 还会接收 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 hook 支持两种控制任务完成的方式：

• 退出码 2：任务不会被标记为已完成，stderr 消息会作为反馈传回给模型。
• JSON {"continue": false, "stopReason": "..."}：当事件由队友结束其轮次触发时，完全停止该队友，与 Stop hook 的行为一致。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 Agent 完成回复时运行。如果停止是由用户中断导致的，则不会运行。API 错误会改为触发 StopFailure。

Stop 输入

除了通用输入字段之外，Stop hook 还会接收 stop_hook_active、last_assistant_message、background_tasks 和 session_crons。当 Claude Code 已经因 stop hook 而继续执行时，stop_hook_active 字段为 true。请检查此值或处理会话记录，以避免因一个永远无法满足的条件而持续阻止。Claude Code 设有 8 次连续继续的上限：在 stop hook 连续八次让轮次继续之后，Claude Code 会覆盖下一次阻止并结束该轮次。要提高此上限，请设置 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP。

last_assistant_message 字段包含 Claude 最终回复的文本内容，因此 hook 无需解析会话记录文件即可访问它。对于需要处理刚完成的轮次的 hook（例如朗读或通知 hook），请使用此字段，而不是读取 transcript_path：在所有版本中，并不能保证会话记录文件在 Stop 时已包含最终消息。

background_tasks 和 session_crons 数组让 hook 能够区分"会话已完成"和"会话已暂停，正在等待后台工作将其重新唤醒"。当任务注册表可访问时，这两个数组都会存在；当没有正在进行或已计划的内容时，它们为空。

background_tasks 中的每个条目描述一个正在进行的任务，并使用以下字段：

session_crons 中的每个条目描述一个会话范围内的计划唤醒，来源于 CronCreate、ScheduleWakeup 和 /loop：

以下示例展示了一个包含一个正在进行的 shell 任务和一个周期性 cron 的 Stop 输入：

{
  "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 hook 可以控制 Claude 是否继续。除了所有 hook 都可用的 JSON 输出字段之外，您的 hook 脚本还可以返回以下特定于事件的字段：

通过退出码 2 进行阻止的 hook 与 reason 的传递方式相同：Claude 会收到 stderr 消息，作为它应该继续的原因说明。

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

当 hook 按设计正常工作并为 Claude 提供指导时（例如"完成前运行测试套件"），请使用 additionalContext。它通过与 decision: "block" 相同的循环保护机制（即 stop_hook_active 输入和 8 次连续继续上限）让对话继续，但会话记录会将其标记为 Stop hook feedback，并且不会显示 hook 错误通知：

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

StopFailure

当轮次因 API 错误而结束时，代替 Stop 运行。除 terminalSequence 外，Claude Code 会忽略该 hook 的输出和退出码。当 Claude 由于速率限制、身份验证问题或其他 API 错误而无法完成回复时，可用于记录失败、发送警报或采取恢复措施。

StopFailure 输入

除了通用输入字段之外，StopFailure hook 还会接收 error、可选的 error_details 和可选的 last_assistant_message。error 字段标识错误类型，并用于匹配器过滤。

{
  "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 hook 没有决策控制。它们仅用于通知和日志记录目的。

TeammateIdle

当 agent team 队友在结束其轮次后即将进入空闲状态时运行。可用于在队友停止工作之前强制执行质量关卡，例如要求 lint 检查通过或验证输出文件是否存在。

TeammateIdle hook 不支持匹配器，每次发生时都会触发。

TeammateIdle 输入

除了通用输入字段之外，TeammateIdle hook 还会接收 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 hook 支持两种控制队友行为的方式：

• 退出码 2：队友会收到 stderr 消息作为反馈，并继续工作而不是进入空闲状态。
• JSON {"continue": false, "stopReason": "..."}：完全停止该队友，与 Stop hook 的行为一致。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

当会话期间配置文件发生更改时运行。可用于审计设置更改、强制执行安全策略，或阻止对配置文件的未经授权的修改。

当设置文件、托管策略文件或 skill 文件发生更改时，Claude Code 会运行 ConfigChange hook。对于托管策略，仅当 managed-settings.json 或 managed-settings.d/ 中的文件发生更改时才会运行。对于服务器托管设置以及 macOS 托管偏好设置或 Windows 注册表策略的更改，Claude Code 会直接应用而不运行这些 hook。在启用了 wslInheritsWindowsSettings 的 WSL 上，它在策略轮询时也会直接应用已更改的 Windows 端托管设置文件，而不运行这些 hook。

匹配器按配置来源进行过滤：

以下示例记录所有配置更改以进行安全审计：

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

ConfigChange 输入

除了通用输入字段之外，ConfigChange hook 还会接收 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 hook 可以阻止配置更改生效。使用退出码 2 或 JSON decision 来阻止更改。被阻止时，新设置不会应用到正在运行的会话。

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

policy_settings 更改无法被阻止。当机器上的托管设置文件发生更改时，hook 仍会针对 policy_settings 来源触发，因此您可以使用它们记录这些编辑，但任何阻止决策都会被忽略。这确保了企业托管设置始终生效。当服务器托管设置到达或刷新时，Claude Code 不会运行 ConfigChange hook。

Claude Code 会根据 ConfigChange hook JSON 输出中的阻止决策采取行动，并丢弃 systemMessage 和 continue。无论您是通过 reason 还是通过退出码 2 时的 stderr 进行阻止，被阻止的更改都不会向您或 Claude 显示任何消息。Claude Code 只会在调试日志中写入一行。

CwdChanged

当主对话中的 shell 命令更改了工作目录时运行，例如 Claude 执行 cd 命令时。可用于响应目录更改：重新加载环境变量、激活特定于项目的工具链，或自动运行设置脚本。可与 FileChanged 配合使用，以支持 direnv 等管理每目录环境的工具。

CwdChanged hook 可以访问 CLAUDE_ENV_FILE。写入该文件的变量会在后续 Bash 命令中持续有效，直到下一个 CwdChanged 事件时由 Claude Code 清除。

CwdChanged 不支持匹配器，每次发生时都会触发。

CwdChanged 输入

除了通用输入字段之外，CwdChanged hook 还会接收 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 输出

除了所有 hook 都可用的 JSON 输出字段之外，CwdChanged hook 还可以返回 watchPaths，以动态设置 FileChanged 监视哪些文件路径：

CwdChanged hook 没有决策控制。它们无法阻止目录更改。

Claude Code 会从其 JSON 输出中读取 watchPaths 和 systemMessage，并丢弃 continue。在交互式会话中，它会将 systemMessage 显示为简短的终端通知。该消息不会进入 SDK 消息流。

DirectoryAdded

在您于会话中途使用 /add-dir 命令添加工作目录之后，或在 SDK 客户端通过 register_repo_root 控制请求添加工作目录之后运行。可用于准备新添加的仓库，例如安装其依赖。

在以下情况下，Claude Code 不会触发此事件：

• 您通过 --add-dir 启动标志传入目录；这些目录由 SessionStart 覆盖
• 您在 /permissions 的 Workspace 选项卡上添加目录
• 您添加的目录已经是工作目录或位于某个工作目录内

Claude Code 会在刷新沙箱和权限状态之后触发 DirectoryAdded，因此当您的 hook 运行时，沙箱化工具已经能看到新目录。hook 命令本身在沙箱之外运行。

Claude Code 不会等待该 hook：添加操作会立即完成，hook 在后台运行，使用 600 秒的默认超时时间。

匹配器按目录的添加方式进行过滤：

DirectoryAdded 输入

除了通用输入字段之外，DirectoryAdded hook 还会接收 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 hook 没有决策控制。它们无法阻止添加操作，因为 hook 运行时添加已经完成。Claude Code 会丢弃其 JSON 输出中的 continue 字段，并根据来源以不同方式呈现其余内容：

• slash_command：Claude Code 会在下一个对话轮次中将 hook 的 systemMessage 作为上下文传递给 Claude，而不是向您显示。失败 hook 的数量会显示在会话记录中。完整的失败输出会写入调试日志
• register_repo_root：Claude Code 仅将 systemMessage 输出和失败输出写入调试日志

FileChanged

当被监视的文件在磁盘上发生更改时运行。Claude Code 通过文件系统监视器而非检查工具调用来检测更改，因此无论是什么更改了文件，它都会运行该 hook：Edit 或 Write 工具调用、Claude 通过 Bash 运行的脚本，或完全在 Claude Code 之外的进程。一个常见用途是在项目配置文件更改时重新加载环境变量。

此事件的 matcher 有两个作用：

• 构建监视列表：该值按 | 拆分，每个片段都被注册为工作目录中的字面文件名，因此 ".envrc|.env" 恰好监视这两个文件。正则表达式模式在这里没有用处：像 ^\.env 这样的值会监视一个字面名为 ^\.env 的文件。
• 过滤运行哪些 hook：当被监视的文件发生更改时，同一个值会按照标准匹配器规则，针对已更改文件的基本名称过滤运行哪些 hook 组。

以下示例会在 data.csv 发生任何更改后（包括 Bash 命令或外部脚本重写该文件）规范化其行尾：

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

该 hook 从 stdin 上 JSON 输入的 file_path 字段读取已更改文件的绝对路径。它的 grep 守卫检查的正是 perl 要删除的内容，即行尾的 CR，因此规范化之后的那次运行会直接退出而不触碰文件。较宽松的守卫会导致无限循环，因为即使没有替换任何内容，perl -i 也会重写文件，而 Claude Code 在每次重写后都会再次运行该 hook。请将此脚本保存到 /path/to/normalize-line-endings.sh 并使其可执行：

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

要确认 hook 是否正常工作，请让 Claude 使用 Bash 命令向 data.csv 追加一行 CRLF。Claude Code 会运行该 hook，文件最终将使用 LF 行尾。

要监视无法预先命名的文件，请从 hook 返回 watchPaths 以动态更新监视列表。只有当有内容指定了要监视的文件时，Claude Code 才会启动监视器，因此请用一个匹配器至少指定了一个文件的 FileChanged 组，或一个返回 watchPaths 的 SessionStart 或 CwdChanged hook 来初始化该列表。当被监视的文件发生更改时，匹配器仍会过滤运行哪些 hook 组，因此请为处理动态路径的组省略匹配器，这样它会匹配每个被监视的文件，且不会向监视列表添加任何内容。"*" 匹配器同样匹配每个文件，但 Claude Code 会像处理其他值一样将其注册到监视列表中，作为一个字面名为 * 的文件。

FileChanged hook 可以访问 CLAUDE_ENV_FILE。写入该文件的变量会在后续 Bash 命令中持续有效，直到下一个 CwdChanged 事件时由 Claude Code 清除。

FileChanged 输入

除了通用输入字段之外，FileChanged hook 还会接收 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 输出

除了所有 hook 都可用的 JSON 输出字段之外，FileChanged hook 还可以返回 watchPaths，以动态更新监视哪些文件路径：

FileChanged hook 没有决策控制。它们无法阻止文件更改的发生。

Claude Code 会从其 JSON 输出中读取 watchPaths 和 systemMessage，并丢弃 continue。在交互式会话中，它会将 systemMessage 显示为简短的终端通知。该消息不会进入 SDK 消息流。

WorktreeCreate

在创建 worktree 时运行，无论是来自 claude --worktree、来自使用 isolation: "worktree" 的子代理，还是用于 Claude Code 隔离在其自身 worktree 中的后台会话。默认情况下，Claude Code 使用 git worktree 创建隔离的工作副本。配置 WorktreeCreate hook 会替换该默认 git 行为，让您可以使用 SVN、Perforce 或 Mercurial 等其他版本控制系统。

由于该 hook 完全替换了默认行为，因此不会处理 .worktreeinclude。如果您需要将 .env 等本地配置文件复制到新的 worktree 中，请在您的 hook 脚本中完成。

该 hook 必须返回所创建 worktree 目录的路径。Claude Code 将此路径用作隔离会话的工作目录。有关每种 hook 类型如何返回路径，请参阅 WorktreeCreate 输出。

Claude Code 会根据 hook 的成功状态和返回的路径采取行动，并丢弃 systemMessage 和 continue。

以下示例创建一个 SVN 工作副本，并打印路径供 Claude Code 使用。请将仓库 URL 替换为您自己的 URL：

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

该 hook 从 stdin 上的 JSON 输入中读取 worktree 的 name，将全新副本检出到新目录中，并打印目录路径。最后一行的 echo 就是 Claude Code 读取为 worktree 路径的内容。请将任何其他输出重定向到 stderr，以免干扰该路径。

WorktreeCreate 输入

除了通用输入字段之外，WorktreeCreate hook 还会接收 name 字段。这是新 worktree 的 slug 标识符，由用户指定或自动生成，例如 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 hook 不使用标准的允许/阻止决策模型，而是由 hook 的成功或失败决定结果。hook 必须返回所创建的 worktree 目录的路径：

• 命令 hook（type: "command"）：将路径作为 stdout 的最后一个非空行打印。Claude Code 在读取该行之前会去除 ANSI 转义码，因此在您的 echo 之前打印的 shell 启动横幅会被忽略。请将其他任何 hook 输出重定向到 stderr。
• HTTP hook（type: "http"）：在响应体中返回 { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }。

如果 hook 失败或未生成路径，worktree 创建将失败并报错。

Claude Code 会相对于 hook 运行所在的目录解析相对路径，并折叠其中的任何 . 或 .. 段。如果解析得到的路径不是 Claude Code 可以进入的目录，会话会打印一条指明该路径的错误，并以代码 1 退出。

Claude Code 会拒绝包含 . 或 .. 段的绝对路径，以及任何经过仓库根目录下符号链接的路径，因为提交到仓库中的符号链接可能会将 worktree 重定向到仓库之外。错误信息会指明被拒绝的路径组成部分。请返回一个规范化的、不经过仓库内符号链接的路径。在 v2.1.216 之前，worktree 创建会直接采用 hook 返回的路径，不进行此项检查。

WorktreeRemove

在移除 worktree 时运行。这是 WorktreeCreate 对应的清理事件。该事件在以下情况下触发：

• 您退出 --worktree 会话并选择将其移除
• 设置了 isolation: "worktree" 的子代理完成
• 您删除了一个后台会话，且其 worktree 由该 hook 创建

对于基于 git 的 worktree，Claude Code 会使用 git worktree remove 自动处理清理。如果您配置了 WorktreeCreate hook，请搭配一个 WorktreeRemove hook，以控制其所创建的 worktree 的清理：

• 没有 WorktreeRemove hook：当您退出 --worktree 会话并选择移除时，Claude Code 会回退为对 WorktreeCreate hook 返回的路径执行 git worktree remove --force，因此 git 能识别的 worktree 会被移除。git 无法识别的 worktree（例如您的 hook 使用非 git 版本控制系统创建的 worktree）会保留在磁盘上。关于删除后台会话时如何处理由 hook 创建的 worktree，请参阅 Agent 视图的删除规则。
• Hook 以 0 退出：该 worktree 视为已移除。Claude Code 不会从 hook 读取其他任何内容，因此请确保您的 hook 已删除该目录。
• Hook 以非零值退出：如果 worktree_path 处的目录在之后仍然存在，则移除失败，worktree 保留在磁盘上，且不会回退到 git。在以非零值退出之前已删除目录的 hook 视为已移除。关于失败的报告方式，请参阅 WorktreeRemove 输入。

Claude Code 从不删除属于 hook 创建的 worktree 的分支，因为它只知道您的 WorktreeCreate hook 返回的路径。如果您的 WorktreeCreate hook 创建了分支，请在 WorktreeRemove hook 中删除该分支。

Claude Code 会丢弃 WorktreeRemove hook 的 JSON 输出字段，例如 systemMessage 和 continue。

对于后台会话的删除，Claude Code 会在运行 hook 之前验证存储的 worktree 路径，并拒绝本身是符号链接或经过仓库根目录下符号链接的路径。对于仍包含文件的 worktree，只有当您在 Agent 视图中确认删除时，hook 才会运行；对于这类 worktree，claude rm 会保留会话和 worktree。在 v2.1.216 之前，hook 会直接在存储的路径上运行，不进行这些检查。

Claude Code 会将 WorktreeCreate 返回的路径作为 hook 输入中的 worktree_path 传入。以下示例读取该路径并删除该目录：

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

WorktreeRemove 输入

除通用输入字段外，WorktreeRemove hook 还会接收 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 hook 的退出码决定结果。当 hook 以非零值退出且 worktree_path 处的目录之后仍然存在时，移除失败：

• worktree 保留在磁盘上，hook 的命令和 stderr 会写入调试日志。
• 如果您正在删除后台会话，该会话也会保留。Agent 视图中的拒绝消息会报告 hook 的结束方式（例如 exited 1），引用其 stderr 的开头部分，并说明再次删除该会话是否仍会移除该目录。

PreCompact

在 Claude Code 即将执行压缩操作之前运行。

匹配器值表示压缩是手动触发还是自动触发：

以代码 2 退出可阻止压缩。对于手动 /compact，stderr 消息会显示给用户。您也可以通过返回带有 "decision": "block" 的 JSON 来阻止。

阻止自动压缩的效果取决于其触发时机。如果压缩是在达到上下文限制之前主动触发的，Claude Code 会跳过压缩，对话在未压缩的情况下继续。如果压缩是为了从 API 已返回的上下文限制错误中恢复而触发的，底层错误会显示出来，当前请求失败。

Claude Code 会丢弃 PreCompact hook 的 systemMessage 和 continue 字段。

PreCompact 输入

除通用输入字段外，PreCompact hook 还会接收 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 会丢弃 PostCompact hook 的 systemMessage 和 continue 字段。

适用与 PreCompact 相同的匹配器值：

PostCompact 输入

除通用输入字段外，PostCompact hook 还会接收 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 hook 没有决策控制。它们无法影响压缩结果，但可以执行后续任务。

PreModelSwitch

在 Claude Code 应用您或客户端请求的模型切换之前运行。可用于阻止切换、要求确认，或在切换发生前显示切换的成本。

PreModelSwitch 需要 Claude Code v2.1.251 或更高版本。Claude Code 会针对以下请求运行它：

• /model <name> 和 /model 选择器
• Option+P 或 Alt+P 模型选择器
• /config 中的 Model 设置
• 启用快速模式且这会改变会话的模型时
• 来自 Agent SDK 宿主或 Remote Control 的 set_model 请求，或 apply_flag_settings 请求中的模型更改

对于 Claude Code 自行进行的切换，例如自动模型回退或在您恢复会话时恢复模型，Claude Code 不会运行 PreModelSwitch hook。这些更改只会触发 PostModelSwitch。

Claude Code 会将匹配器与会话要切换到的模型的规范名称进行比较，忽略任何 [1m] 后缀。别名（如 opus）、带日期的模型 ID 以及特定于提供商的 ID（如 Amazon Bedrock 模型 ID）都会匹配它们所解析到的同一个规范名称，因此 claude-opus-5 涵盖 Opus 5 的所有写法。

当 Claude Code 无法确定目标的规范名称时，例如只有您的 LLM 网关才知道的自定义模型 ID，它会运行所有 PreModelSwitch hook，无论匹配器如何。因此，执行阻止的 hook 应检查其输入中的 to_model，而不是仅依赖匹配器。

匹配器可以写为确切名称、以 | 分隔的列表（如 claude-opus-4-6|claude-opus-5），或正则表达式（如 .*opus.*）。以下示例使用确切名称匹配器，同时检查 hook 输入中的 to_model，因此它会通过以代码 2 退出来拒绝切换到 Opus 4.6，并允许切换到任何其他目标：

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

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

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

要确认 hook 是否生效，请在运行其他模型的会话中运行 /model claude-opus-4-6。Claude Code 会保留当前模型，并报告 PreModelSwitch hook 阻止了切换，同时将您的消息作为原因。

PreModelSwitch 输入

除通用输入字段外，PreModelSwitch hook 还会接收下表中的字段。最后五个字段描述将对话重新发送给新模型的成本，以便 hook 在切换发生之前显示该数值。

以下示例展示在运行 Sonnet 5 的会话中执行 /model opus 时的输入：

{
  "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 hook 可以取消切换、请用户确认切换，或允许切换继续。退出码 2 或顶层的 decision: "block" 会取消切换。

如需更精细的控制，请在 hookSpecificOutput 对象中返回 permissionDecision 和 permissionDecisionReason，与 PreToolUse 相同。PreModelSwitch 接受 "allow"、"deny" 和 "ask"。它不接受 "defer"、updatedInput 或 additionalContext。下表描述这两个字段：

只有交互式会话中的 /model 才能显示 "ask" 提示。在其他所有使用入口上，包括使用 -p 标志的非交互模式、/config 和 set_model 请求，Claude Code 都会将 "ask" 视为拒绝。

以下示例请用户确认，并引用 context_tokens 中的 token 数：

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

当多个 PreModelSwitch hook 返回不同的决策时，优先级为 deny > ask > allow。

无论决策如何，Claude Code 都会向用户显示 hook 返回的任何 systemMessage，因此成本报告 hook 可以返回 {"systemMessage": "..."} 并以 0 退出。

在超时前未响应的 PreModelSwitch hook 会阻止切换。相比之下，在 PreToolUse 上，超时的命令 hook 会让工具调用继续。此事件的默认超时时间为 30 秒。PreModelSwitch 仅运行 command、http 和 mcp_tool hook，因此 prompt 和 agent 的默认值不适用。

以 0 或 2 以外的代码退出且未打印 JSON 决策的 hook 不会阻止切换：Claude Code 会显示其 stderr 并应用切换，如其他退出码中所述。

PostModelSwitch

在会话的模型更改后运行。可用于向 Claude 提供特定于模型的指导，而无需编辑每个 CLAUDE.md，例如适用于某些模型的组织级指令。

PostModelSwitch 需要 Claude Code v2.1.251 或更高版本。它无法阻止，因为模型已经更改。Claude Code 会在以下任何更改后运行 PostModelSwitch hook：

• 您或客户端请求的切换
• 自动模型回退，它会更改会话的模型
• opusplan 等设置在进入或退出计划模式时
• 您恢复会话时 Claude Code 恢复模型

当备用模型链中的模型为某一轮次提供服务时，Claude Code 不会运行 PostModelSwitch hook，因为这种替换只持续一轮，会话的模型保持不变。

匹配器遵循与 PreModelSwitch 相同的规则：Claude Code 将其与会话所切换到的模型的规范名称进行比较。

以下示例在会话的模型更改为任何 Opus 模型时添加指导：

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

要确认 hook 是否生效，请在运行其他模型的会话中切换到 Opus 模型，例如在 Sonnet 会话中运行 /model opus，然后询问 Claude 它对当前模型有哪些指导。

PostModelSwitch 输入

PostModelSwitch hook 接收与 PreModelSwitch 相同的字段，其中 hook_event_name 设置为 "PostModelSwitch"，并增加两个 source 值："auto" 表示自动回退或 Claude Code 自行进行的其他更改，"resume" 表示您恢复会话时恢复的模型。

当 source 为 "auto" 时，requested_model 为 null。当 source 为 "resume" 时，它是 Claude Code 恢复的已保存模型设置。

PostModelSwitch 决策控制

Claude Code 会在退出码为 0 时获取 hook 的纯文本 stdout，或获取 JSON 输出中的 additionalContext，并在切换后随下一个请求将其传递给 Claude。除所有 hook 均可用的 JSON 输出字段外，您还可以返回：

如果在您发送下一个提示词后五秒内 hook 仍未完成，Claude Code 会在不含该输出的情况下发送该请求，并改为将输出附加到再下一个请求。如果模型在下一个请求之前更改了多次，Claude Code 只会传递最后一次切换的目标模型对应的输出。

SessionEnd

在 Claude Code 会话结束时运行。适用于清理任务、记录会话 统计信息或保存会话状态。支持使用匹配器按退出原因进行筛选。

hook 输入中的 reason 字段表示会话结束的原因：

SessionEnd 输入

除通用输入字段外，SessionEnd hook 还会接收表示会话结束原因的 reason 字段。有关所有取值，请参阅上方的原因表。

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

SessionEnd hook 没有决策控制。它们无法阻止会话终止，但可以执行清理任务。Claude Code 会丢弃它们的 JSON 输出字段，例如 systemMessage。

SessionEnd hook 的默认超时时间为 1.5 秒。它适用于您退出、运行 /clear 或通过交互式 /resume 切换会话时。您可以通过两种方式为 hook 提供更多时间：

• 单个 hook 的 timeout：在该 hook 的配置中设置 timeout。总体时间预算会自动提高，以匹配您的设置文件中最大的单个 hook timeout，最长 60 秒。如果以这种方式提高预算，未设置自身 timeout 的 hook 仍保持默认值。在插件提供的 hook 上设置的超时时间不会提高预算。
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS：以毫秒为单位设置此环境变量，以显式覆盖预算。您设置的值也会成为每个未设置自身 timeout 的 hook 的超时时间。

以下示例将预算设置为 5 秒：

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

在 v2.1.268 之前，CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 只会提高总体预算，未设置自身 timeout 的 hook 仍会在 1.5 秒后被取消。

Elicitation

在 MCP 服务器于任务执行过程中请求用户输入时运行。默认情况下，Claude Code 会显示一个交互式对话框供用户响应。hook 可以拦截此请求并以编程方式响应，完全跳过对话框。

matcher 字段与 MCP 服务器名称进行匹配。

Elicitation 输入

除通用输入字段外，Elicitation hook 还会接收 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" }
    }
  }
}

对于 URL 模式的 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 authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Elicitation 输出

要在不显示对话框的情况下以编程方式响应，请返回带有 hookSpecificOutput 的 JSON 对象：

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

退出码 2 会拒绝该 elicitation。Claude Code 不会在任何地方显示您的 stderr 消息。

Claude Code 会处理 Elicitation hook JSON 输出中的 hookSpecificOutput，并丢弃 systemMessage 和 continue。

ElicitationResult

在用户响应 MCP elicitation 后运行。hook 可以在响应发回 MCP 服务器之前观察、修改或阻止该响应。

matcher 字段与 MCP 服务器名称进行匹配。

ElicitationResult 输入

除通用输入字段外，ElicitationResult hook 还会接收 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 输出

要覆盖用户的响应，请返回带有 hookSpecificOutput 的 JSON 对象：

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

退出码 2 会阻止该响应，将实际生效的操作更改为 decline。Claude Code 不会在任何地方显示您的 stderr 消息。

Claude Code 会处理 ElicitationResult hook JSON 输出中的 hookSpecificOutput，并丢弃 systemMessage 和 continue。

基于提示的 hooks

除了命令、HTTP 和 MCP tool hooks 外，Claude Code 还支持基于提示的 hooks（type: "prompt"），使用 LLM 来评估是否允许或阻止操作，以及代理 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。如果您在此事件上配置代理 hook，Claude Code 会跳过它，权限流程保持不变。要从 hook 允许或拒绝，请从命令或 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 字段描述了它们的 mcp_tool hooks 何时运行。它们不支持 http、prompt 或 agent hooks。

基于提示的 hooks 如何工作

基于提示的 hooks 不执行 Bash 命令，而是：

1. 将 hook 输入和您的提示发送到 Claude 模型，默认为 Claude Code 用于后台功能的模型
2. LLM 使用包含决定的结构化 JSON 响应
3. Claude Code 自动处理决定

提示 hook 配置

将 type 设置为 "prompt" 并提供 prompt 字符串而不是 command。使用 $ARGUMENTS 占位符将 hook 的 JSON 输入数据注入到您的提示文本中。

此 Stop hook 要求 LLM 在允许 Claude 完成之前评估是否应该停止：

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

响应架构

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 作为工具错误，以便它可以调整并继续，等同于命令 hook 的 permissionDecision: "deny"。在 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 拒绝批准，请使用命令 hook，返回 hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied：ok: false 无效，因为拒绝已经发生。此事件读取的唯一输出是 hookSpecificOutput.retry，提示和代理 hooks 无法设置。它们在此事件上运行，但其输出被丢弃。使用命令 hook返回 retry

如果您需要对任何事件进行更精细的控制，请使用命令 hook，其中包含决定控制中描述的每个事件字段。

检查多个条件后再停止

此 Stop hook 使用详细提示检查三个条件，然后允许 Claude 停止。SubagentStop hooks 使用相同的格式来评估子代理是否应该停止。如果模型因条件尚未满足而返回 "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
          }
        ]
      }
    ]
  }
}

基于代理的 hooks

基于代理的 hooks（type: "agent"）类似于基于提示的 hooks，但具有多轮工具访问。代理 hook 生成一个可以读取文件、搜索代码和检查代码库以验证条件的 subagent，而不是单个 LLM 调用。代理 hooks 支持与基于提示的 hooks 相同的事件，除了 PermissionRequest。

基于代理的 hooks 如何工作

当代理 hook 触发时：

1. Claude Code 生成一个 subagent，带有您的提示和 hook 的 JSON 输入
2. Subagent 可以使用 Read、Grep 和 Glob 等工具进行调查
3. 在最多 50 轮后，subagent 返回结构化的 { "ok": true/false } 决定
4. Claude Code 允许该操作（如果 ok 是 true）。如果 ok 是 false，Claude Code 处理阻止的方式与提示 hook 在该事件上具有 continueOnBlock: true 的方式相同，如响应架构下所列

代理 hooks 在验证需要检查实际文件或测试输出时很有用，而不仅仅是单独评估 hook 输入数据。

代理 hook 配置

将 type 设置为 "agent" 并提供 prompt 字符串，使用 $ARGUMENTS 作为 hook 输入 JSON 的占位符。配置字段与提示 hooks相同，除了代理 hooks 具有更长的默认超时时间 60 秒，并且没有 continueOnBlock 字段。

响应架构是 { "ok": true } 允许或 { "ok": false, "reason": "..." } 阻止。在 ok: false 时，Claude Code 处理代理 hook 的方式与处理同一事件上具有 continueOnBlock: true 的提示 hook 的方式相同；代理 hooks 没有 continueOnBlock 字段，并且不支持提示 hook 的 impossible 字段。

此 Stop hook 验证所有单元测试通过，然后允许 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 添加到命令 hook 的配置以在后台运行它而不阻止 Claude。此字段仅在 type: "command" hooks 上可用。

此 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 仍然对使用 asyncRewake 运行的 hook 强制执行 timeout。

Claude Code 仅在会话运行时传递异步 hook 的结果：

• 在非交互模式中使用 -p 标志，Claude Code 在拆卸时杀死任何仍在运行的异步 hook，并以 cancelled 结果完成它
• 如果你的 hook 的工作必须超越 claude -p 会话，从它启动一个完全分离的进程

异步 Hooks 如何执行

当异步 hook 触发时，Claude Code 启动 hook 进程并立即继续，不等待其完成。Hook 通过 stdin 接收与同步 hook 相同的 JSON 输入。

后台进程退出后，Claude Code 从 hook 的 JSON 响应中传递 additionalContext 和 systemMessage 字段给 Claude 在下一个对话轮次。与同步 hook 的 systemMessage 不同，这两个字段都不会显示给你。

Claude Code 根据与同步 hooks 相同的输出架构验证 JSON 响应，并删除任何值类型错误的字段，例如不是字符串的 systemMessage，而不是传递它。使用 --debug 运行以查看命名每个删除字段的警告。在 v2.1.202 之前，来自异步 hook 的格式错误的 JSON 输出可能会导致会话崩溃，并且每次恢复会话时崩溃都会重复发生。

异步 hook 完成通知默认被抑制。要查看它们，请使用 Ctrl+O 启用详细模式或使用 --verbose 启动 Claude Code。

文件更改后运行测试

此 hook 在 Claude 写入文件时在后台启动测试套件，然后在测试完成时将结果报告回 Claude。将此脚本保存到项目中的 .claude/hooks/run-tests-async.sh 并使用 chmod +x 使其可执行：

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

# 从 stdin 读取 hook 输入
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 仅对源文件运行测试
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# 运行测试并通过 additionalContext 向 Claude 报告结果
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 输出在下一个对话轮次传递。如果会话空闲，响应等待直到下一个用户交互。例外：退出代码为 2 的 asyncRewake hook 即使在会话空闲时也会立即唤醒 Claude。
• 每次执行创建一个单独的后台进程。同一异步 hook 的多个触发之间没有去重。

安全考虑

免责声明

工作区信任

Claude Code 在运行来自设置文件的任何 hook 之前会检查工作区信任。什么被视为受信任取决于会话类型：

• 交互式会话：Claude Code 会保留来自每个设置文件的 hooks，包括您自己的 ~/.claude/settings.json，直到您为该文件夹接受工作区信任对话框，或为其信任扩展到的父目录接受
• -p 或 SDK 会话：Claude Code 从不显示对话框，并将该文件夹视为受信任的，因此在您从未信任过的文件夹中运行存储库的 .claude/settings.json 中提交的 hooks

在您对存储库进行脚本化 claude -p 之前，如果您没有编写该存储库，请审查其 .claude/ 设置文件，使用 --bare 开始，或为该运行关闭 hooks，使用 --settings '{"disableAllHooks": true}'。项目子代理中的 Frontmatter hooks 遵循比设置文件 hooks 更严格的规则。在您信任文件夹之前运行的内容按会话类型列出每种存储库内容。

安全最佳实践

编写 hooks 时请记住这些实践：

• 验证和清理输入：永远不要盲目信任输入数据
• 始终引用 shell 变量：使用 "$VAR" 而不是 $VAR
• 阻止路径遍历：检查文件路径中的 ..
• 使用绝对路径：为脚本指定完整路径。在 exec 形式中，使用 ${CLAUDE_PROJECT_DIR} 且路径无需引用。在 shell 形式中，将其包装在双引号中
• 跳过敏感文件：避免 .env、.git/、密钥等

Windows PowerShell 工具

在 Windows 上，您可以通过在命令 hook 上设置 "shell": "powershell" 在 PowerShell 中运行单个 hooks。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 会将 PowerShell shell 形式命令中的 ${CLAUDE_PROJECT_DIR}、${CLAUDE_PLUGIN_ROOT} 和 ${CLAUDE_PLUGIN_DATA} 占位符重写为 PowerShell 的 ${env:NAME} 形式，无论 hook 是在 settings.json、插件还是 skill 中定义。PowerShell 随后在解析后从导出的环境中解析该值，因此占位符在双引号字符串内有效，但在单引号字符串内无效，PowerShell 在单引号字符串中永远不会展开变量。

不要在 PowerShell hook 中写入裸 $CLAUDE_PROJECT_DIR 拼写。PowerShell 将其解析为未定义的本地变量，并将其解析为 $null，这会导致脚本路径没有其项目根前缀。Claude Code 不会重写该形式；它会在 debug log 中记录警告。

下面的示例显示了一个 settings.json hook，它使用 $env: 形式运行项目脚本：

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

调试 hooks

Hook 执行详细信息被写入调试日志文件。使用 claude --debug-file <path> 启动 Claude Code 以将日志写入已知位置，或运行 claude --debug 并在 ~/.claude/debug/<session-id>.txt 读取日志。--debug 标志不打印到终端。

例如，在 Write 上的 PostToolUse hook，其命令打印 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"

对于更细粒度的 hook 匹配详细信息，设置 CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose 以查看额外的日志行，例如 hook 匹配器计数和查询匹配。

有关故障排除常见问题，如 hooks 不触发、Stop hooks 持续阻止或配置错误，请参阅指南中的限制和故障排除。有关涵盖 /context、/doctor 和设置优先级的更广泛的诊断演练，请参阅调试你的配置。