Session hooks
Methooks kun je op elk punt in de lifecycle van een Copilot-session eigen logica invoegen.Zo voeg je uitvoeringscontrole voor tools, auditlogs, promptverrijking en foutafhandeling toe zonder de kernimplementatie te wijzigen.
De flow van hooks
Basisgebruik
Beschikbare hooks
Als je
null retourneert, gaat het standaardgedrag gewoon door.
Typische use cases
1) Permission control (uitvoeringscontrole)
- Gebruik
onPreToolUseom toegestane tools via een allow-list te beheren - Laat destructieve operaties met
permissionDecision: 'ask'door een mens goedkeuren - Geef met
permissionDecisionReasonexpliciet de reden van weigering op - Bekijk de mogelijke waarden van
toolNamein het overzicht van Tools (bijv.view,glob,bash)
2) Auditing / compliance
- Combineer lifecycle-hooks om audit-events te verzamelen
- Sla de verzamelde data op per session-ID
3) Prompt enrichment (invoerverrijking)
- Voeg met
onSessionStartprojectinformatie (taal, framework, conventies) toe viaadditionalContext - Vouw met
onUserPromptSubmittedshortcuts uit (/fix,/test)
4) Result filtering (resultaten opschonen)
- Maskeer met
onPostToolUsezaken als API keys, tokens en wachtwoorden - Vat te lange resultaten samen en geef alleen op verzoek details terug
5) Error recovery (foutherstel)
- Voer met
onErrorOccurredalleen eenretryuit bijmodel_callmetrecoverable=true - Informeer bij niet-herstelbare fouten de gebruiker beknopt via
userNotification
6) Session metrics (meten)
- Leg met
onSessionStartde starttijd vast - Werk tellers bij in
onPreToolUse/onUserPromptSubmitted - Rapporteer met
onSessionEndde doorlooptijd, het aantal toolaanroepen en de eindreden
Hook input-/output-types
Gedeelde input (BaseHookInput)
PreToolUseHookInput
PreToolUseHookOutput
PostToolUseHookInput
PostToolUseHookOutput
UserPromptSubmittedHookInput
UserPromptSubmittedHookOutput
SessionStartHookInput
SessionStartHookOutput
SessionEndHookInput
SessionEndHookOutput
ErrorOccurredHookInput
ErrorOccurredHookOutput
ToolResultObject
Het standaardobject voor toolresultaten.Best practices
- Voer zware synchrone verwerking niet direct in een hook uit; maak deze zo nodig asynchroon.
- Retourneer
nullals er niets hoeft te veranderen en laat het standaardgedrag zijn werk doen. - Maak
permissionDecisionwaar mogelijk expliciet. - Onderdruk kritieke fouten niet te veel en zorg voor een log-/notificatiekanaal.
- Beheer sessiestatus op basis van session-ID en ruim op in
onSessionEnd.
Raadpleeg de GitHub-repository voor de meest actuele informatie.