Référence des hooks

​

Configuration

• ~/.claude/settings.json - Paramètres utilisateur
• .claude/settings.json - Paramètres du projet
• .claude/settings.local.json - Paramètres du projet local (non validés)
• Paramètres de politique gérés par l’entreprise

​

Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

• matcher : Motif pour correspondre aux noms d’outils, sensible à la casse (applicable uniquement pour PreToolUse et PostToolUse)
  • Les chaînes simples correspondent exactement : Write correspond uniquement à l’outil Write
  • Supporte les expressions régulières : Edit|Write ou Notebook.*
  • Utilisez * pour correspondre à tous les outils. Vous pouvez également utiliser une chaîne vide ("") ou laisser matcher vide.
• hooks : Tableau de commandes à exécuter lorsque le motif correspond
  • type : Actuellement, seul "command" est supporté
  • command : La commande bash à exécuter (peut utiliser la variable d’environnement $CLAUDE_PROJECT_DIR)
  • timeout : (Optionnel) Durée pendant laquelle une commande doit s’exécuter, en secondes, avant d’annuler cette commande spécifique.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

​

Scripts de hooks spécifiques au projet

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

​

Hooks de plugins

• Les hooks de plugins sont définis dans le fichier hooks/hooks.json du plugin ou dans un fichier donné par un chemin personnalisé vers le champ hooks.
• Lorsqu’un plugin est activé, ses hooks sont fusionnés avec les hooks utilisateur et projet
• Plusieurs hooks de différentes sources peuvent répondre au même événement
• Les hooks de plugins utilisent la variable d’environnement ${CLAUDE_PLUGIN_ROOT} pour référencer les fichiers de plugins

{
  "description": "Formatage automatique du code",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

• ${CLAUDE_PLUGIN_ROOT} : Chemin absolu vers le répertoire du plugin
• ${CLAUDE_PROJECT_DIR} : Répertoire racine du projet (identique à celui des hooks de projet)
• Toutes les variables d’environnement standard sont disponibles

​

Événements de hooks

​

PreToolUse

• Task - Tâches de sous-agent (consultez la documentation des sous-agents)
• Bash - Commandes shell
• Glob - Correspondance de motif de fichier
• Grep - Recherche de contenu
• Read - Lecture de fichier
• Edit - Édition de fichier
• Write - Écriture de fichier
• WebFetch, WebSearch - Opérations web

​

PostToolUse

​

Notification

1. Claude a besoin de votre permission pour utiliser un outil. Exemple : « Claude a besoin de votre permission pour utiliser Bash »
2. L’entrée de l’invite est restée inactive pendant au moins 60 secondes. « Claude attend votre entrée »

​

UserPromptSubmit

​

Stop

​

SubagentStop

​

PreCompact

• manual - Invoqué depuis /compact
• auto - Invoqué depuis le compactage automatique (en raison d’une fenêtre de contexte complète)

​

SessionStart

• startup - Invoqué au démarrage
• resume - Invoqué depuis --resume, --continue ou /resume
• clear - Invoqué depuis /clear
• compact - Invoqué depuis le compactage automatique ou manuel.

​

Persistance des variables d’environnement

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Exécutez vos commandes de configuration qui modifient l'environnement
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

​

SessionEnd

• clear - Session effacée avec la commande /clear
• logout - Utilisateur déconnecté
• prompt_input_exit - Utilisateur quitté alors que l’entrée d’invite était visible
• other - Autres raisons de sortie

​

Entrée de hook

{
  // Champs communs
  session_id: string
  transcript_path: string  // Chemin vers le JSON de conversation
  cwd: string              // Le répertoire de travail courant lorsque le hook est invoqué
  permission_mode: string  // Mode de permission actuel : "default", "plan", "acceptEdits" ou "bypassPermissions"

  // Champs spécifiques à l'événement
  hook_event_name: string
  ...
}

​

Entrée PreToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

​

Entrée PostToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

​

Entrée Notification

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

​

Entrée UserPromptSubmit

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

​

Entrée Stop et SubagentStop

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

​

Entrée PreCompact

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

​

Entrée SessionStart

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

​

Entrée SessionEnd

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

​

Sortie de hook

​

Simple : Code de sortie

• Code de sortie 0 : Succès. stdout est montré à l’utilisateur en mode transcription (CTRL-R), sauf pour UserPromptSubmit et SessionStart, où stdout est ajouté au contexte.
• Code de sortie 2 : Erreur de blocage. stderr est renvoyé à Claude pour être traité automatiquement. Consultez le comportement spécifique à chaque événement de hook ci-dessous.
• Autres codes de sortie : Erreur sans blocage. stderr est montré à l’utilisateur et l’exécution continue.

​

Comportement du code de sortie 2

​

Avancé : Sortie JSON

​

Champs JSON communs

{
  "continue": true, // Si Claude doit continuer après l'exécution du hook (par défaut : true)
  "stopReason": "string", // Message montré lorsque continue est false

  "suppressOutput": true, // Masquer stdout du mode transcription (par défaut : false)
  "systemMessage": "string" // Message d'avertissement optionnel montré à l'utilisateur
}

• Pour PreToolUse, ceci est différent de "permissionDecision": "deny", qui bloque uniquement un appel d’outil spécifique et fournit un retour automatique à Claude.
• Pour PostToolUse, ceci est différent de "decision": "block", qui fournit un retour automatisé à Claude.
• Pour UserPromptSubmit, ceci empêche le traitement de l’invite.
• Pour Stop et SubagentStop, ceci a priorité sur tout "decision": "block" en sortie.
• Dans tous les cas, "continue" = false a priorité sur tout "decision": "block" en sortie.

​

Contrôle de décision PreToolUse

• "allow" contourne le système de permission. permissionDecisionReason est montré à l’utilisateur mais pas à Claude.
• "deny" empêche l’exécution de l’appel d’outil. permissionDecisionReason est montré à Claude.
• "ask" demande à l’utilisateur de confirmer l’appel d’outil dans l’interface utilisateur. permissionDecisionReason est montré à l’utilisateur mais pas à Claude.

• updatedInput vous permet de modifier les paramètres d’entrée de l’outil avant l’exécution de l’outil. C’est un objet Record<string, unknown> contenant les champs que vous souhaitez modifier ou ajouter.
• Ceci est très utile avec "permissionDecision": "allow" pour modifier et approuver les appels d’outil.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow"
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    }
  }
}

​

Contrôle de décision PostToolUse

• "block" invite automatiquement Claude avec reason.
• undefined ne fait rien. reason est ignoré.
• "hookSpecificOutput.additionalContext" ajoute du contexte pour que Claude le considère.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

​

Contrôle de décision UserPromptSubmit

• "block" empêche le traitement de l’invite. L’invite soumise est effacée du contexte. "reason" est montré à l’utilisateur mais pas ajouté au contexte.
• undefined permet à l’invite de procéder normalement. "reason" est ignoré.
• "hookSpecificOutput.additionalContext" ajoute la chaîne au contexte si elle n’est pas bloquée.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

​

Contrôle de décision Stop/SubagentStop

• "block" empêche Claude de s’arrêter. Vous devez remplir reason pour que Claude sache comment procéder.
• undefined permet à Claude de s’arrêter. reason est ignoré.

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

​

Contrôle de décision SessionStart

• "hookSpecificOutput.additionalContext" ajoute la chaîne au contexte.
• Les valeurs additionalContext de plusieurs hooks sont concaténées.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

​

Contrôle de décision SessionEnd

​

Exemple de code de sortie : Validation de commande Bash

#!/usr/bin/env python3
import json
import re
import sys

# Définir les règles de validation comme une liste de tuples (motif regex, message)
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# Valider la commande
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Le code de sortie 2 bloque l'appel d'outil et montre stderr à Claude
    sys.exit(2)

​

Exemple de sortie JSON : UserPromptSubmit pour ajouter du contexte et de la validation

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# Charger l'entrée depuis stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Vérifier les motifs sensibles
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Utiliser la sortie JSON pour bloquer avec une raison spécifique
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Ajouter l'heure actuelle au contexte
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
Ce qui suit est également équivalent :
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Permettre à l'invite de procéder avec le contexte supplémentaire
sys.exit(0)

​

Exemple de sortie JSON : PreToolUse avec approbation

#!/usr/bin/env python3
import json
import sys

# Charger l'entrée depuis stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Exemple : Approuver automatiquement les lectures de fichier pour les fichiers de documentation
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Utiliser la sortie JSON pour approuver automatiquement l'appel d'outil
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # Ne pas montrer en mode transcription
        }
        print(json.dumps(output))
        sys.exit(0)

# Pour les autres cas, laisser le flux de permission normal procéder
sys.exit(0)

​

Travailler avec les outils MCP

​

Nommage des outils MCP

• mcp__memory__create_entities - Outil create entities du serveur Memory
• mcp__filesystem__read_file - Outil read file du serveur Filesystem
• mcp__github__search_repositories - Outil search du serveur GitHub

​

Configuration des hooks pour les outils MCP

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

​

Exemples

​

Considérations de sécurité

​

Avertissement

• Vous êtes seul responsable des commandes que vous configurez
• Les hooks peuvent modifier, supprimer ou accéder à tous les fichiers auxquels votre compte utilisateur peut accéder
• Les hooks malveillants ou mal écrits peuvent causer une perte de données ou des dommages au système
• Anthropic ne fournit aucune garantie et n’assume aucune responsabilité pour les dommages résultant de l’utilisation des hooks
• Vous devez tester minutieusement les hooks dans un environnement sûr avant l’utilisation en production

​

Meilleures pratiques de sécurité

1. Valider et nettoyer les entrées - Ne faites jamais confiance aux données d’entrée aveuglément
2. Toujours citer les variables shell - Utilisez "$VAR" et non $VAR
3. Bloquer la traversée de répertoires - Vérifiez la présence de .. dans les chemins de fichier
4. Utiliser des chemins absolus - Spécifiez les chemins complets pour les scripts (utilisez “$CLAUDE_PROJECT_DIR” pour le chemin du projet)
5. Ignorer les fichiers sensibles - Évitez .env, .git/, les clés, etc.

​

Sécurité de la configuration

1. Capture un instantané des hooks au démarrage
2. Utilise cet instantané tout au long de la session
3. Avertit si les hooks sont modifiés de manière externe
4. Nécessite un examen dans le menu /hooks pour que les modifications s’appliquent

​

Détails d’exécution des hooks

• Timeout : Limite d’exécution de 60 secondes par défaut, configurable par commande.
  • Un timeout pour une commande individuelle n’affecte pas les autres commandes.
• Parallélisation : Tous les hooks correspondants s’exécutent en parallèle
• Déduplication : Les commandes de hook identiques multiples sont automatiquement dédupliquées
• Environnement : S’exécute dans le répertoire courant avec l’environnement de Claude Code
  • La variable d’environnement CLAUDE_PROJECT_DIR est disponible et contient le chemin absolu vers le répertoire racine du projet (où Claude Code a été lancé)
  • La variable d’environnement CLAUDE_CODE_REMOTE indique si le hook s’exécute dans un environnement distant (web) ("true") ou un environnement CLI local (non défini ou vide). Utilisez ceci pour exécuter une logique différente en fonction du contexte d’exécution.
• Entrée : JSON via stdin
• Sortie :
  • PreToolUse/PostToolUse/Stop/SubagentStop : Progression affichée en transcription (Ctrl-R)
  • Notification/SessionEnd : Enregistré au débogage uniquement (--debug)
  • UserPromptSubmit/SessionStart : stdout ajouté comme contexte pour Claude

​

Débogage

​

Dépannage de base

1. Vérifier la configuration - Exécutez /hooks pour voir si votre hook est enregistré
2. Vérifier la syntaxe - Assurez-vous que votre JSON de paramètres est valide
3. Tester les commandes - Exécutez d’abord les commandes de hook manuellement
4. Vérifier les permissions - Assurez-vous que les scripts sont exécutables
5. Consulter les journaux - Utilisez claude --debug pour voir les détails d’exécution des hooks

• Guillemets non échappés - Utilisez \" dans les chaînes JSON
• Matcher incorrect - Vérifiez que les noms d’outils correspondent exactement (sensible à la casse)
• Commande non trouvée - Utilisez les chemins complets pour les scripts

​

Débogage avancé

1. Inspecter l’exécution du hook - Utilisez claude --debug pour voir l’exécution détaillée du hook
2. Valider les schémas JSON - Testez l’entrée/sortie du hook avec des outils externes
3. Vérifier les variables d’environnement - Vérifiez que l’environnement de Claude Code est correct
4. Tester les cas limites - Essayez les hooks avec des chemins de fichier ou des entrées inhabituels
5. Surveiller les ressources système - Vérifiez l’épuisement des ressources pendant l’exécution du hook
6. Utiliser la journalisation structurée - Implémentez la journalisation dans vos scripts de hook

​

Exemple de sortie de débogage

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

• Quel hook s’exécute
• Commande en cours d’exécution
• Statut de succès/échec
• Messages de sortie ou d’erreur