Hooks Claude Code : le guide complet pour industrialiser Claude en entreprise (2026)

Un hook Claude Code est une commande shell, une requête HTTP, un prompt LLM ou un subagent qu’Anthropic déclenche automatiquement à des moments précis du cycle de vie d’une session Claude Code. La documentation officielle recense 27 événements (avril 2026) et 4 types de hooks (command, http, prompt, agent) configurables dans settings.json à six niveaux distincts : utilisateur, projet, local, plugin, skill et policy enterprise. Les hooks offrent ce que le LLM seul ne garantit pas : le contrôle déterministe. On ne demande pas à Claude de formater le code, on le force via PostToolUse. On ne compte pas sur sa prudence pour éviter un rm -rf, on bloque l’action au niveau PreToolUse avec un exit code 2. Ce guide couvre la configuration complète, les 6 cas d’usage prioritaires pour une PME, les règles de sécurité enterprise et les pièges à éviter. Sources croisées : documentation Anthropic officielle (code.claude.com/docs/en/hooks, consultée le 22 avril 2026), changelog claudefa.st, exemples GitHub anthropics/claude-code. Auteur : Valentin Charlier, fondateur d’Ocade Fusion (intégration IA, Claude Code, automatisation n8n).

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/mon-hook.sh",
            "timeout": 30
          }
        ],
        "matcher": "Bash"
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
# Ajouter votre logique de détection ici
echo "Action bloquee par hook" >&2
exit 2

C’est quoi un hook Claude Code ?

Un hook Claude Code fonctionne sur le même principe qu’un git hook : un script se déclenche quand un événement précis survient dans la session. L’événement peut être le démarrage de la session, l’envoi d’un prompt utilisateur, l’exécution d’un outil (Edit, Write, Bash, Read), la fin d’une tâche ou la compaction automatique du contexte. La configuration vit dans un fichier settings.json. Anthropic autorise plusieurs scopes superposés avec un ordre de priorité explicite.

Les niveaux disponibles sont : ~/.claude/settings.json pour l’utilisateur global, .claude/settings.json pour le projet commité, .claude/settings.local.json pour le projet local gitignoré, hooks/hooks.json bundlé dans un plugin, un frontmatter de skill ou d’agent pour un scope court, et les managed policy settings pour une DSI. Cette hiérarchie permet à une équipe technique de livrer des règles de sécurité communes sans empêcher les devs d’ajouter leurs outils personnels au-dessus.

La valeur du mécanisme tient en une phrase : là où un LLM reste probabiliste, un hook est déterministe. Quand Claude s’apprête à lire .env, le hook PreToolUse lit le chemin sur stdin, compare à une liste de patterns protégés et renvoie exit 2. L’outil n’est pas exécuté. Le comportement est reproductible à 100 %, audité et versionné dans le repo. Source : documentation officielle Anthropic.

Pourquoi l’adoption des hooks Claude Code s’accélère en 2026

Entre septembre 2025 et avril 2026, Anthropic a ajouté plus de dix événements au système de hooks : TeammateIdle et TaskCompleted (v2.1.33), InstructionsLoaded (v2.1.69), PostCompact et les événements MCP Elicitation (v2.1.76), StopFailure et les agent hooks (v2.1.78), CwdChanged, FileChanged et le type HTTP généralisé (v2.1.83), TaskCreated (v2.1.84), le champ if pour filtrage fin (v2.1.85), la décision defer pour workflows asynchrones (v2.1.89), et PermissionDenied (v2.1.110). Cette cadence traduit une demande claire des équipes entreprise : industrialiser l’usage de Claude Code sans renoncer à la gouvernance.

Trois forces poussent l’adoption : la montée en puissance du mode auto-approve dans Claude Code, qui réclame des garde-fous déterministes ; la multiplication des serveurs MCP tiers, qui exige un sandboxing par pattern (mcp__memory__.*) ; et la pression réglementaire (RGPD, ISO 27001) qui impose un audit log exploitable. Un hook PostToolUse branché sur Bash avec jq -r '.tool_input.command' >> ~/.claude/command-log.txt fournit en cinq lignes ce que les DSI réclament depuis deux ans. Source : changelog claudefa.st/blog/guide/changelog.

Les 27 événements du cycle de vie Claude Code

La documentation d’avril 2026 liste 27 événements officiels, regroupés en sept familles. Connaître cette typologie est la première étape pour choisir où brancher son hook.

Événements de session (3) : SessionStart (matchers startup, resume, clear, compact), SessionEnd (matchers clear, resume, logout, prompt_input_exit, bypass_permissions_disabled, other) et InstructionsLoaded (chargement d’un CLAUDE.md ou d’une règle). Seul SessionStart se marie avec $CLAUDE_ENV_FILE pour persister des variables d’environnement.

Événements par tour (5) : UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, TeammateIdle. Stop peut bloquer la fin de réponse, utile pour forcer Claude à finir un chantier.

Événements par appel d’outil (8) : PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, Elicitation, ElicitationResult. PreToolUse est de loin le plus utilisé : 6 des 6 snippets officiels d’Anthropic l’emploient.

Événements sous-agents (4) : SubagentStart, SubagentStop, TaskCreated, TaskCompleted. Ils ont émergé avec les agent teams en septembre 2025 et permettent de tracer qui fait quoi dans un workflow multi-agents.

Événements compaction (2), environnement (3), worktree (2) complètent la liste. Les plus récents (v2.1.101 à v2.1.110) ajoutent la granularité dont les équipes ont besoin pour observer finement leurs sessions. Source : code.claude.com/docs/en/hooks.

Les 4 types de hooks Claude Code : command, http, prompt, agent

Anthropic expose quatre types de hooks, chacun adapté à une intention différente. Le choix du type conditionne la latence, le coût et la complexité de maintenance.

1. Type command (standard, 95 % des cas). Un script local reçoit un JSON sur stdin et répond via stdout (JSON structuré) ou stderr (exit code 2 pour bloquer). Latence minimale, aucun coût cloud, facile à versionner. Timeout par défaut 600s, ajustable par hook. Le champ if (v2.1.85) permet un filtrage fin type Bash(git push *) sans parser la commande dans le script.

2. Type http (v2.1.83). Requête POST vers une URL interne. Utile pour mutualiser un service d’audit à l’échelle de l’équipe (exemple : tous les PostToolUse de tous les devs sont loggés par un service Node qui alimente un dashboard Grafana). L’interpolation d’env vars est restreinte à une whitelist (allowedEnvVars), ce qui évite les fuites d’API key. Timeout recommandé : 30s.

3. Type prompt (LLM-based). Anthropic envoie la question à un modèle (défaut : claude-haiku-4-5) qui répond oui/non. Coût approximatif : 0,001 $ par appel. Pertinent pour des règles qui demandent du jugement et non une liste fermée, comme « ce prompt contient-il des informations potentiellement sensibles ? ». Moins déterministe qu’un command, donc à réserver aux cas où une regex ne suffit pas.

4. Type agent (expérimental). Un subagent avec accès aux outils Read, Grep, Glob, Bash est lancé pour vérifier une assertion sur le code (50 tours max). Exemple : « les tests passent-ils ? » avant de laisser Claude créer un commit. Ce type est marqué expérimental et peut changer, à réserver aux workflows internes. Source : code.claude.com/docs/en/hooks-guide.

Comment configurer un hook Claude Code : procédure pas à pas

Prérequis : Claude Code v2.1.110 ou supérieur, un shell Bash (ou PowerShell sur Windows), l’outil jq installé (brew install jq sur macOS). Temps estimé : 10 minutes. Résultat attendu : un hook PreToolUse qui bloque toute tentative de lecture de .env.

1. Ouvrir le fichier de settings global : code ~/.claude/settings.json (créer le fichier s’il n’existe pas). Sortie attendue : l’éditeur ouvre un JSON vide ou votre configuration existante.
2. Générer le bloc hook avec l’outil interactif ci-dessus. Sélectionner PreToolUse, matcher Read, action Bloquer l’action. Cliquer sur « Copier » pour le JSON. Sortie attendue : le JSON copié dans le presse-papier.
3. Fusionner dans settings.json : coller le contenu dans la racine du fichier (ou merger avec une clé hooks existante). Sauvegarder. Sortie attendue : le fichier contient une clé hooks.PreToolUse.
4. Créer le script bash : mkdir -p ~/.claude/hooks && code ~/.claude/hooks/mon-hook.sh. Coller le script bash copié depuis l’outil interactif. Adapter la logique de détection : FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') puis tester [[ "$FILE" == *".env"* ]] && exit 2. Sortie attendue : le fichier existe et commence par #!/bin/bash.
5. Rendre le script exécutable : chmod +x ~/.claude/hooks/mon-hook.sh. Sortie attendue : aucun message, le fichier est marqué exécutable. Vérifier avec ls -l ~/.claude/hooks/mon-hook.sh (doit afficher -rwxr-xr-x).
6. Tester le hook : lancer une session Claude Code, demander à Claude de lire .env. Sortie attendue : Claude reçoit une erreur (Blocked: .env matches protected pattern) et reformule sa demande sans tenter la lecture.
7. Vérifier dans le menu intégré : taper /hooks dans la session Claude Code. Sortie attendue : la commande affiche en lecture seule le hook actif avec le scope user.

Dépannage courant. Le hook ne se déclenche pas : vérifier que settings.json parse sans erreur (jq . ~/.claude/settings.json) et que le chemin dans command est absolu ou utilise $CLAUDE_PROJECT_DIR. Le hook bloque mais Claude continue : confirmer que le script termine bien sur exit 2 et non exit 1. Le script ne s’exécute pas : le shell de hook est non-interactive, donc les echo issus de ~/.zshrc polluent stdout ; wrapper les lignes problématiques dans [[ $- == *i* ]] && echo "...". Aller plus loin : guide officiel hooks.

Hook vs skill vs subagent : que choisir ?

Trois mécanismes se superposent dans Claude Code et la confusion est fréquente. Le bon choix dépend du type de contrôle souhaité.

Un hook est déterministe et synchrone : il fait une chose précise (bloquer, logger, formater, notifier) sur un événement précis. Latence faible, coût nul pour un type: "command". Pertinent pour les règles de sécurité, l’auto-format, l’audit et l’injection de contexte. Il n’invoque pas Claude, donc ne consomme aucun token.

Un skill est une capacité ré-utilisable que Claude active quand il juge pertinent. Le skill contient des instructions et des scripts, mais c’est Claude qui décide de l’invoquer. Pertinent pour des workflows complexes (rédaction d’article, montage vidéo, publication WordPress). Coûte des tokens à chaque activation, mais apporte expertise et reproductibilité.

Un subagent est un Claude spécialisé que l’agent principal délègue. Il vient avec son propre contexte et ses propres outils. Pertinent pour les recherches coûteuses en tokens, la revue de code, la validation de spec ou le travail parallèle. Le coût explose vite (chaque subagent consomme une session complète).

Règle pratique : si la décision est binaire et tient en 20 lignes de bash, c’est un hook. Si elle demande du jugement contextualisé et du texte, c’est un skill. Si elle exige des outils et une mini-investigation, c’est un subagent. Les trois se combinent bien dans un setup mature. Référence comparative : ClaudeLog mechanics/hooks documente les différences de scope entre les trois mécanismes.

6 cas d’usage concrets pour PME et ETI

1. Bloquer les fichiers sensibles. Hook PreToolUse sur Edit|Write|Read qui refuse l’accès à .env, package-lock.json, .git/. Cinq lignes de bash, zéro fuite possible, même en mode --dangerously-skip-permissions. C’est l’argument n°1 pour convaincre une DSI.

2. Auto-format post-édition. Hook PostToolUse sur Edit|Write qui lance npx prettier --write sur le fichier modifié. Le code reste clean sans que Claude y pense, et sans consommer de tokens pour lui rappeler.

3. Notification idle. Hook Notification qui appelle osascript (macOS) ou notify-send (Linux) pour alerter quand Claude attend une permission. Gagne du temps quand on travaille sur plusieurs sessions en parallèle.

4. Audit log commandes Bash (conformité). Hook PostToolUse sur Bash qui append command et timestamp dans ~/.claude/command-log.txt. Exploitable pour un rapport ISO 27001 ou pour un audit interne. Complément recommandé : automatisation cloud avec les routines Claude Code.

5. Re-injection de contexte post-compaction. Hook SessionStart avec matcher compact qui fait echo "Rappel : utiliser Bun, pas npm. Sprint : refacto auth.". Le contexte critique est réinjecté automatiquement après chaque compaction.

6. Reload direnv sur cd. Hook CwdChanged qui fait direnv export bash > "$CLAUDE_ENV_FILE". Les variables d’environnement du projet se chargent à chaque changement de dossier, comme dans un shell humain. Sources des exemples : repo officiel anthropics/claude-code.

Sécurité enterprise et managed settings

Pour une DSI, trois propriétés font la différence entre un gadget et un outil déployable en production.

Les hooks deny priment sur le mode permissions. Un PreToolUse qui renvoie {"permissionDecision": "deny"} bloque même un utilisateur qui a lancé Claude en --dangerously-skip-permissions. C’est inversement vrai pour allow : un hook ne peut pas ouvrir ce qu’un policy setting a fermé. Les hooks sont une couche qui resserre, jamais qui relâche.

Les managed settings permettent à une DSI d’imposer un arbre de hooks via le fichier managed settings (niveau organisation). Deux clés clés : "allowManagedHooksOnly": true pour désactiver tous les hooks utilisateur et projet, et "enabledPlugins": ["plugin-id"] pour ne charger que les plugins vettés. Ce mode est à activer avant tout déploiement grande échelle.

Les HTTP hooks respectent une whitelist d’env vars. L’interpolation $MY_TOKEN n’est possible que si la clé figure dans allowedEnvVars. Cela protège contre les fuites d’API key dans les logs d’audit et les URLs. Combinée à l’OAuth step-up (v2.1.85), la fonctionnalité couvre un cas d’usage courant : un audit service qui signe chaque requête sans que la clé quitte la machine du dev. Source : section sécurité documentation officielle.

Pièges concrets à éviter

Stdout pollué par le shell interactif. Les hooks command tournent dans un shell non-interactive. Si ~/.zshrc contient un echo "Welcome" non-conditionnel, la sortie contamine le JSON renvoyé au moteur Claude Code et le hook échoue silencieusement. Solution : wrapper avec [[ $- == *i* ]] && echo "...".

Timeouts trop courts. Par défaut, un hook command a 600s, un http a 30s. Un audit réseau lent peut dépasser. Ajuster explicitement le champ timeout par hook plutôt que de compter sur le défaut.

Espaces dans $CLAUDE_PROJECT_DIR. Si le projet vit sous /Users/Jean Dupont/repo, le chemin contient un espace. Toujours quoter : "$CLAUDE_PROJECT_DIR/scripts/hook.sh", jamais $CLAUDE_PROJECT_DIR/scripts/hook.sh.

Hooks prompt (LLM) en chaîne critique. Un hook de type prompt rajoute ~500ms de latence par appel. Multiplié sur un PostToolUse qui fire à chaque Edit, la session devient lente. Préférer un command avec regex, garder les prompt pour les décisions rares. Autres pièges documentés par la communauté : référence hooks eesel.ai.

Ce qu’il faut retenir

Les hooks Claude Code offrent le contrôle déterministe que le LLM seul ne peut pas garantir, avec 27 événements et 4 types en avril 2026. Six cas d’usage prioritaires couvrent l’essentiel pour une PME : blocage de fichiers sensibles, auto-format, audit log, notification idle, re-injection de contexte, reload direnv. Pour une DSI, les managed settings et la précédence du deny rendent le mécanisme déployable à l’échelle. Le reste est du bash simple, versionnable, audible. Prochaine étape concrète : coller la configuration générée par l’outil interactif ci-dessus dans ~/.claude/settings.json, créer le script, tester en 10 minutes. Pour aller plus loin sur l’automatisation cloud, voir le guide routines Claude Code. Besoin d’un accompagnement pour industrialiser Claude Code dans votre PME ? Prendre contact avec Ocade Fusion.

FAQ hooks Claude Code

Les hooks Claude Code fonctionnent-ils sur Windows ? Oui, via PowerShell. Le champ shell accepte powershell. Les scripts doivent être adaptés (pas de jq par défaut, préférer ConvertFrom-Json).

Peut-on désactiver temporairement un hook ? Oui, en commentant son entrée dans settings.json (JSON ne supporte pas les commentaires natifs, utiliser settings.local.json pour un override gitignoré). Le menu /hooks est en lecture seule, pas d’interface de désactivation live.

Un hook peut-il modifier le prompt utilisateur ? Oui, via UserPromptSubmit qui renvoie un JSON avec additionalContext. Le contexte supplémentaire est injecté avant que Claude ne traite le prompt. Utilisable pour enrichir automatiquement la requête avec des infos projet.

Comment tester un hook sans lancer une session Claude Code ? Simuler l’entrée : echo '{"tool_input": {"file_path": "/tmp/.env"}}' | ~/.claude/hooks/mon-hook.sh; echo "exit: $?". Un exit: 2 confirme le blocage.

Les hooks consomment-ils des tokens ? Les hooks command, http et agent : non pour le déclenchement, oui pour agent qui utilise un subagent Claude. Les hooks prompt consomment toujours des tokens (facturés au modèle Haiku par défaut, ~0,001 $ par appel).

Existe-t-il un registre communautaire de hooks ? Oui, le repo disler/claude-code-hooks-mastery agrège les exemples communautaires et sert de référence de facto, en complément de la doc officielle Anthropic.

Que se passe-t-il si un hook échoue (exit code autre que 0 ou 2) ? Claude affiche une notification système mais poursuit l’action. Seul exit 2 bloque. Tout autre code non-nul est traité comme une alerte non-bloquante.