Glossaire Claude Code
Hooks
Les hooks sont des commandes ou des points de terminaison définis par l'utilisateur qui s'exécutent automatiquement à des points spécifiques du cycle de vie de Claude Code.
Aussi appelé : claude code hooks, PreToolUse, PostToolUse, hook events
Les hooks sont des commandes shell, des points de terminaison HTTP ou des invites LLM définis par l'utilisateur qui s'exécutent automatiquement à des points spécifiques du cycle de vie de Claude Code. La distinction clé est que, bien que les instructions CLAUDE.md soient contextuelles et puissent être ignorées, les hooks sont du code qui s'exécute indépendamment des décisions de Claude. Si une action doit se produire à un point fixe — avant chaque commit, après chaque modification de fichier — elle doit être implémentée comme un hook.
Les noms d'événements vérifiés incluent : SessionStart, SessionEnd, Setup, UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied, PreCompact, PostCompact, Notification, SubagentStart, SubagentStop, InstructionsLoaded, et FileChanged.
La configuration suit une structure à trois niveaux : sélectionner un événement de hook, ajouter un groupe matcher pour filtrer quand il se déclenche (par exemple, 'Bash'), et définir les handlers. Les handlers peuvent être de type command, http, mcp_tool, prompt, ou agent. Les emplacements de configuration vérifiés incluent ~/.claude/settings.json (global), .claude/settings.json (spécifique au projet), .claude/settings.local.json (spécifique au projet et ignoré par git), le hooks/hooks.json d'un plugin, et le frontmatter d'une compétence ou d'un agent (limité à la durée active du composant).
La sémantique des codes de sortie est critique : un code de sortie de 0 signifie succès, permettant à Claude Code d'analyser la sortie JSON pour les décisions ultérieures. Un code de sortie de 2 indique une erreur bloquante, empêchant l'appel de l'outil et affichant stderr à Claude. Les autres codes de sortie non nuls sont traités comme des erreurs non bloquantes.
Crucialement, un hook PreToolUse peut retourner une permissionDecision de deny pour empêcher l'exécution d'un appel d'outil. Cela fournit un mécanisme puissant pour faire respecter les contraintes ou valider les conditions avant que les actions ne soient prises. Pour la gestion des hooks, la compétence Gestion des Hooks peut traduire le langage naturel en configurations validées, et la compétence Déboguer les Hooks offre un flux de travail pour le dépannage des problèmes.