Em modo não interativo com a flag -p, Claude Code oferece AskUserQuestion e ExitPlanMode apenas quando a execução tem um host de permissão para receber o prompt, como um callback canUseTool do Agent SDK. Essas ferramentas requerem interação do usuário. Retornar permissionDecision: "allow" junto com updatedInput satisfaz esse requisito: o hook lê a entrada da ferramenta de stdin, coleta a resposta através de sua própria UI e a retorna em updatedInput para que a ferramenta seja executada sem solicitar. Retornar "allow" sozinho não é suficiente para essas ferramentas. Para AskUserQuestion, repita o array questions original e adicione um objeto answers mapeando o texto de cada pergunta para a resposta escolhida.

A partir da v2.1.199, uma ferramenta MCP cujo servidor a marca com _meta["anthropic/requiresUserInteraction"] é mais rigorosa: um hook não pode pular seu prompt de aprovação com "allow", com ou sem updatedInput, porque Claude Code não pode confirmar que o hook coletou a interação que a ferramenta precisa.

Adiar uma chamada de ferramenta para mais tarde

"defer" é para integrações que executam claude -p como um subprocesso e leem sua saída JSON, como um aplicativo Agent SDK ou uma UI personalizada construída em cima de Claude Code. Permite que esse processo de chamada pause Claude em uma chamada de ferramenta, colete entrada através de sua própria interface e retome onde parou. Claude Code honra este valor apenas em modo não interativo com a flag -p. Em sessões interativas, ele registra um aviso e ignora o resultado do hook.

A ferramenta AskUserQuestion é o caso típico: Claude quer fazer uma pergunta ao usuário, mas não há terminal para responder. Uma execução -p oferece AskUserQuestion apenas quando tem um host de permissão, como uma ferramenta MCP que você passa com --permission-prompt-tool, portanto comece a execução com uma. A viagem de ida e volta funciona assim:

1. Claude chama AskUserQuestion. O hook PreToolUse é disparado.
2. O hook retorna permissionDecision: "defer". A ferramenta não é executada. O processo sai com stop_reason: "tool_deferred" e a chamada de ferramenta pendente preservada na transcrição.
3. O processo de chamada lê deferred_tool_use do resultado do SDK, exibe a pergunta em sua própria UI e espera por uma resposta.
4. O processo de chamada executa claude -p --resume <session-id> com o mesmo host de permissão. A mesma chamada de ferramenta dispara PreToolUse novamente.
5. O hook retorna permissionDecision: "allow" com a resposta em updatedInput. A ferramenta é executada e Claude continua.

O campo deferred_tool_use carrega o id, name e input da ferramenta. O input são os parâmetros que Claude gerou para a chamada de ferramenta, capturados antes da execução:

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

Não há tempo limite ou limite de tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção cleanupPeriodDays, que exclui arquivos de sessão após 30 dias por padrão, seguindo as regras de varredura de retenção. Se a resposta não estiver pronta quando você retomar, o hook pode retornar "defer" novamente e o processo sai da mesma forma. O processo de chamada controla quando quebrar o loop eventualmente retornando "allow" ou "deny" do hook.

"defer" funciona apenas quando Claude faz uma única chamada de ferramenta no turno. Se Claude faz várias chamadas de ferramenta de uma vez, "defer" é ignorado com um aviso e a ferramenta prossegue através do fluxo de permissão normal. A restrição existe porque retomar pode apenas re-executar uma ferramenta: não há maneira de adiar uma chamada de um lote sem deixar as outras não resolvidas.

Se a ferramenta adiada não estiver mais disponível quando você retomar, o processo sai com stop_reason: "tool_deferred_unavailable" e is_error: true antes do hook ser disparado. Isso acontece quando um servidor MCP que forneceu a ferramenta não está conectado para a sessão retomada. O payload deferred_tool_use ainda é incluído para que você possa identificar qual ferramenta desapareceu.

PermissionRequest

Executado quando Claude Code está prestes a pedir permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes em segundo plano em modo não interativo, Claude Code ainda executa esses hooks, e se nenhum hook retornar uma decisão, ele nega a chamada de ferramenta. Use controle de decisão PermissionRequest para permitir ou negar em nome do usuário.

Use este evento quando você precisa de um sinal no momento em que Claude pede permissão para usar uma ferramenta. Claude Code executa um hook Notification com o tipo permission_prompt apenas após o prompt ter esperado cerca de seis segundos.

Claude Code não executa hooks PermissionRequest para a solicitação de rede de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação permission_prompt.

Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.

Entrada PermissionRequest

Os hooks PermissionRequest recebem campos tool_name e tool_input como hooks PreToolUse, mas sem tool_use_id. Para uma ferramenta MCP, eles também recebem o objeto mcp_server. Um array permission_suggestions opcional contém as atualizações de permissão que Claude Code sugere para esta solicitação, como adicionar uma regra de permissão ou alterar o modo de permissão.

O array permission_suggestions não é uma lista exata das opções que você vê, porque cada diálogo de permissão constrói suas próprias opções. Alguns diálogos, como o para edições de arquivo, não leem o array e derivam suas opções da solicitação em si. Um diálogo que o faz pode ainda reter uma opção cuja sugestão permanece no array, por exemplo quando allowManagedPermissionRulesOnly oculta opções de salvamento de regra. Ele também pode oferecer opções que não têm entrada de sugestão, como Yes, and switch to auto mode, que altera o modo de permissão diretamente em vez de através de uma atualização de permissão.

Os hooks PreToolUse são executados antes de cada chamada de ferramenta, independentemente de precisar de permissão. Os hooks PermissionRequest são executados apenas quando Claude Code está prestes a pedir permissão, ou quando de outra forma auto-negaria uma chamada que não pode solicitar. Nenhum evento é disparado para EndConversation.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

Controle de decisão PermissionRequest

Os hooks PermissionRequest podem permitir ou negar solicitações de permissão. Além dos campos de saída JSON disponíveis para todos os hooks, seu script de hook pode retornar um objeto decision com esses campos específicos do evento:

Um hook que sai com 2 sem um objeto decision deixa o fluxo de permissão inalterado, e seu stderr é descartado. Apenas o objeto decision pode conceder ou negar a solicitação.

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

Entradas de atualização de permissão

O campo de saída updatedPermissions e o campo de entrada permission_suggestions ambos usam o mesmo array de objetos de entrada. Cada entrada tem um type que determina seus outros campos, e um destination que controla onde a mudança é escrita.

O campo destination em cada entrada determina se a mudança permanece na memória ou persiste em um arquivo de configurações.

Um hook pode ecoar uma das permission_suggestions que recebeu como sua própria saída updatedPermissions.

PostToolUse

Executado imediatamente após uma ferramenta ser concluída com sucesso.

Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.

Corresponda mais amplamente quando o nome da ferramenta não é o filtro certo:

• Para executar um hook após qualquer ferramenta ser concluída com sucesso, omita o matcher ou defina-o como "*". Seu hook pode então descobrir o que mudou por si mesmo, por exemplo executando git status --porcelain, que também lista arquivos não rastreados que git diff perde. Para chamadas de ferramenta que falham, adicione o mesmo hook em PostToolUseFailure.
• Para executar um hook quando um arquivo específico muda no disco, seja qual for o que o escreveu, use FileChanged. Claude Code não executa um hook PostToolUse correspondente a Edit|Write quando um comando Bash ou um processo fora de Claude Code reescreve o mesmo arquivo.

Entrada PostToolUse

Os hooks PostToolUse são disparados após uma ferramenta já ter sido executada com sucesso. A entrada inclui tanto tool_input, os argumentos enviados para a ferramenta, quanto tool_response, o resultado que ela retornou. O esquema exato para ambos depende da ferramenta. Os caminhos tool_input de ferramenta de arquivo chegam no mesmo formato que para PreToolUse: sempre absoluto, com os separadores nativos da plataforma, portanto barras invertidas no Windows. Para uma ferramenta MCP, a entrada também carrega o objeto mcp_server.

{
  "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",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

Controle de decisão PostToolUse

Os hooks PostToolUse podem fornecer feedback ao Claude após a execução da ferramenta. Além dos campos de saída JSON disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:

O exemplo abaixo substitui a saída de uma chamada Bash. O valor de substituição corresponde à forma de saída da ferramenta Bash:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

Anotar um resultado para o classificador de modo automático

Retorne classifierContext para enviar uma nota breve sobre o resultado da chamada de ferramenta para o classificador de modo automático em vez de para Claude. O classificador nunca recebe resultados de ferramentas em si, portanto este campo é a forma suportada de contar algo sobre o que uma chamada retornou antes de revisar ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.

O exemplo abaixo diz ao classificador de onde a saída de uma consulta veio:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

Quanto peso o classificador dá à nota depende de onde você configurou o hook:

• Hooks configurados em Claude Code: para hooks de arquivos de configurações, plugins, skills e frontmatter de agente, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece intenção do usuário, e se ela afirmar que você aprovou ou solicitou algo, o classificador verifica essa afirmação contra suas próprias mensagens na conversa
• Callbacks do Agent SDK em processo: quando um aplicativo que incorpora Claude Code registra o hook como um callback do SDK TypeScript e retorna a nota durante a sessão ao vivo, o classificador pode pesar uma declaração do usuário retransmitida na nota como intenção do usuário. Tal declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem que você envia, mas nunca levanta um bloqueio que sua própria mensagem não pudesse levantar também. Após uma sessão retomar, Claude Code trata notas restauradas como contexto não verificado. Quando hooks de ambos os grupos anotam a mesma chamada, o classificador trata a nota combinada como não verificada

Claude Code aplica esses limites ao entregar a nota:

• Comprimento: Claude Code limita as notas para uma chamada de ferramenta a 2.000 caracteres e trunca o resto. O limite é compartilhado entre cada hook que responde a essa chamada
• Apenas respostas síncronas: Claude Code ignora o campo na resposta de um hook que é executado em segundo plano, porque essa resposta chega após Claude Code registrar o resultado da ferramenta
• Chamadas que o classificador não registra: a transcrição do classificador omite pesquisas somente leitura como leituras de arquivo e pesquisas. Claude Code descarta uma nota anexada a uma dessas chamadas
• Interação com reescritas: quando a nota descreve saída que você está substituindo com updatedToolOutput, retorne ambos os campos na mesma resposta do hook. Claude Code descarta a nota se essa reescrita for rejeitada ou outra reescrita de hook a substituir. Claude Code entrega uma nota que você retorna sem uma reescrita mesmo quando outro hook reescreve a saída

PostToolUseFailure

Executado quando uma ferramenta que começou a executar falha: a ferramenta lançou um erro, ou uma ferramenta MCP retornou um resultado de erro. Use isso para registrar falhas, enviar alertas ou fornecer feedback corretivo ao Claude.

Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.

Entrada PostToolUseFailure

Os hooks PostToolUseFailure recebem os mesmos campos tool_name e tool_input que PostToolUse, junto com informações de erro como campos de nível superior. Para uma ferramenta MCP, eles também recebem o objeto mcp_server. Por exemplo, um comando npm test falhado pode entregar:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

A string error é geralmente o mesmo texto que Claude recebe como resultado da ferramenta falhada. Seu formato varia por ferramenta e falha. Chave seu hook em tool_name, is_interrupt e a primeira linha Exit code N; trate o resto da string como texto de exibição, não um formato estável.

• Para Bash e PowerShell, um comando que foi executado e saiu produz uma primeira linha Exit code N, depois qualquer saída que o comando produziu como um bloco com stdout e stderr intercalados
• Um payload também pode carregar uma mensagem de falha nua sem linha de código de saída, quando Claude Code não pôde iniciar o próprio processo de shell
• Claude Code trunca no meio strings longas em torno de um marcador ... [N characters truncated] ... e pode inserir linhas suas, como Command timed out after 2m 0s

Controle de decisão PostToolUseFailure

Os hooks PostToolUseFailure podem fornecer contexto ao Claude após uma falha de ferramenta. Além dos campos de saída JSON disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

PostToolBatch

Executado uma vez após cada chamada de ferramenta em um lote ter sido resolvida, antes de Claude Code enviar a próxima solicitação para o modelo. PostToolUse é disparado uma vez por ferramenta, o que significa que é disparado concorrentemente quando Claude faz chamadas de ferramenta paralelas. PostToolBatch é disparado exatamente uma vez com o lote completo, portanto é o lugar certo para injetar contexto que depende do conjunto de ferramentas que foram executadas em vez de em qualquer ferramenta única. Não há matcher para este evento.

Entrada PostToolBatch

Além dos campos de entrada comuns, os hooks PostToolBatch recebem tool_calls, um array descrevendo cada chamada de ferramenta no lote:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

tool_response contém o mesmo conteúdo que o modelo recebe no bloco tool_result correspondente. O valor é uma string serializada ou array de bloco de conteúdo, exatamente como a ferramenta o emitiu. Para Read, isso significa texto com prefixo de número de linha em vez de conteúdo de arquivo bruto. As respostas podem ser grandes, portanto analise apenas os campos que você precisa.

Controle de decisão PostToolBatch

Os hooks PostToolBatch podem injetar contexto para Claude. Além dos campos de saída JSON disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

Retornar decision: "block" ou continue: false para o loop agentic antes da próxima chamada do modelo. A mensagem de bloqueio vem do JSON reason ou stopReason, ou de stderr ao sair com 2. Você a vê como um aviso na transcrição, e ela permanece na conversa, portanto Claude a vê quando a conversa continua.

PermissionDenied

Executado quando modo automático nega uma chamada de ferramenta, incluindo quando nega sem um veredicto do classificador porque uma verificação de segurança separada do modo automático recusou a própria solicitação do classificador ou sua resposta não foi analisada. Este hook é disparado apenas em modo automático: não é executado quando você nega manualmente um diálogo de permissão, quando um hook PreToolUse bloqueia uma chamada, ou quando uma regra deny corresponde. Use-o para registrar negações, ajustar configuração ou dizer ao modelo que pode tentar novamente a chamada de ferramenta.

Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.

Entrada PermissionDenied

Além dos campos de entrada comuns, os hooks PermissionDenied recebem tool_name, tool_input, tool_use_id e reason. Para uma ferramenta MCP, eles também recebem o objeto mcp_server.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

Controle de decisão PermissionDenied

Os hooks PermissionDenied podem dizer ao modelo que pode tentar novamente a chamada de ferramenta negada. Retorne um objeto JSON com hookSpecificOutput.retry definido como true:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

Quando retry é true, Claude Code adiciona uma mensagem à conversa dizendo ao modelo que pode tentar novamente a chamada de ferramenta. Claude Code não reverte a negação em si. Se seu hook não retornar JSON, ou retornar retry: false, a negação permanece e o modelo recebe a mensagem de rejeição original.

Claude Code ignora retry: true quando o classificador produziu nenhum veredicto sobre a ação: sua resposta não foi analisada, ou uma verificação de segurança separada do modo automático recusou a própria solicitação do classificador. Para essas negações, Claude Code já diz ao modelo na mensagem de rejeição se deve tentar novamente mais tarde ou prosseguir.

Notification

Executado quando Claude Code envia notificações. Corresponde ao tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.

Você recebe esses eventos de hook mesmo com notificações de desktop desativadas: a configuração preferredNotifChannel, incluindo notifications_disabled, altera apenas como você é alertado, não se seu hook é executado.

Os tipos agent_needs_input e agent_completed requerem Claude Code v2.1.198 ou posterior.

Os tipos quota_auto_resume_fired, quota_auto_resume_stale e quota_auto_resume_disabled requerem Claude Code v2.1.234 ou posterior.

Em sessões de terminal, permission_prompt para a solicitação de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.

agent_needs_input para uma pergunta de configuração de terminal de colega requer Claude Code v2.1.248 ou posterior.

Claude Code cronometra permission_prompt diferentemente em sessões onde envia solicitações de permissão para o callback canUseTool do Agent SDK, que é como Claude Desktop e a extensão VS Code hospedam Claude Code:

• Espere permission_prompt cerca de seis segundos após Claude pedir permissão. Claude Code não o adia enquanto você digita.
• Se você ou um hook PermissionRequest responder mais cedo, Claude Code não executa permission_prompt.
• Defina CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS como 1 para desativar permission_prompt nessas sessões.

Antes da v2.1.233, permission_prompt não era disparado nessas sessões.

Use matchers separados para executar diferentes manipuladores dependendo do tipo de notificação. Esta configuração dispara um script de alerta específico de permissão quando Claude precisa de aprovação de permissão e uma notificação diferente quando Claude está inativo:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Entrada Notification

Além dos campos de entrada comuns, os hooks Notification recebem message com o texto de notificação, um title opcional e notification_type indicando qual tipo foi disparado.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Os hooks Notification não podem bloquear ou modificar notificações. Claude Code descarta seus campos systemMessage e continue mas ainda emite terminalSequence, que é no que o exemplo de notificação de desktop se baseia. Os hooks Notification são destinados a efeitos colaterais como encaminhar a notificação para um serviço externo.

SubagentStart

Executado quando Claude gera um subagente com a ferramenta Agent, quando Claude retoma um subagente e cada vez que um colega de equipe de agente em processo manipula uma nova mensagem. Suporta matchers para filtrar por nome de tipo de agente. Para agentes integrados, este é o nome do agente como general-purpose, Explore ou Plan. Para subagentes personalizados, este é o campo name do frontmatter do agente, não o nome do arquivo.

Para subagentes enviados por um plugin, o tipo de agente é o identificador com escopo de plugin como my-plugin:reviewer, não o nome de frontmatter nú. O dois-pontos coloca um nome com escopo de plugin no caminho de expressão regular, portanto ancor o matcher com ^ e $ para uma correspondência exata: ^my-plugin:reviewer$.

Entrada SubagentStart

Além dos campos de entrada comuns, os hooks SubagentStart recebem agent_id com o identificador único para o subagente e agent_type com o nome do agente que o matcher filtra.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

Os hooks SubagentStart não podem bloquear a criação de subagente, mas podem injetar contexto no subagente. Além dos campos de saída JSON disponíveis para todos os hooks, você pode retornar:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

Quando o hook é executado novamente para o mesmo subagente, Claude Code injeta o contexto retornado apenas quando o contexto do subagente não já contém a cópia de uma execução anterior. A cópia injetada no lançamento permanece no lugar, deixando o cache de prompt do subagente intacto. Após compactação automática descartar essa cópia, Claude Code injeta o contexto da próxima execução novamente.

SubagentStop

Executado quando um subagente Claude Code terminou de responder. Corresponde ao tipo de agente, mesmos valores que SubagentStart.

Entrada SubagentStop

Além dos campos de entrada comuns, os hooks SubagentStop recebem stop_hook_active, agent_id, agent_type, agent_transcript_path e last_assistant_message. O campo agent_type é o valor usado para filtragem de matcher. O transcript_path é a transcrição da sessão principal, enquanto agent_transcript_path é a própria transcrição do subagente armazenada em uma pasta subagents/ aninhada. O campo last_assistant_message contém o conteúdo de texto da resposta final do subagente, portanto hooks podem acessá-lo sem analisar o arquivo de transcrição.

Não há eventos de hook de subagente Claude Code que não sejam de subagente. Claude Code também executa agentes internos para alguns de seus próprios recursos, como sugestões de prompt e perguntas laterais /btw, e SubagentStop é disparado quando um desses termina também. Para esses eventos, agent_type é o nome do agente que a sessão em si executa, como um definido com --agent ou a configuração agent, e uma string vazia quando a sessão é executada sem um.

Um matcher que nomeia tipos de agente não corresponde a um agent_type vazio. Um hook cujo matcher é omitido, "", ou "*", ou é uma expressão regular que corresponde a uma string vazia, é executado para eventos com um agent_type vazio também.

No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta SubagentHandback entrega seu relatório através dessa ferramenta antes de parar. O campo last_assistant_message então contém o texto de fechamento do subagente, se houver, que não é o relatório entregue. O relatório é a entrada message dessa chamada, que um hook PreToolUse ou PostToolUse correspondente a SubagentHandback recebe como tool_input.message.

Os hooks SubagentStop também recebem os arrays background_tasks e session_crons descritos em entrada Stop. Ambos os arrays estão no escopo da sessão pai, não do subagente.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

Os hooks SubagentStop usam o mesmo formato de controle de decisão que hooks Stop, incluindo hookSpecificOutput.additionalContext com hookEventName definido como "SubagentStop", para feedback sem erro que mantém o subagente em execução. Retornar decision: "block" com um reason mantém o subagente em execução e entrega reason ao subagente como sua próxima instrução. Um hook que bloqueia ao sair com 2 entrega sua mensagem stderr da mesma forma. Para injetar contexto na sessão pai após um subagente retornar, use um hook PostToolUse na ferramenta Agent em vez disso.

TaskCreated

Executado quando uma tarefa está sendo criada via ferramenta TaskCreate. Use isso para impor convenções de nomenclatura, exigir descrições de tarefa ou impedir que certas tarefas sejam criadas. Em uma sessão sem as ferramentas Task, este evento não é disparado.

Os hooks TaskCreated não suportam matchers e são disparados em cada ocorrência.

Entrada TaskCreated

Além dos campos de entrada comuns, os hooks TaskCreated recebem task_id, task_subject e opcionalmente task_description, teammate_name e team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

Controle de decisão TaskCreated

Um hook TaskCreated pode bloquear a criação de duas maneiras. De qualquer forma, Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. Claude Code ignora continue: false deste evento e Claude continua trabalhando.

• Código de saída 2: Claude Code retorna o texto stderr como a mensagem.
• JSON {"decision": "block", "reason": "..."}: Claude Code retorna reason como a mensagem.

Este exemplo bloqueia tarefas cujos assuntos não seguem o formato necessário:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

Executado quando uma tarefa está sendo marcada como concluída. Isso é disparado em duas situações: quando qualquer agente marca explicitamente uma tarefa como concluída através da ferramenta TaskUpdate, ou quando um colega de equipe de agente termina seu turno com tarefas em andamento. Use isso para impor critérios de conclusão como testes aprovados ou verificações de lint antes de uma tarefa poder fechar.

Os hooks TaskCompleted não suportam matchers e são disparados em cada ocorrência.

Entrada TaskCompleted

Além dos campos de entrada comuns, os hooks TaskCompleted recebem task_id, task_subject e opcionalmente task_description, teammate_name e team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

Controle de decisão TaskCompleted

Os hooks TaskCompleted suportam duas maneiras de controlar a conclusão da tarefa:

• Código de saída 2: a tarefa não é marcada como concluída e a mensagem stderr é retornada ao modelo como feedback.
• JSON {"continue": false, "stopReason": "..."}: quando um colega terminando seu turno disparou o evento, para o colega inteiramente, correspondendo ao comportamento do hook Stop. O stopReason é mostrado ao usuário. Quando a ferramenta TaskUpdate disparou o evento, Claude Code ignora continue: false; o código de saída 2 ainda bloqueia a conclusão.

Este exemplo executa testes e bloqueia a conclusão da tarefa se falharem:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

Executado quando o agente Claude Code principal terminou de responder. Não é executado se a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam StopFailure em vez disso.

Entrada Stop

Além dos campos de entrada comuns, os hooks Stop recebem stop_hook_active, last_assistant_message, background_tasks e session_crons. O campo stop_hook_active é true quando Claude Code já está continuando como resultado de um hook stop. Verifique este valor ou processe a transcrição para evitar bloquear em uma condição que nunca será resolvida. Claude Code sobrescreve o hook e termina o turno após 8 bloqueios consecutivos.

O campo last_assistant_message contém o conteúdo de texto da resposta final do Claude, portanto hooks podem acessá-lo sem analisar o arquivo de transcrição. Para hooks que atuam no turno recém-concluído, como hooks de leitura em voz alta ou notificação, use este campo em vez de ler transcript_path: o arquivo de transcrição não é garantido incluir a mensagem final no tempo de Stop em todas as versões.

Os arrays background_tasks e session_crons permitem que hooks distingam "sessão está feita" de "sessão está pausada esperando que trabalho de fundo a acorde novamente". Ambos os arrays estão presentes quando o registro de tarefas é alcançável e estão vazios quando nada está em voo ou agendado.

Cada entrada em background_tasks descreve uma tarefa em voo e usa estes campos:

Cada entrada em session_crons descreve um despertar agendado com escopo de sessão, originário de CronCreate, ScheduleWakeup e /loop:

Este exemplo mostra uma entrada Stop com uma tarefa de shell em voo e um cron recorrente:

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Controle de decisão Stop

Os hooks Stop e SubagentStop podem controlar se Claude continua. Além dos campos de saída JSON disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:

Um hook que bloqueia ao sair com 2 roteia da mesma forma que reason: Claude recebe a mensagem stderr como a explicação de por que deve continuar.

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

Use additionalContext quando o hook está funcionando conforme projetado e dando orientação ao Claude, como "execute a suite de testes antes de terminar". Mantém a conversa passando através das mesmas proteções de loop que decision: "block", a saber a entrada stop_hook_active e o limite de 8 continuações consecutivas, mas a transcrição a rotula como Stop hook feedback e nenhuma notificação de erro de hook é mostrada:

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

Executado em vez de Stop quando o turno termina devido a um erro de API. Claude Code ignora a saída e código de saída do hook, além de terminalSequence. Use isso para registrar falhas, enviar alertas ou tomar ações de recuperação quando Claude não pode completar uma resposta devido a limites de taxa, problemas de autenticação ou outros erros de API.

Entrada StopFailure

Além dos campos de entrada comuns, os hooks StopFailure recebem error, error_details opcional e last_assistant_message opcional. O campo error identifica o tipo de erro e é usado para filtragem de matcher.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

Os hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e registro.

TeammateIdle

Executado quando um colega de equipe de agente está prestes a ficar inativo após terminar seu turno. Use isso para impor portões de qualidade antes de um colega parar de trabalhar, como exigir verificações de lint aprovadas ou verificar que arquivos de saída existem.

Os hooks TeammateIdle não suportam matchers e são disparados em cada ocorrência.

Entrada TeammateIdle

Além dos campos de entrada comuns, os hooks TeammateIdle recebem teammate_name e team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

Controle de decisão TeammateIdle

Os hooks TeammateIdle suportam duas maneiras de controlar o comportamento do colega:

• Código de saída 2: o colega recebe a mensagem stderr como feedback e continua trabalhando em vez de ficar inativo.
• JSON {"continue": false, "stopReason": "..."}: para o colega inteiramente, correspondendo ao comportamento do hook Stop. O stopReason é mostrado ao usuário.

Este exemplo verifica se um artefato de compilação existe antes de permitir que um colega fique inativo:

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

Executado quando um arquivo de configuração muda durante uma sessão. Use isso para auditar mudanças de configurações, impor políticas de segurança ou bloquear modificações não autorizadas em arquivos de configuração.

Claude Code executa hooks ConfigChange quando um arquivo de configurações, um arquivo de política gerenciada ou um arquivo de skill muda. Para política gerenciada, ele os executa apenas quando managed-settings.json ou um arquivo em managed-settings.d/ muda. Ele aplica configurações gerenciadas pelo servidor e mudanças em preferências gerenciadas macOS ou política de registro Windows sem executá-los. Em WSL com wslInheritsWindowsSettings, ele também aplica um arquivo de configurações gerenciadas do lado Windows alterado em sua pesquisa de política sem executá-los.

O matcher filtra na fonte de configuração:

Este exemplo registra todas as mudanças de configuração para auditoria de segurança:

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Entrada ConfigChange

Além dos campos de entrada comuns, os hooks ConfigChange recebem source e opcionalmente file_path. O campo source indica qual tipo de configuração mudou, e file_path fornece o caminho para o arquivo específico que foi modificado.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

Controle de decisão ConfigChange

Os hooks ConfigChange podem bloquear mudanças de configuração de serem aplicadas. Use código de saída 2 ou um JSON decision para impedir a mudança. Quando bloqueado, as novas configurações não são aplicadas à sessão em execução.

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

As mudanças policy_settings não podem ser bloqueadas. Os hooks ainda são disparados para fontes policy_settings quando um arquivo de configurações gerenciadas na máquina muda, portanto você pode usá-los para registrar essas edições, mas qualquer decisão de bloqueio é ignorada. Isso garante que as configurações gerenciadas pela empresa sempre tenham efeito. Claude Code não executa hooks ConfigChange quando configurações gerenciadas pelo servidor chegam ou são atualizadas.

Claude Code atua na decisão de bloqueio da saída JSON de um hook ConfigChange e descarta systemMessage e continue. Uma mudança bloqueada não exibe nenhuma mensagem para você ou para Claude, independentemente de você bloquear com reason ou com stderr ao sair com 2. Claude Code apenas escreve uma linha no log de depuração.

CwdChanged

Executado quando um comando de shell na conversa principal muda o diretório de trabalho, por exemplo quando Claude executa um comando cd. Use isso para reagir a mudanças de diretório: recarregar variáveis de ambiente, ativar toolchains específicas do projeto ou executar scripts de configuração automaticamente. Emparelha com FileChanged para ferramentas como direnv que gerenciam ambiente por diretório.

Os hooks CwdChanged têm acesso a CLAUDE_ENV_FILE. Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento CwdChanged, quando Claude Code as limpa.

CwdChanged não suporta matchers e é disparado em cada ocorrência.

Entrada CwdChanged

Além dos campos de entrada comuns, os hooks CwdChanged recebem old_cwd e new_cwd.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

Saída CwdChanged

Além dos campos de saída JSON disponíveis para todos os hooks, os hooks CwdChanged podem retornar watchPaths para definir dinamicamente quais caminhos de arquivo FileChanged observa:

Os hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.

Claude Code lê watchPaths e systemMessage de sua saída JSON e descarta continue. Em sessões interativas, mostra o systemMessage como uma breve notificação de terminal. A mensagem não chega ao fluxo de mensagens do SDK.

DirectoryAdded

Executado após você adicionar um diretório de trabalho no meio da sessão com o comando /add-dir, ou após um cliente SDK adicionar um com a solicitação de controle register_repo_root. Use isso para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.

Claude Code não dispara este evento quando:

• Você passa um diretório com a flag de startup --add-dir; SessionStart cobre esses diretórios
• Você adiciona um diretório na aba /permissions Workspace
• Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um

Claude Code dispara DirectoryAdded após atualizar estado de sandbox e permissão, portanto ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Comandos de hook em si são executados sem sandbox.

Claude Code não espera pelo hook: a adição é concluída imediatamente, e o hook é executado em segundo plano com o tempo limite padrão de 600 segundos.

O matcher filtra em como o diretório foi adicionado:

Entrada DirectoryAdded

Além dos campos de entrada comuns, os hooks DirectoryAdded recebem directory e source.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

Os hooks DirectoryAdded não têm controle de decisão. Eles não podem bloquear a adição, que já foi concluída quando o hook é executado. Claude Code descarta o campo continue de sua saída JSON e exibe o resto diferentemente por fonte:

• slash_command: Claude Code entrega o systemMessage do hook ao Claude como contexto no próximo turno de conversa, em vez de mostrar a você. Uma contagem de hooks falhados aparece na transcrição. A saída de falha completa vai para o log de depuração
• register_repo_root: Claude Code escreve saída systemMessage e saída de falha apenas no log de depuração

FileChanged

Executado quando um arquivo observado muda no disco. Claude Code detecta mudanças com um observador de sistema de arquivos, não inspecionando chamadas de ferramenta, portanto executa o hook não importa o que mudou o arquivo: uma chamada de ferramenta Edit ou Write, um script que Claude executa com Bash ou um processo fora de Claude Code inteiramente. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.

O matcher para este evento serve dois papéis:

• Construir a lista de observação: o valor é dividido em | e cada segmento é registrado como um nome de arquivo literal no diretório de trabalho, portanto ".envrc|.env" observa exatamente esses dois arquivos. Padrões regex não são úteis aqui: um valor como ^\.env observaria um arquivo literalmente nomeado ^\.env.
• Filtrar quais hooks são executados: quando um arquivo observado muda, o mesmo valor filtra quais grupos de hook são executados usando as regras de matcher padrão contra o nome base do arquivo alterado.

Este exemplo normaliza terminações de linha em data.csv após qualquer mudança, incluindo um comando Bash ou um script externo reescrevendo o arquivo:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

O hook lê o caminho absoluto do arquivo alterado do campo file_path da entrada JSON em stdin. Sua guarda grep testa a mesma coisa que perl remove, um CR no final de uma linha, portanto a execução após uma normalização sai sem tocar no arquivo. Uma guarda mais solta faz um loop para sempre, porque perl -i reescreve o arquivo mesmo quando substitui nada e Claude Code executa o hook novamente após cada reescrita. Salve este script em /path/to/normalize-line-endings.sh e torne-o executável:

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

Para confirmar que o hook funciona, peça ao Claude para anexar uma linha CRLF a data.csv com um comando Bash. Claude Code executa o hook e o arquivo termina com terminações LF.

Para observar arquivos que você não pode nomear antecipadamente, retorne watchPaths de um hook para atualizar a lista de observação dinamicamente. Claude Code inicia o observador apenas quando algo nomeia um arquivo para observar, portanto semeie a lista com um grupo FileChanged cujo matcher nomeia pelo menos um arquivo, ou com um hook SessionStart ou CwdChanged que retorna watchPaths. O matcher ainda filtra quais grupos de hook são executados quando um arquivo observado muda, portanto dê ao grupo que manipula caminhos dinâmicos um matcher omitido, que corresponde a cada arquivo observado e não adiciona nada à lista de observação. Um matcher "*" também corresponde a cada arquivo, mas Claude Code o registra na lista de observação como qualquer outro valor, como um arquivo literal nomeado *.

Os hooks FileChanged têm acesso a CLAUDE_ENV_FILE. Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento CwdChanged, quando Claude Code as limpa.

Entrada FileChanged

Além dos campos de entrada comuns, os hooks FileChanged recebem file_path e event.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

Saída FileChanged

Além dos campos de saída JSON disponíveis para todos os hooks, os hooks FileChanged podem retornar watchPaths para atualizar dinamicamente quais caminhos de arquivo são observados:

Os hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.

Claude Code lê watchPaths e systemMessage de sua saída JSON e descarta continue. Em sessões interativas, mostra o systemMessage como uma breve notificação de terminal. A mensagem não chega ao fluxo de mensagens do SDK.

WorktreeCreate

Executado quando uma worktree está sendo criada, seja de claude --worktree, de um subagente usando isolation: "worktree" ou para uma sessão em segundo plano que Claude Code isola em sua própria worktree. Por padrão, Claude Code cria a cópia de trabalho isolada com git worktree. Configurar um hook WorktreeCreate substitui esse comportamento git padrão, permitindo que você use um sistema de controle de versão diferente como SVN, Perforce ou Mercurial.

Como o hook substitui o comportamento padrão inteiramente, .worktreeinclude não é processado. Se você precisar copiar arquivos de configuração local como .env para a nova worktree, faça isso dentro de seu script de hook.

O hook deve retornar o caminho para o diretório de worktree criado. Claude Code usa este caminho como o diretório de trabalho para a sessão isolada. Veja saída WorktreeCreate para como cada tipo de hook retorna o caminho.

Claude Code atua no sucesso do hook e no caminho retornado, e descarta systemMessage e continue.

Este exemplo cria uma cópia de trabalho SVN e imprime o caminho para Claude Code usar. Substitua a URL do repositório pela sua própria:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

O hook lê o name da worktree da entrada JSON em stdin, faz checkout de uma cópia fresca em um novo diretório e imprime o caminho do diretório. O echo na última linha é o que Claude Code lê como o caminho da worktree. Redirecione qualquer outra saída para stderr para que não interfira com o caminho.

Entrada WorktreeCreate

Além dos campos de entrada comuns, os hooks WorktreeCreate recebem o campo name. Este é um identificador slug para a nova worktree, especificado pelo usuário ou auto-gerado, por exemplo bold-oak-a3f2.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

Saída WorktreeCreate

Os hooks WorktreeCreate não usam o modelo de decisão permitir/bloquear padrão. Em vez disso, o sucesso ou falha do hook determina o resultado. O hook deve retornar o caminho para o diretório de worktree criado:

• Hooks de comando (type: "command"): imprima o caminho como a última linha não vazia de stdout. Claude Code remove códigos de escape ANSI antes de ler essa linha, portanto banners de inicialização de shell impressos antes de seu echo são ignorados. Redirecione qualquer outra saída de hook para stderr.
• Hooks HTTP (type: "http"): retorne { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } no corpo da resposta.

Se o hook falhar ou não produzir um caminho, a criação de worktree falha com um erro.

Claude Code resolve um caminho relativo contra o diretório em que o hook foi executado, colapsando qualquer segmento . ou .. nele. Se o caminho resultante não for um diretório que Claude Code possa entrar, a sessão imprime um erro nomeando o caminho e sai com código 1.

Claude Code recusa um caminho absoluto que contém segmentos . ou .., e qualquer caminho que passa através de um symlink abaixo da raiz do repositório, porque um symlink comprometido no repositório poderia redirecionar a worktree para fora dele. O erro nomeia o componente rejeitado. Retorne um caminho normalizado que não passa através de um symlink dentro do repositório. Antes da v2.1.216, a criação de worktree seguia o caminho do hook sem essa triagem.

WorktreeRemove

Executado quando uma worktree está sendo removida. Este é o equivalente de limpeza para WorktreeCreate. O evento é disparado quando:

• você sai de uma sessão --worktree e escolhe removê-la
• um subagente com isolation: "worktree" termina
• você exclui uma sessão em segundo plano cuja worktree o hook criou

Para worktrees baseadas em git, Claude Code manipula a limpeza automaticamente com git worktree remove. Se você configurou um hook WorktreeCreate para um sistema de controle de versão não-git, emparelhe-o com um hook WorktreeRemove para manipular a limpeza. Sem um, o diretório de worktree é deixado no disco.

Claude Code descarta os campos de saída JSON de um hook WorktreeRemove, como systemMessage e continue.

Para uma exclusão de sessão em segundo plano, Claude Code verifica o caminho de worktree armazenado antes de executar o hook e recusa um caminho que é um symlink ou passa através de um abaixo da raiz do repositório. O hook é executado para uma worktree que ainda contém arquivos apenas quando você confirma a exclusão em agent view; para tal worktree, claude rm mantém a sessão e worktree em vez disso. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.

Claude Code passa o caminho retornado por WorktreeCreate como worktree_path na entrada do hook. Este exemplo lê esse caminho e remove o diretório:

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

Entrada WorktreeRemove

Além dos campos de entrada comuns, os hooks WorktreeRemove recebem o campo worktree_path, que é o caminho absoluto para a worktree sendo removida.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

O código de saída de um hook WorktreeRemove decide o resultado. Quando um hook sai com código não-zero e o diretório em worktree_path ainda existe depois, a remoção falha:

• A worktree permanece no disco, e o comando do hook e stderr vão para o log de depuração.
• Se você estava excluindo uma sessão em segundo plano, a sessão também permanece. A mensagem de recusa em agent view relata como o hook terminou, como exited 1, cita o início de seu stderr e diz se excluir a sessão novamente remove o diretório de qualquer forma.

PreCompact

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

O valor do matcher indica se a compactação foi disparada manualmente ou automaticamente:

Saia com código 2 para bloquear a compactação. Para um /compact manual, a mensagem stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com "decision": "block".

Bloquear compactação automática tem efeitos diferentes dependendo de quando é disparado. Se a compactação foi disparada proativamente antes do limite de contexto, Claude Code a pula e a conversa continua sem compactação. Se a compactação foi disparada para recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente aparece e a solicitação atual falha.

Claude Code descarta os campos systemMessage e continue de um hook PreCompact.

Entrada PreCompact

Além dos campos de entrada comuns, os hooks PreCompact recebem trigger e custom_instructions. Para manual, custom_instructions contém o que o usuário passa para /compact e é null quando ele não passa nada. Para auto, custom_instructions é null.

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

PostCompact

Executado após Claude Code completar uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo para registrar o resumo gerado ou atualizar estado externo. Claude Code descarta os campos systemMessage e continue de um hook PostCompact.

Os mesmos valores de matcher se aplicam como para PreCompact:

Entrada PostCompact

Além dos campos de entrada comuns, os hooks PostCompact recebem trigger e compact_summary. O campo compact_summary contém o resumo de conversa gerado pela operação de compactação.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

Os hooks PostCompact não têm controle de decisão. Eles não podem afetar o resultado da compactação mas podem executar tarefas de acompanhamento.

PreModelSwitch

Executado antes de Claude Code aplicar uma mudança de modelo que você ou um cliente solicitou. Use-o para bloquear uma mudança, exigir confirmação ou mostrar qual será o custo da mudança antes de acontecer.

PreModelSwitch requer Claude Code v2.1.251 ou posterior. Claude Code o executa para essas solicitações:

• /model <name> e o seletor /model
• O seletor de modelo Option+P ou Alt+P
• A configuração Model em /config
• Ativar modo rápido quando isso muda o modelo da sessão
• Uma solicitação set_model, ou uma mudança de modelo em uma solicitação apply_flag_settings, de um host Agent SDK ou Remote Control

Claude Code não executa hooks PreModelSwitch para mudanças que faz por conta própria, como um fallback de modelo automático ou restaurar o modelo quando você retoma uma sessão. Essas mudanças chegam apenas a PostModelSwitch.

Claude Code compara o matcher contra o nome canônico do modelo para o qual a sessão está mudando, ignorando qualquer sufixo [1m]. Um alias como opus, um ID de modelo datado e um ID específico do provedor como um ID de modelo Amazon Bedrock todos correspondem ao um nome canônico que resolvem, portanto claude-opus-5 cobre cada ortografia de Opus 5.

Quando Claude Code não pode determinar um nome canônico para o alvo, por exemplo um ID de modelo personalizado que apenas seu gateway LLM conhece, ele executa cada hook PreModelSwitch independentemente do matcher. Um hook que bloqueia deve portanto verificar to_model de sua entrada em vez de confiar apenas no matcher.

Escreva o matcher como um nome exato, uma lista separada por | como claude-opus-4-6|claude-opus-5 ou uma expressão regular como .*opus.*. Este exemplo usa um matcher de nome exato e também verifica to_model da entrada do hook, portanto recusa uma mudança para Opus 4.6 ao sair com código 2 e deixa qualquer outro alvo passar:

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

Para confirmar que o hook funciona, execute /model claude-opus-4-6 de uma sessão executando um modelo diferente. Claude Code mantém o modelo atual e relata que um hook PreModelSwitch bloqueou a mudança, com sua mensagem como o motivo.

Entrada PreModelSwitch

Além dos campos de entrada comuns, os hooks PreModelSwitch recebem os campos nesta tabela. Os últimos cinco descrevem qual é o custo de reenviar a conversa para o novo modelo, portanto um hook pode mostrar essa figura antes da mudança acontecer.

Este exemplo mostra a entrada para /model opus em uma sessão executando Sonnet 5:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

Controle de decisão PreModelSwitch

Os hooks PreModelSwitch podem cancelar a mudança, pedir ao usuário para confirmá-la ou deixá-la prosseguir. Código de saída 2 ou um decision: "block" de nível superior cancela a mudança.

Para controle mais fino, retorne permissionDecision e permissionDecisionReason em um objeto hookSpecificOutput, como em PreToolUse. PreModelSwitch aceita "allow", "deny" e "ask". Não aceita "defer", updatedInput ou additionalContext. A tabela abaixo descreve ambos os campos:

Apenas /model em uma sessão interativa pode mostrar o prompt "ask". Em todas as outras superfícies, incluindo modo não interativo com a flag -p, /config e solicitações set_model, Claude Code trata "ask" como uma recusa.

Este exemplo pede ao usuário para confirmar e cita a contagem de tokens de context_tokens:

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é deny > ask > allow.

Claude Code mostra ao usuário qualquer systemMessage que seu hook retorna independentemente da decisão, portanto um hook de relatório de custo pode retornar {"systemMessage": "..."} e sair com 0.

Um hook PreModelSwitch que não responde antes de seu tempo limite bloqueia a mudança. Em PreToolUse, por contraste, um hook de comando que atingiu o tempo limite deixa a chamada de ferramenta continuar. O tempo limite padrão para este evento é 30 segundos. PreModelSwitch executa apenas hooks command, http e mcp_tool, portanto os padrões prompt e agent não se aplicam.

Um hook que sai com um código diferente de 0 ou 2 e não imprime nenhuma decisão JSON não bloqueia: Claude Code mostra seu stderr e aplica a mudança, conforme descrito em Outros códigos de saída.

PostModelSwitch

Executado após o modelo da sessão mudar. Use-o para dar orientação específica do modelo ao Claude sem editar cada CLAUDE.md, por exemplo uma instrução em toda a organização que se aplica em certos modelos.

PostModelSwitch requer Claude Code v2.1.251 ou posterior. Não pode bloquear, porque o modelo já mudou. Claude Code executa hooks PostModelSwitch após qualquer uma dessas mudanças:

• Uma mudança que você ou um cliente solicitou
• Um fallback de modelo automático, que muda o modelo da sessão
• Uma configuração como opusplan entrando ou saindo do modo de plano
• Claude Code restaurando o modelo quando você retoma uma sessão

Claude Code não executa hooks PostModelSwitch quando um modelo de uma cadeia de modelo fallback serve um turno, porque essa substituição dura um turno e deixa o modelo da sessão inalterado.

O matcher segue as mesmas regras que PreModelSwitch: Claude Code compara contra o nome canônico do modelo para o qual a sessão mudou.

Este exemplo adiciona orientação sempre que o modelo da sessão muda para qualquer modelo Opus:

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

Para confirmar que o hook funciona, mude para um modelo Opus de uma sessão executando um modelo diferente, por exemplo execute /model opus de uma sessão Sonnet, depois pergunte ao Claude qual orientação ele tem sobre o modelo atual.

Entrada PostModelSwitch

Os hooks PostModelSwitch recebem os mesmos campos que PreModelSwitch, com hook_event_name definido como "PostModelSwitch" e dois valores source mais: "auto" para um fallback automático ou outra mudança que Claude Code fez por conta própria, e "resume" para o modelo restaurado quando você retoma uma sessão.

requested_model é null quando source é "auto". Quando source é "resume", é a configuração de modelo salva que Claude Code restaurou.

Controle de decisão PostModelSwitch

Claude Code pega seu stdout de texto simples do hook ao sair com 0, ou additionalContext de saída JSON, e o entrega ao Claude com a próxima solicitação após a mudança. Além dos campos de saída JSON disponíveis para todos os hooks, você pode retornar:

Se o hook não terminar dentro de cinco segundos após você enviar a próxima solicitação, Claude Code envia essa solicitação sem a saída e a anexa à solicitação seguinte em vez disso. Se o modelo mudar várias vezes antes da próxima solicitação, Claude Code entrega apenas a saída para a mudança de alvo do último modelo.

SessionEnd

Executado quando uma sessão Claude Code termina. Útil para tarefas de limpeza, registrar estatísticas de sessão ou salvar estado de sessão. Suporta matchers para filtrar por motivo de saída.

O campo reason na entrada do hook indica por que a sessão terminou:

Entrada SessionEnd

Além dos campos de entrada comuns, os hooks SessionEnd recebem um campo reason indicando por que a sessão terminou. Veja a tabela de motivos acima para todos os valores.

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

Os hooks SessionEnd não têm controle de decisão. Eles não podem bloquear o término da sessão mas podem executar tarefas de limpeza. Claude Code descarta seus campos de saída JSON, como systemMessage.

Os hooks SessionEnd têm um tempo limite padrão de 1,5 segundos. Aplica-se quando você sai, executa /clear ou muda de sessões com /resume interativo. Você pode dar a um hook mais tempo de duas maneiras:

• timeout por hook: defina timeout na configuração desse hook. O orçamento geral sobe automaticamente para corresponder ao timeout por hook mais alto em seus arquivos de configurações, até 60 segundos. Se você aumentar o orçamento dessa forma, um hook sem seu próprio timeout ainda mantém o padrão. Tempos limite definidos em hooks fornecidos por plugin não aumentam o orçamento.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS: defina esta variável de ambiente em milissegundos para sobrescrever o orçamento explicitamente. O valor que você define também se torna o tempo limite para cada hook sem seu próprio timeout.

Este exemplo define o orçamento para 5 segundos:

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Antes da v2.1.268, CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS aumentava apenas o orçamento geral, e um hook sem seu próprio timeout ainda era cancelado após 1,5 segundos.

Elicitation

Executado quando um servidor MCP solicita entrada do usuário no meio de uma tarefa. Por padrão, Claude Code mostra um diálogo interativo para o usuário responder. Os hooks podem interceptar essa solicitação e responder programaticamente, pulando o diálogo inteiramente.

O campo matcher corresponde ao nome do servidor MCP.

Entrada Elicitation

Além dos campos de entrada comuns, os hooks Elicitation recebem mcp_server_name, message e campos opcionais mode, url, elicitation_id e requested_schema.

Para elicitação de modo de formulário, o caso mais comum:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

Para elicitação de modo URL, usada para autenticação baseada em navegador:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Saída Elicitation

Para responder programaticamente sem mostrar o diálogo, retorne um objeto JSON com hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

Código de saída 2 nega a elicitação. Claude Code não mostra sua mensagem stderr em lugar nenhum.

Claude Code atua em hookSpecificOutput da saída JSON de um hook Elicitation e descarta systemMessage e continue.

ElicitationResult

Executado após um usuário responder a uma elicitação MCP. Os hooks podem observar, modificar ou bloquear a resposta antes de ser enviada de volta para o servidor MCP.

O campo matcher corresponde ao nome do servidor MCP.

Entrada ElicitationResult

Além dos campos de entrada comuns, os hooks ElicitationResult recebem mcp_server_name, action e campos opcionais mode, elicitation_id e content.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

Saída ElicitationResult

Para sobrescrever a resposta do usuário, retorne um objeto JSON com hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

Código de saída 2 bloqueia a resposta, alterando a ação efetiva para decline. Claude Code não mostra sua mensagem stderr em lugar nenhum.

Claude Code atua em hookSpecificOutput da saída JSON de um hook ElicitationResult e descarta systemMessage e continue.

Hooks baseados em prompt

Além de hooks de comando, HTTP e MCP tool, Claude Code suporta hooks baseados em prompt (type: "prompt") que usam um LLM para avaliar se deve permitir ou bloquear uma ação, e hooks de agente (type: "agent") que geram um verificador agentic com acesso a ferramentas. Nem todos os eventos suportam cada tipo de hook.

Eventos que suportam todos os cinco tipos de hook (command, http, mcp_tool, prompt e agent):

• PermissionDenied
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest suporta hooks command, http, mcp_tool e prompt mas não hooks agent. Se você configurar um hook de agente neste evento, Claude Code o ignora e o fluxo de permissão prossegue inalterado. Para permitir ou negar de um hook, retorne o objeto de decisão de um hook de comando ou HTTP.

Eventos que suportam hooks command, http e mcp_tool mas não prompt ou agent:

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart e Setup suportam hooks command e mcp_tool, e MCP tool hook fields descreve quando seus hooks mcp_tool são executados. Eles não suportam hooks http, prompt ou agent.

Como hooks baseados em prompt funcionam

Em vez de executar um comando Bash, hooks baseados em prompt:

1. Enviam a entrada do hook e seu prompt para um modelo Claude, Haiku por padrão
2. O LLM responde com JSON estruturado contendo uma decisão
3. Claude Code processa a decisão automaticamente

Configuração de hook de prompt

Defina type para "prompt" e forneça uma string prompt em vez de um command. Use o placeholder $ARGUMENTS para injetar dados de entrada do hook em seu texto de prompt.

Este hook Stop pede ao LLM para avaliar se todas as tarefas estão completas antes de permitir que Claude termine:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

Esquema de resposta

O LLM deve responder com JSON contendo:

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

O que acontece em ok: false depende do evento:

• Stop e SubagentStop: a razão é alimentada de volta para Claude como sua próxima instrução e o turno continua, a menos que a resposta também defina impossible: true, caso em que Claude Code permite a parada e o turno termina
• PreToolUse: a chamada de ferramenta é negada; por padrão o turno termina e a razão de negação aparece no chat como uma linha de aviso. Defina continueOnBlock: true para em vez disso retornar a razão para Claude como o erro da ferramenta para que possa se ajustar e continuar, equivalente a um hook de comando com permissionDecision: "deny". Antes da v2.1.210, a razão de negação era retornada para Claude como o erro da ferramenta e o turno continuava
• PostToolUse: por padrão o turno termina e a razão aparece no chat como uma linha de aviso. Defina continueOnBlock: true para alimentar a razão de volta para Claude e continuar o turno em vez disso
• PostToolBatch, UserPromptSubmit e UserPromptExpansion: o turno termina e a razão aparece como uma linha de aviso. Esses eventos terminam o turno em decision: "block" independentemente de continue
• PostToolUseFailure e TaskCreated: a razão é retornada para Claude como um erro de ferramenta e o turno continua, independentemente de continueOnBlock
• TaskCompleted: quando dispara porque uma tarefa é marcada como concluída durante um turno, a razão é retornada para Claude como um erro de ferramenta e o turno continua, independentemente de continueOnBlock. Quando dispara porque um colega para, se comporta como TeammateIdle e interrompe o colega por padrão
• TeammateIdle: por padrão o colega para e a razão aparece como uma linha de aviso. Defina continueOnBlock: true para alimentar a razão de volta para o colega e mantê-lo trabalhando em vez disso
• PermissionRequest: ok: false não tem efeito. Para negar uma aprovação de um hook, use um hook de comando retornando hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied: ok: false não tem efeito porque a negação já aconteceu. A única saída que este evento lê é hookSpecificOutput.retry, que hooks de prompt e agente não podem definir. Eles são executados neste evento, mas sua saída é descartada. Use um hook de comando para retornar retry

Se você precisar de controle mais fino em qualquer evento, use um hook de comando com os campos por evento descritos em Controle de decisão.

Verificar múltiplas condições antes de parar

Este hook Stop usa um prompt detalhado para verificar três condições antes de permitir que Claude pare. Hooks SubagentStop usam o mesmo formato para avaliar se um subagente deve parar. Se o modelo retornar "ok": false porque a condição ainda não foi atendida, Claude continua trabalhando com a razão fornecida como sua próxima instrução:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hooks baseados em agente

Hooks baseados em agente (type: "agent") são como hooks baseados em prompt mas com acesso a ferramentas de múltiplos turnos. Em vez de uma única chamada LLM, um hook de agente gera um subagente que pode ler arquivos, pesquisar código e inspecionar o codebase para verificar condições. Hooks de agente suportam os mesmos eventos que hooks baseados em prompt, exceto PermissionRequest.

Como hooks de agente funcionam

Quando um hook de agente dispara:

1. Claude Code gera um subagente com seu prompt e a entrada JSON do hook
2. O subagente pode usar ferramentas como Read, Grep e Glob para investigar
3. Após até 50 turnos, o subagente retorna uma decisão estruturada { "ok": true/false }
4. Claude Code permite a ação se ok for true. Se ok for false, Claude Code trata o bloqueio da mesma forma que um hook de prompt com continueOnBlock: true naquele evento, conforme listado em Response schema

Hooks de agente são úteis quando a verificação requer inspecionar arquivos reais ou saída de teste, não apenas avaliar dados de entrada do hook sozinhos.

Configuração de hook de agente

Defina type para "agent" e forneça uma string prompt, usando $ARGUMENTS como placeholder para a entrada JSON do hook. Os campos de configuração são os mesmos que prompt hooks, exceto que hooks de agente têm um timeout padrão mais longo de 60 segundos e nenhum campo continueOnBlock.

O esquema de resposta é { "ok": true } para permitir ou { "ok": false, "reason": "..." } para bloquear. Em ok: false, Claude Code trata um hook de agente da forma que trata um prompt hook com continueOnBlock: true no mesmo evento; hooks de agente não têm campo continueOnBlock e não suportam o campo impossible do hook de prompt.

Este hook Stop verifica que todos os testes unitários passam antes de permitir que Claude termine:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Executar hooks em background

Por padrão, hooks bloqueiam a execução de Claude até que completem. Para tarefas de longa duração como deployments, suites de teste ou chamadas de API externas, defina "async": true para executar o hook em background enquanto Claude continua trabalhando. Hooks assíncronos não podem bloquear ou controlar comportamento de Claude: campos de resposta como decision, permissionDecision e continue não têm efeito, porque a ação que controlariam já completou.

Configurar um hook assíncrono

Adicione "async": true à configuração de um hook de comando para executá-lo em background sem bloquear Claude. Este campo está apenas disponível em hooks type: "command".

Este hook executa um script de teste após cada chamada de ferramenta Write. Claude continua trabalhando imediatamente enquanto run-tests.sh executa. Quando o script termina, sua saída é entregue no próximo turno de conversa:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Uma vez que um hook assíncrono está executando em background, Claude Code não impõe timeout nele. Claude Code ainda impõe timeout em um hook que você executa com asyncRewake.

Claude Code entrega resultados de um hook assíncrono apenas enquanto a sessão está em execução:

• Em modo não-interativo com a flag -p, Claude Code mata qualquer hook assíncrono ainda em execução no teardown e o finaliza com resultado cancelled
• Se o trabalho do seu hook deve sobreviver a uma sessão claude -p, inicie um processo totalmente desacoplado a partir dele

Como hooks assíncronos executam

Quando um hook assíncrono dispara, Claude Code inicia o processo do hook e imediatamente continua sem esperar que termine. O hook recebe a mesma entrada JSON via stdin que um hook síncrono.

Após o processo em background sair, Claude Code entrega os campos additionalContext e systemMessage da resposta JSON do hook ao Claude no próximo turno de conversa. Diferentemente de um systemMessage de hook síncrono, nenhum dos dois campos é mostrado para você.

Claude Code valida que a resposta JSON contra o mesmo esquema de saída que hooks síncronos, e descarta qualquer campo cujo valor tenha o tipo errado, como um systemMessage que não seja uma string, em vez de entregá-lo. Execute com --debug para ver um aviso nomeando cada campo descartado. Antes da v2.1.202, saída JSON malformada de um hook assíncrono poderia travar a sessão, e a falha recorria cada vez que a sessão era retomada.

Notificações de conclusão de hook assíncrono são suprimidas por padrão. Para vê-las, ative modo verbose com Ctrl+O ou inicie Claude Code com --verbose.

Executar testes após mudanças de arquivo

Este hook inicia uma suite de testes em background sempre que Claude escreve um arquivo, então relata os resultados de volta ao Claude quando os testes terminam. Salve este script em .claude/hooks/run-tests-async.sh em seu projeto e torne-o executável com chmod +x:

#!/bin/bash
# run-tests-async.sh

# Leia entrada de hook de stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Apenas execute testes para arquivos de origem
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Execute testes e relate resultados ao Claude via additionalContext
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

Então adicione esta configuração a .claude/settings.json na raiz do seu projeto. A flag async: true permite que Claude continue trabalhando enquanto testes executam:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

Limitações

Hooks assíncronos têm restrições adicionais comparados a hooks síncronos:

• Saída de hook é entregue no próximo turno de conversa. Se a sessão está ociosa, a resposta espera até a próxima interação do usuário. Exceção: um hook asyncRewake que sai com código 2 acorda Claude imediatamente mesmo quando a sessão está ociosa.
• Cada execução cria um processo em background separado. Não há desduplicação através de múltiplos disparos do mesmo hook assíncrono.

Considerações de segurança

Aviso

Confiança do workspace

Claude Code verifica a confiança do workspace antes de executar qualquer hook de um arquivo de configurações. O que conta como confiável depende do tipo de sessão:

• Sessão interativa: Claude Code retém hooks de todos os arquivos de configurações, incluindo seu próprio ~/.claude/settings.json, até que você aceite o diálogo de confiança do workspace para a pasta, ou para um diretório pai cuja confiança se estende a ela
• Sessão -p ou SDK: Claude Code nunca mostra o diálogo e trata a pasta como confiável, então hooks confirmados no .claude/settings.json de um repositório são executados em uma pasta que você nunca confiou

Antes de executar claude -p em um repositório que você não escreveu, revise seus arquivos de configurações .claude/, comece com --bare, ou desative hooks para essa execução com --settings '{"disableAllHooks": true}'. Hooks de frontmatter em um subagente de projeto seguem uma regra mais rigorosa do que hooks de arquivo de configurações. O que é executado antes de você confiar em uma pasta lista cada tipo de conteúdo de repositório por tipo de sessão.

Melhores práticas de segurança

Mantenha essas práticas em mente ao escrever hooks:

• Valide e sanitize entradas: nunca confie em dados de entrada cegamente
• Sempre cite variáveis shell: use "$VAR" não $VAR
• Bloqueie traversal de caminho: verifique .. em caminhos de arquivo
• Use caminhos absolutos: especifique caminhos completos para scripts. Na forma exec, use ${CLAUDE_PROJECT_DIR} e o caminho não precisa de aspas. Na forma shell, envolva-o em aspas duplas
• Pule arquivos sensíveis: evite .env, .git/, chaves, etc.

Ferramenta Windows PowerShell

No Windows, você pode executar hooks individuais em PowerShell definindo "shell": "powershell" em um hook de comando. Claude Code auto-detecta pwsh.exe, o executável do PowerShell 7 e posterior, e volta para powershell.exe para Windows PowerShell 5.1.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

Para referenciar o diretório raiz do projeto a partir de um comando em forma de shell do PowerShell, escreva ${CLAUDE_PROJECT_DIR} ou $env:CLAUDE_PROJECT_DIR. A partir da v2.1.198, Claude Code reescreve os espaços reservados ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} e ${CLAUDE_PLUGIN_DATA} em um comando em forma de shell do PowerShell para a forma ${env:NAME} do PowerShell, independentemente de o hook estar definido em settings.json, um plugin ou uma skill. PowerShell então resolve o valor do ambiente exportado após análise, então o espaço reservado funciona dentro de strings entre aspas duplas, mas não dentro de strings entre aspas simples, onde PowerShell nunca expande variáveis.

Antes da v2.1.198, essa reescrita se aplicava apenas a hooks de plugin. Em versões anteriores, um hook settings.json precisa da forma $env: ou forma exec, onde ${CLAUDE_PROJECT_DIR} é substituído em cada elemento args independentemente de onde o hook está definido.

Não escreva a forma nua $CLAUDE_PROJECT_DIR em um hook do PowerShell. PowerShell a analisa como uma variável local indefinida e a resolve para $null, o que deixa o caminho do script sem seu prefixo de diretório raiz do projeto. Claude Code não reescreve essa forma; em vez disso, registra um aviso no log de depuração.

O exemplo abaixo mostra um hook settings.json que executa um script de projeto com a forma $env:, que funciona em todas as versões:

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

Debug de hooks

Detalhes de execução de hook são escritos no arquivo de log de debug. Inicie Claude Code com claude --debug-file <path> para escrever o log em um local conhecido, ou execute claude --debug e leia o log em ~/.claude/debug/<session-id>.txt. A flag --debug não imprime no terminal.

Por exemplo, um hook PostToolUse em Write cujo comando imprime hook-ran produz entradas como:

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

Para detalhes de correspondência de hook mais granulares, defina CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose para ver linhas de log adicionais como contagens de matcher de hook e correspondência de consulta.

Para troubleshooting de problemas comuns como hooks não disparando, Stop hooks que continuam bloqueando, ou erros de configuração, consulte Limitações e troubleshooting no guia. Para um passo a passo de diagnóstico mais amplo cobrindo /context, /doctor e precedência de configurações, consulte Debug your config.