referência de ganchos da CLI GitHub Copilot

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. Os arquivos de configuração de gancho .github/hooks/*.json são carregados automaticamente a partir de seu repositório.

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
      }
    ]
  }
}

Campo	Tipo	Obrigatório	Description
`bash`	cadeia	Um dos `bash`/`powershell`	Comando shell para Unix.
`cwd`	cadeia	No	Diretório de trabalho para o comando (relativo à raiz do repositório ou absoluto).
`env`	objeto	No	Variáveis de ambiente a serem definidas (dá suporte à expansão variável).
`powershell`	cadeia	Um dos `bash`/`powershell`	Comando shell para Windows.
`timeoutSec`	número	No	Tempo limite em segundos. Padrão: `30`.
`type`	`"command"`	Sim	Deve ser `"command"`.

Ganchos de prompt

Prompt hooks enviam automaticamente o texto como se o usuário tivesse digitado. Elas têm suporte apenas em sessionStart e são acionadas somente para novas sessões interativas. Eles não são acionados na retomada e não são acionados no modo de prompt não interativo (-p). 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"
      }
    ]
  }
}

Campo	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

Event	Acionado quando	A saída foi processada
`agentStop`	O agente principal conclui um turno.	Sim – pode bloquear e forçar a continuação.
`errorOccurred`	Ocorre um erro durante a execução.	No
`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. |

| 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. | | postToolUse | Depois que cada ferramenta for executada com sucesso. | Sim — pode substituir o resultado bem-sucedido (somente ganchos programáticos do SDK). | | 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). | | 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. | | preToolUse | Antes de executar cada ferramenta. | Sim — pode permitir, negar ou modificar. | | sessionEnd | A sessão é encerrada. | No | | sessionStart | Uma sessão nova ou retomada começa. | No | | subagentStart | Um subagente é gerado (antes de ser executado). Retorna additionalContext prefixado ao prompt do subagente. matcher Dá suporte para filtrar pelo nome do agente. | Não — não é possível bloquear a criação. | | subagentStop | Um subagente completa. | Sim – pode bloquear e forçar a continuação. | | userPromptSubmitted | O usuário envia um prompt. | No |

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" | "failure" | "denied" | "error";
        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.

Campo	Valores	Description
`permissionDecision`

          `"allow"`
          `"deny"`, `"ask"` | Se a ferramenta é executada. A saída vazia usa o comportamento padrão. |

          `agentStop`
           / 
          `subagentStop` controle de decisão

Campo	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 de forma programática, especialmente útil no modo de pipe (-p) e em ambientes de CI onde nenhum prompt interativo está disponível.

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:

Campo	Valores	Description
`behavior`

          `"allow"`, `"deny"` | Aprovar ou negar a chamada da ferramenta. |

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.

Nomes de ferramentas para correspondência de hooks

Nome da ferramenta	Description
`ask_user`	Faça uma pergunta esclarecedora ao usuário.
`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).
`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 postToolUseFailure ganchos de comando, sair com código 2 faz com que stderr seja retornado como diretriz de recuperação para o assistente. Falhas de gancho (códigos de saída ou tempos limite diferentes de zero) são registradas e ignoradas– elas nunca bloqueiam a execução do agente.