Claude Code Hooks : settings.json, les 5 événements et le blocage par exit code
Les hooks sont la couche déterministe de Claude Code : ils s'exécutent toujours, sans qu'on ait à le demander. Ce pas-à-pas illustré emprunte ses images à la vidéo officielle d'Anthropic sur les hooks — les cinq événements, un script de blocage PreToolUse, un JSON deny structuré et une config de formatage PostToolUse complète.
TL;DR — ce que sont les hooks de Claude Code
- Les hooks sont déterministes : ils s'exécutent à des points fixes du cycle de vie de Claude Code, à chaque fois. Une consigne CLAUDE.md du genre « lance Prettier après chaque édition » fonctionne la plupart du temps — un hook fonctionne toujours.
- Cinq événements existent : UserPromptSubmit (avant le traitement de votre prompt), PreToolUse (avant un appel d'outil), PostToolUse (après la fin d'un outil), Notification et Stop (quand Claude a fini de répondre).
- Un hook PreToolUse qui se termine avec exit code 2 bloque l'appel d'outil, et le message stderr est renvoyé à Claude pour qu'il comprenne pourquoi. Exit code 0 laisse passer l'appel.
- Les hooks vivent dans settings.json — un événement, un matcher d'outils optionnel et une commande. Gardez-les dans le .claude/settings.json du projet et commitez-le : toute l'équipe hérite des mêmes garanties.
Hooks in Claude Code
Chaîne:Claude (official Anthropic channel)3:22
Claude Code Hooks, Explained Simply
Chaîne:Agentic Lab8:32
Claude Code - Getting Started with Hooks
Chaîne:Greg Baugues11:53
Hooks reference — Claude Code documentation
Doc:code.claude.com
Les images de ce guide viennent de la vidéo explicative officielle d'Anthropic sur les hooks ; le texte du pas-à-pas a été rédigé indépendamment et confronté à la référence officielle des hooks.
Les captures d'écran restent la propriété de leurs auteurs et servent ici de documentation visuelle avec attribution. Chaque étape renvoie par lien profond à l'instant exact de la vidéo source.
Configurer les hooks de Claude Code, pas à pas
1 · Les hooks en situation réelle
- 1
Voir un hook se déclencher en fin de réponse
La barre d'état affiche « Running stop hook · 39s · 484 tokens » — Claude Code exécute un hook Stop avant de vous rendre la main. Toute l'idée tient dans ce screenshot : une commande que vous avez enregistrée s'exécute à un point fixe du cycle de vie, à chaque occurrence, sans rien devoir à la mémoire du modèle.
Un hook Stop qui s'exécute après la réponse de Claude — 39 secondes, 484 tokens dépensés.Regarder à 0:10 - 2
Apprendre les cinq événements de hook
UserPromptSubmit s'exécute dès que vous envoyez un prompt, avant que Claude ne le traite. PreToolUse s'exécute avant chaque appel d'outil. PostToolUse après la fin d'un appel. Notification se déclenche quand Claude envoie une notification, et Stop quand Claude a fini de répondre. Chaque hook que vous écrivez se raccroche à l'un de ces cinq points, et un seul.
Les cinq événements, d'après la vidéo officielle d'Anthropic sur les hooks — tout le reste pend à cette liste.Regarder à 1:04
2 · Écrire ses premiers hooks
- 3
Ajouter un bloc hooks à settings.json
Un hook dans settings.json, c'est trois choses : le nom de l'événement, un matcher optionnel qui restreint les outils concernés, et la commande à exécuter. Sur le screenshot, l'autocomplétion complète le matcher PreToolUse avec Edit — ce hook ne se déclenchera que sur les appels d'édition de fichiers. Si vous préférez ne pas toucher au JSON, le menu /hooks édite la même configuration de façon interactive.
L'autocomplétion propose Edit, cantonnant le hook PreToolUse aux éditions de fichiers.Regarder à 0:14 - 4
Bloquer des commandes dangereuses avec exit code 2
Un hook PreToolUse reçoit le nom de l'outil et son entrée en JSON sur stdin. Ce script le passe à jq pour extraire .tool_input.command, cherche avec grep des motifs destructeurs — rm -rf, git push --force — et en cas de correspondance affiche la raison sur stderr et sort avec le code 2. Exit code 2 bloque l'appel ; le texte stderr est renvoyé à Claude en feedback : le modèle sait pourquoi il a été bloqué et s'ajuste.
jq lit la commande depuis stdin ; une correspondance rm -rf ou --force écrit sur stderr et sort en code 2.Regarder à 2:02 - 5
Envoyer un refus structuré plutôt qu'un exit code
Pour un contrôle plus fin, un hook peut imprimer une décision JSON au lieu de compter sur les exit codes. Ici, un hook PreToolUse attrape DROP TABLE et le hookSpecificOutput transporte un permissionDecision « deny » avec sa raison — « utilise plutôt une migration » — qui atterrit dans le contexte du modèle. Même garantie stricte, avec une consigne actionnable en bonus.
Un permissionDecision à deny bloque la commande SQL et indique au modèle quoi faire à la place.Regarder à 2:16 - 6
Garder les hooks dans le dépôt pour que l'équipe en profite
Les hooks configurés dans le .claude/settings.json du projet sont de niveau projet et se committent. Tous ceux qui clonent le dépôt exécutent les mêmes hooks automatiquement — y compris les bloquants. Rangez les scripts utilitaires dans .claude/hooks/ et référencez-les via la variable d'environnement CLAUDE_PROJECT_DIR : les chemins se résolvent quel que soit le répertoire courant de Claude.
Le dossier .claude du projet contient settings.json et un répertoire hooks/ de scripts partagés.Regarder à 0:17 - 7
Copier une config de hooks complète et réaliste
Cette config fait deux travaux d'un coup. Le bloc PostToolUse matche Edit|Write|MultiEdit et lance .claude/hooks/auto-format.sh avec un timeout de 30 secondes : chaque fichier touché par Claude est formaté. En dessous, un second hook matche Bash et journalise chaque commande exécutée — le grand classique de la conformité. Les champs timeout et async empêchent les formateurs lents de bloquer la session.
Auto-formatage PostToolUse avec timeout de 30 s, plus un hook Bash qui journalise chaque commande.Regarder à 2:46
3 · Les exploiter en équipe
- 8
Connaître le contrat des exit code par cœur
Exit code 0 : on continue. Exit code 2 : blocage — et le stderr est transmis à Claude comme un feedback sur lequel il peut agir. Tout autre exit code affiche le stderr à vous, l'utilisateur, mais l'appel continue : pratique pour des avertissements qu'on veut voir sans stopper net l'agent.
- 9
Enregistrer les hooks via le menu /hooks et choisir ses recettes
La commande /hooks ouvre la même configuration de façon interactive — utile pour vérifier quels hooks sont enregistrés à quel périmètre. Viennent ensuite les quatre recettes de chevet : auto-formatage après édition (PostToolUse), journal de toutes les commandes exécutées (PostToolUse sur Bash), blocage des opérations dangereuses (PreToolUse avec exit 2) et notification de fin de tâche (Stop). Ce qui doit arriver à chaque coup sans exception ne se met pas dans un prompt — ça se met dans un hook.
Le contrat des exit code, en un tableau
Chaque commande de hook communique par son exit code. Trois cas suffisent :
- exit 0Continuer. L'appel d'outil s'exécute normalement. Le stdout du hook est visible en mode transcript (Ctrl-R).
- exit 2Bloquer. L'appel est refusé et le stderr du hook est renvoyé à Claude en feedback : le modèle peut corriger le tir — c'est ce qui rend les hooks exit-2 pédagogiques et pas seulement fatals.
- exit 1Tout autre code : prévenir sans bloquer. Le stderr vous est montré mais l'appel continue. Parfait pour les hooks consultatifs — « ce fichier est généralement généré, vous êtes sûr ? »
Une voie d'évolution : au lieu des exit codes, un hook peut imprimer une décision JSON (hookSpecificOutput avec permissionDecision) pour refuser avec une raison structurée, comme à l'étape 5. Les exit codes forment le contrat simple ; les décisions JSON, le contrat typé.
Quatre recettes à committer dès aujourd'hui
La vidéo officielle cite quatre cas d'usage ; les voici en intentions prêtes à copier :
- 1Auto-formatage après édition — un hook PostToolUse sur Edit|MultiEdit vérifie l'extension du fichier et lance le bon formateur : Prettier pour TypeScript, gofmt pour Go, Ruff pour Python.
- 2Journaliser chaque commande exécutée — un hook PostToolUse sur Bash qui ajoute chaque commande à un fichier. Les équipes de conformité adorent ; vous, en train de debugger ce qui a tourné mardi dernier, adorerez aussi.
- 3Bloquer les opérations dangereuses — un hook PreToolUse avec exit 2 qui protège les répertoires de config de prod, les motifs rm -rf ou les commits sur main. Ce sont des garanties, plus des suggestions.
- 4Notifier la fin d'une tâche — un hook Stop ou Notification qui déclenche une notification bureau ou un son, pour les longues sessions d'agent qu'on n'a pas envie de surveiller.
Les quatre tiennent dans un même .claude/settings.json. Commencez par le formateur — c'est le hook que vous sentirez à chaque sauvegarde.