Hooks 输入输出与退出码

用结构化拒绝和停止控制事件，避免 stdout 污染造成放行。

This page has not been translated into English yet. The original Chinese version is shown below.

Hook 从 stdin 读取一个 JSON 输入对象，向 stdout 写最终 JSON 对象，诊断写 stderr。外部脚本、启动提示和调试输出也不能污染 stdout。

通用输入

每种事件另有专属字段，不能假设每次输入都有 tool_input 或 prompt_response。

字段	用途
`decision`	allow 或 deny；block 是拒绝别名
`reason`	拒绝反馈，具体接收者由事件决定
`continue`	false 请求停止 Agent 循环，部分观察事件会忽略
`stopReason`	停止时给用户的说明
`systemMessage`	向终端用户显示文字
`suppressOutput`	隐藏内部 Hook 元数据日志与遥测
`hookSpecificOutput`	事件专属改写、上下文等结果

这些是通用能力集合，不表示每个事件都接受全部字段。例如 BeforeToolSelection 不支持 decision、continue、systemMessage。

退出码	处理
0	解析 stdout JSON；包括有意的 deny
2	阻止该事件目标，以 stderr 为原因，具体效果随事件变化
其他	非致命警告，使用原参数继续

BeforeTool 的 exit 2 拒绝工具但允许 Agent 继续；AfterTool 隐藏结果；AfterAgent 触发重试；BeforeModel/AfterModel 则阻止该轮模型处理。不能把 exit 2 一律写成“退出整个 CLI”。

{
  "decision": "deny",
  "reason": "The proposed change failed validation."
}

输出合法 JSON 并 exit 0 是官方推荐的结构化拒绝方式。要停止整个循环，使用受该事件支持的 continue false，而不是误用 deny。

Hooks 概览说明，stdout 混入普通文本会导致 JSON 解析失败，默认 Allow 并把输出视为 systemMessage。因此通用脚本崩溃或非 JSON 输出不能被当成可靠的安全拦截。部署前分别验证允许、拒绝、解析失败和退出码路径。