10 Para um guia de início rápido com exemplos, consulte [Automatizar ações com hooks](/docs/pt/hooks-guide).10 Para um guia de início rápido com exemplos, consulte [Automatizar ações com hooks](/docs/pt/hooks-guide).
11</Tip>11</Tip>
12 12
13Hooks são comandos shell definidos pelo usuário, endpoints HTTP ou prompts LLM que executam automaticamente em pontos específicos do ciclo de vida do Claude Code. Use esta referência para consultar esquemas de eventos, opções de configuração, formatos de entrada/saída JSON e recursos avançados como hooks assíncronos, hooks HTTP e hooks de ferramentas MCP. Se você está configurando hooks pela primeira vez, comece com o [guia](/docs/pt/hooks-guide) em vez disso.13Hooks são comandos shell definidos pelo usuário, endpoints HTTP, chamadas de ferramentas MCP, prompts LLM ou subagentos que executam automaticamente em pontos específicos do ciclo de vida do Claude Code. O Claude Code dispara os mesmos eventos de hook onde quer que seja executado: sessões no terminal, extensões de IDE, o [aplicativo Desktop](/docs/pt/desktop-quickstart) e [Claude Code na web](/docs/pt/claude-code-on-the-web). Use esta referência para consultar esquemas de eventos, opções de configuração, formatos de entrada/saída JSON e recursos avançados como hooks assíncronos, hooks HTTP e hooks de ferramentas MCP.
14 14
15<h2 id="hook-lifecycle">15<h2 id="hook-lifecycle">
16 Ciclo de vida do hook16 Ciclo de vida do hook
17</h2>17</h2>
18 18
19Hooks disparam em pontos específicos durante uma sessão do Claude Code. Quando um evento dispara e um matcher corresponde, o Claude Code passa contexto JSON sobre o evento para seu manipulador de hook. Para hooks de comando, a entrada chega em stdin. Para hooks HTTP, chega como corpo da solicitação POST. Seu manipulador pode então inspecionar a entrada, tomar ação e opcionalmente retornar uma decisão.19Claude Code executa hooks em pontos específicos durante uma sessão. Quando um evento dispara e um matcher corresponde, Claude Code passa contexto JSON sobre o evento para seu manipulador de hook. Para hooks de comando, a entrada chega em stdin. Para hooks HTTP, chega como corpo da solicitação POST. Seu manipulador pode então inspecionar a entrada, tomar ação e opcionalmente retornar uma decisão.
20 20
21Os eventos caem em três cadências:21Os eventos caem em três cadências:
22 22
23* uma vez por sessão: `SessionStart` e `SessionEnd`23* por sessão: `SessionStart` e `SessionEnd`
24* uma vez por turno: `UserPromptSubmit`, `Stop` e `StopFailure`24* por turno: `UserPromptSubmit`, `Stop` e `StopFailure`
25* em cada chamada de ferramenta dentro do loop agentic: `PreToolUse` e `PostToolUse`25* em cada chamada de ferramenta dentro do loop agentic: `PreToolUse` e `PostToolUse`, exceto chamadas [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior), que pulam ambas
26 26
27<div style={{maxWidth: "500px", margin: "0 auto"}}>27<div style={{maxWidth: "500px", margin: "0 auto"}}>
28 <Frame>28 <Frame>
29 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=81b9256c1bbe8832553485f5d9e9c746" alt="Diagrama do ciclo de vida do hook mostrando Setup opcional alimentando SessionStart, depois um loop por turno contendo UserPromptSubmit, UserPromptExpansion para slash commands, o loop agentic aninhado (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted), e Stop ou StopFailure, seguido por TeammateIdle, PreCompact, PostCompact e SessionEnd, com Elicitation e ElicitationResult aninhados dentro da execução de ferramenta MCP, PermissionDenied como um ramo lateral de PermissionRequest para negações em modo automático, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged e FileChanged como eventos assíncronos independentes, e MessageDisplay como um evento somente de exibição que é executado enquanto o texto da mensagem do assistente é transmitido" width="520" height="1336" data-path="images/hooks-lifecycle.svg" />29 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=81b9256c1bbe8832553485f5d9e9c746" className="dark:hidden" alt="Diagrama do ciclo de vida do hook mostrando Setup opcional alimentando SessionStart, depois um loop por turno contendo UserPromptSubmit, UserPromptExpansion para slash commands, o loop agentic aninhado (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted), e Stop ou StopFailure, seguido por TeammateIdle, PreCompact, PostCompact e SessionEnd, com Elicitation e ElicitationResult aninhados dentro da execução de ferramenta MCP, PermissionDenied como um ramo lateral de PermissionRequest para negações em modo automático, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, FileChanged e DirectoryAdded como eventos assíncronos independentes, PreModelSwitch como um evento sequencial independente que é executado antes de uma mudança de modelo solicitada, PostModelSwitch como um evento assíncrono independente que é executado após as mudanças de modelo da sessão, e MessageDisplay como um evento somente de exibição que é executado enquanto o texto da mensagem do assistente é transmitido" width="520" height="1336" data-path="images/hooks-lifecycle.svg" />
30
31 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle-dark.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=c9b3d88487335f58cce0b52e2f9e7531" className="hidden dark:block" alt="Diagrama do ciclo de vida do hook mostrando Setup opcional alimentando SessionStart, depois um loop por turno contendo UserPromptSubmit, UserPromptExpansion para slash commands, o loop agentic aninhado (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted), e Stop ou StopFailure, seguido por TeammateIdle, PreCompact, PostCompact e SessionEnd, com Elicitation e ElicitationResult aninhados dentro da execução de ferramenta MCP, PermissionDenied como um ramo lateral de PermissionRequest para negações em modo automático, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, FileChanged e DirectoryAdded como eventos assíncronos independentes, PreModelSwitch como um evento sequencial independente que é executado antes de uma mudança de modelo solicitada, PostModelSwitch como um evento assíncrono independente que é executado após as mudanças de modelo da sessão, e MessageDisplay como um evento somente de exibição que é executado enquanto o texto da mensagem do assistente é transmitido" width="520" height="1336" data-path="images/hooks-lifecycle-dark.svg" />
30 </Frame>32 </Frame>
31</div>33</div>
32 34
33A tabela abaixo resume quando cada evento dispara. A seção [Eventos de hook](#hook-events) documenta o esquema de entrada completo e as opções de controle de decisão para cada um.35A tabela abaixo resume quando cada evento dispara. A seção [Eventos de hook](#hook-events) documenta o esquema de entrada completo e as opções de controle de decisão para cada um.
34 36
35| Event | When it fires |37| Evento | Quando dispara |
36| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |38| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37| `SessionStart` | When a session begins or resumes |39| `SessionStart` | Quando uma sessão começa ou é retomada |
38| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |40| `Setup` | Quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` no modo `-p`. Para preparação única em CI ou scripts |
39| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |41| `UserPromptSubmit` | Quando você envia um prompt, antes de Claude processá-lo |
40| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |42| `UserPromptExpansion` | Quando um comando digitado pelo usuário se expande em um prompt, antes de chegar a Claude. Pode bloquear a expansão |
41| `PreToolUse` | Before a tool call executes. Can block it |43| `PreToolUse` | Antes de uma chamada de ferramenta ser executada. Pode bloqueá-la |
42| `PermissionRequest` | When a tool call needs a permission decision |44| `PermissionRequest` | Quando uma chamada de ferramenta precisa de uma decisão de permissão |
43| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |45| `PermissionDenied` | Quando o modo automático nega uma chamada de ferramenta, incluindo negações sem um veredicto do classificador. Use JSON `hookSpecificOutput.retry: true` para informar ao modelo que ele pode tentar novamente a chamada de ferramenta negada. Claude Code ignora `retry` quando o classificador não produziu veredicto |
44| `PostToolUse` | After a tool call succeeds |46| `PostToolUse` | Depois que uma chamada de ferramenta é bem-sucedida |
45| `PostToolUseFailure` | After a tool call fails |47| `PostToolUseFailure` | Depois que uma chamada de ferramenta falha |
46| `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call |48| `PostToolBatch` | Depois que um lote completo de chamadas de ferramenta paralelas é resolvido, antes da próxima chamada do modelo |
47| `Notification` | When Claude Code sends a notification |49| `Notification` | Quando Claude Code envia uma notificação |
48| `MessageDisplay` | While assistant message text is displayed |50| `MessageDisplay` | Enquanto o texto da mensagem do assistente está sendo exibido |
49| `SubagentStart` | When a subagent is spawned |51| `SubagentStart` | Quando um subagente é criado |
50| `SubagentStop` | When a subagent finishes |52| `SubagentStop` | Quando um subagente termina |
51| `TaskCreated` | When a task is being created via `TaskCreate` |53| `TaskCreated` | Quando uma tarefa está sendo criada via `TaskCreate` |
52| `TaskCompleted` | When a task is being marked as completed |54| `TaskCompleted` | Quando uma tarefa está sendo marcada como concluída |
53| `Stop` | When Claude finishes responding |55| `Stop` | Quando Claude termina de responder |
54| `StopFailure` | When the turn ends due to an API error |56| `StopFailure` | Quando a rodada termina devido a um erro de API |
55| `TeammateIdle` | When an [agent team](/docs/en/agent-teams) teammate is about to go idle |57| `TeammateIdle` | Quando um colega de [equipe de agentes](/docs/pt/agent-teams) está prestes a ficar ocioso |
56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |58| `InstructionsLoaded` | Quando um arquivo CLAUDE.md ou `.claude/rules/*.md` é carregado no contexto. Dispara no início da sessão e quando os arquivos são carregados lentamente durante uma sessão |
57| `ConfigChange` | When a configuration file changes during a session |59| `ConfigChange` | Quando um arquivo de configuração muda durante uma sessão |
58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |60| `CwdChanged` | Quando o diretório de trabalho muda, por exemplo quando Claude executa um comando `cd`. Útil para gerenciamento reativo do ambiente com ferramentas como direnv |
59| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |61| `DirectoryAdded` | Quando um diretório de trabalho é adicionado no meio da sessão via `/add-dir` ou a solicitação de controle SDK `register_repo_root` |
60| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |62| `FileChanged` | Quando um arquivo observado muda no disco. O campo `matcher` especifica quais nomes de arquivo observar |
61| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |63| `WorktreeCreate` | Quando um worktree está sendo criado via `--worktree`, `isolation: "worktree"`, ou para uma sessão em segundo plano. Substitui o comportamento padrão do git |
62| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |64| `WorktreeRemove` | Quando um worktree está sendo removido na saída da sessão, quando um subagente termina, ou quando você exclui uma sessão em segundo plano |
63| `PreCompact` | Before context compaction |65| `PreCompact` | Antes da compactação de contexto |
64| `PostCompact` | After context compaction completes |66| `PostCompact` | Depois que a compactação de contexto é concluída |
65| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |67| `PreModelSwitch` | Antes de Claude Code aplicar uma mudança de modelo que você ou um cliente solicitou. Pode bloquear a mudança |
66| `PostModelSwitch` | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session |68| `PostModelSwitch` | Depois que o modelo da sessão muda, incluindo mudanças que Claude Code faz por conta própria, como restaurar o modelo quando você retoma uma sessão |
67| `Elicitation` | When an MCP server requests user input during a tool call |69| `Elicitation` | Quando um servidor MCP solicita entrada do usuário durante uma chamada de ferramenta |
68| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |70| `ElicitationResult` | Depois que um usuário responde a uma elicitação MCP, antes da resposta ser enviada de volta ao servidor |
69| `SessionEnd` | When a session terminates |71| `SessionEnd` | Quando uma sessão é encerrada |
70 72
71<h3 id="how-a-hook-resolves">73<h3 id="how-a-hook-resolves">
72 Como um hook é resolvido74 Como um hook é resolvido
73</h3>75</h3>
74 76
75Para ver como essas peças se encaixam, considere este hook `PreToolUse` que bloqueia comandos shell destrutivos. O `matcher` se restringe a chamadas de ferramenta Bash e a condição `if` se restringe ainda mais a subcomandos Bash correspondendo a `rm *`, então `block-rm.sh` apenas é gerado quando ambos os filtros correspondem:77Para ver como o evento, o matcher e o manipulador se encaixam, considere este hook `PreToolUse` que bloqueia comandos shell destrutivos.
76 78
77```json theme={null}79<Tabs>
78{80 <Tab title="macOS/Linux">
81 O `matcher` se restringe a chamadas de ferramenta Bash e a condição `if` se restringe ainda mais a subcomandos Bash correspondendo a `rm *`, então `block-rm.sh` apenas é gerado quando ambos os filtros correspondem:
82
83 ```json theme={null}
84 {
79 "hooks": {85 "hooks": {
80 "PreToolUse": [86 "PreToolUse": [
81 {87 {
91 }97 }
92 ]98 ]
93 }99 }
94}100 }
95```101 ```
96 102
97O script lê a entrada JSON de stdin, extrai o comando e retorna uma `permissionDecision` de `"deny"` se contiver `rm -rf`:103 O script lê a entrada JSON de stdin, extrai o comando e retorna uma `permissionDecision` de `"deny"` se contiver `rm -rf`. Salve-o em `.claude/hooks/block-rm.sh` em seu projeto e torne-o executável com `chmod +x .claude/hooks/block-rm.sh` para que Claude Code possa executá-lo:
98 104
99```bash theme={null}105 ```bash theme={null}
100#!/bin/bash106 #!/bin/bash
101# .claude/hooks/block-rm.sh107 # .claude/hooks/block-rm.sh
102COMMAND=$(jq -r '.tool_input.command')108 COMMAND=$(jq -r '.tool_input.command')
103 109
104if echo "$COMMAND" | grep -q 'rm -rf'; then110 if echo "$COMMAND" | grep -q 'rm -rf'; then
105 jq -n '{111 jq -n '{
106 hookSpecificOutput: {112 hookSpecificOutput: {
107 hookEventName: "PreToolUse",113 hookEventName: "PreToolUse",
109 permissionDecisionReason: "Destructive command blocked by hook"115 permissionDecisionReason: "Destructive command blocked by hook"
110 }116 }
111 }'117 }'
112else118 else
113 exit 0 # no decision; normal permission flow applies119 exit 0 # no decision; normal permission flow applies
114fi120 fi
115```121 ```
122
123 Este script, como os outros exemplos Bash nesta página que analisam entrada JSON, usa `jq`, então instale `jq` e certifique-se de que está em seu `PATH` antes de tentar executá-los.
124 </Tab>
125
126 <Tab title="Windows (PowerShell)">
127 O matcher `Bash|PowerShell` cobre a [ferramenta PowerShell](#powershell) bem como Bash. Uma única regra `if` corresponde apenas às chamadas de uma ferramenta, então cada ferramenta obtém seu próprio manipulador: o primeiro se restringe a subcomandos Bash correspondendo a `rm *`, o segundo a comandos PowerShell correspondendo a `Remove-Item *`. Ambos executam o mesmo script através de `powershell.exe`:
128
129 ```json theme={null}
130 {
131 "hooks": {
132 "PreToolUse": [
133 {
134 "matcher": "Bash|PowerShell",
135 "hooks": [
136 {
137 "type": "command",
138 "if": "Bash(rm *)",
139 "command": "powershell.exe",
140 "args": [
141 "-NoProfile",
142 "-ExecutionPolicy",
143 "Bypass",
144 "-File",
145 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
146 ]
147 },
148 {
149 "type": "command",
150 "if": "PowerShell(Remove-Item *)",
151 "command": "powershell.exe",
152 "args": [
153 "-NoProfile",
154 "-ExecutionPolicy",
155 "Bypass",
156 "-File",
157 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
158 ]
159 }
160 ]
161 }
162 ]
163 }
164 }
165 ```
166
167 A flag `-NoProfile` pula o carregamento de seu perfil PowerShell para que o hook inicie rapidamente, e `-ExecutionPolicy Bypass` permite que PowerShell execute o arquivo de script local.
116 168
117Agora suponha que o Claude Code decida executar `Bash "rm -rf /tmp/build"`. Aqui está o que acontece:169 O script lê a entrada JSON de stdin, extrai o comando e retorna uma `permissionDecision` de `"deny"` se contiver `rm -rf` ou `Remove-Item` seguido por `-Recurse`. Salve-o em `.claude/hooks/block-rm.ps1` em seu projeto:
170
171 ```powershell theme={null}
172 # .claude/hooks/block-rm.ps1
173 $callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
174 $command = $callInput.tool_input.command
175
176 if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
177 @{
178 hookSpecificOutput = @{
179 hookEventName = "PreToolUse"
180 permissionDecision = "deny"
181 permissionDecisionReason = "Destructive command blocked by hook"
182 }
183 } | ConvertTo-Json
184 } else {
185 exit 0 # no decision; normal permission flow applies
186 }
187 ```
188 </Tab>
189</Tabs>
190
191Agora suponha que Claude Code decida executar `Bash "rm -rf /tmp/build"` contra a configuração macOS/Linux. Aqui está o que acontece:
118 192
119<Frame>193<Frame>
120 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" alt="Diagrama de resolução de hook: PreToolUse dispara, o matcher verifica correspondência de Bash, então a condição if verifica correspondência de Bash(rm *). Se ambos corresponderem, o comando do hook é executado e retorna permissionDecision deny, então a chamada da ferramenta é bloqueada e o Claude Code continua. Se qualquer verificação falhar em corresponder, o hook é ignorado e a chamada da ferramenta é permitida prosseguir." width="930" height="270" data-path="images/hook-resolution.svg" />194 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" className="dark:hidden" alt="Diagrama de resolução de hook: PreToolUse dispara, o matcher verifica correspondência de Bash, então a condição if verifica correspondência de Bash(rm *). Se ambos corresponderem, o comando do hook é executado e retorna permissionDecision deny, então a chamada da ferramenta é bloqueada e Claude Code continua. Se qualquer verificação falhar em corresponder, o hook é ignorado e a chamada da ferramenta é permitida prosseguir." width="930" height="270" data-path="images/hook-resolution.svg" />
195
196 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/hook-resolution-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=e80af91f8507cee6bd51ac3c2dd92f63" className="hidden dark:block" alt="Diagrama de resolução de hook: PreToolUse dispara, o matcher verifica correspondência de Bash, então a condição if verifica correspondência de Bash(rm *). Se ambos corresponderem, o comando do hook é executado e retorna permissionDecision deny, então a chamada da ferramenta é bloqueada e Claude Code continua. Se qualquer verificação falhar em corresponder, o hook é ignorado e a chamada da ferramenta é permitida prosseguir." width="930" height="270" data-path="images/hook-resolution-dark.svg" />
121</Frame>197</Frame>
122 198
123<Steps>199<Steps>
124 <Step title="Evento dispara">200 <Step title="Evento dispara">
125 O evento `PreToolUse` dispara. O Claude Code envia a entrada da ferramenta como JSON em stdin para o hook:201 O evento `PreToolUse` dispara. Claude Code envia a entrada da ferramenta como JSON em stdin para o hook:
126 202
127 ```json theme={null}203 ```json theme={null}
128 { "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }204 { "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
154 </Step>230 </Step>
155 231
156 <Step title="Claude Code age sobre o resultado">232 <Step title="Claude Code age sobre o resultado">
157 O Claude Code lê a decisão JSON, bloqueia a chamada da ferramenta e mostra a razão ao Claude.233 Claude Code lê a decisão JSON, bloqueia a chamada da ferramenta e mostra a razão ao Claude.
158 </Step>234 </Step>
159</Steps>235</Steps>
160 236
183Onde você define um hook determina seu escopo:259Onde você define um hook determina seu escopo:
184 260
185| Local | Escopo | Compartilhável |261| Local | Escopo | Compartilhável |
186| :------------------------------------------------------------- | :------------------------------- | :---------------------------------------- |262| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------- |
187| `~/.claude/settings.json` | Todos os seus projetos | Não, local para sua máquina |263| `~/.claude/settings.json` | Todos os seus projetos | Não, local para sua máquina |
188| `.claude/settings.json` | Projeto único | Sim, pode ser confirmado no repositório |264| `.claude/settings.json` | Projeto único | Sim, pode ser confirmado no repositório |
189| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code o cria |265| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code salva uma configuração nele |
190| Configurações de política gerenciada | Organização inteira | Sim, controlado por administrador |266| Configurações de política gerenciada | Organização inteira | Sim, controlado por administrador |
191| [Plugin](/docs/pt/plugins) `hooks/hooks.json` | Quando o plugin está ativado | Sim, agrupado com o plugin |267| [Plugin](/docs/pt/plugins) `hooks/hooks.json` | Quando o plugin está ativado | Sim, agrupado com o plugin |
192| Frontmatter de [Skill](/docs/pt/skills) ou [agente](/docs/pt/sub-agents) | Enquanto o componente está ativo | Sim, definido no arquivo do componente |268| Frontmatter de [Skill](/docs/pt/skills) | O resto da sessão uma vez que a skill é invocada. Consulte [Hooks em skills e agentes](#hooks-in-skills-and-agents) | Sim, definido no arquivo da skill |
269| Frontmatter de [Subagent](/docs/pt/sub-agents) | Enquanto esse subagente está em execução | Sim, definido no arquivo do subagente |
270
271Sessões em nuvem em [Claude Code na web](/docs/pt/claude-code-on-the-web) não leem seu `~/.claude/settings.json` local; hooks lá vêm do repositório, significando seu `.claude/settings.json` em uma sessão com um repositório e os plugins que declara em qualquer sessão, e das configurações gerenciadas pelo servidor da sua organização. Em um [ambiente auto-hospedado](/docs/pt/self-hosted-environments-configuration#permissions-and-tool-approval), Claude Code também executa os hooks que o operador propagou do `~/.claude/` do host do runner, e executa os hooks no arquivo de configurações gerenciadas da imagem do runner quando esse arquivo está entre as [fontes gerenciadas que Claude Code aplica](/docs/pt/managed-settings#how-claude-code-combines-managed-sources), o que por padrão significa apenas quando nem configurações gerenciadas pelo servidor nem uma política Claude Code entregue por MDM fornece o nível gerenciado. Consulte [o que é transferido da sua configuração](/docs/pt/cloud-environments#what-carries-over-from-your-setup) para saber quais arquivos chegam a uma sessão em nuvem.
193 272
194Para detalhes sobre resolução de arquivo de configurações, consulte [configurações](/docs/pt/settings). Administradores corporativos podem usar `allowManagedHooksOnly` para bloquear hooks de usuário, projeto e plugin. Hooks de plugins forçadamente ativados em configurações gerenciadas `enabledPlugins` são isentos, para que administradores possam distribuir hooks verificados através de um marketplace de organização. Consulte [Configuração de hook](/docs/pt/settings#hook-configuration).273Para detalhes sobre resolução de arquivo de configurações, consulte [settings](/docs/pt/settings).
274
275Hooks de arquivos de configurações, configurações de política gerenciada e plugins também executam dentro de [subagentes](/docs/pt/sub-agents). Quando um subagente chama uma ferramenta, eventos de ferramenta como `PreToolUse` e `PostToolUse` disparam os mesmos hooks configurados que na conversa principal, e a entrada carrega os campos de entrada comuns `agent_id` e `agent_type` [](#common-input-fields) que identificam o subagente.
276
277Administradores corporativos podem usar `allowManagedHooksOnly` para restringir quais hooks executam:
278
279* Seus hooks de usuário, projeto, local e plugin são bloqueados. Hooks de plugins forçadamente ativados em configurações gerenciadas `enabledPlugins` são isentos
280* Claude Code também restringe suas configurações [`statusLine`](/docs/pt/statusline), [`fileSuggestion`](/docs/pt/settings-reference#filesuggestion) e [`subagentStatusLine`](/docs/pt/statusline#subagent-status-lines) às configurações gerenciadas
281* Claude Code também desabilita plugins com uma [fonte `command`](/docs/pt/plugin-marketplaces#command-sources), incluindo plugins forçadamente ativados em configurações gerenciadas `enabledPlugins`, a menos que [`disableCommandPluginSources`](/docs/pt/settings-reference#disablecommandpluginsources) seja explicitamente definido como `false`. Fontes `command` requerem Claude Code v2.1.229 ou posterior
282* Claude Code também bloqueia [comandos `headersHelper`](/docs/pt/plugin-marketplaces#authenticate-archive-downloads) do marketplace a menos que [`disableCommandPluginSources`](/docs/pt/settings-reference#disablecommandpluginsources) seja explicitamente definido como `false`, exceto para um marketplace que as próprias configurações gerenciadas declarem
283
284Consulte [o que executa sob `allowManagedHooksOnly`](/docs/pt/settings-reference#what-runs-under-allowmanagedhooksonly).
285
286Entradas de hook se mesclam entre níveis de configurações em vez de se substituírem: configurações de usuário, projeto e local adicionam seus próprios hooks sem remover os gerenciados, e a configuração [`disableAllHooks`](#disable-or-remove-hooks) não pode desabilitar hooks gerenciados de fora das configurações gerenciadas.
287
288As [listas de permissões de hook HTTP](/docs/pt/settings-reference#hook-and-skill-settings) se aplicam a hooks de todas as fontes, incluindo configurações de política gerenciada:
289
290* `allowedHttpHookUrls`: quando definido em qualquer nível de configurações, Claude Code executa um manipulador de hook HTTP apenas se sua URL corresponder à lista de permissões mesclada
291* `httpHookAllowedEnvVars`: quando definido, Claude Code interpola apenas as variáveis de ambiente nessa lista em cabeçalhos de hook
195 292
196<h3 id="matcher-patterns">293<h3 id="matcher-patterns">
197 Padrões de matcher294 Padrões de matcher
218Cada tipo de evento corresponde em um campo diferente:315Cada tipo de evento corresponde em um campo diferente:
219 316
220| Evento | O que o matcher filtra | Valores de matcher de exemplo |317| Evento | O que o matcher filtra | Valores de matcher de exemplo |
221| :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |318| :------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
222| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | nome da ferramenta | `Bash`, `Edit\|Write`, `mcp__.*` |319| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | nome da ferramenta | `Bash`, `Edit\|Write`, `mcp__.*` |
223| `SessionStart` | como a sessão começou | `startup`, `resume`, `clear`, `compact` |320| `SessionStart` | como a sessão começou | `startup`, `resume`, `clear`, `compact`, `fork` |
224| `Setup` | qual sinalizador CLI acionou a configuração | `init`, `maintenance` |321| `Setup` | qual sinalizador CLI acionou a configuração | `init`, `maintenance` |
225| `SessionEnd` | por que a sessão terminou | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |322| `SessionEnd` | por que a sessão terminou | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |
226| `Notification` | tipo de notificação | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |323| `Notification` | tipo de notificação | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` |
227| `SubagentStart` | tipo de agente | `general-purpose`, `Explore`, `Plan`, nomes de agentes personalizados ou nomes com escopo de plugin como `^my-plugin:reviewer$` |324| `SubagentStart` | tipo de agente | `general-purpose`, `Explore`, `Plan`, nomes de agentes personalizados ou nomes com escopo de plugin como `^my-plugin:reviewer$` |
228| `PreCompact`, `PostCompact` | o que acionou a compactação | `manual`, `auto` |325| `PreCompact`, `PostCompact` | o que acionou a compactação | `manual`, `auto` |
326| `PreModelSwitch`, `PostModelSwitch` | nome canônico do modelo para o qual a sessão muda, conforme descrito em [PreModelSwitch](#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |
229| `SubagentStop` | tipo de agente | mesmos valores que `SubagentStart` |327| `SubagentStop` | tipo de agente | mesmos valores que `SubagentStart` |
230| `ConfigChange` | fonte de configuração | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |328| `ConfigChange` | fonte de configuração | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |
231| `CwdChanged` | sem suporte a matcher | sempre dispara em cada mudança de diretório |329| `CwdChanged` | sem suporte a matcher | sempre dispara em cada ocorrência |
330| `DirectoryAdded` | como o diretório foi adicionado | `slash_command`, `register_repo_root` |
232| `FileChanged` | nomes de arquivo literais para monitorar (consulte [FileChanged](#filechanged)) | `.envrc\|.env` |331| `FileChanged` | nomes de arquivo literais para monitorar (consulte [FileChanged](#filechanged)) | `.envrc\|.env` |
233| `StopFailure` | tipo de erro | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` |332| `StopFailure` | tipo de erro | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, `unknown` |
234| `InstructionsLoaded` | razão de carregamento | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |333| `InstructionsLoaded` | razão de carregamento | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |
235| `UserPromptExpansion` | nome do comando | seus nomes de skill ou comando |334| `UserPromptExpansion` | nome do comando | seus nomes de skill ou comando |
236| `Elicitation` | nome do servidor MCP | seus nomes de servidor MCP configurados |335| `Elicitation` | nome do servidor MCP | seus nomes de servidor MCP configurados |
237| `ElicitationResult` | nome do servidor MCP | mesmos valores que `Elicitation` |336| `ElicitationResult` | nome do servidor MCP | mesmos valores que `Elicitation` |
238| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` | sem suporte a matcher | sempre dispara em cada ocorrência |337| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` | sem suporte a matcher | sempre dispara em cada ocorrência |
239 338
240O matcher executa contra um campo da [entrada JSON](#hook-input-and-output) que o Claude Code envia para seu hook em stdin. Para eventos de ferramenta, esse campo é `tool_name`. Cada seção [evento de hook](#hook-events) lista o conjunto completo de valores de matcher e o esquema de entrada para esse evento.339Corresponder `StopFailure` em `cloud_credential_error` requer Claude Code v2.1.267 ou posterior, a primeira versão que relata falhas de carregamento de credenciais sob esse valor em vez de `server_error` ou `unknown`.
340
341Para a maioria dos eventos, Claude Code avalia o matcher contra um campo da [entrada JSON](#hook-input-and-output) que envia para seu hook em stdin. Para eventos de ferramenta, esse campo é `tool_name`. Para `PreModelSwitch` e `PostModelSwitch`, Claude Code avalia o matcher contra o nome canônico que deriva de `to_model`, conforme descrito em [PreModelSwitch](#premodelswitch). Cada seção [evento de hook](#hook-events) lista o conjunto completo de valores de matcher e o esquema de entrada para esse evento.
241 342
242Este exemplo executa um script de linting apenas quando Claude escreve ou edita um arquivo:343Este exemplo executa um script de linting apenas quando Claude escreve ou edita um arquivo:
243 344
259}360}
260```361```
261 362
262`UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` e `CwdChanged` não suportam matchers e sempre disparam em cada ocorrência. Se você adicionar um campo `matcher` a esses eventos, ele é silenciosamente ignorado.363Se você adicionar um campo `matcher` a um evento sem suporte a matcher, ele é silenciosamente ignorado.
263 364
264Para eventos de ferramenta, você pode filtrar mais estreitamente definindo o campo [`if`](#common-fields) em manipuladores de hook individuais. `if` usa [sintaxe de regra de permissão](/docs/pt/permissions) para corresponder contra o nome da ferramenta e argumentos juntos, então `"Bash(git *)"` executa quando qualquer subcomando da entrada Bash corresponde a `git *` e `"Edit(*.ts)"` executa apenas para arquivos TypeScript.365Para eventos de ferramenta, você pode filtrar mais estreitamente definindo o campo [`if`](#common-fields) em manipuladores de hook individuais. `if` usa [sintaxe de regra de permissão](/docs/pt/permissions) para corresponder contra o nome da ferramenta e argumentos juntos, então `"Bash(git *)"` executa quando qualquer subcomando da entrada Bash corresponde a `git *` e `"Edit(*.ts)"` executa apenas para arquivos TypeScript.
265 366
323* **[Hooks de comando](#command-hook-fields)** (`type: "command"`): executam um comando shell. Seu script recebe a [entrada JSON](#hook-input-and-output) do evento em stdin e comunica resultados através de códigos de saída e stdout.424* **[Hooks de comando](#command-hook-fields)** (`type: "command"`): executam um comando shell. Seu script recebe a [entrada JSON](#hook-input-and-output) do evento em stdin e comunica resultados através de códigos de saída e stdout.
324* **[Hooks HTTP](#http-hook-fields)** (`type: "http"`): enviam a entrada JSON do evento como uma solicitação HTTP POST para uma URL. O endpoint comunica resultados através do corpo da resposta usando o mesmo [formato de saída JSON](#json-output) que hooks de comando.425* **[Hooks HTTP](#http-hook-fields)** (`type: "http"`): enviam a entrada JSON do evento como uma solicitação HTTP POST para uma URL. O endpoint comunica resultados através do corpo da resposta usando o mesmo [formato de saída JSON](#json-output) que hooks de comando.
325* **[Hooks de ferramenta MCP](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): chamam uma ferramenta em um servidor [MCP](/docs/pt/mcp) já conectado. A saída de texto da ferramenta é tratada como stdout de hook de comando.426* **[Hooks de ferramenta MCP](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): chamam uma ferramenta em um servidor [MCP](/docs/pt/mcp) já conectado. A saída de texto da ferramenta é tratada como stdout de hook de comando.
326* **[Hooks de prompt](#prompt-and-agent-hook-fields)** (`type: "prompt"`): enviam um prompt para um modelo Claude para avaliação de turno único. O modelo retorna uma decisão sim/não como JSON. Consulte [Hooks baseados em prompt](#prompt-based-hooks).427* **[Hooks de prompt](#prompt-and-agent-hook-fields)** (`type: "prompt"`): enviam um prompt para um modelo Claude para avaliação de turno único. O modelo retorna sua decisão como JSON. Consulte [Hooks baseados em prompt](#prompt-based-hooks).
327* **[Hooks de agente](#prompt-and-agent-hook-fields)** (`type: "agent"`): geram um subagente que pode usar ferramentas como Read, Grep e Glob para verificar condições antes de retornar uma decisão. Hooks de agente são experimentais e podem mudar. Consulte [Hooks baseados em agente](#agent-based-hooks).428* **[Hooks de agente](#prompt-and-agent-hook-fields)** (`type: "agent"`): geram um subagente que pode usar ferramentas como Read, Grep e Glob para verificar condições antes de retornar uma decisão. Hooks de agente são experimentais e podem mudar. Consulte [Hooks baseados em agente](#agent-based-hooks).
328 429
329Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL.430Todos os hooks correspondentes executam em paralelo. Se você definir o mesmo manipulador em mais de um arquivo de configurações, ele executa uma vez. Uma cópia do mesmo manipulador de um plugin ou skill permanece separada.
330 431
331Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local. A partir de v2.1.199, [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/pt/env-vars) é definido para o ID de sessão [Remote Control](/docs/pt/remote-control) enquanto a sessão local tem uma conexão Remote Control ativa.432Manipuladores executam no diretório atual com o ambiente do Claude Code. Se o diretório atual não existir mais, por exemplo uma worktree ou diretório temporário que outro shell deletou no meio da sessão, Claude Code executa hooks de comando a partir do primeiro destes que ainda existe: o diretório em que a sessão começou, a raiz do projeto, seu diretório home ou o diretório temporário do sistema. Claude Code registra um aviso nomeando o diretório de fallback no [log de debug](#debug-hooks).
433
434A variável de ambiente `$CLAUDE_CODE_REMOTE` é `"true"` em ambientes web remotos e não é definida na CLI local. Claude Code v2.1.199 e posterior define [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/pt/env-vars) para o ID de sessão [Remote Control](/docs/pt/remote-control) enquanto a sessão local tem uma conexão Remote Control ativa.
332 435
333<h4 id="common-fields">436<h4 id="common-fields">
334 Campos comuns437 Campos comuns
337Esses campos se aplicam a todos os tipos de hook:440Esses campos se aplicam a todos os tipos de hook:
338 441
339| Campo | Obrigatório | Descrição |442| Campo | Obrigatório | Descrição |
340| :-------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |443| :-------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
341| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |444| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |
342| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O comando do hook apenas é executado se a chamada de ferramenta corresponde ao padrão. Consulte a [tabela de correspondência Bash](#bash-if-matching) abaixo para saber como padrões Bash são avaliados contra subcomandos, `$()` e backticks. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/docs/pt/permissions) |445| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O comando do hook apenas é executado se a chamada de ferramenta corresponde ao padrão. Consulte a [tabela de correspondência Bash](#bash-if-matching) abaixo para saber como padrões Bash são avaliados contra subcomandos, `$()` e backticks. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/docs/pt/permissions) |
343| `timeout` | não | Segundos antes de cancelar. Padrões: 600 para `command`, `http` e `mcp_tool`; 30 para `prompt`; 60 para `agent`. [`UserPromptSubmit`](#userpromptsubmit) reduz o padrão de `command`, `http` e `mcp_tool` para 30, e [`MessageDisplay`](#messagedisplay) reduz para 10 |446| `timeout` | não | Segundos antes de cancelar. Claude Code não o impõe em um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background). Padrões: 600 para `command`, `http` e `mcp_tool`; 30 para `prompt`; 60 para `agent`. Claude Code reduz o padrão de `command`, `http` e `mcp_tool` para 30 em [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch) e [`PostModelSwitch`](#postmodelswitch), e para 10 em [`MessageDisplay`](#messagedisplay). Hooks de [`SessionEnd`](#sessionend) compartilham um orçamento de 1,5 segundo; se suas configurações definirem um `timeout` por hook mais longo, Claude Code aumenta o orçamento para corresponder, até 60 segundos |
344| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |447| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |
345| `once` | não | Se `true`, executa apenas uma vez por sessão e depois é removido. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |448| `once` | não | Se `true`, Claude Code remove o hook após sua primeira execução bem-sucedida. Uma execução que falha, bloqueia com código de saída 2 ou expira deixa o hook em vigor, então ele executa novamente no próximo evento correspondente. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |
346 449
347O campo `if` contém exatamente uma regra de permissão. Não há sintaxe `&&`, `||` ou lista para combinar regras; para aplicar múltiplas condições, defina um manipulador de hook separado para cada.450O campo `if` contém exatamente uma regra de permissão. Não há sintaxe `&&`, `||` ou lista para combinar regras; para aplicar múltiplas condições, defina um manipulador de hook separado para cada.
348 451
452Em uma condição `if` para uma ferramenta de arquivo, um padrão de diretório de segmento único como `"Edit(src/**)"` corresponde apenas ao diretório `src` no diretório de trabalho e aos arquivos sob ele. Para corresponder a um diretório nomeado `src` em qualquer profundidade, escreva `"Edit(**/src/**)"`. Antes de v2.1.214, `"Edit(src/**)"` correspondia a um diretório nomeado `src` em qualquer profundidade sob o diretório de trabalho.
453
349<span id="bash-if-matching" />Para padrões Bash, se seu comando de hook executa depende da forma do padrão e do comando Bash que Claude está invocando. Atribuições `VAR=value` iniciais são removidas antes da correspondência.454<span id="bash-if-matching" />Para padrões Bash, se seu comando de hook executa depende da forma do padrão e do comando Bash que Claude está invocando. Atribuições `VAR=value` iniciais são removidas antes da correspondência.
350 455
351| padrão `if` | Comando Bash | Hook executa? | Por quê |456| padrão `if` | Comando Bash | Hook executa? | Por quê |
352| :----------------- | :--------------------- | :------------ | :-------------------------------------------------------------------------------------------------------------- |457| :----------------- | :-------------------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
353| `Bash(git *)` | `FOO=bar git push` | sim | atribuições iniciais são removidas; `git push` corresponde |458| `Bash(git *)` | `FOO=bar git push` | sim | atribuições iniciais são removidas; `git push` corresponde |
354| `Bash(git *)` | `npm test && git push` | sim | cada subcomando é verificado; `git push` corresponde |459| `Bash(git *)` | `npm test && git push` | sim | cada subcomando é verificado; `git push` corresponde |
355| `Bash(rm *)` | `echo $(rm -rf /)` | sim | comandos dentro de `$()` e backticks são verificados; `rm -rf /` corresponde |460| `Bash(rm *)` | `echo $(rm -rf /)` | sim | comandos dentro de `$()` e backticks são verificados; `rm -rf /` corresponde |
356| `Bash(rm *)` | `echo $(date)` | não | nenhum subcomando corresponde a `rm *` |461| `Bash(rm *)` | `echo $(date)` | não | nenhum subcomando corresponde a `rm *` |
462| `Bash(cat *)` | `echo before $(date) after` | não | uma substituição pode estar em qualquer posição de argumento, então o comando completo e `date` são ambos verificados; nenhum corresponde a `cat *` |
463| `Bash(git *)` | `$TOOL git push` | sim | Claude Code não pode dizer para o que o nome do comando se expande, então executa o hook |
357| `Bash(git push *)` | `echo $(date)` | sim | padrões que especificam mais do que o nome do comando executam o hook mesmo assim em `$()`, backticks ou `$VAR` |464| `Bash(git push *)` | `echo $(date)` | sim | padrões que especificam mais do que o nome do comando executam o hook mesmo assim em `$()`, backticks ou `$VAR` |
358 465
359O filtro também falha aberto, executando seu hook independentemente do padrão, quando o comando Bash não pode ser analisado. Como o filtro `if` é melhor esforço, use o [sistema de permissão](/docs/pt/permissions) em vez de um hook para impor um allow ou deny duro.466Quando Claude Code não pode determinar quais comandos a entrada Bash executa, ele executa seu hook independentemente do padrão. Como o filtro `if` é melhor esforço, use o [sistema de permissão](/docs/pt/permissions) em vez de um hook para impor um allow ou deny duro.
360 467
361<h4 id="command-hook-fields">468<h4 id="command-hook-fields">
362 Campos de hook de comando469 Campos de hook de comando
369| `command` | sim | Comando shell a executar. Com `args`, o executável a gerar diretamente. Consulte [Forma exec e forma shell](#exec-form-and-shell-form) |476| `command` | sim | Comando shell a executar. Com `args`, o executável a gerar diretamente. Consulte [Forma exec e forma shell](#exec-form-and-shell-form) |
370| `args` | não | Lista de argumentos. Quando presente, `command` é resolvido como um executável e gerado diretamente com `args` como o vetor de argumentos, sem shell envolvido. Consulte [Forma exec e forma shell](#exec-form-and-shell-form) |477| `args` | não | Lista de argumentos. Quando presente, `command` é resolvido como um executável e gerado diretamente com `args` como o vetor de argumentos, sem shell envolvido. Consulte [Forma exec e forma shell](#exec-form-and-shell-form) |
371| `async` | não | Se `true`, executa em background sem bloquear. Consulte [Executar hooks em background](#run-hooks-in-the-background) |478| `async` | não | Se `true`, executa em background sem bloquear. Consulte [Executar hooks em background](#run-hooks-in-the-background) |
372| `asyncRewake` | não | Se `true`, executa em background e acorda Claude na saída do código 2. Implica `async`. O stderr do hook, ou stdout se stderr estiver vazio, é mostrado ao Claude como um lembrete do sistema para que possa reagir a uma falha de background de longa duração |479| `asyncRewake` | não | Se `true`, executa em background e acorda Claude na saída do código 2. O stderr do hook, ou stdout se stderr estiver vazio, é mostrado ao Claude como um lembrete do sistema para que possa reagir a uma falha de background de longa duração |
373| `shell` | não | Shell a usar para este hook. Aceita `"bash"` ou `"powershell"`. Padrão é `"bash"`, ou `"powershell"` no Windows quando Git Bash não está instalado. Definir `"powershell"` executa o comando via PowerShell no Windows. Não requer `CLAUDE_CODE_USE_POWERSHELL_TOOL` já que hooks geram PowerShell diretamente. Ignorado quando `args` é definido |480| `shell` | não | Shell a usar para este hook. Aceita `"bash"` ou `"powershell"`. Padrão é `"bash"`, ou `"powershell"` no Windows quando Git Bash não está instalado. Definir `"powershell"` executa o comando via PowerShell no Windows. Não requer `CLAUDE_CODE_USE_POWERSHELL_TOOL` já que hooks geram PowerShell diretamente. Ignorado quando `args` é definido |
374 481
375<a id="exec-form-and-shell-form" />482<a id="exec-form-and-shell-form" />
409 516
410Ambas as formas suportam os mesmos [placeholders de caminho](#reference-scripts-by-path), e ambas os exportam como as variáveis de ambiente `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT` e `CLAUDE_PLUGIN_DATA` no processo gerado, então um script pode ler `process.env.CLAUDE_PLUGIN_ROOT` independentemente de como foi lançado.517Ambas as formas suportam os mesmos [placeholders de caminho](#reference-scripts-by-path), e ambas os exportam como as variáveis de ambiente `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT` e `CLAUDE_PLUGIN_DATA` no processo gerado, então um script pode ler `process.env.CLAUDE_PLUGIN_ROOT` independentemente de como foi lançado.
411 518
519Hooks de plugin adicionalmente substituem valores [`${user_config.*}`](/docs/pt/plugins-reference#user-configuration), apenas em forma exec: o valor é substituído em `command` e em cada elemento `args` como uma string simples, então nenhum shell o re-analisa.
520
412Um hook de plugin em forma shell cujo `command` referencia `${user_config.*}` falha com um [erro](/docs/pt/errors#plugin-command-references-user-config) em vez de executar. Para usar um valor de opção de um hook em forma shell, leia a variável de ambiente `$CLAUDE_PLUGIN_OPTION_<KEY>`, como `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` para uma opção `webhook_url`, ou defina `args` para mudar o hook para forma exec. Antes de v2.1.207, comandos de hook de plugin em forma shell também substituíam `${user_config.*}`.521Um hook de plugin em forma shell cujo `command` referencia `${user_config.*}` falha com um [erro](/docs/pt/errors#plugin-command-references-user-config) em vez de executar. Para usar um valor de opção de um hook em forma shell, leia a variável de ambiente `$CLAUDE_PLUGIN_OPTION_<KEY>`, como `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL` para uma opção `webhook_url`, ou defina `args` para mudar o hook para forma exec. Antes de v2.1.207, comandos de hook de plugin em forma shell também substituíam `${user_config.*}`.
413 522
414<Note>523<Note>
427| `headers` | não | Cabeçalhos HTTP adicionais como pares chave-valor. Valores suportam interpolação de variável de ambiente usando sintaxe `$VAR_NAME` ou `${VAR_NAME}`. Apenas variáveis listadas em `allowedEnvVars` são resolvidas |536| `headers` | não | Cabeçalhos HTTP adicionais como pares chave-valor. Valores suportam interpolação de variável de ambiente usando sintaxe `$VAR_NAME` ou `${VAR_NAME}`. Apenas variáveis listadas em `allowedEnvVars` são resolvidas |
428| `allowedEnvVars` | não | Lista de nomes de variáveis de ambiente que podem ser interpoladas em valores de cabeçalho. Referências a variáveis não listadas são substituídas por strings vazias. Obrigatório para qualquer interpolação de variável de ambiente funcionar |537| `allowedEnvVars` | não | Lista de nomes de variáveis de ambiente que podem ser interpoladas em valores de cabeçalho. Referências a variáveis não listadas são substituídas por strings vazias. Obrigatório para qualquer interpolação de variável de ambiente funcionar |
429 538
430O Claude Code envia a [entrada JSON](#hook-input-and-output) do hook como corpo da solicitação POST com `Content-Type: application/json`. O corpo da resposta usa o mesmo [formato de saída JSON](#json-output) que hooks de comando.539Claude Code envia a [entrada JSON](#hook-input-and-output) do hook como corpo da solicitação POST com `Content-Type: application/json`. O corpo da resposta usa o mesmo [formato de saída JSON](#json-output) que hooks de comando.
431 540
432O tratamento de erros difere dos hooks de comando: respostas não-2xx, falhas de conexão e timeouts todos produzem erros não-bloqueadores que permitem que a execução continue. Para bloquear uma chamada de ferramenta ou negar uma permissão, retorne uma resposta 2xx com um corpo JSON contendo `decision: "block"` ou um `hookSpecificOutput` com `permissionDecision: "deny"`.541O tratamento de erros difere dos hooks de comando; consulte [Tratamento de resposta HTTP](#http-response-handling).
433 542
434Este exemplo envia eventos `PreToolUse` para um serviço de validação local, autenticando com um token da variável de ambiente `MY_TOKEN`:543Este exemplo envia eventos `PreToolUse` para um serviço de validação local, autenticando com um token da variável de ambiente `MY_TOKEN`:
435 544
468| `tool` | sim | Nome da ferramenta a chamar naquele servidor |577| `tool` | sim | Nome da ferramenta a chamar naquele servidor |
469| `input` | não | Argumentos passados para a ferramenta. Valores de string suportam substituição `${path}` da [entrada JSON](#hook-input-and-output) do hook, como `"${tool_input.file_path}"` |578| `input` | não | Argumentos passados para a ferramenta. Valores de string suportam substituição `${path}` da [entrada JSON](#hook-input-and-output) do hook, como `"${tool_input.file_path}"` |
470 579
471A saída de texto da ferramenta é tratada como stdout de hook de comando: se analisar como [saída JSON](#json-output) válida, é processada como uma decisão, caso contrário, é mostrada como texto simples. Se o servidor nomeado não estiver conectado, ou a ferramenta retornar `isError: true`, o hook produz um erro não-bloqueador e a execução continua.580Claude Code lê o conteúdo de texto da ferramenta da mesma forma que lê stdout de hook de comando, seguindo a [regra de análise sob código de saída 0](#exit-code-0). Se o servidor nomeado não estiver conectado, ou a ferramenta retornar `isError: true`, o hook produz um erro não-bloqueador e a execução continua.
472
473Hooks de ferramenta MCP estão disponíveis em cada evento de hook uma vez que o Claude Code tenha se conectado aos seus servidores MCP. `SessionStart` e `Setup` normalmente disparam antes dos servidores terminarem de conectar, então hooks nesses eventos devem esperar o erro "não conectado" na primeira execução.
474 581
475Este exemplo chama a ferramenta `security_scan` no servidor MCP `my_server` após cada `Write` ou `Edit`, passando o caminho do arquivo editado:582Este exemplo chama a ferramenta `security_scan` no servidor MCP `my_server` após cada `Write` ou `Edit`, passando o caminho do arquivo editado:
476 583
494}601}
495```602```
496 603
604Um hook `mcp_tool` pode executar apenas uma vez que Claude Code tenha disponibilizado os servidores MCP da sessão para hooks. `SessionStart` e `Setup` podem disparar antes desse ponto:
605
606* **No lançamento**: `SessionStart` dispara antes dos servidores estarem disponíveis, incluindo quando você lança com `--continue` ou `--resume`. Claude Code pula os hooks `mcp_tool` do evento sem chamar suas ferramentas, e o [log de debug](#debug-hooks) registra `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`.
607* **Mais tarde em uma sessão em execução**: após `/clear` ou uma compactação, `SessionStart` dispara novamente com os servidores já disponíveis, e seus hooks `mcp_tool` executam.
608* **Em `Setup`**: `Setup` sempre dispara antes dos servidores estarem disponíveis, então Claude Code pula seus hooks `mcp_tool` toda vez e registra a mesma mensagem nomeando `Setup`.
609
610Por exemplo, esta configuração chama a ferramenta `load_context` no servidor MCP `my_server` de um hook `SessionStart` sem matcher, então se aplica a cada fonte `SessionStart`:
611
612```json theme={null}
613{
614 "hooks": {
615 "SessionStart": [
616 {
617 "hooks": [
618 {
619 "type": "mcp_tool",
620 "server": "my_server",
621 "tool": "load_context"
622 }
623 ]
624 }
625 ]
626 }
627}
628```
629
630Quando você executa `claude`, Claude Code pula este hook, nunca chama `load_context` e escreve a mensagem `no MCP client context` no log de debug. Execute `/clear` nessa mesma sessão e o hook executa e chama `load_context`. Um hook `type: "command"` em `SessionStart` executa no lançamento, então use um para qualquer coisa que a sessão precise de seu primeiro turno.
631
497<h4 id="prompt-and-agent-hook-fields">632<h4 id="prompt-and-agent-hook-fields">
498 Campos de hook de prompt e agente633 Campos de hook de prompt e agente
499</h4>634</h4>
511 646
512Use esses placeholders para referenciar scripts de hook relativos à raiz do projeto ou plugin, independentemente do diretório de trabalho quando o hook executa:647Use esses placeholders para referenciar scripts de hook relativos à raiz do projeto ou plugin, independentemente do diretório de trabalho quando o hook executa:
513 648
514* `${CLAUDE_PROJECT_DIR}`: a raiz do projeto. Claude Code também define essa variável no ambiente de [servidores MCP stdio](/docs/pt/mcp#option-3-add-a-local-stdio-server) e servidores LSP de plugin.649* `${CLAUDE_PROJECT_DIR}`: a raiz do projeto onde a sessão começou. Claude Code também define essa variável no ambiente de [servidores MCP stdio](/docs/pt/mcp#option-3-add-a-local-stdio-server) e servidores LSP de plugin.
515* `${CLAUDE_PLUGIN_ROOT}`: o diretório de instalação do plugin, para scripts agrupados com um [plugin](/docs/pt/plugins). Muda em cada atualização de plugin.650* `${CLAUDE_PLUGIN_ROOT}`: o diretório de instalação do plugin, para scripts agrupados com um [plugin](/docs/pt/plugins). Consulte [variáveis de ambiente de plugin](/docs/pt/plugins-reference#environment-variables) para saber como o caminho se comporta entre atualizações.
516* `${CLAUDE_PLUGIN_DATA}`: o [diretório de dados persistentes](/docs/pt/plugins-reference#persistent-data-directory) do plugin, para dependências e estado que devem sobreviver a atualizações de plugin.651* `${CLAUDE_PLUGIN_DATA}`: o [diretório de dados persistentes](/docs/pt/plugins-reference#persistent-data-directory) do plugin, para dependências e estado que devem sobreviver a atualizações de plugin.
517 652
518Prefira [forma exec](#exec-form-and-shell-form) para qualquer hook que referencie um placeholder de caminho. A forma exec passa cada elemento `args` como um argumento sem tokenização de shell, então caminhos com espaços ou caracteres especiais não precisam de aspas. Em forma shell, envolva cada placeholder em aspas duplas.653<Note>
654 **Worktrees são diferentes.** Se Claude entra em uma [worktree](/docs/pt/worktrees) durante a sessão, Claude Code mantém `${CLAUDE_PROJECT_DIR}` onde estava e passa o caminho da worktree para seus hooks de uma forma diferente:
655
656 * **`${CLAUDE_PROJECT_DIR}` fica no lugar**: ainda aponta para a raiz do projeto onde a sessão começou, então um comando como `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` ainda executa o script no checkout principal.
657 * **`cwd` segue Claude**: o campo `cwd` na [entrada JSON](#common-input-fields) do hook é a raiz da worktree após Claude entrar em uma worktree, e o novo diretório após Claude executar `cd`. Leia-o quando um hook precisa saber em qual diretório Claude está trabalhando.
658</Note>
659
660Prefira [forma exec](#exec-form-and-shell-form) para qualquer hook que referencie um placeholder de caminho. Em forma shell, envolva cada placeholder em aspas duplas.
519 661
520<Tabs>662<Tabs>
521 <Tab title="Scripts de projeto">663 <Tab title="Scripts de projeto">
575 Hooks em skills e agentes717 Hooks em skills e agentes
576</h3>718</h3>
577 719
578Além de arquivos de configurações e plugins, hooks podem ser definidos diretamente em [skills](/docs/pt/skills) e [subagentes](/docs/pt/sub-agents) usando frontmatter. Esses hooks são escopo do ciclo de vida do componente e apenas executam quando esse componente está ativo.720Além de arquivos de configurações e plugins, hooks podem ser definidos diretamente em [skills](/docs/pt/skills) e [subagentes](/docs/pt/sub-agents) usando frontmatter, no mesmo formato de configuração que hooks baseados em configurações. Por quanto tempo Claude Code os mantém registrados depende do componente:
579
580Todos os eventos de hook são suportados. Para subagentes, hooks `Stop` são automaticamente convertidos para `SubagentStop` já que esse é o evento que dispara quando um subagente completa.
581 721
582Hooks usam o mesmo formato de configuração que hooks baseados em configurações, mas são escopo da vida útil do componente e limpos quando termina.722* **Hooks de subagente**: Claude Code os executa apenas enquanto esse subagente está em execução e os remove quando termina. Claude Code converte um hook `Stop` aqui para `SubagentStop`, o evento que dispara quando um subagente completa.
723* **Hooks de skill**: Claude Code os registra quando você ou Claude invoca a skill e continua executando-os pelo resto da sessão, em turnos após o próprio turno da skill também. Para fazer Claude Code remover um hook após sua primeira execução bem-sucedida em vez disso, defina [`once: true`](#common-fields) nele.
583 724
584Esta skill define um hook `PreToolUse` que executa um script de validação de segurança antes de cada comando `Bash`:725Esta skill define um hook `PreToolUse` que executa um script de validação de segurança antes de cada comando `Bash`:
585 726
596---737---
597```738```
598 739
599Agentes usam o mesmo formato em seu frontmatter YAML.740Subagentes usam o mesmo formato em seu frontmatter YAML.
741
742Hooks de frontmatter em uma skill de projeto seguem a mesma [regra de confiança de workspace que hooks em arquivos de configurações](#workspace-trust). Claude Code os registra quando você ou Claude invoca a skill, incluindo em uma execução `-p` em uma pasta que você não confiou.
743
744Hooks de frontmatter em um subagente de projeto executam apenas após você aceitar o [diálogo de confiança de workspace](/docs/pt/permissions#project-allow-rules-and-workspace-trust) para a pasta de onde o arquivo do agente veio. Uma sessão `-p` não conta como aceitá-lo. [O que executa antes de você confiar em uma pasta](/docs/pt/permissions#what-runs-before-you-trust-a-folder) compara isso com a regra de arquivo de configurações, e a página de subagentes lista [quais escopos estão isentos](/docs/pt/sub-agents#hooks-in-subagent-frontmatter). Antes de v2.1.218, esses hooks podiam executar de pastas que você não confiava.
600 745
601<h3 id="the-/hooks-menu">746<h3 id="the-/hooks-menu">
602 O menu `/hooks`747 O menu `/hooks`
606 751
607O menu exibe todos os cinco tipos de hook: `command`, `prompt`, `agent`, `http` e `mcp_tool`. Cada hook é rotulado com um prefixo `[type]` e uma fonte indicando onde foi definido:752O menu exibe todos os cinco tipos de hook: `command`, `prompt`, `agent`, `http` e `mcp_tool`. Cada hook é rotulado com um prefixo `[type]` e uma fonte indicando onde foi definido:
608 753
609* `User`: de `~/.claude/settings.json`754* `User Settings`: de `~/.claude/settings.json`
610* `Project`: de `.claude/settings.json`755* `Project Settings`: de `.claude/settings.json`
611* `Local`: de `.claude/settings.local.json`756* `Local Settings`: de `.claude/settings.local.json`
612* `Plugin`: de `hooks/hooks.json` de um plugin757* `Plugin Hooks`: de `hooks/hooks.json` de um plugin
613* `Session`: registrado em memória para a sessão atual758* `Session Hooks`: registrado em memória para a sessão atual
614* `Built-in`: registrado internamente pelo Claude Code
615 759
616Selecionar um hook abre uma visualização de detalhes mostrando seu evento, matcher, tipo, arquivo de origem e o comando, prompt ou URL completo. O menu é somente leitura: para adicionar, modificar ou remover hooks, edite o JSON de configurações diretamente ou peça ao Claude para fazer a mudança.760Selecionar um hook abre uma visualização de detalhes mostrando seu evento, matcher, tipo, arquivo de origem e o comando, prompt ou URL completo. O menu é somente leitura: para adicionar, modificar ou remover hooks, edite o JSON de configurações diretamente ou peça ao Claude para fazer a mudança.
617 761
621 765
622Para remover um hook, delete sua entrada do arquivo de configurações JSON.766Para remover um hook, delete sua entrada do arquivo de configurações JSON.
623 767
624Para desabilitar temporariamente todos os hooks sem removê-los, defina `"disableAllHooks": true` em seu arquivo de configurações. Não há forma de desabilitar um hook individual mantendo-o na configuração.768Para desabilitar temporariamente todos os hooks sem removê-los, defina `"disableAllHooks": true` em seu arquivo de configurações. Claude Code lê o valor deixado após [precedência de configurações](/docs/pt/settings#settings-precedence) se aplicar, então um `"disableAllHooks": false` no `.claude/settings.json` de um projeto substitui um `true` em suas configurações de usuário. Para desabilitar hooks para uma execução qualquer que as configurações do projeto digam, passe `--settings '{"disableAllHooks": true}'`, que tem precedência sobre configurações de projeto e local. Não há forma de desabilitar um hook individual mantendo-o na configuração.
625 769
626A configuração `disableAllHooks` respeita a hierarquia de configurações gerenciadas. Se um administrador configurou hooks através de configurações de política gerenciada, `disableAllHooks` definido em configurações de usuário, projeto ou local não pode desabilitar esses hooks gerenciados. Apenas `disableAllHooks` definido no nível de configurações gerenciadas pode desabilitar hooks gerenciados.770A configuração `disableAllHooks` respeita a hierarquia de configurações gerenciadas. Se um administrador configurou hooks através de configurações de política gerenciada, `disableAllHooks` definido em configurações de usuário, projeto ou local não pode desabilitar esses hooks gerenciados. Apenas `disableAllHooks` definido no nível de configurações gerenciadas pode desabilitar hooks gerenciados. Para o alcance completo de cada nível, consulte [`disableAllHooks`](/docs/pt/settings-reference#disableallhooks).
627 771
628Edições diretas a hooks em arquivos de configurações são normalmente capturadas automaticamente pelo observador de arquivo.772Edições diretas a hooks em arquivos de configurações são normalmente capturadas automaticamente pelo observador de arquivo.
629 773
633 777
634Hooks de comando recebem dados JSON via stdin e comunicam resultados através de códigos de saída, stdout e stderr. Hooks HTTP recebem o mesmo JSON como corpo da solicitação POST e comunicam resultados através do corpo da resposta HTTP. Esta seção cobre campos e comportamento comuns a todos os eventos. Cada seção de evento sob [Eventos de hook](#hook-events) inclui seu esquema de entrada específico e opções de controle de decisão.778Hooks de comando recebem dados JSON via stdin e comunicam resultados através de códigos de saída, stdout e stderr. Hooks HTTP recebem o mesmo JSON como corpo da solicitação POST e comunicam resultados através do corpo da resposta HTTP. Esta seção cobre campos e comportamento comuns a todos os eventos. Cada seção de evento sob [Eventos de hook](#hook-events) inclui seu esquema de entrada específico e opções de controle de decisão.
635 779
636No macOS e Linux, hooks de comando executam em sua própria sessão sem um terminal controlador a partir de v2.1.139. O processo de hook e qualquer processo filho não podem abrir `/dev/tty` ou enviar sequências de escape diretamente para a interface do Claude Code. Windows não tem `/dev/tty`. Para exibir uma mensagem ao usuário em qualquer plataforma, retorne [`systemMessage`](#json-output) na saída JSON. Para disparar uma notificação de desktop, definir um título de janela ou tocar o sino, retorne [`terminalSequence`](#emit-terminal-notifications) em vez disso.780No macOS e Linux, hooks de comando executam em sua própria sessão sem um terminal controlador. O processo de hook e qualquer processo filho não podem abrir `/dev/tty` ou enviar sequências de escape diretamente para a interface do Claude Code. Windows não tem `/dev/tty`.
781
782Para exibir uma mensagem ao usuário em qualquer plataforma, retorne [`systemMessage`](#json-output) na saída JSON. Alguns eventos descartam isso ou o entregam em outro lugar, e cada [seção de evento](#hook-events) diz assim. Para disparar uma notificação de desktop, definir um título de janela ou tocar o sino, retorne [`terminalSequence`](#emit-terminal-notifications) em vez disso.
637 783
638<h3 id="common-input-fields">784<h3 id="common-input-fields">
639 Campos de entrada comuns785 Campos de entrada comuns
642Eventos de hook recebem esses campos como JSON, além de campos específicos do evento documentados em cada seção [evento de hook](#hook-events). Para hooks de comando, este JSON chega via stdin. Para hooks HTTP, chega como corpo da solicitação POST.788Eventos de hook recebem esses campos como JSON, além de campos específicos do evento documentados em cada seção [evento de hook](#hook-events). Para hooks de comando, este JSON chega via stdin. Para hooks HTTP, chega como corpo da solicitação POST.
643 789
644| Campo | Descrição |790| Campo | Descrição |
645| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |791| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
646| `session_id` | Identificador de sessão atual |792| `session_id` | Identificador de sessão atual |
647| `prompt_id` | UUID identificando o prompt do usuário sendo processado atualmente. Corresponde ao [atributo `prompt.id` em eventos OpenTelemetry](/docs/pt/monitoring-usage#event-correlation-attributes), para que você possa correlacionar saída de hook com telemetria para um único prompt. Ausente até a primeira entrada do usuário. Requer Claude Code v2.1.196 ou posterior |793| `prompt_id` | UUID identificando o prompt do usuário sendo processado atualmente. Corresponde ao [atributo `prompt.id` em eventos OpenTelemetry](/docs/pt/monitoring-usage#event-correlation-attributes), para que você possa correlacionar saída de hook com telemetria para um único prompt. Ausente até a primeira entrada do usuário. Requer Claude Code v2.1.196 ou posterior |
648| `transcript_path` | Caminho para JSON de conversa. O arquivo de transcrição é escrito de forma assíncrona e pode ficar atrás da conversa na memória, portanto pode não incluir ainda as mensagens mais recentes da rodada atual quando um hook dispara. Hooks que precisam do texto final do assistente da rodada atual devem usar `last_assistant_message` em [Stop](#stop) e [SubagentStop](#subagentstop) em vez de ler a transcrição |794| `transcript_path` | Caminho para JSON de conversa. O arquivo de transcrição é escrito de forma assíncrona e pode ficar atrás da conversa na memória, portanto pode não incluir ainda as mensagens mais recentes da rodada atual quando um hook dispara. Hooks que precisam do texto final do assistente da rodada atual devem usar `last_assistant_message` em [Stop](#stop) e [SubagentStop](#subagentstop) em vez de ler a transcrição |
649| `cwd` | Diretório de trabalho atual quando o hook é invocado |795| `cwd` | Diretório de trabalho atual quando o hook é invocado |
796| `scratchpad_dir` | Caminho para o diretório scratchpad da sessão, onde Claude mantém arquivos de trabalho temporários. Ausente quando a sessão não tem scratchpad ou o diretório temporário não está disponível. Requer Claude Code v2.1.257 ou posterior |
650| `permission_mode` | [Modo de permissão](/docs/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. O modo rotulado **Manual** chega como `"default"`, nunca como `"manual"`, portanto scripts que correspondem a `"default"` continuam funcionando. Nem todos os eventos recebem este campo. Verifique o exemplo JSON em cada seção [evento de hook](#hook-events) |797| `permission_mode` | [Modo de permissão](/docs/pt/permissions#permission-modes) atual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` ou `"bypassPermissions"`. O modo rotulado **Manual** chega como `"default"`, nunca como `"manual"`, portanto scripts que correspondem a `"default"` continuam funcionando. Nem todos os eventos recebem este campo. Verifique o exemplo JSON em cada seção [evento de hook](#hook-events) |
651| `effort` | Objeto com um campo `level` contendo o [nível de esforço](/docs/pt/model-config#adjust-effort-level) ativo para a rodada: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Se o esforço solicitado do modelo exceder o que o modelo atual suporta, este é o nível reduzido que o modelo realmente usou. Ultracode não é um nível distinto e é relatado como `"xhigh"`. O objeto corresponde ao campo `effort` da [linha de status](/docs/pt/statusline#available-data). Presente para eventos que disparam dentro de um contexto de uso de ferramenta, como `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando o modelo atual suporta o parâmetro de esforço. O nível também está disponível para comandos de hook e a ferramenta Bash como a variável de ambiente `$CLAUDE_EFFORT`. |798| `effort` | Objeto com um campo `level` contendo o [nível de esforço](/docs/pt/model-config#adjust-effort-level) em vigor quando o hook é executado: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Se você definir um nível que o modelo ativo não suporta, `level` relata o nível que Claude Code executou em vez disso; [Ajustar nível de esforço](/docs/pt/model-config#adjust-effort-level) diz como ele escolhe esse nível. Ultracode não é um nível distinto e é relatado como `"xhigh"`. O objeto corresponde ao campo `effort` da [linha de status](/docs/pt/statusline#available-data). Presente para eventos que disparam dentro de um contexto de uso de ferramenta, como `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando o modelo atual suporta o parâmetro de esforço. O nível também está disponível para comandos de hook e a ferramenta Bash como a variável de ambiente `$CLAUDE_EFFORT`. |
652| `hook_event_name` | Nome do evento que disparou |799| `hook_event_name` | Nome do evento que disparou |
653 800
654Ao executar com `--agent` ou dentro de um subagente, dois campos adicionais são incluídos:801Ao executar com `--agent` ou dentro de um subagente, dois campos adicionais são incluídos:
655 802
656| Campo | Descrição |803| Campo | Descrição |
657| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |804| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
658| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |805| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |
659| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Para [subagentes personalizados](/docs/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo. Para subagentes fornecidos por um [plugin](/docs/pt/plugins), este é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome de frontmatter simples. Consulte [SubagentStart](#subagentstart) para saber como escrever um matcher contra um nome com escopo de plugin. |806| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Consulte [SubagentStart](#subagentstart) para os valores que subagentes personalizados e de plugin relatam e como escrever um matcher contra um nome com escopo de plugin. |
807
808Apenas hooks [`SessionStart`](#sessionstart) podem receber um campo `model`, e Claude Code nem sempre o inclui. Hooks [`PreModelSwitch`](#premodelswitch) e [`PostModelSwitch`](#postmodelswitch) recebem `from_model` e `to_model` em vez disso, portanto use um hook PostModelSwitch para acompanhar o modelo conforme ele muda durante uma sessão.
660 809
661Apenas hooks [`SessionStart`](#sessionstart) podem receber um campo `model`, e não é garantido que esteja presente. Não há variável de ambiente `$CLAUDE_MODEL`. Um processo de hook herda o ambiente pai, então pode ler `$ANTHROPIC_MODEL` se você defini-lo em seu shell, mas esse valor não muda quando você alterna modelos com `/model` durante uma sessão. Um conjunto de variáveis não é herdado: Claude Code [remove variáveis exportadoras `OTEL_*` de cada subprocesso que spawna](/docs/pt/monitoring-usage#administrator-configuration), incluindo hooks.810Não há variável de ambiente `$CLAUDE_MODEL`. O hook pode ler `$ANTHROPIC_MODEL` se você defini-lo em seu shell, mas esse valor não muda quando você alterna modelos com `/model` durante uma sessão.
811
812Um processo de hook herda o ambiente pai, além das variáveis exportadoras `OTEL_*` que Claude Code [remove de cada subprocesso que spawna](/docs/pt/monitoring-usage#administrator-configuration) e, quando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/pt/env-vars#variables) é definido como `1`, as variáveis que ele remove.
662 813
663Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:814Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:
664 815
668 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",819 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
669 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",820 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
670 "cwd": "/home/user/my-project",821 "cwd": "/home/user/my-project",
822 "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
671 "permission_mode": "default",823 "permission_mode": "default",
672 "hook_event_name": "PreToolUse",824 "hook_event_name": "PreToolUse",
673 "tool_name": "Bash",825 "tool_name": "Bash",
674 "tool_input": {826 "tool_input": {
675 "command": "npm test"827 "command": "npm test",
676 }828 "description": "Run test suite",
829 "timeout": 120000,
830 "run_in_background": false
831 },
832 "tool_use_id": "toolu_01ABC123..."
677}833}
678```834```
679 835
680Os campos `tool_name` e `tool_input` são específicos do evento. Cada seção [evento de hook](#hook-events) documenta os campos adicionais para esse evento.836Os campos `tool_name`, `tool_input` e `tool_use_id` são específicos do evento. Cada seção [evento de hook](#hook-events) documenta os campos adicionais para esse evento.
681 837
682<h3 id="exit-code-output">838<h3 id="exit-code-output">
683 Saída de código de saída839 Saída de código de saída
684</h3>840</h3>
685 841
686O código de saída do seu comando de hook diz ao Claude Code se a ação deve prosseguir, ser bloqueada ou ser ignorada.842O código de saída do seu comando de hook diz ao Claude Code se a ação deve prosseguir, ser bloqueada ou ser ignorada. O código de saída não atua sozinho. Claude Code lê [campos de saída JSON](#json-output) de stdout em cada código de saída, não apenas 0, e para eventos que usam o modelo de decisão padrão, um objeto analisado que passa na validação de esquema entra em vigor ao lado do código. O bloqueio da saída 2 é o único resultado que JSON não pode substituir.
843
844Duas tabelas possuem as exceções por evento: [Comportamento de código de saída 2 por evento](#exit-code-2-behavior-per-event) diz o que códigos de saída fazem para cada evento, e [Controle de decisão](#decision-control) diz quais campos de decisão cada evento honra. Campos universais como `systemMessage` funcionam em muitos eventos e são listados na tabela [Saída JSON](#json-output).
845
846<h4 id="exit-code-0">
847 Código de saída 0
848</h4>
849
850Saída 0 significa sucesso, e é o código de saída pretendido quando você imprime JSON para controle estruturado.
851
852Para a maioria dos eventos, Claude Code escreve stdout no log de debug e não o mostra na transcrição. As exceções são `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` e `PostModelSwitch`, onde Claude Code adiciona stdout em texto simples como contexto que Claude pode ver e agir.
687 853
688**Saída 0** significa sucesso. O Claude Code analisa stdout para [campos de saída JSON](#json-output). A saída JSON é apenas processada na saída 0. Para a maioria dos eventos, stdout é escrito no log de debug, mas não mostrado na transcrição. As exceções são `UserPromptSubmit`, `UserPromptExpansion` e `SessionStart`, onde stdout é adicionado como contexto que Claude pode ver e agir.854Se Claude Code lê seu stdout como [saída JSON](#json-output) ou como texto simples depende de como ele começa e termina, ignorando espaço em branco ao redor:
689 855
690**Saída 2** significa um erro bloqueador. O Claude Code ignora stdout e qualquer JSON nele. Em vez disso, texto de stderr é alimentado de volta ao Claude como uma mensagem de erro. O efeito depende do evento: `PreToolUse` bloqueia a chamada da ferramenta, `UserPromptSubmit` rejeita o prompt e assim por diante. Consulte [comportamento de código de saída 2](#exit-code-2-behavior-per-event) para a lista completa.856* **Começa com `{` e termina com `}`**: Claude Code o analisa como JSON. Quando a saída é duas ou mais linhas que cada uma analisa como JSON por conta própria, e nenhuma linha é um objeto [saída JSON](#json-output) que define um campo, Claude Code trata toda a saída como texto simples. Quando uma dessas linhas define um campo, toda a saída é uma falha de análise, descrita abaixo.
857* **Começa com `{` mas não termina com `}`**: Claude Code o trata como texto simples.
858* **Começa com qualquer outra coisa**: Claude Code o trata como texto simples, um array JSON ou uma string JSON entre aspas incluída.
691 859
692**Qualquer outro código de saída** é um erro não-bloqueador para a maioria dos eventos de hook. A transcrição mostra um aviso `<hook name> hook error` seguido pela primeira linha de stderr, para que você possa identificar a causa sem `--debug`. A execução continua e o stderr completo é escrito no log de debug.860Para eventos que usam o modelo de decisão padrão, saída 0 com um objeto analisado que falha na validação de esquema é um erro não-bloqueador: a ação prossegue, e a transcrição mostra um aviso `<hook name> hook error` com a mensagem de validação. O mesmo acontece em qualquer código de saída diferente de 2, enquanto [saída 2 ainda bloqueia](#exit-code-2).
693 861
694Por exemplo, um script de comando de hook que bloqueia comandos Bash perigosos:862Para eventos que usam o modelo de decisão padrão, quando Claude Code tenta analisar seu stdout como JSON e não consegue, ele relata um erro não-bloqueador em cada código de saída diferente de 2. A transcrição mostra um aviso `<hook name> hook error` com a mensagem de análise. Nos eventos que adicionam stdout em texto simples como contexto, Claude Code não adiciona o texto. Antes de v2.1.248, Claude Code tratava esse stdout como texto simples.
863
864Stderr de um hook que sai 0 vai apenas para o log de debug, nunca para a transcrição, e Claude nunca vê. Para lê-lo você mesmo, ative [debug logging](#debug-hooks). Para exibir um aviso para Claude de um hook `PostToolUse` ou `PostToolUseFailure`, saia 2 em vez disso para que [Claude veja o stderr](#exit-code-2-behavior-per-event) mesmo que a ferramenta já tenha executado.
865
866<h4 id="exit-code-2">
867 Código de saída 2
868</h4>
869
870Saída 2 significa um erro bloqueador. Em [eventos que podem bloquear](#exit-code-2-behavior-per-event), saída 2 bloqueia se você imprime JSON ou não: até mesmo um JSON `permissionDecision` de `"allow"` não pode substituir. Claude Code ainda lê qualquer [saída JSON](#json-output) válida em stdout. Em `Elicitation` e `ElicitationResult`, o `hookSpecificOutput` de um hook exit-2 é ignorado.
871
872A mensagem de bloqueio é a razão da decisão de bloqueio do seu JSON quando faz uma, e seu texto stderr caso contrário. O que o bloqueio faz varia por evento: `PreToolUse` bloqueia a chamada da ferramenta, `UserPromptSubmit` rejeita o prompt, e assim por diante. [Comportamento de código de saída 2 por evento](#exit-code-2-behavior-per-event) lista o efeito para cada evento, e cada seção de evento diz onde a mensagem vai.
873
874Um hook que sai 2 enquanto imprime JSON que falha na validação de esquema [saída JSON](#json-output) ainda bloqueia: Claude Code usa stderr como a razão de bloqueio e registra a falha de validação no log de debug. Antes de v2.1.214, Claude Code tratava essa combinação como um erro não-bloqueador e a ação prosseguia.
875
876Este script bloqueia comandos `rm` saindo 2 e deixa cada outro comando para o fluxo de permissão normal:
695 877
696```bash theme={null}878```bash theme={null}
697#!/bin/bash879#!/bin/bash
698# Lê entrada JSON de stdin, verifica o comando880# Lê entrada JSON de stdin, verifica o comando
699command=$(jq -r '.tool_input.command' < /dev/stdin)881input=$(cat)
882command=$(jq -r '.tool_input.command' <<<"$input")
700 883
701if [[ "$command" == rm* ]]; then884if [[ "$command" == rm* ]]; then
702 echo "Blocked: rm commands are not allowed" >&2885 echo "Blocked: rm commands are not allowed" >&2
706exit 0 # Sem decisão: o fluxo de permissão normal se aplica889exit 0 # Sem decisão: o fluxo de permissão normal se aplica
707```890```
708 891
892<h4 id="other-exit-codes">
893 Outros códigos de saída
894</h4>
895
896Qualquer outro código de saída não bloqueia por conta própria para a maioria dos eventos de hook. O que acontece depende de seu stdout:
897
898* Com um objeto analisado que passa na validação de esquema, para eventos que usam o modelo de decisão padrão, Claude Code ignora o código de saída e apenas o JSON decide o resultado:
899 * Cada campo que o evento suporta é honrado, incluindo `permissionDecision`, `additionalContext`, `updatedInput` e `systemMessage`, e o hook não é relatado como um erro.
900 * [Controle de decisão](#decision-control) lista os campos de decisão por evento; campos universais como `systemMessage` seguem a tabela [Saída JSON](#json-output).
901* Com um objeto analisado que falha na validação de esquema, para eventos que usam o modelo de decisão padrão, é o mesmo erro não-bloqueador que [na saída 0](#exit-code-0): a ação prossegue, e o aviso `<hook name> hook error` carrega a mensagem de validação.
902* Com stdout que Claude Code [tenta analisar como JSON](#exit-code-0) e não consegue, Claude Code relata o mesmo erro não-bloqueador que na saída 0 para eventos que usam o modelo de decisão padrão. A ação prossegue, e o aviso carrega a mensagem de análise.
903* Com stdout que Claude Code [trata como texto simples](#exit-code-0), ou com stdout vazio, é um erro não-bloqueador para a maioria dos eventos de hook: a ação prossegue, e a transcrição mostra um aviso `<hook name> hook error` seguido pela primeira linha de stderr, prefixado com `Failed with non-blocking status code:`. Para capturar o stderr completo, ative [debug logging](#debug-hooks).
904
905Eventos fora do modelo de decisão padrão mantêm suas próprias linhas na [tabela por evento](#exit-code-2-behavior-per-event): `WorktreeCreate` falha na criação em qualquer saída não-zero não importa o que seu JSON diz, e eventos que descartam saída de hook inteiramente, como `StopFailure`, ignoram seu JSON em cada código de saída, além de campos de efeito colateral como `terminalSequence`, que ainda disparam.
906
907Um hook que não consegue iniciar cai no mesmo balde não-bloqueador. Quando o caminho do script não existe ou não é executável, o shell sai com um código como 127 e você vê o mesmo aviso com a mensagem do interpretador, por exemplo `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Para a maioria dos eventos de hook, a ação prossegue. Quando você configura um hook de política, observe este aviso em sua primeira execução: um caminho digitado incorretamente em `settings.json` deixa o portão silenciosamente desabilitado.
908
709<Warning>909<Warning>
710 Para a maioria dos eventos de hook, apenas o código de saída 2 bloqueia a ação. O Claude Code trata o código de saída 1 como um erro não-bloqueador e prossegue com a ação, mesmo que 1 seja o código de falha Unix convencional. Se seu hook se destina a impor uma política, use `exit 2`. A exceção é `WorktreeCreate`, onde qualquer código de saída não-zero aborta a criação de worktree.910 Para a maioria dos eventos de hook, código de saída 2 é o único código de saída que bloqueia apenas através do código. Sem JSON válido em stdout, Claude Code trata código de saída 1 como um erro não-bloqueador e prossegue com a ação, mesmo que 1 seja o código de falha Unix convencional. Se seu hook se destina a impor uma política, use `exit 2`. Os eventos de worktree diferem: qualquer código de saída não-zero de `WorktreeCreate` aborta a criação de worktree, e qualquer código de saída não-zero de `WorktreeRemove` faz a remoção de worktree falhar se o diretório ainda existir depois.
711</Warning>911</Warning>
712 912
913<h4 id="timeouts">
914 Timeouts
915</h4>
916
917Além de um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), Claude Code cancela um hook `command`, `http` ou `mcp_tool` que atinge seu [`timeout`](#common-fields), descartando a saída do hook, portanto na maioria dos eventos um hook expirado não renderiza decisão.
918
919Em [`PreModelSwitch`](#premodelswitch), um hook cancelado em seu timeout bloqueia a mudança de modelo. Em `PreToolUse`, as duas famílias de hook diferem:
920
921* Um hook `command`, `http` ou `mcp_tool` expirado não bloqueia a chamada da ferramenta. A chamada continua através do [fluxo de permissão](/docs/pt/permissions) normal, portanto não conte com um hook travado para agir como um portão.
922* Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) que excede seu timeout [bloqueia a chamada da ferramenta](#pretooluse).
923
713<h4 id="exit-code-2-behavior-per-event">924<h4 id="exit-code-2-behavior-per-event">
714 Comportamento de código de saída 2 por evento925 Comportamento de código de saída 2 por evento
715</h4>926</h4>
717Código de saída 2 é a forma de um hook sinalizar "pare, não faça isso". O efeito depende do evento, porque alguns eventos representam ações que podem ser bloqueadas (como uma chamada de ferramenta que ainda não aconteceu) e outros representam coisas que já aconteceram ou não podem ser prevenidas.928Código de saída 2 é a forma de um hook sinalizar "pare, não faça isso". O efeito depende do evento, porque alguns eventos representam ações que podem ser bloqueadas (como uma chamada de ferramenta que ainda não aconteceu) e outros representam coisas que já aconteceram ou não podem ser prevenidas.
718 929
719| Evento de hook | Pode bloquear? | O que acontece na saída 2 |930| Evento de hook | Pode bloquear? | O que acontece na saída 2 |
720| :-------------------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |931| :-------------------- | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
721| `PreToolUse` | Sim | Bloqueia a chamada da ferramenta |932| `PreToolUse` | Sim | Bloqueia a chamada da ferramenta |
722| `PermissionRequest` | Sim | Nega a permissão |933| `PermissionRequest` | Não | Código de saída 2 não é honrado para este evento e o fluxo de permissão prossegue inalterado. Negue através do objeto [`decision`](#permissionrequest-decision-control) em vez disso |
723| `UserPromptSubmit` | Sim | Bloqueia o processamento de prompt e apaga o prompt |934| `UserPromptSubmit` | Sim | Bloqueia o processamento de prompt e apaga o prompt |
724| `UserPromptExpansion` | Sim | Bloqueia a expansão |935| `UserPromptExpansion` | Sim | Bloqueia a expansão |
725| `Stop` | Sim | Previne Claude de parar, continua a conversa |936| `Stop` | Sim | Previne Claude de parar, continua a conversa |
728| `TaskCreated` | Sim | Reverte a criação de tarefa |939| `TaskCreated` | Sim | Reverte a criação de tarefa |
729| `TaskCompleted` | Sim | Previne a tarefa de ser marcada como concluída |940| `TaskCompleted` | Sim | Previne a tarefa de ser marcada como concluída |
730| `ConfigChange` | Sim | Bloqueia a mudança de configuração de entrar em efeito (exceto `policy_settings`) |941| `ConfigChange` | Sim | Bloqueia a mudança de configuração de entrar em efeito (exceto `policy_settings`) |
731| `StopFailure` | Não | Saída e código de saída são ignorados |942| `StopFailure` | Não | Saída e código de saída são ignorados, exceto `terminalSequence` |
732| `PostToolUse` | Não | Mostra stderr ao Claude; a ferramenta já executou |943| `PostToolUse` | Não | Mostra stderr ao Claude; a ferramenta já executou |
733| `PostToolUseFailure` | Não | Mostra stderr ao Claude; a ferramenta já falhou |944| `PostToolUseFailure` | Não | Mostra stderr ao Claude; a ferramenta já falhou |
734| `PostToolBatch` | Sim | Para o loop agentic antes da próxima chamada de modelo |945| `PostToolBatch` | Sim | Para o loop agentic antes da próxima chamada de modelo |
735| `PermissionDenied` | Não | Código de saída e stderr são ignorados porque a negação já ocorreu. Use JSON `hookSpecificOutput.retry: true` para dizer ao modelo que pode tentar novamente |946| `PermissionDenied` | Não | Código de saída e stderr são ignorados porque a negação já ocorreu. Use JSON `hookSpecificOutput.retry: true` para dizer ao modelo que pode tentar novamente; Claude Code ignora `retry: true` para [negações sem veredicto](#permissiondenied-decision-control) |
736| `Notification` | Não | Mostra stderr apenas ao usuário |947| `Notification` | Não | Código de saída e stderr são ignorados |
737| `SubagentStart` | Não | Mostra stderr apenas ao usuário |948| `SubagentStart` | Não | Mostra stderr apenas ao usuário |
738| `SessionStart` | Não | Mostra stderr apenas ao usuário |949| `SessionStart` | Não | Mostra stderr apenas ao usuário |
739| `Setup` | Não | Mostra stderr apenas ao usuário |950| `Setup` | Não | Código de saída e stderr são ignorados |
740| `SessionEnd` | Não | Mostra stderr apenas ao usuário |951| `SessionEnd` | Não | Mostra stderr apenas ao usuário |
741| `CwdChanged` | Não | Mostra stderr apenas ao usuário |952| `CwdChanged` | Não | Mostra stderr apenas ao usuário |
953| `DirectoryAdded` | Não | Stderr vai para o log de debug; o diretório já foi adicionado |
742| `FileChanged` | Não | Mostra stderr apenas ao usuário |954| `FileChanged` | Não | Mostra stderr apenas ao usuário |
743| `PreCompact` | Sim | Bloqueia compactação |955| `PreCompact` | Sim | Bloqueia compactação |
744| `PostCompact` | Não | Mostra stderr apenas ao usuário |956| `PostCompact` | Não | Mostra stderr apenas ao usuário |
957| `PreModelSwitch` | Sim | Bloqueia a mudança de modelo e mostra stderr ao usuário |
958| `PostModelSwitch` | Não | Mostra stderr apenas ao usuário; o modelo já mudou |
745| `Elicitation` | Sim | Nega a elicitação |959| `Elicitation` | Sim | Nega a elicitação |
746| `ElicitationResult` | Sim | Bloqueia a resposta (ação se torna decline) |960| `ElicitationResult` | Sim | Bloqueia a resposta (ação se torna decline) |
747| `WorktreeCreate` | Sim | Qualquer código de saída não-zero causa falha na criação de worktree |961| `WorktreeCreate` | Sim | Qualquer código de saída não-zero causa falha na criação de worktree |
748| `WorktreeRemove` | Não | Falhas são registradas apenas em modo debug |962| `WorktreeRemove` | Sim | Qualquer código de saída não-zero causa falha na remoção de worktree se o diretório ainda existir depois. Consulte [WorktreeRemove](#worktreeremove) para o que acontece com o diretório |
749| `InstructionsLoaded` | Não | Código de saída é ignorado |963| `InstructionsLoaded` | Não | Código de saída é ignorado |
750| `MessageDisplay` | Não | O texto original é exibido |964| `MessageDisplay` | Não | O texto original é exibido |
751 965
752Para `SessionStart`, `Setup` e `SubagentStart`, o stderr de código de saída 2 é renderizado na transcrição como um aviso `<hook name> hook error`, da mesma forma que um [erro não-bloqueador](#exit-code-output) faz. Claude não vê isso, e a sessão ou subagente prossegue. Para `SubagentStart`, o aviso aparece na própria transcrição do subagente, não na conversa pai.966Para `SessionStart`, `SubagentStart` e `PostModelSwitch`, Claude Code renderiza o stderr de código de saída 2 na transcrição como um aviso `<hook name> hook error`, da mesma forma que renderiza um [erro não-bloqueador](#exit-code-output). Claude não vê, e a sessão ou subagente prossegue. Para `SubagentStart`, o aviso aparece na própria transcrição do subagente, não na conversa pai.
753
754A partir do Claude Code v2.1.199, `SessionStart`, `Setup` e `SubagentStart` mostram stderr de código de saída 2 na transcrição. Versões anteriores o escreviam apenas no log de debug.
755 967
756<h3 id="http-response-handling">968<h3 id="http-response-handling">
757 Tratamento de resposta HTTP969 Tratamento de resposta HTTP
758</h3>970</h3>
759 971
760Hooks HTTP usam códigos de status HTTP e corpos de resposta em vez de códigos de saída e stdout:972Hooks HTTP usam códigos de status HTTP e corpos de resposta em vez de códigos de saída e stdout. Os resultados abaixo se aplicam à maioria dos eventos; um evento com seu próprio contrato de falha na [tabela por evento](#exit-code-2-behavior-per-event), como `WorktreeCreate`, aplica esse contrato a um hook HTTP falhado também:
761 973
762* **2xx com corpo vazio**: sucesso, equivalente a código de saída 0 sem saída974* **2xx com corpo vazio**: sucesso, equivalente a código de saída 0 sem saída
763* **2xx com corpo de texto simples**: sucesso, o texto é adicionado como contexto975* **2xx com corpo de objeto JSON**: analisado usando o mesmo esquema [saída JSON](#json-output) que hooks de comando. Um corpo que falha na validação de esquema é um erro não-bloqueador
764* **2xx com corpo JSON**: sucesso, analisado usando o mesmo esquema [saída JSON](#json-output) que hooks de comando976* **2xx com qualquer outro corpo, como texto simples**: erro não-bloqueador, tratado da mesma forma que um status não-2xx. Claude Code não adiciona o texto ao contexto de Claude
765* **Status não-2xx**: erro não-bloqueador, execução continua977* **Status não-2xx**: erro não-bloqueador, execução continua
766* **Falha de conexão ou timeout**: erro não-bloqueador, execução continua978* **Falha de conexão**: erro não-bloqueador, execução continua
979* **Timeout**: o hook é cancelado, conforme descrito em [Timeouts](#timeouts)
767 980
768Diferentemente de hooks de comando, hooks HTTP não podem sinalizar um erro bloqueador apenas através de códigos de status. Para bloquear uma chamada de ferramenta ou negar uma permissão, retorne uma resposta 2xx com um corpo JSON contendo os campos de decisão apropriados.981Diferentemente de hooks de comando, hooks HTTP não podem sinalizar um erro bloqueador apenas através de códigos de status. Para bloquear uma chamada de ferramenta ou negar uma permissão, retorne uma resposta 2xx com um corpo JSON contendo os campos de decisão apropriados.
769 982
771 Saída JSON984 Saída JSON
772</h3>985</h3>
773 986
774Códigos de saída permitem você bloquear ou ficar em silêncio, mas saída JSON oferece controle mais granular. Em vez de sair com código 2 para bloquear, saia 0 e imprima um objeto JSON em stdout. O Claude Code lê campos específicos desse JSON para controlar comportamento, incluindo [controle de decisão](#decision-control) para bloquear, permitir ou escalar para o usuário.987Códigos de saída permitem você bloquear ou ficar em silêncio, mas saída JSON oferece controle mais granular. Em vez de sair com código 2 para bloquear, saia 0 e imprima um objeto JSON em stdout. Claude Code lê campos específicos desse JSON para controlar comportamento, incluindo [controle de decisão](#decision-control) para bloquear, permitir ou escalar para o usuário.
775 988
776<Note>989<Note>
777 Você deve escolher uma abordagem por hook, não ambas: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. O Claude Code apenas processa JSON na saída 0. Se você sair 2, qualquer JSON é ignorado.990 Escolha uma abordagem por hook: ou use códigos de saída sozinhos para sinalizar, ou saia 0 e imprima JSON para controle estruturado. Se você misturar, saída 2 mantém seu [efeito de bloqueio](#exit-code-2-behavior-per-event), e Claude Code ainda lê os campos JSON, com a exceção de elicitação única anotada em [Código de saída 2](#exit-code-2).
778</Note>991</Note>
779 992
780O stdout do seu hook deve conter apenas o objeto JSON. Se seu perfil shell imprime texto na inicialização, pode interferir com análise JSON. Consulte [Validação JSON falhou](/docs/pt/hooks-guide#json-validation-failed) no guia de troubleshooting.993O stdout do seu hook deve conter apenas o objeto JSON. Se seu perfil shell imprime texto na inicialização, pode interferir com análise JSON. Consulte [Hook JSON não tem efeito](/docs/pt/hooks-guide#hook-json-has-no-effect) no guia de troubleshooting.
994
995As strings de saída de hook `additionalContext`, `systemMessage` e `initialUserMessage`, e seu stdout simples, são limitadas a 10.000 caracteres:
781 996
782Saídas de hook, incluindo `additionalContext`, `systemMessage` e stdout simples, são limitadas a 10.000 caracteres. Saída que excede este limite é salva em um arquivo e substituída por uma visualização e caminho de arquivo, da mesma forma que resultados de ferramenta grandes são tratados.997* **Escopo**: Claude Code mede cada string por conta própria, mesmo quando vários hooks executam para o mesmo evento. Para saída JSON, cada campo é medido separadamente; stdout simples é medido como um todo.
998* **Acima do limite**: Claude Code salva a saída em um arquivo no diretório de sessão e a substitui pelo caminho do arquivo e uma visualização de até os primeiros 2.000 caracteres. Um resultado Bash grande válido é tratado da mesma forma, descrito em [Limites de saída](/docs/pt/tools-reference#output-limits). Diferentemente desse teto Bash, este limite não tem configuração ou variável de ambiente para aumentá-lo.
999* **Lendo o arquivo**: Claude Code não pede a Claude para ler o arquivo, portanto mantenha qualquer coisa que Claude sempre deva ver dentro do limite.
783 1000
784O objeto JSON suporta três tipos de campos:1001O objeto JSON suporta três tipos de campos:
785 1002
786* **Campos universais** como `continue` funcionam em todos os eventos. Esses são listados na tabela abaixo.1003* **Campos universais** como `continue` são listados na tabela abaixo. Cada evento os aceita, mas alguns eventos os descartam ou entregam `systemMessage` em outro lugar que não a transcrição. Cada seção de evento diz assim. `terminalSequence` funciona nesses eventos também, com as exceções listadas em [Emitir notificações de terminal](#emit-terminal-notifications).
787* **`decision` e `reason` de nível superior** são usados por alguns eventos para bloquear ou fornecer feedback.1004* **`decision` e `reason` de nível superior** são usados por alguns eventos para bloquear ou fornecer feedback.
788* **`hookSpecificOutput`** é um objeto aninhado para eventos que precisam de controle mais rico. Requer um campo `hookEventName` definido para o nome do evento.1005* **`hookSpecificOutput`** é um objeto aninhado para eventos que precisam de controle mais rico. Requer um campo `hookEventName` definido para o nome do evento.
789 1006
790| Campo | Padrão | Descrição |1007| Campo | Padrão | Descrição |
791| :----------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1008| :----------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
792| `continue` | `true` | Se `false`, Claude para de processar inteiramente após o hook executar. Tem precedência sobre qualquer campo de decisão específico do evento |1009| `continue` | `true` | Se `false`, Claude para de processar inteiramente após o hook executar. Tem precedência sobre qualquer campo de decisão específico do evento |
793| `stopReason` | nenhum | Mensagem mostrada ao usuário quando `continue` é `false`. Não mostrada ao Claude |1010| `stopReason` | nenhum | Mensagem mostrada ao usuário quando `continue` é `false`. Fica na conversa, portanto Claude a vê se a conversa continuar |
794| `suppressOutput` | `false` | Se `true`, oculta stdout do hook da transcrição. Stdout ainda aparece no log de debug |1011| `suppressOutput` | `false` | Não tem efeito: Claude Code aceita o campo mas não age sobre ele. O stdout de um hook bem-sucedido nunca é mostrado na transcrição e é registrado no log de debug |
795| `systemMessage` | nenhum | Mensagem de aviso mostrada ao usuário |1012| `systemMessage` | nenhum | Mensagem de aviso mostrada ao usuário. Em [Agent SDK](/docs/pt/agent-sdk/overview) e saída [`--output-format stream-json`](/docs/pt/headless), pode chegar como um [`SDKInformationalMessage`](/docs/pt/agent-sdk/typescript#sdkinformationalmessage) |
796| `terminalSequence` | nenhum | Uma sequência de escape de terminal para Claude Code emitir em seu nome, como uma notificação de desktop, título de janela ou sino. Restrito a OSC `0`/`1`/`2`/`9`/`99`/`777` e BEL. Se o valor contiver algo fora da lista de permissões, o campo é ignorado. Use isso em vez de escrever para `/dev/tty`, que não está disponível para hooks |1013| `terminalSequence` | nenhum | Uma sequência de escape de terminal para Claude Code emitir em seu nome, como uma notificação de desktop, título de janela ou sino. Restrito a OSC `0`/`1`/`2`/`9`/`99`/`777` e BEL. Se o valor contiver algo fora da lista de permissões, o campo é ignorado. Use isso em vez de escrever para `/dev/tty`, que não está disponível para hooks |
797 1014
798Para parar Claude inteiramente independentemente do tipo de evento:1015Para parar Claude inteiramente:
799 1016
800```json theme={null}1017```json theme={null}
801{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }1018{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
802```1019```
803 1020
1021Para hooks `PreToolUse` e `PostToolUse`, a parada se aplica mesmo quando a chamada da ferramenta falha ou é concluída enquanto Claude ainda está transmitindo uma resposta.
1022
804<h4 id="emit-terminal-notifications">1023<h4 id="emit-terminal-notifications">
805 Emitir notificações de terminal1024 Emitir notificações de terminal
806</h4>1025</h4>
807 1026
808O campo `terminalSequence` requer Claude Code v2.1.141 ou posterior.1027Hooks executam sem um terminal controlador, portanto escrever sequências de escape diretamente para `/dev/tty` falha. Em vez disso, retorne a sequência de escape no campo `terminalSequence` e Claude Code a emite para você através de seu próprio caminho de escrita de terminal. Isso é livre de corrida, funciona dentro de tmux e GNU screen, e funciona no Windows onde não há `/dev/tty`.
809
810Hooks executam sem um terminal controlador, então escrever sequências de escape diretamente para `/dev/tty` falha. Em vez disso, retorne a sequência de escape no campo `terminalSequence` e Claude Code a emite para você através de seu próprio caminho de escrita de terminal. Isso é livre de corrida, funciona dentro de tmux e GNU screen, e funciona no Windows onde não há `/dev/tty`.
811 1028
812O campo aceita uma string de uma ou mais sequências de escape na lista de permissões:1029O campo aceita uma string de uma ou mais sequências de escape na lista de permissões:
813 1030
819 1036
820Sequências podem ser terminadas com BEL ou com ST. Qualquer coisa fora da lista de permissões, incluindo sequências de cursor e cor CSI, sequências de paleta OSC, hiperlinks OSC 8, escritas de área de transferência OSC 52 e OSC 1337, é rejeitada e o campo é ignorado.1037Sequências podem ser terminadas com BEL ou com ST. Qualquer coisa fora da lista de permissões, incluindo sequências de cursor e cor CSI, sequências de paleta OSC, hiperlinks OSC 8, escritas de área de transferência OSC 52 e OSC 1337, é rejeitada e o campo é ignorado.
821 1038
1039Claude Code escreve a sequência em si quando processa a saída do seu hook, portanto o campo funciona em eventos que descartam `systemMessage` e `continue`, como `Notification` e `StopFailure`. Tem dois limites:
1040
1041* Claude Code escreve a sequência apenas em uma sessão interativa, e apenas enquanto sua interface está na tela. Em modo não-interativo com a flag `-p` e no Agent SDK, ignora o campo.
1042* Um hook de comando `WorktreeCreate` não pode retornar JSON, porque Claude Code lê seu stdout como o caminho de worktree. Um hook HTTP `WorktreeCreate` retorna JSON e pode incluir o campo.
1043
822O exemplo abaixo dispara uma notificação de desktop de um hook `Notification`. A sequência de escape é construída com `printf` escapes octais para que os bytes de controle nunca apareçam na linha de comando do shell, e `jq -n --arg` constrói a saída JSON para que aspas, barras invertidas e quebras de linha na mensagem de notificação sejam escapadas corretamente:1044O exemplo abaixo dispara uma notificação de desktop de um hook `Notification`. A sequência de escape é construída com `printf` escapes octais para que os bytes de controle nunca apareçam na linha de comando do shell, e `jq -n --arg` constrói a saída JSON para que aspas, barras invertidas e quebras de linha na mensagem de notificação sejam escapadas corretamente:
823 1045
824```bash theme={null}1046```bash theme={null}
825#!/bin/bash1047#!/bin/bash
826# Hook de notificação: ping no desktop quando Claude Code precisa de atenção.1048# Hook de notificação: ping no desktop quando Claude Code precisa de atenção.
827input=$(cat)1049input=$(cat)
828title="Claude Code'1050title="Claude Code"
829body=$(jq -r '.message // 'Needs your attention"' <<<"$input")1051body=$(jq -r '.message // "Needs your attention"' <<<"$input")
830seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")1052seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
831jq -nc --arg seq "$seq" '{terminalSequence: $seq}'1053jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
832```1054```
833 1055
834A forma `{ "terminalSequence": "..." }` é a mesma de qualquer shell ou linguagem. No Windows, construa a string de escape em PowerShell ou um script e emita o mesmo objeto JSON.1056A forma `{ "terminalSequence": "..." }` é a mesma de qualquer shell ou linguagem.
835
836<Note>
837 `terminalSequence` é a substituição suportada para hooks que anteriormente escreviam sequências de escape diretamente para `/dev/tty`. A lista de permissões é restrita a sequências que não podem mover o cursor ou alterar cores, para que um hook nunca possa corromper um prompt na tela.
838</Note>
839 1057
840<h4 id="add-context-for-claude">1058<h4 id="add-context-for-claude">
841 Adicionar contexto para Claude1059 Adicionar contexto para Claude
842</h4>1060</h4>
843 1061
844O campo `additionalContext` passa uma string do seu hook para a janela de contexto do Claude. O Claude Code envolve a string em um lembrete do sistema e a insere na conversa no ponto onde o hook disparou. Claude lê o lembrete na próxima solicitação de modelo, mas não aparece como uma mensagem de chat na interface.1062O campo `additionalContext` passa uma string do seu hook para a janela de contexto do Claude. Claude Code envolve a string em um lembrete do sistema e a insere na conversa no ponto onde o hook disparou. Claude lê o lembrete na próxima solicitação de modelo, mas não aparece como uma mensagem de chat na interface.
845 1063
846Retorne `additionalContext` dentro de `hookSpecificOutput` ao lado do nome do evento:1064Retorne `additionalContext` dentro de `hookSpecificOutput` ao lado do nome do evento:
847 1065
856 1074
857Onde o lembrete aparece depende do evento:1075Onde o lembrete aparece depende do evento:
858 1076
859* [SessionStart](#sessionstart), [Setup](#setup) e [SubagentStart](#subagentstart): no início da conversa, antes do primeiro prompt1077* [SessionStart](#sessionstart) e [SubagentStart](#subagentstart): no início da conversa, antes do primeiro prompt
860* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): ao lado do prompt enviado1078* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): ao lado do prompt enviado
861* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): ao lado do resultado da ferramenta1079* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): ao lado do resultado da ferramenta
862* [Stop](#stop) e [SubagentStop](#subagentstop): no final da rodada. A conversa continua para que Claude possa agir sobre o feedback. Consulte [Controle de decisão Stop](#stop-decision-control)1080* [Stop](#stop) e [SubagentStop](#subagentstop): no final da rodada. A conversa continua para que Claude possa agir sobre o feedback. Consulte [Controle de decisão Stop](#stop-decision-control)
1081* [PostModelSwitch](#postmodelswitch): com a próxima solicitação após a mudança. Consulte [Controle de decisão PostModelSwitch](#postmodelswitch-decision-control) para timing
863 1082
864Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores. Se um valor exceder 10.000 caracteres, o Claude Code escreve o texto completo em um arquivo no diretório de sessão e passa ao Claude o caminho do arquivo com uma visualização curta em vez disso.1083Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores.
1084
1085Se um valor exceder 10.000 caracteres, Claude Code escreve o texto em um arquivo no diretório de sessão e passa Claude o caminho do arquivo com uma visualização de até os primeiros 2.000 caracteres em vez disso. Claude pode ler o arquivo, mas Claude Code não pede a Claude para.
865 1086
866Use `additionalContext` para informações que Claude deve saber sobre o estado atual do seu ambiente ou a operação que acabou de executar:1087Use `additionalContext` para informações que Claude deve saber sobre o estado atual do seu ambiente ou a operação que acabou de executar:
867 1088
873 1094
874Escreva o texto como declarações factuais em vez de instruções de sistema imperativas. Frases como "O alvo de implantação é produção" ou "Este repositório usa `bun test`" lê como informação de projeto. Texto enquadrado como comandos de sistema fora de banda pode disparar as defesas de injeção de prompt do Claude, o que faz com que Claude superficialize o texto para você em vez de tratá-lo como contexto.1095Escreva o texto como declarações factuais em vez de instruções de sistema imperativas. Frases como "O alvo de implantação é produção" ou "Este repositório usa `bun test`" lê como informação de projeto. Texto enquadrado como comandos de sistema fora de banda pode disparar as defesas de injeção de prompt do Claude, o que faz com que Claude superficialize o texto para você em vez de tratá-lo como contexto.
875 1096
876Uma vez injetado, o texto é salvo na transcrição de sessão. Para eventos de mid-sessão como `PostToolUse` ou `UserPromptSubmit`, retomar com `--continue` ou `--resume` reproduz o texto salvo em vez de re-executar o hook para turnos anteriores, então valores como timestamps ou SHAs de commit ficam obsoletos na retomada. Hooks `SessionStart` executam novamente na retomada com `source` definido como `"resume"`, para que possam atualizar seu contexto.1097Claude Code salva o texto injetado na transcrição de sessão. Para eventos de mid-sessão como `PostToolUse` ou `UserPromptSubmit`, quando você retoma com `--continue` ou `--resume`, Claude Code reproduz o texto salvo em vez de re-executar o hook para turnos anteriores, portanto valores como timestamps ou SHAs de commit ficam obsoletos. Hooks `SessionStart` executam novamente na retomada com `source` definido como `"resume"`, ou `"fork"` se você adicionou `--fork-session`, para que possam atualizar seu contexto.
877 1098
878<h4 id="decision-control">1099<h4 id="decision-control">
879 Controle de decisão1100 Controle de decisão
882Nem todo evento suporta bloqueio ou controle de comportamento através de JSON. Os eventos que fazem cada um usam um conjunto diferente de campos para expressar essa decisão. Use esta tabela como referência rápida antes de escrever um hook:1103Nem todo evento suporta bloqueio ou controle de comportamento através de JSON. Os eventos que fazem cada um usam um conjunto diferente de campos para expressar essa decisão. Use esta tabela como referência rápida antes de escrever um hook:
883 1104
884| Eventos | Padrão de decisão | Campos-chave |1105| Eventos | Padrão de decisão | Campos-chave |
885| :---------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1106| :---------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
886| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | `decision` de nível superior | `decision: "block"`, `reason`. Stop e SubagentStop também aceitam `hookSpecificOutput.additionalContext` para [feedback não-erro que continua a conversa](#stop-decision-control) |1107| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | `decision` de nível superior | `decision: "block"`, `reason`. Stop e SubagentStop também aceitam `hookSpecificOutput.additionalContext` para [feedback não-erro que continua a conversa](#stop-decision-control) |
887| TeammateIdle, TaskCreated, TaskCompleted | Código de saída ou `continue: false` | Código de saída 2 bloqueia a ação com feedback de stderr. JSON `{"continue": false, "stopReason": "..."}` também para o colega inteiramente, correspondendo ao comportamento do hook `Stop` |1108| TeammateIdle, TaskCompleted | Código de saída ou `continue: false` | Código de saída 2 bloqueia a ação com feedback de stderr. JSON `{"continue": false, "stopReason": "..."}` também para o colega inteiramente, correspondendo ao comportamento do hook `Stop`; [TaskCompleted ignora quando a ferramenta `TaskUpdate` disparou o evento](#taskcompleted-decision-control) |
1109| TaskCreated | Código de saída ou `decision` de nível superior | Código de saída 2 ou `decision: "block"` [cancela a tarefa](#taskcreated-decision-control) e retorna a mensagem para Claude. `continue: false` é ignorado |
888| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |1110| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |
1111| PreModelSwitch | `hookSpecificOutput` ou `decision` de nível superior | `permissionDecision` (allow/deny/ask), `permissionDecisionReason`. `decision: "block"` também [cancela a mudança](#premodelswitch-decision-control) |
889| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |1112| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |
890| PermissionDenied | `hookSpecificOutput` | `retry: true` diz ao modelo que pode tentar novamente a chamada de ferramenta negada |1113| PermissionDenied | `hookSpecificOutput` | `retry: true` diz ao modelo que pode tentar novamente a chamada de ferramenta negada; Claude Code ignora para [negações sem veredicto](#permissiondenied-decision-control) |
891| WorktreeCreate | retorno de caminho | Hook de comando imprime caminho em stdout; hook HTTP retorna `hookSpecificOutput.worktreePath`. Falha de hook ou caminho ausente falha na criação |1114| WorktreeCreate | retorno de caminho | Hook de comando imprime caminho em stdout; hook HTTP retorna `hookSpecificOutput.worktreePath`. Falha de hook ou caminho ausente falha na criação |
1115| WorktreeRemove | Código de saída | Qualquer código de saída não-zero faz a remoção falhar se o diretório ainda existir depois. Saída JSON é descartada |
892| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valores de campo de formulário para accept) |1116| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valores de campo de formulário para accept) |
893| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valores de campo de formulário override) |1117| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valores de campo de formulário override) |
894| MessageDisplay | `hookSpecificOutput` | `displayContent` substitui o texto exibido na tela. Apenas exibição: a transcrição e o que Claude vê mantêm o original |1118| MessageDisplay | `hookSpecificOutput` | `displayContent` substitui o texto exibido na tela. Apenas exibição: a transcrição e o que Claude vê mantêm o original |
895| SessionStart, Setup, SubagentStart | Apenas contexto | `hookSpecificOutput.additionalContext` adiciona contexto para Claude. SessionStart também aceita [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Sem bloqueio ou controle de decisão |1119| SessionStart, SubagentStart, PostModelSwitch | Apenas contexto | `hookSpecificOutput.additionalContext` adiciona contexto para Claude. SessionStart também aceita [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Sem bloqueio ou controle de decisão |
896| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | Nenhum | Sem controle de decisão. Usado para efeitos colaterais como logging ou limpeza |1120| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | Nenhum | Sem controle de decisão. Usado para efeitos colaterais como logging ou limpeza |
897 1121
898Alguns eventos também podem reescrever conteúdo em vez de apenas permitir ou bloquear:1122Alguns eventos também podem reescrever conteúdo em vez de apenas permitir ou bloquear:
899 1123
908 1132
909<Tabs>1133<Tabs>
910 <Tab title="Decisão de nível superior">1134 <Tab title="Decisão de nível superior">
911 Usado por `UserPromptSubmit`, `UserPromptExpansion`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `Stop`, `SubagentStop`, `ConfigChange` e `PreCompact`. O único valor é `"block"`. Para permitir que a ação prossiga, omita `decision` do seu JSON ou saia 0 sem qualquer JSON:1135 O único valor para `decision` é `"block"`. Para permitir que a ação prossiga, omita `decision` do seu JSON, ou saia 0 sem qualquer JSON:
912 1136
913 ```json theme={null}1137 ```json theme={null}
914 {1138 {
957 Eventos de hook1181 Eventos de hook
958</h2>1182</h2>
959 1183
960Cada evento corresponde a um ponto no ciclo de vida do Claude Code onde hooks podem executar. As seções abaixo são ordenadas para corresponder ao ciclo de vida: da configuração de sessão através do loop agentic até o fim da sessão. Cada seção descreve quando o evento dispara, quais matchers suporta, a entrada JSON que recebe e como controlar comportamento através de saída.1184Cada evento corresponde a um ponto no ciclo de vida do Claude Code onde os hooks podem ser executados. As seções abaixo estão ordenadas para corresponder ao ciclo de vida: desde a configuração da sessão através do loop agentic até o final da sessão. Cada seção descreve quando o evento é disparado, quais matchers ele suporta, a entrada JSON que recebe e como controlar o comportamento através da saída.
961 1185
962<h3 id="sessionstart">1186<h3 id="sessionstart">
963 SessionStart1187 SessionStart
964</h3>1188</h3>
965 1189
966Executa quando Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento como problemas existentes ou mudanças recentes em seu codebase, ou configurar variáveis de ambiente. Para contexto estático que não requer um script, use [CLAUDE.md](/docs/pt/memory) em vez disso.1190Executado quando Claude Code inicia uma nova sessão ou retoma uma sessão existente. Útil para carregar contexto de desenvolvimento como problemas existentes ou mudanças recentes no seu código, ou configurar variáveis de ambiente. Para contexto estático que não requer um script, use [CLAUDE.md](/docs/pt/memory) em vez disso.
967 1191
968SessionStart executa em cada sessão, então mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados.1192SessionStart é executado em cada sessão, portanto mantenha esses hooks rápidos. Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados. Veja [campos de hook de ferramenta MCP](#mcp-tool-hook-fields) para quando hooks `mcp_tool` são executados.
969 1193
970O valor do matcher corresponde a como a sessão foi iniciada:1194O valor do matcher corresponde a como a sessão foi iniciada:
971 1195
972| Matcher | Quando dispara |1196| Matcher | Quando é disparado |
973| :-------- | :------------------------------------ |1197| :-------- | :---------------------------------------------------------------------------------------------------------------------------------- |
974| `startup` | Nova sessão |1198| `startup` | Nova sessão |
975| `resume` | `--resume`, `--continue` ou `/resume` |1199| `resume` | `--resume`, `--continue`, ou `/resume` |
976| `clear` | `/clear` |1200| `clear` | `/clear` |
977| `compact` | Compactação automática ou manual |1201| `compact` | Compactação automática ou manual |
1202| `fork` | Uma nova sessão bifurcada de uma existente: `--fork-session` com `--resume` ou `--continue`, a cópia de fundo `/fork`, ou `/branch` |
1203
1204Antes da v2.1.214, sessões bifurcadas relatavam fonte `"resume"`.
1205
1206Quando você inicia uma sessão interativa, retoma uma conversa no lançamento com `--continue` ou `--resume`, ou executa `/clear`, os hooks SessionStart são executados em segundo plano. Você pode digitar imediatamente, e uma conversa que você retomou aparece sem esperar pelos hooks. A primeira resposta do Claude ainda espera os hooks terminarem, portanto seu contexto chega ao Claude.
1207
1208Quando você muda de conversas com `/resume` dentro de uma sessão, a mudança espera os hooks terminarem. Se você executar `/clear` ou mudar para outra conversa enquanto os hooks de fundo ainda estão em execução, nada que eles retornem se aplica à sessão.
1209
1210A mesma espera se aplica no lançamento, incluindo uma sessão retomada: um prompt que você envia enquanto os hooks SessionStart ainda estão em execução não chega ao Claude até que terminem.
1211
1212Durante qualquer espera, pressione `Esc` para levar o prompt de volta para a entrada sem enviá-lo. Os hooks continuam em execução.
978 1213
979<h4 id="sessionstart-input">1214<h4 id="sessionstart-input">
980 Entrada de SessionStart1215 Entrada SessionStart
981</h4>1216</h4>
982 1217
983Além dos [campos de entrada comuns](#common-input-fields), hooks SessionStart recebem `source` e opcionalmente `model`, `agent_type` e `session_title`:1218Além dos [campos de entrada comuns](#common-input-fields), os hooks SessionStart recebem `source` e opcionalmente `model`, `agent_type` e `session_title`:
984 1219
985| Campo | Descrição |1220| Campo | Descrição |
986| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1221| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
987| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear` ou `"compact"` após compactação |1222| `source` | Como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear`, `"compact"` após compactação, ou `"fork"` para uma nova sessão bifurcada de uma existente |
988| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através de recuperação de conversa, então verifique o campo antes de lê-lo |1223| `model` | O identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através da recuperação de conversa, portanto verifique o campo antes de lê-lo |
989| `agent_type` | O nome do agente, presente quando você inicia Claude Code com `claude --agent <name>` |1224| `agent_type` | O nome do agente, presente quando você inicia Claude Code com `claude --agent <name>` |
990| `session_title` | O título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente |1225| `session_title` | O título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente |
991 1226
1227Quando `source` é `"resume"` ou `"fork"` e a transcrição contém pelo menos uma resposta do Claude, os hooks SessionStart também recebem os quatro campos abaixo. Seu hook pode usá-los para relatar qual é o custo de retomar uma conversa obsoleta antes da primeira solicitação, por exemplo em uma [`systemMessage`](#json-output). Esses campos requerem Claude Code v2.1.251 ou posterior.
1228
1229| Campo | Descrição |
1230| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1231| `seconds_since_last_response` | Segundos de relógio de parede desde a última resposta na transcrição retomada |
1232| `context_tokens` | Tokens que a primeira solicitação da sessão retomada reenvia como seu prompt |
1233| `prompt_cache_likely_expired` | `true` quando a última resposta é mais antiga que o [tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) da sessão ou uma compactação posterior substituiu a conversa em cache |
1234| `estimated_cache_write_usd` | Custo estimado em dólares americanos de escrever `context_tokens` no cache de prompt no modelo da sessão, excluindo a resposta |
1235
1236Este exemplo mostra a entrada para uma sessão retomada 90 minutos após sua última resposta:
1237
992```json theme={null}1238```json theme={null}
993{1239{
994 "session_id": "abc123",1240 "session_id": "abc123",
995 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1241 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
996 "cwd": "/Users/...",1242 "cwd": "/Users/...",
997 "hook_event_name": "SessionStart",1243 "hook_event_name": "SessionStart",
998 "source": "startup",1244 "source": "resume",
999 "model": "claude-sonnet-5"1245 "model": "claude-opus-5",
1246 "seconds_since_last_response": 5400,
1247 "context_tokens": 182340,
1248 "prompt_cache_likely_expired": true,
1249 "estimated_cache_write_usd": 1.1396
1000}1250}
1001```1251```
1002 1252
1003<h4 id="sessionstart-decision-control">1253<h4 id="sessionstart-decision-control">
1004 Controle de decisão de SessionStart1254 Controle de decisão SessionStart
1005</h4>1255</h4>
1006 1256
1007Qualquer texto que seu script de hook imprima em stdout é adicionado como contexto para Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:1257Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto do Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:
1008 1258
1009| Campo | Descrição |1259| Campo | Descrição |
1010| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1260| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1011| `additionalContext` | String adicionada ao contexto de Claude no início da conversa, antes do primeiro prompt. Consulte [Adicionar contexto para Claude](#add-context-for-claude) para saber como o texto é entregue e o que colocar nele |1261| `additionalContext` | String adicionada ao contexto do Claude no início da conversa, antes do primeiro prompt. Veja [Adicionar contexto para Claude](#add-context-for-claude) para como o texto é entregue e o que colocar nele |
1012| `initialUserMessage` | String usada como a primeira mensagem de usuário da sessão. Aplica-se em [modo não-interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo se nenhum prompt for fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Diferentemente de `additionalContext`, que se anexa a um turno existente, isso cria o turno |1262| `initialUserMessage` | String usada como a primeira mensagem do usuário da sessão. Aplica-se em [modo não interativo](/docs/pt/headless) com a flag `-p`, onde se torna o primeiro turno mesmo que nenhum prompt seja fornecido. Se um prompt for fornecido, ele segue como o próximo turno. Ao contrário de `additionalContext`, que se anexa a um turno existente, isso cria o turno |
1013| `sessionTitle` | Define o título da sessão, com o mesmo efeito que `/rename`. Use para nomear sessões automaticamente a partir da pasta de lançamento, branch git ou nome de worktree. Aplica-se apenas quando `source` é `"startup"` ou `"resume"`; ignorado em `"clear"` e `"compact"` |1263| `sessionTitle` | Define o título da sessão, com o mesmo efeito que `/rename`. Use para nomear sessões automaticamente a partir da pasta de lançamento, ramo git ou nome de worktree. Aplica-se quando `source` é `"startup"`, `"resume"` ou `"fork"`; ignorado em `"clear"` e `"compact"` |
1014| `watchPaths` | Array de caminhos absolutos para monitorar eventos [FileChanged](#filechanged) durante esta sessão |1264| `watchPaths` | Array de caminhos absolutos para observar eventos [FileChanged](#filechanged) durante esta sessão |
1015| `reloadSkills` | Boolean. Quando `true`, Claude Code re-escaneia os diretórios [skill](/docs/pt/skills) e comando após os hooks SessionStart completarem, então skills que o hook instalou estão disponíveis na mesma sessão, começando com o primeiro prompt |1265| `reloadSkills` | Booleano. Quando `true`, Claude Code verifica novamente os diretórios de [skill](/docs/pt/skills) e comando após os hooks SessionStart serem concluídos, portanto skills que o hook instalou estão disponíveis na mesma sessão, começando com o primeiro prompt |
1016 1266
1017```json theme={null}1267```json theme={null}
1018{1268{
1019 "hookSpecificOutput": {1269 "hookSpecificOutput": {
1020 "hookEventName": "SessionStart",1270 "hookEventName": "SessionStart",
1021 "additionalContext": "Branch atual: feat/auth-refactor\nMudanças não confirmadas: src/auth.ts, src/login.tsx\nProblema ativo: #4211 Migrar para OAuth2",1271 "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
1022 "sessionTitle": "auth-refactor"1272 "sessionTitle": "auth-refactor"
1023 }1273 }
1024}1274}
1025```1275```
1026 1276
1027Como stdout simples já chega ao Claude para este evento, um hook que apenas carrega contexto pode imprimir em stdout diretamente sem construir JSON. Use o formulário JSON quando você precisar combinar contexto com outros campos como `suppressOutput` ou `sessionTitle`.1277Como stdout simples já chega ao Claude para este evento, um hook que apenas carrega contexto pode imprimir para stdout diretamente sem construir JSON. Use a forma JSON quando você precisa combinar contexto com outros campos como `sessionTitle`.
1028 1278
1029Use `reloadSkills` quando um hook SessionStart instala ou atualiza skills. A descoberta de skill normalmente executa antes dos hooks SessionStart terminarem, então arquivos que o hook escreve em `~/.claude/skills/` ou `.claude/skills/` caso contrário apenas apareceriam na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a re-varredura:1279Use `reloadSkills` quando um hook SessionStart instala ou atualiza skills. A descoberta de skill normalmente é executada antes dos hooks SessionStart terminarem, portanto arquivos que o hook escreve em `~/.claude/skills/` ou `.claude/skills/` de outra forma só apareceriam na próxima sessão. Este exemplo sincroniza um repositório de skills compartilhado e solicita a nova verificação:
1030 1280
1031```bash theme={null}1281```bash theme={null}
1032#!/bin/bash1282#!/bin/bash
1037echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1287echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1038```1288```
1039 1289
1290A URL do repositório é um espaço reservado; substitua-a pelo seu próprio repositório de skills. Com o espaço reservado, o clone falha e imprime uma mensagem `fatal:` para stderr. Stderr de um hook SessionStart que sai com 0 é apenas informativo, portanto a solicitação `reloadSkills` ainda se aplica.
1291
1040<h4 id="persist-environment-variables">1292<h4 id="persist-environment-variables">
1041 Persistir variáveis de ambiente1293 Persistir variáveis de ambiente
1042</h4>1294</h4>
1043 1295
1044Hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos Bash subsequentes.1296Os hooks SessionStart têm acesso à variável de ambiente `CLAUDE_ENV_FILE`, que fornece um caminho de arquivo onde você pode persistir variáveis de ambiente para comandos Bash subsequentes.
1045 1297
1046Para definir variáveis de ambiente individuais, escreva declarações `export` para `CLAUDE_ENV_FILE`. Use append (`>>`) para preservar variáveis definidas por outros hooks:1298Para definir variáveis de ambiente individuais, escreva instruções `export` para `CLAUDE_ENV_FILE`. Use append (`>>`) para preservar variáveis definidas por outros hooks:
1047 1299
1048```bash theme={null}1300```bash theme={null}
1049#!/bin/bash1301#!/bin/bash
1064 1316
1065ENV_BEFORE=$(export -p | sort)1317ENV_BEFORE=$(export -p | sort)
1066 1318
1067# Execute seus comandos de configuração que modificam o ambiente1319# Run your setup commands that modify the environment
1068source ~/.nvm/nvm.sh1320source ~/.nvm/nvm.sh
1069nvm use 201321nvm use 20
1070 1322
1076exit 01328exit 0
1077```1329```
1078 1330
1079Qualquer variável escrita para este arquivo estará disponível em todos os comandos Bash subsequentes que o Claude Code executa durante a sessão.
1080
1081<Note>1331<Note>
1082 `CLAUDE_ENV_FILE` está disponível para SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged) hooks. Outros tipos de hook não têm acesso a esta variável.1332 `CLAUDE_ENV_FILE` está disponível para hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Outros tipos de hook não têm acesso a esta variável.
1083</Note>1333</Note>
1084 1334
1085<h3 id="setup">1335<h3 id="setup">
1086 Setup1336 Setup
1087</h3>1337</h3>
1088 1338
1089Dispara apenas quando você lança Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em [modo não-interativo](/docs/pt/headless) com a flag `-p`. Não dispara na inicialização normal. Use-o para instalação de dependência única ou limpeza agendada que você aciona explicitamente de CI ou scripts, separado da inicialização de sessão normal. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.1339Disparado apenas quando você inicia Claude Code com `--init-only`, ou com `--init` ou `--maintenance` em [modo não interativo](/docs/pt/headless) com a flag `-p`. Não é disparado no startup normal. Use-o para instalação de dependência única ou limpeza agendada que você dispara explicitamente de CI ou scripts, separado do startup normal da sessão. Para inicialização por sessão, use [SessionStart](#sessionstart) em vez disso.
1090 1340
1091O valor do matcher corresponde à flag CLI que acionou o hook:1341O valor do matcher corresponde à flag CLI que disparou o hook:
1092 1342
1093| Matcher | Quando dispara |1343| Matcher | Quando é disparado |
1094| :------------ | :----------------------------------------- |1344| :------------ | :----------------------------------------- |
1095| `init` | `claude --init-only` ou `claude -p --init` |1345| `init` | `claude --init-only` ou `claude -p --init` |
1096| `maintenance` | `claude -p --maintenance` |1346| `maintenance` | `claude -p --maintenance` |
1097 1347
1098`--init-only` executa hooks Setup e hooks SessionStart com o matcher `startup`, depois sai sem iniciar uma conversa. `--init` e `--maintenance` disparam hooks Setup apenas quando combinados com `-p`; em uma sessão interativa essas duas flags atualmente não disparam hooks Setup.1348Quando você executa `claude --init-only`, Claude Code executa hooks Setup e hooks `SessionStart` com o matcher `startup`, depois sai sem iniciar uma conversa.
1349
1350Quando você inicia ou continua uma conversa com `-p`, você também precisa fornecer um prompt, como um argumento ou canalizado em stdin. Você pode pular o prompt quando um hook `SessionStart` fornece [`initialUserMessage`](#sessionstart-decision-control) ou quando você retoma uma sessão com uma [chamada de ferramenta adiada](#defer-a-tool-call-for-later).
1099 1351
1100Porque Setup não dispara em cada lançamento, um plugin que precisa de uma dependência instalada não pode confiar apenas em Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Consulte o [diretório de dados persistentes](/docs/pt/plugins-reference#persistent-data-directory) para onde armazenar dependências instaladas.1352No sucesso, `--init-only` não imprime nada no terminal. Para confirmar que os hooks foram executados, comece com `claude --debug-file <path> --init-only`, substituindo `<path>` por um local de arquivo de log, e verifique o log para as entradas de hook Setup e SessionStart.
1353
1354Como Setup não é disparado a cada lançamento, um plugin que precisa de uma dependência instalada não pode contar apenas com Setup. O padrão prático é verificar a dependência no primeiro uso e instalar se ausente, por exemplo um hook ou skill que testa `${CLAUDE_PLUGIN_DATA}/node_modules` e executa `npm install` se ausente. Veja o [diretório de dados persistentes](/docs/pt/plugins-reference#persistent-data-directory) para onde armazenar dependências instaladas. Se você distribuir seu plugin através de um marketplace, você pode não precisar deste padrão: Claude Code [instala automaticamente dependências de pacote Node.js elegíveis](/docs/pt/plugins-reference#node-js-package-dependencies) quando armazena em cache o plugin.
1101 1355
1102<h4 id="setup-input">1356<h4 id="setup-input">
1103 Entrada de Setup1357 Entrada Setup
1104</h4>1358</h4>
1105 1359
1106Além dos [campos de entrada comuns](#common-input-fields), hooks Setup recebem um campo `trigger` definido como `"init"` ou `"maintenance"`:1360Além dos [campos de entrada comuns](#common-input-fields), os hooks Setup recebem um campo `trigger` definido como `"init"` ou `"maintenance"`:
1107 1361
1108```json theme={null}1362```json theme={null}
1109{1363{
1116```1370```
1117 1371
1118<h4 id="setup-decision-control">1372<h4 id="setup-decision-control">
1119 Controle de decisão de Setup1373 Controle de decisão Setup
1120</h4>1374</h4>
1121 1375
1122Hooks Setup não podem bloquear. Qualquer código de saída não-zero, incluindo 2, superficializa stderr ao usuário como um aviso de `<hook name> hook error`, e a execução continua. Em [modo não-interativo](/docs/pt/headless), a saída do hook aparece apenas quando você lança com `--verbose`.1376Os hooks Setup não podem bloquear; a execução continua em qualquer código de saída. Em cada código de saída, Claude Code descarta os [campos de saída JSON](#json-output) de um hook Setup, como `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Com `-p`, stdout, stderr e código de saída de um hook Setup aparecem na saída da execução apenas como [eventos `hook_response`](/docs/pt/headless#read-session-metadata) quando você inicia com `--output-format stream-json --verbose`.
1123
1124Para passar informação para o contexto de Claude, retorne `additionalContext` em saída JSON; stdout simples é escrito apenas no log de debug. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar esses campos específicos do evento:
1125
1126| Campo | Descrição |
1127| :------------------ | :-------------------------------------------------------------------------------------- |
1128| `additionalContext` | String adicionada ao contexto de Claude. Os valores de múltiplos hooks são concatenados |
1129
1130```json theme={null}
1131{
1132 "hookSpecificOutput": {
1133 "hookEventName": "Setup",
1134 "additionalContext": "Dependências instaladas: node_modules, .venv"
1135 }
1136}
1137```
1138 1377
1139Hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Variáveis escritas para esse arquivo persistem em comandos Bash subsequentes para a sessão, assim como em [hooks SessionStart](#persist-environment-variables). Apenas hooks `type: "command"` e `type: "mcp_tool"` são suportados.1378Os hooks Setup têm acesso a `CLAUDE_ENV_FILE`. Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes para a sessão, assim como em [hooks SessionStart](#persist-environment-variables). Apenas hooks `type: "command"` são executados em `Setup`. Um hook `type: "mcp_tool"` em `Setup` é sempre pulado, conforme descrito em [campos de hook de ferramenta MCP](#mcp-tool-hook-fields).
1140 1379
1141<h3 id="instructionsloaded">1380<h3 id="instructionsloaded">
1142 InstructionsLoaded1381 InstructionsLoaded
1143</h3>1382</h3>
1144 1383
1145Dispara quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado em contexto. Este evento dispara na inicialização da sessão para arquivos carregados com entusiasmo e novamente mais tarde quando arquivos são carregados preguiçosamente, por exemplo quando Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio ou controle de decisão. Executa assincronamente para fins de observabilidade.1384Disparado quando um arquivo `CLAUDE.md` ou `.claude/rules/*.md` é carregado no contexto. Este evento é disparado no início da sessão para arquivos carregados com entusiasmo e novamente mais tarde quando arquivos são carregados preguiçosamente, por exemplo quando Claude acessa um subdiretório que contém um `CLAUDE.md` aninhado ou quando regras condicionais com frontmatter `paths:` correspondem. O hook não suporta bloqueio ou controle de decisão. Ele é executado de forma assíncrona para fins de observabilidade.
1385
1386Este evento não é disparado quando Claude [lê `AGENTS.md` diretamente](/docs/pt/memory#agents-md) através da configuração **Project instructions**. Ele é disparado quando um `CLAUDE.md` importa seu `AGENTS.md`, com `load_reason` definido como `include` como para qualquer outro arquivo importado, e quando `CLAUDE.md` é um symlink para ele, como um carregamento normal de `CLAUDE.md`.
1146 1387
1147O matcher executa contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar apenas para arquivos carregados na inicialização da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar apenas para carregamentos preguiçosos.1388O matcher é executado contra `load_reason`. Por exemplo, use `"matcher": "session_start"` para disparar apenas para arquivos carregados no início da sessão, ou `"matcher": "path_glob_match|nested_traversal"` para disparar apenas para carregamentos preguiçosos.
1148 1389
1149<h4 id="instructionsloaded-input">1390<h4 id="instructionsloaded-input">
1150 Entrada de InstructionsLoaded1391 Entrada InstructionsLoaded
1151</h4>1392</h4>
1152 1393
1153Além dos [campos de entrada comuns](#common-input-fields), hooks InstructionsLoaded recebem esses campos:1394Além dos [campos de entrada comuns](#common-input-fields), os hooks InstructionsLoaded recebem estes campos:
1154 1395
1155| Campo | Descrição |1396| Campo | Descrição |
1156| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1397| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1157| `file_path` | Caminho absoluto para o arquivo de instrução que foi carregado |1398| `file_path` | Caminho absoluto para o arquivo de instrução que foi carregado |
1158| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |1399| `memory_type` | Escopo do arquivo: `"User"`, `"Project"`, `"Local"` ou `"Managed"` |
1159| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` dispara quando arquivos de instrução são re-carregados após um evento de compactação |1400| `load_reason` | Por que o arquivo foi carregado: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` ou `"compact"`. O valor `"compact"` é disparado quando arquivos de instrução são recarregados após um evento de compactação |
1160| `globs` | Padrões de glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente apenas para carregamentos `path_glob_match` |1401| `globs` | Padrões de glob de caminho do frontmatter `paths:` do arquivo, se houver. Presente apenas para carregamentos `path_glob_match` |
1161| `trigger_file_path` | Caminho para o arquivo cujo acesso acionou este carregamento, para carregamentos preguiçosos |1402| `trigger_file_path` | Caminho para o arquivo cujo acesso disparou este carregamento, para carregamentos preguiçosos |
1162| `parent_file_path` | Caminho para o arquivo de instrução pai que incluiu este, para carregamentos `include` |1403| `parent_file_path` | Caminho para o arquivo de instrução pai que incluiu este, para carregamentos `include` |
1163 1404
1164```json theme={null}1405```json theme={null}
1174```1415```
1175 1416
1176<h4 id="instructionsloaded-decision-control">1417<h4 id="instructionsloaded-decision-control">
1177 Controle de decisão de InstructionsLoaded1418 Controle de decisão InstructionsLoaded
1178</h4>1419</h4>
1179 1420
1180Hooks InstructionsLoaded não têm controle de decisão. Eles não podem bloquear ou modificar carregamento de instrução. Use este evento para logging de auditoria, rastreamento de conformidade ou observabilidade.1421Os hooks InstructionsLoaded não têm controle de decisão. Eles não podem bloquear ou modificar o carregamento de instruções. Claude Code descarta seus [campos de saída JSON](#json-output), como `systemMessage` e `continue`. Use este evento para auditoria de log, rastreamento de conformidade ou observabilidade.
1181 1422
1182<h3 id="userpromptsubmit">1423<h3 id="userpromptsubmit">
1183 UserPromptSubmit1424 UserPromptSubmit
1184</h3>1425</h3>
1185 1426
1186Executa quando o usuário submete um prompt, antes do Claude processá-lo. Isso permite que você adicione contexto adicional baseado no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.1427Executado quando o usuário envia um prompt, antes de Claude processá-lo. Isso permite que você adicione contexto adicional com base no prompt/conversa, valide prompts ou bloqueie certos tipos de prompts.
1187 1428
1188Hooks `UserPromptSubmit` têm um timeout padrão de 30 segundos para tipos `command`, `http` e `mcp_tool`, mais curto que o padrão de 600 segundos para esses tipos em outros eventos. Porque este hook executa antes de cada prompt e bloqueia processamento do modelo até que seja concluído, um hook travado paralisa a sessão. Se seu hook precisa de mais tempo, defina o campo `timeout` na entrada do hook.1429Os hooks `UserPromptSubmit` têm um tempo limite padrão de 30 segundos para tipos `command`, `http` e `mcp_tool`, mais curto que o padrão de 600 segundos para esses tipos na maioria dos outros eventos. Como este hook é executado antes de cada prompt e bloqueia o processamento do modelo até ser concluído, um hook travado paralisa a sessão. Se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1189 1430
1190Um hook `UserPromptSubmit` que atinge seu timeout é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A partir de v2.1.196, a transcrição mostra um aviso nomeando o hook, o timeout que disparou e que a saída foi descartada. Versões anteriores cancelam o hook sem aviso.1431Além de um hook de comando que você executa com [`async: true`](#run-hooks-in-the-background), um hook `UserPromptSubmit` command, HTTP ou MCP tool que atinge seu tempo limite é cancelado e sua saída, incluindo qualquer `additionalContext`, é descartada. O prompt ainda chega ao Claude sem esse contexto. A transcrição mostra um aviso nomeando o hook, o tempo limite que foi disparado e que a saída foi descartada.
1191 1432
1192Um hook de callback [Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu timeout bloqueia o prompt com uma mensagem nomeando o hook e o timeout, porque um callback lá pode estar atuando como um portão de política que não deve falhar aberto. A sessão continua. Antes de v2.1.208, um timeout de callback naquele evento terminava o turno com um erro de execução.1433Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `UserPromptSubmit` que atinge seu tempo limite bloqueia o prompt com uma mensagem nomeando o hook e o tempo limite, porque um callback lá pode estar agindo como um portão de política que não deve falhar aberto. A sessão continua. Antes da v2.1.208, um tempo limite de callback nesse evento terminava o turno com um erro de execução.
1193 1434
1194<h4 id="userpromptsubmit-input">1435<h4 id="userpromptsubmit-input">
1195 Entrada de UserPromptSubmit1436 Entrada UserPromptSubmit
1196</h4>1437</h4>
1197 1438
1198Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptSubmit recebem o campo `prompt` contendo o texto que o usuário submeteu.1439Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptSubmit recebem o campo `prompt` contendo o texto que o usuário enviou.
1199 1440
1200```json theme={null}1441```json theme={null}
1201{1442{
1209```1450```
1210 1451
1211<h4 id="userpromptsubmit-decision-control">1452<h4 id="userpromptsubmit-decision-control">
1212 Controle de decisão de UserPromptSubmit1453 Controle de decisão UserPromptSubmit
1213</h4>1454</h4>
1214 1455
1215Hooks `UserPromptSubmit` podem controlar se um prompt de usuário é processado e adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.1456Os hooks `UserPromptSubmit` podem controlar se um prompt do usuário é processado e adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.
1216 1457
1217Existem duas formas de adicionar contexto à conversa na saída 0:1458Existem duas maneiras de adicionar contexto à conversa no código de saída 0:
1218 1459
1219* **Stdout de texto simples**: qualquer texto não-JSON escrito em stdout é adicionado como contexto1460* **Stdout de texto simples**: Claude Code adiciona stdout que [trata como texto simples](#exit-code-0) ao contexto do Claude
1220* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto1461* **JSON com `additionalContext`**: use o formato JSON abaixo para mais controle. O campo `additionalContext` é adicionado como contexto
1221 1462
1222Stdout simples é mostrado como saída de hook na transcrição. O valor `additionalContext` é injetado como um lembrete do sistema que Claude lê sem uma entrada de transcrição visível.1463Nenhum canal produz uma entrada de transcrição visível. Stdout simples e o valor `additionalContext` são cada um injetados como um lembrete do sistema que começa com o nome do hook; Claude lê ambos. Para confirmar a entrega, verifique o [log de depuração](#debug-hooks).
1223 1464
1224Para bloquear um prompt, retorne um objeto JSON com `decision` definido para `"block"`:1465Para bloquear um prompt, retorne um objeto JSON com `decision` definido como `"block"`:
1225 1466
1226| Campo | Descrição |1467| Campo | Descrição |
1227| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |1468| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
1228| `decision` | `"block"` previne o prompt de ser processado e o apaga do contexto. Omita para permitir que o prompt prossiga |1469| `decision` | `"block"` impede que o prompt seja processado e o apaga do contexto. Omita para permitir que o prompt prossiga |
1229| `reason` | Mostrado ao usuário quando `decision` é `"block"`. Não adicionado ao contexto |1470| `reason` | Mostrado ao usuário quando `decision` é `"block"`. Não adicionado ao contexto |
1230| `additionalContext` | String adicionada ao contexto de Claude junto com o prompt submetido. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |1471| `additionalContext` | String adicionada ao contexto do Claude ao lado do prompt enviado. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1231| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente baseado no conteúdo do prompt |1472| `sessionTitle` | Define o título da sessão. Use para nomear sessões automaticamente com base no conteúdo do prompt |
1232| `suppressOriginalPrompt` | Se `true` quando `decision` é `"block"`, omite o texto do prompt original da mensagem de bloqueio mostrada ao usuário |1473| `suppressOriginalPrompt` | Se `true` quando `decision` é `"block"`, omite o texto do prompt original da mensagem de bloqueio mostrada ao usuário |
1233 1474
1475Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário e não é adicionada ao contexto.
1476
1234```json theme={null}1477```json theme={null}
1235{1478{
1236 "decision": "block",1479 "decision": "block",
1247 UserPromptExpansion1490 UserPromptExpansion
1248</h3>1491</h3>
1249 1492
1250Executa quando um comando de barra invertida digitado pelo usuário se expande em um prompt antes de chegar ao Claude. Use isso para bloquear comandos específicos de invocação direta, injetar contexto para uma skill particular ou registrar quais comandos os usuários invocam. Por exemplo, um hook correspondendo a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook correspondendo a uma skill de revisão pode anexar a lista de verificação de revisão da equipe como `additionalContext`.1493Executado quando um comando digitado pelo usuário se expande em um prompt antes de chegar ao Claude. Use isso para bloquear comandos específicos de invocação direta, injetar contexto para uma skill particular ou registrar quais comandos os usuários invocam. Por exemplo, um hook correspondente a `deploy` pode bloquear `/deploy` a menos que um arquivo de aprovação esteja presente, ou um hook correspondente a uma skill de revisão pode anexar a lista de verificação de revisão da equipe como `additionalContext`.
1251 1494
1252Este evento cobre o caminho que `PreToolUse` não cobre: um hook `PreToolUse` correspondendo à ferramenta `Skill` dispara apenas quando Claude chama a ferramenta, mas digitar `/skillname` diretamente ignora `PreToolUse`. `UserPromptExpansion` dispara nesse caminho direto.1495Este evento cobre o caminho que `PreToolUse` não cobre: um hook `PreToolUse` correspondente à ferramenta `Skill` é disparado apenas quando Claude chama a ferramenta, mas digitar `/skillname` diretamente ignora `PreToolUse`. `UserPromptExpansion` é disparado nesse caminho direto.
1253 1496
1254Corresponde em `command_name`. Deixe o matcher vazio para disparar em cada comando de barra invertida do tipo prompt.1497Corresponde a `command_name`. Deixe o matcher vazio para disparar em cada comando do tipo prompt.
1255 1498
1256<h4 id="userpromptexpansion-input">1499<h4 id="userpromptexpansion-input">
1257 Entrada de UserPromptExpansion1500 Entrada UserPromptExpansion
1258</h4>1501</h4>
1259 1502
1260Além dos [campos de entrada comuns](#common-input-fields), hooks UserPromptExpansion recebem `expansion_type`, `command_name`, `command_args`, `command_source` e a string `prompt` original. O campo `expansion_type` é `slash_command` para skills e comandos personalizados, ou `mcp_prompt` para prompts de servidor MCP.1503Além dos [campos de entrada comuns](#common-input-fields), os hooks UserPromptExpansion recebem `expansion_type`, `command_name`, `command_args`, `command_source` e a string `prompt` original. O campo `expansion_type` é `slash_command` para skills e comandos personalizados, ou `mcp_prompt` para prompts do servidor MCP.
1261 1504
1262```json theme={null}1505```json theme={null}
1263{1506{
1275```1518```
1276 1519
1277<h4 id="userpromptexpansion-decision-control">1520<h4 id="userpromptexpansion-decision-control">
1278 Controle de decisão de UserPromptExpansion1521 Controle de decisão UserPromptExpansion
1279</h4>1522</h4>
1280 1523
1281Hooks `UserPromptExpansion` podem bloquear a expansão ou adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.1524Os hooks `UserPromptExpansion` podem bloquear a expansão ou adicionar contexto. Todos os [campos de saída JSON](#json-output) estão disponíveis.
1282 1525
1283| Campo | Descrição |1526| Campo | Descrição |
1284| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------- |1527| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |
1285| `decision` | `"block"` previne o comando de barra invertida de se expandir. Omita para permitir que prossiga |1528| `decision` | `"block"` impede que o comando se expanda. Omita para permitir que prossiga |
1286| `reason` | Mostrado ao usuário quando `decision` é `"block"` |1529| `reason` | Mostrado ao usuário quando `decision` é `"block"` |
1287| `additionalContext` | String adicionada ao contexto de Claude junto com o prompt expandido. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |1530| `additionalContext` | String adicionada ao contexto do Claude ao lado do prompt expandido. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1531
1532Um hook que bloqueia ao sair com 2 roteia da mesma forma que `reason`: a mensagem de bloqueio mostra o texto stderr ao usuário.
1288 1533
1289```json theme={null}1534```json theme={null}
1290{1535{
1301 MessageDisplay1546 MessageDisplay
1302</h3>1547</h3>
1303 1548
1304Executa enquanto uma mensagem de assistente flui para a tela. Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para renderizar, o hook executa uma vez com essas linhas e Claude Code renderiza o texto de substituição do hook em seu lugar. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.1549Executado enquanto uma mensagem do assistente é transmitida para a tela. Claude Code exibe a mensagem em incrementos: cada vez que um lote de linhas recém-concluídas está pronto para renderizar, o hook é executado uma vez com essas linhas e Claude Code renderiza o texto de substituição do hook em seu lugar. Uma mensagem longa produz várias chamadas; uma mensagem curta pode produzir apenas uma.
1305 1550
1306Use MessageDisplay para:1551Use MessageDisplay para:
1307 1552
1308* remover markdown para uma exibição mínima1553* remover markdown para uma exibição mínima
1309* transformar o texto que um aplicativo Agent SDK mostra seus usuários1554* transformar o texto que um aplicativo Agent SDK mostra aos seus usuários
1310* redactar chaves de API ou nomes de host internos das respostas de Claude1555* redactar chaves de API ou nomes de host internos das respostas do Claude
1311 1556
1312Claude Code mantém cada lote até que seu hook retorne, então mantenha o hook rápido. Se o hook falhar ou expirar, Claude Code exibe o texto original. O timeout padrão para este evento é 10 segundos; se seu hook precisa de mais tempo, defina o campo `timeout` na entrada do hook.1557Claude Code mantém cada lote até que seu hook retorne, portanto mantenha o hook rápido. Se o hook falhar ou atingir o tempo limite, Claude Code exibe o texto original. O tempo limite padrão para este evento é 10 segundos; se seu hook precisar de mais tempo, defina o campo `timeout` na entrada do hook.
1313 1558
1314MessageDisplay é apenas para exibição: o texto de substituição muda apenas o que é renderizado na tela. A transcrição e o que Claude vê mantêm o texto original, então Claude nunca vê a substituição, e modo verbose mostra o original. O hook recebe apenas texto de mensagem de assistente, então resultados de ferramenta e o texto que você digita renderizam inalterados.1559MessageDisplay é apenas para exibição: o texto de substituição altera apenas o que é renderizado na tela. A transcrição e o que Claude vê mantêm o texto original, portanto Claude nunca vê a substituição, e o modo detalhado mostra o original. O hook recebe apenas texto de mensagem do assistente, portanto resultados de ferramentas e o texto que você digita são renderizados inalterados.
1315 1560
1316MessageDisplay não suporta matchers e dispara para cada mensagem de assistente que flui texto; mensagens sem texto, como respostas apenas de chamada de ferramenta, não o acionam.1561MessageDisplay não suporta matchers e é disparado para cada mensagem do assistente que transmite texto; mensagens sem texto, como respostas apenas de chamada de ferramenta, não o disparam.
1317 1562
1318Em execuções não-interativas, incluindo consultas Agent SDK e `claude -p`, MessageDisplay executa uma vez por mensagem de assistente em vez de uma vez por lote de linhas. A chamada única chega após a mensagem ser concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto `delta` para cada mensagem recebe o mesmo texto total em ambos os modos.1563Em execuções não interativas, incluindo consultas do Agent SDK e `claude -p`, MessageDisplay é executado uma vez por mensagem do assistente em vez de uma vez por lote de linhas. A chamada única chega após a mensagem ser concluída e carrega o texto completo da mensagem: `index` é `0`, `final` é `true` e `delta` contém a mensagem inteira. Um hook que coleta o texto `delta` para cada mensagem recebe o mesmo texto total em ambos os modos.
1319 1564
1320<h4 id="messagedisplay-input">1565<h4 id="messagedisplay-input">
1321 Entrada de MessageDisplay1566 Entrada MessageDisplay
1322</h4>1567</h4>
1323 1568
1324Além dos [campos de entrada comuns](#common-input-fields), hooks MessageDisplay recebem identificadores para o turno e mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites de lote dependem de como o texto flui, então use `index` e `final` para rastrear progresso através de uma mensagem em vez de esperar que linhas sejam agrupadas de uma forma particular.1569Além dos [campos de entrada comuns](#common-input-fields), os hooks MessageDisplay recebem identificadores para o turno e mensagem, a posição desta chamada dentro da mensagem e o novo texto em `delta`. Os limites de lote dependem de como o texto é transmitido, portanto use `index` e `final` para rastrear o progresso através de uma mensagem em vez de esperar que as linhas sejam agrupadas de uma forma particular.
1325 1570
1326| Campo | Descrição |1571| Campo | Descrição |
1327| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1572| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1328| `turn_id` | UUID do turno atual |1573| `turn_id` | UUID do turno atual |
1329| `message_id` | UUID da mensagem de assistente sendo exibida. Estável em cada lote da mesma mensagem. Este não é o `msg_…` id da API, então não pode ser correlacionado com ids de mensagem de transcrição |1574| `message_id` | UUID da mensagem do assistente sendo exibida. Estável em cada lote da mesma mensagem. Este não é o `msg_…` id da API, portanto não pode ser correlacionado com ids de mensagem de transcrição |
1330| `index` | Índice baseado em zero deste lote dentro da mensagem |1575| `index` | Índice baseado em zero deste lote dentro da mensagem |
1331| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |1576| `final` | `true` no último lote da mensagem. Cada mensagem tem exatamente um lote final |
1332| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo quebras de linha finais. Sempre linhas inteiras, exceto o lote final que pode terminar no meio de uma linha. Em execuções interativas, o delta do lote final está vazio quando a mensagem termina em uma quebra de linha, então trate `final`, não um delta não-vazio, como o sinal de fim de mensagem. Em execuções Agent SDK e `claude -p`, a chamada única carrega a mensagem inteira |1577| `delta` | As linhas recém-concluídas desde o lote anterior, incluindo quebras de linha finais. Sempre linhas inteiras, exceto o lote final que pode terminar no meio de uma linha. Em execuções interativas, o delta do lote final está vazio quando a mensagem termina em uma quebra de linha, portanto trate `final`, não um delta não vazio, como o sinal de fim de mensagem. Em execuções do Agent SDK e `claude -p`, a chamada única carrega a mensagem inteira |
1333 1578
1334```json theme={null}1579```json theme={null}
1335{1580{
1346```1591```
1347 1592
1348<h4 id="messagedisplay-output">1593<h4 id="messagedisplay-output">
1349 Saída de MessageDisplay1594 Saída MessageDisplay
1350</h4>1595</h4>
1351 1596
1352Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks MessageDisplay podem retornar `displayContent` para substituir o delta na tela:1597Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks MessageDisplay podem retornar `displayContent` para substituir o delta na tela:
1353 1598
1354| Campo | Descrição |1599| Campo | Descrição |
1355| :--------------- | :------------------------------------------------------------ |1600| :--------------- | :------------------------------------------------------------ |
1356| `displayContent` | Texto exibido no lugar do delta. Omita para exibir o original |1601| `displayContent` | Texto exibido no lugar do delta. Omita para exibir o original |
1357 1602
1358Hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem ou mudar o que é armazenado na transcrição ou enviado ao Claude.1603Os hooks MessageDisplay não têm controle de decisão. Eles não podem bloquear a mensagem ou alterar o que é armazenado na transcrição ou enviado ao Claude. Claude Code atua em `displayContent` de sua saída JSON e descarta `systemMessage` e `continue`.
1359 1604
1360Este exemplo remove formatação markdown das respostas de Claude para uma exibição em texto simples. O script lê cada lote de stdin, remove marcadores de negrito e backticks de código inline de `delta` e retorna o resultado como `displayContent`.1605Este exemplo remove formatação markdown das respostas do Claude para uma exibição de texto simples. O script lê cada lote de stdin, remove marcadores em negrito e backticks de código inline de `delta` e retorna o resultado como `displayContent`.
1361 1606
1362<Tabs>1607<Tabs>
1363 <Tab title="macOS/Linux">1608 <Tab title="macOS/Linux">
1387 #!/bin/bash1632 #!/bin/bash
1388 jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'1633 jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'
1389 ```1634 ```
1390
1391 O script precisa de `jq` em seu `PATH`.
1392 </Tab>1635 </Tab>
1393 1636
1394 <Tab title="Windows (PowerShell)">1637 <Tab title="Windows (PowerShell)">
1418 }1661 }
1419 ```1662 ```
1420 1663
1421 A flag `-NoProfile` ignora o carregamento de seu perfil PowerShell para que o hook inicie rápido, e `-ExecutionPolicy Bypass` permite que PowerShell execute o arquivo de script local.1664 A flag `-NoProfile` pula o carregamento de seu perfil do PowerShell para que o hook comece rápido, e `-ExecutionPolicy Bypass` permite que o PowerShell execute o arquivo de script local.
1422 1665
1423 Salve este script em `.claude/hooks/plain-display.ps1` em seu projeto:1666 Salve este script em `.claude/hooks/plain-display.ps1` em seu projeto:
1424 1667
1435 </Tab>1678 </Tab>
1436</Tabs>1679</Tabs>
1437 1680
1438Lotes sem markdown passam inalterados. Se o script falhar, por exemplo porque `jq` está faltando, Claude Code exibe o texto original e nota a falha apenas em [saída de debug](#debug-hooks), não na sessão.1681Lotes sem markdown passam inalterados. Se o script falhar, por exemplo porque `jq` está faltando, Claude Code exibe o texto original e nota a falha apenas em [saída de depuração](#debug-hooks), não na sessão.
1439 1682
1440<h3 id="pretooluse">1683<h3 id="pretooluse">
1441 PreToolUse1684 PreToolUse
1442</h3>1685</h3>
1443 1686
1444Executa após Claude criar parâmetros de ferramenta e antes de processar a chamada da ferramenta. Corresponde no nome da ferramenta: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode` e qualquer [nome de ferramenta MCP](#match-mcp-tools).1687Executado após Claude criar parâmetros de ferramenta e antes de processar a chamada de ferramenta. Corresponde a qualquer nome de ferramenta exceto `EndConversation`: ferramentas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualquer [nome de ferramenta MCP](#match-mcp-tools).
1688
1689Para executar um hook quando um arquivo específico muda no disco, seja qual for o que o escreveu, use [FileChanged](#filechanged) em vez de corresponder a ferramentas de edição de arquivo por nome. Ao contrário de PreToolUse, Claude Code executa hooks FileChanged após a mudança, e eles não têm controle de decisão, portanto não podem bloquear a escrita.
1445 1690
1446<Warning>1691<Warning>
1447 PreToolUse executa apenas quando Claude chama uma ferramenta. Arquivos que você [referencia com `@` em seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem qualquer chamada de ferramenta: Claude Code insere seus conteúdos enquanto constrói o prompt, então nenhum hook PreToolUse dispara para eles, incluindo hooks correspondendo a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação `Read`](/docs/pt/permissions#read-and-edit) em vez disso.1692 PreToolUse é executado apenas quando Claude chama uma ferramenta. Arquivos que você [referencia com `@` em seu prompt](/docs/pt/common-workflows#reference-files-and-directories) são adicionados sem nenhuma chamada de ferramenta: Claude Code insere seu conteúdo ao construir o prompt, portanto nenhum hook PreToolUse é disparado para eles, incluindo hooks correspondentes a `Read`. Para bloquear caminhos específicos de referências `@`, use uma [regra de negação `Read`](/docs/pt/permissions#read-and-edit) em vez disso.
1693
1694 PreToolUse também não é disparado para [`EndConversation`](/docs/pt/tools-reference#endconversation-tool-behavior).
1448</Warning>1695</Warning>
1449 1696
1450Use [Controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, pedir ou adiar a chamada da ferramenta.1697Use [controle de decisão PreToolUse](#pretooluse-decision-control) para permitir, negar, perguntar ou adiar a chamada de ferramenta.
1698
1699Um [hook de callback do Agent SDK](/docs/pt/agent-sdk/hooks) em `PreToolUse` que excede seu tempo limite bloqueia a chamada de ferramenta, e Claude recebe um resultado de erro nomeando o tempo limite. Uma negação explícita retornada por outro hook ainda tem precedência.
1451 1700
1452<h4 id="pretooluse-input">1701<h4 id="pretooluse-input">
1453 Entrada de PreToolUse1702 Entrada PreToolUse
1454</h4>1703</h4>
1455 1704
1456Além dos [campos de entrada comuns](#common-input-fields), hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`. Os campos `tool_input` dependem da ferramenta:1705Além dos [campos de entrada comuns](#common-input-fields), os hooks PreToolUse recebem `tool_name`, `tool_input` e `tool_use_id`.
1706
1707Para uma [ferramenta MCP](#match-mcp-tools), a entrada também carrega `mcp_server`, um objeto com o `name` do servidor e uma `source` que diz de onde veio a definição do servidor. Os valores `source` incluem `plugin`, `sdk` e escopos de configuração como `user` e `project`. [`McpServerProvenance`](/docs/pt/agent-sdk/typescript#mcpserverprovenance) na referência do Agent SDK lista todos eles e diz como tratar um que você não reconhece. Baseie decisões de confiança em `source` em vez de em `name` ou no prefixo de nome de ferramenta `mcp__<server>__`. O campo `mcp_server` requer Claude Code v2.1.274 ou posterior.
1708
1709Para as ferramentas de arquivo `Write`, `Edit` e `Read`, `tool_input.file_path` é sempre absoluto:
1710
1711* Claude Code expande `~` e caminhos relativos antes dos hooks serem executados, portanto um hook que corresponde a caminhos não pode ser contornado via `~` ou uma ortografia relativa do mesmo caminho
1712* No Windows, o caminho chega com separadores de barra invertida, mesmo quando seu hook é executado sob Git Bash onde `$PWD` parece `/c/project`
1713* Uma comparação escrita com barras para frente, como uma verificação `/src/`, nunca corresponde a um caminho de barra invertida, e a chamada de ferramenta prossegue como se o hook não tivesse nada a bloquear
1714* Normalize separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` em Bash, ou `file_path.replace("\\", "/")` em Python, depois corresponda a um segmento de caminho como `/src/` em vez de ancorar com `^`, já que o caminho é absoluto
1715
1716Uma chamada `Write` no Windows entrega:
1717
1718```json theme={null}
1719{
1720 "hook_event_name": "PreToolUse",
1721 "tool_name": "Write",
1722 "tool_input": {
1723 "file_path": "C:\\project\\src\\index.ts",
1724 "content": "..."
1725 },
1726 ...
1727}
1728```
1729
1730Os campos `tool_input` dependem da ferramenta:
1731
1732<a id="bash" />
1457 1733
1458<h5 id="bash">1734<h5 id="bash">
1459 Bash1735 Bash
1460</h5>1736</h5>
1461 1737
1462Executa comandos shell.1738Executa comandos de shell.
1463 1739
1464| Campo | Tipo | Exemplo | Descrição |1740| Campo | Tipo | Exemplo | Descrição |
1465| :------------------ | :------ | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |1741| :------------------ | :------ | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
1466| `command` | string | `"npm test"` | O comando shell a executar |1742| `command` | string | `"npm test"` | O comando de shell a executar |
1467| `description` | string | `"Run test suite"` | Descrição opcional do que o comando faz |1743| `description` | string | `"Run test suite"` | Descrição opcional do que o comando faz |
1468| `timeout` | number | `120000` | Timeout opcional em milissegundos. Valores acima do [máximo](/docs/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |1744| `timeout` | number | `120000` | Tempo limite opcional em milissegundos. Valores acima do [máximo](/docs/pt/tools-reference#bash-tool-behavior) são reduzidos ao máximo em vez de rejeitados |
1469| `run_in_background` | boolean | `false` | Se o comando deve executar em background |1745| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1746
1747Quando um comando Bash muda arquivos em um repositório Git, Claude Code pode registrar o que mudou. Ele registra as mudanças em cada modo de permissão quando a configuração [`bashEditDiffEnabled`](/docs/pt/settings-reference#basheditdiffenabled) ativa o registro; a entrada dessa configuração diz quais arquivos podem defini-la. Caso contrário, ele as registra apenas em modo automático e modo `bypassPermissions`, e apenas quando Claude Code direciona Claude a editar arquivos através de Bash. Defina `bashEditDiffEnabled` como `false` para desativar o registro. Comandos de fundo e comandos somente leitura não carregam diff.
1748
1749Seu [hook PostToolUse](#posttooluse) então recebe os arquivos alterados em `tool_response.bashEditDiff`. A lista cobre o que mudou sob o repositório enquanto o comando era executado. Arquivos que Git ignora e arquivos em submódulos não são listados. Requer Claude Code v2.1.269 ou posterior.
1750
1751<Note>
1752 A lista é melhor esforço e em beta público. Claude Code pode perder uma mudança, incluir um arquivo que outro processo mudou ao mesmo tempo, ou parar em seus limites de tamanho. A forma do campo pode mudar. Use a lista para encontrar o que revisar, não para impor uma política.
1753</Note>
1754
1755`changedFiles` e `files` listam o que o comando mudou; os campos restantes dizem como completo e confiável essa lista é.
1756
1757| Campo | Tipo | Exemplo | Descrição |
1758| :------------- | :------ | :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1759| `changedFiles` | array | `["/path/to/src/app.ts"]` | Caminhos absolutos dos arquivos que o comando mudou, no máximo 200. Presente sempre que `files` contém um diff ou `moreFiles` está acima de zero |
1760| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs de até 5 arquivos alterados, para exibição. `created` ou `deleted` é `true` para um arquivo que o comando adicionou ou removeu |
1761| `moreFiles` | number | `2` | Contagem de arquivos alterados sem diff em `files` |
1762| `unavailable` | boolean | `true` | Definido quando o diff está incompleto ou não pôde ser obtido |
1763| `skipped` | boolean | `true` | Definido para um comando Git que move a árvore de trabalho, como `git checkout` ou `git stash`, portanto Claude Code não obtém diff |
1764| `shared` | boolean | `true` | Definido quando outra chamada de ferramenta Bash, como a de um subagente, foi executada no mesmo repositório ao mesmo tempo, portanto algumas mudanças listadas podem ser desse comando |
1765
1766<a id="powershell" />
1767
1768<h5 id="powershell">
1769 PowerShell
1770</h5>
1771
1772Executa comandos do PowerShell. Veja a [ferramenta PowerShell](/docs/pt/tools-reference#powershell-tool) para disponibilidade por plataforma.
1773
1774Os campos correspondem à ferramenta Bash, com a string de comando em `command`:
1775
1776| Campo | Tipo | Exemplo | Descrição |
1777| :------------------ | :------ | :------------------------- | :----------------------------------------------- |
1778| `command` | string | `"Get-ChildItem -Recurse"` | O comando do PowerShell a executar |
1779| `description` | string | `"List files recursively"` | Descrição opcional do que o comando faz |
1780| `timeout` | number | `120000` | Tempo limite opcional em milissegundos |
1781| `run_in_background` | boolean | `false` | Se o comando deve ser executado em segundo plano |
1782
1783Corresponda a `Bash|PowerShell` em hooks que inspecionam comandos de shell, para que cubram ambas as ferramentas:
1784
1785* No Windows, onde quer que a ferramenta PowerShell esteja habilitada, Claude trata o PowerShell como o shell primário e roteia comandos de shell através dele.
1786* No Windows sem Git Bash, a ferramenta é habilitada automaticamente e Claude Code não registra a ferramenta Bash.
1787* Um hook que corresponde apenas a `Bash` nunca é disparado lá.
1470 1788
1471<h5 id="write">1789<h5 id="write">
1472 Write1790 Write
1508 Glob1826 Glob
1509</h5>1827</h5>
1510 1828
1511Encontra arquivos correspondendo a um padrão glob.1829Encontra arquivos correspondentes a um padrão glob.
1512 1830
1513| Campo | Tipo | Exemplo | Descrição |1831| Campo | Tipo | Exemplo | Descrição |
1514| :-------- | :----- | :--------------- | :------------------------------------------------------------------------- |1832| :-------- | :----- | :--------------- | :---------------------------------------------------------------------- |
1515| `pattern` | string | `"**/*.ts"` | Padrão glob para corresponder arquivos contra |1833| `pattern` | string | `"**/*.ts"` | Padrão glob para corresponder arquivos |
1516| `path` | string | `"/path/to/dir"` | Diretório opcional para pesquisar. Padrão para diretório de trabalho atual |1834| `path` | string | `"/path/to/dir"` | Diretório opcional para pesquisar. Padrão é diretório de trabalho atual |
1517 1835
1518<h5 id="grep">1836<h5 id="grep">
1519 Grep1837 Grep
1522Pesquisa conteúdo de arquivo com expressões regulares.1840Pesquisa conteúdo de arquivo com expressões regulares.
1523 1841
1524| Campo | Tipo | Exemplo | Descrição |1842| Campo | Tipo | Exemplo | Descrição |
1525| :------------ | :------ | :--------------- | :----------------------------------------------------------------------------------- |1843| :------------ | :------ | :--------------- | :-------------------------------------------------------------------------------- |
1526| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular para pesquisar |1844| `pattern` | string | `"TODO.*fix"` | Padrão de expressão regular para pesquisar |
1527| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional para pesquisar |1845| `path` | string | `"/path/to/dir"` | Arquivo ou diretório opcional para pesquisar |
1528| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |1846| `glob` | string | `"*.ts"` | Padrão glob opcional para filtrar arquivos |
1529| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. Padrão para `"files_with_matches"` |1847| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` ou `"count"`. Padrão é `"files_with_matches"` |
1530| `-i` | boolean | `true` | Pesquisa insensível a maiúsculas |1848| `-i` | boolean | `true` | Pesquisa insensível a maiúsculas e minúsculas |
1531| `multiline` | boolean | `false` | Ativar correspondência multilinha |1849| `multiline` | boolean | `false` | Habilitar correspondência multilinha |
1532 1850
1533<h5 id="webfetch">1851<h5 id="webfetch">
1534 WebFetch1852 WebFetch
1535</h5>1853</h5>
1536 1854
1537Busca e processa conteúdo web.1855Busca e processa conteúdo da web.
1538 1856
1539| Campo | Tipo | Exemplo | Descrição |1857| Campo | Tipo | Exemplo | Descrição |
1540| :------- | :----- | :---------------------------- | :------------------------------------ |1858| :------- | :----- | :---------------------------- | :--------------------------------------- |
1541| `url` | string | `"https://example.com/api"` | URL para buscar conteúdo |1859| `url` | string | `"https://example.com/api"` | URL para buscar conteúdo |
1542| `prompt` | string | `"Extract the API endpoints"` | Prompt a executar no conteúdo buscado |1860| `prompt` | string | `"Extract the API endpoints"` | Prompt para executar no conteúdo buscado |
1543 1861
1544<h5 id="websearch">1862<h5 id="websearch">
1545 WebSearch1863 WebSearch
1566| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |1884| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |
1567| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |1885| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescrever o padrão |
1568 1886
1569Em `PostToolUse`, `tool_response` para uma chamada Agent concluída carrega o texto final do subagente junto com telemetria de uso. Leia esses campos para registrar custo por subagente de um hook:1887Quando uma chamada Agent em primeiro plano é concluída, seu [hook PostToolUse](#posttooluse) recebe o resultado do subagente e telemetria de execução em `tool_response`. Leia esses campos para inspecionar a execução; para rollups de token e custo entre subagentes, use os [contadores de token e custo](/docs/pt/monitoring-usage#token-counter) filtrados para `query_source` `"subagent"`, já que `totalTokens` e `usage` cobrem apenas a solicitação final:
1570 1888
1571| Campo | Tipo | Exemplo | Descrição |1889| Campo | Tipo | Exemplo | Descrição |
1572| :------------------ | :----- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1890| :------------------ | :----- | :---------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1573| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em background. A partir de v2.1.198, subagentes executam em background por padrão, então um `run_in_background` omitido também produz `"async_launched"` |1891| `status` | string | `"completed"` | `"completed"` para subagentes em primeiro plano, `"async_launched"` para subagentes em segundo plano. A partir da v2.1.198, subagentes são executados em segundo plano por padrão, portanto um `run_in_background` omitido também produz `"async_launched"` |
1574| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |1892| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |
1575| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente |1893| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente, ou, para um subagente cujo relatório passa por `SubagentHandback`, uma nota breve sobre esse hand-back em seu lugar |
1576| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo que o subagente executou, que pode diferir do modelo solicitado. Requer Claude Code v2.1.174 ou posterior |1894| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo em que o subagente começou, que pode diferir do modelo solicitado |
1577| `totalTokens` | number | `12450` | Total de tokens cobrados através dos turnos do subagente |1895| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados em ordem, com repetições consecutivas colapsadas; definido apenas quando o modelo foi trocado durante a execução. Requer Claude Code v2.1.212 ou posterior |
1896| `totalTokens` | number | `12450` | Contagem de tokens da solicitação final da API do subagente: tokens de entrada, saída e cache combinados. Isso não é um total em toda a execução |
1578| `totalDurationMs` | number | `48211` | Duração de relógio de parede da execução do subagente |1897| `totalDurationMs` | number | `48211` | Duração de relógio de parede da execução do subagente |
1579| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |1898| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |
1580| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1899| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo da solicitação final da API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1581 1900
1582Para subagentes em background, a ferramenta retorna imediatamente após lançar, então `tool_response` não carrega campos de uso. Tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.1901No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference), que Claude Code fornece em [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), entrega seu relatório através dessa ferramenta em vez de retorná-lo como texto. O campo `content` de seu resultado `completed` então carrega uma nota breve sobre esse hand-back em vez do relatório em si. Para ler o relatório, corresponda a um hook `PreToolUse` ou `PostToolUse` em `SubagentHandback` e leia `tool_input.message`.
1583 1902
1584O campo `resolvedModel` nomeia o modelo que o subagente realmente executa, que pode diferir do valor `model` em `tool_input`, como quando `availableModels` ou outra sobrescrita se aplica. Requer Claude Code v2.1.174 ou posterior.1903Para subagentes em segundo plano, a ferramenta retorna quando a tarefa se move para o fundo, portanto `tool_response` não carrega campos de uso: um lançamento em segundo plano retorna imediatamente, e uma tarefa em primeiro plano que Claude Code coloca em segundo plano durante a execução retorna nessa transição. Ele tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.
1904
1905Em uma resposta `completed`, `resolvedModel` nomeia o modelo em que o subagente começou, que pode diferir do valor `model` em `tool_input`, como quando `availableModels` ou outra substituição se aplica. Em uma resposta `async_launched`, `resolvedModel` nomeia o modelo em uso quando o agente se moveu para o fundo, portanto uma troca que aconteceu antes de colocar em segundo plano é refletida lá. `modelsUsed` e o comportamento `resolvedModel` no tempo de colocação em segundo plano requerem Claude Code v2.1.212 ou posterior.
1585 1906
1586<a id="askuserquestion" />1907<a id="askuserquestion" />
1587 1908
1592Faz ao usuário uma a quatro perguntas de múltipla escolha.1913Faz ao usuário uma a quatro perguntas de múltipla escolha.
1593 1914
1594| Campo | Tipo | Exemplo | Descrição |1915| Campo | Tipo | Exemplo | Descrição |
1595| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1916| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1596| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, `header` curto, array `options` e flag `multiSelect` opcional |1917| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Perguntas a apresentar, cada uma com uma string `question`, `header` curto, array `options` e flag `multiSelect` opcional |
1597| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia texto de pergunta para rótulo de opção selecionada. Respostas multi-select juntam rótulos com vírgulas. Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |1918| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapeia texto de pergunta para rótulo de opção selecionada. Respostas de seleção múltipla unem rótulos com vírgulas. Claude não define este campo; forneça-o via `updatedInput` para responder programaticamente |
1598 1919
1599<h5 id="exitplanmode">1920<h5 id="exitplanmode">
1600 ExitPlanMode1921 ExitPlanMode
1601</h5>1922</h5>
1602 1923
1603Apresenta um plano e pede ao usuário para aprová-lo antes do Claude sair do [modo de plano](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escreve o plano em um arquivo no disco antes de chamar a ferramenta, então o `tool_input` literal do modelo é tipicamente vazio. Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para hooks.1924Apresenta um plano e pede ao usuário para aprová-lo antes de Claude sair do [modo de plano](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escreve o plano em um arquivo no disco antes de chamar a ferramenta, portanto o `tool_input` literal do modelo é tipicamente vazio. Claude Code injeta o conteúdo do plano e o caminho do arquivo antes de passar a entrada para hooks.
1604 1925
1605| Campo | Tipo | Exemplo | Descrição |1926| Campo | Tipo | Exemplo | Descrição |
1606| :--------------- | :----- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1927| :--------------- | :----- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1607| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado do arquivo de plano no disco |1928| `plan` | string | `"## Refactor auth\n1. Extract..."` | Conteúdo do plano em Markdown. Injetado do arquivo de plano no disco |
1608| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo de plano. Injetado |1929| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Caminho para o arquivo de plano. Injetado |
1609| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecated. Claude Code aceita o campo mas o ignora. Antes de v2.1.205, ele carregava permissões baseadas em prompt que Claude estava solicitando para implementar o plano |1930| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Descontinuado. Claude Code aceita o campo mas o ignora. Antes da v2.1.205, ele carregava permissões baseadas em prompt que Claude solicitou para implementar o plano |
1610 1931
1611Em `PostToolUse`, `tool_response` é um objeto com campos `plan` e `filePath` contendo o plano aprovado, mais flags de status interno. Leia `tool_response.plan` para o conteúdo do plano em vez de re-ler o arquivo do disco.1932Em `PostToolUse`, `tool_response` é um objeto com campos `plan` e `filePath` contendo o plano aprovado, mais flags de status interno. Leia `tool_response.plan` para o conteúdo do plano em vez de reler o arquivo do disco.
1612 1933
1613<h4 id="pretooluse-decision-control">1934<h4 id="pretooluse-decision-control">
1614 Controle de decisão de PreToolUse1935 Controle de decisão PreToolUse
1615</h4>1936</h4>
1616 1937
1617Hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Diferentemente de outros hooks que usam um campo `decision` de nível superior, PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso oferece controle mais rico: quatro resultados (permitir, negar, pedir ou adiar) além da capacidade de modificar entrada de ferramenta antes da execução.1938Os hooks `PreToolUse` podem controlar se uma chamada de ferramenta prossegue. Ao contrário de outros hooks que usam um campo `decision` de nível superior, PreToolUse retorna sua decisão dentro de um objeto `hookSpecificOutput`. Isso lhe dá controle mais rico: quatro resultados (permitir, negar, perguntar ou adiar) mais a capacidade de modificar a entrada da ferramenta antes da execução.
1618 1939
1619| Campo | Descrição |1940| Campo | Descrição |
1620| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1941| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1621| `permissionDecision` | `"allow"` ignora o prompt de permissão, exceto para [ferramentas que requerem interação do usuário](#pretooluse-decision-control) e ferramentas conectoras [sua organização definiu para `ask`](/docs/pt/mcp#organization-controls-on-connector-tools). `"deny"` previne a chamada da ferramenta. `"ask"` solicita ao usuário confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |1942| `permissionDecision` | `"allow"` pula o prompt de permissão, exceto para as [ações que nenhum modo auto-aprova](/docs/pt/permission-modes#actions-no-mode-auto-approves) e para `AskUserQuestion` e `ExitPlanMode`, que precisam de [`updatedInput` emparelhado com ele](#allow-with-updatedinput). `"deny"` impede a chamada de ferramenta. `"ask"` solicita ao usuário para confirmar. `"defer"` sai graciosamente para que a ferramenta possa ser retomada mais tarde. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas independentemente do que o hook retorna |
1622| `permissionDecisionReason` | Para `"allow"` e `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"defer"`, ignorado |1943| `permissionDecisionReason` | Para `"allow"` e `"ask"`, mostrado ao usuário mas não ao Claude. Para `"deny"`, mostrado ao Claude. Para `"defer"`, ignorado |
1623| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua campos inalterados junto com os modificados. Combine com `"allow"` para aprovação automática ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |1944| `updatedInput` | Modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, portanto inclua campos inalterados ao lado dos modificados. Claude Code avalia regras de permissão e a elegibilidade de [auto-fundo](/docs/pt/tools-reference#background-commands) de um comando Bash contra a entrada que seu hook retorna, não a entrada que Claude enviou. Combine com `"allow"` para auto-aprovar, ou `"ask"` para mostrar a entrada modificada ao usuário. Para `"defer"`, ignorado |
1624| `additionalContext` | String adicionada ao contexto de Claude junto com o resultado da ferramenta. Ignorado quando `permissionDecision` é `"defer"`. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |1945| `additionalContext` | String adicionada ao contexto do Claude ao lado do resultado da ferramenta. Ignorado quando `permissionDecision` é `"defer"`. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1946
1947Quando vários hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.
1625 1948
1626Quando múltiplos hooks PreToolUse retornam decisões diferentes, a precedência é `deny` > `defer` > `ask` > `allow`.1949Um hook que bloqueia ao sair com 2 roteia da mesma forma que `"deny"`: Claude vê a mensagem stderr como o motivo da negação.
1627 1950
1628Quando um hook retorna `"ask"`, o diálogo de permissão exibido ao usuário inclui um rótulo identificando de onde o hook veio: por exemplo, `[User]`, `[Project]`, `[Plugin]` ou `[Local]`. Isso ajuda os usuários a entender qual fonte de configuração está solicitando confirmação.1951Quando um hook retorna `"ask"`, o prompt de permissão exibido ao usuário inclui um rótulo identificando de onde o hook veio: `[settings]` para um hook de qualquer arquivo de configurações ou de frontmatter de agente, `[plugin:<name>]` para um hook de plugin, ou `[skill]` para um hook de frontmatter de skill. Isso ajuda os usuários a entender qual fonte de configuração está solicitando confirmação.
1952
1953Um `"ask"` de um hook também força um prompt de permissão em [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): o classificador ainda pode negar a chamada de ferramenta, mas não pode aprovar a chamada silenciosamente. Antes da v2.1.211, o classificador poderia aprovar um comando Bash executado fora do [sandbox](/docs/pt/sandboxing) sem mostrar o prompt que o hook solicitou; o classificador ainda aplicava suas próprias regras de segurança a esse comando, e uma negação de hook `"deny"` era sempre honrada.
1629 1954
1630```json theme={null}1955```json theme={null}
1631{1956{
1641}1966}
1642```1967```
1643 1968
1644`AskUserQuestion` e `ExitPlanMode` requerem interação do usuário e normalmente bloqueiam em [modo não-interativo](/docs/pt/headless) com a flag `-p`. 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 execute sem solicitar. Retornar `"allow"` sozinho não é suficiente para essas ferramentas. Para `AskUserQuestion`, ecoar de volta o array `questions` original e adicionar um objeto [`answers`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.1969<span id="allow-with-updatedinput" />
1645 1970
1646Ferramentas conectoras [sua organização definiu para `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) solicitam mesmo quando um hook retorna `"allow"`.1971Em [modo não interativo](/docs/pt/headless) com a flag `-p`, Claude Code oferece `AskUserQuestion` e `ExitPlanMode` apenas quando a execução tem um [host de permissão](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs) 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`](#askuserquestion) mapeando o texto de cada pergunta para a resposta escolhida.
1647 1972
1648A partir de v2.1.199, uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é 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.1973A partir da v2.1.199, uma ferramenta MCP cujo servidor a marca com [`_meta["anthropic/requiresUserInteraction"]`](/docs/pt/mcp#require-approval-for-a-specific-tool) é 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.
1649 1974
1650<Note>1975<Note>
1651 PreToolUse anteriormente usava campos `decision` e `reason` de nível superior, mas esses estão deprecados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores deprecados `"approve"` e `"block"` mapeiam para `"allow"` e `"deny"` respectivamente. Outros eventos como PostToolUse e Stop continuam usando `decision` e `reason` de nível superior como seu formato atual.1976 PreToolUse anteriormente usava campos `decision` e `reason` de nível superior, mas estes estão descontinuados para este evento. Use `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` em vez disso. Os valores descontinuados `"approve"` e `"block"` mapeiam para `"allow"` e `"deny"` respectivamente. Outros eventos como PostToolUse e Stop continuam usando `decision` e `reason` de nível superior como seu formato atual.
1652</Note>1977</Note>
1653 1978
1654<h4 id="defer-a-tool-call-for-later">1979<h4 id="defer-a-tool-call-for-later">
1655 Adiar uma chamada de ferramenta para mais tarde1980 Adiar uma chamada de ferramenta para mais tarde
1656</h4>1981</h4>
1657 1982
1658`"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 do Claude Code. Permite que esse processo chamador 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](/docs/pt/headless) com a flag `-p`. Em sessões interativas ele registra um aviso e ignora o resultado do hook.1983`"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](/docs/pt/headless) com a flag `-p`. Em sessões interativas, ele registra um aviso e ignora o resultado do hook.
1659 1984
1660A ferramenta `AskUserQuestion` é o caso típico: Claude quer fazer uma pergunta ao usuário, mas não há terminal para responder. A viagem de ida e volta funciona assim:1985A 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](/docs/pt/headless#turn-off-permission-prompts-in-unattended-runs), 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:
1661 1986
16621. Claude chama `AskUserQuestion`. O hook `PreToolUse` dispara.19871. Claude chama `AskUserQuestion`. O hook `PreToolUse` é disparado.
16632. O hook retorna `permissionDecision: "defer"`. A ferramenta não executa. O processo sai com `stop_reason: "tool_deferred"` e a chamada de ferramenta pendente preservada na transcrição.19882. 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.
16643. O processo chamador lê `deferred_tool_use` do resultado SDK, superficializa a pergunta em sua própria UI e espera por uma resposta.19893. 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.
16654. O processo chamador executa `claude -p --resume <session-id>`. A mesma chamada de ferramenta dispara `PreToolUse` novamente.19904. 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.
16665. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta executa e Claude continua.19915. O hook retorna `permissionDecision: "allow"` com a resposta em `updatedInput`. A ferramenta é executada e Claude continua.
1667 1992
1668O 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:1993O 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:
1669 1994
1681}2006}
1682```2007```
1683 2008
1684Não há timeout ou limite de tentativas. A sessão permanece no disco até que você a retome, sujeita à varredura de retenção [`cleanupPeriodDays`](/docs/pt/settings#available-settings) que deleta arquivos de sessão após 30 dias por padrã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 quebrar o loop eventualmente retornando `"allow"` ou `"deny"` do hook.2009Nã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`](/docs/pt/settings-reference#cleanupperioddays), que exclui arquivos de sessão após 30 dias por padrão, seguindo as [regras de varredura de retenção](/docs/pt/claude-directory#cleaned-up-automatically). 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.
1685 2010
1686`"defer"` apenas funciona 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 resume pode apenas re-executar uma ferramenta: não há forma de adiar uma chamada de um lote sem deixar as outras não resolvidas.2011`"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.
1687 2012
1688Se 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 disparar. 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.2013Se 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.
1689 2014
1690<Note>2015<Note>
1691 `--resume` restaura o modo de permissão que estava ativo quando a ferramenta foi adiada, então você não precisa passar `--permission-mode` novamente. As exceções são `plan` e `bypassPermissions`, que nunca são transportados. Passar `--permission-mode` explicitamente na retomada sobrescreve o valor restaurado.2016 Para retomar uma sessão adiada em modo de plano, passe [`--permission-prompt-tool`](/docs/pt/cli-reference#cli-flags) junto com `--resume` para que Claude Code possa apresentar o plano para aprovação. Sem ele, Claude Code não restaura o modo de plano. Requer Claude Code v2.1.246 ou posterior.
2017
2018 Quando você retoma com `-p`, Claude Code não restaura nenhum outro modo de permissão armazenado. Ele inicia a execução no modo de permissão que uma nova execução `claude -p` iniciaria, portanto passe `--permission-mode` ou `--dangerously-skip-permissions` novamente se a sessão adiada usou uma. Quando você retoma com `claude --resume <session-id>` sem `-p`, Claude Code restaura o modo de permissão armazenado, com as exceções listadas em [modo de permissão ao retomar](/docs/pt/sessions#permission-mode-on-resume).
1692</Note>2019</Note>
1693 2020
1694<h3 id="permissionrequest">2021<h3 id="permissionrequest">
1695 PermissionRequest2022 PermissionRequest
1696</h3>2023</h3>
1697 2024
1698Executa quando o usuário é mostrado um diálogo de permissão.2025Executado 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](/docs/pt/headless), Claude Code ainda executa esses hooks, e se nenhum hook retornar uma decisão, ele nega a chamada de ferramenta.
1699Use [Controle de decisão PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.2026Use [controle de decisão PermissionRequest](#permissionrequest-decision-control) para permitir ou negar em nome do usuário.
2027
2028Use 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](#notification) com o tipo `permission_prompt` apenas após o prompt ter esperado cerca de seis segundos.
2029
2030Claude Code não executa hooks PermissionRequest para a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox. Para obter um sinal para esse prompt, use o tipo de notificação `permission_prompt`.
1700 2031
1701Corresponde no nome da ferramenta, mesmos valores que PreToolUse.2032Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
1702 2033
1703<h4 id="permissionrequest-input">2034<h4 id="permissionrequest-input">
1704 Entrada de PermissionRequest2035 Entrada PermissionRequest
1705</h4>2036</h4>
1706 2037
1707Hooks PermissionRequest recebem campos `tool_name` e `tool_input` como hooks PreToolUse, mas sem `tool_use_id`. Um array `permission_suggestions` opcional contém as opções "sempre permitir" que o usuário normalmente veria no diálogo de permissão. A diferença é quando o hook dispara: hooks PermissionRequest executam quando um diálogo de permissão está prestes a ser mostrado ao usuário, enquanto hooks PreToolUse executam antes da execução da ferramenta independentemente do status de permissão.2038Os 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`](#pretooluse-input). Um array `permission_suggestions` opcional contém as [atualizações de permissão](#permission-update-entries) que Claude Code sugere para esta solicitação, como adicionar uma regra de permissão ou alterar o modo de permissão.
2039
2040O 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`](/docs/pt/settings-reference#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**](/docs/pt/permission-modes#switch-permission-modes), que altera o modo de permissão diretamente em vez de através de uma atualização de permissão.
2041
2042Os 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`](/docs/pt/tools-reference#endconversation-tool-behavior).
1708 2043
1709```json theme={null}2044```json theme={null}
1710{2045{
1730```2065```
1731 2066
1732<h4 id="permissionrequest-decision-control">2067<h4 id="permissionrequest-decision-control">
1733 Controle de decisão de PermissionRequest2068 Controle de decisão PermissionRequest
1734</h4>2069</h4>
1735 2070
1736Hooks `PermissionRequest` podem permitir ou negar solicitações de permissão. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar um objeto `decision` com esses campos específicos do evento:2071Os hooks `PermissionRequest` podem permitir ou negar solicitações de permissão. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar um objeto `decision` com esses campos específicos do evento:
1737 2072
1738| Campo | Descrição |2073| Campo | Descrição |
1739| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2074| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1740| `behavior` | `"allow"` concede a permissão, `"deny"` nega. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas, então um hook retornando `"allow"` não sobrescreve uma regra de negação correspondente |2075| `behavior` | `"allow"` concede a permissão, `"deny"` a nega. [Regras de negação e pergunta](/docs/pt/permissions#manage-permissions) ainda são avaliadas, portanto um hook retornando `"allow"` não sobrescreve uma regra de negação correspondente |
1741| `updatedInput` | Apenas para `"allow"`: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, então inclua campos inalterados junto com os modificados. A entrada modificada é re-avaliada contra regras de negação e pergunta |2076| `updatedInput` | Para `"allow"` apenas: modifica os parâmetros de entrada da ferramenta antes da execução. Substitui o objeto de entrada inteiro, portanto inclua campos inalterados ao lado dos modificados. A entrada modificada é re-avaliada contra regras de negação e pergunta |
1742| `updatedPermissions` | Apenas para `"allow"`: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou mudar o modo de permissão da sessão |2077| `updatedPermissions` | Para `"allow"` apenas: array de [entradas de atualização de permissão](#permission-update-entries) a aplicar, como adicionar uma regra de permissão ou alterar o modo de permissão da sessão |
1743| `message` | Apenas para `"deny"`: diz ao Claude por que a permissão foi negada |2078| `message` | Para `"deny"` apenas: diz ao Claude por que a permissão foi negada |
1744| `interrupt` | Apenas para `"deny"`: se `true`, para Claude |2079| `interrupt` | Para `"deny"` apenas: se `true`, para Claude |
2080
2081Um 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.
1745 2082
1746```json theme={null}2083```json theme={null}
1747{2084{
1761 Entradas de atualização de permissão2098 Entradas de atualização de permissão
1762</h4>2099</h4>
1763 2100
1764O campo de saída `updatedPermissions` e o campo de entrada [`permission_suggestions`](#permissionrequest-input) 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.2101O campo de saída `updatedPermissions` e o campo de entrada [`permission_suggestions`](#permissionrequest-input) 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.
1765 2102
1766| `type` | Campos | Efeito |2103| `type` | Campos | Efeito |
1767| :------------------ | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2104| :------------------ | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1768| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder a toda a ferramenta. `behavior` é `"allow"`, `"deny"` ou `"ask"` |2105| `addRules` | `rules`, `behavior`, `destination` | Adiciona regras de permissão. `rules` é um array de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para corresponder a toda a ferramenta. `behavior` é `"allow"`, `"deny"` ou `"ask"` |
1769| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` dado no `destination` pelas `rules` fornecidas |2106| `replaceRules` | `rules`, `behavior`, `destination` | Substitui todas as regras do `behavior` dado no `destination` pelas `rules` fornecidas |
1770| `removeRules` | `rules`, `behavior`, `destination` | Remove regras correspondentes do `behavior` dado |2107| `removeRules` | `rules`, `behavior`, `destination` | Remove regras correspondentes do `behavior` dado |
1771| `setMode` | `mode`, `destination` | Muda o modo de permissão. Modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como um alias para `default`. O alias `manual` requer Claude Code v2.1.200 ou posterior |2108| `setMode` | `mode`, `destination` | Altera o modo de permissão. Modos válidos são `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` como um alias para `default`. O alias `manual` requer Claude Code v2.1.200 ou posterior |
1772| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |2109| `addDirectories` | `directories`, `destination` | Adiciona diretórios de trabalho. `directories` é um array de strings de caminho |
1773| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |2110| `removeDirectories` | `directories`, `destination` | Remove diretórios de trabalho |
1774 2111
1775<Note>2112<Note>
1776 `setMode` com `bypassPermissions` apenas toma efeito se a sessão foi lançada com modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` em configurações, e o modo não é desabilitado por [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings). Caso contrário, a atualização é um no-op. `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.2113 `setMode` com `bypassPermissions` só tem efeito se você iniciou a sessão com modo bypass já disponível: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` ou `permissions.defaultMode: "bypassPermissions"` em [configurações de usuário, `--settings` ou gerenciadas](/docs/pt/settings-reference#permissions-defaultmode). Caso contrário, a atualização é uma não-operação. A atualização também é uma não-operação quando [`permissions.disableBypassPermissionsMode`](/docs/pt/permissions#managed-settings) desabilita o modo, ou quando a sessão começa em [modo restrito](/docs/pt/cli-reference#cli-flags).
2114
2115 `bypassPermissions` nunca é persistido como `defaultMode` independentemente de `destination`.
1777</Note>2116</Note>
1778 2117
1779O campo `destination` em cada entrada determina se a mudança fica em memória ou persiste em um arquivo de configurações.2118O campo `destination` em cada entrada determina se a mudança permanece na memória ou persiste em um arquivo de configurações.
1780 2119
1781| `destination` | Escreve para |2120| `destination` | Escreve para |
1782| :---------------- | :---------------------------------------------------- |2121| :---------------- | :---------------------------------------------------- |
1783| `session` | apenas em memória, descartado quando a sessão termina |2122| `session` | apenas na memória, descartado quando a sessão termina |
1784| `localSettings` | `.claude/settings.local.json` |2123| `localSettings` | `.claude/settings.local.json` |
1785| `projectSettings` | `.claude/settings.json` |2124| `projectSettings` | `.claude/settings.json` |
1786| `userSettings` | `~/.claude/settings.json` |2125| `userSettings` | `~/.claude/settings.json` |
1787 2126
1788Um hook pode ecoar uma das `permission_suggestions` que recebeu como sua própria saída `updatedPermissions`, que é equivalente ao usuário selecionar essa opção "sempre permitir" no diálogo.2127Um hook pode ecoar uma das `permission_suggestions` que recebeu como sua própria saída `updatedPermissions`.
1789 2128
1790<h3 id="posttooluse">2129<h3 id="posttooluse">
1791 PostToolUse2130 PostToolUse
1792</h3>2131</h3>
1793 2132
1794Executa imediatamente após uma ferramenta completar com sucesso.2133Executado imediatamente após uma ferramenta ser concluída com sucesso.
2134
2135Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
1795 2136
1796Corresponde no nome da ferramenta, mesmos valores que PreToolUse.2137Corresponda mais amplamente quando o nome da ferramenta não é o filtro certo:
2138
2139* 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](#posttoolusefailure).
2140* Para executar um hook quando um arquivo específico muda no disco, seja qual for o que o escreveu, use [FileChanged](#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.
1797 2141
1798<h4 id="posttooluse-input">2142<h4 id="posttooluse-input">
1799 Entrada de PostToolUse2143 Entrada PostToolUse
1800</h4>2144</h4>
1801 2145
1802Hooks `PostToolUse` disparam após uma ferramenta já ter executado com sucesso. A entrada inclui tanto `tool_input`, os argumentos enviados para a ferramenta, quanto `tool_response`, o resultado que retornou. O esquema exato para ambos depende da ferramenta.2146Os 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](#pretooluse-input): 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`](#pretooluse-input).
1803 2147
1804```json theme={null}2148```json theme={null}
1805{2149{
1815 },2159 },
1816 "tool_response": {2160 "tool_response": {
1817 "filePath": "/path/to/file.txt",2161 "filePath": "/path/to/file.txt",
1818 "success": true2162 "type": "create"
1819 },2163 },
1820 "tool_use_id": "toolu_01ABC123...",2164 "tool_use_id": "toolu_01ABC123...",
1821 "duration_ms": 122165 "duration_ms": 12
1827| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |2171| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |
1828 2172
1829<h4 id="posttooluse-decision-control">2173<h4 id="posttooluse-decision-control">
1830 Controle de decisão de PostToolUse2174 Controle de decisão PostToolUse
1831</h4>2175</h4>
1832 2176
1833Hooks `PostToolUse` podem fornecer feedback ao Claude após execução de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2177Os hooks `PostToolUse` podem fornecer feedback ao Claude após a execução da ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:
1834 2178
1835| Campo | Descrição |2179| Campo | Descrição |
1836| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |2180| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1837| `decision` | `"block"` adiciona a `reason` próxima ao resultado da ferramenta. Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |2181| `decision` | `"block"` adiciona o `reason` ao lado do resultado da ferramenta. Claude ainda vê a saída original; para substituí-la, use `updatedToolOutput` |
1838| `reason` | Explicação mostrada ao Claude quando `decision` é `"block"` |2182| `reason` | Explicação mostrada ao Claude quando `decision` é `"block"` |
1839| `additionalContext` | String adicionada ao contexto de Claude junto com o resultado da ferramenta. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |2183| `additionalContext` | String adicionada ao contexto do Claude ao lado do resultado da ferramenta. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
2184| `classifierContext` | Nota breve sobre o resultado desta chamada para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. Veja [Anotar um resultado para o classificador de modo automático](#annotate-a-result-for-the-auto-mode-classifier). Requer Claude Code v2.1.236 ou posterior |
1840| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ser enviado ao Claude. O valor deve corresponder à forma de saída da ferramenta |2185| `updatedToolOutput` | Substitui a saída da ferramenta pelo valor fornecido antes de ser enviado ao Claude. O valor deve corresponder à forma de saída da ferramenta |
1841| `updatedMCPToolOutput` | Substitui a saída apenas para [ferramentas MCP](#match-mcp-tools). Prefira `updatedToolOutput`, que funciona para todas as ferramentas |2186| `updatedMCPToolOutput` | Substitui a saída para [ferramentas MCP](#match-mcp-tools) apenas. Prefira `updatedToolOutput`, que funciona para todas as ferramentas |
1842 2187
1843O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde à forma de saída da ferramenta `Bash`:2188O exemplo abaixo substitui a saída de uma chamada `Bash`. O valor de substituição corresponde à forma de saída da ferramenta `Bash`:
1844 2189
1858```2203```
1859 2204
1860<Warning>2205<Warning>
1861 `updatedToolOutput` apenas muda o que Claude vê. A ferramenta já executou no momento em que o hook dispara, então qualquer arquivo escrito, comandos executados ou requisições de rede enviadas já tiveram efeito. Telemetria como spans de ferramentas OpenTelemetry e eventos de análise também capturam a saída original antes do hook executar. Para prevenir ou modificar uma chamada de ferramenta antes de executar, use um hook [PreToolUse](#pretooluse) em vez disso.2206 `updatedToolOutput` apenas altera o que Claude vê. A ferramenta já foi executada no momento em que o hook é disparado, portanto qualquer arquivo escrito, comando executado ou solicitação de rede enviada já teve efeito. Telemetria como spans de ferramenta OpenTelemetry e eventos de análise também capturam a saída original antes do hook ser executado. Para impedir ou modificar uma chamada de ferramenta antes de ser executada, use um hook [PreToolUse](#pretooluse) em vez disso.
1862 2207
1863 O valor de substituição deve corresponder à forma de saída da ferramenta. Ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponde ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramenta MCP é passada sem validação de esquema. Remover detalhes de erro que Claude precisa pode fazer com que ele prossiga em uma suposição falsa.2208 O valor de substituição deve corresponder à forma de saída da ferramenta. Ferramentas integradas retornam objetos estruturados em vez de strings simples. Por exemplo, `Bash` retorna um objeto com campos `stdout`, `stderr`, `interrupted` e `isImage`. Para ferramentas integradas, um valor que não corresponde ao esquema de saída da ferramenta é ignorado e a saída original é usada. A saída de ferramenta MCP é passada sem validação de esquema. Remover detalhes de erro que Claude precisa pode fazer com que ele prossiga em uma suposição falsa.
1864</Warning>2209</Warning>
1865 2210
2211<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2212 Anotar um resultado para o classificador de modo automático
2213</h4>
2214
2215Retorne `classifierContext` para enviar uma nota breve sobre o resultado da chamada de ferramenta para o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez de para Claude. O classificador [nunca recebe resultados de ferramentas em si](/docs/pt/permission-modes#how-the-classifier-evaluates-actions), 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.
2216
2217O exemplo abaixo diz ao classificador de onde a saída de uma consulta veio:
2218
2219```json theme={null}
2220{
2221 "hookSpecificOutput": {
2222 "hookEventName": "PostToolUse",
2223 "classifierContext": "This query ran against the staging database, not production."
2224 }
2225}
2226```
2227
2228Quanto peso o classificador dá à nota depende de onde você configurou o hook:
2229
2230* **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
2231* **Callbacks do Agent SDK em processo**: quando um aplicativo que incorpora Claude Code registra o hook como um [callback do SDK TypeScript](/docs/pt/agent-sdk/hooks) 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
2232
2233Claude Code aplica esses limites ao entregar a nota:
2234
2235* **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
2236* **Apenas respostas síncronas**: Claude Code ignora o campo na resposta de um hook que [é executado em segundo plano](#run-hooks-in-the-background), porque essa resposta chega após Claude Code registrar o resultado da ferramenta
2237* **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
2238* **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
2239
2240<Warning>
2241 O classificador lê conteúdo que você coloca em `classifierContext` como informação do aplicativo hospedando a sessão, portanto não copie saída de ferramenta não confiável ou texto de terceiros nele. Mantenha a nota para uma breve afirmação sobre esta chamada, como um fato sobre sua origem ou uma declaração do usuário sobre ela; não use o campo para entregar mensagens não relacionadas ou um fluxo de eventos.
2242</Warning>
2243
1866<h3 id="posttoolusefailure">2244<h3 id="posttoolusefailure">
1867 PostToolUseFailure2245 PostToolUseFailure
1868</h3>2246</h3>
1869 2247
1870Executa 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.2248Executado 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.
1871 2249
1872Corresponde no nome da ferramenta, mesmos valores que PreToolUse.2250Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
1873 2251
1874<Note>2252<Note>
1875 Este evento não dispara para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, entrada que falha na validação de esquema ou específica da ferramenta, ou uma negação de permissão. Rejeições de validação são retornadas como resultados `tool_use_error` e acontecem antes dos hooks executarem, então eles não disparam nem `PreToolUse` nem este evento. Negações de permissão disparam `PreToolUse` mas não este evento; consulte [PermissionDenied](#permissiondenied).2253 Este evento não é disparado para chamadas de ferramenta rejeitadas antes da execução: um nome de ferramenta desconhecido, entrada que falha na validação de esquema ou específica da ferramenta, ou uma negação de permissão. Rejeições de validação são retornadas como resultados `tool_use_error` e acontecem antes dos hooks serem executados, portanto não disparam nem `PreToolUse` nem este evento. Negações de permissão disparam `PreToolUse` mas não este evento; veja [PermissionDenied](#permissiondenied).
1876</Note>2254</Note>
1877 2255
1878<h4 id="posttoolusefailure-input">2256<h4 id="posttoolusefailure-input">
1879 Entrada de PostToolUseFailure2257 Entrada PostToolUseFailure
1880</h4>2258</h4>
1881 2259
1882Hooks PostToolUseFailure recebem os mesmos campos `tool_name` e `tool_input` que PostToolUse, junto com informações de erro como campos de nível superior:2260Os 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`](#pretooluse-input). Por exemplo, um comando `npm test` falhado pode entregar:
1883 2261
1884```json theme={null}2262```json theme={null}
1885{2263{
1894 "description": "Run test suite"2272 "description": "Run test suite"
1895 },2273 },
1896 "tool_use_id": "toolu_01ABC123...",2274 "tool_use_id": "toolu_01ABC123...",
1897 "error": "Command exited with non-zero status code 1",2275 "error": "Exit code 1\nError: Cannot find module 'express'",
1898 "is_interrupt": false,2276 "is_interrupt": false,
1899 "duration_ms": 41872277 "duration_ms": 4187
1900}2278}
1901```2279```
1902 2280
1903| Campo | Descrição |2281| Campo | Descrição |
1904| :------------- | :------------------------------------------------------------------------------------------------------------------------ |2282| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1905| `error` | String descrevendo o que deu errado |2283| `error` | String descrevendo o que deu errado. O formato depende da ferramenta que falhou |
1906| `is_interrupt` | Boolean opcional indicando se a falha foi causada por interrupção do usuário |2284| `is_interrupt` | Booleano opcional. True quando a falha chegou a Claude Code como um aborto em vez de como um erro que a ferramenta relatou. Cancelar uma ferramenta em execução não dispara este hook; o resultado da ferramenta carrega a mensagem de interrupção em vez disso |
1907| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |2285| `duration_ms` | Opcional. Tempo de execução da ferramenta em milissegundos. Exclui tempo gasto em prompts de permissão e hooks PreToolUse |
1908 2286
2287A 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.
2288
2289* 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
2290* 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
2291* 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`
2292
1909<h4 id="posttoolusefailure-decision-control">2293<h4 id="posttoolusefailure-decision-control">
1910 Controle de decisão de PostToolUseFailure2294 Controle de decisão PostToolUseFailure
1911</h4>2295</h4>
1912 2296
1913Hooks `PostToolUseFailure` podem fornecer contexto ao Claude após falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2297Os hooks `PostToolUseFailure` podem fornecer contexto ao Claude após uma falha de ferramenta. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:
1914 2298
1915| Campo | Descrição |2299| Campo | Descrição |
1916| :------------------ | :--------------------------------------------------------------------------------------------------------------------------- |2300| :------------------ | :---------------------------------------------------------------------------------------------------------------------- |
1917| `additionalContext` | String adicionada ao contexto de Claude junto com o erro. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |2301| `additionalContext` | String adicionada ao contexto do Claude ao lado do erro. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
1918 2302
1919```json theme={null}2303```json theme={null}
1920{2304{
1929 PostToolBatch2313 PostToolBatch
1930</h3>2314</h3>
1931 2315
1932Executa uma vez após cada chamada de ferramenta em um lote ter sido resolvida, antes do Claude Code enviar a próxima solicitação para o modelo. `PostToolUse` dispara uma vez por ferramenta, o que significa que dispara concorrentemente quando Claude faz chamadas de ferramenta paralelas. `PostToolBatch` dispara exatamente uma vez com o lote completo, então é o lugar certo para injetar contexto que depende do conjunto de ferramentas que executaram em vez de em qualquer ferramenta única. Não há matcher para este evento.2316Executado 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.
1933 2317
1934<h4 id="posttoolbatch-input">2318<h4 id="posttoolbatch-input">
1935 Entrada de PostToolBatch2319 Entrada PostToolBatch
1936</h4>2320</h4>
1937 2321
1938Além dos [campos de entrada comuns](#common-input-fields), hooks PostToolBatch recebem `tool_calls`, um array descrevendo cada chamada de ferramenta no lote:2322Além dos [campos de entrada comuns](#common-input-fields), os hooks PostToolBatch recebem `tool_calls`, um array descrevendo cada chamada de ferramenta no lote:
1939 2323
1940```json theme={null}2324```json theme={null}
1941{2325{
1961}2345}
1962```2346```
1963 2347
1964`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. Respostas podem ser grandes, então analise apenas os campos que você precisa.2348`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.
1965 2349
1966<Note>2350<Note>
1967 A forma `tool_response` difere da de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", success: true}` para `Write`; `PostToolBatch` passa o conteúdo `tool_result` serializado que o modelo vê.2351 A forma `tool_response` difere da de `PostToolUse`. `PostToolUse` passa o objeto `Output` estruturado da ferramenta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` passa o conteúdo `tool_result` serializado que o modelo vê.
1968</Note>2352</Note>
1969 2353
1970<h4 id="posttoolbatch-decision-control">2354<h4 id="posttoolbatch-decision-control">
1971 Controle de decisão de PostToolBatch2355 Controle de decisão PostToolBatch
1972</h4>2356</h4>
1973 2357
1974Hooks `PostToolBatch` podem injetar contexto para Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2358Os hooks `PostToolBatch` podem injetar contexto para Claude. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:
1975 2359
1976| Campo | Descrição |2360| Campo | Descrição |
1977| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |2361| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1978| `additionalContext` | String de contexto injetada uma vez antes da próxima chamada do modelo. Consulte [Adicionar contexto para Claude](#add-context-for-claude) para detalhes de entrega, o que colocar nele e como sessões retomadas lidam com valores passados |2362| `additionalContext` | String de contexto injetada uma vez antes da próxima chamada do modelo. Veja [Adicionar contexto para Claude](#add-context-for-claude) para detalhes de entrega, o que colocar nela e como sessões retomadas lidam com valores passados |
1979 2363
1980```json theme={null}2364```json theme={null}
1981{2365{
1986}2370}
1987```2371```
1988 2372
1989Retornar `decision: "block"` ou `continue: false` para o loop agentic antes da próxima chamada do modelo.2373Retornar `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.
1990 2374
1991<h3 id="permissiondenied">2375<h3 id="permissiondenied">
1992 PermissionDenied2376 PermissionDenied
1993</h3>2377</h3>
1994 2378
1995Executa quando o classificador de [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) nega uma chamada de ferramenta. Este hook apenas dispara em modo automático: não executa 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 de classificador, ajustar configuração ou dizer ao modelo que pode tentar novamente a chamada de ferramenta.2379Executado quando [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) 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](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action) 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.
1996 2380
1997Corresponde no nome da ferramenta, mesmos valores que PreToolUse.2381Corresponde ao nome da ferramenta, mesmos valores que PreToolUse.
1998 2382
1999<h4 id="permissiondenied-input">2383<h4 id="permissiondenied-input">
2000 Entrada de PermissionDenied2384 Entrada PermissionDenied
2001</h4>2385</h4>
2002 2386
2003Além dos [campos de entrada comuns](#common-input-fields), hooks PermissionDenied recebem `tool_name`, `tool_input`, `tool_use_id` e `reason`.2387Além dos [campos de entrada comuns](#common-input-fields), 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`](#pretooluse-input).
2004 2388
2005```json theme={null}2389```json theme={null}
2006{2390{
2015 "description": "Clean build directory"2399 "description": "Clean build directory"
2016 },2400 },
2017 "tool_use_id": "toolu_01ABC123...",2401 "tool_use_id": "toolu_01ABC123...",
2018 "reason": "Auto mode denied: command targets a path outside the project"2402 "reason": "[Irreversible Local Destruction]"
2019}2403}
2020```2404```
2021 2405
2022| Campo | Descrição |2406| Campo | Descrição |
2023| :------- | :---------------------------------------------------------------------------- |2407| :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2024| `reason` | A explicação do classificador para por que a chamada de ferramenta foi negada |2408| `reason` | O motivo da negação. Para um veredicto do classificador, na maioria das sessões ele nomeia a regra correspondente entre colchetes, como `[Data Exfiltration]`; veja [Revisar negações](/docs/pt/auto-mode-config#review-denials) para as outras formas. Para uma [negação sem veredicto](#permissiondenied-decision-control), começa com `Auto mode could not evaluate this action and is blocking it for safety`. Para uma negação porque o modelo do classificador não estava disponível, é o texto fixo `Classifier unavailable` |
2025 2409
2026<h4 id="permissiondenied-decision-control">2410<h4 id="permissiondenied-decision-control">
2027 Controle de decisão de PermissionDenied2411 Controle de decisão PermissionDenied
2028</h4>2412</h4>
2029 2413
2030Hooks PermissionDenied podem dizer ao modelo que pode tentar novamente a chamada de ferramenta negada. Retorne um objeto JSON com `hookSpecificOutput.retry` definido para `true`:2414Os 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`:
2031 2415
2032```json theme={null}2416```json theme={null}
2033{2417{
2038}2422}
2039```2423```
2040 2424
2041Quando `retry` é `true`, Claude Code adiciona uma mensagem à conversa dizendo ao modelo que pode tentar novamente a chamada de ferramenta. A negação em si não é revertida. Se seu hook não retorna JSON ou retorna `retry: false`, a negação permanece e o modelo recebe a mensagem de rejeição original.2425Quando `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.
2426
2427Claude Code ignora `retry: true` quando o classificador produziu [nenhum veredicto sobre a ação](/docs/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action): 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.
2042 2428
2043<h3 id="notification">2429<h3 id="notification">
2044 Notification2430 Notification
2045</h3>2431</h3>
2046 2432
2047Executa quando Claude Code envia notificações. Corresponde no tipo de notificação. Omita o matcher para executar hooks para todos os tipos de notificação.2433Executado 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.
2048 2434
2049| Matcher | Quando dispara |2435Você 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.
2050| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |2436
2051| `permission_prompt` | Claude precisa que você aprove um uso de ferramenta |2437| Matcher | Quando é disparado |
2052| `idle_prompt` | Claude está feito e esperando seu próximo prompt |2438| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2053| `auth_success` | Autenticação é concluída |2439| `permission_prompt` | Claude precisa de sua permissão para usar uma ferramenta ou a [solicitação de rede](/docs/pt/sandboxing#network-isolation) de um comando em sandbox, e o prompt esperou cerca de seis segundos |
2054| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação |2440| `idle_prompt` | Claude terminou de responder cerca de 60 segundos atrás e você não digitou desde então |
2055| `elicitation_complete` | Um formulário de elicitação MCP é submetido ou descartado |2441| `auth_success` | A autenticação é concluída |
2056| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |2442| `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação e você não digitou por cerca de seis segundos |
2057| `agent_needs_input` | Uma sessão em background começa esperando sua entrada. Dispara apenas enquanto [agent view](/docs/pt/agent-view) está aberto em um terminal |2443| `elicitation_url_dialog` | Um servidor MCP pede que você abra uma URL do navegador e você não digitou por cerca de seis segundos |
2058| `agent_completed` | Uma sessão em background termina ou falha. Dispara apenas enquanto [agent view](/docs/pt/agent-view) está aberto em um terminal |2444| `elicitation_complete` | Um servidor MCP relata que uma [elicitação de modo URL](#elicitation-input) está completa |
2445| `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta para o servidor |
2446| `agent_needs_input` | Uma sessão em segundo plano começa a esperar sua entrada enquanto [agent view](/docs/pt/agent-view) está aberta em um terminal, ou a sessão atual pede uma pergunta de configuração de terminal de um [colega de equipe de agente](/docs/pt/agent-teams#choose-a-display-mode) e você não digitou por cerca de seis segundos |
2447| `agent_completed` | Uma sessão em segundo plano termina ou falha. Disparado apenas enquanto [agent view](/docs/pt/agent-view) está aberta em um terminal |
2448| `quota_auto_resume_fired` | Claude Code continua sua tarefa após um limite de uso de claude.ai pausá-la: na redefinição, ou mais cedo quando algo que você faz em Claude Code durante a espera, como adicionar créditos de uso, atualizar seu plano ou trocar modelos, torna o uso disponível novamente, com a [exceção de configuração de modelo](/docs/pt/interactive-mode#wait-for-a-usage-limit-to-reset) |
2449| `quota_auto_resume_stale` | Um limite de uso de claude.ai foi redefinido enquanto seu computador dormia por mais de cerca de 30 minutos. Claude Code espera você pressionar `Enter` em vez de continuar. Após um sono mais curto, ele continua e dispara `quota_auto_resume_fired` em vez disso |
2450| `quota_auto_resume_disabled` | Claude Code termina sua espera por um limite de uso de claude.ai sem continuar sua tarefa: [`autoContinueAtUsageLimit`](/docs/pt/settings-reference#autocontinueatusagelimit) foi desativado ou a redefinição se moveu mais de 24 horas no futuro durante uma espera que Claude Code iniciou por conta própria, a tarefa continuada continuou atingindo o limite, ou a continuação foi bloqueada antes de chegar ao modelo. Não é disparado quando você pressiona `Esc` ou `Ctrl+C`, ou escolhe **Don't continue automatically** |
2059 2451
2060Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.2452Os tipos `agent_needs_input` e `agent_completed` requerem Claude Code v2.1.198 ou posterior.
2061 2453
2062Use matchers separados para executar diferentes manipuladores dependendo do tipo de notificação. Esta configuração aciona 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á ocioso:2454Os tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` requerem Claude Code v2.1.234 ou posterior.
2455
2456Em 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.
2457
2458`agent_needs_input` para uma pergunta de configuração de terminal de colega requer Claude Code v2.1.248 ou posterior.
2459
2460<Note>
2461 Os tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` compartilham seu tempo com notificações de desktop, portanto em sessões de terminal você só os vê quando parece que você está longe do terminal:
2462
2463 * Espere `permission_prompt` uma vez que você não digitou por cerca de seis segundos. O temporizador começa quando o prompt de permissão aparece, e cada pressionamento de tecla o adia. Para executar um hook imediatamente quando Claude pede permissão para usar uma ferramenta, use [PermissionRequest](#permissionrequest) em vez disso.
2464 * Espere `idle_prompt` cerca de 60 segundos após Claude terminar de responder, e apenas se você não digitou desde então. Claude Code não envia `idle_prompt` enquanto espera um limite de uso de claude.ai ser redefinido. Quando a espera termina por conta própria, um dos tipos `quota_auto_resume_*` é disparado em vez disso.
2465 * Espere `elicitation_dialog` para um formulário de elicitação, ou `elicitation_url_dialog` para uma solicitação de URL do navegador, uma vez que você não digitou por cerca de seis segundos. Ambos compartilham o mesmo portão de seis segundos que `permission_prompt`: o temporizador começa quando o diálogo aparece, e cada pressionamento de tecla o adia.
2466
2467 Uma solicitação de permissão ou elicitação que chega enquanto outro diálogo está na tela mantém o mesmo portão de seis segundos, cronometrado a partir de quando a solicitação chega. Sua notificação pode alcançá-lo enquanto a solicitação ainda espera atrás do diálogo aberto.
2468</Note>
2469
2470Claude Code cronometra `permission_prompt` diferentemente em sessões onde envia solicitações de permissão para o callback [`canUseTool`](/docs/pt/agent-sdk/user-input) do Agent SDK, que é como Claude Desktop e a extensão VS Code hospedam Claude Code:
2471
2472* Espere `permission_prompt` cerca de seis segundos após Claude pedir permissão. Claude Code não o adia enquanto você digita.
2473* Se você ou um hook [PermissionRequest](#permissionrequest) responder mais cedo, Claude Code não executa `permission_prompt`.
2474* Defina [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/pt/env-vars) como `1` para desativar `permission_prompt` nessas sessões.
2475
2476Antes da v2.1.233, `permission_prompt` não era disparado nessas sessões.
2477
2478Use 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:
2063 2479
2064```json theme={null}2480```json theme={null}
2065{2481{
2089```2505```
2090 2506
2091<h4 id="notification-input">2507<h4 id="notification-input">
2092 Entrada de Notification2508 Entrada Notification
2093</h4>2509</h4>
2094 2510
2095Além dos [campos de entrada comuns](#common-input-fields), hooks Notification recebem `message` com o texto de notificação, um `title` opcional e `notification_type` indicando qual tipo disparou.2511Além dos [campos de entrada comuns](#common-input-fields), os hooks Notification recebem `message` com o texto de notificação, um `title` opcional e `notification_type` indicando qual tipo foi disparado.
2096 2512
2097```json theme={null}2513```json theme={null}
2098{2514{
2106}2522}
2107```2523```
2108 2524
2109Hooks Notification não podem bloquear ou modificar notificações. Eles são destinados a efeitos colaterais como encaminhar a notificação para um serviço externo. Os [campos de saída JSON](#json-output) comuns como `systemMessage` se aplicam.2525Os hooks Notification não podem bloquear ou modificar notificações. Claude Code descarta seus campos `systemMessage` e `continue` mas ainda emite [`terminalSequence`](#emit-terminal-notifications), 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.
2110 2526
2111<h3 id="subagentstart">2527<h3 id="subagentstart">
2112 SubagentStart2528 SubagentStart
2113</h3>2529</h3>
2114 2530
2115Executa quando um subagente do Claude Code é gerado via ferramenta Agent. 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](/docs/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo.2531Executado quando Claude gera um subagente com a ferramenta Agent, quando Claude [retoma um subagente](/docs/pt/sub-agents#resume-subagents) e cada vez que um [colega de equipe de agente](/docs/pt/agent-teams) 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](/docs/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo.
2116 2532
2117Para subagentes fornecidos por um [plugin](/docs/pt/plugins), o tipo de agente é o identificador com escopo de plugin como `my-plugin:reviewer`, não o nome frontmatter simples. O dois-pontos coloca um nome com escopo de plugin no caminho de expressão regular, então ancorize o matcher com `^` e `$` para uma correspondência exata: `^my-plugin:reviewer$`.2533Para subagentes enviados por um [plugin](/docs/pt/plugins), 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$`.
2118 2534
2119<h4 id="subagentstart-input">2535<h4 id="subagentstart-input">
2120 Entrada de SubagentStart2536 Entrada SubagentStart
2121</h4>2537</h4>
2122 2538
2123Além dos [campos de entrada comuns](#common-input-fields), hooks SubagentStart recebem `agent_id` com o identificador único para o subagente e `agent_type` com o nome do agente que o matcher filtra.2539Além dos [campos de entrada comuns](#common-input-fields), 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.
2124 2540
2125```json theme={null}2541```json theme={null}
2126{2542{
2133}2549}
2134```2550```
2135 2551
2136Hooks SubagentStart não podem bloquear criação de subagente, mas podem injetar contexto no subagente. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, você pode retornar:2552Os 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](#json-output) disponíveis para todos os hooks, você pode retornar:
2137 2553
2138| Campo | Descrição |2554| Campo | Descrição |
2139| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2555| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2140| `additionalContext` | String adicionada ao contexto do subagente no início de sua conversa, antes de seu primeiro prompt. Consulte [Adicionar contexto para Claude](#add-context-for-claude) |2556| `additionalContext` | String adicionada ao contexto do subagente no início de sua conversa, antes de seu primeiro prompt. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
2141 2557
2142```json theme={null}2558```json theme={null}
2143{2559{
2148}2564}
2149```2565```
2150 2566
2567Quando 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](/docs/pt/prompt-caching#subagents-and-the-cache) do subagente intacto. Após [compactação automática](/docs/pt/sub-agents#auto-compaction) descartar essa cópia, Claude Code injeta o contexto da próxima execução novamente.
2568
2151<h3 id="subagentstop">2569<h3 id="subagentstop">
2152 SubagentStop2570 SubagentStop
2153</h3>2571</h3>
2154 2572
2155Executa quando um subagente do Claude Code terminou de responder. Corresponde no tipo de agente, mesmos valores que SubagentStart.2573Executado quando um subagente Claude Code terminou de responder. Corresponde ao tipo de agente, mesmos valores que SubagentStart.
2156 2574
2157<h4 id="subagentstop-input">2575<h4 id="subagentstop-input">
2158 Entrada de SubagentStop2576 Entrada SubagentStop
2159</h4>2577</h4>
2160 2578
2161Além dos [campos de entrada comuns](#common-input-fields), 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, então hooks podem acessá-lo sem analisar o arquivo de transcrição.2579Além dos [campos de entrada comuns](#common-input-fields), 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.
2580
2581No Claude Code v2.1.271 ou posterior, um subagente que é executado com a ferramenta [`SubagentHandback`](/docs/pt/tools-reference) 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`.
2162 2582
2163Hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [Entrada de Stop](#stop-input), disponíveis no Claude Code v2.1.145 ou posterior. Ambos os arrays têm escopo para a sessão pai, não para o subagente.2583Os hooks SubagentStop também recebem os arrays `background_tasks` e `session_crons` descritos em [entrada Stop](#stop-input). Ambos os arrays estão no escopo da sessão pai, não do subagente.
2164 2584
2165```json theme={null}2585```json theme={null}
2166{2586{
2179}2599}
2180```2600```
2181 2601
2182Hooks SubagentStop usam o mesmo formato de controle de decisão que [hooks Stop](#stop-decision-control), incluindo `hookSpecificOutput.additionalContext` com `hookEventName` definido para `"SubagentStop"`, para feedback não-erro que mantém o subagente em execução. Retornar `decision: "block"` com uma `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Para injetar contexto na sessão pai após um subagente retornar, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent` em vez disso.2602Os hooks SubagentStop usam o mesmo formato de controle de decisão que [hooks Stop](#stop-decision-control), 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`](#posttooluse) na ferramenta `Agent` em vez disso.
2183 2603
2184<h3 id="taskcreated">2604<h3 id="taskcreated">
2185 TaskCreated2605 TaskCreated
2186</h3>2606</h3>
2187 2607
2188Executa quando uma tarefa está sendo criada via ferramenta `TaskCreate`. Use isso para impor convenções de nomenclatura, exigir descrições de tarefa ou prevenir que certas tarefas sejam criadas.2608Executado 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](/docs/pt/tools-reference#task-tool-availability), este evento não é disparado.
2189 2609
2190Quando um hook `TaskCreated` sai com código 2, a tarefa não é criada e a mensagem de stderr é alimentada de volta ao modelo como feedback. Para parar o colega inteiramente em vez de re-executá-lo, retorne JSON com `{"continue": false, "stopReason": "..."}`. Hooks TaskCreated não suportam matchers e disparam em cada ocorrência.2610Os hooks TaskCreated não suportam matchers e são disparados em cada ocorrência.
2191 2611
2192<h4 id="taskcreated-input">2612<h4 id="taskcreated-input">
2193 Entrada de TaskCreated2613 Entrada TaskCreated
2194</h4>2614</h4>
2195 2615
2196Além dos [campos de entrada comuns](#common-input-fields), hooks TaskCreated recebem `task_id`, `task_subject` e opcionalmente `task_description`, `teammate_name` e `team_name`.2616Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCreated recebem `task_id`, `task_subject` e opcionalmente `task_description`, `teammate_name` e `team_name`.
2197 2617
2198```json theme={null}2618```json theme={null}
2199{2619{
2200 "session_id": "abc123",2620 "session_id": "abc123",
2201 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",2621 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2202 "cwd": "/Users/...",2622 "cwd": "/Users/...",
2203 "permission_mode": "default",
2204 "hook_event_name": "TaskCreated",2623 "hook_event_name": "TaskCreated",
2205 "task_id": "task-001",2624 "task_id": "task-001",
2206 "task_subject": "Implement user authentication",2625 "task_subject": "Implement user authentication",
2211```2630```
2212 2631
2213| Campo | Descrição |2632| Campo | Descrição |
2214| :----------------- | :------------------------------------------------------------------------- |2633| :----------------- | :----------------------------------------------------------------------------------- |
2215| `task_id` | Identificador da tarefa sendo criada |2634| `task_id` | Identificador da tarefa sendo criada |
2216| `task_subject` | Título da tarefa |2635| `task_subject` | Título da tarefa |
2217| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2636| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2218| `teammate_name` | Nome do colega criando a tarefa. Pode estar ausente |2637| `teammate_name` | Nome do colega criando a tarefa. Pode estar ausente |
2219| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |2638| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2220 2639
2221<h4 id="taskcreated-decision-control">2640<h4 id="taskcreated-decision-control">
2222 Controle de decisão de TaskCreated2641 Controle de decisão TaskCreated
2223</h4>2642</h4>
2224 2643
2225Hooks TaskCreated suportam duas formas de controlar criação de tarefa:2644Um 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.
2226 2645
2227* **Código de saída 2**: a tarefa não é criada e a mensagem de stderr é alimentada de volta ao modelo como feedback.2646* **Código de saída 2**: Claude Code retorna o texto stderr como a mensagem.
2228* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.2647* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code retorna `reason` como a mensagem.
2229 2648
2230Este exemplo bloqueia tarefas cujos assuntos não seguem o formato obrigatório:2649Este exemplo bloqueia tarefas cujos assuntos não seguem o formato necessário:
2231 2650
2232```bash theme={null}2651```bash theme={null}
2233#!/bin/bash2652#!/bin/bash
2246 TaskCompleted2665 TaskCompleted
2247</h3>2666</h3>
2248 2667
2249Executa quando uma tarefa está sendo marcada como concluída. Isso dispara 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](/docs/pt/agent-teams) termina seu turno com tarefas em progresso. Use isso para impor critérios de conclusão como testes aprovados ou verificações de lint antes de uma tarefa fechar.2668Executado 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](/docs/pt/agent-teams) 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.
2250 2669
2251Quando um hook `TaskCompleted` sai com código 2, a tarefa não é marcada como concluída e a mensagem de stderr é alimentada de volta ao modelo como feedback. Para parar o colega inteiramente em vez de re-executá-lo, retorne JSON com `{"continue": false, "stopReason": "..."}`. Hooks TaskCompleted não suportam matchers e disparam em cada ocorrência.2670Os hooks TaskCompleted não suportam matchers e são disparados em cada ocorrência.
2252 2671
2253<h4 id="taskcompleted-input">2672<h4 id="taskcompleted-input">
2254 Entrada de TaskCompleted2673 Entrada TaskCompleted
2255</h4>2674</h4>
2256 2675
2257Além dos [campos de entrada comuns](#common-input-fields), hooks TaskCompleted recebem `task_id`, `task_subject` e opcionalmente `task_description`, `teammate_name` e `team_name`.2676Além dos [campos de entrada comuns](#common-input-fields), os hooks TaskCompleted recebem `task_id`, `task_subject` e opcionalmente `task_description`, `teammate_name` e `team_name`.
2258 2677
2259```json theme={null}2678```json theme={null}
2260{2679{
2272```2691```
2273 2692
2274| Campo | Descrição |2693| Campo | Descrição |
2275| :----------------- | :------------------------------------------------------------------------- |2694| :----------------- | :----------------------------------------------------------------------------------- |
2276| `task_id` | Identificador da tarefa sendo concluída |2695| `task_id` | Identificador da tarefa sendo concluída |
2277| `task_subject` | Título da tarefa |2696| `task_subject` | Título da tarefa |
2278| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2697| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |
2279| `teammate_name` | Nome do colega completando a tarefa. Pode estar ausente |2698| `teammate_name` | Nome do colega concluindo a tarefa. Pode estar ausente |
2280| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |2699| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2281 2700
2282<h4 id="taskcompleted-decision-control">2701<h4 id="taskcompleted-decision-control">
2283 Controle de decisão de TaskCompleted2702 Controle de decisão TaskCompleted
2284</h4>2703</h4>
2285 2704
2286Hooks TaskCompleted suportam duas formas de controlar conclusão de tarefa:2705Os hooks TaskCompleted suportam duas maneiras de controlar a conclusão da tarefa:
2287 2706
2288* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem de stderr é alimentada de volta ao modelo como feedback.2707* **Código de saída 2**: a tarefa não é marcada como concluída e a mensagem stderr é retornada ao modelo como feedback.
2289* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.2708* **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.
2290 2709
2291Este exemplo executa testes e bloqueia conclusão de tarefa se falharem:2710Este exemplo executa testes e bloqueia a conclusão da tarefa se falharem:
2292 2711
2293```bash theme={null}2712```bash theme={null}
2294#!/bin/bash2713#!/bin/bash
2295INPUT=$(cat)2714INPUT=$(cat)
2296TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')2715TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
2297 2716
2298# Execute a suite de testes2717# Run the test suite
2299if ! npm test 2>&1; then2718if ! npm test 2>&1; then
2300 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&22719 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
2301 exit 22720 exit 2
2308 Stop2727 Stop
2309</h3>2728</h3>
2310 2729
2311Executa quando o agente Claude Code principal terminou de responder. Não executa se a parada ocorreu devido a uma interrupção do usuário. Erros de API disparam [StopFailure](#stopfailure) em vez disso.2730Executado 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](#stopfailure) em vez disso.
2312 2731
2313<Tip>2732<Tip>
2314 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop baseado em prompt com escopo de sessão. Use-o quando você quiser que Claude continue trabalhando até que uma condição se mantenha sem escrever configuração de hook.2733 O comando [`/goal`](/docs/pt/goal) é um atalho integrado para um hook Stop baseado em prompt com escopo de sessão. Use-o quando você quer que Claude continue trabalhando em direção a uma condição sem escrever configuração de hook.
2315</Tip>2734</Tip>
2316 2735
2317<h4 id="stop-input">2736<h4 id="stop-input">
2318 Entrada de Stop2737 Entrada Stop
2319</h4>2738</h4>
2320 2739
2321Além dos [campos de entrada comuns](#common-input-fields), 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 prevenir que Claude Code execute indefinidamente. Claude Code sobrescreve o hook e termina o turno após 8 bloqueios consecutivos.2740Além dos [campos de entrada comuns](#common-input-fields), 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.
2322 2741
2323O campo `last_assistant_message` contém o conteúdo de texto da resposta final de Claude, então 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.2742O 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.
2324 2743
2325Os arrays `background_tasks` e `session_crons`, disponíveis no Claude Code v2.1.145 ou posterior, permitem que hooks distingam "sessão está feita" de "sessão está pausada esperando que trabalho em background 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.2744Os 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.
2326 2745
2327Cada entrada em `background_tasks` descreve uma tarefa em voo e usa esses campos:2746Cada entrada em `background_tasks` descreve uma tarefa em voo e usa estes campos:
2328 2747
2329| Campo | Descrição |2748| Campo | Descrição |
2330| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |2749| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2331| `id` | Identificador de tarefa |2750| `id` | Identificador de tarefa |
2332| `type` | Rótulo de tipo de tarefa amigável como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso do Claude Code criou a tarefa. Volta para o discriminante bruto para tipos não reconhecidos |2751| `type` | Rótulo de tipo de tarefa amigável como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` ou `MCP task`. Cada rótulo identifica qual recurso Claude Code criou a tarefa. Volta para o discriminante bruto para tipos não reconhecidos |
2333| `status` | Status atual da tarefa |2752| `status` | Status atual da tarefa |
2334| `description` | Descrição de texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` em string quando cortado |2753| `description` | Descrição de texto livre, limitada a 1000 caracteres com um marcador `… [+N chars]` em string quando cortado |
2335| `command` | Linha de comando shell, limitada a 1000 caracteres. Presente apenas para tarefas `shell` |2754| `command` | Linha de comando de shell, limitada a 1000 caracteres. Presente apenas para tarefas `shell` |
2336| `agent_type` | Nome de tipo de subagente. Presente apenas para tarefas `subagent` |2755| `agent_type` | Nome de tipo de subagente. Presente apenas para tarefas `subagent` |
2337| `server` | Nome do servidor MCP. Presente apenas para tarefas `monitor` e `MCP task` |2756| `server` | Nome do servidor MCP. Presente apenas para tarefas `monitor` e `MCP task` |
2338| `tool` | Nome da ferramenta MCP. Presente apenas para tarefas `monitor` e `MCP task` |2757| `tool` | Nome da ferramenta MCP. Presente apenas para tarefas `monitor` e `MCP task` |
2341Cada entrada em `session_crons` descreve um despertar agendado com escopo de sessão, originário de `CronCreate`, `ScheduleWakeup` e `/loop`:2760Cada entrada em `session_crons` descreve um despertar agendado com escopo de sessão, originário de `CronCreate`, `ScheduleWakeup` e `/loop`:
2342 2761
2343| Campo | Descrição |2762| Campo | Descrição |
2344| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |2763| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
2345| `id` | Identificador de tarefa cron |2764| `id` | Identificador de tarefa Cron |
2346| `schedule` | Expressão cron, por exemplo `0 9 * * 1-5` |2765| `schedule` | Expressão Cron, por exemplo `0 9 * * 1-5` |
2347| `recurring` | `false` para despertares únicos cuja agenda codifica um único tempo de disparo, `true` para tarefas que disparam novamente em cada correspondência |2766| `recurring` | `false` para despertares únicos cuja programação codifica um tempo de disparo único, `true` para tarefas que disparam novamente em cada correspondência |
2348| `prompt` | Prompt submetido quando o cron dispara, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |2767| `prompt` | Prompt enviado quando o cron dispara, limitado a 1000 caracteres com o mesmo marcador `… [+N chars]` |
2349 2768
2350Este exemplo mostra uma entrada de Stop com uma tarefa shell em voo e um cron recorrente:2769Este exemplo mostra uma entrada Stop com uma tarefa de shell em voo e um cron recorrente:
2351 2770
2352```json theme={null}2771```json theme={null}
2353{2772{
2379```2798```
2380 2799
2381<h4 id="stop-decision-control">2800<h4 id="stop-decision-control">
2382 Controle de decisão de Stop2801 Controle de decisão Stop
2383</h4>2802</h4>
2384 2803
2385Hooks `Stop` e `SubagentStop` podem controlar se Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2804Os hooks `Stop` e `SubagentStop` podem controlar se Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:
2386 2805
2387| Campo | Descrição |2806| Campo | Descrição |
2388| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2807| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2389| `decision` | `"block"` previne Claude de parar. Omita para permitir que Claude pare |2808| `decision` | `"block"` impede que Claude pare. Omita para permitir que Claude pare |
2390| `reason` | Obrigatório quando `decision` é `"block"`. Diz ao Claude por que deve continuar |2809| `reason` | Necessário quando `decision` é `"block"`. Diz ao Claude por que deve continuar |
2391| `hookSpecificOutput.additionalContext` | Feedback não-erro para Claude. A conversa continua para que Claude possa agir sobre isso, mas diferentemente de `decision: "block"` é mostrado na transcrição como feedback de hook em vez de erro de hook |2810| `hookSpecificOutput.additionalContext` | Feedback sem erro para Claude. A conversa continua para que Claude possa agir sobre isso, mas ao contrário de `decision: "block"` é mostrado na transcrição como feedback de hook em vez de um erro de hook |
2811
2812Um 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.
2392 2813
2393```json theme={null}2814```json theme={null}
2394{2815{
2397}2818}
2398```2819```
2399 2820
2400Use `additionalContext` quando o hook está funcionando como projetado e dando orientação a Claude, como "execute a suite de testes antes de terminar". Mantém a conversa indo 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:2821Use `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:
2401 2822
2402```json theme={null}2823```json theme={null}
2403{2824{
2412 StopFailure2833 StopFailure
2413</h3>2834</h3>
2414 2835
2415Executa em vez de [Stop](#stop) quando o turno termina devido a um erro de API. Saída e código de saída são ignorados. Use isso para registrar falhas, enviar alertas ou tomar ações de recuperação quando Claude não consegue completar uma resposta devido a limites de taxa, problemas de autenticação ou outros erros de API.2836Executado em vez de [Stop](#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`](#emit-terminal-notifications). 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.
2416 2837
2417<h4 id="stopfailure-input">2838<h4 id="stopfailure-input">
2418 Entrada de StopFailure2839 Entrada StopFailure
2419</h4>2840</h4>
2420 2841
2421Além dos [campos de entrada comuns](#common-input-fields), 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.2842Além dos [campos de entrada comuns](#common-input-fields), 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.
2422 2843
2423| Campo | Descrição |2844| Campo | Descrição |
2424| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2845| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2425| `error` | Tipo de erro: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens` ou `unknown` |2846| `error` | Tipo de erro: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error` ou `unknown` |
2426| `error_details` | Detalhes adicionais sobre o erro, quando disponível |2847| `error_details` | Detalhes adicionais sobre o erro, quando disponível |
2427| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Diferentemente de `Stop` e `SubagentStop`, onde este campo contém a saída conversacional de Claude, para `StopFailure` contém a string de erro da API em si, como `"API Error: Rate limit reached"` |2848| `last_assistant_message` | O texto de erro renderizado mostrado na conversa. Ao contrário de `Stop` e `SubagentStop`, onde este campo contém a saída conversacional do Claude, para `StopFailure` ele contém a string de erro da API em si, como `"API Error: Rate limit reached"` |
2428 2849
2429```json theme={null}2850```json theme={null}
2430{2851{
2438}2859}
2439```2860```
2440 2861
2441Hooks StopFailure não têm controle de decisão. Eles executam apenas para fins de notificação e logging.2862Os hooks StopFailure não têm controle de decisão. Eles são executados apenas para fins de notificação e registro.
2442 2863
2443<h3 id="teammateidle">2864<h3 id="teammateidle">
2444 TeammateIdle2865 TeammateIdle
2445</h3>2866</h3>
2446 2867
2447Executa quando um colega de [equipe de agente](/docs/pt/agent-teams) está prestes a ficar ocioso 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.2868Executado quando um [colega de equipe de agente](/docs/pt/agent-teams) 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.
2448 2869
2449Quando um hook `TeammateIdle` sai com código 2, o colega recebe a mensagem de stderr como feedback e continua trabalhando em vez de ficar ocioso. Para parar o colega inteiramente em vez de re-executá-lo, retorne JSON com `{"continue": false, "stopReason": "..."}`. Hooks TeammateIdle não suportam matchers e disparam em cada ocorrência.2870Os hooks TeammateIdle não suportam matchers e são disparados em cada ocorrência.
2450 2871
2451<h4 id="teammateidle-input">2872<h4 id="teammateidle-input">
2452 Entrada de TeammateIdle2873 Entrada TeammateIdle
2453</h4>2874</h4>
2454 2875
2455Além dos [campos de entrada comuns](#common-input-fields), hooks TeammateIdle recebem `teammate_name` e `team_name`.2876Além dos [campos de entrada comuns](#common-input-fields), os hooks TeammateIdle recebem `teammate_name` e `team_name`.
2456 2877
2457```json theme={null}2878```json theme={null}
2458{2879{
2467```2888```
2468 2889
2469| Campo | Descrição |2890| Campo | Descrição |
2470| :-------------- | :------------------------------------------------------------------------- |2891| :-------------- | :----------------------------------------------------------------------------------- |
2471| `teammate_name` | Nome do colega que está prestes a ficar ocioso |2892| `teammate_name` | Nome do colega que está prestes a ficar inativo |
2472| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |2893| `team_name` | Descontinuado. Nome de equipe derivado de sessão; será removido em uma versão futura |
2473 2894
2474<h4 id="teammateidle-decision-control">2895<h4 id="teammateidle-decision-control">
2475 Controle de decisão de TeammateIdle2896 Controle de decisão TeammateIdle
2476</h4>2897</h4>
2477 2898
2478Hooks TeammateIdle suportam duas formas de controlar comportamento de colega:2899Os hooks TeammateIdle suportam duas maneiras de controlar o comportamento do colega:
2479 2900
2480* **Código de saída 2**: o colega recebe a mensagem de stderr como feedback e continua trabalhando em vez de ficar ocioso.2901* **Código de saída 2**: o colega recebe a mensagem stderr como feedback e continua trabalhando em vez de ficar inativo.
2481* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.2902* **JSON `{"continue": false, "stopReason": "..."}`**: para o colega inteiramente, correspondendo ao comportamento do hook `Stop`. O `stopReason` é mostrado ao usuário.
2482 2903
2483Este exemplo verifica que um artefato de build existe antes de permitir que um colega fique ocioso:2904Este exemplo verifica se um artefato de compilação existe antes de permitir que um colega fique inativo:
2484 2905
2485```bash theme={null}2906```bash theme={null}
2486#!/bin/bash2907#!/bin/bash
2497 ConfigChange2918 ConfigChange
2498</h3>2919</h3>
2499 2920
2500Executa 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 a arquivos de configuração.2921Executado 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.
2501 2922
2502Hooks ConfigChange disparam para mudanças em arquivos de configurações, configurações de política gerenciada e arquivos de skill. O campo `source` na entrada diz qual tipo de configuração mudou, e o campo `file_path` opcional fornece o caminho para o arquivo mudado.2923Claude 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](/docs/pt/server-managed-settings) e mudanças em preferências gerenciadas macOS ou política de registro Windows sem executá-los. Em WSL com [`wslInheritsWindowsSettings`](/docs/pt/settings-reference#wslinheritswindowssettings), ele também aplica um arquivo de configurações gerenciadas do lado Windows alterado em sua pesquisa de política sem executá-los.
2503 2924
2504O matcher filtra na fonte de configuração:2925O matcher filtra na fonte de configuração:
2505 2926
2506| Matcher | Quando dispara |2927| Matcher | Quando é disparado |
2507| :----------------- | :-------------------------------------------- |2928| :----------------- | :------------------------------------------------------------------ |
2508| `user_settings` | `~/.claude/settings.json` muda |2929| `user_settings` | `~/.claude/settings.json` muda |
2509| `project_settings` | `.claude/settings.json` muda |2930| `project_settings` | `.claude/settings.json` muda |
2510| `local_settings` | `.claude/settings.local.json` muda |2931| `local_settings` | `.claude/settings.local.json` muda |
2511| `policy_settings` | Configurações de política gerenciada mudam |2932| `policy_settings` | `managed-settings.json` ou um arquivo em `managed-settings.d/` muda |
2512| `skills` | Um arquivo de skill em `.claude/skills/` muda |2933| `skills` | Um arquivo de skill em `.claude/skills/` muda |
2513 2934
2514Este exemplo registra todas as mudanças de configuração para auditoria de segurança:2935Este exemplo registra todas as mudanças de configuração para auditoria de segurança:
2532```2953```
2533 2954
2534<h4 id="configchange-input">2955<h4 id="configchange-input">
2535 Entrada de ConfigChange2956 Entrada ConfigChange
2536</h4>2957</h4>
2537 2958
2538Além dos [campos de entrada comuns](#common-input-fields), 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.2959Além dos [campos de entrada comuns](#common-input-fields), 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.
2539 2960
2540```json theme={null}2961```json theme={null}
2541{2962{
2549```2970```
2550 2971
2551<h4 id="configchange-decision-control">2972<h4 id="configchange-decision-control">
2552 Controle de decisão de ConfigChange2973 Controle de decisão ConfigChange
2553</h4>2974</h4>
2554 2975
2555Hooks ConfigChange podem bloquear mudanças de configuração de entrar em efeito. Use código de saída 2 ou um JSON `decision` para prevenir a mudança. Quando bloqueado, as novas configurações não são aplicadas à sessão em execução.2976Os 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.
2556 2977
2557| Campo | Descrição |2978| Campo | Descrição |
2558| :--------- | :----------------------------------------------------------------------------------------- |2979| :--------- | :------------------------------------------------------------------------------------------ |
2559| `decision` | `"block"` previne a mudança de configuração de ser aplicada. Omita para permitir a mudança |2980| `decision` | `"block"` impede que a mudança de configuração seja aplicada. Omita para permitir a mudança |
2560| `reason` | Explicação mostrada ao usuário quando `decision` é `"block"` |2981| `reason` | Aceito mas nunca mostrado |
2561 2982
2562```json theme={null}2983```json theme={null}
2563{2984{
2566}2987}
2567```2988```
2568 2989
2569Mudanças `policy_settings` não podem ser bloqueadas. Hooks ainda disparam para fontes `policy_settings`, então você pode usá-los para logging de auditoria, mas qualquer decisão de bloqueio é ignorada. Isso garante que configurações gerenciadas por empresa sempre entrem em efeito.2990As 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](/docs/pt/server-managed-settings) chegam ou são atualizadas.
2991
2992Claude 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.
2570 2993
2571<h3 id="cwdchanged">2994<h3 id="cwdchanged">
2572 CwdChanged2995 CwdChanged
2573</h3>2996</h3>
2574 2997
2575Executa quando o diretório de trabalho muda durante uma sessão, 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](#filechanged) para ferramentas como [direnv](https://direnv.net/) que gerenciam ambiente por diretório.2998Executado 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](#filechanged) para ferramentas como [direnv](https://direnv.net/) que gerenciam ambiente por diretório.
2576 2999
2577Hooks CwdChanged têm acesso a `CLAUDE_ENV_FILE`. Variáveis escritas para esse arquivo persistem em comandos Bash subsequentes para a sessão, assim como em [hooks SessionStart](#persist-environment-variables).3000Os hooks CwdChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento CwdChanged, quando Claude Code as limpa.
2578 3001
2579CwdChanged não suporta matchers e dispara em cada mudança de diretório.3002CwdChanged não suporta matchers e é disparado em cada ocorrência.
2580 3003
2581<h4 id="cwdchanged-input">3004<h4 id="cwdchanged-input">
2582 Entrada de CwdChanged3005 Entrada CwdChanged
2583</h4>3006</h4>
2584 3007
2585Além dos [campos de entrada comuns](#common-input-fields), hooks CwdChanged recebem `old_cwd` e `new_cwd`.3008Além dos [campos de entrada comuns](#common-input-fields), os hooks CwdChanged recebem `old_cwd` e `new_cwd`.
2586 3009
2587```json theme={null}3010```json theme={null}
2588{3011{
2596```3019```
2597 3020
2598<h4 id="cwdchanged-output">3021<h4 id="cwdchanged-output">
2599 Saída de CwdChanged3022 Saída CwdChanged
2600</h4>3023</h4>
2601 3024
2602Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo [FileChanged](#filechanged) monitora:3025Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks CwdChanged podem retornar `watchPaths` para definir dinamicamente quais caminhos de arquivo [FileChanged](#filechanged) observa:
2603 3026
2604| Campo | Descrição |3027| Campo | Descrição |
2605| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3028| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2606| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Caminhos de sua configuração `matcher` são sempre monitorados. Retornar um array vazio limpa a lista dinâmica, que é típico ao entrar em um novo diretório |3029| `watchPaths` | Array de caminhos absolutos. Substitui a lista de observação dinâmica atual. Caminhos de sua configuração `matcher` são sempre observados. Retornar um array vazio limpa a lista dinâmica, que é típico ao entrar em um novo diretório |
2607 3030
2608Hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.3031Os hooks CwdChanged não têm controle de decisão. Eles não podem bloquear a mudança de diretório.
3032
3033Claude 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.
3034
3035<h3 id="directoryadded">
3036 DirectoryAdded
3037</h3>
3038
3039Executado 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.
3040
3041Claude Code não dispara este evento quando:
3042
3043* Você passa um diretório com a flag de startup `--add-dir`; [SessionStart](#sessionstart) cobre esses diretórios
3044* Você adiciona um diretório na aba `/permissions` Workspace
3045* Você adiciona um diretório que já é um diretório de trabalho ou está dentro de um
3046
3047Claude 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.
3048
3049Claude 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.
3050
3051O matcher filtra em como o diretório foi adicionado:
3052
3053| Matcher | Quando é disparado |
3054| :------------------- | :-------------------------------------------------------------------------------------- |
3055| `slash_command` | Você adiciona um diretório com `/add-dir` |
3056| `register_repo_root` | Um cliente SDK adiciona um diretório com a solicitação de controle `register_repo_root` |
3057
3058<h4 id="directoryadded-input">
3059 Entrada DirectoryAdded
3060</h4>
3061
3062Além dos [campos de entrada comuns](#common-input-fields), os hooks DirectoryAdded recebem `directory` e `source`.
3063
3064| Campo | Descrição |
3065| :---------- | :--------------------------------------------------------------------------------------------------------------------------------- |
3066| `directory` | Caminho absoluto do diretório que foi adicionado |
3067| `source` | Como o diretório foi adicionado, `"slash_command"` para `/add-dir` ou `"register_repo_root"` para a solicitação de controle do SDK |
3068
3069```json theme={null}
3070{
3071 "session_id": "abc123",
3072 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
3073 "cwd": "/Users/my-project",
3074 "hook_event_name": "DirectoryAdded",
3075 "directory": "/Users/my-other-repo",
3076 "source": "slash_command"
3077}
3078```
3079
3080Os 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:
3081
3082* `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
3083* `register_repo_root`: Claude Code escreve saída `systemMessage` e saída de falha apenas no log de depuração
2609 3084
2610<h3 id="filechanged">3085<h3 id="filechanged">
2611 FileChanged3086 FileChanged
2612</h3>3087</h3>
2613 3088
2614Executa quando um arquivo monitorado muda no disco. Útil para recarregar variáveis de ambiente quando arquivos de configuração do projeto são modificados.3089Executado 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.
2615 3090
2616O `matcher` para este evento serve dois papéis:3091O `matcher` para este evento serve dois papéis:
2617 3092
2618* **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 nomeado `^\.env`.3093* **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`.
2619* **Filtrar quais hooks executam**: quando um arquivo monitorado muda, o mesmo valor filtra quais grupos de hook executam usando as [regras de matcher](#matcher-patterns) padrão contra o basename do arquivo alterado.3094* **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](#matcher-patterns) padrão contra o nome base do arquivo alterado.
3095
3096Este 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:
3097
3098```json theme={null}
3099{
3100 "hooks": {
3101 "FileChanged": [
3102 {
3103 "matcher": "data.csv",
3104 "hooks": [
3105 {
3106 "type": "command",
3107 "command": "/path/to/normalize-line-endings.sh"
3108 }
3109 ]
3110 }
3111 ]
3112 }
3113}
3114```
3115
3116O hook lê o caminho absoluto do arquivo alterado do campo `file_path` da [entrada JSON](#filechanged-input) 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:
3117
3118```bash theme={null}
3119#!/bin/bash
3120FILE=$(jq -r .file_path)
3121if grep -q $'\r$' "$FILE"; then
3122 perl -pi -e 's/\r$//' "$FILE"
3123fi
3124```
3125
3126Para 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.
2620 3127
2621Hooks FileChanged têm acesso a `CLAUDE_ENV_FILE`. Variáveis escritas para esse arquivo persistem em comandos Bash subsequentes para a sessão, assim como em [hooks SessionStart](#persist-environment-variables).3128Para observar arquivos que você não pode nomear antecipadamente, retorne [`watchPaths`](#filechanged-output) 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](#sessionstart-decision-control) ou [CwdChanged](#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 `*`.
3129
3130Os hooks FileChanged têm acesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variáveis escritas nesse arquivo persistem em comandos Bash subsequentes até o próximo evento [CwdChanged](#cwdchanged), quando Claude Code as limpa.
2622 3131
2623<h4 id="filechanged-input">3132<h4 id="filechanged-input">
2624 Entrada de FileChanged3133 Entrada FileChanged
2625</h4>3134</h4>
2626 3135
2627Além dos [campos de entrada comuns](#common-input-fields), hooks FileChanged recebem `file_path` e `event`.3136Além dos [campos de entrada comuns](#common-input-fields), os hooks FileChanged recebem `file_path` e `event`.
2628 3137
2629| Campo | Descrição |3138| Campo | Descrição |
2630| :---------- | :---------------------------------------------------------------------------------------------------------------------------- |3139| :---------- | :---------------------------------------------------------------------------------------------------------------------------- |
2631| `file_path` | Caminho absoluto para o arquivo que mudou |3140| `file_path` | Caminho absoluto para o arquivo que mudou |
2632| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo deletado |3141| `event` | O que aconteceu: `"change"` para um arquivo modificado, `"add"` para um arquivo criado ou `"unlink"` para um arquivo excluído |
2633 3142
2634```json theme={null}3143```json theme={null}
2635{3144{
2643```3152```
2644 3153
2645<h4 id="filechanged-output">3154<h4 id="filechanged-output">
2646 Saída de FileChanged3155 Saída FileChanged
2647</h4>3156</h4>
2648 3157
2649Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são monitorados:3158Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, os hooks FileChanged podem retornar `watchPaths` para atualizar dinamicamente quais caminhos de arquivo são observados:
2650 3159
2651| Campo | Descrição |3160| Campo | Descrição |
2652| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3161| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2653| `watchPaths` | Array de caminhos absolutos. Substitui a lista de monitoramento dinâmica atual. Caminhos de sua configuração `matcher` são sempre monitorados. Use isso quando seu script de hook descobre arquivos adicionais para monitorar baseado no arquivo alterado |3162| `watchPaths` | Array de caminhos absolutos. Substitui a lista de observação dinâmica atual. Caminhos de sua configuração `matcher` são sempre observados. Use isso quando seu script de hook descobre arquivos adicionais para observar com base no arquivo alterado |
3163
3164Os hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.
2654 3165
2655Hooks FileChanged não têm controle de decisão. Eles não podem bloquear a mudança de arquivo de ocorrer.3166Claude 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.
2656 3167
2657<h3 id="worktreecreate">3168<h3 id="worktreecreate">
2658 WorktreeCreate3169 WorktreeCreate
2659</h3>3170</h3>
2660 3171
2661Executa quando um worktree está sendo criado, seja de `claude --worktree` ou de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope). 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.3172Executado quando uma worktree está sendo criada, seja de `claude --worktree`, de um [subagente usando `isolation: "worktree"`](/docs/pt/sub-agents#choose-the-subagent-scope) ou para uma [sessão em segundo plano](/docs/pt/agent-view#how-file-edits-are-isolated) 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.
2662 3173
2663Porque o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) não é processado. Se você precisar copiar arquivos de configuração local como `.env` para o novo worktree, faça isso dentro de seu script de hook.3174Como o hook substitui o comportamento padrão inteiramente, [`.worktreeinclude`](/docs/pt/worktrees#copy-gitignored-files-into-worktrees) 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.
2664 3175
2665O hook deve retornar o caminho para o diretório worktree criado. Claude Code usa este caminho como o diretório de trabalho para a sessão isolada. Consulte [Saída de WorktreeCreate](#worktreecreate-output) para como cada tipo de hook retorna o caminho.3176O 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](#worktreecreate-output) para como cada tipo de hook retorna o caminho.
2666 3177
2667Este exemplo cria uma cópia de trabalho SVN e imprime o caminho para Claude Code usar. Substitua a URL do repositório pela sua:3178Claude Code atua no sucesso do hook e no caminho retornado, e descarta `systemMessage` e `continue`.
3179
3180Este 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:
2668 3181
2669```json theme={null}3182```json theme={null}
2670{3183{
2683}3196}
2684```3197```
2685 3198
2686O hook lê o `name` do worktree da entrada JSON em stdin, verifica 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 do worktree. Redirecione qualquer outra saída para stderr para que não interfira com o caminho.3199O 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.
2687 3200
2688<h4 id="worktreecreate-input">3201<h4 id="worktreecreate-input">
2689 Entrada de WorktreeCreate3202 Entrada WorktreeCreate
2690</h4>3203</h4>
2691 3204
2692Além dos [campos de entrada comuns](#common-input-fields), hooks WorktreeCreate recebem o campo `name`. Este é um identificador slug para o novo worktree, especificado pelo usuário ou auto-gerado, por exemplo `bold-oak-a3f2`.3205Além dos [campos de entrada comuns](#common-input-fields), 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`.
2693 3206
2694```json theme={null}3207```json theme={null}
2695{3208{
2702```3215```
2703 3216
2704<h4 id="worktreecreate-output">3217<h4 id="worktreecreate-output">
2705 Saída de WorktreeCreate3218 Saída WorktreeCreate
2706</h4>3219</h4>
2707 3220
2708Hooks 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 worktree criado:3221Os 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:
3222
3223* **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.
3224* **Hooks HTTP** (`type: "http"`): retorne `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.
2709 3225
2710* **Hooks de comando** (`type: "command"`): imprimem o caminho como a última linha não-vazia de stdout. Claude Code remove códigos de escape ANSI antes de ler essa linha, então banners de inicialização de shell impressos antes de seu `echo` são ignorados. Redirecione qualquer outra saída de hook para stderr.3226Se o hook falhar ou não produzir um caminho, a criação de worktree falha com um erro.
2711* **Hooks HTTP** (`type: "http"`): retornam `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` no corpo da resposta.
2712 3227
2713Se o hook falhar ou não produzir caminho, a criação de worktree falha com um erro.3228Claude 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.
2714 3229
2715Claude Code resolve um caminho relativo contra o diretório onde o hook executou. 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. Antes de v2.1.205, um caminho relativo ou um caminho que não existia no disco travava a sessão na inicialização, e com `-p` ela ficava parada por cerca de 30 segundos antes de sair com código 0.3230Claude 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.
2716 3231
2717<h3 id="worktreeremove">3232<h3 id="worktreeremove">
2718 WorktreeRemove3233 WorktreeRemove
2719</h3>3234</h3>
2720 3235
2721Executa quando um worktree está sendo removido, seja quando você sai de uma sessão `--worktree` e escolhe removê-lo, ou quando um subagente com `isolation: "worktree"` termina. Esta é a contraparte de limpeza para [WorktreeCreate](#worktreecreate).3236Executado quando uma worktree está sendo removida. Este é o equivalente de limpeza para [WorktreeCreate](#worktreecreate). O evento é disparado quando:
2722 3237
2723Para worktrees baseados em git, Claude Code lida com 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 lidar com limpeza. Sem um, o diretório worktree é deixado no disco.3238* você sai de uma sessão `--worktree` e escolhe removê-la
3239* um subagente com `isolation: "worktree"` termina
3240* você exclui uma [sessão em segundo plano](/docs/pt/agent-view#what-deleting-a-session-removes) cuja worktree o hook criou
2724 3241
2725Claude Code passa o caminho que WorktreeCreate retornou como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:3242Para 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.
3243
3244Claude Code descarta os [campos de saída JSON](#json-output) de um hook WorktreeRemove, como `systemMessage` e `continue`.
3245
3246Para 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](/docs/pt/agent-view#what-deleting-a-session-removes); para tal worktree, [`claude rm`](/docs/pt/agent-view#manage-sessions-from-the-shell) 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.
3247
3248Claude Code passa o caminho retornado por WorktreeCreate como `worktree_path` na entrada do hook. Este exemplo lê esse caminho e remove o diretório:
2726 3249
2727```json theme={null}3250```json theme={null}
2728{3251{
2742```3265```
2743 3266
2744<h4 id="worktreeremove-input">3267<h4 id="worktreeremove-input">
2745 Entrada de WorktreeRemove3268 Entrada WorktreeRemove
2746</h4>3269</h4>
2747 3270
2748Além dos [campos de entrada comuns](#common-input-fields), hooks WorktreeRemove recebem o campo `worktree_path`, que é o caminho absoluto para o worktree sendo removido.3271Além dos [campos de entrada comuns](#common-input-fields), os hooks WorktreeRemove recebem o campo `worktree_path`, que é o caminho absoluto para a worktree sendo removida.
2749 3272
2750```json theme={null}3273```json theme={null}
2751{3274{
2757}3280}
2758```3281```
2759 3282
2760Hooks WorktreeRemove não têm controle de decisão. Eles não podem bloquear remoção de worktree mas podem executar tarefas de limpeza como remover estado de controle de versão ou arquivar mudanças. Falhas de hook são registradas apenas em modo debug.3283O 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:
3284
3285* A worktree permanece no disco, e o comando do hook e stderr vão para o [log de depuração](#debug-hooks).
3286* Se você estava excluindo uma sessão em segundo plano, a sessão também permanece. A mensagem de recusa em [agent view](/docs/pt/agent-view#what-deleting-a-session-removes) 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.
2761 3287
2762<h3 id="precompact">3288<h3 id="precompact">
2763 PreCompact3289 PreCompact
2764</h3>3290</h3>
2765 3291
2766Executa antes do Claude Code estar prestes a executar uma operação de compactação.3292Executado antes de Claude Code estar prestes a executar uma operação de compactação.
2767 3293
2768O valor do matcher indica se a compactação foi acionada manualmente ou automaticamente:3294O valor do matcher indica se a compactação foi disparada manualmente ou automaticamente:
2769 3295
2770| Matcher | Quando dispara |3296| Matcher | Quando é disparado |
2771| :------- | :------------------------------------------------------ |3297| :------- | :--------------------------------------------------------------------------------------------------------------------------------- |
2772| `manual` | `/compact` |3298| `manual` | `/compact` |
2773| `auto` | Auto-compactação quando a janela de contexto está cheia |3299| `auto` | Compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |
2774 3300
2775Saia com código 2 para bloquear compactação. Para um `/compact` manual, a mensagem de stderr é mostrada ao usuário. Você também pode bloquear retornando JSON com `"decision": "block"`.3301Saia 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"`.
2776 3302
2777Bloquear compactação automática tem efeitos diferentes dependendo de quando dispara. Se a compactação foi acionada proativamente antes do limite de contexto, Claude Code a ignora e a conversa continua não compactada. Se a compactação foi acionada para recuperar de um erro de limite de contexto já retornado pela API, o erro subjacente superficializa e a solicitação atual falha.3303Bloquear 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.
3304
3305Claude Code descarta os campos `systemMessage` e `continue` de um hook PreCompact.
2778 3306
2779<h4 id="precompact-input">3307<h4 id="precompact-input">
2780 Entrada de PreCompact3308 Entrada PreCompact
2781</h4>3309</h4>
2782 3310
2783Além dos [campos de entrada comuns](#common-input-fields), hooks PreCompact recebem `trigger` e `custom_instructions`. Para `manual`, `custom_instructions` contém o que o usuário passa para `/compact`. Para `auto`, `custom_instructions` está vazio.3311Além dos [campos de entrada comuns](#common-input-fields), 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`.
2784 3312
2785```json theme={null}3313```json theme={null}
2786{3314{
2789 "cwd": "/Users/...",3317 "cwd": "/Users/...",
2790 "hook_event_name": "PreCompact",3318 "hook_event_name": "PreCompact",
2791 "trigger": "manual",3319 "trigger": "manual",
2792 "custom_instructions": ""3320 "custom_instructions": null
2793}3321}
2794```3322```
2795 3323
2797 PostCompact3325 PostCompact
2798</h3>3326</h3>
2799 3327
2800Executa 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.3328Executado 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.
2801 3329
2802Os mesmos valores de matcher se aplicam como para `PreCompact`:3330Os mesmos valores de matcher se aplicam como para `PreCompact`:
2803 3331
2804| Matcher | Quando dispara |3332| Matcher | Quando é disparado |
2805| :------- | :----------------------------------------------------------- |3333| :------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
2806| `manual` | Após `/compact` |3334| `manual` | Após `/compact` |
2807| `auto` | Após auto-compactação quando a janela de contexto está cheia |3335| `auto` | Após compactação automática quando a conversa atinge a [janela de compactação automática](/docs/pt/model-config#set-the-auto-compact-window) |
2808 3336
2809<h4 id="postcompact-input">3337<h4 id="postcompact-input">
2810 Entrada de PostCompact3338 Entrada PostCompact
2811</h4>3339</h4>
2812 3340
2813Além dos [campos de entrada comuns](#common-input-fields), hooks PostCompact recebem `trigger` e `compact_summary`. O campo `compact_summary` contém o resumo de conversa gerado pela operação de compactação.3341Além dos [campos de entrada comuns](#common-input-fields), 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.
2814 3342
2815```json theme={null}3343```json theme={null}
2816{3344{
2823}3351}
2824```3352```
2825 3353
2826Hooks PostCompact não têm controle de decisão. Eles não podem afetar o resultado de compactação mas podem executar tarefas de acompanhamento.3354Os 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.
3355
3356<h3 id="premodelswitch">
3357 PreModelSwitch
3358</h3>
3359
3360Executado 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.
3361
3362PreModelSwitch requer Claude Code v2.1.251 ou posterior. Claude Code o executa para essas solicitações:
3363
3364* `/model <name>` e o seletor `/model`
3365* O seletor de modelo `Option+P` ou `Alt+P`
3366* A configuração Model em `/config`
3367* Ativar [modo rápido](/docs/pt/fast-mode) quando isso muda o modelo da sessão
3368* Uma solicitação `set_model`, ou uma mudança de modelo em uma solicitação `apply_flag_settings`, de um host [Agent SDK](/docs/pt/agent-sdk/typescript#query-object) ou [Remote Control](/docs/pt/remote-control)
3369
3370Claude Code não executa hooks PreModelSwitch para mudanças que faz por conta própria, como um [fallback de modelo automático](/docs/pt/model-config#automatic-model-fallback) ou restaurar o modelo quando você retoma uma sessão. Essas mudanças chegam apenas a [PostModelSwitch](#postmodelswitch).
3371
3372Claude 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.
3373
3374Quando 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](/docs/pt/llm-gateway) 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.
3375
3376Escreva 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:
3377
3378<Tabs>
3379 <Tab title="macOS/Linux">
3380 O comando verifica `to_model` com `jq`:
3381
3382 ```json theme={null}
3383 {
3384 "hooks": {
3385 "PreModelSwitch": [
3386 {
3387 "matcher": "claude-opus-4-6",
3388 "hooks": [
3389 {
3390 "type": "command",
3391 "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"
3392 }
3393 ]
3394 }
3395 ]
3396 }
3397 }
3398 ```
3399 </Tab>
3400
3401 <Tab title="Windows (PowerShell)">
3402 Registre um hook de comando que executa um script através do PowerShell:
3403
3404 ```json theme={null}
3405 {
3406 "hooks": {
3407 "PreModelSwitch": [
3408 {
3409 "matcher": "claude-opus-4-6",
3410 "hooks": [
3411 {
3412 "type": "command",
3413 "command": "powershell.exe",
3414 "args": [
3415 "-NoProfile",
3416 "-ExecutionPolicy",
3417 "Bypass",
3418 "-File",
3419 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
3420 ]
3421 }
3422 ]
3423 }
3424 ]
3425 }
3426 }
3427 ```
3428
3429 Salve este script em `.claude/hooks/block-opus-46.ps1` em seu projeto:
3430
3431 ```powershell theme={null}
3432 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3433 if ($hookInput.to_model -match 'opus-4-6') {
3434 [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
3435 exit 2
3436 }
3437 exit 0
3438 ```
3439 </Tab>
3440</Tabs>
3441
3442Para 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.
3443
3444<h4 id="premodelswitch-input">
3445 Entrada PreModelSwitch
3446</h4>
3447
3448Além dos [campos de entrada comuns](#common-input-fields), 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.
3449
3450| Campo | Tipo | Descrição |
3451| :-------------------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3452| `from_model` | string | ID de modelo da mudança de |
3453| `to_model` | string | ID de modelo da mudança para. O matcher compara contra o nome canônico deste modelo |
3454| `requested_model` | string ou `null` | O modelo que a solicitação nomeou: um alias como `opus`, um ID de modelo completo, ou `null` quando a solicitação foi para o modelo padrão |
3455| `source` | string | De onde a solicitação veio: `"command"` para `/model <name>`, a configuração Model em `/config` ou ativar modo rápido; `"picker"` para um seletor de modelo; `"sdk"` para 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 |
3456| `context_tokens` | number | Tokens que a próxima solicitação reenvia como seu prompt: os tokens de entrada, leitura de cache, criação de cache e saída da última resposta na conversa principal, combinados. `0` antes da primeira resposta |
3457| `prompt_cache_warm` | boolean | Se o cache de prompt do modelo atual provavelmente ainda está quente, significando que a mudança o perde |
3458| `cache_ttl` | string | [Tempo de vida do cache de prompt](/docs/pt/prompt-caching#cache-lifetime) que Claude Code solicita para esta sessão: `"5m"` ou `"1h"` |
3459| `estimated_cache_write_usd` | number | Custo estimado em dólares americanos de escrever `context_tokens` no cache de prompt em `to_model` na taxa `cache_ttl`, excluindo a próxima resposta. O servidor pode não precisar re-cachear todo o contexto, portanto trate como uma estimativa |
3460| `pricing` | string | Como Claude Code precificou `estimated_cache_write_usd`: `"configured"` em suas próprias taxas quando sua organização as configurou, `"catalog"` ao preço de lista, ou `"default"` quando `to_model` não tem preço conhecido e Claude Code assumiu uma taxa padrão |
3461
3462Este exemplo mostra a entrada para `/model opus` em uma sessão executando Sonnet 5:
3463
3464```json theme={null}
3465{
3466 "session_id": "abc123",
3467 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
3468 "cwd": "/Users/...",
3469 "hook_event_name": "PreModelSwitch",
3470 "from_model": "claude-sonnet-5",
3471 "to_model": "claude-opus-5",
3472 "requested_model": "opus",
3473 "source": "command",
3474 "context_tokens": 182340,
3475 "prompt_cache_warm": true,
3476 "cache_ttl": "5m",
3477 "estimated_cache_write_usd": 1.1396,
3478 "pricing": "catalog"
3479}
3480```
3481
3482<h4 id="premodelswitch-decision-control">
3483 Controle de decisão PreModelSwitch
3484</h4>
3485
3486Os 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.
3487
3488Para controle mais fino, retorne `permissionDecision` e `permissionDecisionReason` em um objeto `hookSpecificOutput`, como em [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` aceita `"allow"`, `"deny"` e `"ask"`. Não aceita `"defer"`, `updatedInput` ou `additionalContext`. A tabela abaixo descreve ambos os campos:
3489
3490| Campo | Descrição |
3491| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3492| `permissionDecision` | `"allow"` prossegue e pula a [confirmação que Claude Code mostra enquanto o cache de prompt está quente](/docs/pt/prompt-caching#switching-models). `"deny"` cancela a mudança. `"ask"` solicita ao usuário para confirmá-la |
3493| `permissionDecisionReason` | Para `"deny"`, mostrado ao usuário como o motivo pelo qual a mudança foi bloqueada, ou retornado como o erro para uma solicitação `set_model`. Para `"ask"`, mostrado no prompt de confirmação. Ignorado para `"allow"` |
3494
3495Apenas `/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.
3496
3497Este exemplo pede ao usuário para confirmar e cita a contagem de tokens de `context_tokens`:
3498
3499```json theme={null}
3500{
3501 "hookSpecificOutput": {
3502 "hookEventName": "PreModelSwitch",
3503 "permissionDecision": "ask",
3504 "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
3505 }
3506}
3507```
3508
3509Quando vários hooks PreModelSwitch retornam decisões diferentes, a precedência é `deny` > `ask` > `allow`.
3510
3511Claude 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.
3512
3513Um hook PreModelSwitch que não responde antes de seu tempo limite bloqueia a mudança. Em [PreToolUse](#timeouts), 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.
3514
3515Um 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](#other-exit-codes).
3516
3517<h3 id="postmodelswitch">
3518 PostModelSwitch
3519</h3>
3520
3521Executado 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.
3522
3523PostModelSwitch 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:
3524
3525* Uma mudança que você ou um cliente solicitou
3526* Um [fallback de modelo automático](/docs/pt/model-config#automatic-model-fallback), que muda o modelo da sessão
3527* Uma configuração como [`opusplan`](/docs/pt/model-config#opusplan-model-setting) entrando ou saindo do modo de plano
3528* Claude Code restaurando o modelo quando você retoma uma sessão
3529
3530Claude Code não executa hooks PostModelSwitch quando um modelo de uma [cadeia de modelo fallback](/docs/pt/model-config#fallback-model-chains) serve um turno, porque essa substituição dura um turno e deixa o modelo da sessão inalterado.
3531
3532O matcher segue as mesmas regras que [PreModelSwitch](#premodelswitch): Claude Code compara contra o nome canônico do modelo para o qual a sessão mudou.
3533
3534Este exemplo adiciona orientação sempre que o modelo da sessão muda para qualquer modelo Opus:
3535
3536```json theme={null}
3537{
3538 "hooks": {
3539 "PostModelSwitch": [
3540 {
3541 "matcher": ".*opus.*",
3542 "hooks": [
3543 {
3544 "type": "command",
3545 "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
3546 }
3547 ]
3548 }
3549 ]
3550 }
3551}
3552```
3553
3554Para 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.
3555
3556<h4 id="postmodelswitch-input">
3557 Entrada PostModelSwitch
3558</h4>
3559
3560Os hooks PostModelSwitch recebem os mesmos campos que [PreModelSwitch](#premodelswitch-input), 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.
3561
3562`requested_model` é `null` quando `source` é `"auto"`. Quando `source` é `"resume"`, é a configuração de modelo salva que Claude Code restaurou.
3563
3564<h4 id="postmodelswitch-decision-control">
3565 Controle de decisão PostModelSwitch
3566</h4>
3567
3568Claude Code pega seu stdout de [texto simples](#exit-code-0) 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](#json-output) disponíveis para todos os hooks, você pode retornar:
3569
3570| Campo | Descrição |
3571| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------- |
3572| `additionalContext` | String adicionada ao contexto do Claude com a próxima solicitação. Veja [Adicionar contexto para Claude](#add-context-for-claude) |
3573
3574Se 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.
2827 3575
2828<h3 id="sessionend">3576<h3 id="sessionend">
2829 SessionEnd3577 SessionEnd
2830</h3>3578</h3>
2831 3579
2832Executa quando uma sessão do Claude Code termina. Útil para tarefas de limpeza, logging de estatísticas de sessão ou salvamento de estado de sessão. Suporta matchers para filtrar por razão de saída.3580Executado 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.
2833 3581
2834O campo `reason` na entrada do hook indica por que a sessão terminou:3582O campo `reason` na entrada do hook indica por que a sessão terminou:
2835 3583
2836| Razão | Descrição |3584| Motivo | Descrição |
2837| :---------------------------- | :----------------------------------------------------- |3585| :---------------------------- | :------------------------------------------------------------------------------------ |
2838| `clear` | Sessão limpa com comando `/clear` |3586| `clear` | Sessão limpa com comando `/clear` |
2839| `resume` | Sessão alternada via `/resume` interativo |3587| `resume` | Sessão mudada via `/resume` interativo |
2840| `logout` | Usuário fez logout |3588| `logout` | Usuário fez logout |
2841| `prompt_input_exit` | Usuário saiu enquanto entrada de prompt estava visível |3589| `prompt_input_exit` | Usuário saiu enquanto entrada de prompt estava visível |
2842| `bypass_permissions_disabled` | Modo de permissões de bypass foi desabilitado |3590| `other` | Outros motivos de saída |
2843| `other` | Outras razões de saída |3591| `bypass_permissions_disabled` | Removido na v2.1.234; Claude Code não o envia. Remova-o de seus matchers `SessionEnd` |
2844 3592
2845<h4 id="sessionend-input">3593<h4 id="sessionend-input">
2846 Entrada de SessionEnd3594 Entrada SessionEnd
2847</h4>3595</h4>
2848 3596
2849Além dos [campos de entrada comuns](#common-input-fields), hooks SessionEnd recebem um campo `reason` indicando por que a sessão terminou. Consulte a tabela de razão acima para todos os valores.3597Além dos [campos de entrada comuns](#common-input-fields), os hooks SessionEnd recebem um campo `reason` indicando por que a sessão terminou. Veja a [tabela de motivos](#sessionend) acima para todos os valores.
2850 3598
2851```json theme={null}3599```json theme={null}
2852{3600{
2858}3606}
2859```3607```
2860 3608
2861Hooks SessionEnd não têm controle de decisão. Eles não podem bloquear terminação de sessão mas podem executar tarefas de limpeza.3609Os 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](#json-output), como `systemMessage`.
3610
3611Os 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:
2862 3612
2863Hooks SessionEnd têm um timeout padrão de 1,5 segundos. Isso se aplica tanto à saída de sessão quanto a `/clear` e alternância de sessões via `/resume` interativo. Se um hook precisa de mais tempo, defina um `timeout` por hook na configuração do hook. O orçamento geral é automaticamente aumentado para o timeout por hook mais alto configurado em arquivos de configurações, até 60 segundos. Timeouts definidos em hooks fornecidos por plugin não aumentam o orçamento. Para sobrescrever o orçamento explicitamente, defina a variável de ambiente `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` em milissegundos.3613* **`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.
3614* **`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`.
3615
3616Este exemplo define o orçamento para 5 segundos:
2864 3617
2865```bash theme={null}3618```bash theme={null}
2866CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3619CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
2867```3620```
2868 3621
3622Antes 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.
3623
2869<h3 id="elicitation">3624<h3 id="elicitation">
2870 Elicitation3625 Elicitation
2871</h3>3626</h3>
2872 3627
2873Executa quando um servidor MCP solicita entrada do usuário no meio da tarefa. Por padrão, Claude Code mostra um diálogo interativo para o usuário responder. Hooks podem interceptar esta solicitação e responder programaticamente, pulando o diálogo inteiramente.3628Executado 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.
2874 3629
2875O campo matcher corresponde ao nome do servidor MCP.3630O campo matcher corresponde ao nome do servidor MCP.
2876 3631
2877<h4 id="elicitation-input">3632<h4 id="elicitation-input">
2878 Entrada de Elicitation3633 Entrada Elicitation
2879</h4>3634</h4>
2880 3635
2881Além dos [campos de entrada comuns](#common-input-fields), hooks Elicitation recebem `mcp_server_name`, `message` e campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.3636Além dos [campos de entrada comuns](#common-input-fields), os hooks Elicitation recebem `mcp_server_name`, `message` e campos opcionais `mode`, `url`, `elicitation_id` e `requested_schema`.
2882 3637
2883Para elicitação em modo de formulário (o caso mais comum):3638Para elicitação de modo de formulário, o caso mais comum:
2884 3639
2885```json theme={null}3640```json theme={null}
2886{3641{
2887 "session_id": "abc123",3642 "session_id": "abc123",
2888 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3643 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2889 "cwd": "/Users/...",3644 "cwd": "/Users/...",
2890 "permission_mode": "default",
2891 "hook_event_name": "Elicitation",3645 "hook_event_name": "Elicitation",
2892 "mcp_server_name": "my-mcp-server",3646 "mcp_server_name": "my-mcp-server",
2893 "message": "Please provide your credentials",3647 "message": "Please provide your credentials",
2901}3655}
2902```3656```
2903 3657
2904Para elicitação em modo URL (autenticação baseada em navegador):3658Para elicitação de modo URL, usada para autenticação baseada em navegador:
2905 3659
2906```json theme={null}3660```json theme={null}
2907{3661{
2908 "session_id": "abc123",3662 "session_id": "abc123",
2909 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3663 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2910 "cwd": "/Users/...",3664 "cwd": "/Users/...",
2911 "permission_mode": "default",
2912 "hook_event_name": "Elicitation",3665 "hook_event_name": "Elicitation",
2913 "mcp_server_name": "my-mcp-server",3666 "mcp_server_name": "my-mcp-server",
2914 "message": "Please authenticate",3667 "message": "Please authenticate",
2918```3671```
2919 3672
2920<h4 id="elicitation-output">3673<h4 id="elicitation-output">
2921 Saída de Elicitation3674 Saída Elicitation
2922</h4>3675</h4>
2923 3676
2924Para responder programaticamente sem mostrar o diálogo, retorne um objeto JSON com `hookSpecificOutput`:3677Para responder programaticamente sem mostrar o diálogo, retorne um objeto JSON com `hookSpecificOutput`:
2936```3689```
2937 3690
2938| Campo | Valores | Descrição |3691| Campo | Valores | Descrição |
2939| :-------- | :---------------------------- | :--------------------------------------------------------------------------------- |3692| :-------- | :---------------------------- | :------------------------------------------------------------------------------- |
2940| `action` | `accept`, `decline`, `cancel` | Se deve aceitar, recusar ou cancelar a solicitação |3693| `action` | `accept`, `decline`, `cancel` | Se deve aceitar, recusar ou cancelar a solicitação |
2941| `content` | object | Valores de campo de formulário a submeter. Apenas usado quando `action` é `accept` |3694| `content` | object | Valores de campo de formulário a enviar. Usado apenas quando `action` é `accept` |
3695
3696Código de saída 2 nega a elicitação. Claude Code não mostra sua mensagem stderr em lugar nenhum.
2942 3697
2943Código de saída 2 nega a elicitação e mostra stderr ao usuário.3698Claude Code atua em `hookSpecificOutput` da saída JSON de um hook Elicitation e descarta `systemMessage` e `continue`.
2944 3699
2945<h3 id="elicitationresult">3700<h3 id="elicitationresult">
2946 ElicitationResult3701 ElicitationResult
2947</h3>3702</h3>
2948 3703
2949Executa após um usuário responder a uma elicitação MCP. Hooks podem observar, modificar ou bloquear a resposta antes de ser enviada de volta ao servidor MCP.3704Executado 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.
2950 3705
2951O campo matcher corresponde ao nome do servidor MCP.3706O campo matcher corresponde ao nome do servidor MCP.
2952 3707
2953<h4 id="elicitationresult-input">3708<h4 id="elicitationresult-input">
2954 Entrada de ElicitationResult3709 Entrada ElicitationResult
2955</h4>3710</h4>
2956 3711
2957Além dos [campos de entrada comuns](#common-input-fields), hooks ElicitationResult recebem `mcp_server_name`, `action` e campos opcionais `mode`, `elicitation_id` e `content`.3712Além dos [campos de entrada comuns](#common-input-fields), os hooks ElicitationResult recebem `mcp_server_name`, `action` e campos opcionais `mode`, `elicitation_id` e `content`.
2958 3713
2959```json theme={null}3714```json theme={null}
2960{3715{
2961 "session_id": "abc123",3716 "session_id": "abc123",
2962 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3717 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2963 "cwd": "/Users/...",3718 "cwd": "/Users/...",
2964 "permission_mode": "default",
2965 "hook_event_name": "ElicitationResult",3719 "hook_event_name": "ElicitationResult",
2966 "mcp_server_name": "my-mcp-server",3720 "mcp_server_name": "my-mcp-server",
2967 "action": "accept",3721 "action": "accept",
2972```3726```
2973 3727
2974<h4 id="elicitationresult-output">3728<h4 id="elicitationresult-output">
2975 Saída de ElicitationResult3729 Saída ElicitationResult
2976</h4>3730</h4>
2977 3731
2978Para sobrescrever a resposta do usuário, retorne um objeto JSON com `hookSpecificOutput`:3732Para sobrescrever a resposta do usuário, retorne um objeto JSON com `hookSpecificOutput`:
2990| Campo | Valores | Descrição |3744| Campo | Valores | Descrição |
2991| :-------- | :---------------------------- | :------------------------------------------------------------------------------------------ |3745| :-------- | :---------------------------- | :------------------------------------------------------------------------------------------ |
2992| `action` | `accept`, `decline`, `cancel` | Sobrescreve a ação do usuário |3746| `action` | `accept`, `decline`, `cancel` | Sobrescreve a ação do usuário |
2993| `content` | object | Sobrescreve valores de campo de formulário. Apenas significativo quando `action` é `accept` |3747| `content` | object | Sobrescreve valores de campo de formulário. Significativo apenas quando `action` é `accept` |
3748
3749Có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.
2994 3750
2995Código de saída 2 bloqueia a resposta, mudando a ação efetiva para `decline`.3751Claude Code atua em `hookSpecificOutput` da saída JSON de um hook ElicitationResult e descarta `systemMessage` e `continue`.
2996 3752
2997<h2 id="prompt-based-hooks">3753<h2 id="prompt-based-hooks">
2998 Hooks baseados em prompt3754 Hooks baseados em prompt
3020 3776
3021* `ConfigChange`3777* `ConfigChange`
3022* `CwdChanged`3778* `CwdChanged`
3779* `DirectoryAdded`
3023* `Elicitation`3780* `Elicitation`
3024* `ElicitationResult`3781* `ElicitationResult`
3025* `FileChanged`3782* `FileChanged`
3026* `InstructionsLoaded`3783* `InstructionsLoaded`
3784* `MessageDisplay`
3027* `Notification`3785* `Notification`
3028* `PostCompact`3786* `PostCompact`
3787* `PostModelSwitch`
3029* `PreCompact`3788* `PreCompact`
3789* `PreModelSwitch`
3030* `SessionEnd`3790* `SessionEnd`
3031* `StopFailure`3791* `StopFailure`
3032* `SubagentStart`3792* `SubagentStart`
3033* `WorktreeCreate`3793* `WorktreeCreate`
3034* `WorktreeRemove`3794* `WorktreeRemove`
3035 3795
3036`SessionStart` e `Setup` suportam hooks `command` e `mcp_tool`. Eles não suportam hooks `http`, `prompt` ou `agent`.3796`SessionStart` e `Setup` suportam hooks `command` e `mcp_tool`, e [MCP tool hook fields](#mcp-tool-hook-fields) descreve quando seus hooks `mcp_tool` são executados. Eles não suportam hooks `http`, `prompt` ou `agent`.
3037 3797
3038<h3 id="how-prompt-based-hooks-work">3798<h3 id="how-prompt-based-hooks-work">
3039 Como hooks baseados em prompt funcionam3799 Como hooks baseados em prompt funcionam
3049 Configuração de hook de prompt3809 Configuração de hook de prompt
3050</h3>3810</h3>
3051 3811
3052Defina `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. Claude Code envia o prompt combinado e entrada para um modelo Claude rápido, que retorna uma decisão JSON.3812Defina `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.
3053 3813
3054Este hook `Stop` pede ao LLM para avaliar se todas as tarefas estão completas antes de permitir que Claude termine:3814Este hook `Stop` pede ao LLM para avaliar se todas as tarefas estão completas antes de permitir que Claude termine:
3055 3815
3071```3831```
3072 3832
3073| Campo | Obrigatório | Descrição |3833| Campo | Obrigatório | Descrição |
3074| :---------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3834| :---------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3075| `type` | sim | Deve ser `"prompt"` |3835| `type` | sim | Deve ser `"prompt"` |
3076| `prompt` | sim | O texto do prompt a enviar para o LLM. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook. Se `$ARGUMENTS` não estiver presente, entrada JSON é anexada ao prompt |3836| `prompt` | sim | O texto do prompt a enviar para o LLM. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook. Se `$ARGUMENTS` não estiver presente, entrada JSON é anexada ao prompt |
3077| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |3837| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |
3078| `timeout` | não | Timeout em segundos. Padrão: 30 |3838| `timeout` | não | Timeout em segundos. Padrão: 30 |
3079| `continueOnBlock` | não | Quando o prompt retorna `ok: false`, alimenta a razão de volta para Claude e continua o turno em vez de parar. Padrão: `false`. Implementado como `continue: true` na `decision: "block"` resultante. Veja [Esquema de resposta](#response-schema) para comportamento por evento |3839| `continueOnBlock` | não | Nos eventos aos quais se aplica, `true` alimenta uma razão `ok: false` de volta para Claude e continua em vez de terminar o turno. Padrão: `false`. Veja [Esquema de resposta](#response-schema) para comportamento por evento |
3080 3840
3081<h3 id="response-schema">3841<h3 id="response-schema">
3082 Esquema de resposta3842 Esquema de resposta
3087```json theme={null}3847```json theme={null}
3088{3848{
3089 "ok": true | false,3849 "ok": true | false,
3090 "reason": "Explanation for the decision"3850 "reason": "Explanation for the decision",
3851 "impossible": true | false
3091}3852}
3092```3853```
3093 3854
3094| Campo | Descrição |3855| Campo | Descrição |
3095| :------- | :--------------------------------------------------------------------------------------------------- |3856| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3096| `ok` | `true` para permitir. `false` produz uma `decision: "block"`. Veja o comportamento por evento abaixo |3857| `ok` | `true` para permitir. Para `false`, veja o comportamento por evento abaixo |
3097| `reason` | Obrigatório quando `ok` é `false`. Usado como a razão do bloqueio |3858| `reason` | Obrigatório quando `ok` é `false` |
3859| `impossible` | Opcional. O modelo o retorna com `ok: false` quando julga que a condição nunca pode ser satisfeita. Em `Stop` e `SubagentStop`, Claude Code então permite que o turno termine em vez de alimentar a razão de volta. Hooks de agente e outros eventos o ignoram |
3098 3860
3099O que acontece em `ok: false` depende do evento:3861O que acontece em `ok: false` depende do evento:
3100 3862
3101* `Stop` e `SubagentStop`: a razão é alimentada de volta para Claude como sua próxima instrução e o turno continua3863* `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
3102* `PreToolUse`: a chamada de ferramenta é negada e a razão é retornada a Claude como o erro da ferramenta, equivalente a um hook de comando com `permissionDecision: "deny"`3864* `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
3103* `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 disso3865* `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
3104* `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`3866* `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`
3105* `PostToolUseFailure`, `TaskCreated` e `TaskCompleted`: a razão é retornada a Claude como um erro de ferramenta, similar a `PreToolUse`3867* `PostToolUseFailure` e `TaskCreated`: a razão é retornada para Claude como um erro de ferramenta e o turno continua, independentemente de `continueOnBlock`
3868* `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
3106* `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 disso3869* `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
3107* `PermissionRequest`: `ok: false` não tem efeito. Para negar uma aprovação de um hook, use um [hook de comando](#command-hook-fields) retornando `hookSpecificOutput.decision.behavior: "deny"`3870* `PermissionRequest`: `ok: false` não tem efeito. Para negar uma aprovação de um hook, use um [hook de comando](#command-hook-fields) retornando `hookSpecificOutput.decision.behavior: "deny"`
3108* `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](#command-hook-fields) para retornar `retry`3871* `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](#command-hook-fields) para retornar `retry`
3109 3872
3110Se você precisar de controle mais fino em qualquer evento, use um [hook de comando](#command-hook-fields) com os campos por evento descritos em [Controle de decisão](#decision-control).3873Se você precisar de controle mais fino em qualquer evento, use um [hook de comando](#command-hook-fields) com os campos por evento descritos em [Controle de decisão](#decision-control).
3111 3874
3113 Verificar múltiplas condições antes de parar3876 Verificar múltiplas condições antes de parar
3114</h3>3877</h3>
3115 3878
3116Este 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](/docs/pt/sub-agents) deve parar. Se `"ok"` for `false`, Claude continua trabalhando com a razão fornecida como sua próxima instrução:3879Este 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](/docs/pt/sub-agents) 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:
3117 3880
3118```json theme={null}3881```json theme={null}
3119{3882{
31521. Claude Code gera um subagente com seu prompt e a entrada JSON do hook39151. Claude Code gera um subagente com seu prompt e a entrada JSON do hook
31532. O subagente pode usar ferramentas como Read, Grep e Glob para investigar39162. O subagente pode usar ferramentas como Read, Grep e Glob para investigar
31543. Após até 50 turnos, o subagente retorna uma decisão estruturada `{ "ok": true/false }`39173. Após até 50 turnos, o subagente retorna uma decisão estruturada `{ "ok": true/false }`
31554. Claude Code processa a decisão da mesma forma que um hook de prompt39184. 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](#response-schema)
3156 3919
3157Hooks 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.3920Hooks 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.
3158 3921
3160 Configuração de hook de agente3923 Configuração de hook de agente
3161</h3>3924</h3>
3162 3925
3163Defina `type` para `"agent"` e forneça uma string `prompt`. Os campos de configuração são os mesmos que [hooks de prompt](#prompt-hook-configuration), com um timeout padrão mais longo:3926Defina `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](#prompt-hook-configuration), exceto que hooks de agente têm um timeout padrão mais longo de 60 segundos e nenhum campo `continueOnBlock`.
3164
3165| Campo | Obrigatório | Descrição |
3166| :-------- | :---------- | :------------------------------------------------------------------------------------------------ |
3167| `type` | sim | Deve ser `"agent"` |
3168| `prompt` | sim | Prompt descrevendo o que verificar. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook |
3169| `model` | não | Modelo a usar. Padrão para um modelo rápido |
3170| `timeout` | não | Timeout em segundos. Padrão: 60 |
3171 3927
3172O esquema de resposta é o mesmo que hooks de prompt: `{ "ok": true }` para permitir ou `{ "ok": false, "reason": "..." }` para bloquear.3928O 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`](#response-schema) no mesmo evento; hooks de agente não têm campo `continueOnBlock` e não suportam o campo `impossible` do hook de prompt.
3173 3929
3174Este hook `Stop` verifica que todos os testes unitários passam antes de permitir que Claude termine:3930Este hook `Stop` verifica que todos os testes unitários passam antes de permitir que Claude termine:
3175 3931
3203 3959
3204Adicione `"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"`.3960Adicione `"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"`.
3205 3961
3206Este hook executa um script de teste após cada chamada de ferramenta `Write`. Claude continua trabalhando imediatamente enquanto `run-tests.sh` executa por até 120 segundos. Quando o script termina, sua saída é entregue no próximo turno de conversa:3962Este 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:
3207 3963
3208```json theme={null}3964```json theme={null}
3209{3965{
3215 {3971 {
3216 "type": "command",3972 "type": "command",
3217 "command": "/path/to/run-tests.sh",3973 "command": "/path/to/run-tests.sh",
3218 "async": true,3974 "async": true
3219 "timeout": 120
3220 }3975 }
3221 ]3976 ]
3222 }3977 }
3225}3980}
3226```3981```
3227 3982
3228O campo `timeout` define o tempo máximo em segundos para o processo em background. Se não especificado, hooks assíncronos usam o mesmo padrão de 10 minutos que hooks síncronos.3983Uma 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`.
3984
3985Claude Code entrega resultados de um hook assíncrono apenas enquanto a sessão está em execução:
3986
3987* Em [modo não-interativo](/docs/pt/headless) com a flag `-p`, Claude Code mata qualquer hook assíncrono ainda em execução no teardown e o finaliza com resultado `cancelled`
3988* Se o trabalho do seu hook deve sobreviver a uma sessão `claude -p`, inicie um processo totalmente desacoplado a partir dele
3229 3989
3230<h3 id="how-async-hooks-execute">3990<h3 id="how-async-hooks-execute">
3231 Como hooks assíncronos executam3991 Como hooks assíncronos executam
3233 3993
3234Quando 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.3994Quando 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.
3235 3995
3236Após o processo em background sair, se o hook produziu uma resposta JSON com um campo `additionalContext`, esse conteúdo é entregue ao Claude como contexto no próximo turno de conversa. Um campo `systemMessage` é mostrado para você, não para Claude.3996Apó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ê.
3237 3997
3238Claude Code valida que a resposta JSON contra o mesmo [esquema de saída](#json-output) 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.3998Claude Code valida que a resposta JSON contra o mesmo [esquema de saída](#json-output) 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.
3239 3999
3283 "type": "command",4043 "type": "command",
3284 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",4044 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
3285 "args": [],4045 "args": [],
3286 "async": true,4046 "async": true
3287 "timeout": 300
3288 }4047 }
3289 ]4048 ]
3290 }4049 }
3297 Limitações4056 Limitações
3298</h3>4057</h3>
3299 4058
3300Hooks assíncronos têm várias restrições comparados a hooks síncronos:4059Hooks assíncronos têm restrições adicionais comparados a hooks síncronos:
3301 4060
3302* Apenas hooks `type: "command"` suportam `async`. Hooks baseados em prompt não podem executar assincronamente.
3303* Hooks assíncronos não podem bloquear chamadas de ferramenta ou retornar decisões. Pelo tempo que o hook completa, a ação acionadora já prosseguiu.
3304* 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.4061* 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.
3305* 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.4062* 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.
3306 4063
3312 Aviso4069 Aviso
3313</h3>4070</h3>
3314 4071
3315Hooks de comando executam com as permissões completas do seu usuário do sistema.
3316
3317<Warning>4072<Warning>
3318 Hooks de comando executam comandos shell com suas permissões completas de usuário. Eles podem modificar, deletar ou acessar qualquer arquivo que sua conta de usuário pode acessar. Revise e teste todos os comandos de hook antes de adicioná-los à sua configuração.4073 Hooks de comando executam comandos shell com suas permissões completas de usuário. Eles podem modificar, deletar ou acessar qualquer arquivo que sua conta de usuário pode acessar. Revise e teste todos os comandos de hook antes de adicioná-los à sua configuração.
3319</Warning>4074</Warning>
3320 4075
4076<h3 id="workspace-trust">
4077 Confiança do workspace
4078</h3>
4079
4080Claude 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:
4081
4082* **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](/docs/pt/permissions#project-allow-rules-and-workspace-trust) para a pasta, ou para um diretório pai cuja confiança se estende a ela
4083* **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
4084
4085Antes de executar `claude -p` em um repositório que você não escreveu, revise seus arquivos de configurações `.claude/`, comece com [`--bare`](/docs/pt/headless#start-faster-with-bare-mode), ou [desative hooks para essa execução](#disable-or-remove-hooks) 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](/docs/pt/permissions#what-runs-before-you-trust-a-folder) lista cada tipo de conteúdo de repositório por tipo de sessão.
4086
3321<h3 id="security-best-practices">4087<h3 id="security-best-practices">
3322 Melhores práticas de segurança4088 Melhores práticas de segurança
3323</h3>4089</h3>
3334 Ferramenta Windows PowerShell4100 Ferramenta Windows PowerShell
3335</h2>4101</h2>
3336 4102
3337No Windows, você pode executar hooks individuais em PowerShell definindo `"shell": "powershell"` em um hook de comando. Hooks geram PowerShell diretamente, então isso funciona independentemente de `CLAUDE_CODE_USE_POWERSHELL_TOOL` estar definido. Claude Code auto-detecta `pwsh.exe`, o executável do PowerShell 7 e posterior, e volta para `powershell.exe` para Windows PowerShell 5.1.4103No 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.
3338 4104
3339```json theme={null}4105```json theme={null}
3340{4106{
3375 Debug de hooks4141 Debug de hooks
3376</h2>4142</h2>
3377 4143
3378Detalhes de execução de hook, incluindo quais hooks corresponderam, seus códigos de saída e saída completa de stdout e stderr, 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.4144Detalhes 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.
4145
4146Por exemplo, um hook `PostToolUse` em `Write` cujo comando imprime `hook-ran` produz entradas como:
3379 4147
3380```text theme={null}4148```text theme={null}
3381[DEBUG] Executing hooks for PostToolUse:Write41492026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
3382[DEBUG] Found 1 hook commands to execute41502026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"
3383[DEBUG] Executing hook command: <Your command> with timeout 600000ms
3384[DEBUG] Hook command completed with status 0: <Your stdout>
3385```4151```
3386 4152
3387Para 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.4153Para 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.
