代理停止前验证

使用 onAgentStop 检查完成条件，并限制由 Hook 触发的连续轮次。

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

onAgentStop 在顶层代理自然到达一轮末尾时执行。此时会话仍然活动，Hook 可以允许停止，也可以请求再运行一轮。它与会话关闭时的 onSessionEnd、子代理生命周期事件都不同。

读取停止上下文

TypeScript 字段	用途
`stopReason`	停止原因，例如 end_turn
`transcriptPath`	磁盘上会话 transcript 路径
`stopHookActive`	当前延续是否已经由之前的阻止停止决定触发

这些字段帮助宿主判断还需不需要最终验证，而不是仅看最后一句回答是否声称任务完成。参考给出的路径是会话记录位置，不能假定连接远程 runtime 时一定能从客户端本机直接读取。

允许停止或继续一轮

无返回值时让代理停止。返回下列结构会排入另一条用户消息，要求代理继续：

{
  "decision": "block",
  "reason": "Run the final validation and fix any failures."
}

reason 应明确指出缺少的验证或交付项。这里的 block 是阻止当前自然停止，不是撤销已经运行的工具，也不是拒绝整个用户请求。

避免重复要求继续

检查 stopHookActive，避免刚因 Hook 继续后又无条件要求继续。runtime 也限制连续 block 次数，但该 SDK 专题没有给出数值；不要把独立 CLI 的限制常量直接移植为 SDK 保证。

应用应以实际完成条件决定是否阻止，例如验证结果是否已经产生；无论代理说什么都返回 block 会消耗额外轮次，并可能一直重复同一要求。该机制不替代会话预算或业务超时。

语言名称

SDK	注册名称
TypeScript	`onAgentStop`
Python	`on_agent_stop`
Go / .NET	`OnAgentStop`
Rust	`on_agent_stop`
Java	`setOnAgentStop`

输入成员还遵循各语言的实际类型：官方表中 Node.js/Python 列 stopReason、transcriptPath、stopHookActive，Go/.NET 用大写首字母，Rust 用 snake_case，Java 通过 getter。不要仅按 handler 命名规则猜输入字段；以当前 SDK 类型为准。

会话资源释放见生命周期 Hooks，子代理开始、完成和失败的展示见自定义代理事件。