Références sur les hooks GitHub Copilot CLI

Les 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. Les fichiers de configuration de "hook" sont chargés automatiquement depuis .github/hooks/*.json de votre référentiel.

Format de configuration des hooks

Les fichiers de configuration de hook utilisent le format JSON avec la version 1.

Crochets de commande

Les commandes hook exécutent des scripts shell et sont prises en charge pour tous les types de hook.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "your-bash-command",
        "powershell": "your-powershell-command",
        "cwd": "optional/working/directory",
        "env": { "VAR": "value" },
        "timeoutSec": 30
      }
    ]
  }
}

Champ	Type	Obligatoire	Description
`bash`	string	L'un de `bash`/`powershell`	Commande Shell pour Unix.
`cwd`	string	Non	Répertoire de travail pour la commande (relatif à la racine du référentiel ou absolu).
`env`	Objet	Non	Variables d’environnement à définir (prend en charge l’expansion des variables).
`powershell`	string	L'un de `bash`/`powershell`	Commande Shell pour Windows.
`timeoutSec`	nombre	Non	Délai d’expiration en secondes. Valeur par défaut : `30`.
`type`	`"command"`	Oui	Doit être `"command"`.

Crochets d’invite

Les déclencheurs automatiques soumettent le texte comme si l'utilisateur l'avait tapé. Elles ne sont prises en charge que sur sessionStart et elles ne s'activent que 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). Le texte peut être une invite en langage naturel ou une commande barre oblique.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

Champ	Type	Obligatoire	Description
`type`	`"prompt"`	Oui	Doit être `"prompt"`.
`prompt`	string	Oui	Texte à soumettre : il peut s'agir d'un message en langage naturel ou d'une commande slash.

Événements de hook

Événement	Se déclenche quand	Sortie traitée
`agentStop`	L’agent principal termine un tour.	Oui : peut bloquer et forcer la continuation.
`errorOccurred`	Une erreur se produit pendant l’exécution.	Non
`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. Gère les expressions régulières `matcher` appliquées à `notification_type`.	Facultatif — possibilité d'injecter `additionalContext` dans la session.
`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). Lorsque la sortie agrégée du hook retourne `behavior: "allow"` ou `"deny"`, cette décision interrompt le flux standard de gestion des permissions. Gère les expressions régulières `matcher` appliquées à `toolName`.	Oui : peut autoriser ou refuser par programme.
`postToolUse`	Après que chaque outil ait terminé avec succès.	Oui — autorise le remplacement du résultat en cas de succès (uniquement via les hooks programmatiques du SDK).
`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).
`preCompact`	Le compactage de contexte est sur le point de commencer (manuel ou automatique). Prend en charge `matcher` afin de filtrer selon le déclencheur (`"manual"`ou `"auto"`).	Non : notification uniquement.
`preToolUse`	Avant l’exécution de chaque outil.	Oui : peut autoriser, refuser ou modifier.
`sessionEnd`	La session se termine.	Non
`sessionStart`	Une session nouvelle ou reprise commence.	Non
`subagentStart`	Un sous-agent est initié (avant son exécution). Retourne `additionalContext` inséré au début de la requête du sous-agent. Prend en charge `matcher` pour filtrer par nom de l’agent.	Non : impossible de bloquer la création.
`subagentStop`	Un sous-assistant termine son exécution.	Oui : peut bloquer et forcer la continuation.
`userPromptSubmitted`	L’utilisateur envoie une invite.	Non

Charges utiles d’entrée associées aux événements de hook

Chaque é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 :

Format camelCase : configurez le nom de l’événement dans camelCase (par exemple, sessionStart). Les champs respectent le format camelCase.

          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 .

`sessionStart` / `SessionStart`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;      // Unix timestamp in milliseconds
    cwd: string;
    source: "startup" | "resume" | "new";
    initialPrompt?: string;
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "SessionStart";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    source: "startup" | "resume" | "new";
    initial_prompt?: string;
}

`sessionEnd` / `SessionEnd`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "SessionEnd";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

`userPromptSubmitted` / `UserPromptSubmit`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    prompt: string;
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "UserPromptSubmit";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    prompt: string;
}

`preToolUse` / `PreToolUse`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
}

          **
          VS Code entrée compatible :**

Lorsqu’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 :

{
    hook_event_name: "PreToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;    // Tool arguments (parsed from JSON string when possible)
}

`postToolUse` / `PostToolUse`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    toolResult: {
        resultType: "success";
        textResultForLlm: string;
    }
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "PostToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    tool_result: {
        result_type: "success" | "failure" | "denied" | "error";
        text_result_for_llm: string;
    }
}

`postToolUseFailure` / `PostToolUseFailure`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    error: string;
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "PostToolUseFailure";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    error: string;
}

`agentStop` / `Stop`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    stopReason: "end_turn";
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "Stop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    stop_reason: "end_turn";
}

`subagentStart`

          **Entrée :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    agentDescription?: string;
}

`subagentStop` / `SubagentStop`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    stopReason: "end_turn";
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "SubagentStop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    agent_name: string;
    agent_display_name?: string;
    stop_reason: "end_turn";
}

`errorOccurred` / `ErrorOccurred`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    errorContext: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "ErrorOccurred";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    error_context: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

`preCompact` / `PreCompact`

          **entrée camelCase :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    trigger: "manual" | "auto";
    customInstructions: string;
}

          **
          VS Code entrée compatible :**

{
    hook_event_name: "PreCompact";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    trigger: "manual" | "auto";
    custom_instructions: string;
}

          `preToolUse` contrôle de décision

Le preToolUse hook peut contrôler l’exécution de l’outil en écrivant un objet JSON dans stdout.

Champ	Valeurs	Description
`permissionDecision`

          `"allow"`, `"deny"`, `"ask"` | Indique si l’outil s’exécute. La sortie vide utilise le comportement par défaut. |

          `agentStop`
           / 
          `subagentStop` contrôle de décision

Champ	Valeurs	Description
`decision`

          `"block"`, `"allow"` | 
          `"block"` oblige un autre agent à réagir en utilisant `reason` comme invite. |

| reason | string | Invite pour le tour suivant lorsque decision est "block". |

          `permissionRequest` contrôle de décision

Le 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 (-p) et environnements CI où aucune invite interactive n’est disponible.

Tous 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.

          **Matcher :** Expression régulière facultative testée par rapport à `toolName`. Ancré comme `^(?:pattern)$`; doit correspondre au nom complet de l’outil. Lorsqu’il est défini, le hook se déclenche uniquement pour les noms d’outils correspondants.

Sortie json vers stdout pour contrôler la décision d’autorisation :

Champ	Valeurs	Description
`behavior`

          `"allow"`, `"deny"` | Spécifie s’il convient d’autoriser ou de refuser l’appel de l’outil. |

Retournez 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é.

`notification` crochet

Le 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.

          **Entrée :**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    hook_event_name: "Notification";
    message: string;           // Human-readable notification text
    title?: string;            // Short title (e.g., "Permission needed", "Shell completed")
    notification_type: string; // One of the types listed below
}

          **Types de notification :**

Type	Quand il se déclenche
`shell_completed`	Une commande d’interpréteur exécutée en arrière-plan (asynchrone) arrive à son terme.
`shell_detached_completed`	Une session shell détachée se termine
`agent_completed`	Un sous-agent en arrière-plan se termine (avec succès ou échec)
`agent_idle`	Un agent en arrière-plan conclut un cycle et passe en état inactif (en attente de `write_agent`).
`permission_prompt`	L’agent demande l’autorisation d’exécuter un outil
`elicitation_dialog`	L’agent demande des informations supplémentaires à l’utilisateur

          **Output:**

{
    additionalContext?: string; // Injected into the session as a user message
}

Si 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.

          **Matcher :** Regex facultatif sur `notification_type`. Le modèle est ancré comme `^(?:pattern)$`. Omettre `matcher` pour recevoir tous les types de notifications.

Noms d’outils pour la correspondance de hooks

Nom de l’outil	Description
`ask_user`	Posez à l’utilisateur une question de clarification.
`bash`	Exécuter des commandes shell (Unix).
`create`	Créez des fichiers.
`edit`	Modifiez le contenu du fichier.
`glob`	Recherchez des fichiers par modèle.
`grep`	Rechercher le contenu du fichier.
`powershell`	Exécuter des commandes shell (Windows).
`task`	Exécutez des tâches de sous-agent.
`view`	Lire le contenu du fichier.
`web_fetch`	Récupérer des pages web.

Si 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 les hooks de commande postToolUseFailure, une sortie avec le code 2 entraîne le renvoi de stderr comme indication de récupération pour l’assistant. Les échecs de hook (codes de sortie non nuls ou délais d’expiration) sont enregistrés et ignorés. Ils ne bloquent jamais l’exécution de l’agent.

Dans cet article