Gemini CLI no ACP: prompt negado por hook BeforeAgent volta como turno vazio
Voltar para o Blog
Artigogemini clitroubleshootingagente de programaçãodev toolsmcp

Gemini CLI no ACP: prompt negado por hook BeforeAgent volta como turno vazio

Mafra16 de novembro de 20266 min de leitura

Você ligou um cliente de editor no Gemini CLI por ACP, escreveu um hook BeforeAgent que barra prompt com palavra proibida, mandou o prompt barrado e o cliente recebeu stopReason: "end_turn" com zero token e nenhum session/update. Nada de erro, nada de motivo. Para o cliente, foi um turno que terminou sem fazer nada. Na 0.68.0, a latest no npm em 16/11/2026, isso acontece porque o evento que carrega a negativa nunca é traduzido para o protocolo ACP.

O que o cliente ACP recebe quando o hook nega um prompt?

Uma resposta de sucesso, vazia. Este é o retorno literal de session/prompt depois de um BeforeAgent com exit 2:

{ "stopReason": "end_turn", "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 } }

O relato da issue google-gemini/gemini-cli #30114, aberta em 03/11/2026, mostra a comparação: o mesmo prompt sem a palavra barrada volta com hello, end_turn e cerca de 10.000 tokens de entrada. Com a palavra barrada, o prompt simplesmente desaparece.

É o pior formato de falha para quem escreve cliente: o turno não falha, então o tratamento de erro não dispara, e a interface fica esperando um texto que nunca chega.

Por que o prompt negado vira turno vazio?

Porque o evento existe e é emitido, mas o switch do ACP não tem caso para ele. O GeminiClient detecta a negativa em packages/core/src/core/client.ts e devolve um evento próprio:

if (hookOutput?.isBlockingDecision()) {
  return {
    type: GeminiEventType.AgentExecutionBlocked,
    value: {
      reason: hookOutput.getEffectiveReason(),
      systemMessage: hookOutput.systemMessage,
    },
  };
}

Do outro lado, em packages/cli/src/acp/acpSession.ts, o método que traduz o stream para o protocolo ACP tem casos para Content, Thought, Retry, ToolCallRequest, Finished, ModelInfo, MaxSessionTurns, LoopDetected, ContextWindowWillOverflow e Error. Termina com default: break;. AgentExecutionBlocked cai nesse default.

Como stopReason começa valendo 'end_turn' e nada o altera, a função devolve sucesso. O motivo que o hook calculou existe em memória, mas não vira agent_message_chunk nem stop reason distinto.

Evento do streamO que o ACP faz com ele
Contentenvia agent_message_chunk
Thoughtenvia agent_thought_chunk
ToolCallRequestpede permissão e executa a ferramenta
Finisheddefine o stop reason do turno
MaxSessionTurns e LoopDetectedstopReason: max_turn_requests
ContextWindowWillOverflowstopReason: max_tokens
Errorlança RequestError com o status
AgentExecutionBlockednada, cai no default
AgentExecutionStoppednada, cai no default
Fluxograma: o cliente ACP manda o prompt, o hook BeforeAgent nega, o turno volta com end_turn e zero token sem nenhum session/update; o motivo só aparece fora do ACP, no modo não interativo
Onde o motivo se perde. Fonte: código do google-gemini/gemini-cli v0.68.0 e issue #30114.

Como confirmar em trinta segundos?

Procure o evento no arquivo do ACP. Se não aparecer, você está no bug:

grep -c AgentExecutionBlocked packages/cli/src/acp/acpSession.ts
# 0

Zero é o resultado esperado na 0.68.0 e também na main em 16/11/2026. Confira também a sua configuração de hook: o bloqueio só acontece com decision: "deny", com continue: false ou com exit 2. Um hook que só imprime aviso e sai com 0 não bloqueia nada e não cai neste caso.

{
  "hooks": {
    "BeforeAgent": [
      {
        "hooks": [
          {
            "type": "command",
            "name": "deny-prompt",
            "command": "grep -q deny-this-word && { echo 'denied by policy' >&2; exit 2; }; exit 0"
          }
        ]
      }
    ]
  }
}

Onde o motivo aparece, se o ACP não repassa?

No modo não interativo. Ali o mesmo evento tem tratamento explícito, em packages/cli/src/nonInteractiveCli.ts, e a mensagem vai para o stderr com o prefixo [WARNING]:

gemini -p "Reply with the single word hello. deny-this-word"
# [WARNING] Agent execution blocked: denied by policy

Esse é o teste mais rápido para separar dois problemas diferentes: se o -p mostra o bloqueio, seu hook está certo e o que falta é o repasse no ACP. Se o -p responder normalmente, o hook nem disparou.

Por que o log diz que o hook falhou?

Porque sair com código 2 é contado como falha do processo. Em packages/core/src/hooks/hookRunner.ts, o resultado do hook recebe success: exitCode === EXIT_CODE_SUCCESS. Sair com 2 para bloquear é o caminho documentado como freio de emergência, mas ele é registrado como execução malsucedida, e aí o CLI emite o aviso:

Hook(s) [deny-prompt] failed for event BeforeAgent. Press F12 to see the debug drawer for more details.

A negação deliberada e o hook quebrado ficam com a mesma cara. Se você quer que a negação conte como sucesso, use o formato estruturado: imprima {"decision": "deny", "reason": "..."} no stdout e saia com 0. O bloqueio acontece igual, o motivo é o mesmo, e o hook deixa de aparecer como falho.

echo '{"decision": "deny", "reason": "Security Policy: potential secret detected."}'
exit 0

Como corrigir o turno vazio no ACP?

Duas saídas, e elas se combinam. A primeira é no cliente, que é o que você controla hoje sem esperar upstream: trate stopReason: "end_turn" com totalTokens: 0 e sem nenhum session/update como prompt barrado, e mostre uma mensagem própria em vez de uma bolha vazia.

A segunda é no agente. Acrescente o caso ao switch de acpSession.ts, logo antes do default, para que o motivo chegue ao fio:

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;

O texto é o mesmo que o modo não interativo já imprime, então a mensagem fica consistente entre os dois caminhos. Depois de aplicar, recompile com npm run build e rode gemini --acp de novo: o cliente passa a receber um chunk de texto antes do end_turn, e a interface tem o que mostrar.

Se você depende do pacote publicado, não edite node_modules. Faça o patch no seu fork, ou use o caminho do cliente até a issue #30114 ser fechada.

Já existe correção publicada?

Não, até 16/11/2026. Conferimos o arquivo em três pontos: a tag v0.68.0, o pacote latest no npm e a main. Nenhum tem caso para AgentExecutionBlocked no acpSession.ts. A issue #30114 segue aberta, e há relatos vizinhos do mesmo buraco: #30199 mostra que continue: false encerra o turno sem mensagem, e #30129 mostra que os hooks SessionStart e Notification nem rodam no ACP.

Enquanto isso, o teste com gemini -p continua sendo a forma mais confiável de saber se o seu hook está funcionando, independente de o cliente estar recebendo o motivo.

Se você quer um agente de programação no terminal sem ficar contando token a cada tentativa, a Verboo Code oferece tokens ilimitados.

Gostou deste artigo?
Compartilhe conhecimento com sua rede.
// Leia também

Artigos relacionados