Hooks para agentes de código são a camada que transforma uma recomendação de segurança em um limite executável. O agente ainda raciocina, lê arquivos, chama ferramentas e tenta se corrigir. A diferença é que comandos sensíveis passam por gates previsíveis antes de tocar rede, segredos, shell, MCP ou arquivos críticos.

Na documentação atual, o Claude Code organiza hooks em 3 cadências: uma vez por sessão, uma vez por turno e em cada chamada de ferramenta dentro do loop agentic (Claude Code Docs, "Hooks reference", consultado em 2026-07-05). Esse detalhe muda a arquitetura: segurança deixa de ser prompt e vira ponto de interceptação.

Resumo prático

  • Use PreToolUse para negar risco antes da execução.
  • Use PostToolUse para coletar evidência e corrigir rota.
  • Use Stop para exigir prova antes do resumo final.
  • Trate MCP, setup e rede como fronteiras de permissão.

Fluxo abstrato mostra um agente de código passando por gates, sandbox e revisão sem texto visível.

Por que hooks viraram peça de segurança?

Na documentação atual, PreToolUse e PostToolUse rodam em cada chamada de ferramenta dentro do loop agentic (Claude Code Docs, "Hooks reference", consultado em 2026-07-05). Hooks viraram peça de segurança porque o risco real aparece no momento em que o agente tenta executar, não quando ele promete seguir uma instrução.

O problema prático é simples: agentes bons obedecem contexto, setup, erro de terminal e documentação local. Isso é ótimo para produtividade. Também cria uma superfície onde conteúdo não confiável pode empurrar uma ação perigosa com aparência de manutenção normal.

Em junho de 2026, o 0din publicou "Clone This Repo and I Own Your Machine", descrevendo um ataque em que um repositório aparentemente normal levou um agente a abrir uma shell reversa por meio de setup, erro rotineiro e carga buscada em DNS (0din, "Clone This Repo and I Own Your Machine", consultado em 2026-07-05). O ponto não é uma ferramenta específica. É a classe de risco.

Se você já montou um harness de agentes para PRs confiáveis, hooks são o próximo passo natural. O harness define critérios. O hook aplica esses critérios no instante certo.

Cápsula citável: Hooks para agentes de código reduzem risco porque interceptam a ação no ponto de execução. A documentação do Claude Code separa hooks por sessão, turno e chamada de ferramenta, permitindo negar comandos antes do shell, registrar evidência depois da ação e bloquear o fim do loop sem prova.

Onde o hook entra no loop agentic?

Na documentação atual, a tabela de eventos do Claude Code lista eventos como SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SubagentStart, Stop e SessionEnd (Claude Code Docs, "Hooks reference", consultado em 2026-07-05). O hook entra onde uma decisão muda custo, risco ou evidência.

Pense no loop como quatro momentos. Primeiro, o agente recebe intenção e contexto. Depois, escolhe uma ferramenta. Em seguida, observa o resultado. Por fim, decide se continua, corrige ou encerra. Você não precisa hookar tudo; precisa hookar a fronteira onde uma falha seria cara.

PreToolUse é o gate de permissão. Ele serve para negar git push, curl solto, npm install em repo desconhecido, leitura de .env e comandos de cloud que alteram estado. Essa decisão deve ser determinística, curta e auditável.

PostToolUse é o gate de evidência. Ele pode rodar lint no arquivo editado, salvar diff, exigir teste próximo ou marcar que uma ferramenta MCP retornou dado externo. Se a evidência falha, o agente recebe um motivo concreto para tentar outra rota.

Stop é o gate de pronto. Ele não deve virar burocracia; deve impedir um resumo final que diz "feito" sem teste, diff, risco residual e próximo passo. Isso conversa diretamente com evals de PR no CI.

Loop abstrato mostra ação, gate, evidência e retry de agentes de código sem texto visível.

Cápsula citável: O lugar certo do hook é a fronteira de decisão. PreToolUse bloqueia antes da ação, PostToolUse transforma resultado em evidência, e Stop impede encerramento sem prova. Essa divisão mantém o agente autônomo, mas tira dele a permissão implícita para atravessar risco sem controle.

O que deve ser deny, ask ou allow?

Na documentação atual, o sistema de permissões do Claude Code separa regras em allow, ask e deny, e avalia nessa ordem efetiva: negar, perguntar e permitir (Claude Code Docs, "Configure permissions", consultado em 2026-07-05). Essa ordem importa porque uma negação ampla não deve depender da boa vontade do modelo.

Use allow para comandos repetitivos, locais e reversíveis. Testes, typecheck, leitura e geração de artefato temporário costumam entrar aqui. Mesmo assim, prefira comandos exatos. npm test é melhor que permitir qualquer coisa começando com npm.

Use ask quando a ação pode ser legítima, mas precisa de intenção humana. Atualizar lockfile, instalar dependência, abrir rede, rodar migração local e alterar workflow de CI são bons candidatos. O objetivo não é travar o agente; é marcar transição de risco.

Use deny para fronteiras que não fazem sentido em sessão agentic comum. Ler segredo, escrever em .git, rodar deploy, publicar pacote, alterar credencial, apagar diretório amplo e acessar domínio inesperado devem falhar cedo.

Na minha prática, eu começo com uma matriz pequena. Uma linha para shell. Uma para arquivos sensíveis. Uma para rede. Uma para MCP. Se a regra não cabe nessa matriz, provavelmente ainda é opinião, não política operacional.

Superfície Padrão inicial Motivo
Testes locais allow com comando exato Dá autonomia sem risco alto.
Instalação e rede ask por padrão Setup pode esconder carga externa.
Segredos e credenciais deny explícito O agente não precisa ler para codar.
Deploy e push deny no dev local Mudança externa exige humano.

Cápsula citável: A matriz allow, ask e deny evita confundir autonomia com permissão irrestrita. A documentação do Claude Code afirma que deny, ask e allow têm precedência definida, então comandos irreversíveis devem estar em deny, enquanto testes locais podem receber allow estreito e auditável.

Como MCP muda a ameaça?

Na especificação de 2025-06-18, o MCP define 3 papéis centrais: hosts, clients e servers, além de recursos, prompts e ferramentas expostos por servidores (Model Context Protocol, "Specification", consultado em 2026-07-05). MCP muda a ameaça porque ferramenta externa vira parte do loop do agente.

MCP é excelente quando entrega contexto sob demanda, como busca na codebase, issue tracker, banco de leitura ou documentação interna. O risco aparece quando o servidor combina escrita, rede, credenciais e descrições de ferramenta que o agente trata como confiáveis.

A própria especificação alerta que ferramentas representam caminhos de execução de código e exigem cautela, consentimento e autorização. Isso precisa virar política local. Um servidor MCP de leitura não deve virar servidor de escrita só porque a ferramenta existe.

Comece com allowlist por servidor. Dê permissão de leitura para servidores de contexto. Exija confirmação para ferramentas que escrevem, criam issue, comentam PR ou disparam workflow. Bloqueie servidores desconhecidos em projetos sensíveis.

Esse padrão aprofunda a ideia de MCP de codebase RAG para agentes que não leem tudo. MCP é melhor quando reduz contexto e amplia precisão; fica perigoso quando amplia autoridade sem gate.

Cápsula citável: MCP não é só contexto; é superfície de ferramenta. A especificação de 2025-06-18 define hosts, clients e servers, e alerta que tools podem abrir caminhos de execução. Por isso, servidores MCP devem entrar no harness com allowlist, escopo de leitura e confirmação para escrita.

Como desenhar um hook sem criar teatro de segurança?

Na documentação atual, hooks podem retornar decisões como negar uma chamada de ferramenta no PreToolUse, enquanto saída silenciosa mantém o fluxo normal de permissão (Claude Code Docs, "Hooks reference", consultado em 2026-07-05). Um bom hook é pequeno, testável e chato de propósito.

Evite hooks que tentam "entender intenção" com linguagem vaga. Isso pertence ao agente. O hook deve checar fatos: comando, caminho, domínio, tipo de ferramenta, branch, arquivo alterado, presença de segredo, ou prova de teste.

Um PreToolUse de shell pode bloquear padrões como remoção ampla, rede via shell e deploy. Um PostToolUse pode registrar comando, saída resumida, arquivos tocados e status. Um Stop pode negar finalização se o agente alterou código sem teste ou explicação.

O insight útil é separar "o agente decide plano" de "o harness decide permissão". Quando esses papéis se misturam, você volta a depender de prompt. Quando ficam separados, o agente pode ser criativo dentro de uma caixa clara.

Em fluxos longos, contexto também vira custo e risco. Eu uso RemoteCode como extensão de contexto para Claude Code e Codex em fluxos agentic longos quando quero que o agente vá mais longe sem despejar todo o histórico no prompt principal; é uma ferramenta minha, então a referência aqui é editorial e contextual.

Cápsula citável: Hook bom não tenta substituir julgamento humano nem raciocínio do agente. Ele verifica fatos observáveis: comando, caminho, domínio, ferramenta e evidência. Essa separação deixa Claude Code, Codex e subagentes trabalharem com autonomia, enquanto o harness aplica limites determinísticos.

Qual é um desenho mínimo para começar?

Na documentação atual, as configurações do Claude Code têm escopos de usuário, projeto, local e gerenciado, e o escopo gerenciado tem maior precedência (Claude Code Docs, "Claude Code settings", consultado em 2026-07-05). O desenho mínimo deve começar no projeto e subir para política gerenciada quando virar padrão de time.

Comece com três arquivos ou blocos: permissões, hooks e critérios de pronto. Permissões dizem o que entra em allow, ask e deny. Hooks aplicam as bordas. Critérios de pronto dizem qual evidência o Stop precisa encontrar.

Para um repositório TypeScript, eu começaria assim: permitir npm test e npm run typecheck, perguntar antes de npm install, negar leitura de .env, negar git push, e bloquear shell com rede em repositório que acabou de ser clonado.

Depois adicione um PostToolUse para rodar teste próximo quando arquivos de src/ mudarem. Se o teste falhar, o agente recebe o erro e tenta corrigir. Se não há teste próximo, ele precisa declarar o motivo no resumo final.

Matriz abstrata mostra zonas de permissão, revisão e bloqueio para agentes de código sem texto visível.

Esse mínimo combina com AGENTS.md enxuto para agentes de código. AGENTS.md orienta comportamento. Hooks e permissões impõem fronteiras. CI confirma a prova.

Cápsula citável: Um desenho mínimo de hooks começa com permissões estreitas, bloqueio de segredos, confirmação para rede e gate final de evidência. Como Claude Code separa escopos de usuário, projeto, local e gerenciado, times podem testar no projeto antes de promover política para todos.

Perguntas frequentes sobre hooks para agentes de código

Hook substitui revisão humana?

Não. Na documentação atual, hooks interceptam eventos como PreToolUse, PostToolUse e Stop, mas eles não entendem impacto de produto sozinhos. Use hook para negar risco mecânico e exigir evidência. Use revisão humana para arquitetura, comportamento de negócio e decisão de merge.

Preciso de hook se já tenho CI?

Sim, quando o agente pode executar ações antes do CI. O CI pega o PR. O hook pega o comando local, a ferramenta MCP, o setup e o encerramento da sessão. Na prática, hook reduz dano antes do commit; CI valida o resultado depois.

O que deve ficar no AGENTS.md e o que deve virar hook?

AGENTS.md deve orientar escolha, comando e critério. Hook deve impor limite. Se a regra é "prefira rodar teste próximo", escreva no AGENTS.md. Se a regra é "não leia .env", coloque em permissão ou hook. Prompt não é fronteira de segurança.

Hooks funcionam com subagentes?

Sim, quando a ferramenta expõe eventos de subagentes. A documentação do Claude Code lista SubagentStart e SubagentStop, além de eventos de ferramenta. Use isso para registrar fan-out, limitar escopo e exigir que cada subagente devolva evidência, não só conclusão.

Como evitar hooks lentos demais?

Use matcher estreito. A documentação do Claude Code permite filtrar eventos por ferramenta, agente ou padrão. Não rode script pesado em toda chamada. Bloqueie antes do risco, colete evidência depois de escrita e deixe o teste caro para CI quando o feedback local não muda a decisão.

Fechamento

Agentes de código precisam de autonomia, mas autonomia sem borda vira permissão acidental. Hooks resolvem isso porque atuam no ponto em que o agente tenta atravessar uma fronteira: shell, rede, segredo, MCP, subagente, escrita e encerramento.

Comece pequeno. Bloqueie segredos, pergunte antes de rede, permita testes exatos e exija prova antes do resumo final. Depois conecte o mesmo padrão aos seus evals de PR, ao seu MCP de codebase e ao seu fan-out de subagentes. O agente continua rápido. Só não corre mais solto onde o estrago custa caro.

Fontes consultadas

  • Claude Code Docs, "Hooks reference", consultado em 2026-07-05, https://code.claude.com/docs/en/hooks
  • Claude Code Docs, "Configure permissions", consultado em 2026-07-05, https://code.claude.com/docs/en/permissions
  • Claude Code Docs, "Claude Code settings", consultado em 2026-07-05, https://code.claude.com/docs/en/settings
  • Model Context Protocol, "Specification 2025-06-18", consultado em 2026-07-05, https://modelcontextprotocol.io/specification/2025-06-18
  • 0din, "Clone This Repo and I Own Your Machine", consultado em 2026-07-05, https://0din.ai/blog/clone-this-repo-and-i-own-your-machine