297| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |297| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
298| `type` | oui | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |298| `type` | oui | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |
299| `if` | non | Syntaxe de règle de permission pour filtrer quand ce hook s'exécute, comme `"Bash(git *)"` ou `"Edit(*.ts)"`. Le hook ne s'exécute que si l'appel d'outil correspond au modèle, ou si une commande Bash est trop complexe à analyser. Évalué uniquement sur les événements d'outil : `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` et `PermissionDenied`. Sur les autres événements, un hook avec `if` défini ne s'exécute jamais. Utilise la même syntaxe que les [règles de permission](/fr/permissions) |299| `if` | non | Syntaxe de règle de permission pour filtrer quand ce hook s'exécute, comme `"Bash(git *)"` ou `"Edit(*.ts)"`. Le hook ne s'exécute que si l'appel d'outil correspond au modèle, ou si une commande Bash est trop complexe à analyser. Évalué uniquement sur les événements d'outil : `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` et `PermissionDenied`. Sur les autres événements, un hook avec `if` défini ne s'exécute jamais. Utilise la même syntaxe que les [règles de permission](/fr/permissions) |
300| `timeout` | non | Secondes avant annulation. Valeurs par défaut : 600 pour command, 30 pour prompt, 60 pour agent |300| `timeout` | non | Secondes avant annulation. Valeurs par défaut : 600 pour `command`, `http` et `mcp_tool` ; 30 pour `prompt` ; 60 pour `agent`. [`UserPromptSubmit`](#userpromptsubmit) abaisse la valeur par défaut de `command`, `http` et `mcp_tool` à 30 |
301| `statusMessage` | non | Message de spinner personnalisé affiché pendant l'exécution du hook |301| `statusMessage` | non | Message de spinner personnalisé affiché pendant l'exécution du hook |
302| `once` | non | Si `true`, s'exécute une seule fois par session puis est supprimé. Honoré uniquement pour les hooks déclarés dans le [frontmatter des skills](#hooks-in-skills-and-agents) ; ignoré dans les fichiers de paramètres et le frontmatter des agents |302| `once` | non | Si `true`, s'exécute une seule fois par session puis est supprimé. Honoré uniquement pour les hooks déclarés dans le [frontmatter des skills](#hooks-in-skills-and-agents) ; ignoré dans les fichiers de paramètres et le frontmatter des agents |
303 303
558 558
559Les hooks de commande reçoivent les données JSON via stdin et communiquent les résultats via les codes de sortie, stdout et stderr. Les hooks HTTP reçoivent le même JSON que le corps de la requête POST et communiquent les résultats via le corps de la réponse HTTP. Cette section couvre les champs et le comportement communs à tous les événements. Chaque section d'événement sous [Événements de hook](#hook-events) inclut son schéma d'entrée spécifique et les options de contrôle de décision.559Les hooks de commande reçoivent les données JSON via stdin et communiquent les résultats via les codes de sortie, stdout et stderr. Les hooks HTTP reçoivent le même JSON que le corps de la requête POST et communiquent les résultats via le corps de la réponse HTTP. Cette section couvre les champs et le comportement communs à tous les événements. Chaque section d'événement sous [Événements de hook](#hook-events) inclut son schéma d'entrée spécifique et les options de contrôle de décision.
560 560
561Sur macOS et Linux, les hooks de commande s'exécutent dans leur propre session sans terminal de contrôle à partir de v2.1.139. Le processus de hook et tous les processus enfants ne peuvent pas ouvrir `/dev/tty` ou envoyer des séquences d'échappement directement à l'interface Claude Code. Windows n'a pas de `/dev/tty`. Pour afficher un message à l'utilisateur sur n'importe quelle plateforme, retournez [`systemMessage`](#json-output) dans la sortie JSON. Pour déclencher une notification de bureau, définir un titre de fenêtre ou sonner la cloche, retournez [`terminalSequence`](#emit-terminal-notifications) à la place.
562
561### Champs d'entrée communs563### Champs d'entrée communs
562 564
563Les événements de hook reçoivent ces champs en JSON, en plus des champs spécifiques à l'événement documentés dans chaque section [événement de hook](#hook-events). Pour les hooks de commande, ce JSON arrive via stdin. Pour les hooks HTTP, il arrive dans le corps de la requête POST.565Les événements de hook reçoivent ces champs en JSON, en plus des champs spécifiques à l'événement documentés dans chaque section [événement de hook](#hook-events). Pour les hooks de commande, ce JSON arrive via stdin. Pour les hooks HTTP, il arrive dans le corps de la requête POST.
694* **`hookSpecificOutput`** est un objet imbriqué pour les événements qui ont besoin d'un contrôle plus riche. Il nécessite un champ `hookEventName` défini au nom de l'événement.696* **`hookSpecificOutput`** est un objet imbriqué pour les événements qui ont besoin d'un contrôle plus riche. Il nécessite un champ `hookEventName` défini au nom de l'événement.
695 697
696| Champ | Par défaut | Description |698| Champ | Par défaut | Description |
697| :--------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |699| :----------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
698| `continue` | `true` | Si `false`, Claude arrête complètement le traitement après l'exécution du hook. Prend précédence sur tous les champs de décision spécifiques à l'événement |700| `continue` | `true` | Si `false`, Claude arrête complètement le traitement après l'exécution du hook. Prend précédence sur tous les champs de décision spécifiques à l'événement |
699| `stopReason` | aucun | Message affiché à l'utilisateur lorsque `continue` est `false`. Non affiché à Claude |701| `stopReason` | aucun | Message affiché à l'utilisateur lorsque `continue` est `false`. Non affiché à Claude |
700| `suppressOutput` | `false` | Si `true`, masque stdout de la sortie du journal de débogage |702| `suppressOutput` | `false` | Si `true`, masque stdout de la sortie du journal de débogage |
701| `systemMessage` | aucun | Message d'avertissement affiché à l'utilisateur |703| `systemMessage` | aucun | Message d'avertissement affiché à l'utilisateur |
704| `terminalSequence` | aucun | Une séquence d'échappement de terminal pour Claude Code d'émettre en votre nom, comme une notification de bureau, un titre de fenêtre ou une cloche. Restreint aux OSC `0`/`1`/`2`/`9`/`99`/`777` et BEL. Si la valeur contient quelque chose en dehors de la liste blanche, le champ est ignoré. Utilisez ceci au lieu d'écrire sur `/dev/tty`, qui n'est pas disponible pour les hooks |
702 705
703Pour arrêter Claude entièrement indépendamment du type d'événement :706Pour arrêter Claude entièrement indépendamment du type d'événement :
704 707
706{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }709{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
707```710```
708 711
712#### Émettre des notifications de terminal
713
714Le champ `terminalSequence` nécessite Claude Code v2.1.141 ou ultérieur.
715
716Les hooks s'exécutent sans terminal de contrôle, donc écrire des séquences d'échappement directement sur `/dev/tty` échoue. À la place, retournez la séquence d'échappement dans le champ `terminalSequence` et Claude Code l'émet pour vous via son propre chemin d'écriture de terminal. C'est sans course, fonctionne à l'intérieur de tmux et GNU screen, et fonctionne sur Windows où il n'y a pas de `/dev/tty`.
717
718Le champ accepte une chaîne d'une ou plusieurs séquences d'échappement en liste blanche :
719
720* OSC `0`, `1`, `2` : titres de fenêtre et d'icône
721* OSC `9` : notifications iTerm2, ConEmu, Windows Terminal et WezTerm, y compris la progression de la barre des tâches `9;4`
722* OSC `99` : notifications Kitty
723* OSC `777` : notifications urxvt, Ghostty et Warp
724* BEL nu
725
726Les séquences peuvent être terminées avec BEL ou avec ST. Tout ce qui est en dehors de la liste blanche, y compris les séquences de curseur CSI et les séquences de couleur, les séquences de palette OSC, les hyperliens OSC 8, les écritures de presse-papiers OSC 52 et OSC 1337, est rejeté et le champ est ignoré.
727
728L'exemple ci-dessous déclenche une notification de bureau à partir d'un hook `Notification`. La séquence d'échappement est construite avec des échappements octaux `printf` afin que les octets de contrôle n'apparaissent jamais sur la ligne de commande shell, et `jq -n --arg` construit la sortie JSON afin que les guillemets, les barres obliques inverses et les sauts de ligne dans le message de notification soient correctement échappés :
729
730```bash theme={null}
731#!/bin/bash
732# Hook de notification : ping le bureau lorsque Claude Code a besoin d'attention.
733input=$(cat)
734title="Claude Code'
735body=$(jq -r '.message // "Needs your attention"' <<<"$input")
736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
738```
739
740La forme `{ "terminalSequence": "..." }` est la même à partir de n'importe quel shell ou langage. Sur Windows, construisez la chaîne d'échappement dans PowerShell ou un script et émettez le même objet JSON.
741
742<Note>
743 `terminalSequence` est le remplacement pris en charge pour les hooks qui écrivaient précédemment des séquences d'échappement directement sur `/dev/tty`. La liste blanche est restreinte aux séquences qui ne peuvent pas déplacer le curseur ou modifier les couleurs, afin qu'un hook ne puisse jamais corrompre une invite à l'écran.
744</Note>
745
709#### Ajouter du contexte pour Claude746#### Ajouter du contexte pour Claude
710 747
711Le champ `additionalContext` transmet une chaîne de votre hook dans la fenêtre de contexte de Claude. Claude Code enveloppe la chaîne dans un rappel système et l'insère dans la conversation au point où le hook s'est déclenché. Claude lit le rappel lors de la prochaine demande du modèle, mais il n'apparaît pas comme un message de chat dans l'interface.748Le champ `additionalContext` transmet une chaîne de votre hook dans la fenêtre de contexte de Claude. Claude Code enveloppe la chaîne dans un rappel système et l'insère dans la conversation au point où le hook s'est déclenché. Claude lit le rappel lors de la prochaine demande du modèle, mais il n'apparaît pas comme un message de chat dans l'interface.
989 1026
990S'exécute lorsque l'utilisateur soumet un prompt, avant que Claude ne le traite. Cela vous permet d'ajouter du contexte supplémentaire basé sur le prompt/conversation, de valider les prompts ou de bloquer certains types de prompts.1027S'exécute lorsque l'utilisateur soumet un prompt, avant que Claude ne le traite. Cela vous permet d'ajouter du contexte supplémentaire basé sur le prompt/conversation, de valider les prompts ou de bloquer certains types de prompts.
991 1028
1029Les hooks `UserPromptSubmit` ont un délai d'expiration par défaut de 30 secondes pour les types `command`, `http` et `mcp_tool`, plus court que le délai par défaut de 600 secondes pour ces types sur d'autres événements. Parce que ce hook s'exécute avant chaque prompt et bloque le traitement du modèle jusqu'à son achèvement, un hook bloqué paralyse la session. Si votre hook a besoin de plus de temps, définissez le champ `timeout` dans l'entrée du hook.
1030
992#### Entrée UserPromptSubmit1031#### Entrée UserPromptSubmit
993 1032
994En plus des [champs d'entrée communs](#common-input-fields), les hooks UserPromptSubmit reçoivent le champ `prompt` contenant le texte que l'utilisateur a soumis.1033En plus des [champs d'entrée communs](#common-input-fields), les hooks UserPromptSubmit reçoivent le champ `prompt` contenant le texte que l'utilisateur a soumis.
2597 2636
2598Lorsqu'un hook asynchrone se déclenche, Claude Code démarre le processus du hook et continue immédiatement sans attendre qu'il se termine. Le hook reçoit la même entrée JSON via stdin qu'un hook synchrone.2637Lorsqu'un hook asynchrone se déclenche, Claude Code démarre le processus du hook et continue immédiatement sans attendre qu'il se termine. Le hook reçoit la même entrée JSON via stdin qu'un hook synchrone.
2599 2638
2600Après la sortie du processus en arrière-plan, si le hook a produit une réponse JSON avec un champ `systemMessage` ou `additionalContext`, ce contenu est livré à Claude comme contexte au tour de conversation suivant.2639Après la sortie du processus en arrière-plan, si le hook a produit une réponse JSON avec un champ `additionalContext`, ce contenu est livré à Claude comme contexte au tour de conversation suivant. Un champ `systemMessage` vous est montré, pas à Claude.
2601 2640
2602Les notifications d'achèvement des hooks asynchrones sont supprimées par défaut. Pour les voir, activez le mode verbeux avec `Ctrl+O` ou démarrez Claude Code avec `--verbose`.2641Les notifications d'achèvement des hooks asynchrones sont supprimées par défaut. Pour les voir, activez le mode verbeux avec `Ctrl+O` ou démarrez Claude Code avec `--verbose`.
2603 2642
2618 exit 02657 exit 0
2619fi2658fi
2620 2659
2621# Exécutez les tests et rapportez les résultats via systemMessage2660# Exécutez les tests et rapportez les résultats à Claude via additionalContext
2622RESULT=$(npm test 2>&1)2661RESULT=$(npm test 2>&1)
2623EXIT_CODE=$?2662EXIT_CODE=$?
2624 2663
2625if [ $EXIT_CODE -eq 0 ]; then2664if [ $EXIT_CODE -eq 0 ]; then
2626 echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"2665 MSG="Tests passed after editing $FILE_PATH"
2627else2666else
2628 echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"2667 MSG="Tests failed after editing $FILE_PATH: $RESULT"
2629fi2668fi
2669jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'
2630```2670```
2631 2671
2632Ensuite, ajoutez cette configuration à `.claude/settings.json` dans la racine de votre projet. Le drapeau `async: true` permet à Claude de continuer à travailler pendant que les tests s'exécutent :2672Ensuite, ajoutez cette configuration à `.claude/settings.json` dans la racine de votre projet. Le drapeau `async: true` permet à Claude de continuer à travailler pendant que les tests s'exécutent :
