Hooks de sesión
Conhooks 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
toolNameen el listado de Tools (por ejemploview,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
onSessionStartañade aadditionalContextinformación del proyecto (lenguaje, framework, convenciones) - En
onUserPromptSubmittedexpande atajos como/fixo/test
4) Result filtering (formatear resultados)
- En
onPostToolUseenmascara 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, hazretrysolo simodel_callyrecoverable=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
- No ejecutes directamente en el hook procesos síncronos pesados. Hazlos asíncronos cuando sea necesario.
- Cuando no necesites cambiar nada, devuelve
nully deja que actúe el comportamiento por defecto. - Explicita
permissionDecisionsiempre que puedas. - No silencies en exceso los errores críticos; ten una vía de log/notificación.
- 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.