Resumo Rápido: Os hooks do Claude Code são scripts de automação que executam em pontos específicos do ciclo de vida durante as sessões de codificação com IA, permitindo que os desenvolvedores executem comandos personalizados, validem ações, formate o código, enviem notificações e apliquem regras do projeto. Esses hooks integram-se ao fluxo de trabalho do Claude através de eventos como SessionStart, PreToolUse e PostToolUse, suportando padrões de execução baseados em comando, HTTP e prompt com tempos limite configuráveis e comportamento de código de saída.
O sistema de hooks do Claude Code transforma o assistente de codificação de IA de uma ferramenta útil em um ambiente de desenvolvimento totalmente automatizado. A maioria dos desenvolvedores não percebe a extensão do controle disponível através dos hooks.
A questão é que os hooks não servem apenas para executar scripts após edições de arquivos. Eles fornecem pontos de interceptação em todo o processo de tomada de decisão do Claude. Antes que ele execute um comando. Após uma chamada de ferramenta falhar. Quando ele precisa de permissão. Até mesmo antes de processar os prompts do usuário.
Este guia abrange tudo o que a documentação oficial fornece, mais padrões práticos que as discussões da comunidade revelam que realmente funcionam em ambientes de produção.
O que os Hooks do Claude Code Realmente Fazem
De acordo com a documentação oficial do Claude Code, os hooks são comandos de shell definidos pelo usuário, endpoints HTTP ou injeções de prompt que executam em pontos específicos do ciclo de vida do Claude Code. Eles recebem entrada JSON estruturada via stdin e controlam o fluxo de trabalho através de códigos de saída ou respostas HTTP.
A automação vai mais fundo do que a maioria dos guias sugere. Os hooks podem bloquear totalmente a execução de ferramentas, injetar contexto adicional no raciocínio do Claude, acionar serviços externos e impor regras de validação que o Claude deve respeitar.
Existem três tipos principais de hooks:
- Hooks de comando: Scripts de shell que se comunicam através de stdout, stderr e códigos de saída
- Hooks HTTP: Endpoints remotos que recebem requisições POST e retornam respostas JSON
- Hooks de prompt: Instruções dinâmicas injetadas no contexto do Claude em eventos específicos
Cada tipo serve a diferentes padrões de automação. Os hooks de comando lidam com validação e formatação local. Os hooks HTTP integram-se com serviços e bancos de dados externos. Os hooks de prompt modificam o comportamento do Claude sem processos externos.
Ciclo de Vida e Sistema de Eventos de Hooks
A documentação oficial define múltiplos eventos de hooks (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification e outros) que disparam durante o fluxo de execução do Claude Code. Entender quando cada um dispara determina que automação se torna possível.
| Evento | Quando Dispara | Pode Bloquear |
|---|---|---|
| SessionStart | Quando uma sessão começa ou é retomada | Não |
| UserPromptSubmit | Quando você envia um prompt, antes que o Claude o processe | Sim |
| PreToolUse | Antes que uma chamada de ferramenta seja executada | Sim |
| PermissionRequest | Quando uma caixa de diálogo de permissão aparece | Sim |
| PostToolUse | Após uma chamada de ferramenta ter sucesso | Não |
| PostToolUseFailure | Após uma chamada de ferramenta falhar | Não |
| Notification | Quando o Claude Code envia uma notificação | Não |
| SubmitMessage | Quando o Claude envia uma mensagem ao usuário | Não |
| ContextCompaction | Quando a janela de contexto se aproxima dos limites | Não |
A capacidade de bloqueio é o que mais importa. Hooks PreToolUse podem impedir operações perigosas antes que elas executem. Código de saída 1 bloqueia a ação. Código de saída 0 permite. Código de saída 2 pede ao Claude para reconsiderar.
Mas espere. Hooks PostToolUse não podem desfazer ações, pois a ferramenta já executou. Essa limitação molda como a lógica de validação é estruturada. Verificações críticas pertencem ao PreToolUse. Limpeza e formatação pertencem ao PostToolUse.
Navegue por Vantagens de Ferramentas de IA ao Configurar o Claude Code
Se você está trabalhando com hooks do Claude Code, também pode estar escolhendo outras ferramentas de IA em seu fluxo de trabalho. Get AI Perks coleta créditos iniciais e descontos de software para ferramentas de IA e nuvem em um só lugar. A plataforma inclui mais de 200 ofertas, com condições de vantagem e orientações de reivindicação para cada uma.
Procurando Vantagens de Claude ou Outras Ferramentas de IA?
Verifique Get AI Perks para:
- navegar por ofertas de Claude e outras ferramentas de IA
- comparar condições de vantagem antes de aplicar
- encontrar descontos iniciais em toda a sua pilha de ferramentas
👉 Visite Get AI Perks para explorar as vantagens atuais de software de IA.
Configuração e Estrutura de Arquivos
Os hooks são definidos no arquivo .claude/settings.json dentro de um projeto. O esquema de configuração suporta hooks globais e correspondentes específicos de ferramentas que filtram quando os hooks são executados.
Estrutura básica de hook de comando:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
A variável ${file} se expande para o caminho do arquivo real da entrada da ferramenta. De acordo com a documentação oficial, os hooks suportam essas expansões de variáveis nos campos de comando e argumentos.
Hierarquia de Localização de Hooks
O Claude Code verifica múltiplos locais para definições de hooks, com uma ordem de precedência clara:
- Nível do projeto: .claude/settings.json no espaço de trabalho atual
- Nível do usuário: ~/.claude/settings.json para todas as sessões
- Fornecido pelo plugin: Hooks incluídos em plugins instalados
Hooks de projeto substituem hooks de usuário para o mesmo evento. Isso permite regras de formatação específicas do projeto enquanto mantém manipuladores de notificação globais.
Padrões de Correspondência para Execução Seletiva
O sistema de correspondência filtra os hooks para ferramentas ou condições específicas. Sem correspondentes, os hooks disparam para cada ocorrência de seu evento.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
O campo pathPattern aceita sintaxe glob. O campo toolName corresponde às ferramentas integradas do Claude, como edit_file, execute_command, read_file e create_directory.
Discussões da comunidade revelam que combinações de correspondência funcionam com lógica E. Todos os correspondentes especificados devem corresponder para que o hook seja executado.
Hooks de Comando: Integração de Scripts Shell
Hooks de comando executam comandos ou scripts shell com entrada JSON estruturada. Eles representam o tipo de hook mais comum para automação local.
A documentação oficial especifica que hooks de comando recebem JSON via stdin com esta estrutura:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Scripts analisam essa entrada para tomar decisões. Um hook de validação Python pode parecer:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Não é possível editar arquivos protegidos”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Código de saída 0 permite a operação. Código de saída 1 a bloqueia e mostra a mensagem stderr para o Claude. Código de saída 2 ativa um comportamento especial dependendo do evento.
Comportamento do Código de Saída 2
De acordo com a documentação de referência oficial de hooks, o código de saída 2 tem significado específico para cada evento (PreToolUse: bloqueia e solicita reconsideração; UserPromptSubmit: fornece contexto sem bloquear; PermissionRequest: bloqueia permissão):
- PreToolUse: Bloqueia a ferramenta e solicita ao Claude que reconsidere com a mensagem stderr como contexto
- UserPromptSubmit: Fornece a saída stderr como contexto adicional sem bloquear
- PermissionRequest: Bloqueia a concessão de permissão
Isso cria um meio-termo entre bloqueio total e permissão. O Claude recebe feedback sobre por que a ação pode ser problemática e pode ajustar sua abordagem.
Hooks de Comando Assíncronos
A flag async: true executa os hooks em segundo plano sem bloquear o fluxo de trabalho do Claude. Isso é importante para operações lentas, como notificações de implantação ou coleta de métricas.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Quando um hook assíncrono é acionado, o Claude Code inicia o processo e continua imediatamente. O campo timeout define o tempo máximo de execução em segundos. Se não especificado, os hooks assíncronos usam um tempo limite padrão de 10 minutos.
Falando sério: hooks assíncronos não podem bloquear operações, pois eles rodam depois que o Claude prossegue. Eles funcionam para registro, notificações e limpeza — não para validação.
Hooks HTTP: Integração de Serviço Externo
Hooks HTTP enviam payloads JSON para endpoints remotos e analisam respostas para controle de decisão. Eles permitem a integração com serviços de validação, bancos de dados e ferramentas de terceiros.
Configuração básica de hook HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
A estrutura do payload corresponde à entrada do hook de comando, mas chega como corpo POST HTTP. A resposta determina a próxima ação do Claude.
Tratamento de Respostas HTTP
De acordo com a documentação oficial, hooks HTTP interpretam respostas com base no código de status e no conteúdo do corpo:
| Código de Status | Efeito | Origem da Mensagem |
|---|---|---|
| 200 | Permitir operação | Corpo da resposta (opcional) |
| 400 | Bloquear operação | Corpo da resposta mostrado ao Claude |
| 500 | Erro no hook, permitir operação | Registrado, mas não mostrado ao Claude |
| Outro | Permitir operação | Falha no hook não bloqueia o fluxo de trabalho |
O corpo da resposta pode incluir um campo de mensagem que o Claude vê como contexto. Isso permite que os serviços de validação expliquem por que uma operação foi bloqueada.
Interpolação de Variáveis de Ambiente
Hooks HTTP suportam a sintaxe ${VAR} em url, headers e outros campos de string. As variáveis se expandem do ambiente onde o Claude Code é executado.
De acordo com a documentação oficial do MCP, a expansão de variáveis de ambiente inclui uma sintaxe de fallback padrão: ${VAR:-default} se expande para VAR se definida, caso contrário, usa o valor padrão.
Restrição de segurança: de acordo com o problema do GitHub #28044, hooks HTTP só podem acessar variáveis de ambiente explicitamente listadas no campo de configuração allowedEnvVars. Isso evita a exposição acidental de credenciais.
Hooks de Prompt: Injeção de Contexto
Hooks de prompt injetam instruções dinâmicas no contexto do Claude em eventos específicos. Eles modificam o comportamento sem processos externos ou chamadas de API.
| { “event”: “SessionStart”, “prompt”: “Você está trabalhando em um projeto TypeScript. Sempre use verificações estritas de nulos e prefira async/await em vez de promises.” } |
O texto injetado se torna parte das instruções do sistema do Claude para aquela sessão. Hooks de prompt também podem usar variáveis de template que se expandem com base nos dados do evento.
Geração Dinâmica de Prompt
De acordo com a documentação oficial, hooks de prompt suportam campos de comando que geram prompts dinâmicos:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
O comando recebe a entrada JSON padrão via stdin e exibe o texto do prompt via stdout. Isso permite a geração de instruções conscientes do contexto com base no estado do projeto.
Hooks Baseados em Agentes
Hooks de agente especificam um subagente que lida com o evento em vez de injeção direta de prompt. O subagente recebe contexto sobre o evento e pode realizar raciocínio em várias etapas.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Uma chamada de ferramenta falhou. Analise o erro e sugira correções.” } |
O subagente nomeado deve ser definido na configuração do projeto. Hooks de agente permitem lógica de decisão complexa que a injeção simples de prompt não pode fornecer.
Padrões Práticos de Hooks
Discussões da comunidade e exemplos oficiais revelam padrões de automação específicos que funcionam de forma confiável em produção.
Formatar Código Automaticamente Após Edições
O padrão mais comum formata o código automaticamente após o Claude editar arquivos:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
A variável ${toolInput.path} se expande para o caminho do arquivo editado. PostToolUse garante que a formatação ocorra após edições bem-sucedidas, mas não bloqueia o fluxo de trabalho do Claude.
Bloquear Modificações de Arquivos Protegidos
Hooks PreToolUse impõem regras de proteção de arquivos:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
O script valida o caminho de destino contra padrões protegidos e sai com o código 1 para bloquear edições proibidas.
Ser Notificado Quando o Claude Precisa de Entrada
De acordo com o guia oficial de fluxo de trabalho, os hooks de Notificação podem disparar alertas de desktop ou enviar mensagens para serviços externos:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Isso dispara sempre que o Claude Code envia uma notificação, incluindo quando espera por entrada do usuário ou após a conclusão de uma tarefa.
Reinjectar Contexto Após Compactação
Hooks de ContextCompaction restauram contexto importante quando a janela de conversação enche:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
A saída do comando é injetada de volta no contexto do Claude após a compactação remover mensagens mais antigas. Isso evita a perda de instruções críticas específicas do projeto.
Auditar Mudanças de Configuração
Acompanhe quando o Claude modifica arquivos de configuração:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
A execução assíncrona evita que o Claude seja bloqueado enquanto as operações do git são concluídas. Isso cria uma trilha de auditoria de mudanças de configuração sem staging manual.
Saída JSON e Controle de Decisão
Hooks de comando podem produzir JSON estruturado para fornecer feedback detalhado além de códigos de saída simples. De acordo com a referência oficial, a saída JSON permite respostas de múltiplos campos que o Claude interpreta para tomada de decisão.
| { “allowed”: false, “message”: “Este arquivo é protegido pela política da equipe”, “suggestion”: “Crie um novo arquivo em src/features/ em vez disso” } |
O campo allowed controla se a operação prossegue. A mensagem aparece para o Claude como contexto. O campo suggestion fornece abordagens alternativas.
Para que os hooks produzam JSON, eles devem:
- Escrever JSON válido para stdout
- Sair com código 0 (para permitido) ou 1 (para bloqueado)
- Incluir no mínimo o campo booleano allowed
O Claude Code analisa o JSON e o usa para aprimorar o loop de feedback. Os códigos de saída ainda determinam a decisão principal, mas o JSON fornece contexto mais rico.
Referência de Campos de Entrada de Hooks
Todos os hooks recebem um objeto JSON via stdin com campos comuns mais dados específicos do evento. Entender o esquema completo permite uma lógica de hook mais sofisticada.
Campos de Entrada Comuns
Cada hook recebe estes campos base:
- event: O nome do evento do hook (ex: “PreToolUse”)
- sessionId: Identificador único para a sessão atual do Claude
- turnId: Identificador para o turno de conversação atual
- timestamp: Carimbo de data/hora ISO 8601 quando o evento disparou
Campos de Evento de Ferramenta
Eventos PreToolUse, PostToolUse e PostToolUseFailure incluem:
- toolName: Nome da ferramenta que está sendo invocada (edit_file, execute_command, etc.)
- toolInput: Objeto contendo os parâmetros de entrada da ferramenta
- toolResponse: Dados de saída da ferramenta (apenas PostToolUse)
- error: Detalhes do erro, incluindo mensagem e código (apenas PostToolUseFailure)
A estrutura toolInput varia de acordo com a ferramenta. Para edit_file, contém path e content. Para execute_command, contém command e args.
Campos de Evento de Permissão
Eventos PermissionRequest incluem:
- permissionType: Tipo de permissão solicitada (file_write, command_execute, etc.)
- requestedAction: Ação específica que requer permissão
- resourcePath: Caminho do arquivo ou identificador de recurso afetado
Hooks de Ferramenta MCP
De acordo com a referência oficial de hooks, os hooks podem corresponder a ferramentas do Model Context Protocol (MCP) usando o campo de correspondência mcpTool. Isso permite a execução de hooks quando o Claude usa ferramentas externas fornecidas por servidores MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
O valor mcpTool corresponde ao nome da ferramenta no formato nome-servidor/nome-ferramenta. Isso permite a lógica de validação para consultas de banco de dados, chamadas de API ou outras operações externas.
Solicitações de recursos do GitHub indicam interesse crescente em uma integração mais profunda do MCP, incluindo hooks que podem inspecionar notificações do servidor MCP e responder a eventos externos.
Considerações de Segurança
Os hooks executam com as mesmas permissões que o próprio Claude Code. Isso cria implicações de segurança para ambientes multiusuário e configurações compartilhadas.
Sandbox de Execução de Comando
De acordo com o problema do GitHub #28044, hooks HTTP são roteados através de um proxy sandbox que restringe o acesso à rede e filtra variáveis de ambiente. Hooks de comando não têm restrições — eles rodam com acesso total ao shell.
A documentação recomenda estas práticas:
- Nunca armazene credenciais em comandos de hook
- Use variáveis de ambiente para dados sensíveis
- Valide toda entrada de expansões ${…}
- Implemente limites de tempo para serviços externos
- Use hooks assíncronos para operações não críticas para evitar bloqueios em falhas
Isolamento de Execução de Hook
Hooks de nível de usuário em ~/.claude/settings.json se aplicam a todos os projetos. Isso cria riscos ao trabalhar em diferentes limites de confiança. Hooks de nível de projeto substituem hooks de usuário, mas não podem desativá-los completamente.
O menu /hooks no Claude Code mostra todos os hooks ativos para a sessão atual. Revisar esta lista antes de trabalhar em projetos sensíveis ajuda a identificar potenciais preocupações de segurança.
Depuração e Solução de Problemas
Falhas de hook nem sempre aparecem claramente na conversa do Claude. A documentação oficial fornece várias abordagens de depuração.
Logs de Execução de Hooks
O Claude Code registra a execução de hooks na saída de depuração da sessão. De acordo com o guia de solução de problemas, habilitar o registro de depuração revela:
- Quais hooks corresponderam a cada evento
- A entrada JSON enviada para cada hook
- Saída stdout e stderr dos processos de hook
- Códigos de saída e tempo de execução
- Códigos de status e corpos de resposta HTTP para hooks HTTP
Habilite o registro de depuração definindo CLAUDE_DEBUG=1 no ambiente antes de iniciar o Claude Code.
Testando Hooks Independentemente
Hooks de comando podem ser testados fora do Claude Code construindo manualmente a entrada JSON:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Isso valida a lógica do hook sem acionar operações reais do Claude. O código de saída e a saída stdout/stderr devem corresponder ao comportamento esperado.
Falhas Comuns de Hook
Discussões da comunidade identificam esses problemas frequentes:
- Erros de tempo limite: Tempo limite padrão de 10 minutos muito curto para operações lentas — aumente com o campo timeout
- Falhas de expansão de caminho: Variáveis como ${file} indefinidas para eventos que não incluem contexto de arquivo
- Erros de permissão: Scripts de hook sem permissões de execução — execute chmod +x script.sh
- Erros de análise JSON: Saída JSON malformada dos hooks — valide com jq antes de retornar
- Indisponibilidade de variáveis de ambiente: Variáveis não propagadas para o processo de hook — verifique o ambiente do Claude Code
Implicações de Desempenho de Hooks
Hooks síncronos bloqueiam o fluxo de trabalho do Claude até a conclusão. O tempo limite padrão de 10 minutos impede travamentos indefinidos, mas mesmo pequenos atrasos se acumulam em várias operações.
Profissionais relatam que hooks de validação simples têm impacto de desempenho insignificante. Hooks de formatação de arquivos causam impacto de desempenho perceptível, mas aceitável. Chamadas de API externas podem criar atrito no fluxo de trabalho. Operações de computação pesada se beneficiam da execução assíncrona.
Loteamento de Hooks
Vários hooks podem corresponder ao mesmo evento. De acordo com a documentação de referência, os hooks executam sequencialmente na ordem de definição. Se algum hook bloquear a operação, os hooks restantes não serão executados.
Isso é importante para o desempenho. Cinco hooks síncronos a 200ms cada adicionam um segundo por evento. Combinar validações relacionadas em um único hook reduz a sobrecarga.
Padrões Avançados
Além da automação básica, os hooks permitem a personalização sofisticada do fluxo de trabalho.
Cadeias de Hooks com Estado
Os hooks podem manter estado entre execuções usando arquivos ou bancos de dados. Um hook PostToolUse pode registrar operações bem-sucedidas que um hook PreToolUse posteriormente valida:
| #!/bin/bash # Registrar edições bem-sucedidas echo “${toolInput.path}” >> .claude/edit-history.txt |
Um hook PreToolUse complementar poderia verificar este histórico para evitar operações redundantes ou impor restrições de ordem.
Ativação Condicional de Hook
Variáveis de ambiente controlam o comportamento do hook em tempo de execução. Definir CLAUDE_SKIP_HOOKS=1 desativa os hooks para situações de emergência.
Os próprios hooks podem verificar flags de ambiente:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Aplicar validação estrita exit 1 fi exit 0 |
Isso permite comportamento em modo de desenvolvimento versus modo de produção sem alterações de configuração.
Validação em Múltiplas Etapas
Hooks PreToolUse podem implementar validação em vários níveis onde o código de saída 2 permite que o Claude prossiga com avisos:
- Falhas graves (saída 1): Bloquear operações perigosas
- Avisos suaves (saída 2): Alertar o Claude para reconsiderar
- Passar com contexto (saída 0 + JSON): Fornecer informações adicionais
Isso cria um espectro de validação mais sutil do que binário permitir/negar.
Integração com CI/CD
De acordo com a documentação oficial de integração de plataforma, o Claude Code é executado em ambientes CI/CD para revisão automatizada de código e triagem de problemas. Os hooks estendem essa automação.
Fluxos de trabalho do GitHub Actions podem definir hooks que aplicam políticas de equipe durante sessões automatizadas:
| -- name: Executar Claude Code com hooks estritos env: STRICT_MODE: 1 run: | claude “Revise este PR e sugira melhorias” |
A flag STRICT_MODE ativa a lógica de validação condicional em scripts de hook. Isso garante que sessões automatizadas sigam regras mais rígidas do que o desenvolvimento interativo.
Geração de Trilha de Auditoria
Hooks PostToolUse em ambientes de CI criam logs de auditoria detalhados de todas as operações do Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
O registro em segundo plano não afeta o desempenho, mas fornece um histórico completo de operações para conformidade e depuração.
O Menu /hooks
O Claude Code fornece um comando /hooks que exibe todos os hooks ativos para a sessão atual. De acordo com a documentação oficial, este menu mostra:
- Tipo de evento do hook
- Padrões de correspondência
- Comando ou endpoint de URL
- Se o hook roda de forma assíncrona
- Fonte da configuração (projeto, usuário ou plugin)
Selecionar um hook mostra sua configuração completa e permite desativá-lo temporariamente para a sessão atual.
Desativar ou Remover Hooks
Os hooks podem ser desativados sem remover a configuração adicionando “enabled”: false à definição do hook. Isso preserva a configuração enquanto impede a execução.
Para remover permanentemente um hook, exclua sua entrada do arquivo settings.json apropriado. As alterações entram em vigor na próxima reinicialização da sessão ou ao executar /reload.
Hooks em Skills e Agentes
De acordo com a documentação oficial, hooks definidos dentro de configurações de skill ou subagente se aplicam apenas quando essa skill ou agente é executado. Isso permite automação especializada para fluxos de trabalho específicos.
Um subagente de depuração pode incluir hooks que registram todas as chamadas de ferramenta:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Esses hooks só disparam durante sessões do agente de depuração, não durante a operação normal do Claude Code.
Referenciar Scripts por Caminho
Comandos de hook suportam caminhos relativos e absolutos. Caminhos relativos são resolvidos a partir da raiz do projeto onde o Claude Code é executado.
Melhores práticas de discussões da comunidade:
- Armazene scripts de hook no diretório .claude/hooks/
- Use nomes descritivos: validate-typescript.sh em vez de hook1.sh
- Torne os scripts executáveis: chmod +x .claude/hooks/*.sh
- Inclua linha shebang: #!/usr/bin/env bash ou #!/usr/bin/env python3
- Adicione tratamento de erro com set -e em scripts bash
Capacidades Futuras de Hooks
Solicitações de recursos do GitHub revelam aprimoramentos de hooks planejados e solicitados:
- Hooks de script inline: Defina a lógica do hook diretamente em settings.json sem arquivos externos
- Integração de ferramentas MCP: Invoque ferramentas de servidor MCP a partir de hooks em vez de comandos shell
- Colaboração multiagente: Hooks que coordenam entre instâncias do Claude em máquinas diferentes
- Tipagem aprimorada: Definições de tipo TypeScript para esquemas de entrada/saída de hook
De acordo com o problema do GitHub #4274, a solicitação por tipos de hook integrados (ferramenta MCP, script inline, chamada de API) visa simplificar a configuração e melhorar a experiência do desenvolvedor.
Perguntas Frequentes
Os hooks podem impedir que o Claude execute comandos perigosos?
Sim. Hooks PreToolUse podem bloquear qualquer execução de ferramenta saindo com o código 1. Isso inclui edições de arquivos, execução de comandos e chamadas de ferramentas MCP. O hook recebe a entrada completa da ferramenta e pode validar contra qualquer critério antes de permitir a operação.
Como depurar um hook que não está funcionando?
Habilite o registro de depuração com CLAUDE_DEBUG=1 antes de iniciar o Claude Code. Verifique os logs da sessão para detalhes de execução de hook, incluindo quais hooks corresponderam, a entrada JSON enviada, saída stdout/stderr e códigos de saída. Teste hooks independentemente enviando JSON de exemplo para o script do hook.
Os hooks funcionam com todas as plataformas do Claude Code?
Hooks funcionam no CLI, aplicativo desktop e extensão VS Code. De acordo com a documentação oficial, hooks executam onde quer que o Claude Code seja executado com acesso ao sistema de arquivos. Claude baseado em navegador e aplicativos móveis não suportam hooks devido a restrições de sandbox.
Os hooks podem modificar as respostas ou o comportamento do Claude?
Hooks de prompt injetam instruções que influenciam o comportamento do Claude. Hooks de agente delegam o tratamento de eventos a subagentes especializados. No entanto, hooks não podem modificar diretamente o texto gerado ou o processo de raciocínio do Claude — eles funcionam fornecendo contexto e bloqueando operações.
Qual é a diferença entre hooks assíncronos e síncronos?
Hooks síncronos bloqueiam o fluxo de trabalho do Claude até a conclusão ou tempo limite. Hooks assíncronos rodam em segundo plano sem bloquear. Hooks síncronos podem impedir operações através de códigos de saída. Hooks assíncronos não podem bloquear, pois o Claude continua antes que o hook seja concluído. Use assíncronos para registro e notificações, síncronos para validação.
Como compartilhar hooks com uma equipe?
Envie o arquivo .claude/settings.json para controle de versão. Hooks de nível de projeto se aplicam a todos os membros da equipe que clonam o repositório. Para políticas de toda a organização, as equipes podem manter um arquivo de configurações compartilhado de nível de usuário que os membros copiam para ~/.claude/settings.json.
Hooks HTTP podem chamar APIs internas atrás de firewalls?
Sim, se o Claude Code for executado em um ambiente com acesso de rede a essas APIs. Hooks HTTP fazem requisições POST padrão da máquina que executa o Claude Code. Firewalls corporativas e VPNs se aplicam normalmente. O proxy sandbox mencionado na documentação controla a exposição de variáveis de ambiente, não o roteamento de rede.
Os hooks aumentam o uso de tokens do Claude Code?
Hooks de prompt injetam texto no contexto do Claude, o que consome tokens. Hooks de comando e HTTP não afetam diretamente o uso de tokens, mas sua saída (mensagens de erro, sugestões) se torna parte do contexto da conversa. Código de saída 2 com mensagens explicativas adiciona mais contexto do que código de saída 1 com bloqueio simples.
Conclusão
Os hooks do Claude Code transformam o assistente de IA de uma ferramenta poderosa em uma plataforma de desenvolvimento totalmente automatizada. O sistema de eventos fornece pontos de interceptação ao longo do fluxo de trabalho do Claude — desde a inicialização da sessão até a compactação de contexto.
Hooks de comando lidam com validação e formatação local. Hooks HTTP integram serviços e bancos de dados externos. Hooks de prompt modificam o comportamento através da injeção de contexto. Juntos, eles permitem padrões de automação que aplicam políticas de equipe, mantêm a qualidade do código e integram-se à infraestrutura de desenvolvimento existente.
O sistema de correspondência filtra hooks para ferramentas e padrões de arquivos específicos. Códigos de saída e saída JSON controlam o fluxo de decisão. A execução assíncrona evita bloqueios em operações lentas. O esquema de configuração completo suporta tudo, desde formatação automática simples até validação complexa em várias etapas.
Comece com hooks PostToolUse básicos para formatação de código. Adicione validação PreToolUse conforme as políticas surgirem. Experimente hooks de prompt para modificação de comportamento. Crie integrações HTTP para aplicação em toda a equipe.
Verifique a documentação oficial do Claude Code para a referência completa de hooks e o esquema de configuração atualizado à medida que novas funcionalidades forem lançadas.
