Hooks Claude Code : automatiser et bloquer, exemples à l’appui

Pour apprendre à automatiser Claude Code sans perdre la main sur votre projet, la formation Claude Code de Dyma consacre un chapitre aux hooks. Ce guide explique les hooks de Claude Code : les événements disponibles, la façon de les configurer, ce qu’un hook reçoit et ce qu’il peut renvoyer, avec deux exemples officiels prêts à copier. Tout a été vérifié le 2 novembre 2026 sur la documentation officielle d’Anthropic (Claude Code 2.1.316).

À quoi servent les hooks ?

La documentation résume leur intérêt en un mot : le déterminisme. Certaines actions doivent toujours se produire, au lieu de dépendre de la décision du modèle. Une consigne écrite dans CLAUDE.md peut être oubliée ; un hook s’exécute à chaque fois que son événement se produit.

Les événements des hooks

La documentation en recense 33. Les plus utilisés suivent le cycle d’une demande :

1. SessionStart se déclenche quand une session commence ou reprend.
2. UserPromptSubmit s’exécute à l’envoi de votre message, avant que Claude le traite.
3. PreToolUse passe avant chaque appel d’outil, et peut le bloquer.
4. PostToolUse suit chaque appel d’outil réussi.
5. Stop arrive quand Claude termine sa réponse.

D’autres couvrent des moments plus précis : Notification quand Claude Code envoie une notification, SubagentStop à la fin d’un sous-agent, PreCompact avant chaque compaction du contexte, automatique ou par /compact, InstructionsLoaded au chargement d’un CLAUDE.md, SessionEnd à la fermeture. Attention : Stop se déclenche à chaque fin de réponse, pas à la fin d’une tâche, et pas si vous interrompez Claude.

Où configurer un hook ?

Les hooks se déclarent sous la clé "hooks" d’un fichier de réglages. Ils s’additionnent d’un niveau à l’autre, aucun n’en remplace un autre.

Dans Claude Code, la commande /hooks affiche tous les hooks en place, chacun avec le fichier d’où il vient. Elle est en lecture seule : pour modifier un hook, éditez le fichier.

Exemple : formater le code après chaque modification

Voici l’exemple officiel, à placer dans .claude/settings.json. Après chaque appel aux outils Edit ou Write, la commande lit le chemin du fichier modifié et le passe à Prettier :

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

La structure est toujours la même : un événement, puis des groupes qui associent un matcher (le filtre, ici sur le nom de l’outil) à une liste de hooks. Le matcher Edit|Write vise deux outils ; * ou une valeur vide les vise tous. Les exemples de la documentation utilisent jq pour lire le JSON : installez-le s’il manque.

Ce que reçoit un hook

Un hook de type commande reçoit sur son entrée standard un objet JSON qui décrit la situation : l’identifiant de session, le dossier de travail, le mode de permission, le nom de l’événement et, pour les événements d’outil, l’outil et ses paramètres. Pour une commande Bash, par exemple, tool_name vaut "Bash" et tool_input.command contient la commande que Claude s’apprête à lancer.

La variable $CLAUDE_PROJECT_DIR donne la racine du projet : utilisez-la pour appeler vos scripts par un chemin absolu, comme "$CLAUDE_PROJECT_DIR"/.claude/hooks/mon-script.sh.

Bloquer une action : les codes de sortie

Le code de sortie du hook décide de la suite :

Le piège est le code 1. C’est le code d’échec habituel sous Unix, mais pour Claude Code il ne bloque rien. Un hook qui doit faire respecter une règle sort avec exit 2. L’exemple officiel, qui interdit les commandes commençant par rm :

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

Le blocage dépend de l’événement : sur PreToolUse, l’outil ne s’exécute pas ; sur UserPromptSubmit, votre message n’est pas traité ; sur Stop, Claude ne s’arrête pas et continue de travailler. Sur PostToolUse, l’outil a déjà tourné : le message est seulement montré à Claude.

Répondre en JSON pour décider plus finement

Au lieu d’un code de sortie, un hook peut sortir avec 0 et imprimer un JSON. Pour PreToolUse, le champ permissionDecision accepte allow, deny, ask (demander à l’utilisateur) ou defer (mettre l’appel en attente, en mode non interactif seulement) :

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

Quand plusieurs hooks répondent, le refus l’emporte. Et un hook muet n’approuve rien : la demande de permission habituelle s’applique. Un hook peut aussi arrêter Claude net avec "continue": false et une raison dans stopReason.

Les types de hooks

La commande shell est le type le plus courant, mais il en existe cinq :

Le type prompt sert à des vérifications qu’un script ferait mal, par exemple demander, sur l’événement Stop, si toutes les tâches sont vraiment terminées.

Hooks et sécurité

La documentation est explicite : les hooks de type commande s’exécutent avec tous vos droits d’utilisateur, et peuvent lire, modifier ou supprimer tout fichier auquel votre compte a accès. Relisez et testez chaque hook avant de l’ajouter, mettez les variables entre guillemets et évitez de toucher aux fichiers sensibles comme .env ou .git/.

Un dépôt cloné peut contenir des hooks dans .claude/settings.json. En session interactive, ils n’agissent qu’après que vous avez accordé votre confiance au dossier. En mode non interactif (claude -p), le dossier est considéré comme de confiance : sur un dépôt inconnu, relisez .claude/ d’abord, ou lancez avec --settings '{"disableAllHooks": true}'.

Aller plus loin

Les hooks complètent les autres modules de Claude Code : CLAUDE.md pour les consignes, les skills pour les procédures, qui peuvent d’ailleurs déclarer leurs propres hooks, et MCP pour les outils externes. Pour débuter, voyez notre guide installer Claude Code et le tutoriel Claude Code.

La formation Claude Code consacre des chapitres aux hooks, aux plugins, à la sécurité et à la revue de code. Pour intégrer des modèles d’IA dans vos propres applications, voyez la formation IA pour développeurs ; pour Claude au quotidien, la formation Claude.

Questions fréquentes