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 stream | O que o ACP faz com ele |
|---|---|
Content | envia agent_message_chunk |
Thought | envia agent_thought_chunk |
ToolCallRequest | pede permissão e executa a ferramenta |
Finished | define o stop reason do turno |
MaxSessionTurns e LoopDetected | stopReason: max_turn_requests |
ContextWindowWillOverflow | stopReason: max_tokens |
Error | lança RequestError com o status |
AgentExecutionBlocked | nada, cai no default |
AgentExecutionStopped | nada, cai no default |
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.



