Hooks de Claude Code

Les hooks de Claude Code sont descommandes Shell définies par l'utilisateurqui s'exécutent automatiquement à des points spécifiques du cycle de vie de Claude Code.

Avec les hooks, vous pouvez obtenir un contrôle précis sur le comportement de Claude Code, en garantissant que certaines opérations (telles que le formatage du code, la journalisation)sont absolument déclenchées, plutôt que de compter sur le grand modèle pour décider de manière autonome s'il doit les exécuter.

Scénarios d'application typiques des hooks

Les hooks peuvent vous aider à implémenter de nombreuses fonctionnalités pratiques. Les scénarios courants incluent :

  • Notification par message: Envoyer automatiquement des rappels sur le bureau/par e-mail lorsque Claude Code attend une entrée ou a besoin d'autorisations
  • Formatage automatique: Après modification.tsfichiers, exécution automatiqueprettier, après modification.gofichiers, exécutergofmt
  • Journaux d'opérations: Enregistrer toutes les commandes exécutées par Claude à des fins d'audit de conformité ou de débogage/dépannage
  • Validation des normes de code: Si le code généré par Claude ne respecte pas les normes du projet (telles que les règles de nommage), fournir automatiquement un retour
  • Contrôle des permissions de fichiers: Empêcher Claude de modifier les fichiers de configuration de l'environnement de production ou les répertoires sensibles (tels que.env、.git)

Par rapport à la contrainte du comportement de Claude via des prompts, les hooks sontdes règles strictes au niveau de l'applicationqui sont appliquées de force dès que l'événement correspondant est déclenché, offrant une stabilité et une fiabilité supérieures.

Rappel important de sécurité

Lorsque les hooks s'exécutent, ilsutilisent directement les identifiants de l'environnement système actuel(tels que les variables d'environnement, les permissions utilisateur), ce qui présente certains risques de sécurité :

  • Le code de hook malveillant peut divulguer vos données sensibles (telles que les clés API, le code source du projet)
  • Des commandes de hook incorrectes peuvent entraîner une suppression accidentelle de fichiers ou des anomalies système

Actions de sécurité requises:

  1. Avant d'enregistrer des hooks, assurez-vous de vérifier la logique et les autorisations des commandes ligne par ligne
  2. Évitez d'exécuter des scripts d'origine inconnue dans les hooks
  3. Pour les meilleures pratiques de sécurité détaillées, reportez-vous auxPrécautions de sécurité de la documentation officielle

Description du type d'événement de hook

Claude Code dispose de plusieurs événements de cycle de vie intégrés. Vous pouvez lier des commandes de hook à différents événements. Chaque événement transmet des données de contexte différentes et affecte le comportement de Claude de différentes manières.

Nom de l'événement Moment du déclenchement Fonction principale
PreToolUse Appel d'outilAvant Peut intercepter l'exécution d'outils (par exemple, empêcher la modification de fichiers sensibles) et fournir des suggestions de retour à Claude
PermissionRequest Lorsqu'une boîte de dialogue de demande d'autorisation apparaît Approuver ou refuser automatiquement les demandes d'autorisation
PostToolUse Appel d'outilAprès achèvement Effectuer des post-opérations (p. ex., formater le code, journaliser les enregistrements)
UserPromptSubmit Après que l'utilisateur a soumis un prompt, avant que Claude ne le traite Prétraiter l'entrée utilisateur (p. ex., compléter les informations de contexte)
Notification Lorsque Claude envoie des notifications Personnaliser les méthodes de notification (p. ex., pop-ups de bureau, alertes SMS)
Stop Lorsque Claude termine une réponse Effectuer le travail de finition (p. ex., nettoyer les fichiers temporaires)
SubagentStop Lorsqu'une tâche d'un sous-agent se termine Traiter les résultats d'exécution du sous-agent
PreCompact Lorsqu'il est sur le point d'effectuer un compactage du contexte Personnaliser les règles de compactage
SessionStart Lors du démarrage d'une nouvelle session ou de la reprise d'une ancienne session Initialiser l'environnement de session (par ex., charger la configuration du projet)
SessionEnd Lorsque la session se termine Enregistrer les données de session, nettoyer l'environnement

Démarrage rapide : implémenter la journalisation des commandes

Ci-dessous, en utilisantl'enregistrement de toutes les commandes Bash exécutées par Claudecomme exemple, nous allons vous guider pas à pas dans la configuration et l'utilisation des hooks.

Prérequis

Installerjqoutil (pour analyser les données JSON depuis la ligne de commande) :

Étape 1 : Ouvrir l'interface de configuration des hooks

Dans l'interface interactive de Claude Code, saisissez la commande slash/hooks, appuyez sur Entrée, puis sélectionnez l'événement à associer — ici nous choisissonsPreToolUse(déclenché avant les appels d'outils, adapté pour journaliser les commandes).

Étape 2 : Ajouter un matcher d'événement

Le rôle du matcher est delimiter les conditions de déclenchement du hook, en n'exécutant la commande du hook que lorsque l'outil spécifié est appelé.

  1. Sélection+ Add new matcher…
  2. Saisissez un mot-clé correspondantBash, ce qui signifie que le hook ne se déclenche que lorsque Claude appelle l'outil Bash.

    Astuce : Saisissez*peut correspondre àtous les outils, ce qui active un hook global.

Étape 3 : Ajouter une commande de hook

Sélection+ Add new hook…, saisissez la commande suivante (fonction : extraire le contenu et la description de la commande, écrire dans un fichier journal) :

jq -r '"\(.tool_input.command) - \(.tool_input.description // "无描述信息")"' >> ~/.claude/bash-command-log.txt

Description de la commande :

  • jq -r ...: Extraire la commande depuis JSON (command) et la description (description), afficher "aucune information de description" lorsqu'il n'y a pas de description.
  • >> ~/.claude/...: Ajouter le contenu au fichier journal dans le répertoire personnel de l'utilisateur.

Étape 4 : Choisir l'emplacement de stockage de la configuration

L'emplacement de sauvegarde de la configuration détermine la portée du hook :

  • Paramètres utilisateur: Enregistrer dans la configuration au niveau utilisateur (~/.claude/settings.json),valable pour tous les projets
  • Paramètres du projet: Enregistrer dans la configuration du projet actuel (.claude/settings.local.json),valable uniquement pour le projet actuel

Ici, nous choisissonsUser settings, pour activer la journalisation globale des commandes. Après avoir sélectionné, appuyez sur laEscpour quitter l'interface de configuration, et le hook est enregistré.

Étape 5 : Vérifier la configuration du hook

  1. Saisissez à nouveau/hookscommande pour afficher la liste des hooks configurés
  2. ou ouvrez directement le fichier de configuration~/.claude/settings.json, et vous verrez la configuration suivante :
    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"无描述信息\")\"' >> ~/.claude/bash-command-log.txt"
              }
            ]
          }
        ]
      }
    }

Étape 6 : Tester l'effet du hook

  1. Saisissez une commande dans Claude Code :帮我执行 ls 命令
  2. Après l'exécution, consultez le fichier journal dans le terminal :
    cat ~/.claude/bash-command-log.txt
  3. Si le contenu suivant apparaît dans le journal, le hook est configuré avec succès :
    ls - Lists files and directories

Exemples pratiques de hooks

Voici plusieurs configurations de hooks couramment utilisées. Vous pouvez les copier directement ou les modifier selon vos besoins.

📌 Pour obtenir l'exemple de code complet, consultez le dépôt officiel :exemple de validateur de commandes bash

Exemple 1 : Formater automatiquement les fichiers TypeScript

Fonction : Après édition/écriture.tsde fichiers, utiliser automatiquementprettierpour formater le code

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write", // 匹配“编辑”和“写入”工具
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Exemple 2 : corriger automatiquement le formatage des fichiers Markdown

Fonction : ajouter automatiquement des balises de langage aux blocs de code qui n'en ont pas et supprimer les lignes vides superflues

Étape 1 : ajouter la configuration du hook

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
          }
        ]
      }
    ]
  }
}

Deuxième étape : créer le script de formatage

Dans le répertoire du projet, créez un nouveau fichier.claude/hooks/markdown_formatter.py, puis collez le code suivant :

Exemples

#!/usr/bin/env python3
"""
Outil de formatage Markdown : ajouter automatiquement des balises de langage aux blocs de code, nettoyer les lignes vides superflues
"""

import json
import sys
import re
import os

def detect_language(code):
    """Détecter automatiquement le langage de programmation en fonction du contenu du code"""
    code = code.strip()
    # Détecter JSON
    if re.search(r'^\s*[{\[]', code):
        try:
            json.loads(code)
            return 'json'
        except:
            pass
    # Détecter Python
    if re.search(r'^\s*def\s+\w+\s*\(', code, re.M) or re.search(r'^\s*(import|from)\s+\w+', code, re.M):
        return 'python'
    # Détecter JavaScript/TypeScript
    if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', code) or re.search(r'=>|console\.(log|error)', code):
        return 'javascript'
    # Détecter Bash
    if re.search(r'^#!.*\b(bash|sh)\b', code, re.M) or re.search(r'\b(if|then|fi|for|in|do|done)\b', code):
        return 'bash'
    # Format de texte par défaut
    return 'text'

def format_markdown(content):
    """Formate le contenu Markdown"""
    # Ajouter un langage aux blocs de code non étiquetés
    fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
    def add_lang(match):
        indent, info, body, closing = match.groups()
        if not info.strip():
            lang = detect_language(body)
            return f"{indent}```{lang}\n{body}{closing}\n"
        return match.group(0)
    content = re.sub(fence_pattern, add_lang, content)
    # Nettoyer les lignes vides supplémentaires (uniquement le contenu en dehors des blocs de code)
    content = re.sub(r'\n{3,}', '\n\n', content)
    return content.rstrip() + '\n'

if __name__ == "__main__":
    try:
        # Lire les données JSON transmises par Claude
        input_data = json.load(sys.stdin)
        file_path = input_data.get('tool_input', {}).get('file_path', '')
        # Traiter uniquement les fichiers .md/.mdx
        if not file_path.endswith(('.md', '.mdx')):
            sys.exit(0)
        # Lire et formater le fichier
        if os.path.exists(file_path):
            with open(file_path, 'r', encoding='utf-8') as f:
                content = f.read()
            formatted_content = format_markdown(content)
            # Écrire uniquement lorsque le contenu change
            if formatted_content != content:
                with open(file_path, 'w', encoding='utf-8') as f:
                    f.write(formatted_content)
                print(f"Fichier Markdown formaté : {file_path}")
    except Exception as e:
        print(f"Échec du formatage : {e}", file=sys.stderr)
        sys.exit(1)

Troisième étape : Accorder la permission d'exécution au script

chmod +x .claude/hooks/markdown_formatter.py

Exemple 3 : Envoyer des notifications de bureau lorsque Claude attend une entrée

Fonctionnalité : Lorsque Claude a besoin d'une saisie utilisateur, afficher automatiquement un rappel de bureau (fonctionne sous Linux/macOS)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "", // 匹配所有通知事件
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code 提示' '请你输入指令或确认权限'"
          }
        ]
      }
    ]
  }
}

Exemple 4 : Empêcher la modification de fichiers sensibles

Fonctionnalité : Empêcher Claude de modifier.env、package-lock.jsonet d'autres fichiers sensibles

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

Remarque : Lorsque le script renvoie un code de statut2, Claude Code interceptera cet appel d'outil, empêchant ainsi la modification de fichier.


Manuel de référence des hooks de Claude Code

Chemin du fichier de configuration

Niveau de configuration Chemin du fichier Portée
Niveau utilisateur ~/.claude/settings.json Tous les projets
Niveau projet .claude/settings.json Projet actuel
Niveau projet local (non commité) .claude/settings.local.json Projet actuel, non inclus dans le contrôle de version
Niveau de politique gérée Chemin spécifié par l'administrateur Contrôle unifié entreprise/équipe

Structure de configuration principale

Les hooks sont organisés parévénement + matcher, prenant en chargecommand(exécuter des commandes Shell) etprompt(appeler le LLM pour les décisions), deux types.

{
  "hooks": {
    "【钩子事件名】": [
      {
        "matcher": "【工具匹配规则】", // 部分事件可省略
        "hooks": [
          {
            "type": "command/prompt",
            "command": "【Shell 命令】", // type=command 时必填
            "prompt": "【LLM 提示词】",  // type=prompt 时必填
            "timeout": 30 // 可选,超时时间(秒)
          }
        ]
      }
    ]
  }
}

Règles de correspondance (applicables uniquement aux événements d’outils)

Règle de correspondance Exemple Description
Correspondance exacte Write Correspond uniquement àWritetool
Correspondance multi-outils Edit | Write CorrespondanceEditouWritetools
Correspondance de préfixe Notebook.* Correspond à tous les outils commençant parNotebookle préfixe
Correspondance complète */ chaîne vide Correspondre à tous les outils

Conseils de configuration spéciaux

Scénario Méthode de configuration Exemple
Référencer un script dans le projet Utiliser des variables d'environnement$CLAUDE_PROJECT_DIR "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
Hooks de plugin Configuré à l'intérieur du pluginhooks/hooks.json, en utilisant${CLAUDE_PLUGIN_ROOT}pour référencer des fichiers de plugin "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
Hooks au niveau du composant (Skill/Agent) Défini dans le frontmatter du composant, portée limitée au cycle de vie du composant Voir ci-dessousConfiguration de l'extensionTableau

Configuration étendue (Skill/Agent/Commandes slash)

La configuration d'extension permet d'intégrer directement des Hooks dans la définition d'un Skill, d'un Agent ou d'une commande slash personnalisée. Ces Hooks ne prennent effet que lorsque le composant correspondant est activé et en cours d'exécution, et sont automatiquement nettoyés après la fin de l'exécution du composant, sans affecter la session globale.

Événements de hook pris en charge

Prend uniquement en chargePreToolUse、PostToolUse、Stoptrois types d'événements, avec les mêmes fonctionnalités que les Hooks globaux, mais la portée est limitée au cycle de vie du Skill ou de la commande slash en cours.

Option de configuration exclusive

  • once: true(facultatif) : lorsqu'elle est définie surtrue, ce Hook ne s'exécute qu'une seule fois dans toute la session, et est automatiquement supprimé après la première exécution réussie afin d'éviter un déclenchement répété.

Exemple complet de configuration

---
# Skill/斜杠命令的基础信息
name: secure-operations
description: 执行Shell命令前先做安全校验的工具
# Hooks 配置段
hooks:
  PreToolUse:
    # 匹配器:仅拦截Bash工具调用
    - matcher: "Bash"
      hooks:
        - type: "command"
          # 要执行的安全校验脚本
          command: "./scripts/security-check.sh"
          # 会话内仅执行一次
          once: true
          # 超时时间(秒),避免脚本卡死
          timeout: 15
---

Configuration des Hooks dans l'Agent

Événements de hook pris en charge

Prend également uniquement en chargePreToolUse、PostToolUse、StopTrois types d'événements, limités uniquement au cycle de vie d'exécution des tâches de ce sous-Agent.

Éléments de configuration spécifiques

Aucun élément de configuration exclusif supplémentaire, non pris en chargeonce: true(Les Hooks sont déclenchés chaque fois que l'Agent exécute une tâche).

Exemple complet de configuration

---
# Agent 的基础信息
name: code-reviewer
description: 自动审查代码修改并运行代码检查的子代理
# Hooks 配置段
hooks:
  PostToolUse:
    # 匹配器:拦截Edit(编辑)或Write(写入)工具
    - matcher: "Edit|Write"
      hooks:
        - type: "command"
          # 代码检查脚本,执行lint校验
          command: "./scripts/run-linter.sh"
          # 超时时间(秒)
          timeout: 30
---

Notes :

  1. Les règles de correspondance pour les Hooks au niveau des composants sont exactement les mêmes que pour les Hooks globaux : la correspondance exacte est prise en charge (par ex.,"Write"), la correspondance multi-outils (par ex.,"Edit|Write"), la correspondance avec caractères génériques ("*"), et la correspondance est sensible à la casse ;
  2. Les Hooks au niveau des composants et les Hooks globaux s'exécutent en parallèle : si des Hooks globaux et des Hooks au niveau des composants sont configurés pour le même événement, les deux types de Hooks s'exécuteront ensemble lorsqu'ils sont déclenchés, sans entrer en conflit l'un avec l'autre ;
  3. Exigences de format de configuration : les Hooks au niveau des composants doivent être écrits dans le frontmatter (---région délimitée), en respectant la syntaxe YAML ; les erreurs d'indentation invalideront la configuration ;
  4. Recommandations pour les chemins de scripts : privilégier les chemins relatifs (par ex.,./scripts/xxx.sh), ou utilisez le$CLAUDE_PROJECT_DIRvariable d’environnement pour spécifier un chemin absolu, garantissant que le composant peut trouver le script dans n’importe quel répertoire.

Événements de hook -- Événements d’outil (Matcher pris en charge)

Nom de l'événement Moment du déclenchement Matchers courants Objectif principal
PreToolUse Appel d’outilavant Bash/Edit/Write/Read Intercepter l’exécution de l’outil, modifier les paramètres d’entrée, approuver/refuser automatiquement les permissions
PermissionRequest Lorsqu'une boîte de dialogue de demande d'autorisation apparaît identiquePreToolUse Gérer automatiquement les demandes de permission sans confirmation manuelle de l’utilisateur
PostToolUse Appel d’outilAprès succès identiquePreToolUse Exécuter des opérations postérieures (par ex., formatage du code, journalisation)
Notification Lorsque Claude envoie une notification permission_prompt/idle_prompt/auth_success Personnaliser les méthodes de notification (par ex., popups de bureau, alertes e-mail)
PreCompact Avant d'effectuer la compression du contexte manual(Déclenchement manuel) /auto(Déclenchement automatique) Personnaliser les règles de compression, sauvegarder le contexte important

Événements de hook -- Événements de session/tâche (Sans Matcher)

Nom de l'événement Moment du déclenchement Objectif principal
UserPromptSubmit Après que l'utilisateur a soumis un prompt, avant que Claude ne le traite Valider la légitimité de l'invite, compléter les informations de contexte
Stop Lorsque l'Agent principal termine sa réponse (non déclenché par une interruption de l'utilisateur) Déterminer intelligemment s'il faut continuer à exécuter la tâche
SubagentStop Lorsque la tâche du sous-Agent se termine Évaluer les résultats de la sous-tâche, décider s'il faut terminer
SessionStart Lors du démarrage/de la reprise d'une session Initialiser l'environnement, charger la configuration du projet, définir les variables d'environnement persistantes
SessionEnd Lorsque la session se termine Nettoyer les fichiers temporaires, enregistrer les journaux de session, sauvegarder l'état de travail

Comparaison des types de hooks

Claude Code prend en charge deux types de hooks pour répondre aux besoins de différents scénarios.

Fonctionnalité commandType (hook de commande) promptType (hook de prompt)
Méthode d'exécution Exécuter des commandes/scripts Shell Appeler LLM (modèle Haiku par défaut) pour une prise de décision intelligente
Logique de décision Basé sur la logique du code,jugement déterministe Basé sur le contexte,jugement sémantique flexible
Difficulté de configuration Nécessite d'écrire des scripts, barrière d'entrée élevée Il suffit d'écrire des prompts, simple et facile à utiliser
Vitesse de réponse Rapide (exécution locale) Plus lent (nécessite des appels API)
Scénarios applicables Règles fixes telles que le formatage du code, la journalisation, l'interception des permissions Scénarios flexibles tels que l'évaluation de l'achèvement des tâches, le jugement d'intentions complexes
Configuration principale command + timeout prompt + timeout(Peut référencer$ARGUMENTSespaces réservés)

Entrée et sortie -- Entrée de hook (JSON transmis via stdin)

Tous les hooks reçoivent des champs communs, et certains événements incluent des champs spécifiques.

Type de champ Champ commun Description
Informations de base session_id Identifiant unique de session
transcript_path Chemin du fichier d'historique de conversation
cwd Répertoire de travail actuel lors de l'exécution du hook
permission_mode Mode d'autorisation actuel (default/plan/acceptEdits, etc.)
hook_event_name Nom de l'événement de hook actuellement déclenché

Exemples de champs spécifiques à chaque événement

Nom de l'événement Champs spécifiques Exemple
PreToolUse tool_name/tool_input {"tool_name":"Write","tool_input":{"file_path":"/test.txt"}}
UserPromptSubmit prompt {"prompt":"帮我写一个排序函数"}
SessionEnd reason {"reason":"clear/logout/other"}

Sortie du hook (deux méthodes)

Méthode 1 : code de sortie (scénarios simples)

Transmettre l'état d'exécution via le code de sortie,stdout/stderrUtilisé pour fournir des informations de retour.

Code de sortie Signification Description du comportement
0 Exécution réussie stdoutPeut renvoyer du JSON pour un contrôle avancé ; certains événements (par ex.,UserPromptSubmit) ajouterontstdoutau contexte
2 Bloquer l'opération Utiliser uniquementstderrcomme message d'erreur renvoyé à Claude,empêchant l'événement actuel de continuer son exécution
Autres valeurs non nulles Erreur non bloquante stderrAffiché uniquement en mode verbeux (ctrl+o), n'affecte pas l'exécution de l'événement

Comportement du code de sortie 2 dans chaque événement

Nom de l'événement Comportement déclenché
PreToolUse Bloquer l'appel d'outil et l'afficher à Claudestderr
UserPromptSubmit Bloquer le traitement de l'invite, effacer la saisie utilisateur
Stop Empêcher Claude de s'arrêter, forcer la poursuite du travail
PostToolUse/Notification Afficher uniquementstderr, n'affecte pas les opérations terminées

Méthode 2 : sortie JSON (scénarios avancés)

Lorsque le code de sortie est0, vous pouvezstdoutrenvoyer du JSON pour obtenir un contrôle précis. Les champs principaux sont les suivants :

Champs JSON courants Objectif
continue: true/false S'il faut autoriser l'événement à continuer à s'exécuter (falsea priorité sur les autres règles)
stopReason continue=falseRaison affichée à l'utilisateur lorsque
systemMessage Message d'avertissement affiché à l'utilisateur

Exemples de champs JSON spécifiques à l'événement

Nom de l'événement Champs spécifiques Exemple
PreToolUse permissionDecision(allow/deny/ask) {"hookSpecificOutput":{"permissionDecision":"allow","updatedInput":{"file_path":"/new.txt"}}}
UserPromptSubmit decision: block/undefined {"decision":"block","reason":"提示包含敏感信息"}
PostToolUse additionalContext {"hookSpecificOutput":{"additionalContext":"文件已格式化完成"}}

Configuration des Hooks pour les outils MCP

Les outils MCP peuvent être intégrés de manière transparente aux Hooks et mis en correspondance via des règles de nommage spécifiques.

Règles de nommage des outils MCP

mcp__<服务器名>__<工具名>

Exemple :mcp__github__search_repositories、mcp__filesystem__read_file

Exemples de correspondance

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*", // 匹配 memory 服务器的所有工具
        "hooks": [{"type": "command", "command": "echo '内存操作日志' >> log.txt"}]
      },
      {
        "matcher": "mcp__.*__write.*", // 匹配所有服务器的写操作工具
        "hooks": [{"type": "command", "command": "./validate-write.py"}]
      }
    ]
  }
}

Sécurité et débogage

Bonnes pratiques de sécurité

Points clés de sécurité Actions concrètes
Validation des entrées Valider strictementtool_inputles chemins de fichiers et les paramètres de commande dans, pour prévenir la traversée de chemin (par ex.,../)
références de variables Utilisation dans les commandes Shell"$VAR"au lieu de$VAR, pour éviter l’injection de paramètres
Moindre privilège Les scripts de hook ne doivent se voir accorder que les permissions nécessaires ; évitez d’utilisersudoet d’autres commandes à haut risque
Exclure les fichiers sensibles Intercepter les opérations sur.env、.gitet les opérations sur les fichiers clés
Examen des commandes Avant d'enregistrer un hook, exécutez manuellement la commande pour vérifier la logique et confirmer l'absence de comportement malveillant.

Conseils de débogage

Type de problème Étapes de dépannage
Le hook ne prend pas effet 1. Exécutez/hookscommande pour vérifier si la configuration est enregistrée<br>2. Vérifiez que la syntaxe JSON est correcte<br>3. Vérifiez si la règle du matcher correspond au nom de l'outil (sensible à la casse)
Échec de l'exécution de la commande 1. Exécutez manuellement la commande du hook pour confirmer qu'elle s'exécute correctement<br>2. Vérifiez si le script dispose des permissions d'exécution (chmod +x script.sh)<br>3. Utilisez un chemin absolu pour appeler le script afin d'éviter les problèmes de variables d'environnement
Afficher les journaux détaillés Ajouter lors du démarrage de Claude Code--debugparamètre pour afficher l'intégralité du processus d'exécution du hook

Documentation de référence : pour obtenir une description complète de la fonctionnalité hook, reportez-vous à la documentation de référence officielleHooks。

Autres extensions