Hooks do Claude Code: O Guia para Utilizadores Avançados que Automatizam o Seu Agente

Claude Code hooks são comandos definidos pelo utilizador que são executados automaticamente em pontos específicos do ciclo de vida do Claude Code — antes de uma chamada de ferramenta, depois de uma edição, quando uma sessão começa, quando o Claude termina um turno — para que possa validar, formatar, registar ou bloquear ações sem estar no circuito de cada vez. São a diferença entre um agente de codificação de IA que sugere e um que segue as suas regras de forma determinística. Este guia explica o que são os hooks, todos os eventos em que podem ser acionados, como configurá-los, cinco receitas práticas que pode copiar, a armadilha do código de saída que apanha toda a gente, e como usar todo o poder do Claude Code sem qualquer configuração local.

O Que São os Claude Code Hooks?

Um hook é um handler — um comando de shell, um endpoint HTTP, uma chamada a uma ferramenta MCP, ou até um prompt de modelo — que o Claude Code executa automaticamente quando ocorre um determinado evento. O handler recebe input estruturado (no stdin para hooks de comando, ou como corpo de POST para hooks HTTP), pode inspecionar o que está a acontecer, tomar uma ação e, opcionalmente, devolver uma decisão que altera o que o Claude faz a seguir.

É essa última parte que torna os hooks poderosos e não apenas convenientes. Um hook não é apenas uma notificação — pode bloquear uma chamada de ferramenta, reescrever o input ou output de uma ferramenta, injetar contexto adicional, ou parar o Claude por completo. Por outras palavras, os hooks transformam o Claude Code de um assistente inteligente num assistente programável que aplica as regras da sua equipa de forma determinística, e não apenas quando o modelo se lembra delas.

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

Os hooks estão associados a eventos, e o Claude Code expõe muitos deles. Agrupam-se por cadência: alguns são acionados uma vez por sessão, outros uma vez por turno, e outros em cada chamada de ferramenta.

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

Os eventos que irá usar mais:

• SessionStart / SessionEnd — uma vez quando uma sessão começa ou termina. Ótimo para carregar contexto (issues em aberto, informação de branch, variáveis de ambiente) ou para limpeza.
• UserPromptSubmit — acionado quando submete um prompt, antes de o Claude o processar. Pode filtrar ou aumentar o prompt.
• PreToolUse — antes de qualquer chamada de ferramenta. É aqui que bloqueia ações perigosas.
• PostToolUse (e PostToolUseFailure) — depois de uma chamada de ferramenta ter sucesso (ou falhar). O local para linting, formatação e verificação.
• Stop / StopFailure — quando o Claude termina de responder, ou o turno acaba com um erro.
• Notification — quando o Claude Code emite uma notificação (útil para alertas de desktop).

Para além destes, o Claude Code também aciona hooks para subagentes (SubagentStart/SubagentStop), tarefas (TaskCreated/TaskCompleted), compactação de contexto (PreCompact/PostCompact), mudanças de diretório de trabalho (CwdChanged), alterações de ficheiros em disco (FileChanged), carregamento de instruções (InstructionsLoaded), e mais. A amplitude é precisamente o objetivo: praticamente qualquer momento no ciclo do agente é um local onde pode aplicar uma política.

Os Cinco Tipos de Handlers de Hooks

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

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

Para a maioria das equipas, os hooks command fazem 90% do trabalho — um script de shell é suficiente para fazer lint, bloquear ou registar.

Como Configurar um Hook

Os hooks vivem em ficheiros de configurações (a documentação oficial dos hooks do Claude Code é a referência canónica), e o local onde os coloca controla o seu âmbito:

A estrutura aninha-se em três níveis: escolhe um evento, adiciona um grupo de matcher, depois define os handlers. Os matchers decidem a que chamadas de ferramenta um hook se aplica — "*" (ou omitir) corresponde a tudo, um simples Edit|Write corresponde a essas ferramentas exatas, e qualquer coisa mais complexa é tratada como uma expressão regular. (As 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

Estes são os padrões a que as equipas recorrem primeiro:

1. Fazer lint ou formatação depois de cada edição. Um hook PostToolUse associado a Edit|Write que executa o seu formatador ou linter, para que o código do agente cumpra sempre as suas regras de estilo.
2. Bloquear comandos destrutivos. Um hook PreToolUse associado a Bash que inspeciona o comando e bloqueia rm -rf e afins antes de sequer serem executados.
3. Notificações de desktop. Um hook Notification que o avisa quando o Claude precisa de atenção ou termina uma tarefa longa.
4. Registo de auditoria. Um hook PostToolUse (ou direcionado a MCP) que regista cada chamada de ferramenta para conformidade — o que foi executado, quando, e com que argumentos.
5. Carregar contexto do projeto no arranque. Um hook SessionStart que traz issues em aberto, 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 a que se associam.

A Armadilha do Código de Saída

Este é o pormenor que apanha toda a gente, por isso interiorize-o: para os hooks 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 — o seu stderr é devolvido ao Claude. Qualquer outro código, incluindo a saída 1, é um erro não bloqueante — o Claude continua.

Portanto, se escrever um hook do tipo "bloquear isto" e fizer exit 1, este não irá bloquear — a ação prossegue. Para efetivamente aplicar uma política a partir de um hook de comando, use exit 2. (Os hooks de comando também podem devolver um controlo mais rico em JSON no stdout — permissionDecision: "deny" para PreToolUse, updatedInput para reescrever argumentos, additionalContext para injetar informação, e continue: false para parar o Claude por completo.)

Um Exemplo Prático: Bloquear rm -rf

Vamos construir a proteção contra comandos destrutivos de ponta a ponta, porque mostra todas as partes móveis. Primeiro, a configuração — um hook PreToolUse associado 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 no stdin, incluindo o input da ferramenta; o script lê-o, 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. Devolva 0 e o comando é executado; devolva 1 e — contraintuitivamente — ainda assim é executado como um erro não bloqueante; só exit 2 bloqueia e devolve a sua mensagem de stderr ao Claude para que este entenda porquê. Torne o script executável, submeta-o em .claude/hooks/, e cada chamada Bash passa agora pela sua proteção — para toda a sua equipa, uma vez que o settings.json do projeto é partilhável. Para uma garantia rígida em vez de uma rede de melhor esforço, combine-o com as regras de permissão do Claude Code; como rede de segurança determinística e sob controlo de versões, este hook já cumpre a sua função.

Quando os Hooks Não São a Resposta

Os hooks servem para políticas determinísticas e repetíveis — "fazer sempre lint depois de uma edição", "nunca executar rm -rf". São a ferramenta errada para coisas que exigem discernimento (use o modelo ou um hook prompt para decisões difusas) e para garantias de segurança rígidas (use o sistema de permissões, já que os filtros if dos hooks de comando falham de forma aberta). Também não abuse dos hooks: cada hook de comando executa um processo com um tempo limite, e uma quantidade excessiva de hooks lentos acrescenta 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 torna explícitas:

• O filtro if falha de forma aberta. Se usar o campo if para restringir um hook a uma regra de permissão e o comando não puder ser interpretado, o hook é executado na mesma. Para uma aplicação rígida de permitir/negar, use o sistema de permissões do Claude Code, e não os hooks.
• Os hooks são executados sem um terminal de controlo — não podem pedir input através de /dev/tty. Use systemMessage ou o output restrito terminalSequence para mensagens dirigidas ao utilizador.
• O stdout tem de estar limpo. Apenas o objeto de decisão em JSON deve estar no stdout; output disperso do perfil de shell pode 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 prompts.

Os Hooks São Engenharia de Harness em Miniatura

Recuando um pouco, os hooks são um exemplo concreto de uma ideia maior: o modelo não é o agente inteiro — o sistema à sua volta é que faz a diferença. Os hooks fazem parte do harness que torna um agente de codificação fiável, ao lado do loop, das ferramentas, da memória e da sandbox. (Aprofundamos esse modelo mental em engenharia de harness.) Quando escreve um bloqueio PreToolUse ou um linter PostToolUse, está a fazer engenharia de harness — a moldar o comportamento do agente de forma determinística em vez de esperar que o modelo se comporte bem.

Esse enquadramento também lhe diz quando os hooks valem o esforço: qualquer regra que de outra forma teria de recordar ao agente sempre é candidata a hook.

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

Os hooks vivem na CLI do Claude Code, o que significa que precisa de a ter instalada e configurada para os usar — uma barreira para quem não está configurado num terminal, e impossível para colegas de equipa que não sejam programadores. Se quiser as capacidades de agente do Claude Code sem gerir uma instalação local, pode executar o Claude Code no seu browser no Happycapy: executa o Claude Code numa sandbox de nuvem gerida onde o harness — o loop, as ferramentas, a memória e o isolamento aos quais os hooks se ligam — já está montado para si. Descreve uma tarefa e observa o agente a trabalhar num ambiente de trabalho visual, sem necessidade de terminal.

Pense assim: os hooks permitem que utilizadores avançados afinem manualmente o harness do Claude Code; o Happycapy dá a todos um harness gerido pronto a usar. Se sempre quis pôr o Claude Code a trabalhar mas a configuração da CLI o impediu, comece gratuitamente em happycapy.ai e execute hoje mesmo uma tarefa real no seu browser.

Perguntas Frequentes

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

São handlers definidos pelo utilizador — comandos de shell, endpoints HTTP, chamadas a ferramentas MCP, ou prompts de 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. Podem validar, formatar, registar, bloquear ou reescrever ações.

P: Que eventos de hook o Claude Code suporta?

Muitos — incluindo SessionStart/SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse (e PostToolUseFailure), Stop/StopFailure, Notification, eventos de subagentes e de tarefas, e eventos de compactação. São acionados uma vez por sessão, uma vez por turno, ou em cada chamada de ferramenta.

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

Para hooks de comando, termine com o código 2 — apenas o código de saída 2 bloqueia (o código 1 não bloqueia). Para PreToolUse, também pode devolver JSON com permissionDecision: "deny". Para uma 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 configuro os hooks do Claude Code?

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

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

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

P: Qual é um bom primeiro hook a adicionar?

Um linter PostToolUse associado a Edit|Write — executa o seu formatador depois de cada alteração de código, para que o output do agente cumpra sempre as 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?