cc-viewer 1.6.182 → 1.6.183

package/concepts/es/Tool-executeCode.md

@@ -1,41 +1,47 @@
-# executeCode (mcp__ide__executeCode)
+# executeCode
 
-## Definición
+Ejecuta un fragmento de código dentro de un kernel o sandbox en vivo proporcionado por una integración de IDE (por ejemplo el kernel de Jupyter vinculado al notebook abierto actualmente). La herramienta solo está presente cuando Claude Code se ejecuta junto con un puente de IDE compatible como la extensión de VS Code con un kernel de Jupyter seleccionado.
 
-Ejecuta código Python en el kernel de Jupyter del archivo notebook actual.
+## Cuándo usar
+
+- Ejecutar un cálculo rápido, inspección de datos o gráfico contra el estado ya cargado en un kernel activo de Jupyter.
+- Validar un fragmento de código antes de pegarlo en una celda de notebook.
+- Explorar un dataframe, variable o modelo en memoria que existe en el kernel pero no está serializado a disco.
+- Producir un gráfico o resultado numérico que el usuario quiere renderizado en línea en el IDE.
+
+NO uses esto para scripts independientes que se atenderían mejor con `Bash` ejecutando `python script.py`, o para código que necesita persistir entre un kernel fresco.
 
 ## Parámetros
 
-| Parámetro | Tipo | Requerido | Descripción |
-|-----------|------|-----------|-------------|
-| `code` | string | Sí | Código Python a ejecutar |
+- `code` (string, obligatorio): El código a ejecutar en el kernel actual. Se ejecuta como si se pegara en una celda de notebook — las variables definidas persisten en el kernel hasta que se reinicie.
+- `language` (string, opcional): El lenguaje del fragmento cuando el puente del IDE soporta múltiples kernels. Lo más común es omitirlo; por defecto es el lenguaje del kernel activo (típicamente Python).
+
+## Ejemplos
+
+### Ejemplo 1: Inspeccionar un dataframe en memoria
+
+```
+executeCode(
+  code="df.head()\nprint(df.shape)\nprint(df.dtypes)"
+)
+```
+
+Devuelve las primeras filas, la forma y los dtypes de columna de un dataframe ya cargado en el kernel.
 
-## Casos de uso
+### Ejemplo 2: Comprobación numérica rápida
 
-**Adecuado para:**
-- Ejecutar código en un entorno Jupyter notebook
-- Probar fragmentos de código
-- Análisis de datos y cálculos
+```
+executeCode(
+  code="import numpy as np\nnp.mean([1, 2, 3, 4, 5])"
+)
+```
 
-**No adecuado para:**
-- Ejecución de código fuera del entorno Jupyter — usar Bash
-- Modificar archivos — usar Edit o Write
+Ejecuta un cálculo puntual sin crear una celda de notebook.
 
 ## Notas
 
-- Esta es una herramienta MCP (Model Context Protocol), proporcionada por la integración con el IDE
-- El código se ejecuta en el kernel de Jupyter actual, el estado persiste entre llamadas
-- A menos que el usuario lo solicite explícitamente, se debe evitar declarar variables o modificar el estado del kernel
-- El estado se pierde al reiniciar el kernel
-
-## Texto original
-
-<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
-    
-    All code will be executed in the current Jupyter kernel.
-    
-    Avoid declaring variables or modifying the state of the kernel unless the user
-    explicitly asks for it.
-    
-    Any code executed will persist across calls to this tool, unless the kernel
-    has been restarted.</textarea>
+- `executeCode` es una herramienta de puente de IDE. No está disponible en sesiones de terminal plano de Claude Code; solo aparece cuando la sesión está conectada a un IDE que expone un kernel (por ejemplo la extensión Jupyter de VS Code).
+- El estado persiste en el kernel. Las variables definidas por una llamada `executeCode` permanecen visibles para llamadas posteriores, para celdas de notebook y para el usuario — ten en cuenta los efectos secundarios.
+- El código de larga duración o bloqueante bloqueará el kernel. Mantén los fragmentos cortos; para trabajo de varios minutos, escribe un script real y ejecútalo vía `Bash`.
+- La salida (stdout, valores de retorno, imágenes) se devuelve a la sesión. Las salidas muy grandes pueden ser truncadas por el puente del IDE.
+- Para ediciones de archivos, prefiere `Edit`, `Write` o `NotebookEdit` — `executeCode` no sustituye a la autoría de archivos fuente.

package/concepts/es/Tool-getDiagnostics.md

@@ -1,32 +1,44 @@
-# getDiagnostics (mcp__ide__getDiagnostics)
+# getDiagnostics
 
-## Definición
+Recupera diagnósticos del servidor de lenguaje (errores, advertencias, pistas) desde el IDE conectado para un archivo específico o para todos los archivos que el IDE tiene abiertos actualmente. Se usa para verificar que los cambios de código compilan limpiamente antes de declarar una tarea terminada.
 
-Obtiene información de diagnóstico del lenguaje de VS Code, incluyendo errores de sintaxis, errores de tipo, advertencias de lint, etc.
+## Cuándo usar
+
+- Tras un `Edit` o `Write` para confirmar que el cambio no introdujo un error de tipo, error de sintaxis o advertencia de lint.
+- Antes de finalizar una tarea para barrer cada archivo abierto en busca de problemas sin resolver.
+- Al diagnosticar un error que reporta el usuario — extraer el mensaje exacto del compilador o verificador de tipos desde el IDE evita adivinar.
+- Como alternativa ligera a ejecutar un build o suite de pruebas completos cuando solo necesitas comprobar la corrección estática.
+
+NO dependas de `getDiagnostics` como reemplazo de la suite de pruebas. Reporta lo que el servidor de lenguaje ve, no lo que se ejecuta en tiempo de prueba o producción.
 
 ## Parámetros
 
-| Parámetro | Tipo | Requerido | Descripción |
-|-----------|------|-----------|-------------|
-| `uri` | string | No | URI del archivo. Si no se proporciona, obtiene la información de diagnóstico de todos los archivos |
+- `uri` (string, opcional): La URI del archivo (típicamente `file:///absolute/path`) para la que obtener diagnósticos. Cuando se omite, la herramienta devuelve diagnósticos para cada archivo que el IDE tiene abierto actualmente.
 
-## Casos de uso
+## Ejemplos
 
-**Adecuado para:**
-- Verificar problemas semánticos de sintaxis, tipos, lint, etc. del código
-- Verificar si se introdujeron nuevos errores después de editar código
-- Reemplazar comandos Bash para verificar la calidad del código
+### Ejemplo 1: Comprobar un solo archivo tras editar
 
-**No adecuado para:**
-- Ejecutar pruebas — usar Bash
-- Verificar errores en tiempo de ejecución — usar Bash para ejecutar el código
+```
+getDiagnostics(
+  uri="file:///Users/sky/project/src/auth.ts"
+)
+```
 
-## Notas
+Devuelve cualquier error de TypeScript, advertencia de ESLint u otros mensajes del servidor de lenguaje para `src/auth.ts`.
 
-- Esta es una herramienta MCP (Model Context Protocol), proporcionada por la integración con el IDE
-- Solo disponible en entornos VS Code / IDE
-- Preferir usar esta herramienta en lugar de comandos Bash para verificar problemas de código
+### Ejemplo 2: Barrer todos los archivos abiertos
 
-## Texto original
+```
+getDiagnostics()
+```
+
+Devuelve diagnósticos de cada editor abierto actualmente. Útil al final de un refactor de varios archivos para asegurar que nada ha regresionado en otro lugar.
+
+## Notas
 
-<textarea readonly>Get language diagnostics from VS Code</textarea>
+- `getDiagnostics` es una herramienta de puente de IDE. Solo está disponible cuando Claude Code está conectado a una integración de IDE compatible (por ejemplo la extensión de VS Code). En una sesión de terminal plano la herramienta no aparecerá.
+- Los resultados reflejan los servidores de lenguaje que el IDE haya cargado — TypeScript, Pyright, ESLint, rust-analyzer, etc. La calidad y cobertura dependen de la configuración del IDE del usuario, no de Claude Code.
+- Los diagnósticos son en vivo. Tras una edición, da al servidor de lenguaje un momento para re-analizar antes de interpretar un resultado vacío como éxito — vuelve a ejecutar si el archivo se acaba de guardar.
+- Los niveles de severidad típicamente incluyen `error`, `warning`, `information` y `hint`. Enfócate primero en `error`; las advertencias pueden ser estilo intencional del proyecto.
+- Para archivos que no están abiertos actualmente en el IDE, el servidor de lenguaje puede no tener diagnósticos que reportar incluso si el archivo contiene problemas reales. Abre el archivo o ejecuta el build para una cobertura autoritativa.

package/concepts/es/Tools.md

@@ -8,7 +8,7 @@ A continuación se presenta el índice clasificado de todas las herramientas.
 
 | Herramienta | Propósito |
 |-------------|-----------|
-| [Task](Tool-Task.md) | Iniciar un sub-agent (SubAgent) para manejar tareas complejas de múltiples pasos |
+| [Agent](Tool-Agent.md) | Iniciar un sub-agent (SubAgent) para manejar tareas complejas de múltiples pasos |
 | [TaskOutput](Tool-TaskOutput.md) | Obtener la salida de tareas en segundo plano |
 | [TaskStop](Tool-TaskStop.md) | Detener una tarea en segundo plano en ejecución |
 | [TaskCreate](Tool-TaskCreate.md) | Crear una entrada en la lista de tareas estructurada |

package/concepts/fr/SubAgent-Search.md

@@ -1,20 +1,52 @@
-# SubAgent: Search
+# SubAgent : Search
 
-## Définition
+## Objectif
 
-Search est un type de sous-agent lancé par l'agent principal de Claude Code pour effectuer des recherches dans le code source. Il exécute des recherches ciblées de fichiers et de contenu à l'aide d'outils tels que Glob, Grep et Read, puis renvoie les résultats à l'agent parent.
+Le sous-agent Search est un agent d'exploration léger et en lecture seule. Dispatchez-le lorsque vous devez comprendre une base de code — trouver où quelque chose se trouve, apprendre comment les composants s'assemblent ou répondre à des questions structurelles — sans modifier aucun fichier. Il est optimisé pour de nombreuses petites lectures à travers de nombreux fichiers, en renvoyant un résumé concis plutôt qu'une sortie brute de recherche.
 
-## Comportement
+Search n'est pas un assistant polyvalent. Il ne peut pas éditer de code, exécuter des builds, valider des modifications ni ouvrir de connexions réseau au-delà de récupérations en lecture seule. Sa valeur réside dans sa capacité à brûler un gros budget d'exploration en parallèle sans consommer le contexte de l'agent principal, puis à renvoyer une réponse compacte.
 
-- Lancé automatiquement lorsque l'agent principal doit rechercher ou explorer le code source
-- S'exécute dans un contexte isolé avec un accès en lecture seule
-- Utilise Glob pour la correspondance de motifs de fichiers, Grep pour la recherche de contenu et Read pour l'inspection de fichiers
-- Renvoie les résultats de recherche à l'agent parent pour un traitement ultérieur
+## Quand l'utiliser
 
-## Quand il apparaît
+- Vous devez répondre à une question qui nécessite trois recherches ou lectures distinctes ou plus. Exemple : « Comment l'authentification est-elle câblée depuis la route de connexion jusqu'au stockage de session ? »
+- La cible est inconnue — vous ne savez pas encore quel fichier, module ou symbole examiner.
+- Vous avez besoin d'une vue d'ensemble structurelle d'une zone inconnue du dépôt avant d'effectuer des changements.
+- Vous souhaitez croiser plusieurs candidats (par exemple, lequel de plusieurs helpers aux noms similaires est réellement appelé en production).
+- Vous avez besoin d'un résumé de style revue de littérature : « liste chaque endroit qui importe X et catégorise par site d'appel. »
 
-Les sous-agents Search apparaissent généralement lorsque :
+N'utilisez pas Search lorsque :
 
-1. L'agent principal doit trouver des fichiers, des fonctions ou des motifs de code spécifiques
-2. L'utilisateur demande une exploration large du code source
-3. L'agent examine des dépendances, des références ou des patterns d'utilisation
+- Vous connaissez déjà le fichier et la ligne exacts. Appelez `Read` directement.
+- Un seul `Grep` ou `Glob` répondra à la question. Exécutez-le directement ; dispatcher un sous-agent ajoute du surcoût.
+- La tâche requiert édition, exécution de commandes ou tout effet de bord. Search est en lecture seule par conception.
+- Vous avez besoin de la sortie verbatim exacte d'un appel d'outil. Les sous-agents résument ; ils ne proxient pas les résultats bruts.
+
+## Niveaux de rigueur
+
+Choisissez le niveau correspondant aux enjeux de la question.
+
+- `quick` — quelques recherches ciblées, réponse au mieux. À utiliser lorsque vous avez besoin d'un pointeur rapide (par exemple, « où se trouve la logique de parsing des variables d'environnement ? ») et que vous êtes à l'aise pour itérer si la réponse est incomplète.
+- `medium` — valeur par défaut. Plusieurs tours de recherche, recoupement de candidats et lecture intégrale des fichiers les plus pertinents. À utiliser pour les questions typiques « aide-moi à comprendre cette zone ».
+- `very thorough` — exploration exhaustive. Le sous-agent poursuivra chaque piste plausible, lira le contexte environnant et vérifiera ses conclusions avant de résumer. À utiliser lorsque la correction importe (par exemple, revue de sécurité, planification de migration) ou lorsqu'une réponse incomplète causera du retravail.
+
+Une rigueur plus élevée coûte plus de temps et de tokens à l'intérieur du sous-agent, mais ces tokens restent à l'intérieur du sous-agent — seul le résumé final revient à l'agent principal.
+
+## Outils disponibles
+
+Search a accès à tous les outils en lecture seule utilisés par l'agent principal, et rien d'autre :
+
+- `Read` — pour lire des fichiers spécifiques, y compris des plages partielles.
+- `Grep` — pour des recherches de contenu dans l'arbre.
+- `Glob` — pour localiser des fichiers par motif de nom.
+- `Bash` en mode lecture seule — pour des commandes qui inspectent l'état sans le muter (par exemple `git log`, `git show`, `ls`, `wc`).
+- `WebFetch` et `WebSearch` — pour lire de la documentation externe lorsque ce contexte est requis.
+
+Les outils d'édition (`Write`, `Edit`, `NotebookEdit`), les commandes shell qui modifient l'état, et les outils de graphe de tâches (`TaskCreate`, `TaskUpdate`, etc.) sont délibérément indisponibles.
+
+## Notes
+
+- Donnez au sous-agent Search une question spécifique, pas un sujet. « Liste chaque appelant de `renderMessage` et note ceux qui passent un thème personnalisé » renvoie une réponse utile ; « parle-moi du rendu » ne le fait pas.
+- Le sous-agent renvoie un résumé. Si vous avez besoin de chemins de fichiers exacts, demandez-les explicitement dans votre invite.
+- Plusieurs questions indépendantes sont mieux dispatchées comme des sous-agents Search parallèles plutôt qu'une longue invite, afin que chacun puisse se concentrer.
+- Comme Search ne peut pas éditer, associez-le à une étape d'édition de suivi dans l'agent principal une fois que vous savez quoi changer.
+- Traitez la sortie de Search comme une preuve, pas comme une vérité absolue. Pour tout ce qui est critique, ouvrez vous-même les fichiers cités avant d'agir.

package/concepts/fr/Tool-Agent.md

@@ -1,125 +1,60 @@
 # Agent
 
-## Définition
+Lance un sous-agent Claude Code autonome avec sa propre fenêtre de contexte pour traiter une tâche ciblée et renvoyer un unique résultat consolidé. C'est le mécanisme canonique pour déléguer de la recherche ouverte, du travail parallèle ou de la collaboration en équipe.
 
-Lance un sous-agent (SubAgent) pour gérer de manière autonome des tâches complexes multi-étapes. Les sous-agents sont des sous-processus indépendants, chacun avec son propre ensemble d'outils et contexte dédiés. Agent est la version renommée de l'outil Task dans les nouvelles versions de Claude Code.
+## Quand l'utiliser
 
-## Paramètres
-
-| Paramètre | Type | Requis | Description |
-|-----------|------|--------|-------------|
-| `prompt` | string | Oui | Description de la tâche à exécuter par le sous-agent |
-| `description` | string | Oui | Résumé bref de 3-5 mots |
-| `subagent_type` | string | Oui | Type de sous-agent, détermine l'ensemble d'outils disponibles |
-| `model` | enum | Non | Spécifier le modèle (sonnet / opus / haiku), par défaut hérité du parent |
-| `max_turns` | integer | Non | Nombre maximum de tours agentiques |
-| `run_in_background` | boolean | Non | Si la tâche s'exécute en arrière-plan ; les tâches en arrière-plan renvoient le chemin du output_file |
-| `resume` | string | Non | ID de l'agent à reprendre, continue depuis la dernière exécution. Utile pour reprendre un sous-agent précédent sans perdre le contexte |
-| `isolation` | enum | Non | Mode d'isolation, `worktree` crée un git worktree temporaire |
-
-## Types de sous-agents
-
-| Type | Utilité | Outils disponibles |
-|------|---------|-------------------|
-| `Bash` | Exécution de commandes, opérations git | Bash |
-| `general-purpose` | Tâches générales multi-étapes | Tous les outils |
-| `Explore` | Exploration rapide de la base de code | Tous les outils sauf Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `Plan` | Concevoir des plans d'implémentation | Tous les outils sauf Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `claude-code-guide` | Questions-réponses sur le guide d'utilisation de Claude Code | Glob, Grep, Read, WebFetch, WebSearch |
-| `statusline-setup` | Configurer la barre d'état | Read, Edit |
-
-## Cas d'utilisation
-
-**Adapté pour :**
-- Tâches complexes nécessitant une réalisation autonome en plusieurs étapes
-- Exploration de la base de code et recherche approfondie (utiliser le type Explore)
-- Travail parallèle nécessitant des environnements isolés
-- Tâches de longue durée nécessitant une exécution en arrière-plan
+- Recherches ouvertes lorsque vous ne savez pas encore quels fichiers sont pertinents et que vous anticipez plusieurs tours de `Glob`, `Grep` et `Read`.
+- Travail parallèle indépendant — lancez plusieurs agents dans un même message pour explorer simultanément des zones distinctes.
+- Isoler une exploration bruyante de la conversation principale afin que le contexte parent reste compact.
+- Déléguer à un type de sous-agent spécialisé tel que `Explore`, `Plan`, `claude-code-guide` ou `statusline-setup`.
+- Faire apparaître un coéquipier nommé dans une équipe active pour un travail coordonné entre plusieurs agents.
 
-**Non adapté pour :**
-- Lire des chemins de fichiers spécifiques — utiliser directement Read ou Glob
-- Rechercher dans 2-3 fichiers connus — utiliser directement Read
-- Rechercher des définitions de classes spécifiques — utiliser directement Glob
+N'utilisez PAS `Agent` lorsque le fichier ou le symbole cible est déjà connu — utilisez directement `Read`, `Grep` ou `Glob`. Une recherche en une seule étape via `Agent` gaspille une fenêtre de contexte entière et ajoute de la latence.
 
-## Notes
-
-- Le sous-agent renvoie un seul message à la fin, ses résultats ne sont pas visibles pour l'utilisateur et l'agent principal doit les transmettre
-- Plusieurs appels Agent peuvent être lancés en parallèle dans un seul message pour améliorer l'efficacité
-- Les tâches en arrière-plan vérifient la progression via l'outil TaskOutput
-- Le type Explore est plus lent que l'appel direct à Glob/Grep, à utiliser uniquement quand la recherche simple ne suffit pas
-- Utilisez `run_in_background: true` pour les tâches longues ne nécessitant pas de résultat immédiat ; utilisez le mode premier plan (par défaut) quand le résultat est nécessaire avant de continuer
-- Le paramètre `resume` permet de continuer une session de sous-agent précédemment démarrée, en préservant le contexte accumulé
-
-## Texte original
+## Paramètres
 
-<textarea readonly>Launch a new agent to handle complex, multi-step tasks autonomously.
+- `description` (string, requis) : libellé court de 3 à 5 mots décrivant la tâche ; affiché dans l'interface et les journaux.
+- `prompt` (string, requis) : briefing complet et autonome que l'agent exécutera. Doit inclure tout le contexte nécessaire, les contraintes et le format de retour attendu.
+- `subagent_type` (string, optionnel) : persona prédéfinie telle que `general-purpose`, `Explore`, `Plan`, `claude-code-guide` ou `statusline-setup`. Par défaut `general-purpose`.
+- `run_in_background` (boolean, optionnel) : si `true`, l'agent s'exécute de façon asynchrone et le parent peut continuer à travailler ; les résultats sont récupérés ultérieurement.
+- `model` (string, optionnel) : remplace le modèle pour cet agent — `opus`, `sonnet` ou `haiku`. Par défaut, le modèle de la session parente.
+- `isolation` (string, optionnel) : définir à `worktree` pour exécuter l'agent dans un worktree git isolé afin que ses écritures sur le système de fichiers n'entrent pas en conflit avec celles du parent.
+- `team_name` (string, optionnel) : lors du lancement dans une équipe existante, l'identifiant de l'équipe que l'agent rejoindra.
+- `name` (string, optionnel) : nom d'adressage du coéquipier au sein de l'équipe, utilisé comme cible `to` pour `SendMessage`.
 
-The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+## Exemples
 
-Available agent types and the tools they have access to:
-- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. (Tools: *)
-- statusline-setup: Use this agent to configure the user's Claude Code status line setting. (Tools: Read, Edit)
-- Explore: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- claude-code-guide: Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can resume using the "resume" parameter. (Tools: Glob, Grep, Read, WebFetch, WebSearch)
+### Exemple 1 : recherche de code ouverte
 
-When using the Agent tool, you must specify a subagent_type parameter to select which agent type to use.
+```
+Agent(
+  description="Find auth middleware",
+  subagent_type="Explore",
+  prompt="Locate every place in this repo where JWT verification is performed. Return a bulleted list of absolute file paths with a one-line note about each site's role. Do not modify any files."
+)
+```
 
-When NOT to use the Agent tool:
-- If you want to read a specific file path, use the Read or Glob tool instead of the Agent tool, to find the match more quickly
-- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
-- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Agent tool, to find the match more quickly
-- Other tasks that are not related to the agent descriptions above
+### Exemple 2 : investigations indépendantes parallèles
 
-Usage notes:
-- Always include a short description (3-5 words) summarizing what the agent will do
-- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
-- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
-- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
-- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.
-- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.
-- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
-- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.
-- The agent's outputs should generally be trusted
-- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
-- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
-- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
-- You can optionally set `isolation: "worktree"` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result.
+Lancez deux agents dans le même message — l'un inspecte le pipeline de build, l'autre examine le harnais de tests. Chacun dispose de sa propre fenêtre de contexte et renvoie un résumé. Les regrouper dans un unique bloc d'appels d'outils les exécute en parallèle.
 
-Example usage:
+### Exemple 3 : ajouter un coéquipier à une équipe en cours
 
-<example_agent_descriptions>
-"test-runner": use this agent after you are done writing code to run tests
-"greeting-responder": use this agent to respond to user greetings with a friendly joke
-</example_agent_descriptions>
+```
+Agent(
+  description="Data layer specialist",
+  team_name="refactor-crew",
+  name="db-lead",
+  prompt="You are db-lead on team refactor-crew. Audit all Prisma schema files and propose a migration plan. Use SendMessage to report findings to the team leader."
+)
+```
 
-<example>
-user: "Please write a function that checks if a number is prime"
-assistant: Sure let me write a function that checks if a number is prime
-assistant: First let me use the Write tool to write a function that checks if a number is prime
-assistant: I'm going to use the Write tool to write the following code:
-<code>
-function isPrime(n) {
-  if (n <= 1) return false
-  for (let i = 2; i * i <= n; i++) {
-    if (n % i === 0) return false
-  }
-  return true
-}
-</code>
-<commentary>
-Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
-</commentary>
-assistant: Now let me use the test-runner agent to run the tests
-assistant: Uses the Agent tool to launch the test-runner agent
-</example>
+## Notes
 
-<example>
-user: "Hello"
-<commentary>
-Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
-</commentary>
-assistant: "I'm going to use the Agent tool to launch the greeting-responder agent"
-</example>
-</textarea>
+- Les agents n'ont aucun souvenir des exécutions précédentes. Chaque invocation part de zéro, donc le `prompt` doit être entièrement autonome — incluez les chemins de fichiers, les conventions, la question et la forme exacte de la réponse souhaitée.
+- L'agent renvoie exactement un message final. Il ne peut pas poser de questions de clarification en cours d'exécution, donc toute ambiguïté dans le prompt se traduit par des approximations dans le résultat.
+- Exécuter plusieurs agents en parallèle est bien plus rapide que des appels séquentiels lorsque les sous-tâches sont indépendantes. Regroupez-les dans un même bloc d'appels d'outils.
+- Utilisez `isolation: "worktree"` chaque fois qu'un agent écrit des fichiers et que vous souhaitez examiner les changements avant de les fusionner dans l'arbre de travail principal.
+- Préférez `subagent_type: "Explore"` pour la reconnaissance en lecture seule et `Plan` pour le travail de conception ; `general-purpose` est la valeur par défaut pour les tâches mixtes lecture/écriture.
+- Les agents en arrière-plan (`run_in_background: true`) conviennent aux tâches longues ; évitez les boucles de polling avec `sleep` — le parent est notifié à la fin.

package/concepts/fr/Tool-AskUserQuestion.md

@@ -1,75 +1,60 @@
 # AskUserQuestion
 
-## Définition
+Présente à l'utilisateur une ou plusieurs questions structurées à choix multiples dans l'interface de chat, collecte ses sélections et les renvoie à l'assistant — utile pour lever une ambiguïté d'intention sans échange libre.
 
-Pose des questions à l'utilisateur pendant l'exécution pour obtenir des clarifications, vérifier des hypothèses ou demander des décisions.
+## Quand l'utiliser
 
-## Paramètres
-
-| Paramètre | Type | Requis | Description |
-|-----------|------|--------|-------------|
-| `questions` | array | Oui | Liste de questions (1-4 questions) |
-| `answers` | object | Non | Réponses collectées auprès de l'utilisateur |
-| `annotations` | object | Non | Annotations pour chaque question (comme les notes de prévisualisation de sélection) |
-| `metadata` | object | Non | Métadonnées pour le suivi et l'analyse |
-
-Chaque objet `question` :
-
-| Champ | Type | Requis | Description |
-|-------|------|--------|-------------|
-| `question` | string | Oui | Texte complet de la question, doit se terminer par un point d'interrogation |
-| `header` | string | Oui | Étiquette courte (maximum 12 caractères), affichée comme chip d'étiquette |
-| `options` | array | Oui | 2-4 options |
-| `multiSelect` | boolean | Oui | Si la sélection multiple est autorisée |
-
-Chaque objet `option` :
-
-| Champ | Type | Requis | Description |
-|-------|------|--------|-------------|
-| `label` | string | Oui | Texte d'affichage de l'option (1-5 mots) |
-| `description` | string | Oui | Description de l'option |
-| `markdown` | string | Non | Contenu de prévisualisation (pour la comparaison visuelle de mises en page ASCII, extraits de code, etc.) |
-
-## Cas d'utilisation
+- Une requête admet plusieurs interprétations raisonnables et l'assistant a besoin que l'utilisateur en choisisse une avant de poursuivre.
+- L'utilisateur doit choisir parmi des options concrètes (framework, bibliothèque, chemin de fichier, stratégie) où des réponses en texte libre seraient sources d'erreurs.
+- Vous souhaitez comparer côte à côte des alternatives grâce au volet de prévisualisation.
+- Plusieurs décisions liées peuvent être regroupées dans une seule invite pour réduire les allers-retours.
+- Un plan ou un appel d'outil dépend d'une configuration que l'utilisateur n'a pas encore précisée.
 
-**Adapté pour :**
-- Collecter les préférences ou exigences de l'utilisateur
-- Clarifier des instructions ambiguës
-- Obtenir des décisions pendant l'implémentation
-- Offrir des choix de direction à l'utilisateur
+## Paramètres
 
-**Non adapté pour :**
-- Demander « le plan est-il correct ? » — utiliser ExitPlanMode
+- `questions` (array, requis) : de une à quatre questions affichées ensemble dans une même invite. Chaque objet question contient :
+  - `question` (string, requis) : le texte complet de la question, terminé par un point d'interrogation.
+  - `header` (string, requis) : une étiquette courte (au plus 12 caractères) rendue sous forme de puce au-dessus de la question.
+  - `options` (array, requis) : de deux à quatre objets option. Chaque option possède un `label` (1 à 5 mots), une `description`, et une prévisualisation `markdown` optionnelle.
+  - `multiSelect` (boolean, requis) : lorsque `true`, l'utilisateur peut sélectionner plusieurs options.
+
+## Exemples
+
+### Exemple 1 : choisir un framework unique
+
+```
+AskUserQuestion(questions=[{
+  "header": "Test runner",
+  "question": "Which test runner should I configure?",
+  "multiSelect": false,
+  "options": [
+    {"label": "Vitest (Recommended)", "description": "Fast, Vite-native, Jest-compatible API"},
+    {"label": "Jest",                  "description": "Mature, broadest plugin ecosystem"},
+    {"label": "Node --test",           "description": "Zero dependencies, built in"}
+  ]
+}])
+```
+
+### Exemple 2 : prévisualisation côte à côte de deux mises en page
+
+```
+AskUserQuestion(questions=[{
+  "header": "Layout",
+  "question": "Which dashboard layout do you prefer?",
+  "multiSelect": false,
+  "options": [
+    {"label": "Sidebar",  "description": "Nav on the left", "markdown": "```\n+------+---------+\n| NAV  | CONTENT |\n+------+---------+\n```"},
+    {"label": "Top bar",  "description": "Nav across top",  "markdown": "```\n+-----------------+\n|       NAV       |\n+-----------------+\n|     CONTENT     |\n+-----------------+\n```"}
+  ]
+}])
+```
 
 ## Notes
 
-- L'utilisateur peut toujours sélectionner « Other » pour fournir une entrée personnalisée
-- L'option recommandée est placée en premier, avec « (Recommended) » à la fin du label
-- La prévisualisation `markdown` n'est compatible qu'avec les questions à sélection unique
-- Les options avec `markdown` passent à une disposition côte à côte
-- En mode planification, utilisé pour clarifier les exigences avant de définir le plan
-
-## Texte original
-
-<textarea readonly>Use this tool when you need to ask the user questions during execution. This allows you to:
-1. Gather user preferences or requirements
-2. Clarify ambiguous instructions
-3. Get decisions on implementation choices as you work
-4. Offer choices to the user about what direction to take.
-
-Usage notes:
-- Users will always be able to select "Other" to provide custom text input
-- Use multiSelect: true to allow multiple answers to be selected for a question
-- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
-
-Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ExitPlanMode for plan approval. IMPORTANT: Do not reference "the plan" in your questions (e.g., "Do you have feedback about the plan?", "Does the plan look good?") because the user cannot see the plan in the UI until you call ExitPlanMode. If you need plan approval, use ExitPlanMode instead.
-
-Preview feature:
-Use the optional `markdown` field on options when presenting concrete artifacts that users need to visually compare:
-- ASCII mockups of UI layouts or components
-- Code snippets showing different implementations
-- Diagram variations
-- Configuration examples
-
-When any option has a markdown, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).
-</textarea>
+- L'interface ajoute automatiquement une option de texte libre « Other » à chaque question. N'ajoutez pas vos propres entrées « Other », « None » ou « Custom » — cela dupliquerait l'échappatoire intégrée.
+- Limitez chaque appel à un nombre de questions compris entre une et quatre, et chaque question à un nombre d'options compris entre deux et quatre. Tout dépassement est rejeté par le harnais.
+- Si vous recommandez une option particulière, placez-la en premier et ajoutez « (Recommended) » à son libellé afin que l'interface mette en valeur le chemin préféré.
+- Les prévisualisations via le champ `markdown` ne sont prises en charge que pour les questions à sélection unique. Utilisez-les pour des artefacts visuels tels que des mises en page ASCII, des extraits de code ou des diffs de configuration — pas pour de simples questions de préférence où un libellé et une description suffisent.
+- Lorsqu'une option d'une question possède une valeur `markdown`, l'interface bascule vers une mise en page côte à côte avec la liste d'options à gauche et la prévisualisation à droite.
+- N'utilisez pas `AskUserQuestion` pour demander « ce plan vous convient-il ? » — appelez plutôt `ExitPlanMode`, qui existe précisément pour l'approbation de plan. En mode plan, évitez également de mentionner « le plan » dans le texte de la question, car le plan n'est pas visible pour l'utilisateur tant que `ExitPlanMode` n'a pas été exécuté.
+- N'utilisez pas cet outil pour demander des entrées sensibles ou libres telles que des clés API ou des mots de passe. Demandez plutôt dans le chat.