Skip to main content

Hooks de sesión

Con hooks puedes insertar lógica en cada punto del ciclo de vida de una sesión de Copilot.
Puedes añadir control de ejecución de herramientas, log de auditoría, enriquecimiento de prompts, manejo de errores, etc., sin tocar la implementación principal.

Flujo de los hooks

Uso básico

Hooks disponibles

Si devuelves null, se mantiene el comportamiento por defecto.

Casos de uso típicos

1) Permission control (control de ejecución)

  • Convierte las herramientas permitidas en una allow-list con onPreToolUse
  • Para operaciones destructivas, requiere aprobación humana con permissionDecision: 'ask'
  • Explicita el motivo del rechazo con permissionDecisionReason
  • Consulta los posibles toolName en el listado de Tools (por ejemplo view, glob, bash)

2) Auditing / compliance (auditoría)

  • Combina los hooks del ciclo de vida para recolectar eventos de auditoría
  • Persiste los datos recolectados por session ID

3) Prompt enrichment (enriquecer entradas)

  • En onSessionStart añade a additionalContext información del proyecto (lenguaje, framework, convenciones)
  • En onUserPromptSubmitted expande atajos como /fix o /test

4) Result filtering (formatear resultados)

  • En onPostToolUse enmascara API keys, tokens, contraseñas, etc.
  • Resume resultados demasiado largos y devuelve detalles solo cuando sea necesario

5) Error recovery (recuperación ante fallos)

  • En onErrorOccurred, haz retry solo si model_call y recoverable=true
  • Para errores no recuperables, notifica al usuario de forma concisa con userNotification

6) Session metrics (medición)

  • Registra la hora de inicio en onSessionStart
  • Incrementa contadores en onPreToolUse / onUserPromptSubmitted
  • Emite duración, número de herramientas y razón de finalización en onSessionEnd

Tipos de input / output de los hooks

Input común (BaseHookInput)

PreToolUseHookInput

PreToolUseHookOutput

PostToolUseHookInput

PostToolUseHookOutput

UserPromptSubmittedHookInput

UserPromptSubmittedHookOutput

SessionStartHookInput

SessionStartHookOutput

SessionEndHookInput

SessionEndHookOutput

ErrorOccurredHookInput

ErrorOccurredHookOutput

ToolResultObject

Objeto estándar del resultado de ejecución de una herramienta.

Buenas prácticas

  1. No ejecutes directamente en el hook procesos síncronos pesados. Hazlos asíncronos cuando sea necesario.
  2. Cuando no necesites cambiar nada, devuelve null y deja que actúe el comportamiento por defecto.
  3. Explicita permissionDecision siempre que puedas.
  4. No silencies en exceso los errores críticos; ten una vía de log/notificación.
  5. Gestiona el estado por sesión basándote en el session id y límpialo en onSessionEnd.
Consulta la información más reciente en el repositorio de GitHub.
Última modificación el 13 de julio de 2026