Gemini CLI 的 ACP:钩子拒绝的提示会变成一个空轮次
返回博客
文章gemini clitroubleshootingagente de programaçãodev toolsmcp

Gemini CLI 的 ACP:钩子拒绝的提示会变成一个空轮次

Mafra2026年11月16日阅读约 5 分钟

你把编辑器客户端通过 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 和 LoopDetectedstopReason: max_turn_requests
ContextWindowWillOverflowstopReason: max_tokens
Error抛出带状态码的 RequestError
AgentExecutionBlocked什么都不做,落进 default
AgentExecutionStopped什么都不做,落进 default
流程图:ACP 客户端发送提示,BeforeAgent 钩子拦截,轮次以 end_turn 和零 token 返回,没有任何 session/update;原因只在 ACP 之外的非交互模式里出现
原因在哪里丢失。来源:google-gemini/gemini-cli v0.68.0 源码与 issue #30114。

怎么在三十秒内确认?

在 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。

喜欢这篇文章吗?
把知识分享给你的朋友。
// 继续阅读

相关文章