Quiconque utilise Claude Code depuis plus d'une semaine a déjà connu ce moment. Vous ajoutez une ligne dans votre CLAUDE.md indiquant de ne pas créer de nouveaux fichiers sans autorisation. L'agent obéit sagement. Puis, après quarante minutes d'une longue session, il crée quatre fichiers que vous n'avez jamais demandés.
Le premier réflexe est d'écrire la règle avec plus d'insistance. La mettre en gras. Tout en haut. En MAJUSCULES. Ce réflexe est mauvais, et comprendre pourquoi est tout l'intérêt des hooks.
Que sont les hooks Claude Code ?
Les hooks Claude Code sont des scripts que l'environnement d'exécution lance automatiquement à des moments précis d'une session : avant l'appel d'un outil, lors de la soumission d'un prompt ou quand l'agent tente de s'arrêter. Claude Code transmet au hook une description JSON de l'événement via stdin, l'exécute et lit le code de sortie ainsi que stdout. Le modèle n'est jamais consulté.
Cette dernière phrase résume toute leur valeur. Tout ce que vous mettez dans un fichier markdown est du contexte qui rivalise avec le reste de la fenêtre pour capter l'attention du modèle. Tout ce que vous mettez dans un hook est un programme. Le modèle peut survoler votre CLAUDE.md. Il ne peut pas survoler un code de sortie.
Une règle est une demande. Un hook est une application stricte.
Les deux ont leur place dans une configuration saine, pour des rôles différents. CLAUDE.md explique l'intention, les préférences et ce qui relève du jugement. Un hook porte les règles qui doivent s'appliquer systématiquement, peu importe la durée de la session ou le niveau de confiance du modèle. Posez-vous une seule question pour chaque règle : que se passe-t-il si l'agent l'ignore une seule fois ?
Si la réponse est « un commit un peu moins propre », laissez-la en markdown. Si la réponse est « il supprime une table » ou « il écrit quatre cents lignes avant que j'aie pu dire ce que je voulais », alors cette règle n'a rien à faire dans du texte. Elle doit être codée.
Un hook répond de deux manières. Soit il s'arrête avec un code de sortie, où 2 est le signal de blocage et Claude Code renvoie votre stderr au modèle pour lui expliquer pourquoi. Soit il s'arrête avec un code 0 et affiche du JSON, ce qui vous permet de renvoyer une vraie décision d'autorisation : allow, deny ou ask. Le piège classique est que le code exit 1, l'échec Unix conventionnel, ne bloque absolument rien.
Les huit événements, et ce que nous y avons associé
Claude Code déclenche des hooks tout au long du cycle de vie d'une session, pas seulement lors des appels d'outils. kitstarter livre huit scripts répartis sur huit de ces événements. Voici le tableau que notre installateur écrit dans votre settings.json, et c'est la réponse la plus honnête que nous puissions donner à la question : « que faire concrètement avec des hooks ? »
Deux de ces lignes méritent qu'on s'y attarde, car elles sont opposées, et leur différence résume toute notre philosophie de conception.
Le seul endroit où nous bloquons strictement, et celui où nous nous y refusons
Le hook de clarté bloque. Pour tout Edit, Write, MultiEdit ou NotebookEdit, il renvoie une décision de refus (deny) tant que vous n'avez pas confirmé ce que vous voulez vraiment, puis il lève la restriction. C'est un vrai verrou, pas une simple incitation. L'agent ne peut pas écrire votre premier fichier tant que l'objectif n'est pas validé.
Le garde-fou refuse de bloquer. Il surveille Bash, reconnaît les commandes destructrices et se contente d'avertir. L'explication figure dans le fichier lui-même : un kit qui bloque systématiquement vos commandes finit par être désinstallé. Avoir raison sur une commande dangereuse ne sert à rien si l'utilisateur supprime tout au bout d'une semaine.
C'est la règle d'or à adopter. Bloquez là où le coût d'une erreur est élevé et où demander confirmation ne coûte rien. Avertissez partout ailleurs. Un hook trop bloquant est un hook qui finit à la corbeille, et un hook supprimé ne sert plus à rien.
Les deux échouent sans bloquer. En cas d'erreur dans le hook, il reste silencieux et vous laisse travailler. Une fonctionnalité d'accompagnement ne vaut jamais la peine de bloquer une session.
L'impact réel des hooks, chiffres à l'appui
Toutes les autres pages sur les hooks Claude Code expliquent l'API. Presque aucune ne vous dit ce qui change concrètement quand ils s'exécutent, car cela demande de les mettre en production et de mesurer les résultats. Nous avons mené des tests en environnement contrôlé : même modèle, mêmes conversations scénarisées en mode vibe coding, un bac à sable neuf par groupe, un groupe avec les hooks et un groupe sans.
Les deux dernières lignes comptent plus que les quatre premières. Les hooks ne sont pas gratuits. Sur une tâche déjà sans ambiguïté, le moteur de clarté est un pur surcoût : il pose une question inutile et vous payez pour les tokens. C'est le prix honnête d'un socle minimal, et c'est le problème produit ouvert que nous cherchons actuellement à régler.
Par quoi commencer avec les hooks Claude Code
Vous n'avez pas besoin d'en avoir huit. Commencez par un seul, en choisissant celui qui cible l'erreur qui vous a fait perdre le plus de temps ce mois-ci.
Si votre agent commence à coder avant que vous ayez fini d'expliquer, verrouillez Edit et Write. S'il lance des commandes qui vous font peur, configurez une alerte sur Bash. S'il se déclare fini sans vérifier, utilisez Stop pour faire de cette affirmation une étape vérifiée par l'environnement. Si vous lancez des sous-agents et remarquez qu'ils ignorent les règles suivies par l'agent principal, réinjectez-les lors de SubagentStart. Et si vous voulez simplement voir ce qui se passe, une barre de statut ne coûte rien et rapporte immédiatement.
Codez-le, commencez par journaliser, puis bloquez plus tard. Déployez progressivement : enregistrez l'événement sans bloquer, puis avertissez sur les schémas que vous reconnaissez, et ne bloquez que ce qui a réellement causé des dégâts. Un hook en qui vous avez confiance en vaut dix que vous avez désactivés.
Rien de tout cela ne nécessite de kit. Les hooks sont une fonctionnalité de Claude Code et la documentation est de qualité. Ce qu'un kit vous apporte, c'est ce qui nous a pris des mois : savoir quels événements méritent d'être connectés, quelles règles méritent d'être appliquées par du code plutôt que par du texte, et là où le blocage est contre-productif. Si vous préférez ne pas assembler tout cela vous-même, nous avons publié le nôtre, et vous pouvez lire exactement ce qu'il fait avant de l'installer.
L'intérêt de ce compromis dépend de l'erreur qui vous fait perdre du temps. Découvrez les trois profils qui achètent ce kit ainsi que les mesures avant et après pour chacun.
Questions fréquentes
Que sont les hooks Claude Code ? Les hooks Claude Code sont des scripts que Claude Code exécute automatiquement à des moments précis d'une session, comme avant l'appel d'un outil ou lors de la soumission d'un prompt. Claude Code transmet l'événement sous forme de JSON via stdin et lit le code de sortie ainsi que stdout. Comme c'est l'environnement d'exécution qui les lance, les hooks sont déterministes : ils s'exécutent que le modèle coopère ou non.
Quelle est la différence entre CLAUDE.md et un hook ? CLAUDE.md est un contexte que le modèle lit et peut survoler : une règle qui y est écrite est donc une simple demande. Un hook est du code exécuté par l'environnement, c'est donc une application stricte. Utilisez CLAUDE.md pour expliquer vos intentions et un hook pour toute règle qui doit s'appliquer systématiquement, comme le refus d'écrire des fichiers avant que l'objectif ne soit confirmé.
Un hook Claude Code peut-il bloquer l'agent ? Oui. Un hook PreToolUse peut renvoyer un code exit 2, ce qui bloque l'appel de l'outil et transmet votre stderr au modèle pour lui expliquer la raison, ou renvoyer un code exit 0 et afficher du JSON avec hookSpecificOutput.permissionDecision défini sur allow, deny ou ask. Le blocage est un outil puissant : réservez-le aux cas où une erreur coûte cher et où demander confirmation est simple.
Les hooks Claude Code ralentissent-ils l'agent ? Ils ont un coût. Dans notre test en environnement contrôlé, le kit avec hooks s'est révélé plus rapide et moins cher sur trois tâches sur cinq, car la demande préalable a évité de réécrire du code. En revanche, il a été environ deux fois plus lent et 75 % plus cher sur une tâche déjà claire, avec un surcoût moyen de 25 % dû aux tokens de contexte des hooks.
Placez vos règles là où l'agent ne peut pas les ignorer
kitstarter intègre huit hooks dans Claude Code, Codex et Antigravity pour qu'ils demandent confirmation avant de coder, restent légers et ne produisent pas de code typique d'une IA.