Référence des hooks
Cette page fournit une documentation de référence pour l’implémentation des hooks dans Claude Code.
Pour un guide de démarrage rapide avec des exemples, voir Commencer avec les hooks Claude Code.
Configuration
Les hooks Claude Code sont configurés dans vos fichiers de paramètres :
~/.claude/settings.json
- Paramètres utilisateur.claude/settings.json
- Paramètres du projet.claude/settings.local.json
- Paramètres locaux du projet (non committé)- Paramètres de politique gérés par l’entreprise
Structure
Les hooks sont organisés par matchers, où chaque matcher peut avoir plusieurs hooks :
- matcher : Motif pour faire correspondre les noms d’outils, sensible à la casse (applicable uniquement pour
PreToolUse
etPostToolUse
)- Les chaînes simples correspondent exactement :
Write
correspond uniquement à l’outil Write - Prend en charge les regex :
Edit|Write
ouNotebook.*
- Utilisez
*
pour faire correspondre tous les outils. Vous pouvez également utiliser une chaîne vide (""
) ou laissermatcher
vide.
- Les chaînes simples correspondent exactement :
- hooks : Tableau de commandes à exécuter lorsque le motif correspond
type
: Actuellement, seul"command"
est pris en chargecommand
: La commande bash à exécuter (peut utiliser la variable d’environnement$CLAUDE_PROJECT_DIR
)timeout
: (Optionnel) Durée pendant laquelle une commande doit s’exécuter, en secondes, avant d’annuler cette commande spécifique.
Pour les événements comme UserPromptSubmit
, Notification
, Stop
, et SubagentStop
qui n’utilisent pas de matchers, vous pouvez omettre le champ matcher :
Scripts de Hook Spécifiques au Projet
Vous pouvez utiliser la variable d’environnement CLAUDE_PROJECT_DIR
(disponible uniquement lorsque Claude Code génère la commande hook) pour référencer des scripts stockés dans votre projet, en s’assurant qu’ils fonctionnent quel que soit le répertoire courant de Claude :
Événements de Hook
PreToolUse
S’exécute après que Claude crée les paramètres d’outil et avant de traiter l’appel d’outil.
Matchers communs :
Task
- Tâches d’agentBash
- Commandes shellGlob
- Correspondance de motifs de fichiersGrep
- Recherche de contenuRead
- Lecture de fichiersEdit
,MultiEdit
- Édition de fichiersWrite
- Écriture de fichiersWebFetch
,WebSearch
- Opérations web
PostToolUse
S’exécute immédiatement après qu’un outil se termine avec succès.
Reconnaît les mêmes valeurs de matcher que PreToolUse.
Notification
S’exécute lorsque Claude Code envoie des notifications. Les notifications sont envoyées lorsque :
- Claude a besoin de votre permission pour utiliser un outil. Exemple : “Claude a besoin de votre permission pour utiliser Bash”
- L’entrée de prompt est inactive depuis au moins 60 secondes. “Claude attend votre entrée”
UserPromptSubmit
S’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.
Stop
S’exécute lorsque l’agent principal Claude Code a fini de répondre. Ne s’exécute pas si l’arrêt s’est produit à cause d’une interruption utilisateur.
SubagentStop
S’exécute lorsqu’un sous-agent Claude Code (appel d’outil Task) a fini de répondre.
PreCompact
S’exécute avant que Claude Code soit sur le point d’exécuter une opération de compactage.
Matchers :
manual
- Invoqué depuis/compact
auto
- Invoqué depuis le compactage automatique (à cause d’une fenêtre de contexte pleine)
Entrée de Hook
Les hooks reçoivent des données JSON via stdin contenant des informations de session et des données spécifiques à l’événement :
Entrée PreToolUse
Le schéma exact pour tool_input
dépend de l’outil.
Entrée PostToolUse
Le schéma exact pour tool_input
et tool_response
dépend de l’outil.
Entrée Notification
Entrée UserPromptSubmit
Entrée Stop et SubagentStop
stop_hook_active
est vrai lorsque Claude Code continue déjà suite à un hook d’arrêt. Vérifiez cette valeur ou traitez le transcript pour empêcher Claude Code de s’exécuter indéfiniment.
Entrée PreCompact
Pour manual
, custom_instructions
provient de ce que l’utilisateur passe dans /compact
. Pour auto
, custom_instructions
est vide.
Sortie de Hook
Il y a deux façons pour les hooks de retourner une sortie vers Claude Code. La sortie communique s’il faut bloquer et tout retour qui devrait être montré à Claude et à l’utilisateur.
Simple : Code de Sortie
Les hooks communiquent le statut via les codes de sortie, stdout, et stderr :
- Code de sortie 0 : Succès.
stdout
est montré à l’utilisateur en mode transcript (CTRL-R), sauf pourUserPromptSubmit
, où stdout est ajouté au contexte. - Code de sortie 2 : Erreur bloquante.
stderr
est renvoyé à Claude pour traitement automatique. Voir le comportement par événement de hook ci-dessous. - Autres codes de sortie : Erreur non bloquante.
stderr
est montré à l’utilisateur et l’exécution continue.
Rappel : Claude Code ne voit pas stdout si le code de sortie est 0, sauf pour le hook UserPromptSubmit
où stdout est injecté comme contexte.
Comportement du Code de Sortie 2
Événement de Hook | Comportement |
---|---|
PreToolUse | Bloque l’appel d’outil, montre stderr à Claude |
PostToolUse | Montre stderr à Claude (l’outil a déjà été exécuté) |
Notification | N/A, montre stderr à l’utilisateur uniquement |
UserPromptSubmit | Bloque le traitement du prompt, efface le prompt, montre stderr à l’utilisateur uniquement |
Stop | Bloque l’arrêt, montre stderr à Claude |
SubagentStop | Bloque l’arrêt, montre stderr au sous-agent Claude |
PreCompact | N/A, montre stderr à l’utilisateur uniquement |
Avancé : Sortie JSON
Les hooks peuvent retourner du JSON structuré dans stdout
pour un contrôle plus sophistiqué :
Champs JSON Communs
Tous les types de hooks peuvent inclure ces champs optionnels :
Si continue
est false, Claude arrête le traitement après l’exécution des hooks.
- Pour
PreToolUse
, c’est différent de"permissionDecision": "deny"
, qui bloque seulement un appel d’outil spécifique et fournit un retour automatique à Claude. - Pour
PostToolUse
, c’est différent de"decision": "block"
, qui fournit un retour automatisé à Claude. - Pour
UserPromptSubmit
, cela empêche le prompt d’être traité. - Pour
Stop
etSubagentStop
, cela prend la priorité sur toute sortie"decision": "block"
. - Dans tous les cas,
"continue" = false
prend la priorité sur toute sortie"decision": "block"
.
stopReason
accompagne continue
avec une raison montrée à l’utilisateur, pas montrée à Claude.
Contrôle de Décision PreToolUse
Les hooks PreToolUse
peuvent contrôler si un appel d’outil procède.
"allow"
contourne le système de permission.permissionDecisionReason
est montré à l’utilisateur mais pas à Claude. (La valeur dépréciée"approve"
+reason
a le même comportement.)"deny"
empêche l’appel d’outil de s’exécuter.permissionDecisionReason
est montré à Claude. (La valeur"block"
+reason
a le même comportement.)"ask"
demande à l’utilisateur de confirmer l’appel d’outil dans l’UI.permissionDecisionReason
est montré à l’utilisateur mais pas à Claude.
Contrôle de Décision PostToolUse
Les hooks PostToolUse
peuvent contrôler si un appel d’outil procède.
"block"
invite automatiquement Claude avecreason
.undefined
ne fait rien.reason
est ignoré.
Contrôle de Décision UserPromptSubmit
Les hooks UserPromptSubmit
peuvent contrôler si un prompt utilisateur est traité.
"block"
empêche le prompt d’être traité. Le prompt soumis est effacé du contexte."reason"
est montré à l’utilisateur mais pas ajouté au contexte.undefined
permet au prompt de procéder normalement."reason"
est ignoré."hookSpecificOutput.additionalContext"
ajoute la chaîne au contexte si pas bloqué.
Contrôle de Décision Stop
/SubagentStop
Les hooks Stop
et SubagentStop
peuvent contrôler si Claude doit continuer.
"block"
empêche Claude de s’arrêter. Vous devez remplirreason
pour que Claude sache comment procéder.undefined
permet à Claude de s’arrêter.reason
est ignoré.
Exemple de Code de Sortie : Validation de Commande Bash
Exemple de Sortie JSON : UserPromptSubmit pour Ajouter du Contexte et de la Validation
Pour les hooks UserPromptSubmit
, vous pouvez injecter du contexte en utilisant l’une ou l’autre méthode :
- Code de sortie 0 avec stdout : Claude voit le contexte (cas spécial pour
UserPromptSubmit
) - Sortie JSON : Fournit plus de contrôle sur le comportement
Exemple de Sortie JSON : PreToolUse avec Approbation
Travailler avec les Outils MCP
Les hooks Claude Code fonctionnent parfaitement avec les outils Model Context Protocol (MCP). Lorsque les serveurs MCP fournissent des outils, ils apparaissent avec un motif de nommage spécial que vous pouvez faire correspondre dans vos hooks.
Nommage des Outils MCP
Les outils MCP suivent le motif mcp__<server>__<tool>
, par exemple :
mcp__memory__create_entities
- Outil de création d’entités du serveur Memorymcp__filesystem__read_file
- Outil de lecture de fichier du serveur Filesystemmcp__github__search_repositories
- Outil de recherche du serveur GitHub
Configuration des Hooks pour les Outils MCP
Vous pouvez cibler des outils MCP spécifiques ou des serveurs MCP entiers :
Exemples
Pour des exemples pratiques incluant le formatage de code, les notifications, et la protection de fichiers, voir Plus d’Exemples dans le guide de démarrage.
Considérations de Sécurité
Avertissement
UTILISEZ À VOS PROPRES RISQUES : Les hooks Claude Code exécutent des commandes shell arbitraires sur votre système automatiquement. En utilisant les hooks, vous reconnaissez que :
- Vous êtes seul responsable des commandes que vous configurez
- Les hooks peuvent modifier, supprimer, ou accéder à tous les fichiers auxquels votre compte utilisateur peut accéder
- Les hooks malveillants ou mal écrits peuvent causer une perte de données ou des dommages système
- Anthropic ne fournit aucune garantie et n’assume aucune responsabilité pour les dommages résultant de l’utilisation des hooks
- Vous devriez tester minutieusement les hooks dans un environnement sûr avant l’utilisation en production
Toujours réviser et comprendre toutes les commandes de hook avant de les ajouter à votre configuration.
Meilleures Pratiques de Sécurité
Voici quelques pratiques clés pour écrire des hooks plus sécurisés :
- Valider et assainir les entrées - Ne jamais faire confiance aveuglément aux données d’entrée
- Toujours citer les variables shell - Utiliser
"$VAR"
pas$VAR
- Bloquer la traversée de chemin - Vérifier
..
dans les chemins de fichiers - Utiliser des chemins absolus - Spécifier des chemins complets pour les scripts (utiliser
$CLAUDE_PROJECT_DIR
pour le chemin du projet) - Ignorer les fichiers sensibles - Éviter
.env
,.git/
, clés, etc.
Sécurité de Configuration
Les modifications directes des hooks dans les fichiers de paramètres ne prennent pas effet immédiatement. Claude Code :
- Capture un instantané des hooks au démarrage
- Utilise cet instantané tout au long de la session
- Avertit si les hooks sont modifiés extérieurement
- Nécessite une révision dans le menu
/hooks
pour que les changements s’appliquent
Cela empêche les modifications malveillantes de hooks d’affecter votre session actuelle.
Détails d’Exécution des Hooks
- Timeout : Limite d’exécution de 60 secondes par défaut, configurable par commande.
- Un timeout pour une commande individuelle n’affecte pas les autres commandes.
- Parallélisation : Tous les hooks correspondants s’exécutent en parallèle
- Environnement : S’exécute dans le répertoire courant avec l’environnement de Claude Code
- La variable d’environnement
CLAUDE_PROJECT_DIR
est disponible et contient le chemin absolu vers le répertoire racine du projet
- La variable d’environnement
- Entrée : JSON via stdin
- Sortie :
- PreToolUse/PostToolUse/Stop : Progrès montré dans le transcript (Ctrl-R)
- Notification : Enregistré en debug uniquement (
--debug
)
Débogage
Dépannage de Base
Si vos hooks ne fonctionnent pas :
- Vérifier la configuration - Exécuter
/hooks
pour voir si votre hook est enregistré - Vérifier la syntaxe - S’assurer que vos paramètres JSON sont valides
- Tester les commandes - Exécuter les commandes de hook manuellement d’abord
- Vérifier les permissions - S’assurer que les scripts sont exécutables
- Réviser les logs - Utiliser
claude --debug
pour voir les détails d’exécution des hooks
Problèmes communs :
- Guillemets non échappés - Utiliser
\"
dans les chaînes JSON - Mauvais matcher - Vérifier que les noms d’outils correspondent exactement (sensible à la casse)
- Commande non trouvée - Utiliser des chemins complets pour les scripts
Débogage Avancé
Pour les problèmes de hooks complexes :
- Inspecter l’exécution des hooks - Utiliser
claude --debug
pour voir l’exécution détaillée des hooks - Valider les schémas JSON - Tester l’entrée/sortie des hooks avec des outils externes
- Vérifier les variables d’environnement - Vérifier que l’environnement de Claude Code est correct
- Tester les cas limites - Essayer les hooks avec des chemins de fichiers ou entrées inhabituels
- Surveiller les ressources système - Vérifier l’épuisement des ressources pendant l’exécution des hooks
- Utiliser la journalisation structurée - Implémenter la journalisation dans vos scripts de hooks
Exemple de Sortie de Debug
Utiliser claude --debug
pour voir les détails d’exécution des hooks :
Les messages de progrès apparaissent en mode transcript (Ctrl-R) montrant :
- Quel hook s’exécute
- Commande en cours d’exécution
- Statut de succès/échec
- Messages de sortie ou d’erreur