Hooks d'agent (Cursor et Claude Code)
Un hook est un petit programme que l'outil lance automatiquement à un moment précis, par exemple avant une commande shell : il peut l'autoriser, la bloquer avec un motif ou formater un fichier.
- hooks
- pretooluse
- posttooluse
- beforeShellExecution
- afterFileEdit
- stop
Syntaxe
Avant une action : Claude Code PreToolUse (outil Bash, Edit…) ≈ Cursor beforeShellExecutionAprès une action : Claude Code PostToolUse ≈ Cursor afterFileEditFin de tour : Claude Code Stop ≈ Cursor stopEntrée : JSON sur stdin (outil, commande, fichier) · Sortie : décision en JSON sur stdout · Journaux : stderrExemple
Hook PreToolUse sur l'outil Bash (Claude Code)Entrée reçue :{"tool_name": "Bash", "tool_input": {"command": "git push origin main"}}Sortie du hook :{"hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Push bloqué : il faut une demande explicite de l'utilisateur."}}Résultat attendu : la commande n'est pas exécutée et l'agent explique pourquoi.À retenir
- Trois hooks utiles et rapides valent mieux que vingt hooks lents que l'équipe finira par désactiver.
- Écrivez un motif de refus actionnable : l'agent le lit et peut proposer une alternative au lieu de réessayer.
- Un hook de fin de tour sert à rappeler une vérification (lint, tests), pas à bloquer des actions déjà effectuées.
- Piège : afficher des messages de débogage sur stdout. La sortie standard est lue comme la réponse du hook, et un print() parasite rend le JSON illisible ; les journaux vont sur stderr.
Voir aussi
- Échec fermé ou échec ouvertQuand un hook plante ou dépasse son délai, il faut décider s'il bloque (échec fermé) ou laisse passer (échec ouvert). Les secrets et l'irréversible bloquent ; le formatage laisse passer.
- Garde-fous du dépôt (Claude Code et Cursor)Un dépôt confié à un agent se protège en couches : des consignes pour guider, des permissions pour interdire, des hooks pour contrôler chaque action et des fichiers ignorés pour cacher les secrets.
- Consultatif ou déterministeUne consigne en Markdown est un conseil que le modèle peut ignorer ; une permission deny ou un hook est une règle appliquée par l'outil. Tout ce qui est irréversible relève de la seconde catégorie.
- Agents en ligne de commandeUn agent de code en terminal lit, modifie et lance des commandes pour prouver que son travail compile. Sa valeur tient à la boucle lire, modifier, exécuter, corriger, et aux limites qu'on lui pose.