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.
Flux des hooks
Utilisation de base
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 |
null maintient le comportement par défaut.
Cas d’usage typiques
1) Contrôle des permissions (Permission control)
- Utilisez
onPreToolUseen 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 à
additionalContextles infos projet (langage, framework, conventions) viaonSessionStart - Développez les raccourcis (
/fix,/test) dansonUserPromptSubmitted
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 unretryuniquement simodel_calletrecoverable=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 |
|---|---|---|
timestamp | int | Instant de déclenchement du hook (Unix ms) |
cwd | string | Répertoire de travail courant |
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 |
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 |
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 |
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
nullpour 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.