Que sont les hooks de Claude Code ? Exécuter des commandes shell de façon déterministe

« 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.

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 ». À noter : les hooks de type prompt LLM et sous-agent avaient un bogue : rédigés comme des instructions (« Bloque les commandes qui... »), ils laissaient passer ce qu'ils auraient dû bloquer ; il a été corrigé dans la v2.1.294 (changelog officiel).

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).

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 même un « allow » en JSON ne peut pas annuler le blocage).

Quand le hook lui-même échoue (il ne démarre pas, dépasse son délai ou se termine avec un code de sortie inattendu), pour la plupart des événements l'action se poursuit par défaut. Un hook de garde dont le chemin est mal saisi se contente d'afficher un avis d'erreur et ne bloque rien. Depuis la v2.1.295, ajouter "onFailure": "block" à un hook command ou http bloque l'action quand le hook échoue (la valeur par défaut est "continue").

# 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)

À partir de la v2.1.300 (14 octobre 2026), le updatedInput renvoyé par les hooks PreToolUse et PermissionRequest est validé de la même manière que la propre entrée de Claude. Les clés que l'outil ne connaît pas sont écartées, et si un hook renvoie une entrée que l'outil n'accepte pas, cet appel est refusé (changelog officiel, vérifié le 18 octobre 2026).

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. Ce principe vaut pour les hooks définis dans les fichiers de réglages, que la documentation des mods appelle « settings hooks » : depuis la v2.1.287, un mod (un plugin dont les hooks sont des fonctions) qui répond à tool.check peut approuver un appel pour lequel une règle ask aurait demandé confirmation ou qu'un hook PreToolUse a bloqué (sauf si ce hook se trouve dans les réglages gérés) ; ses approbations contournent le classificateur du mode auto et, sauf sur les machines dotées de réglages gérés ou avec une connexion à un forfait Team ou Enterprise, il peut même approuver un appel qu'une règle de refus a rejeté (documentation officielle). N'installez que des mods d'auteurs de confiance. Autrement dit, les hooks peuvent étendre la manière dont les permissions sont évaluées, mais les règles de base se trouvent ailleurs : les règles de permission de Claude Code (allow/ask/deny) sont définies dans settings.json. 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.

Si vous voulez simplement « continuer jusqu'à ce que la condition soit remplie » sans écrire vous-même un hook Stop, /goal est là, prêt à l'emploi (un hook à base de prompt qui n'agit que dans la conversation).

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.

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, sauf l'exception des mods vue en section 4). 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 dans les sessions interactives, les hooks des fichiers de paramètres ne s'exécutent pas tant que vous n'avez pas fait confiance au dossier. À lire aussi : les plugins, le MCP, les erreurs de Claude Code, les mods (présentation officielle) et notre guide détaillé : les mods de Claude Code expliqués.

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 ». L'exception est un mod (un plugin dont les hooks sont des fonctions) : en répondant à tool.check, il peut passer outre ces décisions et, sauf sur les machines dotées de réglages gérés ou avec une connexion à un forfait Team ou Enterprise, il peut même approuver un appel qu'une règle de refus a rejeté (documentation officielle). N'installez que des mods d'auteurs de confiance.

Q. J'ai modifié ma configuration mais elle ne prend pas effet.
A. Normalement, les changements s'appliquent automatiquement : quand vous modifiez directement un fichier de paramètres, la surveillance des fichiers détecte le changement. S'il n'a toujours pas pris effet après quelques secondes, la surveillance l'a peut-être manqué : redémarrez la session. Vérifiez aussi que votre JSON est valide (pas de virgule finale ni de commentaire). Dans une session interactive, les hooks des fichiers de paramètres ne s'exécutent pas tant que vous n'avez pas accepté la boîte de dialogue de confiance du dossier. Notez que /hooks est une liste en lecture seule ; pour ajouter ou modifier des hooks, éditez 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 avertit qu'ils s'exécutent « avec toutes les permissions de votre utilisateur ». 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.