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
| Hook | Momento en el que se dispara | Uso principal |
|---|---|---|
onSessionStart | Inicio de sesión (new / resume / startup) | Inyectar contexto inicial, sobreescribir configuración |
onUserPromptSubmitted | Al enviar un prompt del usuario | Enriquecer el prompt, expandir plantillas, filtrar entradas |
onPreToolUse | Antes de ejecutar una herramienta | Permitir / denegar / requerir confirmación, modificar argumentos, silenciar salida |
onPostToolUse | Después de ejecutar una herramienta | Modificar resultados, enmascarar información sensible, log de auditoría |
onErrorOccurred | Al producirse un error en la sesión | Reintentar, notificar, clasificar el error |
onSessionEnd | Al terminar la sesión | Limpieza, métricas, resumen final |
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)
| Propiedad | Tipo | Descripción |
|---|---|---|
timestamp | int | Momento en que se disparó el hook (Unix ms) |
cwd | string | Directorio de trabajo actual |
PreToolUseHookInput
| Propiedad | Tipo | Descripción |
|---|---|---|
toolName | string | Nombre de la herramienta que se va a ejecutar |
toolArgs | mixed | Argumentos previstos |
PreToolUseHookOutput
| Propiedad | Tipo | Descripción |
|---|---|---|
permissionDecision | ?string | allow / deny / ask |
permissionDecisionReason | ?string | Motivo del rechazo o confirmación |
modifiedArgs | mixed | Argumentos sobreescritos |
additionalContext | ?string | Contexto adicional |
suppressOutput | ?bool | Silencia la salida de la herramienta |
PostToolUseHookInput
| Propiedad | Tipo | Descripción |
|---|---|---|
toolName | string | Nombre de la herramienta ejecutada |
toolArgs | mixed | Argumentos utilizados |
toolResult | ToolResultObject|array | Resultado de la herramienta |
PostToolUseHookOutput
| Propiedad | Tipo | Descripción |
|---|---|---|
modifiedResult | ToolResultObject|array|null | Resultado modificado |
additionalContext | ?string | Contexto adicional |
suppressOutput | ?bool | Silencia la visualización del resultado |
UserPromptSubmittedHookInput
| Propiedad | Tipo | Descripción |
|---|---|---|
prompt | string | Prompt introducido por el usuario |
UserPromptSubmittedHookOutput
| Propiedad | Tipo | Descripción |
|---|---|---|
modifiedPrompt | ?string | Prompt modificado |
additionalContext | ?string | Contexto complementario |
suppressOutput | ?bool | Silencia la visualización de la respuesta |
SessionStartHookInput
| Propiedad | Tipo | Descripción |
|---|---|---|
source | string | startup / resume / new |
initialPrompt | ?string | Prompt inicial |
SessionStartHookOutput
| Propiedad | Tipo | Descripción |
|---|---|---|
additionalContext | ?string | Contexto inicial de la sesión |
modifiedConfig | ?array | Sobreescritura parcial de la configuración de la sesión |
SessionEndHookInput
| Propiedad | Tipo | Descripción |
|---|---|---|
reason | string | complete / error / abort / timeout / user_exit |
finalMessage | ?string | Mensaje final |
error | ?string | Error en el momento de la finalización |
SessionEndHookOutput
| Propiedad | Tipo | Descripción |
|---|---|---|
suppressOutput | ?bool | Silencia la salida final |
cleanupActions | ?array | Información de las acciones de limpieza realizadas |
sessionSummary | ?string | Resumen de la sesión |
ErrorOccurredHookInput
| Propiedad | Tipo | Descripción |
|---|---|---|
error | string | Mensaje de error |
errorContext | ?string | Uno de model_call / tool_execution / system / user_input |
recoverable | bool | Si es recuperable |
ErrorOccurredHookOutput
| Propiedad | Tipo | Descripción |
|---|---|---|
suppressOutput | ?bool | Silencia la visualización del error |
errorHandling | ?string | retry / skip / abort |
retryCount | ?int | Número de reintentos |
userNotification | ?string | Texto de notificación al usuario |
ToolResultObject
Objeto estándar del resultado de ejecución de una herramienta.| Propiedad | Tipo | Descripción |
|---|---|---|
textResultForLlm | ?string | Resultado en texto que se pasa al LLM |
resultType | ?string | success / failure / rejected / denied |
resultForAssistant | ?array | Datos del resultado para el assistant |
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.