Hooks Claude Code : pourquoi chacun de mes 95 hooks existe
J’ai construit 95 hooks pour Claude Code. Chacun existe parce que quelque chose a d’abord mal tourné. Le git-safety-guardian existe parce que Claude a fait un force-push sur main. Le recursion-guard existe parce qu’un sous-agent a engendré des enfants à l’infini. Le blog-quality-gate existe parce que j’ai publié un article avec 7 phrases à la voix passive et une note de bas de page orpheline.1
Les hooks Claude Code sont des commandes shell qui s’exécutent à des points précis du cycle de vie (début de session, avant/après l’utilisation d’un outil, soumission de prompt et fin de réponse), offrant des garde-fous déterministes par-dessus le comportement probabiliste du LLM. Les hooks reçoivent du JSON sur stdin et renvoient des décisions (bloquer, autoriser ou modifier) via stdout et les codes de sortie. Ils appliquent des politiques telles que le blocage des force-pushes sur main, la prévention des spawns récursifs d’agents, l’injection de contexte par session et le contrôle qualité en sortie que le LLM seul ne peut garantir.
TL;DR
Les hooks Claude Code exécutent des commandes shell à des points précis du cycle de vie lors du développement assisté par IA. Les hooks offrent des garanties déterministes (blocage des commandes git dangereuses, injection de contexte, application de la qualité) par-dessus un système probabiliste (le LLM). Après avoir construit 95 hooks à travers mon infrastructure, j’ai constaté que les meilleurs hooks viennent des incidents, pas de la planification. Cet article couvre l’architecture, les histoires d’origine derrière mes hooks les plus critiques et les modèles que j’ai appris au cours de 9 mois de développement de hooks.
Mis à jour le 21 octobre 2026. J’ai corrigé les exemples PreToolUse ci-dessous pour utiliser hookSpecificOutput.permissionDecision, ainsi que les phrases sur les codes de sortie et l’exemple de configuration, qui suit désormais le schéma actuel des paramètres. Les champs de premier niveau decision et reason que montraient les exemples auparavant sont obsolètes pour cet événement. Cette correction fait suite au signalement d’un lecteur.
L’architecture
Claude Code expose 26 événements de cycle de vie où les hooks peuvent intercepter, modifier ou bloquer le comportement (en date de la v2.1.116, avril 2026).2 Mes hooks ciblent six des plus courants :
Événements de session
| Événement | Quand il se déclenche | Mes hooks |
|---|---|---|
| SessionStart | Nouvelle session commence | session-start.sh : injecte la date, valide le venv, initialise l’état de récursion |
| SessionEnd | La session se termine | Nettoyer les fichiers temporaires |
Événements d’exécution d’outils
| Événement | Quand il se déclenche | Mes hooks |
|---|---|---|
| PreToolUse | Avant l’exécution d’un outil | git-safety-guardian.sh, recursion-guard.sh, credentials-check.sh |
| PostToolUse | Après la fin de l’outil | post-deliberation.sh, log-bash.sh |
Événements de réponse
| Événement | Quand il se déclenche | Mes hooks |
|---|---|---|
| UserPromptSubmit | L’utilisateur envoie un prompt | Injecteurs de contexte (date, branche, infos sur le modèle) |
| Stop | Claude termine sa réponse | deliberation-pride-check.sh, reviewer-stop-gate.sh |
Chaque hook de type commande reçoit du JSON sur stdin et répond via son code de sortie, stdout et stderr. Un hook PreToolUse bloque l’appel en affichant ceci et en sortant avec le code 0 :
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Force push to main is prohibited"}}
Ou il ne signale aucune décision en n’affichant rien et en sortant avec le code 0, et l’appel suit alors le flux d’autorisation normal ; garder le silence ne l’approuve pas. Le code de sortie 2 bloque également, avec le stderr du hook comme motif, sauf si le hook a aussi affiché du JSON contenant une décision de blocage, auquel cas c’est le motif de cette décision qui l’emporte. La forme de premier niveau {"decision": "block", "reason": "..."} qu’utilisaient auparavant les hooks PreToolUse est obsolète pour cet événement : Claude Code convertit les anciennes valeurs "block" et "approve" en "deny" et "allow", écrivez donc les nouveaux hooks avec hookSpecificOutput. Les autres événements, dont PostToolUse et Stop, continuent d’utiliser decision et reason au premier niveau comme format actuel.3
Dans cet article, PreToolUse:Bash et PreToolUse:Task sont mes propres étiquettes pour un groupe de matcher PreToolUse portant respectivement sur l’outil Bash et sur l’outil des sous-agents, qui s’appelait Task à la publication de cet article et s’appelle Agent depuis la v2.1.63.9 Ce ne sont pas des clés de paramètres ; la section sur la configuration montre la structure réelle.7
Histoires d’origine : les hooks qui comptent le plus
Hook 1 : git-safety-guardian.sh (PreToolUse:Bash)
L’incident : lors d’une session Claude Code précoce, j’ai demandé à l’agent de « nettoyer l’historique git ». L’agent a exécuté git push --force origin main. Le force-push a écrasé trois jours de commits sur une branche partagée. J’ai récupéré à partir d’une sauvegarde locale, mais les 4 heures de récupération m’ont convaincu que le jugement probabiliste ne devrait jamais contrôler les opérations git destructrices.
Le hook :
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# Only check git commands
echo "$COMMAND" | grep -qE '\bgit\b' || exit 0
# Block force push to main/master
if echo "$COMMAND" | grep -qiE 'git\s+push\s+.*--force.*\b(main|master)\b'; then
cat << EOF
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Force push to main/master blocked by safety hook"}}
EOF
fi
La leçon : le hook ne cherche pas à comprendre l’intention. Il fait de la correspondance de motifs sur la chaîne de commande. Simple, déterministe, impossible à contourner par un prompting astucieux. L’agent peut toujours faire un force-push sur des branches de fonctionnalité (parfois légitime), mais main/master sont protégés de façon permanente.4
Interceptions à vie : 8 tentatives de force-push interceptées en 9 mois.
Hook 2 : recursion-guard.sh (PreToolUse:Task)
L’incident : en construisant le système de délibération, j’ai lancé une session qui a engendré 3 sous-agents d’exploration. Chaque sous-agent, n’ayant pas de limite de spawn, a engendré ses propres sous-agents. La récursion a consommé des tokens API à 10 fois le rythme normal. J’ai tué la session manuellement après avoir remarqué l’emballement du burn de tokens.
Le hook :
#!/bin/bash
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"
MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12
# Validate integers safely (((VAR++)) crashes with set -e when VAR=0)
is_positive_int() {
[[ "$1" =~ ^[0-9]+$ ]] && [[ "$1" -gt 0 ]]
}
La décision de conception clé : les agents héritent d’un budget de spawn de leur parent plutôt que d’incrémenter la profondeur. Un agent racine avec budget=12 peut répartir ce budget sur n’importe quelle forme d’arbre. Les limites basées sur la profondeur sont trop rigides (elles empêchent les chaînes profondes mais étroites qui sont parfaitement sûres).5
Blocages à vie : 23 tentatives de spawn emballées.
Hook 3 : blog-quality-gate.sh (Stop)
L’incident : j’ai publié un article de blog avec 7 phrases à la voix passive, une note de bas de page référencée dans le texte mais absente de la section des références, et « a été implémenté par l’équipe » comme phrase d’ouverture. L’article paraissait soigné dans mon éditeur, mais échouait à des contrôles de qualité basiques que tout relecteur humain attraperait.
Le hook : exécute mon linter de blog à 12 modules sur tout fichier de contenu de blog modifié. Vérifie la voix passive, les notes de bas de page orphelines, les meta-descriptions manquantes, les blocs de code non balisés et l’intégrité des citations. Chaque constat est spécifique : « Ligne 47 : voix passive détectée dans « a été implémenté par l’équipe ». Suggestion : « l’équipe a implémenté ». »
Le parallèle avec le retour humain : le hook critique le travail, pas l’opérateur. Il dit « la ligne 47 contient de la voix passive », pas « vous écrivez mal ». Le même principe qui rend le retour humain constructif rend le retour automatisé utile.
Le modèle derrière 95 hooks
L’architecture pilotée par configuration
Mes hooks ont évolué de valeurs codées en dur vers un comportement piloté par configuration :
~/.claude/configs/
├── recursion-limits.json # Depth, spawn budgets, timeouts
├── deliberation-config.json # Consensus thresholds per task type
├── consensus-profiles.json # security=85%, docs=50%
├── circuit-breaker.json # Failure mode configurations
└── file-scope-rules.json # Path-scoped hook application
Déplacer les seuils vers des configurations JSON m’a permis d’ajuster le comportement sans éditer les scripts bash. Lorsque j’ai eu besoin d’un consensus lié à la sécurité à 85 % mais à 50 % pour la documentation, le changement de configuration a pris 30 secondes. Un changement de code aurait nécessité édition, test et redéploiement.6
Le modèle de superposition du cycle de vie
Mes 95 hooks forment un filet de sécurité à quatre couches :
Couche 1 : prévention (PreToolUse) : arrêter les mauvaises choses avant qu’elles n’arrivent. git-safety-guardian, credentials-check, recursion-guard.
Couche 2 : contexte (UserPromptSubmit, SessionStart) : injecter les informations dont l’agent a besoin. Date, branche, contexte du projet, entrées mémoire, principes philosophiques.
Couche 3 : validation (PostToolUse) : vérifier que les actions réalisées respectent les standards. Vérification de consensus post-délibération, journalisation des sorties.
Couche 4 : qualité (Stop) : contrôler la sortie finale. Pride check, quality gate, reviewer stop gate. Cette couche met en œuvre la surveillance métacognitive où l’agent évalue la qualité de son propre raisonnement, pas seulement sa sortie.
Chaque couche est indépendante. Si un hook PreToolUse échoue silencieusement, le hook Stop attrape toujours les problèmes de qualité. Défense en profondeur, appliquée au comportement de l’agent IA.
Configuration
Les hooks vivent dans .claude/settings.json :
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/git-safety-guardian.sh", "timeout": 5 }
]
},
{
"matcher": "Agent",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/recursion-guard.sh" }
]
}
]
}
}
La configuration comporte trois niveaux : l’événement, un groupe de matcher qui filtre les appels d’outils pour lesquels il se déclenche, et les handlers qui s’exécutent en cas de correspondance. timeout s’exprime en secondes, avec 600 par défaut pour un hook de type commande sur la plupart des événements, PreToolUse compris. PreToolUse:Task, l’étiquette de la section sur l’architecture, correspond ici au second groupe : un groupe PreToolUse dont le matcher est Agent. Les hooks asynchrones ("async": true) s’exécutent en arrière-plan sans bloquer, ce qui signifie aussi qu’ils ne peuvent rien bloquer ni décider.7
Hiérarchie de portée
- Niveau utilisateur (
~/.claude/settings.json) : s’applique à tous les projets. Mes 95 hooks vivent ici. - Niveau projet (
.claude/settings.json) : ajoute des hooks spécifiques au projet. - Frontmatter Skill/Subagent : limité au cycle de vie d’un composant spécifique.8
Ce que je ferais différemment
Commencez par 3 hooks, pas 25. Mon premier mois a produit 25 hooks, dont beaucoup ajoutaient du contexte que l’agent avait déjà. Le surcoût du chargement de 25 hooks à chaque appel d’outil était mesurable. J’ai fini par élaguer pour ne garder que les hooks qui produisaient une vraie valeur (prévenant de vrais incidents, attrapant de vrais problèmes de qualité).
Pilotage par configuration dès le premier jour. J’ai passé deux semaines à refactoriser les seuils codés en dur vers des configurations JSON. Cette refactorisation aurait été gratuite si j’avais commencé avec des configurations.
Infrastructure de test tôt. Les 20 premiers hooks n’avaient pas de tests. Lorsque j’ai ajouté le harnais de test (48 tests d’intégration bash), j’ai trouvé 3 hooks qui échouaient silencieusement sur des cas limites. Les tests auraient dû être livrés avec le hook n°1.
Points clés à retenir
Pour les développeurs qui débutent avec les hooks : - Commencez par trois hooks : sécurité git (PreToolUse:Bash), injection de contexte (UserPromptSubmit) et contrôle qualité (Stop) ; n’en ajoutez d’autres que lorsque vous avez des incidents qui les justifient - Utilisez le cadre de timing des décisions : l’architecture des hooks est irréversible (95 hooks en dépendent), donc investissez dans le modèle de cycle de vie avant d’écrire des hooks
Pour les équipes qui standardisent les hooks : - Standardisez les hooks au niveau utilisateur pour que chaque membre de l’équipe obtienne les mêmes garde-fous de sécurité - Suivez les métriques des hooks (opérations bloquées, incidents interceptés) pour justifier le coût de maintenance - Passez en revue les journaux de hooks chaque mois pour identifier de nouveaux motifs qui méritent d’être automatisés
FAQ
Que sont les hooks Claude Code ?
Les hooks sont des scripts shell qui s’exécutent à des points précis du cycle de vie lors des sessions Claude Code. Ils se déclenchent de façon déterministe à des moments précis : avant l’exécution d’un outil (PreToolUse), après sa fin (PostToolUse), lorsque vous envoyez un prompt (UserPromptSubmit), lorsqu’une session commence (SessionStart) et lorsque Claude termine sa réponse (Stop). Les hooks reçoivent du JSON sur stdin avec le contexte complet (nom de l’outil, entrée, ID de session) et peuvent bloquer des opérations, injecter du contexte ou imposer des contrôles qualité. Ils offrent des garanties déterministes par-dessus un LLM probabiliste.
Combien de hooks Claude Code peut-il exécuter et y a-t-il un coût en performance ?
Il n’y a pas de limite stricte sur le nombre de hooks. J’exécute 95 hooks à travers 6 des 26 événements de cycle de vie disponibles (en date de la v2.1.116, avril 2026), avec environ 200 ms de surcoût total par événement. La limite pratique est la latence : chaque hook ajoute du temps d’exécution avant ou après les appels d’outils. L’optimisation clé consiste à utiliser des dispatchers (un par événement, exécutant les hooks séquentiellement à partir de stdin en cache) plutôt que des hooks indépendants qui lisent chacun stdin séparément. Les écritures concurrentes depuis des hooks indépendants provoquaient une corruption du JSON dans ma configuration initiale ; les dispatchers ont entièrement éliminé ce mode de défaillance.
Sur quels événements les hooks Claude Code se déclenchent-ils ?
Claude Code expose 26 événements de cycle de vie pour les hooks en date de la v2.1.116 (avril 2026). Les six plus courants que mes hooks ciblent sont : SessionStart (nouvelle session commence), SessionEnd (la session se termine), PreToolUse (avant l’exécution d’un outil), PostToolUse (après la fin de l’outil), UserPromptSubmit (l’utilisateur envoie un prompt) et Stop (Claude termine sa réponse). D’autres incluent SubagentStart, PermissionRequest, PermissionDenied, TaskCreated, CwdChanged, FileChanged, PreCompact et davantage. PreToolUse et PostToolUse peuvent être affinés avec un matcher sur le nom de l’outil, Bash ou Agent par exemple ; PreToolUse:Bash et PreToolUse:Task sont les raccourcis de cet article pour ces groupes. Chaque événement reçoit du JSON sur stdin avec le contexte pertinent.
Les hooks Claude Code peuvent-ils bloquer des appels d’outils ?
Oui. Un hook PreToolUse qui émet {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "explanation"}} sur stdout et sort avec le code 0 empêche l’appel d’outil de s’exécuter, et le code de sortie 2 le bloque aussi, avec stderr comme motif, sauf si le hook a également émis du JSON contenant une décision de blocage. L’ancienne forme de premier niveau {"decision": "block", "reason": "explanation"} est obsolète pour PreToolUse ; Claude Code la convertit en "deny", et d’autres événements comme PostToolUse et Stop l’utilisent toujours comme format actuel. C’est le mécanisme central pour les hooks de sécurité : mon git-safety-guardian bloque les force-pushes sur main, mon credentials-check bloque les lectures des fichiers .env, et mon recursion-guard bloque les spawns excessifs d’agents. Le blocage est déterministe et ne peut pas être contourné par le prompting. Un hook qui sort avec le code 0 sans rien émettre n’a aucune décision à signaler : l’opération suit donc le flux d’autorisation normal.
Quelle est la différence entre les hooks PreToolUse et PostToolUse ?
PreToolUse se déclenche avant l’exécution d’un outil et peut bloquer entièrement l’opération. Utilisez-le pour les barrières de sécurité : bloquer des commandes dangereuses, vérifier les identifiants, appliquer des budgets de spawn. PostToolUse se déclenche après la fin de l’outil et peut fournir un retour ou déclencher des actions de suivi. Utilisez-le pour la validation : vérifier la qualité de la sortie, journaliser l’activité, vérifier le consensus. Ensemble, ils forment les première et troisième couches d’un filet de sécurité à quatre couches : prévention (PreToolUse), injection de contexte (UserPromptSubmit), validation (PostToolUse) et contrôle qualité (Stop).
Références
-
Infrastructure de hooks de l’auteur. 95 hooks à travers 6 des 26 événements de cycle de vie disponibles (v2.1.116, avril 2026), développés sur 9 mois (2025-2026). ↩
-
Anthropic, « Claude Code Hooks Reference », 2026. 26 types d’événements de cycle de vie en date de la v2.1.116 (avril 2026). ↩
-
Anthropic, « Hooks reference », documentation de Claude Code, consultée le 21 octobre 2026. Contrôle des décisions de PreToolUse : « PreToolUse previously used top-level
decisionandreasonfields, but these are deprecated for this event. UsehookSpecificOutput.permissionDecisionandhookSpecificOutput.permissionDecisionReasoninstead. The deprecated values"approve"and"block"map to"allow"and"deny"respectively. Other events like PostToolUse and Stop continue to use top-leveldecisionandreasonas their current format. » Code de sortie 2 sur PreToolUse : « Blocks the tool call » ; « The message that comes with the block is your hook’s stderr. » Code de sortie 0 : « Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal permission flow. The hook can deny the call, but staying silent doesn’t approve it. » Code de sortie 2 avec JSON : « If your hook also printed JSON that makes a blocking decision, Claude Code uses that decision’s reason instead. » ↩ -
git-safety-guardian.sh de l’auteur. 8 tentatives de force-push interceptées suivies dans
~/.claude/state/. ↩ -
recursion-guard.sh de l’auteur. Modèle d’héritage de budget documenté dans
~/.claude/configs/recursion-limits.json. ↩ -
Architecture pilotée par configuration de l’auteur. 14 fichiers de configuration JSON encodant tous les seuils et règles des hooks. ↩
-
Anthropic, « Hooks reference », documentation de Claude Code, consultée le 21 octobre 2026. Configuration : « The configuration has three levels of nesting », à savoir « Choose a hook event to respond to, like PreToolUse or Stop », « Add a matcher group to filter when it fires, like “only for the Bash tool” » et « Define one or more hook handlers to run when matched ». Champs communs :
typevaut « command », « http », « mcp_tool », « prompt » ou « agent » ;timeout: « Seconds before canceling. Claude Code doesn’t enforce it on a command hook you run with async: true. Defaults: 600 for command, http, and mcp_tool; 30 for prompt; 60 for agent. Claude Code lowers the command, http, and mcp_tool default to 30 on UserPromptSubmit, PreModelSwitch, and PostModelSwitch, and to 10 on MessageDisplay. » Champasyncdes hooks de type commande : « If true, runs in the background without blocking. » Hooks en arrière-plan : « Async hooks can’t block or control Claude’s behavior: response fields like decision, permissionDecision, and continue have no effect, because the action they would have controlled has already completed. » Matcher de PreToolUse : « Matches on any tool name except EndConversation: built-in tools such as Bash, PowerShell, Edit, Write, Read, Glob, Grep, Agent, Workflow, WebFetch, WebSearch, AskUserQuestion, and ExitPlanMode, and any MCP tool names. » ↩↩ -
Anthropic, « Claude Code Documentation », 2025. Hiérarchie de portée des hooks. ↩
-
Anthropic, « Create custom subagents », documentation de Claude Code, consultée le 21 octobre 2026 : « In version 2.1.63, the Task tool was renamed to Agent. Existing
Task(...)references in settings and agent definitions still work as aliases. » ↩