Hook 输出与继续执行

命令 Hook 的 stdout 用于协议结果，调试日志应写 stderr。最终输出必须是一个 JSON 文档；连续打印多个普通 JSON 对象会拼成无效内容，导致决策被忽略。

进度与最终输出

CLI 允许在最终结果前输出单行 progress 对象：

echo '{"type":"progress","message":"Checking policy...","temporary":true}'
echo '{"permissionDecision":"allow"}'

progress 行只负责显示，不参与最终决策。temporary 为 true 时替换前一个临时状态，智能体回复后清除。

CLI 逐行识别并移除完整的 progress JSON，再把剩余 stdout 合并，用一次 JSON.parse 解析。最终对象可跨多行，但 progress 对象必须各占一行。教程建议 jq -c 或 PowerShell ConvertTo-Json -Compress 便于避免格式问题；参考明确允许最终对象多行，并非所有输出都强制单行。

注入上下文

sessionStart 与 subagentStart 支持 additionalContext。多个成功 Hook 的非空内容按执行顺序用双换行合并，整体受 10 MiB 输出限制；会超过限制的贡献被丢弃，已积累内容保留并警告。

notification 异步、不会阻塞会话。返回 additionalContext 会作为用户消息注入，会话空闲时可能再次触发处理。用于桌面提示时，返回空对象即可，避免无意启动后续工作。

修改工具结果

postToolUse 可返回 modifiedResult，或 additionalContext。后者追加到工具结果供模型读取；多份上下文双换行合并，上限 10 KB，这与会话开始的 10 MiB 限制不同。

{
  "additionalContext": "Check the command's exit status before interpreting its output."
}

替换结果通常包含 resultType: "success" 和 textResultForLlm；如果返回 failure，失败会向下游传播，接着触发 postToolUseFailure。postToolUseFailure 的 command 退出码 2 则把 stdout 作为恢复指导追加给智能体。

要求继续执行

agentStop 与 subagentStop 可返回：

{
  "decision": "block",
  "reason": "Summarize the verification results before finishing."
}

block 使用非空 reason 作为下一轮提示。连续 8 次 block 后，CLI 会覆盖 Hook 并结束，防止无限循环；agentStop 的 stop_hook_active 表示当前轮已因先前 block 而继续，处理器应主动限制重复。

只有 subagentStop 支持 modifiedResponse，用于替换返回父级的最终文本。有效 block 优先于改写；多份改写不串联，每个 Hook 都看到原始 response，最后返回 modifiedResponse 的 Hook 生效。不能假设“先脱敏再格式化”会自动组成流水线。

退出码

0 表示成功并处理 JSON；2 通常显示警告后继续，但权限事件按拒绝处理，postToolUseFailure 用作恢复上下文。其他非零通常记录失败后继续，preToolUse command 是拒绝例外。超时始终警告后继续通常流程，详见权限决策。