Skip to main content

Session hooks

Met hooks 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 onPreToolUse om toegestane tools via een allow-list te beheren
  • Laat destructieve operaties met permissionDecision: 'ask' door een mens goedkeuren
  • Geef met permissionDecisionReason expliciet de reden van weigering op
  • Bekijk de mogelijke waarden van toolName in 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 onSessionStart projectinformatie (taal, framework, conventies) toe via additionalContext
  • Vouw met onUserPromptSubmitted shortcuts uit (/fix, /test)

4) Result filtering (resultaten opschonen)

  • Maskeer met onPostToolUse zaken als API keys, tokens en wachtwoorden
  • Vat te lange resultaten samen en geef alleen op verzoek details terug

5) Error recovery (foutherstel)

  • Voer met onErrorOccurred alleen een retry uit bij model_call met recoverable=true
  • Informeer bij niet-herstelbare fouten de gebruiker beknopt via userNotification

6) Session metrics (meten)

  • Leg met onSessionStart de starttijd vast
  • Werk tellers bij in onPreToolUse / onUserPromptSubmitted
  • Rapporteer met onSessionEnd de 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

  1. Voer zware synchrone verwerking niet direct in een hook uit; maak deze zo nodig asynchroon.
  2. Retourneer null als er niets hoeft te veranderen en laat het standaardgedrag zijn werk doen.
  3. Maak permissionDecision waar mogelijk expliciet.
  4. Onderdruk kritieke fouten niet te veel en zorg voor een log-/notificatiekanaal.
  5. Beheer sessiestatus op basis van session-ID en ruim op in onSessionEnd.
Raadpleeg de GitHub-repository voor de meest actuele informatie.
Laatst gewijzigd op 6 september 2026