Documentation — Spybara

agent-sdk/agent-loop.md +395 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Fonctionnement de la boucle d'agent

7> Comprenez le cycle de vie des messages, l'exécution des outils, la fenêtre de contexte et l'architecture qui alimentent vos agents SDK.

9Le SDK Agent vous permet d'intégrer la boucle d'agent autonome de Claude Code dans vos propres applications. Le SDK est un package autonome qui vous donne un contrôle programmatique sur les outils, les permissions, les limites de coûts et la sortie. Vous n'avez pas besoin d'avoir l'interface de ligne de commande Claude Code installée pour l'utiliser.

11Lorsque vous démarrez un agent, le SDK exécute la même [boucle d'exécution qui alimente Claude Code](/fr/how-claude-code-works#the-agentic-loop) : Claude évalue votre prompt, appelle les outils pour agir, reçoit les résultats et répète jusqu'à ce que la tâche soit terminée. Cette page explique ce qui se passe à l'intérieur de cette boucle afin que vous puissiez construire, déboguer et optimiser vos agents efficacement.

13## La boucle en un coup d'œil

15Chaque session d'agent suit le même cycle :

17<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="Boucle d'agent : le prompt entre, Claude évalue, se divise en appels d'outils ou réponse finale" width="680" height="150" data-path="images/agent-loop-diagram.svg" />

191. **Recevoir le prompt.** Claude reçoit votre prompt, ainsi que le prompt système, les définitions d'outils et l'historique de conversation. Le SDK produit un [`SystemMessage`](#message-types) avec le sous-type `"init"` contenant les métadonnées de session.

202. **Évaluer et répondre.** Claude évalue l'état actuel et détermine comment procéder. Il peut répondre avec du texte, demander un ou plusieurs appels d'outils, ou les deux. Le SDK produit un [`AssistantMessage`](#message-types) contenant le texte et toutes les demandes d'appels d'outils.

213. **Exécuter les outils.** Le SDK exécute chaque outil demandé et collecte les résultats. Chaque ensemble de résultats d'outils est renvoyé à Claude pour la décision suivante. Vous pouvez utiliser des [hooks](/fr/agent-sdk/hooks) pour intercepter, modifier ou bloquer les appels d'outils avant qu'ils ne s'exécutent.

224. **Répéter.** Les étapes 2 et 3 se répètent en cycle. Chaque cycle complet est un tour. Claude continue à appeler les outils et à traiter les résultats jusqu'à ce qu'il produise une réponse sans appels d'outils.

235. **Retourner le résultat.** Le SDK produit un [`AssistantMessage`](#message-types) final avec la réponse textuelle (sans appels d'outils), suivi d'un [`ResultMessage`](#message-types) avec le texte final, l'utilisation des tokens, le coût et l'ID de session.

25Une question rapide (« quels fichiers sont ici ? ») peut prendre un ou deux tours d'appel de `Glob` et de réponse avec les résultats. Une tâche complexe (« refactorisez le module d'authentification et mettez à jour les tests ») peut enchaîner des dizaines d'appels d'outils sur plusieurs tours, en lisant des fichiers, en modifiant du code et en exécutant des tests, avec Claude ajustant son approche en fonction de chaque résultat.

27## Tours et messages

29Un tour est un aller-retour dans la boucle : Claude produit une sortie qui inclut des appels d'outils, le SDK exécute ces outils, et les résultats sont renvoyés à Claude automatiquement. Cela se produit sans rendre le contrôle à votre code. Les tours continuent jusqu'à ce que Claude produise une sortie sans appels d'outils, auquel point la boucle se termine et le résultat final est livré.

31Considérez ce qu'une session complète pourrait ressembler pour le prompt « Corrigez les tests défaillants dans auth.ts ».

33D'abord, le SDK envoie votre prompt à Claude et produit un [`SystemMessage`](#message-types) avec les métadonnées de session. Ensuite, la boucle commence :

351. **Tour 1 :** Claude appelle `Bash` pour exécuter `npm test`. Le SDK produit un [`AssistantMessage`](#message-types) avec l'appel d'outil, exécute la commande, puis produit un [`UserMessage`](#message-types) avec la sortie (trois défaillances).

362. **Tour 2 :** Claude appelle `Read` sur `auth.ts` et `auth.test.ts`. Le SDK retourne le contenu des fichiers et produit un `AssistantMessage`.

373. **Tour 3 :** Claude appelle `Edit` pour corriger `auth.ts`, puis appelle `Bash` pour relancer `npm test`. Les trois tests réussissent. Le SDK produit un `AssistantMessage`.

384. **Tour final :** Claude produit une réponse textuelle uniquement sans appels d'outils : « Correction du bug d'authentification, les trois tests réussissent maintenant. » Le SDK produit un `AssistantMessage` final avec ce texte, puis un [`ResultMessage`](#message-types) avec le même texte plus le coût et l'utilisation.

40C'était quatre tours : trois avec des appels d'outils, un final avec réponse textuelle uniquement.

42Vous pouvez limiter la boucle avec `max_turns` / `maxTurns`, qui compte uniquement les tours d'utilisation d'outils. Par exemple, `max_turns=2` dans la boucle ci-dessus aurait arrêté avant l'étape d'édition. Vous pouvez également utiliser `max_budget_usd` / `maxBudgetUsd` pour limiter les tours en fonction d'un seuil de dépense.

44Sans limites, la boucle s'exécute jusqu'à ce que Claude termine de lui-même, ce qui est correct pour les tâches bien délimitées mais peut s'exécuter longtemps sur des prompts ouverts (« améliorez cette base de code »). Définir un budget est une bonne valeur par défaut pour les agents de production. Voir [Tours et budget](#turns-and-budget) ci-dessous pour la référence des options.

46## Types de messages

48Lorsque la boucle s'exécute, le SDK produit un flux de messages. Chaque message porte un type qui vous indique à quel stade de la boucle il provient. Les cinq types principaux sont :

50* **`SystemMessage` :** événements du cycle de vie de la session. Le champ `subtype` les distingue : `"init"` est le premier message (métadonnées de session), et `"compact_boundary"` se déclenche après [compaction](#automatic-compaction). En TypeScript, la limite de compaction est son propre type [`SDKCompactBoundaryMessage`](/fr/agent-sdk/typescript#sdkcompactboundarymessage) plutôt qu'un sous-type de `SDKSystemMessage`.

51* **`AssistantMessage` :** émis après chaque réponse de Claude, y compris la réponse textuelle finale. Contient les blocs de contenu textuel et les blocs d'appels d'outils de ce tour.

52* **`UserMessage` :** émis après chaque exécution d'outil avec le résultat d'outil renvoyé à Claude. Également émis pour toute entrée utilisateur que vous diffusez en boucle.

53* **`StreamEvent` :** émis uniquement lorsque les messages partiels sont activés. Contient les événements de diffusion API bruts (deltas de texte, chunks d'entrée d'outil). Voir [Réponses en flux](/fr/agent-sdk/streaming-output).

54* **`ResultMessage` :** marque la fin de la boucle d'agent. Contient le résultat textuel final, l'utilisation des tokens, le coût et l'ID de session. Vérifiez le champ `subtype` pour déterminer si la tâche a réussi ou a atteint une limite. Un petit nombre d'événements système de fin, tels que `prompt_suggestion`, peuvent arriver après, donc itérez le flux jusqu'à la fin plutôt que de vous arrêter au résultat. Voir [Gérer le résultat](#handle-the-result).

56Ces cinq types couvrent le cycle de vie complet de la boucle d'agent dans les deux SDK. Le SDK TypeScript produit également des événements d'observabilité supplémentaires (événements de hooks, progression des outils, limites de débit, notifications de tâches) qui fournissent des détails supplémentaires mais ne sont pas nécessaires pour piloter la boucle. Voir la [référence des types de messages Python](/fr/agent-sdk/python#message-types) et la [référence des types de messages TypeScript](/fr/agent-sdk/typescript#message-types) pour les listes complètes.

58### Gérer les messages

60Les messages que vous gérez dépendent de ce que vous construisez :

62* **Résultats finaux uniquement :** gérez `ResultMessage` pour obtenir la sortie, le coût et si la tâche a réussi ou a atteint une limite.

63* **Mises à jour de progression :** gérez `AssistantMessage` pour voir ce que Claude fait à chaque tour, y compris les outils qu'il a appelés.

64* **Diffusion en direct :** activez les messages partiels (`include_partial_messages` en Python, `includePartialMessages` en TypeScript) pour obtenir les messages `StreamEvent` en temps réel. Voir [Réponses en flux en temps réel](/fr/agent-sdk/streaming-output).

66La façon dont vous vérifiez les types de messages dépend du SDK :

68* **Python :** vérifiez les types de messages avec `isinstance()` par rapport aux classes importées de `claude_agent_sdk` (par exemple, `isinstance(message, ResultMessage)`).

69* **TypeScript :** vérifiez le champ de chaîne `type` (par exemple, `message.type === "result"`). `AssistantMessage` et `UserMessage` enveloppent le message API brut dans un champ `.message`, donc les blocs de contenu sont à `message.message.content`, pas `message.content`.

71<Accordion title="Exemple : Vérifier les types de messages et gérer les résultats">

72 <CodeGroup>

73 ```python Python theme={null}

74 from claude_agent_sdk import query, AssistantMessage, ResultMessage

76 async for message in query(prompt="Summarize this project"):

77 if isinstance(message, AssistantMessage):

78 print(f"Turn completed: {len(message.content)} content blocks")

79 if isinstance(message, ResultMessage):

80 if message.subtype == "success":

81 print(message.result)

82 else:

83 print(f"Stopped: {message.subtype}")

84 ```

86 ```typescript TypeScript theme={null}

87 import { query } from "@anthropic-ai/claude-agent-sdk";

89 for await (const message of query({ prompt: "Summarize this project" })) {

90 if (message.type === "assistant") {

91 console.log(`Turn completed: ${message.message.content.length} content blocks`);

92 }

93 if (message.type === "result") {

94 if (message.subtype === "success") {

95 console.log(message.result);

96 } else {

97 console.log(`Stopped: ${message.subtype}`);

98 }

99 }

100 }

101 ```

102 </CodeGroup>

103</Accordion>

104

105## Exécution des outils

106

107Les outils donnent à votre agent la capacité d'agir. Sans outils, Claude ne peut que répondre avec du texte. Avec les outils, Claude peut lire des fichiers, exécuter des commandes, rechercher du code et interagir avec des services externes.

108

109### Outils intégrés

110

111Le SDK inclut les mêmes outils qui alimentent Claude Code :

112

113| Catégorie | Outils | Ce qu'ils font |

114| :-------------------------- | :----------------------------------------------- | :--------------------------------------------------------------------------------------------- |

115| **Opérations sur fichiers** | `Read`, `Edit`, `Write` | Lire, modifier et créer des fichiers |

116| **Recherche** | `Glob`, `Grep` | Trouver des fichiers par motif, rechercher du contenu avec regex |

117| **Exécution** | `Bash` | Exécuter des commandes shell, des scripts, des opérations git |

118| **Web** | `WebSearch`, `WebFetch` | Rechercher le web, récupérer et analyser des pages |

119| **Découverte** | `ToolSearch` | Trouver et charger dynamiquement les outils à la demande au lieu de les précharger tous |

120| **Orchestration** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | Générer des sous-agents, invoquer des compétences, demander à l'utilisateur, suivre les tâches |

121

122Au-delà des outils intégrés, vous pouvez :

123

124* **Connecter des services externes** avec des [serveurs MCP](/fr/agent-sdk/mcp) (bases de données, navigateurs, API)

125* **Définir des outils personnalisés** avec des [gestionnaires d'outils personnalisés](/fr/agent-sdk/custom-tools)

126* **Charger les compétences du projet** via des [sources de paramètres](/fr/agent-sdk/claude-code-features) pour des flux de travail réutilisables

127

128### Permissions des outils

129

130Claude détermine les outils à appeler en fonction de la tâche, mais vous contrôlez si ces appels sont autorisés à s'exécuter. Vous pouvez approuver automatiquement des outils spécifiques, en bloquer d'autres entièrement, ou exiger une approbation pour tout. Trois options fonctionnent ensemble pour déterminer ce qui s'exécute :

131

132* **`allowed_tools` / `allowedTools`** approuve automatiquement les outils listés. Un agent en lecture seule avec `["Read", "Glob", "Grep"]` dans sa liste d'outils autorisés exécute ces outils sans demander. Les outils non listés sont toujours disponibles mais nécessitent une permission.

133* **`disallowed_tools` / `disallowedTools`** bloque les outils listés, indépendamment des autres paramètres. Voir [Permissions](/fr/agent-sdk/permissions) pour l'ordre dans lequel les règles sont vérifiées avant qu'un outil s'exécute.

134* **`permission_mode` / `permissionMode`** contrôle ce qui se passe pour les outils qui ne sont pas couverts par les règles d'autorisation ou de refus. Voir [Mode de permission](#permission-mode) pour les modes disponibles.

135

136Vous pouvez également délimiter les outils individuels avec des règles comme `"Bash(npm *)"` pour autoriser uniquement des commandes spécifiques. Voir [Permissions](/fr/agent-sdk/permissions) pour la syntaxe complète des règles.

137

138Lorsqu'un outil est refusé, Claude reçoit un message de rejet comme résultat d'outil et tente généralement une approche différente ou signale qu'il ne pouvait pas procéder.

139

140### Exécution parallèle des outils

141

142Lorsque Claude demande plusieurs appels d'outils en un seul tour, les deux SDK peuvent les exécuter de manière concurrente ou séquentielle selon l'outil. Les outils en lecture seule (comme `Read`, `Glob`, `Grep` et les outils MCP marqués comme en lecture seule) peuvent s'exécuter de manière concurrente. Les outils qui modifient l'état (comme `Edit`, `Write` et `Bash`) s'exécutent séquentiellement pour éviter les conflits.

143

144Les outils personnalisés s'exécutent par défaut de manière séquentielle. Pour activer l'exécution parallèle pour un outil personnalisé, définissez `readOnlyHint` dans ses annotations. Les deux SDK [TypeScript](/fr/agent-sdk/typescript#tool) et [Python](/fr/agent-sdk/python#tool) utilisent ce nom de champ du SDK MCP.

145

146## Contrôler le fonctionnement de la boucle

147

148Vous pouvez limiter le nombre de tours que la boucle prend, combien elle coûte, la profondeur du raisonnement de Claude et si les outils nécessitent une approbation avant de s'exécuter. Tous ces éléments sont des champs sur [`ClaudeAgentOptions`](/fr/agent-sdk/python#claudeagentoptions) (Python) / [`Options`](/fr/agent-sdk/typescript#options) (TypeScript).

149

150### Tours et budget

151

152| Option | Ce qu'elle contrôle | Valeur par défaut |

153| :--------------------------------------------- | :------------------------------------------- | :---------------- |

154| Tours max (`max_turns` / `maxTurns`) | Aller-retours maximum d'utilisation d'outils | Pas de limite |

155| Budget max (`max_budget_usd` / `maxBudgetUsd`) | Coût maximum avant arrêt | Pas de limite |

156

157Lorsque l'une de ces limites est atteinte, le SDK retourne un `ResultMessage` avec un sous-type d'erreur correspondant (`error_max_turns` ou `error_max_budget_usd`). Voir [Gérer le résultat](#handle-the-result) pour savoir comment vérifier ces sous-types et [`ClaudeAgentOptions`](/fr/agent-sdk/python#claudeagentoptions) / [`Options`](/fr/agent-sdk/typescript#options) pour la syntaxe.

158

159### Niveau d'effort

160

161L'option `effort` contrôle la profondeur du raisonnement que Claude applique. Les niveaux d'effort inférieur utilisent moins de tokens par tour et réduisent le coût. Tous les modèles ne supportent pas le paramètre d'effort. Voir [Effort](https://platform.claude.com/docs/fr/build-with-claude/effort) pour savoir quels modèles le supportent.

162

163| Niveau | Comportement | Bon pour |

164| :--------- | :------------------------------------- | :--------------------------------------------------------- |

165| `"low"` | Raisonnement minimal, réponses rapides | Recherches de fichiers, listage de répertoires |

166| `"medium"` | Raisonnement équilibré | Éditions de routine, tâches standard |

167| `"high"` | Analyse approfondie | Refactorisations, débogage |

168| `"xhigh"` | Profondeur de raisonnement étendue | Tâches de codage et d'agent ; recommandé sur Opus 4.7 |

169| `"max"` | Profondeur de raisonnement maximale | Problèmes multi-étapes nécessitant une analyse approfondie |

170

171Si vous ne définissez pas `effort`, le SDK Python laisse le paramètre non défini et s'en remet au comportement par défaut du modèle. Le SDK TypeScript utilise par défaut `"high"`.

172

173<Note>

174 `effort` échange la latence et le coût des tokens pour la profondeur du raisonnement dans chaque réponse. [Extended thinking](https://platform.claude.com/docs/fr/build-with-claude/extended-thinking) est une fonctionnalité distincte qui produit des blocs de chaîne de pensée visibles dans la sortie. Ils sont indépendants : vous pouvez définir `effort: "low"` avec extended thinking activé, ou `effort: "max"` sans lui.

175</Note>

176

177Utilisez un effort inférieur pour les agents effectuant des tâches simples et bien délimitées (comme lister des fichiers ou exécuter un seul grep) pour réduire le coût et la latence. Définissez `effort` dans les options de niveau supérieur `query()` pour la session entière, ou par sous-agent avec le champ `effort` sur [`AgentDefinition`](/fr/agent-sdk/subagents#agentdefinition-configuration) pour remplacer le niveau de session.

178

179### Mode de permission

180

181L'option de mode de permission (`permission_mode` en Python, `permissionMode` en TypeScript) contrôle si l'agent demande une approbation avant d'utiliser les outils :

182

183| Mode | Comportement |

184| :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `"default"` | Les outils non couverts par les règles d'autorisation déclenchent votre rappel d'approbation ; pas de rappel signifie refuser |

186| `"acceptEdits"` | Approuve automatiquement les éditions de fichiers et les commandes communes du système de fichiers (`mkdir`, `touch`, `mv`, `cp`, etc.) ; les autres commandes Bash suivent les règles par défaut |

187| `"plan"` | Les outils en lecture seule s'exécutent ; Claude explore et produit un plan sans éditer vos fichiers source |

188| `"dontAsk"` | Ne demande jamais. Les outils pré-approuvés par les [règles de permission](/fr/settings#permission-settings) s'exécutent, tout le reste est refusé |

189| `"auto"` (TypeScript uniquement) | Utilise un classificateur de modèle pour approuver ou refuser chaque appel d'outil. Voir [Mode auto](/fr/permission-modes#eliminate-prompts-with-auto-mode) pour la disponibilité et le comportement |

190| `"bypassPermissions"` | Exécute tous les outils autorisés sans demander. Ne peut pas être utilisé lors de l'exécution en tant que root sur Unix. À utiliser uniquement dans des environnements isolés où les actions de l'agent ne peuvent pas affecter les systèmes qui vous intéressent |

191

192Pour les applications interactives, utilisez `"default"` avec un rappel d'approbation d'outil pour afficher les invites d'approbation. Pour les agents autonomes sur une machine de développement, `"acceptEdits"` approuve automatiquement les éditions de fichiers et les commandes communes du système de fichiers (`mkdir`, `touch`, `mv`, `cp`, etc.) tout en gardant les autres commandes `Bash` derrière les règles d'autorisation. Réservez `"bypassPermissions"` pour CI, les conteneurs ou d'autres environnements isolés. Voir [Permissions](/fr/agent-sdk/permissions) pour les détails complets.

193

194### Modèle

195

196Si vous ne définissez pas `model`, le SDK utilise la valeur par défaut de Claude Code, qui dépend de votre méthode d'authentification et de votre abonnement. Définissez-le explicitement (par exemple, `model="claude-sonnet-4-6"`) pour épingler un modèle spécifique ou pour utiliser un modèle plus petit pour des agents plus rapides et moins chers. Voir [modèles](https://platform.claude.com/docs/fr/about-claude/models) pour les ID disponibles.

197

198## La fenêtre de contexte

199

200La fenêtre de contexte est la quantité totale d'informations disponibles pour Claude pendant une session. Elle ne se réinitialise pas entre les tours au sein d'une session. Tout s'accumule : le prompt système, les définitions d'outils, l'historique de conversation, les entrées d'outils et les sorties d'outils. Le contenu qui reste le même entre les tours (prompt système, définitions d'outils, CLAUDE.md) est automatiquement [mis en cache par prompt](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching), ce qui réduit le coût et la latence pour les préfixes répétés.

201

202### Ce qui consomme du contexte

203

204Voici comment chaque composant affecte le contexte dans le SDK :

205

206| Source | Quand elle se charge | Impact |

207| :------------------------------ | :------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

208| **Prompt système** | Chaque requête | Petit coût fixe, toujours présent |

209| **Fichiers CLAUDE.md** | Démarrage de session, via [`settingSources`](/fr/agent-sdk/claude-code-features) | Contenu complet dans chaque requête (mais mis en cache par prompt, donc seule la première requête paie le coût complet) |

210| **Définitions d'outils** | Chaque requête | Chaque outil ajoute son schéma ; utilisez la [recherche d'outils MCP](/fr/agent-sdk/mcp#mcp-tool-search) pour charger les outils à la demande au lieu de tous à la fois |

211| **Historique de conversation** | S'accumule au fil des tours | Croît avec chaque tour : prompts, réponses, entrées d'outils, sorties d'outils |

212| **Descriptions de compétences** | Démarrage de session, via sources de paramètres | Résumés courts ; le contenu complet se charge uniquement lors de l'invocation |

213

214Les grandes sorties d'outils consomment un contexte significatif. Lire un gros fichier ou exécuter une commande avec une sortie détaillée peut utiliser des milliers de tokens en un seul tour. Le contexte s'accumule au fil des tours, donc les sessions plus longues avec de nombreux appels d'outils accumulent beaucoup plus de contexte que les courtes.

215

216### Compaction automatique

217

218Lorsque la fenêtre de contexte approche de sa limite, le SDK compacte automatiquement la conversation : il résume l'historique plus ancien pour libérer de l'espace, en gardant vos échanges les plus récents et les décisions clés intacts. Le SDK émet un message avec `type: "system"` et `subtype: "compact_boundary"` dans le flux lorsque cela se produit (en Python c'est un `SystemMessage` ; en TypeScript c'est un type `SDKCompactBoundaryMessage` distinct).

219

220La compaction remplace les messages plus anciens par un résumé, donc les instructions spécifiques du début de la conversation peuvent ne pas être préservées. Les règles persistantes appartiennent à CLAUDE.md (chargé via [`settingSources`](/fr/agent-sdk/claude-code-features)) plutôt qu'au prompt initial, car le contenu CLAUDE.md est réinjecté à chaque requête.

221

222Vous pouvez personnaliser le comportement de compaction de plusieurs façons :

223

224* **Instructions de résumé dans CLAUDE.md :** Le compacteur lit votre CLAUDE.md comme tout autre contexte, donc vous pouvez inclure une section lui indiquant ce qu'il faut préserver lors de la résumé. L'en-tête de section est libre (pas une chaîne magique) ; le compacteur correspond sur l'intention.

225* **Hook `PreCompact` :** Exécutez une logique personnalisée avant la compaction, par exemple pour archiver la transcription complète. Le hook reçoit un champ `trigger` (`manual` ou `auto`). Voir [hooks](/fr/agent-sdk/hooks).

226* **Compaction manuelle :** Envoyez `/compact` comme chaîne de prompt pour déclencher la compaction à la demande. (Les commandes slash envoyées de cette façon sont des entrées SDK, pas des raccourcis CLI uniquement. Voir [commandes slash dans le SDK](/fr/agent-sdk/slash-commands).)

227

228<Accordion title="Exemple : Instructions de résumé dans CLAUDE.md">

229 Ajoutez une section au CLAUDE.md de votre projet indiquant au compacteur ce qu'il faut préserver. Le nom d'en-tête n'est pas spécial ; utilisez n'importe quel label clair.

230

231 ```markdown CLAUDE.md theme={null}

232 # Summary instructions

233

234 When summarizing this conversation, always preserve:

235 - The current task objective and acceptance criteria

236 - File paths that have been read or modified

237 - Test results and error messages

238 - Decisions made and the reasoning behind them

239 ```

240</Accordion>

241

242### Garder le contexte efficace

243

244Quelques stratégies pour les agents de longue durée :

245

246* **Utilisez des sous-agents pour les sous-tâches.** Chaque sous-agent commence avec une conversation fraîche (pas d'historique de messages antérieurs, bien qu'il charge son propre prompt système et le contexte au niveau du projet comme CLAUDE.md). Il ne voit pas les tours du parent, et seule sa réponse finale retourne au parent comme résultat d'outil. Le contexte de l'agent principal croît par ce résumé, pas par la transcription complète de la sous-tâche. Voir [Ce que les sous-agents héritent](/fr/agent-sdk/subagents#what-subagents-inherit) pour les détails.

247* **Soyez sélectif avec les outils.** Chaque définition d'outil prend de l'espace de contexte. Utilisez le champ `tools` sur [`AgentDefinition`](/fr/agent-sdk/subagents#agentdefinition-configuration) pour délimiter les sous-agents à l'ensemble minimum dont ils ont besoin, et utilisez la [recherche d'outils MCP](/fr/agent-sdk/mcp#mcp-tool-search) pour charger les outils à la demande au lieu de les précharger tous.

248* **Surveillez les coûts des serveurs MCP.** Chaque serveur MCP ajoute tous ses schémas d'outils à chaque requête. Quelques serveurs avec de nombreux outils peuvent consommer un contexte significatif avant que l'agent ne fasse aucun travail. L'outil `ToolSearch` peut aider en chargeant les outils à la demande au lieu de les précharger tous. Voir [Recherche d'outils MCP](/fr/agent-sdk/mcp#mcp-tool-search) pour la configuration.

249* **Utilisez un effort inférieur pour les tâches de routine.** Définissez [effort](#effort-level) à `"low"` pour les agents qui n'ont besoin que de lire des fichiers ou de lister des répertoires. Cela réduit l'utilisation des tokens et le coût.

250

251Pour une ventilation détaillée des coûts de contexte par fonctionnalité, voir [Comprendre les coûts de contexte](/fr/features-overview#understand-context-costs).

252

253## Sessions et continuité

254

255Chaque interaction avec le SDK crée ou continue une session. Capturez l'ID de session de `ResultMessage.session_id` (disponible dans les deux SDK) pour reprendre plus tard. Le SDK TypeScript l'expose également comme un champ direct sur le `SystemMessage` init ; en Python, il est imbriqué dans `SystemMessage.data`.

256

257Lorsque vous reprenez, le contexte complet des tours précédents est restauré : les fichiers qui ont été lus, l'analyse qui a été effectuée et les actions qui ont été prises. Vous pouvez également forcer une session pour vous brancher dans une approche différente sans modifier l'original.

258

259Voir [Gestion des sessions](/fr/agent-sdk/sessions) pour le guide complet sur les modèles de reprise, de continuation et de bifurcation.

260

261<Note>

262 En Python, `ClaudeSDKClient` gère automatiquement les ID de session sur plusieurs appels. Voir la [référence du SDK Python](/fr/agent-sdk/python#choosing-between-query-and-claudesdkclient) pour les détails.

263</Note>

264

265## Gérer le résultat

266

267Lorsque la boucle se termine, le `ResultMessage` vous indique ce qui s'est passé et vous donne la sortie. Le champ `subtype` (disponible dans les deux SDK) est le moyen principal de vérifier l'état de terminaison.

268

269| Sous-type de résultat | Ce qui s'est passé | Champ `result` disponible ? |

270| :------------------------------------ | :------------------------------------------------------------------------------------------ | :-------------------------: |

271| `success` | Claude a terminé la tâche normalement | Oui |

272| `error_max_turns` | Limite de `maxTurns` atteinte avant la fin | Non |

273| `error_max_budget_usd` | Limite de `maxBudgetUsd` atteinte avant la fin | Non |

274| `error_during_execution` | Une erreur a interrompu la boucle (par exemple, une défaillance API ou une requête annulée) | Non |

275| `error_max_structured_output_retries` | La validation de la sortie structurée a échoué après la limite de tentatives configurée | Non |

276

277Le champ `result` (la sortie textuelle finale) n'est présent que sur la variante `success`, donc vérifiez toujours le sous-type avant de le lire. Tous les sous-types de résultat portent `total_cost_usd`, `usage`, `num_turns` et `session_id` afin que vous puissiez suivre le coût et reprendre même après des erreurs. En Python, `total_cost_usd` et `usage` sont typés comme optionnels et peuvent être `None` sur certains chemins d'erreur, donc gardez-les avant de les formater. Voir [Suivi des coûts et de l'utilisation](/fr/agent-sdk/cost-tracking) pour les détails sur l'interprétation des champs `usage`.

278

279Le résultat inclut également un champ `stop_reason` (`string | null` en TypeScript, `str | None` en Python) indiquant pourquoi le modèle a arrêté de générer sur son tour final. Les valeurs courantes sont `end_turn` (le modèle a terminé normalement), `max_tokens` (limite de token de sortie atteinte) et `refusal` (le modèle a refusé la requête). Sur les sous-types de résultat d'erreur, `stop_reason` porte la valeur de la dernière réponse d'assistant avant la fin de la boucle. Pour détecter les refus, vérifiez `stop_reason === "refusal"` (TypeScript) ou `stop_reason == "refusal"` (Python). Voir [`SDKResultMessage`](/fr/agent-sdk/typescript#sdkresultmessage) (TypeScript) ou [`ResultMessage`](/fr/agent-sdk/python#resultmessage) (Python) pour le type complet.

280

281## Hooks

282

283Les [Hooks](/fr/agent-sdk/hooks) sont des rappels qui se déclenchent à des points spécifiques de la boucle : avant qu'un outil s'exécute, après son retour, lorsque l'agent termine, et ainsi de suite. Certains hooks couramment utilisés sont :

284

285| Hook | Quand il se déclenche | Utilisations courantes |

286| :------------------------------- | :------------------------------------------- | :----------------------------------------------------- |

287| `PreToolUse` | Avant l'exécution d'un outil | Valider les entrées, bloquer les commandes dangereuses |

288| `PostToolUse` | Après le retour d'un outil | Auditer les sorties, déclencher des effets secondaires |

289| `UserPromptSubmit` | Quand un prompt est envoyé | Injecter du contexte supplémentaire dans les prompts |

290| `Stop` | Quand l'agent termine | Valider le résultat, sauvegarder l'état de la session |

291| `SubagentStart` / `SubagentStop` | Quand un sous-agent est généré ou se termine | Suivre et agréger les résultats des tâches parallèles |

292| `PreCompact` | Avant la compaction du contexte | Archiver la transcription complète avant la résumé |

293

294Les hooks s'exécutent dans le processus de votre application, pas à l'intérieur de la fenêtre de contexte de l'agent, donc ils ne consomment pas de contexte. Les hooks peuvent également court-circuiter la boucle : un hook `PreToolUse` qui rejette un appel d'outil l'empêche de s'exécuter, et Claude reçoit le message de rejet à la place.

295

296Les deux SDK supportent tous les événements ci-dessus. Le SDK TypeScript inclut des événements supplémentaires que Python ne supporte pas encore. Voir [Contrôler l'exécution avec des hooks](/fr/agent-sdk/hooks) pour la liste complète des événements, la disponibilité par SDK et l'API de rappel complète.

297

298## Tout mettre ensemble

299

300Cet exemple combine les concepts clés de cette page dans un seul agent qui corrige les tests défaillants. Il configure l'agent avec les outils autorisés (approuvés automatiquement afin que l'agent s'exécute de manière autonome), les paramètres du projet et les limites de sécurité sur les tours et l'effort de raisonnement. Lorsque la boucle s'exécute, elle capture l'ID de session pour une reprise potentielle, gère le résultat final et imprime le coût total.

301

302<CodeGroup>

303 ```python Python theme={null}

304 import asyncio

305 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

306

307

308 async def run_agent():

309 session_id = None

310

311 async for message in query(

312 prompt="Find and fix the bug causing test failures in the auth module",

313 options=ClaudeAgentOptions(

314 allowed_tools=[

315 "Read",

316 "Edit",

317 "Bash",

318 "Glob",

319 "Grep",

320 ], # Listing tools here auto-approves them (no prompting)

321 setting_sources=[

322 "project"

323 ], # Load CLAUDE.md, skills, hooks from current directory

324 max_turns=30, # Prevent runaway sessions

325 effort="high", # Thorough reasoning for complex debugging

326 ),

327 ):

328 # Handle the final result

329 if isinstance(message, ResultMessage):

330 session_id = message.session_id # Save for potential resumption

331

332 if message.subtype == "success":

333 print(f"Done: {message.result}")

334 elif message.subtype == "error_max_turns":

335 # Agent ran out of turns. Resume with a higher limit.

336 print(f"Hit turn limit. Resume session {session_id} to continue.")

337 elif message.subtype == "error_max_budget_usd":

338 print("Hit budget limit.")

339 else:

340 print(f"Stopped: {message.subtype}")

341 if message.total_cost_usd is not None:

342 print(f"Cost: ${message.total_cost_usd:.4f}")

343

344

345 asyncio.run(run_agent())

346 ```

347

348 ```typescript TypeScript theme={null}

349 import { query } from "@anthropic-ai/claude-agent-sdk";

350

351 let sessionId: string | undefined;

352

353 for await (const message of query({

354 prompt: "Find and fix the bug causing test failures in the auth module",

355 options: {

356 allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)

357 settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory

358 maxTurns: 30, // Prevent runaway sessions

359 effort: "high" // Thorough reasoning for complex debugging

360 }

361 })) {

362 // Save the session ID to resume later if needed

363 if (message.type === "system" && message.subtype === "init") {

364 sessionId = message.session_id;

365 }

366

367 // Handle the final result

368 if (message.type === "result") {

369 if (message.subtype === "success") {

370 console.log(`Done: ${message.result}`);

371 } else if (message.subtype === "error_max_turns") {

372 // Agent ran out of turns. Resume with a higher limit.

373 console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);

374 } else if (message.subtype === "error_max_budget_usd") {

375 console.log("Hit budget limit.");

376 } else {

377 console.log(`Stopped: ${message.subtype}`);

378 }

379 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

380 }

381 }

382 ```

383</CodeGroup>

384

385## Étapes suivantes

386

387Maintenant que vous comprenez la boucle, voici où aller en fonction de ce que vous construisez :

388

389* **Vous n'avez pas encore exécuté un agent ?** Commencez par le [démarrage rapide](/fr/agent-sdk/quickstart) pour obtenir le SDK installé et voir un exemple complet s'exécutant de bout en bout.

390* **Prêt à vous connecter à votre projet ?** [Chargez CLAUDE.md, les compétences et les hooks du système de fichiers](/fr/agent-sdk/claude-code-features) afin que l'agent suive automatiquement les conventions de votre projet.

391* **Construisez une interface utilisateur interactive ?** Activez la [diffusion](/fr/agent-sdk/streaming-output) pour afficher le texte en direct et les appels d'outils lorsque la boucle s'exécute.

392* **Avez-vous besoin d'un contrôle plus strict sur ce que l'agent peut faire ?** Verrouillez l'accès aux outils avec les [permissions](/fr/agent-sdk/permissions) et utilisez les [hooks](/fr/agent-sdk/hooks) pour auditer, bloquer ou transformer les appels d'outils avant qu'ils ne s'exécutent.

393* **Exécutez des tâches longues ou coûteuses ?** Déléguez le travail isolé aux [sous-agents](/fr/agent-sdk/subagents) pour garder votre contexte principal maigre.

394

395Pour la vue d'ensemble conceptuelle plus large de la boucle d'agent (non spécifique au SDK), voir [Fonctionnement de Claude Code](/fr/how-claude-code-works).

agent-sdk/hooks.md +11 −11

Details

236Votre rappel retourne un objet avec deux catégories de champs :236Votre rappel retourne un objet avec deux catégories de champs :

237 237

238* **Champs de niveau supérieur** contrôlent la conversation : `systemMessage` injecte un message dans la conversation visible au modèle, et `continue` (`continue_` en Python) détermine si l'agent continue à s'exécuter après ce hook.238* **Champs de niveau supérieur** contrôlent la conversation : `systemMessage` injecte un message dans la conversation visible au modèle, et `continue` (`continue_` en Python) détermine si l'agent continue à s'exécuter après ce hook.

239* **`hookSpecificOutput`** contrôle l'opération actuelle. Les champs à l'intérieur dépendent du type d'événement hook. Pour les hooks `PreToolUse`, c'est là que vous définissez `permissionDecision` (`"allow"`, `"deny"` ou `"ask"`), `permissionDecisionReason` et `updatedInput`. Dans le SDK TypeScript, `permissionDecision` accepte également `"defer"` pour terminer la requête et [reprendre plus tard](/fr/hooks#defer-a-tool-call-for-later) ; cette valeur n'est pas disponible dans le SDK Python. Pour les hooks `PostToolUse`, vous pouvez définir `additionalContext` pour ajouter des informations au résultat de l'outil.239* **`hookSpecificOutput`** contrôle l'opération actuelle. Les champs à l'intérieur dépendent du type d'événement hook. Pour les hooks `PreToolUse`, c'est là que vous définissez `permissionDecision` (`"allow"`, `"deny"` ou `"ask"`), `permissionDecisionReason` et `updatedInput`. Dans le SDK TypeScript, `permissionDecision` accepte également `"defer"` pour terminer la requête et [reprendre plus tard](/fr/hooks#defer-a-tool-call-for-later) ; cette valeur n'est pas disponible dans le SDK Python. Pour les hooks `PostToolUse`, vous pouvez définir `additionalContext` pour ajouter des informations au résultat de l'outil, ou `updatedToolOutput` pour remplacer entièrement la sortie de l'outil avant que Claude ne la voie.

240 240

241Retournez `{}` pour autoriser l'opération sans modifications. Les hooks de rappel du SDK utilisent le même format de sortie JSON que les [hooks de commande shell Claude Code](/fr/hooks#json-output), qui documente chaque champ et option spécifique à l'événement. Pour les définitions de type du SDK, consultez les références du SDK [TypeScript](/fr/agent-sdk/typescript#sync-hook-json-output) et [Python](/fr/agent-sdk/python#sync-hook-json-output).241Retournez `{}` pour autoriser l'opération sans modifications. Les hooks de rappel du SDK utilisent le même format de sortie JSON que les [hooks de commande shell Claude Code](/fr/hooks#json-output), qui documente chaque champ et option spécifique à l'événement. Pour les définitions de type du SDK, consultez les références du SDK [TypeScript](/fr/agent-sdk/typescript#sync-hook-json-output) et [Python](/fr/agent-sdk/python#sync-hook-json-output).

242 242

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419

420### Chaîner plusieurs hooks420### Enregistrer plusieurs hooks

421 421

422Les hooks s'exécutent dans l'ordre dans lequel ils apparaissent dans le tableau. Gardez chaque hook concentré sur une seule responsabilité et chaînez plusieurs hooks pour une logique complexe :422Quand un événement se déclenche, tous les hooks correspondants s'exécutent en parallèle. Pour les décisions de permission, le résultat le plus restrictif gagne : un seul `deny` bloque l'appel d'outil indépendamment de ce que les autres hooks retournent. Parce que l'ordre d'exécution est non-déterministe, écrivez chaque hook pour agir indépendamment plutôt que de compter sur l'exécution préalable d'un autre hook.

423

424L'exemple ci-dessous enregistre trois vérifications indépendantes pour chaque appel d'outil :

423 425

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # First: check rate limits431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # Second: verify permissions432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # Third: sanitize inputs433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # Last: log the action

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // First: check rate limits443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // Second: verify permissions444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // Third: sanitize inputs445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // Last: log the action

446 ]446 ]

447 }447 }

448 };448 };

agent-sdk/migration-guide.md +289 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Migrer vers Claude Agent SDK

7> Guide pour migrer les SDK TypeScript et Python de Claude Code vers Claude Agent SDK

9## Aperçu

11Le SDK Claude Code a été renommé en **Claude Agent SDK** et sa documentation a été réorganisée. Ce changement reflète les capacités plus larges du SDK pour construire des agents IA au-delà des simples tâches de codage.

13## Qu'est-ce qui a changé

15| Aspect | Ancien | Nouveau |

16| :---------------------------------- | :-------------------------- | :------------------------------- |

17| **Nom du package (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Package Python** | `claude-code-sdk` | `claude-agent-sdk` |

19| **Emplacement de la documentation** | Documentation Claude Code | Guide API → Section Agent SDK |

21<Note>

22 **Modifications de la documentation :** La documentation d'Agent SDK a été déplacée de la documentation Claude Code vers le Guide API sous une section dédiée [Agent SDK](/fr/agent-sdk/overview). La documentation Claude Code se concentre désormais sur l'outil CLI et les fonctionnalités d'automatisation.

23</Note>

25## Étapes de migration

27### Pour les projets TypeScript/JavaScript

29**1. Désinstallez l'ancien package :**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. Installez le nouveau package :**

37```bash theme={null}

38npm install @anthropic-ai/claude-agent-sdk

39```

41**3. Mettez à jour vos imports :**

43Modifiez tous les imports de `@anthropic-ai/claude-code` vers `@anthropic-ai/claude-agent-sdk` :

45```typescript theme={null}

46// Avant

47import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

49// Après

50import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

51```

53**4. Mettez à jour les dépendances package.json :**

55Si vous avez le package listé dans votre `package.json`, mettez-le à jour :

57Avant :

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67Après :

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77C'est tout ! Aucune autre modification de code n'est requise.

79### Pour les projets Python

81**1. Désinstallez l'ancien package :**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. Installez le nouveau package :**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. Mettez à jour vos imports :**

95Modifiez tous les imports de `claude_code_sdk` vers `claude_agent_sdk` :

97```python theme={null}

98# Avant

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# Après

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. Mettez à jour les noms de types :**

106

107Modifiez `ClaudeCodeOptions` en `ClaudeAgentOptions` :

108

109```python theme={null}

110# Avant

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# Après

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```

120

121**5. Consultez les [modifications incompatibles](#breaking-changes)**

122

123Effectuez les modifications de code nécessaires pour terminer la migration.

124

125## Modifications incompatibles

126

127<Warning>

128 Pour améliorer l'isolation et la configuration explicite, Claude Agent SDK v0.1.0 introduit des modifications incompatibles pour les utilisateurs migrant depuis Claude Code SDK. Consultez attentivement cette section avant de migrer.

129</Warning>

130

131### Python : ClaudeCodeOptions renommé en ClaudeAgentOptions

132

133**Qu'est-ce qui a changé :** Le type SDK Python `ClaudeCodeOptions` a été renommé en `ClaudeAgentOptions`.

134

135**Migration :**

136

137```python theme={null}

138# AVANT (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# APRÈS (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**Pourquoi ce changement :** Le nom du type correspond désormais à la marque « Claude Agent SDK » et assure la cohérence dans les conventions de nommage du SDK.

150

151### Le système prompt n'est plus par défaut

152

153**Qu'est-ce qui a changé :** Le SDK n'utilise plus le système prompt de Claude Code par défaut.

154

155**Migration :**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // AVANT (v0.0.x) - Utilisait le système prompt de Claude Code par défaut

160 const result = query({ prompt: "Hello" });

161

162 // APRÈS (v0.1.0) - Utilise un système prompt minimal par défaut

163 // Pour obtenir l'ancien comportement, demandez explicitement le préréglage de Claude Code :

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // Ou utilisez un système prompt personnalisé :

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # AVANT (v0.0.x) - Utilisait le système prompt de Claude Code par défaut

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # APRÈS (v0.1.0) - Utilise un système prompt minimal par défaut

186 # Pour obtenir l'ancien comportement, demandez explicitement le préréglage de Claude Code :

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # Utiliser le préréglage

193 ),

194 ):

195 print(message)

196

197 # Ou utilisez un système prompt personnalisé :

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**Pourquoi ce changement :** Fournit un meilleur contrôle et une meilleure isolation pour les applications SDK. Vous pouvez désormais construire des agents avec un comportement personnalisé sans hériter des instructions axées sur le CLI de Claude Code.

207

208### Défaut des sources de paramètres

209

210Ce défaut a été brièvement modifié dans v0.1.0 puis annulé, donc aucune action de migration n'est nécessaire.

211

212**Comportement actuel :** L'omission de `settingSources` sur `query()` charge les paramètres utilisateur, projet et système de fichiers local, correspondant au CLI. Cela inclut `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, les fichiers CLAUDE.md et les commandes personnalisées.

213

214Pour s'exécuter isolé des paramètres du système de fichiers, passez un tableau vide :

215

216<CodeGroup>

217 ```typescript TypeScript theme={null}

218 const result = query({

219 prompt: "Hello",

220 options: {

221 settingSources: [] // Aucun paramètre du système de fichiers chargé

222 }

223 });

224

225 // Ou charger uniquement des sources spécifiques :

226 const result = query({

227 prompt: "Hello",

228 options: {

229 settingSources: ["project"] // Uniquement les paramètres du projet

230 }

231 });

232 ```

233

234 ```python Python theme={null}

235 from claude_agent_sdk import query, ClaudeAgentOptions

236

237 async for message in query(

238 prompt="Hello",

239 options=ClaudeAgentOptions(setting_sources=[]), # Aucun paramètre du système de fichiers chargé

240 ):

241 print(message)

242

243 # Ou charger uniquement des sources spécifiques :

244 async for message in query(

245 prompt="Hello",

246 options=ClaudeAgentOptions(

247 setting_sources=["project"] # Uniquement les paramètres du projet

248 ),

249 ):

250 print(message)

251 ```

252</CodeGroup>

253

254L'isolation est particulièrement importante pour les pipelines CI/CD, les applications déployées, les environnements de test et les systèmes multi-locataires où les personnalisations locales ne doivent pas s'infiltrer.

255

256<Note>

257 SDK v0.1.0 a brièvement défini par défaut aucun paramètre chargé ; cela a été annulé dans les versions ultérieures. Python SDK 0.1.59 et antérieures traitaient une liste vide de la même manière que l'omission de l'option, donc mettez à jour avant de compter sur `setting_sources=[]`. Consultez [Ce que settingSources ne contrôle pas](/fr/agent-sdk/claude-code-features#what-settingsources-does-not-control) pour les entrées qui sont lues même lorsque `settingSources` est `[]`.

258</Note>

259

260## Pourquoi le changement de nom ?

261

262Le SDK Claude Code a été conçu à l'origine pour les tâches de codage, mais il a évolué en un cadre puissant pour construire tous les types d'agents IA. Le nouveau nom « Claude Agent SDK » reflète mieux ses capacités :

263

264* Construire des agents commerciaux (assistants juridiques, conseillers financiers, support client)

265* Créer des agents de codage spécialisés (bots SRE, examinateurs de sécurité, agents d'examen de code)

266* Développer des agents personnalisés pour n'importe quel domaine avec utilisation d'outils, intégration MCP et bien plus

267

268## Obtenir de l'aide

269

270Si vous rencontrez des problèmes lors de la migration :

271

272**Pour TypeScript/JavaScript :**

273

2741. Vérifiez que tous les imports sont mis à jour pour utiliser `@anthropic-ai/claude-agent-sdk`

2752. Vérifiez que votre package.json a le nouveau nom de package

2763. Exécutez `npm install` pour vous assurer que les dépendances sont mises à jour

277

278**Pour Python :**

279

2801. Vérifiez que tous les imports sont mis à jour pour utiliser `claude_agent_sdk`

2812. Vérifiez que votre requirements.txt ou pyproject.toml a le nouveau nom de package

2823. Exécutez `pip install claude-agent-sdk` pour vous assurer que le package est installé

283

284## Prochaines étapes

285

286* Explorez l'[Aperçu d'Agent SDK](/fr/agent-sdk/overview) pour en savoir plus sur les fonctionnalités disponibles

287* Consultez la [Référence SDK TypeScript](/fr/agent-sdk/typescript) pour la documentation API détaillée

288* Consultez la [Référence SDK Python](/fr/agent-sdk/python) pour la documentation spécifique à Python

289* En savoir plus sur les [Outils personnalisés](/fr/agent-sdk/custom-tools) et l'[Intégration MCP](/fr/agent-sdk/mcp)

agent-sdk/permissions.md +242 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Configurer les permissions

7> Contrôlez comment votre agent utilise les outils avec les modes de permission, les hooks et les règles de permission/refus déclaratives.

9Le Claude Agent SDK fournit des contrôles de permission pour gérer la façon dont Claude utilise les outils. Utilisez les modes de permission et les règles pour définir ce qui est autorisé automatiquement, et le callback [`canUseTool`](/fr/agent-sdk/user-input) pour gérer tout le reste à l'exécution.

11<Note>

12 Cette page couvre les modes de permission et les règles. Pour créer des flux d'approbation interactifs où les utilisateurs approuvent ou refusent les demandes d'outils à l'exécution, consultez [Gérer les approbations et les entrées utilisateur](/fr/agent-sdk/user-input).

13</Note>

15## Comment les permissions sont évaluées

17Lorsque Claude demande un outil, le SDK vérifie les permissions dans cet ordre :

19<Steps>

20 <Step title="Hooks">

21 Exécutez d'abord les [hooks](/fr/agent-sdk/hooks). Un hook peut refuser l'appel directement ou le transmettre. Un hook qui retourne `allow` ne saute pas les règles de refus et de demande ci-dessous ; celles-ci sont évaluées indépendamment du résultat du hook.

22 </Step>

24 <Step title="Règles de refus">

25 Vérifiez les règles `deny` (à partir de `disallowed_tools` et [settings.json](/fr/settings#permission-settings)). Si une règle de refus correspond, l'outil est bloqué, même en mode `bypassPermissions`.

26 </Step>

28 <Step title="Mode de permission">

29 Appliquez le [mode de permission](#permission-modes) actif. `bypassPermissions` approuve tout ce qui atteint cette étape. `acceptEdits` approuve les opérations de fichiers. Les autres modes passent au suivant.

30 </Step>

32 <Step title="Règles d'autorisation">

33 Vérifiez les règles `allow` (à partir de `allowed_tools` et settings.json). Si une règle correspond, l'outil est approuvé.

34 </Step>

36 <Step title="Callback canUseTool">

37 Si aucune des étapes ci-dessus ne résout le problème, appelez votre callback [`canUseTool`](/fr/agent-sdk/user-input) pour une décision. En mode `dontAsk`, cette étape est ignorée et l'outil est refusé.

38 </Step>

39</Steps>

41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="Diagramme du flux d'évaluation des permissions" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

43Cette page se concentre sur les **règles d'autorisation et de refus** et les **modes de permission**. Pour les autres étapes :

45* **Hooks :** exécutez du code personnalisé pour autoriser, refuser ou modifier les demandes d'outils. Consultez [Contrôler l'exécution avec les hooks](/fr/agent-sdk/hooks).

46* **Callback canUseTool :** invitez les utilisateurs à approuver à l'exécution. Consultez [Gérer les approbations et les entrées utilisateur](/fr/agent-sdk/user-input).

48## Règles d'autorisation et de refus

50`allowed_tools` et `disallowed_tools` (TypeScript : `allowedTools` / `disallowedTools`) ajoutent des entrées aux listes de règles d'autorisation et de refus dans le flux d'évaluation ci-dessus. Ils contrôlent si un appel d'outil est approuvé, non si l'outil est disponible pour Claude.

52| Option | Effet |

53| :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |

54| `allowed_tools=["Read", "Grep"]` | `Read` et `Grep` sont auto-approuvés. Les outils non listés ici existent toujours et passent au mode de permission et à `canUseTool`. |

55| `disallowed_tools=["Bash"]` | `Bash` est toujours refusé. Les règles de refus sont vérifiées en premier et s'appliquent dans tous les modes de permission, y compris `bypassPermissions`. |

57Pour un agent verrouillé, associez `allowedTools` avec `permissionMode: "dontAsk"`. Les outils listés sont approuvés ; tout le reste est refusé directement au lieu de demander :

59```typescript theme={null}

60const options = {

61 allowedTools: ["Read", "Glob", "Grep"],

62 permissionMode: "dontAsk"

63};

64```

66<Warning>

67 **`allowed_tools` ne contraint pas `bypassPermissions`.** `allowed_tools` pré-approuve uniquement les outils que vous listez. Les outils non listés ne correspondent à aucune règle d'autorisation et passent au mode de permission, où `bypassPermissions` les approuve. Définir `allowed_tools=["Read"]` avec `permission_mode="bypassPermissions"` approuve toujours tous les outils, y compris `Bash`, `Write` et `Edit`. Si vous avez besoin de `bypassPermissions` mais que vous voulez que certains outils soient bloqués, utilisez `disallowed_tools`.

68</Warning>

70Vous pouvez également configurer les règles d'autorisation, de refus et de demande de manière déclarative dans `.claude/settings.json`. Ces règles sont lues lorsque la source de paramètre `project` est activée, ce qui est le cas pour les options `query()` par défaut. Si vous définissez `setting_sources` (TypeScript : `settingSources`) explicitement, incluez `"project"` pour qu'elles s'appliquent. Consultez [Paramètres de permission](/fr/settings#permission-settings) pour la syntaxe des règles.

72## Modes de permission

74Les modes de permission fournissent un contrôle global sur la façon dont Claude utilise les outils. Vous pouvez définir le mode de permission lors de l'appel de `query()` ou le modifier dynamiquement pendant les sessions de streaming.

76### Modes disponibles

78Le SDK supporte ces modes de permission :

80| Mode | Description | Comportement de l'outil |

81| :----------------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

82| `default` | Comportement de permission standard | Pas d'auto-approbations ; les outils non appariés déclenchent votre callback `canUseTool` |

83| `dontAsk` | Refuser au lieu de demander | Tout ce qui n'est pas pré-approuvé par `allowed_tools` ou les règles est refusé ; `canUseTool` n'est jamais appelé |

84| `acceptEdits` | Auto-accepter les modifications de fichiers | Les modifications de fichiers et les [opérations du système de fichiers](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) sont automatiquement approuvées |

85| `bypassPermissions` | Contourner tous les contrôles de permission | Tous les outils s'exécutent sans invites de permission (à utiliser avec prudence) |

86| `plan` | Mode de planification | Les outils en lecture seule s'exécutent ; Claude analyse et planifie sans modifier vos fichiers source |

87| `auto` (TypeScript uniquement) | Approbations classées par modèle | Un classificateur de modèle approuve ou refuse chaque appel d'outil. Consultez [Mode Auto](/fr/permission-modes#eliminate-prompts-with-auto-mode) pour la disponibilité |

89<Warning>

90 **Héritage des sous-agents :** Lorsque le parent utilise `bypassPermissions`, `acceptEdits` ou `auto`, tous les sous-agents héritent de ce mode et il ne peut pas être remplacé par sous-agent. Les sous-agents peuvent avoir des invites système différentes et un comportement moins contraint que votre agent principal, donc hériter de `bypassPermissions` leur accorde un accès système complet et autonome sans aucune invite d'approbation.

91</Warning>

93### Définir le mode de permission

95Vous pouvez définir le mode de permission une fois au démarrage d'une requête, ou le modifier dynamiquement pendant que la session est active.

97<Tabs>

98 <Tab title="Au moment de la requête">

99 Passez `permission_mode` (Python) ou `permissionMode` (TypeScript) lors de la création d'une requête. Ce mode s'applique pour toute la session sauf s'il est modifié dynamiquement.

100

101 <CodeGroup>

102 ```python Python theme={null}

103 import asyncio

104 from claude_agent_sdk import query, ClaudeAgentOptions

105

106

107 async def main():

108 async for message in query(

109 prompt="Help me refactor this code",

110 options=ClaudeAgentOptions(

111 permission_mode="default", # Set the mode here

112 ),

113 ):

114 if hasattr(message, "result"):

115 print(message.result)

116

117

118 asyncio.run(main())

119 ```

120

121 ```typescript TypeScript theme={null}

122 import { query } from "@anthropic-ai/claude-agent-sdk";

123

124 async function main() {

125 for await (const message of query({

126 prompt: "Help me refactor this code",

127 options: {

128 permissionMode: "default" // Set the mode here

129 }

130 })) {

131 if ("result" in message) {

132 console.log(message.result);

133 }

134 }

135 }

136

137 main();

138 ```

139 </CodeGroup>

140 </Tab>

141

142 <Tab title="Pendant le streaming">

143 Appelez `set_permission_mode()` (Python) ou `setPermissionMode()` (TypeScript) pour modifier le mode en cours de session. Le nouveau mode prend effet immédiatement pour toutes les demandes d'outils suivantes. Cela vous permet de commencer de manière restrictive et d'assouplir les permissions à mesure que la confiance augmente, par exemple en passant à `acceptEdits` après avoir examiné l'approche initiale de Claude.

144

145 <CodeGroup>

146 ```python Python theme={null}

147 import asyncio

148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149

150

151 async def main():

152 async with ClaudeSDKClient(

153 options=ClaudeAgentOptions(

154 permission_mode="default", # Start in default mode

155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158

159 # Change mode dynamically mid-session

160 await client.set_permission_mode("acceptEdits")

161

162 # Process messages with the new permission mode

163 async for message in client.receive_response():

164 if hasattr(message, "result"):

165 print(message.result)

166

167

168 asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

172 import { query } from "@anthropic-ai/claude-agent-sdk";

173

174 async function main() {

175 const q = query({

176 prompt: "Help me refactor this code",

177 options: {

178 permissionMode: "default" // Start in default mode

179 }

180 });

181

182 // Change mode dynamically mid-session

183 await q.setPermissionMode("acceptEdits");

184

185 // Process messages with the new permission mode

186 for await (const message of q) {

187 if ("result" in message) {

188 console.log(message.result);

189 }

190 }

191 }

192

193 main();

194 ```

195 </CodeGroup>

196 </Tab>

197</Tabs>

198

199### Détails des modes

200

201#### Mode d'acceptation des modifications (`acceptEdits`)

202

203Auto-approuve les opérations de fichiers afin que Claude puisse modifier le code sans demander. Les autres outils (comme les commandes Bash qui ne sont pas des opérations du système de fichiers) nécessitent toujours des permissions normales.

204

205**Opérations auto-approuvées :**

206

207* Modifications de fichiers (outils Edit, Write)

208* Commandes du système de fichiers : `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`

209

210Les deux s'appliquent uniquement aux chemins à l'intérieur du répertoire de travail ou de `additionalDirectories`. Les chemins en dehors de cette portée et les écritures vers des chemins protégés demandent toujours.

211

212**À utiliser quand :** vous faites confiance aux modifications de Claude et voulez une itération plus rapide, par exemple lors du prototypage ou lorsque vous travaillez dans un répertoire isolé.

213

214#### Mode de non-demande (`dontAsk`)

215

216Convertit toute invite de permission en refus. Les outils pré-approuvés par `allowed_tools`, les règles d'autorisation de `settings.json` ou un hook s'exécutent normalement. Tout le reste est refusé sans appeler `canUseTool`.

217

218**À utiliser quand :** vous voulez une surface d'outil fixe et explicite pour un agent sans interface et préférez un refus catégorique à une dépendance silencieuse à l'absence de `canUseTool`.

219

220#### Mode de contournement des permissions (`bypassPermissions`)

221

222Auto-approuve tous les usages d'outils sans invites. Les hooks s'exécutent toujours et peuvent bloquer les opérations si nécessaire.

223

224<Warning>

225 À utiliser avec une extrême prudence. Claude a un accès système complet dans ce mode. À utiliser uniquement dans des environnements contrôlés où vous faites confiance à toutes les opérations possibles.

226

227 `allowed_tools` ne contraint pas ce mode. Tous les outils sont approuvés, pas seulement ceux que vous avez listés. Les règles de refus (`disallowed_tools`), les règles `ask` explicites et les hooks sont évalués avant la vérification du mode et peuvent toujours bloquer un outil.

228</Warning>

229

230#### Mode de planification (`plan`)

231

232Restreint Claude aux outils en lecture seule. Claude peut lire des fichiers et exécuter des commandes shell en lecture seule pour explorer la base de code mais ne modifie pas vos fichiers source. Claude peut utiliser `AskUserQuestion` pour clarifier les exigences avant de finaliser le plan. Consultez [Gérer les approbations et les entrées utilisateur](/fr/agent-sdk/user-input#handle-clarifying-questions) pour gérer ces invites.

233

234**À utiliser quand :** vous voulez que Claude propose des modifications sans les exécuter, par exemple lors d'une révision de code ou lorsque vous devez approuver les modifications avant qu'elles ne soient apportées.

235

236## Ressources connexes

237

238Pour les autres étapes du flux d'évaluation des permissions :

239

240* [Gérer les approbations et les entrées utilisateur](/fr/agent-sdk/user-input) : invites d'approbation interactives et questions de clarification

241* [Guide des hooks](/fr/agent-sdk/hooks) : exécutez du code personnalisé à des points clés du cycle de vie de l'agent

242* [Règles de permission](/fr/settings#permission-settings) : règles d'autorisation/refus déclaratives dans `settings.json`

agent-sdk/python.md +41 −39

Details

113#### Paramètres113#### Paramètres

114 114

116| :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------- |116| :------------- | :---------------------------------------------- | :------------------------------------------------------------------------------- |

117| `name` | `str` | Identifiant unique pour l'outil |117| `name` | `str` | Identifiant unique pour l'outil |

118| `description` | `str` | Description lisible de ce que fait l'outil |118| `description` | `str` | Description lisible de ce que fait l'outil |

121 121

122#### Options de schéma d'entrée122#### Options de schéma d'entrée

123 123

269| `cwd` | `str \| None` | Répertoire de travail pour la session |269| `cwd` | `str \| None` | Répertoire de travail pour la session |

270| `tag` | `str \| None` | Étiquette de session définie par l'utilisateur (voir [`tag_session()`](#tag-session)) |270| `tag` | `str \| None` | Étiquette de session définie par l'utilisateur (voir [`tag_session()`](#tag_session)) |

272 272

273#### Exemple273#### Exemple

345 345

346Retourne [`SDKSessionInfo`](#return-type-sdk-session-info), ou `None` si la session n'est pas trouvée.346Retourne [`SDKSessionInfo`](#return-type-sdksessioninfo), ou `None` si la session n'est pas trouvée.

347 347

348#### Exemple348#### Exemple

349 349

381 381

382#### Exemple382#### Exemple

383 383

384Renommez la session la plus récente pour qu'elle soit plus facile à trouver plus tard. Le nouveau titre apparaît dans [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) lors des lectures ultérieures.384Renommez la session la plus récente pour qu'elle soit plus facile à trouver plus tard. Le nouveau titre apparaît dans [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) lors des lectures ultérieures.

385 385

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

477| `set_model(model)` | Change le modèle pour la session actuelle. Passez `None` pour réinitialiser à la valeur par défaut |477| `set_model(model)` | Change le modèle pour la session actuelle. Passez `None` pour réinitialiser à la valeur par défaut |

478| `rewind_files(user_message_id)` | Restaure les fichiers à leur état au message utilisateur spécifié. Nécessite `enable_file_checkpointing=True`. Voir [File checkpointing](/fr/agent-sdk/file-checkpointing) |478| `rewind_files(user_message_id)` | Restaure les fichiers à leur état au message utilisateur spécifié. Nécessite `enable_file_checkpointing=True`. Voir [File checkpointing](/fr/agent-sdk/file-checkpointing) |

479| `get_mcp_status()` | Obtient le statut de tous les serveurs MCP configurés. Retourne [`McpStatusResponse`](#mcp-status-response) |479| `get_mcp_status()` | Obtient le statut de tous les serveurs MCP configurés. Retourne [`McpStatusResponse`](#mcpstatusresponse) |

481| `toggle_mcp_server(server_name, enabled)` | Active ou désactive un serveur MCP en cours de session. La désactivation supprime ses outils |481| `toggle_mcp_server(server_name, enabled)` | Active ou désactive un serveur MCP en cours de session. La désactivation supprime ses outils |

482| `stop_task(task_id)` | Arrête une tâche de fond en cours d'exécution. Un [`TaskNotificationMessage`](#task-notification-message) avec le statut `"stopped"` suit dans le flux de messages |482| `stop_task(task_id)` | Arrête une tâche de fond en cours d'exécution. Un [`TaskNotificationMessage`](#tasknotificationmessage) avec le statut `"stopped"` suit dans le flux de messages |

485 485

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796

797| :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |798| :---------------------------- | :------------------------------------------------------------------------------------ | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuration des outils. Utilisez `{"type": "preset", "preset": "claude_code"}` pour les outils par défaut de Claude Code |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuration des outils. Utilisez `{"type": "preset", "preset": "claude_code"}` pour les outils par défaut de Claude Code |

799| `allowed_tools` | `list[str]` | `[]` | Outils à approuver automatiquement sans demander. Ceci ne restreint pas Claude à seulement ces outils ; les outils non listés passent par `permission_mode` et `can_use_tool`. Utilisez `disallowed_tools` pour bloquer les outils. Voir [Permissions](/fr/agent-sdk/permissions#allow-and-deny-rules) |800| `allowed_tools` | `list[str]` | `[]` | Outils à approuver automatiquement sans demander. Ceci ne restreint pas Claude à seulement ces outils ; les outils non listés passent par `permission_mode` et `can_use_tool`. Utilisez `disallowed_tools` pour bloquer les outils. Voir [Permissions](/fr/agent-sdk/permissions#allow-and-deny-rules) |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuration du prompt système. Passez une chaîne pour un prompt personnalisé, ou utilisez `{"type": "preset", "preset": "claude_code"}` pour le prompt système de Claude Code. Ajoutez `"append"` pour étendre le preset |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuration du prompt système. Passez une chaîne pour un prompt personnalisé, ou utilisez `{"type": "preset", "preset": "claude_code"}` pour le prompt système de Claude Code. Ajoutez `"append"` pour étendre le preset |

812| `output_format` | `dict[str, Any] \| None` | `None` | Format de sortie pour les réponses structurées (par exemple, `{"type": "json_schema", "schema": {...}}`). Voir [Sorties structurées](/fr/agent-sdk/structured-outputs) pour les détails |813| `output_format` | `dict[str, Any] \| None` | `None` | Format de sortie pour les réponses structurées (par exemple, `{"type": "json_schema", "schema": {...}}`). Voir [Sorties structurées](/fr/agent-sdk/structured-outputs) pour les détails |

814| `cwd` | `str \| Path \| None` | `None` | Répertoire de travail actuel |815| `cwd` | `str \| Path \| None` | `None` | Répertoire de travail actuel |

831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Contrôlez quels paramètres du système de fichiers charger. Passez `[]` pour désactiver les paramètres utilisateur, projet et locaux. Les paramètres de politique gérée se chargent indépendamment. Voir [Utiliser les fonctionnalités de Claude Code](/fr/agent-sdk/claude-code-features#what-settingsources-does-not-control) |832| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Contrôlez quels paramètres du système de fichiers charger. Passez `[]` pour désactiver les paramètres utilisateur, projet et locaux. Les paramètres de politique gérée se chargent indépendamment. Voir [Utiliser les fonctionnalités de Claude Code](/fr/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

835| `session_store` | [`SessionStore`](/fr/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Miroir les transcriptions de session vers un backend externe pour que n'importe quel hôte puisse les reprendre. Voir [Persister les sessions vers un stockage externe](/fr/agent-sdk/session-storage) |836| `session_store` | [`SessionStore`](/fr/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Miroir les transcriptions de session vers un backend externe pour que n'importe quel hôte puisse les reprendre. Voir [Persister les sessions vers un stockage externe](/fr/agent-sdk/session-storage) |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quand vider les entrées de transcription en miroir vers `session_store`. `"batched"` vide une fois par tour ou quand le buffer se remplit ; `"eager"` déclenche un vidage en arrière-plan après chaque frame. Ignoré quand `session_store` est `None` |

836 838

837### `OutputFormat`839### `OutputFormat`

838 840

1031| `maxTurns` | Non | Nombre maximum de tours agentiques avant que l'agent s'arrête |1033| `maxTurns` | Non | Nombre maximum de tours agentiques avant que l'agent s'arrête |

1032| `background` | Non | Exécutez cet agent comme une tâche de fond non-bloquante quand invoqué |1034| `background` | Non | Exécutez cet agent comme une tâche de fond non-bloquante quand invoqué |

1033| `effort` | Non | Niveau d'effort de raisonnement pour cet agent. Accepte un niveau nommé ou un entier |1035| `effort` | Non | Niveau d'effort de raisonnement pour cet agent. Accepte un niveau nommé ou un entier |

1034| `permissionMode` | Non | Mode de permission pour l'exécution des outils dans cet agent. Voir [`PermissionMode`](#permission-mode) |1036| `permissionMode` | Non | Mode de permission pour l'exécution des outils dans cet agent. Voir [`PermissionMode`](#permissionmode) |

1035 1037

1036<Note>1038<Note>

1037 Les noms de champs `AgentDefinition` utilisent camelCase, tels que `disallowedTools`, `permissionMode`, et `maxTurns`. Ces noms correspondent directement au format de fil partagé avec le SDK TypeScript. Ceci diffère de `ClaudeAgentOptions`, qui utilise Python snake\_case pour les champs de niveau supérieur équivalents tels que `disallowed_tools` et `permission_mode`. Parce que `AgentDefinition` est une dataclass, passer un mot-clé snake\_case lève une `TypeError` au moment de la construction.1039 Les noms de champs `AgentDefinition` utilisent camelCase, tels que `disallowedTools`, `permissionMode`, et `maxTurns`. Ces noms correspondent directement au format de fil partagé avec le SDK TypeScript. Ceci diffère de `ClaudeAgentOptions`, qui utilise Python snake\_case pour les champs de niveau supérieur équivalents tels que `disallowed_tools` et `permission_mode`. Parce que `AgentDefinition` est une dataclass, passer un mot-clé snake\_case lève une `TypeError` au moment de la construction.

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084

1084| :------------ | :----------------------- | :------------------------------------------------ |1086| :------------ | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1086| `suggestions` | `list[PermissionUpdate]` | Suggestions de mise à jour de permission du CLI |1088| `suggestions` | `list[PermissionUpdate]` | Suggestions de mise à jour de permission du CLI. Les prompts Bash incluent une suggestion avec la destination `localSettings`, donc la retourner dans `updated_permissions` écrit la règle dans `.claude/settings.local.json` et persiste entre les sessions. |

1087 1089

1088### `PermissionResult`1090### `PermissionResult`

1089 1091

1289 1291

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293

1292La configuration d'un serveur MCP telle que rapportée par [`get_mcp_status()`](#methods). C'est l'union de toutes les variantes de transport [`McpServerConfig`](#mcp-server-config) plus une variante de sortie uniquement `claudeai-proxy` pour les serveurs proxifiés via claude.ai.1294La configuration d'un serveur MCP telle que rapportée par [`get_mcp_status()`](#methods). C'est l'union de toutes les variantes de transport [`McpServerConfig`](#mcpserverconfig) plus une variante de sortie uniquement `claudeai-proxy` pour les serveurs proxifiés via claude.ai.

1293 1295

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305

1304`McpSdkServerConfigStatus` est la forme sérialisable de [`McpSdkServerConfig`](#mcp-sdk-server-config) avec seulement les champs `type` (`"sdk"`) et `name` (`str`) ; l'`instance` en processus est omise. `McpClaudeAIProxyServerConfig` a les champs `type` (`"claudeai-proxy"`), `url` (`str`), et `id` (`str`).1306`McpSdkServerConfigStatus` est la forme sérialisable de [`McpSdkServerConfig`](#mcpsdkserverconfig) avec seulement les champs `type` (`"sdk"`) et `name` (`str`) ; l'`instance` en processus est omise. `McpClaudeAIProxyServerConfig` a les champs `type` (`"claudeai-proxy"`), `url` (`str`), et `id` (`str`).

1305 1307

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309

1314 1316

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318

1317Statut d'un serveur MCP connecté, contenu dans [`McpStatusResponse`](#mcp-status-response).1319Statut d'un serveur MCP connecté, contenu dans [`McpStatusResponse`](#mcpstatusresponse).

1318 1320

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331

1331| :----------- | :--------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1333| :----------- | :------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1332| `name` | `str` | Nom du serveur |1334| `name` | `str` | Nom du serveur |

1333| `status` | `str` | L'un de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, ou `"disabled"` |1335| `status` | `str` | L'un de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, ou `"disabled"` |

1334| `serverInfo` | `dict` (optionnel) | Nom et version du serveur (`{"name": str, "version": str}`) |1336| `serverInfo` | `dict` (optionnel) | Nom et version du serveur (`{"name": str, "version": str}`) |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (optionnel) | Configuration du serveur. Même forme que [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, ou SDK), plus une variante `claudeai-proxy` pour les serveurs connectés via claude.ai |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (optionnel) | Configuration du serveur. Même forme que [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, ou SDK), plus une variante `claudeai-proxy` pour les serveurs connectés via claude.ai |

1339 1341

1416```1418```

1417 1419

1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |1421| :------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------- |

1421| `model` | `str` | Modèle qui a généré la réponse |1423| `model` | `str` | Modèle qui a généré la réponse |

1426 1428

1427### `AssistantMessageError`1429### `AssistantMessageError`

1481| `cache_creation_input_tokens` | `int` | Tokens utilisés pour créer de nouvelles entrées de cache. |1483| `cache_creation_input_tokens` | `int` | Tokens utilisés pour créer de nouvelles entrées de cache. |

1482| `cache_read_input_tokens` | `int` | Tokens lus à partir des entrées de cache existantes. |1484| `cache_read_input_tokens` | `int` | Tokens lus à partir des entrées de cache existantes. |

1483 1485

1484Le dict `model_usage` mappe les noms de modèles à l'utilisation par modèle. Les clés du dict interne utilisent camelCase parce que la valeur est passée inchangée du processus CLI sous-jacent, correspondant au type TypeScript [`ModelUsage`](/fr/agent-sdk/typescript#model-usage) :1486Le dict `model_usage` mappe les noms de modèles à l'utilisation par modèle. Les clés du dict interne utilisent camelCase parce que la valeur est passée inchangée du processus CLI sous-jacent, correspondant au type TypeScript [`ModelUsage`](/fr/agent-sdk/typescript#modelusage) :

1485 1487

1486| Clé | Type | Description |1488| Clé | Type | Description |

1487| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |1489| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1488| `inputTokens` | `int` | Tokens d'entrée pour ce modèle. |1490| `inputTokens` | `int` | Tokens d'entrée pour ce modèle. |

1489| `outputTokens` | `int` | Tokens de sortie pour ce modèle. |1491| `outputTokens` | `int` | Tokens de sortie pour ce modèle. |

1490| `cacheReadInputTokens` | `int` | Tokens de lecture de cache pour ce modèle. |1492| `cacheReadInputTokens` | `int` | Tokens de lecture de cache pour ce modèle. |

1491| `cacheCreationInputTokens` | `int` | Tokens de création de cache pour ce modèle. |1493| `cacheCreationInputTokens` | `int` | Tokens de création de cache pour ce modèle. |

1492| `webSearchRequests` | `int` | Requêtes de recherche web effectuées par ce modèle. |1494| `webSearchRequests` | `int` | Requêtes de recherche web effectuées par ce modèle. |

1493| `costUSD` | `float` | Coût estimé en USD pour ce modèle, calculé côté client. Voir [Track cost and usage](/fr/agent-sdk/cost-tracking) pour les avertissements de facturation. |1495| `costUSD` | `float` | Coût estimé en USD pour ce modèle, calculé côté client. Voir [Suivre le coût et l'utilisation](/fr/agent-sdk/cost-tracking) pour les avertissements de facturation. |

1494| `contextWindow` | `int` | Taille de la fenêtre de contexte pour ce modèle. |1496| `contextWindow` | `int` | Taille de la fenêtre de contexte pour ce modèle. |

1495| `maxOutputTokens` | `int` | Limite de tokens de sortie maximum pour ce modèle. |1497| `maxOutputTokens` | `int` | Limite de tokens de sortie maximum pour ce modèle. |

1496 1498

1527```1529```

1528 1530

1530| :---------------- | :---------------------------------- | :-------------------------------- |1532| :---------------- | :-------------------------------- | :-------------------------------- |

1532| `uuid` | `str` | Identifiant d'événement unique |1534| `uuid` | `str` | Identifiant d'événement unique |

1533| `session_id` | `str` | Identifiant de session |1535| `session_id` | `str` | Identifiant de session |

1534 1536

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538

1537État de limite de débit porté par [`RateLimitEvent`](#rate-limit-event).1539État de limite de débit porté par [`RateLimitEvent`](#ratelimitevent).

1538 1540

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1812 1814

1813Paramètres :1815Paramètres :

1814 1816

1815* `input` : Entrée de hook fortement typée avec unions discriminées basées sur `hook_event_name` (voir [`HookInput`](#hook-input))1817* `input` : Entrée de hook fortement typée avec unions discriminées basées sur `hook_event_name` (voir [`HookInput`](#hookinput))

1816* `tool_use_id` : Identifiant d'utilisation d'outil optionnel (pour les hooks liés aux outils)1818* `tool_use_id` : Identifiant d'utilisation d'outil optionnel (pour les hooks liés aux outils)

1817* `context` : Contexte de hook avec des informations supplémentaires1819* `context` : Contexte de hook avec des informations supplémentaires

1818 1820

1819Retourne un [`HookJSONOutput`](#hook-json-output) qui peut contenir :1821Retourne un [`HookJSONOutput`](#hookjsonoutput) qui peut contenir :

1820 1822

1821* `decision` : `"block"` pour bloquer l'action1823* `decision` : `"block"` pour bloquer l'action

1822* `systemMessage` : Message système à ajouter à la transcription1824* `systemMessage` : Message système à ajouter à la transcription

2119 2121

2120#### `HookSpecificOutput`2122#### `HookSpecificOutput`

2121 2123

2122Un `TypedDict` contenant le nom d'événement de hook et les champs spécifiques à l'événement. La forme dépend de la valeur `hookEventName`. Pour les détails complets sur les champs disponibles par événement de hook, voir [Control execution with hooks](/fr/agent-sdk/hooks#outputs).2124Un `TypedDict` contenant le nom d'événement de hook et les champs spécifiques à l'événement. La forme dépend de la valeur `hookEventName`. Pour les détails complets sur les champs disponibles par événement de hook, voir [Contrôler l'exécution avec les hooks](/fr/agent-sdk/hooks#outputs).

2123 2125

2124Une union discriminée de types de sortie spécifiques à l'événement. Le champ `hookEventName` détermine quels champs sont valides.2126Une union discriminée de types de sortie spécifiques à l'événement. Le champ `hookEventName` détermine quels champs sont valides.

2125 2127

3109```3111```

3110 3112

3112| :-------------------------- | :------------------------------------------------------ | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3114| :-------------------------- | :---------------------------------------------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3115| `excludedCommands` | `list[str]` | `[]` | Commandes qui contournent toujours les restrictions du sandbox (par exemple, `["docker"]`). Celles-ci s'exécutent sans sandbox automatiquement sans implication du modèle |3117| `excludedCommands` | `list[str]` | `[]` | Commandes qui contournent toujours les restrictions du sandbox (par exemple, `["docker"]`). Celles-ci s'exécutent sans sandbox automatiquement sans implication du modèle |

3116| `allowUnsandboxedCommands` | `bool` | `True` | Permettez au modèle de demander l'exécution de commandes en dehors du sandbox. Quand `True`, le modèle peut définir `dangerouslyDisableSandbox` dans l'entrée d'outil, qui revient au [système de permissions](#permissions-fallback-for-unsandboxed-commands) |3118| `allowUnsandboxedCommands` | `bool` | `True` | Permettez au modèle de demander l'exécution de commandes en dehors du sandbox. Quand `True`, le modèle peut définir `dangerouslyDisableSandbox` dans l'entrée d'outil, qui revient au [système de permissions](#permissions-fallback-for-unsandboxed-commands) |

3120 3122

3121#### Exemple d'utilisation3123#### Exemple d'utilisation

agent-sdk/streaming-output.md +396 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Diffuser les réponses en temps réel

7> Recevez les réponses en temps réel du SDK Agent à mesure que le texte et les appels d'outils sont diffusés

9Par défaut, le SDK Agent produit des objets `AssistantMessage` complets après que Claude ait terminé de générer chaque réponse. Pour recevoir des mises à jour incrémentielles à mesure que le texte et les appels d'outils sont générés, activez la diffusion de messages partiels en définissant `include_partial_messages` (Python) ou `includePartialMessages` (TypeScript) sur `true` dans vos options.

11<Tip>

12 Cette page couvre la diffusion de sortie (réception des jetons en temps réel). Pour les modes d'entrée (comment vous envoyez les messages), consultez [Envoyer des messages aux agents](/fr/agent-sdk/streaming-vs-single-mode). Vous pouvez également [diffuser les réponses en utilisant le SDK Agent via la CLI](/fr/headless).

13</Tip>

15## Activer la diffusion de sortie

17Pour activer la diffusion, définissez `include_partial_messages` (Python) ou `includePartialMessages` (TypeScript) sur `true` dans vos options. Cela fait que le SDK produit des messages `StreamEvent` contenant les événements API bruts à mesure qu'ils arrivent, en plus des `AssistantMessage` et `ResultMessage` habituels.

19Votre code doit alors :

211. Vérifier le type de chaque message pour distinguer `StreamEvent` des autres types de messages

222. Pour `StreamEvent`, extraire le champ `event` et vérifier son `type`

233. Rechercher les événements `content_block_delta` où `delta.type` est `text_delta`, qui contiennent les fragments de texte réels

25L'exemple ci-dessous active la diffusion et affiche les fragments de texte à mesure qu'ils arrivent. Remarquez les vérifications de type imbriquées : d'abord pour `StreamEvent`, puis pour `content_block_delta`, puis pour `text_delta` :

27<CodeGroup>

28 ```python Python theme={null}

29 from claude_agent_sdk import query, ClaudeAgentOptions

30 from claude_agent_sdk.types import StreamEvent

31 import asyncio

34 async def stream_response():

35 options = ClaudeAgentOptions(

36 include_partial_messages=True,

37 allowed_tools=["Bash", "Read"],

38 )

40 async for message in query(prompt="List the files in my project", options=options):

41 if isinstance(message, StreamEvent):

42 event = message.event

43 if event.get("type") == "content_block_delta":

44 delta = event.get("delta", {})

45 if delta.get("type") == "text_delta":

46 print(delta.get("text", ""), end="", flush=True)

49 asyncio.run(stream_response())

50 ```

52 ```typescript TypeScript theme={null}

53 import { query } from "@anthropic-ai/claude-agent-sdk";

55 for await (const message of query({

56 prompt: "List the files in my project",

57 options: {

58 includePartialMessages: true,

59 allowedTools: ["Bash", "Read"]

60 }

61 })) {

62 if (message.type === "stream_event") {

63 const event = message.event;

64 if (event.type === "content_block_delta") {

65 if (event.delta.type === "text_delta") {

66 process.stdout.write(event.delta.text);

67 }

68 }

69 }

70 }

71 ```

72</CodeGroup>

74## Référence StreamEvent

76Lorsque les messages partiels sont activés, vous recevez les événements de diffusion bruts de l'API Claude enveloppés dans un objet. Le type a des noms différents dans chaque SDK :

78* **Python** : `StreamEvent` (importer depuis `claude_agent_sdk.types`)

79* **TypeScript** : `SDKPartialAssistantMessage` avec `type: 'stream_event'`

81Les deux contiennent les événements bruts de l'API Claude, pas le texte accumulé. Vous devez extraire et accumuler les deltas de texte vous-même. Voici la structure de chaque type :

83<CodeGroup>

84 ```python Python theme={null}

85 @dataclass

86 class StreamEvent:

87 uuid: str # Unique identifier for this event

88 session_id: str # Session identifier

89 event: dict[str, Any] # The raw Claude API stream event

90 parent_tool_use_id: str | None # Parent tool ID if from a subagent

91 ```

93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {

95 type: "stream_event";

96 event: BetaRawMessageStreamEvent; // From Anthropic SDK

97 parent_tool_use_id: string | null;

98 uuid: UUID;

99 session_id: string;

100 };

101 ```

102</CodeGroup>

103

104Le champ `event` contient l'événement de diffusion brut de l'[API Claude](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). Les types d'événements courants incluent :

105

106| Type d'événement | Description |

107| :-------------------- | :---------------------------------------------------------------- |

108| `message_start` | Début d'un nouveau message |

109| `content_block_start` | Début d'un nouveau bloc de contenu (texte ou utilisation d'outil) |

110| `content_block_delta` | Mise à jour incrémentielles du contenu |

111| `content_block_stop` | Fin d'un bloc de contenu |

112| `message_delta` | Mises à jour au niveau du message (raison d'arrêt, utilisation) |

113| `message_stop` | Fin du message |

114

115## Flux de messages

116

117Avec les messages partiels activés, vous recevez les messages dans cet ordre :

118

119```text theme={null}

120StreamEvent (message_start)

121StreamEvent (content_block_start) - text block

122StreamEvent (content_block_delta) - text chunks...

123StreamEvent (content_block_stop)

124StreamEvent (content_block_start) - tool_use block

125StreamEvent (content_block_delta) - tool input chunks...

126StreamEvent (content_block_stop)

127StreamEvent (message_delta)

128StreamEvent (message_stop)

129AssistantMessage - complete message with all content

130... tool executes ...

131... more streaming events for next turn ...

132ResultMessage - final result

133```

134

135Sans les messages partiels activés (`include_partial_messages` en Python, `includePartialMessages` en TypeScript), vous recevez tous les types de messages sauf `StreamEvent`. Les types courants incluent `SystemMessage` (initialisation de session), `AssistantMessage` (réponses complètes), `ResultMessage` (résultat final), et un message de limite compact indiquant quand l'historique de conversation a été compacté (`SDKCompactBoundaryMessage` en TypeScript ; `SystemMessage` avec le sous-type `"compact_boundary"` en Python).

136

137## Diffuser les réponses texte

138

139Pour afficher le texte à mesure qu'il est généré, recherchez les événements `content_block_delta` où `delta.type` est `text_delta`. Ceux-ci contiennent les fragments de texte incrémentiels. L'exemple ci-dessous affiche chaque fragment à mesure qu'il arrive :

140

141<CodeGroup>

142 ```python Python theme={null}

143 from claude_agent_sdk import query, ClaudeAgentOptions

144 from claude_agent_sdk.types import StreamEvent

145 import asyncio

146

147

148 async def stream_text():

149 options = ClaudeAgentOptions(include_partial_messages=True)

150

151 async for message in query(prompt="Explain how databases work", options=options):

152 if isinstance(message, StreamEvent):

153 event = message.event

154 if event.get("type") == "content_block_delta":

155 delta = event.get("delta", {})

156 if delta.get("type") == "text_delta":

157 # Print each text chunk as it arrives

158 print(delta.get("text", ""), end="", flush=True)

159

160 print() # Final newline

161

162

163 asyncio.run(stream_text())

164 ```

165

166 ```typescript TypeScript theme={null}

167 import { query } from "@anthropic-ai/claude-agent-sdk";

168

169 for await (const message of query({

170 prompt: "Explain how databases work",

171 options: { includePartialMessages: true }

172 })) {

173 if (message.type === "stream_event") {

174 const event = message.event;

175 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

176 process.stdout.write(event.delta.text);

177 }

178 }

179 }

180

181 console.log(); // Final newline

182 ```

183</CodeGroup>

184

185## Diffuser les appels d'outils

186

187Les appels d'outils sont également diffusés de manière incrémentielles. Vous pouvez suivre quand les outils commencent, recevoir leur entrée à mesure qu'elle est générée, et voir quand ils se terminent. L'exemple ci-dessous suit l'outil actuellement appelé et accumule l'entrée JSON à mesure qu'elle est diffusée. Il utilise trois types d'événements :

188

189* `content_block_start` : l'outil commence

190* `content_block_delta` avec `input_json_delta` : les fragments d'entrée arrivent

191* `content_block_stop` : l'appel d'outil est complet

192

193<CodeGroup>

194 ```python Python theme={null}

195 from claude_agent_sdk import query, ClaudeAgentOptions

196 from claude_agent_sdk.types import StreamEvent

197 import asyncio

198

199

200 async def stream_tool_calls():

201 options = ClaudeAgentOptions(

202 include_partial_messages=True,

203 allowed_tools=["Read", "Bash"],

204 )

205

206 # Track the current tool and accumulate its input JSON

207 current_tool = None

208 tool_input = ""

209

210 async for message in query(prompt="Read the README.md file", options=options):

211 if isinstance(message, StreamEvent):

212 event = message.event

213 event_type = event.get("type")

214

215 if event_type == "content_block_start":

216 # New tool call is starting

217 content_block = event.get("content_block", {})

218 if content_block.get("type") == "tool_use":

219 current_tool = content_block.get("name")

220 tool_input = ""

221 print(f"Starting tool: {current_tool}")

222

223 elif event_type == "content_block_delta":

224 delta = event.get("delta", {})

225 if delta.get("type") == "input_json_delta":

226 # Accumulate JSON input as it streams in

227 chunk = delta.get("partial_json", "")

228 tool_input += chunk

229 print(f" Input chunk: {chunk}")

230

231 elif event_type == "content_block_stop":

232 # Tool call complete - show final input

233 if current_tool:

234 print(f"Tool {current_tool} called with: {tool_input}")

235 current_tool = None

236

237

238 asyncio.run(stream_tool_calls())

239 ```

240

241 ```typescript TypeScript theme={null}

242 import { query } from "@anthropic-ai/claude-agent-sdk";

243

244 // Track the current tool and accumulate its input JSON

245 let currentTool: string | null = null;

246 let toolInput = "";

247

248 for await (const message of query({

249 prompt: "Read the README.md file",

250 options: {

251 includePartialMessages: true,

252 allowedTools: ["Read", "Bash"]

253 }

254 })) {

255 if (message.type === "stream_event") {

256 const event = message.event;

257

258 if (event.type === "content_block_start") {

259 // New tool call is starting

260 if (event.content_block.type === "tool_use") {

261 currentTool = event.content_block.name;

262 toolInput = "";

263 console.log(`Starting tool: ${currentTool}`);

264 }

265 } else if (event.type === "content_block_delta") {

266 if (event.delta.type === "input_json_delta") {

267 // Accumulate JSON input as it streams in

268 const chunk = event.delta.partial_json;

269 toolInput += chunk;

270 console.log(` Input chunk: ${chunk}`);

271 }

272 } else if (event.type === "content_block_stop") {

273 // Tool call complete - show final input

274 if (currentTool) {

275 console.log(`Tool ${currentTool} called with: ${toolInput}`);

276 currentTool = null;

277 }

278 }

279 }

280 }

281 ```

282</CodeGroup>

283

284## Construire une interface utilisateur de diffusion

285

286Cet exemple combine la diffusion de texte et d'outils dans une interface utilisateur cohésive. Il suit si l'agent exécute actuellement un outil (en utilisant un drapeau `in_tool`) pour afficher des indicateurs de statut comme `[Using Read...]` pendant que les outils s'exécutent. Le texte se diffuse normalement quand il n'y a pas d'outil, et la fin de l'outil déclenche un message « done ». Ce modèle est utile pour les interfaces de chat qui doivent afficher la progression pendant les tâches d'agent multi-étapes.

287

288<CodeGroup>

289 ```python Python theme={null}

290 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

291 from claude_agent_sdk.types import StreamEvent

292 import asyncio

293 import sys

294

295

296 async def streaming_ui():

297 options = ClaudeAgentOptions(

298 include_partial_messages=True,

299 allowed_tools=["Read", "Bash", "Grep"],

300 )

301

302 # Track whether we're currently in a tool call

303 in_tool = False

304

305 async for message in query(

306 prompt="Find all TODO comments in the codebase", options=options

307 ):

308 if isinstance(message, StreamEvent):

309 event = message.event

310 event_type = event.get("type")

311

312 if event_type == "content_block_start":

313 content_block = event.get("content_block", {})

314 if content_block.get("type") == "tool_use":

315 # Tool call is starting - show status indicator

316 tool_name = content_block.get("name")

317 print(f"\n[Using {tool_name}...]", end="", flush=True)

318 in_tool = True

319

320 elif event_type == "content_block_delta":

321 delta = event.get("delta", {})

322 # Only stream text when not executing a tool

323 if delta.get("type") == "text_delta" and not in_tool:

324 sys.stdout.write(delta.get("text", ""))

325 sys.stdout.flush()

326

327 elif event_type == "content_block_stop":

328 if in_tool:

329 # Tool call finished

330 print(" done", flush=True)

331 in_tool = False

332

333 elif isinstance(message, ResultMessage):

334 # Agent finished all work

335 print(f"\n\n--- Complete ---")

336

337

338 asyncio.run(streaming_ui())

339 ```

340

341 ```typescript TypeScript theme={null}

342 import { query } from "@anthropic-ai/claude-agent-sdk";

343

344 // Track whether we're currently in a tool call

345 let inTool = false;

346

347 for await (const message of query({

348 prompt: "Find all TODO comments in the codebase",

349 options: {

350 includePartialMessages: true,

351 allowedTools: ["Read", "Bash", "Grep"]

352 }

353 })) {

354 if (message.type === "stream_event") {

355 const event = message.event;

356

357 if (event.type === "content_block_start") {

358 if (event.content_block.type === "tool_use") {

359 // Tool call is starting - show status indicator

360 process.stdout.write(`\n[Using ${event.content_block.name}...]`);

361 inTool = true;

362 }

363 } else if (event.type === "content_block_delta") {

364 // Only stream text when not executing a tool

365 if (event.delta.type === "text_delta" && !inTool) {

366 process.stdout.write(event.delta.text);

367 }

368 } else if (event.type === "content_block_stop") {

369 if (inTool) {

370 // Tool call finished

371 console.log(" done");

372 inTool = false;

373 }

374 }

375 } else if (message.type === "result") {

376 // Agent finished all work

377 console.log("\n\n--- Complete ---");

378 }

379 }

380 ```

381</CodeGroup>

382

383## Limitations connues

384

385Certaines fonctionnalités du SDK sont incompatibles avec la diffusion :

386

387* **Réflexion étendue** : lorsque vous définissez explicitement `max_thinking_tokens` (Python) ou `maxThinkingTokens` (TypeScript), les messages `StreamEvent` ne sont pas émis. Vous recevrez uniquement les messages complets après chaque tour. Notez que la réflexion est désactivée par défaut dans le SDK, donc la diffusion fonctionne sauf si vous l'activez.

388* **Sortie structurée** : le résultat JSON n'apparaît que dans le `ResultMessage.structured_output` final, pas comme des deltas de diffusion. Consultez [les sorties structurées](/fr/agent-sdk/structured-outputs) pour plus de détails.

389

390## Étapes suivantes

391

392Maintenant que vous pouvez diffuser le texte et les appels d'outils en temps réel, explorez ces sujets connexes :

393

394* [Requêtes interactives ou ponctuelles](/fr/agent-sdk/streaming-vs-single-mode) : choisissez entre les modes d'entrée pour votre cas d'usage

395* [Sorties structurées](/fr/agent-sdk/structured-outputs) : obtenez des réponses JSON typées de l'agent

396* [Permissions](/fr/agent-sdk/permissions) : contrôlez les outils que l'agent peut utiliser

agent-sdk/todo-tracking.md +189 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Listes de tâches

7> Suivre et afficher les tâches à l'aide du SDK Claude Agent pour une gestion organisée des tâches

9Le suivi des tâches fournit un moyen structuré de gérer les tâches et d'afficher la progression aux utilisateurs. Le SDK Claude Agent inclut une fonctionnalité de tâches intégrée qui aide à organiser les flux de travail complexes et à tenir les utilisateurs informés de la progression des tâches.

11### Cycle de vie des tâches

13Les tâches suivent un cycle de vie prévisible :

151. **Créées** en tant que `pending` lorsque les tâches sont identifiées

162. **Activées** en tant que `in_progress` lorsque le travail commence

173. **Complétées** lorsque la tâche se termine avec succès

184. **Supprimées** lorsque toutes les tâches d'un groupe sont complétées

20### Quand les tâches sont utilisées

22Le SDK crée automatiquement des tâches pour :

24* **Les tâches complexes multi-étapes** nécessitant 3 actions distinctes ou plus

25* **Les listes de tâches fournies par l'utilisateur** lorsque plusieurs éléments sont mentionnés

26* **Les opérations non triviales** qui bénéficient du suivi de la progression

27* **Les demandes explicites** lorsque les utilisateurs demandent une organisation des tâches

29## Exemples

31### Surveillance des modifications des tâches

33<CodeGroup>

34 ```typescript TypeScript theme={null}

35 import { query } from "@anthropic-ai/claude-agent-sdk";

37 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",

39 options: { maxTurns: 15 }

40 })) {

41 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {

43 for (const block of message.message.content) {

44 if (block.type === "tool_use" && block.name === "TodoWrite") {

45 const todos = block.input.todos;

47 console.log("Todo Status Update:");

48 todos.forEach((todo, index) => {

49 const status =

50 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

51 console.log(`${index + 1}. ${status} ${todo.content}`);

52 });

53 }

54 }

55 }

56 }

57 ```

59 ```python Python theme={null}

60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

62 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",

64 options=ClaudeAgentOptions(max_turns=15),

65 ):

66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):

68 for block in message.content:

69 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

70 todos = block.input["todos"]

72 print("Todo Status Update:")

73 for i, todo in enumerate(todos):

74 status = (

75 "✅"

76 if todo["status"] == "completed"

77 else "🔧"

78 if todo["status"] == "in_progress"

79 else "❌"

80 )

81 print(f"{i + 1}. {status} {todo['content']}")

82 ```

83</CodeGroup>

85### Affichage de la progression en temps réel

87<CodeGroup>

88 ```typescript TypeScript theme={null}

89 import { query } from "@anthropic-ai/claude-agent-sdk";

91 class TodoTracker {

92 private todos: any[] = [];

94 displayProgress() {

95 if (this.todos.length === 0) return;

97 const completed = this.todos.filter((t) => t.status === "completed").length;

98 const inProgress = this.todos.filter((t) => t.status === "in_progress").length;

99 const total = this.todos.length;

100

101 console.log(`\nProgress: ${completed}/${total} completed`);

102 console.log(`Currently working on: ${inProgress} task(s)\n`);

103

104 this.todos.forEach((todo, index) => {

105 const icon =

106 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

107 const text = todo.status === "in_progress" ? todo.activeForm : todo.content;

108 console.log(`${index + 1}. ${icon} ${text}`);

109 });

110 }

111

112 async trackQuery(prompt: string) {

113 for await (const message of query({

114 prompt,

115 options: { maxTurns: 20 }

116 })) {

117 if (message.type === "assistant") {

118 for (const block of message.message.content) {

119 if (block.type === "tool_use" && block.name === "TodoWrite") {

120 this.todos = block.input.todos;

121 this.displayProgress();

122 }

123 }

124 }

125 }

126 }

127 }

128

129 // Usage

130 const tracker = new TodoTracker();

131 await tracker.trackQuery("Build a complete authentication system with todos");

132 ```

133

134 ```python Python theme={null}

135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict

137

138

139 class TodoTracker:

140 def __init__(self):

141 self.todos: List[Dict] = []

142

143 def display_progress(self):

144 if not self.todos:

145 return

146

147 completed = len([t for t in self.todos if t["status"] == "completed"])

148 in_progress = len([t for t in self.todos if t["status"] == "in_progress"])

149 total = len(self.todos)

150

151 print(f"\nProgress: {completed}/{total} completed")

152 print(f"Currently working on: {in_progress} task(s)\n")

153

154 for i, todo in enumerate(self.todos):

155 icon = (

156 "✅"

157 if todo["status"] == "completed"

158 else "🔧"

159 if todo["status"] == "in_progress"

160 else "❌"

161 )

162 text = (

163 todo["activeForm"]

164 if todo["status"] == "in_progress"

165 else todo["content"]

166 )

167 print(f"{i + 1}. {icon} {text}")

168

169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):

172 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

174 self.todos = block.input["todos"]

175 self.display_progress()

176

177

178 # Usage

179 tracker = TodoTracker()

180 await tracker.track_query("Build a complete authentication system with todos")

181 ```

182</CodeGroup>

183

184## Documentation connexe

185

186* [Référence du SDK TypeScript](/fr/agent-sdk/typescript)

187* [Référence du SDK Python](/fr/agent-sdk/python)

188* [Mode streaming vs mode unique](/fr/agent-sdk/streaming-vs-single-mode)

189* [Outils personnalisés](/fr/agent-sdk/custom-tools)

agent-sdk/typescript.md +31 −31

Details

41#### Paramètres41#### Paramètres

42 42

~~44| :-------- | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------- |~~44| :-------- | :--------------------------------------------------------------- | :---------------------------------------------------------------------------------------- |

47 47

48#### Retours48#### Retours

49 49

~~50Retourne un objet [`Query`](#query-object) qui étend `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` avec des méthodes supplémentaires.~~50Retourne un objet [`Query`](#query-object) qui étend `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` avec des méthodes supplémentaires.

51 51

52### `startup()`52### `startup()`

53 53

54Préconfigure le sous-processus CLI en le générant et en complétant la poignée de main d'initialisation avant qu'une invite soit disponible. Le handle [`WarmQuery`](#warm-query) retourné accepte une invite plus tard et l'écrit dans un processus déjà prêt, de sorte que le premier appel `query()` se résout sans payer le coût de génération et d'initialisation du sous-processus en ligne.54Préconfigure le sous-processus CLI en le générant et en complétant la poignée de main d'initialisation avant qu'une invite soit disponible. Le handle [`WarmQuery`](#warmquery) retourné accepte une invite plus tard et l'écrit dans un processus déjà prêt, de sorte que le premier appel `query()` se résout sans payer le coût de génération et d'initialisation du sous-processus en ligne.

55 55

56```typescript theme={null}56```typescript theme={null}

57function startup(params?: {57function startup(params?: {

69 69

70#### Retours70#### Retours

71 71

~~72Retourne une `Promise<`[`WarmQuery`](#warm-query)`>` qui se résout une fois que le sous-processus a été généré et a complété sa poignée de main d'initialisation.~~72Retourne une `Promise<`[`WarmQuery`](#warmquery)`>` qui se résout une fois que le sous-processus a été généré et a complété sa poignée de main d'initialisation.

73 73

74#### Exemple74#### Exemple

75 75

104#### Paramètres104#### Paramètres

105 105

107| :------------ | :------------------------------------------------------------------ | :---------------------------------------------------------------------------------- |107| :------------ | :---------------------------------------------------------------- | :---------------------------------------------------------------------------------- |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | Annotations MCP optionnelles fournissant des indices comportementaux aux clients |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Annotations MCP optionnelles fournissant des indices comportementaux aux clients |

113 113

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115

191 191

192#### Exemple192#### Exemple

272 272

273Retourne [`SDKSessionInfo`](#return-type-sdk-session-info), ou `undefined` si la session n'est pas trouvée.273Retourne [`SDKSessionInfo`](#return-type-sdksessioninfo), ou `undefined` si la session n'est pas trouvée.

274 274

275### `renameSession()`275### `renameSession()`

276 276

328| `allowedTools` | `string[]` | `[]` | Outils à approuver automatiquement sans demander. Cela ne restreint pas Claude à seulement ces outils ; les outils non répertoriés passent à `permissionMode` et `canUseTool`. Utilisez `disallowedTools` pour bloquer les outils. Voir [Permissions](/fr/agent-sdk/permissions#allow-and-deny-rules) |328| `allowedTools` | `string[]` | `[]` | Outils à approuver automatiquement sans demander. Cela ne restreint pas Claude à seulement ces outils ; les outils non répertoriés passent à `permissionMode` et `canUseTool`. Utilisez `disallowedTools` pour bloquer les outils. Voir [Permissions](/fr/agent-sdk/permissions#allow-and-deny-rules) |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | Arguments supplémentaires |341| `extraArgs` | `Record<string, string \| null>` | `{}` | Arguments supplémentaires |

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Rappels de hook pour les événements |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Rappels de hook pour les événements |

346| `maxBudgetUsd` | `number` | `undefined` | Arrêter la requête quand l'estimation du coût côté client atteint cette valeur en USD. Comparé à la même estimation que `total_cost_usd` ; voir [Suivi des coûts et de l'utilisation](/fr/agent-sdk/cost-tracking) pour les avertissements de précision |346| `maxBudgetUsd` | `number` | `undefined` | Arrêter la requête quand l'estimation du coût côté client atteint cette valeur en USD. Comparé à la même estimation que `total_cost_usd` ; voir [Suivi des coûts et de l'utilisation](/fr/agent-sdk/cost-tracking) pour les avertissements de précision |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | Configurations de serveur MCP |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurations de serveur MCP |

351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Définir le format de sortie pour les résultats de l'agent. Voir [Sorties structurées](/fr/agent-sdk/structured-outputs) pour les détails |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Définir le format de sortie pour les résultats de l'agent. Voir [Sorties structurées](/fr/agent-sdk/structured-outputs) pour les détails |

352| `pathToClaudeCodeExecutable` | `string` | Résolu automatiquement à partir du binaire natif groupé | 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 figure pas dans l'ensemble pris en charge |352| `pathToClaudeCodeExecutable` | `string` | Résolu automatiquement à partir du binaire natif groupé | 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 figure pas dans l'ensemble pris en charge |

362| `sessionStore` | [`SessionStore`](/fr/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Refléter les transcriptions de session vers un backend externe pour que n'importe quel hôte puisse les reprendre. Voir [Persister les sessions vers un stockage externe](/fr/agent-sdk/session-storage) |362| `sessionStore` | [`SessionStore`](/fr/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Refléter les transcriptions de session vers un backend externe pour que n'importe quel hôte puisse les reprendre. Voir [Persister les sessions vers un stockage externe](/fr/agent-sdk/session-storage) |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | Paramètres par défaut de CLI (toutes les sources) | Contrôler les paramètres du système de fichiers à charger. Passez `[]` pour désactiver les paramètres utilisateur, projet et locaux. Les paramètres de politique gérée se chargent indépendamment. Voir [Utiliser les fonctionnalités Claude Code](/fr/agent-sdk/claude-code-features#what-settingsources-does-not-control) |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | Paramètres par défaut de CLI (toutes les sources) | Contrôler les paramètres du système de fichiers à charger. Passez `[]` pour désactiver les paramètres utilisateur, projet et locaux. Les paramètres de politique gérée se chargent indépendamment. Voir [Utiliser les fonctionnalités Claude Code](/fr/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Fonction personnalisée pour générer le processus Claude Code. Utilisez pour exécuter Claude Code dans des VM, des conteneurs ou des environnements distants |364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Fonction personnalisée pour générer le processus Claude Code. Utilisez pour exécuter Claude Code dans des VM, des conteneurs ou des environnements distants |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (invite minimale) | Configuration de l'invite système. Passez une chaîne pour une invite personnalisée, ou `{ type: 'preset', preset: 'claude_code' }` pour utiliser l'invite système de Claude Code. Lors de l'utilisation de la forme d'objet prédéfini, ajoutez `append` pour l'étendre avec des instructions supplémentaires, et définissez `excludeDynamicSections: true` pour déplacer le contexte par session dans le premier message utilisateur pour une [meilleure réutilisation du cache d'invite sur les machines](/fr/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (invite minimale) | Configuration de l'invite système. Passez une chaîne pour une invite personnalisée, ou `{ type: 'preset', preset: 'claude_code' }` pour utiliser l'invite système de Claude Code. Lors de l'utilisation de la forme d'objet prédéfini, ajoutez `append` pour l'étendre avec des instructions supplémentaires, et définissez `excludeDynamicSections: true` pour déplacer le contexte par session dans le premier message utilisateur pour une [meilleure réutilisation du cache d'invite sur les machines](/fr/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

368| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` pour les modèles pris en charge | Contrôle le comportement de réflexion/raisonnement de Claude. Voir [`ThinkingConfig`](#thinking-config) pour les options |368| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` pour les modèles pris en charge | Contrôle le comportement de réflexion/raisonnement de Claude. Voir [`ThinkingConfig`](#thinkingconfig) pour les options |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuration des outils. Passez un tableau de noms d'outils ou utilisez le prédéfini pour obtenir les outils par défaut de Claude Code |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuration des outils. Passez un tableau de noms d'outils ou utilisez le prédéfini pour obtenir les outils par défaut de Claude Code |

371 371

372### Objet `Query`372### Objet `Query`

410| `initializationResult()` | Retourne le résultat d'initialisation complet incluant les commandes prises en charge, les modèles, les informations de compte et la configuration du style de sortie |410| `initializationResult()` | Retourne le résultat d'initialisation complet incluant les commandes prises en charge, les modèles, les informations de compte et la configuration du style de sortie |

493| `background` | Non | Exécuter cet agent en tant que tâche de fond non-bloquante quand invoqué |493| `background` | Non | Exécuter cet agent en tant que tâche de fond non-bloquante quand invoqué |

494| `memory` | Non | Source de mémoire pour cet agent : `'user'`, `'project'`, ou `'local'` |494| `memory` | Non | Source de mémoire pour cet agent : `'user'`, `'project'`, ou `'local'` |

495| `effort` | Non | Niveau d'effort de raisonnement pour cet agent. Accepte un niveau nommé ou un entier |495| `effort` | Non | Niveau d'effort de raisonnement pour cet agent. Accepte un niveau nommé ou un entier |

496| `permissionMode` | Non | Mode de permission pour l'exécution des outils dans cet agent. Voir [`PermissionMode`](#permission-mode) |496| `permissionMode` | Non | Mode de permission pour l'exécution des outils dans cet agent. Voir [`PermissionMode`](#permissionmode) |

497| `criticalSystemReminder_EXPERIMENTAL` | Non | Expérimental : Rappel critique ajouté à l'invite système |497| `criticalSystemReminder_EXPERIMENTAL` | Non | Expérimental : Rappel critique ajouté à l'invite système |

498 498

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // Comportement de permission standard626 | "default" // Comportement de permission standard

627 | "acceptEdits" // Accepter automatiquement les modifications de fichiers627 | "acceptEdits" // Accepter automatiquement les modifications de fichiers

628 | "bypassPermissions" // Contourner tous les contrôles de permission628 | "bypassPermissions" // Contourner tous les contrôles de permission

629 | "plan" // Mode de planification - pas d'exécution629 | "plan" // Mode de planification - outils en lecture seule uniquement

630 | "dontAsk" // Ne pas demander les permissions, refuser si non pré-approuvé630 | "dontAsk" // Ne pas demander les permissions, refuser si non pré-approuvé

631 | "auto"; // Utiliser un classificateur de modèle pour approuver ou refuser chaque appel d'outil631 | "auto"; // Utiliser un classificateur de modèle pour approuver ou refuser chaque appel d'outil

632```632```

651```651```

652 652

654| :--------------- | :------------------------------------------- | :------------------------------------------------------------------------------------------------------ |654| :--------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | Mises à jour de permission suggérées pour que l'utilisateur ne soit pas invité à nouveau pour cet outil |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Mises à jour de permission suggérées pour que l'utilisateur ne soit pas invité à nouveau pour cet outil. Les invites Bash incluent une suggestion avec la destination [`localSettings`](#permissionupdatedestination), donc retourner dans `updatedPermissions` écrit la règle à `.claude/settings.local.json` et persiste entre les sessions. |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381

2382Voir [`McpServerConfig`](#mcp-server-config) pour les détails sur chaque type de transport.2382Voir [`McpServerConfig`](#mcpserverconfig) pour les détails sur chaque type de transport.

2383 2383

2384### `AccountInfo`2384### `AccountInfo`

2385 2385

2825```2825```

2826 2826

2828| :-------------------------- | :------------------------------------------------------ | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2831| `excludedCommands` | `string[]` | `[]` | Commandes qui contournent toujours les restrictions du sandbox (par exemple, `['docker']`). Celles-ci s'exécutent sans sandbox automatiquement sans implication du modèle |2831| `excludedCommands` | `string[]` | `[]` | Commandes qui contournent toujours les restrictions du sandbox (par exemple, `['docker']`). Celles-ci s'exécutent sans sandbox automatiquement sans implication du modèle |

2832| `allowUnsandboxedCommands` | `boolean` | `true` | Permettre au modèle de demander l'exécution de commandes en dehors du sandbox. Quand `true`, le modèle peut définir `dangerouslyDisableSandbox` dans l'entrée de l'outil, qui revient au [système de permissions](#permissions-fallback-for-unsandboxed-commands) |2832| `allowUnsandboxedCommands` | `boolean` | `true` | Permettre au modèle de demander l'exécution de commandes en dehors du sandbox. Quand `true`, le modèle peut définir `dangerouslyDisableSandbox` dans l'entrée de l'outil, qui revient au [système de permissions](#permissions-fallback-for-unsandboxed-commands) |

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Carte des catégories de violation aux motifs à ignorer (par exemple, `{ file: ['/tmp/*'], network: ['localhost'] }`) |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Carte des catégories de violation aux motifs à ignorer (par exemple, `{ file: ['/tmp/*'], network: ['localhost'] }`) |

2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuration de binaire ripgrep personnalisée pour les environnements sandbox |2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuration de binaire ripgrep personnalisée pour les environnements sandbox |

data-usage.md +1 −1

Details

67 67

68Le diagramme ci-dessous montre comment Claude Code se connecte aux services externes lors de l'installation et du fonctionnement normal. Les lignes pleines indiquent les connexions requises, tandis que les lignes pointillées représentent les flux de données optionnels ou initiés par l'utilisateur.68Le diagramme ci-dessous montre comment Claude Code se connecte aux services externes lors de l'installation et du fonctionnement normal. Les lignes pleines indiquent les connexions requises, tandis que les lignes pointillées représentent les flux de données optionnels ou initiés par l'utilisateur.

69 69

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Diagramme montrant les connexions externes de Claude Code : l'installation/mise à jour se connecte au serveur de distribution, et les demandes des utilisateurs se connectent aux services Anthropic, y compris l'authentification Console, l'API publique, et optionnellement Statsig, Sentry et les rapports de bogues" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Diagramme montrant les connexions externes de Claude Code : l'installation/mise à jour se connecte au serveur de distribution, et les demandes des utilisateurs se connectent aux services Anthropic, y compris l'authentification Console, l'API publique, et optionnellement Statsig, Sentry et les rapports de bogues" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71

72Claude Code s'exécute localement. Pour interagir avec le LLM, Claude Code envoie des données sur le réseau. Ces données incluent tous les invites utilisateur et les sorties du modèle, chiffrées en transit via TLS 1.2+. Claude Code est compatible avec la plupart des VPN et proxies LLM populaires.72Claude Code s'exécute localement. Pour interagir avec le LLM, Claude Code envoie des données sur le réseau. Ces données incluent tous les invites utilisateur et les sorties du modèle, chiffrées en transit via TLS 1.2+. Claude Code est compatible avec la plupart des VPN et proxies LLM populaires.

73 73

desktop.md +5 −3

Details

282 282

283### Travailler en parallèle avec les sessions283### Travailler en parallèle avec les sessions

284 284

285Cliquez sur **+ Nouvelle session** dans la barre latérale, ou appuyez sur **Cmd+N** sur macOS ou **Ctrl+N** sur Windows, pour travailler sur plusieurs tâches en parallèle. Appuyez sur **Ctrl+Tab** et **Ctrl+Shift+Tab** pour parcourir les sessions dans la barre latérale. Pour les référentiels Git, chaque session obtient sa propre copie isolée de votre projet en utilisant [Git worktrees](/fr/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), donc les modifications dans une session n'affectent pas les autres sessions jusqu'à ce que vous les validiez.285Cliquez sur **+ Nouvelle session** dans la barre latérale, ou appuyez sur **Cmd+N** sur macOS ou **Ctrl+N** sur Windows, pour travailler sur plusieurs tâches en parallèle. Appuyez sur **Ctrl+Tab** et **Ctrl+Shift+Tab** pour parcourir les sessions dans la barre latérale. Pour les référentiels Git, chaque session obtient sa propre copie isolée de votre projet en utilisant [Git worktrees](/fr/worktrees), donc les modifications dans une session n'affectent pas les autres sessions jusqu'à ce que vous les validiez.

286

287Pour afficher deux sessions à la fois, maintenez **Cmd** sur macOS ou **Ctrl** sur Windows et cliquez sur une session dans la barre latérale. La session s'ouvre dans un deuxième volet à côté de celui que vous avez déjà ouvert. Pendant que la division est active, cliquer sur une autre session de la barre latérale remplace le volet qui a le focus. Appuyez sur **Cmd+\\** sur macOS ou **Ctrl+\\** sur Windows pour fermer le volet actif et revenir à une seule session.

286 288

287Les worktrees sont stockés dans `<project-root>/.claude/worktrees/` par défaut. Vous pouvez modifier ceci en un répertoire personnalisé dans Paramètres → Claude Code sous « Emplacement du worktree ». Vous pouvez également définir un préfixe de branche qui est ajouté au début de chaque nom de branche worktree, ce qui est utile pour garder les branches créées par Claude organisées. Pour supprimer un worktree quand vous avez terminé, survolez la session dans la barre latérale et cliquez sur l'icône d'archive. Pour avoir les sessions s'archiver elles-mêmes quand leur demande de tirage fusionne ou se ferme, activez **Auto-archive après fusion ou fermeture de PR** dans Paramètres → Claude Code. L'auto-archive s'applique uniquement aux sessions locales qui ont terminé l'exécution.289Les worktrees sont stockés dans `<project-root>/.claude/worktrees/` par défaut. Vous pouvez modifier ceci en un répertoire personnalisé dans Paramètres → Claude Code sous « Emplacement du worktree ». Vous pouvez également définir un préfixe de branche qui est ajouté au début de chaque nom de branche worktree, ce qui est utile pour garder les branches créées par Claude organisées. Pour supprimer un worktree quand vous avez terminé, survolez la session dans la barre latérale et cliquez sur l'icône d'archive. Pour avoir les sessions s'archiver elles-mêmes quand leur demande de tirage fusionne ou se ferme, activez **Auto-archive après fusion ou fermeture de PR** dans Paramètres → Claude Code. L'auto-archive s'applique uniquement aux sessions locales qui ont terminé l'exécution.

288 290

289Pour inclure les fichiers ignorés par git comme `.env` dans les nouveaux worktrees, créez un [fichier `.worktreeinclude`](/fr/common-workflows#copy-gitignored-files-to-worktrees) à la racine de votre projet.291Pour inclure les fichiers ignorés par git comme `.env` dans les nouveaux worktrees, créez un [fichier `.worktreeinclude`](/fr/worktrees#copy-gitignored-files-into-worktrees) à la racine de votre projet.

290 292

291<Note>293<Note>

292 L'isolation des sessions nécessite [Git](https://git-scm.com/downloads). La plupart des Macs incluent Git par défaut. Exécutez `git --version` dans Terminal pour vérifier. Sur Windows, Git est requis pour que l'onglet Code fonctionne : [téléchargez Git pour Windows](https://git-scm.com/downloads/win), installez-le et redémarrez l'application. Si vous rencontrez des erreurs Git, demandez à Claude dans l'[onglet Cowork](https://claude.com/product/cowork) de vous aider à dépanner votre configuration.294 L'isolation des sessions nécessite [Git](https://git-scm.com/downloads). La plupart des Macs incluent Git par défaut. Exécutez `git --version` dans Terminal pour vérifier. Sur Windows, Git est requis pour que l'onglet Code fonctionne : [téléchargez Git pour Windows](https://git-scm.com/downloads/win), installez-le et redémarrez l'application. Si vous rencontrez des erreurs Git, demandez à Claude dans l'[onglet Cowork](https://claude.com/product/cowork) de vous aider à dépanner votre configuration.

516 518

517Pour définir les variables d'environnement pour les sessions locales et les serveurs de développement sur n'importe quelle plateforme, ouvrez la liste déroulante d'environnement dans la zone de prompt, survolez **Local** et cliquez sur l'icône d'engrenage pour ouvrir l'éditeur d'environnement local. Les variables que vous enregistrez ici sont stockées chiffrées sur votre machine et s'appliquent à chaque session locale et serveur d'aperçu que vous démarrez. Vous pouvez également ajouter des variables à la clé `env` dans votre fichier `~/.claude/settings.json`, bien que celles-ci n'atteignent que les sessions Claude et non les serveurs de développement. Voir [variables d'environnement](/fr/env-vars) pour la liste complète des variables supportées.519Pour définir les variables d'environnement pour les sessions locales et les serveurs de développement sur n'importe quelle plateforme, ouvrez la liste déroulante d'environnement dans la zone de prompt, survolez **Local** et cliquez sur l'icône d'engrenage pour ouvrir l'éditeur d'environnement local. Les variables que vous enregistrez ici sont stockées chiffrées sur votre machine et s'appliquent à chaque session locale et serveur d'aperçu que vous démarrez. Vous pouvez également ajouter des variables à la clé `env` dans votre fichier `~/.claude/settings.json`, bien que celles-ci n'atteignent que les sessions Claude et non les serveurs de développement. Voir [variables d'environnement](/fr/env-vars) pour la liste complète des variables supportées.

518 520

519[La réflexion étendue](/fr/common-workflows#use-extended-thinking-thinking-mode) est activée par défaut, ce qui améliore les performances sur les tâches de raisonnement complexe mais utilise des tokens supplémentaires. Pour désactiver complètement la réflexion, définissez `MAX_THINKING_TOKENS` à `0` dans l'éditeur d'environnement local. Sur les modèles avec [raisonnement adaptatif](/fr/model-config#adjust-effort-level), toute autre valeur `MAX_THINKING_TOKENS` est ignorée car le raisonnement adaptatif contrôle la profondeur de la réflexion à la place. Sur Opus 4.6 et Sonnet 4.6, définissez `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` à `1` pour utiliser un budget de réflexion fixe ; Opus 4.7 utilise toujours le raisonnement adaptatif et n'a pas de mode de budget fixe.521[La réflexion étendue](/fr/model-config#extended-thinking) est activée par défaut, ce qui améliore les performances sur les tâches de raisonnement complexe mais utilise des tokens supplémentaires. Pour désactiver complètement la réflexion, définissez `MAX_THINKING_TOKENS` à `0` dans l'éditeur d'environnement local. Sur les modèles avec [raisonnement adaptatif](/fr/model-config#adjust-effort-level), toute autre valeur `MAX_THINKING_TOKENS` est ignorée car le raisonnement adaptatif contrôle la profondeur de la réflexion à la place. Sur Opus 4.6 et Sonnet 4.6, définissez `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` à `1` pour utiliser un budget de réflexion fixe ; Opus 4.7 utilise toujours le raisonnement adaptatif et n'a pas de mode de budget fixe.

520 522

521### Sessions distantes523### Sessions distantes

522 524

features-overview.md +51 −14

Details

12 Pour savoir comment fonctionne la boucle agentive principale, consultez [Comment fonctionne Claude Code](/fr/how-claude-code-works).12 Pour savoir comment fonctionne la boucle agentive principale, consultez [Comment fonctionne Claude Code](/fr/how-claude-code-works).

13</Note>13</Note>

14 14

~~15**Nouveau dans Claude Code ?** Commencez par [CLAUDE.md](/fr/memory) pour les conventions de projet. Ajoutez d'autres extensions au fur et à mesure de vos besoins.~~15**Nouveau dans Claude Code ?** Commencez par [CLAUDE.md](/fr/memory) pour les conventions de projet, puis ajoutez d'autres extensions [au fur et à mesure que des déclencheurs spécifiques se présentent](#build-your-setup-over-time).

16 16

17## Aperçu17## Aperçu

18 18

23* **[MCP](/fr/mcp)** connecte Claude à des services et outils externes23* **[MCP](/fr/mcp)** connecte Claude à des services et outils externes

24* **[Subagents](/fr/sub-agents)** exécutent leurs propres boucles dans un contexte isolé, en retournant des résumés24* **[Subagents](/fr/sub-agents)** exécutent leurs propres boucles dans un contexte isolé, en retournant des résumés

25* **[Agent teams](/fr/agent-teams)** coordonnent plusieurs sessions indépendantes avec des tâches partagées et une messagerie pair à pair25* **[Agent teams](/fr/agent-teams)** coordonnent plusieurs sessions indépendantes avec des tâches partagées et une messagerie pair à pair

~~26* **[Hooks](/fr/hooks)** s'exécutent en dehors de la boucle entièrement en tant que scripts déterministes~~26* **[Hooks](/fr/hooks-guide)** se déclenchent sur des événements du cycle de vie et peuvent exécuter un script, une requête HTTP, une invite ou un subagent

27* **[Plugins](/fr/plugins)** et **[marketplaces](/fr/plugin-marketplaces)** empaquettent et distribuent ces fonctionnalités27* **[Plugins](/fr/plugins)** et **[marketplaces](/fr/plugin-marketplaces)** empaquettent et distribuent ces fonctionnalités

28 28

29[Skills](/fr/skills) sont l'extension la plus flexible. Une skill est un fichier markdown contenant des connaissances, des flux de travail ou des instructions. Vous pouvez invoquer des skills avec une commande comme `/deploy`, ou Claude peut les charger automatiquement quand elles sont pertinentes. Les skills peuvent s'exécuter dans votre conversation actuelle ou dans un contexte isolé via des subagents.29[Skills](/fr/skills) sont l'extension la plus flexible. Une skill est un fichier markdown contenant des connaissances, des flux de travail ou des instructions. Vous pouvez invoquer des skills avec une commande comme `/deploy`, ou Claude peut les charger automatiquement quand elles sont pertinentes. Les skills peuvent s'exécuter dans votre conversation actuelle ou dans un contexte isolé via des subagents.

39| **Subagent** | Contexte d'exécution isolé qui retourne des résultats résumés | Isolation du contexte, tâches parallèles, travailleurs spécialisés | Tâche de recherche qui lit de nombreux fichiers mais retourne uniquement les conclusions clés |39| **Subagent** | Contexte d'exécution isolé qui retourne des résultats résumés | Isolation du contexte, tâches parallèles, travailleurs spécialisés | Tâche de recherche qui lit de nombreux fichiers mais retourne uniquement les conclusions clés |

40| **[Agent teams](/fr/agent-teams)** | Coordonnez plusieurs sessions Claude Code indépendantes | Recherche parallèle, développement de nouvelles fonctionnalités, débogage avec hypothèses concurrentes | Générez des relecteurs pour vérifier la sécurité, les performances et les tests simultanément |40| **[Agent teams](/fr/agent-teams)** | Coordonnez plusieurs sessions Claude Code indépendantes | Recherche parallèle, développement de nouvelles fonctionnalités, débogage avec hypothèses concurrentes | Générez des relecteurs pour vérifier la sécurité, les performances et les tests simultanément |

41| **MCP** | Connectez-vous à des services externes | Données ou actions externes | Interrogez votre base de données, publiez sur Slack, contrôlez un navigateur |41| **MCP** | Connectez-vous à des services externes | Données ou actions externes | Interrogez votre base de données, publiez sur Slack, contrôlez un navigateur |

43 43

44**[Plugins](/fr/plugins)** sont la couche d'empaquetage. Un plugin regroupe des skills, des hooks, des subagents et des serveurs MCP dans une seule unité installable. Les skills de plugin sont espacées de noms (comme `/my-plugin:review`) afin que plusieurs plugins puissent coexister. Utilisez les plugins quand vous voulez réutiliser la même configuration sur plusieurs référentiels ou distribuer à d'autres via une **[marketplace](/fr/plugin-marketplaces)**.44**[Plugins](/fr/plugins)** sont la couche d'empaquetage. Un plugin regroupe des skills, des hooks, des subagents et des serveurs MCP dans une seule unité installable. Les skills de plugin sont espacées de noms (comme `/my-plugin:review`) afin que plusieurs plugins puissent coexister. Utilisez les plugins quand vous voulez réutiliser la même configuration sur plusieurs référentiels ou distribuer à d'autres via une **[marketplace](/fr/plugin-marketplaces)**.

45 45

46### Construire votre configuration au fil du temps

48Vous n'avez pas besoin de tout configurer à l'avance. Chaque fonctionnalité a un déclencheur reconnaissable, et la plupart des équipes les ajoutent à peu près dans cet ordre :

50| Déclencheur | Ajouter |

51| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |

52| Claude se trompe sur une convention ou une commande deux fois | Ajoutez-la à [CLAUDE.md](/fr/memory) |

53| Vous continuez à taper la même invite pour démarrer une tâche | Enregistrez-la en tant que [skill](/fr/skills) invocable par l'utilisateur |

54| Vous collez le même playbook ou procédure multi-étapes dans le chat pour la troisième fois | Capturez-la en tant que [skill](/fr/skills) |

55| Vous continuez à copier des données d'un onglet de navigateur que Claude ne peut pas voir | Connectez ce système en tant que [serveur MCP](/fr/mcp) |

56| Une tâche secondaire inonde votre conversation avec une sortie que vous ne référencerez plus | Acheminez-la via un [subagent](/fr/sub-agents) |

57| Vous voulez que quelque chose se produise à chaque fois sans demander | Écrivez un [hook](/fr/hooks-guide) |

58| Un deuxième référentiel a besoin de la même configuration | Empaquetez-la en tant que [plugin](/fr/plugins) |

60Les mêmes déclencheurs vous indiquent quand mettre à jour ce que vous avez déjà. Une erreur répétée ou un commentaire d'examen récurrent est une modification de CLAUDE.md, pas une correction ponctuelle dans le chat. Un flux de travail que vous continuez à ajuster manuellement est une skill qui a besoin d'une autre révision.

46### Comparer les fonctionnalités similaires62### Comparer les fonctionnalités similaires

47 63

48Certaines fonctionnalités peuvent sembler similaires. Voici comment les distinguer.64Certaines fonctionnalités peuvent sembler similaires. Voici comment les distinguer.

55 * **Subagents** sont des travailleurs isolés qui s'exécutent séparément de votre conversation principale71 * **Subagents** sont des travailleurs isolés qui s'exécutent séparément de votre conversation principale

56 72

~~58 | ----------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------- |~~74 | ---------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------- |

77 | **Impact de la [fenêtre de contexte](/fr/context-window)** | S'ajoute à votre fenêtre principale | Utilise une fenêtre séparée avec ses propres tokens d'entrée et de sortie |

62 79

63 **Les skills peuvent être de référence ou d'action.** Les skills de référence fournissent des connaissances que Claude utilise tout au long de votre session (comme votre guide de style API). Les skills d'action disent à Claude de faire quelque chose de spécifique (comme `/deploy` qui exécute votre flux de travail de déploiement).80 **Les skills peuvent être de référence ou d'action.** Les skills de référence fournissent des connaissances que Claude utilise tout au long de votre session (comme votre guide de style API). Les skills d'action disent à Claude de faire quelque chose de spécifique (comme `/deploy` qui exécute votre flux de travail de déploiement).

142 159

143 Exemple : Un serveur MCP connecte Claude à votre base de données. Une skill enseigne à Claude votre modèle de données, les modèles de requête courants et les tables à utiliser pour différentes tâches.160 Exemple : Un serveur MCP connecte Claude à votre base de données. Une skill enseigne à Claude votre modèle de données, les modèles de requête courants et les tables à utiliser pour différentes tâches.

144 </Tab>161 </Tab>

162

163 <Tab title="Hook vs Skill">

164 Un hook se déclenche sur un événement du cycle de vie ; une skill est chargée dans le contexte pour que Claude l'applique.

165

166 | Aspect | Hook | Skill |

167 | -------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |

168 | **S'exécute** | Une commande shell, une requête HTTP, une invite LLM ou un subagent | Instructions que Claude lit et suit |

169 | **Déclenché par** | [Événements du cycle de vie](/fr/hooks#hook-events) tels que `PostToolUse` ou `SessionStart` | Vous tapant `/<name>`, ou Claude correspondant à la description de votre tâche |

170 | **Déterminisme** | Se déclenche toujours sur son événement ; le déclencheur est garanti | Claude interprète les instructions ; le résultat peut varier |

171 | **Coût du contexte** | Zéro sauf si le hook retourne une sortie | La description se charge à chaque session ; le contenu complet se charge quand utilisé |

172 | **Meilleur pour** | Linting après les modifications, blocage des commandes dangereuses, journalisation, notifications | Flux de travail qui nécessitent du raisonnement, matériel de référence, tâches multi-étapes |

173

174 **Utilisez un hook** quand l'action doit se produire de la même manière à chaque fois et n'a pas besoin que Claude réfléchisse. Par exemple : formater à la sauvegarde, rejeter `rm -rf /`, publier un message Slack quand une session se termine.

175

176 **Utilisez une skill** quand Claude devrait décider comment appliquer les étapes, ou quand le contenu est une connaissance plutôt qu'un script. Par exemple : une liste de contrôle `/release`, votre guide de style API, un playbook de débogage.

177

178 **Mettez les garde-fous dans les hooks.** Une instruction comme « ne jamais modifier `.env` » dans CLAUDE.md ou une skill est une demande, pas une garantie. Un hook `PreToolUse` qui bloque la modification est une application. Si une règle doit tenir à chaque fois, faites-en un hook plutôt qu'une instruction d'invite.

179

180 **La sortie du hook atterrit dans le contexte.** Un hook `PostToolUse` qui exécute votre linter alimente les résultats en tant que texte que Claude lit ; une skill `/fix-lint` dit à Claude comment les résoudre.

181 </Tab>

145</Tabs>182</Tabs>

146 183

147### Comprendre comment les fonctionnalités se superposent184### Comprendre comment les fonctionnalités se superposent

151* **Les fichiers CLAUDE.md** sont additifs : tous les niveaux contribuent du contenu au contexte de Claude simultanément. Les fichiers de votre répertoire de travail et au-dessus se chargent au lancement ; les sous-répertoires se chargent au fur et à mesure que vous y travaillez. Quand les instructions entrent en conflit, Claude utilise son jugement pour les réconcilier, les instructions plus spécifiques ayant généralement la priorité. Consultez [comment les fichiers CLAUDE.md se chargent](/fr/memory#how-claudemd-files-load).188* **Les fichiers CLAUDE.md** sont additifs : tous les niveaux contribuent du contenu au contexte de Claude simultanément. Les fichiers de votre répertoire de travail et au-dessus se chargent au lancement ; les sous-répertoires se chargent au fur et à mesure que vous y travaillez. Quand les instructions entrent en conflit, Claude utilise son jugement pour les réconcilier, les instructions plus spécifiques ayant généralement la priorité. Consultez [comment les fichiers CLAUDE.md se chargent](/fr/memory#how-claudemd-files-load).

152* **Les skills et subagents** se remplacent par nom : quand le même nom existe à plusieurs niveaux, une définition gagne en fonction de la priorité (géré > utilisateur > projet pour les skills ; géré > drapeau CLI > projet > utilisateur > plugin pour les subagents). Les skills de plugin sont [espacées de noms](/fr/plugins#add-skills-to-your-plugin) pour éviter les conflits. Consultez [découverte de skills](/fr/skills#where-skills-live) et [portée du subagent](/fr/sub-agents#choose-the-subagent-scope).189* **Les skills et subagents** se remplacent par nom : quand le même nom existe à plusieurs niveaux, une définition gagne en fonction de la priorité (géré > utilisateur > projet pour les skills ; géré > drapeau CLI > projet > utilisateur > plugin pour les subagents). Les skills de plugin sont [espacées de noms](/fr/plugins#add-skills-to-your-plugin) pour éviter les conflits. Consultez [découverte de skills](/fr/skills#where-skills-live) et [portée du subagent](/fr/sub-agents#choose-the-subagent-scope).

153* **Les serveurs MCP** se remplacent par nom : local > projet > utilisateur. Consultez [portée MCP](/fr/mcp#scope-hierarchy-and-precedence).190* **Les serveurs MCP** se remplacent par nom : local > projet > utilisateur. Consultez [portée MCP](/fr/mcp#scope-hierarchy-and-precedence).

154* **Les hooks** fusionnent : tous les hooks enregistrés se déclenchent pour leurs événements correspondants indépendamment de la source. Consultez [hooks](/fr/hooks).191* **Les hooks** fusionnent : tous les hooks enregistrés se déclenchent pour leurs événements correspondants indépendamment de la source. Consultez [hooks](/fr/hooks-guide).

155 192

156### Combiner les fonctionnalités193### Combiner les fonctionnalités

157 194

163| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |200| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |

164| **Skill + MCP** | MCP fournit la connexion ; une skill enseigne à Claude comment l'utiliser bien | MCP se connecte à votre base de données, une skill documente votre schéma et les modèles de requête |201| **Skill + MCP** | MCP fournit la connexion ; une skill enseigne à Claude comment l'utiliser bien | MCP se connecte à votre base de données, une skill documente votre schéma et les modèles de requête |

165| **Skill + Subagent** | Une skill génère des subagents pour le travail parallèle | La skill `/audit` lance des subagents de sécurité, de performance et de style qui travaillent dans un contexte isolé |202| **Skill + Subagent** | Une skill génère des subagents pour le travail parallèle | La skill `/audit` lance des subagents de sécurité, de performance et de style qui travaillent dans un contexte isolé |

166| **CLAUDE.md + Skills** | CLAUDE.md contient les règles toujours actives ; les skills contiennent le matériel de référence chargé à la demande | CLAUDE.md dit ' suivez nos conventions API ', une skill contient le guide de style API complet |203| **CLAUDE.md + Skills** | CLAUDE.md contient les règles toujours actives ; les skills contiennent le matériel de référence chargé à la demande | CLAUDE.md dit « suivez nos conventions API », une skill contient le guide de style API complet |

168 205

169## Comprendre les coûts du contexte206## Comprendre les coûts du contexte

170 207

171Chaque fonctionnalité que vous ajoutez consomme une partie du contexte de Claude. Trop peut remplir votre fenêtre de contexte, mais cela peut aussi ajouter du bruit qui rend Claude moins efficace ; les skills peuvent ne pas se déclencher correctement, ou Claude peut perdre de vue vos conventions. Comprendre ces compromis vous aide à construire une configuration efficace.208Chaque fonctionnalité que vous ajoutez consomme une partie du contexte de Claude. Trop peut remplir votre fenêtre de contexte, mais cela peut aussi ajouter du bruit qui rend Claude moins efficace ; les skills peuvent ne pas se déclencher correctement, ou Claude peut perdre de vue vos conventions. Comprendre ces compromis vous aide à construire une configuration efficace. Pour une vue interactive de la façon dont ces fonctionnalités se combinent dans une session en cours d'exécution, consultez [Explorez la fenêtre de contexte](/fr/context-window).

172 209

173### Coût du contexte par fonctionnalité210### Coût du contexte par fonctionnalité

174 211

178| ---------------- | -------------------------------- | -------------------------------------------------------- | --------------------------------------------------------- |215| ---------------- | -------------------------------- | -------------------------------------------------------- | --------------------------------------------------------- |

184 221

188 225

189Chaque fonctionnalité se charge à différents points de votre session. Les onglets ci-dessous expliquent quand chacune se charge et ce qui entre dans le contexte.226Chaque fonctionnalité se charge à différents points de votre session. Les onglets ci-dessous expliquent quand chacune se charge et ce qui entre dans le contexte.

190 227

191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Chargement du contexte : CLAUDE.md et MCP se chargent au début de la session et restent dans chaque requête. Les skills chargent les descriptions au démarrage, le contenu complet à l'invocation. Les subagents obtiennent un contexte isolé. Les hooks s'exécutent en externe." width="720" height="410" data-path="images/context-loading.svg" />228<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Chargement du contexte : CLAUDE.md se charge au début de la session et reste dans chaque requête. Les noms d'outils MCP se chargent au démarrage avec les schémas complets reportés jusqu'à utilisation. Les skills chargent les descriptions au démarrage, le contenu complet à l'invocation. Les subagents obtiennent un contexte isolé. Les hooks s'exécutent en externe." width="720" height="410" data-path="images/context-loading.svg" />

192 229

193<Tabs>230<Tabs>

194 <Tab title="CLAUDE.md">231 <Tab title="CLAUDE.md">

202 </Tab>239 </Tab>

203 240

204 <Tab title="Skills">241 <Tab title="Skills">

205 Les skills sont des capacités supplémentaires dans la boîte à outils de Claude. Elles peuvent être du matériel de référence (comme un guide de style API) ou des flux de travail invocables que vous déclenchez avec `/<name>` (comme `/deploy`). Claude Code est livré avec des [skills groupées](/fr/skills#bundled-skills) comme `/simplify`, `/batch` et `/debug` qui fonctionnent directement. Vous pouvez également créer les vôtres. Claude utilise les skills quand approprié, ou vous pouvez en invoquer une directement.242 Les skills sont des capacités supplémentaires dans la boîte à outils de Claude. Elles peuvent être du matériel de référence (comme un guide de style API) ou des flux de travail invocables que vous déclenchez avec `/<name>` (comme `/deploy`). Claude Code inclut des [skills groupées](/fr/commands) comme `/simplify`, `/batch` et `/debug` qui fonctionnent directement. Vous pouvez également créer les vôtres. Claude utilise les skills quand approprié, ou vous pouvez en invoquer une directement.

206 243

207 **Quand :** Dépend de la configuration de la skill. Par défaut, les descriptions se chargent au début de la session et le contenu complet se charge quand utilisé. Pour les skills utilisateur uniquement (`disable-model-invocation: true`), rien ne se charge jusqu'à ce que vous les invoquiez.244 **Quand :** Dépend de la configuration de la skill. Par défaut, les descriptions se chargent au début de la session et le contenu complet se charge quand utilisé. Pour les skills utilisateur uniquement (`disable-model-invocation: true`), rien ne se charge jusqu'à ce que vous les invoquiez.

208 245

220 <Tab title="Serveurs MCP">257 <Tab title="Serveurs MCP">

221 **Quand :** Début de session.258 **Quand :** Début de session.

222 259

223 **Ce qui se charge :** Toutes les définitions d'outils et schémas JSON des serveurs connectés.260 **Ce qui se charge :** Noms d'outils des serveurs connectés. Les schémas JSON complets restent reportés jusqu'à ce que Claude ait besoin d'un outil spécifique.

224 261

225 **Coût du contexte :** [Recherche d'outils](/fr/mcp#scale-with-mcp-tool-search) (activée par défaut) charge les outils MCP jusqu'à 10 % du contexte et reporte le reste jusqu'à ce qu'il soit nécessaire.262 **Coût du contexte :** [Recherche d'outils](/fr/mcp#scale-with-mcp-tool-search) est activée par défaut, donc les outils MCP inactifs consomment un contexte minimal.

226 263

227 **Note de fiabilité :** Les connexions MCP peuvent échouer silencieusement en milieu de session. Si un serveur se déconnecte, ses outils disparaissent sans avertissement. Claude peut essayer d'utiliser un outil qui n'existe plus. Si vous remarquez que Claude ne peut pas utiliser un outil MCP auquel il pouvait accéder précédemment, vérifiez la connexion avec `/mcp`.264 **Note de fiabilité :** Les connexions MCP peuvent échouer silencieusement en milieu de session. Si un serveur se déconnecte, ses outils disparaissent sans avertissement. Claude peut essayer d'utiliser un outil qui n'existe plus. Si vous remarquez que Claude ne peut pas utiliser un outil MCP auquel il pouvait accéder précédemment, vérifiez la connexion avec `/mcp`.

228 265

245 </Tab>282 </Tab>

246 283

247 <Tab title="Hooks">284 <Tab title="Hooks">

248 **Quand :** Au déclenchement. Les hooks se déclenchent à des événements de cycle de vie spécifiques comme l'exécution d'outils, les limites de session, la soumission d'invite, les demandes de permission et la compaction. Consultez [Hooks](/fr/hooks) pour la liste complète.285 **Quand :** Au déclenchement. Les hooks se déclenchent à des événements de cycle de vie spécifiques comme l'exécution d'outils, les limites de session, la soumission d'invite, les demandes de permission et la compaction. Consultez [Hooks](/fr/hooks-guide) pour la liste complète.

249 286

250 **Ce qui se charge :** Rien par défaut. Les hooks s'exécutent en tant que scripts externes.287 **Ce qui se charge :** Rien par défaut. Les hooks s'exécutent en dehors de la conversation principale.

251 288

252 **Coût du contexte :** Zéro, sauf si le hook retourne une sortie qui est ajoutée en tant que messages à votre conversation.289 **Coût du contexte :** Zéro, sauf si le hook retourne une sortie qui est ajoutée en tant que messages à votre conversation.

253 290

hooks.md +4 −4

Details

970Pour bloquer un prompt, retournez un objet JSON avec `decision` défini à `"block"` :970Pour bloquer un prompt, retournez un objet JSON avec `decision` défini à `"block"` :

971 971

972| Champ | Description |972| Champ | Description |

973| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------- |973| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------ |

974| `decision` | `"block"` empêche le prompt d'être traité et l'efface du contexte. Omettez pour autoriser le prompt à procéder |974| `decision` | `"block"` empêche le prompt d'être traité et l'efface du contexte. Omettez pour autoriser le prompt à procéder |

976| `additionalContext` | Chaîne ajoutée au contexte de Claude aux côtés du prompt soumis. Consultez [Ajouter du contexte pour Claude](#add-context-for-claude) |976| `additionalContext` | Chaîne ajoutée au contexte de Claude aux côtés du prompt soumis. Consultez [Ajouter du contexte pour Claude](#add-context-for-claude) |

977| `sessionTitle` | Définit le titre de la session, même effet que `/rename`. Utilisez pour nommer les sessions automatiquement en fonction du contenu du prompt |977| `sessionTitle` | Définit le titre de la session. Utilisez pour nommer les sessions automatiquement en fonction du contenu du prompt |

978 978

979```json theme={null}979```json theme={null}

980{980{

2407```2407```

2408 2408

2409| Champ | Description |2409| Champ | Description |

2410| :------- | :------------------------------------------------------------ |2410| :------- | :----------------------------------------------------------------------------------------- |

2411| `ok` | `true` autorise l'action, `false` l'empêche |2411| `ok` | `true` autorise l'action, `false` l'empêche. Voir le comportement par événement ci-dessous |

2413 2413

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

permissions.md +4 −119

Details

36| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |36| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

38| `acceptEdits` | Accepte automatiquement les éditions de fichiers et les commandes courantes du système de fichiers (`mkdir`, `touch`, `mv`, `cp`, etc.) pour les chemins du répertoire de travail ou `additionalDirectories` |38| `acceptEdits` | Accepte automatiquement les éditions de fichiers et les commandes courantes du système de fichiers (`mkdir`, `touch`, `mv`, `cp`, etc.) pour les chemins du répertoire de travail ou `additionalDirectories` |

40| `auto` | Approuve automatiquement les appels d'outils avec des vérifications de sécurité en arrière-plan qui vérifient que les actions s'alignent avec votre demande. Actuellement un aperçu de recherche |40| `auto` | Approuve automatiquement les appels d'outils avec des vérifications de sécurité en arrière-plan qui vérifient que les actions s'alignent avec votre demande. Actuellement un aperçu de recherche |

41| `dontAsk` | Refuse automatiquement les outils sauf s'ils sont pré-approuvés via `/permissions` ou les règles `permissions.allow` |41| `dontAsk` | Refuse automatiquement les outils sauf s'ils sont pré-approuvés via `/permissions` ou les règles `permissions.allow` |

42| `bypassPermissions` | Ignore tous les invites d'autorisation. Les suppressions ciblant la racine du système de fichiers ou le répertoire personnel, comme `rm -rf /` et `rm -rf ~`, demandent toujours comme disjoncteur de sécurité |42| `bypassPermissions` | Ignore tous les invites d'autorisation. Les suppressions ciblant la racine du système de fichiers ou le répertoire personnel, comme `rm -rf /` et `rm -rf ~`, demandent toujours comme disjoncteur de sécurité |

296 296

297* Les règles de refus d'autorisation empêchent Claude d'essayer même d'accéder aux ressources restreintes297* Les règles de refus d'autorisation empêchent Claude d'essayer même d'accéder aux ressources restreintes

298* Les restrictions de sandbox empêchent les commandes Bash d'atteindre les ressources en dehors des limites définies, même si une injection de prompt contourne la prise de décision de Claude298* Les restrictions de sandbox empêchent les commandes Bash d'atteindre les ressources en dehors des limites définies, même si une injection de prompt contourne la prise de décision de Claude

299* Les restrictions du système de fichiers dans le sandbox utilisent les règles de refus Read et Edit, pas une configuration de sandbox séparée299* Les restrictions du système de fichiers dans le sandbox combinent les paramètres [`sandbox.filesystem`](/fr/sandboxing) avec les règles de refus Read et Edit ; les deux sont fusionnées dans la limite finale du sandbox

300* Les restrictions réseau combinent les règles d'autorisation WebFetch avec les listes `allowedDomains` et `deniedDomains` du sandbox300* Les restrictions réseau combinent les règles d'autorisation WebFetch avec les listes `allowedDomains` et `deniedDomains` du sandbox

301 301

302Lorsque le sandboxing est activé avec `autoAllowBashIfSandboxed: true`, qui est la valeur par défaut, les commandes Bash en sandbox s'exécutent sans invite même si vos autorisations incluent `ask: Bash(*)`. La limite du sandbox remplace l'invite par commande. Les règles de refus explicites s'appliquent toujours, et les commandes `rm` ou `rmdir` qui ciblent `/`, votre répertoire personnel ou d'autres chemins système critiques déclenchent toujours une invite. Consultez [modes sandbox](/fr/sandboxing#sandbox-modes) pour modifier ce comportement.302Lorsque le sandboxing est activé avec `autoAllowBashIfSandboxed: true`, qui est la valeur par défaut, les commandes Bash en sandbox s'exécutent sans invite même si vos autorisations incluent `ask: Bash(*)`. La limite du sandbox remplace l'invite par commande. Les règles de refus explicites s'appliquent toujours, et les commandes `rm` ou `rmdir` qui ciblent `/`, votre répertoire personnel ou d'autres chemins système critiques déclenchent toujours une invite. Consultez [modes sandbox](/fr/sandboxing#sandbox-modes) pour modifier ce comportement.

316| `allowManagedMcpServersOnly` | Lorsque `true`, seuls les `allowedMcpServers` des paramètres gérés sont respectés. `deniedMcpServers` fusionne toujours à partir de toutes les sources. Consultez [Configuration MCP gérée](/fr/mcp#managed-mcp-configuration) |316| `allowManagedMcpServersOnly` | Lorsque `true`, seuls les `allowedMcpServers` des paramètres gérés sont respectés. `deniedMcpServers` fusionne toujours à partir de toutes les sources. Consultez [Configuration MCP gérée](/fr/mcp#managed-mcp-configuration) |

317| `allowManagedPermissionRulesOnly` | Lorsque `true`, empêche les paramètres utilisateur et projet de définir les règles d'autorisation `allow`, `ask` ou `deny`. Seules les règles dans les paramètres gérés s'appliquent |317| `allowManagedPermissionRulesOnly` | Lorsque `true`, empêche les paramètres utilisateur et projet de définir les règles d'autorisation `allow`, `ask` ou `deny`. Seules les règles dans les paramètres gérés s'appliquent |

318| `blockedMarketplaces` | Liste noire des sources de marketplace. Les sources bloquées sont vérifiées avant le téléchargement, elles ne touchent donc jamais le système de fichiers. Consultez [restrictions de marketplace gérées](/fr/plugin-marketplaces#managed-marketplace-restrictions) |318| `blockedMarketplaces` | Liste noire des sources de marketplace. Les sources bloquées sont vérifiées avant le téléchargement, elles ne touchent donc jamais le système de fichiers. Consultez [restrictions de marketplace gérées](/fr/plugin-marketplaces#managed-marketplace-restrictions) |

319| `channelsEnabled` | Autoriser les [canaux](/fr/channels) pour les utilisateurs Team et Enterprise. Non défini ou `false` bloque la livraison des messages de canal indépendamment de ce que les utilisateurs passent à `--channels` |319| `channelsEnabled` | Autoriser les [canaux](/fr/channels) pour l'organisation. Consultez [contrôles d'entreprise](/fr/channels#enterprise-controls) pour la valeur par défaut sur chaque plan |

320| `forceRemoteSettingsRefresh` | Lorsque `true`, bloque le démarrage de la CLI jusqu'à ce que les paramètres gérés distants soient fraîchement récupérés et se termine si la récupération échoue. Consultez [application fail-closed](/fr/server-managed-settings#enforce-fail-closed-startup) |320| `forceRemoteSettingsRefresh` | Lorsque `true`, bloque le démarrage de la CLI jusqu'à ce que les paramètres gérés distants soient fraîchement récupérés et se termine si la récupération échoue. Consultez [application fail-closed](/fr/server-managed-settings#enforce-fail-closed-startup) |

321| `pluginTrustMessage` | Message personnalisé ajouté à l'avertissement de confiance du plugin affiché avant l'installation |321| `pluginTrustMessage` | Message personnalisé ajouté à l'avertissement de confiance du plugin affiché avant l'installation |

322| `sandbox.filesystem.allowManagedReadPathsOnly` | Lorsque `true`, seuls les chemins `filesystem.allowRead` des paramètres gérés sont respectés. `denyRead` fusionne toujours à partir de toutes les sources |322| `sandbox.filesystem.allowManagedReadPathsOnly` | Lorsque `true`, seuls les chemins `filesystem.allowRead` des paramètres gérés sont respectés. `denyRead` fusionne toujours à partir de toutes les sources |

327`disableBypassPermissionsMode` est généralement placé dans les paramètres gérés pour appliquer la politique organisationnelle, mais il fonctionne à partir de n'importe quelle portée. Un utilisateur peut le définir dans ses propres paramètres pour se verrouiller hors du mode de contournement.327`disableBypassPermissionsMode` est généralement placé dans les paramètres gérés pour appliquer la politique organisationnelle, mais il fonctionne à partir de n'importe quelle portée. Un utilisateur peut le définir dans ses propres paramètres pour se verrouiller hors du mode de contournement.

328 328

329<Note>329<Note>

330 L'accès à [Remote Control](/fr/remote-control) et aux [sessions web](/fr/claude-code-on-the-web) n'est pas contrôlé par une clé de paramètres gérés. Sur les plans Team et Enterprise, un administrateur active ou désactive ces fonctionnalités dans les [paramètres d'administration Claude Code](https://claude.ai/admin-settings/claude-code).330 Sur les plans Team et Enterprise, un administrateur active ou désactive [Remote Control](/fr/remote-control) et les [sessions web](/fr/claude-code-on-the-web) à l'échelle de l'organisation dans les [paramètres d'administration Claude Code](https://claude.ai/admin-settings/claude-code). Remote Control peut également être désactivé par appareil avec le paramètre géré [`disableRemoteControl`](/fr/settings#available-settings). Les sessions web n'ont pas de clé de paramètres gérés par appareil.

331</Note>331</Note>

332 332

333## Examiner les refus du mode auto

~~334~~

335Lorsque le [mode auto](/fr/permission-modes#eliminate-prompts-with-auto-mode) refuse un appel d'outil, une notification apparaît et l'action refusée est enregistrée dans `/permissions` sous l'onglet Récemment refusé. Appuyez sur `r` sur une action refusée pour la marquer pour réessai : lorsque vous quittez la boîte de dialogue, Claude Code envoie un message indiquant au modèle qu'il peut réessayer cet appel d'outil et reprend la conversation.

~~336~~

337Pour réagir aux refus par programmation, utilisez le [hook `PermissionDenied`](/fr/hooks#permissiondenied).

~~338~~

339## Configurer le classificateur du mode auto

~~340~~

341Le [mode auto](/fr/permission-modes#eliminate-prompts-with-auto-mode) utilise un modèle de classificateur pour décider si chaque action est sûre à exécuter sans inviter. Par défaut, il ne fait confiance qu'au répertoire de travail et, s'il est présent, aux remotes du référentiel actuel. Les actions comme pousser vers l'organisation de contrôle de source de votre entreprise ou écrire dans un bucket cloud d'équipe seront bloquées comme exfiltration de données potentielle.

~~342~~

343Pour ajuster ce que le classificateur autorise ou bloque, ajoutez des instructions à votre fichier [CLAUDE.md](/fr/memory). Le classificateur lit CLAUDE.md à partir des répertoires approuvés aux côtés de la conversation, donc une instruction comme « ne jamais force push » oriente à la fois Claude et le classificateur en même temps. Commencez ici pour les conventions de projet et les règles de comportement.

~~344~~

345Pour les règles qui s'appliquent à plusieurs projets, comme l'infrastructure approuvée ou les règles de refus à l'échelle de l'organisation, utilisez le bloc de paramètres `autoMode`. Le classificateur lit `autoMode` à partir des paramètres utilisateur, `.claude/settings.local.json` et des paramètres gérés. Il ne lit pas à partir des paramètres de projet partagés dans `.claude/settings.json`, car un référentiel archivé pourrait autrement injecter ses propres règles d'autorisation.

~~346~~

347| Portée | Fichier | Utiliser pour |

348| :---------------------------- | :---------------------------- | :--------------------------------------------------------- |

349| Un développeur | `~/.claude/settings.json` | Infrastructure approuvée personnelle |

350| Un projet, un développeur | `.claude/settings.local.json` | Buckets ou services approuvés par projet, gitignored |

351| À l'échelle de l'organisation | Paramètres gérés | Infrastructure approuvée appliquée à tous les développeurs |

~~352~~

353Les entrées de chaque portée sont combinées. Un développeur peut étendre `environment`, `allow` et `soft_deny` avec des entrées personnelles mais ne peut pas supprimer les entrées que les paramètres gérés fournissent. Parce que les règles d'autorisation agissent comme des exceptions aux règles de blocage à l'intérieur du classificateur, une entrée `allow` ajoutée par un développeur peut remplacer une entrée `soft_deny` d'organisation : la combinaison est additive, pas une limite de politique dure. Si vous avez besoin d'une règle que les développeurs ne peuvent pas contourner, utilisez plutôt `permissions.deny` dans les paramètres gérés, qui bloque les actions avant que le classificateur ne soit consulté.

~~354~~

355### Définir l'infrastructure approuvée

~~356~~

357Pour la plupart des organisations, `autoMode.environment` est le seul champ que vous devez définir. Il dit au classificateur quels référentiels, buckets et domaines sont approuvés, sans toucher aux règles de blocage et d'autorisation intégrées. Le classificateur utilise `environment` pour décider ce que signifie « externe » : toute destination non listée est une cible d'exfiltration potentielle.

~~358~~

359```json theme={null}

360{

361 "autoMode": {

362 "environment": [

363 "Source control: github.example.com/acme-corp and all repos under it",

364 "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",

365 "Trusted internal domains: *.corp.example.com, api.internal.example.com",

366 "Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"

367 ]

368 }

369}

370```

~~371~~

372Les entrées sont en prose, pas en regex ou en modèles d'outils. Le classificateur les lit comme des règles en langage naturel. Écrivez-les comme vous décririez votre infrastructure à un nouvel ingénieur. Une section d'environnement approfondie couvre :

~~373~~

374* **Organisation** : le nom de votre entreprise et ce pour quoi Claude Code est principalement utilisé, comme le développement logiciel, l'automatisation de l'infrastructure ou l'ingénierie des données

375* **Contrôle de source** : chaque organisation GitHub, GitLab ou Bitbucket vers laquelle vos développeurs poussent

376* **Fournisseurs cloud et buckets approuvés** : noms de buckets ou préfixes que Claude devrait pouvoir lire et écrire

377* **Domaines internes approuvés** : noms d'hôtes pour les API, tableaux de bord et services à l'intérieur de votre réseau, comme `*.internal.example.com`

378* **Services internes clés** : CI, registres d'artefacts, index de packages internes, outils d'incident

379* **Contexte supplémentaire** : contraintes d'industrie réglementée, infrastructure multi-locataire ou exigences de conformité qui affectent ce que le classificateur devrait traiter comme risqué

~~380~~

381Un modèle de démarrage utile : remplissez les champs entre crochets et supprimez les lignes qui ne s'appliquent pas :

~~382~~

383```json theme={null}

384{

385 "autoMode": {

386 "environment": [

387 "Organization: {COMPANY_NAME}. Primary use: {PRIMARY_USE_CASE, e.g. software development, infrastructure automation}",

388 "Source control: {SOURCE_CONTROL, e.g. GitHub org github.example.com/acme-corp}",

389 "Cloud provider(s): {CLOUD_PROVIDERS, e.g. AWS, GCP, Azure}",

390 "Trusted cloud buckets: {TRUSTED_BUCKETS, e.g. s3://acme-builds, gs://acme-datasets}",

391 "Trusted internal domains: {TRUSTED_DOMAINS, e.g. *.internal.example.com, api.example.com}",

392 "Key internal services: {SERVICES, e.g. Jenkins at ci.example.com, Artifactory at artifacts.example.com}",

393 "Additional context: {EXTRA, e.g. regulated industry, multi-tenant infrastructure, compliance requirements}"

394 ]

395 }

396}

397```

~~398~~

399Plus le contexte spécifique que vous donnez, mieux le classificateur peut distinguer les opérations internes de routine des tentatives d'exfiltration.

~~400~~

401Vous n'avez pas besoin de tout remplir à la fois. Un déploiement raisonnable : commencez par les paramètres par défaut et ajoutez votre organisation de contrôle de source et vos services internes clés, ce qui résout les faux positifs les plus courants comme pousser vers vos propres référentiels. Ajoutez ensuite les domaines approuvés et les buckets cloud. Remplissez le reste à mesure que les blocages se produisent.

~~402~~

403### Remplacer les règles de blocage et d'autorisation

~~404~~

405Deux champs supplémentaires vous permettent de remplacer les listes de règles intégrées du classificateur : `autoMode.soft_deny` contrôle ce qui est bloqué, et `autoMode.allow` contrôle quelles exceptions s'appliquent. Chacun est un tableau de descriptions en prose, lu comme des règles en langage naturel.

~~406~~

407À l'intérieur du classificateur, la précédence est : les règles `soft_deny` bloquent d'abord, puis les règles `allow` remplacent comme exceptions, puis l'intention explicite de l'utilisateur remplace les deux. Si le message de l'utilisateur décrit directement et spécifiquement l'action exacte que Claude est sur le point d'entreprendre, le classificateur l'autorise même si une règle `soft_deny` correspond. Les demandes générales ne comptent pas : demander à Claude de « nettoyer le référentiel » n'autorise pas un force-push, mais demander à Claude de « force-push cette branche » le fait.

~~408~~

409Pour assouplir : supprimez les règles de `soft_deny` lorsque les paramètres par défaut bloquent quelque chose que votre pipeline protège déjà avec l'examen des PR, CI ou les environnements de staging, ou ajoutez à `allow` lorsque le classificateur signale à plusieurs reprises un modèle de routine que les exceptions par défaut ne couvrent pas. Pour renforcer : ajoutez à `soft_deny` pour les risques spécifiques à votre environnement que les paramètres par défaut manquent, ou supprimez de `allow` pour maintenir une exception par défaut aux règles de blocage. Dans tous les cas, exécutez `claude auto-mode defaults` pour obtenir les listes par défaut complètes, puis copiez et modifiez : ne commencez jamais par une liste vide.

~~410~~

411```json theme={null}

412{

413 "autoMode": {

414 "environment": [

415 "Source control: github.example.com/acme-corp and all repos under it"

416 ],

417 "allow": [

418 "Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly",

419 "Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"

420 ],

421 "soft_deny": [

422 "Never run database migrations outside the migrations CLI, even against dev databases",

423 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow",

424 "...copy full default soft_deny list here first, then add your rules..."

425 ]

426 }

427}

428```

~~429~~

430<Danger>

431 Définir `allow` ou `soft_deny` remplace la liste par défaut entière pour cette section. Si vous définissez `soft_deny` avec une seule entrée, chaque règle de blocage intégrée est supprimée : force push, exfiltration de données, `curl | bash`, déploiements de production et toutes les autres règles de blocage par défaut deviennent autorisés. Pour personnaliser en toute sécurité, exécutez `claude auto-mode defaults` pour imprimer les règles intégrées, copiez-les dans votre fichier de paramètres, puis examinez chaque règle par rapport à votre propre pipeline et tolérance au risque. Supprimez uniquement les règles pour les risques que votre infrastructure atténue déjà.

432</Danger>

~~433~~

434Les trois sections sont évaluées indépendamment, donc définir `environment` seul laisse les listes `allow` et `soft_deny` par défaut intactes.

~~435~~

436### Inspecter les paramètres par défaut et votre configuration effective

~~437~~

438Parce que définir `allow` ou `soft_deny` remplace les paramètres par défaut, commencez toute personnalisation en copiant les listes par défaut complètes. Trois sous-commandes CLI vous aident à inspecter et valider :

~~439~~

440```bash theme={null}

441claude auto-mode defaults # the built-in environment, allow, and soft_deny rules

442claude auto-mode config # what the classifier actually uses: your settings where set, defaults otherwise

443claude auto-mode critique # get AI feedback on your custom allow and soft_deny rules

444```

~~445~~

446Enregistrez la sortie de `claude auto-mode defaults` dans un fichier, modifiez les listes pour correspondre à votre politique et collez le résultat dans votre fichier de paramètres. Après l'enregistrement, exécutez `claude auto-mode config` pour confirmer que les règles effectives sont ce que vous attendez. Si vous avez écrit des règles personnalisées, `claude auto-mode critique` les examine et signale les entrées qui sont ambiguës, redondantes ou susceptibles de causer des faux positifs.

~~447~~

448## Précédence des paramètres333## Précédence des paramètres

449 334

450Les règles d'autorisation suivent la même [précédence des paramètres](/fr/settings#settings-precedence) que tous les autres paramètres de Claude Code :335Les règles d'autorisation suivent la même [précédence des paramètres](/fr/settings#settings-precedence) que tous les autres paramètres de Claude Code :

platforms.md +6 −3

Details

13Choisissez une plateforme en fonction de votre façon de travailler et de l'endroit où se trouve votre projet.13Choisissez une plateforme en fonction de votre façon de travailler et de l'endroit où se trouve votre projet.

14 14

16| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |16| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

17| [CLI](/fr/quickstart) | Flux de travail en terminal, scripts, serveurs distants | Ensemble complet de fonctionnalités, [Agent SDK](/fr/headless), fournisseurs tiers |17| [CLI](/fr/quickstart) | Flux de travail en terminal, scripts, serveurs distants | Ensemble complet de fonctionnalités, [Agent SDK](/fr/headless), [utilisation de l'ordinateur](/fr/computer-use) sur macOS (Pro et Max), fournisseurs tiers |

18| [Desktop](/fr/desktop) | Examen visuel, sessions parallèles, configuration gérée | Visionneuse de différences, aperçu de l'application, [utilisation de l'ordinateur](/fr/desktop#let-claude-use-your-computer) et [Dispatch](/fr/desktop#sessions-from-dispatch) sur Pro et Max |18| [Desktop](/fr/desktop) | Examen visuel, sessions parallèles, configuration gérée | Visionneuse de différences, aperçu de l'application, [utilisation de l'ordinateur](/fr/desktop#let-claude-use-your-computer) et [Dispatch](/fr/desktop#sessions-from-dispatch) sur Pro et Max |

21| [Web](/fr/claude-code-on-the-web) | Tâches longues qui ne nécessitent pas beaucoup de direction, ou travail qui devrait continuer quand vous êtes hors ligne | Cloud géré par Anthropic, continue après votre déconnexion |21| [Web](/fr/claude-code-on-the-web) | Tâches longues qui ne nécessitent pas beaucoup de direction, ou travail qui devrait continuer quand vous êtes hors ligne | Cloud géré par Anthropic, continue après votre déconnexion |

22| Mobile | Démarrer et surveiller les tâches loin de votre ordinateur | Sessions cloud depuis l'application Claude pour iOS et Android, [Remote Control](/fr/remote-control) pour les sessions locales, [Dispatch](/fr/desktop#sessions-from-dispatch) vers Desktop sur Pro et Max |

22 23

23Le CLI est la surface la plus complète pour le travail natif en terminal : les scripts, les fournisseurs tiers et l'Agent SDK sont exclusifs au CLI. Desktop et les extensions IDE échangent certaines fonctionnalités exclusives au CLI contre un examen visuel et une intégration plus étroite de l'éditeur. Le web s'exécute dans le cloud d'Anthropic, donc les tâches continuent après votre déconnexion.24Le CLI est la surface la plus complète pour le travail natif en terminal : les scripts et l'Agent SDK sont exclusifs au CLI. Les fournisseurs tiers fonctionnent également dans [VS Code](/fr/vs-code#use-third-party-providers). Les déploiements [Desktop](/fr/desktop) d'entreprise prennent en charge Vertex AI et les fournisseurs de passerelle ; pour Bedrock ou Foundry, utilisez le CLI ou VS Code à la place de Desktop. Desktop et les extensions IDE échangent certaines fonctionnalités exclusives au CLI contre un examen visuel et une intégration plus étroite de l'éditeur. Le web s'exécute dans le cloud d'Anthropic, donc les tâches continuent après votre déconnexion. Mobile est un client léger dans ces mêmes sessions cloud ou dans une session locale via Remote Control, et peut envoyer des tâches à Desktop avec Dispatch.

24 25

25Vous pouvez mélanger les surfaces sur le même projet. La configuration, la mémoire du projet et les serveurs MCP sont partagés entre les surfaces locales.26Vous pouvez mélanger les surfaces sur le même projet. La configuration, la mémoire du projet et les serveurs MCP sont partagés entre les surfaces locales.

26 27

61* [VS Code](/fr/vs-code) : l'extension Claude Code dans votre éditeur62* [VS Code](/fr/vs-code) : l'extension Claude Code dans votre éditeur

62* [JetBrains](/fr/jetbrains) : l'extension pour IntelliJ, PyCharm et autres IDE JetBrains63* [JetBrains](/fr/jetbrains) : l'extension pour IntelliJ, PyCharm et autres IDE JetBrains

63* [Claude Code sur le web](/fr/claude-code-on-the-web) : sessions cloud qui continuent à s'exécuter quand vous vous déconnectez64* [Claude Code sur le web](/fr/claude-code-on-the-web) : sessions cloud qui continuent à s'exécuter quand vous vous déconnectez

65* Mobile : l'application Claude pour [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) et [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) pour démarrer et surveiller les tâches loin de votre ordinateur

64 66

65### Intégrations67### Intégrations

66 68

67* [Chrome](/fr/chrome) : automatisez les tâches du navigateur avec vos sessions connectées69* [Chrome](/fr/chrome) : automatisez les tâches du navigateur avec vos sessions connectées

70* [Utilisation de l'ordinateur](/fr/computer-use) : permettez à Claude d'ouvrir des applications et de contrôler votre écran sur macOS

68* [GitHub Actions](/fr/github-actions) : exécutez Claude dans votre pipeline CI71* [GitHub Actions](/fr/github-actions) : exécutez Claude dans votre pipeline CI

69* [GitLab CI/CD](/fr/gitlab-ci-cd) : la même chose pour GitLab72* [GitLab CI/CD](/fr/gitlab-ci-cd) : la même chose pour GitLab

70* [Code Review](/fr/code-review) : examen automatique à chaque demande de tirage73* [Code Review](/fr/code-review) : examen automatique à chaque demande de tirage

plugin-marketplaces.md +8 −6

Details

23 23

24## Procédure pas à pas : créer une place de marché locale24## Procédure pas à pas : créer une place de marché locale

25 25

26Cet exemple crée une place de marché avec un plugin : une compétence `/quality-review` pour les révisions de code. Vous allez créer la structure de répertoires, ajouter une compétence, créer le manifeste du plugin et le catalogue de la place de marché, puis l'installer et la tester.26Cet exemple crée une place de marché avec un plugin : une compétence `quality-review` pour les révisions de code. Vous allez créer la structure de répertoires, ajouter une compétence, créer le manifeste du plugin et le catalogue de la place de marché, puis l'installer et la tester.

27 27

28<Steps>28<Steps>

29 <Step title="Créer la structure de répertoires">29 <Step title="Créer la structure de répertoires">

35 </Step>35 </Step>

36 36

37 <Step title="Créer la compétence">37 <Step title="Créer la compétence">

~~38 Créez un fichier `SKILL.md` qui définit ce que fait la compétence `/quality-review`.~~38 Créez un fichier `SKILL.md` qui définit ce que fait la compétence `quality-review`.

39 39

40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

61 "name": "quality-review-plugin",61 "name": "quality-review-plugin",

~~62 "description": "Adds a /quality-review skill for quick code reviews",~~62 "description": "Adds a quality-review skill for quick code reviews",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

82 {82 {

83 "name": "quality-review-plugin",83 "name": "quality-review-plugin",

84 "source": "./plugins/quality-review-plugin",84 "source": "./plugins/quality-review-plugin",

~~85 "description": "Adds a /quality-review skill for quick code reviews"~~85 "description": "Adds a quality-review skill for quick code reviews"

86 }86 }

87 ]87 ]

88 }88 }

99 </Step>99 </Step>

100 100

101 <Step title="Essayer">101 <Step title="Essayer">

102 Sélectionnez du code dans votre éditeur et exécutez votre nouvelle compétence.102 Sélectionnez du code dans votre éditeur et exécutez votre nouvelle compétence. Les compétences des plugins sont espacées avec le nom du plugin.

103 103

104 ```shell theme={null}104 ```shell theme={null}

105 /quality-review105 /quality-review-plugin:quality-review

106 ```106 ```

107 </Step>107 </Step>

108</Steps>108</Steps>

693* Pour les sources `hostPattern` : l'hôte de la place de marché est comparé au motif regex693* Pour les sources `hostPattern` : l'hôte de la place de marché est comparé au motif regex

694* Pour les sources `pathPattern` : le chemin du système de fichiers de la place de marché est comparé au motif regex694* Pour les sources `pathPattern` : le chemin du système de fichiers de la place de marché est comparé au motif regex

695 695

696La correspondance exacte ne normalise pas les URL : une barre oblique finale, un suffixe `.git` ou une forme `ssh://` par rapport à `https://` sont traités comme des valeurs différentes. Si la place de marché de votre organisation peut être clonée par plus d'une forme d'URL, préférez une entrée `hostPattern` à une URL littérale afin que toutes les formes correspondent.

697

696Parce que `strictKnownMarketplaces` est défini dans les [paramètres gérés](/fr/settings#settings-files), les configurations individuelles des utilisateurs et des projets ne peuvent pas contourner ces restrictions.698Parce que `strictKnownMarketplaces` est défini dans les [paramètres gérés](/fr/settings#settings-files), les configurations individuelles des utilisateurs et des projets ne peuvent pas contourner ces restrictions.

697 699

698Pour les détails de configuration complets, y compris tous les types de sources pris en charge et la comparaison avec `extraKnownMarketplaces`, consultez la [référence strictKnownMarketplaces](/fr/settings#strictknownmarketplaces).700Pour les détails de configuration complets, y compris tous les types de sources pris en charge et la comparaison avec `extraKnownMarketplaces`, consultez la [référence strictKnownMarketplaces](/fr/settings#strictknownmarketplaces).

plugins-reference.md +7 −3

Details

262**Plugins LSP disponibles :**262**Plugins LSP disponibles :**

263 263

265| :--------------- | :------------------------- | :----------------------------------------------------------------------------------------------- |265| :------------------ | :------------------------- | :----------------------------------------------------------------------------------------------- |

269 269

270Installez d'abord le serveur de langage, puis installez le plugin depuis la marketplace.270Installez d'abord le serveur de langage, puis installez le plugin depuis la marketplace.

271 271

531 531

532Claude Code fournit deux variables pour référencer les chemins des plugins. Les deux sont substituées en ligne partout où elles apparaissent dans le contenu des skills, le contenu des agents, les commandes de hook, les commandes de moniteur, et les configurations des serveurs MCP ou LSP. Les deux sont également exportées en tant que variables d'environnement vers les processus de hook et les sous-processus des serveurs MCP ou LSP.532Claude Code fournit deux variables pour référencer les chemins des plugins. Les deux sont substituées en ligne partout où elles apparaissent dans le contenu des skills, le contenu des agents, les commandes de hook, les commandes de moniteur, et les configurations des serveurs MCP ou LSP. Les deux sont également exportées en tant que variables d'environnement vers les processus de hook et les sous-processus des serveurs MCP ou LSP.

533 533

534**`${CLAUDE_PLUGIN_ROOT}`** : le chemin absolu du répertoire d'installation de votre plugin. Utilisez ceci pour référencer les scripts, les binaires et les fichiers de configuration fournis avec le plugin. Ce chemin change quand le plugin se met à jour, donc les fichiers que vous écrivez ici ne survivent pas à une mise à jour.534**`${CLAUDE_PLUGIN_ROOT}`** : le chemin absolu du répertoire d'installation de votre plugin. Utilisez ceci pour référencer les scripts, les binaires et les fichiers de configuration fournis avec le plugin. Ce chemin change quand le plugin se met à jour. Le répertoire de la version précédente reste sur le disque pendant environ sept jours après une mise à jour avant le nettoyage, mais traitez-le comme éphémère et n'écrivez pas d'état ici.

535

536Quand un plugin se met à jour en cours de session, les commandes de hook, les moniteurs, les serveurs MCP et les serveurs LSP continuent d'utiliser le chemin de la version précédente. Exécutez `/reload-plugins` pour basculer les hooks, les serveurs MCP et les serveurs LSP vers le nouveau chemin ; les moniteurs nécessitent un redémarrage de session.

535 537

536**`${CLAUDE_PLUGIN_DATA}`** : un répertoire persistant pour l'état du plugin qui survit aux mises à jour. Utilisez ceci pour les dépendances installées telles que `node_modules` ou les environnements virtuels Python, le code généré, les caches et tous les autres fichiers qui doivent persister entre les versions du plugin. Le répertoire est créé automatiquement la première fois que cette variable est référencée.538**`${CLAUDE_PLUGIN_DATA}`** : un répertoire persistant pour l'état du plugin qui survit aux mises à jour. Utilisez ceci pour les dépendances installées telles que `node_modules` ou les environnements virtuels Python, le code généré, les caches et tous les autres fichiers qui doivent persister entre les versions du plugin. Le répertoire est créé automatiquement la première fois que cette variable est référencée.

537 539

677 Le répertoire `.claude-plugin/` contient le fichier `plugin.json`. Tous les autres répertoires (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) doivent être à la racine du plugin, pas à l'intérieur de `.claude-plugin/`.679 Le répertoire `.claude-plugin/` contient le fichier `plugin.json`. Tous les autres répertoires (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) doivent être à la racine du plugin, pas à l'intérieur de `.claude-plugin/`.

678</Warning>680</Warning>

679 681

682Un fichier `CLAUDE.md` à la racine du plugin n'est pas chargé comme contexte de projet. Les plugins contribuent au contexte par le biais de skills, d'agents et de hooks plutôt que par CLAUDE.md. Pour livrer des instructions qui se chargent dans le contexte de Claude, mettez-les dans un [skill](#skills).

683

680### Référence des emplacements de fichiers684### Référence des emplacements de fichiers

681 685

security.md +1 −1

Details

27* **Outil bash en sandbox** : [Sandbox](/fr/sandboxing) les commandes bash avec isolation du système de fichiers et du réseau, réduisant les invites de permission tout en maintenant la sécurité. Activez avec `/sandbox` pour définir les limites où Claude Code peut travailler de manière autonome27* **Outil bash en sandbox** : [Sandbox](/fr/sandboxing) les commandes bash avec isolation du système de fichiers et du réseau, réduisant les invites de permission tout en maintenant la sécurité. Activez avec `/sandbox` pour définir les limites où Claude Code peut travailler de manière autonome

28* **Restriction d'accès en écriture** : Claude Code ne peut écrire que dans le dossier où il a été démarré et ses sous-dossiers—il ne peut pas modifier les fichiers dans les répertoires parents sans permission explicite. Bien que Claude Code puisse lire les fichiers en dehors du répertoire de travail (utile pour accéder aux bibliothèques système et aux dépendances), les opérations d'écriture sont strictement limitées à la portée du projet, créant une limite de sécurité claire28* **Restriction d'accès en écriture** : Claude Code ne peut écrire que dans le dossier où il a été démarré et ses sous-dossiers—il ne peut pas modifier les fichiers dans les répertoires parents sans permission explicite. Bien que Claude Code puisse lire les fichiers en dehors du répertoire de travail (utile pour accéder aux bibliothèques système et aux dépendances), les opérations d'écriture sont strictement limitées à la portée du projet, créant une limite de sécurité claire

29* **Atténuation de la fatigue des invites** : Support pour la liste blanche des commandes sûres fréquemment utilisées par utilisateur, par base de code ou par organisation29* **Atténuation de la fatigue des invites** : Support pour la liste blanche des commandes sûres fréquemment utilisées par utilisateur, par base de code ou par organisation

~~30* **Mode Accepter les modifications** : Accepter par lot plusieurs modifications tout en maintenant les invites de permission pour les commandes avec effets secondaires~~30* **Mode Accepter les modifications** : Accepte automatiquement les modifications de fichiers et un ensemble fixe de commandes Bash du système de fichiers comme `mkdir`, `touch`, `rm`, `mv`, `cp` et `sed` pour les chemins du répertoire de travail. Les autres commandes Bash et les chemins hors de la portée continuent à afficher des invites

31 31

32### Responsabilité de l'utilisateur32### Responsabilité de l'utilisateur

33 33

settings.md +26 −3

Details

73 73

74Sur Windows, les chemins affichés comme `~/.claude` se résolvent en `%USERPROFILE%\.claude`.

74***76***

75 77

76## Fichiers de paramètres78## Fichiers de paramètres

166| `apiKeyHelper` | Script personnalisé, à exécuter dans `/bin/sh`, pour générer une valeur d'authentification. Cette valeur sera envoyée comme en-têtes `X-Api-Key` et `Authorization: Bearer` pour les demandes de modèle | `/bin/generate_temp_api_key.sh` |168| `apiKeyHelper` | Script personnalisé, à exécuter dans `/bin/sh`, pour générer une valeur d'authentification. Cette valeur sera envoyée comme en-têtes `X-Api-Key` et `Authorization: Bearer` pour les demandes de modèle | `/bin/generate_temp_api_key.sh` |

167| `attribution` | Personnalisez l'attribution pour les commits git et les pull requests. Voir [Paramètres d'attribution](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | Personnalisez l'attribution pour les commits git et les pull requests. Voir [Paramètres d'attribution](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

168| `autoMemoryDirectory` | Répertoire personnalisé pour le stockage de la [mémoire automatique](/fr/memory#storage-location). Accepte un chemin absolu ou un chemin préfixé par `~/`. Accepté à partir des paramètres de politique et utilisateur, et à partir de l'indicateur `--settings`. Non accepté à partir des paramètres de projet ou locaux, car un référentiel cloné pourrait fournir l'un ou l'autre fichier pour rediriger les écritures de mémoire vers des emplacements sensibles | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | Répertoire personnalisé pour le stockage de la [mémoire automatique](/fr/memory#storage-location). Accepte un chemin absolu ou un chemin préfixé par `~/`. Accepté à partir des paramètres de politique et utilisateur, et à partir de l'indicateur `--settings`. Non accepté à partir des paramètres de projet ou locaux, car un référentiel cloné pourrait fournir l'un ou l'autre fichier pour rediriger les écritures de mémoire vers des emplacements sensibles | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | Activer la [mémoire automatique](/fr/memory#enable-or-disable-auto-memory). Quand `false`, Claude ne lit pas et n'écrit pas dans le répertoire de mémoire automatique. Par défaut : `true`. Vous pouvez également basculer ceci avec `/memory` pendant une session | `false` |

169| `autoMode` | Personnalisez ce que le classificateur du [mode auto](/fr/permission-modes#eliminate-prompts-with-auto-mode) bloque et autorise. Contient les tableaux `environment`, `allow`, et `soft_deny` de règles en prose. Incluez la chaîne littérale `"$defaults"` dans un tableau pour hériter des règles intégrées à cette position. Voir [Configurer le mode auto](/fr/auto-mode-config). Non lu à partir des paramètres de projet partagés | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | Personnalisez ce que le classificateur du [mode auto](/fr/permission-modes#eliminate-prompts-with-auto-mode) bloque et autorise. Contient les tableaux `environment`, `allow`, et `soft_deny` de règles en prose. Incluez la chaîne littérale `"$defaults"` dans un tableau pour hériter des règles intégrées à cette position. Voir [Configurer le mode auto](/fr/auto-mode-config). Non lu à partir des paramètres de projet partagés | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

170| `autoScrollEnabled` | Dans le [rendu fullscreen](/fr/fullscreen), suivre la nouvelle sortie vers le bas de la conversation. Par défaut : `true`. Apparaît dans `/config` comme **Auto-scroll**. Les invites de permission font toujours défiler dans la vue quand ceci est désactivé | `false` |173| `autoScrollEnabled` | Dans le [rendu fullscreen](/fr/fullscreen), suivre la nouvelle sortie vers le bas de la conversation. Par défaut : `true`. Apparaît dans `/config` comme **Auto-scroll**. Les invites de permission font toujours défiler dans la vue quand ceci est désactivé | `false` |

171| `autoUpdatesChannel` | Canal de version à suivre pour les mises à jour. Utilisez `"stable"` pour une version généralement une semaine ancienne et qui ignore les versions avec des régressions majeures, ou `"latest"` (par défaut) pour la version la plus récente | `"stable"` |174| `autoUpdatesChannel` | Canal de version à suivre pour les mises à jour. Utilisez `"stable"` pour une version généralement une semaine ancienne et qui ignore les versions avec des régressions majeures, ou `"latest"` (par défaut) pour la version la plus récente | `"stable"` |

174| `awsAuthRefresh` | Script personnalisé qui modifie le répertoire `.aws` (voir [configuration avancée des identifiants](/fr/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |177| `awsAuthRefresh` | Script personnalisé qui modifie le répertoire `.aws` (voir [configuration avancée des identifiants](/fr/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

175| `awsCredentialExport` | Script personnalisé qui génère du JSON avec les identifiants AWS (voir [configuration avancée des identifiants](/fr/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | Script personnalisé qui génère du JSON avec les identifiants AWS (voir [configuration avancée des identifiants](/fr/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

176| `blockedMarketplaces` | (Paramètres gérés uniquement) Liste noire des sources de marketplace. Appliquée lors de l'ajout de marketplace et lors de l'installation, la mise à jour, l'actualisation et la mise à jour automatique du plugin, donc une marketplace ajoutée avant que la politique soit définie ne peut pas être utilisée pour récupérer les plugins. Les sources bloquées sont vérifiées avant le téléchargement, donc elles ne touchent jamais le système de fichiers. Voir [Restrictions de marketplace gérées](/fr/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Paramètres gérés uniquement) Liste noire des sources de marketplace. Appliquée lors de l'ajout de marketplace et lors de l'installation, la mise à jour, l'actualisation et la mise à jour automatique du plugin, donc une marketplace ajoutée avant que la politique soit définie ne peut pas être utilisée pour récupérer les plugins. Les sources bloquées sont vérifiées avant le téléchargement, donc elles ne touchent jamais le système de fichiers. Voir [Restrictions de marketplace gérées](/fr/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

177| `channelsEnabled` | (Paramètres gérés uniquement) Autoriser les [channels](/fr/channels) pour les utilisateurs Team et Enterprise. Non défini ou `false` bloque la livraison des messages de channel indépendamment de ce que les utilisateurs passent à `--channels` | `true` |180| `channelsEnabled` | (Paramètres gérés uniquement) Autoriser les [channels](/fr/channels) pour l'organisation. Sur les plans Claude.ai Team et Enterprise, les channels sont bloqués quand ceci est non défini ou `false`. Pour les comptes [Anthropic Console](/fr/authentication#claude-console-authentication) utilisant l'authentification par clé API, les channels sont autorisés par défaut sauf si votre organisation déploie des paramètres gérés, auquel cas cette clé doit être définie à `true` | `true` |

178| `cleanupPeriodDays` | Les sessions inactives pendant plus longtemps que cette période sont supprimées au démarrage (par défaut : 30 jours, minimum 1). Définir à `0` est rejeté avec une erreur de validation. Contrôle également le seuil d'âge pour la suppression automatique des [worktrees de subagent orphelins](/fr/worktrees#clean-up-worktrees) au démarrage. Pour désactiver complètement les écritures de transcript, définissez la variable d'environnement [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/fr/env-vars), ou en mode non interactif (`-p`) utilisez l'indicateur `--no-session-persistence` ou l'option SDK `persistSession: false`. | `20` |181| `cleanupPeriodDays` | Les sessions inactives pendant plus longtemps que cette période sont supprimées au démarrage (par défaut : 30 jours, minimum 1). Définir à `0` est rejeté avec une erreur de validation. Contrôle également le seuil d'âge pour la suppression automatique des [worktrees de subagent orphelins](/fr/worktrees#clean-up-worktrees) au démarrage. Pour désactiver complètement les écritures de transcript, définissez la variable d'environnement [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/fr/env-vars), ou en mode non interactif (`-p`) utilisez l'indicateur `--no-session-persistence` ou l'option SDK `persistSession: false`. | `20` |

179| `companyAnnouncements` | Annonce à afficher aux utilisateurs au démarrage. Si plusieurs annonces sont fournies, elles seront affichées aléatoirement. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |182| `companyAnnouncements` | Annonce à afficher aux utilisateurs au démarrage. Si plusieurs annonces sont fournies, elles seront affichées aléatoirement. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

180| `defaultShell` | Shell par défaut pour les commandes `!` de la boîte d'entrée. Accepte `"bash"` (par défaut) ou `"powershell"`. Définir à `"powershell"` achemine les commandes `!` interactives via PowerShell sur Windows. Nécessite `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Voir [Outil PowerShell](/fr/tools-reference#powershell-tool) | `"powershell"` |183| `defaultShell` | Shell par défaut pour les commandes `!` de la boîte d'entrée. Accepte `"bash"` (par défaut) ou `"powershell"`. Définir à `"powershell"` achemine les commandes `!` interactives via PowerShell sur Windows. Nécessite `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Voir [Outil PowerShell](/fr/tools-reference#powershell-tool) | `"powershell"` |

183| `disableAutoMode` | Définir à `"disable"` pour empêcher l'activation du [mode auto](/fr/permission-modes#eliminate-prompts-with-auto-mode). Supprime `auto` du cycle `Shift+Tab` et rejette `--permission-mode auto` au démarrage. Très utile dans les [paramètres gérés](/fr/permissions#managed-settings) où les utilisateurs ne peuvent pas le contourner | `"disable"` |186| `disableAutoMode` | Définir à `"disable"` pour empêcher l'activation du [mode auto](/fr/permission-modes#eliminate-prompts-with-auto-mode). Supprime `auto` du cycle `Shift+Tab` et rejette `--permission-mode auto` au démarrage. Très utile dans les [paramètres gérés](/fr/permissions#managed-settings) où les utilisateurs ne peuvent pas le contourner | `"disable"` |

184| `disableDeepLinkRegistration` | Définir à `"disable"` pour empêcher Claude Code d'enregistrer le gestionnaire de protocole `claude-cli://` auprès du système d'exploitation au démarrage. Les [liens profonds](/fr/deep-links) permettent aux outils externes d'ouvrir une session Claude Code avec une invite pré-remplie. Utile dans les environnements où l'enregistrement du gestionnaire de protocole est restreint ou géré séparément | `"disable"` |187| `disableDeepLinkRegistration` | Définir à `"disable"` pour empêcher Claude Code d'enregistrer le gestionnaire de protocole `claude-cli://` auprès du système d'exploitation au démarrage. Les [liens profonds](/fr/deep-links) permettent aux outils externes d'ouvrir une session Claude Code avec une invite pré-remplie. Utile dans les environnements où l'enregistrement du gestionnaire de protocole est restreint ou géré séparément | `"disable"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}Désactiver le [Contrôle à distance](/fr/remote-control) : bloque `claude remote-control`, l'indicateur `--remote-control`, le démarrage automatique, et le basculement en session. Généralement placé dans les [paramètres gérés](/fr/permissions#managed-settings) pour l'application par appareil MDM, mais fonctionne à partir de n'importe quelle portée. Nécessite Claude Code v2.1.128 ou ultérieur | `true` |

186| `disableSkillShellExecution` | Désactiver l'exécution de shell en ligne pour `` !`...` `` et ` ```! ` blocs dans les [skills](/fr/skills) et les commandes personnalisées à partir des sources utilisateur, projet, plugin ou répertoire supplémentaire. Les commandes sont remplacées par `[shell command execution disabled by policy]` au lieu d'être exécutées. Les skills bundlés et gérés ne sont pas affectés. Très utile dans les [paramètres gérés](/fr/permissions#managed-settings) où les utilisateurs ne peuvent pas le contourner | `true` |190| `disableSkillShellExecution` | Désactiver l'exécution de shell en ligne pour `` !`...` `` et ` ```! ` blocs dans les [skills](/fr/skills) et les commandes personnalisées à partir des sources utilisateur, projet, plugin ou répertoire supplémentaire. Les commandes sont remplacées par `[shell command execution disabled by policy]` au lieu d'être exécutées. Les skills bundlés et gérés ne sont pas affectés. Très utile dans les [paramètres gérés](/fr/permissions#managed-settings) où les utilisateurs ne peuvent pas le contourner | `true` |

187| `editorMode` | Mode de liaison de touches pour l'invite d'entrée : `"normal"` ou `"vim"`. Par défaut : `"normal"`. Apparaît dans `/config` comme **Editor mode** | `"vim"` |191| `editorMode` | Mode de liaison de touches pour l'invite d'entrée : `"normal"` ou `"vim"`. Par défaut : `"normal"`. Apparaît dans `/config` comme **Editor mode** | `"vim"` |

188| `effortLevel` | Persister le [niveau d'effort](/fr/model-config#adjust-effort-level) entre les sessions. Accepte `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Écrit automatiquement quand vous exécutez `/effort` avec l'une de ces valeurs. Voir [Ajuster le niveau d'effort](/fr/model-config#adjust-effort-level) pour les modèles supportés | `"xhigh"` |192| `effortLevel` | Persister le [niveau d'effort](/fr/model-config#adjust-effort-level) entre les sessions. Accepte `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Écrit automatiquement quand vous exécutez `/effort` avec l'une de ces valeurs. Voir [Ajuster le niveau d'effort](/fr/model-config#adjust-effort-level) pour les modèles supportés | `"xhigh"` |

550 },554 },

551 "extraKnownMarketplaces": {555 "extraKnownMarketplaces": {

552 "acme-tools": {556 "acme-tools": {

557 "source": {

553 "source": "github",558 "source": "github",

554 "repo": "acme-corp/claude-plugins"559 "repo": "acme-corp/claude-plugins"

555 }560 }

556 }561 }

562 }

557}563}

558```564```

559 565

568* **Paramètres locaux** (`.claude/settings.local.json`) : Remplacements par machine (non commités)574* **Paramètres locaux** (`.claude/settings.local.json`) : Remplacements par machine (non commités)

569* **Paramètres gérés** (`managed-settings.json`) : Remplacements de politique au niveau de l'organisation qui bloquent l'installation à toutes les portées et masquent le plugin de la marketplace575* **Paramètres gérés** (`managed-settings.json`) : Remplacements de politique au niveau de l'organisation qui bloquent l'installation à toutes les portées et masquent le plugin de la marketplace

570 576

577<Note>

578 Les paramètres de projet ont la priorité sur les paramètres utilisateur, donc définir un plugin à `false` dans `~/.claude/settings.json` ne désactive pas un plugin que le `.claude/settings.json` du projet active. Pour refuser un plugin activé par le projet sur votre machine, définissez-le à `false` dans `.claude/settings.local.json` à la place.

579

580 Les plugins forcément activés par les paramètres gérés ne peuvent pas être désactivés de cette manière, car les paramètres gérés remplacent les paramètres locaux.

581</Note>

582

571**Exemple** :583**Exemple** :

572 584

573```json theme={null}585```json theme={null}

659* Disponible uniquement dans les paramètres gérés (`managed-settings.json`)671* Disponible uniquement dans les paramètres gérés (`managed-settings.json`)

660* Ne peut pas être contourné par les paramètres utilisateur ou projet (précédence la plus élevée)672* Ne peut pas être contourné par les paramètres utilisateur ou projet (précédence la plus élevée)

661* Appliqué AVANT les opérations de réseau/système de fichiers (les sources bloquées ne s'exécutent jamais)673* Appliqué AVANT les opérations de réseau/système de fichiers (les sources bloquées ne s'exécutent jamais)

662* Utilise la correspondance exacte pour les spécifications de source (y compris `ref`, `path` pour les sources git), sauf `hostPattern`, qui utilise la correspondance regex674* Utilise la correspondance exacte pour les spécifications de source (y compris `ref`, `path` pour les sources git), sauf `hostPattern` et `pathPattern`, qui utilisent la correspondance regex

663 675

664**Comportement de la liste blanche** :676**Comportement de la liste blanche** :

665 677

669 681

670**Tous les types de source supportés** :682**Tous les types de source supportés** :

671 683

672La liste blanche supporte plusieurs types de source de marketplace. La plupart des sources utilisent la correspondance exacte, tandis que `hostPattern` utilise la correspondance regex par rapport à l'hôte de la marketplace.684La liste blanche supporte plusieurs types de source de marketplace. La plupart des sources utilisent la correspondance exacte, tandis que `hostPattern` et `pathPattern` utilisent la correspondance regex par rapport à l'hôte de la marketplace et au chemin du système de fichiers respectivement.

673 685

6741. **Référentiels GitHub** :6861. **Référentiels GitHub** :

675 687

749* `url` : extrait le nom d'hôte de l'URL761* `url` : extrait le nom d'hôte de l'URL

750* `npm`, `file`, `directory` : non supporté pour la correspondance de modèle d'hôte762* `npm`, `file`, `directory` : non supporté pour la correspondance de modèle d'hôte

751 763

7648. **Correspondance de modèle de chemin** :

765

766```json theme={null}

767{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }

768{ "source": "pathPattern", "pathPattern": ".*" }

769```

770

771Champs : `pathPattern` (requis : modèle regex correspondant au champ `path` des sources `file` et `directory`)

772

773Utilisez la correspondance de modèle de chemin pour autoriser les marketplaces basées sur le système de fichiers aux côtés des restrictions `hostPattern` pour les sources réseau. Définissez `".*"` pour autoriser tous les chemins locaux, ou un modèle plus étroit pour restreindre à des répertoires spécifiques.

774

752**Exemples de configuration** :775**Exemples de configuration** :

753 776

754Exemple : autoriser uniquement les marketplaces spécifiques :777Exemple : autoriser uniquement les marketplaces spécifiques :

sub-agents.md +35 −10

Details

51 </Tab>51 </Tab>

52 52

53 <Tab title="Plan">53 <Tab title="Plan">

~~54 Un agent de recherche utilisé pendant le [mode plan](/fr/common-workflows#use-plan-mode-for-safe-code-analysis) pour rassembler le contexte avant de présenter un plan.~~54 Un agent de recherche utilisé pendant le [mode plan](/fr/permission-modes#analyze-before-you-edit-with-plan-mode) pour rassembler le contexte avant de présenter un plan.

55 55

56 * **Modèle** : Hérité de la conversation principale56 * **Modèle** : Hérité de la conversation principale

57 * **Outils** : Outils en lecture seule (accès refusé aux outils Write et Edit)57 * **Outils** : Outils en lecture seule (accès refusé aux outils Write et Edit)

77 | :---------------- | :----- | :---------------------------------------------------------------------- |77 | :---------------- | :----- | :---------------------------------------------------------------------- |

80 </Tab>80 </Tab>

81</Tabs>81</Tabs>

82 82

180 180

181**Les sous-agents définis par CLI** sont passés en JSON lors du lancement de Claude Code. Ils n'existent que pour cette session et ne sont pas enregistrés sur le disque, ce qui les rend utiles pour les tests rapides ou les scripts d'automatisation. Vous pouvez définir plusieurs sous-agents dans un seul appel `--agents` :181**Les sous-agents définis par CLI** sont passés en JSON lors du lancement de Claude Code. Ils n'existent que pour cette session et ne sont pas enregistrés sur le disque, ce qui les rend utiles pour les tests rapides ou les scripts d'automatisation. Vous pouvez définir plusieurs sous-agents dans un seul appel `--agents` :

182 182

183```bash theme={null}183<Tabs>

184claude --agents '{184 <Tab title="macOS, Linux, WSL">

185 ```bash theme={null}

186 claude --agents '{

185 "code-reviewer": {187 "code-reviewer": {

186 "description": "Expert code reviewer. Use proactively after code changes.",188 "description": "Expert code reviewer. Use proactively after code changes.",

187 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",189 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

192 "description": "Debugging specialist for errors and test failures.",194 "description": "Debugging specialist for errors and test failures.",

193 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."195 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

194 }196 }

195}'197 }'

196```198 ```

199 </Tab>

200

201 <Tab title="Windows PowerShell">

202 ```powershell theme={null}

203 claude --agents @'

204 {

205 "code-reviewer": {

206 "description": "Expert code reviewer. Use proactively after code changes.",

207 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

208 "tools": ["Read", "Grep", "Glob", "Bash"],

209 "model": "sonnet"

210 },

211 "debugger": {

212 "description": "Debugging specialist for errors and test failures.",

213 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

214 }

215 }

216 '@

217 ```

218 </Tab>

219</Tabs>

197 220

198Le drapeau `--agents` accepte JSON avec les mêmes champs de [frontmatter](#supported-frontmatter-fields) que les sous-agents basés sur fichier : `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` et `color`. Utilisez `prompt` pour l'invite système, équivalent au corps markdown dans les sous-agents basés sur fichier.221Le drapeau `--agents` accepte JSON avec les mêmes champs de [frontmatter](#supported-frontmatter-fields) que les sous-agents basés sur fichier : `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` et `color`. Utilisez `prompt` pour l'invite système, équivalent au corps markdown dans les sous-agents basés sur fichier.

199 222

212Les fichiers de sous-agent utilisent du frontmatter YAML pour la configuration, suivi de l'invite système en Markdown :235Les fichiers de sous-agent utilisent du frontmatter YAML pour la configuration, suivi de l'invite système en Markdown :

213 236

214<Note>237<Note>

215 Les sous-agents sont chargés au démarrage de la session. Si vous créez un sous-agent en ajoutant manuellement un fichier, redémarrez votre session ou utilisez `/agents` pour le charger immédiatement.238 Les sous-agents sont chargés au démarrage de la session. Si vous ajoutez ou modifiez un fichier de sous-agent directement sur le disque, redémarrez votre session pour le charger. Les sous-agents créés via l'interface `/agents` prennent effet immédiatement sans redémarrage.

216</Note>239</Note>

217 240

218```markdown theme={null}241```markdown theme={null}

250| `memory` | Non | [Portée de la mémoire persistante](#enable-persistent-memory) : `user`, `project` ou `local`. Active l'apprentissage entre sessions |273| `memory` | Non | [Portée de la mémoire persistante](#enable-persistent-memory) : `user`, `project` ou `local`. Active l'apprentissage entre sessions |

251| `background` | Non | Définir sur `true` pour toujours exécuter ce sous-agent en tant que [tâche d'arrière-plan](#run-subagents-in-foreground-or-background). Par défaut : `false` |274| `background` | Non | Définir sur `true` pour toujours exécuter ce sous-agent en tant que [tâche d'arrière-plan](#run-subagents-in-foreground-or-background). Par défaut : `false` |

252| `effort` | Non | Niveau d'effort lorsque ce sous-agent est actif. Remplace le niveau d'effort de la session. Par défaut : hérite de la session. Options : `low`, `medium`, `high`, `xhigh`, `max` ; les niveaux disponibles dépendent du modèle |275| `effort` | Non | Niveau d'effort lorsque ce sous-agent est actif. Remplace le niveau d'effort de la session. Par défaut : hérite de la session. Options : `low`, `medium`, `high`, `xhigh`, `max` ; les niveaux disponibles dépendent du modèle |

253| `isolation` | Non | Définir sur `worktree` pour exécuter le sous-agent dans un [git worktree](/fr/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) temporaire, ce qui lui donne une copie isolée du référentiel. Le worktree est automatiquement nettoyé si le sous-agent n'apporte aucune modification |276| `isolation` | Non | Définir sur `worktree` pour exécuter le sous-agent dans un [git worktree](/fr/worktrees) temporaire, ce qui lui donne une copie isolée du référentiel. Le worktree est automatiquement nettoyé si le sous-agent n'apporte aucune modification |

254| `color` | Non | Couleur d'affichage pour le sous-agent dans la liste des tâches et la transcription. Accepte `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` ou `cyan` |277| `color` | Non | Couleur d'affichage pour le sous-agent dans la liste des tâches et la transcription. Accepte `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` ou `cyan` |

255| `initialPrompt` | Non | Auto-soumis comme le premier tour utilisateur lorsque cet agent s'exécute en tant qu'agent de session principal (via `--agent` ou le paramètre `agent`). Les [commandes](/fr/commands) et les [skills](/fr/skills) sont traitées. Préfixé à tout invite fourni par l'utilisateur |278| `initialPrompt` | Non | Auto-soumis comme le premier tour utilisateur lorsque cet agent s'exécute en tant qu'agent de session principal (via `--agent` ou le paramètre `agent`). Les [commandes](/fr/commands) et les [skills](/fr/skills) sont traitées. Préfixé à tout invite fourni par l'utilisateur |

256 279

484exit 0507exit 0

485```508```

486 509

487Consultez [Hook input](/fr/hooks#pretooluse-input) pour le schéma d'entrée complet et [exit codes](/fr/hooks#exit-code-output) pour savoir comment les codes de sortie affectent le comportement.510Consultez [Hook input](/fr/hooks#pretooluse-input) pour le schéma d'entrée complet et [exit codes](/fr/hooks#exit-code-output) pour savoir comment les codes de sortie affectent le comportement. Sur Windows, écrivez les scripts de hook en PowerShell et ajoutez `shell: powershell` à l'entrée du hook comme indiqué dans [exécution de hooks en PowerShell](/fr/hooks#windows-powershell-tool).

488 511

489#### Désactiver des sous-agents spécifiques512#### Désactiver des sous-agents spécifiques

490 513

994exit 01017exit 0

995```1018```

996 1019

997Rendez le script exécutable :1020Sur macOS et Linux, rendez le script exécutable :

998 1021

999```bash theme={null}1022```bash theme={null}

1000chmod +x ./scripts/validate-readonly-query.sh1023chmod +x ./scripts/validate-readonly-query.sh

1001```1024```

1002 1025

1026Sur Windows, écrivez le script de validation en PowerShell et ajoutez `shell: powershell` à l'entrée du hook. Consultez [exécution des hooks dans PowerShell](/fr/hooks#windows-powershell-tool).

1027

1003Le hook reçoit JSON via stdin avec la commande Bash dans `tool_input.command`. Le code de sortie 2 bloque l'opération et renvoie le message d'erreur à Claude. Consultez [Hooks](/fr/hooks#exit-code-output) pour plus de détails sur les codes de sortie et [Hook input](/fr/hooks#pretooluse-input) pour le schéma d'entrée complet.1028Le hook reçoit JSON via stdin avec la commande Bash dans `tool_input.command`. Le code de sortie 2 bloque l'opération et renvoie le message d'erreur à Claude. Consultez [Hooks](/fr/hooks#exit-code-output) pour plus de détails sur les codes de sortie et [Hook input](/fr/hooks#pretooluse-input) pour le schéma d'entrée complet.

1004 1029

1005## Étapes suivantes1030## Étapes suivantes

vs-code.md +13 −3

Details

95* **Modes de permission** : cliquez sur l'indicateur de mode en bas de la zone de saisie pour changer de mode. En mode normal, Claude demande une permission avant chaque action. En Plan Mode, Claude décrit ce qu'il fera et attend l'approbation avant d'apporter des modifications. VS Code ouvre automatiquement le plan en tant que document markdown complet où vous pouvez ajouter des commentaires en ligne pour donner des commentaires avant que Claude ne commence. En mode acceptation automatique, Claude apporte des modifications sans demander. Définissez la valeur par défaut dans les paramètres VS Code sous `claudeCode.initialPermissionMode`.95* **Modes de permission** : cliquez sur l'indicateur de mode en bas de la zone de saisie pour changer de mode. En mode normal, Claude demande une permission avant chaque action. En Plan Mode, Claude décrit ce qu'il fera et attend l'approbation avant d'apporter des modifications. VS Code ouvre automatiquement le plan en tant que document markdown complet où vous pouvez ajouter des commentaires en ligne pour donner des commentaires avant que Claude ne commence. En mode acceptation automatique, Claude apporte des modifications sans demander. Définissez la valeur par défaut dans les paramètres VS Code sous `claudeCode.initialPermissionMode`.

96* **Menu de commandes** : cliquez sur `/` ou tapez `/` pour ouvrir le menu de commandes. Les options incluent l'attachement de fichiers, le changement de modèles, l'activation de la réflexion étendue, l'affichage de l'utilisation du plan (`/usage`) et le démarrage d'une session [Remote Control](/fr/remote-control) (`/remote-control`). La section Personnaliser fournit l'accès aux serveurs MCP, hooks, mémoire, permissions et plugins. Les éléments avec une icône de terminal s'ouvrent dans le terminal intégré.96* **Menu de commandes** : cliquez sur `/` ou tapez `/` pour ouvrir le menu de commandes. Les options incluent l'attachement de fichiers, le changement de modèles, l'activation de la réflexion étendue, l'affichage de l'utilisation du plan (`/usage`) et le démarrage d'une session [Remote Control](/fr/remote-control) (`/remote-control`). La section Personnaliser fournit l'accès aux serveurs MCP, hooks, mémoire, permissions et plugins. Les éléments avec une icône de terminal s'ouvrent dans le terminal intégré.

97* **Indicateur de contexte** : la zone de saisie affiche la quantité de fenêtre de contexte de Claude que vous utilisez. Claude se compacte automatiquement si nécessaire, ou vous pouvez exécuter `/compact` manuellement.97* **Indicateur de contexte** : la zone de saisie affiche la quantité de fenêtre de contexte de Claude que vous utilisez. Claude se compacte automatiquement si nécessaire, ou vous pouvez exécuter `/compact` manuellement.

98* **Réflexion étendue** : permet à Claude de consacrer plus de temps à raisonner sur des problèmes complexes. Activez-la via le menu de commandes (`/`). Le raisonnement de Claude apparaît dans la conversation sous forme de blocs réduits : cliquez sur un bloc pour le lire, ou appuyez sur `Ctrl+O` pour développer ou réduire chaque bloc de réflexion dans la session. Consultez [Réflexion étendue](/fr/common-workflows#use-extended-thinking-thinking-mode) pour plus de détails.98* **Réflexion étendue** : permet à Claude de consacrer plus de temps à raisonner sur des problèmes complexes. Activez-la via le menu de commandes (`/`). Le raisonnement de Claude apparaît dans la conversation sous forme de blocs réduits : cliquez sur un bloc pour le lire, ou appuyez sur `Ctrl+O` pour développer ou réduire chaque bloc de réflexion dans la session. Consultez [Réflexion étendue](/fr/model-config#extended-thinking) pour plus de détails.

99* **Entrée multiligne** : appuyez sur `Shift+Entrée` pour ajouter une nouvelle ligne sans envoyer. Cela fonctionne également dans l'entrée en texte libre ' Autre ' des dialogues de question.99* **Entrée multiligne** : appuyez sur `Shift+Entrée` pour ajouter une nouvelle ligne sans envoyer. Cela fonctionne également dans l'entrée en texte libre ' Autre ' des dialogues de question.

100 100

101### Référencer des fichiers et des dossiers101### Référencer des fichiers et des dossiers

115 115

116### Reprendre les conversations passées116### Reprendre les conversations passées

117 117

118Cliquez sur le bouton **Historique des sessions** en haut du panneau Claude Code pour accéder à votre historique de conversations. Vous pouvez rechercher par mot-clé ou parcourir par heure (Aujourd'hui, Hier, 7 derniers jours, etc.). Cliquez sur n'importe quelle conversation pour la reprendre avec l'historique complet des messages. Les nouvelles sessions reçoivent des titres générés par l'IA en fonction de votre premier message. Survolez une session pour révéler les actions de renommage et de suppression : renommez pour lui donner un titre descriptif, ou supprimez pour la supprimer de la liste. Pour plus d'informations sur la reprise des sessions, consultez [Flux de travail courants](/fr/common-workflows#resume-previous-conversations).118Cliquez sur le bouton **Historique des sessions** en haut du panneau Claude Code pour accéder à votre historique de conversations. Vous pouvez rechercher par mot-clé ou parcourir par heure (Aujourd'hui, Hier, 7 derniers jours, etc.). Cliquez sur n'importe quelle conversation pour la reprendre avec l'historique complet des messages. Les nouvelles sessions reçoivent des titres générés par l'IA en fonction de votre premier message. Survolez une session pour révéler les actions de renommage et de suppression : renommez pour lui donner un titre descriptif, ou supprimez pour la supprimer de la liste. Pour plus d'informations sur la reprise des sessions, consultez [Gérer les sessions](/fr/sessions).

119 119

120### Reprendre les sessions distantes de Claude.ai120### Reprendre les sessions distantes de Claude.ai

121 121

399claude --worktree feature-auth399claude --worktree feature-auth

400```400```

401 401

402Chaque worktree maintient un état de fichier indépendant tout en partageant l'historique git. Cela empêche les instances de Claude d'interférer les unes avec les autres lorsqu'elles travaillent sur différentes tâches. Pour plus de détails, consultez [Exécuter des sessions Claude Code parallèles avec Git worktrees](/fr/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees).402Chaque worktree maintient un état de fichier indépendant tout en partageant l'historique git. Cela empêche les instances de Claude d'interférer les unes avec les autres lorsqu'elles travaillent sur différentes tâches. Pour plus de détails, consultez [Exécuter des sessions parallèles avec Git worktrees](/fr/worktrees).

403 403

404## Utiliser des fournisseurs tiers404## Utiliser des fournisseurs tiers

405 405

476 476

477Vous pouvez également cliquer sur « ✱ Claude Code » dans la **Barre d'état** (coin inférieur droit). Cela fonctionne même sans fichier ouvert. Vous pouvez également utiliser la **Palette de commandes** (`Cmd+Shift+P` / `Ctrl+Shift+P`) et taper « Claude Code ».477Vous pouvez également cliquer sur « ✱ Claude Code » dans la **Barre d'état** (coin inférieur droit). Cela fonctionne même sans fichier ouvert. Vous pouvez également utiliser la **Palette de commandes** (`Cmd+Shift+P` / `Ctrl+Shift+P`) et taper « Claude Code ».

478 478

479### Cmd+Esc ne fait rien sur macOS

480

481Sur macOS Tahoe et versions ultérieures, le raccourci système Game Overlay est lié à `Cmd+Esc` par défaut et intercepte la frappe avant qu'elle n'atteigne VS Code. Pour libérer le raccourci :

482

4831. Ouvrez Paramètres système

4842. Allez à Clavier, puis Raccourcis clavier, puis Contrôleurs de jeu

4853. Décochez la case Game Overlay

486

487Vous pouvez également réassigner l'extension à une touche différente : ouvrez l'[éditeur de raccourcis clavier](https://code.visualstudio.com/docs/configure/keybindings) de VS Code (`Cmd+K Cmd+S`), recherchez `Claude Code: Focus input`, et assignez une nouvelle liaison.

488

479### Claude Code ne répond jamais489### Claude Code ne répond jamais

480 490

481Si Claude Code ne répond pas à vos invites :491Si Claude Code ne répond pas à vos invites :

Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC