cc-viewer 1.6.182 → 1.6.183

package/concepts/de/Tool-executeCode.md

@@ -1,41 +1,47 @@
-# executeCode (mcp__ide__executeCode)
+# executeCode
 
-## Definition
+Führt ein Code-Snippet innerhalb eines Live-Kernels oder einer Sandbox aus, die von einer IDE-Integration bereitgestellt wird (zum Beispiel der Jupyter-Kernel, der an das aktuell geöffnete Notebook gebunden ist). Das Tool ist nur verfügbar, wenn Claude Code neben einer kompatiblen IDE-Brücke wie der VS-Code-Erweiterung mit ausgewähltem Jupyter-Kernel läuft.
 
-Führt Python-Code im Jupyter-Kernel der aktuellen Notebook-Datei aus.
+## Wann verwenden
+
+- Ausführen einer schnellen Berechnung, Datenprüfung oder eines Plots gegen den Zustand, der bereits in einem aktiven Jupyter-Kernel geladen ist.
+- Validieren eines Code-Snippets, bevor es in eine Notebook-Zelle eingefügt wird.
+- Erkunden eines im Speicher gehaltenen Dataframes, einer Variablen oder eines Modells, das im Kernel existiert, aber nicht auf Platte serialisiert ist.
+- Erzeugen eines Charts oder numerischen Ergebnisses, das der Benutzer inline in der IDE gerendert sehen möchte.
+
+NICHT verwenden für eigenständige Skripte, die besser mit `Bash` und `python script.py` ausgeführt werden, oder für Code, der über einen frischen Kernel hinaus bestehen muss.
 
 ## Parameter
 
-| Parameter | Typ | Erforderlich | Beschreibung |
-|-----------|-----|--------------|--------------|
-| `code` | string | Ja | Der auszuführende Python-Code |
+- `code` (string, erforderlich): Der im aktuellen Kernel auszuführende Code. Läuft, als wäre er in eine Notebook-Zelle eingefügt – definierte Variablen bleiben im Kernel erhalten, bis er neu gestartet wird.
+- `language` (string, optional): Die Sprache des Snippets, wenn die IDE-Brücke mehrere Kernel unterstützt. Am häufigsten weggelassen; Standard ist die Sprache des aktiven Kernels (typischerweise Python).
+
+## Beispiele
+
+### Beispiel 1: Einen Dataframe im Speicher inspizieren
+
+```
+executeCode(
+  code="df.head()\nprint(df.shape)\nprint(df.dtypes)"
+)
+```
+
+Gibt die ersten Zeilen, die Form und die Spalten-dtypes eines bereits im Kernel geladenen Dataframes zurück.
 
-## Anwendungsfälle
+### Beispiel 2: Schnelle numerische Prüfung
 
-**Geeignet für:**
-- Code in einer Jupyter-Notebook-Umgebung ausführen
-- Code-Snippets testen
-- Datenanalyse und Berechnungen
+```
+executeCode(
+  code="import numpy as np\nnp.mean([1, 2, 3, 4, 5])"
+)
+```
 
-**Nicht geeignet für:**
-- Codeausführung außerhalb von Jupyter – dafür Bash verwenden
-- Dateien ändern – dafür Edit oder Write verwenden
+Führt eine einmalige Berechnung aus, ohne eine Notebook-Zelle zu erstellen.
 
 ## Hinweise
 
-- Dies ist ein MCP-Tool (Model Context Protocol), bereitgestellt durch die IDE-Integration
-- Code wird im aktuellen Jupyter-Kernel ausgeführt, der Zustand bleibt zwischen Aufrufen bestehen
-- Sofern der Benutzer es nicht ausdrücklich anfordert, sollte das Deklarieren von Variablen oder Ändern des Kernel-Zustands vermieden werden
-- Nach einem Kernel-Neustart geht der Zustand verloren
-
-## Originaltext
-
-<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` ist ein IDE-Brücken-Tool. Es ist in einfachen Terminal-Sitzungen von Claude Code nicht verfügbar; es erscheint nur, wenn die Sitzung mit einer IDE verbunden ist, die einen Kernel freigibt (zum Beispiel die VS-Code-Jupyter-Erweiterung).
+- Zustand bleibt im Kernel erhalten. Von einem `executeCode`-Aufruf definierte Variablen bleiben späteren Aufrufen, Notebook-Zellen und dem Benutzer sichtbar – achten Sie auf Seiteneffekte.
+- Langlaufender oder blockierender Code blockiert den Kernel. Halten Sie Snippets kurz; für Arbeit über mehrere Minuten schreiben Sie ein echtes Skript und führen es über `Bash` aus.
+- Ausgabe (stdout, Rückgabewerte, Bilder) wird an die Sitzung zurückgegeben. Sehr große Ausgaben können von der IDE-Brücke gekürzt werden.
+- Für Datei-Edits bevorzugen Sie `Edit`, `Write` oder `NotebookEdit` – `executeCode` ist kein Ersatz zum Verfassen von Quelldateien.

package/concepts/de/Tool-getDiagnostics.md

@@ -1,32 +1,44 @@
-# getDiagnostics (mcp__ide__getDiagnostics)
+# getDiagnostics
 
-## Definition
+Ruft Language-Server-Diagnosen (Fehler, Warnungen, Hinweise) aus der verbundenen IDE für eine bestimmte Datei oder für jede Datei ab, die die IDE derzeit geöffnet hat. Wird verwendet, um zu verifizieren, dass Code-Änderungen sauber kompilieren, bevor eine Aufgabe für erledigt erklärt wird.
 
-Ruft Sprachdiagnoseinformationen von VS Code ab, einschließlich Syntaxfehler, Typfehler, Lint-Warnungen usw.
+## Wann verwenden
+
+- Nach einem `Edit` oder `Write`, um zu bestätigen, dass die Änderung keinen Typfehler, Syntaxfehler oder keine Lint-Warnung eingeführt hat.
+- Vor dem Beenden einer Aufgabe, um jede offene Datei nach ungelösten Problemen zu durchsuchen.
+- Beim Diagnostizieren eines vom Benutzer gemeldeten Fehlers – das Ziehen der exakten Compiler- oder Type-Checker-Meldung aus der IDE vermeidet Rätselraten.
+- Als leichtgewichtige Alternative zur Ausführung eines vollständigen Builds oder Testbefehls, wenn Sie nur die statische Korrektheit prüfen müssen.
+
+Verlassen Sie sich NICHT auf `getDiagnostics` als Ersatz für die Test-Suite. Es meldet, was der Language-Server sieht, nicht was zur Test- oder Produktionszeit läuft.
 
 ## Parameter
 
-| Parameter | Typ | Erforderlich | Beschreibung |
-|-----------|-----|--------------|--------------|
-| `uri` | string | Nein | Datei-URI. Wenn nicht angegeben, werden Diagnoseinformationen aller Dateien abgerufen |
+- `uri` (string, optional): Die Datei-URI (typischerweise `file:///absolute/path`), für die Diagnosen abgerufen werden sollen. Wenn weggelassen, gibt das Tool Diagnosen für jede derzeit in der IDE geöffnete Datei zurück.
 
-## Anwendungsfälle
+## Beispiele
 
-**Geeignet für:**
-- Syntax-, Typ-, Lint- und andere semantische Probleme im Code prüfen
-- Nach Codebearbeitung überprüfen, ob neue Fehler eingeführt wurden
-- Als Alternative zu Bash-Befehlen zur Codequalitätsprüfung
+### Beispiel 1: Eine einzelne Datei nach dem Bearbeiten prüfen
 
-**Nicht geeignet für:**
-- Tests ausführen – dafür Bash verwenden
-- Laufzeitfehler prüfen – dafür Code über Bash ausführen
+```
+getDiagnostics(
+  uri="file:///Users/sky/project/src/auth.ts"
+)
+```
 
-## Hinweise
+Gibt alle TypeScript-Fehler, ESLint-Warnungen oder andere Language-Server-Meldungen für `src/auth.ts` zurück.
 
-- Dies ist ein MCP-Tool (Model Context Protocol), bereitgestellt durch die IDE-Integration
-- Nur in VS Code / IDE-Umgebungen verfügbar
-- Dieses Tool gegenüber Bash-Befehlen zur Codeprüfung bevorzugen
+### Beispiel 2: Alle geöffneten Dateien durchkämmen
 
-## Originaltext
+```
+getDiagnostics()
+```
+
+Gibt Diagnosen über jeden derzeit geöffneten Editor zurück. Nützlich am Ende eines dateiübergreifenden Refactorings, um sicherzustellen, dass anderswo nichts regrediert ist.
+
+## Hinweise
 
-<textarea readonly>Get language diagnostics from VS Code</textarea>
+- `getDiagnostics` ist ein IDE-Brücken-Tool. Es ist nur verfügbar, wenn Claude Code mit einer unterstützenden IDE-Integration verbunden ist (zum Beispiel der VS-Code-Erweiterung). In einer reinen Terminal-Sitzung erscheint das Tool nicht.
+- Die Ergebnisse spiegeln wider, welche Language-Server die IDE geladen hat – TypeScript, Pyright, ESLint, rust-analyzer usw. Qualität und Abdeckung hängen vom IDE-Setup des Benutzers ab, nicht von Claude Code.
+- Diagnosen sind live. Geben Sie dem Language-Server nach einem Edit einen Moment zur Neu-Analyse, bevor Sie ein leeres Ergebnis als Erfolg interpretieren – wiederholen Sie, falls die Datei gerade gespeichert wurde.
+- Schweregrade umfassen typischerweise `error`, `warning`, `information` und `hint`. Fokussieren Sie sich zuerst auf `error`; Warnungen können absichtlicher Projektstil sein.
+- Für Dateien, die derzeit nicht in der IDE geöffnet sind, hat der Language-Server möglicherweise keine Diagnosen zu melden, selbst wenn die Datei echte Probleme enthält. Öffnen Sie die Datei oder führen Sie den Build aus, um autoritative Abdeckung zu erhalten.

package/concepts/de/Tools.md

@@ -8,7 +8,7 @@ Im Folgenden finden Sie den kategorisierten Index aller Tools.
 
 | Tool | Zweck |
 |------|-------|
-| [Task](Tool-Task.md) | Startet einen Sub-Agent (SubAgent) für komplexe mehrstufige Aufgaben |
+| [Agent](Tool-Agent.md) | Startet einen Sub-Agent (SubAgent) für komplexe mehrstufige Aufgaben |
 | [TaskOutput](Tool-TaskOutput.md) | Ruft die Ausgabe von Hintergrundaufgaben ab |
 | [TaskStop](Tool-TaskStop.md) | Stoppt eine laufende Hintergrundaufgabe |
 | [TaskCreate](Tool-TaskCreate.md) | Erstellt einen strukturierten Aufgabenlisteneintrag |

package/concepts/en/SubAgent-Search.md

@@ -1,20 +1,52 @@
 # SubAgent: Search
 
-## Definition
+## Purpose
 
-Search is a sub-agent type spawned by Claude Code's main agent to perform codebase searches. It executes targeted file and content searches using tools like Glob, Grep, and Read, then returns the results to the parent agent.
+The Search subagent is a lightweight, read-only exploration agent. Dispatch it when you need to understand a codebase — find where something lives, learn how components fit together, or answer structural questions — without changing any files. It is optimised for many small reads across many files, returning a concise summary rather than raw search output.
 
-## Behavior
+Search is not a general-purpose assistant. It cannot edit code, run builds, commit changes, or open network connections beyond read-only fetches. Its value is that it can burn through a large exploration budget in parallel without consuming the main agent's context, then hand back a compact answer.
 
-- Spawned automatically when the main agent needs to search or explore the codebase
-- Runs in an isolated context with read-only access
-- Uses Glob for file pattern matching, Grep for content search, and Read for file inspection
-- Returns search results to the parent agent for further processing
+## When to Use
 
-## When It Appears
+- You need to answer a question that requires three or more distinct searches or reads. Example: "How is authentication wired from the login route down to the session store?"
+- The target is unknown — you do not yet know which file, module, or symbol to look at.
+- You need a structural overview of an unfamiliar area of the repo before making changes.
+- You want to cross-reference multiple candidates (for example, which of several similarly-named helpers is actually called in production).
+- You need a literature-style summary: "list every place that imports X and categorise by call site."
 
-Search sub-agents typically appear when:
+Do not use Search when:
 
-1. The main agent needs to find specific files, functions, or code patterns
-2. A broad codebase exploration is requested by the user
-3. The agent is investigating dependencies, references, or usage patterns
+- You already know the exact file and line. Call `Read` directly.
+- A single `Grep` or `Glob` will answer the question. Run it directly; dispatching a subagent adds overhead.
+- The task requires editing, running commands, or any side effect. Search is read-only by design.
+- You need exact verbatim output of a tool call. Subagents summarise; they do not proxy raw results.
+
+## Thoroughness Levels
+
+Pick the level that matches the stakes of the question.
+
+- `quick` — a few targeted searches, best-effort answer. Use when you need a fast pointer (for example, "where is the env-var parsing logic?") and are comfortable iterating if the answer is incomplete.
+- `medium` — the default. Several rounds of search, cross-checking candidates, and reading the most relevant files in full. Use for typical "help me understand this area" questions.
+- `very thorough` — exhaustive exploration. The subagent will chase every plausible lead, read surrounding context, and double-check findings before summarising. Use when correctness matters (for example, security review, migration planning) or when an incomplete answer will cause rework.
+
+Higher thoroughness costs more time and tokens inside the subagent, but those tokens stay inside the subagent — only the final summary returns to the main agent.
+
+## Tools Available
+
+Search has access to all read-only tools the main agent uses, and nothing else:
+
+- `Read` — for reading specific files, including partial ranges.
+- `Grep` — for content searches across the tree.
+- `Glob` — for locating files by name pattern.
+- `Bash` in read-only mode — for commands that inspect state without mutating it (for example `git log`, `git show`, `ls`, `wc`).
+- `WebFetch` and `WebSearch` — for reading external documentation when that context is required.
+
+Edit tools (`Write`, `Edit`, `NotebookEdit`), shell commands that modify state, and task-graph tools (`TaskCreate`, `TaskUpdate`, and so on) are deliberately unavailable.
+
+## Notes
+
+- Give the Search subagent a specific question, not a topic. "List every caller of `renderMessage` and note which ones pass a custom theme" returns a useful answer; "tell me about rendering" does not.
+- The subagent returns a summary. If you need exact file paths, ask for them explicitly in your prompt.
+- Multiple independent questions are best dispatched as parallel Search subagents rather than one long prompt, so each can focus.
+- Because Search cannot edit, pair it with a follow-up edit step in the main agent once you know what to change.
+- Treat Search output as evidence, not ground truth. For anything load-bearing, open the cited files yourself before acting.

package/concepts/en/Tool-Agent.md

@@ -1,125 +1,60 @@
 # Agent
 
-## Definition
+Spawns an autonomous Claude Code subagent with its own context window to handle a focused task and return a single consolidated result. This is the canonical mechanism for delegating open-ended research, parallel work, or team collaboration.
 
-Launches a SubAgent to autonomously handle complex multi-step tasks. SubAgents are independent subprocesses, each with their own dedicated tool set and context. Agent is the renamed version of the Task tool in newer Claude Code releases.
+## When to Use
 
-## Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `prompt` | string | Yes | Description of the task for the SubAgent to execute |
-| `description` | string | Yes | A 3-5 word short summary |
-| `subagent_type` | string | Yes | SubAgent type, determines the available tool set |
-| `model` | enum | No | Specify model (sonnet / opus / haiku), defaults to inheriting from parent |
-| `max_turns` | integer | No | Maximum number of agentic turns |
-| `run_in_background` | boolean | No | Whether to run in the background; background tasks return an output_file path |
-| `resume` | string | No | Agent ID to resume, continues from the last execution. Useful for picking up where a previous SubAgent left off without losing context |
-| `isolation` | enum | No | Isolation mode, `worktree` creates a temporary git worktree |
-
-## SubAgent Types
-
-| Type | Purpose | Available Tools |
-|------|---------|-----------------|
-| `Bash` | Command execution, git operations | Bash |
-| `general-purpose` | General multi-step tasks | All tools |
-| `Explore` | Quick codebase exploration | All tools except Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `Plan` | Design implementation plans | All tools except Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `claude-code-guide` | Claude Code usage guide Q&A | Glob, Grep, Read, WebFetch, WebSearch |
-| `statusline-setup` | Configure status bar | Read, Edit |
-
-## Use Cases
-
-**Good for:**
-- Complex tasks requiring multi-step autonomous completion
-- Codebase exploration and deep research (using Explore type)
-- Parallel work requiring isolated environments
-- Long-running tasks that need to run in the background
+- Open-ended searches where you do not yet know which files are relevant and expect multiple rounds of `Glob`, `Grep`, and `Read`.
+- Parallel independent work — launch several agents in one message to investigate separate areas concurrently.
+- Isolating noisy exploration from the main conversation so the parent context stays compact.
+- Delegating to a specialized subagent type such as `Explore`, `Plan`, `claude-code-guide`, or `statusline-setup`.
+- Spawning a named teammate into an active team for coordinated multi-agent work.
 
-**Not good for:**
-- Reading a specific file path — use Read or Glob directly
-- Searching within 2-3 known files — use Read directly
-- Searching for a specific class definition — use Glob directly
+Do NOT use when the target file or symbol is already known — use `Read`, `Grep`, or `Glob` directly. A single-step lookup through `Agent` wastes a full context window and adds latency.
 
-## Notes
-
-- After completion, the SubAgent returns a single message; its results are not visible to the user and need to be relayed by the main agent
-- Multiple Agent calls can be issued in parallel within a single message for efficiency
-- Background tasks are checked for progress via the TaskOutput tool
-- The Explore type is slower than directly calling Glob/Grep; only use it when simple searches are insufficient
-- Use `run_in_background: true` for long-running tasks that don't need immediate results; use foreground (default) when the main agent needs the result before proceeding
-- The `resume` parameter allows continuing a previously started SubAgent session, preserving its accumulated context
-
-## Original Text
+## Parameters
 
-<textarea readonly>Launch a new agent to handle complex, multi-step tasks autonomously.
+- `description` (string, required): Short 3–5 word label describing the task; shown in UI and logs.
+- `prompt` (string, required): The complete, self-contained brief the agent will execute. Must include all necessary context, constraints, and the expected return format.
+- `subagent_type` (string, optional): Preset persona such as `general-purpose`, `Explore`, `Plan`, `claude-code-guide`, or `statusline-setup`. Defaults to `general-purpose`.
+- `run_in_background` (boolean, optional): If true, the agent runs asynchronously and the parent can continue working; results are retrieved later.
+- `model` (string, optional): Override the model for this agent — `opus`, `sonnet`, or `haiku`. Defaults to the parent session model.
+- `isolation` (string, optional): Set to `worktree` to run the agent inside an isolated git worktree so its filesystem writes do not collide with the parent.
+- `team_name` (string, optional): When spawning into an existing team, the team identifier the agent will join.
+- `name` (string, optional): Addressable teammate name within the team, used as the `to` target for `SendMessage`.
 
-The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+## Examples
 
-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)
+### Example 1: Open-ended code search
 
-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
+### Example 2: Parallel independent investigations
 
-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.
+Launch two agents in the same message — one inspecting the build pipeline, one reviewing the test harness. Each gets its own context window and returns a summary. Batching in a single tool-call block runs them concurrently.
 
-Example usage:
+### Example 3: Spawn a teammate into a running team
 
-<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>
+- Agents have no memory of prior runs. Every invocation starts from zero, so the `prompt` must be fully self-contained — include file paths, conventions, the question, and the exact shape of the answer you want back.
+- The agent returns exactly one final message. It cannot ask clarifying questions mid-run, so ambiguity in the prompt becomes guesswork in the result.
+- Running multiple agents in parallel is significantly faster than sequential calls when the subtasks are independent. Batch them in a single tool-call block.
+- Use `isolation: "worktree"` whenever an agent will write files and you want to review changes before merging into the main working tree.
+- Prefer `subagent_type: "Explore"` for read-only reconnaissance and `Plan` for design work; `general-purpose` is the default for mixed read/write tasks.
+- Background agents (`run_in_background: true`) suit long-running jobs; avoid polling in a sleep loop — the parent is notified on completion.

package/concepts/en/Tool-AskUserQuestion.md

@@ -1,75 +1,60 @@
 # AskUserQuestion
 
-## Definition
+Presents the user with one or more structured multiple-choice questions inside the chat UI, collects their selections, and returns them to the assistant — useful for disambiguating intent without a free-form back-and-forth.
 
-Asks the user a question during execution to obtain clarification, validate assumptions, or request decisions.
+## When to Use
 
-## Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `questions` | array | Yes | List of questions (1-4 questions) |
-| `answers` | object | No | Answers collected from the user |
-| `annotations` | object | No | Annotations for each question (e.g., notes for preview selections) |
-| `metadata` | object | No | Metadata for tracking and analysis |
-
-Each `question` object:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `question` | string | Yes | Full question text, should end with a question mark |
-| `header` | string | Yes | Short label (max 12 characters), displayed as a tag chip |
-| `options` | array | Yes | 2-4 options |
-| `multiSelect` | boolean | Yes | Whether multiple selections are allowed |
-
-Each `option` object:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `label` | string | Yes | Option display text (1-5 words) |
-| `description` | string | Yes | Option description |
-| `markdown` | string | No | Preview content (for visual comparison of ASCII layouts, code snippets, etc.) |
-
-## Use Cases
+- A request has multiple reasonable interpretations and the assistant needs the user to pick one before proceeding.
+- The user must choose among concrete options (framework, library, file path, strategy) where free-text replies would be error-prone.
+- You want to compare alternatives side by side using the preview pane.
+- Several related decisions can be batched into a single prompt to reduce back-and-forth.
+- A plan or tool call depends on configuration the user has not yet specified.
 
-**Good for:**
-- Collecting user preferences or requirements
-- Clarifying ambiguous instructions
-- Getting decisions during implementation
-- Providing directional choices to the user
+## Parameters
 
-**Not good for:**
-- Asking "Is the plan okay?" — use ExitPlanMode instead
+- `questions` (array, required): One to four questions shown together in a single prompt. Each question object contains:
+  - `question` (string, required): The full question text, ending with a question mark.
+  - `header` (string, required): A short label (at most 12 characters) rendered as a chip above the question.
+  - `options` (array, required): Two to four option objects. Each option has a `label` (1–5 words), a `description`, and an optional `markdown` preview.
+  - `multiSelect` (boolean, required): When `true`, the user may pick more than one option.
+
+## Examples
+
+### Example 1: Pick a single framework
+
+```
+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"}
+  ]
+}])
+```
+
+### Example 2: Side-by-side preview of two layouts
+
+```
+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
 
-- The user can always choose "Other" to provide custom input
-- Place the recommended option first and append "(Recommended)" to its label
-- `markdown` preview is only supported for single-select questions
-- Options with `markdown` switch to a side-by-side layout
-- In plan mode, used to clarify requirements before finalizing the plan
-
-## Original Text
-
-<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>
+- The UI automatically appends an "Other" free-text option to every question. Do not add your own "Other", "None", or "Custom" entry — it will duplicate the built-in escape hatch.
+- Limit each call to between one and four questions and each question to between two and four options. Exceeding these bounds is rejected by the harness.
+- If you recommend a specific option, put it first and append "(Recommended)" to its label so the UI highlights the preferred path.
+- Previews via the `markdown` field are only supported on single-select questions. Use them for visual artifacts such as ASCII layouts, code snippets, or configuration diffs — not for simple preference questions where a label plus description suffice.
+- When any option in a question has a `markdown` value, the UI switches to a side-by-side layout with the option list on the left and the preview on the right.
+- Do not use `AskUserQuestion` to ask "does this plan look good?" — call `ExitPlanMode` instead, which exists precisely for plan approval. In plan mode, also avoid mentioning "the plan" in question text, because the plan is not visible to the user until `ExitPlanMode` runs.
+- Do not use this tool to request sensitive or free-form input such as API keys or passwords. Ask in chat instead.