会话、提示词与停止 Hooks

查询生命周期事件的 matcher、额外字段、继续工作和中断行为。

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

会话生命周期、单回合结束与用户中断是不同事件。先选择真实触发点，再实现输出，避免把 Stop 当作退出清理或把 Interrupt 当作可取消的审批。

启动与结束

事件	matcher 与额外输入	关键行为
`SessionStart`	`source`：startup、resume、clear、compact	普通 stdout 或 additionalContext 可加入 developer context
`SessionEnd`	`reason`，当前为 other	主线程结束时同步清理，不能靠输出保持会话开启
`SubagentStart`	`agent_type`；另有 agent_id、turn_id	上下文加入子智能体，continue false 不阻止启动

根会话压缩后，source 为 compact 的 SessionStart 会在下一次模型请求前运行，包括回合中自动压缩的立即延续。该事件返回 continue false 会结束回合，不再发起后续模型请求。

SessionEnd 在打开的会话被归档或删除、正常关闭 Codex，或会话空闲且没有客户端打开达到 30 分钟时触发。切走会话或 thread/unsubscribe 不会立即触发。它不对子智能体运行，即使配置 async 也仍同步；错误或超时只报告 Hook 失败。

提交提示词与压缩

UserPromptSubmit 不使用 matcher，输入含 prompt 与 turn_id。普通 stdout 或 additionalContext 可补上下文；拒绝提示词使用 decision: "block" 与 reason，或 exit 2 + stderr。

PreCompact 与 PostCompact 按 trigger 的 manual/auto 匹配，输入含 turn_id。普通 stdout 被忽略。PreCompact 返回 continue false 在压缩前停止，PostCompact 返回 continue false 在压缩后停止。

Stop 与 SubagentStop

Stop 不使用 matcher，输入提供 stop_hook_active、last_assistant_message 和 turn_id。若还需工作，可返回：

{
  "decision": "block",
  "reason": "Run one more pass over the failing tests."
}

这里 block 表示阻止停止，Codex 把 reason 作为新的用户继续提示词；并不是拒绝刚才那轮结果。实现时检查 stop_hook_active，避免无条件重复要求继续。

SubagentStop 按 agent_type 匹配，另有 agent_id、可空的 agent_transcript_path、最后消息和 stop_hook_active，允许请求子智能体继续。对这两个事件，任意匹配 Hook 的 continue false 都高于其他 Hook 的继续决定。exit 0 时非空输出必须是 JSON。

Interrupt

只在主线程的活动回合被用户中断时触发，不用于空闲线程或 subagent，忽略 matcher。输入含 turn_id 和 permission_mode。它不能阻止中断或重启回合；exit 0 且无输出即可，或返回带 systemMessage 的 JSON。默认超时 1 秒，配置限制为 1 至 3 秒。