Session-Hooks
Mithooks können Sie sich in die einzelnen Lebenszyklusphasen einer Copilot-Session einklinken.
Tool-Ausführungssteuerung, Audit-Logs, Prompt-Anreicherung, Fehlerbehandlung usw. lassen sich hinzufügen, ohne die Kernimplementierung zu ändern.
Ablauf der Hooks
Grundlegende Verwendung
Verfügbare Hooks
| Hook | Auslösezeitpunkt | Hauptanwendung |
|---|---|---|
onSessionStart | Session-Start (new / resume / startup) | Initialen Kontext einspeisen, Konfiguration überschreiben |
onUserPromptSubmitted | Beim Senden eines User-Prompts | Prompt anreichern, Templates expandieren, Eingabefilter |
onPreToolUse | Vor der Tool-Ausführung | Zulassen/Verweigern/Nachfragen, Argumente ändern, Ausgabe unterdrücken |
onPostToolUse | Nach der Tool-Ausführung | Ergebnisse verändern, sensible Informationen maskieren, Audit-Log |
onErrorOccurred | Bei Fehlern in der Session | Retry, Benachrichtigungen, Fehlerklassifizierung |
onSessionEnd | Bei Session-Ende | Cleanup, Metriken, Abschluss-Zusammenfassung |
null zurückgegeben, läuft das Standardverhalten weiter.
Typische Anwendungsfälle
1) Berechtigungssteuerung (Ausführungskontrolle)
- Zulassene Tools per Allow-List über
onPreToolUse - Destruktive Operationen mit
permissionDecision: 'ask'menschlich freigeben lassen - Über
permissionDecisionReasonden Ablehnungsgrund explizit machen - Kandidaten für
toolNamefinden Sie in der Liste unter Tools (z. B.view,glob,bash)
2) Auditing / Compliance
- Audit-Ereignisse durch Kombination der Lebenszyklus-Hooks sammeln
- Gesammelte Daten pro Session-ID persistieren
3) Prompt-Anreicherung
- In
onSessionStartProjektinformationen (Sprache, Framework, Konventionen) viaadditionalContextergänzen - In
onUserPromptSubmittedShortcuts (/fix,/test) expandieren
4) Ergebnisfilterung
- In
onPostToolUseAPI-Keys / Tokens / Passwörter maskieren - Zu lange Ergebnisse zusammenfassen und Details nur bei Bedarf ausgeben
5) Fehler-Recovery
- In
onErrorOccurrednur beimodel_callundrecoverable=trueeinenretryausführen - Nicht wiederherstellbare Fälle über
userNotificationknapp an den Nutzer melden
6) Session-Metriken
- In
onSessionStartdie Startzeit erfassen - In
onPreToolUse/onUserPromptSubmittedZähler aktualisieren - In
onSessionEndDauer, Anzahl der Tool-Aufrufe und Abschlussgrund ausgeben
Hook-Input-/Output-Typen
Gemeinsame Eingabe (BaseHookInput)
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
timestamp | int | Zeitpunkt der Hook-Auslösung (Unix ms) |
cwd | string | Aktuelles Arbeitsverzeichnis |
PreToolUseHookInput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
toolName | string | Name des einzusetzenden Tools |
toolArgs | mixed | Übergebene Argumente |
PreToolUseHookOutput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
permissionDecision | ?string | allow / deny / ask |
permissionDecisionReason | ?string | Grund für Ablehnung/Rückfrage |
modifiedArgs | mixed | Überschriebene Argumente |
additionalContext | ?string | Zusätzlicher Kontext |
suppressOutput | ?bool | Tool-Ausgabe unterdrücken |
PostToolUseHookInput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
toolName | string | Name des ausgeführten Tools |
toolArgs | mixed | Verwendete Argumente |
toolResult | ToolResultObject|array | Ergebnis des Tools |
PostToolUseHookOutput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
modifiedResult | ToolResultObject|array|null | Geändertes Ergebnis |
additionalContext | ?string | Zusätzlicher Kontext |
suppressOutput | ?bool | Ergebnisausgabe unterdrücken |
UserPromptSubmittedHookInput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
prompt | string | Vom Nutzer eingegebener Prompt |
UserPromptSubmittedHookOutput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
modifiedPrompt | ?string | Modifizierter Prompt |
additionalContext | ?string | Ergänzender Kontext |
suppressOutput | ?bool | Antwortdarstellung unterdrücken |
SessionStartHookInput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
source | string | startup / resume / new |
initialPrompt | ?string | Initialer Prompt |
SessionStartHookOutput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
additionalContext | ?string | Initialer Session-Kontext |
modifiedConfig | ?array | Teilweise Überschreibung der Session-Konfiguration |
SessionEndHookInput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
reason | string | complete / error / abort / timeout / user_exit |
finalMessage | ?string | Letzte Nachricht |
error | ?string | Fehler zum Endzeitpunkt |
SessionEndHookOutput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
suppressOutput | ?bool | Finale Ausgabe unterdrücken |
cleanupActions | ?array | Informationen zu durchgeführten Cleanup-Aktionen |
sessionSummary | ?string | Zusammenfassung der Session |
ErrorOccurredHookInput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
error | string | Fehlermeldung |
errorContext | ?string | Einer von model_call / tool_execution / system / user_input |
recoverable | bool | Ob wiederherstellbar |
ErrorOccurredHookOutput
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
suppressOutput | ?bool | Fehleranzeige unterdrücken |
errorHandling | ?string | retry / skip / abort |
retryCount | ?int | Anzahl der Wiederholungen |
userNotification | ?string | Meldungstext an den Nutzer |
ToolResultObject
Standard-Objekt für Tool-Ausführungsergebnisse.| Eigenschaft | Typ | Beschreibung |
|---|---|---|
textResultForLlm | ?string | An das LLM übergebenes Textergebnis |
resultType | ?string | success / failure / rejected / denied |
resultForAssistant | ?array | Ergebnisdaten für den Assistenten |
Best Practices
- Führen Sie schwere synchrone Verarbeitung nicht direkt im Hook aus. Bei Bedarf asynchron auslagern.
- Wenn keine Änderung nötig ist, geben Sie
nullzurück und überlassen den Standardablauf. - Setzen Sie
permissionDecisionmöglichst explizit. - Unterdrücken Sie kritische Fehler nicht zu stark – halten Sie Log-/Notification-Pfade offen.
- Verwalten Sie Session-bezogenen Zustand auf Basis der Session-ID und räumen Sie ihn in
onSessionEndauf.
Aktuelle Informationen finden Sie im GitHub-Repository.