Hooks
Voici le problème lorsqu'on demande à Claude de faire quelque chose dans un fichier CLAUDE.md : c'est une demande, pas une garantie. Vous pouvez écrire « formate toujours après modification » et Claude écoutera généralement. Généralement. Mais sur une longue exécution que vous ne surveillez pas, « généralement » ne suffit pas. Un hook corrige cela. Un hook est du code déterministe qui s'exécute à un point fixe de la boucle, ce qui lui permet de garantir un comportement plutôt que de l'espérer. Il transforme une règle de « Claude écoute généralement » en « Claude ne peut pas l'ignorer ».
C'est tout l'argument. Voyons maintenant comment cela fonctionne réellement.
Les événements de hook
Claude Code déclenche environ 30 événements de hook au cours d'une session. Vous n'avez pas besoin de tous les connaître, et la référence des hooks(s’ouvre dans un nouvel onglet) les répertorie tous. Il y en a une petite poignée que vous utiliserez encore et encore, et ils correspondent aux points de la boucle agentique où vous voudriez intervenir.
Voici comment ils s'inscrivent dans la boucle. Une session démarre, des requêtes arrivent, des outils sont appelés, et le tour finit par se terminer. Chacun de ces moments a un hook sur lequel vous pouvez accrocher du code.
Ceux qu'il vaut la peine de connaître :
- PreToolUse se déclenche avant un appel d'outil. C'est votre primitive d'application de règles. C'est celui qui peut arrêter quelque chose avant que cela ne se produise.
- PostToolUse se déclenche après un appel d'outil réussi. C'est généralement là que va le formatage automatique ou le linting automatique.
- Stop se déclenche lorsque Claude veut mettre fin à son tour. Vous pouvez refuser et dire « non, tu n'as pas encore terminé » si une condition n'est pas remplie. Il existe un SubagentStop correspondant pour lorsqu'un sous-agent termine.
- PreCompact et PostCompact se déclenchent avant et après la compaction.
- InstructionsLoaded se déclenche lorsqu'un fichier CLAUDE.md ou un fichier de règles se charge. Pratique pour vérifier ce qui a réellement été intégré au contexte.
- SessionStart se déclenche au démarrage et prépare l'environnement. Utilisez la source
startupsi vous ne le voulez que pour les démarrages à neuf.
Un point qui piège les gens : pour réinjecter du contexte après une compaction, n'utilisez pas PostCompact. Utilisez SessionStart avec le matcher compact. C'est celui-là qui parvient réellement à renvoyer sa sortie dans la conversation.
PreToolUse : renvoyer une décision au format JSON
PreToolUse est l'endroit où se trouve le véritable pouvoir, car il peut bloquer un appel d'outil avant son exécution. La façon de répondre à Claude consiste à imprimer du JSON et à quitter avec le code zéro. Le champ clé est permissionDecision, et il prend l'une de trois valeurs :
allow— laisser passer l'appeldeny— arrêter l'appelask— renvoyer la décision à l'utilisateur
Il existe techniquement une quatrième valeur, defer, mais elle ne s'applique qu'aux exécutions non interactives -p où un processus appelant met l'outil en pause et le reprend plus tard. Vous en aurez rarement besoin.
Voici à quoi ressemble la structure :
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Don't push to main. Open a pull request instead."
}
}Au lieu de bloquer un appel, vous pouvez le réécrire. Renvoyez allow ou ask avec updatedInput. Avec ask, vous voyez l'appel réécrit et vous l'approuvez. Avec allow, il s'exécute sans invite :
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"updatedInput": {
"command": "..."
}
}
}C'est ainsi que vous pourriez expurger un secret d'une commande bash tout en la laissant s'exécuter. Un point d'attention : updatedInput remplace l'objet d'entrée entier, vous devez donc renvoyer en écho les champs que vous ne modifiez pas, sinon vous les perdrez.
Codes de sortie, pour les hooks qui ne renvoient pas de JSON
Tous les hooks n'ont pas besoin de parler JSON. Pour les hooks plus simples, les codes de sortie font l'affaire. Il y a trois chiffres qui comptent.
- 0 est un succès. Si la sortie standard est du JSON, Claude l'analyse. Le texte brut est ignoré sur la plupart des événements, mais sur SessionStart, UserPromptSubmit et UserPromptExpansion, le texte brut est ajouté au contexte. C'est exactement ce qui fait fonctionner un hook de préservation d'état.
- 2 est une erreur bloquante. L'erreur standard est renvoyée à Claude en tant que contexte. C'est le code de sortie bloquant presque partout.
- Toute autre valeur n'est pas bloquante. L'erreur standard est enregistrée, et Claude poursuit.
Celui qui piège les gens est le code de sortie 1. Il donne l'impression d'une erreur, mais il ne bloque pas. Claude exécute la commande quand même. Donc si vous vouliez arrêter quelque chose, utilisez la sortie 2, pas 1.
Encore quelques subtilités. La sortie 2 peut même bloquer Stop, c'est ainsi que vous dites à Claude qu'il n'a pas terminé. Mais PostToolUse se déclenche après l'exécution de l'outil, donc bloquer à ce stade-là est trop tard pour arrêter l'appel, même s'il peut toujours renvoyer du texte à Claude. Et quelques événements ignorent totalement le blocage, comme Notification et SessionStart. SessionStart ne vous affiche l'erreur standard qu'à vous, Notification l'ignore, et les deux poursuivent quoi qu'il en soit.
Un vrai garde-fou : expurger au lieu de bloquer
Mettons cela en pratique avec quelque chose de concret. Supposons que vous vouliez un garde-fou PreToolUse sur l'outil Bash. Vous enregistrez un hook dans un fichier de paramètres. Mettez celui-ci dans .claude/settings.json et validez-le, et votre équipe pourra le partager :
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/redact-secrets.sh",
"args": []
}
]
}
]
}
}Le matcher choisit l'outil à surveiller, et un champ if optionnel sur le hook peut le restreindre à une commande spécifique, comme "if": "Bash(curl *)". Exécutez /hooks pour vérifier que le hook est bien enregistré.
L'option évidente est de renvoyer deny et d'arrêter un appel dangereux. C'est bien. Mais l'option moins connue et plus intéressante consiste à renvoyer updatedInput pour réécrire l'appel. C'est ainsi que vous pouvez retirer un secret d'une commande tout en la laissant s'exécuter, au lieu de simplement la refuser.
Voici à quoi cela ressemble en pratique. On demande à Claude d'exécuter une commande qui inclut un secret qui a l'air réel. Le hook l'intercepte, repère le motif sk_live_, et le remplace par un espace réservé avant même que la commande ne s'exécute.
Voici le script, .claude/hooks/redact-secrets.sh. Il a besoin de jq, et vous le rendez exécutable avec chmod +x :
#!/bin/bash
# Remplace les clés d'apparence réelle avant l'exécution de la commande.
jq 'if (.tool_input.command // "" | test("sk_live_\\w+")) then {
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "ask",
permissionDecisionReason: "Replaced a live key with a placeholder",
updatedInput: (.tool_input | .command |= gsub("sk_live_\\w+"; "REDACTED"))
}
} else empty end'Il renvoie ask, vous approuvez donc la commande réécrite. Renvoyer allow contournerait cette invite pour chaque commande correspondant au motif. Une fois que vous l'approuvez, la commande s'exécute sans le secret. C'est la différence entre bloquer et expurger, et c'est le genre de chose qu'un hook peut faire respecter à chaque fois.
Préserver l'état à travers une compaction
Un autre schéma qui vaut la peine d'être mis en place. Lorsque Claude compacte une longue conversation, il perd beaucoup de détails. Un hook SessionStart avec le matcher compact s'exécute juste après la compaction. Faites-lui imprimer un court résumé des fichiers sur lesquels vous avez travaillé. Ce résumé retourne dans le contexte, de sorte que Claude reprend là où il s'était arrêté au lieu de repartir à froid. Celui-ci liste vos modifications non validées :
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [{ "type": "command", "command": "git status --short" }]
}
]
}
}Pour conclure
Les hooks transforment une règle que Claude suit généralement en une règle qu'il suit toujours. Allez au-delà du formatage automatique : protégez les outils avec PreToolUse, verrouillez le tour avec Stop, et préservez l'état à travers une compaction. La mise en place demande un peu d'effort au départ, mais cela rapporte dès la première fois où cela intercepte quelque chose lors d'une exécution que vous ne surveilliez même pas.