工具与审批 Hook 事件

工具事件提供运行时 tool_name、tool_input 和调用标识。tool_use_id 用于内部关联，tool_call_id 可选，对应原提供商调用 ID；不要假定两者始终格式相同。permission_mode 表示该事件实际应用的模式。

PreToolUse 执行前控制

返回 hookSpecificOutput.permissionDecision 与 permissionDecisionReason：

无头和后台 subagent 不能显示该确认时，ask 降为 deny；ACP 当前同样按 deny 处理。TUI 把原因按字面文本显示，不解释其中 Markdown。

可用 updatedInput 替换工具参数。additionalContext 加在模型收到的结果尾部，不修改用户提示、审批提示或工具执行期间显示的错误。即使调用拒绝、停止或失败，也可以随对应错误送回；TUI ask 被用户拒绝或取消时则丢弃上下文。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Confirm this operation before it runs.",
    "additionalContext": "Report only the verified result of this call."
  }
}

上下文的 <、> 会转义，并受 tools.truncateToolOutputThreshold 字符限制；ACP 中该上限覆盖 PreToolUse 与 PostToolUseFailure 合计上下文，整批输出仍有总限制。取消轮次而尚未把工具结果交回模型时，不再投递这些内容。

成功与失败

PostToolUse 包含 tool_response，可附 duration_ms，耗时不包括审批。它可记录结果或追加上下文；此时工具已执行，返回 block 不能被理解为撤销文件改动。

PostToolUseFailure 包含 error、可选 is_interrupt、开始执行后可用的 duration_ms。additionalContext 附加到错误后，工具返回错误或抛异常都适用。

在 Code Mode 的 exec 内调用工具时，脚本收到的返回值不变；嵌套调用的 PreToolUse / PostToolUseFailure 上下文改为附在外层 exec 结果中，位于 exec 自身上下文之后，供模型读取。

PostToolBatch

一批全部调用解决后、结果返回模型之前触发一次，无 matcher。输入 tool_calls 给出每项工具、参数、标识、success/error/cancelled 状态与可选结果对象。

追加上下文进入最后一项结果。decision 为 block/deny、continue: false 或退出 2 时，最后一项被替换为含 stopReason 或 reason 的错误，其他结果保留，上下文仍可附加。这是结果阶段处理，不会回滚整批副作用。

Hook 失败或十五秒内未完成，结果不变并继续。

PermissionRequest

权限对话框阶段使用另一种输出对象 hookSpecificOutput.decision，其中 behavior 为 allow 或 deny，可加 updatedInput、updatedPermissions、message、interrupt。不要把它和 PreToolUse 的 permissionDecision 字符串混用。

Auto 分类拒绝后的 PermissionDenied 只用于观察，不能批准原调用，见状态事件。