Hooks Claude Code : fonctionnement et événements

Fonctionnement d’un hook Claude Code

Les hooks Claude Code sont des commandes shell que Claude Code exécute automatiquement à des points précis de son propre cycle de vie. C’est toute la différence entre un hook et un fichier de règles. Une instruction dans CLAUDE.md est un conseil que le modèle évalue avec le reste de son contexte. Un hook est du code qui s’exécute, que le modèle soit d’accord ou non. Si votre agent ignore systématiquement le formatter que vous lui avez indiqué à deux reprises, vous n’avez pas besoin d’une instruction plus ferme. Vous avez besoin d’un hook.

Le mécanisme est simple. Vous enregistrez une commande dans un fichier de configuration, sous un nom d’événement. Lorsque cet événement se produit, Claude Code exécute votre commande et écrit les données de l’événement au format JSON (JavaScript object notation) sur son entrée standard (stdin). Votre commande lit ces données, effectue son traitement, puis renvoie un code de sortie. Un code de sortie 2 depuis un hook PreToolUse annule l’appel de l’outil avant son exécution. Le contenu écrit par votre script sur la sortie d’erreur standard (stderr) est transmis au modèle comme motif.

Les noms d’événements et de champs utilisés ici proviennent de la référence des hooks Claude Code, vérifiée en août 2026 avec la release 2.1.232. Cette interface évolue rapidement. Consultez donc la référence correspondant à votre version avant de copier du JSON depuis un article de blog, y compris celui-ci. Affichez la vôtre avec claude --version.

Emplacement de la configuration des hooks

Un hook est un bloc JSON dans un fichier de paramètres. Six emplacements peuvent en contenir un, et la portée du fichier détermine la portée du hook.

• ~/.claude/settings.json : tous les projets sur votre machine, et sur aucune autre.
• .claude/settings.json : un seul projet, validé dans le dépôt ; toutes les personnes qui le clonent obtiennent le hook.
• .claude/settings.local.json : un seul projet, uniquement sur votre machine.
• Paramètres de stratégie gérés : à l’échelle de l’organisation, définis par un administrateur.
• hooks/hooks.json dans un plugin : actifs tant que ce plugin est activé.
• Frontmatter d’un skill ou d’un subagent : actif tant que ce composant est actif.

Les entrées de hook provenant de ces fichiers sont fusionnées au lieu de se remplacer. Le fichier de paramètres d’un projet ajoute ses hooks à ceux de vos paramètres utilisateur, au lieu de les remplacer. Un même événement peut donc contenir plusieurs hooks provenant de plusieurs fichiers. La définition de "disableAllHooks": true les désactive, à une exception près : les hooks des paramètres de stratégie gérés continuent de s’exécuter, sauf si cette définition est également appliquée dans les paramètres gérés.

Exécutez /hooks dans une session pour afficher tous les hooks actuellement enregistrés, regroupés par événement, avec pour chacun le fichier source et le matcher. Le menu est en lecture seule. Pour modifier un hook, éditez le fichier de paramètres. Le file watcher détecte généralement la modification sans redémarrage.

Événements de hook disponibles dans Claude Code

La version 2.1.232 répertorie trente et un événements, de SessionStart à SessionEnd, couvrant la compaction, les subagents, les worktrees et les fichiers de configuration. L’administration de serveurs n’en utilise qu’une partie.

• PreToolUse : avant l’exécution d’un appel d’outil. C’est celui qui peut bloquer l’appel.
• PostToolUse : après la réussite d’un appel d’outil. PostToolUseFailure se déclenche en cas d’échec. Un hook qui doit voir tous les résultats doit donc utiliser les deux.
• PermissionRequest : lorsqu’un appel d’outil nécessite une décision d’autorisation, c’est-à-dire au moment où l’invite d’approbation devrait apparaître.
• UserPromptSubmit : lorsque vous soumettez un prompt, avant que Claude le traite. Tout ce que ce hook écrit sur stdout est ajouté au contexte du modèle.
• SessionStart et SessionEnd : à chaque fin de session. SessionStart se déclenche également après une compaction, avec la valeur de matcher compact.
• Stop : lorsque Claude termine sa réponse. Il se déclenche une fois par tour, et non une fois par tâche terminée.

Chaque groupe contient un matcher qui détermine les occurrences pour lesquelles le hook s’exécute. Pour les événements d’outil, il filtre selon le nom de l’outil. Ainsi, "Edit|Write" se déclenche lors des modifications de fichiers, et dans aucun autre cas. Les matchers sont sensibles à la casse. Un matcher vide se déclenche à chaque occurrence. Les outils d’un serveur MCP (model context protocol) sont nommés mcp__<server>__<tool>. Un matcher "mcp__github__.*" intercepte donc les outils d’un serveur donné, sans intercepter ceux des autres serveurs.

Les hooks Stop comportent un piège à connaître avant d’en écrire un. Un hook Stop qui bloque renvoie le modèle au travail, et Claude Code ignore le hook après huit blocages consécutifs. Lisez le champ stop_hook_active dans les données d’entrée du hook et quittez avec le code 0 lorsqu’il vaut true. Sinon, le hook bouclera jusqu’à atteindre cette limite.

Ce qu’un hook reçoit sur stdin

Lorsque Claude est sur le point d’exécuter npm test, un hook PreToolUse sur Bash lit ces données sur stdin :

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Chaque événement contient session_id, cwd, permission_mode, transcript_path et hook_event_name. Les événements d’outil ajoutent tool_name, tool_input et tool_use_id. Les autres événements contiennent leurs propres champs : UserPromptSubmit contient le texte prompt, tandis que SessionStart contient un source de startup, resume, clear, compact ou fork.

jq est la méthode habituelle pour lire ces données dans un script shell, mais une image serveur minimale ne l’inclut pas. Installez-le d’abord avec sudo apt install -y jq sur Ubuntu et Debian.

Ce que le code de sortie fait de l’appel d’outil en cours

Il existe trois issues.

• Le code de sortie 0 signifie que votre hook ne s’oppose pas à l’action. Pour PreToolUse, cela ne vaut pas approbation : le flux normal de vérification des permissions s’exécute quand même. Pour UserPromptSubmit et SessionStart, stdout est ajouté au contexte du modèle.
• Le code de sortie 2 bloque l’action pour les événements qui peuvent être bloqués, notamment PreToolUse, et stderr devient la raison affichée au modèle. Pour les événements qui ne peuvent pas être bloqués, comme PostToolUse, le blocage est ignoré, mais stderr est tout de même transmis au modèle comme retour.
• Tout autre code de sortie indique une erreur non bloquante. L’action se poursuit. La transcription affiche une notification d’erreur du hook contenant la première ligne de stderr après le texte Failed with non-blocking status code:.

Pour obtenir un comportement autre que bloquer ou rester silencieux, utilisez le code de sortie 0 et écrivez plutôt un objet JSON dans stdout. Un hook PreToolUse prend sa décision avec permissionDecision :

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" ignore l’invite interactive, "deny" annule l’appel et transmet la raison au modèle, et "ask" affiche l’invite normalement. Choisissez un seul style par hook. Mélanger le code de sortie 2 avec une décision JSON dans stdout produit un résultat qu’il faut rechercher.

Lorsque plusieurs hooks correspondent au même événement, ils s’exécutent en parallèle et vont tous jusqu’à leur terme. Un deny produit par un hook n’arrête pas ses hooks frères : un hook de journalisation écrit donc toujours sa ligne pendant qu’un hook de protection refuse le même appel. Claude Code fusionne ensuite les réponses et conserve la plus restrictive, dans l’ordre suivant : deny, defer, ask, allow.

Exemple 1 : bloquer une commande destructive avant son exécution

Enregistrez ceci sous .claude/hooks/block-destructive.sh dans votre projet :

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

Rendez le fichier exécutable, puis enregistrez-le dans PreToolUse de .claude/settings.json :

chmod +x .claude/hooks/block-destructive.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

Testez le script manuellement avant de lui faire confiance, car un hook qui plante sur sa propre entrée échoue en mode permissif :

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Vous devriez voir la ligne Blocked by policy: sur stderr et obtenir le code de sortie 2. Fournissez-lui une commande sans danger, comme ls -la, et vous ne devriez obtenir aucune sortie, avec le code de sortie 0. Dans une session, l’appel refusé apparaît dans la transcription, avec votre message comme motif. Le modèle lit ce message et s’adapte.

Une propriété justifie à elle seule cette configuration : les hooks PreToolUse sont exécutés avant la vérification du mode d’autorisation, quel que soit ce mode. Un refus reste donc effectif, même avec bypassPermissions. C’est ce qui rend un hook utile en complément de Claude Code en mode automatique et de ses paramètres d’autorisation, lorsque les invites sont réduites, mais que le hook continue de s’exécuter.

Soyez clair sur la portée de ce mécanisme. La mise en correspondance d’un motif avec une chaîne de commande constitue une protection contre la négligence d’un agent. Elle ne constitue pas une limite contre un agent capable de contourner cette protection, car la même commande peut être écrite sous une forme que votre grep ne détecte jamais. Les règles strictes doivent être définies dans le système d’autorisation et dans le compte sous lequel le processus s’exécute.

Exemple 2 : formater et vérifier après chaque modification

PostToolUse avec un matcher Edit|Write s’exécute après tout outil de modification de fichier. Enregistrez ceci dans .claude/hooks/after-edit.sh :

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Demandez à Claude d’ajouter une fonction mal indentée dans un fichier Python, puis ouvrez le fichier. Il est automatiquement reformaté. Cela confirme que le hook s’est exécuté, car un hook qui réussit n’affiche rien dans la conversation.

Le code de sortie 2 n’annule rien ici. PostToolUse s’exécute après l’exécution de l’outil : la modification est donc écrite sur le disque dans tous les cas. Le code de sortie 2 permet de transmettre la sortie de ruff check au modèle comme feedback. Claude corrige ainsi l’erreur qu’il vient d’introduire au lieu de poursuivre. C’est la différence entre une erreur de linting détectée au moment du commit et une erreur corrigée par l’agent au cours du même tour.

Deux limites des matchers sont importantes ici. Edit|Write ne détecte pas les fichiers modifiés par une commande shell, et Claude écrit assez souvent les fichiers via Bash pour que cette lacune soit réelle. Pour couvrir chaque appel, faites aussi correspondre Bash et demandez au script de lister les fichiers modifiés avec git status --porcelain. Pour couvrir chaque tour une seule fois, placez plutôt l’analyse dans un hook Stop.

Exemple 3 : journaliser chaque appel d’outil à des fins d’audit

Un matcher vide sur PostToolUse s’exécute pour chaque outil. L’envoi de l’enregistrement vers le journal système, plutôt que vers un fichier du répertoire personnel, le met hors de portée du shell de l’agent :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

Relisez les entrées avec journalctl -t claude-code -o cat | tail -n 5. Vous devez obtenir une ligne JSON par appel d’outil, la plus récente en dernier. Si aucune entrée n’apparaît, le hook ne s’est pas exécuté. La section de dépannage ci-dessous explique comment diagnostiquer ce problème.

Ajoutez le même bloc sous PostToolUseFailure pour capturer les appels qui ont échoué, car PostToolUse ne s’exécute qu’en cas de succès et une commande en échec est généralement la plus intéressante. La raison d’utiliser logger plutôt que d’ajouter les entrées à un fichier du répertoire personnel tient à la propriété du fichier : un hook s’exécute avec le même utilisateur que le shell de l’agent. Tout ce que cet utilisateur peut ouvrir en ajout, il peut aussi le tronquer. Le journal est écrit par systemd-journald avec son propre compte.

Durée d’exécution maximale d’un hook

[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command hook on UserPromptSubmit",
    "default_timeout_seconds": 30
  },
  {
    "label": "command hook on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

Par défaut, un hook de commande dispose de 600 secondes, soit dix minutes. Certains événements réduisent fortement cette durée. Les hooks SessionEnd partagent un délai de 1.5 secondes au total. Le nettoyage de fin de session doit donc être rapide. Toutefois, définir une valeur timeout plus longue sur le hook augmente ce délai partagé en conséquence, jusqu’à 60 secondes.

Un hook qui atteint sa limite de temps est annulé et ne rend aucune décision. Pour une barrière de sécurité PreToolUse, cela signifie qu’il ne bloque pas l’opération : l’appel d’outil suit le flux normal de contrôle des permissions. Gardez donc les scripts de barrière de sécurité courts. Pour les tâches lentes qui n’attendent aucune réponse, comme l’envoi d’un log ailleurs, définissez "async": true. Le hook s’exécute alors en arrière-plan sans retarder l’appel d’outil.

Hooks, fichiers de règles, skills et serveurs MCP

Quatre éléments sont souvent confondus parce qu’ils modifient tous le comportement d’un agent. Un seul d’entre eux cesse d’être une simple suggestion.

Un fichier de règles (`CLAUDE.md ou un fichier situé sous .claude/rules/`) est du texte chargé dans le contexte du modèle. Il oriente le comportement, mais n’impose rien. Face à une longue conversation, à un diff volumineux et à une nouvelle demande de l’utilisateur, une seule de ses lignes peut être ignorée. C’est le mécanisme habituel qui explique pourquoi les agents ignorent les instructions que vous avez écrites.

Un skill est un dossier contenant des instructions et des scripts, que le modèle charge lorsqu’il juge le skill pertinent. Ce jugement est précisément le rôle d’un skill, mais aussi sa limite : le modèle décide toujours. Vous pouvez observer ces deux aspects avec un skill comme Ponytail, qui oriente l’agent vers la plus petite modification fonctionnelle : il structure la manière d’aborder toute une tâche, ce qu’aucun hook ne peut faire, mais uniquement lorsque le modèle choisit de le charger.

Un serveur MCP (model context protocol) fournit au modèle de nouveaux outils à appeler. Il étend ce à quoi l’agent peut accéder. Il ne le pousse pas à utiliser ces outils et il s’exécute dans un processus distinct que vous devez exploiter, ce qui constitue une tâche à part entière : voir exécuter des serveurs MCP sur un VPS.

Un hook est le seul des quatre à s’exécuter sans que le modèle le choisisse. Utilisez un fichier de règles pour exprimer une préférence et un skill pour une procédure que le modèle doit suivre lorsqu’elle s’applique. Utilisez un hook pour l’étape qui doit avoir lieu à chaque fois, ou pour l’action qui ne doit jamais avoir lieu. La comparaison détaillée, notamment les cas où un skill est préférable à un fichier de règles, se trouve dans la comparaison des skills, des serveurs MCP et des fichiers de règles.

Un plugin relève du packaging, et ne constitue pas un cinquième mécanisme. Il regroupe des hooks et des skills dans une même unité installable. C’est ainsi qu’une équipe déploie la même mesure de protection sur chaque machine : voir le fonctionnement des plugins Claude Code.

La décision de sécurité sur un VPS partagé

Un hook est du code déclenché par l’agent. Il s’exécute avec les droits de l’utilisateur qui a démarré Claude Code. Il hérite de l’environnement et des permissions sur les fichiers de cet utilisateur. Sur un ordinateur portable, c’est une question de workflow. Sur un VPS où un agent s’exécute sans supervision, c’est une question de sécurité qui comporte quatre aspects pratiques.

Un hook dans un dépôt est du code que vous n’avez pas écrit. .claude/settings.json est commité. Cloner un dépôt et démarrer une session dans ce dépôt peut donc enregistrer les hooks inclus avec le dépôt. Claude Code soumet les hooks du projet à la boîte de dialogue de confiance de l’espace de travail pour ce dossier. Accepter la confiance est donc le moment où vous décidez de les exécuter. Lisez d’abord le bloc hooks.

Un hook voit l’intégralité de l’entrée de l’outil. Un hook d’audit qui journalise tool_input écrit tous les arguments de chaque commande dans un fichier, y compris les éventuels tokens présents sur une ligne de commande. Ce journal doit ensuite être protégé comme le secret lui-même. Cela fait partie du problème plus général qui consiste à empêcher un agent IA d’accéder aux secrets.

Un hook peut écrire dans le contexte du modèle. Tout ce qu’un hook SessionStart ou UserPromptSubmit affiche sur stdout est ajouté à la conversation. Un hook qui injecte du texte provenant d’un système externe, d’un issue tracker ou d’un fichier journal transmet au modèle un texte non fiable, comme si vous l’aviez saisi vous-même. Traitez ce stdout comme une entrée, et non comme une sortie.

Le contrôle réel est le niveau de privilèges. Exécutez l’agent avec un utilisateur dédié et non privilégié, en lui accordant uniquement les règles sudo nécessaires. Un refus PreToolUse est utile. Il s’agit toutefois d’une mesure appliquée au mieux : la référence indique la même chose pour le filtre if et recommande d’utiliser le système de permissions lorsqu’un refus strict est nécessaire. Les règles de permission et le compte utilisé par le processus sont les éléments qui restent fiables sous pression.

Une propriété s’applique à toutes les configurations. Les hooks PreToolUse sont exécutés avant la vérification du mode de permission, quel que soit ce mode. Un hook qui renvoie deny bloque donc l’outil, même avec bypassPermissions. Les hooks peuvent renforcer les restrictions autorisées par les règles de permission. Ils ne peuvent pas les assouplir.

Pourquoi mon hook ne se déclenche-t-il pas ?

Procédez dans cet ordre. Chaque étape indique le symptôme que vous verrez réellement.

• Exécutez /hooks et vérifiez que le hook apparaît sous l’événement attendu. Un hook absent du menu indique généralement une erreur de syntaxe JSON dans le fichier de configuration, car les virgules finales et les commentaires ne sont pas autorisés, ou que le fichier ne se trouve dans aucun des six emplacements précédents.
• Comparez exactement le matcher avec le nom de l’outil. Les matchers sont sensibles à la casse : "bash" ne correspond donc jamais à l’outil Bash.
• Exécutez le script manuellement avec des données d’entrée d’exemple, comme dans l’exemple 1 ci-dessus. Un code de sortie inattendu indique un bug dans votre script. Claude Code le signale comme une erreur de hook, et non comme une décision.
• Un message indiquant jq: command not found signifie que jq est absent de cette machine. Un command not found pour votre propre script signifie que le chemin n’a pas été résolu. Utilisez donc ${CLAUDE_PROJECT_DIR} ou un chemin absolu. Si le script ne s’exécute jamais, il n’est probablement pas exécutable.
• Le hook affiche un JSON valide, mais rien ne se passe. Un hook au format shell s’exécute via sh -c. Si votre profil shell affiche une bannière, celle-ci est ajoutée au début du JSON. La sortie standard ne commence alors plus par {. Claude Code interprète donc l’ensemble comme du texte brut et ignore la décision. Avec le code de sortie 0, rien n’est signalé ailleurs que dans le journal de débogage. Entourez toute occurrence de echo dans votre profil afin qu’elle ne s’exécute que dans les shells interactifs.
• Le problème persiste : démarrez la session avec claude --debug-file /tmp/claude.log et exécutez tail -f /tmp/claude.log dans un second terminal. Le journal de débogage indique quels hooks correspondaient, le code de sortie renvoyé par chacun et tout ce qu’ils ont écrit sur la sortie standard et la sortie d’erreur.

FAQ

Quelle est la différence entre un hook Claude Code et une instruction CLAUDE.md ?

Une instruction CLAUDE.md est du texte placé dans le contexte du modèle. Elle doit donc être prise en compte avec la conversation et la demande en cours, et le modèle peut lui donner un poids différent. Un hook est une commande shell que Claude Code exécute à un moment précis de son cycle de vie. Il s’exécute donc à chaque occurrence de son événement, quelle que soit la décision du modèle. Utilisez une instruction pour exprimer une préférence. Utilisez un hook pour une étape qui doit toujours être exécutée ou pour une action qui ne doit jamais être exécutée.

Comment empêcher Claude Code d’exécuter une commande shell précise ?

Enregistrez un hook PreToolUse avec un matcher Bash qui lit la commande depuis .tool_input.command, écrit la raison sur stderr et quitte avec le code 2. Claude Code annule l’appel et affiche votre raison au modèle. Cela se produit avant la vérification du mode d’autorisation, de sorte que le refus reste effectif même en mode bypassPermissions. La recherche de motifs dans une chaîne de commande constitue un garde-fou, pas une limite de sécurité. La même commande peut être écrite sous une forme que le motif ne détecte pas. Complétez donc cette protection par des règles d’autorisation et par l’utilisation d’un compte non privilégié.

Mon hook affiche un JSON valide, mais rien ne se passe. Pourquoi ?

La cause la plus fréquente est votre profil shell. Un hook sans champ args s’exécute via sh -c. Certains profils affichent une bannière à chaque ouverture du shell, qui se retrouve sur stdout avant votre JSON. Comme la sortie ne commence plus par {, Claude Code la traite entièrement comme du texte brut et ignore la décision. Avec une sortie 0, rien n’est alors signalé dans la transcription. Protégez toute commande echo de votre profil par un test indiquant que le shell est interactif. Confirmez ensuite la correction en lisant le journal de débogage depuis claude --debug-file /tmp/claude.log.

Est-il sûr d’exécuter des hooks Claude Code sur un serveur partagé ?

Les hooks s’exécutent avec l’utilisateur qui a démarré Claude Code et avec les permissions sur les fichiers de cet utilisateur. Un hook peut donc effectuer toute opération autorisée pour ce compte. Deux pratiques couvrent la plupart des risques : exécuter l’agent avec un compte dédié non privilégié et une politique sudo restrictive, puis lire le bloc hooks de chaque dépôt avant d’accepter sa boîte de dialogue de confiance de l’espace de travail, car les hooks du projet sont fournis dans .claude/settings.json. Définissez "disableAllHooks": true dans votre fichier de configuration si vous ne voulez exécuter aucun de ces hooks.