AskUserQuestion et ExitPlanMode nécessitent une interaction utilisateur et bloquent normalement en mode non-interactif avec le drapeau -p. 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 afin 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 dialogue d'approbation avec "allow", avec ou sans updatedInput, car Claude Code ne peut pas confirmer que le hook a collecté l'interaction dont l'outil a besoin.

Différer un appel d'outil pour plus tard

"defer" est pour les intégrations qui exécutent claude -p en tant que sous-processus et lisent sa sortie JSON, comme une application Agent SDK ou une interface utilisateur personnalisée construite sur Claude Code. Il 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. Le cycle 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>. 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, suivant les règles du balayage de rétention. Si la réponse n'est pas prête lorsque vous reprenez, le hook peut retourner "defer" à nouveau et le processus quitte de la même manière. Le processus appelant contrôle quand casser la boucle en retournant finalement "allow" ou "deny" du hook.

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

Si l'outil différé n'est plus disponible lorsque vous reprenez, le processus quitte avec stop_reason: "tool_deferred_unavailable" et is_error: true avant que le hook ne se déclenche. Cela se produit lorsqu'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 afin que vous puissiez identifier quel outil a disparu.

PermissionRequest

S'exécute lorsque Claude Code est sur le point de vous demander la permission d'utiliser un outil. Dans les sessions qui ne peuvent pas afficher un dialogue, comme les subagents 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 autoriser ou refuser au nom de l'utilisateur.

Utilisez cet événement lorsque 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 le dialogue ait attendu environ six secondes.

Claude Code n'exécute pas les hooks PermissionRequest pour la demande réseau d'une commande en sandbox. Pour obtenir un signal pour ce dialogue, 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. Un tableau optionnel permission_suggestions contient les entrées de mise à jour de permission que Claude Code suggère pour cette demande, comme l'ajout d'une règle d'autorisation ou la modification du mode de permission.

Le dialogue de permission construit ses options « toujours autoriser » à partir de ces suggestions, mais le tableau n'est pas une liste exacte des options que vous voyez. Le dialogue peut retenir une option dont la suggestion reste dans le tableau, par exemple lorsque allowManagedPermissionRulesOnly masque les options d'enregistrement de règles. Il peut également offrir des options qui n'ont pas d'entrée de suggestion, comme Oui, et basculer 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 lorsque Claude Code est sur le point de vous demander la permission, ou lorsqu'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 autoriser 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 demande.

{
  "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ù la modification est écrite.

Le champ destination sur chaque entrée détermine si la modification 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 lorsque 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 lorsqu'un fichier spécifique change sur le disque, quel que soit ce qui l'a écrit, utilisez FileChanged. Claude Code n'exécute pas un hook PostToolUse correspondant à Edit|Write lorsqu'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 des barres obliques inverses sur Windows.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  },
  "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 note courte 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 des outils 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 indique 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 de l'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 par rapport à vos propres messages dans la conversation
• Rappels Agent SDK en processus : lorsqu'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é. Lorsque 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, car 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 telles que les lectures de fichiers et les recherches. Claude Code rejette une note attachée à l'un de ces appels
• Interaction avec les réécritures : lorsque la note décrit la sortie que vous remplacez avec updatedToolOutput, retournez les deux champs dans la même réponse du 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 lorsqu'un autre hook réécrit la sortie

PostToolUseFailure

S'exécute lorsqu'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 défaillances, 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 au niveau supérieur. 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 échoué de l'outil. Son format varie selon l'outil et l'échec. Basez 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 a fonctionné et s'est terminée produit une première ligne Exit code N, puis toute sortie que la commande a produite en tant qu'un bloc avec stdout et stderr entrelacés
• Une charge utile peut également porter un message d'échec brut sans ligne de code de sortie, lorsque Claude Code n'a pas pu démarrer le processus shell lui-même
• Claude Code tronque au milieu les chaînes plus longues que 10 000 caractères autour d'un marqueur ... [N characters truncated] ..., et peut insérer ses propres lignes, comme Command timed out after 2m 0s

Contrôle de décision PostToolUseFailure

Les hooks PostToolUseFailure peuvent fournir du contexte à Claude après l'échec d'un 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 une batch ait été résolu, avant que Claude Code n'envoie la demande suivante au modèle. PostToolUse se déclenche une fois par outil, ce qui signifie qu'il se déclenche simultanément lorsque Claude fait des appels d'outil parallèles. PostToolBatch se déclenche exactement une fois avec la batch complète, donc c'est le bon endroit pour injecter du contexte qui dépend de l'ensemble des outils qui ont fonctionné plutôt que sur un seul outil. 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 la batch :

{
  "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 blocs 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 volumineuses, 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 agentique avant l'appel du modèle suivant. Le message de blocage provient du JSON reason ou stopReason, ou de stderr sur exit 2. Vous le voyez comme un avertissement dans la transcription, et il reste dans la conversation, donc Claude le voit lorsque la conversation continue.

PermissionDenied

S'exécute lorsque le mode auto refuse un appel d'outil, y compris lorsqu'il refuse sans un verdict du classificateur parce qu'une vérification de sécurité séparée du mode auto a refusé la demande 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 lorsque vous refusez manuellement un dialogue de permission, lorsqu'un hook PreToolUse bloque un appel ou lorsqu'une règle deny correspond. Utilisez-le pour enregistrer les refus, ajuster la configuration ou indiquer 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.

{
  "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": "Blocked by classifier"
}

Contrôle de décision PermissionDenied

Les hooks PermissionDenied peuvent indiquer 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
  }
}

Lorsque retry est true, Claude Code ajoute un message à la conversation indiquant au modèle qu'il peut réessayer l'appel d'outil. Le refus lui-même n'est pas inversé. 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 lorsque le classificateur n'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 demande du classificateur. Pour ces refus, Claude Code indique déjà au modèle dans le message de rejet s'il faut réessayer plus tard ou continuer.

Notification

S'exécute lorsque 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 demande réseau d'une commande en sandbox nécessite Claude Code v2.1.246 ou ultérieur.

agent_needs_input pour une 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 demandes de permission au rappel canUseTool du SDK Agent, ce qui est la façon dont 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 lorsque Claude a besoin d'approbation de permission et une notification différente lorsque 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 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 tels que le transfert de la notification vers un service externe.

SubagentStart

S'exécute lorsqu'un subagent Claude Code est lancé via l'outil Agent. 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 subagents personnalisés, c'est le champ name du frontmatter de l'agent, pas le nom du fichier.

Pour les subagents fournis par un plugin, l'identifiant de type d'agent est l'identifiant limité au plugin comme my-plugin:reviewer, pas le nom brut du frontmatter. Le deux-points place un nom limité au 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 subagent et agent_type avec le nom de l'agent que 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 subagent, mais ils peuvent injecter du contexte dans le subagent. 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"
  }
}

SubagentStop

S'exécute lorsqu'un subagent Claude Code a terminé sa réponse. 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 subagent stockée dans un dossier subagents/ imbriqué. Le champ last_assistant_message contient le contenu textuel de la réponse finale du subagent, donc les hooks peuvent y accéder sans analyser le fichier de transcription.

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

{
  "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 subagent en cours d'exécution. Retourner decision: "block" avec une reason garde le subagent en cours d'exécution et livre reason au subagent comme sa prochaine instruction. Un hook qui bloque en quittant 2 livre son message stderr de la même manière. Pour injecter du contexte dans la session parent après qu'un subagent retourne, utilisez un hook PostToolUse sur l'outil Agent à la place.

TaskCreated

S'exécute lorsqu'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âches 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 lorsqu'une tâche est marquée comme complétée. Cela se déclenche dans deux situations : lorsqu'un agent marque explicitement une tâche comme complétée via l'outil TaskUpdate, ou lorsqu'un coéquipier d'une équipe d'agents termine son tour avec des tâches en cours. Utilisez ceci pour appliquer les critères d'achèvement comme passer les tests ou les vérifications de lint avant qu'une tâche ne 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 l'achèvement de la 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": "..."} : arrête complètement le coéquipier, correspondant au comportement du hook Stop. Le stopReason est affiché à l'utilisateur.

Cet exemple exécute les tests et bloque l'achèvement de la tâche s'ils échouent :

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

# Exécutez la suite de tests
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 lorsque l'agent Claude Code principal a terminé sa réponse. Ne s'exécute pas si l'arrêt s'est produit en raison d'une interruption utilisateur. Les erreurs API déclenchent StopFailure à la place.

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 lorsque Claude Code continue déjà en raison d'un hook stop. Vérifiez cette valeur ou traitez la transcription pour empêcher 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 la lecture à haute voix ou les hooks de notification, utilisez ce champ plutôt que de relire 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 du réveil du travail en arrière-plan ». Les deux tableaux sont présents lorsque le registre des tâches est accessible et sont vides lorsque 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é limité à 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 manière que reason : Claude reçoit le message stderr comme l'explication pour pourquoi il doit continuer.

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

Utilisez additionalContext lorsque 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 à travers 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 affichée :

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

StopFailure

S'exécute à la place de Stop lorsque le tour se termine en raison d'une erreur API. Claude Code ignore la sortie du hook et le code de sortie, à part terminalSequence. Utilisez ceci pour enregistrer les défaillances, envoyer des alertes ou prendre des mesures de récupération lorsque Claude ne peut pas terminer une réponse en raison de limites de débit, de 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, optionnellement error_details et optionnellement 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 journalisation uniquement.

TeammateIdle

S'exécute lorsqu'un coéquipier d'une équipe d'agents est sur le point de devenir inactif après avoir terminé son tour. Utilisez ceci pour appliquer des portes de qualité avant qu'un coéquipier ne cesse de travailler, comme exiger des vérifications de lint réussies 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 complètement le coéquipier, correspondant au comportement du hook Stop. Le stopReason est affiché à l'utilisateur.

Cet exemple vérifie qu'un artefact de construction existe avant d'autoriser un coéquipier à 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 lorsqu'un fichier de configuration change pendant une session. Utilisez ceci pour auditer les modifications 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 lorsqu'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 lorsque managed-settings.json ou un fichier dans managed-settings.d/ change. Il applique les paramètres gérés par le serveur et les modifications aux préférences gérées macOS ou à la politique de registre Windows sans les exécuter. Sur WSL avec wslInheritsWindowsSettings, il applique également un fichier de paramètres gérés Windows modifié côté sur son sondage de politique sans les exécuter.

Le matcher filtre sur la source de configuration :

Cet exemple enregistre toutes les modifications 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 vers le 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 modifications de configuration de prendre effet. Utilisez le code de sortie 2 ou une decision JSON pour empêcher la modification. Lorsqu'elle est bloquée, 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 modifications policy_settings ne peuvent pas être bloquées. Les hooks se déclenchent toujours pour les sources policy_settings, vous pouvez donc les utiliser pour la journalisation d'audit, 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 lorsque 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 à vous ou à Claude, que vous bloquez avec reason ou avec stderr sur exit 2. Claude Code écrit uniquement une ligne au journal de débogage.

CwdChanged

S'exécute lorsque le répertoire de travail change pendant une session, par exemple lorsque 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'associe 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 pour la session, tout comme dans les hooks SessionStart.

CwdChanged ne supporte pas les matchers et se déclenche à chaque changement de répertoire.

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 fichiers 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 affiche le systemMessage comme une brève notification de terminal. Le message n'atteint pas le flux de messages SDK.

DirectoryAdded

S'exécute après que vous ajoutiez un répertoire de travail en milieu de session avec la commande /add-dir, ou après qu'un client SDK en ajoute un avec la demande 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 lorsque :

• 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 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 lorsque 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é lorsque 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 l'afficher. Un nombre de hooks échoués apparaît dans la transcription. La sortie d'échec complète va au journal de débogage
• register_repo_root : Claude Code écrit la sortie systemMessage et la sortie d'échec au journal de débogage uniquement

FileChanged

S'exécute lorsqu'un fichier surveillé change sur le disque. Claude Code détecte les modifications 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 lorsque 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 : lorsqu'un fichier surveillé change, la même valeur filtre quels groupes de hook s'exécutent en utilisant les règles de matcher standard par rapport au basename 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é depuis le 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 lorsqu'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 des 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 lorsque 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 lorsqu'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 un nom de fichier littéral *.

Les hooks FileChanged ont accès à CLAUDE_ENV_FILE. Les variables écrites dans ce fichier persistent dans les commandes Bash suivantes pour la session, tout comme dans les hooks SessionStart.

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 fichiers 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 affiche le systemMessage comme une brève notification de terminal. Le message n'atteint pas le flux de messages SDK.

WorktreeCreate

S'exécute lorsqu'un worktree est en cours de création, soit à partir de claude --worktree, soit à partir d'un subagent utilisant isolation: "worktree", soit 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 du worktree créé. Claude Code utilise ce chemin comme répertoire de travail pour la session isolée. Consultez 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 depuis 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 chemin du worktree. Redirigez toute autre sortie du hook vers stderr afin 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 généré automatiquement, 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 autoriser/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 du 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 aucun chemin, la création du worktree échoue avec une erreur.

Claude Code résout un chemin relatif par rapport au répertoire dans lequel le hook s'est exécuté, en effondrant tout segment . ou .. dans celui-ci. Si le chemin résultant n'est pas un répertoire dans lequel 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 tout chemin qui passe par un symlink en dessous de la racine du référentiel, parce qu'un symlink engagé au référentiel pourrait rediriger le worktree en dehors de celui-ci. L'erreur nomme le composant rejeté. Retournez un chemin normalisé qui ne passe pas par un symlink à 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 lorsqu'un worktree est en cours de suppression. Cela se produit lorsque :

• vous quittez une session --worktree et choisissez de la supprimer
• un subagent 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 lui, le répertoire du worktree est laissé sur le disque.

Claude Code rejette les champs de sortie JSON d'un hook WorktreeRemove, tels que 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 symlink 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 lorsque 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 transmet le chemin que WorktreeCreate a retourné 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"
}

Les hooks WorktreeRemove n'ont pas de contrôle de décision. Ils ne peuvent pas bloquer la suppression du worktree mais peuvent effectuer des tâches de nettoyage comme supprimer l'état du contrôle de version ou archiver les modifications. Les défaillances des hooks sont enregistrées en mode debug uniquement.

PreCompact

S'exécute avant que Claude Code ne 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 affiché à l'utilisateur. Vous pouvez également bloquer en retournant JSON avec "decision": "block".

Le blocage de la compaction automatique a des effets différents selon le moment où il 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 remonte et la demande 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 transmet dans /compact et est null lorsqu'il ne transmet 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 complète une opération de compaction. Utilisez cet événement pour réagir au nouvel état compacté, 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 des tâches de suivi.

PreModelSwitch

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

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

• /model <name> et le sélecteur /model
• Le sélecteur de modèle Option+P ou Alt+P
• Le paramètre Model dans /config
• L'activation du mode rapide lorsque cela change le modèle de la session
• Une demande set_model, ou un changement de modèle dans une demande 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 seul, comme un repli de modèle automatique ou la restauration du modèle lorsque vous reprenez une session. Ces changements atteignent PostModelSwitch uniquement.

Claude Code compare le matcher par rapport au nom canonique du modèle vers lequel la session bascule, 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 nom canonique unique auquel ils se résolvent, donc claude-opus-5 couvre chaque orthographe d'Opus 5.

Lorsque 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 doit donc vérifier to_model de son entrée plutôt que de compter uniquement sur le matcher.

É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 signale 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 du tableau ci-dessous. Les cinq derniers décrivent le coût de l'envoi de la conversation au nouveau modèle, donc un hook peut afficher ce chiffre avant le changement.

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" au niveau supérieur 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 afficher le dialogue "ask". Sur chaque autre surface, y compris le mode non-interactif avec le drapeau -p, /config et les demandes 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?"
  }
}

Lorsque plusieurs hooks PreModelSwitch retournent des décisions différentes, la précédence est deny > ask > allow.

Claude Code affiche tout systemMessage que votre hook retourne indépendamment de la décision, donc un hook de rapport de coûts peut 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 valeurs par défaut prompt et agent ne s'appliquent pas.

Un hook qui quitte avec un code autre que 0 ou 2 et n'imprime aucune décision JSON ne bloque pas : Claude Code affiche 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 restaurant le modèle lorsque vous reprenez une session

Claude Code n'exécute pas les hooks PostModelSwitch lorsqu'un modèle d'une chaîne de modèles 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 par rapport au nom canonique du modèle vers lequel la session a basculé.

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, basculez 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 seul, et "resume" pour le modèle restauré lorsque vous reprenez une session.

requested_model est null lorsque source est "auto". Lorsque 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 stdout en texte brut du hook sur exit 0, ou additionalContext de la sortie JSON, et le livre à Claude avec la demande 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 terminé dans les cinq secondes après que vous ayez envoyé la demande suivante, Claude Code envoie cette demande sans la sortie et l'attache à la demande suivante à la place. Si le modèle change plusieurs fois avant la demande suivante, Claude Code livre uniquement la sortie pour le changement vers le modèle cible final.

SessionEnd

S'exécute lorsqu'une session Claude Code se termine. Utile pour les tâches de nettoyage, la journalisation des statistiques de session ou l'enregistrement de l'état de 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. Consultez le tableau des raisons 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 session mais peuvent effectuer des tâches de nettoyage. Claude Code rejette leurs champs de sortie JSON, tels que systemMessage.

Les hooks SessionEnd ont un délai d'expiration par défaut de 1,5 secondes. Cela s'applique à la sortie de session, à /clear et au basculement de sessions via /resume interactif. Si un hook a besoin de plus de temps, définissez un timeout par hook dans la configuration du hook. Le budget global est automatiquement augmenté au délai d'expiration par hook le plus élevé configuré dans les fichiers de paramètres, jusqu'à 60 secondes. Les délais d'expiration définis sur les hooks fournis par les plugins ne relèvent pas le budget. Pour remplacer le budget explicitement, définissez la variable d'environnement CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS en millisecondes.

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Elicitation

S'exécute lorsqu'un serveur MCP demande une entrée utilisateur en milieu de tâche. Par défaut, Claude Code affiche un dialogue interactif pour que l'utilisateur réponde. Les hooks peuvent intercepter cette demande et répondre par programmation, en ignorant complètement 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/...",
  "permission_mode": "default",
  "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 (authentification basée sur navigateur) :

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "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 afficher 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épond à 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/...",
  "permission_mode": "default",
  "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 en 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
• PermissionRequest
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

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. 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.

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. 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 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, y compris les hooks qui ont correspondu, leurs codes de sortie et la sortie complète stdout et stderr, 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:
hook-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.