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. Dit is een andere functie dan de declaratieve hooks in de definitie van een custom agent en het laden van file-based hooks. Zie Custom agents voor configuratie per agent.

File-based hooks detecteren

Met hookDirectories geef je expliciete roots op waarin file-based hooks worden gedetecteerd. Dit dient alleen voor detectie en geeft de agent geen algemene toegangsrechten tot bestanden. Expliciete roots zijn ook bruikbaar als enableConfigDiscovery of enableFileHooks is uitgeschakeld. Relatieve paden worden eenmalig opgelost ten opzichte van de effectieve workingDirectory op het moment van opgeven.

Weglaten of null: andere detectiebronnen blijven ongewijzigd
[]: alleen de expliciet opgegeven SDK-roots worden gewist

Instellingen die hookbronnen uitschakelen en Managed Settings blijven van toepassing. enableFileHooks regelt file hooks uit de repository (.github/hooks/ en roots uit vertrouwde repository-instellingen). Expliciete hookDirectories en hooks met PHP-callbacks worden hiermee niet uitgeschakeld.

use Revolution\Copilot\Types\SessionConfig;

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

De flow van hooks

Basisgebruik

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: 'Vat de belangrijkste punten van de README samen');
    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: 'Los de huidige fouten op en vat de wijzigingen samen.',
                );
            }

            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} is niet toegestaan in deze omgeving",
                );
            }

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

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: 'Verken indien nodig ook gerelateerde bestanden en vergelijk ze.',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: 'Er wordt opnieuw geprobeerd vanwege een tijdelijke modelfout.',
                );
            }

            return null;
        },

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

            return null;
        },
    ),
]);

Beschikbare hooks

Hook	Wanneer afgevuurd	Belangrijkste toepassingen
`onSessionStart`	Start van de session (`new` / `resume` / `startup`)	Initiële context injecteren, configuratie overschrijven
`onUserPromptSubmitted`	Bij het versturen van een gebruikersprompt	Promptverrijking, templates uitvouwen, invoerfilters
`onPreToolUse`	Vóór het uitvoeren van een tool	Toestaan/weigeren/bevestiging vragen, argumenten aanpassen, output onderdrukken
`onPostToolUse`	Ná het uitvoeren van een tool	Resultaten aanpassen, gevoelige informatie maskeren, auditlogs
`onErrorOccurred`	Bij een fout binnen de session	Retries, notificaties, foutclassificatie
`onSessionEnd`	Bij het einde van de session	Opruimen, metrics, eindsamenvatting

Als je null retourneert, gaat het standaardgedrag gewoon door. Een losse session eindigt niet wanneer het antwoord op een prompt klaar is. onSessionEnd wordt niet per prompt uitgevoerd, maar wanneer de session wordt verbroken of vernietigd.

Prompts blokkeren

onUserPromptSubmitted kan een prompt weigeren door decision: 'block' te retourneren. Bij weigering start er geen model-turn en wordt het gebruikersbericht ook niet vastgelegd. Als je reason opgeeft, wordt die inhoud opgenomen in een tijdelijk session.warning-event met warningType: "policy_blocked".

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: 'Deze prompt is niet toegestaan.',
        );
    }

    return null;
},

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`)

Property	Type	Beschrijving
`sessionId`	`string`	ID van de betreffende runtime-session. Bij hooks van child-tools de child-session, bij start/stop-hooks van subagents de ID van de parent-session
`timestamp`	`int`	Tijdstip waarop de hook is afgevuurd (Unix ms)
`cwd`	`string`	Huidige werkdirectory
`agentId`	`?string`	Actor-ID van de subagent die de hook uitvoert
`agentType`	`?string`	Type subagent
`parentAgentId`	`?string`	Actor-ID van de directe parent

agentId / agentType / parentAgentId zijn beschikbaar in hooks waarbij een subagent de actor is. Ze worden niet meegegeven in hooks van de root-agent. Oudere runtimes laten de velden helemaal weg als de informatie ontbreekt. Daarom kunnen ze allemaal null zijn.

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`

Property	Type	Beschrijving
`toolName`	`string`	Naam van de uit te voeren tool
`toolArgs`	`mixed`	Argumenten van de uit te voeren tool

`PreToolUseHookOutput`

Property	Type	Beschrijving
`permissionDecision`	`?string`	`allow` / `deny` / `ask`
`permissionDecisionReason`	`?string`	Reden bij weigering/bevestiging
`modifiedArgs`	`mixed`	Overschreven argumenten
`additionalContext`	`?string`	Aanvullende context
`suppressOutput`	`?bool`	Onderdruk de tool-output

`PostToolUseHookInput`

Property	Type	Beschrijving
`toolName`	`string`	Naam van de uitgevoerde tool
`toolArgs`	`mixed`	Argumenten bij uitvoering
`toolResult`	`ToolResultObject\|array`	Toolresultaat

`PostToolUseHookOutput`

Property	Type	Beschrijving
`modifiedResult`	`ToolResultObject\|array\|null`	Aangepast resultaat
`additionalContext`	`?string`	Aanvullende context
`suppressOutput`	`?bool`	Onderdruk het tonen van het toolresultaat

`UserPromptSubmittedHookInput`

Property	Type	Beschrijving
`prompt`	`string`	Door de gebruiker ingevoerde prompt

`UserPromptSubmittedHookOutput`

Property	Type	Beschrijving
`modifiedPrompt`	`?string`	Aangepaste prompt
`additionalContext`	`?string`	Aanvullende context
`suppressOutput`	`?bool`	Onderdruk het tonen van de respons
`decision`	`?string`	Met `block` weiger je de prompt en voorkom je de model-turn en het vastleggen van het gebruikersbericht
`reason`	`?string`	Reden van de weigering. Wordt opgenomen in het `session.warning`-event

`SessionStartHookInput`

Property	Type	Beschrijving
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	Initiële prompt

`SessionStartHookOutput`

Property	Type	Beschrijving
`additionalContext`	`?string`	Initiële context van de session
`modifiedConfig`	`?array`	Gedeeltelijke overschrijving van de sessieconfiguratie

`SessionEndHookInput`

Property	Type	Beschrijving
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	Laatste bericht
`error`	`?string`	Fout bij het beëindigen. Als de runtime een error-object doorgeeft: de waarde van `message` als dat een string is, anders de JSON-string van het object

`SessionEndHookOutput`

Property	Type	Beschrijving
`suppressOutput`	`?bool`	Onderdruk de laatste output
`cleanupActions`	`?array`	Informatie over uitgevoerde opruimacties
`sessionSummary`	`?string`	Samenvatting van de session

`ErrorOccurredHookInput`

Property	Type	Beschrijving
`error`	`string`	Foutmelding. Als de runtime een error-object doorgeeft: de waarde van `message` als dat een string is, anders de JSON-string van het object
`errorContext`	`string`	Een van `model_call` / `tool_execution` / `system` / `user_input`
`recoverable`	`bool`	Of herstel mogelijk is

`ErrorOccurredHookOutput`

Property	Type	Beschrijving
`suppressOutput`	`?bool`	Onderdruk het tonen van de fout
`errorHandling`	`?string`	`retry` / `skip` / `abort`
`retryCount`	`?int`	Aantal retries
`userNotification`	`?string`	Melding aan de gebruiker

ToolResultObject

Het standaardobject voor toolresultaten.

Property	Type	Beschrijving
`textResultForLlm`	`?string`	Tekstresultaat dat aan de LLM wordt doorgegeven
`resultType`	`?string`	`success` / `failure` / `rejected` / `denied`
`resultForAssistant`	`?array`	Resultaatdata voor de assistent

Best practices

Voer zware synchrone verwerking niet direct in een hook uit; maak deze zo nodig asynchroon.
Retourneer null als er niets hoeft te veranderen en laat het standaardgedrag zijn werk doen.
Maak permissionDecision waar 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.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds en RSS

Middleware

Session hooks

Session hooks

File-based hooks detecteren

De flow van hooks

Basisgebruik

Beschikbare hooks

Prompts blokkeren

Typische use cases

1) Permission control (uitvoeringscontrole)

2) Auditing / compliance

3) Prompt enrichment (invoerverrijking)

4) Result filtering (resultaten opschonen)

5) Error recovery (foutherstel)

6) Session metrics (meten)

Hook input-/output-types

Gedeelde input (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Best practices

​Session hooks

​File-based hooks detecteren

​De flow van hooks

​Basisgebruik

​Beschikbare hooks

​Prompts blokkeren

​Typische use cases

​1) Permission control (uitvoeringscontrole)

​2) Auditing / compliance

​3) Prompt enrichment (invoerverrijking)

​4) Result filtering (resultaten opschonen)

​5) Error recovery (foutherstel)

​6) Session metrics (meten)

​Hook input-/output-types

​Gedeelde input (BaseHookInput)

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​Best practices

Session hooks

File-based hooks detecteren

De flow van hooks

Basisgebruik

Beschikbare hooks

Prompts blokkeren

Typische use cases

1) Permission control (uitvoeringscontrole)

2) Auditing / compliance

3) Prompt enrichment (invoerverrijking)

4) Result filtering (resultaten opschonen)

5) Error recovery (foutherstel)

6) Session metrics (meten)

Hook input-/output-types

Gedeelde input (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Best practices