Que sont les hooks Claude Code ?
Les hooks Claude Code sont des commandes shell qui s’exécutent automatiquement à des moments précis du cycle de vie de l’agent, par exemple avant le lancement d’un outil ou à la fin d’un tour. Comme ils s’exécutent à chaque fois au lieu de dépendre du modèle, ils constituent un moyen fiable d’imposer des règles et d’ajouter des contrôles.
Événements
Les hooks se définissent dans des fichiers settings.json et se rattachent à un événement. Pour les événements d’outils, un matcher permet de cibler des outils précis, comme Bash ou Edit.
- PreToolUse : avant l’exécution d’un outil ; il peut bloquer l’appel.
- PostToolUse : après la fin d’un outil, par exemple pour formater le fichier modifié.
- UserPromptSubmit : avant que votre message n’atteigne le modèle.
- Stop : quand l’agent termine son tour.
- SessionStart : au début d’une session, utile pour ajouter du contexte.
- Notification : quand Claude Code envoie une notification.
Comment ça marche
La commande du hook reçoit les détails de l’événement, comme le nom et l’entrée de l’outil, en JSON sur l’entrée standard. Son code de sortie dit à Claude Code quoi faire : 0 signifie continuer, et 2 bloque l’action et transmet le message d’erreur au modèle. Pour un contrôle plus fin, un hook peut aussi renvoyer une décision et une raison en JSON.
À quoi les gens les utilisent
Les hooks transforment en règle tout ce que le modèle pourrait oublier.
- Bloquer des commandes dangereuses ou la lecture de fichiers comme .env.
- Lancer un formateur ou un linter après chaque modification.
- Réécrire des commandes pour que leur sortie soit plus courte.
- Envoyer une notification ou lancer les tests à la fin d’un tour.
Points de vigilance
Les hooks s’exécutent avec vos permissions et sans demander, donc n’ajoutez pas le hook de quelqu’un d’autre sans l’avoir lu. Un hook lent ralentit chaque appel d’outil, gardez-les rapides. Le texte qu’un hook renvoie peut finir dans le contexte du modèle, gardez-le court.
Les hooks dans AgentVera
AgentVera fait tourner plusieurs de ses fonctions sous forme de hooks dans les agents Claude Code. Le profil de contexte Lean, en revanche, ne charge pas les hooks de niveau utilisateur.
- Smart tools : quatre hooks qui bloquent les relectures répétées de fichiers, limitent les exécutions complètes de tests aux tests concernés, signalent les nouvelles erreurs de type juste après une modification et partagent le résultat d’une commande entre agents. Tous sont activés par défaut.
- RTK : les commandes Bash de Claude Code sont réécrites par un hook en versions à sortie plus courte (git status → rtk git status).
- Codex n’a pas de hooks, donc RTK y fonctionne par des instructions, et les smart tools ne tournent que dans les agents Claude Code locaux.
- Outils intelligentsÉvite les relectures, les suites de tests complètes et les commandes répétées avant qu’elles n’atteignent le modèle.
- Économies de tokensProfils de contexte, sorties de commandes raccourcies avec RTK, taille du contexte en direct et auto-compact, activés par défaut pour chaque agent.
FAQ
Où configure-t-on les hooks Claude Code ?
Dans des fichiers settings.json : ~/.claude/settings.json pour votre utilisateur, .claude/settings.json pour le projet et .claude/settings.local.json pour votre machine seulement. Vous pouvez aussi les gérer avec la commande /hooks.
Comment un hook bloque-t-il une commande ?
Si un hook PreToolUse se termine avec le code 2, l’appel d’outil est bloqué et la sortie d’erreur du hook va au modèle comme raison.
Les hooks sont-ils sûrs ?
Les hooks sont des commandes shell exécutées avec vos permissions, donc aussi sûrs que ce qu’ils contiennent. Lisez les hooks de projet fournis avec un dépôt avant de les exécuter.
Quelle différence entre un hook et un skill ?
Un hook est une commande qui s’exécute à chaque fois qu’un événement donné se produit ; le modèle ne décide pas. Un skill est un ensemble d’instructions et de fichiers que le modèle charge quand il le juge pertinent.