Session-Hooks

Klinken Sie sich mit SessionHooks in den Lebenszyklus einer Copilot-Session ein und implementieren Sie Ausführungssteuerung, Auditing und Recovery-Logik.

​

Session-Hooks

Mit hooks 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

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionHooks;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookInput;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookOutput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\SessionEndHookInput;
use Revolution\Copilot\Types\Hooks\SessionEndHookOutput;
use Revolution\Copilot\Types\Hooks\SessionStartHookInput;
use Revolution\Copilot\Types\Hooks\SessionStartHookOutput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookInput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookOutput;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'READMEの要点をまとめて');
    dump($response->content());
}, config: [
    'model' => 'gpt-5',
    'hooks' => new SessionHooks(
        onSessionStart: function (SessionStartHookInput $input): ?SessionStartHookOutput {
            return new SessionStartHookOutput(
                additionalContext: "Project root: {$input->cwd}",
            );
        },

        onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
            if (str_starts_with($input->prompt, '/fix')) {
                return new UserPromptSubmittedHookOutput(
                    modifiedPrompt: '現在のエラーを修正して、変更点を要約して。',
                );
            }

            return null;
        },

        onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
            $blocked = ['bash', 'shell', 'delete_file'];

            if (in_array($input->toolName, $blocked, true)) {
                return new PreToolUseHookOutput(
                    permissionDecision: 'deny',
                    permissionDecisionReason: "{$input->toolName} はこの環境では許可されていません",
                );
            }

            return new PreToolUseHookOutput(permissionDecision: 'allow');
        },

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: '必要なら関連ファイルも探索して比較してください。',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: '一時的なモデルエラーのためリトライします。',
                );
            }

            return null;
        },

        onSessionEnd: function (SessionEndHookInput $input): ?SessionEndHookOutput {
            if ($input->reason !== 'complete') {
                return new SessionEndHookOutput(
                    sessionSummary: "Session ended with reason: {$input->reason}",
                );
            }

            return null;
        },
    ),
]);

​

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

Wird 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 permissionDecisionReason den Ablehnungsgrund explizit machen
• Kandidaten für toolName finden 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 onSessionStart Projektinformationen (Sprache, Framework, Konventionen) via additionalContext ergänzen
• In onUserPromptSubmitted Shortcuts (/fix, /test) expandieren

​

4) Ergebnisfilterung

• In onPostToolUse API-Keys / Tokens / Passwörter maskieren
• Zu lange Ergebnisse zusammenfassen und Details nur bei Bedarf ausgeben

​

5) Fehler-Recovery

• In onErrorOccurred nur bei model_call und recoverable=true einen retry ausführen
• Nicht wiederherstellbare Fälle über userNotification knapp an den Nutzer melden

​

6) Session-Metriken

• In onSessionStart die Startzeit erfassen
• In onPreToolUse / onUserPromptSubmitted Zähler aktualisieren
• In onSessionEnd Dauer, 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

1. Führen Sie schwere synchrone Verarbeitung nicht direkt im Hook aus. Bei Bedarf asynchron auslagern.
2. Wenn keine Änderung nötig ist, geben Sie null zurück und überlassen den Standardablauf.
3. Setzen Sie permissionDecision möglichst explizit.
4. Unterdrücken Sie kritische Fehler nicht zu stark – halten Sie Log-/Notification-Pfade offen.
5. Verwalten Sie Session-bezogenen Zustand auf Basis der Session-ID und räumen Sie ihn in onSessionEnd auf.

Aktuelle Informationen finden Sie im GitHub-Repository.