En mode non interactif avec le flag -p, Claude Code ne propose AskUserQuestion et ExitPlanMode que lorsque l'exécution dispose d'un hôte de permissions pour recevoir la demande, comme un callback canUseTool de l'Agent SDK. Ces outils nécessitent une interaction de l'utilisateur. Renvoyer permissionDecision: "allow" avec updatedInput satisfait cette exigence : le hook lit l'entrée de l'outil depuis stdin, recueille la réponse via votre propre interface et la renvoie dans updatedInput afin que l'outil s'exécute sans demande. Renvoyer "allow" seul ne suffit pas pour ces outils. Pour AskUserQuestion, renvoyez le tableau questions d'origine et ajoutez un objet answers associant le texte de chaque question à la réponse choisie.

Un outil MCP que son serveur marque avec _meta["anthropic/requiresUserInteraction"] est plus strict : un hook ne peut pas ignorer sa demande d'approbation avec "allow", avec ou sans updatedInput, car Claude Code ne peut pas confirmer que le hook a recueilli l'interaction dont l'outil a besoin.

Différer un appel d'outil

"defer" est destiné aux intégrations qui exécutent claude -p comme sous-processus et lisent sa sortie JSON, comme une application Agent SDK ou une interface personnalisée construite sur Claude Code. Il permet à ce processus appelant de mettre Claude en pause sur un appel d'outil, de recueillir une saisie via sa propre interface, puis de reprendre là où il s'était arrêté. Claude Code ne respecte cette valeur qu'en mode non interactif avec le flag -p. Dans les sessions interactives, il consigne 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 y répondre. Une exécution -p ne propose AskUserQuestion que lorsqu'elle dispose d'un hôte de permissions, comme un outil MCP que vous transmettez avec --permission-prompt-tool ; démarrez donc l'exécution avec l'un d'eux. L'aller-retour fonctionne ainsi :

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

Le champ deferred_tool_use contient l'id, le name et l'input de l'outil. L'input correspond aux 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 ni délai d'expiration ni limite de nouvelles tentatives. La session reste sur le disque jusqu'à ce que vous la repreniez, sous réserve du nettoyage de rétention cleanupPeriodDays, qui supprime les fichiers de session après 30 jours par défaut, conformément aux règles du nettoyage de rétention. Si la réponse n'est pas prête lorsque vous reprenez, le hook peut renvoyer "defer" à nouveau et le processus se termine de la même manière. Le processus appelant décide quand sortir de la boucle en renvoyant finalement "allow" ou "deny" depuis le hook.

"defer" ne fonctionne que lorsque Claude effectue un seul appel d'outil dans le tour. Si Claude effectue plusieurs appels d'outils à la fois, "defer" est ignoré avec un avertissement et l'outil suit le flux de permission normal. Cette 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 lorsque vous reprenez, le processus se termine 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 fournissait l'outil n'est pas connecté pour la session reprise. Le payload deferred_tool_use est tout de même inclus afin que vous puissiez identifier l'outil manquant.

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 de demande, comme les sous-agents en arrière-plan en mode non interactif, Claude Code exécute tout de même ces hooks, et si aucun hook ne renvoie de décision, il refuse l'appel d'outil. Pour un appel qui atteint un --permission-prompt-tool ou le callback canUseTool de l'Agent SDK, les hooks s'exécutent en parallèle de votre hôte, et la première décision prise s'applique. Utilisez le contrôle de décision de 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 n'exécute un hook Notification de type permission_prompt qu'après que la demande a attendu environ six secondes.

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

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

Entrée de 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 facultatif permission_suggestions contient les mises à jour de permissions que Claude Code suggère pour cette demande, comme l'ajout d'une règle d'autorisation ou le changement du mode de permission.

Le tableau permission_suggestions n'est pas une liste exacte des options que vous voyez, car chaque boîte de dialogue de permission construit ses propres options. Certaines boîtes de dialogue, comme celle des modifications de fichiers, ne lisent pas du tout le tableau et dérivent leurs options de la demande elle-même. Une boîte de dialogue qui le lit peut tout de même masquer une option dont la suggestion reste dans le tableau, par exemple lorsque allowManagedPermissionRulesOnly masque les options d'enregistrement de règles. Elle peut également proposer des options sans entrée de suggestion, comme Yes, and switch to auto mode, qui change directement le mode de permission plutôt que de passer par une mise à jour de permissions.

Les hooks PreToolUse s'exécutent avant chaque appel d'outil, qu'il nécessite une permission ou non. Les hooks PermissionRequest ne s'exécutent que lorsque Claude Code est sur le point de vous demander la permission, ou lorsqu'il refuserait autrement automatiquement un appel qui ne peut pas afficher de demande. Aucun des deux événements 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 de PermissionRequest

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

Un hook qui se termine avec le code 2 sans objet decision laisse le flux de permission inchangé, et sa sortie stderr est ignorée. 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 permissions

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 possède un type qui détermine ses autres champs, et une destination qui contrôle où la modification est écrite.

Le champ destination de chaque entrée détermine si la modification reste en mémoire ou est conservée 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 s'est terminé avec succès.

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

Élargissez la correspondance lorsque le nom de l'outil n'est pas le bon filtre :

• Pour exécuter un hook après la réussite de n'importe quel outil, omettez le matcher ou définissez-le sur "*". Votre hook peut alors découvrir lui-même ce qui a changé, par exemple en exécutant git status --porcelain, qui liste aussi les fichiers non suivis que git diff ignore. Pour les appels d'outils 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 extérieur à 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 renvoyé. Le schéma exact de ces deux champs dépend de l'outil. Les chemins tool_input des outils de fichiers arrivent dans le même format que pour PreToolUse : toujours absolus, avec les séparateurs natifs de la plateforme, donc des barres obliques inverses sous Windows. Pour un outil MCP, l'entrée contient é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 un retour à 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 renvoyer ces champs propres à 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 classifieur du mode auto

Renvoyez classifierContext pour envoyer une courte note sur le résultat de l'appel d'outil au classifieur du mode auto plutôt qu'à Claude. Le classifieur ne reçoit jamais les résultats des outils eux-mêmes, ce champ est donc le moyen prévu pour lui indiquer quelque chose sur ce qu'un appel a renvoyé avant qu'il n'examine les actions suivantes. Ce champ nécessite Claude Code v2.1.236 ou ultérieur.

L'exemple ci-dessous indique au classifieur 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 classifieur accorde à la note dépend de l'endroit où vous avez configuré le hook :

• Hooks configurés dans Claude Code : pour les hooks provenant des fichiers de paramètres, des plugins, des skills et du frontmatter des agents, le classifieur traite la note comme un contexte non vérifié fourni par l'application. La note n'établit jamais l'intention de l'utilisateur, et si elle affirme que vous avez approuvé ou demandé quelque chose, le classifieur vérifie cette affirmation par rapport à vos propres messages dans la conversation
• Callbacks Agent SDK en processus : lorsqu'une application intégrant Claude Code enregistre le hook comme callback du SDK TypeScript et renvoie la note pendant la session en cours, le classifieur peut considérer une déclaration de l'utilisateur relayée dans la note comme une intention de l'utilisateur. Une telle déclaration peut satisfaire une exigence de consentement que le classifieur 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 la reprise d'une session, Claude Code traite les notes restaurées comme un contexte non vérifié. Lorsque des hooks des deux groupes annotent le même appel, le classifieur traite la note combinée comme non vérifiée

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

• Longueur : Claude Code plafonne les notes d'un appel d'outil à 2 000 caractères et tronque le reste. Ce plafond est partagé entre tous les hooks qui répondent à 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 a enregistré le résultat de l'outil
• Appels que le classifieur n'enregistre pas : la transcription du classifieur omet les consultations en lecture seule comme les lectures de fichiers et les recherches. Claude Code supprime une note attachée à l'un de ces appels
• Interaction avec les réécritures : lorsque la note décrit une sortie que vous remplacez avec updatedToolOutput, renvoyez les deux champs dans la même réponse de hook. Claude Code abandonne la note si cette réécriture est rejetée ou si la réécriture d'un autre hook la remplace. Claude Code transmet une note que vous renvoyez sans réécriture même lorsqu'un autre hook réécrit la sortie

PostToolUseFailure

S'exécute lorsqu'un outil dont l'exécution a commencé échoue : l'outil a levé une erreur, ou un outil MCP a renvoyé un résultat d'erreur. Utilisez-le pour journaliser les échecs, envoyer des alertes ou fournir un retour correctif à Claude.

Correspond au nom de l'outil, avec les 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 des informations sur l'erreur sous forme de champs de premier niveau. Pour un outil MCP, ils reçoivent également l'objet mcp_server. Par exemple, une commande npm test en échec pourrait transmettre :

{
  "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 en échec. Son format varie selon l'outil et le type d'é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, et non comme un format stable.

• Pour Bash et PowerShell, une commande qui s'est exécutée puis terminée produit une première ligne Exit code N, suivie de toute la sortie produite par la commande en un seul bloc, avec stdout et stderr entremêlés
• Un payload peut aussi contenir un simple message d'échec sans ligne de code de sortie, lorsque Claude Code n'a pas pu démarrer le processus shell lui-même
• Claude Code tronque le milieu des longues chaînes autour d'un marqueur ... [N characters truncated] ..., et peut insérer ses propres lignes, comme Command timed out after 2m 0s

Contrôle de décision PostToolUseFailure

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 renvoyer ces champs propres à l'événement :

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

PostToolBatch

S'exécute une fois après la résolution de tous les appels d'outils d'un lot, avant que Claude Code n'envoie la requête suivante au modèle. PostToolUse se déclenche une fois par outil, ce qui signifie qu'il se déclenche de manière concurrente lorsque Claude effectue des appels d'outils parallèles. PostToolBatch se déclenche exactement une fois avec le lot complet ; c'est donc le bon endroit pour injecter un contexte qui dépend de l'ensemble des outils exécutés plutôt que d'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 du 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\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

tool_response contient le même contenu que celui 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 tel que l'outil l'a émis. Pour Read, cela signifie du texte préfixé par des numéros de ligne plutôt que le contenu brut du fichier. Les réponses peuvent être volumineuses ; n'analysez donc que 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 renvoyer ces champs propres à l'événement :

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

Renvoyer decision: "block" ou continue: false arrête la boucle agentique avant le prochain appel au modèle. Le message de blocage provient de la reason ou du stopReason JSON, ou de stderr avec le code de sortie 2. Vous le voyez comme un avertissement dans la transcription, et il reste dans la conversation, de sorte que Claude le voit lorsque la conversation reprend.

PermissionDenied

S'exécute lorsque le mode auto refuse un appel d'outil, y compris lorsqu'il refuse sans verdict du classifieur parce qu'un contrôle de sécurité distinct du mode auto a refusé la requête du classifieur lui-même ou que sa réponse n'a pas pu être analysée. Ce hook ne se déclenche qu'en mode auto : il ne s'exécute pas lorsque vous refusez manuellement une boîte de dialogue de permission, lorsqu'un hook PreToolUse bloque un appel, ou lorsqu'une règle deny correspond. Utilisez-le pour journaliser 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, avec les 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 indiquer au modèle qu'il peut réessayer l'appel d'outil refusé. Renvoyez un objet JSON avec hookSpecificOutput.retry défini sur true :

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

Lorsque retry vaut true, Claude Code ajoute un message à la conversation indiquant au modèle qu'il peut réessayer l'appel d'outil. Claude Code n'annule pas le refus lui-même. Si votre hook ne renvoie pas de JSON, ou renvoie retry: false, le refus est maintenu et le modèle reçoit le message de rejet d'origine.

Claude Code ignore retry: true lorsque le classifieur n'a produit aucun verdict sur l'action : sa réponse n'a pas pu être analysée, ou un contrôle de sécurité distinct du mode auto a refusé la requête du classifieur lui-même. Pour ces refus, Claude Code indique déjà au modèle, dans le message de rejet, s'il doit réessayer plus tard ou passer à autre chose.

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 lorsque les notifications de bureau sont désactivées : le paramètre preferredNotifChannel, y compris notifications_disabled, ne modifie que la manière dont vous êtes alerté, et non l'exécution de votre hook.

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 du terminal d'un coéquipier nécessite Claude Code v2.1.248 ou ultérieur.

Claude Code minute permission_prompt différemment dans les sessions où il envoie les demandes de permission au callback canUseTool de l'Agent SDK, ce qui est la façon dont Claude Desktop et l'extension VS Code hébergent Claude Code :

• Attendez-vous à permission_prompt environ six secondes après que Claude a demandé 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 sur 1 pour désactiver permission_prompt dans ces sessions.

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

Utilisez des matchers distincts pour exécuter différents gestionnaires selon le type de notification. Cette configuration déclenche un script d'alerte propre aux permissions lorsque Claude a besoin d'une approbation de permission, et une notification différente lorsque Claude est 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 la notification, un title facultatif 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 ni bloquer ni modifier les notifications. Claude Code supprime leurs champs systemMessage et continue, mais émet toujours terminalSequence, sur lequel repose l'exemple de notification de bureau. Les hooks Notification sont destinés aux effets de bord, comme la transmission de la notification à un service externe.

SubagentStart

S'exécute lorsque Claude lance un sous-agent avec l'outil Agent, lorsque Claude reprend un sous-agent, et chaque fois qu'un coéquipier en processus d'une équipe d'agents traite un nouveau message. Prend en charge les matchers pour filtrer par nom de type d'agent. Pour les agents intégrés, il s'agit du nom de l'agent, comme general-purpose, Explore ou Plan. Pour les sous-agents personnalisés, il s'agit du champ name du frontmatter de l'agent, et non du nom de fichier.

Pour les sous-agents fournis par un plugin, le type d'agent est l'identifiant propre au plugin, comme my-plugin:reviewer, et non le simple nom du frontmatter. Les deux-points font passer un nom propre au plugin par le traitement des expressions régulières ; ancrez donc 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 d'un 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 renvoyer :

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

Lorsque le hook s'exécute à nouveau pour le même sous-agent, Claude Code n'injecte le contexte renvoyé que si le contexte du sous-agent ne contient pas déjà la copie d'une exécution précédente. La copie injectée au lancement reste en place, ce qui préserve le cache de prompt du sous-agent. Après que la compaction automatique a supprimé cette copie, Claude Code injecte à nouveau le contexte de l'exécution suivante.

SubagentStop

S'exécute lorsqu'un sous-agent Claude Code a fini de répondre. Correspond au type d'agent, avec les 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 par 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, afin que les hooks puissent y accéder sans analyser le fichier de transcription.

Tous les événements SubagentStop ne proviennent pas d'un sous-agent lancé par Claude. Claude Code exécute également des agents internes pour certaines de ses propres fonctionnalités, comme les suggestions de prompt et les questions annexes /btw, et SubagentStop se déclenche aussi lorsque l'un d'eux se termine. Pour ces événements, agent_type est le nom de l'agent sous lequel la session elle-même s'exécute, tel que défini avec --agent ou le paramètre agent, et une chaîne vide lorsque la session s'exécute sans agent.

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

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

Les hooks SubagentStop reçoivent également les tableaux background_tasks et session_crons décrits dans Entrée Stop. Ces deux tableaux portent sur la session parente, et non sur le 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 sur "SubagentStop", pour un retour non lié à une erreur qui maintient le sous-agent en cours d'exécution. Renvoyer decision: "block" avec une reason maintient le sous-agent en cours d'exécution et lui transmet reason comme instruction suivante. Un hook qui bloque en se terminant avec le code 2 transmet son message stderr de la même manière. Pour injecter du contexte dans la session parente après le retour d'un sous-agent, utilisez plutôt un hook PostToolUse sur l'outil Agent.

TaskCreated

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

Les hooks TaskCreated ne prennent pas en charge 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, de manière facultative, 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 manières. Dans les deux cas, Claude Code supprime la tâche et renvoie votre message à Claude comme erreur de l'outil. Claude Code ignore continue: false pour cet événement et Claude continue de travailler.

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

Cet exemple bloque les tâches dont le sujet ne respecte 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 en cours de marquage comme terminée. Cela se déclenche dans deux situations : lorsqu'un agent marque explicitement une tâche comme terminé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-le pour imposer des critères d'achèvement, comme la réussite des tests ou des vérifications de lint, avant qu'une tâche puisse être clôturée.

Les hooks TaskCompleted ne prennent pas en charge 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, de manière facultative, 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 offrent deux manières de contrôler l'achèvement des tâches :

• Code de sortie 2 : la tâche n'est pas marquée comme terminée et le message stderr est renvoyé au modèle comme retour.
• JSON {"continue": false, "stopReason": "..."} : lorsque l'événement a été déclenché par un coéquipier terminant son tour, arrête complètement le coéquipier, comme le comportement du hook Stop. Le stopReason est affiché à l'utilisateur. Lorsque l'événement a été déclenché par l'outil TaskUpdate, Claude Code ignore continue: false ; le code de sortie 2 bloque toujours l'achèvement.

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')

# 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 lorsque l'agent principal de Claude Code a fini de répondre. Ne s'exécute pas si l'arrêt est dû à une interruption de l'utilisateur. Les erreurs d'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 vaut true lorsque Claude Code poursuit déjà à la suite 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 applique un plafond de 8 poursuites consécutives : après que les hooks Stop ont prolongé le tour huit fois de suite, Claude Code passe outre le blocage suivant et termine le tour. Pour relever ce plafond, définissez CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Le champ last_assistant_message contient le contenu textuel de la réponse finale de Claude, afin que les hooks puissent 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 à voix haute ou de notification, utilisez ce champ plutôt que de lire transcript_path : il n'est pas garanti, sur toutes les versions, que le fichier de transcription contienne le message final au moment de Stop.

Les tableaux background_tasks et session_crons permettent aux hooks de distinguer « la session est terminée » de « la session est en pause en attendant qu'un travail en arrière-plan la réveille ». Les deux tableaux sont présents lorsque le registre des tâches est accessible et sont vides lorsque rien n'est en cours ni planifié.

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

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

Cet exemple montre une entrée Stop avec une tâche shell en cours 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 renvoyer ces champs propres à l'événement :

Un hook qui bloque en se terminant avec le code 2 est traité de la même manière que reason : Claude reçoit le message stderr comme explication de la raison pour laquelle 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 indications à Claude, comme « exécuter la suite de tests avant de terminer ». Il fait continuer la conversation avec les mêmes protections contre les boucles que decision: "block", à savoir l'entrée stop_hook_active et le plafond de 8 poursuites 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 d'API. Claude Code ignore la sortie et le code de sortie du hook, à l'exception de terminalSequence. Utilisez-le pour journaliser les échecs, 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 d'API.

Entrée StopFailure

En plus des champs d'entrée communs, les hooks StopFailure reçoivent error, un error_details facultatif et un last_assistant_message facultatif. Le champ error identifie le type d'erreur et est utilisé pour le filtrage par 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 uniquement à des fins de notification et de journalisation.

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-le pour imposer des contrôles qualité avant qu'un coéquipier n'arrête de travailler, par exemple en exigeant la réussite des vérifications de lint ou en vérifiant l'existence des fichiers de sortie.

Les hooks TeammateIdle ne prennent pas en charge 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 offrent deux manières de contrôler le comportement du coéquipier :

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

Cet exemple vérifie qu'un artefact de build 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 lorsqu'un fichier de configuration change pendant une session. Utilisez-le pour auditer les modifications de paramètres, appliquer des politiques de sécurité ou bloquer les modifications non autorisées des 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 ne les exécute que lorsque managed-settings.json ou un fichier de managed-settings.d/ change. Il applique les paramètres gérés par le serveur et les modifications des préférences gérées macOS ou de la politique du registre Windows sans les exécuter. Sous WSL avec wslInheritsWindowsSettings, il applique également un fichier de paramètres gérés modifié côté Windows lors de son interrogation de politique, sans les exécuter.

Le matcher filtre sur la source de configuration :

Cet exemple journalise toutes les modifications de configuration à des fins d'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, de manière facultative, file_path. Le champ source indique quel type de configuration a changé, et file_path fournit le chemin du fichier précis 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 empêcher des modifications de configuration de prendre effet. Utilisez le code de sortie 2 ou une decision JSON pour empêcher la modification. En cas de blocage, les nouveaux paramètres ne sont pas appliqués à la session en cours.

{
  "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 lorsqu'un fichier de paramètres gérés sur la machine change, ce qui vous permet de les utiliser pour journaliser ces modifications, 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 des paramètres gérés par le serveur arrivent ou sont actualisés.

Claude Code applique la décision de blocage issue de la sortie JSON d'un hook ConfigChange et supprime systemMessage et continue. Une modification bloquée n'affiche aucun message, ni à vous ni à Claude, que vous bloquiez avec reason ou avec stderr et le code de sortie 2. Claude Code écrit seulement une ligne dans le log de débogage.

CwdChanged

S'exécute lorsqu'une commande shell dans la conversation principale change le répertoire de travail, par exemple lorsque Claude exécute une commande cd. Utilisez-le pour réagir aux changements de répertoire : recharger des variables d'environnement, activer des chaînes d'outils propres au projet ou exécuter automatiquement des scripts de configuration. Se combine avec FileChanged pour des 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, moment où Claude Code les efface.

CwdChanged ne prend pas en charge 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 renvoyer watchPaths pour définir dynamiquement les chemins de fichiers surveillés par FileChanged :

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 dans leur sortie JSON et supprime continue. Dans les sessions interactives, il affiche le systemMessage sous forme de brève notification dans le terminal. Le message n'atteint pas le flux de messages du SDK.

DirectoryAdded

S'exécute après que vous avez ajouté un répertoire de travail en cours de session avec la commande /add-dir, ou après qu'un client SDK en a ajouté un avec la requête de contrôle register_repo_root. Utilisez-le pour préparer un dépôt 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 flag de démarrage --add-dir ; SessionStart couvre ces répertoires
• Vous ajoutez un répertoire dans l'onglet Workspace de /permissions
• Vous ajoutez un répertoire qui est déjà un répertoire de travail ou qui se trouve à l'intérieur de l'un d'eux

Claude Code déclenche DirectoryAdded après avoir actualisé l'état du sandbox et des permissions, de sorte que les outils en sandbox voient déjà le nouveau répertoire lorsque votre hook s'exécute. Les commandes des hooks elles-mêmes s'exécutent hors 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 manière 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 est déjà terminé lorsque le hook s'exécute. Claude Code supprime le champ continue de leur sortie JSON et présente le reste différemment selon la source :

• slash_command : Claude Code transmet le systemMessage du hook à Claude comme contexte au tour suivant de la conversation, plutôt que de vous l'afficher. Le nombre de hooks en échec apparaît dans la transcription. La sortie complète des échecs est envoyée dans le log de débogage
• register_repo_root : Claude Code écrit la sortie systemMessage et la sortie des échecs uniquement dans le log de débogage

FileChanged

S'exécute lorsqu'un fichier surveillé change sur le disque. Claude Code détecte les modifications avec un observateur du système de fichiers, et non en inspectant les appels d'outils ; il exécute donc le hook quelle que soit l'origine de la modification : un appel d'outil Edit ou Write, un script que Claude exécute avec Bash, ou un processus entièrement extérieur à Claude Code. Un usage courant consiste à recharger des variables d'environnement lorsque des fichiers de configuration du projet changent.

Le matcher de cet événement joue deux rôles :

• Construire la liste de surveillance : la valeur est découpée sur | et chaque segment est enregistré comme un nom de fichier littéral dans le répertoire de travail ; ainsi ".envrc|.env" surveille exactement ces deux fichiers. Les expressions régulières ne sont pas utiles ici : une valeur comme ^\.env surveillerait un fichier littéralement nommé ^\.env.
• Filtrer les hooks qui s'exécutent : lorsqu'un fichier surveillé change, la même valeur filtre les groupes de hooks qui s'exécutent selon les règles standard des matchers, appliquées au nom de base du fichier modifié.

Cet exemple normalise les fins de ligne de data.csv après toute modification, y compris lorsqu'une commande Bash ou un script externe réécrit 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é dans le champ file_path de l'entrée JSON sur stdin. Sa garde grep teste la même chose que ce que perl supprime, un CR en fin de ligne, de sorte que l'exécution qui suit une normalisation se termine sans toucher au fichier. Une garde plus permissive boucle indéfiniment, car perl -i réécrit le fichier même lorsqu'il ne substitue rien et Claude Code réexécute le hook après chaque réécriture. Enregistrez ce script sous /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 vérifier 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 retrouve avec des fins de ligne LF.

Pour surveiller des fichiers que vous ne pouvez pas nommer à l'avance, renvoyez watchPaths depuis un hook afin de mettre à jour dynamiquement la liste de surveillance. Claude Code ne démarre l'observateur que lorsqu'un élément nomme un fichier à surveiller ; amorcez donc la liste avec un groupe FileChanged dont le matcher nomme au moins un fichier, ou avec un hook SessionStart ou CwdChanged qui renvoie watchPaths. Le matcher filtre toujours les groupes de hooks qui s'exécutent lorsqu'un fichier surveillé change ; donnez donc au groupe qui gère les chemins dynamiques un matcher omis, qui correspond à tous les fichiers surveillés et n'ajoute rien à la liste de surveillance. Un matcher "*" correspond également à tous les fichiers, mais Claude Code l'enregistre dans la liste de surveillance comme n'importe quelle autre valeur, en tant que fichier littéral 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, moment où 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 renvoyer watchPaths pour mettre à jour dynamiquement les chemins de fichiers surveillés :

Les hooks FileChanged n'ont pas de contrôle de décision. Ils ne peuvent pas empêcher la modification du fichier.

Claude Code lit watchPaths et systemMessage dans leur sortie JSON et supprime continue. Dans les sessions interactives, il affiche le systemMessage sous forme de brève notification dans le terminal. Le message n'atteint pas le flux de messages du SDK.

WorktreeCreate

S'exécute lorsqu'un worktree est en cours de création, que ce soit depuis claude --worktree, depuis 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, ce qui vous permet d'utiliser un autre système de gestion de versions comme SVN, Perforce ou Mercurial.

Comme le hook remplace entièrement le comportement par défaut, .worktreeinclude n'est pas traité. Si vous devez copier des fichiers de configuration locaux comme .env dans le nouveau worktree, faites-le dans votre script de hook.

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

Claude Code tient compte de la réussite du hook et du chemin renvoyé, et supprime systemMessage et continue.

Cet exemple crée une copie de travail SVN et affiche le chemin que Claude Code doit utiliser. Remplacez l'URL du dépôt 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 dans l'entrée JSON sur stdin, extrait une nouvelle copie dans un nouveau répertoire et affiche le chemin du répertoire. L'echo de la dernière ligne est ce que Claude Code lit comme chemin du worktree. Redirigez toute autre sortie 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. Il s'agit d'un identifiant de type 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 de WorktreeCreate

Les hooks WorktreeCreate n'utilisent pas le modèle de décision standard autoriser/bloquer. C'est plutôt la réussite ou l'échec du hook qui détermine le résultat. Le hook doit renvoyer le chemin vers le répertoire du worktree créé :

• Hooks de commande (type: "command") : affichez le chemin sur la dernière ligne non vide de stdout. Claude Code supprime les codes d'échappement ANSI avant de lire cette ligne, de sorte que les bannières de démarrage du shell affichées avant votre echo sont ignorées. Redirigez toute autre sortie du hook vers stderr.
• Hooks HTTP (type: "http") : renvoyez { "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 réduisant les éventuels segments . ou .. qu'il contient. Si le chemin obtenu n'est pas un répertoire dans lequel Claude Code peut entrer, la session affiche une erreur indiquant le chemin et se termine avec le code 1.

Claude Code refuse un chemin absolu contenant des segments . ou .., ainsi que tout chemin passant par un lien symbolique situé sous la racine du dépôt, car un lien symbolique commité dans le dépôt pourrait rediriger le worktree en dehors de celui-ci. L'erreur indique le composant rejeté. Renvoyez un chemin normalisé qui ne passe pas par un lien symbolique à l'intérieur du dépôt. Avant la v2.1.216, la création du worktree suivait le chemin du hook sans ce contrôle.

WorktreeRemove

S'exécute lorsqu'un worktree est en cours de suppression. C'est le pendant de nettoyage de WorktreeCreate. L'événement se déclenche lorsque :

• 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 automatiquement le nettoyage avec git worktree remove. Si vous avez configuré un hook WorktreeCreate, associez-le à un hook WorktreeRemove pour contrôler le nettoyage des worktrees qu'il crée :

• Aucun hook WorktreeRemove : lorsque vous quittez une session --worktree et choisissez la suppression, Claude Code se rabat sur git worktree remove --force sur le chemin renvoyé par votre hook WorktreeCreate, de sorte qu'un worktree reconnu par git est supprimé. Un worktree que git ne reconnaît pas, par exemple un worktree créé par votre hook avec un système de gestion de versions autre que git, reste sur le disque. Pour savoir ce que la suppression d'une session en arrière-plan fait d'un worktree créé par un hook, consultez les règles de suppression de la vue agent.
• Le hook se termine avec le code 0 : le worktree est considéré comme supprimé. Claude Code ne lit rien d'autre du hook ; assurez-vous donc que votre hook a bien supprimé le répertoire.
• Le hook se termine avec un code non nul : la suppression échoue si le répertoire situé à worktree_path existe toujours ensuite, et le worktree reste sur le disque sans solution de repli git. Un hook qui a supprimé le répertoire avant de se terminer avec un code non nul est considéré comme ayant supprimé le worktree. Pour savoir comment l'échec est signalé, consultez Entrée de WorktreeRemove.

Claude Code ne supprime jamais une branche appartenant à un worktree créé par un hook, car il ne connaît que le chemin renvoyé par votre hook WorktreeCreate. Si votre hook WorktreeCreate crée une branche, supprimez-la dans votre hook WorktreeRemove.

Claude Code ignore les champs de sortie JSON d'un hook WorktreeRemove, tels que systemMessage et continue.

Lors de la suppression d'une session en arrière-plan, Claude Code vérifie le chemin du worktree enregistré avant d'exécuter le hook et refuse un chemin qui est un lien symbolique ou qui passe par un lien symbolique sous la racine du dépôt. Le hook s'exécute pour un worktree contenant encore des fichiers uniquement lorsque vous confirmez la suppression dans la vue agent ; pour un tel worktree, claude rm conserve plutôt la session et le worktree. Avant la v2.1.216, le hook s'exécutait sur le chemin enregistré sans ces vérifications.

Claude Code transmet le chemin renvoyé par WorktreeCreate sous la forme 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 de WorktreeRemove

En plus des champs d'entrée communs, les hooks WorktreeRemove reçoivent le champ worktree_path, qui est le chemin absolu vers le 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étermine le résultat. Lorsqu'un hook se termine avec un code non nul et que le répertoire situé à worktree_path existe toujours ensuite, la suppression échoue :

• Le worktree reste sur le disque, et la commande et le stderr du hook sont envoyés au log de débogage.
• Si vous supprimiez une session en arrière-plan, la session est également conservée. Le message de refus dans la vue agent indique comment le hook s'est terminé, par exemple exited 1, cite le début de son stderr et précise si une nouvelle suppression de la session supprime malgré tout le répertoire.

PreCompact

S'exécute juste avant que Claude Code n'effectue une opération de compaction.

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

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

Le blocage de la compaction automatique a des effets différents selon le moment où elle se déclenche. Si la compaction a été déclenchée de manière proactive avant la limite de contexte, Claude Code l'ignore et la conversation se poursuit sans être compactée. Si la compaction a été déclenchée pour récupérer d'une erreur de limite de contexte déjà renvoyée par l'API, l'erreur sous-jacente remonte et la requête en cours échoue.

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

Entrée de 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 à /compact et vaut null lorsqu'il ne transmet rien. Pour auto, custom_instructions vaut 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 a terminé une opération de compaction. Utilisez cet événement pour réagir au nouvel état compacté, par exemple pour journaliser le résumé généré ou mettre à jour un état externe. Claude Code ignore les champs systemMessage et continue d'un hook PostCompact.

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

Entrée de 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 la 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 aucun contrôle de décision. Ils ne peuvent pas influer sur 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 demandé par vous ou par un client. Utilisez-le pour bloquer un changement, exiger une confirmation ou afficher ce que le changement coûtera avant qu'il n'ait lieu.

PreModelSwitch nécessite Claude Code v2.1.251 ou une version ultérieure. 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 celle-ci 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, provenant d'un hôte Agent SDK ou de Remote Control

Claude Code n'exécute pas les hooks PreModelSwitch pour les changements qu'il effectue de lui-même, comme un basculement automatique vers un modèle de secours ou la restauration du modèle lorsque vous reprenez une session. Ces changements atteignent uniquement PostModelSwitch.

Claude Code compare le matcher au nom canonique du modèle vers lequel la session bascule, en ignorant tout suffixe [1m]. Un alias tel que opus, un identifiant de modèle daté et un identifiant propre à un fournisseur, comme un identifiant de modèle Amazon Bedrock, correspondent tous au même nom canonique vers lequel ils se résolvent ; ainsi, claude-opus-5 couvre toutes les écritures d'Opus 5.

Lorsque Claude Code ne peut pas déterminer un nom canonique pour la cible, par exemple un identifiant de modèle personnalisé que seule votre passerelle LLM connaît, il exécute tous les hooks PreModelSwitch quel que soit le matcher. Un hook qui bloque doit donc vérifier to_model dans son entrée plutôt que de se fier uniquement au matcher.

Écrivez le matcher sous la forme d'un nom exact, d'une liste séparée par des | telle que claude-opus-4-6|claude-opus-5, ou d'une expression régulière telle que .*opus.*. Cet exemple utilise un matcher à nom exact et vérifie également to_model dans l'entrée du hook ; il refuse ainsi un changement vers Opus 4.6 en se terminant avec le code 2 et laisse passer toute autre cible :

{
"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 vérifier que le hook fonctionne, exécutez /model claude-opus-4-6 depuis une session utilisant un autre modèle. Claude Code conserve le modèle actuel et indique qu'un hook PreModelSwitch a bloqué le changement, avec votre message comme motif.

Entrée de 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 coûte le renvoi de la conversation au nouveau modèle, afin qu'un hook puisse afficher ce montant avant que le changement n'ait lieu.

Cet exemple montre l'entrée pour /model opus dans une session utilisant 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 de PreModelSwitch

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

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

Seul /model dans une session interactive peut afficher la demande "ask". Sur toutes les autres surfaces, y compris le mode non interactif avec le flag -p, /config et les requêtes set_model, Claude Code traite "ask" comme un refus.

Cet exemple demande une confirmation à l'utilisateur et cite le nombre de tokens issu 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 renvoient des décisions différentes, l'ordre de priorité est deny > ask > allow.

Claude Code affiche à l'utilisateur tout systemMessage renvoyé par votre hook, quelle que soit la décision ; un hook de rapport de coût peut donc renvoyer {"systemMessage": "..."} et se terminer avec le code 0.

Un hook PreModelSwitch qui ne répond pas avant l'expiration de son délai bloque le changement. Pour PreToolUse, à l'inverse, un hook de commande ayant expiré laisse l'appel d'outil se poursuivre. Le délai d'expiration par défaut pour cet événement est de 30 secondes. PreModelSwitch exécute uniquement les hooks command, http et mcp_tool ; les valeurs par défaut de prompt et agent ne s'appliquent donc pas.

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

PostModelSwitch

S'exécute après le changement du modèle de la session. Utilisez-le pour donner à Claude des consignes propres à un modèle sans modifier chaque CLAUDE.md, par exemple une instruction à l'échelle de l'organisation qui s'applique à certains modèles.

PostModelSwitch nécessite Claude Code v2.1.251 ou une version ultérieure. Il ne peut pas bloquer, car le modèle a déjà changé. Claude Code exécute les hooks PostModelSwitch après l'un de ces changements :

• Un changement demandé par vous ou par un client
• Un basculement automatique vers un modèle de secours, qui change le modèle de la session
• Un paramètre tel que opusplan entrant dans le mode plan ou en sortant
• La restauration du modèle par Claude Code 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 secours traite un tour, car cette substitution dure un seul tour et ne modifie pas le modèle de la session.

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

Cet exemple ajoute des consignes chaque fois que le modèle de la session passe à un 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 vérifier que le hook fonctionne, passez à un modèle Opus depuis une session utilisant un autre modèle, par exemple en exécutant /model opus depuis une session Sonnet, puis demandez à Claude quelles consignes il a concernant le modèle actuel.

Entrée de PostModelSwitch

Les hooks PostModelSwitch reçoivent les mêmes champs que PreModelSwitch, avec hook_event_name défini sur "PostModelSwitch" et deux valeurs supplémentaires pour source : "auto" pour un basculement automatique vers un modèle de secours ou tout autre changement effectué par Claude Code de lui-même, et "resume" pour le modèle restauré lorsque vous reprenez une session.

requested_model vaut null lorsque source vaut "auto". Lorsque source vaut "resume", il s'agit du paramètre de modèle enregistré que Claude Code a restauré.

Contrôle de décision de PostModelSwitch

Claude Code récupère le stdout en texte brut de votre hook lors d'une sortie avec le code 0, ou additionalContext depuis la sortie JSON, et le transmet à Claude avec la prochaine requête après le changement. En plus des champs de sortie JSON disponibles pour tous les hooks, vous pouvez renvoyer :

Si le hook n'a pas terminé dans les cinq secondes suivant l'envoi de votre prochain prompt, Claude Code envoie cette requête sans la sortie et la joint plutôt à la requête suivante. Si le modèle change plusieurs fois avant la prochaine requête, Claude Code transmet uniquement la sortie correspondant au modèle cible du dernier changement.

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 la session. Prend en charge les matchers pour filtrer selon le motif de sortie.

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

Entrée de 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 motifs 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 aucun contrôle de décision. Ils ne peuvent pas bloquer la fin de la session, mais peuvent effectuer des tâches de nettoyage. Claude Code ignore leurs champs de sortie JSON, tels que systemMessage.

Les hooks SessionEnd ont un délai d'expiration par défaut de 1,5 seconde. Il s'applique lorsque vous quittez, exécutez /clear ou changez de session avec /resume en mode interactif. Vous pouvez accorder plus de temps à un hook 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é de vos fichiers de paramètres, jusqu'à 60 secondes. Si vous augmentez le budget de cette façon, un hook sans son propre timeout conserve tout de même la valeur par défaut. Les délais d'expiration définis sur des hooks fournis par des plugins n'augmentent pas le budget.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS : définissez cette variable d'environnement en millisecondes pour remplacer explicitement le budget. La valeur que vous définissez devient également le délai d'expiration de chaque hook sans son propre timeout.

Cet exemple définit le budget à 5 secondes :

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Avant la v2.1.268, CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS augmentait uniquement le budget global, et un hook sans son propre timeout était tout de même annulé au bout de 1,5 seconde.

Elicitation

S'exécute lorsqu'un serveur MCP demande une saisie de l'utilisateur en cours de tâche. Par défaut, Claude Code affiche une boîte de dialogue interactive pour que l'utilisateur réponde. Les hooks peuvent intercepter cette demande et y répondre de manière programmatique, en ignorant entièrement la boîte de dialogue.

Le champ matcher est comparé au nom du serveur MCP.

Entrée d'Elicitation

En plus des champs d'entrée communs, les hooks Elicitation reçoivent mcp_server_name, message et les champs facultatifs 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 via le 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 d'Elicitation

Pour répondre de manière programmatique sans afficher la boîte de dialogue, renvoyez 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 tient compte de hookSpecificOutput dans la sortie JSON d'un hook Elicitation et ignore systemMessage et continue.

ElicitationResult

S'exécute après qu'un utilisateur a répondu à 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 est comparé au nom du serveur MCP.

Entrée d'ElicitationResult

En plus des champs d'entrée communs, les hooks ElicitationResult reçoivent mcp_server_name, action et les champs facultatifs 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 d'ElicitationResult

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

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

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

Claude Code tient compte de hookSpecificOutput dans la sortie JSON d'un hook ElicitationResult et ignore 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, par défaut celui que Claude Code utilise pour la fonctionnalité en arrière-plan
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. 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 un 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.

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

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