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

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

Adiar uma chamada de ferramenta para mais tarde

"defer" é para integrações que executam claude -p como subprocesso e leem sua saída JSON, como um app do Agent SDK ou uma UI personalizada construída sobre o Claude Code. Ele permite que esse processo chamador pause o Claude em uma chamada de ferramenta, colete a entrada por meio da sua própria interface e retome de onde parou. O Claude Code respeita este valor somente no modo não interativo com a flag -p. Em sessões interativas, ele registra um aviso em log e ignora o resultado do hook.

A ferramenta AskUserQuestion é o caso típico: o Claude quer perguntar algo ao usuário, mas não há terminal para responder. Uma execução -p oferece AskUserQuestion somente quando tem um host de permissão, como uma ferramenta MCP que você passa com --permission-prompt-tool, então inicie a execução com um. O ciclo funciona assim:

1. O 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 chamador lê deferred_tool_use do resultado do SDK, apresenta a pergunta na sua própria UI e aguarda uma resposta.
4. O processo chamador executa claude -p --resume <session-id> com o mesmo host de permissão. A mesma chamada de ferramenta dispara o PreToolUse novamente.
5. O hook retorna permissionDecision: "allow" com a resposta em updatedInput. A ferramenta é executada e o Claude continua.

O campo deferred_tool_use carrega o id, o name e o input da ferramenta. O input são os parâmetros que o 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á timeout nem limite de novas tentativas. A sessão permanece no disco até que você a retome, sujeita à limpeza de retenção cleanupPeriodDays, que exclui os arquivos de sessão após 30 dias por padrão, seguindo as regras de limpeza 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 chamador controla quando interromper o loop, retornando eventualmente "allow" ou "deny" do hook.

"defer" só funciona quando o Claude faz uma única chamada de ferramenta no turno. Se o Claude fizer várias chamadas de ferramenta de uma vez, "defer" é ignorado com um aviso e a ferramenta prossegue pelo fluxo normal de permissões. A restrição existe porque a retomada só pode executar novamente uma ferramenta: não há como adiar uma chamada de um lote sem deixar as outras sem resolução.

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 que o hook seja disparado. Isso acontece quando um servidor MCP que fornecia a ferramenta não está conectado na sessão retomada. O payload deferred_tool_use ainda é incluído para que você possa identificar qual ferramenta ficou ausente.

PermissionRequest

É executado quando o Claude Code está prestes a pedir sua permissão para usar uma ferramenta. Em sessões que não podem mostrar um prompt, como subagentes em segundo plano no modo não interativo, o Claude Code ainda executa esses hooks e, se nenhum hook retornar uma decisão, ele nega a chamada de ferramenta. Para uma chamada que chega a um --permission-prompt-tool ou ao callback canUseTool do Agent SDK, os hooks são executados junto com o seu host, e o que decidir primeiro se aplica. Use o controle de decisão do PermissionRequest para permitir ou negar em nome do usuário.

Use este evento quando precisar de um sinal no momento em que o Claude pede permissão para usar uma ferramenta. O Claude Code executa um hook Notification com o tipo permission_prompt somente depois que o prompt esperou cerca de seis segundos.

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

Faz a correspondência com o nome da ferramenta, com os mesmos valores do PreToolUse.

Entrada do PermissionRequest

Os hooks PermissionRequest recebem os campos tool_name e tool_input como os hooks PreToolUse, mas sem tool_use_id. Para uma ferramenta MCP, eles também recebem o objeto mcp_server. Um array opcional permission_suggestions contém as atualizações de permissão que o Claude Code sugere para esta solicitação, como adicionar uma regra allow 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 monta suas próprias opções. Alguns diálogos, como o de edições de arquivos, não leem o array de forma alguma e derivam suas opções da própria solicitação. Um diálogo que o lê ainda pode omitir uma opção cuja sugestão permanece no array, por exemplo quando allowManagedPermissionRulesOnly oculta as opções de salvar regras. 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 por meio de uma atualização de permissão.

Os hooks PreToolUse são executados antes de cada chamada de ferramenta, precise ela de permissão ou não. Os hooks PermissionRequest são executados somente quando o Claude Code está prestes a pedir sua permissão, ou quando, de outra forma, ele negaria automaticamente uma chamada que não pode exibir um prompt. Nenhum dos dois eventos é 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 do 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 estes campos específicos do evento:

Um hook que sai com 2 sem um objeto decision deixa o fluxo de permissões inalterado, e seu stderr é descartado. Somente 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 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 alteração é gravada.

O campo destination em cada entrada determina se a alteração permanece na memória ou é persistida 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.

Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.

Faça uma correspondência mais ampla quando o nome da ferramenta não for o filtro adequado:

• 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 por conta própria o que mudou, por exemplo executando git status --porcelain, que também lista arquivos não rastreados que o git diff não mostra. Para chamadas de ferramenta que falham, adicione o mesmo hook em PostToolUseFailure.
• Para executar um hook quando um arquivo específico muda no disco, independentemente de quem o gravou, use FileChanged. O Claude Code não executa um hook PostToolUse que corresponde a Edit|Write quando um comando Bash ou um processo fora do Claude Code reescreve o mesmo arquivo.

Entrada do PostToolUse

Os hooks PostToolUse são disparados depois que uma ferramenta já foi executada com sucesso. A entrada inclui tanto tool_input, os argumentos enviados à ferramenta, quanto tool_response, o resultado que ela retornou. O esquema exato de ambos depende da ferramenta. Os caminhos em tool_input de ferramentas de arquivo chegam no mesmo formato que em PreToolUse: sempre absolutos, com os separadores nativos da plataforma, portanto barras invertidas no Windows. Para uma ferramenta MCP, a entrada também inclui 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 do 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 estes campos específicos do evento:

O exemplo abaixo substitui a saída de uma chamada Bash. O valor de substituição corresponde ao formato 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 do modo auto

Retorne classifierContext para enviar uma nota curta sobre o resultado da chamada de ferramenta ao classificador do modo auto, e não ao Claude. O classificador nunca recebe os próprios resultados das ferramentas, então este campo é a forma suportada de informá-lo sobre o que uma chamada retornou antes que ele revise ações posteriores. O campo requer Claude Code v2.1.236 ou posterior.

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

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

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

• Hooks configurados no Claude Code: para hooks de arquivos de configurações, plugins, skills e frontmatter de agentes, o classificador trata a nota como contexto não verificado fornecido pela aplicação. A nota nunca estabelece a intenção do usuário e, se afirmar que você aprovou ou solicitou algo, o classificador verifica essa afirmação com base nas suas próprias mensagens na conversa
• Callbacks in-process do Agent SDK: quando uma aplicação que incorpora o Claude Code registra o hook como um callback do TypeScript SDK e retorna a nota durante a sessão ativa, o classificador pode considerar uma declaração do usuário repassada na nota como intenção do usuário. Tal declaração pode satisfazer um requisito de consentimento que o classificador aceitaria de uma mensagem enviada por você, mas nunca remove um bloqueio que sua própria mensagem também não conseguiria remover. Depois que uma sessão é retomada, o Claude Code trata as 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

O Claude Code aplica estes limites ao entregar a nota:

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

PostToolUseFailure

É executado quando uma ferramenta que começou a ser executada falha: a ferramenta lançou um erro ou uma ferramenta MCP retornou um resultado de erro. Use-o para registrar falhas em log, enviar alertas ou fornecer feedback corretivo ao Claude.

Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.

Entrada do PostToolUseFailure

Os hooks PostToolUseFailure recebem os mesmos campos tool_name e tool_input que o 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 com falha 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 o Claude recebe como resultado da ferramenta que falhou. Seu formato varia conforme a ferramenta e a falha. Baseie seu hook em tool_name, is_interrupt e na primeira linha Exit code N; trate o restante da string como texto de exibição, não como um formato estável.

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

Controle de decisão do 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 estes campos específicos do evento:

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

PostToolBatch

É executado uma vez depois que todas as chamadas de ferramenta de um lote foram resolvidas, antes de o Claude Code enviar a próxima requisição ao modelo. PostToolUse é disparado uma vez por ferramenta, o que significa que é disparado simultaneamente quando o Claude faz chamadas de ferramenta em paralelo. PostToolBatch é disparado exatamente uma vez com o lote completo, portanto é o lugar certo para injetar contexto que depende do conjunto de ferramentas executadas, e não de uma única ferramenta. Não há matcher para este evento.

Entrada do PostToolBatch

Além dos campos de entrada comuns, os hooks PostToolBatch recebem tool_calls, um array que descreve 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\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

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

Controle de decisão do PostToolBatch

Os hooks PostToolBatch podem injetar contexto para o Claude. Além dos campos de saída JSON disponíveis para todos os hooks, seu script de hook pode retornar estes 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 interrompe o loop agêntico antes da próxima chamada ao modelo. A mensagem de bloqueio vem do reason ou stopReason do JSON, ou do stderr no código de saída 2. Você a vê como um aviso na transcrição, e ela permanece na conversa, então o Claude a vê quando a conversa continua.

PermissionDenied

É executado quando o modo auto nega uma chamada de ferramenta, inclusive quando nega sem um veredito do classificador porque uma verificação de segurança separada do modo auto recusou a própria requisição do classificador ou porque a resposta dele não pôde ser analisada. Este hook só é disparado no modo auto: ele não é executado quando você nega manualmente uma caixa de diálogo de permissão, quando um hook PreToolUse bloqueia uma chamada ou quando uma regra deny corresponde. Use-o para registrar negações em log, ajustar a configuração ou informar ao modelo que ele pode tentar novamente a chamada de ferramenta.

Faz correspondência pelo nome da ferramenta, com os mesmos valores de PreToolUse.

Entrada do 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 do PermissionDenied

Os hooks PermissionDenied podem informar ao modelo que ele 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, o Claude Code adiciona uma mensagem à conversa informando ao modelo que ele pode tentar novamente a chamada de ferramenta. O próprio Claude Code não reverte a negação. Se o seu hook não retornar JSON, ou retornar retry: false, a negação se mantém e o modelo recebe a mensagem de rejeição original.

O Claude Code ignora retry: true quando o classificador não produziu nenhum veredito sobre a ação: sua resposta não pôde ser analisada, ou uma verificação de segurança separada do modo auto recusou a própria requisição do classificador. Para essas negações, o Claude Code já informa ao modelo, na mensagem de rejeição, se deve tentar novamente mais tarde ou seguir em frente.

Notification

É executado quando o Claude Code envia notificações. Faz correspondência pelo 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 as notificações da área de trabalho desativadas: a configuração preferredNotifChannel, incluindo notifications_disabled, altera apenas como você é alertado, não se o seu hook é executado.

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 requisição de rede de um comando em sandbox requer Claude Code v2.1.246 ou posterior.

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

O Claude Code cronometra permission_prompt de forma diferente em sessões nas quais envia solicitações de permissão ao callback canUseTool do Agent SDK, que é como o Claude Desktop e a extensão do VS Code hospedam o Claude Code:

• Espere permission_prompt cerca de seis segundos depois que o Claude pede permissão. O Claude Code não o adia enquanto você digita.
• Se você ou um hook PermissionRequest responder antes, o 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 handlers diferentes dependendo do tipo de notificação. Esta configuração aciona um script de alerta específico de permissão quando o Claude precisa de aprovação de permissão e uma notificação diferente quando o Claude está ocioso:

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

Além dos campos de entrada comuns, os hooks Notification recebem message com o texto da 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 nem modificar notificações. O Claude Code descarta seus campos systemMessage e continue, mas ainda emite terminalSequence, que é o que o exemplo de notificação da área de trabalho utiliza. Os hooks Notification destinam-se a efeitos colaterais, como encaminhar a notificação para um serviço externo.

SubagentStart

É executado quando o Claude cria um subagente com a ferramenta Agent, quando o Claude retoma um subagente e sempre que um colega de uma equipe de agentes in-process processa uma nova mensagem. Suporta matchers para filtrar pelo nome do tipo de agente. Para agentes integrados, é o nome do agente, como general-purpose, Explore ou Plan. Para subagentes personalizados, é o campo name do frontmatter do agente, não o nome do arquivo.

Para subagentes fornecidos por um plugin, o tipo de agente é o identificador com escopo de plugin, como my-plugin:reviewer, não o nome simples do frontmatter. Os dois-pontos colocam um nome com escopo de plugin no caminho de expressão regular, portanto ancore o matcher com ^ e $ para uma correspondência exata: ^my-plugin:reviewer$.

Entrada do SubagentStart

Além dos campos de entrada comuns, os hooks SubagentStart recebem agent_id com o identificador único do subagente e agent_type com o nome do agente pelo qual 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 subagentes, 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, o Claude Code injeta o contexto retornado somente quando o contexto do subagente ainda não contém a cópia de uma execução anterior. A cópia injetada na inicialização permanece no lugar, mantendo intacto o cache de prompt do subagente. Depois que a compactação automática descarta essa cópia, o Claude Code injeta novamente o contexto da próxima execução.

SubagentStop

É executado quando um subagente do Claude Code termina de responder. Faz correspondência pelo tipo de agente, com os mesmos valores de SubagentStart.

Entrada do 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 a filtragem do matcher. O transcript_path é a transcrição da sessão principal, enquanto agent_transcript_path é a transcrição do próprio subagente, armazenada em uma pasta aninhada subagents/. O campo last_assistant_message contém o conteúdo de texto da resposta final do subagente, para que os hooks possam acessá-lo sem analisar o arquivo de transcrição.

Nem todo evento SubagentStop vem de um subagente criado pelo Claude. O Claude Code também executa agentes internos para alguns de seus próprios recursos, como sugestões de prompt e perguntas paralelas com /btw, e o SubagentStop também é disparado quando um deles termina. Para esses eventos, agent_type é o nome do agente com o qual a própria sessão é executada, como um definido com --agent ou com 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, também é executado para eventos com agent_type vazio.

No Claude Code v2.1.271 ou posterior, um subagente executado com a ferramenta SubagentHandback entrega seu relatório por meio dessa ferramenta antes de parar. O campo last_assistant_message passa então a conter o texto final 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 com correspondência em SubagentHandback recebe como tool_input.message.

Os hooks SubagentStop também recebem os arrays background_tasks e session_crons descritos em Entrada do Stop. Ambos os arrays têm escopo na sessão pai, não no 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 dos hooks Stop, incluindo hookSpecificOutput.additionalContext com hookEventName definido como "SubagentStop", para feedback que não é de erro e 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 saindo com código 2 entrega sua mensagem de stderr da mesma forma. Para injetar contexto na sessão pai depois que um subagente retorna, use um hook PostToolUse na ferramenta Agent.

TaskCreated

É executado quando uma tarefa está sendo criada por meio da ferramenta TaskCreate. Use-o para impor convenções de nomenclatura, exigir descrições de tarefas ou impedir que determinadas 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 todas as ocorrências.

Entrada do 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 do TaskCreated

Um hook TaskCreated pode bloquear a criação de duas formas. Em ambos os casos, o Claude Code exclui a tarefa e retorna sua mensagem ao Claude como o erro da ferramenta. O Claude Code ignora continue: false deste evento e o Claude continua trabalhando.

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

Este exemplo bloqueia tarefas cujos assuntos não seguem o formato exigido:

#!/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 por meio da ferramenta TaskUpdate, ou quando um colega de uma equipe de agentes termina seu turno com tarefas em andamento. Use-o para impor critérios de conclusão, como testes ou verificações de lint aprovados, antes que uma tarefa possa ser fechada.

Os hooks TaskCompleted não suportam matchers e são disparados em todas as ocorrências.

Entrada do 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 do TaskCompleted

Os hooks TaskCompleted suportam duas formas de controlar a conclusão de tarefas:

• Código de saída 2: a tarefa não é marcada como concluída e a mensagem de stderr é devolvida ao modelo como feedback.
• JSON {"continue": false, "stopReason": "..."}: quando um colega de equipe que termina seu turno acionou o evento, interrompe o colega completamente, correspondendo ao comportamento do hook Stop. O stopReason é mostrado ao usuário. Quando a ferramenta TaskUpdate acionou o evento, o 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 eles 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 principal do Claude Code termina 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 do 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 o Claude Code já está continuando como resultado de um hook de parada. Verifique esse valor ou processe a transcrição para evitar bloquear com base em uma condição que nunca será resolvida. O Claude Code aplica um limite de 8 continuações consecutivas: depois que os hooks de parada continuaram o turno oito vezes seguidas, o Claude Code sobrescreve o próximo bloqueio e encerra o turno. Para aumentar o limite, defina CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

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

Os arrays background_tasks e session_crons permitem que os hooks distingam "a sessão terminou" de "a sessão está pausada aguardando que um trabalho em segundo plano a desperte novamente". Ambos os arrays estão presentes quando o registro de tarefas está acessível e ficam vazios quando não há nada em andamento ou agendado.

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

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

Este exemplo mostra uma entrada de Stop com uma tarefa de shell em andamento 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 do Stop

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

Um hook que bloqueia saindo com código 2 é encaminhado da mesma forma que reason: o Claude recebe a mensagem de 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 fornecendo orientação ao Claude, como "execute a suíte de testes antes de terminar". Ele mantém a conversa em andamento com as mesmas proteções contra loop de decision: "block", ou seja, a entrada stop_hook_active e o limite de 8 continuações consecutivas, mas a transcrição o 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. O Claude Code ignora a saída e o código de saída do hook, exceto terminalSequence. Use-o para registrar falhas em log, enviar alertas ou tomar ações de recuperação quando o Claude não consegue concluir uma resposta devido a rate limits, problemas de autenticação ou outros erros de API.

Entrada do 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 a filtragem do 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 log.

TeammateIdle

É executado quando um colega de uma equipe de agentes está prestes a ficar ocioso após terminar seu turno. Use-o para impor critérios de qualidade antes que um colega pare de trabalhar, como exigir verificações de lint aprovadas ou verificar se os arquivos de saída existem.

Os hooks TeammateIdle não suportam matchers e são disparados em todas as ocorrências.

Entrada do 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 do TeammateIdle

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

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

Este exemplo verifica se um artefato de build existe antes de permitir que um colega fique ocioso:

#!/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-o para auditar alterações de configurações, impor políticas de segurança ou bloquear modificações não autorizadas em arquivos de configuração.

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 somente quando managed-settings.json ou um arquivo em managed-settings.d/ muda. Ele aplica configurações gerenciadas pelo servidor e alterações nas preferências gerenciadas do macOS ou na política do registro do Windows sem executá-los. No WSL com wslInheritsWindowsSettings, ele também aplica um arquivo de configurações gerenciadas alterado do lado do Windows em sua verificação periódica de política sem executá-los.

O matcher filtra pela origem da configuração:

Este exemplo registra em log todas as alterações 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 do 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 do 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 do ConfigChange

Os hooks ConfigChange podem impedir que alterações de configuração entrem em vigor. Use o código de saída 2 ou um decision em JSON para impedir a alteração. Quando bloqueadas, 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 alterações de policy_settings não podem ser bloqueadas. Os hooks ainda são disparados para origens policy_settings quando um arquivo de configurações gerenciadas na máquina muda, então você pode usá-los para registrar essas edições em log, mas qualquer decisão de bloqueio é ignorada. Isso garante que as configurações gerenciadas pela empresa sempre entrem em vigor. O Claude Code não executa hooks ConfigChange quando configurações gerenciadas pelo servidor chegam ou são atualizadas.

O Claude Code age com base na decisão de bloqueio da saída JSON de um hook ConfigChange e descarta systemMessage e continue. Uma alteração bloqueada não exibe nenhuma mensagem para você nem para o Claude, seja o bloqueio feito com reason ou com stderr no código de saída 2. O Claude Code apenas grava uma linha no log de depuração.

CwdChanged

É executado quando um comando de shell na conversa principal altera o diretório de trabalho, por exemplo quando o Claude executa um comando cd. Use-o 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. Funciona em conjunto com FileChanged para ferramentas como direnv que gerenciam o ambiente por diretório.

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

O CwdChanged não suporta matchers e é disparado em todas as ocorrências.

Entrada do 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 do 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 o FileChanged monitora:

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

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

DirectoryAdded

É executado depois que você adiciona um diretório de trabalho no meio da sessão com o comando /add-dir, ou depois que um cliente SDK adiciona um com a requisição de controle register_repo_root. Use-o para preparar um repositório recém-adicionado, por exemplo instalando suas dependências.

O Claude Code não dispara este evento quando:

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

O Claude Code dispara o DirectoryAdded depois de atualizar o estado do sandbox e das permissões, então as ferramentas em sandbox já veem o novo diretório quando seu hook é executado. Os próprios comandos de hook são executados fora do sandbox.

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

O matcher filtra pela forma como o diretório foi adicionado:

Entrada do 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. O Claude Code descarta o campo continue da saída JSON deles e apresenta o restante de forma diferente conforme a origem:

• slash_command: o Claude Code entrega o systemMessage do hook ao Claude como contexto no próximo turno da conversa, em vez de mostrá-lo a você. Uma contagem de hooks com falha aparece na transcrição. A saída completa das falhas vai para o log de depuração
• register_repo_root: o Claude Code grava a saída de systemMessage e a saída de falhas somente no log de depuração

FileChanged

É executado quando um arquivo monitorado muda no disco. O Claude Code detecta alterações com um monitor do sistema de arquivos, não inspecionando chamadas de ferramenta, portanto executa o hook independentemente do que alterou o arquivo: uma chamada de ferramenta Edit ou Write, um script que o Claude executa com Bash ou um processo totalmente fora do Claude Code. Um uso comum é recarregar variáveis de ambiente quando arquivos de configuração do projeto mudam.

O matcher deste evento tem duas funções:

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

Este exemplo normaliza as terminações de linha em data.csv após qualquer alteração, incluindo um comando Bash ou um script externo que reescreve 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 no stdin. Sua proteção com grep testa a mesma coisa que o perl remove, um CR no final de uma linha, portanto a execução após uma normalização termina sem tocar no arquivo. Uma proteção menos rigorosa entra em loop para sempre, porque perl -i reescreve o arquivo mesmo quando não substitui nada, e o 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 acrescentar uma linha CRLF a data.csv com um comando Bash. O Claude Code executa o hook e o arquivo fica com terminações LF.

Para monitorar arquivos que você não pode nomear de antemão, retorne watchPaths de um hook para atualizar a lista de monitoramento dinamicamente. O Claude Code inicia o monitor somente quando algo nomeia um arquivo a ser monitorado, então inicialize a lista com um grupo FileChanged cujo matcher nomeie pelo menos um arquivo, ou com um hook SessionStart ou CwdChanged que retorne watchPaths. O matcher ainda filtra quais grupos de hooks são executados quando um arquivo monitorado muda, então dê ao grupo que lida com caminhos dinâmicos um matcher omitido, que corresponde a todos os arquivos monitorados e não adiciona nada à lista de monitoramento. Um matcher "*" também corresponde a todos os arquivos, mas o Claude Code o registra na lista de monitoramento como qualquer outro valor, como um arquivo literal chamado *.

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

Entrada do 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 do 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 monitorados:

Os hooks FileChanged não têm controle de decisão. Eles não podem impedir que a alteração do arquivo ocorra.

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

WorktreeCreate

É executado quando um worktree está sendo criado, seja a partir de claude --worktree, de um subagente usando isolation: "worktree" ou para uma sessão em segundo plano que o Claude Code isola em seu próprio worktree. Por padrão, o Claude Code cria a cópia de trabalho isolada com git worktree. Configurar um hook WorktreeCreate substitui esse comportamento padrão do git, 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 por completo, .worktreeinclude não é processado. Se você precisar copiar arquivos de configuração locais como .env para o novo worktree, faça isso dentro do seu script de hook.

O hook deve retornar o caminho do diretório do worktree criado. O Claude Code usa esse caminho como o diretório de trabalho da sessão isolada. Consulte Saída do WorktreeCreate para ver como cada tipo de hook retorna o caminho.

O Claude Code age com base 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 o Claude Code usar. Substitua a URL do repositório pela sua:

{
  "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 do worktree da entrada JSON no stdin, faz checkout de uma cópia nova em um novo diretório e imprime o caminho do diretório. O echo na última linha é o que o Claude Code lê como o caminho do worktree. Redirecione qualquer outra saída para o stderr para que ela não interfira no caminho.

Entrada do WorktreeCreate

Além dos campos de entrada comuns, os hooks WorktreeCreate recebem o campo name. Ele é um identificador slug para o novo worktree, especificado pelo usuário ou gerado automaticamente, 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 do WorktreeCreate

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

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

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

O Claude Code resolve um caminho relativo em relação ao diretório em que o hook foi executado, eliminando quaisquer segmentos . ou .. nele. Se o caminho resultante não for um diretório em que o Claude Code possa entrar, a sessão imprime um erro com o nome do caminho e encerra com o código 1.

O Claude Code recusa um caminho absoluto que contenha segmentos . ou .., e qualquer caminho que passe por um link simbólico abaixo da raiz do repositório, porque um link simbólico commitado no repositório poderia redirecionar o worktree para fora dele. O erro indica o componente rejeitado. Retorne um caminho normalizado que não passe por um link simbólico dentro do repositório. Antes da v2.1.216, a criação do worktree seguia o caminho do hook sem essa verificação.

WorktreeRemove

É executado quando um worktree está sendo removido. Este é o equivalente de limpeza do WorktreeCreate. O evento é disparado quando:

• você sai de uma sessão --worktree e escolhe removê-lo
• um subagente com isolation: "worktree" termina
• você exclui uma sessão em segundo plano cujo worktree foi criado pelo hook

Para worktrees baseados em git, o Claude Code lida com a limpeza automaticamente com git worktree remove. Se você configurou um hook WorktreeCreate, combine-o com um hook WorktreeRemove para controlar a limpeza dos worktrees que ele cria:

• Sem hook WorktreeRemove: quando você sai de uma sessão --worktree e escolhe a remoção, o Claude Code recorre a git worktree remove --force no caminho que seu hook WorktreeCreate retornou, de modo que um worktree que o git reconhece é removido. Um worktree que o git não reconhece, por exemplo, um que seu hook criou com um sistema de controle de versão que não seja git, permanece no disco. Para saber o que a exclusão de uma sessão em segundo plano faz com um worktree criado por hook, consulte as regras de exclusão da visualização de agentes.
• O hook encerra com 0: o worktree é considerado removido. O Claude Code não lê mais nada do hook, então certifique-se de que seu hook excluiu o diretório.
• O hook encerra com código diferente de zero: a remoção falha se o diretório em worktree_path ainda existir depois, e o worktree permanece no disco sem fallback do git. Um hook que excluiu o diretório antes de encerrar com código diferente de zero é considerado como tendo removido o worktree. Para saber como a falha é relatada, consulte Entrada do WorktreeRemove.

O Claude Code nunca exclui um branch pertencente a um worktree criado por hook, porque ele conhece apenas o caminho que seu hook WorktreeCreate retornou. Se seu hook WorktreeCreate criar um branch, exclua-o no seu hook WorktreeRemove.

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

Para a exclusão de uma sessão em segundo plano, o Claude Code verifica o caminho do worktree armazenado antes de executar o hook e recusa um caminho que seja um link simbólico ou que passe por um abaixo da raiz do repositório. O hook é executado para um worktree que ainda contém arquivos somente quando você confirma a exclusão na visualização de agentes; para um worktree assim, claude rm mantém a sessão e o worktree. Antes da v2.1.216, o hook era executado no caminho armazenado sem essas verificações.

O Claude Code passa o caminho retornado pelo 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 do WorktreeRemove

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

{
  "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 encerra com código diferente de zero e o diretório em worktree_path ainda existe depois, a remoção falha:

• O worktree permanece no disco, e o comando e o stderr do hook 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 na visualização de agentes informa como o hook terminou, como exited 1, cita o início do seu stderr e diz se excluir a sessão novamente remove o diretório mesmo assim.

PreCompact

É executado antes de o Claude Code executar uma operação de compactação.

O valor do matcher indica se a compactação foi acionada manual ou automaticamente:

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

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

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

Entrada do 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 depois que o Claude Code conclui uma operação de compactação. Use este evento para reagir ao novo estado compactado, por exemplo, para registrar em log o resumo gerado ou atualizar um estado externo. O Claude Code descarta os campos systemMessage e continue de um hook PostCompact.

Os mesmos valores de matcher do PreCompact se aplicam:

Entrada do PostCompact

Além dos campos de entrada comuns, os hooks PostCompact recebem trigger e compact_summary. O campo compact_summary contém o resumo da 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 o Claude Code aplicar uma troca de modelo que você ou um cliente solicitou. Use-o para bloquear uma troca, exigir confirmação ou mostrar quanto a troca vai custar antes que ela aconteça.

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

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

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

O Claude Code compara o matcher com o nome canônico do modelo para o qual a sessão está trocando, ignorando qualquer sufixo [1m]. Um alias como opus, um ID de modelo com data e um ID específico de provedor, como um ID de modelo do Amazon Bedrock, correspondem todos ao único nome canônico para o qual são resolvidos, então claude-opus-5 abrange todas as grafias do Opus 5.

Quando o Claude Code não consegue determinar um nome canônico para o destino, por exemplo, um ID de modelo personalizado que somente o seu gateway de LLM conhece, ele executa todos os hooks PreModelSwitch independentemente do matcher. Portanto, um hook que bloqueia deve verificar to_model em sua entrada em vez de depender apenas do 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 na entrada do hook, de modo que recusa uma troca para o Opus 4.6 encerrando com o código 2 e permite qualquer outro destino:

{
"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 em uma sessão que esteja usando um modelo diferente. O Claude Code mantém o modelo atual e informa que um hook PreModelSwitch bloqueou a troca, com a sua mensagem como motivo.

Entrada do PreModelSwitch

Além dos campos de entrada comuns, os hooks PreModelSwitch recebem os campos desta tabela. Os cinco últimos descrevem quanto custa reenviar a conversa para o novo modelo, para que um hook possa mostrar esse valor antes que a troca aconteça.

Este exemplo mostra a entrada para /model opus em uma sessão usando o 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 do PreModelSwitch

Os hooks PreModelSwitch podem cancelar a troca, pedir ao usuário que a confirme ou deixá-la prosseguir. O código de saída 2 ou um decision: "block" no nível superior cancela a troca.

Para um controle mais refinado, retorne permissionDecision e permissionDecisionReason em um objeto hookSpecificOutput, como no PreToolUse. O PreModelSwitch aceita "allow", "deny" e "ask". Ele não aceita "defer", updatedInput nem additionalContext. A tabela abaixo descreve ambos os campos:

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

Este exemplo pede ao usuário que confirme 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.

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

Um hook PreModelSwitch que não responde antes do seu timeout bloqueia a troca. No PreToolUse, por outro lado, um hook de comando que atingiu o timeout deixa a chamada de ferramenta continuar. O timeout padrão para este evento é de 30 segundos. O PreModelSwitch executa apenas hooks command, http e mcp_tool, então os padrões de prompt e agent não se aplicam.

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

PostModelSwitch

É executado depois que o modelo da sessão muda. Use-o para dar ao Claude orientações específicas do modelo sem editar cada CLAUDE.md, por exemplo, uma instrução para toda a organização que se aplica a determinados modelos.

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

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

O Claude Code não executa hooks PostModelSwitch quando um modelo de uma cadeia de modelos de fallback atende a um turno, porque essa substituição dura um turno e mantém o modelo da sessão inalterado.

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

Este exemplo adiciona orientações 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, troque para um modelo Opus a partir de uma sessão que esteja usando um modelo diferente, por exemplo, execute /model opus em uma sessão do Sonnet, e depois pergunte ao Claude quais orientações ele tem sobre o modelo atual.

Entrada do PostModelSwitch

Os hooks PostModelSwitch recebem os mesmos campos do PreModelSwitch, com hook_event_name definido como "PostModelSwitch" e mais dois valores de source: "auto" para um fallback automático ou outra mudança que o 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 o Claude Code restaurou.

Controle de decisão do PostModelSwitch

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

Se o hook não tiver terminado dentro de cinco segundos depois que você enviar o próximo prompt, o Claude Code envia essa requisição sem a saída e a anexa à requisição seguinte. Se o modelo mudar várias vezes antes da próxima requisição, o Claude Code entrega apenas a saída referente ao modelo de destino da última troca.

SessionEnd

É executado quando uma sessão do Claude Code termina. Útil para tarefas de limpeza, registro em log de estatísticas da sessão ou salvamento do estado da sessão. Suporta matchers para filtrar pelo motivo de saída.

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

Entrada do SessionEnd

Além dos campos de entrada comuns, os hooks SessionEnd recebem um campo reason indicando por que a sessão terminou. Consulte a tabela de motivos acima para ver 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 encerramento da sessão, mas podem executar tarefas de limpeza. O Claude Code descarta seus campos de saída JSON, como systemMessage.

Os hooks SessionEnd têm um timeout padrão de 1,5 segundo. Ele se aplica quando você sai, executa /clear ou troca de sessão com o /resume interativo. Você pode dar mais tempo a um hook de duas maneiras:

• timeout por hook: defina timeout na configuração desse hook. O orçamento geral aumenta automaticamente para corresponder ao maior timeout por hook nos seus arquivos de configuração, até 60 segundos. Se você aumentar o orçamento dessa forma, um hook sem seu próprio timeout ainda mantém o padrão. Timeouts definidos em hooks fornecidos por plugins 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 timeout de cada hook sem seu próprio timeout.

Este exemplo define o orçamento como 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 segundo.

Elicitation

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

O campo matcher é comparado com o nome do servidor MCP.

Entrada do Elicitation

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

Para elicitação no 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 no 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 do Elicitation

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

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

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

O Claude Code age com base no hookSpecificOutput da saída JSON de um hook Elicitation e descarta systemMessage e continue.

ElicitationResult

É executado depois que um usuário responde a uma elicitação MCP. Os hooks podem observar, modificar ou bloquear a resposta antes que ela seja enviada de volta ao servidor MCP.

O campo matcher é comparado com o nome do servidor MCP.

Entrada do ElicitationResult

Além dos campos de entrada comuns, os hooks ElicitationResult recebem mcp_server_name, action e os 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 do ElicitationResult

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

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

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

O Claude Code age com base no 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, por padrão aquele que Claude Code usa para funcionalidade em segundo plano
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. 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.

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::

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