En mode non-interactif avec le drapeau -p, Claude Code offre AskUserQuestion et ExitPlanMode uniquement quand l'exécution a un hôte de permission pour recevoir l'invite, comme un rappel canUseTool d'Agent SDK. Ces outils nécessitent l'interaction de l'utilisateur. Retourner permissionDecision: "allow" avec updatedInput satisfait cette exigence : le hook lit l'entrée de l'outil depuis stdin, collecte la réponse via votre propre interface utilisateur, et la retourne dans updatedInput pour que l'outil s'exécute sans inviter. Retourner "allow" seul n'est pas suffisant pour ces outils. Pour AskUserQuestion, renvoyez le tableau questions original et ajoutez un objet answers mappant le texte de chaque question à la réponse choisie.

À partir de v2.1.199, un outil MCP dont le serveur le marque avec _meta["anthropic/requiresUserInteraction"] est plus strict : un hook ne peut pas ignorer son invite d'approbation avec "allow", avec ou sans updatedInput, parce que Claude Code ne peut pas confirmer que le hook a collecté l'interaction que l'outil a besoin.

Différer un appel d'outil pour plus tard

"defer" est pour les intégrations qui exécutent claude -p comme un sous-processus et lisent sa sortie JSON, comme une application Agent SDK ou une interface utilisateur personnalisée construite au-dessus de Claude Code. Cela permet à ce processus appelant de mettre en pause Claude à un appel d'outil, de collecter l'entrée via sa propre interface, et de reprendre où il s'était arrêté. Claude Code honore cette valeur uniquement en mode non-interactif avec le drapeau -p. Dans les sessions interactives, il enregistre un avertissement et ignore le résultat du hook.

L'outil AskUserQuestion est le cas typique : Claude veut poser une question à l'utilisateur, mais il n'y a pas de terminal pour répondre. Une exécution -p offre AskUserQuestion uniquement quand elle a un hôte de permission, comme un outil MCP que vous passez avec --permission-prompt-tool, donc commencez l'exécution avec un. Le aller-retour fonctionne comme ceci :

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.

Le champ deferred_tool_use porte l'id, le name, et l'input de l'outil. L'input est les paramètres que Claude a générés pour l'appel d'outil, capturés avant l'exécution :

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

Il n'y a pas de délai d'expiration ou de limite de tentatives. La session reste sur le disque jusqu'à ce que vous la repreniez, soumise au balayage de rétention cleanupPeriodDays, qui supprime les fichiers de session après 30 jours par défaut, en suivant les règles du balayage de rétention. Si la réponse n'est pas prête quand vous reprenez, le hook peut retourner "defer" à nouveau et le processus quitte de la même façon. Le processus appelant contrôle quand casser la boucle en retournant finalement "allow" ou "deny" du hook.

"defer" fonctionne uniquement quand Claude effectue un seul appel d'outil dans le tour. Si Claude effectue plusieurs appels d'outil à la fois, "defer" est ignoré avec un avertissement et l'outil procède via le flux de permission normal. La contrainte existe parce que la reprise ne peut réexécuter qu'un seul outil : il n'y a aucun moyen de différer un appel d'un lot sans laisser les autres non résolus.

Si l'outil différé n'est plus disponible quand vous reprenez, le processus quitte avec stop_reason: "tool_deferred_unavailable" et is_error: true avant que le hook se déclenche. Cela se produit quand un serveur MCP qui a fourni l'outil n'est pas connecté pour la session reprise. La charge utile deferred_tool_use est toujours incluse pour que vous puissiez identifier quel outil a disparu.

PermissionRequest

S'exécute quand Claude Code est sur le point de vous demander la permission d'utiliser un outil. Dans les sessions qui ne peuvent pas montrer une invite, comme les sous-agents en arrière-plan en mode non-interactif, Claude Code exécute toujours ces hooks, et si aucun hook ne retourne une décision, il refuse l'appel d'outil. Utilisez Contrôle de décision PermissionRequest pour permettre ou refuser au nom de l'utilisateur.

Utilisez cet événement quand vous avez besoin d'un signal au moment où Claude demande la permission d'utiliser un outil. Claude Code exécute un hook Notification avec le type permission_prompt uniquement après que l'invite ait attendu environ six secondes.

Claude Code n'exécute pas les hooks PermissionRequest pour la requête réseau d'une commande en sandbox. Pour obtenir un signal pour cette invite, utilisez le type de notification permission_prompt.

Correspond au nom de l'outil, mêmes valeurs que PreToolUse.

Entrée PermissionRequest

Les hooks PermissionRequest reçoivent les champs tool_name et tool_input comme les hooks PreToolUse, mais sans tool_use_id. Pour un outil MCP, ils reçoivent également l'objet mcp_server. Un tableau optionnel permission_suggestions contient les mises à jour de permission que Claude Code suggère pour cette requête, comme ajouter une règle d'autorisation ou changer le mode de permission.

Le tableau permission_suggestions n'est pas une liste exacte des options que vous voyez, parce que chaque dialogue de permission construit ses propres options. Certains dialogues, comme celui pour les éditions de fichiers, ne lisent pas du tout le tableau et dérivent leurs options de la requête elle-même. Un dialogue qui le lit peut toujours retenir une option dont la suggestion reste dans le tableau, par exemple quand allowManagedPermissionRulesOnly cache les options de sauvegarde de règles. Il peut également offrir des options qui n'ont pas d'entrée de suggestion, comme Oui, et passer en mode auto, qui change le mode de permission directement plutôt que via une mise à jour de permission.

Les hooks PreToolUse s'exécutent avant chaque appel d'outil, qu'il ait besoin de permission ou non. Les hooks PermissionRequest s'exécutent uniquement quand Claude Code est sur le point de vous demander la permission, ou quand il refuserait autrement un appel qui ne peut pas inviter. Aucun événement ne se déclenche pour EndConversation.

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

Les hooks PermissionRequest peuvent permettre ou refuser les demandes de permission. En plus des champs de sortie JSON disponibles pour tous les hooks, votre script de hook peut retourner un objet decision avec ces champs spécifiques à l'événement :

Un hook qui quitte 2 sans un objet decision laisse le flux de permission inchangé, et son stderr est rejeté. Seul l'objet decision peut accorder ou refuser la requête.

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

Entrées de mise à jour de permission

Le champ de sortie updatedPermissions et le champ d'entrée permission_suggestions utilisent tous deux le même tableau d'objets d'entrée. Chaque entrée a un type qui détermine ses autres champs, et une destination qui contrôle où le changement est écrit.

Le champ destination sur chaque entrée détermine si le changement reste en mémoire ou persiste dans un fichier de paramètres.

Un hook peut renvoyer l'une des permission_suggestions qu'il a reçues comme sa propre sortie updatedPermissions.

PostToolUse

S'exécute immédiatement après qu'un outil se termine avec succès.

Correspond au nom de l'outil, mêmes valeurs que PreToolUse.

Correspondez plus largement quand le nom de l'outil n'est pas le bon filtre :

• 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'outil 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

Les hooks PostToolUse se déclenchent après qu'un outil s'est déjà exécuté avec succès. L'entrée inclut à la fois tool_input, les arguments envoyés à l'outil, et tool_response, le résultat qu'il a retourné. Le schéma exact pour les deux dépend de l'outil. Les chemins tool_input des outils de fichier arrivent dans le même format que pour PreToolUse : toujours absolu, avec les séparateurs natifs de la plateforme, donc les barres obliques inverses sur Windows. Pour un outil MCP, l'entrée porte également l'objet mcp_server.

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

Les hooks PostToolUse peuvent fournir des commentaires à Claude après l'exécution de l'outil. En plus des champs de sortie JSON disponibles pour tous les hooks, votre script de hook peut retourner ces champs spécifiques à l'événement :

L'exemple ci-dessous remplace la sortie d'un appel Bash. La valeur de remplacement correspond à la forme de sortie de l'outil Bash :

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

Retournez classifierContext pour envoyer une brève note sur le résultat de l'appel d'outil au classificateur du mode auto plutôt qu'à Claude. Le classificateur ne reçoit jamais les résultats d'outil eux-mêmes, donc ce champ est la façon supportée de lui dire quelque chose sur ce qu'un appel a retourné avant qu'il examine les actions ultérieures. Le champ nécessite Claude Code v2.1.236 ou ultérieur.

L'exemple ci-dessous dit au classificateur d'où provient la sortie d'une requête :

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

Le poids que le classificateur donne à la note dépend de l'endroit où vous avez configuré le hook :

• Hooks configurés dans Claude Code : pour les hooks des fichiers de paramètres, des plugins, des skills, et du 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

Claude Code applique ces limites lors de la livraison de la note :

• 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 de l'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

S'exécute quand un outil qui a commencé à s'exécuter échoue : l'outil a levé une erreur, ou un outil MCP a retourné un résultat d'erreur. Utilisez ceci pour enregistrer les échecs, envoyer des alertes, ou fournir des commentaires correctifs à Claude.

Correspond au nom de l'outil, mêmes valeurs que PreToolUse.

Entrée PostToolUseFailure

Les hooks PostToolUseFailure reçoivent les mêmes champs tool_name et tool_input que PostToolUse, ainsi que les informations d'erreur comme champs de haut niveau. Pour un outil MCP, ils reçoivent également l'objet mcp_server. Par exemple, une commande npm test échouée pourrait livrer :

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

La chaîne error est généralement le même texte que Claude reçoit comme résultat de l'outil échoué. Son format varie selon l'outil et l'échec. Clé votre hook sur tool_name, is_interrupt, et la première ligne Exit code N ; traitez le reste de la chaîne comme du texte d'affichage, pas un format stable.

• 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 des lignes de son propre, comme Command timed out after 2m 0s

Contrôle de décision PostToolUseFailure

Les hooks PostToolUseFailure peuvent fournir du contexte à Claude après un échec d'outil. En plus des champs de sortie JSON disponibles pour tous les hooks, votre script de hook peut retourner ces champs spécifiques à l'événement :

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

PostToolBatch

S'exécute une fois après que chaque appel d'outil dans un lot se soit résolu, avant que Claude Code envoie la requête suivante au modèle. PostToolUse se déclenche une fois par outil, ce qui signifie qu'il se déclenche simultanément quand Claude effectue des appels d'outil parallèles. PostToolBatch se déclenche exactement une fois avec le lot complet, donc c'est le bon endroit pour injecter du contexte qui dépend de l'ensemble des outils qui se sont exécutés plutôt que de n'importe quel outil unique. Il n'y a pas de matcher pour cet événement.

Entrée PostToolBatch

En plus des champs d'entrée communs, les hooks PostToolBatch reçoivent tool_calls, un tableau décrivant chaque appel d'outil dans le lot :

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

tool_response contient le même contenu que le modèle reçoit dans le bloc tool_result correspondant. La valeur est une chaîne sérialisée ou un tableau de bloc de contenu, exactement comme l'outil l'a émis. Pour Read, cela signifie du texte préfixé par le numéro de ligne plutôt que le contenu brut du fichier. Les réponses peuvent être grandes, donc analysez uniquement les champs dont vous avez besoin.

Contrôle de décision PostToolBatch

Les hooks PostToolBatch peuvent injecter du contexte pour Claude. En plus des champs de sortie JSON disponibles pour tous les hooks, votre script de hook peut retourner ces champs spécifiques à l'événement :

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

Retourner decision: "block" ou continue: false arrête la boucle agentive avant l'appel du modèle suivant. Le message de blocage provient du JSON reason ou stopReason, ou de stderr sur la sortie 2. Vous le voyez comme un avertissement dans la transcription, et il reste dans la conversation, donc Claude le voit quand la conversation continue.

PermissionDenied

S'exécute quand le mode auto refuse un appel d'outil, y compris quand il refuse sans verdict du classificateur parce qu'une vérification de sécurité séparée du mode auto a refusé la propre requête du classificateur ou sa réponse n'a pas analysé. Ce hook ne se déclenche que en mode auto : il ne s'exécute pas quand vous refusez manuellement un dialogue de permission, quand un hook PreToolUse bloque un appel, ou quand une règle deny correspond. Utilisez-le pour enregistrer les refus, ajuster la configuration, ou dire au modèle qu'il peut réessayer l'appel d'outil.

Correspond au nom de l'outil, mêmes valeurs que PreToolUse.

Entrée PermissionDenied

En plus des champs d'entrée communs, les hooks PermissionDenied reçoivent tool_name, tool_input, tool_use_id, et reason. Pour un outil MCP, ils reçoivent également l'objet mcp_server.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

Contrôle de décision PermissionDenied

Les hooks PermissionDenied peuvent dire au modèle qu'il peut réessayer l'appel d'outil refusé. Retournez un objet JSON avec hookSpecificOutput.retry défini à true :

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

Quand retry est true, Claude Code ajoute un message à la conversation disant au modèle qu'il peut réessayer l'appel d'outil. Claude Code ne renverse pas le refus lui-même. Si votre hook ne retourne pas JSON, ou retourne retry: false, le refus tient et le modèle reçoit le message de rejet original.

Claude Code ignore retry: true quand le classificateur a produit aucun verdict sur l'action : sa réponse n'a pas analysé, ou une vérification de sécurité séparée du mode auto a refusé la propre requête du classificateur. Pour ces refus, Claude Code dit déjà au modèle dans le message de rejet s'il faut réessayer plus tard ou continuer.

Notification

S'exécute quand Claude Code envoie des notifications. Correspond au type de notification. Omettez le matcher pour exécuter les hooks pour tous les types de notification.

Vous recevez ces événements de hook même avec les notifications de bureau désactivées : le paramètre preferredNotifChannel, y compris notifications_disabled, change uniquement comment vous êtes alerté, pas si votre hook s'exécute.

Les types agent_needs_input et agent_completed nécessitent Claude Code v2.1.198 ou ultérieur.

Les types quota_auto_resume_fired, quota_auto_resume_stale, et quota_auto_resume_disabled nécessitent Claude Code v2.1.234 ou ultérieur.

Dans les sessions de terminal, permission_prompt pour la requête réseau d'une commande en sandbox nécessite Claude Code v2.1.246 ou ultérieur.

agent_needs_input pour la question de configuration de terminal d'un coéquipier nécessite Claude Code v2.1.248 ou ultérieur.

Claude Code chronomètre permission_prompt différemment dans les sessions où il envoie les requêtes de permission au rappel canUseTool d'Agent SDK, ce qui est comment Claude Desktop et l'extension VS Code hébergent Claude Code :

• Attendez permission_prompt environ six secondes après que Claude demande la permission. Claude Code ne le reporte pas pendant que vous tapez.
• Si vous ou un hook PermissionRequest répondez plus tôt, Claude Code n'exécute pas permission_prompt.
• Définissez CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS à 1 pour désactiver permission_prompt dans ces sessions.

Avant v2.1.233, permission_prompt ne se déclenchait pas dans ces sessions.

Utilisez des matchers séparés pour exécuter différents gestionnaires selon le type de notification. Cette configuration déclenche un script d'alerte spécifique à la permission quand Claude a besoin d'approbation de permission et une notification différente quand Claude a été inactif :

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Entrée Notification

En plus des champs d'entrée communs, les hooks Notification reçoivent message avec le texte de notification, un title optionnel, et notification_type indiquant quel type s'est déclenché.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Les hooks Notification ne peuvent pas bloquer ou modifier les notifications. Claude Code rejette leurs champs systemMessage et continue mais émet toujours terminalSequence, sur lequel l'exemple de notification de bureau s'appuie. Les hooks Notification sont destinés aux effets secondaires comme le transfert de la notification vers un service externe.

SubagentStart

S'exécute quand Claude crée un sous-agent avec l'outil Agent, quand Claude reprend un sous-agent, et chaque fois qu'un coéquipier d'équipe agent en processus gère un nouveau message. Supporte les matchers pour filtrer par nom de type d'agent. Pour les agents intégrés, c'est le nom de l'agent comme general-purpose, Explore, ou Plan. Pour les sous-agents personnalisés, c'est le champ name du frontmatter de l'agent, pas le nom de fichier.

Pour les sous-agents fournis par un plugin, le type d'agent est l'identifiant scoped du plugin comme my-plugin:reviewer, pas le nom du frontmatter nu. Le deux-points place un nom scoped du plugin sur le chemin d'expression régulière, donc ancrez le matcher avec ^ et $ pour une correspondance exacte : ^my-plugin:reviewer$.

Entrée SubagentStart

En plus des champs d'entrée communs, les hooks SubagentStart reçoivent agent_id avec l'identifiant unique du sous-agent et agent_type avec le nom de l'agent sur lequel le matcher filtre.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

Les hooks SubagentStart ne peuvent pas bloquer la création de sous-agent, mais ils peuvent injecter du contexte dans le sous-agent. En plus des champs de sortie JSON disponibles pour tous les hooks, vous pouvez retourner :

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

Quand le hook s'exécute à nouveau pour le même sous-agent, Claude Code injecte le contexte retourné uniquement quand le contexte du sous-agent ne contient pas déjà la copie d'une exécution antérieure. La copie injectée au lancement reste en place, laissant le cache d'invite du sous-agent intact. Après que la compaction automatique rejette cette copie, Claude Code injecte le contexte de la prochaine exécution à nouveau.

SubagentStop

S'exécute quand un sous-agent Claude Code a fini de répondre. Correspond au type d'agent, mêmes valeurs que SubagentStart.

Entrée SubagentStop

En plus des champs d'entrée communs, les hooks SubagentStop reçoivent stop_hook_active, agent_id, agent_type, agent_transcript_path, et last_assistant_message. Le champ agent_type est la valeur utilisée pour le filtrage du matcher. Le transcript_path est la transcription de la session principale, tandis que agent_transcript_path est la propre transcription du sous-agent stockée dans un dossier subagents/ imbriqué. Le champ last_assistant_message contient le contenu textuel de la réponse finale du sous-agent, donc les hooks peuvent y accéder sans analyser le fichier de transcription.

Pas chaque événement SubagentStop provient d'un sous-agent que Claude a créé. Claude Code exécute également des agents internes pour certaines de ses propres fonctionnalités, comme les suggestions d'invite et les questions latérales /btw, et SubagentStop se déclenche quand l'un de ceux-ci se termine aussi. Pour ces événements, agent_type est le nom de l'agent que la session elle-même exécute, comme celui défini avec --agent ou le paramètre agent, et une chaîne vide quand la session s'exécute sans un.

Un matcher qui nomme les types d'agent ne correspond pas à un agent_type vide. Un hook dont le matcher est omis, "", ou "*", ou est une expression régulière qui correspond à une chaîne vide, s'exécute pour les événements avec un agent_type vide aussi.

Sur Claude Code v2.1.271 ou ultérieur, un sous-agent qui s'exécute avec l'outil SubagentHandback livre son rapport via cet outil avant qu'il ne s'arrête. Le champ last_assistant_message contient alors le texte de fermeture du sous-agent, le cas échéant, qui n'est pas le rapport livré. Le rapport est l'entrée message de cet appel, qu'un hook PreToolUse ou PostToolUse correspondant à SubagentHandback reçoit comme tool_input.message.

Les hooks SubagentStop reçoivent également les tableaux background_tasks et session_crons décrits sous Entrée Stop. Les deux tableaux sont scoped à la session parent, pas au sous-agent.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

Les hooks SubagentStop utilisent le même format de contrôle de décision que les hooks Stop, y compris hookSpecificOutput.additionalContext avec hookEventName défini à "SubagentStop", pour les commentaires sans erreur qui gardent le sous-agent en cours d'exécution. Retourner decision: "block" avec une reason garde le sous-agent en cours d'exécution et livre reason au sous-agent comme sa prochaine instruction. Un hook qui bloque en quittant 2 livre son message stderr de la même façon. Pour injecter du contexte dans la session parent après qu'un sous-agent retourne, utilisez plutôt un hook PostToolUse sur l'outil Agent.

TaskCreated

S'exécute quand une tâche est en cours de création via l'outil TaskCreate. Utilisez ceci pour appliquer les conventions de nommage, exiger les descriptions de tâche, ou empêcher certaines tâches d'être créées. Dans une session sans les outils Task, cet événement ne se déclenche pas.

Les hooks TaskCreated ne supportent pas les matchers et se déclenchent à chaque occurrence.

Entrée TaskCreated

En plus des champs d'entrée communs, les hooks TaskCreated reçoivent task_id, task_subject, et optionnellement task_description, teammate_name, et team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

Contrôle de décision TaskCreated

Un hook TaskCreated peut bloquer la création de deux façons. De l'une ou l'autre façon, Claude Code supprime la tâche et retourne votre message à Claude comme l'erreur de l'outil. Claude Code ignore continue: false de cet événement et Claude continue de travailler.

• Code de sortie 2 : Claude Code retourne le texte stderr comme le message.
• JSON {"decision": "block", "reason": "..."} : Claude Code retourne reason comme le message.

Cet exemple bloque les tâches dont les sujets ne suivent pas le format requis :

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

S'exécute quand une tâche est en cours de marquage comme complétée. Cela se déclenche dans deux situations : qu'un agent marque explicitement une tâche comme complétée via l'outil TaskUpdate, ou quand un coéquipier d'équipe agent termine son tour avec des tâches en cours. Utilisez ceci pour appliquer les critères de complétion comme passer les tests ou les vérifications lint avant qu'une tâche puisse se fermer.

Les hooks TaskCompleted ne supportent pas les matchers et se déclenchent à chaque occurrence.

Entrée TaskCompleted

En plus des champs d'entrée communs, les hooks TaskCompleted reçoivent task_id, task_subject, et optionnellement task_description, teammate_name, et team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

Contrôle de décision TaskCompleted

Les hooks TaskCompleted supportent deux façons de contrôler la complétion de tâche :

• Code de sortie 2 : la tâche n'est pas marquée comme complétée et le message stderr est renvoyé au modèle comme commentaire.
• JSON {"continue": false, "stopReason": "..."} : quand un coéquipier terminant son tour a déclenché l'événement, arrête le coéquipier entièrement, correspondant au comportement du hook Stop. Le stopReason est montré à l'utilisateur. Quand l'outil TaskUpdate a déclenché l'événement, Claude Code ignore continue: false ; le code de sortie 2 bloque toujours la complétion.

Cet exemple exécute les tests et bloque la complétion de tâche s'ils échouent :

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

S'exécute quand l'agent Claude Code principal a fini de répondre. Ne s'exécute pas si l'arrêt s'est produit en raison d'une interruption utilisateur. Les erreurs API déclenchent plutôt StopFailure.

Entrée Stop

En plus des champs d'entrée communs, les hooks Stop reçoivent stop_hook_active, last_assistant_message, background_tasks, et session_crons. Le champ stop_hook_active est true quand Claude Code continue déjà en raison d'un hook stop. Vérifiez cette valeur ou traitez la transcription pour éviter de bloquer sur une condition qui ne se résoudra jamais. Claude Code remplace le hook et termine le tour après 8 blocages consécutifs.

Le champ last_assistant_message contient le contenu textuel de la réponse finale de Claude, donc les hooks peuvent y accéder sans analyser le fichier de transcription. Pour les hooks qui agissent sur le tour qui vient de se terminer, comme les hooks de lecture à haute voix ou de notification, utilisez ce champ plutôt que de lire transcript_path : le fichier de transcription n'est pas garanti d'inclure le message final au moment de Stop sur toutes les versions.

Les tableaux background_tasks et session_crons permettent aux hooks de distinguer « la session est terminée » de « la session est en pause en attente que le travail en arrière-plan la réveille ». Les deux tableaux sont présents quand le registre de tâches est accessible et sont vides quand rien n'est en vol ou programmé.

Chaque entrée dans background_tasks décrit une tâche en vol et utilise ces champs :

Chaque entrée dans session_crons décrit un réveil programmé scoped à la session, provenant de CronCreate, ScheduleWakeup, et /loop :

Cet exemple montre une entrée Stop avec une tâche shell en vol et un cron récurrent :

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Contrôle de décision Stop

Les hooks Stop et SubagentStop peuvent contrôler si Claude continue. En plus des champs de sortie JSON disponibles pour tous les hooks, votre script de hook peut retourner ces champs spécifiques à l'événement :

Un hook qui bloque en quittant 2 s'achemine de la même façon que reason : Claude reçoit le message stderr comme l'explication de pourquoi il devrait continuer.

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

Utilisez additionalContext quand le hook fonctionne comme prévu et donne des conseils à Claude, comme « exécutez la suite de tests avant de terminer ». Cela garde la conversation en cours via les mêmes protections de boucle que decision: "block", à savoir l'entrée stop_hook_active et le plafond de 8 continuations consécutives, mais la transcription l'étiquette Stop hook feedback et aucune notification d'erreur de hook n'est montrée :

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

S'exécute à la place de Stop quand le tour se termine en raison d'une erreur API. Claude Code ignore la sortie et le code de sortie du hook, à part terminalSequence. Utilisez ceci pour enregistrer les échecs, envoyer des alertes, ou prendre des actions de récupération quand Claude ne peut pas terminer une réponse en raison des limites de débit, des problèmes d'authentification, ou d'autres erreurs API.

Entrée StopFailure

En plus des champs d'entrée communs, les hooks StopFailure reçoivent error, optionnel error_details, et optionnel last_assistant_message. Le champ error identifie le type d'erreur et est utilisé pour le filtrage du matcher.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

Les hooks StopFailure n'ont pas de contrôle de décision. Ils s'exécutent à des fins de notification et de logging uniquement.

TeammateIdle

S'exécute quand un coéquipier d'équipe agent est sur le point de devenir inactif après avoir terminé son tour. Utilisez ceci pour appliquer les portes de qualité avant qu'un coéquipier arrête de travailler, comme exiger les vérifications lint de passage ou vérifier que les fichiers de sortie existent.

Les hooks TeammateIdle ne supportent pas les matchers et se déclenchent à chaque occurrence.

Entrée TeammateIdle

En plus des champs d'entrée communs, les hooks TeammateIdle reçoivent teammate_name et team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

Contrôle de décision TeammateIdle

Les hooks TeammateIdle supportent deux façons de contrôler le comportement du coéquipier :

• Code de sortie 2 : le coéquipier reçoit le message stderr comme commentaire et continue de travailler au lieu de devenir inactif.
• JSON {"continue": false, "stopReason": "..."} : arrête le coéquipier entièrement, correspondant au comportement du hook Stop. Le stopReason est montré à l'utilisateur.

Cet exemple vérifie qu'un artefact de construction existe avant de permettre à un coéquipier de devenir inactif :

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

S'exécute quand un fichier de configuration change pendant une session. Utilisez ceci pour auditer les changements de paramètres, appliquer les politiques de sécurité, ou bloquer les modifications non autorisées aux fichiers de configuration.

Claude Code exécute les hooks ConfigChange quand un fichier de paramètres, un fichier de politique gérée, ou un fichier de skill change. Pour la politique gérée, il les exécute uniquement quand managed-settings.json ou un fichier dans managed-settings.d/ change. Il applique les paramètres gérés par le serveur et les changements aux préférences gérées macOS ou à la politique du registre Windows sans les exécuter. Sur WSL avec wslInheritsWindowsSettings, il applique également un fichier de paramètres gérés Windows modifié du côté Windows sur son sondage de politique sans les exécuter.

Le matcher filtre sur la source de configuration :

Cet exemple enregistre tous les changements de configuration pour l'audit de sécurité :

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Entrée ConfigChange

En plus des champs d'entrée communs, les hooks ConfigChange reçoivent source et optionnellement file_path. Le champ source indique quel type de configuration a changé, et file_path fournit le chemin du fichier spécifique qui a été modifié.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

Contrôle de décision ConfigChange

Les hooks ConfigChange peuvent bloquer les changements de configuration de prendre effet. Utilisez le code de sortie 2 ou un JSON decision pour empêcher le changement. Quand bloqué, les nouveaux paramètres ne sont pas appliqués à la session en cours d'exécution.

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

Les changements policy_settings ne peuvent pas être bloqués. Les hooks se déclenchent toujours pour les sources policy_settings quand un fichier de paramètres gérés sur la machine change, pour que vous puissiez enregistrer ces édits, mais toute décision de blocage est ignorée. Cela garantit que les paramètres gérés par l'entreprise prennent toujours effet. Claude Code n'exécute pas les hooks ConfigChange quand les paramètres gérés par le serveur arrivent ou se rafraîchissent.

Claude Code agit sur la décision de blocage de la sortie JSON d'un hook ConfigChange et rejette systemMessage et continue. Un changement bloqué ne surface aucun message pour vous ou pour Claude, que vous bloquez avec reason ou avec stderr sur la sortie 2. Claude Code écrit uniquement une ligne dans le journal de débogage.

CwdChanged

S'exécute quand une commande shell dans la conversation principale change le répertoire de travail, par exemple quand Claude exécute une commande cd. Utilisez ceci pour réagir aux changements de répertoire : recharger les variables d'environnement, activer les chaînes d'outils spécifiques au projet, ou exécuter les scripts de configuration automatiquement. S'apparie avec FileChanged pour les outils comme direnv qui gèrent l'environnement par répertoire.

Les hooks CwdChanged ont accès à CLAUDE_ENV_FILE. Les variables écrites dans ce fichier persistent dans les commandes Bash suivantes jusqu'au prochain événement CwdChanged, quand Claude Code les efface.

CwdChanged ne supporte pas les matchers et se déclenche à chaque occurrence.

Entrée CwdChanged

En plus des champs d'entrée communs, les hooks CwdChanged reçoivent old_cwd et new_cwd.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

Sortie CwdChanged

En plus des champs de sortie JSON disponibles pour tous les hooks, les hooks CwdChanged peuvent retourner watchPaths pour définir dynamiquement quels chemins de fichier FileChanged surveille :

Les hooks CwdChanged n'ont pas de contrôle de décision. Ils ne peuvent pas bloquer le changement de répertoire.

Claude Code lit watchPaths et systemMessage de leur sortie JSON et rejette continue. Dans les sessions interactives, il montre le systemMessage comme une brève notification de terminal. Le message n'atteint pas le flux de message SDK.

DirectoryAdded

S'exécute après que vous ajoutiez un répertoire de travail en cours de session avec la commande /add-dir, ou après qu'un client SDK en ajoute un avec la requête de contrôle register_repo_root. Utilisez ceci pour préparer un référentiel nouvellement ajouté, par exemple en installant ses dépendances.

Claude Code ne déclenche pas cet événement quand :

• Vous passez un répertoire avec le drapeau de démarrage --add-dir ; SessionStart couvre ces répertoires
• Vous ajoutez un répertoire sur l'onglet Workspace /permissions
• Vous ajoutez un répertoire qui est déjà un répertoire de travail ou à l'intérieur d'un

Claude Code se déclenche DirectoryAdded après avoir rafraîchi l'état du sandbox et de la permission, donc les outils en sandbox voient déjà le nouveau répertoire quand votre hook s'exécute. Les commandes du hook elles-mêmes s'exécutent sans sandbox.

Claude Code n'attend pas le hook : l'ajout se termine immédiatement, et le hook s'exécute en arrière-plan avec le délai d'expiration par défaut de 600 secondes.

Le matcher filtre sur la façon dont le répertoire a été ajouté :

Entrée DirectoryAdded

En plus des champs d'entrée communs, les hooks DirectoryAdded reçoivent directory et source.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

Les hooks DirectoryAdded n'ont pas de contrôle de décision. Ils ne peuvent pas bloquer l'ajout, qui s'est déjà terminé quand le hook s'exécute. Claude Code rejette le champ continue de leur sortie JSON et affiche le reste différemment par source :

• slash_command : Claude Code livre le systemMessage du hook à Claude comme contexte sur le tour de conversation suivant, plutôt que de vous le montrer. Un nombre de hooks échoués apparaît dans la transcription. La sortie d'échec complète va dans le journal de débogage
• register_repo_root : Claude Code écrit la sortie systemMessage et la sortie d'échec uniquement dans le journal de débogage

FileChanged

S'exécute quand un fichier surveillé change sur le disque. Claude Code détecte les changements avec un observateur de système de fichiers, pas en inspectant les appels d'outil, donc il exécute le hook peu importe ce qui a changé le fichier : un appel d'outil Edit ou Write, un script que Claude exécute avec Bash, ou un processus en dehors de Claude Code entièrement. Un usage courant est de recharger les variables d'environnement quand les fichiers de configuration du projet changent.

Le matcher pour cet événement sert deux rôles :

• Construire la liste de surveillance : la valeur est divisée sur | et chaque segment est enregistré comme un nom de fichier littéral dans le répertoire de travail, donc ".envrc|.env" surveille exactement ces deux fichiers. Les modèles regex ne sont pas utiles ici : une valeur comme ^\.env surveillerait un fichier littéralement nommé ^\.env.
• Filtrer quels hooks s'exécutent : quand un fichier surveillé change, la même valeur filtre quels groupes de hook s'exécutent en utilisant les règles de matcher standard contre le nom de base du fichier modifié.

Cet exemple normalise les fins de ligne dans data.csv après n'importe quel changement, y compris une commande Bash ou un script externe réécrivant le fichier :

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

Le hook lit le chemin absolu du fichier modifié du champ file_path de l'entrée JSON sur stdin. Sa garde grep teste la même chose que perl supprime, un CR à la fin d'une ligne, donc l'exécution après une normalisation quitte sans toucher le fichier. Une garde plus lâche boucle pour toujours, parce que perl -i réécrit le fichier même quand il ne substitue rien et Claude Code exécute le hook à nouveau après chaque réécriture. Enregistrez ce script à /path/to/normalize-line-endings.sh et rendez-le exécutable :

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

Pour confirmer que le hook fonctionne, demandez à Claude d'ajouter une ligne CRLF à data.csv avec une commande Bash. Claude Code exécute le hook et le fichier se termine avec les fins de ligne LF.

Pour surveiller les fichiers que vous ne pouvez pas nommer à l'avance, retournez watchPaths d'un hook pour mettre à jour la liste de surveillance dynamiquement. Claude Code démarre l'observateur uniquement quand quelque chose nomme un fichier à surveiller, donc semez la liste avec un groupe FileChanged dont le matcher nomme au moins un fichier, ou avec un hook SessionStart ou CwdChanged qui retourne watchPaths. Le matcher filtre toujours quels groupes de hook s'exécutent quand un fichier surveillé change, donc donnez au groupe qui gère les chemins dynamiques un matcher omis, qui correspond à chaque fichier surveillé et n'ajoute rien à la liste de surveillance. Un matcher "*" correspond également à chaque fichier, mais Claude Code l'enregistre dans la liste de surveillance comme n'importe quelle autre valeur, comme un fichier littéralement nommé *.

Les hooks FileChanged ont accès à CLAUDE_ENV_FILE. Les variables écrites dans ce fichier persistent dans les commandes Bash suivantes jusqu'au prochain événement CwdChanged, quand Claude Code les efface.

Entrée FileChanged

En plus des champs d'entrée communs, les hooks FileChanged reçoivent file_path et event.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

Sortie FileChanged

En plus des champs de sortie JSON disponibles pour tous les hooks, les hooks FileChanged peuvent retourner watchPaths pour mettre à jour dynamiquement quels chemins de fichier sont surveillés :

Les hooks FileChanged n'ont pas de contrôle de décision. Ils ne peuvent pas bloquer le changement de fichier de se produire.

Claude Code lit watchPaths et systemMessage de leur sortie JSON et rejette continue. Dans les sessions interactives, il montre le systemMessage comme une brève notification de terminal. Le message n'atteint pas le flux de message SDK.

WorktreeCreate

S'exécute quand un worktree est en cours de création, que ce soit à partir de claude --worktree, à partir d'un sous-agent utilisant isolation: "worktree", ou pour une session en arrière-plan que Claude Code isole dans son propre worktree. Par défaut, Claude Code crée la copie de travail isolée avec git worktree. Configurer un hook WorktreeCreate remplace ce comportement git par défaut, vous permettant d'utiliser un système de contrôle de version différent comme SVN, Perforce, ou Mercurial.

Parce que le hook remplace le comportement par défaut entièrement, .worktreeinclude n'est pas traité. Si vous avez besoin de copier les fichiers de configuration locaux comme .env dans le nouveau worktree, faites-le à l'intérieur de votre script de hook.

Le hook doit retourner le chemin du répertoire worktree créé. Claude Code utilise ce chemin comme le répertoire de travail pour la session isolée. Voir Sortie WorktreeCreate pour savoir comment chaque type de hook retourne le chemin.

Claude Code agit sur le succès du hook et le chemin retourné, et rejette systemMessage et continue.

Cet exemple crée une copie de travail SVN et imprime le chemin pour que Claude Code l'utilise. Remplacez l'URL du référentiel par la vôtre :

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Le hook lit le name du worktree de l'entrée JSON sur stdin, extrait une copie fraîche dans un nouveau répertoire, et imprime le chemin du répertoire. Le echo sur la dernière ligne est ce que Claude Code lit comme le chemin du worktree. Redirigez toute autre sortie vers stderr pour qu'elle n'interfère pas avec le chemin.

Entrée WorktreeCreate

En plus des champs d'entrée communs, les hooks WorktreeCreate reçoivent le champ name. C'est un identifiant slug pour le nouveau worktree, soit spécifié par l'utilisateur, soit auto-généré, par exemple bold-oak-a3f2.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

Sortie WorktreeCreate

Les hooks WorktreeCreate n'utilisent pas le modèle de décision permettre/bloquer standard. Au lieu de cela, le succès ou l'échec du hook détermine le résultat. Le hook doit retourner le chemin du répertoire worktree créé :

• Hooks de commande (type: "command"): imprimez le chemin comme la dernière ligne non-vide de stdout. Claude Code supprime les codes d'échappement ANSI avant de lire cette ligne, donc les bannières de démarrage du shell imprimées avant votre echo sont ignorées. Redirigez toute autre sortie du hook vers stderr.
• Hooks HTTP (type: "http"): retournez { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } dans le corps de la réponse.

Si le hook échoue ou ne produit pas de chemin, la création du worktree échoue avec une erreur.

Claude Code résout un chemin relatif contre le répertoire dans lequel le hook s'est exécuté, en effondrant tout segment . ou .. dedans. Si le chemin résultant n'est pas un répertoire que Claude Code peut entrer, la session imprime une erreur nommant le chemin et quitte avec le code 1.

Claude Code refuse un chemin absolu qui contient des segments . ou .., et n'importe quel chemin qui passe par un lien symbolique en dessous de la racine du référentiel, parce qu'un lien symbolique commis au référentiel pourrait rediriger le worktree en dehors de lui. L'erreur nomme le composant rejeté. Retournez un chemin normalisé qui ne passe pas par un lien symbolique à l'intérieur du référentiel. Avant v2.1.216, la création du worktree suivait le chemin du hook sans ce dépistage.

WorktreeRemove

S'exécute quand un worktree est en cours de suppression. C'est la contrepartie de nettoyage de WorktreeCreate. L'événement se déclenche quand :

• vous quittez une session --worktree et choisissez de la supprimer
• un sous-agent avec isolation: "worktree" se termine
• vous supprimez une session en arrière-plan dont le worktree a été créé par le hook

Pour les worktrees basés sur git, Claude Code gère le nettoyage automatiquement avec git worktree remove. Si vous avez configuré un hook WorktreeCreate pour un système de contrôle de version non-git, associez-le à un hook WorktreeRemove pour gérer le nettoyage. Sans un, le répertoire worktree est laissé sur le disque.

Claude Code rejette les champs de sortie JSON d'un hook WorktreeRemove, comme systemMessage et continue.

Pour une suppression de session en arrière-plan, Claude Code vérifie le chemin du worktree stocké avant d'exécuter le hook et refuse un chemin qui est un lien symbolique ou passe par un en dessous de la racine du référentiel. Le hook s'exécute pour un worktree qui contient toujours des fichiers uniquement quand vous confirmez la suppression dans la vue agent ; pour un tel worktree, claude rm garde la session et le worktree à la place. Avant v2.1.216, le hook s'exécutait sur le chemin stocké sans ces vérifications.

Claude Code passe le chemin retourné par WorktreeCreate comme worktree_path dans l'entrée du hook. Cet exemple lit ce chemin et supprime le répertoire :

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

Entrée WorktreeRemove

En plus des champs d'entrée communs, les hooks WorktreeRemove reçoivent le champ worktree_path, qui est le chemin absolu du worktree en cours de suppression.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

Le code de sortie d'un hook WorktreeRemove décide du résultat. Quand un hook quitte non-zéro et le répertoire à worktree_path existe toujours après, la suppression échoue :

• Le worktree reste sur le disque, et la commande du hook et stderr vont dans le journal de débogage.
• Si vous supprimiez une session en arrière-plan, la session reste aussi. Le message de refus dans la vue agent rapporte comment le hook s'est terminé, comme exited 1, cite le début de son stderr, et dit si la suppression de la session à nouveau supprime le répertoire de toute façon.

PreCompact

S'exécute avant que Claude Code soit sur le point d'exécuter une opération de compaction.

La valeur du matcher indique si la compaction a été déclenchée manuellement ou automatiquement :

Quittez avec le code 2 pour bloquer la compaction. Pour un /compact manuel, le message stderr est montré à l'utilisateur. Vous pouvez également bloquer en retournant JSON avec "decision": "block".

Bloquer la compaction automatique a des effets différents selon quand elle se déclenche. Si la compaction a été déclenchée de manière proactive avant la limite de contexte, Claude Code la saute et la conversation continue sans compaction. Si la compaction a été déclenchée pour récupérer d'une erreur de limite de contexte déjà retourné par l'API, l'erreur sous-jacente surface et la requête actuelle échoue.

Claude Code rejette les champs systemMessage et continue d'un hook PreCompact.

Entrée PreCompact

En plus des champs d'entrée communs, les hooks PreCompact reçoivent trigger et custom_instructions. Pour manual, custom_instructions contient ce que l'utilisateur passe dans /compact et est null quand il ne passe rien. Pour auto, custom_instructions est null.

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

PostCompact

S'exécute après que Claude Code termine une opération de compaction. Utilisez cet événement pour réagir à l'état compacté nouveau, par exemple pour enregistrer le résumé généré ou mettre à jour l'état externe. Claude Code rejette les champs systemMessage et continue d'un hook PostCompact.

Les mêmes valeurs de matcher s'appliquent que pour PreCompact :

Entrée PostCompact

En plus des champs d'entrée communs, les hooks PostCompact reçoivent trigger et compact_summary. Le champ compact_summary contient le résumé de conversation généré par l'opération de compaction.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

Les hooks PostCompact n'ont pas de contrôle de décision. Ils ne peuvent pas affecter le résultat de la compaction mais peuvent effectuer les tâches de suivi.

PreModelSwitch

S'exécute avant que Claude Code applique un changement de modèle que vous ou un client avez demandé. Utilisez-le pour bloquer un changement, exiger une confirmation, ou montrer ce que le changement coûtera avant qu'il se produise.

PreModelSwitch nécessite Claude Code v2.1.251 ou ultérieur. Claude Code l'exécute pour ces requêtes :

• /model <name> et le sélecteur /model
• Le sélecteur de modèle Option+P ou Alt+P
• Le paramètre Model dans /config
• Activer le mode rapide quand cela change le modèle de la session
• Une requête set_model, ou un changement de modèle dans une requête apply_flag_settings, d'un hôte Agent SDK ou Remote Control

Claude Code n'exécute pas les hooks PreModelSwitch pour les changements qu'il fait de son propre chef, comme un repli de modèle automatique ou la restauration du modèle quand vous reprenez une session. Ces changements atteignent PostModelSwitch uniquement.

Claude Code compare le matcher contre le nom canonique du modèle vers lequel la session change, en ignorant tout suffixe [1m]. Un alias comme opus, un ID de modèle daté, et un ID spécifique au fournisseur comme un ID de modèle Amazon Bedrock correspondent tous au seul nom canonique auquel ils se résolvent, donc claude-opus-5 couvre chaque orthographe d'Opus 5.

Quand Claude Code ne peut pas déterminer un nom canonique pour la cible, par exemple un ID de modèle personnalisé que seule votre passerelle LLM connaît, il exécute chaque hook PreModelSwitch indépendamment du matcher. Un hook qui bloque devrait donc vérifier to_model de son entrée plutôt que de compter sur le matcher seul.

Écrivez le matcher comme un nom exact, une liste séparée par | comme claude-opus-4-6|claude-opus-5, ou une expression régulière comme .*opus.*. Cet exemple utilise un matcher de nom exact et vérifie également to_model de l'entrée du hook, donc il refuse un changement vers Opus 4.6 en quittant avec le code 2 et laisse n'importe quelle autre cible passer :

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

Pour confirmer que le hook fonctionne, exécutez /model claude-opus-4-6 à partir d'une session exécutant un modèle différent. Claude Code garde le modèle actuel et rapporte qu'un hook PreModelSwitch a bloqué le changement, avec votre message comme raison.

Entrée PreModelSwitch

En plus des champs d'entrée communs, les hooks PreModelSwitch reçoivent les champs de ce tableau. Les cinq derniers décrivent ce que renvoyer la conversation au nouveau modèle coûte, pour qu'un hook puisse montrer ce chiffre avant que le changement se produise.

Cet exemple montre l'entrée pour /model opus dans une session exécutant Sonnet 5 :

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

Contrôle de décision PreModelSwitch

Les hooks PreModelSwitch peuvent annuler le changement, demander à l'utilisateur de le confirmer, ou le laisser procéder. Le code de sortie 2 ou un decision: "block" de haut niveau annule le changement.

Pour un contrôle plus fin, retournez permissionDecision et permissionDecisionReason dans un objet hookSpecificOutput, comme sur PreToolUse. PreModelSwitch accepte "allow", "deny", et "ask". Il n'accepte pas "defer", updatedInput, ou additionalContext. Le tableau ci-dessous décrit les deux champs :

Seul /model dans une session interactive peut montrer l'invite "ask". Sur chaque autre surface, y compris le mode non-interactif avec le drapeau -p, /config, et les requêtes set_model, Claude Code traite "ask" comme un refus.

Cet exemple demande à l'utilisateur de confirmer et cite le nombre de tokens de context_tokens :

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

Quand plusieurs hooks PreModelSwitch retournent des décisions différentes, la priorité est deny > ask > allow.

Claude Code montre à l'utilisateur tout systemMessage que votre hook retourne indépendamment de la décision, pour qu'un hook de rapport de coûts puisse retourner {"systemMessage": "..."} et quitter 0.

Un hook PreModelSwitch qui ne répond pas avant son délai d'expiration bloque le changement. Sur PreToolUse, par contraste, un hook de commande qui expire laisse l'appel d'outil continuer. Le délai d'expiration par défaut pour cet événement est 30 secondes. PreModelSwitch exécute uniquement les hooks command, http, et mcp_tool, donc les défauts prompt et agent ne s'appliquent pas.

Un hook qui quitte avec un code autre que 0 ou 2 et n'imprime pas de décision JSON ne bloque pas : Claude Code montre son stderr et applique le changement, comme décrit sous Autres codes de sortie.

PostModelSwitch

S'exécute après que le modèle de la session change. Utilisez-le pour donner à Claude des conseils spécifiques au modèle sans éditer chaque CLAUDE.md, par exemple une instruction à l'échelle de l'organisation qui s'applique sur certains modèles.

PostModelSwitch nécessite Claude Code v2.1.251 ou ultérieur. Il ne peut pas bloquer, parce que le modèle a déjà changé. Claude Code exécute les hooks PostModelSwitch après n'importe lequel de ces changements :

• Un changement que vous ou un client avez demandé
• Un repli de modèle automatique, qui change le modèle de la session
• Un paramètre comme opusplan entrant ou quittant le mode plan
• Claude Code restaure le modèle quand vous reprenez une session

Claude Code n'exécute pas les hooks PostModelSwitch quand un modèle d'une chaîne de modèle de repli sert un tour, parce que cette substitution dure un tour et laisse le modèle de la session inchangé.

Le matcher suit les mêmes règles que PreModelSwitch : Claude Code le compare contre le nom canonique du modèle vers lequel la session a changé.

Cet exemple ajoute des conseils chaque fois que le modèle de la session change vers n'importe quel modèle Opus :

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

Pour confirmer que le hook fonctionne, changez vers un modèle Opus à partir d'une session exécutant un modèle différent, par exemple exécutez /model opus à partir d'une session Sonnet, puis demandez à Claude quels conseils il a sur le modèle actuel.

Entrée PostModelSwitch

Les hooks PostModelSwitch reçoivent les mêmes champs que PreModelSwitch, avec hook_event_name défini à "PostModelSwitch" et deux valeurs source supplémentaires : "auto" pour un repli automatique ou un autre changement que Claude Code a fait de son propre chef, et "resume" pour le modèle restauré quand vous reprenez une session.

requested_model est null quand source est "auto". Quand source est "resume", c'est le paramètre de modèle sauvegardé que Claude Code a restauré.

Contrôle de décision PostModelSwitch

Claude Code prend votre sortie standard texte brut du hook sur la sortie 0, ou additionalContext de la sortie JSON, et la livre à Claude avec la requête suivante après le changement. En plus des champs de sortie JSON disponibles pour tous les hooks, vous pouvez retourner :

Si le hook n'a pas fini dans les cinq secondes après que vous envoyiez la requête suivante, Claude Code envoie cette requête sans la sortie et l'attache à la requête suivante à la place. Si le modèle change plusieurs fois avant la requête suivante, Claude Code livre uniquement la sortie pour le modèle cible du dernier changement.

SessionEnd

S'exécute quand une session Claude Code se termine. Utile pour les tâches de nettoyage, l'enregistrement des statistiques de session, ou la sauvegarde de l'état de la session. Supporte les matchers pour filtrer par raison de sortie.

Le champ reason dans l'entrée du hook indique pourquoi la session s'est terminée :

Entrée SessionEnd

En plus des champs d'entrée communs, les hooks SessionEnd reçoivent un champ reason indiquant pourquoi la session s'est terminée. Voir le tableau de raison ci-dessus pour toutes les valeurs.

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

Les hooks SessionEnd n'ont pas de contrôle de décision. Ils ne peuvent pas bloquer la terminaison de la session mais peuvent effectuer les tâches de nettoyage. Claude Code rejette leurs champs de sortie JSON, comme systemMessage.

Les hooks SessionEnd ont un délai d'expiration par défaut de 1,5 secondes. Il s'applique quand vous quittez, exécutez /clear, ou changez de sessions avec /resume interactif. Vous pouvez donner à un hook plus de temps de deux façons :

• timeout par hook : définissez timeout dans la configuration de ce hook. Le budget global augmente automatiquement pour correspondre au timeout par hook le plus élevé dans vos fichiers de paramètres, jusqu'à 60 secondes. Si vous augmentez le budget de cette façon, un hook sans son propre timeout garde toujours le défaut. Les délais d'expiration définis sur les hooks fournis par les plugins ne lèvent pas le budget.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS : définissez cette variable d'environnement en millisecondes pour remplacer le budget explicitement. La valeur que vous définissez devient également le délai d'expiration pour chaque hook sans son propre timeout.

Cet exemple définit le budget à 5 secondes :

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Avant v2.1.268, CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS levait uniquement le budget global, et un hook sans son propre timeout était toujours annulé après 1,5 secondes.

Elicitation

S'exécute quand un serveur MCP demande l'entrée utilisateur en cours de tâche. Par défaut, Claude Code montre un dialogue interactif pour que l'utilisateur réponde. Les hooks peuvent intercepter cette requête et répondre par programmation, ignorant entièrement le dialogue.

Le champ matcher correspond au nom du serveur MCP.

Entrée Elicitation

En plus des champs d'entrée communs, les hooks Elicitation reçoivent mcp_server_name, message, et les champs optionnels mode, url, elicitation_id, et requested_schema.

Pour l'élicitation en mode formulaire, le cas le plus courant :

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

Pour l'élicitation en mode URL, utilisée pour l'authentification basée sur navigateur :

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Sortie Elicitation

Pour répondre par programmation sans montrer le dialogue, retournez un objet JSON avec hookSpecificOutput :

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

Le code de sortie 2 refuse l'élicitation. Claude Code n'affiche votre message stderr nulle part.

Claude Code agit sur hookSpecificOutput de la sortie JSON d'un hook Elicitation et rejette systemMessage et continue.

ElicitationResult

S'exécute après qu'un utilisateur réponde à une élicitation MCP. Les hooks peuvent observer, modifier, ou bloquer la réponse avant qu'elle ne soit renvoyée au serveur MCP.

Le champ matcher correspond au nom du serveur MCP.

Entrée ElicitationResult

En plus des champs d'entrée communs, les hooks ElicitationResult reçoivent mcp_server_name, action, et les champs optionnels mode, elicitation_id, et content.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

Sortie ElicitationResult

Pour remplacer la réponse de l'utilisateur, retournez un objet JSON avec hookSpecificOutput :

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

Le code de sortie 2 bloque la réponse, changeant l'action effective à decline. Claude Code n'affiche votre message stderr nulle part.

Claude Code agit sur hookSpecificOutput de la sortie JSON d'un hook ElicitationResult et rejette systemMessage et continue.

Hooks basés sur des prompts

En plus des hooks de commande, HTTP et MCP tool, Claude Code supporte les hooks basés sur des prompts (type: "prompt") qui utilisent un LLM pour évaluer s'il faut autoriser ou bloquer une action, et les hooks d'agent (type: "agent") qui lancent un vérificateur agentique avec accès aux outils. Tous les événements ne supportent pas tous les types de hooks.

Les événements qui supportent les cinq types de hooks (command, http, mcp_tool, prompt et agent) :

• PermissionDenied
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest supporte les hooks command, http, mcp_tool et prompt mais pas les hooks agent. Si vous configurez un hook d'agent sur cet événement, Claude Code le saute et le flux de permission se poursuit sans changement. Pour autoriser ou refuser à partir d'un hook, retournez l'objet de décision à partir d'un hook de commande ou HTTP.

Les événements qui supportent les hooks command, http et mcp_tool mais pas prompt ou agent :

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart et Setup supportent les hooks command et mcp_tool, et les champs des hooks MCP tool décrivent quand leurs hooks mcp_tool s'exécutent. Ils ne supportent pas les hooks http, prompt ou agent.

Comment fonctionnent les hooks basés sur des prompts

Au lieu d'exécuter une commande Bash, les hooks basés sur des prompts :

1. Envoient l'entrée du hook et votre prompt à un modèle Claude, Haiku par défaut
2. Le LLM répond avec JSON structuré contenant une décision
3. Claude Code traite automatiquement la décision

Configuration des hooks de prompt

Définissez type à "prompt" et fournissez une chaîne prompt au lieu d'une command. Utilisez le placeholder $ARGUMENTS pour injecter les données d'entrée JSON du hook dans votre texte de prompt.

Ce hook Stop demande au LLM d'évaluer si toutes les tâches sont complètes avant d'autoriser Claude à terminer :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

Schéma de réponse

Le LLM doit répondre avec JSON contenant :

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

Ce qui se passe sur ok: false dépend de l'événement :

• Stop et SubagentStop : la raison est renvoyée à Claude comme sa prochaine instruction et le tour continue, sauf si la réponse définit également impossible: true, 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 raison de refus apparaît dans le chat comme une ligne d'avertissement. Définissez continueOnBlock: true pour renvoyer la raison à Claude comme l'erreur de l'outil afin qu'il puisse s'ajuster et continuer, équivalent à un hook de commande avec permissionDecision: "deny". Avant v2.1.210, la raison de refus était renvoyée à Claude comme l'erreur de l'outil et le tour continuait
• PostToolUse : par défaut le tour se termine et la raison apparaît dans le chat comme une ligne d'avertissement. Définissez continueOnBlock: true pour renvoyer la raison à Claude et continuer le tour à la place
• PostToolBatch, UserPromptSubmit et UserPromptExpansion : le tour se termine et la raison apparaît comme une ligne d'avertissement. Ces événements terminent le tour sur decision: "block" indépendamment de continue
• PostToolUseFailure et TaskCreated : la raison est retournée à Claude comme une erreur d'outil et le tour continue, indépendamment de continueOnBlock
• TaskCompleted : lorsqu'il se déclenche parce qu'une tâche est marquée comme complétée pendant un tour, la raison est retournée à Claude comme une erreur d'outil et le tour continue, indépendamment de continueOnBlock. Lorsqu'il se déclenche parce qu'un coéquipier s'arrête, il se comporte comme TeammateIdle et arrête le coéquipier par défaut
• TeammateIdle : par défaut le coéquipier s'arrête et la raison apparaît comme une ligne d'avertissement. Définissez continueOnBlock: true pour renvoyer la raison au coéquipier et le garder actif à la place
• PermissionRequest : ok: false n'a aucun effet. Pour refuser une approbation d'un hook, utilisez un hook de commande retournant hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied : ok: false n'a aucun effet car le refus a déjà eu lieu. La seule sortie que cet événement lit est hookSpecificOutput.retry, que les hooks de prompt et d'agent ne peuvent pas définir. Ils s'exécutent sur cet événement, mais leur sortie est ignorée. Utilisez un hook de commande pour retourner retry

Si vous avez besoin d'un contrôle plus fin sur un événement quelconque, utilisez un hook de commande avec les champs par événement décrits dans Contrôle de décision.

Vérifier plusieurs conditions avant d'arrêter

Ce hook Stop utilise un prompt détaillé pour vérifier trois conditions avant d'autoriser Claude à s'arrêter. Les hooks SubagentStop utilisent le même format pour évaluer si un subagent doit s'arrêter. Si le modèle retourne "ok": false parce que la condition n'est pas encore satisfaite, Claude continue de travailler avec la raison fournie comme sa prochaine instruction :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hooks basés sur des agents

Les hooks basés sur des agents (type: "agent") sont comme les hooks basés sur des prompts mais avec accès aux outils multi-tours. Au lieu d'un seul appel LLM, un hook d'agent lance un subagent qui peut lire des fichiers, rechercher du code et inspecter la codebase pour vérifier les conditions. Les hooks d'agent supportent les mêmes événements que les hooks basés sur des prompts, sauf PermissionRequest.

Comment fonctionnent les hooks d'agent

Lorsqu'un hook d'agent se déclenche :

1. Claude Code lance un subagent avec votre prompt et l'entrée JSON du hook
2. Le subagent peut utiliser des outils comme Read, Grep et Glob pour enquêter
3. Après jusqu'à 50 tours, le subagent retourne une décision structurée { "ok": true/false }
4. Claude Code autorise l'action si ok est true. Si ok est false, Claude Code traite le blocage de la même manière qu'un hook de prompt avec continueOnBlock: true sur cet événement, comme indiqué sous Schéma de réponse

Les hooks d'agent sont utiles lorsque la vérification nécessite d'inspecter les fichiers réels ou la sortie des tests, pas seulement d'évaluer les données d'entrée du hook seules.

Configuration des hooks d'agent

Définissez type à "agent" et fournissez une chaîne prompt, en utilisant $ARGUMENTS comme placeholder pour l'entrée JSON du hook. Les champs de configuration sont les mêmes que les hooks de prompt, sauf que les hooks d'agent ont un délai d'expiration par défaut plus long de 60 secondes et aucun champ continueOnBlock.

Le schéma de réponse est { "ok": true } pour autoriser ou { "ok": false, "reason": "..." } pour bloquer. Sur ok: false, Claude Code traite un hook d'agent de la même manière qu'il traite un hook de prompt avec continueOnBlock: true sur le même événement ; les hooks d'agent n'ont pas de champ continueOnBlock et ne supportent pas le champ impossible du hook de prompt.

Ce hook Stop vérifie que tous les tests unitaires réussissent avant d'autoriser Claude à terminer :

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

Exécuter les hooks en arrière-plan

Par défaut, les hooks bloquent l'exécution de Claude jusqu'à ce qu'ils se terminent. Pour les tâches longues comme les déploiements, les suites de tests ou les appels API externes, définissez "async": true pour exécuter le hook en arrière-plan tandis que Claude continue de travailler. Les hooks asynchrones ne peuvent pas bloquer ou contrôler le comportement de Claude : les champs de réponse comme decision, permissionDecision et continue n'ont aucun effet, car l'action qu'ils auraient contrôlée s'est déjà produite.

Configurer un hook asynchrone

Ajoutez "async": true à la configuration d'un hook de commande pour l'exécuter en arrière-plan sans bloquer Claude. Ce champ n'est disponible que sur les hooks type: "command".

Ce hook exécute un script de test après chaque appel d'outil Write. Claude continue de travailler immédiatement tandis que run-tests.sh s'exécute. Lorsque le script se termine, sa sortie est livrée au tour de conversation suivant :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Une fois qu'un hook asynchrone s'exécute en arrière-plan, Claude Code n'applique pas de timeout sur celui-ci. Claude Code applique toujours le timeout sur un hook que vous exécutez avec asyncRewake.

Claude Code livre les résultats d'un hook asynchrone uniquement pendant que la session s'exécute :

• En mode non-interactif avec le drapeau -p, Claude Code tue tout hook asynchrone encore en cours d'exécution lors du démontage et le finalise avec le résultat cancelled
• Si le travail de votre hook doit survivre à une session claude -p, démarrez un processus complètement détaché à partir de celui-ci

Comment les hooks asynchrones s'exécutent

Lorsqu'un hook asynchrone se déclenche, Claude Code démarre le processus du hook et continue immédiatement sans attendre qu'il se termine. Le hook reçoit la même entrée JSON via stdin qu'un hook synchrone.

Après la sortie du processus en arrière-plan, Claude Code livre les champs additionalContext et systemMessage de la réponse JSON du hook à Claude au tour de conversation suivant. Contrairement au systemMessage d'un hook synchrone, aucun de ces champs ne vous est montré.

Claude Code valide que la réponse JSON respecte le même schéma de sortie que les hooks synchrones, et supprime tout champ dont la valeur a le mauvais type, comme un systemMessage qui n'est pas une chaîne de caractères, au lieu de le livrer. Exécutez avec --debug pour voir un avertissement nommant chaque champ supprimé. Avant la v2.1.202, une sortie JSON malformée d'un hook asynchrone pouvait faire planter la session, et le plantage s'est reproduit chaque fois que la session a été reprise.

Les notifications d'achèvement des hooks asynchrones sont supprimées par défaut. Pour les voir, activez le mode verbeux avec Ctrl+O ou démarrez Claude Code avec --verbose.

Exécuter les tests après les modifications de fichiers

Ce hook démarre une suite de tests en arrière-plan chaque fois que Claude écrit un fichier, puis rapporte les résultats à Claude lorsque les tests se terminent. Enregistrez ce script dans .claude/hooks/run-tests-async.sh dans votre projet et rendez-le exécutable avec chmod +x :

#!/bin/bash
# run-tests-async.sh

# Lisez l'entrée du hook depuis stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Exécutez les tests uniquement pour les fichiers source
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Exécutez les tests et rapportez les résultats à Claude via additionalContext
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

Ensuite, ajoutez cette configuration à .claude/settings.json dans la racine de votre projet. Le drapeau async: true permet à Claude de continuer à travailler pendant que les tests s'exécutent :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

Limitations

Les hooks asynchrones ont des contraintes supplémentaires par rapport aux hooks synchrones :

• La sortie du hook est livrée au tour de conversation suivant. Si la session est inactive, la réponse attend jusqu'à la prochaine interaction utilisateur. Exception : un hook asyncRewake qui quitte avec le code 2 réveille Claude immédiatement même lorsque la session est inactive.
• Chaque exécution crée un processus en arrière-plan séparé. Il n'y a pas de déduplication sur plusieurs déclenchements du même hook asynchrone.

Considérations de sécurité

Avertissement

Confiance de l'espace de travail

Claude Code vérifie la confiance de l'espace de travail avant d'exécuter tout hook à partir d'un fichier de paramètres. Ce qui compte comme approuvé dépend du type de session :

• Session interactive : Claude Code retient les hooks de tous les fichiers de paramètres, y compris votre propre ~/.claude/settings.json, jusqu'à ce que vous acceptiez le dialogue de confiance de l'espace de travail pour le dossier, ou pour un répertoire parent dont la confiance s'étend à celui-ci
• Session -p ou SDK : Claude Code n'affiche jamais le dialogue et traite le dossier comme approuvé, donc les hooks validés dans le .claude/settings.json d'un référentiel s'exécutent dans un dossier que vous n'avez jamais approuvé

Avant de scripter claude -p sur un référentiel que vous n'avez pas écrit, examinez ses fichiers de paramètres .claude/, commencez par --bare, ou désactivez les hooks pour cette exécution avec --settings '{"disableAllHooks": true}'. Les hooks de frontmatter dans un sous-agent de projet suivent une règle plus stricte que les hooks de fichier de paramètres. Ce qui s'exécute avant que vous approuviez un dossier énumère chaque type de contenu de référentiel par type de session.

Meilleures pratiques de sécurité

Gardez ces pratiques à l'esprit lors de l'écriture de hooks :

• Validez et nettoyez les entrées : ne faites jamais confiance aux données d'entrée aveuglément
• Citez toujours les variables shell : utilisez "$VAR" pas $VAR
• Bloquez la traversée de répertoires : vérifiez les .. dans les chemins de fichiers
• Utilisez les chemins absolus : spécifiez les chemins complets pour les scripts. En forme exec, utilisez ${CLAUDE_PROJECT_DIR} et le chemin n'a pas besoin de guillemets. En forme shell, enveloppez-le dans des guillemets doubles
• Ignorez les fichiers sensibles : évitez .env, .git/, les clés, etc.

Outil PowerShell sur Windows

Sur Windows, vous pouvez exécuter les hooks individuels dans PowerShell en définissant "shell": "powershell" sur un hook de commande. Claude Code détecte automatiquement pwsh.exe, l'exécutable PowerShell 7 et versions ultérieures, et bascule vers powershell.exe pour Windows PowerShell 5.1.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

Pour référencer la racine du projet à partir d'une commande PowerShell en forme shell, écrivez ${CLAUDE_PROJECT_DIR} ou $env:CLAUDE_PROJECT_DIR. À partir de la v2.1.198, Claude Code réécrit les placeholders ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} et ${CLAUDE_PLUGIN_DATA} dans une commande PowerShell en forme shell vers la forme ${env:NAME} de PowerShell, que le hook soit défini dans settings.json, un plugin ou une skill. PowerShell résout ensuite la valeur à partir de l'environnement exporté après l'analyse, donc le placeholder fonctionne à l'intérieur des chaînes entre guillemets doubles mais pas à l'intérieur des chaînes entre guillemets simples, où PowerShell n'étend jamais les variables.

Avant la v2.1.198, cette réécriture s'appliquait uniquement aux hooks de plugin. Sur les versions antérieures, un hook settings.json a besoin de la forme $env: ou de la forme exec, où ${CLAUDE_PROJECT_DIR} est substitué dans chaque élément args indépendamment de l'endroit où le hook est défini.

N'écrivez pas l'orthographe nue $CLAUDE_PROJECT_DIR dans un hook PowerShell. PowerShell l'analyse comme une variable locale indéfinie et la résout en $null, ce qui laisse le chemin du script sans son préfixe de racine de projet. Claude Code ne réécrit pas cette forme ; il enregistre plutôt un avertissement dans le journal de débogage.

L'exemple ci-dessous montre un hook settings.json qui exécute un script de projet avec la forme $env:, qui fonctionne sur chaque version :

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

Déboguer les hooks

Les détails d'exécution des hooks sont écrits dans le fichier journal de débogage. Démarrez Claude Code avec claude --debug-file <path> pour écrire le journal à un emplacement connu, ou exécutez claude --debug et lisez le journal à ~/.claude/debug/<session-id>.txt. Le drapeau --debug n'imprime pas sur le terminal.

Par exemple, un hook PostToolUse sur Write dont la commande affiche hook-ran produit des entrées comme :

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

Pour plus de détails granulaires sur la correspondance des hooks, définissez CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose pour voir des lignes de journal supplémentaires telles que les comptes de matcher de hook et la correspondance de requête.

Pour dépanner les problèmes courants comme les hooks qui ne se déclenchent pas, les hooks Stop qui continuent à bloquer, ou les erreurs de configuration, consultez Limitations et dépannage dans le guide. Pour une procédure de diagnostic plus large couvrant /context, /doctor et la précédence des paramètres, consultez Déboguer votre configuration.