Referência de Hooks - Claude Docs

Para um guia de início rápido com exemplos, consulte Comece com hooks do Claude Code.

Configuração

Os hooks do Claude Code são configurados em seus arquivos de 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

Os hooks são organizados por matchers, onde cada matcher pode ter vários hooks:

{
  "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 a todas as ferramentas. Você também pode usar string vazia ("") ou deixar matcher em branco.
hooks: Array de comandos a executar quando o padrão corresponde
- type: Atualmente apenas "command" é suportado
- command: O comando bash a executar (pode usar a variável de ambiente $CLAUDE_PROJECT_DIR)
- timeout: (Opcional) 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:

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

Scripts de Hook Específicos do Projeto

Você pode usar a variável de ambiente CLAUDE_PROJECT_DIR (disponível apenas quando Claude Code executa o comando hook) para referenciar scripts armazenados em seu projeto, garantindo que funcionem independentemente do diretório atual do Claude:

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

Hooks de plugin

Plugins podem fornecer hooks que se integram perfeitamente com seus hooks de usuário e projeto. Os hooks de plugin são automaticamente mesclados com sua configuração quando os plugins estão ativados. Como funcionam os 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 é ativado, 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

Exemplo de configuração de hook 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
          }
        ]
      }
    ]
  }
}

Os hooks de plugin usam o mesmo formato que hooks regulares com um campo description opcional para explicar o propósito do hook.

Os hooks de plugin são executados junto com seus hooks personalizados. Se vários hooks corresponderem a um evento, todos serão executados em paralelo.

Variáveis de ambiente para plugins:

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

Consulte a referência de componentes de plugin para detalhes sobre como criar hooks de plugin.

Eventos de Hook

PreToolUse

Executado após Claude criar parâmetros de ferramenta e antes de processar a chamada de ferramenta. Matchers comuns:

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

PostToolUse

Executado imediatamente após uma ferramenta ser concluída com sucesso. Reconhece os mesmos valores de matcher que PreToolUse.

Notification

Executado quando Claude Code envia notificações. As 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 ociosa por pelo menos 60 segundos. “Claude está aguardando sua entrada”

UserPromptSubmit

Executado quando o usuário envia um prompt, antes de Claude processá-lo. Isso permite que você adicione contexto adicional com base no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.

Stop

Executado quando o agente principal do Claude Code terminou de responder. Não é executado se a parada ocorreu devido a uma interrupção do usuário.

SubagentStop

Executado quando um subagente do Claude Code (chamada de ferramenta Task) terminou de responder.

PreCompact

Executado antes de Claude Code estar prestes a executar uma operação de compactação. Matchers:

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

SessionStart

Executado quando Claude Code inicia uma nova sessão ou retoma uma sessão existente (que atualmente inicia uma nova sessão internamente). Útil para carregar contexto de desenvolvimento como problemas existentes ou alterações recentes em sua base de código, instalar dependências ou configurar variáveis de ambiente. Matchers:

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

Os hooks SessionStart têm acesso à variável de ambiente CLAUDE_ENV_FILE, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos bash subsequentes. Exemplo: Configurando variáveis de ambiente individuais

#!/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

Exemplo: Persistindo todas as alterações de ambiente do hook Quando sua configuração modifica o ambiente (por exemplo, nvm use), capture e persista todas as alterações comparando o ambiente:

#!/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

Qualquer variável escrita neste arquivo estará disponível em todos os comandos bash subsequentes que Claude Code executa durante a sessão.

CLAUDE_ENV_FILE está disponível apenas para hooks SessionStart. Outros tipos de hook não têm acesso a esta variável.

SessionEnd

Executado quando uma sessão do Claude Code termina. Útil para tarefas de limpeza, registro de estatísticas de sessão ou salvamento do estado da sessão. O campo reason na entrada do hook será um de:

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

Entrada de Hook

Os hooks recebem dados JSON via stdin contendo informações de sessão e dados específicos do evento:

{
  // 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

O esquema exato para tool_input depende da ferramenta.

{
  "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

O esquema exato para tool_input e tool_response depende da ferramenta.

{
  "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 de Notificação

{
  "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

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.

{
  "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

Para manual, custom_instructions vem do que o usuário passa para /compact. Para auto, custom_instructions está vazio.

{
  "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

Existem duas maneiras para hooks retornarem saída de volta ao Claude Code. A saída comunica se deve bloquear e qualquer feedback que deve ser mostrado ao Claude e ao 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 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 ao 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.

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 de Hook	Comportamento
`PreToolUse`	Bloqueia a chamada de ferramenta, mostra stderr ao Claude
`PostToolUse`	Mostra stderr ao Claude (ferramenta já foi executada)
`Notification`	N/A, mostra stderr apenas ao usuário
`UserPromptSubmit`	Bloqueia o processamento de prompt, apaga o prompt, mostra stderr apenas ao usuário
`Stop`	Bloqueia a parada, mostra stderr ao Claude
`SubagentStop`	Bloqueia a parada, mostra stderr ao subagente Claude
`PreCompact`	N/A, mostra stderr apenas ao usuário
`SessionStart`	N/A, mostra stderr apenas ao usuário
`SessionEnd`	N/A, mostra stderr apenas ao 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:

{
  "continue": true, // Se Claude deve continuar após a 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
}

Se continue for false, Claude para de processar após os hooks serem executados.

Para PreToolUse, isso é diferente de "permissionDecision": "deny", que apenas bloqueia uma chamada de ferramenta específica e fornece feedback automático ao Claude.
Para PostToolUse, isso é diferente de "decision": "block", que fornece feedback automatizado ao 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".

stopReason acompanha continue com um motivo mostrado ao usuário, não mostrado ao 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 ao Claude.
"deny" impede que a chamada de ferramenta seja executada. permissionDecisionReason é mostrado ao Claude.
"ask" pede ao usuário para confirmar a chamada de ferramenta na UI. permissionDecisionReason é mostrado ao usuário mas não ao Claude.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "My reason here"
  }
}

Os campos decision e reason estão descontinuados para hooks PreToolUse. Use hookSpecificOutput.permissionDecision e hookSpecificOutput.permissionDecisionReason em vez disso. Os campos descontinuados "approve" e "block" mapeiam para "allow" e "deny" respectivamente.

Controle de Decisão `PostToolUse`

Os hooks PostToolUse podem fornecer feedback ao Claude após a execução da ferramenta.

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

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

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 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": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

Controle de Decisão `Stop`/`SubagentStop`

Os hooks Stop e SubagentStop podem controlar se Claude deve continuar.

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

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

Controle de Decisão `SessionStart`

Os hooks SessionStart permitem que você carregue contexto no início de uma sessão.

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

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

Controle de Decisão `SessionEnd`

Os hooks SessionEnd são executados quando uma sessão termina. Eles não podem bloquear o término da sessão mas podem executar tarefas de limpeza.

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

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

# Define validation rules as a list of (regex pattern, message) tuples
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


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"Error: Invalid JSON input: {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)

# Validate the command
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Exit code 2 blocks tool call and shows stderr to Claude
    sys.exit(2)

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

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

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

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

# Check for sensitive patterns
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Use JSON output to block with a specific reason
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Add current time to context
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
The following is also equivalent:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Allow the prompt to proceed with the additional context
sys.exit(0)

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

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

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

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

# Example: Auto-approve file reads for documentation files
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Use JSON output to auto-approve the tool call
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # Don't show in transcript mode
        }
        print(json.dumps(output))
        sys.exit(0)

# For other cases, let the normal permission flow proceed
sys.exit(0)

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 create entities do servidor Memory
mcp__filesystem__read_file - Ferramenta read file do servidor Filesystem
mcp__github__search_repositories - Ferramenta search do servidor GitHub

Configurando Hooks para Ferramentas MCP

Você pode direcionar ferramentas MCP específicas ou servidores MCP inteiros:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

Exemplos

Para exemplos práticos incluindo formatação de código, notificações e proteção de arquivo, consulte Mais Exemplos no guia de início.

Considerações de Segurança

Aviso de Isenção

USE POR SUA 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 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 qualquer dano resultante do uso de hooks
Você deve testar completamente os hooks em um ambiente seguro antes do uso em produção

Sempre revise e compreenda qualquer comando de hook antes de adicioná-lo à sua configuração.

Melhores Práticas de Segurança

Aqui estão algumas práticas-chave para escrever hooks mais seguros:

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

Segurança de Configuração

Edições diretas de hooks em arquivos de configuração não entram em vigor imediatamente. Claude Code:

Captura um snapshot de hooks na inicialização
Usa este snapshot durante toda a sessão
Avisa se hooks forem modificados externamente
Requer revisão no menu /hooks para que as alterações entrem em vigor

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 são executados em paralelo
Deduplicação: Múltiplos comandos de hook idênticos são automaticamente deduplicated
Ambiente: Executado 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 na 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

Se seus hooks não estão funcionando:

Verifique a configuração - Execute /hooks para ver se seu hook está registrado
Verifique a sintaxe - Certifique-se de que suas configurações JSON são válidas
Teste comandos - Execute comandos de hook manualmente primeiro
Verifique permissões - Certifique-se de que os scripts são executáveis
Revise 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 os 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:

Inspecione a execução do hook - Use claude --debug para ver a execução detalhada do hook
Valide esquemas JSON - Teste entrada/saída de hook com ferramentas externas
Verifique variáveis de ambiente - Verifique se o ambiente do Claude Code está correto
Teste casos extremos - Tente hooks com caminhos de arquivo ou entradas incomuns
Monitore recursos do sistema - Verifique se há esgotamento de recursos durante a execução do hook
Use 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:

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

As mensagens de progresso aparecem no modo de transcrição (Ctrl-R) mostrando:

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

Primeiros passos

Construir com Claude Code

Claude Agent SDK

Implantação

Administração

Configuração

Referência

Recursos

​Configuração

​Estrutura

​Scripts de Hook Específicos do Projeto

​Hooks de plugin

​Eventos de Hook

​PreToolUse

​PostToolUse

​Notification

​UserPromptSubmit

​Stop

​SubagentStop

​PreCompact

​SessionStart

​Persistindo variáveis de ambiente

​SessionEnd

​Entrada de Hook

​Entrada PreToolUse

​Entrada PostToolUse

​Entrada de Notificação

​Entrada UserPromptSubmit

​Entrada Stop e SubagentStop

​Entrada PreCompact

​Entrada SessionStart

​Entrada SessionEnd

​Saída de Hook

​Simples: Código de Saída

​Comportamento do Código de Saída 2

​Avançado: Saída JSON

​Campos JSON Comuns

​Controle de Decisão PreToolUse

​Controle de Decisão PostToolUse

​Controle de Decisão UserPromptSubmit

​Controle de Decisão Stop/SubagentStop

​Controle de Decisão SessionStart

​Controle de Decisão SessionEnd

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

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

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

​Trabalhando com Ferramentas MCP

​Nomenclatura de Ferramentas MCP

​Configurando Hooks para Ferramentas MCP

​Exemplos

​Considerações de Segurança

​Aviso de Isenção

​Melhores Práticas de Segurança

​Segurança de Configuração

​Detalhes de Execução de Hook

​Depuração

​Solução de Problemas Básica

​Depuração Avançada

​Exemplo de Saída de Debug

Configuração

Estrutura

Scripts de Hook Específicos do Projeto

Hooks de plugin

Eventos de Hook

PreToolUse

PostToolUse

Notification

UserPromptSubmit

Stop

SubagentStop

PreCompact

SessionStart

Persistindo variáveis de ambiente

SessionEnd

Entrada de Hook

Entrada PreToolUse

Entrada PostToolUse

Entrada de Notificação

Entrada UserPromptSubmit

Entrada Stop e SubagentStop

Entrada PreCompact

Entrada SessionStart

Entrada SessionEnd

Saída de Hook

Simples: Código de Saída

Comportamento do Código de Saída 2

Avançado: Saída JSON

Campos JSON Comuns

Controle de Decisão `PreToolUse`

Controle de Decisão `PostToolUse`

Controle de Decisão `UserPromptSubmit`

Controle de Decisão `Stop`/`SubagentStop`

Controle de Decisão `SessionStart`

Controle de Decisão `SessionEnd`

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

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

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

Trabalhando com Ferramentas MCP

Nomenclatura de Ferramentas MCP

Configurando Hooks para Ferramentas MCP

Exemplos

Considerações de Segurança

Aviso de Isenção

Melhores Práticas de Segurança

Segurança de Configuração

Detalhes de Execução de Hook

Depuração

Solução de Problemas Básica

Depuração Avançada

Exemplo de Saída de Debug