200| :- | :- | :- | :- |200| :- | :- | :- | :- |
201| `title` | `string` | `undefined` | Titre lisible par l'homme pour l'outil |201| `title` | `string` | `undefined` | Titre lisible par l'homme pour l'outil |
202| `readOnlyHint` | `boolean` | `false` | Si `true`, l'outil ne modifie pas son environnement |202| `readOnlyHint` | `boolean` | `false` | Si `true`, l'outil ne modifie pas son environnement |
203| `destructiveHint` | `boolean` | `true` | Si `true`, l'outil peut effectuer des mises à jour destructrices (uniquement significatif quand `readOnlyHint` est `false`) |203| `destructiveHint` | `boolean` | `true` | Si `true`, l'outil peut effectuer des mises à jour destructrices. Définissez explicitement `destructiveHint: true` sur tout outil que vous marquez [`always_ask`](#mcpservertoolpolicy), sinon le classifieur du mode auto peut approuver les appels de cet outil à la place de votre callback `canUseTool`. Laisser `destructiveHint` non défini ne suffit pas, car Claude Code traite un `destructiveHint` non défini comme `false` lorsqu'il gère les appels `always_ask`, bien que la valeur par défaut de la spécification MCP soit `true` |
204| `idempotentHint` | `boolean` | `false` | Si `true`, les appels répétés avec les mêmes arguments n'ont aucun effet supplémentaire (uniquement significatif quand `readOnlyHint` est `false`) |204| `idempotentHint` | `boolean` | `false` | Si `true`, les appels répétés avec les mêmes arguments n'ont aucun effet supplémentaire (uniquement significatif quand `readOnlyHint` est `false`) |
205| `openWorldHint` | `boolean` | `true` | Si `true`, l'outil interagit avec des entités externes (par exemple, recherche web). Si `false`, le domaine de l'outil est fermé (par exemple, un outil de mémoire) |205| `openWorldHint` | `boolean` | `true` | Si `true`, l'outil interagit avec des entités externes (par exemple, recherche web). Si `false`, le domaine de l'outil est fermé (par exemple, un outil de mémoire) |
206 206
492 492
493Objet de configuration pour la fonction `query()`.493Objet de configuration pour la fonction `query()`.
494 494
495| Propriété | Type | Valeur par défaut | Description |495| Propriété | Type | Par défaut | Description |
496| :- | :- | :- | :- |496| :- | :- | :- | :- |
497| `abortController` | `AbortController` | `new AbortController()` | Contrôleur permettant d'annuler les opérations |497| `abortController` | `AbortController` | `new AbortController()` | Contrôleur permettant d'annuler les opérations |
498| `additionalDirectories` | `string[]` | `[]` | Répertoires supplémentaires auxquels Claude peut accéder. Le SDK transmet chaque entrée à Claude Code sous la forme `--add-dir`, de sorte qu'avec la source de paramètres `project`, Claude Code [charge également les skills, commandes et sous-agents du répertoire](https://code.claude.com/docs/fr/permissions.md#additional-directories-grant-file-access-not-configuration) |498| `additionalDirectories` | `string[]` | `[]` | Répertoires supplémentaires auxquels Claude peut accéder. Le SDK transmet chaque entrée à Claude Code sous la forme `--add-dir`, de sorte qu'avec la source de paramètres `project`, Claude Code [charge également les skills, les commandes et les sous-agents du répertoire](https://code.claude.com/docs/fr/permissions.md#additional-directories-grant-file-access-not-configuration) |
499| `agent` | `string` | `undefined` | Nom de l'agent pour le thread principal. L'agent doit être défini dans l'option `agents` ou dans les paramètres |499| `agent` | `string` | `undefined` | Nom de l'agent pour le thread principal. L'agent doit être défini dans l'option `agents` ou dans les paramètres |
500| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Définir des sous-agents par programmation |500| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Définir des sous-agents par programmation |
501| `agentProgressSummaries` | `boolean` | `false` | Lorsque `true`, génère des résumés de progression d'une ligne pour les sous-agents et les transmet dans les événements [`task_progress`](#sdktaskprogressmessage) via le champ `summary`. S'applique aux sous-agents au premier plan et en arrière-plan |501| `agentProgressSummaries` | `boolean` | `false` | Lorsque `true`, génère des résumés de progression d'une ligne pour les sous-agents et les transmet dans les événements [`task_progress`](#sdktaskprogressmessage) via le champ `summary`. S'applique aux sous-agents au premier plan et en arrière-plan |
502| `allowDangerouslySkipPermissions` | `boolean` | `false` | Active le contournement des permissions. Requis lors de l'utilisation de `permissionMode: 'bypassPermissions'`, au démarrage ou ultérieurement via `setPermissionMode()`. Consultez [mode plan](https://code.claude.com/docs/fr/agent-sdk/permissions.md#plan-mode-plan) pour savoir comment il interagit avec `permissionMode: 'plan'` |502| `allowDangerouslySkipPermissions` | `boolean` | `false` | Active le contournement des permissions. Requis lors de l'utilisation de `permissionMode: 'bypassPermissions'`, au démarrage ou ultérieurement via `setPermissionMode()`. Consultez [mode plan](https://code.claude.com/docs/fr/agent-sdk/permissions.md#plan-mode-plan) pour savoir comment cette option interagit avec `permissionMode: 'plan'` |
503| `allowedTools` | `string[]` | `[]` | Outils à approuver automatiquement sans demande, à l'exception des lectures depuis des [chemins réseau](https://code.claude.com/docs/fr/permissions.md#network-paths). Cela ne limite pas Claude à ces seuls outils. Si vous nommez ici l'un des [outils de suivi des tâches](https://code.claude.com/docs/fr/agent-sdk/todo-tracking.md#model-availability), Claude Code active également ces outils pour la session. Les autres outils non listés sont soumis à `permissionMode` et `canUseTool`. Utilisez `disallowedTools` pour bloquer des outils. Consultez [Permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#allow-and-deny-rules) |503| `allowedTools` | `string[]` | `[]` | Outils à approuver automatiquement sans demande, à l'exception des lectures depuis des [chemins réseau](https://code.claude.com/docs/fr/permissions.md#network-paths). Cela ne limite pas Claude à ces seuls outils. Si vous nommez ici l'un des [outils de suivi des tâches](https://code.claude.com/docs/fr/agent-sdk/todo-tracking.md#model-availability), Claude Code active également cette fonctionnalité pour la session. Les autres outils non listés sont traités par `permissionMode` et `canUseTool`. Utilisez `disallowedTools` pour bloquer des outils. Consultez [Permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#allow-and-deny-rules) |
504| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Activer les fonctionnalités bêta |504| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Activer les fonctionnalités bêta |
505| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Fonction de permission personnalisée, invoquée uniquement lorsque le [flux de permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated) aboutit à une demande. Non invoquée pour les appels approuvés automatiquement par `allowedTools`, les règles d'autorisation ou `permissionMode`. Une règle d'autorisation ne pré-approuve pas les [actions qu'aucun mode n'approuve automatiquement](https://code.claude.com/docs/fr/permission-modes.md#actions-no-mode-auto-approves). Consultez [`CanUseTool`](#canusetool) pour plus de détails |505| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Fonction de permission personnalisée, invoquée uniquement lorsque le [flux de permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated) aboutit à une demande. Non invoquée pour les appels approuvés automatiquement par `allowedTools`, les règles d'autorisation ou `permissionMode`. Une règle d'autorisation ne pré-approuve pas les [actions qu'aucun mode n'approuve automatiquement](https://code.claude.com/docs/fr/permission-modes.md#actions-no-mode-auto-approves). Consultez [`CanUseTool`](#canusetool) pour plus de détails |
506| `continue` | `boolean` | `false` | Poursuivre la conversation la plus récente |506| `continue` | `boolean` | `false` | Poursuivre la conversation la plus récente |
509| `debugFile` | `string` | `undefined` | Écrire les logs de débogage dans un chemin de fichier spécifique. Active implicitement le mode débogage |509| `debugFile` | `string` | `undefined` | Écrire les logs de débogage dans un chemin de fichier spécifique. Active implicitement le mode débogage |
510| `disallowedTools` | `string[]` | `[]` | Outils à refuser. Un nom seul tel que `"Bash"` retire l'outil du contexte de Claude. Une règle ciblée telle que `"Bash(rm *)"` laisse l'outil disponible et refuse les appels correspondants dans tous les modes de permission, y compris `bypassPermissions`, pour la commande [telle qu'écrite](https://code.claude.com/docs/fr/permissions.md#bash-rule-limits). Consultez [Permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#allow-and-deny-rules) |510| `disallowedTools` | `string[]` | `[]` | Outils à refuser. Un nom seul tel que `"Bash"` retire l'outil du contexte de Claude. Une règle ciblée telle que `"Bash(rm *)"` laisse l'outil disponible et refuse les appels correspondants dans tous les modes de permission, y compris `bypassPermissions`, pour la commande [telle qu'écrite](https://code.claude.com/docs/fr/permissions.md#bash-rule-limits). Consultez [Permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#allow-and-deny-rules) |
511| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Contrôle l'effort que Claude consacre à sa réponse. Fonctionne avec la réflexion adaptative pour guider la profondeur de réflexion. Consultez [ajuster le niveau d'effort](https://code.claude.com/docs/fr/model-config.md#adjust-effort-level) |511| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Contrôle l'effort que Claude consacre à sa réponse. Fonctionne avec la réflexion adaptative pour guider la profondeur de réflexion. Consultez [ajuster le niveau d'effort](https://code.claude.com/docs/fr/model-config.md#adjust-effort-level) |
512| `enableFileCheckpointing` | `boolean` | `false` | Activer le suivi des modifications de fichiers pour le retour en arrière. Consultez [Checkpointing de fichiers](https://code.claude.com/docs/fr/agent-sdk/file-checkpointing.md) |512| `enableFileCheckpointing` | `boolean` | `false` | Activer le suivi des modifications de fichiers pour permettre le retour en arrière. Consultez [Checkpointing de fichiers](https://code.claude.com/docs/fr/agent-sdk/file-checkpointing.md) |
513| `env` | `Record<string, string \| undefined>` | `process.env` | Variables d'environnement. Lorsqu'elle est définie, cette option remplace l'environnement du sous-processus au lieu de fusionner avec `process.env`, passez donc `{ ...process.env, YOUR_VAR: 'value' }` pour conserver les variables héritées comme `PATH`. Consultez [Gérer les réponses d'API lentes ou bloquées](#handle-slow-or-stalled-api-responses) pour un exemple de ce modèle, et [Variables d'environnement](https://code.claude.com/docs/fr/env-vars.md) pour les variables que lit la CLI sous-jacente. Définissez `CLAUDE_AGENT_SDK_CLIENT_APP` pour identifier votre application dans l'en-tête User-Agent |513| `env` | `Record<string, string \| undefined>` | `process.env` | Variables d'environnement. Lorsqu'elle est définie, cette option remplace l'environnement du sous-processus au lieu de fusionner avec `process.env`, donc transmettez `{ ...process.env, YOUR_VAR: 'value' }` pour conserver les variables héritées comme `PATH`. Consultez [Gérer les réponses lentes ou bloquées de l'API](#handle-slow-or-stalled-api-responses) pour un exemple de ce modèle, et [Variables d'environnement](https://code.claude.com/docs/fr/env-vars.md) pour les variables que lit la CLI sous-jacente. Définissez `CLAUDE_AGENT_SDK_CLIENT_APP` pour identifier votre application dans l'en-tête User-Agent |
514| `executable` | `'bun' \| 'deno' \| 'node'` | Détecté automatiquement | Runtime JavaScript à utiliser |514| `executable` | `'bun' \| 'deno' \| 'node'` | Détection automatique | Runtime JavaScript à utiliser |
515| `executableArgs` | `string[]` | `[]` | Arguments à transmettre à l'exécutable |515| `executableArgs` | `string[]` | `[]` | Arguments à transmettre à l'exécutable |
516| `extraArgs` | `Record<string, string \| null>` | `{}` | Arguments supplémentaires |516| `extraArgs` | `Record<string, string \| null>` | `{}` | Arguments supplémentaires |
517| `fallbackModel` | `string` | `undefined` | Modèle à utiliser si le modèle principal échoue. Accepte une liste séparée par des virgules. Pour l'ordre et la limite, consultez [Chaînes de modèles de secours](https://code.claude.com/docs/fr/model-config.md#fallback-model-chains). Pour des recommandations, consultez [Choisir un modèle](https://code.claude.com/docs/fr/agent-sdk/configuration.md#choose-a-model) |517| `fallbackModel` | `string` | `undefined` | Modèle à utiliser si le modèle principal échoue. Accepte une liste séparée par des virgules. Pour l'ordre et la limite, consultez [Chaînes de modèles de secours](https://code.claude.com/docs/fr/model-config.md#fallback-model-chains). Pour des conseils, consultez [Choisir un modèle](https://code.claude.com/docs/fr/agent-sdk/configuration.md#choose-a-model) |
518| `forkSession` | `boolean` | `false` | Lors d'une reprise avec `resume`, créer un fork vers un nouvel ID de session au lieu de poursuivre la session d'origine |518| `forkSession` | `boolean` | `false` | Lors d'une reprise avec `resume`, créer un fork vers un nouvel ID de session au lieu de poursuivre la session d'origine |
519| `forwardSubagentText` | `boolean` | `false` | Transmettre le texte et les blocs de réflexion des sous-agents sous forme de messages assistant et utilisateur avec `parent_tool_use_id` défini, afin que les consommateurs puissent afficher une transcription imbriquée. Sans cette option, Claude Code omet le texte et les blocs de réflexion d'un sous-agent qui s'exécute au [premier plan](https://code.claude.com/docs/fr/sub-agents.md#run-subagents-in-foreground-or-background). Pour les sous-agents imbriqués, les skills avec `context: fork` et la version de Claude Code requise pour chacun, consultez [Suivre les messages des sous-agents](https://code.claude.com/docs/fr/headless.md#follow-subagent-messages) |519| `forwardSubagentText` | `boolean` | `false` | Transmettre le texte et les blocs de réflexion des sous-agents sous forme de messages assistant et utilisateur avec `parent_tool_use_id` défini, afin que les consommateurs puissent afficher une transcription imbriquée. Sans cette option, Claude Code omet le texte et les blocs de réflexion d'un sous-agent qui s'exécute au [premier plan](https://code.claude.com/docs/fr/sub-agents.md#run-subagents-in-foreground-or-background). Pour les sous-agents imbriqués, les skills avec `context: fork` et la version de Claude Code requise pour chacun, consultez [Suivre les messages des sous-agents](https://code.claude.com/docs/fr/headless.md#follow-subagent-messages) |
520| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callbacks de hooks pour les événements |520| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callbacks de hooks pour les événements |
521| `includeHookEvents` | `boolean` | `false` | Inclure les événements du cycle de vie des hooks dans le flux de messages sous forme de [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) et [`SDKHookResponseMessage`](#sdkhookresponsemessage). Les événements du cycle de vie des hooks `SessionStart` et `Setup` sont toujours inclus et ne nécessitent pas cette option. Certains événements de hook, tels que `Notification`, `SessionEnd`, `PreCompact` et `PostCompact`, ne produisent jamais de `SDKHookStartedMessage`, même avec cette option. Pour ces événements, Claude Code émet tout de même un `SDKHookProgressMessage` lorsqu'un hook de commande qui s'exécute pendant plus d'une seconde produit une sortie, et n'émet un `SDKHookResponseMessage` que lorsqu'un hook [qui s'exécute en arrière-plan](https://code.claude.com/docs/fr/hooks.md#run-hooks-in-the-background) se termine |521| `includeHookEvents` | `boolean` | `false` | Inclure les événements de cycle de vie des hooks dans le flux de messages sous forme de [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) et [`SDKHookResponseMessage`](#sdkhookresponsemessage). Les événements de cycle de vie des hooks `SessionStart` et `Setup` sont toujours inclus et ne nécessitent pas cette option. Certains événements de hook, tels que `Notification`, `SessionEnd`, `PreCompact` et `PostCompact`, ne produisent jamais de `SDKHookStartedMessage`, même avec cette option. Pour ces événements, Claude Code émet tout de même un `SDKHookProgressMessage` tant qu'un hook de commande qui s'exécute pendant plus d'une seconde produit une sortie, et n'émet un `SDKHookResponseMessage` que lorsqu'un hook [qui s'exécute en arrière-plan](https://code.claude.com/docs/fr/hooks.md#run-hooks-in-the-background) se termine |
522| `includePartialMessages` | `boolean` | `false` | Inclure les événements de messages partiels |522| `includePartialMessages` | `boolean` | `false` | Inclure les événements de messages partiels |
523| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Délai d'expiration en millisecondes pour chaque appel à `sessionStore.load()` et `sessionStore.listSubkeys()` lors de la matérialisation de la reprise. Si l'adaptateur ne se résout pas dans ce délai, la requête échoue au lieu de rester bloquée. Ignoré lorsque `sessionStore` n'est pas défini |523| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Délai d'expiration en millisecondes pour chaque appel à `sessionStore.load()` et `sessionStore.listSubkeys()` pendant la matérialisation de la reprise. Si l'adaptateur ne se résout pas dans ce délai, la requête échoue au lieu de rester bloquée. Ignoré lorsque `sessionStore` n'est pas défini |
524| `managedSettings` | `Settings` | `undefined` | Paramètres de niveau stratégie que votre processus hôte fournit à la session lancée. Sur les machines disposant de paramètres gérés déployés par un administrateur, Claude Code les ignore sauf si la source gérée de priorité la plus élevée de l'administrateur définit `parentSettingsBehavior: 'merge'`, et ne les fusionne jamais lorsqu'un [`policyHelper`](https://code.claude.com/docs/fr/settings-reference#policyhelper) fournit des paramètres gérés. Les valeurs fusionnées passent par un filtre uniquement restrictif ; [Restreindre les paramètres parents](https://code.claude.com/docs/fr/claude-apps-gateway#restrict-parent-settings) décrit ce que le filtre admet et les verrous `allowManaged*Only`. Pour un hôte qui définit [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/fr/env-vars), trois clés sont lues directement depuis ce payload à la place : sa [configuration de modèle](https://code.claude.com/docs/fr/model-config.md#restrict-model-selection) sur Claude Code v2.1.222 ou ultérieure, [`modelPricing`](https://code.claude.com/docs/fr/settings-reference#modelpricing) lorsqu'aucune source gérée ne le définit sur v2.1.246 ou ultérieure, et son entrée env `ENABLE_TOOL_SEARCH` sur v2.1.247 ou ultérieure |524| `managedSettings` | `Settings` | `undefined` | Paramètres de niveau stratégie que votre processus hôte fournit à la session lancée. Sur les machines dotées de paramètres gérés déployés par un administrateur, Claude Code les ignore à moins que la source gérée de plus haute priorité de l'administrateur ne définisse `parentSettingsBehavior: 'merge'`, et ne les fusionne jamais tant qu'un [`policyHelper`](https://code.claude.com/docs/fr/settings-reference#policyhelper) fournit des paramètres gérés. Les valeurs fusionnées passent par un filtre uniquement restrictif ; [Restreindre les paramètres parents](https://code.claude.com/docs/fr/claude-apps-gateway#restrict-parent-settings) décrit ce que le filtre admet ainsi que les verrous `allowManaged*Only`. Un hôte qui définit [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/fr/env-vars) lit plutôt trois clés directement depuis ce payload : sa [configuration de modèle](https://code.claude.com/docs/fr/model-config.md#restrict-model-selection) sur Claude Code v2.1.222 ou ultérieur, [`modelPricing`](https://code.claude.com/docs/fr/settings-reference#modelpricing) lorsqu'aucune source gérée ne le définit sur v2.1.246 ou ultérieur, et son entrée env `ENABLE_TOOL_SEARCH` sur v2.1.247 ou ultérieur |
525| `maxBudgetUsd` | `number` | `undefined` | Arrêter la requête lorsque l'estimation des coûts côté client atteint cette valeur en USD. L'estimation peut dépasser cette valeur, donc [prévoyez une marge](https://code.claude.com/docs/fr/agent-sdk/agent-loop.md#budget-headroom). Ne compte que les dépenses propres à l'appel ; les totaux restaurés depuis une session reprise ne comptent pas. Pour les réserves sur la précision et le comportement de réinitialisation, consultez [Suivre les coûts et l'utilisation](https://code.claude.com/docs/fr/agent-sdk/cost-tracking.md) |525| `maxBudgetUsd` | `number` | `undefined` | Arrêter la requête lorsque l'estimation du coût côté client atteint cette valeur en USD. L'estimation peut dépasser cette valeur, donc [prévoyez une marge](https://code.claude.com/docs/fr/agent-sdk/agent-loop.md#budget-headroom). Ne compte que les dépenses propres à l'appel ; les totaux restaurés depuis une session reprise ne sont pas comptés. Pour les réserves sur la précision et le comportement de réinitialisation, consultez [Suivre les coûts et l'utilisation](https://code.claude.com/docs/fr/agent-sdk/cost-tracking.md) |
526| `maxThinkingTokens` | `number` | `undefined` | *Obsolète :* Utilisez `thinking` à la place. Nombre maximal de tokens pour le processus de réflexion |526| `maxThinkingTokens` | `number` | `undefined` | *Obsolète :* utilisez plutôt `thinking`. Nombre maximal de tokens pour le processus de réflexion |
527| `maxTurns` | `number` | `undefined` | Nombre maximal de tours agentiques (allers-retours d'utilisation d'outils) |527| `maxTurns` | `number` | `undefined` | Nombre maximal de tours agentiques (allers-retours d'utilisation d'outils) |
528| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurations des serveurs MCP |528| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurations des serveurs MCP |
529| `model` | `string` | Valeur par défaut de la CLI | Alias de modèle Claude ou nom complet du modèle. Consultez [valeurs acceptées et ID spécifiques aux fournisseurs](https://code.claude.com/docs/fr/model-config.md#available-models) |529| `model` | `string` | Valeur par défaut de la CLI | Alias de modèle Claude ou nom complet du modèle. Consultez [valeurs acceptées et ID spécifiques aux fournisseurs](https://code.claude.com/docs/fr/model-config.md#available-models) |
530| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback pour gérer les requêtes d'élicitation MCP. Appelé lorsqu'un serveur MCP demande une saisie utilisateur et qu'aucun hook ne la gère en premier. S'il n'est pas fourni, les requêtes d'élicitation non gérées sont automatiquement refusées |530| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback pour gérer les requêtes d'élicitation MCP. Appelé lorsqu'un serveur MCP demande une saisie à l'utilisateur et qu'aucun hook ne la traite en premier. S'il n'est pas fourni, les requêtes d'élicitation non traitées sont automatiquement refusées |
531| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Définir le format de sortie des résultats de l'agent. Consultez [Sorties structurées](https://code.claude.com/docs/fr/agent-sdk/structured-outputs.md) pour plus de détails |531| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Définir le format de sortie des résultats de l'agent. Consultez [Sorties structurées](https://code.claude.com/docs/fr/agent-sdk/structured-outputs.md) pour plus de détails |
532| `outputStyle` | `string` | `undefined` | Ce n'est pas un champ d'`Options`. Définissez plutôt `outputStyle` dans l'objet [`settings`](https://code.claude.com/docs/fr/settings) inline ou dans un fichier de paramètres. Consultez [Activer un style de sortie](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#activate-an-output-style) |532| `outputStyle` | `string` | `undefined` | Ce n'est pas un champ de `Options`. Définissez plutôt `outputStyle` dans l'objet [`settings`](https://code.claude.com/docs/fr/settings) inline ou dans un fichier de paramètres. Consultez [Activer un style de sortie](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#activate-an-output-style) |
533| `pathToClaudeCodeExecutable` | `string` | Résolu automatiquement depuis le binaire natif fourni | Chemin vers l'exécutable Claude Code. Nécessaire uniquement si les dépendances optionnelles ont été ignorées lors de l'installation ou si votre plateforme ne fait pas partie de l'ensemble pris en charge |533| `pathToClaudeCodeExecutable` | `string` | Résolu automatiquement à partir du binaire natif intégré | Chemin vers l'exécutable Claude Code. Nécessaire uniquement si les dépendances optionnelles ont été ignorées lors de l'installation ou si votre plateforme ne fait pas partie de l'ensemble pris en charge |
534| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Mode de permission pour la session. Si vous l'omettez et que rien d'autre ne définit de mode de permission, comme un paramètre [`permissions.defaultMode`](https://code.claude.com/docs/fr/settings-reference#permissions-defaultmode), la session démarre en `default`. Consultez [Modes de permission](https://code.claude.com/docs/fr/agent-sdk/permissions.md#permission-modes) |534| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Mode de permission pour la session. Si vous l'omettez et que rien d'autre ne définit de mode de permission, comme un paramètre [`permissions.defaultMode`](https://code.claude.com/docs/fr/settings-reference#permissions-defaultmode), la session démarre en `default`. Consultez [Modes de permission](https://code.claude.com/docs/fr/agent-sdk/permissions.md#permission-modes) |
535| `permissionPromptToolName` | `string` | `undefined` | Nom de l'outil MCP pour les demandes de permission |535| `permissionPromptToolName` | `string` | `undefined` | Nom de l'outil MCP pour les demandes de permission |
536| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Qui répond aux demandes de permission : `'host'` les achemine vers votre callback [`canUseTool`](#canusetool) ou l'outil `permissionPromptToolName`, et `'none'` [refuse les appels qui auraient déclenché une demande](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated). Nécessite Claude Code v2.1.259 ou ultérieure |536| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Qui répond aux demandes de permission : `'host'` les achemine vers votre callback [`canUseTool`](#canusetool) ou vers l'outil `permissionPromptToolName`, et `'none'` [refuse les appels qui auraient déclenché une demande](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated). Nécessite Claude Code v2.1.259 ou ultérieur |
537| `persistSession` | `boolean` | `true` | Lorsque `false`, désactive la persistance de la session sur disque. Les sessions ne peuvent pas être reprises ultérieurement |537| `persistSession` | `boolean` | `true` | Lorsque `false`, désactive la persistance de la session sur disque. Les sessions ne peuvent alors pas être reprises ultérieurement |
538| `planModeInstructions` | `string` | `undefined` | Instructions de workflow personnalisées pour le mode plan. Lorsque `permissionMode` vaut `'plan'`, cette chaîne remplace le corps par défaut du workflow du mode plan. La CLI l'encadre toujours avec le préambule d'application de la lecture seule et le pied de page du protocole ExitPlanMode |538| `planModeInstructions` | `string` | `undefined` | Instructions de workflow personnalisées pour le mode plan. Lorsque `permissionMode` vaut `'plan'`, cette chaîne remplace le corps du workflow par défaut du mode plan. La CLI l'encadre toujours avec le préambule imposant la lecture seule et le pied de page du protocole ExitPlanMode |
539| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Charger des plugins personnalisés depuis des chemins locaux. Consultez [Plugins](https://code.claude.com/docs/fr/agent-sdk/plugins.md) pour plus de détails |539| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Charger des plugins personnalisés depuis des chemins locaux. Consultez [Plugins](https://code.claude.com/docs/fr/agent-sdk/plugins.md) pour plus de détails |
540| `projectConfigRoot` | `string` | `undefined` | Chemin absolu du checkout de confiance dont `cwd` est un worktree. Claude Code lit les paramètres du projet, `.mcp.json` et les commandes, agents, skills, workflows, routines et styles de sortie du dossier `.claude/` du projet depuis ce répertoire au lieu de `cwd`, et y fait pointer `CLAUDE_PROJECT_DIR`. Les hooks, les scripts auxiliaires tels que `apiKeyHelper` et les serveurs MCP stdio démarrent avec ce répertoire comme répertoire de travail. Les fichiers `CLAUDE.md` et `.claude/rules/` sont toujours chargés depuis `cwd`. Nécessite Claude Code v2.1.275 ou ultérieure |540| `projectConfigRoot` | `string` | `undefined` | Chemin absolu du checkout de confiance dont `cwd` est un worktree. Claude Code lit les paramètres du projet, `.mcp.json`, ainsi que les commandes, agents, skills, workflows, routines et styles de sortie du répertoire `.claude/` du projet depuis ce répertoire au lieu de `cwd`, et définit `CLAUDE_PROJECT_DIR` sur ce répertoire. Les hooks, les scripts auxiliaires tels que `apiKeyHelper` et les serveurs MCP stdio démarrent avec ce répertoire comme répertoire de travail. Les fichiers `CLAUDE.md` et `.claude/rules/` sont toujours chargés depuis `cwd`. Nécessite Claude Code v2.1.275 ou ultérieur |
541| `promptSuggestions` | `boolean` | `false` | Activer les suggestions de prompts. Après un tour, Claude Code émet un message `prompt_suggestion` contenant une prédiction du prochain prompt de l'utilisateur. Claude Code ne génère aucune suggestion pour certains tours, par exemple lorsque votre compte est proche de sa limite d'utilisation ou l'a atteinte. Consultez [Quand Claude Code ignore les suggestions](https://code.claude.com/docs/fr/interactive-mode.md#when-claude-code-skips-suggestions) |541| `promptSuggestions` | `boolean` | `false` | Activer les suggestions de prompts. Après un tour, Claude Code émet un message `prompt_suggestion` contenant une prédiction du prochain prompt de l'utilisateur. Claude Code ne génère aucune suggestion pour certains tours, par exemple lorsque votre compte approche ou a atteint sa limite d'utilisation. Consultez [Quand Claude Code ignore les suggestions](https://code.claude.com/docs/fr/interactive-mode.md#when-claude-code-skips-suggestions) |
542| `resume` | `string` | `undefined` | ID de session à reprendre |542| `resume` | `string` | `undefined` | ID de la session à reprendre |
543| `resumeDropsTurn` | `string` | `undefined` | Avec `resumeSessionAt` : l'UUID du prompt du tour que la reprise tronquante a l'intention d'écarter. Claude Code refuse la reprise lorsque la plage écartée contient quoi que ce soit qui ne soit pas attribuable à ce tour, comme des messages en file d'attente absorbés ou des notifications de tâches, et mentionne le flag `--resume-drops-turn` dans le message de refus. Seules les reprises de l'Agent SDK et du mode print lisent cette paire. Nécessite Claude Code v2.1.223 ou ultérieure |543| `resumeDropsTurn` | `string` | `undefined` | Avec `resumeSessionAt` : l'UUID du prompt du tour que la reprise avec troncature entend supprimer. Claude Code refuse la reprise lorsque la plage supprimée contient quoi que ce soit qui ne peut pas être attribué à ce tour, comme des messages en file d'attente absorbés ou des notifications de tâches, et mentionne le flag `--resume-drops-turn` dans le message de rejet. Seuls l'Agent SDK et les reprises en mode print lisent cette paire. Nécessite Claude Code v2.1.223 ou ultérieur |
544| `resumeSessionAt` | `string` | `undefined` | Reprendre la session à un UUID de message spécifique |544| `resumeSessionAt` | `string` | `undefined` | Reprendre la session à un UUID de message spécifique |
545| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configurer le comportement du sandbox par programmation. Consultez [Paramètres du sandbox](#sandboxsettings) pour plus de détails |545| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configurer le comportement du sandbox par programmation. Consultez [Paramètres du sandbox](#sandboxsettings) pour plus de détails |
546| `sessionId` | `string` | Généré automatiquement | Utiliser un UUID spécifique pour la session au lieu d'en générer un automatiquement |546| `sessionId` | `string` | Généré automatiquement | Utiliser un UUID spécifique pour la session au lieu d'en générer un automatiquement |
547| `sessionStore` | [`SessionStore`](https://code.claude.com/docs/fr/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Dupliquer les transcriptions de session vers un backend externe afin qu'un autre hôte puisse les reprendre. Consultez [Persister les sessions dans un stockage externe](https://code.claude.com/docs/fr/agent-sdk/session-storage.md) |547| `sessionStore` | [`SessionStore`](https://code.claude.com/docs/fr/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Répliquer les transcriptions de session vers un backend externe afin qu'un autre hôte puisse les reprendre. Consultez [Conserver les sessions dans un stockage externe](https://code.claude.com/docs/fr/agent-sdk/session-storage.md) |
548| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Mode de vidage pour `sessionStore`. Ignoré lorsque `sessionStore` n'est pas défini |548| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Mode de vidage pour `sessionStore`. Ignoré lorsque `sessionStore` n'est pas défini |
549| `settings` | `string \| Settings` | `undefined` | Objet de [paramètres](https://code.claude.com/docs/fr/settings.md) inline, chemin vers un fichier de paramètres ou chaîne JSON inline. Alimente la couche de paramètres de flag dans l'[ordre de priorité](https://code.claude.com/docs/fr/settings.md#settings-precedence). Modifiable à l'exécution avec [`applyFlagSettings()`](#applyflagsettings) |549| `settings` | `string \| Settings` | `undefined` | Objet de [paramètres](https://code.claude.com/docs/fr/settings.md) inline, chemin d'un fichier de paramètres ou chaîne JSON inline. Alimente la couche de paramètres de flag dans l'[ordre de priorité](https://code.claude.com/docs/fr/settings.md#settings-precedence). Modifiable à l'exécution avec [`applyFlagSettings()`](#applyflagsettings) |
550| `settingSources` | [`SettingSource`](#settingsource)`[]` | Valeurs par défaut de la CLI (toutes les sources) | Contrôler quels paramètres du système de fichiers charger. Passez `[]` pour désactiver les paramètres utilisateur, projet et locaux. La [stratégie gérée par endpoint](https://code.claude.com/docs/fr/managed-settings.md#delivery-mechanisms) est chargée dans tous les cas ; les paramètres gérés par le serveur sont récupérés lorsque la session s'authentifie avec des identifiants d'organisation sur une [configuration éligible](https://code.claude.com/docs/fr/server-managed-settings.md#platform-availability). Consultez [Utiliser les fonctionnalités de Claude Code](https://code.claude.com/docs/fr/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) |550| `settingSources` | [`SettingSource`](#settingsource)`[]` | Valeurs par défaut de la CLI (toutes les sources) | Contrôler quels paramètres du système de fichiers charger. Transmettez `[]` pour désactiver les paramètres utilisateur, projet et locaux. La [stratégie gérée sur le poste](https://code.claude.com/docs/fr/managed-settings.md#delivery-mechanisms) est chargée dans tous les cas ; les paramètres gérés par le serveur sont récupérés lorsque la session s'authentifie avec des identifiants d'organisation sur une [configuration éligible](https://code.claude.com/docs/fr/server-managed-settings.md#platform-availability). Consultez [Utiliser les fonctionnalités de Claude Code](https://code.claude.com/docs/fr/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) |
551| `skills` | `string[] \| 'all'` | `undefined` | Skills disponibles pour la session. Passez `'all'` pour activer tous les skills découverts, ou une liste de noms de skills. Ne passez que des noms exacts. Sur Agent SDK v0.3.221 ou ultérieure, le SDK rejette les noms mal formés et les noms sous forme de caractères génériques avec une erreur avant de démarrer le processus Claude Code. Lorsque cette option est définie, le SDK ajoute automatiquement l'outil Skill à `allowedTools`. Si vous passez également `tools`, incluez `'Skill'` dans cette liste. Consultez [Skills](https://code.claude.com/docs/fr/agent-sdk/skills.md) |551| `skills` | `string[] \| 'all'` | `undefined` | Skills disponibles pour la session. Transmettez `'all'` pour activer tous les skills découverts, ou une liste de noms de skills. Transmettez uniquement des noms exacts. Sur Agent SDK v0.3.221 ou ultérieur, le SDK rejette les noms mal formés et les noms contenant des caractères génériques avec une erreur avant de démarrer le processus Claude Code. Lorsque cette option est définie, le SDK ajoute automatiquement l'outil Skill à `allowedTools`. Si vous transmettez aussi `tools`, incluez `'Skill'` dans cette liste. Consultez [Skills](https://code.claude.com/docs/fr/agent-sdk/skills.md) |
552| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Fonction personnalisée pour lancer le processus Claude Code. À utiliser pour exécuter Claude Code dans des VM, des conteneurs ou des environnements distants |552| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Fonction personnalisée pour lancer le processus Claude Code. À utiliser pour exécuter Claude Code dans des VM, des conteneurs ou des environnements distants |
553| `stderr` | `(data: string) => void` | `undefined` | Callback pour la sortie stderr |553| `stderr` | `(data: string) => void` | `undefined` | Callback pour la sortie stderr |
554| `strictMcpConfig` | `boolean` | `false` | Utiliser uniquement les serveurs passés dans `mcpServers` et ignorer le `.mcp.json` du projet, les paramètres utilisateur, les serveurs MCP fournis par des plugins et les [connecteurs claude.ai](https://code.claude.com/docs/fr/mcp.md#use-mcp-servers-from-claude-ai) |554| `strictMcpConfig` | `boolean` | `false` | Utiliser uniquement les serveurs transmis dans `mcpServers` et ignorer le `.mcp.json` du projet, les paramètres utilisateur, les serveurs MCP fournis par des plugins et les [connecteurs claude.ai](https://code.claude.com/docs/fr/mcp.md#use-mcp-servers-from-claude-ai) |
555| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt minimal) | Configuration du prompt système. Passez une chaîne pour un prompt personnalisé, ou `{ type: 'preset', preset: 'claude_code' }` pour utiliser le prompt système de Claude Code. Passez un tableau de chaînes avec la constante exportée `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` entre la partie statique et la partie propre à chaque requête pour [mettre en cache la partie statique d'un prompt personnalisé](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt). Avec la forme objet preset, ajoutez `append` pour l'étendre avec des instructions supplémentaires, et définissez `excludeDynamicSections: true` pour déplacer le contexte propre à la session dans le premier message utilisateur afin d'[améliorer la réutilisation du cache de prompts entre machines](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Définissez `snapshot: false` pour reconstruire le prompt à chaque requête au lieu de [réutiliser le prompt enregistré par la session lors de sa première requête](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). Pour définir `snapshot` sur un prompt personnalisé, passez la forme `{ type: 'custom', prompt }`. La forme `{ type: 'custom' }` et le champ `snapshot` nécessitent TypeScript Agent SDK v0.3.257 ou ultérieure |555| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt minimal) | Configuration du prompt système. Transmettez une chaîne pour un prompt personnalisé, ou `{ type: 'preset', preset: 'claude_code' }` pour utiliser le prompt système de Claude Code. Transmettez un tableau de chaînes avec la constante exportée `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` entre la partie statique et la partie propre à chaque requête pour [mettre en cache la partie statique d'un prompt personnalisé](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt). Avec la forme objet du preset, ajoutez `append` pour l'étendre avec des instructions supplémentaires, et définissez `excludeDynamicSections: true` pour déplacer le contexte propre à la session dans le premier message utilisateur afin d'[améliorer la réutilisation du cache de prompts entre machines](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Définissez `snapshot: false` pour reconstruire le prompt à chaque requête au lieu de [réutiliser le prompt que la session a enregistré lors de sa première requête](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). Pour définir `snapshot` sur un prompt personnalisé, utilisez la forme `{ type: 'custom', prompt }`. La forme `{ type: 'custom' }` et le champ `snapshot` nécessitent TypeScript Agent SDK v0.3.257 ou ultérieur |
556| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Budget de tâche côté API en tokens. Lorsqu'il est défini, le modèle est informé de son budget de tokens restant afin de pouvoir doser son utilisation des outils et conclure avant la limite |556| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Budget de tâche côté API, en tokens. Lorsqu'il est défini, le modèle est informé de son budget de tokens restant afin de pouvoir doser son utilisation des outils et conclure avant la limite |
557| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` pour les modèles pris en charge | Contrôle le comportement de réflexion/raisonnement de Claude. Consultez [`ThinkingConfig`](#thinkingconfig) pour les options |557| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` pour les modèles pris en charge | Contrôle le comportement de réflexion/raisonnement de Claude. Consultez [`ThinkingConfig`](#thinkingconfig) pour les options |
558| `title` | `string` | `undefined` | Titre d'affichage de la session. Lors d'une reprise via `resume` ou `continue`, le titre persisté de la session reprise a priorité ; utilisez [`renameSession()`](#renamesession) pour renommer une session existante |558| `title` | `string` | `undefined` | Titre d'affichage de la session. Lors d'une reprise via `resume` ou `continue`, le titre persistant de la session reprise a priorité ; utilisez [`renameSession()`](#renamesession) pour renommer une session existante |
559| `toolAliases` | `Record<string, string>` | `undefined` | Associer des noms d'outils intégrés à des noms d'outils MCP afin que Claude appelle votre implémentation MCP à la place de l'outil intégré. Par exemple, `{ Bash: 'mcp__workspace__bash' }` |559| `toolAliases` | `Record<string, string>` | `undefined` | Associer des noms d'outils intégrés à des noms d'outils MCP afin que Claude appelle votre implémentation MCP à la place de l'outil intégré. Par exemple, `{ Bash: 'mcp__workspace__bash' }` |
560| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuration du comportement des outils intégrés. Consultez [`ToolConfig`](#toolconfig) pour plus de détails |560| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuration du comportement des outils intégrés. Consultez [`ToolConfig`](#toolconfig) pour plus de détails |
561| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuration des outils. Passez un tableau de noms d'outils ou utilisez le preset pour obtenir les outils par défaut de Claude Code |561| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuration des outils. Transmettez un tableau de noms d'outils ou utilisez le preset pour obtenir les outils par défaut de Claude Code |
562| `verbatimPrompts` | `boolean` | `false` | Transmettre chaque prompt tel qu'il est écrit. Le SDK envoie chaque message utilisateur avec `client_composed: true`. Consultez [`client_composed`](#sdkusermessage) pour savoir ce que Claude Code ignore sur ces messages. Utilisez cette option lorsque le texte de votre prompt inclut du contenu que l'utilisateur final n'a pas saisi. Pour un contrôle par tour, laissez-la désactivée et définissez plutôt `client_composed` sur les messages individuels envoyés en streaming. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieure et Claude Code v2.1.248 ou ultérieure ; la version de Claude Code fournie avec ces versions du SDK satisfait l'exigence relative à Claude Code |562| `verbatimPrompts` | `boolean` | `false` | Transmettre chaque prompt tel qu'écrit. Le SDK envoie chaque message utilisateur avec `client_composed: true`. Consultez [`client_composed`](#sdkusermessage) pour savoir ce que Claude Code ignore sur ces messages. Utilisez cette option lorsque le texte de votre prompt inclut du contenu que l'utilisateur final n'a pas saisi. Pour un contrôle tour par tour, laissez-la désactivée et définissez plutôt `client_composed` sur des messages individuels envoyés en streaming. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur et Claude Code v2.1.248 ou ultérieur ; la version de Claude Code intégrée à ces versions du SDK satisfait l'exigence relative à Claude Code |
563 563
564#### Gérer les réponses d'API lentes ou bloquées564#### Gérer les réponses lentes ou bloquées de l'API
565 565
566Le sous-processus CLI lit plusieurs variables d'environnement qui contrôlent les délais d'expiration de l'API et la détection des blocages. Transmettez-les via l'option `env` :566Le sous-processus de la CLI lit plusieurs variables d'environnement qui contrôlent les délais d'expiration de l'API et la détection des blocages. Transmettez-les via l'option `env` :
567 567
568```typescript theme={null}568```typescript theme={null}
569import { query } from "@anthropic-ai/claude-agent-sdk";569import { query } from "@anthropic-ai/claude-agent-sdk";
581});581});
582```582```
583 583
584* [`API_TIMEOUT_MS`](https://code.claude.com/docs/fr/env-vars) : durée pendant laquelle chaque tentative de requête peut attendre les en-têtes de réponse, en millisecondes. Elle ne limite pas la durée d'une réponse en streaming une fois les en-têtes reçus. Valeur par défaut : `600000`. S'applique à la boucle principale et à tous les sous-agents.584* [`API_TIMEOUT_MS`](https://code.claude.com/docs/fr/env-vars) : durée pendant laquelle chaque tentative de requête peut attendre les en-têtes de réponse, en millisecondes. Elle ne limite pas la durée d'une réponse en streaming une fois les en-têtes reçus. Valeur par défaut `600000`. S'applique à la boucle principale et à tous les sous-agents.
585* `CLAUDE_CODE_MAX_RETRIES` : nombre maximal de nouvelles tentatives d'API. Valeur par défaut `10`, plafonnée à `15`. Chaque nouvelle tentative dispose de sa propre fenêtre `API_TIMEOUT_MS`.585* `CLAUDE_CODE_MAX_RETRIES` : nombre maximal de nouvelles tentatives auprès de l'API. Valeur par défaut `10`, plafonnée à `15`. Chaque nouvelle tentative dispose de sa propre fenêtre `API_TIMEOUT_MS`.
586 586
587 Pour les exécutions sans surveillance qui doivent attendre la fin de pannes plus longues, définissez [`CLAUDE_CODE_RETRY_WATCHDOG=1`](https://code.claude.com/docs/fr/errors#tune-retry-behavior) : cette variable réessaie indéfiniment en cas d'erreurs de capacité transitoires et, sur Claude Code v2.1.199 ou ultérieur, porte la valeur par défaut à `300` pour les autres erreurs transitoires et supprime le plafond de cette variable.587 Pour les exécutions sans surveillance qui doivent patienter pendant des pannes plus longues, définissez [`CLAUDE_CODE_RETRY_WATCHDOG=1`](https://code.claude.com/docs/fr/errors#tune-retry-behavior) : cette option réessaie indéfiniment en cas d'erreurs de capacité transitoires et, sur Claude Code v2.1.199 ou ultérieur, porte la valeur par défaut pour les autres erreurs transitoires à `300` et supprime le plafond de cette variable.
588* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` : watchdog de blocage pour les sous-agents. Tant que le watchdog de flux est actif, la valeur par défaut est `CLAUDE_STREAM_IDLE_TIMEOUT_MS` plus 5 minutes, soit `600000` sauf si vous augmentez cette variable. Lorsque le watchdog de flux est désactivé, la valeur par défaut est `600000`. Avant v2.1.257, la valeur par défaut était toujours `600000`.588* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` : watchdog de blocage pour les sous-agents. Lorsque le watchdog de flux est activé, la valeur par défaut est `CLAUDE_STREAM_IDLE_TIMEOUT_MS` plus 5 minutes, soit `600000` à moins que vous n'augmentiez cette variable. Lorsque le watchdog de flux est désactivé, la valeur par défaut est `600000`. Avant la v2.1.257, la valeur par défaut était toujours `600000`.
589 589
590 Le minuteur est réinitialisé à chaque événement de flux. En cas de blocage, Claude Code interrompt le sous-agent et signale le blocage au parent. Pour un sous-agent en arrière-plan, il marque également la tâche comme échouée et joint tout résultat partiel.590 Le minuteur est réinitialisé à chaque événement de flux. En cas de blocage, Claude Code interrompt le sous-agent et signale le blocage au parent. Pour un sous-agent en arrière-plan, il marque également la tâche comme ayant échoué et y joint tout résultat partiel.
591* `CLAUDE_ENABLE_STREAM_WATCHDOG` avec `CLAUDE_STREAM_IDLE_TIMEOUT_MS` : watchdog de flux qui interrompt la requête lorsque les en-têtes sont arrivés mais que le corps de la réponse cesse d'être transmis. Le watchdog est activé par défaut pour tous les fournisseurs ; définissez `CLAUDE_ENABLE_STREAM_WATCHDOG=0` pour le désactiver. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` vaut `300000` par défaut et ne peut pas descendre en dessous de ce minimum. Après l'interruption, [Nouvelles tentatives automatiques](https://code.claude.com/docs/fr/errors.md#automatic-retries) décrit ce que fait Claude Code, selon l'avancement de la réponse.591* `CLAUDE_ENABLE_STREAM_WATCHDOG` avec `CLAUDE_STREAM_IDLE_TIMEOUT_MS` : watchdog de flux qui interrompt la requête lorsque les en-têtes sont arrivés mais que le corps de la réponse cesse d'être diffusé. Le watchdog est activé par défaut pour tous les fournisseurs ; définissez `CLAUDE_ENABLE_STREAM_WATCHDOG=0` pour le désactiver. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` vaut `300000` par défaut et ne peut pas descendre en dessous de ce minimum. Après l'interruption, [Nouvelles tentatives automatiques](https://code.claude.com/docs/fr/errors.md#automatic-retries) décrit ce que fait Claude Code, selon l'état d'avancement de la réponse.
592 592
593 Pendant que le watchdog attend une réponse qu'une passerelle derrière `ANTHROPIC_BASE_URL` maintient ouverte avec des pings keep-alive, un hôte qui définit `includePartialMessages` continue de recevoir des [événements de flux](#sdkpartialassistantmessage) `ping` ; interprétez donc ces trames comme des signes d'activité plutôt que de faire expirer la session en cas de silence. Avant v2.1.257, les trames s'arrêtaient 5 minutes après le dernier véritable événement de flux.593 Pendant que le watchdog attend une réponse qu'une passerelle située derrière `ANTHROPIC_BASE_URL` maintient ouverte avec des pings keep-alive, un hôte qui définit `includePartialMessages` continue de recevoir des [événements de flux](#sdkpartialassistantmessage) `ping` ; interprétez donc ces trames comme des signes d'activité plutôt que de faire expirer la session en cas de silence. Avant la v2.1.257, ces trames s'arrêtaient 5 minutes après le dernier véritable événement de flux.
594 594
595### Objet `Query`595### Objet `Query`
596 596
630 ): Promise<SDKControlReadFileResponse | null>;630 ): Promise<SDKControlReadFileResponse | null>;
631 reloadPlugins(options?: {631 reloadPlugins(options?: {
632 holdOnCacheImpact?: boolean;632 holdOnCacheImpact?: boolean;
633 addPlugins?: SdkPluginConfig[];
633 }): Promise<SDKControlReloadPluginsResponse>;634 }): Promise<SDKControlReloadPluginsResponse>;
634 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;635 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
635 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;636 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
654 655
655| Méthode | Description |656| Méthode | Description |
656| :- | :- |657| :- | :- |
657| `interrupt()` | Interrompt la requête. Disponible uniquement en mode d'entrée en streaming. Lorsque la CLI annonce la capacité `interrupt_receipt_v1` dans [`SDKSystemMessage.capabilities`](#sdksystemmessage), se résout avec un [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) listant les messages qui étaient en attente lorsque l'interruption est arrivée. Se résout avec `undefined` sur les CLI antérieures à v2.1.205 |658| `interrupt()` | Interrompt la requête. Disponible uniquement en mode d'entrée en streaming. Lorsque la CLI annonce la capacité `interrupt_receipt_v1` dans [`SDKSystemMessage.capabilities`](#sdksystemmessage), se résout avec un [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) listant les messages en attente au moment de l'interruption. Se résout en `undefined` sur les CLI antérieures à la v2.1.205 |
658| `rewindFiles(userMessageId, options?)` | Restaure les fichiers dans leur état au moment du message utilisateur spécifié. Passez `{ dryRun: true }` pour prévisualiser les modifications. Nécessite `enableFileCheckpointing: true`. Consultez [Checkpointing de fichiers](https://code.claude.com/docs/fr/agent-sdk/file-checkpointing.md) |659| `rewindFiles(userMessageId, options?)` | Restaure les fichiers dans leur état au moment du message utilisateur spécifié. Transmettez `{ dryRun: true }` pour prévisualiser les modifications. Nécessite `enableFileCheckpointing: true`. Consultez [Checkpointing de fichiers](https://code.claude.com/docs/fr/agent-sdk/file-checkpointing.md) |
659| `setPermissionMode()` | Modifie le mode de permission (disponible uniquement en mode d'entrée en streaming) |660| `setPermissionMode()` | Modifie le mode de permission (disponible uniquement en mode d'entrée en streaming) |
660| `setModel()` | Modifie le modèle (disponible uniquement en mode d'entrée en streaming). Passer `undefined` ou la chaîne `"default"` réinitialise vers le [modèle par défaut de Claude Code](https://code.claude.com/docs/fr/model-config.md). Une session en mode `auto` [passe en mode `default`](https://code.claude.com/docs/fr/agent-sdk/permissions#auto-mode-auto) si le nouveau modèle ne prend pas en charge le mode auto |661| `setModel()` | Modifie le modèle (disponible uniquement en mode d'entrée en streaming). Transmettre `undefined` ou la chaîne `"default"` rétablit le [modèle par défaut de Claude Code](https://code.claude.com/docs/fr/model-config.md). Une session en mode `auto` [passe en mode `default`](https://code.claude.com/docs/fr/agent-sdk/permissions#auto-mode-auto) si le nouveau modèle ne prend pas en charge le mode auto |
661| `setMaxThinkingTokens()` | *Obsolète :* Utilisez plutôt l'option `thinking`. Modifie le nombre maximal de tokens de réflexion. Passer `null` rétablit la réflexion à la valeur par défaut de la session : un remplacement en cours de session est effacé, et la réflexion reste désactivée pour les sessions où elle est désactivée |662| `setMaxThinkingTokens()` | *Obsolète :* utilisez plutôt l'option `thinking`. Modifie le nombre maximal de tokens de réflexion. Transmettre `null` rétablit la réflexion à la valeur par défaut de la session : un remplacement effectué en cours de session est effacé, et la réflexion reste désactivée pour les sessions où elle l'est |
662| `applyFlagSettings(settings)` | Fusionne des paramètres dans la couche de paramètres de flag de la session à l'exécution (disponible uniquement en mode d'entrée en streaming). Consultez [`applyFlagSettings()`](#applyflagsettings) |663| `applyFlagSettings(settings)` | Fusionne des paramètres dans la couche de paramètres de flag de la session à l'exécution (disponible uniquement en mode d'entrée en streaming). Consultez [`applyFlagSettings()`](#applyflagsettings) |
663| `updateSettings(source, settings)` | Écrit une clé autorisée dans le fichier de paramètres locaux du projet ou dans votre fichier de paramètres utilisateur, afin que la valeur persiste pour les sessions ultérieures. Consultez [`updateSettings()`](#updatesettings). Nécessite TypeScript SDK v0.3.257 ou ultérieure, qui inclut Claude Code v2.1.257 |664| `updateSettings(source, settings)` | Écrit une clé autorisée dans le fichier de paramètres locaux du projet ou dans votre fichier de paramètres utilisateur, afin que la valeur persiste pour les sessions ultérieures. Consultez [`updateSettings()`](#updatesettings). Nécessite le SDK TypeScript v0.3.257 ou ultérieur, qui intègre Claude Code v2.1.257 |
664| `initializationResult()` | Renvoie le résultat complet de l'initialisation, y compris les commandes prises en charge, les modèles, les informations de compte et la configuration du style de sortie |665| `initializationResult()` | Renvoie le résultat complet de l'initialisation, y compris les commandes prises en charge, les modèles, les informations de compte et la configuration du style de sortie |
665| `reinitialize()` | Renvoie la requête de contrôle `initialize` à la CLI en cours d'exécution et renvoie un nouveau résultat au lieu du résultat mis en cache lors de la première connexion. Utilisez-la après une interruption du transport, par exemple lors du rattachement à une session après une déconnexion, afin que les demandes de permission en attente parviennent de nouveau à votre callback `canUseTool`. Rendez le callback idempotent par ID de requête, car une requête dont la réponse a été perdue est de nouveau distribuée. Nécessite Claude Code v2.1.195 ou ultérieure |666| `reinitialize()` | Renvoie la requête de contrôle `initialize` à la CLI en cours d'exécution et renvoie un nouveau résultat au lieu du résultat mis en cache lors de la première connexion. Utilisez-la après une interruption du transport, par exemple lors du rattachement à une session après une déconnexion, afin que les demandes de permission en attente parviennent à nouveau à votre callback `canUseTool`. Rendez le callback idempotent par ID de requête, car une requête dont la réponse a été perdue est à nouveau distribuée. Nécessite Claude Code v2.1.195 ou ultérieur |
666| `supportedCommands()` | Renvoie les commandes disponibles. À partir d'Agent SDK v0.3.216, la liste reflète les modifications de commandes en cours de session ; consultez [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |667| `supportedCommands()` | Renvoie les commandes disponibles. À partir d'Agent SDK v0.3.216, la liste reflète les modifications de commandes survenues en cours de session ; consultez [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |
667| `supportedModels()` | Renvoie les modèles disponibles avec leurs informations d'affichage |668| `supportedModels()` | Renvoie les modèles disponibles avec leurs informations d'affichage |
668| `supportedAgents()` | Renvoie les sous-agents disponibles sous forme de [`AgentInfo`](#agentinfo)`[]` |669| `supportedAgents()` | Renvoie les sous-agents disponibles sous forme de [`AgentInfo`](#agentinfo)`[]` |
669| `mcpServerStatus()` | Renvoie l'état des serveurs MCP connectés sous forme de [`McpServerStatus`](#mcpserverstatus)`[]` |670| `mcpServerStatus()` | Renvoie l'état des serveurs MCP connectés sous forme de [`McpServerStatus`](#mcpserverstatus)`[]` |
670| `getContextUsage(opts?)` | Renvoie un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) détaillant l'utilisation de la fenêtre de contexte de la session par catégorie, skill et outil. Avec la valeur par défaut de `detail`, il inclut les données que `/context` affiche dans une session interactive, calculées à l'aide de requêtes API de comptage de tokens qui n'apparaissent pas dans le flux de messages ; consultez [comment ces requêtes sont gérées](#sdkcontrolgetcontextusageresponse). L'[option `detail`](#sdkcontrolgetcontextusageresponse) nécessite Agent SDK v0.3.257 ou ultérieur |671| `getContextUsage(opts?)` | Renvoie un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) détaillant l'utilisation de la fenêtre de contexte de la session par catégorie, skill et outil. Avec la valeur par défaut de `detail`, il inclut les données qu'affiche `/context` dans une session interactive, calculées au moyen de requêtes API de comptage de tokens qui n'apparaissent pas dans le flux de messages ; consultez [comment ces requêtes sont traitées](#sdkcontrolgetcontextusageresponse). L'[option `detail`](#sdkcontrolgetcontextusageresponse) nécessite Agent SDK v0.3.257 ou ultérieur |
671| `readFile(path, options?)` | Lit un fichier depuis le 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'elle sert. Passez `{ maxBytes }` pour modifier la limite de lecture (1 Mo par défaut, 10 Mo maximum) et `{ encoding: 'base64' }` pour les fichiers binaires tels que les images. Se résout avec un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` en cas de refus de permission, de fichier manquant ou d'erreur de transport. Nécessite TypeScript SDK v0.2.121 ou ultérieure |672| `readFile(path, options?)` | Lit un fichier depuis le 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 fournit. Transmettez `{ maxBytes }` pour modifier la limite de lecture (1 Mo par défaut, plafond de 10 Mo) et `{ encoding: 'base64' }` pour les fichiers binaires tels que les images. Se résout avec un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), ou `null` en cas de refus de permission, de fichier manquant ou d'erreur de transport. Nécessite le SDK TypeScript v0.2.121 ou ultérieur |
672| `reloadPlugins(options?)` | Recharge les plugins depuis le disque, afin que les plugins que vous installez ou modifiez en cours de session parviennent à la session en cours. Se résout avec un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listant les commandes, les sous-agents, les plugins et l'état des serveurs MCP de la session. Nécessite Agent SDK v0.2.85 ou ultérieure. L'[option `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) nécessite Agent SDK v0.3.268 ou ultérieure |673| `reloadPlugins(options?)` | Recharge les plugins depuis le disque, afin que les plugins que vous installez ou modifiez en cours de session parviennent à la session en cours d'exécution. Se résout avec un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listant les commandes, les sous-agents, les plugins et l'état des serveurs MCP de la session. Nécessite Agent SDK v0.2.85 ou ultérieur. L'[option `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) nécessite Agent SDK v0.3.268 ou ultérieur. L'[option `addPlugins`](#load-more-plugin-folders-with-addplugins) nécessite Agent SDK v0.3.301 ou ultérieur |
673| `reloadSkills()` | Recharge les skills depuis le disque, afin que les skills que vous ajoutez ou modifiez en cours de session deviennent disponibles pour la session en cours. Se résout avec un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listant les skills disponibles après le rechargement. Nécessite Agent SDK v0.3.163 ou ultérieure |674| `reloadSkills()` | Recharge les skills depuis le disque, afin que les skills que vous ajoutez ou modifiez en cours de session deviennent disponibles pour la session en cours d'exécution. Se résout avec un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listant les skills disponibles après le rechargement. Nécessite Agent SDK v0.3.163 ou ultérieur |
674| `reloadOutputStyles()` | Relit les [styles de sortie](https://code.claude.com/docs/fr/output-styles.md) depuis le disque, afin qu'un fichier de style que vous ajoutez ou modifiez en cours de session devienne disponible pour la session en cours. Se résout avec un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listant les noms de styles disponibles après le rechargement. Nécessite Agent SDK v0.3.261 ou ultérieure |675| `reloadOutputStyles()` | Relit les [styles de sortie](https://code.claude.com/docs/fr/output-styles.md) depuis le disque, afin qu'un fichier de style que vous ajoutez ou modifiez en cours de session devienne disponible pour la session en cours d'exécution. Se résout avec un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listant les noms de styles disponibles après le rechargement. Nécessite Agent SDK v0.3.261 ou ultérieur |
675| `seedReadState(path, mtime)` | Marque un fichier comme déjà lu afin qu'une modification ultérieure via Edit n'échoue pas avec `File has not been read yet`. Consultez [`seedReadState()`](#seedreadstate). Nécessite TypeScript SDK v0.2.83 ou ultérieur |676| `seedReadState(path, mtime)` | Marque un fichier comme déjà lu afin qu'un Edit ultérieur n'échoue pas avec `File has not been read yet`. Consultez [`seedReadState()`](#seedreadstate). Nécessite le SDK TypeScript v0.2.83 ou ultérieur |
676| `accountInfo()` | Renvoie les informations du compte |677| `accountInfo()` | Renvoie les informations du compte |
677| `reconnectMcpServer(serverName)` | Reconnecte un serveur MCP par son nom. Si le nom correspond également à une entrée d'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()`, et non l'entrée du fichier de paramètres. Cet ordre de résolution nécessite Claude Code v2.1.257 ou ultérieure |678| `reconnectMcpServer(serverName)` | Reconnecter un serveur MCP par son nom. Si le nom correspond également à une entrée d'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()`, et non l'entrée du fichier de paramètres. Cet ordre de résolution nécessite Claude Code v2.1.257 ou ultérieur |
678| `toggleMcpServer(serverName, enabled)` | Active ou désactive un serveur MCP par son nom, avec la même résolution de nom que `reconnectMcpServer()`. Désactiver un serveur le déconnecte et retire ses outils. Consultez [`toggleMcpServer()`](#togglemcpserver) pour connaître la version de Claude Code requise pour chaque type de serveur |679| `toggleMcpServer(serverName, enabled)` | Activer ou désactiver un serveur MCP par son nom, avec la même résolution de nom que `reconnectMcpServer()`. La désactivation d'un serveur le déconnecte et retire ses outils. Consultez [`toggleMcpServer()`](#togglemcpserver) pour connaître la version de Claude Code requise pour chaque type de serveur |
679| `setMcpServers(servers)` | Remplace les serveurs MCP gérés par cette méthode : les serveurs ajoutés par son intermédiaire et les [serveurs SDK in-process](#createsdkmcpserver). Se résout avec un [`McpSetServersResult`](#mcpsetserversresult) indiquant quels serveurs ont été ajoutés et retirés, ainsi que les éventuelles erreurs ; cette section indique quels autres serveurs restent connectés |680| `setMcpServers(servers)` | Remplacer les serveurs MCP gérés par cette méthode : les serveurs ajoutés par son intermédiaire et les [serveurs SDK in-process](#createsdkmcpserver). Se résout avec un [`McpSetServersResult`](#mcpsetserversresult) indiquant quels serveurs ont été ajoutés et supprimés, ainsi que les éventuelles erreurs ; cette section précise quels autres serveurs restent connectés |
680| `setMcpPermissionModeOverride(serverName, mode)` | Remplace le mode de permission des outils d'un serveur MCP par un mode plus strict que celui de la session, ou efface ce remplacement avec `null`. Disponible uniquement en mode d'entrée en streaming. Consultez [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride). Nécessite TypeScript SDK v0.3.187 ou ultérieur |681| `setMcpPermissionModeOverride(serverName, mode)` | Remplace le mode de permission des outils d'un serveur MCP par un mode plus strict que celui de la session, ou efface ce remplacement avec `null`. Disponible uniquement en mode d'entrée en streaming. Consultez [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride). Nécessite le SDK TypeScript v0.3.187 ou ultérieur |
681| `readMcpResource(serverName, uri)` | *Alpha.* Lit une ressource MCP Apps `ui://` depuis un serveur MCP connecté afin que votre application puisse afficher le widget d'un outil. Se résout avec un [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Nécessite TypeScript Agent SDK v0.3.280 ou ultérieure |682| `readMcpResource(serverName, uri)` | *Alpha.* Lit une ressource MCP Apps `ui://` depuis un serveur MCP connecté afin que votre application puisse afficher le widget d'un outil. Se résout avec un [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Nécessite TypeScript Agent SDK v0.3.280 ou ultérieur |
682| `streamInput(stream)` | Envoie des messages d'entrée en flux à la requête pour les conversations multi-tours |683| `streamInput(stream)` | Envoyer en flux des messages d'entrée à la requête pour des conversations à plusieurs tours |
683| `stopTask(taskId)` | Arrête une tâche en arrière-plan en cours d'exécution par son ID |684| `stopTask(taskId)` | Arrêter une tâche en arrière-plan en cours d'exécution par son ID |
684| `backgroundTasks(toolUseId?)` | Place en arrière-plan les commandes Bash et les sous-agents en cours d'exécution que le tour attend, comme lorsque vous appuyez sur Ctrl+B dans le terminal interactif. Consultez [`backgroundTasks()`](#backgroundtasks). Nécessite TypeScript SDK v0.2.139 ou ultérieur |685| `backgroundTasks(toolUseId?)` | Place en arrière-plan les commandes Bash et les sous-agents en cours d'exécution que le tour attend, comme lorsque vous appuyez sur Ctrl+B dans le terminal interactif. Consultez [`backgroundTasks()`](#backgroundtasks). Nécessite le SDK TypeScript v0.2.139 ou ultérieur |
685| `close()` | Ferme la requête et termine le processus sous-jacent. Met fin de force à la requête et libère toutes les ressources |686| `close()` | Fermer la requête et terminer le processus sous-jacent. Met fin de force à la requête et libère toutes les ressources |
686 687
687#### `setMcpPermissionModeOverride()`688#### `setMcpPermissionModeOverride()`
688 689
689Remplace le mode de permission des outils d'un serveur MCP par un mode plus strict que celui de la session, ou efface ce remplacement avec `null`. Utilisez-la lorsqu'une session s'exécute dans un mode qui ignore les demandes par action, mais que les outils d'un serveur doivent tout de même être examinés. Nécessite TypeScript SDK v0.3.187 ou ultérieur.690Remplace le mode de permission des outils d'un serveur MCP par un mode plus strict que celui de la session, ou efface ce remplacement avec `null`. Utilisez-la lorsqu'une session s'exécute dans un mode qui ignore les demandes par action, mais que les outils d'un serveur doivent tout de même être vérifiés. Nécessite le SDK TypeScript v0.3.187 ou ultérieur.
690 691
691Passez l'une de ces trois valeurs comme `mode` :692Transmettez l'une de ces trois valeurs comme `mode` :
692 693
693* `'default'` : Claude Code évalue les appels d'outils de ce serveur comme le fait le [mode manuel](https://code.claude.com/docs/fr/permission-modes.md#available-modes).694* `'default'` : Claude Code évalue les appels d'outils de ce serveur comme le fait le [mode manuel](https://code.claude.com/docs/fr/permission-modes.md#available-modes).
694* `'auto'` : Claude Code fait passer les appels d'outils de ce serveur par le classifieur du [mode auto](https://code.claude.com/docs/fr/permission-modes.md#eliminate-prompts-with-auto-mode). Claude Code rejette cette valeur lorsque le classifieur n'est pas disponible pour la session.695* `'auto'` : Claude Code fait passer les appels d'outils de ce serveur par le classifieur du [mode auto](https://code.claude.com/docs/fr/permission-modes.md#eliminate-prompts-with-auto-mode). Claude Code rejette cette valeur lorsque le classifieur n'est pas disponible pour la session.
695* `null` : efface le remplacement.696* `null` : efface le remplacement.
696 697
697Le remplacement ne prend effet que lorsque la session se trouve dans un mode qui ignore les demandes par action : `bypassPermissions` ou `auto`. Dans tout autre mode de session, Claude Code ignore le remplacement, de sorte qu'il ne peut jamais élargir ce que la session autorise.698Le remplacement ne prend effet que lorsque la session se trouve dans un mode qui ignore les demandes par action : `bypassPermissions` ou `auto`. Dans tout autre mode de session, Claude Code ignore le remplacement, qui ne peut donc jamais élargir ce que la session autorise.
698 699
699La promesse se résout avec `{ warning }` lorsqu'aucun serveur portant ce nom n'est encore connu. Claude Code enregistre tout de même le remplacement et l'applique dès qu'un serveur portant exactement ce nom se connecte ; l'avertissement sert donc à détecter une faute de frappe, et non à signaler un échec.700La promesse se résout avec `{ warning }` lorsqu'aucun serveur portant ce nom n'est encore connu. Claude Code enregistre tout de même le remplacement et l'applique dès qu'un serveur portant exactement ce nom se connecte ; l'avertissement sert donc à détecter les fautes de frappe, il ne signale pas un échec.
700 701
701Disponible uniquement en mode d'entrée en streaming, avec la même contrainte que `setModel()` et `setPermissionMode()`.702Disponible uniquement en mode d'entrée en streaming, avec la même contrainte que `setModel()` et `setPermissionMode()`.
702 703
703#### `seedReadState()`704#### `seedReadState()`
704 705
705Marque un fichier comme déjà lu afin qu'une modification ultérieure via Edit n'échoue pas avec `File has not been read yet`. Utilisez-la lorsque votre application a retiré du contexte de la conversation un résultat `Read` antérieur et que Claude va ensuite modifier ce fichier. Nécessite TypeScript SDK v0.2.83 ou ultérieur.706Marque un fichier comme déjà lu afin qu'un Edit ultérieur n'échoue pas avec `File has not been read yet`. Utilisez-la lorsque votre application a retiré un résultat `Read` antérieur du contexte de la conversation et que Claude va ensuite modifier ce fichier. Nécessite le SDK TypeScript v0.2.83 ou ultérieur.
706 707
707Passez `mtime` comme l'heure de modification du fichier au moment de cette lecture antérieure, en millisecondes entières depuis l'epoch, par exemple `Math.floor(stat.mtimeMs)`. Si le fichier sur le disque a été modifié après cette date, Claude Code n'applique pas le marquage.708Transmettez `mtime` comme date de modification du fichier au moment de cette lecture antérieure, en millisecondes entières depuis l'epoch, par exemple `Math.floor(stat.mtimeMs)`. Si le fichier sur le disque a été modifié après cette date, Claude Code ne le marque pas.
708 709
709La promesse se résout que le fichier ait été marqué ou non ; une promesse résolue ne vous indique donc pas ce qui s'est passé.710La promesse se résout que le fichier ait été marqué ou non ; une promesse résolue ne vous indique donc pas ce qui s'est produit.
710 711
711#### `backgroundTasks()`712#### `backgroundTasks()`
712 713
713Place en arrière-plan les commandes Bash et les sous-agents en cours d'exécution que le tour attend, comme lorsque vous appuyez sur Ctrl+B dans le terminal interactif. Passez le `toolUseId` d'un appel d'outil pour ne placer en arrière-plan que la commande Bash ou le sous-agent lancé par cet appel, ou omettez-le pour placer en arrière-plan toutes les tâches au premier plan. Nécessite TypeScript SDK v0.2.139 ou ultérieur.714Place en arrière-plan les commandes Bash et les sous-agents en cours d'exécution que le tour attend, comme lorsque vous appuyez sur Ctrl+B dans le terminal interactif. Transmettez le `toolUseId` d'un appel d'outil pour ne placer en arrière-plan que la commande Bash ou le sous-agent lancé par cet appel, ou omettez-le pour placer en arrière-plan toutes les tâches au premier plan. Nécessite le SDK TypeScript v0.2.139 ou ultérieur.
714 715
715Chaque appel d'outil placé en arrière-plan revient immédiatement à Claude avec un résultat indiquant qu'il s'exécute en arrière-plan, le tour se poursuit, et Claude Code émet un [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) lorsque la tâche se termine.716Chaque appel d'outil placé en arrière-plan revient immédiatement à Claude avec un résultat indiquant qu'il s'exécute en arrière-plan, le tour se poursuit, et Claude Code émet un [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) lorsque la tâche se termine.
716 717
717Dans une session où les tâches en arrière-plan sont activées, la promesse se résout en un booléen :718Dans une session où les tâches en arrière-plan sont activées, la promesse se résout en un booléen :
718 719
719* **`true`** : une tâche a été placée en arrière-plan, ou vous avez omis `toolUseId`.720* **`true`** : une tâche a été placée en arrière-plan, ou vous avez omis `toolUseId`.
720* **`false`** : le `toolUseId` que vous avez passé ne correspond à aucune tâche au premier plan.721* **`false`** : le `toolUseId` que vous avez transmis ne correspond à aucune tâche au premier plan.
721 722
722Si les tâches en arrière-plan sont désactivées pour la session, par exemple avec [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/fr/env-vars), la promesse est rejetée et rien n'est placé en arrière-plan.723Si les tâches en arrière-plan sont désactivées pour la session, par exemple avec [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/fr/env-vars), la promesse est rejetée et rien n'est placé en arrière-plan.
723 724
724#### `applyFlagSettings()`725#### `applyFlagSettings()`
725 726
726Modifie les [paramètres](https://code.claude.com/docs/fr/settings.md) d'une session en cours sans redémarrer la requête. Utilisez-la lorsqu'un paramètre dépourvu de setter dédié doit changer en cours de session, par exemple pour resserrer `permissions` après que l'agent a lu une entrée non fiable. `setModel()` et `setPermissionMode()` sont des setters dédiés pour ces deux clés ; `applyFlagSettings()` est la forme générale qui accepte n'importe quel sous-ensemble des clés de paramètres, et passer `model` ici se comporte de la même manière que `setModel()`.727Modifie les [paramètres](https://code.claude.com/docs/fr/settings.md) d'une session en cours d'exécution sans redémarrer la requête. Utilisez-la lorsqu'un paramètre dépourvu de setter dédié doit changer en cours de session, par exemple pour restreindre `permissions` après que l'agent a lu une entrée non fiable. `setModel()` et `setPermissionMode()` sont des setters dédiés à ces deux clés ; `applyFlagSettings()` est la forme générale qui accepte n'importe quel sous-ensemble des clés de paramètres, et transmettre `model` ici se comporte comme `setModel()`.
727 728
728Seules certaines clés prennent effet en cours de session :729Seules certaines clés prennent effet en cours de session :
729 730
730* **Appliquées au tour suivant** : `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Changer d'`agent` applique également le remplacement de modèle et les hooks de cet agent au tour suivant. Son prompt système s'applique au tour suivant ou, dans une session qui [réutilise un prompt système enregistré](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session), une fois la session compactée.731* **Appliquées au tour suivant** : `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Changer `agent` applique également le remplacement de modèle et les hooks de cet agent au tour suivant. Son prompt système s'applique au tour suivant ou, dans une session qui [réutilise un prompt système enregistré](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session), une fois la session compactée.
731* **Appliquée pendant le tour en cours** : `model`. Si vous changez de `model` pendant que Claude travaille sur un tour, la réponse que Claude est déjà en train de générer se termine avec l'ancien modèle, et le reste du tour, à partir du prochain appel que Claude Code adresse au modèle, utilise le nouveau. Les sous-agents conservent leur propre modèle. Avant v2.1.212, un changement en cours de tour attendait le tour suivant.732* **Appliquées pendant le tour en cours** : `model`. Si vous changez `model` pendant que Claude travaille sur un tour, la réponse que Claude est déjà en train de générer se termine avec l'ancien modèle, et le reste du tour, à commencer par le prochain appel de Claude Code au modèle, utilise le nouveau. Les sous-agents conservent leur propre modèle. Avant la v2.1.212, un changement en cours de tour attendait le tour suivant.
732* **Sans effet en cours de session** : les options du prompt système. Elles sont résolues une seule fois au démarrage, de sorte que la session en cours conserve la valeur d'origine même si l'appel réussit. Pour les modifier, démarrez une nouvelle session.733* **Sans effet en cours de session** : les options du prompt système. Elles sont résolues une seule fois au démarrage, de sorte que la session en cours conserve la valeur d'origine même si l'appel réussit. Pour les modifier, démarrez une nouvelle session.
733 734
734`effortLevel` accepte un nom de [niveau d'effort](https://code.claude.com/docs/fr/model-config.md#adjust-effort-level). Il accepte également `"ultracode"`, qui demande un effort `xhigh` avec [ultracode](https://code.claude.com/docs/fr/workflows.md#let-claude-decide-with-ultracode) activé. `applyFlagSettings()` déclare `effortLevel` sans cette valeur ; en TypeScript, passez donc `{ ultracode: true, effortLevel: "xhigh" }` pour obtenir le même résultat, ou la clé [`ultracode`](https://code.claude.com/docs/fr/settings-reference#ultracode) seule pour activer ultracode au niveau d'effort actuel de la session. La valeur `ultracode` nécessite Claude Code v2.1.203 ou ultérieure et n'est acceptée que par `applyFlagSettings()`, et non par la clé `effortLevel` d'un fichier de paramètres. Avant v2.1.284, la clé `ultracode` seule définissait également le niveau sur `xhigh`.735`effortLevel` accepte un nom de [niveau d'effort](https://code.claude.com/docs/fr/model-config.md#adjust-effort-level). Il accepte également `"ultracode"`, qui demande un effort `xhigh` avec [ultracode](https://code.claude.com/docs/fr/workflows.md#let-claude-decide-with-ultracode) activé. `applyFlagSettings()` déclare `effortLevel` sans cette valeur ; en TypeScript, transmettez donc `{ ultracode: true, effortLevel: "xhigh" }` pour obtenir le même résultat, ou la clé [`ultracode`](https://code.claude.com/docs/fr/settings-reference#ultracode) seule pour activer ultracode au niveau d'effort actuel de la session. La valeur `ultracode` nécessite Claude Code v2.1.203 ou ultérieur et n'est acceptée que par `applyFlagSettings()`, et non par la clé `effortLevel` d'un fichier de paramètres. Avant la v2.1.284, la clé `ultracode` seule définissait également le niveau sur `xhigh`.
735 736
736Les valeurs sont écrites dans la couche de paramètres de flag, fusionnées par-dessus ce que l'option inline `settings` de `query()` a défini au démarrage. Il s'agit du même niveau que celui que la [section sur la priorité de cette page](#settings-precedence) appelle options programmatiques.737Les valeurs sont écrites dans la couche de paramètres de flag, fusionnées par-dessus ce que l'option inline `settings` de `query()` a défini au démarrage. Il s'agit du même niveau que celui que la [section sur la priorité de cette page](#settings-precedence) appelle options programmatiques.
737 738
738Les appels successifs fusionnent superficiellement les clés de premier niveau. Un second appel avec `{ permissions: {...} }` remplace l'intégralité de l'objet `permissions` de l'appel précédent au lieu de le fusionner en profondeur.739Les appels successifs fusionnent superficiellement les clés de premier niveau. Un second appel avec `{ permissions: {...} }` remplace l'intégralité de l'objet `permissions` de l'appel précédent au lieu d'y être fusionné en profondeur.
739 740
740Pour effacer une clé définie avec `applyFlagSettings()`, passez `null` pour cette clé. La plupart des clés se rabattent alors d'abord sur une valeur définie au démarrage par l'option `settings` de `query()`, puis sur des sources de priorité inférieure. Un `model` effacé revient au [modèle par défaut de Claude Code](https://code.claude.com/docs/fr/model-config.md), même lorsqu'un fichier de paramètres définit `model`. Passer `undefined` n'a aucun effet, car la sérialisation JSON le supprime.741Pour effacer une clé que vous avez définie avec `applyFlagSettings()`, transmettez `null` pour cette clé. La plupart des clés se rabattent alors d'abord sur une valeur que l'option `settings` de `query()` a définie au démarrage, puis sur des sources de priorité inférieure. Un `model` effacé revient au [modèle par défaut de Claude Code](https://code.claude.com/docs/fr/model-config.md), même lorsqu'un fichier de paramètres définit `model`. Transmettre `undefined` n'a aucun effet, car la sérialisation JSON le supprime.
741 742
742Trois clés en plus de `model` réinitialisent l'état de la session au lieu de se rabattre sur une autre valeur :743Trois clés autres que `model` réinitialisent l'état de la session au lieu de se rabattre sur une autre valeur :
743 744
744* `effortLevel: null` ramène la session au niveau d'effort par défaut du modèle, et non à l'option `effort` de `query()` ni à un `effortLevel` provenant d'un fichier de paramètres.745* `effortLevel: null` rétablit le niveau d'effort par défaut du modèle pour la session, et non l'option `effort` de `query()` ni un `effortLevel` provenant d'un fichier de paramètres.
745* `agent: null` exécute le thread principal sans agent à partir du tour suivant, au lieu de restaurer l'option `agent` de `query()` ou un `agent` provenant d'un fichier de paramètres. Si l'agent effacé avait appliqué son propre modèle, la session revient au modèle résolu au démarrage.746* `agent: null` exécute le thread principal sans agent à partir du tour suivant, au lieu de restaurer l'option `agent` de `query()` ou un `agent` provenant d'un fichier de paramètres. Si l'agent effacé avait appliqué son propre modèle, la session revient au modèle qu'elle avait résolu au démarrage.
746* `ultracode: null` désactive ultracode, comme `false`, au lieu de restaurer une valeur `ultracode` provenant d'un fichier de paramètres. La session conserve son niveau d'effort actuel ; passez donc `effortLevel` dans le même appel pour le modifier.747* `ultracode: null` désactive ultracode, comme le fait `false`, au lieu de restaurer une valeur `ultracode` provenant d'un fichier de paramètres. La session conserve son niveau d'effort actuel ; transmettez donc `effortLevel` dans le même appel pour le modifier.
747 748
748Disponible uniquement en mode d'entrée en streaming, la même contrainte que pour `setModel()` et `setPermissionMode()`.749Disponible uniquement en mode d'entrée en streaming, avec la même contrainte que `setModel()` et `setPermissionMode()`.
749 750
750L'exemple ci-dessous change le modèle actif en cours de session, puis efface le remplacement afin que le modèle revienne au [modèle par défaut de Claude Code](https://code.claude.com/docs/fr/model-config.md).751L'exemple ci-dessous change le modèle actif en cours de session, puis efface le remplacement afin que le modèle revienne au [modèle par défaut de Claude Code](https://code.claude.com/docs/fr/model-config.md).
751 752
763 764
764> [!NOTE]765> [!NOTE]
765>766>
766> `applyFlagSettings()` est disponible uniquement en TypeScript. Le SDK Python n'expose pas de méthode équivalente.767> `applyFlagSettings()` est propre à TypeScript. Le SDK Python n'expose pas de méthode équivalente.
767 768
768#### `updateSettings()`769#### `updateSettings()`
769 770
770Écrit une clé autorisée dans un fichier de paramètres sur disque, afin que la valeur persiste pour les sessions ultérieures qui chargent cette source. Chaque source accepte une clé, avec une valeur de type chaîne :771Écrit une clé autorisée dans un fichier de paramètres sur le disque, afin que la valeur persiste pour les sessions ultérieures qui chargent cette source. Chaque source accepte une seule clé, avec une valeur de type chaîne :
771 772
772* **`"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 prochaine requête de la session.773* **`"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 prochaine requête de la session.
773* **`"userSettings"`** : accepte `effortLevel` et l'enregistre comme [niveau d'effort](https://code.claude.com/docs/fr/model-config.md#adjust-effort-level) par défaut pour le modèle actuel de la session, sous [`modelSettings`](https://code.claude.com/docs/fr/settings-reference#modelsettings) dans votre fichier de paramètres utilisateur. Passer `max` n'écrit rien, car `max` est limité à la session. La session en cours conserve son niveau d'effort actuel dans tous les cas ; appelez donc [`applyFlagSettings()`](#applyflagsettings) si vous souhaitez également le modifier. Cette source nécessite TypeScript SDK v0.3.277 ou ultérieure, qui inclut Claude Code v2.1.277.774* **`"userSettings"`** : accepte `effortLevel` et l'enregistre comme [niveau d'effort](https://code.claude.com/docs/fr/model-config.md#adjust-effort-level) par défaut pour le modèle actuel de la session, sous [`modelSettings`](https://code.claude.com/docs/fr/settings-reference#modelsettings) dans votre fichier de paramètres utilisateur. Transmettre `max` n'écrit rien, car `max` est limité à la session. Dans tous les cas, la session en cours conserve son niveau d'effort actuel ; appelez donc [`applyFlagSettings()`](#applyflagsettings) si vous souhaitez également le modifier. Cette source nécessite le SDK TypeScript v0.3.277 ou ultérieur, qui intègre Claude Code v2.1.277.
774 775
775L'appel est rejeté lorsque la requête contient toute autre clé, lorsque la session s'exécute via un transport distant, et lorsque les [`settingSources`](#options) de la session excluent la source que vous indiquez. La suppression d'une clé n'est pas prise en charge.776L'appel est rejeté lorsque la requête contient une autre clé, lorsque la session s'exécute via un transport distant et lorsque les [`settingSources`](#options) de la session excluent la source que vous indiquez. La suppression d'une clé n'est pas prise en charge.
776 777
777#### `toggleMcpServer()`778#### `toggleMcpServer()`
778 779
779Désactiver un serveur le déconnecte et retire ses outils de la session. Pour les serveurs que vous avez ajoutés en cours de session et pour les serveurs in-process, cela dépend de votre version de Claude Code :780La désactivation d'un serveur le déconnecte et retire ses outils de la session. Pour les serveurs que vous avez ajoutés en cours de session et pour les serveurs in-process, cela dépend de votre version de Claude Code :
780 781
781* Un serveur stdio, SSE ou HTTP que vous avez ajouté en cours de session avec `setMcpServers()` : le retrait de ses outils nécessite Claude Code v2.1.285 ou ultérieure.782* Un serveur stdio, SSE ou HTTP que vous avez ajouté en cours de session avec `setMcpServers()` : le retrait de ses outils nécessite Claude Code v2.1.285 ou ultérieur.
782* Un serveur in-process que vous avez créé avec [`createSdkMcpServer()`](#createsdkmcpserver), que vous l'ayez passé dans `mcpServers` ou avec `setMcpServers()` : sa déconnexion et le retrait de ses outils nécessitent Claude Code v2.1.286 ou ultérieure. La désactivation d'un tel serveur fait également échouer ses appels d'outils encore en cours, de sorte que Claude reçoit immédiatement un résultat d'erreur pour chacun d'eux, sans attendre le retour de votre handler.783* Un serveur in-process que vous avez créé avec [`createSdkMcpServer()`](#createsdkmcpserver), que vous l'ayez transmis dans `mcpServers` ou avec `setMcpServers()` : sa déconnexion et le retrait de ses outils nécessitent Claude Code v2.1.286 ou ultérieur. La désactivation d'un tel serveur fait également échouer ses appels d'outils encore en cours d'exécution, de sorte que Claude reçoit immédiatement un résultat d'erreur pour chacun d'eux, sans attendre le retour de votre gestionnaire.
783 784
784### `WarmQuery`785### `WarmQuery`
785 786
786Handle renvoyé par [`startup()`](#startup). Le sous-processus est déjà lancé et initialisé, de sorte qu'appeler `query()` sur ce handle écrit le prompt directement dans un processus prêt, sans latence de démarrage.787Handle renvoyé par [`startup()`](#startup). Le sous-processus est déjà lancé et initialisé ; appeler `query()` sur ce handle écrit donc le prompt directement dans un processus prêt, sans latence de démarrage.
787 788
788```typescript theme={null}789```typescript theme={null}
789interface WarmQuery extends AsyncDisposable {790interface WarmQuery extends AsyncDisposable {
796 797
797| Méthode | Description |798| Méthode | Description |
798| :- | :- |799| :- | :- |
799| `query(prompt)` | Envoie un prompt au sous-processus préchauffé et renvoie un [`Query`](#query-object). Ne peut être appelée qu'une seule fois par `WarmQuery` |800| `query(prompt)` | Envoyer un prompt au sous-processus préchauffé et renvoyer un [`Query`](#query-object). Ne peut être appelée qu'une seule fois par `WarmQuery` |
800| `close()` | Ferme le sous-processus sans envoyer de prompt. Utilisez-la pour abandonner une requête préchauffée dont vous n'avez plus besoin |801| `close()` | Fermer le sous-processus sans envoyer de prompt. Utilisez-la pour abandonner une requête préchauffée qui n'est plus nécessaire |
801 802
802`WarmQuery` implémente `AsyncDisposable`, il peut donc être utilisé avec `await using` pour un nettoyage automatique.803`WarmQuery` implémente `AsyncDisposable` ; il peut donc être utilisé avec `await using` pour un nettoyage automatique.
803 804
804### `SpareProcess`805### `SpareProcess`
805 806
806*Alpha.* Handle renvoyé par [`prewarm()`](#prewarm) : un processus Claude Code démarré qui n'est pas encore lié à une session et qui peut être réclamé une seule fois. Nécessite TypeScript Agent SDK v0.3.282 ou ultérieure.807*Alpha.* Handle renvoyé par [`prewarm()`](#prewarm) : un processus Claude Code démarré qui n'est pas encore lié à une session et peut être réclamé une seule fois. Nécessite TypeScript Agent SDK v0.3.282 ou ultérieur.
807 808
808```typescript theme={null}809```typescript theme={null}
809interface SpareProcess extends AsyncDisposable {810interface SpareProcess extends AsyncDisposable {
821 822
822| Membre | Description |823| Membre | Description |
823| :- | :- |824| :- | :- |
824| `claim({ prompt, options })` | Lie le processus de réserve à une session dans `options.cwd` et envoie son premier message. Renvoie un [`Query`](#query-object) de manière synchrone, comme le fait `query()`. Ne peut être appelée qu'une seule fois |825| `claim({ prompt, options })` | Lier le processus de réserve à une session dans `options.cwd` et envoyer son premier message. Renvoie un [`Query`](#query-object) de manière synchrone, comme le fait `query()`. Ne peut être appelée qu'une seule fois |
825| `claimed` | Se résout avec le répertoire de travail et l'ID de la session une fois que Claude Code accepte la réclamation. Est rejetée lorsque Claude Code refuse la réclamation, lorsque le processus s'est terminé ou a été fermé auparavant, et, avec un message commençant par `option_not_applied`, lorsque la session s'exécute sans le `model` ou le `maxThinkingTokens` que vous avez demandé |826| `claimed` | Se résout avec le répertoire de travail et l'ID de la session une fois que Claude Code accepte la réclamation. Est rejetée lorsque Claude Code refuse la réclamation, lorsque le processus s'est terminé ou a été fermé auparavant et, avec un message commençant par `option_not_applied`, lorsque la session s'exécute sans le `model` ou le `maxThinkingTokens` que vous avez demandé |
826| `exited` | Se règle lorsque le processus se termine, qu'il ait été réclamé ou non. Remplacez un processus de réserve qui se termine avant que vous ne le réclamiez |827| `exited` | Se résout lorsque le processus se termine, qu'il ait été réclamé ou non. Remplacez un processus de réserve qui se termine avant que vous ne le réclamiez |
827| `close()` | Termine le processus. Avant une réclamation, cela abandonne le processus de réserve et rejette `claimed` |828| `close()` | Terminer le processus. Avant une réclamation, cela abandonne le processus de réserve et rejette `claimed` |
828 829
829`options.cwd` est requis. Une réclamation peut également définir `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, une surcouche de paramètres de flag dans `settings`, `appendSystemPrompt`, `title`, `agents` et des jetons propres à la session dans `env`.830`options.cwd` est obligatoire. Une réclamation peut également définir `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, une surcouche de paramètres de flag dans `settings`, `appendSystemPrompt`, `title`, `agents` et des jetons propres à la session dans `env`.
830 831
831Claude Code peut refuser une réclamation, par exemple pour un dossier qui n'existe pas ou dont les paramètres de projet définissent `env`, `agent` ou `model`. Après un refus, un prompt que `claim()` a déjà envoyé reçoit un résultat d'erreur dont le texte commence par `not_claimed`, puis la requête renvoyée lève une exception. Encapsulez la boucle de la requête dans un bloc try pour continuer au-delà de l'exception. Lorsque `claimed` est rejetée avec un message commençant par `option_not_applied`, la session s'exécute sans le `model` ou le `maxThinkingTokens` que vous avez demandé. Après tout autre rejet, votre prompt n'a pas été exécuté ; démarrez donc plutôt la session avec `query()`.832Claude Code peut refuser une réclamation, par exemple pour un dossier qui n'existe pas ou dont les paramètres de projet définissent `env`, `agent` ou `model`. Après un refus, un prompt que `claim()` a déjà envoyé reçoit un résultat d'erreur dont le texte commence par `not_claimed`, puis la requête renvoyée lève une exception. Encadrez la boucle de la requête dans un bloc try pour continuer au-delà de cette exception. Lorsque `claimed` est rejetée avec un message commençant par `option_not_applied`, la session s'exécute sans le `model` ou le `maxThinkingTokens` que vous avez demandé. Après tout autre rejet, votre prompt n'a pas été exécuté ; démarrez donc plutôt la session avec `query()`.
832 833
833### `SDKControlInitializeResponse`834### `SDKControlInitializeResponse`
834 835
857};858};
858```859```
859 860
860`hooks_applied` indique si Claude Code a enregistré les `hooks` que contenait la requête `initialize`. Le SDK envoie cette requête une fois au démarrage de la session, puis à chaque appel à [`reinitialize()`](#query-object). Le champ nécessite Agent SDK v0.3.238 ou ultérieure.861`hooks_applied` indique si Claude Code a enregistré les `hooks` contenus dans la requête `initialize`. Le SDK envoie cette requête une première fois au démarrage de la session, puis à chaque appel à [`reinitialize()`](#query-object). Ce champ nécessite Agent SDK v0.3.238 ou ultérieur.
861 862
862Claude Code omet le champ lorsque la requête ne contenait aucun hook. Lorsque la requête contenait des hooks, la valeur dépend du fait que la requête soit ou non le premier initialize de la session et, pour un initialize répété, de la manière dont elle a atteint la session :863Claude Code omet ce champ lorsque la requête ne contenait aucun hook. Lorsque la requête contenait des hooks, la valeur dépend du fait qu'il s'agisse ou non de la première initialisation de la session et, pour une initialisation répétée, de la manière dont elle a atteint la session :
863 864
864* `true` : Claude Code a enregistré les hooks. Le premier initialize d'une session renvoie cette valeur. Un initialize répété envoyé via le stdin de la CLI renvoie également `true`. Dans ce cas, les hooks de la nouvelle requête remplacent ceux enregistrés précédemment.865* `true` : Claude Code a enregistré les hooks. La première initialisation d'une session renvoie cette valeur. Une initialisation répétée envoyée via l'entrée standard de la CLI renvoie également `true`. Dans ce cas, les hooks de la nouvelle requête remplacent ceux enregistrés précédemment.
865* `false` : Claude Code a ignoré les hooks. Un initialize répété envoyé à une session distante renvoie cette valeur, de sorte qu'un second client qui rejoint une session ne peut pas remplacer les hooks enregistrés par le premier client.866* `false` : Claude Code a ignoré les hooks. Une initialisation répétée envoyée à une session distante renvoie cette valeur, de sorte qu'un second client qui rejoint une session ne peut pas remplacer les hooks enregistrés par le premier client.
866 867
867Avant Agent SDK v0.3.238, la réponse ne contenait jamais ce champ, et Claude Code ignorait `hooks` à chaque initialize répété.868Avant Agent SDK v0.3.238, la réponse ne contenait jamais ce champ, et Claude Code ignorait `hooks` à chaque initialisation répétée.
868 869
869Le champ `sdkMcpServerManifests` de la requête et le champ `sdk_mcp_manifests_parked` de la réponse concernent les [serveurs MCP SDK](https://code.claude.com/docs/fr/agent-sdk/custom-tools.md) in-process que vous avez créés avec [`createSdkMcpServer()`](#createsdkmcpserver). Votre application ne définit ni ne lit aucun de ces champs.870Le champ `sdkMcpServerManifests` de la requête et le champ `sdk_mcp_manifests_parked` de la réponse concernent les [serveurs MCP SDK](https://code.claude.com/docs/fr/agent-sdk/custom-tools.md) in-process que vous avez créés avec [`createSdkMcpServer()`](#createsdkmcpserver). Votre application ne définit ni ne lit aucun de ces deux champs.
870 871
871`claude_code_version` est la version de Claude Code du processus qui exécute les tours de la session. Il s'agit de la même valeur que celle du message init [`SDKSystemMessage`](#sdksystemmessage), ce qui vous permet de lire la version de la CLI avant le premier tour.872`claude_code_version` est la version de Claude Code du processus qui exécute les tours de la session. Il s'agit de la même valeur que celle contenue dans le message d'initialisation [`SDKSystemMessage`](#sdksystemmessage) ; vous pouvez donc lire la version de la CLI avant le premier tour.
872 873
873* Ce champ nécessite Agent SDK v0.3.296 ou ultérieur, qui inclut Claude Code v2.1.296.874* Ce champ nécessite Agent SDK v0.3.296 ou ultérieur, qui intègre Claude Code v2.1.296.
874* Si le champ vaut `undefined` et que vous définissez `pathToClaudeCodeExecutable`, faites-le pointer vers Claude Code v2.1.296 ou ultérieur.875* Si le champ vaut `undefined` et que vous définissez `pathToClaudeCodeExecutable`, faites-le pointer vers Claude Code v2.1.296 ou ultérieur.
875 876
876La réponse indique toujours `fast_mode_state`, et lorsqu'un élément bloque le [mode rapide](https://code.claude.com/docs/fr/fast-mode.md), `fast_mode_disabled_reason` fournit le code de raison en complément, afin que vous puissiez expliquer l'état bloqué au lieu de redéduire la disponibilité. Ces deux comportements nécessitent Claude Code v2.1.219 ou ultérieure. Avant v2.1.219, la réponse omettait `fast_mode_state` lorsque le mode rapide n'était pas disponible et ne fournissait jamais de raison. Pour les codes de raison et leur signification, consultez [`fast_mode_disabled_reason`](#sdkresultmessage) dans le message de résultat.877La réponse indique toujours `fast_mode_state`, et lorsque quelque chose bloque le [mode rapide](https://code.claude.com/docs/fr/fast-mode.md), `fast_mode_disabled_reason` contient le code de raison à côté, ce qui vous permet d'expliquer l'état bloqué au lieu de redéterminer la disponibilité. Ces deux comportements nécessitent Claude Code v2.1.219 ou ultérieur. Avant la v2.1.219, la réponse omettait `fast_mode_state` lorsque le mode rapide n'était pas disponible et ne contenait jamais de raison. Pour les codes de raison et leur signification, consultez [`fast_mode_disabled_reason`](#sdkresultmessage) dans le message de résultat.
877 878
878Le wrapper de réponse de contrôle d'un `initialize` réussi contient également un tableau `pending_permission_requests`. Le champ se trouve sur le wrapper de réponse lui-même, et non dans le payload `SDKControlInitializeResponse` ci-dessus. Chaque entrée est un message `control_request` complet, avec la même forme `{ type: "control_request", request_id, request }` que celle des demandes de permission que la session diffuse en flux pendant son exécution.879L'enveloppe de réponse de contrôle d'un `initialize` réussi contient également un tableau `pending_permission_requests`. Ce champ se trouve dans l'enveloppe de réponse elle-même, et non dans le payload `SDKControlInitializeResponse` ci-dessus. Chaque entrée est un message `control_request` complet, de même forme `{ type: "control_request", request_id, request }` que ceux que la session diffuse pour les demandes de permission pendant son exécution.
879 880
880Le tableau liste les demandes de permission que ce processus Claude Code a émises et qui ne sont pas encore résolues. Le SDK lit le tableau pour vous et distribue chaque entrée à votre callback [`canUseTool`](#canusetool), la même redistribution que celle déclenchée par [`reinitialize()`](#query-object) après une interruption du transport. Traitez les ID de requête répétés de manière idempotente, car une entrée peut répéter une requête que le callback a déjà reçue avant la perte de connexion.881Le tableau liste les demandes de permission que ce processus Claude Code a émises et qui ne sont pas encore résolues. Le SDK lit le tableau pour vous et distribue chaque entrée à votre callback [`canUseTool`](#canusetool), la même redistribution que celle déclenchée par [`reinitialize()`](#query-object) après une interruption du transport. Traitez les ID de requête répétés de manière idempotente, car une entrée peut répéter une demande que le callback a déjà reçue avant la coupure de la connexion.
881 882
882Le tableau est toujours présent dans une réponse `initialize` réussie et il est vide lorsque ce processus n'a aucune demande de permission non résolue. Nécessite Claude Code v2.1.268 ou ultérieure. Les versions antérieures pouvaient omettre le champ ; si vous analysez vous-même le protocole filaire, considérez donc un champ manquant comme le signe d'une CLI plus ancienne plutôt que comme la preuve que rien n'est en attente.883Le tableau est toujours présent dans une réponse `initialize` réussie et il est vide lorsque ce processus n'a aucune demande de permission non résolue. Nécessite Claude Code v2.1.268 ou ultérieur. Les versions antérieures pouvaient omettre ce champ ; si vous analysez vous-même le protocole filaire, considérez donc l'absence du champ comme le signe d'une CLI plus ancienne plutôt que comme la preuve que rien n'est en attente.
883 884
884### `SDKControlInterruptResponse`885### `SDKControlInterruptResponse`
885 886
886Le reçu d'interruption : la valeur avec laquelle [`interrupt()`](#query-object) se résout sur une CLI qui annonce la capacité `interrupt_receipt_v1` dans [`SDKSystemMessage.capabilities`](#sdksystemmessage). Nécessite Claude Code v2.1.205 ou ultérieure. Les CLI antérieures répondent à l'interruption avec un payload de succès vide, de sorte que `interrupt()` se résout en `undefined`.887L'accusé d'interruption : la valeur avec laquelle [`interrupt()`](#query-object) se résout sur une CLI qui annonce la capacité `interrupt_receipt_v1` dans [`SDKSystemMessage.capabilities`](#sdksystemmessage). Nécessite Claude Code v2.1.205 ou ultérieur. Les CLI antérieures répondent à l'interruption avec un payload de succès vide ; `interrupt()` se résout donc en `undefined`.
887 888
888```typescript theme={null}889```typescript theme={null}
889type SDKControlInterruptResponse = {890type SDKControlInterruptResponse = {
892};893};
893```894```
894 895
895`still_queued` liste les UUID des messages utilisateur qui étaient en attente lorsque l'interruption est arrivée : les messages encore dans la file d'attente, ainsi que les messages que Claude Code avait déjà retirés de la file pour le tour suivant. Une fois le premier tour de la session commencé, Claude Code traite les messages listés après l'interruption, sauf si vous les annulez d'abord, et peut en fusionner plusieurs en un seul tour. Si vous interrompez avant le début du premier tour, Claude Code interrompt ce tour dès qu'il commence, et les messages listés dans ce tour ne reçoivent aucune réponse.896`still_queued` liste les UUID des messages utilisateur qui étaient en attente au moment de l'interruption : les messages encore dans la file d'attente, ainsi que ceux que Claude Code avait déjà retirés de la file pour le tour suivant. Une fois le premier tour de la session commencé, Claude Code traite les messages listés après l'interruption, sauf si vous les annulez auparavant, et peut en fusionner plusieurs en un seul tour. Si vous interrompez avant le début du premier tour, Claude Code interrompt ce tour dès qu'il commence, et les messages listés dans ce tour ne reçoivent aucune réponse.
896 897
897Utilisez le reçu pour décider s'il faut renvoyer quelque chose. Un message listé que vous n'annulez pas entre dans la conversation, qu'il reçoive une réponse ou non ; le renvoyer le transmet donc deux fois à Claude.898Utilisez l'accusé pour décider s'il faut renvoyer quelque chose. Un message listé que vous n'annulez pas entre dans la conversation, qu'il reçoive une réponse ou non ; le renvoyer le transmet donc deux fois à Claude.
898 899
899Interprétez la liste en tenant compte des réserves suivantes :900Interprétez la liste en tenant compte des réserves suivantes :
900 901
901* Seuls les messages mis en file d'attente avec un UUID apparaissent. Un tableau vide ne signifie pas que rien d'autre ne s'exécutera.902* Seuls les messages mis en file d'attente avec un UUID y figurent. Un tableau vide ne signifie pas que rien d'autre ne s'exécutera.
902* Seuls les messages du thread principal sont listés. Les messages adressés à un sous-agent sont hors du périmètre.903* Seuls les messages du thread principal sont listés. Les messages adressés à un sous-agent ne sont pas concernés.
903* La liste peut inclure des UUID que votre client n'a jamais envoyés, comme les déclencheurs de [tâches planifiées limitées à la session](https://code.claude.com/docs/fr/scheduled-tasks.md). Ignorez les UUID que vous ne reconnaissez pas au lieu de les traiter comme une erreur.904* La liste peut inclure des UUID que votre client n'a jamais envoyés, comme les déclencheurs de [tâches planifiées limitées à la session](https://code.claude.com/docs/fr/scheduled-tasks.md). Ignorez les UUID que vous ne reconnaissez pas au lieu de les traiter comme une erreur.
904 905
905Un client qui pilote directement le protocole de contrôle de la CLI, plutôt que via `interrupt()`, peut définir `cancel_queued: true` sur la requête de contrôle `interrupt`. Claude Code v2.1.219 et versions ultérieures annoncent la prise en charge avec la capacité `interrupt_cancel_queued_v1` dans [`SDKSystemMessage.capabilities`](#sdksystemmessage) ; les CLI plus anciennes ignorent le champ et laissent les messages en file d'attente s'exécuter normalement. Une telle interruption annule également tous les messages qui seraient sinon listés sous `still_queued` : le reçu les liste sous `cancelled` à la place, `still_queued` est vide, et aucun d'eux ne s'exécute.906Un client qui pilote directement le protocole de contrôle de la CLI, plutôt que via `interrupt()`, peut définir `cancel_queued: true` sur la requête de contrôle `interrupt`. Claude Code v2.1.219 et ultérieur annonce cette prise en charge avec la capacité `interrupt_cancel_queued_v1` dans [`SDKSystemMessage.capabilities`](#sdksystemmessage) ; les CLI plus anciennes ignorent ce champ et laissent les messages en file d'attente s'exécuter normalement. Une telle interruption annule également tous les messages qui seraient autrement listés sous `still_queued` : l'accusé les liste plutôt sous `cancelled`, `still_queued` est vide, et aucun d'eux ne s'exécute.
906 907
907La liste `cancelled` comporte les mêmes réserves que `still_queued`. La méthode `interrupt()` n'envoie jamais `cancel_queued`, de sorte que les reçus avec lesquels elle se résout ne contiennent pas `cancelled`.908La liste `cancelled` est soumise aux mêmes réserves que `still_queued`. La méthode `interrupt()` n'envoie jamais `cancel_queued` ; les accusés avec lesquels elle se résout ne contiennent donc pas `cancelled`.
908 909
909Le reçu est un instantané pris au moment où l'interruption est traitée et, lors d'une interruption propre, il arrive avant le [`SDKResultMessage`](#sdkresultmessage) du tour interrompu. Lisez le reçu plutôt que d'inspecter la file d'attente après ce résultat : la boucle démarre immédiatement le tour suivant en file d'attente, de sorte que la file que vous inspectez après le résultat a déjà changé.910L'accusé est un instantané pris au moment où l'interruption est traitée et, lors d'une interruption propre, il arrive avant le [`SDKResultMessage`](#sdkresultmessage) du tour interrompu. Lisez l'accusé plutôt que d'inspecter la file d'attente après ce résultat : la boucle démarre immédiatement le tour suivant en file d'attente, si bien que la file que vous inspectez après le résultat a déjà changé.
910 911
911### `SDKControlGetContextUsageResponse`912### `SDKControlGetContextUsageResponse`
912 913
913Type de retour de [`getContextUsage()`](#query-object). Avec la valeur par défaut de `detail`, la réponse inclut le payload que Claude Code affiche pour la commande `/context` dans une session interactive. En plus du nombre de tokens, ce payload contient des champs d'affichage tels que `color` et `gridRows`, que Claude Code utilise pour dessiner la grille d'utilisation de `/context`.914Type de retour de [`getContextUsage()`](#query-object). Avec la valeur par défaut de `detail`, la réponse inclut le payload que Claude Code affiche pour la commande `/context` dans une session interactive. En plus du nombre de tokens, ce payload contient des champs d'affichage tels que `color` et `gridRows` que Claude Code utilise pour dessiner la grille d'utilisation de `/context`.
914 915
915L'argument optionnel `detail` de la méthode détermine la manière dont Claude Code compte chaque catégorie. L'argument `detail` nécessite Agent SDK v0.3.257 ou ultérieure.916L'argument facultatif `detail` de la méthode détermine la manière dont Claude Code compte chaque catégorie. L'argument `detail` nécessite Agent SDK v0.3.257 ou ultérieur.
916 917
917* **`'full'`** : la valeur par défaut. Claude Code compte chaque catégorie avec des requêtes API de [comptage de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Ces requêtes n'apparaissent pas dans le flux de messages, de sorte que le suivi des coûts qui lit le flux ne les verra pas. Sur l'API Anthropic, le comptage de tokens n'est pas facturé.918* **`'full'`** : la valeur par défaut. Claude Code compte chaque catégorie au moyen de requêtes API de [comptage de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Ces requêtes n'apparaissent pas dans le flux de messages ; un suivi des coûts qui lit le flux ne les verra donc pas. Sur l'API Anthropic, le comptage de tokens n'est pas facturé.
918* **`'summary'`** : passez `{ detail: 'summary' }` pour obtenir plutôt une réponse basée sur l'utilisation de la dernière réponse et sur des estimations locales. Aucune requête de comptage de tokens n'est envoyée, et les nombres par catégorie sont approximatifs.919* **`'summary'`** : transmettez `{ detail: 'summary' }` pour obtenir plutôt une réponse fondée sur l'utilisation de la dernière réponse et sur des estimations locales. Aucune requête de comptage de tokens n'est envoyée, et les chiffres par catégorie sont approximatifs.
919 920
920Lorsque vous envoyez `/context` comme prompt au lieu d'appeler la méthode, Claude Code joint un payload [`SDKContextUsage`](#sdkcontextusage) au champ `context_usage` du message assistant qui délivre le résultat. Ce champ nécessite Agent SDK v0.3.232 ou ultérieure.921Lorsque vous envoyez `/context` sous forme de prompt au lieu d'appeler la méthode, Claude Code joint un payload [`SDKContextUsage`](#sdkcontextusage) au champ `context_usage` du message assistant qui transmet le résultat. Ce champ nécessite Agent SDK v0.3.232 ou ultérieur.
921 922
922Dans `SDKControlGetContextUsageResponse`, `categories[].id`, `mcpInstructions`, ainsi que les champs `pluginId` et `path` des entrées `agents` et `skills.skillFrontmatter` nécessitent Agent SDK v0.3.304 ou ultérieur.923Dans `SDKControlGetContextUsageResponse`, `categories[].id`, `mcpInstructions` ainsi que les champs `pluginId` et `path` des entrées `agents` et `skills.skillFrontmatter` nécessitent Agent SDK v0.3.304 ou ultérieur.
923 924
924```typescript theme={null}925```typescript theme={null}
925type SDKControlGetContextUsageResponse = {926type SDKControlGetContextUsageResponse = {
1041 1042
1042Lisez l'attribution des tokens à partir des champs de collection :1043Lisez l'attribution des tokens à partir des champs de collection :
1043 1044
1044* `categories` contient les totaux par catégorie. Le `kind` de chaque entrée classe la ligne avec les mêmes valeurs que [`SDKContextUsageCategory`](#sdkcontextusagecategory). Classez les lignes selon ce champ plutôt que selon le `name` d'affichage. Le champ nécessite Agent SDK v0.3.268 ou ultérieure.1045* `categories` contient les totaux par catégorie. Le champ `kind` de chaque entrée classe la ligne avec les mêmes valeurs que [`SDKContextUsageCategory`](#sdkcontextusagecategory). Classez les lignes selon ce champ plutôt que selon le `name` d'affichage. Ce champ nécessite Agent SDK v0.3.268 ou ultérieur.
1045* `mcpTools` et `agents` attribuent les tokens à des outils MCP et à des sous-agents individuels.1046* `mcpTools` et `agents` attribuent les tokens aux outils MCP et aux sous-agents individuels.
1046* `memoryFiles` liste chaque fichier de mémoire chargé avec son coût.1047* `memoryFiles` liste chaque fichier de mémoire chargé avec son coût.
1047* `skills.skillFrontmatter` attribue les tokens de la liste des skills à chaque skill inclus. Les nombres par skill mesurent l'entrée de chaque skill dans la liste telle que Claude Code l'envoie réellement, qui peut être plus courte que le frontmatter complet du skill. Comparez `skills.totalSkills` à `skills.includedSkills` pour vérifier si chaque skill découvert figure dans la liste.1048* `skills.skillFrontmatter` attribue les tokens de la liste des skills à chaque skill inclus. Les comptes par skill mesurent l'entrée de chaque skill dans la liste telle que Claude Code l'envoie réellement, qui peut être plus courte que le frontmatter complet du skill. Comparez `skills.totalSkills` à `skills.includedSkills` pour vérifier si chaque skill découvert figure dans la liste.
1048 1049
1049`totalTokens` représente l'utilisation actuelle du contexte de la session, et `maxTokens` la fenêtre par rapport à laquelle cette utilisation est mesurée. Cette fenêtre est la fenêtre de contexte du modèle, ou la fenêtre de compaction automatique inférieure lorsqu'elle s'applique. `rawMaxTokens` contient la même valeur que `maxTokens`, et `percentage` correspond à `totalTokens` exprimé en pourcentage arrondi de cette fenêtre. `apiUsage` contient l'utilisation issue de la dernière réponse de l'API, et non un total cumulé pour la session.1050`totalTokens` correspond à l'utilisation actuelle du contexte de la session, et `maxTokens` à la fenêtre par rapport à laquelle cette utilisation est mesurée. Cette fenêtre est la fenêtre de contexte du modèle, ou la fenêtre de compaction automatique plus petite lorsqu'elle s'applique. `rawMaxTokens` contient la même valeur que `maxTokens`, et `percentage` exprime `totalTokens` sous forme de pourcentage arrondi de cette fenêtre. `apiUsage` contient l'utilisation issue de la dernière réponse de l'API, et non un total cumulé pour la session.
1050 1051
1051Claude Code laisse non définis les diagnostics optionnels `deferredBuiltinTools`, `systemTools` et `systemPromptSections` ; attendez-vous donc à ce qu'ils soient absents, même si le type les déclare.1052Claude Code ne renseigne pas les diagnostics facultatifs `deferredBuiltinTools`, `systemTools` et `systemPromptSections` ; attendez-vous donc à ce qu'ils soient absents, même si le type les déclare.
1052 1053
1053#### Trouver une ligne par ID, les tokens d'instructions d'un serveur ou le plugin et le fichier d'une entrée1054#### Trouver une ligne par ID, les tokens d'instructions d'un serveur, ou le plugin et le fichier d'une entrée
1054 1055
1055Les instructions de serveur MCP sont les notes d'utilisation que les serveurs connectés fournissent et que Claude Code ajoute au contexte, et la ligne `mcp_instructions` de `categories` compte leurs tokens. Utilisez ces champs de [`getContextUsage()`](#query-object) pour isoler une ligne de `categories` par `id`, répartir les tokens de `mcp_instructions` par serveur, ou trouver le plugin et le fichier à l'origine d'une entrée d'agent ou de skill :1056Les instructions des serveurs MCP sont les notes d'utilisation que fournissent les serveurs connectés et que Claude Code ajoute au contexte ; la ligne `mcp_instructions` de `categories` compte leurs tokens. Utilisez ces champs de [`getContextUsage()`](#query-object) pour sélectionner une ligne de `categories` par `id`, répartir les tokens de `mcp_instructions` par serveur, ou trouver le plugin et le fichier à l'origine d'une entrée d'agent ou de skill :
1056 1057
1057| Champ | Emplacement | Contenu |1058| Champ | Emplacement | Contenu |
1058| :- | :- | :- |1059| :- | :- | :- |
1059| `id` | Chaque ligne de `categories` | L'identifiant de la ligne, l'une des valeurs listées par le [type de réponse](#sdkcontrolgetcontextusageresponse), comme `mcp_instructions`. Filtrez sur `id` pour isoler une ligne, ou sur `kind` pour regrouper des lignes. Une version ultérieure de Claude Code peut envoyer une valeur que vos types installés ne listent pas ; traitez donc un `id` que vous ne reconnaissez pas comme absent |1060| `id` | Chaque ligne de `categories` | L'identifiant de la ligne, l'une des valeurs listées par le [type de réponse](#sdkcontrolgetcontextusageresponse), comme `mcp_instructions`. Filtrez sur `id` pour sélectionner une ligne, ou sur `kind` pour regrouper des lignes. Une version ultérieure de Claude Code peut envoyer une valeur que vos types installés ne listent pas ; considérez donc un `id` que vous ne reconnaissez pas comme absent |
1060| `mcpInstructions` | La réponse | Une entrée `{ serverName, tokens }` par serveur MCP connecté qui fournit des instructions, ou un tableau vide lorsqu'aucun n'en fournit. Les valeurs `tokens` sont des estimations dont la somme correspond aux `tokens` de la ligne `mcp_instructions`. `serverName` est le `name` que [`mcpServerStatus()`](#query-object) indique pour ce serveur |1061| `mcpInstructions` | La réponse | Une entrée `{ serverName, tokens }` par serveur MCP connecté qui fournit des instructions, ou un tableau vide lorsqu'aucun n'en fournit. Les valeurs `tokens` sont des estimations dont la somme correspond aux `tokens` de la ligne `mcp_instructions`. `serverName` est le `name` que [`mcpServerStatus()`](#query-object) indique pour ce serveur |
1061| `pluginId` | Entrées `agents` et `skills.skillFrontmatter` | Nomme le plugin dont provient l'entrée, sous forme d'ID au format `name@marketplace`, et est absent pour une entrée qui ne provient pas d'un plugin. Lorsque le plugin ne provient pas d'une marketplace, la partie après `@` nomme plutôt [son origine](https://code.claude.com/docs/fr/plugins/loading.md#find-where-a-plugin-came-from), comme `inline` pour un plugin que vous avez chargé via l'option [`plugins`](#options) |1062| `pluginId` | Entrées `agents` et `skills.skillFrontmatter` | Nomme le plugin dont provient l'entrée, sous forme d'ID au format `name@marketplace`, et est absent pour une entrée qui ne provient pas d'un plugin. Lorsque le plugin ne provient pas d'une marketplace, la partie après `@` indique plutôt [son origine](https://code.claude.com/docs/fr/plugins/loading.md#find-where-a-plugin-came-from), par exemple `inline` pour un plugin que vous avez chargé via l'option [`plugins`](#options) |
1062| `path` | Entrées `agents` et `skills.skillFrontmatter` | Chemin absolu du fichier qui définit l'agent ou le skill, sur la machine où s'exécute Claude Code. Le champ est absent lorsqu'aucun fichier ne définit l'entrée, par exemple pour un agent provenant de l'option [`agents`](#options) ou pour un skill intégré à Claude Code |1063| `path` | Entrées `agents` et `skills.skillFrontmatter` | Chemin absolu du fichier qui définit l'agent ou le skill, sur la machine où s'exécute Claude Code. Ce champ est absent lorsqu'aucun fichier ne définit l'entrée, par exemple pour un agent provenant de l'option [`agents`](#options) ou un skill intégré à Claude Code |
1063 1064
1064À titre d'exemple de filtrage sur `id`, cet extrait trouve la ligne `mcp_instructions` :1065À titre d'exemple de filtrage sur `id`, cet extrait trouve la ligne `mcp_instructions` :
1065 1066
1083};1084};
1084```1085```
1085 1086
1086`contents` contient le texte du fichier, ou des données base64 lorsque vous avez demandé `encoding: 'base64'` ; le champ `encoding` de la réponse est alors défini sur `'base64'`. `absPath` est le chemin absolu résolu. `truncated` est défini lorsque le fichier dépassait la limite `maxBytes` et que le contenu a été tronqué à cette limite.1087`contents` contient le texte du fichier, ou des données base64 lorsque vous avez demandé `encoding: 'base64'` ; le champ `encoding` de la réponse est alors défini sur `'base64'`. `absPath` est le chemin absolu résolu. `truncated` est défini lorsque le fichier dépassait la limite `maxBytes` et que le contenu a été coupé à cette limite.
1087 1088
1088#### Ce que `readFile()` peut lire1089#### Ce que `readFile()` peut lire
1089 1090
1090`readFile()` sert un ensemble de fichiers plus restreint que l'outil Read :1091`readFile()` donne accès à un ensemble de fichiers plus restreint que l'outil Read :
1091 1092
1092* Un fichier ordinaire situé dans l'un des répertoires de travail de la session, tels que `cwd` et `additionalDirectories`1093* Un fichier ordinaire situé dans l'un des répertoires de travail de la session, comme `cwd` et `additionalDirectories`
1093* Quelques fichiers propres à Claude Code pour la session, tels que les résultats d'outils1094* Quelques fichiers propres à Claude Code pour la session, comme les résultats d'outils
1094 1095
1095Les règles de refus et de demande `Read` bloquent toujours un chemin correspondant, et une règle d'autorisation `Read` large n'ouvre pas le reste du système de fichiers à `readFile()`. Pour tout autre fichier, l'appel se résout avec `null`.1096Les règles deny et ask de `Read` bloquent toujours un chemin correspondant, et une règle allow large de `Read` n'ouvre pas le reste du système de fichiers à `readFile()`. Dans tous les autres cas, l'appel se résout avec `null`.
1096 1097
1097### `SDKControlReloadPluginsResponse`1098### `SDKControlReloadPluginsResponse`
1098 1099
1121 1122
1122Les champs de collection décrivent la session après l'appel :1123Les champs de collection décrivent la session après l'appel :
1123 1124
1124* `commands`, `agents` et `mcpServers` : les commandes, les sous-agents et l'état des serveurs MCP de la session, sous les mêmes formes que celles renvoyées par `supportedCommands()`, `supportedAgents()` et `mcpServerStatus()`. `supportedAgents()` continue de renvoyer la liste capturée lors de l'initialisation ; lisez donc `agents` ici pour obtenir l'ensemble après un rechargement1125* `commands`, `agents` et `mcpServers` : les commandes, les sous-agents et l'état des serveurs MCP de la session, sous les mêmes formes que celles renvoyées par `supportedCommands()`, `supportedAgents()` et `mcpServerStatus()`. `supportedAgents()` continue de renvoyer la liste capturée à l'initialisation ; lisez donc `agents` ici pour obtenir l'ensemble après un rechargement
1125* `plugins` : chaque plugin chargé avec son `name` et son `path` d'installation. `version` reprend ce que déclare le manifeste du plugin et est contrôlé par l'auteur du plugin ; validez-le donc avant de vous y fier. Il est omis lorsque le manifeste n'en déclare aucune1126* `plugins` : chaque plugin chargé avec son `name` et son `path` d'installation. `version` reprend ce que déclare le manifeste du plugin et est contrôlé par l'auteur du plugin ; validez-le donc avant de vous y fier. Il est omis lorsque le manifeste n'en déclare aucune
1126* `error_count` : le nombre d'erreurs survenues lors du chargement des plugins1127* `error_count` : le nombre d'erreurs survenues lors du chargement des plugins
1127 1128
1128Passez `{ holdOnCacheImpact: true }` à `reloadPlugins()` pour suspendre un rechargement qui invaliderait le cache de prompts de la conversation au lieu de l'appliquer. Claude Code effectue la vérification que réalise la commande interactive `/reload-plugins` avant d'[avertir du coût pour le cache](https://code.claude.com/docs/fr/prompt-caching.md#enabling-or-disabling-a-plugin). L'option nécessite Agent SDK v0.3.268 ou ultérieure. Un exécutable Claude Code antérieur à v2.1.268, comme celui vers lequel vous faites pointer `pathToClaudeCodeExecutable`, ignore l'option et applique le rechargement.1129Passez `{ holdOnCacheImpact: true }` à `reloadPlugins()` pour suspendre un rechargement qui invaliderait le cache de prompts de la conversation au lieu de l'appliquer. Claude Code exécute la vérification que la commande interactive `/reload-plugins` effectue avant d'[avertir du coût pour le cache](https://code.claude.com/docs/fr/prompt-caching.md#enabling-or-disabling-a-plugin). L'option nécessite l'Agent SDK v0.3.268 ou une version ultérieure. Un exécutable Claude Code antérieur à la v2.1.268, comme celui que vous désignez avec `pathToClaudeCodeExecutable`, ignore l'option et applique le rechargement.
1129 1130
1130Lorsque vous passez l'option, lisez `held` pour savoir ce qui s'est passé :1131Lorsque vous passez l'option, lisez `held` pour savoir ce qui s'est passé :
1131 1132
1132* `true` : le rechargement n'a pas été appliqué, et les champs de collection décrivent la session telle qu'elle est toujours. `cache_impact` indique ce que l'application changerait. Pour appliquer malgré tout, appelez de nouveau `reloadPlugins()` sans l'option.1133* `true` : le rechargement n'a pas été appliqué, et les champs de collection décrivent la session dans son état actuel. `cache_impact` indique ce que l'application modifierait. Pour l'appliquer malgré tout, appelez de nouveau `reloadPlugins()` sans l'option.
1133* `false` : la vérification n'a trouvé aucun impact sur le cache, et le rechargement a été appliqué.1134* `false` : la vérification n'a trouvé aucun impact sur le cache, et le rechargement a été appliqué.
1134* Absent : vous n'avez pas passé l'option, ou l'exécutable Claude Code est antérieur à v2.1.268 et a appliqué le rechargement.1135* Absent : vous n'avez pas passé l'option, ou l'exécutable Claude Code est antérieur à la v2.1.268 et a appliqué le rechargement.
1136
1137`cache_impact` n'est présent qu'avec `held: true`. `mcp_servers_added` et `mcp_servers_removed` nomment les serveurs MCP de plugins que le rechargement enregistrerait ou supprimerait, sous forme de noms à portée `plugin:<plugin>:<server>`. Ces noms sont rédigés par les auteurs des plugins ; validez-les donc avant de les afficher. `lsp_tool_change` indique si l'application ajouterait ou supprimerait l'outil LSP, ou vaut `null` si elle ne ferait ni l'un ni l'autre. Les formes `may-` signifient que la vérification n'a pas pu voir entièrement l'ensemble de plugins en attente.
1138
1139#### Charger d'autres dossiers de plugins avec `addPlugins`
1140
1141Pour charger des dossiers de plugins qui ne figuraient pas dans l'option [`plugins`](#options) au démarrage, passez-les à `reloadPlugins()` sous la forme `addPlugins`, une liste d'entrées [`SdkPluginConfig`](#sdkpluginconfig) dont le `path` est absolu. Claude Code charge les nouveaux dossiers et recharge les plugins existants de la session en une seule passe. Les serveurs MCP de chaque plugin ajouté se connectent également, sauf si vous définissez [`skipMcpDiscovery`](#sdkpluginconfig) sur l'entrée de ce dossier. Nécessite l'Agent SDK v0.3.301 ou une version ultérieure et Claude Code v2.1.301 ou une version ultérieure.
1142
1143Cet exemple ajoute un dossier à une requête `q` en cours d'exécution et affiche le chemin d'installation de chaque plugin chargé par la session au retour de l'appel :
1144
1145```typescript theme={null}
1146const result = await q.reloadPlugins({
1147 addPlugins: [{ type: "local", path: "/opt/my-app/plugins/reports" }]
1148});
1149
1150console.log(result.plugins.map((plugin) => plugin.path));
1151```
1135 1152
1136`cache_impact` n'est présent qu'avec `held: true`. `mcp_servers_added` et `mcp_servers_removed` nomment les serveurs MCP de plugins que le rechargement enregistrerait ou supprimerait, sous forme de noms à portée `plugin:<plugin>:<server>`. Les noms sont définis par les auteurs des plugins ; validez-les donc avant de les afficher. `lsp_tool_change` indique si l'application ajouterait ou retirerait l'outil LSP, ou vaut `null` si elle ne ferait ni l'un ni l'autre. Les formes `may-` signifient que la vérification n'a pas pu voir entièrement l'ensemble des plugins en attente.1153Si le dossier a été chargé, la liste affichée inclut `/opt/my-app/plugins/reports`, et les commandes et sous-agents du plugin apparaissent dans `result.commands` et `result.agents`.
1154
1155Un dossier ajouté reste rattaché à la session. Lorsque vous appelez de nouveau `reloadPlugins()`, Claude Code le recharge avec les autres plugins, et vous n'avez pas à le repasser dans `addPlugins`.
1156
1157##### Lorsque `reloadPlugins()` ne charge pas les dossiers `addPlugins`
1158
1159Si `reloadPlugins()` est rejeté, aucun des dossiers `addPlugins` n'est ajouté ; repassez-les donc dans `addPlugins` lorsque vous réessayez. Lorsque le rejet a l'une des causes suivantes, la session conserve les plugins dont elle disposait déjà :
1160
1161* **Un `path` relatif ou une entrée mal formée** : le message d'erreur indique `add_plugins must be a list of { type: "local", path } entries with absolute paths`. Claude Code refuse la liste entière à cause d'une seule entrée incorrecte ; passez donc chaque entrée sous la forme `{ type: "local", path }` avec un `path` absolu
1162* **Un administrateur a activé [`disableSideloadFlags`](https://code.claude.com/docs/fr/settings-reference#disablesideloadflags) dans vos paramètres gérés** : le message indique `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`. Pour charger le dossier, demandez à cet administrateur de supprimer le paramètre
1163* **Le [sandbox](https://code.claude.com/docs/fr/sandboxing.md) n'a pas pu être reconstruit** : lorsque le [sandboxing](#sandboxsettings) est activé, Claude Code reconstruit la configuration du sandbox afin que les commandes shell exécutées en sandbox ne puissent pas écrire dans les dossiers que vous ajoutez. Le message indique `the sandbox could not be rebuilt to keep shell commands out of this folder`. Vérifiez que vos [paramètres de sandbox](#sandboxsettings) forment toujours une configuration valide
1164
1165Si vous passez `holdOnCacheImpact` et que l'appel se résout avec [`held: true`](#sdkcontrolreloadpluginsresponse), les dossiers `addPlugins` ne sont pas ajoutés. Pour les ajouter malgré tout, appelez de nouveau `reloadPlugins()` avec la même liste `addPlugins` et sans `holdOnCacheImpact`.
1166
1167Lorsque l'appel se résout sans `held: true` et qu'un dossier est toujours absent de `result.plugins`, commencez par vérifier les causes suivantes :
1168
1169* **Le dossier n'existe pas ou son plugin n'a pas pu être chargé** : `result.error_count` vaut `1` ou plus. Le dossier reste tout de même rattaché à la session. Après avoir corrigé le dossier, appelez de nouveau `reloadPlugins()` pour le charger, cette fois sans l'indiquer dans `addPlugins`
1170* **L'exécutable Claude Code est antérieur à la v2.1.301** : un exécutable antérieur à la v2.1.301 ignore `addPlugins` et ne recharge que les plugins dont la session disposait déjà. Vérifiez `claude_code_version` dans le [message init](#sdksystemmessage), et exécutez un exécutable en v2.1.301 ou ultérieure
1137 1171
1138### `SDKControlReloadSkillsResponse`1172### `SDKControlReloadSkillsResponse`
1139 1173
1161 1195
1162### `SDKControlMcpReadResourceResponse`1196### `SDKControlMcpReadResourceResponse`
1163 1197
1164Type de retour de [`readMcpResource()`](#query-object), contenant le résultat `resources/read` du serveur MCP. Nécessite TypeScript Agent SDK v0.3.280 ou ultérieure.1198Type de retour de [`readMcpResource()`](#query-object), qui transporte le résultat `resources/read` du serveur MCP. Nécessite le TypeScript Agent SDK v0.3.280 ou une version ultérieure.
1165 1199
1166```typescript theme={null}1200```typescript theme={null}
1167type SDKControlMcpReadResourceResponse = {1201type SDKControlMcpReadResourceResponse = {
1175};1209};
1176```1210```
1177 1211
1178Passez à `readMcpResource()` le nom du serveur tel que le signale `mcpServerStatus()` et un URI `ui://`, comme le `ui.resourceUri` qu'un outil déclare dans son [`_meta`](#mcpserverstatus). L'appel est rejeté 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é. Il est disponible lorsque les [`capabilities`](#sdksystemmessage) du message d'initialisation incluent `mcp_read_resource_v1`.1212Passez à `readMcpResource()` le nom du serveur tel que `mcpServerStatus()` le rapporte et une URI `ui://`, comme le `ui.resourceUri` qu'un outil déclare dans son [`_meta`](#mcpserverstatus). L'appel est rejeté 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é. Il est disponible lorsque les [`capabilities`](#sdksystemmessage) du message init incluent `mcp_read_resource_v1`.
1179 1213
1180Chaque entrée de `contents` est un élément de contenu tel que le serveur l'a envoyé, sans les clés `_meta` sous le préfixe `com.anthropic/`, qui est réservé à Claude Code. `blob` contient des données base64 pour un élément binaire, et `_meta` est le `_meta` propre à l'élément, où un serveur MCP Apps place les `ui.csp` et `ui.permissions` de la ressource.1214Chaque entrée `contents` est un élément de contenu tel que le serveur l'a envoyé, moins toute clé `_meta` sous le préfixe `com.anthropic/`, réservé à Claude Code. `blob` contient les données base64 d'un élément binaire, et `_meta` est le propre `_meta` de l'élément, où un serveur MCP Apps place les `ui.csp` et `ui.permissions` de la ressource.
1181 1215
1182Le contenu est du HTML tiers non fiable ; affichez-le donc dans un sandbox.1216Le contenu est du HTML tiers non fiable ; affichez-le donc dans un sandbox.
1183 1217
1206};1240};
1207```1241```
1208 1242
1209| Champ | Requis | Description |1243| Champ | Obligatoire | Description |
1210| :- | :- | :- |1244| :- | :- | :- |
1211| `description` | Oui | Description en langage naturel indiquant quand utiliser cet agent |1245| `description` | Oui | Description en langage naturel indiquant quand utiliser cet agent |
1212| `tools` | Non | Tableau des noms d'outils autorisés. S'il est omis, hérite de tous les [outils disponibles pour les sous-agents](https://code.claude.com/docs/fr/sub-agents.md#available-tools). Pour précharger des skills dans le contexte de l'agent, utilisez le champ `skills` plutôt que de lister `'Skill'` ici |1246| `tools` | Non | Tableau des noms d'outils autorisés. S'il est omis, hérite de chaque [outil disponible pour les sous-agents](https://code.claude.com/docs/fr/sub-agents.md#available-tools). Pour précharger des skills dans le contexte de l'agent, utilisez le champ `skills` plutôt que d'indiquer `'Skill'` ici |
1213| `disallowedTools` | Non | Tableau des noms d'outils à interdire explicitement pour cet agent. Les motifs au niveau du serveur MCP sont également acceptés : `mcp__server` ou `mcp__server__*` retire tous les outils de ce serveur, et `mcp__*` retire tous les outils MCP de n'importe quel serveur |1247| `disallowedTools` | Non | Tableau des noms d'outils à interdire explicitement pour cet agent. Les motifs au niveau du serveur MCP sont également acceptés : `mcp__server` ou `mcp__server__*` supprime tous les outils de ce serveur, et `mcp__*` supprime tous les outils MCP de n'importe quel serveur |
1214| `prompt` | Oui | Le prompt système de l'agent |1248| `prompt` | Oui | Le prompt système de l'agent |
1215| `model` | Non | Remplacement du modèle pour cet agent. Accepte un alias tel que `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, ou un ID de modèle complet. `'inherit'` utilise le modèle principal. Si vous l'omettez, Claude Code choisit le modèle selon l'[ordre des modèles des sous-agents](https://code.claude.com/docs/fr/sub-agents.md#choose-a-model) |1249| `model` | Non | Remplacement du modèle pour cet agent. Accepte un alias tel que `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, ou un ID de modèle complet. `'inherit'` utilise le modèle principal. Si vous l'omettez, Claude Code choisit le modèle selon l'[ordre des modèles des sous-agents](https://code.claude.com/docs/fr/sub-agents.md#choose-a-model) |
1216| `mcpServers` | Non | Spécifications des serveurs MCP pour cet agent |1250| `mcpServers` | Non | Spécifications des serveurs MCP pour cet agent |
1217| `skills` | Non | Tableau des noms de skills à précharger dans le contexte de l'agent |1251| `skills` | Non | Tableau des noms de skills à précharger dans le contexte de l'agent |
1218| `initialPrompt` | Non | Soumis automatiquement comme premier tour utilisateur lorsque cet agent s'exécute en tant qu'agent du thread principal |1252| `initialPrompt` | Non | Soumis automatiquement comme premier tour utilisateur lorsque cet agent s'exécute en tant qu'agent du thread principal |
1219| `maxTurns` | Non | Nombre maximal de tours agentiques (allers-retours API) avant l'arrêt |1253| `maxTurns` | Non | Nombre maximal de tours agentiques (allers-retours avec l'API) avant l'arrêt |
1220| `autoCompactWindow` | Non | Réduit la [fenêtre de compaction automatique](https://code.claude.com/docs/fr/sub-agents.md#subagent-auto-compact-window) de cet agent lorsqu'il s'exécute en tant que sous-agent, à un nombre de tokens compris entre `100000` et `1000000`. Nécessite TypeScript Agent SDK v0.3.296 ou ultérieur |1254| `autoCompactWindow` | Non | Abaisse la [fenêtre de compaction automatique](https://code.claude.com/docs/fr/sub-agents.md#subagent-auto-compact-window) de cet agent lorsqu'il s'exécute en tant que sous-agent, à un nombre de tokens compris entre `100000` et `1000000`. Nécessite le TypeScript Agent SDK v0.3.296 ou une version ultérieure |
1221| `background` | Non | Exécuter cet agent comme tâche en arrière-plan non bloquante lorsqu'il est invoqué |1255| `background` | Non | Exécute cet agent en tant que tâche en arrière-plan non bloquante lorsqu'il est invoqué |
1222| `omitClaudeMd` | Non | Exclut les fichiers CLAUDE.md utilisateur, projet et locaux du contexte initial de cet agent ; les fichiers de politique gérée sont toujours chargés. Utilisez-le pour les agents qui tirent tout ce dont ils ont besoin du prompt de l'outil Agent. Ignoré lorsque cet agent s'exécute en tant qu'agent du thread principal. Nécessite TypeScript Agent SDK v0.3.271 ou ultérieur |1256| `omitClaudeMd` | Non | Exclut les fichiers CLAUDE.md utilisateur, projet et locaux du contexte initial de cet agent ; les fichiers de politique gérée sont toujours chargés. Utilisez-le pour les agents qui tirent tout ce dont ils ont besoin du prompt de l'outil Agent. Ignoré lorsque cet agent s'exécute en tant qu'agent du thread principal. Nécessite le TypeScript Agent SDK v0.3.271 ou une version ultérieure |
1223| `memory` | Non | Source de mémoire pour cet agent : `'user'`, `'project'` ou `'local'` |1257| `memory` | Non | Source de mémoire pour cet agent : `'user'`, `'project'` ou `'local'` |
1224| `effort` | Non | Niveau d'effort de raisonnement pour cet agent. Accepte un niveau nommé ou un entier |1258| `effort` | Non | Niveau d'effort de raisonnement pour cet agent. Accepte un niveau nommé ou un entier |
1225| `permissionMode` | Non | Mode de permission pour l'exécution des outils au sein de cet agent. Les [règles d'héritage des sous-agents](https://code.claude.com/docs/fr/agent-sdk/permissions.md#available-modes) déterminent quand il s'applique. Consultez [`PermissionMode`](#permissionmode) |1259| `permissionMode` | Non | Mode de permission pour l'exécution des outils au sein de cet agent. Les [règles d'héritage des sous-agents](https://code.claude.com/docs/fr/agent-sdk/permissions.md#available-modes) déterminent quand il s'applique. Voir [`PermissionMode`](#permissionmode) |
1226| `criticalSystemReminder_EXPERIMENTAL` | Non | Expérimental : rappel critique ajouté au prompt système |1260| `criticalSystemReminder_EXPERIMENTAL` | Non | Expérimental : rappel critique ajouté au prompt système |
1227 1261
1228### `AgentMcpServerSpec`1262### `AgentMcpServerSpec`
1229 1263
1230Spécifie les serveurs MCP disponibles pour un sous-agent. Peut être un nom de serveur (chaîne référençant un serveur de la configuration `mcpServers` du parent) ou un enregistrement de configuration de serveur en ligne associant des noms de serveurs à des configurations.1264Spécifie les serveurs MCP disponibles pour un sous-agent. Peut être un nom de serveur (chaîne faisant référence à un serveur de la configuration `mcpServers` du parent) ou un enregistrement de configuration de serveur en ligne associant des noms de serveurs à des configurations.
1231 1265
1232```typescript theme={null}1266```typescript theme={null}
1233type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1267type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
1247| :- | :- | :- |1281| :- | :- | :- |
1248| `'user'` | Paramètres utilisateur globaux | `~/.claude/settings.json` |1282| `'user'` | Paramètres utilisateur globaux | `~/.claude/settings.json` |
1249| `'project'` | Paramètres de projet partagés (sous contrôle de version) | `.claude/settings.json` |1283| `'project'` | Paramètres de projet partagés (sous contrôle de version) | `.claude/settings.json` |
1250| `'local'` | Paramètres de projet locaux, ajoutés au gitignore lorsque Claude Code y enregistre un paramètre | `.claude/settings.local.json` |1284| `'local'` | Paramètres de projet locaux, ignorés par Git lorsque Claude Code y enregistre un paramètre | `.claude/settings.local.json` |
1251 1285
1252#### Comportement par défaut1286#### Comportement par défaut
1253 1287
1254Lorsque `settingSources` est omis ou `undefined`, `query()` charge les mêmes paramètres du système de fichiers que la CLI Claude Code : utilisateur, projet et local. Consultez [Ce que settingSources ne contrôle pas](https://code.claude.com/docs/fr/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) pour connaître les entrées lues indépendamment de cette option, et comment les désactiver.1288Lorsque `settingSources` est omis ou `undefined`, `query()` charge les mêmes paramètres du système de fichiers que la CLI Claude Code : utilisateur, projet et local. Consultez [Ce que settingSources ne contrôle pas](https://code.claude.com/docs/fr/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) pour connaître les entrées lues indépendamment de cette option et savoir comment les désactiver.
1255 1289
1256#### Pourquoi utiliser settingSources1290#### Pourquoi utiliser settingSources
1257 1291
1267});1301});
1268```1302```
1269 1303
1270**Charger uniquement des sources de paramètres spécifiques :**1304**Charger uniquement certaines sources de paramètres :**
1271 1305
1272```typescript theme={null}1306```typescript theme={null}
1273import { query } from "@anthropic-ai/claude-agent-sdk";1307import { query } from "@anthropic-ai/claude-agent-sdk";
1281});1315});
1282```1316```
1283 1317
1284Pour charger les instructions de projet CLAUDE.md, incluez `"project"` dans `settingSources`. Consultez [Modifier les prompts système](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#claude-md-files-for-project-level-instructions) pour savoir comment le chargement de CLAUDE.md interagit avec les options du prompt système.1318Pour charger les instructions de projet CLAUDE.md, incluez `"project"` dans `settingSources`. Consultez [Modifier les prompts système](https://code.claude.com/docs/fr/agent-sdk/modifying-system-prompts.md#claude-md-files-for-project-level-instructions) pour savoir comment le chargement de CLAUDE.md interagit avec les options de prompt système.
1285 1319
1286#### Priorité des paramètres1320#### Priorité des paramètres
1287 1321
1288Lorsque plusieurs sources sont chargées, les paramètres sont fusionnés selon cet ordre de priorité (de la plus haute à la plus basse) :1322Lorsque plusieurs sources sont chargées, les paramètres sont fusionnés selon cet ordre de priorité (de la plus élevée à la plus basse) :
1289 1323
12901. Paramètres locaux (`.claude/settings.local.json`)13241. Paramètres locaux (`.claude/settings.local.json`)
12912. Paramètres de projet (`.claude/settings.json`)13252. Paramètres de projet (`.claude/settings.json`)
12923. Paramètres utilisateur (`~/.claude/settings.json`)13263. Paramètres utilisateur (`~/.claude/settings.json`)
1293 1327
1294Les options programmatiques telles que `agents`, `allowedTools` et `settings` remplacent les paramètres utilisateur, projet et locaux du système de fichiers. Les paramètres de politique gérés ont priorité sur les options programmatiques.1328Les options programmatiques telles que `agents`, `allowedTools` et `settings` remplacent les paramètres utilisateur, projet et locaux du système de fichiers. Les paramètres de politique gérée ont priorité sur les options programmatiques.
1295 1329
1296### `PermissionMode`1330### `PermissionMode`
1297 1331
1309 1343
1310Type de fonction de permission personnalisée pour contrôler l'utilisation des outils.1344Type de fonction de permission personnalisée pour contrôler l'utilisation des outils.
1311 1345
1312La fonction est le remplacement, dans le SDK, de la demande de permission interactive : elle n'est invoquée que lorsque le [flux d'évaluation des permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated) aboutit à une demande. Les appels d'outils déjà approuvés par une entrée `allowedTools`, une règle d'autorisation des paramètres ou le mode de permission, comme `acceptEdits` ou `bypassPermissions`, ne l'invoquent jamais. Pour contrôler chaque appel d'outil, utilisez plutôt un [hook `PreToolUse`](https://code.claude.com/docs/fr/agent-sdk/hooks).1346Cette fonction est le remplaçant, dans le SDK, de la demande de permission interactive : elle n'est invoquée que lorsque le [flux d'évaluation des permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated) aboutit à une demande. Les appels d'outils déjà approuvés par une entrée `allowedTools`, une règle allow des paramètres ou le mode de permission, comme `acceptEdits` ou `bypassPermissions`, ne l'invoquent jamais. Pour contrôler chaque appel d'outil, utilisez plutôt un [hook `PreToolUse`](https://code.claude.com/docs/fr/agent-sdk/hooks).
1313 1347
1314Une règle d'autorisation ne pré-approuve pas les [actions qu'aucun mode n'approuve automatiquement](https://code.claude.com/docs/fr/permission-modes.md#actions-no-mode-auto-approves) ; consultez [Comment les permissions sont évaluées](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated) pour savoir lesquelles atteignent le callback et ce qui se passe en mode `dontAsk` et `auto`.1348Une règle allow ne pré-approuve pas les [actions qu'aucun mode n'approuve automatiquement](https://code.claude.com/docs/fr/permission-modes.md#actions-no-mode-auto-approves) ; consultez [Comment les permissions sont évaluées](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated) pour savoir lesquelles atteignent le callback et ce qui se passe en mode `dontAsk` et `auto`.
1315 1349
1316```typescript theme={null}1350```typescript theme={null}
1317type CanUseTool = (1351type CanUseTool = (
1334 1368
1335| Option | Type | Description |1369| Option | Type | Description |
1336| :- | :- | :- |1370| :- | :- | :- |
1337| `signal` | `AbortSignal` | Signalé si l'opération doit être abandonnée |1371| `signal` | `AbortSignal` | Signalé si l'opération doit être annulée |
1338| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Mises à jour de permissions suggérées afin que l'utilisateur ne soit plus sollicité pour cet outil. Les demandes Bash incluent une suggestion avec la [destination](#permissionupdatedestination) `localSettings`, de sorte que la renvoyer dans `updatedPermissions` écrit la règle dans `.claude/settings.local.json` et la conserve d'une session à l'autre. |1372| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Mises à jour de permissions suggérées pour que l'utilisateur ne soit plus sollicité pour cet outil. Les demandes Bash incluent une suggestion avec la [destination](#permissionupdatedestination) `localSettings` ; la renvoyer dans `updatedPermissions` écrit donc la règle dans `.claude/settings.local.json` et la conserve d'une session à l'autre. |
1339| `blockedPath` | `string` | Le chemin de fichier qui a déclenché la demande de permission, le cas échéant |1373| `blockedPath` | `string` | Le chemin de fichier qui a déclenché la demande de permission, le cas échéant |
1340| `mcpServer` | `{ name: string; source: string }` | Pour un outil `mcp__*`, le serveur MCP qui le fournit et l'origine de la définition de ce serveur, avec les champs de [`McpServerProvenance`](#mcpserverprovenance). Absent pour les autres outils. Nécessite Agent SDK v0.3.274 ou ultérieur |1374| `mcpServer` | `{ name: string; source: string }` | Pour un outil `mcp__*`, le serveur MCP qui le fournit et l'origine de la définition de ce serveur, avec les champs de [`McpServerProvenance`](#mcpserverprovenance). Absent pour les autres outils. Nécessite l'Agent SDK v0.3.274 ou une version ultérieure |
1341| `decisionReason` | `string` | Explique pourquoi cette demande de permission a été déclenchée |1375| `decisionReason` | `string` | Explique pourquoi cette demande de permission a été déclenchée |
1342| `defaultToNo` | `boolean` | Lorsque `true`, une seule frappe accidentelle ne doit pas approuver cette demande : ouvrez votre demande sur son option de refus, ne présélectionnez pas l'approbation et ne proposez aucun raccourci d'approbation à une touche. Nécessite Agent SDK v0.3.268 ou ultérieur |1376| `defaultToNo` | `boolean` | Lorsque `true`, une seule frappe accidentelle ne doit pas approuver cette demande : ouvrez votre invite sur son option de refus, ne présélectionnez pas l'approbation et ne proposez aucun raccourci d'approbation à une touche. Nécessite l'Agent SDK v0.3.268 ou une version ultérieure |
1343| `suppressAlwaysAllowRule` | `boolean` | Lorsque `true`, ne proposez pas de choix d'autorisation permanente pour cette demande. Nécessite Agent SDK v0.3.268 ou ultérieur |1377| `suppressAlwaysAllowRule` | `boolean` | Lorsque `true`, ne proposez pas de choix « toujours autoriser » persistant pour cette demande. Nécessite l'Agent SDK v0.3.268 ou une version ultérieure |
1344| `toolUseID` | `string` | Identifiant unique de cet appel d'outil spécifique au sein du message de l'assistant |1378| `toolUseID` | `string` | Identifiant unique de cet appel d'outil spécifique au sein du message de l'assistant |
1345| `agentID` | `string` | En cas d'exécution au sein d'un sous-agent, l'ID du sous-agent |1379| `agentID` | `string` | En cas d'exécution au sein d'un sous-agent, l'ID du sous-agent |
1346| `requestId` | `string` | Le `request_id` de l'enveloppe `control_request`. Une `control_response` que votre application envoie en dehors du SDK, comme un HTTP POST signé, doit reprendre cette valeur afin que le processus Claude Code puisse faire correspondre la réponse à la requête |1380| `requestId` | `string` | Le `request_id` de l'enveloppe `control_request`. Une `control_response` que votre application envoie en dehors du SDK, comme un POST HTTP signé, doit renvoyer cette valeur afin que le processus Claude Code puisse faire correspondre la réponse à la requête |
1347 1381
1348Le callback résout normalement la requête en renvoyant un [`PermissionResult`](#permissionresult), que le SDK réécrit sur son transport en tant que `control_response`. Renvoyez `null` uniquement lorsque votre application a déjà envoyé la `control_response` pour cette requête via son propre canal, en reprenant `requestId` ; le SDK ignore alors l'écriture de la réponse sur son transport. Renvoyer `null` dans tout autre cas bloque indéfiniment l'appel d'outil, car aucune `control_response` n'est jamais envoyée et les demandes de permission n'expirent pas.1382Le callback résout normalement la requête en renvoyant un [`PermissionResult`](#permissionresult), que le SDK réécrit sur son transport en tant que `control_response`. Ne renvoyez `null` que lorsque votre application a déjà envoyé la `control_response` de cette requête par son propre canal, en renvoyant `requestId` ; le SDK n'écrit alors pas la réponse sur son transport. Renvoyer `null` dans tout autre cas laisse l'appel d'outil bloqué indéfiniment, car aucune `control_response` n'est jamais envoyée et les demandes de permission n'expirent pas.
1349 1383
1350L'option `requestId` et la valeur de retour `null` nécessitent Claude Code v2.1.199 ou ultérieur.1384L'option `requestId` et la valeur de retour `null` nécessitent Claude Code v2.1.199 ou une version ultérieure.
1351 1385
1352### `PermissionResult`1386### `PermissionResult`
1353 1387
1383 1417
1384| Champ | Type | Description |1418| Champ | Type | Description |
1385| :- | :- | :- |1419| :- | :- | :- |
1386| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Active le champ `preview` sur les options [`AskUserQuestion`](https://code.claude.com/docs/fr/agent-sdk/user-input#question-format) et définit le format de son contenu. Lorsqu'il n'est pas défini, Claude n'émet pas d'aperçus |1420| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Active le champ `preview` sur les options d'[`AskUserQuestion`](https://code.claude.com/docs/fr/agent-sdk/user-input#question-format) et définit le format de son contenu. Lorsqu'il n'est pas défini, Claude n'émet pas d'aperçus |
1387 1421
1388### `McpServerConfig`1422### `McpServerConfig`
1389 1423
1430 1464
1431#### `McpSdkServerConfigWithInstance`1465#### `McpSdkServerConfigWithInstance`
1432 1466
1467La configuration d'un serveur MCP en processus, c'est-à-dire un serveur que [`createSdkMcpServer()`](#createsdkmcpserver) crée et qui s'exécute dans le processus de votre application. Il s'agit de l'objet renvoyé par `createSdkMcpServer()`, auquel s'ajoute une liste facultative `tools` d'entrées [`McpServerToolPolicy`](#mcpservertoolpolicy) que vous ajoutez vous-même. Pour exiger une approbation pour les appels à l'un des outils du serveur, ou pour les refuser, ajoutez une entrée qui nomme l'outil.
1468
1433```typescript theme={null}1469```typescript theme={null}
1434type McpSdkServerConfigWithInstance = {1470type McpSdkServerConfigWithInstance = {
1435 type: "sdk";1471 type: "sdk";
1436 name: string;1472 name: string;
1437 timeout?: number;1473 timeout?: number;
1474 tools?: McpServerToolPolicy[];
1438 instance: McpServer;1475 instance: McpServer;
1439};1476};
1440```1477```
1441 1478
1479Pour définir une politique, décomposez l'objet renvoyé par `createSdkMcpServer()` dans un nouvel objet de `mcpServers` et ajoutez la liste `tools` à ce nouvel objet. L'option `tools` de `createSdkMcpServer()` elle-même est une liste différente, qui contient les définitions d'outils et n'accepte pas d'entrées de politique. La liste de politiques nécessite l'Agent SDK v0.3.301 ou une version ultérieure, et [`McpServerToolPolicy`](#mcpservertoolpolicy) décrit l'effet de chaque valeur de `permission_policy`.
1480
1481Cet exemple pré-approuve tous les outils du serveur `records` avec un caractère générique `allowedTools`, puis marque `delete_record` comme `always_ask` afin que ses appels soient malgré tout transmis à `canUseTool`. Avec l'annotation `destructiveHint: true`, l'appel atteint toujours le callback si la session s'exécute en mode `auto`, où le [classifieur](https://code.claude.com/docs/fr/permission-modes.md#eliminate-prompts-with-auto-mode) du mode auto pourrait sinon l'approuver.
1482
1483```typescript theme={null}
1484import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
1485import { z } from "zod";
1486
1487const deleteRecord = tool(
1488 "delete_record",
1489 "Delete a customer record by ID",
1490 { id: z.string() },
1491 async ({ id }) => ({ content: [{ type: "text", text: `Deleted record ${id}` }] }),
1492 { annotations: { destructiveHint: true } }
1493);
1494
1495const records = createSdkMcpServer({ name: "records", tools: [deleteRecord] });
1496
1497for await (const message of query({
1498 prompt: "Delete customer record 42",
1499 options: {
1500 mcpServers: {
1501 // Spread the returned config and add the policy list beside it
1502 records: {
1503 ...records,
1504 tools: [{ name: "delete_record", permission_policy: "always_ask" as const }]
1505 }
1506 },
1507 allowedTools: ["mcp__records__*"],
1508 canUseTool: async (toolName, input) => {
1509 console.log(`Approval requested for ${toolName}`);
1510 return { behavior: "allow", updatedInput: input };
1511 }
1512 }
1513})) {
1514 if (message.type === "result" && message.subtype === "success") {
1515 console.log(message.result);
1516 }
1517}
1518```
1519
1520Lorsque Claude appelle l'outil, le script affiche `Approval requested for mcp__records__delete_record` avant l'exécution de l'outil `delete_record`, bien que l'entrée `allowedTools` aurait sinon approuvé l'appel.
1521
1522Pour modifier ou lever la politique d'un outil pendant l'exécution de la session, passez la configuration du serveur avec une nouvelle valeur `tools` à [`setMcpServers()`](#mcpsetserversresult). La valeur `tools` que vous passez prend effet à partir du prochain appel de Claude aux outils de ce serveur :
1523
1524* **Une liste avec des entrées** : les entrées remplacent les politiques actuelles
1525* **Une liste vide** : toutes les politiques du serveur sont supprimées
1526* **Aucune clé `tools`** : les politiques actuelles sont conservées
1527
1528Incluez dans cet appel vos autres serveurs en processus et tout serveur ajouté par un appel `setMcpServers()` antérieur, faute de quoi l'appel les déconnecte.
1529
1530#### `McpServerToolPolicy`
1531
1532Une entrée de la liste `tools` d'un [`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance), qui nomme l'un des outils du serveur et définit la politique de permission pour les appels à cet outil. La liste nécessite l'Agent SDK v0.3.301 ou une version ultérieure et Claude Code v2.1.301 ou une version ultérieure. Un exécutable Claude Code plus ancien, comme un exécutable que vous désignez avec `pathToClaudeCodeExecutable`, ignore la liste. `always_ask` et `always_deny` ne sont alors pas appliqués, et chaque appel passe par le [flux de permissions](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated).
1533
1534```typescript theme={null}
1535type McpServerToolPolicy = {
1536 name: string;
1537 permission_policy?: "always_allow" | "always_ask" | "always_deny";
1538 org_max_permission?: "allow" | "ask" | "blocked";
1539};
1540```
1541
1542| Champ | Type | Description |
1543| :- | :- | :- |
1544| `name` | `string` | Le nom brut de l'outil tel que passé à [`tool()`](#tool), sans le préfixe `mcp__<server>__` |
1545| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | La politique d'approbation pour les appels de l'outil, [`always_ask` ou `always_deny`](#permission-policy-values). `always_allow` est ignoré sur un serveur en processus : pour pré-approuver un outil, indiquez-le plutôt dans [`allowedTools`](#options) |
1546| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | Un plafond par outil défini par un administrateur de l'organisation. Ignoré sur un serveur en processus ; laissez-le donc non défini |
1547
1548##### Valeurs de `permission_policy`
1549
1550Choisissez `always_ask` pour approuver vous-même chaque appel, ou `always_deny` pour bloquer complètement l'outil :
1551
1552* **`always_ask`** : chaque appel à l'outil [nécessite une approbation](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated), même si une entrée `allowedTools` ou une règle allow le couvre. L'appel est transmis à votre callback `canUseTool` ou à votre outil [`permissionPromptToolName`](#options), sauf s'il est réglé auparavant. Un [mod](https://code.claude.com/docs/fr/plugins/mods/overview.md) dans un plugin que vous chargez [peut l'approuver en premier](https://code.claude.com/docs/fr/permissions.md#precedence-among-rules-hooks-and-mods). Sinon, en mode `dontAsk` il est refusé, et en [mode `auto`, `plan` et `bypassPermissions`](#permission-modes-that-can-approve-an-always_ask-call) il peut être approuvé avant d'atteindre votre callback
1553* **`always_deny`** : un appel à l'outil [est refusé](https://code.claude.com/docs/fr/agent-sdk/permissions.md#how-permissions-are-evaluated) dans tous les modes de permission, y compris `bypassPermissions`, mais un mod dans un plugin que vous chargez [peut tout de même l'approuver](https://code.claude.com/docs/fr/permissions.md#precedence-among-rules-hooks-and-mods)
1554
1555Si vous ne passez ni `canUseTool` ni `permissionPromptToolName`, ou si vous définissez [`permissionPrompts`](#options) sur `'none'`, un appel `always_ask` qui n'est pas réglé auparavant est refusé, sauf si un [hook `PermissionRequest`](https://code.claude.com/docs/fr/hooks#permissionrequest) l'autorise.
1556
1557##### Modes de permission pouvant approuver un appel `always_ask`
1558
1559En mode `auto`, `plan` et `bypassPermissions`, un appel à un outil marqué [`always_ask`](#permission-policy-values) peut être approuvé avant d'atteindre votre callback `canUseTool`. Repérez le mode de votre session dans cette liste pour savoir quand cette approbation a lieu et ce qu'il faut définir pour que l'appel atteigne malgré tout votre callback :
1560
1561* **`auto`** : le [classifieur](https://code.claude.com/docs/fr/permission-modes.md#eliminate-prompts-with-auto-mode) du mode auto examine l'appel et peut l'autoriser. Pour que chaque appel atteigne votre callback en mode `auto`, définissez `destructiveHint: true` dans les [annotations](#toolannotations) de l'outil
1562* **`plan`** : tant que le [mode auto est disponible](https://code.claude.com/docs/fr/permission-modes.md#eliminate-prompts-with-auto-mode) pour la session, les appels à un outil `always_ask` annoté `readOnlyHint: true` sont transmis au classifieur du mode auto, qui peut les autoriser. Les appels aux autres outils `always_ask` atteignent votre callback. Pour que les appels d'un outil en lecture seule atteignent également votre callback, ajoutez `destructiveHint: true` aux annotations de cet outil en plus de `readOnlyHint: true`. Vous pouvez aussi définir [`useAutoModeDuringPlan`](https://code.claude.com/docs/fr/settings-reference#useautomodeduringplan) sur `false`, ce qui désactive le classifieur pendant la planification
1563* **`bypassPermissions`** : lorsque la variable d'environnement [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/fr/env-vars#variables) vaut `true`, comme c'est le cas dans une [session cloud](https://code.claude.com/docs/fr/claude-code-on-the-web.md), l'appel est approuvé sans votre callback, quelles que soient les annotations de l'outil. Partout ailleurs, l'appel atteint votre callback. Pour qu'il atteigne aussi votre callback dans une session cloud, exécutez plutôt la session en mode `default` ou `acceptEdits`
1564
1565Définissez explicitement `destructiveHint` sur `true` en mode `auto` et `plan`. Pour les appels `always_ask`, Claude Code interprète un `destructiveHint` non défini comme `false`, bien que la valeur par défaut indiquée dans [`ToolAnnotations`](#toolannotations) soit `true`.
1566
1442#### `McpClaudeAIProxyServerConfig`1567#### `McpClaudeAIProxyServerConfig`
1443 1568
1444```typescript theme={null}1569```typescript theme={null}
1464| Champ | Type | Description |1589| Champ | Type | Description |
1465| :- | :- | :- |1590| :- | :- | :- |
1466| `type` | `'local'` | Doit être `'local'` (seuls les plugins locaux sont actuellement pris en charge) |1591| `type` | `'local'` | Doit être `'local'` (seuls les plugins locaux sont actuellement pris en charge) |
1467| `path` | `string` | Chemin absolu ou relatif vers le répertoire du plugin |1592| `path` | `string` | Chemin vers le répertoire du plugin. Un chemin relatif est résolu par rapport à l'option [`cwd`](#options) au démarrage de la session. Le chemin doit être absolu lorsque vous chargez le plugin en cours de session avec [`addPlugins`](#load-more-plugin-folders-with-addplugins) |
1468| `skipMcpDiscovery` | `boolean` | Lorsque `true`, le SDK charge les skills, hooks, agents et commandes de ce plugin, mais ne lit pas son `.mcp.json` ni les `mcpServers` de son manifeste. Définissez cette option lorsque votre application gère les connexions MCP du plugin. |1593| `skipMcpDiscovery` | `boolean` | Lorsque `true`, le SDK charge les skills, hooks, agents et commandes de ce plugin, mais ne lit pas son `.mcp.json` ni les `mcpServers` de son manifeste. Définissez-le lorsque votre application gère les connexions MCP du plugin. |
1469 1594
1470**Exemple :**1595**Exemple :**
1471 1596
5076};5201};
5077```5202```
5078 5203
5079`source` indique la provenance de la définition du serveur, avec les mêmes valeurs et la même règle de confiance que le `source` de [`McpServerProvenance`](#mcpserverprovenance). Le champ nécessite l'Agent SDK v0.3.274 ou version ultérieure et est absent dans les versions antérieures.5204Utilisez `source` pour décider du degré de confiance à accorder à un serveur, et le `_meta` de chaque entrée `tools` pour trouver une ressource d'interface utilisateur que le serveur a associée à cet outil :
5205
5206* **`source`** : la provenance de la définition du serveur, avec les mêmes valeurs que le `source` de [`McpServerProvenance`](#mcpserverprovenance). Fondez vos décisions de confiance sur `source` plutôt que sur `name`, car seul votre propre serveur in-process indique `sdk`, quel que soit le nom sous lequel un autre serveur est enregistré. Si vous ne reconnaissez pas une valeur de `source`, traitez ce serveur comme vous traitez tout serveur dont le `source` n'est pas `sdk`. Nécessite l'Agent SDK v0.3.274 ou version ultérieure
5207* **`_meta`** : l'objet `ui` et la chaîne `ui/resourceUri` issus du `_meta` que le serveur a déclaré pour l'outil. Claude Code retient toutes les autres clés de `_meta`. `ui/resourceUri` est une ancienne graphie de premier niveau de `ui.resourceUri`. Lorsque le serveur associe une [ressource d'interface MCP Apps](https://code.claude.com/docs/fr/mcp.md#reference-mcp-resources) à l'outil, `ui.resourceUri` ou `ui/resourceUri` contient l'URI `ui://` de la ressource. Récupérez cette URI avec [`readMcpResource()`](#query-object) et affichez la ressource dans votre application. Nécessite l'Agent SDK v0.3.280 ou version ultérieure
5208
5209Claude Code n'envoie `_meta` que lorsque le tableau [`capabilities`](#sdksystemmessage) du message `system` de sous-type `init` inclut `mcp_tool_ui_meta_v1`. Vous n'activez pas `mcp_tool_ui_meta_v1` vous-même.
5210
5211#### Lorsque le `_meta.ui` d'un outil ne contient que `visibility`
5212
5213Si votre serveur déclare `ui.resourceUri` pour un outil mais que le `_meta.ui` reçu par votre application ne contient que `visibility`, l'objet `ui` envoyé par le serveur a échoué à l'une des vérifications de Claude Code. Claude Code vérifie `ui` et `ui/resourceUri` séparément ; une clé peut donc atteindre votre application alors que l'autre échoue. Comparez le `_meta` de la réponse `tools/list` de votre serveur aux vérifications de chaque clé :
5214
5215* **`ui`** : atteint votre application sans modification, y compris tout membre autre que `resourceUri` et `visibility`, si les trois vérifications réussissent :
5216
5217 * `resourceUri` est absent, ou est une chaîne qui commence par `ui://`
5218 * `visibility` est absent, ou ne répertorie que `"model"` et `"app"`
5219 * L'objet entier fait au plus 4 096 caractères une fois sérialisé en JSON
5220
5221 Si l'une des vérifications échoue, votre application reçoit au plus un `ui` dont le seul membre est un tableau `visibility` contenant les entrées `"model"` et `"app"` que le serveur a répertoriées.
5222* **`ui/resourceUri`** : atteint votre application s'il s'agit d'une chaîne qui commence par `ui://` et fait au plus 4 096 caractères. Sinon, Claude Code la supprime
5080 5223
5081`_meta` sur une entrée `tools` contient les membres MCP Apps du `_meta` de cet outil, afin que votre application puisse trouver la ressource `ui://` à afficher avec [`readMcpResource()`](#query-object). Claude Code transmet l'objet `ui` et la chaîne plate dépréciée `ui/resourceUri`, et retient toutes les autres clés. Dans `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 est transmis sans modification. Claude Code supprime l'une ou l'autre clé lorsque la valeur est mal formée, et omet `_meta` pour un outil qui ne déclare ni l'une ni l'autre. Le champ n'est présent que lorsque les [`capabilities`](#sdksystemmessage) du message d'initialisation incluent `mcp_tool_ui_meta_v1`, et nécessite l'Agent SDK TypeScript v0.3.280 ou version ultérieure.5224Lorsqu'il ne reste à Claude Code aucun membre `ui` ni aucune chaîne `ui/resourceUri` à envoyer, l'entrée `tools` n'a aucun `_meta`.
5082 5225
5083### `McpServerStatusConfig`5226### `McpServerStatusConfig`
5084 5227
5313Lorsque vous appelez `setMcpServers()`, Claude Code applique ces règles :5456Lorsque vous appelez `setMcpServers()`, Claude Code applique ces règles :
5314 5457
5315* **Serveurs que l'appel ne nomme pas** : en dehors d'une [session cloud](https://code.claude.com/docs/fr/claude-code-on-the-web.md), Claude Code déconnecte les serveurs ajoutés par un appel `setMcpServers()` antérieur ainsi que les serveurs SDK in-process, et les répertorie dans `removed`. Les autres serveurs continuent de fonctionner et ne sont pas répertoriés dans `removed`, parmi lesquels les serveurs stdio, HTTP et SSE de l'option [`mcpServers`](#options), les serveurs issus des fichiers de paramètres et les serveurs fournis par des plugins.5458* **Serveurs que l'appel ne nomme pas** : en dehors d'une [session cloud](https://code.claude.com/docs/fr/claude-code-on-the-web.md), Claude Code déconnecte les serveurs ajoutés par un appel `setMcpServers()` antérieur ainsi que les serveurs SDK in-process, et les répertorie dans `removed`. Les autres serveurs continuent de fonctionner et ne sont pas répertoriés dans `removed`, parmi lesquels les serveurs stdio, HTTP et SSE de l'option [`mcpServers`](#options), les serveurs issus des fichiers de paramètres et les serveurs fournis par des plugins.
5316* **Serveurs que l'appel nomme** : Claude Code remplace un serveur stdio, HTTP ou SSE ajouté par un appel `setMcpServers()` antérieur uniquement lorsque sa configuration diffère de celle que vous avez transmise. Un serveur SDK in-process déjà enregistré sous ce nom reste tel quel ; pour en remplacer un, omettez-le d'un appel et ajoutez-le dans le suivant.5459* **Serveurs stdio, HTTP et SSE ajoutés par un appel `setMcpServers()` antérieur** : en dehors d'une session cloud, un serveur que vous nommez à nouveau avec une configuration identique conserve sa connexion et ses outils. Il n'apparaît ni dans `added` ni dans `removed`. Si vous transmettez une configuration modifiée, Claude Code reconnecte le serveur avec cette configuration et le répertorie dans `added`, pas dans `removed`.
5460* **Serveurs stdio, HTTP et SSE que l'appel nomme et qu'aucun appel antérieur n'a ajoutés** : en dehors d'une session cloud, Claude Code ajoute le serveur et le répertorie dans `added`, ou dans `errors` s'il refuse le serveur.
5461* **Serveurs SDK in-process que l'appel nomme** : un serveur déjà enregistré via `mcpServers` ou un appel antérieur conserve son instance en cours d'exécution et son délai d'expiration. Si vous transmettez une [liste de politiques `tools`](#mcpsdkserverconfigwithinstance) pour celui-ci, même vide, vous remplacez ses politiques ; sinon, elles restent inchangées. Pour exécuter une nouvelle instance en dehors d'une session cloud, omettez le serveur d'un appel et nommez-le dans le suivant.
5317* **Serveurs intégrés démarrés par la CLI au lancement** : si l'appel en nomme un, Claude Code supprime cette entrée et l'indique dans `errors`.5462* **Serveurs intégrés démarrés par la CLI au lancement** : si l'appel en nomme un, Claude Code supprime cette entrée et l'indique dans `errors`.
5318* **Serveurs stdio, HTTP ou SSE qui portent le même nom qu'un serveur d'une portée d'installation MCP telle que `.mcp.json`** : sous ce nom, la session utilise les outils de votre serveur plutôt que ceux du [serveur de la portée d'installation](https://code.claude.com/docs/fr/mcp.md#mcp-installation-scopes). Avant Claude Code v2.1.305, Claude Code pouvait déconnecter votre serveur et connecter le serveur de la portée d'installation lorsque votre application [rechargeait les plugins](#query-object).5463* **Serveurs stdio, HTTP ou SSE qui portent le même nom qu'un serveur d'une portée d'installation MCP telle que `.mcp.json`** : sous ce nom, la session utilise les outils de votre serveur plutôt que ceux du [serveur de la portée d'installation](https://code.claude.com/docs/fr/mcp.md#mcp-installation-scopes). Avant Claude Code v2.1.305, Claude Code pouvait déconnecter votre serveur et connecter le serveur de la portée d'installation lorsque votre application [rechargeait les plugins](#query-object).
5319 5464
5800 5945
5801Les typages publiés du SDK déclarent `SDKConversationResetMessage` dans Claude Code v2.1.203 et versions ultérieures. Avant la v2.1.203, `SDKMessage` référençait le type sans le déclarer ; le rétrécissement de type sur `type === "conversation_reset"` échouait donc à la vérification des types lorsque `skipLibCheck` était désactivé.5946Les typages publiés du SDK déclarent `SDKConversationResetMessage` dans Claude Code v2.1.203 et versions ultérieures. Avant la v2.1.203, `SDKMessage` référençait le type sans le déclarer ; le rétrécissement de type sur `type === "conversation_reset"` échouait donc à la vérification des types lorsque `skipLibCheck` était désactivé.
5802 5947
5948### `BUILTIN_TOOL_NAMES` et `LEGACY_TOOL_NAME_ALIASES`
5949
5950Utilisez ces deux constantes pour vérifier les noms d'outils saisis par les utilisateurs de votre application. Toutes deux orthographient chaque nom de la manière dont vous l'écrivez dans les règles de permission, les matchers de hooks et les options `tools` et `disallowedTools`. Importez-les depuis `@anthropic-ai/claude-agent-sdk` ou depuis `@anthropic-ai/claude-agent-sdk/core`. Elles nécessitent l'Agent SDK v0.3.301 ou version ultérieure et sont en version alpha.
5951
5952Les déclarations de types du SDK attribuent à `BUILTIN_TOOL_NAMES` un type tuple en lecture seule et à `LEGACY_TOOL_NAME_ALIASES` un type record de chaîne à chaîne :
5953
5954```typescript theme={null}
5955const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];
5956const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
5957```
5958
5959* **`BUILTIN_TOOL_NAMES`** : les noms des outils intégrés de Claude Code par ordre alphabétique, comme `Agent`, `Bash` et `Read`. Les noms d'outils MCP ne sont pas inclus. Comme le type est un tuple de littéraux de chaîne, `(typeof BUILTIN_TOOL_NAMES)[number]` vous donne un type union des noms
5960* **`LEGACY_TOOL_NAME_ALIASES`** : les anciens noms d'outils que les règles de permission, les matchers de hooks et les options `tools` et `disallowedTools` acceptent toujours. Chaque clé est un ancien nom et sa valeur est le nom actuel : par exemple, `Task` correspond à `Agent`, et `KillShell` et `KillBash` correspondent à `TaskStop`
5961
5962Vous pouvez confirmer un nom avec l'un ou l'autre de deux tests : `BUILTIN_TOOL_NAMES` l'inclut, ou `Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name)` renvoie `true`. Un nom qui échoue aux deux peut tout de même être valide, car `BUILTIN_TOOL_NAMES` omet les outils MCP et certains outils intégrés. Si vous construisez une liste de refus à partir de `BUILTIN_TOOL_NAMES`, Claude peut toujours utiliser les outils que la constante omet. Pour refuser tous les outils, définissez plutôt [`disallowedTools: ["*"]`](https://code.claude.com/docs/fr/agent-sdk/permissions#allow-and-deny-rules).
5963
5964Trouver un nom dans `BUILTIN_TOOL_NAMES` ne vous indique pas que la session dispose de cet outil : `TodoWrite` est répertorié bien qu'il soit [désactivé par défaut](https://code.claude.com/docs/fr/tools-reference.md). Pour savoir de quels outils dispose une session, lisez le tableau `tools` de son [`SDKSystemMessage`](#sdksystemmessage). Ce tableau inclut les outils MCP et répertorie l'outil Agent sous le nom `Task` ; faites donc correspondre chaque nom via `LEGACY_TOOL_NAME_ALIASES` avant de le comparer à `BUILTIN_TOOL_NAMES`.
5965
5803### `AbortError`5966### `AbortError`
5804 5967
5805Classe d'erreur personnalisée pour les opérations d'abandon.5968Classe d'erreur personnalisée pour les opérations d'abandon.
