referencia de enlaces de GitHub Copilot

Introducción

Los enlaces son comandos externos que se ejecutan en puntos de ciclo de vida específicos durante una sesión, lo que permite la automatización personalizada, los controles de seguridad y las integraciones.

Los hooks se admiten en dos Copilot superficies: CLI de Copilot y agente en la nube de Copilot. La mayoría de las cargas de eventos y formato de configuración son idénticas, pero el entorno de ejecución y el conjunto de eventos que pueden desencadenarse difieren.

A lo largo de este artículo, el comportamiento que difiere entre las dos superficies se menciona en las notas "solo de la CLI" y "solo del agente en la nube". Todo lo que no esté marcado se aplica a ambos.

Ubicaciones de ganchos

Las ubicaciones en las que se ejecutan los hooks y dónde puede almacenar los archivos de configuración de los hooks dependen de la superficie.

• **CLI de Copilot ** — los ganchos se ejecutan en la máquina local del desarrollador en el mismo shell que la CLI. La CLI admite todos los eventos de enlace descritos en este artículo.

  Los enlaces se cargan desde los siguientes orígenes en orden (usuario, luego proyecto, complementos) y se combinan. Cuando aparece el mismo evento en varios orígenes, se ejecutan todas las entradas de enlace de todos los orígenes.

  • Archivos de hook a nivel de repositorio — .github/hooks/*.json en la raíz del repositorio.
  • Archivos de 'hook' de nivel de usuario: *.json archivos en el directorio de 'hooks' de nivel de usuario. De forma predeterminada, es ~/.copilot/hooks/ en macOS y Linux, o %USERPROFILE%\.copilot\hooks\ en Windows. Si COPILOT_HOME está establecido, es $COPILOT_HOME/hooks/.
  • Bloque insertado hooks en la configuración del repositorio : el hooks campo en el nivel superior de .github/copilot/settings.json (Git confirmado) o .github/copilot/settings.local.json (normalmente gitignored y específico del usuario) en el repositorio. .claude/settings.json También se leen archivos y .claude/settings.local.json herramientas cruzadas en el repositorio.
  • Bloque en línea hooks en la configuración de nivel de usuario — el hooks campo en el nivel superior de ~/.copilot/settings.json.
  • Enlaces aportados por complementos instalados : declarados por cada complemento en su propio hooks.json (o en hooks/hooks.json) dentro del directorio de instalación del complemento.

• **agente en la nube de Copilot ** — los hooks se ejecutan dentro del espacio aislado de Linux efímero que el agente en la nube aprovisiona para cada trabajo. El entorno de pruebas no es interactivo, tiene una red limitada y se destruye cuando finaliza la tarea. Se desencadena un subconjunto de eventos, y solo se respetan las entradas bash (o command).

  La configuración de enlace se carga desde .github/hooks/*.json archivos en el repositorio clonado.

Entorno de ejecución del agente en la nube

Esta sección solo se aplica a agente en la nube de Copilot. Describe las restricciones que afectan a cómo escribir scripts de enlace y configurar entradas de enlace para trabajos del agente en la nube.

Propiedad	Value
Sistema operativo	Linux. Solo se respeta el bash campo en los ganchos de comando, powershell las entradas se omiten. El campo multiplataforma command se utiliza como alternativa.
Directorio de trabajo

          `/workspace` cuando se clona un repositorio; de lo contrario `/root`, . Use esta ruta de acceso al establecer `cwd` en una entrada de enlace o al hacer referencia a archivos desde un script. |

| Filesystem | Efímero. Los archivos escritos por enlaces (registros, CSV, transcripciones) se descartan cuando finaliza el trabajo. Para conservar la salida del hook, envíela a través de una http entrada de hook. | | Red saliente | Restringido por el firewall del agente en la nube. De forma predeterminada, solo se puede acceder a los nombres de host GitHub y Copilot; el alcance de cualquier otro host (por ejemplo, https://hooks.example.com) requiere una regla de permiso de firewall configurada por el administrador. | | Variables de entorno disponibles | GITHUB_COPILOT_API_TOKEN y GITHUB_COPILOT_GIT_TOKEN están configurados en el espacio aislado. COPILOT_AGENT_PROMPT contiene el aviso/la solicitud con el que se invocó el trabajo. HOME se establece en /root, por lo que cualquier hook script que resuelve las rutas de acceso ~/... escribe en el espacio aislado efímero. GITHUB_TOKEN no está establecido. | | Interactividad | Totalmente no interactivo. El agente se ejecuta con todos los permisos de herramienta concedidos previamente, por lo que no se muestran diálogos de permisos y no se muestra ninguna notificación a un usuario. | | Detección de configuración | En un trabajo de agente de la nube, la única configuración de hook que existe de forma predeterminada está .github/hooks/*.json dentro del repositorio clonado. El sandbox no se incluye con archivos de enlace de nivel de usuario, settings.json, config.json, o complementos instalados. |

Formato de configuración de gancho

Los archivos de configuración de enlace usan el formato JSON con la versión 1.

Ganchos de comando

Los ganchos de comando ejecutan scripts de shell y son compatibles con todos los 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	Obligatorio	Description
bash	string	Uno de estos valores: bash, powershell o command	Comando shell para Unix.
command	string	Uno de estos valores: bash, powershell o command	Recurso de respaldo multiplataforma que se usa cuando no se establece ni bash ni powershell para la plataforma actual.
cwd	string	No	Directorio de trabajo para el comando (relativo a la raíz del repositorio o absoluto).
env	object	No	Variables de entorno que se van a establecer (admite la expansión de variables).
powershell	string	Uno de estos valores: bash, powershell o command	Comando shell para Windows.
timeoutSec	número	No	Tiempo de espera en segundos. Valor predeterminado: 30.
type	"command"	Sí	Debe ser "command".

Ganchos HTTP

Los enlaces HTTP envían la carga de entrada como JSON POST a una dirección URL.

{
  "version": 1,
  "hooks": {
    "postToolUse": [
      {
        "type": "http",
        "url": "https://hooks.example.com/copilot",
        "headers": { "X-Source": "copilot-cli" },
        "allowedEnvVars": ["GITHUB_TOKEN"],
        "timeoutSec": 30
      }
    ]
  }
}

Campo	Tipo	Obligatorio	Description
allowedEnvVars	string[]	No	Nombres de variables de entorno que se pueden expandir dentro de los valores de headers. Cuando se establece, url debe usar https://.
headers	object	No	Solicitar encabezados que se van a incluir.
timeoutSec	número	No	Tiempo de espera en segundos. Valor predeterminado: 30.
type	"http"	Sí	Debe ser "http".
url	string	Sí	Dirección URL de destino. Debe usar http: o https:. Para preToolUse y permissionRequest, debe usar https:// porque la respuesta puede conceder permisos de herramienta.

Ganchos de activación

Los ganchos de solicitud envían automáticamente texto como si lo hubiera escrito el usuario. Solo se admiten en sessionStart. El texto puede ser un indicador de lenguaje natural o un comando de barra.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

Campo	Tipo	Obligatorio	Description
type	"prompt"	Sí	Debe ser "prompt".
prompt	string	Sí	Texto que se va a enviar: puede ser un mensaje en lenguaje natural o un comando de barra.

Eventos de enlace

En la tabla siguiente se enumeran todos los eventos admitidos. La columna agente en la nube muestra si el evento se ejecuta en el agente en la nube y señala cualquier diferencia de comportamiento.

Event	Se activa cuando	Salida procesada	Agente en la nube
agentStop	El agente principal finaliza un turno.	Sí: puede bloquear y forzar la continuación.	Fuegos.

          `decision: "block"` fuerza otro turno, que sigue contando contra el tiempo de espera del trabajo. |

| errorOccurred | Se produce un error durante la ejecución. | No | Fuegos. | | notification | Se desencadena de forma asincrónica cuando la CLI emite una notificación del sistema (finalización del shell, finalización del agente o inactividad, notificaciones de permisos, diálogos de solicitud). Fire-and-forget: nunca bloquea la sesión. Admite matcher regex en notification_type. | Opcional: puede insertar additionalContext en la sesión. | No se activa. El agente en la nube no muestra notificaciones a un usuario (consulte la fila Interactivity en la tabla del entorno de ejecución del agente en la nube anterior). | | permissionRequest | Se desencadena antes de que el servicio de permisos se ejecute (motor de reglas, aprobaciones de sesión, permitir o denegar automáticamente y solicitudes al usuario). Si la salida del enlace combinado es behavior: "allow" o "deny", esa decisión interrumpe el flujo normal de permisos. Admite matcher regex en toolName. | Sí: puede permitir o denegar mediante programación. | Las llamadas a herramientas se aprueban previamente, por lo que este enlace no se activa o no tiene ningún efecto. Use preToolUse para tomar decisiones de permisos en su lugar. | | postToolUse | Una vez que cada herramienta haya completado su tarea correctamente. | No | Fuegos. | | postToolUseFailure | Después de que una herramienta finalice con un error. | Sí — puede proporcionar instrucciones de recuperación a través de additionalContext (código 2 de salida para ganchos de comandos). | Fuegos. | | preCompact | La compactación de contexto está a punto de comenzar (manual o automática). Admite matcher para filtrar por desencadenador ("manual" o "auto"). | No: solo notificación. | Solo se activa con trigger: "auto". No hay ningún usuario para solicitar la compactación manual. | | preToolUse | Antes de que se ejecute cada herramienta. | Sí: puede permitir, denegar o modificar. | Fuegos. Una decisión de "ask" se trata como "deny" porque ningún usuario está disponible para responder. | | sessionEnd | La sesión finaliza. | No | Se activa una vez por tarea. reason es normalmente "complete", "error" o "timeout", "abort" y "user_exit" no se esperan puesto que no hay ningún usuario. | | sessionStart | Comienza una sesión nueva o reanudada. | Opcional: puede insertar additionalContext en la sesión. | Se activa una vez por trabajo, como una nueva sesión (no una reanudación). Consulte la nota de los ganchos del aviso anterior para ver el comportamiento de las entradas prompt en el agente de nube. | | subagentStart | Se genera un subagente (antes de que se ejecute). Admite matcher para filtrar por nombre del agente. | Opcional: no se puede bloquear la creación, pero additionalContext se antepone al prompt del subagente. | Fuegos. | | subagentStop | Se completa un subagente. | Sí: puede bloquear y forzar la continuación. | Fuegos. | | userPromptSubmitted | El usuario envía una sugerencia. | No | Se activa como máximo una vez, para la instrucción asociada al trabajo. No hay ninguna entrada de usuario de seguimiento. |

Cargas de entrada de eventos de enlace

Cada evento de enlace entrega una carga JSON al controlador de enlace. Se admiten dos formatos de carga, seleccionados por el nombre de evento usado en la configuración del enlace:

• formato camelCase : configure el nombre del evento en camelCase (por ejemplo, sessionStart). Los campos emplean el formato camelCase.
• VS Code formato compatible : configure el nombre del evento en PascalCase (por ejemplo, SessionStart). Los campos usan snake_case para coincidir con el formato de extensión 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 compatible:**

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

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

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

Cuando se configura con el nombre del evento PreToolUse PascalCase, la carga utiliza nombres de campo snake_case para que coincidan con el formato de extensión 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 compatible:**

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

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

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

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

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

{
    hook_event_name: "PreCompact";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    trigger: "manual" | "auto";
    custom_instructions: string;
}

preToolUse control de decisión

El gancho preToolUse puede controlar la ejecución de la herramienta escribiendo un objeto JSON en la salida estándar (stdout).

Campo	Valores	Description
permissionDecision

          `"allow"`, `"deny"`, `"ask"` | Si se ejecuta la herramienta. La salida vacía usa el comportamiento predeterminado. En el agente en la nube, `"ask"` se trata como `"deny"` porque no hay ningún usuario disponible para responder. |

| permissionDecisionReason | string | Motivo que se muestra al agente. Obligatorio cuando la decisión es "deny". | | modifiedArgs | object | Sustituya los argumentos de la herramienta para usar en lugar de los originales. |

agentStop

           / 
          `subagentStop` control de decisión

Campo	Valores	Description
decision

          `"block"`, `"allow"` | 
          `"block"` obliga a otro agente a realizar un turno usando `reason` como solicitud. |

| reason | string | Solicite el siguiente turno cuando decision sea "block". |

permissionRequest control de decisión

El permissionRequest enlace se activa antes de que se ejecute el servicio de permisos, antes de las comprobaciones de reglas, las aprobaciones de sesión, la autorización automática o la denegación automática y la solicitud del usuario. Si los enlaces devuelven behavior: "allow" o "deny", esa decisión cortocircuita el flujo de permisos normal. No devolver nada conduce al manejo normal de permisos. Úselo para aprobar o denegar llamadas a herramientas mediante programación, especialmente útiles en el modo de canalización de la CLI (-p) y otros usos de CI de la CLI en los que no haya ninguna solicitud interactiva disponible. No se aplica al agente en la nube.

Todos los ganchos configurados permissionRequest se ejecutan para cada solicitud (excepto las clases de permiso read y hook, que se cortocircuitan antes de los ganchos). Las salidas de enlace se combinan con salidas de enlace posteriores que reemplazan a las anteriores.

          **Comparador:** Expresión regular opcional probada en `toolName`. Anclado como `^(?:pattern)$`; debe coincidir con el nombre completo de la herramienta. Cuando se establece, el gancho se activa solo para los nombres de herramientas coincidentes.

Genera JSON en stdout para controlar la decisión de permisos:

Campo	Valores	Description
behavior

          `"allow"`, `"deny"` | Aprobar o denegar la llamada a la herramienta. |

| message | string | Motivo comunicado al LLM cuando se rechaza. | | interrupt | boolean | Cuando true se combina con "deny", detiene completamente el agente. |

Devuelve una salida vacía o {} para pasar por el flujo de permisos normal. En el caso de los ganchos de comandos, el código de salida 2 se trata como deny; stdout JSON (si existe) se combina con {"behavior":"deny"}, y se ignora stderr.

notification gancho

El notification gancho se dispara de forma asincrónica cuando la CLI emite una notificación de sistema. Estos enlaces se activan y olvidan: nunca bloquean la sesión y se registran y omiten los errores.

          **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 notificación:**

Tipo	Cuando se activa
shell_completed	Un comando de shell en segundo plano (asincrónico) ha finalizado.
shell_detached_completed	Se completa una sesión de shell desconectada
agent_completed	Un subagente en segundo plano finaliza (completado o fallido)
agent_idle	Un agente en segundo plano finaliza un turno y entra en estado inactivo (esperando write_agent)
permission_prompt	El agente solicita permiso para ejecutar una herramienta.
elicitation_dialog	El agente solicita información adicional del usuario.

          **Output:**

{
    additionalContext?: string; // Injected into the session as a user message
}

Si additionalContext se devuelve, el texto se inserta en la sesión como mensaje de usuario antepuesto. Esto puede desencadenar el procesamiento adicional del agente si la sesión está inactiva. Devuelve {} o una salida vacía para no realizar ninguna acción.

          **Buscador de coincidencias:** Regex opcional en `notification_type`. El patrón está anclado como `^(?:pattern)$`. 
          `matcher` Omitir para recibir todos los tipos de notificación.

Filtrado del buscador de coincidencias

Varios eventos aceptan una expresión regular opcional matcher en cada entrada de gancho que filtra las invocaciones para las que el gancho se activa. El patrón está anclado como ^(?:matcher)$ y debe coincidir con el valor completo. Las expresiones regulares no válidas hacen que se omita la entrada del gancho.

| Event | matcher se compara con | |-------|------------------------------| | notification | notification_type | | permissionRequest | toolName | | preCompact | trigger ("manual" o "auto") | | preToolUse | toolName | | subagentStart | agentName |

Nombres de herramientas para la coincidencia de ganchos

Nombre de la herramienta	Description
ask_user	Pregunte al usuario una pregunta aclarante. En el agente en la nube no hay ningún usuario, por lo que ask_user no genera un resultado útil.
bash	Ejecute comandos de shell (Unix).
create	Cree nuevos archivos.
edit	Modifique el contenido del archivo.
glob	Buscar archivos por patrón.
grep	Buscar contenido del archivo.
powershell	Ejecute comandos de shell (Windows). No aparece en el agente de nube (zona de pruebas de Linux).
task	Ejecutar tareas de subagentes.
view	Leer el contenido del archivo.
web_fetch	Capturar páginas web.

Si se configuran varios ganchos del mismo tipo, se ejecutan en orden. Para preToolUse, si algún gancho devuelve "deny", la herramienta se bloquea. Los errores de enlace (códigos de salida distintos de 2, o tiempos de espera) se registran y omiten; nunca bloquean la ejecución del agente.

Códigos de salida para enlaces de comandos

Código de salida	Meaning
0	Éxito.

          `stdout` se analiza como JSON de salida del hook si está presente. |

| 2 | Se trata como una advertencia de forma predeterminada. stderr se muestra al usuario, pero la ejecución continúa. Para permissionRequest, exit 2 se considera como {"behavior":"deny"} y cualquier stdout JSON se fusiona. Para postToolUseFailure, exit 2 se trata como additionalContext y stdout se agrega al error que se muestra al agente. | | Otros que no son cero | Se registra como un error de enlace. La ejecución continúa (no se puede abrir). |

Deshabilitar todos los ganchos

Use disableAllHooks cuando quiera mantener la configuración del hook en el disco, pero evitar que se ejecute, por ejemplo:

• Estás depurando un problema y deseas confirmar que un gancho es el responsable sin eliminar la configuración.

• Pausar la automatización durante una tarea confidencial (una revisión de código, una rama de versión, trabajar con secretos) sin perder la configuración. (CLI de Copilot solo).)

• Envíe un archivo de hooks en el repositorio de control de código fuente del que los colaboradores puedan excluirse localmente configurando la opción en su repositorio settings.json. (CLI de Copilot solo).)

• Silenciar temporalmente los enlaces lentos o ruidosos durante una sesión interactiva. (CLI de Copilot solo).)

          `disableAllHooks` Establezca `true` al nivel más alto para omitir todos los enlaces del archivo sin eliminarlo.
  

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

El comportamiento depende de dónde establezca la marca:

• Dentro de un único .github/hooks/*.json archivo solo se omiten los ganchos declarados en ese archivo. Honrado tanto por CLI de Copilot como por agente en la nube de Copilot.
• En el nivel superior del repositorio settings.json — CLI de Copilot sólo. Todos los enlaces de cada origen (archivos de repositorio, archivos de usuario, complementos y bloques de enlace insertados) se omiten para las sesiones de ese repositorio. El agente en la nube no carga settings.json.

Lectura adicional

• Uso de enlaces con CLI de GitHub Copilot
• referencia de enlaces de GitHub Copilot
• Referencia de comandos de la CLI de GitHub Copilot
• Conceptos para el agente de la nube de GitHub Copilot