Claude Code hooks: como impor regras antes e depois de agir

Claude Code hooks: como impor regras antes e depois de agir

Hooks no Claude Code são comandos que você configura para rodar automaticamente em momentos definidos do ciclo do agente, como antes de uma ferramenta ser usada ou depois de um arquivo ser editado. Em vez de pedir no prompt que o agente lembre de validar, bloquear ou registrar, você move a regra para um código que sempre executa. O resultado é uma camada determinística em volta de um agente que, por natureza, decide de forma probabilística.

Principais pontos

• Instrução no prompt é pedido; hook é regra. O agente pode esquecer o pedido, mas não consegue pular um comando que o próprio Claude Code dispara.
• O hook antes da ação (PreToolUse) serve para bloquear. O hook depois da ação (PostToolUse) serve para validar e registrar.
• Comece com poucas regras, em modo restritivo para o que é irreversível e em modo de observação para o resto.
• Hooks são código executado com as permissões do seu usuário. Eles precisam de revisão, versionamento e limites, como qualquer script de produção.
• Hook não substitui isolamento, permissões mínimas e aprovação humana. Ele é uma camada a mais, não a única.

Por que regra no prompt não basta?

Quando você escreve no arquivo de instruções do projeto que o agente nunca deve mexer em arquivos de credenciais, está contando com a atenção do modelo em cada passo de uma sessão longa. Na maior parte do tempo funciona. O problema é que a empresa não decide com base na maior parte do tempo: decide com base no pior caso, como um comando destrutivo, um arquivo sensível alterado ou uma etapa de teste pulada.

O texto de Building effective agents, da Anthropic, separa workflows (caminhos definidos em código) de agentes (que dirigem o próprio processo). Hooks são a forma de colocar um pedaço de workflow dentro de um agente: o modelo continua escolhendo o que fazer, mas certas checagens acontecem sempre, na mesma ordem, sem depender de interpretação.

Há também uma razão de auditoria. Se alguém pergunta o que o agente executou ontem, a resposta não deveria depender do que o próprio agente lembra ou resume. Um registro escrito por um hook é um fato; um resumo do modelo é uma narrativa.

Em quais momentos do ciclo dá para interceptar?

O Claude Code expõe eventos em que você pode anexar comandos. Os nomes e campos podem mudar entre versões, então confirme sempre na documentação oficial do Claude Code antes de copiar uma configuração. Os eventos mais úteis para governança costumam ser estes:

• PreToolUse: roda antes de uma ferramenta ser executada (leitura, edição, comando de terminal). É o ponto para bloquear.
• PostToolUse: roda depois que a ferramenta terminou. É o ponto para formatar, testar e registrar.
• UserPromptSubmit: roda quando a pessoa envia uma mensagem. Serve para validar o pedido ou acrescentar contexto.
• Stop: roda quando o agente considera que terminou. Serve para exigir que testes passem antes de aceitar o fim da tarefa.
• SessionStart e SessionEnd: marcam o início e o fim da sessão, úteis para carregar contexto e fechar o registro.
• Notification: dispara quando o agente precisa de atenção, por exemplo para pedir permissão. Serve para avisar alguém.

Os hooks são declarados em arquivos de configuração do Claude Code, no nível do usuário ou do projeto. Cada entrada associa um evento a um filtro (o matcher, que pode apontar para uma ferramenta específica) e a um comando. O comando recebe os dados do evento em formato JSON pela entrada padrão, incluindo o nome da ferramenta e os parâmetros que ela vai usar.

Como bloquear uma ação perigosa antes de ela acontecer?

O padrão é simples. Você registra um hook de PreToolUse para as ferramentas que importam, por exemplo a de comandos de terminal e as de edição de arquivos. O script lê o JSON recebido, examina o comando ou o caminho do arquivo e decide. Segundo a documentação do Claude Code, um código de saída que sinaliza bloqueio (o código dois) impede a ferramenta de rodar e devolve ao agente o texto que o script escreveu no canal de erro. Isso importa: a mensagem de bloqueio vira informação para o modelo ajustar o plano, não apenas uma falha seca.

Boas regras de bloqueio têm três características:

• Pensam em lista de permissão, não só de proibição. Bloquear apenas comandos perigosos conhecidos deixa passar o perigoso que você não previu. Permitir só um conjunto conhecido de comandos para certas pastas é mais seguro.
• Dão uma mensagem útil. Em vez de negado, escreva algo como: edição de arquivos de ambiente não é permitida nesta sessão; peça aprovação a uma pessoa.
• Protegem o que é irreversível primeiro: apagar dados, publicar em ramo principal, tocar em ambiente de produção, enviar mensagens a clientes, alterar credenciais.

Esse raciocínio é o princípio do menor privilégio descrito no guia de autorização da OWASP: conceder só o acesso necessário para a tarefa e negar o resto por padrão. O hook é a implementação prática dessa ideia dentro da sessão do agente.

Um cuidado de engenharia: o script de bloqueio precisa ser rápido, previsível e testado sozinho. Se ele quebra, o comportamento depende de como foi escrito e de como a versão do Claude Code trata falhas que não são bloqueios. Teste os dois caminhos, o de permitir e o de negar, com entradas de exemplo antes de ligar o hook.

Como validar e registrar depois que o agente agiu?

O hook de PostToolUse roda quando a ação já aconteceu, então ele não desfaz nada por si só. Seu valor está em fechar o ciclo de verificação. Usos comuns:

• Rodar o formatador e o analisador estático nos arquivos que acabaram de ser alterados e devolver os erros ao agente para correção imediata.
• Executar os testes mais relacionados à mudança e relatar a falha em texto claro.
• Gravar uma linha de registro por ação, com data e hora, identificador da sessão, ferramenta usada e um resumo do alvo (caminho do arquivo ou comando).
• Sinalizar mudanças fora do escopo esperado, como arquivos de configuração tocados em uma tarefa que deveria mexer só em uma tela.

O hook de Stop completa o desenho. Ele pode recusar o fim da tarefa enquanto uma condição objetiva não for atendida, por exemplo testes verdes ou arquivo de changelog atualizado. Assim a definição de pronto deixa de ser opinião do agente.

Sobre o registro, pense como em observabilidade: o objetivo é conseguir reconstruir o que aconteceu a partir de dados, não de memória. O primer de observabilidade do OpenTelemetry descreve bem a ideia de ter sinais suficientes para entender o comportamento de um sistema por fora. Um arquivo de linhas em formato JSON, com campos estáveis, já cumpre esse papel no começo; depois ele pode alimentar um painel.

Um alerta sobre privacidade: o que passa por uma sessão de código pode incluir dados pessoais, chaves e trechos de bases reais. Registre metadados e caminhos, não o conteúdo completo. Se o fluxo toca dados de clientes, alinhe o que é guardado, por quanto tempo e com que finalidade, conforme discutimos em LGPD no WhatsApp com IA: consentimento, base legal e registro. O raciocínio vale além do WhatsApp.

Qual é o passo a passo para implantar o primeiro hook?

Um roteiro enxuto, na ordem em que costuma dar menos retrabalho:

• Passo um: liste as ações que não podem acontecer sem uma pessoa decidir (apagar, publicar, alterar credenciais, enviar algo externo). Essa lista vira as regras de bloqueio.
• Passo dois: liste as verificações que hoje alguém faz manualmente depois do trabalho (formatar, testar, revisar escopo). Essa lista vira as regras de validação.
• Passo três: escreva primeiro o hook de registro, sem bloquear nada. Rode por alguns dias de uso normal e leia o que foi gravado.
• Passo quatro: com base no registro real, escreva o primeiro hook de bloqueio para a ação mais crítica. Teste com entradas permitidas e proibidas fora do Claude Code.
• Passo cinco: guarde os scripts e a configuração no repositório do projeto, com revisão de código, para que a regra seja versionada e discutida pelo time.
• Passo seis: defina quem recebe o aviso quando um bloqueio acontece e o que essa pessoa faz. Bloqueio sem dono vira só frustração.
• Passo sete: revise o registro periodicamente. Regras que nunca disparam podem ser removidas; regras que disparam toda hora indicam um problema no fluxo ou na instrução.

Como isso fica na prática? Cenário ilustrativo

Cenário ilustrativo: uma equipe pequena de uma loja virtual usa o Claude Code para manter o código que integra pedidos, estoque e envio de mensagens a clientes. A pessoa responsável quer ganhar velocidade, mas teme três coisas: alteração acidental de arquivos com chaves, mudança direta no ambiente de produção e entrega de código sem teste.

Ela configura quatro hooks. Um de PreToolUse nega edição de arquivos de ambiente e comandos que apontem para o banco de produção, devolvendo uma mensagem pedindo aprovação humana. Outro de PostToolUse roda o formatador e os testes do módulo alterado e devolve as falhas ao agente. Um terceiro, também de PostToolUse, grava em arquivo uma linha por ação com sessão, ferramenta e alvo. O de Stop recusa o encerramento se os testes do módulo estiverem falhando.

Na primeira semana, o registro mostra que o agente tentou ler um arquivo de credenciais para descobrir uma variável. Nada grave aconteceu, mas a equipe decide fornecer essa variável por um caminho controlado e ajustar as instruções do projeto. O hook não resolveu tudo; ele tornou visível o que antes passaria despercebido.

Quais são os limites e riscos dos hooks?

Hooks são poderosos justamente porque executam comandos reais. Isso traz responsabilidades:

• Rodam com as permissões do usuário que iniciou a sessão. Um hook mal escrito ou alterado por terceiros pode causar dano. Trate configuração de hooks em repositório compartilhado como código sensível, com revisão obrigatória.
• Um filtro de texto não entende intenção. Bloquear uma palavra em um comando é frágil, já que o mesmo efeito pode ser obtido de outras formas. Combine hooks com permissões do próprio Claude Code, ambiente isolado e credenciais com escopo mínimo.
• Conteúdo externo pode manipular o agente. Páginas, arquivos e mensagens lidos durante a tarefa podem conter instruções maliciosas. A lista OWASP Top 10 para aplicações com LLM trata esse risco, e hooks de bloqueio ajudam a limitar o estrago, mas não eliminam a necessidade de isolar o que o agente pode alcançar.
• Excesso de regras cansa. Se todo trabalho passa por bloqueios confusos, a equipe tenta contornar. Poucas regras, claras e com mensagem útil, funcionam melhor.
• Hooks não decidem o que é aceitável para o negócio. Quem decide é uma política. Para definir quais ações exigem aprovação humana e quem aprova, vale partir de uma política de aprovação para agentes de IA.

Como aplicar o método: mapear, limitar, pilotar e transferir

O mesmo caminho que usamos para qualquer agente de IA serve para hooks. Mapear: descrever o fluxo atual, quem faz o quê, onde há risco e o que hoje é conferido à mão. Limitar: transformar os riscos em regras de bloqueio, escopo de pastas e dados, e escolher o que exige aprovação humana. Pilotar: rodar um fluxo real com registro e uma métrica combinada, como a taxa de bloqueios úteis ou o retrabalho evitado, seguindo a lógica de medir um piloto de automação com IA. Transferir: entregar as regras documentadas e versionadas para o time, com dono definido, e decidir se expande, ajusta ou para.

Se o agente em questão não é só de código, mas opera ferramentas expostas a outras pessoas ou canais, o raciocínio de evidência antes da exposição aparece também no checklist de segurança do OpenClaw Gateway.

Perguntas frequentes

O que são claude code hooks e para que servem? São comandos configurados para rodar em eventos específicos do ciclo do Claude Code, como antes e depois do uso de uma ferramenta. Servem para impor regras que não podem depender da memória do modelo: bloquear ações, validar resultados e registrar o que aconteceu.

Um hook consegue impedir que o agente execute um comando? Sim, o hook de PreToolUse pode bloquear a ferramenta antes de ela rodar, e a mensagem do bloqueio é devolvida ao agente. Mesmo assim, ele deve ser combinado com permissões mínimas e ambiente isolado, porque um filtro isolado pode ter lacunas. Confirme o comportamento exato de códigos de saída na documentação da sua versão.

Hooks substituem a revisão humana? Não. Eles automatizam verificações objetivas e criam registro, mas decisões de negócio, como publicar, apagar dados ou falar com clientes, continuam pedindo aprovação de uma pessoa. O hook pode ser justamente o mecanismo que interrompe a ação e aciona essa pessoa.

Por onde começar sem arriscar o projeto? Comece com um hook que apenas registra as ações, observe o uso real e só depois adicione bloqueios para as ações irreversíveis. Versione os scripts no repositório, teste-os fora do agente e revise o registro com regularidade para ajustar o que for excessivo ou insuficiente.

Fontes

• Anthropic: Building effective agents
• OWASP: Authorization Cheat Sheet
• OpenTelemetry: observability concepts
• OWASP Top 10 for LLM Applications