Hooks de session

hooks permet d’injecter du code dans chaque étape du cycle de vie d’une session Copilot. Vous pouvez ainsi ajouter le contrôle d’exécution d’outils, le journal d’audit, l’enrichissement de prompts, la gestion d’erreurs, etc., sans toucher au cœur de l’implémentation. Il s’agit d’une fonctionnalité distincte des hooks déclaratifs dans les définitions d’agents personnalisés et du chargement des hooks basés sur des fichiers. Pour la configuration par agent, consultez Agents personnalisés.

Découverte des hooks basés sur des fichiers

hookDirectories permet d’indiquer des racines explicites où découvrir des hooks basés sur des fichiers. Cela sert uniquement à la découverte et n’accorde pas à l’agent de permissions générales d’accès aux fichiers. Les racines explicites restent utilisables même si enableConfigDiscovery ou enableFileHooks sont désactivés. Les chemins relatifs sont résolus une seule fois, par rapport au workingDirectory effectif au moment de la spécification.

Omis ou null : les autres sources de découverte ne sont pas modifiées
[] : seules les racines SDK explicites sont effacées

Les réglages de désactivation par source des hooks et les Managed Settings continuent de s’appliquer. enableFileHooks contrôle les hooks de fichiers provenant du dépôt (.github/hooks/ et les racines des paramètres de dépôts de confiance). Il ne désactive ni les hookDirectories explicites ni les hooks de callbacks PHP.

use Revolution\Copilot\Types\SessionConfig;

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

Flux des hooks

Utilisation de base

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} n'est pas autorisé dans cet environnement",
                );
            }

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

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: 'Si nécessaire, explorez les fichiers liés et comparez-les.',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: 'Nouvelle tentative suite à une erreur temporaire du modèle.',
                );
            }

            return null;
        },

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

            return null;
        },
    ),
]);

Hooks disponibles

Hook	Moment de déclenchement	Usages principaux
`onSessionStart`	Début de session (`new` / `resume` / `startup`)	Injection de contexte initial, surcharge de configuration
`onUserPromptSubmitted`	Envoi d’un prompt utilisateur	Enrichissement, expansion de templates, filtrage d’entrée
`onPreToolUse`	Avant l’exécution d’un outil	Autoriser/refuser/demander, modifier les arguments, masquer la sortie
`onPostToolUse`	Après l’exécution d’un outil	Modification du résultat, masquage d’infos sensibles, audit
`onErrorOccurred`	En cas d’erreur pendant la session	Retry, notification, classification
`onSessionEnd`	Fin de session	Nettoyage, métriques, résumé de fin

Renvoyer null maintient le comportement par défaut.

Bloquer un prompt

onUserPromptSubmitted peut refuser un prompt en renvoyant decision: 'block'. En cas de refus, aucun tour du modèle n’est lancé et le message utilisateur n’est pas enregistré. Si vous indiquez reason, son contenu est inclus dans un événement session.warning éphémère avec warningType: "policy_blocked".

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: "Ce prompt n'est pas autorisé.",
        );
    }

    return null;
},

Cas d’usage typiques

1) Contrôle des permissions (Permission control)

Utilisez onPreToolUse en mode allow-list
Les opérations destructrices déclenchent une validation humaine via permissionDecision: 'ask'
Précisez la raison du refus avec permissionDecisionReason
Les noms d’outils candidats se trouvent dans la liste Outils (ex. view, glob, bash)

2) Audit / conformité

Combinez les hooks du cycle de vie pour collecter des événements d’audit
Persistez les données collectées par ID de session

3) Enrichissement du prompt

Ajoutez à additionalContext les infos projet (langage, framework, conventions) via onSessionStart
Développez les raccourcis (/fix, /test) dans onUserPromptSubmitted

4) Filtrage des résultats

Masquez les API keys / tokens / mots de passe dans onPostToolUse
Résumez les résultats trop longs et ne renvoyez le détail qu’à la demande

5) Récupération d’erreur

Dans onErrorOccurred, effectuez un retry uniquement si model_call et recoverable=true
En cas d’erreur non récupérable, notifiez brièvement l’utilisateur via userNotification

6) Métriques de session

Enregistrez l’heure de début dans onSessionStart
Incrémentez les compteurs dans onPreToolUse / onUserPromptSubmitted
Émettez la durée, le nombre d’outils et la raison de fin dans onSessionEnd

Types d’entrée / sortie des hooks

Entrée commune (`BaseHookInput`)

Propriété	Type	Description
`sessionId`	`string`	ID de la session runtime associée. Session enfant pour les hooks d’outils enfants, ID de la session parente pour les hooks de démarrage/arrêt de sous-agent
`timestamp`	`int`	Instant de déclenchement du hook (Unix ms)
`cwd`	`string`	Répertoire de travail courant
`agentId`	`?string`	ID d’acteur du sous-agent qui exécute le hook
`agentType`	`?string`	Type de sous-agent
`parentAgentId`	`?string`	ID de l’acteur parent direct

agentId / agentType / parentAgentId sont disponibles dans les hooks dont l’acteur est un sous-agent. Ils ne sont pas inclus dans les hooks de l’agent racine. Avec les anciens runtimes, les champs eux-mêmes sont omis lorsque l’information est absente. Ils peuvent donc tous valoir null.

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`

Propriété	Type	Description
`toolName`	`string`	Nom de l’outil à exécuter
`toolArgs`	`mixed`	Arguments prévus

`PreToolUseHookOutput`

Propriété	Type	Description
`permissionDecision`	`?string`	`allow` / `deny` / `ask`
`permissionDecisionReason`	`?string`	Raison du refus/de la demande
`modifiedArgs`	`mixed`	Arguments après modification
`additionalContext`	`?string`	Contexte supplémentaire
`suppressOutput`	`?bool`	Masquer la sortie de l’outil

`PostToolUseHookInput`

Propriété	Type	Description
`toolName`	`string`	Nom de l’outil exécuté
`toolArgs`	`mixed`	Arguments utilisés
`toolResult`	`ToolResultObject\|array`	Résultat de l’outil

`PostToolUseHookOutput`

Propriété	Type	Description
`modifiedResult`	`ToolResultObject\|array\|null`	Résultat modifié
`additionalContext`	`?string`	Contexte supplémentaire
`suppressOutput`	`?bool`	Masquer l’affichage du résultat

`UserPromptSubmittedHookInput`

Propriété	Type	Description
`prompt`	`string`	Prompt saisi par l’utilisateur

`UserPromptSubmittedHookOutput`

Propriété	Type	Description
`modifiedPrompt`	`?string`	Prompt modifié
`additionalContext`	`?string`	Contexte complémentaire
`suppressOutput`	`?bool`	Masquer l’affichage de la réponse
`decision`	`?string`	`block` refuse le prompt et empêche le tour du modèle et l’enregistrement du message utilisateur
`reason`	`?string`	Motif du refus. Inclus dans l’événement `session.warning`

`SessionStartHookInput`

Propriété	Type	Description
`source`	`string`	`startup` / `resume` / `new`
`initialPrompt`	`?string`	Prompt initial

`SessionStartHookOutput`

Propriété	Type	Description
`additionalContext`	`?string`	Contexte initial de session
`modifiedConfig`	`?array`	Surcharge partielle de la configuration de session

`SessionEndHookInput`

Propriété	Type	Description
`reason`	`string`	`complete` / `error` / `abort` / `timeout` / `user_exit`
`finalMessage`	`?string`	Message final
`error`	`?string`	Erreur de fin. Si le runtime transmet un objet d’erreur, il s’agit de `message` lorsque c’est une chaîne, sinon de la chaîne JSON de l’objet

`SessionEndHookOutput`

Propriété	Type	Description
`suppressOutput`	`?bool`	Masquer la sortie finale
`cleanupActions`	`?array`	Infos sur le nettoyage effectué
`sessionSummary`	`?string`	Résumé de session

`ErrorOccurredHookInput`

Propriété	Type	Description
`error`	`string`	Message d’erreur. Si le runtime transmet un objet d’erreur, il s’agit de `message` lorsque c’est une chaîne, sinon de la chaîne JSON de l’objet
`errorContext`	`string`	Parmi `model_call` / `tool_execution` / `system` / `user_input`
`recoverable`	`bool`	Récupérable ou non

`ErrorOccurredHookOutput`

Propriété	Type	Description
`suppressOutput`	`?bool`	Masquer l’affichage de l’erreur
`errorHandling`	`?string`	`retry` / `skip` / `abort`
`retryCount`	`?int`	Nombre de tentatives
`userNotification`	`?string`	Notification adressée à l’utilisateur

ToolResultObject

Objet standard représentant le résultat d’exécution d’un outil.

Propriété	Type	Description
`textResultForLlm`	`?string`	Résultat texte à transmettre au LLM
`resultType`	`?string`	`success` / `failure` / `rejected` / `denied`
`resultForAssistant`	`?array`	Données de résultat destinées à l’assistant

Bonnes pratiques

N’exécutez pas trop de traitements synchrones lourds à l’intérieur des hooks. Passez à de l’asynchrone si nécessaire.
Quand aucun changement n’est requis, renvoyez null pour laisser le comportement par défaut.
Explicitez autant que possible permissionDecision.
Ne masquez pas trop les erreurs critiques : conservez des chemins de log/notification.
Gérez l’état par ID de session et nettoyez dans onSessionEnd.

Pour les dernières informations, consultez le dépôt GitHub.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Kits de démarrage

Flux et RSS

Middleware

Hooks de session

Hooks de session

Découverte des hooks basés sur des fichiers

Flux des hooks

Utilisation de base

Hooks disponibles

Bloquer un prompt

Cas d’usage typiques

1) Contrôle des permissions (Permission control)

2) Audit / conformité

3) Enrichissement du prompt

4) Filtrage des résultats

5) Récupération d’erreur

6) Métriques de session

Types d’entrée / sortie des hooks

Entrée commune (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Bonnes pratiques

​Hooks de session

​Découverte des hooks basés sur des fichiers

​Flux des hooks

​Utilisation de base

​Hooks disponibles

​Bloquer un prompt

​Cas d’usage typiques

​1) Contrôle des permissions (Permission control)

​2) Audit / conformité

​3) Enrichissement du prompt

​4) Filtrage des résultats

​5) Récupération d’erreur

​6) Métriques de session

​Types d’entrée / sortie des hooks

​Entrée commune (BaseHookInput)

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​Bonnes pratiques

Hooks de session

Découverte des hooks basés sur des fichiers

Flux des hooks

Utilisation de base

Hooks disponibles

Bloquer un prompt

Cas d’usage typiques

1) Contrôle des permissions (Permission control)

2) Audit / conformité

3) Enrichissement du prompt

4) Filtrage des résultats

5) Récupération d’erreur

6) Métriques de session

Types d’entrée / sortie des hooks

Entrée commune (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Bonnes pratiques