O que são os hooks do Claude Code, e quando usá-los?

A ideia central: automático, não lembrado

O Claude Code já deixa você guiar o comportamento com instruções, em lugares como o CLAUDE.md ou um system prompt — mas isso depende de o modelo ler e escolher seguir aquilo na hora certa. Um hook remove essa dependência: é um comando que a própria aplicação executa num ponto fixo, sempre, não importa o que o modelo lembre ou deixe de lembrar.

É essa a proposta numa frase: um hook transforma uma sugestão em garantia, porque quem decide se algo acontece é o shell rodando um comando, não o modelo escolhendo obedecer.

Os eventos aos quais um hook pode se prender

O Claude Code define mais eventos do que estes sete, incluindo PreCompact, PostCompact, SubagentStart e SubagentStop, entre outros — mas estes são os que a maioria das configurações usa primeiro, porque correspondem aos momentos em que as pessoas realmente querem intervir.

• SessionStart — quando uma sessão começa ou é retomada.
• UserPromptSubmit — quando você envia um prompt, antes de o Claude processá-lo.
• PreToolUse — antes de uma chamada de ferramenta executar; é o único que pode bloqueá-la.
• PermissionRequest — quando uma chamada de ferramenta precisa de uma decisão de permissão.
• PostToolUse — depois que uma chamada de ferramenta é bem-sucedida.
• Stop — quando o Claude termina de responder.
• SessionEnd — quando uma sessão termina.

Como um hook é configurado

Um hook é JSON escrito num arquivo de settings, com três níveis de aninhamento: uma chave hooks, depois o nome do evento, depois um array de entradas — cada uma com um matcher e sua própria lista de { type: "command", command, timeout }.

O arquivo de settings pode morar em mais de um lugar. ~/.claude/settings.json vale para todos os projetos da máquina e não é feito para compartilhar. .claude/settings.json vale para um projeto e é feito para ir para o git. .claude/settings.local.json também vale para um projeto, mas fica fora do git (gitignored). Além desses, uma organização pode publicar managed policy settings, e um plugin pode trazer seu próprio hooks/hooks.json.

O matcher decide a quais chamadas de ferramenta uma entrada se aplica. “*”, ou deixar o matcher de fora, casa com tudo. Um matcher composto só de letras, dígitos, _, -, espaço, vírgula ou | — como “Bash” ou “Edit|Write” — é comparado como string exata. Qualquer outro caractere transforma o matcher inteiro numa expressão regular JavaScript não ancorada, e é isso que faz algo como “^Edit$” se comportar diferente de um simples “Edit”.

Bloqueio, saída estruturada, e quem pode desligar um hook

Um hook controla o que acontece depois principalmente pelo código de saída (exit code). Exit code 0 sem nenhuma saída significa que o hook não tem decisão a reportar, e a chamada de ferramenta segue o fluxo normal de permissão. Exit code 2 é o erro bloqueante: em eventos que podem bloquear, o exit 2 bloqueia a ação mesmo que o hook também tenha impresso JSON — nem um permissionDecision de “allow” em JSON consegue sobrepor isso. Qualquer outro código é um erro não bloqueante na maioria dos eventos, e a ação segue em frente do mesmo jeito.

Um hook também pode devolver JSON estruturado em vez de depender só do exit code: um objeto hookSpecificOutput carrega o nome do evento, um permissionDecision de allow, deny ou escalate, e o motivo dele, além de campos universais como continue (que, se false, faz o Claude parar de processar), stopReason e systemMessage.

Hooks podem ser desligados por completo com disableAllHooks: true nos settings — exceto os hooks configurados pelas managed policy settings de uma organização, que settings de usuário, projeto ou local não conseguem desligar. Um administrador pode ir além com allowManagedHooksOnly, restringindo quais hooks têm permissão de rodar.