Referência de hooks
Esta página fornece documentação de referência para implementar hooks no Claude Code.
Para um guia de início rápido com exemplos, veja Começar com hooks do Claude Code.
Configuração
Os hooks do Claude Code são configurados em seus arquivos de configurações:
~/.claude/settings.json
- Configurações do usuário.claude/settings.json
- Configurações do projeto.claude/settings.local.json
- Configurações locais do projeto (não commitadas)- Configurações de política gerenciada empresarial
Estrutura
Os hooks são organizados por matchers, onde cada matcher pode ter múltiplos hooks:
- matcher: Padrão para corresponder nomes de ferramentas, sensível a maiúsculas e minúsculas (aplicável apenas para
PreToolUse
ePostToolUse
)- Strings simples correspondem exatamente:
Write
corresponde apenas à ferramenta Write - Suporta regex:
Edit|Write
ouNotebook.*
- Use
*
para corresponder a todas as ferramentas. Você também pode usar string vazia (""
) ou deixarmatcher
em branco.
- Strings simples correspondem exatamente:
- hooks: Array de comandos para executar quando o padrão corresponder
type
: Atualmente apenas"command"
é suportadocommand
: O comando bash para executar (pode usar a variável de ambiente$CLAUDE_PROJECT_DIR
)timeout
: (Opcional) Por quanto tempo um comando deve executar, em segundos, antes de cancelar esse comando específico.
Para eventos como UserPromptSubmit
, Notification
, Stop
, e SubagentStop
que não usam matchers, você pode omitir o campo matcher:
Scripts de Hook Específicos do Projeto
Você pode usar a variável de ambiente CLAUDE_PROJECT_DIR
(disponível apenas quando
o Claude Code gera o comando hook) para referenciar scripts armazenados em seu projeto,
garantindo que funcionem independentemente do diretório atual do Claude:
Eventos de Hook
PreToolUse
Executa depois que Claude cria parâmetros de ferramenta e antes de processar a chamada da ferramenta.
Matchers comuns:
Task
- Tarefas do agenteBash
- Comandos shellGlob
- Correspondência de padrão de arquivoGrep
- Busca de conteúdoRead
- Leitura de arquivoEdit
,MultiEdit
- Edição de arquivoWrite
- Escrita de arquivoWebFetch
,WebSearch
- Operações web
PostToolUse
Executa imediatamente após uma ferramenta ser completada com sucesso.
Reconhece os mesmos valores de matcher que PreToolUse.
Notification
Executa quando Claude Code envia notificações. Notificações são enviadas quando:
- Claude precisa de sua permissão para usar uma ferramenta. Exemplo: “Claude precisa de sua permissão para usar Bash”
- A entrada do prompt ficou inativa por pelo menos 60 segundos. “Claude está esperando por sua entrada”
UserPromptSubmit
Executa quando o usuário submete um prompt, antes que Claude o processe. Isso permite que você adicione contexto adicional baseado no prompt/conversa, valide prompts, ou bloqueie certos tipos de prompts.
Stop
Executa quando o agente principal do Claude Code terminou de responder. Não executa se a parada ocorreu devido a uma interrupção do usuário.
SubagentStop
Executa quando um subagente do Claude Code (chamada da ferramenta Task) terminou de responder.
PreCompact
Executa antes que Claude Code esteja prestes a executar uma operação de compactação.
Matchers:
manual
- Invocado de/compact
auto
- Invocado de auto-compact (devido à janela de contexto cheia)
Entrada do Hook
Os hooks recebem dados JSON via stdin contendo informações da sessão e dados específicos do evento:
Entrada PreToolUse
O esquema exato para tool_input
depende da ferramenta.
Entrada PostToolUse
O esquema exato para tool_input
e tool_response
depende da ferramenta.
Entrada Notification
Entrada UserPromptSubmit
Entrada Stop e SubagentStop
stop_hook_active
é verdadeiro quando Claude Code já está continuando como resultado de
um hook de parada. Verifique este valor ou processe a transcrição para evitar que Claude Code
execute indefinidamente.
Entrada PreCompact
Para manual
, custom_instructions
vem do que o usuário passa para
/compact
. Para auto
, custom_instructions
está vazio.
Saída do Hook
Existem duas maneiras para hooks retornarem saída de volta para Claude Code. A saída comunica se deve bloquear e qualquer feedback que deve ser mostrado para Claude e o usuário.
Simples: Código de Saída
Os hooks comunicam status através de códigos de saída, stdout, e stderr:
- Código de saída 0: Sucesso.
stdout
é mostrado ao usuário no modo transcrição (CTRL-R), exceto paraUserPromptSubmit
, onde stdout é adicionado ao contexto. - Código de saída 2: Erro de bloqueio.
stderr
é enviado de volta para Claude processar automaticamente. Veja comportamento por evento de hook abaixo. - Outros códigos de saída: Erro não bloqueante.
stderr
é mostrado ao usuário e a execução continua.
Lembrete: Claude Code não vê stdout se o código de saída for 0, exceto para
o hook UserPromptSubmit
onde stdout é injetado como contexto.
Comportamento do Código de Saída 2
Evento do Hook | Comportamento |
---|---|
PreToolUse | Bloqueia a chamada da ferramenta, mostra stderr para Claude |
PostToolUse | Mostra stderr para Claude (ferramenta já executou) |
Notification | N/A, mostra stderr apenas para o usuário |
UserPromptSubmit | Bloqueia processamento do prompt, apaga prompt, mostra stderr apenas para o usuário |
Stop | Bloqueia parada, mostra stderr para Claude |
SubagentStop | Bloqueia parada, mostra stderr para subagente Claude |
PreCompact | N/A, mostra stderr apenas para o usuário |
Avançado: Saída JSON
Os hooks podem retornar JSON estruturado em stdout
para controle mais sofisticado:
Campos JSON Comuns
Todos os tipos de hook podem incluir estes campos opcionais:
Se continue
for false, Claude para de processar após os hooks executarem.
- Para
PreToolUse
, isso é diferente de"permissionDecision": "deny"
, que apenas bloqueia uma chamada de ferramenta específica e fornece feedback automático para Claude. - Para
PostToolUse
, isso é diferente de"decision": "block"
, que fornece feedback automatizado para Claude. - Para
UserPromptSubmit
, isso impede que o prompt seja processado. - Para
Stop
eSubagentStop
, isso tem precedência sobre qualquer saída"decision": "block"
. - Em todos os casos,
"continue" = false
tem precedência sobre qualquer saída"decision": "block"
.
stopReason
acompanha continue
com uma razão mostrada ao usuário, não mostrada
para Claude.
Controle de Decisão PreToolUse
Os hooks PreToolUse
podem controlar se uma chamada de ferramenta prossegue.
"allow"
ignora o sistema de permissão.permissionDecisionReason
é mostrado ao usuário mas não para Claude. (Valor"approve"
depreciado +reason
tem o mesmo comportamento.)"deny"
impede que a chamada da ferramenta execute.permissionDecisionReason
é mostrado para Claude. (Valor"block"
+reason
tem o mesmo comportamento.)"ask"
pede ao usuário para confirmar a chamada da ferramenta na UI.permissionDecisionReason
é mostrado ao usuário mas não para Claude.
Controle de Decisão PostToolUse
Os hooks PostToolUse
podem controlar se uma chamada de ferramenta prossegue.
"block"
automaticamente solicita Claude comreason
.undefined
não faz nada.reason
é ignorado.
Controle de Decisão UserPromptSubmit
Os hooks UserPromptSubmit
podem controlar se um prompt do usuário é processado.
"block"
impede que o prompt seja processado. O prompt submetido é apagado do contexto."reason"
é mostrado ao usuário mas não adicionado ao contexto.undefined
permite que o prompt prossiga normalmente."reason"
é ignorado."hookSpecificOutput.additionalContext"
adiciona a string ao contexto se não bloqueado.
Controle de Decisão Stop
/SubagentStop
Os hooks Stop
e SubagentStop
podem controlar se Claude deve continuar.
"block"
impede que Claude pare. Você deve preencherreason
para Claude saber como proceder.undefined
permite que Claude pare.reason
é ignorado.
Exemplo de Código de Saída: Validação de Comando Bash
Exemplo de Saída JSON: UserPromptSubmit para Adicionar Contexto e Validação
Para hooks UserPromptSubmit
, você pode injetar contexto usando qualquer método:
- Código de saída 0 com stdout: Claude vê o contexto (caso especial para
UserPromptSubmit
) - Saída JSON: Fornece mais controle sobre o comportamento
Exemplo de Saída JSON: PreToolUse com Aprovação
Trabalhando com Ferramentas MCP
Os hooks do Claude Code funcionam perfeitamente com ferramentas do Model Context Protocol (MCP). Quando servidores MCP fornecem ferramentas, elas aparecem com um padrão de nomenclatura especial que você pode corresponder em seus hooks.
Nomenclatura de Ferramentas MCP
As ferramentas MCP seguem o padrão mcp__<server>__<tool>
, por exemplo:
mcp__memory__create_entities
- Ferramenta de criar entidades do servidor de memóriamcp__filesystem__read_file
- Ferramenta de ler arquivo do servidor de sistema de arquivosmcp__github__search_repositories
- Ferramenta de busca do servidor GitHub
Configurando Hooks para Ferramentas MCP
Você pode direcionar ferramentas MCP específicas ou servidores MCP inteiros:
Exemplos
Para exemplos práticos incluindo formatação de código, notificações, e proteção de arquivos, veja Mais Exemplos no guia de início.
Considerações de Segurança
Aviso Legal
USE POR SUA PRÓPRIA CONTA E RISCO: Os hooks do Claude Code executam comandos shell arbitrários em seu sistema automaticamente. Ao usar hooks, você reconhece que:
- Você é o único responsável pelos comandos que configura
- Os hooks podem modificar, deletar, ou acessar qualquer arquivo que sua conta de usuário pode acessar
- Hooks maliciosos ou mal escritos podem causar perda de dados ou danos ao sistema
- Anthropic não fornece garantia e não assume responsabilidade por quaisquer danos resultantes do uso de hooks
- Você deve testar completamente os hooks em um ambiente seguro antes do uso em produção
Sempre revise e entenda quaisquer comandos de hook antes de adicioná-los à sua configuração.
Melhores Práticas de Segurança
Aqui estão algumas práticas chave para escrever hooks mais seguros:
- Validar e sanitizar entradas - Nunca confie cegamente nos dados de entrada
- Sempre aspear variáveis shell - Use
"$VAR"
não$VAR
- Bloquear travessia de caminho - Verifique por
..
em caminhos de arquivo - Usar caminhos absolutos - Especifique caminhos completos para scripts (use
$CLAUDE_PROJECT_DIR
para o caminho do projeto) - Pular arquivos sensíveis - Evite
.env
,.git/
, chaves, etc.
Segurança da Configuração
Edições diretas aos hooks em arquivos de configurações não tê efeito imediatamente. Claude Code:
- Captura um snapshot dos hooks na inicialização
- Usa este snapshot durante toda a sessão
- Avisa se hooks são modificados externamente
- Requer revisão no menu
/hooks
para que mudanças se apliquem
Isso impede que modificações maliciosas de hooks afetem sua sessão atual.
Detalhes de Execução de Hook
- Timeout: Limite de execução de 60 segundos por padrão, configurável por comando.
- Um timeout para um comando individual não afeta os outros comandos.
- Paralelização: Todos os hooks correspondentes executam em paralelo
- Ambiente: Executa no diretório atual com o ambiente do Claude Code
- A variável de ambiente
CLAUDE_PROJECT_DIR
está disponível e contém o caminho absoluto para o diretório raiz do projeto
- A variável de ambiente
- Entrada: JSON via stdin
- Saída:
- PreToolUse/PostToolUse/Stop: Progresso mostrado na transcrição (Ctrl-R)
- Notification: Logado apenas para debug (
--debug
)
Depuração
Solução de Problemas Básica
Se seus hooks não estão funcionando:
- Verificar configuração - Execute
/hooks
para ver se seu hook está registrado - Verificar sintaxe - Certifique-se de que suas configurações JSON são válidas
- Testar comandos - Execute comandos de hook manualmente primeiro
- Verificar permissões - Certifique-se de que scripts são executáveis
- Revisar logs - Use
claude --debug
para ver detalhes de execução de hook
Problemas comuns:
- Aspas não escapadas - Use
\"
dentro de strings JSON - Matcher errado - Verifique se nomes de ferramentas correspondem exatamente (sensível a maiúsculas e minúsculas)
- Comando não encontrado - Use caminhos completos para scripts
Depuração Avançada
Para problemas complexos de hook:
- Inspecionar execução de hook - Use
claude --debug
para ver execução detalhada de hook - Validar esquemas JSON - Teste entrada/saída de hook com ferramentas externas
- Verificar variáveis de ambiente - Verifique se o ambiente do Claude Code está correto
- Testar casos extremos - Tente hooks com caminhos de arquivo ou entradas incomuns
- Monitorar recursos do sistema - Verifique por esgotamento de recursos durante execução de hook
- Usar logging estruturado - Implemente logging em seus scripts de hook
Exemplo de Saída de Debug
Use claude --debug
para ver detalhes de execução de hook:
Mensagens de progresso aparecem no modo transcrição (Ctrl-R) mostrando:
- Qual hook está executando
- Comando sendo executado
- Status de sucesso/falha
- Mensagens de saída ou erro