你把编辑器客户端通过 ACP 接进了 Gemini CLI,写了一个 BeforeAgent 钩子拦截含违禁词的提示,发了一条被拦下的提示,客户端收到的是 stopReason: "end_turn",零 token,连一个 session/update 都没有。没有报错,没有原因。对客户端来说,这就是一个什么都没做就结束的轮次。在 0.68.0(2026-11-16 的 npm latest)里,这会发生是因为承载拒绝的事件从来没有被翻译成 ACP 协议。
钩子拒绝提示时,ACP 客户端收到什么?
一个成功的空响应。BeforeAgent 钩子以 2 退出后,session/prompt 的原样返回就是这样:
{ "stopReason": "end_turn", "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 } }
2026-11-03 提交的 issue google-gemini/gemini-cli #30114 给出了对照:同一条提示,去掉违禁词,会返回 hello、end_turn 和大约一万个输入 token。带上违禁词,提示直接消失。
对写客户端的人来说,这是最难处理的失败形态:轮次没有失败,你的错误处理不会触发,界面就一直等着永远不会到来的文本。
为什么被拒绝的提示会变成空轮次?
因为事件存在,也确实被发出了,但 ACP 的 switch 里没有它的分支。GeminiClient 在 packages/core/src/core/client.ts 里识别出拒绝,并返回自己的事件:
if (hookOutput?.isBlockingDecision()) {
return {
type: GeminiEventType.AgentExecutionBlocked,
value: {
reason: hookOutput.getEffectiveReason(),
systemMessage: hookOutput.systemMessage,
},
};
}
另一边,packages/cli/src/acp/acpSession.ts 里负责把数据流翻译成 ACP 协议的方法,有 Content、Thought、Retry、ToolCallRequest、Finished、ModelInfo、MaxSessionTurns、LoopDetected、ContextWindowWillOverflow 和 Error 的分支。结尾是 default: break;。AgentExecutionBlocked 就落进了这个 default。
因为 stopReason 初始值是 'end_turn',之后没人改它,函数就返回了成功。钩子算出来的原因存在内存里,却既没有变成 agent_message_chunk,也没有变成独立的 stop reason。
| 数据流事件 | ACP 对它做什么 |
|---|---|
Content | 发送 agent_message_chunk |
Thought | 发送 agent_thought_chunk |
ToolCallRequest | 请求授权并执行工具 |
Finished | 确定本轮的 stop reason |
MaxSessionTurns 和 LoopDetected | stopReason: max_turn_requests |
ContextWindowWillOverflow | stopReason: max_tokens |
Error | 抛出带状态码的 RequestError |
AgentExecutionBlocked | 什么都不做,落进 default |
AgentExecutionStopped | 什么都不做,落进 default |
怎么在三十秒内确认?
在 ACP 文件里找这个事件。找不到,你就在这个 bug 上:
grep -c AgentExecutionBlocked packages/cli/src/acp/acpSession.ts
# 0
在 0.68.0 里,零就是预期结果,2026-11-16 的 main 也一样。顺便检查你的钩子配置:只有 decision: "deny"、continue: false 或 exit 2 才会拦截。只打印一句警告然后以 0 退出的钩子什么也拦不住,也走不到这个分支。
{
"hooks": {
"BeforeAgent": [
{
"hooks": [
{
"type": "command",
"name": "deny-prompt",
"command": "grep -q deny-this-word && { echo 'denied by policy' >&2; exit 2; }; exit 0"
}
]
}
]
}
}
ACP 不转发,那原因在哪里能看到?
在非交互模式里。那里同一个事件有明确处理,在 packages/cli/src/nonInteractiveCli.ts,消息带 [WARNING] 前缀写到 stderr:
gemini -p "Reply with the single word hello. deny-this-word"
# [WARNING] Agent execution blocked: denied by policy
这是区分两个不同问题最快的测试:如果 -p 显示了拦截,说明钩子是对的,缺的只是 ACP 的转发;如果 -p 正常回答,说明钩子根本没触发。
为什么日志说钩子失败了?
因为以 2 退出被算作进程失败。在 packages/core/src/hooks/hookRunner.ts 里,钩子结果被赋值为 success: exitCode === EXIT_CODE_SUCCESS。用 2 退出拦截是文档里写的紧急刹车,但它被记录成一次不成功的执行,于是 CLI 打出这条警告:
Hook(s) [deny-prompt] failed for event BeforeAgent. Press F12 to see the debug drawer for more details.
故意的拒绝和坏掉的钩子长得一模一样。如果你想让拒绝算作成功,就用结构化格式:把 {"decision": "deny", "reason": "..."} 打到 stdout,然后以 0 退出。拦截照样发生,原因一样,钩子也不再显示为失败。
echo '{"decision": "deny", "reason": "Security Policy: potential secret detected."}'
exit 0
怎么修掉 ACP 里的空轮次?
两条出路,而且可以叠加。第一条在客户端,这是你今天不用等上游就能控制的:把 stopReason: "end_turn" 加 totalTokens: 0 再加没有任何 session/update 的情况当作提示被拦截,显示你自己的消息,而不是一个空气泡。
第二条在 agent 里。在 acpSession.ts 的 switch 里、default 之前补上这个分支,让原因走到协议线上:
case GeminiEventType.AgentExecutionBlocked:
await this.sendUpdate({
sessionUpdate: 'agent_message_chunk',
content: {
type: 'text',
text: `Agent execution blocked: ${
event.value.systemMessage?.trim() || event.value.reason
}`,
},
});
break;
这段文字和非交互模式已经打印的是同一句,所以两条路径的说法保持一致。改完用 npm run build 重新构建,再跑一次 gemini --acp:客户端现在会在 end_turn 之前收到一个文本块,界面就有东西可显示了。
如果你依赖的是已发布的包,别改 node_modules。在你的 fork 里打补丁,或者在 issue #30114 关闭之前先用客户端那条路。
已经有发布的修复了吗?
截至 2026-11-16,没有。我们在三处查了这个文件:v0.68.0 标签、npm 上的 latest 包,以及 main。三处都没有 acpSession.ts 里对 AgentExecutionBlocked 的分支。issue #30114 仍然开着,旁边还有同类的洞:#30199 说 continue: false 会无消息地结束轮次,#30129 说 SessionStart 和 Notification 钩子在 ACP 下根本不跑。
在那之前,用 gemini -p 测试仍然是判断钩子是否生效最可靠的办法,不管客户端有没有收到原因。
如果你想要一个在终端里干活、不用每次尝试都数 token 的编程 agent,Verboo Code 提供不限量 token。



