O que são hooks do Claude Code?
Hooks do Claude Code são comandos de shell que rodam automaticamente em pontos definidos do ciclo de vida do agente, como antes de uma ferramenta rodar ou quando um turno termina. Como rodam sempre, em vez de depender do modelo, são uma forma confiável de impor regras e adicionar verificações.
Eventos
Os hooks são definidos em arquivos settings.json e associados a um evento. Para eventos de ferramenta, um matcher permite mirar ferramentas específicas, como Bash ou Edit.
- PreToolUse: antes de uma ferramenta rodar; pode bloquear a chamada.
- PostToolUse: depois que uma ferramenta termina, por exemplo para formatar o arquivo editado.
- UserPromptSubmit: antes de a sua mensagem chegar ao modelo.
- Stop: quando o agente termina o turno.
- SessionStart: quando uma sessão começa, útil para adicionar contexto.
- Notification: quando o Claude Code envia uma notificação.
Como funciona
O comando do hook recebe os detalhes do evento, como o nome e a entrada da ferramenta, em JSON pela entrada padrão. O código de saída diz ao Claude Code o que fazer: 0 significa seguir em frente, e 2 bloqueia a ação e passa a mensagem de erro ao modelo. Para um controle mais fino, um hook também pode devolver uma decisão e um motivo em JSON.
Para que são usados
Os hooks transformam em regra qualquer coisa que o modelo possa esquecer.
- Bloquear comandos perigosos ou a leitura de arquivos como .env.
- Rodar um formatador ou linter depois de cada edição.
- Reescrever comandos para que a saída seja mais curta.
- Enviar uma notificação ou rodar testes quando um turno termina.
Pontos de atenção
Os hooks rodam com as suas permissões de usuário e sem perguntar, então não adicione o hook de outra pessoa sem lê-lo. Um hook lento deixa lenta cada chamada de ferramenta, então mantenha-os rápidos. O texto que um hook devolve pode ir parar no contexto do modelo, então seja breve.
Hooks no AgentVera
O AgentVera roda vários dos seus recursos como hooks nos agentes Claude Code. Já o perfil de contexto Lean não carrega os hooks do nível de usuário.
- Smart tools: quatro hooks que bloqueiam leituras repetidas de arquivos, reduzem execuções completas de testes aos testes afetados, apontam novos erros de tipo logo após uma edição e compartilham o resultado de um comando entre agentes. Todos vêm ligados por padrão.
- RTK: os comandos Bash do Claude Code são reescritos por um hook em versões com saída mais curta (git status → rtk git status).
- O Codex não tem hooks, então lá o RTK funciona por instruções, e as smart tools rodam só em agentes Claude Code locais.
Perguntas frequentes
Onde os hooks do Claude Code são configurados?
Em arquivos settings.json: ~/.claude/settings.json para o seu usuário, .claude/settings.json para o projeto e .claude/settings.local.json só para a sua máquina. Você também pode gerenciá-los com o comando /hooks.
Como um hook bloqueia um comando?
Se um hook PreToolUse sai com código 2, a chamada da ferramenta é bloqueada e a saída de erro do hook vai para o modelo como motivo.
Hooks são seguros?
Hooks são comandos de shell que rodam com as suas permissões, então são tão seguros quanto o que contêm. Leia os hooks de projeto que vêm com um repositório antes de rodá-los.
Qual a diferença entre um hook e uma skill?
Um hook é um comando que roda toda vez que um determinado evento acontece; o modelo não decide. Uma skill é um conjunto de instruções e arquivos que o modelo carrega quando julga relevante.