Referência dos hooks do GitHub Copilot

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: CLI do Copilot e agente de nuvem Copilot. 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 os dois contextos é destacado em notas "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 hooks são executados e onde você pode armazenar arquivos de configuração de hook dependem do ambiente:

• **CLI do Copilot ** — 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 em ordem (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 gancho no nível do repositório — .github/hooks/*.json na raiz do repositório.
  • Arquivos de gancho de nível de usuário – *.json arquivos no diretório de ganchos de nível de 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/.
  • Bloco embutido hooks nas configurações do repositório — o hooks campo no nível superior de .github/copilot/settings.json (Git commitado) ou .github/copilot/settings.local.json (normalmente ignorado pelo git e específico do usuário) no repositório. Arquivos de ferramentas cruzadas .claude/settings.json e .claude/settings.local.json no repositório também são lidos.
  • Bloco embutido hooks na configuração no nível do usuário – o hooks campo no nível superior de ~/.copilot/settings.json.
  • Hooks contribuídos por plugins instalados — declarados por cada plugin em seu próprio hooks.json (ou em hooks/hooks.json) dentro do diretório de instalação do plugin.

• **agente de nuvem Copilot ** — ganchos são executados dentro da sandbox 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 bash (ou command) entradas são consideradas.

  A configuração do gancho é carregada a partir de arquivos .github/hooks/*.json no repositório clonado.

Ambiente de execução do agente de nuvem

Esta seção se aplica somente aagente de nuvem Copilot. Ele descreve restrições que afetam a forma como você escreve scripts de gancho e configura entradas de gancho para trabalhos de 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 hook, envie-a por meio de uma http entrada de hook. | | 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 ~/... grava 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 de agente de nuvem, a única configuração de gancho que existe por padrão está .github/hooks/*.json dentro do repositório clonado. O sandbox não é enviado com arquivos de hook settings.json, config.json no nível de usuário ou plugins instalados. |

Formato de configuração do gancho

Os arquivos de configuração do gancho usam o formato JSON com a versão 1.

Ganchos de comando

Os ganchos de comando executam scripts de shell e têm suporte em todos os tipos de gancho.

{
  "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	Fallback entre plataformas usado quando nem bash nem powershell está definido na plataforma atual.
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.
timeoutSec	número	Não	Tempo limite em segundos. Padrão: 30.
type	"command"	Sim	Deve ser "command".

Ganchos HTTP

Os ganchos HTTP enviam o conteúdo de entrada como um JSON POST para uma URL.

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

{
  "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 enviada pode ser uma mensagem de linguagem natural ou um comando de barra.

Eventos de intercepção

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 outro turno, que ainda conta contra o 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. matcher Dá suporte ao regex 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 gancho mesclado retornar behavior: "allow" ou "deny", essa decisão interrompe o fluxo de permissão normal. matcher Dá suporte ao regex em toolName. | Sim – pode permitir ou negar programaticamente. | As chamadas de ferramenta são previamente aprovadas, portanto, esse 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. | Não | 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). matcher Dá suporte 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 | Dispara 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 um currículo). Consulte a nota de prompts acima sobre o comportamento das entradas prompt no agente de nuvem. | | subagentStart | Um subagente é gerado (antes de ser executado). matcher Dá suporte 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. | Não | Acionado no máximo uma vez, para o prompt fornecido ao trabalho. Não há nenhuma entrada de acompanhamento do usuário. |

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 (formato de nomenclatura onde a primeira palavra é minúscula e as subsequentes começam com letra maiúscula).
• 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:**

{
    sessionId: string;
    timestamp: number;      // Unix timestamp in milliseconds
    cwd: string;
    source: "startup" | "resume" | "new";
    initialPrompt?: string;
}

          **
          VS Code entrada compatível:**

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

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

          **
          VS Code entrada compatível:**

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

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    prompt: string;
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "UserPromptSubmit";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    prompt: string;
}

preToolUse / PreToolUse

          **entrada camelCase:**

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

{
    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)
}

postToolUse / PostToolUse

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    toolResult: {
        resultType: "success";
        textResultForLlm: string;
    }
}

          **
          VS Code entrada compatível:**

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

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    error: string;
}

          **
          VS Code entrada compatível:**

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

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    stopReason: "end_turn";
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "Stop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    stop_reason: "end_turn";
}

subagentStart

          **Entrada:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    agentDescription?: string;
}

subagentStop / SubagentStop

          **entrada camelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    stopReason: "end_turn";
}

          **
          VS Code entrada compatível:**

{
    hook_event_name: "SubagentStop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    agent_name: string;
    agent_display_name?: string;
    stop_reason: "end_turn";
}

errorOccurred / ErrorOccurred

          **entrada camelCase:**

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

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

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    trigger: "manual" | "auto";
    customInstructions: string;
}

          **
          VS Code entrada compatível:**

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

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

permissionRequest controle de decisão

O permissionRequest gancho é acionado antes da execução do serviço de permissão , 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 ferramentas programaticamente — 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 pelos tipos de permissão read e hook, que curto-circuitam antes dos ganchos). As saídas de gancho são mescladas com saídas de gancho posteriores substituindo as anteriores.

          **Matcher:** Regex opcional testado contra `toolName`. Ancorado como `^(?:pattern)$`; deve corresponder ao nome completo da ferramenta. Quando definido, o gancho é acionado apenas para nomes de ferramentas correspondentes.

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

Retornar 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.

notification Gancho

O notification gancho é acionado de forma assíncrona quando a CLI emite uma notificação do sistema. Esses ganchos são "fire-and-forget" (disparar e esquecer): eles nunca bloqueiam a sessão, e quaisquer erros são registrados no log e ignorados.

          **Entrada:**

{
    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 em execução em 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:**

{
    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 é ancorado como `^(?:pattern)$`. Omita `matcher` para receber todos os tipos de notificação.

Filtragem do comparador

Vários eventos aceitam um regex opcional matcher em cada registro de gancho que filtra para quais invocações o gancho é disparado. O padrão é ancorado como ^(?:matcher)$ e deve corresponder ao valor completo. Regexes inválidos fazem com que a entrada de hook seja ignorada.

| Acontecimento | matcher é comparado com | |-------|------------------------------| | notification | notification_type | | permissionRequest | toolName | | preCompact | trigger ("manual" ou "auto") | | preToolUse | toolName | | subagentStart | agentName |

Nomes de ferramentas para correspondência de hooks

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. Falhas de hooks (códigos de saída diferentes de zero, exceto 2 ou tempos limite) são registradas e ignoradas—nunca bloqueiam a execução do agente.

Códigos de saída para hooks 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, a saída 2 é tratada como {"behavior":"deny"} e qualquer stdout JSON é mesclado. 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). |

Desabilitar todos os ganchos

Use disableAllHooks quando quiser manter a configuração do gancho no disco, mas impedir que ela seja executada, por exemplo:

• Debugando um problema e você deseja confirmar se um "hook" é a causa sem deletar sua configuração.
• Pausar a automação durante uma tarefa confidencial (uma revisão de código, um branch de versão, trabalhar com segredos) sem perder a configuração. (CLI do Copilot somente.)
• Enviar um arquivo de ganchos no controle do código-fonte do qual os colaboradores podem recusar localmente definindo a opção em seu repositório settings.json. (CLI do Copilot apenas.)
• Silenciando temporariamente ganchos lentos ou barulhentos durante uma sessão interativa. (CLI do Copilot somente.)

Defina disableAllHooks como true no nível superior para ignorar cada gancho no arquivo sem excluí-lo.

{
  "version": 1,
  "disableAllHooks": false,
  "hooks": {
    "preToolUse": [ /* hook entries */ ]
  }
}

O comportamento depende de onde você define o sinalizador:

• Dentro de um único .github/hooks/*.json arquivo , somente os ganchos declarados nesse arquivo são pulados. Honrado por ambos CLI do Copilot e agente de nuvem Copilot.
• No nível mais alto do repositório settings.json — CLI do Copilot apenas. Cada hook de cada origem (arquivos de repositório, arquivos de usuário, plug-ins e blocos de hook embutidos) é ignorado durante as sessões nesse repositório. O agente de nuvem não carrega settings.json.

Leitura adicional

• Usando ganchos com CLI do GitHub Copilot
• Referência dos hooks do GitHub Copilot
• referência de comando da CLI GitHub Copilot
• Conceitos para GitHub Copilot agente de nuvem