SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor

Hooks Claude Code : fonctionnement, événements et sécurité

Découvrez où configurer les hooks Claude Code, les événements déclenchés, le rôle du code de sortie 2 et les risques de sécurité liés à leur exécution automatique.

Ce qu’est un hook Claude Code

Les hooks Claude Code sont des commandes shell que Claude Code exécute automatiquement à des points précis de son 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, et le modèle l’évalue avec le reste de son contexte. Un hook est du code, et il 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 paramètres, sous le nom d’un é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. Le code de sortie 2 d’un hook PreToolUse annule l’appel de l’outil avant son exécution, et tout ce que votre script écrit sur la sortie d’erreur standard (stderr) est transmis au modèle comme motif, sauf si le hook affiche également du JSON contenant une décision de blocage : dans ce cas, le motif de cette décision est prioritaire.

Les noms d’événements et de champs utilisés ici proviennent de la référence des hooks de Claude Code, vérifiée le 12 novembre 2026. 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.

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éfinit celle du hook.

  • ~/.claude/settings.json : tous les projets de votre machine, mais pas ceux des autres utilisateurs.
  • .claude/settings.json : un seul projet, validé dans le dépôt. Toute personne qui le clone obtient donc le hook.
  • .claude/settings.local.json : un seul projet, sur votre machine uniquement.
  • 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’une skill ou d’un subagent. Les hooks d’une skill restent actifs jusqu’à la fin de la session après l’appel de la skill. Ceux d’un subagent restent actifs pendant son exécution.

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 événement peut donc contenir plusieurs hooks provenant de plusieurs fichiers. Définir "disableAllHooks": true les désactive, à une exception près : les hooks provenant des paramètres de stratégie gérés continuent de s’exécuter, sauf si ce paramètre est également appliqué 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 le fichier source et le matcher de chacun. 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.

Quels événements de hooks Claude Code existent

La référence des hooks répertorie trente trois événements, de SessionStart à SessionEnd, couvrant la compaction, les sous-agents, les worktrees et les fichiers de configuration. Pour l’administration des serveurs, seuls quelques-uns sont utilisés.

  • PreToolUse : avant l’exécution d’un appel d’outil, sauf pour EndConversation. C’est celui qui peut bloquer l’appel.
  • PostToolUse : après la réussite d’un appel d’outil, sauf pour EndConversation. PostToolUseFailure se déclenche à la place lorsqu’il échoue. Un hook qui doit voir chaque résultat doit donc utiliser les deux.
  • PermissionRequest : lorsqu’un appel d’outil nécessite une décision d’autorisation, au moment où l’invite d’approbation s’afficherait.
  • UserPromptSubmit : lorsque vous envoyez un prompt, avant que Claude le traite. La sortie stdout en texte brut d’un hook qui réussit est ajoutée 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. Cela se produit une fois par tour, et non une fois par tâche terminée.

Pour les événements qui prennent en charge les matchers, un groupe peut contenir un matcher qui détermine quelles occurrences exécutent le hook. Pour les événements liés aux outils, 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 et ignore ceux des autres.

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. Par défaut, Claude Code remplace le blocage suivant après huit continuations consécutives, et le compteur est réinitialisé chaque fois que Claude appelle un outil. Lisez le champ stop_hook_active dans l’entrée du hook et quittez avec le code 0 lorsqu’il vaut true. Sinon, votre hook peut renvoyer Claude au travail indéfiniment.

Entrée standard reçue par un hook

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

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

Les champs d’entrée courants incluent session_id, cwd, transcript_path et hook_event_name ; permission_mode n’est pas envoyé lors de chaque événement. Les événements liés aux outils ajoutent tool_name, tool_input et tool_use_id. Les autres événements transportent 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 de 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 à l’appel d’outil en cours

Il existe trois issues possibles.

  • Le code de sortie 0 indique une réussite. Tous les champs de décision JSON valides restent applicables, y compris un blocage ou un refus. Sur PreToolUse, le code de sortie 0 sans décision n’est pas une approbation : le flux normal de contrôle des permissions continue. Sur UserPromptSubmit, UserPromptExpansion, SessionStart et PostModelSwitch, la sortie standard en texte brut est ajoutée au contexte du modèle. Pour la plupart des autres événements, la sortie standard est envoyée uniquement au journal de débogage.
  • Le code de sortie 2 bloque l’action pour les événements qui peuvent être bloqués, notamment PreToolUse. La sortie d’erreur devient le message associé au blocage, sauf si la sortie JSON contient une décision de blocage : sa raison est alors prioritaire. Le destinataire de ce message dépend de l’événement. Sur PreToolUse et Stop, le modèle le voit comme la raison du blocage. Sur UserPromptSubmit et PreModelSwitch, le message vous est affiché et n’est pas ajouté au contexte du modèle. Sur PostToolUse et PostToolUseFailure, qui ne peuvent pas être bloqués, le blocage est ignoré, mais la sortie d’erreur parvient tout de même au modèle comme feedback. Pour la plupart des autres événements qui ne peuvent pas être bloqués, la sortie d’erreur vous est affichée uniquement ou est ignorée. Sur Stop, SubagentStop, TaskCompleted et le hook UserPromptSubmit d’un plugin, le code de sortie 2 avec une sortie standard vide et une erreur de fichier absent sur la sortie d’erreur est traité comme une erreur sans blocage.
  • Tout autre code de sortie, avec une sortie standard en texte brut ou vide, est normalement traité comme une erreur sans blocage. La transcription affiche une notification d’erreur du hook contenant la première ligne de la sortie d’erreur après le texte Failed with non-blocking status code:. Un JSON valide peut tout de même décider de l’issue pour des événements tels que PreToolUse, sauf si l’échec du hook bloque l’action. WorktreeCreate échoue lors de toute sortie différente de zéro. WorktreeRemove échoue lors d’une sortie différente de zéro si le répertoire existe toujours ensuite.

Pour toute décision autre qu’un blocage ou l’absence de réponse, utilisez le code de sortie 0 et affichez plutôt un objet JSON sur la sortie standard. Un hook PreToolUse prend une 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 lorsque les règles de permissions et les exigences d’approbation de l’outil l’autorisent. "deny" annule l’appel et envoie la raison au modèle. "ask" demande une confirmation. Choisissez un seul style par hook. Si vous combinez le code de sortie 2 avec une décision JSON sur la sortie standard, le blocage reste appliqué, même si le JSON indique "allow".

Lorsque plusieurs hooks correspondent au même événement, ils s’exécutent en parallèle. Les hooks de prompt et d’agent sont limités à douze exécutions simultanées. Un deny provenant d’un hook n’arrête pas ses hooks frères. Ainsi, un hook de journalisation écrit toujours sa ligne pendant qu’un hook de protection refuse le même appel. Pour PreToolUse, 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 dans .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 s’ouvre généralement par défaut lorsque onFailure n’est pas défini. Sous Windows sans Git Bash, un hook de commande PreToolUse ou PermissionRequest au format shell qui échoue peut au contraire bloquer l’appel de l’outil :

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 telle que ls -la : vous ne devriez voir aucune sortie et obtenir le code de sortie 0. Dans une session, l’appel refusé apparaît dans la transcription avec votre message comme motif, puis le modèle lit ce message et adapte son comportement.

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 le mode d’autorisation utilisé. 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 est toujours exécuté.

Soyez clair sur la portée de ce mécanisme. La recherche de motifs dans une chaîne de commande protège contre la négligence d’un agent. Elle ne constitue pas une limite contre un agent capable de contourner cette règle, 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 le code après chaque modification

PostToolUse avec un matcher Edit|Write s’exécute après la réussite de l’un ou l’autre de ces outils de modification de fichiers. 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 correctement formaté. 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 enregistrée sur le disque dans tous les cas. L’intérêt du code de sortie 2 est que la sortie de ruff check est transmise au modèle comme feedback. Le modèle 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 pendant le 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 suffisamment souvent les fichiers via Bash pour que cette lacune soit réelle. Pour couvrir chaque appel, faites également 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 se déclenche après chaque appel d’outil réussi, sauf EndConversation. Envoyer l’enregistrement au journal système plutôt que dans un fichier du répertoire personnel ne le soustrait pas à l’accès du shell de l’agent : l’accès dépend des permissions du compte. Les utilisateurs peuvent lire leurs journaux privés par utilisateur. root et les membres de systemd-journal, adm ou wheel peuvent lire tous les fichiers de journal :

{
  "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. Si vous avez l’autorisation de lire les enregistrements, vous devez voir une ligne JSON par appel d’outil réussi autre que EndConversation, dans l’ordre chronologique, avec l’entrée la plus récente en dernier. Si rien ne s’affiche, vérifiez l’accès au journal ainsi que l’exécution du hook ; la section de dépannage ci-dessous traite du hook.

Ajoutez le même bloc sous PostToolUseFailure pour enregistrer les appels qui ont échoué, car PostToolUse ne se déclenche 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é : un hook s’exécute avec le même utilisateur que le shell de l’agent. Tout ce que cet utilisateur peut modifier en ajoutant du contenu, il peut aussi le tronquer. Le journal est écrit par systemd-journald ; sa protection contre la suppression dépend néanmoins des privilèges du compte de l’agent.

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

GraphiqueDefault hook timeout in seconds, by hook type and event
Les données de ce graphique
[
  {
    "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, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool 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 se partagent un délai de 1.5 seconde, ce qui impose un nettoyage rapide en fin de session. Toutefois, définir une valeur timeout plus longue pour un hook dans vos fichiers de configuration augmente ce délai partagé en conséquence, jusqu’à 60 secondes.

Un hook synchrone de commande, HTTP ou d’outil MCP qui atteint son délai d’expiration est annulé et ne produit normalement aucune décision ; avec PreModelSwitch, l’expiration bloque le changement. Pour une protection PreToolUse, l’expiration laisse normalement l’appel d’outil suivre le flux normal d’autorisation, sauf dans le cas Windows indiqué ci-dessus lorsque onFailure n’est pas défini. Gardez donc les scripts de protection courts. Depuis la version 2.1.295, vous pouvez inverser ce comportement par défaut pour un hook command ou http avec "onFailure": "block". Une expiration, un crash ou un code de sortie inattendu devient alors un blocage. Cette option n’a toutefois aucun effet sur Stop, SubagentStop, TaskCompleted, TeammateIdle ni sur les hooks de commande exécutés en arrière-plan. Pour les tâches lentes qui ne nécessitent pas d’attendre, comme l’envoi d’un log ailleurs, définissez "async": true. Le hook s’exécute alors en arrière-plan sans bloquer 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 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 son comportement, mais n’impose rien. Face à une longue conversation, à un diff volumineux et à une nouvelle demande, une de ses lignes peut être oubliée. C’est le mécanisme habituel qui explique pourquoi les agents ignorent les instructions que vous avez écrites.

Une skill est un dossier contenant des instructions et des scripts que le modèle charge lorsqu’il juge la skill pertinente. Ce jugement est précisément l’objectif d’une skill, mais aussi sa limite : le modèle garde la décision. Vous pouvez observer ces deux aspects avec une skill comme Ponytail, qui oriente l’agent vers la plus petite modification fonctionnelle : elle structure l’approche de toute une tâche d’une manière qu’aucun hook ne permet, mais uniquement lorsque le modèle choisit de la charger.

Un serveur MCP (model context protocol) fournit au modèle de nouveaux outils à appeler. Il élargit ce à quoi l’agent peut accéder. Il ne l’incite pas à utiliser ces outils. C’est aussi 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 une skill pour définir 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ù une 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 plutôt que d’un cinquième mécanisme. Il regroupe des hooks et des skills dans une unité installable. C’est ainsi qu’une équipe déploie la même 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, et il s’exécute avec les droits de l’utilisateur qui a démarré Claude Code. Il hérite des permissions sur les fichiers et de l’environnement de cet utilisateur. Sur un ordinateur portable, c’est une question de workflow. Sur un VPS où un agent s’exécute sans surveillance, c’est une question de sécurité qui comporte quatre aspects pratiques.

Un hook présent dans un dépôt est du code que vous n’avez pas écrit. .claude/settings.json est versionné, donc cloner un dépôt et démarrer une session à l’intérieur peut enregistrer les hooks fournis avec le dépôt. Dans une session interactive, 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. Une session claude -p ou SDK, qui est généralement utilisée par un agent sans surveillance, n’affiche jamais cette boîte de dialogue et considère le dossier comme fiable. Les hooks du dépôt s’exécutent donc sans confirmation. Examinez ses fichiers .claude/ avant d’écrire des scripts qui l’utilisent, ou exécutez-le avec --settings '{"disableAllHooks": true}'.

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 journal, y compris tout token qui se trouvait par hasard sur une ligne de commande. Ce journal doit alors être protégé au même niveau que le secret. Cela fait partie du problème plus général consistant à maintenir les secrets hors de portée d’un agent IA.

Un hook peut écrire dans le contexte du modèle. La sortie stdout en texte brut d’un hook SessionStart ou UserPromptSubmit qui réussit est ajoutée à la conversation. Un hook qui injecte du texte provenant d’une source externe, d’un outil de suivi des tickets ou d’un fichier journal transmet ce texte non fiable au modèle comme si vous l’aviez saisi vous-même. Un hook qui relaie une note provenant d’une autre session Claude Code sur le même VPS fait la même chose. La sortie d’un agent ne mérite pas davantage votre confiance que celle de l’outil de suivi des tickets. Traitez cette sortie stdout comme une entrée, et non comme une sortie.

Les privilèges constituent le véritable contrôle. Exécutez l’agent avec un utilisateur dédié et sans privilèges, en ne lui accordant que les règles sudo nécessaires. Un refus PreToolUse est utile, mais il est conçu pour fonctionner au mieux : la référence indique la même chose à propos du filtre if et vous demande d’utiliser le système de permissions lorsque vous avez besoin d’un refus strict. Les règles de permission et le compte sous lequel le processus s’exécute sont les éléments qui restent fiables sous contrainte.

Une propriété s’applique à tous les modes de permission. Les hooks PreToolUse s’exécutent 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 ce que les règles de permission autorisent. Ils ne peuvent pas l’assouplir. L’exception concerne un mod. Sur une machine sans paramètres gérés et sans fichier managed-mcp.json, dans une session qui n’est pas connectée via /login à une offre Team ou Enterprise, un mod installé qui gère tool.check peut autoriser un appel bloqué par votre hook PreToolUse. Avec des paramètres gérés, un fichier managed-mcp.json ou une /login Team ou Enterprise utilisée comme identifiant de la session, un appel bloqué par un hook PreToolUse reste bloqué par défaut, quel que soit le fichier de paramètres dont provient le hook. Une session qui s’exécute avec une clé API ou un CLAUDE_CODE_OAUTH_TOKEN de longue durée, comme c’est le cas de nombreux serveurs, est considérée comme non connectée, même lorsqu’un identifiant de connexion est enregistré. Vérifiez ce que les mods Claude Code peuvent modifier avant d’en installer un sur un serveur.

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

Suivez ces étapes dans l’ordre. Chaque étape décrit 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 indiqués plus haut.
  • Comparez exactement le matcher avec le nom de l’outil. Les matchers sont sensibles à la casse. Ainsi, "bash" ne correspond jamais à l’outil Bash.
  • Exécutez le script manuellement avec un exemple d’entrée, comme dans l’exemple 1 ci-dessus. Un code de sortie inattendu indique un bug dans votre script. Vérifiez également sa sortie standard, car un JSON valide peut tout de même fournir une décision pour des événements tels que PreToolUse.
  • 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. Sur macOS et Linux, un hook de type shell est exécuté via sh -c dans un shell non interactif. Certaines configurations chargent toutefois votre profil, par exemple BASH_ENV qui pointe vers ~/.bashrc. Si ce profil affiche une bannière, celle-ci est ajoutée avant votre 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. Comme le hook s’est terminé avec le code 0, la transcription n’affiche aucune erreur. Pour la plupart des événements, ce texte est envoyé uniquement dans le journal de débogage. Pour UserPromptSubmit, UserPromptExpansion, SessionStart et PostModelSwitch, il est en revanche ajouté au contexte du modèle, bannière comprise. Entourez tout echo dans votre profil afin qu’il 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 entre donc en concurrence avec la conversation et la demande actuelle, et le modèle peut la mettre en balance avec celles-ci. 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 une action qui ne doit jamais l’être.

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 se termine avec le code 2. Claude Code annule l’appel et affiche votre raison au modèle. Cela se produit avant la vérification du permission mode, donc le refus reste applicable même en mode bypassPermissions. La mise en correspondance d’une chaîne de commande constitue une mesure de protection, pas une frontière de sécurité, car la même commande peut être écrite sous une forme que le pattern ne détecte pas. Complétez donc cette protection par des règles de permissions et par l’utilisation d’un compte non privilégié.

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

Vérifiez si votre profil shell affiche du texte avant le JSON. Sous macOS et Linux, un hook sans champ args s’exécute via sh -c. Dans les configurations qui chargent toujours votre profil, par exemple lorsque BASH_ENV pointe vers ~/.bashrc, un profil qui affiche une bannière l’écrit sur stdout avant votre JSON. Comme la sortie ne commence alors plus par {, Claude Code la traite entièrement comme du texte brut et ignore la décision. Comme le hook s’est terminé avec le code 0, le transcript n’affiche aucune erreur. Protégez toute commande echo de votre profil par un test indiquant que le shell est interactif, puis confirmez la correction en consultant le debug log 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 de fichiers de cet utilisateur. Un hook peut donc effectuer toutes les opérations autorisées à ce compte. Deux pratiques couvrent l’essentiel des risques : exécutez l’agent avec un compte dédié non privilégié et une policy sudo restrictive, puis lisez le bloc hooks de tout repository avant d’accepter sa boîte de dialogue de confiance de l’espace de travail ou d’y exécuter claude -p, car les hooks du projet sont inclus dans .claude/settings.json et le mode -p n’affiche jamais cette boîte de dialogue. Définissez "disableAllHooks": true dans votre fichier de settings pour désactiver les hooks, sauf les hooks gérés qui exigent ce paramètre au niveau managed. Un paramètre de projet false peut remplacer un paramètre utilisateur true.

Cet article vous a-t-il été utile ?