Sommaire

« Je veux un formatage automatique après chaque édition. » « Ne laisse jamais quoi que ce soit réécrire .env ou package-lock.json. » « Bloque les commandes rm -rf dangereuses. » La façon de rendre réelles ces règles « cela doit toujours se produire » — sans dépendre des caprices de l'IA — ce sont les hooks de Claude Code. Un hook est une commande shell qui s'exécute automatiquement à des points précis du cycle de vie de Claude Code, et les hooks sont aussi un élément de base des plugins.

Cet article expose, sur la base de la documentation officielle, ce que sont les hooks, la liste des événements, comment les configurer, le contrat d'entrée/sortie, les cas d'usage et la sécurité. Trois points d'emblée. ① Un hook est « une logique déterministe que le harness (Claude Code lui-même) exécute » — il se déclenche à coup sûr, sans attendre que le modèle « décide » de le faire. ② On écrit les hooks dans settings.json sous la forme nom d'événement → matcher → command. ③ Des événements comme PreToolUse peuvent « bloquer » via le code de sortie 2 ou via du JSON — en empêchant les éditions de fichiers protégés ou les commandes dangereuses.

CLAUDE CODE · HOOKS

Se déclenche « à coup sûr » aux points clés du cycle de vie

— le harness l'exécute de façon déterministe, pas le jugement du modèle

SessionStart La session commence. La sortie est injectée comme contexte
UserPromptSubmit Quand un prompt est soumis [peut bloquer]
PreToolUse Juste avant qu'un outil s'exécute = le gardien [peut bloquer]
PostToolUse Après qu'un outil réussit = formatage automatique / audit
Stop Quand une réponse se termine = continuer jusqu'à ce que les tests passent, etc. [peut bloquer]

À chaque point, votre commande shell s'exécute. Les classiques : PreToolUse pour refouler les actions dangereuses à la porte, PostToolUse pour formater automatiquement.

1. Que sont les hooks de Claude Code ?

La définition officielle est la suivante : « Les hooks sont des commandes shell définies par l'utilisateur qui s'exécutent à des points précis du cycle de vie de Claude Code. Ils offrent un contrôle déterministe du comportement de Claude Code, en garantissant que certaines actions se produisent toujours plutôt que de compter sur le LLM pour choisir de les exécuter. » On les utilise pour faire respecter les règles d'un projet, automatiser les tâches répétitives et intégrer Claude Code à vos outils existants.

Le cœur, c'est le déterminisme. Demandez à Claude de « lancer les tests » et qu'il le fasse ou non dépend de son « jugement ». Mais avec un hook, le harness l'exécute toujours — aucun caprice n'entre en jeu. Au-delà des commandes (command), il existe désormais aussi des types de gestionnaires comme HTTP, les outils MCP, les prompts LLM et la vérification par sous-agent — mais pour commencer, il suffit de voir les hooks comme « un mécanisme pour toujours exécuter une commande shell aux points clés ».

2. Les événements de hook

Un événement représente « à quel endroit du cycle de vie il se déclenche ». Commencez par les neuf classiques (« peut bloquer » = vous pouvez arrêter cette action via le code de sortie 2 ou du JSON).

ÉvénementSe déclenche quandBloque
SessionStartUne session commence ou reprend (la sortie standard est injectée comme contexte)Non
UserPromptSubmitVous soumettez un prompt, avant que Claude ne le traiteOui
PreToolUseJuste avant un appel d'outil (le gardien principal)Oui
PostToolUseAprès qu'un outil réussit (l'action elle-même est irréversible)Oui
NotificationLors d'une notification (en attente d'une saisie/permission, etc.)Non
StopQuand Claude termine sa réponse (bloquer = continuer à travailler)Oui
SubagentStopQuand un sous-agent termineOui
SessionEndQuand une session se termineNon
PreCompactAvant la compaction du contexteOui

La documentation 2026 ajoute bien d'autres événements — PermissionRequest, PostToolUseFailure, ConfigChange, FileChanged, WorktreeCreate, entre autres. Mais les noms d'événements peuvent être ajoutés ou modifiés d'une version à l'autre, c'est pourquoi cet article s'appuie sur les neuf classiques stables, plus le contrat de la section suivante (consultez la documentation officielle pour la liste complète et à jour).

3. Comment configurer les hooks

On écrit les hooks sous la clé "hooks" de settings.json. L'emplacement définit la portée : utilisateur (~/.claude/settings.json) / projet (.claude/settings.json, partageable via git) / local (.claude/settings.local.json) / politique gérée (organisation) / le hooks/hooks.json d'un plugin. La forme du JSON ressemble à ceci.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

La structure est « hooks → nom d'événement → un tableau de { matcher, hooks:[...] } → chaque hook a un type + une command ». Le matcher indique le nom de l'outil ciblé : "*" (ou omis) correspond à tout, "Edit|Write" est une liste séparée par |, et les autres caractères sont des regex (par ex. mcp__memory__.*). Il est sensible à la casse. La commande /hooks liste les hooks configurés mais est en lecture seule — pour ajouter ou modifier, éditez directement settings.json. Désactivez-les tous avec "disableAllHooks": true.

4. Le contrat d'entrée/sortie

Un hook reçoit du JSON sur l'entrée standard (stdin) et renvoie son résultat via le code de sortie ou via du JSON sur la sortie standard.

Entrée (stdin) : les champs communs incluent session_id, transcript_path, cwd et hook_event_name. Les événements d'outils ajoutent tool_name et tool_input (par ex. {"command":"rm -rf /tmp/build"}) ; UserPromptSubmit ajoute prompt. Codes de sortie : 0 = succès (pour certains événements, la sortie standard est ajoutée au contexte — même si un code 0 sur PreToolUse n'est pas une « approbation » ; le flux de permission normal s'applique quand même), 2 = bloquer (la sortie d'erreur est transmise à Claude comme matière pour s'ajuster, et la sortie JSON est ignorée).

# Exemple : « deny » depuis PreToolUse via une sortie JSON structurée (imprimée sur stdout)
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}
# Champs communs : continue (false = tout arrêter) / decision:"block"+reason /
#                additionalContext (ajoute pour Claude) / updatedInput (reecrit les arguments)

Le principe le plus important : « les hooks peuvent resserrer les restrictions mais pas les assouplir. » Renvoyer allow ne fait que sauter l'invite ; les règles de refus (deny) dans n'importe quelle portée (y compris les réglages gérés) ont toujours la priorité. Un refus de PreToolUse bloque même sous bypassPermissions / --dangerously-skip-permissions. Pour le modèle de permission plus large, voir les modes de permission et la sécurité.

5. Exemples de cas d'usage

Les classiques officiels, avec leur configuration.

CAS D'USAGE

Les automatisations classiques

Formater automatiquement après les éditions
PostToolUse + Edit|Write lance prettier / un linter automatiquement.
Protéger les fichiers critiques
PreToolUse bloque (exit 2) les éditions de .env, .git/, etc.
Bloquer les commandes dangereuses
PreToolUse détecte rm -rf etc. et renvoie deny.
Réinjecter le contexte
La sortie standard de SessionStart recharge les conventions et les notes à chaque fois (même après une compaction).
Notifications et journal d'audit
Notification pour les alertes de bureau ; PostToolUse pour journaliser l'historique des commandes.
Tester avant de s'arrêter
Stop empêche Claude de s'arrêter tant que les tests ne passent pas (continuer jusqu'au vert).

À noter : Claude peut aussi modifier des fichiers via Bash. Pour intercepter chaque changement, ajoutez un hook Stop qui parcourt l'arbre de travail une fois par tour.

6. Sécurité

Les hooks sont puissants, mais ils exécutent automatiquement des commandes shell arbitraires avec vos privilèges — à ne pas prendre à la légère.

⚠️ L'avertissement officiel

« Les hooks exécutent automatiquement des commandes shell arbitraires. Vous êtes seul responsable de la sécurité des hooks que vous configurez. UTILISEZ-LES À VOS PROPRES RISQUES. » Les hooks peuvent lire des fichiers, modifier votre base de code, exfiltrer des données ou exécuter n'importe quelle commande — ne configurez que ceux en lesquels vous avez entièrement confiance.

Instantané au démarrage (une fonction de sécurité clé) : la configuration des hooks est capturée au démarrage de la session, de sorte que les modifications de configuration en cours de session ne prennent pas effet. Cela empêche un prompt malveillant ou la sortie d'un outil de réécrire votre configuration de hooks pendant une session. Appliquez les changements dans une nouvelle session.

En pratique : validez et mettez toujours les entrées entre guillemets (extrayez avec jq ; des variables sans guillemets peuvent devenir des arguments supplémentaires ou de la syntaxe shell), utilisez des chemins absolus et ${CLAUDE_PROJECT_DIR}, ne touchez pas aux fichiers sensibles comme .env ou .ssh, et ne faites jamais eval sur la sortie d'un outil. Les hooks s'exécutent sans terminal de contrôle (pas de /dev/tty). Dans les organisations, les administrateurs peuvent restreindre les hooks avec allowManagedHooksOnly.

Résumé

Les hooks de Claude Code sont des commandes shell définies par l'utilisateur qui s'exécutent automatiquement aux points clés du cycle de vie, rendant « cela doit toujours se produire » réel et déterministe sans dépendre du jugement du modèle. Les événements classiques sont au nombre de neuf : SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Notification / Stop / SubagentStop / SessionEnd / PreCompact (PreToolUse et d'autres peuvent bloquer — en empêchant les éditions de fichiers protégés ou les commandes dangereuses). Vous les configurez dans settings.json sous "hooks" sous la forme événement → matcher → type + command.

Les E/S sont du JSON sur stdin, un code de sortie 0 (succès) / 2 (bloquer), ou du JSON structuré sur stdout. Le principe : « vous pouvez resserrer mais pas assouplir les restrictions » (le refus l'emporte toujours). Les cas d'usage classiques : formatage automatique, protection des fichiers, blocage des commandes dangereuses, réinjection de contexte, audit, tester avant de s'arrêter. Mais comme ils exécutent du code arbitraire, soyez strict : ne faites confiance qu'aux hooks sûrs et validez/mettez les entrées entre guillemets, et comprenez que la configuration est capturée au démarrage. À lire aussi : les plugins, le MCP, les erreurs de Claude Code.

FAQ

Q. À quoi servent les hooks ?
A. Ils automatisent de façon déterministe « cela doit toujours se produire ». Des choses comme « formater après les éditions », « ne jamais laisser réécrire les fichiers protégés », « bloquer les rm -rf dangereux » et « passer les tests avant de s'arrêter » sont exécutées à coup sûr par le harness, sans dépendre du jugement de l'IA. Un hook est une commande shell qui s'exécute aux points clés du cycle de vie, configurée dans settings.json.

Q. Quels événements (moments) existe-t-il ?
A. Les classiques sont au nombre de neuf : SessionStart (début), UserPromptSubmit (à la soumission), PreToolUse (juste avant un outil), PostToolUse (après un outil), Notification, Stop (fin de la réponse), SubagentStop, SessionEnd (fin), PreCompact (avant la compaction). Parmi eux, PreToolUse, UserPromptSubmit, Stop, PreCompact et d'autres peuvent bloquer et arrêter l'action. La version 2026 ajoute bien d'autres événements, mais les noms peuvent changer d'une version à l'autre, alors consultez la documentation officielle pour la version la plus récente.

Q. Puis-je empêcher les éditions de fichiers protégés ou les commandes dangereuses ?
A. Oui — avec un hook PreToolUse. Un script inspecte le chemin du fichier ou la commande dans tool_input, et s'il correspond à .env, rm -rf, etc., renvoie le code de sortie 2 (ou du JSON avec permissionDecision:"deny") pour le bloquer. Point crucial : le refus a toujours la priorité et bloque même sous bypassPermissions. Les hooks ne fonctionnent que dans le sens « resserrer les restrictions ».

Q. J'ai modifié ma configuration mais elle ne prend pas effet.
A. C'est voulu (une fonction de sécurité). La configuration des hooks est capturée sous forme d'instantané au démarrage de la session, de sorte que les modifications en cours de session ne s'appliquent pas. Cela empêche un prompt malveillant ou la sortie d'un outil de réécrire silencieusement votre configuration de hooks. Démarrez une nouvelle session pour l'appliquer. Notez que /hooks est une liste en lecture seule ; ajoutez ou modifiez les hooks en éditant directement settings.json.

Q. Les hooks sont-ils sûrs ?
A. Pas inconditionnellement. Les hooks exécutent des commandes shell arbitraires avec vos privilèges, c'est pourquoi la documentation dit « utilisez-les à vos propres risques ». Ne configurez que des hooks de confiance, validez et mettez les entrées entre guillemets avec jq, utilisez des chemins absolus et ne touchez pas à .env / .ssh, et ne faites jamais eval sur la sortie d'un outil. Dans les organisations, les administrateurs peuvent restreindre les hooks avec allowManagedHooksOnly.