Referencia de ganchos de la CLI de GitHub Copilot

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 archivos de configuración de hook se cargan automáticamente desde .github/hooks/*.json de tu repositorio.

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 `bash`/`powershell`	Comando shell para Unix.
`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 `bash`/`powershell`	Comando shell para Windows.
`timeoutSec`	número	No	Tiempo de espera en segundos. Valor predeterminado: `30`.
`type`	`"command"`	Sí	Debe ser `"command"`.

Ganchos de activación

Los ganchos de solicitud envían automáticamente texto como si lo hubiera escrito el usuario. Se admiten únicamente en sessionStart y se ejecutan solo para nuevas sesiones interactivas. No se activan en la reanudación y no se activan en modo de aviso no interactivo (-p). 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

Evento	Se activa cuando	Salida procesada
`agentStop`	El agente principal finaliza un turno.	Sí: puede bloquear y forzar la continuación.
`errorOccurred`	Se produce un error durante la ejecución.	No
`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.
`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.
`postToolUse`	Una vez que cada herramienta haya completado su tarea correctamente.	Sí: puede reemplazar el resultado exitoso (solo hooks programáticos del SDK).
`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).
`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.
`preToolUse`	Antes de que se ejecute cada herramienta.	Sí: puede permitir, denegar o modificar.
`sessionEnd`	La sesión finaliza.	No
`sessionStart`	Comienza una sesión nueva o reanudada.	No
`subagentStart`	Se genera un subagente (antes de que se ejecute). Devuelve `additionalContext` antepuesto al mensaje del subagente. Admite `matcher` para filtrar por nombre del agente.	No: no se puede bloquear la creación.
`subagentStop`	Se completa un subagente.	Sí: puede bloquear y forzar la continuación.
`userPromptSubmitted`	El usuario envía una sugerencia.	No

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

          `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 (-p) y entornos de CI en los que no haya ninguna solicitud interactiva disponible.

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

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.

          **Salida:**

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

Nombres de herramientas para la coincidencia de ganchos

Nombre de la herramienta	Description
`ask_user`	Pregunte al usuario una pregunta aclarante.
`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).
`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. En postToolUseFailure el caso de los enlaces de comandos, salir con código 2 hace que stderr se devuelva como guía de recuperación para el asistente. Los errores de enlace (códigos de salida distintos de cero o tiempos de espera) se registran y omiten; nunca bloquean la ejecución del agente.