Claude Code Hooks: settings.json, os 5 eventos e o bloqueio por exit code
Hooks são a camada determinística do Claude Code: eles sempre rodam, sem depender do modelo. Este passo a passo ilustrado usa o vídeo de hooks da própria Anthropic para as imagens — os cinco eventos, um script de bloqueio no PreToolUse, deny em JSON estruturado e uma config completa de formatação no PostToolUse.
TL;DR — o que são os hooks do Claude Code
- Hooks são determinísticos: rodam em pontos fixos do ciclo de vida do Claude Code, toda vez. Uma instrução no CLAUDE.md tipo “rode o Prettier depois de cada edição” funciona na maioria das vezes — um hook funciona sempre.
- São cinco eventos: UserPromptSubmit (antes do seu prompt ser processado), PreToolUse (antes de uma chamada de ferramenta), PostToolUse (quando uma ferramenta termina), Notification e Stop (quando o Claude termina de responder).
- Um hook de PreToolUse que sai com exit code 2 bloqueia a chamada de ferramenta, e a mensagem de stderr volta para o Claude para ele saber o porquê. Exit code 0 deixa a chamada passar.
- Os hooks moram no settings.json — um evento, um matcher de ferramenta opcional e um comando. Guarde-os no .claude/settings.json do projeto e faça commit, e o time inteiro herda as mesmas garantias.
Hooks in Claude Code
Canal:Claude (official Anthropic channel)3:22
Claude Code Hooks, Explained Simply
Canal:Agentic Lab8:32
Claude Code - Getting Started with Hooks
Canal:Greg Baugues11:53
Hooks reference — Claude Code documentation
Docs:code.claude.com
Os frames deste guia vêm do vídeo explicativo oficial de hooks da Anthropic; o texto do passo a passo foi escrito de forma independente e conferido com a referência oficial de hooks.
Os screenshots permanecem propriedade de seus criadores e são usados com atribuição como documentação visual. Cada passo tem deep-link para o momento exato do vídeo original.
Configurando hooks do Claude Code, passo a passo
1 · Como os hooks ficam na prática
- 1
Veja um hook disparar no fim de uma resposta
A linha de status mostra “Running stop hook · 39s · 484 tokens” — o Claude Code está executando um Stop hook antes de devolver o turno para você. Essa é a ideia inteira em um screenshot: um comando que você registrou roda num ponto fixo do ciclo de vida, a cada ocorrência que der match, sem depender do modelo lembrar de fazer algo.
Um Stop hook executando depois da resposta do Claude — 39 segundos, 484 tokens gastos.Assistir em 0:10 - 2
Conheça os cinco eventos de hook
O UserPromptSubmit roda no momento em que você envia um prompt, antes do Claude processar. O PreToolUse roda antes de cada chamada de ferramenta. O PostToolUse roda depois que a chamada termina. O Notification dispara quando o Claude manda uma notificação, e o Stop roda quando o Claude termina de responder. Todo hook que você escrever se prende a exatamente um desses cinco pontos.
Os cinco eventos, do vídeo oficial de hooks da Anthropic — todo o resto pende desta lista.Assistir em 1:04
2 · Escreva seus primeiros hooks
- 3
Adicione um bloco de hooks ao settings.json
Um hook são três coisas no settings.json: o nome do evento, um matcher opcional que limita a qual ferramenta se aplica, e o comando a rodar. No screenshot, o matcher do PreToolUse está sendo completado com Edit — esse hook só dispara em chamadas de edição de arquivo. Se você prefere não mexer em JSON, o menu /hooks edita a mesma config de forma interativa.
O autocomplete completa o matcher com Edit, restringindo o hook de PreToolUse a edições de arquivo.Assistir em 0:14 - 4
Bloqueie comandos perigosos com exit code 2
Um hook de PreToolUse recebe o nome da ferramenta e o input como JSON no stdin. Este script passa tudo pelo jq para pegar o .tool_input.command, faz grep de padrões destrutivos — rm -rf, git push --force — e, ao dar match, imprime o motivo no stderr e sai com código 2. O exit code 2 bloqueia a chamada; o texto do stderr volta para o Claude como feedback, então o modelo sabe por que foi bloqueado e pode se ajustar.
O jq lê o comando do stdin; match de rm -rf ou --force imprime no stderr e sai com 2.Assistir em 2:02 - 5
Envie uma negação estruturada em vez de um exit code
Para controle mais fino, um hook pode imprimir uma decisão em JSON em vez de depender de exit codes. Aqui um hook de PreToolUse pega um DROP TABLE, e o hookSpecificOutput carrega permissionDecision “deny” mais um motivo — “use uma migration em vez disso” — que cai no contexto do modelo. A mesma garantia dura, mas com uma instrução acionável junto.
Um permissionDecision de deny bloqueia o comando SQL e diz ao modelo o que fazer no lugar.Assistir em 2:16 - 6
Mantenha os hooks no repositório para o time receber
Hooks configurados no .claude/settings.json do projeto são de nível de projeto e podem ser commitados. Todo mundo que clonar o repo roda os mesmos hooks automaticamente — incluindo os que bloqueiam. Guarde os scripts auxiliares em .claude/hooks/ e referencie-os com a variável de ambiente CLAUDE_PROJECT_DIR para que os caminhos resolvam não importa onde esteja o diretório de trabalho do Claude.
A pasta .claude do projeto guarda o settings.json mais um diretório hooks/ de scripts compartilhados.Assistir em 0:17 - 7
Copie uma config de hooks completa e real
Essa config faz dois trabalhos ao mesmo tempo. O bloco de PostToolUse faz match de Edit|Write|MultiEdit e roda o .claude/hooks/auto-format.sh com timeout de 30 segundos, então todo arquivo que o Claude toca sai formatado. Logo abaixo, um segundo hook faz match de Bash e loga cada comando executado — o padrão de compliance. Os campos timeout e async impedem que formatadores lentos travem a sessão.
Auto-formatação via PostToolUse com timeout de 30s, mais um hook de Bash que loga cada comando.Assistir em 2:46
3 · Use como um time
- 8
Decore o contrato de exit codes de cabeça
Exit code 0 significa seguir em frente. Exit code 2 significa bloquear — e o stderr vai para o Claude como feedback sobre o qual ele pode agir. Qualquer outro exit code mostra o stderr para você, usuário, mas a chamada continua; use isso para avisos que você quer ver sem bloquear o agente na marra.
- 9
Registre hooks pelo menu /hooks e escolha suas receitas
O comando /hooks abre a mesma configuração de forma interativa — útil para conferir quais hooks estão registrados em qual escopo. Daqui saem as quatro receitas de trabalho: auto-formatar depois de editar (PostToolUse), logar todos os comandos executados (PostToolUse no Bash), bloquear operações perigosas (PreToolUse com exit 2), e avisar você quando o Claude terminar (Stop). Princípio: se algo precisa acontecer sempre, sem falha, não coloque num prompt — coloque num hook.
O contrato de exit codes, em uma tabela
Todo comando de hook se comunica pelo seu exit code. Três casos cobrem tudo o que você precisa:
- exit 0Seguir. A chamada roda normalmente. O stdout do hook fica visível no modo transcript (Ctrl-R).
- exit 2Bloquear. A chamada é rejeitada e o stderr do hook volta para o Claude como feedback, então o modelo corrige a rota — é isso que torna os hooks de exit-2 didáticos, não apenas fatais.
- exit 1Qualquer outro código: avisar, não bloquear. O stderr é mostrado para você, mas a chamada continua. Use para hooks consultivos — “esse arquivo normalmente é gerado, tem certeza?”
Mais um caminho de upgrade: em vez de exit codes, um hook pode imprimir uma decisão em JSON (hookSpecificOutput com permissionDecision) para negar com um motivo estruturado, como no passo 5. Exit codes são o contrato simples; decisões JSON são o contrato tipado.
Quatro receitas que valem um commit hoje
O vídeo oficial destaca quatro casos de uso; aqui vão como intenção pronta para copiar:
- 1Auto-formatar depois de editar — um hook de PostToolUse com match em Edit|MultiEdit que confere a extensão do arquivo e roda o formatador certo: Prettier para TypeScript, gofmt para Go, Ruff para Python.
- 2Logar cada comando executado — um hook de PostToolUse no Bash que anexa cada comando a um arquivo. Times de compliance amam; o você do futuro debugando a última terça-feira também.
- 3Bloquear operações perigosas — um hook de PreToolUse com exit 2 protegendo diretórios de config de produção, padrões de rm -rf ou commits na main. Isso vira garantia, não sugestão.
- 4Notificar quando a tarefa termina — um hook de Stop ou Notification que dispara uma notificação de desktop ou som, para não ter de ficar de babá nas execuções longas.
As quatro cabem em um único .claude/settings.json. Comece pelo formatador — é o hook que você sente a cada salvamento.