Source: https://aiprimetech.io/pt/claude-code/hooks/

[Início](/pt/) › [Claude Code](/pt/claude-code/) › Hooks

[Visão geral](/pt/claude-code/)[Instalação](/pt/claude-code/install/)[referência da CLI](/pt/claude-code/cli/)[Preços e limites](/pt/claude-code/pricing/)[Agent SDK](/pt/claude-code/sdk/)[Skills e plugins](/pt/claude-code/skills/)[GitHub](/pt/claude-code/github/)[Web, desktop e IDE](/pt/claude-code/web-and-desktop/)[Modelos](/pt/claude-code/models/)[Erros](/pt/claude-code/errors/)[Código aberto?](/pt/claude-code/open-source/)[Tutorial](/pt/claude-code/tutorial/)[Para estudantes](/pt/claude-code/for-students/)[Automação de QA](/pt/claude-code/qa-automation/)[vs Cursor](/pt/claude-code/vs-cursor/)[vs Codex e OpenCode](/pt/claude-code/vs-codex/)[Subagentes](/pt/claude-code/subagents/)[Hooks](/pt/claude-code/hooks/)[MCP](/pt/claude-code/mcp/)[Ecossistema](/pt/claude-code/ecosystem/)[VS Code](/pt/claude-code/vscode/)[OpenRouter](/pt/claude-code/openrouter/)[Limites de requisições](/pt/claude-code/rate-limits/)[Guia em chinês](/claude-code/zh/)

Última atualização: 11 de outubro de 2026

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

Hooks são comandos de shell que o Claude Code executa em pontos fixos do seu ciclo — antes de uma chamada de ferramenta, depois dela, quando você envia um prompt e quando ele termina. Ao contrário das instruções em CLAUDE.md, que o modelo pode ou não seguir, um hook sempre é executado. É assim que você cria regras que são cumpridas.

## TLDR
- Configurados em .claude/settings.json (projeto) ou ~/.claude/settings.json (usuário), ou com /hooks.
- Eventos: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart.
- O hook recebe JSON na entrada padrão (nome da ferramenta, entrada, sessão); a saída 0 permite, e a saída 2 bloqueia e envia a saída de erro padrão de volta ao Claude.
- Usos típicos: formatar após cada edição, bloquear comandos perigosos, exigir testes antes de encerrar e enviar notificações na área de trabalho.

## 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.

## Experimente gratuitamente primeiro

Novas contas recebem $5 em crédito gratuito para a API com o código CLAUDECODE — suficiente para uma noite de Claude Code com Sonnet — e depois créditos com 7.69231× o valor nominal.

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

[Crie uma conta com o código CLAUDECODE](/register?promo=CLAUDECODE)

## Perguntas frequentes

O que são hooks do Claude Code?

Comandos de shell que o Claude Code executa automaticamente em eventos do seu ciclo — antes/depois de chamadas de ferramentas, no envio de um prompt e no encerramento. Eles são determinísticos, ao contrário das instruções em CLAUDE.md.Como bloqueio um comando com um hook?

Um hook PreToolUse com matcher Bash que inspeciona tool_input.command na entrada padrão e termina com o código 2; o texto da saída de erro padrão é mostrado ao Claude como o motivo.Onde ficam os hooks?

Em .claude/settings.json no projeto (compartilhado) ou em ~/.claude/settings.json (pessoal), sob a chave hooks; /hooks permite editá-los interativamente.

## Execute o Claude Code no gateway

Os mesmos modelos, duas variáveis de ambiente, créditos com 7.69231× o valor nominal — ou um plano ilimitado com preço fixo. Novas contas: $5 em crédito gratuito para a API com o código CLAUDECODE.[Obter uma chave de API](/register?promo=CLAUDECODE) [Ver planos ilimitados](/pt/plans/)

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.

## Mais guias do Claude Code

[Claude Code: o guia completo](/pt/claude-code/)[Como instalar o Claude Code](/pt/claude-code/install/)[Documentação da CLI do Claude Code: comandos e flags](/pt/claude-code/cli/)[Preços e limites do Claude Code, explicados](/pt/claude-code/pricing/)[O SDK do Claude Code, agora Claude Agent SDK](/pt/claude-code/sdk/)[Skills e plugins do Claude Code](/pt/claude-code/skills/)[Claude Code no GitHub: o App, a Action e @claude](/pt/claude-code/github/)[O Claude Code tem uma interface web? Entenda as versões web, desktop e para IDE](/pt/claude-code/web-and-desktop/)[Qual modelo o Claude Code usa e como alterá-lo](/pt/claude-code/models/)[Erros do Claude Code e como corrigi-los](/pt/claude-code/errors/)[O Claude Code é de código aberto?](/pt/claude-code/open-source/)[Tutorial do Claude Code: sua primeira sessão real](/pt/claude-code/tutorial/)[Claude para estudantes: Claude Code, a API e o que você realmente ganha na área de educação](/pt/claude-code/for-students/)[Como usar o Claude Code para automação de QA](/pt/claude-code/qa-automation/)[Claude Code vs Cursor: qual usar, quando — e como usar ambos](/pt/claude-code/vs-cursor/)[Claude Code vs Codex vs OpenCode: comparação dos agentes de terminal](/pt/claude-code/vs-codex/)[Subagentes do Claude Code: como funcionam, como defini-los e equipes de agentes](/pt/claude-code/subagents/)[MCP no Claude Code: conexão de servidores, escopos, MCP remoto e exemplos reais](/pt/claude-code/mcp/)[O ecossistema do Claude Code: roteadores, frameworks, plugins e as listas que os acompanham](/pt/claude-code/ecosystem/)[Claude Code no VS Code: a extensão, o uso pelo terminal e os erros](/pt/claude-code/vscode/)[Como usar o OpenRouter no Claude Code (e quando não usar)](/pt/claude-code/openrouter/)[Erro de limite de taxa do Claude: o que significa "Erro de API: limite de taxa atingido" e como corrigir](/pt/claude-code/rate-limits/)[Como usar o Claude Code: da instalação ao uso diário](/claude-code/zh/)