Automatiser les actions avec les hooks

​

Configurer votre premier hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

Ce que vous pouvez automatiser

​

Être notifié lorsque Claude a besoin d’une entrée

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

notify-send 'Claude Code' 'test'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Formater automatiquement le code après les modifications

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

​

Bloquer les modifications des fichiers protégés

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Réinjecter le contexte après compaction

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Auditer les modifications de configuration

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Recharger l’environnement lorsque le répertoire ou les fichiers changent

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Approuver automatiquement les invites de permission spécifiques

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Comment fonctionnent les hooks

• "type": "http" : POST les données d’événement vers une URL. Consultez Hooks HTTP.
• "type": "mcp_tool" : appeler un outil sur un serveur MCP configuré. Consultez Champs de hooks d’outil MCP.
• "type": "prompt" : évaluation LLM à un seul tour. Consultez Hooks basés sur des invites.
• "type": "agent" : vérification multi-tour avec accès aux outils. Les hooks d’agent sont expérimentaux et peuvent changer. Consultez Hooks basés sur des agents.

​

Combiner les résultats de plusieurs hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

Lire l’entrée et retourner la sortie

​

Entrée du hook

• hook_event_name : l’événement qui a déclenché le hook
• tool_name : l’outil que Claude est sur le point d’utiliser
• tool_input : les arguments que Claude a passés à l’outil. Pour Bash, son champ command contient la commande shell.

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

​

Sortie du hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2 # exit 2 = block the action
fi

exit 0  # exit 0 = no decision; the normal permission flow applies

• Exit 0 : votre hook ne signale aucune objection via son code de sortie.
  • Pour un hook PreToolUse, cela n’approuve pas l’appel d’outil : le flux de permission normal s’applique toujours.
  • Pour les hooks UserPromptSubmit, UserPromptExpansion, SessionStart et PostModelSwitch, Claude Code ajoute stdout qu’il traite comme du texte brut au contexte de Claude.
• Exit 2 : Claude Code bloque l’action. Écrivez une raison sur stderr. Où elle aboutit dépend de l’événement : certains événements la transmettent à Claude comme retour afin qu’il puisse s’ajuster, d’autres la montrent à l’utilisateur, et quelques-uns, comme ConfigChange et Elicitation, ne font surface à aucun message. Certains événements ne peuvent pas être bloqués : pour SessionStart et autres, exit 2 affiche stderr à l’utilisateur et l’exécution continue. Consultez comportement du code de sortie 2 par événement pour la liste complète.
• Tout autre code de sortie : pour la plupart des événements, le résultat dépend de ce que votre hook a imprimé sur stdout :
  • Un objet analysé qui passe la validation du schéma : Claude Code ignore le code de sortie, le JSON seul décide du résultat, et le hook n’est pas signalé comme une erreur. Les exceptions par événement, comme WorktreeCreate échouant sur tout code de sortie non nul, sont listées dans la section Sortie du code de sortie de la référence.
  • Un objet analysé qui échoue la validation du schéma, ou stdout que Claude Code essaie d’analyser comme JSON mais qui n’est pas du JSON valide : une erreur non bloquante ; l’avis porte le message de validation ou d’analyse.
  • Stdout que Claude Code traite comme du texte brut, ou stdout vide : l’action se poursuit comme une erreur non bloquante. La transcription affiche un avis <hook name> hook error, puis la première ligne de stderr préfixée par Failed with non-blocking status code:. Pour capturer le stderr complet, activez le journal de débogage avec claude --debug ou en exécutant /debug en milieu de session.

​

Sortie JSON structurée

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow" : ignorer l’invite de permission interactive. Les règles de refus et d’ask, y compris les listes de refus gérées par l’entreprise, s’appliquent toujours, tout comme les invites pour les outils MCP marqués requiresUserInteraction et pour les outils de connecteur que votre organisation a définis sur ask dans les sessions où ce paramètre atteint Claude Code
• "deny" : annuler l’appel d’outil et envoyer la raison à Claude
• "ask" : afficher l’invite de permission à l’utilisateur comme d’habitude

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

Filtrer les hooks avec des matchers

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Filtrer par nom d’outil et arguments avec le champ if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Configurer l’emplacement du hook

​

Hooks basés sur des invites

• "ok": true : l’action se poursuit
• "ok": false : ce qui se passe dépend de l’événement :
  • Stop et SubagentStop : la reason est renvoyée à Claude afin qu’il continue à travailler, sauf si la réponse définit également "impossible": true pour marquer la condition comme une condition qui ne peut jamais être satisfaite, auquel cas Claude Code autorise l’arrêt et le tour se termine
  • PreToolUse : l’appel d’outil est refusé ; par défaut le tour se termine et la reason du refus apparaît dans le chat sous forme de ligne d’avertissement. Définissez continueOnBlock: true sur le hook pour retourner à la place la reason à Claude comme erreur d’outil, afin qu’il puisse s’ajuster et continuer. Avant v2.1.210, la reason du refus était retournée à Claude comme erreur d’outil et le tour continuait
  • PostToolUse : par défaut le tour se termine et la reason apparaît dans le chat sous forme de ligne d’avertissement. Définissez continueOnBlock: true pour retourner la reason à Claude et continuer le tour à la place
  • PostToolBatch, UserPromptSubmit et UserPromptExpansion : le tour se termine et la reason apparaît dans le chat sous forme de ligne d’avertissement

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks basés sur des agents

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

Hooks HTTP

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Limitations et dépannage

​

Limitations

• Les hooks de commande communiquent uniquement via stdout, stderr et les codes de sortie. Ils ne peuvent pas déclencher des commandes / ou des appels d’outils. Le texte retourné via additionalContext est injecté comme un rappel système que Claude lit en tant que texte brut. Les hooks HTTP communiquent via le corps de la réponse à la place.
• Les délais d’expiration du hook varient selon le type. Remplacez par hook avec le champ timeout en secondes.
  • command, http, mcp_tool : 10 minutes. Claude Code réduit cette valeur par défaut à 30 secondes pour les hooks UserPromptSubmit, PreModelSwitch et PostModelSwitch, et à 10 secondes pour MessageDisplay.
  • prompt : 30 secondes.
  • agent : 60 secondes.
  • Les hooks SessionEnd de tout type partagent un budget de 1,5 seconde. Si vos paramètres définissent un timeout par hook plus long, Claude Code augmente le budget pour correspondre, jusqu’à 60 secondes.
• Les hooks PostToolUse ne peuvent pas annuler les actions puisque l’outil a déjà été exécuté.
• Les hooks PermissionRequest se déclenchent lorsque Claude Code est sur le point de vous demander une permission.
  • En mode non-interactif avec l’indicateur -p, cette invite n’existe que lorsque le callback canUseTool du SDK Agent la fournit. Dans les exécutions -p simples ou avec --permission-prompt-tool, utilisez plutôt les hooks PreToolUse pour les décisions de permission automatisées.
  • Les sous-agents en arrière-plan ne peuvent pas afficher une invite en mode non-interactif. Claude Code exécute toujours les hooks pour leurs appels d’outils, et si aucun hook ne retourne une décision, il refuse l’appel. Dans une session interactive, les invites des sous-agents en arrière-plan s’affichent dans votre session principale et les hooks se déclenchent comme d’habitude.
• Les hooks Stop se déclenchent chaque fois que Claude termine sa réponse, pas seulement à la fin de la tâche. Ils ne se déclenchent pas sur les interruptions de l’utilisateur. Les erreurs API déclenchent StopFailure à la place.
• Lorsque plusieurs hooks PreToolUse retournent updatedInput pour réécrire les arguments d’un outil, le dernier à terminer gagne. Puisque les hooks s’exécutent en parallèle, l’ordre est non-déterministe. Évitez d’avoir plus d’un hook modifier l’entrée du même outil.

​

Hooks et modes de permission

​

Hook ne se déclenche pas

• Exécutez /hooks et confirmez que le hook apparaît sous l’événement correct
• Vérifiez que le modèle de matcher correspond exactement au nom de l’outil. Les matchers sont sensibles à la casse
• Vérifiez que vous déclenchez le bon type d’événement : PreToolUse se déclenche avant l’exécution de l’outil, PostToolUse se déclenche après. Un hook PermissionRequest se déclenche lorsque Claude Code est sur le point de vous demander une permission ; consultez les limitations pour les cas non-interactifs

​

Erreur du hook dans la sortie

• Votre script a quitté avec un code non-zéro de manière inattendue. Testez-le manuellement en piping du JSON d’exemple :
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• Si vous voyez « command not found », utilisez des chemins absolus ou ${CLAUDE_PROJECT_DIR} pour référencer les scripts. Pour éviter complètement les guillemets du shell, ajoutez "args": [] pour basculer vers la forme exec, qui génère le script directement sans shell
• Si vous voyez « jq: command not found », installez jq ou utilisez Python/Node.js pour l’analyse JSON
• Si l’avis affiche un message de validation JSON, la sortie de votre hook a été analysée en JSON mais a échoué la validation du schéma. S’il affiche un message d’analyse JSON, la sortie ressemblait à un objet JSON mais n’était pas du JSON valide. Les deux se produisent même à la sortie 0. Pour corriger un échec d’analyse, construisez la charge utile avec un encodeur JSON tel que jq au lieu de la concaténation de chaînes, afin que les guillemets et les barres obliques inverses à l’intérieur des valeurs soient échappés. La section Exit code output de la référence couvre les combinaisons de code de sortie et JSON
• Si le script ne s’exécute pas du tout, rendez-le exécutable : chmod +x ./my-hook.sh

​

/hooks n’affiche aucun hook configuré

• Les modifications de fichiers sont normalement récupérées automatiquement. Si elles n’ont pas apparues après quelques secondes, l’observateur de fichiers peut avoir manqué la modification : redémarrez votre session pour forcer un rechargement.
• Vérifiez que votre JSON est valide : les virgules finales et les commentaires ne sont pas autorisés
• Confirmez que le fichier de paramètres est au bon emplacement : .claude/settings.json pour les hooks de projet, ~/.claude/settings.json pour les hooks globaux

​

Le hook Stop atteint le plafond de blocage

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

​

Hook JSON n’a aucun effet

• Sortie supplémentaire avant le JSON : quelque chose d’autre écrit sur stdout en premier, généralement un echo inconditionnel dans votre profil shell, donc la sortie ne commence plus par { et Claude Code ne l’analyse pas en JSON. La cause et la correction suivent cette liste.
• Un champ au mauvais niveau : comparez le placement de chaque champ par rapport au format JSON output. Par exemple, permissionDecision appartient à l’intérieur de hookSpecificOutput, pas au niveau supérieur.

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Techniques de débogage

• Exécution réussie : vous ne voyez rien, sauf si le JSON du hook affiche quelque chose, comme systemMessage ou un retour du hook Stop.
  • Pour confirmer qu’un hook a été exécuté, vérifiez son effet, comme un fichier reformaté, ou activez la journalisation de débogage comme décrit ci-dessous et déclenchez le hook à nouveau
• Erreur de blocage : sur la plupart des événements, vous voyez le retour du hook. Lorsque le JSON du hook a pris une décision de blocage, le retour est la raison de cette décision ; sinon, c’est stderr du hook. Sur quelques événements, comme ConfigChange et Elicitation, un blocage ne surface aucun message.
• Erreur sans blocage : l’action a procédé, et vous voyez un avis <hook name> hook error avec une brève explication, comme la première ligne de stderr préfixée par Failed with non-blocking status code:, ou un message de validation ou d’analyse JSON.

​

En savoir plus

• Référence des Hooks : schémas d’événements complets, format de sortie JSON, hooks asynchrones et hooks d’outils MCP
• Considérations de sécurité : examinez avant de déployer les hooks dans des environnements partagés ou de production
• Exemple de validateur de commande Bash : implémentation de référence complète