# Referência de ganchos do GitHub Copilot Encontre eventos de gancho, formatos de configuração e cargas de entrada para ganchos em Copilot CLI e Copilot cloud agent. ## Introdução Ganchos 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. Há 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. Ao 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. ## Localizações de ganchos Os locais em que os ganchos são executados e onde você pode armazenar arquivos de configuração de ganchos dependem da superfície: * **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. 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. * **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. * **Arquivos de gancho no nível do repositório** — `.github/hooks/*.json` na raiz do repositório. * **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/`. * **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. * **Bloqueio `hooks` embutido na configuração no nível do usuário** – o campo `hooks` no nível superior de `~/.copilot/settings.json`. * **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. * **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. A configuração do gancho é carregada a partir de arquivos `.github/hooks/*.json` no repositório clonado. ### Ganchos de política > \[!NOTE] > **Copilot CLI Só.** Não há suporte para ganchos de política em Copilot cloud agent. Os 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`. Os ganchos de política são descobertos de duas fontes: * **Sistema de arquivos**: arquivos JSON no diretório de política apropriado à plataforma, carregados em ordem alfabética: * Linux/macOS: `/etc/github-copilot/policy.d/*.json` * Windows: `C:\ProgramData\GitHub\Copilot\policy.d\*.json` * **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). Os 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. Os 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. ## Ambiente de execução do agente de nuvem Esta 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. | Property | Value | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | | Diretório de trabalho | | | `/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. | | | 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`. | | 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. | | Variáveis de ambiente disponíveis | | | `GITHUB_COPILOT_API_TOKEN` e `GITHUB_COPILOT_GIT_TOKEN` são definidos no sandbox. | | | `COPILOT_AGENT_PROMPT` mantém o prompt com o qual o trabalho foi invocado. | | | `HOME` é definido como `/root`, de modo que qualquer script de gancho que resolve caminhos `~/...` grave na área restrita efêmera. | | | `GITHUB_TOKEN` não está definido. | | | 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. | | 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. | ## Formato de configuração do gancho Os arquivos de configuração do gancho usam o formato JSON com a versão `1`. > \[!NOTE] > 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. ### Ganchos de comando Os ganchos de comando executam scripts de shell e têm suporte em todos os tipos de gancho. > \[!NOTE] > **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. ```json { "version": 1, "hooks": { "preToolUse": [ { "type": "command", "bash": "YOUR_BASH_COMMAND", "powershell": "YOUR_POWERSHELL_COMMAND", "cwd": "OPTIONAL/WORKING/DIRECTORY", "env": { "VAR": "VALUE" }, "timeoutSec": 30 } ] } } ``` | Field | Tipo | Obrigatório | Description | | ------------ | ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bash` | cadeia | Uma opção entre `bash`, `powershell` ou `command` | Comando shell para Unix. | | `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. | | `cwd` | cadeia | Não | Diretório de trabalho para o comando (relativo à raiz do repositório ou absoluto). | | `env` | objeto | Não | Variáveis de ambiente a serem definidas (dá suporte à expansão variável). | | `powershell` | cadeia | Uma opção entre `bash`, `powershell` ou `command` | Comando shell para Windows. | | `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. | | `timeoutSec` | número | Não | Tempo limite em segundos. Padrão: `30`. | | `type` | `"command"` | Não | Tipo de gancho. Quando omitido, o padrão é `"command"`. | #### Mensagens de progresso Os 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: ```bash echo '{"type": "progress", "message": "Checking policy..."}' # ... perform work ... echo '{"permissionDecision": "allow"}' ``` Defina `"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: ```bash echo '{"type": "progress", "message": "Routing...", "temporary": true}' echo '{"type": "progress", "message": "Thinking...", "temporary": true}' # ... perform work ... echo '{"permissionDecision": "allow"}' ``` As 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. **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: * 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. * 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. * 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. * 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. ### Ganchos HTTP Os ganchos HTTP enviam o conteúdo de entrada como um JSON `POST` para uma URL. > \[!NOTE] > > * 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. > * **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. ```json { "version": 1, "hooks": { "postToolUse": [ { "type": "http", "url": "https://hooks.example.com/copilot", "headers": { "X-Source": "copilot-cli" }, "allowedEnvVars": ["GITHUB_TOKEN"], "timeoutSec": 30 } ] } } ``` | Field | Tipo | Obrigatório | Description | | ---------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `allowedEnvVars` | string\[] | Não | Nomes de variáveis de ambiente que podem ser expandidos dentro de valores `headers`. Quando definido, `url` deve usar `https://`. | | `headers` | objeto | Não | Solicitar cabeçalhos a serem incluídos. | | `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. | | `timeoutSec` | número | Não | Tempo limite em segundos. Padrão: `30`. | | `type` | `"http"` | Sim | Deve ser `"http"`. | | `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. | ### Ganchos de prompt Prompt 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. > \[!NOTE] > **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`). > \[!NOTE] > **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. ```json { "version": 1, "hooks": { "sessionStart": [ { "type": "prompt", "prompt": "YOUR_PROMPT_TEXT_OR_SLASH_COMMAND" } ] } } ``` | Field | Tipo | Obrigatório | Description | | -------- | ---------- | ----------- | ---------------------------------------------------------------------------------------- | | `type` | `"prompt"` | Sim | Deve ser `"prompt"`. | | `prompt` | cadeia | Sim | O texto a ser enviado pode ser uma mensagem de linguagem natural ou um comando de barra. | ## Eventos de gancho A 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. | Acontecimento | Acionado quando | A saída foi processada | Agente de nuvem | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `agentStop` | O agente principal conclui um turno. | Sim – pode bloquear e forçar a continuação. | Incêndios. | | `decision: "block"` força outra rodada, que ainda conta no tempo limite do trabalho. | | | | | `errorOccurred` | Ocorre um erro durante a execução. | Não | Incêndios. | | `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ã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). | | | | | `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. | | `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. | | `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. | | `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. | | `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. | | `sessionEnd` | A sessão é encerrada. | Não | É acionado uma vez por trabalho. | | `reason` normalmente é `"complete"`, `"error"` ou `"timeout"`; `"abort"` e `"user_exit"` não são esperados porque não há usuário. | | | | | `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. | | `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. | | `subagentStop` | Um subagente completa. | Sim – pode bloquear e forçar a continuação. | Incêndios. | | `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. | | `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. | ## Cargas de entrada de evento do gancho Cada 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: * **formato camelCase** — Configure o nome do evento em camelCase (por exemplo, `sessionStart`). Os campos usam camelCase. * **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. ### `sessionStart` / `SessionStart` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; // Unix timestamp in milliseconds cwd: string; source: "startup" | "resume" | "new"; initialPrompt?: string; } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "SessionStart"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; source: "startup" | "resume" | "new"; initial_prompt?: string; } ``` ### `sessionEnd` / `SessionEnd` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "SessionEnd"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; } ``` ### `userPromptSubmitted` / `UserPromptSubmit` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; prompt: string; } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "UserPromptSubmit"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; prompt: string; } ``` **Saída:** ```typescript { modifiedPrompt?: string; // Replaces the prompt for the rest of the turn (SDK programmatic hooks only) } ``` Retorne `{}` ou vazio para deixar o prompt inalterado. > \[!NOTE] > \* > `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`. > > * 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. ### `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. 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. **Entrada:** ```typescript { sessionId: string; timestamp: number; // epoch-ms integer cwd: string; prompt: string; // user prompt after userPromptSubmitted hooks have run transformedPrompt: string; // runtime-transformed content the model will receive } ``` **Saída:** ```typescript { modifiedTransformedPrompt?: string; // Replaces the model-facing content } ``` Retorne `{}` ou vazio para deixar o conteúdo transformado inalterado. `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. ### `preToolUse` / `PreToolUse` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; } ``` \*\* VS Code entrada compatível:\*\* Quando 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. ```typescript { hook_event_name: "PreToolUse"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; // Tool arguments (parsed from JSON string when possible) } ``` **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: * `*`, `**` ou um valor `matcher` vazio é acionado para cada ferramenta. * 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. * 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). Payloads para PascalCase `PreToolUse` informam `tool_name` como o nome da ferramenta no Claude (por exemplo, `Bash`, não `bash`). | Ferramenta de runtime | Nome da ferramenta Claude | | ------------------------------------------- | ------------------------- | | `bash`, `powershell` | `Bash` | | `view` | `Read` | | `create` | `Write` | | `edit`, `str_replace_editor`, `apply_patch` | `Edit` | | `grep`, `rg` | `Grep` | | `glob` | `Glob` | | `web_fetch` | `WebFetch` | | `web_search` | `WebSearch` | | `ask_user` | `AskUserQuestion` | | `update_todo` | `TodoWrite` | | `task` | | | `Agent` (o literal `Task` também é aceito) | | Ferramentas sem equivalente no Claude mantêm seus nomes de tempo de execução. > \[!IMPORTANT] > **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. ### `postToolUse` / `PostToolUse` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; toolResult: { resultType: "success"; textResultForLlm: string; } } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "PostToolUse"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; tool_result: { result_type: "success"; text_result_for_llm: string; } } ``` ### `postToolUseFailure` / `PostToolUseFailure` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; error: string; } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "PostToolUseFailure"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; error: string; } ``` ### `agentStop` / `Stop` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; stopReason: "end_turn"; stop_hook_active: boolean; // true when this turn was already forced to continue by a prior "block" decision from this hook } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "Stop"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; stop_reason: "end_turn"; stop_hook_active: boolean; } ``` ### `subagentStart` > \[!NOTE] > 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. **Entrada:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; agentName: string; agentDisplayName?: string; agentDescription?: string; } ``` ### `subagentStop` / `SubagentStop` É acionado quando um subagente é concluído normalmente, antes de retornar os resultados para o pai. `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. **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; agentId: string; agentType: string; agentName: string; agentDisplayName?: string; response: string; // Full final subagent response text stopReason: "end_turn"; } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "SubagentStop"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; agent_id: string; agent_type: string; agent_name: string; agent_display_name?: string; last_assistant_message: string; // The `response` text stop_reason: "end_turn"; } ``` ### `errorOccurred` / `ErrorOccurred` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; error: { message: string; name: string; stack?: string; }; errorContext: "model_call" | "tool_execution" | "system" | "user_input"; recoverable: boolean; } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "ErrorOccurred"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; error: { message: string; name: string; stack?: string; }; error_context: "model_call" | "tool_execution" | "system" | "user_input"; recoverable: boolean; } ``` ### `preCompact` / `PreCompact` **entrada camelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; trigger: "manual" | "auto"; customInstructions: string; } ``` \*\* VS Code entrada compatível:\*\* ```typescript { hook_event_name: "PreCompact"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; trigger: "manual" | "auto"; custom_instructions: string; } ``` ## `preToolUse` controle de decisão O `preToolUse` gancho pode controlar a execução da ferramenta escrevendo um objeto JSON para stdout. | Field | Valores | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `permissionDecision` | | | | `"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. | | | `permissionDecisionReason` | cadeia | Motivo mostrado ao agente. Obrigatório quando a decisão é `"deny"`. | | `modifiedArgs` | objeto | Substitua os argumentos da ferramenta para serem usados no lugar dos originais. | Quando 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: `. ## `agentStop`/ `subagentStop` controle de decisão | Field | Valores | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------- | | `decision` | | | | `"block"`, `"allow"` | | | | `"block"` obriga outro agente a fazer um turno usando `reason` como prompt. | | | | `reason` | cadeia | Solicite a próxima rodada quando `decision` for `"block"`. | | `modifiedResponse` | cadeia | | | \*\* | | | | `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`. | | | `decision` e `reason` se comporte da mesma forma para ambos `agentStop` e `subagentStop`. `modifiedResponse` aplica-se somente a `subagentStop`: * Uma decisão válida `block` vence `modifiedResponse`: se um hook retornar os dois, o subagente continuará e a reescrita será descartada. * 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. * Os nomes de campo de saída (`decision`, `reason`, `modifiedResponse`) são os mesmos para as configurações camelCase e VS Code compatíveis. > \[!NOTE] > **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. ## `postToolUse` saída O `postToolUse` gancho pode modificar o resultado da ferramenta ou injetar contexto adicional para o modelo escrevendo um objeto JSON para stdout. ```typescript { modifiedResult?: { resultType: "success"; textResultForLlm: string; }; additionalContext?: string; } ``` | Field | Tipo | Description | | ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `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. | Retorne `{}` ou esvazie a saída para manter o resultado bem-sucedido original. > \[!NOTE] > `modifiedResult` é respeitado por ganchos programáticos do SDK e por ganchos `postToolUse` de arquivo de configuração HTTP/comando. **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. ```json { "type": "command", "matcher": "bash|edit", "bash": "./scripts/log-tool.sh" } ``` ## `permissionRequest` controle de decisão > \[!NOTE] > **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. O 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. Todos 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. **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. **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. > \[!NOTE] > **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. Para controlar a decisão de permissão, exibir JSON no stdout: | Field | Valores | Description | | ------------------- | ----------------------------------------- | ----------------------------------------------------------------------- | | `behavior` | | | | `"allow"`, `"deny"` | Aprovar ou negar a chamada da ferramenta. | | | `message` | cadeia | Motivo para voltar à LLM ao negar. | | `interrupt` | boolean | Quando `true` é combinado com `"deny"`, interrompe totalmente o agente. | Retorne 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. ## Gancho `notification` > \[!NOTE] > **Copilot CLI Só.** O gancho `notification` não é acionado em Copilot cloud agent. O `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. **Entrada:** ```typescript { sessionId: string; timestamp: number; cwd: string; hook_event_name: "Notification"; message: string; // Human-readable notification text title?: string; // Short title (e.g., "Permission needed", "Shell completed") notification_type: string; // One of the types listed below } ``` **Tipos de notificação:** | Tipo | Quando é acionado | | -------------------------- | ---------------------------------------------------------------------------------------------- | | `shell_completed` | Um comando de shell em segundo plano (assíncrono) termina | | `shell_detached_completed` | Uma sessão de shell desconectada é concluída | | `agent_completed` | Um subagente de segundo plano é finalizado (completo ou com falha) | | `agent_idle` | Um agente em segundo plano conclui um ciclo e entra em modo inativo (aguardando `write_agent`) | | `permission_prompt` | O agente solicita permissão para executar uma ferramenta | | `elicitation_dialog` | O agente solicita informações adicionais do usuário | **Saída:** ```typescript { additionalContext?: string; // Injected into the session as a user message } ``` Se `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. **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. ## Filtragem do comparador Vá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. \| Acontecimento | `matcher` corresponde a | \|-------|------------------------------| \| `notification` | `notification_type` | \| `permissionRequest` | `toolName` | \| `postToolUse` | `toolName` | \| `preCompact` | `trigger` (`"manual"` ou `"auto"`) | \| `preToolUse` | `toolName` | \| `subagentStart` | `agentName` | ## Nomes de ferramentas para correspondência de ganchos | Nome da ferramenta | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `bash` | Execute comandos de shell (Unix). | | `create` | Crie novos arquivos. | | `edit` | Modificar o conteúdo do arquivo. | | `glob` | Localizar arquivos por padrão. | | `grep` | Pesquisar conteúdo do arquivo. | | `powershell` | Execute comandos de shell (Windows). Não aparece no agente de nuvem (área restrita do Linux). | | `task` | Executar tarefas de subagente. | | `view` | Ler o conteúdo do arquivo. | | `web_fetch` | Recuperar páginas da Web. | Se 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. **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"`. **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. ## Códigos de saída para ganchos de comando | Código de saída | Significado | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | | `0` | Êxito. | | `stdout` é analisado como o JSON de saída do gancho, se presente. | | | `2` | Tratado como um aviso por padrão. | | `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. | | | Outros que não são zero | Registrado como uma falha de gancho. A execução continua (fail-open). | | **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)"`. | | | Intervalo | Encerrado após `timeoutSec`. Erro registrado, a execução continua. | | **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. | | Para 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. ## Desabilitar todos os ganchos Use `disableAllHooks` quando quiser manter a configuração do gancho no disco, mas impedir que ela seja executada, por exemplo: * Depuração de um problema e você deseja confirmar se um gancho é a causa sem excluir sua configuração. * 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.**) * 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.**) * Silenciando temporariamente ganchos lentos ou barulhentos durante uma sessão interativa. (**Copilot CLI somente.**) Defina `disableAllHooks` como `true` no nível superior para ignorar cada gancho no arquivo sem excluí-lo. ```json { "version": 1, "disableAllHooks": false, "hooks": { "preToolUse": [ /* hook entries */ ] } } ``` O comportamento depende de onde você define o sinalizador: * **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. * **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`. ## Leitura adicional * [Usando ganchos com GitHub Copilot CLI](/pt/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) * [Referência de ganchos do GitHub Copilot](/pt/copilot/reference/hooks-reference) * [referência de comando da CLI GitHub Copilot](/pt/copilot/reference/copilot-cli-reference/cli-command-reference) * [Conceitos para GitHub Copilot agente de nuvem](/pt/copilot/concepts/agents/cloud-agent)