Referência de Hooks

​

Configuração

• ~/.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 confirmadas)
• Configurações de política gerenciada pela empresa

​

Estrutura

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

• matcher: Padrão para corresponder nomes de ferramentas, sensível a maiúsculas e minúsculas (aplicável apenas para PreToolUse e PostToolUse)
  • Strings simples correspondem exatamente: Write corresponde apenas à ferramenta Write
  • Suporta regex: Edit|Write ou Notebook.*
  • Use * para corresponder todas as ferramentas. Você também pode usar uma string vazia ("") ou deixar matcher em branco.
• hooks: Array de hooks a executar quando o padrão corresponder
  • type: Tipo de execução do hook - "command" para comandos bash ou "prompt" para avaliação baseada em LLM
  • command: (Para type: "command") O comando bash a executar (pode usar a variável de ambiente $CLAUDE_PROJECT_DIR)
  • prompt: (Para type: "prompt") O prompt a enviar para o LLM para avaliação
  • timeout: (Opcional) Quanto tempo um hook deve executar, em segundos, antes de cancelar esse hook específico

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

​

Scripts de Hook Específicos do Projeto

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

​

Hooks de plugin

• Os hooks de plugin são definidos no arquivo hooks/hooks.json do plugin ou em um arquivo fornecido por um caminho personalizado para o campo hooks.
• Quando um plugin é habilitado, seus hooks são mesclados com hooks de usuário e projeto
• Vários hooks de diferentes fontes podem responder ao mesmo evento
• Os hooks de plugin usam a variável de ambiente ${CLAUDE_PLUGIN_ROOT} para referenciar arquivos de plugin

{
  "description": "Formatação automática de código",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

• ${CLAUDE_PLUGIN_ROOT}: Caminho absoluto para o diretório do plugin
• ${CLAUDE_PROJECT_DIR}: Diretório raiz do projeto (igual ao dos hooks do projeto)
• Todas as variáveis de ambiente padrão estão disponíveis

​

Hooks Baseados em Prompt

​

Como funcionam os hooks baseados em prompt

1. Enviam a entrada do hook e seu prompt para um LLM rápido (Haiku)
2. O LLM responde com JSON estruturado contendo uma decisão
3. Claude Code processa a decisão automaticamente

​

Configuração

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Avalie se Claude deve parar: $ARGUMENTS. Verifique se todas as tarefas estão completas."
          }
        ]
      }
    ]
  }
}

• type: Deve ser "prompt"
• prompt: O texto do prompt a enviar para o LLM
  • Use $ARGUMENTS como um placeholder para o JSON de entrada do hook
  • Se $ARGUMENTS não estiver presente, o JSON de entrada é anexado ao prompt
• timeout: (Opcional) Timeout em segundos (padrão: 30 segundos)

​

Esquema de resposta

{
  "decision": "approve" | "block",
  "reason": "Explicação para a decisão",
  "continue": false,  // Opcional: para Claude inteiramente
  "stopReason": "Mensagem mostrada ao usuário",  // Opcional: mensagem de parada personalizada
  "systemMessage": "Aviso ou contexto"  // Opcional: mostrado ao usuário
}

• decision: "approve" permite a ação, "block" a previne
• reason: Explicação mostrada a Claude quando a decisão é "block"
• continue: (Opcional) Se false, para a execução do Claude inteiramente
• stopReason: (Opcional) Mensagem mostrada quando continue é false
• systemMessage: (Opcional) Mensagem adicional mostrada ao usuário

​

Eventos de hook suportados

• Stop: Decidir inteligentemente se Claude deve continuar trabalhando
• SubagentStop: Avaliar se um subagente completou sua tarefa
• UserPromptSubmit: Validar prompts do usuário com assistência de LLM
• PreToolUse: Tomar decisões de permissão conscientes do contexto

​

Exemplo: Hook Stop inteligente

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Você está avaliando se Claude deve parar de trabalhar. Contexto: $ARGUMENTS\n\nAnalise a conversa e determine se:\n1. Todas as tarefas solicitadas pelo usuário estão completas\n2. Há erros que precisam ser resolvidos\n3. Trabalho de acompanhamento é necessário\n\nResponda com JSON: {\"decision\": \"approve\" ou \"block\", \"reason\": \"sua explicação\"}",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

​

Exemplo: SubagentStop com lógica personalizada

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Avalie se este subagente deve parar. Entrada: $ARGUMENTS\n\nVerifique se:\n- O subagente completou sua tarefa atribuída\n- Ocorreram erros que precisam ser corrigidos\n- É necessária coleta de contexto adicional\n\nRetorne: {\"decision\": \"approve\" ou \"block\", \"reason\": \"explicação\"}"
          }
        ]
      }
    ]
  }
}

​

Comparação com hooks de comando bash

​

Melhores práticas

• Seja específico em prompts: Declare claramente o que você quer que o LLM avalie
• Inclua critérios de decisão: Liste os fatores que o LLM deve considerar
• Teste seus prompts: Verifique se o LLM toma decisões corretas para seus casos de uso
• Defina timeouts apropriados: O padrão é 30 segundos, ajuste se necessário
• Use para decisões complexas: Hooks bash são melhores para regras simples e determinísticas

​

Eventos de Hook

​

PreToolUse

• Task - Tarefas de subagente (consulte documentação de subagentes)
• Bash - Comandos de shell
• Glob - Correspondência de padrão de arquivo
• Grep - Busca de conteúdo
• Read - Leitura de arquivo
• Edit - Edição de arquivo
• Write - Escrita de arquivo
• WebFetch, WebSearch - Operações web

​

PostToolUse

​

Notification

1. Claude precisa de sua permissão para usar uma ferramenta. Exemplo: “Claude precisa de sua permissão para usar Bash”
2. A entrada do prompt ficou ociosa por pelo menos 60 segundos. “Claude está aguardando sua entrada”

​

UserPromptSubmit

​

Stop

​

SubagentStop

​

PreCompact

• manual - Invocado de /compact
• auto - Invocado de auto-compact (devido à janela de contexto cheia)

​

SessionStart

• startup - Invocado na inicialização
• resume - Invocado de --resume, --continue ou /resume
• clear - Invocado de /clear
• compact - Invocado de compactação automática ou manual.

​

Persistindo variáveis de ambiente

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Execute seus comandos de configuração que modificam o ambiente
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

​

SessionEnd

• clear - Sessão limpa com comando /clear
• logout - Usuário fez logout
• prompt_input_exit - Usuário saiu enquanto a entrada de prompt estava visível
• other - Outros motivos de saída

​

Entrada de Hook

{
  // Campos comuns
  session_id: string
  transcript_path: string  // Caminho para JSON de conversa
  cwd: string              // O diretório de trabalho atual quando o hook é invocado
  permission_mode: string  // Modo de permissão atual: "default", "plan", "acceptEdits" ou "bypassPermissions"

  // Campos específicos do evento
  hook_event_name: string
  ...
}

​

Entrada PreToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

​

Entrada PostToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

​

Entrada Notification

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

​

Entrada UserPromptSubmit

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

​

Entrada Stop e SubagentStop

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

​

Entrada PreCompact

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

​

Entrada SessionStart

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

​

Entrada SessionEnd

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

​

Saída de Hook

​

Simples: Código de Saída

• Código de saída 0: Sucesso. stdout é mostrado ao usuário no modo de transcrição (CTRL-R), exceto para UserPromptSubmit e SessionStart, onde stdout é adicionado ao contexto.
• Código de saída 2: Erro de bloqueio. stderr é alimentado de volta a Claude para processar automaticamente. Consulte o comportamento específico do evento de hook abaixo.
• Outros códigos de saída: Erro não bloqueador. stderr é mostrado ao usuário e a execução continua.

​

Comportamento do Código de Saída 2

​

Avançado: Saída JSON

​

Campos JSON Comuns

{
  "continue": true, // Se Claude deve continuar após execução do hook (padrão: true)
  "stopReason": "string", // Mensagem mostrada quando continue é false

  "suppressOutput": true, // Ocultar stdout do modo de transcrição (padrão: false)
  "systemMessage": "string" // Mensagem de aviso opcional mostrada ao usuário
}

• Para PreToolUse, isso é diferente de "permissionDecision": "deny", que apenas bloqueia uma chamada de ferramenta específica e fornece feedback automático a Claude.
• Para PostToolUse, isso é diferente de "decision": "block", que fornece feedback automatizado a Claude.
• Para UserPromptSubmit, isso impede que o prompt seja processado.
• Para Stop e SubagentStop, 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".

​

Controle de Decisão PreToolUse

• "allow" ignora o sistema de permissão. permissionDecisionReason é mostrado ao usuário mas não a Claude.
• "deny" impede que a chamada de ferramenta seja executada. permissionDecisionReason é mostrado a Claude.
• "ask" pede ao usuário para confirmar a chamada de ferramenta na UI. permissionDecisionReason é mostrado ao usuário mas não a Claude.

• updatedInput permite que você modifique os parâmetros de entrada da ferramenta antes que a ferramenta seja executada. Este é um objeto Record<string, unknown> contendo os campos que você deseja alterar ou adicionar.
• Isso é mais útil com "permissionDecision": "allow" para modificar e aprovar chamadas de ferramenta.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow"
    "permissionDecisionReason": "Meu motivo aqui",
    "updatedInput": {
      "field_to_modify": "novo valor"
    }
  }
}

​

Controle de Decisão PostToolUse

• "block" solicita automaticamente a Claude com reason.
• undefined não faz nada. reason é ignorado.
• "hookSpecificOutput.additionalContext" adiciona contexto para Claude considerar.

{
  "decision": "block" | undefined,
  "reason": "Explicação para a decisão",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Informação adicional para Claude"
  }
}

​

Controle de Decisão UserPromptSubmit

• "block" impede que o prompt seja processado. O prompt enviado é 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.

{
  "decision": "block" | undefined,
  "reason": "Explicação para a decisão",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Meu contexto adicional aqui"
  }
}

​

Controle de Decisão Stop/SubagentStop

• "block" impede que Claude pare. Você deve preencher reason para que Claude saiba como proceder.
• undefined permite que Claude pare. reason é ignorado.

{
  "decision": "block" | undefined,
  "reason": "Deve ser fornecido quando Claude é impedido de parar"
}

​

Controle de Decisão SessionStart

• "hookSpecificOutput.additionalContext" adiciona a string ao contexto.
• Os valores additionalContext de vários hooks são concatenados.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Meu contexto adicional aqui"
  }
}

​

Controle de Decisão SessionEnd

​

Exemplo de Código de Saída: Validação de Comando Bash

#!/usr/bin/env python3
import json
import re
import sys

# Defina regras de validação como uma lista de tuplas (padrão regex, mensagem)
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) em vez de 'grep' para melhor desempenho e recursos",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' ou 'rg --files -g pattern' em vez de 'find -name' para melhor desempenho",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Erro: Entrada JSON inválida: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# Valide o comando
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Código de saída 2 bloqueia chamada de ferramenta e mostra stderr a Claude
    sys.exit(2)

​

Exemplo de Saída JSON: UserPromptSubmit para Adicionar Contexto e Validação

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# Carregue entrada de stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Erro: Entrada JSON inválida: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Verifique padrões sensíveis
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contém possíveis segredos"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Use saída JSON para bloquear com um motivo específico
        output = {
            "decision": "block",
            "reason": f"Violação de política de segurança: {message}. Por favor, reformule sua solicitação sem informações sensíveis."
        }
        print(json.dumps(output))
        sys.exit(0)

# Adicione hora atual ao contexto
context = f"Hora atual: {datetime.datetime.now()}"
print(context)

"""
O seguinte também é equivalente:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Permita que o prompt prossiga com o contexto adicional
sys.exit(0)

​

Exemplo de Saída JSON: PreToolUse com Aprovação

#!/usr/bin/env python3
import json
import sys

# Carregue entrada de stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Erro: Entrada JSON inválida: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Exemplo: Auto-aprovar leituras de arquivo para arquivos de documentação
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Use saída JSON para auto-aprovar a chamada de ferramenta
        output = {
            "decision": "approve",
            "reason": "Arquivo de documentação auto-aprovado",
            "suppressOutput": True  # Não mostrar no modo de transcrição
        }
        print(json.dumps(output))
        sys.exit(0)

# Para outros casos, deixe o fluxo de permissão normal prosseguir
sys.exit(0)

​

Trabalhando com Ferramentas MCP

​

Nomenclatura de Ferramentas MCP

• mcp__memory__create_entities - Ferramenta criar entidades do servidor Memory
• mcp__filesystem__read_file - Ferramenta ler arquivo do servidor Filesystem
• mcp__github__search_repositories - Ferramenta buscar repositórios do servidor GitHub

​

Configurando Hooks para Ferramentas MCP

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Operação de memória iniciada' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

​

Exemplos

​

Considerações de Segurança

​

Aviso Legal

• Você é o único responsável pelos comandos que configura
• Os hooks podem modificar, deletar ou acessar qualquer arquivo que sua conta de usuário possa 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 danos resultantes do uso de hooks
• Você deve testar completamente os hooks em um ambiente seguro antes do uso em produção

​

Melhores Práticas de Segurança

1. Valide e sanitize entradas - Nunca confie cegamente em dados de entrada
2. Sempre cite variáveis de shell - Use "$VAR" não $VAR
3. Bloqueie travessia de caminho - Verifique .. em caminhos de arquivo
4. Use caminhos absolutos - Especifique caminhos completos para scripts (use “$CLAUDE_PROJECT_DIR” para o caminho do projeto)
5. Pule arquivos sensíveis - Evite .env, .git/, chaves, etc.

​

Segurança de Configuração

1. Captura um snapshot de hooks na inicialização
2. Usa este snapshot durante toda a sessão
3. Avisa se hooks forem modificados externamente
4. Requer revisão no menu /hooks para que mudanças sejam aplicadas

​

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 são executados em paralelo
• Deduplicação: Múltiplos comandos de hook idênticos são automaticamente deduplicated
• 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 (onde Claude Code foi iniciado)
  • A variável de ambiente CLAUDE_CODE_REMOTE indica se o hook está sendo executado em um ambiente remoto (web) ("true") ou ambiente CLI local (não definido ou vazio). Use isso para executar lógica diferente com base no contexto de execução.
• Entrada: JSON via stdin
• Saída:
  • PreToolUse/PostToolUse/Stop/SubagentStop: Progresso mostrado em transcrição (Ctrl-R)
  • Notification/SessionEnd: Registrado apenas em debug (--debug)
  • UserPromptSubmit/SessionStart: stdout adicionado como contexto para Claude

​

Depuração

​

Solução de Problemas Básica

1. Verifique configuração - Execute /hooks para ver se seu hook está registrado
2. Verifique sintaxe - Certifique-se de que suas configurações JSON são válidas
3. Teste comandos - Execute comandos de hook manualmente primeiro
4. Verifique permissões - Certifique-se de que scripts são executáveis
5. Revise logs - Use claude --debug para ver detalhes de execução de hook

• 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

1. Inspecione execução de hook - Use claude --debug para ver execução detalhada de hook
2. Valide esquemas JSON - Teste entrada/saída de hook com ferramentas externas
3. Verifique variáveis de ambiente - Verifique se o ambiente do Claude Code está correto
4. Teste casos extremos - Tente hooks com caminhos de arquivo ou entradas incomuns
5. Monitore recursos do sistema - Verifique esgotamento de recursos durante execução de hook
6. Use logging estruturado - Implemente logging em seus scripts de hook

​

Exemplo de Saída de Debug

[DEBUG] Executando hooks para PostToolUse:Write
[DEBUG] Obtendo comandos de hook correspondentes para PostToolUse com query: Write
[DEBUG] Encontrados 1 matchers de hook em configurações
[DEBUG] Correspondidos 1 hooks para query "Write"
[DEBUG] Encontrados 1 comandos de hook a executar
[DEBUG] Executando comando de hook: <Your command> com timeout 60000ms
[DEBUG] Comando de hook completado com status 0: <Your stdout>

• Qual hook está sendo executado
• Comando sendo executado
• Status de sucesso/falha
• Mensagens de saída ou erro