{"meta":{"title":"Referência de ganchos do GitHub Copilot","intro":"Encontre eventos de gancho, formatos de configuração e cargas de entrada para ganchos em Copilot CLI e Copilot cloud agent.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/pt/enterprise-cloud@latest/copilot/reference","title":"Referência"},{"href":"/pt/enterprise-cloud@latest/copilot/reference/hooks-reference","title":"Referência de ganchos"}],"documentType":"article"},"body":"# Referência de ganchos do GitHub Copilot\n\nEncontre eventos de gancho, formatos de configuração e cargas de entrada para ganchos em Copilot CLI e Copilot cloud agent.\n\n## Introdução\n\nGanchos são comandos externos que são executados em pontos de ciclo de vida específicos durante uma sessão, permitindo automação personalizada, controles de segurança e integrações.\n\nHá suporte para ganchos em duas Copilot superfícies: Copilot CLI e Copilot cloud agent. A maioria dos conteúdos de eventos e formato de configuração são idênticos, mas o ambiente de execução e o conjunto de eventos que podem ser disparados diferem.\n\nAo longo deste artigo, o comportamento que difere entre as duas superfícies é destacado nas observações \"Somente CLI\" e \"Somente agente de nuvem\". Qualquer coisa não marcada se aplica a ambos.\n\n## Localizações de ganchos\n\nOs locais em que os ganchos são executados e onde você pode armazenar arquivos de configuração de ganchos dependem da superfície:\n\n* **Copilot CLI** — os ganchos são executados no computador local do desenvolvedor no mesmo shell que a CLI. Todos os eventos de gancho descritos neste artigo têm suporte da CLI.\n\n Os ganchos são carregados das seguintes fontes na ordem (política, usuário, projeto e plug-ins) e combinados. Quando o mesmo evento aparece em várias fontes, todas as entradas de gancho de todas as fontes são executadas.\n\n * **Arquivos de hook em nível de política** — arquivos JSON no diretório de política adequado à plataforma, carregados em ordem alfabética. Os ganchos de política são válidos para todo o sistema e são carregados antes de quaisquer outros ganchos. Eles não podem ser desativados por `disableAllHooks` e estão disponíveis independentemente do estado de confiança da pasta. Veja [Policy hooks](#policy-hooks) abaixo.\n * **Arquivos de gancho no nível do repositório** — `.github/hooks/*.json` na raiz do repositório.\n * **Arquivos de gancho no nível do usuário** — arquivos `*.json` no diretório de ganchos no nível do usuário. Por padrão, isso é `~/.copilot/hooks/` no macOS e linux ou `%USERPROFILE%\\.copilot\\hooks\\` no Windows. Se `COPILOT_HOME` estiver definido, será `$COPILOT_HOME/hooks/`.\n * **Bloqueio `hooks` embutido nas configurações do repositório** — o campo `hooks` no nível superior de `.github/copilot/settings.json` (commit no Git) ou `.github/copilot/settings.local.json` (normalmente gitignored e específico do usuário) no repositório. Arquivos entre ferramentas `.claude/settings.json` e `.claude/settings.local.json` no repositório também são lidos.\n * **Bloqueio `hooks` embutido na configuração no nível do usuário** – o campo `hooks` no nível superior de `~/.copilot/settings.json`.\n * **Ganchos contribuídos por plug-ins instalados** — declarados por cada plug-in em seu próprio `hooks.json` (ou em `hooks/hooks.json`) dentro do diretório de instalação do plug-in.\n\n* **Copilot cloud agent** — ganchos são executados dentro da área restrita efêmera do Linux que o agente de nuvem provisiona para cada trabalho. O sandbox não é interativo, tem uma rede limitada e é destruído quando o trabalho termina. Um subconjunto de eventos é acionado e somente entradas `bash` (ou `command`) são respeitadas.\n\n A configuração do gancho é carregada a partir de arquivos `.github/hooks/*.json` no repositório clonado.\n\n### Ganchos de política\n\n> \\[!NOTE]\n> **Copilot CLI Só.** Não há suporte para ganchos de política em Copilot cloud agent.\n\nOs ganchos de política são ganchos válidos para todo o sistema, carregados pelos administradores. Eles são carregados antes de todos os outros hooks e não podem ser desativados por `disableAllHooks`.\n\nOs ganchos de política são descobertos de duas fontes:\n\n* **Sistema de arquivos**: arquivos JSON no diretório de política apropriado à plataforma, carregados em ordem alfabética:\n * Linux/macOS: `/etc/github-copilot/policy.d/*.json`\n * Windows: `C:\\ProgramData\\GitHub\\Copilot\\policy.d\\*.json`\n* **Windows Registry**: valores em `HKLM\\Software\\Policies\\GitHub\\Copilot` (cada subchave contém um valor `Policy` REG\\_SZ que contém um documento de política JSON).\n\nOs arquivos de gancho de política usam o mesmo formato de configuração de gancho que os ganchos de usuário e de projeto (`{ \"version\": 1, \"hooks\": { ... } }`). Em sistemas POSIX, os arquivos de política devem pertencer à raiz e não devem ter permissão de gravação para o grupo nem para outros.\n\nOs ganchos de política são destinados ao uso por administradores de TI corporativos e exigem privilégios elevados para instalação. Os usuários finais não podem modificá-los.\n\n## Ambiente de execução do agente de nuvem\n\nEsta seção se aplica somente a**Copilot cloud agent**. Descreve restrições que afetam a forma como você escreve scripts de gancho e configura entradas de gancho para trabalhos do agente de nuvem.\n\n| Property | Value |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Sistema operacional | Linux. Somente o `bash` campo nos ganchos de comando é reconhecido; `powershell` as entradas são ignoradas. O campo multiplataforma `command` é respeitado como um recurso alternativo. |\n| Diretório de trabalho | |\n| `/workspace` quando um repositório é clonado, caso contrário `/root`. Use esse caminho ao definir `cwd` em uma entrada de gancho ou ao referenciar arquivos de um script. | |\n| Filesystem | Efêmero. Arquivos escritos por hooks (logs, CSVs, transcrições) são descartados quando o trabalho termina. Para manter a saída do gancho, envie-a por meio de uma entrada de gancho `http`. |\n| Rede de saída | Restrito pelo firewall do agente de nuvem. Por padrão, somente GitHub e Copilot nomes de host são acessíveis; alcançar qualquer outro host (por exemplo, `https://hooks.example.com`) requer uma regra de permissão de firewall configurada pelo administrador. |\n| Variáveis de ambiente disponíveis | |\n| `GITHUB_COPILOT_API_TOKEN` e `GITHUB_COPILOT_GIT_TOKEN` são definidos no sandbox. | |\n| `COPILOT_AGENT_PROMPT` mantém o prompt com o qual o trabalho foi invocado. | |\n| `HOME` é definido como `/root`, de modo que qualquer script de gancho que resolve caminhos `~/...` grave na área restrita efêmera. | |\n| `GITHUB_TOKEN` não está definido. | |\n| Interatividade | Totalmente não interativo. O agente é executado com todas as permissões de ferramenta pré-concedidas, portanto, nenhuma caixa de diálogo de permissão é mostrada e nenhuma notificação é exibida para um usuário. |\n| Descoberta de configuração | Em um trabalho do agente de nuvem, a única configuração de gancho que existe por padrão é `.github/hooks/*.json` dentro do repositório clonado. A área restrita não é enviada com arquivos de gancho no nível do usuário, `settings.json`, `config.json` ou plug-ins instalados. |\n\n## Formato de configuração do gancho\n\nOs arquivos de configuração do gancho usam o formato JSON com a versão `1`.\n\n> \\[!NOTE]\n> Se um arquivo de configuração de gancho carregado de um diretório (por exemplo, `.github/hooks/`) contiver um item de gancho malformado, somente esse item será descartado e registrado — ganchos irmãos válidos no mesmo arquivo ainda serão carregados. Erros estruturais (JSON inválido, um `version` inválido ou uma lista de eventos que não seja um array) ainda fazem com que o arquivo inteiro seja rejeitado. Os hooks definidos inline em `settings.json` permanecem estritos: qualquer erro de validação em nível de item rejeita todo o campo `hooks`. Outros arquivos de configuração sempre são carregados de forma independente.\n\n### Ganchos de comando\n\nOs ganchos de comando executam scripts de shell e têm suporte em todos os tipos de gancho.\n\n> \\[!NOTE]\n> **Somente agente de nuvem.** O agente de nuvem executa hooks em um sandbox do Linux. Somente o `bash` campo é honrado; `powershell` as entradas são ignoradas. O campo multiplataforma `command` é respeitado como um recurso alternativo.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"preToolUse\": [\n {\n \"type\": \"command\",\n \"bash\": \"YOUR_BASH_COMMAND\",\n \"powershell\": \"YOUR_POWERSHELL_COMMAND\",\n \"cwd\": \"OPTIONAL/WORKING/DIRECTORY\",\n \"env\": { \"VAR\": \"VALUE\" },\n \"timeoutSec\": 30\n }\n ]\n }\n}\n```\n\n| Field | Tipo | Obrigatório | Description |\n| ------------ | ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `bash` | cadeia | Uma opção entre `bash`, `powershell` ou `command` | Comando shell para Unix. |\n| `command` | cadeia | Uma opção entre `bash`, `powershell` ou `command` | Alternativa multiplataforma. Copiado para `bash` e `powershell` quando esses campos não estiverem presentes; entradas explícitas de `bash` ou `powershell` têm prioridade em suas respectivas plataformas. |\n| `cwd` | cadeia | Não | Diretório de trabalho para o comando (relativo à raiz do repositório ou absoluto). |\n| `env` | objeto | Não | Variáveis de ambiente a serem definidas (dá suporte à expansão variável). |\n| `powershell` | cadeia | Uma opção entre `bash`, `powershell` ou `command` | Comando shell para Windows. |\n| `timeout` | número | Não | Alias para `timeoutSec`, em segundos. Usado somente quando `timeoutSec` está ausente; `timeoutSec` tem precedência quando ambos estão presentes. |\n| `timeoutSec` | número | Não | Tempo limite em segundos. Padrão: `30`. |\n| `type` | `\"command\"` | Não | Tipo de gancho. Quando omitido, o padrão é `\"command\"`. |\n\n#### Mensagens de progresso\n\nOs ganchos de comando podem emitir linhas de status de progresso para a linha do tempo da CLI durante a execução. Escreva um `{\"type\": \"progress\", \"message\": \"...\"}` objeto JSON para stdout antes de gravar a saída final:\n\n```bash\necho '{\"type\": \"progress\", \"message\": \"Checking policy...\"}'\n# ... perform work ...\necho '{\"permissionDecision\": \"allow\"}'\n```\n\nDefina `\"temporary\": true` para emitir uma linha de status transitória. Uma linha transitória substitui a linha transitória anterior e é removida quando o assistente responde, em vez de se acumular na cronologia:\n\n```bash\necho '{\"type\": \"progress\", \"message\": \"Routing...\", \"temporary\": true}'\necho '{\"type\": \"progress\", \"message\": \"Thinking...\", \"temporary\": true}'\n# ... perform work ...\necho '{\"permissionDecision\": \"allow\"}'\n```\n\nAs mensagens de progresso são apenas para exibição e não afetam a saída do hook nem a lógica de decisão.\n\n**Como stdout é analisado quando as mensagens de progresso são misturadas.** — A CLI analisa a saída padrão (stdout) linha por linha enquanto o gancho é executado. Qualquer linha que, após o corte, seja um único objeto JSON completo com `\"type\": \"progress\"` é tratada como um evento de progresso e **removida do fluxo de saída do gancho**. Todas as outras linhas — linhas em branco, texto sem formatação e objetos JSON que não são mensagens de progresso — são preservadas verbatim. Quando o gancho é encerrado, as linhas preservadas são concatenadas, cortadas e analisadas com uma única chamada `JSON.parse`: esse resultado é a saída do gancho (o \"JSON de saída do gancho\" referenciado em outro lugar neste artigo). Isso significa que:\n\n* Emitir linhas de progresso ao lado de um objeto de decisão final (como nos exemplos acima) é seguro e é o padrão pretendido: as linhas de progresso nunca chegam ao analisador JSON.\n* Cada mensagem de progresso deve estar em sua própria linha e deve ser um JSON válido nessa única linha. Objetos de progresso multilinha ou formatados de forma legível não são reconhecidos como indicadores de progresso e permanecerão no fluxo de saída, onde provavelmente farão o `JSON.parse` final falhar.\n* O objeto final de decisão, por outro lado, pode se estender por várias linhas — somente o *reconhecimento* de progresso é baseado em linhas; o que resta após a remoção das informações de progresso é analisado como um único documento JSON, não como JSON delimitado por linhas.\n* Se a saída restante estiver vazia ou não puder ser interpretada como JSON, o hook será tratado como se não tivesse produzido nenhuma saída e seguirá o comportamento padrão. Dois ou mais objetos JSON no stdout que não sejam de progresso (por exemplo, duas chamadas `echo '{\"permissionDecision\": ...}'`) serão concatenados, resultando em JSON inválido, e serão ignorados — emita exatamente um objeto de decisão final.\n\n### Ganchos HTTP\n\nOs ganchos HTTP enviam o conteúdo de entrada como um JSON `POST` para uma URL.\n\n> \\[!NOTE]\n>\n> * Por padrão, somente `https://` URLs são permitidas. Solicitações não TLS `http://` são rejeitadas, exceto por `http://localhost`, `http://127.*`e `http://[::1]` quando `COPILOT_HOOK_ALLOW_LOCALHOST=1` é definida.\n> *\n\n**Somente agente de nuvem.** A rede de saída da sandbox é restringida pelo firewall do agente de nuvem, portanto `url` deve ser direcionada a um host na lista de permitidos.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"postToolUse\": [\n {\n \"type\": \"http\",\n \"url\": \"https://hooks.example.com/copilot\",\n \"headers\": { \"X-Source\": \"copilot-cli\" },\n \"allowedEnvVars\": [\"GITHUB_TOKEN\"],\n \"timeoutSec\": 30\n }\n ]\n }\n}\n```\n\n| Field | Tipo | Obrigatório | Description |\n| ---------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `allowedEnvVars` | string\\[] | Não | Nomes de variáveis de ambiente que podem ser expandidos dentro de valores `headers`. Quando definido, `url` deve usar `https://`. |\n| `headers` | objeto | Não | Solicitar cabeçalhos a serem incluídos. |\n| `timeout` | número | Não | Alias para `timeoutSec`, em segundos. Usado somente quando `timeoutSec` está ausente; `timeoutSec` tem precedência quando ambos estão presentes. |\n| `timeoutSec` | número | Não | Tempo limite em segundos. Padrão: `30`. |\n| `type` | `\"http\"` | Sim | Deve ser `\"http\"`. |\n| `url` | cadeia | Sim | URL de destino. Deve usar `http:` ou `https:`. Para `preToolUse` e `permissionRequest`, é necessário usar `https://` porque a resposta pode conceder permissões da ferramenta. |\n\n### Ganchos de prompt\n\nPrompt hooks enviam automaticamente o texto como se o usuário tivesse digitado. Eles só têm suporte em `sessionStart`. O texto pode ser uma solicitação em linguagem natural ou um comando de barra.\n\n> \\[!NOTE]\n> **Copilot CLI Só.** Ganchos de prompt são acionados apenas para **novas sessões interativas**. Eles não são acionados na retomada nem no modo de prompt não interativo (`-p`).\n\n> \\[!NOTE]\n> **Agente de nuvem.** Os trabalhos do agente de nuvem são executados de forma não interativa (semelhante a `-p`), portanto, as entradas de gancho `prompt` podem não ser acionadas. Confirme o comportamento em seu ambiente antes de confiar neles.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"sessionStart\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"YOUR_PROMPT_TEXT_OR_SLASH_COMMAND\"\n }\n ]\n }\n}\n```\n\n| Field | Tipo | Obrigatório | Description |\n| -------- | ---------- | ----------- | ---------------------------------------------------------------------------------------- |\n| `type` | `\"prompt\"` | Sim | Deve ser `\"prompt\"`. |\n| `prompt` | cadeia | Sim | O texto a ser enviado pode ser uma mensagem de linguagem natural ou um comando de barra. |\n\n## Eventos de gancho\n\nA tabela a seguir lista todos os eventos com suporte. A coluna **Agente de nuvem** mostra se o evento é acionado no agente de nuvem e observa as diferenças de comportamento.\n\n| Acontecimento | Acionado quando | A saída foi processada | Agente de nuvem |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `agentStop` | O agente principal conclui um turno. | Sim – pode bloquear e forçar a continuação. | Incêndios. |\n| `decision: \"block\"` força outra rodada, que ainda conta no tempo limite do trabalho. | | | |\n| `errorOccurred` | Ocorre um erro durante a execução. | Não | Incêndios. |\n| `notification` | É acionado de forma assíncrona quando a CLI emite uma notificação do sistema (conclusão do shell, conclusão do agente ou estado ocioso, prompts de permissão, caixas de diálogo para elicitação). Disparar e esquecer: nunca bloqueia a sessão. Oferece suporte a um padrão regex `matcher` (o valor do campo `matcher`) em `notification_type`. | Opcional – pode injetar `additionalContext` na sessão. | |\n| **Não é acionado.** O agente de nuvem não apresenta notificações a um usuário (consulte a linha **Interatividade** na tabela de ambiente de execução do agente de nuvem acima). | | | |\n| `permissionRequest` | É acionado antes que o serviço de permissão seja executado (mecanismo de regras, aprovações de sessão, permissão automática/negação automática e solicitação do usuário). Se a saída do hook mesclado retornar `behavior: \"allow\"` ou `\"deny\"`, essa decisão interrompe o fluxo normal de permissões — exceto no caso de uma solicitação de sandbox-bypass (`requestSandboxBypass: true`), em que um `allow` não pré-aprova a saída e apenas `deny` é propagado (consulte a exceção de sandbox-bypass no [controle de decisão `permissionRequest`](#permissionrequest-decision-control)). Oferece suporte a um padrão regex `matcher` (o valor do campo `matcher`) em `toolName`. | Sim – pode permitir ou negar programaticamente. | As chamadas de ferramenta são previamente aprovadas, portanto, este gancho não é acionado ou não tem efeito. Use `preToolUse` para tomar decisões de permissões em vez disso. |\n| `postToolUse` | Depois que cada ferramenta for executada com sucesso. | Sim — pode modificar o resultado da ferramenta ou injetar contexto adicional para o modelo. | Incêndios. |\n| `postToolUseFailure` | Depois que uma ferramenta termina com falha. | Sim – pode fornecer diretrizes de recuperação por meio de `additionalContext` (código de saída `2` para hooks de comando). | Incêndios. |\n| `preCompact` | A compactação de contexto está prestes a começar (manual ou automática). Dá suporte a um `matcher` padrão regex (o valor do `matcher` campo) para filtrar por gatilho (`\"manual\"` ou `\"auto\"`). | Não — somente notificação. | Acionado apenas com `trigger: \"auto\"`. Não existe usuário para solicitar a compactação manual. |\n| `preToolUse` | Antes de executar cada ferramenta. | Sim — pode permitir, negar ou modificar. | Incêndios. A decisão de `\"ask\"` é tratada como `\"deny\"` porque nenhum usuário está disponível para responder. |\n| `sessionEnd` | A sessão é encerrada. | Não | É acionado uma vez por trabalho. |\n| `reason` normalmente é `\"complete\"`, `\"error\"` ou `\"timeout\"`; `\"abort\"` e `\"user_exit\"` não são esperados porque não há usuário. | | | |\n| `sessionStart` | Uma sessão nova ou retomada começa. | Opcional – pode injetar `additionalContext` na sessão. | É acionado uma vez por trabalho, como uma nova sessão (não uma retomada). Consulte a observação Ganchos de prompt acima para ver o comportamento das entradas `prompt` no agente de nuvem. |\n| `subagentStart` | Um subagente é gerado (antes de ser executado). Oferece suporte a um padrão regex `matcher` (o valor do campo `matcher`) para filtrar pelo nome do agente. | Opcional – não pode bloquear a criação, mas `additionalContext` é acrescentado ao prompt do subagente. | Incêndios. |\n| `subagentStop` | Um subagente completa. | Sim – pode bloquear e forçar a continuação. | Incêndios. |\n| `userPromptSubmitted` | O usuário envia um prompt. | Opcional–`modifiedPrompt` é respeitado apenas por ganchos programáticos do SDK. | É acionado no máximo uma vez, para o prompt fornecido ao trabalho. Não há nenhuma entrada de usuário de acompanhamento. |\n| `userPromptTransformed` | É acionado após o runtime transformar um prompt enviado em seu conteúdo voltado para o modelo, pouco antes de esse conteúdo ser emitido e mantido no histórico de sessão. É executado para a mensagem primária e para cada mensagem anterior em um envio em lote. Apenas mutação — ele pode reescrever o conteúdo que o modelo recebe, mas não bloquear nem lidar com o turno. As notificações do sistema nunca acionam isso. | Sim — pode reescrever o conteúdo voltado para o modelo. | Incêndios. |\n\n## Cargas de entrada de evento do gancho\n\nCada evento de gancho fornece uma carga JSON para o manipulador de gancho. Há suporte para dois formatos de conteúdo, selecionados pelo nome do evento usado na configuração do gancho:\n\n* **formato camelCase** — Configure o nome do evento em camelCase (por exemplo, `sessionStart`). Os campos usam camelCase.\n* **VS Code Formato compatível** — configure o nome do evento em PascalCase (por exemplo, `SessionStart`). Os campos usam snake\\_case para corresponder ao formato de extensão VS CodeCopilot.\n\n### `sessionStart` / `SessionStart`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number; // Unix timestamp in milliseconds\n cwd: string;\n source: \"startup\" | \"resume\" | \"new\";\n initialPrompt?: string;\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"SessionStart\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n source: \"startup\" | \"resume\" | \"new\";\n initial_prompt?: string;\n}\n```\n\n### `sessionEnd` / `SessionEnd`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"SessionEnd\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n### `userPromptSubmitted` / `UserPromptSubmit`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n prompt: string;\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"UserPromptSubmit\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n prompt: string;\n}\n```\n\n**Saída:**\n\n```typescript\n{\n modifiedPrompt?: string; // Replaces the prompt for the rest of the turn (SDK programmatic hooks only)\n}\n```\n\nRetorne `{}` ou vazio para deixar o prompt inalterado.\n\n> \\[!NOTE]\n> \\*\n> `modifiedPrompt` é respeitado apenas por hooks programáticos do SDK. Os hooks de comando e de arquivo de configuração HTTP `userPromptSubmitted` têm sua saída descartada, incluindo `modifiedPrompt`. O runtime mais leve de processamento de hooks usado por sessões hospedadas ou com steering Copilot cloud agent também o ignora. Essa é a mesma divisão de runtime que `preToolUse`.\n>\n> * Um `modifiedPrompt`, `modifiedTransformedPrompt` ou um valor `responseContent` tratado que não seja string é ignorado em vez de corromper a sessão — um aviso de tipo com o nome do campo é registrado e emitido como um evento `session.warning`. Uma substituição de cadeia de caracteres vazia é rejeitada em vez de apagar o conteúdo voltado para o modelo. Um `null``additionalContext` valor é tratado como ausente em vez de ser injetado como o texto `null`literal. A saída do gancho (stdout para ganchos de comando, o corpo da resposta para ganchos HTTP) é limitada a 10 MiB por invocação— uma resposta maior é truncada em vez de esgotar a memória.\n\n### `userPromptTransformed`\n\nÉ acionado após o runtime transformar um prompt enviado em seu conteúdo voltado para o modelo, pouco antes de esse conteúdo ser emitido e mantido no histórico de sessão. É executado para a mensagem primária e para cada mensagem anterior em um envio em lote. Somente mutação – ele pode reescrever o conteúdo recebido pelo modelo, mas não bloquear ou manipular a curva. As notificações do sistema nunca acionam isso.\n\n**Entrada:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number; // epoch-ms integer\n cwd: string;\n prompt: string; // user prompt after userPromptSubmitted hooks have run\n transformedPrompt: string; // runtime-transformed content the model will receive\n}\n```\n\n**Saída:**\n\n```typescript\n{\n modifiedTransformedPrompt?: string; // Replaces the model-facing content\n}\n```\n\nRetorne `{}` ou vazio para deixar o conteúdo transformado inalterado.\n`modifiedTransformedPrompt` substitui apenas o conteúdo enviado para o modelo e armazenado no histórico de sessão — o prompt exibido na linha do tempo não é afetado — e a substituição é reproduzida inalterada se a sessão for retomada.\n\n### `preToolUse` / `PreToolUse`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\nQuando configurado com o nome do evento `PreToolUse` PascalCase, o conteúdo usa nomes de campo em snake\\_case para corresponder ao formato de extensão VS CodeCopilot.\n\n```typescript\n{\n hook_event_name: \"PreToolUse\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown; // Tool arguments (parsed from JSON string when possible)\n}\n```\n\n**Correspondentes no formato Claude (PascalCase `PreToolUse`):** ganchos configurados com o nome de evento em PascalCase `PreToolUse` — como usados nos plug-ins do Claude Code e no formato Open Plugins — aplicam a semântica de correspondência do Claude em vez da regra nativa de regex:\n\n* `*`, `**` ou um valor `matcher` vazio é acionado para cada ferramenta.\n* Um nome exato ou uma alternância separada por `|` (por exemplo, `Bash` ou `Edit|Write`) é ativado quando qualquer token corresponde ao nome da ferramenta de runtime ou ao nome da ferramenta no Claude na tabela abaixo.\n* Qualquer outro valor é tratado como uma regex sensível a maiúsculas e minúsculas, ancorada como `^(?:PATTERN)$` e aplicada ao nome da ferramenta no Claude (ou ao nome do runtime para ferramentas sem equivalente no Claude).\n\nPayloads para PascalCase `PreToolUse` informam `tool_name` como o nome da ferramenta no Claude (por exemplo, `Bash`, não `bash`).\n\n| Ferramenta de runtime | Nome da ferramenta Claude |\n| ------------------------------------------- | ------------------------- |\n| `bash`, `powershell` | `Bash` |\n| `view` | `Read` |\n| `create` | `Write` |\n| `edit`, `str_replace_editor`, `apply_patch` | `Edit` |\n| `grep`, `rg` | `Grep` |\n| `glob` | `Glob` |\n| `web_fetch` | `WebFetch` |\n| `web_search` | `WebSearch` |\n| `ask_user` | `AskUserQuestion` |\n| `update_todo` | `TodoWrite` |\n| `task` | |\n| `Agent` (o literal `Task` também é aceito) | |\n\nFerramentas sem equivalente no Claude mantêm seus nomes de tempo de execução.\n\n> \\[!IMPORTANT]\n> **Comportamento de falha de comando vs. HTTP para `preToolUse`:** Os hooks de comando `preToolUse` são **fail-closed** em caso de erro — um travamento ou uma saída diferente de zero (incluindo a saída `2`) bloqueia a chamada da ferramenta, mesmo que o JSON de stdout do hook informe `permissionDecision: \"allow\"`. Os timeouts de gancho de comando **sempre operam em modo fail-open, mesmo para `preToolUse` e ganchos de política implantados por administradores** — um gancho que excede o tempo limite exibe um aviso e permite que a chamada da ferramenta prossiga pelo fluxo normal de permissões, em vez de negá-la. Os ganchos `preToolUse` HTTP são do tipo **fail-open**—um erro de rede, um tempo limite ou uma resposta com status diferente de 2xx segue para o fluxo de permissão padrão. Escolha a variante que corresponde aos seus requisitos de segurança.\n\n### `postToolUse` / `PostToolUse`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n toolResult: {\n resultType: \"success\";\n textResultForLlm: string;\n }\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"PostToolUse\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown;\n tool_result: {\n result_type: \"success\";\n text_result_for_llm: string;\n }\n}\n```\n\n### `postToolUseFailure` / `PostToolUseFailure`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n error: string;\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"PostToolUseFailure\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown;\n error: string;\n}\n```\n\n### `agentStop` / `Stop`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n stopReason: \"end_turn\";\n stop_hook_active: boolean; // true when this turn was already forced to continue by a prior \"block\" decision from this hook\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"Stop\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n stop_reason: \"end_turn\";\n stop_hook_active: boolean;\n}\n```\n\n### `subagentStart`\n\n> \\[!NOTE]\n> O agente interno `general-purpose` não emite `subagentStart` nem `subagentStop` eventos. Todos os outros agentes internos baseados em YAML, incluindo `explore`, `task`, `code-review`, `rubber-duck`, `research` e `security-review`, e os agentes personalizados definidos pelo usuário emitem esses eventos.\n\n**Entrada:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n agentName: string;\n agentDisplayName?: string;\n agentDescription?: string;\n}\n```\n\n### `subagentStop` / `SubagentStop`\n\nÉ acionado quando um subagente é concluído normalmente, antes de retornar os resultados para o pai.\n`stopReason` atualmente é sempre `\"end_turn\"`. Este gancho é acionado antes do tratamento de overflow de respostas grandes, portanto `response` (ou `last_assistant_message` no formato compatível com VS Code) contém o texto completo da resposta final do subagente.\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n agentId: string;\n agentType: string;\n agentName: string;\n agentDisplayName?: string;\n response: string; // Full final subagent response text\n stopReason: \"end_turn\";\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"SubagentStop\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n agent_id: string;\n agent_type: string;\n agent_name: string;\n agent_display_name?: string;\n last_assistant_message: string; // The `response` text\n stop_reason: \"end_turn\";\n}\n```\n\n### `errorOccurred` / `ErrorOccurred`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n error: {\n message: string;\n name: string;\n stack?: string;\n };\n errorContext: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n recoverable: boolean;\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"ErrorOccurred\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n error: {\n message: string;\n name: string;\n stack?: string;\n };\n error_context: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n recoverable: boolean;\n}\n```\n\n### `preCompact` / `PreCompact`\n\n**entrada camelCase:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n trigger: \"manual\" | \"auto\";\n customInstructions: string;\n}\n```\n\n\\*\\*\nVS Code entrada compatível:\\*\\*\n\n```typescript\n{\n hook_event_name: \"PreCompact\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n trigger: \"manual\" | \"auto\";\n custom_instructions: string;\n}\n```\n\n## `preToolUse` controle de decisão\n\nO `preToolUse` gancho pode controlar a execução da ferramenta escrevendo um objeto JSON para stdout.\n\n| Field | Valores | Description |\n| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| `permissionDecision` | | |\n| `\"allow\"`, `\"deny\"`, `\"ask\"` | Se a ferramenta é executada. A saída vazia usa o comportamento padrão. No agente de nuvem, `\"ask\"` é tratado como `\"deny\"` porque nenhum usuário está disponível para responder. | |\n| `permissionDecisionReason` | cadeia | Motivo mostrado ao agente. Obrigatório quando a decisão é `\"deny\"`. |\n| `modifiedArgs` | objeto | Substitua os argumentos da ferramenta para serem usados no lugar dos originais. |\n\nQuando Copilot CLI pode mostrar o prompt de permissão de gancho, o usuário pode digitar comentários opcionais junto com uma negação. Esse comentário é acrescentado à mensagem que o agente recebe: `Denied by user via preToolUse hook prompt: . The user provided the following feedback: `.\n\n## `agentStop`/ `subagentStop` controle de decisão\n\n| Field | Valores | Description |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------- |\n| `decision` | | |\n| `\"block\"`, `\"allow\"` | | |\n| `\"block\"` obriga outro agente a fazer um turno usando `reason` como prompt. | | |\n| `reason` | cadeia | Solicite a próxima rodada quando `decision` for `\"block\"`. |\n| `modifiedResponse` | cadeia | |\n| \\*\\* | | |\n| `subagentStop` Só.\\*\\* Substitui a resposta retornada ao agente pai quando o subagente pode concluir sua execução — útil para ocultar ou reformatar a saída do subagente. Não aplicável a `agentStop`. | | |\n\n`decision` e `reason` se comporte da mesma forma para ambos `agentStop` e `subagentStop`.\n`modifiedResponse` aplica-se somente a `subagentStop`:\n\n* Uma decisão válida `block` vence `modifiedResponse`: se um hook retornar os dois, o subagente continuará e a reescrita será descartada.\n* As regravações não compõem vários ganchos correspondentes. Cada hook recebe o mesmo `response` original, e o último hook que retorna `modifiedResponse` prevalece — encadear um redactor e um formatter não passa o texto com trechos ocultados para o formatter.\n* Os nomes de campo de saída (`decision`, `reason`, `modifiedResponse`) são os mesmos para as configurações camelCase e VS Code compatíveis.\n\n> \\[!NOTE]\n> **Guarda fugitivo.** Após 8 continuações consecutivas `block`, a CLI ignora o hook e encerra a vez assim mesmo, para evitar um loop infinito. Use o campo de entrada `stop_hook_active` em `agentStop` para detectar que esta vez já foi forçada a continuar e se autolimitar antes de atingir o limite.\n\n## `postToolUse` saída\n\nO `postToolUse` gancho pode modificar o resultado da ferramenta ou injetar contexto adicional para o modelo escrevendo um objeto JSON para stdout.\n\n```typescript\n{\n modifiedResult?: {\n resultType: \"success\";\n textResultForLlm: string;\n };\n additionalContext?: string;\n}\n```\n\n| Field | Tipo | Description |\n| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `modifiedResult` | objeto | Resultado da ferramenta de substituição. Deve ter `resultType: \"success\"`. Se retornado com `resultType: \"failure\"`, a falha é roteada downstream e `postToolUseFailure` é acionado em seguida. |\n| `additionalContext` | cadeia | Orientações adicionais anexadas a `textResultForLlm` para que o modelo as veja após a saída da ferramenta na mesma rodada. Quando vários ganchos retornam `additionalContext`, os resultados são unidos com uma nova linha dupla e limitados a 10 KB. |\n\nRetorne `{}` ou esvazie a saída para manter o resultado bem-sucedido original.\n\n> \\[!NOTE]\n> `modifiedResult` é respeitado por ganchos programáticos do SDK e por ganchos `postToolUse` de arquivo de configuração HTTP/comando.\n\n**Matcher:** Regex opcional testado contra `toolName`. O padrão regex é o valor do `matcher` campo, compilado como `^(?:PATTERN)$`, e deve corresponder ao nome inteiro da ferramenta. Se o padrão não for uma expressão regular válida, o gancho será ignorado. Omita `matcher` para receber resultados de todas as ferramentas.\n\n```json\n{\n \"type\": \"command\",\n \"matcher\": \"bash|edit\",\n \"bash\": \"./scripts/log-tool.sh\"\n}\n```\n\n## `permissionRequest` controle de decisão\n\n> \\[!NOTE]\n> **Copilot CLI Só.** O gancho `permissionRequest` não se aplica em Copilot cloud agent— as chamadas de ferramenta lá são pré-aprovadas (consulte a linha **Interatividade** na tabela de ambiente de execução do Agente de nuvem). Use `preToolUse` para tomar decisões de permissão no agente de nuvem.\n\nO gancho `permissionRequest` é disparado antes da execução do serviço de permissão, ou seja, antes de verificações de regra, aprovações de sessão, permissão automática/negação automática e solicitação do usuário. Se os ganchos retornarem `behavior: \"allow\"` ou `\"deny\"`, essa decisão causará um curto-circuito no fluxo de permissão normal. O retorno de nada passa pelo tratamento normal de permissões. Use-o para aprovar ou negar chamadas de ferramenta de forma programática — especialmente útil no modo de pipe da CLI (`-p`) e em outros usos de CI da CLI em que nenhum prompt interativo está disponível. Ele não se aplica ao agente de nuvem.\n\nTodos os ganchos configurados `permissionRequest` são executados para cada solicitação (exceto os tipos de permissão `read` e `hook`, que entram em curto-circuito antes dos ganchos). As saídas de gancho são mescladas com saídas de gancho posteriores substituindo as anteriores.\n\n**Exceção de desvio da sandbox:** para qualquer solicitação que peça para sair da sandbox (`requestSandboxBypass: true` em `toolInput`), um hook `allow` não pré-aprova a solicitação nem ignora a solicitação de confirmação do usuário — sair da sandbox constitui uma elevação de privilégios que o usuário deve sempre confirmar de forma interativa. Isso abrange um comando de shell que solicita execução fora da sandbox e um `web_fetch` cuja URL é bloqueada pela política de rede da sandbox. Apenas `deny` ainda é propagado (para que um hook de política possa bloquear a saída); um `allow` (ou nenhuma decisão) segue para o prompt normal.\n\n**Matcher:** Regex opcional testado contra `toolName`. O padrão regex é o valor do `matcher` campo, ancorado como `^(?:PATTERN)$`, e deve corresponder ao nome completo da ferramenta. Quando definido, o gancho é acionado apenas para nomes de ferramentas correspondentes.\n\n> \\[!NOTE]\n> **Correspondentes no formato Claude (PascalCase `PermissionRequest`):** ganchos configurados com o nome de evento PascalCase `PermissionRequest` usam a mesma semântica de correspondência do Claude que `PreToolUse`. Consulte [correspondentes no formato Claude (PascalCase PreToolUse)](#claude-format-matchers-pascalcase-pretooluse) para ver as regras dos correspondentes e a tabela de nomes de ferramentas.\n\nPara controlar a decisão de permissão, exibir JSON no stdout:\n\n| Field | Valores | Description |\n| ------------------- | ----------------------------------------- | ----------------------------------------------------------------------- |\n| `behavior` | | |\n| `\"allow\"`, `\"deny\"` | Aprovar ou negar a chamada da ferramenta. | |\n| `message` | cadeia | Motivo para voltar à LLM ao negar. |\n| `interrupt` | boolean | Quando `true` é combinado com `\"deny\"`, interrompe totalmente o agente. |\n\nRetorne uma saída vazia ou `{}` para avançar para o fluxo de permissão normal. Para ganchos de comando, o código `2` de saída é tratado como uma negação; stdout JSON (se houver) é mesclado com `{\"behavior\":\"deny\"}`, e stderr é ignorado.\n\n## Gancho `notification`\n\n> \\[!NOTE]\n> **Copilot CLI Só.** O gancho `notification` não é acionado em Copilot cloud agent.\n\nO `notification` gancho é acionado de forma assíncrona quando a CLI emite uma notificação do sistema. Esses ganchos são fire-and-forget: eles nunca bloqueiam a sessão, e quaisquer erros são registrados no log e ignorados.\n\n**Entrada:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n hook_event_name: \"Notification\";\n message: string; // Human-readable notification text\n title?: string; // Short title (e.g., \"Permission needed\", \"Shell completed\")\n notification_type: string; // One of the types listed below\n}\n```\n\n**Tipos de notificação:**\n\n| Tipo | Quando é acionado |\n| -------------------------- | ---------------------------------------------------------------------------------------------- |\n| `shell_completed` | Um comando de shell em segundo plano (assíncrono) termina |\n| `shell_detached_completed` | Uma sessão de shell desconectada é concluída |\n| `agent_completed` | Um subagente de segundo plano é finalizado (completo ou com falha) |\n| `agent_idle` | Um agente em segundo plano conclui um ciclo e entra em modo inativo (aguardando `write_agent`) |\n| `permission_prompt` | O agente solicita permissão para executar uma ferramenta |\n| `elicitation_dialog` | O agente solicita informações adicionais do usuário |\n\n**Saída:**\n\n```typescript\n{\n additionalContext?: string; // Injected into the session as a user message\n}\n```\n\nSe `additionalContext` for retornado, o texto será injetado na sessão como uma mensagem de usuário prefixada. Isso pode disparar um processamento adicional do agente se a sessão estiver ociosa. Retornar `{}` ou esvaziar a saída para não executar nenhuma ação.\n\n**Matcher:** Regex opcional em `notification_type`. O padrão de regex corresponde ao valor do campo `matcher`, delimitado por `^(?:PATTERN)$`. Omita `matcher` para receber todos os tipos de notificação.\n\n## Filtragem do comparador\n\nVários eventos aceitam um regex `matcher` opcional em cada entrada de gancho que filtra para quais invocações o gancho é acionado. Ele é compilado como `^(?:PATTERN)$` e deve corresponder ao valor completo. Regexes inválidos fazem com que a entrada de gancho seja ignorada.\n\n\\| Acontecimento |\n`matcher` corresponde a |\n\\|-------|------------------------------|\n\\| `notification` | `notification_type` |\n\\| `permissionRequest` | `toolName` |\n\\| `postToolUse` | `toolName` |\n\\| `preCompact` |\n`trigger` (`\"manual\"` ou `\"auto\"`) |\n\\| `preToolUse` | `toolName` |\n\\| `subagentStart` | `agentName` |\n\n## Nomes de ferramentas para correspondência de ganchos\n\n| Nome da ferramenta | Description |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `ask_user` | Faça uma pergunta esclarecedora ao usuário. No agente de nuvem não há nenhum usuário, portanto `ask_user` , não produz um resultado útil. |\n| `bash` | Execute comandos de shell (Unix). |\n| `create` | Crie novos arquivos. |\n| `edit` | Modificar o conteúdo do arquivo. |\n| `glob` | Localizar arquivos por padrão. |\n| `grep` | Pesquisar conteúdo do arquivo. |\n| `powershell` | Execute comandos de shell (Windows). Não aparece no agente de nuvem (área restrita do Linux). |\n| `task` | Executar tarefas de subagente. |\n| `view` | Ler o conteúdo do arquivo. |\n| `web_fetch` | Recuperar páginas da Web. |\n\nSe vários ganchos do mesmo tipo forem configurados, eles serão executados em ordem. Para `preToolUse`, se algum gancho retornar `\"deny\"`, a ferramenta será bloqueada. Para a maioria dos eventos, as falhas de gancho (códigos de saída diferentes de zero, exceto `2`, ou tempos limite excedidos) são registradas e ignoradas.\n**Exceção: `preToolUse` os ganchos de comando são fechados com fail-closed na saída `2` e em erros sem tempo limite** — saída `2`, uma falha ou qualquer outra saída diferente de zero (diferente de um tempo limite) nega a chamada da ferramenta, mesmo que o JSON stdout do gancho seja reportado `permissionDecision: \"allow\"`.\n**Os timeouts sempre resultam em fail-open, inclusive para `preToolUse` e hooks de política implantados pelo administrador**: uma advertência é exibida, e a chamada da ferramenta prossegue pelo fluxo normal de permissão em vez de ser negada.\n\n## Códigos de saída para ganchos de comando\n\n| Código de saída | Significado |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |\n| `0` | Êxito. |\n| `stdout` é analisado como o JSON de saída do gancho, se presente. | |\n| `2` | Tratado como um aviso por padrão. |\n| `stderr` é exibido para o usuário, mas a execução continua. Para `permissionRequest` e `preToolUse`, a saída `2` é tratada como uma negação: qualquer `stdout` JSON é mesclado com a decisão de negação e a chamada de ferramenta é negada mesmo se esse JSON relatar `permissionDecision: \"allow\"`. Para `postToolUseFailure`, a saída `2` é tratada como `additionalContext` e `stdout` é acrescentada à falha mostrada ao agente. | |\n| Outros que não são zero | Registrado como uma falha de gancho. A execução continua (fail-open). |\n| **Exceção: `preToolUse` é fail-closed**— uma saída diferente de zero (diferente da saída 2) nega a chamada da ferramenta com `\"Denied by preToolUse hook (hook errored)\"`. | |\n| Intervalo | Encerrado após `timeoutSec`. Erro registrado, a execução continua. |\n| **Os timeouts são tratados em fail-open em todos os eventos, incluindo `preToolUse` e hooks de política implantados pelo administrador**—um aviso é exibido e o processamento prossegue como se o hook não tivesse sido executado. Se `preToolUse`, a chamada da ferramenta segue o fluxo normal de permissão em vez de ser negada. Um hook que travou ou que nega explicitamente ainda falha de forma fechada; somente os timeouts são exceção. | |\n\nPara a maioria dos eventos, saídas diferentes de zero e expirações por tempo limite são registradas e ignoradas — a execução do agente continua. Para hooks de comando `preToolUse`, a saída 2, travamentos e outras saídas diferentes de zero sempre resultam em fail-closed e negam a chamada da ferramenta — a saída 2 sempre nega, mesmo que o JSON do hook `stdout` informe `permissionDecision: \"allow\"` —, mas **timeouts sempre resultam em fail-open** — um hook lento ou inacessível não deve bloquear silenciosamente chamadas da ferramenta nem operações, mesmo quando o hook foi implantado por um administrador como política.\n\n## Desabilitar todos os ganchos\n\nUse `disableAllHooks` quando quiser manter a configuração do gancho no disco, mas impedir que ela seja executada, por exemplo:\n\n* Depuração de um problema e você deseja confirmar se um gancho é a causa sem excluir sua configuração.\n* Pausar a automação durante uma tarefa confidencial (uma revisão de código, uma ramificação de versão, trabalho com segredos) sem perder a configuração. (**Copilot CLI somente.**)\n* Enviar um arquivo de ganchos no controle do código-fonte que os colaboradores podem recusar localmente definindo a opção em seu repositório `settings.json`. (**Copilot CLI somente.**)\n* Silenciando temporariamente ganchos lentos ou barulhentos durante uma sessão interativa. (**Copilot CLI somente.**)\n\nDefina `disableAllHooks` como `true` no nível superior para ignorar cada gancho no arquivo sem excluí-lo.\n\n```json\n{\n \"version\": 1,\n \"disableAllHooks\": false,\n \"hooks\": {\n \"preToolUse\": [ /* hook entries */ ]\n }\n}\n```\n\nO comportamento depende de onde você define o sinalizador:\n\n* **Dentro de um único arquivo `.github/hooks/*.json`** — somente os ganchos declarados nesse arquivo são ignorados. Respeitado por Copilot CLI e Copilot cloud agent.\n* **No nível mais alto do repositório `settings.json`** — **Copilot CLI apenas.** Todos os ganchos de todas as fontes (arquivos de repositório, arquivos de usuário, plug-ins e blocos de ganchos embutidos) são ignorados durante as sessões nesse repositório. Os ganchos de política não são afetados e continuam sendo executados. O agente de nuvem não carrega `settings.json`.\n\n## Leitura adicional\n\n* [Usando ganchos com GitHub Copilot CLI](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)\n* [Referência de ganchos do GitHub Copilot](/pt/enterprise-cloud@latest/copilot/reference/hooks-reference)\n* [referência de comando da CLI GitHub Copilot](/pt/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [Conceitos para GitHub Copilot agente de nuvem](/pt/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent)"}