Hooks do Claude Code: controle determinístico sobre o que o agente faz

Anatomia de um hook

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}

Três partes: o evento, um matcher (uma expressão regular aplicada ao nome da ferramenta em eventos de ferramenta; omita-o para corresponder a tudo) e um ou mais comandos. O comando recebe um objeto JSON na entrada padrão que descreve o evento — nos eventos de ferramenta, ele inclui tool_name e tool_input, que é como o exemplo acima encontra o arquivo que acabou de ser editado. Coloque-o em .claude/settings.json para compartilhar com o repositório, ~/.claude/settings.json para uso pessoal, ou execute /hooks e deixe o Claude Code escrevê-lo.

Os eventos

• PreToolUse — antes de uma ferramenta ser executada. O único evento que pode bloquear: a saída 2 cancela a chamada, e o Claude lê sua saída de erro padrão como o motivo.
• PostToolUse — depois que uma ferramenta é executada com sucesso. Formatadores, linters e verificações de tipos no arquivo editado.
• UserPromptSubmit — quando você envia um prompt; pode injetar contexto ou rejeitar o prompt.
• Stop / SubagentStop — quando o agente (ou um subagente) está prestes a encerrar. A saída 2 aqui significa "ainda não terminou" — o uso clássico é impedir o encerramento enquanto os testes falham.
• PreCompact — antes de /compact; salve tudo de que precisar da transcrição completa.
• SessionStart — quando uma sessão começa ou é retomada; carregue o ambiente e exiba lembretes.
• Notification — quando o Claude Code precisa da sua atenção (solicitação de permissão, inatividade); conecte-o a uma notificação na área de trabalho ou no Slack.

Bloqueio de comandos perigosos

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

O código de saída 2 é o contrato: a chamada de ferramenta não acontece, e tudo o que o hook escrever na saída de erro padrão se torna a explicação que o Claude vê, para que ele possa escolher outra abordagem em vez de tentar a mesma coisa novamente. Qualquer outro código de saída diferente de zero é registrado, mas não bloqueia.

"Não encerre até que os testes passem"

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

Combine isso com um limite de --max-turns em execuções sem interface para que uma falha realmente impossível de corrigir não gere um ciclo infinito.

Hooks vs CLAUDE.md vs permissões

CLAUDE.md contém orientações que o modelo lê; /permissions é uma lista do que ele pode fazer sem perguntar; hooks são código que é executado independentemente disso. Use CLAUDE.md para estilo e contexto, permissões para definir o que é permitido e o que exige confirmação, e hooks para tudo o que deve ser garantido em todas as ocasiões — formatação, verificação de segredos, validações obrigatórias de testes e logs de auditoria. Eles se combinam: uma permissão permite executar Bash(git *) , e um hook PreToolUse ainda bloqueia git push --force.

Hooks e o gateway

Os hooks são executados localmente e nunca acessam a API, então nada muda quando o Claude Code aponta para ANTHROPIC_BASE_URL=https://aiprimetech.io. Uma combinação útil: um hook Stop que exibe /costde uso no mesmo estilo a partir dos seus próprios logs, para que uma equipe que usa créditos pagos conforme o consumo veja o preço de cada sessão ao encerrá-la.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Perguntas frequentes

A AI Prime Tech é um gateway de API independente e não é afiliada, endossada nem patrocinada pela Anthropic. “Claude” e “Claude Code” são marcas comerciais da Anthropic. Os recursos do Claude Code descritos aqui seguem a documentação pública da Anthropic no momento da redação e mudam com frequência; os preços e as listas de modelos nesta página são obtidos das configurações atuais deste gateway.