Falhas nos ganchos do agente Gemini: como bloquear uma chamada de ferramenta

TL;DR

Os hooks do agente Gemini permitem que você execute um script antes de cada chamada de ferramenta embutida que um agente gerenciado faz e cancele a chamada com {"decision": "deny"} — mas cada caminho de falha nesse manipulador, incluindo uma falha, uma resposta HTTP não-2xx, um tempo limite e uma saída malformada, resolve para allow. Eles também nunca são acionados para servidores MCP ou ferramentas de função personalizadas, que são tratadas fora do sandbox. Trate os hooks como uma camada de auditoria e empurrão, coloque seu verdadeiro limite nas regras de rede do ambiente e no servidor MCP, e use max_total_tokens para o único controle que realmente falha fechado.

O que é um hook de agente Gemini?

Um hook de agente Gemini é um comando ou manipulador HTTP que o tempo de execução do agente gerenciado invoca em torno de uma chamada de ferramenta embutida, que pode vetar essa chamada antes que ela seja executada. Você envia um .agents/hooks.json para o sandbox e o tempo de execução o descobre automaticamente em /.agents/hooks.json ou .agents/hooks.json — de um repositório git ao lado de AGENTS.md, de um bucket de armazenamento em nuvem, ou inline através de environment.sources.

O Google lançou-os em 28 de julho de 2026 na mesma atualização que fez da geração 3.6 Flash o padrão do agente gerenciado, adicionou max_total_tokens, e abriu a camada gratuita. Os hooks receberam a menor atenção dos quatro e são os que têm as bordas mais afiadas.

A forma é pequena o suficiente para caber na sua cabeça:

{
  "security-gate": {
    "enabled": true,
    "pre_tool_execution": [
      {
        "matcher": "code_execution|delete_file",
        "hooks": [
          { "type": "command", "command": "python3 /.agents/hooks-scripts/gate.py", "timeout": 5 }
        ]
      }
    ]
  }
}

As chaves de nível superior são nomes de grupos que você escolhe. Cada grupo recebe enabled, pre_tool_execution e post_tool_execution. Cada regra recebe um matcher RE2 contra o nome da ferramenta e um array hooks ordenado cujos manipuladores são executados sequencialmente. O manipulador recebe o evento no stdin:

{
  "tool_call": {
    "name": "code_execution",
    "args": { "code": "rm -rf /tmp/forbidden", "language": "bash" }
  },
  "environment_id": "env_xyz789"
}

…e responde no stdout com {"decision": "allow"} ou {"decision": "deny", "reason": "..."}. Em um deny, a chamada é cancelada e o agente recebe sua razão, para que ele possa se adaptar em vez de tentar novamente cegamente — a mesma propriedade que torna uma boa descrição de ferramenta digna de ser escrita com cuidado.

Por que os hooks do agente Gemini falham abertos

Aqui está a parte que muda a forma como você deve usá-los. Do referência de hooks do agente:

Se um script de comando falhar (status de saída diferente de zero), um hook HTTP retorna um código de status não-2xx (como um erro de servidor 4xx ou 5xx), ou uma operação expira ou retorna JSON não reconhecido, o tempo de execução o trata como uma aprovação (allow).

Todo caminho que um manipulador pode falhar resolve a favor do agente:

A justificativa é declarada claramente na documentação: um hook que poderia travar ou falhar severamente bloquearia o agente, e um agente que para de funcionar porque um script de lint tem um erro de sintaxe é um produto pior do que um que prossegue. Essa é uma decisão defensável de disponibilidade para um tempo de execução gerenciado cuja promessa inteira é que um único ponto final simplesmente funcione.

É também a exata inversão do que um controle de segurança deve fazer. Um firewall t