309| `uuid` | `string` | Identifiant de message unique |309| `uuid` | `string` | Identifiant de message unique |
310| `session_id` | `string` | Session à laquelle ce message appartient |310| `session_id` | `string` | Session à laquelle ce message appartient |
311| `message` | `unknown` | Charge utile de message brute de la transcription |311| `message` | `unknown` | Charge utile de message brute de la transcription |
312| `parent_tool_use_id` | `string \| null` | Pour les messages de sous-agent, le `tool_use_id` de l'appel d'outil `Agent` qui l'a généré. `null` pour les messages de session principale et les sessions plus anciennes |312| `parent_tool_use_id` | `string \| null` | Pour les messages de sous-agent, le `tool_use_id` de l'appel d'outil `Agent` ou `Skill` qui l'a généré. `null` pour les messages de session principale et les sessions plus anciennes |
313| `parent_agent_id` | `string \| null` | Pour les messages d'un [sous-agent imbriqué](/docs/fr/sub-agents#let-subagents-spawn-their-own-subagents), le `agentId` du sous-agent qui l'a généré. `null` pour les messages de session principale, les messages des sous-agents de niveau supérieur et les sessions plus anciennes. Nécessite Claude Code v2.1.202 ou ultérieur |313| `parent_agent_id` | `string \| null` | Pour les messages d'un [sous-agent imbriqué](/docs/fr/sub-agents#let-subagents-spawn-their-own-subagents), le `agentId` du sous-agent qui l'a généré. `null` pour les messages de session principale, les messages des sous-agents de niveau supérieur et les sessions plus anciennes. Nécessite Claude Code v2.1.202 ou ultérieur |
314 314
315<h4 id="example-3">315<h4 id="example-3">
504| `extraArgs` | `Record<string, string \| null>` | `{}` | Arguments supplémentaires |504| `extraArgs` | `Record<string, string \| null>` | `{}` | Arguments supplémentaires |
505| `fallbackModel` | `string` | `undefined` | Modèle à utiliser si le principal échoue. Accepte une liste séparée par des virgules. Pour l'ordre et le plafond, voir [Chaînes de modèle de secours](/docs/fr/model-config#fallback-model-chains). Pour des conseils, voir [Choisir un modèle](/docs/fr/agent-sdk/configuration#choose-a-model) |505| `fallbackModel` | `string` | `undefined` | Modèle à utiliser si le principal échoue. Accepte une liste séparée par des virgules. Pour l'ordre et le plafond, voir [Chaînes de modèle de secours](/docs/fr/model-config#fallback-model-chains). Pour des conseils, voir [Choisir un modèle](/docs/fr/agent-sdk/configuration#choose-a-model) |
506| `forkSession` | `boolean` | `false` | Lors de la reprise avec `resume`, bifurquer vers un nouvel ID de session au lieu de continuer la session d'origine |506| `forkSession` | `boolean` | `false` | Lors de la reprise avec `resume`, bifurquer vers un nouvel ID de session au lieu de continuer la session d'origine |
507| `forwardSubagentText` | `boolean` | `false` | Transférer les blocs de texte et de réflexion des sous-agents en tant que messages assistant et utilisateur avec `parent_tool_use_id` défini, pour que les consommateurs puissent afficher une transcription imbriquée. Sans cette option, Claude Code émet les blocs `tool_use` et `tool_result` des sous-agents mais pas le texte ou la réflexion. Les messages des sous-agents à chaque profondeur d'imbrication sont transférés sur Claude Code v2.1.219 et ultérieur ; avant v2.1.219, seuls les messages des sous-agents de profondeur 1 apparaissaient |507| `forwardSubagentText` | `boolean` | `false` | Transférer les blocs de texte et de réflexion des sous-agents en tant que messages assistant et utilisateur avec `parent_tool_use_id` défini, pour que les consommateurs puissent afficher une transcription imbriquée. Sans cette option, Claude Code émet les blocs `tool_use` et `tool_result` des sous-agents mais pas le texte ou la réflexion. Les messages des sous-agents à chaque profondeur d'imbrication sont transférés sur Claude Code v2.1.219 et ultérieur ; avant v2.1.219, seuls les messages des sous-agents de profondeur 1 apparaissaient. Les messages des sous-agents qu'une compétence bifurquée génère, et des compétences bifurquées imbriquées, nécessitent v2.1.275 ou ultérieur |
508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Rappels de hook pour les événements |508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Rappels de hook pour les événements |
509| `includeHookEvents` | `boolean` | `false` | Inclure les événements du cycle de vie du hook dans le flux de messages en tant que [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), et [`SDKHookResponseMessage`](#sdkhookresponsemessage). Les événements du cycle de vie pour les hooks `SessionStart` et `Setup` sont toujours inclus et n'ont pas besoin de cette option. Certains événements de hook, tels que `Notification`, `SessionEnd`, `PreCompact`, et `PostCompact`, ne produisent jamais un `SDKHookStartedMessage`, même avec cette option. Pour ceux-ci, Claude Code émet toujours un `SDKHookProgressMessage` tandis qu'un hook de commande qui s'exécute pendant plus d'une seconde produit une sortie, et émet un `SDKHookResponseMessage` uniquement quand un hook [qui s'exécute en arrière-plan](/docs/fr/hooks#run-hooks-in-the-background) se termine |509| `includeHookEvents` | `boolean` | `false` | Inclure les événements du cycle de vie du hook dans le flux de messages en tant que [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), et [`SDKHookResponseMessage`](#sdkhookresponsemessage). Les événements du cycle de vie pour les hooks `SessionStart` et `Setup` sont toujours inclus et n'ont pas besoin de cette option. Certains événements de hook, tels que `Notification`, `SessionEnd`, `PreCompact`, et `PostCompact`, ne produisent jamais un `SDKHookStartedMessage`, même avec cette option. Pour ceux-ci, Claude Code émet toujours un `SDKHookProgressMessage` tandis qu'un hook de commande qui s'exécute pendant plus d'une seconde produit une sortie, et émet un `SDKHookResponseMessage` uniquement quand un hook [qui s'exécute en arrière-plan](/docs/fr/hooks#run-hooks-in-the-background) se termine |
510| `includePartialMessages` | `boolean` | `false` | Inclure les événements de message partiel |510| `includePartialMessages` | `boolean` | `false` | Inclure les événements de message partiel |
525| `persistSession` | `boolean` | `true` | Quand `false`, désactive la persistance de session sur disque. Les sessions ne peuvent pas être reprises plus tard |525| `persistSession` | `boolean` | `true` | Quand `false`, désactive la persistance de session sur disque. Les sessions ne peuvent pas être reprises plus tard |
526| `planModeInstructions` | `string` | `undefined` | Instructions de flux de travail personnalisées pour le mode plan. Quand `permissionMode` est `'plan'`, cette chaîne remplace le corps du flux de travail du mode plan par défaut. La CLI l'enveloppe toujours avec le préambule d'application en lecture seule et le pied de page du protocole ExitPlanMode |526| `planModeInstructions` | `string` | `undefined` | Instructions de flux de travail personnalisées pour le mode plan. Quand `permissionMode` est `'plan'`, cette chaîne remplace le corps du flux de travail du mode plan par défaut. La CLI l'enveloppe toujours avec le préambule d'application en lecture seule et le pied de page du protocole ExitPlanMode |
527| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Charger les plugins personnalisés à partir de chemins locaux. Voir [Plugins](/docs/fr/agent-sdk/plugins) pour les détails |527| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Charger les plugins personnalisés à partir de chemins locaux. Voir [Plugins](/docs/fr/agent-sdk/plugins) pour les détails |
528| `projectConfigRoot` | `string` | `undefined` | Chemin absolu du checkout de confiance dont `cwd` est une worktree. Claude Code lit les paramètres du projet, `.mcp.json`, et les commandes, agents, compétences, workflows, routines et styles de sortie du projet `.claude/` à partir de ce répertoire au lieu de `cwd`, et définit `CLAUDE_PROJECT_DIR` sur celui-ci. Les hooks, les scripts d'aide tels que `apiKeyHelper`, et les serveurs MCP stdio commencent avec ce répertoire comme répertoire de travail. Les fichiers `CLAUDE.md` et `.claude/rules/` se chargent toujours à partir de `cwd`. Nécessite Claude Code v2.1.275 ou ultérieur |
528| `promptSuggestions` | `boolean` | `false` | Activer les suggestions d'invite. Après un tour, Claude Code émet un message `prompt_suggestion` portant une invite utilisateur suivante prédite. Claude Code ne génère aucune suggestion pour certains tours, comme quand votre compte est proche ou à sa limite d'utilisation. Voir [Quand Claude Code ignore les suggestions](/docs/fr/interactive-mode#when-claude-code-skips-suggestions) |529| `promptSuggestions` | `boolean` | `false` | Activer les suggestions d'invite. Après un tour, Claude Code émet un message `prompt_suggestion` portant une invite utilisateur suivante prédite. Claude Code ne génère aucune suggestion pour certains tours, comme quand votre compte est proche ou à sa limite d'utilisation. Voir [Quand Claude Code ignore les suggestions](/docs/fr/interactive-mode#when-claude-code-skips-suggestions) |
529| `resume` | `string` | `undefined` | ID de session à reprendre |530| `resume` | `string` | `undefined` | ID de session à reprendre |
530| `resumeDropsTurn` | `string` | `undefined` | Avec `resumeSessionAt` : l'UUID du tour que la reprise tronquée a l'intention de rejeter. Claude Code refuse la reprise quand la plage rejetée contient quelque chose non attribuable à ce tour, comme des messages en attente absorbés ou des notifications de tâche, et nomme le drapeau `--resume-drops-turn` dans le message de rejet. Seul l'Agent SDK et les reprises en mode impression lisent la paire. Nécessite Claude Code v2.1.223 ou ultérieur |531| `resumeDropsTurn` | `string` | `undefined` | Avec `resumeSessionAt` : l'UUID du tour que la reprise tronquée a l'intention de rejeter. Claude Code refuse la reprise quand la plage rejetée contient quelque chose non attribuable à ce tour, comme des messages en attente absorbés ou des notifications de tâche, et nomme le drapeau `--resume-drops-turn` dans le message de rejet. Seul l'Agent SDK et les reprises en mode impression lisent la paire. Nécessite Claude Code v2.1.223 ou ultérieur |
600 : Settings[K] | null;601 : Settings[K] | null;
601 }): Promise<void>;602 }): Promise<void>;
602 updateSettings(603 updateSettings(
603 source: 'localSettings',604 source: 'localSettings' | 'userSettings',
604 settings: Record<string, unknown>,605 settings: Record<string, unknown>,
605 ): Promise<void>;606 ): Promise<void>;
606 initializationResult(): Promise<SDKControlInitializeResponse>;607 initializationResult(): Promise<SDKControlInitializeResponse>;
621 reconnectMcpServer(serverName: string): Promise<void>;622 reconnectMcpServer(serverName: string): Promise<void>;
622 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;623 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
623 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;624 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
625 readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;
624 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;626 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
625 stopTask(taskId: string): Promise<void>;627 stopTask(taskId: string): Promise<void>;
626 close(): void;628 close(): void;
639| `setModel()` | Change le modèle (disponible uniquement en mode d'entrée en diffusion). Passer `undefined` ou la chaîne `"default"` réinitialise au [modèle par défaut de Claude Code](/docs/fr/model-config) |641| `setModel()` | Change le modèle (disponible uniquement en mode d'entrée en diffusion). Passer `undefined` ou la chaîne `"default"` réinitialise au [modèle par défaut de Claude Code](/docs/fr/model-config) |
640| `setMaxThinkingTokens()` | *Déprécié :* Utilisez l'option `thinking` à la place. Change les tokens de réflexion maximum. Passer `null` réinitialise la réflexion à la valeur par défaut de la session : un remplacement en milieu de session est effacé, et la réflexion reste désactivée pour les sessions qui l'ont désactivée |642| `setMaxThinkingTokens()` | *Déprécié :* Utilisez l'option `thinking` à la place. Change les tokens de réflexion maximum. Passer `null` réinitialise la réflexion à la valeur par défaut de la session : un remplacement en milieu de session est effacé, et la réflexion reste désactivée pour les sessions qui l'ont désactivée |
641| `applyFlagSettings(settings)` | Fusionne les paramètres dans la couche de paramètres d'indicateur de la session à l'exécution (disponible uniquement en mode d'entrée en diffusion). Voir [`applyFlagSettings()`](#applyflagsettings) |643| `applyFlagSettings(settings)` | Fusionne les paramètres dans la couche de paramètres d'indicateur de la session à l'exécution (disponible uniquement en mode d'entrée en diffusion). Voir [`applyFlagSettings()`](#applyflagsettings) |
642| `updateSettings(source, settings)` | Fusionne les paramètres dans le fichier de paramètres locaux du projet, `.claude/settings.local.json` ; ils prennent effet à la requête suivante. Accepte uniquement `source: 'localSettings'` et un ensemble de clés autorisées, actuellement `outputStyle`, avec des valeurs de chaîne ; la suppression d'une clé n'est pas prise en charge. Rejette sur les transports distants et dans les sessions dont [`settingSources`](#options) excluent `local`. Nécessite TypeScript SDK v0.3.257 ou ultérieur, qui regroupe Claude Code v2.1.257 |644| `updateSettings(source, settings)` | Écrit une clé autorisée dans le fichier de paramètres locaux du projet ou votre fichier de paramètres utilisateur, pour que la valeur persiste pour les sessions ultérieures. Voir [`updateSettings()`](#updatesettings). Nécessite TypeScript SDK v0.3.257 ou ultérieur, qui regroupe Claude Code v2.1.257 |
643| `initializationResult()` | Retourne le résultat d'initialisation complet incluant les commandes prises en charge, les modèles, les informations de compte et la configuration du style de sortie |645| `initializationResult()` | Retourne le résultat d'initialisation complet incluant les commandes prises en charge, les modèles, les informations de compte et la configuration du style de sortie |
644| `reinitialize()` | Renvoie la demande de contrôle `initialize` au CLI en cours d'exécution et retourne un résultat frais au lieu du résultat de première connexion mis en cache. Utilisez-le après une interruption de transport, comme se reconnecter à une session après une déconnexion, pour que les demandes de permission en attente atteignent à nouveau votre rappel `canUseTool`. Rendez le rappel idempotent par ID de requête, car une requête dont la réponse a été perdue est distribuée à nouveau. Nécessite Claude Code v2.1.195 ou ultérieur |646| `reinitialize()` | Renvoie la demande de contrôle `initialize` au CLI en cours d'exécution et retourne un résultat frais au lieu du résultat de première connexion mis en cache. Utilisez-le après une interruption de transport, comme se reconnecter à une session après une déconnexion, pour que les demandes de permission en attente atteignent à nouveau votre rappel `canUseTool`. Rendez le rappel idempotent par ID de requête, car une requête dont la réponse a été perdue est distribuée à nouveau. Nécessite Claude Code v2.1.195 ou ultérieur |
645| `supportedCommands()` | Retourne les commandes disponibles. À partir d'Agent SDK v0.3.216, la liste reflète les changements de commande en milieu de session ; voir [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |647| `supportedCommands()` | Retourne les commandes disponibles. À partir d'Agent SDK v0.3.216, la liste reflète les changements de commande en milieu de session ; voir [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |
646| `supportedModels()` | Retourne les modèles disponibles avec les informations d'affichage |648| `supportedModels()` | Retourne les modèles disponibles avec les informations d'affichage |
647| `supportedAgents()` | Retourne les sous-agents disponibles en tant que [`AgentInfo`](#agentinfo)`[]` |649| `supportedAgents()` | Retourne les sous-agents disponibles en tant que [`AgentInfo`](#agentinfo)`[]` |
648| `mcpServerStatus()` | Retourne l'état des serveurs MCP connectés |650| `mcpServerStatus()` | Retourne l'état des serveurs MCP connectés en tant que [`McpServerStatus`](#mcpserverstatus)`[]` |
649| `getContextUsage(opts?)` | Retourne une [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) ventilant l'utilisation de la fenêtre de contexte de la session par catégorie, compétence et outil. Avec la valeur par défaut `detail`, c'est les mêmes données que `/context` affiche dans une session interactive. L'[option `detail`](#sdkcontrolgetcontextusageresponse) nécessite Agent SDK v0.3.257 ou ultérieur |651| `getContextUsage(opts?)` | Retourne une [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) ventilant l'utilisation de la fenêtre de contexte de la session par catégorie, compétence et outil. Avec la valeur par défaut `detail`, c'est les mêmes données que `/context` affiche dans une session interactive. L'[option `detail`](#sdkcontrolgetcontextusageresponse) nécessite Agent SDK v0.3.257 ou ultérieur |
650| `readFile(path, options?)` | Lit un fichier du système de fichiers de la session. Claude Code résout le chemin par rapport à `cwd` ; [Ce que `readFile()` peut lire](#what-readfile-can-read) liste les fichiers qu'il sert. Passez `{ maxBytes }` pour modifier le plafond de lecture (par défaut 1 Mo, plafond 10 Mo) et `{ encoding: 'base64' }` pour les fichiers binaires tels que les images. Se résout avec une [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` sur refus de permission, un fichier manquant, ou une erreur de transport. Nécessite TypeScript SDK v0.2.121 ou ultérieur |652| `readFile(path, options?)` | Lit un fichier du système de fichiers de la session. Claude Code résout le chemin par rapport à `cwd` ; [Ce que `readFile()` peut lire](#what-readfile-can-read) liste les fichiers qu'il sert. Passez `{ maxBytes }` pour modifier le plafond de lecture (par défaut 1 Mo, plafond 10 Mo) et `{ encoding: 'base64' }` pour les fichiers binaires tels que les images. Se résout avec une [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` sur refus de permission, un fichier manquant, ou une erreur de transport. Nécessite TypeScript SDK v0.2.121 ou ultérieur |
651| `reloadSkills()` | Recharge les compétences à partir du disque, donc les compétences que vous ajoutez ou modifiez en milieu de session deviennent disponibles pour la session en cours d'exécution. Se résout avec une [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listant les compétences disponibles après le rechargement. Nécessite Agent SDK v0.3.163 ou ultérieur |653| `reloadSkills()` | Recharge les compétences à partir du disque, donc les compétences que vous ajoutez ou modifiez en milieu de session deviennent disponibles pour la session en cours d'exécution. Se résout avec une [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listant les compétences disponibles après le rechargement. Nécessite Agent SDK v0.3.163 ou ultérieur |
653| `reconnectMcpServer(serverName)` | Reconnecter un serveur MCP par nom. Si le nom correspond également à une entrée dans un fichier de paramètres tel que `.mcp.json` ou `~/.claude.json`, Claude Code reconnecte le serveur que vous avez configuré via [`mcpServers`](#options) ou `setMcpServers()`, pas l'entrée du fichier de paramètres. Cet ordre de résolution nécessite Claude Code v2.1.257 ou ultérieur |655| `reconnectMcpServer(serverName)` | Reconnecter un serveur MCP par nom. Si le nom correspond également à une entrée dans un fichier de paramètres tel que `.mcp.json` ou `~/.claude.json`, Claude Code reconnecte le serveur que vous avez configuré via [`mcpServers`](#options) ou `setMcpServers()`, pas l'entrée du fichier de paramètres. Cet ordre de résolution nécessite Claude Code v2.1.257 ou ultérieur |
654| `toggleMcpServer(serverName, enabled)` | Activer ou désactiver un serveur MCP par nom, avec la même résolution de nom que `reconnectMcpServer()`. La désactivation déconnecte le serveur |656| `toggleMcpServer(serverName, enabled)` | Activer ou désactiver un serveur MCP par nom, avec la même résolution de nom que `reconnectMcpServer()`. La désactivation déconnecte le serveur |
655| `setMcpServers(servers)` | Remplacer dynamiquement l'ensemble des serveurs MCP pour cette session. Se résout avec un [`McpSetServersResult`](#mcpsetserversresult) nommant les serveurs qui ont été ajoutés et supprimés, et toute erreur |657| `setMcpServers(servers)` | Remplacer dynamiquement l'ensemble des serveurs MCP pour cette session. Se résout avec un [`McpSetServersResult`](#mcpsetserversresult) nommant les serveurs qui ont été ajoutés et supprimés, et toute erreur |
658| `readMcpResource(serverName, uri)` | *Alpha.* Lit une ressource MCP Apps `ui://` à partir d'un serveur MCP connecté pour que votre application puisse afficher le widget d'un outil. Se résout avec une [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur |
656| `streamInput(stream)` | Diffuser les messages d'entrée vers la requête pour les conversations multi-tours |659| `streamInput(stream)` | Diffuser les messages d'entrée vers la requête pour les conversations multi-tours |
657| `stopTask(taskId)` | Arrêter une tâche de fond en cours d'exécution par ID |660| `stopTask(taskId)` | Arrêter une tâche de fond en cours d'exécution par ID |
658| `close()` | Fermer la requête et terminer le processus sous-jacent. Termine de force la requête et nettoie toutes les ressources |661| `close()` | Fermer la requête et terminer le processus sous-jacent. Termine de force la requête et nettoie toutes les ressources |
673 676
674Les valeurs sont écrites dans la couche de paramètres d'indicateur, la même couche que l'option `settings` en ligne de `query()` remplit au démarrage. C'est le même niveau que la [section de précédence sur la page](#settings-precedence) appelle les options programmatiques.677Les valeurs sont écrites dans la couche de paramètres d'indicateur, la même couche que l'option `settings` en ligne de `query()` remplit au démarrage. C'est le même niveau que la [section de précédence sur la page](#settings-precedence) appelle les options programmatiques.
675 678
676Les appels successifs fusionnent superficiellement les clés de niveau supérieur. Un deuxième appel avec `{ permissions: {...} }` remplace l'objet `permissions` entier de l'appel précédent plutôt que de le fusionner profondément. Pour effacer une clé de la couche d'indicateur, passez `null` pour cette clé. La plupart des clés reviennent alors aux sources de précédence inférieure. Un `model` effacé réinitialise au [modèle par défaut de Claude Code](/docs/fr/model-config), même quand un fichier de paramètres définit `model`. Passer `undefined` n'a aucun effet car la sérialisation JSON le supprime.679Les appels successifs fusionnent superficiellement les clés de niveau supérieur. Un deuxième appel avec `{ permissions: {...} }` remplace l'objet `permissions` entier de l'appel précédent plutôt que de le fusionner profondément.
680
681Pour effacer une clé que vous avez définie avec `applyFlagSettings()`, passez `null` pour cette clé. La plupart des clés reviennent alors d'abord à une valeur que l'option `settings` de `query()` a définie au démarrage, puis aux sources de précédence inférieure. Un `model` effacé réinitialise au [modèle par défaut de Claude Code](/docs/fr/model-config), même quand un fichier de paramètres définit `model`. Passer `undefined` n'a aucun effet car la sérialisation JSON le supprime.
682
683Trois clés en plus de `model` réinitialisent l'état de session au lieu de revenir :
684
685* `effortLevel: null` retourne la session au niveau d'effort par défaut du modèle, pas à l'option `effort` de `query()` ou un `effortLevel` d'un fichier de paramètres.
686* `agent: null` exécute le thread principal sans agent, à partir du tour suivant, plutôt que de restaurer l'option `agent` de `query()` ou un `agent` d'un fichier de paramètres. Si l'agent effacé avait appliqué son propre modèle, la session revient au modèle qu'elle a résolu au démarrage.
687* `ultracode: null` désactive ultracode, comme `false` le fait, plutôt que de restaurer une valeur `ultracode` d'un fichier de paramètres. La session conserve son niveau d'effort actuel, donc passez `effortLevel` dans le même appel pour le modifier.
677 688
678Disponible uniquement en mode d'entrée en diffusion, la même contrainte que `setModel()` et `setPermissionMode()`.689Disponible uniquement en mode d'entrée en diffusion, la même contrainte que `setModel()` et `setPermissionMode()`.
679 690
695 `applyFlagSettings()` est TypeScript uniquement. Le SDK Python n'expose pas de méthode équivalente.706 `applyFlagSettings()` est TypeScript uniquement. Le SDK Python n'expose pas de méthode équivalente.
696</Note>707</Note>
697 708
709<h4 id="updatesettings">
710 `updateSettings()`
711</h4>
712
713Écrit une clé autorisée dans un fichier de paramètres sur disque, pour que la valeur persiste pour les sessions ultérieures qui chargent cette source. Chaque source accepte une clé, avec une valeur de chaîne :
714
715* **`"localSettings"`** : accepte `outputStyle` et le fusionne dans le fichier de paramètres locaux du projet, `.claude/settings.local.json`. Le nouveau style prend effet à la requête suivante de la session.
716* **`"userSettings"`** : accepte `effortLevel` et l'enregistre comme le [niveau d'effort](/docs/fr/model-config#adjust-effort-level) par défaut pour le modèle actuel de la session, sous [`modelSettings`](/docs/fr/settings-reference#modelsettings) dans votre fichier de paramètres utilisateur. Passer `max` n'écrit rien, car `max` est session uniquement. La session en cours d'exécution conserve son niveau d'effort actuel de toute façon, donc appelez [`applyFlagSettings()`](#applyflagsettings) quand vous voulez aussi changer cela. Cette source nécessite TypeScript SDK v0.3.277 ou ultérieur, qui regroupe Claude Code v2.1.277.
717
718L'appel rejette quand la requête porte une autre clé, quand la session s'exécute sur un transport distant, et quand [`settingSources`](#options) de la session excluent la source que vous nommez. La suppression d'une clé n'est pas prise en charge.
719
698<h3 id="warmquery">720<h3 id="warmquery">
699 `WarmQuery`721 `WarmQuery`
700</h3>722</h3>
942 964
943`skills` liste les compétences disponibles après le rechargement, dans la même forme [`SlashCommand`](#slashcommand) que `supportedCommands()` retourne.965`skills` liste les compétences disponibles après le rechargement, dans la même forme [`SlashCommand`](#slashcommand) que `supportedCommands()` retourne.
944 966
967<h3 id="sdkcontrolmcpreadresourceresponse">
968 `SDKControlMcpReadResourceResponse`
969</h3>
970
971Type de retour de [`readMcpResource()`](#query-object), portant le résultat `resources/read` du serveur MCP. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur.
972
973```typescript theme={null}
974type SDKControlMcpReadResourceResponse = {
975 contents: {
976 uri: string;
977 mimeType?: string;
978 text?: string;
979 blob?: string;
980 _meta?: Record<string, unknown>;
981 }[];
982};
983```
984
985Passez à `readMcpResource()` le nom du serveur tel que `mcpServerStatus()` le signale et un URI `ui://`, comme le `ui.resourceUri` qu'un outil déclare dans son [`_meta`](#mcpserverstatus). L'appel rejette pour tout autre schéma d'URI, pour un [serveur MCP SDK](#createsdkmcpserver) que votre application héberge elle-même, et pour un serveur qui n'est pas connecté. C'est disponible quand le message init's [`capabilities`](#sdksystemmessage) incluent `mcp_read_resource_v1`.
986
987Chaque entrée `contents` est un élément de contenu tel que le serveur l'a envoyé. `blob` contient les données base64 pour un élément binaire, et `_meta` est le propre `_meta` de l'élément, où un serveur MCP Apps met le `ui.csp` et `ui.permissions` de la ressource. Le contenu est du HTML tiers non fiable, donc rendez-le dans un sandbox.
988
945<h3 id="agentdefinition">989<h3 id="agentdefinition">
946 `AgentDefinition`990 `AgentDefinition`
947</h3>991</h3>
1321 `SDKAssistantMessage`1365 `SDKAssistantMessage`
1322</h3>1366</h3>
1323 1367
1324Message de réponse assistant.1368Message de réponse de l'assistant.
1325 1369
1326```typescript theme={null}1370```typescript theme={null}
1327type SDKAssistantMessage = {1371type SDKAssistantMessage = {
1328 type: "assistant";1372 type: "assistant";
1329 uuid: UUID;1373 uuid: UUID;
1330 session_id: string;1374 session_id: string;
1331 message: BetaMessage; // Du SDK Anthropic1375 message: BetaMessage; // From Anthropic SDK
1332 parent_tool_use_id: string | null;1376 parent_tool_use_id: string | null;
1333 error?: SDKAssistantMessageError;1377 error?: SDKAssistantMessageError;
1334 aborted?: true;1378 aborted?: true;
1341 1385
1342Le champ `message` est un [`BetaMessage`](https://platform.claude.com/docs/fr/api/messages/create) du SDK Anthropic. Il inclut des champs comme `id`, `content`, `model`, `stop_reason` et `usage`.1386Le champ `message` est un [`BetaMessage`](https://platform.claude.com/docs/fr/api/messages/create) du SDK Anthropic. Il inclut des champs comme `id`, `content`, `model`, `stop_reason` et `usage`.
1343 1387
1344`SDKAssistantMessageError` est l'un de : `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'` ou `'unknown'`. Quatre de ces valeurs signifient plus que leurs noms le disent :1388`SDKAssistantMessageError` est l'un des suivants : `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'`, ou `'unknown'`. Quatre de ces valeurs signifient plus que leurs noms ne l'indiquent :
1345 1389
1346* `'model_not_found'` : le modèle sélectionné n'existe pas ou n'est pas disponible pour votre compte ou déploiement1390* `'model_not_found'` : le modèle sélectionné n'existe pas ou n'est pas disponible pour votre compte ou déploiement
1347* `'overloaded'` : l'API a retourné un 529 parce que le serveur est à pleine capacité, par opposition à `'rate_limit'`, qui est un 429 contre votre quota1391* `'overloaded'` : l'API a retourné un 529 parce que le serveur est à capacité, contrairement à `'rate_limit'`, qui est un 429 contre votre quota
1348* `'account_on_hold'` : [votre compte est suspendu](/docs/fr/errors#your-account-is-on-hold)1392* `'account_on_hold'` : [votre compte est suspendu](/docs/fr/errors#your-account-is-on-hold)
1349* `'cloud_credential_error'` : Claude Code n'a pas pu obtenir des identifiants AWS ou Google Cloud utilisables sur la machine sur laquelle il s'exécute, donc aucune demande n'a atteint le fournisseur cloud. La cause habituelle est une connexion cloud qui a expiré ou n'a jamais été complétée sur cette machine, bien qu'un service d'identifiants brièvement inaccessible rapporte la même valeur. Voir [Impossible de charger les identifiants AWS ou Google Cloud](/docs/fr/errors#could-not-load-aws-or-google-cloud-credentials). Nécessite TypeScript Agent SDK v0.3.267 ou ultérieur, qui regroupe Claude Code v2.1.2671393* `'cloud_credential_error'` : Claude Code n'a pas pu obtenir des identifiants AWS ou Google Cloud utilisables sur la machine sur laquelle il s'exécute, donc aucune requête n'a atteint le fournisseur cloud. La cause habituelle est une connexion cloud qui a expiré ou n'a jamais été complétée sur cette machine, bien qu'un service d'identifiants brièvement inaccessible rapporte la même valeur. Voir [Impossible de charger les identifiants AWS ou Google Cloud](/docs/fr/errors#could-not-load-aws-or-google-cloud-credentials). Nécessite TypeScript Agent SDK v0.3.267 ou ultérieur, qui regroupe Claude Code v2.1.267
1350 1394
1351`aborted` est `true` quand une interruption ou un abandon a tronqué le message assistant avant la fin du flux : le message n'a pas de `stop_reason` et le contenu peut se terminer au milieu d'un mot. Le champ est absent sur les messages normalement complétés. Il nécessite Agent SDK v0.3.214 ou ultérieur.1395`aborted` est `true` quand une interruption ou un abandon a tronqué le message de l'assistant avant la fin du flux : le message n'a pas de `stop_reason` et le contenu peut se terminer au milieu d'un mot. Le champ est absent sur les messages normalement complétés. Il nécessite Agent SDK v0.3.214 ou ultérieur.
1352 1396
1353Claude Code définit `user_message_uuid` et `user_message_uuids` sur le premier message assistant du tour, selon les conditions dans [`user_message_uuid`](#user_message_uuid).1397Claude Code définit `user_message_uuid` et `user_message_uuids` sur le premier message de l'assistant du tour, selon les conditions dans [`user_message_uuid`](#user_message_uuid).
1354 1398
1355`timestamp` est l'heure ISO 8601 quand le contenu du message a fini de générer sur le processus qui l'a produit. La valeur provient de l'horloge de cette machine, donc utilisez-la uniquement pour l'affichage et ne classez pas les messages par elle. Un tour API peut produire plusieurs messages assistant qui partagent un `message.id`, chacun avec son propre `timestamp`. Quand le champ est absent, revenez à l'heure à laquelle vous avez reçu le message.1399`timestamp` est l'heure ISO 8601 à laquelle le contenu du message a fini de générer sur le processus qui l'a produit. La valeur provient de l'horloge de cette machine, donc utilisez-la uniquement pour l'affichage et ne triez pas les messages par elle. Un tour API peut produire plusieurs messages d'assistant qui partagent un `message.id`, chacun avec son propre `timestamp`. Quand le champ est absent, revenez à l'heure à laquelle vous avez reçu le message.
1356 1400
1357`context_usage` est une copie structurée du rapport `/context`, typée comme [`SDKContextUsage`](#sdkcontextusage), et nécessite Agent SDK v0.3.232 ou ultérieur. Quand vous envoyez `/context` comme invite, Claude Code livre le rapport en tant que message assistant dont `message.content` contient le tableau markdown, et attache `context_usage` à ce même message. Claude Code ne définit pas le champ sur aucun autre message assistant, et les versions antérieures livrent le tableau `/context` sans lui, donc lisez la ventilation du champ quand il est présent et revenez au texte markdown quand il ne l'est pas.1401`context_usage` est une copie structurée du rapport `/context`, typée comme [`SDKContextUsage`](#sdkcontextusage), et nécessite Agent SDK v0.3.232 ou ultérieur. Quand vous envoyez `/context` comme invite, Claude Code livre le rapport comme un message d'assistant dont `message.content` contient le tableau markdown, et attache `context_usage` à ce même message. Claude Code ne définit pas le champ sur aucun autre message d'assistant, et les versions antérieures livrent le tableau `/context` sans lui, donc lisez la ventilation du champ quand il est présent et revenez au texte markdown quand il ne l'est pas.
1358 1402
1359<h3 id="sdkusermessage">1403<h3 id="sdkusermessage">
1360 `SDKUserMessage`1404 `SDKUserMessage`
1367 type: "user";1411 type: "user";
1368 uuid?: UUID;1412 uuid?: UUID;
1369 session_id?: string;1413 session_id?: string;
1370 message: MessageParam; // Du SDK Anthropic1414 message: MessageParam; // From Anthropic SDK
1415 pasted_content?: MessageParam["content"][];
1371 parent_tool_use_id: string | null;1416 parent_tool_use_id: string | null;
1372 isSynthetic?: boolean;1417 isSynthetic?: boolean;
1373 shouldQuery?: boolean;1418 shouldQuery?: boolean;
1374 tool_use_result?: unknown;1419 tool_use_result?: unknown;
1375 origin?: SDKMessageOrigin;1420 origin?: SDKMessageOrigin;
1421 inline_pastes?: string[];
1376};1422};
1377```1423```
1378 1424
1379Définissez `shouldQuery` sur `false` pour ajouter le message à la transcription sans déclencher un tour assistant. Le message est conservé et fusionné dans le prochain message utilisateur qui déclenche un tour. Utilisez ceci pour injecter du contexte, comme la sortie d'une commande que vous avez exécutée en dehors de la bande, sans dépenser un appel de modèle.1425Définissez `pasted_content` pour envoyer du contenu que l'utilisateur a collé dans votre interface d'invite plutôt que tapé, une entrée par collage, chacune étant une chaîne ou un tableau de blocs de contenu. Claude Code ajoute le texte de chaque entrée après le texte tapé, dans l'ordre, et peut envelopper chaque collage dans des balises `<pasted_content>`. Les blocs autres que le texte sont ignorés, donc envoyez les images et les documents dans `message.content`. Nécessite Agent SDK v0.3.277 ou ultérieur.
1426
1427Définissez `shouldQuery` à `false` pour ajouter le message à la transcription sans déclencher un tour d'assistant. Le message est conservé et fusionné dans le prochain message utilisateur qui déclenche un tour. Utilisez ceci pour injecter du contexte, comme la sortie d'une commande que vous avez exécutée hors bande, sans dépenser un appel de modèle pour cela.
1380 1428
1381Sur un message qui porte un bloc `tool_result`, `tool_use_result` est l'objet de sortie structuré de l'outil plutôt que le texte envoyé au modèle. Sa forme dépend de l'outil nommé par le bloc `tool_use` correspondant, donc le champ est typé `unknown` ; les formes intégrées sont listées sous [Types de sortie d'outil](#tool-output-types).1429Sur un message qui porte un bloc `tool_result`, `tool_use_result` est l'objet de sortie structuré de l'outil plutôt que le texte envoyé au modèle. Sa forme dépend de l'outil nommé par le bloc `tool_use` correspondant, donc le champ est typé `unknown` ; les formes intégrées sont listées sous [Types de sortie d'outil](#tool-output-types).
1382 1430
1383Pour l'outil `Agent`, `tool_use_result` est [`AgentOutput`](#agent-2). Sur un résultat `completed`, `content` contient le rapport du sous-agent sans l'ID d'agent et la remorque d'utilisation que Claude Code ajoute au texte `tool_result`, donc rendez à partir de `tool_use_result` au lieu d'analyser ce texte.1431Pour l'outil `Agent`, `tool_use_result` est [`AgentOutput`](#agent-2). Sur un résultat `completed`, `content` contient le rapport du sous-agent sans l'ID d'agent et la remorque d'utilisation que Claude Code ajoute au texte `tool_result`, donc rendez à partir de `tool_use_result` au lieu d'analyser ce texte.
1384 1432
1385Pour un outil MCP dont le résultat contient des blocs `resource_link`, `tool_use_result` est un objet avec un tableau `resourceLinks` d'entrées [`SDKMcpResourceLink`](#sdkmcpresourcelink). Claude reçoit chaque lien sous forme de ligne de texte dans le bloc `tool_result`, donc lisez `resourceLinks` pour afficher les fichiers que le serveur a retournés au lieu d'analyser ce texte. Claude Code omet `resourceLinks` quand le résultat n'a pas de liens et sur les résultats des sous-agents, conserve au maximum 50 liens par résultat, et arrête d'ajouter des liens une fois que le tableau atteint 64 KiB de JSON sérialisé. `resourceLinks` nécessite Agent SDK v0.3.257 ou ultérieur.1433Pour un outil MCP dont le résultat contient des blocs `resource_link`, `tool_use_result` est un objet avec un tableau `resourceLinks` d'entrées [`SDKMcpResourceLink`](#sdkmcpresourcelink). Claude reçoit chaque lien comme une ligne de texte dans le bloc `tool_result`, donc lisez `resourceLinks` pour rendre les fichiers que le serveur a retournés au lieu d'analyser ce texte. Claude Code omet `resourceLinks` quand le résultat n'a pas de liens et sur les résultats des sous-agents, conserve au maximum 50 liens par résultat, et arrête d'ajouter des liens une fois que le tableau atteint 64 KiB de JSON sérialisé. `resourceLinks` nécessite Agent SDK v0.3.257 ou ultérieur.
1434
1435Définissez `inline_pastes` pour dire à Claude Code quelles parties de `message.content` l'utilisateur a collées plutôt que tapées, une chaîne par collage. Le texte d'invite reste où l'utilisateur l'a mis. Claude Code peut envelopper chaque collage listé dans des balises `<pasted_content>` où il se tient, donc Claude peut distinguer le matériel collé des propres paroles de l'utilisateur. Seuls les collages du dernier bloc de texte de l'invite sont enveloppés. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur.
1386 1436
1387<h3 id="sdkusermessagereplay">1437<h3 id="sdkusermessagereplay">
1388 `SDKUserMessageReplay`1438 `SDKUserMessageReplay`
1404};1454};
1405```1455```
1406 1456
1407Un tour utilisateur injecté de l'extérieur de la session, dont le [`origin`](#sdkmessageorigin) est `peer` ou `channel`, atteint le flux en tant que relecture, qu'il ait été livré pendant un tour actif ou ait démarré un nouveau tour alors que la session était inactive. Avant v2.1.207, un tour injecté livré alors que la session était inactive ne produisait aucun message sur le flux et n'apparaissait que lorsque vous relisiez la transcription.1457Un tour utilisateur injecté de l'extérieur de la session, dont le [`origin`](#sdkmessageorigin) est de type `peer` ou `channel`, arrive sur le flux comme un rejeu qu'il ait été livré pendant un tour actif ou ait démarré un nouveau tour alors que la session était inactive. Avant v2.1.207, un tour injecté livré alors que la session était inactive ne produisait aucun message sur le flux et n'apparaissait que quand vous relisiez la transcription.
1408 1458
1409<h3 id="sdkresultmessage">1459<h3 id="sdkresultmessage">
1410 `SDKResultMessage`1460 `SDKResultMessage`
1477 };1527 };
1478```1528```
1479 1529
1480Plusieurs champs du résultat portent des détails diagnostiques au-delà du `subtype` :1530Plusieurs champs sur le résultat portent des détails de diagnostic au-delà de `subtype` :
1481 1531
1482* `api_error_status` : le code de statut HTTP de l'erreur API qui a terminé la conversation. Absent ou `null` quand le tour s'est terminé sans erreur API.1532* `api_error_status` : le code de statut HTTP de l'erreur API qui a terminé la conversation. Absent ou `null` quand le tour s'est terminé sans erreur API.
1483* `ttft_ms` : temps jusqu'au premier jeton en millisecondes, mesuré quand le premier message assistant complet arrive. Présent uniquement sur le bras de succès.1533* `ttft_ms` : temps jusqu'au premier jeton en millisecondes, mesuré quand le premier message d'assistant complet arrive. Présent sur le bras de succès uniquement.
1484* `ttft_stream_ms` : temps en millisecondes jusqu'au premier événement de flux `message_start`, quand le flux de réponse s'ouvre. Inférieur à `ttft_ms` ; l'écart entre les deux est le temps passé à diffuser le premier message. Présent uniquement sur le bras de succès.1534* `ttft_stream_ms` : temps en millisecondes jusqu'au premier événement de flux `message_start`, quand le flux de réponse s'ouvre. Inférieur à `ttft_ms` ; l'écart entre les deux est le temps passé à diffuser le premier message. Présent sur le bras de succès uniquement.
1485* `user_message_uuid` : l'`uuid` du message que vous avez envoyé qui a démarré ce tour. Voir [`user_message_uuid`](#user_message_uuid) pour savoir quels résultats le portent.1535* `user_message_uuid` : l'`uuid` du message que vous avez envoyé que ce tour a répondu. Voir [`user_message_uuid`](#user_message_uuid) pour savoir quels résultats le portent.
1486* `user_message_uuids` : les `uuid`s de chaque message que vous avez envoyé auquel Claude Code a répondu dans ce tour. Voir [`user_message_uuids`](#user_message_uuids).1536* `user_message_uuids` : les `uuid`s de chaque message que vous avez envoyé que Claude Code a répondu dans ce tour. Voir [`user_message_uuids`](#user_message_uuids).
1487* `request_sent_wall_ms` : millisecondes d'époque auxquelles Claude Code a envoyé la demande API, pour les jointures par rapport aux horodatages côté serveur. Présent uniquement avec [`user_message_uuid`](#user_message_uuid), sur un résultat de succès avec `is_error` false dont le tour a envoyé une demande API.1537* `request_sent_wall_ms` : millisecondes d'époque auxquelles Claude Code a envoyé la requête API, pour les jointures contre les horodatages côté serveur. Présent uniquement avec [`user_message_uuid`](#user_message_uuid), sur un résultat de succès avec `is_error` false dont le tour a envoyé une requête API.
1488* `first_content_frame_ms` : temps en millisecondes jusqu'au premier événement de flux `content_block_start` ou `content_block_delta`, en comptant les blocs de réflexion comme du contenu. Présent sur le bras de succès uniquement, quand `is_error` est false. Nécessite Agent SDK v0.3.260 ou ultérieur.1538* `first_content_frame_ms` : temps en millisecondes jusqu'au premier événement de flux `content_block_start` ou `content_block_delta`, en comptant les blocs de réflexion comme du contenu. Présent sur le bras de succès uniquement, quand `is_error` est false. Nécessite Agent SDK v0.3.260 ou ultérieur.
1489* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms` : chronométrages pour télécharger le premier événement de flux du tour. Claude Code les enregistre uniquement dans les sessions qu'il diffuse vers claude.ai, comme les [sessions cloud](/docs/fr/claude-code-on-the-web), et les résultats que `query()` produit ne les portent pas. Nécessite Agent SDK v0.3.260 ou ultérieur.1539* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms` : chronométrages pour télécharger le premier événement de flux du tour. Claude Code les enregistre uniquement dans les sessions qu'il diffuse à claude.ai, comme les [sessions cloud](/docs/fr/claude-code-on-the-web), et les résultats que `query()` produit ne les portent pas. Nécessite Agent SDK v0.3.260 ou ultérieur.
1490* `usage` : boucle d'agent principal uniquement. Exclut les appels de sous-agent et de modèle auxiliaire, et est par tour dans les sessions d'entrée en diffusion. Préférez `modelUsage` pour la comptabilité des jetons/coûts.1540* `usage` : boucle d'agent principal uniquement. Exclut les appels de sous-agent et de modèle auxiliaire, et est par tour dans les sessions d'entrée en flux. Préférez `modelUsage` pour la comptabilité des jetons/coûts.
1491* `modelUsage` : totaux par modèle pour chaque appel de modèle effectué via le pipeline de requête pendant cet appel `query()`, y compris la boucle principale, les sous-agents et les appels internes tels que la compaction et les agents Workflow. Les appels d'assistance en dehors de ce pipeline, tels que le classificateur de permissions et les demandes de comptage de jetons, sont exclus. Dans les sessions d'entrée en diffusion, les totaux sont cumulatifs entre les tours, donc lisez le résultat le plus récent plutôt que de faire la somme entre les résultats. Voir [Suivre les coûts en mode d'entrée en diffusion](/docs/fr/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) pour les réinitialisations et [Récupérer les totaux après un crash de session](/docs/fr/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) pour les résultats mis à zéro.1541* `modelUsage` : totaux par modèle pour chaque appel de modèle effectué via le pipeline de requête pendant cet appel `query()`, y compris la boucle principale, les sous-agents et les appels internes tels que la compaction et les agents Workflow. Les appels d'assistance en dehors de ce pipeline, comme le classificateur de permissions et les demandes de comptage de jetons, sont exclus. Un appel qui reprend une session compte également les [totaux par modèle restaurés à partir des appels antérieurs de la session](/docs/fr/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Dans les sessions d'entrée en flux, les totaux sont cumulatifs entre les tours, donc lisez le dernier résultat plutôt que de faire la somme entre les résultats. Voir [Suivre les coûts en mode d'entrée en flux](/docs/fr/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) pour les réinitialisations et [Récupérer les totaux après un crash de session](/docs/fr/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) pour les résultats mis à zéro.
1492* `total_cost_usd` : coût estimé cumulatif en USD pour cet appel `query()`, couvrant les mêmes appels que `modelUsage` et réinitialisé aux mêmes points. C'est une estimation, pas un relevé de facturation. Voir [Suivre le coût et l'utilisation](/docs/fr/agent-sdk/cost-tracking) pour les avertissements de précision.1542* `total_cost_usd` : coût estimé cumulatif en USD, couvrant les mêmes appels que `modelUsage` et réinitialisé aux mêmes points. Un appel qui reprend une session compte également les [totaux restaurés à partir des appels antérieurs de la session](/docs/fr/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). C'est une estimation, pas un relevé de facturation. Voir [Suivre le coût et l'utilisation](/docs/fr/agent-sdk/cost-tracking) pour les avertissements de précision.
1493* `queued_turn_count` : le nombre de messages que vous avez envoyés avec `origin: { kind: "human" }` qui attendent toujours quand Claude Code a produit le résultat. Voir [`queued_turn_count`](#queued_turn_count) pour ce que `0` et un champ absent vous disent.1543* `queued_turn_count` : le nombre de messages que vous avez envoyés avec `origin: { kind: "human" }` qui attendent toujours quand Claude Code a produit le résultat. Voir [`queued_turn_count`](#queued_turn_count) pour ce que `0` et un champ absent vous disent.
1494*1544* `startup_failure_reason` : pourquoi Claude Code a refusé de démarrer, sur le résultat `error_during_execution` qu'il écrit avant de quitter sur une défaillance de démarrage connue. Voir [`startup_failure_reason`](#startup_failure_reason) pour les valeurs et quelles défaillances la portent. Nécessite Agent SDK v0.3.274 ou ultérieur.
1495 1545* `terminal_reason` : pourquoi la boucle s'est terminée. L'un de `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, ou `"turn_setup_failed"`.
1496`startup_failure_reason` : pourquoi Claude Code a refusé de démarrer, sur le résultat `error_during_execution` qu'il écrit avant de quitter lors d'une défaillance de démarrage connue. Voir [`startup_failure_reason`](#startup_failure_reason) pour les valeurs et quelles défaillances la portent. Nécessite Agent SDK v0.3.274 ou ultérieur.1546* `fast_mode_state` : l'un de `"on"`, `"off"`, ou `"cooldown"`.
1497 1547* `fast_mode_disabled_reason` : pourquoi le [mode rapide](/docs/fr/fast-mode) n'est pas disponible en ce moment. Absent quand rien ne bloque le mode rapide, bien qu'une requête puisse toujours s'exécuter à vitesse standard. Pendant le refroidissement après une limite de débit du mode rapide, Claude Code rapporte `fast_mode_state: "cooldown"` sans code de raison et réactive le mode rapide quand le refroidissement expire. Nécessite Claude Code v2.1.219 ou ultérieur.
1498* `terminal_reason` : pourquoi la boucle s'est terminée. L'un de `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"` ou `"turn_setup_failed"`.
1499* `fast_mode_state` : l'un de `"on"`, `"off"` ou `"cooldown"`.
1500* `fast_mode_disabled_reason` : pourquoi le [mode rapide](/docs/fr/fast-mode) n'est pas disponible en ce moment. Absent quand rien ne bloque le mode rapide, bien qu'une demande puisse toujours s'exécuter à vitesse standard. Pendant le refroidissement après une limite de débit du mode rapide, Claude Code rapporte `fast_mode_state: "cooldown"` sans code de raison et réactive le mode rapide quand le refroidissement expire. Nécessite Claude Code v2.1.219 ou ultérieur.
1501 1548
1502Utilisez le code de raison pour expliquer pourquoi le mode rapide est désactivé dans votre propre interface utilisateur au lieu de redériver la disponibilité. Chaque code nomme la vérification qui a bloqué le mode rapide :1549Utilisez le code de raison pour expliquer pourquoi le mode rapide est désactivé dans votre propre interface utilisateur au lieu de redériver la disponibilité. Chaque code nomme la vérification qui a bloqué le mode rapide :
1503 1550
1510| `unknown` | Claude Code n'a pas pu déterminer la disponibilité |1557| `unknown` | Claude Code n'a pas pu déterminer la disponibilité |
1511| `not_first_party` | La session utilise un fournisseur autre que l'API Anthropic |1558| `not_first_party` | La session utilise un fournisseur autre que l'API Anthropic |
1512| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/fr/env-vars) est défini |1559| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/fr/env-vars) est défini |
1513| `model_not_allowed` | Le modèle Opus du mode rapide n'est pas dans la liste d'autorisation [`availableModels`](/docs/fr/model-config#restrict-model-selection) de l'organisation |1560| `model_not_allowed` | Le modèle Opus du mode rapide ne figure pas dans la liste d'autorisation [`availableModels`](/docs/fr/model-config#restrict-model-selection) de l'organisation |
1514| `sdk_opt_in_required` | La session n'a pas opté pour le mode rapide : passez `fastMode: true` dans l'option [`settings`](#options) ou via [`applyFlagSettings()`](#applyflagsettings) |1561| `sdk_opt_in_required` | La session n'a pas opté pour le mode rapide : passez `fastMode: true` dans l'option [`settings`](#options) ou via [`applyFlagSettings()`](#applyflagsettings) |
1515| `pending` | La vérification de disponibilité n'a pas encore été complétée |1562| `pending` | La vérification de disponibilité n'a pas encore été complétée |
1516 1563
1517La même paire de champs apparaît sur [`SDKSystemMessage`](#sdksystemmessage) et sur [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse), afin que vous puissiez lire l'état du mode rapide avant le premier tour.1564La même paire de champs apparaît sur [`SDKSystemMessage`](#sdksystemmessage) et sur [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse), donc vous pouvez lire l'état du mode rapide avant le premier tour.
1565
1566Le champ `origin` transmet le [`SDKMessageOrigin`](#sdkmessageorigin) du message utilisateur qui a déclenché ce résultat. Quand le SDK injecte un tour de suivi synthétique, comme pour une tâche de fond terminée, le `SDKResultMessage` résultant porte `origin: { kind: "task-notification" }`. Les routines dont le déclencheur s'est déclenché et les messages vérifiés par le serveur de vos autres sessions arrivent avec ce type aussi, chacun avec le `subkind` décrit dans [Sous-types de notification de tâche](#task-notification-subkinds). Vérifiez `kind` pour distinguer les résultats qui répondent à votre invite des suivis injectés avant de les router ou de les supprimer. Si votre application [déclare des exécutions planifiées](#declare-a-scheduled-run), leurs résultats portent `kind: "task-notification"` aussi, donc ne supprimez pas sur `kind` seul.
1518 1567
1519Le champ `origin` transmet le [`SDKMessageOrigin`](#sdkmessageorigin) du message utilisateur qui a déclenché ce résultat. Quand le SDK injecte un tour de suivi synthétique, comme pour une tâche de fond terminée, le `SDKResultMessage` résultant porte `origin: { kind: "task-notification" }`. Les routines dont le déclencheur s'est déclenché et les messages vérifiés par le serveur de vos autres sessions arrivent avec ce type aussi, chacun avec le `subkind` décrit dans [Sous-types de notification de tâche](#task-notification-subkinds). Vérifiez `kind` pour distinguer les résultats qui répondent à votre invite des suivis injectés avant de les acheminer ou de les supprimer.1568Quand plusieurs complétions de tâche de fond sont mises en file d'attente ensemble, Claude Code peut les répondre en un seul tour plutôt qu'un tour chacun. Chaque complétion produit toujours son propre résultat avec cette origine. Tous sauf le dernier des complétions que Claude Code répond ensemble produisent des résultats vides avec `num_turns: 0`, dans l'ordre, et le résultat du dernier porte le tour qui les répond tous.
1520 1569
1521Le champ est absent pour les résultats émis avant tout tour utilisateur, comme les erreurs de démarrage.1570Le champ est absent pour les résultats émis avant tout tour utilisateur, comme les erreurs de démarrage.
1522 1571
1523Quand un hook `PreToolUse` retourne `permissionDecision: "defer"`, le résultat a `stop_reason: "tool_deferred"` et `deferred_tool_use` porte l'`id`, le `name` et l'`input` de l'outil en attente. Lisez ce champ pour afficher la demande dans votre propre interface utilisateur, puis reprenez avec le même `session_id` pour continuer. Consultez [Différer un appel d'outil pour plus tard](/docs/fr/hooks#defer-a-tool-call-for-later) pour le trajet complet.1572Quand un hook `PreToolUse` retourne `permissionDecision: "defer"`, le résultat a `stop_reason: "tool_deferred"` et `deferred_tool_use` porte l'`id`, le `name` et l'`input` de l'outil en attente. Lisez ce champ pour afficher la requête dans votre propre interface utilisateur, puis reprenez avec le même `session_id` pour continuer. Voir [Différer un appel d'outil pour plus tard](/docs/fr/hooks#defer-a-tool-call-for-later) pour le trajet complet.
1524 1573
1525<h4 id="user_message_uuid">1574<h4 id="user_message_uuid">
1526 `user_message_uuid`1575 `user_message_uuid`
1527</h4>1576</h4>
1528 1577
1529L'`uuid` du [`SDKUserMessage`](#sdkusermessage) que le tour répond, répété afin que vous puissiez faire correspondre la réponse de Claude Code au message que vous avez envoyé. Claude Code le répète uniquement si vous définissez `uuid` sur ce message. Le champ est optionnel sur `SDKUserMessage`, et une invite de chaîne passée à `query()` n'en porte aucune.1578L'`uuid` du [`SDKUserMessage`](#sdkusermessage) auquel le tour répond, répété pour que vous puissiez faire correspondre la réponse de Claude Code au message que vous avez envoyé. Claude Code répète un `uuid` uniquement si vous en définissez un sur le message. Le champ est optionnel sur `SDKUserMessage`, et une invite de chaîne passée à `query()` n'en porte aucune.
1530 1579
1531Quel message de votre part un tour répond dépend de la façon dont le tour a commencé :1580Quel message de votre part un tour répond dépend de la façon dont le tour a commencé :
1532 1581
1533* **Un message régulier que vous avez envoyé**, c'est-à-dire sans `isSynthetic: true` : le tour répond à ce message pour toute sa durée. Quand vous envoyez plusieurs messages rapprochés, Claude Code peut les fusionner en un tour, et le champ porte alors uniquement l'`uuid` du dernier message. Pour faire correspondre la réponse à l'un des messages fusionnés, utilisez [`user_message_uuids`](#user_message_uuids).1582* **Un message régulier que vous avez envoyé**, c'est-à-dire sans `isSynthetic: true` : le tour répond à ce message pour toute sa durée. Quand vous envoyez plusieurs messages rapprochés, Claude Code peut les fusionner en un seul tour, et le champ porte alors uniquement l'`uuid` du dernier message. Pour faire correspondre la réponse à l'un des messages fusionnés, utilisez [`user_message_uuids`](#user_message_uuids).
1534* **Un message que vous avez envoyé avec `isSynthetic: true`** : le tour répond d'abord à ce message. Si Claude Code récupère un message régulier de votre part entre les appels d'outil, le tour répond au message récupéré à partir de là. Répéter l'`uuid` d'un message synthétique nécessite Agent SDK v0.3.265 ou ultérieur ; les versions antérieures ne répètent rien sur les tours synthétiques.1583* **Un message que vous avez envoyé avec `isSynthetic: true`** : le tour répond d'abord à ce message. Si Claude Code reprend un message régulier de votre part entre les appels d'outil, le tour répond au message repris à partir de là. Répéter l'`uuid` d'un message synthétique nécessite Agent SDK v0.3.265 ou ultérieur ; les versions antérieures ne répètent rien sur les tours synthétiques.
1535* **Une invite que Claude Code a générée lui-même**, comme le tour qui continue le travail interrompu après le redémarrage d'une session : le tour ne répond d'abord à aucun message de votre part et ses cadres ne portent aucun écho. Si Claude Code récupère un message régulier de votre part entre les appels d'outil, le tour répond à ce message à partir de là. L'écho de récupération nécessite Agent SDK v0.3.265 ou ultérieur ; les versions antérieures ne répètent rien sur ces tours.1584* **Une invite que Claude Code a générée lui-même**, comme le tour qui continue le travail interrompu après un redémarrage de session : le tour ne répond d'abord à aucun message de votre part et ses cadres ne portent aucun écho. Si Claude Code reprend un message régulier de votre part entre les appels d'outil, le tour répond à ce message à partir de là. L'écho de reprise nécessite Agent SDK v0.3.265 ou ultérieur ; les versions antérieures ne répètent rien sur ces tours.
1536 1585
1537Claude Code répète l'`uuid` du message répondu sur trois types de cadre :1586Claude Code répète l'`uuid` du message répondu sur trois types de cadre :
1538 1587
1539* **Le résultat** : chaque résultat d'un tour qui a répondu à un message que vous avez envoyé. Chaque tel résultat le porte sur Agent SDK v0.3.265 ou ultérieur. Avant v0.3.265, le résultat de succès d'un tour qu'un message régulier a commencé le manquait quand le tour n'a envoyé aucune demande API ou s'est terminé avec un appel d'outil différé. Avant v0.3.246, les résultats d'erreur le manquaient aussi, et avant v0.3.216 chaque résultat le faisait.1588* **Le résultat** : chaque résultat d'un tour qui a répondu à un message que vous avez envoyé. Chaque tel résultat le porte sur Agent SDK v0.3.265 ou ultérieur. Avant v0.3.265, le résultat de succès d'un tour qu'un message régulier a démarré lui manquait quand le tour n'a envoyé aucune requête API ou s'est terminé avec un appel d'outil différé. Avant v0.3.246, les résultats d'erreur lui manquaient aussi, et avant v0.3.216 chaque résultat le faisait.
1540* **La première réponse du tour** : le premier [message assistant](#sdkassistantmessage), ou avec `includePartialMessages` le premier [événement de flux](#sdkpartialassistantmessage) dont `event.type` n'est pas `ping`, afin que vous puissiez lier la réponse avant l'arrivée du résultat. Quand un tour ne diffuse rien, Claude Code le définit sur le premier message assistant à la place. Le premier écho de réponse nécessite Agent SDK v0.3.246 ou ultérieur. Quand le message que le tour répond change en cours de tour, le premier écho de réponse après le changement porte le champ aussi, sur Agent SDK v0.3.265 ou ultérieur ; les versions antérieures le définissent sur un cadre de réponse par tour.1589* **La première réponse du tour** : le premier [message d'assistant](#sdkassistantmessage), ou avec `includePartialMessages` le premier [événement de flux](#sdkpartialassistantmessage) dont `event.type` n'est pas `ping`, pour que vous puissiez lier la réponse avant l'arrivée du résultat. Quand un tour ne diffuse rien, Claude Code le définit sur le premier message d'assistant à la place. L'écho de première réponse nécessite Agent SDK v0.3.246 ou ultérieur. Quand le message auquel le tour répond change en cours de tour, la première réponse après le changement porte le champ aussi, sur Agent SDK v0.3.265 ou ultérieur ; les versions antérieures le définissent sur un cadre de réponse par tour.
1541* **Chaque cadre [`thinking_tokens`](#sdkthinkingtokensmessage) du tour** : afin que vous puissiez attribuer la progression de la réflexion au message que vous avez envoyé sans attendre la première réponse du tour. Nécessite Agent SDK v0.3.260 ou ultérieur.1590* **Chaque cadre [`thinking_tokens`](#sdkthinkingtokensmessage) du tour** : pour que vous puissiez attribuer la progression de la réflexion au message que vous avez envoyé sans attendre la première réponse du tour. Nécessite Agent SDK v0.3.260 ou ultérieur.
1542 1591
1543Claude Code omet le champ dans ces cas :1592Claude Code omet le champ dans ces cas :
1544 1593
1545* Cadres de réponse autres que ces premiers échos1594* Cadres de réponse autres que ces premières réponses
1546* Cadres de sous-agent1595* Cadres de sous-agent
1547* Tours qui ne répondent à aucun message avec un `uuid` : le tour a répondu à un message que vous avez envoyé sans un, ou Claude Code a commencé le tour lui-même et n'a récupéré aucun message régulier qui en a un1596* Tours qui ne répondent à aucun message avec un `uuid` : le tour a répondu à un message que vous avez envoyé sans en avoir un, ou Claude Code a démarré le tour lui-même et n'a repris aucun message régulier qui en a un
1548* Résultats qui ne répondent à aucun message que vous avez envoyé, comme le résultat mis à zéro après un crash de processus worker1597* Résultats qui ne répondent à aucun message que vous avez envoyé, comme le résultat mis à zéro après un crash de processus de travail
1549 1598
1550<h4 id="user_message_uuids">1599<h4 id="user_message_uuids">
1551 `user_message_uuids`1600 `user_message_uuids`
1552</h4>1601</h4>
1553 1602
1554Les `uuid`s de chaque message que vous avez envoyé auquel Claude Code a répondu dans ce tour. Quand vous envoyez plusieurs messages rapprochés, Claude Code peut les fusionner en un tour, et `user_message_uuid` nomme alors uniquement le dernier d'entre eux. Pour faire correspondre la réponse à l'un des messages fusionnés, cherchez l'`uuid` de ce message n'importe où dans cette liste. Nécessite Agent SDK v0.3.259 ou ultérieur.1603Les `uuid`s de chaque message que vous avez envoyé que Claude Code a répondu dans ce tour. Quand vous envoyez plusieurs messages rapprochés, Claude Code peut les fusionner en un seul tour, et `user_message_uuid` nomme alors uniquement le dernier d'entre eux. Pour faire correspondre la réponse à l'un des messages fusionnés, cherchez l'`uuid` de ce message n'importe où dans cette liste. Nécessite Agent SDK v0.3.259 ou ultérieur.
1555 1604
1556Claude Code définit la liste avec `user_message_uuid` sur chaque cadre de réponse qui porte ce champ et sur le résultat. Pour l'ensemble complet des cadres qui portent `user_message_uuid`, et la version que chacun nécessite, voir [`user_message_uuid`](#user_message_uuid). La liste contient toujours `user_message_uuid` et contient au maximum 64 entrées.1605Claude Code définit la liste avec `user_message_uuid` sur chaque cadre de réponse qui porte ce champ et sur le résultat. Pour l'ensemble complet des cadres qui portent `user_message_uuid`, et la version que chacun nécessite, voir [`user_message_uuid`](#user_message_uuid). La liste contient toujours `user_message_uuid` et contient au maximum 64 entrées.
1557 1606
1558Quand Claude Code récupère un message régulier que vous avez envoyé pendant qu'un tour s'exécutait, il ajoute l'`uuid` de ce message à la liste du résultat.1607Quand Claude Code reprend un message régulier que vous avez envoyé pendant qu'un tour s'exécutait, il ajoute l'`uuid` de ce message à la liste du résultat.
1559 1608
1560Quand une première réponse ou un résultat porte `user_message_uuid` sans la liste, il provient d'une version antérieure de Claude Code, donc revenez au champ unique.1609Quand une première réponse ou un résultat porte `user_message_uuid` sans la liste, il provient d'une version antérieure de Claude Code, donc revenez au champ unique.
1561 1610
1563 `queued_turn_count`1612 `queued_turn_count`
1564</h4>1613</h4>
1565 1614
1566Le nombre de messages que vous avez envoyés avec [`origin: { kind: "human" }`](#sdkmessageorigin) qui attendent toujours dans la file d'attente de commandes quand Claude Code a produit le résultat. Nécessite Agent SDK v0.3.242 ou ultérieur.1615Le nombre de messages que vous avez envoyés avec [`origin: { kind: "human" }`](#sdkmessageorigin) qui attendent toujours dans la file de commandes quand Claude Code a produit le résultat. Nécessite Agent SDK v0.3.242 ou ultérieur.
1567 1616
1568Ce que `0` et un champ absent vous disent :1617Ce que `0` et un champ absent vous disent :
1569 1618
1570* **`0`** : Claude Code ne compte pas les messages que vous avez envoyés sans cet `origin`, et ne compte pas les notifications de tâche, donc un tour peut toujours suivre.1619* **`0`** : Claude Code ne compte pas les messages que vous avez envoyés sans ce `origin`, et ne compte pas les notifications de tâche, donc un tour peut toujours suivre.
1571* **Absent** : le résultat final que Claude Code émet après un crash ou une erreur de démarrage fatale omet le champ, et [peut porter des totaux mis à zéro](/docs/fr/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).1620* **Absent** : le résultat final que Claude Code émet après un crash ou une erreur de démarrage fatale omet le champ, et [peut porter des totaux mis à zéro](/docs/fr/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).
1572 1621
1573<h4 id="startup_failure_reason">1622<h4 id="startup_failure_reason">
1574 `startup_failure_reason`1623 `startup_failure_reason`
1575</h4>1624</h4>
1576 1625
1577Pourquoi Claude Code a refusé de démarrer, afin que votre application puisse offrir la correction au lieu d'une nouvelle tentative. Claude Code le définit sur le résultat `error_during_execution` qu'il écrit avant de quitter lors d'une défaillance de démarrage connue. Ce résultat porte des totaux mis à zéro, et son tableau `errors` porte le même texte que stderr. Le champ est absent sur tous les autres résultats. Nécessite Agent SDK v0.3.274 ou ultérieur.1626Pourquoi Claude Code a refusé de démarrer, pour que votre application puisse offrir la correction au lieu d'une nouvelle tentative. Claude Code le définit sur le résultat `error_during_execution` qu'il écrit avant de quitter sur une défaillance de démarrage connue. Ce résultat porte des totaux mis à zéro, et son tableau `errors` porte le même texte que stderr. Le champ est absent sur tous les autres résultats. Nécessite Agent SDK v0.3.274 ou ultérieur.
1578 1627
1579Définissez `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` sur `1` dans [`env`](#options) pour recevoir ce résultat pour chaque valeur `SDKStartupFailureReason`. Sans cette variable, Claude Code écrit le résultat uniquement pour ces défaillances, et le reste se termine par une sortie stderr, un code de sortie non-zéro et aucun message de résultat :1628Définissez `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` à `1` dans [`env`](#options) pour recevoir ce résultat pour chaque valeur `SDKStartupFailureReason`. Sans cette variable, Claude Code écrit le résultat uniquement pour ces défaillances, et le reste se termine par une sortie stderr, un code de sortie non nul et aucun message de résultat :
1580 1629
1581* Une reprise que Claude Code arrête parce qu'il [ne peut pas retourner la session à son worktree](/docs/fr/worktrees#the-session-resumes-outside-its-worktree), avec `worktree_unverified` ou `worktree_resume_refused`. Cette section dit quel erreur porte quelle valeur.1630* Une reprise que Claude Code arrête parce qu'elle [ne peut pas retourner la session à son worktree](/docs/fr/worktrees#the-session-resumes-outside-its-worktree), avec `worktree_unverified` ou `worktree_resume_refused`. Cette section dit quelle erreur porte quelle valeur.
1582* Une [`continue`](#options) refusée d'une conversation qu'une session de fond tient, avec `session_held_by_background`. Pour une [`resume`](#options) refusée d'une telle conversation, Claude Code écrit le résultat uniquement quand la variable est définie.1631* Une [`continue`](#options) refusée d'une conversation qu'une session de fond tient, avec `session_held_by_background`. Pour une [`resume`](#options) refusée d'une telle conversation, Claude Code écrit le résultat uniquement quand la variable est définie.
1583 1632
1584```typescript theme={null}1633```typescript theme={null}
1604Chaque valeur nomme un refus :1653Chaque valeur nomme un refus :
1605 1654
1606| Valeur | Ce qui a arrêté la session |1655| Valeur | Ce qui a arrêté la session |
1607| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1656| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1608| `org_pin_api_key_conflict` | Les paramètres gérés [nécessitent une connexion de passerelle de première partie ou Cloud](/docs/fr/authentication#restrict-login-to-your-organization), et une clé API Anthropic, un jeton d'authentification ou un `apiKeyHelper` est configuré à la place |1657| `org_pin_api_key_conflict` | Les paramètres gérés [nécessitent une connexion de première partie ou Cloud gateway](/docs/fr/authentication#restrict-login-to-your-organization), et une clé API Anthropic, un jeton d'authentification ou un `apiKeyHelper` est configuré à la place |
1609| `org_verify_failed` | L'organisation de la connexion n'a pas pu être vérifiée par rapport à la broche, par exemple en raison d'une défaillance réseau ou d'un jeton révoqué |1658| `org_verify_failed` | L'organisation de la connexion n'a pas pu être vérifiée par rapport à la broche, par exemple en raison d'une défaillance réseau ou d'un jeton révoqué |
1610| `org_pin_mismatch` | La connexion appartient à une organisation que la broche ne permet pas |1659| `org_pin_mismatch` | La connexion appartient à une organisation que la broche ne permet pas |
1611| `managed_settings_invalid` | Les paramètres de politique gérée n'ont pas pu être lus, ou la broche ne nomme aucune organisation |1660| `managed_settings_invalid` | Les paramètres de politique gérés n'ont pas pu être lus, ou la broche ne nomme aucune organisation |
1612| `remote_settings_required_unavailable` | Les paramètres gérés que l'organisation nécessite n'ont pas pu être chargés |1661| `remote_settings_required_unavailable` | Les paramètres gérés que l'organisation nécessite n'ont pas pu être chargés |
1613| `gateway_signin_required` | La [passerelle Cloud](/docs/fr/claude-apps-gateway) a terminé cette connexion |1662| `gateway_signin_required` | La [Cloud gateway](/docs/fr/claude-apps-gateway) a terminé cette connexion |
1614| `gateway_access_denied` | La demande de paramètres gérés à la passerelle Cloud est revenue avec un 403, que le [tableau de dépannage](/docs/fr/claude-apps-gateway-deploy#troubleshooting) de la passerelle couvre |1663| `gateway_access_denied` | La demande de paramètres gérés à la Cloud gateway est revenue avec un 403, que la [table de dépannage](/docs/fr/claude-apps-gateway-deploy#troubleshooting) de la gateway couvre |
1615| `proxy_invalid` | Un paramètre de proxy n'est pas une URL complète |1664| `proxy_invalid` | Un paramètre de proxy n'est pas une URL complète |
1616| `temp_dir_unusable` | Le répertoire temporaire par utilisateur n'est pas sûr ou n'a pas pu être créé |1665| `temp_dir_unusable` | Le répertoire temporaire par utilisateur n'est pas sûr ou n'a pas pu être créé |
1617| `cwd_unavailable` | Le répertoire de travail a été supprimé, déplacé ou ne peut pas être lu |1666| `cwd_unavailable` | Le répertoire de travail a été supprimé, déplacé ou ne peut pas être lu |
1618| `shell_tool_missing` | Sur Windows, aucun outil shell n'est disponible : Git Bash est manquant, et PowerShell est manquant ou désactivé avec `CLAUDE_CODE_USE_POWERSHELL_TOOL` |1667| `shell_tool_missing` | Sur Windows, aucun outil shell n'est disponible : Git Bash manque, et PowerShell manque ou est désactivé avec `CLAUDE_CODE_USE_POWERSHELL_TOOL` |
1619| `session_held_by_background` | La conversation à reprendre ou continuer s'exécute en tant que [session de fond](/docs/fr/agent-view) |1668| `session_held_by_background` | La conversation à reprendre ou continuer s'exécute comme une [session de fond](/docs/fr/agent-view) |
1620| `worktree_resume_refused` | Le worktree de la session a échoué ses vérifications de sécurité, ou la reprise a été lancée de l'intérieur. `errors` dit si l'exécution de la même reprise continue sans le worktree |1669| `worktree_resume_refused` | Le worktree de la session a échoué ses vérifications de sécurité, ou la reprise a été lancée de l'intérieur. `errors` dit si l'exécution de la même reprise continue sans le worktree |
1621| `worktree_unverified` | Le worktree de la session n'a pas pu être vérifié en ce moment, et une nouvelle tentative peut réussir |1670| `worktree_unverified` | Le worktree de la session n'a pas pu être vérifié en ce moment, et une nouvelle tentative peut réussir |
1622| `cli_version_too_old` | Cette version de Claude Code est inférieure au minimum qu'Anthropic nécessite |1671| `cli_version_too_old` | Cette version de Claude Code est inférieure au minimum qu'Anthropic nécessite |
1626 `SDKSystemMessage`1675 `SDKSystemMessage`
1627</h3>1676</h3>
1628 1677
1629Message d'initialisation système.1678Message d'initialisation du système.
1630 1679
1631```typescript theme={null}1680```typescript theme={null}
1632type SDKSystemMessage = {1681type SDKSystemMessage = {
1661 1710
1662`fast_mode_state` rapporte l'état du [mode rapide](/docs/fr/fast-mode) de la session. Quand quelque chose bloque le mode rapide, `fast_mode_disabled_reason` nomme la vérification qui l'a bloqué ; le champ nécessite Claude Code v2.1.219 ou ultérieur. Pour les codes de raison et leurs significations, voir [`fast_mode_disabled_reason`](#sdkresultmessage) sur le message de résultat.1711`fast_mode_state` rapporte l'état du [mode rapide](/docs/fr/fast-mode) de la session. Quand quelque chose bloque le mode rapide, `fast_mode_disabled_reason` nomme la vérification qui l'a bloqué ; le champ nécessite Claude Code v2.1.219 ou ultérieur. Pour les codes de raison et leurs significations, voir [`fast_mode_disabled_reason`](#sdkresultmessage) sur le message de résultat.
1663 1712
1664`terminal_slash_commands` nomme les entrées dans `slash_commands` dont l'interface est liée au terminal local, comme `exit`. Vous pouvez les envoyer comme n'importe quelle autre entrée dans `slash_commands` ; le champ existe afin qu'un client distant ou mobile puisse les masquer de ses menus de commandes. Le champ est présent uniquement quand non vide, et nécessite Agent SDK v0.3.229 ou ultérieur.1713`terminal_slash_commands` nomme les entrées dans `slash_commands` dont l'interface est liée au terminal local, comme `exit`. Vous pouvez les envoyer comme n'importe quelle autre entrée dans `slash_commands` ; le champ existe pour qu'un client distant ou mobile puisse les masquer de ses menus de commandes. Le champ est présent uniquement quand non vide, et nécessite Agent SDK v0.3.229 ou ultérieur.
1665 1714
1666*1715*
1667 1716
1668`source` sur chaque entrée `mcp_servers` : d'où provient la définition du serveur, avec les mêmes valeurs que [`McpServerStatus`](#mcpserverstatus)'s `source`. Nécessite Agent SDK v0.3.274 ou ultérieur.1717`source` sur chaque entrée `mcp_servers` : d'où provient la définition du serveur, avec les mêmes valeurs que `source` de [`McpServerStatus`](#mcpserverstatus). Nécessite Agent SDK v0.3.274 ou ultérieur.
1669 1718
1670*1719*
1671 1720
1672`effort` : le [niveau d'effort](/docs/fr/model-config#adjust-effort-level) que Claude Code envoie sur la prochaine demande de la session, ou `null` quand il n'en envoie aucun. Claude Code définit le champ uniquement sur le message d'initialisation qu'il envoie aux clients [Remote Control](/docs/fr/remote-control), et l'omet du message d'initialisation que votre application lit. Nécessite Agent SDK v0.3.234 ou ultérieur.1721`effort` : le [niveau d'effort](/docs/fr/model-config#adjust-effort-level) que Claude Code envoie sur la prochaine requête de la session, ou `null` quand il n'en envoie aucun. Claude Code définit le champ uniquement sur le message d'initialisation qu'il envoie aux clients [Remote Control](/docs/fr/remote-control), et l'omet du message d'initialisation que votre application lit. Nécessite Agent SDK v0.3.234 ou ultérieur.
1673 1722
1674Le tableau `capabilities` nomme les comportements de protocole que ce CLI implémente, afin que vous puissiez détecter les fonctionnalités au lieu de comparer les chaînes `claude_code_version`. C'est un ensemble ouvert : ignorez les valeurs que vous ne reconnaissez pas, et vérifiez la capacité spécifique dont vous dépendez. Le champ nécessite Claude Code v2.1.205 ou ultérieur et est absent sur les CLI antérieurs.1723Le tableau `capabilities` nomme les comportements de protocole que cette CLI implémente, pour que vous puissiez faire de la détection de fonctionnalités au lieu de comparer les chaînes `claude_code_version`. C'est un ensemble ouvert : ignorez les valeurs que vous ne reconnaissez pas, et vérifiez la capacité spécifique dont vous dépendez du comportement. Le champ nécessite Claude Code v2.1.205 ou ultérieur et est absent sur les CLI antérieures.
1675 1724
1676| Capacité | Signification |1725| Capacité | Signification |
1677| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1726| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1678| `interrupt_receipt_v1` | [`interrupt()`](#query-object) se résout avec une réception [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) nommant les messages qui étaient en attente quand l'interruption est arrivée |1727| `interrupt_receipt_v1` | [`interrupt()`](#query-object) se résout avec un reçu [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) listant les messages qui étaient en attente quand l'interruption est arrivée |
1679| `interrupt_cancel_queued_v1` | La demande de contrôle `interrupt` honore `cancel_queued: true`, annulant les messages que la réception énumérerait autrement sous `still_queued` et les énumérant sous `cancelled` à la place. Voir [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse). Nécessite Claude Code v2.1.219 ou ultérieur |1728| `interrupt_cancel_queued_v1` | La demande de contrôle `interrupt` honore `cancel_queued: true`, annulant les messages que le reçu listerait autrement sous `still_queued` et les listant sous `cancelled` à la place. Voir [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse). Nécessite Claude Code v2.1.219 ou ultérieur |
1680 1729
1681<h3 id="sdkpartialassistantmessage">1730<h3 id="sdkpartialassistantmessage">
1682 `SDKPartialAssistantMessage`1731 `SDKPartialAssistantMessage`
1683</h3>1732</h3>
1684 1733
1685Message partiel en diffusion (uniquement quand `includePartialMessages` est true). Le champ `parent_tool_use_id` est toujours `null` : les événements de flux sont émis pour la session principale uniquement. Pour l'attribution de sous-agent, utilisez les messages complets, qui portent `parent_tool_use_id`, ou activez [`forwardSubagentText`](#options) pour recevoir le texte et la réflexion du sous-agent en tant que messages complets.1734Message partiel en flux (uniquement quand `includePartialMessages` est true). Le champ `parent_tool_use_id` est toujours `null` : les événements de flux sont émis pour la session principale uniquement. Pour l'attribution de sous-agent, utilisez les messages complets, qui portent `parent_tool_use_id`, ou activez [`forwardSubagentText`](#options) pour recevoir le texte et la réflexion du sous-agent comme des messages complets.
1686 1735
1687```typescript theme={null}1736```typescript theme={null}
1688type SDKPartialAssistantMessage = {1737type SDKPartialAssistantMessage = {
1689 type: "stream_event";1738 type: "stream_event";
1690 event: BetaRawMessageStreamEvent; // Du SDK Anthropic1739 event: BetaRawMessageStreamEvent; // From Anthropic SDK
1691 parent_tool_use_id: string | null;1740 parent_tool_use_id: string | null;
1692 uuid: UUID;1741 uuid: UUID;
1693 session_id: string;1742 session_id: string;
1694 ttft_ms?: number; // Temps jusqu'au premier jeton en ms, présent uniquement sur les événements message_start1743 ttft_ms?: number; // Time to first token in ms, present only on message_start events
1695 user_message_uuid?: string;1744 user_message_uuid?: string;
1696 user_message_uuids?: string[];1745 user_message_uuids?: string[];
1697};1746};
1698```1747```
1699 1748
1700Claude Code définit `user_message_uuid` et `user_message_uuids` sur le premier événement de flux non-ping du tour, et à nouveau quand le message que le tour répond change, selon les conditions dans [`user_message_uuid`](#user_message_uuid).1749Claude Code définit `user_message_uuid` et `user_message_uuids` sur le premier événement de flux non-ping du tour, et à nouveau quand le message auquel le tour répond change, selon les conditions dans [`user_message_uuid`](#user_message_uuid).
1701 1750
1702<h3 id="sdkcompactboundarymessage">1751<h3 id="sdkcompactboundarymessage">
1703 `SDKCompactBoundaryMessage`1752 `SDKCompactBoundaryMessage`
1722 `SDKInformationalMessage`1771 `SDKInformationalMessage`
1723</h3>1772</h3>
1724 1773
1725Bannière de texte générique émise par la boucle. Porte les lignes d'état non-erreur, les retours de hook comme la raison de blocage d'un hook `UserPromptSubmit`, et la sortie de commande. Sur Claude Code v2.1.227 ou ultérieur, le [`systemMessage`](/docs/fr/hooks#json-output) d'un hook peut arriver en tant que ce message, avec chaque ligne préfixée par le nom du hook, comme `PostToolUse:Bash says:`. Qu'un `systemMessage` d'un hook arrive en tant que ce message dépend de l'événement. La section de chaque [événement](/docs/fr/hooks#hook-events) sur la page des hooks dit comment la sortie s'affiche. Rendez `content` en texte brut au `level` donné.1774Bannière de texte générique émise par la boucle. Porte les lignes d'état non-erreur, les retours de hook comme la raison du blocage d'un hook `UserPromptSubmit`, et la sortie de commande. Sur Claude Code v2.1.227 ou ultérieur, le [`systemMessage`](/docs/fr/hooks#json-output) d'un hook peut arriver comme ce message, avec chaque ligne préfixée par le nom du hook, comme `PostToolUse:Bash says:`. Qu'un `systemMessage` d'un hook arrive comme ce message dépend de l'événement. Chaque [section d'événement](/docs/fr/hooks#hook-events) sur la page des hooks dit comment la sortie s'affiche. Rendez `content` comme texte brut au `level` donné.
1726 1775
1727```typescript theme={null}1776```typescript theme={null}
1728type SDKInformationalMessage = {1777type SDKInformationalMessage = {
1741 `SDKWorkerShuttingDownMessage`1790 `SDKWorkerShuttingDownMessage`
1742</h3>1791</h3>
1743 1792
1744Émis lors de l'arrêt gracieux du worker afin que les clients distants puissent montrer pourquoi le worker a disparu au lieu d'attendre l'expiration du heartbeat. La `reason` est une courte chaîne snake\_case définie par le CLI hôte, comme `"host_exit"` ou `"remote_control_disabled"`. Agissez sur ceci uniquement lors de la diffusion en direct. Une session reprise rejoue les instances passées de ce message, donc ignorez-les dans ce cas.1793Émis lors d'un arrêt gracieux du travailleur pour que les clients de contrôle à distance puissent montrer pourquoi le travailleur a quitté au lieu d'attendre l'expiration du délai d'attente du battement de cœur. La `reason` est une courte chaîne snake\_case définie par la CLI hôte, comme `"host_exit"` ou `"remote_control_disabled"`. Agissez sur ceci uniquement lors de la diffusion en direct. Une session reprise rejoue les instances passées de ce message, donc ignorez-les dans ce cas.
1745 1794
1746```typescript theme={null}1795```typescript theme={null}
1747type SDKWorkerShuttingDownMessage = {1796type SDKWorkerShuttingDownMessage = {
1757 `SDKPluginInstallMessage`1806 `SDKPluginInstallMessage`
1758</h3>1807</h3>
1759 1808
1760Événement de progression d'installation de plugin. Émis quand [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/fr/env-vars) est défini, pour que votre application Agent SDK puisse suivre l'installation du plugin de marketplace avant le premier tour. Les statuts `started` et `completed` encadrent l'installation globale. Les statuts `installed` et `failed` rapportent les marchés individuels et incluent `name`.1809Événement de progression d'installation de plugin. Émis quand [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/fr/env-vars) est défini, pour que votre application Agent SDK puisse suivre l'installation du plugin de marketplace avant le premier tour. Les statuts `started` et `completed` encadrent l'installation globale. Les statuts `installed` et `failed` rapportent les marketplaces individuels et incluent `name`.
1761 1810
1762```typescript theme={null}1811```typescript theme={null}
1763type SDKPluginInstallMessage = {1812type SDKPluginInstallMessage = {
1775 `SDKPermissionDeniedMessage`1824 `SDKPermissionDeniedMessage`
1776</h3>1825</h3>
1777 1826
1778Événement de flux émis quand le système de permissions refuse un appel d'outil sans invite interactive. Utilisez-le pour afficher le refus dans votre interface utilisateur au fur et à mesure, plutôt que d'observer uniquement le résultat d'outil `is_error` qui suit. Lequel des refus il rapporte dépend de la façon dont l'exécution gère les invites de permissions :1827Événement de flux émis quand le système de permissions refuse un appel d'outil sans invite interactive. Utilisez-le pour rendre le refus dans votre interface utilisateur au fur et à mesure, plutôt que d'observer uniquement le résultat d'outil `is_error` qui suit. Quels refus il rapporte dépend de la façon dont l'exécution gère les invites de permissions :
1779 1828
1780* **Avec un callback [`canUseTool`](#canusetool) et le [`permissionPrompts: 'host'`](#options) par défaut** : les invites de permissions vont à votre callback, et cet événement rapporte les refus que Claude Code décide par lui-même sans l'appeler.1829* **Avec un rappel [`canUseTool`](#canusetool) et le [`permissionPrompts: 'host'`](#options) par défaut** : les invites de permissions vont à votre rappel, et cet événement rapporte les refus que Claude Code décide par lui-même sans l'appeler.
1781* **Sans aucun des deux** : une exécution `-p` nue, ou `query()` qui ne définit ni `canUseTool` ni `permissionPromptToolName`, refuse tout appel d'outil qui aurait invité, et cet événement rapporte aussi ces refus ainsi que ceux que Claude Code décide par lui-même. Avant v2.1.223, Claude Code n'émettait pas cet événement dans les exécutions sans callback.1830*
1782* **Avec un outil de prompt MCP**, défini avec `permissionPromptToolName` ou le drapeau [`--permission-prompt-tool`](/docs/fr/cli-reference#cli-flags), et le `permissionPrompts: 'host'` par défaut : Claude Code n'émet pas du tout cet événement, pas même pour les refus de règles qu'il décide par lui-même.
1783* **Avec [`permissionPrompts: 'none'`](#options)** : Claude Code refuse les appels qui auraient invité, même quand `canUseTool` ou un outil de prompt MCP est aussi défini, et cet événement rapporte aussi ces refus ainsi que ceux que Claude Code décide par lui-même. Nécessite Claude Code v2.1.259 ou ultérieur.
1784 1831
1785Dans chaque configuration, cet événement ignore tout refus décidé sur le chemin du hook `PreToolUse`, que le hook ait refusé l'appel lui-même ou qu'une règle de refus ait remplacé la décision d'autorisation ou de demande du hook. L'événement est aussi au mieux : occasionnellement Claude Code enregistre un refus sans émettre cet événement, donc `permission_denials` sur le [message de résultat](#sdkresultmessage) est le registre faisant autorité.1832**Avec aucun des deux** : une exécution `-p` nue, ou `query()` qui ne définit ni `canUseTool` ni `permissionPromptToolName`, refuse tout appel d'outil qui aurait invité, et cet événement rapporte ces refus ainsi que ceux que Claude Code décide par lui-même. Avant v2.1.223, Claude Code n'émettait pas cet événement dans les exécutions sans rappel.
1833
1834* **Avec un outil d'invite MCP**, défini avec `permissionPromptToolName` ou le drapeau [`--permission-prompt-tool`](/docs/fr/cli-reference#cli-flags), et le `permissionPrompts: 'host'` par défaut : Claude Code n'émet pas du tout cet événement, pas même pour les refus de règle qu'il décide par lui-même.
1835*
1836
1837**Avec [`permissionPrompts: 'none'`](#options)** : Claude Code refuse les appels qui auraient invité, même quand `canUseTool` ou un outil d'invite MCP est aussi défini, et cet événement rapporte ces refus ainsi que ceux que Claude Code décide par lui-même. Nécessite Claude Code v2.1.259 ou ultérieur.
1838
1839Dans chaque configuration, cet événement ignore tout refus décidé sur le chemin du hook `PreToolUse`, que le hook ait refusé l'appel lui-même ou qu'une règle de refus ait remplacé la décision d'autorisation ou de demande du hook. L'événement est aussi du meilleur effort : occasionnellement Claude Code enregistre un refus sans émettre cet événement, donc `permission_denials` sur le [message de résultat](#sdkresultmessage) est le registre faisant autorité.
1786 1840
1787```typescript theme={null}1841```typescript theme={null}
1788type SDKPermissionDeniedMessage = {1842type SDKPermissionDeniedMessage = {
1800```1854```
1801 1855
1802| Champ | Type | Description |1856| Champ | Type | Description |
1803| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |1857| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
1804| `tool_name` | `string` | Nom de l'outil qui a été refusé |1858| `tool_name` | `string` | Nom de l'outil qui a été refusé |
1805| `tool_use_id` | `string` | ID du bloc `tool_use` auquel ce refus répond |1859| `tool_use_id` | `string` | ID du bloc `tool_use` auquel ce refus répond |
1806| `agent_id` | `string` | ID du sous-agent quand l'appel refusé provient d'un sous-agent. Reflète le champ sur `can_use_tool` pour l'acheminement côté hôte |1860| `agent_id` | `string` | ID du sous-agent quand l'appel refusé provient de l'intérieur d'un sous-agent. Reflète le champ sur `can_use_tool` pour le routage côté hôte |
1807| `decision_reason_type` | `string` | Discriminateur du composant qui a décidé, tel que `"rule"`, `"mode"`, `"classifier"` ou `"asyncAgent"` |1861| `decision_reason_type` | `string` | Discriminateur pour le composant qui a décidé, comme `"rule"`, `"mode"`, `"classifier"`, ou `"asyncAgent"` |
1808| `decision_reason` | `string` | Raison lisible par l'homme du composant décideur, quand disponible |1862| `decision_reason` | `string` | Raison lisible par l'homme du composant décideur, quand disponible |
1809| `message` | `string` | Message de rejet retourné au modèle dans le `tool_result` |1863| `message` | `string` | Message de rejet retourné au modèle dans le `tool_result` |
1810 1864
1812 `SDKPermissionDenial`1866 `SDKPermissionDenial`
1813</h3>1867</h3>
1814 1868
1815Informations sur une utilisation d'outil refusée.1869Information sur un usage d'outil refusé.
1816 1870
1817```typescript theme={null}1871```typescript theme={null}
1818type SDKPermissionDenial = {1872type SDKPermissionDenial = {
1826 `SDKContextUsage`1880 `SDKContextUsage`
1827</h3>1881</h3>
1828 1882
1829Forme structurée du rapport `/context`, portée comme `context_usage` sur le [`SDKAssistantMessage`](#sdkassistantmessage) qui livre un résultat `/context`. Agent SDK v0.3.232 et ultérieur exportent le type. Contrairement à [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), il porte uniquement les données nécessaires pour afficher la ventilation d'utilisation, sans champs d'affichage tels que `color` et `gridRows`.1883Forme structurée du rapport `/context`, portée comme `context_usage` sur le [`SDKAssistantMessage`](#sdkassistantmessage) qui livre un résultat `/context`. Agent SDK v0.3.232 et ultérieur exportent le type. Contrairement à [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), il porte uniquement les données nécessaires pour rendre la ventilation d'utilisation, sans champs d'affichage comme `color` et `gridRows`.
1830 1884
1831```typescript theme={null}1885```typescript theme={null}
1832type SDKContextUsage = {1886type SDKContextUsage = {
1863};1917};
1864```1918```
1865 1919
1866Le tableau énumère ce que Claude Code met dans chaque champ. Les champs de `model` à `over_limit` décrivent la session dans son ensemble, et les champs de collection attribuent les jetons aux éléments individuels.1920Le tableau liste ce que Claude Code met dans chaque champ. Les champs de `model` à `over_limit` décrivent la session dans son ensemble, et les champs de collection attribuent les jetons aux éléments individuels.
1867 1921
1868| Champ | Type | Description |1922| Champ | Type | Description |
1869| ---------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1923| ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1870| `model` | `string` | Le modèle de la boucle principale pour lequel Claude Code a calculé l'utilisation, pas celui d'un sous-agent |1924| `model` | `string` | Le modèle de la boucle principale pour lequel Claude Code a calculé l'utilisation, pas celui d'un sous-agent |
1871| `total_tokens` | `number` | L'estimation de Claude Code des jetons en utilisation. Non limité à la fenêtre, donc il peut dépasser `raw_max_tokens` quand la session dépasse la limite |1925| `total_tokens` | `number` | L'estimation de Claude Code des jetons en utilisation. Non limité à la fenêtre, donc il peut dépasser `raw_max_tokens` quand la session dépasse la limite |
1872| `raw_max_tokens` | `number` | La fenêtre de contexte du modèle, ou la [fenêtre de compaction automatique](/docs/fr/model-config#context-window-and-auto-compaction) inférieure quand une s'applique, comme une que vous avez définie ou la limite de 200K que Claude Code applique à certains modèles avec une fenêtre de 1M jetons. Claude Code mesure `total_tokens` par rapport à cette fenêtre |1926| `raw_max_tokens` | `number` | La fenêtre de contexte du modèle, ou la [fenêtre de compaction automatique](/docs/fr/model-config#context-window-and-auto-compaction) inférieure quand une s'applique, comme une que vous définissez ou la limite de 200K que Claude Code applique à certains modèles avec une fenêtre de 1M de jetons. Claude Code mesure `total_tokens` par rapport à cette fenêtre |
1873| `percentage` | `number` | `total_tokens` en pourcentage arrondi de `raw_max_tokens`, donc il peut dépasser 100 quand la session dépasse la limite |1927| `percentage` | `number` | `total_tokens` en pourcentage arrondi de `raw_max_tokens`, donc il peut dépasser 100 quand la session dépasse la limite |
1874| `over_limit` | `object` | Présent uniquement quand `total_tokens` dépasse `raw_max_tokens`. `tokens_over` est le montant au-delà, et `kind` dit comment Claude Code a résolu la fenêtre |1928| `over_limit` | `object` | Présent uniquement quand `total_tokens` dépasse `raw_max_tokens`. `tokens_over` est le montant au-dessus, et `kind` dit comment Claude Code a résolu la fenêtre |
1875| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | Une entrée par ligne de la ventilation d'utilisation par catégorie |1929| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | Une entrée par ligne de la ventilation d'utilisation par catégorie |
1876| `mcp_tools` | `object[]` | Jetons attribués à chaque outil MCP, avec son nom de fil, comme `mcp__linear__create_issue`, et son `server_name` |1930| `mcp_tools` | `object[]` | Jetons attribués à chaque outil MCP, avec son nom de fil, comme `mcp__linear__create_issue`, et son `server_name` |
1877| `memory_files` | `object[]` | Jetons attribués à chaque fichier de mémoire chargé, avec son `path` et une étiquette de source comme `Project` ou `User` dans `type` |1931| `memory_files` | `object[]` | Jetons attribués à chaque fichier de mémoire chargé, avec son `path` et une étiquette source comme `Project` ou `User` dans `type` |
1878| `agents` | `object[]` | Jetons attribués à chaque définition de sous-agent personnalisé, avec un identifiant de source comme `projectSettings`, `userSettings` ou `plugin`. Les sous-agents intégrés ne sont pas énumérés |1932| `agents` | `object[]` | Jetons attribués à chaque définition de sous-agent personnalisé, avec un identifiant source comme `projectSettings`, `userSettings`, ou `plugin`. Les sous-agents intégrés ne sont pas listés |
1879| `skills` | `object[]` | Jetons attribués à chaque compétence dans l'énumération des compétences, avec un identifiant de source et, pour les compétences de plugin, le nom du plugin dans `plugin_name`. Absent quand aucune compétence ne contribue de jetons |1933| `skills` | `object[]` | Jetons attribués à chaque compétence dans la liste des compétences, avec un identifiant source et, pour les compétences de plugin, le nom du plugin dans `plugin_name`. Absent quand aucune compétence ne contribue de jetons |
1880 1934
1881`over_limit.kind` enregistre comment Claude Code a résolu la fenêtre, pas si l'API accepte la prochaine demande :1935`over_limit.kind` enregistre comment Claude Code a résolu la fenêtre, pas si l'API accepte la prochaine requête :
1882 1936
1883* `hard_limit` : la fenêtre est ce que Claude Code croit être la limite propre du modèle, au-delà de laquelle l'API refuse les demandes1937* `hard_limit` : la fenêtre est ce que Claude Code croit être la limite propre du modèle, au-delà de laquelle l'API refuse les requêtes
1884* `compaction_window` : la fenêtre est une fenêtre de politique de compaction, qui peut ou non coïncider avec la limite du modèle1938* `compaction_window` : la fenêtre est une fenêtre de politique de compaction, qui peut ou non coïncider avec la limite du modèle
1885 1939
1886Claude Code évolue le type de manière additive, ajoutant de nouvelles données en tant que champs optionnels plutôt que de remodeler les existants. Lisez les champs que vous connaissez et ignorez ceux que vous ne reconnaissez pas.1940Claude Code évolue le type de manière additive, ajoutant de nouvelles données comme des champs optionnels plutôt que de remodeler les existants. Lisez les champs que vous connaissez et ignorez ceux que vous ne reconnaissez pas.
1887 1941
1888<h3 id="sdkcontextusagecategory">1942<h3 id="sdkcontextusagecategory">
1889 `SDKContextUsageCategory`1943 `SDKContextUsageCategory`
1899};1953};
1900```1954```
1901 1955
1902Le tableau énumère ce que Claude Code met dans chaque champ d'une ligne.1956Le tableau liste ce que Claude Code met dans chaque champ d'une ligne.
1903 1957
1904| Champ | Type | Description |1958| Champ | Type | Description |
1905| -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |1959| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
1906| `name` | `string` | Le nom d'affichage de la ligne tel que `/context` l'imprime, comme `Messages`. Classifiez les lignes par `kind`, pas par nom |1960| `name` | `string` | Le nom d'affichage de la ligne comme `/context` l'imprime, comme `Messages`. Classifiez les lignes par `kind`, pas par nom |
1907| `tokens` | `number` | Le nombre de jetons de la ligne. Les lignes peuvent porter zéro jeton |1961| `tokens` | `number` | Le nombre de jetons de la ligne. Les lignes peuvent porter zéro jeton |
1908| `kind` | `string` | Ce que la ligne représente : `used`, `free`, `buffer` ou `deferred` |1962| `kind` | `string` | Ce que la ligne représente : `used`, `free`, `buffer`, ou `deferred` |
1909 1963
1910Chaque valeur `kind` dit ce que les jetons de la ligne sont :1964Chaque valeur `kind` dit ce que les jetons de la ligne sont :
1911 1965
1912* `used` : contenu qui occupe la fenêtre de contexte1966* `used` : contenu qui occupe la fenêtre de contexte
1913* `free` : la fenêtre restante1967* `free` : la fenêtre restante
1914* `buffer` : la réserve de compaction1968* `buffer` : la réserve de compaction
1915* `deferred` : schémas d'outil que Claude Code tient hors de la fenêtre et exclut du calcul d'utilisation, énumérés pour la sensibilisation1969* `deferred` : schémas d'outil que Claude Code tient hors de la fenêtre et exclut du calcul d'utilisation, listés pour la sensibilisation
1916 1970
1917<h3 id="sdkmessageorigin">1971<h3 id="sdkmessageorigin">
1918 `SDKMessageOrigin`1972 `SDKMessageOrigin`
1919</h3>1973</h3>
1920 1974
1921Provenance d'un message de rôle utilisateur. Ceci apparaît comme `origin` sur [`SDKUserMessage`](#sdkusermessage) et est transmis au [`SDKResultMessage`](#sdkresultmessage) correspondant afin que vous puissiez dire ce qui a déclenché un tour donné.1975Provenance d'un message de rôle utilisateur. Ceci apparaît comme `origin` sur [`SDKUserMessage`](#sdkusermessage) et est transféré sur le [`SDKResultMessage`](#sdkresultmessage) correspondant pour que vous puissiez dire ce qui a déclenché un tour donné.
1922 1976
1923```typescript theme={null}1977```typescript theme={null}
1924type SDKMessageOrigin =1978type SDKMessageOrigin =
1937 | {1991 | {
1938 kind: "task-notification";1992 kind: "task-notification";
1939 subkind?: "scheduled-trigger" | "peer-send-message";1993 subkind?: "scheduled-trigger" | "peer-send-message";
1994 fireReason?: string;
1940 }1995 }
1941 | { kind: "coordinator" }1996 | { kind: "coordinator" }
1942 | { kind: "auto-continuation" }1997 | { kind: "auto-continuation" }
1944```1999```
1945 2000
1946| `kind` | Signification |2001| `kind` | Signification |
1947| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2002| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1948| `human` | Entrée directe de l'utilisateur final. Si votre application transmet ce que l'utilisateur a tapé en tant que message utilisateur, définissez son `origin` sur `{ kind: "human" }` explicitement : Claude Code traite un message utilisateur sans `origin` comme non attribué, et vérifie que les exigences d'une invite tapée par l'humain, comme le mot-clé de flux de travail [`ultracode`](/docs/fr/workflows#ask-for-a-workflow-in-your-prompt), ne l'acceptent pas. Avant v2.1.210, Claude Code traitait une `origin` absente sur un message utilisateur comme une entrée humaine. |2003| `human` | Entrée directe de l'utilisateur final. Si votre application transmet ce que l'utilisateur a tapé comme un message utilisateur, définissez son `origin` à `{ kind: "human" }` explicitement : Claude Code traite un message utilisateur sans `origin` comme non attribué, et vérifie que les vérifications qui nécessitent une invite tapée par l'humain, comme le [mot-clé de flux de travail `ultracode`](/docs/fr/workflows#ask-for-a-workflow-in-your-prompt), ne l'acceptent pas. Avant v2.1.210, Claude Code traitait un `origin` absent sur un message utilisateur comme une entrée humaine. |
1949| `channel` | Message arrivant sur un [canal](/docs/fr/channels). `server` est le nom du serveur MCP source. |2004| `channel` | Message arrivant sur un [canal](/docs/fr/channels). `server` est le nom du serveur MCP source. |
1950| `peer` | Message d'un autre agent : un [coéquipier](/docs/fr/agent-teams) en processus ou un [pair entre sessions](/docs/fr/cross-session-messaging), une autre de vos sessions Claude Code. Voir [Champs d'origine de pair](#peer-origin-fields) pour la sémantique par champ et le modèle de confiance. |2005| `peer` | Message d'un autre agent : un [coéquipier](/docs/fr/agent-teams) en processus ou un [pair entre sessions](/docs/fr/cross-session-messaging), une autre de vos sessions Claude Code. Voir [Champs d'origine pair](#peer-origin-fields) pour la sémantique par champ et le modèle de confiance. |
1951| `task-notification` | Tour synthétique injecté pour une livraison qui arrive sans une invite utilisateur fraîche, comme une tâche de fond terminée ; voir [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) pour ce bras. Le `subkind` optionnel marque ce qui a levé la notification. Voir [Sous-types de notification de tâche](#task-notification-subkinds). |2006| `task-notification` | Tour synthétique injecté pour une livraison qui arrive sans une invite utilisateur fraîche, comme une tâche de fond terminée ; voir [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) pour ce bras. Une invite que votre application [déclare comme une exécution planifiée](#declare-a-scheduled-run) porte ce type aussi. Le `subkind` optionnel marque ce qui a levé la notification. Voir [Sous-types de notification de tâche](#task-notification-subkinds). |
1952| `coordinator` | Message d'un coordinateur d'équipe dans une [équipe d'agents](/docs/fr/agent-teams). |2007| `coordinator` | Message d'un coordinateur d'équipe dans une [équipe d'agents](/docs/fr/agent-teams). |
1953| `auto-continuation` | Tour synthétique injecté quand la session continue sans nouvelle entrée utilisateur, comme un résultat de commande qui déclenche une invite de suivi. |2008| `auto-continuation` | Tour synthétique injecté quand la session continue sans entrée utilisateur fraîche, comme un résultat de commande qui déclenche une invite de suivi. |
1954| `unclassified` | Tour injecté dont l'origine n'a pas pu être déterminée. Nécessite Claude Code v2.1.223 ou ultérieur. Quand Claude Code reçoit un [`SDKUserMessage`](#sdkusermessage) avec `isSynthetic: true` et ne peut pas le classer comme un autre `kind`, il définit ce type à l'arrivée du message et encadre le tour au modèle comme une source non-utilisateur plutôt que de le traiter comme une entrée humaine. Votre application ne devrait pas définir cette valeur. |2009| `unclassified` | Tour injecté dont l'origine n'a pas pu être déterminée. Nécessite Claude Code v2.1.223 ou ultérieur. Quand Claude Code reçoit un [`SDKUserMessage`](#sdkusermessage) avec `isSynthetic: true` et ne peut pas le classer comme un autre `kind`, il définit ce type à l'arrivée du message et encadre le tour au modèle comme une source non-utilisateur plutôt que de le traiter comme une entrée humaine. Votre application ne devrait pas définir cette valeur. |
1955 2010
1956<h3 id="task-notification-subkinds">2011<h3 id="task-notification-subkinds">
1957 Sous-types de notification de tâche2012 Sous-types de notification de tâche
1958</h3>2013</h3>
1959 2014
1960Quand Claude Code livre une notification de tâche dans une session, il définit `subkind` sur l'`origin` de la notification uniquement si les serveurs Anthropic ont vérifié d'où cette notification provenait. `subkind` nécessite Claude Code v2.1.213 ou ultérieur, et il prend l'une de deux valeurs :2015Quand Claude Code livre une notification de tâche dans une session, il définit `subkind` sur le `origin` de la notification si les serveurs Anthropic ont vérifié d'où provenait cette notification. Il le définit aussi quand votre application [déclare le message comme une exécution planifiée](#declare-a-scheduled-run) elle-même, ce qui nécessite TypeScript Agent SDK v0.3.280 ou ultérieur. `subkind` nécessite Claude Code v2.1.213 ou ultérieur, et prend l'une de deux valeurs :
1961 2016
1962* `scheduled-trigger` : la notification est une invite stockée d'une [routine](/docs/fr/routines), livrée parce que l'un des déclencheurs de la routine s'est déclenché : son horaire, son [déclencheur API](/docs/fr/routines#add-an-api-trigger), son [déclencheur GitHub](/docs/fr/routines#add-a-github-trigger), ou **Exécuter maintenant**. Claude Code encadre ceux-ci au modèle comme la tâche assignée de la session, avec un avis différent de l'[avis que les autres notifications de tâche portent](#sdktasknotificationmessage).2017* `scheduled-trigger` : la notification est une invite stockée d'une [routine](/docs/fr/routines), livrée parce que l'un des déclencheurs de la routine s'est déclenché : son horaire, son [déclencheur API](/docs/fr/routines#add-an-api-trigger), son [déclencheur GitHub](/docs/fr/routines#add-a-github-trigger), ou **Exécuter maintenant**. Une invite que votre application [déclare comme une exécution planifiée](#declare-a-scheduled-run) porte cette valeur aussi. Claude Code encadre celles-ci au modèle comme la tâche assignée de la session, avec un avis différent de l'[avis que les autres notifications de tâche portent](#sdktasknotificationmessage).
1963*2018*
1964 2019
1965`peer-send-message` : la notification est un message qu'une autre de vos sessions a envoyé avec l'outil côté serveur `send_message` que les sessions [Claude Code sur le web](/docs/fr/claude-code-on-the-web) utilisent pour se envoyer des messages les unes aux autres, pas l'[outil `SendMessage` entre sessions](/docs/fr/cross-session-messaging), et les serveurs Anthropic ont vérifié que les deux sessions appartiennent au même groupe privé de sessions. Nécessite Claude Code v2.1.224 ou ultérieur. Une livraison `send_message` que les serveurs n'ont pas vérifiée de cette façon n'obtient pas de subkind.2020`peer-send-message` : la notification est un message qu'une autre de vos sessions a envoyé avec l'outil côté serveur `send_message` que les [sessions cloud](/docs/fr/claude-code-on-the-web) utilisent pour se messagerie mutuellement, pas l'[outil `SendMessage` entre sessions](/docs/fr/cross-session-messaging), et les serveurs Anthropic ont vérifié que les deux sessions appartiennent au même groupe privé de sessions. Nécessite Claude Code v2.1.224 ou ultérieur. Une livraison `send_message` que les serveurs n'ont pas vérifiée de cette façon n'obtient pas de subkind.
1966 2021
1967Chaque autre notification de tâche n'a pas de `subkind`. Cela inclut les [tâches programmées](/docs/fr/scheduled-tasks) qui se déclenchent sur votre propre machine, l'[activité PR](/docs/fr/claude-code-on-the-web#how-claude-responds-to-pr-activity) livrée dans une session, et les événements de fond comme une tâche terminée. Les messages de l'[outil `SendMessage` entre sessions](/docs/fr/cross-session-messaging) ne sont pas du tout des notifications de tâche : qu'ils proviennent d'une session sur la même machine ou via les serveurs Anthropic d'une autre machine, Claude Code leur donne `kind: "peer"` et les [champs d'origine de pair](#peer-origin-fields).2022Chaque autre notification de tâche n'a pas de `subkind`. Cela inclut l'[activité PR](/docs/fr/claude-code-on-the-web#how-claude-responds-to-pr-activity) livrée dans une session et les événements de fond comme une tâche terminée. Les messages de l'[outil `SendMessage` entre sessions](/docs/fr/cross-session-messaging) ne sont pas du tout des notifications de tâche : qu'ils proviennent d'une session sur la même machine ou via les serveurs Anthropic d'une autre machine, Claude Code leur donne `kind: "peer"` et les [champs d'origine pair](#peer-origin-fields).
2023
2024`fireReason` dit pourquoi une notification `scheduled-trigger` s'est déclenchée, comme un jeton minuscule court comme `scheduled`, `manual`, `retry`, `catch_up`, ou `api`. Les serveurs Anthropic le définissent sur les livraisons d'une [routine](/docs/fr/routines), et votre application le définit quand elle déclare une exécution planifiée. Il est absent quand aucun des deux n'en a envoyé un. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur.
2025
2026<h4 id="declare-a-scheduled-run">
2027 Déclarer une exécution planifiée
2028</h4>
2029
2030Si votre application exécute des invites selon son propre horaire, déclarez chaque exécution pour que Claude Code encadre le tour au modèle comme une tâche planifiée plutôt que comme une entrée en direct de l'utilisateur. Démarrez la session avec `CLAUDE_CODE_HOST_SCHEDULED_RUN` défini à `1` dans [`env`](#options), puis envoyez le [`SDKUserMessage`](#sdkusermessage) de l'exécution avec `origin: { kind: "task-notification", subkind: "scheduled-trigger", fireReason: "scheduled" }` et sans `isSynthetic`. Claude Code ignore la déclaration dans un processus démarré sans cette variable. Il l'ignore aussi dans un processus dont l'environnement porte [`CLAUDECODE`](/docs/fr/env-vars) ou `CLAUDE_CODE_CHILD_SESSION`. Claude Code conserve `fireReason` uniquement quand la valeur est 1 à 32 lettres minuscules ou traits de soulignement. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur.
1968 2031
1969<h3 id="peer-origin-fields">2032<h3 id="peer-origin-fields">
1970 Champs d'origine de pair2033 Champs d'origine pair
1971</h3>2034</h3>
1972 2035
1973Une origine `peer` identifie quel agent a envoyé le message : un [coéquipier](/docs/fr/agent-teams) en processus envoyant à `main` avec `SendMessage`, ou un [pair entre sessions](/docs/fr/cross-session-messaging), une autre de vos sessions Claude Code. Les pairs entre sessions nécessitent Claude Code v2.1.224 ou ultérieur sur macOS et Linux ; voir [disponibilité de la messagerie entre sessions](/docs/fr/cross-session-messaging#availability) pour l'exigence Windows native. Un pair entre sessions peut s'exécuter sur la même machine, ou sur [une autre de vos machines](/docs/fr/cross-session-messaging#message-sessions-on-other-machines) ou [Claude Code sur le web](/docs/fr/claude-code-on-the-web) quand son message arrive via Remote Control. Les deux types d'expéditeur remplissent les champs différemment :2036Une origine `peer` identifie quel agent a envoyé le message : un [coéquipier](/docs/fr/agent-teams) en processus envoyant à `main` avec `SendMessage`, ou un [pair entre sessions](/docs/fr/cross-session-messaging), une autre de vos sessions Claude Code. Les pairs entre sessions nécessitent Claude Code v2.1.224 ou ultérieur sur macOS et Linux ; voir [disponibilité de la messagerie entre sessions](/docs/fr/cross-session-messaging#availability) pour l'exigence Windows native. Un pair entre sessions peut s'exécuter sur la même machine, ou sur [une autre de vos machines](/docs/fr/cross-session-messaging#message-sessions-on-other-machines) ou [dans le cloud](/docs/fr/claude-code-on-the-web) quand son message arrive via Remote Control. Les deux types d'expéditeur remplissent les champs différemment :
1974 2037
1975* `from` : le nom du coéquipier, ou l'adresse de l'expéditeur pour un pair entre sessions. Pour un [message entre machines unidirectionnel](/docs/fr/cross-session-messaging#message-sessions-on-other-machines), l'expéditeur n'a pas d'adresse de réponse et `from` est `"unknown"`. La valeur est créée par l'expéditeur ; `verifiedPeerPid` est l'identité vérifiée.2038* `from` : le nom du coéquipier, ou l'adresse de l'expéditeur pour un pair entre sessions. Pour un [message entre machines unidirectionnel](/docs/fr/cross-session-messaging#message-sessions-on-other-machines), l'expéditeur n'a pas d'adresse de réponse et `from` est `"unknown"`. La valeur est créée par l'expéditeur ; `verifiedPeerPid` est l'identité vérifiée.
1976*2039*
1977 2040
1978`fromMode` : la classe de permissions de la session d'envoi, `bypass` ou `prompting`, déclarée par un hôte qui relaie un message de pair entre vos sessions, comme l'[application de bureau](/docs/fr/desktop#work-across-sessions). Claude Code la lit dans la session de réception quand il applique les [contrôles entrants](/docs/fr/cross-session-messaging#control-inbound-messages). Nécessite Agent SDK v0.3.234 ou ultérieur.2041`fromMode` : la classe de permissions de la session d'envoi, `bypass` ou `prompting`, déclarée par un hôte qui relaie un message pair entre vos sessions, comme l'[application de bureau](/docs/fr/desktop#work-across-sessions). Claude Code la lit dans la session de réception quand il applique les [contrôles entrants](/docs/fr/cross-session-messaging#control-inbound-messages). Nécessite Agent SDK v0.3.234 ou ultérieur.
1979 2042
1980* `senderTaskId` : l'ID de tâche du coéquipier. Absent pour un pair entre sessions.2043* `senderTaskId` : l'ID de tâche du coéquipier. Absent pour un pair entre sessions.
1981*2044*
1982 2045
1983`name` : le nom d'affichage de l'expéditeur, normalisé par Claude Code : il supprime les points de code de contrôle, de format, de substitut Unicode, et de séparateur de ligne ou de paragraphe, puis tronque le résultat et le limite à 64 points de code avec des points de suspension. Nécessite Claude Code v2.1.205 ou ultérieur.2046`name` : le nom d'affichage de l'expéditeur, normalisé par Claude Code : il supprime les points de code de contrôle, format, substitut et séparateur de ligne ou paragraphe Unicode, puis coupe le résultat et le limite à 64 points de code avec une ellipse. Nécessite Claude Code v2.1.205 ou ultérieur.
1984 2047
1985*2048*
1986 2049
1987`body` : le corps du message décodé avec l'enveloppe de pair supprimée, octet-exact avec ce que le modèle voit. Toujours présent pour un message de coéquipier ; pour un pair entre sessions, présent uniquement quand le tour est exactement une enveloppe de pair formée par Claude Code. Rendez `name` et `body` au lieu de réanalyser le texte du message. Nécessite Claude Code v2.1.205 ou ultérieur.2050`body` : le corps du message décodé avec l'enveloppe pair supprimée, octet-exact avec ce que le modèle voit. Toujours présent pour un message de coéquipier ; pour un pair entre sessions, présent uniquement quand le tour est exactement une enveloppe pair formée par Claude Code. Rendez `name` et `body` au lieu de réanalyser le texte du message. Nécessite Claude Code v2.1.205 ou ultérieur.
1988 2051
1989*2052*
1990 2053
1991`fromSession` : l'ID de session de l'expéditeur ouvert par l'hôte, défini par l'hôte de l'expéditeur afin que votre interface utilisateur puisse créer un lien vers la session d'envoi. Comme `from`, il est affirmé par l'expéditeur : utilisez-le uniquement comme cible de navigation, et ne le traitez pas comme une preuve de l'identité de l'expéditeur. Nécessite Claude Code v2.1.216 ou ultérieur.2054`fromSession` : l'ID de session ouvrable par l'hôte de l'expéditeur, défini par l'hôte de l'expéditeur pour que votre interface utilisateur puisse se lier à la session d'envoi. Comme `from`, il est affirmé par l'expéditeur : utilisez-le uniquement comme cible de navigation, et ne le traitez pas comme une preuve de l'identité de l'expéditeur. Nécessite Claude Code v2.1.216 ou ultérieur.
1992 2055
1993*2056*
1994 2057
1995`verifiedPeerPid` : l'ID de processus du processus qui s'est connecté à la prise de messagerie entre sessions de cette session, vérifié par le noyau et lu de la connexion elle-même, jamais de la charge utile. Utilisez-le, pas `from`, pour identifier l'expéditeur : `from` peut être forgé par n'importe quel processus du même utilisateur. Le champ est absent quand Claude Code ne peut pas le vérifier, comme sur Windows ou l'entrée non-socket, donc une valeur absente signifie que l'expéditeur n'est pas vérifié. Pour le trafic relayé, il identifie le relais plutôt que l'auteur du message, et les ID de processus sont recyclables, donc traitez-le comme une provenance plutôt qu'un jeton d'authentification. Nécessite Claude Code v2.1.216 ou ultérieur.2058`verifiedPeerPid` : l'ID de processus du processus qui s'est connecté à la prise de messagerie entre sessions de cette session, vérifié par le noyau et lu de la connexion elle-même, jamais de la charge utile. Utilisez-le, pas `from`, pour identifier l'expéditeur : `from` est forgeable par n'importe quel processus du même utilisateur. Le champ est absent quand Claude Code ne peut pas le vérifier, comme sur Windows ou l'entrée non-socket, donc une valeur absente signifie que l'expéditeur n'est pas vérifié. Pour le trafic relayé, il identifie le relais plutôt que l'auteur du message, et les ID de processus sont recyclables, donc traitez-le comme la provenance plutôt que comme un jeton d'authentification. Nécessite Claude Code v2.1.216 ou ultérieur.
1996 2059
1997<h2 id="hook-types">2060<h2 id="hook-types">
1998 Types de hook2061 Types de hook
2858 | ReadMcpResourceInput2921 | ReadMcpResourceInput
2859 | RefreshMcpToolsInput2922 | RefreshMcpToolsInput
2860 | RemoteTriggerInput2923 | RemoteTriggerInput
2861 | REPLInput
2862 | ReportFindingsInput2924 | ReportFindingsInput
2863 | ScheduleWakeupInput2925 | ScheduleWakeupInput
2864 | ShowOnboardingRolePickerInput2926 | ShowOnboardingRolePickerInput
2865 | TaskCreateInput2927 | TaskCreateInput
2866 | TaskGetInput2928 | TaskGetInput
2867 | TaskListInput2929 | TaskListInput
2868 | TaskOutputInput
2869 | TaskStopInput2930 | TaskStopInput
2870 | TaskUpdateInput2931 | TaskUpdateInput
2871 | TodoWriteInput2932 | TodoWriteInput
2960 3021
2961Exécute une source de fond et livre chaque événement à Claude pour qu'il puisse réagir sans interrogation : `command` exécute un script et émet un événement par ligne stdout, et `ws` ouvre une WebSocket et émet un événement par trame texte. Fournissez exactement l'un de `command` ou `ws`. La source `ws` nécessite Claude Code v2.1.195 ou version ultérieure.3022Exécute une source de fond et livre chaque événement à Claude pour qu'il puisse réagir sans interrogation : `command` exécute un script et émet un événement par ligne stdout, et `ws` ouvre une WebSocket et émet un événement par trame texte. Fournissez exactement l'un de `command` ou `ws`. La source `ws` nécessite Claude Code v2.1.195 ou version ultérieure.
2962 3023
2963`timeout_ms` est la date limite de la montre en millisecondes. Elle est par défaut 300000, et la date limite effective est au maximum 1800000, soit 30 minutes. À la date limite, la montre se termine et Claude reçoit un avis pour qu'il puisse démarrer une nouvelle montre s'il en a toujours besoin.3024`timeout_ms` est la date limite de la montre en millisecondes. Elle est par défaut 300000 et accepte les valeurs jusqu'à 3600000. La date limite effective est au maximum 1800000, soit 30 minutes, donc une valeur acceptée plus grande est raccourcie à cela. À la date limite, la montre se termine et Claude reçoit un avis pour qu'il puisse démarrer une nouvelle montre s'il en a toujours besoin.
2964 3025
2965Le type exporté marque `timeout_ms` comme requis car le schéma remplit la valeur par défaut ; un appel qui l'omet valide.3026Le type exporté marque `timeout_ms` comme requis car le schéma remplit la valeur par défaut ; un appel qui l'omet valide.
2966 3027
2970 TaskOutput3031 TaskOutput
2971</h3>3032</h3>
2972 3033
2973**Nom de l'outil :** `TaskOutput`3034Supprimé dans Claude Code v2.1.277, ainsi que son type `TaskOutputInput`. Récupérait précédemment la sortie d'une tâche de fond en cours d'exécution ou terminée ; Claude lit le fichier de sortie d'une tâche de fond avec `Read` à la place.
2974 3035
2975<Note>`TaskOutput` est déprécié ; préférez `Read` sur le chemin du fichier de sortie de la tâche. Les schémas ci-dessous restent valides pour les hooks et les gestionnaires de permission qui rencontrent l'outil.</Note>3036Une entrée `disallowedTools` ou une règle de refus qui nomme toujours `TaskOutput` est ignorée sans avertissement.
2976
2977```typescript theme={null}
2978type TaskOutputInput = {
2979 task_id: string;
2980 block: boolean;
2981 timeout: number;
2982};
2983```
2984
2985Récupère la sortie d'une tâche de fond en cours d'exécution ou terminée.
2986 3037
2987<h3 id="edit">3038<h3 id="edit">
2988 Edit3039 Edit
3477 REPL3528 REPL
3478</h3>3529</h3>
3479 3530
3480**Nom de l'outil :** `REPL`3531Supprimé dans v2.1.275. Jusqu'à v2.1.274, un outil `REPL` expérimental pouvait être activé avec `CLAUDE_CODE_REPL=1` dans l'option [`env`](#options).
3481
3482```typescript theme={null}
3483type REPLInput = {
3484 code: string;
3485 description?: string;
3486 timeout?: number;
3487};
3488```
3489
3490Exécute le code JavaScript dans un REPL persistant. L'état persiste entre les appels et l'await au niveau supérieur est supporté. `timeout` est en millisecondes, avec une valeur par défaut de 30000 et un maximum de 600000.
3491
3492Les types sont exportés, mais l'outil est désactivé dans les sessions SDK sauf si vous définissez `CLAUDE_CODE_REPL=1` dans l'option [`env`](#options). Il nécessite également l'exécutable `claude` basé sur Bun que le programme d'installation natif fournit.
3493 3532
3494<h3 id="reportfindings">3533<h3 id="reportfindings">
3495 ReportFindings3534 ReportFindings
3535 action?: "publish" | "list";3574 action?: "publish" | "list";
3536 file_path?: string;3575 file_path?: string;
3537 favicon?: string;3576 favicon?: string;
3577 icon?: string;
3538 limit?: number;3578 limit?: number;
3539 scope?: "mine" | "shared" | "all";3579 scope?: "mine" | "shared" | "all";
3540 title?: string;3580 title?: string;
3547};3587};
3548```3588```
3549 3589
3550Publie un fichier `.html` ou `.md` local en tant que page d'artefact hébergée, ou répertorie les artefacts publiés de l'utilisateur. Omettez `action` ou passez `"publish"` pour publier `file_path`, qui est requis pour l'action de publication ainsi que `favicon`, un ou deux emoji qui marquent l'artefact dans la galerie de l'utilisateur. `title` nomme la page publiée dans l'onglet du navigateur et la galerie lorsque le fichier HTML n'a pas de balise `<title>`. `url` cible un artefact existant à mettre à jour sur place au lieu de créer un nouveau.3590Publie un fichier `.html` ou `.md` local en tant que page d'artefact hébergée, ou répertorie les artefacts publiés de l'utilisateur. Omettez `action` ou passez `"publish"` pour publier `file_path`, qui est requis pour l'action de publication. Chaque champ ci-dessous s'applique à une publication :
3591
3592* `icon` : un mot générique court pour l'icône de l'onglet du navigateur de l'artefact, tel que `chart` ou `map`. Claude l'inclut à la première publication et l'omet à une mise à jour, ce qui conserve l'icône stockée de l'artefact.
3593* `favicon` : déprécié, et Claude l'omet.
3594* `title` : nomme la page publiée dans l'onglet du navigateur et la galerie lorsque le fichier HTML n'a pas de balise `<title>`.
3595* `url` : cible un artefact existant à mettre à jour sur place au lieu de créer un nouveau.
3551 3596
3552`force` est un dernier recours qui écrase une version plus récente qu'une autre session a publiée. En cas de conflit, la publication échouée retourne le contenu plus récent ; Claude fusionne ses modifications sur ce contenu, ou relit l'artefact, et publie à nouveau. Passez `force` uniquement lorsque l'utilisateur demande explicitement de rejeter cette version.3597`force` est un dernier recours qui écrase une version plus récente qu'une autre session a publiée. En cas de conflit, la publication échouée retourne le contenu plus récent ; Claude fusionne ses modifications sur ce contenu, ou relit l'artefact, et publie à nouveau. Passez `force` uniquement lorsque l'utilisateur demande explicitement de rejeter cette version.
3553 3598
3684 | ReadMcpResourceOutput3729 | ReadMcpResourceOutput
3685 | RefreshMcpToolsOutput3730 | RefreshMcpToolsOutput
3686 | RemoteTriggerOutput3731 | RemoteTriggerOutput
3687 | REPLOutput
3688 | ReportFindingsOutput3732 | ReportFindingsOutput
3689 | ScheduleWakeupOutput3733 | ScheduleWakeupOutput
3690 | ShowOnboardingRolePickerOutput3734 | ShowOnboardingRolePickerOutput
4534 4578
4535Retourne les détails de livraison, y compris si une notification push ou locale a été envoyée et pourquoi la livraison a été ignorée.4579Retourne les détails de livraison, y compris si une notification push ou locale a été envoyée et pourquoi la livraison a été ignorée.
4536 4580
4537<h3 id="repl-2">
4538 REPL
4539</h3>
4540
4541**Nom de l'outil :** `REPL`
4542
4543```typescript theme={null}
4544type REPLOutput = {
4545 code: string;
4546 result: {
4547 [k: string]: unknown;
4548 };
4549 stdout: string;
4550 stderr: string;
4551 error?: string;
4552 registeredTools?: string[];
4553 images?: {
4554 base64: string;
4555 mediaType: string;
4556 }[];
4557 documents?: {
4558 base64: string;
4559 }[];
4560};
4561```
4562
4563Retourne le résultat de l'exécution, la sortie de la console capturée, et toutes les images ou documents surfacés par les appels `Read` internes.
4564
4565<h3 id="reportfindings-2">4581<h3 id="reportfindings-2">
4566 ReportFindings4582 ReportFindings
4567</h3>4583</h3>
4848 `ApiKeySource`4864 `ApiKeySource`
4849</h3>4865</h3>
4850 4866
4851D'où provient la clé API pour les demandes de la session, rapportée comme `apiKeySource` sur le message d'initialisation [`SDKSystemMessage`](#sdksystemmessage).4867D'où provient la clé API pour les requêtes de la session, signalée comme `apiKeySource` sur le message d'initialisation [`SDKSystemMessage`](#sdksystemmessage).
4852 4868
4853```typescript theme={null}4869```typescript theme={null}
4854type ApiKeySource =4870type ApiKeySource =
4863 | "oauth";4879 | "oauth";
4864```4880```
4865 4881
4866Claude Code rapporte l'une de quatre valeurs :4882Claude Code signale l'une de quatre valeurs :
4867 4883
4868| Valeur | Clé en utilisation |4884| Valeur | Clé en utilisation |
4869| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |4885| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
4870| `ANTHROPIC_API_KEY` | La clé dans la variable d'environnement `ANTHROPIC_API_KEY` |4886| `ANTHROPIC_API_KEY` | La clé dans la variable d'environnement `ANTHROPIC_API_KEY` |
4871| `apiKeyHelper` | La clé retournée par votre commande [`apiKeyHelper`](/docs/fr/settings-reference#apikeyhelper) |4887| `apiKeyHelper` | La clé renvoyée par votre commande [`apiKeyHelper`](/docs/fr/settings-reference#apikeyhelper) |
4872| `/login managed key` | La clé que Claude Code a stockée quand vous vous êtes connecté avec un [compte Claude Console](/docs/fr/authentication#claude-console-authentication) |4888| `/login managed key` | La clé que Claude Code a stockée lorsque vous vous êtes connecté avec un [compte Claude Console](/docs/fr/authentication#claude-console-authentication) |
4873| `none` | Aucune clé API. La session s'authentifie d'une autre manière, comme une connexion claude.ai, un jeton porteur ou un fournisseur cloud |4889| `none` | Aucune clé API. La session s'authentifie d'une autre manière, par exemple une connexion claude.ai, un jeton porteur ou un fournisseur cloud |
4874 4890
4875Agent SDK v0.3.234 et versions ultérieures listent ces quatre valeurs dans le type. Le type conserve également `user`, `project`, `org`, `temporary` et `oauth` pour que le code plus ancien se compile toujours, et Claude Code ne les rapporte pas.4891Agent SDK v0.3.234 et versions ultérieures listent ces quatre valeurs dans le type. Le type conserve également `user`, `project`, `org`, `temporary` et `oauth` afin que le code plus ancien soit toujours compilé, et Claude Code ne les signale pas.
4876 4892
4877<h3 id="sdkbeta">4893<h3 id="sdkbeta">
4878 `SdkBeta`4894 `SdkBeta`
4879</h3>4895</h3>
4880 4896
4881Fonctionnalités bêta disponibles qui peuvent être activées via l'option `betas`. Voir [En-têtes bêta](https://platform.claude.com/docs/en/api/beta-headers) pour plus d'informations.4897Les fonctionnalités bêta disponibles qui peuvent être activées via l'option `betas`. Consultez [En-têtes bêta](https://platform.claude.com/docs/en/api/beta-headers) pour plus d'informations.
4882 4898
4883```typescript theme={null}4899```typescript theme={null}
4884type SdkBeta = "context-1m-2025-08-07";4900type SdkBeta = "context-1m-2025-08-07";
4885```4901```
4886 4902
4887<Warning>4903<Warning>
4888 La bêta `context-1m-2025-08-07` est retirée à partir du 30 avril 2026. Passer cette valeur avec Claude Sonnet 4.5 ou Sonnet 4 n'a aucun effet, et les demandes qui dépassent la fenêtre de contexte standard de 200 k tokens retournent une erreur. Pour utiliser une fenêtre de contexte de 1 M tokens, migrez vers [Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7 ou Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview), qui incluent 1 M de contexte à prix standard sans en-tête bêta requis.4904 La bêta `context-1m-2025-08-07` est retirée à partir du 30 avril 2026. Passer cette valeur avec Claude Sonnet 4.5 ou Sonnet 4 n'a aucun effet, et les requêtes qui dépassent la fenêtre de contexte standard de 200 k jetons renvoient une erreur. Pour utiliser une fenêtre de contexte de 1 M de jetons, migrez vers [Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7 ou Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview), qui incluent 1 M de contexte au prix standard sans en-tête bêta requis.
4889</Warning>4905</Warning>
4890 4906
4891<h3 id="slashcommand">4907<h3 id="slashcommand">
4900 description: string;4916 description: string;
4901 argumentHint: string;4917 argumentHint: string;
4902 aliases?: string[];4918 aliases?: string[];
4919 builtin?: boolean;
4903};4920};
4904```4921```
4905 4922
4923`builtin` est `true` sur une ligne lorsque la commande est celle de Claude Code et que taper `/name` l'exécute. Elle est absente pour une commande définie par un utilisateur, un projet, un plugin ou un serveur MCP, et pour une commande groupée que l'un de ceux-ci [remplace par nom](/docs/fr/skills#resolve-skills-that-share-a-name). Nécessite Agent SDK v0.3.277 ou version ultérieure.
4924
4906<h3 id="modelinfo">4925<h3 id="modelinfo">
4907 `ModelInfo`4926 `ModelInfo`
4908</h3>4927</h3>
4924```4943```
4925 4944
4926| Champ | Type | Description |4945| Champ | Type | Description |
4927| :------------------------- | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |4946| :------------------------- | :----------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
4928| `value` | `string` | Identifiant de modèle à passer dans les appels API |4947| `value` | `string` | Identifiant du modèle à passer dans les appels API |
4929| `resolvedModel` | `string \| undefined` | ID de modèle canonique sur le fil que la `value` de cette entrée résout. Une entrée d'alias telle que `sonnet` résout à un ID de modèle explicite tel que `claude-sonnet-5`, de sorte qu'un hôte peut faire correspondre un ID de modèle explicite stocké à l'entrée d'alias qui le couvre. Nécessite Claude Code v2.1.197 ou ultérieur. |4948| `resolvedModel` | `string \| undefined` | ID du modèle canonique sur le fil auquel la `value` de cette entrée se résout. Une entrée d'alias telle que `sonnet` se résout en un ID de modèle explicite tel que `claude-sonnet-5`, afin qu'un hôte puisse faire correspondre un ID de modèle explicite stocké à l'entrée d'alias qui le couvre. Nécessite Claude Code v2.1.197 ou version ultérieure. |
4930| `displayName` | `string` | Nom d'affichage lisible par l'homme |4949| `displayName` | `string` | Nom d'affichage lisible par l'homme |
4931| `description` | `string` | Description des capacités du modèle |4950| `description` | `string` | Description des capacités du modèle |
4932| `supportsEffort` | `boolean \| undefined` | Si ce modèle supporte les niveaux d'effort |4951| `supportsEffort` | `boolean \| undefined` | Si ce modèle supporte les niveaux d'effort |
4950```4969```
4951 4970
4952| Champ | Type | Description |4971| Champ | Type | Description |
4953| :------------ | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |4972| :------------ | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
4954| `name` | `string` | Identifiant de type d'agent (par exemple, `"Explore"`, `"general-purpose"`) |4973| `name` | `string` | Identifiant du type d'agent (par exemple, `"Explore"`, `"general-purpose"`) |
4955| `description` | `string` | Description de quand utiliser cet agent |4974| `description` | `string` | Description de quand utiliser cet agent |
4956| `model` | `string \| undefined` | Modèle que cet agent utilise : un alias ou ID de modèle, ou `'inherit'` pour le modèle du parent. Quand c'est `undefined`, Claude Code choisit le modèle dans l'[ordre des modèles de sous-agent](/docs/fr/sub-agents#choose-a-model) |4975| `model` | `string \| undefined` | Modèle que cet agent utilise : un alias ou un ID de modèle, ou `'inherit'` pour le modèle du parent. Lorsqu'il est `undefined`, Claude Code choisit le modèle dans l'[ordre des modèles de sous-agent](/docs/fr/sub-agents#choose-a-model) |
4957 4976
4958<h3 id="mcpserverprovenance">4977<h3 id="mcpserverprovenance">
4959 `McpServerProvenance`4978 `McpServerProvenance`
4960</h3>4979</h3>
4961 4980
4962Le serveur MCP qui sert un outil `mcp__*`, et d'où provient la définition de ce serveur. Les entrées du hook [`PreToolUse`](#pretoolusehookinput), `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` et `PermissionDenied` le portent comme `mcp_server`, et les options [`CanUseTool`](#canusetool) le portent comme `mcpServer`. Les deux l'omettent pour les outils qui ne proviennent pas d'un serveur MCP.4981Le serveur MCP qui sert un outil `mcp__*`, et d'où provient la définition de ce serveur. Les entrées de hook [`PreToolUse`](#pretoolusehookinput), `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` et `PermissionDenied` le portent comme `mcp_server`, et les options [`CanUseTool`](#canusetool) le portent comme `mcpServer`. Les deux l'omettent pour les outils qui ne proviennent pas d'un serveur MCP.
4963 4982
4964```typescript theme={null}4983```typescript theme={null}
4965type McpServerProvenance = {4984type McpServerProvenance = {
4969```4988```
4970 4989
4971| Champ | Type | Description |4990| Champ | Type | Description |
4972| :------- | :------- | :---------------------------------------------------------------------------------------------------------------------- |4991| :------- | :------- | :--------------------------------------------------------------------------------------------------------------------- |
4973| `name` | `string` | Le nom sous lequel le serveur est enregistré, la même valeur que [`mcpServerStatus()`](#query-object) rapporte pour lui |4992| `name` | `string` | Le nom sous lequel le serveur est enregistré, la même valeur que [`mcpServerStatus()`](#query-object) signale pour lui |
4974| `source` | `string` | D'où provient la définition du serveur : `sdk`, `plugin` ou une portée de configuration |4993| `source` | `string` | D'où provient la définition du serveur : `sdk`, `plugin` ou une portée de configuration |
4975 4994
4976`source` prend l'une des valeurs suivantes. L'ensemble est ouvert, donc traitez une valeur que vous ne reconnaissez pas comme une source configurée, jamais comme `sdk` :4995`source` prend l'une des valeurs suivantes. L'ensemble est ouvert, donc traitez une valeur que vous ne reconnaissez pas comme une source configurée, jamais comme `sdk` :
4977 4996
4978* **`sdk`** : un serveur en processus que votre application a enregistré. Seule l'application hôte du SDK peut en enregistrer un, donc un serveur configuré ne rapporte jamais `sdk`, quel que soit son nom.4997* **`sdk`** : un serveur en processus que votre application a enregistré. Seule l'application hôte du SDK peut en enregistrer un, donc un serveur configuré ne signale jamais `sdk`, quel que soit son nom.
4979* **`plugin`** : un serveur qu'un [plugin](/docs/fr/agent-sdk/plugins) fournit. Son `name` est la forme `plugin:<plugin-name>:<server-name>` délimitée décrite sous [serveurs MCP fournis par plugin](/docs/fr/mcp#plugin-provided-mcp-servers).4998* **`plugin`** : un serveur qu'un [plugin](/docs/fr/agent-sdk/plugins) fournit. Son `name` est la forme `plugin:<plugin-name>:<server-name>` délimitée décrite sous [serveurs MCP fournis par plugin](/docs/fr/mcp#plugin-provided-mcp-servers).
4980* **Une portée de configuration** : `user`, `project`, `local`, `dynamic`, `managed`, `enterprise`, `claudeai` ou `agent`. Un serveur `.mcp.json` rapporte `project`, et [les portées d'installation MCP](/docs/fr/mcp#mcp-installation-scopes) définissent `local`, `project` et `user`. Les serveurs que votre application transmet dans l'option [`mcpServers`](#options), autres que les serveurs SDK en processus, rapportent `dynamic`.4999* **Une portée de configuration** : `user`, `project`, `local`, `dynamic`, `managed`, `enterprise`, `claudeai` ou `agent`. Un serveur `.mcp.json` signale `project`, et [les portées d'installation MCP](/docs/fr/mcp#mcp-installation-scopes) définissent `local`, `project` et `user`. Les serveurs que votre application transmet dans l'option [`mcpServers`](#options), autres que les serveurs SDK en processus, signalent `dynamic`.
4981 5000
4982Basez les décisions de confiance sur `source`, pas sur `name` ou le préfixe du nom d'outil `mcp__<server>__`. Pour toute source autre que `sdk`, `name` est du texte non fiable : échappez-le avant l'affichage.5001Basez les décisions de confiance sur `source`, pas sur `name` ou le préfixe du nom d'outil `mcp__<server>__`. Pour toute source autre que `sdk`, `name` est du texte non fiable : échappez-le avant l'affichage.
4983 5002
4984`McpServerProvenance` et les champs qui le portent nécessitent Agent SDK v0.3.274 ou ultérieur.5003`McpServerProvenance` et les champs qui le portent nécessitent Agent SDK v0.3.274 ou version ultérieure.
4985 5004
4986<h3 id="mcpserverstatus">5005<h3 id="mcpserverstatus">
4987 `McpServerStatus`5006 `McpServerStatus`
4988</h3>5007</h3>
4989 5008
4990Statut d'un serveur MCP connecté.5009État d'un serveur MCP connecté.
4991 5010
4992```typescript theme={null}5011```typescript theme={null}
4993type McpServerStatus = {5012type McpServerStatus = {
5009 destructive?: boolean;5028 destructive?: boolean;
5010 openWorld?: boolean;5029 openWorld?: boolean;
5011 };5030 };
5031 _meta?: Record<string, unknown>;
5012 }[];5032 }[];
5013};5033};
5014```5034```
5015 5035
5016`source` indique d'où provient la définition du serveur, avec les mêmes valeurs et règle de confiance que le `source` de [`McpServerProvenance`](#mcpserverprovenance). Le champ nécessite Agent SDK v0.3.274 ou ultérieur et est absent sur les versions antérieures.5036`source` indique d'où provient la définition du serveur, avec les mêmes valeurs et règle de confiance que le `source` de [`McpServerProvenance`](#mcpserverprovenance). Le champ nécessite Agent SDK v0.3.274 ou version ultérieure et est absent sur les versions antérieures.
5037
5038`_meta` sur une entrée `tools` porte les membres MCP Apps de `_meta` de cet outil, afin que votre application puisse trouver la ressource `ui://` à rendre avec [`readMcpResource()`](#query-object). Claude Code transmet l'objet `ui` et la chaîne `ui/resourceUri` plate dépréciée, et retient toute autre clé. À l'intérieur de `ui`, `resourceUri` est une chaîne `ui://` et `visibility` un tableau de `"model"` et `"app"` lorsque le serveur les définit, et tout autre membre passe inchangé. Claude Code supprime l'une ou l'autre clé lorsque la valeur est malformée, et omet `_meta` d'un outil qui ne déclare ni l'une ni l'autre. Le champ est présent uniquement lorsque les [`capabilities`](#sdksystemmessage) du message d'initialisation incluent `mcp_tool_ui_meta_v1`, et nécessite TypeScript Agent SDK v0.3.280 ou version ultérieure.
5017 5039
5018<h3 id="mcpserverstatusconfig">5040<h3 id="mcpserverstatusconfig">
5019 `McpServerStatusConfig`5041 `McpServerStatusConfig`
5020</h3>5042</h3>
5021 5043
5022La configuration d'un serveur MCP telle que rapportée par `mcpServerStatus()`. C'est l'union de tous les types de transport de serveur MCP.5044La configuration d'un serveur MCP telle que signalée par `mcpServerStatus()`. C'est l'union de tous les types de transport de serveur MCP.
5023 5045
5024```typescript theme={null}5046```typescript theme={null}
5025type McpServerStatusConfig =5047type McpServerStatusConfig =
5030 | McpClaudeAIProxyServerConfig;5052 | McpClaudeAIProxyServerConfig;
5031```5053```
5032 5054
5033Voir [`McpServerConfig`](#mcpserverconfig) pour les détails sur chaque type de transport.5055Consultez [`McpServerConfig`](#mcpserverconfig) pour les détails sur chaque type de transport.
5034 5056
5035<h3 id="accountinfo">5057<h3 id="accountinfo">
5036 `AccountInfo`5058 `AccountInfo`
5052 `ModelUsage`5074 `ModelUsage`
5053</h3>5075</h3>
5054 5076
5055Statistiques d'utilisation par modèle retournées dans les messages de résultat. La valeur `costUSD` est une estimation côté client. Voir [Suivi des coûts et de l'utilisation](/docs/fr/agent-sdk/cost-tracking) pour les avertissements de facturation.5077Statistiques d'utilisation par modèle renvoyées dans les messages de résultat. La valeur `costUSD` est une estimation côté client. Consultez [Suivre le coût et l'utilisation](/docs/fr/agent-sdk/cost-tracking) pour les avertissements de facturation.
5056 5078
5057```typescript theme={null}5079```typescript theme={null}
5058type ModelUsage = {5080type ModelUsage = {
5071};5093};
5072```5094```
5073 5095
5074`thinkingTokens` compte les tokens de réflexion que ce modèle a générés. `outputTokens` les inclut déjà, donc n'additionnez pas les deux. Le champ est absent jusqu'à ce qu'un tour s'exécute sur une version de Claude Code qui l'enregistre, donc une session reprise qui a commencé sur une version antérieure rapporte un décompte partiel. `thinkingTokens` nécessite Agent SDK v0.3.257 ou ultérieur.5096`thinkingTokens` compte les jetons de réflexion que ce modèle a générés. `outputTokens` les inclut déjà, donc n'additionnez pas les deux. Le champ est absent jusqu'à ce qu'un tour s'exécute sur une version de Claude Code qui l'enregistre, donc une session reprise qui a commencé sur une version antérieure signale un décompte partiel. `thinkingTokens` nécessite Agent SDK v0.3.257 ou version ultérieure.
5075 5097
5076Les champs `canonicalModel` et `provider` nécessitent Claude Code v2.1.218 ou ultérieur. `canonicalModel` est l'ID de modèle canonique que la recherche de tarification utilise ; il peut différer de la chaîne de modèle brute qui indexe l'entrée, par exemple quand cette chaîne est un ID spécifique au fournisseur ou un alias.5098Les champs `canonicalModel` et `provider` nécessitent Claude Code v2.1.218 ou version ultérieure. `canonicalModel` est l'ID de modèle canonique que la recherche de prix utilise ; il peut différer de la chaîne de modèle brute qui clé l'entrée, par exemple lorsque cette chaîne est un ID spécifique au fournisseur ou un alias.
5077 5099
5078`provider` nomme le backend API qui a servi le modèle, comme `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` ou `gateway`.5100`provider` nomme le backend API qui a servi le modèle, tel que `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` ou `gateway`.
5079 5101
5080`costBasis` nomme la table de prix qui a tarifé la dernière demande du modèle : `list` pour le prix catalogue, `managed` pour une table [`modelPricing`](/docs/fr/settings-reference#modelpricing), ou `unknown` quand aucun ne correspondait à l'ID du modèle. Le champ nécessite Claude Code v2.1.246 ou ultérieur.5102`costBasis` nomme la table de prix qui a tarifé la dernière requête du modèle : `list` pour le prix catalogue, `managed` pour une table [`modelPricing`](/docs/fr/settings-reference#modelpricing), ou `unknown` lorsqu'aucune ne correspondait à l'ID du modèle. Le champ nécessite Claude Code v2.1.246 ou version ultérieure.
5081 5103
5082<h3 id="configscope">5104<h3 id="configscope">
5083 `ConfigScope`5105 `ConfigScope`
5091 `NonNullableUsage`5113 `NonNullableUsage`
5092</h3>5114</h3>
5093 5115
5094Une version de [`Usage`](#usage) avec tous les champs nullables rendus non nullables.5116Une version de [`Usage`](#usage) avec tous les champs nullables rendus non-nullables.
5095 5117
5096```typescript theme={null}5118```typescript theme={null}
5097type NonNullableUsage = {5119type NonNullableUsage = {
5103 `Usage`5125 `Usage`
5104</h3>5126</h3>
5105 5127
5106Statistiques d'utilisation des tokens. C'est le type `BetaUsage` de `@anthropic-ai/sdk`.5128Statistiques d'utilisation des jetons. C'est le type `BetaUsage` de `@anthropic-ai/sdk`.
5107 5129
5108```typescript theme={null}5130```typescript theme={null}
5109type Usage = {5131type Usage = {
5126 5148
5127`BetaServerToolUsage`, `BetaIterationsUsage` et `BetaOutputTokensDetails` sont définis dans `@anthropic-ai/sdk`.5149`BetaServerToolUsage`, `BetaIterationsUsage` et `BetaOutputTokensDetails` sont définis dans `@anthropic-ai/sdk`.
5128 5150
5129`output_tokens_details` décompose la sortie facturée par catégorie. Il porte actuellement un champ, `thinking_tokens: number`, comptant les tokens de sortie que le modèle a générés comme raisonnement interne, y compris les délimiteurs de bloc de réflexion. Le champ `output_tokens_details` nécessite TypeScript SDK v0.3.228 ou ultérieur, qui regroupe Claude Code v2.1.228.5151`output_tokens_details` décompose la sortie facturée par catégorie. Il porte actuellement un champ, `thinking_tokens: number`, comptant les jetons de sortie que le modèle a générés comme raisonnement interne, y compris les délimiteurs de bloc de réflexion. Le champ `output_tokens_details` nécessite TypeScript SDK v0.3.228 ou version ultérieure, qui regroupe Claude Code v2.1.228.
5130 5152
5131* **Facturation** : lisez la décomposition pour l'observabilité, pas pour la facturation. `output_tokens` reste le total faisant autorité, et `output_tokens - thinking_tokens` approxime la sortie sans raisonnement.5153* **Facturation** : lisez la décomposition pour l'observabilité, pas pour la facturation. `output_tokens` reste le total faisant autorité, et `output_tokens - thinking_tokens` approxime la sortie sans raisonnement.
5132* **Ce que le décompte couvre** : le raisonnement brut que le modèle a produit, qui peut être plus long que le texte de réflexion retourné dans le corps de la réponse. L'API le calcule en retokenisant ce texte brut, donc il peut différer du décompte de génération exact du modèle de quelques tokens.5154* **Ce que le décompte couvre** : le raisonnement brut que le modèle a produit, qui peut être plus long que le texte de réflexion renvoyé dans le corps de la réponse. L'API le calcule en retokenisant ce texte brut, donc il peut différer du décompte de génération exact du modèle de quelques jetons.
5133* **Streaming** : sur les messages d'assistant en flux, cette décomposition, comme `output_tokens`, est un espace réservé `message_start` et ne porte aucun décompte réel, donc lisez-la depuis le `usage` du message de résultat comme [Lire les tokens de sortie du message de résultat](/docs/fr/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) le décrit. Sur le message de résultat, `thinking_tokens` lit `0` quand le modèle ou le fournisseur ne rapporte aucune décomposition.5155* **Streaming** : sur les messages d'assistant diffusés, cette décomposition, comme `output_tokens`, est un espace réservé `message_start` et ne porte aucun décompte réel, donc lisez-la à partir du message de résultat `usage` comme [Lire les jetons de sortie du message de résultat](/docs/fr/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) le décrit. Sur le message de résultat, `thinking_tokens` lit `0` lorsque le modèle ou le fournisseur ne signale aucune décomposition.
5134* **Cas `null`** : `output_tokens_details` lui-même est `null` sur les messages d'assistant que Claude Code synthétise, comme les messages d'erreur API.5156* **Cas `null`** : `output_tokens_details` lui-même est `null` sur les messages d'assistant que Claude Code synthétise, tels que les messages d'erreur API.
5135 5157
5136<h3 id="calltoolresult">5158<h3 id="calltoolresult">
5137 `CallToolResult`5159 `CallToolResult`
5138</h3>5160</h3>
5139 5161
5140Type de résultat d'outil MCP (depuis `@modelcontextprotocol/sdk/types.js`). `structuredContent` est un objet JSON qui peut être retourné aux côtés de `content`, incluant des blocs d'image. Voir [Retourner des données structurées](/docs/fr/agent-sdk/custom-tools#return-structured-data).5162Type de résultat d'outil MCP (de `@modelcontextprotocol/sdk/types.js`). `structuredContent` est un objet JSON qui peut être renvoyé aux côtés de `content`, y compris les blocs d'image. Consultez [Retourner des données structurées](/docs/fr/agent-sdk/custom-tools#return-structured-data).
5141 5163
5142```typescript theme={null}5164```typescript theme={null}
5143type CallToolResult = {5165type CallToolResult = {
5144 content: Array<{5166 content: Array<{
5145 type: "text" | "image" | "audio" | "resource" | "resource_link";5167 type: "text" | "image" | "audio" | "resource" | "resource_link";
5146 // Les champs supplémentaires varient selon le type5168 // Additional fields vary by type
5147 }>;5169 }>;
5148 structuredContent?: Record<string, unknown>;5170 structuredContent?: Record<string, unknown>;
5149 isError?: boolean;5171 isError?: boolean;
5154 `SDKMcpResourceLink`5176 `SDKMcpResourceLink`
5155</h3>5177</h3>
5156 5178
5157Un fichier qu'un outil MCP a retourné par référence. Claude Code construit chaque entrée à partir d'un bloc `resource_link` dans le résultat de l'outil et livre la liste comme `resourceLinks` sur [`SDKUserMessage.tool_use_result`](#sdkusermessage), ou comme `resource_links` sur [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) quand l'appel s'est terminé en arrière-plan. Nécessite Agent SDK v0.3.257 ou ultérieur.5179Un fichier qu'un outil MCP a renvoyé par référence. Claude Code construit chaque entrée à partir d'un bloc `resource_link` dans le résultat de l'outil et livre la liste comme `resourceLinks` sur [`SDKUserMessage.tool_use_result`](#sdkusermessage), ou comme `resource_links` sur [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) lorsque l'appel s'est terminé en arrière-plan. Nécessite Agent SDK v0.3.257 ou version ultérieure.
5158 5180
5159```typescript theme={null}5181```typescript theme={null}
5160type SDKMcpResourceLink = {5182type SDKMcpResourceLink = {
5171Claude Code supprime un bloc dont `uri` ou `name` n'est pas une chaîne, et omet un champ optionnel dont la valeur n'est pas du type listé.5193Claude Code supprime un bloc dont `uri` ou `name` n'est pas une chaîne, et omet un champ optionnel dont la valeur n'est pas du type listé.
5172 5194
5173| Champ | Type | Description |5195| Champ | Type | Description |
5174| :------------ | :------------------------------------- | :----------------------------------------------------------------- |5196| :------------ | :------------------------------------- | :------------------------------------------------------------------- |
5175| `uri` | `string` | URI de la ressource, tel que le serveur l'a retourné |5197| `uri` | `string` | URI de la ressource, telle que le serveur l'a renvoyée |
5176| `name` | `string` | Nom que le serveur a donné à la ressource |5198| `name` | `string` | Nom que le serveur a donné à la ressource |
5177| `title` | `string \| undefined` | Titre d'affichage, quand le serveur en a défini un |5199| `title` | `string \| undefined` | Titre d'affichage, lorsque le serveur en a défini un |
5178| `description` | `string \| undefined` | Description, quand le serveur en a défini une |5200| `description` | `string \| undefined` | Description, lorsque le serveur en a défini une |
5179| `mimeType` | `string \| undefined` | Type MIME, quand le serveur en a défini un |5201| `mimeType` | `string \| undefined` | Type MIME, lorsque le serveur en a défini un |
5180| `size` | `number \| undefined` | Taille en octets, quand le serveur en a défini une |5202| `size` | `number \| undefined` | Taille en octets, lorsque le serveur en a défini une |
5181| `annotations` | `Record<string, unknown> \| undefined` | L'objet d'annotations MCP du bloc, quand le serveur en a défini un |5203| `annotations` | `Record<string, unknown> \| undefined` | L'objet d'annotations MCP du bloc, lorsque le serveur en a défini un |
5182 5204
5183<h3 id="thinkingconfig">5205<h3 id="thinkingconfig">
5184 `ThinkingConfig`5206 `ThinkingConfig`
5190type ThinkingDisplay = "summarized" | "omitted";5212type ThinkingDisplay = "summarized" | "omitted";
5191 5213
5192type ThinkingConfig =5214type ThinkingConfig =
5193 | { type: "adaptive"; display?: ThinkingDisplay } // Le modèle détermine quand et combien raisonner (Opus 4.6+)5215 | { type: "adaptive"; display?: ThinkingDisplay } // The model determines when and how much to reason (Opus 4.6+)
5194 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // Budget de token de réflexion fixe5216 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // Fixed thinking token budget
5195 | { type: "disabled" }; // Pas de réflexion étendue5217 | { type: "disabled" }; // No extended thinking
5196```5218```
5197 5219
5198Le champ `display` optionnel contrôle si le texte de réflexion est retourné `"summarized"` ou `"omitted"`. Sur Claude Opus 4.7 et versions ultérieures, la valeur par défaut de l'API est `"omitted"`, donc définissez `"summarized"` pour recevoir le contenu de réflexion dans les blocs `thinking`. Claude Code n'envoie pas `display` à Amazon Bedrock ou à la plateforme Agent de Google Cloud, donc sur ces fournisseurs Opus 4.7 et versions ultérieures retournent des blocs `thinking` vides même quand vous définissez `display` à `"summarized"`.5220Le champ optionnel `display` contrôle si le texte de réflexion est renvoyé `"summarized"` ou `"omitted"`. Sur Claude Opus 4.7 et versions ultérieures, la valeur par défaut de l'API est `"omitted"`, donc définissez `"summarized"` pour recevoir le contenu de réflexion dans les blocs `thinking`. Claude Code n'envoie pas `display` à Amazon Bedrock ou à la plateforme Agent de Google Cloud, donc sur ces fournisseurs Opus 4.7 et versions ultérieures renvoient des blocs `thinking` vides même lorsque vous définissez `display` sur `"summarized"`.
5199 5221
5200<h3 id="spawnedprocess">5222<h3 id="spawnedprocess">
5201 `SpawnedProcess`5223 `SpawnedProcess`
5232 `SpawnOptions`5254 `SpawnOptions`
5233</h3>5255</h3>
5234 5256
5235Options passées à la fonction de génération personnalisée.5257Options transmises à la fonction de génération personnalisée.
5236 5258
5237```typescript theme={null}5259```typescript theme={null}
5238interface SpawnOptions {5260interface SpawnOptions {
5245```5267```
5246 5268
5247<Note>5269<Note>
5248 Le champ `signal` indique à votre fonction de génération quand arrêter le processus. Passez-le comme option `signal` à `spawn()` de Node, ou passez-le à votre gestionnaire d'arrêt de VM ou de conteneur.5270 Le champ `signal` indique à votre fonction de génération quand arrêter le processus. Transmettez-le comme l'option `signal` au `spawn()` de Node, ou transmettez-le à votre gestionnaire d'arrêt de VM ou de conteneur.
5249 5271
5250 Ce signal ne se déclenche pas au moment où [`Options.abortController`](#options) s'arrête. Le SDK ferme d'abord stdin du processus et attend environ deux secondes pour que l'interface de ligne de commande s'arrête proprement, puis arrête ce signal. Pour réagir au moment où l'appelant s'arrête, écoutez votre propre `Options.abortController.signal`, que votre fonction de génération peut référencer depuis sa portée englobante.5272 Ce signal ne se déclenche pas à l'instant où [`Options.abortController`](#options) s'arrête. Le SDK ferme d'abord stdin du processus et attend environ deux secondes pour que l'interface de ligne de commande s'arrête proprement, puis arrête ce signal. Pour réagir au moment où l'appelant s'arrête, écoutez votre propre `Options.abortController.signal`, que votre fonction de génération peut référencer à partir de sa portée englobante.
5251</Note>5273</Note>
5252 5274
5253<h3 id="mcpsetserversresult">5275<h3 id="mcpsetserversresult">
5264};5286};
5265```5287```
5266 5288
5267Quand vous appelez `setMcpServers()`, Claude Code applique ces règles :5289Lorsque vous appelez `setMcpServers()`, Claude Code applique ces règles :
5268 5290
5269* **Serveurs que l'appel ne nomme pas** : Claude Code garde les serveurs fournis par les plugins en cours d'exécution. Nécessite Agent SDK v0.3.210 ou ultérieur.5291* **Serveurs que l'appel ne nomme pas** : Claude Code maintient les serveurs fournis par plugin en cours d'exécution. Nécessite Agent SDK v0.3.210 ou version ultérieure.
5270* **Serveurs que l'appel nomme** : sauf pour les serveurs intégrés que l'interface de ligne de commande a démarrés au démarrage, Claude Code remplace un serveur en cours d'exécution uniquement quand sa configuration diffère de celle que vous avez passée.5292* **Serveurs que l'appel nomme** : à l'exception des serveurs intégrés que l'interface de ligne de commande a démarrés au démarrage, Claude Code remplace un serveur en cours d'exécution uniquement lorsque sa configuration diffère de celle que vous avez transmise.
5271* **Serveurs intégrés que l'interface de ligne de commande a démarrés au démarrage** : si l'appel en nomme un, Claude Code supprime cette entrée et la rapporte dans `errors`.5293* **Serveurs intégrés que l'interface de ligne de commande a démarrés au démarrage** : si l'appel en nomme un, Claude Code supprime cette entrée et la signale dans `errors`.
5272 5294
5273La promesse se résout après que les serveurs stdio, HTTP et SSE nouvellement ajoutés se connectent ou échouent, donc les outils des serveurs qui se sont connectés sont disponibles au prochain tour.5295La promesse se résout après que les serveurs stdio, HTTP et SSE nouvellement ajoutés se connectent ou échouent, donc les outils des serveurs qui se sont connectés sont disponibles au tour suivant.
5274 5296
5275`added` liste les serveurs que Claude Code a ajoutés ou remplacés, qu'ils se soient connectés ou non. Un serveur qui n'a pas pu se connecter apparaît dans `added` et `errors`, avec le texte d'échec sous `errors` et une ligne `failed` dans [`mcpServerStatus()`](#methods). Avant Claude Code v2.1.257, un serveur dont la tentative de connexion a levé une exception était rapporté uniquement sous `errors`.5297`added` liste les serveurs que Claude Code a ajoutés ou remplacés, qu'ils se soient connectés ou non. Un serveur qui n'a pas pu se connecter apparaît à la fois dans `added` et `errors`, avec le texte d'échec sous `errors` et une ligne `failed` dans [`mcpServerStatus()`](#methods). Avant Claude Code v2.1.257, un serveur dont la tentative de connexion a levé une exception était signalé uniquement sous `errors`.
5276 5298
5277<h3 id="rewindfilesresult">5299<h3 id="rewindfilesresult">
5278 `RewindFilesResult`5300 `RewindFilesResult`
5291};5313};
5292```5314```
5293 5315
5294`skippedLinks` compte les chemins suivis que le rembobinage a refusé de restaurer ou de supprimer pour la sécurité des liens : un lien symbolique, un lien physique ou un autre fichier non régulier au chemin suivi, un répertoire parent qui ne résout plus vers où il pointait quand le point de contrôle a été pris, ou une sauvegarde qui n'a pas pu être lue en toute sécurité. Le champ nécessite Claude Code v2.1.216 ou ultérieur. Un appel d'aperçu avec `rewindFiles(userMessageId, { dryRun: true })` ne le définit jamais.5316`skippedLinks` compte les chemins suivis que la rembobinage a refusé de restaurer ou de supprimer pour la sécurité des liens : un lien symbolique, un lien physique ou un autre fichier non régulier au chemin suivi, un répertoire parent qui ne se résout plus à l'endroit où il pointait lorsque le point de contrôle a été pris, ou une sauvegarde qui n'a pas pu être lue en toute sécurité. Le champ nécessite Claude Code v2.1.216 ou version ultérieure. Un appel d'aperçu avec `rewindFiles(userMessageId, { dryRun: true })` ne le définit jamais.
5295 5317
5296<h3 id="sdkstatusmessage">5318<h3 id="sdkstatusmessage">
5297 `SDKStatusMessage`5319 `SDKStatusMessage`
5298</h3>5320</h3>
5299 5321
5300Message de mise à jour de statut (par exemple, compaction).5322Message de mise à jour d'état (par exemple, compactage).
5301 5323
5302```typescript theme={null}5324```typescript theme={null}
5303type SDKStatusMessage = {5325type SDKStatusMessage = {
5314 `SDKTaskNotificationMessage`5336 `SDKTaskNotificationMessage`
5315</h3>5337</h3>
5316 5338
5317Notification quand une tâche de fond se termine, échoue ou est arrêtée. Les tâches de fond incluent les commandes Bash `run_in_background`, les montres [Monitor](#monitor) et les sous-agents de fond. Pour le champ `ambient`, voir [`SDKTaskStartedMessage`](#sdktaskstartedmessage), qui le définit et son exigence de version.5339Notification lorsqu'une tâche en arrière-plan se termine, échoue ou est arrêtée. Les tâches en arrière-plan incluent les commandes Bash `run_in_background`, les montres [Monitor](#monitor) et les sous-agents en arrière-plan. Pour le champ `ambient`, consultez [`SDKTaskStartedMessage`](#sdktaskstartedmessage), qui le définit et son exigence de version.
5318 5340
5319```typescript theme={null}5341```typescript theme={null}
5320type SDKTaskNotificationMessage = {5342type SDKTaskNotificationMessage = {
5337};5359};
5338```5360```
5339 5361
5340Quand Claude Code [déplace un long appel d'outil MCP en arrière-plan](/docs/fr/mcp#automatic-backgrounding-of-long-tool-calls), le bloc `tool_result` pour cet appel ne contient qu'un espace réservé et le résultat réel de l'appel arrive dans cette notification. Faites correspondre la notification à l'appel avec `tool_use_id`. Sur une notification `completed`, `resource_links` liste les fichiers que l'outil a retournés par référence comme entrées [`SDKMcpResourceLink`](#sdkmcpresourcelink), avec les mêmes limites de 50 liens et 64 KiB que [`tool_use_result.resourceLinks`](#sdkusermessage). Claude Code omet `resource_links` quand le résultat n'avait pas de liens et sur les notifications pour les tâches qui ne sont pas des appels d'outil MCP. `resource_links` nécessite Agent SDK v0.3.257 ou ultérieur.5362Lorsque Claude Code [déplace un long appel d'outil MCP en arrière-plan](/docs/fr/mcp#automatic-backgrounding-of-long-tool-calls), le bloc `tool_result` pour cet appel ne contient qu'un espace réservé et le résultat réel de l'appel arrive dans cette notification. Faites correspondre la notification à l'appel avec `tool_use_id`. Sur une notification `completed`, `resource_links` liste les fichiers que l'outil a renvoyés par référence comme entrées [`SDKMcpResourceLink`](#sdkmcpresourcelink), avec les mêmes limites de 50 liens et 64 KiB que [`tool_use_result.resourceLinks`](#sdkusermessage). Claude Code omet `resource_links` lorsque le résultat n'avait pas de liens et sur les notifications pour les tâches qui ne sont pas des appels d'outil MCP. `resource_links` nécessite Agent SDK v0.3.257 ou version ultérieure.
5341 5363
5342Claude Code ajoute une notice à chaque notification de tâche qu'il envoie au modèle, sauf les livraisons estampillées avec la [sous-sorte `scheduled-trigger`](#task-notification-subkinds), qui portent un encadrement de tâche assignée à la place. La notice indique qu'aucune entrée humaine n'a eu lieu, donc le modèle ne traite pas la notification comme une instruction ou une approbation de l'utilisateur.5364Claude Code ajoute un avis à chaque notification de tâche qu'il envoie au modèle, sauf les livraisons estampillées avec le sous-type [`scheduled-trigger`](#task-notification-subkinds), qui portent plutôt un cadrage de tâche assignée. L'avis indique qu'aucune entrée humaine n'a eu lieu, donc le modèle ne traite pas la notification comme une instruction ou une approbation de l'utilisateur.
5343 5365
5344Pour détecter un tour de notification de tâche, vérifiez `origin.kind === "task-notification"` sur [`SDKUserMessage`](#sdkusermessage) ou [`SDKResultMessage`](#sdkresultmessage) plutôt que de faire correspondre le texte de la notice. Lisez `subkind` depuis le même champ si vous avez besoin de savoir ce qui l'a levée. Avant v2.1.205, Claude Code laissait la notice hors des notifications qui arrivaient pendant que la session était inactive.5366Pour détecter un tour de notification de tâche, vérifiez `origin.kind === "task-notification"` sur [`SDKUserMessage`](#sdkusermessage) ou [`SDKResultMessage`](#sdkresultmessage) plutôt que de faire correspondre le texte de l'avis. Lisez `subkind` à partir du même champ si vous avez besoin de savoir ce qui l'a soulevé. Avant v2.1.205, Claude Code laissait l'avis hors des notifications qui arrivaient pendant que la session était inactive.
5345 5367
5346<h3 id="sdktoolusesummarymessage">5368<h3 id="sdktoolusesummarymessage">
5347 `SDKToolUseSummaryMessage`5369 `SDKToolUseSummaryMessage`
5363 `SDKHookStartedMessage`5385 `SDKHookStartedMessage`
5364</h3>5386</h3>
5365 5387
5366Émis quand un hook commence à s'exécuter.5388Émis lorsqu'un hook commence à s'exécuter.
5367 5389
5368Claude Code livre ce message, [`SDKHookProgressMessage`](#sdkhookprogressmessage) et [`SDKHookResponseMessage`](#sdkhookresponsemessage) au flux de messages immédiatement, y compris pendant qu'un hook `SessionStart` ou `Setup` s'exécute encore lors du démarrage de la session. Claude Code v2.1.169 à v2.1.203 a livré ces messages en un seul lot après qu'un hook `SessionStart` ou `Setup` se soit terminé ; v2.1.204 a restauré la livraison en direct.5390Claude Code livre ce message, [`SDKHookProgressMessage`](#sdkhookprogressmessage) et [`SDKHookResponseMessage`](#sdkhookresponsemessage) au flux de messages immédiatement, y compris pendant qu'un hook `SessionStart` ou `Setup` s'exécute toujours au démarrage de la session. Claude Code v2.1.169 à v2.1.203 livrait ces messages en un lot après qu'un hook `SessionStart` ou `Setup` se soit terminé ; v2.1.204 a restauré la livraison en direct.
5369 5391
5370```typescript theme={null}5392```typescript theme={null}
5371type SDKHookStartedMessage = {5393type SDKHookStartedMessage = {
5404 `SDKHookResponseMessage`5426 `SDKHookResponseMessage`
5405</h3>5427</h3>
5406 5428
5407Émis quand un hook termine l'exécution.5429Émis lorsqu'un hook termine son exécution.
5408 5430
5409```typescript theme={null}5431```typescript theme={null}
5410type SDKHookResponseMessage = {5432type SDKHookResponseMessage = {
5452};5474};
5453```5475```
5454 5476
5455Pendant qu'un appel d'outil s'exécute dans la conversation principale, Claude Code émet un message `tool_progress` toutes les 30 secondes avec `heartbeat: true`. Chaque battement porte le nom de l'outil et les secondes écoulées, donc vous pouvez distinguer un appel de longue durée d'une session bloquée. Claude Code n'émet pas de battements pour les appels d'outil à l'intérieur d'un sous-agent. Le champ `heartbeat` nécessite Agent SDK v0.3.214 ou ultérieur. Avant v2.1.257, Claude Code n'émettait pas non plus de battements pour un appel d'outil Agent au premier plan.5477Pendant qu'un appel d'outil s'exécute dans la conversation principale, Claude Code émet un message `tool_progress` toutes les 30 secondes avec `heartbeat: true`. Chaque battement porte le nom de l'outil et les secondes écoulées, afin que vous puissiez distinguer un appel de longue durée d'une session bloquée. Claude Code n'émet pas de battements pour les appels d'outil à l'intérieur d'un sous-agent. Le champ `heartbeat` nécessite Agent SDK v0.3.214 ou version ultérieure. Avant v2.1.257, Claude Code n'émettait pas non plus de battements pour un appel d'outil Agent au premier plan.
5456 5478
5457Sur les messages `tool_progress` pour l'outil Agent autres que les battements, `subagent_type` nomme le type de sous-agent en cours d'exécution, comme `general-purpose`. `subagent_retry` est présent pendant que ce sous-agent attend un backoff d'erreur API, comme une limite de débit ou une surcharge, avec un message par tentative de nouvelle tentative. Les deux champs nécessitent Agent SDK v0.3.214 ou ultérieur.5479Sur les messages `tool_progress` pour l'outil Agent autres que les battements, `subagent_type` nomme le type de sous-agent en cours d'exécution, tel que `general-purpose`. `subagent_retry` est présent pendant que ce sous-agent attend un backoff d'erreur API, tel qu'une limite de débit ou une surcharge, avec un message par tentative de nouvelle tentative. Les deux champs nécessitent Agent SDK v0.3.214 ou version ultérieure.
5458 5480
5459Pour rendre un indicateur de nouvelle tentative à partir de `subagent_retry` :5481Pour rendre un indicateur de nouvelle tentative à partir de `subagent_retry` :
5460 5482
5461* Suivez l'indicateur par `parent_tool_use_id`, qui est unique par sous-agent. `tool_use_id` est partagé par les sous-agents parallèles d'un tour d'assistant, donc le suivi par celui-ci laisserait la mise à jour d'un sous-agent effacer l'indicateur d'un autre.5483* Suivez l'indicateur par `parent_tool_use_id`, qui est unique par sous-agent. `tool_use_id` est partagé par les sous-agents parallèles d'un tour d'assistant, donc le suivi par celui-ci laisserait la mise à jour d'un sous-agent effacer l'indicateur d'un autre.
5462* Effacez l'indicateur quand un `tool_progress` ultérieur pour le même `parent_tool_use_id` arrive sans `subagent_retry` ni `heartbeat: true`, ou quand le message de résultat de l'outil arrive. Les cadres avec `heartbeat: true` rapportent uniquement la vivacité, donc gardez l'indicateur quand un arrive. `attempt` peut dépasser `max_retries` sous une nouvelle tentative persistante, donc ne dérivez pas l'effacement des compteurs.5484* Effacez l'indicateur lorsqu'un `tool_progress` ultérieur pour le même `parent_tool_use_id` arrive sans `subagent_retry` ni `heartbeat: true`, ou lorsque le message de résultat de l'outil arrive. Les cadres avec `heartbeat: true` ne signalent que la vivacité, donc conservez l'indicateur lorsqu'un arrive. `attempt` peut dépasser `max_retries` sous une nouvelle tentative persistante, donc ne dérivez pas l'effacement des compteurs.
5463* Traitez `error_category` comme un ensemble fermé de jetons pour choisir votre propre texte de message, pas comme du texte d'affichage : `rate_limit`, `overloaded`, `authentication_failed`, `server_error` ou `unknown`.5485* Traitez `error_category` comme un jeton pour choisir votre propre texte de message, pas comme du texte d'affichage. Les valeurs sont `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, `cloud_credential_error` et `unknown`. Gérez une valeur que vous ne reconnaissez pas de la même manière que vous gérez `unknown`, car les versions ultérieures peuvent ajouter des valeurs.
5464 5486
5465<h3 id="sdkauthstatusmessage">5487<h3 id="sdkauthstatusmessage">
5466 `SDKAuthStatusMessage`5488 `SDKAuthStatusMessage`
5483 `SDKTaskStartedMessage`5505 `SDKTaskStartedMessage`
5484</h3>5506</h3>
5485 5507
5486Émis quand une tâche commence. Le champ `task_type` est `"local_bash"` pour les commandes Bash et les montres [Monitor](#monitor), `"local_agent"` pour les sous-agents, ou `"remote_agent"`.5508Émis lorsqu'une tâche commence. Le champ `task_type` est `"local_bash"` pour les commandes Bash et les montres [Monitor](#monitor), `"local_agent"` pour les sous-agents, ou `"remote_agent"`.
5487 5509
5488```typescript theme={null}5510```typescript theme={null}
5489type SDKTaskStartedMessage = {5511type SDKTaskStartedMessage = {
5501};5523};
5502```5524```
5503 5525
5504`ambient` est `true` pour les tâches qui ne font pas partie du travail de la session, comme les tâches que Claude Code exécute pour son propre fonctionnement. Les observateurs de mise à jour en direct sont également ambiants, y compris les observateurs que l'utilisateur a demandés. Excluez les tâches ambiantes des indicateurs d'activité. Le champ nécessite Agent SDK v0.3.247 ou ultérieur.5526`ambient` est `true` pour les tâches qui ne font pas partie du travail de la session, telles que les tâches que Claude Code exécute pour son propre fonctionnement. Les montres de mise à jour en direct sont également ambiantes, y compris les montres que l'utilisateur a demandées. Excluez les tâches ambiantes des indicateurs d'activité. Le champ nécessite Agent SDK v0.3.247 ou version ultérieure.
5505 5527
5506`ambient` apparaît également sur [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) et sur les entrées [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage).5528`ambient` apparaît également sur [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) et sur les entrées [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage).
5507 5529
5508`is_backgrounded` et `spawn_depth` décrivent comment Claude Code a démarré la tâche. Les deux champs nécessitent Agent SDK v0.3.238 ou ultérieur.5530`is_backgrounded` et `spawn_depth` décrivent comment Claude Code a démarré la tâche. Les deux champs nécessitent Agent SDK v0.3.238 ou version ultérieure.
5509 5531
5510* `is_backgrounded` : Claude Code le définit sur les tâches `"local_agent"` et `"local_bash"`. `true` signifie que la tâche s'exécute en arrière-plan. `false` signifie que la tâche s'exécute au premier plan, et l'appel d'outil qui l'a démarrée reste bloqué jusqu'à ce que la tâche se termine ou se déplace en arrière-plan.5532* `is_backgrounded` : Claude Code le définit sur les tâches `"local_agent"` et `"local_bash"`. `true` signifie que la tâche s'exécute en arrière-plan. `false` signifie que la tâche s'exécute au premier plan, et l'appel d'outil qui l'a démarrée reste bloqué jusqu'à ce que la tâche se termine ou se déplace en arrière-plan.
5511* `spawn_depth` : Claude Code le définit uniquement sur les tâches `"local_agent"`. Un sous-agent que le thread principal a généré a une profondeur `1`. Un sous-agent qu'un sous-agent de profondeur `1` a généré a une profondeur `2`, et ainsi de suite.5533* `spawn_depth` : Claude Code le définit uniquement sur les tâches `"local_agent"`. Un sous-agent que le thread principal a généré a une profondeur `1`. Un sous-agent qu'un sous-agent de profondeur `1` a généré a une profondeur `2`, et ainsi de suite.
5512 5534
5513Un [sous-agent repris](/docs/fr/agent-sdk/subagents#resume-subagents) rapporte toujours `is_backgrounded: true`, car Claude Code exécute chaque sous-agent repris en arrière-plan. Quand une tâche au premier plan se déplace en arrière-plan plus tard, Claude Code rapporte la nouvelle valeur `is_backgrounded` dans un message [`task_updated`](#sdktaskupdatedmessage) plutôt que d'envoyer un second `task_started`.5535Un [sous-agent repris](/docs/fr/agent-sdk/subagents#resume-subagents) signale toujours `is_backgrounded: true`, car Claude Code exécute chaque sous-agent repris en arrière-plan. Lorsqu'une tâche au premier plan se déplace en arrière-plan plus tard, Claude Code signale la nouvelle valeur `is_backgrounded` dans un message [`task_updated`](#sdktaskupdatedmessage) plutôt que d'envoyer un second `task_started`.
5514 5536
5515<h3 id="sdktaskprogressmessage">5537<h3 id="sdktaskprogressmessage">
5516 `SDKTaskProgressMessage`5538 `SDKTaskProgressMessage`
5517</h3>5539</h3>
5518 5540
5519Émis périodiquement pendant qu'un sous-agent ou une tâche de fond s'exécute. Le champ `summary` est rempli uniquement quand [`agentProgressSummaries`](#options) est activé.5541Émis périodiquement pendant qu'un sous-agent ou une tâche en arrière-plan s'exécute. Le champ `summary` est rempli uniquement lorsque [`agentProgressSummaries`](#options) est activé.
5520 5542
5521```typescript theme={null}5543```typescript theme={null}
5522type SDKTaskProgressMessage = {5544type SDKTaskProgressMessage = {
5542 `SDKTaskUpdatedMessage`5564 `SDKTaskUpdatedMessage`
5543</h3>5565</h3>
5544 5566
5545Émis quand l'état d'une tâche de fond change, par exemple quand elle passe de `running` à `completed`. Fusionnez `patch` dans votre carte de tâches locale indexée par `task_id`. Le champ `end_time` est un timestamp Unix epoch en millisecondes, comparable avec `Date.now()`.5567Émis lorsque l'état d'une tâche en arrière-plan change, par exemple lorsqu'elle passe de `running` à `completed`. Fusionnez `patch` dans votre carte de tâches locale indexée par `task_id`. Le champ `end_time` est un horodatage d'époque Unix en millisecondes, comparable avec `Date.now()`.
5546 5568
5547```typescript theme={null}5569```typescript theme={null}
5548type SDKTaskUpdatedMessage = {5570type SDKTaskUpdatedMessage = {
5566 `SDKBackgroundTasksChangedMessage`5588 `SDKBackgroundTasksChangedMessage`
5567</h3>5589</h3>
5568 5590
5569Émis chaque fois que l'ensemble des tâches de fond en direct change : une tâche démarre, se termine, est tuée, un agent au premier plan est mis en arrière-plan, ou la `description` ou le champ `ambient` d'une tâche change.5591Émis chaque fois que l'ensemble des tâches en arrière-plan en direct change : une tâche démarre, se termine, est tuée, un agent au premier plan est mis en arrière-plan, ou le champ `description` ou `ambient` d'une tâche change.
5570 5592
5571Le tableau `tasks` est l'ensemble complet en direct. Remplacez tout ensemble en cache par chaque charge utile au lieu d'associer les événements `task_started` et `task_notification`, de sorte que le prochain changement d'adhésion corrige tout événement que vous avez manqué.5593Le tableau `tasks` est l'ensemble en direct complet. Remplacez tout ensemble mis en cache par chaque charge utile au lieu d'appairer les événements `task_started` et `task_notification`, afin que le prochain changement d'adhésion corrige tout événement que vous avez manqué.
5572 5594
5573L'ordre par rapport à ces événements par tâche n'est pas spécifié, donc ne mettez pas en corrélation les deux flux.5595L'ordre relatif à ces événements par tâche n'est pas spécifié, donc ne corrélez pas les deux flux.
5574 5596
5575Rien n'est émis au démarrage. Réinitialisez à un ensemble vide chaque fois que le processus CLI de la session démarre ou redémarre et laissez le prochain changement d'adhésion le repeupler.5597Rien n'est émis au démarrage. Réinitialisez à un ensemble vide chaque fois que le processus CLI de la session démarre ou redémarre et laissez le prochain changement d'adhésion le repeupler.
5576 5598
5577Quand vous envoyez une demande de contrôle `initialize` répétée à une session en cours d'exécution, comme avec [`reinitialize()`](#query-object) après une interruption de transport, Claude Code suit la réponse avec un instantané de l'ensemble en direct actuel, même quand il est vide. Un hôte qui se reconnecte apprend donc ce qui s'exécute sans attendre le prochain changement d'adhésion. Avant Agent SDK v0.3.239, Claude Code n'envoyait pas d'instantané après une `initialize` répétée.5599Lorsque vous envoyez une demande de contrôle `initialize` répétée à une session en cours d'exécution, par exemple avec [`reinitialize()`](#query-object) après un écart de transport, Claude Code suit la réponse avec un instantané de l'ensemble en direct actuel, même lorsqu'il est vide. Un hôte qui se reconnecte apprend donc ce qui s'exécute sans attendre le prochain changement d'adhésion. Avant Agent SDK v0.3.239, Claude Code n'envoyait aucun instantané après un `initialize` répété.
5578 5600
5579Nécessite Claude Code v2.1.203 ou ultérieur.5601Nécessite Claude Code v2.1.203 ou version ultérieure.
5580 5602
5581```typescript theme={null}5603```typescript theme={null}
5582type SDKBackgroundTasksChangedMessage = {5604type SDKBackgroundTasksChangedMessage = {
5597 `SDKThinkingTokensMessage`5619 `SDKThinkingTokensMessage`
5598</h3>5620</h3>
5599 5621
5600Émis pendant que Claude produit un bloc de réflexion, y compris un bloc masqué. `estimated_tokens` est une estimation en cours des tokens de réflexion générés jusqu'à présent dans le bloc actuel, et `estimated_tokens_delta` est l'incrément porté par cette trame. Utilisez ces estimations pour l'affichage de la progression.5622Émis pendant que Claude produit un bloc de réflexion, y compris un bloc édité. `estimated_tokens` est une estimation en cours des jetons de réflexion générés jusqu'à présent dans le bloc actuel, et `estimated_tokens_delta` est l'incrément porté par ce cadre. Utilisez ces estimations pour l'affichage de la progression.
5601 5623
5602Quand le modèle ou le fournisseur rapporte une décomposition, le décompte final pour la boucle d'agent de haut niveau est le [`usage.output_tokens_details.thinking_tokens`](#usage) du message de résultat, qui [n'inclut pas les tokens des sous-agents](/docs/fr/agent-sdk/cost-tracking#get-the-total-cost-of-a-query).5624Lorsque le modèle ou le fournisseur signale une décomposition, le décompte final pour la boucle d'agent de haut niveau est le [`usage.output_tokens_details.thinking_tokens`](#usage) du message de résultat, qui [n'inclut pas les jetons de sous-agent](/docs/fr/agent-sdk/cost-tracking#get-the-total-cost-of-a-query).
5603 5625
5604Nécessite Claude Code v2.1.153 ou ultérieur.5626Nécessite Claude Code v2.1.153 ou version ultérieure.
5605 5627
5606```typescript theme={null}5628```typescript theme={null}
5607type SDKThinkingTokensMessage = {5629type SDKThinkingTokensMessage = {
5619 `SDKFilesPersistedEvent`5641 `SDKFilesPersistedEvent`
5620</h3>5642</h3>
5621 5643
5622Émis quand les points de contrôle de fichiers sont persistés sur disque.5644Émis lorsque les points de contrôle de fichiers sont persistés sur le disque.
5623 5645
5624```typescript theme={null}5646```typescript theme={null}
5625type SDKFilesPersistedEvent = {5647type SDKFilesPersistedEvent = {
5637 `SDKRateLimitEvent`5659 `SDKRateLimitEvent`
5638</h3>5660</h3>
5639 5661
5640Émis quand la session rencontre une limite de débit.5662Émis lorsque la session rencontre une limite de débit.
5641 5663
5642```typescript theme={null}5664```typescript theme={null}
5643type SDKRateLimitEvent = {5665type SDKRateLimitEvent = {
5655};5677};
5656```5678```
5657 5679
5658Quand `errorCode` est `"credits_required"`, le rejet provient d'un abonnement claude.ai dont l'utilisation incluse est épuisée, et la session ne peut pas continuer jusqu'à ce que l'utilisateur achète des crédits d'utilisation. `canUserPurchaseCredits` indique si l'utilisateur authentifié peut acheter des crédits pour le compte, et `hasChargeableSavedPaymentMethod` indique si une méthode de paiement enregistrée est disponible. Ces trois champs sont absents sur les événements de limite de débit qui ne sont pas des rejets de crédits requis. Nécessite Claude Code v2.1.181 ou ultérieur.5680Lorsque `errorCode` est `"credits_required"`, le rejet provient d'un abonnement claude.ai dont l'utilisation incluse est épuisée, et la session ne peut pas continuer jusqu'à ce que l'utilisateur achète des crédits d'utilisation. `canUserPurchaseCredits` indique si l'utilisateur authentifié peut acheter des crédits pour le compte, et `hasChargeableSavedPaymentMethod` indique si une méthode de paiement enregistrée est en dossier. Les trois champs sont absents sur les événements de limite de débit qui ne sont pas des rejets de crédits requis. Nécessite Claude Code v2.1.181 ou version ultérieure.
5659 5681
5660<h3 id="sdklocalcommandoutputmessage">5682<h3 id="sdklocalcommandoutputmessage">
5661 `SDKLocalCommandOutputMessage`5683 `SDKLocalCommandOutputMessage`
5662</h3>5684</h3>
5663 5685
5664Claude Code n'émet pas ce type de message. Quand vous envoyez une commande telle que `/context` ou `/usage` comme une invite, sa sortie arrive comme un [`SDKAssistantMessage`](#sdkassistantmessage).5686Claude Code n'émet pas ce type de message. Lorsque vous envoyez une commande telle que `/context` ou `/usage` comme invite, sa sortie arrive comme [`SDKAssistantMessage`](#sdkassistantmessage).
5665 5687
5666```typescript theme={null}5688```typescript theme={null}
5667type SDKLocalCommandOutputMessage = {5689type SDKLocalCommandOutputMessage = {
5677 `SDKCommandsChangedMessage`5699 `SDKCommandsChangedMessage`
5678</h3>5700</h3>
5679 5701
5680Émis quand l'ensemble des commandes disponibles change en cours de session, par exemple quand Claude Code découvre des compétences alors que l'agent entre dans un sous-répertoire. Le tableau `commands` est la liste complète mise à jour, donc remplacez toute liste de commandes en cache par cette charge utile. Appeler [`supportedCommands()`](#query-object) après ce message retourne la même liste mise à jour, car la méthode suit le dernier push ; cela nécessite Agent SDK v0.3.216 ou ultérieur. Dans les versions antérieures du SDK, `supportedCommands()` retourne l'instantané capturé à l'initialisation et ne reflète jamais les changements en cours de session.5702Émis lorsque l'ensemble des commandes disponibles change en milieu de session, par exemple lorsque Claude Code découvre des compétences à mesure que l'agent entre dans un sous-répertoire. Le tableau `commands` est la liste complète mise à jour, donc remplacez tout cache de liste de commandes par cette charge utile. L'appel de [`supportedCommands()`](#query-object) après ce message renvoie la même liste mise à jour, car la méthode suit le dernier push ; cela nécessite Agent SDK v0.3.216 ou version ultérieure. Dans les versions antérieures du SDK, `supportedCommands()` renvoie l'instantané capturé à l'initialisation et ne reflète jamais les changements en milieu de session.
5681 5703
5682```typescript theme={null}5704```typescript theme={null}
5683type SDKCommandsChangedMessage = {5705type SDKCommandsChangedMessage = {
5693 `SDKPromptSuggestionMessage`5715 `SDKPromptSuggestionMessage`
5694</h3>5716</h3>
5695 5717
5696Émis après un tour quand [`promptSuggestions`](#options) est activé et que Claude Code a généré une suggestion pour ce tour. Contient l'invite utilisateur suivante prédite. Pour les tours qui n'en reçoivent pas, voir [Quand Claude Code saute les suggestions](/docs/fr/interactive-mode#when-claude-code-skips-suggestions).5718Émis après un tour lorsque [`promptSuggestions`](#options) est activé et que Claude Code a généré une suggestion pour ce tour. Contient l'invite utilisateur suivante prédite. Pour les tours qui n'en reçoivent pas, consultez [Quand Claude Code ignore les suggestions](/docs/fr/interactive-mode#when-claude-code-skips-suggestions).
5697 5719
5698```typescript theme={null}5720```typescript theme={null}
5699type SDKPromptSuggestionMessage = {5721type SDKPromptSuggestionMessage = {
5708 `SDKConversationResetMessage`5730 `SDKConversationResetMessage`
5709</h3>5731</h3>
5710 5732
5711Émis quand la conversation de la session est remplacée sans terminer la session. Dans un appel `query()`, seul `/clear` et ses alias produisent ce message. Montez une transcription vide sous `new_conversation_id` et abandonnez tout titre de session en cache.5733Émis lorsque la conversation de la session est remplacée sans terminer la session. Dans un appel `query()`, seul `/clear` et ses alias produisent ce message. Montez une transcription vide sous `new_conversation_id` et jetez tout titre de session mis en cache.
5712 5734
5713```typescript theme={null}5735```typescript theme={null}
5714type SDKConversationResetMessage = {5736type SDKConversationResetMessage = {
5719};5741};
5720```5742```
5721 5743
5722Les typages publiés du SDK déclarent `SDKConversationResetMessage` dans Claude Code v2.1.203 et ultérieur. Avant v2.1.203, `SDKMessage` référençait le type sans le déclarer, donc le rétrécissement sur `type === "conversation_reset"` n'a pas pu être typé quand `skipLibCheck` était désactivé.5744Les typages publiés du SDK déclarent `SDKConversationResetMessage` dans Claude Code v2.1.203 et versions ultérieures. Avant v2.1.203, `SDKMessage` référençait le type sans le déclarer, donc le rétrécissement sur `type === "conversation_reset"` n'a pas pu être typé lorsque `skipLibCheck` était désactivé.
5723 5745
5724<h3 id="aborterror">5746<h3 id="aborterror">
5725 `AbortError`5747 `AbortError`
5726</h3>5748</h3>
5727 5749
5728Classe d'erreur personnalisée pour les opérations d'abandon.5750Classe d'erreur personnalisée pour les opérations d'arrêt.
5729 5751
5730```typescript theme={null}5752```typescript theme={null}
5731class AbortError extends Error {}5753class AbortError extends Error {}
5732```5754```
5733 5755
5734`AbortError` est la seule classe d'erreur dans l'API typée du SDK. Les autres défaillances, comme la sortie ou l'échec du lancement du processus Claude Code, rejettent l'itération de message avec des erreurs qui ne portent aucune classe SDK pour correspondre. [Dépannage](/docs/fr/agent-sdk/troubleshooting) indexe ces erreurs par message, avec la cause et la correction pour chacune.5756`AbortError` est la seule classe d'erreur dans l'API typée du SDK. Les autres défaillances, telles que la sortie ou l'échec du lancement du processus Claude Code, rejettent l'itération de message avec des erreurs qui ne portent aucune classe SDK pour correspondre. [Dépannage](/docs/fr/agent-sdk/troubleshooting) clé ces erreurs par message, avec la cause et la correction pour chacune.
5735 5757
5736<h2 id="sandbox-configuration">5758<h2 id="sandbox-configuration">
5737 Configuration du sandbox5759 Configuration du sandbox
5741 `SandboxSettings`5763 `SandboxSettings`
5742</h3>5764</h3>
5743 5765
5744Configuration pour le comportement du sandbox. Utilisez ceci pour activer le sandboxing des commandes et configurer les restrictions réseau par programmation.5766Configuration du comportement du sandbox. Utilisez ceci pour activer le sandboxing des commandes et configurer les restrictions réseau par programmation.
5745 5767
5746```typescript theme={null}5768```typescript theme={null}
5747type SandboxSettings = {5769type SandboxSettings = {
5758};5780};
5759```5781```
5760 5782
5761| Propriété | Type | Par défaut | Description |5783| Property | Type | Default | Description |
5762| :-------------------------- | :---------------------------------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |5784| :-------------------------- | :---------------------------------------------------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5763| `enabled` | `boolean` | `false` | Activer le mode sandbox pour l'exécution des commandes |5785| `enabled` | `boolean` | `false` | Activer le mode sandbox pour l'exécution des commandes |
5764| `failIfUnavailable` | `boolean` | `true` | S'arrêter au démarrage si `enabled` est `true` mais que le sandbox ne peut pas démarrer. Définissez `false` pour revenir à l'exécution non sandboxée avec un avertissement sur stderr |5786| `failIfUnavailable` | `boolean` | `true` | S'arrêter au démarrage si `enabled` est `true` mais que le sandbox ne peut pas démarrer. Définissez `false` pour revenir à l'exécution non sandboxée avec un avertissement sur stderr |
5765| `autoAllowBashIfSandboxed` | `boolean` | `true` | Approuver automatiquement les commandes Bash quand le sandbox est activé |5787| `autoAllowBashIfSandboxed` | `boolean` | `true` | Approuver automatiquement les commandes Bash lorsque le sandbox est activé |
5766| `excludedCommands` | `string[]` | `[]` | Commandes qui contournent toujours les restrictions du sandbox (par exemple, `['docker']`). Celles-ci s'exécutent sans sandbox automatiquement sans implication du modèle |5788| `excludedCommands` | `string[]` | `[]` | Commandes qui contournent les restrictions du sandbox, telles que `['docker *']`. Celles-ci s'exécutent automatiquement sans sandbox et sans intervention du modèle ; [`sandbox.excludedCommands`](/docs/fr/settings-reference#sandbox-excludedcommands) couvre le moment où une entrée s'applique |
5767| `allowUnsandboxedCommands` | `boolean` | `true` | Permettre au modèle de demander l'exécution de commandes en dehors du sandbox. Quand `true`, le modèle peut définir `dangerouslyDisableSandbox` dans l'entrée de l'outil, qui revient au [système de permissions](#permissions-fallback-for-unsandboxed-commands) |5789| `allowUnsandboxedCommands` | `boolean` | `true` | Permettre au modèle de demander l'exécution de commandes en dehors du sandbox. Lorsque `true`, le modèle peut définir `dangerouslyDisableSandbox` dans l'entrée de l'outil, ce qui revient au [système de permissions](#permissions-fallback-for-unsandboxed-commands) |
5768| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | Configuration du sandbox spécifique au réseau |5790| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | Configuration du sandbox spécifique au réseau |
5769| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Configuration du sandbox spécifique au système de fichiers pour les restrictions de lecture/écriture |5791| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Configuration du sandbox spécifique au système de fichiers pour les restrictions de lecture/écriture |
5770| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Carte des sous-chaînes de commande, ou `*` pour chaque commande, aux sous-chaînes du texte de violation à ignorer, comme `{ "*": ['/etc/hosts'] }` ; voir [`sandbox.ignoreViolations`](/docs/fr/settings-reference#sandbox-ignoreviolations) |5792| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mappage des sous-chaînes de commande, ou `*` pour chaque commande, aux sous-chaînes du texte de violation à ignorer, telles que `{ "*": ['/etc/hosts'] }` ; voir [`sandbox.ignoreViolations`](/docs/fr/settings-reference#sandbox-ignoreviolations) |
5771| `enableWeakerNestedSandbox` | `boolean` | `false` | Activer un sandbox imbriqué plus faible pour la compatibilité |5793| `enableWeakerNestedSandbox` | `boolean` | `false` | Activer un sandbox imbriqué plus faible pour la compatibilité |
5772| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuration de binaire ripgrep personnalisée pour les environnements sandbox |5794| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuration du binaire ripgrep personnalisé pour les environnements sandbox |
5773 5795
5774<Note>5796<Note>
5775 Le sandbox dépend du support de la plateforme et, sur Linux, d'outils comme `bubblewrap` et `socat`. Quand `enabled` est `true` et que le sandbox ne peut pas démarrer, `query()` signale un message `result` avec `subtype: "error_during_execution"` et la raison dans `errors`. Pour un appel `query()` à message unique, le SDK lève une exception après avoir produit ce résultat d'erreur, donc enveloppez la boucle dans un bloc try pour continuer au-delà. Voir [Gérer le résultat](/docs/fr/agent-sdk/agent-loop#handle-the-result) pour le contrat d'erreur.5797 Le sandbox dépend du support de la plateforme et, sur Linux, d'outils comme `bubblewrap` et `socat`. Lorsque `enabled` est `true` et que le sandbox ne peut pas démarrer, `query()` signale un message `result` avec `subtype: "error_during_execution"` et la raison dans `errors`. Pour un seul appel `query()`, le SDK lance une exception après avoir cédé ce résultat d'erreur, donc enveloppez la boucle dans un bloc try pour continuer au-delà. Voir [Gérer le résultat](/docs/fr/agent-sdk/agent-loop#handle-the-result) pour le contrat d'erreur.
5776 5798
5777 Pour exécuter sans sandbox à la place, définissez `failIfUnavailable: false`.5799 Pour s'exécuter sans sandbox à la place, définissez `failIfUnavailable: false`.
5778</Note>5800</Note>
5779 5801
5780<h4 id="example-usage">5802<h4 id="example-usage">
5800 if ("result" in message) console.log(message.result);5822 if ("result" in message) console.log(message.result);
5801 }5823 }
5802} catch (error) {5824} catch (error) {
5803 // Un appel query() à message unique lève une exception après avoir produit un résultat d'erreur,5825 // A single-shot query() throws after yielding an error result,
5804 // par exemple quand le sandbox ne peut pas démarrer (failIfUnavailable est par défaut true).5826 // such as when the sandbox can't start (failIfUnavailable defaults to true).
5805 console.log(`Session ended with an error: ${error}`);5827 console.log(`Session ended with an error: ${error}`);
5806}5828}
5807```5829```
5808 5830
5809<Warning>5831<Warning>
5810 **Sécurité des sockets Unix :** L'option `allowUnixSockets` peut accorder l'accès à des services système qui s'étendent en dehors du sandbox. Par exemple, permettre `/var/run/docker.sock` accorde effectivement un accès complet au système hôte via l'API Docker, contournant l'isolation du sandbox. Autorisez uniquement les sockets Unix strictement nécessaires et comprenez les implications de sécurité de chacun.5832 **Sécurité des sockets Unix :** L'option `allowUnixSockets` peut accorder l'accès à des services système qui s'étendent en dehors du sandbox. Par exemple, autoriser `/var/run/docker.sock` accorde effectivement un accès complet au système hôte via l'API Docker, contournant l'isolation du sandbox. Autorisez uniquement les sockets Unix strictement nécessaires et comprenez les implications de sécurité de chacun.
5811</Warning>5833</Warning>
5812 5834
5813<h3 id="sandboxnetworkconfig">5835<h3 id="sandboxnetworkconfig">
5814 `SandboxNetworkConfig`5836 `SandboxNetworkConfig`
5815</h3>5837</h3>
5816 5838
5817Configuration spécifique au réseau pour le mode sandbox. Ces paramètres s'appliquent aux commandes Bash sandboxées quand `enabled` est `true` dans le parent [`SandboxSettings`](#sandboxsettings). Ils ne restreignent pas l'outil WebFetch, qui utilise à la place les [règles de permissions](/docs/fr/permissions#webfetch).5839Configuration spécifique au réseau pour le mode sandbox. Ces paramètres s'appliquent aux commandes Bash sandboxées lorsque `enabled` est `true` dans le parent [`SandboxSettings`](#sandboxsettings). Ils ne restreignent pas l'outil WebFetch, qui utilise à la place des [règles de permission](/docs/fr/permissions#webfetch).
5818 5840
5819```typescript theme={null}5841```typescript theme={null}
5820type SandboxNetworkConfig = {5842type SandboxNetworkConfig = {
5830};5852};
5831```5853```
5832 5854
5833| Propriété | Type | Par défaut | Description |5855| Property | Type | Default | Description |
5834| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |5856| :------------------------ | :--------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5835| `allowedDomains` | `string[]` | `[]` | Noms de domaine auxquels les processus sandboxés peuvent accéder |5857| `allowedDomains` | `string[]` | `[]` | Noms de domaine auxquels les processus sandboxés peuvent accéder |
5836| `deniedDomains` | `string[]` | `[]` | Noms de domaine auxquels les processus sandboxés ne peuvent pas accéder. Prend la priorité sur `allowedDomains` |5858| `deniedDomains` | `string[]` | `[]` | Noms de domaine auxquels les processus sandboxés ne peuvent pas accéder. Prend la priorité sur `allowedDomains` |
5837| `strictAllowlist` | `boolean` | `false` | Refuser aux commandes sandboxées l'accès aux hôtes en dehors de la [liste d'autorisation réseau](/docs/fr/sandboxing#network-isolation) au lieu de demander. Appliqué uniquement aux commandes sandboxées ; les outils en processus tels que WebFetch ne sont pas contrôlés par cela. Honoré uniquement à partir des paramètres utilisateur, gérés ou CLI `--settings` ; les paramètres de projet sont ignorés. Nécessite Claude Code v2.1.219 ou ultérieur |5859| `strictAllowlist` | `boolean` | `false` | Refuser aux commandes sandboxées l'accès aux hôtes en dehors de la [liste d'autorisation réseau](/docs/fr/sandboxing#network-isolation) au lieu de demander. Appliqué uniquement aux commandes sandboxées ; les outils en processus tels que WebFetch ne sont pas contrôlés par celui-ci. Honoré uniquement à partir des paramètres utilisateur, gérés ou CLI `--settings` ; les paramètres de projet sont ignorés. Nécessite Claude Code v2.1.219 ou ultérieur |
5838| `allowManagedDomainsOnly` | `boolean` | `false` | Paramètres gérés uniquement. Quand défini dans les [paramètres gérés](/docs/fr/managed-settings), seules les entrées `allowedDomains` et les règles d'autorisation `WebFetch(domain:...)` des paramètres gérés sont honorées, et les entrées d'autorisation des paramètres utilisateur, projet ou locaux sont ignorées. N'a aucun effet quand défini via les options SDK |5860| `allowManagedDomainsOnly` | `boolean` | `false` | Paramètres gérés uniquement. Lorsqu'il est défini dans les [paramètres gérés](/docs/fr/managed-settings), seules les entrées `allowedDomains` et les règles d'autorisation `WebFetch(domain:...)` des paramètres gérés sont honorées, et les entrées d'autorisation des paramètres utilisateur, projet ou locaux sont ignorées. N'a aucun effet lorsqu'il est défini via les options SDK |
5839| `allowLocalBinding` | `boolean` | `false` | Permettre aux processus de se lier aux ports locaux (par exemple, pour les serveurs de développement) |5861| `allowLocalBinding` | `boolean` | `false` | Permettre aux processus de se lier à des ports locaux (par exemple, pour les serveurs de développement) |
5840| `allowUnixSockets` | `string[]` | `[]` | Chemins de socket Unix auxquels les processus peuvent accéder (par exemple, socket Docker) |5862| `allowUnixSockets` | `string[]` | `[]` | Chemins de socket Unix auxquels les processus peuvent accéder (par exemple, socket Docker) |
5841| `allowAllUnixSockets` | `boolean` | `false` | Permettre l'accès à tous les sockets Unix |5863| `allowAllUnixSockets` | `boolean` | `false` | Permettre l'accès à tous les sockets Unix |
5842| `httpProxyPort` | `number` | `undefined` | Port du proxy HTTP pour les demandes réseau |5864| `httpProxyPort` | `number` | `undefined` | Port du proxy HTTP pour les requêtes réseau |
5843| `socksProxyPort` | `number` | `undefined` | Port du proxy SOCKS pour les demandes réseau |5865| `socksProxyPort` | `number` | `undefined` | Port du proxy SOCKS pour les requêtes réseau |
5844 5866
5845<Note>5867<Note>
5846 Le proxy sandbox intégré applique `allowedDomains` en fonction du nom d'hôte demandé et ne termine pas ou n'inspecte pas le trafic TLS, donc des techniques telles que le [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) peuvent potentiellement le contourner. Voir [Limitations de sécurité du sandboxing](/docs/fr/sandboxing#security-limitations) pour les détails et [Déploiement sécurisé](/docs/fr/agent-sdk/secure-deployment#traffic-forwarding) pour configurer un proxy qui termine TLS.5868 Le proxy sandbox intégré applique `allowedDomains` en fonction du nom d'hôte demandé et ne termine ni n'inspecte le trafic TLS, donc des techniques telles que le [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) peuvent potentiellement le contourner. Voir [Limitations de sécurité du sandboxing](/docs/fr/sandboxing#security-limitations) pour les détails et [Déploiement sécurisé](/docs/fr/agent-sdk/secure-deployment#traffic-forwarding) pour configurer un proxy qui termine TLS.
5847</Note>5869</Note>
5848 5870
5849<h3 id="sandboxfilesystemconfig">5871<h3 id="sandboxfilesystemconfig">
5860};5882};
5861```5883```
5862 5884
5863| Propriété | Type | Par défaut | Description |5885| Property | Type | Default | Description |
5864| :----------- | :--------- | :--------- | :------------------------------------------------------------- |5886| :----------- | :--------- | :------ | :----------------------------------------------------------------------- |
5865| `allowWrite` | `string[]` | `[]` | Motifs de chemin de fichier pour permettre l'accès en écriture |5887| `allowWrite` | `string[]` | `[]` | Modèles de chemin de fichier pour lesquels autoriser l'accès en écriture |
5866| `denyWrite` | `string[]` | `[]` | Motifs de chemin de fichier pour refuser l'accès en écriture |5888| `denyWrite` | `string[]` | `[]` | Modèles de chemin de fichier pour lesquels refuser l'accès en écriture |
5867| `denyRead` | `string[]` | `[]` | Motifs de chemin de fichier pour refuser l'accès en lecture |5889| `denyRead` | `string[]` | `[]` | Modèles de chemin de fichier pour lesquels refuser l'accès en lecture |
5868 5890
5869<h3 id="permissions-fallback-for-unsandboxed-commands">5891<h3 id="permissions-fallback-for-unsandboxed-commands">
5870 Repli des permissions pour les commandes non sandboxées5892 Système de permissions de secours pour les commandes non sandboxées
5871</h3>5893</h3>
5872 5894
5873Quand `allowUnsandboxedCommands` est activé, le modèle peut demander l'exécution de commandes en dehors du sandbox en définissant `dangerouslyDisableSandbox: true` dans l'entrée de l'outil. Ces demandes reviennent au système de permissions existant, ce qui signifie que votre gestionnaire `canUseTool` est invoqué, vous permettant d'implémenter une logique d'autorisation personnalisée. Les commandes listées dans `excludedCommands` contournent plutôt le sandbox automatiquement, sans implication du modèle ; voir [`SandboxSettings`](#sandboxsettings).5895Lorsque `allowUnsandboxedCommands` est activé, le modèle peut demander l'exécution de commandes en dehors du sandbox en définissant `dangerouslyDisableSandbox: true` dans l'entrée de l'outil. Ces demandes reviennent au système de permissions existant, ce qui signifie que votre gestionnaire `canUseTool` est invoqué, vous permettant de mettre en œuvre une logique d'autorisation personnalisée.
5896
5897Vos entrées `excludedCommands` prennent plutôt un appel en dehors du sandbox sans intervention du modèle ; [`sandbox.excludedCommands`](/docs/fr/settings-reference#sandbox-excludedcommands) couvre le moment où une entrée s'applique.
5874 5898
5875Dans l'exemple ci-dessous, `isCommandAuthorized` représente une vérification d'autorisation que vous définissez.5899Dans l'exemple ci-dessous, `isCommandAuthorized` représente une vérification d'autorisation que vous définissez.
5876 5900
5882 options: {5906 options: {
5883 sandbox: {5907 sandbox: {
5884 enabled: true,5908 enabled: true,
5885 allowUnsandboxedCommands: true // Le modèle peut demander l'exécution non sandboxée5909 allowUnsandboxedCommands: true // Model can request unsandboxed execution
5886 },5910 },
5887 permissionMode: "default",5911 permissionMode: "default",
5888 canUseTool: async (tool, input) => {5912 canUseTool: async (tool, input) => {
5889 // Vérifier si le modèle demande de contourner le sandbox5913 // Check if the model is requesting to bypass the sandbox
5890 if (tool === "Bash" && input.dangerouslyDisableSandbox) {5914 if (tool === "Bash" && input.dangerouslyDisableSandbox) {
5891 // Le modèle demande d'exécuter cette commande en dehors du sandbox5915 // The model is requesting to run this command outside the sandbox
5892 console.log(`Unsandboxed command requested: ${input.command}`);5916 console.log(`Unsandboxed command requested: ${input.command}`);
5893 5917
5894 if (isCommandAuthorized(input.command)) {5918 if (isCommandAuthorized(input.command)) {
5910<Warning>5934<Warning>
5911 Les commandes s'exécutant avec `dangerouslyDisableSandbox: true` ont un accès complet au système. Assurez-vous que votre gestionnaire `canUseTool` valide ces demandes avec soin.5935 Les commandes s'exécutant avec `dangerouslyDisableSandbox: true` ont un accès complet au système. Assurez-vous que votre gestionnaire `canUseTool` valide ces demandes avec soin.
5912 5936
5913 Si `permissionMode` est défini sur `bypassPermissions` et `allowUnsandboxedCommands` est activé, le modèle peut exécuter de manière autonome des commandes en dehors du sandbox sans aucune invite d'approbation, à l'exception des [actions que le mode no n'approuve pas automatiquement](/docs/fr/permission-modes#actions-no-mode-auto-approves). Cette combinaison permet effectivement au modèle d'échapper à l'isolation du sandbox silencieusement.5937 Si `permissionMode` est défini sur `bypassPermissions` et `allowUnsandboxedCommands` est activé, le modèle peut exécuter de manière autonome des commandes en dehors du sandbox sans invites d'approbation, à l'exception des [actions qu'aucun mode n'approuve automatiquement](/docs/fr/permission-modes#actions-no-mode-auto-approves). Cette combinaison permet effectivement au modèle d'échapper à l'isolation du sandbox silencieusement.
5914</Warning>5938</Warning>
5915 5939
5916<h2 id="see-also">5940<h2 id="see-also">
