{"meta":{"title":"Références sur les hooks GitHub Copilot","intro":"Rechercher des événements de hook, des formats de configuration et des charges utiles d’entrée pour les hooks dans Copilot CLI et Copilot cloud agent.","product":"GitHub Copilot","breadcrumbs":[{"href":"/fr/copilot","title":"GitHub Copilot"},{"href":"/fr/copilot/reference","title":"Informations de référence"},{"href":"/fr/copilot/reference/hooks-reference","title":"Référence des hooks"}],"documentType":"article"},"body":"# Références sur les hooks GitHub Copilot\n\nRechercher des événements de hook, des formats de configuration et des charges utiles d’entrée pour les hooks dans Copilot CLI et Copilot cloud agent.\n\n## Présentation\n\nLes hooks sont des commandes externes qui s’exécutent à des points de cycle de vie spécifiques pendant une session, ce qui permet l’automatisation personnalisée, les contrôles de sécurité et les intégrations.\n\nLes hooks sont pris en charge dans deux surfaces Copilot : Copilot CLI et Copilot cloud agent. La plupart des charges utiles du format de configuration et des événements sont identiques, mais l’environnement d’exécution et l’ensemble d’événements pouvant être déclenchés diffèrent.\n\nTout au long de cet article, le comportement qui diffère entre les deux surfaces est indiqué dans les notes « CLI uniquement » et « Agent Cloud uniquement ». Tout ce qui n’est pas marqué s’applique aux deux.\n\n## Emplacements de crochets\n\nLes emplacements où les hooks s’exécutent et où vous pouvez stocker les fichiers de configuration de hooks dépendent de la surface :\n\n* **Copilot CLI** — les hooks s’exécutent sur l’ordinateur local du développeur dans le même interpréteur de commandes que l’interface CLI. Tous les événements de hook décrits dans cet article sont pris en charge par la CLI.\n\n Les hooks sont chargés à partir des sources suivantes dans l’ordre (stratégie, utilisateur, projet, plug-ins) et combinés. Lorsque le même événement apparaît dans plusieurs sources, toutes les entrées de hook de toutes les sources sont exécutées.\n\n * **Fichiers de hook au niveau de la stratégie** : fichiers JSON dans le répertoire de stratégie approprié à la plateforme, chargés par ordre alphabétique. Les hooks de stratégie s’appliquent à toute la machine et sont chargés avant tous les autres hooks. Ils ne peuvent pas être désactivés par `disableAllHooks` et sont disponibles quel que soit l’état d’approbation du dossier. Consultez [les hooks de stratégie](#policy-hooks) ci-dessous.\n * **Fichiers de hook au niveau du référentiel** , `.github/hooks/*.json` dans la racine du référentiel.\n * **Fichiers de hook au niveau de l’utilisateur** : `*.json` fichiers dans le répertoire des hooks au niveau de l’utilisateur. Par défaut, il s’agit de `~/.copilot/hooks/` sur macOS et Linux, ou `%USERPROFILE%\\.copilot\\hooks\\` sur Windows. Si `COPILOT_HOME` est définie, c’est `$COPILOT_HOME/hooks/`.\n * **Bloc inline `hooks` dans les paramètres du référentiel** : le champ `hooks` au niveau supérieur de `.github/copilot/settings.json` (validé dans Git) ou `.github/copilot/settings.local.json` (généralement ignoré par Git et spécifique à l’utilisateur) dans le référentiel. Les fichiers croisés `.claude/settings.json` et `.claude/settings.local.json` dans le référentiel sont également lus.\n * **Bloc inline `hooks` dans la configuration** au niveau de l’utilisateur : le champ `hooks` au niveau supérieur de `~/.copilot/settings.json`.\n * **Crochets contribués par les plug-ins installés** : déclarés par chaque plug-in dans son propre `hooks.json` (ou sous `hooks/hooks.json`) à l’intérieur du répertoire d’installation du plug-in.\n\n* **Copilot cloud agent** — les hooks s’exécutent à l’intérieur du bac à sable Linux éphémère que l’agent cloud provisionne pour chaque tâche. Le bac à sable est non interactif, a un réseau contraint et est détruit lorsque le travail se termine. Un sous-ensemble d’événements se déclenche, et seules les entrées `bash` (ou `command`) sont prises en compte.\n\n La configuration du hook est chargée depuis des fichiers `.github/hooks/*.json` dans le référentiel cloné.\n\n### Points d’extension de stratégie\n\n> \\[!NOTE]\n> **Copilot CLI Seulement.** Les hooks de stratégie ne sont pas pris en charge sous Copilot cloud agent.\n\nLes hooks de stratégie sont des hooks à l’échelle de l’ordinateur chargés par les administrateurs. Ils sont chargés avant tous les autres hooks et ne peuvent pas être désactivés par `disableAllHooks`.\n\nLes points d’ancrage de politique sont identifiés à partir de deux sources :\n\n* **Système de fichiers** : fichiers JSON dans le répertoire de stratégie propre à la plateforme, chargés par ordre alphabétique :\n * Linux/macOS : `/etc/github-copilot/policy.d/*.json`\n * Windows : `C:\\ProgramData\\GitHub\\Copilot\\policy.d\\*.json`\n* **Windows Registre** : valeurs sous `HKLM\\Software\\Policies\\GitHub\\Copilot` (chaque sous-clé contient une valeur `Policy` REG\\_SZ contenant un document de stratégie JSON).\n\nLes fichiers de hook de stratégie utilisent le même format de configuration des hooks que les hooks utilisateur et de projet (`{ \"version\": 1, \"hooks\": { ... } }`). Sur les systèmes POSIX, les fichiers de stratégie doivent être détenus par la racine et ne doivent pas être groupables ou accessibles en écriture mondiale.\n\nLes hooks de stratégie sont destinés à être utilisés par les administrateurs informatiques d’entreprise et nécessitent des privilèges élevés à installer. Les utilisateurs finaux ne peuvent pas les modifier.\n\n## Environnement d’exécution de l’agent cloud\n\nCette section s’applique à **Copilot cloud agent** uniquement. Il décrit les contraintes qui affectent la façon dont vous écrivez des scripts de hook et configurez des entrées de hook pour les travaux de l’agent cloud.\n\n| Propriété | Valeur |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Système d'exploitation | Linux. Seul le `bash` champ des crochets de commande est respecté ; les entrées `powershell` sont ignorées. Le champ multiplateforme `command` est utilisé comme solution de repli. |\n| Répertoire de travail | |\n| `/workspace` lorsqu’un référentiel est cloné ; sinon `/root`. Utilisez ce chemin lors de la définition `cwd` d’une entrée de hook ou lors du référencement de fichiers à partir d’un script. | |\n| Filesystem | Éphémère. Les fichiers écrits par des hooks (journaux, CSV, transcriptions) sont supprimés lorsque le travail se termine. Pour conserver la sortie du hook, envoyez-la via une entrée de hook `http`. |\n| Réseau sortant | Restreint par le pare-feu de l’agent cloud. Par défaut, seuls les noms d’hôte GitHub et Copilot sont accessibles ; l’accès à tout autre hôte (par exemple, `https://hooks.example.com`) nécessite une règle d’autorisation de pare-feu configurée par l’administrateur. |\n| Variables d’environnement disponibles | |\n| `GITHUB_COPILOT_API_TOKEN` et `GITHUB_COPILOT_GIT_TOKEN` sont configurés dans le bac à sable. | |\n| `COPILOT_AGENT_PROMPT` contient la requête avec laquelle la tâche a été invoquée. | |\n| `HOME` est défini sur `/root`, de sorte que tout script de hook qui résout des chemins `~/...` écrit dans le bac à sable éphémère. | |\n| `GITHUB_TOKEN` n’est pas défini. | |\n| Interactivité | Entièrement non interactif. L’agent s’exécute avec toutes les autorisations d’outil pré-accordées, donc aucune boîte de dialogue d’autorisation n’est affichée et aucune notification n’est exposée à un utilisateur. |\n| Découverte de la configuration | Dans une tâche d’agent cloud, la seule configuration de hook qui existe par défaut se trouve `.github/hooks/*.json` à l’intérieur du référentiel cloné. Le bac à sable n’est pas fourni avec des fichiers de hook de niveau utilisateur, `settings.json`, `config.json`, ou des extensions installées. |\n\n## Format de configuration des hooks\n\nLes fichiers de configuration de hook utilisent le format JSON avec la version `1`.\n\n> \\[!NOTE]\n> Si un fichier de configuration de hook chargé à partir d’un répertoire (par exemple, `.github/hooks/`) contient un hook mal formé, seul cet élément est ignoré et consigné dans le journal ; les hooks homologues valides du même fichier sont quand même chargés. Les erreurs structurelles (JSON non valide, un mauvais `version`ou une liste d’événements non matricielle) rejettent toujours l’intégralité du fichier. Les hooks définis en ligne dans `settings.json` restent stricts : toute erreur de validation au niveau d’un élément rejette l’intégralité du champ `hooks`. D’autres fichiers de configuration se chargent toujours indépendamment.\n\n### Crochets de commande\n\nLes commandes hook exécutent des scripts shell et sont prises en charge pour tous les types de hook.\n\n> \\[!NOTE]\n> **Agent cloud uniquement.** L'agent cloud exécute des hooks dans un environnement sandbox Linux. Seul le `bash` champ est respecté ; `powershell` les entrées sont ignorées. Le champ multiplateforme `command` est utilisé comme solution de repli.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"preToolUse\": [\n {\n \"type\": \"command\",\n \"bash\": \"YOUR_BASH_COMMAND\",\n \"powershell\": \"YOUR_POWERSHELL_COMMAND\",\n \"cwd\": \"OPTIONAL/WORKING/DIRECTORY\",\n \"env\": { \"VAR\": \"VALUE\" },\n \"timeoutSec\": 30\n }\n ]\n }\n}\n```\n\n| Champ | Type | Obligatoire | Description |\n| ------------ | ----------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `bash` | string | Valeurs possibles : `bash`, `powershell` ou `command` | Commande Shell pour Unix. |\n| `command` | string | Valeurs possibles : `bash`, `powershell` ou `command` | Solution de repli multiplateforme. Copié à la fois dans `bash` et `powershell` lorsque ces champs sont absents ; les entrées explicites dans `bash` ou `powershell` prévalent sur leurs plateformes respectives. |\n| `cwd` | string | Non | Répertoire de travail pour la commande (relatif à la racine du référentiel ou absolu). |\n| `env` | Objet | Non | Variables d’environnement à définir (prend en charge l’expansion des variables). |\n| `powershell` | string | Valeurs possibles : `bash`, `powershell` ou `command` | Commande Shell pour Windows. |\n| `timeout` | Numéro | Non | Alias de `timeoutSec`, en secondes. Utilisé uniquement lorsqu’il `timeoutSec` est absent ; `timeoutSec` est prioritaire lorsque les deux sont présents. |\n| `timeoutSec` | Numéro | Non | Délai d’expiration en secondes. Valeur par défaut : `30`. |\n| `type` | `\"command\"` | Non | Type de crochet. La valeur par défaut est `\"command\"` lorsqu’elle est omise. |\n\n#### Messages de progression\n\nLes hooks de commande peuvent envoyer des lignes d’état d’avancement dans la chronologie de la CLI pendant leur exécution. Écrivez un `{\"type\": \"progress\", \"message\": \"...\"}` objet JSON dans stdout avant d’écrire la sortie finale :\n\n```bash\necho '{\"type\": \"progress\", \"message\": \"Checking policy...\"}'\n# ... perform work ...\necho '{\"permissionDecision\": \"allow\"}'\n```\n\nDéfinir `\"temporary\": true` pour émettre une ligne d’état temporaire. Une ligne temporaire remplace la ligne temporaire précédente et est effacée lorsque l’Assistant répond, au lieu d’accumuler dans la chronologie :\n\n```bash\necho '{\"type\": \"progress\", \"message\": \"Routing...\", \"temporary\": true}'\necho '{\"type\": \"progress\", \"message\": \"Thinking...\", \"temporary\": true}'\n# ... perform work ...\necho '{\"permissionDecision\": \"allow\"}'\n```\n\nLes messages de progression sont affichés uniquement et n’affectent pas la sortie du hook ou la logique de décision.\n\n**Comment stdout est analysé lorsque des messages de progression s’y mêlent.** — La CLI analyse la sortie standard ligne par ligne pendant l’exécution du hook. Toute ligne qui, après suppression des espaces superflus, consiste en un seul objet JSON complet contenant `\"type\": \"progress\"` est interprétée comme un événement de progression et **supprimée du flux de sortie du hook**. Toutes les autres lignes ( lignes vides, texte brut et objets JSON qui ne sont pas des messages de progression) sont conservées en détail. Lorsque le hook se termine, les lignes conservées sont concaténées, rognées et analysées avec un seul `JSON.parse` appel : ce résultat est la sortie du hook (le « JSON de sortie de hook » référencé ailleurs dans cet article). Cela signifie :\n\n* L’émission de lignes de progression en même temps qu’un objet de décision final (comme dans les exemples ci-dessus) est sécurisée et est le modèle prévu : les lignes de progression n’atteignent jamais l’analyseur JSON.\n* Chaque message de progression doit se trouver sur sa propre ligne et doit être json valide sur cette seule ligne. Les objets de progression sur plusieurs lignes ou avec mise en forme ne sont pas reconnus comme des indicateurs de progression et resteront dans le flux de sortie, ce qui provoquera probablement l’échec du `JSON.parse` final.\n* L’objet de décision final, en revanche, peut s’étendre sur plusieurs lignes — seule la *reconnaissance* de la progression se fait ligne par ligne ; ce qui reste après suppression des informations de progression est analysé comme un seul document JSON, et non comme du JSON délimité par des sauts de ligne.\n* Si la sortie restante est vide, ou ne peut pas être analysée comme du JSON, le hook est considéré comme n’ayant produit aucune sortie, et le comportement par défaut est alors appliqué. Deux objets JSON de non-progression ou davantage sur stdout (par exemple, deux appels à `echo '{\"permissionDecision\": ...}'`) seront donc concaténés en un JSON non valide et ignorés — émettez exactement un seul objet de décision final.\n\n### Hooks HTTP\n\nLes hooks HTTP envoient la charge utile d’entrée en tant que JSON `POST` à une URL.\n\n> \\[!NOTE]\n>\n> * Par défaut, seules `https://` les URL sont autorisées. Les requêtes non-TLS `http://` sont rejetées, à l’exception de `http://localhost`, `http://127.*`et `http://[::1]` quand `COPILOT_HOOK_ALLOW_LOCALHOST=1` elles sont définies.\n> *\n\n**Agent cloud uniquement.** Le réseau sortant depuis le bac à sable est limité par le pare-feu de l'agent cloud, donc `url` doit cibler un hôte autorisé.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"postToolUse\": [\n {\n \"type\": \"http\",\n \"url\": \"https://hooks.example.com/copilot\",\n \"headers\": { \"X-Source\": \"copilot-cli\" },\n \"allowedEnvVars\": [\"GITHUB_TOKEN\"],\n \"timeoutSec\": 30\n }\n ]\n }\n}\n```\n\n| Champ | Type | Obligatoire | Description |\n| ---------------- | ----------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `allowedEnvVars` | chaîne de caractères\\[] | Non | Noms de variables d’environnement qui peuvent être développés à l’intérieur des `headers` valeurs. Quand elle est définie, `url` doit utiliser `https://`. |\n| `headers` | Objet | Non | En-têtes de demande à inclure. |\n| `timeout` | Numéro | Non | Alias de `timeoutSec`, en secondes. Utilisé uniquement lorsqu’il `timeoutSec` est absent ; `timeoutSec` est prioritaire lorsque les deux sont présents. |\n| `timeoutSec` | Numéro | Non | Délai d’expiration en secondes. Valeur par défaut : `30`. |\n| `type` | `\"http\"` | Oui | Doit être `\"http\"`. |\n| `url` | string | Oui | URL cible. Doit utiliser `http:` ou `https:`. Pour `preToolUse` et `permissionRequest`, doit utiliser `https://` , car la réponse peut accorder des autorisations d’outil. |\n\n### Crochets d’invite\n\nLes déclencheurs automatiques soumettent le texte comme si l'utilisateur l'avait tapé. Ils ne sont pris en charge que sur `sessionStart`. Le texte peut être une invite en langage naturel ou une commande barre oblique.\n\n> \\[!NOTE]\n> **Copilot CLI Seulement.** Les crochets d’invite se déclenchent uniquement pour les **nouvelles sessions interactives**. Ils ne se déclenchent pas lors de la reprise et ne se déclenchent pas en mode d’invite non interactif (`-p`).\n\n> \\[!NOTE]\n> **Cloud Agent.** Les tâches d’agent cloud s’exécutent de manière non interactive (comme pour `-p`), par conséquent il est possible que les entrées de hook `prompt` ne se déclenchent pas. Confirmez le comportement dans votre environnement avant de vous y fier.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"sessionStart\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"YOUR_PROMPT_TEXT_OR_SLASH_COMMAND\"\n }\n ]\n }\n}\n```\n\n| Champ | Type | Obligatoire | Description |\n| -------- | ---------- | ----------- | ------------------------------------------------------------------------------------------- |\n| `type` | `\"prompt\"` | Oui | Doit être `\"prompt\"`. |\n| `prompt` | string | Oui | Texte à soumettre : il peut s'agir d'un message en langage naturel ou d'une commande slash. |\n\n## Événements de hook\n\nLe tableau ci-dessous répertorie chaque événement pris en charge. La colonne **Agent Cloud** indique si l’événement se déclenche sous un agent cloud et note les différences de comportement.\n\n| Événement | Se déclenche quand | Sortie traitée | Agent de cloud |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `agentStop` | L’agent principal termine un tour. | Oui : peut bloquer et forcer la continuation. | Incendies. |\n| `decision: \"block\"` force un autre tour d’exécution, qui est toujours comptabilisé dans le délai d’expiration de la tâche. | | | |\n| `errorOccurred` | Une erreur se produit pendant l’exécution. | Non | Incendies. |\n| `notification` | S’active de manière asynchrone lorsque l’interface CLI émet une notification système (fin d’exécution de l’interpréteur de commande, achèvement ou inactivité de l’agent, demandes d’autorisation, boîtes de dialogue interactives). Fire-and-forget : ne bloque jamais la session. Prend en charge une expression régulière `matcher` (la valeur du champ `matcher`) sur `notification_type`. | Facultatif — possibilité d'injecter `additionalContext` dans la session. | |\n| **Ne se déclenche pas.** L’agent cloud n’affiche pas les notifications à un utilisateur (consultez la ligne **Interactivité** dans le tableau d’environnement d’exécution de l’agent cloud ci-dessus). | | | |\n| `permissionRequest` | Se déclenche avant que le service d’autorisation ne s'exécute (moteur de règles, approbations de session, autorisation automatique/refus automatique et invitation de l'utilisateur). Si la sortie fusionnée du hook renvoie `behavior: \"allow\"` ou `\"deny\"`, cette décision court-circuite le flux normal d’autorisation, sauf dans le cas d’une demande de contournement du bac à sable (`requestSandboxBypass: true`), où un `allow` ne préautorise pas la sortie et seule la valeur `deny` est propagée (voir l’exception de contournement du bac à sable dans le [`permissionRequest` contrôle des décisions](#permissionrequest-decision-control)). Prend en charge une expression régulière `matcher` (la valeur du champ `matcher`) sur `toolName`. | Oui : peut autoriser ou refuser par programme. | Les appels d’outils sont pré-approuvés, donc ce hook ne s’exécute pas ou n’a aucun effet. Utilisez `preToolUse` pour prendre des décisions d’autorisation au lieu de cela. |\n| `postToolUse` | Après que chaque outil ait terminé avec succès. | Oui : peut modifier le résultat de l’outil ou injecter un contexte supplémentaire pour le modèle. | Incendies. |\n| `postToolUseFailure` | Suite à l’échec d’un outil. | Oui : peut fournir des conseils de récupération via `additionalContext` (code `2` de sortie pour les hooks de commande). | Incendies. |\n| `preCompact` | Le compactage de contexte est sur le point de commencer (manuel ou automatique). Prend en charge un motif regex `matcher` (la valeur du champ `matcher`) pour filtrer selon le déclencheur (`\"manual\"` ou `\"auto\"`). | Non : notification uniquement. | Se déclenche uniquement avec `trigger: \"auto\"`. Il n’existe aucun utilisateur pour demander un compactage manuel. |\n| `preToolUse` | Avant l’exécution de chaque outil. | Oui : peut autoriser, refuser ou modifier. | Incendies. La décision `\"ask\"` est traitée comme `\"deny\"` car aucun utilisateur n’est disponible pour répondre. |\n| `sessionEnd` | La session se termine. | Non | Se déclenche une fois par tâche. |\n| `reason` est généralement `\"complete\"`, `\"error\"` ou `\"timeout\"`; `\"abort\"` et `\"user_exit\"` ne sont pas attendus, car il n'y a pas d'utilisateur. | | | |\n| `sessionStart` | Une session nouvelle ou reprise commence. | Facultatif — possibilité d'injecter `additionalContext` dans la session. | Se déclenche une fois par tâche, en tant que nouvelle session (et non une reprise). Consultez la note sur les hooks de requête ci-dessus pour connaître le comportement des entrées `prompt` sous l’agent cloud. |\n| `subagentStart` | Un sous-agent est initié (avant son exécution). Prend en charge un `matcher` modèle regex (la valeur du `matcher` champ) pour filtrer par nom d’agent. | Facultatif : impossible de bloquer la création, mais `additionalContext` est ajouté avant la requête du sous-agent. | Incendies. |\n| `subagentStop` | Un sous-assistant termine son exécution. | Oui : peut bloquer et forcer la continuation. | Incendies. |\n| `userPromptSubmitted` | L’utilisateur envoie une invite. | Facultatif :`modifiedPrompt` est respecté uniquement par les hooks programmatiques du SDK. | S’exécute au maximum une fois, pour la requête spécifiée pour la tâche. Il n’existe aucune entrée utilisateur de suivi. |\n| `userPromptTransformed` | Se déclenche après que le runtime a transformé un prompt soumis en contenu destiné au modèle, juste avant que ce contenu soit généré et enregistré dans l’historique de session. S’exécute pour le message initial et pour chaque message précédent dans une soumission par lot. Mutation uniquement : il peut réécrire le contenu reçu par le modèle, mais pas bloquer ou gérer le tour. Les notifications système ne le déclenchent jamais. | Oui — on peut réécrire le contenu destiné au modèle. | Incendies. |\n\n## Charges utiles d’entrée associées aux événements de hook\n\nChaque événement de hook remet une charge utile JSON au gestionnaire de hooks. Deux formats de charge utile sont pris en charge, sélectionnés par le nom d’événement utilisé dans la configuration de hook :\n\n* **Format camelCase** : configurez le nom de l’événement dans camelCase (par exemple, `sessionStart`). Les champs respectent le format camelCase.\n* **VS Code format compatible** : configurez le nom de l’événement dans PascalCase (par exemple, `SessionStart`). Les champs utilisent snake\\_case pour correspondre au format d’extension VS CodeCopilot .\n\n### `sessionStart` / `SessionStart`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number; // Unix timestamp in milliseconds\n cwd: string;\n source: \"startup\" | \"resume\" | \"new\";\n initialPrompt?: string;\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"SessionStart\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n source: \"startup\" | \"resume\" | \"new\";\n initial_prompt?: string;\n}\n```\n\n### `sessionEnd` / `SessionEnd`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"SessionEnd\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n### `userPromptSubmitted` / `UserPromptSubmit`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n prompt: string;\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"UserPromptSubmit\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n prompt: string;\n}\n```\n\n**Output:**\n\n```typescript\n{\n modifiedPrompt?: string; // Replaces the prompt for the rest of the turn (SDK programmatic hooks only)\n}\n```\n\nRenvoyez `{}` ou vide pour laisser l’invite inchangée.\n\n> \\[!NOTE]\n> \\*\n> `modifiedPrompt` n’est pris en compte que par les hooks programmatiques de l’SDK. Les hooks de commande et de fichier `userPromptSubmitted` de configuration HTTP ont leur sortie supprimée, y compris `modifiedPrompt`. L’environnement d’exécution plus léger utilisé pour le traitement des hooks par les sessions Copilot cloud agent hébergées ou pilotées l’ignore également. Il s’agit du même fractionnement du runtime que `preToolUse`.\n>\n> * Une valeur non-chaîne `modifiedPrompt`, `modifiedTransformedPrompt`ou une valeur gérée `responseContent` est ignorée plutôt que de endommager la session. Un avertissement de type nommant le champ est enregistré et émis en tant qu’événement `session.warning` . Une substitution par une chaîne vide est rejetée au lieu de vider le contenu destiné au modèle. Une `null``additionalContext` valeur est traitée comme absente au lieu d’être injectée en tant que texte `null`littéral . La sortie d’un hook (stdout pour les hooks de commande, le corps de la réponse pour les hooks HTTP) est plafonnée à 10 Mio par invocation ; toute réponse plus volumineuse est tronquée au lieu d’épuiser la mémoire.\n\n### `userPromptTransformed`\n\nSe déclenche après que le runtime a transformé un prompt soumis en contenu destiné au modèle, juste avant que ce contenu soit généré et enregistré dans l’historique de session. S’exécute pour le message initial et pour chaque message précédent dans une soumission par lot. Mutation uniquement : il peut réécrire le contenu reçu par le modèle, mais pas bloquer ou gérer le tour. Les notifications système ne le déclenchent jamais.\n\n**Entrée :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number; // epoch-ms integer\n cwd: string;\n prompt: string; // user prompt after userPromptSubmitted hooks have run\n transformedPrompt: string; // runtime-transformed content the model will receive\n}\n```\n\n**Output:**\n\n```typescript\n{\n modifiedTransformedPrompt?: string; // Replaces the model-facing content\n}\n```\n\nRetourne `{}` ou vide pour laisser le contenu transformé inchangé.\n`modifiedTransformedPrompt` remplace uniquement le contenu envoyé au modèle et stocké dans l’historique de la session — le prompt affiché dans la chronologie n’est pas affecté — et le remplacement est rejoué à l’identique si la session est reprise.\n\n### `preToolUse` / `PreToolUse`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\nLorsqu’elle est configurée avec le nom `PreToolUse` de l’événement PascalCase, la charge utile utilise des noms de champs en snake\\_case afin de correspondre au format d’extension VS CodeCopilot :\n\n```typescript\n{\n hook_event_name: \"PreToolUse\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown; // Tool arguments (parsed from JSON string when possible)\n}\n```\n\n**Correspondances de format Claude (PascalCase `PreToolUse`) :** Les hooks configurés avec le nom d’événement PascalCase `PreToolUse` — tels qu’utilisés dans les plug-ins Claude Code et le format Open Plugins — appliquent la sémantique de correspondance de Claude au lieu de la règle regex native :\n\n* `*`, `**`ou une valeur vide `matcher` se déclenche pour chaque outil.\n* Un nom littéral ou une alternative séparée par `|` (par exemple, `Bash` ou `Edit|Write`) se déclenche lorsqu’un jeton correspond au nom de l’outil d’exécution ou à son nom d’outil Claude indiqué dans le tableau ci-dessous.\n* Toute autre valeur est traitée comme une expression régulière sensible à la casse, ancrée sous la forme `^(?:PATTERN)$`, et évaluée sur le nom de l’outil Claude (ou sur le nom du runtime pour les outils sans équivalent Claude).\n\nLes charges utiles en PascalCase `PreToolUse` indiquent `tool_name` comme nom de l’outil Claude dans (par exemple, `Bash`, et non `bash`).\n\n| Outil d’exécution | Nom de l’outil Claude |\n| -------------------------------------------------- | --------------------- |\n| `bash`, `powershell` | `Bash` |\n| `view` | `Read` |\n| `create` | `Write` |\n| `edit`, `str_replace_editor`, `apply_patch` | `Edit` |\n| `grep`, `rg` | `Grep` |\n| `glob` | `Glob` |\n| `web_fetch` | `WebFetch` |\n| `web_search` | `WebSearch` |\n| `ask_user` | `AskUserQuestion` |\n| `update_todo` | `TodoWrite` |\n| `task` | |\n| `Agent` (le littéral `Task` est également accepté) | |\n\nLes outils qui n’ont pas d’équivalent dans Claude conservent leurs noms d’exécution.\n\n> \\[!IMPORTANT]\n> **Comportement en cas d’échec des commandes par rapport à HTTP pour `preToolUse` :** les hooks de commande `preToolUse` sont **configurés pour refuser par défaut** en cas d’erreur : un plantage ou une sortie avec un code non nul (y compris la sortie `2`) entraîne le refus de l’appel à l’outil, même si le JSON sur stdout du hook indique `permissionDecision: \"allow\"`. Les **délais d’expiration des hooks de commande fonctionnent toujours en mode fail-open, même pour `preToolUse`les hooks de stratégie déployés par l’administrateur** : un hook arrivé à expiration affiche un avertissement et laisse l’appel de l’outil suivre le flux d’autorisation normal au lieu d’être bloqué. Les hooks HTTP `preToolUse` fonctionnent en mode **« fail-open »** : une erreur réseau, un délai d’expiration ou une réponse non-2xx revient au flux d’autorisation par défaut. Choisissez la variante qui correspond à vos exigences de sécurité.\n\n### `postToolUse` / `PostToolUse`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n toolResult: {\n resultType: \"success\";\n textResultForLlm: string;\n }\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"PostToolUse\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown;\n tool_result: {\n result_type: \"success\";\n text_result_for_llm: string;\n }\n}\n```\n\n### `postToolUseFailure` / `PostToolUseFailure`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n error: string;\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"PostToolUseFailure\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown;\n error: string;\n}\n```\n\n### `agentStop` / `Stop`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n stopReason: \"end_turn\";\n stop_hook_active: boolean; // true when this turn was already forced to continue by a prior \"block\" decision from this hook\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"Stop\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n stop_reason: \"end_turn\";\n stop_hook_active: boolean;\n}\n```\n\n### `subagentStart`\n\n> \\[!NOTE]\n> L’agent intégré `general-purpose` n’émet pas d’événements `subagentStart` ou `subagentStop`. Tous les autres agents YAML intégrés, notamment `explore`, , `task`, `code-review``rubber-duck`, `research`et `security-review`les agents personnalisés définis par l’utilisateur émettent ces événements.\n\n**Entrée :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n agentName: string;\n agentDisplayName?: string;\n agentDescription?: string;\n}\n```\n\n### `subagentStop` / `SubagentStop`\n\nSe déclenche lorsqu’un sous-agent se termine normalement, avant de renvoyer les résultats au parent.\n`stopReason` est actuellement toujours `\"end_turn\"`. Ce point d’extension se déclenche avant la gestion du débordement des réponses volumineuses ; ainsi, `response` (ou `last_assistant_message` au format compatible avec VS Code) contient l’intégralité du texte de réponse final du sous-agent.\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n agentId: string;\n agentType: string;\n agentName: string;\n agentDisplayName?: string;\n response: string; // Full final subagent response text\n stopReason: \"end_turn\";\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"SubagentStop\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n agent_id: string;\n agent_type: string;\n agent_name: string;\n agent_display_name?: string;\n last_assistant_message: string; // The `response` text\n stop_reason: \"end_turn\";\n}\n```\n\n### `errorOccurred` / `ErrorOccurred`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n error: {\n message: string;\n name: string;\n stack?: string;\n };\n errorContext: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n recoverable: boolean;\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"ErrorOccurred\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n error: {\n message: string;\n name: string;\n stack?: string;\n };\n error_context: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n recoverable: boolean;\n}\n```\n\n### `preCompact` / `PreCompact`\n\n**entrée camelCase :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n trigger: \"manual\" | \"auto\";\n customInstructions: string;\n}\n```\n\n\\*\\*\nVS Code entrée compatible :\\*\\*\n\n```typescript\n{\n hook_event_name: \"PreCompact\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n trigger: \"manual\" | \"auto\";\n custom_instructions: string;\n}\n```\n\n## `preToolUse` contrôle de décision\n\nLe `preToolUse` hook peut contrôler l’exécution de l’outil en écrivant un objet JSON dans stdout.\n\n| Champ | Valeurs | Description |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |\n| `permissionDecision` | | |\n| `\"allow\"`, `\"deny\"`, `\"ask\"` | Indique si l’outil s’exécute. La sortie vide utilise le comportement par défaut. Sous l'agent cloud, `\"ask\"` est traité comme `\"deny\"` parce qu'aucun utilisateur n'est disponible pour répondre. | |\n| `permissionDecisionReason` | string | Raison indiquée à l’agent. Obligatoire lorsque la décision est `\"deny\"`. |\n| `modifiedArgs` | Objet | Remplacez les arguments de l’outil à utiliser au lieu des arguments d’origine. |\n\nLorsque Copilot CLI peut afficher la demande d’autorisation du hook, l’utilisateur peut saisir un commentaire facultatif lors d’un refus. Ce commentaire est ajouté au message que l’agent reçoit : `Denied by user via preToolUse hook prompt: . The user provided the following feedback: `.\n\n## `agentStop`/ `subagentStop` contrôle de décision\n\n| Champ | Valeurs | Description |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------- |\n| `decision` | | |\n| `\"block\"`, `\"allow\"` | | |\n| `\"block\"` oblige un autre agent à réagir en utilisant `reason` comme invite. | | |\n| `reason` | string | Invite pour le tour suivant lorsque `decision` est `\"block\"`. |\n| `modifiedResponse` | string | |\n| \\*\\* | | |\n| `subagentStop` Seulement.\\*\\* Remplace la réponse renvoyée au parent lorsque le sous-agent est autorisé à terminer son exécution, utile pour expurger ou reformater la sortie du sous-agent. Non applicable à `agentStop`. | | |\n\n`decision` et `reason` se comportent de la même façon pour les deux `agentStop` et `subagentStop`.\n`modifiedResponse` s’applique uniquement à `subagentStop`:\n\n* Une décision valide `block` l’emporte sur `modifiedResponse` : si un hook renvoie les deux, le sous-agent continue et la réécriture est écartée.\n* Les réécritures ne se composent pas entre plusieurs hooks correspondants. Chaque hook reçoit le même texte d’origine `response`, et le dernier hook à renvoyer `modifiedResponse` l’emporte : chaîner une fonction de masquage et une fonction de mise en forme n’alimente pas la fonction de mise en forme avec le texte masqué.\n* Les noms de champs de sortie (`decision`, `reason`, `modifiedResponse`) sont identiques pour les configurations camelCase et VS Code compatibles.\n\n> \\[!NOTE]\n> **Garde de fuite.** Après 8 continuations consécutives `block`, l’interface de ligne de commande ignore le hook et met quand même fin au tour, afin d’éviter une boucle infinie. Utilisez le champ de saisie `stop_hook_active` dans `agentStop` pour détecter que ce tour a déjà été forcé à continuer, et vous limiter avant d’atteindre le plafond.\n\n## `postToolUse` sortie\n\nLe `postToolUse` hook peut modifier le résultat de l’outil ou injecter un contexte supplémentaire pour le modèle en écrivant un objet JSON dans stdout.\n\n```typescript\n{\n modifiedResult?: {\n resultType: \"success\";\n textResultForLlm: string;\n };\n additionalContext?: string;\n}\n```\n\n| Champ | Type | Description |\n| ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `modifiedResult` | Objet | Résultat de l’outil de remplacement. Doit comporter `resultType: \"success\"`. S’il est renvoyé avec `resultType: \"failure\"`, la route d’échec en aval est alors empruntée et `postToolUseFailure` se déclenche ensuite. |\n| `additionalContext` | string | Des instructions supplémentaires sont ajoutées à `textResultForLlm` afin que le modèle le voie après la sortie de l’outil dans le même tour. Lorsque plusieurs hooks renvoient `additionalContext`, les résultats sont concaténés avec deux sauts de ligne et plafonnés à 10 Ko. |\n\nRenvoyer `{}` ou vider la sortie pour conserver le résultat d’origine réussi.\n\n> \\[!NOTE]\n> `modifiedResult` est pris en compte à la fois par les hooks programmatiques du SDK et par les hooks de configuration en fichier (commande/HTTP) `postToolUse`.\n\n**Matcher :** Expression régulière facultative testée par rapport à `toolName`. Le modèle regex est la valeur du champ, `matcher`compilé en tant que`^(?:PATTERN)$`, et doit correspondre à l’ensemble du nom de l’outil. Si le modèle n’est pas une expression régulière valide, le crochet est ignoré. Omettez `matcher` pour recevoir les résultats de tous les outils.\n\n```json\n{\n \"type\": \"command\",\n \"matcher\": \"bash|edit\",\n \"bash\": \"./scripts/log-tool.sh\"\n}\n```\n\n## `permissionRequest` contrôle de décision\n\n> \\[!NOTE]\n> **Copilot CLI Seulement.** Le `permissionRequest` hook ne s’applique pas sous Copilot cloud agent: les appels d’outil sont pré-approuvés (voir la ligne **Interactivity** dans la table d’environnement d’exécution de l’agent cloud). Utilisez `preToolUse` pour prendre des décisions d’autorisation dans l’agent cloud.\n\nLe `permissionRequest` hook se déclenche avant l'exécution du service de permission : avant les vérifications de règles, les approbations de session, l'acceptation automatique/le refus automatique, et l'interpellation de l'utilisateur. Si les hooks retournent `behavior: \"allow\"` ou `\"deny\"`, cette décision court-circuite le flux de permis normal. L’absence de retour équivaut à suivre le mécanisme habituel de gestion des permissions. Utilisez-le pour approuver ou refuser des appels d’outils par programmation, particulièrement utiles en mode canal CLI (`-p`) et d’autres utilisations CI CLI où aucune invite interactive n’est disponible. Elle ne s’applique pas à l’agent cloud.\n\nTous les hooks `permissionRequest` configurés sont exécutés pour chaque requête, à l’exception des types d’autorisation `read` et `hook`, qui sont interceptés avant l’exécution des hooks. Les sorties des hooks sont combinées, celles des hooks exécutés ultérieurement remplaçant les précédentes.\n\n**Exception de contournement du bac à sable :** pour toute demande visant à sortir du bac à sable (`requestSandboxBypass: true` in `toolInput`), un hook `allow` ne préapprouve pas la demande et ne contourne pas l’invite utilisateur — sortir du bac à sable constitue une élévation de privilèges que l’utilisateur doit toujours confirmer de manière interactive. Cela couvre une commande shell demandant une exécution en dehors du sandbox, ainsi qu’une `web_fetch` dont l’URL est refusée par la stratégie réseau du sandbox. Seul `deny` se propage (donc un crochet de stratégie peut bloquer l’échappement) ; une `allow` (ou aucune décision) passe à l’invite normale.\n\n**Matcher :** Expression régulière facultative testée par rapport à `toolName`. Le modèle regex est la valeur du champ, `matcher`ancré en tant que`^(?:PATTERN)$`, et doit correspondre à l’ensemble du nom complet de l’outil. Lorsqu’il est défini, le hook se déclenche uniquement pour les noms d’outils correspondants.\n\n> \\[!NOTE]\n> **Matchers au format Claude (PascalCase `PermissionRequest`) :** Les hooks configurés avec le nom d’événement PascalCase `PermissionRequest` utilisent la même sémantique de correspondance Claude que `PreToolUse`. Consultez [les correspondances au format Claude (PascalCase PreToolUse)](#claude-format-matchers-pascalcase-pretooluse) pour connaître les règles de correspondance et la table de noms d’outil.\n\nSortie json vers stdout pour contrôler la décision d’autorisation :\n\n| Champ | Valeurs | Description |\n| ------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| `behavior` | | |\n| `\"allow\"`, `\"deny\"` | Spécifie s’il convient d’autoriser ou de refuser l’appel de l’outil. | |\n| `message` | string | Motif transmis au GML en cas de refus. |\n| `interrupt` | booléen | Lorsque `true` est combiné à `\"deny\"`, l’agent est entièrement arrêté. |\n\nRetournez une sortie vide ou `{}` afin de rétablir le flux normal de gestion des permissions Pour les crochets de commande, le code `2` de sortie est traité comme un refus ; le code JSON stdout (le cas échéant) est fusionné `{\"behavior\":\"deny\"}`avec , et stderr est ignoré.\n\n## `notification` crochet\n\n> \\[!NOTE]\n> **Copilot CLI Seulement.** Le `notification` hook ne se déclenche pas sous Copilot cloud agent.\n\nLe `notification` hook se déclenche de façon asynchrone lorsque l’interface CLI émet une notification système. Ces hooks fonctionnent selon un modèle « fire-and-forget » : ils ne bloquent jamais la session, et toute erreur est journalisée puis ignorée.\n\n**Entrée :**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n hook_event_name: \"Notification\";\n message: string; // Human-readable notification text\n title?: string; // Short title (e.g., \"Permission needed\", \"Shell completed\")\n notification_type: string; // One of the types listed below\n}\n```\n\n**Types de notification :**\n\n| Type | Quand il se déclenche |\n| -------------------------- | ------------------------------------------------------------------------------------------------- |\n| `shell_completed` | Une commande d’interpréteur exécutée en arrière-plan (asynchrone) arrive à son terme. |\n| `shell_detached_completed` | Une session shell détachée se termine |\n| `agent_completed` | Un sous-agent en arrière-plan se termine (avec succès ou échec) |\n| `agent_idle` | Un agent en arrière-plan conclut un cycle et passe en état inactif (en attente de `write_agent`). |\n| `permission_prompt` | L’agent demande l’autorisation d’exécuter un outil |\n| `elicitation_dialog` | L’agent demande des informations supplémentaires à l’utilisateur |\n\n**Output:**\n\n```typescript\n{\n additionalContext?: string; // Injected into the session as a user message\n}\n```\n\nSi `additionalContext` est retourné, le texte est injecté dans la session en tant que message utilisateur préfixé. Cela peut déclencher un traitement supplémentaire de l'agent si la session est inutilisée. Renvoyer `{}` ou vider la sortie pour n’effectuer aucune action.\n\n**Matcher :** Regex facultatif sur `notification_type`. Le modèle regex est la valeur du `matcher` champ, ancré comme `^(?:PATTERN)$`. Omettre `matcher` pour recevoir tous les types de notifications.\n\n## Filtrage de correspondance\n\nPlusieurs événements acceptent une expression régulière facultative `matcher` sur chaque entrée de hook qui filtre les appels pour lesquels le hook se déclenche. Elle est compilée comme `^(?:PATTERN)$` et doit correspondre à la valeur complète. Les expressions régulières invalides entraînent l’ignorance de l’entrée de hook.\n\n\\| Événement |\n`matcher` est mis en correspondance avec |\n\\|-------|------------------------------|\n\\| `notification` | `notification_type` |\n\\| `permissionRequest` | `toolName` |\n\\| `postToolUse` | `toolName` |\n\\| `preCompact` |\n`trigger` (`\"manual\"` ou `\"auto\"`) |\n\\| `preToolUse` | `toolName` |\n\\| `subagentStart` | `agentName` |\n\n## Noms d’outils pour la correspondance de hooks\n\n| Nom de l’outil | Description |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `ask_user` | Posez à l’utilisateur une question de clarification. Sous l’agent cloud, il n’y a pas d’utilisateur, donc `ask_user` ne produit pas de résultat utile. |\n| `bash` | Exécuter des commandes shell (Unix). |\n| `create` | Créez des fichiers. |\n| `edit` | Modifiez le contenu du fichier. |\n| `glob` | Recherchez des fichiers par modèle. |\n| `grep` | Rechercher le contenu du fichier. |\n| `powershell` | Exécuter des commandes shell (Windows). N’apparaît pas sous agent cloud (bac à sable Linux). |\n| `task` | Exécutez des tâches de sous-agent. |\n| `view` | Lire le contenu du fichier. |\n| `web_fetch` | Récupérer des pages web. |\n\nSi plusieurs hooks du même type sont configurés, ils s'exécutent dans l'ordre. Pour `preToolUse`, si un crochet retourne `\"deny\"`, l’outil est bloqué. Pour la plupart des événements, les échecs de hook (codes de sortie non nuls autres que `2`, ou les délais d’expiration) sont enregistrés et ignorés.\n**Exception : `preToolUse` les hooks de commande adoptent un comportement de fermeture par défaut à la sortie `2` et en cas d’erreurs autres qu’un dépassement de délai** — une sortie `2`, un plantage ou toute autre sortie non nulle (autre qu’un dépassement de délai) entraîne le refus de l’appel à l’outil, même si le JSON émis sur la sortie standard du hook indique `permissionDecision: \"allow\"`.\n**Les délais d’expiration fonctionnent toujours en mode fail-open, y compris pour `preToolUse` et les hooks de politique déployés par l’administrateur** : un avertissement est affiché et l’appel à l’outil suit le processus normal d’autorisation au lieu d’être refusé.\n\n## Codes de sortie pour les hooks de commande\n\n| Code de sortie | Sens |\n| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| `0` | Opération réussie. |\n| `stdout` est analysé comme le JSON de sortie du hook s'il est présent. | |\n| `2` | Traité comme un avertissement par défaut. |\n| `stderr` est présenté à l’utilisateur, mais l’exécution continue. Pour `permissionRequest` et `preToolUse`, la sortie `2` est traitée comme un refus : tout JSON `stdout` est fusionné à la décision de refus et l’appel de l’outil est refusé même si ce JSON indique `permissionDecision: \"allow\"`. Pour `postToolUseFailure`, la sortie `2` est traitée comme `additionalContext` et `stdout` est ajoutée à l’échec indiqué à l’agent. | |\n| Les autres valeurs non nulles | Journalisé en tant qu’échec de hook. L’exécution continue (fail-open). |\n| **Exception : `preToolUse` est en mode fail-closed** : un code de sortie non nul (autre que le code de sortie 2) bloque l’appel à l’outil avec `\"Denied by preToolUse hook (hook errored)\"`. | |\n| Délai d'expiration | Tué après `timeoutSec`. Erreur enregistrée, l’exécution se poursuit. |\n| **Les délais d’expiration sont ouverts automatiquement pour chaque événement, y compris `preToolUse` et les hooks de stratégie déployés par l’administrateur**. Un avertissement est exposé et le traitement se poursuit comme si le hook n’avait pas été exécuté. Pour `preToolUse`, l’appel à l’outil suit le processus normal d’autorisation au lieu d’être refusé. Un crochet bloqué ou explicitement refusé continue d’échouer ; seuls les délais d’expiration sont exemptés. | |\n\nPour la plupart des événements, les sorties et les délais d’expiration non nuls sont enregistrés et ignorés. L’exécution de l’agent se poursuit. Pour les hooks de commande `preToolUse`, le code de sortie 2, les plantages et tous les autres codes de sortie non nuls entraînent systématiquement un échec en mode fail-closed et refusent l’appel à l’outil : le code de sortie 2 refuse toujours, même si le JSON du hook `stdout` indique `permissionDecision: \"allow\"` ; mais **les délais d’expiration sont toujours traités en mode fail-open** : un hook lent ou inaccessible ne doit pas bloquer silencieusement les appels à l’outil ni le travail, même lorsque le hook a été déployé par un administrateur comme règle de politique.\n\n## Désactiver tous les hooks\n\nUtilisez `disableAllHooks` quand vous souhaitez conserver votre configuration de hook sur le disque, mais l’empêcher de s’exécuter, par exemple :\n\n* Déboguer un problème et vérifier si un hook en est la cause sans supprimer votre configuration.\n* Suspension de l’automatisation pendant une tâche sensible (révision de code, branche de mise en production, utilisation de secrets) sans perdre la configuration. (**Copilot CLI uniquement.**)\n* Publication d’un fichier de hooks dans le contrôle de source que les contributeurs peuvent désactiver localement en configurant l’option dans leur référentiel `settings.json`. (**Copilot CLI uniquement.**)\n* Silençage temporaire des hooks lents ou bruyants pendant une session interactive. (**Copilot CLI uniquement.**)\n\nDéfinissez `disableAllHooks` sur `true` au niveau supérieur pour ignorer chaque point d'ancrage dans le fichier sans le supprimer.\n\n```json\n{\n \"version\": 1,\n \"disableAllHooks\": false,\n \"hooks\": {\n \"preToolUse\": [ /* hook entries */ ]\n }\n}\n```\n\nLe comportement dépend de l’emplacement où vous définissez l’indicateur :\n\n* **Dans un seul fichier `.github/hooks/*.json`**, seuls les hooks déclarés dans ce fichier sont ignorés. Honoré par les deux Copilot CLI et Copilot cloud agent.\n* **Au niveau supérieur du référentiel `settings.json`** — **Copilot CLI seulement.** Chaque hook de chaque source (fichiers du référentiel, fichiers utilisateur, plug-ins et blocs de hook inline) est ignoré lors des sessions de ce référentiel. Les hooks de stratégie ne sont pas affectés et continuent à s’exécuter. L’agent cloud ne charge `settings.json`pas .\n\n## Lectures complémentaires\n\n* [Utilisation de crochets avec GitHub Copilot CLI](/fr/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)\n* [Références sur les hooks GitHub Copilot](/fr/copilot/reference/hooks-reference)\n* [Référence de commande CLI pour GitHub Copilot](/fr/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [Concepts de l’agent cloud GitHub Copilot](/fr/copilot/concepts/agents/cloud-agent)"}