Claude Code Hooks: O Guia Avançado para Automatizar Seu Agente

Os hooks do Claude Code são comandos definidos pelo usuário que são executados automaticamente em pontos específicos do ciclo de vida do Claude Code — antes de uma chamada de ferramenta, após uma edição, quando uma sessão é iniciada, quando o Claude termina um turno — para que você possa validar, formatar, registrar ou bloquear ações sem precisar estar envolvido a cada vez. Eles fazem a diferença entre um agente de codificação com IA que sugere e um que segue suas regras de forma determinística. Este guia explica o que são os hooks, todos os eventos em que eles podem ser acionados, como configurá-los, cinco receitas práticas que você pode copiar, a pegadinha do código de saída que confunde todo mundo, e como usar todo o poder do Claude Code sem nenhuma configuração local.

O Que São os Hooks do Claude Code?

Um hook é um handler — um comando de shell, um endpoint HTTP, uma chamada de ferramenta MCP, ou até mesmo um prompt para o modelo — que o Claude Code executa automaticamente quando um determinado evento ocorre. O handler recebe uma entrada estruturada (via stdin para hooks de comando, ou como um corpo POST para hooks HTTP), pode inspecionar o que está acontecendo, tomar uma ação, e opcionalmente retornar uma decisão que altera o que o Claude faz em seguida.

Essa última parte é o que torna os hooks poderosos, não apenas convenientes. Um hook não é apenas uma notificação — ele pode bloquear uma chamada de ferramenta, reescrever a entrada ou saída de uma ferramenta, injetar contexto extra, ou parar o Claude completamente. Em outras palavras, os hooks transformam o Claude Code de um assistente inteligente em um assistente programável que aplica as diretrizes da sua equipe de forma determinística, não apenas quando o modelo por acaso se lembra delas.

Quando os Hooks São Acionados: O Ciclo de Vida

Os hooks se conectam a eventos, e o Claude Code expõe muitos deles. Eles são agrupados por cadência: alguns disparam uma vez por sessão, alguns uma vez por turno, e alguns a cada chamada de ferramenta.

Onde os hooks disparam ao longo de uma sessão do Claude Code — de SessionStart a SessionEnd.

Os eventos que você mais usará:

• SessionStart / SessionEnd — uma vez quando uma sessão começa ou termina. Ótimo para carregar contexto (issues abertas, informações do branch, variáveis de ambiente) ou fazer limpeza.
• UserPromptSubmit — dispara quando você envia um prompt, antes de o Claude processá-lo. Você pode filtrar ou aumentar o prompt.
• PreToolUse — antes de qualquer chamada de ferramenta. É aqui que você bloqueia ações perigosas.
• PostToolUse (e PostToolUseFailure) — depois que uma chamada de ferramenta é bem-sucedida (ou falha). O lugar para lint, formatação e verificação.
• Stop / StopFailure — quando o Claude termina de responder, ou o turno termina com um erro.
• Notification — quando o Claude Code emite uma notificação (útil para alertas de desktop).

Além desses, o Claude Code também dispara hooks para subagentes (SubagentStart/SubagentStop), tarefas (TaskCreated/TaskCompleted), compactação de contexto (PreCompact/PostCompact), mudanças de diretório de trabalho (CwdChanged), mudanças de arquivo no disco (FileChanged), carregamento de instruções (InstructionsLoaded), e mais. A amplitude é o ponto principal: quase qualquer momento no loop do agente é um lugar onde você pode anexar uma política.

Os Cinco Tipos de Handlers de Hook

Um evento de hook pode acionar cinco tipos diferentes de handler, o que é o que torna o sistema flexível:

1. command — executa um comando de shell; lê a entrada via stdin, sinaliza decisões via código de saída e stdout.
2. http — envia o JSON do evento via POST para uma URL e lê a resposta em JSON.
3. mcp_tool — chama uma ferramenta em um servidor MCP conectado.
4. prompt — uma avaliação do modelo em um único turno que retorna uma decisão em JSON do tipo sim/não (útil para verificações imprecisas).
5. agent — inicia um subagente (experimental).

Para a maioria das equipes, os hooks do tipo command fazem 90% do trabalho — um script de shell já é suficiente para fazer lint, bloquear ou registrar logs.

Como Configurar um Hook

Os hooks ficam em arquivos de configurações (a documentação oficial de hooks do Claude Code é a referência canônica), e onde você os coloca controla seu escopo:

A estrutura tem três níveis: escolha um evento, adicione um grupo de matcher, depois defina os handlers. Os matchers decidem a quais chamadas de ferramenta um hook se aplica — "*" (ou omiti-lo) corresponde a tudo, um simples Edit|Write corresponde exatamente a essas ferramentas, e qualquer coisa mais complexa é tratada como uma expressão regular. (Ferramentas MCP correspondem ao padrão mcp__<server>__<tool>.)

Aqui está um hook PostToolUse que executa uma verificação de lint depois de cada edição:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/path/to/lint-check.sh" }]
      }
    ]
  }
}

Cinco Receitas Práticas de Hooks

Esses são os padrões que as equipes buscam primeiro:

1. Fazer lint ou formatar depois de cada edição. Um hook PostToolUse correspondido a Edit|Write que executa seu formatador ou linter, para que o código do agente sempre atenda às suas regras de estilo.
2. Bloquear comandos destrutivos. Um hook PreToolUse correspondido a Bash que inspeciona o comando e bloqueia rm -rf e afins antes que eles sejam executados.
3. Notificações de desktop. Um hook Notification que te avisa quando o Claude precisa de atenção ou termina uma tarefa longa.
4. Registro de auditoria. Um hook PostToolUse (ou direcionado a MCP) que registra cada chamada de ferramenta para conformidade — o que foi executado, quando, e com quais argumentos.
5. Carregar contexto do projeto na inicialização. Um hook SessionStart que traz issues abertas, o branch atual, ou variáveis de ambiente para que o agente comece cada sessão já orientado.

Cinco receitas comuns de hooks e os eventos aos quais elas se conectam.

A Pegadinha do Código de Saída

Este é o detalhe que confunde todo mundo, então internalize isto: para hooks do tipo command, apenas o código de saída 2 bloqueia. Saída 0 significa sucesso (e o stdout é analisado em busca de qualquer decisão em JSON). Saída 2 é um erro bloqueante — seu stderr é enviado de volta para o Claude. Qualquer outro código, incluindo a saída 1, é um erro não bloqueante — o Claude continua.

Então, se você escrever um hook do tipo "bloqueie isto" e usar exit 1, ele não vai bloquear — a ação prossegue. Para de fato aplicar uma política a partir de um hook de comando, use exit 2. (Hooks de comando também podem retornar controle mais rico como JSON no stdout — permissionDecision: "deny" para PreToolUse, updatedInput para reescrever argumentos, additionalContext para injetar informações, e continue: false para parar o Claude completamente.)

Um Exemplo Prático: Bloqueando rm -rf

Vamos construir a proteção contra comandos destrutivos do início ao fim, porque isso mostra cada parte móvel. Primeiro, a configuração — um hook PreToolUse correspondido a Bash:

{ "hooks": { "PreToolUse": [{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh" }] }] } }

Depois o script, guard.sh. O Claude Code envia o evento como JSON via stdin, incluindo a entrada da ferramenta; o script lê isso, verifica o comando, e decide:

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
  echo "Blocked: destructive command refused by policy." >&2
  exit 2     # exit 2 blocks — exit 1 would NOT
fi
exit 0

A linha decisiva é exit 2. Retorne 0 e o comando é executado; retorne 1 e — contraintuitivamente — ele ainda assim é executado como um erro não bloqueante; apenas exit 2 bloqueia e envia sua mensagem de stderr de volta para o Claude para que ele entenda o motivo. Torne o script executável, faça o commit dele em .claude/hooks/, e agora toda chamada Bash passa pela sua proteção — para toda a sua equipe, já que o settings.json do projeto é compartilhável. Para uma garantia rígida em vez de uma rede de melhor esforço, combine isso com as regras de permissão do Claude Code; como uma rede de segurança determinística e versionada, este hook já cumpre seu papel.

Quando os Hooks Não São a Resposta

Os hooks servem para políticas determinísticas e repetíveis — "sempre faça lint depois de uma edição", "nunca execute rm -rf". Eles são a ferramenta errada para coisas que exigem julgamento (use o modelo ou um hook do tipo prompt para decisões imprecisas) e para garantias rígidas de segurança (use o sistema de permissões, já que os filtros if de hook de comando falham de forma aberta). Também não abuse dos hooks: todo hook de comando executa um processo com um timeout, e uma quantidade excessiva de hooks lentos adiciona latência a cada chamada de ferramenta. Mantenha-os rápidos, poucos, e focados nas regras que realmente importam.

Notas de Segurança que Vale a Pena Conhecer

Algumas realidades que a documentação deixa explícitas:

• O filtro if falha de forma aberta. Se você usar o campo if para restringir um hook a uma regra de permissão e o comando não puder ser analisado, o hook é executado mesmo assim. Para aplicação rígida de permitir/negar, use o sistema de permissões do Claude Code, não os hooks.
• Os hooks são executados sem um terminal de controle — eles não conseguem exibir prompts em /dev/tty. Use systemMessage ou a saída restrita terminalSequence para mensagens voltadas ao usuário.
• O stdout precisa estar limpo. Apenas o objeto de decisão em JSON deve estar no stdout; saídas perdidas de perfis de shell podem quebrar a análise.
• Trate o contexto injetado com cuidado. additionalContext deve ser escrito como declarações factuais, não como comandos imperativos, para funcionar bem com as defesas contra injeção de prompt.

Hooks São Engenharia de Harness em Miniatura

Dando um passo atrás, os hooks são um exemplo concreto de uma ideia maior: o modelo não é o agente inteiro — o sistema ao redor dele também é. Os hooks fazem parte do harness que torna um agente de codificação confiável, ao lado do loop, das ferramentas, da memória e do sandbox. (Nós nos aprofundamos nesse modelo mental em engenharia de harness.) Quando você escreve um bloqueio PreToolUse ou um linter PostToolUse, você está fazendo engenharia de harness — moldando o comportamento do agente de forma determinística em vez de torcer para que o modelo se comporte bem.

Esse enquadramento também te diz quando os hooks valem o esforço: qualquer regra que você teria que lembrar o agente toda vez é uma candidata a um hook.

Usando Todo o Poder do Claude Code Sem Configuração Local

Os hooks vivem na CLI do Claude Code, o que significa que você precisa tê-la instalada e configurada para usá-los — uma barreira para quem não está configurado em um terminal, e algo impossível para colegas de equipe que não são desenvolvedores. Se você quer as capacidades de agente do Claude Code sem gerenciar uma instalação local, você pode executar o Claude Code no seu navegador na Happycapy: ela executa o Claude Code em um sandbox de nuvem gerenciado onde o harness — o loop, as ferramentas, a memória e o isolamento aos quais os hooks se conectam — já está todo configurado para você. Você descreve uma tarefa e observa o agente trabalhar em um desktop visual, sem necessidade de terminal.

Pense da seguinte forma: os hooks permitem que usuários avançados ajustem manualmente o harness do Claude Code; a Happycapy oferece a todos um harness gerenciado, pronto para uso. Se você queria colocar o Claude Code para trabalhar mas a configuração da CLI te impediu, comece gratuitamente em happycapy.ai e execute uma tarefa real no seu navegador hoje mesmo.

Perguntas Frequentes

P: O que são os hooks do Claude Code?

São handlers definidos pelo usuário — comandos de shell, endpoints HTTP, chamadas de ferramenta MCP, ou prompts para o modelo — que o Claude Code executa automaticamente em eventos do ciclo de vida, como antes de uma chamada de ferramenta (PreToolUse), depois de uma edição (PostToolUse), ou no início de uma sessão. Eles podem validar, formatar, registrar, bloquear, ou reescrever ações.

P: Quais eventos de hook o Claude Code suporta?

Muitos — incluindo SessionStart/SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse (e PostToolUseFailure), Stop/StopFailure, Notification, eventos de subagente e de tarefa, e eventos de compactação. Eles disparam uma vez por sessão, uma vez por turno, ou a cada chamada de ferramenta.

P: Como eu faço um hook bloquear uma chamada de ferramenta?

Para hooks de comando, encerre com o código 2 — apenas a saída 2 bloqueia (a saída 1 não bloqueia). Para PreToolUse, você também pode retornar um JSON com permissionDecision: "deny". Para aplicação rígida, prefira o sistema de permissões do Claude Code, já que o filtro if do hook falha de forma aberta.

P: Onde eu configuro os hooks do Claude Code?

Em arquivos de configurações: ~/.claude/settings.json (todos os projetos), .claude/settings.json (um projeto, compartilhável), ou .claude/settings.local.json (apenas local). Você escolhe um evento, adiciona um matcher, e define os handlers.

P: Posso usar os hooks do Claude Code sem instalar a CLI?

Os hooks em si exigem a CLI do Claude Code. Se seu objetivo é usar o Claude Code sem configuração local, execute-o em um sandbox de navegador gerenciado como a Happycapy, que fornece o agente e seu harness prontos para uso — ideal para quando você não quer instalar e configurar a CLI você mesmo.

P: Qual é um bom primeiro hook para adicionar?

Um linter PostToolUse correspondido a Edit|Write — ele executa seu formatador depois de cada mudança de código, para que a saída do agente sempre atenda às suas regras de estilo. É de baixo risco e imediatamente útil.

Guias relacionados

• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?