Référence des hooks

​

Cycle de vie des hooks

• une fois par session : SessionStart et SessionEnd
• une fois par tour : UserPromptSubmit, Stop et StopFailure
• à chaque appel d’outil à l’intérieur de la boucle agentique : PreToolUse et PostToolUse, sauf les appels EndConversation, qui ignorent les deux

​

Comment un hook se résout

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # no decision; normal permission flow applies
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          }
        ]
      }
    ]
  }
}

# .claude/hooks/block-rm.ps1
$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
$command = $callInput.tool_input.command

if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Destructive command blocked by hook"
    }
  } | ConvertTo-Json
} else {
  exit 0  # no decision; normal permission flow applies
}

{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

​

Configuration

1. Choisissez un événement de hook auquel répondre, comme PreToolUse ou Stop
2. Ajoutez un groupe de matcher pour filtrer quand il se déclenche, comme « uniquement pour l’outil Bash »
3. Définissez un ou plusieurs gestionnaires de hook à exécuter lorsqu’il y a correspondance

​

Emplacements des hooks

• Vos hooks utilisateur, projet, local et plugin sont bloqués. Les hooks des plugins forcément activés dans les paramètres gérés enabledPlugins sont exempts
• Claude Code restreint également votre statusLine, fileSuggestion et subagentStatusLine aux paramètres gérés
• Claude Code désactive également les plugins avec une source command, y compris les plugins forcément activés dans les paramètres gérés enabledPlugins, sauf si disableCommandPluginSources est explicitement défini à false. Les sources command nécessitent Claude Code v2.1.229 ou ultérieur
• Claude Code bloque également les commandes headersHelper du marketplace sauf si disableCommandPluginSources est explicitement défini à false, sauf pour un marketplace que les paramètres gérés eux-mêmes déclarent

• allowedHttpHookUrls : lorsqu’il est défini à n’importe quel niveau de paramètres, Claude Code exécute un gestionnaire de hook HTTP uniquement si son URL correspond à la liste blanche fusionnée
• httpHookAllowedEnvVars : lorsqu’il est défini, Claude Code n’interpose que les variables d’environnement de cette liste dans les en-têtes de hook

​

Modèles de matcher

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

​

Correspondre aux outils MCP

• mcp__memory__create_entities : outil de création d’entités du serveur Memory
• mcp__filesystem__read_file : outil de lecture de fichier du serveur Filesystem
• mcp__github__search_repositories : outil de recherche du serveur GitHub

• mcp__memory__.* correspond à tous les outils du serveur memory
• mcp__brave-search__.* correspond à tous les outils d’un serveur dont le nom contient un trait d’union
• mcp__.*__write.* correspond à tout outil dont le nom commence par write de n’importe quel serveur

{
  "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"
          }
        ]
      }
    ]
  }
}

​

Champs du gestionnaire de hook

• Hooks de commande (type: "command") : exécutent une commande shell. Votre script reçoit l’entrée JSON de l’événement sur stdin et communique les résultats via les codes de sortie et stdout.
• Hooks HTTP (type: "http") : envoient l’entrée JSON de l’événement en tant que requête HTTP POST à une URL. Le point de terminaison communique les résultats via le corps de la réponse en utilisant le même format de sortie JSON que les hooks de commande.
• Hooks de l’outil MCP (type: "mcp_tool") : appellent un outil sur un serveur MCP configuré. La sortie textuelle de l’outil est traitée comme stdout d’un hook de commande.
• Hooks de prompt (type: "prompt") : envoient un prompt à un modèle Claude pour une évaluation en un seul tour. Le modèle retourne sa décision en JSON. Consultez Hooks basés sur des prompts.
• Hooks d’agent (type: "agent") : lancent un subagent qui peut utiliser des outils comme Read, Grep et Glob pour vérifier les conditions avant de retourner une décision. Les hooks d’agent sont expérimentaux et peuvent changer. Consultez Hooks basés sur des agents.

​

Champs communs

​

Champs des hooks de commande

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
}

{
  "type": "command",
  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
}

​

Champs des hooks HTTP

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Champs des hooks de l’outil MCP

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": { "file_path": "${tool_input.file_path}" }
          }
        ]
      }
    ]
  }
}

​

Champs des hooks de prompt et d’agent

​

Référencer les scripts par chemin

• ${CLAUDE_PROJECT_DIR} : la racine du projet où la session a démarré. Claude Code définit également cette variable dans l’environnement des serveurs MCP stdio et des serveurs LSP de plugin.
• ${CLAUDE_PLUGIN_ROOT} : le répertoire d’installation du plugin, pour les scripts fournis avec un plugin. Consultez variables d’environnement du plugin pour savoir comment le chemin se comporte lors des mises à jour.
• ${CLAUDE_PLUGIN_DATA} : le répertoire de données persistantes du plugin, pour les dépendances et l’état qui doivent survivre aux mises à jour du plugin.

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

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

​

Hooks dans les skills et agents

• Hooks de subagent : Claude Code les exécute uniquement pendant que ce subagent s’exécute et les supprime lorsqu’il se termine. Claude Code convertit un hook Stop ici en SubagentStop, l’événement qu’il déclenche lorsqu’un subagent se termine.
• Hooks de skill : Claude Code les enregistre lorsque vous ou Claude invoquez le skill et continue à les exécuter pour le reste de la session, sur les tours après le tour du skill lui-même. Pour que Claude Code supprime un hook après sa première exécution réussie à la place, définissez once: true sur celui-ci.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

​

Le menu /hooks

​

Désactiver ou supprimer les hooks

​

Entrée et sortie des hooks

​

Champs d’entrée communs

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

​

Sortie du code de sortie

​

Exit code 0

• Commence par { et se termine par } : Claude Code l’analyse comme JSON. Lorsque la sortie est deux lignes ou plus qui s’analysent chacune comme JSON seules, et aucune ligne n’est un objet sortie JSON qui définit un champ, Claude Code traite la sortie entière comme du texte brut. Lorsque l’une de ces lignes définit un champ, la sortie entière est un échec d’analyse, décrit ci-dessous.
• Commence par { mais ne se termine pas par } : Claude Code le traite comme du texte brut.
• Commence par n’importe quoi d’autre : Claude Code le traite comme du texte brut, un tableau JSON ou une chaîne JSON entre guillemets incluse.

​

Exit code 2

#!/bin/bash
# Lit l'entrée JSON depuis stdin, vérifie la commande
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Erreur bloquante : l'appel d'outil est empêché
fi

exit 0  # Pas de décision : le flux de permission normal s'applique

​

Autres codes de sortie

• Avec un objet analysé qui passe la validation du schéma, pour les événements qui utilisent le modèle de décision standard, Claude Code ignore le code de sortie et le JSON seul décide du résultat :
  • Chaque champ que l’événement supporte est honoré, y compris permissionDecision, additionalContext, updatedInput et systemMessage, et le hook n’est pas signalé comme une erreur.
  • Contrôle de décision énumère les champs de décision par événement ; les champs universels comme systemMessage suivent le tableau Sortie JSON.
• Avec un objet analysé qui échoue la validation du schéma, pour les événements qui utilisent le modèle de décision standard, c’est la même erreur non-bloquante que sur exit 0 : l’action procède, et l’avis <hook name> hook error porte le message de validation.
• Avec stdout que Claude Code essaie d’analyser comme JSON et ne peut pas, Claude Code rapporte la même erreur non-bloquante que sur exit 0 pour les événements qui utilisent le modèle de décision standard. L’action procède, et l’avis porte le message d’analyse.
• Avec stdout que Claude Code traite comme du texte brut, ou avec stdout vide, c’est une erreur non-bloquante pour la plupart des événements de hook : l’action procède, et la transcription affiche un avis <hook name> hook error suivi de la première ligne de stderr, préfixée par Failed with non-blocking status code:. Pour capturer le stderr complet, activez la journalisation de débogage.

​

Délais d’expiration

• Un hook command, http ou mcp_tool expiré ne bloque pas l’appel d’outil. L’appel continue via le flux de permission normal, donc ne comptez pas sur un hook bloqué pour agir comme une porte.
• Un hook de rappel Agent SDK qui dépasse son délai d’expiration bloque l’appel d’outil.

​

Comportement du code de sortie 2 par événement

​

Gestion des réponses HTTP

• 2xx avec un corps vide : succès, équivalent à exit code 0 sans sortie
• 2xx avec un corps d’objet JSON : analysé en utilisant le même schéma sortie JSON que les hooks de commande. Un corps qui échoue la validation du schéma est une erreur non-bloquante
• 2xx avec n’importe quel autre corps, comme du texte brut : erreur non-bloquante, gérée de la même manière qu’un statut non-2xx. Claude Code n’ajoute pas le texte au contexte de Claude
• Statut non-2xx : erreur non-bloquante, l’exécution continue
• Défaillance de connexion : erreur non-bloquante, l’exécution continue
• Délai d’expiration : le hook est annulé, comme décrit sous Délais d’expiration

​

Sortie JSON

• Portée : Claude Code mesure chaque chaîne seule, même lorsque plusieurs hooks s’exécutent pour le même événement. Pour la sortie JSON, chaque champ est mesuré séparément ; stdout brut est mesuré dans son ensemble.
• Au-delà de la limite : Claude Code enregistre la sortie dans un fichier du répertoire de session et la remplace par le chemin du fichier et un aperçu de jusqu’à 2 000 premiers caractères. Un grand résultat Bash valide est géré de la même manière, décrit sous Output limits. Contrairement à ce plafond Bash, ce cap n’a pas de paramètre ou de variable d’environnement pour l’augmenter.
• Lecture du fichier : Claude Code ne demande pas à Claude de lire le fichier, donc gardez tout ce que Claude doit toujours voir dans le cap.

• Champs universels comme continue sont listés dans le tableau ci-dessous. Chaque événement les accepte, mais certains événements les rejettent ou livrent systemMessage ailleurs que dans la transcription. Chaque section d’événement le précise. terminalSequence fonctionne sur ces événements aussi, avec les exceptions listées sous Émettre des notifications de terminal.
• decision et reason au niveau supérieur sont utilisés par certains événements pour bloquer ou fournir des commentaires.
• hookSpecificOutput est un objet imbriqué pour les événements qui ont besoin d’un contrôle plus riche. Il nécessite un champ hookEventName défini au nom de l’événement.

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

​

Émettre des notifications de terminal

• OSC 0, 1, 2 : titres de fenêtre et d’icône
• OSC 9 : notifications iTerm2, ConEmu, Windows Terminal et WezTerm, y compris la progression de la barre des tâches 9;4
• OSC 99 : notifications Kitty
• OSC 777 : notifications urxvt, Ghostty et Warp
• BEL nu

• Claude Code écrit la séquence uniquement dans une session interactive, et uniquement tandis que son interface est à l’écran. En mode non-interactif avec le drapeau -p et dans l’Agent SDK, il ignore le champ.
• Un hook de commande WorktreeCreate ne peut pas retourner JSON, car Claude Code lit son stdout comme le chemin du worktree. Un hook HTTP WorktreeCreate retourne JSON et peut inclure le champ.

#!/bin/bash
# Hook de notification : ping le bureau lorsque Claude Code a besoin d'attention.
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

​

Ajouter du contexte pour Claude

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

• SessionStart et SubagentStart : au début de la conversation, avant le premier prompt
• UserPromptSubmit et UserPromptExpansion : aux côtés du prompt soumis
• PreToolUse, PostToolUse, PostToolUseFailure et PostToolBatch : à côté du résultat de l’outil
• Stop et SubagentStop : à la fin du tour. La conversation continue afin que Claude puisse agir sur les commentaires. Consultez Contrôle de décision Stop
• PostModelSwitch : avec la prochaine demande après le changement. Consultez Contrôle de décision PostModelSwitch pour le timing

• État de l’environnement : la branche actuelle, la cible de déploiement ou les drapeaux de fonctionnalité actifs
• Règles de projet conditionnelles : quelle commande de test s’applique au fichier qui vient d’être modifié, quels répertoires sont en lecture seule dans ce worktree
• Données externes : problèmes ouverts qui vous sont assignés, résultats CI récents, contenu récupéré à partir d’un service interne

​

Contrôle de décision

• PreToolUse : updatedInput directement sous hookSpecificOutput remplace les arguments d’un outil avant son exécution. Consultez Contrôle de décision PreToolUse
• PermissionRequest : updatedInput à l’intérieur de l’objet decision. Consultez Contrôle de décision PermissionRequest
• PostToolUse : updatedToolOutput remplace le résultat de l’outil. Consultez Contrôle de décision PostToolUse
• UserPromptSubmit : ne peut pas remplacer le prompt ; injecte uniquement additionalContext à côté de celui-ci

{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

​

Événements de hook

​

SessionStart

​

Entrée SessionStart

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "resume",
  "model": "claude-opus-5",
  "seconds_since_last_response": 5400,
  "context_tokens": 182340,
  "prompt_cache_likely_expired": true,
  "estimated_cache_write_usd": 1.1396
}

​

Contrôle de décision SessionStart

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
    "sessionTitle": "auth-refactor"
  }
}

#!/bin/bash

git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills

echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

​

Persister les variables d’environnement

#!/bin/bash

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

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
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

​

Setup

​

Entrée Setup

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Setup",
  "trigger": "init"
}

​

Contrôle de décision Setup

​

InstructionsLoaded

​

Entrée InstructionsLoaded

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/Users/my-project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

​

Contrôle de décision InstructionsLoaded

​

UserPromptSubmit

​

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"
}

​

Contrôle de décision UserPromptSubmit

• Sortie standard en texte brut : Claude Code ajoute la sortie standard qu’il traite comme du texte brut au contexte de Claude
• JSON avec additionalContext : utilisez le format JSON ci-dessous pour plus de contrôle. Le champ additionalContext est ajouté comme contexte

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title",
    "suppressOriginalPrompt": true
  }
}

​

Ce qu’une invite bloquée laisse derrière

​

UserPromptExpansion

​

Entrée UserPromptExpansion

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../00893aaf.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

​

Contrôle de décision UserPromptExpansion

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

​

MessageDisplay

• supprimer le markdown pour un affichage minimal
• transformer le texte qu’une application Agent SDK montre à ses utilisateurs
• masquer les clés API ou les noms d’hôtes internes des réponses de Claude

​

Entrée MessageDisplay

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "MessageDisplay",
  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
  "index": 0,
  "final": false,
  "delta": "Here is the plan:\n"
}

​

Sortie MessageDisplay

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
            ]
          }
        ]
      }
    ]
  }
}

$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
$text = $batch.delta -replace '\*\*', '' -replace '`', ''
@{
  hookSpecificOutput = @{
    hookEventName = "MessageDisplay"
    displayContent = $text
  }
} | ConvertTo-Json

​

PreToolUse

​

Entrée PreToolUse

• Claude Code développe ~ et les chemins relatifs avant que les hooks s’exécutent, donc un hook qui correspond à des chemins ne peut pas être contourné via ~ ou une orthographe relative du même chemin
• Sur Windows, le chemin arrive avec des séparateurs de barre oblique inverse, même quand votre hook s’exécute sous Git Bash où $PWD ressemble à /c/project
• Une comparaison écrite avec des barres obliques avant, comme une vérification /src/, ne correspond jamais à un chemin de barre oblique inverse, et l’appel d’outil procède comme si le hook n’avait rien à bloquer
• Normalisez les séparateurs avant de comparer : FILE_PATH="${FILE_PATH//\\//}" en Bash, ou file_path.replace("\\", "/") en Python, puis correspondez à un segment de chemin comme /src/ plutôt que d’ancrer avec ^, puisque le chemin est absolu

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "C:\\project\\src\\index.ts",
    "content": "..."
  },
  ...
}

• Sur Windows, partout où l’outil PowerShell est activé, Claude traite PowerShell comme le shell principal et achemine les commandes shell à travers lui.
• Sur Windows sans Git Bash, l’outil est activé automatiquement et Claude Code n’enregistre pas l’outil Bash du tout.
• Un hook qui correspond uniquement à Bash ne se déclenche jamais là.

​

Contrôle de décision PreToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

​

Différer un appel d’outil pour plus tard

1. Claude appelle AskUserQuestion. Le hook PreToolUse se déclenche.
2. Le hook retourne permissionDecision: "defer". L’outil ne s’exécute pas. Le processus quitte avec stop_reason: "tool_deferred" et l’appel d’outil en attente préservé dans la transcription.
3. Le processus appelant lit deferred_tool_use du résultat SDK, affiche la question dans sa propre interface utilisateur, et attend une réponse.
4. Le processus appelant exécute claude -p --resume <session-id> avec le même hôte de permission. Le même appel d’outil déclenche PreToolUse à nouveau.
5. Le hook retourne permissionDecision: "allow" avec la réponse dans updatedInput. L’outil s’exécute et Claude continue.

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

​

PermissionRequest

​

Entrée PermissionRequest

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

​

Contrôle de décision PermissionRequest

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

​

Entrées de mise à jour de permission

​

PostToolUse

• Pour exécuter un hook après que n’importe quel outil se termine avec succès, omettez le matcher ou définissez-le à "*". Votre hook peut alors découvrir ce qui a changé lui-même, par exemple en exécutant git status --porcelain, qui liste également les fichiers non suivis que git diff manque. Pour les appels d’outils qui échouent, ajoutez le même hook sous PostToolUseFailure.
• Pour exécuter un hook quand un fichier spécifique change sur le disque, peu importe ce qui l’a écrit, utilisez FileChanged. Claude Code n’exécute pas un hook PostToolUse correspondant à Edit|Write quand une commande Bash ou un processus en dehors de Claude Code réécrit le même fichier.

​

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",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

​

Contrôle de décision PostToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

​

Annoter un résultat pour le classificateur du mode auto

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

• Hooks configurés dans Claude Code : pour les hooks des fichiers de paramètres, plugins, skills, et frontmatter d’agent, le classificateur traite la note comme du contexte non vérifié fourni par l’application. La note n’établit jamais l’intention de l’utilisateur, et si elle prétend que vous avez approuvé ou demandé quelque chose, le classificateur vérifie cette affirmation contre vos propres messages dans la conversation
• Rappels Agent SDK en processus : quand une application intégrant Claude Code enregistre le hook comme un rappel SDK TypeScript et retourne la note pendant la session en direct, le classificateur peut peser une déclaration d’utilisateur relayée dans la note comme intention de l’utilisateur. Une telle déclaration peut satisfaire une exigence de consentement que le classificateur accepterait d’un message que vous envoyez, mais elle ne lève jamais un blocage que votre propre message ne pourrait pas lever non plus. Après qu’une session reprenne, Claude Code traite les notes restaurées comme du contexte non vérifié. Quand les hooks des deux groupes annotent le même appel, le classificateur traite la note combinée comme non vérifiée

• Longueur : Claude Code plafonne les notes pour un appel d’outil à 2 000 caractères et tronque le reste. Le plafond est partagé entre chaque hook qui répond à cet appel
• Réponses synchrones uniquement : Claude Code ignore le champ dans la réponse d’un hook qui s’exécute en arrière-plan, parce que cette réponse arrive après que Claude Code enregistre le résultat d’outil
• Appels que le classificateur n’enregistre pas : la transcription du classificateur omet les recherches en lecture seule comme les lectures de fichiers et les recherches. Claude Code rejette une note attachée à l’un de ces appels
• Interaction avec les réécritures : quand la note décrit la sortie que vous remplacez avec updatedToolOutput, retournez les deux champs dans la même réponse de hook. Claude Code rejette la note si cette réécriture est rejetée ou qu’une réécriture d’un autre hook la remplace. Claude Code livre une note que vous retournez sans réécriture même quand un autre hook réécrit la sortie

​

PostToolUseFailure

​

Entrée PostToolUseFailure

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

• Pour Bash et PowerShell, une commande qui s’est exécutée et a quitté produit une première ligne Exit code N, puis toute sortie que la commande a produite comme un bloc avec stdout et stderr entrelacés
• Une charge utile peut également porter un message d’échec nu sans ligne de code de sortie, quand Claude Code n’a pas pu démarrer le processus shell lui-même
• Claude Code tronque au milieu les longues chaînes autour d’un marqueur ... [N characters truncated] ..., et peut insérer ses propres lignes, comme Command timed out after 2m 0s

​

Contrôle de décision PostToolUseFailure

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

​

PostToolBatch

​

Entrée PostToolBatch