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. Diese Funktion ist unabhängig von deklarativen hooks in Definitionen benutzerdefinierter Agenten und vom Laden dateibasierter Hooks. Für Einstellungen pro Agent siehe Benutzerdefinierte Agenten.

Discovery dateibasierter Hooks

In hookDirectories können Sie explizite Roots angeben, in denen dateibasierte Hooks gesucht werden. Diese dienen nur der Discovery und gewähren dem Agenten keinen allgemeinen Dateizugriff. Explizite Roots sind auch dann nutzbar, wenn enableConfigDiscovery oder enableFileHooks deaktiviert ist. Relative Pfade werden einmalig relativ zu dem workingDirectory aufgelöst, das beim Setzen gilt.

Weggelassen oder null: Andere Discovery-Quellen bleiben unverändert
[]: Entfernt nur die explizit gesetzten SDK-Roots

Deaktivierungseinstellungen für Hook-Quellen und Managed Settings gelten weiterhin. enableFileHooks steuert Datei-Hooks aus dem Repository (.github/hooks/ und Roots aus vertrauenswürdigen Repository-Einstellungen). Explizite hookDirectories und PHP-Callback-hooks werden dadurch nicht deaktiviert.

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    workingDirectory: '/workspace/project',
    enableFileHooks: false,
    hookDirectories: ['../shared-hooks'],
);

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.

Prompts blockieren

onUserPromptSubmitted kann einen Prompt ablehnen, indem es decision: 'block' zurückgibt. Bei einer Ablehnung wird kein Modell-Turn gestartet und auch keine User-Nachricht aufgezeichnet. Wenn Sie reason angeben, wird der Inhalt in ein temporäres session.warning-Event mit warningType: "policy_blocked" aufgenommen.

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: 'Dieser Prompt ist nicht erlaubt.',
        );
    }

    return null;
},

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
`sessionId`	`string`	ID der zugehörigen Runtime-Session. Bei Hooks von Kind-Tools die Kind-Session, bei Start-/Stopp-Hooks von Subagenten die ID der Eltern-Session
`timestamp`	`int`	Zeitpunkt der Hook-Auslösung (Unix ms)
`cwd`	`string`	Aktuelles Arbeitsverzeichnis
`agentId`	`?string`	Akteur-ID des Subagenten, der den Hook ausführt
`agentType`	`?string`	Typ des Subagenten
`parentAgentId`	`?string`	Akteur-ID des direkten Elternteils

agentId / agentType / parentAgentId sind in Hooks verfügbar, deren Akteur ein Subagent ist. In Hooks des Root-Agenten sind sie nicht enthalten. Ältere Runtimes lassen die Felder ganz weg, wenn keine Informationen vorliegen. Daher können alle drei null sein.

onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
    if ($input->agentId !== null) {
        logger()->info('Subagent tool use', [
            'agentId' => $input->agentId,
            'agentType' => $input->agentType,
            'parentAgentId' => $input->parentAgentId,
            'tool' => $input->toolName,
        ]);
    }

    return null;
},

`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
`decision`	`?string`	`block` lehnt den Prompt ab und verhindert den Modell-Turn sowie die Aufzeichnung der User-Nachricht
`reason`	`?string`	Ablehnungsgrund. Wird in das `session.warning`-Event aufgenommen

`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. Übergibt die Runtime ein Fehlerobjekt, wird dessen `message` verwendet, sofern es ein String ist, andernfalls der JSON-String des Objekts

`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. Übergibt die Runtime ein Fehlerobjekt, wird dessen `message` verwendet, sofern es ein String ist, andernfalls der JSON-String des Objekts
`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 null zurück und überlassen den Standardablauf.
Setzen Sie permissionDecision mö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 onSessionEnd auf.

Aktuelle Informationen finden Sie im GitHub-Repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds und RSS

Middleware

Session-Hooks

Session-Hooks

Discovery dateibasierter Hooks

Ablauf der Hooks

Grundlegende Verwendung

Verfügbare Hooks

Prompts blockieren

Typische Anwendungsfälle

1) Berechtigungssteuerung (Ausführungskontrolle)

2) Auditing / Compliance

3) Prompt-Anreicherung

4) Ergebnisfilterung

5) Fehler-Recovery

6) Session-Metriken

Hook-Input-/Output-Typen

Gemeinsame Eingabe (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Best Practices

​Session-Hooks

​Discovery dateibasierter Hooks

​Ablauf der Hooks

​Grundlegende Verwendung

​Verfügbare Hooks

​Prompts blockieren

​Typische Anwendungsfälle

​1) Berechtigungssteuerung (Ausführungskontrolle)

​2) Auditing / Compliance

​3) Prompt-Anreicherung

​4) Ergebnisfilterung

​5) Fehler-Recovery

​6) Session-Metriken

​Hook-Input-/Output-Typen

​Gemeinsame Eingabe (BaseHookInput)

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​Best Practices

Session-Hooks

Discovery dateibasierter Hooks

Ablauf der Hooks

Grundlegende Verwendung

Verfügbare Hooks

Prompts blockieren

Typische Anwendungsfälle

1) Berechtigungssteuerung (Ausführungskontrolle)

2) Auditing / Compliance

3) Prompt-Anreicherung

4) Ergebnisfilterung

5) Fehler-Recovery

6) Session-Metriken

Hook-Input-/Output-Typen

Gemeinsame Eingabe (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Best Practices