diff --git a/.github/workflows/sdk-python.yml b/.github/workflows/sdk-python.yml
new file mode 100644
index 000000000..43e76dedb
--- /dev/null
+++ b/.github/workflows/sdk-python.yml
@@ -0,0 +1,59 @@
+name: 'SDK Python'
+
+on:
+  pull_request:
+    branches:
+      - 'main'
+      - 'release/**'
+    paths:
+      - 'packages/sdk-python/**'
+      - 'docs/developers/sdk-python.md'
+      - 'docs/developers/_meta.ts'
+      - 'README.md'
+      - 'package.json'
+      - '.github/workflows/sdk-python.yml'
+  push:
+    branches:
+      - 'main'
+      - 'release/**'
+    paths:
+      - 'packages/sdk-python/**'
+      - 'docs/developers/sdk-python.md'
+      - 'docs/developers/_meta.ts'
+      - 'README.md'
+      - 'package.json'
+      - '.github/workflows/sdk-python.yml'
+
+jobs:
+  sdk-python:
+    name: 'SDK Python (${{ matrix.python-version }})'
+    runs-on: 'ubuntu-latest'
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # ratchet:actions/checkout@v5
+
+      - name: 'Set up Python'
+        uses: 'actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065' # ratchet:actions/setup-python@v5
+        with:
+          python-version: '${{ matrix.python-version }}'
+
+      - name: 'Install SDK test dependencies'
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e 'packages/sdk-python[dev]'
+
+      - name: 'Run Ruff'
+        run: 'python -m ruff check --config packages/sdk-python/pyproject.toml packages/sdk-python'
+
+      - name: 'Run Ruff Format'
+        run: 'python -m ruff format --check --config packages/sdk-python/pyproject.toml packages/sdk-python'
+
+      - name: 'Run Mypy'
+        run: 'python -m mypy --config-file packages/sdk-python/pyproject.toml packages/sdk-python/src'
+
+      - name: 'Run Pytest'
+        run: 'python -m pytest -c packages/sdk-python/pyproject.toml packages/sdk-python/tests -q'
diff --git a/.gitignore b/.gitignore
index 9644bc90b..2dae5710a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,6 +26,7 @@ package-lock.json
 .qoder
 .claude
 CLAUDE.md
+.codex
 
 # Qwen Code Configs
 .qwen/*
@@ -88,3 +89,4 @@ storybook-static
 
 # Dev symlink: qc-helper bundled skill docs (created by scripts/dev.js)
 packages/core/src/skills/bundled/qc-helper/docs
+tmp/
\ No newline at end of file
diff --git a/README.md b/README.md
index b56c72120..5358f9d0e 100644
--- a/README.md
+++ b/README.md
@@ -424,7 +424,7 @@ As an open-source terminal agent, you can use Qwen Code in four primary ways:
 1. Interactive mode (terminal UI)
 2. Headless mode (scripts, CI)
 3. IDE integration (VS Code, Zed)
-4. TypeScript SDK
+4. SDKs (TypeScript, Python, Java)
 
 #### Interactive mode
 
@@ -452,11 +452,38 @@ Use Qwen Code inside your editor (VS Code, Zed, and JetBrains IDEs):
 - [Use in Zed](https://qwenlm.github.io/qwen-code-docs/en/users/integration-zed/)
 - [Use in JetBrains IDEs](https://qwenlm.github.io/qwen-code-docs/en/users/integration-jetbrains/)
 
-#### TypeScript SDK
+#### SDKs
 
-Build on top of Qwen Code with the TypeScript SDK:
+Build on top of Qwen Code with the available SDKs:
 
-- [Use the Qwen Code SDK](./packages/sdk-typescript/README.md)
+- TypeScript: [Use the Qwen Code SDK](./packages/sdk-typescript/README.md)
+- Python: [Use the Python SDK](./packages/sdk-python/README.md)
+- Java: [Use the Java SDK](./packages/sdk-java/qwencode/README.md)
+
+Python SDK example:
+
+```python
+import asyncio
+
+from qwen_code_sdk import is_sdk_result_message, query
+
+
+async def main() -> None:
+    result = query(
+        "Summarize the repository layout.",
+        {
+            "cwd": "/path/to/project",
+            "path_to_qwen_executable": "qwen",
+        },
+    )
+
+    async for message in result:
+        if is_sdk_result_message(message):
+            print(message["result"])
+
+
+asyncio.run(main())
+```
 
 ## Commands & Shortcuts
 
diff --git a/docs/design/openrouter-auth-and-models.md b/docs/design/openrouter-auth-and-models.md
new file mode 100644
index 000000000..7c82476a6
--- /dev/null
+++ b/docs/design/openrouter-auth-and-models.md
@@ -0,0 +1,89 @@
+# OpenRouter Auth and Model Management Design
+
+This document captures the design intent behind the OpenRouter auth flow and the
+model management changes introduced with it. It intentionally focuses on the
+product and architectural choices, not implementation history.
+
+## Goals
+
+- Let users authenticate with OpenRouter from both CLI and `/auth`.
+- Reuse the existing OpenAI-compatible provider path instead of adding a new auth
+  type for OpenRouter.
+- Make the first-run experience usable without asking users to manage hundreds of
+  models immediately.
+- Keep a clear path toward richer model management via `/manage-models`.
+
+## OpenRouter Auth
+
+OpenRouter is integrated as an OpenAI-compatible provider:
+
+- auth type: `AuthType.USE_OPENAI`
+- provider settings: `modelProviders.openai`
+- API key env var: `OPENROUTER_API_KEY`
+- base URL: `https://openrouter.ai/api/v1`
+
+This avoids introducing an OpenRouter-specific `AuthType` when the runtime model
+provider path is already OpenAI-compatible. It keeps auth status, model
+resolution, provider selection, and settings schema aligned with the existing
+provider abstraction.
+
+The user-facing flows are:
+
+- `qwen auth openrouter --key <key>` for automation or direct API-key setup.
+- `qwen auth openrouter` for browser-based OAuth.
+- `/auth` → API Key → OpenRouter for the TUI flow.
+
+Browser OAuth uses OpenRouter's PKCE flow and writes the exchanged API key into
+settings before refreshing auth as `AuthType.USE_OPENAI`.
+
+## Model Management
+
+OpenRouter exposes a large dynamic model catalog. Writing every discovered model
+into `modelProviders.openai` would make `/model` noisy and would turn a long-term
+settings field into a cache of a remote catalog.
+
+The key design split is:
+
+- **Catalog**: the full set of models discovered from a source such as
+  OpenRouter.
+- **Enabled set**: the smaller set of models that should appear in `/model` and
+  be persisted in user settings.
+
+For the initial OpenRouter flow, auth should finish with a useful default enabled
+set instead of interrupting the user with a large picker. The recommended set
+should be small, stable, and biased toward models that let users try the product
+successfully, including free models when available.
+
+`/model` remains a fast model switcher. It should not become the place where
+users browse and curate a full provider catalog.
+
+## `/manage-models`
+
+Richer model management belongs in a separate `/manage-models` entry point. That
+flow should let users:
+
+- browse discovered models;
+- search by id, display name, provider prefix, and derived tags such as `free` or
+  `vision`;
+- see which models are currently enabled;
+- enable or disable models in batches.
+
+The source dimension must remain part of this design. OpenRouter is only the
+first dynamic catalog source; future sources such as ModelScope and ModelStudio
+should fit the same shape. UI complexity can be reduced, but the underlying
+source abstraction should stay available as the extension point.
+
+## Current Boundary
+
+This change should do the minimum needed to make OpenRouter auth and model setup
+pleasant:
+
+- OAuth or key-based auth configures OpenRouter through the existing
+  OpenAI-compatible provider path.
+- The initial enabled model set is curated instead of dumping the full catalog
+  into settings.
+- Full catalog storage, browsing, filtering, and batch management are deferred to
+  `/manage-models`.
+
+The design principle is simple: authentication should get users to a working
+state quickly, while model curation should live in a dedicated management flow.
diff --git a/docs/design/tool-use-summary/tool-use-summary-design.md b/docs/design/tool-use-summary/tool-use-summary-design.md
new file mode 100644
index 000000000..f5d88a3e8
--- /dev/null
+++ b/docs/design/tool-use-summary/tool-use-summary-design.md
@@ -0,0 +1,177 @@
+# Tool-Use Summary Design
+
+> Fast-model labels for parallel tool batches — motivation, competitive analysis with Claude Code, architecture, and the append-only-Static rationale that drove the current full-mode render.
+>
+> User documentation: [Tool-Use Summaries](../../users/features/tool-use-summaries.md).
+
+## 1. Executive Summary
+
+After each tool batch completes, Qwen Code fires a short fast-model call that returns a git-commit-subject-style label summarizing the batch. The label shows as an inline dim `● <label>` line in full mode and replaces the generic `Tool × N` header in compact mode. Generation runs fire-and-forget in parallel with the next turn's API stream, so its ~1s latency is hidden behind main-model streaming.
+
+| Dimension             | Claude Code                                                           | Qwen Code                                                                                  |
+| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Trigger point         | `query.ts` — after a tool batch finalizes                             | `useGeminiStream.ts` → `handleCompletedTools` — same lifecycle point                       |
+| Generation model      | Haiku via `queryHaiku`                                                | Configured `fastModel` via `GeminiClient.generateContent`                                  |
+| Subagent behavior     | `!toolUseContext.agentId` — main session only                         | Implicit — subagents run through `agents/runtime/`, not `useGeminiStream`                  |
+| Scheduling            | Fire-and-forget, awaited right before the next turn's stream emits    | Fire-and-forget, appended to history when resolved                                         |
+| Output shape          | `ToolUseSummaryMessage` yielded into the SDK stream                   | `HistoryItemToolUseSummary` added to UI history + factory exported for future SDK use      |
+| Gate                  | `CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES` env, default **off**            | `experimental.emitToolUseSummaries` setting (default **on**) + env override                |
+| Primary consumer      | Mobile / SDK clients                                                  | CLI compact mode + full mode, future SDK                                                   |
+| Prompt                | Git-commit-subject, past tense, most distinctive noun (verbatim port) | Identical system prompt                                                                    |
+| Input truncation      | 300 chars per tool field via `truncateJson`                           | Identical                                                                                  |
+| Intent prefix         | First 200 chars of the assistant's last message                       | Identical                                                                                  |
+| Prompt caching        | `enablePromptCaching: true` on the Haiku call                         | Not yet wired (forked-agent route available; flagged as future optimization)               |
+| Label post-processing | Raw model text                                                        | `cleanSummary` (strips markdown, quotes, error-prefixes; caps at 100 chars, ReDoS-bounded) |
+| Session persistence   | Stream-only; each session regenerates                                 | UI history only; `ChatRecordingService` does not persist `tool_use_summary` entries        |
+
+## 2. Claude Code Implementation Analysis
+
+### 2.1 Flow
+
+Claude Code runs the tool loop in `query.ts`. After a tool batch executes and its results are normalized, the generator function forks a Haiku call, keeps the pending promise on `nextPendingToolUseSummary`, and continues with the next turn's API call. The Haiku latency (~1s) overlaps the main model's streaming (5–30s), so the user sees zero added latency. Right before emitting the next turn's content, the generator awaits the pending summary and yields a `tool_use_summary` message into the stream.
+
+```
+tool_batch_complete → fork queryHaiku (fire-and-forget)
+                          ↓
+               next_turn_stream_starts
+                          ↓
+       ← summary Promise resolves during streaming →
+                          ↓
+       await pendingToolUseSummary → yield ToolUseSummaryMessage
+                          ↓
+                continue with next turn
+```
+
+### 2.2 Key source files
+
+| Component       | File                                                       | Key logic                                                                               |
+| --------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Generator       | `services/toolUseSummary/toolUseSummaryGenerator.ts:45-97` | `generateToolUseSummary({ tools, signal, isNonInteractiveSession, lastAssistantText })` |
+| Trigger         | `query.ts:1411-1482`                                       | Guard by `emitToolUseSummaries` gate + no-subagent; fork Haiku; carry promise           |
+| Await + emit    | `query.ts:1055-1060`                                       | Await `pendingToolUseSummary` at next-turn boundary, yield message                      |
+| Message factory | `utils/messages.ts:5105-5116`                              | `createToolUseSummaryMessage(summary, precedingToolUseIds)`                             |
+| Feature gate    | `query/config.ts:23,36-38`                                 | `emitToolUseSummaries: isEnvTruthy(CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES)`                |
+
+### 2.3 Design decisions
+
+1. **Always generate when the gate is on, regardless of compact/detail state.** The summary is a stream-level artifact; the UI decides whether to render it.
+2. **Emit as a first-class message type.** `tool_use_summary` sits alongside `user`, `assistant`, `tool_result` in the SDK stream with a `precedingToolUseIds` field for consumers to correlate against the batch.
+3. **Subagents are excluded.** `!toolUseContext.agentId` — subagent output is aggregated upstream; individual subagent batches would produce noisy labels that never surface in the primary UI.
+4. **Default off.** The env-only gate keeps cost at zero unless a downstream SDK consumer opts in. The CC terminal itself does not render the message.
+5. **Input truncation at 300 chars per field.** Covers the dominant cost risk — a single large tool result blowing up the prompt — while keeping enough signal for the label.
+
+## 3. Qwen Code Implementation
+
+### 3.1 Flow
+
+Qwen Code hooks the same lifecycle point (`useGeminiStream.handleCompletedTools`) but renders on both sides of `ui.compactMode` so the feature is useful to CLI users without any SDK plumbing.
+
+```
+tool_batch_complete (handleCompletedTools)
+           ↓
+  config.getEmitToolUseSummaries()?
+           ↓
+   fork generateToolUseSummary (fire-and-forget)
+           ↓
+  submitQuery() for next turn (streaming starts)
+           ↓
+   ← summary Promise resolves during streaming →
+           ↓
+  addItem({type:'tool_use_summary', summary, precedingToolUseIds})
+           ↓
+  HistoryItemDisplay renders:
+    compactMode=false → ● <label> standalone line
+    compactMode=true  → hidden; MainContent lookup injects into CompactToolGroupDisplay header
+```
+
+### 3.2 Key source files
+
+| Component           | File                                                                  | Key logic                                                                 |
+| ------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Service             | `packages/core/src/services/toolUseSummary.ts`                        | `generateToolUseSummary`, `truncateJson`, `cleanSummary`, message factory |
+| Config gate         | `packages/core/src/config/config.ts:getEmitToolUseSummaries`          | Env override → settings → default (true)                                  |
+| Trigger             | `packages/cli/src/ui/hooks/useGeminiStream.ts:handleCompletedTools`   | Fires fast-model call, addItem on resolve                                 |
+| Full-mode render    | `packages/cli/src/ui/components/HistoryItemDisplay.tsx`               | Renders `● <label>` line when `!compactMode`                              |
+| Compact-mode lookup | `packages/cli/src/ui/components/MainContent.tsx`                      | `summaryByCallId` map → `compactLabel` prop to each tool_group            |
+| Compact header      | `packages/cli/src/ui/components/messages/CompactToolGroupDisplay.tsx` | Replaces default `Tool × N` with `<Summary> · N tools` when label present |
+| Merge handling      | `packages/cli/src/ui/utils/mergeCompactToolGroups.ts`                 | Treats `tool_use_summary` as hidden-in-compact for adjacency              |
+| UI type             | `packages/cli/src/ui/types.ts:HistoryItemToolUseSummary`              | `{ type: 'tool_use_summary', summary, precedingToolUseIds }`              |
+
+### 3.3 The `<Static>` append-only constraint
+
+The central architectural decision in this PR is **why the full-mode label is a standalone history item and not a decoration on the tool_group itself**.
+
+Qwen Code renders the transcript via Ink's `<Static>`. Static is append-only: once an item is committed to the terminal buffer, Ink will not repaint that region unless `refreshStatic()` is called to clear and re-render the entire transcript. This is the performance model the CLI depends on — static items don't re-render on every keystroke.
+
+Now consider the fast-model call's timing:
+
+```
+T0   tool batch completes, tool_group is pushed to history
+T0+ε tool_group renders through <Static> and is committed to the buffer
+T0+1s fast-model call resolves with a label
+```
+
+At T0+1s, we cannot retroactively add the label to the already-committed tool_group. Two options exist:
+
+1. **Update the tool_group's props + call `refreshStatic()`.** Works, but causes a full transcript repaint on every batch — one of the most expensive UI operations in the app. Visible flash. Unacceptable for a cosmetic label.
+2. **Render the summary as its own new history item appended _after_ the tool_group.** Static handles this natively — new items append cleanly, no repaint.
+
+This PR takes option 2 in full mode. The `tool_use_summary` entry is a real history item, rendered as a single dim `● <label>` line by `HistoryItemDisplay`. No `refreshStatic` needed.
+
+Compact mode is different because of `mergeCompactToolGroups`. When consecutive tool*groups merge, `MainContent` already calls `refreshStatic()` — that's an existing codepath, and it re-renders the merged group with the label looked up from history. So compact mode \_does* get the label as a header replacement. To avoid rendering the same label twice (once as the compact header, once as a trailing `● <label>` line), `HistoryItemDisplay` hides the standalone line when `compactMode` is true.
+
+```
+Full mode              Compact mode (with merge)
+───────────            ─────────────────────────
+[tool_group]           [merged tool_group — header replaced via lookup]
+● <label>              (● <label> line is hidden)
+```
+
+### 3.4 Gate semantics
+
+Three layers, resolved in order of precedence:
+
+1. `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0|1|true|false` — env override, highest priority.
+2. `experimental.emitToolUseSummaries` in `settings.json` — default `true`.
+3. Implicit skip — if `config.getFastModel()` returns `undefined`, generation is skipped regardless of the gate. No error, no user-visible change.
+
+### 3.5 Output cleaning
+
+`cleanSummary` runs on every model response before it is added to history:
+
+1. Take the first line only (drops model reasoning preambles).
+2. Strip bullet prefixes (`-`, `*`, `•`) — models sometimes return the label as a list item.
+3. Strip surrounding quotes/backticks via a bounded `{1,10}` regex (CodeQL-safe; no real label has more than a handful of wrapping quotes).
+4. Strip prefix labels (`Label:`, `Summary:`, `Result:`, `Output:`) that some models prepend.
+5. Reject error-message shapes (`API error: ...`, `Error: ...`, `I cannot ...`, `I can't ...`, `Unable to ...`) — returns empty string so no history item is added.
+6. Hard-cap length at 100 characters (mobile UI truncates around 30; the slack covers CJK phrases).
+
+### 3.6 Telemetry
+
+The summary generation call sets `promptId: 'tool_use_summary_generation'` so its token usage is accounted separately in `/stats`. This lets users see the exact incremental cost of the feature without conflating it with prompt suggestions or the main session's usage.
+
+## 4. Deviations from Claude Code (and why)
+
+| Deviation                                                                | Why                                                                                                                                                                                     |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Settings layer in addition to env gate                                   | Qwen Code renders the label in the CLI; users need a persistent switch, not a per-shell env export.                                                                                     |
+| Default **on** instead of off                                            | Label is immediately user-visible in both display modes; users configuring `fastModel` are opting into fast-model features already.                                                     |
+| Dedicated `cleanSummary` post-processing                                 | Qwen Code supports more heterogeneous providers than CC; some models prepend `Label:` or wrap in quotes. Normalizing at the boundary keeps the UI consistent.                           |
+| Stores `HistoryItemToolUseSummary` rather than emitting a stream message | CLI-first implementation; the SDK-stream route is a future PR. The `ToolUseSummaryMessage` factory is already exported for that work.                                                   |
+| Prompt caching not yet wired                                             | The fast model is often the same as the main model for users who haven't configured a separate one. Adding cache sharing requires routing via `forkedAgent.ts`; tracked as a follow-up. |
+| Dual render paths (full-mode inline + compact-mode header)               | Qwen Code's default is `ui.compactMode: false`; without the inline full-mode render, the feature would be invisible to most users.                                                      |
+
+## 5. Known limitations
+
+- **No session persistence.** `tool_use_summary` is not written to the chat recording JSONL. Resuming a session loses labels; tool groups render with the generic header as a fallback. Low-priority: labels regenerate naturally as the user continues the session.
+- **No SDK stream emission yet.** The message factory is exported, but the CLI does not yet feed `tool_use_summary` into the SDK bridge. Follow-up PR.
+- **No prompt caching.** Each batch incurs a fresh input-token cost. Negligible in absolute terms (~300 tokens) but measurable if you run dozens of batches per turn.
+- **Summary for merged compact groups picks the first contributing batch's label.** If a user fires ten dissimilar batches back-to-back (tight loop, not typical), the merged compact header will show only the leading batch's intent. Trade-off accepted: fanning out per-batch labels in a merged view is visually noisier than taking the first.
+- **Fast model required.** Without a configured `fastModel`, generation is skipped. Falling back to the main model is deliberately disallowed to keep the cost profile bounded.
+
+## 6. Future work
+
+1. Wire `ToolUseSummaryMessage` into the SDK bridge so the existing factory gets used downstream.
+2. Route generation via `forkedAgent.ts` with `enablePromptCaching` so repeated tool-name prefixes hit provider caches.
+3. Optional: persist `tool_use_summary` entries to `ChatRecordingService` and replay on session resume.
+4. Optional: per-tool-name label shortcuts (e.g., always `Read <filename>` for a single `read_file` call) as a pre-LLM fast path.
diff --git a/docs/developers/_meta.ts b/docs/developers/_meta.ts
index 42c938c9f..ed6597257 100644
--- a/docs/developers/_meta.ts
+++ b/docs/developers/_meta.ts
@@ -11,7 +11,8 @@ export default {
     type: 'separator',
   },
   'sdk-typescript': 'Typescript SDK',
-  'sdk-java': 'Java SDK(alpha)',
+  'sdk-python': 'Python SDK (alpha)',
+  'sdk-java': 'Java SDK (alpha)',
   'Dive Into Qwen Code': {
     title: 'Dive Into Qwen Code',
     type: 'separator',
diff --git a/docs/developers/development/telemetry.md b/docs/developers/development/telemetry.md
index 94859048e..006a668a7 100644
--- a/docs/developers/development/telemetry.md
+++ b/docs/developers/development/telemetry.md
@@ -7,8 +7,7 @@ Learn how to enable and setup OpenTelemetry for Qwen Code.
   - [OpenTelemetry Integration](#opentelemetry-integration)
   - [Configuration](#configuration)
   - [Aliyun Telemetry](#aliyun-telemetry)
-    - [Prerequisites](#prerequisites)
-    - [Direct Export (Recommended)](#direct-export-recommended)
+    - [Manual OTLP Export](#manual-otlp-export)
   - [Local Telemetry](#local-telemetry)
     - [File-based Output (Recommended)](#file-based-output-recommended)
     - [Collector-Based Export (Advanced)](#collector-based-export-advanced)
@@ -44,6 +43,11 @@ observability framework — Qwen Code's observability system provides:
   instrumentation
 
 [OpenTelemetry]: https://opentelemetry.io/
+[aliyun-opentelemetry-overview]: https://www.alibabacloud.com/help/en/arms/tracing-analysis/product-overview/what-is-tracing-analysis
+[aliyun-opentelemetry-get-started]: https://www.alibabacloud.com/help/en/arms/tracing-analysis/before-you-begin
+[aliyun-opentelemetry-console-cn]: https://trace.console.aliyun.com
+[aliyun-opentelemetry-console-cn-legacy]: https://tracing.console.aliyun.com
+[aliyun-opentelemetry-console-intl]: https://arms.console.alibabacloud.com
 
 ## Configuration
 
@@ -54,15 +58,15 @@ observability framework — Qwen Code's observability system provides:
 All telemetry behavior is controlled through your `.qwen/settings.json` file.
 These settings can be overridden by environment variables or CLI flags.
 
-| Setting        | Environment Variable           | CLI Flag                                                 | Description                                       | Values             | Default                 |
-| -------------- | ------------------------------ | -------------------------------------------------------- | ------------------------------------------------- | ------------------ | ----------------------- |
-| `enabled`      | `QWEN_TELEMETRY_ENABLED`       | `--telemetry` / `--no-telemetry`                         | Enable or disable telemetry                       | `true`/`false`     | `false`                 |
-| `target`       | `QWEN_TELEMETRY_TARGET`        | `--telemetry-target <local\|qwen>`                       | Where to send telemetry data                      | `"qwen"`/`"local"` | `"local"`               |
-| `otlpEndpoint` | `QWEN_TELEMETRY_OTLP_ENDPOINT` | `--telemetry-otlp-endpoint <URL>`                        | OTLP collector endpoint                           | URL string         | `http://localhost:4317` |
-| `otlpProtocol` | `QWEN_TELEMETRY_OTLP_PROTOCOL` | `--telemetry-otlp-protocol <grpc\|http>`                 | OTLP transport protocol                           | `"grpc"`/`"http"`  | `"grpc"`                |
-| `outfile`      | `QWEN_TELEMETRY_OUTFILE`       | `--telemetry-outfile <path>`                             | Save telemetry to file (overrides `otlpEndpoint`) | file path          | -                       |
-| `logPrompts`   | `QWEN_TELEMETRY_LOG_PROMPTS`   | `--telemetry-log-prompts` / `--no-telemetry-log-prompts` | Include prompts in telemetry logs                 | `true`/`false`     | `true`                  |
-| `useCollector` | `QWEN_TELEMETRY_USE_COLLECTOR` | -                                                        | Use external OTLP collector (advanced)            | `true`/`false`     | `false`                 |
+| Setting        | Environment Variable           | CLI Flag                                                 | Description                                       | Values            | Default                 |
+| -------------- | ------------------------------ | -------------------------------------------------------- | ------------------------------------------------- | ----------------- | ----------------------- |
+| `enabled`      | `QWEN_TELEMETRY_ENABLED`       | `--telemetry` / `--no-telemetry`                         | Enable or disable telemetry                       | `true`/`false`    | `false`                 |
+| `target`       | `QWEN_TELEMETRY_TARGET`        | `--telemetry-target <local\|gcp>`                        | Where to send telemetry data                      | `"gcp"`/`"local"` | `"local"`               |
+| `otlpEndpoint` | `QWEN_TELEMETRY_OTLP_ENDPOINT` | `--telemetry-otlp-endpoint <URL>`                        | OTLP collector endpoint                           | URL string        | `http://localhost:4317` |
+| `otlpProtocol` | `QWEN_TELEMETRY_OTLP_PROTOCOL` | `--telemetry-otlp-protocol <grpc\|http>`                 | OTLP transport protocol                           | `"grpc"`/`"http"` | `"grpc"`                |
+| `outfile`      | `QWEN_TELEMETRY_OUTFILE`       | `--telemetry-outfile <path>`                             | Save telemetry to file (overrides `otlpEndpoint`) | file path         | -                       |
+| `logPrompts`   | `QWEN_TELEMETRY_LOG_PROMPTS`   | `--telemetry-log-prompts` / `--no-telemetry-log-prompts` | Include prompts in telemetry logs                 | `true`/`false`    | `true`                  |
+| `useCollector` | `QWEN_TELEMETRY_USE_COLLECTOR` | -                                                        | Use external OTLP collector (advanced)            | `true`/`false`    | `false`                 |
 
 **Note on boolean environment variables:** For the boolean settings (`enabled`,
 `logPrompts`, `useCollector`), setting the corresponding environment variable to
@@ -73,21 +77,55 @@ For detailed information about all configuration options, see the
 
 ## Aliyun Telemetry
 
-### Direct Export (Recommended)
+### Manual OTLP Export
 
-Sends telemetry directly to Aliyun services. No collector needed.
+To view Qwen Code telemetry in Alibaba Cloud Managed Service for
+OpenTelemetry, configure Qwen Code to export to the OTLP endpoint
+provided by ARMS.
 
-1. Enable telemetry in your `.qwen/settings.json`:
+Setting `"target": "gcp"` alone does not configure the export
+destination. If `otlpEndpoint` is not set, Qwen Code still defaults to
+`http://localhost:4317`. If `outfile` is set, it overrides
+`otlpEndpoint` and telemetry is written to the file instead of being
+sent to Alibaba Cloud.
+
+1. Enable telemetry in your `.qwen/settings.json` and set the OTLP
+   endpoint:
    ```json
    {
      "telemetry": {
        "enabled": true,
-       "target": "qwen"
+       "target": "gcp",
+       "otlpEndpoint": "https://<your-otlp-endpoint>",
+       "otlpProtocol": "grpc"
      }
    }
    ```
-2. Run Qwen Code and send prompts.
-3. View logs and metrics in the Aliyun Console.
+2. If your Alibaba Cloud endpoint requires authentication, provide OTLP
+   headers through standard OpenTelemetry environment variables such as
+   `OTEL_EXPORTER_OTLP_HEADERS` (or the signal-specific variants). Qwen
+   Code does not currently expose OTLP auth headers directly in
+   `.qwen/settings.json`.
+3. Run Qwen Code and send prompts.
+4. View telemetry in Managed Service for OpenTelemetry:
+   - Product overview:
+     [What is Managed Service for OpenTelemetry?][aliyun-opentelemetry-overview]
+   - Getting started:
+     [Get started with Managed Service for OpenTelemetry][aliyun-opentelemetry-get-started]
+   - Console entry points:
+     - China mainland:
+       [trace.console.aliyun.com][aliyun-opentelemetry-console-cn]
+       (legacy console:
+       [tracing.console.aliyun.com][aliyun-opentelemetry-console-cn-legacy])
+     - International:
+       [arms.console.alibabacloud.com][aliyun-opentelemetry-console-intl]
+   - In the console, use `Applications` to inspect traces and service
+     topology.
+   - To locate the OTLP endpoint and access information:
+     - **New console** (`trace.console.aliyun.com` or international):
+       navigate to `Integration Center`.
+     - **Legacy console** (`tracing.console.aliyun.com`): navigate to
+       `Cluster Configurations` → `Access point information`.
 
 ## Local Telemetry
 
diff --git a/docs/developers/sdk-python.md b/docs/developers/sdk-python.md
new file mode 100644
index 000000000..7ef2c0ab6
--- /dev/null
+++ b/docs/developers/sdk-python.md
@@ -0,0 +1,168 @@
+# Python SDK
+
+## `qwen-code-sdk`
+
+`qwen-code-sdk` is an experimental Python SDK for Qwen Code. v1 targets the
+existing `stream-json` CLI protocol and keeps the transport surface small and
+testable.
+
+## Scope
+
+- Package name: `qwen-code-sdk`
+- Import path: `qwen_code_sdk`
+- Runtime requirement: Python `>=3.10`
+- CLI dependency: external `qwen` executable is required in v1
+- Transport scope: process transport only
+- Not included in v1: ACP transport, SDK-embedded MCP servers
+
+## Install
+
+```bash
+pip install qwen-code-sdk
+```
+
+If `qwen` is not on `PATH`, pass `path_to_qwen_executable` explicitly.
+
+## Quick Start
+
+```python
+import asyncio
+
+from qwen_code_sdk import is_sdk_result_message, query
+
+
+async def main() -> None:
+    result = query(
+        "Explain the repository structure.",
+        {
+            "cwd": "/path/to/project",
+            "path_to_qwen_executable": "qwen",
+        },
+    )
+
+    async for message in result:
+        if is_sdk_result_message(message):
+            print(message["result"])
+
+
+asyncio.run(main())
+```
+
+## API Surface
+
+### Top-level entry points
+
+- `query(prompt, options=None) -> Query`
+- `query_sync(prompt, options=None) -> SyncQuery`
+
+`prompt` supports either:
+
+- `str` for single-turn requests
+- `AsyncIterable[SDKUserMessage]` for multi-turn streams
+
+### `Query`
+
+- Async iterable over SDK messages
+- `close()`
+- `interrupt()`
+- `set_model(model)`
+- `set_permission_mode(mode)`
+- `supported_commands()`
+- `mcp_server_status()`
+- `get_session_id()`
+- `is_closed()`
+
+### `QueryOptions`
+
+Supported options in v1:
+
+- `cwd`
+- `model`
+- `path_to_qwen_executable`
+- `permission_mode`
+- `can_use_tool`
+- `env`
+- `system_prompt`
+- `append_system_prompt`
+- `debug`
+- `max_session_turns`
+- `core_tools`
+- `exclude_tools`
+- `allowed_tools`
+- `auth_type`
+- `include_partial_messages`
+- `resume`
+- `continue_session`
+- `session_id`
+- `timeout`
+- `mcp_servers`
+- `stderr`
+
+Session argument priority is fixed as:
+
+1. `resume`
+2. `continue_session`
+3. `session_id`
+
+## Permission Handling
+
+When the CLI emits a `can_use_tool` control request, the SDK routes it through
+`can_use_tool(tool_name, tool_input, context)`.
+
+- Default behavior: deny
+- Default timeout: 60 seconds
+- Timeout fallback: deny
+- Callback exceptions: converted to deny with an error message
+- Callback context: `cancel_event`, `suggestions`, and `blocked_path`
+- Callback contract: `can_use_tool` must be async with 3 positional arguments;
+  `stderr` must accept 1 positional string argument
+
+## Error Model
+
+- `ValidationError`: invalid options, invalid UUIDs, unsupported combinations
+- `ControlRequestTimeoutError`: initialize, interrupt, or other control request
+  timed out
+- `ProcessExitError`: CLI exited non-zero
+- `AbortError`: control request or session was cancelled
+
+## Troubleshooting
+
+If the SDK cannot start the CLI:
+
+- Verify `qwen --version` works in the target environment
+- Pass `path_to_qwen_executable` if your shell uses `nvm`, `pyenv`, or other
+  non-standard PATH setup
+- Use `debug=True` or `stderr=print` to surface CLI stderr while debugging
+
+If session control calls time out:
+
+- Check that the target `qwen` version supports `--input-format stream-json`
+- Increase `timeout.control_request`
+- Verify that no wrapper script is swallowing stdout/stderr
+
+## Repository Integration
+
+Repository-level helper commands:
+
+- `npm run test:sdk:python`
+- `npm run lint:sdk:python`
+- `npm run typecheck:sdk:python`
+- `npm run smoke:sdk:python -- --qwen qwen`
+
+## Real E2E Smoke
+
+For a real runtime check (actual `qwen` process + real model call), run from
+the repository root. The npm helper uses `python3`, so ensure it resolves to a
+Python `>=3.10` interpreter:
+
+```bash
+npm run smoke:sdk:python -- --qwen qwen
+```
+
+This script runs:
+
+- async single-turn query
+- async control flow (`supported_commands`, permission mode updates)
+- sync `query_sync` query
+
+It prints JSON and returns non-zero on failure.
diff --git a/docs/users/configuration/auth.md b/docs/users/configuration/auth.md
index e47fef752..75c6ec455 100644
--- a/docs/users/configuration/auth.md
+++ b/docs/users/configuration/auth.md
@@ -330,6 +330,7 @@ You'll see a selector with arrow-key navigation:
 Select authentication method:
 
   Alibaba Cloud Coding Plan - Paid · Up to 6,000 requests/5 hrs · All Alibaba Cloud Coding Plan Models
+  API Key - Bring your own API key
   Qwen OAuth - Discontinued — switch to Coding Plan or API Key
 
 (Use ↑ ↓ arrows to navigate, Enter to select, Ctrl+C to exit)
@@ -340,9 +341,10 @@ Select authentication method:
 | Command                                              | Description                                       |
 | ---------------------------------------------------- | ------------------------------------------------- |
 | `qwen auth`                                          | Interactive authentication setup                  |
-| `qwen auth qwen-oauth`                               | Authenticate with Qwen OAuth                      |
 | `qwen auth coding-plan`                              | Authenticate with Alibaba Cloud Coding Plan       |
 | `qwen auth coding-plan --region china --key sk-sp-…` | Non-interactive Coding Plan setup (for scripting) |
+| `qwen auth api-key`                                  | Authenticate with an API key                      |
+| `qwen auth qwen-oauth`                               | Authenticate with Qwen OAuth (discontinued)       |
 | `qwen auth status`                                   | Show current authentication status                |
 
 **Examples:**
@@ -357,6 +359,9 @@ qwen auth coding-plan
 # Set up Coding Plan non-interactively (useful for CI/scripting)
 qwen auth coding-plan --region china --key sk-sp-xxxxxxxxx
 
+# Set up API key (ModelStudio Standard or custom provider)
+qwen auth api-key
+
 # Check your current auth configuration
 qwen auth status
 ```
diff --git a/docs/users/configuration/settings.md b/docs/users/configuration/settings.md
index 8ea037779..751bdb35f 100644
--- a/docs/users/configuration/settings.md
+++ b/docs/users/configuration/settings.md
@@ -117,6 +117,7 @@ Settings are organized into categories. All settings should be placed within the
 | `ui.enableFollowupSuggestions`          | boolean          | Enable [followup suggestions](../features/followup-suggestions) that predict what you want to type next after the model responds. Suggestions appear as ghost text and can be accepted with Tab, Enter, or Right Arrow.                                                                                                                                                                                                                                                                                                                            | `true`      |
 | `ui.enableCacheSharing`                 | boolean          | Use cache-aware forked queries for suggestion generation. Reduces cost on providers that support prefix caching (experimental).                                                                                                                                                                                                                                                                                                                                                                                                                    | `true`      |
 | `ui.enableSpeculation`                  | boolean          | Speculatively execute accepted suggestions before submission. Results appear instantly when you accept (experimental).                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`     |
+| `experimental.emitToolUseSummaries`     | boolean          | Generate short LLM-based labels summarizing each tool-call batch. See [Tool-Use Summaries](../features/tool-use-summaries). Requires `fastModel` to be configured; silently skipped otherwise. Can be overridden per-session with `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=1`.                                                                                                                                                                                                                                                                   | `true`      |
 
 #### ide
 
@@ -133,17 +134,17 @@ Settings are organized into categories. All settings should be placed within the
 
 #### model
 
-| Setting                                            | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Default     |
-| -------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
-| `model.name`                                       | string  | The Qwen model to use for conversations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
-| `model.maxSessionTurns`                            | number  | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `-1`        |
-| `model.generationConfig`                           | object  | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `enableCacheControl`, `contextWindowSize` (override model's context window size), `modalities` (override auto-detected input modalities), `customHeaders` (custom HTTP headers for API requests), and `extra_body` (additional body parameters for OpenAI-compatible API requests only), along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults. | `undefined` |
-| `model.chatCompression.contextPercentageThreshold` | number  | Sets the threshold for chat history compression as a percentage of the model's total token limit. This is a value between 0 and 1 that applies to both automatic compression and the manual `/compress` command. For example, a value of `0.6` will trigger compression when the chat history exceeds 60% of the token limit. Use `0` to disable compression entirely.                                                                                                                                                                                               | `0.7`       |
-| `model.skipNextSpeakerCheck`                       | boolean | Skip the next speaker check.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`     |
-| `model.skipLoopDetection`                          | boolean | Disables loop detection checks. Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions.                                                                                                                                                                                                                                                                                                              | `false`     |
-| `model.skipStartupContext`                         | boolean | Skips sending the startup workspace context (environment summary and acknowledgement) at the beginning of each session. Enable this if you prefer to provide context manually or want to save tokens on startup.                                                                                                                                                                                                                                                                                                                                                     | `false`     |
-| `model.enableOpenAILogging`                        | boolean | Enables logging of OpenAI API calls for debugging and analysis. When enabled, API requests and responses are logged to JSON files.                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`     |
-| `model.openAILoggingDir`                           | string  | Custom directory path for OpenAI API logs. If not specified, defaults to `logs/openai` in the current working directory. Supports absolute paths, relative paths (resolved from current working directory), and `~` expansion (home directory).                                                                                                                                                                                                                                                                                                                      | `undefined` |
+| Setting                                            | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Default     |
+| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| `model.name`                                       | string  | The Qwen model to use for conversations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `undefined` |
+| `model.maxSessionTurns`                            | number  | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `-1`        |
+| `model.generationConfig`                           | object  | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `enableCacheControl`, `splitToolMedia` (set `true` for strict OpenAI-compatible servers like LM Studio that reject non-text content on `role: "tool"` messages — splits media into a follow-up user message), `contextWindowSize` (override model's context window size), `modalities` (override auto-detected input modalities), `customHeaders` (custom HTTP headers for API requests), and `extra_body` (additional body parameters for OpenAI-compatible API requests only), along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults. | `undefined` |
+| `model.chatCompression.contextPercentageThreshold` | number  | Sets the threshold for chat history compression as a percentage of the model's total token limit. This is a value between 0 and 1 that applies to both automatic compression and the manual `/compress` command. For example, a value of `0.6` will trigger compression when the chat history exceeds 60% of the token limit. Use `0` to disable compression entirely.                                                                                                                                                                                                                                                                                                                                                                                       | `0.7`       |
+| `model.skipNextSpeakerCheck`                       | boolean | Skip the next speaker check.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `false`     |
+| `model.skipLoopDetection`                          | boolean | Disables loop detection checks. Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`     |
+| `model.skipStartupContext`                         | boolean | Skips sending the startup workspace context (environment summary and acknowledgement) at the beginning of each session. Enable this if you prefer to provide context manually or want to save tokens on startup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`     |
+| `model.enableOpenAILogging`                        | boolean | Enables logging of OpenAI API calls for debugging and analysis. When enabled, API requests and responses are logged to JSON files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false`     |
+| `model.openAILoggingDir`                           | string  | Custom directory path for OpenAI API logs. If not specified, defaults to `logs/openai` in the current working directory. Supports absolute paths, relative paths (resolved from current working directory), and `~` expansion (home directory).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |
 
 **Example model.generationConfig:**
 
diff --git a/docs/users/features/_meta.ts b/docs/users/features/_meta.ts
index bdb2d6145..661a26c03 100644
--- a/docs/users/features/_meta.ts
+++ b/docs/users/features/_meta.ts
@@ -2,6 +2,7 @@ export default {
   commands: 'Commands',
   'code-review': 'Code Review',
   'followup-suggestions': 'Followup Suggestions',
+  'tool-use-summaries': 'Tool-Use Summaries',
   'sub-agents': 'SubAgents',
   arena: 'Agent Arena',
   skills: 'Skills',
diff --git a/docs/users/features/commands.md b/docs/users/features/commands.md
index 5ba31859c..7e80b519a 100644
--- a/docs/users/features/commands.md
+++ b/docs/users/features/commands.md
@@ -240,9 +240,10 @@ In addition to the in-session `/auth` slash command, Qwen Code provides standalo
 | Command                                              | Description                                                   |
 | ---------------------------------------------------- | ------------------------------------------------------------- |
 | `qwen auth`                                          | Interactive authentication setup                              |
-| `qwen auth qwen-oauth`                               | ~~Authenticate with Qwen OAuth~~ (discontinued on 2026-04-15) |
 | `qwen auth coding-plan`                              | Authenticate with Alibaba Cloud Coding Plan                   |
 | `qwen auth coding-plan --region china --key sk-sp-…` | Non-interactive Coding Plan setup (for scripting)             |
+| `qwen auth api-key`                                  | Authenticate with an API key                                  |
+| `qwen auth qwen-oauth`                               | ~~Authenticate with Qwen OAuth~~ (discontinued on 2026-04-15) |
 | `qwen auth status`                                   | Show current authentication status                            |
 
 > [!tip]
diff --git a/docs/users/features/tool-use-summaries.md b/docs/users/features/tool-use-summaries.md
new file mode 100644
index 000000000..8be660ca1
--- /dev/null
+++ b/docs/users/features/tool-use-summaries.md
@@ -0,0 +1,178 @@
+# Tool-Use Summaries
+
+Qwen Code can generate a short, git-commit-subject-style label after each tool batch completes, summarizing what the batch accomplished. The label appears inline in the transcript and replaces the generic `Tool × N` header in compact mode.
+
+This is a UX aid for parallel tool calls: when the model fans out into several `Read` + `Grep` + `Bash` calls at once, the summary tells you the intent at a glance instead of forcing you to scan the tool list.
+
+The feature is enabled by default and runs silently in the background. It requires a configured [fast model](./followup-suggestions#fast-model).
+
+## What You See
+
+### Full mode (default)
+
+The summary appears as a dim badge line directly below the tool group:
+
+```
+╭──────────────────────────────────────────────╮
+│ ✓  ReadFile a.txt                            │
+│ ✓  ReadFile b.txt                            │
+│ ✓  ReadFile c.txt                            │
+│ ✓  ReadFile d.txt                            │
+╰──────────────────────────────────────────────╯
+
+ ● Read 4 text files
+```
+
+### Compact mode (`Ctrl+O` or `ui.compactMode: true`)
+
+The label replaces the generic `Tool × N` header in the compact one-liner:
+
+```
+╭──────────────────────────────────────────────╮
+│✓  Read txt files  · 4 tools                  │
+│Press Ctrl+O to show full tool output         │
+╰──────────────────────────────────────────────╯
+```
+
+The individual tool calls are still a keystroke away (`Ctrl+O` to toggle to full mode).
+
+## How It Works
+
+After a tool batch finalizes, Qwen Code fires a fire-and-forget call to the configured fast model with:
+
+- The tool names, truncated arguments, and truncated results (each capped at 300 characters).
+- The assistant's most recent text output (first 200 characters) as an intent prefix.
+- A system prompt instructing the model to return a past-tense, 30-character label in git-commit-subject style.
+
+The call runs in parallel with the next turn's API streaming, so its ~1s latency is hidden behind the main model's response. When the label resolves, it is appended to the transcript as a `tool_use_summary` entry.
+
+Example labels: `Searched in auth/`, `Fixed NPE in UserService`, `Created signup endpoint`, `Read config.json`, `Ran failing tests`.
+
+## When It Appears
+
+The summary is generated when **all** of the following are true:
+
+- `experimental.emitToolUseSummaries` is `true` (default).
+- A `fastModel` is configured (via settings or `/model --fast`).
+- At least one tool completed in the batch.
+- The turn was not aborted before tool completion.
+- The fast model returned a non-empty, non-error response.
+
+Subagent tool calls do not trigger summary generation — only the main session's tool batches do.
+
+## When It Doesn't Appear
+
+The summary is silently skipped (no error, no UI change) when:
+
+- No fast model is configured.
+- The fast model call fails, times out, or returns empty.
+- The model returned an obvious error-message-like string (e.g., `Error: ...`, `I cannot ...`) — filtered out by the client so the UI does not show misleading labels.
+- The turn was aborted (`Ctrl+C`) before the model finished.
+
+In all these cases, the tool group renders as it always has.
+
+## Fast Model
+
+The label is generated using the [fast model](./followup-suggestions#fast-model) — the same model you configure for prompt suggestions and speculative execution. Configure it via:
+
+### Via command
+
+```
+/model --fast qwen3-coder-flash
+```
+
+### Via `settings.json`
+
+```json
+{
+  "fastModel": "qwen3-coder-flash"
+}
+```
+
+When no fast model is configured, summary generation is skipped entirely — the feature has no effect until you set one up.
+
+## Configuration
+
+These settings can be configured in `settings.json`:
+
+| Setting                             | Type    | Default | Description                                                                                        |
+| ----------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `experimental.emitToolUseSummaries` | boolean | `true`  | Master switch for summary generation. Turn off to disable the extra fast-model call.               |
+| `fastModel`                         | string  | `""`    | Fast model used for summary generation (shared with prompt suggestions). Required; no-op if empty. |
+
+### Environment override
+
+`QWEN_CODE_EMIT_TOOL_USE_SUMMARIES` overrides the `experimental.emitToolUseSummaries` setting for the current session:
+
+- `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=false` — force off.
+- `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=1` or `=true` — force on.
+- Unset — use the `experimental.emitToolUseSummaries` setting.
+
+### Example
+
+```json
+{
+  "fastModel": "qwen3-coder-flash",
+  "experimental": {
+    "emitToolUseSummaries": true
+  }
+}
+```
+
+## Scope & lifecycle
+
+Three points that tend to trip up a first read of this feature:
+
+1. **One generation per batch, shared by both display modes.** The fast-model call happens exactly once in `handleCompletedTools` when a tool batch finalizes. Toggling `Ctrl+O` afterwards does **not** trigger a new call — both modes read from the same `tool_use_summary` history entry that was captured the first time. You can flip compact mode on and off freely without extra cost.
+2. **No backfill on toggle or on session resume.** A `tool_group` that completed before the feature was enabled (or before you flipped the setting on, or in a resumed session — `ChatRecordingService` does not persist summary entries) will never get a label. There is no "sweep existing history" pass. If you turn this setting on mid-session, only _future_ batches will show a label; older groups keep the default rendering with no indicator that a label is missing.
+3. **Main-agent batches only.** The trigger lives in the main session's turn loop (`useGeminiStream`), so:
+   - ✅ Shell, MCP, file operations, and the `Task` / subagent tool _call itself_ (as it appears in the main batch) are summarized.
+   - ❌ A subagent's **internal** tool batches (run through `packages/core/src/agents/runtime/`) are not summarized.
+
+   An outer batch that _contains_ a `Task` tool will still be labeled, but the fast model sees only the subagent tool call and its aggregated output — not the individual tool calls inside the subagent. Expect labels like `Ran research-agent` or `Delegated file search` rather than `Searched 14 files`. This is intentional — summarizing subagent internals would multiply the fast-model cost and surface noise that never shows up in the primary UI.
+
+## Recommended pairing: enable compact mode
+
+For batches of 3+ parallel tool calls, pairing this feature with `ui.compactMode: true` produces the cleanest transcript. The compact view folds the whole batch into a single labeled row (`✓  Read txt files  · 4 tools`) instead of showing every tool line plus the trailing summary. Details remain one keystroke away via `Ctrl+O`.
+
+```json
+{
+  "fastModel": "qwen3-coder-flash",
+  "ui": {
+    "compactMode": true
+  },
+  "experimental": {
+    "emitToolUseSummaries": true
+  }
+}
+```
+
+In full mode (the default), the summary renders as a trailing `● <label>` line below the tool group — useful for large or heterogeneous batches, but for small same-type batches (e.g. `Read × 3`) the label can read as a restatement of the visible tool lines. If that matches your usual workflow, either turn compact mode on as above, or turn the summary off entirely via `experimental.emitToolUseSummaries: false`.
+
+## Monitoring
+
+Summary model usage appears in `/stats` output under the fast-model token totals, with the `prompt_id` `tool_use_summary_generation` so it can be distinguished from prompt suggestions and other background tasks.
+
+## Data flow & privacy
+
+The summary call sends each successful tool's name, truncated `args`, and truncated result (each field capped at 300 characters) to the **fast model**, plus the first 200 characters of the assistant's most recent text as an intent prefix.
+
+If your fast model is configured for the same provider/auth as your main session model, the data flows along the same boundary your main session already uses — no change in trust scope. If you have configured a fast model from a **different provider**, tool inputs and outputs (potentially including file contents read by `read_file`, command output from shell calls, or values surfaced through MCP tools) will be sent to that other provider as part of the summarization prompt. That is a strictly larger data-sharing scope than the main session alone.
+
+If this matters for your workflow, you have two clean options:
+
+- Configure `fastModel` to a model under the same provider as your main session, so the summary call doesn't cross any new auth/data boundary.
+- Disable the feature entirely with `experimental.emitToolUseSummaries: false` (or `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0`).
+
+The 300-character per-field cap limits exposure but does not eliminate it — secrets discovered in tool output during the cap window can still be sent. Treat the fast model's data boundary the same way you treat the main model's.
+
+## Cost
+
+One fast-model call per qualifying tool batch. Input is a small fixed system prompt plus the truncated tool inputs/outputs (each capped at 300 characters per field). Output is a single short line (capped at 100 characters, typically 20 tokens or fewer). On a typical fast model this is roughly $0.001 per batch.
+
+If you do not want the extra cost, turn the feature off via `experimental.emitToolUseSummaries: false` or `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0`.
+
+## Related
+
+- [Compact Mode](../configuration/settings#ui.compactMode) — toggle with `Ctrl+O`; the summary replaces the generic tool-group header when compact mode is on.
+- [Followup Suggestions](./followup-suggestions) — another fast-model-driven UX enhancement that shares the same `fastModel` setting.
diff --git a/docs/users/quickstart.md b/docs/users/quickstart.md
index db3914745..ee3ff6081 100644
--- a/docs/users/quickstart.md
+++ b/docs/users/quickstart.md
@@ -223,6 +223,7 @@ Here are the most important commands for daily use:
 | `qwen`                | start Qwen Code                                  | `qwen`                        |
 | `/auth`               | Change authentication method (in session)        | `/auth`                       |
 | `qwen auth`           | Configure authentication from the terminal       | `qwen auth`                   |
+| `qwen auth api-key`   | Configure API key authentication                 | `qwen auth api-key`           |
 | `qwen auth status`    | Check current authentication status              | `qwen auth status`            |
 | `/help`               | Display help information for available commands  | `/help` or `/?`               |
 | `/compress`           | Replace chat history with summary to save Tokens | `/compress`                   |
diff --git a/eslint.config.js b/eslint.config.js
index 27214f6d6..f2eb93ecf 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -190,10 +190,11 @@ export default tseslint.config(
   },
   // extra settings for scripts that we run directly with node
   {
-    files: ['./scripts/**/*.js', 'esbuild.config.js', 'packages/*/scripts/**/*.js'],
+    files: ['./scripts/**/*.js', './scripts/**/*.mjs', 'esbuild.config.js', 'packages/*/scripts/**/*.js'],
     languageOptions: {
       globals: {
         ...globals.node,
+        ...globals.browser,
         process: 'readonly',
         console: 'readonly',
       },
diff --git a/package-lock.json b/package-lock.json
index ecb84a6b5..1c6f4b57f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12842,6 +12842,7 @@
       "os": [
         "darwin"
       ],
+      "peer": true,
       "engines": {
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
diff --git a/package.json b/package.json
index 5611c59ea..507ea5da2 100644
--- a/package.json
+++ b/package.json
@@ -43,6 +43,7 @@
     "test:integration:sandbox:podman": "cross-env QWEN_SANDBOX=podman vitest run --root ./integration-tests",
     "test:integration:sdk:sandbox:none": "cross-env QWEN_SANDBOX=false vitest run --root ./integration-tests --poolOptions.threads.maxThreads 2 sdk-typescript",
     "test:integration:sdk:sandbox:docker": "cross-env QWEN_SANDBOX=docker npm run build:sandbox && QWEN_SANDBOX=docker vitest run --root ./integration-tests --poolOptions.threads.maxThreads 2 sdk-typescript",
+    "test:sdk:python": "python3 -m pytest -c packages/sdk-python/pyproject.toml packages/sdk-python/tests -q",
     "test:integration:cli:sandbox:none": "cross-env QWEN_SANDBOX=false vitest run --root ./integration-tests cli",
     "test:integration:cli:sandbox:docker": "cross-env QWEN_SANDBOX=docker npm run build:sandbox && QWEN_SANDBOX=docker vitest run --root ./integration-tests cli",
     "test:integration:interactive:sandbox:none": "cross-env QWEN_SANDBOX=false vitest run --root ./integration-tests interactive",
@@ -53,9 +54,12 @@
     "lint": "eslint . --ext .ts,.tsx && eslint integration-tests",
     "lint:fix": "eslint . --fix && eslint integration-tests --fix",
     "lint:ci": "eslint . --ext .ts,.tsx --max-warnings 0 && eslint integration-tests --max-warnings 0",
+    "lint:sdk:python": "python3 -m ruff check --config packages/sdk-python/pyproject.toml packages/sdk-python",
     "lint:all": "node scripts/lint.js",
     "format": "prettier --experimental-cli --write .",
     "typecheck": "npm run typecheck --workspaces --if-present",
+    "typecheck:sdk:python": "python3 -m mypy --config-file packages/sdk-python/pyproject.toml packages/sdk-python/src",
+    "smoke:sdk:python": "python3 packages/sdk-python/scripts/smoke_real.py",
     "check-i18n": "npm run check-i18n --workspace=packages/cli",
     "preflight": "npm run clean && npm ci && npm run format && npm run lint:ci && npm run build && npm run typecheck && npm run test:ci",
     "prepare": "husky && npm run build && npm run bundle",
diff --git a/packages/cli/src/acp-integration/session/Session.test.ts b/packages/cli/src/acp-integration/session/Session.test.ts
index 1f806b510..8178267b2 100644
--- a/packages/cli/src/acp-integration/session/Session.test.ts
+++ b/packages/cli/src/acp-integration/session/Session.test.ts
@@ -221,6 +221,7 @@ describe('Session', () => {
         {
           name: 'init',
           description: 'Initialize project context',
+          argumentHint: '[path]',
         },
       ]);
 
@@ -239,7 +240,7 @@ describe('Session', () => {
             {
               name: 'init',
               description: 'Initialize project context',
-              input: null,
+              input: { hint: '[path]' },
             },
           ],
         },
diff --git a/packages/cli/src/acp-integration/session/Session.ts b/packages/cli/src/acp-integration/session/Session.ts
index f4426faab..6521f3e12 100644
--- a/packages/cli/src/acp-integration/session/Session.ts
+++ b/packages/cli/src/acp-integration/session/Session.ts
@@ -981,7 +981,7 @@ export class Session implements SessionContext {
         (cmd) => ({
           name: cmd.name,
           description: cmd.description,
-          input: null,
+          input: cmd.argumentHint ? { hint: cmd.argumentHint } : null,
         }),
       );
 
diff --git a/packages/cli/src/commands/auth.ts b/packages/cli/src/commands/auth.ts
index b90795bc7..7c67cbd35 100644
--- a/packages/cli/src/commands/auth.ts
+++ b/packages/cli/src/commands/auth.ts
@@ -7,6 +7,7 @@
 import type { CommandModule, Argv } from 'yargs';
 import {
   handleQwenAuth,
+  handleApiKeyAuth,
   runInteractiveAuth,
   showAuthStatus,
 } from './auth/handler.js';
@@ -50,6 +51,29 @@ const codePlanCommand = {
   },
 };
 
+const apiKeyCommand = {
+  command: 'api-key',
+  describe: t('Authenticate using an API key'),
+  handler: async () => {
+    await handleApiKeyAuth();
+  },
+};
+
+const openRouterCommand = {
+  command: 'openrouter',
+  describe: t('Authenticate using OpenRouter API key setup'),
+  builder: (yargs: Argv) =>
+    yargs.option('key', {
+      alias: 'k',
+      describe: t('API key for OpenRouter'),
+      type: 'string',
+    }),
+  handler: async (argv: { key?: string }) => {
+    const key = argv['key'] as string | undefined;
+    await handleQwenAuth('openrouter', { key });
+  },
+};
+
 const statusCommand = {
   command: 'status',
   describe: t('Show current authentication status'),
@@ -61,12 +85,14 @@ const statusCommand = {
 export const authCommand: CommandModule = {
   command: 'auth',
   describe: t(
-    'Configure Qwen authentication information with Qwen-OAuth or Alibaba Cloud Coding Plan',
+    'Configure Qwen authentication with OpenRouter, Coding Plan, API Key, or Qwen-OAuth',
   ),
   builder: (yargs: Argv) =>
     yargs
       .command(qwenOauthCommand)
       .command(codePlanCommand)
+      .command(openRouterCommand)
+      .command(apiKeyCommand)
       .command(statusCommand)
       .demandCommand(0) // Don't require a subcommand
       .version(false),
diff --git a/packages/cli/src/commands/auth/handler.ts b/packages/cli/src/commands/auth/handler.ts
index 25a7d44fa..31c3aace6 100644
--- a/packages/cli/src/commands/auth/handler.ts
+++ b/packages/cli/src/commands/auth/handler.ts
@@ -12,18 +12,34 @@ import {
 } from '@qwen-code/qwen-code-core';
 import { writeStdoutLine, writeStderrLine } from '../../utils/stdioHelpers.js';
 import { t } from '../../i18n/index.js';
+import { getPersistScopeForModelSelection } from '../../config/modelProvidersScope.js';
 import {
   getCodingPlanConfig,
   isCodingPlanConfig,
   CodingPlanRegion,
   CODING_PLAN_ENV_KEY,
-} from '@qwen-code/qwen-code-core';
-import { getPersistScopeForModelSelection } from '../../config/modelProvidersScope.js';
+} from '../../constants/codingPlan.js';
 import { backupSettingsFile } from '../../utils/settingsUtils.js';
 import { loadSettings, type LoadedSettings } from '../../config/settings.js';
 import { loadCliConfig } from '../../config/config.js';
 import type { CliArgs } from '../../config/config.js';
 import { InteractiveSelector } from './interactiveSelector.js';
+import {
+  ALIBABA_STANDARD_API_KEY_ENDPOINTS,
+  DASHSCOPE_STANDARD_API_KEY_ENV_KEY,
+  type AlibabaStandardRegion,
+} from '../../constants/alibabaStandardApiKey.js';
+import {
+  applyOpenRouterModelsConfiguration,
+  createOpenRouterOAuthSession,
+  isOpenRouterConfig,
+  OPENROUTER_ENV_KEY,
+  runOpenRouterOAuthLogin,
+} from './openrouterOAuth.js';
+
+function formatElapsedTime(startMs: number): string {
+  return `${((Date.now() - startMs) / 1000).toFixed(2)}s`;
+}
 
 interface QwenAuthOptions {
   region?: string;
@@ -39,6 +55,8 @@ interface MergedSettingsWithCodingPlan {
   security?: {
     auth?: {
       selectedType?: string;
+      apiKey?: string;
+      baseUrl?: string;
     };
   };
   codingPlan?: CodingPlanSettings;
@@ -49,83 +67,93 @@ interface MergedSettingsWithCodingPlan {
   env?: Record<string, string>;
 }
 
+/**
+ * Creates a minimal CliArgs for auth command config loading
+ */
+function createMinimalArgv(): CliArgs {
+  return {
+    query: undefined,
+    model: undefined,
+    sandbox: undefined,
+    sandboxImage: undefined,
+    debug: undefined,
+    prompt: undefined,
+    promptInteractive: undefined,
+    yolo: undefined,
+    bare: undefined,
+    approvalMode: undefined,
+    telemetry: undefined,
+    checkpointing: undefined,
+    telemetryTarget: undefined,
+    telemetryOtlpEndpoint: undefined,
+    telemetryOtlpProtocol: undefined,
+    telemetryLogPrompts: undefined,
+    telemetryOutfile: undefined,
+    allowedMcpServerNames: undefined,
+    allowedTools: undefined,
+    acp: undefined,
+    experimentalAcp: undefined,
+    experimentalLsp: undefined,
+    extensions: [],
+    listExtensions: undefined,
+    openaiLogging: undefined,
+    openaiApiKey: undefined,
+    openaiBaseUrl: undefined,
+    openaiLoggingDir: undefined,
+    proxy: undefined,
+    includeDirectories: undefined,
+    screenReader: undefined,
+    inputFormat: undefined,
+    outputFormat: undefined,
+    includePartialMessages: undefined,
+    chatRecording: undefined,
+    continue: undefined,
+    resume: undefined,
+    sessionId: undefined,
+    maxSessionTurns: undefined,
+    coreTools: undefined,
+    excludeTools: undefined,
+    disabledSlashCommands: undefined,
+    authType: undefined,
+    channel: undefined,
+    systemPrompt: undefined,
+    appendSystemPrompt: undefined,
+  };
+}
+
+/**
+ * Loads settings and config for auth commands
+ */
+async function loadAuthConfig(settings: LoadedSettings) {
+  return loadCliConfig(
+    settings.merged,
+    createMinimalArgv(),
+    process.cwd(),
+    [],
+    {
+      userHooks: settings.getUserHooks(),
+      projectHooks: settings.getProjectHooks(),
+    },
+  );
+}
+
 /**
  * Handles the authentication process based on the specified command and options
  */
 export async function handleQwenAuth(
-  command: 'qwen-oauth' | 'coding-plan',
+  command: 'qwen-oauth' | 'coding-plan' | 'openrouter',
   options: QwenAuthOptions,
 ) {
   try {
     const settings = loadSettings();
-
-    // Create a minimal argv for config loading
-    const minimalArgv: CliArgs = {
-      query: undefined,
-      model: undefined,
-      sandbox: undefined,
-      sandboxImage: undefined,
-      debug: undefined,
-      prompt: undefined,
-      promptInteractive: undefined,
-      yolo: undefined,
-      bare: undefined,
-      approvalMode: undefined,
-      telemetry: undefined,
-      checkpointing: undefined,
-      telemetryTarget: undefined,
-      telemetryOtlpEndpoint: undefined,
-      telemetryOtlpProtocol: undefined,
-      telemetryLogPrompts: undefined,
-      telemetryOutfile: undefined,
-      allowedMcpServerNames: undefined,
-      allowedTools: undefined,
-      acp: undefined,
-      experimentalAcp: undefined,
-      experimentalLsp: undefined,
-      extensions: [],
-      listExtensions: undefined,
-      openaiLogging: undefined,
-      openaiApiKey: undefined,
-      openaiBaseUrl: undefined,
-      openaiLoggingDir: undefined,
-      proxy: undefined,
-      includeDirectories: undefined,
-      screenReader: undefined,
-      inputFormat: undefined,
-      outputFormat: undefined,
-      includePartialMessages: undefined,
-      chatRecording: undefined,
-      continue: undefined,
-      resume: undefined,
-      sessionId: undefined,
-      maxSessionTurns: undefined,
-      coreTools: undefined,
-      excludeTools: undefined,
-      disabledSlashCommands: undefined,
-      authType: undefined,
-      channel: undefined,
-      systemPrompt: undefined,
-      appendSystemPrompt: undefined,
-    };
-
-    // Create a minimal config to access settings and storage
-    const config = await loadCliConfig(
-      settings.merged,
-      minimalArgv,
-      process.cwd(),
-      [], // No extensions for auth command
-      // Pass separated hooks for proper source attribution
-      {
-        userHooks: settings.getUserHooks(),
-        projectHooks: settings.getProjectHooks(),
-      },
-    );
+    const config = await loadAuthConfig(settings);
 
     if (command === 'qwen-oauth') {
       await handleQwenOAuth(config, settings);
     } else if (command === 'coding-plan') {
       await handleCodePlanAuth(config, settings, options);
+    } else if (command === 'openrouter') {
+      await handleOpenRouterAuth(config, settings, options);
     }
 
     // Exit after authentication is complete
@@ -279,6 +307,105 @@ async function handleCodePlanAuth(
   }
 }
 
+/**
+ * Handles OpenRouter API key setup.
+ */
+async function handleOpenRouterAuth(
+  config: Config,
+  settings: LoadedSettings,
+  options: QwenAuthOptions,
+): Promise<void> {
+  writeStdoutLine(t('Processing OpenRouter authentication...'));
+
+  try {
+    const authStartMs = Date.now();
+    let selectedKey = options.key;
+
+    if (!selectedKey) {
+      const oauthStartMs = Date.now();
+      const oauthSession = createOpenRouterOAuthSession();
+      writeStdoutLine(
+        t(
+          'Starting OpenRouter OAuth in your browser. If needed, open this link manually: {{authorizationUrl}}',
+          {
+            authorizationUrl: oauthSession.authorizationUrl,
+          },
+        ),
+      );
+      const oauthResult = await runOpenRouterOAuthLogin(undefined, {
+        session: oauthSession,
+      });
+      writeStdoutLine(
+        t('Waited for OpenRouter browser authorization in {{elapsed}}.', {
+          elapsed:
+            typeof oauthResult.authorizationCodeWaitMs === 'number'
+              ? `${(oauthResult.authorizationCodeWaitMs / 1000).toFixed(2)}s`
+              : formatElapsedTime(oauthStartMs),
+        }),
+      );
+      writeStdoutLine(
+        t('Exchanged OpenRouter auth code for API key in {{elapsed}}.', {
+          elapsed:
+            typeof oauthResult.apiKeyExchangeMs === 'number'
+              ? `${(oauthResult.apiKeyExchangeMs / 1000).toFixed(2)}s`
+              : formatElapsedTime(oauthStartMs),
+        }),
+      );
+      writeStdoutLine(
+        t('OpenRouter OAuth callback completed in {{elapsed}}.', {
+          elapsed: formatElapsedTime(oauthStartMs),
+        }),
+      );
+      selectedKey = oauthResult.apiKey;
+    }
+
+    if (!selectedKey) {
+      throw new Error(
+        'OpenRouter authentication completed without an API key.',
+      );
+    }
+
+    const authTypeScope = getPersistScopeForModelSelection(settings);
+    const settingsFile = settings.forScope(authTypeScope);
+    backupSettingsFile(settingsFile.path);
+
+    const modelsStartMs = Date.now();
+    await applyOpenRouterModelsConfiguration({
+      settings,
+      config,
+      apiKey: selectedKey,
+      reloadConfig: true,
+    });
+    writeStdoutLine(
+      t('Fetched OpenRouter models in {{elapsed}}.', {
+        elapsed: formatElapsedTime(modelsStartMs),
+      }),
+    );
+
+    const refreshStartMs = Date.now();
+    await config.refreshAuth(AuthType.USE_OPENAI);
+    writeStdoutLine(
+      t('Refreshed OpenRouter auth in {{elapsed}}.', {
+        elapsed: formatElapsedTime(refreshStartMs),
+      }),
+    );
+    writeStdoutLine(
+      t('Total OpenRouter setup time: {{elapsed}}.', {
+        elapsed: formatElapsedTime(authStartMs),
+      }),
+    );
+
+    writeStdoutLine(t('Successfully configured OpenRouter.'));
+  } catch (error) {
+    writeStderrLine(
+      t('Failed to configure OpenRouter: {{error}}', {
+        error: getErrorMessage(error),
+      }),
+    );
+    process.exit(1);
+  }
+}
+
 /**
  * Prompts the user to select a region using an interactive selector
  */
@@ -303,16 +430,21 @@ async function promptForRegion(): Promise<CodingPlanRegion> {
 }
 
 /**
- * Prompts the user to enter an API key
+ * Generic raw-mode text input prompt.
+ * @param promptText - Text displayed before the cursor
+ * @param options.mask - If true, echoes '*' instead of the typed character (for passwords)
+ * @param options.defaultValue - Value returned when the user presses Enter on empty input
  */
-async function promptForKey(): Promise<string> {
-  // Create a simple password-style input (without echoing characters)
+async function promptForInput(
+  promptText: string,
+  options: { mask?: boolean; defaultValue?: string } = {},
+): Promise<string> {
+  const { mask = false, defaultValue } = options;
   const stdin = process.stdin;
   const stdout = process.stdout;
 
-  stdout.write(t('Enter your Coding Plan API key: '));
+  stdout.write(promptText);
 
-  // Set raw mode to capture keystrokes
   const wasRaw = stdin.isRaw;
   if (stdin.setRawMode) {
     stdin.setRawMode(true);
@@ -331,8 +463,10 @@ async function promptForKey(): Promise<string> {
             if (stdin.setRawMode) {
               stdin.setRawMode(wasRaw);
             }
-            stdout.write('\n'); // New line after input
-            resolve(input);
+            stdout.write('\n');
+            resolve(
+              defaultValue !== undefined && !input ? defaultValue : input,
+            );
             return;
           case '\x03': // Ctrl+C
             stdin.removeListener('data', onData);
@@ -351,10 +485,8 @@ async function promptForKey(): Promise<string> {
             }
             break;
           default:
-            // Add character to input
             input += char;
-            // Print asterisk instead of the actual character for security
-            stdout.write('*');
+            stdout.write(mask ? '*' : char);
             break;
         }
       }
@@ -364,12 +496,28 @@ async function promptForKey(): Promise<string> {
   });
 }
 
+/**
+ * Prompts the user to enter an API key (masked input)
+ */
+async function promptForKey(
+  promptText: string = t('Enter your Coding Plan API key: '),
+): Promise<string> {
+  return promptForInput(promptText, { mask: true });
+}
+
 /**
  * Runs the interactive authentication flow
  */
 export async function runInteractiveAuth() {
   const selector = new InteractiveSelector(
     [
+      {
+        value: 'openrouter' as const,
+        label: t('OpenRouter'),
+        description: t(
+          'API key setup · OpenAI-compatible provider via OpenRouter',
+        ),
+      },
       {
         value: 'coding-plan' as const,
         label: t('Alibaba Cloud Coding Plan'),
@@ -377,6 +525,11 @@ export async function runInteractiveAuth() {
           'Paid · Up to 6,000 requests/5 hrs · All Alibaba Cloud Coding Plan Models',
         ),
       },
+      {
+        value: 'api-key' as const,
+        label: t('API Key'),
+        description: t('Bring your own API key'),
+      },
       {
         value: 'qwen-oauth' as const,
         label: t('Qwen OAuth'),
@@ -400,9 +553,227 @@ export async function runInteractiveAuth() {
 
   if (choice === 'coding-plan') {
     await handleQwenAuth('coding-plan', {});
+  } else if (choice === 'api-key') {
+    await handleApiKeyAuth();
+  } else if (choice === 'openrouter') {
+    await handleQwenAuth('openrouter', {});
   }
 }
 
+/**
+ * Handles API Key authentication - shows sub-menu for Standard or Custom API key
+ */
+export async function handleApiKeyAuth() {
+  try {
+    const selector = new InteractiveSelector(
+      [
+        {
+          value: 'alibaba-standard' as const,
+          label: t('Alibaba Cloud ModelStudio Standard API Key'),
+          description: t('Quick setup for Model Studio (China/International)'),
+        },
+        {
+          value: 'custom' as const,
+          label: t('Custom API Key'),
+          description: t(
+            'For other OpenAI / Anthropic / Gemini-compatible providers',
+          ),
+        },
+      ],
+      t('Select API key type:'),
+    );
+
+    const choice = await selector.select();
+
+    if (choice === 'alibaba-standard') {
+      await handleAlibabaStandardApiKeyAuth();
+    } else if (choice === 'custom') {
+      handleCustomApiKeyAuth();
+    }
+  } catch (error) {
+    writeStderrLine(getErrorMessage(error));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles Alibaba Cloud ModelStudio Standard API Key authentication
+ */
+async function handleAlibabaStandardApiKeyAuth(): Promise<void> {
+  try {
+    const settings = loadSettings();
+    const config = await loadAuthConfig(settings);
+
+    // Step 1: Select region
+    const region = await promptForStandardRegion();
+
+    // Step 2: Enter API key
+    const apiKey = await promptForKey(t('Enter your API key: '));
+    const trimmedApiKey = apiKey.trim();
+    if (!trimmedApiKey) {
+      writeStderrLine(t('API key cannot be empty.'));
+      process.exit(1);
+    }
+
+    // Step 3: Enter model IDs
+    const modelIdsInput = await promptForModelIds();
+    const modelIds = modelIdsInput
+      .split(',')
+      .map((id) => id.trim())
+      .filter(
+        (id, index, array) => id.length > 0 && array.indexOf(id) === index,
+      );
+    if (modelIds.length === 0) {
+      writeStderrLine(t('Model IDs cannot be empty.'));
+      process.exit(1);
+    }
+
+    writeStdoutLine(
+      t('Processing Alibaba Cloud ModelStudio Standard API Key...'),
+    );
+
+    // Persist settings
+    const baseUrl = ALIBABA_STANDARD_API_KEY_ENDPOINTS[region];
+    const persistScope = getPersistScopeForModelSelection(settings);
+    const settingsFile = settings.forScope(persistScope);
+    backupSettingsFile(settingsFile.path);
+
+    // Store API key
+    settings.setValue(
+      persistScope,
+      `env.${DASHSCOPE_STANDARD_API_KEY_ENV_KEY}`,
+      trimmedApiKey,
+    );
+    process.env[DASHSCOPE_STANDARD_API_KEY_ENV_KEY] = trimmedApiKey;
+
+    // Build model configs
+    const newConfigs: ModelConfig[] = modelIds.map((modelId) => ({
+      id: modelId,
+      name: `[ModelStudio Standard] ${modelId}`,
+      baseUrl,
+      envKey: DASHSCOPE_STANDARD_API_KEY_ENV_KEY,
+    }));
+
+    // Get existing configs and filter out old Alibaba Standard entries
+    const existingConfigs =
+      (settings.merged.modelProviders as Record<string, ModelConfig[]>)?.[
+        AuthType.USE_OPENAI
+      ] || [];
+
+    const nonReplacedConfigs = existingConfigs.filter(
+      (existing) =>
+        // Filter out old Alibaba Standard entries
+        !(
+          existing.envKey === DASHSCOPE_STANDARD_API_KEY_ENV_KEY &&
+          typeof existing.baseUrl === 'string' &&
+          Object.values(ALIBABA_STANDARD_API_KEY_ENDPOINTS).includes(
+            existing.baseUrl,
+          )
+        ) &&
+        // Filter out Coding Plan entries (their key will be cleared)
+        !isCodingPlanConfig(existing.baseUrl, existing.envKey),
+    );
+
+    const updatedConfigs = [...newConfigs, ...nonReplacedConfigs];
+
+    // Persist model providers and auth settings
+    settings.setValue(
+      persistScope,
+      `modelProviders.${AuthType.USE_OPENAI}`,
+      updatedConfigs,
+    );
+    settings.setValue(
+      persistScope,
+      'security.auth.selectedType',
+      AuthType.USE_OPENAI,
+    );
+    settings.setValue(persistScope, 'model.name', modelIds[0]);
+
+    // Clear stale Coding Plan state to avoid incorrect status/update prompts
+    delete process.env[CODING_PLAN_ENV_KEY];
+    settings.setValue(persistScope, `env.${CODING_PLAN_ENV_KEY}`, '');
+    settings.setValue(persistScope, 'codingPlan.region', '');
+    settings.setValue(persistScope, 'codingPlan.version', '');
+
+    // Reload and refresh
+    const updatedModelProviders: Record<string, ModelConfig[]> = {
+      ...(settings.merged.modelProviders as Record<string, ModelConfig[]>),
+      [AuthType.USE_OPENAI]: updatedConfigs,
+    };
+    config.reloadModelProvidersConfig(updatedModelProviders);
+    await config.refreshAuth(AuthType.USE_OPENAI);
+
+    writeStdoutLine(
+      t(
+        'Successfully configured Alibaba Cloud ModelStudio Standard API Key with {{modelCount}} model(s).',
+        { modelCount: String(modelIds.length) },
+      ),
+    );
+    process.exit(0);
+  } catch (error) {
+    writeStderrLine(getErrorMessage(error));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles Custom API Key - prints docs link
+ */
+function handleCustomApiKeyAuth(): void {
+  writeStdoutLine(
+    t(
+      '\nYou can configure your API key and models in settings.json.\nRefer to the documentation for setup instructions:\n  https://qwenlm.github.io/qwen-code-docs/en/users/configuration/model-providers/\n',
+    ),
+  );
+  process.exit(0);
+}
+
+/**
+ * Prompts the user to select a region for ModelStudio Standard API Key
+ */
+async function promptForStandardRegion(): Promise<AlibabaStandardRegion> {
+  const selector = new InteractiveSelector(
+    [
+      {
+        value: 'cn-beijing' as AlibabaStandardRegion,
+        label: t('China (Beijing)'),
+        description: ALIBABA_STANDARD_API_KEY_ENDPOINTS['cn-beijing'],
+      },
+      {
+        value: 'sg-singapore' as AlibabaStandardRegion,
+        label: t('Singapore'),
+        description: ALIBABA_STANDARD_API_KEY_ENDPOINTS['sg-singapore'],
+      },
+      {
+        value: 'us-virginia' as AlibabaStandardRegion,
+        label: t('US (Virginia)'),
+        description: ALIBABA_STANDARD_API_KEY_ENDPOINTS['us-virginia'],
+      },
+      {
+        value: 'cn-hongkong' as AlibabaStandardRegion,
+        label: t('China (Hong Kong)'),
+        description: ALIBABA_STANDARD_API_KEY_ENDPOINTS['cn-hongkong'],
+      },
+    ],
+    t('Select region:'),
+  );
+
+  return await selector.select();
+}
+
+/**
+ * Prompts the user to enter comma-separated model IDs
+ */
+async function promptForModelIds(): Promise<string> {
+  const defaultModels = 'qwen3.5-plus,glm-5,kimi-k2.5';
+  return promptForInput(
+    t('Enter model IDs (comma-separated, default: {{default}}): ', {
+      default: defaultModels,
+    }),
+    { defaultValue: defaultModels },
+  );
+}
+
 /**
  * Shows the current authentication status
  */
@@ -420,13 +791,19 @@ export async function showAuthStatus(): Promise<void> {
       writeStdoutLine(t('⚠️  No authentication method configured.\n'));
       writeStdoutLine(t('Run one of the following commands to get started:\n'));
       writeStdoutLine(
-        t(
-          '  qwen auth qwen-oauth     - Authenticate with Qwen OAuth (free tier)',
-        ),
+        t('  qwen auth openrouter      - Configure OpenRouter API key'),
       );
       writeStdoutLine(
         t(
-          '  qwen auth coding-plan      - Authenticate with Alibaba Cloud Coding Plan\n',
+          '  qwen auth coding-plan    - Authenticate with Alibaba Cloud Coding Plan',
+        ),
+      );
+      writeStdoutLine(
+        t('  qwen auth api-key        - Authenticate with an API key'),
+      );
+      writeStdoutLine(
+        t(
+          '  qwen auth qwen-oauth     - Authenticate with Qwen OAuth (discontinued)\n',
         ),
       );
       writeStdoutLine(t('Or simply run:'));
@@ -446,54 +823,259 @@ export async function showAuthStatus(): Promise<void> {
         t('\n  ⚠ Run /auth to switch to Coding Plan or another provider.\n'),
       );
     } else if (selectedType === AuthType.USE_OPENAI) {
-      // Check for Coding Plan configuration
       const codingPlanRegion = mergedSettings.codingPlan?.region;
       const codingPlanVersion = mergedSettings.codingPlan?.version;
       const modelName = mergedSettings.model?.name;
-
-      // Check if API key is set in environment
-      const hasApiKey =
-        !!process.env[CODING_PLAN_ENV_KEY] ||
-        !!mergedSettings.env?.[CODING_PLAN_ENV_KEY];
-
-      if (hasApiKey) {
-        writeStdoutLine(
-          t('✓ Authentication Method: Alibaba Cloud Coding Plan'),
+      const openAiProviders =
+        mergedSettings.modelProviders?.[AuthType.USE_OPENAI] || [];
+      const activeConfig = modelName
+        ? openAiProviders.find((c) => c.id === modelName)
+        : openAiProviders[0];
+      const isActiveOpenRouter = activeConfig
+        ? isOpenRouterConfig(activeConfig)
+        : false;
+      const providerCodingPlanRegion = isCodingPlanConfig(
+        activeConfig?.baseUrl,
+        activeConfig?.envKey,
+      );
+      const detectedCodingPlanRegion = activeConfig
+        ? providerCodingPlanRegion
+        : !modelName
+          ? codingPlanRegion
+          : false;
+      const isActiveStandard =
+        activeConfig &&
+        activeConfig.envKey === DASHSCOPE_STANDARD_API_KEY_ENV_KEY &&
+        typeof activeConfig.baseUrl === 'string' &&
+        Object.values(ALIBABA_STANDARD_API_KEY_ENDPOINTS).includes(
+          activeConfig.baseUrl,
         );
+      const hasOpenRouterApiKey =
+        !!process.env[OPENROUTER_ENV_KEY] ||
+        !!mergedSettings.env?.[OPENROUTER_ENV_KEY];
 
-        if (codingPlanRegion) {
-          const regionDisplay =
-            codingPlanRegion === CodingPlanRegion.CHINA
-              ? t('中国 (China) - 阿里云百炼')
-              : t('Global - Alibaba Cloud');
-          writeStdoutLine(t('  Region: {{region}}', { region: regionDisplay }));
-        }
+      if (isActiveOpenRouter) {
+        if (hasOpenRouterApiKey) {
+          writeStdoutLine(t('✓ Authentication Method: OpenRouter'));
 
-        if (modelName) {
+          if (modelName) {
+            writeStdoutLine(
+              t('  Current Model: {{model}}', { model: modelName }),
+            );
+          }
+
+          writeStdoutLine(t('  Status: API key configured\n'));
+        } else {
           writeStdoutLine(
-            t('  Current Model: {{model}}', { model: modelName }),
+            t('⚠️  Authentication Method: OpenRouter (Incomplete)'),
+          );
+          writeStdoutLine(
+            t('  Issue: API key not found in environment or settings\n'),
+          );
+          writeStdoutLine(t('  Run `qwen auth openrouter` to re-configure.\n'));
+        }
+      } else if (detectedCodingPlanRegion) {
+        const hasCodingPlanKey =
+          !!process.env[CODING_PLAN_ENV_KEY] ||
+          !!mergedSettings.env?.[CODING_PLAN_ENV_KEY];
+
+        if (hasCodingPlanKey) {
+          writeStdoutLine(
+            t('✓ Authentication Method: Alibaba Cloud Coding Plan'),
+          );
+
+          const displayRegion = codingPlanRegion || detectedCodingPlanRegion;
+          if (displayRegion) {
+            const regionDisplay =
+              displayRegion === CodingPlanRegion.CHINA
+                ? t('中国 (China) - 阿里云百炼')
+                : t('Global - Alibaba Cloud');
+            writeStdoutLine(
+              t('  Region: {{region}}', { region: regionDisplay }),
+            );
+          }
+
+          if (modelName) {
+            writeStdoutLine(
+              t('  Current Model: {{model}}', { model: modelName }),
+            );
+          }
+
+          if (codingPlanVersion) {
+            writeStdoutLine(
+              t('  Config Version: {{version}}', {
+                version: codingPlanVersion.substring(0, 8) + '...',
+              }),
+            );
+          }
+
+          writeStdoutLine(t('  Status: API key configured\n'));
+        } else {
+          writeStdoutLine(
+            t(
+              '⚠️  Authentication Method: Alibaba Cloud Coding Plan (Incomplete)',
+            ),
+          );
+          writeStdoutLine(
+            t('  Issue: API key not found in environment or settings\n'),
+          );
+          writeStdoutLine(
+            t('  Run `qwen auth coding-plan` to re-configure.\n'),
           );
         }
+      } else if (isActiveStandard) {
+        const hasStandardKey =
+          !!process.env[DASHSCOPE_STANDARD_API_KEY_ENV_KEY] ||
+          !!mergedSettings.env?.[DASHSCOPE_STANDARD_API_KEY_ENV_KEY];
 
-        if (codingPlanVersion) {
+        if (hasStandardKey) {
           writeStdoutLine(
-            t('  Config Version: {{version}}', {
-              version: codingPlanVersion.substring(0, 8) + '...',
-            }),
+            t(
+              '✓ Authentication Method: Alibaba Cloud ModelStudio Standard API Key',
+            ),
           );
+
+          if (modelName) {
+            writeStdoutLine(
+              t('  Current Model: {{model}}', { model: modelName }),
+            );
+          }
+
+          writeStdoutLine(t('  Status: API key configured\n'));
+        } else {
+          writeStdoutLine(
+            t(
+              '⚠️  Authentication Method: Alibaba Cloud ModelStudio Standard API Key (Incomplete)',
+            ),
+          );
+          writeStdoutLine(
+            t('  Issue: API key not found in environment or settings\n'),
+          );
+          writeStdoutLine(t('  Run `qwen auth api-key` to re-configure.\n'));
+        }
+      } else if (activeConfig) {
+        let hasApiKey: boolean;
+        if (activeConfig.envKey) {
+          hasApiKey =
+            !!process.env[activeConfig.envKey] ||
+            !!mergedSettings.env?.[activeConfig.envKey];
+        } else {
+          hasApiKey =
+            !!process.env['OPENAI_API_KEY'] ||
+            !!mergedSettings.env?.['OPENAI_API_KEY'] ||
+            !!mergedSettings.security?.auth?.apiKey;
         }
 
-        writeStdoutLine(t('  Status: API key configured\n'));
+        if (hasApiKey) {
+          writeStdoutLine(
+            t('✓ Authentication Method: OpenAI-compatible Provider'),
+          );
+
+          if (modelName) {
+            writeStdoutLine(
+              t('  Current Model: {{model}}', { model: modelName }),
+            );
+          }
+
+          const baseUrl =
+            activeConfig.baseUrl || mergedSettings.security?.auth?.baseUrl;
+          if (baseUrl) {
+            writeStdoutLine(t('  Base URL: {{baseUrl}}', { baseUrl }));
+          }
+
+          writeStdoutLine(t('  Status: API key configured\n'));
+        } else {
+          writeStdoutLine(
+            t(
+              '⚠️  Authentication Method: OpenAI-compatible Provider (Incomplete)',
+            ),
+          );
+          writeStdoutLine(
+            t('  Issue: API key not found in environment or settings\n'),
+          );
+          writeStdoutLine(t('  Run `qwen auth` to re-configure.\n'));
+        }
       } else {
-        writeStdoutLine(
-          t(
-            '⚠️  Authentication Method: Alibaba Cloud Coding Plan (Incomplete)',
-          ),
-        );
-        writeStdoutLine(
-          t('  Issue: API key not found in environment or settings\n'),
-        );
-        writeStdoutLine(t('  Run `qwen auth coding-plan` to re-configure.\n'));
+        const hasCodingPlanKey =
+          !!process.env[CODING_PLAN_ENV_KEY] ||
+          !!mergedSettings.env?.[CODING_PLAN_ENV_KEY];
+        const hasGenericApiKey =
+          !!process.env['OPENAI_API_KEY'] ||
+          !!mergedSettings.env?.['OPENAI_API_KEY'] ||
+          !!mergedSettings.security?.auth?.apiKey;
+        const hasCodingPlanMetadata =
+          !modelName && (!!codingPlanRegion || !!codingPlanVersion);
+
+        if (hasGenericApiKey) {
+          writeStdoutLine(
+            t('✓ Authentication Method: OpenAI-compatible Provider'),
+          );
+
+          if (modelName) {
+            writeStdoutLine(
+              t('  Current Model: {{model}}', { model: modelName }),
+            );
+          }
+
+          const baseUrl = mergedSettings.security?.auth?.baseUrl;
+          if (baseUrl) {
+            writeStdoutLine(t('  Base URL: {{baseUrl}}', { baseUrl }));
+          }
+
+          writeStdoutLine(t('  Status: API key configured\n'));
+        } else if (hasCodingPlanKey) {
+          writeStdoutLine(
+            t('✓ Authentication Method: Alibaba Cloud Coding Plan'),
+          );
+
+          if (codingPlanRegion) {
+            const regionDisplay =
+              codingPlanRegion === CodingPlanRegion.CHINA
+                ? t('中国 (China) - 阿里云百炼')
+                : t('Global - Alibaba Cloud');
+            writeStdoutLine(
+              t('  Region: {{region}}', { region: regionDisplay }),
+            );
+          }
+
+          if (modelName) {
+            writeStdoutLine(
+              t('  Current Model: {{model}}', { model: modelName }),
+            );
+          }
+
+          if (codingPlanVersion) {
+            writeStdoutLine(
+              t('  Config Version: {{version}}', {
+                version: codingPlanVersion.substring(0, 8) + '...',
+              }),
+            );
+          }
+
+          writeStdoutLine(t('  Status: API key configured\n'));
+        } else if (hasCodingPlanMetadata) {
+          writeStdoutLine(
+            t(
+              '⚠️  Authentication Method: Alibaba Cloud Coding Plan (Incomplete)',
+            ),
+          );
+          writeStdoutLine(
+            t('  Issue: API key not found in environment or settings\n'),
+          );
+          writeStdoutLine(
+            t('  Run `qwen auth coding-plan` to re-configure.\n'),
+          );
+        } else {
+          writeStdoutLine(
+            t(
+              '⚠️  Authentication Method: OpenAI-compatible Provider (Incomplete)',
+            ),
+          );
+          writeStdoutLine(
+            t('  Issue: API key not found in environment or settings\n'),
+          );
+          writeStdoutLine(t('  Run `qwen auth` to re-configure.\n'));
+        }
       }
     } else {
       writeStdoutLine(
diff --git a/packages/cli/src/commands/auth/openrouter.test.ts b/packages/cli/src/commands/auth/openrouter.test.ts
new file mode 100644
index 000000000..d4aedf05f
--- /dev/null
+++ b/packages/cli/src/commands/auth/openrouter.test.ts
@@ -0,0 +1,304 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { handleQwenAuth } from './handler.js';
+import { AuthType } from '@qwen-code/qwen-code-core';
+import type { LoadedSettings } from '../../config/settings.js';
+
+const {
+  mockRefreshAuth,
+  mockSetValue,
+  mockForScope,
+  mockBackupSettingsFile,
+  mockLoadCliConfig,
+} = vi.hoisted(() => {
+  const mockRefreshAuth = vi.fn();
+  return {
+    mockRefreshAuth,
+    mockSetValue: vi.fn(),
+    mockForScope: vi.fn(() => ({ path: '/user.json' })),
+    mockBackupSettingsFile: vi.fn(),
+    mockLoadCliConfig: vi.fn(async () => ({
+      refreshAuth: mockRefreshAuth,
+    })),
+  };
+});
+
+vi.mock('../../config/settings.js', () => ({
+  loadSettings: vi.fn(),
+}));
+
+vi.mock('../../config/config.js', () => ({
+  loadCliConfig: mockLoadCliConfig,
+}));
+
+vi.mock('../../utils/settingsUtils.js', () => ({
+  backupSettingsFile: mockBackupSettingsFile,
+}));
+
+vi.mock('../../config/modelProvidersScope.js', () => ({
+  getPersistScopeForModelSelection: vi.fn(() => 'user'),
+}));
+
+vi.mock('../../utils/stdioHelpers.js', () => ({
+  writeStdoutLine: vi.fn(),
+  writeStderrLine: vi.fn(),
+}));
+
+vi.mock('./openrouterOAuth.js', () => ({
+  OPENROUTER_ENV_KEY: 'OPENROUTER_API_KEY',
+  OPENROUTER_OAUTH_CALLBACK_URL: 'http://localhost:3000/openrouter/callback',
+  createOpenRouterOAuthSession: vi.fn(() => ({
+    callbackUrl: 'http://localhost:3000/openrouter/callback',
+    codeVerifier: 'test-verifier',
+    authorizationUrl: 'https://openrouter.ai/auth?manual=1',
+  })),
+  applyOpenRouterModelsConfiguration: vi.fn(async ({ settings, apiKey }) => {
+    process.env['OPENROUTER_API_KEY'] = apiKey;
+    settings.setValue('user', 'env.OPENROUTER_API_KEY', apiKey);
+    settings.setValue(
+      'user',
+      'security.auth.selectedType',
+      AuthType.USE_OPENAI,
+    );
+    settings.setValue('user', 'model.name', 'openai/gpt-4o-mini:free');
+    settings.setValue('user', `modelProviders.${AuthType.USE_OPENAI}`, [
+      {
+        id: 'openai/gpt-4o-mini:free',
+        name: 'OpenRouter · GPT-4o mini',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'anthropic/claude-3.7-sonnet',
+        name: 'OpenRouter · Claude 3.7 Sonnet',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'gpt-4.1',
+        name: 'OpenAI GPT-4.1',
+        baseUrl: 'https://api.openai.com/v1',
+        envKey: 'OPENAI_API_KEY',
+      },
+    ]);
+    return {
+      updatedConfigs: [
+        {
+          id: 'openai/gpt-4o-mini:free',
+          name: 'OpenRouter · GPT-4o mini',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'anthropic/claude-3.7-sonnet',
+          name: 'OpenRouter · Claude 3.7 Sonnet',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'gpt-4.1',
+          name: 'OpenAI GPT-4.1',
+          baseUrl: 'https://api.openai.com/v1',
+          envKey: 'OPENAI_API_KEY',
+        },
+      ],
+      activeModelId: 'openai/gpt-4o-mini:free',
+      persistScope: 'user',
+    };
+  }),
+  runOpenRouterOAuthLogin: vi.fn(),
+}));
+
+import { loadSettings } from '../../config/settings.js';
+import {
+  applyOpenRouterModelsConfiguration,
+  runOpenRouterOAuthLogin,
+} from './openrouterOAuth.js';
+
+describe('handleQwenAuth openrouter', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
+    delete process.env['OPENROUTER_API_KEY'];
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env['OPENROUTER_API_KEY'];
+  });
+
+  const createMockSettings = (
+    merged: Record<string, unknown>,
+  ): LoadedSettings =>
+    ({
+      merged,
+      system: { settings: {}, path: '/system.json' },
+      systemDefaults: { settings: {}, path: '/system-defaults.json' },
+      user: { settings: {}, path: '/user.json' },
+      workspace: { settings: {}, path: '/workspace.json' },
+      forScope: mockForScope,
+      setValue: mockSetValue,
+      getUserHooks: vi.fn(() => []),
+      getProjectHooks: vi.fn(() => []),
+      isTrusted: true,
+    }) as unknown as LoadedSettings;
+
+  it('stores OpenRouter key and model provider config', async () => {
+    vi.mocked(loadSettings).mockReturnValue(
+      createMockSettings({
+        modelProviders: {
+          [AuthType.USE_OPENAI]: [
+            {
+              id: 'gpt-4.1',
+              name: 'OpenAI GPT-4.1',
+              baseUrl: 'https://api.openai.com/v1',
+              envKey: 'OPENAI_API_KEY',
+            },
+          ],
+        },
+      }),
+    );
+
+    await handleQwenAuth('openrouter', { key: 'or-key-123' });
+
+    expect(mockBackupSettingsFile).toHaveBeenCalledWith('/user.json');
+    expect(mockSetValue).toHaveBeenCalledWith(
+      'user',
+      'env.OPENROUTER_API_KEY',
+      'or-key-123',
+    );
+    expect(mockSetValue).toHaveBeenCalledWith(
+      'user',
+      'security.auth.selectedType',
+      AuthType.USE_OPENAI,
+    );
+    expect(mockSetValue).toHaveBeenCalledWith(
+      'user',
+      'model.name',
+      'openai/gpt-4o-mini:free',
+    );
+
+    const modelProvidersCall = mockSetValue.mock.calls.find(
+      (call) => call[1] === `modelProviders.${AuthType.USE_OPENAI}`,
+    );
+    expect(modelProvidersCall).toBeDefined();
+    expect(modelProvidersCall?.[2]).toEqual([
+      {
+        id: 'openai/gpt-4o-mini:free',
+        name: 'OpenRouter · GPT-4o mini',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'anthropic/claude-3.7-sonnet',
+        name: 'OpenRouter · Claude 3.7 Sonnet',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'gpt-4.1',
+        name: 'OpenAI GPT-4.1',
+        baseUrl: 'https://api.openai.com/v1',
+        envKey: 'OPENAI_API_KEY',
+      },
+    ]);
+    expect(applyOpenRouterModelsConfiguration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        settings: expect.anything(),
+        config: expect.anything(),
+        apiKey: 'or-key-123',
+        reloadConfig: true,
+      }),
+    );
+    expect(mockRefreshAuth).toHaveBeenCalledWith(AuthType.USE_OPENAI);
+    expect(process.env['OPENROUTER_API_KEY']).toBe('or-key-123');
+  });
+
+  it('replaces existing OpenRouter configs instead of duplicating them', async () => {
+    vi.mocked(loadSettings).mockReturnValue(
+      createMockSettings({
+        modelProviders: {
+          [AuthType.USE_OPENAI]: [
+            {
+              id: 'old/model',
+              name: 'Old OpenRouter Model',
+              baseUrl: 'https://openrouter.ai/api/v1',
+              envKey: 'OPENROUTER_API_KEY',
+            },
+            {
+              id: 'gpt-4.1',
+              name: 'OpenAI GPT-4.1',
+              baseUrl: 'https://api.openai.com/v1',
+              envKey: 'OPENAI_API_KEY',
+            },
+          ],
+        },
+      }),
+    );
+
+    await handleQwenAuth('openrouter', { key: 'or-key-456' });
+
+    const modelProvidersCall = mockSetValue.mock.calls.find(
+      (call) => call[1] === `modelProviders.${AuthType.USE_OPENAI}`,
+    );
+    expect(modelProvidersCall?.[2]).toEqual([
+      {
+        id: 'openai/gpt-4o-mini:free',
+        name: 'OpenRouter · GPT-4o mini',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'anthropic/claude-3.7-sonnet',
+        name: 'OpenRouter · Claude 3.7 Sonnet',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'gpt-4.1',
+        name: 'OpenAI GPT-4.1',
+        baseUrl: 'https://api.openai.com/v1',
+        envKey: 'OPENAI_API_KEY',
+      },
+    ]);
+  });
+
+  it('uses OAuth flow when key is not provided', async () => {
+    vi.mocked(loadSettings).mockReturnValue(createMockSettings({}));
+    vi.mocked(runOpenRouterOAuthLogin).mockResolvedValue({
+      apiKey: 'oauth-key-123',
+      userId: 'user-1',
+      authorizationUrl: 'https://openrouter.ai/auth?manual=1',
+    });
+
+    await handleQwenAuth('openrouter', {});
+
+    expect(runOpenRouterOAuthLogin).toHaveBeenCalledTimes(1);
+    expect(mockSetValue).toHaveBeenCalledWith(
+      'user',
+      'env.OPENROUTER_API_KEY',
+      'oauth-key-123',
+    );
+    expect(process.env['OPENROUTER_API_KEY']).toBe('oauth-key-123');
+  });
+
+  it('delegates OpenRouter provider updates to the shared configuration helper', async () => {
+    vi.mocked(loadSettings).mockReturnValue(createMockSettings({}));
+
+    await handleQwenAuth('openrouter', { key: 'or-key-dynamic' });
+
+    expect(applyOpenRouterModelsConfiguration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        settings: expect.anything(),
+        config: expect.anything(),
+        apiKey: 'or-key-dynamic',
+        reloadConfig: true,
+      }),
+    );
+  });
+});
diff --git a/packages/cli/src/commands/auth/openrouterOAuth.test.ts b/packages/cli/src/commands/auth/openrouterOAuth.test.ts
new file mode 100644
index 000000000..81fe89d77
--- /dev/null
+++ b/packages/cli/src/commands/auth/openrouterOAuth.test.ts
@@ -0,0 +1,730 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthType, type Config } from '@qwen-code/qwen-code-core';
+import type { LoadedSettings } from '../../config/settings.js';
+import {
+  buildOpenRouterAuthorizationUrl,
+  createOpenRouterOAuthSession,
+  createOAuthState,
+  createPkcePair,
+  exchangeAuthCodeForApiKey,
+  fetchOpenRouterModels,
+  getOpenRouterModelsWithFallback,
+  getPreferredOpenRouterModelId,
+  mergeOpenRouterConfigs,
+  OPENROUTER_DEFAULT_MODELS,
+  OPENROUTER_MODELS_URL,
+  OPENROUTER_OAUTH_AUTHORIZE_URL,
+  OPENROUTER_OAUTH_EXCHANGE_URL,
+  runOpenRouterOAuthLogin,
+  selectRecommendedOpenRouterModels,
+  startOAuthCallbackListener,
+  applyOpenRouterModelsConfiguration,
+} from './openrouterOAuth.js';
+import { request } from 'node:http';
+
+describe('openrouterOAuth', () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('creates a valid PKCE pair', () => {
+    const pkce = createPkcePair();
+
+    expect(pkce.codeVerifier).toMatch(/^[A-Za-z0-9\-_]+$/);
+    expect(pkce.codeChallenge).toMatch(/^[A-Za-z0-9\-_]+$/);
+    expect(pkce.codeVerifier.length).toBeGreaterThan(20);
+    expect(pkce.codeChallenge.length).toBeGreaterThan(20);
+  });
+
+  it('builds OpenRouter authorization URL with required params', () => {
+    const url = buildOpenRouterAuthorizationUrl({
+      callbackUrl: 'http://localhost:3000/openrouter/callback',
+      codeChallenge: 'challenge123',
+      state: 'state-123',
+      codeChallengeMethod: 'S256',
+      limit: 100,
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.origin + parsed.pathname).toBe(
+      OPENROUTER_OAUTH_AUTHORIZE_URL,
+    );
+    expect(parsed.searchParams.get('callback_url')).toBe(
+      'http://localhost:3000/openrouter/callback',
+    );
+    expect(parsed.searchParams.get('code_challenge')).toBe('challenge123');
+    expect(parsed.searchParams.get('state')).toBe('state-123');
+    expect(parsed.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(parsed.searchParams.get('limit')).toBe('100');
+  });
+
+  it('creates a random OAuth state token', () => {
+    const state = createOAuthState();
+
+    expect(state).toMatch(/^[A-Za-z0-9\-_]+$/);
+    expect(state.length).toBeGreaterThan(20);
+  });
+
+  it('exchanges auth code for API key', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        key: 'or-key-123',
+        user_id: 'user-1',
+      }),
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await exchangeAuthCodeForApiKey({
+      code: 'auth-code-123',
+      codeVerifier: 'verifier-123',
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      OPENROUTER_OAUTH_EXCHANGE_URL,
+      expect.objectContaining({
+        method: 'POST',
+        headers: expect.objectContaining({
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        }),
+      }),
+    );
+    expect(result).toEqual({
+      apiKey: 'or-key-123',
+      userId: 'user-1',
+    });
+    expect(typeof result.apiKey).toBe('string');
+  });
+
+  it('throws when exchange response does not contain key', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({
+        ok: true,
+        json: async () => ({}),
+      })),
+    );
+
+    await expect(
+      exchangeAuthCodeForApiKey({
+        code: 'auth-code-123',
+        codeVerifier: 'verifier-123',
+      }),
+    ).rejects.toThrow('no key was returned');
+  });
+
+  it('resolves callback code without waiting for server close completion', async () => {
+    const listener = startOAuthCallbackListener(
+      'http://localhost:3100/openrouter/callback',
+      5000,
+      'state-123',
+    );
+    await listener.ready;
+
+    const codePromise = listener.waitForCode;
+    await new Promise<void>((resolve, reject) => {
+      const req = request(
+        'http://localhost:3100/openrouter/callback?code=fast-code-123&state=state-123',
+        (res) => {
+          res.resume();
+          res.on('end', resolve);
+        },
+      );
+      req.on('error', reject);
+      req.end();
+    });
+
+    await expect(codePromise).resolves.toBe('fast-code-123');
+  });
+
+  it('rejects callback codes with mismatched OAuth state', async () => {
+    const listener = startOAuthCallbackListener(
+      'http://localhost:3101/openrouter/callback',
+      5000,
+      'expected-state',
+    );
+    await listener.ready;
+
+    const codePromise = listener.waitForCode.catch((error: unknown) => error);
+    await new Promise<void>((resolve, reject) => {
+      const req = request(
+        'http://localhost:3101/openrouter/callback?code=fast-code-123&state=wrong-state',
+        (res) => {
+          expect(res.statusCode).toBe(400);
+          res.resume();
+          res.on('end', resolve);
+        },
+      );
+      req.on('error', reject);
+      req.end();
+    });
+
+    await expect(codePromise).resolves.toEqual(
+      expect.objectContaining({
+        message: expect.stringContaining('Invalid OAuth state'),
+      }),
+    );
+  }, 15_000);
+
+  it('creates a reusable OAuth session for manual fallback links', () => {
+    const session = createOpenRouterOAuthSession(
+      'http://localhost:3000/openrouter/callback',
+      {
+        codeVerifier: 'verifier-123',
+        codeChallenge: 'challenge-123',
+      },
+      'state-123',
+    );
+
+    expect(session).toEqual({
+      callbackUrl: 'http://localhost:3000/openrouter/callback',
+      codeVerifier: 'verifier-123',
+      state: 'state-123',
+      authorizationUrl: expect.stringContaining('code_challenge=challenge-123'),
+    });
+    expect(session.authorizationUrl).toContain('state=state-123');
+  });
+
+  it('returns OAuth result without waiting for slow listener close', async () => {
+    let resolveClose!: () => void;
+    const listener = {
+      ready: Promise.resolve(),
+      waitForCode: Promise.resolve('auth-code-123'),
+      close: vi.fn(
+        () =>
+          new Promise<void>((resolve) => {
+            resolveClose = resolve;
+          }),
+      ),
+    };
+    const openBrowser = vi.fn(async () => ({}) as never);
+    const exchangeApiKey = vi.fn(async () => ({
+      apiKey: 'or-key-123',
+      userId: 'user-1',
+    }));
+    const resultPromise = runOpenRouterOAuthLogin(
+      'http://localhost:3000/openrouter/callback',
+      {
+        openBrowser,
+        startListener: vi.fn(() => listener),
+        exchangeApiKey,
+        now: () => 1000,
+      },
+    );
+
+    await expect(resultPromise).resolves.toMatchObject({
+      apiKey: 'or-key-123',
+      userId: 'user-1',
+      authorizationUrl: expect.stringContaining('https://openrouter.ai/auth'),
+    });
+    expect(listener.close).toHaveBeenCalled();
+    resolveClose();
+  });
+
+  it('passes the session state to the OAuth callback listener', async () => {
+    const listener = {
+      ready: Promise.resolve(),
+      waitForCode: Promise.resolve('auth-code-123'),
+      close: vi.fn(async () => undefined),
+    };
+    const openBrowser = vi.fn(async () => ({}) as never);
+    const startListener = vi.fn(() => listener);
+    const exchangeApiKey = vi.fn(async () => ({
+      apiKey: 'or-key-123',
+      userId: 'user-1',
+    }));
+
+    await runOpenRouterOAuthLogin('http://localhost:3000/openrouter/callback', {
+      openBrowser,
+      startListener,
+      exchangeApiKey,
+      session: {
+        callbackUrl: 'http://localhost:3000/openrouter/callback',
+        codeVerifier: 'verifier-123',
+        state: 'state-123',
+        authorizationUrl: 'https://openrouter.ai/auth?state=state-123',
+      },
+    });
+
+    expect(startListener).toHaveBeenCalledWith(
+      'http://localhost:3000/openrouter/callback',
+      expect.any(Number),
+      'state-123',
+    );
+  });
+
+  it('records wait and exchange timings during OAuth login', async () => {
+    const listener = {
+      ready: Promise.resolve(),
+      waitForCode: Promise.resolve('auth-code-123'),
+      close: vi.fn(async () => undefined),
+    };
+    const openBrowser = vi.fn(async () => ({}) as never);
+    const exchangeApiKey = vi.fn(async () => ({
+      apiKey: 'or-key-123',
+      userId: 'user-1',
+    }));
+    const now = vi
+      .fn<() => number>()
+      .mockReturnValueOnce(1000)
+      .mockReturnValueOnce(2200)
+      .mockReturnValueOnce(3000)
+      .mockReturnValueOnce(3450);
+
+    const result = await runOpenRouterOAuthLogin(
+      'http://localhost:3000/openrouter/callback',
+      {
+        openBrowser,
+        startListener: () => listener,
+        exchangeApiKey,
+        now,
+      },
+    );
+
+    expect(openBrowser).toHaveBeenCalledWith(
+      expect.stringContaining('https://openrouter.ai/auth'),
+    );
+    expect(exchangeApiKey).toHaveBeenCalledWith({
+      code: 'auth-code-123',
+      codeVerifier: expect.any(String),
+    });
+    expect(result).toEqual({
+      apiKey: 'or-key-123',
+      userId: 'user-1',
+      authorizationUrl: expect.stringContaining('https://openrouter.ai/auth'),
+      authorizationCodeWaitMs: 1200,
+      apiKeyExchangeMs: 450,
+    });
+    expect(listener.close).toHaveBeenCalled();
+  });
+
+  it('allows cancelling OAuth wait with process signals after opening the browser', async () => {
+    let sigintHandler: ((signal: NodeJS.Signals) => void) | undefined;
+    let sigtermHandler: ((signal: NodeJS.Signals) => void) | undefined;
+    const signalTarget = {
+      once: vi.fn(
+        (
+          event: 'SIGINT' | 'SIGTERM',
+          handler: (signal: NodeJS.Signals) => void,
+        ) => {
+          if (event === 'SIGINT') {
+            sigintHandler = handler;
+          } else {
+            sigtermHandler = handler;
+          }
+        },
+      ),
+      removeListener: vi.fn(
+        (
+          _event: 'SIGINT' | 'SIGTERM',
+          _handler: (signal: NodeJS.Signals) => void,
+        ) => undefined,
+      ),
+    };
+    const listener = {
+      ready: Promise.resolve(),
+      waitForCode: new Promise<string>(() => undefined),
+      close: vi.fn(async () => undefined),
+    };
+    const openBrowser = vi.fn(async () => ({}) as never);
+    const exchangeApiKey = vi.fn();
+
+    const resultPromise = runOpenRouterOAuthLogin(
+      'http://localhost:3000/openrouter/callback',
+      {
+        openBrowser,
+        startListener: () => listener,
+        exchangeApiKey,
+        signalTarget,
+      },
+    );
+
+    await vi.waitFor(() => {
+      expect(openBrowser).toHaveBeenCalledTimes(1);
+      expect(sigintHandler).toBeTypeOf('function');
+      expect(sigtermHandler).toBeTypeOf('function');
+    });
+
+    sigintHandler?.('SIGINT');
+
+    await expect(resultPromise).rejects.toThrow(
+      'OpenRouter OAuth cancelled by user (SIGINT) while waiting for browser authorization.',
+    );
+    expect(exchangeApiKey).not.toHaveBeenCalled();
+    expect(listener.close).toHaveBeenCalled();
+    expect(signalTarget.removeListener).toHaveBeenCalledWith(
+      'SIGINT',
+      sigintHandler,
+    );
+    expect(signalTarget.removeListener).toHaveBeenCalledWith(
+      'SIGTERM',
+      sigtermHandler,
+    );
+  });
+
+  it('allows cancelling OAuth wait with an abort signal', async () => {
+    const abortController = new AbortController();
+    const listener = {
+      ready: Promise.resolve(),
+      waitForCode: new Promise<string>(() => undefined),
+      close: vi.fn(async () => undefined),
+    };
+    const openBrowser = vi.fn(async () => ({}) as never);
+    const exchangeApiKey = vi.fn();
+
+    const resultPromise = runOpenRouterOAuthLogin(
+      'http://localhost:3000/openrouter/callback',
+      {
+        openBrowser,
+        startListener: () => listener,
+        exchangeApiKey,
+        abortSignal: abortController.signal,
+      },
+    );
+
+    await vi.waitFor(() => {
+      expect(openBrowser).toHaveBeenCalledTimes(1);
+    });
+
+    abortController.abort();
+
+    await expect(resultPromise).rejects.toMatchObject({
+      name: 'AbortError',
+      message: 'OpenRouter OAuth cancelled.',
+    });
+    expect(exchangeApiKey).not.toHaveBeenCalled();
+    expect(listener.close).toHaveBeenCalled();
+  });
+
+  it('fetches dynamic OpenRouter text models with free-first ordering', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        data: [
+          {
+            id: 'openai/gpt-5-mini',
+            name: 'GPT-5 Mini',
+            context_length: 128000,
+            architecture: {
+              input_modalities: ['text', 'image'],
+              output_modalities: ['text'],
+            },
+            pricing: {
+              prompt: '0.000001',
+              completion: '0.000003',
+            },
+          },
+          {
+            id: 'minimax/minimax-m1',
+            name: 'MiniMax M1',
+            architecture: {
+              input_modalities: ['text'],
+              output_modalities: ['text'],
+            },
+            pricing: {
+              prompt: '0',
+              completion: '0',
+            },
+          },
+          {
+            id: 'qwen/qwen3-coder:free',
+            name: 'Qwen3 Coder',
+            architecture: {
+              input_modalities: ['text'],
+              output_modalities: ['text'],
+            },
+            pricing: {
+              prompt: '0',
+              completion: '0',
+            },
+          },
+          {
+            id: 'zhipu/glm-4.5',
+            name: 'GLM 4.5',
+            architecture: {
+              input_modalities: ['text'],
+              output_modalities: ['text'],
+            },
+            pricing: {
+              prompt: '0.000002',
+              completion: '0.000004',
+            },
+          },
+          {
+            id: 'black-forest-labs/flux',
+            name: 'Flux',
+            architecture: {
+              input_modalities: ['text'],
+              output_modalities: ['image'],
+            },
+          },
+        ],
+      }),
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const models = await fetchOpenRouterModels();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      OPENROUTER_MODELS_URL,
+      expect.objectContaining({ method: 'GET' }),
+    );
+    expect(models).toEqual([
+      {
+        id: 'qwen/qwen3-coder:free',
+        name: 'OpenRouter · Qwen3 Coder',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'minimax/minimax-m1',
+        name: 'OpenRouter · MiniMax M1',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'openai/gpt-5-mini',
+        name: 'OpenRouter · GPT-5 Mini',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+        capabilities: { vision: true },
+        generationConfig: { contextWindowSize: 128000 },
+      },
+      {
+        id: 'zhipu/glm-4.5',
+        name: 'OpenRouter · GLM 4.5',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+    ]);
+  });
+
+  it('selects a recommended OpenRouter subset instead of returning the full catalog', () => {
+    const recommended = selectRecommendedOpenRouterModels(
+      [
+        {
+          id: 'qwen/qwen3-coder:free',
+          name: 'OpenRouter · Qwen3 Coder',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'qwen/qwen3-max',
+          name: 'OpenRouter · Qwen3 Max',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'glm/glm-4.5-air:free',
+          name: 'OpenRouter · GLM 4.5 Air',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'minimax/minimax-m1',
+          name: 'OpenRouter · MiniMax M1',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'anthropic/claude-3.7-sonnet',
+          name: 'OpenRouter · Claude 3.7 Sonnet',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'google/gemini-2.5-flash',
+          name: 'OpenRouter · Gemini 2.5 Flash',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'openai/gpt-5-mini',
+          name: 'OpenRouter · GPT-5 Mini',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+          capabilities: { vision: true },
+        },
+        {
+          id: 'deepseek/deepseek-r1',
+          name: 'OpenRouter · DeepSeek R1',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+          generationConfig: { contextWindowSize: 1048576 },
+        },
+        {
+          id: 'meta/llama-3.3-70b',
+          name: 'OpenRouter · Llama 3.3 70B',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+      ],
+      6,
+    );
+
+    expect(recommended.map((model) => model.id)).toEqual([
+      'qwen/qwen3-coder:free',
+      'glm/glm-4.5-air:free',
+      'qwen/qwen3-max',
+      'minimax/minimax-m1',
+      'anthropic/claude-3.7-sonnet',
+      'google/gemini-2.5-flash',
+    ]);
+  });
+
+  it('applies OpenRouter configuration to settings and reloads providers', async () => {
+    const settings = {
+      merged: {
+        modelProviders: {
+          [AuthType.USE_OPENAI]: [
+            { id: 'custom/model', baseUrl: 'https://example.com/v1' },
+          ],
+        },
+      },
+      user: { settings: { modelProviders: {} }, path: '/user.json' },
+      workspace: { settings: {}, path: '/workspace.json' },
+      system: { settings: {}, path: '/system.json' },
+      systemDefaults: { settings: {}, path: '/system-defaults.json' },
+      setValue: vi.fn(),
+      forScope: vi.fn(),
+    } as unknown as LoadedSettings;
+    const config = {
+      reloadModelProvidersConfig: vi.fn(),
+    } as unknown as Config;
+    const fetchSpy = vi
+      .spyOn(
+        await import('./openrouterOAuth.js'),
+        'getOpenRouterModelsWithFallback',
+      )
+      .mockResolvedValue([
+        {
+          id: 'openai/gpt-4o-mini',
+          name: 'OpenRouter · GPT-4o mini',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+      ]);
+
+    const result = await applyOpenRouterModelsConfiguration({
+      settings,
+      config,
+      apiKey: 'or-key-123',
+      reloadConfig: true,
+    });
+
+    expect(settings.setValue).toHaveBeenCalledWith(
+      expect.anything(),
+      'env.OPENROUTER_API_KEY',
+      'or-key-123',
+    );
+
+    const modelProvidersCall = vi
+      .mocked(settings.setValue)
+      .mock.calls.find(
+        (call) => call[1] === `modelProviders.${AuthType.USE_OPENAI}`,
+      );
+    expect(modelProvidersCall).toBeDefined();
+    expect(modelProvidersCall?.[2]).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        }),
+        expect.objectContaining({
+          id: 'custom/model',
+          baseUrl: 'https://example.com/v1',
+        }),
+      ]),
+    );
+
+    expect(config.reloadModelProvidersConfig).toHaveBeenCalled();
+    expect(result.activeModelId).toBeDefined();
+    fetchSpy.mockRestore();
+  });
+
+  it('prefers the default OpenRouter model when it remains enabled', () => {
+    expect(
+      getPreferredOpenRouterModelId([
+        { id: 'anthropic/claude-3.7-sonnet' },
+        { id: 'openai/gpt-4o-mini' },
+      ] as never),
+    ).toBe('openai/gpt-4o-mini');
+  });
+
+  it('falls back to the first enabled OpenRouter model when the default is unavailable', () => {
+    expect(
+      getPreferredOpenRouterModelId([
+        { id: 'anthropic/claude-3.7-sonnet' },
+      ] as never),
+    ).toBe('anthropic/claude-3.7-sonnet');
+  });
+
+  it('falls back to default models when dynamic fetch fails', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({
+        ok: false,
+        status: 500,
+        text: async () => 'server error',
+      })),
+    );
+
+    await expect(getOpenRouterModelsWithFallback()).resolves.toEqual(
+      OPENROUTER_DEFAULT_MODELS,
+    );
+  });
+
+  it('replaces only existing OpenRouter configs when merging dynamic models', () => {
+    const merged = mergeOpenRouterConfigs(
+      [
+        {
+          id: 'old/model',
+          name: 'Old OpenRouter Model',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+        {
+          id: 'gpt-4.1',
+          name: 'OpenAI GPT-4.1',
+          baseUrl: 'https://api.openai.com/v1',
+          envKey: 'OPENAI_API_KEY',
+        },
+      ],
+      [
+        {
+          id: 'openai/gpt-5-mini',
+          name: 'OpenRouter · GPT-5 Mini',
+          baseUrl: 'https://openrouter.ai/api/v1',
+          envKey: 'OPENROUTER_API_KEY',
+        },
+      ],
+    );
+
+    expect(merged).toEqual([
+      {
+        id: 'openai/gpt-5-mini',
+        name: 'OpenRouter · GPT-5 Mini',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+      {
+        id: 'gpt-4.1',
+        name: 'OpenAI GPT-4.1',
+        baseUrl: 'https://api.openai.com/v1',
+        envKey: 'OPENAI_API_KEY',
+      },
+    ]);
+  });
+});
diff --git a/packages/cli/src/commands/auth/openrouterOAuth.ts b/packages/cli/src/commands/auth/openrouterOAuth.ts
new file mode 100644
index 000000000..5d36da75b
--- /dev/null
+++ b/packages/cli/src/commands/auth/openrouterOAuth.ts
@@ -0,0 +1,751 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { createServer, type Server } from 'node:http';
+import { createHash, randomBytes } from 'node:crypto';
+import open from 'open';
+
+import {
+  AuthType,
+  type Config,
+  type ModelProvidersConfig,
+  type ProviderModelConfig as ModelConfig,
+} from '@qwen-code/qwen-code-core';
+import type { LoadedSettings } from '../../config/settings.js';
+import { getPersistScopeForModelSelection } from '../../config/modelProvidersScope.js';
+
+export const OPENROUTER_ENV_KEY = 'OPENROUTER_API_KEY';
+export const OPENROUTER_DEFAULT_MODEL = 'openai/gpt-4o-mini';
+export const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+export const OPENROUTER_OAUTH_AUTHORIZE_URL = 'https://openrouter.ai/auth';
+export const OPENROUTER_OAUTH_EXCHANGE_URL =
+  'https://openrouter.ai/api/v1/auth/keys';
+export const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
+export const OPENROUTER_OAUTH_CALLBACK_URL =
+  'http://localhost:3000/openrouter/callback';
+const OPENROUTER_CODE_CHALLENGE_METHOD = 'S256';
+const OPENROUTER_OAUTH_TIMEOUT_MS = 5 * 60 * 1000;
+const OPENROUTER_MINIMUM_TEXT_MODELS = 1;
+
+export const OPENROUTER_DEFAULT_MODELS: ModelConfig[] = [
+  {
+    id: 'openai/gpt-4o-mini',
+    name: 'OpenRouter · GPT-4o mini',
+    baseUrl: OPENROUTER_BASE_URL,
+    envKey: OPENROUTER_ENV_KEY,
+  },
+  {
+    id: 'anthropic/claude-3.7-sonnet',
+    name: 'OpenRouter · Claude 3.7 Sonnet',
+    baseUrl: OPENROUTER_BASE_URL,
+    envKey: OPENROUTER_ENV_KEY,
+  },
+  {
+    id: 'google/gemini-2.5-flash',
+    name: 'OpenRouter · Gemini 2.5 Flash',
+    baseUrl: OPENROUTER_BASE_URL,
+    envKey: OPENROUTER_ENV_KEY,
+  },
+];
+
+export interface OpenRouterOAuthResult {
+  apiKey: string;
+  userId?: string;
+  authorizationUrl?: string;
+  authorizationCodeWaitMs?: number;
+  apiKeyExchangeMs?: number;
+}
+
+export interface PkcePair {
+  codeVerifier: string;
+  codeChallenge: string;
+}
+
+export interface OpenRouterOAuthSession {
+  callbackUrl: string;
+  codeVerifier: string;
+  state: string;
+  authorizationUrl: string;
+}
+
+export interface OAuthCallbackListener {
+  ready: Promise<void>;
+  waitForCode: Promise<string>;
+  close: () => Promise<void>;
+}
+
+interface OpenRouterModelApiRecord {
+  id?: string;
+  name?: string;
+  description?: string;
+  context_length?: number;
+  architecture?: {
+    input_modalities?: string[];
+    output_modalities?: string[];
+  };
+  pricing?: {
+    prompt?: string;
+    completion?: string;
+  };
+}
+
+function toBase64Url(input: Buffer): string {
+  return input
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+export function createPkcePair(): PkcePair {
+  const codeVerifier = toBase64Url(randomBytes(32));
+  const codeChallenge = toBase64Url(
+    createHash('sha256').update(codeVerifier).digest(),
+  );
+  return { codeVerifier, codeChallenge };
+}
+
+export function buildOpenRouterAuthorizationUrl(params: {
+  callbackUrl: string;
+  codeChallenge: string;
+  state: string;
+  codeChallengeMethod?: 'S256';
+  limit?: number;
+}): string {
+  const url = new URL(OPENROUTER_OAUTH_AUTHORIZE_URL);
+  url.searchParams.set('callback_url', params.callbackUrl);
+  url.searchParams.set('code_challenge', params.codeChallenge);
+  url.searchParams.set('state', params.state);
+  url.searchParams.set(
+    'code_challenge_method',
+    params.codeChallengeMethod || OPENROUTER_CODE_CHALLENGE_METHOD,
+  );
+  if (typeof params.limit === 'number') {
+    url.searchParams.set('limit', String(params.limit));
+  }
+  return url.toString();
+}
+
+export function createOAuthState(): string {
+  return toBase64Url(randomBytes(32));
+}
+
+export function createOpenRouterOAuthSession(
+  callbackUrl = OPENROUTER_OAUTH_CALLBACK_URL,
+  pkcePair = createPkcePair(),
+  state = createOAuthState(),
+): OpenRouterOAuthSession {
+  return {
+    callbackUrl,
+    codeVerifier: pkcePair.codeVerifier,
+    state,
+    authorizationUrl: buildOpenRouterAuthorizationUrl({
+      callbackUrl,
+      codeChallenge: pkcePair.codeChallenge,
+      state,
+      codeChallengeMethod: OPENROUTER_CODE_CHALLENGE_METHOD,
+    }),
+  };
+}
+
+export function startOAuthCallbackListener(
+  callbackUrl = OPENROUTER_OAUTH_CALLBACK_URL,
+  timeoutMs = OPENROUTER_OAUTH_TIMEOUT_MS,
+  expectedState?: string,
+): OAuthCallbackListener {
+  const parsedUrl = new URL(callbackUrl);
+  if (parsedUrl.protocol !== 'http:') {
+    throw new Error(
+      'Only http localhost callback URLs are currently supported.',
+    );
+  }
+
+  let server: Server | undefined;
+  let timeout: NodeJS.Timeout | undefined;
+  let settled = false;
+
+  const close = async () => {
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = undefined;
+    }
+    if (!server) {
+      return;
+    }
+    await new Promise<void>((resolve, reject) => {
+      server!.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+    server = undefined;
+  };
+
+  let resolveReady!: () => void;
+  let rejectReady!: (error: Error) => void;
+  const ready = new Promise<void>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+
+  let resolveCode!: (code: string) => void;
+  let rejectCode!: (error: Error) => void;
+  const waitForCode = new Promise<string>((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+
+  const finish = (action: 'resolve' | 'reject', payload: string | Error) => {
+    if (settled) {
+      return;
+    }
+    settled = true;
+
+    if (action === 'resolve') {
+      resolveCode(payload as string);
+    } else {
+      rejectCode(payload as Error);
+    }
+
+    void close().catch(() => undefined);
+  };
+
+  server = createServer((req, res) => {
+    const requestUrl = new URL(req.url || '/', parsedUrl.origin);
+    if (requestUrl.pathname !== parsedUrl.pathname) {
+      res.statusCode = 404;
+      res.end('Not found');
+      return;
+    }
+
+    const error = requestUrl.searchParams.get('error');
+    if (error) {
+      res.statusCode = 400;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end(`OpenRouter authorization failed: ${error}`);
+      void finish(
+        'reject',
+        new Error(`OpenRouter authorization failed: ${error}`),
+      );
+      return;
+    }
+
+    const callbackState = requestUrl.searchParams.get('state');
+    if (expectedState && callbackState !== expectedState) {
+      res.statusCode = 400;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end('Invalid OAuth state.');
+      void finish(
+        'reject',
+        new Error('Invalid OAuth state from OpenRouter callback.'),
+      );
+      return;
+    }
+
+    const code = requestUrl.searchParams.get('code');
+    if (!code) {
+      res.statusCode = 400;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end('Missing authorization code.');
+      void finish(
+        'reject',
+        new Error('Missing authorization code from OpenRouter callback.'),
+      );
+      return;
+    }
+
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.end(
+      '<html><body><h1>OpenRouter authentication complete.</h1><p>You can return to Qwen Code.</p></body></html>',
+    );
+    void finish('resolve', code);
+  });
+
+  server.once('error', (error) => {
+    rejectReady(error instanceof Error ? error : new Error(String(error)));
+    void finish(
+      'reject',
+      error instanceof Error ? error : new Error(String(error)),
+    );
+  });
+
+  const port = parsedUrl.port ? Number(parsedUrl.port) : 80;
+  server.listen(port, parsedUrl.hostname, () => {
+    resolveReady();
+  });
+
+  timeout = setTimeout(() => {
+    void finish(
+      'reject',
+      new Error('Timed out waiting for OpenRouter OAuth callback.'),
+    );
+  }, timeoutMs);
+
+  return {
+    ready,
+    waitForCode,
+    close,
+  };
+}
+
+function buildOpenRouterHeaders() {
+  return {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    'HTTP-Referer': 'https://github.com/QwenLM/qwen-code.git',
+    'X-OpenRouter-Title': 'Qwen Code',
+  };
+}
+
+const OPENROUTER_MODEL_PRIORITY_PREFIXES = ['qwen/', 'glm/', 'minimax/'];
+const OPENROUTER_RECOMMENDED_MODEL_LIMIT = 16;
+const OPENROUTER_FREE_MODEL_ID_HINT = ':free';
+
+export function getPreferredOpenRouterModelId(
+  models: ModelConfig[],
+): string | undefined {
+  return (
+    models.find((model) => model.id === OPENROUTER_DEFAULT_MODEL)?.id ||
+    models[0]?.id
+  );
+}
+
+function isOpenRouterFreeModelId(modelId: string): boolean {
+  const normalizedId = modelId.toLowerCase();
+  return (
+    normalizedId.includes(OPENROUTER_FREE_MODEL_ID_HINT) ||
+    normalizedId === 'openrouter/free'
+  );
+}
+
+function getOpenRouterModelPriority(modelId: string): number {
+  const normalizedId = modelId.toLowerCase();
+  const matchedIndex = OPENROUTER_MODEL_PRIORITY_PREFIXES.findIndex((prefix) =>
+    normalizedId.startsWith(prefix),
+  );
+  return matchedIndex === -1
+    ? OPENROUTER_MODEL_PRIORITY_PREFIXES.length
+    : matchedIndex;
+}
+
+function isOpenRouterFreeConfig(model: ModelConfig): boolean {
+  return isOpenRouterFreeModelId(model.id);
+}
+
+function compareOpenRouterModels(a: ModelConfig, b: ModelConfig): number {
+  const freeDiff =
+    Number(isOpenRouterFreeConfig(b)) - Number(isOpenRouterFreeConfig(a));
+  if (freeDiff !== 0) {
+    return freeDiff;
+  }
+
+  const priorityDiff =
+    getOpenRouterModelPriority(a.id) - getOpenRouterModelPriority(b.id);
+  if (priorityDiff !== 0) {
+    return priorityDiff;
+  }
+
+  return a.id.localeCompare(b.id);
+}
+
+function toOpenRouterModelConfig(
+  model: OpenRouterModelApiRecord,
+): ModelConfig | null {
+  if (!model.id) {
+    return null;
+  }
+
+  const outputModalities = model.architecture?.output_modalities || [];
+  const supportsTextOutput = outputModalities.length
+    ? outputModalities.includes('text')
+    : true;
+
+  if (!supportsTextOutput) {
+    return null;
+  }
+
+  const inputModalities = model.architecture?.input_modalities || [];
+  const supportsVision = inputModalities.includes('image');
+
+  return {
+    id: model.id,
+    name: model.name
+      ? `OpenRouter · ${model.name}`
+      : `OpenRouter · ${model.id}`,
+    baseUrl: OPENROUTER_BASE_URL,
+    envKey: OPENROUTER_ENV_KEY,
+    capabilities: supportsVision ? { vision: true } : undefined,
+    generationConfig:
+      typeof model.context_length === 'number'
+        ? { contextWindowSize: model.context_length }
+        : undefined,
+  };
+}
+
+function chooseRepresentativeModel(
+  models: ModelConfig[],
+  predicate: (model: ModelConfig) => boolean,
+  selectedIds: Set<string>,
+): ModelConfig | undefined {
+  return models.find((model) => predicate(model) && !selectedIds.has(model.id));
+}
+
+function addRecommendedModel(
+  target: ModelConfig[],
+  model: ModelConfig | undefined,
+  selectedIds: Set<string>,
+  limit: number,
+): void {
+  if (!model || selectedIds.has(model.id) || target.length >= limit) {
+    return;
+  }
+  target.push(model);
+  selectedIds.add(model.id);
+}
+
+export function selectRecommendedOpenRouterModels(
+  models: ModelConfig[],
+  limit = OPENROUTER_RECOMMENDED_MODEL_LIMIT,
+): ModelConfig[] {
+  if (models.length <= limit) {
+    return models;
+  }
+
+  const sorted = [...models].sort(compareOpenRouterModels);
+  const recommended: ModelConfig[] = [];
+  const selectedIds = new Set<string>();
+
+  const freeModels = sorted.filter((model) => isOpenRouterFreeConfig(model));
+  for (const model of freeModels.slice(0, Math.min(limit, 6))) {
+    addRecommendedModel(recommended, model, selectedIds, limit);
+  }
+
+  for (const prefix of OPENROUTER_MODEL_PRIORITY_PREFIXES) {
+    addRecommendedModel(
+      recommended,
+      chooseRepresentativeModel(
+        sorted,
+        (model) => model.id.toLowerCase().startsWith(prefix),
+        selectedIds,
+      ),
+      selectedIds,
+      limit,
+    );
+  }
+
+  for (const family of ['anthropic/', 'google/', 'openai/']) {
+    addRecommendedModel(
+      recommended,
+      chooseRepresentativeModel(
+        sorted,
+        (model) => model.id.toLowerCase().startsWith(family),
+        selectedIds,
+      ),
+      selectedIds,
+      limit,
+    );
+  }
+
+  addRecommendedModel(
+    recommended,
+    chooseRepresentativeModel(
+      sorted,
+      (model) => model.capabilities?.vision === true,
+      selectedIds,
+    ),
+    selectedIds,
+    limit,
+  );
+
+  addRecommendedModel(
+    recommended,
+    chooseRepresentativeModel(
+      sorted,
+      (model) => (model.generationConfig?.contextWindowSize || 0) >= 1000000,
+      selectedIds,
+    ),
+    selectedIds,
+    limit,
+  );
+
+  for (const model of sorted) {
+    if (recommended.length >= limit) {
+      break;
+    }
+    addRecommendedModel(recommended, model, selectedIds, limit);
+  }
+
+  return recommended;
+}
+
+export function isOpenRouterConfig(config: ModelConfig): boolean {
+  return (config.baseUrl || '').includes('openrouter.ai');
+}
+
+export function mergeOpenRouterConfigs(
+  existingConfigs: ModelConfig[],
+  openRouterModels = OPENROUTER_DEFAULT_MODELS,
+): ModelConfig[] {
+  const nonOpenRouterConfigs = existingConfigs.filter(
+    (existing) => !isOpenRouterConfig(existing),
+  );
+  return [...openRouterModels, ...nonOpenRouterConfigs];
+}
+
+export interface ApplyOpenRouterModelsResult {
+  updatedConfigs: ModelConfig[];
+  activeModelId?: string;
+  persistScope: ReturnType<typeof getPersistScopeForModelSelection>;
+}
+
+export async function applyOpenRouterModelsConfiguration(params: {
+  settings: LoadedSettings;
+  config: Config;
+  apiKey: string;
+  reloadConfig: boolean;
+}): Promise<ApplyOpenRouterModelsResult> {
+  const { settings, config, apiKey, reloadConfig } = params;
+  const persistScope = getPersistScopeForModelSelection(settings);
+
+  settings.setValue(persistScope, `env.${OPENROUTER_ENV_KEY}`, apiKey);
+  process.env[OPENROUTER_ENV_KEY] = apiKey;
+
+  const existingConfigs =
+    (settings.merged.modelProviders as ModelProvidersConfig | undefined)?.[
+      AuthType.USE_OPENAI
+    ] || [];
+  const openRouterCatalog = await getOpenRouterModelsWithFallback();
+  const openRouterModels = selectRecommendedOpenRouterModels(openRouterCatalog);
+  const updatedConfigs = mergeOpenRouterConfigs(
+    existingConfigs,
+    openRouterModels,
+  );
+
+  settings.setValue(
+    persistScope,
+    `modelProviders.${AuthType.USE_OPENAI}`,
+    updatedConfigs,
+  );
+  settings.setValue(
+    persistScope,
+    'security.auth.selectedType',
+    AuthType.USE_OPENAI,
+  );
+
+  const activeModelId = getPreferredOpenRouterModelId(updatedConfigs);
+  if (activeModelId) {
+    settings.setValue(persistScope, 'model.name', activeModelId);
+  }
+
+  if (reloadConfig) {
+    const updatedModelProviders: ModelProvidersConfig = {
+      ...(settings.merged.modelProviders as ModelProvidersConfig | undefined),
+      [AuthType.USE_OPENAI]: updatedConfigs,
+    };
+    config.reloadModelProvidersConfig(updatedModelProviders);
+  }
+
+  return {
+    updatedConfigs,
+    activeModelId,
+    persistScope,
+  };
+}
+
+export async function fetchOpenRouterModels(): Promise<ModelConfig[]> {
+  const response = await fetch(OPENROUTER_MODELS_URL, {
+    method: 'GET',
+    headers: buildOpenRouterHeaders(),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `OpenRouter models request failed (${response.status}): ${errorText}`,
+    );
+  }
+
+  const data = (await response.json()) as {
+    data?: OpenRouterModelApiRecord[];
+  };
+  const records = Array.isArray(data.data) ? data.data : [];
+  const models = records
+    .map((record) => toOpenRouterModelConfig(record))
+    .filter((model): model is ModelConfig => model !== null)
+    .sort(compareOpenRouterModels);
+
+  if (models.length < OPENROUTER_MINIMUM_TEXT_MODELS) {
+    throw new Error(
+      'OpenRouter models request returned no usable text models.',
+    );
+  }
+
+  return models;
+}
+
+export async function getOpenRouterModelsWithFallback(): Promise<
+  ModelConfig[]
+> {
+  try {
+    return await fetchOpenRouterModels();
+  } catch {
+    return OPENROUTER_DEFAULT_MODELS;
+  }
+}
+
+export async function exchangeAuthCodeForApiKey(params: {
+  code: string;
+  codeVerifier: string;
+}): Promise<OpenRouterOAuthResult> {
+  const response = await fetch(OPENROUTER_OAUTH_EXCHANGE_URL, {
+    method: 'POST',
+    headers: buildOpenRouterHeaders(),
+    body: JSON.stringify({
+      code: params.code,
+      code_verifier: params.codeVerifier,
+      code_challenge_method: OPENROUTER_CODE_CHALLENGE_METHOD,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `OpenRouter API key exchange failed (${response.status}): ${errorText}`,
+    );
+  }
+
+  const data = (await response.json()) as {
+    key?: string;
+    user_id?: string;
+  };
+
+  if (!data.key) {
+    throw new Error(
+      'OpenRouter API key exchange succeeded but no key was returned.',
+    );
+  }
+
+  return {
+    apiKey: data.key,
+    userId: data.user_id,
+  };
+}
+
+interface OAuthSignalTarget {
+  once(event: NodeJS.Signals, listener: (signal: NodeJS.Signals) => void): void;
+  removeListener(
+    event: NodeJS.Signals,
+    listener: (signal: NodeJS.Signals) => void,
+  ): void;
+}
+
+interface OpenRouterOAuthLoginDeps {
+  openBrowser?: typeof open;
+  startListener?: typeof startOAuthCallbackListener;
+  exchangeApiKey?: typeof exchangeAuthCodeForApiKey;
+  now?: () => number;
+  signalTarget?: OAuthSignalTarget;
+  abortSignal?: AbortSignal;
+  session?: OpenRouterOAuthSession;
+}
+
+export async function runOpenRouterOAuthLogin(
+  callbackUrl = OPENROUTER_OAUTH_CALLBACK_URL,
+  deps: OpenRouterOAuthLoginDeps = {},
+): Promise<OpenRouterOAuthResult> {
+  const session = deps.session || createOpenRouterOAuthSession(callbackUrl);
+  const {
+    callbackUrl: effectiveCallbackUrl,
+    codeVerifier,
+    state,
+    authorizationUrl: authUrl,
+  } = session;
+
+  const openBrowser = deps.openBrowser || open;
+  const startListener = deps.startListener || startOAuthCallbackListener;
+  const exchangeApiKey = deps.exchangeApiKey || exchangeAuthCodeForApiKey;
+  const now = deps.now || Date.now;
+  const signalTarget = deps.signalTarget || process;
+  const abortSignal = deps.abortSignal;
+
+  const listener = startListener(
+    effectiveCallbackUrl,
+    OPENROUTER_OAUTH_TIMEOUT_MS,
+    state,
+  );
+  let cleanupSignalHandlers = () => {};
+  let cleanupAbortListener = () => {};
+  try {
+    await listener.ready;
+    await openBrowser(authUrl);
+
+    const waitForCancel = new Promise<never>((_, reject) => {
+      const handleSignal = (signal: NodeJS.Signals) => {
+        reject(
+          new Error(
+            `OpenRouter OAuth cancelled by user (${signal}) while waiting for browser authorization.`,
+          ),
+        );
+      };
+
+      signalTarget.once('SIGINT', handleSignal);
+      signalTarget.once('SIGTERM', handleSignal);
+      cleanupSignalHandlers = () => {
+        signalTarget.removeListener('SIGINT', handleSignal);
+        signalTarget.removeListener('SIGTERM', handleSignal);
+      };
+    });
+
+    const waitForAbort = new Promise<never>((_, reject) => {
+      if (!abortSignal) {
+        return;
+      }
+
+      const handleAbort = () => {
+        reject(new DOMException('OpenRouter OAuth cancelled.', 'AbortError'));
+      };
+
+      if (abortSignal.aborted) {
+        handleAbort();
+        return;
+      }
+
+      abortSignal.addEventListener('abort', handleAbort, { once: true });
+      cleanupAbortListener = () => {
+        abortSignal.removeEventListener('abort', handleAbort);
+      };
+    });
+
+    const waitStartMs = now();
+    const code = await Promise.race([
+      listener.waitForCode,
+      waitForCancel,
+      waitForAbort,
+    ]);
+    cleanupSignalHandlers();
+    cleanupAbortListener();
+    const authorizationCodeWaitMs = now() - waitStartMs;
+
+    const exchangeStartMs = now();
+    const exchangeResult = await exchangeApiKey({ code, codeVerifier });
+    const apiKeyExchangeMs = now() - exchangeStartMs;
+
+    return {
+      ...exchangeResult,
+      authorizationUrl: authUrl,
+      authorizationCodeWaitMs,
+      apiKeyExchangeMs,
+    };
+  } finally {
+    cleanupSignalHandlers();
+    cleanupAbortListener();
+    void listener.close().catch(() => undefined);
+  }
+}
diff --git a/packages/cli/src/commands/auth/status.test.ts b/packages/cli/src/commands/auth/status.test.ts
index ca5a52718..e49a4e553 100644
--- a/packages/cli/src/commands/auth/status.test.ts
+++ b/packages/cli/src/commands/auth/status.test.ts
@@ -6,7 +6,8 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { showAuthStatus } from './handler.js';
-import { AuthType, CODING_PLAN_ENV_KEY } from '@qwen-code/qwen-code-core';
+import { AuthType } from '@qwen-code/qwen-code-core';
+import { CODING_PLAN_ENV_KEY } from '../../constants/codingPlan.js';
 import type { LoadedSettings } from '../../config/settings.js';
 
 vi.mock('../../config/settings.js', () => ({
@@ -26,11 +27,15 @@ describe('showAuthStatus', () => {
     vi.clearAllMocks();
     vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
     delete process.env[CODING_PLAN_ENV_KEY];
+    delete process.env['OPENAI_API_KEY'];
+    delete process.env['OPENROUTER_API_KEY'];
   });
 
   afterEach(() => {
     vi.restoreAllMocks();
     delete process.env[CODING_PLAN_ENV_KEY];
+    delete process.env['OPENAI_API_KEY'];
+    delete process.env['OPENROUTER_API_KEY'];
   });
 
   const createMockSettings = (
@@ -55,6 +60,9 @@ describe('showAuthStatus', () => {
     expect(writeStdoutLine).toHaveBeenCalledWith(
       expect.stringContaining('No authentication method configured'),
     );
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('qwen auth openrouter'),
+    );
     expect(writeStdoutLine).toHaveBeenCalledWith(
       expect.stringContaining('qwen auth qwen-oauth'),
     );
@@ -120,6 +128,77 @@ describe('showAuthStatus', () => {
     expect(process.exit).toHaveBeenCalledWith(0);
   });
 
+  it('should show OpenRouter status when configured with API key', async () => {
+    process.env['OPENROUTER_API_KEY'] = 'test-openrouter-key';
+
+    vi.mocked(loadSettings).mockReturnValue(
+      createMockSettings({
+        security: {
+          auth: {
+            selectedType: AuthType.USE_OPENAI,
+          },
+        },
+        model: {
+          name: 'openai/gpt-4o-mini',
+        },
+        modelProviders: {
+          [AuthType.USE_OPENAI]: [
+            {
+              id: 'openai/gpt-4o-mini',
+              name: 'OpenRouter · GPT-4o mini',
+              baseUrl: 'https://openrouter.ai/api/v1',
+              envKey: 'OPENROUTER_API_KEY',
+            },
+          ],
+        },
+      }),
+    );
+
+    await showAuthStatus();
+
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('OpenRouter'),
+    );
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('openai/gpt-4o-mini'),
+    );
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('API key configured'),
+    );
+    expect(process.exit).toHaveBeenCalledWith(0);
+  });
+
+  it('should show OpenRouter as incomplete when API key is missing', async () => {
+    vi.mocked(loadSettings).mockReturnValue(
+      createMockSettings({
+        security: {
+          auth: {
+            selectedType: AuthType.USE_OPENAI,
+          },
+        },
+        modelProviders: {
+          [AuthType.USE_OPENAI]: [
+            {
+              id: 'openai/gpt-4o-mini',
+              name: 'OpenRouter · GPT-4o mini',
+              baseUrl: 'https://openrouter.ai/api/v1',
+              envKey: 'OPENROUTER_API_KEY',
+            },
+          ],
+        },
+      }),
+    );
+
+    await showAuthStatus();
+
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('OpenRouter (Incomplete)'),
+    );
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('qwen auth openrouter'),
+    );
+  });
+
   it('should show Coding Plan as incomplete when API key is missing', async () => {
     vi.mocked(loadSettings).mockReturnValue(
       createMockSettings({
@@ -144,6 +223,78 @@ describe('showAuthStatus', () => {
     );
   });
 
+  it('should show Coding Plan when detected via modelProviders entry (no codingPlan.region)', async () => {
+    process.env[CODING_PLAN_ENV_KEY] = 'test-api-key';
+
+    vi.mocked(loadSettings).mockReturnValue(
+      createMockSettings({
+        security: {
+          auth: {
+            selectedType: AuthType.USE_OPENAI,
+          },
+        },
+        model: {
+          name: 'qwen3.5-plus',
+        },
+        modelProviders: {
+          openai: [
+            {
+              id: 'qwen3.5-plus',
+              envKey: 'BAILIAN_CODING_PLAN_API_KEY',
+              baseUrl: 'https://coding.dashscope.aliyuncs.com/v1',
+            },
+          ],
+        },
+      }),
+    );
+
+    await showAuthStatus();
+
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('Alibaba Cloud Coding Plan'),
+    );
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('API key configured'),
+    );
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('中国 (China)'),
+    );
+    expect(writeStdoutLine).not.toHaveBeenCalledWith(
+      expect.stringContaining('OpenAI-compatible Provider'),
+    );
+    expect(process.exit).toHaveBeenCalledWith(0);
+  });
+
+  it('should not fall back to stale Coding Plan metadata when model selection is unmatched', async () => {
+    process.env['OPENAI_API_KEY'] = 'test-openai-key';
+
+    vi.mocked(loadSettings).mockReturnValue(
+      createMockSettings({
+        security: {
+          auth: {
+            selectedType: AuthType.USE_OPENAI,
+          },
+        },
+        codingPlan: {
+          region: 'global',
+          version: 'abc123def456',
+        },
+        model: {
+          name: 'manual-provider-model',
+        },
+      }),
+    );
+
+    await showAuthStatus();
+
+    expect(writeStdoutLine).toHaveBeenCalledWith(
+      expect.stringContaining('OpenAI-compatible Provider'),
+    );
+    expect(writeStdoutLine).not.toHaveBeenCalledWith(
+      expect.stringContaining('Alibaba Cloud Coding Plan'),
+    );
+  });
+
   it('should show Coding Plan region for china', async () => {
     process.env[CODING_PLAN_ENV_KEY] = 'test-api-key';
 
@@ -262,4 +413,339 @@ describe('showAuthStatus', () => {
     );
     expect(process.exit).toHaveBeenCalledWith(1);
   });
+
+  describe('OpenAI-compatible provider (no Coding Plan)', () => {
+    afterEach(() => {
+      delete process.env['OPENAI_API_KEY'];
+      delete process.env['CUSTOM_API_KEY'];
+      delete process.env['XUNFEI_API_KEY'];
+      delete process.env[CODING_PLAN_ENV_KEY];
+    });
+
+    it('should show OpenAI-compatible status with OPENAI_API_KEY', async () => {
+      process.env['OPENAI_API_KEY'] = 'test-key';
+
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+          model: {
+            name: 'gpt-4o',
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('gpt-4o'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key configured'),
+      );
+      expect(writeStdoutLine).not.toHaveBeenCalledWith(
+        expect.stringContaining('Alibaba Cloud Coding Plan'),
+      );
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should show OpenAI-compatible status with custom envKey from modelProviders', async () => {
+      process.env['CUSTOM_API_KEY'] = 'test-key';
+
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+          model: {
+            name: 'custom-model',
+          },
+          modelProviders: {
+            openai: [
+              {
+                id: 'custom-model',
+                envKey: 'CUSTOM_API_KEY',
+                baseUrl: 'https://custom-api.example.com/v1',
+              },
+            ],
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('custom-model'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('https://custom-api.example.com/v1'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key configured'),
+      );
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should show OpenAI-compatible status with settings.security.auth.apiKey', async () => {
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+              apiKey: 'settings-api-key',
+              baseUrl: 'https://my-provider.example.com/v1',
+            },
+          },
+          model: {
+            name: 'my-model',
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('https://my-provider.example.com/v1'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key configured'),
+      );
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should show incomplete when no API key is found for OpenAI-compatible provider', async () => {
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider (Incomplete)'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key not found'),
+      );
+      expect(writeStdoutLine).not.toHaveBeenCalledWith(
+        expect.stringContaining('Alibaba Cloud Coding Plan'),
+      );
+    });
+
+    it('should detect API key via default model when model.name is unset', async () => {
+      process.env['CUSTOM_API_KEY'] = 'test-key';
+
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+          modelProviders: {
+            openai: [
+              {
+                id: 'default-model',
+                envKey: 'CUSTOM_API_KEY',
+                baseUrl: 'https://default-api.example.com/v1',
+              },
+            ],
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('https://default-api.example.com/v1'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key configured'),
+      );
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should show Incomplete when explicit envKey is missing even if OPENAI_API_KEY is set', async () => {
+      process.env['OPENAI_API_KEY'] = 'fallback-key';
+
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+          model: {
+            name: 'custom-model',
+          },
+          modelProviders: {
+            openai: [
+              {
+                id: 'custom-model',
+                envKey: 'CUSTOM_API_KEY',
+                baseUrl: 'https://custom-api.example.com/v1',
+              },
+            ],
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider (Incomplete)'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key not found'),
+      );
+    });
+
+    it('should not bind to unrelated provider entry when model.name does not match', async () => {
+      process.env['OPENAI_API_KEY'] = 'test-key';
+
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+          model: {
+            name: 'manual-model-not-in-providers',
+          },
+          modelProviders: {
+            openai: [
+              {
+                id: 'other-model',
+                envKey: 'OTHER_API_KEY',
+                baseUrl: 'https://other-api.example.com/v1',
+              },
+            ],
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key configured'),
+      );
+      // Should NOT show the unrelated provider's base URL
+      expect(writeStdoutLine).not.toHaveBeenCalledWith(
+        expect.stringContaining('https://other-api.example.com/v1'),
+      );
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should show OpenAI-compatible when stale codingPlan.region exists but active model is generic', async () => {
+      process.env['XUNFEI_API_KEY'] = 'active-key';
+
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+          codingPlan: {
+            region: 'china',
+            version: 'stale-version',
+          },
+          model: {
+            name: 'spark-v4',
+          },
+          modelProviders: {
+            openai: [
+              {
+                id: 'spark-v4',
+                envKey: 'XUNFEI_API_KEY',
+                baseUrl: 'https://spark-api-open.xf-yun.com/v1',
+              },
+            ],
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key configured'),
+      );
+      expect(writeStdoutLine).not.toHaveBeenCalledWith(
+        expect.stringContaining('Alibaba Cloud Coding Plan'),
+      );
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+
+    it('should show OpenAI-compatible when stale Coding Plan key exists but active model is generic', async () => {
+      process.env[CODING_PLAN_ENV_KEY] = 'stale-coding-plan-key';
+      process.env['XUNFEI_API_KEY'] = 'active-key';
+
+      vi.mocked(loadSettings).mockReturnValue(
+        createMockSettings({
+          security: {
+            auth: {
+              selectedType: AuthType.USE_OPENAI,
+            },
+          },
+          model: {
+            name: 'spark-v4',
+          },
+          modelProviders: {
+            openai: [
+              {
+                id: 'spark-v4',
+                envKey: 'XUNFEI_API_KEY',
+                baseUrl: 'https://spark-api-open.xf-yun.com/v1',
+              },
+            ],
+          },
+        }),
+      );
+
+      await showAuthStatus();
+
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('OpenAI-compatible Provider'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('spark-v4'),
+      );
+      expect(writeStdoutLine).toHaveBeenCalledWith(
+        expect.stringContaining('API key configured'),
+      );
+      expect(writeStdoutLine).not.toHaveBeenCalledWith(
+        expect.stringContaining('Alibaba Cloud Coding Plan'),
+      );
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+  });
 });
diff --git a/packages/cli/src/config/config.ts b/packages/cli/src/config/config.ts
index 304f878ac..fb3d1318a 100755
--- a/packages/cli/src/config/config.ts
+++ b/packages/cli/src/config/config.ts
@@ -1168,6 +1168,7 @@ export async function loadCliConfig(
       argv.maxSessionTurns ?? settings.model?.maxSessionTurns ?? -1,
     experimentalZedIntegration: argv.acp || argv.experimentalAcp || false,
     cronEnabled: settings.experimental?.cron ?? false,
+    emitToolUseSummaries: settings.experimental?.emitToolUseSummaries ?? true,
     listExtensions: argv.listExtensions || false,
     overrideExtensions: overrideExtensions || argv.extensions,
     noBrowser: !!process.env['NO_BROWSER'],
diff --git a/packages/cli/src/config/settingsSchema.ts b/packages/cli/src/config/settingsSchema.ts
index 9bfa13110..c051ffa15 100644
--- a/packages/cli/src/config/settingsSchema.ts
+++ b/packages/cli/src/config/settingsSchema.ts
@@ -924,6 +924,17 @@ const SETTINGS_SCHEMA = {
             parentKey: 'generationConfig',
             showInDialog: false,
           },
+          splitToolMedia: {
+            type: 'boolean',
+            label: 'Split Tool Result Media',
+            category: 'Generation Configuration',
+            requiresRestart: false,
+            default: false,
+            description:
+              'When true, media (images / audio / video / files) returned by MCP tool calls is split into a follow-up user message instead of being embedded in the tool message. Required for strict OpenAI-compatible servers (e.g., LM Studio) that reject non-text content on `role: "tool"` messages with HTTP 400 "Invalid \'messages\' in payload". Default false preserves the prior behavior for permissive providers. See QwenLM/qwen-code#3616.',
+            parentKey: 'generationConfig',
+            showInDialog: false,
+          },
           schemaCompliance: {
             type: 'enum',
             label: 'Tool Schema Compliance',
@@ -1862,6 +1873,16 @@ const SETTINGS_SCHEMA = {
           'Enable in-session cron/loop tools (experimental). When enabled, the model can create recurring prompts using cron_create, cron_list, and cron_delete tools. Can also be enabled via QWEN_CODE_ENABLE_CRON=1 environment variable.',
         showInDialog: true,
       },
+      emitToolUseSummaries: {
+        type: 'boolean',
+        label: 'Tool Use Summaries',
+        category: 'Experimental',
+        requiresRestart: false,
+        default: true,
+        description:
+          'Generate a short LLM-based label after each tool batch completes. In compact mode the label replaces the generic `Tool × N` header; in full mode it appears as a dim `● <label>` line below the tool group. Requires a fast model to be configured; runs in parallel with the next API call so latency is hidden. Currently affects interactive CLI rendering only — SDK / non-interactive emission of the `tool_use_summary` message is not yet wired (the message factory is exported for a follow-up PR). Can be overridden with QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0 or =1.',
+        showInDialog: true,
+      },
     },
   },
 } as const satisfies SettingsSchema;
diff --git a/packages/cli/src/gemini.tsx b/packages/cli/src/gemini.tsx
index 49c29532d..1add91580 100644
--- a/packages/cli/src/gemini.tsx
+++ b/packages/cli/src/gemini.tsx
@@ -44,6 +44,7 @@ import { SessionStatsProvider } from './ui/contexts/SessionContext.js';
 import { SettingsContext } from './ui/contexts/SettingsContext.js';
 import { VimModeProvider } from './ui/contexts/VimModeContext.js';
 import { AgentViewProvider } from './ui/contexts/AgentViewContext.js';
+import { BackgroundTaskViewProvider } from './ui/contexts/BackgroundTaskViewContext.js';
 import { useKittyKeyboardProtocol } from './ui/hooks/useKittyKeyboardProtocol.js';
 import { themeManager, AUTO_THEME_NAME } from './ui/themes/theme-manager.js';
 import {
@@ -77,6 +78,7 @@ import {
   startEarlyInputCapture,
   stopAndGetCapturedInput,
 } from './utils/earlyInputCapture.js';
+import { preconnectApi } from './utils/apiPreconnect.js';
 import { validateNonInteractiveAuth } from './validateNonInterActiveAuth.js';
 import { showResumeSessionPicker } from './ui/components/StandaloneSessionPicker.js';
 import { initializeLlmOutputLanguage } from './utils/languageUtils.js';
@@ -85,6 +87,7 @@ import { DualOutputContext } from './dualOutput/DualOutputContext.js';
 import { RemoteInputWatcher } from './remoteInput/RemoteInputWatcher.js';
 import { RemoteInputContext } from './remoteInput/RemoteInputContext.js';
 import { installTerminalRedrawOptimizer } from './ui/utils/terminalRedrawOptimizer.js';
+import { installSynchronizedOutput } from './ui/utils/synchronizedOutput.js';
 
 const debugLogger = createDebugLogger('STARTUP');
 
@@ -174,6 +177,10 @@ export async function startInteractiveUI(
     process.stdout.isTTY && !config.getScreenReader()
       ? installTerminalRedrawOptimizer(process.stdout)
       : () => {};
+  const restoreSynchronizedOutput =
+    process.stdout.isTTY && !config.getScreenReader()
+      ? installSynchronizedOutput(process.stdout)
+      : () => {};
 
   // Create dual output bridge if --json-fd or --json-file is specified.
   // Errors are caught so a bad fd/path degrades gracefully instead of
@@ -245,13 +252,15 @@ export async function startInteractiveUI(
               <SessionStatsProvider sessionId={config.getSessionId()}>
                 <VimModeProvider settings={settings}>
                   <AgentViewProvider config={config}>
-                    <AppContainer
-                      config={config}
-                      settings={settings}
-                      startupWarnings={startupWarnings}
-                      version={version}
-                      initializationResult={initializationResult}
-                    />
+                    <BackgroundTaskViewProvider config={config}>
+                      <AppContainer
+                        config={config}
+                        settings={settings}
+                        startupWarnings={startupWarnings}
+                        version={version}
+                        initializationResult={initializationResult}
+                      />
+                    </BackgroundTaskViewProvider>
                   </AgentViewProvider>
                 </VimModeProvider>
               </SessionStatsProvider>
@@ -297,6 +306,7 @@ export async function startInteractiveUI(
     // operational, preventing garbled terminal output after the app exits.
     disableKittyProtocol();
     instance.unmount();
+    restoreSynchronizedOutput();
     restoreTerminalRedrawOptimizer();
   });
 }
@@ -522,6 +532,21 @@ export async function main() {
     // This ensures MCP server subprocesses are properly terminated on exit
     registerCleanup(() => config.shutdown());
 
+    // Startup optimization: preconnect API to warm TCP+TLS connection
+    // Fires early; cost is one HEAD request even for local-only commands
+    try {
+      const modelsConfig = config.getModelsConfig();
+      const authType = modelsConfig.getCurrentAuthType();
+      const resolvedBaseUrl = modelsConfig.getGenerationConfig().baseUrl;
+      const proxy = config.getProxy();
+      preconnectApi(authType, { resolvedBaseUrl, proxy });
+    } catch (error) {
+      // If we can't get authType, skip preconnect - it's optional optimization
+      debugLogger.debug(
+        `Preconnect skipped due to error getting authType: ${error}`,
+      );
+    }
+
     // FIXME: list extensions after the config initialize
     // if (config.getListExtensions()) {
     //   console.log('Installed extensions:');
diff --git a/packages/cli/src/i18n/languages.ts b/packages/cli/src/i18n/languages.ts
index 0f72c7c96..02c17d14f 100644
--- a/packages/cli/src/i18n/languages.ts
+++ b/packages/cli/src/i18n/languages.ts
@@ -13,6 +13,7 @@ export type SupportedLanguage =
   | 'ja'
   | 'pt'
   | 'fr'
+  | 'ca'
   | string;
 
 export interface LanguageDefinition {
@@ -75,6 +76,12 @@ export const SUPPORTED_LANGUAGES: readonly LanguageDefinition[] = [
     fullName: 'French',
     nativeName: 'Français',
   },
+  {
+    code: 'ca',
+    id: 'ca-ES',
+    fullName: 'Catalan',
+    nativeName: 'Català',
+  },
 ];
 
 /**
diff --git a/packages/cli/src/i18n/locales/ca.js b/packages/cli/src/i18n/locales/ca.js
new file mode 100644
index 000000000..c8599fd04
--- /dev/null
+++ b/packages/cli/src/i18n/locales/ca.js
@@ -0,0 +1,2143 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Traduccions en català per al CLI de Qwen Code per Jordi Mas i Hernàndez <jmas@softcatala.org>
+
+export default {
+  // ============================================================================
+  // Ajuda / Components de la interfície
+  // ============================================================================
+  '↑ to manage attachments': '↑ per gestionar els adjunts',
+  '← → select, Delete to remove, ↓ to exit':
+    '← → seleccionar, Supr per eliminar, ↓ per sortir',
+  'Attachments: ': 'Adjunts: ',
+
+  'Basics:': 'Bàsic:',
+  'Add context': 'Afegir context',
+  'Use {{symbol}} to specify files for context (e.g., {{example}}) to target specific files or folders.':
+    'Useu {{symbol}} per especificar fitxers de context (p. ex., {{example}}) per seleccionar fitxers o carpetes específics.',
+  '@': '@',
+  '@src/myFile.ts': '@src/myFile.ts',
+  'Shell mode': 'Mode shell',
+  'YOLO mode': 'Mode YOLO',
+  'plan mode': 'mode de planificació',
+  'auto-accept edits': 'acceptació automàtica de canvis',
+  'Accepting edits': 'Acceptant canvis',
+  '(shift + tab to cycle)': '(maj + tab per canviar)',
+  '(tab to cycle)': '(tab per canviar)',
+  'Execute shell commands via {{symbol}} (e.g., {{example1}}) or use natural language (e.g., {{example2}}).':
+    'Executeu ordres shell amb {{symbol}} (p. ex., {{example1}}) o useu el llenguatge natural (p. ex., {{example2}}).',
+  '!': '!',
+  '!npm run start': '!npm run start',
+  'start server': 'iniciar el servidor',
+  'Commands:': 'Ordres:',
+  'shell command': 'ordre shell',
+  'Model Context Protocol command (from external servers)':
+    'Ordre del protocol de context del model (des de servidors externs)',
+  'Keyboard Shortcuts:': 'Dreceres de teclat:',
+  'Toggle this help display': 'Mostrar/amagar aquesta ajuda',
+  'Toggle shell mode': 'Canviar el mode shell',
+  'Open command menu': "Obrir el menú d'ordres",
+  'Add file context': 'Afegir context de fitxer',
+  'Accept suggestion / Autocomplete': 'Acceptar suggeriment / Autocompleció',
+  'Reverse search history': "Cerca inversa a l'historial",
+  'Press ? again to close': 'Premeu ? de nou per tancar',
+  'for shell mode': 'per al mode shell',
+  'for commands': 'per a les ordres',
+  'for file paths': 'per als camins de fitxers',
+  'to clear input': "per esborrar l'entrada",
+  'to cycle approvals': 'per canviar les aprovacions',
+  'to quit': 'per sortir',
+  'for newline': 'per a nova línia',
+  'to clear screen': 'per netejar la pantalla',
+  'to search history': "per cercar a l'historial",
+  'to paste images': 'per enganxar imatges',
+  'for external editor': 'per a editor extern',
+  'to toggle compact mode': 'per canviar el mode compacte',
+  'Jump through words in the input': "Saltar entre paraules a l'entrada",
+  'Close dialogs, cancel requests, or quit application':
+    "Tancar diàlegs, cancel·lar peticions o sortir de l'aplicació",
+  'New line': 'Nova línia',
+  'New line (Alt+Enter works for certain linux distros)':
+    'Nova línia (Alt+Retorn funciona en certes distribucions de Linux)',
+  'Clear the screen': 'Netejar la pantalla',
+  'Open input in external editor': "Obrir l'entrada en un editor extern",
+  'Send message': 'Enviar missatge',
+  'Initializing...': 'Inicialitzant...',
+  'Connecting to MCP servers... ({{connected}}/{{total}})':
+    'Connectant als servidors MCP... ({{connected}}/{{total}})',
+  'Type your message or @path/to/file':
+    'Escriviu el vostre missatge o @camí/al/fitxer',
+  '? for shortcuts': '? per a dreceres',
+  "Press 'i' for INSERT mode and 'Esc' for NORMAL mode.":
+    "Premeu 'i' per al mode INSERCIÓ i 'Esc' per al mode NORMAL.",
+  'Cancel operation / Clear input (double press)':
+    'Cancel·lar operació / Esborrar entrada (doble premuda)',
+  'Cycle approval modes': "Canviar els modes d'aprovació",
+  'Cycle through your prompt history': "Navegar per l'historial de missatges",
+  'For a full list of shortcuts, see {{docPath}}':
+    'Per a una llista completa de dreceres, vegeu {{docPath}}',
+  'docs/keyboard-shortcuts.md': 'docs/keyboard-shortcuts.md',
+  'for help on Qwen Code': 'per a ajuda sobre Qwen Code',
+  'show version info': 'mostrar informació de la versió',
+  'submit a bug report': "enviar un informe d'error",
+  'About Qwen Code': 'Sobre Qwen Code',
+  Status: 'Estat',
+
+  // ============================================================================
+  // Informació del sistema
+  // ============================================================================
+  'Qwen Code': 'Qwen Code',
+  Runtime: "Entorn d'execució",
+  OS: 'SO',
+  Auth: 'Autenticació',
+  'CLI Version': 'Versió del CLI',
+  'Git Commit': 'Commit de Git',
+  Model: 'Model',
+  'Fast Model': 'Model ràpid',
+  Sandbox: 'Entorn aïllat',
+  'OS Platform': 'Plataforma del SO',
+  'OS Arch': 'Arquitectura del SO',
+  'OS Release': 'Versió del SO',
+  'Node.js Version': 'Versió de Node.js',
+  'NPM Version': 'Versió de NPM',
+  'Session ID': 'ID de sessió',
+  'Auth Method': "Mètode d'autenticació",
+  'Base URL': 'URL base',
+  Proxy: 'Proxy',
+  'Memory Usage': 'Ús de memòria',
+  'IDE Client': 'Client IDE',
+
+  // ============================================================================
+  // Ordres - General
+  // ============================================================================
+  'Analyzes the project and creates a tailored QWEN.md file.':
+    'Analitza el projecte i crea un fitxer QWEN.md personalitzat.',
+  'List available Qwen Code tools. Usage: /tools [desc]':
+    'Llistar les eines disponibles de Qwen Code. Ús: /tools [desc]',
+  'List available skills.': 'Llistar les habilitats disponibles.',
+  'Available Qwen Code CLI tools:': 'Eines del CLI de Qwen Code disponibles:',
+  'No tools available': 'No hi ha eines disponibles',
+  'View or change the approval mode for tool usage':
+    "Veure o canviar el mode d'aprovació per a l'ús d'eines",
+  'Invalid approval mode "{{arg}}". Valid modes: {{modes}}':
+    'Mode d\'aprovació no vàlid "{{arg}}". Modes vàlids: {{modes}}',
+  'Approval mode set to "{{mode}}"': 'Mode d\'aprovació establert a "{{mode}}"',
+  'View or change the language setting':
+    "Veure o canviar la configuració d'idioma",
+  'change the theme': 'canviar el tema',
+  'Select Theme': 'Seleccionar tema',
+  Preview: 'Previsualització',
+  '(Use Enter to select, Tab to configure scope)':
+    "(Useu Retorn per seleccionar, Tab per configurar l'àmbit)",
+  '(Use Enter to apply scope, Tab to go back)':
+    "(Useu Retorn per aplicar l'àmbit, Tab per tornar enrere)",
+  'Theme configuration unavailable due to NO_COLOR env variable.':
+    "La configuració del tema no està disponible degut a la variable d'entorn NO_COLOR.",
+  'Theme "{{themeName}}" not found.': 'Tema "{{themeName}}" no trobat.',
+  'Theme "{{themeName}}" not found in selected scope.':
+    'Tema "{{themeName}}" no trobat en l\'àmbit seleccionat.',
+  'Clear conversation history and free up context':
+    "Esborrar l'historial de la conversa i alliberar context",
+  'Compresses the context by replacing it with a summary.':
+    'Comprimeix el context substituint-lo per un resum.',
+  'open full Qwen Code documentation in your browser':
+    'obrir la documentació completa de Qwen Code al navegador',
+  'Configuration not available.': 'Configuració no disponible.',
+  'change the auth method': "canviar el mètode d'autenticació",
+  'Configure authentication information for login':
+    "Configurar la informació d'autenticació per a iniciar sessió",
+  'Copy the last result or code snippet to clipboard':
+    "Copiar l'últim resultat o fragment de codi al porta-retalls",
+
+  // ============================================================================
+  // Ordres - Agents
+  // ============================================================================
+  'Manage subagents for specialized task delegation.':
+    'Gestionar subagents per a la delegació de tasques especialitzades.',
+  'Manage existing subagents (view, edit, delete).':
+    'Gestionar subagents existents (veure, editar, eliminar).',
+  'Create a new subagent with guided setup.':
+    'Crear un nou subagent amb configuració guiada.',
+
+  // ============================================================================
+  // Agents - Diàleg de gestió
+  // ============================================================================
+  Agents: 'Agents',
+  'Choose Action': 'Triar acció',
+  'Edit {{name}}': 'Editar {{name}}',
+  'Edit Tools: {{name}}': 'Editar eines: {{name}}',
+  'Edit Color: {{name}}': 'Editar color: {{name}}',
+  'Delete {{name}}': 'Eliminar {{name}}',
+  'Unknown Step': 'Pas desconegut',
+  'Esc to close': 'Esc per tancar',
+  'Enter to select, ↑↓ to navigate, Esc to close':
+    'Retorn per seleccionar, ↑↓ per navegar, Esc per tancar',
+  'Esc to go back': 'Esc per tornar enrere',
+  'Enter to confirm, Esc to cancel': 'Retorn per confirmar, Esc per cancel·lar',
+  'Enter to select, ↑↓ to navigate, Esc to go back':
+    'Retorn per seleccionar, ↑↓ per navegar, Esc per tornar enrere',
+  'Enter to submit, Esc to go back': 'Retorn per enviar, Esc per tornar enrere',
+  'Invalid step: {{step}}': 'Pas no vàlid: {{step}}',
+  'No subagents found.': "No s'han trobat subagents.",
+  "Use '/agents create' to create your first subagent.":
+    "Useu '/agents create' per crear el vostre primer subagent.",
+  '(built-in)': '(integrat)',
+  '(overridden by project level agent)':
+    '(sobreescrit per un agent de nivell de projecte)',
+  'Project Level ({{path}})': 'Nivell de projecte ({{path}})',
+  'User Level ({{path}})': "Nivell d'usuari ({{path}})",
+  'Built-in Agents': 'Agents integrats',
+  'Extension Agents': "Agents d'extensió",
+  'Using: {{count}} agents': 'En ús: {{count}} agents',
+  'View Agent': 'Veure agent',
+  'Edit Agent': 'Editar agent',
+  'Delete Agent': 'Eliminar agent',
+  Back: 'Enrere',
+  'No agent selected': 'Cap agent seleccionat',
+  'File Path: ': 'Camí del fitxer: ',
+  'Tools: ': 'Eines: ',
+  'Color: ': 'Color: ',
+  'Description:': 'Descripció:',
+  'System Prompt:': 'Missatge del sistema:',
+  'Open in editor': "Obrir a l'editor",
+  'Edit tools': 'Editar eines',
+  'Edit color': 'Editar color',
+  '❌ Error:': '❌ Error:',
+  'Are you sure you want to delete agent "{{name}}"?':
+    'Esteu segur que voleu eliminar l\'agent "{{name}}"?',
+
+  // ============================================================================
+  // Agents - Assistent de creació
+  // ============================================================================
+  'Project Level (.qwen/agents/)': 'Nivell de projecte (.qwen/agents/)',
+  'User Level (~/.qwen/agents/)': "Nivell d'usuari (~/.qwen/agents/)",
+  '✅ Subagent Created Successfully!': '✅ Subagent creat correctament!',
+  'Subagent "{{name}}" has been saved to {{level}} level.':
+    'El subagent "{{name}}" s\'ha desat al nivell {{level}}.',
+  'Name: ': 'Nom: ',
+  'Location: ': 'Ubicació: ',
+  '❌ Error saving subagent:': '❌ Error en desar el subagent:',
+  'Warnings:': 'Advertències:',
+  'Name "{{name}}" already exists at {{level}} level - will overwrite existing subagent':
+    'El nom "{{name}}" ja existeix al nivell {{level}} - sobreescriurà el subagent existent',
+  'Name "{{name}}" exists at user level - project level will take precedence':
+    'El nom "{{name}}" existeix al nivell d\'usuari - el nivell de projecte tindrà prioritat',
+  'Name "{{name}}" exists at project level - existing subagent will take precedence':
+    'El nom "{{name}}" existeix al nivell de projecte - el subagent existent tindrà prioritat',
+  'Description is over {{length}} characters':
+    'La descripció supera els {{length}} caràcters',
+  'System prompt is over {{length}} characters':
+    'El missatge del sistema supera els {{length}} caràcters',
+  'Step {{n}}: Choose Location': 'Pas {{n}}: Triar ubicació',
+  'Step {{n}}: Choose Generation Method':
+    'Pas {{n}}: Triar mètode de generació',
+  'Generate with Qwen Code (Recommended)': 'Generar amb Qwen Code (Recomanat)',
+  'Manual Creation': 'Creació manual',
+  'Describe what this subagent should do and when it should be used. (Be comprehensive for best results)':
+    "Descriviu què ha de fer aquest subagent i quan s'ha d'usar. (Sigueu exhaustiu per obtenir els millors resultats)",
+  'e.g., Expert code reviewer that reviews code based on best practices...':
+    'p. ex., Revisor de codi expert que revisa el codi seguint les millors pràctiques...',
+  'Generating subagent configuration...':
+    'Generant la configuració del subagent...',
+  'Failed to generate subagent: {{error}}':
+    'Error en generar el subagent: {{error}}',
+  'Step {{n}}: Describe Your Subagent':
+    'Pas {{n}}: Descriure el vostre subagent',
+  'Step {{n}}: Enter Subagent Name': 'Pas {{n}}: Introduir el nom del subagent',
+  'Step {{n}}: Enter System Prompt':
+    'Pas {{n}}: Introduir el missatge del sistema',
+  'Step {{n}}: Enter Description': 'Pas {{n}}: Introduir la descripció',
+  'Step {{n}}: Select Tools': 'Pas {{n}}: Seleccionar eines',
+  'All Tools (Default)': 'Totes les eines (per defecte)',
+  'All Tools': 'Totes les eines',
+  'Read-only Tools': 'Eines de només lectura',
+  'Read & Edit Tools': 'Eines de lectura i edició',
+  'Read & Edit & Execution Tools': 'Eines de lectura, edició i execució',
+  'All tools selected, including MCP tools':
+    'Totes les eines seleccionades, incloses les eines MCP',
+  'Selected tools:': 'Eines seleccionades:',
+  'Read-only tools:': 'Eines de només lectura:',
+  'Edit tools:': "Eines d'edició:",
+  'Execution tools:': "Eines d'execució:",
+  'Step {{n}}: Choose Background Color': 'Pas {{n}}: Triar el color de fons',
+  'Step {{n}}: Confirm and Save': 'Pas {{n}}: Confirmar i desar',
+  'Esc to cancel': 'Esc per cancel·lar',
+  'Press Enter to save, e to save and edit, Esc to go back':
+    'Premeu Retorn per desar, e per desar i editar, Esc per tornar enrere',
+  'Press Enter to continue, {{navigation}}Esc to {{action}}':
+    'Premeu Retorn per continuar, {{navigation}}Esc per {{action}}',
+  cancel: 'cancel·lar',
+  'go back': 'tornar enrere',
+  '↑↓ to navigate, ': '↑↓ per navegar, ',
+  'Enter a clear, unique name for this subagent.':
+    'Introduïu un nom clar i únic per a aquest subagent.',
+  'e.g., Code Reviewer': 'p. ex., Revisor de codi',
+  'Name cannot be empty.': 'El nom no pot estar buit.',
+  "Write the system prompt that defines this subagent's behavior. Be comprehensive for best results.":
+    "Escriviu el missatge del sistema que defineix el comportament d'aquest subagent. Sigueu exhaustiu per obtenir els millors resultats.",
+  'e.g., You are an expert code reviewer...':
+    'p. ex., Sou un revisor de codi expert...',
+  'System prompt cannot be empty.':
+    'El missatge del sistema no pot estar buit.',
+  'Describe when and how this subagent should be used.':
+    "Descriviu quan i com s'ha d'usar aquest subagent.",
+  'e.g., Reviews code for best practices and potential bugs.':
+    'p. ex., Revisa el codi seguint les millors pràctiques i detectant errors potencials.',
+  'Description cannot be empty.': 'La descripció no pot estar buida.',
+  'Failed to launch editor: {{error}}': "Error en iniciar l'editor: {{error}}",
+  'Failed to save and edit subagent: {{error}}':
+    'Error en desar i editar el subagent: {{error}}',
+
+  // ============================================================================
+  // Extensions - Diàleg de gestió
+  // ============================================================================
+  'Manage Extensions': 'Gestionar extensions',
+  'Extension Details': "Detalls de l'extensió",
+  'View Extension': "Veure l'extensió",
+  'Update Extension': "Actualitzar l'extensió",
+  'Disable Extension': "Desactivar l'extensió",
+  'Enable Extension': "Activar l'extensió",
+  'Uninstall Extension': "Desinstal·lar l'extensió",
+  'Select Scope': "Seleccionar l'àmbit",
+  'User Scope': "Àmbit d'usuari",
+  'Workspace Scope': "Àmbit de l'espai de treball",
+  'No extensions found.': "No s'han trobat extensions.",
+  Active: 'Activa',
+  Disabled: 'Desactivada',
+  'Update available': 'Actualització disponible',
+  'Up to date': 'Al dia',
+  'Checking...': 'Comprovant...',
+  'Updating...': 'Actualitzant...',
+  Unknown: 'Desconegut',
+  Error: 'Error',
+  'Version:': 'Versió:',
+  'Status:': 'Estat:',
+  'Are you sure you want to uninstall extension "{{name}}"?':
+    'Esteu segur que voleu desinstal·lar l\'extensió "{{name}}"?',
+  'This action cannot be undone.': 'Aquesta acció no es pot desfer.',
+  'Extension "{{name}}" disabled successfully.':
+    'L\'extensió "{{name}}" s\'ha desactivat correctament.',
+  'Extension "{{name}}" enabled successfully.':
+    'L\'extensió "{{name}}" s\'ha activat correctament.',
+  'Extension "{{name}}" updated successfully.':
+    'L\'extensió "{{name}}" s\'ha actualitzat correctament.',
+  'Failed to update extension "{{name}}": {{error}}':
+    'Error en actualitzar l\'extensió "{{name}}": {{error}}',
+  'Select the scope for this action:':
+    "Seleccioneu l'àmbit per a aquesta acció:",
+  'User - Applies to all projects': "Usuari - S'aplica a tots els projectes",
+  'Workspace - Applies to current project only':
+    "Espai de treball - S'aplica només al projecte actual",
+  'Name:': 'Nom:',
+  'MCP Servers:': 'Servidors MCP:',
+  'Settings:': 'Configuració:',
+  active: 'activa',
+  disabled: 'desactivada',
+  'View Details': 'Veure detalls',
+  'Update failed:': "Error en l'actualització:",
+  'Updating {{name}}...': 'Actualitzant {{name}}...',
+  'Update complete!': 'Actualització completada!',
+  'User (global)': 'Usuari (global)',
+  'Workspace (project-specific)': 'Espai de treball (específic del projecte)',
+  'Disable "{{name}}" - Select Scope':
+    'Desactivar "{{name}}" - Seleccionar àmbit',
+  'Enable "{{name}}" - Select Scope': 'Activar "{{name}}" - Seleccionar àmbit',
+  'No extension selected': 'Cap extensió seleccionada',
+  'Press Y/Enter to confirm, N/Esc to cancel':
+    'Premeu Y/Retorn per confirmar, N/Esc per cancel·lar',
+  'Y/Enter to confirm, N/Esc to cancel':
+    'Y/Retorn per confirmar, N/Esc per cancel·lar',
+  '{{count}} extensions installed': '{{count}} extensions instal·lades',
+  "Use '/extensions install' to install your first extension.":
+    "Useu '/extensions install' per instal·lar la vostra primera extensió.",
+  'up to date': 'al dia',
+  'update available': 'actualització disponible',
+  'checking...': 'comprovant...',
+  'not updatable': 'no actualitzable',
+  error: 'error',
+
+  // ============================================================================
+  // Ordres - General (continuació)
+  // ============================================================================
+  'View and edit Qwen Code settings':
+    'Veure i editar la configuració de Qwen Code',
+  Settings: 'Configuració',
+  'To see changes, Qwen Code must be restarted. Press r to exit and apply changes now.':
+    'Per veure els canvis, cal reiniciar Qwen Code. Premeu r per sortir i aplicar els canvis ara.',
+  'The command "/{{command}}" is not supported in non-interactive mode.':
+    'L\'ordre "/{{command}}" no és compatible en mode no interactiu.',
+
+  // ============================================================================
+  // Etiquetes de configuració
+  // ============================================================================
+  'Vim Mode': 'Mode Vim',
+  'Disable Auto Update': 'Desactivar actualització automàtica',
+  'Attribution: commit': 'Atribució: commit',
+  'Terminal Bell Notification': 'Notificació de campana del terminal',
+  'Enable Usage Statistics': "Activar estadístiques d'ús",
+  Theme: 'Tema',
+  'Preferred Editor': 'Editor preferit',
+  'Auto-connect to IDE': 'Connexió automàtica a IDE',
+  'Enable Prompt Completion': 'Activar la compleció de missatges',
+  'Debug Keystroke Logging': 'Registre de tecles per a depuració',
+  'Language: UI': 'Idioma: Interfície',
+  'Language: Model': 'Idioma: Model',
+  'Output Format': 'Format de sortida',
+  'Hide Window Title': 'Amagar el títol de la finestra',
+  'Show Status in Title': "Mostrar l'estat al títol",
+  'Hide Tips': 'Amagar consells',
+  'Show Line Numbers in Code': 'Mostrar números de línia al codi',
+  'Show Citations': 'Mostrar cites',
+  'Custom Witty Phrases': 'Frases enginyoses personalitzades',
+  'Show Welcome Back Dialog': 'Mostrar el diàleg de benvinguda',
+  'Enable User Feedback': 'Activar les valoracions dels usuaris',
+  'How is Qwen doing this session? (optional)':
+    'Com va Qwen en aquesta sessió? (opcional)',
+  Bad: 'Malament',
+  Fine: 'Bé',
+  Good: 'Molt bé',
+  Dismiss: 'Descartar',
+  'Not Sure Yet': 'Encara no estic segur',
+  'Any other key': 'Qualsevol altra tecla',
+  'Disable Loading Phrases': 'Desactivar frases de càrrega',
+  'Screen Reader Mode': 'Mode de lector de pantalla',
+  'IDE Mode': 'Mode IDE',
+  'Max Session Turns': 'Torns màxims de sessió',
+  'Skip Next Speaker Check': 'Ometre la comprovació del proper parlant',
+  'Skip Loop Detection': 'Ometre la detecció de bucles',
+  'Skip Startup Context': "Ometre el context d'inici",
+  'Enable OpenAI Logging': "Activar el registre d'OpenAI",
+  'OpenAI Logging Directory': "Directori de registres d'OpenAI",
+  Timeout: "Temps d'espera",
+  'Max Retries': 'Reintents màxims',
+  'Disable Cache Control': 'Desactivar el control de memòria cau',
+  'Memory Discovery Max Dirs': 'Directoris màxims de descoberta de memòria',
+  'Load Memory From Include Directories':
+    'Carregar memòria des dels directoris inclosos',
+  'Respect .gitignore': 'Respectar .gitignore',
+  'Respect .qwenignore': 'Respectar .qwenignore',
+  'Enable Recursive File Search': 'Activar la cerca recursiva de fitxers',
+  'Disable Fuzzy Search': 'Desactivar la cerca difusa',
+  'Interactive Shell (PTY)': 'Shell interactiva (PTY)',
+  'Show Color': 'Mostrar color',
+  'Auto Accept': 'Acceptació automàtica',
+  'Use Ripgrep': 'Usar Ripgrep',
+  'Use Builtin Ripgrep': 'Usar Ripgrep integrat',
+  'Enable Tool Output Truncation':
+    "Activar el truncament de la sortida d'eines",
+  'Tool Output Truncation Threshold':
+    "Llindar de truncament de la sortida d'eines",
+  'Tool Output Truncation Lines': "Línies de truncament de la sortida d'eines",
+  'Folder Trust': 'Confiança de carpeta',
+  'Vision Model Preview': 'Previsualització del model de visió',
+  'Tool Schema Compliance': "Compliment de l'esquema d'eines",
+  'Auto (detect from system)': 'Automàtic (detectar del sistema)',
+  'Auto (detect terminal theme)': 'Automàtic (detectar el tema del terminal)',
+  Auto: 'Automàtic',
+  Text: 'Text',
+  JSON: 'JSON',
+  Plan: 'Planificació',
+  Default: 'Per defecte',
+  'Auto Edit': 'Edició automàtica',
+  YOLO: 'YOLO',
+  'toggle vim mode on/off': 'activar/desactivar el mode Vim',
+  'check session stats. Usage: /stats [model|tools]':
+    'comprovar les estadístiques de la sessió. Ús: /stats [model|tools]',
+  'Show model-specific usage statistics.':
+    "Mostrar les estadístiques d'ús específiques del model.",
+  'Show tool-specific usage statistics.':
+    "Mostrar les estadístiques d'ús específiques de les eines.",
+  'exit the cli': 'sortir del CLI',
+  'Open MCP management dialog, or authenticate with OAuth-enabled servers':
+    'Obrir el diàleg de gestió MCP o autenticar-se amb servidors OAuth',
+  'List configured MCP servers and tools, or authenticate with OAuth-enabled servers':
+    'Llistar els servidors MCP configurats i les seves eines, o autenticar-se amb servidors OAuth',
+  'Manage workspace directories':
+    "Gestionar els directoris de l'espai de treball",
+  'Add directories to the workspace. Use comma to separate multiple paths':
+    "Afegir directoris a l'espai de treball. Useu comes per separar múltiples camins",
+  'Show all directories in the workspace':
+    "Mostrar tots els directoris de l'espai de treball",
+  'set external editor preference': "establir la preferència d'editor extern",
+  'Select Editor': 'Seleccionar editor',
+  'Editor Preference': "Preferència d'editor",
+  'These editors are currently supported. Please note that some editors cannot be used in sandbox mode.':
+    'Aquests editors estan suportats. Cal tenir en compte que alguns editors no es poden usar en mode aïllat.',
+  'Your preferred editor is:': 'El vostre editor preferit és:',
+  'Manage extensions': 'Gestionar extensions',
+  'Manage installed extensions': 'Gestionar les extensions instal·lades',
+  'List active extensions': 'Llistar les extensions actives',
+  'Update extensions. Usage: update <extension-names>|--all':
+    "Actualitzar extensions. Ús: update <noms-d'extensions>|--all",
+  'Disable an extension': 'Desactivar una extensió',
+  'Enable an extension': 'Activar una extensió',
+  'Install an extension from a git repo or local path':
+    "Instal·lar una extensió des d'un repositori git o camí local",
+  'Uninstall an extension': 'Desinstal·lar una extensió',
+  'No extensions installed.': 'No hi ha extensions instal·lades.',
+  'Usage: /extensions update <extension-names>|--all':
+    "Ús: /extensions update <noms-d'extensions>|--all",
+  'Extension "{{name}}" not found.': 'Extensió "{{name}}" no trobada.',
+  'No extensions to update.': 'No hi ha extensions per actualitzar.',
+  'Usage: /extensions install <source>': 'Ús: /extensions install <font>',
+  'Installing extension from "{{source}}"...':
+    'Instal·lant extensió des de "{{source}}"...',
+  'Extension "{{name}}" installed successfully.':
+    'L\'extensió "{{name}}" s\'ha instal·lat correctament.',
+  'Failed to install extension from "{{source}}": {{error}}':
+    'Error en instal·lar l\'extensió des de "{{source}}": {{error}}',
+  'Usage: /extensions uninstall <extension-name>':
+    "Ús: /extensions uninstall <nom-de-l'extensió>",
+  'Uninstalling extension "{{name}}"...':
+    'Desinstal·lant l\'extensió "{{name}}"...',
+  'Extension "{{name}}" uninstalled successfully.':
+    'L\'extensió "{{name}}" s\'ha desinstal·lat correctament.',
+  'Failed to uninstall extension "{{name}}": {{error}}':
+    'Error en desinstal·lar l\'extensió "{{name}}": {{error}}',
+  'Usage: /extensions {{command}} <extension> [--scope=<user|workspace>]':
+    'Ús: /extensions {{command}} <extensió> [--scope=<user|workspace>]',
+  'Unsupported scope "{{scope}}", should be one of "user" or "workspace"':
+    'Àmbit no suportat "{{scope}}", ha de ser "user" o "workspace"',
+  'Extension "{{name}}" disabled for scope "{{scope}}"':
+    'L\'extensió "{{name}}" desactivada per a l\'àmbit "{{scope}}"',
+  'Extension "{{name}}" enabled for scope "{{scope}}"':
+    'L\'extensió "{{name}}" activada per a l\'àmbit "{{scope}}"',
+  'Do you want to continue? [Y/n]: ': 'Voleu continuar? [S/n]: ',
+  'Do you want to continue?': 'Voleu continuar?',
+  'Installing extension "{{name}}".': 'Instal·lant l\'extensió "{{name}}".',
+  '**Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.**':
+    "**Les extensions poden introduir comportaments inesperats. Assegureu-vos d'haver investigat la font de l'extensió i de confiar en l'autor.**",
+  'This extension will run the following MCP servers:':
+    'Aquesta extensió executarà els servidors MCP següents:',
+  local: 'local',
+  remote: 'remot',
+  'This extension will add the following commands: {{commands}}.':
+    'Aquesta extensió afegirà les ordres següents: {{commands}}.',
+  'This extension will append info to your QWEN.md context using {{fileName}}':
+    'Aquesta extensió afegirà informació al vostre context QWEN.md usant {{fileName}}',
+  'This extension will exclude the following core tools: {{tools}}':
+    'Aquesta extensió exclourà les eines principals següents: {{tools}}',
+  'This extension will install the following skills:':
+    'Aquesta extensió instal·larà les habilitats següents:',
+  'This extension will install the following subagents:':
+    'Aquesta extensió instal·larà els subagents següents:',
+  'Installation cancelled for "{{name}}".':
+    'Instal·lació cancel·lada per a "{{name}}".',
+  'You are installing an extension from {{originSource}}. Some features may not work perfectly with Qwen Code.':
+    'Esteu instal·lant una extensió des de {{originSource}}. Algunes funcions poden no funcionar perfectament amb Qwen Code.',
+  '--ref and --auto-update are not applicable for marketplace extensions.':
+    "--ref i --auto-update no s'apliquen a les extensions del mercat.",
+  'Extension "{{name}}" installed successfully and enabled.':
+    'L\'extensió "{{name}}" s\'ha instal·lat i activat correctament.',
+  'Installs an extension from a git repository URL, local path, or claude marketplace (marketplace-url:plugin-name).':
+    "Instal·la una extensió des d'una URL de repositori git, un camí local o el mercat (marketplace-url:nom-del-connector).",
+  'The github URL, local path, or marketplace source (marketplace-url:plugin-name) of the extension to install.':
+    "La URL de GitHub, el camí local o la font del mercat (marketplace-url:nom-del-connector) de l'extensió a instal·lar.",
+  'The git ref to install from.':
+    'La referència git des de la qual instal·lar.',
+  'Enable auto-update for this extension.':
+    "Activar l'actualització automàtica per a aquesta extensió.",
+  'Enable pre-release versions for this extension.':
+    'Activar les versions preliminars per a aquesta extensió.',
+  'Acknowledge the security risks of installing an extension and skip the confirmation prompt.':
+    "Acceptar els riscos de seguretat d'instal·lar una extensió i ometre el missatge de confirmació.",
+  'The source argument must be provided.': "Cal proporcionar l'argument font.",
+  'Extension "{{name}}" successfully uninstalled.':
+    'L\'extensió "{{name}}" s\'ha desinstal·lat correctament.',
+  'Uninstalls an extension.': 'Desinstal·la una extensió.',
+  'The name or source path of the extension to uninstall.':
+    "El nom o camí font de l'extensió a desinstal·lar.",
+  'Please include the name of the extension to uninstall as a positional argument.':
+    "Incloeu el nom de l'extensió a desinstal·lar com a argument posicional.",
+  'Enables an extension.': 'Activa una extensió.',
+  'The name of the extension to enable.': "El nom de l'extensió a activar.",
+  'The scope to enable the extenison in. If not set, will be enabled in all scopes.':
+    "L'àmbit en el qual activar l'extensió. Si no s'estableix, s'activarà en tots els àmbits.",
+  'Extension "{{name}}" successfully enabled for scope "{{scope}}".':
+    'L\'extensió "{{name}}" s\'ha activat correctament per a l\'àmbit "{{scope}}".',
+  'Extension "{{name}}" successfully enabled in all scopes.':
+    'L\'extensió "{{name}}" s\'ha activat correctament en tots els àmbits.',
+  'Invalid scope: {{scope}}. Please use one of {{scopes}}.':
+    'Àmbit no vàlid: {{scope}}. Useu un dels següents: {{scopes}}.',
+  'Disables an extension.': 'Desactiva una extensió.',
+  'The name of the extension to disable.': "El nom de l'extensió a desactivar.",
+  'The scope to disable the extenison in.':
+    "L'àmbit en el qual desactivar l'extensió.",
+  'Extension "{{name}}" successfully disabled for scope "{{scope}}".':
+    'L\'extensió "{{name}}" s\'ha desactivat correctament per a l\'àmbit "{{scope}}".',
+  'Extension "{{name}}" successfully updated: {{oldVersion}} → {{newVersion}}.':
+    'L\'extensió "{{name}}" s\'ha actualitzat correctament: {{oldVersion}} → {{newVersion}}.',
+  'Unable to install extension "{{name}}" due to missing install metadata':
+    'No es pot instal·lar l\'extensió "{{name}}" per manca de metadades d\'instal·lació',
+  'Extension "{{name}}" is already up to date.':
+    'L\'extensió "{{name}}" ja és al dia.',
+  'Updates all extensions or a named extension to the latest version.':
+    "Actualitza totes les extensions o una extensió específica a l'última versió.",
+  'Update all extensions.': 'Actualitzar totes les extensions.',
+  'The name of the extension to update.': "El nom de l'extensió a actualitzar.",
+  'Either an extension name or --all must be provided':
+    "Cal proporcionar un nom d'extensió o --all",
+  'Lists installed extensions.': 'Llista les extensions instal·lades.',
+  'Path:': 'Camí:',
+  'Source:': 'Font:',
+  'Type:': 'Tipus:',
+  'Ref:': 'Ref:',
+  'Release tag:': 'Etiqueta de versió:',
+  'Enabled (User):': 'Activada (Usuari):',
+  'Enabled (Workspace):': 'Activada (Espai de treball):',
+  'Context files:': 'Fitxers de context:',
+  'Skills:': 'Habilitats:',
+  'Agents:': 'Agents:',
+  'MCP servers:': 'Servidors MCP:',
+  'Link extension failed to install.':
+    "No s'ha pogut instal·lar l'extensió d'enllaç.",
+  'Extension "{{name}}" linked successfully and enabled.':
+    'L\'extensió "{{name}}" s\'ha enllaçat i activat correctament.',
+  'Links an extension from a local path. Updates made to the local path will always be reflected.':
+    "Enllaça una extensió des d'un camí local. Els canvis al camí local sempre es reflectiran.",
+  'The name of the extension to link.': "El nom de l'extensió a enllaçar.",
+  'Set a specific setting for an extension.':
+    'Establir una configuració específica per a una extensió.',
+  'Name of the extension to configure.': "Nom de l'extensió a configurar.",
+  'The setting to configure (name or env var).':
+    "La configuració a establir (nom o variable d'entorn).",
+  'The scope to set the setting in.': "L'àmbit on establir la configuració.",
+  'List all settings for an extension.':
+    "Llistar tota la configuració d'una extensió.",
+  'Name of the extension.': "Nom de l'extensió.",
+  'Extension "{{name}}" has no settings to configure.':
+    'L\'extensió "{{name}}" no té cap configuració.',
+  'Settings for "{{name}}":': 'Configuració per a "{{name}}":',
+  '(workspace)': '(espai de treball)',
+  '(user)': '(usuari)',
+  '[not set]': '[no establert]',
+  '[value stored in keychain]': '[valor emmagatzemat al clauer]',
+  'Value:': 'Valor:',
+  'Manage extension settings.': 'Gestionar la configuració de les extensions.',
+  'You need to specify a command (set or list).':
+    'Cal especificar una ordre (set o list).',
+
+  // ============================================================================
+  // Selecció de connector / Mercat
+  // ============================================================================
+  'No plugins available in this marketplace.':
+    'No hi ha connectors disponibles en aquest mercat.',
+  'Select a plugin to install from marketplace "{{name}}":':
+    'Seleccioneu un connector per instal·lar des del mercat "{{name}}":',
+  'Plugin selection cancelled.': 'Selecció de connector cancel·lada.',
+  'Select a plugin from "{{name}}"': 'Seleccionar un connector de "{{name}}"',
+  'Use ↑↓ or j/k to navigate, Enter to select, Escape to cancel':
+    'Useu ↑↓ o j/k per navegar, Retorn per seleccionar, Esc per cancel·lar',
+  '{{count}} more above': '{{count}} més amunt',
+  '{{count}} more below': '{{count}} més avall',
+  'manage IDE integration': "gestionar la integració de l'IDE",
+  'check status of IDE integration':
+    "comprovar l'estat de la integració de l'IDE",
+  'install required IDE companion for {{ideName}}':
+    'instal·lar el complement IDE necessari per a {{ideName}}',
+  'enable IDE integration': "activar la integració de l'IDE",
+  'disable IDE integration': "desactivar la integració de l'IDE",
+  'IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: VS Code or VS Code forks.':
+    "La integració de l'IDE no és compatible en el vostre entorn actual. Per usar aquesta funció, executeu Qwen Code en un dels IDEs compatibles: VS Code o bifurcacions de VS Code.",
+  'Set up GitHub Actions': 'Configurar GitHub Actions',
+  'Configure terminal keybindings for multiline input (VS Code, Cursor, Windsurf, Trae)':
+    'Configurar les dreceres del terminal per a entrada multilínia (VS Code, Cursor, Windsurf, Trae)',
+  'Please restart your terminal for the changes to take effect.':
+    'Reinicieu el terminal perquè els canvis tinguin efecte.',
+  'Failed to configure terminal: {{error}}':
+    'Error en configurar el terminal: {{error}}',
+  'Could not determine {{terminalName}} config path on Windows: APPDATA environment variable is not set.':
+    "No s'ha pogut determinar el camí de configuració de {{terminalName}} a Windows: la variable d'entorn APPDATA no està establerta.",
+  '{{terminalName}} keybindings.json exists but is not a valid JSON array. Please fix the file manually or delete it to allow automatic configuration.':
+    '{{terminalName}} keybindings.json existeix però no és un array JSON vàlid. Corregiu el fitxer manualment o elimineu-lo per permetre la configuració automàtica.',
+  'File: {{file}}': 'Fitxer: {{file}}',
+  'Failed to parse {{terminalName}} keybindings.json. The file contains invalid JSON. Please fix the file manually or delete it to allow automatic configuration.':
+    'Error en analitzar {{terminalName}} keybindings.json. El fitxer conté JSON no vàlid. Corregiu el fitxer manualment o elimineu-lo per permetre la configuració automàtica.',
+  'Error: {{error}}': 'Error: {{error}}',
+  'Shift+Enter binding already exists': 'La drecera Shift+Retorn ja existeix',
+  'Ctrl+Enter binding already exists': 'La drecera Ctrl+Retorn ja existeix',
+  'Existing keybindings detected. Will not modify to avoid conflicts.':
+    "S'han detectat dreceres existents. No es modificaran per evitar conflictes.",
+  'Please check and modify manually if needed: {{file}}':
+    'Comproveu i modifiqueu manualment si cal: {{file}}',
+  'Added Shift+Enter and Ctrl+Enter keybindings to {{terminalName}}.':
+    "S'han afegit les dreceres Shift+Retorn i Ctrl+Retorn a {{terminalName}}.",
+  'Modified: {{file}}': 'Modificat: {{file}}',
+  '{{terminalName}} keybindings already configured.':
+    'Les dreceres de {{terminalName}} ja estan configurades.',
+  'Failed to configure {{terminalName}}.':
+    'Error en configurar {{terminalName}}.',
+  'Your terminal is already configured for an optimal experience with multiline input (Shift+Enter and Ctrl+Enter).':
+    'El vostre terminal ja està configurat per a una experiència òptima amb entrada multilínia (Shift+Retorn i Ctrl+Retorn).',
+
+  // ============================================================================
+  // Ordres - Hooks
+  // ============================================================================
+  'Manage Qwen Code hooks': 'Gestionar els hooks de Qwen Code',
+  'List all configured hooks': 'Llistar tots els hooks configurats',
+  'Enable a disabled hook': 'Activar un hook desactivat',
+  'Disable an active hook': 'Desactivar un hook actiu',
+  Hooks: 'Hooks',
+  'Loading hooks...': 'Carregant hooks...',
+  'Error loading hooks:': 'Error en carregar els hooks:',
+  'Press Escape to close': 'Premeu Esc per tancar',
+  'Press Escape, Ctrl+C, or Ctrl+D to cancel':
+    'Premeu Esc, Ctrl+C o Ctrl+D per cancel·lar',
+  'Press Space, Enter, or Escape to dismiss':
+    'Premeu Espai, Retorn o Esc per descartar',
+  'No hook selected': 'Cap hook seleccionat',
+  'No hook events found.': "No s'han trobat esdeveniments de hook.",
+  '{{count}} hook configured': '{{count}} hook configurat',
+  '{{count}} hooks configured': '{{count}} hooks configurats',
+  'This menu is read-only. To add or modify hooks, edit settings.json directly or ask Qwen Code.':
+    'Aquest menú és de només lectura. Per afegir o modificar hooks, editeu settings.json directament o demaneu-ho a Qwen Code.',
+  'Enter to select · Esc to cancel':
+    'Retorn per seleccionar · Esc per cancel·lar',
+  'Exit codes:': 'Codis de sortida:',
+  'Configured hooks:': 'Hooks configurats:',
+  'No hooks configured for this event.':
+    'No hi ha hooks configurats per a aquest esdeveniment.',
+  'To add hooks, edit settings.json directly or ask Qwen.':
+    'Per afegir hooks, editeu settings.json directament o demaneu-ho a Qwen.',
+  'Enter to select · Esc to go back':
+    'Retorn per seleccionar · Esc per tornar enrere',
+  'Hook details': 'Detalls del hook',
+  'Event:': 'Esdeveniment:',
+  'Extension:': 'Extensió:',
+  'Desc:': 'Desc:',
+  'No hook config selected': 'Cap configuració de hook seleccionada',
+  'To modify or remove this hook, edit settings.json directly or ask Qwen to help.':
+    'Per modificar o eliminar aquest hook, editeu settings.json directament o demaneu ajuda a Qwen.',
+  'Hook Configuration - Disabled': 'Configuració de hooks - Desactivats',
+  'All hooks are currently disabled. You have {{count}} that are not running.':
+    'Tots els hooks estan desactivats. En teniu {{count}} que no estan en execució.',
+  '{{count}} configured hook': '{{count}} hook configurat',
+  '{{count}} configured hooks': '{{count}} hooks configurats',
+  'When hooks are disabled:': 'Quan els hooks estan desactivats:',
+  'No hook commands will execute': "Cap ordre de hook s'executarà",
+  'StatusLine will not be displayed': "La barra d'estat no es mostrarà",
+  'Tool operations will proceed without hook validation':
+    "Les operacions d'eines continuaran sense validació de hook",
+  'To re-enable hooks, remove "disableAllHooks" from settings.json or ask Qwen Code.':
+    'Per tornar a activar els hooks, elimineu "disableAllHooks" de settings.json o demaneu-ho a Qwen Code.',
+  Project: 'Projecte',
+  User: 'Usuari',
+  System: 'Sistema',
+  Extension: 'Extensió',
+  'Local Settings': 'Configuració local',
+  'User Settings': "Configuració d'usuari",
+  'System Settings': 'Configuració del sistema',
+  Extensions: 'Extensions',
+  'Session (temporary)': 'Sessió (temporal)',
+  '✓ Enabled': '✓ Activat',
+  '✗ Disabled': '✗ Desactivat',
+  'Before tool execution': "Abans de l'execució de l'eina",
+  'After tool execution': "Després de l'execució de l'eina",
+  'After tool execution fails': "Quan falla l'execució de l'eina",
+  'When notifications are sent': "Quan s'envien notificacions",
+  'When the user submits a prompt': "Quan l'usuari envia un missatge",
+  'When a new session is started': "Quan s'inicia una nova sessió",
+  'Right before Qwen Code concludes its response':
+    'Immediatament abans que Qwen Code conclou la seva resposta',
+  'When a subagent (Agent tool call) is started':
+    "Quan s'inicia un subagent (crida a l'eina Agent)",
+  'Right before a subagent concludes its response':
+    'Immediatament abans que un subagent conclou la seva resposta',
+  'Before conversation compaction': 'Abans de la compactació de la conversa',
+  'When a session is ending': "Quan una sessió s'està acabant",
+  'When a permission dialog is displayed':
+    'Quan es mostra un diàleg de permisos',
+  'Input to command is JSON of tool call arguments.':
+    "L'entrada a l'ordre és JSON dels arguments de la crida a l'eina.",
+  'Input to command is JSON with fields "inputs" (tool call arguments) and "response" (tool call response).':
+    'L\'entrada a l\'ordre és JSON amb els camps "inputs" (arguments de la crida a l\'eina) i "response" (resposta de la crida a l\'eina).',
+  'Input to command is JSON with tool_name, tool_input, tool_use_id, error, error_type, is_interrupt, and is_timeout.':
+    "L'entrada a l'ordre és JSON amb tool_name, tool_input, tool_use_id, error, error_type, is_interrupt i is_timeout.",
+  'Input to command is JSON with notification message and type.':
+    "L'entrada a l'ordre és JSON amb el missatge de notificació i el tipus.",
+  'Input to command is JSON with original user prompt text.':
+    "L'entrada a l'ordre és JSON amb el text original del missatge de l'usuari.",
+  'Input to command is JSON with session start source.':
+    "L'entrada a l'ordre és JSON amb la font d'inici de sessió.",
+  'Input to command is JSON with session end reason.':
+    "L'entrada a l'ordre és JSON amb el motiu de fi de sessió.",
+  'Input to command is JSON with agent_id and agent_type.':
+    "L'entrada a l'ordre és JSON amb agent_id i agent_type.",
+  'Input to command is JSON with agent_id, agent_type, and agent_transcript_path.':
+    "L'entrada a l'ordre és JSON amb agent_id, agent_type i agent_transcript_path.",
+  'Input to command is JSON with compaction details.':
+    "L'entrada a l'ordre és JSON amb els detalls de compactació.",
+  'Input to command is JSON with tool_name, tool_input, and tool_use_id. Output JSON with hookSpecificOutput containing decision to allow or deny.':
+    "L'entrada a l'ordre és JSON amb tool_name, tool_input i tool_use_id. La sortida JSON amb hookSpecificOutput conté la decisió de permetre o denegar.",
+  'stdout/stderr not shown': 'stdout/stderr no es mostra',
+  'show stderr to model and continue conversation':
+    'mostrar stderr al model i continuar la conversa',
+  'show stderr to user only': "mostrar stderr només a l'usuari",
+  'stdout shown in transcript mode (ctrl+o)':
+    'stdout mostrat en mode transcripció (ctrl+o)',
+  'show stderr to model immediately': 'mostrar stderr al model immediatament',
+  'show stderr to user only but continue with tool call':
+    "mostrar stderr només a l'usuari però continuar amb la crida a l'eina",
+  'block processing, erase original prompt, and show stderr to user only':
+    "blocar el processament, esborrar el missatge original i mostrar stderr només a l'usuari",
+  'stdout shown to Qwen': 'stdout mostrat a Qwen',
+  'show stderr to user only (blocking errors ignored)':
+    "mostrar stderr només a l'usuari (errors de bloqueig ignorats)",
+  'command completes successfully': "l'ordre es completa correctament",
+  'stdout shown to subagent': 'stdout mostrat al subagent',
+  'show stderr to subagent and continue having it run':
+    'mostrar stderr al subagent i continuar la seva execució',
+  'stdout appended as custom compact instructions':
+    'stdout afegit com a instruccions compactes personalitzades',
+  'block compaction': 'blocar la compactació',
+  'show stderr to user only but continue with compaction':
+    "mostrar stderr només a l'usuari però continuar amb la compactació",
+  'use hook decision if provided': 'usar la decisió del hook si es proporciona',
+  'Config not loaded.': 'Configuració no carregada.',
+  'Hooks are not enabled. Enable hooks in settings to use this feature.':
+    'Els hooks no estan activats. Activeu els hooks a la configuració per usar aquesta funció.',
+  'No hooks configured. Add hooks in your settings.json file.':
+    'No hi ha hooks configurats. Afegiu hooks al vostre fitxer settings.json.',
+  'Configured Hooks ({{count}} total)':
+    'Hooks configurats ({{count}} en total)',
+
+  // ============================================================================
+  // Ordres - Exportació de sessió
+  // ============================================================================
+  'Export current session message history to a file':
+    "Exportar l'historial de missatges de la sessió actual a un fitxer",
+  'Export session to HTML format': 'Exportar la sessió en format HTML',
+  'Export session to JSON format': 'Exportar la sessió en format JSON',
+  'Export session to JSONL format (one message per line)':
+    'Exportar la sessió en format JSONL (un missatge per línia)',
+  'Export session to markdown format': 'Exportar la sessió en format markdown',
+
+  // ============================================================================
+  // Ordres - Idees
+  // ============================================================================
+  'generate personalized programming insights from your chat history':
+    'generar idees de programació personalitzades a partir del vostre historial de xat',
+
+  // ============================================================================
+  // Ordres - Historial de sessió
+  // ============================================================================
+  'Resume a previous session': 'Reprendre una sessió anterior',
+  'Restore a tool call. This will reset the conversation and file history to the state it was in when the tool call was suggested':
+    "Restaurar una crida a una eina. Això restablirà la conversa i l'historial de fitxers a l'estat en què es trobaven quan es va suggerir la crida a l'eina",
+  'Could not detect terminal type. Supported terminals: VS Code, Cursor, Windsurf, and Trae.':
+    "No s'ha pogut detectar el tipus de terminal. Terminals compatibles: VS Code, Cursor, Windsurf i Trae.",
+  'Terminal "{{terminal}}" is not supported yet.':
+    'El terminal "{{terminal}}" no és compatible encara.',
+
+  // ============================================================================
+  // Ordres - Idioma
+  // ============================================================================
+  'Invalid language. Available: {{options}}':
+    'Idioma no vàlid. Disponibles: {{options}}',
+  'Language subcommands do not accept additional arguments.':
+    "Les subordres d'idioma no accepten arguments addicionals.",
+  'Current UI language: {{lang}}': 'Idioma actual de la interfície: {{lang}}',
+  'Current LLM output language: {{lang}}':
+    'Idioma actual de la sortida del model: {{lang}}',
+  'LLM output language not set': 'Idioma de sortida del model no establert',
+  'Set UI language': "Establir l'idioma de la interfície",
+  'Set LLM output language': "Establir l'idioma de sortida del model",
+  'Usage: /language ui [{{options}}]': 'Ús: /language ui [{{options}}]',
+  'Usage: /language output <language>': 'Ús: /language output <idioma>',
+  'Example: /language output 中文': 'Exemple: /language output 中文',
+  'Example: /language output English': 'Exemple: /language output English',
+  'Example: /language output 日本語': 'Exemple: /language output 日本語',
+  'Example: /language output Português': 'Exemple: /language output Português',
+  'UI language changed to {{lang}}':
+    'Idioma de la interfície canviat a {{lang}}',
+  'LLM output language set to {{lang}}':
+    'Idioma de sortida del model establert a {{lang}}',
+  'LLM output language rule file generated at {{path}}':
+    "Fitxer de regles d'idioma de sortida del model generat a {{path}}",
+  'Please restart the application for the changes to take effect.':
+    "Reinicieu l'aplicació perquè els canvis tinguin efecte.",
+  'Failed to generate LLM output language rule file: {{error}}':
+    "Error en generar el fitxer de regles d'idioma de sortida del model: {{error}}",
+  'Invalid command. Available subcommands:':
+    'Ordre no vàlida. Subordres disponibles:',
+  'Available subcommands:': 'Subordres disponibles:',
+  'To request additional UI language packs, please open an issue on GitHub.':
+    "Per sol·licitar paquets d'idioma addicionals per a la interfície, obriu una incidència a GitHub.",
+  'Available options:': 'Opcions disponibles:',
+  'Set UI language to {{name}}':
+    "Establir l'idioma de la interfície a {{name}}",
+
+  // ============================================================================
+  // Ordres - Mode d'aprovació
+  // ============================================================================
+  'Tool Approval Mode': "Mode d'aprovació d'eines",
+  'Current approval mode: {{mode}}': "Mode d'aprovació actual: {{mode}}",
+  'Available approval modes:': "Modes d'aprovació disponibles:",
+  'Approval mode changed to: {{mode}}': "Mode d'aprovació canviat a: {{mode}}",
+  'Approval mode changed to: {{mode}} (saved to {{scope}} settings{{location}})':
+    "Mode d'aprovació canviat a: {{mode}} (desat a la configuració {{scope}}{{location}})",
+  'Usage: /approval-mode <mode> [--session|--user|--project]':
+    'Ús: /approval-mode <mode> [--session|--user|--project]',
+  'Scope subcommands do not accept additional arguments.':
+    "Les subordres d'àmbit no accepten arguments addicionals.",
+  'Plan mode - Analyze only, do not modify files or execute commands':
+    'Mode de planificació - Analitzar només, sense modificar fitxers ni executar ordres',
+  'Default mode - Require approval for file edits or shell commands':
+    'Mode per defecte - Requerir aprovació per a edicions de fitxers o ordres shell',
+  'Auto-edit mode - Automatically approve file edits':
+    "Mode d'edició automàtica - Aprovar automàticament les edicions de fitxers",
+  'YOLO mode - Automatically approve all tools':
+    'Mode YOLO - Aprovar automàticament totes les eines',
+  '{{mode}} mode': 'Mode {{mode}}',
+  'Settings service is not available; unable to persist the approval mode.':
+    "El servei de configuració no està disponible; no es pot persistir el mode d'aprovació.",
+  'Failed to save approval mode: {{error}}':
+    "Error en desar el mode d'aprovació: {{error}}",
+  'Failed to change approval mode: {{error}}':
+    "Error en canviar el mode d'aprovació: {{error}}",
+  'Apply to current session only (temporary)':
+    'Aplicar només a la sessió actual (temporal)',
+  'Persist for this project/workspace':
+    'Persistir per a aquest projecte/espai de treball',
+  'Persist for this user on this machine':
+    'Persistir per a aquest usuari en aquesta màquina',
+  'Analyze only, do not modify files or execute commands':
+    'Analitzar només, sense modificar fitxers ni executar ordres',
+  'Require approval for file edits or shell commands':
+    'Requerir aprovació per a edicions de fitxers o ordres shell',
+  'Automatically approve file edits':
+    'Aprovar automàticament les edicions de fitxers',
+  'Automatically approve all tools': 'Aprovar automàticament totes les eines',
+  'Workspace approval mode exists and takes priority. User-level change will have no effect.':
+    "Existeix un mode d'aprovació de l'espai de treball i té prioritat. El canvi a nivell d'usuari no tindrà cap efecte.",
+  'Apply To': 'Aplicar a',
+  'Workspace Settings': "Configuració de l'espai de treball",
+
+  // ============================================================================
+  // Ordres - Memòria
+  // ============================================================================
+  'Commands for interacting with memory.':
+    'Ordres per interactuar amb la memòria.',
+  'Show the current memory contents.':
+    'Mostrar el contingut actual de la memòria.',
+  'Show project-level memory contents.':
+    'Mostrar el contingut de la memòria a nivell de projecte.',
+  'Show global memory contents.': 'Mostrar el contingut de la memòria global.',
+  'Add content to project-level memory.':
+    'Afegir contingut a la memòria a nivell de projecte.',
+  'Add content to global memory.': 'Afegir contingut a la memòria global.',
+  'Refresh the memory from the source.':
+    'Actualitzar la memòria des de la font.',
+  'Usage: /memory add --project <text to remember>':
+    'Ús: /memory add --project <text a recordar>',
+  'Usage: /memory add --global <text to remember>':
+    'Ús: /memory add --global <text a recordar>',
+  'Attempting to save to project memory: "{{text}}"':
+    'Intentant desar a la memòria del projecte: "{{text}}"',
+  'Attempting to save to global memory: "{{text}}"':
+    'Intentant desar a la memòria global: "{{text}}"',
+  'Current memory content from {{count}} file(s):':
+    'Contingut actual de la memòria de {{count}} fitxer(s):',
+  'Memory is currently empty.': 'La memòria és buida actualment.',
+  'Project memory file not found or is currently empty.':
+    "El fitxer de memòria del projecte no s'ha trobat o és buit.",
+  'Global memory file not found or is currently empty.':
+    "El fitxer de memòria global no s'ha trobat o és buit.",
+  'Global memory is currently empty.': 'La memòria global és buida actualment.',
+  'Global memory content:\n\n---\n{{content}}\n---':
+    'Contingut de la memòria global:\n\n---\n{{content}}\n---',
+  'Project memory content from {{path}}:\n\n---\n{{content}}\n---':
+    'Contingut de la memòria del projecte des de {{path}}:\n\n---\n{{content}}\n---',
+  'Project memory is currently empty.': 'La memòria del projecte és buida.',
+  'Refreshing memory from source files...':
+    'Actualitzant la memòria des dels fitxers font...',
+  'Add content to the memory. Use --global for global memory or --project for project memory.':
+    'Afegir contingut a la memòria. Useu --global per a la memòria global o --project per a la memòria del projecte.',
+  'Usage: /memory add [--global|--project] <text to remember>':
+    'Ús: /memory add [--global|--project] <text a recordar>',
+  'Attempting to save to memory {{scope}}: "{{fact}}"':
+    'Intentant desar a la memòria {{scope}}: "{{fact}}"',
+  'Open auto-memory folder': 'Obrir la carpeta de memòria automàtica',
+  'Auto-memory: {{status}}': 'Memòria automàtica: {{status}}',
+  'Auto-dream: {{status}} · {{lastDream}} · /dream to run':
+    'Auto-dream: {{status}} · {{lastDream}} · /dream per executar',
+  never: 'mai',
+  on: 'activada',
+  off: 'desactivada',
+  '✦ dreaming': '✦ somniant',
+  'Remove matching entries from managed auto-memory.':
+    'Eliminar les entrades coincidents de la memòria automàtica gestionada.',
+  'Usage: /forget <memory text to remove>':
+    'Ús: /forget <text de memòria a eliminar>',
+  'No managed auto-memory entries matched: {{query}}':
+    'Cap entrada de memòria automàtica gestionada coincideix: {{query}}',
+  'Show managed auto-memory status.':
+    "Mostrar l'estat de la memòria automàtica gestionada.",
+  'Run managed auto-memory extraction for the current session.':
+    "Executar l'extracció de memòria automàtica gestionada per a la sessió actual.",
+  'Managed auto-memory root: {{root}}':
+    'Arrel de la memòria automàtica gestionada: {{root}}',
+  'Managed auto-memory topics:': 'Temes de la memòria automàtica gestionada:',
+  'No extraction cursor found yet.':
+    "Encara no s'ha trobat cap cursor d'extracció.",
+  'Cursor: session={{sessionId}}, offset={{offset}}, updated={{updatedAt}}':
+    'Cursor: session={{sessionId}}, offset={{offset}}, updated={{updatedAt}}',
+  'No chat client available to extract memory.':
+    'No hi ha cap client de xat disponible per extreure memòria.',
+  'Managed auto-memory extraction is already running.':
+    "L'extracció de memòria automàtica gestionada ja s'està executant.",
+  'Managed auto-memory extraction found no new durable memories.':
+    "L'extracció de memòria automàtica gestionada no ha trobat noves memòries durables.",
+  'Consolidate managed auto-memory topic files.':
+    'Consolidar els fitxers de temes de memòria automàtica gestionada.',
+  'Managed auto-memory dream found nothing to improve.':
+    "L'auto-dream de memòria gestionada no ha trobat res a millorar.",
+  'Deduplicated entries: {{count}}': 'Entrades desduplicades: {{count}}',
+  'Save a durable memory using the save_memory tool.':
+    "Desar una memòria durable usant l'eina save_memory.",
+  'Usage: /remember [--global|--project] <text to remember>':
+    'Ús: /remember [--global|--project] <text a recordar>',
+
+  // ============================================================================
+  // Ordres - MCP
+  // ============================================================================
+  'Authenticate with an OAuth-enabled MCP server':
+    'Autenticar-se amb un servidor MCP amb OAuth',
+  'List configured MCP servers and tools':
+    'Llistar els servidors MCP configurats i les seves eines',
+  'Restarts MCP servers.': 'Reinicia els servidors MCP.',
+  'Open MCP management dialog': 'Obrir el diàleg de gestió MCP',
+  'Could not retrieve tool registry.':
+    "No s'ha pogut recuperar el registre d'eines.",
+  'No MCP servers configured with OAuth authentication.':
+    'No hi ha servidors MCP configurats amb autenticació OAuth.',
+  'MCP servers with OAuth authentication:':
+    'Servidors MCP amb autenticació OAuth:',
+  'Use /mcp auth <server-name> to authenticate.':
+    'Useu /mcp auth <nom-del-servidor> per autenticar-vos.',
+  "MCP server '{{name}}' not found.":
+    "El servidor MCP '{{name}}' no s'ha trobat.",
+  "Successfully authenticated and refreshed tools for '{{name}}'.":
+    "S'ha autenticat correctament i s'han actualitzat les eines per a '{{name}}'.",
+  "Failed to authenticate with MCP server '{{name}}': {{error}}":
+    "Error en autenticar-se amb el servidor MCP '{{name}}': {{error}}",
+  "Re-discovering tools from '{{name}}'...":
+    "Redescobrint les eines de '{{name}}'...",
+  "Discovered {{count}} tool(s) from '{{name}}'.":
+    "S'han descobert {{count}} eina(es) de '{{name}}'.",
+  'Authentication complete. Returning to server details...':
+    'Autenticació completada. Tornant als detalls del servidor...',
+  'Authentication successful.': 'Autenticació correcta.',
+  'If the browser does not open, copy and paste this URL into your browser:':
+    "Si el navegador no s'obre, copieu i enganxeu aquesta URL al vostre navegador:",
+  'Make sure to copy the COMPLETE URL - it may wrap across multiple lines.':
+    'Assegureu-vos de copiar la URL COMPLETA - pot ocupar múltiples línies.',
+
+  // ============================================================================
+  // Diàleg de gestió MCP
+  // ============================================================================
+  'Manage MCP servers': 'Gestionar els servidors MCP',
+  'Server Detail': 'Detalls del servidor',
+  'Disable Server': 'Desactivar el servidor',
+  Tools: 'Eines',
+  'Tool Detail': "Detalls de l'eina",
+  'MCP Management': 'Gestió MCP',
+  'Loading...': 'Carregant...',
+  'Unknown step': 'Pas desconegut',
+  'Esc to back': 'Esc per tornar',
+  '↑↓ to navigate · Enter to select · Esc to close':
+    '↑↓ per navegar · Retorn per seleccionar · Esc per tancar',
+  '↑↓ to navigate · Enter to select · Esc to back':
+    '↑↓ per navegar · Retorn per seleccionar · Esc per tornar',
+  '↑↓ to navigate · Enter to confirm · Esc to back':
+    '↑↓ per navegar · Retorn per confirmar · Esc per tornar',
+  'User Settings (global)': "Configuració d'usuari (global)",
+  'Workspace Settings (project-specific)':
+    "Configuració de l'espai de treball (específica del projecte)",
+  'Disable server:': 'Desactivar el servidor:',
+  'Select where to add the server to the exclude list:':
+    "Seleccioneu on afegir el servidor a la llista d'exclusió:",
+  'Press Enter to confirm, Esc to cancel':
+    'Premeu Retorn per confirmar, Esc per cancel·lar',
+  'View tools': 'Veure eines',
+  Reconnect: 'Reconnectar',
+  Enable: 'Activar',
+  Disable: 'Desactivar',
+  Authenticate: 'Autenticar',
+  'Re-authenticate': 'Tornar a autenticar',
+  'Clear Authentication': "Esborrar l'autenticació",
+  'Server:': 'Servidor:',
+  'Command:': 'Ordre:',
+  'Working Directory:': 'Directori de treball:',
+  'Capabilities:': 'Capacitats:',
+  'No server selected': 'Cap servidor seleccionat',
+  prompts: 'missatges',
+  '(disabled)': '(desactivat)',
+  'Error:': 'Error:',
+  tool: 'eina',
+  tools: 'eines',
+  connected: 'connectat',
+  connecting: 'connectant',
+  disconnected: 'desconnectat',
+  'User MCPs': "MCPs de l'usuari",
+  'Project MCPs': 'MCPs del projecte',
+  'Extension MCPs': 'MCPs de les extensions',
+  server: 'servidor',
+  servers: 'servidors',
+  'Add MCP servers to your settings to get started.':
+    'Afegiu servidors MCP a la configuració per començar.',
+  'Run qwen --debug to see error logs':
+    "Executeu qwen --debug per veure els registres d'errors",
+  'OAuth Authentication': 'Autenticació OAuth',
+  'Press Enter to start authentication, Esc to go back':
+    "Premeu Retorn per iniciar l'autenticació, Esc per tornar enrere",
+  'Authenticating... Please complete the login in your browser.':
+    "Autenticant... Completeu l'inici de sessió al vostre navegador.",
+  'Press c to copy the authorization URL to your clipboard.':
+    "Premeu c per copiar la URL d'autorització al porta-retalls.",
+  'Copy request sent to your terminal. If paste is empty, copy the URL above manually.':
+    'Sol·licitud de còpia enviada al vostre terminal. Si el que enganxeu és buit, copieu la URL anterior manualment.',
+  'Cannot write to terminal — copy the URL above manually.':
+    'No es pot escriure al terminal — copieu la URL anterior manualment.',
+  'Press Enter or Esc to go back': 'Premeu Retorn o Esc per tornar enrere',
+  'No tools available for this server.':
+    'No hi ha eines disponibles per a aquest servidor.',
+  destructive: 'destructiu',
+  'read-only': 'només lectura',
+  'open-world': 'món obert',
+  idempotent: 'idempotent',
+  'Tools for {{name}}': 'Eines per a {{name}}',
+  'Tools for {{serverName}}': 'Eines per a {{serverName}}',
+  '{{current}}/{{total}}': '{{current}}/{{total}}',
+  required: 'obligatori',
+  Type: 'Tipus',
+  Enum: 'Enumeració',
+  Parameters: 'Paràmetres',
+  'No tool selected': 'Cap eina seleccionada',
+  Annotations: 'Anotacions',
+  Title: 'Títol',
+  'Read Only': 'Només lectura',
+  Destructive: 'Destructiu',
+  Idempotent: 'Idempotent',
+  'Open World': 'Món obert',
+  Server: 'Servidor',
+  '{{count}} invalid tools': '{{count}} eines no vàlides',
+  invalid: 'no vàlid',
+  'invalid: {{reason}}': 'no vàlid: {{reason}}',
+  'missing name': 'nom absent',
+  'missing description': 'descripció absent',
+  '(unnamed)': '(sense nom)',
+  'Warning: This tool cannot be called by the LLM':
+    'Advertència: el model no pot cridar aquesta eina',
+  Reason: 'Motiu',
+  'Tools must have both name and description to be used by the LLM.':
+    'Les eines han de tenir nom i descripció per poder ser usades pel model.',
+
+  // ============================================================================
+  // Ordres - Xat
+  // ============================================================================
+  'Manage conversation history.': "Gestionar l'historial de la conversa.",
+  'List saved conversation checkpoints':
+    'Llistar els punts de control desats de la conversa',
+  'No saved conversation checkpoints found.':
+    "No s'han trobat punts de control de conversa desats.",
+  'List of saved conversations:': 'Llista de converses desades:',
+  'Note: Newest last, oldest first':
+    'Nota: Les més recents al final, les més antigues al principi',
+  'Save the current conversation as a checkpoint. Usage: /chat save <tag>':
+    'Desar la conversa actual com a punt de control. Ús: /chat save <etiqueta>',
+  'Missing tag. Usage: /chat save <tag>':
+    'Etiqueta absent. Ús: /chat save <etiqueta>',
+  'Delete a conversation checkpoint. Usage: /chat delete <tag>':
+    'Eliminar un punt de control de conversa. Ús: /chat delete <etiqueta>',
+  'Missing tag. Usage: /chat delete <tag>':
+    'Etiqueta absent. Ús: /chat delete <etiqueta>',
+  "Conversation checkpoint '{{tag}}' has been deleted.":
+    "El punt de control de conversa '{{tag}}' s'ha eliminat.",
+  "Error: No checkpoint found with tag '{{tag}}'.":
+    "Error: No s'ha trobat cap punt de control amb l'etiqueta '{{tag}}'.",
+  'Resume a conversation from a checkpoint. Usage: /chat resume <tag>':
+    "Reprendre una conversa des d'un punt de control. Ús: /chat resume <etiqueta>",
+  'Missing tag. Usage: /chat resume <tag>':
+    'Etiqueta absent. Ús: /chat resume <etiqueta>',
+  'No saved checkpoint found with tag: {{tag}}.':
+    "No s'ha trobat cap punt de control desat amb l'etiqueta: {{tag}}.",
+  'A checkpoint with the tag {{tag}} already exists. Do you want to overwrite it?':
+    "Ja existeix un punt de control amb l'etiqueta {{tag}}. Voleu sobreescriure'l?",
+  'No chat client available to save conversation.':
+    'No hi ha cap client de xat disponible per desar la conversa.',
+  'Conversation checkpoint saved with tag: {{tag}}.':
+    "Punt de control de conversa desat amb l'etiqueta: {{tag}}.",
+  'No conversation found to save.': "No s'ha trobat cap conversa per desar.",
+  'No chat client available to share conversation.':
+    'No hi ha cap client de xat disponible per compartir la conversa.',
+  'Invalid file format. Only .md and .json are supported.':
+    'Format de fitxer no vàlid. Només es suporten .md i .json.',
+  'Error sharing conversation: {{error}}':
+    'Error en compartir la conversa: {{error}}',
+  'Conversation shared to {{filePath}}': 'Conversa compartida a {{filePath}}',
+  'No conversation found to share.':
+    "No s'ha trobat cap conversa per compartir.",
+  'Share the current conversation to a markdown or json file. Usage: /chat share <file>':
+    'Compartir la conversa actual a un fitxer markdown o json. Ús: /chat share <fitxer>',
+
+  // ============================================================================
+  // Ordres - Resum
+  // ============================================================================
+  'Generate a project summary and save it to .qwen/PROJECT_SUMMARY.md':
+    'Generar un resum del projecte i desar-lo a .qwen/PROJECT_SUMMARY.md',
+  'No chat client available to generate summary.':
+    'No hi ha cap client de xat disponible per generar el resum.',
+  'Already generating summary, wait for previous request to complete':
+    "Ja s'està generant el resum, espereu que acabi la sol·licitud anterior",
+  'No conversation found to summarize.':
+    "No s'ha trobat cap conversa per resumir.",
+  'Failed to generate project context summary: {{error}}':
+    'Error en generar el resum del context del projecte: {{error}}',
+  'Saved project summary to {{filePathForDisplay}}.':
+    'Resum del projecte desat a {{filePathForDisplay}}.',
+  'Saving project summary...': 'Desant el resum del projecte...',
+  'Generating project summary...': 'Generant el resum del projecte...',
+  'Failed to generate summary - no text content received from LLM response':
+    "Error en generar el resum - no s'ha rebut contingut de text de la resposta del model",
+
+  // ============================================================================
+  // Ordres - Model
+  // ============================================================================
+  'Switch the model for this session (--fast for suggestion model)':
+    'Canviar el model per a aquesta sessió (--fast per al model de suggeriments)',
+  'Set a lighter model for prompt suggestions and speculative execution':
+    'Establir un model més lleuger per a suggeriments de missatges i execució especulativa',
+  'Content generator configuration not available.':
+    'Configuració del generador de contingut no disponible.',
+  'Authentication type not available.': "Tipus d'autenticació no disponible.",
+  'No models available for the current authentication type ({{authType}}).':
+    "No hi ha models disponibles per al tipus d'autenticació actual ({{authType}}).",
+
+  // ============================================================================
+  // Ordres - Netejar
+  // ============================================================================
+  'Starting a new session, resetting chat, and clearing terminal.':
+    'Iniciant una nova sessió, restablint el xat i netejant el terminal.',
+  'Starting a new session and clearing.':
+    'Iniciant una nova sessió i netejant.',
+
+  // ============================================================================
+  // Ordres - Comprimir
+  // ============================================================================
+  'Already compressing, wait for previous request to complete':
+    "Ja s'està comprimint, espereu que acabi la sol·licitud anterior",
+  'Failed to compress chat history.': "Error en comprimir l'historial del xat.",
+  'Failed to compress chat history: {{error}}':
+    "Error en comprimir l'historial del xat: {{error}}",
+  'Compressing chat history': "Comprimint l'historial del xat",
+  'Chat history compressed from {{originalTokens}} to {{newTokens}} tokens.':
+    "L'historial del xat s'ha comprimit de {{originalTokens}} a {{newTokens}} tokens.",
+  'Compression was not beneficial for this history size.':
+    "La compressió no ha estat beneficiosa per a aquesta mida d'historial.",
+  'Chat history compression did not reduce size. This may indicate issues with the compression prompt.':
+    "La compressió de l'historial del xat no ha reduït la mida. Això pot indicar problemes amb el missatge de compressió.",
+  'Could not compress chat history due to a token counting error.':
+    "No s'ha pogut comprimir l'historial del xat per un error de recompte de tokens.",
+  'Chat history is already compressed.':
+    "L'historial del xat ja està comprimit.",
+
+  // ============================================================================
+  // Ordres - Directori
+  // ============================================================================
+  'Configuration is not available.': 'Configuració no disponible.',
+  'Please provide at least one path to add.':
+    'Proporcioneu almenys un camí per afegir.',
+  'The /directory add command is not supported in restrictive sandbox profiles. Please use --include-directories when starting the session instead.':
+    "L'ordre /directory add no és compatible en perfils d'entorn aïllat restrictius. En el seu lloc, useu --include-directories en iniciar la sessió.",
+  "Error adding '{{path}}': {{error}}": "Error en afegir '{{path}}': {{error}}",
+  'Successfully added QWEN.md files from the following directories if there are:\n- {{directories}}':
+    "S'han afegit correctament els fitxers QWEN.md dels directoris següents si n'hi ha:\n- {{directories}}",
+  'Error refreshing memory: {{error}}':
+    'Error en actualitzar la memòria: {{error}}',
+  'Successfully added directories:\n- {{directories}}':
+    "S'han afegit correctament els directoris:\n- {{directories}}",
+  'Current workspace directories:\n{{directories}}':
+    "Directoris actuals de l'espai de treball:\n{{directories}}",
+
+  // ============================================================================
+  // Ordres - Documentació
+  // ============================================================================
+  'Please open the following URL in your browser to view the documentation:\n{{url}}':
+    'Obriu la URL següent al vostre navegador per veure la documentació:\n{{url}}',
+  'Opening documentation in your browser: {{url}}':
+    'Obrint la documentació al vostre navegador: {{url}}',
+
+  // ============================================================================
+  // Diàlegs - Confirmació d'eines
+  // ============================================================================
+  'Do you want to proceed?': 'Voleu continuar?',
+  'Yes, allow once': 'Sí, permetre una vegada',
+  'Allow always': 'Permetre sempre',
+  Yes: 'Sí',
+  No: 'No',
+  'No (esc)': 'No (esc)',
+  'Yes, allow always for this session':
+    'Sí, permetre sempre per a aquesta sessió',
+  'Modify in progress:': 'Modificació en curs:',
+  'Save and close external editor to continue':
+    "Deseu i tanqueu l'editor extern per continuar",
+  'Apply this change?': 'Aplicar aquest canvi?',
+  'Yes, allow always': 'Sí, permetre sempre',
+  'Modify with external editor': 'Modificar amb editor extern',
+  'No, suggest changes (esc)': 'No, suggerir canvis (esc)',
+  "Allow execution of: '{{command}}'?":
+    "Permetre l'execució de: '{{command}}'?",
+  'Yes, allow always ...': 'Sí, permetre sempre...',
+  'Always allow in this project': 'Permetre sempre en aquest projecte',
+  'Always allow {{action}} in this project':
+    'Permetre sempre {{action}} en aquest projecte',
+  'Always allow for this user': 'Permetre sempre per a aquest usuari',
+  'Always allow {{action}} for this user':
+    'Permetre sempre {{action}} per a aquest usuari',
+  'Yes, restore previous mode ({{mode}})':
+    'Sí, restaurar el mode anterior ({{mode}})',
+  'Yes, and auto-accept edits': 'Sí, i acceptar els canvis automàticament',
+  'Yes, and manually approve edits': 'Sí, i aprovar els canvis manualment',
+  'No, keep planning (esc)': 'No, seguir planificant (esc)',
+  'URLs to fetch:': 'URLs a recuperar:',
+  'MCP Server: {{server}}': 'Servidor MCP: {{server}}',
+  'Tool: {{tool}}': 'Eina: {{tool}}',
+  'Allow execution of MCP tool "{{tool}}" from server "{{server}}"?':
+    'Permetre l\'execució de l\'eina MCP "{{tool}}" del servidor "{{server}}"?',
+  'Yes, always allow tool "{{tool}}" from server "{{server}}"':
+    'Sí, permetre sempre l\'eina "{{tool}}" del servidor "{{server}}"',
+  'Yes, always allow all tools from server "{{server}}"':
+    'Sí, permetre sempre totes les eines del servidor "{{server}}"',
+
+  // ============================================================================
+  // Diàlegs - Confirmació de shell
+  // ============================================================================
+  'Shell Command Execution': "Execució d'ordres shell",
+  'A custom command wants to run the following shell commands:':
+    'Una ordre personalitzada vol executar les ordres shell següents:',
+
+  // ============================================================================
+  // Diàlegs - Quota Pro
+  // ============================================================================
+  'Pro quota limit reached for {{model}}.':
+    "S'ha assolit el límit de quota Pro per a {{model}}.",
+  'Change auth (executes the /auth command)':
+    "Canviar autenticació (executa l'ordre /auth)",
+  'Continue with {{model}}': 'Continuar amb {{model}}',
+
+  // ============================================================================
+  // Diàlegs - Benvinguda
+  // ============================================================================
+  'Current Plan:': 'Pla actual:',
+  'Progress: {{done}}/{{total}} tasks completed':
+    'Progrés: {{done}}/{{total}} tasques completades',
+  ', {{inProgress}} in progress': ', {{inProgress}} en curs',
+  'Pending Tasks:': 'Tasques pendents:',
+  'What would you like to do?': 'Què voleu fer?',
+  'Choose how to proceed with your session:':
+    'Trieu com voleu continuar la vostra sessió:',
+  'Start new chat session': 'Iniciar una nova sessió de xat',
+  'Continue previous conversation': 'Continuar la conversa anterior',
+  '👋 Welcome back! (Last updated: {{timeAgo}})':
+    '👋 Benvingut de nou! (Darrera actualització: {{timeAgo}})',
+  '🎯 Overall Goal:': '🎯 Objectiu general:',
+
+  // ============================================================================
+  // Diàlegs - Autenticació
+  // ============================================================================
+  'Get started': 'Comencem',
+  'Select Authentication Method': "Seleccioneu el mètode d'autenticació",
+  'OpenAI API key is required to use OpenAI authentication.':
+    "Cal una clau API d'OpenAI per usar l'autenticació d'OpenAI.",
+  'You must select an auth method to proceed. Press Ctrl+C again to exit.':
+    "Cal seleccionar un mètode d'autenticació per continuar. Premeu Ctrl+C de nou per sortir.",
+  'Terms of Services and Privacy Notice':
+    'Termes de servei i avís de privacitat',
+  'Qwen OAuth': 'Qwen OAuth',
+  'Discontinued — switch to Coding Plan or API Key':
+    'Descontinuat — canvieu a Coding Plan o clau API',
+  'Qwen OAuth free tier was discontinued on 2026-04-15. Run /auth to switch provider.':
+    'El nivell gratuït de Qwen OAuth es va descontinuar el 15-04-2026. Executeu /auth per canviar de proveïdor.',
+  'Qwen OAuth free tier was discontinued on 2026-04-15. Please select Coding Plan or API Key instead.':
+    'El nivell gratuït de Qwen OAuth es va descontinuar el 15-04-2026. Seleccioneu Coding Plan o clau API en el seu lloc.',
+  'Qwen OAuth free tier was discontinued on 2026-04-15. Please select a model from another provider or run /auth to switch.':
+    "El nivell gratuït de Qwen OAuth es va descontinuar el 15-04-2026. Seleccioneu un model d'un altre proveïdor o executeu /auth per canviar.",
+  '\n⚠ Qwen OAuth free tier was discontinued on 2026-04-15. Please select another option.\n':
+    '\n⚠ El nivell gratuït de Qwen OAuth es va descontinuar el 15-04-2026. Seleccioneu una altra opció.\n',
+  'Paid · Up to 6,000 requests/5 hrs · All Alibaba Cloud Coding Plan Models':
+    "De pagament · Fins a 6.000 sol·licituds/5 h · Tots els models del Coding Plan d'Alibaba Cloud",
+  'Alibaba Cloud Coding Plan': "Coding Plan d'Alibaba Cloud",
+  'Bring your own API key': 'Porteu la vostra pròpia clau API',
+  'API-KEY': 'API-KEY',
+  'Use coding plan credentials or your own api-keys/providers.':
+    'Useu les credencials del coding plan o les vostres pròpies claus API/proveïdors.',
+  OpenAI: 'OpenAI',
+  'Failed to login. Message: {{message}}':
+    'Error en iniciar sessió. Missatge: {{message}}',
+  'Authentication is enforced to be {{enforcedType}}, but you are currently using {{currentType}}.':
+    "L'autenticació ha de ser {{enforcedType}}, però actualment esteu usant {{currentType}}.",
+  'Qwen OAuth authentication timed out. Please try again.':
+    "L'autenticació Qwen OAuth ha expirat. Torneu-ho a intentar.",
+  'Qwen OAuth authentication cancelled.':
+    "L'autenticació Qwen OAuth s'ha cancel·lat.",
+  'Qwen OAuth Authentication': 'Autenticació Qwen OAuth',
+  'Please visit this URL to authorize:': 'Visiteu aquesta URL per autoritzar:',
+  'Or scan the QR code below:': 'O escanegeu el codi QR de sota:',
+  'Waiting for authorization': "Esperant l'autorització",
+  'Time remaining:': 'Temps restant:',
+  '(Press ESC or CTRL+C to cancel)': '(Premeu ESC o CTRL+C per cancel·lar)',
+  'Qwen OAuth Authentication Timeout':
+    "Temps d'espera de l'autenticació Qwen OAuth esgotat",
+  'OAuth token expired (over {{seconds}} seconds). Please select authentication method again.':
+    "El token OAuth ha expirat (més de {{seconds}} segons). Seleccioneu el mètode d'autenticació de nou.",
+  'Press any key to return to authentication type selection.':
+    "Premeu qualsevol tecla per tornar a la selecció del tipus d'autenticació.",
+  'Waiting for Qwen OAuth authentication...':
+    "Esperant l'autenticació Qwen OAuth...",
+  'Note: Your existing API key in settings.json will not be cleared when using Qwen OAuth. You can switch back to OpenAI authentication later if needed.':
+    "Nota: La vostra clau API existent a settings.json no s'esborrarà en usar Qwen OAuth. Podeu tornar a l'autenticació d'OpenAI més endavant si cal.",
+  'Note: Your existing API key will not be cleared when using Qwen OAuth.':
+    "Nota: La vostra clau API existent no s'esborrarà en usar Qwen OAuth.",
+  'Authentication timed out. Please try again.':
+    "L'autenticació ha expirat. Torneu-ho a intentar.",
+  'Waiting for auth... (Press ESC or CTRL+C to cancel)':
+    "Esperant l'autenticació... (Premeu ESC o CTRL+C per cancel·lar)",
+  'Missing API key for OpenAI-compatible auth. Set settings.security.auth.apiKey, or set the {{envKeyHint}} environment variable.':
+    "Manca la clau API per a l'autenticació compatible amb OpenAI. Establiu settings.security.auth.apiKey o la variable d'entorn {{envKeyHint}}.",
+  '{{envKeyHint}} environment variable not found.':
+    "La variable d'entorn {{envKeyHint}} no s'ha trobat.",
+  '{{envKeyHint}} environment variable not found. Please set it in your .env file or environment variables.':
+    "La variable d'entorn {{envKeyHint}} no s'ha trobat. Establiu-la al fitxer .env o a les variables d'entorn.",
+  '{{envKeyHint}} environment variable not found (or set settings.security.auth.apiKey). Please set it in your .env file or environment variables.':
+    "La variable d'entorn {{envKeyHint}} no s'ha trobat (o establiu settings.security.auth.apiKey). Establiu-la al fitxer .env o a les variables d'entorn.",
+  'Missing API key for OpenAI-compatible auth. Set the {{envKeyHint}} environment variable.':
+    "Manca la clau API per a l'autenticació compatible amb OpenAI. Establiu la variable d'entorn {{envKeyHint}}.",
+  'Anthropic provider missing required baseUrl in modelProviders[].baseUrl.':
+    'El proveïdor Anthropic no té la baseUrl obligatòria a modelProviders[].baseUrl.',
+  'ANTHROPIC_BASE_URL environment variable not found.':
+    "La variable d'entorn ANTHROPIC_BASE_URL no s'ha trobat.",
+  'Invalid auth method selected.':
+    "S'ha seleccionat un mètode d'autenticació no vàlid.",
+  'Failed to authenticate. Message: {{message}}':
+    'Error en autenticar-se. Missatge: {{message}}',
+  'Authenticated successfully with {{authType}} credentials.':
+    "S'ha autenticat correctament amb les credencials {{authType}}.",
+  'Invalid QWEN_DEFAULT_AUTH_TYPE value: "{{value}}". Valid values are: {{validValues}}':
+    'Valor de QWEN_DEFAULT_AUTH_TYPE no vàlid: "{{value}}". Els valors vàlids són: {{validValues}}',
+  'OpenAI Configuration Required': "Configuració d'OpenAI necessària",
+  'Please enter your OpenAI configuration. You can get an API key from':
+    "Introduïu la vostra configuració d'OpenAI. Podeu obtenir una clau API de",
+  'API Key:': 'Clau API:',
+  'Invalid credentials: {{errorMessage}}':
+    'Credencials no vàlides: {{errorMessage}}',
+  'Failed to validate credentials': 'Error en validar les credencials',
+  'Press Enter to continue, Tab/↑↓ to navigate, Esc to cancel':
+    'Premeu Retorn per continuar, Tab/↑↓ per navegar, Esc per cancel·lar',
+
+  // ============================================================================
+  // Diàlegs - Model
+  // ============================================================================
+  'Select Model': 'Seleccioneu el model',
+  '(Press Esc to close)': '(Premeu Esc per tancar)',
+  'Current (effective) configuration': 'Configuració actual (efectiva)',
+  AuthType: "Tipus d'autenticació",
+  'API Key': 'Clau API',
+  unset: 'no establert',
+  '(default)': '(per defecte)',
+  '(set)': '(establert)',
+  '(not set)': '(no establert)',
+  Modality: 'Modalitat',
+  'Context Window': 'Fin. de context',
+  text: 'text',
+  'text-only': 'només text',
+  image: 'imatge',
+  pdf: 'pdf',
+  audio: 'àudio',
+  video: 'vídeo',
+  'not set': 'no establert',
+  none: 'cap',
+  unknown: 'desconegut',
+  "Failed to switch model to '{{modelId}}'.\n\n{{error}}":
+    "Error en canviar al model '{{modelId}}'.\n\n{{error}}",
+  'Qwen 3.6 Plus — efficient hybrid model with leading coding performance':
+    'Qwen 3.6 Plus — model híbrid eficient amb un rendiment de codificació líder',
+  'The latest Qwen Vision model from Alibaba Cloud ModelStudio (version: qwen3-vl-plus-2025-09-23)':
+    "L'últim model de visió Qwen d'Alibaba Cloud ModelStudio (versió: qwen3-vl-plus-2025-09-23)",
+
+  // ============================================================================
+  // Diàlegs - Permisos
+  // ============================================================================
+  'Manage folder trust settings':
+    'Gestionar la configuració de confiança de carpetes',
+  'Manage permission rules': 'Gestionar les regles de permisos',
+  Allow: 'Permetre',
+  Ask: 'Preguntar',
+  Deny: 'Denegar',
+  Workspace: 'Espai de treball',
+  "Qwen Code won't ask before using allowed tools.":
+    "Qwen Code no preguntarà abans d'usar les eines permeses.",
+  'Qwen Code will ask before using these tools.':
+    "Qwen Code preguntarà abans d'usar aquestes eines.",
+  'Qwen Code is not allowed to use denied tools.':
+    'Qwen Code no té permís per usar les eines denegades.',
+  'Manage trusted directories for this workspace.':
+    "Gestionar els directoris de confiança d'aquest espai de treball.",
+  'Any use of the {{tool}} tool': "Qualsevol ús de l'eina {{tool}}",
+  "{{tool}} commands matching '{{pattern}}'":
+    "Ordres de {{tool}} que coincideixen amb '{{pattern}}'",
+  'From user settings': "Des de la configuració d'usuari",
+  'From project settings': 'Des de la configuració del projecte',
+  'From session': 'Des de la sessió',
+  'Project settings (local)': 'Configuració del projecte (local)',
+  'Saved in .qwen/settings.local.json': 'Desat a .qwen/settings.local.json',
+  'Project settings': 'Configuració del projecte',
+  'Checked in at .qwen/settings.json': 'Registrat a .qwen/settings.json',
+  'User settings': "Configuració d'usuari",
+  'Saved in at ~/.qwen/settings.json': 'Desat a ~/.qwen/settings.json',
+  'Add a new rule…': 'Afegir una nova regla…',
+  'Add {{type}} permission rule': 'Afegir una regla de permís {{type}}',
+  'Permission rules are a tool name, optionally followed by a specifier in parentheses.':
+    "Les regles de permisos són un nom d'eina, seguit opcionalment d'un especificador entre parèntesis.",
+  'e.g.,': 'p. ex.,',
+  or: 'o',
+  'Enter permission rule…': 'Introduïu la regla de permís…',
+  'Enter to submit · Esc to cancel': 'Retorn per enviar · Esc per cancel·lar',
+  'Where should this rule be saved?': "On s'ha de desar aquesta regla?",
+  'Enter to confirm · Esc to cancel':
+    'Retorn per confirmar · Esc per cancel·lar',
+  'Delete {{type}} rule?': 'Eliminar la regla {{type}}?',
+  'Are you sure you want to delete this permission rule?':
+    'Esteu segur que voleu eliminar aquesta regla de permisos?',
+  'Permissions:': 'Permisos:',
+  '(←/→ or tab to cycle)': '(←/→ o tab per canviar)',
+  'Press ↑↓ to navigate · Enter to select · Type to search · Esc to cancel':
+    'Premeu ↑↓ per navegar · Retorn per seleccionar · Escriviu per cercar · Esc per cancel·lar',
+  'Search…': 'Cercar…',
+  'Use /trust to manage folder trust settings for this workspace.':
+    "Useu /trust per gestionar la configuració de confiança de carpetes d'aquest espai de treball.",
+  'Add directory…': 'Afegir directori…',
+  'Add directory to workspace': "Afegir directori a l'espai de treball",
+  'Qwen Code can read files in the workspace, and make edits when auto-accept edits is on.':
+    "Qwen Code pot llegir fitxers a l'espai de treball i fer canvis quan l'acceptació automàtica de canvis està activada.",
+  'Qwen Code will be able to read files in this directory and make edits when auto-accept edits is on.':
+    "Qwen Code podrà llegir fitxers en aquest directori i fer canvis quan l'acceptació automàtica de canvis està activada.",
+  'Enter the path to the directory:': 'Introduïu el camí del directori:',
+  'Enter directory path…': 'Introduïu el camí del directori…',
+  'Tab to complete · Enter to add · Esc to cancel':
+    'Tab per completar · Retorn per afegir · Esc per cancel·lar',
+  'Remove directory?': 'Eliminar el directori?',
+  'Are you sure you want to remove this directory from the workspace?':
+    "Esteu segur que voleu eliminar aquest directori de l'espai de treball?",
+  '  (Original working directory)': '  (Directori de treball original)',
+  '  (from settings)': '  (des de la configuració)',
+  'Directory does not exist.': 'El directori no existeix.',
+  'Path is not a directory.': 'El camí no és un directori.',
+  'This directory is already in the workspace.':
+    "Aquest directori ja és a l'espai de treball.",
+  'Already covered by existing directory: {{dir}}':
+    'Ja cobert per un directori existent: {{dir}}',
+
+  // ============================================================================
+  // Barra d'estat
+  // ============================================================================
+  'Using:': 'En ús:',
+  '{{count}} open file': '{{count}} fitxer obert',
+  '{{count}} open files': '{{count}} fitxers oberts',
+  '(ctrl+g to view)': '(ctrl+g per veure)',
+  '{{count}} {{name}} file': '{{count}} fitxer {{name}}',
+  '{{count}} {{name}} files': '{{count}} fitxers {{name}}',
+  '{{count}} MCP server': '{{count}} servidor MCP',
+  '{{count}} MCP servers': '{{count}} servidors MCP',
+  '{{count}} Blocked': '{{count}} bloquejats',
+  '(ctrl+t to view)': '(ctrl+t per veure)',
+  '(ctrl+t to toggle)': '(ctrl+t per canviar)',
+  'Press Ctrl+C again to exit.': 'Premeu Ctrl+C de nou per sortir.',
+  'Press Ctrl+D again to exit.': 'Premeu Ctrl+D de nou per sortir.',
+  'Press Esc again to clear.': 'Premeu Esc de nou per esborrar.',
+  'Press ↑ to edit queued messages': 'Premeu ↑ per editar els missatges en cua',
+
+  // ============================================================================
+  // Estat MCP
+  // ============================================================================
+  'No MCP servers configured.': 'No hi ha servidors MCP configurats.',
+  '⏳ MCP servers are starting up ({{count}} initializing)...':
+    "⏳ Els servidors MCP s'estan iniciant ({{count}} inicialitzant)...",
+  'Note: First startup may take longer. Tool availability will update automatically.':
+    "Nota: El primer inici pot tardar més. La disponibilitat de les eines s'actualitzarà automàticament.",
+  'Configured MCP servers:': 'Servidors MCP configurats:',
+  Ready: 'Preparat',
+  'Starting... (first startup may take longer)':
+    'Iniciant... (el primer inici pot tardar més)',
+  Disconnected: 'Desconnectat',
+  '{{count}} tool': '{{count}} eina',
+  '{{count}} tools': '{{count}} eines',
+  '{{count}} prompt': '{{count}} missatge',
+  '{{count}} prompts': '{{count}} missatges',
+  '(from {{extensionName}})': '(de {{extensionName}})',
+  OAuth: 'OAuth',
+  'OAuth expired': 'OAuth expirat',
+  'OAuth not authenticated': 'OAuth no autenticat',
+  'tools and prompts will appear when ready':
+    'les eines i els missatges apareixeran quan estiguin a punt',
+  '{{count}} tools cached': '{{count}} eines en memòria cau',
+  'Tools:': 'Eines:',
+  'Parameters:': 'Paràmetres:',
+  'Prompts:': 'Missatges:',
+  Blocked: 'Bloquejat',
+  '💡 Tips:': '💡 Consells:',
+  Use: 'Useu',
+  'to show server and tool descriptions':
+    'per mostrar les descripcions del servidor i de les eines',
+  'to show tool parameter schemas':
+    'per mostrar els esquemes de paràmetres de les eines',
+  'to hide descriptions': 'per amagar les descripcions',
+  'to authenticate with OAuth-enabled servers':
+    'per autenticar-vos amb servidors OAuth',
+  Press: 'Premeu',
+  'to toggle tool descriptions on/off':
+    'per activar/desactivar les descripcions de les eines',
+  "Starting OAuth authentication for MCP server '{{name}}'...":
+    "Iniciant l'autenticació OAuth per al servidor MCP '{{name}}'...",
+  'Restarting MCP servers...': 'Reiniciant els servidors MCP...',
+
+  // ============================================================================
+  // Consells d'inici
+  // ============================================================================
+  'Tips:': 'Consells:',
+  'Use /compress when the conversation gets long to summarize history and free up context.':
+    "Useu /compress quan la conversa sigui llarga per resumir l'historial i alliberar context.",
+  'Start a fresh idea with /clear or /new; the previous session stays available in history.':
+    "Comenceu una idea nova amb /clear o /new; la sessió anterior segueix disponible a l'historial.",
+  'Use /bug to submit issues to the maintainers when something goes off.':
+    'Useu /bug per enviar incidències als mantenidors quan alguna cosa vagi malament.',
+  'Switch auth type quickly with /auth.':
+    "Canvieu ràpidament el tipus d'autenticació amb /auth.",
+  'You can run any shell commands from Qwen Code using ! (e.g. !ls).':
+    'Podeu executar qualsevol ordre shell des de Qwen Code usant ! (p. ex. !ls).',
+  'Type / to open the command popup; Tab autocompletes slash commands and saved prompts.':
+    "Escriviu / per obrir el menú emergent d'ordres; Tab completa automàticament les ordres de barra i els missatges desats.",
+  'You can resume a previous conversation by running qwen --continue or qwen --resume.':
+    'Podeu reprendre una conversa anterior executant qwen --continue o qwen --resume.',
+  'You can switch permission mode quickly with Shift+Tab or /approval-mode.':
+    'Podeu canviar ràpidament el mode de permisos amb Maj+Tab o /approval-mode.',
+  'You can switch permission mode quickly with Tab or /approval-mode.':
+    'Podeu canviar ràpidament el mode de permisos amb Tab o /approval-mode.',
+  'Try /insight to generate personalized insights from your chat history.':
+    'Proveu /insight per generar idees personalitzades a partir del vostre historial de xat.',
+  'Press Ctrl+O to toggle compact mode — hide tool output and thinking for a cleaner view.':
+    'Premeu Ctrl+O per canviar el mode compacte — amagueu la sortida de les eines i el pensament per a una vista més neta.',
+  'Add a QWEN.md file to give Qwen Code persistent project context.':
+    'Afegiu un fitxer QWEN.md per donar a Qwen Code un context persistent del projecte.',
+  'Use /btw to ask a quick side question without disrupting the conversation.':
+    'Useu /btw per fer una pregunta ràpida sense interrompre la conversa.',
+  'Context is almost full! Run /compress now or start /new to continue.':
+    'El context gairebé és ple! Executeu /compress ara o inicieu /new per continuar.',
+  'Context is getting full. Use /compress to free up space.':
+    "El context s'omple. Useu /compress per alliberar espai.",
+  'Long conversation? /compress summarizes history to free context.':
+    "Conversa llarga? /compress resumeix l'historial per alliberar context.",
+
+  // ============================================================================
+  // Pantalla de sortida / Estadístiques
+  // ============================================================================
+  'Agent powering down. Goodbye!': "L'agent s'apaga. Fins aviat!",
+  'To continue this session, run': 'Per continuar aquesta sessió, executeu',
+  'Interaction Summary': 'Resum de la interacció',
+  'Session ID:': 'ID de sessió:',
+  'Tool Calls:': 'Crides a eines:',
+  'Success Rate:': "Taxa d'èxit:",
+  'User Agreement:': "Acord de l'usuari:",
+  reviewed: 'revisades',
+  'Code Changes:': 'Canvis de codi:',
+  Performance: 'Rendiment',
+  'Wall Time:': 'Temps real:',
+  'Agent Active:': 'Agent actiu:',
+  'API Time:': "Temps de l'API:",
+  'Tool Time:': "Temps d'eines:",
+  'Session Stats': 'Estadístiques de la sessió',
+  'Model Usage': 'Ús del model',
+  Reqs: 'Sol·licituds',
+  'Input Tokens': "Tokens d'entrada",
+  'Output Tokens': 'Tokens de sortida',
+  'Savings Highlight:': 'Estalvis destacats:',
+  'of input tokens were served from the cache, reducing costs.':
+    "dels tokens d'entrada s'han servit des de la memòria cau, reduint els costos.",
+  'Tip: For a full token breakdown, run `/stats model`.':
+    'Consell: Per a un desglossament complet de tokens, executeu `/stats model`.',
+  'Model Stats For Nerds': 'Estadístiques del model per a nerds',
+  'Tool Stats For Nerds': "Estadístiques d'eines per a nerds",
+  Metric: 'Mètrica',
+  API: 'API',
+  Requests: 'Sol·licituds',
+  Errors: 'Errors',
+  'Avg Latency': 'Latència mitjana',
+  Tokens: 'Tokens',
+  Total: 'Total',
+  Prompt: 'Missatge',
+  Cached: 'En memòria cau',
+  Thoughts: 'Pensaments',
+  Tool: 'Eina',
+  Output: 'Sortida',
+  'No API calls have been made in this session.':
+    "No s'ha realitzat cap crida a l'API en aquesta sessió.",
+  'Tool Name': "Nom de l'eina",
+  Calls: 'Crides',
+  'Success Rate': "Taxa d'èxit",
+  'Avg Duration': 'Durada mitjana',
+  'User Decision Summary': "Resum de decisions de l'usuari",
+  'Total Reviewed Suggestions:': 'Total de suggeriments revisats:',
+  ' » Accepted:': ' » Acceptats:',
+  ' » Rejected:': ' » Rebutjats:',
+  ' » Modified:': ' » Modificats:',
+  ' Overall Agreement Rate:': " Taxa d'acord global:",
+  'No tool calls have been made in this session.':
+    "No s'ha realitzat cap crida a eines en aquesta sessió.",
+  'Session start time is unavailable, cannot calculate stats.':
+    "L'hora d'inici de la sessió no està disponible, no es poden calcular les estadístiques.",
+
+  // ============================================================================
+  // Migració del format d'ordres
+  // ============================================================================
+  'Command Format Migration': "Migració del format d'ordres",
+  'Found {{count}} TOML command file:':
+    "S'ha trobat {{count}} fitxer d'ordres TOML:",
+  'Found {{count}} TOML command files:':
+    "S'han trobat {{count}} fitxers d'ordres TOML:",
+  '... and {{count}} more': '... i {{count}} més',
+  'The TOML format is deprecated. Would you like to migrate them to Markdown format?':
+    'El format TOML és obsolet. Voleu migrar-los al format Markdown?',
+  '(Backups will be created and original files will be preserved)':
+    '(Es crearan còpies de seguretat i els fitxers originals es conservaran)',
+
+  // ============================================================================
+  // Frases de càrrega
+  // ============================================================================
+  'Waiting for user confirmation...': "Esperant la confirmació de l'usuari...",
+  '(esc to cancel, {{time}})': '(esc per cancel·lar, {{time}})',
+
+  // ============================================================================
+  // Frases de càrrega enginyoses
+  // ============================================================================
+  WITTY_LOADING_PHRASES: [
+    'Em sento afortunat',
+    'Enviant el millor...',
+    "Setze jutges d'un jutjat mengen fetge d'un penjat.",
+    'Navegant pel fong mucilaginós...',
+    'Consultant els esperits digitals...',
+    'Desperta ferro...',
+    'Escalfant els hàmsters de la IA...',
+    'Preguntant a la petxina màgica...',
+    'Generant una rèplica enginyosa...',
+    'Polint els algorismes...',
+    'No correu la perfecció (ni el meu codi)...',
+    'Preparant bytes frescos...',
+    'Comptant electrons...',
+    'Activant els processadors cognitius...',
+    "Buscant errors de sintaxi a l'univers...",
+    "Un moment, optimitzant l'humor...",
+    'Barrejant les gràcies...',
+    'Desenredant les xarxes neuronals...',
+    'Compilant la brillantor...',
+    'Carregant gràcia.exe...',
+    'Invocant el núvol de saviesa...',
+    'Preparant una resposta enginyosa...',
+    'Un segon, estic depurant la realitat...',
+    'Donant els últims cops de...',
+    'Afinant les freqüències còsmiques...',
+    'Elaborant una resposta digna de la vostra paciència...',
+    'Compilant els 1 i els 0...',
+    'Resolent dependències... i crisis existencials...',
+    'Desfragmentant records... tant de RAM com personals...',
+    "Reiniciant el mòdul de l'humor...",
+    'Emmagatzemant en memòria cau el necessari (principalment mems de gats)...',
+    'Optimitzant per a velocitat ridícula',
+    'Intercanviant bits... que no ho sàpiguen els bytes...',
+    'Recollint brossa... torno de seguida...',
+    'Assemblant les internets...',
+    'Convertint cafè en codi...',
+    'Actualitzant la sintaxi de la realitat...',
+    'Reconnectant les sinapsis...',
+    'Buscant un punt i coma mal posat...',
+    'Engreixant els engranatges de la màquina...',
+    'Precalfant els servidors...',
+    'Calibrant el condensador de flux...',
+    'Activant el motor de improbabilitat...',
+    'Canalitzant la Força...',
+    'Alineant les estrelles per a una resposta òptima...',
+    'I tots ho diem...',
+    'Carregant la propera gran idea...',
+    'Un moment, estic en el meu element...',
+    'Preparant-me per impressionar-vos amb brillantor...',
+    'Un moment, polint el meu enginy...',
+    'Aguanteu, estic creant una obra mestra...',
+    "Un moment, depurant l'univers...",
+    'Un moment, alineant els píxels...',
+    "Un segon, optimitzant l'humor...",
+    'Un moment, afinant els algorismes...',
+    'Velocitat de curvatura activada...',
+    'Preparant la següent jugada mestre...',
+    'No us espanteu...',
+    'Seguint el conill blanc...',
+    'La veritat és aquí... en algun lloc...',
+    'Bufant al cartutx...',
+    'Carregant... Feu un gir de barril!',
+    'Esperant la reaparició...',
+    'Paciència, pensa que Rodalies encara va més lent...',
+    "El pastís no és una mentida, simplement s'està carregant...",
+    'Tafanejant la pantalla de creació de personatge...',
+    'Un moment, trobo el meme adequat...',
+    "Prement 'A' per continuar...",
+    'Pasturant gats digitals...',
+    'Polint els píxels...',
+    'Buscant un acudit per a la pantalla de càrrega...',
+    'Distreu-vos amb aquesta frase enginyosa...',
+    'Gairebé a punt... probablement...',
+    'Els nostres hàmsters treballen tan ràpid com poden...',
+    'Donant un copet al cap a Cloudy...',
+    'Fent festes al gat...',
+    'Endavant les atxes...',
+    'Mai no us deixaré anar, mai no us decebré...',
+    'Tocant el baix...',
+    'Vaig a buscar ratafia...',
+    'Vaig a tota velocitat, vaig a tota marxa...',
+    'És la vida real? És sols fantasia?...',
+    'Tinc bon pressentiment sobre això...',
+    'Tocant el tigre...',
+    'Investigant els últims mems...',
+    'Pensant com fer això més enginyós...',
+    'Hmm... deixeu-me pensar...',
+    'Suant la cansalada...',
+    'Trient el fetge per la boca...',
+    "Posar fil a l'agulla...",
+    'Un moment, ho tenim a tocar..',
+    'Això és bufar i fer ampolles',
+    'Què pots fer amb un llapis trencat? Res, no té punta...',
+    'Aplicant manteniment percussiu...',
+    "Buscant l'orientació correcta de l'USB...",
+    'Assegurant que el fum màgic quedi dins dels cables...',
+    'Intentant sortir del Vim...',
+    'Girant la roda del hàmster...',
+    'Això no és un error, és una característica no documentada...',
+    'Endavant.',
+    'Tornaré... amb una resposta.',
+    'El meu altre procés és una TARDIS...',
+    'Posant oli als engranatges...',
+    'Deixant que els pensaments macerin...',
+    'Acabo de recordar on he deixat les claus...',
+    "Ponderant l'orbe...",
+    'He vist coses que no creuríeu... com un usuari que llegeix els missatges de càrrega.',
+    'Iniciant la mirada pensativa...',
+    "Quin és el berenar preferit d'un computador? Xips micro.",
+    'Per què els programadors de Java porten ulleres? Perquè no veuen en C#.',
+    'Carregant el làser... piu piu!',
+    'Dividint per zero... és broma!',
+    'Buscant un supervisor adult... és a dir, processant.',
+    'Fent que faci xup xup.',
+    'Emmarcant... perquè fins i tot les IA necessiten un moment.',
+    'Entrellaçant partícules quàntiques per a una resposta més ràpida...',
+    'Polint el crom... dels algorismes.',
+    'No esteu entretinguts? (Hi estem treballant!)',
+    'Invocant els follets del codi... per ajudar, és clar.',
+    'Esperant que acabi el so del mòdem de marcació...',
+    "Recalibrant el mesurament de l'humor.",
+    'La meva altra pantalla de càrrega és fins i tot més divertida.',
+    'Estic bastant segur que hi ha un gat caminant per algun teclat...',
+    'Millorant... millorant... encara carregant.',
+    "No és un error, és una característica... d'aquesta pantalla de càrrega.",
+    'Heu provat apagar-ho i tornar-lo a encendre? (La pantalla de càrrega, no jo.)',
+    'Construint piló addicionals...',
+  ],
+
+  // ============================================================================
+  // Entrada de configuració d'extensions
+  // ============================================================================
+  'Enter value...': 'Introduïu el valor...',
+  'Enter sensitive value...': 'Introduïu el valor sensible...',
+  'Press Enter to submit, Escape to cancel':
+    'Premeu Retorn per enviar, Esc per cancel·lar',
+
+  // ============================================================================
+  // Eina de migració d'ordres
+  // ============================================================================
+  'Markdown file already exists: {{filename}}':
+    'El fitxer Markdown ja existeix: {{filename}}',
+  'TOML Command Format Deprecation Notice':
+    "Avís d'obsolescència del format d'ordres TOML",
+  'Found {{count}} command file(s) in TOML format:':
+    "S'ha(n) trobat {{count}} fitxer(s) d'ordres en format TOML:",
+  'The TOML format for commands is being deprecated in favor of Markdown format.':
+    "El format TOML per a ordres s'està fent obsolet en favor del format Markdown.",
+  'Markdown format is more readable and easier to edit.':
+    "El format Markdown és més llegible i fàcil d'editar.",
+  'You can migrate these files automatically using:':
+    'Podeu migrar aquests fitxers automàticament usant:',
+  'Or manually convert each file:': 'O convertiu cada fitxer manualment:',
+  'TOML: prompt = "..." / description = "..."':
+    'TOML: prompt = "..." / description = "..."',
+  'Markdown: YAML frontmatter + content':
+    'Markdown: capçalera YAML + contingut',
+  'The migration tool will:': "L'eina de migració farà:",
+  'Convert TOML files to Markdown': 'Convertir fitxers TOML a Markdown',
+  'Create backups of original files':
+    'Crear còpies de seguretat dels fitxers originals',
+  'Preserve all command functionality':
+    'Preservar tota la funcionalitat de les ordres',
+  'TOML format will continue to work for now, but migration is recommended.':
+    'El format TOML seguirà funcionant de moment, però es recomana la migració.',
+
+  // ============================================================================
+  // Extensions - Ordre d'explorar
+  // ============================================================================
+  'Open extensions page in your browser':
+    "Obrir la pàgina d'extensions al vostre navegador",
+  'Unknown extensions source: {{source}}.':
+    "Font d'extensions desconeguda: {{source}}.",
+  'Would open extensions page in your browser: {{url}} (skipped in test environment)':
+    "Obriria la pàgina d'extensions al vostre navegador: {{url}} (omès en entorn de proves)",
+  'View available extensions at {{url}}':
+    'Veure les extensions disponibles a {{url}}',
+  'Opening extensions page in your browser: {{url}}':
+    "Obrint la pàgina d'extensions al vostre navegador: {{url}}",
+  'Failed to open browser. Check out the extensions gallery at {{url}}':
+    "Error en obrir el navegador. Visiteu la galeria d'extensions a {{url}}",
+
+  // ============================================================================
+  // Reintents / Límit de velocitat
+  // ============================================================================
+  'Rate limit error: {{reason}}': 'Error de límit de velocitat: {{reason}}',
+  'Retrying in {{seconds}} seconds… (attempt {{attempt}}/{{maxRetries}})':
+    'Reintentant en {{seconds}} segons… (intent {{attempt}}/{{maxRetries}})',
+  'Press Ctrl+Y to retry': 'Premeu Ctrl+Y per reintentar',
+  'No failed request to retry.':
+    'No hi ha cap sol·licitud fallida per reintentar.',
+  'to retry last request': "per reintentar l'última sol·licitud",
+
+  // ============================================================================
+  // Autenticació del Coding Plan
+  // ============================================================================
+  'API key cannot be empty.': 'La clau API no pot estar buida.',
+  'Invalid API key. Coding Plan API keys start with "sk-sp-". Please check.':
+    'Clau API no vàlida. Les claus API del Coding Plan comencen per "sk-sp-". Comproveu-la.',
+  'You can get your Coding Plan API key here':
+    'Podeu obtenir la vostra clau API del Coding Plan aquí',
+  'API key is stored in settings.env. You can migrate it to a .env file for better security.':
+    "La clau API s'emmagatzema a settings.env. Podeu migrar-la a un fitxer .env per una millor seguretat.",
+  'New model configurations are available for Alibaba Cloud Coding Plan. Update now?':
+    "Hi ha noves configuracions de model disponibles per al Coding Plan d'Alibaba Cloud. Actualitzeu ara?",
+  'Coding Plan configuration updated successfully. New models are now available.':
+    "La configuració del Coding Plan s'ha actualitzat correctament. Ara hi ha nous models disponibles.",
+  'Coding Plan API key not found. Please re-authenticate with Coding Plan.':
+    "No s'ha trobat la clau API del Coding Plan. Torneu a autenticar-vos amb el Coding Plan.",
+  'Failed to update Coding Plan configuration: {{message}}':
+    'Error en actualitzar la configuració del Coding Plan: {{message}}',
+
+  // ============================================================================
+  // Configuració de clau API personalitzada
+  // ============================================================================
+  'You can configure your API key and models in settings.json':
+    'Podeu configurar la vostra clau API i els models a settings.json',
+  'Refer to the documentation for setup instructions':
+    'Consulteu la documentació per a les instruccions de configuració',
+
+  // ============================================================================
+  // Diàleg d'autenticació - Títols i etiquetes
+  // ============================================================================
+  'Coding Plan': 'Coding Plan',
+  "Paste your api key of ModelStudio Coding Plan and you're all set!":
+    'Enganxeu la vostra clau API del Coding Plan de ModelStudio i ja esteu llest!',
+  Custom: 'Personalitzat',
+  'More instructions about configuring `modelProviders` manually.':
+    'Més instruccions sobre la configuració manual de `modelProviders`.',
+  'Select API-KEY configuration mode:':
+    'Seleccioneu el mode de configuració de la clau API:',
+  '(Press Escape to go back)': '(Premeu Esc per tornar enrere)',
+  '(Press Enter to submit, Escape to cancel)':
+    '(Premeu Retorn per enviar, Esc per cancel·lar)',
+  'Select Region for Coding Plan': 'Seleccioneu la regió per al Coding Plan',
+  'Choose based on where your account is registered':
+    "Trieu en funció d'on teniu registrat el compte",
+  'Enter Coding Plan API Key': 'Introduïu la clau API del Coding Plan',
+
+  // ============================================================================
+  // Actualitzacions internacionals del Coding Plan
+  // ============================================================================
+  'New model configurations are available for {{region}}. Update now?':
+    'Hi ha noves configuracions de model disponibles per a {{region}}. Actualitzeu ara?',
+  '{{region}} configuration updated successfully. Model switched to "{{model}}".':
+    'La configuració de {{region}} s\'ha actualitzat correctament. El model ha canviat a "{{model}}".',
+  'Authenticated successfully with {{region}}. API key and model configs saved to settings.json (backed up).':
+    "S'ha autenticat correctament amb {{region}}. La clau API i les configuracions del model s'han desat a settings.json (amb còpia de seguretat).",
+
+  // ============================================================================
+  // Component d'ús del context
+  // ============================================================================
+  'Context Usage': 'Ús del context',
+  '% used': '% usat',
+  '% context used': '% del context usat',
+  'Context exceeds limit! Use /compress or /clear to reduce.':
+    'El context supera el límit! Useu /compress o /clear per reduir-lo.',
+  'Use /compress or /clear': 'Useu /compress o /clear',
+  'No API response yet. Send a message to see actual usage.':
+    "Encara no hi ha cap resposta de l'API. Envieu un missatge per veure l'ús real.",
+  'Estimated pre-conversation overhead':
+    'Càrrega estimada prèvia a la conversa',
+  'Context window': 'Finestra de context',
+  tokens: 'tokens',
+  Used: 'Usat',
+  Free: 'Lliure',
+  'Autocompact buffer': 'Memòria intermèdia de compactació automàtica',
+  'Usage by category': 'Ús per categoria',
+  'System prompt': 'Missatge del sistema',
+  'Built-in tools': 'Eines integrades',
+  'MCP tools': 'Eines MCP',
+  'Memory files': 'Fitxers de memòria',
+  Skills: 'Habilitats',
+  Messages: 'Missatges',
+  'Show context window usage breakdown.':
+    "Mostrar el desglossament de l'ús de la finestra de context.",
+  'Run /context detail for per-item breakdown.':
+    'Executeu /context detail per a un desglossament per element.',
+  'Show context window usage breakdown. Use "/context detail" for per-item breakdown.':
+    'Mostrar el desglossament de l\'ús de la finestra de context. Useu "/context detail" per a un desglossament per element.',
+  'body loaded': 'cos carregat',
+  memory: 'memòria',
+  '{{region}} configuration updated successfully.':
+    "La configuració de {{region}} s'ha actualitzat correctament.",
+  'Authenticated successfully with {{region}}. API key and model configs saved to settings.json.':
+    "S'ha autenticat correctament amb {{region}}. La clau API i les configuracions del model s'han desat a settings.json.",
+  'Tip: Use /model to switch between available Coding Plan models.':
+    'Consell: Useu /model per canviar entre els models del Coding Plan disponibles.',
+
+  // ============================================================================
+  // Eina de preguntes a l'usuari
+  // ============================================================================
+  'Please answer the following question(s):':
+    'Responeu la(es) pregunta(es) següent(s):',
+  'Cannot ask user questions in non-interactive mode. Please run in interactive mode to use this tool.':
+    "No es poden fer preguntes a l'usuari en mode no interactiu. Executeu en mode interactiu per usar aquesta eina.",
+  'User declined to answer the questions.':
+    "L'usuari ha declinat respondre les preguntes.",
+  'User has provided the following answers:':
+    "L'usuari ha proporcionat les respostes següents:",
+  'Failed to process user answers:':
+    "Error en processar les respostes de l'usuari:",
+  'Type something...': 'Escriviu alguna cosa...',
+  Submit: 'Enviar',
+  'Submit answers': 'Enviar respostes',
+  Cancel: 'Cancel·lar',
+  'Your answers:': 'Les vostres respostes:',
+  '(not answered)': '(sense resposta)',
+  'Ready to submit your answers?':
+    'Preparats per enviar les vostres respostes?',
+  '↑/↓: Navigate | ←/→: Switch tabs | Enter: Select':
+    '↑/↓: Navegar | ←/→: Canviar pestanyes | Retorn: Seleccionar',
+  '↑/↓: Navigate | ←/→: Switch tabs | Space/Enter: Toggle | Esc: Cancel':
+    '↑/↓: Navegar | ←/→: Canviar pestanyes | Espai/Retorn: Canviar | Esc: Cancel·lar',
+  '↑/↓: Navigate | Space/Enter: Toggle | Esc: Cancel':
+    '↑/↓: Navegar | Espai/Retorn: Canviar | Esc: Cancel·lar',
+  '↑/↓: Navigate | Enter: Select | Esc: Cancel':
+    '↑/↓: Navegar | Retorn: Seleccionar | Esc: Cancel·lar',
+
+  // ============================================================================
+  // Ordres - Autenticació
+  // ============================================================================
+  'Configure Qwen authentication information with Qwen-OAuth or Alibaba Cloud Coding Plan':
+    "Configurar la informació d'autenticació de Qwen amb Qwen-OAuth o el Coding Plan d'Alibaba Cloud",
+  'Authenticate using Qwen OAuth': 'Autenticar-se usant Qwen OAuth',
+  'Authenticate using Alibaba Cloud Coding Plan':
+    "Autenticar-se usant el Coding Plan d'Alibaba Cloud",
+  'Region for Coding Plan (china/global)':
+    'Regió per al Coding Plan (china/global)',
+  'API key for Coding Plan': 'Clau API per al Coding Plan',
+  'Show current authentication status': "Mostrar l'estat d'autenticació actual",
+  'Authentication completed successfully.':
+    "L'autenticació s'ha completat correctament.",
+  'Starting Qwen OAuth authentication...':
+    "Iniciant l'autenticació Qwen OAuth...",
+  'Successfully authenticated with Qwen OAuth.':
+    "S'ha autenticat correctament amb Qwen OAuth.",
+  'Failed to authenticate with Qwen OAuth: {{error}}':
+    'Error en autenticar-se amb Qwen OAuth: {{error}}',
+  'Processing Alibaba Cloud Coding Plan authentication...':
+    "Processant l'autenticació del Coding Plan d'Alibaba Cloud...",
+  'Successfully authenticated with Alibaba Cloud Coding Plan.':
+    "S'ha autenticat correctament amb el Coding Plan d'Alibaba Cloud.",
+  'Failed to authenticate with Coding Plan: {{error}}':
+    'Error en autenticar-se amb el Coding Plan: {{error}}',
+  '中国 (China)': '中国 (China)',
+  '阿里云百炼 (aliyun.com)': '阿里云百炼 (aliyun.com)',
+  Global: 'Global',
+  'Alibaba Cloud (alibabacloud.com)': 'Alibaba Cloud (alibabacloud.com)',
+  'Select region for Coding Plan:': 'Seleccioneu la regió per al Coding Plan:',
+  'Enter your Coding Plan API key: ':
+    'Introduïu la vostra clau API del Coding Plan: ',
+  'Select authentication method:': "Seleccioneu el mètode d'autenticació:",
+  '\n=== Authentication Status ===\n': "\n=== Estat d'autenticació ===\n",
+  '⚠️  No authentication method configured.\n':
+    "⚠️  Cap mètode d'autenticació configurat.\n",
+  'Run one of the following commands to get started:\n':
+    'Executeu una de les ordres següents per començar:\n',
+  '  qwen auth qwen-oauth     - Authenticate with Qwen OAuth (discontinued)':
+    '  qwen auth qwen-oauth     - Autenticar-se amb Qwen OAuth (descontinuat)',
+  '  qwen auth coding-plan      - Authenticate with Alibaba Cloud Coding Plan\n':
+    "  qwen auth coding-plan      - Autenticar-se amb el Coding Plan d'Alibaba Cloud\n",
+  'Or simply run:': 'O simplement executeu:',
+  '  qwen auth                - Interactive authentication setup\n':
+    "  qwen auth                - Configuració interactiva de l'autenticació\n",
+  '✓ Authentication Method: Qwen OAuth': "✓ Mètode d'autenticació: Qwen OAuth",
+  '  Type: Free tier (discontinued 2026-04-15)':
+    '  Tipus: Nivell gratuït (descontinuat el 15-04-2026)',
+  '  Limit: No longer available': '  Límit: Ja no disponible',
+  'Qwen OAuth free tier was discontinued on 2026-04-15. Run /auth to switch to Coding Plan, OpenRouter, Fireworks AI, or another provider.':
+    'El nivell gratuït de Qwen OAuth es va descontinuar el 15-04-2026. Executeu /auth per canviar al Coding Plan, OpenRouter, Fireworks AI o un altre proveïdor.',
+  '  Models: Qwen latest models\n': '  Models: Últims models Qwen\n',
+  '✓ Authentication Method: Alibaba Cloud Coding Plan':
+    "✓ Mètode d'autenticació: Coding Plan d'Alibaba Cloud",
+  '中国 (China) - 阿里云百炼': '中国 (China) - 阿里云百炼',
+  'Global - Alibaba Cloud': 'Global - Alibaba Cloud',
+  '  Region: {{region}}': '  Regió: {{region}}',
+  '  Current Model: {{model}}': '  Model actual: {{model}}',
+  '  Config Version: {{version}}': '  Versió de configuració: {{version}}',
+  '  Status: API key configured\n': '  Estat: Clau API configurada\n',
+  '⚠️  Authentication Method: Alibaba Cloud Coding Plan (Incomplete)':
+    "⚠️  Mètode d'autenticació: Coding Plan d'Alibaba Cloud (Incomplet)",
+  '  Issue: API key not found in environment or settings\n':
+    "  Problema: Clau API no trobada a l'entorn o la configuració\n",
+  '  Run `qwen auth coding-plan` to re-configure.\n':
+    '  Executeu `qwen auth coding-plan` per tornar a configurar.\n',
+  '✓ Authentication Method: {{type}}': "✓ Mètode d'autenticació: {{type}}",
+  '  Status: Configured\n': '  Estat: Configurat\n',
+  'Failed to check authentication status: {{error}}':
+    "Error en comprovar l'estat d'autenticació: {{error}}",
+  'Select an option:': 'Seleccioneu una opció:',
+  'Raw mode not available. Please run in an interactive terminal.':
+    'El mode raw no està disponible. Executeu en un terminal interactiu.',
+  '(Use ↑ ↓ arrows to navigate, Enter to select, Ctrl+C to exit)\n':
+    '(Useu les fletxes ↑ ↓ per navegar, Retorn per seleccionar, Ctrl+C per sortir)\n',
+  compact: 'compacte',
+  'compact mode: on (Ctrl+O off)':
+    'mode compacte: activat (Ctrl+O per desactivar)',
+  'Hide tool output and thinking for a cleaner view (toggle with Ctrl+O).':
+    'Amagueu la sortida de les eines i el pensament per a una vista més neta (canvieu amb Ctrl+O).',
+  'Press Ctrl+O to show full tool output':
+    'Premeu Ctrl+O per mostrar la sortida completa de les eines',
+
+  'Switch to plan mode or exit plan mode':
+    'Canviar al mode de planificació o sortir del mode de planificació',
+  'Exited plan mode. Previous approval mode restored.':
+    "S'ha sortit del mode de planificació. S'ha restaurat el mode d'aprovació anterior.",
+  'Enabled plan mode. The agent will analyze and plan without executing tools.':
+    "S'ha activat el mode de planificació. L'agent analitzarà i planificarà sense executar eines.",
+  'Already in plan mode. Use "/plan exit" to exit plan mode.':
+    'Ja esteu en mode de planificació. Useu "/plan exit" per sortir del mode de planificació.',
+  'Not in plan mode. Use "/plan" to enter plan mode first.':
+    'No esteu en mode de planificació. Useu "/plan" per entrar al mode de planificació primer.',
+
+  "Set up Qwen Code's status line UI":
+    "Configurar la interfície de la barra d'estat de Qwen Code",
+};
diff --git a/packages/cli/src/i18n/locales/de.js b/packages/cli/src/i18n/locales/de.js
index d4b6e94bf..4cc0d50e5 100644
--- a/packages/cli/src/i18n/locales/de.js
+++ b/packages/cli/src/i18n/locales/de.js
@@ -1301,6 +1301,8 @@ export default {
     'Kostenpflichtig \u00B7 Bis zu 6.000 Anfragen/5 Std. \u00B7 Alle Alibaba Cloud Coding Plan Modelle',
   'Alibaba Cloud Coding Plan': 'Alibaba Cloud Coding Plan',
   'Bring your own API key': 'Eigenen API-Schlüssel verwenden',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    'Browserbasierte Authentifizierung mit externen Anbietern (z. B. OpenRouter, ModelScope)',
   'API-KEY': 'API-KEY',
   'Use coding plan credentials or your own api-keys/providers.':
     'Verwenden Sie Coding Plan-Anmeldedaten oder Ihre eigenen API-Schlüssel/Anbieter.',
diff --git a/packages/cli/src/i18n/locales/en.js b/packages/cli/src/i18n/locales/en.js
index c2a427bdb..268aa5048 100644
--- a/packages/cli/src/i18n/locales/en.js
+++ b/packages/cli/src/i18n/locales/en.js
@@ -1361,6 +1361,8 @@ export default {
     'Paid \u00B7 Up to 6,000 requests/5 hrs \u00B7 All Alibaba Cloud Coding Plan Models',
   'Alibaba Cloud Coding Plan': 'Alibaba Cloud Coding Plan',
   'Bring your own API key': 'Bring your own API key',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)',
   'API-KEY': 'API-KEY',
   'Use coding plan credentials or your own api-keys/providers.':
     'Use coding plan credentials or your own api-keys/providers.',
diff --git a/packages/cli/src/i18n/locales/fr.js b/packages/cli/src/i18n/locales/fr.js
index 138f7bf8d..433b61f4a 100644
--- a/packages/cli/src/i18n/locales/fr.js
+++ b/packages/cli/src/i18n/locales/fr.js
@@ -1345,6 +1345,8 @@ export default {
     "Payant · Jusqu'à 6 000 requêtes/5h · Tous les modèles Alibaba Cloud Coding Plan",
   'Alibaba Cloud Coding Plan': 'Plan de codage Alibaba Cloud',
   'Bring your own API key': 'Apportez votre propre clé API',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    'Authentification basée sur le navigateur avec des fournisseurs tiers (par exemple OpenRouter, ModelScope)',
   'API-KEY': 'CLÉ-API',
   'Use coding plan credentials or your own api-keys/providers.':
     'Utilisez les identifiants du plan de codage ou vos propres clés API/fournisseurs.',
diff --git a/packages/cli/src/i18n/locales/ja.js b/packages/cli/src/i18n/locales/ja.js
index 2c7225639..94a4e5ffc 100644
--- a/packages/cli/src/i18n/locales/ja.js
+++ b/packages/cli/src/i18n/locales/ja.js
@@ -1022,6 +1022,8 @@ export default {
     '有料 \u00B7 5時間最大6,000リクエスト \u00B7 すべての Alibaba Cloud Coding Plan モデル',
   'Alibaba Cloud Coding Plan': 'Alibaba Cloud Coding Plan',
   'Bring your own API key': '自分のAPIキーを使用',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    'サードパーティプロバイダーによるブラウザベースの認証（例：OpenRouter、ModelScope）',
   'API-KEY': 'API-KEY',
   'Use coding plan credentials or your own api-keys/providers.':
     'Coding Planの認証情報またはご自身のAPIキー/プロバイダーをご利用ください。',
diff --git a/packages/cli/src/i18n/locales/pt.js b/packages/cli/src/i18n/locales/pt.js
index db681a19a..74e9630dc 100644
--- a/packages/cli/src/i18n/locales/pt.js
+++ b/packages/cli/src/i18n/locales/pt.js
@@ -1309,6 +1309,8 @@ export default {
     'Pago \u00B7 Até 6.000 solicitações/5 hrs \u00B7 Todos os modelos Alibaba Cloud Coding Plan',
   'Alibaba Cloud Coding Plan': 'Alibaba Cloud Coding Plan',
   'Bring your own API key': 'Traga sua própria chave API',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    'Autenticação baseada em navegador com provedores terceiros (por exemplo, OpenRouter, ModelScope)',
   'API-KEY': 'API-KEY',
   'Use coding plan credentials or your own api-keys/providers.':
     'Use credenciais do Coding Plan ou suas próprias chaves API/provedores.',
diff --git a/packages/cli/src/i18n/locales/ru.js b/packages/cli/src/i18n/locales/ru.js
index ed2af31b3..f2071ffed 100644
--- a/packages/cli/src/i18n/locales/ru.js
+++ b/packages/cli/src/i18n/locales/ru.js
@@ -1231,6 +1231,8 @@ export default {
     'Платно \u00B7 До 6 000 запросов/5 часов \u00B7 Все модели Alibaba Cloud Coding Plan',
   'Alibaba Cloud Coding Plan': 'Alibaba Cloud Coding Plan',
   'Bring your own API key': 'Используйте свой API-ключ',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    'Браузерная аутентификация с использованием сторонних провайдеров (например, OpenRouter, ModelScope)',
   'API-KEY': 'API-KEY',
   'Use coding plan credentials or your own api-keys/providers.':
     'Используйте учетные данные Coding Plan или свои собственные API-ключи/провайдеры.',
diff --git a/packages/cli/src/i18n/locales/zh-TW.js b/packages/cli/src/i18n/locales/zh-TW.js
index 9460ba71d..5ab279b51 100644
--- a/packages/cli/src/i18n/locales/zh-TW.js
+++ b/packages/cli/src/i18n/locales/zh-TW.js
@@ -1141,6 +1141,8 @@ export default {
   'Alibaba Cloud Coding Plan': '阿里雲百鍊 Coding Plan',
   'Bring your own API key': '使用自己的 API 密鑰',
   'API-KEY': 'API-KEY',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    '基於瀏覽器的第三方提供商認證（例如 OpenRouter、ModelScope）',
   'Use coding plan credentials or your own api-keys/providers.':
     '使用 Coding Plan 憑證或您自己的 API 密鑰/提供商。',
   OpenAI: 'OpenAI',
diff --git a/packages/cli/src/i18n/locales/zh.js b/packages/cli/src/i18n/locales/zh.js
index 4c3c98ba6..701732e87 100644
--- a/packages/cli/src/i18n/locales/zh.js
+++ b/packages/cli/src/i18n/locales/zh.js
@@ -1291,6 +1291,8 @@ export default {
     '付费 \u00B7 每 5 小时最多 6,000 次请求 \u00B7 支持阿里云百炼 Coding Plan 全部模型',
   'Alibaba Cloud Coding Plan': '阿里云百炼 Coding Plan',
   'Bring your own API key': '使用自己的 API 密钥',
+  'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)':
+    '基于浏览器的第三方提供商认证（例如 OpenRouter、ModelScope）',
   'Use coding plan credentials or your own api-keys/providers.':
     '使用 Coding Plan 凭证或您自己的 API 密钥/提供商。',
   OpenAI: 'OpenAI',
diff --git a/packages/cli/src/nonInteractiveCli.test.ts b/packages/cli/src/nonInteractiveCli.test.ts
index c1f8ab9ba..b2757d845 100644
--- a/packages/cli/src/nonInteractiveCli.test.ts
+++ b/packages/cli/src/nonInteractiveCli.test.ts
@@ -28,6 +28,8 @@ import { vi, type Mock, type MockInstance } from 'vitest';
 import type { LoadedSettings } from './config/settings.js';
 import { CommandKind, type ExecutionMode } from './ui/commands/types.js';
 import { filterCommandsForMode } from './services/commandUtils.js';
+import { _resetCleanupFunctionsForTest } from './utils/cleanup.js';
+import { _resetExitLatchForTest } from './utils/errors.js';
 
 // Mock core modules
 vi.mock('./ui/hooks/atCommandProcessor.js');
@@ -79,6 +81,12 @@ describe('runNonInteractive', () => {
   let mockGetDebugResponses: Mock;
 
   beforeEach(async () => {
+    // Reset module-level state from any prior test in this file. Without
+    // these resets the once-set exit latch parks subsequent JSON-mode
+    // handleError tests in the never-resolving promise (5s vitest timeout).
+    _resetCleanupFunctionsForTest();
+    _resetExitLatchForTest();
+
     mockCoreExecuteToolCall = vi.mocked(executeToolCall);
     mockShutdownTelemetry = vi.mocked(shutdownTelemetry);
     mockGetCommandsForMode.mockImplementation((mode: ExecutionMode) =>
@@ -158,7 +166,9 @@ describe('runNonInteractive', () => {
       getBackgroundTaskRegistry: vi.fn().mockReturnValue({
         setNotificationCallback: vi.fn(),
         setRegisterCallback: vi.fn(),
-        getRunning: vi.fn().mockReturnValue([]),
+        getAll: vi.fn().mockReturnValue([]),
+        hasUnfinalizedTasks: vi.fn().mockReturnValue(false),
+        abortAll: vi.fn(),
       }),
     } as unknown as Config;
 
diff --git a/packages/cli/src/nonInteractiveCli.ts b/packages/cli/src/nonInteractiveCli.ts
index 23965c7d9..5232f6096 100644
--- a/packages/cli/src/nonInteractiveCli.ts
+++ b/packages/cli/src/nonInteractiveCli.ts
@@ -5,7 +5,7 @@
  */
 
 import type {
-  BackgroundAgentStatus,
+  BackgroundTaskStatus,
   Config,
   ToolCallRequestInfo,
 } from '@qwen-code/qwen-code-core';
@@ -302,7 +302,7 @@ export async function runNonInteractive(
         sdkNotification?: {
           task_id: string;
           tool_use_id?: string;
-          status: BackgroundAgentStatus;
+          status: BackgroundTaskStatus;
           usage?: {
             total_tokens: number;
             tool_uses: number;
@@ -349,7 +349,7 @@ export async function runNonInteractive(
           config.getMaxSessionTurns() >= 0 &&
           turnCount > config.getMaxSessionTurns()
         ) {
-          handleMaxTurnsExceededError(config);
+          await handleMaxTurnsExceededError(config);
         }
 
         const toolCallRequests: ToolCallRequestInfo[] = [];
@@ -372,7 +372,7 @@ export async function runNonInteractive(
 
         for await (const event of responseStream) {
           if (abortController.signal.aborted) {
-            handleCancellationError(config);
+            await handleCancellationError(config);
           }
           // Use adapter for all event processing
           adapter.processEvent(event);
@@ -498,7 +498,7 @@ export async function runNonInteractive(
               config.getMaxSessionTurns() >= 0 &&
               turnCount > config.getMaxSessionTurns()
             ) {
-              handleMaxTurnsExceededError(config);
+              await handleMaxTurnsExceededError(config);
             }
 
             const inputFormat =
@@ -711,11 +711,15 @@ export async function runNonInteractive(
               while (localQueue.length > 0) {
                 emitNotificationToSdk(localQueue.shift()!);
               }
-              handleCancellationError(config);
+              await handleCancellationError(config);
             }
             await drainLocalQueue();
-            const running = registry.getRunning();
-            if (running.length === 0 && localQueue.length === 0) break;
+            // Wait for every task's terminal notification, not just the
+            // running ones: cancel() marks status 'cancelled' synchronously
+            // but the notification is emitted later by the natural handler,
+            // and SDK consumers need every task_started paired with one.
+            if (!registry.hasUnfinalizedTasks() && localQueue.length === 0)
+              break;
             await new Promise((r) => setTimeout(r, 100));
           }
 
@@ -766,7 +770,7 @@ export async function runNonInteractive(
         usage,
         stats,
       });
-      handleError(error, config);
+      await handleError(error, config);
     } finally {
       const reg = config.getBackgroundTaskRegistry();
       reg.setNotificationCallback(undefined);
diff --git a/packages/cli/src/services/BuiltinCommandLoader.ts b/packages/cli/src/services/BuiltinCommandLoader.ts
index cdde266b8..68d533e2a 100644
--- a/packages/cli/src/services/BuiltinCommandLoader.ts
+++ b/packages/cli/src/services/BuiltinCommandLoader.ts
@@ -8,6 +8,7 @@ import type { ICommandLoader } from './types.js';
 import type { SlashCommand } from '../ui/commands/types.js';
 import type { Config } from '@qwen-code/qwen-code-core';
 import { aboutCommand } from '../ui/commands/aboutCommand.js';
+import { tasksCommand } from '../ui/commands/tasksCommand.js';
 import { agentsCommand } from '../ui/commands/agentsCommand.js';
 import { arenaCommand } from '../ui/commands/arenaCommand.js';
 import { approvalModeCommand } from '../ui/commands/approvalModeCommand.js';
@@ -36,6 +37,7 @@ import { dreamCommand } from '../ui/commands/dreamCommand.js';
 import { forgetCommand } from '../ui/commands/forgetCommand.js';
 import { memoryCommand } from '../ui/commands/memoryCommand.js';
 import { modelCommand } from '../ui/commands/modelCommand.js';
+import { manageModelsCommand } from '../ui/commands/manageModelsCommand.js';
 import { rememberCommand } from '../ui/commands/rememberCommand.js';
 import { planCommand } from '../ui/commands/planCommand.js';
 import { permissionsCommand } from '../ui/commands/permissionsCommand.js';
@@ -45,6 +47,7 @@ import { recapCommand } from '../ui/commands/recapCommand.js';
 import { renameCommand } from '../ui/commands/renameCommand.js';
 import { restoreCommand } from '../ui/commands/restoreCommand.js';
 import { resumeCommand } from '../ui/commands/resumeCommand.js';
+import { rewindCommand } from '../ui/commands/rewindCommand.js';
 import { settingsCommand } from '../ui/commands/settingsCommand.js';
 import { skillsCommand } from '../ui/commands/skillsCommand.js';
 import { statsCommand } from '../ui/commands/statsCommand.js';
@@ -90,6 +93,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
     const allDefinitions: Array<SlashCommand | null> = [
       aboutCommand,
       agentsCommand,
+      tasksCommand,
       arenaCommand,
       approvalModeCommand,
       authCommand,
@@ -117,6 +121,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
         : []),
       memoryCommand,
       modelCommand,
+      manageModelsCommand,
       rememberCommand,
       planCommand,
       permissionsCommand,
@@ -126,6 +131,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
       renameCommand,
       restoreCommand(this.config),
       resumeCommand,
+      rewindCommand,
       skillsCommand,
       statsCommand,
       summaryCommand,
diff --git a/packages/cli/src/services/BundledSkillLoader.test.ts b/packages/cli/src/services/BundledSkillLoader.test.ts
index a2bd4544c..5c99f3afd 100644
--- a/packages/cli/src/services/BundledSkillLoader.test.ts
+++ b/packages/cli/src/services/BundledSkillLoader.test.ts
@@ -69,6 +69,16 @@ describe('BundledSkillLoader', () => {
     expect(mockSkillManager.listSkills).not.toHaveBeenCalled();
   });
 
+  it('should propagate argumentHint from bundled skills to slash commands', async () => {
+    const skill = makeSkill({ argumentHint: '[topic]' });
+    mockSkillManager.listSkills.mockResolvedValue([skill]);
+
+    const loader = new BundledSkillLoader(mockConfig);
+    const commands = await loader.loadCommands(signal);
+
+    expect(commands[0]?.argumentHint).toBe('[topic]');
+  });
+
   it('should load bundled skills as slash commands', async () => {
     const skill = makeSkill();
     mockSkillManager.listSkills.mockResolvedValue([skill]);
diff --git a/packages/cli/src/services/BundledSkillLoader.ts b/packages/cli/src/services/BundledSkillLoader.ts
index 5ea6682b5..d5f36c93e 100644
--- a/packages/cli/src/services/BundledSkillLoader.ts
+++ b/packages/cli/src/services/BundledSkillLoader.ts
@@ -66,6 +66,7 @@ export class BundledSkillLoader implements ICommandLoader {
         source: 'bundled-skill' as const,
         sourceLabel: 'Skill',
         modelInvocable: !skill.disableModelInvocation,
+        argumentHint: skill.argumentHint,
         whenToUse: skill.whenToUse,
         action: async (context, _args): Promise<SlashCommandActionReturn> => {
           // Resolve template variables in skill body
diff --git a/packages/cli/src/services/FileCommandLoader-markdown.test.ts b/packages/cli/src/services/FileCommandLoader-markdown.test.ts
index 737cc39db..816bc1269 100644
--- a/packages/cli/src/services/FileCommandLoader-markdown.test.ts
+++ b/packages/cli/src/services/FileCommandLoader-markdown.test.ts
@@ -27,6 +27,7 @@ describe('FileCommandLoader - Markdown support', () => {
     // Create a test markdown command file
     const mdContent = `---
 description: Test markdown command
+argument-hint: "[issue-number]"
 ---
 
 This is a test prompt from markdown.`;
@@ -47,6 +48,7 @@ This is a test prompt from markdown.`;
       expect(commands).toHaveLength(1);
       expect(commands[0].name).toBe('test-command');
       expect(commands[0].description).toBe('Test markdown command');
+      expect(commands[0].argumentHint).toBe('[issue-number]');
     } finally {
       // Restore original method
       loader['getCommandDirectories'] = originalMethod;
diff --git a/packages/cli/src/services/FileCommandLoader.ts b/packages/cli/src/services/FileCommandLoader.ts
index ba03c9567..61bb78210 100644
--- a/packages/cli/src/services/FileCommandLoader.ts
+++ b/packages/cli/src/services/FileCommandLoader.ts
@@ -355,6 +355,7 @@ export class FileCommandLoader implements ICommandLoader {
           ? validDef.frontmatter.description
           : undefined,
       whenToUse: validDef.frontmatter?.when_to_use,
+      argumentHint: validDef.frontmatter?.['argument-hint'],
       disableModelInvocation:
         validDef.frontmatter?.['disable-model-invocation'],
     };
diff --git a/packages/cli/src/services/SkillCommandLoader.test.ts b/packages/cli/src/services/SkillCommandLoader.test.ts
index 00c189123..a884d2c4f 100644
--- a/packages/cli/src/services/SkillCommandLoader.test.ts
+++ b/packages/cli/src/services/SkillCommandLoader.test.ts
@@ -58,6 +58,19 @@ describe('SkillCommandLoader', () => {
     expect(mockSkillManager.listSkills).not.toHaveBeenCalled();
   });
 
+  it('should propagate argumentHint from skills to slash commands', async () => {
+    const skill = makeSkill({ argumentHint: '[topic]' });
+    mockSkillManager.listSkills.mockImplementation(
+      ({ level }: { level: string }) =>
+        Promise.resolve(level === 'user' ? [skill] : []),
+    );
+
+    const loader = new SkillCommandLoader(mockConfig);
+    const commands = await loader.loadCommands(signal);
+
+    expect(commands[0]?.argumentHint).toBe('[topic]');
+  });
+
   it('should query user, project, and extension levels', async () => {
     const loader = new SkillCommandLoader(mockConfig);
     await loader.loadCommands(signal);
diff --git a/packages/cli/src/services/SkillCommandLoader.ts b/packages/cli/src/services/SkillCommandLoader.ts
index 58e297633..daf7bc918 100644
--- a/packages/cli/src/services/SkillCommandLoader.ts
+++ b/packages/cli/src/services/SkillCommandLoader.ts
@@ -84,6 +84,7 @@ export class SkillCommandLoader implements ICommandLoader {
             : 'skill-dir-command') as CommandSource,
           sourceLabel,
           modelInvocable,
+          argumentHint: skill.argumentHint,
           whenToUse: skill.whenToUse,
           action: async (context, _args): Promise<SlashCommandActionReturn> => {
             const body = skill.body;
diff --git a/packages/cli/src/services/command-factory.ts b/packages/cli/src/services/command-factory.ts
index 1aa363254..ef3f91bee 100644
--- a/packages/cli/src/services/command-factory.ts
+++ b/packages/cli/src/services/command-factory.ts
@@ -37,6 +37,7 @@ import { AtFileProcessor } from './prompt-processors/atFileProcessor.js';
 export interface CommandDefinition {
   prompt: string;
   description?: string;
+  argumentHint?: string;
   whenToUse?: string;
   disableModelInvocation?: boolean;
 }
@@ -121,6 +122,7 @@ export function createSlashCommandFromDefinition(
     modelInvocable: definition.disableModelInvocation
       ? false
       : !extensionName || !!(definition.description || definition.whenToUse),
+    argumentHint: definition.argumentHint,
     whenToUse: definition.whenToUse,
     action: async (
       context: CommandContext,
diff --git a/packages/cli/src/services/markdown-command-parser.test.ts b/packages/cli/src/services/markdown-command-parser.test.ts
index bbefa43a4..da71db1a8 100644
--- a/packages/cli/src/services/markdown-command-parser.test.ts
+++ b/packages/cli/src/services/markdown-command-parser.test.ts
@@ -14,6 +14,7 @@ describe('parseMarkdownCommand', () => {
   it('should parse markdown with YAML frontmatter', () => {
     const content = `---
 description: Test command
+argument-hint: "[issue-number]"
 ---
 
 This is the prompt content.`;
@@ -23,6 +24,7 @@ This is the prompt content.`;
     expect(result).toEqual({
       frontmatter: {
         description: 'Test command',
+        'argument-hint': '[issue-number]',
       },
       prompt: 'This is the prompt content.',
     });
@@ -146,6 +148,7 @@ describe('MarkdownCommandDefSchema', () => {
     const validDef = {
       frontmatter: {
         description: 'Test description',
+        'argument-hint': '[issue-number]',
       },
       prompt: 'Test prompt',
     };
diff --git a/packages/cli/src/services/markdown-command-parser.ts b/packages/cli/src/services/markdown-command-parser.ts
index bfe5a3e2b..8e0e0139c 100644
--- a/packages/cli/src/services/markdown-command-parser.ts
+++ b/packages/cli/src/services/markdown-command-parser.ts
@@ -18,6 +18,7 @@ export const MarkdownCommandDefSchema = z.object({
   frontmatter: z
     .object({
       description: z.string().optional(),
+      'argument-hint': z.string().optional(),
       when_to_use: z.string().optional(),
       'disable-model-invocation': z.boolean().optional(),
     })
diff --git a/packages/cli/src/services/notificationService.test.ts b/packages/cli/src/services/notificationService.test.ts
new file mode 100644
index 000000000..dfbce64e9
--- /dev/null
+++ b/packages/cli/src/services/notificationService.test.ts
@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { sendNotification } from './notificationService.js';
+import type { TerminalNotification } from '../ui/hooks/useTerminalNotification.js';
+
+vi.mock('../utils/osc.js', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../utils/osc.js')>();
+  return {
+    ...original,
+    detectTerminal: vi.fn(() => 'unknown'),
+    generateKittyId: vi.fn(() => 42),
+  };
+});
+
+const { detectTerminal: mockedDetectTerminal } = await import(
+  '../utils/osc.js'
+);
+
+function createMockTerminal(): TerminalNotification {
+  return {
+    notifyITerm2: vi.fn(),
+    notifyKitty: vi.fn(),
+    notifyGhostty: vi.fn(),
+    notifyBell: vi.fn(),
+  };
+}
+
+describe('sendNotification', () => {
+  let terminal: TerminalNotification;
+
+  const origIsTTY = process.stdout.isTTY;
+
+  beforeEach(() => {
+    terminal = createMockTerminal();
+    vi.mocked(mockedDetectTerminal).mockReturnValue('unknown');
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: true,
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: origIsTTY,
+      configurable: true,
+    });
+  });
+
+  it('returns disabled when not enabled', () => {
+    const result = sendNotification({ message: 'test' }, terminal, false);
+    expect(result).toBe('disabled');
+    expect(terminal.notifyBell).not.toHaveBeenCalled();
+  });
+
+  it('sends iTerm2 notification for iTerm.app', () => {
+    vi.mocked(mockedDetectTerminal).mockReturnValue('iTerm.app');
+    const result = sendNotification(
+      { message: 'test', title: 'Title' },
+      terminal,
+      true,
+    );
+    expect(result).toBe('iterm2');
+    expect(terminal.notifyITerm2).toHaveBeenCalledWith({
+      message: 'test',
+      title: 'Title',
+    });
+  });
+
+  it('sends kitty notification for kitty', () => {
+    vi.mocked(mockedDetectTerminal).mockReturnValue('kitty');
+    const result = sendNotification(
+      { message: 'test', title: 'Title' },
+      terminal,
+      true,
+    );
+    expect(result).toBe('kitty');
+    expect(terminal.notifyKitty).toHaveBeenCalledWith({
+      message: 'test',
+      title: 'Title',
+      id: 42,
+    });
+  });
+
+  it('sends ghostty notification for ghostty', () => {
+    vi.mocked(mockedDetectTerminal).mockReturnValue('ghostty');
+    const result = sendNotification(
+      { message: 'test', title: 'Title' },
+      terminal,
+      true,
+    );
+    expect(result).toBe('ghostty');
+    expect(terminal.notifyGhostty).toHaveBeenCalledWith({
+      message: 'test',
+      title: 'Title',
+    });
+  });
+
+  it('falls back to bell for Apple_Terminal', () => {
+    vi.mocked(mockedDetectTerminal).mockReturnValue('Apple_Terminal');
+    const result = sendNotification({ message: 'test' }, terminal, true);
+    expect(result).toBe('terminal_bell');
+    expect(terminal.notifyBell).toHaveBeenCalled();
+  });
+
+  it('falls back to bell for unknown terminal', () => {
+    vi.mocked(mockedDetectTerminal).mockReturnValue('unknown');
+    const result = sendNotification({ message: 'test' }, terminal, true);
+    expect(result).toBe('terminal_bell');
+    expect(terminal.notifyBell).toHaveBeenCalled();
+  });
+
+  it('uses default title when not provided', () => {
+    vi.mocked(mockedDetectTerminal).mockReturnValue('iTerm.app');
+    sendNotification({ message: 'test' }, terminal, true);
+    expect(terminal.notifyITerm2).toHaveBeenCalledWith({
+      message: 'test',
+      title: 'Qwen Code',
+    });
+  });
+
+  it('returns error when notification method throws', () => {
+    vi.mocked(mockedDetectTerminal).mockReturnValue('iTerm.app');
+    vi.mocked(terminal.notifyITerm2).mockImplementation(() => {
+      throw new Error('write failed');
+    });
+    const result = sendNotification({ message: 'test' }, terminal, true);
+    expect(result).toBe('error');
+  });
+
+  it('returns disabled when stdout is not a TTY', () => {
+    Object.defineProperty(process.stdout, 'isTTY', {
+      value: false,
+      configurable: true,
+    });
+    const result = sendNotification({ message: 'test' }, terminal, true);
+    expect(result).toBe('disabled');
+    expect(terminal.notifyBell).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/cli/src/services/notificationService.ts b/packages/cli/src/services/notificationService.ts
new file mode 100644
index 000000000..160b0dd54
--- /dev/null
+++ b/packages/cli/src/services/notificationService.ts
@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Notification routing service.
+ *
+ * When `terminalBell` setting is enabled, auto-detects the terminal and
+ * sends notifications through the best available channel:
+ *
+ *   iTerm.app → OSC 9 (native notification)
+ *   kitty     → OSC 99 (desktop notification protocol)
+ *   ghostty   → OSC 777 (notify)
+ *   others    → terminal bell fallback
+ *
+ * When disabled, no notification is sent.
+ */
+
+import { createDebugLogger } from '@qwen-code/qwen-code-core';
+import type { TerminalNotification } from '../ui/hooks/useTerminalNotification.js';
+import { detectTerminal, generateKittyId } from '../utils/osc.js';
+
+const debugLogger = createDebugLogger('NOTIFICATION_SERVICE');
+
+export interface NotificationOptions {
+  message: string;
+  title?: string;
+}
+
+const DEFAULT_TITLE = 'Qwen Code';
+
+/**
+ * Send a notification through the auto-detected channel.
+ *
+ * @param opts - Notification content
+ * @param terminal - Terminal notification primitives
+ * @param enabled - Whether notifications are enabled (from `terminalBell` setting)
+ * @returns The channel method that was actually used, or 'disabled'.
+ */
+export function sendNotification(
+  opts: NotificationOptions,
+  terminal: TerminalNotification,
+  enabled: boolean,
+): string {
+  if (!enabled) {
+    return 'disabled';
+  }
+
+  // Don't write raw escape sequences when stdout is not a TTY
+  // (CI, piped output, redirected to log files, etc.)
+  if (!process.stdout?.isTTY) {
+    return 'disabled';
+  }
+
+  const title = opts.title ?? DEFAULT_TITLE;
+
+  try {
+    const terminalType = detectTerminal();
+
+    switch (terminalType) {
+      case 'iTerm.app':
+        terminal.notifyITerm2({ ...opts, title });
+        return 'iterm2';
+      case 'kitty':
+        terminal.notifyKitty({ ...opts, title, id: generateKittyId() });
+        return 'kitty';
+      case 'ghostty':
+        terminal.notifyGhostty({ ...opts, title });
+        return 'ghostty';
+      case 'Apple_Terminal':
+      default:
+        terminal.notifyBell();
+        return 'terminal_bell';
+    }
+  } catch (error) {
+    debugLogger.warn('Failed to send notification:', error);
+    return 'error';
+  }
+}
diff --git a/packages/cli/src/ui/App.test.tsx b/packages/cli/src/ui/App.test.tsx
index 8df422f4b..7dcc98d90 100644
--- a/packages/cli/src/ui/App.test.tsx
+++ b/packages/cli/src/ui/App.test.tsx
@@ -57,6 +57,7 @@ describe('App', () => {
     streamingState: StreamingState.Idle,
     quittingMessages: null,
     dialogsVisible: false,
+    stickyTodos: null,
     mainControlsRef: { current: null },
     historyManager: {
       addItem: vi.fn(),
diff --git a/packages/cli/src/ui/AppContainer.test.tsx b/packages/cli/src/ui/AppContainer.test.tsx
index 2c4392cf9..9b15d302b 100644
--- a/packages/cli/src/ui/AppContainer.test.tsx
+++ b/packages/cli/src/ui/AppContainer.test.tsx
@@ -15,6 +15,7 @@ import {
 } from 'vitest';
 import { render, cleanup } from 'ink-testing-library';
 import { AppContainer, dedupeNewestFirst } from './AppContainer.js';
+import ansiEscapes from 'ansi-escapes';
 import {
   type Config,
   makeFakeConfig,
@@ -30,6 +31,7 @@ import {
 } from './contexts/UIActionsContext.js';
 import { ToolCallStatus } from './types.js';
 import { useContext } from 'react';
+import { Box, measureElement } from 'ink';
 
 // Mock useStdout to capture terminal title writes
 let mockStdout: { write: ReturnType<typeof vi.fn> };
@@ -49,7 +51,7 @@ let capturedUIActions: UIActions;
 function TestContextConsumer() {
   capturedUIState = useContext(UIStateContext)!;
   capturedUIActions = useContext(UIActionsContext)!;
-  return null;
+  return <Box ref={capturedUIState.mainControlsRef} />;
 }
 
 vi.mock('./App.js', () => ({
@@ -121,7 +123,6 @@ import { useSessionStats } from './contexts/SessionContext.js';
 import { useTextBuffer } from './components/shared/text-buffer.js';
 import { useLogger } from './hooks/useLogger.js';
 import { useLoadingIndicator } from './hooks/useLoadingIndicator.js';
-import { measureElement } from 'ink';
 import { useTerminalSize } from './hooks/useTerminalSize.js';
 import { ShellExecutionService } from '@qwen-code/qwen-code-core';
 
@@ -190,9 +191,17 @@ describe('AppContainer State Management', () => {
       onAuthError: vi.fn(),
       isAuthDialogOpen: false,
       isAuthenticating: false,
+      pendingAuthType: undefined,
+      externalAuthState: null,
+      qwenAuthState: {
+        deviceAuth: null,
+        authStatus: 'idle',
+        authMessage: null,
+      },
       handleAuthSelect: vi.fn(),
       handleCodingPlanSubmit: vi.fn(),
       handleAlibabaStandardSubmit: vi.fn(),
+      handleOpenRouterSubmit: vi.fn(),
       openAuthDialog: vi.fn(),
       cancelAuthentication: vi.fn(),
     });
@@ -428,6 +437,83 @@ describe('AppContainer State Management', () => {
       }).not.toThrow();
     });
 
+    it('refreshStatic clears the terminal before remounting history', () => {
+      render(
+        <AppContainer
+          config={mockConfig}
+          settings={mockSettings}
+          version="1.0.0"
+          initializationResult={mockInitResult}
+        />,
+      );
+
+      capturedUIActions.refreshStatic();
+
+      expect(mockStdout.write).toHaveBeenCalledWith(ansiEscapes.clearTerminal);
+    });
+
+    it('handleClearScreen avoids a second clearTerminal write', () => {
+      const clearSpy = vi.spyOn(console, 'clear').mockImplementation(() => {});
+
+      render(
+        <AppContainer
+          config={mockConfig}
+          settings={mockSettings}
+          version="1.0.0"
+          initializationResult={mockInitResult}
+        />,
+      );
+
+      capturedUIActions.handleClearScreen();
+
+      expect(clearSpy).toHaveBeenCalledTimes(1);
+      expect(mockStdout.write).not.toHaveBeenCalledWith(
+        ansiEscapes.clearTerminal,
+      );
+
+      clearSpy.mockRestore();
+    });
+
+    it('passes a remount-only refresh callback to slash commands', () => {
+      let slashRefreshStatic: (() => void) | undefined;
+      mockedUseSlashCommandProcessor.mockImplementation(
+        (
+          _config,
+          _settings,
+          _addItem,
+          _clearItems,
+          _loadHistory,
+          refreshStatic,
+        ) => {
+          slashRefreshStatic = refreshStatic;
+          return {
+            handleSlashCommand: vi.fn(),
+            slashCommands: [],
+            pendingHistoryItems: [],
+            commandContext: {},
+            shellConfirmationRequest: null,
+            confirmationRequest: null,
+          };
+        },
+      );
+
+      render(
+        <AppContainer
+          config={mockConfig}
+          settings={mockSettings}
+          version="1.0.0"
+          initializationResult={mockInitResult}
+        />,
+      );
+
+      slashRefreshStatic?.();
+
+      expect(slashRefreshStatic).toBeDefined();
+      expect(mockStdout.write).not.toHaveBeenCalledWith(
+        ansiEscapes.clearTerminal,
+      );
+    });
+
     it('provides ConfigContext with config object', () => {
       expect(() => {
         render(
@@ -1319,7 +1405,17 @@ describe('AppContainer State Management', () => {
         onAuthError: vi.fn(),
         isAuthDialogOpen: false,
         isAuthenticating: true,
+        pendingAuthType: undefined,
+        externalAuthState: null,
+        qwenAuthState: {
+          deviceAuth: null,
+          authStatus: 'idle',
+          authMessage: null,
+        },
         handleAuthSelect: vi.fn(),
+        handleCodingPlanSubmit: vi.fn(),
+        handleAlibabaStandardSubmit: vi.fn(),
+        handleOpenRouterSubmit: vi.fn(),
         openAuthDialog: vi.fn(),
         cancelAuthentication: vi.fn(),
       });
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index e8156b59e..e33beca8a 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -58,6 +58,7 @@ import {
   type WaitingToolCall,
 } from '@qwen-code/qwen-code-core';
 import { buildResumedHistoryItems } from './utils/resumeHistoryUtils.js';
+import { getStickyTodos } from './utils/todoSnapshot.js';
 import { validateAuthMethod } from '../config/auth.js';
 import { loadHierarchicalGeminiMemory } from '../config/config.js';
 import process from 'node:process';
@@ -69,11 +70,17 @@ import { useAuthCommand } from './auth/useAuth.js';
 import { useEditorSettings } from './hooks/useEditorSettings.js';
 import { useSettingsCommand } from './hooks/useSettingsCommand.js';
 import { useModelCommand } from './hooks/useModelCommand.js';
+import { useManageModelsCommand } from './hooks/useManageModelsCommand.js';
 import { useArenaCommand } from './hooks/useArenaCommand.js';
 import { useApprovalModeCommand } from './hooks/useApprovalModeCommand.js';
 import { useResumeCommand } from './hooks/useResumeCommand.js';
 import { useDeleteCommand } from './hooks/useDeleteCommand.js';
 import { useSlashCommandProcessor } from './hooks/slashCommandProcessor.js';
+import { useDoublePress } from './hooks/useDoublePress.js';
+import {
+  computeApiTruncationIndex,
+  isRealUserTurn,
+} from './utils/historyMapping.js';
 import { useVimMode } from './contexts/VimModeContext.js';
 import { CompactModeProvider } from './contexts/CompactModeContext.js';
 import { useTerminalSize } from './hooks/useTerminalSize.js';
@@ -120,6 +127,10 @@ import {
 import { useCodingPlanUpdates } from './hooks/useCodingPlanUpdates.js';
 import { ShellFocusContext } from './contexts/ShellFocusContext.js';
 import { useAgentViewState } from './contexts/AgentViewContext.js';
+import {
+  useBackgroundTaskViewState,
+  useBackgroundTaskViewActions,
+} from './contexts/BackgroundTaskViewContext.js';
 import { t } from '../i18n/index.js';
 import { useWelcomeBack } from './hooks/useWelcomeBack.js';
 import { useDialogClose } from './hooks/useDialogClose.js';
@@ -131,6 +142,7 @@ import { useMcpDialog } from './hooks/useMcpDialog.js';
 import { useHooksDialog } from './hooks/useHooksDialog.js';
 import { useMemoryDialog } from './hooks/useMemoryDialog.js';
 import { useAttentionNotifications } from './hooks/useAttentionNotifications.js';
+import { buildTerminalNotification } from './hooks/useTerminalNotification.js';
 import { useContextualTips } from './hooks/useContextualTips.js';
 import { getTipHistory } from '../services/tips/index.js';
 import { useRemoteInput } from '../remoteInput/RemoteInputContext.js';
@@ -308,6 +320,20 @@ export const AppContainer = (props: AppContainerProps) => {
   const { stdin, setRawMode } = useStdin();
   const { stdout } = useStdout();
 
+  // Raw write function for terminal escape sequences.
+  // Uses process.stdout directly instead of Ink's useStdout() because
+  // standard Ink v6.2.3 proxies stdout writes through its rendering
+  // pipeline, which can corrupt binary escape sequences (OSC, DCS).
+  const writeRaw = useCallback((data: string) => {
+    process.stdout.write(data);
+  }, []);
+
+  // Terminal notification helpers (constructed directly, not via context)
+  const terminal = useMemo(
+    () => buildTerminalNotification(writeRaw),
+    [writeRaw],
+  );
+
   // Additional hooks moved from App.tsx
   const { stats: sessionStats, startNewSession } = useSessionStats();
   const logger = useLogger(config.storage, sessionStats.sessionId);
@@ -478,10 +504,14 @@ export const AppContainer = (props: AppContainerProps) => {
     fetchUserMessages();
   }, [historyManager.history, logger]);
 
+  const remountStaticHistory = useCallback(() => {
+    setHistoryRemountKey((prev) => prev + 1);
+  }, []);
+
   const refreshStatic = useCallback(() => {
     stdout.write(ansiEscapes.clearTerminal);
-    setHistoryRemountKey((prev) => prev + 1);
-  }, [setHistoryRemountKey, stdout]);
+    remountStaticHistory();
+  }, [remountStaticHistory, stdout]);
 
   const {
     isThemeDialogOpen,
@@ -508,10 +538,13 @@ export const AppContainer = (props: AppContainerProps) => {
     isAuthDialogOpen,
     isAuthenticating,
     pendingAuthType,
+    externalAuthState,
     qwenAuthState,
     handleAuthSelect,
     handleCodingPlanSubmit,
     handleAlibabaStandardSubmit,
+    handleOpenRouterSubmit,
+    handleCustomApiKeySubmit,
     openAuthDialog,
     cancelAuthentication,
   } = useAuthCommand(settings, config, historyManager.addItem, refreshStatic);
@@ -581,6 +614,11 @@ export const AppContainer = (props: AppContainerProps) => {
     openModelDialog,
     closeModelDialog,
   } = useModelCommand();
+  const {
+    isManageModelsDialogOpen,
+    openManageModelsDialog,
+    closeManageModelsDialog,
+  } = useManageModelsCommand();
   const { activeArenaDialog, openArenaDialog, closeArenaDialog } =
     useArenaCommand();
 
@@ -632,6 +670,12 @@ export const AppContainer = (props: AppContainerProps) => {
   const { isHooksDialogOpen, openHooksDialog, closeHooksDialog } =
     useHooksDialog();
 
+  // Ref bridge: the guarded openRewindSelector callback is defined later
+  // (after useDoublePress), but slashCommandActions needs it now. The ref
+  // lets the useMemo capture a stable function pointer whose implementation
+  // is swapped in once the real callback exists.
+  const openRewindSelectorRef = useRef<() => void>(() => {});
+
   const slashCommandActions = useMemo(
     () => ({
       openAuthDialog,
@@ -640,6 +684,7 @@ export const AppContainer = (props: AppContainerProps) => {
       openMemoryDialog,
       openSettingsDialog,
       openModelDialog,
+      openManageModelsDialog,
       openTrustDialog,
       openArenaDialog,
       openPermissionsDialog,
@@ -660,6 +705,7 @@ export const AppContainer = (props: AppContainerProps) => {
       openMcpDialog,
       openHooksDialog,
       openResumeDialog,
+      openRewindSelector: () => openRewindSelectorRef.current(),
       handleResume,
       openDeleteDialog,
     }),
@@ -670,6 +716,7 @@ export const AppContainer = (props: AppContainerProps) => {
       openMemoryDialog,
       openSettingsDialog,
       openModelDialog,
+      openManageModelsDialog,
       openArenaDialog,
       setDebugMessage,
       dispatchExtensionStateUpdate,
@@ -704,7 +751,7 @@ export const AppContainer = (props: AppContainerProps) => {
     historyManager.addItem,
     historyManager.clearItems,
     historyManager.loadHistory,
-    refreshStatic,
+    remountStaticHistory,
     toggleVimEnabled,
     isProcessing,
     setIsProcessing,
@@ -857,6 +904,8 @@ export const AppContainer = (props: AppContainerProps) => {
   const [hasSuggestionsVisible, setHasSuggestionsVisible] = useState(false);
 
   const agentViewState = useAgentViewState();
+  const { dialogOpen: bgTasksDialogOpen } = useBackgroundTaskViewState();
+  const { closeDialog: closeBgTasksDialog } = useBackgroundTaskViewActions();
 
   // Prompt suggestion state
   const [promptSuggestion, setPromptSuggestion] = useState<string | null>(null);
@@ -1213,6 +1262,10 @@ export const AppContainer = (props: AppContainerProps) => {
     () => [...pendingSlashCommandHistoryItems, ...pendingGeminiHistoryItems],
     [pendingSlashCommandHistoryItems, pendingGeminiHistoryItems],
   );
+  const stickyTodos = useMemo(
+    () => getStickyTodos(historyManager.history, pendingHistoryItems),
+    [historyManager.history, pendingHistoryItems],
+  );
 
   // Terminal tab progress bar (OSC 9;4) for iTerm2/Ghostty
   useTerminalProgress(streamingState, isToolExecuting(pendingHistoryItems));
@@ -1246,8 +1299,8 @@ export const AppContainer = (props: AppContainerProps) => {
   const handleClearScreen = useCallback(() => {
     historyManager.clearItems();
     clearScreen();
-    refreshStatic();
-  }, [historyManager, refreshStatic]);
+    remountStaticHistory();
+  }, [historyManager, remountStaticHistory]);
 
   const { handleInput: vimHandleInput } = useVim(buffer, handleFinalSubmit);
 
@@ -1265,40 +1318,6 @@ export const AppContainer = (props: AppContainerProps) => {
     (streamingState === StreamingState.Idle ||
       streamingState === StreamingState.Responding);
 
-  const [controlsHeight, setControlsHeight] = useState(0);
-
-  useLayoutEffect(() => {
-    if (mainControlsRef.current) {
-      const fullFooterMeasurement = measureElement(mainControlsRef.current);
-      if (fullFooterMeasurement.height > 0) {
-        setControlsHeight(fullFooterMeasurement.height);
-      }
-    }
-  }, [buffer, terminalWidth, terminalHeight, btwItem]);
-
-  // agentViewState is declared earlier (before handleFinalSubmit) so it
-  // is available for input routing. Referenced here for layout computation.
-
-  // Compute available terminal height based on controls measurement.
-  // When in-process agents are present the AgentTabBar renders an extra
-  // row at the top of the layout; subtract it so downstream consumers
-  // (shell, transcript, etc.) don't overestimate available space.
-  const tabBarHeight = agentViewState.agents.size > 0 ? 1 : 0;
-  const availableTerminalHeight = Math.max(
-    0,
-    terminalHeight - controlsHeight - staticExtraHeight - 2 - tabBarHeight,
-  );
-
-  config.setShellExecutionConfig({
-    terminalWidth: Math.floor(terminalWidth * SHELL_WIDTH_FRACTION),
-    terminalHeight: Math.max(
-      Math.floor(availableTerminalHeight - SHELL_HEIGHT_PADDING),
-      1,
-    ),
-    pager: settings.merged.tools?.shell?.pager,
-    showColor: settings.merged.tools?.shell?.showColor,
-  });
-
   const isFocused = useFocus();
   useBracketedPaste();
 
@@ -1326,16 +1345,6 @@ export const AppContainer = (props: AppContainerProps) => {
   const initialPrompt = useMemo(() => config.getQuestion(), [config]);
   const initialPromptSubmitted = useRef(false);
 
-  useEffect(() => {
-    if (activePtyId) {
-      ShellExecutionService.resizePty(
-        activePtyId,
-        Math.floor(terminalWidth * SHELL_WIDTH_FRACTION),
-        Math.max(Math.floor(availableTerminalHeight - SHELL_HEIGHT_PADDING), 1),
-      );
-    }
-  }, [terminalWidth, availableTerminalHeight, activePtyId]);
-
   useEffect(() => {
     if (
       initialPrompt &&
@@ -1530,6 +1539,8 @@ export const AppContainer = (props: AppContainerProps) => {
   const [escapePressedOnce, setEscapePressedOnce] = useState(false);
   const escapeTimerRef = useRef<NodeJS.Timeout | null>(null);
   const dialogsVisibleRef = useRef(false);
+  const [isRewindSelectorOpen, setIsRewindSelectorOpen] = useState(false);
+  const [rewindEscPending, setRewindEscPending] = useState(false);
   const [constrainHeight, setConstrainHeight] = useState<boolean>(true);
   const [ideContextState, setIdeContextState] = useState<
     IdeContext | undefined
@@ -1543,8 +1554,108 @@ export const AppContainer = (props: AppContainerProps) => {
     needsRestart: ideNeedsRestart,
     restartReason: ideTrustRestartReason,
   } = useIdeTrustListener();
+  const {
+    isFeedbackDialogOpen,
+    openFeedbackDialog,
+    closeFeedbackDialog,
+    temporaryCloseFeedbackDialog,
+    submitFeedback,
+  } = useFeedbackDialog({
+    config,
+    settings,
+    streamingState,
+    history: historyManager.history,
+    sessionStats,
+  });
+  const dialogsVisible =
+    showWelcomeBackDialog ||
+    shouldShowIdePrompt ||
+    shouldShowCommandMigrationNudge ||
+    isFolderTrustDialogOpen ||
+    !!shellConfirmationRequest ||
+    !!confirmationRequest ||
+    confirmUpdateExtensionRequests.length > 0 ||
+    !!codingPlanUpdateRequest ||
+    settingInputRequests.length > 0 ||
+    pluginChoiceRequests.length > 0 ||
+    !!loopDetectionConfirmationRequest ||
+    isThemeDialogOpen ||
+    isSettingsDialogOpen ||
+    isMemoryDialogOpen ||
+    isModelDialogOpen ||
+    isManageModelsDialogOpen ||
+    isTrustDialogOpen ||
+    activeArenaDialog !== null ||
+    isPermissionsDialogOpen ||
+    isAuthDialogOpen ||
+    isAuthenticating ||
+    isEditorDialogOpen ||
+    showIdeRestartPrompt ||
+    isSubagentCreateDialogOpen ||
+    isAgentsManagerDialogOpen ||
+    isMcpDialogOpen ||
+    isHooksDialogOpen ||
+    isApprovalModeDialogOpen ||
+    isResumeDialogOpen ||
+    isDeleteDialogOpen ||
+    isExtensionsManagerDialogOpen ||
+    isRewindSelectorOpen ||
+    bgTasksDialogOpen;
+  dialogsVisibleRef.current = dialogsVisible;
+  const shouldShowStickyTodos =
+    stickyTodos !== null &&
+    !dialogsVisible &&
+    !isFeedbackDialogOpen &&
+    streamingState !== StreamingState.WaitingForConfirmation;
+  const [controlsHeight, setControlsHeight] = useState(0);
+
+  useLayoutEffect(() => {
+    if (!mainControlsRef.current) {
+      setControlsHeight(0);
+      return;
+    }
+
+    const fullFooterMeasurement = measureElement(mainControlsRef.current);
+    setControlsHeight(fullFooterMeasurement.height);
+  }, [
+    buffer,
+    terminalWidth,
+    terminalHeight,
+    btwItem,
+    dialogsVisible,
+    shouldShowStickyTodos,
+    stickyTodos,
+  ]);
+
+  // agentViewState is declared earlier (before handleFinalSubmit) so it
+  // is available for input routing. Referenced here for layout computation.
+  const tabBarHeight = agentViewState.agents.size > 0 ? 1 : 0;
+  const availableTerminalHeight = Math.max(
+    0,
+    terminalHeight - controlsHeight - staticExtraHeight - 2 - tabBarHeight,
+  );
+
+  config.setShellExecutionConfig({
+    terminalWidth: Math.floor(terminalWidth * SHELL_WIDTH_FRACTION),
+    terminalHeight: Math.max(
+      Math.floor(availableTerminalHeight - SHELL_HEIGHT_PADDING),
+      1,
+    ),
+    pager: settings.merged.tools?.shell?.pager,
+    showColor: settings.merged.tools?.shell?.showColor,
+  });
   const isInitialMount = useRef(true);
 
+  useEffect(() => {
+    if (activePtyId) {
+      ShellExecutionService.resizePty(
+        activePtyId,
+        Math.floor(terminalWidth * SHELL_WIDTH_FRACTION),
+        Math.max(Math.floor(availableTerminalHeight - SHELL_HEIGHT_PADDING), 1),
+      );
+    }
+  }, [terminalWidth, availableTerminalHeight, activePtyId]);
+
   useEffect(() => {
     if (ideNeedsRestart) {
       // IDE trust changed, force a restart.
@@ -1577,6 +1688,98 @@ export const AppContainer = (props: AppContainerProps) => {
     setShowEscapePrompt(showPrompt);
   }, []);
 
+  // --- Rewind selector callbacks ---
+  const openRewindSelector = useCallback(() => {
+    if (streamingState !== StreamingState.Idle) return;
+    if (config.getIdeMode()) return;
+    if (dialogsVisibleRef.current) return;
+    const hasUserTurns = historyManager.history.some((h) => h.type === 'user');
+    if (!hasUserTurns) return;
+    setIsRewindSelectorOpen(true);
+  }, [streamingState, config, historyManager.history]);
+  openRewindSelectorRef.current = openRewindSelector;
+
+  const closeRewindSelector = useCallback(() => {
+    setIsRewindSelectorOpen(false);
+  }, []);
+
+  const handleRewindConfirm = useCallback(
+    (userItem: HistoryItem) => {
+      const geminiClient = config.getGeminiClient();
+      if (!geminiClient) return;
+
+      // 1. Compute values from current history BEFORE truncation
+      const originalHistory = historyManager.history;
+      const originalLength = originalHistory.length;
+
+      let targetTurnIndex = 0;
+      for (const h of originalHistory) {
+        if (h.id === userItem.id) break;
+        if (isRealUserTurn(h)) targetTurnIndex++;
+      }
+
+      // 2. Compute API truncation point
+      const apiHistory = geminiClient.getHistory();
+      const apiTruncateIndex = computeApiTruncationIndex(
+        originalHistory,
+        userItem.id,
+        apiHistory,
+      );
+
+      // Abort if the target turn is unreachable (e.g., absorbed by compression)
+      if (apiTruncateIndex < 0) {
+        historyManager.addItem(
+          {
+            type: 'error',
+            text: 'Cannot rewind to a turn that was compressed. Try a more recent turn.',
+          },
+          Date.now(),
+        );
+        setIsRewindSelectorOpen(false);
+        return;
+      }
+
+      // 3. Truncate API history and strip stale thinking blocks
+      geminiClient.truncateHistory(apiTruncateIndex);
+      geminiClient.stripThoughtsFromHistory();
+
+      // 4. Truncate UI history (keep everything before the target item)
+      const truncatedUi = originalHistory.filter((h) => h.id < userItem.id);
+      historyManager.loadHistory(truncatedUi);
+
+      // 5. Re-render the terminal
+      refreshStatic();
+
+      // 6. Pre-populate input with the original user text
+      if (userItem.type === 'user' && userItem.text) {
+        buffer.setText(userItem.text);
+      }
+
+      // 7. Add info message
+      historyManager.addItem(
+        {
+          type: 'info',
+          text: 'Conversation rewound. Edit your prompt and press Enter to continue.',
+        },
+        Date.now(),
+      );
+
+      // 8. Record the rewind event — re-roots the parentUuid chain so
+      //    rewound messages end up on a dead branch during resume.
+      config.getChatRecordingService()?.rewindRecording(targetTurnIndex, {
+        truncatedCount: originalLength - truncatedUi.length,
+      });
+
+      // 9. Close the selector
+      setIsRewindSelectorOpen(false);
+    },
+    [config, historyManager, refreshStatic, buffer],
+  );
+
+  const handleDoubleEscRewind = useDoublePress(openRewindSelector, (pending) =>
+    setRewindEscPending(pending),
+  );
+
   const handleIdePromptComplete = useCallback(
     (result: IdeIntegrationNudgeResult) => {
       if (result.userSelection === 'yes') {
@@ -1698,6 +1901,8 @@ export const AppContainer = (props: AppContainerProps) => {
     elapsedTime,
     settings,
     config,
+    terminal,
+    pendingToolCalls,
   });
 
   // Dialog close functionality
@@ -1720,6 +1925,8 @@ export const AppContainer = (props: AppContainerProps) => {
     isFolderTrustDialogOpen,
     showWelcomeBackDialog,
     handleWelcomeBackClose,
+    isBackgroundTasksDialogOpen: bgTasksDialogOpen,
+    closeBackgroundTasksDialog: closeBgTasksDialog,
   });
 
   const handleExit = useCallback(
@@ -1870,6 +2077,20 @@ export const AppContainer = (props: AppContainerProps) => {
           return;
         }
 
+        // Input is empty and idle — double-ESC opens rewind selector
+        if (
+          streamingState === StreamingState.Idle &&
+          !dialogsVisibleRef.current
+        ) {
+          if (escapeTimerRef.current) {
+            clearTimeout(escapeTimerRef.current);
+            escapeTimerRef.current = null;
+          }
+          setEscapePressedOnce(false);
+          handleDoubleEscRewind();
+          return;
+        }
+
         // No action available, reset the flag
         if (escapeTimerRef.current) {
           clearTimeout(escapeTimerRef.current);
@@ -1966,6 +2187,7 @@ export const AppContainer = (props: AppContainerProps) => {
       compactMode,
       setCompactMode,
       refreshStatic,
+      handleDoubleEscRewind,
     ],
   );
 
@@ -2007,41 +2229,6 @@ export const AppContainer = (props: AppContainerProps) => {
     stdout,
   ]);
 
-  const nightly = props.version.includes('nightly');
-
-  const dialogsVisible =
-    showWelcomeBackDialog ||
-    shouldShowIdePrompt ||
-    shouldShowCommandMigrationNudge ||
-    isFolderTrustDialogOpen ||
-    !!shellConfirmationRequest ||
-    !!confirmationRequest ||
-    confirmUpdateExtensionRequests.length > 0 ||
-    !!codingPlanUpdateRequest ||
-    settingInputRequests.length > 0 ||
-    pluginChoiceRequests.length > 0 ||
-    !!loopDetectionConfirmationRequest ||
-    isThemeDialogOpen ||
-    isSettingsDialogOpen ||
-    isMemoryDialogOpen ||
-    isModelDialogOpen ||
-    isTrustDialogOpen ||
-    activeArenaDialog !== null ||
-    isPermissionsDialogOpen ||
-    isAuthDialogOpen ||
-    isAuthenticating ||
-    isEditorDialogOpen ||
-    showIdeRestartPrompt ||
-    isSubagentCreateDialogOpen ||
-    isAgentsManagerDialogOpen ||
-    isMcpDialogOpen ||
-    isHooksDialogOpen ||
-    isApprovalModeDialogOpen ||
-    isResumeDialogOpen ||
-    isDeleteDialogOpen ||
-    isExtensionsManagerDialogOpen;
-  dialogsVisibleRef.current = dialogsVisible;
-
   // Drain queued messages when idle. `queueDrainNonce` re-fires the effect
   // after each submission settles so multi-step queues drain end-to-end.
   const queueDrainingRef = useRef(false);
@@ -2075,19 +2262,7 @@ export const AppContainer = (props: AppContainerProps) => {
     queueDrainNonce,
   ]);
 
-  const {
-    isFeedbackDialogOpen,
-    openFeedbackDialog,
-    closeFeedbackDialog,
-    temporaryCloseFeedbackDialog,
-    submitFeedback,
-  } = useFeedbackDialog({
-    config,
-    settings,
-    streamingState,
-    history: historyManager.history,
-    sessionStats,
-  });
+  const nightly = props.version.includes('nightly');
 
   const uiState: UIState = useMemo(
     () => ({
@@ -2100,6 +2275,7 @@ export const AppContainer = (props: AppContainerProps) => {
       authError,
       isAuthDialogOpen,
       pendingAuthType,
+      externalAuthState,
       // Qwen OAuth state
       qwenAuthState,
       editorError,
@@ -2110,6 +2286,7 @@ export const AppContainer = (props: AppContainerProps) => {
       isMemoryDialogOpen,
       isModelDialogOpen,
       isFastModelMode,
+      isManageModelsDialogOpen,
       isTrustDialogOpen,
       activeArenaDialog,
       isPermissionsDialogOpen,
@@ -2163,6 +2340,7 @@ export const AppContainer = (props: AppContainerProps) => {
       staticExtraHeight,
       dialogsVisible,
       pendingHistoryItems,
+      stickyTodos,
       btwItem,
       setBtwItem,
       cancelBtw,
@@ -2206,6 +2384,9 @@ export const AppContainer = (props: AppContainerProps) => {
       // Prompt suggestion
       promptSuggestion,
       dismissPromptSuggestion,
+      // Rewind selector
+      isRewindSelectorOpen,
+      rewindEscPending,
     }),
     [
       isThemeDialogOpen,
@@ -2215,6 +2396,7 @@ export const AppContainer = (props: AppContainerProps) => {
       authError,
       isAuthDialogOpen,
       pendingAuthType,
+      externalAuthState,
       // Qwen OAuth state
       qwenAuthState,
       editorError,
@@ -2225,6 +2407,7 @@ export const AppContainer = (props: AppContainerProps) => {
       isMemoryDialogOpen,
       isModelDialogOpen,
       isFastModelMode,
+      isManageModelsDialogOpen,
       isTrustDialogOpen,
       activeArenaDialog,
       isPermissionsDialogOpen,
@@ -2277,6 +2460,7 @@ export const AppContainer = (props: AppContainerProps) => {
       staticExtraHeight,
       dialogsVisible,
       pendingHistoryItems,
+      stickyTodos,
       btwItem,
       setBtwItem,
       cancelBtw,
@@ -2322,6 +2506,9 @@ export const AppContainer = (props: AppContainerProps) => {
       // Prompt suggestion
       promptSuggestion,
       dismissPromptSuggestion,
+      // Rewind selector
+      isRewindSelectorOpen,
+      rewindEscPending,
     ],
   );
 
@@ -2339,12 +2526,16 @@ export const AppContainer = (props: AppContainerProps) => {
       cancelAuthentication,
       handleCodingPlanSubmit,
       handleAlibabaStandardSubmit,
+      handleOpenRouterSubmit,
+      handleCustomApiKeySubmit,
       handleEditorSelect,
       exitEditorDialog,
       closeSettingsDialog,
       closeMemoryDialog,
       closeModelDialog,
       openModelDialog,
+      openManageModelsDialog,
+      closeManageModelsDialog,
       openArenaDialog,
       closeArenaDialog,
       handleArenaModelsSelected,
@@ -2391,6 +2582,10 @@ export const AppContainer = (props: AppContainerProps) => {
       closeFeedbackDialog,
       temporaryCloseFeedbackDialog,
       submitFeedback,
+      // Rewind selector
+      openRewindSelector,
+      closeRewindSelector,
+      handleRewindConfirm,
     }),
     [
       openThemeDialog,
@@ -2405,12 +2600,16 @@ export const AppContainer = (props: AppContainerProps) => {
       cancelAuthentication,
       handleCodingPlanSubmit,
       handleAlibabaStandardSubmit,
+      handleOpenRouterSubmit,
+      handleCustomApiKeySubmit,
       handleEditorSelect,
       exitEditorDialog,
       closeSettingsDialog,
       closeMemoryDialog,
       closeModelDialog,
       openModelDialog,
+      openManageModelsDialog,
+      closeManageModelsDialog,
       openArenaDialog,
       closeArenaDialog,
       handleArenaModelsSelected,
@@ -2455,6 +2654,10 @@ export const AppContainer = (props: AppContainerProps) => {
       closeFeedbackDialog,
       temporaryCloseFeedbackDialog,
       submitFeedback,
+      // Rewind selector
+      openRewindSelector,
+      closeRewindSelector,
+      handleRewindConfirm,
     ],
   );
 
diff --git a/packages/cli/src/ui/auth/AuthDialog.test.tsx b/packages/cli/src/ui/auth/AuthDialog.test.tsx
index b540ae56e..ad62f46ff 100644
--- a/packages/cli/src/ui/auth/AuthDialog.test.tsx
+++ b/packages/cli/src/ui/auth/AuthDialog.test.tsx
@@ -34,6 +34,7 @@ const createMockUIActions = (overrides: Partial<UIActions> = {}): UIActions => {
     handleAuthSelect: vi.fn(),
     handleCodingPlanSubmit: vi.fn(),
     handleAlibabaStandardSubmit: vi.fn(),
+    handleOpenRouterSubmit: vi.fn(),
     onAuthError: vi.fn(),
     handleRetryLastPrompt: vi.fn(),
   } as Partial<UIActions>;
@@ -69,6 +70,118 @@ const renderAuthDialog = (
   );
 };
 
+/**
+ * Type text into the terminal one character at a time.
+ * Works around a Node 24.x + ink compatibility issue on Windows
+ * where bulk stdin.write() may not propagate to TextInput correctly.
+ */
+const typeText = async (
+  stdin: { write: (s: string) => void },
+  text: string,
+) => {
+  const delay = (ms = 5) => new Promise((resolve) => setTimeout(resolve, ms));
+  for (const char of text) {
+    stdin.write(char);
+    await delay(5);
+  }
+  await delay(30);
+};
+
+const escapeRegExp = (text: string) =>
+  text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const expectSelectedOption = (frame: string | undefined, label: string) => {
+  expect(frame).toMatch(
+    new RegExp(`›\\s*(?:\\d+\\.\\s*)?${escapeRegExp(label)}`),
+  );
+};
+
+const waitForSelectedOption = async (
+  lastFrame: () => string | undefined,
+  label: string,
+) => {
+  await vi.waitFor(() => {
+    expectSelectedOption(lastFrame(), label);
+  });
+};
+
+const pressEnterAndWaitFor = async (
+  stdin: { write: (s: string) => void },
+  lastFrame: () => string | undefined,
+  expectedText: string,
+) => {
+  stdin.write('\r');
+  await vi.waitFor(() => {
+    expect(lastFrame()).toContain(expectedText);
+  });
+};
+
+const moveDownAndWaitForSelection = async (
+  stdin: { write: (s: string) => void },
+  lastFrame: () => string | undefined,
+  label: string,
+) => {
+  stdin.write('\u001b[B');
+  await waitForSelectedOption(lastFrame, label);
+};
+
+const navigateToCustomProtocolSelect = async (
+  stdin: { write: (s: string) => void },
+  lastFrame: () => string | undefined,
+) => {
+  await waitForSelectedOption(lastFrame, 'OAuth');
+  await moveDownAndWaitForSelection(
+    stdin,
+    lastFrame,
+    'Alibaba Cloud Coding Plan',
+  );
+  await moveDownAndWaitForSelection(stdin, lastFrame, 'API Key');
+  await pressEnterAndWaitFor(stdin, lastFrame, 'Select API Key Type');
+  await waitForSelectedOption(
+    lastFrame,
+    'Alibaba Cloud ModelStudio Standard API Key',
+  );
+  await moveDownAndWaitForSelection(stdin, lastFrame, 'Custom API Key');
+  await pressEnterAndWaitFor(stdin, lastFrame, 'Step 1/6 · Protocol');
+};
+
+const navigateToCustomBaseUrlInput = async (
+  stdin: { write: (s: string) => void },
+  lastFrame: () => string | undefined,
+) => {
+  await navigateToCustomProtocolSelect(stdin, lastFrame);
+  await pressEnterAndWaitFor(stdin, lastFrame, 'Step 2/6 · Base URL');
+};
+
+const navigateToCustomApiKeyInput = async (
+  stdin: { write: (s: string) => void },
+  lastFrame: () => string | undefined,
+) => {
+  await navigateToCustomBaseUrlInput(stdin, lastFrame);
+  await pressEnterAndWaitFor(stdin, lastFrame, 'Step 3/6 · API Key');
+};
+
+const navigateToCustomModelIdInput = async (
+  stdin: { write: (s: string) => void },
+  lastFrame: () => string | undefined,
+  apiKey = 'sk-test',
+) => {
+  await navigateToCustomApiKeyInput(stdin, lastFrame);
+  await typeText(stdin, apiKey);
+  await pressEnterAndWaitFor(stdin, lastFrame, 'Step 4/6 · Model IDs');
+};
+
+const navigateToCustomAdvancedConfig = async (
+  stdin: { write: (s: string) => void },
+  lastFrame: () => string | undefined,
+  apiKey = 'sk-test',
+  modelIds = 'model-1,model-2',
+) => {
+  await navigateToCustomModelIdInput(stdin, lastFrame, apiKey);
+  await typeText(stdin, modelIds);
+  await pressEnterAndWaitFor(stdin, lastFrame, 'Step 5/6 · Advanced Config');
+};
+
 describe('AuthDialog', () => {
   const wait = (ms = 50) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -308,8 +421,8 @@ describe('AuthDialog', () => {
 
       const { lastFrame } = renderAuthDialog(settings);
 
-      // QWEN_OAUTH is the first option, so it should be selected
-      expect(lastFrame()).toContain('Qwen OAuth');
+      // QWEN_OAUTH maps to 'OAUTH' in the new three-option main menu
+      expect(lastFrame()).toContain('OAuth');
     });
 
     it('should fall back to default if QWEN_DEFAULT_AUTH_TYPE is not set', () => {
@@ -391,8 +504,8 @@ describe('AuthDialog', () => {
       const { lastFrame } = renderAuthDialog(settings);
 
       // Since the auth dialog doesn't show QWEN_DEFAULT_AUTH_TYPE errors anymore,
-      // it will just show the default Qwen OAuth option
-      expect(lastFrame()).toContain('Qwen OAuth');
+      // it will just show the default OAuth option
+      expect(lastFrame()).toContain('OAuth');
     });
   });
 
@@ -558,4 +671,524 @@ describe('AuthDialog', () => {
     expect(handleAuthSelect).toHaveBeenCalledWith(undefined);
     unmount();
   });
+
+  it('should show OpenRouter in API key options', async () => {
+    const settings: LoadedSettings = new LoadedSettings(
+      {
+        settings: { ui: { customThemes: {} }, mcpServers: {} },
+        originalSettings: { ui: { customThemes: {} }, mcpServers: {} },
+        path: '',
+      },
+      {
+        settings: {},
+        originalSettings: {},
+        path: '',
+      },
+      {
+        settings: {
+          security: { auth: { selectedType: undefined } },
+          ui: { customThemes: {} },
+          mcpServers: {},
+        },
+        originalSettings: {
+          security: { auth: { selectedType: undefined } },
+          ui: { customThemes: {} },
+          mcpServers: {},
+        },
+        path: '',
+      },
+      {
+        settings: { ui: { customThemes: {} }, mcpServers: {} },
+        originalSettings: { ui: { customThemes: {} }, mcpServers: {} },
+        path: '',
+      },
+      true,
+      new Set(),
+    );
+
+    const { stdin, lastFrame, unmount } = renderAuthDialog(settings);
+    await wait();
+
+    // OAuth is selected by default, press Enter to enter OAuth provider list
+    stdin.write('\r');
+    await wait();
+
+    await vi.waitFor(() => {
+      const frame = lastFrame();
+      expect(frame).toContain('OpenRouter');
+      expect(frame).toContain('Browser OAuth');
+    });
+
+    unmount();
+  });
+
+  it('should trigger OpenRouter OAuth from API key options', async () => {
+    const handleOpenRouterSubmit = vi.fn().mockResolvedValue(undefined);
+    const settings: LoadedSettings = new LoadedSettings(
+      {
+        settings: { ui: { customThemes: {} }, mcpServers: {} },
+        originalSettings: { ui: { customThemes: {} }, mcpServers: {} },
+        path: '',
+      },
+      {
+        settings: {},
+        originalSettings: {},
+        path: '',
+      },
+      {
+        settings: {
+          security: { auth: { selectedType: undefined } },
+          ui: { customThemes: {} },
+          mcpServers: {},
+        },
+        originalSettings: {
+          security: { auth: { selectedType: undefined } },
+          ui: { customThemes: {} },
+          mcpServers: {},
+        },
+        path: '',
+      },
+      {
+        settings: { ui: { customThemes: {} }, mcpServers: {} },
+        originalSettings: { ui: { customThemes: {} }, mcpServers: {} },
+        path: '',
+      },
+      true,
+      new Set(),
+    );
+
+    const { stdin, unmount } = renderAuthDialog(
+      settings,
+      {},
+      { handleOpenRouterSubmit },
+    );
+    await wait();
+
+    // OAuth is selected by default, press Enter to enter OAuth provider list
+    stdin.write('\r');
+    await wait();
+    // OpenRouter is the first option, press Enter to trigger OAuth
+    stdin.write('\r');
+    await wait();
+
+    await vi.waitFor(() => {
+      expect(handleOpenRouterSubmit).toHaveBeenCalledTimes(1);
+    });
+
+    unmount();
+  });
+});
+
+const isUnreliableTuiInputEnvironment =
+  process.platform === 'win32' ||
+  (process.env['CI'] === 'true' && process.version.startsWith('v20.'));
+const itWhenTuiInputReliable = isUnreliableTuiInputEnvironment ? it.skip : it;
+
+describe('AuthDialog Custom API Key Wizard', () => {
+  const wait = (ms = 50) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  const createStandardSettings = (): LoadedSettings =>
+    new LoadedSettings(
+      {
+        settings: { ui: { customThemes: {} }, mcpServers: {} },
+        originalSettings: { ui: { customThemes: {} }, mcpServers: {} },
+        path: '',
+      },
+      {
+        settings: {},
+        originalSettings: {},
+        path: '',
+      },
+      {
+        settings: {
+          security: { auth: { selectedType: undefined } },
+          ui: { customThemes: {} },
+          mcpServers: {},
+        },
+        originalSettings: {
+          security: { auth: { selectedType: undefined } },
+          ui: { customThemes: {} },
+          mcpServers: {},
+        },
+        path: '',
+      },
+      {
+        settings: { ui: { customThemes: {} }, mcpServers: {} },
+        originalSettings: { ui: { customThemes: {} }, mcpServers: {} },
+        path: '',
+      },
+      true,
+      new Set(),
+    );
+
+  itWhenTuiInputReliable(
+    'navigates to protocol selection when Custom API Key is selected',
+    async () => {
+      const settings = createStandardSettings();
+      const handleCustomApiKeySubmit = vi.fn();
+
+      const mockUIState = {
+        authError: null,
+        pendingAuthType: undefined,
+      } as UIState;
+
+      const mockUIActions = {
+        handleAuthSelect: vi.fn(),
+        handleCodingPlanSubmit: vi.fn(),
+        handleAlibabaStandardSubmit: vi.fn(),
+        handleOpenRouterSubmit: vi.fn(),
+        handleCustomApiKeySubmit,
+        onAuthError: vi.fn(),
+        handleRetryLastPrompt: vi.fn(),
+      } as unknown as UIActions;
+
+      const mockConfig = {
+        getAuthType: vi.fn(() => undefined),
+        getContentGeneratorConfig: vi.fn(() => ({})),
+      } as unknown as Config;
+
+      const { stdin, lastFrame, unmount } = renderWithProviders(
+        <UIStateContext.Provider value={mockUIState}>
+          <UIActionsContext.Provider value={mockUIActions}>
+            <AuthDialog />
+          </UIActionsContext.Provider>
+        </UIStateContext.Provider>,
+        { settings, config: mockConfig },
+      );
+
+      await navigateToCustomProtocolSelect(stdin, lastFrame);
+
+      await vi.waitFor(() => {
+        const frame = lastFrame();
+        expect(frame).toContain('Step 1/6 · Protocol');
+        expect(frame).toContain('OpenAI-compatible');
+        expect(frame).toContain('Anthropic-compatible');
+        expect(frame).toContain('Gemini-compatible');
+      });
+
+      unmount();
+    },
+  );
+
+  itWhenTuiInputReliable(
+    'navigates to base URL input after selecting a protocol',
+    async () => {
+      const settings = createStandardSettings();
+      const handleCustomApiKeySubmit = vi.fn();
+
+      const mockUIState = {
+        authError: null,
+        pendingAuthType: undefined,
+      } as UIState;
+
+      const mockUIActions = {
+        handleAuthSelect: vi.fn(),
+        handleCodingPlanSubmit: vi.fn(),
+        handleAlibabaStandardSubmit: vi.fn(),
+        handleOpenRouterSubmit: vi.fn(),
+        handleCustomApiKeySubmit,
+        onAuthError: vi.fn(),
+        handleRetryLastPrompt: vi.fn(),
+      } as unknown as UIActions;
+
+      const mockConfig = {
+        getAuthType: vi.fn(() => undefined),
+        getContentGeneratorConfig: vi.fn(() => ({})),
+      } as unknown as Config;
+
+      const { stdin, lastFrame, unmount } = renderWithProviders(
+        <UIStateContext.Provider value={mockUIState}>
+          <UIActionsContext.Provider value={mockUIActions}>
+            <AuthDialog />
+          </UIActionsContext.Provider>
+        </UIStateContext.Provider>,
+        { settings, config: mockConfig },
+      );
+
+      await navigateToCustomBaseUrlInput(stdin, lastFrame);
+
+      await vi.waitFor(() => {
+        const frame = lastFrame();
+        expect(frame).toContain('Step 2/6 · Base URL');
+        expect(frame).toContain('Enter the API endpoint');
+      });
+
+      unmount();
+    },
+  );
+
+  itWhenTuiInputReliable(
+    'shows review screen with JSON after entering model IDs',
+    async () => {
+      const settings = createStandardSettings();
+      const handleCustomApiKeySubmit = vi.fn();
+
+      const mockUIState = {
+        authError: null,
+        pendingAuthType: undefined,
+      } as UIState;
+
+      const mockUIActions = {
+        handleAuthSelect: vi.fn(),
+        handleCodingPlanSubmit: vi.fn(),
+        handleAlibabaStandardSubmit: vi.fn(),
+        handleOpenRouterSubmit: vi.fn(),
+        handleCustomApiKeySubmit,
+        onAuthError: vi.fn(),
+        handleRetryLastPrompt: vi.fn(),
+      } as unknown as UIActions;
+
+      const mockConfig = {
+        getAuthType: vi.fn(() => undefined),
+        getContentGeneratorConfig: vi.fn(() => ({})),
+      } as unknown as Config;
+
+      const { stdin, lastFrame, unmount } = renderWithProviders(
+        <UIStateContext.Provider value={mockUIState}>
+          <UIActionsContext.Provider value={mockUIActions}>
+            <AuthDialog />
+          </UIActionsContext.Provider>
+        </UIStateContext.Provider>,
+        { settings, config: mockConfig },
+      );
+
+      await navigateToCustomAdvancedConfig(
+        stdin,
+        lastFrame,
+        'sk-test-key-12345',
+        'qwen/qwen3-coder,gpt-4.1',
+      );
+      await pressEnterAndWaitFor(stdin, lastFrame, 'Step 6/6 · Review');
+
+      await vi.waitFor(() => {
+        const frame = lastFrame();
+        expect(frame).toContain('Step 6/6 · Review');
+        expect(frame).toContain('The following JSON will be saved');
+        expect(frame).toContain('QWEN_CUSTOM_API_KEY_OPENAI');
+        expect(frame).toContain('qwen/qwen3-coder');
+        expect(frame).toContain('gpt-4.1');
+        expect(frame).toContain('Enter to save');
+      });
+
+      unmount();
+    },
+  );
+
+  itWhenTuiInputReliable(
+    'calls handleCustomApiKeySubmit on Enter in review view',
+    async () => {
+      const settings = createStandardSettings();
+      const handleCustomApiKeySubmit = vi.fn().mockResolvedValue(undefined);
+
+      const mockUIState = {
+        authError: null,
+        pendingAuthType: undefined,
+      } as UIState;
+
+      const mockUIActions = {
+        handleAuthSelect: vi.fn(),
+        handleCodingPlanSubmit: vi.fn(),
+        handleAlibabaStandardSubmit: vi.fn(),
+        handleOpenRouterSubmit: vi.fn(),
+        handleCustomApiKeySubmit,
+        onAuthError: vi.fn(),
+        handleRetryLastPrompt: vi.fn(),
+      } as unknown as UIActions;
+
+      const mockConfig = {
+        getAuthType: vi.fn(() => undefined),
+        getContentGeneratorConfig: vi.fn(() => ({})),
+      } as unknown as Config;
+
+      const { stdin, lastFrame, unmount } = renderWithProviders(
+        <UIStateContext.Provider value={mockUIState}>
+          <UIActionsContext.Provider value={mockUIActions}>
+            <AuthDialog />
+          </UIActionsContext.Provider>
+        </UIStateContext.Provider>,
+        { settings, config: mockConfig },
+      );
+
+      await navigateToCustomAdvancedConfig(
+        stdin,
+        lastFrame,
+        'sk-test',
+        'model-1,model-2',
+      );
+      await pressEnterAndWaitFor(stdin, lastFrame, 'Step 6/6 · Review');
+
+      await vi.waitFor(() => {
+        const frame = lastFrame();
+        expect(frame).toContain('Enter to save');
+      });
+
+      stdin.write('\r'); // Enter to save
+      await wait();
+
+      await vi.waitFor(() => {
+        expect(handleCustomApiKeySubmit).toHaveBeenCalledWith(
+          AuthType.USE_OPENAI,
+          'https://api.openai.com/v1',
+          'sk-test',
+          'model-1,model-2',
+          undefined,
+        );
+      });
+
+      unmount();
+    },
+  );
+
+  itWhenTuiInputReliable(
+    'shows advanced config screen after entering model IDs',
+    async () => {
+      const settings = createStandardSettings();
+      const handleCustomApiKeySubmit = vi.fn();
+
+      const mockUIState = {
+        authError: null,
+        pendingAuthType: undefined,
+      } as UIState;
+
+      const mockUIActions = {
+        handleAuthSelect: vi.fn(),
+        handleCodingPlanSubmit: vi.fn(),
+        handleAlibabaStandardSubmit: vi.fn(),
+        handleOpenRouterSubmit: vi.fn(),
+        handleCustomApiKeySubmit,
+        onAuthError: vi.fn(),
+        handleRetryLastPrompt: vi.fn(),
+      } as unknown as UIActions;
+
+      const mockConfig = {
+        getAuthType: vi.fn(() => undefined),
+        getContentGeneratorConfig: vi.fn(() => ({})),
+      } as unknown as Config;
+
+      const { stdin, lastFrame, unmount } = renderWithProviders(
+        <UIStateContext.Provider value={mockUIState}>
+          <UIActionsContext.Provider value={mockUIActions}>
+            <AuthDialog />
+          </UIActionsContext.Provider>
+        </UIStateContext.Provider>,
+        { settings, config: mockConfig },
+      );
+
+      await navigateToCustomAdvancedConfig(
+        stdin,
+        lastFrame,
+        'sk-test',
+        'model-1,model-2',
+      );
+
+      await vi.waitFor(() => {
+        const frame = lastFrame();
+        expect(frame).toContain('Step 5/6 · Advanced Config');
+        expect(frame).toContain(
+          'Optional: configure advanced generation settings',
+        );
+        expect(frame).toContain('Enable thinking');
+        expect(frame).toContain('Enable modality');
+        expect(frame).toContain('Enter to continue');
+      });
+
+      unmount();
+    },
+  );
+
+  itWhenTuiInputReliable(
+    'passes generationConfig when advanced options are toggled',
+    async () => {
+      const settings = createStandardSettings();
+      const handleCustomApiKeySubmit = vi.fn().mockResolvedValue(undefined);
+
+      const mockUIState = {
+        authError: null,
+        pendingAuthType: undefined,
+      } as UIState;
+
+      const mockUIActions = {
+        handleAuthSelect: vi.fn(),
+        handleCodingPlanSubmit: vi.fn(),
+        handleAlibabaStandardSubmit: vi.fn(),
+        handleOpenRouterSubmit: vi.fn(),
+        handleCustomApiKeySubmit,
+        onAuthError: vi.fn(),
+        handleRetryLastPrompt: vi.fn(),
+      } as unknown as UIActions;
+
+      const mockConfig = {
+        getAuthType: vi.fn(() => undefined),
+        getContentGeneratorConfig: vi.fn(() => ({})),
+      } as unknown as Config;
+
+      const { stdin, lastFrame, unmount } = renderWithProviders(
+        <UIStateContext.Provider value={mockUIState}>
+          <UIActionsContext.Provider value={mockUIActions}>
+            <AuthDialog />
+          </UIActionsContext.Provider>
+        </UIStateContext.Provider>,
+        { settings, config: mockConfig },
+      );
+
+      await navigateToCustomAdvancedConfig(
+        stdin,
+        lastFrame,
+        'sk-test',
+        'model-1',
+      );
+
+      await vi.waitFor(() => {
+        const frame = lastFrame();
+        expect(frame).toContain('Step 5/6 · Advanced Config');
+      });
+
+      // Toggle thinking (press Space — thinking is initially focused)
+      stdin.write(' ');
+      await wait();
+
+      // Navigate down to modality, toggle (press ↓ then Space)
+      stdin.write('\u001b[B');
+      await wait();
+      stdin.write(' ');
+      await wait();
+
+      // Press Enter to continue to review
+      stdin.write('\r');
+      await wait();
+
+      // Verify review includes generationConfig
+      await vi.waitFor(() => {
+        const frame = lastFrame();
+        expect(frame).toContain('"generationConfig"');
+        expect(frame).toContain('"enable_thinking"');
+        expect(frame).toContain('"image": true');
+        expect(frame).toContain('"video": true');
+        expect(frame).toContain('"audio": true');
+      });
+
+      // Press Enter to save
+      stdin.write('\r');
+      await wait();
+
+      await vi.waitFor(() => {
+        expect(handleCustomApiKeySubmit).toHaveBeenCalledWith(
+          AuthType.USE_OPENAI,
+          'https://api.openai.com/v1',
+          'sk-test',
+          'model-1',
+          {
+            enableThinking: true,
+            multimodal: {
+              image: true,
+              video: true,
+              audio: true,
+            },
+          },
+        );
+      });
+
+      unmount();
+    },
+  );
 });
diff --git a/packages/cli/src/ui/auth/AuthDialog.tsx b/packages/cli/src/ui/auth/AuthDialog.tsx
index f7fb402b2..4d32b003f 100644
--- a/packages/cli/src/ui/auth/AuthDialog.tsx
+++ b/packages/cli/src/ui/auth/AuthDialog.tsx
@@ -26,6 +26,11 @@ import {
   ALIBABA_STANDARD_API_KEY_ENDPOINTS,
   type AlibabaStandardRegion,
 } from '../../constants/alibabaStandardApiKey.js';
+import {
+  generateCustomApiKeyEnvKey,
+  normalizeCustomModelIds,
+  maskApiKey,
+} from './useAuth.js';
 
 const MODEL_PROVIDERS_DOCUMENTATION_URL =
   'https://qwenlm.github.io/qwen-code-docs/en/users/configuration/model-providers/';
@@ -43,8 +48,15 @@ function parseDefaultAuthType(
 }
 
 // Main menu option type
-type MainOption = typeof AuthType.QWEN_OAUTH | 'CODING_PLAN' | 'API_KEY';
-type ApiKeyOption = 'ALIBABA_STANDARD_API_KEY' | 'CUSTOM_API_KEY';
+type MainOption = 'OAUTH' | 'CODING_PLAN' | 'API_KEY';
+type ApiKeyOption =
+  | 'OPENROUTER_OAUTH'
+  | 'ALIBABA_STANDARD_API_KEY'
+  | 'CUSTOM_API_KEY';
+type OAuthOption =
+  | 'OPENROUTER_OAUTH'
+  | 'MODELSCOPE_OAUTH'
+  | 'QWEN_OAUTH_DISCONTINUED';
 
 // View level for navigation
 type ViewLevel =
@@ -55,7 +67,13 @@ type ViewLevel =
   | 'alibaba-standard-region-select'
   | 'alibaba-standard-api-key-input'
   | 'alibaba-standard-model-id-input'
-  | 'custom-info';
+  | 'custom-protocol-select'
+  | 'custom-base-url-input'
+  | 'custom-api-key-input'
+  | 'custom-model-id-input'
+  | 'custom-advanced-config'
+  | 'custom-review-json'
+  | 'oauth-provider-select';
 
 const ALIBABA_STANDARD_MODEL_IDS_PLACEHOLDER = 'qwen3.5-plus,glm-5,kimi-k2.5';
 const ALIBABA_STANDARD_API_DOCUMENTATION_URLS: Record<
@@ -77,6 +95,8 @@ export function AuthDialog(): React.JSX.Element {
     handleAuthSelect: onAuthSelect,
     handleCodingPlanSubmit,
     handleAlibabaStandardSubmit,
+    handleOpenRouterSubmit,
+    handleCustomApiKeySubmit,
     onAuthError,
   } = useUIActions();
   const config = useConfig();
@@ -90,6 +110,7 @@ export function AuthDialog(): React.JSX.Element {
   const [alibabaStandardRegionIndex, setAlibabaStandardRegionIndex] =
     useState<number>(0);
   const [apiKeyTypeIndex, setApiKeyTypeIndex] = useState<number>(0);
+  const [oauthProviderIndex, setOAuthProviderIndex] = useState<number>(0);
   const [alibabaStandardRegion, setAlibabaStandardRegion] =
     useState<AlibabaStandardRegion>('cn-beijing');
   const [alibabaStandardApiKey, setAlibabaStandardApiKey] = useState('');
@@ -100,6 +121,30 @@ export function AuthDialog(): React.JSX.Element {
   const [alibabaStandardModelIdError, setAlibabaStandardModelIdError] =
     useState<string | null>(null);
 
+  // Custom API Key wizard state
+  const [customProtocolIndex, setCustomProtocolIndex] = useState<number>(0);
+  const [customProtocol, setCustomProtocol] = useState<AuthType>(
+    AuthType.USE_OPENAI,
+  );
+  const [customBaseUrl, setCustomBaseUrl] = useState('');
+  const [customBaseUrlError, setCustomBaseUrlError] = useState<string | null>(
+    null,
+  );
+  const [customApiKey, setCustomApiKey] = useState('');
+  const [customApiKeyError, setCustomApiKeyError] = useState<string | null>(
+    null,
+  );
+  const [customModelIds, setCustomModelIds] = useState('');
+  const [customModelIdsError, setCustomModelIdsError] = useState<string | null>(
+    null,
+  );
+
+  // Advanced generation config state
+  const [advancedThinkingEnabled, setAdvancedThinkingEnabled] = useState(false);
+  const [advancedModalityEnabled, setAdvancedModalityEnabled] = useState(false);
+  const [focusedConfigIndex, setFocusedConfigIndex] = useState(0);
+  // 0 = thinking, 1 = modality
+
   // Main authentication entries (flat three-option layout)
   const mainItems = [
     {
@@ -119,11 +164,13 @@ export function AuthDialog(): React.JSX.Element {
       value: 'API_KEY' as MainOption,
     },
     {
-      key: AuthType.QWEN_OAUTH,
-      title: t('Qwen OAuth'),
-      label: t('Qwen OAuth'),
-      description: t('Discontinued — switch to Coding Plan or API Key'),
-      value: AuthType.QWEN_OAUTH as MainOption,
+      key: 'OAUTH',
+      title: t('OAuth'),
+      label: t('OAuth'),
+      description: t(
+        'Browser-based authentication with third-party providers (e.g. OpenRouter, ModelScope)',
+      ),
+      value: 'OAUTH' as MainOption,
     },
   ];
 
@@ -210,6 +257,38 @@ export function AuthDialog(): React.JSX.Element {
     },
   ];
 
+  const protocolItems = [
+    {
+      key: AuthType.USE_OPENAI,
+      title: t('OpenAI-compatible'),
+      label: t('OpenAI-compatible'),
+      description: t(
+        'OpenAI Chat Completions API (OpenRouter, vLLM, Ollama, LM Studio, Fireworks, etc.)',
+      ),
+      value: AuthType.USE_OPENAI as AuthType,
+    },
+    {
+      key: AuthType.USE_ANTHROPIC,
+      title: t('Anthropic-compatible'),
+      label: t('Anthropic-compatible'),
+      description: t('Anthropic Messages API'),
+      value: AuthType.USE_ANTHROPIC as AuthType,
+    },
+    {
+      key: AuthType.USE_GEMINI,
+      title: t('Gemini-compatible'),
+      label: t('Gemini-compatible'),
+      description: t('Google Gemini API'),
+      value: AuthType.USE_GEMINI as AuthType,
+    },
+  ];
+
+  const DEFAULT_CUSTOM_BASE_URLS: Partial<Record<AuthType, string>> = {
+    [AuthType.USE_OPENAI]: 'https://api.openai.com/v1',
+    [AuthType.USE_ANTHROPIC]: 'https://api.anthropic.com/v1',
+    [AuthType.USE_GEMINI]: 'https://generativelanguage.googleapis.com',
+  };
+
   const apiKeyTypeItems = [
     {
       key: 'ALIBABA_STANDARD_API_KEY',
@@ -229,8 +308,36 @@ export function AuthDialog(): React.JSX.Element {
     },
   ];
 
+  const oauthProviderItems = [
+    {
+      key: 'OPENROUTER_OAUTH',
+      title: t('OpenRouter'),
+      label: t('OpenRouter'),
+      description: t(
+        'Browser OAuth · Auto-configure API key and OpenRouter models',
+      ),
+      value: 'OPENROUTER_OAUTH' as OAuthOption,
+    },
+    {
+      key: 'MODELSCOPE_OAUTH',
+      title: t('ModelScope'),
+      label: t('ModelScope'),
+      description: t(
+        'Browser OAuth · Auto-configure API key and ModelScope models',
+      ),
+      value: 'MODELSCOPE_OAUTH' as OAuthOption,
+    },
+    {
+      key: 'QWEN_OAUTH_DISCONTINUED',
+      title: t('Qwen'),
+      label: t('Qwen'),
+      description: t('Discontinued — switch to Coding Plan or API Key'),
+      value: 'QWEN_OAUTH_DISCONTINUED' as OAuthOption,
+    },
+  ];
+
   // Map an AuthType to the corresponding main menu option.
-  // QWEN_OAUTH maps directly; USE_OPENAI maps to:
+  // QWEN_OAUTH maps to 'OAUTH'; USE_OPENAI maps to:
   // - CODING_PLAN when current config matches coding plan
   // - API_KEY for other OpenAI / Anthropic / Gemini-compatible configs
   const contentGenConfig = config.getContentGeneratorConfig();
@@ -240,7 +347,7 @@ export function AuthDialog(): React.JSX.Element {
       contentGenConfig?.apiKeyEnvKey,
     ) !== false;
   const authTypeToMainOption = (authType: AuthType): MainOption => {
-    if (authType === AuthType.QWEN_OAUTH) return AuthType.QWEN_OAUTH;
+    if (authType === AuthType.QWEN_OAUTH) return 'OAUTH';
     if (authType === AuthType.USE_OPENAI && isCurrentlyCodingPlan) {
       return 'CODING_PLAN';
     }
@@ -269,8 +376,8 @@ export function AuthDialog(): React.JSX.Element {
         return item.value === authTypeToMainOption(defaultAuthType);
       }
 
-      // Priority 4: default to QWEN_OAUTH
-      return item.value === AuthType.QWEN_OAUTH;
+      // Priority 4: default to OAUTH
+      return item.value === 'OAUTH';
     }),
   );
 
@@ -289,13 +396,8 @@ export function AuthDialog(): React.JSX.Element {
       return;
     }
 
-    // Qwen OAuth free tier discontinued — show warning instead of proceeding
-    if (value === AuthType.QWEN_OAUTH) {
-      setErrorMessage(
-        t(
-          'Qwen OAuth free tier was discontinued on 2026-04-15. Please select Coding Plan or API Key instead.',
-        ),
-      );
+    if (value === 'OAUTH') {
+      setViewLevel('oauth-provider-select');
       return;
     }
 
@@ -313,7 +415,53 @@ export function AuthDialog(): React.JSX.Element {
       return;
     }
 
-    setViewLevel('custom-info');
+    // Reset custom wizard state and go to protocol selection
+    setCustomProtocolIndex(0);
+    setCustomProtocol(AuthType.USE_OPENAI);
+    setCustomBaseUrl('');
+    setCustomBaseUrlError(null);
+    setCustomApiKey('');
+    setCustomApiKeyError(null);
+    setCustomModelIds('');
+    setCustomModelIdsError(null);
+    setAdvancedThinkingEnabled(false);
+    setAdvancedModalityEnabled(false);
+    setFocusedConfigIndex(0);
+    setViewLevel('custom-protocol-select');
+  };
+
+  const handleOAuthProviderSelect = async (value: OAuthOption) => {
+    setErrorMessage(null);
+    onAuthError(null);
+
+    if (value === 'OPENROUTER_OAUTH') {
+      await handleOpenRouterSubmit();
+      return;
+    }
+
+    // Qwen OAuth free tier discontinued — show warning instead of proceeding
+    if (value === 'QWEN_OAUTH_DISCONTINUED') {
+      setErrorMessage(
+        t(
+          'Qwen OAuth free tier was discontinued on 2026-04-15. Please select Coding Plan or API Key instead.',
+        ),
+      );
+      return;
+    }
+
+    // Future: Add support for ModelScope OAuth when implemented
+    if (value === 'MODELSCOPE_OAUTH') {
+      // Currently not implemented, show message
+      setErrorMessage(
+        t(
+          'ModelScope OAuth is not yet implemented. Please select another option.',
+        ),
+      );
+      return;
+    }
+
+    // For other OAuth providers, you can extend the functionality here
+    await onAuthSelect(AuthType.USE_OPENAI);
   };
 
   const handleRegionSelect = async (selectedRegion: CodingPlanRegion) => {
@@ -381,6 +529,89 @@ export function AuthDialog(): React.JSX.Element {
     );
   };
 
+  const handleCustomProtocolSelect = (protocol: AuthType) => {
+    setErrorMessage(null);
+    onAuthError(null);
+    setCustomProtocol(protocol);
+    const defaultUrl = DEFAULT_CUSTOM_BASE_URLS[protocol] ?? '';
+    setCustomBaseUrl(defaultUrl);
+    setCustomBaseUrlError(null);
+    setViewLevel('custom-base-url-input');
+  };
+
+  const handleCustomBaseUrlSubmit = () => {
+    const trimmedUrl = customBaseUrl.trim();
+    if (!trimmedUrl) {
+      setCustomBaseUrlError(t('Base URL cannot be empty.'));
+      return;
+    }
+    if (!/^https?:\/\//i.test(trimmedUrl)) {
+      setCustomBaseUrlError(t('Base URL must start with http:// or https://.'));
+      return;
+    }
+    setCustomBaseUrlError(null);
+    setCustomApiKey('');
+    setCustomApiKeyError(null);
+    setViewLevel('custom-api-key-input');
+  };
+
+  const handleCustomApiKeySubmitLocal = () => {
+    const trimmedKey = customApiKey.trim();
+    if (!trimmedKey) {
+      setCustomApiKeyError(t('API key cannot be empty.'));
+      return;
+    }
+    setCustomApiKeyError(null);
+    setCustomModelIds('');
+    setCustomModelIdsError(null);
+    setViewLevel('custom-model-id-input');
+  };
+
+  const handleCustomModelIdSubmit = () => {
+    const normalized = normalizeCustomModelIds(customModelIds);
+    if (normalized.length === 0) {
+      setCustomModelIdsError(t('Model IDs cannot be empty.'));
+      return;
+    }
+    setCustomModelIdsError(null);
+    setViewLevel('custom-advanced-config');
+  };
+
+  const handleAdvancedConfigSubmit = () => {
+    setViewLevel('custom-review-json');
+  };
+
+  const handleCustomReviewSubmit = () => {
+    const trimmedBaseUrl = customBaseUrl.trim();
+    const trimmedApiKey = customApiKey.trim();
+    const trimmedModelIds = customModelIds;
+
+    // Build generationConfig only if any advanced option is set
+    const hasThinking = advancedThinkingEnabled;
+    const hasModality = advancedModalityEnabled;
+
+    const generationConfig =
+      hasThinking || hasModality
+        ? {
+            enableThinking: hasThinking ? true : undefined,
+            multimodal: hasModality
+              ? { image: true, video: true, audio: true }
+              : undefined,
+          }
+        : undefined;
+
+    void handleCustomApiKeySubmit(
+      customProtocol as
+        | AuthType.USE_OPENAI
+        | AuthType.USE_ANTHROPIC
+        | AuthType.USE_GEMINI,
+      trimmedBaseUrl,
+      trimmedApiKey,
+      trimmedModelIds,
+      generationConfig,
+    );
+  };
+
   const handleGoBack = () => {
     setErrorMessage(null);
     onAuthError(null);
@@ -391,14 +622,26 @@ export function AuthDialog(): React.JSX.Element {
       setViewLevel('region-select');
     } else if (viewLevel === 'api-key-type-select') {
       setViewLevel('main');
-    } else if (viewLevel === 'custom-info') {
+    } else if (viewLevel === 'custom-protocol-select') {
       setViewLevel('api-key-type-select');
+    } else if (viewLevel === 'custom-base-url-input') {
+      setViewLevel('custom-protocol-select');
+    } else if (viewLevel === 'custom-api-key-input') {
+      setViewLevel('custom-base-url-input');
+    } else if (viewLevel === 'custom-model-id-input') {
+      setViewLevel('custom-api-key-input');
+    } else if (viewLevel === 'custom-advanced-config') {
+      setViewLevel('custom-model-id-input');
+    } else if (viewLevel === 'custom-review-json') {
+      setViewLevel('custom-advanced-config');
     } else if (viewLevel === 'alibaba-standard-region-select') {
       setViewLevel('api-key-type-select');
     } else if (viewLevel === 'alibaba-standard-api-key-input') {
       setViewLevel('alibaba-standard-region-select');
     } else if (viewLevel === 'alibaba-standard-model-id-input') {
       setViewLevel('alibaba-standard-api-key-input');
+    } else if (viewLevel === 'oauth-provider-select') {
+      setViewLevel('main');
     }
   };
 
@@ -411,7 +654,18 @@ export function AuthDialog(): React.JSX.Element {
           return;
         }
 
-        if (viewLevel === 'api-key-input' || viewLevel === 'custom-info') {
+        if (viewLevel === 'api-key-input') {
+          handleGoBack();
+          return;
+        }
+        if (
+          viewLevel === 'custom-protocol-select' ||
+          viewLevel === 'custom-base-url-input' ||
+          viewLevel === 'custom-api-key-input' ||
+          viewLevel === 'custom-model-id-input' ||
+          viewLevel === 'custom-advanced-config' ||
+          viewLevel === 'custom-review-json'
+        ) {
           handleGoBack();
           return;
         }
@@ -419,7 +673,8 @@ export function AuthDialog(): React.JSX.Element {
           viewLevel === 'api-key-type-select' ||
           viewLevel === 'alibaba-standard-region-select' ||
           viewLevel === 'alibaba-standard-api-key-input' ||
-          viewLevel === 'alibaba-standard-model-id-input'
+          viewLevel === 'alibaba-standard-model-id-input' ||
+          viewLevel === 'oauth-provider-select'
         ) {
           handleGoBack();
           return;
@@ -443,6 +698,50 @@ export function AuthDialog(): React.JSX.Element {
     { isActive: true },
   );
 
+  // Handle Enter key for review view to save
+  useKeypress(
+    (key) => {
+      if (key.name === 'return' && viewLevel === 'custom-review-json') {
+        handleCustomReviewSubmit();
+      }
+    },
+    { isActive: true },
+  );
+
+  // Advanced config keypress: ↑↓ to navigate, Space to toggle, Enter to submit
+  useKeypress(
+    (key) => {
+      if (viewLevel !== 'custom-advanced-config') return;
+
+      const { name } = key;
+
+      if (name === 'up') {
+        setFocusedConfigIndex((v) => (v <= 0 ? 1 : v - 1));
+        return;
+      }
+
+      if (name === 'down') {
+        setFocusedConfigIndex((v) => (v >= 1 ? 0 : v + 1));
+        return;
+      }
+
+      if (name === 'space') {
+        if (focusedConfigIndex === 0) {
+          setAdvancedThinkingEnabled((v) => !v);
+        } else {
+          setAdvancedModalityEnabled((v) => !v);
+        }
+        return;
+      }
+
+      if (name === 'return') {
+        handleAdvancedConfigSubmit();
+        return;
+      }
+    },
+    { isActive: true },
+  );
+
   // Render main auth selection
   const renderMainView = () => (
     <>
@@ -625,26 +924,294 @@ export function AuthDialog(): React.JSX.Element {
     </Box>
   );
 
-  // Render custom mode info
-  const renderCustomInfoView = () => (
+  // Render custom protocol selection
+  const renderCustomProtocolSelectView = () => (
     <>
+      <Box marginTop={1}>
+        <DescriptiveRadioButtonSelect
+          items={protocolItems}
+          initialIndex={customProtocolIndex}
+          onSelect={handleCustomProtocolSelect}
+          onHighlight={(value) => {
+            const index = protocolItems.findIndex(
+              (item) => item.value === value,
+            );
+            setCustomProtocolIndex(index);
+          }}
+          itemGap={1}
+        />
+      </Box>
+      <Box marginTop={1}>
+        <Text color={theme.text.secondary}>
+          {t('Enter to select, ↑↓ to navigate, Esc to go back')}
+        </Text>
+      </Box>
+    </>
+  );
+
+  // Render custom base URL input
+  const renderCustomBaseUrlInputView = () => (
+    <Box marginTop={1} flexDirection="column">
       <Box marginTop={1}>
         <Text color={theme.text.primary}>
-          {t('You can configure your API key and models in settings.json')}
+          {t('Enter the API endpoint for this protocol.')}
         </Text>
       </Box>
       <Box marginTop={1}>
-        <Text>{t('Refer to the documentation for setup instructions')}</Text>
+        <TextInput
+          value={customBaseUrl}
+          onChange={(value) => {
+            setCustomBaseUrl(value);
+            if (customBaseUrlError) {
+              setCustomBaseUrlError(null);
+            }
+          }}
+          onSubmit={handleCustomBaseUrlSubmit}
+          placeholder="https://api.openai.com/v1"
+        />
       </Box>
-      <Box marginTop={0}>
+      {customBaseUrlError && (
+        <Box marginTop={1}>
+          <Text color={theme.status.error}>{customBaseUrlError}</Text>
+        </Box>
+      )}
+      <Box marginTop={1}>
         <Link url={MODEL_PROVIDERS_DOCUMENTATION_URL} fallback={false}>
           <Text color={theme.text.link}>
-            {MODEL_PROVIDERS_DOCUMENTATION_URL}
+            {t(
+              'Need advanced generationConfig or capabilities? See documentation',
+            )}
           </Text>
         </Link>
       </Box>
       <Box marginTop={1}>
-        <Text color={theme.text.secondary}>{t('Esc to go back')}</Text>
+        <Text color={theme.text.secondary}>
+          {t('Enter to submit, Esc to go back')}
+        </Text>
+      </Box>
+    </Box>
+  );
+
+  // Render custom API key input
+  const renderCustomApiKeyInputView = () => (
+    <Box marginTop={1} flexDirection="column">
+      <Box marginTop={1}>
+        <Text color={theme.text.primary}>
+          {t('Enter the API key for this endpoint.')}
+        </Text>
+      </Box>
+      <Box marginTop={1}>
+        <TextInput
+          value={customApiKey}
+          onChange={(value) => {
+            setCustomApiKey(value);
+            if (customApiKeyError) {
+              setCustomApiKeyError(null);
+            }
+          }}
+          onSubmit={handleCustomApiKeySubmitLocal}
+          placeholder="sk-..."
+        />
+      </Box>
+      {customApiKeyError && (
+        <Box marginTop={1}>
+          <Text color={theme.status.error}>{customApiKeyError}</Text>
+        </Box>
+      )}
+      <Box marginTop={1}>
+        <Text color={theme.text.secondary}>
+          {t('Enter to submit, Esc to go back')}
+        </Text>
+      </Box>
+    </Box>
+  );
+
+  // Render custom model ID input
+  const renderCustomModelIdInputView = () => (
+    <Box marginTop={1} flexDirection="column">
+      <Box marginTop={1}>
+        <Text color={theme.text.primary}>
+          {t('Enter one or more model IDs, separated by commas.')}
+        </Text>
+      </Box>
+      <Box marginTop={1}>
+        <TextInput
+          value={customModelIds}
+          onChange={(value) => {
+            setCustomModelIds(value);
+            if (customModelIdsError) {
+              setCustomModelIdsError(null);
+            }
+          }}
+          onSubmit={handleCustomModelIdSubmit}
+          placeholder="qwen/qwen3-coder,openai/gpt-4.1"
+        />
+      </Box>
+      {customModelIdsError && (
+        <Box marginTop={1}>
+          <Text color={theme.status.error}>{customModelIdsError}</Text>
+        </Box>
+      )}
+      <Box marginTop={1}>
+        <Text color={theme.text.secondary}>
+          {t('Enter to submit, Esc to go back')}
+        </Text>
+      </Box>
+    </Box>
+  );
+
+  // Render custom advanced config
+  const renderCustomAdvancedConfigView = () => {
+    const checkmark = (v: boolean) => (v ? '◉' : '○');
+    const cursor = (index: number) =>
+      focusedConfigIndex === index ? '›' : ' ';
+
+    return (
+      <Box marginTop={1} flexDirection="column">
+        <Box marginTop={1}>
+          <Text color={theme.text.primary}>
+            {t('Optional: configure advanced generation settings.')}
+          </Text>
+        </Box>
+        <Box marginTop={1} marginLeft={2}>
+          <Text
+            color={focusedConfigIndex === 0 ? theme.status.success : undefined}
+          >
+            {cursor(0)} {checkmark(advancedThinkingEnabled)}{' '}
+            {t('Enable thinking')}
+          </Text>
+        </Box>
+        <Box marginTop={0} marginLeft={4}>
+          <Text color={theme.text.secondary}>
+            {t(
+              'Allows the model to perform extended reasoning before responding.',
+            )}
+          </Text>
+        </Box>
+        <Box marginTop={1} marginLeft={2}>
+          <Text
+            color={focusedConfigIndex === 1 ? theme.status.success : undefined}
+          >
+            {cursor(1)} {checkmark(advancedModalityEnabled)}{' '}
+            {t('Enable modality')}
+          </Text>
+        </Box>
+        <Box marginTop={0} marginLeft={4}>
+          <Text color={theme.text.secondary}>
+            {t('Enables image, video, and audio input/output capabilities.')}
+          </Text>
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.text.secondary}>
+            {t(
+              '\u2191\u2193 to navigate, Space to toggle, Enter to continue, Esc to go back',
+            )}
+          </Text>
+        </Box>
+      </Box>
+    );
+  };
+
+  // Render custom review JSON
+  const renderCustomReviewJsonView = () => {
+    const generatedEnvKey = generateCustomApiKeyEnvKey(
+      customProtocol,
+      customBaseUrl.trim(),
+    );
+    const normalizedIds = normalizeCustomModelIds(customModelIds);
+    const maskedKey = maskApiKey(customApiKey);
+
+    // Build generationConfig preview lines
+    const hasThinking = advancedThinkingEnabled;
+    const hasModality = advancedModalityEnabled;
+    const hasGenConfig = hasThinking || hasModality;
+
+    let genConfig: Record<string, unknown> | undefined;
+    if (hasGenConfig) {
+      genConfig = {};
+      if (hasModality) {
+        genConfig['modalities'] = {
+          image: true,
+          video: true,
+          audio: true,
+        };
+      }
+      if (hasThinking) {
+        genConfig['extra_body'] = {
+          enable_thinking: true,
+        };
+      }
+    }
+
+    const modelEntries = normalizedIds.map((id) => {
+      const entry: Record<string, unknown> = {
+        id,
+        name: id,
+        baseUrl: customBaseUrl.trim(),
+        envKey: generatedEnvKey,
+      };
+      if (genConfig) {
+        entry['generationConfig'] = genConfig;
+      }
+      return entry;
+    });
+
+    const preview = {
+      env: { [generatedEnvKey]: maskedKey },
+      modelProviders: {
+        [customProtocol]: modelEntries,
+      },
+      security: {
+        auth: {
+          selectedType: customProtocol,
+        },
+      },
+      model: {
+        name: normalizedIds[0],
+      },
+    };
+
+    const jsonPreview = JSON.stringify(preview, null, 2);
+
+    return (
+      <Box marginTop={1} flexDirection="column">
+        <Box marginTop={1}>
+          <Text color={theme.text.primary}>
+            {t('The following JSON will be saved to settings.json:')}
+          </Text>
+        </Box>
+        <Box marginTop={1}>
+          <Text>{jsonPreview}</Text>
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.text.secondary}>
+            {t('Enter to save, Esc to go back')}
+          </Text>
+        </Box>
+      </Box>
+    );
+  };
+
+  const renderOAuthProviderSelectView = () => (
+    <>
+      <Box marginTop={1}>
+        <DescriptiveRadioButtonSelect
+          items={oauthProviderItems}
+          initialIndex={oauthProviderIndex}
+          onSelect={handleOAuthProviderSelect}
+          onHighlight={(value) => {
+            const index = oauthProviderItems.findIndex(
+              (item) => item.value === value,
+            );
+            setOAuthProviderIndex(index);
+          }}
+          itemGap={1}
+        />
+      </Box>
+      <Box marginTop={1}>
+        <Text color={theme?.text?.secondary}>
+          {t('Enter to select, ↑↓ to navigate, Esc to go back')}
+        </Text>
       </Box>
     </>
   );
@@ -659,8 +1226,18 @@ export function AuthDialog(): React.JSX.Element {
         return t('Enter Coding Plan API Key');
       case 'api-key-type-select':
         return t('Select API Key Type');
-      case 'custom-info':
-        return t('Custom Configuration');
+      case 'custom-protocol-select':
+        return t('Step 1/6 \u00B7 Protocol');
+      case 'custom-base-url-input':
+        return t('Step 2/6 \u00B7 Base URL');
+      case 'custom-api-key-input':
+        return t('Step 3/6 \u00B7 API Key');
+      case 'custom-model-id-input':
+        return t('Step 4/6 \u00B7 Model IDs');
+      case 'custom-advanced-config':
+        return t('Step 5/6 \u00B7 Advanced Config');
+      case 'custom-review-json':
+        return t('Step 6/6 \u00B7 Review');
       case 'alibaba-standard-region-select':
         return t(
           'Select Region for Alibaba Cloud ModelStudio Standard API Key',
@@ -669,6 +1246,8 @@ export function AuthDialog(): React.JSX.Element {
         return t('Enter Alibaba Cloud ModelStudio Standard API Key');
       case 'alibaba-standard-model-id-input':
         return t('Enter Model IDs');
+      case 'oauth-provider-select':
+        return t('Select OAuth Provider');
       default:
         return t('Select Authentication Method');
     }
@@ -694,7 +1273,15 @@ export function AuthDialog(): React.JSX.Element {
         renderAlibabaStandardApiKeyInputView()}
       {viewLevel === 'alibaba-standard-model-id-input' &&
         renderAlibabaStandardModelIdInputView()}
-      {viewLevel === 'custom-info' && renderCustomInfoView()}
+      {viewLevel === 'custom-protocol-select' &&
+        renderCustomProtocolSelectView()}
+      {viewLevel === 'custom-base-url-input' && renderCustomBaseUrlInputView()}
+      {viewLevel === 'custom-api-key-input' && renderCustomApiKeyInputView()}
+      {viewLevel === 'custom-model-id-input' && renderCustomModelIdInputView()}
+      {viewLevel === 'custom-advanced-config' &&
+        renderCustomAdvancedConfigView()}
+      {viewLevel === 'custom-review-json' && renderCustomReviewJsonView()}
+      {viewLevel === 'oauth-provider-select' && renderOAuthProviderSelectView()}
 
       {(authError || errorMessage) && (
         <Box marginTop={1}>
diff --git a/packages/cli/src/ui/auth/useAuth.test.ts b/packages/cli/src/ui/auth/useAuth.test.ts
new file mode 100644
index 000000000..53ca65b86
--- /dev/null
+++ b/packages/cli/src/ui/auth/useAuth.test.ts
@@ -0,0 +1,351 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { AuthType } from '@qwen-code/qwen-code-core';
+import {
+  useAuthCommand,
+  generateCustomApiKeyEnvKey,
+  normalizeCustomModelIds,
+  maskApiKey,
+} from './useAuth.js';
+import {
+  OPENROUTER_OAUTH_CALLBACK_URL,
+  applyOpenRouterModelsConfiguration,
+  createOpenRouterOAuthSession,
+  runOpenRouterOAuthLogin,
+} from '../../commands/auth/openrouterOAuth.js';
+
+vi.mock('../hooks/useQwenAuth.js', () => ({
+  useQwenAuth: vi.fn(() => ({
+    qwenAuthState: {},
+    cancelQwenAuth: vi.fn(),
+  })),
+}));
+
+vi.mock('../../utils/settingsUtils.js', () => ({
+  backupSettingsFile: vi.fn(),
+}));
+
+vi.mock('../../config/modelProvidersScope.js', () => ({
+  getPersistScopeForModelSelection: vi.fn(() => 'user'),
+}));
+
+vi.mock('../../commands/auth/openrouterOAuth.js', () => ({
+  OPENROUTER_OAUTH_CALLBACK_URL: 'http://localhost:3000/openrouter/callback',
+  createOpenRouterOAuthSession: vi.fn(() => ({
+    callbackUrl: 'http://localhost:3000/openrouter/callback',
+    codeVerifier: 'test-verifier',
+    state: 'test-state',
+    authorizationUrl:
+      'https://openrouter.ai/auth?callback_url=http%3A%2F%2Flocalhost%3A3000%2Fopenrouter%2Fcallback&code_challenge=test-challenge&state=test-state',
+  })),
+  applyOpenRouterModelsConfiguration: vi.fn(async () => ({
+    updatedConfigs: [
+      {
+        id: 'openai/gpt-4o-mini:free',
+        name: 'OpenRouter · GPT-4o mini',
+        baseUrl: 'https://openrouter.ai/api/v1',
+        envKey: 'OPENROUTER_API_KEY',
+      },
+    ],
+    activeModelId: 'openai/gpt-4o-mini:free',
+    persistScope: 'user',
+  })),
+  runOpenRouterOAuthLogin: vi.fn(
+    () => new Promise(() => undefined) as Promise<{ apiKey: string }>,
+  ),
+}));
+
+const createSettings = () => ({
+  merged: {
+    modelProviders: {},
+  },
+  setValue: vi.fn(),
+  forScope: vi.fn(() => ({
+    path: '/tmp/settings.json',
+  })),
+});
+
+const createConfig = () => ({
+  getAuthType: vi.fn(() => AuthType.USE_OPENAI),
+  getUsageStatisticsEnabled: vi.fn(() => false),
+  reloadModelProvidersConfig: vi.fn(),
+  refreshAuth: vi.fn(async () => undefined),
+});
+
+describe('useAuthCommand', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('closes auth dialog immediately when starting OpenRouter OAuth', async () => {
+    const settings = createSettings();
+    const config = createConfig();
+    const addItem = vi.fn();
+
+    const { result } = renderHook(() =>
+      useAuthCommand(settings as never, config as never, addItem),
+    );
+
+    act(() => {
+      result.current.openAuthDialog();
+    });
+
+    expect(result.current.isAuthDialogOpen).toBe(true);
+
+    await act(async () => {
+      void result.current.handleOpenRouterSubmit();
+      await Promise.resolve();
+    });
+
+    expect(result.current.pendingAuthType).toBe(AuthType.USE_OPENAI);
+    expect(result.current.isAuthenticating).toBe(true);
+    expect(result.current.externalAuthState).toEqual({
+      title: 'OpenRouter Authentication',
+      message:
+        'Open the authorization page if your browser does not launch automatically.',
+      detail: expect.stringContaining('https://openrouter.ai/auth'),
+    });
+    expect(result.current.isAuthDialogOpen).toBe(false);
+    expect(addItem).not.toHaveBeenCalled();
+  });
+
+  it('cancels OpenRouter OAuth wait and reopens the auth dialog', async () => {
+    const settings = createSettings();
+    const config = createConfig();
+    const addItem = vi.fn();
+
+    const { result } = renderHook(() =>
+      useAuthCommand(settings as never, config as never, addItem),
+    );
+
+    act(() => {
+      result.current.openAuthDialog();
+    });
+
+    await act(async () => {
+      void result.current.handleOpenRouterSubmit();
+      await Promise.resolve();
+    });
+
+    expect(result.current.isAuthenticating).toBe(true);
+    expect(createOpenRouterOAuthSession).toHaveBeenCalledWith(
+      OPENROUTER_OAUTH_CALLBACK_URL,
+    );
+    expect(runOpenRouterOAuthLogin).toHaveBeenCalledWith(
+      OPENROUTER_OAUTH_CALLBACK_URL,
+      expect.objectContaining({
+        abortSignal: expect.any(AbortSignal),
+        session: expect.objectContaining({
+          authorizationUrl: expect.stringContaining(
+            'https://openrouter.ai/auth',
+          ),
+        }),
+      }),
+    );
+
+    act(() => {
+      result.current.cancelAuthentication();
+    });
+
+    const abortSignal = vi.mocked(runOpenRouterOAuthLogin).mock.calls[0]?.[1]
+      ?.abortSignal;
+    expect(abortSignal?.aborted).toBe(true);
+    expect(result.current.isAuthenticating).toBe(false);
+    expect(result.current.externalAuthState).toBe(null);
+    expect(result.current.pendingAuthType).toBe(AuthType.USE_OPENAI);
+    expect(result.current.isAuthDialogOpen).toBe(true);
+  });
+
+  it('cleans up UI state when OpenRouter OAuth rejects with AbortError', async () => {
+    const settings = createSettings();
+    const config = createConfig();
+    const addItem = vi.fn();
+    vi.mocked(runOpenRouterOAuthLogin).mockRejectedValueOnce(
+      new DOMException('OpenRouter OAuth cancelled.', 'AbortError'),
+    );
+
+    const { result } = renderHook(() =>
+      useAuthCommand(settings as never, config as never, addItem),
+    );
+
+    await act(async () => {
+      await result.current.handleOpenRouterSubmit();
+    });
+
+    expect(result.current.isAuthenticating).toBe(false);
+    expect(result.current.externalAuthState).toBe(null);
+    expect(result.current.pendingAuthType).toBeUndefined();
+    expect(result.current.isAuthDialogOpen).toBe(true);
+    expect(addItem).not.toHaveBeenCalled();
+  });
+
+  it('adds /model and /manage-models guidance after OpenRouter auth succeeds', async () => {
+    const settings = createSettings();
+    const config = createConfig();
+    const addItem = vi.fn();
+    vi.mocked(runOpenRouterOAuthLogin).mockResolvedValueOnce({
+      apiKey: 'oauth-key-123',
+      userId: 'user-1',
+    });
+
+    const { result } = renderHook(() =>
+      useAuthCommand(settings as never, config as never, addItem),
+    );
+
+    await act(async () => {
+      await result.current.handleOpenRouterSubmit();
+    });
+
+    expect(applyOpenRouterModelsConfiguration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        settings: expect.anything(),
+        config: expect.anything(),
+        apiKey: 'oauth-key-123',
+        reloadConfig: true,
+      }),
+    );
+    expect(addItem).toHaveBeenCalledWith(
+      expect.objectContaining({ text: 'Successfully configured OpenRouter.' }),
+      expect.any(Number),
+    );
+    expect(addItem).toHaveBeenCalledWith(
+      expect.objectContaining({ text: 'Use /model to switch models.' }),
+      expect.any(Number),
+    );
+    expect(addItem).toHaveBeenCalledWith(
+      expect.objectContaining({
+        text: 'Want more OpenRouter models? Use /manage-models to browse and enable them.',
+      }),
+      expect.any(Number),
+    );
+  });
+});
+
+describe('generateCustomApiKeyEnvKey', () => {
+  it('generates env key from openai protocol and base URL', () => {
+    const key = generateCustomApiKeyEnvKey(
+      'openai',
+      'https://api.openai.com/v1',
+    );
+    expect(key).toBe('QWEN_CUSTOM_API_KEY_OPENAI_HTTPS_API_OPENAI_COM_V1');
+  });
+
+  it('generates env key from anthropic protocol and base URL', () => {
+    const key = generateCustomApiKeyEnvKey(
+      'anthropic',
+      'https://api.anthropic.com/v1',
+    );
+    expect(key).toBe(
+      'QWEN_CUSTOM_API_KEY_ANTHROPIC_HTTPS_API_ANTHROPIC_COM_V1',
+    );
+  });
+
+  it('generates env key from gemini protocol and base URL', () => {
+    const key = generateCustomApiKeyEnvKey(
+      'gemini',
+      'https://generativelanguage.googleapis.com',
+    );
+    expect(key).toBe(
+      'QWEN_CUSTOM_API_KEY_GEMINI_HTTPS_GENERATIVELANGUAGE_GOOGLEAPIS_COM',
+    );
+  });
+
+  it('handles localhost URLs', () => {
+    const key = generateCustomApiKeyEnvKey(
+      'openai',
+      'http://localhost:11434/v1',
+    );
+    expect(key).toBe('QWEN_CUSTOM_API_KEY_OPENAI_HTTP_LOCALHOST_11434_V1');
+  });
+
+  it('normalizes trailing slashes and special chars', () => {
+    const key = generateCustomApiKeyEnvKey(
+      'openai',
+      'https://openrouter.ai/api/v1/',
+    );
+    expect(key).toBe('QWEN_CUSTOM_API_KEY_OPENAI_HTTPS_OPENROUTER_AI_API_V1');
+  });
+
+  it('different protocols with same base URL produce different keys', () => {
+    const baseUrl = 'https://api.example.com/v1';
+    const openaiKey = generateCustomApiKeyEnvKey('openai', baseUrl);
+    const anthropicKey = generateCustomApiKeyEnvKey('anthropic', baseUrl);
+    expect(openaiKey).not.toBe(anthropicKey);
+    expect(openaiKey).toContain('OPENAI');
+    expect(anthropicKey).toContain('ANTHROPIC');
+  });
+});
+
+describe('normalizeCustomModelIds', () => {
+  it('splits comma-separated model IDs', () => {
+    const result = normalizeCustomModelIds('qwen/qwen3-coder,openai/gpt-4.1');
+    expect(result).toEqual(['qwen/qwen3-coder', 'openai/gpt-4.1']);
+  });
+
+  it('trims whitespace from each model ID', () => {
+    const result = normalizeCustomModelIds(
+      ' qwen/qwen3-coder , openai/gpt-4.1 ',
+    );
+    expect(result).toEqual(['qwen/qwen3-coder', 'openai/gpt-4.1']);
+  });
+
+  it('deduplicates while preserving order', () => {
+    const result = normalizeCustomModelIds(
+      'qwen/qwen3-coder,openai/gpt-4.1,qwen/qwen3-coder',
+    );
+    expect(result).toEqual(['qwen/qwen3-coder', 'openai/gpt-4.1']);
+  });
+
+  it('removes empty entries', () => {
+    const result = normalizeCustomModelIds('qwen/qwen3-coder,,openai/gpt-4.1');
+    expect(result).toEqual(['qwen/qwen3-coder', 'openai/gpt-4.1']);
+  });
+
+  it('returns empty array for empty input', () => {
+    const result = normalizeCustomModelIds('');
+    expect(result).toEqual([]);
+  });
+
+  it('returns empty array for whitespace-only input', () => {
+    const result = normalizeCustomModelIds('  ,  ,  ');
+    expect(result).toEqual([]);
+  });
+
+  it('handles single model ID', () => {
+    const result = normalizeCustomModelIds('qwen/qwen3-coder');
+    expect(result).toEqual(['qwen/qwen3-coder']);
+  });
+});
+
+describe('maskApiKey', () => {
+  it('masks a standard API key showing first 3 and last 4 chars', () => {
+    const result = maskApiKey('sk-or-v1-1234567890abcdef');
+    expect(result).toBe('sk-...cdef');
+  });
+
+  it('shows placeholder for empty string', () => {
+    const result = maskApiKey('');
+    expect(result).toBe('(not set)');
+  });
+
+  it('masks short keys with asterisks', () => {
+    const result = maskApiKey('abc');
+    expect(result).toBe('***');
+  });
+
+  it('masks 6-char keys with asterisks', () => {
+    const result = maskApiKey('abcdef');
+    expect(result).toBe('***');
+  });
+
+  it('trims whitespace before masking', () => {
+    const result = maskApiKey('  sk-or-v1-1234567890abcdef  ');
+    expect(result).toBe('sk-...cdef');
+  });
+});
diff --git a/packages/cli/src/ui/auth/useAuth.ts b/packages/cli/src/ui/auth/useAuth.ts
index eb32d7f87..c16c6060e 100644
--- a/packages/cli/src/ui/auth/useAuth.ts
+++ b/packages/cli/src/ui/auth/useAuth.ts
@@ -39,6 +39,53 @@ import {
   DASHSCOPE_STANDARD_API_KEY_ENV_KEY,
   type AlibabaStandardRegion,
 } from '../../constants/alibabaStandardApiKey.js';
+import {
+  applyOpenRouterModelsConfiguration,
+  createOpenRouterOAuthSession,
+  OPENROUTER_OAUTH_CALLBACK_URL,
+  runOpenRouterOAuthLogin,
+} from '../../commands/auth/openrouterOAuth.js';
+
+/**
+ * Generate a Qwen-managed env key from protocol and base URL.
+ * Format: QWEN_CUSTOM_API_KEY_${PROTOCOL}_${NORMALIZED_BASE_URL}
+ */
+export function generateCustomApiKeyEnvKey(
+  protocol: string,
+  baseUrl: string,
+): string {
+  const normalize = (value: string) =>
+    value
+      .trim()
+      .toUpperCase()
+      .replace(/[^A-Z0-9]+/g, '_')
+      .replace(/_+/g, '_')
+      .replace(/^_+|_+$/g, '');
+
+  return `QWEN_CUSTOM_API_KEY_${normalize(protocol)}_${normalize(baseUrl)}`;
+}
+
+/**
+ * Normalize model IDs: split by comma, trim, deduplicate, remove empty.
+ */
+export function normalizeCustomModelIds(modelIdsInput: string): string[] {
+  return modelIdsInput
+    .split(',')
+    .map((id) => id.trim())
+    .filter((id, index, array) => id.length > 0 && array.indexOf(id) === index);
+}
+
+/**
+ * Mask an API key for display: show first 3 and last 4 chars.
+ */
+export function maskApiKey(apiKey: string): string {
+  const trimmed = apiKey.trim();
+  if (trimmed.length === 0) return '(not set)';
+  if (trimmed.length <= 6) return '***';
+  const head = trimmed.slice(0, 3);
+  const tail = trimmed.slice(-4);
+  return `${head}...${tail}`;
+}
 
 export type { QwenAuthState } from '../hooks/useQwenAuth.js';
 
@@ -61,6 +108,13 @@ export const useAuthCommand = (
   const [pendingAuthType, setPendingAuthType] = useState<AuthType | undefined>(
     undefined,
   );
+  const [externalAuthState, setExternalAuthState] = useState<{
+    title: string;
+    message: string;
+    detail?: string;
+  } | null>(null);
+  const [openRouterAuthAbortController, setOpenRouterAuthAbortController] =
+    useState<AbortController | null>(null);
 
   const { qwenAuthState, cancelQwenAuth } = useQwenAuth(
     pendingAuthType,
@@ -81,6 +135,7 @@ export const useAuthCommand = (
   const handleAuthFailure = useCallback(
     (error: unknown) => {
       setIsAuthenticating(false);
+      setExternalAuthState(null);
       const errorMessage = t('Failed to authenticate. Message: {{message}}', {
         message: getErrorMessage(error),
       });
@@ -276,6 +331,11 @@ export const useAuthCommand = (
       cancelQwenAuth();
     }
 
+    if (isAuthenticating && pendingAuthType === AuthType.USE_OPENAI) {
+      openRouterAuthAbortController?.abort();
+      setOpenRouterAuthAbortController(null);
+    }
+
     // Log authentication cancellation
     if (isAuthenticating && pendingAuthType) {
       const authEvent = new AuthEvent(pendingAuthType, 'manual', 'cancelled');
@@ -284,9 +344,16 @@ export const useAuthCommand = (
 
     // Do not reset pendingAuthType here, persist the previously selected type.
     setIsAuthenticating(false);
+    setExternalAuthState(null);
     setIsAuthDialogOpen(true);
     setAuthError(null);
-  }, [isAuthenticating, pendingAuthType, cancelQwenAuth, config]);
+  }, [
+    isAuthenticating,
+    pendingAuthType,
+    cancelQwenAuth,
+    config,
+    openRouterAuthAbortController,
+  ]);
 
   /**
    * Handle coding plan submission - generates configs from template and stores api-key
@@ -552,6 +619,284 @@ export const useAuthCommand = (
     [settings, config, handleAuthFailure, addItem, onAuthChange],
   );
 
+  const handleOpenRouterSubmit = useCallback(async () => {
+    try {
+      setPendingAuthType(AuthType.USE_OPENAI);
+      setIsAuthenticating(true);
+      setAuthError(null);
+      setIsAuthDialogOpen(false);
+
+      const oauthSession = createOpenRouterOAuthSession(
+        OPENROUTER_OAUTH_CALLBACK_URL,
+      );
+      setExternalAuthState({
+        title: t('OpenRouter Authentication'),
+        message: t(
+          'Open the authorization page if your browser does not launch automatically.',
+        ),
+        detail: oauthSession.authorizationUrl,
+      });
+
+      const abortController = new AbortController();
+      setOpenRouterAuthAbortController(abortController);
+      const oauthResult = await runOpenRouterOAuthLogin(
+        OPENROUTER_OAUTH_CALLBACK_URL,
+        {
+          abortSignal: abortController.signal,
+          session: oauthSession,
+        },
+      );
+      setOpenRouterAuthAbortController(null);
+      setExternalAuthState({
+        title: t('OpenRouter Authentication'),
+        message: t('Finalizing OpenRouter setup...'),
+        detail: t(
+          'Syncing OpenRouter models and updating your local configuration.',
+        ),
+      });
+      const selectedKey = oauthResult.apiKey;
+      if (!selectedKey) {
+        throw new Error(
+          t('OpenRouter authentication completed without an API key.'),
+        );
+      }
+
+      const persistScope = getPersistScopeForModelSelection(settings);
+      const settingsFile = settings.forScope(persistScope);
+      backupSettingsFile(settingsFile.path);
+
+      await applyOpenRouterModelsConfiguration({
+        settings,
+        config,
+        apiKey: selectedKey,
+        reloadConfig: true,
+      });
+      await config.refreshAuth(AuthType.USE_OPENAI);
+
+      setAuthError(null);
+      setExternalAuthState(null);
+      setAuthState(AuthState.Authenticated);
+      setPendingAuthType(undefined);
+      setIsAuthDialogOpen(false);
+      setIsAuthenticating(false);
+      onAuthChange?.();
+
+      addItem(
+        {
+          type: MessageType.INFO,
+          text: t('Successfully configured OpenRouter.'),
+        },
+        Date.now(),
+      );
+
+      addItem(
+        {
+          type: MessageType.INFO,
+          text: t('Use /model to switch models.'),
+        },
+        Date.now(),
+      );
+
+      addItem(
+        {
+          type: MessageType.INFO,
+          text: t(
+            'Want more OpenRouter models? Use /manage-models to browse and enable them.',
+          ),
+        },
+        Date.now(),
+      );
+
+      const authEvent = new AuthEvent(AuthType.USE_OPENAI, 'manual', 'success');
+      logAuth(config, authEvent);
+    } catch (error) {
+      setOpenRouterAuthAbortController(null);
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        setExternalAuthState(null);
+        setPendingAuthType(undefined);
+        setIsAuthenticating(false);
+        setIsAuthDialogOpen(true);
+        return;
+      }
+      handleAuthFailure(error);
+    }
+  }, [
+    settings,
+    config,
+    handleAuthFailure,
+    addItem,
+    onAuthChange,
+    setOpenRouterAuthAbortController,
+  ]);
+
+  /**
+   * Handle custom API key setup wizard submission.
+   * Persists key to env[generatedEnvKey] and creates modelProviders entries.
+   */
+  const handleCustomApiKeySubmit = useCallback(
+    async (
+      protocol:
+        | AuthType.USE_OPENAI
+        | AuthType.USE_ANTHROPIC
+        | AuthType.USE_GEMINI,
+      baseUrl: string,
+      apiKey: string,
+      modelIdsInput: string,
+      generationConfig?: {
+        enableThinking?: boolean;
+        multimodal?: {
+          image?: boolean;
+          video?: boolean;
+          audio?: boolean;
+        };
+        maxTokens?: number;
+      },
+    ) => {
+      try {
+        setIsAuthenticating(true);
+        setAuthError(null);
+
+        const trimmedApiKey = apiKey.trim();
+        const trimmedBaseUrl = baseUrl.trim();
+        const modelIds = normalizeCustomModelIds(modelIdsInput);
+
+        if (!trimmedApiKey) {
+          throw new Error(t('API key cannot be empty.'));
+        }
+        if (!trimmedBaseUrl) {
+          throw new Error(t('Base URL cannot be empty.'));
+        }
+        if (!/^https?:\/\//i.test(trimmedBaseUrl)) {
+          throw new Error(t('Base URL must start with http:// or https://.'));
+        }
+        if (modelIds.length === 0) {
+          throw new Error(t('Model IDs cannot be empty.'));
+        }
+
+        const generatedEnvKey = generateCustomApiKeyEnvKey(
+          protocol,
+          trimmedBaseUrl,
+        );
+        const persistScope = getPersistScopeForModelSelection(settings);
+
+        const settingsFile = settings.forScope(persistScope);
+        backupSettingsFile(settingsFile.path);
+
+        // Persist API key to env
+        settings.setValue(
+          persistScope,
+          `env.${generatedEnvKey}`,
+          trimmedApiKey,
+        );
+        process.env[generatedEnvKey] = trimmedApiKey;
+
+        // Build generationConfig if any option is set
+        let genConfig: ProviderModelConfig['generationConfig'] | undefined;
+        if (generationConfig) {
+          const hasThinking = generationConfig.enableThinking === true;
+          const hasMultimodal =
+            generationConfig.multimodal &&
+            (generationConfig.multimodal.image === true ||
+              generationConfig.multimodal.video === true ||
+              generationConfig.multimodal.audio === true);
+          const hasMaxTokens =
+            generationConfig.maxTokens !== undefined &&
+            generationConfig.maxTokens > 0;
+
+          if (hasThinking || hasMultimodal || hasMaxTokens) {
+            genConfig = {};
+            if (hasMultimodal) {
+              genConfig.modalities = {
+                image: generationConfig.multimodal!.image ?? false,
+                video: generationConfig.multimodal!.video ?? false,
+                audio: generationConfig.multimodal!.audio ?? false,
+              };
+            }
+            if (hasThinking) {
+              genConfig.extra_body = { enable_thinking: true };
+            }
+            if (hasMaxTokens) {
+              genConfig.samplingParams = {
+                max_tokens: generationConfig.maxTokens,
+              };
+            }
+          }
+        }
+
+        // Build new model configs
+        const newConfigs: ProviderModelConfig[] = modelIds.map((modelId) => ({
+          id: modelId,
+          name: modelId,
+          baseUrl: trimmedBaseUrl,
+          envKey: generatedEnvKey,
+          ...(genConfig ? { generationConfig: genConfig } : {}),
+        }));
+
+        // Merge with existing configs: replace same generatedEnvKey, preserve rest
+        const existingConfigs =
+          (
+            settings.merged.modelProviders as ModelProvidersConfig | undefined
+          )?.[protocol] || [];
+
+        const preservedConfigs = existingConfigs.filter(
+          (existing) => existing.envKey !== generatedEnvKey,
+        );
+
+        const updatedConfigs = [...newConfigs, ...preservedConfigs];
+
+        // Persist modelProviders, security, model
+        settings.setValue(
+          persistScope,
+          `modelProviders.${protocol}`,
+          updatedConfigs,
+        );
+        settings.setValue(persistScope, 'security.auth.selectedType', protocol);
+        settings.setValue(persistScope, 'model.name', modelIds[0]);
+
+        // Hot-reload before refreshAuth
+        const updatedModelProviders: ModelProvidersConfig = {
+          ...(settings.merged.modelProviders as
+            | ModelProvidersConfig
+            | undefined),
+          [protocol]: updatedConfigs,
+        };
+        config.reloadModelProvidersConfig(updatedModelProviders);
+        await config.refreshAuth(protocol);
+
+        setAuthError(null);
+        setAuthState(AuthState.Authenticated);
+        setPendingAuthType(undefined);
+        setIsAuthDialogOpen(false);
+        setIsAuthenticating(false);
+        onAuthChange?.();
+
+        addItem(
+          {
+            type: MessageType.INFO,
+            text: t(
+              'Custom API Key authenticated successfully. Settings updated with generated env key and model provider config.',
+            ),
+          },
+          Date.now(),
+        );
+
+        addItem(
+          {
+            type: MessageType.INFO,
+            text: t('Tip: Use /model to switch between configured models.'),
+          },
+          Date.now(),
+        );
+
+        const authEvent = new AuthEvent(protocol, 'manual', 'success');
+        logAuth(config, authEvent);
+      } catch (error) {
+        handleAuthFailure(error);
+      }
+    },
+    [settings, config, handleAuthFailure, addItem, onAuthChange],
+  );
+
   /**
    /**
     * We previously used a useEffect to trigger authentication automatically when
@@ -600,10 +945,13 @@ export const useAuthCommand = (
     isAuthDialogOpen,
     isAuthenticating,
     pendingAuthType,
+    externalAuthState,
     qwenAuthState,
     handleAuthSelect,
     handleCodingPlanSubmit,
     handleAlibabaStandardSubmit,
+    handleOpenRouterSubmit,
+    handleCustomApiKeySubmit,
     openAuthDialog,
     cancelAuthentication,
   };
diff --git a/packages/cli/src/ui/commands/manageModelsCommand.test.ts b/packages/cli/src/ui/commands/manageModelsCommand.test.ts
new file mode 100644
index 000000000..2666d4f8b
--- /dev/null
+++ b/packages/cli/src/ui/commands/manageModelsCommand.test.ts
@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { manageModelsCommand } from './manageModelsCommand.js';
+import type { CommandContext } from './types.js';
+import { createMockCommandContext } from '../../test-utils/mockCommandContext.js';
+
+describe('manageModelsCommand', () => {
+  let mockContext: CommandContext;
+
+  beforeEach(() => {
+    mockContext = createMockCommandContext();
+  });
+
+  it('should return a dialog action to open the manage-models dialog', () => {
+    if (!manageModelsCommand.action) {
+      throw new Error('The manage-models command must have an action.');
+    }
+
+    const result = manageModelsCommand.action(mockContext, '');
+
+    expect(result).toEqual({
+      type: 'dialog',
+      dialog: 'manage-models',
+    });
+  });
+
+  it('should have the correct name and description', () => {
+    expect(manageModelsCommand.name).toBe('manage-models');
+    expect(manageModelsCommand.description).toBe(
+      'Browse dynamic model catalogs and choose which models stay enabled locally',
+    );
+  });
+});
diff --git a/packages/cli/src/ui/commands/manageModelsCommand.ts b/packages/cli/src/ui/commands/manageModelsCommand.ts
new file mode 100644
index 000000000..e16b18016
--- /dev/null
+++ b/packages/cli/src/ui/commands/manageModelsCommand.ts
@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { OpenDialogActionReturn, SlashCommand } from './types.js';
+import { CommandKind } from './types.js';
+import { t } from '../../i18n/index.js';
+
+export const manageModelsCommand: SlashCommand = {
+  name: 'manage-models',
+  get description() {
+    return t(
+      'Browse dynamic model catalogs and choose which models stay enabled locally',
+    );
+  },
+  kind: CommandKind.BUILT_IN,
+  supportedModes: ['interactive'] as const,
+  action: (): OpenDialogActionReturn => ({
+    type: 'dialog',
+    dialog: 'manage-models',
+  }),
+};
diff --git a/packages/cli/src/ui/commands/rewindCommand.ts b/packages/cli/src/ui/commands/rewindCommand.ts
new file mode 100644
index 000000000..020091795
--- /dev/null
+++ b/packages/cli/src/ui/commands/rewindCommand.ts
@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { SlashCommand, SlashCommandActionReturn } from './types.js';
+import { CommandKind } from './types.js';
+import { t } from '../../i18n/index.js';
+
+export const rewindCommand: SlashCommand = {
+  name: 'rewind',
+  altNames: ['rollback'],
+  get description() {
+    return t('Rewind conversation to a previous turn');
+  },
+  kind: CommandKind.BUILT_IN,
+  action: async (): Promise<SlashCommandActionReturn> => ({
+    type: 'dialog',
+    dialog: 'rewind',
+  }),
+};
diff --git a/packages/cli/src/ui/commands/tasksCommand.test.ts b/packages/cli/src/ui/commands/tasksCommand.test.ts
new file mode 100644
index 000000000..9d4355b04
--- /dev/null
+++ b/packages/cli/src/ui/commands/tasksCommand.test.ts
@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+import { tasksCommand } from './tasksCommand.js';
+import { type CommandContext } from './types.js';
+import { createMockCommandContext } from '../../test-utils/mockCommandContext.js';
+import type { BackgroundShellEntry } from '@qwen-code/qwen-code-core';
+
+function entry(
+  overrides: Partial<BackgroundShellEntry> = {},
+): BackgroundShellEntry {
+  return {
+    shellId: 'bg_aaaaaaaa',
+    command: 'sleep 60',
+    cwd: '/tmp',
+    status: 'running',
+    startTime: Date.now() - 5_000,
+    outputPath: '/tmp/tasks/sess/shell-bg_aaaaaaaa.output',
+    abortController: new AbortController(),
+    ...overrides,
+  };
+}
+
+describe('tasksCommand', () => {
+  let context: CommandContext;
+  let getAll: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    getAll = vi.fn().mockReturnValue([]);
+    context = createMockCommandContext({
+      services: {
+        config: {
+          getBackgroundShellRegistry: () => ({ getAll }),
+        },
+      },
+    } as unknown as Parameters<typeof createMockCommandContext>[0]);
+  });
+
+  it('reports an empty registry', async () => {
+    const result = await tasksCommand.action!(context, '');
+    expect(result).toEqual({
+      type: 'message',
+      messageType: 'info',
+      content: 'No background shells.',
+    });
+  });
+
+  it('lists running and terminal entries with status / runtime / output path', async () => {
+    getAll.mockReturnValue([
+      entry({
+        shellId: 'bg_run',
+        command: 'npm run dev',
+        status: 'running',
+        startTime: Date.now() - 12_000,
+        pid: 1111,
+      }),
+      entry({
+        shellId: 'bg_done',
+        command: 'npm test',
+        status: 'completed',
+        exitCode: 0,
+        startTime: Date.now() - 70_000,
+        endTime: Date.now() - 5_000,
+        outputPath: '/tmp/tasks/sess/shell-bg_done.output',
+      }),
+      entry({
+        shellId: 'bg_fail',
+        command: 'flaky.sh',
+        status: 'failed',
+        error: 'spawn ENOENT',
+        startTime: Date.now() - 3_000,
+        endTime: Date.now() - 2_000,
+      }),
+    ]);
+
+    const result = await tasksCommand.action!(context, '');
+    if (!result || result.type !== 'message') {
+      throw new Error('expected message result');
+    }
+    expect(result.content).toContain('Background shells (3 total)');
+    expect(result.content).toContain('[bg_run] running');
+    expect(result.content).toContain('pid=1111');
+    expect(result.content).toContain('npm run dev');
+    expect(result.content).toContain('[bg_done] completed (exit 0)');
+    expect(result.content).toContain('[bg_fail] failed: spawn ENOENT');
+    expect(result.content).toContain(
+      'output: /tmp/tasks/sess/shell-bg_done.output',
+    );
+  });
+});
diff --git a/packages/cli/src/ui/commands/tasksCommand.ts b/packages/cli/src/ui/commands/tasksCommand.ts
new file mode 100644
index 000000000..b58772e41
--- /dev/null
+++ b/packages/cli/src/ui/commands/tasksCommand.ts
@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { BackgroundShellEntry } from '@qwen-code/qwen-code-core';
+import type { SlashCommand } from './types.js';
+import { CommandKind } from './types.js';
+import { t } from '../../i18n/index.js';
+import { formatDuration } from '../utils/formatters.js';
+
+function statusLabel(entry: BackgroundShellEntry): string {
+  switch (entry.status) {
+    case 'completed':
+      return `completed (exit ${entry.exitCode ?? '?'})`;
+    case 'failed':
+      return `failed: ${entry.error ?? 'unknown error'}`;
+    case 'cancelled':
+      return 'cancelled';
+    case 'running':
+      return 'running';
+    default:
+      return entry.status;
+  }
+}
+
+export const tasksCommand: SlashCommand = {
+  name: 'tasks',
+  get description() {
+    return t('List background tasks');
+  },
+  kind: CommandKind.BUILT_IN,
+  supportedModes: ['interactive', 'non_interactive', 'acp'] as const,
+  action: async (context) => {
+    const { config } = context.services;
+    if (!config) {
+      return {
+        type: 'message' as const,
+        messageType: 'error' as const,
+        content: 'Config not available.',
+      };
+    }
+
+    const entries = config.getBackgroundShellRegistry().getAll();
+
+    if (entries.length === 0) {
+      return {
+        type: 'message' as const,
+        messageType: 'info' as const,
+        content: 'No background shells.',
+      };
+    }
+
+    const now = Date.now();
+    const lines: string[] = [
+      `Background shells (${entries.length} total)`,
+      '',
+    ];
+    for (const entry of entries) {
+      const endTime = entry.endTime ?? now;
+      const runtime = formatDuration(endTime - entry.startTime, {
+        hideTrailingZeros: true,
+      });
+      const pidPart = entry.pid !== undefined ? ` pid=${entry.pid}` : '';
+      lines.push(
+        `[${entry.shellId}] ${statusLabel(entry)}  ${runtime}${pidPart}  ${entry.command}`,
+      );
+      lines.push(`            output: ${entry.outputPath}`);
+    }
+
+    return {
+      type: 'message' as const,
+      messageType: 'info' as const,
+      content: lines.join('\n'),
+    };
+  },
+};
diff --git a/packages/cli/src/ui/commands/types.ts b/packages/cli/src/ui/commands/types.ts
index 01e6d6564..9afd2ac9c 100644
--- a/packages/cli/src/ui/commands/types.ts
+++ b/packages/cli/src/ui/commands/types.ts
@@ -173,6 +173,7 @@ export interface OpenDialogActionReturn {
     | 'memory'
     | 'model'
     | 'fast-model'
+    | 'manage-models'
     | 'subagent_create'
     | 'subagent_list'
     | 'trust'
@@ -182,7 +183,8 @@ export interface OpenDialogActionReturn {
     | 'delete'
     | 'extensions_manage'
     | 'hooks'
-    | 'mcp';
+    | 'mcp'
+    | 'rewind';
 }
 
 /**
diff --git a/packages/cli/src/ui/components/DialogManager.tsx b/packages/cli/src/ui/components/DialogManager.tsx
index dc0c64d27..e15ad77b4 100644
--- a/packages/cli/src/ui/components/DialogManager.tsx
+++ b/packages/cli/src/ui/components/DialogManager.tsx
@@ -16,11 +16,13 @@ import { PluginChoicePrompt } from './PluginChoicePrompt.js';
 import { ThemeDialog } from './ThemeDialog.js';
 import { SettingsDialog } from './SettingsDialog.js';
 import { QwenOAuthProgress } from './QwenOAuthProgress.js';
+import { ExternalAuthProgress } from './ExternalAuthProgress.js';
 import { AuthDialog } from '../auth/AuthDialog.js';
 import { EditorSettingsDialog } from './EditorSettingsDialog.js';
 import { TrustDialog } from './TrustDialog.js';
 import { PermissionsDialog } from './PermissionsDialog.js';
 import { ModelDialog } from './ModelDialog.js';
+import { ManageModelsDialog } from './ManageModelsDialog.js';
 import { ArenaStartDialog } from './arena/ArenaStartDialog.js';
 import { ArenaSelectDialog } from './arena/ArenaSelectDialog.js';
 import { ArenaStopDialog } from './arena/ArenaStopDialog.js';
@@ -43,7 +45,10 @@ import { ExtensionsManagerDialog } from './extensions/ExtensionsManagerDialog.js
 import { MCPManagementDialog } from './mcp/MCPManagementDialog.js';
 import { HooksManagementDialog } from './hooks/HooksManagementDialog.js';
 import { SessionPicker } from './SessionPicker.js';
+import { RewindSelector } from './RewindSelector.js';
 import { MemoryDialog } from './MemoryDialog.js';
+import { BackgroundTasksDialog } from './background-view/BackgroundTasksDialog.js';
+import { useBackgroundTaskViewState } from '../contexts/BackgroundTaskViewContext.js';
 import { t } from '../../i18n/index.js';
 
 interface DialogManagerProps {
@@ -61,6 +66,7 @@ export const DialogManager = ({
 
   const uiState = useUIState();
   const uiActions = useUIActions();
+  const { dialogOpen: bgTasksDialogOpen } = useBackgroundTaskViewState();
   const { constrainHeight, terminalHeight, staticExtraHeight, mainAreaWidth } =
     uiState;
 
@@ -212,6 +218,14 @@ export const DialogManager = ({
       />
     );
   }
+  if (uiState.isManageModelsDialogOpen) {
+    return (
+      <ManageModelsDialog
+        config={config}
+        onClose={uiActions.closeManageModelsDialog}
+      />
+    );
+  }
   if (uiState.isSettingsDialogOpen) {
     return (
       <Box flexDirection="column">
@@ -309,6 +323,23 @@ export const DialogManager = ({
   }
 
   if (uiState.isAuthenticating) {
+    if (
+      uiState.pendingAuthType === AuthType.USE_OPENAI &&
+      uiState.externalAuthState
+    ) {
+      return (
+        <ExternalAuthProgress
+          title={uiState.externalAuthState.title}
+          message={uiState.externalAuthState.message}
+          detail={uiState.externalAuthState.detail}
+          onCancel={() => {
+            uiActions.cancelAuthentication();
+            uiActions.setAuthState(AuthState.Updating);
+          }}
+        />
+      );
+    }
+
     // OpenAI authentication now handled through AuthDialog with coding-plan/custom sub-modes
     // Qwen OAuth remains as a separate flow
     if (uiState.pendingAuthType === AuthType.QWEN_OAUTH) {
@@ -381,6 +412,7 @@ export const DialogManager = ({
         onSelect={uiActions.handleResume}
         onCancel={uiActions.closeResumeDialog}
         initialSessions={uiState.resumeMatchedSessions}
+        enablePreview
       />
     );
   }
@@ -397,5 +429,29 @@ export const DialogManager = ({
     );
   }
 
+  if (uiState.isRewindSelectorOpen) {
+    return (
+      <RewindSelector
+        history={uiState.history}
+        onRewind={uiActions.handleRewindConfirm}
+        onCancel={uiActions.closeRewindSelector}
+      />
+    );
+  }
+
+  // Background tasks dialog — lowest priority so other dialogs
+  // (permissions, trust prompts, auth, etc.) always take precedence. The
+  // dialog is part of the shared dialogsVisible machinery (see
+  // AppContainer) so its visibility mutes the composer and the global
+  // Ctrl+C / Esc handlers route through `closeAnyOpenDialog`.
+  if (bgTasksDialogOpen) {
+    return (
+      <BackgroundTasksDialog
+        availableTerminalHeight={terminalHeight - staticExtraHeight}
+        terminalWidth={mainAreaWidth}
+      />
+    );
+  }
+
   return null;
 };
diff --git a/packages/cli/src/ui/components/ExternalAuthProgress.test.tsx b/packages/cli/src/ui/components/ExternalAuthProgress.test.tsx
new file mode 100644
index 000000000..528d20237
--- /dev/null
+++ b/packages/cli/src/ui/components/ExternalAuthProgress.test.tsx
@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { render } from 'ink-testing-library';
+import { ExternalAuthProgress } from './ExternalAuthProgress.js';
+
+vi.mock('../hooks/useKeypress.js', () => ({
+  useKeypress: vi.fn(),
+}));
+
+describe('ExternalAuthProgress', () => {
+  it('shows cancel hint when cancel is available', () => {
+    const onCancel = vi.fn();
+    const { lastFrame } = render(
+      <ExternalAuthProgress
+        title="OpenRouter Authentication"
+        message="Open the authorization page if your browser does not launch automatically."
+        detail="https://openrouter.ai/auth?example=1"
+        onCancel={onCancel}
+      />,
+    );
+
+    expect(lastFrame()).toContain('Esc to cancel');
+  });
+});
diff --git a/packages/cli/src/ui/components/ExternalAuthProgress.tsx b/packages/cli/src/ui/components/ExternalAuthProgress.tsx
new file mode 100644
index 000000000..cfea9a81d
--- /dev/null
+++ b/packages/cli/src/ui/components/ExternalAuthProgress.tsx
@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { Box, Text } from 'ink';
+import { theme } from '../semantic-colors.js';
+import { t } from '../../i18n/index.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+
+interface ExternalAuthProgressProps {
+  title: string;
+  message: string;
+  detail?: string;
+  onCancel?: () => void;
+}
+
+export function ExternalAuthProgress({
+  title,
+  message,
+  detail,
+  onCancel,
+}: ExternalAuthProgressProps): React.JSX.Element {
+  useKeypress(
+    (key) => {
+      if (key.name === 'escape' || (key.ctrl && key.name === 'c')) {
+        onCancel?.();
+      }
+    },
+    { isActive: Boolean(onCancel) },
+  );
+
+  return (
+    <Box
+      borderStyle="single"
+      borderColor={theme.border.default}
+      flexDirection="column"
+      padding={1}
+      width="100%"
+    >
+      <Text bold>{title}</Text>
+
+      <Box marginTop={1} flexDirection="column">
+        <Text>{message}</Text>
+        {detail ? <Text color={theme.text.secondary}>{detail}</Text> : null}
+      </Box>
+
+      <Box marginTop={1} flexDirection="column">
+        <Text color={theme.text.secondary}>
+          {t('Please wait while authentication completes...')}
+        </Text>
+        {onCancel ? (
+          <Text color={theme.text.secondary}>{t('Esc to cancel')}</Text>
+        ) : null}
+      </Box>
+    </Box>
+  );
+}
diff --git a/packages/cli/src/ui/components/Footer.test.tsx b/packages/cli/src/ui/components/Footer.test.tsx
index c405dbe3e..064206a92 100644
--- a/packages/cli/src/ui/components/Footer.test.tsx
+++ b/packages/cli/src/ui/components/Footer.test.tsx
@@ -13,6 +13,7 @@ import { type UIState, UIStateContext } from '../contexts/UIStateContext.js';
 import { ConfigContext } from '../contexts/ConfigContext.js';
 import { VimModeProvider } from '../contexts/VimModeContext.js';
 import { SettingsContext } from '../contexts/SettingsContext.js';
+import { KeypressProvider } from '../contexts/KeypressContext.js';
 import type { LoadedSettings } from '../../config/settings.js';
 
 vi.mock('../hooks/useTerminalSize.js');
@@ -97,11 +98,13 @@ const renderWithWidth = (width: number, uiState: UIState) => {
   return render(
     <SettingsContext.Provider value={mockSettings}>
       <ConfigContext.Provider value={createMockConfig() as never}>
-        <VimModeProvider settings={mockSettings}>
-          <UIStateContext.Provider value={uiState}>
-            <Footer />
-          </UIStateContext.Provider>
-        </VimModeProvider>
+        <KeypressProvider kittyProtocolEnabled={false}>
+          <VimModeProvider settings={mockSettings}>
+            <UIStateContext.Provider value={uiState}>
+              <Footer />
+            </UIStateContext.Provider>
+          </VimModeProvider>
+        </KeypressProvider>
       </ConfigContext.Provider>
     </SettingsContext.Provider>,
   );
diff --git a/packages/cli/src/ui/components/Footer.tsx b/packages/cli/src/ui/components/Footer.tsx
index 1debdcb9c..efebd5e90 100644
--- a/packages/cli/src/ui/components/Footer.tsx
+++ b/packages/cli/src/ui/components/Footer.tsx
@@ -12,6 +12,7 @@ import { ContextUsageDisplay } from './ContextUsageDisplay.js';
 import { useTerminalSize } from '../hooks/useTerminalSize.js';
 import { AutoAcceptIndicator } from './AutoAcceptIndicator.js';
 import { ShellModeIndicator } from './ShellModeIndicator.js';
+import { BackgroundTasksPill } from './background-view/BackgroundTasksPill.js';
 import { isNarrowWidth } from '../utils/isNarrowWidth.js';
 
 import { useStatusLine } from '../hooks/useStatusLine.js';
@@ -100,6 +101,10 @@ export const Footer: React.FC = () => {
     <Text color={theme.status.warning}>{t('Press Ctrl+D again to exit.')}</Text>
   ) : uiState.showEscapePrompt ? (
     <Text color={theme.text.secondary}>{t('Press Esc again to clear.')}</Text>
+  ) : uiState.rewindEscPending ? (
+    <Text color={theme.text.secondary}>
+      {t('Press Esc again to rewind conversation.')}
+    </Text>
   ) : vimEnabled && vimMode === 'INSERT' ? (
     <Text color={theme.text.secondary}>-- INSERT --</Text>
   ) : uiState.shellModeActive ? (
@@ -169,7 +174,10 @@ export const Footer: React.FC = () => {
               {line}
             </Text>
           ))}
-        <Text wrap="truncate">{leftBottomContent}</Text>
+        <Box flexDirection="row" flexShrink={1}>
+          <Text wrap="truncate">{leftBottomContent}</Text>
+          <BackgroundTasksPill />
+        </Box>
       </Box>
 
       {/* Right Section — never compressed, aligns to top so multi-line
diff --git a/packages/cli/src/ui/components/Header.test.tsx b/packages/cli/src/ui/components/Header.test.tsx
index 72da62aba..087618654 100644
--- a/packages/cli/src/ui/components/Header.test.tsx
+++ b/packages/cli/src/ui/components/Header.test.tsx
@@ -5,7 +5,7 @@
  */
 
 import { render } from 'ink-testing-library';
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { Header, AuthDisplayType } from './Header.js';
 import * as useTerminalSize from '../hooks/useTerminalSize.js';
 
@@ -20,10 +20,21 @@ const defaultProps = {
 };
 
 describe('<Header />', () => {
+  const originalNoColor = process.env['NO_COLOR'];
+
   beforeEach(() => {
+    delete process.env['NO_COLOR'];
     useTerminalSizeMock.mockReturnValue({ columns: 120, rows: 24 });
   });
 
+  afterEach(() => {
+    if (originalNoColor === undefined) {
+      delete process.env['NO_COLOR'];
+    } else {
+      process.env['NO_COLOR'] = originalNoColor;
+    }
+  });
+
   it('renders the ASCII logo on wide terminal', () => {
     const { lastFrame } = render(<Header {...defaultProps} />);
     expect(lastFrame()).toContain('██╔═══██╗');
@@ -81,4 +92,12 @@ describe('<Header />', () => {
     expect(lastFrame()).toContain('┌');
     expect(lastFrame()).toContain('┐');
   });
+
+  it('renders plain text when NO_COLOR disables gradient colors', () => {
+    process.env['NO_COLOR'] = '1';
+
+    const { lastFrame } = render(<Header {...defaultProps} />);
+
+    expect(lastFrame()).toContain('██╔═══██╗');
+  });
 });
diff --git a/packages/cli/src/ui/components/Header.tsx b/packages/cli/src/ui/components/Header.tsx
index 2d919385f..345bb9fe4 100644
--- a/packages/cli/src/ui/components/Header.tsx
+++ b/packages/cli/src/ui/components/Header.tsx
@@ -12,6 +12,7 @@ import { theme } from '../semantic-colors.js';
 import { shortAsciiLogo } from './AsciiArt.js';
 import { getAsciiArtWidth, getCachedStringWidth } from '../utils/textUtils.js';
 import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { getRenderableGradientColors } from '../utils/gradientUtils.js';
 
 /**
  * Auth display type for the Header component.
@@ -98,12 +99,11 @@ export const Header: React.FC<HeaderProps> = ({
         ? shortenedPath.slice(0, maxPathLength)
         : shortenedPath;
 
-  // Use theme gradient colors if available, otherwise use text colors (excluding primary)
-  const gradientColors = theme.ui.gradient || [
+  const gradientColors = getRenderableGradientColors(theme.ui.gradient, [
     theme.text.secondary,
     theme.text.link,
     theme.text.accent,
-  ];
+  ]);
 
   return (
     <Box
@@ -116,9 +116,13 @@ export const Header: React.FC<HeaderProps> = ({
       {showLogo && (
         <>
           <Box flexShrink={0}>
-            <Gradient colors={gradientColors}>
+            {gradientColors ? (
+              <Gradient colors={gradientColors}>
+                <Text>{displayLogo}</Text>
+              </Gradient>
+            ) : (
               <Text>{displayLogo}</Text>
-            </Gradient>
+            )}
           </Box>
           {/* Fixed gap between logo and info panel */}
           <Box width={logoGap} />
diff --git a/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx b/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx
index 7b4a22e80..443a28d18 100644
--- a/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx
+++ b/packages/cli/src/ui/components/HistoryItemDisplay.test.tsx
@@ -284,4 +284,23 @@ describe('<HistoryItemDisplay />', () => {
 
     expect(lastFrame()).toMatchSnapshot();
   });
+
+  it('renders tool_use_summary as a dim badge line in full mode', () => {
+    const item: HistoryItem = {
+      id: 1,
+      type: 'tool_use_summary',
+      summary: 'Read txt files',
+      precedingToolUseIds: ['c1', 'c2', 'c3', 'c4'],
+    };
+    const { lastFrame } = renderWithProviders(
+      <HistoryItemDisplay
+        {...baseItem}
+        item={item}
+        isPending={false}
+        terminalWidth={80}
+      />,
+    );
+    expect(lastFrame()).toContain('Read txt files');
+    expect(lastFrame()).toContain('●');
+  });
 });
diff --git a/packages/cli/src/ui/components/HistoryItemDisplay.tsx b/packages/cli/src/ui/components/HistoryItemDisplay.tsx
index a37544db0..5344da6a1 100644
--- a/packages/cli/src/ui/components/HistoryItemDisplay.tsx
+++ b/packages/cli/src/ui/components/HistoryItemDisplay.tsx
@@ -64,6 +64,21 @@ interface HistoryItemDisplayProps {
   activeShellPtyId?: number | null;
   embeddedShellFocused?: boolean;
   availableTerminalHeightGemini?: number;
+  /**
+   * When the item is a `tool_group`, an optional short LLM-generated label
+   * summarizing the batch. Replaces the generic "Tool × N" line in compact
+   * mode. Computed by the parent from `tool_use_summary` history items.
+   */
+  compactLabel?: string;
+  /**
+   * When the item is a `tool_use_summary`, true if a sibling tool_group has
+   * absorbed this label via its compact-mode header. The standalone `● <label>`
+   * line is suppressed in that case. False for force-expanded groups in
+   * compact mode (they render through the full ToolGroupMessage path and
+   * don't consume compactLabel, so the standalone line is the label's only
+   * path to the screen) and for all tool_use_summary items in full mode.
+   */
+  summaryAbsorbed?: boolean;
 }
 
 const HistoryItemDisplayComponent: React.FC<HistoryItemDisplayProps> = ({
@@ -77,6 +92,8 @@ const HistoryItemDisplayComponent: React.FC<HistoryItemDisplayProps> = ({
   activeShellPtyId,
   embeddedShellFocused,
   availableTerminalHeightGemini,
+  compactLabel,
+  summaryAbsorbed = false,
 }) => {
   const marginTop =
     item.type === 'gemini_content' || item.type === 'gemini_thought_content'
@@ -198,8 +215,33 @@ const HistoryItemDisplayComponent: React.FC<HistoryItemDisplayProps> = ({
           memoryWriteCount={itemForDisplay.memoryWriteCount}
           memoryReadCount={itemForDisplay.memoryReadCount}
           isUserInitiated={itemForDisplay.isUserInitiated}
+          compactLabel={compactLabel}
         />
       )}
+      {/*
+        `tool_use_summary` as a standalone inline item.
+
+        In full mode (`compactMode=false`), the label arrives via the fast-model
+        call AFTER the tool_group has been committed to Ink's append-only
+        <Static>, so we cannot update the tool_group's header retroactively.
+        Rendering a standalone `● <label>` line appends cleanly.
+
+        In compact mode, the label is normally absorbed into the merged
+        tool_group's header (via `compactLabel` prop to CompactToolGroupDisplay),
+        and `summaryAbsorbed=true` is set so this block does nothing. But when
+        the sibling tool_group is force-expanded (errors, confirmations,
+        user-initiated, focused shell), the full-expand path ignores
+        `compactLabel`, and `MainContent` leaves `summaryAbsorbed=false` —
+        the standalone line below is then the label's only route to the UI,
+        which is exactly the case where a summary is most diagnostically
+        useful ("Fixed NPE in UserService" on an errored batch).
+      */}
+      {itemForDisplay.type === 'tool_use_summary' &&
+        (!compactMode || !summaryAbsorbed) && (
+          <Box paddingLeft={1}>
+            <Text dimColor>● {itemForDisplay.summary}</Text>
+          </Box>
+        )}
       {itemForDisplay.type === 'compression' && (
         <CompressionMessage compression={itemForDisplay.compression} />
       )}
diff --git a/packages/cli/src/ui/components/InputPrompt.tsx b/packages/cli/src/ui/components/InputPrompt.tsx
index bbdf36f5c..9e8eb31c9 100644
--- a/packages/cli/src/ui/components/InputPrompt.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.tsx
@@ -47,6 +47,10 @@ import {
   useAgentViewState,
   useAgentViewActions,
 } from '../contexts/AgentViewContext.js';
+import {
+  useBackgroundTaskViewState,
+  useBackgroundTaskViewActions,
+} from '../contexts/BackgroundTaskViewContext.js';
 import { FEEDBACK_DIALOG_KEYS } from '../FeedbackDialog.js';
 import { BaseTextInput } from './BaseTextInput.js';
 import type { RenderLineOptions } from './BaseTextInput.js';
@@ -124,7 +128,16 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   const { pasteWorkaround } = useKeypressContext();
   const { agents, agentTabBarFocused } = useAgentViewState();
   const { setAgentTabBarFocused } = useAgentViewActions();
+  const {
+    entries: bgEntries,
+    dialogOpen: bgDialogOpen,
+    pillFocused: bgPillFocused,
+  } = useBackgroundTaskViewState();
+  const { setPillFocused: setBgPillFocused } = useBackgroundTaskViewActions();
   const hasAgents = agents.size > 0;
+  // Includes terminal entries — the pill stays open so users can reopen
+  // the dialog to inspect final state after the last agent finishes.
+  const hasBgAgents = bgEntries.length > 0;
   const [justNavigatedHistory, setJustNavigatedHistory] = useState(false);
   const [escPressCount, setEscPressCount] = useState(0);
   const [showEscapePrompt, setShowEscapePrompt] = useState(false);
@@ -194,6 +207,8 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
   const midInputGhostTextRef = useRef<{
     text: string;
     insertPosition: number;
+    acceptText?: string;
+    showCursorBeforeText?: boolean;
   } | null>(null);
   midInputGhostTextRef.current = completion.midInputGhostText;
 
@@ -443,12 +458,12 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
 
   const handleInput = useCallback(
     (key: Key): boolean => {
-      // When the tab bar has focus, block all non-printable keys so arrow
-      // keys and shortcuts don't interfere. Printable characters fall
-      // through to BaseTextInput's default handler so the first keystroke
-      // appears in the input immediately (the tab bar handler releases
-      // focus on the same event).
-      if (agentTabBarFocused) {
+      // When the Arena tab bar or background pill has focus, block
+      // non-printable keys so arrow keys and shortcuts don't interfere.
+      // Printable characters fall through to BaseTextInput's default
+      // handler so the first keystroke appears in the input immediately
+      // (each surface's own handler releases focus on the same event).
+      if (agentTabBarFocused || bgPillFocused) {
         if (
           key.sequence &&
           key.sequence.length === 1 &&
@@ -460,6 +475,16 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         return true; // consume non-printable keys
       }
 
+      // When the Background tasks dialog is open, swallow every key so
+      // nothing reaches the composer buffer — the dialog's own keypress
+      // handler owns selection, open/close, and stop actions. Unlike
+      // the tab bar we do NOT let printable chars type through, because
+      // the dialog doesn't auto-close on printable input and users
+      // would leak text into the hidden composer.
+      if (bgDialogOpen) {
+        return true;
+      }
+
       // TODO(jacobr): this special case is likely not needed anymore.
       // We should probably stop supporting paste if the InputPrompt is not
       // focused.
@@ -827,9 +852,9 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         !key.paste &&
         !key.shift &&
         !completion.showSuggestions &&
-        midInputGhostTextRef.current
+        midInputGhostTextRef.current?.acceptText
       ) {
-        buffer.insert(midInputGhostTextRef.current.text);
+        buffer.insert(midInputGhostTextRef.current.acceptText);
         return true;
       }
 
@@ -927,10 +952,20 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
           if (inputHistory.navigateDown()) {
             return true;
           }
+          // Focus order on Down from an empty composer:
+          // team tab bar (if any Arena agents) → Background tasks pill
+          // (if any bg agents) → otherwise stay put. The pill itself
+          // opens the dialog on Enter; the tab bar re-routes Down into
+          // the pill once it has focus, so both surfaces remain reachable
+          // in sequence.
           if (hasAgents) {
             setAgentTabBarFocused(true);
             return true;
           }
+          if (hasBgAgents) {
+            setBgPillFocused(true);
+            return true;
+          }
           return true;
         }
       } else {
@@ -1094,8 +1129,12 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
       parsePlaceholder,
       freePlaceholderId,
       agentTabBarFocused,
+      bgDialogOpen,
+      bgPillFocused,
       hasAgents,
+      hasBgAgents,
       setAgentTabBarFocused,
+      setBgPillFocused,
       followup,
       onPromptSuggestionDismiss,
     ],
@@ -1169,18 +1208,29 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
         // Check for mid-input ghost text (only renders when cursor is at end of input)
         const ghostText = midInputGhostTextRef.current;
         if (ghostText && showCursorOpt && ghostText.text.length > 0) {
-          // First ghost char: inverted (as cursor). Rest: dimmed gray.
-          const firstChar = ghostText.text[0]!;
-          const rest = ghostText.text.slice(firstChar.length);
-          renderedLine.push(
-            <Text key="ghost-cursor">{chalk.inverse(firstChar)}</Text>,
-          );
-          if (rest.length > 0) {
+          if (ghostText.showCursorBeforeText) {
+            renderedLine.push(
+              <Text key="ghost-cursor">{chalk.inverse(' ')}</Text>,
+            );
             renderedLine.push(
               <Text key="ghost-rest" color={theme.text.secondary}>
-                {rest}
+                {ghostText.text}
               </Text>,
             );
+          } else {
+            // First ghost char: inverted (as cursor). Rest: dimmed gray.
+            const firstChar = ghostText.text[0]!;
+            const rest = ghostText.text.slice(firstChar.length);
+            renderedLine.push(
+              <Text key="ghost-cursor">{chalk.inverse(firstChar)}</Text>,
+            );
+            if (rest.length > 0) {
+              renderedLine.push(
+                <Text key="ghost-rest" color={theme.text.secondary}>
+                  {rest}
+                </Text>,
+              );
+            }
           }
           renderedLine.push(<Text key="ghost-zwsp">{`\u200B`}</Text>);
         } else {
diff --git a/packages/cli/src/ui/components/MainContent.tsx b/packages/cli/src/ui/components/MainContent.tsx
index 89c799097..172419ee9 100644
--- a/packages/cli/src/ui/components/MainContent.tsx
+++ b/packages/cli/src/ui/components/MainContent.tsx
@@ -5,7 +5,8 @@
  */
 
 import { Box, Static } from 'ink';
-import { useEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type { HistoryItem, HistoryItemWithoutId } from '../types.js';
 import { HistoryItemDisplay } from './HistoryItemDisplay.js';
 import { ShowMoreLines } from './ShowMoreLines.js';
 import { Notifications } from './Notifications.js';
@@ -16,7 +17,10 @@ import { useAppContext } from '../contexts/AppContext.js';
 import { AppHeader } from './AppHeader.js';
 import { DebugModeNotification } from './DebugModeNotification.js';
 import { useCompactMode } from '../contexts/CompactModeContext.js';
-import { mergeCompactToolGroups } from '../utils/mergeCompactToolGroups.js';
+import {
+  isForceExpandGroup,
+  mergeCompactToolGroups,
+} from '../utils/mergeCompactToolGroups.js';
 
 // Limit Gemini messages to a very high number of lines to mitigate performance
 // issues in the worst case if we somehow get an enormous response from Gemini.
@@ -37,7 +41,47 @@ export const MainContent = () => {
     availableTerminalHeight,
   } = uiState;
 
-  // Merge consecutive tool_groups for compact mode display
+  // Set of callIds whose label is absorbed by a compact-mode tool_group header.
+  // Computed from RAW history (not merged) — force-expand status depends only
+  // on the tool_group's own state, and mergeable groups don't change force-
+  // expand status when merged. Iterating raw history avoids a circular
+  // dependency with mergedHistory (which receives absorbedCallIds).
+  //
+  // In compact mode, non-force-expanded tool_groups render via
+  // CompactToolGroupDisplay and consume the label as their header replacement.
+  // Force-expanded groups (errors, confirmations, user-initiated, focused
+  // shell) render through the full ToolGroupMessage path and ignore
+  // compactLabel — their callIds are intentionally NOT in this set so the
+  // standalone `● <label>` line in HistoryItemDisplay is the label's only
+  // path to the screen.
+  const absorbedCallIds = useMemo(() => {
+    const absorbed = new Set<string>();
+    if (!compactMode) return absorbed;
+    for (const item of uiState.history) {
+      if (item.type !== 'tool_group') continue;
+      if (
+        isForceExpandGroup(
+          item,
+          uiState.embeddedShellFocused ?? false,
+          uiState.activePtyId,
+        )
+      ) {
+        continue;
+      }
+      for (const tool of item.tools) absorbed.add(tool.callId);
+    }
+    return absorbed;
+  }, [
+    compactMode,
+    uiState.history,
+    uiState.embeddedShellFocused,
+    uiState.activePtyId,
+  ]);
+
+  // Merge consecutive tool_groups for compact mode display. Summaries for
+  // absorbed call IDs are dropped during merge so refreshStatic fires;
+  // summaries for force-expanded (non-absorbed) groups pass through so
+  // HistoryItemDisplay can render them as standalone `● <label>` lines.
   const mergedHistory = useMemo(
     () =>
       compactMode
@@ -45,6 +89,7 @@ export const MainContent = () => {
             uiState.history,
             uiState.embeddedShellFocused,
             uiState.activePtyId,
+            absorbedCallIds,
           )
         : uiState.history,
     [
@@ -52,9 +97,56 @@ export const MainContent = () => {
       uiState.history,
       uiState.embeddedShellFocused,
       uiState.activePtyId,
+      absorbedCallIds,
     ],
   );
 
+  // Build a callId → summary lookup from `tool_use_summary` history items so
+  // compact-mode tool groups can render a semantic label instead of a generic
+  // "Tool × N" line. A summary is indexed under every callId it covers; when
+  // multiple groups are merged, the first group's summary wins (see below).
+  const summaryByCallId = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const item of uiState.history) {
+      if (item.type === 'tool_use_summary') {
+        for (const callId of item.precedingToolUseIds) {
+          // First summary wins — earlier summaries represent the opening
+          // intent of a batch streak, later ones would override it otherwise.
+          if (!map.has(callId)) {
+            map.set(callId, item.summary);
+          }
+        }
+      }
+    }
+    return map;
+  }, [uiState.history]);
+
+  const isSummaryAbsorbed = useCallback(
+    (item: HistoryItem | HistoryItemWithoutId): boolean => {
+      if (item.type !== 'tool_use_summary') return false;
+      return item.precedingToolUseIds.some((id) => absorbedCallIds.has(id));
+    },
+    [absorbedCallIds],
+  );
+
+  const getCompactLabel = useCallback(
+    (item: HistoryItem | HistoryItemWithoutId): string | undefined => {
+      if (item.type !== 'tool_group' || item.tools.length === 0)
+        return undefined;
+      // Look up ONLY the first tool's callId. A merged group concatenates
+      // batch A (earliest calls) then batch B; earlier iterations scanned
+      // all callIds and returned "first hit", but async resolution order
+      // breaks that — if B's summary resolves first, the header renders
+      // SB; when A later resolves, the next render flips to SA. Anchoring
+      // on item.tools[0].callId gives stable "leading batch governs"
+      // semantics; if A's call failed and only B resolved, the header
+      // stays blank for that group (acceptable — the fallback is the
+      // default "Tool × N" rendering once the lookup misses).
+      return summaryByCallId.get(item.tools[0].callId);
+    },
+    [summaryByCallId],
+  );
+
   // Ink's <Static> is append-only: once an item is rendered to the terminal
   // buffer, it cannot be replaced. In compact mode, when a new tool_group is
   // merged into a previous one, the merged result has FEWER items than the
@@ -102,6 +194,8 @@ export const MainContent = () => {
               item={h}
               isPending={false}
               commands={uiState.slashCommands}
+              compactLabel={getCompactLabel(h)}
+              summaryAbsorbed={isSummaryAbsorbed(h)}
             />
           )),
         ]}
@@ -123,6 +217,8 @@ export const MainContent = () => {
               isFocused={!uiState.isEditorDialogOpen}
               activeShellPtyId={uiState.activePtyId}
               embeddedShellFocused={uiState.embeddedShellFocused}
+              compactLabel={getCompactLabel(item)}
+              summaryAbsorbed={isSummaryAbsorbed(item)}
             />
           ))}
           <ShowMoreLines constrainHeight={uiState.constrainHeight} />
diff --git a/packages/cli/src/ui/components/ManageModelsDialog.test.tsx b/packages/cli/src/ui/components/ManageModelsDialog.test.tsx
new file mode 100644
index 000000000..a39e3c1f8
--- /dev/null
+++ b/packages/cli/src/ui/components/ManageModelsDialog.test.tsx
@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  applyCatalogFilters,
+  buildModelLabel,
+  getNextEnabledTabSource,
+  getNextFocusMode,
+  type FilterMode,
+} from './ManageModelsDialog.js';
+import type { ManageModelsCatalogEntry } from '../manageModels/manageModels.js';
+
+function makeEntry(
+  id: string,
+  options: {
+    badges?: string[];
+    supportsVision?: boolean;
+    contextWindowSize?: number;
+  } = {},
+): ManageModelsCatalogEntry {
+  return {
+    id,
+    label: id,
+    searchText: `${id} ${(options.badges || []).join(' ')}`,
+    supportsVision: options.supportsVision ?? false,
+    contextWindowSize: options.contextWindowSize,
+    badges: options.badges || [],
+    model: {
+      id,
+      name: id,
+      baseUrl: 'https://openrouter.ai/api/v1',
+    },
+  };
+}
+
+describe('ManageModelsDialog helpers', () => {
+  it('buildModelLabel uses the short display label only', () => {
+    expect(
+      buildModelLabel(
+        makeEntry('qwen/qwen3-coder:free', {
+          badges: ['free', 'vision'],
+          contextWindowSize: 1_000_000,
+        }),
+      ),
+    ).toBe('qwen/qwen3-coder:free');
+  });
+
+  it.each<[FilterMode, string[]]>([
+    ['all', ['qwen/qwen3-coder:free', 'openai/gpt-4o-mini']],
+    ['enabled', ['openai/gpt-4o-mini']],
+    ['free', ['qwen/qwen3-coder:free']],
+    ['vision', ['qwen/qwen3-coder:free']],
+  ])('applyCatalogFilters supports %s filter', (filterMode, expectedIds) => {
+    const entries = [
+      makeEntry('qwen/qwen3-coder:free', {
+        badges: ['free', 'vision'],
+        supportsVision: true,
+      }),
+      makeEntry('openai/gpt-4o-mini'),
+    ];
+
+    expect(
+      applyCatalogFilters({
+        entries,
+        query: '',
+        selectedIds: ['openai/gpt-4o-mini'],
+        filterMode,
+      }).map((entry) => entry.id),
+    ).toEqual(expectedIds);
+  });
+
+  it('applyCatalogFilters combines query and filter mode', () => {
+    const entries = [
+      makeEntry('qwen/qwen3-coder:free', {
+        badges: ['free'],
+      }),
+      makeEntry('glm/glm-4.5-air:free', {
+        badges: ['free'],
+      }),
+    ];
+
+    expect(
+      applyCatalogFilters({
+        entries,
+        query: 'qwen',
+        selectedIds: [],
+        filterMode: 'free',
+      }).map((entry) => entry.id),
+    ).toEqual(['qwen/qwen3-coder:free']);
+  });
+
+  it('applyCatalogFilters supports enabled quick filter in search', () => {
+    const entries = [
+      makeEntry('qwen/qwen3-coder:free'),
+      makeEntry('openai/gpt-4o-mini'),
+    ];
+
+    expect(
+      applyCatalogFilters({
+        entries,
+        query: 'enabled',
+        selectedIds: ['openai/gpt-4o-mini'],
+        filterMode: 'all',
+      }).map((entry) => entry.id),
+    ).toEqual(['openai/gpt-4o-mini']);
+
+    expect(
+      applyCatalogFilters({
+        entries,
+        query: 'is:enabled gpt',
+        selectedIds: ['openai/gpt-4o-mini'],
+        filterMode: 'all',
+      }).map((entry) => entry.id),
+    ).toEqual(['openai/gpt-4o-mini']);
+  });
+
+  it('cycles focus across tabs, search, and list', () => {
+    expect(getNextFocusMode('tabs', 'forward', true)).toBe('search');
+    expect(getNextFocusMode('search', 'forward', true)).toBe('list');
+    expect(getNextFocusMode('list', 'forward', true)).toBe('tabs');
+    expect(getNextFocusMode('search', 'backward', false)).toBe('tabs');
+  });
+
+  it('keeps provider tab on the only enabled source', () => {
+    expect(getNextEnabledTabSource('openrouter', 'left')).toBe('openrouter');
+    expect(getNextEnabledTabSource('openrouter', 'right')).toBe('openrouter');
+  });
+});
diff --git a/packages/cli/src/ui/components/ManageModelsDialog.tsx b/packages/cli/src/ui/components/ManageModelsDialog.tsx
new file mode 100644
index 000000000..98998d54f
--- /dev/null
+++ b/packages/cli/src/ui/components/ManageModelsDialog.tsx
@@ -0,0 +1,648 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Box, Text } from 'ink';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import process from 'node:process';
+import {
+  type Config,
+  type ProviderModelConfig as ModelConfig,
+} from '@qwen-code/qwen-code-core';
+import { useSettings } from '../contexts/SettingsContext.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+import { theme } from '../semantic-colors.js';
+import { TextInput } from './shared/TextInput.js';
+import type { LoadedSettings } from '../../config/settings.js';
+import {
+  type ManageModelsCatalog,
+  type ManageModelsCatalogEntry,
+  type ManageModelsSource,
+  fetchManageModelsCatalog,
+  getEnabledModelIdsForSource,
+  saveManageModelsSelection,
+} from '../manageModels/manageModels.js';
+
+interface ManageModelsDialogProps {
+  config: Config;
+  onClose: () => void;
+}
+
+type DialogStatus = 'loading' | 'ready' | 'saving' | 'error';
+type FocusMode = 'tabs' | 'search' | 'list';
+export type FilterMode = 'all' | 'enabled' | 'free' | 'vision';
+
+const MAX_VISIBLE_MODELS = 12;
+const MANAGE_MODELS_TABS = [
+  { source: 'openrouter', label: 'OpenRouter', enabled: true },
+  { source: 'modelstudio', label: 'ModelStudio', enabled: false },
+] as const;
+
+type ManageModelsTabSource = (typeof MANAGE_MODELS_TABS)[number]['source'];
+
+export function buildModelLabel(entry: ManageModelsCatalogEntry): string {
+  return entry.label;
+}
+
+export function applyCatalogFilters(params: {
+  entries: ManageModelsCatalogEntry[];
+  query: string;
+  selectedIds: string[];
+  filterMode: FilterMode;
+}): ManageModelsCatalogEntry[] {
+  const { entries, query, selectedIds, filterMode } = params;
+  const normalized = query.trim().toLowerCase();
+  const rawTokens = normalized ? normalized.split(/\s+/).filter(Boolean) : [];
+  const quickFilterEnabled = rawTokens.some(
+    (token) => token === 'enabled' || token === 'is:enabled',
+  );
+  const tokens = rawTokens.filter(
+    (token) => token !== 'enabled' && token !== 'is:enabled',
+  );
+  const selectedSet = new Set(selectedIds);
+
+  return entries.filter((entry) => {
+    if (
+      (filterMode === 'enabled' || quickFilterEnabled) &&
+      !selectedSet.has(entry.id)
+    ) {
+      return false;
+    }
+    if (filterMode === 'free' && !entry.badges.includes('free')) {
+      return false;
+    }
+    if (filterMode === 'vision' && !entry.supportsVision) {
+      return false;
+    }
+
+    if (tokens.length === 0) {
+      return true;
+    }
+
+    const haystack = `${entry.searchText} ${entry.id}`.toLowerCase();
+    return tokens.every((token) => haystack.includes(token));
+  });
+}
+
+function getFilterLabel(filterMode: FilterMode): string {
+  switch (filterMode) {
+    case 'enabled':
+      return 'Enabled';
+    case 'free':
+      return 'Free';
+    case 'vision':
+      return 'Vision';
+    case 'all':
+    default:
+      return 'All';
+  }
+}
+
+function cycleFilter(
+  current: FilterMode,
+  direction: 'left' | 'right',
+): FilterMode {
+  const modes: FilterMode[] = ['all', 'enabled', 'free', 'vision'];
+  const currentIndex = modes.indexOf(current);
+  const nextIndex =
+    direction === 'right'
+      ? (currentIndex + 1) % modes.length
+      : (currentIndex - 1 + modes.length) % modes.length;
+  return modes[nextIndex] || 'all';
+}
+
+function formatContextWindowSize(value?: number): string {
+  return typeof value === 'number' ? value.toLocaleString('en-US') : 'unknown';
+}
+
+export function getNextFocusMode(
+  current: FocusMode,
+  direction: 'forward' | 'backward',
+  hasList: boolean,
+): FocusMode {
+  const order: FocusMode[] = hasList
+    ? ['tabs', 'search', 'list']
+    : ['tabs', 'search'];
+  const currentIndex = order.indexOf(current);
+  const safeIndex = currentIndex >= 0 ? currentIndex : 0;
+  const nextIndex =
+    direction === 'forward'
+      ? (safeIndex + 1) % order.length
+      : (safeIndex - 1 + order.length) % order.length;
+  return order[nextIndex] || 'tabs';
+}
+
+export function getNextEnabledTabSource(
+  current: ManageModelsTabSource,
+  direction: 'left' | 'right',
+): ManageModelsTabSource {
+  const currentIndex = MANAGE_MODELS_TABS.findIndex(
+    (tab) => tab.source === current,
+  );
+  const safeIndex = currentIndex >= 0 ? currentIndex : 0;
+
+  for (let offset = 1; offset <= MANAGE_MODELS_TABS.length; offset += 1) {
+    const candidateIndex =
+      direction === 'right'
+        ? (safeIndex + offset) % MANAGE_MODELS_TABS.length
+        : (safeIndex - offset + MANAGE_MODELS_TABS.length) %
+          MANAGE_MODELS_TABS.length;
+    const candidate = MANAGE_MODELS_TABS[candidateIndex];
+    if (candidate?.enabled) {
+      return candidate.source;
+    }
+  }
+
+  return current;
+}
+
+export function ManageModelsDialog({
+  config,
+  onClose,
+}: ManageModelsDialogProps): React.JSX.Element {
+  const settings = useSettings();
+  const [activeTabSource, setActiveTabSource] =
+    useState<ManageModelsTabSource>('openrouter');
+  const source: ManageModelsSource = 'openrouter';
+
+  const [status, setStatus] = useState<DialogStatus>('loading');
+  const [error, setError] = useState<string | null>(null);
+  const [catalog, setCatalog] = useState<ManageModelsCatalog | null>(null);
+  const [query, setQuery] = useState('');
+  const [focusMode, setFocusMode] = useState<FocusMode>('tabs');
+  const [filterMode, setFilterMode] = useState<FilterMode>('all');
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
+  const [highlightedId, setHighlightedId] = useState<string | null>(null);
+  const [statusMessage, setStatusMessage] = useState<string | null>(null);
+
+  const loadCatalog = useCallback(async () => {
+    setStatus('loading');
+    setError(null);
+    setStatusMessage(null);
+
+    try {
+      const nextCatalog = await fetchManageModelsCatalog(source);
+      const enabledIds = getEnabledModelIdsForSource(source, settings);
+      setCatalog(nextCatalog);
+      setSelectedIds(enabledIds);
+      setHighlightedId(nextCatalog.entries[0]?.id || null);
+      setStatus('ready');
+    } catch (loadError) {
+      setError(
+        loadError instanceof Error ? loadError.message : String(loadError),
+      );
+      setStatus('error');
+    }
+  }, [settings, source]);
+
+  useEffect(() => {
+    void loadCatalog();
+  }, [loadCatalog]);
+
+  const filteredEntries = useMemo(
+    () =>
+      applyCatalogFilters({
+        entries: catalog?.entries || [],
+        query,
+        selectedIds,
+        filterMode,
+      }),
+    [catalog?.entries, query, selectedIds, filterMode],
+  );
+
+  useEffect(() => {
+    if (filteredEntries.length === 0) {
+      setHighlightedId(null);
+      if (focusMode === 'list') {
+        setFocusMode('search');
+      }
+      return;
+    }
+
+    if (
+      highlightedId &&
+      filteredEntries.some((entry) => entry.id === highlightedId)
+    ) {
+      return;
+    }
+
+    setHighlightedId(filteredEntries[0]?.id || null);
+  }, [filteredEntries, focusMode, highlightedId]);
+
+  const highlightedIndex = useMemo(() => {
+    if (!highlightedId) {
+      return 0;
+    }
+    const index = filteredEntries.findIndex(
+      (entry) => entry.id === highlightedId,
+    );
+    return index >= 0 ? index : 0;
+  }, [filteredEntries, highlightedId]);
+
+  const highlightedEntry = useMemo(() => {
+    if (!highlightedId) {
+      return null;
+    }
+    return catalog?.entries.find((entry) => entry.id === highlightedId) || null;
+  }, [catalog?.entries, highlightedId]);
+
+  const visibleWindow = useMemo(() => {
+    if (filteredEntries.length <= MAX_VISIBLE_MODELS) {
+      return {
+        start: 0,
+        entries: filteredEntries,
+      };
+    }
+
+    const centeredStart = Math.max(
+      0,
+      Math.min(
+        highlightedIndex - Math.floor(MAX_VISIBLE_MODELS / 2),
+        filteredEntries.length - MAX_VISIBLE_MODELS,
+      ),
+    );
+
+    return {
+      start: centeredStart,
+      entries: filteredEntries.slice(
+        centeredStart,
+        centeredStart + MAX_VISIBLE_MODELS,
+      ),
+    };
+  }, [filteredEntries, highlightedIndex]);
+
+  const moveHighlight = useCallback(
+    (direction: 'up' | 'down') => {
+      if (filteredEntries.length === 0) {
+        return;
+      }
+
+      if (direction === 'up') {
+        if (highlightedIndex <= 0) {
+          setFocusMode('search');
+          return;
+        }
+        setHighlightedId(filteredEntries[highlightedIndex - 1]?.id || null);
+        return;
+      }
+
+      const nextIndex = Math.min(
+        highlightedIndex + 1,
+        filteredEntries.length - 1,
+      );
+      setHighlightedId(filteredEntries[nextIndex]?.id || null);
+    },
+    [filteredEntries, highlightedIndex],
+  );
+
+  const toggleHighlightedSelection = useCallback(() => {
+    const currentEntry = filteredEntries[highlightedIndex];
+    if (!currentEntry) {
+      return;
+    }
+
+    setSelectedIds((current) => {
+      const next = new Set(current);
+      if (next.has(currentEntry.id)) {
+        next.delete(currentEntry.id);
+      } else {
+        next.add(currentEntry.id);
+      }
+      return Array.from(next);
+    });
+  }, [filteredEntries, highlightedIndex]);
+
+  const handleSave = useCallback(async () => {
+    if (!catalog) {
+      return;
+    }
+
+    const selectedEntries = catalog.entries.filter((entry) =>
+      selectedIds.includes(entry.id),
+    );
+
+    if (selectedEntries.length === 0) {
+      setError('Select at least one model to keep enabled.');
+      return;
+    }
+
+    setStatus('saving');
+    setError(null);
+    setStatusMessage(null);
+
+    try {
+      const selectedModels: ModelConfig[] = selectedEntries.map(
+        (entry) => entry.model,
+      );
+      const result = await saveManageModelsSelection({
+        source,
+        selectedModels,
+        settings: settings as LoadedSettings,
+        config,
+      });
+      setSelectedIds(result.selectedIds);
+      setStatus('ready');
+      setStatusMessage(
+        result.activeModelId
+          ? `Saved ${result.selectedIds.length} enabled models · active model: ${result.activeModelId} · use /model to switch models`
+          : `Saved ${result.selectedIds.length} enabled models · use /model to switch models`,
+      );
+    } catch (saveError) {
+      setError(
+        saveError instanceof Error ? saveError.message : String(saveError),
+      );
+      setStatus('error');
+    }
+  }, [catalog, config, selectedIds, settings, source]);
+
+  useKeypress(
+    (key) => {
+      if (key.name === 'escape') {
+        onClose();
+        return;
+      }
+
+      if (key.ctrl && key.name === 'r' && status !== 'saving') {
+        void loadCatalog();
+        return;
+      }
+
+      if (status === 'saving') {
+        return;
+      }
+
+      if (key.name === 'tab') {
+        setFocusMode((current) =>
+          getNextFocusMode(
+            current,
+            key.shift ? 'backward' : 'forward',
+            filteredEntries.length > 0,
+          ),
+        );
+        return;
+      }
+
+      if (focusMode === 'tabs') {
+        if (key.name === 'left') {
+          setActiveTabSource((current) =>
+            getNextEnabledTabSource(current, 'left'),
+          );
+          return;
+        }
+        if (key.name === 'right') {
+          setActiveTabSource((current) =>
+            getNextEnabledTabSource(current, 'right'),
+          );
+          return;
+        }
+        if (key.name === 'down') {
+          setFocusMode('search');
+        }
+        return;
+      }
+
+      if (focusMode === 'search') {
+        if (key.name === 'left') {
+          setFilterMode((current) => cycleFilter(current, 'left'));
+          return;
+        }
+        if (key.name === 'right') {
+          setFilterMode((current) => cycleFilter(current, 'right'));
+          return;
+        }
+        if (key.name === 'up') {
+          setFocusMode('tabs');
+          return;
+        }
+        if (key.name === 'down' && filteredEntries.length > 0) {
+          setFocusMode('list');
+        }
+        return;
+      }
+
+      if (focusMode === 'list') {
+        if (key.name === 'up') {
+          moveHighlight('up');
+          return;
+        }
+        if (key.name === 'down') {
+          moveHighlight('down');
+          return;
+        }
+        if (key.name === 'space' || key.sequence === ' ') {
+          toggleHighlightedSelection();
+          return;
+        }
+        if (key.name === 'return') {
+          void handleSave();
+        }
+      }
+    },
+    { isActive: true },
+  );
+
+  const terminalWidth = process.stdout.columns || 120;
+  const searchInputWidth = Math.max(40, Math.min(100, terminalWidth - 16));
+
+  const enabledSet = useMemo(() => new Set(selectedIds), [selectedIds]);
+  const hiddenAboveCount = visibleWindow.start;
+  const hiddenBelowCount = Math.max(
+    0,
+    filteredEntries.length -
+      (visibleWindow.start + visibleWindow.entries.length),
+  );
+
+  return (
+    <Box flexDirection="column" width="100%">
+      <Box width="100%">
+        <Text color={theme.border.default} wrap="truncate">
+          {'─'.repeat(200)}
+        </Text>
+      </Box>
+      <Box flexDirection="column">
+        <Box>
+          <Text color={theme.text.accent} bold>
+            Manage Models:{' '}
+          </Text>
+          {MANAGE_MODELS_TABS.map((tab) => {
+            const isActive = activeTabSource === tab.source;
+            const isFocused = focusMode === 'tabs' && isActive;
+
+            return (
+              <Box key={tab.source} marginRight={2}>
+                {isActive ? (
+                  <Text
+                    bold
+                    backgroundColor={
+                      isFocused ? theme.text.accent : theme.border.default
+                    }
+                    color={theme.background.primary}
+                  >
+                    {` ${tab.label} `}
+                  </Text>
+                ) : (
+                  <Text color={theme.text.secondary}>
+                    {` ${tab.label}${tab.enabled ? '' : ' (soon)'} `}
+                  </Text>
+                )}
+              </Box>
+            );
+          })}
+        </Box>
+      </Box>
+
+      {(status === 'loading' || status === 'saving') && (
+        <Box marginTop={1}>
+          <Text color={theme.text.secondary}>
+            {status === 'loading'
+              ? 'Loading OpenRouter catalog…'
+              : 'Saving enabled models…'}
+          </Text>
+        </Box>
+      )}
+
+      {error && (
+        <Box marginTop={1}>
+          <Text color={theme.status.error}>{error}</Text>
+        </Box>
+      )}
+
+      {statusMessage && (
+        <Box marginTop={1}>
+          <Text color={theme.status.success}>{statusMessage}</Text>
+        </Box>
+      )}
+
+      <Box
+        borderStyle="round"
+        borderColor={
+          focusMode === 'search' ? theme.text.accent : theme.border.default
+        }
+        paddingLeft={1}
+        paddingRight={1}
+      >
+        <TextInput
+          value={query}
+          onChange={setQuery}
+          onTab={() => {
+            if (filteredEntries.length > 0) {
+              setFocusMode('list');
+            }
+          }}
+          onDown={() => {
+            if (filteredEntries.length > 0) {
+              setFocusMode('list');
+            }
+          }}
+          placeholder="Search models… (type enabled to filter)"
+          height={1}
+          isActive={status !== 'saving' && focusMode === 'search'}
+          inputWidth={searchInputWidth}
+        />
+      </Box>
+
+      <Box flexDirection="row" gap={2}>
+        <Box
+          borderStyle="round"
+          borderColor={theme.border.default}
+          flexDirection="column"
+          paddingX={1}
+          paddingY={0}
+          width="56%"
+        >
+          <Text color={theme.text.secondary}>
+            {getFilterLabel(filterMode)} · {catalog?.entries.length || 0} total
+            · {filteredEntries.length} shown · {selectedIds.length} enabled
+          </Text>
+
+          {filteredEntries.length === 0 ? (
+            <Text color={theme.text.secondary}>
+              No models match the current search and filter.
+            </Text>
+          ) : (
+            <Box flexDirection="column">
+              {hiddenAboveCount > 0 && (
+                <Text color={theme.text.secondary}>
+                  ↑ {hiddenAboveCount} more above
+                </Text>
+              )}
+
+              {visibleWindow.entries.map((entry, index) => {
+                const absoluteIndex = visibleWindow.start + index;
+                const isActive =
+                  focusMode === 'list' && absoluteIndex === highlightedIndex;
+                const isEnabled = enabledSet.has(entry.id);
+                const prefix = isActive ? '›' : ' ';
+                const checkbox = isEnabled ? '[✓]' : '[ ]';
+                const rowColor = isActive
+                  ? theme.status.success
+                  : isEnabled
+                    ? theme.text.accent
+                    : theme.text.primary;
+
+                return (
+                  <Text key={entry.id} color={rowColor} wrap="truncate-end">
+                    {prefix} {checkbox} {buildModelLabel(entry)}
+                  </Text>
+                );
+              })}
+
+              {hiddenBelowCount > 0 && (
+                <Text color={theme.text.secondary}>
+                  ↓ {hiddenBelowCount} more below
+                </Text>
+              )}
+            </Box>
+          )}
+        </Box>
+
+        <Box
+          borderStyle="round"
+          borderColor={theme.border.default}
+          flexDirection="column"
+          paddingX={1}
+          paddingY={0}
+          width="44%"
+        >
+          <Text bold>Details</Text>
+          {highlightedEntry ? (
+            <Box flexDirection="column">
+              <Text>{highlightedEntry.label}</Text>
+              <Text color={theme.text.secondary}>
+                Model ID: {highlightedEntry.id}
+              </Text>
+              <Text color={theme.text.secondary}>
+                Enabled: {enabledSet.has(highlightedEntry.id) ? 'yes' : 'no'}
+              </Text>
+              <Text color={theme.text.secondary}>
+                Vision: {highlightedEntry.supportsVision ? 'yes' : 'no'}
+              </Text>
+              <Text color={theme.text.secondary}>
+                Context:{' '}
+                {formatContextWindowSize(highlightedEntry.contextWindowSize)}
+              </Text>
+              <Text color={theme.text.secondary}>
+                Tags:{' '}
+                {highlightedEntry.badges.length > 0
+                  ? highlightedEntry.badges.join(', ')
+                  : 'none'}
+              </Text>
+            </Box>
+          ) : (
+            <Text color={theme.text.secondary}>
+              Move to the model list to inspect a model.
+            </Text>
+          )}
+        </Box>
+      </Box>
+
+      <Box>
+        <Text color={theme.text.secondary}>
+          ←/→ tab switch · ↓ enter list · Space toggle · Enter save · Esc cancel
+        </Text>
+      </Box>
+    </Box>
+  );
+}
diff --git a/packages/cli/src/ui/components/RewindSelector.tsx b/packages/cli/src/ui/components/RewindSelector.tsx
new file mode 100644
index 000000000..5da006cad
--- /dev/null
+++ b/packages/cli/src/ui/components/RewindSelector.tsx
@@ -0,0 +1,328 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useMemo, useCallback } from 'react';
+import { Box, Text } from 'ink';
+import type { HistoryItem } from '../types.js';
+import { theme } from '../semantic-colors.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+import { truncateText } from '../utils/sessionPickerUtils.js';
+import { isRealUserTurn } from '../utils/historyMapping.js';
+import { t } from '../../i18n/index.js';
+
+export interface RewindSelectorProps {
+  history: HistoryItem[];
+  onRewind: (userItem: HistoryItem) => void;
+  onCancel: () => void;
+}
+
+const MAX_VISIBLE_ITEMS = 7;
+
+/**
+ * Extract user-type items from UI history for the rewind pick list.
+ */
+function getUserTurns(history: HistoryItem[]): HistoryItem[] {
+  return history.filter(isRealUserTurn);
+}
+
+interface TurnItemViewProps {
+  item: HistoryItem;
+  isSelected: boolean;
+  isFirst: boolean;
+  isLast: boolean;
+  showScrollUp: boolean;
+  showScrollDown: boolean;
+  maxPromptWidth: number;
+  turnNumber: number;
+}
+
+function TurnItemView({
+  item,
+  isSelected,
+  isFirst,
+  isLast,
+  showScrollUp,
+  showScrollDown,
+  maxPromptWidth,
+  turnNumber,
+}: TurnItemViewProps): React.JSX.Element {
+  const showUpIndicator = isFirst && showScrollUp;
+  const showDownIndicator = isLast && showScrollDown;
+
+  const prefix = isSelected
+    ? '› '
+    : showUpIndicator
+      ? '↑ '
+      : showDownIndicator
+        ? '↓ '
+        : '  ';
+
+  const promptText = item.text || '(empty prompt)';
+  const truncatedPrompt = truncateText(promptText, maxPromptWidth);
+
+  return (
+    <Box flexDirection="column" marginBottom={isLast ? 0 : 1}>
+      <Box>
+        <Text
+          color={
+            isSelected
+              ? theme.text.accent
+              : showUpIndicator || showDownIndicator
+                ? theme.text.secondary
+                : undefined
+          }
+          bold={isSelected}
+        >
+          {prefix}
+        </Text>
+        <Text color={theme.text.secondary}>{`#${turnNumber} `}</Text>
+        <Text
+          color={isSelected ? theme.text.accent : theme.text.primary}
+          bold={isSelected}
+        >
+          {truncatedPrompt}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * Two-phase rewind selector:
+ * 1. Pick list — choose which user turn to rewind to
+ * 2. Confirm — confirm the rewind action
+ */
+export function RewindSelector({
+  history,
+  onRewind,
+  onCancel,
+}: RewindSelectorProps) {
+  const { columns: width, rows: height } = useTerminalSize();
+  const userTurns = useMemo(() => getUserTurns(history), [history]);
+
+  const [selectedIndex, setSelectedIndex] = useState(userTurns.length - 1);
+  const [confirmItem, setConfirmItem] = useState<HistoryItem | null>(null);
+
+  const boxWidth = width - 4;
+  const maxVisibleItems = Math.min(MAX_VISIBLE_ITEMS, userTurns.length);
+
+  // Centered scroll offset
+  const scrollOffset = useMemo(() => {
+    if (userTurns.length <= maxVisibleItems) return 0;
+    const halfVisible = Math.floor(maxVisibleItems / 2);
+    let offset = selectedIndex - halfVisible;
+    offset = Math.max(0, offset);
+    offset = Math.min(userTurns.length - maxVisibleItems, offset);
+    return offset;
+  }, [userTurns.length, maxVisibleItems, selectedIndex]);
+
+  const visibleTurns = useMemo(
+    () => userTurns.slice(scrollOffset, scrollOffset + maxVisibleItems),
+    [userTurns, scrollOffset, maxVisibleItems],
+  );
+  const showScrollUp = scrollOffset > 0;
+  const showScrollDown = scrollOffset + maxVisibleItems < userTurns.length;
+
+  const handleConfirmSelect = useCallback(
+    (confirmed: boolean) => {
+      if (confirmed && confirmItem) {
+        onRewind(confirmItem);
+      } else {
+        setConfirmItem(null);
+      }
+    },
+    [confirmItem, onRewind],
+  );
+
+  // Pick-list key handler
+  useKeypress(
+    (key) => {
+      const { name, ctrl } = key;
+
+      if (name === 'escape' || (ctrl && name === 'c')) {
+        onCancel();
+        return;
+      }
+
+      if (name === 'return') {
+        const selected = userTurns[selectedIndex];
+        if (selected) {
+          setConfirmItem(selected);
+        }
+        return;
+      }
+
+      if (name === 'up' || name === 'k') {
+        setSelectedIndex((prev) => Math.max(0, prev - 1));
+        return;
+      }
+
+      if (name === 'down' || name === 'j') {
+        setSelectedIndex((prev) => Math.min(userTurns.length - 1, prev + 1));
+        return;
+      }
+    },
+    { isActive: confirmItem === null },
+  );
+
+  // Confirm key handler
+  useKeypress(
+    (key) => {
+      const { name, ctrl, sequence } = key;
+
+      if (name === 'escape' || (ctrl && name === 'c')) {
+        setConfirmItem(null);
+        return;
+      }
+
+      if (name === 'return' || sequence === 'y' || sequence === 'Y') {
+        handleConfirmSelect(true);
+        return;
+      }
+
+      if (sequence === 'n' || sequence === 'N') {
+        handleConfirmSelect(false);
+        return;
+      }
+    },
+    { isActive: confirmItem !== null },
+  );
+
+  if (userTurns.length === 0) {
+    return (
+      <Box flexDirection="column" width={boxWidth}>
+        <Box
+          flexDirection="column"
+          borderStyle="round"
+          borderColor={theme.border.default}
+          width={boxWidth}
+        >
+          <Box paddingX={1}>
+            <Text color={theme.text.secondary}>
+              {t('No user turns to rewind to.')}
+            </Text>
+          </Box>
+        </Box>
+      </Box>
+    );
+  }
+
+  // Confirm phase
+  if (confirmItem) {
+    const promptPreview = truncateText(
+      confirmItem.text || '(empty)',
+      boxWidth - 10,
+    );
+    return (
+      <Box flexDirection="column" width={boxWidth}>
+        <Box
+          flexDirection="column"
+          borderStyle="round"
+          borderColor={theme.border.default}
+          width={boxWidth}
+        >
+          <Box paddingX={1}>
+            <Text bold color={theme.text.primary}>
+              {t('Rewind Conversation')}
+            </Text>
+          </Box>
+          <Box>
+            <Text color={theme.border.default}>{'─'.repeat(boxWidth - 2)}</Text>
+          </Box>
+          <Box paddingX={1} flexDirection="column">
+            <Box marginBottom={1}>
+              <Text color={theme.text.primary}>{t('Rewind to: ')}</Text>
+              <Text color={theme.text.accent} bold>
+                {promptPreview}
+              </Text>
+            </Box>
+            <Text color={theme.status.warning}>
+              {t(
+                'This will remove all conversation after this turn. The prompt will be pre-populated in the input for editing.',
+              )}
+            </Text>
+          </Box>
+          <Box>
+            <Text color={theme.border.default}>{'─'.repeat(boxWidth - 2)}</Text>
+          </Box>
+          <Box paddingX={1}>
+            <Text color={theme.text.secondary}>
+              {t('Enter/Y to confirm · Esc/N to go back')}
+            </Text>
+          </Box>
+        </Box>
+      </Box>
+    );
+  }
+
+  // Pick-list phase
+  return (
+    <Box
+      flexDirection="column"
+      width={boxWidth}
+      height={height - 1}
+      overflow="hidden"
+    >
+      <Box
+        flexDirection="column"
+        borderStyle="round"
+        borderColor={theme.border.default}
+        width={boxWidth}
+        height={height - 1}
+        overflow="hidden"
+      >
+        {/* Header */}
+        <Box paddingX={1}>
+          <Text bold color={theme.text.primary}>
+            {t('Rewind Conversation')}
+          </Text>
+          <Text color={theme.text.secondary}>
+            {' '}
+            {t('({{count}} turns)', { count: String(userTurns.length) })}
+          </Text>
+        </Box>
+
+        {/* Separator */}
+        <Box>
+          <Text color={theme.border.default}>{'─'.repeat(boxWidth - 2)}</Text>
+        </Box>
+
+        {/* Turn list */}
+        <Box flexDirection="column" flexGrow={1} paddingX={1} overflow="hidden">
+          {visibleTurns.map((item, visibleIndex) => {
+            const actualIndex = scrollOffset + visibleIndex;
+            return (
+              <TurnItemView
+                key={item.id}
+                item={item}
+                isSelected={actualIndex === selectedIndex}
+                isFirst={visibleIndex === 0}
+                isLast={visibleIndex === visibleTurns.length - 1}
+                showScrollUp={showScrollUp}
+                showScrollDown={showScrollDown}
+                maxPromptWidth={boxWidth - 10}
+                turnNumber={actualIndex + 1}
+              />
+            );
+          })}
+        </Box>
+
+        {/* Separator */}
+        <Box>
+          <Text color={theme.border.default}>{'─'.repeat(boxWidth - 2)}</Text>
+        </Box>
+
+        {/* Footer */}
+        <Box paddingX={1}>
+          <Text color={theme.text.secondary}>
+            {t('↑↓ to navigate · Enter to select · Esc to cancel')}
+          </Text>
+        </Box>
+      </Box>
+    </Box>
+  );
+}
diff --git a/packages/cli/src/ui/components/SessionPicker.tsx b/packages/cli/src/ui/components/SessionPicker.tsx
index c80c35be1..8bcf3f5b9 100644
--- a/packages/cli/src/ui/components/SessionPicker.tsx
+++ b/packages/cli/src/ui/components/SessionPicker.tsx
@@ -18,6 +18,7 @@ import {
 } from '../utils/sessionPickerUtils.js';
 import { useTerminalSize } from '../hooks/useTerminalSize.js';
 import { t } from '../../i18n/index.js';
+import { SessionPreview } from './SessionPreview.js';
 
 export interface SessionPickerProps {
   sessionService: SessionService | null;
@@ -41,6 +42,14 @@ export interface SessionPickerProps {
    * When provided, skips initial load and disables pagination.
    */
   initialSessions?: SessionData[];
+
+  /**
+   * Enable Space-to-preview. Off by default — preview's Enter shortcut
+   * forwards to `onSelect`, which for resume flows is "resume", but for
+   * destructive flows (e.g. delete) would commit the action. Only opt in
+   * for non-destructive selection flows.
+   */
+  enablePreview?: boolean;
 }
 
 const PREFIX_CHARS = {
@@ -147,6 +156,7 @@ export function SessionPicker(props: SessionPickerProps) {
     title,
     centerSelection = true,
     initialSessions,
+    enablePreview = false,
   } = props;
 
   const { columns: width, rows: height } = useTerminalSize();
@@ -172,8 +182,32 @@ export function SessionPicker(props: SessionPickerProps) {
     centerSelection,
     initialSessions,
     isActive: true,
+    enablePreview,
   });
 
+  if (
+    enablePreview &&
+    picker.viewMode === 'preview' &&
+    picker.previewSessionId &&
+    sessionService
+  ) {
+    const previewed = picker.filteredSessions.find(
+      (s) => s.sessionId === picker.previewSessionId,
+    );
+    return (
+      <SessionPreview
+        sessionService={sessionService}
+        sessionId={picker.previewSessionId}
+        sessionTitle={previewed?.customTitle ?? previewed?.prompt ?? undefined}
+        messageCount={previewed?.messageCount}
+        mtime={previewed?.mtime}
+        gitBranch={previewed?.gitBranch}
+        onExit={picker.exitPreview}
+        onResume={onSelect}
+      />
+    );
+  }
+
   return (
     <Box
       flexDirection="column"
@@ -262,7 +296,12 @@ export function SessionPicker(props: SessionPickerProps) {
                 >
                   B
                 </Text>
-                {t(' to toggle branch')} ·
+                {t(' to toggle branch · ')}
+              </Text>
+            )}
+            {enablePreview && (
+              <Text color={theme.text.secondary}>
+                {t('Space to preview · ')}
               </Text>
             )}
             <Text color={theme.text.secondary}>
diff --git a/packages/cli/src/ui/components/SessionPreview.test.tsx b/packages/cli/src/ui/components/SessionPreview.test.tsx
new file mode 100644
index 000000000..479eeee54
--- /dev/null
+++ b/packages/cli/src/ui/components/SessionPreview.test.tsx
@@ -0,0 +1,176 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { render } from 'ink-testing-library';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { KeypressProvider } from '../contexts/KeypressContext.js';
+import { SessionPreview } from './SessionPreview.js';
+
+beforeEach(() => {
+  Object.defineProperty(process.stdout, 'columns', {
+    value: 80,
+    configurable: true,
+  });
+  Object.defineProperty(process.stdout, 'rows', {
+    value: 24,
+    configurable: true,
+  });
+});
+
+afterEach(() => vi.clearAllMocks());
+
+const wait = (ms = 50) => new Promise((r) => setTimeout(r, ms));
+
+function mockService(resolved: unknown) {
+  return {
+    loadSession: vi
+      .fn()
+      .mockReturnValue(
+        resolved instanceof Promise ? resolved : Promise.resolve(resolved),
+      ),
+    listSessions: vi.fn(),
+    loadLastSession: vi.fn(),
+  } as never;
+}
+
+function fakeResumedData() {
+  return {
+    conversation: {
+      sessionId: 's1',
+      projectHash: 'h',
+      startTime: '2026-01-01T00:00:00.000Z',
+      lastUpdated: '2026-01-01T00:00:00.000Z',
+      messages: [
+        {
+          uuid: 'u1',
+          parentUuid: null,
+          sessionId: 's1',
+          timestamp: '2026-01-01T00:00:00.000Z',
+          type: 'user',
+          cwd: '/tmp',
+          version: 'test',
+          message: {
+            role: 'user',
+            parts: [{ text: 'Hello world PREVIEW-MARKER' }],
+          },
+        },
+        {
+          uuid: 'u2',
+          parentUuid: 'u1',
+          sessionId: 's1',
+          timestamp: '2026-01-01T00:00:01.000Z',
+          type: 'assistant',
+          cwd: '/tmp',
+          version: 'test',
+          message: {
+            role: 'model',
+            parts: [{ text: 'Hi from assistant REPLY-MARKER' }],
+          },
+        },
+      ],
+    },
+    filePath: '/tmp/s1.jsonl',
+    lastCompletedUuid: 'u2',
+  };
+}
+
+describe('SessionPreview', () => {
+  it('shows loading state before data arrives', () => {
+    const svc = mockService(new Promise(() => {})); // never resolves
+    const { lastFrame } = render(
+      <KeypressProvider kittyProtocolEnabled={false}>
+        <SessionPreview
+          sessionService={svc}
+          sessionId="s1"
+          sessionTitle="My session"
+          onExit={vi.fn()}
+          onResume={vi.fn()}
+        />
+      </KeypressProvider>,
+    );
+    expect(lastFrame()).toContain('Loading session preview');
+  });
+
+  it('renders all messages after load', async () => {
+    const svc = mockService(fakeResumedData());
+    const { lastFrame } = render(
+      <KeypressProvider kittyProtocolEnabled={false}>
+        <SessionPreview
+          sessionService={svc}
+          sessionId="s1"
+          sessionTitle="My session"
+          onExit={vi.fn()}
+          onResume={vi.fn()}
+        />
+      </KeypressProvider>,
+    );
+    await wait(100);
+    const frame = lastFrame() ?? '';
+    expect(frame).toContain('PREVIEW-MARKER');
+    expect(frame).toContain('REPLY-MARKER');
+  });
+
+  it('renders footer metadata (messageCount · time · branch)', async () => {
+    const svc = mockService(fakeResumedData());
+    const { lastFrame } = render(
+      <KeypressProvider kittyProtocolEnabled={false}>
+        <SessionPreview
+          sessionService={svc}
+          sessionId="s1"
+          sessionTitle="My session"
+          messageCount={42}
+          mtime={Date.now() - 60_000}
+          gitBranch="feat/preview"
+          onExit={vi.fn()}
+          onResume={vi.fn()}
+        />
+      </KeypressProvider>,
+    );
+    await wait(100);
+    const frame = lastFrame() ?? '';
+    expect(frame).toMatch(/42\s*messages/);
+    expect(frame).toContain('feat/preview');
+  });
+
+  it('calls onExit when Escape is pressed', async () => {
+    const onExit = vi.fn();
+    const svc = mockService(fakeResumedData());
+    const { stdin } = render(
+      <KeypressProvider kittyProtocolEnabled={false}>
+        <SessionPreview
+          sessionService={svc}
+          sessionId="s1"
+          sessionTitle="My session"
+          onExit={onExit}
+          onResume={vi.fn()}
+        />
+      </KeypressProvider>,
+    );
+    await wait(100);
+    stdin.write('\u001B'); // ESC
+    await wait(50);
+    expect(onExit).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls onResume(sessionId) when Enter is pressed', async () => {
+    const onResume = vi.fn();
+    const svc = mockService(fakeResumedData());
+    const { stdin } = render(
+      <KeypressProvider kittyProtocolEnabled={false}>
+        <SessionPreview
+          sessionService={svc}
+          sessionId="s1"
+          sessionTitle="My session"
+          onExit={vi.fn()}
+          onResume={onResume}
+        />
+      </KeypressProvider>,
+    );
+    await wait(100);
+    stdin.write('\r'); // Enter
+    await wait(50);
+    expect(onResume).toHaveBeenCalledWith('s1');
+  });
+});
diff --git a/packages/cli/src/ui/components/SessionPreview.tsx b/packages/cli/src/ui/components/SessionPreview.tsx
new file mode 100644
index 000000000..c8b9cb4dd
--- /dev/null
+++ b/packages/cli/src/ui/components/SessionPreview.tsx
@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Box, Text } from 'ink';
+import { useEffect, useMemo, useState } from 'react';
+import type {
+  ResumedSessionData,
+  SessionService,
+} from '@qwen-code/qwen-code-core';
+import { theme } from '../semantic-colors.js';
+import { HistoryItemDisplay } from './HistoryItemDisplay.js';
+import { useKeypress } from '../hooks/useKeypress.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { buildResumedHistoryItems } from '../utils/resumeHistoryUtils.js';
+import { formatRelativeTime } from '../utils/formatters.js';
+import { formatMessageCount } from '../utils/sessionPickerUtils.js';
+import { t } from '../../i18n/index.js';
+
+export interface SessionPreviewProps {
+  sessionService: SessionService;
+  sessionId: string;
+  sessionTitle?: string;
+  /** Message count from the session list entry, for the footer. */
+  messageCount?: number;
+  /** Last-modified time (ms epoch) from the session list entry, for the footer. */
+  mtime?: number;
+  /** Git branch from the session list entry, for the footer. */
+  gitBranch?: string;
+  onExit: () => void;
+  onResume: (sessionId: string) => void;
+}
+
+export function SessionPreview(props: SessionPreviewProps) {
+  const {
+    sessionService,
+    sessionId,
+    sessionTitle,
+    messageCount,
+    mtime,
+    gitBranch,
+    onExit,
+    onResume,
+  } = props;
+  const { columns } = useTerminalSize();
+  const [data, setData] = useState<ResumedSessionData | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setData(null);
+    setError(null);
+    sessionService
+      .loadSession(sessionId)
+      .then((d: ResumedSessionData | undefined) => {
+        if (cancelled) return;
+        if (!d) {
+          setError('Session not found');
+          return;
+        }
+        setData(d);
+      })
+      .catch((e: unknown) => {
+        if (cancelled) return;
+        setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [sessionService, sessionId]);
+
+  // Preview passes `null` config: tool_group entries degrade to name-only
+  // (no description). Users can press Enter to resume for full fidelity.
+  const items = useMemo(() => {
+    if (!data) return [];
+    return buildResumedHistoryItems(data, null);
+  }, [data]);
+
+  useKeypress(
+    (key) => {
+      const { name, ctrl } = key;
+      if (name === 'escape' || (ctrl && name === 'c')) {
+        onExit();
+        return;
+      }
+      if (name === 'return') {
+        onResume(sessionId);
+      }
+    },
+    { isActive: true },
+  );
+
+  // Clamp to a safe minimum: `'─'.repeat(boxWidth - 2)` would throw RangeError
+  // in very narrow terminals (tmux splits, small panes) if boxWidth < 2.
+  const boxWidth = Math.max(10, columns - 4);
+  const separatorWidth = Math.max(0, boxWidth - 2);
+
+  const metaParts: string[] = [];
+  if (typeof messageCount === 'number') {
+    metaParts.push(formatMessageCount(messageCount));
+  }
+  if (typeof mtime === 'number') {
+    metaParts.push(formatRelativeTime(mtime));
+  }
+  if (gitBranch) {
+    metaParts.push(gitBranch);
+  }
+  const metaLine = metaParts.join(' · ');
+
+  return (
+    <Box flexDirection="column" width={boxWidth}>
+      {/* Header */}
+      <Box paddingX={1}>
+        <Text bold color={theme.text.primary}>
+          {sessionTitle ?? t('Session Preview')}
+        </Text>
+      </Box>
+      <Box>
+        <Text color={theme.border.default}>{'─'.repeat(separatorWidth)}</Text>
+      </Box>
+
+      {/* Body: render all items, let the terminal's scrollback own overflow. */}
+      {error ? (
+        <Box paddingY={1} justifyContent="center">
+          <Text color={theme.status.error}>{error}</Text>
+        </Box>
+      ) : !data ? (
+        <Box paddingY={1} justifyContent="center">
+          <Text color={theme.text.secondary}>
+            {t('Loading session preview...')}
+          </Text>
+        </Box>
+      ) : (
+        <Box flexDirection="column">
+          {items.map((item) => (
+            <HistoryItemDisplay
+              key={item.id}
+              item={item}
+              terminalWidth={boxWidth}
+              isPending={false}
+            />
+          ))}
+        </Box>
+      )}
+
+      {/* Footer */}
+      <Box>
+        <Text color={theme.border.default}>{'─'.repeat(separatorWidth)}</Text>
+      </Box>
+      {metaLine && (
+        <Box paddingX={1}>
+          <Text color={theme.text.secondary}>{metaLine}</Text>
+        </Box>
+      )}
+      <Box paddingX={1}>
+        <Text color={theme.text.secondary}>
+          {t('Enter to resume · Esc to back')}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
diff --git a/packages/cli/src/ui/components/SettingsDialog.test.tsx b/packages/cli/src/ui/components/SettingsDialog.test.tsx
index c72750737..c1b75f755 100644
--- a/packages/cli/src/ui/components/SettingsDialog.test.tsx
+++ b/packages/cli/src/ui/components/SettingsDialog.test.tsx
@@ -963,11 +963,25 @@ describe('SettingsDialog', () => {
         </KeypressProvider>,
       );
 
-      // Trigger a restart-required setting change: navigate to "Language: UI" (2nd item) and toggle it.
-      stdin.write(TerminalKeys.DOWN_ARROW as string);
-      await wait();
-      stdin.write(TerminalKeys.ENTER as string);
-      await wait();
+      await waitFor(() => {
+        expect(lastFrame()).toContain('Tool Approval Mode');
+      });
+
+      const languageIndex = getDialogSettingKeys().indexOf('general.language');
+      expect(languageIndex).toBeGreaterThanOrEqual(0);
+
+      const press = async (key: string) => {
+        act(() => {
+          stdin.write(key);
+        });
+        await wait();
+      };
+
+      // Trigger a restart-required setting change by toggling the UI language setting.
+      for (let i = 0; i < languageIndex; i++) {
+        await press(TerminalKeys.DOWN_ARROW as string);
+      }
+      await press(TerminalKeys.ENTER as string);
 
       await waitFor(() => {
         expect(lastFrame()).toContain(
@@ -976,10 +990,8 @@ describe('SettingsDialog', () => {
       });
 
       // Switch scopes; restart prompt should remain visible.
-      stdin.write(TerminalKeys.TAB as string);
-      await wait();
-      stdin.write('2');
-      await wait();
+      await press(TerminalKeys.TAB as string);
+      await press('2');
 
       await waitFor(() => {
         expect(lastFrame()).toContain(
diff --git a/packages/cli/src/ui/components/StandaloneSessionPicker.test.tsx b/packages/cli/src/ui/components/StandaloneSessionPicker.test.tsx
index 9a7c7b193..629231eb9 100644
--- a/packages/cli/src/ui/components/StandaloneSessionPicker.test.tsx
+++ b/packages/cli/src/ui/components/StandaloneSessionPicker.test.tsx
@@ -4,11 +4,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { ReactNode } from 'react';
 import { render } from 'ink-testing-library';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { KeypressProvider } from '../contexts/KeypressContext.js';
+import { ConfigContext } from '../contexts/ConfigContext.js';
+import { SettingsContext } from '../contexts/SettingsContext.js';
 import { SessionPicker } from './SessionPicker.js';
+import type { LoadedSettings } from '../../config/settings.js';
 import type {
+  Config,
   SessionListItem,
   ListSessionsResult,
 } from '@qwen-code/qwen-code-core';
@@ -621,4 +626,281 @@ describe('SessionPicker', () => {
       unmount();
     });
   });
+
+  describe('Preview Mode', () => {
+    // Mirror `StandaloneSessionPicker`'s runtime wrapping so the preview
+    // render tree (ToolGroupMessage, ToolMessage) can safely call
+    // `useConfig()` / `useSettings()` in tests. Without these, any test
+    // whose previewed session contains tool calls would crash.
+    const PREVIEW_CONFIG_STUB = {
+      getShouldUseNodePtyShell: () => false,
+      getIdeMode: () => false,
+      isTrustedFolder: () => false,
+      getToolRegistry: () => ({ getTool: () => undefined }),
+      getContentGenerator: () => ({ useSummarizedThinking: () => false }),
+    } as unknown as Config;
+    const PREVIEW_SETTINGS_STUB = {
+      merged: { ui: {} },
+    } as unknown as LoadedSettings;
+
+    function renderPicker(children: ReactNode) {
+      return render(
+        <KeypressProvider kittyProtocolEnabled={false}>
+          <ConfigContext.Provider value={PREVIEW_CONFIG_STUB}>
+            <SettingsContext.Provider value={PREVIEW_SETTINGS_STUB}>
+              {children}
+            </SettingsContext.Provider>
+          </ConfigContext.Provider>
+        </KeypressProvider>,
+      );
+    }
+
+    function fakeResumedData(sessionId: string) {
+      return {
+        conversation: {
+          sessionId,
+          projectHash: 'h',
+          startTime: '2026-01-01T00:00:00.000Z',
+          lastUpdated: '2026-01-01T00:00:00.000Z',
+          messages: [
+            {
+              uuid: 'u1',
+              parentUuid: null,
+              sessionId,
+              timestamp: '2026-01-01T00:00:00.000Z',
+              type: 'user',
+              cwd: '/tmp',
+              version: 'test',
+              message: {
+                role: 'user',
+                parts: [{ text: 'USER-ASKED-THIS' }],
+              },
+            },
+            {
+              uuid: 'u2',
+              parentUuid: 'u1',
+              sessionId,
+              timestamp: '2026-01-01T00:00:01.000Z',
+              type: 'assistant',
+              cwd: '/tmp',
+              version: 'test',
+              message: {
+                role: 'model',
+                parts: [{ text: 'ASSISTANT-REPLIED' }],
+              },
+            },
+          ],
+        },
+        filePath: `/tmp/${sessionId}.jsonl`,
+        lastCompletedUuid: 'u2',
+      };
+    }
+
+    it('opens preview on Space and closes on Esc', async () => {
+      const sessions = [
+        createMockSession({
+          sessionId: 's1',
+          prompt: 'First session',
+          messageCount: 2,
+        }),
+      ];
+      const service = createMockSessionService(sessions);
+      service.loadSession.mockResolvedValue(fakeResumedData('s1'));
+
+      const { stdin, lastFrame } = renderPicker(
+        <SessionPicker
+          sessionService={service as never}
+          onSelect={vi.fn()}
+          onCancel={vi.fn()}
+          enablePreview
+        />,
+      );
+
+      await wait(100);
+      expect(lastFrame()).toContain('First session');
+
+      stdin.write(' '); // Space
+      await wait(150);
+      const previewFrame = lastFrame() ?? '';
+      expect(previewFrame).toContain('USER-ASKED-THIS');
+      expect(previewFrame).toContain('ASSISTANT-REPLIED');
+
+      stdin.write('\u001B'); // Esc
+      await wait(50);
+      const afterExitFrame = lastFrame() ?? '';
+      expect(afterExitFrame).toContain('First session');
+      expect(afterExitFrame).not.toContain('USER-ASKED-THIS');
+    });
+
+    it('renders tool_group items without crashing (stub Providers mounted)', async () => {
+      // The previewed session contains a function call + tool_result, which
+      // produces a `tool_group` HistoryItem that exercises ToolGroupMessage
+      // and ToolMessage — the places that throw without stub Providers.
+      const toolSession = {
+        conversation: {
+          sessionId: 's1',
+          projectHash: 'h',
+          startTime: '2026-01-01T00:00:00.000Z',
+          lastUpdated: '2026-01-01T00:00:00.000Z',
+          messages: [
+            {
+              uuid: 'u1',
+              parentUuid: null,
+              sessionId: 's1',
+              timestamp: '2026-01-01T00:00:00.000Z',
+              type: 'user',
+              cwd: '/tmp',
+              version: 'test',
+              message: { role: 'user', parts: [{ text: 'list files' }] },
+            },
+            {
+              uuid: 'u2',
+              parentUuid: 'u1',
+              sessionId: 's1',
+              timestamp: '2026-01-01T00:00:01.000Z',
+              type: 'assistant',
+              cwd: '/tmp',
+              version: 'test',
+              message: {
+                role: 'model',
+                parts: [
+                  {
+                    functionCall: {
+                      id: 'call-1',
+                      name: 'BashTool',
+                      args: { command: 'ls' },
+                    },
+                  },
+                ],
+              },
+            },
+            {
+              uuid: 'u3',
+              parentUuid: 'u2',
+              sessionId: 's1',
+              timestamp: '2026-01-01T00:00:02.000Z',
+              type: 'tool_result',
+              cwd: '/tmp',
+              version: 'test',
+              toolCallResult: {
+                callId: 'call-1',
+                resultDisplay: 'a.txt\nb.txt',
+                status: 'success',
+              },
+            },
+          ],
+        },
+        filePath: '/tmp/s1.jsonl',
+        lastCompletedUuid: 'u3',
+      };
+
+      const sessions = [
+        createMockSession({
+          sessionId: 's1',
+          prompt: 'list files',
+          messageCount: 3,
+        }),
+      ];
+      const service = createMockSessionService(sessions);
+      service.loadSession.mockResolvedValue(toolSession);
+
+      const { stdin, lastFrame } = renderPicker(
+        <SessionPicker
+          sessionService={service as never}
+          onSelect={vi.fn()}
+          onCancel={vi.fn()}
+          enablePreview
+        />,
+      );
+
+      await wait(100);
+      stdin.write(' '); // Space → preview
+      await wait(150);
+      const frame = lastFrame() ?? '';
+      // Tool group renders with raw function name fallback (no registry).
+      expect(frame).toContain('BashTool');
+    });
+
+    it('Enter inside preview fires onSelect with previewed sessionId', async () => {
+      const sessions = [
+        createMockSession({
+          sessionId: 's1',
+          prompt: 'First',
+          messageCount: 2,
+        }),
+        createMockSession({
+          sessionId: 's2',
+          prompt: 'Second',
+          messageCount: 2,
+        }),
+      ];
+      const service = createMockSessionService(sessions);
+      service.loadSession.mockResolvedValue(fakeResumedData('s1'));
+      const onSelect = vi.fn();
+
+      const { stdin } = renderPicker(
+        <SessionPicker
+          sessionService={service as never}
+          onSelect={onSelect}
+          onCancel={vi.fn()}
+          enablePreview
+        />,
+      );
+
+      await wait(100);
+      stdin.write(' '); // open preview on s1
+      await wait(150);
+      stdin.write('\r'); // Enter
+      await wait(50);
+      expect(onSelect).toHaveBeenCalledWith('s1');
+    });
+
+    it('without enablePreview, Space is a no-op and footer omits the hint', async () => {
+      // Regression: SessionPicker is also reused by the delete-session
+      // dialog, where `onSelect = handleDelete`. If preview were on by
+      // default, Space → preview → Enter would silently delete the session
+      // while the preview UI still says "Enter to resume". The default must
+      // stay opt-in.
+      const sessions = [
+        createMockSession({
+          sessionId: 's1',
+          prompt: 'Deletable session',
+          messageCount: 2,
+        }),
+      ];
+      const service = createMockSessionService(sessions);
+      service.loadSession.mockResolvedValue(fakeResumedData('s1'));
+      const onSelect = vi.fn();
+
+      const { stdin, lastFrame } = renderPicker(
+        <SessionPicker
+          sessionService={service as never}
+          onSelect={onSelect}
+          onCancel={vi.fn()}
+          // intentionally NO enablePreview — emulates the delete dialog
+        />,
+      );
+
+      await wait(100);
+      const beforeFrame = lastFrame() ?? '';
+      expect(beforeFrame).toContain('Deletable session');
+      // Hint must not appear, otherwise we are training users to press
+      // Space in destructive flows.
+      expect(beforeFrame).not.toContain('Space to preview');
+
+      stdin.write(' '); // Space
+      await wait(150);
+      const afterFrame = lastFrame() ?? '';
+      // No preview body, still on the list.
+      expect(afterFrame).not.toContain('USER-ASKED-THIS');
+      expect(afterFrame).toContain('Deletable session');
+
+      // Enter must still call onSelect on the highlighted row (delete path
+      // unchanged), not be eaten by a phantom preview.
+      stdin.write('\r');
+      await wait(50);
+      expect(onSelect).toHaveBeenCalledWith('s1');
+      expect(service.loadSession).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/packages/cli/src/ui/components/StandaloneSessionPicker.tsx b/packages/cli/src/ui/components/StandaloneSessionPicker.tsx
index ba9a3f21f..1a245e0ab 100644
--- a/packages/cli/src/ui/components/StandaloneSessionPicker.tsx
+++ b/packages/cli/src/ui/components/StandaloneSessionPicker.tsx
@@ -9,12 +9,41 @@ import { render, Box, useApp } from 'ink';
 import {
   getGitBranch,
   SessionService,
+  type Config,
   type SessionListItem,
 } from '@qwen-code/qwen-code-core';
 import { KeypressProvider } from '../contexts/KeypressContext.js';
+import { ConfigContext } from '../contexts/ConfigContext.js';
+import { SettingsContext } from '../contexts/SettingsContext.js';
+import type { LoadedSettings } from '../../config/settings.js';
 import { SessionPicker } from './SessionPicker.js';
 import { writeStdoutLine } from '../../utils/stdioHelpers.js';
 
+/**
+ * `--resume` runs this picker BEFORE `loadCliConfig`, so no real Config /
+ * LoadedSettings exist yet. But the preview render tree (HistoryItemDisplay
+ * → ToolGroupMessage → ToolMessage) calls `useConfig()` / `useSettings()`,
+ * which throw without a Provider mounted.
+ *
+ * These stubs satisfy the Context consumers. Every downstream access of
+ * Config/Settings in the preview path is either optional-chained or gated
+ * on states (Confirming / Executing) that never occur in resumed session
+ * data, so the stubbed methods are only read, never invoked for real work.
+ * Tool descriptions fall back to the raw function-call name (see
+ * `buildResumedHistoryItems` handling when the registry returns undefined).
+ */
+const PREVIEW_CONFIG_STUB = {
+  getShouldUseNodePtyShell: () => false,
+  getIdeMode: () => false,
+  isTrustedFolder: () => false,
+  getToolRegistry: () => ({ getTool: () => undefined }),
+  getContentGenerator: () => ({ useSummarizedThinking: () => false }),
+} as unknown as Config;
+
+const PREVIEW_SETTINGS_STUB = {
+  merged: { ui: {} },
+} as unknown as LoadedSettings;
+
 interface StandalonePickerScreenProps {
   sessionService: SessionService;
   onSelect: (sessionId: string) => void;
@@ -43,20 +72,25 @@ function StandalonePickerScreen({
   }
 
   return (
-    <SessionPicker
-      sessionService={sessionService}
-      onSelect={(id) => {
-        onSelect(id);
-        handleExit();
-      }}
-      onCancel={() => {
-        onCancel();
-        handleExit();
-      }}
-      currentBranch={currentBranch}
-      centerSelection={true}
-      initialSessions={initialSessions}
-    />
+    <ConfigContext.Provider value={PREVIEW_CONFIG_STUB}>
+      <SettingsContext.Provider value={PREVIEW_SETTINGS_STUB}>
+        <SessionPicker
+          sessionService={sessionService}
+          onSelect={(id) => {
+            onSelect(id);
+            handleExit();
+          }}
+          onCancel={() => {
+            onCancel();
+            handleExit();
+          }}
+          currentBranch={currentBranch}
+          centerSelection={true}
+          initialSessions={initialSessions}
+          enablePreview
+        />
+      </SettingsContext.Provider>
+    </ConfigContext.Provider>
   );
 }
 
diff --git a/packages/cli/src/ui/components/StatsDisplay.test.tsx b/packages/cli/src/ui/components/StatsDisplay.test.tsx
index b75b3c2dc..0a4540ca2 100644
--- a/packages/cli/src/ui/components/StatsDisplay.test.tsx
+++ b/packages/cli/src/ui/components/StatsDisplay.test.tsx
@@ -5,7 +5,7 @@
  */
 
 import { render } from 'ink-testing-library';
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { StatsDisplay } from './StatsDisplay.js';
 import * as SessionContext from '../contexts/SessionContext.js';
 import type {
@@ -14,6 +14,7 @@ import type {
   SessionMetrics,
 } from '../contexts/SessionContext.js';
 import { MAIN_SOURCE } from '@qwen-code/qwen-code-core';
+import { DEFAULT_THEME, themeManager } from '../themes/theme-manager.js';
 
 // Wraps a core metrics object as a ModelMetrics with a single `main` source
 // bucket, matching the shape produced by processing an API call with no
@@ -33,6 +34,21 @@ vi.mock('../contexts/SessionContext.js', async (importOriginal) => {
 });
 
 const useSessionStatsMock = vi.mocked(SessionContext.useSessionStats);
+const originalNoColor = process.env['NO_COLOR'];
+
+beforeEach(() => {
+  delete process.env['NO_COLOR'];
+});
+
+afterEach(() => {
+  if (originalNoColor === undefined) {
+    delete process.env['NO_COLOR'];
+  } else {
+    process.env['NO_COLOR'] = originalNoColor;
+  }
+  themeManager.loadCustomThemes({});
+  themeManager.setActiveTheme(DEFAULT_THEME.name);
+});
 
 const renderWithMockedStats = (metrics: SessionMetrics) => {
   useSessionStatsMock.mockReturnValue({
@@ -558,5 +574,35 @@ describe('<StatsDisplay />', () => {
       expect(output).not.toContain('Session Stats');
       expect(output).toMatchSnapshot();
     });
+
+    it('renders a custom title as plain text when the theme has too few gradient colors', () => {
+      themeManager.loadCustomThemes({
+        OneColorGradient: {
+          name: 'OneColorGradient',
+          type: 'custom',
+          ui: { gradient: ['red'] },
+        },
+      });
+      themeManager.setActiveTheme('OneColorGradient');
+      useSessionStatsMock.mockReturnValue({
+        stats: {
+          sessionId: 'test-session-id',
+          sessionStartTime: new Date(),
+          metrics: zeroMetrics,
+          lastPromptTokenCount: 0,
+          promptCount: 5,
+        },
+
+        getPromptCount: () => 5,
+        startNewPrompt: vi.fn(),
+      });
+
+      const { lastFrame } = render(
+        <StatsDisplay duration="1s" title="Agent powering down. Goodbye!" />,
+      );
+      const output = lastFrame();
+      expect(output).toContain('Agent powering down. Goodbye!');
+      expect(output).not.toContain('Invalid number of stops');
+    });
   });
 });
diff --git a/packages/cli/src/ui/components/StatsDisplay.tsx b/packages/cli/src/ui/components/StatsDisplay.tsx
index 2a766f698..e66d4cd19 100644
--- a/packages/cli/src/ui/components/StatsDisplay.tsx
+++ b/packages/cli/src/ui/components/StatsDisplay.tsx
@@ -18,6 +18,7 @@ import {
   USER_AGREEMENT_RATE_HIGH,
   USER_AGREEMENT_RATE_MEDIUM,
 } from '../utils/displayUtils.js';
+import { getRenderableGradientColors } from '../utils/gradientUtils.js';
 import { computeSessionStats } from '../utils/computeStats.js';
 import { flattenModelsBySource } from '../utils/modelsBySource.js';
 import { t } from '../../i18n/index.js';
@@ -194,8 +195,9 @@ export const StatsDisplay: React.FC<StatsDisplayProps> = ({
 
   const renderTitle = () => {
     if (title) {
-      return theme.ui.gradient && theme.ui.gradient.length > 0 ? (
-        <Gradient colors={theme.ui.gradient}>
+      const gradientColors = getRenderableGradientColors(theme.ui.gradient);
+      return gradientColors ? (
+        <Gradient colors={gradientColors}>
           <Text bold color={theme.text.primary}>
             {title}
           </Text>
diff --git a/packages/cli/src/ui/components/StickyTodoList.test.tsx b/packages/cli/src/ui/components/StickyTodoList.test.tsx
new file mode 100644
index 000000000..0c2af5454
--- /dev/null
+++ b/packages/cli/src/ui/components/StickyTodoList.test.tsx
@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { render } from 'ink-testing-library';
+import { describe, expect, it } from 'vitest';
+import { StickyTodoList } from './StickyTodoList.js';
+import type { TodoItem } from './TodoDisplay.js';
+
+describe('StickyTodoList', () => {
+  it('keeps each task number attached to the original task after sorting', () => {
+    const todos: TodoItem[] = [
+      {
+        id: 'done',
+        content: 'Summarize results',
+        status: 'completed',
+      },
+      {
+        id: 'pending',
+        content: 'Run cli tests',
+        status: 'pending',
+      },
+      {
+        id: 'active',
+        content: 'Run core tests',
+        status: 'in_progress',
+      },
+    ];
+
+    const { lastFrame } = render(<StickyTodoList todos={todos} width={60} />);
+    const output = lastFrame() ?? '';
+    const lines = output
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+
+    expect(output).toContain('Current tasks');
+    expect(output).toContain('╭');
+    expect(
+      lines.find((line) => line.includes('Run core tests')) ?? '',
+    ).toContain('3.');
+    expect(
+      lines.find((line) => line.includes('Run cli tests')) ?? '',
+    ).toContain('2.');
+    expect(
+      lines.find((line) => line.includes('Summarize results')) ?? '',
+    ).toContain('1.');
+    expect(output.indexOf('Run core tests')).toBeLessThan(
+      output.indexOf('Run cli tests'),
+    );
+    expect(output.indexOf('Run cli tests')).toBeLessThan(
+      output.indexOf('Summarize results'),
+    );
+  });
+});
diff --git a/packages/cli/src/ui/components/StickyTodoList.tsx b/packages/cli/src/ui/components/StickyTodoList.tsx
new file mode 100644
index 000000000..7f68591a8
--- /dev/null
+++ b/packages/cli/src/ui/components/StickyTodoList.tsx
@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { useMemo } from 'react';
+import { Box, Text } from 'ink';
+import { t } from '../../i18n/index.js';
+import { Colors } from '../colors.js';
+import { theme } from '../semantic-colors.js';
+import { getOrderedStickyTodos } from '../utils/todoSnapshot.js';
+import type { TodoItem } from './TodoDisplay.js';
+
+interface StickyTodoListProps {
+  todos: TodoItem[];
+  width: number;
+}
+
+const STATUS_ICONS = {
+  pending: '○',
+  in_progress: '◐',
+  completed: '●',
+} as const;
+
+export const StickyTodoList: React.FC<StickyTodoListProps> = ({
+  todos,
+  width,
+}) => {
+  const orderedTodos = useMemo(() => getOrderedStickyTodos(todos), [todos]);
+  const todoNumberById = useMemo(
+    () =>
+      new Map(todos.map((todo, index) => [todo.id, `${index + 1}.`] as const)),
+    [todos],
+  );
+
+  if (todos.length === 0) {
+    return null;
+  }
+
+  const numberColumnWidth = String(orderedTodos.length).length + 2;
+
+  return (
+    <Box
+      marginX={2}
+      width={width}
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={theme.border.default}
+      paddingX={1}
+    >
+      <Text color={theme.text.secondary} bold>
+        {t('Current tasks')}
+      </Text>
+      {orderedTodos.map((todo, index) => {
+        const todoNumber = todoNumberById.get(todo.id) ?? `${index + 1}.`;
+        const itemColor =
+          todo.status === 'in_progress'
+            ? Colors.AccentGreen
+            : Colors.Foreground;
+
+        return (
+          <Box key={todo.id} flexDirection="row" minHeight={1}>
+            <Box width={numberColumnWidth}>
+              <Text color={theme.text.secondary}>{todoNumber}</Text>
+            </Box>
+            <Box width={2}>
+              <Text color={itemColor}>{STATUS_ICONS[todo.status]}</Text>
+            </Box>
+            <Box flexGrow={1}>
+              <Text
+                color={itemColor}
+                strikethrough={todo.status === 'completed'}
+                wrap="wrap"
+              >
+                {todo.content}
+              </Text>
+            </Box>
+          </Box>
+        );
+      })}
+    </Box>
+  );
+};
diff --git a/packages/cli/src/ui/components/agent-view/AgentChatContent.tsx b/packages/cli/src/ui/components/agent-view/AgentChatContent.tsx
new file mode 100644
index 000000000..9f086df4f
--- /dev/null
+++ b/packages/cli/src/ui/components/agent-view/AgentChatContent.tsx
@@ -0,0 +1,274 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Presentational transcript renderer for a single AgentCore. Subscribes
+ * to the core's event emitter internally and force-renders on updates,
+ * so consumers only pass state props and don't wire their own listeners.
+ */
+
+import { Box, Text, Static } from 'ink';
+import { useMemo, useState, useEffect, useCallback, useRef } from 'react';
+import {
+  AgentStatus,
+  AgentEventType,
+  getGitBranch,
+  type AgentCore,
+  type AgentInteractive,
+  type AgentStatusChangeEvent,
+} from '@qwen-code/qwen-code-core';
+import { useUIState } from '../../contexts/UIStateContext.js';
+import { useTerminalSize } from '../../hooks/useTerminalSize.js';
+import { useKeypress } from '../../hooks/useKeypress.js';
+import { useAgentViewActions } from '../../contexts/AgentViewContext.js';
+import { HistoryItemDisplay } from '../HistoryItemDisplay.js';
+import { ToolCallStatus } from '../../types.js';
+import { theme } from '../../semantic-colors.js';
+import { GeminiRespondingSpinner } from '../GeminiRespondingSpinner.js';
+import { agentMessagesToHistoryItems } from './agentHistoryAdapter.js';
+import { AgentHeader } from './AgentHeader.js';
+
+export interface AgentChatContentProps {
+  /** The agent's AgentCore — the source of truth for transcript state. */
+  core: AgentCore;
+  /**
+   * The InteractiveAgent wrapper, if any. Present for live arena tabs;
+   * omit for read-only transcript surfaces. When provided, drives the
+   * spinner and the embedded-shell affordance — all reads happen inside
+   * this component, which re-renders on the relevant events, so state
+   * stays fresh without plumbing props from an ancestor that doesn't
+   * subscribe.
+   */
+  interactiveAgent?: AgentInteractive | null;
+  /** Stable identifier used for memo keys and the Static remount key. */
+  instanceKey: string;
+  /** Optional display name shown in the header. */
+  modelName?: string;
+}
+
+export const AgentChatContent = ({
+  core,
+  interactiveAgent,
+  instanceKey,
+  modelName,
+}: AgentChatContentProps) => {
+  const readonly = !interactiveAgent;
+  const uiState = useUIState();
+  const { historyRemountKey, availableTerminalHeight, constrainHeight } =
+    uiState;
+  const { columns: terminalWidth } = useTerminalSize();
+  const contentWidth = terminalWidth - 4;
+
+  // Force re-render on message updates and status changes.
+  // STREAM_TEXT is deliberately excluded — model text is shown only after
+  // each round completes (via committed messages), avoiding per-chunk re-renders.
+  const [, setRenderTick] = useState(0);
+  const tickRef = useRef(0);
+  const forceRender = useCallback(() => {
+    tickRef.current += 1;
+    setRenderTick(tickRef.current);
+  }, []);
+
+  useEffect(() => {
+    const emitter = core.getEventEmitter();
+
+    const onStatusChange = (_event: AgentStatusChangeEvent) => forceRender();
+    const onToolCall = () => forceRender();
+    const onToolResult = () => forceRender();
+    const onRoundEnd = () => forceRender();
+    const onApproval = () => forceRender();
+    const onOutputUpdate = () => forceRender();
+    const onFinish = () => forceRender();
+
+    emitter.on(AgentEventType.STATUS_CHANGE, onStatusChange);
+    emitter.on(AgentEventType.TOOL_CALL, onToolCall);
+    emitter.on(AgentEventType.TOOL_RESULT, onToolResult);
+    emitter.on(AgentEventType.ROUND_END, onRoundEnd);
+    emitter.on(AgentEventType.TOOL_WAITING_APPROVAL, onApproval);
+    emitter.on(AgentEventType.TOOL_OUTPUT_UPDATE, onOutputUpdate);
+    emitter.on(AgentEventType.FINISH, onFinish);
+
+    return () => {
+      emitter.off(AgentEventType.STATUS_CHANGE, onStatusChange);
+      emitter.off(AgentEventType.TOOL_CALL, onToolCall);
+      emitter.off(AgentEventType.TOOL_RESULT, onToolResult);
+      emitter.off(AgentEventType.ROUND_END, onRoundEnd);
+      emitter.off(AgentEventType.TOOL_WAITING_APPROVAL, onApproval);
+      emitter.off(AgentEventType.TOOL_OUTPUT_UPDATE, onOutputUpdate);
+      emitter.off(AgentEventType.FINISH, onFinish);
+    };
+  }, [core, forceRender]);
+
+  const messages = core.getMessages();
+  const pendingApprovals = core.getPendingApprovals();
+  const liveOutputs = core.getLiveOutputs();
+  const shellPids = core.getShellPids();
+
+  // Read status/PTY/timing state fresh on every render — this component
+  // re-renders on STATUS_CHANGE/TOOL_CALL/TOOL_OUTPUT_UPDATE so the reads
+  // stay current without prop plumbing from a non-subscribed ancestor.
+  const status = interactiveAgent?.getStatus() ?? AgentStatus.COMPLETED;
+  const executionStartTimes = interactiveAgent?.getExecutionStartTimes();
+  const activePtyId =
+    shellPids.size > 0
+      ? ((shellPids.values().next().value as number | undefined) ?? null)
+      : null;
+  const isRunning =
+    status === AgentStatus.RUNNING || status === AgentStatus.INITIALIZING;
+
+  // Embedded-shell focus (Ctrl+F toggle). Lives here so the auto-reset
+  // effect sees a fresh activePtyId — AgentChatView above us doesn't
+  // subscribe to agent events, so driving this from there would leave
+  // focus stuck on a terminated PTY.
+  const [embeddedShellFocused, setEmbeddedShellFocused] = useState(false);
+  const { setAgentShellFocused } = useAgentViewActions();
+
+  useEffect(() => {
+    if (readonly) return;
+    setAgentShellFocused(embeddedShellFocused);
+    return () => setAgentShellFocused(false);
+  }, [embeddedShellFocused, readonly, setAgentShellFocused]);
+
+  useEffect(() => {
+    if (!activePtyId) setEmbeddedShellFocused(false);
+  }, [activePtyId]);
+
+  useKeypress(
+    (key) => {
+      if (readonly) return;
+      if (key.ctrl && key.name === 'f') {
+        if (activePtyId || embeddedShellFocused) {
+          setEmbeddedShellFocused((prev) => !prev);
+        }
+      }
+    },
+    { isActive: !readonly },
+  );
+
+  // tickRef.current in deps ensures we rebuild when events fire even if
+  // messages.length and pendingApprovals.size haven't changed (e.g. a
+  // tool result updates an existing entry in place).
+  const allItems = useMemo(
+    () =>
+      agentMessagesToHistoryItems(
+        messages,
+        pendingApprovals,
+        liveOutputs,
+        shellPids,
+        executionStartTimes,
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      instanceKey,
+      messages.length,
+      pendingApprovals.size,
+      liveOutputs.size,
+      shellPids.size,
+      executionStartTimes?.size,
+      tickRef.current,
+    ],
+  );
+
+  // Any tool_group with an Executing or Confirming tool — plus everything
+  // after it — stays in the live area so confirmation dialogs remain
+  // interactive (Ink's <Static> cannot receive input).
+  const splitIndex = useMemo(() => {
+    for (let idx = allItems.length - 1; idx >= 0; idx--) {
+      const item = allItems[idx]!;
+      if (
+        item.type === 'tool_group' &&
+        item.tools.some(
+          (t) =>
+            t.status === ToolCallStatus.Executing ||
+            t.status === ToolCallStatus.Confirming,
+        )
+      ) {
+        return idx;
+      }
+    }
+    return allItems.length;
+  }, [allItems]);
+
+  const committedItems = allItems.slice(0, splitIndex);
+  const pendingItems = allItems.slice(splitIndex);
+
+  const agentWorkingDir = core.runtimeContext.getTargetDir() ?? '';
+  // Cache the branch — it won't change during the agent's lifetime and
+  // getGitBranch uses synchronous execSync which blocks the render loop.
+  const agentGitBranch = useMemo(
+    () => (agentWorkingDir ? getGitBranch(agentWorkingDir) : ''),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [instanceKey],
+  );
+
+  const agentModelId = core.modelConfig.model ?? '';
+
+  return (
+    <Box flexDirection="column">
+      {/* Committed message history.
+          key includes historyRemountKey: when refreshStatic() clears the
+          terminal it bumps the key, forcing Static to remount and re-emit
+          all items on the cleared screen. */}
+      <Static
+        key={`agent-${instanceKey}-${historyRemountKey}`}
+        items={[
+          <AgentHeader
+            key="agent-header"
+            modelId={agentModelId}
+            modelName={modelName}
+            workingDirectory={agentWorkingDir}
+            gitBranch={agentGitBranch}
+          />,
+          ...committedItems.map((item) => (
+            <HistoryItemDisplay
+              key={item.id}
+              item={item}
+              isPending={false}
+              terminalWidth={terminalWidth}
+              mainAreaWidth={contentWidth}
+            />
+          )),
+        ]}
+      >
+        {(item) => item}
+      </Static>
+
+      {/* Live area — tool groups awaiting confirmation or still executing.
+          Must remain outside Static so confirmation dialogs are interactive. */}
+      {pendingItems.map((item) => (
+        <HistoryItemDisplay
+          key={item.id}
+          item={item}
+          isPending={true}
+          terminalWidth={terminalWidth}
+          mainAreaWidth={contentWidth}
+          availableTerminalHeight={
+            constrainHeight ? availableTerminalHeight : undefined
+          }
+          isFocused={!readonly}
+          activeShellPtyId={activePtyId}
+          embeddedShellFocused={embeddedShellFocused}
+        />
+      ))}
+
+      {/* Spinner */}
+      {isRunning && (
+        <Box marginX={2} marginTop={1}>
+          <GeminiRespondingSpinner />
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+// Re-exported helper for consumers that render an error panel when the
+// backing agent/core isn't available (e.g. a race where the registry
+// entry exists but `core` hasn't been attached yet).
+export const AgentChatMissing = ({ label }: { label: string }) => (
+  <Box marginX={2}>
+    <Text color={theme.status.error}>{label}</Text>
+  </Box>
+);
diff --git a/packages/cli/src/ui/components/agent-view/AgentChatView.tsx b/packages/cli/src/ui/components/agent-view/AgentChatView.tsx
index 55389bc5e..117738eb5 100644
--- a/packages/cli/src/ui/components/agent-view/AgentChatView.tsx
+++ b/packages/cli/src/ui/components/agent-view/AgentChatView.tsx
@@ -5,45 +5,13 @@
  */
 
 /**
- * @fileoverview AgentChatView — displays a single in-process agent's conversation.
- *
- * Renders the agent's message history using HistoryItemDisplay — the same
- * component used by the main agent view. AgentMessage[] is converted to
- * HistoryItem[] by agentMessagesToHistoryItems() so all 27 HistoryItem types
- * are available without duplicating rendering logic.
- *
- * Layout:
- *  - Static area:  finalized messages (efficient Ink <Static>)
- *  - Live area:    tool groups still executing / awaiting confirmation
- *  - Status line:  spinner while the agent is running
- *
- * Model text output is shown only after each round completes (no live
- * streaming), which avoids per-chunk re-renders and keeps the display simple.
+ * Arena wrapper around AgentChatContent. Resolves the selected agent
+ * from AgentViewContext; the content component owns live-state reads
+ * and the Ctrl+F embedded-shell toggle.
  */
 
-import { Box, Text, Static } from 'ink';
-import { useMemo, useState, useEffect, useCallback, useRef } from 'react';
-import {
-  AgentStatus,
-  AgentEventType,
-  getGitBranch,
-  type AgentStatusChangeEvent,
-} from '@qwen-code/qwen-code-core';
-import {
-  useAgentViewState,
-  useAgentViewActions,
-} from '../../contexts/AgentViewContext.js';
-import { useUIState } from '../../contexts/UIStateContext.js';
-import { useTerminalSize } from '../../hooks/useTerminalSize.js';
-import { HistoryItemDisplay } from '../HistoryItemDisplay.js';
-import { ToolCallStatus } from '../../types.js';
-import { theme } from '../../semantic-colors.js';
-import { GeminiRespondingSpinner } from '../GeminiRespondingSpinner.js';
-import { useKeypress } from '../../hooks/useKeypress.js';
-import { agentMessagesToHistoryItems } from './agentHistoryAdapter.js';
-import { AgentHeader } from './AgentHeader.js';
-
-// ─── Main Component ─────────────────────────────────────────
+import { useAgentViewState } from '../../contexts/AgentViewContext.js';
+import { AgentChatContent, AgentChatMissing } from './AgentChatContent.js';
 
 interface AgentChatViewProps {
   agentId: string;
@@ -51,225 +19,21 @@ interface AgentChatViewProps {
 
 export const AgentChatView = ({ agentId }: AgentChatViewProps) => {
   const { agents } = useAgentViewState();
-  const { setAgentShellFocused } = useAgentViewActions();
-  const uiState = useUIState();
-  const { historyRemountKey, availableTerminalHeight, constrainHeight } =
-    uiState;
-  const { columns: terminalWidth } = useTerminalSize();
   const agent = agents.get(agentId);
-  const contentWidth = terminalWidth - 4;
-
-  // Force re-render on message updates and status changes.
-  // STREAM_TEXT is deliberately excluded — model text is shown only after
-  // each round completes (via committed messages), avoiding per-chunk re-renders.
-  const [, setRenderTick] = useState(0);
-  const tickRef = useRef(0);
-  const forceRender = useCallback(() => {
-    tickRef.current += 1;
-    setRenderTick(tickRef.current);
-  }, []);
-
-  useEffect(() => {
-    if (!agent) return;
-
-    const emitter = agent.interactiveAgent.getEventEmitter();
-    if (!emitter) return;
-
-    const onStatusChange = (_event: AgentStatusChangeEvent) => forceRender();
-    const onToolCall = () => forceRender();
-    const onToolResult = () => forceRender();
-    const onRoundEnd = () => forceRender();
-    const onApproval = () => forceRender();
-    const onOutputUpdate = () => forceRender();
-
-    emitter.on(AgentEventType.STATUS_CHANGE, onStatusChange);
-    emitter.on(AgentEventType.TOOL_CALL, onToolCall);
-    emitter.on(AgentEventType.TOOL_RESULT, onToolResult);
-    emitter.on(AgentEventType.ROUND_END, onRoundEnd);
-    emitter.on(AgentEventType.TOOL_WAITING_APPROVAL, onApproval);
-    emitter.on(AgentEventType.TOOL_OUTPUT_UPDATE, onOutputUpdate);
-
-    return () => {
-      emitter.off(AgentEventType.STATUS_CHANGE, onStatusChange);
-      emitter.off(AgentEventType.TOOL_CALL, onToolCall);
-      emitter.off(AgentEventType.TOOL_RESULT, onToolResult);
-      emitter.off(AgentEventType.ROUND_END, onRoundEnd);
-      emitter.off(AgentEventType.TOOL_WAITING_APPROVAL, onApproval);
-      emitter.off(AgentEventType.TOOL_OUTPUT_UPDATE, onOutputUpdate);
-    };
-  }, [agent, forceRender]);
 
   const interactiveAgent = agent?.interactiveAgent;
-  const messages = interactiveAgent?.getMessages() ?? [];
-  const pendingApprovals = interactiveAgent?.getPendingApprovals();
-  const liveOutputs = interactiveAgent?.getLiveOutputs();
-  const shellPids = interactiveAgent?.getShellPids();
-  const executionStartTimes = interactiveAgent?.getExecutionStartTimes();
-  const status = interactiveAgent?.getStatus();
-  const isRunning =
-    status === AgentStatus.RUNNING || status === AgentStatus.INITIALIZING;
-
-  // Derive the active PTY PID: first shell PID among currently-executing tools.
-  // Resets naturally to undefined when the tool finishes (shellPids cleared).
-  const activePtyId =
-    shellPids && shellPids.size > 0
-      ? shellPids.values().next().value
-      : undefined;
-
-  // Track whether the user has toggled input focus into the embedded shell.
-  // Mirrors the main agent's embeddedShellFocused in AppContainer.
-  const [embeddedShellFocused, setEmbeddedShellFocusedLocal] = useState(false);
-
-  // Sync to AgentViewContext so AgentTabBar can suppress arrow-key navigation
-  // when an agent's embedded shell is focused.
-  useEffect(() => {
-    setAgentShellFocused(embeddedShellFocused);
-    return () => setAgentShellFocused(false);
-  }, [embeddedShellFocused, setAgentShellFocused]);
-
-  // Reset focus when the shell exits (activePtyId disappears).
-  useEffect(() => {
-    if (!activePtyId) setEmbeddedShellFocusedLocal(false);
-  }, [activePtyId]);
-
-  // Ctrl+F: toggle shell input focus when a PTY is active.
-  useKeypress(
-    (key) => {
-      if (key.ctrl && key.name === 'f') {
-        if (activePtyId || embeddedShellFocused) {
-          setEmbeddedShellFocusedLocal((prev) => !prev);
-        }
-      }
-    },
-    { isActive: true },
-  );
-
-  // Convert AgentMessage[] → HistoryItem[] via adapter.
-  // tickRef.current in deps ensures we rebuild when events fire even if
-  // messages.length and pendingApprovals.size haven't changed (e.g. a
-  // tool result updates an existing entry in place).
-  const allItems = useMemo(
-    () =>
-      agentMessagesToHistoryItems(
-        messages,
-        pendingApprovals ?? new Map(),
-        liveOutputs,
-        shellPids,
-        executionStartTimes,
-      ),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [
-      agentId,
-      messages.length,
-      pendingApprovals?.size,
-      liveOutputs?.size,
-      shellPids?.size,
-      executionStartTimes?.size,
-      tickRef.current,
-    ],
-  );
-
-  // Split into committed (Static) and pending (live area).
-  // Any tool_group with an Executing or Confirming tool — plus everything
-  // after it — stays in the live area so confirmation dialogs remain
-  // interactive (Ink's <Static> cannot receive input).
-  const splitIndex = useMemo(() => {
-    for (let idx = allItems.length - 1; idx >= 0; idx--) {
-      const item = allItems[idx]!;
-      if (
-        item.type === 'tool_group' &&
-        item.tools.some(
-          (t) =>
-            t.status === ToolCallStatus.Executing ||
-            t.status === ToolCallStatus.Confirming,
-        )
-      ) {
-        return idx;
-      }
-    }
-    return allItems.length; // all committed
-  }, [allItems]);
-
-  const committedItems = allItems.slice(0, splitIndex);
-  const pendingItems = allItems.slice(splitIndex);
-
   const core = interactiveAgent?.getCore();
-  const agentWorkingDir = core?.runtimeContext.getTargetDir() ?? '';
-  // Cache the branch — it won't change during the agent's lifetime and
-  // getGitBranch uses synchronous execSync which blocks the render loop.
-  const agentGitBranch = useMemo(
-    () => (agentWorkingDir ? getGitBranch(agentWorkingDir) : ''),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [agentId],
-  );
 
   if (!agent || !interactiveAgent || !core) {
-    return (
-      <Box marginX={2}>
-        <Text color={theme.status.error}>
-          Agent &quot;{agentId}&quot; not found.
-        </Text>
-      </Box>
-    );
+    return <AgentChatMissing label={`Agent "${agentId}" not found.`} />;
   }
 
-  const agentModelId = core.modelConfig.model ?? '';
-
   return (
-    <Box flexDirection="column">
-      {/* Committed message history.
-          key includes historyRemountKey: when refreshStatic() clears the
-          terminal it bumps the key, forcing Static to remount and re-emit
-          all items on the cleared screen. */}
-      <Static
-        key={`agent-${agentId}-${historyRemountKey}`}
-        items={[
-          <AgentHeader
-            key="agent-header"
-            modelId={agentModelId}
-            modelName={agent.modelName}
-            workingDirectory={agentWorkingDir}
-            gitBranch={agentGitBranch}
-          />,
-          ...committedItems.map((item) => (
-            <HistoryItemDisplay
-              key={item.id}
-              item={item}
-              isPending={false}
-              terminalWidth={terminalWidth}
-              mainAreaWidth={contentWidth}
-            />
-          )),
-        ]}
-      >
-        {(item) => item}
-      </Static>
-
-      {/* Live area — tool groups awaiting confirmation or still executing.
-          Must remain outside Static so confirmation dialogs are interactive.
-          Pass PTY state so ShellInputPrompt is reachable via Ctrl+F. */}
-      {pendingItems.map((item) => (
-        <HistoryItemDisplay
-          key={item.id}
-          item={item}
-          isPending={true}
-          terminalWidth={terminalWidth}
-          mainAreaWidth={contentWidth}
-          availableTerminalHeight={
-            constrainHeight ? availableTerminalHeight : undefined
-          }
-          isFocused={true}
-          activeShellPtyId={activePtyId ?? null}
-          embeddedShellFocused={embeddedShellFocused}
-        />
-      ))}
-
-      {/* Spinner */}
-      {isRunning && (
-        <Box marginX={2} marginTop={1}>
-          <GeminiRespondingSpinner />
-        </Box>
-      )}
-    </Box>
+    <AgentChatContent
+      core={core}
+      interactiveAgent={interactiveAgent}
+      instanceKey={agentId}
+      modelName={agent.modelName}
+    />
   );
 };
diff --git a/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx b/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx
index c7b0b113c..f92f8365c 100644
--- a/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx
+++ b/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx
@@ -26,6 +26,10 @@ import {
   useAgentViewActions,
   type RegisteredAgent,
 } from '../../contexts/AgentViewContext.js';
+import {
+  useBackgroundTaskViewState,
+  useBackgroundTaskViewActions,
+} from '../../contexts/BackgroundTaskViewContext.js';
 import { useKeypress } from '../../hooks/useKeypress.js';
 import { useUIState } from '../../contexts/UIStateContext.js';
 import { theme } from '../../semantic-colors.js';
@@ -59,9 +63,16 @@ function statusIndicator(agent: RegisteredAgent): {
 export const AgentTabBar: React.FC = () => {
   const { activeView, agents, agentShellFocused, agentTabBarFocused } =
     useAgentViewState();
-  const { switchToNext, switchToPrevious, setAgentTabBarFocused } =
-    useAgentViewActions();
+  const {
+    switchToNext,
+    switchToPrevious,
+    switchToMain,
+    setAgentTabBarFocused,
+  } = useAgentViewActions();
+  const { entries: bgEntries } = useBackgroundTaskViewState();
+  const { setPillFocused: setBgPillFocused } = useBackgroundTaskViewActions();
   const { embeddedShellFocused } = useUIState();
+  const hasBgAgents = bgEntries.length > 0;
 
   useKeypress(
     (key) => {
@@ -74,6 +85,15 @@ export const AgentTabBar: React.FC = () => {
         switchToNext();
       } else if (key.name === 'up') {
         setAgentTabBarFocused(false);
+      } else if (key.name === 'down') {
+        // Switch to main first — the footer pill only renders under the
+        // main view, so focusing it from an agent tab would strand focus
+        // on an offscreen surface.
+        if (hasBgAgents) {
+          setAgentTabBarFocused(false);
+          switchToMain();
+          setBgPillFocused(true);
+        }
       } else if (
         key.sequence &&
         key.sequence.length === 1 &&
diff --git a/packages/cli/src/ui/components/arena/ArenaSelectDialog.test.tsx b/packages/cli/src/ui/components/arena/ArenaSelectDialog.test.tsx
index efcfc9165..e123444a0 100644
--- a/packages/cli/src/ui/components/arena/ArenaSelectDialog.test.tsx
+++ b/packages/cli/src/ui/components/arena/ArenaSelectDialog.test.tsx
@@ -10,6 +10,7 @@ import {
   AgentStatus,
   ArenaSessionStatus,
   type ArenaManager,
+  type ArenaAgentResult,
   type Config,
 } from '@qwen-code/qwen-code-core';
 import { renderWithProviders } from '../../../test-utils/render.js';
@@ -17,72 +18,7 @@ import { ArenaSelectDialog } from './ArenaSelectDialog.js';
 
 describe('ArenaSelectDialog', () => {
   it('toggles quick preview and detailed diff for the highlighted agent', async () => {
-    const result = {
-      sessionId: 'arena-1',
-      task: 'Update auth',
-      status: ArenaSessionStatus.IDLE,
-      agents: [
-        {
-          agentId: 'model-1',
-          model: { modelId: 'model-1', authType: 'openai' },
-          status: AgentStatus.IDLE,
-          worktree: {
-            id: 'w1',
-            name: 'model-1',
-            path: '/tmp/model-1',
-            branch: 'arena/model-1',
-            isActive: true,
-            createdAt: 1,
-          },
-          stats: {
-            rounds: 1,
-            totalTokens: 1000,
-            inputTokens: 700,
-            outputTokens: 300,
-            durationMs: 2000,
-            toolCalls: 2,
-            successfulToolCalls: 2,
-            failedToolCalls: 0,
-          },
-          diff: `diff --git a/src/auth.ts b/src/auth.ts
---- a/src/auth.ts
-+++ b/src/auth.ts
-@@ -1 +1 @@
--old
-+new`,
-          diffSummary: {
-            files: [{ path: 'src/auth.ts', additions: 1, deletions: 1 }],
-            additions: 1,
-            deletions: 1,
-          },
-          modifiedFiles: ['src/auth.ts'],
-          approachSummary: 'Updated the auth implementation inline.',
-          startedAt: 1,
-        },
-      ],
-      startedAt: 1,
-      wasRepoInitialized: false,
-    };
-
-    const manager = {
-      getResult: vi.fn(() => result),
-      getAgentStates: vi.fn(() => [
-        {
-          agentId: 'model-1',
-          model: { modelId: 'model-1', authType: 'openai' },
-          status: AgentStatus.IDLE,
-          stats: result.agents[0]!.stats,
-        },
-      ]),
-      getAgentState: vi.fn(),
-      applyAgentResult: vi.fn(),
-    } as unknown as ArenaManager;
-
-    const config = {
-      getArenaManager: () => manager,
-      cleanupArenaRuntime: vi.fn(),
-      getChatRecordingService: () => undefined,
-    } as unknown as Config;
+    const { manager, config } = createDialogHarness();
 
     const { lastFrame, stdin } = renderWithProviders(
       <ArenaSelectDialog
@@ -105,4 +41,196 @@ describe('ArenaSelectDialog', () => {
     });
     expect(lastFrame()).toContain('diff --git a/src/auth.ts b/src/auth.ts');
   });
+
+  it('closes without applying or cleaning up when Escape is pressed', async () => {
+    const { manager, config, closeArenaDialog, applyAgentResult } =
+      createDialogHarness();
+    const cleanupArenaRuntime = config.cleanupArenaRuntime as ReturnType<
+      typeof vi.fn
+    >;
+
+    const { stdin } = renderWithProviders(
+      <ArenaSelectDialog
+        manager={manager}
+        config={config}
+        addItem={vi.fn()}
+        closeArenaDialog={closeArenaDialog}
+      />,
+    );
+
+    stdin.write('\x1B');
+
+    await waitFor(() => {
+      expect(closeArenaDialog).toHaveBeenCalledTimes(1);
+    });
+    expect(applyAgentResult).not.toHaveBeenCalled();
+    expect(cleanupArenaRuntime).not.toHaveBeenCalled();
+  });
+
+  it('discards results without applying changes when x is pressed', async () => {
+    const { manager, config, closeArenaDialog, applyAgentResult } =
+      createDialogHarness();
+    const cleanupArenaRuntime = config.cleanupArenaRuntime as ReturnType<
+      typeof vi.fn
+    >;
+
+    const { stdin } = renderWithProviders(
+      <ArenaSelectDialog
+        manager={manager}
+        config={config}
+        addItem={vi.fn()}
+        closeArenaDialog={closeArenaDialog}
+      />,
+    );
+
+    stdin.write('x');
+
+    await waitFor(() => {
+      expect(cleanupArenaRuntime).toHaveBeenCalledWith(true);
+    });
+    expect(closeArenaDialog).toHaveBeenCalledTimes(1);
+    expect(applyAgentResult).not.toHaveBeenCalled();
+  });
+
+  it('applies the highlighted successful agent when Enter is pressed', async () => {
+    const { manager, config, closeArenaDialog, applyAgentResult } =
+      createDialogHarness();
+    const cleanupArenaRuntime = config.cleanupArenaRuntime as ReturnType<
+      typeof vi.fn
+    >;
+
+    const { stdin } = renderWithProviders(
+      <ArenaSelectDialog
+        manager={manager}
+        config={config}
+        addItem={vi.fn()}
+        closeArenaDialog={closeArenaDialog}
+      />,
+    );
+
+    stdin.write('\r');
+
+    await waitFor(() => {
+      expect(applyAgentResult).toHaveBeenCalledWith('model-1');
+    });
+    expect(closeArenaDialog).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(cleanupArenaRuntime).toHaveBeenCalledWith(true);
+    });
+  });
+
+  it('ignores Enter when the highlighted agent is not selectable', async () => {
+    const failedAgent = createAgentResult({
+      agentId: 'model-1',
+      status: AgentStatus.FAILED,
+    });
+    const { manager, config, closeArenaDialog, applyAgentResult } =
+      createDialogHarness([failedAgent]);
+    const cleanupArenaRuntime = config.cleanupArenaRuntime as ReturnType<
+      typeof vi.fn
+    >;
+
+    const { stdin } = renderWithProviders(
+      <ArenaSelectDialog
+        manager={manager}
+        config={config}
+        addItem={vi.fn()}
+        closeArenaDialog={closeArenaDialog}
+      />,
+    );
+
+    stdin.write('\r');
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(applyAgentResult).not.toHaveBeenCalled();
+    expect(closeArenaDialog).not.toHaveBeenCalled();
+    expect(cleanupArenaRuntime).not.toHaveBeenCalled();
+  });
 });
+
+function createDialogHarness(agents = [createAgentResult()]) {
+  const result = {
+    sessionId: 'arena-1',
+    task: 'Update auth',
+    status: ArenaSessionStatus.IDLE,
+    agents,
+    startedAt: 1,
+    wasRepoInitialized: false,
+  };
+
+  const applyAgentResult = vi.fn().mockResolvedValue({ success: true });
+  const manager = {
+    getResult: vi.fn(() => result),
+    getAgentStates: vi.fn(() =>
+      agents.map((agent) => ({
+        agentId: agent.agentId,
+        model: agent.model,
+        status: agent.status,
+        stats: agent.stats,
+      })),
+    ),
+    getAgentState: vi.fn((agentId: string) =>
+      agents.find((agent) => agent.agentId === agentId),
+    ),
+    applyAgentResult,
+  } as unknown as ArenaManager;
+
+  const config = {
+    getArenaManager: () => manager,
+    cleanupArenaRuntime: vi.fn().mockResolvedValue(undefined),
+    getChatRecordingService: () => undefined,
+  } as unknown as Config;
+
+  return {
+    manager,
+    config,
+    closeArenaDialog: vi.fn(),
+    applyAgentResult,
+  };
+}
+
+function createAgentResult({
+  agentId = 'model-1',
+  status = AgentStatus.IDLE,
+}: {
+  agentId?: string;
+  status?: AgentStatus;
+} = {}): ArenaAgentResult {
+  return {
+    agentId,
+    model: { modelId: agentId, authType: 'openai' },
+    status,
+    worktree: {
+      id: `worktree-${agentId}`,
+      name: agentId,
+      path: `/tmp/${agentId}`,
+      branch: `arena/${agentId}`,
+      isActive: true,
+      createdAt: 1,
+    },
+    stats: {
+      rounds: 1,
+      totalTokens: 1000,
+      inputTokens: 700,
+      outputTokens: 300,
+      durationMs: 2000,
+      toolCalls: 2,
+      successfulToolCalls: 2,
+      failedToolCalls: 0,
+    },
+    diff: `diff --git a/src/auth.ts b/src/auth.ts
+--- a/src/auth.ts
++++ b/src/auth.ts
+@@ -1 +1 @@
+-old
++new`,
+    diffSummary: {
+      files: [{ path: 'src/auth.ts', additions: 1, deletions: 1 }],
+      additions: 1,
+      deletions: 1,
+    },
+    modifiedFiles: ['src/auth.ts'],
+    approachSummary: 'Updated the auth implementation inline.',
+    startedAt: 1,
+  };
+}
diff --git a/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.test.tsx b/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.test.tsx
new file mode 100644
index 000000000..8d2ce1c2f
--- /dev/null
+++ b/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.test.tsx
@@ -0,0 +1,199 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { useState } from 'react';
+import { act } from '@testing-library/react';
+import { render } from 'ink-testing-library';
+import type { BackgroundTaskEntry, Config } from '@qwen-code/qwen-code-core';
+import { BackgroundTasksDialog } from './BackgroundTasksDialog.js';
+import {
+  BackgroundTaskViewProvider,
+  useBackgroundTaskViewActions,
+  useBackgroundTaskViewState,
+} from '../../contexts/BackgroundTaskViewContext.js';
+import { ConfigContext } from '../../contexts/ConfigContext.js';
+import { useBackgroundTaskView } from '../../hooks/useBackgroundTaskView.js';
+import { useKeypress } from '../../hooks/useKeypress.js';
+
+vi.mock('../../hooks/useBackgroundTaskView.js', () => ({
+  useBackgroundTaskView: vi.fn(),
+}));
+
+vi.mock('../../hooks/useKeypress.js', () => ({
+  useKeypress: vi.fn(),
+}));
+
+const mockedUseBackgroundTaskView = vi.mocked(useBackgroundTaskView);
+const mockedUseKeypress = vi.mocked(useKeypress);
+
+function entry(overrides: Partial<BackgroundTaskEntry>): BackgroundTaskEntry {
+  return {
+    agentId: 'a',
+    description: 'desc',
+    status: 'running',
+    startTime: 0,
+    abortController: new AbortController(),
+    ...overrides,
+  };
+}
+
+interface ProbeHandle {
+  actions: ReturnType<typeof useBackgroundTaskViewActions>;
+  state: ReturnType<typeof useBackgroundTaskViewState>;
+  setEntries: (next: readonly BackgroundTaskEntry[]) => void;
+}
+
+interface Harness {
+  cancel: ReturnType<typeof vi.fn>;
+  setEntries: (next: readonly BackgroundTaskEntry[]) => void;
+  pressKey: (key: { name?: string; sequence?: string }) => void;
+  call: (fn: () => void) => void;
+  lastFrame: () => string | undefined;
+  probe: { current: ProbeHandle | null };
+}
+
+function setup(initial: readonly BackgroundTaskEntry[]): Harness {
+  const handlers: Array<(key: { name?: string; sequence?: string }) => void> =
+    [];
+  mockedUseKeypress.mockImplementation((cb, opts) => {
+    if (opts?.isActive !== false) handlers.push(cb as never);
+  });
+
+  const cancel = vi.fn();
+  const config = {
+    getBackgroundTaskRegistry: () => ({
+      cancel,
+      setActivityChangeCallback: vi.fn(),
+    }),
+  } as unknown as Config;
+
+  const handle: { current: ProbeHandle | null } = { current: null };
+
+  // Wrapper holds the entries in React state so updates propagate normally.
+  // The hook mock is bound to this wrapper via the closure below.
+  function Harness() {
+    const [entries, setEntries] = useState(initial);
+    mockedUseBackgroundTaskView.mockImplementation(() => ({ entries }));
+    return (
+      <ConfigContext.Provider value={config}>
+        <BackgroundTaskViewProvider config={config}>
+          <Probe entriesSetter={setEntries} />
+          <BackgroundTasksDialog
+            availableTerminalHeight={30}
+            terminalWidth={80}
+          />
+        </BackgroundTaskViewProvider>
+      </ConfigContext.Provider>
+    );
+  }
+
+  function Probe({
+    entriesSetter,
+  }: {
+    entriesSetter: (e: readonly BackgroundTaskEntry[]) => void;
+  }) {
+    handle.current = {
+      actions: useBackgroundTaskViewActions(),
+      state: useBackgroundTaskViewState(),
+      setEntries: entriesSetter,
+    };
+    return null;
+  }
+
+  const { lastFrame } = render(<Harness />);
+
+  return {
+    cancel,
+    setEntries(next) {
+      handlers.length = 0;
+      act(() => handle.current!.setEntries(next));
+    },
+    pressKey(key) {
+      act(() => {
+        for (const h of handlers) h(key);
+      });
+    },
+    call(fn) {
+      act(() => fn());
+    },
+    lastFrame,
+    probe: handle,
+  };
+}
+
+describe('BackgroundTasksDialog', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('exits to list mode when the running entry being viewed flips to a terminal status', () => {
+    const running = entry({ agentId: 'a', status: 'running' });
+    const h = setup([running]);
+
+    h.call(() => h.probe.current!.actions.openDialog());
+    h.call(() => h.probe.current!.actions.enterDetail());
+    expect(h.probe.current!.state.dialogMode).toBe('detail');
+
+    h.setEntries([{ ...running, status: 'completed' }]);
+
+    expect(h.probe.current!.state.dialogMode).toBe('list');
+  });
+
+  it('exits to list mode after cancelling the running entry being viewed in detail', () => {
+    const running = entry({ agentId: 'a', status: 'running' });
+    const h = setup([running]);
+
+    h.call(() => h.probe.current!.actions.openDialog());
+    h.call(() => h.probe.current!.actions.enterDetail());
+    expect(h.probe.current!.state.dialogMode).toBe('detail');
+
+    h.pressKey({ sequence: 'x' });
+    expect(h.cancel).toHaveBeenCalledWith('a');
+
+    // Registry would push the cancelled status; simulate that update.
+    h.setEntries([{ ...running, status: 'cancelled' }]);
+
+    expect(h.probe.current!.state.dialogMode).toBe('list');
+  });
+
+  it('keeps detail mode when an already-terminal entry is opened (no spurious fallback)', () => {
+    const done = entry({ agentId: 'a', status: 'completed' });
+    const h = setup([done]);
+
+    h.call(() => h.probe.current!.actions.openDialog());
+    h.call(() => h.probe.current!.actions.enterDetail());
+    expect(h.probe.current!.state.dialogMode).toBe('detail');
+
+    // The auto-fallback ref must only trigger on a running → terminal
+    // transition. Re-rendering with a fresh terminal entry must not evict
+    // the user from detail.
+    h.setEntries([{ ...done }]);
+    expect(h.probe.current!.state.dialogMode).toBe('detail');
+  });
+
+  it('clamps selectedIndex when entries shrink', () => {
+    const a = entry({ agentId: 'a' });
+    const b = entry({ agentId: 'b' });
+    const c = entry({ agentId: 'c' });
+    const h = setup([a, b, c]);
+
+    h.call(() => h.probe.current!.actions.openDialog());
+    h.call(() => h.probe.current!.actions.moveSelectionDown());
+    h.call(() => h.probe.current!.actions.moveSelectionDown());
+    expect(h.probe.current!.state.selectedIndex).toBe(2);
+
+    h.setEntries([a]);
+    expect(h.probe.current!.state.selectedIndex).toBe(0);
+
+    h.setEntries([]);
+    expect(h.probe.current!.state.selectedIndex).toBe(0);
+  });
+});
diff --git a/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx b/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx
new file mode 100644
index 000000000..1f5f20067
--- /dev/null
+++ b/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx
@@ -0,0 +1,572 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * BackgroundTasksDialog — overlay with two modes (`list`, `detail`).
+ * Key handling is scoped to this component; the composer is muted via
+ * the `bgDialogOpen` branch in InputPrompt while the dialog is open.
+ */
+
+import type React from 'react';
+import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Text } from 'ink';
+import stringWidth from 'string-width';
+import {
+  useBackgroundTaskViewState,
+  useBackgroundTaskViewActions,
+} from '../../contexts/BackgroundTaskViewContext.js';
+import { useKeypress } from '../../hooks/useKeypress.js';
+import { MaxSizedBox } from '../shared/MaxSizedBox.js';
+import { theme } from '../../semantic-colors.js';
+import { useConfig } from '../../contexts/ConfigContext.js';
+import {
+  buildBackgroundEntryLabel,
+  ToolDisplayNames,
+  ToolNames,
+  type BackgroundTaskEntry,
+} from '@qwen-code/qwen-code-core';
+
+// Tool-name → display-name lookup (`run_shell_command` → `Shell`).
+const TOOL_DISPLAY_BY_NAME: Record<string, string> = Object.fromEntries(
+  (Object.keys(ToolNames) as Array<keyof typeof ToolNames>).map((key) => [
+    ToolNames[key],
+    ToolDisplayNames[key],
+  ]),
+);
+
+function formatActivityLabel(name: string, description: string | undefined) {
+  const display = TOOL_DISPLAY_BY_NAME[name] ?? name;
+  const singleLineDesc = description
+    ? description.replace(/\s*\n\s*/g, ' ').trim()
+    : '';
+  return singleLineDesc ? `${display}(${singleLineDesc})` : display;
+}
+import { formatDuration, formatTokenCount } from '../../utils/formatters.js';
+
+const STATUS_VERBS: Record<BackgroundTaskEntry['status'], string> = {
+  running: 'Running',
+  completed: 'Completed',
+  failed: 'Failed',
+  cancelled: 'Stopped',
+};
+
+interface StatusPresentation {
+  icon: string;
+  color: string;
+  labelColor: string;
+}
+
+function terminalStatusPresentation(
+  status: BackgroundTaskEntry['status'],
+): StatusPresentation | null {
+  switch (status) {
+    case 'completed':
+      return {
+        icon: '\u2714',
+        color: theme.status.success,
+        labelColor: theme.text.secondary,
+      };
+    case 'failed':
+      return {
+        icon: '\u2716',
+        color: theme.status.error,
+        labelColor: theme.status.errorDim,
+      };
+    case 'cancelled':
+      return {
+        icon: '\u2716',
+        color: theme.status.warning,
+        labelColor: theme.status.warningDim,
+      };
+    default:
+      return null;
+  }
+}
+
+function rowLabel(entry: BackgroundTaskEntry): string {
+  return buildBackgroundEntryLabel(entry, { includePrefix: false });
+}
+
+function elapsedFor(entry: BackgroundTaskEntry): string {
+  const elapsedMs = Math.max(
+    0,
+    (entry.endTime ?? Date.now()) - entry.startTime,
+  );
+  // Round down to whole seconds — the detail subtitle is a glanceable
+  // indicator, not a stopwatch, and sub-second precision flickers distract
+  // from the actual status change.
+  const wholeSeconds = Math.floor(elapsedMs / 1000);
+  return formatDuration(wholeSeconds * 1000, { hideTrailingZeros: true });
+}
+
+// Manually truncate to an exact cell width so each row lines up with the
+// others regardless of content length. Relying on Ink's `wrap="truncate-end"`
+// inside MaxSizedBox produced inconsistent row widths when some rows fit and
+// others needed ellipsis, breaking the left-column alignment of the prefix.
+function truncateToWidth(text: string, maxWidth: number): string {
+  if (maxWidth <= 0) return '';
+  if (stringWidth(text) <= maxWidth) return text;
+  const ellipsis = '…';
+  const ellipsisWidth = stringWidth(ellipsis);
+  const target = Math.max(0, maxWidth - ellipsisWidth);
+  let width = 0;
+  let result = '';
+  for (const char of text) {
+    const charWidth = stringWidth(char);
+    if (width + charWidth > target) break;
+    width += charWidth;
+    result += char;
+  }
+  return result + ellipsis;
+}
+
+// ─── List mode ─────────────────────────────────────────────
+
+const ListBody: React.FC<{
+  entries: readonly BackgroundTaskEntry[];
+  selectedIndex: number;
+  maxRows: number;
+}> = ({ entries, selectedIndex, maxRows }) => {
+  // Keep the "Local agents (N)" section header rendered even when the list
+  // is empty, so the overlay doesn't collapse into a single line of
+  // empty-state text when the last agent finishes while the dialog is open.
+  if (entries.length === 0) {
+    return (
+      <Box flexDirection="column">
+        <Box paddingX={1}>
+          <Text bold>Local agents</Text>
+          <Text color={theme.text.secondary}> (0)</Text>
+        </Box>
+        <Box paddingX={1}>
+          <Text color={theme.text.secondary}>No tasks currently running</Text>
+        </Box>
+      </Box>
+    );
+  }
+
+  // Window entries around selectedIndex. When the list fits, show
+  // everything; otherwise centre the selection and clamp to the ends.
+  // "+N more above/below" lines consume one row each on the respective
+  // side, so subtract them from the available row budget.
+  const fits = entries.length <= maxRows;
+  const effectiveRows = Math.max(1, fits ? maxRows : maxRows - 2);
+  const windowStart = fits
+    ? 0
+    : Math.max(
+        0,
+        Math.min(
+          selectedIndex - Math.floor(effectiveRows / 2),
+          entries.length - effectiveRows,
+        ),
+      );
+  const windowEnd = fits
+    ? entries.length
+    : Math.min(entries.length, windowStart + effectiveRows);
+  const hiddenAbove = windowStart;
+  const hiddenBelow = entries.length - windowEnd;
+  const visible = entries.slice(windowStart, windowEnd);
+
+  return (
+    <Box flexDirection="column">
+      <Box paddingX={1}>
+        <Text bold>Local agents</Text>
+        <Text color={theme.text.secondary}> ({entries.length})</Text>
+      </Box>
+      <Box flexDirection="column">
+        {hiddenAbove > 0 && (
+          <Box paddingX={1}>
+            <Text color={theme.text.secondary}>
+              {`  ^ ${hiddenAbove} more above`}
+            </Text>
+          </Box>
+        )}
+        {visible.map((entry, visibleIdx) => {
+          const idx = windowStart + visibleIdx;
+          const isSelected = idx === selectedIndex;
+          const terminal = terminalStatusPresentation(entry.status);
+          const labelColor = isSelected
+            ? theme.text.accent
+            : terminal
+              ? terminal.labelColor
+              : theme.text.primary;
+          return (
+            <Box key={entry.agentId} flexDirection="row" paddingX={1}>
+              <Text color={isSelected ? theme.text.accent : undefined}>
+                {isSelected ? '> ' : '  '}
+              </Text>
+              <Text color={labelColor}>{rowLabel(entry)}</Text>
+            </Box>
+          );
+        })}
+        {hiddenBelow > 0 && (
+          <Box paddingX={1}>
+            <Text color={theme.text.secondary}>
+              {`  v ${hiddenBelow} more below`}
+            </Text>
+          </Box>
+        )}
+      </Box>
+    </Box>
+  );
+};
+
+// ─── Detail mode ───────────────────────────────────────────
+
+const DetailBody: React.FC<{
+  entry: BackgroundTaskEntry;
+  maxHeight: number;
+  maxWidth: number;
+}> = ({ entry, maxHeight, maxWidth }) => {
+  const title = `${entry.subagentType ?? 'Agent'} \u203A ${rowLabel(entry)}`;
+
+  const terminal = terminalStatusPresentation(entry.status);
+  const dimSubtitleParts: string[] = [elapsedFor(entry)];
+  if (entry.stats?.totalTokens) {
+    dimSubtitleParts.push(
+      `${formatTokenCount(entry.stats.totalTokens)} tokens`,
+    );
+  }
+  if (entry.stats?.toolUses !== undefined) {
+    dimSubtitleParts.push(
+      `${entry.stats.toolUses} tool${entry.stats.toolUses === 1 ? '' : 's'}`,
+    );
+  }
+
+  // Registry stores activities newest-last; keep that order so the live
+  // row sits at the bottom of the Progress block. Cap at 5 in case the
+  // registry ever raises its buffer.
+  const activities = (entry.recentActivities ?? []).slice(-5);
+  const hasError = entry.status === 'failed' && Boolean(entry.error);
+
+  // Prompt: show at most 5 newline-delimited segments, each row truncated
+  // to one visual line. Append an ellipsis if the source had more.
+  const promptLines = entry.prompt ? entry.prompt.split('\n') : [];
+  const visiblePromptLines = promptLines.slice(0, 5);
+  const promptTruncated = promptLines.length > visiblePromptLines.length;
+  if (promptTruncated && visiblePromptLines.length > 0) {
+    const lastIdx = visiblePromptLines.length - 1;
+    visiblePromptLines[lastIdx] =
+      `${visiblePromptLines[lastIdx].trimEnd()}\u2026`;
+  }
+
+  return (
+    <MaxSizedBox
+      maxHeight={maxHeight}
+      maxWidth={maxWidth}
+      overflowDirection="bottom"
+    >
+      <Box>
+        <Text bold color={theme.text.accent}>
+          {title}
+        </Text>
+      </Box>
+      <Box>
+        {terminal && (
+          <Text color={terminal.color}>
+            {`${terminal.icon} ${STATUS_VERBS[entry.status]} \u00B7 `}
+          </Text>
+        )}
+        <Text color={theme.text.secondary}>
+          {dimSubtitleParts.join(' \u00B7 ')}
+        </Text>
+      </Box>
+
+      {activities.length > 0 && (
+        <Fragment>
+          <Box />
+          <Box>
+            <Text bold dimColor>
+              Progress
+            </Text>
+          </Box>
+          {activities.map((a, i) => {
+            const isLast = i === activities.length - 1;
+            // ASCII `>` is unambiguously one cell wide in every terminal
+            // font, so `> ` (2 cells) aligns with a two-space indent on the
+            // other rows. Unicode chevrons rendered with inconsistent width
+            // broke alignment in some fonts.
+            const prefix = isLast ? '> ' : '  ';
+            const label = truncateToWidth(
+              formatActivityLabel(a.name, a.description),
+              Math.max(0, maxWidth - stringWidth(prefix)),
+            );
+            return (
+              <Box key={`${a.at}-${i}`}>
+                <Text
+                  color={isLast ? theme.text.primary : theme.text.secondary}
+                >
+                  {prefix}
+                  {label}
+                </Text>
+              </Box>
+            );
+          })}
+        </Fragment>
+      )}
+
+      {visiblePromptLines.length > 0 && (
+        <Fragment>
+          <Box />
+          <Box>
+            <Text bold dimColor>
+              Prompt
+            </Text>
+          </Box>
+          {visiblePromptLines.map((line, i) => (
+            <Box key={`prompt-${i}`}>
+              <Text wrap="truncate-end">{line || ' '}</Text>
+            </Box>
+          ))}
+        </Fragment>
+      )}
+
+      {hasError && (
+        <Fragment>
+          <Box />
+          <Box>
+            <Text bold color={theme.status.error}>
+              Error
+            </Text>
+          </Box>
+          <Box>
+            <Text color={theme.status.error} wrap="wrap">
+              {entry.error}
+            </Text>
+          </Box>
+        </Fragment>
+      )}
+    </MaxSizedBox>
+  );
+};
+
+// ─── Dialog shell ──────────────────────────────────────────
+
+interface BackgroundTasksDialogProps {
+  availableTerminalHeight: number;
+  terminalWidth: number;
+}
+
+export const BackgroundTasksDialog: React.FC<BackgroundTasksDialogProps> = ({
+  availableTerminalHeight,
+  terminalWidth,
+}) => {
+  const { entries, selectedIndex, dialogOpen, dialogMode } =
+    useBackgroundTaskViewState();
+  const {
+    moveSelectionUp,
+    moveSelectionDown,
+    closeDialog,
+    enterDetail,
+    exitDetail,
+    cancelSelected,
+  } = useBackgroundTaskViewActions();
+  const config = useConfig();
+
+  // Progress and Prompt are each self-capped at 5 rows inside DetailBody,
+  // so the body never grows unbounded. Use all available height (minus the
+  // dialog chrome) as the MaxSizedBox budget so nothing gets clipped just
+  // because the terminal is short. Chrome = border(2) + title(1) + two
+  // marginTops(2) + hint(1) = 6 rows.
+  const detailContentHeight = Math.max(10, availableTerminalHeight - 6);
+  // Rounded border + paddingX=1 on the outer Box ≈ 4 horizontal cells.
+  const detailContentWidth = Math.max(10, terminalWidth - 4);
+
+  // List mode row budget: terminal height minus chrome (border 2 + title 1
+  // + two marginTops 2 + hint 1) and list header ("N active agents" 1 +
+  // marginTop 1 + "Local agents (N)" 1) = 10.
+  const listMaxRows = Math.max(3, availableTerminalHeight - 10);
+
+  const selectedEntry = useMemo(
+    () => entries[selectedIndex] ?? null,
+    [entries, selectedIndex],
+  );
+
+  // Tick up a local counter on each activity callback to force the
+  // detail body to re-render while it's open. The main status
+  // subscription in useBackgroundTaskView intentionally ignores
+  // activity updates so the Footer pill and AppContainer don't re-run
+  // on every tool call a background agent makes.
+  const [, bumpActivity] = useState(0);
+  const selectedAgentId = selectedEntry?.agentId;
+  useEffect(() => {
+    if (!dialogOpen || dialogMode !== 'detail' || !selectedAgentId) return;
+    const registry = config.getBackgroundTaskRegistry();
+    const onActivity = (entry: BackgroundTaskEntry) => {
+      if (entry.agentId !== selectedAgentId) return;
+      bumpActivity((n) => n + 1);
+    };
+    registry.setActivityChangeCallback(onActivity);
+    return () => registry.setActivityChangeCallback(undefined);
+  }, [dialogOpen, dialogMode, config, selectedAgentId]);
+
+  // Wall-clock tick for the running agent's duration. Activity callbacks
+  // fire when tools run, but duration needs to advance even when the agent
+  // is quietly thinking — otherwise the "33s" line freezes between tool uses.
+  const selectedStatus = selectedEntry?.status;
+  useEffect(() => {
+    if (
+      !dialogOpen ||
+      dialogMode !== 'detail' ||
+      !selectedAgentId ||
+      selectedStatus !== 'running'
+    )
+      return;
+    const id = setInterval(() => bumpActivity((n) => n + 1), 1000);
+    return () => clearInterval(id);
+  }, [dialogOpen, dialogMode, selectedAgentId, selectedStatus]);
+
+  // Auto-fallback to the list view when the selected agent reaches a
+  // terminal state while the user is watching it live. We only exit on
+  // the running → terminal *transition* — if the user deliberately
+  // opened an already-completed entry, they stay on it. The detail
+  // view itself renders terminal state fine, so this is a UX choice
+  // (return focus to the running roster) rather than a correctness fix.
+  const initialDetailStatusRef = useRef<{
+    agentId: string;
+    status: BackgroundTaskEntry['status'];
+  } | null>(null);
+  useEffect(() => {
+    if (!dialogOpen || dialogMode !== 'detail') {
+      initialDetailStatusRef.current = null;
+      return;
+    }
+    // Defensive fallback: if the viewed entry has somehow gone missing,
+    // drop back to the list so we don't sit on a "No entry to show" screen.
+    // Hitting this path now is unlikely — terminal entries stay in the
+    // registry — but the entry could disappear if the registry is reset.
+    if (!selectedAgentId) {
+      initialDetailStatusRef.current = null;
+      exitDetail();
+      return;
+    }
+    const seen = initialDetailStatusRef.current;
+    if (!seen || seen.agentId !== selectedAgentId) {
+      // First render in detail mode for this entry — remember the status we
+      // opened with so we can detect a transition away from 'running' later.
+      if (selectedStatus) {
+        initialDetailStatusRef.current = {
+          agentId: selectedAgentId,
+          status: selectedStatus,
+        };
+      }
+      return;
+    }
+    if (
+      seen.status === 'running' &&
+      selectedStatus &&
+      selectedStatus !== 'running'
+    ) {
+      exitDetail();
+    }
+  }, [dialogOpen, dialogMode, selectedAgentId, selectedStatus, exitDetail]);
+
+  useKeypress(
+    (key) => {
+      if (!dialogOpen) return;
+
+      if (dialogMode === 'list') {
+        if (key.name === 'up') {
+          moveSelectionUp();
+          return;
+        }
+        if (key.name === 'down') {
+          moveSelectionDown();
+          return;
+        }
+        if (key.name === 'return') {
+          if (selectedEntry) enterDetail();
+          return;
+        }
+        if (key.name === 'escape' || key.name === 'left') {
+          closeDialog();
+          return;
+        }
+        if (key.sequence === 'x' && !key.ctrl && !key.meta) {
+          cancelSelected();
+          return;
+        }
+        // Note: the "stop all agents" chord (ctrl+x ctrl+k in claw-code)
+        // is intentionally deferred. `useKeypress` fires per keystroke,
+        // so collapsing the chord to plain ctrl+k makes a destructive
+        // action too easy to trigger by mistake. Stop-all will land in
+        // a follow-up PR once proper chord handling is in place.
+        return;
+      }
+
+      // detail mode
+      if (key.name === 'left') {
+        exitDetail();
+        return;
+      }
+      if (
+        key.name === 'escape' ||
+        key.name === 'return' ||
+        key.name === 'space'
+      ) {
+        closeDialog();
+        return;
+      }
+      if (key.sequence === 'x' && !key.ctrl && !key.meta) {
+        cancelSelected();
+        return;
+      }
+    },
+    { isActive: dialogOpen },
+  );
+
+  if (!dialogOpen) return null;
+
+  // Hint footer — context-sensitive.
+  const hints: string[] = [];
+  if (dialogMode === 'list') {
+    hints.push('\u2191/\u2193 select', 'Enter view');
+    if (selectedEntry?.status === 'running') hints.push('x stop');
+    hints.push('\u2190/Esc close');
+  } else {
+    hints.push('\u2190 go back', 'Esc/Enter/Space close');
+    if (selectedEntry?.status === 'running') hints.push('x stop');
+  }
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={theme.border.default}
+      marginTop={1}
+      paddingX={1}
+    >
+      {dialogMode === 'list' && (
+        <Box paddingX={1}>
+          <Text bold color={theme.text.accent}>
+            Background tasks
+          </Text>
+        </Box>
+      )}
+      <Box marginTop={dialogMode === 'list' ? 1 : 0}>
+        {dialogMode === 'list' ? (
+          <ListBody
+            entries={entries}
+            selectedIndex={selectedIndex}
+            maxRows={listMaxRows}
+          />
+        ) : selectedEntry ? (
+          <DetailBody
+            entry={selectedEntry}
+            maxHeight={detailContentHeight}
+            maxWidth={detailContentWidth}
+          />
+        ) : (
+          <Box paddingX={1}>
+            <Text color={theme.text.secondary}>No entry to show.</Text>
+          </Box>
+        )}
+      </Box>
+      <Box marginTop={1} paddingX={1}>
+        <Text color={theme.text.secondary}>{hints.join(' \u00B7 ')}</Text>
+      </Box>
+    </Box>
+  );
+};
diff --git a/packages/cli/src/ui/components/background-view/BackgroundTasksPill.test.tsx b/packages/cli/src/ui/components/background-view/BackgroundTasksPill.test.tsx
new file mode 100644
index 000000000..ffdd53e8b
--- /dev/null
+++ b/packages/cli/src/ui/components/background-view/BackgroundTasksPill.test.tsx
@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { BackgroundTaskEntry } from '@qwen-code/qwen-code-core';
+import { getPillLabel } from './BackgroundTasksPill.js';
+
+function entry(overrides: Partial<BackgroundTaskEntry>): BackgroundTaskEntry {
+  return {
+    agentId: 'a',
+    description: 'desc',
+    status: 'running',
+    startTime: 0,
+    abortController: new AbortController(),
+    ...overrides,
+  };
+}
+
+describe('getPillLabel', () => {
+  it('uses singular form for one running agent', () => {
+    expect(getPillLabel([entry({ agentId: 'a' })])).toBe('1 local agent');
+  });
+
+  it('uses plural form for multiple running agents', () => {
+    expect(
+      getPillLabel([
+        entry({ agentId: 'a' }),
+        entry({ agentId: 'b' }),
+        entry({ agentId: 'c' }),
+      ]),
+    ).toBe('3 local agents');
+  });
+
+  it('counts only running entries when running and terminal mix', () => {
+    expect(
+      getPillLabel([
+        entry({ agentId: 'a', status: 'running' }),
+        entry({ agentId: 'b', status: 'completed' }),
+        entry({ agentId: 'c', status: 'cancelled' }),
+      ]),
+    ).toBe('1 local agent');
+  });
+
+  it('uses singular done form for one terminal-only entry', () => {
+    expect(getPillLabel([entry({ agentId: 'a', status: 'completed' })])).toBe(
+      '1 local agent done',
+    );
+  });
+
+  it('uses plural done form when all entries are terminal', () => {
+    expect(
+      getPillLabel([
+        entry({ agentId: 'a', status: 'completed' }),
+        entry({ agentId: 'b', status: 'failed' }),
+      ]),
+    ).toBe('2 local agents done');
+  });
+});
diff --git a/packages/cli/src/ui/components/background-view/BackgroundTasksPill.tsx b/packages/cli/src/ui/components/background-view/BackgroundTasksPill.tsx
new file mode 100644
index 000000000..fc8edfb4b
--- /dev/null
+++ b/packages/cli/src/ui/components/background-view/BackgroundTasksPill.tsx
@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { useCallback } from 'react';
+import { Text } from 'ink';
+import {
+  useBackgroundTaskViewState,
+  useBackgroundTaskViewActions,
+} from '../../contexts/BackgroundTaskViewContext.js';
+import { useKeypress, type Key } from '../../hooks/useKeypress.js';
+import { theme } from '../../semantic-colors.js';
+import type { BackgroundTaskEntry } from '@qwen-code/qwen-code-core';
+
+/**
+ * Pill label: counts running entries while any are running; once everything
+ * has terminated, switches to a "done" form so the pill still invites
+ * reopening the dialog to inspect final state.
+ */
+export function getPillLabel(entries: readonly BackgroundTaskEntry[]): string {
+  const running = entries.filter((e) => e.status === 'running').length;
+  if (running > 0) {
+    return running === 1 ? '1 local agent' : `${running} local agents`;
+  }
+  return entries.length === 1
+    ? '1 local agent done'
+    : `${entries.length} local agents done`;
+}
+
+export const BackgroundTasksPill: React.FC = () => {
+  const { entries, pillFocused } = useBackgroundTaskViewState();
+  const { openDialog, setPillFocused } = useBackgroundTaskViewActions();
+
+  const onKeypress = useCallback(
+    (key: Key) => {
+      if (key.name === 'return') {
+        openDialog();
+      } else if (key.name === 'up' || key.name === 'escape') {
+        setPillFocused(false);
+      } else if (
+        key.sequence &&
+        key.sequence.length === 1 &&
+        !key.ctrl &&
+        !key.meta
+      ) {
+        setPillFocused(false);
+      }
+    },
+    [openDialog, setPillFocused],
+  );
+
+  useKeypress(onKeypress, { isActive: pillFocused });
+
+  if (entries.length === 0) return null;
+
+  const label = getPillLabel(entries);
+
+  return (
+    <>
+      <Text color={theme.text.secondary}> · </Text>
+      <Text inverse={pillFocused}>{label}</Text>
+    </>
+  );
+};
diff --git a/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.test.tsx b/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.test.tsx
index e0180c3d1..88d0a9e24 100644
--- a/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.test.tsx
+++ b/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.test.tsx
@@ -36,7 +36,22 @@ function shellTool(
   };
 }
 
-describe('<CompactToolGroupDisplay />', () => {
+function toolCall(
+  overrides: Partial<IndividualToolCallDisplay> = {},
+): IndividualToolCallDisplay {
+  return {
+    callId: 'call-1',
+    name: 'read_file',
+    description: 'Read a.ts',
+    resultDisplay: 'file contents',
+    status: ToolCallStatus.Success,
+    confirmationDetails: undefined,
+    renderOutputAsMarkdown: false,
+    ...overrides,
+  };
+}
+
+describe('<CompactToolGroupDisplay /> — shell timeout plumbing', () => {
   beforeEach(() => {
     vi.useFakeTimers();
     vi.setSystemTime(NOW);
@@ -91,3 +106,76 @@ describe('<CompactToolGroupDisplay />', () => {
     expect(lastFrame()).not.toContain('timeout');
   });
 });
+
+describe('<CompactToolGroupDisplay /> — summary label', () => {
+  it('renders default header (active tool name + count) when no compactLabel is provided', () => {
+    const tools = [
+      toolCall({ callId: 'c1', name: 'read_file' }),
+      toolCall({ callId: 'c2', name: 'read_file' }),
+      toolCall({ callId: 'c3', name: 'grep' }),
+    ];
+    const { lastFrame } = render(
+      <CompactToolGroupDisplay toolCalls={tools} contentWidth={80} />,
+    );
+    const frame = lastFrame()!;
+    // Active tool = last in array when none are executing/confirming.
+    expect(frame).toContain('grep');
+    expect(frame).toContain('× 3');
+  });
+
+  it('replaces header with compactLabel when provided', () => {
+    const tools = [
+      toolCall({ callId: 'c1', name: 'read_file' }),
+      toolCall({ callId: 'c2', name: 'grep' }),
+    ];
+    const { lastFrame } = render(
+      <CompactToolGroupDisplay
+        toolCalls={tools}
+        contentWidth={80}
+        compactLabel="Searched in auth/"
+      />,
+    );
+    const frame = lastFrame()!;
+    expect(frame).toContain('Searched in auth/');
+    expect(frame).toContain('2 tools');
+    // The raw tool name should not appear as the primary header when a
+    // summary is shown.
+    expect(frame).not.toContain('read_file × 2');
+  });
+
+  it('shows tool count suffix only when multiple tools are present', () => {
+    const tools = [toolCall({ callId: 'c1', name: 'read_file' })];
+    const { lastFrame } = render(
+      <CompactToolGroupDisplay
+        toolCalls={tools}
+        contentWidth={80}
+        compactLabel="Read config.json"
+      />,
+    );
+    const frame = lastFrame()!;
+    expect(frame).toContain('Read config.json');
+    expect(frame).not.toContain('tools');
+  });
+
+  it('renders nothing for empty tool calls', () => {
+    const { lastFrame } = render(
+      <CompactToolGroupDisplay toolCalls={[]} contentWidth={80} />,
+    );
+    expect(lastFrame()).toBe('');
+  });
+
+  it('preserves default rendering for shell commands without label', () => {
+    const tools = [
+      toolCall({
+        callId: 'c1',
+        name: 'Bash',
+        description: 'ls -la',
+      }),
+    ];
+    const { lastFrame } = render(
+      <CompactToolGroupDisplay toolCalls={tools} contentWidth={80} />,
+    );
+    expect(lastFrame()).toContain('Bash');
+    expect(lastFrame()).toContain('ls -la');
+  });
+});
diff --git a/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.tsx b/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.tsx
index 063a0c283..ea08396ac 100644
--- a/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.tsx
+++ b/packages/cli/src/ui/components/messages/CompactToolGroupDisplay.tsx
@@ -18,6 +18,13 @@ import { ToolElapsedTime } from '../shared/ToolElapsedTime.js';
 interface CompactToolGroupDisplayProps {
   toolCalls: IndividualToolCallDisplay[];
   contentWidth: number;
+  /**
+   * Optional LLM-generated label (~30 chars, git-commit-subject style) that
+   * replaces the "active tool name + count + description" header when
+   * present. Falls back to the default rendering while the label is still
+   * being generated or if generation was skipped/failed.
+   */
+  compactLabel?: string;
 }
 
 // Priority: Confirming > Executing > Error > Canceled > Pending > Success
@@ -66,9 +73,57 @@ function getShellTimeoutMs(
   return undefined;
 }
 
+/**
+ * Summary-label header: bold label + " · N tools" count when there are 2+
+ * tools in the batch. The count is intentionally suppressed for N=1 so
+ * single-tool batches don't read as `Read config.json · 1 tools`. Future
+ * edits: keep the `length > 1` guard, not `>= 1`.
+ */
+function renderSummaryHeader(label: string, count: number) {
+  return (
+    <>
+      <Text bold>{label}</Text>
+      {count > 1 ? (
+        <Text color={theme.text.secondary}>
+          {'  · '}
+          {count} tools
+        </Text>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * Default header: active tool name + " × N" count + first-line description.
+ * Same N=1 suffix suppression as `renderSummaryHeader`.
+ */
+function renderDefaultHeader(
+  activeToolName: string,
+  activeToolDescription: string,
+  count: number,
+) {
+  return (
+    <>
+      <Text bold>{activeToolName}</Text>
+      {count > 1 ? (
+        <Text color={theme.text.secondary}>
+          {' × '}
+          {count}
+        </Text>
+      ) : null}
+      {activeToolDescription ? (
+        <Text color={theme.text.secondary}>
+          {'  '}
+          {activeToolDescription}
+        </Text>
+      ) : null}
+    </>
+  );
+}
+
 export const CompactToolGroupDisplay: React.FC<
   CompactToolGroupDisplayProps
-> = ({ toolCalls, contentWidth }) => {
+> = ({ toolCalls, contentWidth, compactLabel }) => {
   if (toolCalls.length === 0) return null;
 
   const overallStatus = getOverallStatus(toolCalls);
@@ -103,24 +158,18 @@ export const CompactToolGroupDisplay: React.FC<
       borderColor={borderColor}
       gap={0}
     >
-      {/* Status line: icon + tool name + count + description + elapsed */}
+      {/* Status line: icon + (summary | tool name + description) + count + elapsed */}
       <Box flexDirection="row">
         <ToolStatusIndicator status={overallStatus} name={activeTool.name} />
         <Box flexGrow={1}>
           <Text wrap="truncate-end">
-            <Text bold>{activeTool.name}</Text>
-            {toolCalls.length > 1 ? (
-              <Text color={theme.text.secondary}>
-                {' × '}
-                {toolCalls.length}
-              </Text>
-            ) : null}
-            {activeToolDescription ? (
-              <Text color={theme.text.secondary}>
-                {'  '}
-                {activeToolDescription}
-              </Text>
-            ) : null}
+            {compactLabel
+              ? renderSummaryHeader(compactLabel, toolCalls.length)
+              : renderDefaultHeader(
+                  activeTool.name,
+                  activeToolDescription,
+                  toolCalls.length,
+                )}
           </Text>
         </Box>
         <ToolElapsedTime
diff --git a/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx b/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
index 2812c8baa..71385c533 100644
--- a/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
+++ b/packages/cli/src/ui/components/messages/ToolGroupMessage.tsx
@@ -44,6 +44,12 @@ interface ToolGroupMessageProps {
   /** Pre-computed count of read ops from managed-auto-memory files. */
   memoryReadCount?: number;
   isUserInitiated?: boolean;
+  /**
+   * Short LLM-generated label for this batch. Used in compact mode in place
+   * of the "active tool name × count" line. Undefined when summary
+   * generation is disabled, still in-flight, or failed.
+   */
+  compactLabel?: string;
 }
 
 // Main component renders the border and maps the tools using ToolMessage
@@ -57,6 +63,7 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
   memoryWriteCount,
   memoryReadCount,
   isUserInitiated,
+  compactLabel,
 }) => {
   const config = useConfig();
   const { compactMode } = useCompactMode();
@@ -139,6 +146,7 @@ export const ToolGroupMessage: React.FC<ToolGroupMessageProps> = ({
       <CompactToolGroupDisplay
         toolCalls={toolCalls}
         contentWidth={contentWidth}
+        compactLabel={compactLabel}
       />
     );
   }
diff --git a/packages/cli/src/ui/components/messages/ToolMessage.test.tsx b/packages/cli/src/ui/components/messages/ToolMessage.test.tsx
index a8e57c8a1..8e2fb0d33 100644
--- a/packages/cli/src/ui/components/messages/ToolMessage.test.tsx
+++ b/packages/cli/src/ui/components/messages/ToolMessage.test.tsx
@@ -547,6 +547,76 @@ describe('<ToolMessage />', () => {
     expect(output).toContain('line 30');
   });
 
+  it('pre-slices large non-shell string output before MaxSizedBox layout', () => {
+    const longString = Array.from(
+      { length: 5000 },
+      (_, i) => `line ${i + 1}`,
+    ).join('\n');
+    const { lastFrame } = renderWithContext(
+      <ToolMessage
+        {...baseProps}
+        name="some-other-tool"
+        resultDisplay={longString}
+        status={ToolCallStatus.Success}
+        availableTerminalHeight={12}
+      />,
+      StreamingState.Idle,
+    );
+    const output = lastFrame()!;
+
+    expect(output).toContain('... first 4995 lines hidden ...');
+    expect(output).not.toContain('line 4995');
+    expect(output).toContain('line 4996');
+    expect(output).toContain('line 4997');
+    expect(output).toContain('line 4998');
+    expect(output).toContain('line 4999');
+    expect(output).toContain('line 5000');
+  });
+
+  it('pre-slices single-line output by visual width before MaxSizedBox layout', () => {
+    const longSingleLine = Array.from({ length: 1000 }, (_, i) =>
+      String(i % 10),
+    ).join('');
+    const { lastFrame } = renderWithContext(
+      <ToolMessage
+        {...baseProps}
+        name="some-other-tool"
+        contentWidth={20}
+        resultDisplay={longSingleLine}
+        status={ToolCallStatus.Success}
+        availableTerminalHeight={12}
+      />,
+      StreamingState.Idle,
+    );
+    const output = lastFrame()!;
+
+    expect(output).toMatch(/\.\.\. first \d+ lin/);
+    expect(output).not.toContain(longSingleLine);
+    expect(output).toContain(longSingleLine.slice(-10));
+  });
+
+  it('does not pre-slice string output that exactly fits available height', () => {
+    const exactFitString = Array.from(
+      { length: 6 },
+      (_, i) => `line ${i + 1}`,
+    ).join('\n');
+    const { lastFrame } = renderWithContext(
+      <ToolMessage
+        {...baseProps}
+        name="some-other-tool"
+        resultDisplay={exactFitString}
+        status={ToolCallStatus.Success}
+        availableTerminalHeight={12}
+      />,
+      StreamingState.Idle,
+    );
+    const output = lastFrame()!;
+
+    expect(output).not.toContain('lines hidden');
+    expect(output).toContain('line 1');
+    expect(output).toContain('line 6');
+  });
+
   it.each([
     ['negative', -1],
     ['fractional', 1.5],
diff --git a/packages/cli/src/ui/components/messages/ToolMessage.tsx b/packages/cli/src/ui/components/messages/ToolMessage.tsx
index 64f616cfc..417c00010 100644
--- a/packages/cli/src/ui/components/messages/ToolMessage.tsx
+++ b/packages/cli/src/ui/components/messages/ToolMessage.tsx
@@ -12,7 +12,7 @@ import { DiffRenderer } from './DiffRenderer.js';
 import { MarkdownDisplay } from '../../utils/MarkdownDisplay.js';
 import { AnsiOutputText, ShellStatsBar } from '../AnsiOutput.js';
 import type { ShellStatsBarProps } from '../AnsiOutput.js';
-import { MaxSizedBox } from '../shared/MaxSizedBox.js';
+import { MaxSizedBox, MINIMUM_MAX_HEIGHT } from '../shared/MaxSizedBox.js';
 import { TodoDisplay } from '../TodoDisplay.js';
 import type {
   TodoResultDisplay,
@@ -31,6 +31,7 @@ import { theme } from '../../semantic-colors.js';
 import { useSettings } from '../../contexts/SettingsContext.js';
 import type { LoadedSettings } from '../../../config/settings.js';
 import { useCompactMode } from '../../contexts/CompactModeContext.js';
+import { getCachedStringWidth, toCodePoints } from '../../utils/textUtils.js';
 
 import {
   ToolStatusIndicator,
@@ -48,6 +49,65 @@ const DEFAULT_SHELL_OUTPUT_MAX_LINES = 5;
 const MAXIMUM_RESULT_DISPLAY_CHARACTERS = 1000000;
 export type TextEmphasis = 'high' | 'medium' | 'low';
 
+function sliceTextForMaxHeight(
+  text: string,
+  maxHeight: number | undefined,
+  maxWidth: number,
+): { text: string; hiddenLinesCount: number } {
+  if (maxHeight === undefined) {
+    return { text, hiddenLinesCount: 0 };
+  }
+
+  const targetMaxHeight = Math.max(Math.round(maxHeight), MINIMUM_MAX_HEIGHT);
+  const visibleContentHeight = targetMaxHeight - 1;
+  const visualWidth = Math.max(1, Math.floor(maxWidth));
+  const visibleLines: string[] = [];
+  let visualLineCount = 0;
+  let currentLine = '';
+  let currentLineWidth = 0;
+
+  const appendVisibleLine = (line: string) => {
+    visualLineCount += 1;
+    visibleLines.push(line);
+    if (visibleLines.length > visibleContentHeight) {
+      visibleLines.shift();
+    }
+  };
+
+  const flushCurrentLine = () => {
+    appendVisibleLine(currentLine);
+    currentLine = '';
+    currentLineWidth = 0;
+  };
+
+  for (const char of toCodePoints(text)) {
+    if (char === '\n') {
+      flushCurrentLine();
+      continue;
+    }
+
+    const charWidth = Math.max(getCachedStringWidth(char), 1);
+    if (currentLineWidth > 0 && currentLineWidth + charWidth > visualWidth) {
+      flushCurrentLine();
+    }
+
+    currentLine += char;
+    currentLineWidth += charWidth;
+  }
+
+  flushCurrentLine();
+
+  if (visualLineCount <= targetMaxHeight) {
+    return { text, hiddenLinesCount: 0 };
+  }
+
+  const hiddenLinesCount = visualLineCount - visibleContentHeight;
+  return {
+    text: visibleLines.join('\n'),
+    hiddenLinesCount,
+  };
+}
+
 type DisplayRendererResult =
   | { type: 'none' }
   | { type: 'todo'; data: TodoResultDisplay }
@@ -234,11 +294,21 @@ const StringResultRenderer: React.FC<{
     );
   }
 
+  const sliced = sliceTextForMaxHeight(
+    displayData,
+    availableHeight,
+    childWidth,
+  );
+
   return (
-    <MaxSizedBox maxHeight={availableHeight} maxWidth={childWidth}>
+    <MaxSizedBox
+      maxHeight={availableHeight}
+      maxWidth={childWidth}
+      additionalHiddenLinesCount={sliced.hiddenLinesCount}
+    >
       <Box>
         <Text wrap="wrap" color={theme.text.primary}>
-          {displayData}
+          {sliced.text}
         </Text>
       </Box>
     </MaxSizedBox>
diff --git a/packages/cli/src/ui/components/shared/MultiSelect.tsx b/packages/cli/src/ui/components/shared/MultiSelect.tsx
index b910430ba..7191d4fd6 100644
--- a/packages/cli/src/ui/components/shared/MultiSelect.tsx
+++ b/packages/cli/src/ui/components/shared/MultiSelect.tsx
@@ -19,9 +19,10 @@ export interface MultiSelectItem<T> extends SelectionListItem<T> {
 export interface MultiSelectProps<T> {
   items: Array<MultiSelectItem<T>>;
   initialIndex?: number;
-  initialSelectedKeys?: string[];
+  selectedKeys?: string[];
   onConfirm: (selectedValues: T[]) => void;
   onChange?: (selectedValues: T[]) => void;
+  onSelectedKeysChange?: (selectedKeys: string[]) => void;
   onHighlight?: (value: T) => void;
   isFocused?: boolean;
   showNumbers?: boolean;
@@ -43,32 +44,18 @@ function getSelectedValues<T>(
 export function MultiSelect<T>({
   items,
   initialIndex = 0,
-  initialSelectedKeys = EMPTY_SELECTED_KEYS,
+  selectedKeys = EMPTY_SELECTED_KEYS,
   onConfirm,
   onChange,
+  onSelectedKeysChange,
   onHighlight,
   isFocused = true,
   showNumbers = true,
   showScrollArrows = false,
   maxItemsToShow = 10,
 }: MultiSelectProps<T>): React.JSX.Element {
-  const [selectedKeys, setSelectedKeys] = useState<Set<string>>(
-    () => new Set(initialSelectedKeys),
-  );
   const [scrollOffset, setScrollOffset] = useState(0);
-
-  useEffect(() => {
-    setSelectedKeys((prev) => {
-      const next = new Set(initialSelectedKeys);
-      if (
-        prev.size === next.size &&
-        Array.from(next).every((key) => prev.has(key))
-      ) {
-        return prev;
-      }
-      return next;
-    });
-  }, [initialSelectedKeys]);
+  const selectedKeySet = useMemo(() => new Set(selectedKeys), [selectedKeys]);
 
   const { activeIndex } = useSelectionList({
     items,
@@ -81,7 +68,7 @@ export function MultiSelect<T>({
     showNumbers: false,
     onHighlight,
     onSelect: () => {
-      onConfirm(getSelectedValues(items, selectedKeys));
+      onConfirm(getSelectedValues(items, selectedKeySet));
     },
   });
 
@@ -92,23 +79,19 @@ export function MultiSelect<T>({
         return;
       }
 
-      setSelectedKeys((prev) => {
-        const next = new Set(prev);
-        if (next.has(item.key)) {
-          next.delete(item.key);
-        } else {
-          next.add(item.key);
-        }
-        return next;
-      });
+      const next = new Set(selectedKeySet);
+      if (next.has(item.key)) {
+        next.delete(item.key);
+      } else {
+        next.add(item.key);
+      }
+      const nextKeys = Array.from(next);
+      onSelectedKeysChange?.(nextKeys);
+      onChange?.(getSelectedValues(items, next));
     },
-    [items],
+    [items, onChange, onSelectedKeysChange, selectedKeySet],
   );
 
-  useEffect(() => {
-    onChange?.(getSelectedValues(items, selectedKeys));
-  }, [items, selectedKeys, onChange]);
-
   useKeypress(
     (key) => {
       if (key.name === 'space' || key.sequence === ' ') {
@@ -152,7 +135,7 @@ export function MultiSelect<T>({
       {visibleItems.map((item, index) => {
         const itemIndex = scrollOffset + index;
         const isActive = activeIndex === itemIndex;
-        const isChecked = selectedKeys.has(item.key);
+        const isChecked = selectedKeySet.has(item.key);
 
         const itemNumberText = `${String(itemIndex + 1).padStart(
           numberColumnWidth,
diff --git a/packages/cli/src/ui/components/shared/TextInput.tsx b/packages/cli/src/ui/components/shared/TextInput.tsx
index 3e7b62258..b77848d0e 100644
--- a/packages/cli/src/ui/components/shared/TextInput.tsx
+++ b/packages/cli/src/ui/components/shared/TextInput.tsx
@@ -22,7 +22,7 @@ export interface TextInputProps {
   onChange: (text: string) => void;
   onSubmit?: () => void;
   /** Called when Tab is pressed; if provided, prevents the default tab-insertion behaviour. */
-  onTab?: () => void;
+  onTab?: (key: Key) => void;
   /** Called when ↑ is pressed; if provided, prevents cursor-up in the buffer. */
   onUp?: () => void;
   /** Called when ↓ is pressed; if provided, prevents cursor-down in the buffer. */
@@ -80,7 +80,7 @@ export function TextInput({
       // Tab completion: delegate to caller instead of inserting a tab character
       // During paste, let tab through as literal content (e.g. Excel tab-separated data)
       if (key.name === 'tab' && !key.paste) {
-        onTab?.();
+        onTab?.(key);
         return;
       }
 
diff --git a/packages/cli/src/ui/components/subagents/runtime/AgentExecutionDisplay.tsx b/packages/cli/src/ui/components/subagents/runtime/AgentExecutionDisplay.tsx
index c0a7d6506..a82d0fe1e 100644
--- a/packages/cli/src/ui/components/subagents/runtime/AgentExecutionDisplay.tsx
+++ b/packages/cli/src/ui/components/subagents/runtime/AgentExecutionDisplay.tsx
@@ -73,6 +73,10 @@ const getStatusText = (status: AgentResultDisplay['status']) => {
   }
 };
 
+const BackgroundManageHint: React.FC = () => (
+  <Text color={theme.text.secondary}> (↓ to manage)</Text>
+);
+
 const MAX_TOOL_CALLS = 5;
 const MAX_TASK_PROMPT_LINES = 5;
 
@@ -150,6 +154,7 @@ export const AgentExecutionDisplay: React.FC<AgentExecutionDisplayProps> = ({
             </Text>
             <StatusDot status={data.status} />
             <StatusIndicator status={data.status} />
+            {data.status === 'background' && <BackgroundManageHint />}
           </Box>
         )}
 
@@ -231,6 +236,7 @@ export const AgentExecutionDisplay: React.FC<AgentExecutionDisplayProps> = ({
         </Text>
         <StatusDot status={data.status} />
         <StatusIndicator status={data.status} />
+        {data.status === 'background' && <BackgroundManageHint />}
       </Box>
 
       {/* Task description */}
diff --git a/packages/cli/src/ui/contexts/BackgroundTaskViewContext.tsx b/packages/cli/src/ui/contexts/BackgroundTaskViewContext.tsx
new file mode 100644
index 000000000..cdb6a3605
--- /dev/null
+++ b/packages/cli/src/ui/contexts/BackgroundTaskViewContext.tsx
@@ -0,0 +1,214 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * BackgroundTaskViewContext — React state for the Background tasks
+ * dialog. Subscription plumbing (registry callbacks → entries) lives in
+ * `useBackgroundTaskView`, invoked once here so it owns the single-slot
+ * `setStatusChangeCallback` for the TUI's lifetime.
+ */
+
+import {
+  createContext,
+  useContext,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+import {
+  type BackgroundTaskEntry,
+  type Config,
+} from '@qwen-code/qwen-code-core';
+import { useBackgroundTaskView } from '../hooks/useBackgroundTaskView.js';
+
+// ─── Types ──────────────────────────────────────────────────
+
+export type BackgroundDialogMode = 'closed' | 'list' | 'detail';
+
+export interface BackgroundTaskViewState {
+  /** Live snapshot of every background agent entry, ordered by startTime. */
+  entries: readonly BackgroundTaskEntry[];
+  /** Index into `entries` for the currently focused row (0-based). */
+  selectedIndex: number;
+  /** `'closed'` when the overlay isn't mounted; otherwise the active mode. */
+  dialogMode: BackgroundDialogMode;
+  /** Convenience boolean: `dialogMode !== 'closed'`. */
+  dialogOpen: boolean;
+  /**
+   * True when the footer pill owns keyboard focus (highlighted, awaiting
+   * Enter to open the dialog). Mirrors the Arena tab-bar focus pattern.
+   */
+  pillFocused: boolean;
+}
+
+export interface BackgroundTaskViewActions {
+  moveSelectionUp(): boolean;
+  moveSelectionDown(): boolean;
+  openDialog(): void;
+  closeDialog(): void;
+  enterDetail(): void;
+  exitDetail(): void;
+  /** Cancel the currently selected entry (no-op if not running). */
+  cancelSelected(): void;
+  setPillFocused(focused: boolean): void;
+}
+
+// ─── Context ────────────────────────────────────────────────
+
+export const BackgroundTaskViewStateContext =
+  createContext<BackgroundTaskViewState | null>(null);
+export const BackgroundTaskViewActionsContext =
+  createContext<BackgroundTaskViewActions | null>(null);
+
+// ─── Defaults (used when no provider is mounted) ────────────
+
+const DEFAULT_STATE: BackgroundTaskViewState = {
+  entries: [],
+  selectedIndex: 0,
+  dialogMode: 'closed',
+  dialogOpen: false,
+  pillFocused: false,
+};
+
+const noop = () => {};
+const noopBool = () => false;
+
+const DEFAULT_ACTIONS: BackgroundTaskViewActions = {
+  moveSelectionUp: noopBool,
+  moveSelectionDown: noopBool,
+  openDialog: noop,
+  closeDialog: noop,
+  enterDetail: noop,
+  exitDetail: noop,
+  cancelSelected: noop,
+  setPillFocused: noop,
+};
+
+// ─── Hooks ──────────────────────────────────────────────────
+
+export function useBackgroundTaskViewState(): BackgroundTaskViewState {
+  return useContext(BackgroundTaskViewStateContext) ?? DEFAULT_STATE;
+}
+
+export function useBackgroundTaskViewActions(): BackgroundTaskViewActions {
+  return useContext(BackgroundTaskViewActionsContext) ?? DEFAULT_ACTIONS;
+}
+
+// ─── Provider ───────────────────────────────────────────────
+
+interface BackgroundTaskViewProviderProps {
+  config?: Config;
+  children: React.ReactNode;
+}
+
+export function BackgroundTaskViewProvider({
+  config,
+  children,
+}: BackgroundTaskViewProviderProps) {
+  const { entries } = useBackgroundTaskView(config ?? null);
+
+  const [rawSelectedIndex, setRawSelectedIndex] = useState(0);
+  const [dialogMode, setDialogMode] = useState<BackgroundDialogMode>('closed');
+  const [pillFocused, setPillFocused] = useState(false);
+  const dialogOpen = dialogMode !== 'closed';
+  const hasEntries = entries.length > 0;
+
+  // Drop stale pill focus once the pill itself unmounts — i.e., when the
+  // registry is empty. The pill stays rendered while terminal entries
+  // exist (so the user can reopen the dialog post-termination), so we
+  // intentionally do *not* drop focus on the running → terminal flip.
+  useEffect(() => {
+    if (pillFocused && !hasEntries) setPillFocused(false);
+  }, [pillFocused, hasEntries]);
+
+  // rawSelectedIndex can fall out of range when entries shrink; clamp on read.
+  const selectedIndex =
+    entries.length === 0
+      ? 0
+      : Math.min(Math.max(0, rawSelectedIndex), entries.length - 1);
+
+  const moveSelectionUp = useCallback((): boolean => {
+    if (selectedIndex <= 0) return false;
+    setRawSelectedIndex(selectedIndex - 1);
+    return true;
+  }, [selectedIndex]);
+
+  const moveSelectionDown = useCallback((): boolean => {
+    if (entries.length === 0) return false;
+    if (selectedIndex >= entries.length - 1) return false;
+    setRawSelectedIndex(selectedIndex + 1);
+    return true;
+  }, [entries.length, selectedIndex]);
+
+  const openDialog = useCallback(() => {
+    setDialogMode('list');
+    setPillFocused(false);
+  }, []);
+
+  const closeDialog = useCallback(() => {
+    setDialogMode('closed');
+  }, []);
+
+  const enterDetail = useCallback(() => {
+    if (entries.length === 0) return;
+    setDialogMode('detail');
+  }, [entries.length]);
+
+  const exitDetail = useCallback(() => {
+    setDialogMode('list');
+  }, []);
+
+  const cancelSelected = useCallback(() => {
+    if (!config) return;
+    const target = entries[selectedIndex];
+    if (!target) return;
+    // cancel() is a no-op for non-running entries, so no pre-check here.
+    config.getBackgroundTaskRegistry().cancel(target.agentId);
+  }, [config, entries, selectedIndex]);
+
+  const state: BackgroundTaskViewState = useMemo(
+    () => ({
+      entries,
+      selectedIndex,
+      dialogMode,
+      dialogOpen,
+      pillFocused,
+    }),
+    [entries, selectedIndex, dialogMode, dialogOpen, pillFocused],
+  );
+
+  const actions: BackgroundTaskViewActions = useMemo(
+    () => ({
+      moveSelectionUp,
+      moveSelectionDown,
+      openDialog,
+      closeDialog,
+      enterDetail,
+      exitDetail,
+      cancelSelected,
+      setPillFocused,
+    }),
+    [
+      moveSelectionUp,
+      moveSelectionDown,
+      openDialog,
+      closeDialog,
+      enterDetail,
+      exitDetail,
+      cancelSelected,
+      setPillFocused,
+    ],
+  );
+
+  return (
+    <BackgroundTaskViewStateContext.Provider value={state}>
+      <BackgroundTaskViewActionsContext.Provider value={actions}>
+        {children}
+      </BackgroundTaskViewActionsContext.Provider>
+    </BackgroundTaskViewStateContext.Provider>
+  );
+}
diff --git a/packages/cli/src/ui/contexts/UIActionsContext.tsx b/packages/cli/src/ui/contexts/UIActionsContext.tsx
index 5aac4e66a..052ff5491 100644
--- a/packages/cli/src/ui/contexts/UIActionsContext.tsx
+++ b/packages/cli/src/ui/contexts/UIActionsContext.tsx
@@ -17,7 +17,7 @@ import {
 } from '@qwen-code/qwen-code-core';
 import { type SettingScope } from '../../config/settings.js';
 import { type AlibabaStandardRegion } from '../../constants/alibabaStandardApiKey.js';
-import type { AuthState } from '../types.js';
+import type { AuthState, HistoryItem } from '../types.js';
 import { type ArenaDialogType } from '../hooks/useArenaCommand.js';
 // OpenAICredentials type (previously imported from OpenAIKeyPrompt)
 export interface OpenAICredentials {
@@ -52,6 +52,25 @@ export interface UIActions {
     region: AlibabaStandardRegion,
     modelIdsInput: string,
   ) => Promise<void>;
+  handleOpenRouterSubmit: () => Promise<void>;
+  handleCustomApiKeySubmit: (
+    protocol:
+      | AuthType.USE_OPENAI
+      | AuthType.USE_ANTHROPIC
+      | AuthType.USE_GEMINI,
+    baseUrl: string,
+    apiKey: string,
+    modelIdsInput: string,
+    generationConfig?: {
+      enableThinking?: boolean;
+      multimodal?: {
+        image?: boolean;
+        video?: boolean;
+        audio?: boolean;
+      };
+      maxTokens?: number;
+    },
+  ) => Promise<void>;
   setAuthState: (state: AuthState) => void;
   onAuthError: (error: string | null) => void;
   cancelAuthentication: () => void;
@@ -64,6 +83,8 @@ export interface UIActions {
   closeMemoryDialog: () => void;
   closeModelDialog: () => void;
   openModelDialog: (options?: { fastModelMode?: boolean }) => void;
+  openManageModelsDialog: () => void;
+  closeManageModelsDialog: () => void;
   openArenaDialog: (type: Exclude<ArenaDialogType, null>) => void;
   closeArenaDialog: () => void;
   handleArenaModelsSelected?: (models: string[]) => void;
@@ -110,6 +131,10 @@ export interface UIActions {
   closeFeedbackDialog: () => void;
   temporaryCloseFeedbackDialog: () => void;
   submitFeedback: (rating: number) => void;
+  // Rewind selector
+  openRewindSelector: () => void;
+  closeRewindSelector: () => void;
+  handleRewindConfirm: (userItem: HistoryItem) => void;
 }
 
 export const UIActionsContext = createContext<UIActions | null>(null);
diff --git a/packages/cli/src/ui/contexts/UIStateContext.tsx b/packages/cli/src/ui/contexts/UIStateContext.tsx
index b2450ec2c..c987d99cd 100644
--- a/packages/cli/src/ui/contexts/UIStateContext.tsx
+++ b/packages/cli/src/ui/contexts/UIStateContext.tsx
@@ -17,7 +17,8 @@ import type {
   SettingInputRequest,
   PluginChoiceRequest,
 } from '../types.js';
-import type { QwenAuthState } from '../hooks/useQwenAuth.js';
+import type { TodoItem } from '../components/TodoDisplay.js';
+import type { ExternalAuthState, QwenAuthState } from '../hooks/useQwenAuth.js';
 import type { CommandContext, SlashCommand } from '../commands/types.js';
 import type { TextBuffer } from '../components/shared/text-buffer.js';
 import type {
@@ -47,6 +48,7 @@ export interface UIState {
   authError: string | null;
   isAuthDialogOpen: boolean;
   pendingAuthType: AuthType | undefined;
+  externalAuthState: ExternalAuthState | null;
   // Qwen OAuth state
   qwenAuthState: QwenAuthState;
   editorError: string | null;
@@ -57,6 +59,7 @@ export interface UIState {
   isMemoryDialogOpen: boolean;
   isModelDialogOpen: boolean;
   isFastModelMode: boolean;
+  isManageModelsDialogOpen: boolean;
   isTrustDialogOpen: boolean;
   activeArenaDialog: ArenaDialogType;
   isPermissionsDialogOpen: boolean;
@@ -110,6 +113,7 @@ export interface UIState {
   staticExtraHeight: number;
   dialogsVisible: boolean;
   pendingHistoryItems: HistoryItemWithoutId[];
+  stickyTodos: TodoItem[] | null;
   btwItem: HistoryItemBtw | null;
   setBtwItem: (item: HistoryItemBtw | null) => void;
   cancelBtw: () => void;
@@ -158,6 +162,9 @@ export interface UIState {
   promptSuggestion: string | null;
   /** Dismiss prompt suggestion (clears state, aborts speculation) */
   dismissPromptSuggestion: () => void;
+  // Rewind selector
+  isRewindSelectorOpen: boolean;
+  rewindEscPending: boolean;
 }
 
 export const UIStateContext = createContext<UIState | null>(null);
diff --git a/packages/cli/src/ui/hooks/slashCommandProcessor.test.ts b/packages/cli/src/ui/hooks/slashCommandProcessor.test.ts
index 0893c8e28..7b963cfd2 100644
--- a/packages/cli/src/ui/hooks/slashCommandProcessor.test.ts
+++ b/packages/cli/src/ui/hooks/slashCommandProcessor.test.ts
@@ -501,7 +501,7 @@ describe('useSlashCommandProcessor', () => {
       );
     });
 
-    it('should strip thoughts when handling "load_history" action', async () => {
+    it('should preserve thoughts when handling "load_history" action', async () => {
       const mockClient = {
         setHistory: vi.fn(),
         stripThoughtsFromHistory: vi.fn(),
@@ -531,7 +531,7 @@ describe('useSlashCommandProcessor', () => {
       });
 
       expect(mockClient.setHistory).toHaveBeenCalledTimes(1);
-      expect(mockClient.stripThoughtsFromHistory).toHaveBeenCalledWith();
+      expect(mockClient.stripThoughtsFromHistory).not.toHaveBeenCalled();
     });
 
     it('should handle a "quit" action', async () => {
diff --git a/packages/cli/src/ui/hooks/slashCommandProcessor.ts b/packages/cli/src/ui/hooks/slashCommandProcessor.ts
index 135ec7d11..f9d685b78 100644
--- a/packages/cli/src/ui/hooks/slashCommandProcessor.ts
+++ b/packages/cli/src/ui/hooks/slashCommandProcessor.ts
@@ -86,6 +86,7 @@ interface SlashCommandProcessorActions {
   openMemoryDialog: () => void;
   openSettingsDialog: () => void;
   openModelDialog: (options?: { fastModelMode?: boolean }) => void;
+  openManageModelsDialog: () => void;
   openTrustDialog: () => void;
   openPermissionsDialog: () => void;
   openApprovalModeDialog: () => void;
@@ -101,6 +102,7 @@ interface SlashCommandProcessorActions {
   openExtensionsManagerDialog: () => void;
   openMcpDialog: () => void;
   openHooksDialog: () => void;
+  openRewindSelector: () => void;
 }
 
 /**
@@ -594,6 +596,9 @@ export const useSlashCommandProcessor = (
                     case 'fast-model':
                       actions.openModelDialog({ fastModelMode: true });
                       return { type: 'handled' };
+                    case 'manage-models':
+                      actions.openManageModelsDialog();
+                      return { type: 'handled' };
                     case 'trust':
                       actions.openTrustDialog();
                       return { type: 'handled' };
@@ -628,6 +633,9 @@ export const useSlashCommandProcessor = (
                     case 'extensions_manage':
                       actions.openExtensionsManagerDialog();
                       return { type: 'handled' };
+                    case 'rewind':
+                      actions.openRewindSelector();
+                      return { type: 'handled' };
                     case 'help':
                       return { type: 'handled' };
                     default: {
@@ -639,7 +647,6 @@ export const useSlashCommandProcessor = (
                   }
                 case 'load_history': {
                   config?.getGeminiClient()?.setHistory(result.clientHistory);
-                  config?.getGeminiClient()?.stripThoughtsFromHistory();
                   fullCommandContext.ui.clear();
                   result.history.forEach((item, index) => {
                     fullCommandContext.ui.addItem(item, index);
diff --git a/packages/cli/src/ui/hooks/useAttentionNotifications.test.ts b/packages/cli/src/ui/hooks/useAttentionNotifications.test.ts
index e8beb86fd..57ad80ac0 100644
--- a/packages/cli/src/ui/hooks/useAttentionNotifications.test.ts
+++ b/packages/cli/src/ui/hooks/useAttentionNotifications.test.ts
@@ -7,15 +7,28 @@
 import { renderHook } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { StreamingState } from '../types.js';
-import {
-  AttentionNotificationReason,
-  notifyTerminalAttention,
-} from '../../utils/attentionNotification.js';
 import {
   LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS,
   useAttentionNotifications,
 } from './useAttentionNotifications.js';
 import type { LoadedSettings } from '../../config/settings.js';
+import type { TerminalNotification } from './useTerminalNotification.js';
+import type { TrackedToolCall } from './useReactToolScheduler.js';
+
+vi.mock('../../services/notificationService.js', () => ({
+  sendNotification: vi.fn(),
+}));
+
+const { sendNotification: mockedSendNotification } = await import(
+  '../../services/notificationService.js'
+);
+
+const mockTerminal: TerminalNotification = {
+  notifyITerm2: vi.fn(),
+  notifyKitty: vi.fn(),
+  notifyGhostty: vi.fn(),
+  notifyBell: vi.fn(),
+};
 
 const mockSettings: LoadedSettings = {
   merged: {
@@ -33,19 +46,9 @@ const mockSettingsDisabled: LoadedSettings = {
   },
 } as LoadedSettings;
 
-vi.mock('../../utils/attentionNotification.js', () => ({
-  notifyTerminalAttention: vi.fn(),
-  AttentionNotificationReason: {
-    ToolApproval: 'tool_approval',
-    LongTaskComplete: 'long_task_complete',
-  },
-}));
-
-const mockedNotify = vi.mocked(notifyTerminalAttention);
-
 describe('useAttentionNotifications', () => {
   beforeEach(() => {
-    mockedNotify.mockReset();
+    vi.mocked(mockedSendNotification).mockReset();
   });
 
   const render = (
@@ -58,6 +61,7 @@ describe('useAttentionNotifications', () => {
           streamingState: StreamingState.Idle,
           elapsedTime: 0,
           settings: mockSettings,
+          terminal: mockTerminal,
           ...props,
         },
       },
@@ -72,12 +76,15 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.WaitingForConfirmation,
         elapsedTime: 0,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
-    expect(mockedNotify).toHaveBeenCalledWith(
-      AttentionNotificationReason.ToolApproval,
-      { enabled: true },
+    expect(mockedSendNotification).toHaveBeenCalledTimes(1);
+    expect(mockedSendNotification).toHaveBeenCalledWith(
+      expect.objectContaining({ title: 'Qwen Code' }),
+      mockTerminal,
+      true,
     );
   });
 
@@ -93,10 +100,11 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.WaitingForConfirmation,
         elapsedTime: 0,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
-    expect(mockedNotify).toHaveBeenCalledTimes(1);
+    expect(mockedSendNotification).toHaveBeenCalledTimes(1);
   });
 
   it('sends a notification when a long task finishes while unfocused', () => {
@@ -108,6 +116,7 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.Responding,
         elapsedTime: LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS + 5,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
@@ -117,13 +126,11 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.Idle,
         elapsedTime: 0,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
-    expect(mockedNotify).toHaveBeenCalledWith(
-      AttentionNotificationReason.LongTaskComplete,
-      { enabled: true },
-    );
+    expect(mockedSendNotification).toHaveBeenCalledTimes(1);
   });
 
   it('does not notify about long tasks when the CLI is focused', () => {
@@ -135,6 +142,7 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.Responding,
         elapsedTime: LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS + 2,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
@@ -144,13 +152,11 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.Idle,
         elapsedTime: 0,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
-    expect(mockedNotify).not.toHaveBeenCalledWith(
-      AttentionNotificationReason.LongTaskComplete,
-      expect.anything(),
-    );
+    expect(mockedSendNotification).not.toHaveBeenCalled();
   });
 
   it('does not treat short responses as long tasks', () => {
@@ -162,6 +168,7 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.Responding,
         elapsedTime: 5,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
@@ -171,13 +178,95 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.Idle,
         elapsedTime: 0,
         settings: mockSettings,
+        terminal: mockTerminal,
       },
     });
 
-    expect(mockedNotify).not.toHaveBeenCalled();
+    expect(mockedSendNotification).not.toHaveBeenCalled();
   });
 
-  it('does not notify when terminalBell setting is disabled', () => {
+  it('includes tool name in approval notification message', () => {
+    const { rerender } = render();
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.WaitingForConfirmation,
+        elapsedTime: 0,
+        settings: mockSettings,
+        terminal: mockTerminal,
+        pendingToolCalls: [
+          { status: 'awaiting_approval', request: { name: 'Bash' } },
+        ] as unknown as TrackedToolCall[],
+      },
+    });
+
+    expect(mockedSendNotification).toHaveBeenCalledTimes(1);
+    expect(mockedSendNotification).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Qwen Code needs your permission to use Bash',
+      }),
+      mockTerminal,
+      true,
+    );
+  });
+
+  it('uses fallback message when no pending tool call is found', () => {
+    const { rerender } = render();
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.WaitingForConfirmation,
+        elapsedTime: 0,
+        settings: mockSettings,
+        terminal: mockTerminal,
+        pendingToolCalls: [] as TrackedToolCall[],
+      },
+    });
+
+    expect(mockedSendNotification).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Qwen Code is waiting for your input',
+      }),
+      mockTerminal,
+      true,
+    );
+  });
+
+  it('sends "waiting for input" message for long task completion', () => {
+    const { rerender } = render();
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.Responding,
+        elapsedTime: LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS + 5,
+        settings: mockSettings,
+        terminal: mockTerminal,
+      },
+    });
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.Idle,
+        elapsedTime: 0,
+        settings: mockSettings,
+        terminal: mockTerminal,
+      },
+    });
+
+    expect(mockedSendNotification).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: 'Qwen Code is waiting for your input',
+      }),
+      mockTerminal,
+      true,
+    );
+  });
+
+  it('does not notify when terminalBell is disabled', () => {
     const { rerender } = render({
       settings: mockSettingsDisabled,
     });
@@ -188,12 +277,10 @@ describe('useAttentionNotifications', () => {
         streamingState: StreamingState.WaitingForConfirmation,
         elapsedTime: 0,
         settings: mockSettingsDisabled,
+        terminal: mockTerminal,
       },
     });
 
-    expect(mockedNotify).toHaveBeenCalledWith(
-      AttentionNotificationReason.ToolApproval,
-      { enabled: false },
-    );
+    expect(mockedSendNotification).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/cli/src/ui/hooks/useAttentionNotifications.ts b/packages/cli/src/ui/hooks/useAttentionNotifications.ts
index 5ef6f2913..4ab5ace5a 100644
--- a/packages/cli/src/ui/hooks/useAttentionNotifications.ts
+++ b/packages/cli/src/ui/hooks/useAttentionNotifications.ts
@@ -4,27 +4,30 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { useEffect, useRef } from 'react';
+import { useEffect, useMemo, useRef } from 'react';
 import { StreamingState } from '../types.js';
-import {
-  notifyTerminalAttention,
-  AttentionNotificationReason,
-} from '../../utils/attentionNotification.js';
 import type { LoadedSettings } from '../../config/settings.js';
 import type { Config } from '@qwen-code/qwen-code-core';
 import {
   fireNotificationHook,
   NotificationType,
 } from '@qwen-code/qwen-code-core';
+import type { TerminalNotification } from './useTerminalNotification.js';
+import type { TrackedToolCall } from './useReactToolScheduler.js';
+import { sendNotification } from '../../services/notificationService.js';
 
 export const LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS = 20;
 
+const NOTIFICATION_TITLE = 'Qwen Code';
+
 interface UseAttentionNotificationsOptions {
   isFocused: boolean;
   streamingState: StreamingState;
   elapsedTime: number;
   settings: LoadedSettings;
   config?: Config;
+  terminal: TerminalNotification;
+  pendingToolCalls?: TrackedToolCall[];
 }
 
 export const useAttentionNotifications = ({
@@ -33,33 +36,58 @@ export const useAttentionNotifications = ({
   elapsedTime,
   settings,
   config,
+  terminal,
+  pendingToolCalls,
 }: UseAttentionNotificationsOptions) => {
-  const terminalBellEnabled = settings?.merged?.general?.terminalBell ?? true;
+  const terminalBellEnabled: boolean =
+    (settings?.merged?.general?.terminalBell as boolean) ?? true;
+
   const awaitingNotificationSentRef = useRef(false);
   const respondingElapsedRef = useRef(0);
   const idleNotificationSentRef = useRef(false);
 
+  // Extract the awaiting tool name as a primitive so the effect doesn't
+  // re-fire on every render due to pendingToolCalls array identity changes.
+  const awaitingToolName = useMemo(() => {
+    const awaitingTool = pendingToolCalls?.find(
+      (tc) => tc.status === 'awaiting_approval',
+    );
+    return awaitingTool?.request.name;
+  }, [pendingToolCalls]);
+
   useEffect(() => {
     if (
       streamingState === StreamingState.WaitingForConfirmation &&
       !isFocused &&
-      !awaitingNotificationSentRef.current
+      !awaitingNotificationSentRef.current &&
+      terminalBellEnabled
     ) {
-      notifyTerminalAttention(AttentionNotificationReason.ToolApproval, {
-        enabled: terminalBellEnabled,
-      });
+      const message = awaitingToolName
+        ? `Qwen Code needs your permission to use ${awaitingToolName}`
+        : 'Qwen Code is waiting for your input';
+
+      sendNotification(
+        { message, title: NOTIFICATION_TITLE },
+        terminal,
+        terminalBellEnabled,
+      );
       awaitingNotificationSentRef.current = true;
     }
 
     if (streamingState !== StreamingState.WaitingForConfirmation || isFocused) {
       awaitingNotificationSentRef.current = false;
     }
-  }, [isFocused, streamingState, terminalBellEnabled]);
+  }, [
+    isFocused,
+    streamingState,
+    terminalBellEnabled,
+    terminal,
+    awaitingToolName,
+  ]);
 
   useEffect(() => {
     if (streamingState === StreamingState.Responding) {
       respondingElapsedRef.current = elapsedTime;
-      // Reset idle notification flag when responding
       idleNotificationSentRef.current = false;
       return;
     }
@@ -68,12 +96,16 @@ export const useAttentionNotifications = ({
       const wasLongTask =
         respondingElapsedRef.current >=
         LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS;
-      if (wasLongTask && !isFocused) {
-        notifyTerminalAttention(AttentionNotificationReason.LongTaskComplete, {
-          enabled: terminalBellEnabled,
-        });
+      if (wasLongTask && !isFocused && terminalBellEnabled) {
+        sendNotification(
+          {
+            message: 'Qwen Code is waiting for your input',
+            title: NOTIFICATION_TITLE,
+          },
+          terminal,
+          terminalBellEnabled,
+        );
       }
-      // Reset tracking for next task
       respondingElapsedRef.current = 0;
 
       // Fire idle_prompt notification hook when entering idle state
@@ -88,7 +120,6 @@ export const useAttentionNotifications = ({
             'Waiting for input',
           ).catch(() => {
             // Silently ignore errors - fireNotificationHook has internal error handling
-            // and notification hooks should not block the idle flow
           });
         }
         idleNotificationSentRef.current = true;
@@ -96,7 +127,13 @@ export const useAttentionNotifications = ({
       return;
     }
 
-    // Reset idle notification flag when in WaitingForConfirmation state
     idleNotificationSentRef.current = false;
-  }, [streamingState, elapsedTime, isFocused, terminalBellEnabled, config]);
+  }, [
+    streamingState,
+    elapsedTime,
+    isFocused,
+    terminalBellEnabled,
+    config,
+    terminal,
+  ]);
 };
diff --git a/packages/cli/src/ui/hooks/useBackgroundTaskView.ts b/packages/cli/src/ui/hooks/useBackgroundTaskView.ts
new file mode 100644
index 000000000..c55040b6e
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useBackgroundTaskView.ts
@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * useBackgroundTaskView — subscribes to the background task registry's
+ * status-change callback and maintains a reactive snapshot of every
+ * `BackgroundTaskEntry`, including terminal ones. Surfaces that only
+ * care about live work (the footer pill, the composer's Down-arrow
+ * route) filter for `running` themselves.
+ *
+ * Intentionally ignores activity updates (appendActivity). Tool-call
+ * traffic from a running background agent would otherwise churn the
+ * Footer pill and the AppContainer every few hundred ms. The detail
+ * dialog subscribes to the activity callback directly when it needs
+ * live Progress updates.
+ */
+
+import { useState, useEffect } from 'react';
+import {
+  type BackgroundTaskEntry,
+  type Config,
+} from '@qwen-code/qwen-code-core';
+
+export interface UseBackgroundTaskViewResult {
+  entries: readonly BackgroundTaskEntry[];
+}
+
+export function useBackgroundTaskView(
+  config: Config | null,
+): UseBackgroundTaskViewResult {
+  const [entries, setEntries] = useState<BackgroundTaskEntry[]>([]);
+
+  useEffect(() => {
+    if (!config) return;
+    const registry = config.getBackgroundTaskRegistry();
+
+    // getAll() returns a fresh array in registration (= startTime) order.
+    setEntries(registry.getAll());
+
+    const onStatusChange = () => {
+      setEntries(registry.getAll());
+    };
+
+    registry.setStatusChangeCallback(onStatusChange);
+
+    return () => {
+      registry.setStatusChangeCallback(undefined);
+    };
+  }, [config]);
+
+  return { entries };
+}
diff --git a/packages/cli/src/ui/hooks/useCommandCompletion.test.ts b/packages/cli/src/ui/hooks/useCommandCompletion.test.ts
index 74e5e942d..25f2f4924 100644
--- a/packages/cli/src/ui/hooks/useCommandCompletion.test.ts
+++ b/packages/cli/src/ui/hooks/useCommandCompletion.test.ts
@@ -9,7 +9,8 @@
 import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/react';
 import { useCommandCompletion } from './useCommandCompletion.js';
-import type { CommandContext } from '../commands/types.js';
+import type { CommandContext, SlashCommand } from '../commands/types.js';
+import { CommandKind } from '../commands/types.js';
 import type { Config } from '@qwen-code/qwen-code-core';
 import { useTextBuffer } from '../components/shared/text-buffer.js';
 import { useEffect } from 'react';
@@ -585,4 +586,62 @@ describe('useCommandCompletion', () => {
       );
     });
   });
+
+  describe('argument hint ghost text', () => {
+    it('shows argumentHint as inline ghost text for a complete slash command', () => {
+      const slashCommands: SlashCommand[] = [
+        {
+          name: 'fix-issue',
+          description: 'Fix GitHub issue',
+          argumentHint: '[issue-number]',
+          kind: CommandKind.FILE,
+        },
+      ];
+
+      const { result } = renderHook(() => {
+        const textBuffer = useTextBufferForTest('/fix-issue');
+        const completion = useCommandCompletion(
+          textBuffer,
+          testRootDir,
+          slashCommands,
+          mockCommandContext,
+          false,
+          mockConfig,
+        );
+        return completion;
+      });
+
+      expect(result.current.midInputGhostText).toEqual({
+        text: '[issue-number]',
+        insertPosition: '/fix-issue'.length,
+        showCursorBeforeText: true,
+      });
+    });
+
+    it('does not show argumentHint after arguments have started', () => {
+      const slashCommands: SlashCommand[] = [
+        {
+          name: 'fix-issue',
+          description: 'Fix GitHub issue',
+          argumentHint: '[issue-number]',
+          kind: CommandKind.FILE,
+        },
+      ];
+
+      const { result } = renderHook(() => {
+        const textBuffer = useTextBufferForTest('/fix-issue 123');
+        const completion = useCommandCompletion(
+          textBuffer,
+          testRootDir,
+          slashCommands,
+          mockCommandContext,
+          false,
+          mockConfig,
+        );
+        return completion;
+      });
+
+      expect(result.current.midInputGhostText).toBeNull();
+    });
+  });
 });
diff --git a/packages/cli/src/ui/hooks/useCommandCompletion.tsx b/packages/cli/src/ui/hooks/useCommandCompletion.tsx
index cedea5c56..0b1cfd72f 100644
--- a/packages/cli/src/ui/hooks/useCommandCompletion.tsx
+++ b/packages/cli/src/ui/hooks/useCommandCompletion.tsx
@@ -19,6 +19,7 @@ import { useAtCompletion } from './useAtCompletion.js';
 import { useSlashCompletion } from './useSlashCompletion.js';
 import type { Config } from '@qwen-code/qwen-code-core';
 import { useCompletion } from './useCompletion.js';
+import { parseSlashCommand } from '../../utils/commands.js';
 
 export enum CompletionMode {
   IDLE = 'IDLE',
@@ -40,7 +41,12 @@ export interface UseCommandCompletionReturn {
   navigateDown: () => void;
   handleAutocomplete: (indexToUse: number) => void;
   /** Inline ghost text for mid-input slash commands (not at line start). */
-  midInputGhostText: { text: string; insertPosition: number } | null;
+  midInputGhostText: {
+    text: string;
+    insertPosition: number;
+    acceptText?: string;
+    showCursorBeforeText?: boolean;
+  } | null;
 }
 
 export function useCommandCompletion(
@@ -243,17 +249,46 @@ export function useCommandCompletion(
   const midInputGhostText = useMemo((): {
     text: string;
     insertPosition: number;
+    acceptText?: string;
+    showCursorBeforeText?: boolean;
   } | null => {
     if (!active || reverseSearchActive) return null;
     const cursorOffset = logicalPosToOffset(buffer.lines, cursorRow, cursorCol);
     const midCmd = findMidInputSlashCommand(buffer.text, cursorOffset);
-    if (!midCmd) return null;
-    const match = getBestSlashCommandMatch(
-      midCmd.partialCommand,
+    if (midCmd) {
+      const match = getBestSlashCommandMatch(
+        midCmd.partialCommand,
+        slashCommands,
+      );
+      if (!match) return null;
+      return {
+        text: match.suffix,
+        insertPosition: cursorOffset,
+        acceptText: match.suffix,
+      };
+    }
+
+    if (cursorRow !== 0) return null;
+    const currentLine = buffer.lines[cursorRow] || '';
+    const lineCodePoints = toCodePoints(currentLine);
+    if (cursorCol !== lineCodePoints.length) return null;
+
+    const lineToCursor = lineCodePoints.slice(0, cursorCol).join('');
+    if (!isSlashCommand(lineToCursor.trim())) return null;
+
+    const { commandToExecute, args } = parseSlashCommand(
+      lineToCursor,
       slashCommands,
     );
-    if (!match) return null;
-    return { text: match.suffix, insertPosition: cursorOffset };
+    if (!commandToExecute?.argumentHint || args.trim().length > 0) {
+      return null;
+    }
+
+    return {
+      text: commandToExecute.argumentHint,
+      insertPosition: cursorOffset,
+      showCursorBeforeText: true,
+    };
   }, [
     buffer.text,
     buffer.lines,
diff --git a/packages/cli/src/ui/hooks/useDialogClose.ts b/packages/cli/src/ui/hooks/useDialogClose.ts
index 2f8f8828b..ba1200294 100644
--- a/packages/cli/src/ui/hooks/useDialogClose.ts
+++ b/packages/cli/src/ui/hooks/useDialogClose.ts
@@ -57,6 +57,10 @@ export interface DialogCloseOptions {
   // Welcome back dialog
   showWelcomeBackDialog: boolean;
   handleWelcomeBackClose: () => void;
+
+  // Background tasks dialog
+  isBackgroundTasksDialogOpen: boolean;
+  closeBackgroundTasksDialog: () => void;
 }
 
 /**
@@ -114,6 +118,14 @@ export function useDialogClose(options: DialogCloseOptions) {
       return true;
     }
 
+    if (options.isBackgroundTasksDialogOpen) {
+      // Background tasks dialog — routed through closeAnyOpenDialog so
+      // Ctrl+C and the global escape path dismiss it without escalating
+      // to exit prompts.
+      options.closeBackgroundTasksDialog();
+      return true;
+    }
+
     // No dialog was open
     return false;
   }, [options]);
diff --git a/packages/cli/src/ui/hooks/useDoublePress.ts b/packages/cli/src/ui/hooks/useDoublePress.ts
new file mode 100644
index 000000000..89d6c1b97
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useDoublePress.ts
@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useRef, useCallback, useEffect } from 'react';
+
+const DOUBLE_PRESS_TIMEOUT_MS = 800;
+
+/**
+ * Generic double-press detection hook.
+ *
+ * Returns a callback that should be invoked on each press. On the first
+ * press, optionally calls `onPending(true)` and starts a timer. If a
+ * second press arrives within 800ms, calls `onDoublePress`. Otherwise,
+ * the pending state is cleared after the timeout.
+ *
+ * @param onDoublePress Callback fired when a double-press is detected
+ * @param onPending Optional callback to update pending state (for UI hints)
+ * @returns A callback to invoke on each press
+ */
+export function useDoublePress(
+  onDoublePress: () => void,
+  onPending?: (pending: boolean) => void,
+): () => void {
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Clean up timer on unmount
+  useEffect(
+    () => () => {
+      if (timeoutRef.current !== null) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    },
+    [],
+  );
+
+  return useCallback(() => {
+    if (timeoutRef.current !== null) {
+      // Second press within the timeout window
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+      onPending?.(false);
+      onDoublePress();
+    } else {
+      // First press — start the timer
+      onPending?.(true);
+      timeoutRef.current = setTimeout(() => {
+        timeoutRef.current = null;
+        onPending?.(false);
+      }, DOUBLE_PRESS_TIMEOUT_MS);
+    }
+  }, [onDoublePress, onPending]);
+}
diff --git a/packages/cli/src/ui/hooks/useGeminiStream.test.tsx b/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
index 7483e9349..0616b97ed 100644
--- a/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
+++ b/packages/cli/src/ui/hooks/useGeminiStream.test.tsx
@@ -6,7 +6,7 @@
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import type { Mock, MockInstance } from 'vitest';
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/react';
 import { useGeminiStream, classifyApiError } from './useGeminiStream.js';
 import * as atCommandProcessor from './atCommandProcessor.js';
@@ -207,6 +207,8 @@ describe('useGeminiStream', () => {
       getArenaAgentClient: vi.fn(() => null),
       isCronEnabled: vi.fn(() => false),
       getCronScheduler: vi.fn(() => null),
+      getEmitToolUseSummaries: vi.fn(() => false),
+      getFastModel: vi.fn(() => undefined),
       getBackgroundTaskRegistry: vi.fn(() => ({
         setNotificationCallback: vi.fn(),
       })),
@@ -238,6 +240,10 @@ describe('useGeminiStream', () => {
     handleAtCommandSpy = vi.spyOn(atCommandProcessor, 'handleAtCommand');
   });
 
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   const mockLoadedSettings: LoadedSettings = {
     merged: { preferredEditor: 'vscode' },
     user: { path: '/user/settings.json', settings: {} },
@@ -822,7 +828,482 @@ describe('useGeminiStream', () => {
     expect(result.current.streamingState).toBe(StreamingState.Responding);
   });
 
+  describe('Tool-use summary generation', () => {
+    const makeCompletedToolCall = (
+      callId: string,
+      name: string,
+      args: Record<string, unknown>,
+    ): TrackedCompletedToolCall =>
+      ({
+        request: {
+          callId,
+          name,
+          args,
+          isClientInitiated: false,
+          prompt_id: 'prompt-1',
+        },
+        status: 'success',
+        responseSubmittedToGemini: false,
+        tool: {
+          name,
+          displayName: name,
+          description: 'desc',
+          build: vi.fn(),
+        } as any,
+        invocation: {
+          getDescription: () => 'Mock description',
+        } as unknown as AnyToolInvocation,
+        startTime: Date.now(),
+        endTime: Date.now(),
+        response: {
+          callId,
+          responseParts: [{ text: `result for ${name}` }],
+          error: undefined,
+          errorType: undefined,
+          resultDisplay: '',
+        },
+      }) as TrackedCompletedToolCall;
+
+    const runCompletion = async (
+      config: Config,
+      completedTools: TrackedCompletedToolCall[],
+    ) => {
+      let capturedOnComplete:
+        | ((completedTools: TrackedToolCall[]) => Promise<void>)
+        | null = null;
+
+      mockUseReactToolScheduler.mockImplementation((onComplete) => {
+        capturedOnComplete = onComplete;
+        return [
+          completedTools,
+          mockScheduleToolCalls,
+          mockMarkToolsAsSubmitted,
+        ];
+      });
+
+      // Seed history with a tool_group whose callIds match the completed
+      // tools, so the staleness check (which verifies the tool_group is
+      // still the latest in history) passes. Without this seed the summary
+      // would be dropped as stale before addItem is called.
+      const historyWithToolGroup = [
+        {
+          type: 'tool_group',
+          id: 1,
+          tools: completedTools.map((tc) => ({
+            callId: tc.request.callId,
+            name: tc.request.name,
+            description: '',
+            status: 0,
+            resultDisplay: undefined,
+            confirmationDetails: undefined,
+          })),
+        } as unknown as HistoryItem,
+      ];
+
+      renderHook(() =>
+        useGeminiStream(
+          new MockedGeminiClientClass(config),
+          historyWithToolGroup,
+          mockAddItem,
+          config,
+          mockLoadedSettings,
+          mockOnDebugMessage,
+          mockHandleSlashCommand,
+          false,
+          () => 'vscode' as EditorType,
+          () => {},
+          () => Promise.resolve(),
+          false,
+          () => {},
+          () => {},
+          () => {},
+          () => {},
+          80,
+          24,
+        ),
+      );
+
+      await act(async () => {
+        if (capturedOnComplete) {
+          await capturedOnComplete(completedTools);
+        }
+      });
+    };
+
+    it('skips summary generation when the feature is disabled', async () => {
+      const config = {
+        ...mockConfig,
+        getEmitToolUseSummaries: vi.fn(() => false),
+        getFastModel: vi.fn(() => 'qwen-fast'),
+        getGeminiClient: vi.fn(() => ({
+          generateContent: vi.fn(),
+        })),
+      } as unknown as Config;
+
+      await runCompletion(config, [
+        makeCompletedToolCall('c1', 'Read', { file: 'a.ts' }),
+        makeCompletedToolCall('c2', 'Grep', { pattern: 'foo' }),
+      ]);
+
+      // The flag is off — even though a fast model is configured, no summary
+      // history item should be added.
+      const summaryItems = (mockAddItem.mock.calls as any[][]).filter(
+        (call) => call[0]?.type === 'tool_use_summary',
+      );
+      expect(summaryItems).toHaveLength(0);
+    });
+
+    it('skips summary generation when no fast model is configured', async () => {
+      const generateContent = vi.fn();
+      const config = {
+        ...mockConfig,
+        getEmitToolUseSummaries: vi.fn(() => true),
+        getFastModel: vi.fn(() => undefined),
+        getGeminiClient: vi.fn(() => ({ generateContent })),
+      } as unknown as Config;
+
+      await runCompletion(config, [
+        makeCompletedToolCall('c1', 'Read', { file: 'a.ts' }),
+      ]);
+
+      expect(generateContent).not.toHaveBeenCalled();
+    });
+
+    it('fires generation with tool input/output when enabled', async () => {
+      const generateContent = vi.fn().mockResolvedValue({
+        candidates: [{ content: { parts: [{ text: 'Searched auth/' }] } }],
+      });
+      const config = {
+        ...mockConfig,
+        getEmitToolUseSummaries: vi.fn(() => true),
+        getFastModel: vi.fn(() => 'qwen-fast'),
+        getGeminiClient: vi.fn(() => ({ generateContent })),
+      } as unknown as Config;
+
+      await runCompletion(config, [
+        makeCompletedToolCall('c1', 'Grep', { pattern: 'login' }),
+        makeCompletedToolCall('c2', 'Read', { file: 'auth.ts' }),
+      ]);
+
+      // Wait for the fire-and-forget promise chain to settle (addItem happens in .then()).
+      await waitFor(() => {
+        const summaryItems = (mockAddItem.mock.calls as any[][]).filter(
+          (call) => call[0]?.type === 'tool_use_summary',
+        );
+        expect(summaryItems).toHaveLength(1);
+        expect(summaryItems[0][0]).toMatchObject({
+          type: 'tool_use_summary',
+          summary: 'Searched auth/',
+          precedingToolUseIds: ['c1', 'c2'],
+        });
+      });
+
+      // Model was called with the fast model and includes tool names in the prompt.
+      expect(generateContent).toHaveBeenCalledTimes(1);
+      const callArgs = generateContent.mock.calls[0];
+      expect(callArgs[3]).toBe('qwen-fast');
+      const userText = callArgs[0][0].parts[0].text as string;
+      expect(userText).toContain('Tool: Grep');
+      expect(userText).toContain('Tool: Read');
+      expect(userText).toContain('"pattern":"login"');
+    });
+
+    it('drops a late summary when a newer tool_group has been added', async () => {
+      // Resolve the fast-model call but ensure history shows a NEWER
+      // tool_group AFTER ours — simulates a slow summary landing during
+      // the next turn. The summary must not be appended; otherwise the
+      // ● label line would land in the wrong transcript position.
+      let resolveSummary: (val: { candidates: unknown[] }) => void;
+      const generateContent = vi.fn().mockImplementation(
+        () =>
+          new Promise((resolve) => {
+            resolveSummary = resolve;
+          }),
+      );
+      const config = {
+        ...mockConfig,
+        getEmitToolUseSummaries: vi.fn(() => true),
+        getFastModel: vi.fn(() => 'qwen-fast'),
+        getGeminiClient: vi.fn(() => ({ generateContent })),
+      } as unknown as Config;
+
+      let capturedOnComplete:
+        | ((completedTools: TrackedToolCall[]) => Promise<void>)
+        | null = null;
+      const completedTools = [
+        makeCompletedToolCall('c1', 'Read', { file: 'a.ts' }),
+      ];
+      mockUseReactToolScheduler.mockImplementation((onComplete) => {
+        capturedOnComplete = onComplete;
+        return [
+          completedTools,
+          mockScheduleToolCalls,
+          mockMarkToolsAsSubmitted,
+        ];
+      });
+
+      // History initially has our tool_group, but a newer tool_group is
+      // added before the summary resolves.
+      const history: HistoryItem[] = [
+        {
+          type: 'tool_group',
+          id: 1,
+          tools: [
+            {
+              callId: 'c1',
+              name: 'Read',
+              description: '',
+              status: 0,
+              resultDisplay: undefined,
+              confirmationDetails: undefined,
+            },
+          ],
+        } as unknown as HistoryItem,
+        {
+          type: 'tool_group',
+          id: 2,
+          tools: [
+            {
+              callId: 'c2',
+              name: 'Edit',
+              description: '',
+              status: 0,
+              resultDisplay: undefined,
+              confirmationDetails: undefined,
+            },
+          ],
+        } as unknown as HistoryItem,
+      ];
+
+      renderHook(() =>
+        useGeminiStream(
+          new MockedGeminiClientClass(config),
+          history,
+          mockAddItem,
+          config,
+          mockLoadedSettings,
+          mockOnDebugMessage,
+          mockHandleSlashCommand,
+          false,
+          () => 'vscode' as EditorType,
+          () => {},
+          () => Promise.resolve(),
+          false,
+          () => {},
+          () => {},
+          () => {},
+          () => {},
+          80,
+          24,
+        ),
+      );
+
+      await act(async () => {
+        if (capturedOnComplete) {
+          await capturedOnComplete(completedTools);
+        }
+      });
+
+      // Resolve the summary — it should be dropped because tool_group id=2
+      // is newer than our anchor tool_group id=1.
+      await act(async () => {
+        resolveSummary!({
+          candidates: [{ content: { parts: [{ text: 'Read file' }] } }],
+        });
+      });
+
+      const summaryItems = (mockAddItem.mock.calls as any[][]).filter(
+        (call) => call[0]?.type === 'tool_use_summary',
+      );
+      expect(summaryItems).toHaveLength(0);
+    });
+
+    it('does not add a history item when the model returns empty', async () => {
+      const generateContent = vi.fn().mockResolvedValue({
+        candidates: [{ content: { parts: [{ text: '' }] } }],
+      });
+      const config = {
+        ...mockConfig,
+        getEmitToolUseSummaries: vi.fn(() => true),
+        getFastModel: vi.fn(() => 'qwen-fast'),
+        getGeminiClient: vi.fn(() => ({ generateContent })),
+      } as unknown as Config;
+
+      await runCompletion(config, [
+        makeCompletedToolCall('c1', 'Read', { file: 'a.ts' }),
+      ]);
+
+      // The fast-model call happened but produced no label, so no history item.
+      await waitFor(() => {
+        expect(generateContent).toHaveBeenCalled();
+      });
+      const summaryItems = (mockAddItem.mock.calls as any[][]).filter(
+        (call) => call[0]?.type === 'tool_use_summary',
+      );
+      expect(summaryItems).toHaveLength(0);
+    });
+  });
+
   describe('Cancellation', () => {
+    it('buffers streamed content until the throttle interval elapses', async () => {
+      vi.useFakeTimers();
+
+      let releaseStream!: () => void;
+      const holdStream = new Promise<void>((resolve) => {
+        releaseStream = resolve;
+      });
+
+      const mockStream = (async function* () {
+        yield {
+          type: ServerGeminiEventType.Content,
+          value: 'Hel',
+        };
+        yield {
+          type: ServerGeminiEventType.Content,
+          value: 'lo',
+        };
+        await holdStream;
+      })();
+      mockSendMessageStream.mockReturnValue(mockStream);
+
+      const { result } = renderTestHook();
+
+      act(() => {
+        void result.current.submitQuery('test query');
+      });
+
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(mockSendMessageStream).toHaveBeenCalledTimes(1);
+
+      expect(result.current.pendingHistoryItems).toEqual([]);
+
+      await act(async () => {
+        vi.advanceTimersByTime(60);
+      });
+
+      expect(result.current.pendingHistoryItems).toEqual([
+        expect.objectContaining({
+          type: 'gemini',
+          text: 'Hello',
+        }),
+      ]);
+
+      act(() => {
+        result.current.cancelOngoingRequest();
+      });
+
+      await act(async () => {
+        releaseStream();
+      });
+    });
+
+    it('buffers streamed thoughts until the throttle interval elapses', async () => {
+      vi.useFakeTimers();
+
+      let releaseStream!: () => void;
+      const holdStream = new Promise<void>((resolve) => {
+        releaseStream = resolve;
+      });
+
+      const mockStream = (async function* () {
+        yield {
+          type: ServerGeminiEventType.Thought,
+          value: { description: 'Think' },
+        };
+        yield {
+          type: ServerGeminiEventType.Thought,
+          value: { description: 'ing' },
+        };
+        await holdStream;
+      })();
+      mockSendMessageStream.mockReturnValue(mockStream);
+
+      const { result } = renderTestHook();
+
+      act(() => {
+        void result.current.submitQuery('test query');
+      });
+
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(mockSendMessageStream).toHaveBeenCalledTimes(1);
+      expect(result.current.pendingHistoryItems).toEqual([]);
+
+      await act(async () => {
+        vi.advanceTimersByTime(60);
+      });
+
+      expect(result.current.pendingHistoryItems).toEqual([
+        expect.objectContaining({
+          type: 'gemini_thought',
+          text: 'Thinking',
+        }),
+      ]);
+      expect(result.current.thought).toEqual({ description: 'Thinking' });
+
+      act(() => {
+        result.current.cancelOngoingRequest();
+      });
+
+      await act(async () => {
+        releaseStream();
+      });
+    });
+
+    it('flushes buffered content before cancellation', async () => {
+      vi.useFakeTimers();
+
+      let releaseStream!: () => void;
+      const holdStream = new Promise<void>((resolve) => {
+        releaseStream = resolve;
+      });
+
+      const mockStream = (async function* () {
+        yield {
+          type: ServerGeminiEventType.Content,
+          value: 'Initial',
+        };
+        await holdStream;
+      })();
+      mockSendMessageStream.mockReturnValue(mockStream);
+
+      const { result } = renderTestHook();
+
+      act(() => {
+        void result.current.submitQuery('test query');
+      });
+
+      await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(mockSendMessageStream).toHaveBeenCalledTimes(1);
+
+      act(() => {
+        result.current.cancelOngoingRequest();
+      });
+
+      expect(mockAddItem).toHaveBeenCalledWith(
+        {
+          type: 'gemini',
+          text: 'Initial',
+        },
+        expect.any(Number),
+      );
+
+      await act(async () => {
+        releaseStream();
+      });
+    });
+
     it('should cancel an in-progress stream when cancelOngoingRequest is called', async () => {
       const mockStream = (async function* () {
         yield { type: 'content', value: 'Part 1' };
@@ -992,6 +1473,10 @@ describe('useGeminiStream', () => {
         expect(mockSendMessageStream).toHaveBeenCalledTimes(1);
       });
 
+      await act(async () => {
+        await Promise.resolve();
+      });
+
       // Cancel the request
       act(() => {
         result.current.cancelOngoingRequest();
@@ -2811,6 +3296,13 @@ describe('useGeminiStream', () => {
           result.current.cancelOngoingRequest();
         });
 
+        expect(mockAddItem).toHaveBeenCalledWith(
+          {
+            type: 'gemini',
+            text: 'First call content',
+          },
+          expect.any(Number),
+        );
         expect(mainAbortSignal?.aborted).toBe(true);
       } finally {
         resolveFirstCall();
diff --git a/packages/cli/src/ui/hooks/useGeminiStream.ts b/packages/cli/src/ui/hooks/useGeminiStream.ts
index d680a736d..e59112f3d 100644
--- a/packages/cli/src/ui/hooks/useGeminiStream.ts
+++ b/packages/cli/src/ui/hooks/useGeminiStream.ts
@@ -4,7 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
+import {
+  useState,
+  useRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useLayoutEffect,
+} from 'react';
 import type {
   Config,
   EditorType,
@@ -42,6 +49,7 @@ import {
   ApiCancelEvent,
   isSupportedImageMimeType,
   getUnsupportedImageFormatWarning,
+  generateToolUseSummary,
 } from '@qwen-code/qwen-code-core';
 import { type Part, type PartListUnion, FinishReason } from '@google/genai';
 import type {
@@ -80,6 +88,48 @@ import { useDualOutput } from '../../dualOutput/DualOutputContext.js';
 
 const debugLogger = createDebugLogger('GEMINI_STREAM');
 
+/**
+ * Pull the assistant's most recent visible text from the UI history. Used as
+ * an intent prefix for tool-use summary generation so the summarizer knows
+ * what the user was trying to accomplish.
+ */
+function extractLastAssistantText(history: HistoryItem[]): string | undefined {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const item = history[i];
+    if (
+      (item.type === 'gemini' || item.type === 'gemini_content') &&
+      typeof item.text === 'string' &&
+      item.text.trim().length > 0
+    ) {
+      return item.text;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Flatten `functionResponse` parts into a compact string for the summarizer.
+ * The summarizer itself truncates to 300 chars per field, so we just join
+ * whatever is available without re-serializing.
+ */
+function extractToolResultText(parts: Part[] | Part | undefined): unknown {
+  if (!parts) return '';
+  const list = Array.isArray(parts) ? parts : [parts];
+  const chunks: unknown[] = [];
+  for (const part of list) {
+    if ('functionResponse' in part && part.functionResponse) {
+      const response = (part.functionResponse as { response?: unknown })
+        .response;
+      if (response !== undefined) chunks.push(response);
+    } else if ('text' in part && typeof part.text === 'string') {
+      chunks.push(part.text);
+    }
+  }
+  if (chunks.length === 0) return '';
+  if (chunks.length === 1) return chunks[0];
+  return chunks;
+}
+
 /**
  * Classify API error to StopFailureErrorType
  * @internal Exported for testing purposes
@@ -178,6 +228,11 @@ enum StreamProcessingStatus {
 }
 
 const EDIT_TOOL_NAMES = new Set(['replace', 'write_file']);
+const STREAM_UPDATE_THROTTLE_MS = 60;
+
+type BufferedStreamEvent =
+  | { kind: 'content'; value: string }
+  | { kind: 'thought'; value: ThoughtSummary };
 
 function showCitations(settings: LoadedSettings): boolean {
   const enabled = settings?.merged?.ui?.showCitations;
@@ -216,6 +271,7 @@ export const useGeminiStream = (
 ) => {
   const [initError, setInitError] = useState<string | null>(null);
   const abortControllerRef = useRef<AbortController | null>(null);
+  const flushBufferedStreamEventsRef = useRef<Set<() => void>>(new Set());
   const turnCancelledRef = useRef(false);
   const isSubmittingQueryRef = useRef(false);
   const lastPromptRef = useRef<PartListUnion | null>(null);
@@ -223,6 +279,22 @@ export const useGeminiStream = (
   const dualOutput = useDualOutput();
   const [isResponding, setIsResponding] = useState<boolean>(false);
   const [thought, setThought] = useState<ThoughtSummary | null>(null);
+  // Hold the latest history in a ref so handleCompletedTools can read it
+  // without depending on `history` (which would recreate the tool scheduler
+  // every render). Use useLayoutEffect instead of writing during render —
+  // writing refs in the render phase is unsafe under React's concurrent
+  // rendering (a bailed-out render could leave the ref with a dropped value).
+  const historyRef = useRef<HistoryItem[]>(history);
+  useLayoutEffect(() => {
+    historyRef.current = history;
+  }, [history]);
+  // In-flight tool-use-summary aborters. Each batch gets its own AbortController
+  // because the captured turn controller is replaced when submitQuery starts
+  // the next turn, and the summary call outlives the current turn (that's the
+  // whole point — it overlaps with the next turn's streaming). cancelOngoingRequest
+  // aborts all in-flight summaries so Ctrl+C during the next turn also kills
+  // this turn's stale summary work.
+  const summaryAbortRefsRef = useRef<Set<AbortController>>(new Set());
   const [pendingHistoryItem, pendingHistoryItemRef, setPendingHistoryItem] =
     useStateAndRef<HistoryItemWithoutId | null>(null);
   const [
@@ -483,9 +555,18 @@ export const useGeminiStream = (
     if (turnCancelledRef.current) {
       return;
     }
+    for (const flushBufferedStreamEvents of flushBufferedStreamEventsRef.current) {
+      flushBufferedStreamEvents();
+    }
     turnCancelledRef.current = true;
     isSubmittingQueryRef.current = false;
     abortControllerRef.current?.abort();
+    // Cancel any in-flight tool-use-summary generations so their Promise.then
+    // doesn't addItem a stale label after the user cancelled.
+    for (const ac of summaryAbortRefsRef.current) {
+      ac.abort();
+    }
+    summaryAbortRefsRef.current.clear();
 
     // Report cancellation to arena status reporter (if in arena mode).
     // This is needed because cancellation during tool execution won't
@@ -1121,133 +1202,226 @@ export const useGeminiStream = (
       let geminiMessageBuffer = '';
       let thoughtBuffer = '';
       const toolCallRequests: ToolCallRequestInfo[] = [];
-      dualOutput?.startAssistantMessage();
-      for await (const event of stream) {
-        dualOutput?.processEvent(event);
-        switch (event.type) {
-          case ServerGeminiEventType.Thought:
-            // If the thought has a subject, it's a discrete status update rather than
-            // a streamed textual thought, so we update the thought state directly.
-            if (event.value.subject) {
-              setThought(event.value);
-            } else {
-              thoughtBuffer = handleThoughtEvent(
-                event.value,
-                thoughtBuffer,
-                userMessageTimestamp,
-              );
+      const bufferedEvents: BufferedStreamEvent[] = [];
+      let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+      const discardBufferedStreamEvents = () => {
+        if (flushTimer) {
+          clearTimeout(flushTimer);
+          flushTimer = null;
+        }
+        bufferedEvents.length = 0;
+      };
+
+      const flushBufferedStreamEvents = () => {
+        if (flushTimer) {
+          clearTimeout(flushTimer);
+          flushTimer = null;
+        }
+
+        if (bufferedEvents.length === 0) {
+          return;
+        }
+
+        while (bufferedEvents.length > 0) {
+          const nextEvent = bufferedEvents.shift()!;
+
+          if (nextEvent.kind === 'content') {
+            let mergedContent = nextEvent.value;
+
+            while (bufferedEvents[0]?.kind === 'content') {
+              const queuedContent = bufferedEvents.shift();
+              if (queuedContent?.kind !== 'content') {
+                break;
+              }
+              mergedContent += queuedContent.value;
             }
-            break;
-          case ServerGeminiEventType.Content:
+
             geminiMessageBuffer = handleContentEvent(
-              event.value,
+              mergedContent,
               geminiMessageBuffer,
               userMessageTimestamp,
             );
-            break;
-          case ServerGeminiEventType.ToolCallRequest:
-            toolCallRequests.push(event.value);
-            // Count tool call args JSON toward token estimation (matches
-            // Claude Code's input_json_delta handling).
-            try {
-              const argsJson = JSON.stringify(event.value.args);
-              streamingResponseLengthRef.current += argsJson.length;
-            } catch {
-              // Best-effort — don't block on serialization errors
+            continue;
+          }
+
+          let mergedThought = nextEvent.value;
+
+          while (bufferedEvents[0]?.kind === 'thought') {
+            const queuedThought = bufferedEvents.shift();
+            if (queuedThought?.kind !== 'thought') {
+              break;
             }
-            break;
-          case ServerGeminiEventType.UserCancelled:
-            handleUserCancelledEvent(userMessageTimestamp);
-            break;
-          case ServerGeminiEventType.Error:
-            handleErrorEvent(event.value, userMessageTimestamp);
-            break;
-          case ServerGeminiEventType.ChatCompressed:
-            handleChatCompressionEvent(event.value, userMessageTimestamp);
-            break;
-          case ServerGeminiEventType.ToolCallConfirmation:
-          case ServerGeminiEventType.ToolCallResponse:
-            // do nothing
-            break;
-          case ServerGeminiEventType.MaxSessionTurns:
-            handleMaxSessionTurnsEvent();
-            break;
-          case ServerGeminiEventType.SessionTokenLimitExceeded:
-            handleSessionTokenLimitExceededEvent(event.value);
-            break;
-          case ServerGeminiEventType.Finished:
-            handleFinishedEvent(
-              event as ServerGeminiFinishedEvent,
-              userMessageTimestamp,
-            );
-            break;
-          case ServerGeminiEventType.Citation:
-            handleCitationEvent(event.value, userMessageTimestamp);
-            break;
-          case ServerGeminiEventType.LoopDetected:
-            // handle later because we want to move pending history to history
-            // before we add loop detected message to history
-            loopDetectedRef.current = true;
-            break;
-          case ServerGeminiEventType.Retry:
-            // On fresh restart (escalation / rate-limit / invalid stream),
-            // clear pending content and buffers to discard the failed attempt.
-            // On continuation (recovery), keep the pending gemini item AND
-            // buffers so the model's continuation text appends to them —
-            // otherwise handleContentEvent would see a null pending item,
-            // create a fresh one, and reset the buffer to just the new chunk,
-            // losing the partial text we meant to preserve.
-            if (!event.isContinuation) {
+            mergedThought = {
+              subject: queuedThought.value.subject || mergedThought.subject,
+              description: `${mergedThought.description ?? ''}${
+                queuedThought.value.description ?? ''
+              }`,
+            };
+          }
+
+          thoughtBuffer = handleThoughtEvent(
+            mergedThought,
+            thoughtBuffer,
+            userMessageTimestamp,
+          );
+        }
+      };
+
+      const scheduleBufferedStreamFlush = () => {
+        if (flushTimer) {
+          return;
+        }
+
+        flushTimer = setTimeout(() => {
+          flushBufferedStreamEvents();
+        }, STREAM_UPDATE_THROTTLE_MS);
+      };
+
+      flushBufferedStreamEventsRef.current.add(flushBufferedStreamEvents);
+      dualOutput?.startAssistantMessage();
+      try {
+        for await (const event of stream) {
+          dualOutput?.processEvent(event);
+          switch (event.type) {
+            case ServerGeminiEventType.Thought:
+              // If the thought has a subject, it's a discrete status update rather than
+              // a streamed textual thought, so we update the thought state directly.
+              if (event.value.subject) {
+                flushBufferedStreamEvents();
+                setThought(event.value);
+              } else {
+                bufferedEvents.push({ kind: 'thought', value: event.value });
+                scheduleBufferedStreamFlush();
+              }
+              break;
+            case ServerGeminiEventType.Content:
+              bufferedEvents.push({ kind: 'content', value: event.value });
+              scheduleBufferedStreamFlush();
+              break;
+            case ServerGeminiEventType.ToolCallRequest:
+              flushBufferedStreamEvents();
+              toolCallRequests.push(event.value);
+              // Count tool call args JSON toward token estimation (matches
+              // Claude Code's input_json_delta handling).
+              try {
+                const argsJson = JSON.stringify(event.value.args);
+                streamingResponseLengthRef.current += argsJson.length;
+              } catch {
+                // Best-effort — don't block on serialization errors
+              }
+              break;
+            case ServerGeminiEventType.UserCancelled:
+              flushBufferedStreamEvents();
+              handleUserCancelledEvent(userMessageTimestamp);
+              break;
+            case ServerGeminiEventType.Error:
+              flushBufferedStreamEvents();
+              handleErrorEvent(event.value, userMessageTimestamp);
+              break;
+            case ServerGeminiEventType.ChatCompressed:
+              flushBufferedStreamEvents();
+              handleChatCompressionEvent(event.value, userMessageTimestamp);
+              break;
+            case ServerGeminiEventType.ToolCallConfirmation:
+            case ServerGeminiEventType.ToolCallResponse:
+              flushBufferedStreamEvents();
+              break;
+            case ServerGeminiEventType.MaxSessionTurns:
+              flushBufferedStreamEvents();
+              handleMaxSessionTurnsEvent();
+              break;
+            case ServerGeminiEventType.SessionTokenLimitExceeded:
+              flushBufferedStreamEvents();
+              handleSessionTokenLimitExceededEvent(event.value);
+              break;
+            case ServerGeminiEventType.Finished:
+              flushBufferedStreamEvents();
+              handleFinishedEvent(
+                event as ServerGeminiFinishedEvent,
+                userMessageTimestamp,
+              );
+              break;
+            case ServerGeminiEventType.Citation:
+              flushBufferedStreamEvents();
+              handleCitationEvent(event.value, userMessageTimestamp);
+              break;
+            case ServerGeminiEventType.LoopDetected:
+              flushBufferedStreamEvents();
+              // handle later because we want to move pending history to history
+              // before we add loop detected message to history
+              loopDetectedRef.current = true;
+              break;
+            case ServerGeminiEventType.Retry:
+              // On fresh restart (escalation / rate-limit / invalid stream),
+              // clear pending content and buffers to discard the failed attempt.
+              // On continuation (recovery), keep the pending gemini item AND
+              // buffers so the model's continuation text appends to them —
+              // otherwise handleContentEvent would see a null pending item,
+              // create a fresh one, and reset the buffer to just the new chunk,
+              // losing the partial text we meant to preserve.
+              if (!event.isContinuation) {
+                discardBufferedStreamEvents();
+                if (pendingHistoryItemRef.current) {
+                  setPendingHistoryItem(null);
+                }
+                geminiMessageBuffer = '';
+                thoughtBuffer = '';
+              } else {
+                flushBufferedStreamEvents();
+              }
+              // Always discard tool call requests from the truncated/failed
+              // attempt to prevent duplicate execution after escalation or
+              // recovery. The recovery path now skips turns that already
+              // contain a functionCall (see geminiChat.ts), so this only
+              // clears stale requests from pre-RETRY accumulation.
+              toolCallRequests.length = 0;
+              // Show retry info if available (rate-limit / throttling errors)
+              if (event.retryInfo) {
+                startRetryCountdown(event.retryInfo);
+              } else {
+                // The retry attempt is starting now, so any prior retry UI is stale.
+                clearRetryCountdown();
+              }
+              break;
+            case ServerGeminiEventType.HookSystemMessage:
+              flushBufferedStreamEvents();
+              // Display system message from Stop hooks with "Stop says:" prefix
+              // First commit any pending AI response to ensure correct ordering
               if (pendingHistoryItemRef.current) {
+                addItem(pendingHistoryItemRef.current, userMessageTimestamp);
                 setPendingHistoryItem(null);
               }
-              geminiMessageBuffer = '';
-              thoughtBuffer = '';
+              addItem(
+                {
+                  type: 'stop_hook_system_message',
+                  message: event.value,
+                } as HistoryItemWithoutId,
+                userMessageTimestamp,
+              );
+              break;
+            case ServerGeminiEventType.UserPromptSubmitBlocked:
+              flushBufferedStreamEvents();
+              handleUserPromptSubmitBlockedEvent(
+                event.value,
+                userMessageTimestamp,
+              );
+              break;
+            case ServerGeminiEventType.StopHookLoop:
+              flushBufferedStreamEvents();
+              handleStopHookLoopEvent(event.value, userMessageTimestamp);
+              break;
+            default: {
+              // enforces exhaustive switch-case
+              const unreachable: never = event;
+              return unreachable;
             }
-            // Always discard tool call requests from the truncated/failed
-            // attempt to prevent duplicate execution after escalation or
-            // recovery. The recovery path now skips turns that already
-            // contain a functionCall (see geminiChat.ts), so this only
-            // clears stale requests from pre-RETRY accumulation.
-            toolCallRequests.length = 0;
-            // Show retry info if available (rate-limit / throttling errors)
-            if (event.retryInfo) {
-              startRetryCountdown(event.retryInfo);
-            } else {
-              // The retry attempt is starting now, so any prior retry UI is stale.
-              clearRetryCountdown();
-            }
-            break;
-          case ServerGeminiEventType.HookSystemMessage:
-            // Display system message from Stop hooks with "Stop says:" prefix
-            // First commit any pending AI response to ensure correct ordering
-            if (pendingHistoryItemRef.current) {
-              addItem(pendingHistoryItemRef.current, userMessageTimestamp);
-              setPendingHistoryItem(null);
-            }
-            addItem(
-              {
-                type: 'stop_hook_system_message',
-                message: event.value,
-              } as HistoryItemWithoutId,
-              userMessageTimestamp,
-            );
-            break;
-          case ServerGeminiEventType.UserPromptSubmitBlocked:
-            handleUserPromptSubmitBlockedEvent(
-              event.value,
-              userMessageTimestamp,
-            );
-            break;
-          case ServerGeminiEventType.StopHookLoop:
-            handleStopHookLoopEvent(event.value, userMessageTimestamp);
-            break;
-          default: {
-            // enforces exhaustive switch-case
-            const unreachable: never = event;
-            return unreachable;
           }
         }
+      } finally {
+        flushBufferedStreamEvents();
+        discardBufferedStreamEvents();
+        flushBufferedStreamEventsRef.current.delete(flushBufferedStreamEvents);
       }
       dualOutput?.finalizeAssistantMessage();
       if (toolCallRequests.length > 0) {
@@ -1766,6 +1940,97 @@ export const useGeminiStream = (
 
       markToolsAsSubmitted(callIdsToMarkAsSubmitted);
 
+      // Fire tool-use summary generation in parallel with the next API call.
+      // The fast-model Haiku-equivalent latency (~1s) is hidden behind the
+      // main-model streaming (5-30s). Mirrors Claude Code's query.ts:1411-1482
+      // behavior. Fire-and-forget: failures are silent and never block the turn.
+      // Subagent exclusion is implicit — useGeminiStream only drives the
+      // main session; subagents run through agents/runtime/ with their own loop.
+      if (config.getEmitToolUseSummaries()) {
+        // Only summarize successful tools. Error/cancelled entries push
+        // "Cancelled by user" / retry-loop warnings into the summarizer
+        // prompt and produce plausibly-worded but misleading labels (the
+        // fast model happily synthesizes "Attempted to read files" from a
+        // batch that was mostly failures). cleanSummary can reject output
+        // prefixes but not prevent this kind of polluted-input hallucination.
+        const successfulTools = geminiTools.filter(
+          (tc) => tc.status === 'success',
+        );
+        if (successfulTools.length > 0) {
+          const toolInfoForSummary = successfulTools.map((tc) => ({
+            name: tc.request.name,
+            input: tc.request.args,
+            output: extractToolResultText(tc.response.responseParts),
+          }));
+          const toolUseIds = successfulTools.map((tc) => tc.request.callId);
+          const lastAssistantText = extractLastAssistantText(
+            historyRef.current,
+          );
+          // Dedicated AbortController for this batch. Scoping it to the
+          // current turn via abortControllerRef.current would be wrong —
+          // submitQuery() below allocates a new controller for the next
+          // turn, so the captured signal becomes stale the moment the
+          // next turn starts. Instead, check the live abort state at
+          // resolve time (which covers both Ctrl+C on the next turn and
+          // mid-flight cancellation of this batch via turnCancelledRef).
+          const summaryAbort = new AbortController();
+          summaryAbortRefsRef.current.add(summaryAbort);
+
+          // Capture the first callId so we can locate "our" tool_group at
+          // resolve time. If a newer tool_group has been added since we
+          // fired (i.e., the conversation moved on), we drop the summary
+          // rather than wedging the `● <label>` line between later items.
+          const anchorCallId = toolUseIds[0];
+
+          void generateToolUseSummary({
+            config,
+            tools: toolInfoForSummary,
+            signal: summaryAbort.signal,
+            lastAssistantText,
+          })
+            .then((summary) => {
+              summaryAbortRefsRef.current.delete(summaryAbort);
+              const cancelled =
+                turnCancelledRef.current ||
+                abortControllerRef.current?.signal.aborted ||
+                summaryAbort.signal.aborted;
+              if (!summary || cancelled) return;
+
+              // Stale-summary check: only append if our tool_group is still
+              // the latest one in history. If a newer batch landed while
+              // the fast-model call was in flight, the conversation has
+              // moved past this batch and dropping in a `● <label>` line
+              // now would land it after later content (full mode) or
+              // attribute it to the wrong group (compact mode).
+              const currentHistory = historyRef.current;
+              const ourIdx = currentHistory.findIndex(
+                (h) =>
+                  h.type === 'tool_group' &&
+                  h.tools.some((t) => t.callId === anchorCallId),
+              );
+              if (ourIdx < 0) return;
+              const laterToolGroupExists = currentHistory
+                .slice(ourIdx + 1)
+                .some((h) => h.type === 'tool_group');
+              if (laterToolGroupExists) return;
+
+              if (summary && !cancelled) {
+                addItem(
+                  {
+                    type: 'tool_use_summary',
+                    summary,
+                    precedingToolUseIds: toolUseIds,
+                  } as HistoryItemWithoutId,
+                  Date.now(),
+                );
+              }
+            })
+            .catch(() => {
+              summaryAbortRefsRef.current.delete(summaryAbort);
+            });
+        }
+      }
+
       // Don't continue if model was switched due to quota error
       if (modelSwitchedFromQuotaError) {
         return;
diff --git a/packages/cli/src/ui/hooks/useHistoryManager.ts b/packages/cli/src/ui/hooks/useHistoryManager.ts
index c25fc84a2..1d3fc8de1 100644
--- a/packages/cli/src/ui/hooks/useHistoryManager.ts
+++ b/packages/cli/src/ui/hooks/useHistoryManager.ts
@@ -21,6 +21,7 @@ export interface UseHistoryManagerReturn {
   ) => void;
   clearItems: () => void;
   loadHistory: (newHistory: HistoryItem[]) => void;
+  truncateToItem: (itemId: number) => void;
 }
 
 /**
@@ -101,6 +102,14 @@ export function useHistory(): UseHistoryManagerReturn {
     messageIdCounterRef.current = 0;
   }, []);
 
+  // Truncates history to exclude the item with the given ID and everything after it.
+  const truncateToItem = useCallback((itemId: number) => {
+    setHistory((prev) => {
+      const index = prev.findIndex((h) => h.id === itemId);
+      return index === -1 ? prev : prev.slice(0, index);
+    });
+  }, []);
+
   return useMemo(
     () => ({
       history,
@@ -108,7 +117,8 @@ export function useHistory(): UseHistoryManagerReturn {
       updateItem,
       clearItems,
       loadHistory,
+      truncateToItem,
     }),
-    [history, addItem, updateItem, clearItems, loadHistory],
+    [history, addItem, updateItem, clearItems, loadHistory, truncateToItem],
   );
 }
diff --git a/packages/cli/src/ui/hooks/useManageModelsCommand.test.ts b/packages/cli/src/ui/hooks/useManageModelsCommand.test.ts
new file mode 100644
index 000000000..f9d46218f
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useManageModelsCommand.test.ts
@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useManageModelsCommand } from './useManageModelsCommand.js';
+
+describe('useManageModelsCommand', () => {
+  it('should initialize with the dialog closed', () => {
+    const { result } = renderHook(() => useManageModelsCommand());
+    expect(result.current.isManageModelsDialogOpen).toBe(false);
+  });
+
+  it('should open the dialog when openManageModelsDialog is called', () => {
+    const { result } = renderHook(() => useManageModelsCommand());
+
+    act(() => {
+      result.current.openManageModelsDialog();
+    });
+
+    expect(result.current.isManageModelsDialogOpen).toBe(true);
+  });
+
+  it('should close the dialog when closeManageModelsDialog is called', () => {
+    const { result } = renderHook(() => useManageModelsCommand());
+
+    act(() => {
+      result.current.openManageModelsDialog();
+    });
+    expect(result.current.isManageModelsDialogOpen).toBe(true);
+
+    act(() => {
+      result.current.closeManageModelsDialog();
+    });
+    expect(result.current.isManageModelsDialogOpen).toBe(false);
+  });
+});
diff --git a/packages/cli/src/ui/hooks/useManageModelsCommand.ts b/packages/cli/src/ui/hooks/useManageModelsCommand.ts
new file mode 100644
index 000000000..ed1f2965e
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useManageModelsCommand.ts
@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useCallback, useState } from 'react';
+
+interface UseManageModelsCommandReturn {
+  isManageModelsDialogOpen: boolean;
+  openManageModelsDialog: () => void;
+  closeManageModelsDialog: () => void;
+}
+
+export function useManageModelsCommand(): UseManageModelsCommandReturn {
+  const [isManageModelsDialogOpen, setIsManageModelsDialogOpen] =
+    useState(false);
+
+  const openManageModelsDialog = useCallback(() => {
+    setIsManageModelsDialogOpen(true);
+  }, []);
+
+  const closeManageModelsDialog = useCallback(() => {
+    setIsManageModelsDialogOpen(false);
+  }, []);
+
+  return {
+    isManageModelsDialogOpen,
+    openManageModelsDialog,
+    closeManageModelsDialog,
+  };
+}
diff --git a/packages/cli/src/ui/hooks/useQwenAuth.ts b/packages/cli/src/ui/hooks/useQwenAuth.ts
index 2b1819c1c..f3bbf7e19 100644
--- a/packages/cli/src/ui/hooks/useQwenAuth.ts
+++ b/packages/cli/src/ui/hooks/useQwenAuth.ts
@@ -24,6 +24,12 @@ export interface QwenAuthState {
   authMessage: string | null;
 }
 
+export interface ExternalAuthState {
+  title: string;
+  message: string;
+  detail?: string;
+}
+
 export const useQwenAuth = (
   pendingAuthType: AuthType | undefined,
   isAuthenticating: boolean,
diff --git a/packages/cli/src/ui/hooks/useResumeCommand.test.ts b/packages/cli/src/ui/hooks/useResumeCommand.test.ts
index 4d5a5a68d..a346e0ad9 100644
--- a/packages/cli/src/ui/hooks/useResumeCommand.test.ts
+++ b/packages/cli/src/ui/hooks/useResumeCommand.test.ts
@@ -145,6 +145,7 @@ describe('useResumeCommand', () => {
       getTargetDir: () => '/tmp',
       getGeminiClient: () => geminiClient,
       startNewSession: vi.fn(),
+      getChatRecordingService: () => ({ rebuildTurnBoundaries: vi.fn() }),
       getDebugLogger: () => ({
         warn: vi.fn(),
         debug: vi.fn(),
diff --git a/packages/cli/src/ui/hooks/useResumeCommand.ts b/packages/cli/src/ui/hooks/useResumeCommand.ts
index 037b75f3c..f9ca2df23 100644
--- a/packages/cli/src/ui/hooks/useResumeCommand.ts
+++ b/packages/cli/src/ui/hooks/useResumeCommand.ts
@@ -95,6 +95,10 @@ export function useResumeCommand(
 
       // Update session history core.
       config.startNewSession(sessionId, sessionData);
+      // Rebuild turn boundary tracking so rewind works within resumed sessions.
+      config
+        .getChatRecordingService()
+        ?.rebuildTurnBoundaries(sessionData.conversation.messages);
       await config.getGeminiClient()?.initialize?.();
 
       // Fire SessionStart event after resuming session
diff --git a/packages/cli/src/ui/hooks/useSessionPicker.ts b/packages/cli/src/ui/hooks/useSessionPicker.ts
index 98bba2f65..fef9dbd07 100644
--- a/packages/cli/src/ui/hooks/useSessionPicker.ts
+++ b/packages/cli/src/ui/hooks/useSessionPicker.ts
@@ -48,6 +48,11 @@ export interface UseSessionPickerOptions {
    * Enable/disable input handling.
    */
   isActive?: boolean;
+  /**
+   * Enable Space-to-preview. See SessionPickerProps.enablePreview for the
+   * safety rationale (preview's Enter forwards to onSelect).
+   */
+  enablePreview?: boolean;
 }
 
 export interface UseSessionPickerResult {
@@ -61,6 +66,9 @@ export interface UseSessionPickerResult {
   showScrollUp: boolean;
   showScrollDown: boolean;
   loadMoreSessions: () => Promise<void>;
+  viewMode: 'list' | 'preview';
+  previewSessionId: string | null;
+  exitPreview: () => void;
 }
 
 export function useSessionPicker({
@@ -72,6 +80,7 @@ export function useSessionPicker({
   centerSelection = false,
   initialSessions,
   isActive = true,
+  enablePreview = false,
 }: UseSessionPickerOptions): UseSessionPickerResult {
   const hasInitialSessions = initialSessions !== undefined;
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -86,6 +95,15 @@ export function useSessionPicker({
   // For follow mode (non-centered)
   const [followScrollOffset, setFollowScrollOffset] = useState(0);
 
+  // Preview view state.
+  const [viewMode, setViewMode] = useState<'list' | 'preview'>('list');
+  const [previewSessionId, setPreviewSessionId] = useState<string | null>(null);
+
+  const exitPreview = useCallback(() => {
+    setViewMode('list');
+    setPreviewSessionId(null);
+  }, []);
+
   const isLoadingMoreRef = useRef(false);
 
   const filteredSessions = useMemo(
@@ -213,6 +231,12 @@ export function useSessionPicker({
   // Key handling (KeypressContext)
   useKeypress(
     (key) => {
+      // Preview owns the keyboard while active; suppress list-mode
+      // handlers so we don't double-handle Escape / Enter / navigation.
+      if (viewMode !== 'list') {
+        return;
+      }
+
       const { name, sequence, ctrl } = key;
 
       if (name === 'escape' || (ctrl && name === 'c')) {
@@ -264,13 +288,22 @@ export function useSessionPicker({
         return;
       }
 
+      if (name === 'space' && enablePreview) {
+        const session = filteredSessions[selectedIndex];
+        if (session) {
+          setPreviewSessionId(session.sessionId);
+          setViewMode('preview');
+        }
+        return;
+      }
+
       if (sequence === 'b' || sequence === 'B') {
         if (currentBranch) {
           setFilterByBranch((prev) => !prev);
         }
       }
     },
-    { isActive },
+    { isActive: isActive && viewMode === 'list' },
   );
 
   return {
@@ -284,5 +317,8 @@ export function useSessionPicker({
     showScrollUp,
     showScrollDown,
     loadMoreSessions,
+    viewMode,
+    previewSessionId,
+    exitPreview,
   };
 }
diff --git a/packages/cli/src/ui/hooks/useSlashCompletion.test.ts b/packages/cli/src/ui/hooks/useSlashCompletion.test.ts
index a526ce6b3..dbe7a601c 100644
--- a/packages/cli/src/ui/hooks/useSlashCompletion.test.ts
+++ b/packages/cli/src/ui/hooks/useSlashCompletion.test.ts
@@ -246,6 +246,35 @@ describe('useSlashCompletion', () => {
       });
     });
 
+    it('should keep argumentHint out of command suggestion labels', async () => {
+      const slashCommands = [
+        createTestCommand({
+          name: 'fix-issue',
+          description: 'Fix GitHub issue',
+          argumentHint: '[issue-number]',
+        }),
+      ];
+      const { result } = renderHook(() =>
+        useTestHarnessForSlashCompletion(
+          true,
+          '/fix',
+          slashCommands,
+          mockCommandContext,
+        ),
+      );
+
+      await waitFor(() => {
+        expect(result.current.suggestions).toEqual([
+          {
+            label: 'fix-issue',
+            value: 'fix-issue',
+            description: 'Fix GitHub issue',
+            commandKind: CommandKind.BUILT_IN,
+          },
+        ]);
+      });
+    });
+
     it('should prefer higher completionPriority when match quality ties', async () => {
       const slashCommands = [
         createTestCommand({
diff --git a/packages/cli/src/ui/hooks/useTerminalNotification.test.ts b/packages/cli/src/ui/hooks/useTerminalNotification.test.ts
new file mode 100644
index 000000000..2cde12971
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useTerminalNotification.test.ts
@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { buildTerminalNotification } from './useTerminalNotification.js';
+
+describe('buildTerminalNotification', () => {
+  const originalEnv = { ...process.env };
+  const writeRaw = vi.fn();
+
+  afterEach(() => {
+    writeRaw.mockReset();
+    process.env = { ...originalEnv };
+  });
+
+  it('notifyITerm2 writes OSC 9 sequence', () => {
+    process.env['TERM_PROGRAM'] = 'iTerm.app';
+    delete process.env['TERM'];
+    const terminal = buildTerminalNotification(writeRaw);
+    terminal.notifyITerm2({ message: 'Hello', title: 'Test' });
+    expect(writeRaw).toHaveBeenCalledTimes(1);
+    const written = writeRaw.mock.calls[0]![0] as string;
+    expect(written).toContain('Test:\nHello');
+    expect(written).toContain('\x1b]9;');
+  });
+
+  it('notifyKitty writes three OSC 99 sequences', () => {
+    process.env['TERM'] = 'xterm-kitty';
+    delete process.env['TERM_PROGRAM'];
+    const terminal = buildTerminalNotification(writeRaw);
+    terminal.notifyKitty({ message: 'Body', title: 'Title', id: 7 });
+    expect(writeRaw).toHaveBeenCalledTimes(3);
+    const calls = writeRaw.mock.calls.map((c) => c[0] as string);
+    expect(calls[0]).toContain('i=7:d=0:p=title');
+    expect(calls[1]).toContain('i=7:p=body');
+    expect(calls[2]).toContain('i=7:d=1:a=focus');
+  });
+
+  it('notifyGhostty writes OSC 777 sequence', () => {
+    process.env['TERM_PROGRAM'] = 'ghostty';
+    delete process.env['TERM'];
+    const terminal = buildTerminalNotification(writeRaw);
+    terminal.notifyGhostty({ message: 'Body', title: 'Title' });
+    expect(writeRaw).toHaveBeenCalledTimes(1);
+    const written = writeRaw.mock.calls[0]![0] as string;
+    expect(written).toContain('777;notify;Title;Body');
+  });
+
+  it('notifyBell writes raw BEL without wrapping', () => {
+    process.env['TMUX'] = '/tmp/tmux';
+    const terminal = buildTerminalNotification(writeRaw);
+    terminal.notifyBell();
+    expect(writeRaw).toHaveBeenCalledWith('\x07');
+    // BEL should NOT be wrapped in DCS passthrough
+    expect(writeRaw.mock.calls[0]![0]).not.toContain('\x1bPtmux');
+  });
+});
diff --git a/packages/cli/src/ui/hooks/useTerminalNotification.ts b/packages/cli/src/ui/hooks/useTerminalNotification.ts
new file mode 100644
index 000000000..775031897
--- /dev/null
+++ b/packages/cli/src/ui/hooks/useTerminalNotification.ts
@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * React hook and context for writing raw escape sequences to the terminal,
+ * bypassing Ink's stdout interception.
+ *
+ * Provides per-protocol notification helpers (iTerm2 / Kitty / Ghostty / Bell)
+ * and terminal progress reporting.
+ */
+
+import {
+  BEL,
+  wrapForMultiplexer,
+  oscITerm2Notify,
+  oscKittyNotify,
+  oscGhosttyNotify,
+} from '../../utils/osc.js';
+
+// ── Types ──────────────────────────────────────────────────────────
+
+type WriteRaw = (data: string) => void;
+
+export interface TerminalNotification {
+  notifyITerm2: (opts: { message: string; title?: string }) => void;
+  notifyKitty: (opts: { message: string; title: string; id: number }) => void;
+  notifyGhostty: (opts: { message: string; title: string }) => void;
+  notifyBell: () => void;
+}
+
+// ── Factory (no React context needed) ──────────────────────────────
+
+/**
+ * Build a TerminalNotification object from a raw write function.
+ * Useful when the caller already has stdout.write and does not need
+ * (or cannot use) TerminalWriteContext (e.g. in AppContainer's body
+ * before the provider is mounted in the JSX tree).
+ */
+export function buildTerminalNotification(
+  writeRaw: WriteRaw,
+): TerminalNotification {
+  return {
+    notifyITerm2({ message, title }) {
+      writeRaw(wrapForMultiplexer(oscITerm2Notify(title ?? '', message)));
+    },
+    notifyKitty({ message, title, id }) {
+      for (const seq of oscKittyNotify(title, message, id)) {
+        writeRaw(wrapForMultiplexer(seq));
+      }
+    },
+    notifyGhostty({ message, title }) {
+      writeRaw(wrapForMultiplexer(oscGhosttyNotify(title, message)));
+    },
+    notifyBell() {
+      // Raw BEL — inside tmux this triggers tmux's bell-action (window flag).
+      // Wrapping would make it opaque DCS payload and lose that fallback.
+      writeRaw(BEL);
+    },
+  };
+}
diff --git a/packages/cli/src/ui/hooks/useTerminalProgress.ts b/packages/cli/src/ui/hooks/useTerminalProgress.ts
index 779b9205b..754a8aeb4 100644
--- a/packages/cli/src/ui/hooks/useTerminalProgress.ts
+++ b/packages/cli/src/ui/hooks/useTerminalProgress.ts
@@ -7,6 +7,12 @@
 import { useEffect, useCallback } from 'react';
 import { useStdout } from 'ink';
 import { StreamingState } from '../types.js';
+import {
+  OSC_PREFIX,
+  BEL,
+  wrapForMultiplexer,
+  detectTerminal,
+} from '../../utils/osc.js';
 
 /**
  * OSC 9;4 progress sequences for terminal tab/title bar progress.
@@ -15,32 +21,14 @@ import { StreamingState } from '../types.js';
  * @see https://iterm2.com/documentation-escape-codes.html
  * @see https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences
  */
-const OSC = '\x1b]';
-const BEL = '\x07';
-
-/**
- * Wrap an OSC sequence for tmux/screen passthrough.
- * tmux requires DCS escape: \ePtmux;\e<seq>\e\\
- * screen requires DCS escape: \eP<seq>\e\\
- */
-function wrapForMultiplexer(seq: string): string {
-  if (process.env['TMUX']) {
-    return `\x1bPtmux;\x1b${seq}\x1b\\`;
-  }
-  if (process.env['STY']) {
-    return `\x1bP${seq}\x1b\\`;
-  }
-  return seq;
-}
-
-const PROGRESS_CLEAR = wrapForMultiplexer(`${OSC}9;4;0;${BEL}`);
-const PROGRESS_INDETERMINATE = wrapForMultiplexer(`${OSC}9;4;3;;${BEL}`);
+const PROGRESS_CLEAR = wrapForMultiplexer(`${OSC_PREFIX}9;4;0;${BEL}`);
+const PROGRESS_INDETERMINATE = wrapForMultiplexer(`${OSC_PREFIX}9;4;3;;${BEL}`);
 
 function isProgressBarSupported(): boolean {
   // Don't emit escape sequences when stdout is not a TTY (CI, piped output,
   // redirected to log files, etc.)
   if (!process.stdout?.isTTY) return false;
-  const term = process.env['TERM_PROGRAM'];
+  const term = detectTerminal();
   if (term === 'iTerm.app') return true;
   if (term === 'ghostty') return true;
   if (process.env['ConEmuPID']) return true;
diff --git a/packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx b/packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx
new file mode 100644
index 000000000..29aab2f93
--- /dev/null
+++ b/packages/cli/src/ui/layouts/DefaultAppLayout.test.tsx
@@ -0,0 +1,183 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it, vi, type Mock } from 'vitest';
+import { render } from 'ink-testing-library';
+import { Text } from 'ink';
+import { DefaultAppLayout } from './DefaultAppLayout.js';
+import { UIStateContext, type UIState } from '../contexts/UIStateContext.js';
+import {
+  UIActionsContext,
+  type UIActions,
+} from '../contexts/UIActionsContext.js';
+import { useAgentViewState } from '../contexts/AgentViewContext.js';
+import { StreamingState } from '../types.js';
+
+vi.mock('../components/MainContent.js', () => ({
+  MainContent: () => <Text>MainContent</Text>,
+}));
+
+vi.mock('../components/DialogManager.js', () => ({
+  DialogManager: () => <Text>DialogManager</Text>,
+}));
+
+vi.mock('../components/Composer.js', () => ({
+  Composer: () => <Text>Composer</Text>,
+}));
+
+vi.mock('../components/ExitWarning.js', () => ({
+  ExitWarning: () => <Text>ExitWarning</Text>,
+}));
+
+vi.mock('../components/messages/BtwMessage.js', () => ({
+  BtwMessage: () => <Text>BtwMessage</Text>,
+}));
+
+vi.mock('../components/StickyTodoList.js', () => ({
+  StickyTodoList: () => <Text>StickyTodoList</Text>,
+}));
+
+vi.mock('../components/agent-view/AgentTabBar.js', () => ({
+  AgentTabBar: () => <Text>AgentTabBar</Text>,
+}));
+
+vi.mock('../components/agent-view/AgentChatView.js', () => ({
+  AgentChatView: () => <Text>AgentChatView</Text>,
+}));
+
+vi.mock('../components/agent-view/AgentComposer.js', () => ({
+  AgentComposer: () => <Text>AgentComposer</Text>,
+}));
+
+vi.mock('../hooks/useTerminalSize.js', () => ({
+  useTerminalSize: () => ({ columns: 80 }),
+}));
+
+vi.mock('../contexts/AgentViewContext.js', () => ({
+  useAgentViewState: vi.fn(),
+}));
+
+const mockedUseAgentViewState = useAgentViewState as Mock;
+
+const mockUIActions = {
+  refreshStatic: vi.fn(),
+} as unknown as UIActions;
+
+const baseUIState: Partial<UIState> = {
+  dialogsVisible: false,
+  isFeedbackDialogOpen: false,
+  mainControlsRef: { current: null },
+  mainAreaWidth: 80,
+  terminalWidth: 80,
+  streamingState: StreamingState.Idle,
+  historyManager: {
+    addItem: vi.fn(),
+    history: [],
+    updateItem: vi.fn(),
+    clearItems: vi.fn(),
+    loadHistory: vi.fn(),
+    truncateToItem: vi.fn(),
+  },
+  stickyTodos: [
+    {
+      id: 'todo-1',
+      content: 'Pinned task',
+      status: 'pending',
+    },
+  ],
+  btwItem: null,
+};
+
+const renderLayout = (uiState: Partial<UIState>) =>
+  render(
+    <UIActionsContext.Provider value={mockUIActions}>
+      <UIStateContext.Provider value={uiState as UIState}>
+        <DefaultAppLayout />
+      </UIStateContext.Provider>
+    </UIActionsContext.Provider>,
+  );
+
+describe('DefaultAppLayout', () => {
+  it('renders sticky todo list before the composer in the main view', () => {
+    mockedUseAgentViewState.mockReturnValue({
+      activeView: 'main',
+      agents: new Map(),
+    });
+
+    const { lastFrame } = renderLayout(baseUIState);
+    const output = lastFrame() ?? '';
+
+    expect(output).toContain('StickyTodoList');
+    expect(output.indexOf('StickyTodoList')).toBeGreaterThan(
+      output.indexOf('MainContent'),
+    );
+    expect(output.indexOf('StickyTodoList')).toBeLessThan(
+      output.indexOf('Composer'),
+    );
+  });
+
+  it('does not render sticky todo list when dialogs are visible', () => {
+    mockedUseAgentViewState.mockReturnValue({
+      activeView: 'main',
+      agents: new Map(),
+    });
+
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      dialogsVisible: true,
+    });
+
+    const output = lastFrame() ?? '';
+    expect(output).not.toContain('StickyTodoList');
+    expect(output).toContain('DialogManager');
+  });
+
+  it('does not render sticky todo list while waiting for confirmation', () => {
+    mockedUseAgentViewState.mockReturnValue({
+      activeView: 'main',
+      agents: new Map(),
+    });
+
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      streamingState: StreamingState.WaitingForConfirmation,
+    });
+
+    const output = lastFrame() ?? '';
+    expect(output).not.toContain('StickyTodoList');
+    expect(output).toContain('Composer');
+  });
+
+  it('does not render sticky todo list when feedback dialog is open', () => {
+    mockedUseAgentViewState.mockReturnValue({
+      activeView: 'main',
+      agents: new Map(),
+    });
+
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      isFeedbackDialogOpen: true,
+    });
+
+    const output = lastFrame() ?? '';
+    expect(output).not.toContain('StickyTodoList');
+    expect(output).toContain('Composer');
+  });
+
+  it('does not render sticky todo list in an agent tab view', () => {
+    mockedUseAgentViewState.mockReturnValue({
+      activeView: 'agent-1',
+      agents: new Map([['agent-1', {}]]),
+    });
+
+    const { lastFrame } = renderLayout(baseUIState);
+
+    const output = lastFrame() ?? '';
+    expect(output).not.toContain('StickyTodoList');
+    expect(output).toContain('AgentChatView');
+    expect(output).toContain('AgentComposer');
+  });
+});
diff --git a/packages/cli/src/ui/layouts/DefaultAppLayout.tsx b/packages/cli/src/ui/layouts/DefaultAppLayout.tsx
index 88efdbefd..f66e5a713 100644
--- a/packages/cli/src/ui/layouts/DefaultAppLayout.tsx
+++ b/packages/cli/src/ui/layouts/DefaultAppLayout.tsx
@@ -11,6 +11,7 @@ import { MainContent } from '../components/MainContent.js';
 import { DialogManager } from '../components/DialogManager.js';
 import { Composer } from '../components/Composer.js';
 import { ExitWarning } from '../components/ExitWarning.js';
+import { StickyTodoList } from '../components/StickyTodoList.js';
 import { BtwMessage } from '../components/messages/BtwMessage.js';
 import { AgentTabBar } from '../components/agent-view/AgentTabBar.js';
 import { AgentChatView } from '../components/agent-view/AgentChatView.js';
@@ -19,6 +20,7 @@ import { useUIState } from '../contexts/UIStateContext.js';
 import { useUIActions } from '../contexts/UIActionsContext.js';
 import { useAgentViewState } from '../contexts/AgentViewContext.js';
 import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { StreamingState } from '../types.js';
 
 export const DefaultAppLayout: React.FC = () => {
   const uiState = useUIState();
@@ -27,6 +29,12 @@ export const DefaultAppLayout: React.FC = () => {
   const { columns: terminalWidth } = useTerminalSize();
   const hasAgents = agents.size > 0;
   const isAgentTab = activeView !== 'main' && agents.has(activeView);
+  const stickyTodoWidth = Math.min(uiState.mainAreaWidth, 64);
+  const shouldShowStickyTodos =
+    uiState.stickyTodos !== null &&
+    !uiState.dialogsVisible &&
+    !uiState.isFeedbackDialogOpen &&
+    uiState.streamingState !== StreamingState.WaitingForConfirmation;
 
   // Clear terminal on view switch so previous view's <Static> output
   // is removed. refreshStatic clears the terminal and bumps the
@@ -69,6 +77,12 @@ export const DefaultAppLayout: React.FC = () => {
               </Box>
             ) : (
               <>
+                {shouldShowStickyTodos && (
+                  <StickyTodoList
+                    todos={uiState.stickyTodos!}
+                    width={stickyTodoWidth}
+                  />
+                )}
                 {uiState.btwItem && (
                   <Box marginX={2} width={uiState.mainAreaWidth}>
                     <BtwMessage
diff --git a/packages/cli/src/ui/layouts/ScreenReaderAppLayout.test.tsx b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.test.tsx
new file mode 100644
index 000000000..297308098
--- /dev/null
+++ b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.test.tsx
@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { render } from 'ink-testing-library';
+import { Text } from 'ink';
+import { ScreenReaderAppLayout } from './ScreenReaderAppLayout.js';
+import { UIStateContext, type UIState } from '../contexts/UIStateContext.js';
+import { StreamingState } from '../types.js';
+
+vi.mock('../components/Notifications.js', () => ({
+  Notifications: () => <Text>Notifications</Text>,
+}));
+
+vi.mock('../components/MainContent.js', () => ({
+  MainContent: () => <Text>MainContent</Text>,
+}));
+
+vi.mock('../components/DialogManager.js', () => ({
+  DialogManager: () => <Text>DialogManager</Text>,
+}));
+
+vi.mock('../components/Composer.js', () => ({
+  Composer: () => <Text>Composer</Text>,
+}));
+
+vi.mock('../components/Footer.js', () => ({
+  Footer: () => <Text>Footer</Text>,
+}));
+
+vi.mock('../components/ExitWarning.js', () => ({
+  ExitWarning: () => <Text>ExitWarning</Text>,
+}));
+
+vi.mock('../components/messages/BtwMessage.js', () => ({
+  BtwMessage: () => <Text>BtwMessage</Text>,
+}));
+
+vi.mock('../components/StickyTodoList.js', () => ({
+  StickyTodoList: () => <Text>StickyTodoList</Text>,
+}));
+
+const baseUIState: Partial<UIState> = {
+  dialogsVisible: false,
+  isFeedbackDialogOpen: false,
+  mainAreaWidth: 80,
+  terminalWidth: 80,
+  streamingState: StreamingState.Idle,
+  historyManager: {
+    addItem: vi.fn(),
+    history: [],
+    updateItem: vi.fn(),
+    clearItems: vi.fn(),
+    loadHistory: vi.fn(),
+    truncateToItem: vi.fn(),
+  },
+  stickyTodos: [
+    {
+      id: 'todo-1',
+      content: 'Pinned task',
+      status: 'pending',
+    },
+  ],
+  btwItem: null,
+};
+
+const renderLayout = (uiState: Partial<UIState>) =>
+  render(
+    <UIStateContext.Provider value={uiState as UIState}>
+      <ScreenReaderAppLayout />
+    </UIStateContext.Provider>,
+  );
+
+describe('ScreenReaderAppLayout', () => {
+  it('renders sticky todo list before the composer', () => {
+    const { lastFrame } = renderLayout(baseUIState);
+    const output = lastFrame() ?? '';
+
+    expect(output).toContain('StickyTodoList');
+    expect(output.indexOf('StickyTodoList')).toBeGreaterThan(
+      output.indexOf('MainContent'),
+    );
+    expect(output.indexOf('StickyTodoList')).toBeLessThan(
+      output.indexOf('Composer'),
+    );
+  });
+
+  it('does not render sticky todo list when dialogs are visible', () => {
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      dialogsVisible: true,
+    });
+
+    const output = lastFrame() ?? '';
+    expect(output).not.toContain('StickyTodoList');
+    expect(output).toContain('DialogManager');
+  });
+
+  it('does not render sticky todo list while waiting for confirmation', () => {
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      streamingState: StreamingState.WaitingForConfirmation,
+    });
+
+    const output = lastFrame() ?? '';
+    expect(output).not.toContain('StickyTodoList');
+    expect(output).toContain('Composer');
+  });
+
+  it('does not render sticky todo list when feedback dialog is open', () => {
+    const { lastFrame } = renderLayout({
+      ...baseUIState,
+      isFeedbackDialogOpen: true,
+    });
+
+    const output = lastFrame() ?? '';
+    expect(output).not.toContain('StickyTodoList');
+    expect(output).toContain('Composer');
+  });
+});
diff --git a/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx
index e601db4b9..b79eda8ec 100644
--- a/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx
+++ b/packages/cli/src/ui/layouts/ScreenReaderAppLayout.tsx
@@ -12,11 +12,19 @@ import { DialogManager } from '../components/DialogManager.js';
 import { Composer } from '../components/Composer.js';
 import { Footer } from '../components/Footer.js';
 import { ExitWarning } from '../components/ExitWarning.js';
+import { StickyTodoList } from '../components/StickyTodoList.js';
 import { BtwMessage } from '../components/messages/BtwMessage.js';
 import { useUIState } from '../contexts/UIStateContext.js';
+import { StreamingState } from '../types.js';
 
 export const ScreenReaderAppLayout: React.FC = () => {
   const uiState = useUIState();
+  const stickyTodoWidth = Math.min(uiState.mainAreaWidth, 64);
+  const shouldShowStickyTodos =
+    uiState.stickyTodos !== null &&
+    !uiState.dialogsVisible &&
+    !uiState.isFeedbackDialogOpen &&
+    uiState.streamingState !== StreamingState.WaitingForConfirmation;
 
   return (
     <Box flexDirection="column" width="90%" height="100%">
@@ -35,6 +43,12 @@ export const ScreenReaderAppLayout: React.FC = () => {
         </Box>
       ) : (
         <>
+          {shouldShowStickyTodos && (
+            <StickyTodoList
+              todos={uiState.stickyTodos!}
+              width={stickyTodoWidth}
+            />
+          )}
           {uiState.btwItem && (
             <Box marginX={2} width={uiState.mainAreaWidth}>
               <BtwMessage
diff --git a/packages/cli/src/ui/manageModels/manageModels.test.ts b/packages/cli/src/ui/manageModels/manageModels.test.ts
new file mode 100644
index 000000000..8ad3568c8
--- /dev/null
+++ b/packages/cli/src/ui/manageModels/manageModels.test.ts
@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  AuthType,
+  type Config,
+  type ModelProvidersConfig,
+} from '@qwen-code/qwen-code-core';
+import type { LoadedSettings } from '../../config/settings.js';
+import {
+  fetchManageModelsCatalog,
+  getEnabledModelIdsForSource,
+  saveManageModelsSelection,
+} from './manageModels.js';
+
+const {
+  mockFetchOpenRouterModels,
+  mockMergeOpenRouterConfigs,
+  mockIsOpenRouterConfig,
+} = vi.hoisted(() => ({
+  mockFetchOpenRouterModels: vi.fn(),
+  mockMergeOpenRouterConfigs: vi.fn(),
+  mockIsOpenRouterConfig: vi.fn(),
+}));
+
+vi.mock('../../commands/auth/openrouterOAuth.js', () => ({
+  OPENROUTER_DEFAULT_MODEL: 'openai/gpt-4o-mini',
+  fetchOpenRouterModels: mockFetchOpenRouterModels,
+  mergeOpenRouterConfigs: mockMergeOpenRouterConfigs,
+  isOpenRouterConfig: mockIsOpenRouterConfig,
+}));
+
+describe('manageModels', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('fetchManageModelsCatalog maps OpenRouter models into catalog entries', async () => {
+    mockFetchOpenRouterModels.mockResolvedValue([
+      {
+        id: 'qwen/qwen3-coder:free',
+        name: 'OpenRouter · Qwen3 Coder',
+        capabilities: { vision: true },
+        generationConfig: { contextWindowSize: 1_000_000 },
+      },
+    ]);
+
+    const catalog = await fetchManageModelsCatalog('openrouter');
+
+    expect(catalog.source).toBe('openrouter');
+    expect(catalog.entries).toHaveLength(1);
+    expect(catalog.entries[0]?.label).toBe('Qwen3 Coder');
+    expect(catalog.entries[0]?.badges).toEqual(
+      expect.arrayContaining(['free', 'vision', 'long-context']),
+    );
+  });
+
+  it('getEnabledModelIdsForSource only returns OpenRouter-enabled ids', () => {
+    mockIsOpenRouterConfig.mockImplementation(
+      (config: { baseUrl?: string }) =>
+        config.baseUrl?.includes('openrouter') ?? false,
+    );
+
+    const settings = {
+      merged: {
+        modelProviders: {
+          [AuthType.USE_OPENAI]: [
+            {
+              id: 'openai/gpt-4o-mini',
+              baseUrl: 'https://openrouter.ai/api/v1',
+            },
+            { id: 'custom/model', baseUrl: 'https://example.com/v1' },
+          ],
+        },
+      },
+    } as unknown as LoadedSettings;
+
+    expect(getEnabledModelIdsForSource('openrouter', settings)).toEqual([
+      'openai/gpt-4o-mini',
+    ]);
+  });
+
+  it('saveManageModelsSelection merges selected OpenRouter models and reloads config', async () => {
+    const settings = {
+      isTrusted: false,
+      user: { settings: { modelProviders: {} } },
+      workspace: { settings: {} },
+      merged: {
+        modelProviders: {
+          [AuthType.USE_OPENAI]: [
+            { id: 'old-openrouter', baseUrl: 'https://openrouter.ai/api/v1' },
+            { id: 'custom/model', baseUrl: 'https://example.com/v1' },
+          ],
+        } satisfies ModelProvidersConfig,
+      },
+      setValue: vi.fn(),
+    } as unknown as LoadedSettings;
+
+    const config = {
+      getContentGeneratorConfig: vi
+        .fn()
+        .mockReturnValue({ authType: AuthType.USE_OPENAI }),
+      getModel: vi.fn().mockReturnValue('old-openrouter'),
+      reloadModelProvidersConfig: vi.fn(),
+      refreshAuth: vi.fn().mockResolvedValue(undefined),
+    } as unknown as Config;
+
+    mockMergeOpenRouterConfigs.mockReturnValue([
+      { id: 'openai/gpt-4o-mini', baseUrl: 'https://openrouter.ai/api/v1' },
+      { id: 'custom/model', baseUrl: 'https://example.com/v1' },
+    ]);
+
+    const result = await saveManageModelsSelection({
+      source: 'openrouter',
+      selectedModels: [
+        { id: 'openai/gpt-4o-mini', baseUrl: 'https://openrouter.ai/api/v1' },
+      ],
+      settings,
+      config,
+    });
+
+    expect(mockMergeOpenRouterConfigs).toHaveBeenCalled();
+    expect(settings.setValue).toHaveBeenCalledWith(
+      expect.anything(),
+      `modelProviders.${AuthType.USE_OPENAI}`,
+      [
+        { id: 'openai/gpt-4o-mini', baseUrl: 'https://openrouter.ai/api/v1' },
+        { id: 'custom/model', baseUrl: 'https://example.com/v1' },
+      ],
+    );
+    expect(config.reloadModelProvidersConfig).toHaveBeenCalled();
+    expect(config.refreshAuth).toHaveBeenCalledWith(AuthType.USE_OPENAI);
+    expect(result.selectedIds).toEqual(['openai/gpt-4o-mini']);
+    expect(result.activeModelId).toBe('openai/gpt-4o-mini');
+  });
+});
diff --git a/packages/cli/src/ui/manageModels/manageModels.ts b/packages/cli/src/ui/manageModels/manageModels.ts
new file mode 100644
index 000000000..c2d4bfe12
--- /dev/null
+++ b/packages/cli/src/ui/manageModels/manageModels.ts
@@ -0,0 +1,211 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  AuthType,
+  type Config,
+  type ProviderModelConfig as ModelConfig,
+  type ModelProvidersConfig,
+} from '@qwen-code/qwen-code-core';
+import type { LoadedSettings } from '../../config/settings.js';
+import { getPersistScopeForModelSelection } from '../../config/modelProvidersScope.js';
+import {
+  OPENROUTER_DEFAULT_MODEL,
+  fetchOpenRouterModels,
+  isOpenRouterConfig,
+  mergeOpenRouterConfigs,
+} from '../../commands/auth/openrouterOAuth.js';
+
+export const MANAGE_MODELS_SOURCES = ['openrouter'] as const;
+
+export type ManageModelsSource = (typeof MANAGE_MODELS_SOURCES)[number];
+
+export interface ManageModelsCatalogEntry {
+  id: string;
+  label: string;
+  searchText: string;
+  supportsVision: boolean;
+  contextWindowSize?: number;
+  badges: string[];
+  model: ModelConfig;
+}
+
+export interface ManageModelsCatalog {
+  source: ManageModelsSource;
+  title: string;
+  description: string;
+  authType: AuthType;
+  entries: ManageModelsCatalogEntry[];
+}
+
+export interface ManageModelsSaveResult {
+  updatedConfigs: ModelConfig[];
+  selectedIds: string[];
+  activeModelId?: string;
+}
+
+function isFreeOpenRouterModel(modelId: string): boolean {
+  const normalizedId = modelId.toLowerCase();
+  return normalizedId.includes(':free') || normalizedId === 'openrouter/free';
+}
+
+function getManageModelsDisplayLabel(
+  source: ManageModelsSource,
+  model: ModelConfig,
+): string {
+  const rawLabel = model.name || model.id;
+
+  switch (source) {
+    case 'openrouter':
+      return rawLabel.replace(/^OpenRouter\s*·\s*/i, '').trim() || model.id;
+    default:
+      return rawLabel;
+  }
+}
+
+function createEntry(
+  source: ManageModelsSource,
+  model: ModelConfig,
+): ManageModelsCatalogEntry {
+  const contextWindowSize = model.generationConfig?.contextWindowSize;
+  const supportsVision = model.capabilities?.vision === true;
+  const badges: string[] = [];
+
+  if (isFreeOpenRouterModel(model.id)) {
+    badges.push('free');
+  }
+  if (supportsVision) {
+    badges.push('vision');
+  }
+  if (typeof contextWindowSize === 'number' && contextWindowSize >= 1_000_000) {
+    badges.push('long-context');
+  }
+
+  const displayLabel = getManageModelsDisplayLabel(source, model);
+
+  return {
+    id: model.id,
+    label: displayLabel,
+    searchText: [model.id, model.name, displayLabel, ...badges]
+      .filter(Boolean)
+      .join(' '),
+    supportsVision,
+    contextWindowSize,
+    badges,
+    model,
+  };
+}
+
+export async function fetchManageModelsCatalog(
+  source: ManageModelsSource,
+): Promise<ManageModelsCatalog> {
+  switch (source) {
+    case 'openrouter': {
+      const models = await fetchOpenRouterModels();
+      return {
+        source,
+        title: 'OpenRouter',
+        description:
+          'Browse the latest OpenRouter model catalog and choose which models are enabled locally.',
+        authType: AuthType.USE_OPENAI,
+        entries: models.map((model) => createEntry(source, model)),
+      };
+    }
+    default:
+      throw new Error(`Unsupported manage models source: ${source}`);
+  }
+}
+
+export function getEnabledModelIdsForSource(
+  source: ManageModelsSource,
+  settings: LoadedSettings,
+): string[] {
+  const modelProviders = settings.merged.modelProviders as
+    | ModelProvidersConfig
+    | undefined;
+  const openaiConfigs = modelProviders?.[AuthType.USE_OPENAI] || [];
+
+  switch (source) {
+    case 'openrouter':
+      return openaiConfigs
+        .filter((config) => isOpenRouterConfig(config))
+        .map((config) => config.id);
+    default:
+      return [];
+  }
+}
+
+export async function saveManageModelsSelection(params: {
+  source: ManageModelsSource;
+  selectedModels: ModelConfig[];
+  settings: LoadedSettings;
+  config: Config;
+}): Promise<ManageModelsSaveResult> {
+  const { source, selectedModels, settings, config } = params;
+  const persistScope = getPersistScopeForModelSelection(settings);
+  const mergedModelProviders = settings.merged.modelProviders as
+    | ModelProvidersConfig
+    | undefined;
+  const existingOpenAIConfigs =
+    mergedModelProviders?.[AuthType.USE_OPENAI] || [];
+
+  switch (source) {
+    case 'openrouter': {
+      const updatedConfigs = mergeOpenRouterConfigs(
+        existingOpenAIConfigs,
+        selectedModels,
+      );
+
+      if (updatedConfigs.length === 0) {
+        throw new Error(
+          'At least one OpenAI-compatible model must remain enabled.',
+        );
+      }
+
+      settings.setValue(
+        persistScope,
+        `modelProviders.${AuthType.USE_OPENAI}`,
+        updatedConfigs,
+      );
+
+      const selectedIds = selectedModels.map((model) => model.id);
+      const currentAuthType = config.getContentGeneratorConfig()?.authType;
+      const currentModelId = config.getModel();
+      const currentModelStillAvailable = currentModelId
+        ? updatedConfigs.some((model) => model.id === currentModelId)
+        : false;
+
+      let activeModelId = currentModelId;
+      if (!currentModelStillAvailable) {
+        const preferredDefault = updatedConfigs.find(
+          (model) => model.id === OPENROUTER_DEFAULT_MODEL,
+        );
+        activeModelId = preferredDefault?.id || updatedConfigs[0]?.id;
+        if (activeModelId) {
+          settings.setValue(persistScope, 'model.name', activeModelId);
+        }
+      }
+
+      const updatedModelProviders: ModelProvidersConfig = {
+        ...(mergedModelProviders || {}),
+        [AuthType.USE_OPENAI]: updatedConfigs,
+      };
+      config.reloadModelProvidersConfig(updatedModelProviders);
+
+      if (currentAuthType === AuthType.USE_OPENAI) {
+        await config.refreshAuth(AuthType.USE_OPENAI);
+      }
+
+      return {
+        updatedConfigs,
+        selectedIds,
+        activeModelId,
+      };
+    }
+    default:
+      throw new Error(`Unsupported manage models source: ${source}`);
+  }
+}
diff --git a/packages/cli/src/ui/types.ts b/packages/cli/src/ui/types.ts
index 775537da9..b29e31588 100644
--- a/packages/cli/src/ui/types.ts
+++ b/packages/cli/src/ui/types.ts
@@ -210,6 +210,19 @@ export type HistoryItemToolGroup = HistoryItemBase & {
   isUserInitiated?: boolean;
 };
 
+/**
+ * Short LLM-generated label summarizing a preceding tool batch. Emitted after
+ * the batch completes and consumed by compact-mode rendering to replace the
+ * generic "Tool × N" line with something like "Searched in auth/". Also
+ * surfaces to SDK clients as a `tool_use_summary` stream message.
+ */
+export type HistoryItemToolUseSummary = HistoryItemBase & {
+  type: 'tool_use_summary';
+  summary: string;
+  /** Tool callIds this summary describes. Used to locate the target tool_group. */
+  precedingToolUseIds: string[];
+};
+
 export type HistoryItemNotification = HistoryItemBase & {
   type: 'notification';
   text: string;
@@ -471,6 +484,7 @@ export type HistoryItemWithoutId =
   | HistoryItemAbout
   | HistoryItemHelp
   | HistoryItemToolGroup
+  | HistoryItemToolUseSummary
   | HistoryItemStats
   | HistoryItemModelStats
   | HistoryItemToolStats
diff --git a/packages/cli/src/ui/utils/gradientUtils.ts b/packages/cli/src/ui/utils/gradientUtils.ts
new file mode 100644
index 000000000..0c164768a
--- /dev/null
+++ b/packages/cli/src/ui/utils/gradientUtils.ts
@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export function getRenderableGradientColors(
+  ...candidates: Array<string[] | undefined>
+): string[] | undefined {
+  return candidates.find(
+    (colors): colors is string[] =>
+      Array.isArray(colors) &&
+      colors.length >= 2 &&
+      colors.every(
+        (color) => typeof color === 'string' && color.trim().length > 0,
+      ),
+  );
+}
diff --git a/packages/cli/src/ui/utils/historyMapping.test.ts b/packages/cli/src/ui/utils/historyMapping.test.ts
new file mode 100644
index 000000000..84c18a2ff
--- /dev/null
+++ b/packages/cli/src/ui/utils/historyMapping.test.ts
@@ -0,0 +1,243 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { computeApiTruncationIndex, isRealUserTurn } from './historyMapping.js';
+import type { HistoryItem } from '../types.js';
+import type { Content, Part } from '@google/genai';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function userContent(text: string): Content {
+  return { role: 'user', parts: [{ text } as Part] };
+}
+
+function modelContent(text: string): Content {
+  return { role: 'model', parts: [{ text } as Part] };
+}
+
+function functionResponseContent(): Content {
+  return {
+    role: 'user',
+    parts: [
+      {
+        functionResponse: { name: 'tool', response: { result: 'ok' } },
+      } as unknown as Part,
+    ],
+  };
+}
+
+function startupPair(): [Content, Content] {
+  return [
+    userContent('Environment context...'),
+    modelContent('Got it. Thanks for the context!'),
+  ];
+}
+
+function userItem(id: number, text = `prompt ${id}`): HistoryItem {
+  return { type: 'user', id, text } as HistoryItem;
+}
+
+function geminiItem(id: number): HistoryItem {
+  return { type: 'gemini', id, text: `response ${id}` } as HistoryItem;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('computeApiTruncationIndex', () => {
+  it('returns 0 for empty API history', () => {
+    const ui: HistoryItem[] = [userItem(1)];
+    const api: Content[] = [];
+    expect(computeApiTruncationIndex(ui, 1, api)).toBe(0);
+  });
+
+  describe('without startup context', () => {
+    it('rewinds to the first user turn (keep nothing)', () => {
+      const ui: HistoryItem[] = [
+        userItem(1),
+        geminiItem(2),
+        userItem(3),
+        geminiItem(4),
+      ];
+      const api: Content[] = [
+        userContent('prompt 1'),
+        modelContent('response 1'),
+        userContent('prompt 3'),
+        modelContent('response 3'),
+      ];
+      // Rewind to turn 1 → keep 0 entries before it
+      expect(computeApiTruncationIndex(ui, 1, api)).toBe(0);
+    });
+
+    it('rewinds to the second user turn (keep first turn)', () => {
+      const ui: HistoryItem[] = [
+        userItem(1),
+        geminiItem(2),
+        userItem(3),
+        geminiItem(4),
+      ];
+      const api: Content[] = [
+        userContent('prompt 1'),
+        modelContent('response 1'),
+        userContent('prompt 3'),
+        modelContent('response 3'),
+      ];
+      // Rewind to turn 3 → keep entries before the second user Content
+      expect(computeApiTruncationIndex(ui, 3, api)).toBe(2);
+    });
+
+    it('rewinds to the third user turn', () => {
+      const ui: HistoryItem[] = [
+        userItem(1),
+        geminiItem(2),
+        userItem(3),
+        geminiItem(4),
+        userItem(5),
+        geminiItem(6),
+      ];
+      const api: Content[] = [
+        userContent('prompt 1'),
+        modelContent('response 1'),
+        userContent('prompt 3'),
+        modelContent('response 3'),
+        userContent('prompt 5'),
+        modelContent('response 5'),
+      ];
+      expect(computeApiTruncationIndex(ui, 5, api)).toBe(4);
+    });
+  });
+
+  describe('with startup context pair', () => {
+    it('keeps startup context when rewinding to the first turn', () => {
+      const ui: HistoryItem[] = [userItem(1), geminiItem(2)];
+      const api: Content[] = [
+        ...startupPair(),
+        userContent('prompt 1'),
+        modelContent('response 1'),
+      ];
+      // Rewind to turn 1 → keep startup pair (2 entries)
+      expect(computeApiTruncationIndex(ui, 1, api)).toBe(2);
+    });
+
+    it('keeps startup + first turn when rewinding to second turn', () => {
+      const ui: HistoryItem[] = [
+        userItem(1),
+        geminiItem(2),
+        userItem(3),
+        geminiItem(4),
+      ];
+      const api: Content[] = [
+        ...startupPair(),
+        userContent('prompt 1'),
+        modelContent('response 1'),
+        userContent('prompt 3'),
+        modelContent('response 3'),
+      ];
+      // startup(2) + turn1(2) = 4 entries to keep
+      expect(computeApiTruncationIndex(ui, 3, api)).toBe(4);
+    });
+  });
+
+  describe('with tool call entries (functionResponse)', () => {
+    it('skips functionResponse entries when counting user prompts', () => {
+      const ui: HistoryItem[] = [
+        userItem(1),
+        geminiItem(2),
+        // tool_group items are not type 'user', they don't affect the count
+        userItem(5),
+        geminiItem(6),
+      ];
+      const api: Content[] = [
+        userContent('prompt 1'),
+        modelContent('response with tool call'),
+        functionResponseContent(), // tool result — should be skipped
+        modelContent('response after tool'),
+        userContent('prompt 5'),
+        modelContent('response 5'),
+      ];
+      // Rewind to turn 5: 1 user turn before it → find the 2nd user text
+      // API walk: idx 0 = user text (count=1), idx 4 = user text (count=2 > 1) → return 4
+      expect(computeApiTruncationIndex(ui, 5, api)).toBe(4);
+    });
+  });
+
+  describe('compression fallback', () => {
+    it('returns -1 when not enough user prompts found', () => {
+      const ui: HistoryItem[] = [
+        userItem(1),
+        geminiItem(2),
+        userItem(3),
+        geminiItem(4),
+        userItem(5),
+        geminiItem(6),
+      ];
+      // After compression, API history may be shorter than expected
+      const api: Content[] = [
+        modelContent('compressed summary'),
+        userContent('prompt 5'),
+        modelContent('response 5'),
+      ];
+      // Rewind to turn 5 → 2 user turns before it, but API only has 1 user text
+      expect(computeApiTruncationIndex(ui, 5, api)).toBe(-1);
+    });
+  });
+
+  describe('with slash-command items in UI history', () => {
+    it('ignores slash-command items when counting user turns', () => {
+      const ui: HistoryItem[] = [
+        userItem(1, 'hello'),
+        geminiItem(2),
+        userItem(3, '/help'), // slash command — should be skipped
+        userItem(5, 'world'),
+        geminiItem(6),
+      ];
+      const api: Content[] = [
+        userContent('hello'),
+        modelContent('response 1'),
+        userContent('world'),
+        modelContent('response 2'),
+      ];
+      // Rewind to 'world' (id=5): 1 real user turn before it (id=1)
+      // Slash '/help' (id=3) should not be counted
+      expect(computeApiTruncationIndex(ui, 5, api)).toBe(2);
+    });
+  });
+
+  describe('single turn', () => {
+    it('handles rewinding the only turn', () => {
+      const ui: HistoryItem[] = [userItem(1), geminiItem(2)];
+      const api: Content[] = [
+        userContent('prompt 1'),
+        modelContent('response 1'),
+      ];
+      expect(computeApiTruncationIndex(ui, 1, api)).toBe(0);
+    });
+  });
+});
+
+describe('isRealUserTurn', () => {
+  it('returns true for normal user prompts', () => {
+    expect(isRealUserTurn(userItem(1, 'hello world'))).toBe(true);
+  });
+
+  it('returns false for slash commands', () => {
+    expect(isRealUserTurn(userItem(1, '/help'))).toBe(false);
+    expect(isRealUserTurn(userItem(1, '/rewind'))).toBe(false);
+    expect(isRealUserTurn(userItem(1, '/stats'))).toBe(false);
+  });
+
+  it('returns false for ? commands', () => {
+    expect(isRealUserTurn(userItem(1, '?help'))).toBe(false);
+  });
+
+  it('returns false for non-user items', () => {
+    expect(isRealUserTurn(geminiItem(1))).toBe(false);
+  });
+});
diff --git a/packages/cli/src/ui/utils/historyMapping.ts b/packages/cli/src/ui/utils/historyMapping.ts
new file mode 100644
index 000000000..389acf2e9
--- /dev/null
+++ b/packages/cli/src/ui/utils/historyMapping.ts
@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { HistoryItem } from '../types.js';
+import type { Content } from '@google/genai';
+
+/**
+ * Returns true when the history item represents a real user prompt that was
+ * sent to the model, as opposed to a slash-command invocation (`/help`,
+ * `/stats`, …) which is stored with `type: 'user'` in the UI but never
+ * reaches the API history or `turnParentUuids`.
+ */
+export function isRealUserTurn(item: HistoryItem): boolean {
+  if (item.type !== 'user' || !item.text) return false;
+  return !item.text.startsWith('/') && !item.text.startsWith('?');
+}
+
+/**
+ * The well-known startup context model acknowledgment.
+ * Used to identify the startup context pair in the API history.
+ */
+const STARTUP_CONTEXT_MODEL_ACK = 'Got it. Thanks for the context!';
+
+/**
+ * Checks if a Content entry is a user-initiated text prompt
+ * as opposed to a tool result (functionResponse).
+ */
+function isUserTextContent(content: Content): boolean {
+  if (content.role !== 'user') return false;
+  if (!content.parts || content.parts.length === 0) return false;
+
+  const hasFunctionResponse = content.parts.some(
+    (part) => 'functionResponse' in part,
+  );
+  if (hasFunctionResponse) return false;
+
+  return content.parts.some((part) => 'text' in part && part.text);
+}
+
+/**
+ * Detects whether the API history starts with the startup context pair
+ * (user env context + model acknowledgment).
+ */
+function hasStartupContext(apiHistory: Content[]): boolean {
+  if (apiHistory.length < 2) return false;
+  const first = apiHistory[0];
+  const second = apiHistory[1];
+  if (first?.role !== 'user' || second?.role !== 'model') return false;
+  return (
+    second.parts?.some(
+      (part) => 'text' in part && part.text === STARTUP_CONTEXT_MODEL_ACK,
+    ) ?? false
+  );
+}
+
+/**
+ * Computes the number of API Content[] entries to keep when rewinding
+ * to a specific user turn in the UI history.
+ *
+ * The API history may include:
+ * - A startup context pair: [user(env), model(ack)] at the beginning
+ * - User text prompts (corresponding to UI user turns)
+ * - Model responses (with optional functionCall parts)
+ * - Tool result entries: user(functionResponse) + model(response)
+ *
+ * This function counts user text Content entries (skipping tool results
+ * and the startup context pair) to find the API boundary corresponding
+ * to the target UI user turn.
+ *
+ * Note: In IDE mode, additional user Content entries may be injected for
+ * IDE context. This function does not account for those and will produce
+ * incorrect results. Rewind is therefore disabled in IDE mode (guarded
+ * in openRewindSelector).
+ *
+ * @param uiHistory The full UI history array
+ * @param targetUserItemId The ID of the user HistoryItem to rewind to
+ * @param apiHistory The current API Content[] array
+ * @returns The number of Content entries to keep, or -1 if the target turn
+ *   could not be located (e.g., it was absorbed by chat compression).
+ */
+export function computeApiTruncationIndex(
+  uiHistory: HistoryItem[],
+  targetUserItemId: number,
+  apiHistory: Content[],
+): number {
+  // Count how many UI user turns exist before the target
+  let uiUserTurnCount = 0;
+  for (const item of uiHistory) {
+    if (item.id === targetUserItemId) {
+      break;
+    }
+    if (isRealUserTurn(item)) {
+      uiUserTurnCount++;
+    }
+  }
+
+  // Determine the starting index in the API history (skip startup context)
+  const startIndex = hasStartupContext(apiHistory) ? 2 : 0;
+
+  if (uiUserTurnCount === 0) {
+    // Rewinding to the first user turn: keep only startup context (if any)
+    return startIndex;
+  }
+
+  // Walk the API history from after the startup context, counting
+  // user text prompts to find the one corresponding to the target turn.
+  let realUserPromptCount = 0;
+
+  for (let i = startIndex; i < apiHistory.length; i++) {
+    if (isUserTextContent(apiHistory[i]!)) {
+      realUserPromptCount++;
+      // The target turn is the (uiUserTurnCount + 1)th real user prompt.
+      // We want to truncate right before it.
+      if (realUserPromptCount > uiUserTurnCount) {
+        return i;
+      }
+    }
+  }
+
+  // If we didn't find enough user prompts (e.g., after compression),
+  // signal that the target turn is unreachable.
+  return -1;
+}
diff --git a/packages/cli/src/ui/utils/mergeCompactToolGroups.test.ts b/packages/cli/src/ui/utils/mergeCompactToolGroups.test.ts
index 2a8f69afe..405516234 100644
--- a/packages/cli/src/ui/utils/mergeCompactToolGroups.test.ts
+++ b/packages/cli/src/ui/utils/mergeCompactToolGroups.test.ts
@@ -343,6 +343,134 @@ describe('mergeCompactToolGroups', () => {
     expect(merged[3].type).toBe('tool_group');
   });
 
+  it('drops trailing tool_use_summary after a single absorbed tool_group', () => {
+    // Single-batch turn: one tool_group, then its summary arrives. The group
+    // is non-force-expanded (compact-mode candidate), so its callId is in
+    // absorbedCallIds — the summary is consumed by the compact header and
+    // dropped from merged output. Without this drop, mergedHistory.length
+    // would grow lock-step with history.length and MainContent's
+    // refreshStatic heuristic would never fire.
+    const items: HistoryItem[] = [
+      createToolGroup(1, [createTool('c1', 'Shell', ToolCallStatus.Success)]),
+      {
+        type: 'tool_use_summary',
+        id: 2,
+        summary: 'Ran shell batch',
+        precedingToolUseIds: ['c1'],
+      },
+    ];
+
+    const merged = mergeCompactToolGroups(
+      items,
+      false,
+      undefined,
+      new Set(['c1']),
+    );
+
+    expect(merged.length).toBe(1);
+    expect(merged[0].id).toBe(1);
+    expect(merged[0].type).toBe('tool_group');
+  });
+
+  it('drops absorbed trailing tool_use_summary even when followed by visible non-mergeable items', () => {
+    const items: HistoryItem[] = [
+      createToolGroup(1, [createTool('c1', 'Shell', ToolCallStatus.Success)]),
+      {
+        type: 'tool_use_summary',
+        id: 2,
+        summary: 'Ran shell batch',
+        precedingToolUseIds: ['c1'],
+      },
+      { type: 'user', id: 3, text: 'next prompt' },
+    ];
+
+    const merged = mergeCompactToolGroups(
+      items,
+      false,
+      undefined,
+      new Set(['c1']),
+    );
+
+    expect(merged.length).toBe(2);
+    expect(merged[0].type).toBe('tool_group');
+    expect(merged[1].type).toBe('user');
+  });
+
+  it('preserves tool_use_summary for force-expanded (non-absorbed) tool_group', () => {
+    // The errored tool_group is force-expanded: it renders through the full
+    // ToolGroupMessage path, ignoring `compactLabel`. Its callId is NOT in
+    // absorbedCallIds, so the summary must survive in merged output —
+    // HistoryItemDisplay then renders it as a standalone `● <label>` line,
+    // which is the only way the label reaches the screen for this group.
+    const items: HistoryItem[] = [
+      createToolGroup(1, [
+        createTool('c1', 'Shell', ToolCallStatus.Error, 'boom'),
+      ]),
+      {
+        type: 'tool_use_summary',
+        id: 2,
+        summary: 'Tried shell batch',
+        precedingToolUseIds: ['c1'],
+      },
+    ];
+
+    // Empty absorbedCallIds — the errored group's callId is not absorbed.
+    const merged = mergeCompactToolGroups(items, false, undefined, new Set());
+
+    expect(merged.length).toBe(2);
+    expect(merged[0].type).toBe('tool_group');
+    expect(merged[1].type).toBe('tool_use_summary');
+  });
+
+  it('preserves tool_use_summary when no absorbedCallIds set is provided (default)', () => {
+    // Default empty set — preserves all summaries. This is the safe default
+    // for callers that don't compute absorption (e.g., older test fixtures
+    // and any future callers outside MainContent).
+    const items: HistoryItem[] = [
+      createToolGroup(1, [createTool('c1', 'Shell', ToolCallStatus.Success)]),
+      {
+        type: 'tool_use_summary',
+        id: 2,
+        summary: 'Ran shell batch',
+        precedingToolUseIds: ['c1'],
+      },
+    ];
+
+    const merged = mergeCompactToolGroups(items);
+
+    expect(merged.length).toBe(2);
+    expect(merged[0].type).toBe('tool_group');
+    expect(merged[1].type).toBe('tool_use_summary');
+  });
+
+  it('merges tool_groups separated by tool_use_summary (hidden in compact)', () => {
+    // Two mergeable batches separated by an absorbed summary — the summary
+    // is dropped during merge, the two groups concatenate.
+    const items: HistoryItem[] = [
+      createToolGroup(1, [createTool('c1', 'Shell', ToolCallStatus.Success)]),
+      {
+        type: 'tool_use_summary',
+        id: 2,
+        summary: 'Ran first shell batch',
+        precedingToolUseIds: ['c1'],
+      },
+      createToolGroup(3, [createTool('c2', 'Shell', ToolCallStatus.Success)]),
+    ];
+
+    const merged = mergeCompactToolGroups(
+      items,
+      false,
+      undefined,
+      new Set(['c1', 'c2']),
+    );
+
+    expect(merged.length).toBe(1);
+    expect(merged[0].id).toBe(1);
+    if (isToolGroup(merged[0])) {
+      expect(merged[0].tools.map((t) => t.callId)).toEqual(['c1', 'c2']);
+    }
+  });
+
   it('preserves trailing gemini_thought after merged group', () => {
     const items: HistoryItem[] = [
       createToolGroup(1, [createTool('c1', 'Shell', ToolCallStatus.Success)]),
diff --git a/packages/cli/src/ui/utils/mergeCompactToolGroups.ts b/packages/cli/src/ui/utils/mergeCompactToolGroups.ts
index 087cdb82f..a5540e178 100644
--- a/packages/cli/src/ui/utils/mergeCompactToolGroups.ts
+++ b/packages/cli/src/ui/utils/mergeCompactToolGroups.ts
@@ -34,8 +34,12 @@ function isAgentWithPendingConfirmation(
 /**
  * Check if a tool_group history item should be excluded from merging due to force-expand conditions.
  * These conditions match ToolGroupMessage.tsx:105-112 showCompact logic.
+ * Exported so MainContent can determine which callIds get their label
+ * "absorbed" by the compact tool_group header vs which need the standalone
+ * `● <label>` line rendered (force-expanded groups never go through the
+ * compact path, so their label would otherwise be invisible).
  */
-function isForceExpandGroup(
+export function isForceExpandGroup(
   item: HistoryItem,
   embeddedShellFocused: boolean,
   activeShellPtyId: number | undefined,
@@ -83,12 +87,16 @@ function isForceExpandGroup(
 
 /**
  * Check if an item is hidden in compact mode (so it shouldn't break tool_group adjacency).
- * This mirrors HistoryItemDisplay.tsx:123-142 which hides gemini_thought / gemini_thought_content
- * when compactMode is true.
+ * This mirrors HistoryItemDisplay.tsx which hides:
+ *  - `gemini_thought` / `gemini_thought_content` (thinking — hidden when compactMode is true),
+ *  - `tool_use_summary` (consumed upstream to decorate the adjacent tool_group's label;
+ *    never rendered standalone so it must not break adjacency between two batches).
  */
 function isHiddenInCompactMode(item: HistoryItem): boolean {
   return (
-    item.type === 'gemini_thought' || item.type === 'gemini_thought_content'
+    item.type === 'gemini_thought' ||
+    item.type === 'gemini_thought_content' ||
+    item.type === 'tool_use_summary'
   );
 }
 
@@ -104,12 +112,20 @@ function isHiddenInCompactMode(item: HistoryItem): boolean {
  * @param items - History items array
  * @param embeddedShellFocused - Whether embedded shell is focused
  * @param activeShellPtyId - PTY ID of the active shell (if any)
+ * @param absorbedCallIds - Set of tool callIds whose summary label is consumed
+ *   by a compact-mode tool_group header (i.e., the corresponding tool_group is
+ *   NOT force-expanded). Summaries for these callIds are dropped from the
+ *   merged result so MainContent's refreshStatic heuristic fires and the
+ *   tool_group re-renders with its label. Summaries for force-expanded groups
+ *   pass through unchanged so HistoryItemDisplay can render them as standalone
+ *   `● <label>` lines (the compact path doesn't consume their label).
  * @returns New array with merged tool_groups (does not mutate input)
  */
 export function mergeCompactToolGroups(
   items: HistoryItem[],
   embeddedShellFocused: boolean = false,
   activeShellPtyId: number | undefined = undefined,
+  absorbedCallIds: ReadonlySet<string> = new Set(),
 ): HistoryItem[] {
   const result: HistoryItem[] = [];
   let i = 0;
@@ -117,6 +133,34 @@ export function mergeCompactToolGroups(
   while (i < items.length) {
     const item = items[i];
 
+    // Drop `tool_use_summary` items whose preceding callIds are *all* absorbed
+    // by a compact tool_group header. Those headers will display the label
+    // directly (via the `compactLabel` lookup in MainContent), so keeping the
+    // standalone summary in the merged result would either double-display the
+    // label (if HistoryItemDisplay rendered both) or, more importantly, would
+    // bump mergedHistory.length lock-step with history.length and prevent
+    // refreshStatic from firing — Ink's <Static> would never repaint the
+    // committed tool_group with the new label.
+    //
+    // Summaries with at least one non-absorbed preceding callId — e.g., when
+    // the corresponding tool_group is force-expanded (errors / confirming /
+    // user-initiated / focused shell) and renders through the full
+    // ToolGroupMessage path that does not consume `compactLabel` — must
+    // survive in the merged result so HistoryItemDisplay can render them as
+    // standalone `● <label>` lines.
+    if (item.type === 'tool_use_summary') {
+      const allAbsorbed =
+        item.precedingToolUseIds.length > 0 &&
+        item.precedingToolUseIds.every((id) => absorbedCallIds.has(id));
+      if (allAbsorbed) {
+        i++;
+        continue;
+      }
+      result.push(item);
+      i++;
+      continue;
+    }
+
     // Pass through non-mergeable items unchanged
     if (
       item.type !== 'tool_group' ||
diff --git a/packages/cli/src/ui/utils/resumeHistoryUtils.ts b/packages/cli/src/ui/utils/resumeHistoryUtils.ts
index bf134785a..2de73a5b1 100644
--- a/packages/cli/src/ui/utils/resumeHistoryUtils.ts
+++ b/packages/cli/src/ui/utils/resumeHistoryUtils.ts
@@ -82,7 +82,11 @@ function extractFunctionCalls(
   return calls;
 }
 
-function getTool(config: Config, name: string): AnyDeclarativeTool | undefined {
+function getTool(
+  config: Config | null,
+  name: string,
+): AnyDeclarativeTool | undefined {
+  if (!config) return undefined;
   const toolRegistry = config.getToolRegistry();
   return toolRegistry.getTool(name);
 }
@@ -144,7 +148,7 @@ function restoreHistoryItem(raw: unknown): HistoryItemWithoutId | undefined {
  */
 function convertToHistoryItems(
   conversation: ConversationRecord,
-  config: Config,
+  config: Config | null,
 ): HistoryItemWithoutId[] {
   const items: HistoryItemWithoutId[] = [];
   const pendingAtCommands: AtCommandRecordPayload[] = [];
@@ -252,6 +256,9 @@ function convertToHistoryItems(
         if (!payload) continue;
         pendingAtCommands.push(payload);
       }
+      if (record.subtype === 'rewind') {
+        items.push({ type: 'info', text: 'Conversation rewound.' });
+      }
       continue;
     }
     switch (record.type) {
@@ -318,12 +325,13 @@ function convertToHistoryItems(
       case 'assistant': {
         const parts = record.message?.parts as Part[] | undefined;
 
-        // Extract thought content
-        const thoughtText = !config
-          .getContentGenerator()
-          .useSummarizedThinking()
-          ? extractThoughtTextFromParts(parts)
-          : '';
+        // Extract thought content. With no config (standalone picker preview),
+        // default to showing thoughts verbatim (same path as
+        // `!useSummarizedThinking()`).
+        const thoughtText =
+          !config || !config.getContentGenerator().useSummarizedThinking()
+            ? extractThoughtTextFromParts(parts)
+            : '';
 
         // Extract text content (non-function-call, non-thought)
         const text = extractTextFromParts(parts);
@@ -448,13 +456,16 @@ function convertToHistoryItems(
  * and assigns unique IDs to each item for use with loadHistory.
  *
  * @param sessionData The resumed session data from SessionService
- * @param config The config object for accessing tool registry
+ * @param config The config object for accessing tool registry. Pass `null`
+ *   to render in "preview" mode (no tool metadata lookup, thoughts shown
+ *   verbatim) — used by the standalone resume picker that runs before
+ *   `loadCliConfig`.
  * @param baseTimestamp Base timestamp for generating unique IDs
  * @returns Array of HistoryItem with proper IDs
  */
 export function buildResumedHistoryItems(
   sessionData: ResumedSessionData,
-  config: Config,
+  config: Config | null,
   baseTimestamp: number = Date.now(),
 ): HistoryItem[] {
   const items: HistoryItem[] = [];
diff --git a/packages/cli/src/ui/utils/synchronizedOutput.test.ts b/packages/cli/src/ui/utils/synchronizedOutput.test.ts
new file mode 100644
index 000000000..f9c9da0e1
--- /dev/null
+++ b/packages/cli/src/ui/utils/synchronizedOutput.test.ts
@@ -0,0 +1,191 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  BEGIN_SYNCHRONIZED_UPDATE,
+  END_SYNCHRONIZED_UPDATE,
+  getSynchronizedOutputStatsSnapshot,
+  installSynchronizedOutput,
+  resetSynchronizedOutputStats,
+  terminalSupportsSynchronizedOutput,
+} from './synchronizedOutput.js';
+import { installTerminalRedrawOptimizer } from './terminalRedrawOptimizer.js';
+
+const ESC = '\u001B[';
+const ERASE_LINE = `${ESC}2K`;
+const CURSOR_UP_ONE = `${ESC}1A`;
+const CURSOR_DOWN_ONE = `${ESC}1B`;
+const CURSOR_LEFT = `${ESC}G`;
+
+function createStdout(write: NodeJS.WriteStream['write']): NodeJS.WriteStream {
+  return {
+    isTTY: true,
+    write,
+  } as NodeJS.WriteStream;
+}
+
+describe('terminalSupportsSynchronizedOutput', () => {
+  it.each([
+    [{ TERM_PROGRAM: 'WezTerm' }, true],
+    [{ TERM_PROGRAM: 'iTerm.app' }, true],
+    [{ TERM: 'xterm-kitty' }, true],
+    [{ KITTY_WINDOW_ID: '1' }, true],
+    [{ TERM_PROGRAM: 'Apple_Terminal' }, false],
+    [{ TERM_PROGRAM: 'JetBrains-JediTerm' }, false],
+    [{ TERM_PROGRAM: 'WezTerm', TMUX: '/tmp/tmux' }, false],
+    [{ TERM_PROGRAM: 'WezTerm', SSH_TTY: '/dev/pts/1' }, false],
+    [{ TERM_PROGRAM: 'WezTerm', SSH_CLIENT: '127.0.0.1 1 2' }, false],
+    [{ TERM_PROGRAM: 'WezTerm', QWEN_CODE_SYNCHRONIZED_OUTPUT: '0' }, false],
+    [
+      {
+        TERM_PROGRAM: 'WezTerm',
+        QWEN_CODE_DISABLE_SYNCHRONIZED_OUTPUT: '1',
+        QWEN_CODE_FORCE_SYNCHRONIZED_OUTPUT: '1',
+      },
+      false,
+    ],
+    [
+      {
+        TERM_PROGRAM: 'Apple_Terminal',
+        QWEN_CODE_FORCE_SYNCHRONIZED_OUTPUT: '1',
+      },
+      true,
+    ],
+  ])('detects support for %j', (env, expected) => {
+    expect(terminalSupportsSynchronizedOutput(env)).toBe(expected);
+  });
+});
+
+describe('installSynchronizedOutput', () => {
+  afterEach(() => {
+    resetSynchronizedOutputStats();
+  });
+
+  it('does not install for non-TTY stdout', () => {
+    const write = vi.fn(() => true) as NodeJS.WriteStream['write'];
+    const stdout = {
+      isTTY: false,
+      write,
+    } as NodeJS.WriteStream;
+
+    const restore = installSynchronizedOutput(stdout, {
+      TERM_PROGRAM: 'WezTerm',
+    });
+
+    expect(stdout.write).toBe(write);
+    restore();
+  });
+
+  it('wraps one synchronous write burst in balanced BSU and ESU markers', async () => {
+    const writes: string[] = [];
+    const write = vi.fn((chunk: string | Uint8Array) => {
+      writes.push(typeof chunk === 'string' ? chunk : chunk.toString());
+      return true;
+    }) as NodeJS.WriteStream['write'];
+    const stdout = createStdout(write);
+
+    const restore = installSynchronizedOutput(stdout, {
+      TERM_PROGRAM: 'WezTerm',
+    });
+
+    stdout.write('frame-a');
+    stdout.write(Buffer.from('frame-b'));
+    await Promise.resolve();
+
+    expect(writes).toEqual([
+      BEGIN_SYNCHRONIZED_UPDATE,
+      'frame-a',
+      'frame-b',
+      END_SYNCHRONIZED_UPDATE,
+    ]);
+    expect(getSynchronizedOutputStatsSnapshot()).toEqual({
+      synchronizedOutputFrameCount: 1,
+      synchronizedOutputBeginCount: 1,
+      synchronizedOutputEndCount: 1,
+    });
+
+    restore();
+    expect(stdout.write).toBe(write);
+  });
+
+  it('preserves write return values and callbacks', async () => {
+    const callback = vi.fn();
+    const write = vi.fn(
+      (
+        _chunk: string | Uint8Array,
+        encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+      ) => {
+        if (typeof encodingOrCallback === 'function') {
+          encodingOrCallback();
+        }
+        return false;
+      },
+    ) as NodeJS.WriteStream['write'];
+    const stdout = createStdout(write);
+
+    const restore = installSynchronizedOutput(stdout, {
+      TERM_PROGRAM: 'iTerm.app',
+    });
+
+    const result = stdout.write('payload', callback);
+    await Promise.resolve();
+
+    expect(result).toBe(false);
+    expect(callback).toHaveBeenCalledTimes(1);
+    restore();
+  });
+
+  it('composes after terminal redraw optimization without losing erase optimization', async () => {
+    const writes: string[] = [];
+    const write = vi.fn((chunk: string | Uint8Array) => {
+      writes.push(typeof chunk === 'string' ? chunk : chunk.toString());
+      return true;
+    }) as NodeJS.WriteStream['write'];
+    const stdout = createStdout(write);
+    const restoreRedrawOptimizer = installTerminalRedrawOptimizer(stdout);
+    const restoreSynchronizedOutput = installSynchronizedOutput(stdout, {
+      TERM_PROGRAM: 'WezTerm',
+    });
+
+    stdout.write(
+      `${ERASE_LINE}${CURSOR_UP_ONE}${ERASE_LINE}${CURSOR_UP_ONE}${ERASE_LINE}${CURSOR_LEFT}`,
+    );
+    await Promise.resolve();
+
+    expect(writes).toEqual([
+      BEGIN_SYNCHRONIZED_UPDATE,
+      `${ESC}2A${ERASE_LINE}${CURSOR_DOWN_ONE}${ERASE_LINE}${CURSOR_DOWN_ONE}${ERASE_LINE}${ESC}2A${CURSOR_LEFT}`,
+      END_SYNCHRONIZED_UPDATE,
+    ]);
+
+    restoreSynchronizedOutput();
+    restoreRedrawOptimizer();
+    expect(stdout.write).toBe(write);
+  });
+
+  it('closes an open frame before restore', () => {
+    const writes: string[] = [];
+    const write = vi.fn((chunk: string | Uint8Array) => {
+      writes.push(typeof chunk === 'string' ? chunk : chunk.toString());
+      return true;
+    }) as NodeJS.WriteStream['write'];
+    const stdout = createStdout(write);
+    const restore = installSynchronizedOutput(stdout, {
+      TERM_PROGRAM: 'WezTerm',
+    });
+
+    stdout.write('payload');
+    restore();
+
+    expect(writes).toEqual([
+      BEGIN_SYNCHRONIZED_UPDATE,
+      'payload',
+      END_SYNCHRONIZED_UPDATE,
+    ]);
+    expect(stdout.write).toBe(write);
+  });
+});
diff --git a/packages/cli/src/ui/utils/synchronizedOutput.ts b/packages/cli/src/ui/utils/synchronizedOutput.ts
new file mode 100644
index 000000000..fb75786ad
--- /dev/null
+++ b/packages/cli/src/ui/utils/synchronizedOutput.ts
@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const BEGIN_SYNCHRONIZED_UPDATE = '\u001B[?2026h';
+export const END_SYNCHRONIZED_UPDATE = '\u001B[?2026l';
+
+export interface SynchronizedOutputStatsSnapshot {
+  synchronizedOutputFrameCount: number;
+  synchronizedOutputBeginCount: number;
+  synchronizedOutputEndCount: number;
+}
+
+const synchronizedOutputStats: SynchronizedOutputStatsSnapshot = {
+  synchronizedOutputFrameCount: 0,
+  synchronizedOutputBeginCount: 0,
+  synchronizedOutputEndCount: 0,
+};
+
+let installed = false;
+
+export function getSynchronizedOutputStatsSnapshot(): SynchronizedOutputStatsSnapshot {
+  return { ...synchronizedOutputStats };
+}
+
+export function resetSynchronizedOutputStats(): void {
+  synchronizedOutputStats.synchronizedOutputFrameCount = 0;
+  synchronizedOutputStats.synchronizedOutputBeginCount = 0;
+  synchronizedOutputStats.synchronizedOutputEndCount = 0;
+}
+
+export function terminalSupportsSynchronizedOutput(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (
+    env['QWEN_CODE_DISABLE_SYNCHRONIZED_OUTPUT'] === '1' ||
+    env['QWEN_CODE_SYNCHRONIZED_OUTPUT'] === '0'
+  ) {
+    return false;
+  }
+
+  if (
+    env['QWEN_CODE_FORCE_SYNCHRONIZED_OUTPUT'] === '1' ||
+    env['QWEN_CODE_SYNCHRONIZED_OUTPUT'] === '1'
+  ) {
+    return true;
+  }
+
+  if (env['TMUX'] || env['SSH_TTY'] || env['SSH_CLIENT']) {
+    return false;
+  }
+
+  const termProgram = env['TERM_PROGRAM'];
+  if (termProgram === 'WezTerm' || termProgram === 'iTerm.app') {
+    return true;
+  }
+
+  const term = env['TERM'];
+  return Boolean(env['KITTY_WINDOW_ID'] || term?.includes('kitty'));
+}
+
+export function installSynchronizedOutput(
+  stdout: NodeJS.WriteStream = process.stdout,
+  env: NodeJS.ProcessEnv = process.env,
+): () => void {
+  if (installed || !stdout.isTTY || !terminalSupportsSynchronizedOutput(env)) {
+    return () => {};
+  }
+
+  const originalWrite = stdout.write;
+  let inFrame = false;
+
+  const writeControlSequence = (sequence: string) => {
+    originalWrite.call(stdout, sequence);
+  };
+
+  const endFrame = () => {
+    if (!inFrame) {
+      return;
+    }
+
+    inFrame = false;
+    synchronizedOutputStats.synchronizedOutputEndCount += 1;
+    writeControlSequence(END_SYNCHRONIZED_UPDATE);
+  };
+
+  const patchedWrite = function (
+    this: NodeJS.WriteStream,
+    chunk: unknown,
+    encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+    callback?: (error?: Error | null) => void,
+  ) {
+    if (!inFrame) {
+      inFrame = true;
+      synchronizedOutputStats.synchronizedOutputFrameCount += 1;
+      synchronizedOutputStats.synchronizedOutputBeginCount += 1;
+      writeControlSequence(BEGIN_SYNCHRONIZED_UPDATE);
+      queueMicrotask(endFrame);
+    }
+
+    return originalWrite.call(
+      this,
+      chunk as string | Uint8Array,
+      encodingOrCallback as BufferEncoding,
+      callback,
+    );
+  } as typeof stdout.write;
+
+  const exitHandler = () => {
+    try {
+      endFrame();
+    } catch {
+      // stdout may already be closed during process shutdown.
+    }
+  };
+
+  stdout.write = patchedWrite;
+  installed = true;
+  process.once('exit', exitHandler);
+
+  return () => {
+    if (stdout.write === patchedWrite) {
+      endFrame();
+      stdout.write = originalWrite;
+    }
+    process.removeListener('exit', exitHandler);
+    installed = false;
+  };
+}
diff --git a/packages/cli/src/ui/utils/terminalRedrawOptimizer.test.ts b/packages/cli/src/ui/utils/terminalRedrawOptimizer.test.ts
index 53d747c14..2e411758e 100644
--- a/packages/cli/src/ui/utils/terminalRedrawOptimizer.test.ts
+++ b/packages/cli/src/ui/utils/terminalRedrawOptimizer.test.ts
@@ -6,8 +6,10 @@
 
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
+  getTerminalRedrawStatsSnapshot,
   installTerminalRedrawOptimizer,
   optimizeMultilineEraseLines,
+  resetTerminalRedrawStats,
 } from './terminalRedrawOptimizer.js';
 
 const ESC = '\u001B[';
@@ -56,6 +58,7 @@ describe('optimizeMultilineEraseLines', () => {
 describe('installTerminalRedrawOptimizer', () => {
   afterEach(() => {
     vi.unstubAllEnvs();
+    resetTerminalRedrawStats();
   });
 
   it('optimizes string writes and restores the original writer', () => {
@@ -87,6 +90,30 @@ describe('installTerminalRedrawOptimizer', () => {
     expect(write).toHaveBeenCalledWith(input, undefined, undefined);
   });
 
+  it('tracks write, byte, clear, and erase optimization counters', () => {
+    const write = vi.fn(() => true);
+    const stdout = { write } as unknown as NodeJS.WriteStream;
+    installTerminalRedrawOptimizer(stdout);
+
+    stdout.write(
+      `${ERASE_LINE}${CURSOR_UP_ONE}${ERASE_LINE}${CURSOR_UP_ONE}${ERASE_LINE}${CURSOR_LEFT}`,
+    );
+    stdout.write(Buffer.from('ok'));
+    stdout.write('\u001B[2J\u001B[3J\u001B[H');
+
+    expect(getTerminalRedrawStatsSnapshot()).toEqual({
+      stdoutWriteCount: 3,
+      stdoutBytes:
+        Buffer.byteLength(
+          `${ESC}2A${ERASE_LINE}${CURSOR_DOWN_ONE}${ERASE_LINE}${CURSOR_DOWN_ONE}${ERASE_LINE}${ESC}2A${CURSOR_LEFT}`,
+        ) +
+        Buffer.byteLength('ok') +
+        Buffer.byteLength('\u001B[2J\u001B[3J\u001B[H'),
+      clearTerminalCount: 1,
+      eraseLinesOptimizedCount: 1,
+    });
+  });
+
   it('can be disabled for terminal compatibility fallback', () => {
     vi.stubEnv('QWEN_CODE_LEGACY_ERASE_LINES', '1');
     const write = vi.fn(() => true);
diff --git a/packages/cli/src/ui/utils/terminalRedrawOptimizer.ts b/packages/cli/src/ui/utils/terminalRedrawOptimizer.ts
index 166c687ed..b82186a6d 100644
--- a/packages/cli/src/ui/utils/terminalRedrawOptimizer.ts
+++ b/packages/cli/src/ui/utils/terminalRedrawOptimizer.ts
@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import ansiEscapes from 'ansi-escapes';
+
 const ESC = '\u001B[';
 const ERASE_LINE = `${ESC}2K`;
 const CURSOR_UP_ONE = `${ESC}1A`;
@@ -33,6 +35,79 @@ function countOccurrences(value: string, search: string): number {
   return count;
 }
 
+export interface TerminalRedrawStatsSnapshot {
+  stdoutWriteCount: number;
+  stdoutBytes: number;
+  clearTerminalCount: number;
+  eraseLinesOptimizedCount: number;
+}
+
+const terminalRedrawStats: TerminalRedrawStatsSnapshot = {
+  stdoutWriteCount: 0,
+  stdoutBytes: 0,
+  clearTerminalCount: 0,
+  eraseLinesOptimizedCount: 0,
+};
+
+export function getTerminalRedrawStatsSnapshot(): TerminalRedrawStatsSnapshot {
+  return { ...terminalRedrawStats };
+}
+
+export function resetTerminalRedrawStats(): void {
+  terminalRedrawStats.stdoutWriteCount = 0;
+  terminalRedrawStats.stdoutBytes = 0;
+  terminalRedrawStats.clearTerminalCount = 0;
+  terminalRedrawStats.eraseLinesOptimizedCount = 0;
+}
+
+function getChunkByteLength(
+  chunk: string | Uint8Array,
+  encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+): number {
+  if (typeof chunk === 'string') {
+    const encoding =
+      typeof encodingOrCallback === 'string' ? encodingOrCallback : undefined;
+    return Buffer.byteLength(chunk, encoding);
+  }
+
+  return chunk.byteLength;
+}
+
+function optimizeMultilineEraseLinesWithCount(output: string): {
+  output: string;
+  optimizedSequenceCount: number;
+} {
+  let optimizedSequenceCount = 0;
+
+  const optimizedOutput = output.replace(
+    MULTILINE_ERASE_LINES_PATTERN,
+    (sequence) => {
+      const lineCount = countOccurrences(sequence, ERASE_LINE);
+      const cursorUpCount = lineCount - 1;
+
+      if (cursorUpCount <= 1) {
+        return sequence;
+      }
+
+      optimizedSequenceCount += 1;
+
+      let boundedErase = `${ESC}${cursorUpCount}A`;
+
+      for (let line = 0; line < lineCount; line++) {
+        boundedErase += ERASE_LINE;
+
+        if (line < lineCount - 1) {
+          boundedErase += CURSOR_DOWN_ONE;
+        }
+      }
+
+      return `${boundedErase}${ESC}${cursorUpCount}A${CURSOR_LEFT}`;
+    },
+  );
+
+  return { output: optimizedOutput, optimizedSequenceCount };
+}
+
 /**
  * Ink clears dynamic output via ansi-escapes.eraseLines(), which emits a
  * clear-line + cursor-up pair for every previous line. That can make terminal
@@ -40,26 +115,7 @@ function countOccurrences(value: string, search: string): number {
  * upward cursor movement while still clearing only the same old frame lines.
  */
 export function optimizeMultilineEraseLines(output: string): string {
-  return output.replace(MULTILINE_ERASE_LINES_PATTERN, (sequence) => {
-    const lineCount = countOccurrences(sequence, ERASE_LINE);
-    const cursorUpCount = lineCount - 1;
-
-    if (cursorUpCount <= 1) {
-      return sequence;
-    }
-
-    let boundedErase = `${ESC}${cursorUpCount}A`;
-
-    for (let line = 0; line < lineCount; line++) {
-      boundedErase += ERASE_LINE;
-
-      if (line < lineCount - 1) {
-        boundedErase += CURSOR_DOWN_ONE;
-      }
-    }
-
-    return `${boundedErase}${ESC}${cursorUpCount}A${CURSOR_LEFT}`;
-  });
+  return optimizeMultilineEraseLinesWithCount(output).output;
 }
 
 export function installTerminalRedrawOptimizer(
@@ -77,8 +133,35 @@ export function installTerminalRedrawOptimizer(
     encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
     callback?: (error?: Error | null) => void,
   ) {
-    const optimizedChunk =
-      typeof chunk === 'string' ? optimizeMultilineEraseLines(chunk) : chunk;
+    const optimizedResult =
+      typeof chunk === 'string'
+        ? optimizeMultilineEraseLinesWithCount(chunk)
+        : undefined;
+    const optimizedChunk = optimizedResult?.output ?? chunk;
+
+    if (
+      typeof optimizedChunk === 'string' ||
+      optimizedChunk instanceof Uint8Array ||
+      Buffer.isBuffer(optimizedChunk)
+    ) {
+      terminalRedrawStats.stdoutWriteCount += 1;
+      terminalRedrawStats.stdoutBytes += getChunkByteLength(
+        optimizedChunk,
+        encodingOrCallback,
+      );
+
+      if (typeof optimizedChunk === 'string') {
+        terminalRedrawStats.clearTerminalCount += countOccurrences(
+          optimizedChunk,
+          ansiEscapes.clearTerminal,
+        );
+      }
+    }
+
+    if (optimizedResult) {
+      terminalRedrawStats.eraseLinesOptimizedCount +=
+        optimizedResult.optimizedSequenceCount;
+    }
 
     return originalWrite.call(
       this,
diff --git a/packages/cli/src/ui/utils/todoSnapshot.test.ts b/packages/cli/src/ui/utils/todoSnapshot.test.ts
new file mode 100644
index 000000000..815d974b7
--- /dev/null
+++ b/packages/cli/src/ui/utils/todoSnapshot.test.ts
@@ -0,0 +1,199 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { HistoryItem, HistoryItemWithoutId } from '../types.js';
+import { ToolCallStatus } from '../types.js';
+import { getStickyTodos } from './todoSnapshot.js';
+
+function makeTodoToolGroup(
+  content: string,
+  withId?: number,
+): HistoryItem | HistoryItemWithoutId {
+  const item = {
+    type: 'tool_group' as const,
+    tools: [
+      {
+        callId: `todo-${content}`,
+        name: 'TodoWrite',
+        description: 'Update todos',
+        resultDisplay: {
+          type: 'todo_list' as const,
+          todos: [
+            {
+              id: `todo-${content}`,
+              content,
+              status: 'pending' as const,
+            },
+          ],
+        },
+        status: ToolCallStatus.Success,
+        confirmationDetails: undefined,
+      },
+    ],
+  };
+
+  if (withId !== undefined) {
+    return { ...item, id: withId };
+  }
+
+  return item;
+}
+
+function makeCustomTodoToolGroup(
+  todos: Array<{
+    id: string;
+    content: string;
+    status: 'pending' | 'in_progress' | 'completed';
+  }>,
+  withId?: number,
+): HistoryItem | HistoryItemWithoutId {
+  const item = {
+    type: 'tool_group' as const,
+    tools: [
+      {
+        callId: 'todo-custom',
+        name: 'TodoWrite',
+        description: 'Update todos',
+        resultDisplay: {
+          type: 'todo_list' as const,
+          todos,
+        },
+        status: ToolCallStatus.Success,
+        confirmationDetails: undefined,
+      },
+    ],
+  };
+
+  if (withId !== undefined) {
+    return { ...item, id: withId };
+  }
+
+  return item;
+}
+
+function makeEmptyTodoToolGroup(
+  withId?: number,
+): HistoryItem | HistoryItemWithoutId {
+  const item = {
+    type: 'tool_group' as const,
+    tools: [
+      {
+        callId: 'todo-clear',
+        name: 'TodoWrite',
+        description: 'Clear todos',
+        resultDisplay: {
+          type: 'todo_list' as const,
+          todos: [],
+        },
+        status: ToolCallStatus.Success,
+        confirmationDetails: undefined,
+      },
+    ],
+  };
+
+  if (withId !== undefined) {
+    return { ...item, id: withId };
+  }
+
+  return item;
+}
+
+describe('getStickyTodos', () => {
+  it('returns the latest todo snapshot from history', () => {
+    const history = [
+      makeTodoToolGroup('first task', 1),
+      makeTodoToolGroup('latest history task', 2),
+    ] as HistoryItem[];
+
+    expect(getStickyTodos(history, [])).toEqual([
+      {
+        id: 'todo-latest history task',
+        content: 'latest history task',
+        status: 'pending',
+      },
+    ]);
+  });
+
+  it('prefers pending todo snapshots over history', () => {
+    const history = [makeTodoToolGroup('history task', 1)] as HistoryItem[];
+    const pendingHistoryItems = [
+      makeTodoToolGroup('pending task'),
+    ] as HistoryItemWithoutId[];
+
+    expect(getStickyTodos(history, pendingHistoryItems)).toEqual([
+      {
+        id: 'todo-pending task',
+        content: 'pending task',
+        status: 'pending',
+      },
+    ]);
+  });
+
+  it('returns null when the latest todo snapshot clears the list', () => {
+    const history = [makeTodoToolGroup('history task', 1)] as HistoryItem[];
+    const pendingHistoryItems = [
+      makeEmptyTodoToolGroup(),
+    ] as HistoryItemWithoutId[];
+
+    expect(getStickyTodos(history, pendingHistoryItems)).toBeNull();
+  });
+
+  it('returns null when the latest history todo snapshot is fully completed', () => {
+    const history = [
+      makeCustomTodoToolGroup(
+        [
+          {
+            id: 'todo-1',
+            content: 'Run tests',
+            status: 'completed',
+          },
+          {
+            id: 'todo-2',
+            content: 'Summarize results',
+            status: 'completed',
+          },
+        ],
+        1,
+      ),
+    ] as HistoryItem[];
+
+    expect(getStickyTodos(history, [])).toBeNull();
+  });
+
+  it('keeps showing a fully completed pending snapshot until the turn finishes', () => {
+    const history = [
+      makeTodoToolGroup('older history task', 1),
+    ] as HistoryItem[];
+    const pendingHistoryItems = [
+      makeCustomTodoToolGroup([
+        {
+          id: 'todo-1',
+          content: 'Run tests',
+          status: 'completed',
+        },
+        {
+          id: 'todo-2',
+          content: 'Summarize results',
+          status: 'completed',
+        },
+      ]),
+    ] as HistoryItemWithoutId[];
+
+    expect(getStickyTodos(history, pendingHistoryItems)).toEqual([
+      {
+        id: 'todo-1',
+        content: 'Run tests',
+        status: 'completed',
+      },
+      {
+        id: 'todo-2',
+        content: 'Summarize results',
+        status: 'completed',
+      },
+    ]);
+  });
+});
diff --git a/packages/cli/src/ui/utils/todoSnapshot.ts b/packages/cli/src/ui/utils/todoSnapshot.ts
new file mode 100644
index 000000000..3f297e30d
--- /dev/null
+++ b/packages/cli/src/ui/utils/todoSnapshot.ts
@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { TodoItem } from '../components/TodoDisplay.js';
+import type {
+  HistoryItem,
+  HistoryItemWithoutId,
+  IndividualToolCallDisplay,
+} from '../types.js';
+
+type HistoryLikeItem = HistoryItem | HistoryItemWithoutId;
+type SnapshotSearchResult = TodoItem[] | null | undefined;
+const STICKY_TODO_STATUS_PRIORITY: Record<TodoItem['status'], number> = {
+  in_progress: 0,
+  pending: 1,
+  completed: 2,
+};
+
+function extractTodosFromResultDisplay(
+  resultDisplay: unknown,
+): TodoItem[] | null {
+  if (!resultDisplay) {
+    return null;
+  }
+
+  if (typeof resultDisplay === 'object') {
+    const candidate = resultDisplay as Record<string, unknown>;
+    if (
+      candidate['type'] === 'todo_list' &&
+      Array.isArray(candidate['todos'])
+    ) {
+      return candidate['todos'] as TodoItem[];
+    }
+  }
+
+  if (typeof resultDisplay === 'string') {
+    try {
+      const parsed = JSON.parse(resultDisplay) as Record<string, unknown>;
+      if (parsed['type'] === 'todo_list' && Array.isArray(parsed['todos'])) {
+        return parsed['todos'] as TodoItem[];
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+function findLatestTodoSnapshot(
+  items: readonly HistoryLikeItem[],
+): SnapshotSearchResult {
+  for (let itemIndex = items.length - 1; itemIndex >= 0; itemIndex -= 1) {
+    const item = items[itemIndex];
+    if (item.type !== 'tool_group') {
+      continue;
+    }
+
+    for (
+      let toolIndex = item.tools.length - 1;
+      toolIndex >= 0;
+      toolIndex -= 1
+    ) {
+      const tool = item.tools[toolIndex] as IndividualToolCallDisplay;
+      const todos = extractTodosFromResultDisplay(tool.resultDisplay);
+      if (todos) {
+        return todos.length > 0 ? todos : null;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function areAllTodosCompleted(todos: readonly TodoItem[]): boolean {
+  return todos.length > 0 && todos.every((todo) => todo.status === 'completed');
+}
+
+export function getStickyTodos(
+  history: readonly HistoryItem[],
+  pendingHistoryItems: readonly HistoryItemWithoutId[],
+): TodoItem[] | null {
+  const pendingSnapshot = findLatestTodoSnapshot(pendingHistoryItems);
+  if (pendingSnapshot !== undefined) {
+    return pendingSnapshot;
+  }
+
+  const historySnapshot = findLatestTodoSnapshot(history);
+  if (historySnapshot && areAllTodosCompleted(historySnapshot)) {
+    return null;
+  }
+
+  return historySnapshot ?? null;
+}
+
+export function getOrderedStickyTodos(todos: readonly TodoItem[]): TodoItem[] {
+  return todos
+    .map((todo, index) => ({ todo, index }))
+    .sort(
+      (left, right) =>
+        STICKY_TODO_STATUS_PRIORITY[left.todo.status] -
+          STICKY_TODO_STATUS_PRIORITY[right.todo.status] ||
+        left.index - right.index,
+    )
+    .map(({ todo }) => todo);
+}
diff --git a/packages/cli/src/utils/apiPreconnect.test.ts b/packages/cli/src/utils/apiPreconnect.test.ts
new file mode 100644
index 000000000..ba50f1ff1
--- /dev/null
+++ b/packages/cli/src/utils/apiPreconnect.test.ts
@@ -0,0 +1,241 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { preconnectApi, resetPreconnectState } from './apiPreconnect.js';
+
+// Mock fetch
+const mockFetch = vi.fn().mockResolvedValue(undefined);
+global.fetch = mockFetch;
+
+// Mock the shared dispatcher functions from core
+const { mockGetOrCreateSharedDispatcher, mockDebugLogger } = vi.hoisted(() => {
+  const dispatcher = { fake: 'dispatcher' };
+  const mockDebugLogger = { debug: vi.fn() };
+  return {
+    mockGetOrCreateSharedDispatcher: vi.fn(() => dispatcher),
+    mockDebugLogger,
+  };
+});
+vi.mock('@qwen-code/qwen-code-core', () => ({
+  createDebugLogger: () => mockDebugLogger,
+  detectRuntime: () => 'node',
+  getOrCreateSharedDispatcher: mockGetOrCreateSharedDispatcher,
+}));
+
+describe('apiPreconnect', () => {
+  beforeEach(() => {
+    resetPreconnectState();
+    mockFetch.mockClear();
+    mockFetch.mockResolvedValue(undefined);
+    mockGetOrCreateSharedDispatcher.mockClear();
+    delete process.env['HTTPS_PROXY'];
+    delete process.env['https_proxy'];
+    delete process.env['HTTP_PROXY'];
+    delete process.env['http_proxy'];
+    delete process.env['QWEN_CODE_DISABLE_PRECONNECT'];
+    delete process.env['NODE_EXTRA_CA_CERTS'];
+    delete process.env['SANDBOX'];
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('shouldSkipPreconnect', () => {
+    it('should skip when NODE_EXTRA_CA_CERTS is set', () => {
+      process.env['NODE_EXTRA_CA_CERTS'] = '/path/to/ca.pem';
+      preconnectApi('qwen-oauth');
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('resolvedBaseUrl handling', () => {
+    it('should use resolvedBaseUrl when it is a default URL', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl: 'https://api.openai.com/v1',
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.openai.com/v1',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should skip when resolvedBaseUrl is a custom (non-default) URL', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl: 'https://custom.api.com/v1',
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('should skip when resolvedBaseUrl is a subdomain-spoofed URL', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl: 'https://api.openai.com.malicious.com/v1',
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('should use resolvedBaseUrl when it is a dashscope compatible-mode URL', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://dashscope.aliyuncs.com/compatible-mode/v1',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should skip when resolvedBaseUrl is a dashscope subdomain-spoofed URL', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl: 'https://dashscope.aliyuncs.com.malicious.com/v1',
+      });
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('should accept DashScope regional endpoint (sg-singapore)', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl:
+          'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should accept DashScope regional endpoint (us-virginia)', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl: 'https://dashscope-us.aliyuncs.com/compatible-mode/v1',
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://dashscope-us.aliyuncs.com/compatible-mode/v1',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should accept DashScope regional endpoint (cn-hongkong)', () => {
+      preconnectApi('openai', {
+        resolvedBaseUrl:
+          'https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1',
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should fall back to authType default when resolvedBaseUrl is a non-URL sentinel', () => {
+      preconnectApi('qwen-oauth', {
+        resolvedBaseUrl: 'DYNAMIC_QWEN_OAUTH_BASE_URL',
+      });
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://coding.dashscope.aliyuncs.com',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should fall back to default URL when resolvedBaseUrl is undefined', () => {
+      preconnectApi('qwen-oauth');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://coding.dashscope.aliyuncs.com',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+  });
+
+  describe('preconnect behavior', () => {
+    it('should use default baseUrl for qwen-oauth', () => {
+      preconnectApi('qwen-oauth');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://coding.dashscope.aliyuncs.com',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should use default baseUrl for openai', () => {
+      preconnectApi('openai');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.openai.com',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should use default baseUrl for anthropic', () => {
+      preconnectApi('anthropic');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.anthropic.com',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should pass shared dispatcher on Node.js runtime', () => {
+      preconnectApi('qwen-oauth');
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          dispatcher: { fake: 'dispatcher' },
+        }),
+      );
+    });
+
+    it('should pass undefined proxy to shared dispatcher by default', () => {
+      preconnectApi('qwen-oauth');
+      expect(mockGetOrCreateSharedDispatcher).toHaveBeenCalledWith(undefined);
+    });
+
+    it('should pass configured proxy to shared dispatcher', () => {
+      preconnectApi('qwen-oauth', { proxy: 'http://proxy.example.com:8080' });
+      expect(mockGetOrCreateSharedDispatcher).toHaveBeenCalledWith(
+        'http://proxy.example.com:8080',
+      );
+    });
+
+    it('should not fire twice', () => {
+      preconnectApi('qwen-oauth');
+      preconnectApi('openai');
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('should retry when targetUrl was unavailable on first call', () => {
+      // First call: unknown authType, no resolvedBaseUrl → no targetUrl
+      preconnectApi('unknown-auth');
+      expect(mockFetch).not.toHaveBeenCalled();
+
+      // Second call: valid authType → should fire
+      preconnectApi('qwen-oauth');
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://coding.dashscope.aliyuncs.com',
+        expect.objectContaining({ method: 'HEAD' }),
+      );
+    });
+
+    it('should handle fetch errors gracefully', async () => {
+      mockFetch.mockRejectedValue(new Error('Network error'));
+      // Should not throw
+      expect(() => preconnectApi('qwen-oauth')).not.toThrow();
+    });
+
+    it('should handle synchronous dispatcher errors gracefully', () => {
+      mockGetOrCreateSharedDispatcher.mockImplementation(() => {
+        throw new Error('Failed to create dispatcher');
+      });
+      expect(() => preconnectApi('qwen-oauth')).not.toThrow();
+    });
+
+    it('should skip when QWEN_CODE_DISABLE_PRECONNECT is set', () => {
+      process.env['QWEN_CODE_DISABLE_PRECONNECT'] = '1';
+      preconnectApi('qwen-oauth');
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it('should skip in sandbox mode', () => {
+      process.env['SANDBOX'] = '1';
+      preconnectApi('qwen-oauth');
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/packages/cli/src/utils/apiPreconnect.ts b/packages/cli/src/utils/apiPreconnect.ts
new file mode 100644
index 000000000..611a8b5a1
--- /dev/null
+++ b/packages/cli/src/utils/apiPreconnect.ts
@@ -0,0 +1,213 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * API Preconnect - Warm API connections to reduce TCP+TLS handshake latency
+ *
+ * Principle: Fire a fire-and-forget HEAD request early in startup to warm
+ * the TCP+TLS connection. Subsequent actual API calls reuse this connection,
+ * saving 100-200ms.
+ *
+ * The preconnect uses the same shared undici dispatcher as the SDK clients,
+ * ensuring the warmed TCP+TLS connection is reused by subsequent API calls.
+ */
+
+import {
+  createDebugLogger,
+  detectRuntime,
+  getOrCreateSharedDispatcher,
+} from '@qwen-code/qwen-code-core';
+
+import { ALIBABA_STANDARD_API_KEY_ENDPOINTS } from '../constants/alibabaStandardApiKey.js';
+
+const debugLogger = createDebugLogger('PRECONNECT');
+
+let preconnectFired = false;
+
+/**
+ * Default API base URLs by AuthType.
+ * DashScope regional endpoints are derived from ALIBABA_STANDARD_API_KEY_ENDPOINTS
+ * so preconnect covers all supported regions (cn-beijing, sg-singapore, us-virginia, cn-hongkong).
+ */
+const DEFAULT_BASE_URLS: Record<string, string> = {
+  openai: 'https://api.openai.com',
+  'qwen-oauth': 'https://coding.dashscope.aliyuncs.com',
+  anthropic: 'https://api.anthropic.com',
+  dashscope: 'https://dashscope.aliyuncs.com',
+};
+
+/**
+ * All known default base URLs, including DashScope regional endpoints.
+ * Used by isDefaultBaseUrl() to accept any supported default endpoint.
+ */
+const ALL_DEFAULT_URLS: string[] = [
+  ...Object.values(DEFAULT_BASE_URLS),
+  ...Object.values(ALIBABA_STANDARD_API_KEY_ENDPOINTS),
+];
+
+/**
+ * Check if preconnect should be skipped due to environment conditions
+ */
+function shouldSkipPreconnect(): boolean {
+  // Skip for custom CA certificate (enterprise TLS inspection may interfere)
+  if (process.env['NODE_EXTRA_CA_CERTS']) {
+    debugLogger.debug('Skipping preconnect: custom CA certificate configured');
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if running in sandbox mode
+ * In sandbox mode, preconnect is ineffective because the process will restart
+ */
+function isInSandboxMode(): boolean {
+  return process.env['SANDBOX'] !== undefined;
+}
+
+/**
+ * Check if baseUrl is a default URL
+ */
+function isDefaultBaseUrl(baseUrl: string): boolean {
+  const normalizedInput = baseUrl
+    .toLowerCase()
+    .replace(/^https?:\/\//, '')
+    .replace(/\/+$/, '');
+  return ALL_DEFAULT_URLS.some((defaultUrl) => {
+    const normalizedDefault = defaultUrl
+      .toLowerCase()
+      .replace(/^https?:\/\//, '')
+      .replace(/\/+$/, '');
+    return (
+      normalizedInput === normalizedDefault ||
+      normalizedInput.startsWith(normalizedDefault + '/')
+    );
+  });
+}
+
+/**
+ * Get the target URL for preconnect.
+ * Uses the already-resolved base URL from the model config, falling back
+ * to default URLs by authType.
+ *
+ * Only preconnects to known default URLs — custom URLs may not accept HEAD
+ * requests or may require mTLS / private deployment configurations.
+ */
+function getPreconnectTargetUrl(
+  authType: string | undefined,
+  resolvedBaseUrl: string | undefined,
+): string | undefined {
+  // 1. Use the resolved base URL from model config (already incorporates
+  //    modelProviders > cli > env > settings priority chain)
+  if (resolvedBaseUrl && /^https?:\/\//i.test(resolvedBaseUrl)) {
+    if (isDefaultBaseUrl(resolvedBaseUrl)) {
+      return resolvedBaseUrl;
+    }
+    debugLogger.debug(
+      'Skipping preconnect: resolved baseUrl is not a default URL',
+    );
+    return undefined;
+  }
+
+  // 2. Fall back to default value by authType
+  if (authType && DEFAULT_BASE_URLS[authType]) {
+    return DEFAULT_BASE_URLS[authType];
+  }
+
+  return undefined;
+}
+
+/**
+ * Execute API preconnect
+ * Use HEAD request to establish TCP+TLS connection without sending actual request body.
+ * Uses the shared undici dispatcher to ensure connection pool is shared with SDK clients.
+ *
+ * @param authType - Authentication type (openai, qwen-oauth, anthropic, etc.)
+ * @param options - Configuration options
+ */
+export function preconnectApi(
+  authType: string | undefined,
+  options: {
+    resolvedBaseUrl?: string;
+    proxy?: string;
+  } = {},
+): void {
+  if (preconnectFired) {
+    return;
+  }
+
+  // Check if disabled
+  if (process.env['QWEN_CODE_DISABLE_PRECONNECT'] === '1') {
+    debugLogger.debug('Preconnect disabled by environment variable');
+    preconnectFired = true;
+    return;
+  }
+
+  // Check if in sandbox mode (process will restart, preconnect is ineffective)
+  if (isInSandboxMode()) {
+    debugLogger.debug('Skipping preconnect: sandbox mode detected');
+    preconnectFired = true;
+    return;
+  }
+
+  // Check environment skip conditions (custom CA)
+  if (shouldSkipPreconnect()) {
+    preconnectFired = true;
+    return;
+  }
+
+  // Skip on non-Node runtimes (e.g. Bun) — they use independent connection
+  // pools, so warming undici's pool provides no benefit.
+  if (detectRuntime() !== 'node') {
+    debugLogger.debug('Skipping preconnect: unsupported runtime');
+    preconnectFired = true;
+    return;
+  }
+
+  const targetUrl = getPreconnectTargetUrl(authType, options.resolvedBaseUrl);
+
+  if (!targetUrl) {
+    debugLogger.debug('No target URL for preconnect');
+    return;
+  }
+
+  preconnectFired = true;
+  debugLogger.debug(`Preconnecting to: ${targetUrl}`);
+
+  try {
+    // Use the same shared undici dispatcher that SDK clients will use,
+    // so the warmed TCP+TLS connection is reused by subsequent API calls.
+    const dispatcher = getOrCreateSharedDispatcher(options.proxy);
+
+    // Fire HEAD request to warm connection (fire-and-forget)
+    fetch(targetUrl, {
+      method: 'HEAD',
+      signal: AbortSignal.timeout(5_000),
+      headers: {
+        'User-Agent': 'QwenCode-Preconnect/1.0',
+      },
+      dispatcher,
+    } as RequestInit)
+      .then(() => {
+        debugLogger.debug('Preconnect completed');
+      })
+      .catch((error) => {
+        debugLogger.debug(`Preconnect failed (ignored): ${error}`);
+      });
+  } catch (error) {
+    // Preconnect failure doesn't affect main flow
+    debugLogger.debug(`Preconnect failed (ignored): ${error}`);
+  }
+}
+
+/**
+ * Reset preconnect state (for testing only)
+ * @internal
+ */
+export function resetPreconnectState(): void {
+  preconnectFired = false;
+}
diff --git a/packages/cli/src/utils/attentionNotification.test.ts b/packages/cli/src/utils/attentionNotification.test.ts
deleted file mode 100644
index 9ebb785c7..000000000
--- a/packages/cli/src/utils/attentionNotification.test.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-/**
- * @license
- * Copyright 2025 Qwen
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import {
-  notifyTerminalAttention,
-  AttentionNotificationReason,
-} from './attentionNotification.js';
-
-describe('notifyTerminalAttention', () => {
-  let stream: { write: ReturnType<typeof vi.fn>; isTTY: boolean };
-
-  beforeEach(() => {
-    stream = { write: vi.fn().mockReturnValue(true), isTTY: true };
-  });
-
-  it('emits terminal bell character', () => {
-    const result = notifyTerminalAttention(
-      AttentionNotificationReason.ToolApproval,
-      {
-        stream,
-      },
-    );
-
-    expect(result).toBe(true);
-    expect(stream.write).toHaveBeenCalledWith('\u0007');
-  });
-
-  it('returns false when not running inside a tty', () => {
-    stream.isTTY = false;
-
-    const result = notifyTerminalAttention(
-      AttentionNotificationReason.ToolApproval,
-      { stream },
-    );
-
-    expect(result).toBe(false);
-    expect(stream.write).not.toHaveBeenCalled();
-  });
-
-  it('returns false when stream write fails', () => {
-    stream.write = vi.fn().mockImplementation(() => {
-      throw new Error('Write failed');
-    });
-
-    const result = notifyTerminalAttention(
-      AttentionNotificationReason.ToolApproval,
-      { stream },
-    );
-
-    expect(result).toBe(false);
-  });
-
-  it('works with different notification reasons', () => {
-    const reasons = [
-      AttentionNotificationReason.ToolApproval,
-      AttentionNotificationReason.LongTaskComplete,
-    ];
-
-    reasons.forEach((reason) => {
-      stream.write.mockClear();
-
-      const result = notifyTerminalAttention(reason, { stream });
-
-      expect(result).toBe(true);
-      expect(stream.write).toHaveBeenCalledWith('\u0007');
-    });
-  });
-});
diff --git a/packages/cli/src/utils/attentionNotification.ts b/packages/cli/src/utils/attentionNotification.ts
deleted file mode 100644
index 89da6826c..000000000
--- a/packages/cli/src/utils/attentionNotification.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-/**
- * @license
- * Copyright 2025 Qwen
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import process from 'node:process';
-import { createDebugLogger } from '@qwen-code/qwen-code-core';
-
-export enum AttentionNotificationReason {
-  ToolApproval = 'tool_approval',
-  LongTaskComplete = 'long_task_complete',
-}
-
-export interface TerminalNotificationOptions {
-  stream?: Pick<NodeJS.WriteStream, 'write' | 'isTTY'>;
-  enabled?: boolean;
-}
-
-const TERMINAL_BELL = '\u0007';
-const debugLogger = createDebugLogger('ATTENTION_NOTIFICATION');
-
-/**
- * Grabs the user's attention by emitting the terminal bell character.
- * This causes the terminal to flash or play a sound, alerting the user
- * to check the CLI for important events.
- *
- * @returns true when the bell was successfully written to the terminal.
- */
-export function notifyTerminalAttention(
-  _reason: AttentionNotificationReason,
-  options: TerminalNotificationOptions = {},
-): boolean {
-  // Check if terminal bell is enabled (default true for backwards compatibility)
-  if (options.enabled === false) {
-    return false;
-  }
-
-  const stream = options.stream ?? process.stdout;
-  if (!stream?.write || stream.isTTY === false) {
-    return false;
-  }
-
-  try {
-    stream.write(TERMINAL_BELL);
-    return true;
-  } catch (error) {
-    debugLogger.warn('Failed to send terminal bell:', error);
-    return false;
-  }
-}
diff --git a/packages/cli/src/utils/errors.test.ts b/packages/cli/src/utils/errors.test.ts
index 1dfa0deda..b899ab1b5 100644
--- a/packages/cli/src/utils/errors.test.ts
+++ b/packages/cli/src/utils/errors.test.ts
@@ -12,12 +12,14 @@ import {
   ToolErrorType,
 } from '@qwen-code/qwen-code-core';
 import {
+  _resetExitLatchForTest,
   getErrorMessage,
   handleError,
   handleToolError,
   handleCancellationError,
   handleMaxTurnsExceededError,
 } from './errors.js';
+import { _resetCleanupFunctionsForTest, registerCleanup } from './cleanup.js';
 
 const mockWriteStderrLine = vi.hoisted(() => vi.fn());
 const debugLoggerSpy = vi.hoisted(() => ({
@@ -99,6 +101,8 @@ describe('errors', () => {
     debugLoggerSpy.info.mockClear();
     debugLoggerSpy.warn.mockClear();
     debugLoggerSpy.error.mockClear();
+    _resetCleanupFunctionsForTest();
+    _resetExitLatchForTest();
 
     // Mock process.stderr.write
     processStderrWriteSpy = vi
@@ -176,24 +180,24 @@ describe('errors', () => {
         ).mockReturnValue(OutputFormat.TEXT);
       });
 
-      it('should log error message and re-throw', () => {
+      it('should log error message and re-throw', async () => {
         const testError = new Error('Test error');
 
-        expect(() => {
-          handleError(testError, mockConfig);
-        }).toThrow(testError);
+        await expect(handleError(testError, mockConfig)).rejects.toThrow(
+          testError,
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           'API Error: Test error',
         );
       });
 
-      it('should handle non-Error objects', () => {
+      it('should handle non-Error objects', async () => {
         const testError = 'String error';
 
-        expect(() => {
-          handleError(testError, mockConfig);
-        }).toThrow(testError);
+        await expect(handleError(testError, mockConfig)).rejects.toThrow(
+          testError,
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           'API Error: String error',
@@ -208,12 +212,12 @@ describe('errors', () => {
         ).mockReturnValue(OutputFormat.JSON);
       });
 
-      it('should format error as JSON and exit with default code', () => {
+      it('should format error as JSON and exit with default code', async () => {
         const testError = new Error('Test error');
 
-        expect(() => {
-          handleError(testError, mockConfig);
-        }).toThrow('process.exit called with code: 1');
+        await expect(handleError(testError, mockConfig)).rejects.toThrow(
+          'process.exit called with code: 1',
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           JSON.stringify(
@@ -230,12 +234,12 @@ describe('errors', () => {
         );
       });
 
-      it('should use custom error code when provided', () => {
+      it('should use custom error code when provided', async () => {
         const testError = new Error('Test error');
 
-        expect(() => {
-          handleError(testError, mockConfig, 42);
-        }).toThrow('process.exit called with code: 42');
+        await expect(handleError(testError, mockConfig, 42)).rejects.toThrow(
+          'process.exit called with code: 42',
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           JSON.stringify(
@@ -252,12 +256,12 @@ describe('errors', () => {
         );
       });
 
-      it('should extract exitCode from FatalError instances', () => {
+      it('should extract exitCode from FatalError instances', async () => {
         const fatalError = new FatalInputError('Fatal error');
 
-        expect(() => {
-          handleError(fatalError, mockConfig);
-        }).toThrow('process.exit called with code: 42');
+        await expect(handleError(fatalError, mockConfig)).rejects.toThrow(
+          'process.exit called with code: 42',
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           JSON.stringify(
@@ -274,26 +278,26 @@ describe('errors', () => {
         );
       });
 
-      it('should handle error with code property', () => {
+      it('should handle error with code property', async () => {
         const errorWithCode = new Error('Error with code') as Error & {
           code: number;
         };
         errorWithCode.code = 404;
 
-        expect(() => {
-          handleError(errorWithCode, mockConfig);
-        }).toThrow('process.exit called with code: 404');
+        await expect(handleError(errorWithCode, mockConfig)).rejects.toThrow(
+          'process.exit called with code: 404',
+        );
       });
 
-      it('should handle error with status property', () => {
+      it('should handle error with status property', async () => {
         const errorWithStatus = new Error('Error with status') as Error & {
           status: string;
         };
         errorWithStatus.status = 'TIMEOUT';
 
-        expect(() => {
-          handleError(errorWithStatus, mockConfig);
-        }).toThrow('process.exit called with code: 1'); // string codes become 1
+        await expect(handleError(errorWithStatus, mockConfig)).rejects.toThrow(
+          'process.exit called with code: 1', // string codes become 1
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           JSON.stringify(
@@ -590,10 +594,10 @@ describe('errors', () => {
         ).mockReturnValue(OutputFormat.TEXT);
       });
 
-      it('should log cancellation message and exit with 130', () => {
-        expect(() => {
-          handleCancellationError(mockConfig);
-        }).toThrow('process.exit called with code: 130');
+      it('should log cancellation message and exit with 130', async () => {
+        await expect(handleCancellationError(mockConfig)).rejects.toThrow(
+          'process.exit called with code: 130',
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           'Operation cancelled.',
@@ -608,10 +612,10 @@ describe('errors', () => {
         ).mockReturnValue(OutputFormat.JSON);
       });
 
-      it('should format cancellation as JSON and exit with 130', () => {
-        expect(() => {
-          handleCancellationError(mockConfig);
-        }).toThrow('process.exit called with code: 130');
+      it('should format cancellation as JSON and exit with 130', async () => {
+        await expect(handleCancellationError(mockConfig)).rejects.toThrow(
+          'process.exit called with code: 130',
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           JSON.stringify(
@@ -638,10 +642,10 @@ describe('errors', () => {
         ).mockReturnValue(OutputFormat.TEXT);
       });
 
-      it('should log max turns message and exit with 53', () => {
-        expect(() => {
-          handleMaxTurnsExceededError(mockConfig);
-        }).toThrow('process.exit called with code: 53');
+      it('should log max turns message and exit with 53', async () => {
+        await expect(handleMaxTurnsExceededError(mockConfig)).rejects.toThrow(
+          'process.exit called with code: 53',
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           'Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.',
@@ -656,10 +660,10 @@ describe('errors', () => {
         ).mockReturnValue(OutputFormat.JSON);
       });
 
-      it('should format max turns error as JSON and exit with 53', () => {
-        expect(() => {
-          handleMaxTurnsExceededError(mockConfig);
-        }).toThrow('process.exit called with code: 53');
+      it('should format max turns error as JSON and exit with 53', async () => {
+        await expect(handleMaxTurnsExceededError(mockConfig)).rejects.toThrow(
+          'process.exit called with code: 53',
+        );
 
         expect(mockWriteStderrLine).toHaveBeenCalledWith(
           JSON.stringify(
@@ -678,4 +682,119 @@ describe('errors', () => {
       });
     });
   });
+
+  describe('cleanup-before-exit invariant', () => {
+    // Regression: previously these handlers called process.exit synchronously,
+    // bypassing the caller's runExitCleanup → flush() chain on SIGINT, max-
+    // turn, and fatal-error paths. Same family as the EPIPE/process.exit
+    // bug fixed for stdout in nonInteractiveCli.
+    it('handleCancellationError drains registered cleanups before exit', async () => {
+      const cleanupOrder: string[] = [];
+      registerCleanup(() => {
+        cleanupOrder.push('cleanup');
+      });
+      processExitSpy.mockImplementation((code) => {
+        cleanupOrder.push(`exit:${code}`);
+        throw new Error(`process.exit called with code: ${code}`);
+      });
+
+      await expect(handleCancellationError(mockConfig)).rejects.toThrow(
+        'process.exit called with code: 130',
+      );
+
+      expect(cleanupOrder).toEqual(['cleanup', 'exit:130']);
+    });
+
+    it('handleMaxTurnsExceededError drains registered cleanups before exit', async () => {
+      const cleanupOrder: string[] = [];
+      registerCleanup(() => {
+        cleanupOrder.push('cleanup');
+      });
+      processExitSpy.mockImplementation((code) => {
+        cleanupOrder.push(`exit:${code}`);
+        throw new Error(`process.exit called with code: ${code}`);
+      });
+
+      await expect(handleMaxTurnsExceededError(mockConfig)).rejects.toThrow(
+        'process.exit called with code: 53',
+      );
+
+      expect(cleanupOrder).toEqual(['cleanup', 'exit:53']);
+    });
+
+    it('handleError drains registered cleanups before exit (JSON mode)', async () => {
+      (mockConfig.getOutputFormat as ReturnType<typeof vi.fn>).mockReturnValue(
+        OutputFormat.JSON,
+      );
+      const cleanupOrder: string[] = [];
+      registerCleanup(() => {
+        cleanupOrder.push('cleanup');
+      });
+      processExitSpy.mockImplementation((code) => {
+        cleanupOrder.push(`exit:${code}`);
+        throw new Error(`process.exit called with code: ${code}`);
+      });
+
+      await expect(handleError(new Error('boom'), mockConfig)).rejects.toThrow(
+        'process.exit called with code: 1',
+      );
+
+      expect(cleanupOrder).toEqual(['cleanup', 'exit:1']);
+    });
+
+    it('a second terminating handler does not race the first into double-exit', async () => {
+      // Models the real concurrency: SIGINT → handleCancellationError fires
+      // while a stream rejection lands in the catch → handleError(JSON).
+      // Without the exit-once latch we'd get duplicate cleanup runs +
+      // duplicate process.exit calls + interleaved stderr writes.
+      // (Text-mode handleError throws instead of exiting, so it isn't part
+      // of the race — the latch lives on the exit path.)
+      (mockConfig.getOutputFormat as ReturnType<typeof vi.fn>).mockReturnValue(
+        OutputFormat.JSON,
+      );
+
+      let exitCalls = 0;
+      processExitSpy.mockImplementation((code) => {
+        exitCalls += 1;
+        throw new Error(`process.exit called with code: ${code}`);
+      });
+
+      const first = handleCancellationError(mockConfig);
+      const second = handleError(new Error('boom'), mockConfig);
+
+      await expect(first).rejects.toThrow('process.exit called with code: 130');
+
+      // The second handler is parked in the latch's unresolved promise.
+      let secondSettled = false;
+      void second.then(
+        () => {
+          secondSettled = true;
+        },
+        () => {
+          secondSettled = true;
+        },
+      );
+      await new Promise((r) => setTimeout(r, 20));
+
+      expect(exitCalls).toBe(1);
+      expect(secondSettled).toBe(false);
+    });
+
+    it('handleError drains registered cleanups before re-throw (text mode)', async () => {
+      // Text mode re-throws to the caller; we still want the queue drained
+      // first so the unhandled-rejection path doesn't lose records.
+      (mockConfig.getOutputFormat as ReturnType<typeof vi.fn>).mockReturnValue(
+        OutputFormat.TEXT,
+      );
+      const events: string[] = [];
+      registerCleanup(() => {
+        events.push('cleanup');
+      });
+
+      const original = new Error('boom');
+      await expect(handleError(original, mockConfig)).rejects.toBe(original);
+
+      expect(events).toEqual(['cleanup']);
+    });
+  });
 });
diff --git a/packages/cli/src/utils/errors.ts b/packages/cli/src/utils/errors.ts
index 598f535b7..76d95fcfa 100644
--- a/packages/cli/src/utils/errors.ts
+++ b/packages/cli/src/utils/errors.ts
@@ -14,6 +14,7 @@ import {
   ToolErrorType,
   createDebugLogger,
 } from '@qwen-code/qwen-code-core';
+import { runExitCleanup } from './cleanup.js';
 import { writeStderrLine } from './stdioHelpers.js';
 
 const debugLogger = createDebugLogger('CLI_ERRORS');
@@ -81,16 +82,45 @@ function getNumericExitCode(errorCode: string | number): number {
   return typeof errorCode === 'number' ? errorCode : 1;
 }
 
+/**
+ * Drains pending cleanup before terminating. Routing every "we're about
+ * to die" path through here keeps async exit-side I/O (chat-recording
+ * flush, telemetry shutdown, MCP disconnect) from being skipped — the
+ * earlier sync writes were inherently bounded so a bare `process.exit`
+ * was safe; with the async-jsonl change it is not.
+ */
+// Guards against double-entry when two terminating paths race (e.g. SIGINT
+// fires `handleCancellationError` while a stream rejection routes through
+// `handleError`): only the first caller drains cleanup + exits; the second
+// suspends forever in the unresolved promise and gets killed when the first
+// caller's process.exit fires.
+let exiting = false;
+
+async function exitAfterCleanup(code: number): Promise<never> {
+  if (exiting) return new Promise<never>(() => {});
+  exiting = true;
+  await runExitCleanup();
+  // `return` so process.exit's `never` narrows the function's terminating
+  // statement — without it TS reports "function returning 'never' cannot
+  // have a reachable end point" because await doesn't propagate `never`.
+  return process.exit(code);
+}
+
+/** Test-only — reset the exit-once latch between cases. */
+export function _resetExitLatchForTest(): void {
+  exiting = false;
+}
+
 /**
  * Handles errors consistently for both JSON and text output formats.
  * In JSON mode, outputs formatted JSON error and exits.
  * In text mode, outputs error message and re-throws.
  */
-export function handleError(
+export async function handleError(
   error: unknown,
   config: Config,
   customErrorCode?: string | number,
-): never {
+): Promise<never> {
   const errorMessage = parseAndFormatApiError(
     error,
     config.getContentGeneratorConfig()?.authType,
@@ -106,9 +136,12 @@ export function handleError(
     );
 
     writeStderrLine(formattedError);
-    process.exit(getNumericExitCode(errorCode));
+    return exitAfterCleanup(getNumericExitCode(errorCode));
   } else {
     writeStderrLine(errorMessage);
+    // Drain queued writes before re-throwing so the unhandled rejection
+    // path doesn't lose chat-recording records that are still in the queue.
+    await runExitCleanup();
     throw error;
   }
 }
@@ -155,7 +188,7 @@ export function handleToolError(
 /**
  * Handles cancellation/abort signals consistently.
  */
-export function handleCancellationError(config: Config): never {
+export async function handleCancellationError(config: Config): Promise<never> {
   const cancellationError = new FatalCancellationError('Operation cancelled.');
 
   if (config.getOutputFormat() === OutputFormat.JSON) {
@@ -166,17 +199,18 @@ export function handleCancellationError(config: Config): never {
     );
 
     writeStderrLine(formattedError);
-    process.exit(cancellationError.exitCode);
   } else {
     writeStderrLine(cancellationError.message);
-    process.exit(cancellationError.exitCode);
   }
+  return exitAfterCleanup(cancellationError.exitCode);
 }
 
 /**
  * Handles max session turns exceeded consistently.
  */
-export function handleMaxTurnsExceededError(config: Config): never {
+export async function handleMaxTurnsExceededError(
+  config: Config,
+): Promise<never> {
   const maxTurnsError = new FatalTurnLimitedError(
     'Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.',
   );
@@ -189,9 +223,8 @@ export function handleMaxTurnsExceededError(config: Config): never {
     );
 
     writeStderrLine(formattedError);
-    process.exit(maxTurnsError.exitCode);
   } else {
     writeStderrLine(maxTurnsError.message);
-    process.exit(maxTurnsError.exitCode);
   }
+  return exitAfterCleanup(maxTurnsError.exitCode);
 }
diff --git a/packages/cli/src/utils/osc.test.ts b/packages/cli/src/utils/osc.test.ts
new file mode 100644
index 000000000..c407e728c
--- /dev/null
+++ b/packages/cli/src/utils/osc.test.ts
@@ -0,0 +1,280 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  detectTerminal,
+  osc,
+  wrapForMultiplexer,
+  oscITerm2Notify,
+  oscKittyNotify,
+  oscGhosttyNotify,
+  sanitizeOscPayload,
+  encodeKittyPayload,
+  OSC,
+  BEL,
+  ST,
+} from './osc.js';
+
+describe('detectTerminal', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    delete process.env['TERM_PROGRAM'];
+    delete process.env['TERM'];
+    delete process.env['KITTY_WINDOW_ID'];
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('detects iTerm.app via TERM_PROGRAM', () => {
+    process.env['TERM_PROGRAM'] = 'iTerm.app';
+    expect(detectTerminal()).toBe('iTerm.app');
+  });
+
+  it('detects kitty via TERM_PROGRAM', () => {
+    process.env['TERM_PROGRAM'] = 'kitty';
+    expect(detectTerminal()).toBe('kitty');
+  });
+
+  it('detects ghostty via TERM_PROGRAM', () => {
+    process.env['TERM_PROGRAM'] = 'ghostty';
+    expect(detectTerminal()).toBe('ghostty');
+  });
+
+  it('detects Apple_Terminal via TERM_PROGRAM', () => {
+    process.env['TERM_PROGRAM'] = 'Apple_Terminal';
+    expect(detectTerminal()).toBe('Apple_Terminal');
+  });
+
+  it('detects kitty via TERM=xterm-kitty when TERM_PROGRAM is absent', () => {
+    process.env['TERM'] = 'xterm-kitty';
+    expect(detectTerminal()).toBe('kitty');
+  });
+
+  it('detects ghostty via TERM=xterm-ghostty when TERM_PROGRAM is absent', () => {
+    process.env['TERM'] = 'xterm-ghostty';
+    expect(detectTerminal()).toBe('ghostty');
+  });
+
+  it('detects kitty via KITTY_WINDOW_ID as fallback', () => {
+    process.env['KITTY_WINDOW_ID'] = '1';
+    expect(detectTerminal()).toBe('kitty');
+  });
+
+  it('returns unknown when no terminal is detected', () => {
+    expect(detectTerminal()).toBe('unknown');
+  });
+
+  it('TERM_PROGRAM takes priority over TERM', () => {
+    process.env['TERM'] = 'xterm-ghostty';
+    process.env['TERM_PROGRAM'] = 'iTerm.app';
+    expect(detectTerminal()).toBe('iTerm.app');
+  });
+
+  it('falls back to TERM when TERM_PROGRAM is not a known terminal', () => {
+    process.env['TERM'] = 'xterm-ghostty';
+    process.env['TERM_PROGRAM'] = 'some-unknown-terminal';
+    expect(detectTerminal()).toBe('ghostty');
+  });
+
+  it('KITTY_WINDOW_ID is last resort fallback', () => {
+    process.env['TERM'] = 'xterm-256color';
+    process.env['KITTY_WINDOW_ID'] = '1';
+    expect(detectTerminal()).toBe('kitty');
+  });
+});
+
+describe('osc', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('builds OSC sequence with BEL terminator for non-kitty', () => {
+    process.env['TERM_PROGRAM'] = 'iTerm.app';
+    delete process.env['TERM'];
+    const result = osc(9, 'hello');
+    expect(result).toBe(`\x1b]9;hello${BEL}`);
+  });
+
+  it('builds OSC sequence with ST terminator for kitty', () => {
+    process.env['TERM'] = 'xterm-kitty';
+    delete process.env['TERM_PROGRAM'];
+    delete process.env['STY'];
+    const result = osc(99, 'test');
+    expect(result).toBe(`\x1b]99;test${ST}`);
+  });
+
+  it('falls back to BEL for kitty inside screen to avoid ST conflict with DCS wrapper', () => {
+    process.env['TERM'] = 'xterm-kitty';
+    delete process.env['TERM_PROGRAM'];
+    process.env['STY'] = '12345.pts-0.host';
+    const result = osc(99, 'test');
+    expect(result).toBe(`\x1b]99;test${BEL}`);
+  });
+
+  it('joins multiple parts with semicolons', () => {
+    process.env['TERM_PROGRAM'] = 'ghostty';
+    delete process.env['TERM'];
+    const result = osc(777, 'notify', 'Title', 'Body');
+    expect(result).toBe(`\x1b]777;notify;Title;Body${BEL}`);
+  });
+});
+
+describe('wrapForMultiplexer', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('returns sequence unchanged outside multiplexer', () => {
+    delete process.env['TMUX'];
+    delete process.env['STY'];
+    const seq = `\x1b]9;hello${BEL}`;
+    expect(wrapForMultiplexer(seq)).toBe(seq);
+  });
+
+  it('wraps in DCS passthrough for tmux with ESC doubling', () => {
+    process.env['TMUX'] = '/tmp/tmux-1000/default,12345,0';
+    delete process.env['STY'];
+    const seq = `\x1b]9;hello${BEL}`;
+    // ESC bytes in payload should be doubled
+    expect(wrapForMultiplexer(seq)).toBe(
+      `\x1bPtmux;\x1b\x1b]9;hello${BEL}\x1b\\`,
+    );
+  });
+
+  it('wraps in DCS passthrough for screen', () => {
+    delete process.env['TMUX'];
+    process.env['STY'] = '12345.pts-0.host';
+    const seq = `\x1b]9;hello${BEL}`;
+    expect(wrapForMultiplexer(seq)).toBe(`\x1bP${seq}\x1b\\`);
+  });
+});
+
+describe('oscITerm2Notify', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('formats notification with title and message', () => {
+    process.env['TERM_PROGRAM'] = 'iTerm.app';
+    delete process.env['TERM'];
+    const result = oscITerm2Notify('Qwen Code', 'Hello');
+    expect(result).toContain('Qwen Code:\nHello');
+  });
+
+  it('formats notification without title', () => {
+    process.env['TERM_PROGRAM'] = 'iTerm.app';
+    delete process.env['TERM'];
+    const result = oscITerm2Notify('', 'Hello');
+    expect(result).toContain('Hello');
+    expect(result).not.toContain(':');
+  });
+});
+
+describe('encodeKittyPayload', () => {
+  it('base64-encodes ASCII text', () => {
+    expect(encodeKittyPayload('Title')).toBe(
+      Buffer.from('Title', 'utf8').toString('base64'),
+    );
+  });
+
+  it('base64-encodes UTF-8 text', () => {
+    expect(encodeKittyPayload('你好')).toBe(
+      Buffer.from('你好', 'utf8').toString('base64'),
+    );
+  });
+});
+
+describe('oscKittyNotify', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('returns three-step protocol sequences with base64-encoded payloads', () => {
+    process.env['TERM'] = 'xterm-kitty';
+    delete process.env['TERM_PROGRAM'];
+    delete process.env['STY'];
+    const seqs = oscKittyNotify('Title', 'Body', 42);
+    expect(seqs).toHaveLength(3);
+    const b64Title = Buffer.from('Title', 'utf8').toString('base64');
+    const b64Body = Buffer.from('Body', 'utf8').toString('base64');
+    // Step 1: title with e=1 (base64)
+    expect(seqs[0]).toContain('i=42:d=0:p=title:e=1');
+    expect(seqs[0]).toContain(b64Title);
+    expect(seqs[0]).not.toContain('Title');
+    // Step 2: body with e=1 (base64)
+    expect(seqs[1]).toContain('i=42:p=body:e=1');
+    expect(seqs[1]).toContain(b64Body);
+    expect(seqs[1]).not.toContain('Body');
+    // Step 3: activate (no payload to encode)
+    expect(seqs[2]).toContain('i=42:d=1:a=focus');
+  });
+});
+
+describe('oscGhosttyNotify', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('formats OSC 777 notification', () => {
+    process.env['TERM_PROGRAM'] = 'ghostty';
+    delete process.env['TERM'];
+    const result = oscGhosttyNotify('Title', 'Body');
+    expect(result).toBe(`\x1b]${OSC.GHOSTTY};notify;Title;Body${BEL}`);
+  });
+});
+
+describe('sanitizeOscPayload', () => {
+  it('strips ESC character', () => {
+    expect(sanitizeOscPayload('hello\x1bworld')).toBe('helloworld');
+  });
+
+  it('strips BEL character', () => {
+    expect(sanitizeOscPayload('hello\x07world')).toBe('helloworld');
+  });
+
+  it('strips all C0 control characters', () => {
+    expect(sanitizeOscPayload('a\x00b\x01c\x1fd')).toBe('abcd');
+  });
+
+  it('preserves normal text', () => {
+    expect(sanitizeOscPayload('Hello World! 你好')).toBe('Hello World! 你好');
+  });
+
+  it('strips C1 control characters', () => {
+    expect(sanitizeOscPayload('hello\x9cworld')).toBe('helloworld');
+  });
+});
+
+describe('osc sanitizes payloads', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('strips control characters from string parts', () => {
+    process.env['TERM_PROGRAM'] = 'ghostty';
+    delete process.env['TERM'];
+    const result = osc(OSC.GHOSTTY, 'notify', 'Title\x1b]hack', 'Body\x07end');
+    expect(result).not.toContain('\x1b]hack');
+    expect(result).toContain('Title]hack');
+    expect(result).toContain('Bodyend');
+  });
+});
diff --git a/packages/cli/src/utils/osc.ts b/packages/cli/src/utils/osc.ts
new file mode 100644
index 000000000..a58a2f10e
--- /dev/null
+++ b/packages/cli/src/utils/osc.ts
@@ -0,0 +1,196 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * OSC (Operating System Command) escape sequence utilities for terminal
+ * notifications, tab status indicators, and multiplexer passthrough.
+ */
+
+// ── Escape sequence primitives ──────────────────────────────────────
+
+export const ESC = '\x1b';
+export const BEL = '\x07';
+/** String Terminator — used by Kitty instead of BEL */
+export const ST = ESC + '\\';
+export const OSC_PREFIX = ESC + ']';
+const SEP = ';';
+
+// ── OSC type codes ──────────────────────────────────────────────────
+
+export const OSC = {
+  /** iTerm2 notification / progress */
+  ITERM2: 9,
+  /** Kitty desktop notification protocol */
+  KITTY: 99,
+  /** Ghostty / cmux notification */
+  GHOSTTY: 777,
+} as const;
+
+// ── Terminal type detection ─────────────────────────────────────────
+
+export type TerminalType =
+  | 'iTerm.app'
+  | 'kitty'
+  | 'ghostty'
+  | 'Apple_Terminal'
+  | 'unknown';
+
+/**
+ * Detect the current terminal emulator from environment variables.
+ *
+ * Strategy: check TERM_PROGRAM first (identifies the actual emulator),
+ * then fall back to TERM (describes capabilities, but Ghostty/Kitty set
+ * distinctive TERM values when TERM_PROGRAM is absent — e.g. over SSH
+ * or inside multiplexers), and finally check terminal-specific env vars.
+ */
+export function detectTerminal(): TerminalType {
+  // 1. TERM_PROGRAM — most reliable for identifying the emulator
+  const termProgram = process.env['TERM_PROGRAM'];
+  switch (termProgram) {
+    case 'iTerm.app':
+      return 'iTerm.app';
+    case 'kitty':
+      return 'kitty';
+    case 'ghostty':
+      return 'ghostty';
+    case 'Apple_Terminal':
+      return 'Apple_Terminal';
+    default:
+      break;
+  }
+
+  // 2. TERM — Ghostty and Kitty set distinctive TERM values even when
+  //    TERM_PROGRAM is absent (SSH sessions, multiplexers)
+  if (process.env['TERM'] === 'xterm-ghostty') {
+    return 'ghostty';
+  }
+  if (process.env['TERM']?.includes('kitty')) {
+    return 'kitty';
+  }
+
+  // 3. Terminal-specific env vars as last resort
+  if (process.env['KITTY_WINDOW_ID']) return 'kitty';
+
+  return 'unknown';
+}
+
+// ── Sanitization ───────────────────────────────────────────────────
+
+/**
+ * Strip control characters that could break out of an OSC payload.
+ * Removes ESC (\x1b), BEL (\x07), ST (ESC + \), and other C0/C1
+ * control bytes that terminals interpret as sequence boundaries.
+ * Preserves HT (\t), LF (\n), and CR (\r) which are safe in payloads.
+ */
+export function sanitizeOscPayload(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\x80-\x9f]/g, '');
+}
+
+// ── Core OSC builders ───────────────────────────────────────────────
+
+/**
+ * Build an OSC escape sequence from parts.
+ *
+ * Terminator selection:
+ * - Kitty prefers ST (`ESC \`), but ST inside a GNU screen DCS wrapper
+ *   would prematurely terminate the outer DCS. So when `STY` is set
+ *   (screen session), we fall back to BEL even for Kitty.
+ * - All other terminals always use BEL.
+ *
+ * All string parts are sanitized to prevent control character injection.
+ */
+export function osc(...parts: Array<string | number>): string {
+  const isKitty = detectTerminal() === 'kitty';
+  const inScreen = !!process.env['STY'];
+  // Use ST for Kitty except inside screen where ST conflicts with DCS wrapper
+  const terminator = isKitty && !inScreen ? ST : BEL;
+  const sanitized = parts.map((p) =>
+    typeof p === 'string' ? sanitizeOscPayload(p) : p,
+  );
+  return `${OSC_PREFIX}${sanitized.join(SEP)}${terminator}`;
+}
+
+/**
+ * Wrap an OSC sequence for tmux / screen passthrough.
+ *
+ * - tmux: DCS `\ePtmux;\e<seq>\e\\` with ESC doubling inside
+ * - screen: DCS `\eP<seq>\e\\`
+ *
+ * BEL should NOT be wrapped — raw BEL triggers tmux's bell-action,
+ * whereas a wrapped BEL becomes an opaque DCS payload and is ignored.
+ */
+export function wrapForMultiplexer(sequence: string): string {
+  if (process.env['TMUX']) {
+    // tmux requires all ESC bytes inside the payload to be doubled
+    const escaped = sequence.replaceAll('\x1b', '\x1b\x1b');
+    return `\x1bPtmux;${escaped}\x1b\\`;
+  }
+  if (process.env['STY']) {
+    return `\x1bP${sequence}\x1b\\`;
+  }
+  return sequence;
+}
+
+// ── Encoding helpers ───────────────────────────────────────────────
+
+/**
+ * Base64-encode a UTF-8 string for Kitty OSC 99 payloads.
+ * Kitty requires `e=1` (base64) encoding to safely transport arbitrary
+ * UTF-8 text without delimiter/control-character conflicts.
+ */
+export function encodeKittyPayload(text: string): string {
+  return Buffer.from(text, 'utf8').toString('base64');
+}
+
+// ── Notification helpers ────────────────────────────────────────────
+
+/**
+ * iTerm2 notification via OSC 9.
+ * Format: `\e]9;\n\n<title>:\n<message>\a`
+ */
+export function oscITerm2Notify(title: string, message: string): string {
+  const displayString = title ? `${title}:\n${message}` : message;
+  // The \n\n prefix signals iTerm2 to show a system notification
+  // rather than just a tab badge/growl.
+  return osc(OSC.ITERM2, `\n\n${displayString}`);
+}
+
+/**
+ * Kitty desktop notification via OSC 99 (three-step protocol).
+ * Returns an array of sequences that must be written in order.
+ *
+ * Payloads are base64-encoded (`e=1`) as required by the Kitty
+ * notification protocol to safely transport UTF-8 text.
+ *
+ * @see https://sw.kovidgoyal.net/kitty/desktop-notifications/
+ */
+export function oscKittyNotify(
+  title: string,
+  message: string,
+  id: number,
+): string[] {
+  return [
+    osc(OSC.KITTY, `i=${id}:d=0:p=title:e=1`, encodeKittyPayload(title)),
+    osc(OSC.KITTY, `i=${id}:p=body:e=1`, encodeKittyPayload(message)),
+    osc(OSC.KITTY, `i=${id}:d=1:a=focus`, ''),
+  ];
+}
+
+/**
+ * Ghostty / cmux notification via OSC 777.
+ * Format: `\e]777;notify;<title>;<message>\a`
+ */
+export function oscGhosttyNotify(title: string, message: string): string {
+  return osc(OSC.GHOSTTY, 'notify', title, message);
+}
+
+/**
+ * Generate a random Kitty notification ID.
+ */
+export function generateKittyId(): number {
+  return Math.floor(Math.random() * 2 ** 31);
+}
diff --git a/packages/core/src/agents/agent-transcript.test.ts b/packages/core/src/agents/agent-transcript.test.ts
new file mode 100644
index 000000000..ccf17d8c1
--- /dev/null
+++ b/packages/core/src/agents/agent-transcript.test.ts
@@ -0,0 +1,408 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  getSubagentSessionDir,
+  getAgentJsonlPath,
+  getAgentMetaPath,
+  attachJsonlTranscriptWriter,
+  writeAgentMeta,
+  type AgentMeta,
+} from './agent-transcript.js';
+import { AgentEventEmitter, AgentEventType } from './runtime/agent-events.js';
+import type { ChatRecord } from '../services/chatRecordingService.js';
+
+describe('agent-transcript', () => {
+  describe('path helpers', () => {
+    it('places the session dir under projectDir/subagents/<sessionId>', () => {
+      expect(getSubagentSessionDir('/proj', 'sess-1')).toBe(
+        path.join('/proj', 'subagents', 'sess-1'),
+      );
+    });
+
+    it('returns .jsonl path for the canonical transcript', () => {
+      expect(getAgentJsonlPath('/proj', 'sess-1', 'agent-1')).toBe(
+        path.join('/proj', 'subagents', 'sess-1', 'agent-agent-1.jsonl'),
+      );
+    });
+
+    it('returns .meta.json path for the sidecar', () => {
+      expect(getAgentMetaPath('/proj', 'sess-1', 'agent-1')).toBe(
+        path.join('/proj', 'subagents', 'sess-1', 'agent-agent-1.meta.json'),
+      );
+    });
+
+    it('sanitizes agentId to prevent path traversal', () => {
+      const result = getAgentJsonlPath(
+        '/proj',
+        'sess-1',
+        '../../../etc/passwd',
+      );
+      expect(result).not.toContain('..');
+      expect(result).toContain(
+        path.join('/proj', 'subagents', 'sess-1') + path.sep,
+      );
+      expect(result.endsWith('.jsonl')).toBe(true);
+    });
+
+    it('sanitizes sessionId to prevent path traversal', () => {
+      const result = getAgentJsonlPath('/proj', '../escape', 'agent-1');
+      expect(result).not.toContain('..');
+      expect(
+        result.startsWith(path.join('/proj', 'subagents') + path.sep),
+      ).toBe(true);
+    });
+
+    it('preserves alphanumerics, underscores, and hyphens in agentId', () => {
+      expect(getAgentJsonlPath('/proj', 'sess', 'agent_1-abc')).toBe(
+        path.join('/proj', 'subagents', 'sess', 'agent-agent_1-abc.jsonl'),
+      );
+    });
+  });
+
+  describe('writeAgentMeta', () => {
+    let tempDir: string;
+
+    beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'meta-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it('writes a JSON sidecar with the expected fields', () => {
+      const metaPath = path.join(
+        tempDir,
+        'subagents',
+        's1',
+        'agent-a.meta.json',
+      );
+      const meta: AgentMeta = {
+        agentId: 'a',
+        agentType: 'explore',
+        description: 'Explore: list ts files',
+        parentSessionId: 's1',
+        parentAgentId: null,
+        createdAt: '2026-04-20T00:00:00.000Z',
+      };
+      writeAgentMeta(metaPath, meta);
+      const parsed = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      expect(parsed).toEqual(meta);
+    });
+
+    it('creates parent directories that do not yet exist', () => {
+      const metaPath = path.join(
+        tempDir,
+        'a',
+        'deeply',
+        'nested',
+        'agent.meta.json',
+      );
+      writeAgentMeta(metaPath, {
+        agentId: 'a',
+        agentType: 'x',
+        description: 'd',
+        parentSessionId: 's',
+        parentAgentId: null,
+        createdAt: 'now',
+      });
+      expect(fs.existsSync(metaPath)).toBe(true);
+    });
+  });
+
+  describe('attachJsonlTranscriptWriter (canonical)', () => {
+    let tempDir: string;
+
+    beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsonl-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    function readJsonl(p: string): ChatRecord[] {
+      return fs
+        .readFileSync(p, 'utf-8')
+        .split('\n')
+        .filter((l) => l.trim().length > 0)
+        .map((l) => JSON.parse(l) as ChatRecord);
+    }
+
+    function makeWriter(
+      jsonlPath: string,
+      extra: { initialUserPrompt?: string } = {},
+    ) {
+      const emitter = new AgentEventEmitter();
+      const { cleanup } = attachJsonlTranscriptWriter(emitter, jsonlPath, {
+        agentId: 'agent-x',
+        agentName: 'explore',
+        agentColor: 'blue',
+        sessionId: 'session-1',
+        cwd: '/proj',
+        version: '1.2.3',
+        gitBranch: 'main',
+        ...extra,
+      });
+      return { emitter, cleanup };
+    }
+
+    it('stamps base fields on every subagent record', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      emitter.emit(AgentEventType.ROUND_TEXT, {
+        subagentId: 'agent-x',
+        round: 1,
+        text: 'Hello',
+        thoughtText: '',
+        timestamp: Date.now(),
+      });
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records).toHaveLength(1);
+      const r = records[0];
+      expect(r.agentId).toBe('agent-x');
+      expect(r.agentName).toBe('explore');
+      expect(r.agentColor).toBe('blue');
+      expect(r.isSidechain).toBe(true);
+      expect(r.sessionId).toBe('session-1');
+      expect(r.cwd).toBe('/proj');
+      expect(r.version).toBe('1.2.3');
+      expect(r.gitBranch).toBe('main');
+      expect(r.parentUuid).toBeNull();
+    });
+
+    it('writes a ROUND_TEXT event as an assistant record with text part', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      emitter.emit(AgentEventType.ROUND_TEXT, {
+        subagentId: 'agent-x',
+        round: 1,
+        text: 'Hello',
+        thoughtText: '',
+        timestamp: Date.now(),
+      });
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records).toHaveLength(1);
+      expect(records[0].type).toBe('assistant');
+      expect(records[0].message?.parts?.[0]).toMatchObject({ text: 'Hello' });
+    });
+
+    it('drops empty ROUND_TEXT to keep the canonical view free of noise', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      emitter.emit(AgentEventType.ROUND_TEXT, {
+        subagentId: 'agent-x',
+        round: 1,
+        text: '',
+        thoughtText: '',
+        timestamp: Date.now(),
+      });
+      cleanup();
+
+      expect(fs.existsSync(jsonlPath)).toBe(false);
+    });
+
+    it('writes TOOL_CALL events as assistant records with functionCall parts', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      emitter.emit(AgentEventType.TOOL_CALL, {
+        subagentId: 'agent-x',
+        round: 1,
+        callId: 'c1',
+        name: 'read_file',
+        args: { file_path: '/x.txt' },
+        description: 'read x',
+        timestamp: Date.now(),
+      });
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records).toHaveLength(1);
+      const part = records[0].message?.parts?.[0] as {
+        functionCall?: { id: string; name: string; args: unknown };
+      };
+      expect(part.functionCall).toMatchObject({
+        id: 'c1',
+        name: 'read_file',
+        args: { file_path: '/x.txt' },
+      });
+    });
+
+    it('writes TOOL_RESULT events as tool_result records with toolCallResult metadata', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      emitter.emit(AgentEventType.TOOL_RESULT, {
+        subagentId: 'agent-x',
+        round: 1,
+        callId: 'c1',
+        name: 'read_file',
+        success: true,
+        durationMs: 7,
+        timestamp: Date.now(),
+      });
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records).toHaveLength(1);
+      expect(records[0].type).toBe('tool_result');
+      expect(records[0].toolCallResult).toMatchObject({
+        callId: 'c1',
+        durationMs: 7,
+      });
+    });
+
+    it('preserves real responseParts from TOOL_RESULT when present', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      const responseParts = [
+        {
+          functionResponse: {
+            id: 'c1',
+            name: 'read_file',
+            response: { output: 'line1\nline2\n' },
+          },
+        },
+      ];
+      emitter.emit(AgentEventType.TOOL_RESULT, {
+        subagentId: 'agent-x',
+        round: 1,
+        callId: 'c1',
+        name: 'read_file',
+        success: true,
+        responseParts,
+        timestamp: Date.now(),
+      });
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records[0].message?.parts).toEqual(responseParts);
+    });
+
+    it('chains parentUuid across multiple records', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      emitter.emit(AgentEventType.ROUND_TEXT, {
+        subagentId: 'agent-x',
+        round: 1,
+        text: 'hi',
+        thoughtText: '',
+        timestamp: 1,
+      });
+      emitter.emit(AgentEventType.TOOL_CALL, {
+        subagentId: 'agent-x',
+        round: 1,
+        callId: 'c1',
+        name: 'read_file',
+        args: {},
+        description: '',
+        timestamp: 2,
+      });
+      emitter.emit(AgentEventType.TOOL_RESULT, {
+        subagentId: 'agent-x',
+        round: 1,
+        callId: 'c1',
+        name: 'read_file',
+        success: true,
+        timestamp: 3,
+      });
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records).toHaveLength(3);
+      expect(records[0].parentUuid).toBeNull();
+      expect(records[1].parentUuid).toBe(records[0].uuid);
+      expect(records[2].parentUuid).toBe(records[1].uuid);
+    });
+
+    it('seeds the JSONL with the launching prompt as a user-role record', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { cleanup } = makeWriter(jsonlPath, {
+        initialUserPrompt: 'Find all TODO comments',
+      });
+
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records).toHaveLength(1);
+      expect(records[0].type).toBe('user');
+      expect(records[0].message).toEqual({
+        role: 'user',
+        parts: [{ text: 'Find all TODO comments' }],
+      });
+      expect(records[0].isSidechain).toBe(true);
+      expect(records[0].parentUuid).toBeNull();
+    });
+
+    it('skips an empty initialUserPrompt so the chain stays clean', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { cleanup } = makeWriter(jsonlPath, { initialUserPrompt: '' });
+
+      cleanup();
+
+      expect(fs.existsSync(jsonlPath)).toBe(false);
+    });
+
+    it('writes EXTERNAL_MESSAGE events as user records chained after the seed', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath, {
+        initialUserPrompt: 'initial prompt',
+      });
+
+      emitter.emit(AgentEventType.EXTERNAL_MESSAGE, {
+        subagentId: 'agent-x',
+        text: 'follow-up from parent',
+        timestamp: 100,
+      });
+      cleanup();
+
+      const records = readJsonl(jsonlPath);
+      expect(records).toHaveLength(2);
+      expect(records[1].type).toBe('user');
+      expect(records[1].message).toEqual({
+        role: 'user',
+        parts: [{ text: 'follow-up from parent' }],
+      });
+      expect(records[1].parentUuid).toBe(records[0].uuid);
+    });
+
+    it('stops writing after cleanup', () => {
+      const jsonlPath = path.join(tempDir, 's', 'agent-x.jsonl');
+      const { emitter, cleanup } = makeWriter(jsonlPath);
+
+      cleanup();
+      emitter.emit(AgentEventType.ROUND_TEXT, {
+        subagentId: 'agent-x',
+        round: 1,
+        text: 'late',
+        thoughtText: '',
+        timestamp: 1,
+      });
+      emitter.emit(AgentEventType.EXTERNAL_MESSAGE, {
+        subagentId: 'agent-x',
+        text: 'late injection',
+        timestamp: 2,
+      });
+
+      expect(fs.existsSync(jsonlPath)).toBe(false);
+    });
+  });
+});
diff --git a/packages/core/src/agents/agent-transcript.ts b/packages/core/src/agents/agent-transcript.ts
new file mode 100644
index 000000000..c2d73f1bf
--- /dev/null
+++ b/packages/core/src/agents/agent-transcript.ts
@@ -0,0 +1,287 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Per-agent transcript for background subagents.
+ *
+ * Each background subagent produces two sibling files under
+ * `<projectDir>/subagents/<sessionId>/`:
+ *
+ *   agent-<id>.jsonl       — canonical, ChatRecord-shaped event log;
+ *                            the model reads this via read_file to check
+ *                            in-flight progress and <output-file> in the
+ *                            notification XML points here
+ *   agent-<id>.meta.json   — sidecar with agentType, description, parent
+ *                            session/agent IDs, createdAt
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import {
+  AgentEventType,
+  type AgentEventEmitter,
+  type AgentToolCallEvent,
+  type AgentToolResultEvent,
+  type AgentRoundTextEvent,
+  type AgentExternalMessageEvent,
+} from './runtime/agent-events.js';
+import { type ChatRecord } from '../services/chatRecordingService.js';
+import { createDebugLogger } from '../utils/debugLogger.js';
+
+const debugLogger = createDebugLogger('AGENT_TRANSCRIPT');
+
+function sanitizeFilenameComponent(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+
+/**
+ * Returns the directory holding all subagent transcripts for a given session.
+ * Layout: `<projectDir>/subagents/<sessionId>/`.
+ *
+ * TODO: this path is part of the model-facing contract via `<output-file>` in
+ * the task-notification XML. When a second background task kind lands (e.g. a
+ * shell pool), migrate to `<projectDir>/tasks/<sessionId>/<kind>-<id>.jsonl`
+ * so the namespace generalizes. Update `read-file.ts` auto-allow accordingly.
+ */
+export function getSubagentSessionDir(
+  projectDir: string,
+  sessionId: string,
+): string {
+  // Sanitize sessionId defensively (UUIDs are safe; resumed/external IDs
+  // could carry path-traversal bytes).
+  return path.join(
+    projectDir,
+    'subagents',
+    sanitizeFilenameComponent(sessionId),
+  );
+}
+
+/** Returns the canonical JSONL transcript path. */
+export function getAgentJsonlPath(
+  projectDir: string,
+  sessionId: string,
+  agentId: string,
+): string {
+  return path.join(
+    getSubagentSessionDir(projectDir, sessionId),
+    `agent-${sanitizeFilenameComponent(agentId)}.jsonl`,
+  );
+}
+
+/** Returns the sidecar metadata file path. */
+export function getAgentMetaPath(
+  projectDir: string,
+  sessionId: string,
+  agentId: string,
+): string {
+  return path.join(
+    getSubagentSessionDir(projectDir, sessionId),
+    `agent-${sanitizeFilenameComponent(agentId)}.meta.json`,
+  );
+}
+
+export interface AgentMeta {
+  agentId: string;
+  agentType: string;
+  description: string;
+  /** SessionId of the user session that launched this agent. */
+  parentSessionId: string;
+  /** AgentId of the launching subagent for nested forks; null for top-level. */
+  parentAgentId: string | null;
+  /** ISO 8601 creation time. */
+  createdAt: string;
+}
+
+/**
+ * Best-effort — a failed sidecar write must not break the agent launch path.
+ */
+export function writeAgentMeta(metaPath: string, meta: AgentMeta): void {
+  try {
+    fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+  } catch (error) {
+    debugLogger.warn(`Failed to write agent meta sidecar ${metaPath}:`, error);
+  }
+}
+
+export interface AttachJsonlOptions {
+  /** Subagent identifier — populated on every record. */
+  agentId: string;
+  /** Display name (subagent type), e.g. "explore". */
+  agentName?: string;
+  /** UI hint. */
+  agentColor?: string;
+  /** Parent user-session UUID — recorded as `sessionId` on every record. */
+  sessionId: string;
+  /** cwd at launch time, for resume context. */
+  cwd: string;
+  /** CLI version for compatibility tracking. */
+  version: string;
+  /** Optional git branch at launch time. */
+  gitBranch?: string;
+  /**
+   * Launching prompt — recorded as the first `user`-role record so the
+   * transcript is self-describing. Empty/omitted seeds nothing.
+   */
+  initialUserPrompt?: string;
+}
+
+export interface AttachJsonlTranscriptResult {
+  /** Removes the event listeners and closes the file handle. Idempotent. */
+  cleanup: () => void;
+}
+
+/**
+ * Subscribes to an AgentEventEmitter and appends ChatRecord-shaped JSONL
+ * lines to `jsonlPath`. Maintains a parentUuid chain so consumers can walk
+ * the transcript tree the same way they walk the main session log.
+ *
+ * Holds a single append-mode fd for the lifetime of the writer so streaming
+ * tools (which can fire many TOOL_CALL/TOOL_RESULT events per round) avoid
+ * an open+write+close syscall storm. The fd is opened lazily on the first
+ * write so callers that attach but never produce a record don't materialize
+ * an empty file.
+ */
+export function attachJsonlTranscriptWriter(
+  emitter: AgentEventEmitter,
+  jsonlPath: string,
+  options: AttachJsonlOptions,
+): AttachJsonlTranscriptResult {
+  let lastUuid: string | null = null;
+  let fd: number | null = null;
+  let openFailed = false;
+
+  const ensureOpen = (): boolean => {
+    if (fd !== null) return true;
+    if (openFailed) return false;
+    try {
+      fs.mkdirSync(path.dirname(jsonlPath), { recursive: true });
+      fd = fs.openSync(jsonlPath, 'a');
+      return true;
+    } catch (error) {
+      debugLogger.warn(`Failed to open JSONL transcript ${jsonlPath}:`, error);
+      openFailed = true;
+      return false;
+    }
+  };
+
+  const baseFields = (type: ChatRecord['type']) => ({
+    uuid: randomUUID(),
+    parentUuid: lastUuid,
+    sessionId: options.sessionId,
+    timestamp: new Date().toISOString(),
+    type,
+    cwd: options.cwd,
+    version: options.version,
+    gitBranch: options.gitBranch,
+    agentId: options.agentId,
+    agentName: options.agentName,
+    agentColor: options.agentColor,
+    isSidechain: true,
+  });
+
+  const append = (record: ChatRecord) => {
+    if (!ensureOpen()) return;
+    try {
+      fs.writeSync(fd!, JSON.stringify(record) + '\n');
+      lastUuid = record.uuid;
+    } catch (error) {
+      debugLogger.warn(`Failed to append JSONL record to ${jsonlPath}:`, error);
+    }
+  };
+
+  const onRoundText = (event: AgentRoundTextEvent) => {
+    if (!event.text) return;
+    append({
+      ...baseFields('assistant'),
+      message: { role: 'model', parts: [{ text: event.text }] },
+    });
+  };
+
+  const onToolCall = (event: AgentToolCallEvent) => {
+    append({
+      ...baseFields('assistant'),
+      message: {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              id: event.callId,
+              name: event.name,
+              args: event.args,
+            },
+          },
+        ],
+      },
+    });
+  };
+
+  const onToolResult = (event: AgentToolResultEvent) => {
+    // Prefer the real response parts the model saw; fall back to a status
+    // stub only when the agent aborted before a response was formed.
+    const parts = event.responseParts ?? [
+      {
+        functionResponse: {
+          id: event.callId,
+          name: event.name,
+          response: {
+            success: event.success,
+            ...(event.error ? { error: event.error } : {}),
+          },
+        },
+      },
+    ];
+    append({
+      ...baseFields('tool_result'),
+      message: { role: 'user', parts },
+      toolCallResult: {
+        callId: event.callId,
+        ...(event.durationMs !== undefined
+          ? { durationMs: event.durationMs }
+          : {}),
+      },
+    });
+  };
+
+  const recordUserMessage = (text: string) => {
+    if (!text) return;
+    append({
+      ...baseFields('user'),
+      message: { role: 'user', parts: [{ text }] },
+    });
+  };
+
+  const onExternalMessage = (event: AgentExternalMessageEvent) => {
+    recordUserMessage(event.text);
+  };
+
+  if (options.initialUserPrompt) {
+    recordUserMessage(options.initialUserPrompt);
+  }
+
+  emitter.on(AgentEventType.ROUND_TEXT, onRoundText);
+  emitter.on(AgentEventType.TOOL_CALL, onToolCall);
+  emitter.on(AgentEventType.TOOL_RESULT, onToolResult);
+  emitter.on(AgentEventType.EXTERNAL_MESSAGE, onExternalMessage);
+
+  const cleanup = () => {
+    emitter.off(AgentEventType.ROUND_TEXT, onRoundText);
+    emitter.off(AgentEventType.TOOL_CALL, onToolCall);
+    emitter.off(AgentEventType.TOOL_RESULT, onToolResult);
+    emitter.off(AgentEventType.EXTERNAL_MESSAGE, onExternalMessage);
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // best effort
+      }
+      fd = null;
+    }
+  };
+
+  return { cleanup };
+}
diff --git a/packages/core/src/agents/backends/InProcessBackend.test.ts b/packages/core/src/agents/backends/InProcessBackend.test.ts
index 6bddb0b7a..fb515a5d5 100644
--- a/packages/core/src/agents/backends/InProcessBackend.test.ts
+++ b/packages/core/src/agents/backends/InProcessBackend.test.ts
@@ -21,34 +21,64 @@ vi.mock('../../core/contentGenerator.js', () => ({
   }),
 }));
 
-// Mock AgentCore and AgentInteractive to avoid real model calls
+// Mock AgentCore and AgentInteractive to avoid real model calls.
+// The mock must also expose the observable-state accessors that
+// AgentInteractive now delegates to (getMessages, pendingApprovals,
+// liveOutputs, shellPids, pushMessage, etc.) — otherwise agent lifecycle
+// methods like abort() / addMessage() fail on missing prototype methods.
 vi.mock('../runtime/agent-core.js', () => ({
-  AgentCore: vi.fn().mockImplementation(() => ({
-    subagentId: 'mock-id',
-    name: 'mock-agent',
-    eventEmitter: {
+  AgentCore: vi.fn().mockImplementation(() => {
+    const messages: Array<Record<string, unknown>> = [];
+    const pendingApprovals = new Map<string, unknown>();
+    const liveOutputs = new Map<string, unknown>();
+    const shellPids = new Map<string, number>();
+    const emitter = {
       on: vi.fn(),
       off: vi.fn(),
       emit: vi.fn(),
-    },
-    stats: {
-      start: vi.fn(),
-      getSummary: vi.fn().mockReturnValue({}),
-    },
-    createChat: vi.fn().mockResolvedValue({}),
-    prepareTools: vi.fn().mockReturnValue([]),
-    runReasoningLoop: vi.fn().mockResolvedValue({
-      text: 'Done',
-      terminateMode: null,
-      turnsUsed: 1,
-    }),
-    getEventEmitter: vi.fn().mockReturnValue({
-      on: vi.fn(),
-      off: vi.fn(),
-      emit: vi.fn(),
-    }),
-    getExecutionSummary: vi.fn().mockReturnValue({}),
-  })),
+    };
+    return {
+      subagentId: 'mock-id',
+      name: 'mock-agent',
+      eventEmitter: emitter,
+      stats: {
+        start: vi.fn(),
+        getSummary: vi.fn().mockReturnValue({}),
+      },
+      createChat: vi.fn().mockResolvedValue({}),
+      prepareTools: vi.fn().mockReturnValue([]),
+      runReasoningLoop: vi.fn().mockResolvedValue({
+        text: 'Done',
+        terminateMode: null,
+        turnsUsed: 1,
+      }),
+      getEventEmitter: vi.fn().mockReturnValue(emitter),
+      getExecutionSummary: vi.fn().mockReturnValue({}),
+      getMessages: () => messages,
+      getPendingApprovals: () => pendingApprovals,
+      getLiveOutputs: () => liveOutputs,
+      getShellPids: () => shellPids,
+      pushMessage: (
+        role: string,
+        content: string,
+        options?: { thought?: boolean; metadata?: Record<string, unknown> },
+      ) => {
+        const message: Record<string, unknown> = {
+          role,
+          content,
+          timestamp: Date.now(),
+        };
+        if (options?.thought) message['thought'] = true;
+        if (options?.metadata) message['metadata'] = options.metadata;
+        messages.push(message);
+      },
+      setPendingApproval: (callId: string, details: unknown) =>
+        pendingApprovals.set(callId, details),
+      deletePendingApproval: (callId: string) =>
+        pendingApprovals.delete(callId),
+      clearPendingApprovals: () => pendingApprovals.clear(),
+    };
+  }),
 }));
 
 function createMockToolRegistry() {
diff --git a/packages/core/src/agents/background-tasks.test.ts b/packages/core/src/agents/background-tasks.test.ts
index 3a401e15b..e69155dd9 100644
--- a/packages/core/src/agents/background-tasks.test.ts
+++ b/packages/core/src/agents/background-tasks.test.ts
@@ -77,7 +77,14 @@ describe('BackgroundTaskRegistry', () => {
     expect(displayText).toContain('failed');
   });
 
-  it('cancels a running background agent', () => {
+  it('cancels a running background agent without emitting a notification', () => {
+    // cancel() is intent-only: it aborts the signal and marks the entry
+    // cancelled, but does not emit a task-notification. The natural
+    // completion handler (bgBody) emits the terminal notification with
+    // the agent's real partial/final result via complete()/fail().
+    const callback = vi.fn();
+    registry.setNotificationCallback(callback);
+
     const abortController = new AbortController();
 
     registry.register({
@@ -92,6 +99,115 @@ describe('BackgroundTaskRegistry', () => {
 
     expect(registry.get('test-1')!.status).toBe('cancelled');
     expect(abortController.signal.aborted).toBe(true);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it('emits a fallback cancelled notification after the grace period when the natural handler never runs', () => {
+    vi.useFakeTimers();
+    try {
+      const callback = vi.fn();
+      registry.setNotificationCallback(callback);
+
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      });
+
+      registry.cancel('test-1');
+      expect(callback).not.toHaveBeenCalled();
+
+      // Pathological tool case: bgBody never emits. After the grace period
+      // the fallback fires so hasUnfinalizedTasks() stops reporting true
+      // and the headless wait loop can exit.
+      vi.runAllTimers();
+
+      expect(callback).toHaveBeenCalledOnce();
+      const [, modelText] = callback.mock.calls[0] as [string, string];
+      expect(modelText).toContain('<status>cancelled</status>');
+      expect(registry.hasUnfinalizedTasks()).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('skips the fallback notification when the natural handler finalizes first', () => {
+    vi.useFakeTimers();
+    try {
+      const callback = vi.fn();
+      registry.setNotificationCallback(callback);
+
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      });
+
+      registry.cancel('test-1');
+      // Natural handler wins the race with the partial result.
+      registry.finalizeCancelled('test-1', 'partial output');
+      expect(callback).toHaveBeenCalledOnce();
+      callback.mockClear();
+
+      vi.runAllTimers();
+
+      // Fallback lands on a notified entry and no-ops.
+      expect(callback).not.toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('finalizeCancellationIfPending emits a fallback cancelled notification', () => {
+    const callback = vi.fn();
+    registry.setNotificationCallback(callback);
+
+    registry.register({
+      agentId: 'test-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    registry.cancel('test-1');
+    registry.finalizeCancellationIfPending('test-1');
+
+    expect(callback).toHaveBeenCalledOnce();
+    const [, modelText] = callback.mock.calls[0] as [string, string];
+    expect(modelText).toContain('<status>cancelled</status>');
+  });
+
+  it('complete() after the cancellation has already been notified is a no-op', () => {
+    // Once finalizeCancelled has emitted the terminal notification, a
+    // late-arriving complete() must not double-fire — the SDK contract
+    // is one notification per task_started.
+    const callback = vi.fn();
+    registry.setNotificationCallback(callback);
+
+    registry.register({
+      agentId: 'test-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    registry.cancel('test-1');
+    registry.finalizeCancelled('test-1', 'partial');
+    expect(callback).toHaveBeenCalledOnce();
+    callback.mockClear();
+
+    registry.complete('test-1', 'late result');
+
+    expect(callback).not.toHaveBeenCalled();
+    // Status stays cancelled — the notified terminal state wins.
+    expect(registry.get('test-1')!.status).toBe('cancelled');
+    expect(registry.get('test-1')!.result).toBe('partial');
   });
 
   it('does not cancel a non-running agent', () => {
@@ -130,12 +246,15 @@ describe('BackgroundTaskRegistry', () => {
 
     registry.complete('a', 'done');
 
-    const running = registry.getRunning();
+    const running = registry.getAll().filter((e) => e.status === 'running');
     expect(running).toHaveLength(1);
     expect(running[0].agentId).toBe('b');
   });
 
-  it('aborts all running agents', () => {
+  it('aborts all running agents and emits fallback notifications', () => {
+    const callback = vi.fn();
+    registry.setNotificationCallback(callback);
+
     const ac1 = new AbortController();
     const ac2 = new AbortController();
 
@@ -160,9 +279,63 @@ describe('BackgroundTaskRegistry', () => {
     expect(ac2.signal.aborted).toBe(true);
     expect(registry.get('a')!.status).toBe('cancelled');
     expect(registry.get('b')!.status).toBe('cancelled');
+    // abortAll is a shutdown path — no natural handler will fire, so
+    // finalizeCancellationIfPending emits one cancelled notification per
+    // agent to keep the SDK contract intact.
+    expect(callback).toHaveBeenCalledTimes(2);
   });
 
-  it('complete is a no-op after cancellation (state race guard)', () => {
+  it('hasUnfinalizedTasks reports cancelled-but-not-notified entries', () => {
+    // Headless runs rely on this to keep the event loop alive after a
+    // task_stop until the agent's natural handler has emitted the
+    // terminal task-notification — otherwise the matching notification
+    // can be dropped before stream-json/SDK consumers observe it.
+    registry.register({
+      agentId: 'test-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    expect(registry.hasUnfinalizedTasks()).toBe(true);
+
+    registry.cancel('test-1');
+    expect(registry.get('test-1')!.status).toBe('cancelled');
+    expect(registry.hasUnfinalizedTasks()).toBe(true);
+
+    registry.finalizeCancelled('test-1', '');
+    expect(registry.hasUnfinalizedTasks()).toBe(false);
+  });
+
+  it('hasUnfinalizedTasks clears once every entry has been notified', () => {
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.register({
+      agentId: 'b',
+      description: 'agent b',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    expect(registry.hasUnfinalizedTasks()).toBe(true);
+    registry.complete('a', 'done');
+    expect(registry.hasUnfinalizedTasks()).toBe(true);
+    registry.fail('b', 'boom');
+    expect(registry.hasUnfinalizedTasks()).toBe(false);
+  });
+
+  it('complete after cancellation surfaces the real result', () => {
+    // When cancel races with the natural completion handler, the agent's
+    // reasoning loop may have finished with a real result before the abort
+    // landed. complete() transitions cancelled → completed and emits the
+    // terminal notification carrying that real result, instead of letting
+    // the bare "cancelled" notification discard it.
     const callback = vi.fn();
     registry.setNotificationCallback(callback);
 
@@ -175,18 +348,19 @@ describe('BackgroundTaskRegistry', () => {
     });
 
     registry.cancel('test-1');
-    registry.complete('test-1', 'late result');
+    registry.complete('test-1', 'real result after cancel race');
 
-    // Status should remain 'cancelled', not flip to 'completed'
-    expect(registry.get('test-1')!.status).toBe('cancelled');
-    // Exactly one notification, emitted by cancel() itself — the late
-    // complete() must be no-op'd by the running-status guard.
+    expect(registry.get('test-1')!.status).toBe('completed');
+    expect(registry.get('test-1')!.result).toBe(
+      'real result after cancel race',
+    );
     expect(callback).toHaveBeenCalledTimes(1);
     const [, modelText] = callback.mock.calls[0];
-    expect(modelText).toContain('<status>cancelled</status>');
+    expect(modelText).toContain('<status>completed</status>');
+    expect(modelText).toContain('real result after cancel race');
   });
 
-  it('fail is a no-op after cancellation (state race guard)', () => {
+  it('fail after cancellation surfaces the real error', () => {
     const callback = vi.fn();
     registry.setNotificationCallback(callback);
 
@@ -199,12 +373,34 @@ describe('BackgroundTaskRegistry', () => {
     });
 
     registry.cancel('test-1');
+    registry.fail('test-1', 'real error after cancel race');
+
+    expect(registry.get('test-1')!.status).toBe('failed');
+    expect(registry.get('test-1')!.error).toBe('real error after cancel race');
+    expect(callback).toHaveBeenCalledTimes(1);
+    const [, modelText] = callback.mock.calls[0];
+    expect(modelText).toContain('<status>failed</status>');
+  });
+
+  it('second terminal call does not double-notify', () => {
+    // Once a terminal notification has fired, subsequent terminal calls
+    // (from late fire-and-forget paths) must not produce a duplicate.
+    const callback = vi.fn();
+    registry.setNotificationCallback(callback);
+
+    registry.register({
+      agentId: 'test-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    registry.complete('test-1', 'first');
     registry.fail('test-1', 'late error');
 
-    expect(registry.get('test-1')!.status).toBe('cancelled');
     expect(callback).toHaveBeenCalledTimes(1);
-    const [, modelText] = callback.mock.calls[0];
-    expect(modelText).toContain('<status>cancelled</status>');
+    expect(registry.get('test-1')!.status).toBe('completed');
   });
 
   it('does not send notification without callback', () => {
@@ -261,6 +457,190 @@ describe('BackgroundTaskRegistry', () => {
     expect(meta.toolUseId).toBeUndefined();
   });
 
+  it('getAll returns every entry regardless of status', () => {
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.register({
+      agentId: 'b',
+      description: 'agent b',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.register({
+      agentId: 'c',
+      description: 'agent c',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    registry.complete('a', 'done');
+    registry.fail('b', 'boom');
+
+    const all = registry.getAll();
+    expect(all).toHaveLength(3);
+    expect(all.map((e) => e.status).sort()).toEqual([
+      'completed',
+      'failed',
+      'running',
+    ]);
+    // Callers that need only running entries filter getAll() themselves.
+    expect(
+      registry
+        .getAll()
+        .filter((e) => e.status === 'running')
+        .map((e) => e.agentId),
+    ).toEqual(['c']);
+  });
+
+  it('statusChange callback fires on register and every state transition', () => {
+    const seen: Array<{ id: string; status: string }> = [];
+    registry.setStatusChangeCallback((entry) => {
+      seen.push({ id: entry.agentId, status: entry.status });
+    });
+
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.register({
+      agentId: 'b',
+      description: 'agent b',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.complete('a', 'ok');
+    registry.fail('b', 'err');
+
+    expect(seen).toEqual([
+      { id: 'a', status: 'running' },
+      { id: 'b', status: 'running' },
+      { id: 'a', status: 'completed' },
+      { id: 'b', status: 'failed' },
+    ]);
+  });
+
+  it('statusChange callback errors do not break registry operations', () => {
+    registry.setStatusChangeCallback(() => {
+      throw new Error('listener broke');
+    });
+
+    // Should not throw even though the callback does.
+    expect(() =>
+      registry.register({
+        agentId: 'a',
+        description: 'agent a',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      }),
+    ).not.toThrow();
+    expect(registry.get('a')?.status).toBe('running');
+  });
+
+  it('statusChange callback can be cleared with undefined', () => {
+    const cb = vi.fn();
+    registry.setStatusChangeCallback(cb);
+    registry.setStatusChangeCallback(undefined);
+
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  it('appendActivity builds a rolling buffer capped at 5', () => {
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    for (let i = 0; i < 7; i++) {
+      registry.appendActivity('a', {
+        name: `Tool${i}`,
+        description: `call ${i}`,
+        at: i,
+      });
+    }
+
+    const activities = registry.get('a')!.recentActivities ?? [];
+    expect(activities.map((a) => a.name)).toEqual([
+      'Tool2',
+      'Tool3',
+      'Tool4',
+      'Tool5',
+      'Tool6',
+    ]);
+  });
+
+  it('appendActivity no-ops after the agent terminates', () => {
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    registry.complete('a', 'done');
+    registry.appendActivity('a', { name: 'Late', description: 'x', at: 99 });
+
+    expect(registry.get('a')!.recentActivities ?? []).toHaveLength(0);
+  });
+
+  it('appendActivity fires activityChange, not statusChange', () => {
+    const statusCb = vi.fn();
+    const activityCb = vi.fn();
+    registry.setStatusChangeCallback(statusCb);
+    registry.setActivityChangeCallback(activityCb);
+
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    statusCb.mockClear();
+    activityCb.mockClear();
+
+    registry.appendActivity('a', { name: 'T', description: 'd', at: 0 });
+
+    expect(statusCb).not.toHaveBeenCalled();
+    expect(activityCb).toHaveBeenCalledOnce();
+    expect(activityCb.mock.calls[0][0].agentId).toBe('a');
+  });
+
+  it('stores prompt verbatim on the entry', () => {
+    registry.register({
+      agentId: 'a',
+      description: 'agent a',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+      prompt: 'Run sleep 30 and report done.',
+    });
+    expect(registry.get('a')!.prompt).toBe('Run sleep 30 and report done.');
+  });
+
   it('escapes XML metacharacters in interpolated fields', () => {
     const callback = vi.fn();
     registry.setNotificationCallback(callback);
@@ -284,4 +664,113 @@ describe('BackgroundTaskRegistry', () => {
     expect(modelText).toContain('&lt;b&gt;bold&lt;/b&gt;');
     expect(modelText).toContain('&amp;');
   });
+
+  describe('queueMessage', () => {
+    it('queues a message for a running agent', () => {
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      });
+
+      const result = registry.queueMessage('test-1', 'hello');
+      expect(result).toBe(true);
+      expect(registry.get('test-1')!.pendingMessages).toEqual(['hello']);
+    });
+
+    it('returns false for non-existent agent', () => {
+      expect(registry.queueMessage('nope', 'hello')).toBe(false);
+    });
+
+    it('returns false for non-running agent', () => {
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      });
+      registry.complete('test-1', 'done');
+
+      expect(registry.queueMessage('test-1', 'hello')).toBe(false);
+    });
+  });
+
+  describe('drainMessages', () => {
+    it('drains all messages and clears the queue', () => {
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      });
+
+      registry.queueMessage('test-1', 'msg-1');
+      registry.queueMessage('test-1', 'msg-2');
+
+      const messages = registry.drainMessages('test-1');
+      expect(messages).toEqual(['msg-1', 'msg-2']);
+      expect(registry.get('test-1')!.pendingMessages).toEqual([]);
+    });
+
+    it('returns empty array when no messages queued', () => {
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      });
+
+      expect(registry.drainMessages('test-1')).toEqual([]);
+    });
+
+    it('returns empty array for non-existent agent', () => {
+      expect(registry.drainMessages('nope')).toEqual([]);
+    });
+  });
+
+  describe('notification XML', () => {
+    it('includes output-file tag when outputFile is set', () => {
+      const callback = vi.fn();
+      registry.setNotificationCallback(callback);
+
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+        outputFile: '/tmp/agents/test-1.txt',
+      });
+
+      registry.complete('test-1', 'done');
+
+      const [, modelText] = callback.mock.calls[0];
+      expect(modelText).toContain(
+        '<output-file>/tmp/agents/test-1.txt</output-file>',
+      );
+    });
+
+    it('omits output-file tag when outputFile is not set', () => {
+      const callback = vi.fn();
+      registry.setNotificationCallback(callback);
+
+      registry.register({
+        agentId: 'test-1',
+        description: 'test agent',
+        status: 'running',
+        startTime: Date.now(),
+        abortController: new AbortController(),
+      });
+
+      registry.complete('test-1', 'done');
+
+      const [, modelText] = callback.mock.calls[0];
+      expect(modelText).not.toContain('<output-file>');
+    });
+  });
 });
diff --git a/packages/core/src/agents/background-tasks.ts b/packages/core/src/agents/background-tasks.ts
index aa3b60b69..8e30e1828 100644
--- a/packages/core/src/agents/background-tasks.ts
+++ b/packages/core/src/agents/background-tasks.ts
@@ -17,7 +17,46 @@ import { createDebugLogger } from '../utils/debugLogger.js';
 const debugLogger = createDebugLogger('BACKGROUND_TASKS');
 
 const MAX_DESCRIPTION_LENGTH = 40;
-const MAX_RESULT_LENGTH = 2000;
+const MAX_RECENT_ACTIVITIES = 5;
+
+// Grace period after cancel() before emitting a fallback cancelled
+// notification. The natural handler (bgBody) almost always settles and
+// emits the terminal notification with the real partial result well
+// within this window; the timeout only fires for pathological tools
+// that ignore AbortSignal. Must be long enough that normal scheduler
+// unwind wins the race, short enough that a stuck headless wait loop
+// doesn't feel hung.
+const CANCEL_GRACE_MS = 5000;
+
+/**
+ * Single source of truth for the human-facing label of a background
+ * entry. Shared by the notification payload (model-facing) and the TUI
+ * dialog (user-facing) so the two surfaces never drift.
+ *
+ * When `includePrefix` is true (default), returns `subagentType: desc`;
+ * when false, returns the bare truncated description — used where the
+ * subagent type is already rendered separately (e.g. the dialog header).
+ */
+export function buildBackgroundEntryLabel(
+  entry: { description: string; subagentType?: string },
+  options: { includePrefix?: boolean } = {},
+): string {
+  const { includePrefix = true } = options;
+  let raw = entry.description;
+  if (
+    entry.subagentType &&
+    raw.toLowerCase().startsWith(entry.subagentType.toLowerCase() + ':')
+  ) {
+    raw = raw.slice(entry.subagentType.length + 1).trimStart();
+  }
+  const truncated =
+    raw.length > MAX_DESCRIPTION_LENGTH
+      ? raw.slice(0, MAX_DESCRIPTION_LENGTH - 1) + '\u2026'
+      : raw;
+  return includePrefix && entry.subagentType
+    ? `${entry.subagentType}: ${truncated}`
+    : truncated;
+}
 
 // Escape text so it is safe to interpolate into an XML element body.
 // Subagent-produced strings (description, result, error) can contain `<`,
@@ -32,7 +71,7 @@ function escapeXml(text: string): string {
     .replace(/>/g, '&gt;');
 }
 
-export type BackgroundAgentStatus =
+export type BackgroundTaskStatus =
   | 'running'
   | 'completed'
   | 'failed'
@@ -44,11 +83,26 @@ export interface AgentCompletionStats {
   durationMs: number;
 }
 
-export interface BackgroundAgentEntry {
+/**
+ * A compact record of a recent tool invocation — drives the Progress
+ * section of the detail dialog. The Agent tool maintains a rolling
+ * buffer of these on each background entry by subscribing to the
+ * subagent's event emitter.
+ */
+export interface BackgroundActivity {
+  /** Tool name (e.g. `Bash`, `Read`). */
+  name: string;
+  /** Short one-line description — the tool's own render-friendly summary. */
+  description: string;
+  /** Emission timestamp (ms). */
+  at: number;
+}
+
+export interface BackgroundTaskEntry {
   agentId: string;
   description: string;
   subagentType?: string;
-  status: BackgroundAgentStatus;
+  status: BackgroundTaskStatus;
   startTime: number;
   endTime?: number;
   result?: string;
@@ -56,11 +110,37 @@ export interface BackgroundAgentEntry {
   abortController: AbortController;
   stats?: AgentCompletionStats;
   toolUseId?: string;
+  /**
+   * The original user-supplied prompt for the background task. Surfaced
+   * verbatim in the detail dialog's Prompt section. Optional because
+   * resume-restored entries may not have it.
+   */
+  prompt?: string;
+  /**
+   * Rolling buffer (newest last, capped at MAX_RECENT_ACTIVITIES) of
+   * recent tool invocations by this agent. Feeds the detail dialog's
+   * Progress section. Replaced as a new array each time an activity is
+   * appended so reference-based change detection works. Optional:
+   * callers may register without providing it, and `appendActivity`
+   * initializes the array lazily.
+   */
+  recentActivities?: readonly BackgroundActivity[];
+  /** Absolute path to the agent's on-disk JSONL transcript file. */
+  outputFile?: string;
+  /** Messages queued by SendMessage, drained between tool rounds. */
+  pendingMessages?: string[];
+  /**
+   * True once a terminal task-notification has been emitted for this entry.
+   * Prevents duplicate notifications when cancel races with the natural
+   * completion path (cancel aborts the signal; the agent's own handler then
+   * fires the notification with the real partial/final result).
+   */
+  notified?: boolean;
 }
 
 export interface NotificationMeta {
   agentId: string;
-  status: BackgroundAgentStatus;
+  status: BackgroundTaskStatus;
   stats?: AgentCompletionStats;
   toolUseId?: string;
 }
@@ -71,14 +151,32 @@ export type BackgroundNotificationCallback = (
   meta: NotificationMeta,
 ) => void;
 
-export type BackgroundRegisterCallback = (entry: BackgroundAgentEntry) => void;
+export type BackgroundRegisterCallback = (entry: BackgroundTaskEntry) => void;
+
+/**
+ * Fires on entry status transitions — register, complete, fail, cancel.
+ * Intentionally does NOT fire on `appendActivity` so consumers that only
+ * care about the pill / roster (Footer, AppContainer) don't re-render
+ * on every tool call a background agent makes.
+ */
+export type BackgroundStatusChangeCallback = (
+  entry: BackgroundTaskEntry,
+) => void;
+
+/** Fires on `appendActivity` — scoped to detail-view consumers. */
+export type BackgroundActivityChangeCallback = (
+  entry: BackgroundTaskEntry,
+) => void;
 
 export class BackgroundTaskRegistry {
-  private readonly agents = new Map<string, BackgroundAgentEntry>();
+  private readonly agents = new Map<string, BackgroundTaskEntry>();
   private notificationCallback?: BackgroundNotificationCallback;
   private registerCallback?: BackgroundRegisterCallback;
+  private statusChangeCallback?: BackgroundStatusChangeCallback;
+  private activityChangeCallback?: BackgroundActivityChangeCallback;
 
-  register(entry: BackgroundAgentEntry): void {
+  register(entry: BackgroundTaskEntry): void {
+    if (!entry.pendingMessages) entry.pendingMessages = [];
     this.agents.set(entry.agentId, entry);
     debugLogger.info(`Registered background agent: ${entry.agentId}`);
 
@@ -89,16 +187,26 @@ export class BackgroundTaskRegistry {
         debugLogger.error('Failed to emit register callback:', error);
       }
     }
+    this.emitStatusChange(entry);
   }
 
-  // No-op if not 'running' — guards against race with concurrent cancellation.
+  // Transition a still-running entry to 'completed' and emit the terminal
+  // notification. No-op if the entry is already terminal *and* has been
+  // notified — protects against duplicate emission when cancel aborts the
+  // signal and the natural handler also races to completion.
   complete(
     agentId: string,
     result: string,
     stats?: AgentCompletionStats,
   ): void {
     const entry = this.agents.get(agentId);
-    if (!entry || entry.status !== 'running') return;
+    if (!entry) return;
+    // Allow running → completed (normal path) and cancelled → completed
+    // (cancel raced the natural handler: the reasoning loop finished with
+    // a real result before the abort landed, and we prefer to surface that
+    // real result over the bare cancel).
+    if (entry.status !== 'running' && entry.status !== 'cancelled') return;
+    if (entry.notified) return;
 
     entry.status = 'completed';
     entry.endTime = Date.now();
@@ -107,12 +215,15 @@ export class BackgroundTaskRegistry {
     debugLogger.info(`Background agent completed: ${agentId}`);
 
     this.emitNotification(entry);
+    this.emitStatusChange(entry);
   }
 
-  // No-op if not 'running' — guards against race with concurrent cancellation.
+  // See complete() for the cancelled → terminal path rationale.
   fail(agentId: string, error: string, stats?: AgentCompletionStats): void {
     const entry = this.agents.get(agentId);
-    if (!entry || entry.status !== 'running') return;
+    if (!entry) return;
+    if (entry.status !== 'running' && entry.status !== 'cancelled') return;
+    if (entry.notified) return;
 
     entry.status = 'failed';
     entry.endTime = Date.now();
@@ -121,12 +232,17 @@ export class BackgroundTaskRegistry {
     debugLogger.info(`Background agent failed: ${agentId}`);
 
     this.emitNotification(entry);
+    this.emitStatusChange(entry);
   }
 
-  // Emit the terminal notification here — the fire-and-forget complete()/fail()
-  // path is guarded by `status !== 'running'` and will no-op, so without this the
-  // SDK contract breaks: consumers saw task_started but never receive a matching
-  // task_notification.
+  // Cancellation aborts the signal and marks the entry as cancelled, but
+  // does *not* emit the terminal notification immediately. The natural
+  // completion path (bgBody) fires complete()/fail()/finalizeCancelled()
+  // with the real partial/final result, which carries far more information
+  // than a bare "cancelled" message. A deferred fallback handles the rare
+  // case where a tool ignores AbortSignal and bgBody never settles — the
+  // timeout lands on finalizeCancellationIfPending(), which is a no-op
+  // once the natural handler has already emitted.
   cancel(agentId: string): void {
     const entry = this.agents.get(agentId);
     if (!entry || entry.status !== 'running') return;
@@ -135,18 +251,124 @@ export class BackgroundTaskRegistry {
     entry.status = 'cancelled';
     entry.endTime = Date.now();
     debugLogger.info(`Background agent cancelled: ${agentId}`);
+    this.emitStatusChange(entry);
 
-    this.emitNotification(entry);
+    const timer = setTimeout(() => {
+      this.finalizeCancellationIfPending(agentId);
+    }, CANCEL_GRACE_MS);
+    timer.unref?.();
   }
 
-  get(agentId: string): BackgroundAgentEntry | undefined {
+  // Emit the terminal cancelled notification once the agent's natural
+  // handler has confirmed that the reasoning loop ended because of the
+  // abort (terminateMode === CANCELLED). Attaches the partial result and
+  // stats so the parent model still sees whatever work the agent had
+  // captured before the abort landed, instead of a bare "cancelled" line.
+  finalizeCancelled(
+    agentId: string,
+    partialResult: string,
+    stats?: AgentCompletionStats,
+  ): void {
+    const entry = this.agents.get(agentId);
+    if (!entry) return;
+    if (entry.status !== 'running' && entry.status !== 'cancelled') return;
+    if (entry.notified) return;
+
+    entry.status = 'cancelled';
+    entry.endTime ??= Date.now();
+    if (partialResult) entry.result = partialResult;
+    entry.stats = stats;
+    this.emitNotification(entry);
+    this.emitStatusChange(entry);
+  }
+
+  // Emit the terminal cancelled notification for entries that were cancelled
+  // but for which no natural handler delivered a follow-up complete()/fail()/
+  // finalizeCancelled(). Used by shutdown paths (abortAll) to guarantee the
+  // SDK contract (every registered agent produces exactly one
+  // task-notification).
+  finalizeCancellationIfPending(agentId: string): void {
+    const entry = this.agents.get(agentId);
+    if (!entry || entry.status !== 'cancelled' || entry.notified) return;
+    this.emitNotification(entry);
+    this.emitStatusChange(entry);
+  }
+
+  /**
+   * Append a recent tool activity to a running entry's rolling buffer.
+   * No-op if the entry is not running — late events after a cancellation
+   * shouldn't leak into the Progress section.
+   */
+  appendActivity(agentId: string, activity: BackgroundActivity): void {
+    const entry = this.agents.get(agentId);
+    if (!entry || entry.status !== 'running') return;
+
+    const prior = entry.recentActivities ?? [];
+    const next = [...prior, activity];
+    if (next.length > MAX_RECENT_ACTIVITIES) {
+      next.splice(0, next.length - MAX_RECENT_ACTIVITIES);
+    }
+    entry.recentActivities = next;
+    this.emitActivityChange(entry);
+  }
+
+  get(agentId: string): BackgroundTaskEntry | undefined {
     return this.agents.get(agentId);
   }
 
-  getRunning(): BackgroundAgentEntry[] {
-    return Array.from(this.agents.values()).filter(
-      (e) => e.status === 'running',
+  /**
+   * Snapshot of every entry regardless of status. Used by the TUI
+   * footer/dialog to render rows for still-running AND terminal-state
+   * tasks; the headless holdback loop keys off `hasUnfinalizedTasks`
+   * instead, so callers that only need the running slice can filter
+   * this snapshot at the call site.
+   */
+  getAll(): BackgroundTaskEntry[] {
+    return Array.from(this.agents.values());
+  }
+
+  /**
+   * True if any registered task has not yet emitted its terminal
+   * task-notification. Covers `running` (still executing) and
+   * `cancelled`-but-not-finalized (cancel requested, but the natural
+   * handler hasn't fired finalizeCancelled() yet). Headless callers
+   * must keep their event loop alive while this returns true, so every
+   * task_started is paired with a matching task_notification.
+   */
+  hasUnfinalizedTasks(): boolean {
+    for (const entry of this.agents.values()) {
+      if (!entry.notified) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Enqueue a message for delivery to a running background agent.
+   * The agent drains this queue between tool rounds.
+   */
+  queueMessage(agentId: string, message: string): boolean {
+    const entry = this.agents.get(agentId);
+    if (!entry || entry.status !== 'running') return false;
+    const queue = entry.pendingMessages!;
+    queue.push(message);
+    debugLogger.info(
+      `Queued message for background agent ${agentId} (${queue.length} pending)`,
     );
+    return true;
+  }
+
+  /**
+   * Drain all pending messages for an agent. Returns the messages
+   * and clears the queue. Called by the agent's reasoning loop.
+   */
+  drainMessages(agentId: string): string[] {
+    const entry = this.agents.get(agentId);
+    if (!entry || !entry.pendingMessages!.length) return [];
+    const messages = entry.pendingMessages!.splice(0);
+    debugLogger.info(
+      `Drained ${messages.length} message(s) for background agent ${agentId}`,
+    );
+    return messages;
   }
 
   setNotificationCallback(
@@ -159,31 +381,39 @@ export class BackgroundTaskRegistry {
     this.registerCallback = cb;
   }
 
+  setStatusChangeCallback(
+    cb: BackgroundStatusChangeCallback | undefined,
+  ): void {
+    this.statusChangeCallback = cb;
+  }
+
+  setActivityChangeCallback(
+    cb: BackgroundActivityChangeCallback | undefined,
+  ): void {
+    this.activityChangeCallback = cb;
+  }
+
   abortAll(): void {
     for (const entry of Array.from(this.agents.values())) {
       this.cancel(entry.agentId);
+      // Shutdown path: no natural handler will run, so emit the cancelled
+      // notification here to honour the one-notification-per-agent contract.
+      this.finalizeCancellationIfPending(entry.agentId);
     }
     debugLogger.info('Aborted all background agents');
   }
 
-  private buildDisplayLabel(entry: BackgroundAgentEntry): string {
-    // Strip the subagent type prefix if the description already starts with it
-    // to avoid duplication like "Explore: Explore: list ts files".
-    let rawDesc = entry.description;
-    if (
-      entry.subagentType &&
-      rawDesc.toLowerCase().startsWith(entry.subagentType.toLowerCase() + ':')
-    ) {
-      rawDesc = rawDesc.slice(entry.subagentType.length + 1).trimStart();
-    }
-    const desc =
-      rawDesc.length > MAX_DESCRIPTION_LENGTH
-        ? rawDesc.slice(0, MAX_DESCRIPTION_LENGTH) + '...'
-        : rawDesc;
-    return entry.subagentType ? `${entry.subagentType}: ${desc}` : desc;
+  private buildDisplayLabel(entry: BackgroundTaskEntry): string {
+    return buildBackgroundEntryLabel(entry);
   }
 
-  private emitNotification(entry: BackgroundAgentEntry): void {
+  private emitNotification(entry: BackgroundTaskEntry): void {
+    // Mark notified *before* invoking the callback so that a re-entrant
+    // terminal call inside the callback chain (cancel → complete race)
+    // sees the flag and short-circuits, rather than firing twice.
+    if (entry.notified) return;
+    entry.notified = true;
+
     if (!this.notificationCallback) return;
 
     const statusText =
@@ -196,14 +426,6 @@ export class BackgroundTaskRegistry {
     const label = this.buildDisplayLabel(entry);
     const displayLine = `Background agent "${label}" ${statusText}.`;
 
-    // Truncate before escaping so we don't slice through an escape
-    // sequence (e.g. mid-`&amp;`) and emit malformed XML.
-    const rawResult = entry.result
-      ? entry.result.length > MAX_RESULT_LENGTH
-        ? entry.result.slice(0, MAX_RESULT_LENGTH) + '\n[truncated]'
-        : entry.result
-      : undefined;
-
     const xmlParts: string[] = [
       '<task-notification>',
       `<task-id>${escapeXml(entry.agentId)}</task-id>`,
@@ -215,12 +437,17 @@ export class BackgroundTaskRegistry {
       `<status>${escapeXml(entry.status)}</status>`,
       `<summary>Agent "${escapeXml(entry.description)}" ${statusText}.</summary>`,
     );
-    if (rawResult) {
-      xmlParts.push(`<result>${escapeXml(rawResult)}</result>`);
+    if (entry.result) {
+      xmlParts.push(`<result>${escapeXml(entry.result)}</result>`);
     }
     if (entry.error) {
       xmlParts.push(`<result>Error: ${escapeXml(entry.error)}</result>`);
     }
+    if (entry.outputFile) {
+      xmlParts.push(
+        `<output-file>${escapeXml(entry.outputFile)}</output-file>`,
+      );
+    }
     if (entry.stats) {
       xmlParts.push(
         '<usage>',
@@ -245,4 +472,22 @@ export class BackgroundTaskRegistry {
       debugLogger.error('Failed to emit background notification:', error);
     }
   }
+
+  private emitStatusChange(entry: BackgroundTaskEntry): void {
+    if (!this.statusChangeCallback) return;
+    try {
+      this.statusChangeCallback(entry);
+    } catch (error) {
+      debugLogger.error('Failed to emit background status change:', error);
+    }
+  }
+
+  private emitActivityChange(entry: BackgroundTaskEntry): void {
+    if (!this.activityChangeCallback) return;
+    try {
+      this.activityChangeCallback(entry);
+    } catch (error) {
+      debugLogger.error('Failed to emit background activity change:', error);
+    }
+  }
 }
diff --git a/packages/core/src/agents/runtime/agent-core.ts b/packages/core/src/agents/runtime/agent-core.ts
index 763594540..8f8202965 100644
--- a/packages/core/src/agents/runtime/agent-core.ts
+++ b/packages/core/src/agents/runtime/agent-core.ts
@@ -29,6 +29,7 @@ import {
 import type {
   ToolConfirmationOutcome,
   ToolCallConfirmationDetails,
+  ToolResultDisplay,
 } from '../../tools/tools.js';
 import { getInitialChatHistory } from '../../utils/environmentContext.js';
 import { FinishReason } from '@google/genai';
@@ -46,6 +47,7 @@ import type {
   ModelConfig,
   RunConfig,
   ToolConfig,
+  AgentMessage,
 } from './agent-types.js';
 import { AgentTerminateMode } from './agent-types.js';
 import type {
@@ -56,8 +58,9 @@ import type {
   AgentToolOutputUpdateEvent,
   AgentUsageEvent,
   AgentHooks,
+  AgentExternalMessageEvent,
 } from './agent-events.js';
-import { type AgentEventEmitter, AgentEventType } from './agent-events.js';
+import { AgentEventEmitter, AgentEventType } from './agent-events.js';
 import { AgentStatistics, type AgentStatsSummary } from './agent-statistics.js';
 import { matchesMcpPattern } from '../../permissions/rule-parser.js';
 import { ToolNames } from '../../tools/tool-names.js';
@@ -71,14 +74,27 @@ import { type ContextState, templateString } from './agent-headless.js';
  * Tools that must never be available to subagents (including forked agents).
  * - AgentTool prevents recursive subagent spawning.
  * - Cron tools are session-scoped and should only run from the main session.
+ * - TaskStop and SendMessage are parent-side control-plane tools for managing
+ *   background subagents; subagents have no agent IDs to manage natively, so
+ *   exposing them only widens the surface for cross-agent interference if an
+ *   ID leaks via prompt or transcript.
  */
 export const EXCLUDED_TOOLS_FOR_SUBAGENTS: ReadonlySet<string> = new Set([
   ToolNames.AGENT,
   ToolNames.CRON_CREATE,
   ToolNames.CRON_LIST,
   ToolNames.CRON_DELETE,
+  ToolNames.TASK_STOP,
+  ToolNames.SEND_MESSAGE,
 ]);
 
+/**
+ * Prefix applied to each external message injected into a background agent's
+ * reasoning loop via getExternalMessages. Kept here so tests and any future
+ * parsers can import the same literal.
+ */
+export const EXTERNAL_MESSAGE_PREFIX = '[Message from parent agent]:';
+
 export interface ReasoningLoopResult {
   /** The final model text response (empty if terminated by abort/limits). */
   text: string;
@@ -98,6 +114,12 @@ export interface ReasoningLoopOptions {
   maxTimeMinutes?: number;
   /** Start time in ms (for timeout calculation). Defaults to Date.now(). */
   startTimeMs?: number;
+  /**
+   * Optional callback to drain external messages between tool rounds.
+   * Called after processFunctionCalls completes. Returned strings are
+   * appended to the next model request as user-role content.
+   */
+  getExternalMessages?: () => string[];
 }
 
 /**
@@ -153,10 +175,26 @@ export class AgentCore {
   readonly modelConfig: ModelConfig;
   readonly runConfig: RunConfig;
   readonly toolConfig?: ToolConfig;
-  readonly eventEmitter?: AgentEventEmitter;
+  /**
+   * Event emitter for this agent. Always present — if the caller doesn't
+   * pass one, AgentCore allocates its own so the observable state below
+   * is populated regardless of who constructs the agent.
+   */
+  readonly eventEmitter: AgentEventEmitter;
   readonly hooks?: AgentHooks;
   readonly stats = new AgentStatistics();
 
+  // Observable state lives on Core (not a wrapper) so headless and
+  // background agents can be observed with the same accessors as
+  // interactive ones. Populated by listeners set up in the constructor.
+  private readonly messages: AgentMessage[] = [];
+  private readonly pendingApprovals = new Map<
+    string,
+    ToolCallConfirmationDetails
+  >();
+  private readonly liveOutputs = new Map<string, ToolResultDisplay>();
+  private readonly shellPids = new Map<string, number>();
+
   /**
    * Legacy execution stats maintained for aggregate tracking.
    */
@@ -207,8 +245,9 @@ export class AgentCore {
     this.modelConfig = modelConfig;
     this.runConfig = runConfig;
     this.toolConfig = toolConfig;
-    this.eventEmitter = eventEmitter;
+    this.eventEmitter = eventEmitter ?? new AgentEventEmitter();
     this.hooks = hooks;
+    this.setupStateListeners();
   }
 
   // ─── Chat Creation ────────────────────────────────────────
@@ -567,6 +606,30 @@ export class AgentCore {
           currentResponseId,
           wasOutputTruncated,
         );
+
+        const externalMsgs = options?.getExternalMessages?.() ?? [];
+        if (externalMsgs.length > 0) {
+          // Append to the tool-response user message so external input rides
+          // alongside the tool results the model is about to see.
+          // processFunctionCalls always returns exactly one user-role entry.
+          const last = currentMessages[currentMessages.length - 1];
+          last.parts!.push(
+            ...externalMsgs.map((text) => ({
+              text: `\n${EXTERNAL_MESSAGE_PREFIX} ${text}`,
+            })),
+          );
+          // Emit one event per injection so observers (e.g. the JSONL
+          // transcript writer) can persist each external message as a
+          // user-role record. The framing prefix is stripped — the prefix
+          // is a model-facing detail, not part of the original message.
+          for (const text of externalMsgs) {
+            this.eventEmitter?.emit(AgentEventType.EXTERNAL_MESSAGE, {
+              subagentId: this.subagentId,
+              text,
+              timestamp: Date.now(),
+            });
+          }
+        }
       } else {
         // No tool calls — treat this as the model's final answer.
         if (roundText && roundText.trim().length > 0) {
@@ -957,9 +1020,67 @@ export class AgentCore {
     return [{ role: 'user', parts: toolResponseParts }];
   }
 
+  // ─── Observable state accessors ────────────────────────────
+
+  getMessages(): readonly AgentMessage[] {
+    return this.messages;
+  }
+
+  /**
+   * Tool calls currently awaiting user approval. Mutated by
+   * AgentInteractive's TOOL_WAITING_APPROVAL handler; headless agents
+   * never populate this because they run with
+   * `getShouldAvoidPermissionPrompts === true`.
+   */
+  getPendingApprovals(): ReadonlyMap<string, ToolCallConfirmationDetails> {
+    return this.pendingApprovals;
+  }
+
+  getLiveOutputs(): ReadonlyMap<string, ToolResultDisplay> {
+    return this.liveOutputs;
+  }
+
+  getShellPids(): ReadonlyMap<string, number> {
+    return this.shellPids;
+  }
+
+  pushMessage(
+    role: AgentMessage['role'],
+    content: string,
+    options?: { thought?: boolean; metadata?: Record<string, unknown> },
+  ): void {
+    const message: AgentMessage = {
+      role,
+      content,
+      timestamp: Date.now(),
+    };
+    if (options?.thought) {
+      message.thought = true;
+    }
+    if (options?.metadata) {
+      message.metadata = options.metadata;
+    }
+    this.messages.push(message);
+  }
+
+  setPendingApproval(
+    callId: string,
+    details: ToolCallConfirmationDetails,
+  ): void {
+    this.pendingApprovals.set(callId, details);
+  }
+
+  deletePendingApproval(callId: string): void {
+    this.pendingApprovals.delete(callId);
+  }
+
+  clearPendingApprovals(): void {
+    this.pendingApprovals.clear();
+  }
+
   // ─── Stats & Events ───────────────────────────────────────
 
-  getEventEmitter(): AgentEventEmitter | undefined {
+  getEventEmitter(): AgentEventEmitter {
     return this.eventEmitter;
   }
 
@@ -1072,6 +1193,81 @@ export class AgentCore {
 
   // ─── Private Helpers ──────────────────────────────────────
 
+  /**
+   * TOOL_WAITING_APPROVAL is deliberately NOT listened to here because
+   * the correct response depends on whether the consumer is interactive
+   * (needs to wrap onConfirm with cancel-round behavior) or headless
+   * (approvals never fire). AgentInteractive owns that listener and
+   * writes into `pendingApprovals` via the public mutator API.
+   */
+  private setupStateListeners(): void {
+    const emitter = this.eventEmitter;
+
+    emitter.on(AgentEventType.ROUND_TEXT, (event: AgentRoundTextEvent) => {
+      if (event.thoughtText) {
+        this.pushMessage('assistant', event.thoughtText, { thought: true });
+      }
+      if (event.text) {
+        this.pushMessage('assistant', event.text);
+      }
+    });
+
+    emitter.on(AgentEventType.TOOL_CALL, (event: AgentToolCallEvent) => {
+      this.pushMessage('tool_call', `Tool call: ${event.name}`, {
+        metadata: {
+          callId: event.callId,
+          toolName: event.name,
+          args: event.args,
+          description: event.description,
+          renderOutputAsMarkdown: event.isOutputMarkdown,
+          round: event.round,
+        },
+      });
+    });
+
+    emitter.on(
+      AgentEventType.TOOL_OUTPUT_UPDATE,
+      (event: AgentToolOutputUpdateEvent) => {
+        this.liveOutputs.set(event.callId, event.outputChunk);
+        if (event.pid !== undefined) {
+          this.shellPids.set(event.callId, event.pid);
+        }
+      },
+    );
+
+    emitter.on(AgentEventType.TOOL_RESULT, (event: AgentToolResultEvent) => {
+      this.liveOutputs.delete(event.callId);
+      this.shellPids.delete(event.callId);
+      this.pendingApprovals.delete(event.callId);
+
+      const statusText = event.success ? 'succeeded' : 'failed';
+      const summary = event.error
+        ? `Tool ${event.name} ${statusText}: ${event.error}`
+        : `Tool ${event.name} ${statusText}`;
+      this.pushMessage('tool_result', summary, {
+        metadata: {
+          callId: event.callId,
+          toolName: event.name,
+          success: event.success,
+          resultDisplay: event.resultDisplay,
+          outputFile: event.outputFile,
+          round: event.round,
+        },
+      });
+    });
+
+    // Mirror send_message injections into the observable message stream so
+    // the TUI detail dialog shows parent→child messages alongside what the
+    // JSONL transcript records. The framing prefix is stripped — that's a
+    // model-facing detail, not what the user wants to see in the dialog.
+    emitter.on(
+      AgentEventType.EXTERNAL_MESSAGE,
+      (event: AgentExternalMessageEvent) => {
+        this.pushMessage('user', event.text);
+      },
+    );
+  }
+
   /**
    * Builds the system prompt with template substitution and optional
    * non-interactive instructions suffix.
diff --git a/packages/core/src/agents/runtime/agent-events.ts b/packages/core/src/agents/runtime/agent-events.ts
index e6d1c2231..0eeb0ed40 100644
--- a/packages/core/src/agents/runtime/agent-events.ts
+++ b/packages/core/src/agents/runtime/agent-events.ts
@@ -35,6 +35,7 @@ export type AgentEvent =
   | 'tool_output_update'
   | 'tool_waiting_approval'
   | 'usage_metadata'
+  | 'external_message'
   | 'finish'
   | 'error'
   | 'status_change';
@@ -51,6 +52,8 @@ export enum AgentEventType {
   TOOL_OUTPUT_UPDATE = 'tool_output_update',
   TOOL_WAITING_APPROVAL = 'tool_waiting_approval',
   USAGE_METADATA = 'usage_metadata',
+  /** External user message injected mid-run (e.g. via send_message). */
+  EXTERNAL_MESSAGE = 'external_message',
   FINISH = 'finish',
   ERROR = 'error',
   STATUS_CHANGE = 'status_change',
@@ -159,6 +162,13 @@ export interface AgentApprovalRequestEvent {
   timestamp: number;
 }
 
+export interface AgentExternalMessageEvent {
+  subagentId: string;
+  /** Raw message text (without any framing prefix). */
+  text: string;
+  timestamp: number;
+}
+
 export interface AgentFinishEvent {
   subagentId: string;
   terminateReason: string;
@@ -204,6 +214,7 @@ export interface AgentEventMap {
   [AgentEventType.TOOL_OUTPUT_UPDATE]: AgentToolOutputUpdateEvent;
   [AgentEventType.TOOL_WAITING_APPROVAL]: AgentApprovalRequestEvent;
   [AgentEventType.USAGE_METADATA]: AgentUsageEvent;
+  [AgentEventType.EXTERNAL_MESSAGE]: AgentExternalMessageEvent;
   [AgentEventType.FINISH]: AgentFinishEvent;
   [AgentEventType.ERROR]: AgentErrorEvent;
   [AgentEventType.STATUS_CHANGE]: AgentStatusChangeEvent;
diff --git a/packages/core/src/agents/runtime/agent-headless.ts b/packages/core/src/agents/runtime/agent-headless.ts
index bba61038c..66d7a2da3 100644
--- a/packages/core/src/agents/runtime/agent-headless.ts
+++ b/packages/core/src/agents/runtime/agent-headless.ts
@@ -136,6 +136,7 @@ export class AgentHeadless {
   private readonly core: AgentCore;
   private finalText: string = '';
   private terminateMode: AgentTerminateMode = AgentTerminateMode.ERROR;
+  private externalMessageProvider?: () => string[];
 
   private constructor(core: AgentCore) {
     this.core = core;
@@ -193,6 +194,16 @@ export class AgentHeadless {
     context: ContextState,
     externalSignal?: AbortSignal,
   ): Promise<void> {
+    // Record the initial user turn in the observable message log before
+    // anything that can throw — createChat / prepareTools failures still
+    // get a transcript showing the task that was asked, which is what
+    // the background-agent detail view reads via AgentCore.getMessages().
+    // Mirrors AgentInteractive's run loop.
+    const initialTaskText = String(
+      (context.get('task_prompt') as string) ?? 'Get Started!',
+    );
+    this.core.pushMessage('user', initialTaskText);
+
     const chat = await this.core.createChat(context);
 
     if (!chat) {
@@ -214,9 +225,6 @@ export class AgentHeadless {
 
     const toolsList = await this.core.prepareTools();
 
-    const initialTaskText = String(
-      (context.get('task_prompt') as string) ?? 'Get Started!',
-    );
     const initialMessages = [
       { role: 'user' as const, parts: [{ text: initialTaskText }] },
     ];
@@ -254,6 +262,7 @@ export class AgentHeadless {
           maxTurns: this.core.runConfig.max_turns,
           maxTimeMinutes: this.core.runConfig.max_time_minutes,
           startTimeMs: startTime,
+          getExternalMessages: this.externalMessageProvider,
         },
       );
 
@@ -350,6 +359,14 @@ export class AgentHeadless {
     return this.terminateMode;
   }
 
+  /**
+   * Sets a callback that the reasoning loop calls between tool rounds
+   * to drain external messages (e.g. from SendMessage tool).
+   */
+  setExternalMessageProvider(provider: () => string[]): void {
+    this.externalMessageProvider = provider;
+  }
+
   get name(): string {
     return this.core.name;
   }
diff --git a/packages/core/src/agents/runtime/agent-interactive.test.ts b/packages/core/src/agents/runtime/agent-interactive.test.ts
index 5560b665f..a37836038 100644
--- a/packages/core/src/agents/runtime/agent-interactive.test.ts
+++ b/packages/core/src/agents/runtime/agent-interactive.test.ts
@@ -8,6 +8,12 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { AgentInteractive } from './agent-interactive.js';
 import type { AgentCore } from './agent-core.js';
 import { AgentEventEmitter, AgentEventType } from './agent-events.js';
+import type {
+  AgentRoundTextEvent,
+  AgentToolCallEvent,
+  AgentToolResultEvent,
+  AgentToolOutputUpdateEvent,
+} from './agent-events.js';
 import { ContextState } from './agent-headless.js';
 import type { AgentInteractiveConfig } from './agent-types.js';
 import { AgentStatus } from './agent-types.js';
@@ -31,6 +37,15 @@ function createMockCore(
     : overrides.chatValue !== undefined
       ? overrides.chatValue
       : createMockChat();
+
+  // Simulate the observable state that the real AgentCore now owns.
+  // AgentInteractive delegates its state accessors to these, so the mock
+  // needs to reflect mutations made via `pushMessage` / approval helpers.
+  const messages: Array<Record<string, unknown>> = [];
+  const pendingApprovals = new Map<string, unknown>();
+  const liveOutputs = new Map<string, unknown>();
+  const shellPids = new Map<string, number>();
+
   const core = {
     subagentId: 'test-agent-abc123',
     name: 'test-agent',
@@ -71,8 +86,95 @@ function createMockCore(
       outputTokens: 0,
       totalTokens: 0,
     }),
+    // Observable state surface (mirrors real AgentCore API).
+    getMessages: () => messages,
+    getPendingApprovals: () => pendingApprovals,
+    getLiveOutputs: () => liveOutputs,
+    getShellPids: () => shellPids,
+    pushMessage: (
+      role: string,
+      content: string,
+      options?: { thought?: boolean; metadata?: Record<string, unknown> },
+    ) => {
+      const message: Record<string, unknown> = {
+        role,
+        content,
+        timestamp: Date.now(),
+      };
+      if (options?.thought) message['thought'] = true;
+      if (options?.metadata) message['metadata'] = options.metadata;
+      messages.push(message);
+    },
+    setPendingApproval: (callId: string, details: unknown) =>
+      pendingApprovals.set(callId, details),
+    deletePendingApproval: (callId: string) => pendingApprovals.delete(callId),
+    clearPendingApprovals: () => pendingApprovals.clear(),
   } as unknown as AgentCore;
 
+  // Mirror AgentCore.setupStateListeners: events on the shared emitter
+  // populate the state containers above. The real AgentCore wires this in
+  // its constructor; the mock does it here so tests that drive behavior
+  // by emitting events observe the same resulting state.
+  emitter.on(AgentEventType.ROUND_TEXT, (event: AgentRoundTextEvent) => {
+    if (event.thoughtText) {
+      (core.pushMessage as (...args: unknown[]) => void)(
+        'assistant',
+        event.thoughtText,
+        { thought: true },
+      );
+    }
+    if (event.text) {
+      (core.pushMessage as (...args: unknown[]) => void)(
+        'assistant',
+        event.text,
+      );
+    }
+  });
+  emitter.on(AgentEventType.TOOL_CALL, (event: AgentToolCallEvent) => {
+    (core.pushMessage as (...args: unknown[]) => void)(
+      'tool_call',
+      `Tool call: ${event.name}`,
+      {
+        metadata: {
+          callId: event.callId,
+          toolName: event.name,
+          args: event.args,
+          description: event.description,
+          renderOutputAsMarkdown: event.isOutputMarkdown,
+          round: event.round,
+        },
+      },
+    );
+  });
+  emitter.on(
+    AgentEventType.TOOL_OUTPUT_UPDATE,
+    (event: AgentToolOutputUpdateEvent) => {
+      liveOutputs.set(event.callId, event.outputChunk);
+      if (event.pid !== undefined) {
+        shellPids.set(event.callId, event.pid);
+      }
+    },
+  );
+  emitter.on(AgentEventType.TOOL_RESULT, (event: AgentToolResultEvent) => {
+    liveOutputs.delete(event.callId);
+    shellPids.delete(event.callId);
+    pendingApprovals.delete(event.callId);
+    const statusText = event.success ? 'succeeded' : 'failed';
+    const summary = event.error
+      ? `Tool ${event.name} ${statusText}: ${event.error}`
+      : `Tool ${event.name} ${statusText}`;
+    (core.pushMessage as (...args: unknown[]) => void)('tool_result', summary, {
+      metadata: {
+        callId: event.callId,
+        toolName: event.name,
+        success: event.success,
+        resultDisplay: event.resultDisplay,
+        outputFile: event.outputFile,
+        round: event.round,
+      },
+    });
+  });
+
   return { core, emitter };
 }
 
diff --git a/packages/core/src/agents/runtime/agent-interactive.ts b/packages/core/src/agents/runtime/agent-interactive.ts
index a01d9edb1..b7fbba1df 100644
--- a/packages/core/src/agents/runtime/agent-interactive.ts
+++ b/packages/core/src/agents/runtime/agent-interactive.ts
@@ -14,11 +14,9 @@
 import { createDebugLogger } from '../../utils/debugLogger.js';
 import { type AgentEventEmitter, AgentEventType } from './agent-events.js';
 import type {
-  AgentRoundTextEvent,
-  AgentToolCallEvent,
-  AgentToolResultEvent,
-  AgentToolOutputUpdateEvent,
   AgentApprovalRequestEvent,
+  AgentToolOutputUpdateEvent,
+  AgentToolResultEvent,
 } from './agent-events.js';
 import type { AgentStatsSummary } from './agent-statistics.js';
 import type { AgentCore } from './agent-core.js';
@@ -54,7 +52,6 @@ export class AgentInteractive {
   readonly config: AgentInteractiveConfig;
   private readonly core: AgentCore;
   private readonly queue = new AsyncMessageQueue<string>();
-  private readonly messages: AgentMessage[] = [];
 
   private status: AgentStatus = AgentStatus.INITIALIZING;
   private error: string | undefined;
@@ -67,28 +64,11 @@ export class AgentInteractive {
   private processing = false;
   private roundCancelledByUser = false;
 
-  // Pending tool approval requests. Keyed by callId.
-  // Populated by TOOL_WAITING_APPROVAL, removed by TOOL_RESULT or when
-  // the user responds. The UI reads this to show confirmation dialogs.
-  private readonly pendingApprovals = new Map<
-    string,
-    ToolCallConfirmationDetails
-  >();
-
-  // Live streaming output for currently-executing tools. Keyed by callId.
-  // Populated by TOOL_OUTPUT_UPDATE (replaces previous), cleared on TOOL_RESULT.
-  // The UI reads this via getLiveOutputs() to show real-time stdout.
-  private readonly liveOutputs = new Map<string, ToolResultDisplay>();
-
-  // PTY PIDs for currently-executing shell tools. Keyed by callId.
-  // Populated by TOOL_OUTPUT_UPDATE when pid is present, cleared on TOOL_RESULT.
-  // The UI reads this via getShellPids() to enable interactive shell input.
-  private readonly shellPids = new Map<string, number>();
-
   // Wall-clock timestamp when each currently-executing tool transitioned into
   // the scheduler's `executing` state. Keyed by callId. First TOOL_OUTPUT_UPDATE
   // carrying executionStartTime wins; later events that re-carry it are ignored
-  // so the timer is stable.
+  // so the timer is stable. Lives on InteractiveAgent (not AgentCore) because
+  // it's only consumed by the interactive UI's elapsed-time indicator.
   private readonly executionStartTimes = new Map<string, number>();
 
   constructor(config: AgentInteractiveConfig, core: AgentCore) {
@@ -233,7 +213,7 @@ export class AgentInteractive {
   cancelCurrentRound(): void {
     this.roundCancelledByUser = true;
     this.roundAbortController?.abort();
-    this.pendingApprovals.clear();
+    this.core.clearPendingApprovals();
     this.addMessage('info', 'Agent round cancelled.', {
       metadata: { level: 'warning' },
     });
@@ -261,7 +241,7 @@ export class AgentInteractive {
   abort(): void {
     this.masterAbortController.abort();
     this.queue.drain();
-    this.pendingApprovals.clear();
+    this.core.clearPendingApprovals();
   }
 
   // ─── Message Queue ─────────────────────────────────────────
@@ -276,10 +256,10 @@ export class AgentInteractive {
     }
   }
 
-  // ─── State Accessors ───────────────────────────────────────
+  // ─── State Accessors (delegates to AgentCore) ──────────────
 
   getMessages(): readonly AgentMessage[] {
-    return this.messages;
+    return this.core.getMessages();
   }
 
   getStatus(): AgentStatus {
@@ -307,7 +287,7 @@ export class AgentInteractive {
     return this.core;
   }
 
-  getEventEmitter(): AgentEventEmitter | undefined {
+  getEventEmitter(): AgentEventEmitter {
     return this.core.getEventEmitter();
   }
 
@@ -317,7 +297,7 @@ export class AgentInteractive {
    * The UI reads this to render confirmation dialogs inside ToolGroupMessage.
    */
   getPendingApprovals(): ReadonlyMap<string, ToolCallConfirmationDetails> {
-    return this.pendingApprovals;
+    return this.core.getPendingApprovals();
   }
 
   /**
@@ -326,7 +306,7 @@ export class AgentInteractive {
    * Entries are cleared when TOOL_RESULT arrives for the call.
    */
   getLiveOutputs(): ReadonlyMap<string, ToolResultDisplay> {
-    return this.liveOutputs;
+    return this.core.getLiveOutputs();
   }
 
   /**
@@ -336,7 +316,7 @@ export class AgentInteractive {
    * interactive shell input via HistoryItemDisplay's activeShellPtyId prop.
    */
   getShellPids(): ReadonlyMap<string, number> {
-    return this.shellPids;
+    return this.core.getShellPids();
   }
 
   /**
@@ -394,53 +374,20 @@ export class AgentInteractive {
     content: string,
     options?: { thought?: boolean; metadata?: Record<string, unknown> },
   ): void {
-    const message: AgentMessage = {
-      role,
-      content,
-      timestamp: Date.now(),
-    };
-    if (options?.thought) {
-      message.thought = true;
-    }
-    if (options?.metadata) {
-      message.metadata = options.metadata;
-    }
-    this.messages.push(message);
+    this.core.pushMessage(role, content, options);
   }
 
+  /**
+   * Wraps TOOL_WAITING_APPROVAL's onConfirm so a Cancel outcome aborts
+   * the current round (headless agents bypass this path entirely).
+   * Core already owns the message / live-output / shell-PID listeners.
+   */
   private setupEventListeners(): void {
     const emitter = this.core.eventEmitter;
-    if (!emitter) return;
-
-    emitter.on(AgentEventType.ROUND_TEXT, (event: AgentRoundTextEvent) => {
-      if (event.thoughtText) {
-        this.addMessage('assistant', event.thoughtText, { thought: true });
-      }
-      if (event.text) {
-        this.addMessage('assistant', event.text);
-      }
-    });
-
-    emitter.on(AgentEventType.TOOL_CALL, (event: AgentToolCallEvent) => {
-      this.addMessage('tool_call', `Tool call: ${event.name}`, {
-        metadata: {
-          callId: event.callId,
-          toolName: event.name,
-          args: event.args,
-          description: event.description,
-          renderOutputAsMarkdown: event.isOutputMarkdown,
-          round: event.round,
-        },
-      });
-    });
 
     emitter.on(
       AgentEventType.TOOL_OUTPUT_UPDATE,
       (event: AgentToolOutputUpdateEvent) => {
-        this.liveOutputs.set(event.callId, event.outputChunk);
-        if (event.pid !== undefined) {
-          this.shellPids.set(event.callId, event.pid);
-        }
         if (
           event.executionStartTime !== undefined &&
           !this.executionStartTimes.has(event.callId)
@@ -451,25 +398,7 @@ export class AgentInteractive {
     );
 
     emitter.on(AgentEventType.TOOL_RESULT, (event: AgentToolResultEvent) => {
-      this.liveOutputs.delete(event.callId);
-      this.shellPids.delete(event.callId);
       this.executionStartTimes.delete(event.callId);
-      this.pendingApprovals.delete(event.callId);
-
-      const statusText = event.success ? 'succeeded' : 'failed';
-      const summary = event.error
-        ? `Tool ${event.name} ${statusText}: ${event.error}`
-        : `Tool ${event.name} ${statusText}`;
-      this.addMessage('tool_result', summary, {
-        metadata: {
-          callId: event.callId,
-          toolName: event.name,
-          success: event.success,
-          resultDisplay: event.resultDisplay,
-          outputFile: event.outputFile,
-          round: event.round,
-        },
-      });
     });
 
     emitter.on(
@@ -481,17 +410,17 @@ export class AgentInteractive {
             outcome: Parameters<ToolCallConfirmationDetails['onConfirm']>[0],
             payload?: Parameters<ToolCallConfirmationDetails['onConfirm']>[1],
           ) => {
-            this.pendingApprovals.delete(event.callId);
+            this.core.deletePendingApproval(event.callId);
             // Nudge the UI to re-render so the tool transitions visually
             // from Confirming → Executing without waiting for the first
             // real TOOL_OUTPUT_UPDATE from the tool's execution.
-            this.core.eventEmitter?.emit(AgentEventType.TOOL_OUTPUT_UPDATE, {
+            this.core.eventEmitter.emit(AgentEventType.TOOL_OUTPUT_UPDATE, {
               subagentId: this.core.subagentId,
               round: event.round,
               callId: event.callId,
               outputChunk: '',
               timestamp: Date.now(),
-            } as AgentToolOutputUpdateEvent);
+            });
             await event.respond(outcome, payload);
             // When the user denies a tool, cancel the round immediately
             // so the agent doesn't waste a turn "acknowledging" the denial.
@@ -501,7 +430,7 @@ export class AgentInteractive {
           },
         } as ToolCallConfirmationDetails;
 
-        this.pendingApprovals.set(event.callId, fullDetails);
+        this.core.setPendingApproval(event.callId, fullDetails);
       },
     );
   }
diff --git a/packages/core/src/config/config.test.ts b/packages/core/src/config/config.test.ts
index c3ce32493..873c403d8 100644
--- a/packages/core/src/config/config.test.ts
+++ b/packages/core/src/config/config.test.ts
@@ -531,7 +531,7 @@ describe('Server Config (config.ts)', () => {
       expect(vi.mocked(createContentGenerator)).toHaveBeenCalledTimes(1);
     });
 
-    it('should strip thoughts from history on model switch (#3304)', async () => {
+    it('should preserve thoughts from history on model switch', async () => {
       const config = new Config(baseParams);
 
       const mockContentConfig: ContentGeneratorConfig = {
@@ -567,7 +567,7 @@ describe('Server Config (config.ts)', () => {
 
       await config.switchModel(AuthType.QWEN_OAUTH, 'coder-model');
 
-      expect(stripSpy).toHaveBeenCalledTimes(1);
+      expect(stripSpy).not.toHaveBeenCalled();
     });
   });
 
diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts
index de4d151b1..52aa49394 100644
--- a/packages/core/src/config/config.ts
+++ b/packages/core/src/config/config.ts
@@ -61,6 +61,7 @@ import { PermissionManager } from '../permissions/permission-manager.js';
 import { SubagentManager } from '../subagents/subagent-manager.js';
 import type { SubagentConfig } from '../subagents/types.js';
 import { BackgroundTaskRegistry } from '../agents/background-tasks.js';
+import { BackgroundShellRegistry } from '../services/backgroundShellRegistry.js';
 import {
   DEFAULT_OTLP_ENDPOINT,
   DEFAULT_TELEMETRY_TARGET,
@@ -383,6 +384,7 @@ export interface ConfigParameters {
   sessionTokenLimit?: number;
   experimentalZedIntegration?: boolean;
   cronEnabled?: boolean;
+  emitToolUseSummaries?: boolean;
   listExtensions?: boolean;
   overrideExtensions?: string[];
   allowedMcpServers?: string[];
@@ -544,6 +546,7 @@ export class Config {
   private promptRegistry!: PromptRegistry;
   private subagentManager!: SubagentManager;
   private readonly backgroundTaskRegistry = new BackgroundTaskRegistry();
+  private readonly backgroundShellRegistry = new BackgroundShellRegistry();
   private extensionManager!: ExtensionManager;
   private skillManager: SkillManager | null = null;
   private permissionManager: PermissionManager | null = null;
@@ -631,6 +634,7 @@ export class Config {
   private readonly cliVersion?: string;
   private readonly experimentalZedIntegration: boolean = false;
   private readonly cronEnabled: boolean = false;
+  private readonly emitToolUseSummaries: boolean = true;
   private readonly chatRecordingEnabled: boolean;
   private readonly loadMemoryFromIncludeDirectories: boolean = false;
   private readonly importFormat: 'tree' | 'flat';
@@ -773,6 +777,7 @@ export class Config {
     this.experimentalZedIntegration =
       params.experimentalZedIntegration ?? false;
     this.cronEnabled = params.cronEnabled ?? false;
+    this.emitToolUseSummaries = params.emitToolUseSummaries ?? true;
     this.listExtensions = params.listExtensions ?? false;
     this.overrideExtensions = params.overrideExtensions;
     this.noBrowser = params.noBrowser ?? false;
@@ -1420,11 +1425,9 @@ export class Config {
       return;
     }
 
-    // Strip thinking blocks from conversation history on model switch.
-    // reasoning_content is a non-standard field that causes strict
-    // OpenAI-compatible providers to reject requests with 422 errors
-    // when thought parts from a previous model leak into the payload (#3304).
-    this.geminiClient.stripThoughtsFromHistory();
+    // Keep full history (including thought parts) on model switch.
+    // Some OpenAI-compatible reasoning models (e.g. DeepSeek) require
+    // reasoning_content to be preserved across turns.
 
     // Hot update path: only supported for qwen-oauth.
     // For other auth types we always refresh to recreate the ContentGenerator.
@@ -1451,6 +1454,7 @@ export class Config {
       this.contentGeneratorConfig.contextWindowSize = config.contextWindowSize;
       this.contentGeneratorConfig.enableCacheControl =
         config.enableCacheControl;
+      this.contentGeneratorConfig.splitToolMedia = config.splitToolMedia;
 
       if ('model' in sources) {
         this.contentGeneratorConfigSources['model'] = sources['model'];
@@ -1467,6 +1471,10 @@ export class Config {
         this.contentGeneratorConfigSources['contextWindowSize'] =
           sources['contextWindowSize'];
       }
+      if ('splitToolMedia' in sources) {
+        this.contentGeneratorConfigSources['splitToolMedia'] =
+          sources['splitToolMedia'];
+      }
       return;
     }
 
@@ -1604,6 +1612,7 @@ export class Config {
       }
 
       this.backgroundTaskRegistry.abortAll();
+      this.backgroundShellRegistry.abortAll();
 
       await this.cleanupArenaRuntime();
     } catch (error) {
@@ -1990,6 +1999,22 @@ export class Config {
     return this.cronEnabled;
   }
 
+  /**
+   * Whether the turn loop should fire a fast-model call after each tool batch
+   * to emit a `tool_use_summary` message. Mirrors Claude Code's
+   * `CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES` gate, but defaults to on so the
+   * compact-mode UI benefits without configuration.
+   *
+   * Env overrides (either direction): `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0`
+   * to force off, `=1` to force on.
+   */
+  getEmitToolUseSummaries(): boolean {
+    const env = process.env['QWEN_CODE_EMIT_TOOL_USE_SUMMARIES'];
+    if (env === '0' || env === 'false') return false;
+    if (env === '1' || env === 'true') return true;
+    return this.emitToolUseSummaries;
+  }
+
   getEnableRecursiveFileSearch(): boolean {
     return this.fileFiltering.enableRecursiveFileSearch;
   }
@@ -2467,6 +2492,10 @@ export class Config {
     return this.backgroundTaskRegistry;
   }
 
+  getBackgroundShellRegistry(): BackgroundShellRegistry {
+    return this.backgroundShellRegistry;
+  }
+
   /**
    * Whether interactive permission prompts should be auto-denied.
    * True for background agents that have no UI to show prompts.
@@ -2601,6 +2630,14 @@ export class Config {
       const { AgentTool } = await import('../tools/agent/agent.js');
       return new AgentTool(this);
     });
+    await registerLazy(ToolNames.TASK_STOP, async () => {
+      const { TaskStopTool } = await import('../tools/task-stop.js');
+      return new TaskStopTool(this);
+    });
+    await registerLazy(ToolNames.SEND_MESSAGE, async () => {
+      const { SendMessageTool } = await import('../tools/send-message.js');
+      return new SendMessageTool(this);
+    });
     await registerLazy(ToolNames.SKILL, async () => {
       const { SkillTool } = await import('../tools/skill.js');
       return new SkillTool(this);
diff --git a/packages/core/src/core/client.ts b/packages/core/src/core/client.ts
index 797f61190..f8961ff04 100644
--- a/packages/core/src/core/client.ts
+++ b/packages/core/src/core/client.ts
@@ -217,6 +217,11 @@ export class GeminiClient {
     this.forceFullIdeContext = true;
   }
 
+  truncateHistory(keepCount: number) {
+    this.getChat().truncateHistory(keepCount);
+    this.forceFullIdeContext = true;
+  }
+
   async setTools(): Promise<void> {
     if (!this.isInitialized()) {
       return;
diff --git a/packages/core/src/core/contentGenerator.ts b/packages/core/src/core/contentGenerator.ts
index 7b1614236..d9ec8b36f 100644
--- a/packages/core/src/core/contentGenerator.ts
+++ b/packages/core/src/core/contentGenerator.ts
@@ -116,6 +116,15 @@ export type ContentGeneratorConfig = {
   // Supported input modalities. Unsupported media types are replaced with text
   // placeholders. Leave undefined to use automatic detection from model name.
   modalities?: InputModalities;
+  // When true, media parts in MCP tool responses are split into a follow-up
+  // `role: "user"` message instead of being embedded inside the `role: "tool"`
+  // message. The OpenAI Chat Completions spec only permits string / text-part
+  // content on tool messages; strict OpenAI-compatible servers (notably
+  // LM Studio) reject anything else with HTTP 400 "Invalid 'messages' in
+  // payload". Enable this for any provider that strictly validates tool
+  // message content. Default: false (preserves prior behavior for permissive
+  // providers). See QwenLM/qwen-code#3616.
+  splitToolMedia?: boolean;
 };
 
 // Keep the public ContentGeneratorConfigSources API, but reuse the generic
diff --git a/packages/core/src/core/geminiChat.ts b/packages/core/src/core/geminiChat.ts
index ff76eb5c6..cf6e37761 100644
--- a/packages/core/src/core/geminiChat.ts
+++ b/packages/core/src/core/geminiChat.ts
@@ -788,6 +788,10 @@ export class GeminiChat {
     this.history = history;
   }
 
+  truncateHistory(keepCount: number): void {
+    this.history = this.history.slice(0, keepCount);
+  }
+
   stripThoughtsFromHistory(): void {
     this.history = this.history
       .map((content) => {
diff --git a/packages/core/src/core/openaiContentGenerator/converter.test.ts b/packages/core/src/core/openaiContentGenerator/converter.test.ts
index f9bc0666f..8e4b52e01 100644
--- a/packages/core/src/core/openaiContentGenerator/converter.test.ts
+++ b/packages/core/src/core/openaiContentGenerator/converter.test.ts
@@ -382,6 +382,422 @@ describe('OpenAIContentConverter', () => {
       expect(userMessage).toBeUndefined();
     });
 
+    it('should split tool-result media into a follow-up user message when splitToolMedia is enabled (issue #3616)', () => {
+      // Same shape as the embedded-image test above, but with the strict
+      // OpenAI-compat opt-in flag set. The tool message must stay
+      // spec-compliant (string / text-part content only) and the image must
+      // arrive in a follow-up user message.
+      const request: GenerateContentParameters = {
+        model: 'models/test',
+        contents: [
+          {
+            role: 'model',
+            parts: [
+              {
+                functionCall: {
+                  id: 'call_1',
+                  name: 'Read',
+                  args: {},
+                },
+              },
+            ],
+          },
+          {
+            role: 'user',
+            parts: [
+              {
+                functionResponse: {
+                  id: 'call_1',
+                  name: 'Read',
+                  response: { output: 'Image content' },
+                  parts: [
+                    {
+                      inlineData: {
+                        mimeType: 'image/png',
+                        data: 'base64encodedimagedata',
+                      },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      const strictContext: RequestContext = {
+        ...requestContext,
+        splitToolMedia: true,
+      };
+      const messages = converter.convertGeminiRequestToOpenAI(
+        request,
+        strictContext,
+      );
+
+      const toolMessage = messages.find((m) => m.role === 'tool');
+      expect(toolMessage).toBeDefined();
+      // Tool message content is a plain string (or text-part array) — no media
+      expect(typeof toolMessage?.content === 'string').toBe(true);
+      expect(toolMessage?.content).toContain('Image content');
+
+      // The image lives in a follow-up user message
+      const userMessage = messages.find((m) => m.role === 'user');
+      expect(userMessage).toBeDefined();
+      const userContent = userMessage?.content as Array<{
+        type: string;
+        text?: string;
+        image_url?: { url: string };
+      }>;
+      expect(Array.isArray(userContent)).toBe(true);
+      const imagePart = userContent.find((p) => p.type === 'image_url');
+      expect(imagePart?.image_url?.url).toBe(
+        'data:image/png;base64,base64encodedimagedata',
+      );
+    });
+
+    it('should keep all tool messages contiguous and merge split media into a single follow-up user message for parallel tool calls (issue #3616)', () => {
+      // Two assistant tool calls in parallel. Both responses come back in the
+      // same `user` content as separate functionResponse parts. The first
+      // returns an image; the second returns text only. OpenAI Chat
+      // Completions requires every `role: "tool"` response to appear
+      // contiguously before any non-tool message, so the synthesised user
+      // message carrying split media MUST come after BOTH tool messages,
+      // not interleaved between them.
+      const request: GenerateContentParameters = {
+        model: 'models/test',
+        contents: [
+          {
+            role: 'model',
+            parts: [
+              {
+                functionCall: {
+                  id: 'call_screenshot',
+                  name: 'browser_take_screenshot',
+                  args: {},
+                },
+              },
+              {
+                functionCall: {
+                  id: 'call_console',
+                  name: 'browser_console_messages',
+                  args: {},
+                },
+              },
+            ],
+          },
+          {
+            role: 'user',
+            parts: [
+              {
+                functionResponse: {
+                  id: 'call_screenshot',
+                  name: 'browser_take_screenshot',
+                  response: { output: 'Captured screenshot' },
+                  parts: [
+                    {
+                      inlineData: {
+                        mimeType: 'image/png',
+                        data: 'shotbase64',
+                      },
+                    },
+                  ],
+                },
+              },
+              {
+                functionResponse: {
+                  id: 'call_console',
+                  name: 'browser_console_messages',
+                  response: { output: 'no console messages' },
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      const strictContext: RequestContext = {
+        ...requestContext,
+        splitToolMedia: true,
+      };
+      const messages = converter.convertGeminiRequestToOpenAI(
+        request,
+        strictContext,
+      );
+
+      // Locate the assistant turn (with the two tool calls) and assert that
+      // the next two messages are both `tool`, contiguously, before any
+      // user message.
+      const assistantIdx = messages.findIndex((m) => m.role === 'assistant');
+      expect(assistantIdx).toBeGreaterThanOrEqual(0);
+      expect(messages[assistantIdx + 1]?.role).toBe('tool');
+      expect(messages[assistantIdx + 2]?.role).toBe('tool');
+      expect(messages[assistantIdx + 3]?.role).toBe('user');
+
+      // Both tool messages have spec-compliant content (string OR array of
+      // text-typed parts only — no image_url / input_audio / video_url /
+      // file parts allowed by OpenAI on tool messages).
+      const isSpecCompliantToolContent = (content: unknown): boolean => {
+        if (typeof content === 'string') return true;
+        if (!Array.isArray(content)) return false;
+        return (content as Array<{ type: string }>).every(
+          (p) => p.type === 'text',
+        );
+      };
+      expect(
+        isSpecCompliantToolContent(
+          (messages[assistantIdx + 1] as { content: unknown }).content,
+        ),
+      ).toBe(true);
+      expect(
+        isSpecCompliantToolContent(
+          (messages[assistantIdx + 2] as { content: unknown }).content,
+        ),
+      ).toBe(true);
+
+      // Exactly one synthesised user message exists, and it carries the
+      // single image from the first tool response.
+      const userMessages = messages.filter((m) => m.role === 'user');
+      expect(userMessages).toHaveLength(1);
+      const userContent = userMessages[0].content as Array<{
+        type: string;
+        text?: string;
+        image_url?: { url: string };
+      }>;
+      const imageParts = userContent.filter((p) => p.type === 'image_url');
+      expect(imageParts).toHaveLength(1);
+      expect(imageParts[0].image_url?.url).toBe(
+        'data:image/png;base64,shotbase64',
+      );
+    });
+
+    it('should merge media from multiple media-bearing parallel tool responses into one follow-up user message (issue #3616)', () => {
+      // Both tool responses return images. The accumulator must combine them
+      // into a single user message — we should NOT see two separate user
+      // messages (which would still violate the contiguity rule because the
+      // first user message would split the tool messages apart).
+      const request: GenerateContentParameters = {
+        model: 'models/test',
+        contents: [
+          {
+            role: 'model',
+            parts: [
+              {
+                functionCall: { id: 'call_a', name: 'shot_a', args: {} },
+              },
+              {
+                functionCall: { id: 'call_b', name: 'shot_b', args: {} },
+              },
+            ],
+          },
+          {
+            role: 'user',
+            parts: [
+              {
+                functionResponse: {
+                  id: 'call_a',
+                  name: 'shot_a',
+                  response: { output: 'A' },
+                  parts: [
+                    { inlineData: { mimeType: 'image/png', data: 'aaa' } },
+                  ],
+                },
+              },
+              {
+                functionResponse: {
+                  id: 'call_b',
+                  name: 'shot_b',
+                  response: { output: 'B' },
+                  parts: [
+                    { inlineData: { mimeType: 'image/png', data: 'bbb' } },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      const strictContext: RequestContext = {
+        ...requestContext,
+        splitToolMedia: true,
+      };
+      const messages = converter.convertGeminiRequestToOpenAI(
+        request,
+        strictContext,
+      );
+
+      const toolMessages = messages.filter((m) => m.role === 'tool');
+      const userMessages = messages.filter((m) => m.role === 'user');
+      expect(toolMessages).toHaveLength(2);
+      expect(userMessages).toHaveLength(1);
+
+      const userContent = userMessages[0].content as Array<{
+        type: string;
+        text?: string;
+        image_url?: { url: string };
+      }>;
+      const imageUrls = userContent
+        .filter((p) => p.type === 'image_url')
+        .map((p) => p.image_url?.url);
+      expect(imageUrls).toEqual([
+        'data:image/png;base64,aaa',
+        'data:image/png;base64,bbb',
+      ]);
+    });
+
+    it('should not synthesise a follow-up user message when splitToolMedia is enabled but the response has no media (issue #3616)', () => {
+      // Regression guard: when the flag is on but a tool response is text-only,
+      // the synthesis path must not emit any user message. Without this guard,
+      // a future refactor that always emits the follow-up could regress silently.
+      const request: GenerateContentParameters = {
+        model: 'models/test',
+        contents: [
+          {
+            role: 'model',
+            parts: [{ functionCall: { id: 'c', name: 'echo', args: {} } }],
+          },
+          {
+            role: 'user',
+            parts: [
+              {
+                functionResponse: {
+                  id: 'c',
+                  name: 'echo',
+                  response: { output: 'plain text result' },
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      const strictContext: RequestContext = {
+        ...requestContext,
+        splitToolMedia: true,
+      };
+      const messages = converter.convertGeminiRequestToOpenAI(
+        request,
+        strictContext,
+      );
+
+      const toolMessages = messages.filter((m) => m.role === 'tool');
+      const userMessages = messages.filter((m) => m.role === 'user');
+      expect(toolMessages).toHaveLength(1);
+      expect(userMessages).toHaveLength(0);
+    });
+
+    it('should fall back to a placeholder string when the tool response is media-only (issue #3616)', () => {
+      // When extractFunctionResponseContent returns empty AND parts contain
+      // only media, the tool message must end up with the placeholder string
+      // rather than an empty array (which would be invalid spec).
+      const request: GenerateContentParameters = {
+        model: 'models/test',
+        contents: [
+          {
+            role: 'model',
+            parts: [{ functionCall: { id: 'c', name: 'shot', args: {} } }],
+          },
+          {
+            role: 'user',
+            parts: [
+              {
+                functionResponse: {
+                  id: 'c',
+                  name: 'shot',
+                  // null response triggers extractFunctionResponseContent
+                  // to return "" — the empty-text branch we want to cover.
+                  response: null as unknown as Record<string, unknown>,
+                  parts: [
+                    { inlineData: { mimeType: 'image/png', data: 'xxx' } },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      const strictContext: RequestContext = {
+        ...requestContext,
+        splitToolMedia: true,
+      };
+      const messages = converter.convertGeminiRequestToOpenAI(
+        request,
+        strictContext,
+      );
+
+      const toolMessage = messages.find((m) => m.role === 'tool');
+      expect(toolMessage).toBeDefined();
+      expect(toolMessage?.content).toBe(
+        '[media attached in following user message]',
+      );
+      const userMessage = messages.find((m) => m.role === 'user');
+      const userContent = userMessage?.content as Array<{
+        type: string;
+        image_url?: { url: string };
+      }>;
+      const img = userContent.find((p) => p.type === 'image_url');
+      expect(img?.image_url?.url).toBe('data:image/png;base64,xxx');
+    });
+
+    it('should preserve prior embedded-media behavior when splitToolMedia is false (default) on parallel tool calls (issue #3616)', () => {
+      // Same input as the parallel-tool-calls split test, but with the flag
+      // off. Asserts that the opt-in is actually opt-in: media stays embedded
+      // in the tool message and no follow-up user message is synthesised.
+      const request: GenerateContentParameters = {
+        model: 'models/test',
+        contents: [
+          {
+            role: 'model',
+            parts: [
+              { functionCall: { id: 'c1', name: 's1', args: {} } },
+              { functionCall: { id: 'c2', name: 's2', args: {} } },
+            ],
+          },
+          {
+            role: 'user',
+            parts: [
+              {
+                functionResponse: {
+                  id: 'c1',
+                  name: 's1',
+                  response: { output: 'r1' },
+                  parts: [
+                    { inlineData: { mimeType: 'image/png', data: 'aaa' } },
+                  ],
+                },
+              },
+              {
+                functionResponse: {
+                  id: 'c2',
+                  name: 's2',
+                  response: { output: 'r2' },
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      // requestContext default has splitToolMedia undefined / false
+      const messages = converter.convertGeminiRequestToOpenAI(
+        request,
+        requestContext,
+      );
+
+      const toolMessages = messages.filter((m) => m.role === 'tool');
+      const userMessages = messages.filter((m) => m.role === 'user');
+      expect(toolMessages).toHaveLength(2);
+      expect(userMessages).toHaveLength(0);
+      // First tool message should still carry the embedded image
+      const firstToolContent = toolMessages[0].content as Array<{
+        type: string;
+        image_url?: { url: string };
+      }>;
+      const img = firstToolContent.find((p) => p.type === 'image_url');
+      expect(img?.image_url?.url).toBe('data:image/png;base64,aaa');
+    });
+
     it('should convert function responses with fileData to tool message with embedded image_url', () => {
       const request: GenerateContentParameters = {
         model: 'models/test',
diff --git a/packages/core/src/core/openaiContentGenerator/converter.ts b/packages/core/src/core/openaiContentGenerator/converter.ts
index 035c7bd9a..b7796f249 100644
--- a/packages/core/src/core/openaiContentGenerator/converter.ts
+++ b/packages/core/src/core/openaiContentGenerator/converter.ts
@@ -400,6 +400,14 @@ function processContent(
   const reasoningParts: string[] = [];
   const toolCalls: OpenAI.Chat.ChatCompletionMessageToolCall[] = [];
   let toolCallIndex = 0;
+  // When `splitToolMedia` is enabled, media stripped from tool messages is
+  // accumulated here and emitted as a single follow-up user message after
+  // ALL tool messages in this group have been pushed. OpenAI Chat
+  // Completions requires every `role: "tool"` response for a given assistant
+  // turn to appear contiguously before any non-tool message; emitting the
+  // user message inline (after each tool message) would interleave and
+  // break that contract when multiple parallel tool calls return media.
+  const accumulatedSplitMedia: OpenAIContentPart[] = [];
 
   for (const part of parts) {
     if (typeof part === 'string') {
@@ -441,11 +449,65 @@ function processContent(
         requestContext,
       );
       if (toolMessage) {
+        // Opt-in only (ContentGeneratorConfig.splitToolMedia). OpenAI spec
+        // only permits string / text-part content on `role: "tool"` messages.
+        // Strict OpenAI-compatible servers (e.g. LM Studio) reject tool
+        // messages containing image_url / input_audio / video_url / file
+        // parts with HTTP 400 "Invalid 'messages' in payload". When the flag
+        // is set, strip non-text media from this tool message and accumulate
+        // it; the combined media is emitted as a single follow-up user
+        // message after the parts loop completes — preserving the
+        // "all tool responses contiguous" requirement for parallel tool
+        // calls. Default (flag false) preserves prior behavior: media is
+        // embedded in the tool message and permissive providers continue
+        // to receive it that way. See #3616.
+        if (
+          requestContext.splitToolMedia &&
+          Array.isArray(toolMessage.content)
+        ) {
+          const mediaParts: OpenAIContentPart[] = [];
+          const textParts: OpenAI.Chat.ChatCompletionContentPartText[] = [];
+          for (const cp of toolMessage.content as OpenAIContentPart[]) {
+            if (
+              cp &&
+              (cp.type === 'image_url' ||
+                cp.type === 'input_audio' ||
+                cp.type === 'video_url' ||
+                cp.type === 'file')
+            ) {
+              mediaParts.push(cp);
+            } else if (cp && cp.type === 'text') {
+              textParts.push(cp);
+            }
+          }
+          if (mediaParts.length > 0) {
+            const textOnly = textParts.map((p) => p.text).join('\n');
+            toolMessage.content =
+              textOnly || '[media attached in following user message]';
+            accumulatedSplitMedia.push(...mediaParts);
+          }
+        }
         messages.push(toolMessage);
       }
     }
   }
 
+  // Emit one combined user message containing all media stripped from the
+  // tool messages in this group. Runs after the parts loop so all tool
+  // messages remain contiguous (OpenAI requirement for parallel tool calls).
+  if (accumulatedSplitMedia.length > 0) {
+    messages.push({
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: '(attached media from previous tool call)',
+        },
+        ...accumulatedSplitMedia,
+      ] as unknown as OpenAI.Chat.ChatCompletionContentPartText[],
+    });
+  }
+
   if (role === 'assistant') {
     if (
       contentParts.length === 0 &&
diff --git a/packages/core/src/core/openaiContentGenerator/pipeline.ts b/packages/core/src/core/openaiContentGenerator/pipeline.ts
index 728968f9a..2f1731079 100644
--- a/packages/core/src/core/openaiContentGenerator/pipeline.ts
+++ b/packages/core/src/core/openaiContentGenerator/pipeline.ts
@@ -521,6 +521,7 @@ export class ContentGenerationPipeline {
       model: effectiveModel,
       modalities: this.contentGeneratorConfig.modalities ?? {},
       startTime: Date.now(),
+      splitToolMedia: this.contentGeneratorConfig.splitToolMedia ?? false,
       ...(toolCallParser ? { toolCallParser } : {}),
     };
   }
diff --git a/packages/core/src/core/openaiContentGenerator/provider/deepseek.test.ts b/packages/core/src/core/openaiContentGenerator/provider/deepseek.test.ts
index f4ced4c45..6570e4aec 100644
--- a/packages/core/src/core/openaiContentGenerator/provider/deepseek.test.ts
+++ b/packages/core/src/core/openaiContentGenerator/provider/deepseek.test.ts
@@ -49,16 +49,41 @@ describe('DeepSeekOpenAICompatibleProvider', () => {
       expect(result).toBe(true);
     });
 
-    it('returns false for non deepseek baseUrl', () => {
+    it('returns false when neither baseUrl nor model match deepseek', () => {
       const config = {
         ...mockContentGeneratorConfig,
         baseUrl: 'https://api.example.com/v1',
+        model: 'gpt-4o',
       } as ContentGeneratorConfig;
 
       const result =
         DeepSeekOpenAICompatibleProvider.isDeepSeekProvider(config);
       expect(result).toBe(false);
     });
+
+    it('returns true for deepseek model on a non-deepseek baseUrl (e.g. sglang) — issue #3613', () => {
+      const config = {
+        ...mockContentGeneratorConfig,
+        baseUrl: 'https://my-sglang.example.com:8000/v1',
+        model: 'deepseek-v4-pro',
+      } as ContentGeneratorConfig;
+
+      const result =
+        DeepSeekOpenAICompatibleProvider.isDeepSeekProvider(config);
+      expect(result).toBe(true);
+    });
+
+    it('matches model name case-insensitively', () => {
+      const config = {
+        ...mockContentGeneratorConfig,
+        baseUrl: 'https://my-vllm.example.com/v1',
+        model: 'DeepSeek-R1',
+      } as ContentGeneratorConfig;
+
+      const result =
+        DeepSeekOpenAICompatibleProvider.isDeepSeekProvider(config);
+      expect(result).toBe(true);
+    });
   });
 
   describe('buildRequest', () => {
diff --git a/packages/core/src/core/openaiContentGenerator/provider/deepseek.ts b/packages/core/src/core/openaiContentGenerator/provider/deepseek.ts
index e34dc724d..5c8fc1212 100644
--- a/packages/core/src/core/openaiContentGenerator/provider/deepseek.ts
+++ b/packages/core/src/core/openaiContentGenerator/provider/deepseek.ts
@@ -22,8 +22,17 @@ export class DeepSeekOpenAICompatibleProvider extends DefaultOpenAICompatiblePro
     contentGeneratorConfig: ContentGeneratorConfig,
   ): boolean {
     const baseUrl = contentGeneratorConfig.baseUrl ?? '';
+    if (baseUrl.toLowerCase().includes('api.deepseek.com')) {
+      return true;
+    }
 
-    return baseUrl.toLowerCase().includes('api.deepseek.com');
+    // DeepSeek models served behind any OpenAI-compatible endpoint (sglang,
+    // vllm, ollama, etc.) share the same content-format constraint that the
+    // official api.deepseek.com endpoint has. Detect them by model name so
+    // the buildRequest flattening below kicks in.
+    // See https://github.com/QwenLM/qwen-code/issues/3613
+    const model = contentGeneratorConfig.model ?? '';
+    return model.toLowerCase().includes('deepseek');
   }
 
   /**
diff --git a/packages/core/src/core/openaiContentGenerator/types.ts b/packages/core/src/core/openaiContentGenerator/types.ts
index 630612172..0c481c7ff 100644
--- a/packages/core/src/core/openaiContentGenerator/types.ts
+++ b/packages/core/src/core/openaiContentGenerator/types.ts
@@ -18,6 +18,10 @@ export interface RequestContext {
   modalities: InputModalities;
   startTime: number;
   toolCallParser?: StreamingToolCallParser;
+  // When true, media parts in tool-result messages are split into a follow-up
+  // user message for strict OpenAI-compat servers. See ContentGeneratorConfig
+  // for details.
+  splitToolMedia?: boolean;
 }
 
 export interface ErrorHandler {
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 80210ee03..88e356265 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -147,6 +147,8 @@ export * from './services/sessionService.js';
 export * from './services/sessionTitle.js';
 export { stripTerminalControlSequences } from './utils/terminalSafe.js';
 export * from './services/shellExecutionService.js';
+export * from './services/backgroundShellRegistry.js';
+export * from './services/toolUseSummary.js';
 export * from './utils/bareMode.js';
 
 // ============================================================================
@@ -298,6 +300,10 @@ export * from './utils/request-tokenizer/supportedImageFormats.js';
 export { TextTokenizer } from './utils/request-tokenizer/textTokenizer.js';
 export * from './utils/retry.js';
 export * from './utils/ripgrepUtils.js';
+export {
+  detectRuntime,
+  getOrCreateSharedDispatcher,
+} from './utils/runtimeFetchOptions.js';
 export * from './utils/schemaValidator.js';
 export * from './utils/shell-utils.js';
 export * from './utils/subagentGenerator.js';
diff --git a/packages/core/src/models/constants.ts b/packages/core/src/models/constants.ts
index 1ad1f023a..101bf4da5 100644
--- a/packages/core/src/models/constants.ts
+++ b/packages/core/src/models/constants.ts
@@ -30,6 +30,7 @@ export const MODEL_GENERATION_CONFIG_FIELDS = [
   'customHeaders',
   'extra_body',
   'modalities',
+  'splitToolMedia',
 ] as const satisfies ReadonlyArray<keyof ContentGeneratorConfig>;
 
 /**
diff --git a/packages/core/src/models/modelConfigResolver.test.ts b/packages/core/src/models/modelConfigResolver.test.ts
index 978949b2c..4aeb8fbee 100644
--- a/packages/core/src/models/modelConfigResolver.test.ts
+++ b/packages/core/src/models/modelConfigResolver.test.ts
@@ -185,6 +185,114 @@ describe('modelConfigResolver', () => {
         expect(result.warnings).toHaveLength(1);
         expect(result.warnings[0]).toContain('unsupported-model');
       });
+
+      it('QWEN_CODE_API_TIMEOUT_MS applies in Qwen OAuth path', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.QWEN_OAUTH,
+          cli: {},
+          settings: {},
+          env: {
+            QWEN_CODE_API_TIMEOUT_MS: '45000',
+          },
+        });
+
+        expect(result.config.timeout).toBe(45000);
+        expect(result.sources['timeout']).toBeDefined();
+        expect(result.sources['timeout'].kind).toBe('env');
+        expect(result.sources['timeout'].envKey).toBe(
+          'QWEN_CODE_API_TIMEOUT_MS',
+        );
+        expect(result.config.model).toBe(DEFAULT_QWEN_MODEL);
+      });
+
+      it('modelProvider timeout takes precedence over QWEN_CODE_API_TIMEOUT_MS in OAuth', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.QWEN_OAUTH,
+          cli: {},
+          settings: {},
+          env: {
+            QWEN_CODE_API_TIMEOUT_MS: '45000',
+          },
+          modelProvider: {
+            id: 'qwen-oauth',
+            name: 'Qwen OAuth',
+            generationConfig: {
+              timeout: 120000,
+            },
+          },
+        });
+
+        expect(result.config.timeout).toBe(120000);
+        expect(result.sources['timeout'].kind).toBe('modelProviders');
+      });
+
+      it('invalid QWEN_CODE_API_TIMEOUT_MS ignored in OAuth path', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.QWEN_OAUTH,
+          cli: {},
+          settings: {},
+          env: {
+            QWEN_CODE_API_TIMEOUT_MS: 'not-a-number',
+          },
+        });
+
+        expect(result.config.timeout).toBeUndefined();
+      });
+
+      it('negative QWEN_CODE_API_TIMEOUT_MS ignored in OAuth path', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.QWEN_OAUTH,
+          cli: {},
+          settings: {},
+          env: {
+            QWEN_CODE_API_TIMEOUT_MS: '-100',
+          },
+        });
+
+        expect(result.config.timeout).toBeUndefined();
+      });
+
+      it('zero QWEN_CODE_API_TIMEOUT_MS ignored in OAuth path', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.QWEN_OAUTH,
+          cli: {},
+          settings: {},
+          env: {
+            QWEN_CODE_API_TIMEOUT_MS: '0',
+          },
+        });
+
+        expect(result.config.timeout).toBeUndefined();
+      });
+
+      it('QWEN_CODE_API_TIMEOUT_MS works with float value in OAuth', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.QWEN_OAUTH,
+          cli: {},
+          settings: {},
+          env: {
+            QWEN_CODE_API_TIMEOUT_MS: '12345.67',
+          },
+        });
+
+        expect(result.config.timeout).toBe(12345);
+      });
+
+      it('QWEN_CODE_API_TIMEOUT_MS works with proxy in OAuth path', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.QWEN_OAUTH,
+          cli: {},
+          settings: {},
+          env: {
+            QWEN_CODE_API_TIMEOUT_MS: '60000',
+          },
+          proxy: 'http://proxy.example.com:8080',
+        });
+
+        expect(result.config.timeout).toBe(60000);
+        expect(result.config.proxy).toBe('http://proxy.example.com:8080');
+        expect(result.sources['timeout'].kind).toBe('env');
+      });
     });
 
     describe('Anthropic auth type', () => {
@@ -258,6 +366,235 @@ describe('modelConfigResolver', () => {
         expect(result.config.timeout).toBe(60000);
         expect(result.sources['timeout'].kind).toBe('modelProviders');
       });
+
+      it('QWEN_CODE_API_TIMEOUT_MS env var overrides settings timeout', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {
+            apiKey: 'key',
+            generationConfig: {
+              timeout: 30000,
+            },
+          },
+          env: {
+            OPENAI_API_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: '900000',
+          },
+        });
+
+        expect(result.config.timeout).toBe(900000);
+        expect(result.sources['timeout'].kind).toBe('env');
+        expect(result.sources['timeout'].envKey).toBe(
+          'QWEN_CODE_API_TIMEOUT_MS',
+        );
+      });
+
+      it('modelProvider timeout wins over QWEN_CODE_API_TIMEOUT_MS', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {},
+          env: {
+            MY_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: '900000',
+          },
+          modelProvider: {
+            id: 'model',
+            name: 'Model',
+            envKey: 'MY_KEY',
+            baseUrl: 'https://api.example.com',
+            generationConfig: {
+              timeout: 60000,
+            },
+          },
+        });
+
+        // modelProvider > env: modelProvider timeout should win
+        expect(result.config.timeout).toBe(60000);
+        expect(result.sources['timeout'].kind).toBe('modelProviders');
+      });
+
+      it('QWEN_CODE_API_TIMEOUT_MS applies when modelProvider has no timeout', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {},
+          env: {
+            MY_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: '900000',
+          },
+          modelProvider: {
+            id: 'model',
+            name: 'Model',
+            envKey: 'MY_KEY',
+            baseUrl: 'https://api.example.com',
+            generationConfig: {},
+          },
+        });
+
+        expect(result.config.timeout).toBe(900000);
+        expect(result.sources['timeout'].kind).toBe('env');
+        expect(result.sources['timeout'].envKey).toBe(
+          'QWEN_CODE_API_TIMEOUT_MS',
+        );
+      });
+
+      it('ignores invalid QWEN_CODE_API_TIMEOUT_MS values', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {
+            apiKey: 'key',
+            generationConfig: {
+              timeout: 30000,
+            },
+          },
+          env: {
+            OPENAI_API_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: 'invalid',
+          },
+        });
+
+        // Should fall back to settings value
+        expect(result.config.timeout).toBe(30000);
+        expect(result.sources['timeout'].kind).toBe('settings');
+      });
+
+      it('ignores negative or zero QWEN_CODE_API_TIMEOUT_MS values', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {
+            apiKey: 'key',
+            generationConfig: {
+              timeout: 30000,
+            },
+          },
+          env: {
+            OPENAI_API_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: '0',
+          },
+        });
+
+        // Should fall back to settings value
+        expect(result.config.timeout).toBe(30000);
+        expect(result.sources['timeout'].kind).toBe('settings');
+      });
+
+      it('timeout is undefined when not configured, default applied in buildClient', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {
+            apiKey: 'key',
+          },
+          env: {
+            OPENAI_API_KEY: 'key',
+          },
+        });
+
+        // timeout is undefined here; DEFAULT_TIMEOUT (120000) is applied in
+        // the provider's buildClient() when timeout is not set.
+        expect(result.config.timeout).toBeUndefined();
+      });
+
+      it('QWEN_CODE_API_TIMEOUT_MS works for Anthropic auth type', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_ANTHROPIC,
+          cli: {},
+          settings: {},
+          env: {
+            ANTHROPIC_API_KEY: 'key',
+            ANTHROPIC_BASE_URL: 'https://api.anthropic.com',
+            QWEN_CODE_API_TIMEOUT_MS: '600000',
+          },
+        });
+
+        expect(result.config.timeout).toBe(600000);
+        expect(result.sources['timeout'].kind).toBe('env');
+        expect(result.sources['timeout'].envKey).toBe(
+          'QWEN_CODE_API_TIMEOUT_MS',
+        );
+      });
+
+      it('env var actually changes resolved timeout value', () => {
+        // Integration-style test: proves the env var flows through to the resolved config
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {
+            apiKey: 'key',
+            generationConfig: {
+              timeout: 30000,
+            },
+          },
+          env: {
+            OPENAI_API_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: '900000',
+          },
+        });
+
+        // Timeout should be the env var value, not the settings value
+        expect(result.config.timeout).toBe(900000);
+        expect(result.sources['timeout'].kind).toBe('env');
+        expect(result.sources['timeout'].envKey).toBe(
+          'QWEN_CODE_API_TIMEOUT_MS',
+        );
+
+        // Prove it would be used by the client (default.ts:48 reads config.timeout)
+        const clientTimeout = result.config.timeout;
+        expect(clientTimeout).toBe(900000);
+      });
+
+      it('handles extremely large timeout values safely', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: { apiKey: 'key' },
+          env: {
+            OPENAI_API_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: '999999999',
+          },
+        });
+
+        expect(result.config.timeout).toBe(999999999);
+        expect(result.sources['timeout'].kind).toBe('env');
+      });
+
+      it('handles whitespace-padded env values', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: { apiKey: 'key' },
+          env: {
+            OPENAI_API_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: ' 300000 ',
+          },
+        });
+
+        // Number() implicitly trims whitespace, so this should parse correctly
+        expect(result.config.timeout).toBe(300000);
+        expect(result.sources['timeout'].kind).toBe('env');
+      });
+
+      it('ignores negative QWEN_CODE_API_TIMEOUT_MS values', () => {
+        const result = resolveModelConfig({
+          authType: AuthType.USE_OPENAI,
+          cli: {},
+          settings: {
+            apiKey: 'key',
+            generationConfig: { timeout: 30000 },
+          },
+          env: {
+            OPENAI_API_KEY: 'key',
+            QWEN_CODE_API_TIMEOUT_MS: '-100',
+          },
+        });
+
+        expect(result.config.timeout).toBe(30000);
+        expect(result.sources['timeout'].kind).toBe('settings');
+      });
     });
 
     describe('proxy handling', () => {
@@ -348,4 +685,173 @@ describe('modelConfigResolver', () => {
       expect(result.errors[0].message).toContain('envKey');
     });
   });
+
+  describe('[Regression] timeout env override refactor', () => {
+    it('[Regression] OAuth path must apply QWEN_CODE_API_TIMEOUT_MS (was broken before fix #3629)', () => {
+      // Guards against the original bug where resolveQwenOAuthConfig()
+      // returned before applying the env override.
+      const result = resolveModelConfig({
+        authType: AuthType.QWEN_OAUTH,
+        cli: {},
+        settings: {},
+        env: {
+          QWEN_CODE_API_TIMEOUT_MS: '45000',
+        },
+      });
+
+      expect(result.config.timeout).toBe(45000);
+      expect(result.sources['timeout']).toBeDefined();
+      expect(result.sources['timeout'].kind).toBe('env');
+      expect(result.sources['timeout'].envKey).toBe('QWEN_CODE_API_TIMEOUT_MS');
+      expect(result.config.model).toBe(DEFAULT_QWEN_MODEL);
+    });
+
+    it('[Regression] non-OAuth path must apply QWEN_CODE_API_TIMEOUT_MS', () => {
+      const result = resolveModelConfig({
+        authType: AuthType.USE_OPENAI,
+        cli: {},
+        settings: { apiKey: 'key' },
+        env: {
+          OPENAI_API_KEY: 'key',
+          QWEN_CODE_API_TIMEOUT_MS: '900000',
+        },
+      });
+
+      expect(result.config.timeout).toBe(900000);
+      expect(result.sources['timeout'].kind).toBe('env');
+      expect(result.sources['timeout'].envKey).toBe('QWEN_CODE_API_TIMEOUT_MS');
+    });
+
+    it('[Regression] modelProvider timeout must win over env in both paths', () => {
+      // Non-OAuth
+      const nonOAuth = resolveModelConfig({
+        authType: AuthType.USE_OPENAI,
+        cli: {},
+        settings: {},
+        env: {
+          MY_KEY: 'key',
+          QWEN_CODE_API_TIMEOUT_MS: '900000',
+        },
+        modelProvider: {
+          id: 'model',
+          name: 'Model',
+          envKey: 'MY_KEY',
+          baseUrl: 'https://api.example.com',
+          generationConfig: { timeout: 60000 },
+        },
+      });
+      expect(nonOAuth.config.timeout).toBe(60000);
+      expect(nonOAuth.sources['timeout'].kind).toBe('modelProviders');
+
+      // OAuth
+      const oauth = resolveModelConfig({
+        authType: AuthType.QWEN_OAUTH,
+        cli: {},
+        settings: {},
+        env: {
+          QWEN_CODE_API_TIMEOUT_MS: '45000',
+        },
+        modelProvider: {
+          id: 'qwen-oauth',
+          name: 'Qwen OAuth',
+          generationConfig: { timeout: 120000 },
+        },
+      });
+      expect(oauth.config.timeout).toBe(120000);
+      expect(oauth.sources['timeout'].kind).toBe('modelProviders');
+    });
+
+    it('[Regression] refactor must not alter precedence: env > settings', () => {
+      const result = resolveModelConfig({
+        authType: AuthType.USE_OPENAI,
+        cli: {},
+        settings: {
+          apiKey: 'key',
+          generationConfig: { timeout: 30000 },
+        },
+        env: {
+          OPENAI_API_KEY: 'key',
+          QWEN_CODE_API_TIMEOUT_MS: '900000',
+        },
+      });
+
+      // env must override settings
+      expect(result.config.timeout).toBe(900000);
+      expect(result.sources['timeout'].kind).toBe('env');
+    });
+  });
+
+  describe('[Additional] timeout env override edge cases', () => {
+    it('handles scientific notation in QWEN_CODE_API_TIMEOUT_MS', () => {
+      const result = resolveModelConfig({
+        authType: AuthType.USE_OPENAI,
+        cli: {},
+        settings: { apiKey: 'key' },
+        env: {
+          OPENAI_API_KEY: 'key',
+          QWEN_CODE_API_TIMEOUT_MS: '1.5e5',
+        },
+      });
+
+      expect(result.config.timeout).toBe(150000);
+      expect(result.sources['timeout'].kind).toBe('env');
+    });
+
+    it('handles hex values in QWEN_CODE_API_TIMEOUT_MS', () => {
+      const result = resolveModelConfig({
+        authType: AuthType.USE_OPENAI,
+        cli: {},
+        settings: { apiKey: 'key', generationConfig: { timeout: 30000 } },
+        env: {
+          OPENAI_API_KEY: 'key',
+          QWEN_CODE_API_TIMEOUT_MS: '0x2BF20', // 180000 in hex
+        },
+      });
+
+      expect(result.config.timeout).toBe(180000);
+      expect(result.sources['timeout'].kind).toBe('env');
+    });
+
+    it('ignores empty string QWEN_CODE_API_TIMEOUT_MS', () => {
+      const result = resolveModelConfig({
+        authType: AuthType.USE_OPENAI,
+        cli: {},
+        settings: { apiKey: 'key', generationConfig: { timeout: 30000 } },
+        env: {
+          OPENAI_API_KEY: 'key',
+          QWEN_CODE_API_TIMEOUT_MS: '',
+        },
+      });
+
+      expect(result.config.timeout).toBe(30000);
+      expect(result.sources['timeout'].kind).toBe('settings');
+    });
+
+    it('applies env override for every supported auth type', () => {
+      const authTypes = [
+        { type: AuthType.USE_OPENAI, env: { OPENAI_API_KEY: 'key' } },
+        {
+          type: AuthType.USE_ANTHROPIC,
+          env: {
+            ANTHROPIC_API_KEY: 'key',
+            ANTHROPIC_BASE_URL: 'https://api.anthropic.com',
+          },
+        },
+      ];
+
+      for (const { type, env } of authTypes) {
+        const result = resolveModelConfig({
+          authType: type,
+          cli: {},
+          settings: {
+            ...(type === AuthType.USE_OPENAI ? { apiKey: 'key' } : {}),
+          },
+          env: { ...env, QWEN_CODE_API_TIMEOUT_MS: '99999' },
+        });
+
+        expect(result.config.timeout).toBe(99999);
+        expect(result.sources['timeout'].kind).toBe('env');
+      }
+    });
+  });
 });
diff --git a/packages/core/src/models/modelConfigResolver.ts b/packages/core/src/models/modelConfigResolver.ts
index c7db1611c..81c916523 100644
--- a/packages/core/src/models/modelConfigResolver.ts
+++ b/packages/core/src/models/modelConfigResolver.ts
@@ -105,6 +105,32 @@ export interface ModelConfigResolutionResult {
   warnings: string[];
 }
 
+/**
+ * Applies QWEN_CODE_API_TIMEOUT_MS env override if modelProvider has not set a timeout.
+ * Precedence: modelProvider > env > settings > default
+ * Mutates generationConfig and sources in-place.
+ */
+function applyTimeoutEnvOverride(
+  env: Record<string, string | undefined>,
+  generationConfig: Partial<ContentGeneratorConfig>,
+  sources: ConfigSources,
+  modelProvider?: ModelProviderConfig,
+): void {
+  if (modelProvider?.generationConfig?.timeout !== undefined) return;
+
+  const raw = env['QWEN_CODE_API_TIMEOUT_MS'];
+  if (raw === undefined) return;
+
+  const parsed = Number(raw);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    generationConfig.timeout = Math.floor(parsed);
+    sources['timeout'] = {
+      kind: 'env',
+      envKey: 'QWEN_CODE_API_TIMEOUT_MS',
+    };
+  }
+}
+
 /**
  * Resolve model configuration from all input sources.
  *
@@ -231,11 +257,10 @@ export function resolveModelConfig(
   let apiKeyEnvKey: string | undefined;
   if (authType && modelProvider?.envKey) {
     apiKeyEnvKey = modelProvider.envKey;
-    sources['apiKeyEnvKey'] = modelProvidersSource(
-      authType,
-      modelProvider.id,
-      'envKey',
-    );
+    sources['apiKeyEnvKey'] = {
+      ...modelProvidersSource(authType, modelProvider.id, 'envKey'),
+      envKey: modelProvider.envKey,
+    };
   }
 
   // ---- Generation Config (from settings or modelProvider) ----
@@ -247,6 +272,9 @@ export function resolveModelConfig(
     sources,
   );
 
+  // ---- Env override: QWEN_CODE_API_TIMEOUT_MS ----
+  applyTimeoutEnvOverride(env, generationConfig, sources, modelProvider);
+
   // Build final config
   const config: ContentGeneratorConfig = {
     authType,
@@ -325,6 +353,9 @@ function resolveQwenOAuthConfig(
     sources,
   );
 
+  // ---- Env override: QWEN_CODE_API_TIMEOUT_MS ----
+  applyTimeoutEnvOverride(input.env, generationConfig, sources, modelProvider);
+
   const config: ContentGeneratorConfig = {
     authType: AuthType.QWEN_OAUTH,
     model: resolvedModel,
diff --git a/packages/core/src/models/modelsConfig.test.ts b/packages/core/src/models/modelsConfig.test.ts
index 87c8aaf34..f2e4bc1f1 100644
--- a/packages/core/src/models/modelsConfig.test.ts
+++ b/packages/core/src/models/modelsConfig.test.ts
@@ -597,6 +597,639 @@ describe('ModelsConfig', () => {
     expect(gc.samplingParams?.temperature).toBe(0.9); // Preserved from initial config
   });
 
+  it('should fall back to settings-sourced apiKey when registry model envKey is not in process.env (restart scenario)', () => {
+    // Simulate the restart scenario from issue #3417:
+    // 1. User has settings.security.auth.apiKey = 'settings-api-key'
+    // 2. modelProviders.openai has a model with envKey = 'CODING_PLAN_KEY'
+    // 3. process.env['CODING_PLAN_KEY'] is NOT set
+    // 4. resolveCliGenerationConfig correctly resolved apiKey from settings (layer 4)
+    // 5. syncAfterAuthRefresh should NOT discard the settings-sourced key
+
+    const envKey = 'CODING_PLAN_KEY_TEST_3417';
+    // Ensure the env var is NOT set
+    delete process.env[envKey];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'qwen3.5-plus',
+          name: 'Test Model',
+          baseUrl: 'https://api.example.com/v1',
+          envKey,
+          generationConfig: {
+            samplingParams: { temperature: 0.3 },
+          },
+        },
+      ],
+    };
+
+    // ModelsConfig initialized with settings-sourced apiKey (as would happen at startup)
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'qwen3.5-plus',
+        apiKey: 'settings-api-key',
+        baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+      },
+      generationConfigSources: {
+        model: { kind: 'settings', detail: 'settings.model.name' },
+        apiKey: { kind: 'settings', detail: 'security.auth.apiKey' },
+        baseUrl: { kind: 'settings', detail: 'security.auth.baseUrl' },
+      },
+    });
+
+    // Verify initial state
+    expect(currentGenerationConfig(modelsConfig).apiKey).toBe(
+      'settings-api-key',
+    );
+
+    // Simulate what refreshAuth does on startup
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'qwen3.5-plus');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // The settings-sourced apiKey should be preserved as fallback
+    expect(gc.apiKey).toBe('settings-api-key');
+    // envKey metadata should still be set for diagnostics
+    expect(gc.apiKeyEnvKey).toBe(envKey);
+    // Model and other provider config should be applied
+    expect(gc.model).toBe('qwen3.5-plus');
+    expect(gc.samplingParams?.temperature).toBe(0.3);
+
+    // Source should still reflect settings origin
+    const sources = modelsConfig.getGenerationConfigSources();
+    expect(sources['apiKey']?.kind).toBe('settings');
+  });
+
+  it('should prefer env var over settings apiKey when both exist (restart scenario)', () => {
+    const envKey = 'CODING_PLAN_KEY_TEST_3417_PREFER';
+    // Set the env var
+    process.env[envKey] = 'env-api-key';
+
+    try {
+      const modelProvidersConfig: ModelProvidersConfig = {
+        openai: [
+          {
+            id: 'test-model',
+            name: 'Test Model',
+            baseUrl: 'https://api.example.com/v1',
+            envKey,
+          },
+        ],
+      };
+
+      const modelsConfig = new ModelsConfig({
+        initialAuthType: AuthType.USE_OPENAI,
+        modelProvidersConfig,
+        generationConfig: {
+          model: 'test-model',
+          apiKey: 'settings-api-key',
+        },
+        generationConfigSources: {
+          model: { kind: 'settings', detail: 'settings.model.name' },
+          apiKey: { kind: 'settings', detail: 'security.auth.apiKey' },
+        },
+      });
+
+      modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'test-model');
+
+      const gc = currentGenerationConfig(modelsConfig);
+      // Env var should take priority over settings apiKey
+      expect(gc.apiKey).toBe('env-api-key');
+      expect(gc.apiKeyEnvKey).toBe(envKey);
+
+      const sources = modelsConfig.getGenerationConfigSources();
+      expect(sources['apiKey']?.kind).toBe('env');
+    } finally {
+      delete process.env[envKey];
+    }
+  });
+
+  it('should preserve programmatic apiKey when authType and modelId unchanged (restart scenario)', () => {
+    // When apiKey was set via updateCredentials (programmatic source) and
+    // syncAfterAuthRefresh is called with the same authType+modelId,
+    // the short-circuit should preserve the existing key.
+    const envKey = 'CODING_PLAN_KEY_TEST_3417_PROG';
+    delete process.env[envKey];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'provider-model',
+          name: 'Provider Model',
+          baseUrl: 'https://api.example.com/v1',
+          envKey,
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'provider-model',
+        apiKey: 'programmatic-key',
+      },
+      generationConfigSources: {
+        model: { kind: 'programmatic', detail: 'updateCredentials' },
+        apiKey: { kind: 'programmatic', detail: 'updateCredentials' },
+      },
+    });
+
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'provider-model');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // Same authType + same modelId → apiKey preserved via save/restore around applyResolvedModelDefaults
+    expect(gc.apiKey).toBe('programmatic-key');
+  });
+
+  it('should NOT preserve env apiKey with via.modelProviders during model switch', () => {
+    // When switching from model-a to model-b, model-a's provider-specific
+    // envKey value should NOT be reused for model-b — they may target
+    // different services with different credentials.
+    const envKeyA = 'PROVIDER_KEY_A_TEST_3417';
+    const envKeyB = 'PROVIDER_KEY_B_TEST_3417';
+    delete process.env[envKeyA];
+    delete process.env[envKeyB];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'model-a',
+          name: 'Model A',
+          baseUrl: 'https://api-a.example.com/v1',
+          envKey: envKeyA,
+        },
+        {
+          id: 'model-b',
+          name: 'Model B',
+          baseUrl: 'https://api-b.example.com/v1',
+          envKey: envKeyB,
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'model-a',
+        apiKey: 'key-for-model-a',
+      },
+      generationConfigSources: {
+        model: {
+          kind: 'modelProviders',
+          authType: 'openai',
+          modelId: 'model-a',
+          detail: 'model.id',
+        },
+        apiKey: {
+          kind: 'env',
+          envKey: envKeyA,
+          via: {
+            kind: 'modelProviders',
+            authType: 'openai',
+            modelId: 'model-a',
+            detail: 'envKey',
+          },
+        },
+      },
+    });
+
+    // Switch to model-b whose envKey is also not set
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'model-b');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // model-a's key should NOT be reused for model-b
+    expect(gc.apiKey).toBeUndefined();
+    expect(gc.model).toBe('model-b');
+  });
+
+  it('should NOT preserve settings-sourced apiKey when switching to a different provider within same authType', () => {
+    // Cross-provider switch: provider-A (settings-sourced key) → provider-B
+    // Settings key must NOT leak to provider-B which may have a different baseUrl.
+    const envKeyA = 'PROVIDER_KEY_A_SETTINGS_TEST';
+    const envKeyB = 'PROVIDER_KEY_B_SETTINGS_TEST';
+    delete process.env[envKeyA];
+    delete process.env[envKeyB];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'provider-a',
+          name: 'Provider A',
+          baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+          envKey: envKeyA,
+        },
+        {
+          id: 'provider-b',
+          name: 'Provider B',
+          baseUrl: 'https://api.openai.com/v1',
+          envKey: envKeyB,
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'provider-a',
+        apiKey: 'settings-api-key',
+        baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+      },
+      generationConfigSources: {
+        model: { kind: 'settings', detail: 'settings.model.name' },
+        apiKey: { kind: 'settings', detail: 'security.auth.apiKey' },
+        baseUrl: { kind: 'settings', detail: 'security.auth.baseUrl' },
+      },
+    });
+
+    // Switch to provider-b (different model, same authType)
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'provider-b');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // settings-sourced key for provider-a must NOT be sent to provider-b
+    expect(gc.apiKey).toBeUndefined();
+    expect(gc.model).toBe('provider-b');
+    expect(gc.baseUrl).toBe('https://api.openai.com/v1');
+  });
+
+  it('should NOT preserve CLI-sourced apiKey when switching to a different provider within same authType', () => {
+    // Cross-provider switch: provider-A (CLI-sourced key) → provider-B
+    const envKeyA = 'PROVIDER_KEY_A_CLI_TEST';
+    const envKeyB = 'PROVIDER_KEY_B_CLI_TEST';
+    delete process.env[envKeyA];
+    delete process.env[envKeyB];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'cli-provider-a',
+          name: 'CLI Provider A',
+          baseUrl: 'https://api-a.example.com/v1',
+          envKey: envKeyA,
+        },
+        {
+          id: 'cli-provider-b',
+          name: 'CLI Provider B',
+          baseUrl: 'https://api-b.example.com/v1',
+          envKey: envKeyB,
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'cli-provider-a',
+        apiKey: 'cli-provided-key',
+      },
+      generationConfigSources: {
+        model: { kind: 'cli', detail: '--model' },
+        apiKey: { kind: 'cli', detail: '--openaiApiKey' },
+      },
+    });
+
+    // Switch to cli-provider-b (different model, same authType)
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'cli-provider-b');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // CLI key for provider-a must NOT be sent to provider-b
+    expect(gc.apiKey).toBeUndefined();
+    expect(gc.model).toBe('cli-provider-b');
+    expect(gc.baseUrl).toBe('https://api-b.example.com/v1');
+  });
+
+  it('should NOT preserve apiKey on first syncAfterAuthRefresh when previousAuthType is undefined (cold start)', () => {
+    // Cold start: ModelsConfig created without initialAuthType, then
+    // syncAfterAuthRefresh is called for the first time. previousAuthType
+    // is undefined, so isUnchanged must be false — no key preservation.
+    const envKey = 'COLD_START_KEY_TEST_3417';
+    delete process.env[envKey];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'cold-start-model',
+          name: 'Cold Start Model',
+          baseUrl: 'https://api.example.com/v1',
+          envKey,
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'cold-start-model',
+        apiKey: 'stale-key-from-previous-session',
+      },
+      generationConfigSources: {
+        model: { kind: 'settings', detail: 'settings.model.name' },
+        apiKey: { kind: 'settings', detail: 'security.auth.apiKey' },
+      },
+    });
+
+    // First auth refresh — previousAuthType is undefined
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'cold-start-model');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // previousAuthType (undefined) !== USE_OPENAI → isUnchanged is false → no preservation
+    expect(gc.apiKey).toBeUndefined();
+    expect(gc.model).toBe('cold-start-model');
+  });
+
+  it('should NOT preserve apiKey when same modelId but envKey changed (hot-reload)', () => {
+    // Hot-reload scenario: model provider config is reloaded, changing the
+    // envKey for the same model id. The old apiKey must NOT be restored.
+    const oldEnvKey = 'OLD_ENV_KEY_HOT_RELOAD_TEST';
+    const newEnvKey = 'NEW_ENV_KEY_HOT_RELOAD_TEST';
+    delete process.env[oldEnvKey];
+    delete process.env[newEnvKey];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'hot-reload-model',
+          name: 'Hot Reload Model',
+          baseUrl: 'https://api.example.com/v1',
+          envKey: oldEnvKey,
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'hot-reload-model',
+        apiKey: 'old-api-key',
+        baseUrl: 'https://api.example.com/v1',
+        apiKeyEnvKey: oldEnvKey,
+      },
+      generationConfigSources: {
+        model: { kind: 'settings', detail: 'settings.model.name' },
+        apiKey: { kind: 'settings', detail: 'security.auth.apiKey' },
+        baseUrl: {
+          kind: 'modelProviders',
+          authType: 'openai',
+          modelId: 'hot-reload-model',
+          detail: 'baseUrl',
+        },
+        apiKeyEnvKey: {
+          kind: 'modelProviders',
+          authType: 'openai',
+          modelId: 'hot-reload-model',
+          detail: 'envKey',
+        },
+      },
+    });
+
+    // Simulate hot-reload: update registry with new envKey
+    modelsConfig.reloadModelProvidersConfig({
+      openai: [
+        {
+          id: 'hot-reload-model',
+          name: 'Hot Reload Model',
+          baseUrl: 'https://api.example.com/v1',
+          envKey: newEnvKey,
+        },
+      ],
+    });
+
+    // syncAfterAuthRefresh with same authType and modelId
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'hot-reload-model');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // envKey changed → isUnchanged is false → old key must NOT be preserved
+    expect(gc.apiKey).toBeUndefined();
+    expect(gc.apiKeyEnvKey).toBe(newEnvKey);
+    expect(gc.model).toBe('hot-reload-model');
+  });
+
+  it('should NOT preserve apiKey when same modelId but baseUrl changed (hot-reload)', () => {
+    // Hot-reload scenario: model provider config is reloaded, changing the
+    // baseUrl for the same model id. The old apiKey must NOT be restored.
+    const envKey = 'BASE_URL_HOT_RELOAD_TEST';
+    delete process.env[envKey];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'url-reload-model',
+          name: 'URL Reload Model',
+          baseUrl: 'https://old-api.example.com/v1',
+          envKey,
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'url-reload-model',
+        apiKey: 'old-api-key',
+        baseUrl: 'https://old-api.example.com/v1',
+        apiKeyEnvKey: envKey,
+      },
+      generationConfigSources: {
+        model: { kind: 'settings', detail: 'settings.model.name' },
+        apiKey: { kind: 'settings', detail: 'security.auth.apiKey' },
+        baseUrl: {
+          kind: 'modelProviders',
+          authType: 'openai',
+          modelId: 'url-reload-model',
+          detail: 'baseUrl',
+        },
+        apiKeyEnvKey: {
+          kind: 'modelProviders',
+          authType: 'openai',
+          modelId: 'url-reload-model',
+          detail: 'envKey',
+        },
+      },
+    });
+
+    // Simulate hot-reload: update registry with new baseUrl
+    modelsConfig.reloadModelProvidersConfig({
+      openai: [
+        {
+          id: 'url-reload-model',
+          name: 'URL Reload Model',
+          baseUrl: 'https://new-api.example.com/v1',
+          envKey,
+        },
+      ],
+    });
+
+    // syncAfterAuthRefresh with same authType and modelId
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'url-reload-model');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // baseUrl changed → isUnchanged is false → old key must NOT be preserved
+    expect(gc.apiKey).toBeUndefined();
+    expect(gc.baseUrl).toBe('https://new-api.example.com/v1');
+    expect(gc.model).toBe('url-reload-model');
+  });
+
+  it('should NOT preserve apiKey when no-envKey model has baseUrl changed (hot-reload)', () => {
+    // Hot-reload scenario for a model without envKey: baseUrl changes but
+    // modelId stays the same. The old apiKey must NOT be restored.
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'no-envkey-model',
+          name: 'No EnvKey Model',
+          baseUrl: 'https://old-api.example.com/v1',
+          // no envKey
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'no-envkey-model',
+        apiKey: 'old-settings-key',
+        baseUrl: 'https://old-api.example.com/v1',
+      },
+      // Simulate post-apply state: baseUrl source is modelProviders
+      generationConfigSources: {
+        model: {
+          kind: 'modelProviders',
+          authType: 'openai',
+          modelId: 'no-envkey-model',
+          detail: 'model.id',
+        },
+        apiKey: { kind: 'settings', detail: 'security.auth.apiKey' },
+        baseUrl: {
+          kind: 'modelProviders',
+          authType: 'openai',
+          modelId: 'no-envkey-model',
+          detail: 'baseUrl',
+        },
+      },
+    });
+
+    // Simulate hot-reload: update registry with new baseUrl
+    modelsConfig.reloadModelProvidersConfig({
+      openai: [
+        {
+          id: 'no-envkey-model',
+          name: 'No EnvKey Model',
+          baseUrl: 'https://new-api.example.com/v1',
+        },
+      ],
+    });
+
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'no-envkey-model');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // baseUrl changed → isProviderChanged is true even without envKey
+    expect(gc.apiKey).toBeUndefined();
+    expect(gc.baseUrl).toBe('https://new-api.example.com/v1');
+    expect(gc.model).toBe('no-envkey-model');
+  });
+
+  it('should preserve general env var apiKey (e.g. OPENAI_API_KEY) when provider envKey is absent', () => {
+    // If the user has OPENAI_API_KEY set but NOT the provider-specific envKey,
+    // the general env var should be preserved as a fallback.
+    const providerEnvKey = 'SPECIFIC_PROVIDER_KEY_TEST_3417';
+    delete process.env[providerEnvKey];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'test-model',
+          name: 'Test Model',
+          baseUrl: 'https://api.example.com/v1',
+          envKey: providerEnvKey,
+        },
+      ],
+    };
+
+    // resolveCliGenerationConfig resolved apiKey from OPENAI_API_KEY (layer 3)
+    // — source has kind:'env' but no 'via' (general env var, not provider-specific)
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'test-model',
+        apiKey: 'openai-api-key-value',
+      },
+      generationConfigSources: {
+        model: { kind: 'settings', detail: 'settings.model.name' },
+        apiKey: { kind: 'env', envKey: 'OPENAI_API_KEY' },
+      },
+    });
+
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'test-model');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // General env var key should be preserved
+    expect(gc.apiKey).toBe('openai-api-key-value');
+
+    const sources = modelsConfig.getGenerationConfigSources();
+    expect(sources['apiKey']?.kind).toBe('env');
+    expect(sources['apiKey']?.envKey).toBe('OPENAI_API_KEY');
+  });
+
+  it('should preserve CLI-sourced apiKey (--openaiApiKey) when registry model envKey is absent', () => {
+    // Regression: CLI-passed keys (source kind 'cli') must not be discarded
+    // during syncAfterAuthRefresh when the provider's envKey is unset.
+    const envKey = 'CODING_PLAN_KEY_TEST_3417_CLI';
+    delete process.env[envKey];
+
+    const modelProvidersConfig: ModelProvidersConfig = {
+      openai: [
+        {
+          id: 'cli-test-model',
+          name: 'CLI Test Model',
+          baseUrl: 'https://api.example.com/v1',
+          envKey,
+          generationConfig: {
+            samplingParams: { temperature: 0.5 },
+          },
+        },
+      ],
+    };
+
+    const modelsConfig = new ModelsConfig({
+      initialAuthType: AuthType.USE_OPENAI,
+      modelProvidersConfig,
+      generationConfig: {
+        model: 'cli-test-model',
+        apiKey: 'cli-provided-key',
+      },
+      generationConfigSources: {
+        model: { kind: 'cli', detail: '--model' },
+        apiKey: { kind: 'cli', detail: '--openaiApiKey' },
+      },
+    });
+
+    // Verify initial state
+    expect(currentGenerationConfig(modelsConfig).apiKey).toBe(
+      'cli-provided-key',
+    );
+
+    modelsConfig.syncAfterAuthRefresh(AuthType.USE_OPENAI, 'cli-test-model');
+
+    const gc = currentGenerationConfig(modelsConfig);
+    // CLI-sourced apiKey should be preserved as fallback
+    expect(gc.apiKey).toBe('cli-provided-key');
+    expect(gc.apiKeyEnvKey).toBe(envKey);
+    expect(gc.model).toBe('cli-test-model');
+    expect(gc.samplingParams?.temperature).toBe(0.5);
+
+    const sources = modelsConfig.getGenerationConfigSources();
+    expect(sources['apiKey']?.kind).toBe('cli');
+    expect(sources['apiKey']?.detail).toBe('--openaiApiKey');
+  });
+
   it('should maintain consistency between currentModelId and _generationConfig.model after initialization', () => {
     const modelProvidersConfig: ModelProvidersConfig = {
       openai: [
diff --git a/packages/core/src/models/modelsConfig.ts b/packages/core/src/models/modelsConfig.ts
index f7086bbca..d34cc08c6 100644
--- a/packages/core/src/models/modelsConfig.ts
+++ b/packages/core/src/models/modelsConfig.ts
@@ -877,7 +877,49 @@ export class ModelsConfig {
     if (modelId && this.modelRegistry.hasModel(authType, modelId)) {
       const resolved = this.modelRegistry.getModel(authType, modelId);
       if (resolved) {
+        // When authType and modelId haven't changed (startup/restart scenario),
+        // the current apiKey was already correctly resolved by
+        // resolveCliGenerationConfig. Save it so we can restore it if
+        // applyResolvedModelDefaults clears it (i.e. process.env[envKey] is
+        // absent). For cross-provider switches (different modelId), we must
+        // NOT preserve the previous key — it may belong to a different
+        // service. Also detect hot-reload scenarios where the provider
+        // config changed in place (same modelId, different envKey/baseUrl)
+        // by comparing fields that applyResolvedModelDefaults sets. Use
+        // baseUrl source === 'modelProviders' as the "has been applied"
+        // signal — it covers both envKey and no-envKey models, and avoids
+        // false positives when startup baseUrl differs from registry
+        // default. (See #3417)
+        const hasBeenApplied =
+          this.generationConfigSources['baseUrl']?.kind === 'modelProviders';
+        const isProviderChanged =
+          hasBeenApplied &&
+          (this._generationConfig.apiKeyEnvKey !== resolved.envKey ||
+            this._generationConfig.baseUrl !== resolved.baseUrl);
+        const isUnchanged =
+          previousAuthType === authType &&
+          this._generationConfig.model === modelId &&
+          !isProviderChanged;
+        const savedApiKey = isUnchanged
+          ? this._generationConfig.apiKey
+          : undefined;
+        const savedApiKeySource = isUnchanged
+          ? this.generationConfigSources['apiKey']
+            ? { ...this.generationConfigSources['apiKey'] }
+            : undefined
+          : undefined;
+
         this.applyResolvedModelDefaults(resolved);
+
+        // Restore the previously-resolved apiKey if applyResolvedModelDefaults
+        // cleared it (env var not found) and this is the same model.
+        if (isUnchanged && !this._generationConfig.apiKey && savedApiKey) {
+          this._generationConfig.apiKey = savedApiKey;
+          if (savedApiKeySource) {
+            this.generationConfigSources['apiKey'] = savedApiKeySource;
+          }
+        }
+
         this.strictModelProviderSelection = true;
         // Clear active runtime model snapshot since we're now using a registry model
         this.activeRuntimeModelSnapshotId = undefined;
diff --git a/packages/core/src/models/types.ts b/packages/core/src/models/types.ts
index 64f5ef43e..2560a63aa 100644
--- a/packages/core/src/models/types.ts
+++ b/packages/core/src/models/types.ts
@@ -38,6 +38,7 @@ export type ModelGenerationConfig = Pick<
   | 'extra_body'
   | 'contextWindowSize'
   | 'modalities'
+  | 'splitToolMedia'
 >;
 
 /**
diff --git a/packages/core/src/services/backgroundShellRegistry.test.ts b/packages/core/src/services/backgroundShellRegistry.test.ts
new file mode 100644
index 000000000..193492d27
--- /dev/null
+++ b/packages/core/src/services/backgroundShellRegistry.test.ts
@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  BackgroundShellRegistry,
+  type BackgroundShellEntry,
+} from './backgroundShellRegistry.js';
+
+function makeEntry(
+  overrides: Partial<BackgroundShellEntry> = {},
+): BackgroundShellEntry {
+  return {
+    shellId: 's1',
+    command: 'sleep 60',
+    cwd: '/tmp',
+    status: 'running',
+    startTime: 1000,
+    outputPath: '/tmp/s1.output',
+    abortController: new AbortController(),
+    ...overrides,
+  };
+}
+
+describe('BackgroundShellRegistry', () => {
+  describe('register / get / getAll', () => {
+    it('round-trips a registered entry by id', () => {
+      const reg = new BackgroundShellRegistry();
+      const e = makeEntry({ shellId: 'a' });
+      reg.register(e);
+      expect(reg.get('a')).toBe(e);
+    });
+
+    it('returns undefined for unknown id', () => {
+      const reg = new BackgroundShellRegistry();
+      expect(reg.get('missing')).toBeUndefined();
+    });
+
+    it('lists all entries via getAll', () => {
+      const reg = new BackgroundShellRegistry();
+      const a = makeEntry({ shellId: 'a' });
+      const b = makeEntry({ shellId: 'b' });
+      reg.register(a);
+      reg.register(b);
+      const all = reg.getAll();
+      expect(all).toHaveLength(2);
+      expect(all).toContain(a);
+      expect(all).toContain(b);
+    });
+  });
+
+  describe('complete', () => {
+    it('transitions running → completed with exitCode and endTime', () => {
+      const reg = new BackgroundShellRegistry();
+      reg.register(makeEntry({ shellId: 'a' }));
+      reg.complete('a', 0, 2000);
+      const e = reg.get('a')!;
+      expect(e.status).toBe('completed');
+      expect(e.exitCode).toBe(0);
+      expect(e.endTime).toBe(2000);
+    });
+
+    it('is a no-op when entry is not running', () => {
+      const reg = new BackgroundShellRegistry();
+      reg.register(makeEntry({ shellId: 'a' }));
+      reg.cancel('a', 1500);
+      reg.complete('a', 0, 2000);
+      const e = reg.get('a')!;
+      expect(e.status).toBe('cancelled');
+      expect(e.exitCode).toBeUndefined();
+    });
+
+    it('is a no-op for unknown id', () => {
+      const reg = new BackgroundShellRegistry();
+      expect(() => reg.complete('missing', 0, 0)).not.toThrow();
+    });
+  });
+
+  describe('fail', () => {
+    it('transitions running → failed with error and endTime', () => {
+      const reg = new BackgroundShellRegistry();
+      reg.register(makeEntry({ shellId: 'a' }));
+      reg.fail('a', 'spawn error', 2000);
+      const e = reg.get('a')!;
+      expect(e.status).toBe('failed');
+      expect(e.error).toBe('spawn error');
+      expect(e.endTime).toBe(2000);
+    });
+
+    it('is a no-op when entry is not running', () => {
+      const reg = new BackgroundShellRegistry();
+      reg.register(makeEntry({ shellId: 'a' }));
+      reg.complete('a', 0, 1500);
+      reg.fail('a', 'late error', 2000);
+      const e = reg.get('a')!;
+      expect(e.status).toBe('completed');
+      expect(e.error).toBeUndefined();
+    });
+  });
+
+  describe('abortAll', () => {
+    it('cancels every running entry and leaves terminal entries alone', () => {
+      const reg = new BackgroundShellRegistry();
+      const acRunning1 = new AbortController();
+      const acRunning2 = new AbortController();
+      const acDone = new AbortController();
+      reg.register(makeEntry({ shellId: 'a', abortController: acRunning1 }));
+      reg.register(makeEntry({ shellId: 'b', abortController: acRunning2 }));
+      reg.register(makeEntry({ shellId: 'c', abortController: acDone }));
+      reg.complete('c', 0, 1500);
+
+      reg.abortAll();
+
+      expect(reg.get('a')!.status).toBe('cancelled');
+      expect(reg.get('b')!.status).toBe('cancelled');
+      expect(reg.get('c')!.status).toBe('completed');
+      expect(acRunning1.signal.aborted).toBe(true);
+      expect(acRunning2.signal.aborted).toBe(true);
+      expect(acDone.signal.aborted).toBe(false);
+    });
+
+    it('is a no-op when registry is empty', () => {
+      const reg = new BackgroundShellRegistry();
+      expect(() => reg.abortAll()).not.toThrow();
+    });
+  });
+
+  describe('cancel', () => {
+    it('transitions running → cancelled and aborts the signal', () => {
+      const reg = new BackgroundShellRegistry();
+      const ac = new AbortController();
+      reg.register(makeEntry({ shellId: 'a', abortController: ac }));
+      reg.cancel('a', 2000);
+      const e = reg.get('a')!;
+      expect(e.status).toBe('cancelled');
+      expect(e.endTime).toBe(2000);
+      expect(ac.signal.aborted).toBe(true);
+    });
+
+    it('is a no-op when entry is already terminal', () => {
+      const reg = new BackgroundShellRegistry();
+      const ac = new AbortController();
+      reg.register(makeEntry({ shellId: 'a', abortController: ac }));
+      reg.complete('a', 0, 1500);
+      reg.cancel('a', 2000);
+      const e = reg.get('a')!;
+      expect(e.status).toBe('completed');
+      expect(ac.signal.aborted).toBe(false);
+    });
+
+    it('is a no-op for unknown id', () => {
+      const reg = new BackgroundShellRegistry();
+      expect(() => reg.cancel('missing', 0)).not.toThrow();
+    });
+  });
+});
diff --git a/packages/core/src/services/backgroundShellRegistry.ts b/packages/core/src/services/backgroundShellRegistry.ts
new file mode 100644
index 000000000..b8b2e5951
--- /dev/null
+++ b/packages/core/src/services/backgroundShellRegistry.ts
@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Tracks background shell processes spawned via the `shell` tool with
+ * `is_background: true`. Each entry holds the metadata the agent and the
+ * `/tasks` slash command need to query, observe, or terminate a running
+ * background shell.
+ *
+ * State machine: register → running → { completed | failed | cancelled }.
+ * Transitions out of running are one-shot: complete/fail/cancel become
+ * no-ops once the entry has settled. This prevents late callbacks (e.g. a
+ * process that exits during cancellation) from clobbering the terminal
+ * status.
+ */
+
+export type BackgroundShellStatus =
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+export interface BackgroundShellEntry {
+  /** Stable id used by the model and the `/tasks` UI. */
+  shellId: string;
+  /** The user-supplied command, after any pre-processing the tool applies. */
+  command: string;
+  /** Working directory the process was spawned in. */
+  cwd: string;
+  /** OS pid once spawned; absent if registration happens before spawn. */
+  pid?: number;
+  status: BackgroundShellStatus;
+  /** Exit code on `completed`. */
+  exitCode?: number;
+  /** Error message on `failed`. */
+  error?: string;
+  /** ms epoch when the entry was registered. */
+  startTime: number;
+  /** ms epoch when the entry transitioned out of running. */
+  endTime?: number;
+  /** Absolute path of the captured stdout/stderr file. */
+  outputPath: string;
+  /** Aborted by `cancel()`; callers should wire it into the spawn. */
+  abortController: AbortController;
+}
+
+export class BackgroundShellRegistry {
+  // Entries persist for the session lifetime — no automatic eviction of
+  // terminal entries. For typical interactive sessions (tens of background
+  // shells over an hour) this is fine, but long-running sessions that spawn
+  // many short-lived background commands will see the map and the on-disk
+  // output files grow without bound. Eviction policy (LRU? age-based? cap?)
+  // is left as a follow-up alongside output-file rotation.
+  private readonly entries = new Map<string, BackgroundShellEntry>();
+
+  register(entry: BackgroundShellEntry): void {
+    this.entries.set(entry.shellId, entry);
+  }
+
+  get(shellId: string): BackgroundShellEntry | undefined {
+    return this.entries.get(shellId);
+  }
+
+  getAll(): readonly BackgroundShellEntry[] {
+    return [...this.entries.values()];
+  }
+
+  complete(shellId: string, exitCode: number, endTime: number): void {
+    const entry = this.entries.get(shellId);
+    if (!entry || entry.status !== 'running') return;
+    entry.status = 'completed';
+    entry.exitCode = exitCode;
+    entry.endTime = endTime;
+  }
+
+  fail(shellId: string, error: string, endTime: number): void {
+    const entry = this.entries.get(shellId);
+    if (!entry || entry.status !== 'running') return;
+    entry.status = 'failed';
+    entry.error = error;
+    entry.endTime = endTime;
+  }
+
+  cancel(shellId: string, endTime: number): void {
+    const entry = this.entries.get(shellId);
+    if (!entry || entry.status !== 'running') return;
+    entry.status = 'cancelled';
+    entry.endTime = endTime;
+    entry.abortController.abort();
+  }
+
+  /**
+   * Cancel every still-running entry. Called on session/Config shutdown so
+   * background shells don't outlive the CLI process and leak orphaned
+   * children. Symmetric with `BackgroundTaskRegistry.abortAll()` for the
+   * subagent path.
+   */
+  abortAll(): void {
+    const endTime = Date.now();
+    for (const entry of Array.from(this.entries.values())) {
+      if (entry.status === 'running') {
+        this.cancel(entry.shellId, endTime);
+      }
+    }
+  }
+}
diff --git a/packages/core/src/services/chatRecordingService.ts b/packages/core/src/services/chatRecordingService.ts
index 7732be1a5..21c94114d 100644
--- a/packages/core/src/services/chatRecordingService.ts
+++ b/packages/core/src/services/chatRecordingService.ts
@@ -91,7 +91,8 @@ export interface ChatRecord {
     | 'at_command'
     | 'notification'
     | 'cron'
-    | 'custom_title';
+    | 'custom_title'
+    | 'rewind';
   /** Working directory at time of message */
   cwd: string;
   /** CLI version for compatibility tracking */
@@ -133,7 +134,17 @@ export interface ChatRecord {
     | UiTelemetryRecordPayload
     | AtCommandRecordPayload
     | CustomTitleRecordPayload
-    | NotificationRecordPayload;
+    | NotificationRecordPayload
+    | RewindRecordPayload;
+
+  /** Background subagent that produced this record (e.g. "explore-7f3c"). */
+  agentId?: string;
+  /** Display name for the subagent (e.g. "Explore"). */
+  agentName?: string;
+  /** UI hint for tools rendering subagent transcripts. */
+  agentColor?: string;
+  /** True for records produced by a subagent (a sidechain off the parent session). */
+  isSidechain?: boolean;
 }
 
 export interface NotificationRecordPayload {
@@ -212,6 +223,14 @@ export interface UiTelemetryRecordPayload {
   uiEvent: UiEvent;
 }
 
+/**
+ * Stored payload for conversation rewind events.
+ */
+export interface RewindRecordPayload {
+  /** Number of UI history items truncated. */
+  truncatedCount: number;
+}
+
 /**
  * Service for recording the current chat session to disk.
  *
@@ -240,6 +259,18 @@ export class ChatRecordingService {
   /** UUID of the last written record in the chain */
   private lastRecordUuid: string | null = null;
   private readonly config: Config;
+  /**
+   * Tracks the `lastRecordUuid` value just before each user turn was recorded.
+   * Used by {@link rewindRecording} to re-root the parentUuid chain so that
+   * rewound messages end up on a dead branch in the tree, making
+   * `reconstructHistory()` skip them automatically on resume.
+   *
+   * Index `i` holds the UUID of the last record written before the (i+1)th
+   * user message was appended. For example, `turnParentUuids[0]` is the UUID
+   * right before the very first user message (often `null` or the startup
+   * context record).
+   */
+  private turnParentUuids: Array<string | null> = [];
   /**
    * Cached chats-dir / conversation-file path so per-record appendRecord
    * doesn't re-stat them on every write. The first call performs the
@@ -463,6 +494,7 @@ export class ChatRecordingService {
    */
   recordUserMessage(message: PartListUnion): void {
     try {
+      this.turnParentUuids.push(this.lastRecordUuid);
       const record: ChatRecord = {
         ...this.createBaseRecord('user'),
         message: createUserContent(message),
@@ -739,6 +771,70 @@ export class ChatRecordingService {
     }
   }
 
+  /**
+   * Records a conversation rewind and re-roots the parentUuid chain.
+   *
+   * Sets `lastRecordUuid` back to the UUID that was current just before the
+   * target user turn was recorded, then appends a rewind system record.
+   * This makes all messages after that point sit on a dead branch in the
+   * UUID tree, so `reconstructHistory()` will skip them on resume.
+   *
+   * @param targetTurnIndex 0-based index of the user turn to rewind to.
+   *   For example, 0 means rewind to the very first user message (keeping
+   *   nothing before it), 1 means keep the first user turn, etc.
+   * @param payload Additional metadata to persist with the rewind record.
+   */
+  rewindRecording(targetTurnIndex: number, payload: RewindRecordPayload): void {
+    try {
+      // Re-root: point back to the record just before the target user turn.
+      this.lastRecordUuid = this.turnParentUuids[targetTurnIndex] ?? null;
+      // Trim future boundaries — they no longer exist in the active branch.
+      this.turnParentUuids = this.turnParentUuids.slice(0, targetTurnIndex);
+
+      const record: ChatRecord = {
+        ...this.createBaseRecord('system'),
+        type: 'system',
+        subtype: 'rewind',
+        systemPayload: payload,
+      };
+
+      this.appendRecord(record);
+    } catch (error) {
+      debugLogger.error('Error saving rewind record:', error);
+    }
+  }
+
+  /**
+   * Rebuilds `turnParentUuids` from a reconstructed message list.
+   *
+   * Call this after resuming a session so that subsequent rewinds within
+   * the resumed session have correct boundary data. Also updates
+   * `lastRecordUuid` to the last record in the chain.
+   */
+  rebuildTurnBoundaries(messages: ChatRecord[]): void {
+    this.turnParentUuids = [];
+    let prevUuid: string | null =
+      this.config.getResumedSessionData()?.lastCompletedUuid !== undefined
+        ? null
+        : this.lastRecordUuid;
+
+    for (let i = 0; i < messages.length; i++) {
+      const record = messages[i];
+      if (
+        record.type === 'user' &&
+        record.subtype !== 'notification' &&
+        record.subtype !== 'cron'
+      ) {
+        this.turnParentUuids.push(prevUuid);
+      }
+      prevUuid = record.uuid;
+    }
+    // Ensure lastRecordUuid points to the end of the reconstructed chain.
+    if (messages.length > 0) {
+      this.lastRecordUuid = messages[messages.length - 1].uuid;
+    }
+  }
+
   /**
    * Records a custom title for the session.
    * Appended as a system record so it persists with the session data.
diff --git a/packages/core/src/services/shellExecutionService.test.ts b/packages/core/src/services/shellExecutionService.test.ts
index 17a0a525e..5cc203929 100644
--- a/packages/core/src/services/shellExecutionService.test.ts
+++ b/packages/core/src/services/shellExecutionService.test.ts
@@ -33,6 +33,26 @@ const mockIsBinary = vi.hoisted(() => vi.fn());
 const mockPlatform = vi.hoisted(() => vi.fn());
 const mockGetPty = vi.hoisted(() => vi.fn());
 const mockSerializeTerminalToObject = vi.hoisted(() => vi.fn());
+const mockSerializeTerminalToText = vi.hoisted(() =>
+  vi.fn((terminal: pkg.Terminal): string => {
+    const buffer = terminal.buffer.active;
+    const lines: string[] = [];
+
+    for (let i = 0; i < buffer.length; i++) {
+      const line = buffer.getLine(i);
+      const lineContent = line ? line.translateToString(true) : '';
+
+      if (line?.isWrapped && lines.length > 0) {
+        lines[lines.length - 1] += lineContent;
+        continue;
+      }
+
+      lines.push(lineContent);
+    }
+
+    return lines.join('\n').trimEnd();
+  }),
+);
 const mockGetShellConfiguration = vi.hoisted(() =>
   vi.fn().mockReturnValue({
     executable: 'bash',
@@ -74,6 +94,7 @@ vi.mock('../utils/getPty.js', () => ({
 }));
 vi.mock('../utils/terminalSerializer.js', () => ({
   serializeTerminalToObject: mockSerializeTerminalToObject,
+  serializeTerminalToText: mockSerializeTerminalToText,
 }));
 vi.mock('../utils/shell-utils.js', () => ({
   getShellConfiguration: mockGetShellConfiguration,
@@ -122,6 +143,17 @@ const createExpectedAnsiOutput = (text: string | string[]): AnsiOutput => {
   return expected;
 };
 
+const createAnsiToken = (text: string) => ({
+  text,
+  bold: false,
+  italic: false,
+  underline: false,
+  dim: false,
+  inverse: false,
+  fg: '',
+  bg: '',
+});
+
 const setupConflictingPathEnv = () => {
   process.env = {
     ...originalProcessEnv,
@@ -135,6 +167,21 @@ const expectNormalizedWindowsPathEnv = (env: NodeJS.ProcessEnv) => {
   expect(env['Path']).toBeUndefined();
 };
 
+const waitForDataEventCount = async (
+  onOutputEventMock: Mock<(event: ShellOutputEvent) => void>,
+  expectedCount: number,
+) => {
+  for (let attempt = 0; attempt < 20; attempt++) {
+    const dataEvents = onOutputEventMock.mock.calls.filter(
+      ([event]) => event.type === 'data',
+    );
+    if (dataEvents.length >= expectedCount) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+};
+
 describe('ShellExecutionService', () => {
   let mockPtyProcess: EventEmitter & {
     pid: number;
@@ -364,6 +411,23 @@ describe('ShellExecutionService', () => {
 
       expect(result.output).toBe('Compressing objects: 100% (7/7), done.');
     });
+
+    it('should not persist narrow terminal soft wraps as transcript newlines', async () => {
+      const { result } = await simulateExecution(
+        'narrow-output',
+        (pty) => {
+          pty.onData.mock.calls[0][0]('abcdefghijklmnopqrstuvwxyz\nshort\n');
+          pty.onExit.mock.calls[0][0]({ exitCode: 0, signal: null });
+        },
+        {
+          ...shellExecutionConfig,
+          terminalWidth: 8,
+          terminalHeight: 4,
+        },
+      );
+
+      expect(result.output).toBe('abcdefghijklmnopqrstuvwxyz\nshort');
+    });
   });
 
   describe('pty interaction', () => {
@@ -709,6 +773,59 @@ describe('ShellExecutionService', () => {
       );
     });
 
+    it('does not re-emit live output when only soft-wrap segmentation changes', async () => {
+      const coloredShellExecutionConfig = {
+        ...shellExecutionConfig,
+        showColor: true,
+        disableDynamicLineTrimming: true,
+      };
+      const firstWrappedOutput = [
+        [createAnsiToken('abcd')],
+        [createAnsiToken('efgh')],
+      ];
+      const rewrappedOutput = [
+        [createAnsiToken('ab')],
+        [createAnsiToken('cdef')],
+        [createAnsiToken('gh')],
+      ];
+      const logicalOutput = [[createAnsiToken('abcdefgh')]];
+      let rawRenderCount = 0;
+
+      mockSerializeTerminalToObject.mockImplementation(
+        (
+          _terminal,
+          _scrollOffset,
+          options?: { unwrapWrappedLines?: boolean },
+        ) => {
+          if (options?.unwrapWrappedLines) {
+            return logicalOutput;
+          }
+
+          rawRenderCount += 1;
+          return rawRenderCount === 1 ? firstWrappedOutput : rewrappedOutput;
+        },
+      );
+
+      await simulateExecution(
+        'narrow-output',
+        (pty) => {
+          pty.onData.mock.calls[0][0]('abcdefgh');
+          pty.onData.mock.calls[0][0]('\r');
+          pty.onExit.mock.calls[0][0]({ exitCode: 0, signal: null });
+        },
+        coloredShellExecutionConfig,
+      );
+
+      const dataEvents = onOutputEventMock.mock.calls.filter(
+        ([event]) => event.type === 'data',
+      );
+      expect(dataEvents).toHaveLength(1);
+      expect(dataEvents[0][0]).toEqual({
+        type: 'data',
+        chunk: firstWrappedOutput,
+      });
+    });
+
     it('should call onOutputEvent with AnsiOutput when showColor is false', async () => {
       await simulateExecution(
         'ls --color=auto',
@@ -733,6 +850,47 @@ describe('ShellExecutionService', () => {
       );
     });
 
+    it('does not re-emit default plain live output when only soft-wrap segmentation changes', async () => {
+      const abortController = new AbortController();
+      const handle = await ShellExecutionService.execute(
+        'narrow-output',
+        '/test/dir',
+        onOutputEventMock,
+        abortController.signal,
+        true,
+        {
+          ...shellExecutionConfig,
+          terminalWidth: 4,
+          terminalHeight: 4,
+          showColor: false,
+          disableDynamicLineTrimming: false,
+        },
+      );
+
+      await new Promise((resolve) => process.nextTick(resolve));
+      mockPtyProcess.onData.mock.calls[0][0]('abcdefgh');
+      await waitForDataEventCount(onOutputEventMock, 1);
+
+      ShellExecutionService.resizePty(handle.pid!, 2, 4);
+      mockPtyProcess.onData.mock.calls[0][0]('\r');
+      mockPtyProcess.onExit.mock.calls[0][0]({ exitCode: 0, signal: null });
+      await handle.result;
+
+      const dataEvents = onOutputEventMock.mock.calls.filter(
+        ([event]) => event.type === 'data',
+      );
+      expect(dataEvents).toHaveLength(1);
+      const firstDataEvent = dataEvents[0][0];
+      if (firstDataEvent.type !== 'data') {
+        throw new Error('Expected a shell data event.');
+      }
+      const chunk = firstDataEvent.chunk as AnsiOutput;
+      expect(chunk.map((line) => line[0]?.text).filter(Boolean)).toEqual([
+        'abcd',
+        'efgh',
+      ]);
+    });
+
     it('should handle multi-line output correctly when showColor is false', async () => {
       await simulateExecution(
         'ls --color=auto',
diff --git a/packages/core/src/services/shellExecutionService.ts b/packages/core/src/services/shellExecutionService.ts
index 113ddb5a2..8d7e0bb3b 100644
--- a/packages/core/src/services/shellExecutionService.ts
+++ b/packages/core/src/services/shellExecutionService.ts
@@ -17,6 +17,7 @@ import { getShellConfiguration } from '../utils/shell-utils.js';
 import pkg from '@xterm/headless';
 import {
   serializeTerminalToObject,
+  serializeTerminalToText,
   type AnsiOutput,
 } from '../utils/terminalSerializer.js';
 import { normalizePathEnvForWindows } from '../utils/windowsPath.js';
@@ -135,17 +136,6 @@ const isExpectedPtyExitRaceError = (error: unknown): boolean => {
   );
 };
 
-const getFullBufferText = (terminal: pkg.Terminal): string => {
-  const buffer = terminal.buffer.active;
-  const lines: string[] = [];
-  for (let i = 0; i < buffer.length; i++) {
-    const line = buffer.getLine(i);
-    const lineContent = line ? line.translateToString(true) : '';
-    lines.push(lineContent);
-  }
-  return lines.join('\n').trimEnd();
-};
-
 const replayTerminalOutput = async (
   output: string,
   cols: number,
@@ -163,7 +153,90 @@ const replayTerminalOutput = async (
     replayTerminal.write(output, () => resolve());
   });
 
-  return getFullBufferText(replayTerminal);
+  return serializeTerminalToText(replayTerminal);
+};
+
+const getLastNonEmptyAnsiLineIndex = (output: AnsiOutput): number => {
+  for (let i = output.length - 1; i >= 0; i--) {
+    const line = output[i];
+    if (
+      line
+        .map((segment) => segment.text)
+        .join('')
+        .trim().length > 0
+    ) {
+      return i;
+    }
+  }
+
+  return -1;
+};
+
+const trimTrailingEmptyAnsiLines = (output: AnsiOutput): AnsiOutput =>
+  output.slice(0, getLastNonEmptyAnsiLineIndex(output) + 1);
+
+const areAnsiOutputsEqual = (
+  left: AnsiOutput | null,
+  right: AnsiOutput,
+): boolean => {
+  if (!left || left.length !== right.length) {
+    return false;
+  }
+
+  return left.every((leftLine, lineIndex) => {
+    const rightLine = right[lineIndex];
+    if (leftLine.length !== rightLine.length) {
+      return false;
+    }
+
+    return leftLine.every((leftToken, tokenIndex) => {
+      const rightToken = rightLine[tokenIndex];
+      return (
+        leftToken.text === rightToken.text &&
+        leftToken.bold === rightToken.bold &&
+        leftToken.italic === rightToken.italic &&
+        leftToken.underline === rightToken.underline &&
+        leftToken.dim === rightToken.dim &&
+        leftToken.inverse === rightToken.inverse &&
+        leftToken.fg === rightToken.fg &&
+        leftToken.bg === rightToken.bg
+      );
+    });
+  });
+};
+
+const createPlainAnsiLine = (text: string) => [
+  {
+    text,
+    bold: false,
+    italic: false,
+    underline: false,
+    dim: false,
+    inverse: false,
+    fg: '',
+    bg: '',
+  },
+];
+
+const serializePlainViewportToAnsiOutput = (
+  terminal: pkg.Terminal,
+  unwrapWrappedLines = false,
+): AnsiOutput => {
+  const buffer = terminal.buffer.active;
+  const lines: AnsiOutput = [];
+
+  for (let y = 0; y < terminal.rows; y++) {
+    const line = buffer.getLine(buffer.viewportY + y);
+    const lineContent = line ? line.translateToString(true) : '';
+
+    if (unwrapWrappedLines && line?.isWrapped && lines.length > 0) {
+      lines[lines.length - 1][0].text += lineContent;
+    } else {
+      lines.push(createPlainAnsiLine(lineContent));
+    }
+  }
+
+  return lines;
 };
 
 interface ProcessCleanupStrategy {
@@ -256,6 +329,7 @@ export class ShellExecutionService {
     abortSignal: AbortSignal,
     shouldUseNodePty: boolean,
     shellExecutionConfig: ShellExecutionConfig,
+    options: { streamStdout?: boolean } = {},
   ): Promise<ShellExecutionHandle> {
     if (shouldUseNodePty) {
       const ptyInfo = await getPty();
@@ -280,6 +354,7 @@ export class ShellExecutionService {
       cwd,
       onOutputEvent,
       abortSignal,
+      options.streamStdout ?? false,
     );
   }
 
@@ -288,6 +363,7 @@ export class ShellExecutionService {
     cwd: string,
     onOutputEvent: (event: ShellOutputEvent) => void,
     abortSignal: AbortSignal,
+    streamStdout: boolean,
   ): ShellExecutionHandle {
     try {
       const isWindows = os.platform() === 'win32';
@@ -342,26 +418,61 @@ export class ShellExecutionService {
             }
           }
 
-          outputChunks.push(data);
-
+          // Binary sniff applies in both modes — even streaming consumers
+          // (e.g. background shell output file) shouldn't pile up text-decoded
+          // garbage when the command actually emits binary (`cat /bin/ls`,
+          // image dumps, etc.). Track sniffed bytes by running sum so the
+          // accumulator is truly byte-bounded — the previous version recomputed
+          // sniffedBytes from `slice(0, 20)` on every call, which never grew
+          // past the first 20 chunks' total and let the chunk array leak on
+          // line-sized streams.
           if (isStreamingRawContent && sniffedBytes < MAX_SNIFF_SIZE) {
-            const sniffBuffer = Buffer.concat(outputChunks.slice(0, 20));
-            sniffedBytes = sniffBuffer.length;
-
+            outputChunks.push(data);
+            sniffedBytes += data.length;
+            const sniffBuffer = Buffer.concat(outputChunks);
             if (isBinary(sniffBuffer)) {
               isStreamingRawContent = false;
+              if (streamStdout) {
+                // Tell the streaming consumer to stop writing text chunks;
+                // drop the sniff accumulator now so it can be GC'd.
+                onOutputEvent({ type: 'binary_detected' });
+                outputChunks.length = 0;
+              }
+            } else if (streamStdout && sniffedBytes >= MAX_SNIFF_SIZE) {
+              // Sniff passed in streaming mode — text confirmed, drop the
+              // accumulator. Subsequent chunks fall through to the streaming
+              // emit path below without ever touching outputChunks.
+              outputChunks.length = 0;
             }
+          } else if (!streamStdout) {
+            // Buffered (foreground) mode past sniff: keep accumulating for
+            // the final emit at exit. Streaming mode does not accumulate.
+            outputChunks.push(data);
           }
 
-          if (isStreamingRawContent) {
-            const decoder = stream === 'stdout' ? stdoutDecoder : stderrDecoder;
-            const decodedChunk = decoder.decode(data, { stream: true });
+          if (!isStreamingRawContent) {
+            // Binary mode: drop further data. Foreground emits the
+            // binary_detected event from handleExit (existing behavior);
+            // background already emitted it above.
+            return;
+          }
 
-            if (stream === 'stdout') {
-              stdout += decodedChunk;
-            } else {
-              stderr += decodedChunk;
-            }
+          const decoder = stream === 'stdout' ? stdoutDecoder : stderrDecoder;
+          const decodedChunk = decoder.decode(data, { stream: true });
+
+          if (streamStdout) {
+            // Streaming text mode: push through immediately, no string
+            // accumulation. (Up to ~4KB may already have been emitted
+            // before binary detection trips — bounded, acceptable.)
+            onOutputEvent({ type: 'data', chunk: decodedChunk });
+            return;
+          }
+
+          // Buffered text mode: accumulate for the final cleaned-blob emit.
+          if (stream === 'stdout') {
+            stdout += decodedChunk;
+          } else {
+            stderr += decodedChunk;
           }
         };
 
@@ -378,7 +489,9 @@ export class ShellExecutionService {
           const finalStrippedOutput = stripAnsi(combinedOutput).trim();
 
           if (isStreamingRawContent) {
-            if (finalStrippedOutput) {
+            // In streaming mode chunks were already emitted as they arrived;
+            // re-emitting the final blob would duplicate everything.
+            if (!streamStdout && finalStrippedOutput) {
               onOutputEvent({ type: 'data', chunk: finalStrippedOutput });
             }
           } else {
@@ -536,7 +649,7 @@ export class ShellExecutionService {
 
         let processingChain = Promise.resolve();
         let decoder: TextDecoder | null = null;
-        let output: string | AnsiOutput | null = null;
+        let outputComparison: AnsiOutput | null = null;
         const outputChunks: Buffer[] = [];
         const error: Error | null = null;
         let exited = false;
@@ -558,7 +671,7 @@ export class ShellExecutionService {
 
           if (!shellExecutionConfig.disableDynamicLineTrimming) {
             if (!hasStartedOutput) {
-              const bufferText = getFullBufferText(headlessTerminal);
+              const bufferText = serializeTerminalToText(headlessTerminal);
               if (bufferText.trim().length === 0) {
                 return;
               }
@@ -567,53 +680,36 @@ export class ShellExecutionService {
           }
 
           let newOutput: AnsiOutput;
+          let newOutputComparison: AnsiOutput;
           if (shellExecutionConfig.showColor) {
             newOutput = serializeTerminalToObject(headlessTerminal);
+            newOutputComparison = serializeTerminalToObject(
+              headlessTerminal,
+              0,
+              { unwrapWrappedLines: true },
+            );
           } else {
-            const buffer = headlessTerminal.buffer.active;
-            const lines: AnsiOutput = [];
-            for (let y = 0; y < headlessTerminal.rows; y++) {
-              const line = buffer.getLine(buffer.viewportY + y);
-              const lineContent = line ? line.translateToString(true) : '';
-              lines.push([
-                {
-                  text: lineContent,
-                  bold: false,
-                  italic: false,
-                  underline: false,
-                  dim: false,
-                  inverse: false,
-                  fg: '',
-                  bg: '',
-                },
-              ]);
-            }
-            newOutput = lines;
+            newOutput = serializePlainViewportToAnsiOutput(headlessTerminal);
+            newOutputComparison = serializePlainViewportToAnsiOutput(
+              headlessTerminal,
+              true,
+            );
           }
 
-          let lastNonEmptyLine = -1;
-          for (let i = newOutput.length - 1; i >= 0; i--) {
-            const line = newOutput[i];
-            if (
-              line
-                .map((segment) => segment.text)
-                .join('')
-                .trim().length > 0
-            ) {
-              lastNonEmptyLine = i;
-              break;
-            }
-          }
-
-          const trimmedOutput = newOutput.slice(0, lastNonEmptyLine + 1);
+          const trimmedOutput = trimTrailingEmptyAnsiLines(newOutput);
+          const trimmedOutputComparison =
+            trimTrailingEmptyAnsiLines(newOutputComparison);
 
           const finalOutput = shellExecutionConfig.disableDynamicLineTrimming
             ? newOutput
             : trimmedOutput;
+          const finalOutputComparison =
+            shellExecutionConfig.disableDynamicLineTrimming
+              ? newOutputComparison
+              : trimmedOutputComparison;
 
-          // Using stringify for a quick deep comparison.
-          if (JSON.stringify(output) !== JSON.stringify(finalOutput)) {
-            output = finalOutput;
+          if (!areAnsiOutputsEqual(outputComparison, finalOutputComparison)) {
+            outputComparison = finalOutputComparison;
             onOutputEvent({
               type: 'data',
               chunk: finalOutput,
@@ -759,11 +855,11 @@ export class ShellExecutionService {
                     rows,
                   );
                 } else {
-                  fullOutput = getFullBufferText(headlessTerminal);
+                  fullOutput = serializeTerminalToText(headlessTerminal);
                 }
               } catch {
                 try {
-                  fullOutput = getFullBufferText(headlessTerminal);
+                  fullOutput = serializeTerminalToText(headlessTerminal);
                 } catch {
                   // Ignore fallback rendering errors and resolve with empty text.
                 }
diff --git a/packages/core/src/services/toolUseSummary.test.ts b/packages/core/src/services/toolUseSummary.test.ts
new file mode 100644
index 000000000..bc6649bbc
--- /dev/null
+++ b/packages/core/src/services/toolUseSummary.test.ts
@@ -0,0 +1,409 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Config } from '../config/config.js';
+import {
+  cleanSummary,
+  createToolUseSummaryMessage,
+  generateToolUseSummary,
+  TOOL_USE_SUMMARY_SYSTEM_PROMPT,
+  truncateJson,
+} from './toolUseSummary.js';
+
+// Sanity helper for the pre-truncation tests: `y` count in the output must
+// be less than maxLength (since JSON quoting and the field name eat some of
+// the budget) — confirming the input never reached its full 10MB form.
+function maxLengthGuard(maxLength: number) {
+  return maxLength;
+}
+
+describe('truncateJson', () => {
+  it('returns JSON for short values', () => {
+    expect(truncateJson({ foo: 'bar' }, 100)).toBe('{"foo":"bar"}');
+    expect(truncateJson('hello', 100)).toBe('"hello"');
+    expect(truncateJson(42, 100)).toBe('42');
+  });
+
+  it('truncates long values with ellipsis', () => {
+    const long = 'x'.repeat(500);
+    const result = truncateJson(long, 50);
+    expect(result.length).toBe(50);
+    expect(result.endsWith('...')).toBe(true);
+  });
+
+  it('handles undefined', () => {
+    expect(truncateJson(undefined, 100)).toBe('[undefined]');
+  });
+
+  it('pre-truncates large string leaves before JSON serialization', () => {
+    // Ensures we don't allocate the full JSON for a 10MB string just to
+    // slice it to maxLength. The result must still be ≤ maxLength.
+    const huge = 'x'.repeat(10_000_000);
+    const result = truncateJson(huge, 300);
+    expect(result.length).toBeLessThanOrEqual(300);
+    expect(result.endsWith('...')).toBe(true);
+  });
+
+  it('pre-truncates large string fields inside objects', () => {
+    // The point: a 10MB string field must not be fully serialized before the
+    // outer cap is applied (would allocate 10MB+ of JSON only to slice it).
+    // Pre-truncation slices each string leaf to maxLength first, so the
+    // serializer never sees the full payload.
+    const obj = { content: 'y'.repeat(10_000_000) };
+    const result = truncateJson(obj, 300);
+    expect(result.length).toBeLessThanOrEqual(300);
+    // The huge field is truncated to <= maxLength characters — far below
+    // its original 10M length.
+    const yCount = (result.match(/y/g) ?? []).length;
+    expect(yCount).toBeLessThan(maxLengthGuard(300));
+  });
+
+  it('handles circular references gracefully', () => {
+    const circular: Record<string, unknown> = {};
+    circular['self'] = circular;
+    expect(truncateJson(circular, 100)).toBe('[unable to serialize]');
+  });
+});
+
+describe('cleanSummary', () => {
+  it('preserves well-formed labels', () => {
+    expect(cleanSummary('Searched in auth/')).toBe('Searched in auth/');
+    expect(cleanSummary('Fixed NPE in UserService')).toBe(
+      'Fixed NPE in UserService',
+    );
+  });
+
+  it('takes first line only', () => {
+    expect(cleanSummary('Created signup endpoint\nSome reasoning')).toBe(
+      'Created signup endpoint',
+    );
+  });
+
+  it('strips surrounding quotes', () => {
+    expect(cleanSummary('"Read config.json"')).toBe('Read config.json');
+    expect(cleanSummary("'Ran failing tests'")).toBe('Ran failing tests');
+    expect(cleanSummary('`Fixed bug`')).toBe('Fixed bug');
+  });
+
+  it('strips leading bullet/dash', () => {
+    expect(cleanSummary('- Searched auth')).toBe('Searched auth');
+    expect(cleanSummary('* Read files')).toBe('Read files');
+    expect(cleanSummary('• Fixed NPE')).toBe('Fixed NPE');
+  });
+
+  it('strips Label:/Summary: prefixes', () => {
+    expect(cleanSummary('Label: Fixed bug')).toBe('Fixed bug');
+    expect(cleanSummary('Summary: Ran tests')).toBe('Ran tests');
+    expect(cleanSummary('Label:Searched files')).toBe('Searched files');
+  });
+
+  it('rejects error messages', () => {
+    expect(cleanSummary('API error: 500')).toBe('');
+    expect(cleanSummary('Error: something went wrong')).toBe('');
+    expect(cleanSummary('I cannot generate a summary')).toBe('');
+    expect(cleanSummary("I can't help with that")).toBe('');
+    expect(cleanSummary('Unable to determine')).toBe('');
+  });
+
+  it('caps length at 100 chars', () => {
+    const long = 'x'.repeat(200);
+    expect(cleanSummary(long).length).toBe(100);
+  });
+
+  it('returns empty for empty/whitespace input', () => {
+    expect(cleanSummary('')).toBe('');
+    expect(cleanSummary('   ')).toBe('');
+    expect(cleanSummary('\n\n')).toBe('');
+  });
+
+  it('preserves CJK labels', () => {
+    expect(cleanSummary('搜索了 auth 模块')).toBe('搜索了 auth 模块');
+  });
+
+  it('strips Unicode curly quotes', () => {
+    expect(cleanSummary('“Read config.json”')).toBe('Read config.json');
+    expect(cleanSummary('‘Ran tests’')).toBe('Ran tests');
+  });
+
+  it('strips CJK corner brackets', () => {
+    expect(cleanSummary('「搜索了 auth 模块」')).toBe('搜索了 auth 模块');
+    expect(cleanSummary('『Fixed bug』')).toBe('Fixed bug');
+  });
+
+  it('strips markdown emphasis markers', () => {
+    expect(cleanSummary('**Read 4 files**')).toBe('Read 4 files');
+    expect(cleanSummary('_Searched auth_')).toBe('Searched auth');
+    expect(cleanSummary('__Fixed NPE__')).toBe('Fixed NPE');
+  });
+
+  it('rejects Chinese refusal responses', () => {
+    expect(cleanSummary('我无法生成摘要')).toBe('');
+    expect(cleanSummary('我不能回答这个')).toBe('');
+    expect(cleanSummary('抱歉，我不能帮助')).toBe('');
+    expect(cleanSummary('无法确定')).toBe('');
+    expect(cleanSummary('无法完成')).toBe('');
+  });
+
+  it('rejects curly-apostrophe English refusals', () => {
+    // U+2019 right single quotation mark — models often emit this for
+    // typographic apostrophes and the ASCII-only check missed it.
+    expect(cleanSummary('I can’t generate that')).toBe('');
+  });
+
+  it('rejects additional English refusal patterns', () => {
+    expect(cleanSummary('Failed to read files')).toBe('');
+    expect(cleanSummary('Sorry, I cannot')).toBe('');
+    expect(cleanSummary('Request failed')).toBe('');
+  });
+});
+
+describe('createToolUseSummaryMessage', () => {
+  it('creates a message with generated uuid and timestamp', () => {
+    const msg = createToolUseSummaryMessage('Fixed bug', ['call-1', 'call-2']);
+    expect(msg.type).toBe('tool_use_summary');
+    expect(msg.summary).toBe('Fixed bug');
+    expect(msg.precedingToolUseIds).toEqual(['call-1', 'call-2']);
+    expect(msg.uuid).toMatch(/^[0-9a-f-]{36}$/);
+    expect(msg.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it('generates distinct uuids', () => {
+    const a = createToolUseSummaryMessage('a', []);
+    const b = createToolUseSummaryMessage('b', []);
+    expect(a.uuid).not.toBe(b.uuid);
+  });
+});
+
+describe('generateToolUseSummary', () => {
+  const makeMockConfig = (
+    fastModel: string | undefined,
+    generateContentFn?: ReturnType<typeof vi.fn>,
+  ): Config => {
+    const mockClient = generateContentFn
+      ? { generateContent: generateContentFn }
+      : undefined;
+    return {
+      getFastModel: () => fastModel,
+      getGeminiClient: () => mockClient,
+    } as unknown as Config;
+  };
+
+  const abortController = (): AbortController => new AbortController();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns null when tools array is empty', async () => {
+    const config = makeMockConfig('qwen-fast');
+    const result = await generateToolUseSummary({
+      config,
+      tools: [],
+      signal: abortController().signal,
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when no fast model is configured', async () => {
+    const config = makeMockConfig(undefined);
+    const result = await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Read', input: { file: 'a.ts' }, output: '...' }],
+      signal: abortController().signal,
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when signal is already aborted', async () => {
+    const config = makeMockConfig('qwen-fast');
+    const ac = abortController();
+    ac.abort();
+    const result = await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Read', input: {}, output: '' }],
+      signal: ac.signal,
+    });
+    expect(result).toBeNull();
+  });
+
+  it('calls model with fast model id and system prompt', async () => {
+    const generateContentFn = vi.fn().mockResolvedValue({
+      candidates: [
+        {
+          content: { parts: [{ text: 'Searched in auth/' }] },
+        },
+      ],
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    const result = await generateToolUseSummary({
+      config,
+      tools: [
+        { name: 'Grep', input: { pattern: 'login' }, output: '3 matches' },
+      ],
+      signal: abortController().signal,
+    });
+
+    expect(result).toBe('Searched in auth/');
+    expect(generateContentFn).toHaveBeenCalledTimes(1);
+
+    const args = generateContentFn.mock.calls[0];
+    const [contents, generationConfig, , model, promptId] = args;
+
+    expect(model).toBe('qwen-fast');
+    expect(promptId).toBe('tool_use_summary_generation');
+    expect(generationConfig.systemInstruction).toBe(
+      TOOL_USE_SUMMARY_SYSTEM_PROMPT,
+    );
+    expect(generationConfig.tools).toEqual([]);
+
+    const userText = contents[0].parts[0].text as string;
+    expect(userText).toContain('Tool: Grep');
+    expect(userText).toContain('"pattern":"login"');
+    expect(userText).toContain('3 matches');
+    expect(userText).toContain('Label:');
+  });
+
+  it('includes lastAssistantText as intent prefix', async () => {
+    const generateContentFn = vi.fn().mockResolvedValue({
+      candidates: [{ content: { parts: [{ text: 'Fixed auth bug' }] } }],
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Edit', input: {}, output: '' }],
+      signal: abortController().signal,
+      lastAssistantText:
+        'I will now fix the authentication bug in the login flow.',
+    });
+
+    const userText = generateContentFn.mock.calls[0][0][0].parts[0]
+      .text as string;
+    expect(userText).toContain(
+      "User's intent (from assistant's last message):",
+    );
+    expect(userText).toContain('fix the authentication bug');
+  });
+
+  it('truncates lastAssistantText to 200 chars', async () => {
+    const generateContentFn = vi.fn().mockResolvedValue({
+      candidates: [{ content: { parts: [{ text: 'Done' }] } }],
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    const longText = 'A'.repeat(500);
+    await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Edit', input: {}, output: '' }],
+      signal: abortController().signal,
+      lastAssistantText: longText,
+    });
+
+    const userText = generateContentFn.mock.calls[0][0][0].parts[0]
+      .text as string;
+    // 200 As + some wrapper text, but no 500 As
+    expect(userText).toContain('A'.repeat(200));
+    expect(userText).not.toContain('A'.repeat(201));
+  });
+
+  it('uses explicit model parameter over config fast model', async () => {
+    const generateContentFn = vi.fn().mockResolvedValue({
+      candidates: [{ content: { parts: [{ text: 'Done' }] } }],
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Edit', input: {}, output: '' }],
+      signal: abortController().signal,
+      model: 'qwen-turbo-explicit',
+    });
+
+    expect(generateContentFn.mock.calls[0][3]).toBe('qwen-turbo-explicit');
+  });
+
+  it('returns null when model returns empty text', async () => {
+    const generateContentFn = vi.fn().mockResolvedValue({
+      candidates: [{ content: { parts: [{ text: '' }] } }],
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    const result = await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Read', input: {}, output: '' }],
+      signal: abortController().signal,
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when model call throws', async () => {
+    const generateContentFn = vi.fn().mockRejectedValue(new Error('API error'));
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    const result = await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Read', input: {}, output: '' }],
+      signal: abortController().signal,
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when the signal aborts during the call', async () => {
+    const ac = abortController();
+    const generateContentFn = vi.fn().mockImplementation(async () => {
+      ac.abort();
+      throw new Error('aborted');
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    const result = await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Read', input: {}, output: '' }],
+      signal: ac.signal,
+    });
+    expect(result).toBeNull();
+  });
+
+  it('truncates tool input/output to 300 chars', async () => {
+    const generateContentFn = vi.fn().mockResolvedValue({
+      candidates: [{ content: { parts: [{ text: 'Read file' }] } }],
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    const hugeInput = { content: 'x'.repeat(10000) };
+    const hugeOutput = 'y'.repeat(10000);
+
+    await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Read', input: hugeInput, output: hugeOutput }],
+      signal: abortController().signal,
+    });
+
+    const userText = generateContentFn.mock.calls[0][0][0].parts[0]
+      .text as string;
+    // Each field capped at 300, so overall prompt shouldn't contain the
+    // full 10K repetition.
+    expect(userText).not.toContain('x'.repeat(500));
+    expect(userText).not.toContain('y'.repeat(500));
+    expect(userText).toContain('...');
+  });
+
+  it('cleans markdown bullets / quotes from model output', async () => {
+    const generateContentFn = vi.fn().mockResolvedValue({
+      candidates: [{ content: { parts: [{ text: '- "Searched auth/"' }] } }],
+    });
+    const config = makeMockConfig('qwen-fast', generateContentFn);
+
+    const result = await generateToolUseSummary({
+      config,
+      tools: [{ name: 'Grep', input: {}, output: '' }],
+      signal: abortController().signal,
+    });
+    expect(result).toBe('Searched auth/');
+  });
+});
diff --git a/packages/core/src/services/toolUseSummary.ts b/packages/core/src/services/toolUseSummary.ts
new file mode 100644
index 000000000..aa2007155
--- /dev/null
+++ b/packages/core/src/services/toolUseSummary.ts
@@ -0,0 +1,309 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Tool Use Summary Generator
+ *
+ * Generates a short human-readable label (git-commit-subject style, ~30 chars)
+ * describing what a batch of tool calls accomplished. Uses the configured fast
+ * model so the call is cheap; runs in parallel with the next turn's API call so
+ * its ~1s latency is hidden behind the 5-30s main-model streaming.
+ *
+ * Ported from Claude Code (`services/toolUseSummary/toolUseSummaryGenerator.ts`).
+ * The system prompt is verbatim; the input/output shape and truncation rules
+ * are preserved for behavioral parity with the SDK `tool_use_summary` message.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { Config } from '../config/config.js';
+import { getResponseText } from '../utils/partUtils.js';
+import { createDebugLogger } from '../utils/debugLogger.js';
+
+const debugLogger = createDebugLogger('TOOL_USE_SUMMARY');
+
+/**
+ * Message emitted into the stream after a tool batch completes with a
+ * successful summary. Mirrors Claude Code's `ToolUseSummaryMessage` so SDK
+ * clients consuming either stream see a compatible shape.
+ */
+export interface ToolUseSummaryMessage {
+  type: 'tool_use_summary';
+  summary: string;
+  /** Tool-use call IDs this summary describes. */
+  precedingToolUseIds: string[];
+  uuid: string;
+  timestamp: string;
+}
+
+/**
+ * Creates a `tool_use_summary` message. The UUID and timestamp are generated
+ * here so the message is immediately serializable for recording/SDK emission.
+ */
+export function createToolUseSummaryMessage(
+  summary: string,
+  precedingToolUseIds: string[],
+): ToolUseSummaryMessage {
+  return {
+    type: 'tool_use_summary',
+    summary,
+    precedingToolUseIds,
+    uuid: randomUUID(),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export const TOOL_USE_SUMMARY_SYSTEM_PROMPT = `Write a short summary label describing what these tool calls accomplished. It appears as a single-line row in a mobile app and truncates around 30 characters, so think git-commit-subject, not sentence.
+
+Keep the verb in past tense and the most distinctive noun. Drop articles, connectors, and long location context first.
+
+Examples:
+- Searched in auth/
+- Fixed NPE in UserService
+- Created signup endpoint
+- Read config.json
+- Ran failing tests`;
+
+/** Max characters per input/output field fed to the summarizer. */
+const INPUT_TRUNCATE_LENGTH = 300;
+/** Max characters of the last assistant text included as user-intent prefix. */
+const LAST_ASSISTANT_TEXT_LENGTH = 200;
+/** Output length cap. Matches mobile UI truncation behavior. */
+const MAX_SUMMARY_LENGTH = 100;
+
+export interface ToolInfo {
+  name: string;
+  input: unknown;
+  output: unknown;
+}
+
+export interface GenerateToolUseSummaryParams {
+  config: Config;
+  tools: ToolInfo[];
+  signal: AbortSignal;
+  /**
+   * Trailing text from the assistant's last message, used as intent prefix
+   * so the summarizer knows what the user was trying to accomplish.
+   */
+  lastAssistantText?: string;
+  /**
+   * Fast model to use. If omitted, falls back to `config.getFastModel()`;
+   * if that also returns undefined, the call is skipped (returns null).
+   * Unlike `sessionRecap`, this does not fall back to the main model —
+   * summary generation is a nice-to-have and must not incur main-model cost.
+   */
+  model?: string;
+}
+
+/**
+ * Generates a short label for a completed tool batch.
+ *
+ * @returns The summary string, or null when skipped (no tools, no fast model,
+ * aborted, or model failure). Non-critical: callers should not surface errors.
+ */
+export async function generateToolUseSummary(
+  params: GenerateToolUseSummaryParams,
+): Promise<string | null> {
+  const { config, tools, signal, lastAssistantText } = params;
+
+  if (tools.length === 0) {
+    return null;
+  }
+
+  const model = params.model ?? config.getFastModel();
+  if (!model) {
+    debugLogger.debug('No fast model configured — skipping summary generation');
+    return null;
+  }
+
+  if (signal.aborted) {
+    return null;
+  }
+
+  try {
+    const toolSummaries = tools
+      .map((tool) => {
+        const inputStr = truncateJson(tool.input, INPUT_TRUNCATE_LENGTH);
+        const outputStr = truncateJson(tool.output, INPUT_TRUNCATE_LENGTH);
+        return `Tool: ${tool.name}\nInput: ${inputStr}\nOutput: ${outputStr}`;
+      })
+      .join('\n\n');
+
+    const contextPrefix = lastAssistantText
+      ? `User's intent (from assistant's last message): ${lastAssistantText.slice(0, LAST_ASSISTANT_TEXT_LENGTH)}\n\n`
+      : '';
+
+    const userPrompt = `${contextPrefix}Tools completed:\n\n${toolSummaries}\n\nLabel:`;
+
+    const geminiClient = config.getGeminiClient();
+    if (!geminiClient) {
+      debugLogger.debug('No gemini client available — skipping');
+      return null;
+    }
+
+    const response = await geminiClient.generateContent(
+      [{ role: 'user', parts: [{ text: userPrompt }] }],
+      {
+        systemInstruction: TOOL_USE_SUMMARY_SYSTEM_PROMPT,
+        tools: [],
+        maxOutputTokens: 60,
+        temperature: 0.3,
+      },
+      signal,
+      model,
+      'tool_use_summary_generation',
+    );
+
+    if (signal.aborted) return null;
+
+    const raw = getResponseText(response)?.trim();
+    if (!raw) {
+      debugLogger.debug('Summary generation returned empty result');
+      return null;
+    }
+
+    const cleaned = cleanSummary(raw);
+    if (!cleaned) {
+      debugLogger.debug(`Summary cleaned to empty: raw="${raw}"`);
+      return null;
+    }
+
+    debugLogger.debug(`Summary generated: "${cleaned}"`);
+    return cleaned;
+  } catch (err) {
+    if (signal.aborted) return null;
+    debugLogger.warn(
+      `Summary generation failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Truncates a JSON value to a maximum length for the prompt. Mirrors
+ * Claude Code's `truncateJson` behavior (including the `...` suffix).
+ *
+ * For large string inputs, pre-truncates BEFORE serialization to avoid
+ * allocating the full JSON representation on the interactive turn path —
+ * a 10MB ReadFile result would otherwise be fully stringified just to be
+ * sliced down to 300 chars and discarded.
+ *
+ * For object/array inputs, recursively pre-truncates string fields one
+ * level deep before serialization. Tool inputs (`args`) and outputs
+ * (functionResponse content) are typically shallow objects with the
+ * dominant cost in a small number of long string fields.
+ */
+export function truncateJson(value: unknown, maxLength: number): string {
+  try {
+    const pre = preTruncate(value, maxLength);
+    const str = JSON.stringify(pre);
+    if (str == null) return '[undefined]';
+    return str.length <= maxLength ? str : str.slice(0, maxLength - 3) + '...';
+  } catch {
+    return '[unable to serialize]';
+  }
+}
+
+/**
+ * Walks an arbitrary value and pre-truncates string leaves that exceed
+ * `maxLength`. Bounded to depth 4 to keep the cost predictable on deeply
+ * nested objects (rare in tool args/outputs but possible).
+ */
+function preTruncate(value: unknown, maxLength: number, depth = 0): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') {
+    return value.length > maxLength ? value.slice(0, maxLength) : value;
+  }
+  if (depth >= 4) return value;
+  if (Array.isArray(value)) {
+    return value.map((v) => preTruncate(v, maxLength, depth + 1));
+  }
+  if (typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = preTruncate(v, maxLength, depth + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Strips markdown, quotes, and common prefix noise from the model's raw
+ * response. Enforces `MAX_SUMMARY_LENGTH` as a hard cap — the mobile UI
+ * truncates around 30 chars, but we allow some slack so unusual-but-useful
+ * labels (e.g. CJK phrases) survive. Returns empty string if the result is
+ * unusable (error message, prefixed label, etc.).
+ */
+/**
+ * Character class covering ASCII and common Unicode quote / bracket-quote
+ * pairs. Chinese-instruct models frequently emit U+2018/U+2019 (curly single),
+ * U+201C/U+201D (curly double), U+300C-F (CJK corner brackets). Bounded
+ * quantifier keeps the regex linear (js/polynomial-redos).
+ */
+const QUOTE_CHARS = '"\'`‘’“”「」『』';
+const LEADING_QUOTES_RE = new RegExp(`^[${QUOTE_CHARS}]{1,10}`);
+const TRAILING_QUOTES_RE = new RegExp(`[${QUOTE_CHARS}]{1,10}$`);
+
+/**
+ * Error/refusal-like response markers, matched case-insensitively anywhere
+ * the label should not produce. Covers English and Chinese refusals common
+ * in mixed-provider deployments.
+ */
+const REFUSAL_PREFIXES = [
+  /^api error\b/i,
+  /^error[:：]/i,
+  // Match "I can't" (ASCII U+0027 apostrophe), "I can’t" (curly U+2019),
+  // and "I cannot" as a single pattern.
+  /^i can(?:['’]t|not)\b/i,
+  /^unable to\b/i,
+  /^failed to\b/i,
+  /^sorry[,，]/i,
+  /^request failed\b/i,
+  /^我无法/,
+  /^我不能/,
+  /^抱歉[,，]?/,
+  /^无法/,
+];
+
+export function cleanSummary(raw: string): string {
+  // Take first line only
+  let text = raw.split('\n')[0]?.trim() ?? '';
+
+  // Strip leading bullet/dash first — otherwise a bulleted quoted label like
+  // `- "Searched auth/"` would keep its leading quote after the trailing one
+  // is stripped.
+  text = text.replace(/^[-*•]\s+/, '').trim();
+
+  // Strip markdown emphasis (`**bold**`, `__bold__`, `_italic_`). Bounded
+  // quantifiers keep the regex linear.
+  text = text
+    .replace(/^[*_]{1,3}/, '')
+    .replace(/[*_]{1,3}$/, '')
+    .trim();
+
+  // Strip surrounding ASCII + Unicode quotes/backticks.
+  text = text
+    .replace(LEADING_QUOTES_RE, '')
+    .replace(TRAILING_QUOTES_RE, '')
+    .trim();
+
+  // Strip common prefix labels like "Label:" "Summary:"
+  text = text.replace(/^(label|summary|result|output)\s*[:：]\s*/i, '').trim();
+
+  if (!text) return '';
+
+  // Reject error/refusal-like responses (English + Chinese variants).
+  for (const re of REFUSAL_PREFIXES) {
+    if (re.test(text)) return '';
+  }
+
+  // Hard cap length
+  if (text.length > MAX_SUMMARY_LENGTH) {
+    text = text.slice(0, MAX_SUMMARY_LENGTH).trim();
+  }
+
+  return text;
+}
diff --git a/packages/core/src/skills/bundled/batch/SKILL.md b/packages/core/src/skills/bundled/batch/SKILL.md
index b6b9c9e8d..a44d1cdac 100644
--- a/packages/core/src/skills/bundled/batch/SKILL.md
+++ b/packages/core/src/skills/bundled/batch/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: batch
 description: Execute batch operations on multiple files in parallel. Automatically discovers files, splits into chunks, and processes with parallel worker agents. Use `/batch` followed by operation and file pattern.
+argument-hint: '<operation> <file-pattern>'
 allowedTools:
   - task
   - glob
diff --git a/packages/core/src/skills/bundled/loop/SKILL.md b/packages/core/src/skills/bundled/loop/SKILL.md
index ea9ae7cf3..70bc49418 100644
--- a/packages/core/src/skills/bundled/loop/SKILL.md
+++ b/packages/core/src/skills/bundled/loop/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: loop
 description: Create a recurring loop that runs a prompt on a schedule. Usage - /loop 5m check the build, /loop check the PR every 30m, /loop run tests (defaults to 10m). /loop list to show jobs, /loop clear to cancel all.
+argument-hint: '[interval] <prompt> | list | clear'
 allowedTools:
   - cron_create
   - cron_list
diff --git a/packages/core/src/skills/bundled/qc-helper/SKILL.md b/packages/core/src/skills/bundled/qc-helper/SKILL.md
index 14fbaa152..bc68011a5 100644
--- a/packages/core/src/skills/bundled/qc-helper/SKILL.md
+++ b/packages/core/src/skills/bundled/qc-helper/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: qc-helper
 description: Answer any question about Qwen Code usage, features, configuration, and troubleshooting by referencing the official user documentation. Also helps users view or modify their settings.json. Invoke with `/qc-helper` followed by a question, e.g. `/qc-helper how do I configure MCP servers?` or `/qc-helper change approval mode to yolo`.
+argument-hint: '<question>'
 allowedTools:
   - read_file
   - edit_file
diff --git a/packages/core/src/skills/bundled/review/SKILL.md b/packages/core/src/skills/bundled/review/SKILL.md
index 62022b3c5..2a0571184 100644
--- a/packages/core/src/skills/bundled/review/SKILL.md
+++ b/packages/core/src/skills/bundled/review/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: review
 description: Review changed code for correctness, security, code quality, and performance. Use when the user asks to review code changes, a PR, or specific files. Invoke with `/review`, `/review <pr-number>`, `/review <file-path>`, or `/review <pr-number> --comment` to post inline comments on the PR.
+argument-hint: '[pr-number|file-path] [--comment]'
 allowedTools:
   - task
   - run_shell_command
@@ -17,7 +18,7 @@ You are an expert code reviewer. Your job is to review code changes and provide
 
 **Critical rules (most commonly violated — read these first):**
 
-1. **Match the language of the PR.** If the PR is in English, ALL your output (terminal + PR comments) MUST be in English. If in Chinese, use Chinese. Do NOT switch languages.
+1. **Match the language of the PR.** If the PR is in English, ALL your output (terminal + PR comments) MUST be in English. If in Chinese, use Chinese. Do NOT switch languages. For **local reviews** (no PR), if the system prompt includes an output language preference, use that language; otherwise follow the user's input language.
 2. **Step 9: use Create Review API** with `comments` array for inline comments. Do NOT use `gh api .../pulls/.../comments` to post individual comments. See Step 9 for the JSON format.
 
 **Design philosophy: Silence is better than noise.** Every comment you make should be worth the reader's time. If you're unsure whether something is a problem, DO NOT MENTION IT. Low-quality feedback causes "cry wolf" fatigue — developers stop reading all AI comments and miss real issues.
@@ -528,4 +529,4 @@ These criteria apply to both Step 4 (review agents) and Step 5 (verification age
 - Flag any exposed secrets, credentials, API keys, or tokens in the diff as **Critical**.
 - Silence is better than noise. If you have nothing important to say, say nothing.
 - **Do NOT use `#N` notation** (e.g., `#1`, `#2`) in PR comments or summaries — GitHub auto-links these to issues/PRs. Use `(1)`, `[1]`, or descriptive references instead.
-- **Match the language of the PR.** Write review comments, findings, and summaries in the same language as the PR title/description/code comments. If the PR is in English, write in English. If in Chinese, write in Chinese. Do NOT switch languages.
+- **Match the language of the PR.** Write review comments, findings, and summaries in the same language as the PR title/description/code comments. If the PR is in English, write in English. If in Chinese, write in Chinese. Do NOT switch languages. For **local reviews** (no PR), respect the user's output language preference if set; otherwise follow the user's input language.
diff --git a/packages/core/src/skills/skill-load.test.ts b/packages/core/src/skills/skill-load.test.ts
index 754a1a204..2dbaca2fd 100644
--- a/packages/core/src/skills/skill-load.test.ts
+++ b/packages/core/src/skills/skill-load.test.ts
@@ -43,6 +43,13 @@ describe('skill-load', () => {
           allowedTools: ['read_file', 'write_file'],
         };
       }
+      if (yamlString.includes('argument-hint:')) {
+        return {
+          name: 'test-skill',
+          description: 'A test skill',
+          'argument-hint': '[topic]',
+        };
+      }
       // Default case
       return {
         name: 'test-skill',
@@ -174,6 +181,21 @@ You are a helpful assistant with this skill.
       expect(config.allowedTools).toEqual(['read_file', 'write_file']);
     });
 
+    it('should parse argument-hint from frontmatter', () => {
+      const markdownWithArgumentHint = `---
+name: test-skill
+description: A test skill
+argument-hint: "[topic]"
+---
+
+Skill body.
+`;
+
+      const config = parseSkillContent(markdownWithArgumentHint, testFilePath);
+
+      expect(config.argumentHint).toBe('[topic]');
+    });
+
     it('should throw error for invalid format without frontmatter', () => {
       const invalidMarkdown = `# Just a heading
 Some content without frontmatter.
diff --git a/packages/core/src/skills/skill-load.ts b/packages/core/src/skills/skill-load.ts
index 2eba12aa7..5b236d926 100644
--- a/packages/core/src/skills/skill-load.ts
+++ b/packages/core/src/skills/skill-load.ts
@@ -115,6 +115,10 @@ export function parseSkillContent(
 
   // Extract optional model field
   const model = parseModelField(frontmatter);
+  const argumentHint =
+    typeof frontmatter['argument-hint'] === 'string'
+      ? frontmatter['argument-hint']
+      : undefined;
 
   // Optional `paths` frontmatter: glob patterns that gate when this skill
   // is offered to the model (conditional skill).
@@ -124,6 +128,7 @@ export function parseSkillContent(
     name,
     description,
     allowedTools,
+    argumentHint,
     model,
     filePath,
     body: body.trim(),
diff --git a/packages/core/src/skills/skill-manager.test.ts b/packages/core/src/skills/skill-manager.test.ts
index 26bce924a..f4384ef01 100644
--- a/packages/core/src/skills/skill-manager.test.ts
+++ b/packages/core/src/skills/skill-manager.test.ts
@@ -82,6 +82,13 @@ describe('SkillManager', () => {
           allowedTools: ['read_file', 'write_file'],
         };
       }
+      if (yamlString.includes('argument-hint:')) {
+        return {
+          name: 'test-skill',
+          description: 'A test skill',
+          'argument-hint': '[topic]',
+        };
+      }
       // Match a frontmatter-level `paths:` field, not any incidental
       // occurrence of "paths:" in the body. Multiline + start-anchor matches
       // a top-level YAML key.
@@ -277,6 +284,25 @@ You are a helpful assistant with this skill.
       expect(config.allowedTools).toEqual(['read_file', 'write_file']);
     });
 
+    it('should parse argument-hint from frontmatter', () => {
+      const markdownWithArgumentHint = `---
+name: test-skill
+description: A test skill
+argument-hint: "[topic]"
+---
+
+Skill body.
+`;
+
+      const config = manager.parseSkillContent(
+        markdownWithArgumentHint,
+        validSkillConfig.filePath,
+        'project',
+      );
+
+      expect(config.argumentHint).toBe('[topic]');
+    });
+
     it('should parse content with paths (conditional skill)', () => {
       const markdown = `---
 name: tsx-helper
diff --git a/packages/core/src/skills/skill-manager.ts b/packages/core/src/skills/skill-manager.ts
index 4590940e0..4bd12fbc2 100644
--- a/packages/core/src/skills/skill-manager.ts
+++ b/packages/core/src/skills/skill-manager.ts
@@ -530,7 +530,11 @@ export class SkillManager {
       // Extract optional model field
       const model = parseModelField(frontmatter);
 
-      // Extract when_to_use and disable-model-invocation
+      // Extract argument-hint, when_to_use, and disable-model-invocation
+      const argumentHint =
+        typeof frontmatter['argument-hint'] === 'string'
+          ? frontmatter['argument-hint']
+          : undefined;
       const whenToUse =
         typeof frontmatter['when_to_use'] === 'string'
           ? frontmatter['when_to_use']
@@ -552,6 +556,7 @@ export class SkillManager {
         allowedTools,
         hooks,
         skillRoot,
+        argumentHint,
         model,
         level,
         filePath,
diff --git a/packages/core/src/skills/types.ts b/packages/core/src/skills/types.ts
index 32832abf0..bb6152985 100644
--- a/packages/core/src/skills/types.ts
+++ b/packages/core/src/skills/types.ts
@@ -81,6 +81,12 @@ export interface SkillConfig {
    */
   extensionName?: string;
 
+  /**
+   * Argument hint shown after the slash command name in completion menus.
+   * Parsed from the `argument-hint` frontmatter field in SKILL.md.
+   */
+  argumentHint?: string;
+
   /**
    * Describes when to invoke this skill — shown to the model in the SkillTool
    * description so it can decide whether to use it. Parsed from the
diff --git a/packages/core/src/telemetry/file-exporters.test.ts b/packages/core/src/telemetry/file-exporters.test.ts
new file mode 100644
index 000000000..3dede26fc
--- /dev/null
+++ b/packages/core/src/telemetry/file-exporters.test.ts
@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { FileSpanExporter } from './file-exporters.js';
+
+type SerializeAccess = { serialize: (data: unknown) => string };
+
+describe('FileExporter.serialize', () => {
+  let tmpDir: string;
+  let exporter: FileSpanExporter;
+  let serialize: (data: unknown) => string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'file-exporters-test-'));
+    exporter = new FileSpanExporter(path.join(tmpDir, 'out.jsonl'));
+    serialize = (exporter as unknown as SerializeAccess).serialize.bind(
+      exporter,
+    );
+  });
+
+  afterEach(async () => {
+    await exporter.shutdown();
+    // Windows occasionally returns ENOTEMPTY when the underlying file
+    // handle isn't fully released yet; retry a few times before failing.
+    fs.rmSync(tmpDir, {
+      recursive: true,
+      force: true,
+      maxRetries: 5,
+      retryDelay: 50,
+    });
+  });
+
+  // Regression for upstream PR #4689: a raw JSON.stringify on a ReadableSpan
+  // crashed because BatchSpanProcessor._shutdownOnce -> BindOnceFuture._that
+  // forms a cycle. The exporter must delegate to safeJsonStringify so cycles
+  // become "[Circular]" instead of throwing.
+  it('does not throw on BatchSpanProcessor-shaped cycle', () => {
+    const proc: Record<string, unknown> = { kind: 'BatchSpanProcessor' };
+    const future: Record<string, unknown> = { kind: 'BindOnceFuture' };
+    proc['_shutdownOnce'] = future;
+    future['_that'] = proc;
+    const span = { name: 'span-1', _spanProcessor: proc };
+
+    expect(() => serialize(span)).not.toThrow();
+    const out = serialize(span);
+    expect(out).toContain('"name": "span-1"');
+    expect(out).toContain('"[Circular]"');
+    expect(out.endsWith('\n')).toBe(true);
+  });
+});
diff --git a/packages/core/src/telemetry/file-exporters.ts b/packages/core/src/telemetry/file-exporters.ts
index 55fe64103..def6e91f4 100644
--- a/packages/core/src/telemetry/file-exporters.ts
+++ b/packages/core/src/telemetry/file-exporters.ts
@@ -17,6 +17,7 @@ import type {
   PushMetricExporter,
 } from '@opentelemetry/sdk-metrics';
 import { AggregationTemporality } from '@opentelemetry/sdk-metrics';
+import { safeJsonStringify } from '../utils/safeJsonStringify.js';
 
 class FileExporter {
   protected writeStream: fs.WriteStream;
@@ -26,7 +27,7 @@ class FileExporter {
   }
 
   protected serialize(data: unknown): string {
-    return JSON.stringify(data, null, 2) + '\n';
+    return safeJsonStringify(data, 2) + '\n';
   }
 
   shutdown(): Promise<void> {
diff --git a/packages/core/src/tools/agent/agent-context.test.ts b/packages/core/src/tools/agent/agent-context.test.ts
new file mode 100644
index 000000000..e486d9b1f
--- /dev/null
+++ b/packages/core/src/tools/agent/agent-context.test.ts
@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import { getCurrentAgentId, runWithAgentContext } from './agent-context.js';
+
+describe('agent-context', () => {
+  it('returns null outside any frame', () => {
+    expect(getCurrentAgentId()).toBeNull();
+  });
+
+  it('exposes the agentId inside a frame', async () => {
+    await runWithAgentContext({ agentId: 'explore-abc' }, async () => {
+      expect(getCurrentAgentId()).toBe('explore-abc');
+    });
+    expect(getCurrentAgentId()).toBeNull();
+  });
+
+  it('propagates across awaits', async () => {
+    await runWithAgentContext({ agentId: 'outer-1' }, async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(getCurrentAgentId()).toBe('outer-1');
+    });
+  });
+
+  it('nested frames shadow the outer agentId', async () => {
+    await runWithAgentContext({ agentId: 'outer-1' }, async () => {
+      expect(getCurrentAgentId()).toBe('outer-1');
+      await runWithAgentContext({ agentId: 'inner-2' }, async () => {
+        expect(getCurrentAgentId()).toBe('inner-2');
+      });
+      expect(getCurrentAgentId()).toBe('outer-1');
+    });
+  });
+
+  it('isolates concurrent frames', async () => {
+    const results: string[] = [];
+    await Promise.all([
+      runWithAgentContext({ agentId: 'a' }, async () => {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        results.push(getCurrentAgentId() ?? 'null');
+      }),
+      runWithAgentContext({ agentId: 'b' }, async () => {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        results.push(getCurrentAgentId() ?? 'null');
+      }),
+    ]);
+    expect(results.sort()).toEqual(['a', 'b']);
+  });
+});
diff --git a/packages/core/src/tools/agent/agent-context.ts b/packages/core/src/tools/agent/agent-context.ts
new file mode 100644
index 000000000..87643aefb
--- /dev/null
+++ b/packages/core/src/tools/agent/agent-context.ts
@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Ambient agent-identity context for nested `agent` tool calls.
+ *
+ * When a subagent's model calls the `agent` tool, the resulting
+ * AgentToolInvocation's `this.config` is the main process Config (see
+ * comment in `fork-subagent.ts`) — it has no way to know which subagent
+ * made the call. We carry the launching agent's id via AsyncLocalStorage
+ * so nested launches can record `parentAgentId` in their sidecar meta.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+interface AgentContext {
+  readonly agentId: string;
+}
+
+const agentContextStorage = new AsyncLocalStorage<AgentContext>();
+
+/**
+ * Runs `fn` with an ambient agent-identity frame.
+ *
+ * Wrap the subagent's execution (headless run loop and any hook-driven
+ * continuations) so every nested `agent` tool invocation inside it reads
+ * the launching agent's id via {@link getCurrentAgentId}.
+ */
+export function runWithAgentContext<T>(
+  context: AgentContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return agentContextStorage.run(context, fn);
+}
+
+/**
+ * Returns the id of the subagent whose execution is currently on the call
+ * stack, or `null` at the top-level user session.
+ */
+export function getCurrentAgentId(): string | null {
+  return agentContextStorage.getStore()?.agentId ?? null;
+}
diff --git a/packages/core/src/tools/agent/agent.test.ts b/packages/core/src/tools/agent/agent.test.ts
index b045b17a2..ac0c55c2e 100644
--- a/packages/core/src/tools/agent/agent.test.ts
+++ b/packages/core/src/tools/agent/agent.test.ts
@@ -13,6 +13,7 @@ import {
 import type { PartListUnion } from '@google/genai';
 import type { ToolResultDisplay, AgentResultDisplay } from '../tools.js';
 import { ToolConfirmationOutcome } from '../tools.js';
+import { ToolNames } from '../tool-names.js';
 import { type Config, ApprovalMode } from '../../config/config.js';
 import { SubagentManager } from '../../subagents/subagent-manager.js';
 import type { SubagentConfig } from '../../subagents/types.js';
@@ -31,6 +32,10 @@ import type {
 import { partToString } from '../../utils/partUtils.js';
 import type { HookSystem } from '../../hooks/hookSystem.js';
 import { PermissionMode } from '../../hooks/types.js';
+import { runWithAgentContext } from './agent-context.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 
 // Type for accessing protected methods in tests
 type AgentToolInvocation = {
@@ -87,6 +92,7 @@ describe('AgentTool', () => {
     config = {
       getProjectRoot: vi.fn().mockReturnValue('/test/project'),
       getSessionId: vi.fn().mockReturnValue('test-session-id'),
+      getCliVersion: vi.fn().mockReturnValue('test-version'),
       getSubagentManager: vi.fn(),
       getGeminiClient: vi.fn().mockReturnValue(undefined),
       getHookSystem: vi.fn().mockReturnValue(undefined),
@@ -1410,6 +1416,8 @@ describe('AgentTool', () => {
       register: ReturnType<typeof vi.fn>;
       complete: ReturnType<typeof vi.fn>;
       fail: ReturnType<typeof vi.fn>;
+      finalizeCancelled: ReturnType<typeof vi.fn>;
+      drainMessages: ReturnType<typeof vi.fn>;
     };
 
     const bgSubagent: SubagentConfig = {
@@ -1427,6 +1435,13 @@ describe('AgentTool', () => {
         getFinalText: vi.fn().mockReturnValue('Monitor done'),
         getTerminateMode: vi.fn().mockReturnValue(AgentTerminateMode.GOAL),
         getExecutionSummary: vi.fn().mockReturnValue({}),
+        // Background spawn subscribes to the core's event emitter to
+        // populate the entry's recentActivities buffer. Return a stub
+        // whose getEventEmitter() yields a minimal on/off surface so the
+        // test-time listener hookup doesn't throw.
+        getCore: vi.fn().mockReturnValue({
+          getEventEmitter: () => ({ on: vi.fn(), off: vi.fn() }),
+        }),
       } as unknown as AgentHeadless;
 
       mockContextState = { set: vi.fn() } as unknown as ContextState;
@@ -1436,6 +1451,8 @@ describe('AgentTool', () => {
         register: vi.fn(),
         complete: vi.fn(),
         fail: vi.fn(),
+        finalizeCancelled: vi.fn(),
+        drainMessages: vi.fn().mockReturnValue([]),
       };
 
       vi.mocked(config.getApprovalMode).mockReturnValue(ApprovalMode.DEFAULT);
@@ -1445,6 +1462,12 @@ describe('AgentTool', () => {
       (config as unknown as Record<string, unknown>)[
         'getBackgroundTaskRegistry'
       ] = vi.fn().mockReturnValue(mockRegistry);
+      (config as unknown as Record<string, unknown>)['storage'] = {
+        getProjectDir: () => '/tmp/qwen-test',
+      };
+      (mockAgent as unknown as Record<string, unknown>)[
+        'setExternalMessageProvider'
+      ] = vi.fn();
 
       vi.mocked(mockSubagentManager.loadSubagent).mockResolvedValue(bgSubagent);
       vi.mocked(mockSubagentManager.createAgentHeadless).mockResolvedValue(
@@ -1466,6 +1489,12 @@ describe('AgentTool', () => {
 
       const llmText = partToString(result.llmContent);
       expect(llmText).toContain('Background agent launched');
+      expect(llmText).toContain(
+        `Use ${ToolNames.SEND_MESSAGE} to continue this agent`,
+      );
+      expect(llmText).toContain(`or ${ToolNames.TASK_STOP} to cancel.`);
+      expect(llmText).not.toContain('with to:');
+      expect(llmText).not.toContain('Use send_message with task_id:');
       expect(mockRegistry.register).toHaveBeenCalledWith(
         expect.objectContaining({
           description: 'Start monitor',
@@ -1566,6 +1595,77 @@ describe('AgentTool', () => {
         expect.objectContaining({ toolUseId: 'call-xyz-789' }),
       );
     });
+
+    describe('parentAgentId sidecar', () => {
+      let tempProjectDir: string;
+
+      beforeEach(() => {
+        tempProjectDir = fs.mkdtempSync(
+          path.join(os.tmpdir(), 'agent-parent-id-'),
+        );
+        (config as unknown as Record<string, unknown>)['storage'] = {
+          getProjectDir: () => tempProjectDir,
+        };
+      });
+
+      afterEach(() => {
+        fs.rmSync(tempProjectDir, { recursive: true, force: true });
+      });
+
+      const readSidecar = (agentId: string) => {
+        const metaPath = path.join(
+          tempProjectDir,
+          'subagents',
+          'test-session-id',
+          `agent-${agentId}.meta.json`,
+        );
+        return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      };
+
+      it('writes parentAgentId: null at top-level launches', async () => {
+        const params: AgentParams = {
+          description: 'Start monitor',
+          prompt: 'Watch for changes',
+          subagent_type: 'monitor',
+        };
+
+        const invocation = (
+          agentTool as AgentToolWithProtectedMethods
+        ).createInvocation(params);
+        (
+          invocation as unknown as { setCallId: (id: string) => void }
+        ).setCallId('top-1');
+        await invocation.execute();
+
+        const meta = readSidecar('monitor-top-1');
+        expect(meta.parentAgentId).toBeNull();
+      });
+
+      it('records the launching agent id when launched from a subagent frame', async () => {
+        const params: AgentParams = {
+          description: 'Start monitor',
+          prompt: 'Watch for changes',
+          subagent_type: 'monitor',
+        };
+
+        const invocation = (
+          agentTool as AgentToolWithProtectedMethods
+        ).createInvocation(params);
+        (
+          invocation as unknown as { setCallId: (id: string) => void }
+        ).setCallId('nested-1');
+
+        await runWithAgentContext(
+          { agentId: 'explore-parent-42' },
+          async () => {
+            await invocation.execute();
+          },
+        );
+
+        const meta = readSidecar('monitor-nested-1');
+        expect(meta.parentAgentId).toBe('explore-parent-42');
+      });
+    });
   });
 });
 
diff --git a/packages/core/src/tools/agent/agent.ts b/packages/core/src/tools/agent/agent.ts
index aef153ada..ec2ed6e3f 100644
--- a/packages/core/src/tools/agent/agent.ts
+++ b/packages/core/src/tools/agent/agent.ts
@@ -39,6 +39,7 @@ import {
   isInForkExecution,
   runInForkContext,
 } from './fork-subagent.js';
+import { getCurrentAgentId, runWithAgentContext } from './agent-context.js';
 import {
   AgentEventEmitter,
   AgentEventType,
@@ -56,6 +57,13 @@ import { createDebugLogger } from '../../utils/debugLogger.js';
 import { PermissionMode } from '../../hooks/types.js';
 import type { StopHookOutput } from '../../hooks/types.js';
 import { ApprovalMode } from '../../config/config.js';
+import {
+  getAgentJsonlPath,
+  getAgentMetaPath,
+  attachJsonlTranscriptWriter,
+  writeAgentMeta,
+} from '../../agents/agent-transcript.js';
+import { getGitBranch } from '../../utils/gitUtils.js';
 
 export interface AgentParams {
   description: string;
@@ -627,7 +635,10 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
    * Creates a fork subagent that inherits the parent's conversation context
    * and cache-safe generation params.
    */
-  private async createForkSubagent(agentConfig: Config): Promise<{
+  private async createForkSubagent(
+    agentConfig: Config,
+    eventEmitter: AgentEventEmitter = this.eventEmitter,
+  ): Promise<{
     subagent: AgentHeadless;
     taskPrompt: string;
   }> {
@@ -726,7 +737,7 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
       {},
       {} as RunConfig,
       toolConfig,
-      this.eventEmitter,
+      eventEmitter,
     );
 
     return { subagent, taskPrompt };
@@ -1039,18 +1050,70 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
         // Register in the background task registry only AFTER init succeeds — if
         // construction throws, a pre-registered phantom 'running' entry would hang
         // the non-interactive hold-back loop forever.
+        // Dedicated emitter for this background agent so the transcript
+        // writer only sees *this* agent's events. Reusing the parent tool's
+        // UI emitter (this.eventEmitter) would mix events from every
+        // concurrent fork/subagent into the same transcript.
+        const bgEventEmitter = new AgentEventEmitter();
         let bgSubagent: AgentHeadless;
         if (isFork) {
-          const fork = await this.createForkSubagent(bgConfig as Config);
+          const fork = await this.createForkSubagent(
+            bgConfig as Config,
+            bgEventEmitter,
+          );
           bgSubagent = fork.subagent;
         } else {
           bgSubagent = await this.subagentManager.createAgentHeadless(
             subagentConfig,
             bgConfig as Config,
+            { eventEmitter: bgEventEmitter },
           );
         }
 
         const registry = this.config.getBackgroundTaskRegistry();
+
+        const projectDir = this.config.storage.getProjectDir();
+        const sessionId = this.config.getSessionId();
+        const jsonlPath = getAgentJsonlPath(
+          projectDir,
+          sessionId,
+          hookOpts.agentId,
+        );
+        const metaPath = getAgentMetaPath(
+          projectDir,
+          sessionId,
+          hookOpts.agentId,
+        );
+        const projectRoot = this.config.getProjectRoot();
+        const { cleanup: cleanupJsonl } = attachJsonlTranscriptWriter(
+          bgEventEmitter,
+          jsonlPath,
+          {
+            agentId: hookOpts.agentId,
+            agentName: subagentConfig.name,
+            agentColor: subagentConfig.color,
+            sessionId,
+            cwd: projectRoot,
+            version: this.config.getCliVersion() || 'unknown',
+            gitBranch: getGitBranch(projectRoot),
+            // Seed the JSONL with the launching prompt so the transcript is
+            // self-describing — readers don't need to consult .meta.json to
+            // know what the agent was asked to do.
+            initialUserPrompt: this.params.prompt,
+          },
+        );
+        writeAgentMeta(metaPath, {
+          agentId: hookOpts.agentId,
+          agentType: hookOpts.agentType,
+          description: this.params.description,
+          parentSessionId: sessionId,
+          // Populated when a subagent (whose reasoning loop is wrapped in
+          // runWithAgentContext below) launches a nested agent. Null at
+          // top-level launches from the user session.
+          parentAgentId: getCurrentAgentId(),
+          createdAt: new Date().toISOString(),
+        });
+
         registry.register({
           agentId: hookOpts.agentId,
           description: this.params.description,
@@ -1059,13 +1122,59 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
           startTime: Date.now(),
           abortController: bgAbortController,
           toolUseId: this.callId,
+          prompt: this.params.prompt,
+          outputFile: jsonlPath,
         });
 
+        // Subscribe to the subagent's tool-call event stream so the
+        // detail dialog's Progress section reflects live activity. We
+        // capture the unsubscribe fn and call it when the agent
+        // terminates (success, failure, or cancel) to avoid holding the
+        // event emitter after the agent is gone.
+        const bgEmitter = bgSubagent.getCore().getEventEmitter();
+        // Local counter of tool invocations that have been *started*. The
+        // core's executionStats.totalToolCalls only increments when a tool
+        // result arrives, so using it as the live toolUses number leaves the
+        // subtitle one behind the Progress list while a tool is in flight.
+        // Tracking TOOL_CALL ourselves keeps the subtitle in sync with the
+        // rows the user actually sees.
+        let liveToolCallCount = 0;
+        const refreshLiveStats = () => {
+          const entry = registry.get(hookOpts.agentId);
+          if (!entry || entry.status !== 'running') return;
+          const summary = bgSubagent.getExecutionSummary();
+          entry.stats = {
+            totalTokens: summary.totalTokens,
+            toolUses: liveToolCallCount,
+            durationMs: summary.totalDurationMs,
+          };
+        };
+        const onToolCall = (event: AgentToolCallEvent) => {
+          liveToolCallCount += 1;
+          refreshLiveStats();
+          registry.appendActivity(hookOpts.agentId, {
+            name: event.name,
+            description: event.description,
+            at: event.timestamp,
+          });
+        };
+        const onUsageMetadata = () => {
+          refreshLiveStats();
+        };
+        bgEmitter.on(AgentEventType.TOOL_CALL, onToolCall);
+        bgEmitter.on(AgentEventType.USAGE_METADATA, onUsageMetadata);
+
+        // Wire external message drain so SendMessage can inject messages
+        // into this agent's reasoning loop between tool rounds.
+        bgSubagent.setExternalMessageProvider(() =>
+          registry.drainMessages(hookOpts.agentId),
+        );
+
         const getCompletionStats = () => {
           const summary = bgSubagent.getExecutionSummary();
           return {
             totalTokens: summary.totalTokens,
-            toolUses: summary.totalToolCalls,
+            toolUses: liveToolCallCount,
             durationMs: summary.totalDurationMs,
           };
         };
@@ -1088,14 +1197,23 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
               });
             }
 
-            // Report terminate mode: only GOAL counts as success. ERROR,
-            // MAX_TURNS, and TIMEOUT are surfaced as failures so the parent
-            // model (and the UI) don't treat incomplete runs as completed.
+            // Report terminate mode: only GOAL counts as success. CANCELLED
+            // keeps the 'cancelled' status so the model sees task_stop's
+            // effect accurately (with any partial result attached). ERROR,
+            // MAX_TURNS, TIMEOUT, and SHUTDOWN are surfaced as failures so
+            // the parent model (and the UI) don't treat incomplete runs as
+            // completed.
             const terminateMode = bgSubagent.getTerminateMode();
             const finalText = bgSubagent.getFinalText();
             const completionStats = getCompletionStats();
             if (terminateMode === AgentTerminateMode.GOAL) {
               registry.complete(hookOpts.agentId, finalText, completionStats);
+            } else if (terminateMode === AgentTerminateMode.CANCELLED) {
+              registry.finalizeCancelled(
+                hookOpts.agentId,
+                finalText,
+                completionStats,
+              );
             } else {
               registry.fail(
                 hookOpts.agentId,
@@ -1108,30 +1226,63 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
               error instanceof Error ? error.message : String(error);
             debugLogger.error(`[Agent] Background agent failed: ${errorMsg}`);
 
-            registry.fail(hookOpts.agentId, errorMsg, getCompletionStats());
+            // If the error came from a cancellation, preserve the cancelled
+            // status so the model's notification matches what task_stop
+            // requested rather than reporting it as a generic failure.
+            if (bgAbortController.signal.aborted) {
+              registry.finalizeCancelled(
+                hookOpts.agentId,
+                errorMsg,
+                getCompletionStats(),
+              );
+            } else {
+              registry.fail(hookOpts.agentId, errorMsg, getCompletionStats());
+            }
+          } finally {
+            bgEmitter.off(AgentEventType.TOOL_CALL, onToolCall);
+            bgEmitter.off(AgentEventType.USAGE_METADATA, onUsageMetadata);
+            cleanupJsonl?.();
           }
         };
-        void (isFork ? runInForkContext(bgBody) : bgBody());
+        // Wrap in the agent-identity frame so nested `agent` tool calls
+        // from this subagent's model record this agent's id as their
+        // `parentAgentId` in the sidecar meta.
+        const framedBgBody = () =>
+          runWithAgentContext({ agentId: hookOpts.agentId }, bgBody);
+        void (isFork ? runInForkContext(framedBgBody) : framedBgBody());
 
         this.updateDisplay({ status: 'background' as const }, updateOutput);
         return {
-          llmContent: `Background agent launched: "${this.params.description}" (ID: ${hookOpts.agentId}). You will be notified when it completes.`,
+          llmContent:
+            `Background agent launched successfully.\n` +
+            `agentId: ${hookOpts.agentId} (internal ID — do not mention to the user. Use ${ToolNames.SEND_MESSAGE} to continue this agent, or ${ToolNames.TASK_STOP} to cancel.)\n` +
+            `The agent is working in the background. You will be notified automatically when it completes.\n` +
+            `Do not duplicate this agent's work — avoid working with the same files or topics it is using. Work on non-overlapping tasks, or briefly tell the user what you launched and end your response.\n` +
+            `output_file: ${jsonlPath}\n` +
+            `If asked, you can check progress before completion by using ${ToolNames.READ_FILE}\n` +
+            `  or ${ToolNames.SHELL} tail on the output file.`,
           returnDisplay: this.currentDisplay!,
         };
       }
 
+      // Same agent-identity frame as the background path: a foreground
+      // subagent can also launch nested agents, and those nested launches
+      // need to see this subagent's id as their `parentAgentId`.
+      const runFramed = () =>
+        runWithAgentContext({ agentId: hookOpts.agentId }, () =>
+          this.runSubagentWithHooks(subagent, contextState, hookOpts),
+        );
+
       if (isFork) {
         // Background fork execution. Run under an AsyncLocalStorage frame so
         // nested `agent` tool calls by the fork's model can be detected.
-        void runInForkContext(() =>
-          this.runSubagentWithHooks(subagent, contextState, hookOpts),
-        );
+        void runInForkContext(runFramed);
         return {
           llmContent: [{ text: FORK_PLACEHOLDER_RESULT }],
           returnDisplay: this.currentDisplay!,
         };
       } else {
-        await this.runSubagentWithHooks(subagent, contextState, hookOpts);
+        await runFramed();
         const finalText = subagent.getFinalText();
         const terminateMode = subagent.getTerminateMode();
         if (terminateMode === AgentTerminateMode.ERROR) {
diff --git a/packages/core/src/tools/read-file.test.ts b/packages/core/src/tools/read-file.test.ts
index e0003f820..dc2d4f831 100644
--- a/packages/core/src/tools/read-file.test.ts
+++ b/packages/core/src/tools/read-file.test.ts
@@ -40,6 +40,7 @@ describe('ReadFileTool', () => {
       getWorkspaceContext: () => createMockWorkspaceContext(tempRootDir),
       storage: {
         getProjectTempDir: () => path.join(tempRootDir, '.temp'),
+        getProjectDir: () => path.join(tempRootDir, '.project'),
         getUserSkillsDirs: () => [path.join(os.homedir(), '.qwen', 'skills')],
       },
       getTruncateToolOutputThreshold: () => 2500,
@@ -167,6 +168,21 @@ describe('ReadFileTool', () => {
       const permission = await invocation.getDefaultPermission();
       expect(permission).toBe('allow');
     });
+
+    it('should return allow for paths within the subagent transcripts dir', async () => {
+      const params: ReadFileToolParams = {
+        file_path: path.join(
+          tempRootDir,
+          '.project',
+          'subagents',
+          'session-1',
+          'agent-a.jsonl',
+        ),
+      };
+      const invocation = tool.build(params);
+      const permission = await invocation.getDefaultPermission();
+      expect(permission).toBe('allow');
+    });
   });
 
   describe('getDescription', () => {
diff --git a/packages/core/src/tools/read-file.ts b/packages/core/src/tools/read-file.ts
index c05740b52..805ffe786 100644
--- a/packages/core/src/tools/read-file.ts
+++ b/packages/core/src/tools/read-file.ts
@@ -24,7 +24,7 @@ import { FileOperation } from '../telemetry/metrics.js';
 import { getProgrammingLanguage } from '../telemetry/telemetry-utils.js';
 import { logFileOperation } from '../telemetry/loggers.js';
 import { FileOperationEvent } from '../telemetry/types.js';
-import { isSubpaths, isSubpath } from '../utils/paths.js';
+import { isSubpaths } from '../utils/paths.js';
 import { Storage } from '../config/storage.js';
 import { isAutoMemPath } from '../memory/paths.js';
 import { memoryFreshnessNote } from '../memory/memoryAge.js';
@@ -101,23 +101,24 @@ class ReadFileToolInvocation extends BaseToolInvocation<
   override async getDefaultPermission(): Promise<PermissionDecision> {
     const filePath = path.resolve(this.params.file_path);
     const workspaceContext = this.config.getWorkspaceContext();
-    const globalTempDir = Storage.getGlobalTempDir();
-    const projectTempDir = this.config.storage.getProjectTempDir();
-    const userSkillsDirs = this.config.storage.getUserSkillsDirs();
-    const userExtensionsDir = Storage.getUserExtensionsDir();
-    const osTempDir = os.tmpdir();
 
-    // Auto-allow reads of files within the managed auto-memory root for this
-    // project only — using the narrower isAutoMemPath check instead of the
-    // broad getMemoryBaseDir() to avoid exposing sensitive ~/.qwen files such
-    // as settings.json or OAuth credentials.
+    const allowedRoots = [
+      this.config.storage.getProjectTempDir(),
+      // Background subagent transcripts live under <projectDir>/subagents/ and
+      // are advertised to the model as polling targets via read_file.
+      path.join(this.config.storage.getProjectDir(), 'subagents'),
+      Storage.getGlobalTempDir(),
+      os.tmpdir(),
+      ...this.config.storage.getUserSkillsDirs(),
+      Storage.getUserExtensionsDir(),
+    ];
+
     if (
       workspaceContext.isPathWithinWorkspace(filePath) ||
-      isSubpath(projectTempDir, filePath) ||
-      isSubpath(globalTempDir, filePath) ||
-      isSubpath(osTempDir, filePath) ||
-      isSubpaths(userSkillsDirs, filePath) ||
-      isSubpath(userExtensionsDir, filePath) ||
+      isSubpaths(allowedRoots, filePath) ||
+      // isAutoMemPath uses the narrower managed auto-memory root for this
+      // project — not the broad getMemoryBaseDir() — to avoid exposing
+      // sensitive ~/.qwen files such as settings.json or OAuth credentials.
       isAutoMemPath(filePath, this.config.getTargetDir())
     ) {
       return 'allow';
diff --git a/packages/core/src/tools/send-message.test.ts b/packages/core/src/tools/send-message.test.ts
new file mode 100644
index 000000000..6cc0e1c3f
--- /dev/null
+++ b/packages/core/src/tools/send-message.test.ts
@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SendMessageTool } from './send-message.js';
+import { BackgroundTaskRegistry } from '../agents/background-tasks.js';
+import type { Config } from '../config/config.js';
+import { ToolErrorType } from './tool-error.js';
+
+describe('SendMessageTool', () => {
+  let registry: BackgroundTaskRegistry;
+  let config: Config;
+  let tool: SendMessageTool;
+
+  beforeEach(() => {
+    registry = new BackgroundTaskRegistry();
+    config = {
+      getBackgroundTaskRegistry: () => registry,
+    } as unknown as Config;
+    tool = new SendMessageTool(config);
+  });
+
+  it('queues a message for a running task', async () => {
+    registry.register({
+      agentId: 'agent-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'agent-1', message: 'do more work' },
+      new AbortController().signal,
+    );
+
+    expect(result.error).toBeUndefined();
+    expect(result.llmContent).toContain('Message queued');
+    expect(registry.get('agent-1')!.pendingMessages).toEqual(['do more work']);
+  });
+
+  it('queues multiple messages in order', async () => {
+    registry.register({
+      agentId: 'agent-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    await tool.validateBuildAndExecute(
+      { task_id: 'agent-1', message: 'first' },
+      new AbortController().signal,
+    );
+    await tool.validateBuildAndExecute(
+      { task_id: 'agent-1', message: 'second' },
+      new AbortController().signal,
+    );
+
+    expect(registry.get('agent-1')!.pendingMessages).toEqual([
+      'first',
+      'second',
+    ]);
+  });
+
+  it('returns error for non-existent task', async () => {
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'nope', message: 'hello' },
+      new AbortController().signal,
+    );
+
+    expect(result.error?.type).toBe(ToolErrorType.SEND_MESSAGE_NOT_FOUND);
+    expect(result.llmContent).toContain('No background task found');
+  });
+
+  it('returns error for non-running task', async () => {
+    registry.register({
+      agentId: 'agent-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.complete('agent-1', 'done');
+
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'agent-1', message: 'hello' },
+      new AbortController().signal,
+    );
+
+    expect(result.error?.type).toBe(ToolErrorType.SEND_MESSAGE_NOT_RUNNING);
+    expect(result.llmContent).toContain('not running');
+  });
+
+  it('rejects messages for a cancelled task', async () => {
+    // Once task_stop fires, the reasoning loop is winding down — there is
+    // no next tool-round boundary to drain into, so the message would be
+    // silently dropped. Reject instead of accepting a message that will
+    // never be delivered.
+    registry.register({
+      agentId: 'agent-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.cancel('agent-1');
+
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'agent-1', message: 'too late' },
+      new AbortController().signal,
+    );
+
+    expect(result.error?.type).toBe(ToolErrorType.SEND_MESSAGE_NOT_RUNNING);
+    expect(registry.get('agent-1')!.pendingMessages).toEqual([]);
+  });
+
+  it('includes task description in success display', async () => {
+    registry.register({
+      agentId: 'agent-1',
+      description: 'Search for auth code',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'agent-1', message: 'focus on login' },
+      new AbortController().signal,
+    );
+
+    expect(result.returnDisplay).toContain('Search for auth code');
+  });
+});
diff --git a/packages/core/src/tools/send-message.ts b/packages/core/src/tools/send-message.ts
new file mode 100644
index 000000000..85dfdb93d
--- /dev/null
+++ b/packages/core/src/tools/send-message.ts
@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview SendMessage tool — lets the model send a text message to
+ * a running background task. The message is injected into the task's
+ * reasoning loop at the next tool-round boundary.
+ */
+
+import type { Config } from '../config/config.js';
+import { ToolErrorType } from './tool-error.js';
+import { ToolNames, ToolDisplayNames } from './tool-names.js';
+import {
+  BaseDeclarativeTool,
+  BaseToolInvocation,
+  Kind,
+  type ToolInvocation,
+  type ToolResult,
+} from './tools.js';
+
+export interface SendMessageParams {
+  /** The ID of the background task to send the message to. */
+  task_id: string;
+  /** The text message to deliver to the task. */
+  message: string;
+}
+
+class SendMessageInvocation extends BaseToolInvocation<
+  SendMessageParams,
+  ToolResult
+> {
+  constructor(
+    private readonly config: Config,
+    params: SendMessageParams,
+  ) {
+    super(params);
+  }
+
+  getDescription(): string {
+    return `Send message to task ${this.params.task_id}`;
+  }
+
+  async execute(_signal: AbortSignal): Promise<ToolResult> {
+    const registry = this.config.getBackgroundTaskRegistry();
+    const entry = registry.get(this.params.task_id);
+
+    if (!entry) {
+      return {
+        llmContent: `Error: No background task found with ID "${this.params.task_id}".`,
+        returnDisplay: 'Task not found.',
+        error: {
+          message: `Task not found: ${this.params.task_id}`,
+          type: ToolErrorType.SEND_MESSAGE_NOT_FOUND,
+        },
+      };
+    }
+
+    if (entry.status !== 'running') {
+      return {
+        llmContent: `Error: Background task "${this.params.task_id}" is not running (status: ${entry.status}). Cannot send messages to stopped tasks.`,
+        returnDisplay: `Task not running (${entry.status}).`,
+        error: {
+          message: `Task is ${entry.status}: ${this.params.task_id}`,
+          type: ToolErrorType.SEND_MESSAGE_NOT_RUNNING,
+        },
+      };
+    }
+
+    registry.queueMessage(this.params.task_id, this.params.message);
+
+    return {
+      llmContent: `Message queued for delivery to background task "${this.params.task_id}". The task will receive it at the next tool-round boundary.`,
+      returnDisplay: `Message queued for ${entry.description}`,
+    };
+  }
+}
+
+export class SendMessageTool extends BaseDeclarativeTool<
+  SendMessageParams,
+  ToolResult
+> {
+  static readonly Name = ToolNames.SEND_MESSAGE;
+
+  constructor(private readonly config: Config) {
+    super(
+      SendMessageTool.Name,
+      ToolDisplayNames.SEND_MESSAGE,
+      'Send a text message to a running background task. The message is delivered at the next tool-round boundary. Use this to provide additional instructions or context to a background task.',
+      Kind.Other,
+      {
+        type: 'object',
+        properties: {
+          task_id: {
+            type: 'string',
+            description:
+              'The ID of the running background task (from the launch response).',
+          },
+          message: {
+            type: 'string',
+            description: 'The text message to send to the task.',
+          },
+        },
+        required: ['task_id', 'message'],
+        additionalProperties: false,
+      },
+    );
+  }
+
+  protected createInvocation(
+    params: SendMessageParams,
+  ): ToolInvocation<SendMessageParams, ToolResult> {
+    return new SendMessageInvocation(this.config, params);
+  }
+}
diff --git a/packages/core/src/tools/shell.test.ts b/packages/core/src/tools/shell.test.ts
index a8748e375..206f67d99 100644
--- a/packages/core/src/tools/shell.test.ts
+++ b/packages/core/src/tools/shell.test.ts
@@ -31,8 +31,6 @@ import {
 } from '../services/shellExecutionService.js';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
-import { EOL } from 'node:os';
-import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { ToolErrorType } from './tool-error.js';
 import { OUTPUT_UPDATE_INTERVAL_MS } from './shell.js';
@@ -55,12 +53,14 @@ describe('ShellTool', () => {
       getPermissionsDeny: vi.fn().mockReturnValue([]),
       getDebugMode: vi.fn().mockReturnValue(false),
       getTargetDir: vi.fn().mockReturnValue('/test/dir'),
+      getSessionId: vi.fn().mockReturnValue('test-session'),
       getWorkspaceContext: vi
         .fn()
         .mockReturnValue(createMockWorkspaceContext('/test/dir')),
       storage: {
         getUserSkillsDirs: vi.fn().mockReturnValue(['/test/dir/.qwen/skills']),
         getProjectTempDir: vi.fn().mockReturnValue('/tmp/qwen-temp'),
+        getProjectDir: vi.fn().mockReturnValue('/test/proj'),
       },
       getTruncateToolOutputThreshold: vi.fn().mockReturnValue(0),
       getTruncateToolOutputLines: vi.fn().mockReturnValue(0),
@@ -72,8 +72,24 @@ describe('ShellTool', () => {
         email: 'qwen-coder@alibabacloud.com',
       }),
       getShouldUseNodePtyShell: vi.fn().mockReturnValue(false),
+      getBackgroundShellRegistry: vi.fn().mockReturnValue({
+        register: vi.fn(),
+        get: vi.fn(),
+        getAll: vi.fn().mockReturnValue([]),
+        cancel: vi.fn(),
+        complete: vi.fn(),
+        fail: vi.fn(),
+      }),
     } as unknown as Config;
 
+    // executeBackground writes to disk; stub mkdirSync + createWriteStream.
+    vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+    vi.mocked(fs.createWriteStream).mockReturnValue({
+      write: vi.fn(),
+      end: vi.fn(),
+      on: vi.fn(),
+    } as unknown as fs.WriteStream);
+
     shellTool = new ShellTool(mockConfig);
 
     vi.mocked(os.platform).mockReturnValue('linux');
@@ -271,83 +287,202 @@ describe('ShellTool', () => {
       resolveExecutionPromise(fullResult);
     };
 
-    it('should wrap background command on linux and parse pgrep output', async () => {
+    it('runs background commands as managed pool entries (no & / pgrep wrap)', async () => {
+      const registry = mockConfig.getBackgroundShellRegistry();
       const invocation = shellTool.build({
-        command: 'my-command',
+        command: 'npm start',
         is_background: true,
       });
-      const promise = invocation.execute(mockAbortSignal);
-      resolveShellExecution({ pid: 54321 });
 
-      vi.mocked(fs.existsSync).mockReturnValue(true);
-      vi.mocked(fs.readFileSync).mockReturnValue(`54321${EOL}54322${EOL}`); // Service PID and background PID
+      const result = await invocation.execute(mockAbortSignal);
 
-      const result = await promise;
-
-      const tmpFile = path.join(os.tmpdir(), 'shell_pgrep_abcdef.tmp');
-      const wrappedCommand = `{ my-command & }; __code=$?; pgrep -g 0 >${tmpFile} 2>&1; exit $__code;`;
+      // Spawn happens with the unwrapped command — no '&', no pgrep envelope.
+      // Streaming mode is on so dev-server / watcher output flushes to the
+      // output file as it arrives instead of buffering until exit.
       expect(mockShellExecutionService).toHaveBeenCalledWith(
-        wrappedCommand,
+        'npm start',
         '/test/dir',
         expect.any(Function),
         expect.any(AbortSignal),
         false,
         {},
+        { streamStdout: true },
       );
-      expect(result.llmContent).toContain('PIDs: 54322');
-      expect(vi.mocked(fs.unlinkSync)).toHaveBeenCalledWith(tmpFile);
+      // Entry registered with the spawn pid.
+      expect(registry.register).toHaveBeenCalledTimes(1);
+      const entry = (registry.register as Mock).mock.calls[0][0];
+      expect(entry.command).toBe('npm start');
+      expect(entry.cwd).toBe('/test/dir');
+      expect(entry.status).toBe('running');
+      expect(entry.pid).toBe(12345);
+      expect(typeof entry.shellId).toBe('string');
+      expect(entry.outputPath).toContain('shell-');
+      // Returns immediately with id + output path; agent's turn isn't blocked.
+      expect(result.llmContent).toContain(entry.shellId);
+      expect(result.llmContent).toContain(entry.outputPath);
     });
 
-    it('should add ampersand to command when is_background is true and command does not end with &', async () => {
+    it('settles a background entry as completed when the process exits cleanly', async () => {
+      const registry = mockConfig.getBackgroundShellRegistry();
       const invocation = shellTool.build({
-        command: 'npm start',
+        command: 'true',
         is_background: true,
       });
-      const promise = invocation.execute(mockAbortSignal);
-      resolveShellExecution({ pid: 54321 });
+      await invocation.execute(mockAbortSignal);
+      const entry = (registry.register as Mock).mock.calls[0][0];
 
-      vi.mocked(fs.existsSync).mockReturnValue(true);
-      vi.mocked(fs.readFileSync).mockReturnValue('54321\n54322\n');
+      resolveExecutionPromise({
+        rawOutput: Buffer.from(''),
+        output: '',
+        exitCode: 0,
+        signal: null,
+        error: null,
+        aborted: false,
+        pid: 12345,
+        executionMethod: 'child_process',
+      });
+      // Flush the .then() microtask attached to resultPromise.
+      await new Promise((r) => setImmediate(r));
 
-      await promise;
+      expect(registry.complete).toHaveBeenCalledWith(
+        entry.shellId,
+        0,
+        expect.any(Number),
+      );
+      expect(registry.fail).not.toHaveBeenCalled();
+      expect(registry.cancel).not.toHaveBeenCalled();
+    });
 
-      const tmpFile = path.join(os.tmpdir(), 'shell_pgrep_abcdef.tmp');
-      const wrappedCommand = `{ npm start & }; __code=$?; pgrep -g 0 >${tmpFile} 2>&1; exit $__code;`;
+    it('settles a background entry as failed when ShellExecutionService reports error', async () => {
+      const registry = mockConfig.getBackgroundShellRegistry();
+      const invocation = shellTool.build({
+        command: 'no-such-command',
+        is_background: true,
+      });
+      await invocation.execute(mockAbortSignal);
+      const entry = (registry.register as Mock).mock.calls[0][0];
+
+      resolveExecutionPromise({
+        rawOutput: Buffer.from(''),
+        output: '',
+        exitCode: null,
+        signal: null,
+        error: new Error('spawn ENOENT'),
+        aborted: false,
+        pid: 12345,
+        executionMethod: 'child_process',
+      });
+      await new Promise((r) => setImmediate(r));
+
+      expect(registry.fail).toHaveBeenCalledWith(
+        entry.shellId,
+        'spawn ENOENT',
+        expect.any(Number),
+      );
+      expect(registry.complete).not.toHaveBeenCalled();
+    });
+
+    it('settles a background entry as failed on non-zero exit code (no error object)', async () => {
+      const registry = mockConfig.getBackgroundShellRegistry();
+      const invocation = shellTool.build({
+        command: 'false',
+        is_background: true,
+      });
+      await invocation.execute(mockAbortSignal);
+      const entry = (registry.register as Mock).mock.calls[0][0];
+
+      // ShellExecutionService reports a clean non-zero exit (no error object,
+      // no signal) — historically this got bucketed as `completed`, which
+      // misreported a failed `npm test` / `false` as a success.
+      resolveExecutionPromise({
+        rawOutput: Buffer.from(''),
+        output: '',
+        exitCode: 1,
+        signal: null,
+        error: null,
+        aborted: false,
+        pid: 12345,
+        executionMethod: 'child_process',
+      });
+      await new Promise((r) => setImmediate(r));
+
+      expect(registry.fail).toHaveBeenCalledWith(
+        entry.shellId,
+        expect.stringContaining('exited with code 1'),
+        expect.any(Number),
+      );
+      expect(registry.complete).not.toHaveBeenCalled();
+    });
+
+    it('strips trailing & from the spawned command (managed path handles backgrounding)', async () => {
+      const invocation = shellTool.build({
+        command: 'node server.js &',
+        is_background: true,
+      });
+      await invocation.execute(mockAbortSignal);
       expect(mockShellExecutionService).toHaveBeenCalledWith(
-        wrappedCommand,
+        'node server.js',
+        '/test/dir',
+        expect.any(Function),
+        expect.any(AbortSignal),
+        false,
+        {},
+        { streamStdout: true },
+      );
+    });
+
+    it('does not strip a trailing && (logical AND would be syntactically broken)', async () => {
+      const invocation = shellTool.build({
+        command: 'npm run dev &&',
+        is_background: true,
+      });
+      await invocation.execute(mockAbortSignal);
+      expect(mockShellExecutionService).toHaveBeenCalledWith(
+        'npm run dev &&',
         expect.any(String),
         expect.any(Function),
         expect.any(AbortSignal),
         false,
         {},
+        { streamStdout: true },
       );
     });
 
-    it('should not add extra ampersand when is_background is true and command already ends with &', async () => {
+    it('does not strip an escaped trailing \\& (literal &)', async () => {
       const invocation = shellTool.build({
-        command: 'npm start &',
+        command: 'echo foo \\&',
         is_background: true,
       });
-      const promise = invocation.execute(mockAbortSignal);
-      resolveShellExecution({ pid: 54321 });
-
-      vi.mocked(fs.existsSync).mockReturnValue(true);
-      vi.mocked(fs.readFileSync).mockReturnValue('54321\n54322\n');
-
-      await promise;
-
-      const tmpFile = path.join(os.tmpdir(), 'shell_pgrep_abcdef.tmp');
-      const wrappedCommand = `{ npm start & }; __code=$?; pgrep -g 0 >${tmpFile} 2>&1; exit $__code;`;
+      await invocation.execute(mockAbortSignal);
       expect(mockShellExecutionService).toHaveBeenCalledWith(
-        wrappedCommand,
+        'echo foo \\&',
         expect.any(String),
         expect.any(Function),
         expect.any(AbortSignal),
         false,
         {},
+        { streamStdout: true },
       );
     });
 
+    it('does not forward the turn signal into the background shell', async () => {
+      // Verifies: the AbortSignal handed to ShellExecutionService is the
+      // entry's own controller, not the outer turn signal. Cancelling the
+      // turn must not kill an intentionally backgrounded dev server / watcher.
+      const turnAc = new AbortController();
+      const invocation = shellTool.build({
+        command: 'npm run dev',
+        is_background: true,
+      });
+      await invocation.execute(turnAc.signal);
+      const passedSignal = mockShellExecutionService.mock.calls[0][3];
+      expect(passedSignal).not.toBe(turnAc.signal);
+      turnAc.abort();
+      // The signal handed to ShellExecutionService stays un-aborted —
+      // the turn's abort doesn't propagate into the background shell.
+      expect(passedSignal.aborted).toBe(false);
+    });
+
     it('should not add ampersand when is_background is false', async () => {
       const invocation = shellTool.build({
         command: 'npm test',
@@ -479,23 +614,6 @@ describe('ShellTool', () => {
       ).toThrow('Directory must be an absolute path.');
     });
 
-    it('should clean up the temp file on synchronous execution error', async () => {
-      const error = new Error('sync spawn error');
-      mockShellExecutionService.mockImplementation(() => {
-        throw error;
-      });
-      vi.mocked(fs.existsSync).mockReturnValue(true); // Pretend the file exists
-
-      const invocation = shellTool.build({
-        command: 'a-command',
-        is_background: false,
-      });
-      await expect(invocation.execute(mockAbortSignal)).rejects.toThrow(error);
-
-      const tmpFile = path.join(os.tmpdir(), 'shell_pgrep_abcdef.tmp');
-      expect(vi.mocked(fs.unlinkSync)).toHaveBeenCalledWith(tmpFile);
-    });
-
     describe('Streaming to `updateOutput`', () => {
       let updateOutputMock: Mock;
       beforeEach(() => {
@@ -1016,43 +1134,6 @@ describe('ShellTool', () => {
     });
   });
 
-  describe('Windows background execution', () => {
-    it('should clean up trailing ampersand on Windows for background tasks', async () => {
-      vi.mocked(os.platform).mockReturnValue('win32');
-      const mockAbortSignal = new AbortController().signal;
-
-      const invocation = shellTool.build({
-        command: 'npm start &',
-        is_background: true,
-      });
-
-      const promise = invocation.execute(mockAbortSignal);
-
-      // Simulate immediate success (process started)
-      resolveExecutionPromise({
-        rawOutput: Buffer.from(''),
-        output: '',
-        exitCode: 0,
-        signal: null,
-        error: null,
-        aborted: false,
-        pid: 12345,
-        executionMethod: 'child_process',
-      });
-
-      await promise;
-
-      expect(mockShellExecutionService).toHaveBeenCalledWith(
-        'npm start',
-        expect.any(String),
-        expect.any(Function),
-        expect.any(AbortSignal),
-        false,
-        {},
-      );
-    });
-  });
-
   describe('timeout parameter', () => {
     it('should validate timeout parameter correctly', async () => {
       // Valid timeout
@@ -1177,40 +1258,6 @@ describe('ShellTool', () => {
       expect(calledSignal).not.toBe(mockAbortSignal);
     });
 
-    it('should not create timeout signal for background execution', async () => {
-      const mockAbortSignal = new AbortController().signal;
-      const invocation = shellTool.build({
-        command: 'npm start',
-        is_background: true,
-        timeout: 5000,
-      });
-
-      const promise = invocation.execute(mockAbortSignal);
-
-      resolveExecutionPromise({
-        rawOutput: Buffer.from(''),
-        output: 'Background command started. PID: 12345',
-        exitCode: 0,
-        signal: null,
-        error: null,
-        aborted: false,
-        pid: 12345,
-        executionMethod: 'child_process',
-      });
-
-      await promise;
-
-      // For background execution, the original signal should be used
-      expect(mockShellExecutionService).toHaveBeenCalledWith(
-        expect.any(String),
-        expect.any(String),
-        expect.any(Function),
-        mockAbortSignal,
-        false,
-        {},
-      );
-    });
-
     it('should handle timeout vs user cancellation correctly', async () => {
       const userAbortController = new AbortController();
       const invocation = shellTool.build({
diff --git a/packages/core/src/tools/shell.ts b/packages/core/src/tools/shell.ts
index 02c486181..625dfe4c6 100644
--- a/packages/core/src/tools/shell.ts
+++ b/packages/core/src/tools/shell.ts
@@ -6,7 +6,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os, { EOL } from 'node:os';
+import os from 'node:os';
 import crypto from 'node:crypto';
 import type { Config } from '../config/config.js';
 import { ToolNames, ToolDisplayNames } from './tool-names.js';
@@ -29,6 +29,8 @@ import type {
   ShellOutputEvent,
 } from '../services/shellExecutionService.js';
 import { ShellExecutionService } from '../services/shellExecutionService.js';
+import type { BackgroundShellEntry } from '../services/backgroundShellRegistry.js';
+import stripAnsi from 'strip-ansi';
 import { formatMemoryUsage } from '../utils/formatters.js';
 import type { AnsiOutput } from '../utils/terminalSerializer.js';
 import { isSubpaths } from '../utils/paths.js';
@@ -46,6 +48,20 @@ import {
 
 const debugLogger = createDebugLogger('SHELL');
 
+/**
+ * Strip a single bare trailing `&` (bash background operator) from a
+ * command string. Returns the input unchanged if the trailing form is
+ * `&&` (logical AND), `\&` (escaped literal `&`), or there is no `&`
+ * at the end at all. Linear time, no regex backtracking risk.
+ */
+function stripTrailingBackgroundAmp(command: string): string {
+  const trimmed = command.trimEnd();
+  if (!trimmed.endsWith('&')) return command;
+  if (trimmed.endsWith('&&')) return command;
+  if (trimmed.endsWith('\\&')) return command;
+  return trimmed.slice(0, -1).trimEnd();
+}
+
 export const OUTPUT_UPDATE_INTERVAL_MS = 1000;
 const DEFAULT_FOREGROUND_TIMEOUT_MS = 120000;
 
@@ -208,9 +224,12 @@ export class ShellToolInvocation extends BaseToolInvocation<
       };
     }
 
-    const effectiveTimeout = this.params.is_background
-      ? undefined
-      : (this.params.timeout ?? DEFAULT_FOREGROUND_TIMEOUT_MS);
+    if (this.params.is_background) {
+      return this.executeBackground(signal, shellExecutionConfig);
+    }
+
+    const effectiveTimeout =
+      this.params.timeout ?? DEFAULT_FOREGROUND_TIMEOUT_MS;
 
     // Create combined signal with timeout for foreground execution
     let combinedSignal = signal;
@@ -219,294 +238,345 @@ export class ShellToolInvocation extends BaseToolInvocation<
       combinedSignal = AbortSignal.any([signal, timeoutSignal]);
     }
 
-    const isWindows = os.platform() === 'win32';
-    const tempFileName = `shell_pgrep_${crypto
-      .randomBytes(6)
-      .toString('hex')}.tmp`;
-    const tempFilePath = path.join(os.tmpdir(), tempFileName);
+    // Add co-author to git commit commands
+    const processedCommand = this.addCoAuthorToGitCommit(strippedCommand);
+    const commandToExecute = processedCommand;
+    const cwd = this.params.directory || this.config.getTargetDir();
 
-    try {
-      // Add co-author to git commit commands
-      const processedCommand = this.addCoAuthorToGitCommit(strippedCommand);
+    let cumulativeOutput: string | AnsiOutput = '';
+    let lastUpdateTime = Date.now();
+    let isBinaryStream = false;
+    let totalLines = 0;
+    let totalBytes = 0;
 
-      const shouldRunInBackground = this.params.is_background;
-      let finalCommand = processedCommand;
+    const { result: resultPromise, pid } = await ShellExecutionService.execute(
+      commandToExecute,
+      cwd,
+      (event: ShellOutputEvent) => {
+        let shouldUpdate = false;
 
-      // On non-Windows, use & to run in background.
-      // On Windows, we don't use start /B because it creates a detached process that
-      // doesn't die when the parent dies. Instead, we rely on the race logic below
-      // to return early while keeping the process attached (detached: false).
-      if (
-        !isWindows &&
-        shouldRunInBackground &&
-        !finalCommand.trim().endsWith('&')
-      ) {
-        finalCommand = finalCommand.trim() + ' &';
-      }
-
-      // On Windows, we rely on the race logic below to handle background tasks.
-      // We just ensure the command string is clean.
-      if (isWindows && shouldRunInBackground) {
-        finalCommand = finalCommand.trim().replace(/&+$/, '').trim();
-      }
-
-      // On non-Windows background commands, wrap with pgrep to capture
-      // subprocess PIDs so we can report them to the user.
-      const commandToExecute =
-        !isWindows && shouldRunInBackground
-          ? (() => {
-              let command = finalCommand.trim();
-              if (!command.endsWith('&')) command += ';';
-              return `{ ${command} }; __code=$?; pgrep -g 0 >${tempFilePath} 2>&1; exit $__code;`;
-            })()
-          : finalCommand;
-
-      const cwd = this.params.directory || this.config.getTargetDir();
-
-      let cumulativeOutput: string | AnsiOutput = '';
-      let lastUpdateTime = Date.now();
-      let isBinaryStream = false;
-      let totalLines = 0;
-      let totalBytes = 0;
-
-      const { result: resultPromise, pid } =
-        await ShellExecutionService.execute(
-          commandToExecute,
-          cwd,
-          (event: ShellOutputEvent) => {
-            let shouldUpdate = false;
-
-            switch (event.type) {
-              case 'data':
-                if (isBinaryStream) break;
-                cumulativeOutput = event.chunk;
-                // Stats are only consumed by the ANSI-output branch below,
-                // so skip the per-chunk accounting for plain string chunks.
-                if (Array.isArray(event.chunk)) {
-                  totalLines = event.chunk.length;
-                  totalBytes = event.chunk.reduce(
-                    (sum, line) =>
-                      sum +
-                      line.reduce(
-                        (ls, token) =>
-                          ls + Buffer.byteLength(token.text, 'utf-8'),
-                        0,
-                      ),
+        switch (event.type) {
+          case 'data':
+            if (isBinaryStream) break;
+            cumulativeOutput = event.chunk;
+            // Stats are only consumed by the ANSI-output branch below,
+            // so skip the per-chunk accounting for plain string chunks.
+            if (Array.isArray(event.chunk)) {
+              totalLines = event.chunk.length;
+              totalBytes = event.chunk.reduce(
+                (sum, line) =>
+                  sum +
+                  line.reduce(
+                    (ls, token) => ls + Buffer.byteLength(token.text, 'utf-8'),
                     0,
-                  );
-                }
-                shouldUpdate = true;
-                break;
-              case 'binary_detected':
-                isBinaryStream = true;
-                cumulativeOutput =
-                  '[Binary output detected. Halting stream...]';
-                shouldUpdate = true;
-                break;
-              case 'binary_progress':
-                isBinaryStream = true;
-                cumulativeOutput = `[Receiving binary output... ${formatMemoryUsage(
-                  event.bytesReceived,
-                )} received]`;
-                if (Date.now() - lastUpdateTime > OUTPUT_UPDATE_INTERVAL_MS) {
-                  shouldUpdate = true;
-                }
-                break;
-              default: {
-                throw new Error('An unhandled ShellOutputEvent was found.');
-              }
+                  ),
+                0,
+              );
             }
-
-            if (shouldUpdate && updateOutput) {
-              if (typeof cumulativeOutput === 'string') {
-                updateOutput(cumulativeOutput);
-              } else {
-                updateOutput({
-                  ansiOutput: cumulativeOutput,
-                  totalLines,
-                  totalBytes,
-                  // Only include timeout when user explicitly set it
-                  ...(this.params.timeout != null && {
-                    timeoutMs: this.params.timeout,
-                  }),
-                });
-              }
-              lastUpdateTime = Date.now();
+            shouldUpdate = true;
+            break;
+          case 'binary_detected':
+            isBinaryStream = true;
+            cumulativeOutput = '[Binary output detected. Halting stream...]';
+            shouldUpdate = true;
+            break;
+          case 'binary_progress':
+            isBinaryStream = true;
+            cumulativeOutput = `[Receiving binary output... ${formatMemoryUsage(
+              event.bytesReceived,
+            )} received]`;
+            if (Date.now() - lastUpdateTime > OUTPUT_UPDATE_INTERVAL_MS) {
+              shouldUpdate = true;
             }
-          },
-          combinedSignal,
-          shouldRunInBackground
-            ? false
-            : this.config.getShouldUseNodePtyShell(),
-          shellExecutionConfig ?? {},
-        );
-
-      if (pid && setPidCallback) {
-        setPidCallback(pid);
-      }
-
-      // On Windows, background commands rely on early return since there's
-      // no & backgrounding or pgrep. Awaiting would block until completion.
-      if (shouldRunInBackground && isWindows) {
-        const pidMsg = pid ? ` PID: ${pid}` : '';
-        const killHint = ' (Use taskkill /F /T /PID <pid> to stop)';
-
-        return {
-          llmContent: `Background command started.${pidMsg}${killHint}`,
-          returnDisplay: `Background command started.${pidMsg}${killHint}`,
-        };
-      }
-
-      const result = await resultPromise;
-
-      if (shouldRunInBackground) {
-        // Read subprocess PIDs captured by the pgrep wrapper (non-Windows only)
-        const backgroundPIDs: number[] = [];
-        if (!isWindows) {
-          if (fs.existsSync(tempFilePath)) {
-            const pgrepLines = fs
-              .readFileSync(tempFilePath, 'utf8')
-              .split(EOL)
-              .filter(Boolean);
-            for (const line of pgrepLines) {
-              if (!/^\d+$/.test(line)) {
-                debugLogger.warn(`pgrep: ${line}`);
-                continue;
-              }
-              const bgPid = Number(line);
-              if (bgPid !== result.pid) {
-                backgroundPIDs.push(bgPid);
-              }
-            }
-          } else if (!signal.aborted) {
-            debugLogger.warn('missing pgrep output');
+            break;
+          default: {
+            throw new Error('An unhandled ShellOutputEvent was found.');
           }
         }
 
-        const bgPidMsg =
-          backgroundPIDs.length > 0
-            ? ` PIDs: ${backgroundPIDs.join(', ')}`
-            : pid
-              ? ` PID: ${pid}`
-              : '';
-        const killHint = ' (Use kill <pid> to stop)';
-
-        return {
-          llmContent: `Background command started.${bgPidMsg}${killHint}`,
-          returnDisplay: `Background command started.${bgPidMsg}${killHint}`,
-        };
-      }
-
-      let llmContent = '';
-      if (result.aborted) {
-        // Check if it was a timeout or user cancellation
-        const wasTimeout =
-          !this.params.is_background &&
-          effectiveTimeout &&
-          combinedSignal.aborted &&
-          !signal.aborted;
-
-        if (wasTimeout) {
-          llmContent = `Command timed out after ${effectiveTimeout}ms before it could complete.`;
-          if (result.output.trim()) {
-            llmContent += ` Below is the output before it timed out:\n${result.output}`;
+        if (shouldUpdate && updateOutput) {
+          if (typeof cumulativeOutput === 'string') {
+            updateOutput(cumulativeOutput);
           } else {
-            llmContent += ' There was no output before it timed out.';
-          }
-        } else {
-          llmContent =
-            'Command was cancelled by user before it could complete.';
-          if (result.output.trim()) {
-            llmContent += ` Below is the output before it was cancelled:\n${result.output}`;
-          } else {
-            llmContent += ' There was no output before it was cancelled.';
+            updateOutput({
+              ansiOutput: cumulativeOutput,
+              totalLines,
+              totalBytes,
+              // Only include timeout when user explicitly set it
+              ...(this.params.timeout != null && {
+                timeoutMs: this.params.timeout,
+              }),
+            });
           }
+          lastUpdateTime = Date.now();
         }
-      } else {
-        // Create a formatted error string for display, replacing the wrapper command
-        // with the user-facing command.
-        const finalError = result.error
-          ? result.error.message.replace(commandToExecute, this.params.command)
-          : '(none)';
+      },
+      combinedSignal,
+      this.config.getShouldUseNodePtyShell(),
+      shellExecutionConfig ?? {},
+    );
 
-        llmContent = [
-          `Command: ${this.params.command}`,
-          `Directory: ${this.params.directory || '(root)'}`,
-          `Output: ${result.output || '(empty)'}`,
-          `Error: ${finalError}`, // Use the cleaned error string.
-          `Exit Code: ${result.exitCode ?? '(none)'}`,
-          `Signal: ${result.signal ?? '(none)'}`,
-          `Process Group PGID: ${result.pid ?? '(none)'}`,
-        ].join('\n');
-      }
+    if (pid && setPidCallback) {
+      setPidCallback(pid);
+    }
 
-      let returnDisplayMessage = '';
-      if (this.config.getDebugMode()) {
-        returnDisplayMessage = llmContent;
-      } else {
+    const result = await resultPromise;
+
+    let llmContent = '';
+    if (result.aborted) {
+      // Check if it was a timeout or user cancellation
+      const wasTimeout =
+        effectiveTimeout && combinedSignal.aborted && !signal.aborted;
+
+      if (wasTimeout) {
+        llmContent = `Command timed out after ${effectiveTimeout}ms before it could complete.`;
         if (result.output.trim()) {
-          returnDisplayMessage = result.output;
+          llmContent += ` Below is the output before it timed out:\n${result.output}`;
         } else {
-          if (result.aborted) {
-            // Check if it was a timeout or user cancellation
-            const wasTimeout =
-              !this.params.is_background &&
-              effectiveTimeout &&
-              combinedSignal.aborted &&
-              !signal.aborted;
-
-            returnDisplayMessage = wasTimeout
-              ? `Command timed out after ${effectiveTimeout}ms.`
-              : 'Command cancelled by user.';
-          } else if (result.signal) {
-            returnDisplayMessage = `Command terminated by signal: ${result.signal}`;
-          } else if (result.error) {
-            returnDisplayMessage = `Command failed: ${getErrorMessage(
-              result.error,
-            )}`;
-          } else if (result.exitCode !== null && result.exitCode !== 0) {
-            returnDisplayMessage = `Command exited with code: ${result.exitCode}`;
-          }
-          // If output is empty and command succeeded (code 0, no error/signal/abort),
-          // returnDisplayMessage will remain empty, which is fine.
+          llmContent += ' There was no output before it timed out.';
+        }
+      } else {
+        llmContent = 'Command was cancelled by user before it could complete.';
+        if (result.output.trim()) {
+          llmContent += ` Below is the output before it was cancelled:\n${result.output}`;
+        } else {
+          llmContent += ' There was no output before it was cancelled.';
         }
       }
+    } else {
+      // Create a formatted error string for display, replacing the wrapper command
+      // with the user-facing command.
+      const finalError = result.error
+        ? result.error.message.replace(commandToExecute, this.params.command)
+        : '(none)';
 
-      // Truncate large output and save full content to a temp file.
-      if (typeof llmContent === 'string') {
-        const truncatedResult = await truncateToolOutput(
-          this.config,
-          ShellTool.Name,
-          llmContent,
-        );
+      llmContent = [
+        `Command: ${this.params.command}`,
+        `Directory: ${this.params.directory || '(root)'}`,
+        `Output: ${result.output || '(empty)'}`,
+        `Error: ${finalError}`, // Use the cleaned error string.
+        `Exit Code: ${result.exitCode ?? '(none)'}`,
+        `Signal: ${result.signal ?? '(none)'}`,
+        `Process Group PGID: ${result.pid ?? '(none)'}`,
+      ].join('\n');
+    }
 
-        if (truncatedResult.outputFile) {
-          llmContent = truncatedResult.content;
-          returnDisplayMessage +=
-            (returnDisplayMessage ? '\n' : '') +
-            `Output too long and was saved to: ${truncatedResult.outputFile}`;
+    let returnDisplayMessage = '';
+    if (this.config.getDebugMode()) {
+      returnDisplayMessage = llmContent;
+    } else {
+      if (result.output.trim()) {
+        returnDisplayMessage = result.output;
+      } else {
+        if (result.aborted) {
+          // Check if it was a timeout or user cancellation
+          const wasTimeout =
+            effectiveTimeout && combinedSignal.aborted && !signal.aborted;
+
+          returnDisplayMessage = wasTimeout
+            ? `Command timed out after ${effectiveTimeout}ms.`
+            : 'Command cancelled by user.';
+        } else if (result.signal) {
+          returnDisplayMessage = `Command terminated by signal: ${result.signal}`;
+        } else if (result.error) {
+          returnDisplayMessage = `Command failed: ${getErrorMessage(
+            result.error,
+          )}`;
+        } else if (result.exitCode !== null && result.exitCode !== 0) {
+          returnDisplayMessage = `Command exited with code: ${result.exitCode}`;
         }
-      }
-
-      const executionError = result.error
-        ? {
-            error: {
-              message: result.error.message,
-              type: ToolErrorType.SHELL_EXECUTE_ERROR,
-            },
-          }
-        : {};
-
-      return {
-        llmContent,
-        returnDisplay: returnDisplayMessage,
-        ...executionError,
-      };
-    } finally {
-      if (fs.existsSync(tempFilePath)) {
-        fs.unlinkSync(tempFilePath);
+        // If output is empty and command succeeded (code 0, no error/signal/abort),
+        // returnDisplayMessage will remain empty, which is fine.
       }
     }
+
+    // Truncate large output and save full content to a temp file.
+    if (typeof llmContent === 'string') {
+      const truncatedResult = await truncateToolOutput(
+        this.config,
+        ShellTool.Name,
+        llmContent,
+      );
+
+      if (truncatedResult.outputFile) {
+        llmContent = truncatedResult.content;
+        returnDisplayMessage +=
+          (returnDisplayMessage ? '\n' : '') +
+          `Output too long and was saved to: ${truncatedResult.outputFile}`;
+      }
+    }
+
+    const executionError = result.error
+      ? {
+          error: {
+            message: result.error.message,
+            type: ToolErrorType.SHELL_EXECUTE_ERROR,
+          },
+        }
+      : {};
+
+    return {
+      llmContent,
+      returnDisplay: returnDisplayMessage,
+      ...executionError,
+    };
+  }
+
+  /**
+   * Background-execution path: spawn the command into a managed registry
+   * entry instead of detaching with `&`. Output streams to a per-shell file
+   * the agent can `Read`; cancellation flows through the entry's
+   * AbortController; the registry's terminal status is set when the process
+   * exits. Returns immediately so the agent's turn isn't blocked.
+   */
+  private async executeBackground(
+    signal: AbortSignal,
+    shellExecutionConfig?: ShellExecutionConfig,
+  ): Promise<ToolResult> {
+    const strippedCommand = stripShellWrapper(this.params.command);
+    // Strip a single bare trailing `&` (the bash background operator) before
+    // spawn: bash treats it as background-detach, exits the wrapper
+    // immediately, and the real child outlives the wrapper — the registry
+    // would settle as `completed` while the shell is still running, and
+    // chunked output would land on a closed stream. The managed path is
+    // itself the backgrounding mechanism, so the trailing `&` is redundant.
+    //
+    // Deliberately precise: do not touch `&&` (logical AND), `\&` (escaped
+    // literal `&`), or commands without a trailing `&`. Earlier `\s*&+\s*$`
+    // was both too greedy (it ate `&&` and `\&`) and a ReDoS hazard on
+    // long all-`&` inputs. Plain string checks here are linear and clearer
+    // than a lookbehind regex.
+    const noTrailingAmp = stripTrailingBackgroundAmp(strippedCommand);
+    if (noTrailingAmp !== strippedCommand) {
+      debugLogger.warn(
+        'Stripped trailing & from background shell command — managed path handles backgrounding',
+      );
+    }
+    const processedCommand = this.addCoAuthorToGitCommit(noTrailingAmp);
+    const cwd = this.params.directory || this.config.getTargetDir();
+
+    // Output goes under the project temp dir (which `ReadFileTool`
+    // auto-allows by default), so the LLM can `Read` the captured output
+    // without bouncing off a permission prompt — important because
+    // background-agent contexts can't surface interactive prompts.
+    const outputDir = path.join(
+      this.config.storage.getProjectTempDir(),
+      'background-shells',
+      this.config.getSessionId(),
+    );
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    const shellId = `bg_${crypto.randomBytes(4).toString('hex')}`;
+    const outputPath = path.join(outputDir, `shell-${shellId}.output`);
+
+    // Background shells are explicitly independent of the current turn:
+    // the user pressing Ctrl+C on a turn (which aborts `signal`) should
+    // NOT kill a long-running dev server / watcher they intentionally
+    // backgrounded. Cancellation flows only through the entry's own
+    // AbortController, driven by future `task_stop` integration (#3471).
+    // The `signal` parameter is still honored for the synchronous early
+    // return below (don't even spawn if the agent already aborted), but
+    // we deliberately do not forward it.
+    const entryAc = new AbortController();
+
+    const outputStream = fs.createWriteStream(outputPath, { flags: 'w' });
+    // Without an 'error' listener, a write failure (disk full, permission
+    // change, fs going away) would surface as an uncaught exception and
+    // kill the entire CLI session. Log + drop is the sane default — the
+    // process keeps running, the registry still settles via resultPromise.
+    outputStream.on('error', (err) => {
+      debugLogger.warn(
+        `background shell ${shellId} output write error: ${err.message}`,
+      );
+    });
+
+    const startTime = Date.now();
+    const entry: BackgroundShellEntry = {
+      shellId,
+      command: processedCommand,
+      cwd,
+      status: 'running',
+      startTime,
+      outputPath,
+      abortController: entryAc,
+    };
+
+    const { result: resultPromise, pid } = await ShellExecutionService.execute(
+      processedCommand,
+      cwd,
+      (event: ShellOutputEvent) => {
+        if (event.type === 'data' && typeof event.chunk === 'string') {
+          // Strip ANSI escape codes (color, cursor-move, clear-screen) before
+          // writing — agents read the file as plain text, and dev servers /
+          // build tools spam plenty of escape sequences that would render as
+          // garbage. Costs ~one regex per chunk; cheap relative to disk I/O.
+          outputStream.write(stripAnsi(event.chunk));
+        }
+        // ANSI array chunks and binary streams are not written to the output
+        // file: agents read the file as plain text and binary spam would be
+        // unhelpful.
+      },
+      entryAc.signal,
+      // Background shells are non-interactive by design — no terminal to
+      // attach a PTY to, no human to type at it. Force the child_process
+      // path so we don't pull in node-pty for fire-and-forget commands.
+      false,
+      shellExecutionConfig ?? {},
+      // Stream stdout/stderr through to the output file as chunks arrive.
+      // Default child_process mode buffers until exit, which would leave
+      // dev-server / watcher output files empty until the process dies.
+      { streamStdout: true },
+    );
+
+    if (pid !== undefined) entry.pid = pid;
+    const registry = this.config.getBackgroundShellRegistry();
+    registry.register(entry);
+
+    // Settle in the background — do NOT await here, the agent should be
+    // unblocked immediately.
+    void resultPromise.then(
+      (result) => {
+        outputStream.end();
+        const endTime = Date.now();
+        if (entryAc.signal.aborted) {
+          if (registry.get(shellId)?.status === 'running') {
+            registry.cancel(shellId, endTime);
+          }
+        } else if (
+          result.error ||
+          (result.exitCode !== null && result.exitCode !== 0) ||
+          result.signal !== null
+        ) {
+          // Non-zero exit / killed by signal / spawn error all count as failed.
+          // Treating them as `completed` would let `/tasks` (and any future
+          // model-facing notification) misreport a failed `npm test` or
+          // `false` command as a success.
+          const reason = result.error
+            ? result.error.message
+            : result.signal !== null
+              ? `terminated by signal ${result.signal}`
+              : `exited with code ${result.exitCode}`;
+          registry.fail(shellId, reason, endTime);
+        } else {
+          registry.complete(shellId, result.exitCode ?? 0, endTime);
+        }
+      },
+      (err) => {
+        outputStream.end();
+        registry.fail(shellId, getErrorMessage(err), Date.now());
+      },
+    );
+
+    const pidLine = pid !== undefined ? `pid: ${pid}\n` : '';
+    return {
+      llmContent:
+        `Background shell started.\n` +
+        `id: ${shellId}\n` +
+        pidLine +
+        `output file: ${outputPath}\n` +
+        `Use the /tasks command to list and inspect background shells, or Read the output file directly.`,
+      returnDisplay: `Background shell ${shellId} started${pid !== undefined ? ` (pid ${pid})` : ''}.`,
+    };
   }
 
   private addCoAuthorToGitCommit(command: string): string {
diff --git a/packages/core/src/tools/task-stop.test.ts b/packages/core/src/tools/task-stop.test.ts
new file mode 100644
index 000000000..d5df835a3
--- /dev/null
+++ b/packages/core/src/tools/task-stop.test.ts
@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { TaskStopTool } from './task-stop.js';
+import { BackgroundTaskRegistry } from '../agents/background-tasks.js';
+import type { Config } from '../config/config.js';
+import { ToolErrorType } from './tool-error.js';
+
+describe('TaskStopTool', () => {
+  let registry: BackgroundTaskRegistry;
+  let config: Config;
+  let tool: TaskStopTool;
+
+  beforeEach(() => {
+    registry = new BackgroundTaskRegistry();
+    config = {
+      getBackgroundTaskRegistry: () => registry,
+    } as unknown as Config;
+    tool = new TaskStopTool(config);
+  });
+
+  it('cancels a running agent', async () => {
+    const ac = new AbortController();
+    registry.register({
+      agentId: 'agent-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: ac,
+    });
+
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'agent-1' },
+      new AbortController().signal,
+    );
+
+    expect(result.error).toBeUndefined();
+    expect(result.llmContent).toContain('Cancellation requested');
+    expect(result.llmContent).toContain('agent-1');
+    expect(registry.get('agent-1')!.status).toBe('cancelled');
+    expect(ac.signal.aborted).toBe(true);
+  });
+
+  it('returns error for non-existent task', async () => {
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'nope' },
+      new AbortController().signal,
+    );
+
+    expect(result.error?.type).toBe(ToolErrorType.TASK_STOP_NOT_FOUND);
+    expect(result.llmContent).toContain('No background task found');
+  });
+
+  it('returns error for non-running task', async () => {
+    registry.register({
+      agentId: 'agent-1',
+      description: 'test agent',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+    registry.complete('agent-1', 'done');
+
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'agent-1' },
+      new AbortController().signal,
+    );
+
+    expect(result.error?.type).toBe(ToolErrorType.TASK_STOP_NOT_RUNNING);
+    expect(result.llmContent).toContain('not running');
+  });
+
+  it('includes description in success response', async () => {
+    registry.register({
+      agentId: 'agent-1',
+      description: 'Search for auth code',
+      status: 'running',
+      startTime: Date.now(),
+      abortController: new AbortController(),
+    });
+
+    const result = await tool.validateBuildAndExecute(
+      { task_id: 'agent-1' },
+      new AbortController().signal,
+    );
+
+    expect(result.llmContent).toContain('Search for auth code');
+    expect(result.returnDisplay).toContain('Search for auth code');
+  });
+});
diff --git a/packages/core/src/tools/task-stop.ts b/packages/core/src/tools/task-stop.ts
new file mode 100644
index 000000000..655b70450
--- /dev/null
+++ b/packages/core/src/tools/task-stop.ts
@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview TaskStop tool — lets the model cancel a running background task.
+ */
+
+import type { Config } from '../config/config.js';
+import { ToolErrorType } from './tool-error.js';
+import { ToolNames, ToolDisplayNames } from './tool-names.js';
+import {
+  BaseDeclarativeTool,
+  BaseToolInvocation,
+  Kind,
+  type ToolInvocation,
+  type ToolResult,
+} from './tools.js';
+
+export interface TaskStopParams {
+  /** The ID of the background task to stop. */
+  task_id: string;
+}
+
+class TaskStopInvocation extends BaseToolInvocation<
+  TaskStopParams,
+  ToolResult
+> {
+  constructor(
+    private readonly config: Config,
+    params: TaskStopParams,
+  ) {
+    super(params);
+  }
+
+  getDescription(): string {
+    return `Stop background task ${this.params.task_id}`;
+  }
+
+  async execute(_signal: AbortSignal): Promise<ToolResult> {
+    const registry = this.config.getBackgroundTaskRegistry();
+    const entry = registry.get(this.params.task_id);
+
+    if (!entry) {
+      return {
+        llmContent: `Error: No background task found with ID "${this.params.task_id}".`,
+        returnDisplay: 'Task not found.',
+        error: {
+          message: `Task not found: ${this.params.task_id}`,
+          type: ToolErrorType.TASK_STOP_NOT_FOUND,
+        },
+      };
+    }
+
+    if (entry.status !== 'running') {
+      return {
+        llmContent: `Error: Background task "${this.params.task_id}" is not running (status: ${entry.status}).`,
+        returnDisplay: `Task not running (${entry.status}).`,
+        error: {
+          message: `Task is ${entry.status}: ${this.params.task_id}`,
+          type: ToolErrorType.TASK_STOP_NOT_RUNNING,
+        },
+      };
+    }
+
+    registry.cancel(this.params.task_id);
+
+    // The terminal task-notification is emitted by the task's own handler
+    // (via registry.complete/fail) rather than cancel(), so the parent model
+    // still receives the task's real partial/final result — not just a bare
+    // "cancelled" message — once the reasoning loop unwinds.
+    const desc = entry.description;
+    return {
+      llmContent: `Cancellation requested for background task "${this.params.task_id}". A final task-notification carrying the task's last result will follow.\nDescription: ${desc}`,
+      returnDisplay: `Cancelled: ${desc}`,
+    };
+  }
+}
+
+export class TaskStopTool extends BaseDeclarativeTool<
+  TaskStopParams,
+  ToolResult
+> {
+  static readonly Name = ToolNames.TASK_STOP;
+
+  constructor(private readonly config: Config) {
+    super(
+      TaskStopTool.Name,
+      ToolDisplayNames.TASK_STOP,
+      'Cancel a running background task by its ID. The task ID is returned when the task is launched.',
+      Kind.Other,
+      {
+        type: 'object',
+        properties: {
+          task_id: {
+            type: 'string',
+            description:
+              'The ID of the background task to stop (from the launch response or notification).',
+          },
+        },
+        required: ['task_id'],
+        additionalProperties: false,
+      },
+    );
+  }
+
+  protected createInvocation(
+    params: TaskStopParams,
+  ): ToolInvocation<TaskStopParams, ToolResult> {
+    return new TaskStopInvocation(this.config, params);
+  }
+}
diff --git a/packages/core/src/tools/tool-error.ts b/packages/core/src/tools/tool-error.ts
index fe9d2122b..6a29472c6 100644
--- a/packages/core/src/tools/tool-error.ts
+++ b/packages/core/src/tools/tool-error.ts
@@ -66,4 +66,12 @@ export enum ToolErrorType {
 
   // Truncation Errors
   OUTPUT_TRUNCATED = 'output_truncated',
+
+  // TaskStop-specific Errors
+  TASK_STOP_NOT_FOUND = 'task_stop_not_found',
+  TASK_STOP_NOT_RUNNING = 'task_stop_not_running',
+
+  // SendMessage-specific Errors
+  SEND_MESSAGE_NOT_FOUND = 'send_message_not_found',
+  SEND_MESSAGE_NOT_RUNNING = 'send_message_not_running',
 }
diff --git a/packages/core/src/tools/tool-names.ts b/packages/core/src/tools/tool-names.ts
index 256722192..bde051035 100644
--- a/packages/core/src/tools/tool-names.ts
+++ b/packages/core/src/tools/tool-names.ts
@@ -28,6 +28,8 @@ export const ToolNames = {
   CRON_CREATE: 'cron_create',
   CRON_LIST: 'cron_list',
   CRON_DELETE: 'cron_delete',
+  TASK_STOP: 'task_stop',
+  SEND_MESSAGE: 'send_message',
 } as const;
 
 /**
@@ -54,6 +56,8 @@ export const ToolDisplayNames = {
   CRON_CREATE: 'CronCreate',
   CRON_LIST: 'CronList',
   CRON_DELETE: 'CronDelete',
+  TASK_STOP: 'TaskStop',
+  SEND_MESSAGE: 'SendMessage',
 } as const;
 
 // Migration from old tool names to new tool names
diff --git a/packages/core/src/utils/fileUtils.test.ts b/packages/core/src/utils/fileUtils.test.ts
index 5f1bc1034..a1f529cdf 100644
--- a/packages/core/src/utils/fileUtils.test.ts
+++ b/packages/core/src/utils/fileUtils.test.ts
@@ -40,6 +40,40 @@ vi.mock('mime/lite', () => ({
   getType: vi.fn(),
 }));
 
+// Mock execFile so isPdftotextAvailable does not spawn a real process.
+// On platforms where pdftotext is not installed (e.g. Windows CI),
+// the 5-second execFile timeout can exceed the default 5s test timeout.
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  return {
+    ...actual,
+    execFile: vi.fn(
+      (
+        _command: string,
+        _args: string[],
+        _optionsOrCallback: unknown,
+        _callback?: unknown,
+      ) => {
+        // Resolve the callback (supports both signatures of execFile)
+        const cb =
+          typeof _optionsOrCallback === 'function'
+            ? _optionsOrCallback
+            : _callback;
+        const error = Object.assign(new Error('Command not found'), {
+          code: 'ENOENT',
+        });
+        if (typeof cb === 'function') {
+          setImmediate(() => cb(error, '', ''));
+        }
+        return {
+          kill: vi.fn(),
+          on: vi.fn(),
+        } as unknown as import('node:child_process').ChildProcess;
+      },
+    ),
+  };
+});
+
 const mockMimeGetType = mime.getType as Mock;
 
 describe('fileUtils', () => {
diff --git a/packages/core/src/utils/jsonl-utils.test.ts b/packages/core/src/utils/jsonl-utils.test.ts
new file mode 100644
index 000000000..60e86b204
--- /dev/null
+++ b/packages/core/src/utils/jsonl-utils.test.ts
@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  _recoverObjectsFromLine,
+  _resetEnsuredDirsCacheForTest,
+  read,
+  readLines,
+} from './jsonl-utils.js';
+
+let tmpRoot: string;
+
+beforeAll(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'jsonl-utils-test-'));
+});
+
+afterAll(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  _resetEnsuredDirsCacheForTest();
+});
+
+function tmpFile(content: string): string {
+  const p = path.join(
+    tmpRoot,
+    `t-${Math.random().toString(36).slice(2)}.jsonl`,
+  );
+  fs.writeFileSync(p, content, 'utf8');
+  return p;
+}
+
+describe('_recoverObjectsFromLine', () => {
+  it('returns single object for a well-formed JSON line', () => {
+    expect(_recoverObjectsFromLine<{ a: number }>('{"a":1}')).toEqual([
+      { a: 1 },
+    ]);
+  });
+
+  it('splits two concatenated objects with no separator', () => {
+    expect(
+      _recoverObjectsFromLine<{ a: number } | { b: number }>('{"a":1}{"b":2}'),
+    ).toEqual([{ a: 1 }, { b: 2 }]);
+  });
+
+  it('does not split on `}{` that appears inside a string value', () => {
+    const line = '{"text":"close-then-open: }{ here"}';
+    expect(_recoverObjectsFromLine<{ text: string }>(line)).toEqual([
+      { text: 'close-then-open: }{ here' },
+    ]);
+  });
+
+  it('handles escaped quotes inside strings', () => {
+    const line = '{"q":"he said \\"hi\\"","n":1}{"q":"x"}';
+    expect(_recoverObjectsFromLine<{ q: string; n?: number }>(line)).toEqual([
+      { q: 'he said "hi"', n: 1 },
+      { q: 'x' },
+    ]);
+  });
+
+  it('recovers objects around an unbalanced fragment', () => {
+    // Middle `{"oops":}` fails JSON.parse, surrounding objects still parse.
+    expect(
+      _recoverObjectsFromLine<{ a?: number; b?: number }>(
+        '{"a":1}{"oops":}{"b":2}',
+      ),
+    ).toEqual([{ a: 1 }, { b: 2 }]);
+  });
+
+  it('returns empty array when nothing balanced can be parsed', () => {
+    expect(_recoverObjectsFromLine('not json at all')).toEqual([]);
+    expect(_recoverObjectsFromLine('{"unterminated":')).toEqual([]);
+  });
+});
+
+describe('read() / readLines() with malformed lines', () => {
+  it('reads a clean file unchanged', async () => {
+    const file = tmpFile('{"a":1}\n{"a":2}\n{"a":3}\n');
+    expect(await read<{ a: number }>(file)).toEqual([
+      { a: 1 },
+      { a: 2 },
+      { a: 3 },
+    ]);
+  });
+
+  it('recovers concatenated records without losing later lines', async () => {
+    // The #3606 corruption shape: two records glued onto one physical line,
+    // with valid records before and after.
+    const file = tmpFile(
+      '{"uuid":"a","i":1}\n{"uuid":"b","i":2}{"uuid":"c","i":3}\n{"uuid":"d","i":4}\n',
+    );
+    const out = await read<{ uuid: string; i: number }>(file);
+    expect(out.map((r) => r.uuid)).toEqual(['a', 'b', 'c', 'd']);
+  });
+
+  it('skips a fully-garbage line and keeps reading', async () => {
+    const file = tmpFile('{"a":1}\nnot-json-at-all\n{"a":3}\n');
+    expect(await read<{ a: number }>(file)).toEqual([{ a: 1 }, { a: 3 }]);
+  });
+
+  it('returns [] for a missing file', async () => {
+    expect(await read(path.join(tmpRoot, 'does-not-exist.jsonl'))).toEqual([]);
+  });
+
+  it('readLines respects the limit when objects come from recovery', async () => {
+    // Two clean lines, then a glued pair. Asking for 3 should yield 3.
+    const file = tmpFile('{"i":1}\n{"i":2}\n{"i":3}{"i":4}\n{"i":5}\n');
+    expect((await readLines<{ i: number }>(file, 3)).map((r) => r.i)).toEqual([
+      1, 2, 3,
+    ]);
+  });
+
+  it('readLines recovers when the malformed line is within the first N', async () => {
+    const file = tmpFile('{"i":1}{"i":2}\n{"i":3}\n');
+    expect((await readLines<{ i: number }>(file, 5)).map((r) => r.i)).toEqual([
+      1, 2, 3,
+    ]);
+  });
+
+  it('skips blank lines', async () => {
+    const file = tmpFile('{"a":1}\n\n{"a":2}\n');
+    expect(await read<{ a: number }>(file)).toEqual([{ a: 1 }, { a: 2 }]);
+  });
+});
diff --git a/packages/core/src/utils/jsonl-utils.ts b/packages/core/src/utils/jsonl-utils.ts
index 639076a1a..1c7cb5bb7 100644
--- a/packages/core/src/utils/jsonl-utils.ts
+++ b/packages/core/src/utils/jsonl-utils.ts
@@ -44,6 +44,89 @@ function getFileLock(filePath: string): Mutex {
   return fileLocks.get(filePath)!;
 }
 
+/**
+ * Recovers parsed objects from a single physical line that may contain one
+ * or more concatenated top-level JSON objects (i.e. a missing newline
+ * separator left two records glued together as `}{`). Walks the line with a
+ * brace-depth counter that respects string boundaries and `\` escapes, then
+ * tries `JSON.parse` on each balanced top-level fragment. Fragments that
+ * still fail to parse are skipped silently — the caller decides whether to
+ * warn.
+ *
+ * **Limitation**: only top-level `{...}` records are recovered. A glued line
+ * whose records are top-level arrays (`[...][...]`) will not split. All
+ * existing JSONL writers in this codebase produce object records, so this
+ * matches the actual corruption shape — extend if that ever changes.
+ *
+ * Exported for unit tests; not part of the module's stable surface.
+ */
+export function _recoverObjectsFromLine<T = unknown>(line: string): T[] {
+  const out: T[] = [];
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  let start = -1;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (inString) {
+      if (c === '\\') escape = true;
+      else if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      continue;
+    }
+    if (c === '{') {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (c === '}') {
+      depth--;
+      if (depth === 0 && start >= 0) {
+        const fragment = line.slice(start, i + 1);
+        try {
+          out.push(JSON.parse(fragment) as T);
+        } catch {
+          // Skip un-parseable fragment; caller may still recover others.
+        }
+        start = -1;
+      } else if (depth < 0) {
+        // Unbalanced close brace — reset and keep scanning for the next
+        // well-formed object rather than giving up on the whole line.
+        depth = 0;
+        start = -1;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Parses a single physical JSONL line tolerantly. Returns the parsed objects:
+ * one if the line is well-formed, multiple if it is `}{`-glued from an
+ * interrupted append (the #3606 corruption shape), zero if nothing can be
+ * recovered. Mirrors the silent skip in `countSessionMessages`.
+ */
+function parseLineTolerant<T>(line: string, filePath: string): T[] {
+  try {
+    return [JSON.parse(line) as T];
+  } catch {
+    const fragments = _recoverObjectsFromLine<T>(line);
+    if (fragments.length === 0) {
+      debugLogger.warn(`Failed to parse line in ${filePath}`);
+    } else {
+      debugLogger.warn(
+        `Recovered ${fragments.length} record(s) from malformed line in ${filePath}`,
+      );
+    }
+    return fragments;
+  }
+}
+
 /**
  * Reads the first N lines from a JSONL file efficiently.
  * Returns an array of parsed objects.
@@ -63,8 +146,10 @@ export async function readLines<T = unknown>(
     for await (const line of rl) {
       if (results.length >= count) break;
       const trimmed = line.trim();
-      if (trimmed.length > 0) {
-        results.push(JSON.parse(trimmed) as T);
+      if (trimmed.length === 0) continue;
+      for (const obj of parseLineTolerant<T>(trimmed, filePath)) {
+        if (results.length >= count) break;
+        results.push(obj);
       }
     }
 
@@ -95,8 +180,9 @@ export async function read<T = unknown>(filePath: string): Promise<T[]> {
     const results: T[] = [];
     for await (const line of rl) {
       const trimmed = line.trim();
-      if (trimmed.length > 0) {
-        results.push(JSON.parse(trimmed) as T);
+      if (trimmed.length === 0) continue;
+      for (const obj of parseLineTolerant<T>(trimmed, filePath)) {
+        results.push(obj);
       }
     }
 
diff --git a/packages/core/src/utils/runtimeFetchOptions.test.ts b/packages/core/src/utils/runtimeFetchOptions.test.ts
index fd4e7a089..62a4b0455 100644
--- a/packages/core/src/utils/runtimeFetchOptions.test.ts
+++ b/packages/core/src/utils/runtimeFetchOptions.test.ts
@@ -4,8 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi } from 'vitest';
-import { buildRuntimeFetchOptions } from './runtimeFetchOptions.js';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  buildRuntimeFetchOptions,
+  getOrCreateSharedDispatcher,
+  resetDispatcherCache,
+} from './runtimeFetchOptions.js';
 
 type UndiciOptions = Record<string, unknown>;
 
@@ -31,6 +35,9 @@ vi.mock('undici', () => {
 });
 
 describe('buildRuntimeFetchOptions (node runtime)', () => {
+  beforeEach(() => {
+    resetDispatcherCache();
+  });
   it('disables undici timeouts for Agent in OpenAI options', () => {
     const result = buildRuntimeFetchOptions('openai');
 
@@ -93,3 +100,36 @@ describe('buildRuntimeFetchOptions (node runtime)', () => {
     });
   });
 });
+
+describe('getOrCreateSharedDispatcher', () => {
+  beforeEach(() => {
+    resetDispatcherCache();
+  });
+
+  it('returns the same instance for repeated calls without proxy', () => {
+    const d1 = getOrCreateSharedDispatcher();
+    const d2 = getOrCreateSharedDispatcher();
+    expect(d1).toBe(d2);
+  });
+
+  it('returns the same instance for repeated calls with the same proxy', () => {
+    const d1 = getOrCreateSharedDispatcher('http://proxy.local');
+    const d2 = getOrCreateSharedDispatcher('http://proxy.local');
+    expect(d1).toBe(d2);
+  });
+
+  it('returns different instances for different proxy URLs', () => {
+    const d1 = getOrCreateSharedDispatcher();
+    const d2 = getOrCreateSharedDispatcher('http://proxy.local');
+    expect(d1).not.toBe(d2);
+  });
+
+  it('shares the same dispatcher with buildRuntimeFetchOptions', () => {
+    const shared = getOrCreateSharedDispatcher();
+    const result = buildRuntimeFetchOptions('openai');
+    const sdkDispatcher = (
+      result as { fetchOptions?: { dispatcher?: unknown } }
+    ).fetchOptions?.dispatcher;
+    expect(sdkDispatcher).toBe(shared);
+  });
+});
diff --git a/packages/core/src/utils/runtimeFetchOptions.ts b/packages/core/src/utils/runtimeFetchOptions.ts
index 1e0ef4806..86f1d81a2 100644
--- a/packages/core/src/utils/runtimeFetchOptions.ts
+++ b/packages/core/src/utils/runtimeFetchOptions.ts
@@ -131,21 +131,57 @@ export function buildRuntimeFetchOptions(
   }
 }
 
+/**
+ * Cache of shared dispatcher instances keyed by proxy URL (undefined = no proxy).
+ * Ensures preconnect and SDK clients share the same connection pool.
+ */
+const dispatcherCache = new Map<string | undefined, Dispatcher>();
+
+/**
+ * Get or create a shared undici dispatcher for the given proxy configuration.
+ * The dispatcher is cached so that preconnect and subsequent SDK requests
+ * share the same connection pool, enabling TCP+TLS connection reuse.
+ *
+ * @param proxyUrl - Optional proxy URL; undefined for direct connections
+ * @returns A cached undici Dispatcher (Agent or ProxyAgent)
+ */
+export function getOrCreateSharedDispatcher(proxyUrl?: string): Dispatcher {
+  const cached = dispatcherCache.get(proxyUrl);
+  if (cached) {
+    return cached;
+  }
+
+  const dispatcher = proxyUrl
+    ? new ProxyAgent({
+        uri: proxyUrl,
+        headersTimeout: 0,
+        bodyTimeout: 0,
+        keepAliveTimeout: 60_000,
+      })
+    : new Agent({
+        headersTimeout: 0,
+        bodyTimeout: 0,
+        keepAliveTimeout: 60_000,
+      });
+
+  dispatcherCache.set(proxyUrl, dispatcher);
+  return dispatcher;
+}
+
+/**
+ * Reset the dispatcher cache (for testing only)
+ * @internal
+ */
+export function resetDispatcherCache(): void {
+  dispatcherCache.clear();
+}
+
 function buildFetchOptionsWithDispatcher(
   sdkType: SDKType,
   proxyUrl?: string,
 ): OpenAIRuntimeFetchOptions | AnthropicRuntimeFetchOptions {
   try {
-    const dispatcher = proxyUrl
-      ? new ProxyAgent({
-          uri: proxyUrl,
-          headersTimeout: 0,
-          bodyTimeout: 0,
-        })
-      : new Agent({
-          headersTimeout: 0,
-          bodyTimeout: 0,
-        });
+    const dispatcher = getOrCreateSharedDispatcher(proxyUrl);
     return { fetchOptions: { dispatcher } };
   } catch {
     return sdkType === 'openai' ? undefined : {};
diff --git a/packages/core/src/utils/shell-utils.test.ts b/packages/core/src/utils/shell-utils.test.ts
index b95e95c7b..f03814268 100644
--- a/packages/core/src/utils/shell-utils.test.ts
+++ b/packages/core/src/utils/shell-utils.test.ts
@@ -442,6 +442,18 @@ describe('getCommandRoots', () => {
     expect(result).toEqual(['grep']);
   });
 
+  it('should treat escaped newlines in chained commands as line continuations', async () => {
+    const result = getCommandRoots(
+      'cd project && \\\ngit add file.php && \\\ngit commit -m "feat"',
+    );
+    expect(result).toEqual(['cd', 'git', 'git']);
+  });
+
+  it('should not treat escaped CRLF as a line continuation', async () => {
+    const result = getCommandRoots('echo SAFE \\\r\nrm -rf /');
+    expect(result).toEqual(['echo', 'rm']);
+  });
+
   it('should filter out empty segments from consecutive newlines', async () => {
     const result = getCommandRoots('ls\n\ngrep foo');
     expect(result).toEqual(['ls', 'grep']);
diff --git a/packages/core/src/utils/shell-utils.ts b/packages/core/src/utils/shell-utils.ts
index ac4a2d0d5..55d778dde 100644
--- a/packages/core/src/utils/shell-utils.ts
+++ b/packages/core/src/utils/shell-utils.ts
@@ -224,6 +224,11 @@ export function splitCommands(command: string): string[] {
     const char = command[i];
     const nextChar = command[i + 1];
 
+    if (!inSingleQuotes && char === '\\' && nextChar === '\n') {
+      i += 2;
+      continue;
+    }
+
     if (char === '\\' && i < command.length - 1) {
       currentCommand += char + command[i + 1];
       i += 2;
diff --git a/packages/core/src/utils/terminalSerializer.test.ts b/packages/core/src/utils/terminalSerializer.test.ts
index fd6241d04..ab067d186 100644
--- a/packages/core/src/utils/terminalSerializer.test.ts
+++ b/packages/core/src/utils/terminalSerializer.test.ts
@@ -8,6 +8,7 @@ import { describe, it, expect } from 'vitest';
 import { Terminal } from '@xterm/headless';
 import {
   serializeTerminalToObject,
+  serializeTerminalToText,
   convertColorToHex,
   ColorMode,
 } from './terminalSerializer.js';
@@ -171,7 +172,85 @@ describe('terminalSerializer', () => {
       expect(result[0][0].bg).toBe('#008000');
       expect(result[0][0].text).toBe('Styled text');
     });
+
+    it('can unwrap soft-wrapped ANSI rows for live output comparison', async () => {
+      const terminal = new Terminal({
+        cols: 8,
+        rows: 4,
+        allowProposedApi: true,
+        scrollback: 100,
+        convertEol: true,
+      });
+
+      await writeToTerminal(terminal, 'abcdefghijkl\nshort\n');
+
+      const result = serializeTerminalToObject(terminal, 0, {
+        unwrapWrappedLines: true,
+      });
+      const visibleText = result
+        .map((line) =>
+          line
+            .map((token) => token.text)
+            .join('')
+            .trimEnd(),
+        )
+        .filter(Boolean);
+
+      expect(visibleText).toEqual(['abcdefghijkl', 'short']);
+      expect(result[0]).toHaveLength(1);
+    });
   });
+
+  describe('serializeTerminalToText', () => {
+    it('unwraps soft-wrapped narrow terminal lines for transcript text', async () => {
+      const terminal = new Terminal({
+        cols: 10,
+        rows: 4,
+        allowProposedApi: true,
+        scrollback: 100,
+        convertEol: true,
+      });
+
+      await writeToTerminal(terminal, 'abcdefghijklmnopqrstuvwxyz\n');
+
+      expect(serializeTerminalToText(terminal)).toBe(
+        'abcdefghijklmnopqrstuvwxyz',
+      );
+    });
+
+    it('keeps explicit newlines while unwrapping visual continuation rows', async () => {
+      const terminal = new Terminal({
+        cols: 8,
+        rows: 4,
+        allowProposedApi: true,
+        scrollback: 100,
+        convertEol: true,
+      });
+
+      await writeToTerminal(terminal, 'abcdefghijkl\nshort\n');
+
+      expect(serializeTerminalToText(terminal)).toBe('abcdefghijkl\nshort');
+    });
+
+    it('does not treat resize reflow as duplicated transcript lines', async () => {
+      const terminal = new Terminal({
+        cols: 12,
+        rows: 4,
+        allowProposedApi: true,
+        scrollback: 100,
+        convertEol: true,
+      });
+
+      await writeToTerminal(terminal, 'abcdefghijklmnopqrstuvwxyz\n123456\n');
+      terminal.resize(6, 4);
+      await writeToTerminal(terminal, 'done\n');
+
+      expect(serializeTerminalToText(terminal)).toBe(
+        'abcdefghijklmnopqrstuvwxyz\n123456\ndone',
+      );
+    });
+  });
+
   describe('convertColorToHex', () => {
     it('should convert RGB color to hex', () => {
       const color = (100 << 16) | (200 << 8) | 50;
diff --git a/packages/core/src/utils/terminalSerializer.ts b/packages/core/src/utils/terminalSerializer.ts
index e12fe25aa..94f85a5c3 100644
--- a/packages/core/src/utils/terminalSerializer.ts
+++ b/packages/core/src/utils/terminalSerializer.ts
@@ -5,6 +5,7 @@
  */
 
 import type { IBufferCell, Terminal } from '@xterm/headless';
+
 export interface AnsiToken {
   text: string;
   bold: boolean;
@@ -19,6 +20,49 @@ export interface AnsiToken {
 export type AnsiLine = AnsiToken[];
 export type AnsiOutput = AnsiLine[];
 
+export interface SerializeTerminalToObjectOptions {
+  unwrapWrappedLines?: boolean;
+}
+
+const canMergeAnsiTokens = (left: AnsiToken, right: AnsiToken): boolean =>
+  left.bold === right.bold &&
+  left.italic === right.italic &&
+  left.underline === right.underline &&
+  left.dim === right.dim &&
+  left.inverse === right.inverse &&
+  left.fg === right.fg &&
+  left.bg === right.bg;
+
+const appendAnsiLineTokens = (target: AnsiLine, source: AnsiLine) => {
+  for (const token of source) {
+    const previous = target[target.length - 1];
+    if (previous && canMergeAnsiTokens(previous, token)) {
+      previous.text += token.text;
+    } else {
+      target.push({ ...token });
+    }
+  }
+};
+
+export function serializeTerminalToText(terminal: Terminal): string {
+  const buffer = terminal.buffer.active;
+  const lines: string[] = [];
+
+  for (let i = 0; i < buffer.length; i++) {
+    const line = buffer.getLine(i);
+    const lineContent = line ? line.translateToString(true) : '';
+
+    if (line?.isWrapped && lines.length > 0) {
+      lines[lines.length - 1] += lineContent;
+      continue;
+    }
+
+    lines.push(lineContent);
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
 const enum Attribute {
   inverse = 1,
   bold = 2,
@@ -134,6 +178,7 @@ class Cell {
 export function serializeTerminalToObject(
   terminal: Terminal,
   scrollOffset: number = 0,
+  options: SerializeTerminalToObjectOptions = {},
 ): AnsiOutput {
   const buffer = terminal.buffer.active;
   const defaultFg = '';
@@ -199,7 +244,11 @@ export function serializeTerminalToObject(
       currentLine.push(token);
     }
 
-    result.push(currentLine);
+    if (options.unwrapWrappedLines && line.isWrapped && result.length > 0) {
+      appendAnsiLineTokens(result[result.length - 1], currentLine);
+    } else {
+      result.push(currentLine);
+    }
   }
 
   return result;
diff --git a/packages/sdk-python/README.md b/packages/sdk-python/README.md
new file mode 100644
index 000000000..67cf3ae34
--- /dev/null
+++ b/packages/sdk-python/README.md
@@ -0,0 +1,117 @@
+# qwen-code-sdk
+
+Experimental Python SDK for programmatic access to Qwen Code through the
+`stream-json` protocol.
+
+## Installation
+
+```bash
+pip install qwen-code-sdk
+```
+
+## Requirements
+
+- Python `>=3.10`
+- External `qwen` CLI installed and available in `PATH`
+
+You can also point the SDK at an explicit CLI binary or script with
+`path_to_qwen_executable`.
+
+## Quick Start
+
+```python
+import asyncio
+
+from qwen_code_sdk import is_sdk_result_message, query
+
+
+async def main() -> None:
+    result = query(
+        "List the top-level packages in this repository.",
+        {
+            "cwd": "/path/to/project",
+            "path_to_qwen_executable": "qwen",
+        },
+    )
+
+    async for message in result:
+        if is_sdk_result_message(message):
+            print(message["result"])
+
+
+asyncio.run(main())
+```
+
+## Sync API
+
+```python
+from qwen_code_sdk import query_sync
+
+
+with query_sync(
+    "Say hello",
+    {
+        "path_to_qwen_executable": "qwen",
+    },
+) as result:
+    for message in result:
+        print(message)
+```
+
+## Main APIs
+
+- `query(prompt, options=None) -> Query`
+- `query_sync(prompt, options=None) -> SyncQuery`
+- `Query.close()`, `interrupt()`, `set_model()`, `set_permission_mode()`
+- `Query.supported_commands()`, `mcp_server_status()`, `get_session_id()`
+
+`prompt` accepts either a single `str` or an `AsyncIterable[SDKUserMessage]`
+for multi-turn sessions.
+
+## Permission Callback
+
+```python
+from qwen_code_sdk import query
+
+
+async def can_use_tool(tool_name, tool_input, context):
+    if tool_name == "write_file":
+        return {"behavior": "deny", "message": "Writes disabled in this app"}
+    return {"behavior": "allow", "updatedInput": tool_input}
+
+
+result = query(
+    "Create hello.txt",
+    {
+        "path_to_qwen_executable": "qwen",
+        "can_use_tool": can_use_tool,
+    },
+)
+```
+
+The callback defaults to deny. If it does not return within 60 seconds, the SDK
+auto-denies the tool request.
+
+The `context` argument includes `cancel_event`, `suggestions`, and
+`blocked_path` when the CLI provides a path-specific permission target.
+`can_use_tool` must be an `async def` callback accepting
+`(tool_name, tool_input, context)`. `stderr` must accept a single `str`.
+
+## Errors
+
+- `ValidationError`: invalid query options or malformed session identifiers
+- `ControlRequestTimeoutError`: CLI control operation exceeded timeout
+- `ProcessExitError`: `qwen` exited with a non-zero code
+- `AbortError`: query or control request was cancelled
+
+## Current Scope
+
+`0.1.x` is intentionally narrow:
+
+- Uses external `qwen` CLI via process transport
+- Targets `stream-json` parity with the TypeScript SDK core flow
+- Does not yet implement ACP transport
+- Does not yet embed MCP servers inside the SDK process
+
+See [developer documentation](../../docs/developers/sdk-python.md) for more
+detail.
diff --git a/packages/sdk-python/pyproject.toml b/packages/sdk-python/pyproject.toml
new file mode 100644
index 000000000..10745ef69
--- /dev/null
+++ b/packages/sdk-python/pyproject.toml
@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qwen-code-sdk"
+version = "0.1.0"
+description = "Python SDK for programmatic access to qwen-code CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Qwen Team" }]
+keywords = ["qwen", "qwen-code", "sdk", "python", "ai", "code-assistant"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["typing-extensions>=4.12.0"]
+
+[project.urls]
+Homepage = "https://qwenlm.github.io/qwen-code-docs/"
+Repository = "https://github.com/QwenLM/qwen-code"
+Issues = "https://github.com/QwenLM/qwen-code/issues"
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.11.0",
+  "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "ruff>=0.8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qwen_code_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "ASYNC", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+show_error_codes = true
+mypy_path = "src"
diff --git a/packages/sdk-python/scripts/smoke_real.py b/packages/sdk-python/scripts/smoke_real.py
new file mode 100644
index 000000000..820b5a21b
--- /dev/null
+++ b/packages/sdk-python/scripts/smoke_real.py
@@ -0,0 +1,388 @@
+#!/usr/bin/env python3
+"""Run real end-to-end smoke tests against qwen CLI using qwen_code_sdk.
+
+This script is intentionally lightweight and avoids any test doubles.
+It is useful for manual verification after changing SDK runtime behavior.
+"""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info < (3, 10):  # noqa: UP036
+    import json
+
+    version = ".".join(str(part) for part in sys.version_info[:3])
+    payload = {
+        "ok": False,
+        "stage": "startup",
+        "error": f"Python >=3.10 is required, current version is {version}",
+        "error_type": "RuntimeError",
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    raise SystemExit(2)
+
+import argparse
+import asyncio
+import json
+import subprocess
+import threading
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from queue import Empty, Queue
+from typing import Any, TypeVar
+
+SDK_ROOT = Path(__file__).resolve().parents[1]
+SRC_ROOT = SDK_ROOT / "src"
+if str(SRC_ROOT) not in sys.path:
+    sys.path.insert(0, str(SRC_ROOT))
+
+from qwen_code_sdk import (  # noqa: E402
+    SDKUserMessage,
+    SyncQuery,
+    is_sdk_assistant_message,
+    is_sdk_result_message,
+    is_sdk_system_message,
+    query,
+    query_sync,
+)
+from qwen_code_sdk.transport import prepare_spawn_info  # noqa: E402
+
+T = TypeVar("T")
+
+
+@dataclass
+class AsyncSingleResult:
+    ok: bool
+    assistant_text: str | None
+    result_text: str | None
+    session_id: str
+
+
+@dataclass
+class AsyncControlResult:
+    ok: bool
+    supported_commands_type: str
+    saw_system_message: bool
+    saw_result_message: bool
+    session_id: str
+
+
+@dataclass
+class SyncResult:
+    ok: bool
+    saw_result_message: bool
+    result_text: str | None
+    session_id: str
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run real qwen_code_sdk smoke tests using qwen CLI",
+    )
+    parser.add_argument(
+        "--qwen",
+        default="qwen",
+        help="Path or command for qwen executable (default: qwen)",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=str(Path.cwd()),
+        help="Working directory passed to SDK query options",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="Optional model name. If set, script will call set_model(model).",
+    )
+    parser.add_argument(
+        "--timeout-seconds",
+        type=float,
+        default=90.0,
+        help="Timeout used for control/callback/stream-close options",
+    )
+    parser.add_argument(
+        "--json-only",
+        action="store_true",
+        help="Print only JSON result (no progress logs)",
+    )
+    return parser.parse_args()
+
+
+def check_qwen_cli_available(qwen_cmd: str, timeout_seconds: float) -> str:
+    spawn_info = prepare_spawn_info(qwen_cmd)
+    completed = subprocess.run(
+        [spawn_info.command, *spawn_info.args, "--version"],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=timeout_seconds,
+    )
+    return completed.stdout.strip()
+
+
+def build_options(args: argparse.Namespace) -> dict[str, Any]:
+    return {
+        "cwd": args.cwd,
+        "path_to_qwen_executable": args.qwen,
+        "permission_mode": "yolo",
+        "max_session_turns": 1,
+        "timeout": {
+            "control_request": args.timeout_seconds,
+            "can_use_tool": args.timeout_seconds,
+            "stream_close": args.timeout_seconds,
+        },
+    }
+
+
+def extract_assistant_text(message: dict[str, Any]) -> str:
+    content = message["message"].get("content", [])
+    if not isinstance(content, list):
+        return ""
+
+    text_parts: list[str] = []
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "text":
+            text_parts.append(str(block.get("text", "")))
+    return "".join(text_parts)
+
+
+async def run_async_single(args: argparse.Namespace) -> AsyncSingleResult:
+    token = "SDK_REAL_ASYNC_OK"
+    options = build_options(args)
+    q = query(
+        f"Reply exactly with {token}",
+        options,
+    )
+
+    assistant_text: str | None = None
+    result_text: str | None = None
+    try:
+        async for message in q:
+            if is_sdk_assistant_message(message):
+                assistant_text = (assistant_text or "") + extract_assistant_text(
+                    message
+                )
+            if is_sdk_result_message(message):
+                result_text = str(message.get("result", ""))
+    finally:
+        await q.close()
+
+    ok = token in (assistant_text or "") and token in (result_text or "")
+    return AsyncSingleResult(
+        ok=ok,
+        assistant_text=assistant_text,
+        result_text=result_text,
+        session_id=q.get_session_id(),
+    )
+
+
+async def run_async_controls(args: argparse.Namespace) -> AsyncControlResult:
+    token = "SDK_REAL_CONTROL_OK"
+    options = build_options(args)
+    release_prompt = asyncio.Event()
+
+    async def prompts() -> AsyncIterator[SDKUserMessage]:
+        await release_prompt.wait()
+        yield {
+            "type": "user",
+            "session_id": "00000000-0000-4000-8000-000000000001",
+            "message": {
+                "role": "user",
+                "content": f"Reply exactly with {token}",
+            },
+            "parent_tool_use_id": None,
+        }
+
+    q = query(prompts(), options)
+
+    supported: dict[str, Any] | None = None
+    saw_system_message = False
+    saw_result_message = False
+    try:
+        supported = await q.supported_commands()
+        await q.set_permission_mode("plan")
+        await q.set_permission_mode("yolo")
+        if args.model:
+            await q.set_model(args.model)
+
+        release_prompt.set()
+        async for message in q:
+            if is_sdk_system_message(message):
+                saw_system_message = True
+            if is_sdk_result_message(message):
+                saw_result_message = True
+                break
+    finally:
+        await q.close()
+
+    ok = isinstance(supported, dict) and saw_result_message
+    return AsyncControlResult(
+        ok=ok,
+        supported_commands_type=type(supported).__name__,
+        saw_system_message=saw_system_message,
+        saw_result_message=saw_result_message,
+        session_id=q.get_session_id(),
+    )
+
+
+async def run_stage(stage: str, coro: Awaitable[T], timeout_seconds: float) -> T:
+    try:
+        return await asyncio.wait_for(coro, timeout=timeout_seconds)
+    except TimeoutError as exc:
+        message = f"{stage} timed out after {timeout_seconds} seconds"
+        raise TimeoutError(message) from exc
+
+
+def run_sync(
+    args: argparse.Namespace,
+    on_query: Callable[[SyncQuery], None] | None = None,
+) -> SyncResult:
+    token = "SDK_REAL_SYNC_OK"
+    options = build_options(args)
+    q = query_sync(
+        f"Reply exactly with {token}",
+        options,
+    )
+    if on_query is not None:
+        on_query(q)
+
+    saw_result_message = False
+    result_text: str | None = None
+    try:
+        for message in q:
+            if is_sdk_result_message(message):
+                saw_result_message = True
+                result_text = str(message.get("result", ""))
+                break
+    finally:
+        q.close()
+
+    ok = saw_result_message and token in (result_text or "")
+    return SyncResult(
+        ok=ok,
+        saw_result_message=saw_result_message,
+        result_text=result_text,
+        session_id=q.get_session_id(),
+    )
+
+
+def run_sync_with_timeout(args: argparse.Namespace) -> SyncResult:
+    result_queue: Queue[SyncResult | BaseException] = Queue(maxsize=1)
+    query_holder: dict[str, SyncQuery] = {}
+
+    def remember_query(q: SyncQuery) -> None:
+        query_holder["query"] = q
+
+    def worker() -> None:
+        try:
+            result_queue.put(run_sync(args, on_query=remember_query))
+        except BaseException as exc:
+            result_queue.put(exc)
+
+    thread = threading.Thread(
+        target=worker,
+        name="qwen-sdk-real-smoke-sync",
+        daemon=True,
+    )
+    thread.start()
+
+    try:
+        item = result_queue.get(timeout=args.timeout_seconds)
+    except Empty as exc:
+        q = query_holder.get("query")
+        if q is not None:
+            q.close()
+        raise TimeoutError(
+            f"sync check timed out after {args.timeout_seconds} seconds"
+        ) from exc
+
+    thread.join(timeout=1.0)
+    if isinstance(item, BaseException):
+        raise item
+    return item
+
+
+def build_failure_payload(
+    *,
+    stage: str,
+    exc: BaseException,
+    qwen_version: str | None = None,
+    completed: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": False,
+        "stage": stage,
+        "error": str(exc),
+        "error_type": type(exc).__name__,
+    }
+    if qwen_version is not None:
+        payload["qwen_version"] = qwen_version
+    if completed:
+        payload["completed"] = completed
+    return payload
+
+
+async def main() -> int:
+    args = parse_args()
+
+    try:
+        qwen_version = check_qwen_cli_available(args.qwen, args.timeout_seconds)
+    except (subprocess.CalledProcessError, OSError, subprocess.TimeoutExpired) as exc:
+        payload = build_failure_payload(stage="preflight", exc=exc)
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return 2
+
+    stage = "async single-turn check"
+    completed: dict[str, Any] = {}
+    try:
+        if not args.json_only:
+            print(f"[smoke] qwen version: {qwen_version}")
+            print(f"[smoke] running {stage}...")
+        async_single = await run_stage(
+            stage,
+            run_async_single(args),
+            args.timeout_seconds,
+        )
+        completed["async_single"] = asdict(async_single)
+
+        stage = "async control check"
+        if not args.json_only:
+            print(f"[smoke] running {stage}...")
+        async_controls = await run_stage(
+            stage,
+            run_async_controls(args),
+            args.timeout_seconds,
+        )
+        completed["async_controls"] = asdict(async_controls)
+
+        stage = "sync check"
+        if not args.json_only:
+            print(f"[smoke] running {stage}...")
+        sync_result = run_sync_with_timeout(args)
+        completed["sync"] = asdict(sync_result)
+    except Exception as exc:
+        payload = build_failure_payload(
+            stage=stage,
+            exc=exc,
+            qwen_version=qwen_version,
+            completed=completed,
+        )
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return 1
+
+    all_ok = async_single.ok and async_controls.ok and sync_result.ok
+    payload = {
+        "ok": all_ok,
+        "qwen_version": qwen_version,
+        "async_single": asdict(async_single),
+        "async_controls": asdict(async_controls),
+        "sync": asdict(sync_result),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if all_ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))
diff --git a/packages/sdk-python/src/qwen_code_sdk/__init__.py b/packages/sdk-python/src/qwen_code_sdk/__init__.py
new file mode 100644
index 000000000..b2de65ad2
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/__init__.py
@@ -0,0 +1,108 @@
+"""qwen_code_sdk package exports."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterable, Iterable, Mapping
+from typing import Any
+
+from .errors import (
+    AbortError,
+    ControlRequestTimeoutError,
+    ProcessExitError,
+    QwenSDKError,
+    ValidationError,
+)
+from .protocol import (
+    APIAssistantMessage,
+    APIUserMessage,
+    ContentBlock,
+    SDKAssistantMessage,
+    SDKMessage,
+    SDKPartialAssistantMessage,
+    SDKResultMessage,
+    SDKSystemMessage,
+    SDKUserMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    Usage,
+    is_control_cancel,
+    is_control_request,
+    is_control_response,
+    is_sdk_assistant_message,
+    is_sdk_partial_assistant_message,
+    is_sdk_result_message,
+    is_sdk_system_message,
+    is_sdk_user_message,
+)
+from .query import Query, query
+from .sync_query import SyncQuery
+from .types import (
+    AuthType,
+    CanUseTool,
+    CanUseToolContext,
+    PermissionAllowResult,
+    PermissionDenyResult,
+    PermissionMode,
+    PermissionResult,
+    PermissionSuggestion,
+    QueryOptions,
+    QueryOptionsDict,
+    TimeoutOptions,
+    TimeoutOptionsDict,
+)
+
+
+def query_sync(
+    prompt: str | Iterable[SDKUserMessage] | AsyncIterable[SDKUserMessage],
+    options: QueryOptions | QueryOptionsDict | Mapping[str, Any] | None = None,
+) -> SyncQuery:
+    return SyncQuery(prompt=prompt, options=options)
+
+
+__all__ = [
+    "APIAssistantMessage",
+    "APIUserMessage",
+    "AbortError",
+    "AuthType",
+    "CanUseTool",
+    "CanUseToolContext",
+    "ContentBlock",
+    "ControlRequestTimeoutError",
+    "PermissionAllowResult",
+    "PermissionDenyResult",
+    "PermissionMode",
+    "PermissionResult",
+    "PermissionSuggestion",
+    "ProcessExitError",
+    "Query",
+    "QueryOptions",
+    "QueryOptionsDict",
+    "QwenSDKError",
+    "SDKAssistantMessage",
+    "SDKMessage",
+    "SDKPartialAssistantMessage",
+    "SDKResultMessage",
+    "SDKSystemMessage",
+    "SDKUserMessage",
+    "SyncQuery",
+    "TextBlock",
+    "ThinkingBlock",
+    "TimeoutOptions",
+    "TimeoutOptionsDict",
+    "ToolResultBlock",
+    "ToolUseBlock",
+    "Usage",
+    "ValidationError",
+    "is_control_cancel",
+    "is_control_request",
+    "is_control_response",
+    "is_sdk_assistant_message",
+    "is_sdk_partial_assistant_message",
+    "is_sdk_result_message",
+    "is_sdk_system_message",
+    "is_sdk_user_message",
+    "query",
+    "query_sync",
+]
diff --git a/packages/sdk-python/src/qwen_code_sdk/errors.py b/packages/sdk-python/src/qwen_code_sdk/errors.py
new file mode 100644
index 000000000..e8837f917
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/errors.py
@@ -0,0 +1,27 @@
+"""Error types for qwen_code_sdk."""
+
+from __future__ import annotations
+
+
+class QwenSDKError(Exception):
+    """Base error for all SDK failures."""
+
+
+class ValidationError(QwenSDKError):
+    """Raised when query options are invalid."""
+
+
+class AbortError(QwenSDKError):
+    """Raised when an operation is aborted by caller or transport."""
+
+
+class ProcessExitError(QwenSDKError):
+    """Raised when qwen CLI exits with non-zero status or signal."""
+
+    def __init__(self, message: str, exit_code: int | None = None) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+class ControlRequestTimeoutError(QwenSDKError):
+    """Raised when a control request times out waiting for response."""
diff --git a/packages/sdk-python/src/qwen_code_sdk/json_lines.py b/packages/sdk-python/src/qwen_code_sdk/json_lines.py
new file mode 100644
index 000000000..8b4b33ef7
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/json_lines.py
@@ -0,0 +1,14 @@
+"""JSON lines utilities."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def serialize_json_line(payload: Any) -> str:
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+
+
+def parse_json_line(line: str) -> Any:
+    return json.loads(line)
diff --git a/packages/sdk-python/src/qwen_code_sdk/protocol.py b/packages/sdk-python/src/qwen_code_sdk/protocol.py
new file mode 100644
index 000000000..7e5e50b70
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/protocol.py
@@ -0,0 +1,357 @@
+"""Protocol message types and helpers for qwen stream-json."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypeAlias, TypeGuard
+
+from typing_extensions import NotRequired, TypedDict
+
+from .types import PermissionMode, PermissionSuggestion
+
+
+class Annotation(TypedDict):
+    type: str
+    value: str
+
+
+class Usage(TypedDict):
+    input_tokens: int
+    output_tokens: int
+    cache_creation_input_tokens: NotRequired[int]
+    cache_read_input_tokens: NotRequired[int]
+    total_tokens: NotRequired[int]
+
+
+class ExtendedUsage(Usage, total=False):
+    server_tool_use: dict[str, int]
+    service_tier: str
+    cache_creation: dict[str, int]
+
+
+class CLIPermissionDenial(TypedDict):
+    tool_name: str
+    tool_use_id: str
+    tool_input: Any
+
+
+class TextBlock(TypedDict):
+    type: Literal["text"]
+    text: str
+    annotations: NotRequired[list[Annotation]]
+
+
+class ThinkingBlock(TypedDict):
+    type: Literal["thinking"]
+    thinking: str
+    signature: NotRequired[str]
+    annotations: NotRequired[list[Annotation]]
+
+
+class ToolUseBlock(TypedDict):
+    type: Literal["tool_use"]
+    id: str
+    name: str
+    input: Any
+    annotations: NotRequired[list[Annotation]]
+
+
+class ToolResultBlock(TypedDict):
+    type: Literal["tool_result"]
+    tool_use_id: str
+    content: NotRequired[str | list[ContentBlock]]
+    is_error: NotRequired[bool]
+    annotations: NotRequired[list[Annotation]]
+
+
+ContentBlock: TypeAlias = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+
+
+class APIUserMessage(TypedDict):
+    role: Literal["user"]
+    content: str | list[ContentBlock]
+
+
+class APIAssistantMessage(TypedDict):
+    role: Literal["assistant"]
+    content: list[ContentBlock]
+    id: NotRequired[str]
+    type: NotRequired[Literal["message"]]
+    model: NotRequired[str]
+    stop_reason: NotRequired[str | None]
+    usage: NotRequired[Usage]
+
+
+class SDKUserMessage(TypedDict):
+    type: Literal["user"]
+    session_id: str
+    message: APIUserMessage
+    parent_tool_use_id: str | None
+    uuid: NotRequired[str]
+    options: NotRequired[dict[str, Any]]
+
+
+class SDKAssistantMessage(TypedDict):
+    type: Literal["assistant"]
+    uuid: str
+    session_id: str
+    message: APIAssistantMessage
+    parent_tool_use_id: str | None
+
+
+class MCPServerState(TypedDict):
+    name: str
+    status: str
+
+
+class SDKSystemMessage(TypedDict):
+    type: Literal["system"]
+    subtype: str
+    uuid: str
+    session_id: str
+    data: NotRequired[Any]
+    cwd: NotRequired[str]
+    tools: NotRequired[list[str]]
+    mcp_servers: NotRequired[list[MCPServerState]]
+    model: NotRequired[str]
+    permission_mode: NotRequired[str]
+    slash_commands: NotRequired[list[str]]
+    qwen_code_version: NotRequired[str]
+    output_style: NotRequired[str]
+    agents: NotRequired[list[str]]
+    skills: NotRequired[list[str]]
+    capabilities: NotRequired[dict[str, Any]]
+
+
+class SDKResultMessageSuccess(TypedDict):
+    type: Literal["result"]
+    subtype: Literal["success"]
+    uuid: str
+    session_id: str
+    is_error: Literal[False]
+    duration_ms: int
+    duration_api_ms: int
+    num_turns: int
+    result: str
+    usage: ExtendedUsage
+    permission_denials: list[CLIPermissionDenial]
+
+
+class ResultErrorObject(TypedDict):
+    message: str
+    type: NotRequired[str]
+
+
+class SDKResultMessageError(TypedDict):
+    type: Literal["result"]
+    subtype: Literal["error_max_turns", "error_during_execution"]
+    uuid: str
+    session_id: str
+    is_error: Literal[True]
+    duration_ms: int
+    duration_api_ms: int
+    num_turns: int
+    usage: ExtendedUsage
+    permission_denials: list[CLIPermissionDenial]
+    error: NotRequired[ResultErrorObject]
+
+
+SDKResultMessage: TypeAlias = SDKResultMessageSuccess | SDKResultMessageError
+
+
+class MessageStartStreamEvent(TypedDict):
+    type: Literal["message_start"]
+    message: dict[str, Any]
+
+
+class ContentBlockStartEvent(TypedDict):
+    type: Literal["content_block_start"]
+    index: int
+    content_block: ContentBlock
+
+
+class ContentBlockDeltaEvent(TypedDict):
+    type: Literal["content_block_delta"]
+    index: int
+    delta: dict[str, Any]
+
+
+class ContentBlockStopEvent(TypedDict):
+    type: Literal["content_block_stop"]
+    index: int
+
+
+class MessageStopStreamEvent(TypedDict):
+    type: Literal["message_stop"]
+
+
+StreamEvent: TypeAlias = (
+    MessageStartStreamEvent
+    | ContentBlockStartEvent
+    | ContentBlockDeltaEvent
+    | ContentBlockStopEvent
+    | MessageStopStreamEvent
+)
+
+
+class SDKPartialAssistantMessage(TypedDict):
+    type: Literal["stream_event"]
+    uuid: str
+    session_id: str
+    event: StreamEvent
+    parent_tool_use_id: str | None
+
+
+class CLIControlInterruptRequest(TypedDict):
+    subtype: Literal["interrupt"]
+
+
+class CLIControlPermissionRequest(TypedDict):
+    subtype: Literal["can_use_tool"]
+    tool_name: str
+    tool_use_id: str
+    input: Any
+    permission_suggestions: list[PermissionSuggestion] | None
+    blocked_path: str | None
+
+
+class CLIControlInitializeRequest(TypedDict):
+    subtype: Literal["initialize"]
+    hooks: NotRequired[Any]
+    mcpServers: NotRequired[dict[str, dict[str, Any]]]
+
+
+class CLIControlSetPermissionModeRequest(TypedDict):
+    subtype: Literal["set_permission_mode"]
+    mode: PermissionMode
+
+
+class CLIControlSetModelRequest(TypedDict):
+    subtype: Literal["set_model"]
+    model: str
+
+
+class CLIControlMcpStatusRequest(TypedDict):
+    subtype: Literal["mcp_server_status"]
+
+
+class CLIControlSupportedCommandsRequest(TypedDict):
+    subtype: Literal["supported_commands"]
+
+
+ControlRequestPayload: TypeAlias = (
+    CLIControlInterruptRequest
+    | CLIControlPermissionRequest
+    | CLIControlInitializeRequest
+    | CLIControlSetPermissionModeRequest
+    | CLIControlSetModelRequest
+    | CLIControlMcpStatusRequest
+    | CLIControlSupportedCommandsRequest
+    | dict[str, Any]
+)
+
+
+class CLIControlRequest(TypedDict):
+    type: Literal["control_request"]
+    request_id: str
+    request: ControlRequestPayload
+
+
+class ControlResponseSuccess(TypedDict):
+    subtype: Literal["success"]
+    request_id: str
+    response: Any
+
+
+class ControlResponseError(TypedDict):
+    subtype: Literal["error"]
+    request_id: str
+    error: str | dict[str, Any]
+
+
+class CLIControlResponse(TypedDict):
+    type: Literal["control_response"]
+    response: ControlResponseSuccess | ControlResponseError
+
+
+class ControlCancelRequest(TypedDict):
+    type: Literal["control_cancel_request"]
+    request_id: NotRequired[str]
+
+
+SDKMessage: TypeAlias = (
+    SDKUserMessage
+    | SDKAssistantMessage
+    | SDKSystemMessage
+    | SDKResultMessage
+    | SDKPartialAssistantMessage
+)
+
+
+ControlMessage: TypeAlias = (
+    CLIControlRequest | CLIControlResponse | ControlCancelRequest
+)
+
+
+def is_sdk_user_message(msg: Any) -> TypeGuard[SDKUserMessage]:
+    return isinstance(msg, dict) and msg.get("type") == "user" and "message" in msg
+
+
+def is_sdk_assistant_message(msg: Any) -> TypeGuard[SDKAssistantMessage]:
+    return (
+        isinstance(msg, dict)
+        and msg.get("type") == "assistant"
+        and "session_id" in msg
+        and "message" in msg
+    )
+
+
+def is_sdk_system_message(msg: Any) -> TypeGuard[SDKSystemMessage]:
+    return (
+        isinstance(msg, dict)
+        and msg.get("type") == "system"
+        and "subtype" in msg
+        and "session_id" in msg
+    )
+
+
+def is_sdk_result_message(msg: Any) -> TypeGuard[SDKResultMessage]:
+    return (
+        isinstance(msg, dict)
+        and msg.get("type") == "result"
+        and "subtype" in msg
+        and "session_id" in msg
+    )
+
+
+def is_sdk_partial_assistant_message(msg: Any) -> TypeGuard[SDKPartialAssistantMessage]:
+    return (
+        isinstance(msg, dict)
+        and msg.get("type") == "stream_event"
+        and "session_id" in msg
+        and "event" in msg
+    )
+
+
+def is_control_request(msg: Any) -> TypeGuard[CLIControlRequest]:
+    return (
+        isinstance(msg, dict)
+        and msg.get("type") == "control_request"
+        and "request_id" in msg
+        and "request" in msg
+    )
+
+
+def is_control_response(msg: Any) -> TypeGuard[CLIControlResponse]:
+    return (
+        isinstance(msg, dict)
+        and msg.get("type") == "control_response"
+        and "response" in msg
+    )
+
+
+def is_control_cancel(msg: Any) -> TypeGuard[ControlCancelRequest]:
+    return (
+        isinstance(msg, dict)
+        and msg.get("type") == "control_cancel_request"
+        and "request_id" in msg
+    )
diff --git a/packages/sdk-python/src/qwen_code_sdk/py.typed b/packages/sdk-python/src/qwen_code_sdk/py.typed
new file mode 100644
index 000000000..e69de29bb
diff --git a/packages/sdk-python/src/qwen_code_sdk/query.py b/packages/sdk-python/src/qwen_code_sdk/query.py
new file mode 100644
index 000000000..9bef85781
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/query.py
@@ -0,0 +1,607 @@
+"""Async Query implementation for qwen_code_sdk."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterable, Mapping, MutableMapping
+from dataclasses import dataclass, replace
+from types import TracebackType
+from typing import Any, cast
+from uuid import uuid4
+
+from .errors import AbortError, ControlRequestTimeoutError
+from .json_lines import serialize_json_line
+from .protocol import (
+    CLIControlRequest,
+    CLIControlResponse,
+    SDKMessage,
+    SDKUserMessage,
+    is_control_cancel,
+    is_control_request,
+    is_control_response,
+    is_sdk_assistant_message,
+    is_sdk_partial_assistant_message,
+    is_sdk_result_message,
+    is_sdk_system_message,
+    is_sdk_user_message,
+)
+from .transport import ProcessTransport
+from .types import (
+    CanUseToolContext,
+    PermissionDenyResult,
+    QueryOptions,
+    QueryOptionsDict,
+)
+from .validation import validate_query_options
+
+_DONE = object()
+
+
+@dataclass
+class _PendingControlRequest:
+    future: asyncio.Future[dict[str, Any] | None]
+    cancel_event: asyncio.Event
+    timeout_handle: asyncio.TimerHandle
+
+
+@dataclass
+class _IncomingControlRequest:
+    task: asyncio.Task[None]
+    cancel_event: asyncio.Event
+
+
+class Query:
+    def __init__(
+        self,
+        transport: ProcessTransport,
+        options: QueryOptions,
+        prompt: str | AsyncIterable[SDKUserMessage],
+        session_id: str,
+    ) -> None:
+        self._transport = transport
+        self._options = options
+        self._prompt = prompt
+        self._single_turn = isinstance(prompt, str)
+        self._session_id = session_id
+        self._session_id_locked = bool(options.resume or options.session_id)
+
+        self._message_queue: asyncio.Queue[SDKMessage | Exception | object] = (
+            asyncio.Queue()
+        )
+        self._closed = False
+        self._started = False
+        self._start_lock = asyncio.Lock()
+        self._cancel_event = asyncio.Event()
+
+        self._router_task: asyncio.Task[None] | None = None
+        self._input_task: asyncio.Task[None] | None = None
+        self._initialize_task: asyncio.Task[None] | None = None
+        self._first_result_event = asyncio.Event()
+        self._terminal_event_sent = False
+        self._exhausted = False
+
+        self._pending_control_requests: dict[str, _PendingControlRequest] = {}
+        self._incoming_control_requests: dict[str, _IncomingControlRequest] = {}
+
+    async def _ensure_started(self) -> None:
+        if self._closed:
+            raise RuntimeError("Query is closed")
+        if self._started:
+            return
+
+        async with self._start_lock:
+            if self._closed:
+                raise RuntimeError("Query is closed")
+            if self._started:
+                return
+            await self._transport.start()
+            self._router_task = asyncio.create_task(self._message_router())
+            self._initialize_task = asyncio.create_task(self._initialize())
+
+            if self._single_turn:
+                self._input_task = asyncio.create_task(self._send_single_turn_prompt())
+            else:
+                self._input_task = asyncio.create_task(
+                    self.stream_input(self._prompt)  # type: ignore[arg-type]
+                )
+            self._started = True
+
+    async def _initialize(self) -> None:
+        try:
+            payload: dict[str, Any] = {"hooks": None}
+            await self._send_control_request("initialize", payload)
+        except Exception as exc:
+            await self._finish_with_error(exc)
+
+    async def _send_single_turn_prompt(self) -> None:
+        try:
+            assert isinstance(self._prompt, str)
+            await self._wait_initialized()
+            message: SDKUserMessage = {
+                "type": "user",
+                "session_id": self._session_id,
+                "message": {
+                    "role": "user",
+                    "content": self._prompt,
+                },
+                "parent_tool_use_id": None,
+            }
+
+            await self._write_payload(message)
+        except Exception as exc:
+            await self._finish_with_error(exc)
+            raise
+
+    async def _wait_initialized(self) -> None:
+        if self._initialize_task is None:
+            return
+        await self._initialize_task
+
+    async def _message_router(self) -> None:
+        try:
+            async for message in self._transport.read_messages():
+                await self._route_message(message)
+                if self._closed:
+                    break
+
+            if self._closed:
+                return
+
+            if self._transport.exit_error is not None:
+                await self._finish_with_error(self._transport.exit_error)
+                return
+
+            await self._finish()
+        except Exception as exc:  # pragma: no cover - critical propagation path
+            await self._finish_with_error(exc)
+
+    async def _route_message(self, message: Any) -> None:
+        self._maybe_update_session_id(message)
+
+        if is_control_request(message):
+            self._start_incoming_control_request(message)
+            return
+
+        if is_control_response(message):
+            self._handle_control_response(message)
+            return
+
+        if is_control_cancel(message):
+            self._handle_control_cancel_request(message)
+            return
+
+        if is_sdk_result_message(message):
+            self._first_result_event.set()
+            if self._single_turn:
+                self._transport.end_input()
+            await self._message_queue.put(message)
+            return
+
+        if (
+            is_sdk_system_message(message)
+            or is_sdk_assistant_message(message)
+            or is_sdk_user_message(message)
+            or is_sdk_partial_assistant_message(message)
+        ):
+            await self._message_queue.put(message)
+            return
+
+    def _maybe_update_session_id(self, message: Any) -> None:
+        if self._session_id_locked or not isinstance(message, Mapping):
+            return
+
+        session_id = message.get("session_id")
+        if isinstance(session_id, str) and session_id:
+            self._session_id = session_id
+            self._session_id_locked = True
+
+    def _start_incoming_control_request(self, request: CLIControlRequest) -> None:
+        request_id = request["request_id"]
+        cancel_event = asyncio.Event()
+
+        async def runner() -> None:
+            try:
+                await self._handle_control_request(request, cancel_event)
+            except asyncio.CancelledError:
+                pass
+            except Exception as exc:  # pragma: no cover - fatal background path
+                await self._finish_with_error(exc)
+            finally:
+                self._incoming_control_requests.pop(request_id, None)
+
+        task = asyncio.create_task(runner())
+        self._incoming_control_requests[request_id] = _IncomingControlRequest(
+            task=task,
+            cancel_event=cancel_event,
+        )
+
+    async def _handle_control_request(
+        self,
+        request: CLIControlRequest,
+        cancel_event: asyncio.Event,
+    ) -> None:
+        request_id = request["request_id"]
+        payload = request["request"]
+        subtype = payload.get("subtype")
+
+        try:
+            if subtype == "can_use_tool":
+                response = await self._handle_permission_request(
+                    cast(MutableMapping[str, Any], payload),
+                    cancel_event,
+                )
+            elif subtype == "mcp_message":
+                raise RuntimeError("mcp_message is unsupported in python sdk v1")
+            else:
+                raise RuntimeError(f"Unknown control request subtype: {subtype}")
+
+            if cancel_event.is_set():
+                return
+
+            await self._send_control_response(
+                request_id, success=True, response=response
+            )
+        except Exception as exc:
+            if cancel_event.is_set():
+                return
+            await self._send_control_response(
+                request_id,
+                success=False,
+                response=str(exc),
+            )
+
+    async def _handle_permission_request(
+        self,
+        payload: MutableMapping[str, Any],
+        cancel_event: asyncio.Event,
+    ) -> dict[str, Any]:
+        tool_name = str(payload.get("tool_name", ""))
+        tool_input = payload.get("input")
+        if not isinstance(tool_input, dict):
+            tool_input = {}
+
+        if self._options.can_use_tool is None:
+            return {"behavior": "deny", "message": "Denied"}
+
+        context: CanUseToolContext = {
+            "cancel_event": cancel_event,
+            "suggestions": payload.get("permission_suggestions"),
+            "blocked_path": payload.get("blocked_path"),
+        }
+
+        try:
+            result = await asyncio.wait_for(
+                self._options.can_use_tool(tool_name, tool_input, context),
+                timeout=self._options.timeout.can_use_tool,
+            )
+        except asyncio.TimeoutError:
+            return {
+                "behavior": "deny",
+                "message": "Permission request timed out",
+            }
+        except asyncio.CancelledError:
+            if cancel_event.is_set():
+                raise
+            return {
+                "behavior": "deny",
+                "message": "Permission check failed: callback cancelled",
+            }
+        except Exception as exc:
+            return {
+                "behavior": "deny",
+                "message": f"Permission check failed: {exc}",
+            }
+
+        behavior = result.get("behavior")
+        if behavior == "allow":
+            return {
+                "behavior": "allow",
+                "updatedInput": result.get("updatedInput", tool_input),
+            }
+
+        deny_result = cast(PermissionDenyResult, result)
+        return {
+            "behavior": "deny",
+            "message": deny_result.get("message", "Denied"),
+            **(
+                {"interrupt": deny_result["interrupt"]}
+                if "interrupt" in deny_result
+                else {}
+            ),
+        }
+
+    def _handle_control_response(self, response: CLIControlResponse) -> None:
+        payload = response["response"]
+        request_id = payload["request_id"]
+
+        pending = self._pending_control_requests.pop(request_id, None)
+        if pending is None:
+            return
+
+        pending.timeout_handle.cancel()
+
+        if payload["subtype"] == "success":
+            if not pending.future.done():
+                pending.future.set_result(payload.get("response"))
+        else:
+            error = payload.get("error", "Unknown control error")
+            if isinstance(error, dict):
+                error_message = str(error.get("message", "Unknown control error"))
+            else:
+                error_message = str(error)
+            if not pending.future.done():
+                pending.future.set_exception(RuntimeError(error_message))
+
+    def _handle_control_cancel_request(self, message: Mapping[str, Any]) -> None:
+        request_id = message.get("request_id")
+        if not isinstance(request_id, str):
+            return
+
+        pending = self._pending_control_requests.pop(request_id, None)
+        if pending is not None:
+            pending.timeout_handle.cancel()
+            pending.cancel_event.set()
+            if not pending.future.done():
+                pending.future.set_exception(AbortError("Control request cancelled"))
+
+        incoming = self._incoming_control_requests.get(request_id)
+        if incoming is None:
+            return
+
+        incoming.cancel_event.set()
+        incoming.task.cancel()
+
+    async def _send_control_request(
+        self,
+        subtype: str,
+        data: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        if self._closed:
+            raise RuntimeError("Query is closed")
+
+        if subtype != "initialize":
+            await self._wait_initialized()
+
+        request_id = str(uuid4())
+
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[dict[str, Any] | None] = loop.create_future()
+        cancel_event = asyncio.Event()
+
+        def on_timeout() -> None:
+            pending = self._pending_control_requests.pop(request_id, None)
+            if pending is None:
+                return
+            pending.cancel_event.set()
+            if not pending.future.done():
+                pending.future.set_exception(
+                    ControlRequestTimeoutError(f"Control request timeout: {subtype}")
+                )
+
+        timeout_handle = loop.call_later(
+            self._options.timeout.control_request,
+            on_timeout,
+        )
+
+        self._pending_control_requests[request_id] = _PendingControlRequest(
+            future=future,
+            cancel_event=cancel_event,
+            timeout_handle=timeout_handle,
+        )
+
+        request_payload: dict[str, Any] = {"subtype": subtype}
+        if data:
+            request_payload.update(data)
+
+        payload: CLIControlRequest = {
+            "type": "control_request",
+            "request_id": request_id,
+            "request": request_payload,
+        }
+
+        await self._write_payload(payload)
+        return await future
+
+    async def _send_control_response(
+        self,
+        request_id: str,
+        *,
+        success: bool,
+        response: Any,
+    ) -> None:
+        payload: CLIControlResponse
+        if success:
+            payload = {
+                "type": "control_response",
+                "response": {
+                    "subtype": "success",
+                    "request_id": request_id,
+                    "response": response,
+                },
+            }
+        else:
+            payload = {
+                "type": "control_response",
+                "response": {
+                    "subtype": "error",
+                    "request_id": request_id,
+                    "error": str(response),
+                },
+            }
+
+        await self._write_payload(payload)
+
+    async def _write_payload(self, payload: Any) -> None:
+        self._transport.write(serialize_json_line(payload))
+        await self._transport.drain()
+
+    async def stream_input(self, messages: AsyncIterable[SDKUserMessage]) -> None:
+        try:
+            if self._closed:
+                raise RuntimeError("Query is closed")
+
+            await self._wait_initialized()
+
+            async for message in messages:
+                if self._cancel_event.is_set() or self._closed:
+                    break
+                await self._write_payload(message)
+
+            if not self._single_turn:
+                try:
+                    await asyncio.wait_for(
+                        self._first_result_event.wait(),
+                        timeout=self._options.timeout.stream_close,
+                    )
+                except asyncio.TimeoutError:
+                    pass
+
+                self._transport.end_input()
+        except Exception as exc:
+            await self._finish_with_error(exc)
+            raise
+
+    async def interrupt(self) -> None:
+        await self._ensure_started()
+        await self._send_control_request("interrupt")
+
+    async def set_permission_mode(self, mode: str) -> None:
+        await self._ensure_started()
+        await self._send_control_request("set_permission_mode", {"mode": mode})
+
+    async def set_model(self, model: str) -> None:
+        await self._ensure_started()
+        await self._send_control_request("set_model", {"model": model})
+
+    async def supported_commands(self) -> dict[str, Any] | None:
+        await self._ensure_started()
+        return await self._send_control_request("supported_commands")
+
+    async def mcp_server_status(self) -> dict[str, Any] | None:
+        await self._ensure_started()
+        return await self._send_control_request("mcp_server_status")
+
+    @property
+    def control_request_timeout(self) -> float:
+        return self._options.timeout.control_request
+
+    def get_session_id(self) -> str:
+        return self._session_id
+
+    def is_closed(self) -> bool:
+        return self._closed
+
+    def _fail_pending_control_requests(self, error: Exception) -> None:
+        for request_id, pending in list(self._pending_control_requests.items()):
+            pending.timeout_handle.cancel()
+            pending.cancel_event.set()
+            if not pending.future.done():
+                pending.future.set_exception(error)
+            self._pending_control_requests.pop(request_id, None)
+
+    async def _cancel_incoming_control_requests(self) -> None:
+        current_task = asyncio.current_task()
+        tasks: list[asyncio.Task[None]] = []
+
+        for incoming in list(self._incoming_control_requests.values()):
+            incoming.cancel_event.set()
+            if incoming.task is current_task:
+                continue
+            incoming.task.cancel()
+            tasks.append(incoming.task)
+
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+
+        self._closed = True
+        self._cancel_event.set()
+
+        error = RuntimeError("Query is closed")
+        self._fail_pending_control_requests(error)
+        await self._cancel_incoming_control_requests()
+
+        await self._transport.close()
+
+        if self._input_task is not None:
+            self._input_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await self._input_task
+
+        if self._router_task is not None:
+            with contextlib.suppress(Exception):
+                await self._router_task
+
+        await self._finish()
+
+    async def _finish(self) -> None:
+        if self._terminal_event_sent:
+            return
+        self._terminal_event_sent = True
+        await self._message_queue.put(_DONE)
+
+    async def _finish_with_error(self, exc: Exception) -> None:
+        if self._terminal_event_sent:
+            return
+        self._closed = True
+        self._terminal_event_sent = True
+        self._cancel_event.set()
+        self._fail_pending_control_requests(exc)
+        await self._cancel_incoming_control_requests()
+        await self._transport.close()
+        await self._message_queue.put(exc)
+        await self._message_queue.put(_DONE)
+
+    def __aiter__(self) -> Query:
+        return self
+
+    async def __anext__(self) -> SDKMessage:
+        if self._exhausted:
+            raise StopAsyncIteration
+        await self._ensure_started()
+        item = await self._message_queue.get()
+
+        if item is _DONE:
+            self._exhausted = True
+            raise StopAsyncIteration
+
+        if isinstance(item, Exception):
+            raise item
+
+        return cast(SDKMessage, item)
+
+    async def __aenter__(self) -> Query:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+
+def query(
+    prompt: str | AsyncIterable[SDKUserMessage],
+    options: QueryOptions | QueryOptionsDict | Mapping[str, Any] | None = None,
+) -> Query:
+    if isinstance(options, QueryOptions):
+        parsed_options = replace(options)
+    else:
+        parsed_options = QueryOptions.from_mapping(options)
+
+    validate_query_options(parsed_options)
+
+    session_id = parsed_options.resume or parsed_options.session_id
+    if session_id is None and not parsed_options.continue_session:
+        session_id = str(uuid4())
+    if parsed_options.resume is None and not parsed_options.continue_session:
+        parsed_options = replace(parsed_options, session_id=session_id)
+
+    transport = ProcessTransport(parsed_options)
+    return Query(transport, parsed_options, prompt, session_id or "")
diff --git a/packages/sdk-python/src/qwen_code_sdk/sync_query.py b/packages/sdk-python/src/qwen_code_sdk/sync_query.py
new file mode 100644
index 000000000..c08713dd6
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/sync_query.py
@@ -0,0 +1,217 @@
+"""Synchronous wrapper around the async Query API."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import warnings
+from collections.abc import AsyncIterable, AsyncIterator, Iterable, Mapping
+from queue import Queue
+from typing import Any, cast
+
+from .protocol import SDKMessage, SDKUserMessage
+from .query import Query, query
+from .types import QueryOptions, QueryOptionsDict
+
+_STOP = object()
+_SYNC_TIMEOUT_MARGIN = 5.0
+
+
+class SyncQuery:
+    def __init__(
+        self,
+        prompt: str | Iterable[SDKUserMessage] | AsyncIterable[SDKUserMessage],
+        options: QueryOptions | QueryOptionsDict | Mapping[str, Any] | None = None,
+    ) -> None:
+        self._queue: Queue[SDKMessage | Exception | object] = Queue()
+        self._ready = threading.Event()
+        self._shutdown = threading.Event()
+        self._stop_sent = threading.Event()
+        self._exhausted = False
+        self._query: Query | None = None
+        self._consumer_task: asyncio.Task[None] | None = None
+
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(
+            target=self._run_loop,
+            name="qwen-sdk-sync-loop",
+            daemon=True,
+        )
+        self._thread.start()
+
+        if isinstance(prompt, str) or isinstance(prompt, AsyncIterable):
+            source_prompt: str | AsyncIterable[SDKUserMessage] = prompt
+        else:
+            source_prompt = _iterable_to_async(prompt)
+
+        future = asyncio.run_coroutine_threadsafe(
+            self._bootstrap(source_prompt, options),
+            self._loop,
+        )
+        try:
+            future.result()
+        except Exception:
+            self._stop_loop()
+            raise
+
+    def _run_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    async def _bootstrap(
+        self,
+        prompt: str | AsyncIterable[SDKUserMessage],
+        options: QueryOptions | QueryOptionsDict | Mapping[str, Any] | None,
+    ) -> None:
+        self._query = query(prompt=prompt, options=options)
+        self._ready.set()
+        self._consumer_task = asyncio.create_task(self._consume())
+
+    async def _consume(self) -> None:
+        assert self._query is not None
+        try:
+            async for message in self._query:
+                self._queue.put(message)
+        except Exception as exc:
+            self._queue.put(exc)
+        finally:
+            if not self._stop_sent.is_set():
+                self._stop_sent.set()
+                self._queue.put(_STOP)
+
+    def _require_query(self) -> Query:
+        self._ready.wait(timeout=30)
+        if self._query is None:
+            raise RuntimeError("SyncQuery failed to initialize")
+        return self._query
+
+    def __iter__(self) -> SyncQuery:
+        return self
+
+    def __next__(self) -> SDKMessage:
+        if self._exhausted:
+            raise StopIteration
+        item = self._queue.get()
+
+        if item is _STOP:
+            self._exhausted = True
+            raise StopIteration
+
+        if isinstance(item, Exception):
+            raise item
+
+        return cast(SDKMessage, item)
+
+    def __enter__(self) -> SyncQuery:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def interrupt(self) -> None:
+        q = self._require_query()
+        asyncio.run_coroutine_threadsafe(q.interrupt(), self._loop).result(
+            timeout=q.control_request_timeout + _SYNC_TIMEOUT_MARGIN
+        )
+
+    def set_model(self, model: str) -> None:
+        q = self._require_query()
+        asyncio.run_coroutine_threadsafe(q.set_model(model), self._loop).result(
+            timeout=q.control_request_timeout + _SYNC_TIMEOUT_MARGIN
+        )
+
+    def set_permission_mode(self, mode: str) -> None:
+        q = self._require_query()
+        asyncio.run_coroutine_threadsafe(
+            q.set_permission_mode(mode),
+            self._loop,
+        ).result(timeout=q.control_request_timeout + _SYNC_TIMEOUT_MARGIN)
+
+    def supported_commands(self) -> Any:
+        q = self._require_query()
+        return asyncio.run_coroutine_threadsafe(
+            q.supported_commands(),
+            self._loop,
+        ).result(timeout=q.control_request_timeout + _SYNC_TIMEOUT_MARGIN)
+
+    def mcp_server_status(self) -> Any:
+        q = self._require_query()
+        return asyncio.run_coroutine_threadsafe(
+            q.mcp_server_status(),
+            self._loop,
+        ).result(timeout=q.control_request_timeout + _SYNC_TIMEOUT_MARGIN)
+
+    def get_session_id(self) -> str:
+        q = self._require_query()
+        return q.get_session_id()
+
+    def is_closed(self) -> bool:
+        q = self._require_query()
+        return q.is_closed()
+
+    def close(self) -> None:
+        if self._shutdown.is_set():
+            return
+
+        self._shutdown.set()
+
+        q = self._query
+        if q is not None:
+            try:
+                asyncio.run_coroutine_threadsafe(q.close(), self._loop).result(
+                    timeout=30
+                )
+            except Exception:
+                pass
+
+        # Wait for _consume() to put _STOP before stopping the loop,
+        # otherwise consumers blocked on queue.get() will deadlock.
+        if self._consumer_task is not None:
+            try:
+                asyncio.run_coroutine_threadsafe(
+                    self._await_consumer(), self._loop
+                ).result(timeout=5)
+            except Exception:
+                pass
+
+        if not self._stop_sent.is_set():
+            self._stop_sent.set()
+            self._queue.put(_STOP)
+        self._stop_loop()
+
+    async def _await_consumer(self) -> None:
+        if self._consumer_task is not None:
+            try:
+                await asyncio.wait_for(self._consumer_task, timeout=5.0)
+            except Exception:
+                pass
+
+    def _stop_loop(self) -> None:
+        if self._loop.is_running():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+        self._thread.join(timeout=5)
+        if not self._loop.is_closed():
+            self._loop.close()
+
+    def __del__(self) -> None:
+        try:
+            if not self._shutdown.is_set():
+                warnings.warn(
+                    "SyncQuery was not closed. "
+                    "Use 'with SyncQuery(...) as q:' or call q.close() explicitly.",
+                    ResourceWarning,
+                    stacklevel=1,
+                )
+                try:
+                    self.close()
+                except Exception:
+                    pass
+        except AttributeError:
+            pass
+
+
+async def _iterable_to_async(
+    messages: Iterable[SDKUserMessage],
+) -> AsyncIterator[SDKUserMessage]:
+    for message in messages:
+        yield message
diff --git a/packages/sdk-python/src/qwen_code_sdk/transport.py b/packages/sdk-python/src/qwen_code_sdk/transport.py
new file mode 100644
index 000000000..854236494
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/transport.py
@@ -0,0 +1,243 @@
+"""Process transport for qwen CLI stream-json protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import subprocess
+import sys
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .errors import ProcessExitError
+from .json_lines import parse_json_line
+from .types import QueryOptions
+
+
+@dataclass(frozen=True)
+class SpawnInfo:
+    command: str
+    args: list[str]
+
+
+def prepare_spawn_info(path_to_qwen_executable: str | None) -> SpawnInfo:
+    if path_to_qwen_executable is None:
+        return SpawnInfo(command="qwen", args=[])
+
+    spec = path_to_qwen_executable
+    if os.path.sep not in spec and (
+        os.path.altsep is None or os.path.altsep not in spec
+    ):
+        return SpawnInfo(command=spec, args=[])
+
+    path = Path(spec).expanduser().resolve()
+
+    suffix = path.suffix.lower()
+    if suffix == ".py":
+        return SpawnInfo(command=sys.executable, args=[str(path)])
+    if suffix in {".js", ".mjs", ".cjs"}:
+        return SpawnInfo(command="node", args=[str(path)])
+
+    return SpawnInfo(command=str(path), args=[])
+
+
+class ProcessTransport:
+    def __init__(self, options: QueryOptions):
+        self._options = options
+        self._process: asyncio.subprocess.Process | None = None
+        self._stderr_task: asyncio.Task[None] | None = None
+        self._closed = False
+        self._input_closed = False
+        self._exit_error: Exception | None = None
+
+    @property
+    def exit_error(self) -> Exception | None:
+        return self._exit_error
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    async def start(self) -> None:
+        if self._closed:
+            raise RuntimeError("Transport is closed")
+        if self._process is not None:
+            return
+
+        spawn_info = prepare_spawn_info(self._options.path_to_qwen_executable)
+        args = [*spawn_info.args, *build_cli_arguments(self._options)]
+        stderr_target = (
+            asyncio.subprocess.PIPE
+            if self._options.debug or self._options.stderr is not None
+            else subprocess.DEVNULL
+        )
+
+        self._process = await asyncio.create_subprocess_exec(
+            spawn_info.command,
+            *args,
+            cwd=self._options.cwd,
+            env={**os.environ, **(self._options.env or {})},
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=stderr_target,
+        )
+
+        if self._options.debug or self._options.stderr is not None:
+            self._stderr_task = asyncio.create_task(self._forward_stderr())
+
+    async def _forward_stderr(self) -> None:
+        if self._process is None or self._process.stderr is None:
+            return
+
+        while True:
+            chunk = await self._process.stderr.readline()
+            if not chunk:
+                return
+            text = chunk.decode("utf-8", errors="replace").rstrip("\n")
+            try:
+                if self._options.stderr is not None:
+                    self._options.stderr(text)
+                elif self._options.debug:
+                    print(text, file=sys.stderr)
+            except Exception:
+                print(text, file=sys.stderr)
+
+    def write(self, data: str) -> None:
+        if self._closed:
+            raise RuntimeError("Transport is closed")
+        if self._process is None or self._process.stdin is None:
+            raise RuntimeError("Transport is not started")
+        if self._input_closed:
+            raise RuntimeError("Transport input is already closed")
+
+        self._process.stdin.write(data.encode("utf-8"))
+
+    async def drain(self) -> None:
+        if self._process is None or self._process.stdin is None:
+            return
+        await self._process.stdin.drain()
+
+    def end_input(self) -> None:
+        if self._closed or self._input_closed:
+            return
+        if self._process is None or self._process.stdin is None:
+            return
+        self._process.stdin.close()
+        self._input_closed = True
+
+    async def read_messages(self) -> AsyncIterator[Any]:
+        if self._process is None or self._process.stdout is None:
+            raise RuntimeError("Transport is not started")
+
+        while True:
+            line = await self._process.stdout.readline()
+            if not line:
+                break
+
+            raw = line.decode("utf-8", errors="replace").strip()
+            if not raw:
+                continue
+            try:
+                yield parse_json_line(raw)
+            except json.JSONDecodeError:
+                continue
+
+        await self._finalize_exit()
+
+    async def wait_for_exit(self) -> None:
+        if self._process is None:
+            return
+        await self._finalize_exit()
+
+    async def _finalize_exit(self) -> None:
+        if self._process is None:
+            return
+
+        return_code = self._process.returncode
+        if return_code is None:
+            return_code = await self._process.wait()
+
+        if return_code != 0 and self._exit_error is None:
+            self._exit_error = ProcessExitError(
+                f"CLI process exited with code {return_code}",
+                exit_code=return_code,
+            )
+
+        if self._stderr_task is not None:
+            await self._stderr_task
+            self._stderr_task = None
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+
+        self._closed = True
+
+        if self._process is None:
+            return
+
+        if self._process.stdin is not None and not self._input_closed:
+            self._process.stdin.close()
+            self._input_closed = True
+
+        if self._process.returncode is None:
+            self._process.terminate()
+            try:
+                await asyncio.wait_for(self._process.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                self._process.kill()
+                await self._process.wait()
+
+        await self._finalize_exit()
+
+
+def build_cli_arguments(options: QueryOptions) -> list[str]:
+    args: list[str] = [
+        "--input-format",
+        "stream-json",
+        "--output-format",
+        "stream-json",
+        "--channel=SDK",
+    ]
+
+    if options.model:
+        args.extend(["--model", options.model])
+
+    if options.system_prompt:
+        args.extend(["--system-prompt", options.system_prompt])
+
+    if options.append_system_prompt:
+        args.extend(["--append-system-prompt", options.append_system_prompt])
+
+    if options.permission_mode:
+        args.extend(["--approval-mode", options.permission_mode])
+
+    if options.max_session_turns is not None:
+        args.extend(["--max-session-turns", str(options.max_session_turns)])
+
+    if options.core_tools:
+        args.extend(["--core-tools", ",".join(options.core_tools)])
+
+    if options.exclude_tools:
+        args.extend(["--exclude-tools", ",".join(options.exclude_tools)])
+
+    if options.allowed_tools:
+        args.extend(["--allowed-tools", ",".join(options.allowed_tools)])
+
+    if options.auth_type:
+        args.extend(["--auth-type", options.auth_type])
+
+    if options.include_partial_messages:
+        args.append("--include-partial-messages")
+
+    if options.resume:
+        args.extend(["--resume", options.resume])
+    elif options.continue_session:
+        args.append("--continue")
+    elif options.session_id:
+        args.extend(["--session-id", options.session_id])
+
+    return args
diff --git a/packages/sdk-python/src/qwen_code_sdk/types.py b/packages/sdk-python/src/qwen_code_sdk/types.py
new file mode 100644
index 000000000..3d8ec7203
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/types.py
@@ -0,0 +1,323 @@
+"""Public type definitions for qwen_code_sdk."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, MutableMapping
+from dataclasses import dataclass
+from inspect import Parameter, Signature, iscoroutinefunction, signature
+from typing import (
+    Any,
+    Literal,
+    TypeAlias,
+    TypedDict,
+    cast,
+)
+
+from typing_extensions import NotRequired
+
+PermissionMode: TypeAlias = Literal["default", "plan", "auto-edit", "yolo"]
+AuthType: TypeAlias = Literal[
+    "openai",
+    "anthropic",
+    "qwen-oauth",
+    "gemini",
+    "vertex-ai",
+]
+
+
+class PermissionSuggestion(TypedDict):
+    type: Literal["allow", "deny", "modify"]
+    label: str
+    description: NotRequired[str]
+    modifiedInput: NotRequired[Any]
+
+
+class PermissionAllowResult(TypedDict):
+    behavior: Literal["allow"]
+    updatedInput: NotRequired[dict[str, Any]]
+
+
+class PermissionDenyResult(TypedDict):
+    behavior: Literal["deny"]
+    message: NotRequired[str]
+    interrupt: NotRequired[bool]
+
+
+PermissionResult: TypeAlias = PermissionAllowResult | PermissionDenyResult
+
+
+class CanUseToolContext(TypedDict):
+    cancel_event: Any
+    suggestions: list[PermissionSuggestion] | None
+    blocked_path: str | None
+
+
+CanUseTool: TypeAlias = Callable[
+    [str, dict[str, Any], CanUseToolContext],
+    Awaitable[PermissionResult],
+]
+
+
+class TimeoutOptionsDict(TypedDict, total=False):
+    """Timeout configuration. All values are in seconds."""
+
+    can_use_tool: float
+    control_request: float
+    stream_close: float
+
+
+@dataclass(frozen=True)
+class TimeoutOptions:
+    can_use_tool: float = 60.0
+    control_request: float = 60.0
+    stream_close: float = 60.0
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any] | None) -> TimeoutOptions:
+        if value is None:
+            return cls()
+
+        def _read(name: str, default: float) -> float:
+            raw = value.get(name, default)
+            if isinstance(raw, bool) or not isinstance(raw, (int, float)):
+                raise TypeError(f"timeout.{name} must be a positive number")
+            if raw <= 0:
+                raise ValueError(f"timeout.{name} must be a positive number")
+            return float(raw)
+
+        return cls(
+            can_use_tool=_read("can_use_tool", 60.0),
+            control_request=_read("control_request", 60.0),
+            stream_close=_read("stream_close", 60.0),
+        )
+
+
+class QueryOptionsDict(TypedDict, total=False):
+    cwd: str
+    model: str
+    path_to_qwen_executable: str
+    permission_mode: PermissionMode
+    can_use_tool: CanUseTool
+    env: dict[str, str]
+    system_prompt: str
+    append_system_prompt: str
+    debug: bool
+    max_session_turns: int
+    core_tools: list[str]
+    exclude_tools: list[str]
+    allowed_tools: list[str]
+    auth_type: AuthType
+    include_partial_messages: bool
+    resume: str
+    continue_session: bool
+    session_id: str
+    timeout: TimeoutOptionsDict
+    mcp_servers: dict[str, dict[str, Any]]
+    stderr: Callable[[str], None]
+
+
+@dataclass
+class QueryOptions:
+    cwd: str | None = None
+    model: str | None = None
+    path_to_qwen_executable: str | None = None
+    permission_mode: PermissionMode | None = None
+    can_use_tool: CanUseTool | None = None
+    env: dict[str, str] | None = None
+    system_prompt: str | None = None
+    append_system_prompt: str | None = None
+    debug: bool = False
+    max_session_turns: int | None = None
+    core_tools: list[str] | None = None
+    exclude_tools: list[str] | None = None
+    allowed_tools: list[str] | None = None
+    auth_type: AuthType | None = None
+    include_partial_messages: bool = False
+    resume: str | None = None
+    continue_session: bool = False
+    session_id: str | None = None
+    timeout: TimeoutOptions = TimeoutOptions()
+    mcp_servers: dict[str, dict[str, Any]] | None = None
+    stderr: Callable[[str], None] | None = None
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any] | None) -> QueryOptions:
+        if value is None:
+            return cls()
+
+        data: MutableMapping[str, Any] = dict(value)
+        timeout = TimeoutOptions.from_mapping(data.get("timeout"))
+
+        return cls(
+            cwd=_as_optional_str(data, "cwd"),
+            model=_as_optional_str(data, "model"),
+            path_to_qwen_executable=_as_optional_str(data, "path_to_qwen_executable"),
+            permission_mode=cast(
+                PermissionMode | None,
+                _as_optional_str(data, "permission_mode"),
+            ),
+            can_use_tool=cast(
+                CanUseTool | None,
+                _as_optional_callable(data, "can_use_tool"),
+            ),
+            env=_as_optional_str_dict(data, "env"),
+            system_prompt=_as_optional_str(data, "system_prompt"),
+            append_system_prompt=_as_optional_str(data, "append_system_prompt"),
+            debug=_as_optional_bool(data, "debug") or False,
+            max_session_turns=_as_optional_int(data, "max_session_turns"),
+            core_tools=_as_optional_str_list(data, "core_tools"),
+            exclude_tools=_as_optional_str_list(data, "exclude_tools"),
+            allowed_tools=_as_optional_str_list(data, "allowed_tools"),
+            auth_type=cast(
+                AuthType | None,
+                _as_optional_str(data, "auth_type"),
+            ),
+            include_partial_messages=_as_optional_bool(data, "include_partial_messages")
+            or False,
+            resume=_as_optional_str(data, "resume"),
+            continue_session=_as_optional_bool(data, "continue_session") or False,
+            session_id=_as_optional_str(data, "session_id"),
+            timeout=timeout,
+            mcp_servers=_as_optional_nested_dict(data, "mcp_servers"),
+            stderr=cast(
+                Callable[[str], None] | None,
+                _as_optional_callable(data, "stderr"),
+            ),
+        )
+
+
+def _as_optional_str(data: Mapping[str, Any], key: str) -> str | None:
+    raw = data.get(key)
+    if raw is None:
+        return None
+    if not isinstance(raw, str):
+        raise TypeError(f"{key} must be a string")
+    return raw
+
+
+def _as_optional_int(data: Mapping[str, Any], key: str) -> int | None:
+    raw = data.get(key)
+    if raw is None:
+        return None
+    if isinstance(raw, bool) or not isinstance(raw, int):
+        raise TypeError(f"{key} must be an integer")
+    return int(raw)
+
+
+def _as_optional_bool(data: Mapping[str, Any], key: str) -> bool | None:
+    raw = data.get(key)
+    if raw is None:
+        return None
+    if not isinstance(raw, bool):
+        raise TypeError(f"{key} must be a boolean")
+    return raw
+
+
+def _as_optional_callable(
+    data: Mapping[str, Any], key: str
+) -> Callable[..., Any] | None:
+    raw = data.get(key)
+    if raw is None:
+        return None
+    if not callable(raw):
+        raise TypeError(f"{key} must be callable")
+    if key == "can_use_tool":
+        _validate_can_use_tool_callable(raw, error_type=TypeError)
+    elif key == "stderr":
+        _validate_stderr_callable(raw, error_type=TypeError)
+    return cast(Callable[..., Any], raw)
+
+
+def _validate_can_use_tool_callable(value: object, error_type: type[Exception]) -> None:
+    if not callable(value):
+        raise error_type("can_use_tool must be callable")
+
+    if not iscoroutinefunction(value):
+        raise error_type("can_use_tool must be an async callable")
+
+    try:
+        sig = signature(value)
+    except (TypeError, ValueError):
+        return
+
+    if not _supports_argument_count(sig, 3):
+        raise error_type("can_use_tool must accept exactly 3 positional arguments")
+
+
+def _validate_stderr_callable(value: object, error_type: type[Exception]) -> None:
+    if not callable(value):
+        raise error_type("stderr must be callable")
+
+    try:
+        sig = signature(value)
+    except (TypeError, ValueError):
+        return
+
+    if not _supports_argument_count(sig, 1):
+        raise error_type("stderr must accept exactly 1 positional argument")
+
+
+def _supports_argument_count(sig: Signature, count: int) -> bool:
+    params = list(sig.parameters.values())
+    positional_params = [
+        param
+        for param in params
+        if param.kind
+        in (
+            Parameter.POSITIONAL_ONLY,
+            Parameter.POSITIONAL_OR_KEYWORD,
+        )
+    ]
+    required_positional = [
+        param for param in positional_params if param.default is Parameter.empty
+    ]
+    has_var_positional = any(param.kind is Parameter.VAR_POSITIONAL for param in params)
+
+    if len(required_positional) > count:
+        return False
+    if has_var_positional:
+        return True
+    return len(positional_params) >= count
+
+
+def _as_optional_str_dict(data: Mapping[str, Any], key: str) -> dict[str, str] | None:
+    raw = data.get(key)
+    if raw is None:
+        return None
+    if not isinstance(raw, Mapping):
+        raise TypeError(f"{key} must be a mapping of string to string")
+
+    parsed: dict[str, str] = {}
+    for k, v in raw.items():
+        if not isinstance(k, str) or not isinstance(v, str):
+            raise TypeError(f"{key} must be a mapping of string to string")
+        parsed[k] = v
+    return parsed
+
+
+def _as_optional_str_list(data: Mapping[str, Any], key: str) -> list[str] | None:
+    raw = data.get(key)
+    if raw is None:
+        return None
+    if not isinstance(raw, list):
+        raise TypeError(f"{key} must be a list of strings")
+    if any(not isinstance(item, str) for item in raw):
+        raise TypeError(f"{key} must be a list of strings")
+    return list(raw)
+
+
+def _as_optional_nested_dict(
+    data: Mapping[str, Any], key: str
+) -> dict[str, dict[str, Any]] | None:
+    raw = data.get(key)
+    if raw is None:
+        return None
+    if not isinstance(raw, Mapping):
+        raise TypeError(f"{key} must be a mapping")
+
+    parsed: dict[str, dict[str, Any]] = {}
+    for k, v in raw.items():
+        if not isinstance(k, str) or not isinstance(v, Mapping):
+            raise TypeError(f"{key} must be a mapping of string to mapping")
+        parsed[k] = dict(v)
+    return parsed
diff --git a/packages/sdk-python/src/qwen_code_sdk/validation.py b/packages/sdk-python/src/qwen_code_sdk/validation.py
new file mode 100644
index 000000000..f19fe4cfb
--- /dev/null
+++ b/packages/sdk-python/src/qwen_code_sdk/validation.py
@@ -0,0 +1,94 @@
+"""Validation helpers for query options."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from uuid import RFC_4122, UUID
+
+from .errors import ValidationError
+from .types import (
+    QueryOptions,
+    _validate_can_use_tool_callable,
+    _validate_stderr_callable,
+)
+
+_VALID_PERMISSION_MODES = {"default", "plan", "auto-edit", "yolo"}
+_VALID_AUTH_TYPES = {"openai", "anthropic", "qwen-oauth", "gemini", "vertex-ai"}
+
+
+def validate_query_options(options: QueryOptions) -> None:
+    if (
+        options.permission_mode
+        and options.permission_mode not in _VALID_PERMISSION_MODES
+    ):
+        raise ValidationError(
+            f"Invalid permission_mode: {options.permission_mode!r}. "
+            "Expected one of: default, plan, auto-edit, yolo."
+        )
+
+    if options.auth_type and options.auth_type not in _VALID_AUTH_TYPES:
+        raise ValidationError(
+            f"Invalid auth_type: {options.auth_type!r}. "
+            "Expected one of: openai, anthropic, qwen-oauth, gemini, vertex-ai."
+        )
+
+    _validate_optional_callable(options.can_use_tool, _validate_can_use_tool_callable)
+    _validate_optional_callable(options.stderr, _validate_stderr_callable)
+
+    if options.resume and options.continue_session:
+        raise ValidationError(
+            "Cannot use resume together with continue_session. "
+            "Use continue_session for latest session "
+            "or resume for a specific session ID."
+        )
+
+    if options.session_id and (options.resume or options.continue_session):
+        raise ValidationError(
+            "Cannot use session_id with resume or continue_session. "
+            "session_id starts a new session, "
+            "resume/continue_session restore existing sessions."
+        )
+
+    if options.session_id:
+        validate_session_id(options.session_id, "session_id")
+
+    if options.resume:
+        validate_session_id(options.resume, "resume")
+
+    if options.max_session_turns is not None and options.max_session_turns < -1:
+        raise ValidationError("max_session_turns must be -1 or a non-negative integer")
+
+    if (
+        options.path_to_qwen_executable is not None
+        and not options.path_to_qwen_executable.strip()
+    ):
+        raise ValidationError("path_to_qwen_executable cannot be empty")
+
+    if options.mcp_servers:
+        raise ValidationError(
+            "mcp_servers is not supported in Python SDK v1. "
+            "Remove the mcp_servers option or use the TypeScript SDK."
+        )
+
+
+def _validate_optional_callable(
+    value: object,
+    validator: Callable[[object, type[ValidationError]], None],
+) -> None:
+    if value is None:
+        return
+    validator(value, ValidationError)
+
+
+def validate_session_id(value: str, param_name: str) -> None:
+    try:
+        parsed = UUID(value)
+    except ValueError as exc:
+        raise ValidationError(
+            f"Invalid {param_name}: {value!r}. Must be a valid UUID."
+        ) from exc
+
+    if parsed.variant != RFC_4122:
+        raise ValidationError(
+            f"Invalid {param_name}: {value!r}. UUID variant must be RFC 4122."
+        )
diff --git a/packages/sdk-python/tests/integration/conftest.py b/packages/sdk-python/tests/integration/conftest.py
new file mode 100644
index 000000000..f73a5e6ac
--- /dev/null
+++ b/packages/sdk-python/tests/integration/conftest.py
@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+import os
+import stat
+import textwrap
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture()
+def fake_qwen_path(tmp_path: Path) -> str:
+    script_path = tmp_path / "fake_qwen.py"
+    script_path.write_text(
+        textwrap.dedent(
+            """
+            #!/usr/bin/env python3
+            import argparse
+            import json
+            import sys
+            import uuid
+
+
+            def send(message):
+                sys.stdout.write(json.dumps(message, separators=(",", ":")) + "\\n")
+                sys.stdout.flush()
+
+
+            def parse_user_content(message):
+                payload = message.get("message", {})
+                content = payload.get("content", "")
+                if isinstance(content, str):
+                    return content
+                if isinstance(content, list):
+                    text_parts = []
+                    for block in content:
+                        if isinstance(block, dict) and block.get("type") == "text":
+                            text_parts.append(str(block.get("text", "")))
+                    return " ".join(text_parts)
+                return str(content)
+
+
+            def build_system_message():
+                return {
+                    "type": "system",
+                    "subtype": "init",
+                    "uuid": session_id,
+                    "session_id": session_id,
+                    "cwd": ".",
+                    "tools": ["Read", "Edit", "Bash"],
+                    "mcp_servers": [],
+                    "model": state["model"],
+                    "permission_mode": state["permission_mode"],
+                    "qwen_code_version": "fake-1.0.0",
+                    "capabilities": {
+                        "canSetModel": True,
+                        "canSetPermissionMode": True,
+                    },
+                }
+
+
+            def build_assistant_message(text):
+                return {
+                    "type": "assistant",
+                    "uuid": str(uuid.uuid4()),
+                    "session_id": session_id,
+                    "message": {
+                        "id": str(uuid.uuid4()),
+                        "type": "message",
+                        "role": "assistant",
+                        "model": state["model"],
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": text,
+                            }
+                        ],
+                        "usage": {
+                            "input_tokens": 1,
+                            "output_tokens": 1,
+                        },
+                    },
+                    "parent_tool_use_id": None,
+                }
+
+
+            def build_result_message(result_text):
+                return {
+                    "type": "result",
+                    "subtype": "success",
+                    "uuid": str(uuid.uuid4()),
+                    "session_id": session_id,
+                    "is_error": False,
+                    "duration_ms": 5,
+                    "duration_api_ms": 1,
+                    "num_turns": 1,
+                    "result": result_text,
+                    "usage": {
+                        "input_tokens": 1,
+                        "output_tokens": 1,
+                    },
+                    "permission_denials": [],
+                }
+
+
+            parser = argparse.ArgumentParser(add_help=False)
+            parser.add_argument("--model")
+            parser.add_argument("--approval-mode")
+            parser.add_argument("--include-partial-messages", action="store_true")
+            parser.add_argument("--session-id")
+            parser.add_argument("--resume")
+            parser.add_argument(
+                "--continue",
+                dest="continue_session",
+                action="store_true",
+            )
+            args, _ = parser.parse_known_args()
+
+            session_id = (
+                args.resume
+                or args.session_id
+                or (
+                    "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
+                    if args.continue_session
+                    else str(uuid.uuid4())
+                )
+            )
+            state = {
+                "model": args.model or "coder-model",
+                "permission_mode": args.approval_mode or "default",
+                "include_partial": bool(args.include_partial_messages),
+            }
+
+            pending_permission = None
+            pending_unknown_control = None
+
+            for line in sys.stdin:
+                line = line.strip()
+                if not line:
+                    continue
+                message = json.loads(line)
+                msg_type = message.get("type")
+
+                if msg_type == "control_request":
+                    request_id = message["request_id"]
+                    request = message["request"]
+                    subtype = request.get("subtype")
+
+                    if subtype == "initialize":
+                        send(
+                            {
+                                "type": "control_response",
+                                "response": {
+                                    "subtype": "success",
+                                    "request_id": request_id,
+                                    "response": {},
+                                },
+                            }
+                        )
+                        send(build_system_message())
+                    elif subtype == "set_model":
+                        state["model"] = request["model"]
+                        send(
+                            {
+                                "type": "control_response",
+                                "response": {
+                                    "subtype": "success",
+                                    "request_id": request_id,
+                                    "response": {},
+                                },
+                            }
+                        )
+                        send(build_system_message())
+                    elif subtype == "set_permission_mode":
+                        state["permission_mode"] = request["mode"]
+                        send(
+                            {
+                                "type": "control_response",
+                                "response": {
+                                    "subtype": "success",
+                                    "request_id": request_id,
+                                    "response": {},
+                                },
+                            }
+                        )
+                        send(build_system_message())
+                    elif subtype == "interrupt":
+                        send(
+                            {
+                                "type": "control_response",
+                                "response": {
+                                    "subtype": "success",
+                                    "request_id": request_id,
+                                    "response": {},
+                                },
+                            }
+                        )
+                    elif subtype == "supported_commands":
+                        send(
+                            {
+                                "type": "control_response",
+                                "response": {
+                                    "subtype": "success",
+                                    "request_id": request_id,
+                                    "response": {
+                                        "commands": [
+                                            "initialize",
+                                            "interrupt",
+                                            "set_model",
+                                            "set_permission_mode",
+                                        ]
+                                    },
+                                },
+                            }
+                        )
+                    elif subtype == "mcp_server_status":
+                        send(
+                            {
+                                "type": "control_response",
+                                "response": {
+                                    "subtype": "success",
+                                    "request_id": request_id,
+                                    "response": {"servers": []},
+                                },
+                            }
+                        )
+                    else:
+                        send(
+                            {
+                                "type": "control_response",
+                                "response": {
+                                    "subtype": "error",
+                                    "request_id": request_id,
+                                    "error": f"unsupported request: {subtype}",
+                                },
+                            }
+                        )
+
+                elif msg_type == "user":
+                    prompt = parse_user_content(message)
+
+                    if "exit nonzero" in prompt:
+                        sys.exit(9)
+
+                    if "request unknown control" in prompt:
+                        request_id = str(uuid.uuid4())
+                        pending_unknown_control = {
+                            "request_id": request_id,
+                            "prompt": prompt,
+                        }
+                        send(
+                            {
+                                "type": "control_request",
+                                "request_id": request_id,
+                                "request": {
+                                    "subtype": "something_new",
+                                    "payload": {},
+                                },
+                            }
+                        )
+                        continue
+
+                    if "use tool" in prompt or "create file" in prompt:
+                        tool_use_id = str(uuid.uuid4())
+                        send(
+                            {
+                                "type": "assistant",
+                                "uuid": str(uuid.uuid4()),
+                                "session_id": session_id,
+                                "message": {
+                                    "id": str(uuid.uuid4()),
+                                    "type": "message",
+                                    "role": "assistant",
+                                    "model": state["model"],
+                                    "content": [
+                                        {
+                                            "type": "tool_use",
+                                            "id": tool_use_id,
+                                            "name": "write_file",
+                                            "input": {
+                                                "path": "demo.txt",
+                                                "content": "hello",
+                                            },
+                                        }
+                                    ],
+                                    "usage": {"input_tokens": 1, "output_tokens": 1},
+                                },
+                                "parent_tool_use_id": None,
+                            }
+                        )
+                        request_id = str(uuid.uuid4())
+                        pending_permission = {
+                            "request_id": request_id,
+                            "tool_use_id": tool_use_id,
+                            "prompt": prompt,
+                        }
+                        send(
+                            {
+                                "type": "control_request",
+                                "request_id": request_id,
+                                "request": {
+                                    "subtype": "can_use_tool",
+                                    "tool_name": "write_file",
+                                    "tool_use_id": tool_use_id,
+                                    "input": {"path": "demo.txt", "content": "hello"},
+                                    "permission_suggestions": [
+                                        {"type": "allow", "label": "Allow write"}
+                                    ],
+                                    "blocked_path": None,
+                                },
+                            }
+                        )
+                        continue
+
+                    if state["include_partial"]:
+                        send(
+                            {
+                                "type": "stream_event",
+                                "uuid": str(uuid.uuid4()),
+                                "session_id": session_id,
+                                "event": {
+                                    "type": "content_block_delta",
+                                    "index": 0,
+                                    "delta": {"type": "text_delta", "text": "partial"},
+                                },
+                                "parent_tool_use_id": None,
+                            }
+                        )
+
+                    send(build_assistant_message(f"Echo: {prompt}"))
+                    send(build_result_message(f"done: {prompt}"))
+
+                elif msg_type == "control_response":
+                    payload = message.get("response", {})
+                    request_id = payload.get("request_id")
+
+                    if (
+                        pending_unknown_control
+                        and request_id == pending_unknown_control["request_id"]
+                    ):
+                        if payload.get("subtype") != "error":
+                            sys.exit(3)
+                        prompt = pending_unknown_control["prompt"]
+                        pending_unknown_control = None
+                        send(
+                            build_assistant_message(
+                                f"Unknown control handled for: {prompt}"
+                            )
+                        )
+                        send(build_result_message(f"unknown-control: {prompt}"))
+                        continue
+
+                    if (
+                        pending_permission
+                        and request_id == pending_permission["request_id"]
+                    ):
+                        prompt = pending_permission["prompt"]
+                        tool_use_id = pending_permission["tool_use_id"]
+                        pending_permission = None
+
+                        behavior = "deny"
+                        if payload.get("subtype") == "success":
+                            response_payload = payload.get("response") or {}
+                            behavior = response_payload.get("behavior", "deny")
+
+                        is_allowed = behavior == "allow"
+                        send(
+                            {
+                                "type": "user",
+                                "session_id": session_id,
+                                "message": {
+                                    "role": "user",
+                                    "content": [
+                                        {
+                                            "type": "tool_result",
+                                            "tool_use_id": tool_use_id,
+                                            "is_error": not is_allowed,
+                                            "content": "ok" if is_allowed else "denied",
+                                        }
+                                    ],
+                                },
+                                "parent_tool_use_id": tool_use_id,
+                            }
+                        )
+                        send(build_assistant_message(f"tool handled: {prompt}"))
+                        send(build_result_message(f"tool-result: {prompt}"))
+                        continue
+            """
+        ).strip()
+        + "\n",
+        encoding="utf-8",
+    )
+    script_path.chmod(script_path.stat().st_mode | stat.S_IEXEC)
+    return str(script_path)
+
+
+@pytest.fixture(autouse=True)
+def disable_history_expansion() -> None:
+    # No-op fixture used as explicit marker for deterministic test env.
+    os.environ.setdefault("PYTHONUTF8", "1")
diff --git a/packages/sdk-python/tests/integration/test_async_query.py b/packages/sdk-python/tests/integration/test_async_query.py
new file mode 100644
index 000000000..3aca1e807
--- /dev/null
+++ b/packages/sdk-python/tests/integration/test_async_query.py
@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Callable
+from typing import Any
+
+import pytest
+from qwen_code_sdk import (
+    ProcessExitError,
+    SDKUserMessage,
+    is_sdk_assistant_message,
+    is_sdk_partial_assistant_message,
+    is_sdk_result_message,
+    is_sdk_system_message,
+    is_sdk_user_message,
+    query,
+)
+
+CONTINUED_SESSION_ID = "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
+VALID_UUID = "123e4567-e89b-12d3-a456-426614174000"
+RESUME_UUID = "223e4567-e89b-12d3-a456-426614174000"
+
+
+async def _collect_messages(result: Any) -> list[dict[str, Any]]:
+    messages: list[dict[str, Any]] = []
+    async for message in result:
+        messages.append(message)
+    return messages
+
+
+async def _wait_for(predicate: Callable[[], bool], timeout: float = 2.0) -> None:
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    while loop.time() < deadline:
+        if predicate():
+            return
+        await asyncio.sleep(0.01)
+    raise AssertionError("timed out waiting for expected SDK state")
+
+
+def _tool_result_error_flag(message: dict[str, Any]) -> bool:
+    content = message["message"]["content"]
+    assert isinstance(content, list)
+    return bool(content[0]["is_error"])
+
+
+@pytest.mark.asyncio
+async def test_single_turn_query(fake_qwen_path: str) -> None:
+    result = query(
+        "hello world",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+        },
+    )
+    messages = await _collect_messages(result)
+
+    assistant = next(
+        message for message in messages if is_sdk_assistant_message(message)
+    )
+    final = next(message for message in messages if is_sdk_result_message(message))
+
+    assert assistant["message"]["content"][0]["text"] == "Echo: hello world"
+    assert final["result"] == "done: hello world"
+    await result.close()
+
+
+@pytest.mark.asyncio
+async def test_include_partial_messages(fake_qwen_path: str) -> None:
+    result = query(
+        "stream partial",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+            "include_partial_messages": True,
+        },
+    )
+    messages = await _collect_messages(result)
+
+    partial = next(
+        message for message in messages if is_sdk_partial_assistant_message(message)
+    )
+    assert partial["event"]["type"] == "content_block_delta"
+    await result.close()
+
+
+@pytest.mark.asyncio
+async def test_default_permission_callback_denies_tool_use(fake_qwen_path: str) -> None:
+    result = query(
+        "use tool now",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+        },
+    )
+    messages = await _collect_messages(result)
+
+    tool_result = next(
+        message
+        for message in messages
+        if is_sdk_user_message(message)
+        and isinstance(message["message"]["content"], list)
+    )
+    assert _tool_result_error_flag(tool_result) is True
+    await result.close()
+
+
+@pytest.mark.asyncio
+async def test_permission_callback_can_allow_tool_use(fake_qwen_path: str) -> None:
+    async def can_use_tool(
+        tool_name: str,
+        tool_input: dict[str, Any],
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        assert tool_name == "write_file"
+        assert tool_input["path"] == "demo.txt"
+        assert context["suggestions"][0]["type"] == "allow"
+        return {"behavior": "allow", "updatedInput": tool_input}
+
+    result = query(
+        "create file with use tool",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+            "can_use_tool": can_use_tool,
+        },
+    )
+    messages = await _collect_messages(result)
+
+    tool_result = next(
+        message
+        for message in messages
+        if is_sdk_user_message(message)
+        and isinstance(message["message"]["content"], list)
+    )
+    assert _tool_result_error_flag(tool_result) is False
+    await result.close()
+
+
+@pytest.mark.asyncio
+async def test_unknown_control_requests_are_rejected(fake_qwen_path: str) -> None:
+    result = query(
+        "request unknown control",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+        },
+    )
+    messages = await _collect_messages(result)
+
+    final = next(message for message in messages if is_sdk_result_message(message))
+    assert final["result"] == "unknown-control: request unknown control"
+    await result.close()
+
+
+@pytest.mark.asyncio
+async def test_dynamic_controls_and_status(fake_qwen_path: str) -> None:
+    release_input = asyncio.Event()
+
+    async def prompts() -> AsyncIterator[SDKUserMessage]:
+        yield {
+            "type": "user",
+            "session_id": VALID_UUID,
+            "message": {
+                "role": "user",
+                "content": "first turn",
+            },
+            "parent_tool_use_id": None,
+        }
+        await release_input.wait()
+
+    result = query(
+        prompts(),
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+            "session_id": VALID_UUID,
+        },
+    )
+
+    messages: list[dict[str, Any]] = []
+
+    async def consume() -> list[dict[str, Any]]:
+        async for message in result:
+            messages.append(message)
+        return messages
+
+    collector = asyncio.create_task(consume())
+    await _wait_for(lambda: any(is_sdk_result_message(message) for message in messages))
+
+    assert await result.supported_commands() == {
+        "commands": [
+            "initialize",
+            "interrupt",
+            "set_model",
+            "set_permission_mode",
+        ]
+    }
+    assert await result.mcp_server_status() == {"servers": []}
+
+    await result.set_model("new-model")
+    await result.set_permission_mode("plan")
+    release_input.set()
+    await collector
+
+    system_messages = [
+        message for message in messages if is_sdk_system_message(message)
+    ]
+    assert any(message["model"] == "new-model" for message in system_messages)
+    assert any(message["permission_mode"] == "plan" for message in system_messages)
+    await result.close()
+
+
+@pytest.mark.asyncio
+async def test_session_id_resume_and_continue(fake_qwen_path: str) -> None:
+    explicit = query(
+        "hello explicit",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+            "session_id": VALID_UUID,
+        },
+    )
+    explicit_messages = await _collect_messages(explicit)
+    assert explicit.get_session_id() == VALID_UUID
+    assert all(message["session_id"] == VALID_UUID for message in explicit_messages)
+    await explicit.close()
+
+    resumed = query(
+        "hello resume",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+            "resume": RESUME_UUID,
+        },
+    )
+    resumed_messages = await _collect_messages(resumed)
+    assert resumed.get_session_id() == RESUME_UUID
+    assert all(message["session_id"] == RESUME_UUID for message in resumed_messages)
+    await resumed.close()
+
+    continued = query(
+        "hello continue",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+            "continue_session": True,
+        },
+    )
+    continued_messages = await _collect_messages(continued)
+    assert continued.get_session_id() == CONTINUED_SESSION_ID
+    assert any(
+        message["session_id"] == CONTINUED_SESSION_ID for message in continued_messages
+    )
+    await continued.close()
+
+
+@pytest.mark.asyncio
+async def test_non_zero_process_exit_is_propagated(fake_qwen_path: str) -> None:
+    result = query(
+        "please exit nonzero",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+        },
+    )
+
+    with pytest.raises(ProcessExitError, match="code 9"):
+        await _collect_messages(result)
+
+    await result.close()
+
+
+@pytest.mark.asyncio
+async def test_async_context_manager(fake_qwen_path: str) -> None:
+    async with query(
+        "hello context",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+        },
+    ) as result:
+        messages = await _collect_messages(result)
+
+    assert result.is_closed()
+    final = next(m for m in messages if is_sdk_result_message(m))
+    assert final["result"] == "done: hello context"
diff --git a/packages/sdk-python/tests/integration/test_sync_query.py b/packages/sdk-python/tests/integration/test_sync_query.py
new file mode 100644
index 000000000..6f129ccbf
--- /dev/null
+++ b/packages/sdk-python/tests/integration/test_sync_query.py
@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import threading
+import time
+
+import pytest
+import qwen_code_sdk.sync_query as sync_query_module
+from qwen_code_sdk import is_sdk_result_message, query_sync
+from qwen_code_sdk.sync_query import SyncQuery
+
+
+def test_sync_query_single_turn(fake_qwen_path: str) -> None:
+    result = query_sync(
+        "hello sync",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+        },
+    )
+
+    commands = result.supported_commands()
+    messages = list(result)
+
+    assert commands["commands"][0] == "initialize"
+    assert any(
+        is_sdk_result_message(message) and message["result"] == "done: hello sync"
+        for message in messages
+    )
+
+    result.close()
+    result.close()
+
+
+def test_sync_query_bootstrap_failure_cleans_up_loop_thread(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def raising_query(*args: object, **kwargs: object) -> object:
+        raise RuntimeError("bootstrap failed")
+
+    monkeypatch.setattr(sync_query_module, "query", raising_query)
+
+    baseline_threads = {
+        thread.ident
+        for thread in threading.enumerate()
+        if thread.name == "qwen-sdk-sync-loop"
+    }
+
+    with pytest.raises(RuntimeError, match="bootstrap failed"):
+        SyncQuery("hello")
+
+    deadline = time.time() + 1.0
+    while time.time() < deadline:
+        active_threads = {
+            thread.ident
+            for thread in threading.enumerate()
+            if thread.name == "qwen-sdk-sync-loop"
+        }
+        if active_threads == baseline_threads:
+            break
+        time.sleep(0.01)
+
+    active_threads = {
+        thread.ident
+        for thread in threading.enumerate()
+        if thread.name == "qwen-sdk-sync-loop"
+    }
+    assert active_threads == baseline_threads
+
+
+def test_sync_query_context_manager(fake_qwen_path: str) -> None:
+    with query_sync(
+        "hello context",
+        {
+            "path_to_qwen_executable": fake_qwen_path,
+        },
+    ) as result:
+        messages = list(result)
+        assert any(
+            is_sdk_result_message(m) and m["result"] == "done: hello context"
+            for m in messages
+        )
+
+    assert result.is_closed()
diff --git a/packages/sdk-python/tests/unit/test_query_core.py b/packages/sdk-python/tests/unit/test_query_core.py
new file mode 100644
index 000000000..0dd8f3f62
--- /dev/null
+++ b/packages/sdk-python/tests/unit/test_query_core.py
@@ -0,0 +1,612 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import Any, cast
+
+import pytest
+from qwen_code_sdk.errors import AbortError, ControlRequestTimeoutError
+from qwen_code_sdk.json_lines import parse_json_line
+from qwen_code_sdk.query import Query
+from qwen_code_sdk.types import QueryOptions, TimeoutOptions
+
+VALID_UUID = "123e4567-e89b-12d3-a456-426614174000"
+_EOF = object()
+
+
+class FakeTransport:
+    def __init__(self) -> None:
+        self.writes: list[dict[str, Any]] = []
+        self.exit_error: Exception | None = None
+        self.closed = False
+        self.close_calls = 0
+        self.input_closed = False
+        self._queue: asyncio.Queue[dict[str, Any] | object] = asyncio.Queue()
+
+    async def start(self) -> None:
+        return None
+
+    def write(self, data: str) -> None:
+        self.writes.append(parse_json_line(data))
+
+    async def drain(self) -> None:
+        return None
+
+    def end_input(self) -> None:
+        self.input_closed = True
+
+    async def read_messages(self):  # type: ignore[no-untyped-def]
+        while True:
+            item = await self._queue.get()
+            if item is _EOF:
+                break
+            yield item
+
+    async def close(self) -> None:
+        self.closed = True
+        self.close_calls += 1
+        self.input_closed = True
+        self._queue.put_nowait(_EOF)
+
+    def push(self, payload: dict[str, Any]) -> None:
+        self._queue.put_nowait(payload)
+
+
+async def _wait_for(predicate: Callable[[], bool], timeout: float = 1.0) -> None:
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    while loop.time() < deadline:
+        if predicate():
+            return
+        await asyncio.sleep(0.01)
+    raise AssertionError("timed out waiting for test condition")
+
+
+async def _wait_for_request(
+    transport: FakeTransport,
+    subtype: str,
+    timeout: float = 1.0,
+) -> dict[str, Any]:
+    await _wait_for(
+        lambda: any(
+            payload.get("type") == "control_request"
+            and payload.get("request", {}).get("subtype") == subtype
+            for payload in transport.writes
+        ),
+        timeout=timeout,
+    )
+    for payload in transport.writes:
+        if (
+            payload.get("type") == "control_request"
+            and payload.get("request", {}).get("subtype") == subtype
+        ):
+            return payload
+    raise AssertionError(f"missing control request: {subtype}")
+
+
+async def _wait_for_control_response(
+    transport: FakeTransport,
+    request_id: str,
+    timeout: float = 1.0,
+) -> dict[str, Any]:
+    await _wait_for(
+        lambda: any(
+            payload.get("type") == "control_response"
+            and payload.get("response", {}).get("request_id") == request_id
+            for payload in transport.writes
+        ),
+        timeout=timeout,
+    )
+    for payload in transport.writes:
+        if (
+            payload.get("type") == "control_response"
+            and payload.get("response", {}).get("request_id") == request_id
+        ):
+            return payload
+    raise AssertionError(f"missing control response: {request_id}")
+
+
+async def _start_query(transport: FakeTransport) -> Query:
+    query = Query(
+        transport=transport,  # type: ignore[arg-type]
+        options=QueryOptions(
+            timeout=TimeoutOptions(
+                can_use_tool=0.05,
+                control_request=0.05,
+                stream_close=0.05,
+            )
+        ),
+        prompt="hello",
+        session_id=VALID_UUID,
+    )
+    await query._ensure_started()
+
+    init_request = await _wait_for_request(transport, "initialize")
+    transport.push(
+        {
+            "type": "control_response",
+            "response": {
+                "subtype": "success",
+                "request_id": init_request["request_id"],
+                "response": {},
+            },
+        }
+    )
+    await _wait_for(
+        lambda: any(payload.get("type") == "user" for payload in transport.writes)
+    )
+    return query
+
+
+@pytest.mark.asyncio
+async def test_unknown_control_request_returns_error_response() -> None:
+    transport = FakeTransport()
+    query = await _start_query(transport)
+
+    transport.push(
+        {
+            "type": "control_request",
+            "request_id": "unknown-1",
+            "request": {
+                "subtype": "something_new",
+            },
+        }
+    )
+
+    response = await _wait_for_control_response(transport, "unknown-1")
+
+    assert response["response"]["subtype"] == "error"
+    assert "Unknown control request subtype" in response["response"]["error"]
+    await query.close()
+
+
+@pytest.mark.asyncio
+async def test_control_request_times_out() -> None:
+    transport = FakeTransport()
+    query = await _start_query(transport)
+
+    with pytest.raises(ControlRequestTimeoutError, match="supported_commands"):
+        await query.supported_commands()
+
+    await query.close()
+
+
+@pytest.mark.asyncio
+async def test_control_request_cancel_propagates_abort_error() -> None:
+    transport = FakeTransport()
+    query = await _start_query(transport)
+
+    task = asyncio.create_task(query.supported_commands())
+    request = await _wait_for_request(transport, "supported_commands")
+    transport.push(
+        {
+            "type": "control_cancel_request",
+            "request_id": request["request_id"],
+        }
+    )
+
+    with pytest.raises(AbortError, match="Control request cancelled"):
+        await task
+
+    await query.close()
+
+
+@pytest.mark.asyncio
+async def test_incoming_control_request_cancel_does_not_block_router() -> None:
+    transport = FakeTransport()
+    started = asyncio.Event()
+    cancelled = asyncio.Event()
+    captured_cancel_events: list[asyncio.Event] = []
+
+    async def can_use_tool(
+        tool_name: str,
+        tool_input: dict[str, Any],
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        assert tool_name == "write_file"
+        assert tool_input["path"] == "demo.txt"
+        cancel_event = cast(asyncio.Event, context["cancel_event"])
+        captured_cancel_events.append(cancel_event)
+        started.set()
+        try:
+            await cancel_event.wait()
+            cancelled.set()
+            return {"behavior": "deny", "message": "Cancelled"}
+        except asyncio.CancelledError:
+            if cancel_event.is_set():
+                cancelled.set()
+            raise
+
+    query = Query(
+        transport=transport,  # type: ignore[arg-type]
+        options=QueryOptions(
+            can_use_tool=can_use_tool,
+            timeout=TimeoutOptions(
+                can_use_tool=1.0,
+                control_request=0.2,
+                stream_close=0.05,
+            ),
+        ),
+        prompt="hello",
+        session_id=VALID_UUID,
+    )
+    await query._ensure_started()
+
+    init_request = await _wait_for_request(transport, "initialize")
+    transport.push(
+        {
+            "type": "control_response",
+            "response": {
+                "subtype": "success",
+                "request_id": init_request["request_id"],
+                "response": {},
+            },
+        }
+    )
+    await _wait_for(
+        lambda: any(payload.get("type") == "user" for payload in transport.writes)
+    )
+
+    transport.push(
+        {
+            "type": "control_request",
+            "request_id": "incoming-1",
+            "request": {
+                "subtype": "can_use_tool",
+                "tool_name": "write_file",
+                "tool_use_id": "tool-1",
+                "input": {"path": "demo.txt", "content": "hello"},
+                "permission_suggestions": [],
+                "blocked_path": None,
+            },
+        }
+    )
+
+    await _wait_for(lambda: started.is_set())
+    assert captured_cancel_events[0] is not query._cancel_event
+
+    supported_commands_task = asyncio.create_task(query.supported_commands())
+    supported_request = await _wait_for_request(transport, "supported_commands")
+
+    transport.push(
+        {
+            "type": "control_cancel_request",
+            "request_id": "incoming-1",
+        }
+    )
+    await _wait_for(lambda: cancelled.is_set())
+
+    transport.push(
+        {
+            "type": "control_response",
+            "response": {
+                "subtype": "success",
+                "request_id": supported_request["request_id"],
+                "response": {"commands": ["supported_commands"]},
+            },
+        }
+    )
+
+    assert await supported_commands_task == {"commands": ["supported_commands"]}
+    assert all(
+        not (
+            payload.get("type") == "control_response"
+            and payload.get("response", {}).get("request_id") == "incoming-1"
+        )
+        for payload in transport.writes
+    )
+    await query.close()
+
+
+@pytest.mark.asyncio
+async def test_permission_request_passes_blocked_path_to_callback() -> None:
+    transport = FakeTransport()
+    captured_context: dict[str, Any] | None = None
+
+    async def can_use_tool(
+        tool_name: str,
+        tool_input: dict[str, Any],
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        nonlocal captured_context
+        assert tool_name == "write_file"
+        assert tool_input["path"] == "demo.txt"
+        captured_context = context
+        return {"behavior": "deny", "message": "blocked"}
+
+    query = Query(
+        transport=transport,  # type: ignore[arg-type]
+        options=QueryOptions(
+            can_use_tool=can_use_tool,
+            timeout=TimeoutOptions(
+                can_use_tool=1.0,
+                control_request=0.2,
+                stream_close=0.05,
+            ),
+        ),
+        prompt="hello",
+        session_id=VALID_UUID,
+    )
+    await query._ensure_started()
+
+    init_request = await _wait_for_request(transport, "initialize")
+    transport.push(
+        {
+            "type": "control_response",
+            "response": {
+                "subtype": "success",
+                "request_id": init_request["request_id"],
+                "response": {},
+            },
+        }
+    )
+    await _wait_for(
+        lambda: any(payload.get("type") == "user" for payload in transport.writes)
+    )
+
+    transport.push(
+        {
+            "type": "control_request",
+            "request_id": "incoming-2",
+            "request": {
+                "subtype": "can_use_tool",
+                "tool_name": "write_file",
+                "tool_use_id": "tool-2",
+                "input": {"path": "demo.txt", "content": "hello"},
+                "permission_suggestions": [],
+                "blocked_path": "/tmp/demo.txt",
+            },
+        }
+    )
+
+    response = await _wait_for_control_response(transport, "incoming-2")
+
+    assert captured_context is not None
+    assert isinstance(captured_context["cancel_event"], asyncio.Event)
+    assert captured_context["suggestions"] == []
+    assert captured_context["blocked_path"] == "/tmp/demo.txt"
+    assert response["response"]["subtype"] == "success"
+    assert response["response"]["response"] == {
+        "behavior": "deny",
+        "message": "blocked",
+    }
+    await query.close()
+
+
+@pytest.mark.asyncio
+async def test_permission_request_cancelled_callback_returns_deny() -> None:
+    transport = FakeTransport()
+
+    async def can_use_tool(
+        tool_name: str,
+        tool_input: dict[str, Any],
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        assert tool_name == "write_file"
+        assert tool_input["path"] == "demo.txt"
+        assert isinstance(context["cancel_event"], asyncio.Event)
+        raise asyncio.CancelledError()
+
+    query = Query(
+        transport=transport,  # type: ignore[arg-type]
+        options=QueryOptions(
+            can_use_tool=can_use_tool,
+            timeout=TimeoutOptions(
+                can_use_tool=1.0,
+                control_request=0.2,
+                stream_close=0.05,
+            ),
+        ),
+        prompt="hello",
+        session_id=VALID_UUID,
+    )
+    await query._ensure_started()
+
+    init_request = await _wait_for_request(transport, "initialize")
+    transport.push(
+        {
+            "type": "control_response",
+            "response": {
+                "subtype": "success",
+                "request_id": init_request["request_id"],
+                "response": {},
+            },
+        }
+    )
+    await _wait_for(
+        lambda: any(payload.get("type") == "user" for payload in transport.writes)
+    )
+
+    transport.push(
+        {
+            "type": "control_request",
+            "request_id": "incoming-3",
+            "request": {
+                "subtype": "can_use_tool",
+                "tool_name": "write_file",
+                "tool_use_id": "tool-3",
+                "input": {"path": "demo.txt", "content": "hello"},
+                "permission_suggestions": [],
+                "blocked_path": None,
+            },
+        }
+    )
+
+    response = await _wait_for_control_response(transport, "incoming-3")
+
+    assert response["response"]["subtype"] == "success"
+    assert response["response"]["response"] == {
+        "behavior": "deny",
+        "message": "Permission check failed: callback cancelled",
+    }
+    await query.close()
+
+
+@pytest.mark.asyncio
+async def test_finish_with_error_closes_transport_and_fails_pending_requests() -> None:
+    transport = FakeTransport()
+    query = await _start_query(transport)
+
+    supported_commands_task = asyncio.create_task(query.supported_commands())
+    await _wait_for_request(transport, "supported_commands")
+
+    await query._finish_with_error(RuntimeError("boom"))
+
+    with pytest.raises(RuntimeError, match="boom"):
+        await supported_commands_task
+
+    assert query.is_closed() is True
+    assert transport.closed is True
+
+
+@pytest.mark.asyncio
+async def test_ensure_started_raises_after_close() -> None:
+    transport = FakeTransport()
+    query = await _start_query(transport)
+
+    await query.close()
+
+    with pytest.raises(RuntimeError, match="Query is closed"):
+        await query.supported_commands()
+
+
+@pytest.mark.asyncio
+async def test_anext_after_exhaustion_raises_stop_async_iteration() -> None:
+    """After the async iterator is exhausted, subsequent __anext__ calls must
+    raise StopAsyncIteration immediately instead of blocking."""
+    transport = FakeTransport()
+    query = await _start_query(transport)
+
+    # Deliver one assistant message, then a result to end the turn.
+    transport.push(
+        {
+            "type": "assistant",
+            "session_id": VALID_UUID,
+            "message": {
+                "role": "assistant",
+                "content": [{"type": "text", "text": "hi"}],
+            },
+        }
+    )
+    transport.push(
+        {
+            "type": "result",
+            "session_id": VALID_UUID,
+            "result": "done",
+            "is_error": False,
+            "duration_ms": 10,
+            "duration_api_ms": 5,
+            "num_turns": 1,
+        }
+    )
+    # Signal end of transport stream so the router finishes naturally.
+    await transport.close()
+
+    # Consume all messages until exhaustion.
+    messages: list[Any] = []
+    with pytest.raises(StopAsyncIteration):
+        while True:
+            messages.append(await query.__anext__())
+
+    assert len(messages) >= 1
+
+    # The iterator is now exhausted — a second call must raise immediately.
+    with pytest.raises(StopAsyncIteration):
+        await query.__anext__()
+
+
+@pytest.mark.asyncio
+async def test_initialize_failure_no_unhandled_task_exception(
+    recwarn: pytest.WarningsChecker,
+) -> None:
+    """When _initialize fails, no 'Task exception was never retrieved' warning
+    should appear — _finish_with_error already surfaces the error."""
+    transport = FakeTransport()
+    query = Query(
+        transport=transport,  # type: ignore[arg-type]
+        options=QueryOptions(
+            timeout=TimeoutOptions(
+                can_use_tool=0.05,
+                control_request=0.05,
+                stream_close=0.05,
+            )
+        ),
+        prompt="hello",
+        session_id=VALID_UUID,
+    )
+    await query._ensure_started()
+
+    # Let the initialize request time out — this triggers _finish_with_error
+    # inside _initialize.
+    init_request = await _wait_for_request(transport, "initialize")
+    assert init_request is not None  # init was sent
+
+    # Don't respond to initialize — let the control-request timeout fire.
+    # The error propagates through _message_queue.
+    with pytest.raises(ControlRequestTimeoutError):
+        await query.__anext__()
+
+    await query.close()
+
+    # Give the event loop a moment to report any unhandled task exceptions.
+    await asyncio.sleep(0.1)
+
+    # No "Task exception was never retrieved" warnings should have appeared.
+    task_warnings = [w for w in recwarn.list if "never retrieved" in str(w.message)]
+    assert task_warnings == []
+
+
+@pytest.mark.asyncio
+async def test_async_context_manager_closes_on_exit() -> None:
+    transport = FakeTransport()
+    query = Query(
+        transport=transport,  # type: ignore[arg-type]
+        options=QueryOptions(
+            timeout=TimeoutOptions(
+                can_use_tool=0.05,
+                control_request=0.05,
+                stream_close=0.05,
+            )
+        ),
+        prompt="hello",
+        session_id=VALID_UUID,
+    )
+
+    async with query as q:
+        assert q is query
+        assert not q.is_closed()
+
+    assert query.is_closed() is True
+
+
+def test_sync_next_after_exhaustion_raises_stop_iteration() -> None:
+    """After the sync iterator is exhausted, subsequent __next__ calls must
+    raise StopIteration immediately instead of blocking on queue.get()."""
+    from queue import Queue
+
+    from qwen_code_sdk.sync_query import _STOP, SyncQuery
+
+    # Build a minimal SyncQuery without spawning the real event-loop thread.
+    sq = object.__new__(SyncQuery)
+    sq._queue = Queue()
+    sq._exhausted = False
+
+    # Put one message then the sentinel.
+    msg_payload = {
+        "type": "assistant",
+        "message": {"role": "assistant", "content": []},
+    }
+    sq._queue.put(msg_payload)
+    sq._queue.put(_STOP)
+
+    # First call returns the message.
+    msg = next(sq)
+    assert msg["type"] == "assistant"
+
+    # Second call should exhaust.
+    with pytest.raises(StopIteration):
+        next(sq)
+
+    # Third call must raise immediately, not block.
+    with pytest.raises(StopIteration):
+        next(sq)
diff --git a/packages/sdk-python/tests/unit/test_transport.py b/packages/sdk-python/tests/unit/test_transport.py
new file mode 100644
index 000000000..340d1c1e6
--- /dev/null
+++ b/packages/sdk-python/tests/unit/test_transport.py
@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import asyncio
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+from qwen_code_sdk.transport import build_cli_arguments, prepare_spawn_info
+from qwen_code_sdk.types import QueryOptions, TimeoutOptions
+
+VALID_UUID = "123e4567-e89b-12d3-a456-426614174000"
+
+
+class DummyProcess:
+    def __init__(self) -> None:
+        self.stdin = None
+        self.stdout = None
+        self.stderr = None
+        self.returncode = 0
+
+
+def test_build_cli_arguments_maps_supported_options() -> None:
+    args = build_cli_arguments(
+        QueryOptions(
+            model="qwen3-coder",
+            system_prompt="system prompt",
+            append_system_prompt="append prompt",
+            permission_mode="auto-edit",
+            max_session_turns=7,
+            core_tools=["Read", "Edit"],
+            exclude_tools=["Bash(rm *)"],
+            allowed_tools=["Bash(git status)"],
+            auth_type="openai",
+            include_partial_messages=True,
+            session_id=VALID_UUID,
+        )
+    )
+
+    assert args == [
+        "--input-format",
+        "stream-json",
+        "--output-format",
+        "stream-json",
+        "--channel=SDK",
+        "--model",
+        "qwen3-coder",
+        "--system-prompt",
+        "system prompt",
+        "--append-system-prompt",
+        "append prompt",
+        "--approval-mode",
+        "auto-edit",
+        "--max-session-turns",
+        "7",
+        "--core-tools",
+        "Read,Edit",
+        "--exclude-tools",
+        "Bash(rm *)",
+        "--allowed-tools",
+        "Bash(git status)",
+        "--auth-type",
+        "openai",
+        "--include-partial-messages",
+        "--session-id",
+        VALID_UUID,
+    ]
+
+
+def test_cli_argument_precedence_prefers_resume_then_continue_then_session_id() -> None:
+    args = build_cli_arguments(
+        QueryOptions(
+            resume=VALID_UUID,
+            continue_session=True,
+            session_id="223e4567-e89b-12d3-a456-426614174000",
+        )
+    )
+
+    assert "--resume" in args
+    assert "--continue" not in args
+    assert "--session-id" not in args
+
+
+def test_prepare_spawn_info_uses_runtime_for_python_scripts(tmp_path: Path) -> None:
+    script_path = tmp_path / "fake-qwen.py"
+    script_path.write_text("print('ok')\n", encoding="utf-8")
+
+    spawn_info = prepare_spawn_info(str(script_path))
+
+    assert spawn_info.command == sys.executable
+    assert spawn_info.args == [str(script_path.resolve())]
+
+
+def test_prepare_spawn_info_uses_node_for_javascript_files(tmp_path: Path) -> None:
+    script_path = tmp_path / "fake-qwen.js"
+    script_path.write_text("console.log('ok');\n", encoding="utf-8")
+
+    spawn_info = prepare_spawn_info(str(script_path))
+
+    assert spawn_info.command == "node"
+    assert spawn_info.args == [str(script_path.resolve())]
+
+
+def test_prepare_spawn_info_keeps_plain_command_names() -> None:
+    spawn_info = prepare_spawn_info("qwen-custom")
+
+    assert spawn_info.command == "qwen-custom"
+    assert spawn_info.args == []
+
+
+@pytest.mark.asyncio
+async def test_transport_discards_stderr_when_debug_is_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, Any] = {}
+
+    async def fake_create_subprocess_exec(*args: Any, **kwargs: Any) -> DummyProcess:
+        captured["args"] = args
+        captured["kwargs"] = kwargs
+        return DummyProcess()
+
+    monkeypatch.setattr(
+        asyncio,
+        "create_subprocess_exec",
+        fake_create_subprocess_exec,
+    )
+
+    transport_module = __import__(
+        "qwen_code_sdk.transport",
+        fromlist=["ProcessTransport"],
+    )
+    transport = transport_module.ProcessTransport(
+        QueryOptions(timeout=TimeoutOptions())
+    )
+
+    await transport.start()
+
+    assert captured["kwargs"]["stderr"] is subprocess.DEVNULL
+
+
+def test_prepare_spawn_info_defaults_to_qwen_when_none() -> None:
+    spawn_info = prepare_spawn_info(None)
+
+    assert spawn_info.command == "qwen"
+    assert spawn_info.args == []
+
+
+def test_prepare_spawn_info_uses_node_for_mjs_files(tmp_path: Path) -> None:
+    script_path = tmp_path / "cli.mjs"
+    script_path.write_text("export default {};\n", encoding="utf-8")
+
+    spawn_info = prepare_spawn_info(str(script_path))
+
+    assert spawn_info.command == "node"
+    assert spawn_info.args == [str(script_path.resolve())]
+
+
+def test_prepare_spawn_info_uses_node_for_cjs_files(tmp_path: Path) -> None:
+    script_path = tmp_path / "cli.cjs"
+    script_path.write_text("module.exports = {};\n", encoding="utf-8")
+
+    spawn_info = prepare_spawn_info(str(script_path))
+
+    assert spawn_info.command == "node"
+    assert spawn_info.args == [str(script_path.resolve())]
+
+
+@pytest.mark.asyncio
+async def test_transport_start_raises_after_close(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def fake_create_subprocess_exec(*args: Any, **kwargs: Any) -> DummyProcess:
+        return DummyProcess()
+
+    monkeypatch.setattr(
+        asyncio,
+        "create_subprocess_exec",
+        fake_create_subprocess_exec,
+    )
+
+    transport_module = __import__(
+        "qwen_code_sdk.transport",
+        fromlist=["ProcessTransport"],
+    )
+    transport = transport_module.ProcessTransport(
+        QueryOptions(timeout=TimeoutOptions())
+    )
+    transport._closed = True
+
+    with pytest.raises(RuntimeError, match="Transport is closed"):
+        await transport.start()
+
+
+@pytest.mark.asyncio
+async def test_read_messages_skips_malformed_json_lines() -> None:
+    """Malformed JSON lines should be skipped, not crash the stream."""
+
+    class FakeStdout:
+        def __init__(self, lines: list[bytes]) -> None:
+            self._lines = iter(lines)
+
+        async def readline(self) -> bytes:
+            return next(self._lines, b"")
+
+    transport_module = __import__(
+        "qwen_code_sdk.transport",
+        fromlist=["ProcessTransport"],
+    )
+    transport = transport_module.ProcessTransport(
+        QueryOptions(timeout=TimeoutOptions())
+    )
+
+    class FakeProcess:
+        returncode = 0
+        stdin = None
+        stderr = None
+
+        def __init__(self) -> None:
+            self.stdout = FakeStdout(
+                [
+                    b"not valid json\n",
+                    b'{"type":"system","subtype":"init","uuid":"u","session_id":"s"}\n',
+                    b"also bad\n",
+                    b"",
+                ]
+            )
+
+        async def wait(self) -> int:
+            return 0
+
+    transport._process = FakeProcess()
+
+    messages: list[Any] = []
+    async for msg in transport.read_messages():
+        messages.append(msg)
+
+    assert len(messages) == 1
+    assert messages[0]["type"] == "system"
+
+
+@pytest.mark.asyncio
+async def test_stderr_callback_exceptions_do_not_fail_transport() -> None:
+    class FakeStdout:
+        async def readline(self) -> bytes:
+            return b""
+
+    class FakeStderr:
+        def __init__(self) -> None:
+            self._lines = iter([b"error message\n", b""])
+
+        async def readline(self) -> bytes:
+            return next(self._lines, b"")
+
+    transport_module = __import__(
+        "qwen_code_sdk.transport",
+        fromlist=["ProcessTransport"],
+    )
+
+    callback_calls = 0
+
+    def stderr_callback(text: str) -> None:
+        nonlocal callback_calls
+        callback_calls += 1
+        assert text == "error message"
+        raise RuntimeError("sink failed")
+
+    transport = transport_module.ProcessTransport(
+        QueryOptions(
+            stderr=stderr_callback,
+            timeout=TimeoutOptions(),
+        )
+    )
+
+    class FakeProcess:
+        returncode = 0
+        stdin = None
+
+        def __init__(self) -> None:
+            self.stdout = FakeStdout()
+            self.stderr = FakeStderr()
+
+        async def wait(self) -> int:
+            return 0
+
+    transport._process = FakeProcess()
+    transport._stderr_task = asyncio.create_task(transport._forward_stderr())
+
+    await transport.wait_for_exit()
+
+    assert callback_calls == 1
diff --git a/packages/sdk-python/tests/unit/test_validation.py b/packages/sdk-python/tests/unit/test_validation.py
new file mode 100644
index 000000000..dd85ef2e9
--- /dev/null
+++ b/packages/sdk-python/tests/unit/test_validation.py
@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+import pytest
+from qwen_code_sdk.errors import ValidationError
+from qwen_code_sdk.types import QueryOptions, TimeoutOptions
+from qwen_code_sdk.validation import validate_query_options
+
+VALID_UUID = "123e4567-e89b-12d3-a456-426614174000"
+
+
+def test_rejects_resume_with_continue_session() -> None:
+    with pytest.raises(ValidationError, match="resume together with continue_session"):
+        validate_query_options(
+            QueryOptions(
+                resume=VALID_UUID,
+                continue_session=True,
+            )
+        )
+
+
+def test_rejects_session_id_with_resume() -> None:
+    with pytest.raises(ValidationError, match="Cannot use session_id with resume"):
+        validate_query_options(
+            QueryOptions(
+                session_id=VALID_UUID,
+                resume="223e4567-e89b-12d3-a456-426614174000",
+            )
+        )
+
+
+def test_rejects_invalid_session_id() -> None:
+    with pytest.raises(ValidationError, match="Invalid session_id"):
+        validate_query_options(QueryOptions(session_id="not-a-uuid"))
+
+
+def test_rejects_invalid_resume() -> None:
+    with pytest.raises(ValidationError, match="Invalid resume"):
+        validate_query_options(QueryOptions(resume="not-a-uuid"))
+
+
+def test_rejects_invalid_permission_mode() -> None:
+    with pytest.raises(ValidationError, match="Invalid permission_mode"):
+        validate_query_options(
+            QueryOptions.from_mapping({"permission_mode": "unsafe-mode"})
+        )
+
+
+def test_rejects_invalid_auth_type() -> None:
+    with pytest.raises(ValidationError, match="Invalid auth_type"):
+        validate_query_options(QueryOptions.from_mapping({"auth_type": "custom"}))
+
+
+def test_from_mapping_rejects_non_callable_can_use_tool() -> None:
+    with pytest.raises(TypeError, match="can_use_tool must be callable"):
+        QueryOptions.from_mapping({"can_use_tool": "bad"})
+
+
+def test_from_mapping_rejects_non_callable_stderr() -> None:
+    with pytest.raises(TypeError, match="stderr must be callable"):
+        QueryOptions.from_mapping({"stderr": "bad"})
+
+
+def test_validation_rejects_non_callable_can_use_tool() -> None:
+    with pytest.raises(ValidationError, match="can_use_tool must be callable"):
+        validate_query_options(QueryOptions(can_use_tool=cast(Any, "bad")))
+
+
+def test_validation_rejects_non_callable_stderr() -> None:
+    with pytest.raises(ValidationError, match="stderr must be callable"):
+        validate_query_options(QueryOptions(stderr=cast(Any, "bad")))
+
+
+def test_from_mapping_rejects_sync_can_use_tool() -> None:
+    def can_use_tool(  # type: ignore[no-untyped-def]
+        tool_name, tool_input, context
+    ):
+        return {"behavior": "deny", "message": "bad"}
+
+    with pytest.raises(TypeError, match="can_use_tool must be an async callable"):
+        QueryOptions.from_mapping({"can_use_tool": can_use_tool})
+
+
+def test_validation_rejects_sync_can_use_tool() -> None:
+    def can_use_tool(  # type: ignore[no-untyped-def]
+        tool_name, tool_input, context
+    ):
+        return {"behavior": "deny", "message": "bad"}
+
+    with pytest.raises(ValidationError, match="can_use_tool must be an async callable"):
+        validate_query_options(QueryOptions(can_use_tool=cast(Any, can_use_tool)))
+
+
+def test_from_mapping_rejects_can_use_tool_with_wrong_arity() -> None:
+    async def can_use_tool(
+        tool_name: str,
+        tool_input: dict[str, Any],
+    ) -> dict[str, str]:
+        return {"behavior": "deny"}
+
+    with pytest.raises(
+        TypeError, match="can_use_tool must accept exactly 3 positional arguments"
+    ):
+        QueryOptions.from_mapping({"can_use_tool": can_use_tool})
+
+
+def test_validation_rejects_can_use_tool_with_wrong_arity() -> None:
+    async def can_use_tool(
+        tool_name: str,
+        tool_input: dict[str, Any],
+    ) -> dict[str, str]:
+        return {"behavior": "deny"}
+
+    with pytest.raises(
+        ValidationError,
+        match="can_use_tool must accept exactly 3 positional arguments",
+    ):
+        validate_query_options(QueryOptions(can_use_tool=cast(Any, can_use_tool)))
+
+
+def test_from_mapping_rejects_stderr_with_wrong_arity() -> None:
+    def stderr() -> None:
+        return None
+
+    with pytest.raises(
+        TypeError, match="stderr must accept exactly 1 positional argument"
+    ):
+        QueryOptions.from_mapping({"stderr": stderr})
+
+
+def test_validation_rejects_stderr_with_wrong_arity() -> None:
+    def stderr() -> None:
+        return None
+
+    with pytest.raises(
+        ValidationError, match="stderr must accept exactly 1 positional argument"
+    ):
+        validate_query_options(QueryOptions(stderr=cast(Any, stderr)))
+
+
+def test_rejects_invalid_max_session_turns() -> None:
+    with pytest.raises(ValidationError, match="max_session_turns"):
+        validate_query_options(QueryOptions(max_session_turns=-2))
+
+
+def test_rejects_empty_qwen_executable_path() -> None:
+    with pytest.raises(
+        ValidationError, match="path_to_qwen_executable cannot be empty"
+    ):
+        validate_query_options(QueryOptions(path_to_qwen_executable="   "))
+
+
+def test_timeout_rejects_non_numeric_value() -> None:
+    with pytest.raises(TypeError, match=r"timeout\.can_use_tool must be a positive"):
+        TimeoutOptions.from_mapping({"can_use_tool": "fast"})
+
+
+def test_timeout_rejects_negative_value() -> None:
+    pattern = r"timeout\.control_request must be a positive"
+    with pytest.raises(ValueError, match=pattern):
+        TimeoutOptions.from_mapping({"control_request": -1})
+
+
+def test_timeout_rejects_boolean_value() -> None:
+    with pytest.raises(TypeError, match=r"timeout\.stream_close must be a positive"):
+        TimeoutOptions.from_mapping({"stream_close": True})
+
+
+def test_rejects_mcp_servers() -> None:
+    with pytest.raises(ValidationError, match="mcp_servers is not supported"):
+        validate_query_options(
+            QueryOptions(mcp_servers={"my-server": {"command": "node", "args": []}})
+        )
diff --git a/packages/vscode-ide-companion/assets/icon-blue.png b/packages/vscode-ide-companion/assets/icon-blue.png
new file mode 100644
index 000000000..cc410859d
Binary files /dev/null and b/packages/vscode-ide-companion/assets/icon-blue.png differ
diff --git a/packages/vscode-ide-companion/assets/icon-orange.png b/packages/vscode-ide-companion/assets/icon-orange.png
new file mode 100644
index 000000000..a5afa5a0c
Binary files /dev/null and b/packages/vscode-ide-companion/assets/icon-orange.png differ
diff --git a/packages/vscode-ide-companion/package.json b/packages/vscode-ide-companion/package.json
index b47c44b52..d04fc0514 100644
--- a/packages/vscode-ide-companion/package.json
+++ b/packages/vscode-ide-companion/package.json
@@ -235,6 +235,18 @@
           ],
           "default": "china",
           "markdownDescription": "Region for Coding Plan. _(Only used when Provider is `coding-plan`)_"
+        },
+        "qwen-code.dotIndicator": {
+          "order": 3,
+          "type": "boolean",
+          "default": true,
+          "description": "Show a colored dot on the tab icon when a task completes (orange) or needs your attention (blue) while the tab is hidden."
+        },
+        "qwen-code.notifications": {
+          "order": 4,
+          "type": "boolean",
+          "default": true,
+          "description": "Show notifications with sound when a task completes (at least 20 seconds) or needs your attention, while you are not actively viewing the Qwen Code panel."
         }
       }
     },
diff --git a/packages/vscode-ide-companion/schemas/settings.schema.json b/packages/vscode-ide-companion/schemas/settings.schema.json
index 13e230672..e78f3b2cb 100644
--- a/packages/vscode-ide-companion/schemas/settings.schema.json
+++ b/packages/vscode-ide-companion/schemas/settings.schema.json
@@ -83,7 +83,7 @@
           "default": false
         },
         "language": {
-          "description": "The language for the user interface. Use \"auto\" to detect from system settings. You can also use custom language codes (e.g., \"es\", \"fr\") by placing JS language files in ~/.qwen/locales/ (e.g., ~/.qwen/locales/es.js). Options: auto, en, zh-TW, zh, ru, de, ja, pt, fr",
+          "description": "The language for the user interface. Use \"auto\" to detect from system settings. You can also use custom language codes (e.g., \"es\", \"fr\") by placing JS language files in ~/.qwen/locales/ (e.g., ~/.qwen/locales/es.js). Options: auto, en, zh-TW, zh, ru, de, ja, pt, fr, ca",
           "enum": [
             "auto",
             "en",
@@ -93,7 +93,8 @@
             "de",
             "ja",
             "pt",
-            "fr"
+            "fr",
+            "ca"
           ],
           "default": "auto"
         },
@@ -358,6 +359,11 @@
               "type": "boolean",
               "default": true
             },
+            "splitToolMedia": {
+              "description": "When true, media (images / audio / video / files) returned by MCP tool calls is split into a follow-up user message instead of being embedded in the tool message. Required for strict OpenAI-compatible servers (e.g., LM Studio) that reject non-text content on `role: \"tool\"` messages with HTTP 400 \"Invalid 'messages' in payload\". Default false preserves the prior behavior for permissive providers. See QwenLM/qwen-code#3616.",
+              "type": "boolean",
+              "default": false
+            },
             "schemaCompliance": {
               "description": "The compliance mode for tool schemas sent to the model. Use \"openapi_30\" for strict OpenAPI 3.0 compatibility (e.g., for Gemini). Options: auto, openapi_30",
               "enum": [
@@ -2009,6 +2015,11 @@
           "description": "Enable in-session cron/loop tools (experimental). When enabled, the model can create recurring prompts using cron_create, cron_list, and cron_delete tools. Can also be enabled via QWEN_CODE_ENABLE_CRON=1 environment variable.",
           "type": "boolean",
           "default": false
+        },
+        "emitToolUseSummaries": {
+          "description": "Generate a short LLM-based label after each tool batch completes. In compact mode the label replaces the generic `Tool × N` header; in full mode it appears as a dim `● <label>` line below the tool group. Requires a fast model to be configured; runs in parallel with the next API call so latency is hidden. Currently affects interactive CLI rendering only — SDK / non-interactive emission of the `tool_use_summary` message is not yet wired (the message factory is exported for a follow-up PR). Can be overridden with QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0 or =1.",
+          "type": "boolean",
+          "default": true
         }
       }
     },
diff --git a/packages/vscode-ide-companion/src/services/sessionExportService.test.ts b/packages/vscode-ide-companion/src/services/sessionExportService.test.ts
index e67f54071..e9679e3f9 100644
--- a/packages/vscode-ide-companion/src/services/sessionExportService.test.ts
+++ b/packages/vscode-ide-companion/src/services/sessionExportService.test.ts
@@ -128,6 +128,15 @@ describe('sessionExportService', () => {
         'Unsupported /export format. Use /export html, /export md, /export json, or /export jsonl.',
       );
     });
+
+    it('strips leading zero-width space placeholder before parsing', () => {
+      expect(parseExportSlashCommand('\u200B/export html')).toBe('html');
+      expect(parseExportSlashCommand('\u200B/export md')).toBe('md');
+    });
+
+    it('returns null for zero-width space only input', () => {
+      expect(parseExportSlashCommand('\u200B')).toBeNull();
+    });
   });
 
   describe('exportSessionToFile', () => {
diff --git a/packages/vscode-ide-companion/src/services/sessionExportService.ts b/packages/vscode-ide-companion/src/services/sessionExportService.ts
index 3f4ab50ea..7f202c2f1 100644
--- a/packages/vscode-ide-companion/src/services/sessionExportService.ts
+++ b/packages/vscode-ide-companion/src/services/sessionExportService.ts
@@ -23,6 +23,7 @@ import {
   isSessionExportFormat,
   type SessionExportFormat,
 } from '../utils/exportSlashCommand.js';
+import { stripZeroWidthSpaces } from '@qwen-code/webui';
 
 export { EXPORT_SESSION_FORMATS as SESSION_EXPORT_FORMATS };
 export type { SessionExportFormat } from '../utils/exportSlashCommand.js';
@@ -40,7 +41,7 @@ const EXPORT_CONFIG = {
 export function parseExportSlashCommand(
   text: string,
 ): SessionExportFormat | null {
-  const trimmed = text.replace(/\u200B/g, '').trim();
+  const trimmed = stripZeroWidthSpaces(text).trim();
   if (!trimmed.startsWith('/')) {
     return null;
   }
diff --git a/packages/vscode-ide-companion/src/webview/handlers/SessionMessageHandler.ts b/packages/vscode-ide-companion/src/webview/handlers/SessionMessageHandler.ts
index ef73630ae..1c19f9db4 100644
--- a/packages/vscode-ide-companion/src/webview/handlers/SessionMessageHandler.ts
+++ b/packages/vscode-ide-companion/src/webview/handlers/SessionMessageHandler.ts
@@ -15,6 +15,7 @@ import {
 } from '../utils/imageHandler.js';
 import { isAuthenticationRequiredError } from '../../utils/authErrors.js';
 import { getErrorMessage } from '../../utils/errorMessage.js';
+import { stripZeroWidthSpaces } from '@qwen-code/webui';
 import {
   exportSessionToFile,
   parseExportSlashCommand,
@@ -392,7 +393,7 @@ export class SessionMessageHandler extends BaseMessageHandler {
     // Guard: do not process empty or whitespace-only messages.
     // This prevents ghost user-message bubbles when slash-command completions
     // or model-selector interactions clear the input but still trigger a submit.
-    const trimmedText = text.replace(/\u200B/g, '').trim();
+    const trimmedText = stripZeroWidthSpaces(text).trim();
     const hasAttachments = (attachments?.length ?? 0) > 0;
     if (!trimmedText && !hasAttachments) {
       console.warn('[SessionMessageHandler] Ignoring empty message');
diff --git a/packages/vscode-ide-companion/src/webview/hooks/useCompletionTrigger.ts b/packages/vscode-ide-companion/src/webview/hooks/useCompletionTrigger.ts
index d61bd23c0..76aeb74eb 100644
--- a/packages/vscode-ide-companion/src/webview/hooks/useCompletionTrigger.ts
+++ b/packages/vscode-ide-companion/src/webview/hooks/useCompletionTrigger.ts
@@ -8,6 +8,7 @@ import type { RefObject } from 'react';
 import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
 import type { CompletionItem } from '../../types/completionItemTypes.js';
 import { shouldAllowCompletionQuery } from '../utils/slashCommandUtils.js';
+import { stripZeroWidthSpaces } from '@qwen-code/webui';
 
 interface CompletionTriggerState {
   isOpen: boolean;
@@ -252,7 +253,9 @@ export function useCompletionTrigger(
     };
 
     const handleInput = async () => {
-      const text = inputElement.textContent || '';
+      // Strip zero-width space placeholders before processing, consistent
+      // with InputForm's onInput handler that strips them for React state.
+      const text = stripZeroWidthSpaces(inputElement.textContent || '');
       const selection = window.getSelection();
       if (!selection || selection.rangeCount === 0) {
         console.log('[useCompletionTrigger] No selection or rangeCount === 0');
@@ -304,8 +307,12 @@ export function useCompletionTrigger(
 
       // Find trigger character before cursor
       // Use text length if cursorPosition is 0 but we have text (edge case for first character)
-      const effectiveCursorPosition =
-        cursorPosition === 0 && text.length > 0 ? text.length : cursorPosition;
+      // Clamp to text.length because the DOM cursor offset may exceed the
+      // stripped text length (e.g. after removing a leading zero-width space).
+      const effectiveCursorPosition = Math.min(
+        cursorPosition === 0 && text.length > 0 ? text.length : cursorPosition,
+        text.length,
+      );
 
       const textBeforeCursor = text.substring(0, effectiveCursorPosition);
       const lastAtMatch = textBeforeCursor.lastIndexOf('@');
diff --git a/packages/vscode-ide-companion/src/webview/hooks/useMessageSubmit.test.ts b/packages/vscode-ide-companion/src/webview/hooks/useMessageSubmit.test.ts
new file mode 100644
index 000000000..dd0479dbb
--- /dev/null
+++ b/packages/vscode-ide-companion/src/webview/hooks/useMessageSubmit.test.ts
@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import { ZERO_WIDTH_SPACE, stripZeroWidthSpaces } from '@qwen-code/webui';
+import { shouldSendMessage } from './useMessageSubmit.js';
+
+describe('ZERO_WIDTH_SPACE and stripZeroWidthSpaces', () => {
+  it('ZERO_WIDTH_SPACE is U+200B', () => {
+    expect(ZERO_WIDTH_SPACE).toBe('\u200B');
+    expect(ZERO_WIDTH_SPACE.length).toBe(1);
+  });
+
+  it('strips a single leading zero-width space', () => {
+    expect(stripZeroWidthSpaces('\u200B')).toBe('');
+  });
+
+  it('strips zero-width space before real text', () => {
+    expect(stripZeroWidthSpaces('\u200B/help')).toBe('/help');
+  });
+
+  it('strips multiple zero-width spaces', () => {
+    expect(stripZeroWidthSpaces('\u200Bhello\u200B world\u200B')).toBe(
+      'hello world',
+    );
+  });
+
+  it('returns unchanged text when no zero-width spaces present', () => {
+    expect(stripZeroWidthSpaces('hello world')).toBe('hello world');
+  });
+
+  it('returns empty string for empty input', () => {
+    expect(stripZeroWidthSpaces('')).toBe('');
+  });
+
+  it('preserves other whitespace characters', () => {
+    expect(stripZeroWidthSpaces('\u200B \t\n')).toBe(' \t\n');
+  });
+});
+
+describe('shouldSendMessage', () => {
+  const defaults = {
+    isStreaming: false,
+    isWaitingForResponse: false,
+  };
+
+  it('returns false when streaming', () => {
+    expect(
+      shouldSendMessage({ ...defaults, inputText: 'hello', isStreaming: true }),
+    ).toBe(false);
+  });
+
+  it('returns false when waiting for response', () => {
+    expect(
+      shouldSendMessage({
+        ...defaults,
+        inputText: 'hello',
+        isWaitingForResponse: true,
+      }),
+    ).toBe(false);
+  });
+
+  it('returns true for non-empty text', () => {
+    expect(shouldSendMessage({ ...defaults, inputText: 'hello' })).toBe(true);
+  });
+
+  it('returns false for empty text', () => {
+    expect(shouldSendMessage({ ...defaults, inputText: '' })).toBe(false);
+  });
+
+  it('returns false for whitespace-only text', () => {
+    expect(shouldSendMessage({ ...defaults, inputText: '   ' })).toBe(false);
+  });
+
+  it('returns false when input is only a zero-width space placeholder', () => {
+    expect(shouldSendMessage({ ...defaults, inputText: '\u200B' })).toBe(false);
+  });
+
+  it('returns false when input is zero-width space plus whitespace', () => {
+    expect(shouldSendMessage({ ...defaults, inputText: '\u200B   ' })).toBe(
+      false,
+    );
+  });
+
+  it('returns true when input has real text after zero-width space', () => {
+    expect(shouldSendMessage({ ...defaults, inputText: '\u200Bhello' })).toBe(
+      true,
+    );
+  });
+
+  it('returns true when input has only attachments and no text', () => {
+    expect(
+      shouldSendMessage({
+        ...defaults,
+        inputText: '',
+        attachedImages: [
+          {
+            id: '1',
+            name: 'test.png',
+            type: 'image/png',
+            size: 100,
+            data: 'base64data',
+            timestamp: Date.now(),
+          },
+        ],
+      }),
+    ).toBe(true);
+  });
+
+  it('returns true when input has only attachments and zero-width space', () => {
+    expect(
+      shouldSendMessage({
+        ...defaults,
+        inputText: '\u200B',
+        attachedImages: [
+          {
+            id: '1',
+            name: 'test.png',
+            type: 'image/png',
+            size: 100,
+            data: 'base64data',
+            timestamp: Date.now(),
+          },
+        ],
+      }),
+    ).toBe(true);
+  });
+});
diff --git a/packages/vscode-ide-companion/src/webview/hooks/useMessageSubmit.ts b/packages/vscode-ide-companion/src/webview/hooks/useMessageSubmit.ts
index 517d2db4e..4fad1df0f 100644
--- a/packages/vscode-ide-companion/src/webview/hooks/useMessageSubmit.ts
+++ b/packages/vscode-ide-companion/src/webview/hooks/useMessageSubmit.ts
@@ -8,6 +8,7 @@ import { useCallback } from 'react';
 import type { VSCodeAPI } from './useVSCode.js';
 import { getRandomLoadingMessage } from '../../constants/loadingMessages.js';
 import type { ImageAttachment } from './useImage.js';
+import { ZERO_WIDTH_SPACE, stripZeroWidthSpaces } from '@qwen-code/webui';
 
 interface UseMessageSubmitProps {
   vscode: VSCodeAPI;
@@ -49,7 +50,7 @@ export const shouldSendMessage = ({
     return false;
   }
 
-  const hasText = inputText.replace(/\u200B/g, '').trim().length > 0;
+  const hasText = stripZeroWidthSpaces(inputText).trim().length > 0;
   const hasAttachments = (attachedImages?.length ?? 0) > 0;
   return hasText || hasAttachments;
 };
@@ -93,7 +94,7 @@ export const useMessageSubmit = ({
       if (textToSend.trim() === '/account') {
         setInputText('');
         if (inputFieldRef.current) {
-          inputFieldRef.current.textContent = '\u200B';
+          inputFieldRef.current.textContent = ZERO_WIDTH_SPACE;
           inputFieldRef.current.setAttribute('data-empty', 'true');
         }
         vscode.postMessage({ type: 'getAccountInfo', data: {} });
@@ -104,9 +105,7 @@ export const useMessageSubmit = ({
       if (textToSend.trim() === '/login') {
         setInputText('');
         if (inputFieldRef.current) {
-          // Use a zero-width space to maintain the height of the contentEditable element
-          inputFieldRef.current.textContent = '\u200B';
-          // Set the data-empty attribute to show the placeholder
+          inputFieldRef.current.textContent = ZERO_WIDTH_SPACE;
           inputFieldRef.current.setAttribute('data-empty', 'true');
         }
         vscode.postMessage({
@@ -194,9 +193,7 @@ export const useMessageSubmit = ({
 
       setInputText('');
       if (inputFieldRef.current) {
-        // Use a zero-width space to maintain the height of the contentEditable element
-        inputFieldRef.current.textContent = '\u200B';
-        // Set the data-empty attribute to show the placeholder
+        inputFieldRef.current.textContent = ZERO_WIDTH_SPACE;
         inputFieldRef.current.setAttribute('data-empty', 'true');
       }
       fileContext.clearFileReferences();
diff --git a/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.test.ts b/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.test.ts
index 61cb7a4f7..525b5a10b 100644
--- a/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.test.ts
+++ b/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.test.ts
@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const {
   mockConfigChangeHandlers,
@@ -24,6 +24,12 @@ const {
   mockWriteModelProvidersConfig,
   mockClearPersistedAuth,
   slashCommandNotificationCallbackRef,
+  endTurnCallbackRef,
+  streamChunkCallbackRef,
+  permissionRequestCallbackRef,
+  askUserQuestionCallbackRef,
+  mockShowInformationMessage,
+  mockWindowState,
   mockQwenAgentManagerInstances,
 } = vi.hoisted(() => ({
   mockConfigChangeHandlers: [] as Array<
@@ -80,6 +86,24 @@ const {
         }) => void)
       | undefined,
   },
+  endTurnCallbackRef: {
+    current: undefined as ((reason?: string) => void) | undefined,
+  },
+  streamChunkCallbackRef: {
+    current: undefined as ((chunk: string) => void) | undefined,
+  },
+  permissionRequestCallbackRef: {
+    current: undefined as ((request: unknown) => Promise<string>) | undefined,
+  },
+  askUserQuestionCallbackRef: {
+    current: undefined as
+      | ((request: unknown) => Promise<{ optionId: string }>)
+      | undefined,
+  },
+  mockShowInformationMessage: vi.fn<
+    (message: string, ...items: string[]) => Thenable<string | undefined>
+  >(() => Promise.resolve(undefined)),
+  mockWindowState: { focused: true },
   mockQwenAgentManagerInstances: [] as Array<{
     permissionRequestCallback?: (request: unknown) => Promise<string>;
     cancelCurrentPrompt: ReturnType<typeof vi.fn>;
@@ -116,6 +140,8 @@ vi.mock('vscode', () => ({
     onDidChangeActiveTextEditor: mockOnDidChangeActiveTextEditor,
     onDidChangeTextEditorSelection: mockOnDidChangeTextEditorSelection,
     activeTextEditor: undefined,
+    showInformationMessage: mockShowInformationMessage,
+    state: mockWindowState,
   },
   workspace: {
     workspaceFolders: [{ uri: { fsPath: '/workspace-root' } }],
@@ -145,7 +171,9 @@ vi.mock('../../services/qwenAgentManager.js', () => ({
     createNewSession = vi.fn();
     setModelFromUi = vi.fn();
     onMessage = vi.fn();
-    onStreamChunk = vi.fn();
+    onStreamChunk = vi.fn((cb: (chunk: string) => void) => {
+      streamChunkCallbackRef.current = cb;
+    });
     onThoughtChunk = vi.fn();
     onModeInfo = vi.fn();
     onModeChanged = vi.fn();
@@ -175,15 +203,22 @@ vi.mock('../../services/qwenAgentManager.js', () => ({
         slashCommandNotificationCallbackRef.current = callback;
       },
     );
-    onEndTurn = vi.fn();
+    onEndTurn = vi.fn((cb: (reason?: string) => void) => {
+      endTurnCallbackRef.current = cb;
+    });
     onToolCall = vi.fn();
     onPlan = vi.fn();
     onPermissionRequest = vi.fn(
       (callback: (request: unknown) => Promise<string>) => {
         this.permissionRequestCallback = callback;
+        permissionRequestCallbackRef.current = callback;
+      },
+    );
+    onAskUserQuestion = vi.fn(
+      (callback: (request: unknown) => Promise<{ optionId: string }>) => {
+        askUserQuestionCallbackRef.current = callback;
       },
     );
-    onAskUserQuestion = vi.fn();
     onDisconnected = vi.fn();
     permissionRequestCallback?: (request: unknown) => Promise<string>;
     cancelCurrentPrompt = vi.fn();
@@ -263,6 +298,25 @@ vi.mock('../utils/imageHandler.js', () => ({
   createImagePathResolver: mockCreateImagePathResolver,
 }));
 
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('child_process')>();
+  return {
+    ...actual,
+    exec: vi.fn((_cmd: string, cb?: (err: Error | null) => void) => {
+      cb?.(null);
+    }),
+    execFile: vi.fn(
+      (_file: string, _args?: string[], cb?: (err: Error | null) => void) => {
+        if (typeof _args === 'function') {
+          (_args as unknown as (err: Error | null) => void)(null);
+        } else {
+          cb?.(null);
+        }
+      },
+    ),
+  };
+});
+
 vi.mock('../../utils/authErrors.js', () => ({
   isAuthenticationRequiredError: vi.fn(() => false),
 }));
@@ -334,6 +388,13 @@ async function setupAttachedProvider(options?: {
 
 beforeEach(() => {
   mockConfigChangeHandlers.length = 0;
+  endTurnCallbackRef.current = undefined;
+  streamChunkCallbackRef.current = undefined;
+  permissionRequestCallbackRef.current = undefined;
+  askUserQuestionCallbackRef.current = undefined;
+  mockWindowState.focused = true;
+  mockShowInformationMessage.mockReset();
+  mockShowInformationMessage.mockReturnValue(Promise.resolve(undefined));
 });
 
 describe('WebViewProvider.attachToView', () => {
@@ -1203,3 +1264,380 @@ describe('WebViewProvider initial model inheritance', () => {
     expect(agentManager.setModelFromUi).toHaveBeenCalledWith('glm-5');
   });
 });
+
+describe('Notification & dot indicator', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    mockConfigGet.mockImplementation((key: string, defaultValue?: unknown) => {
+      if (key === 'dotIndicator') {
+        return true;
+      }
+      if (key === 'notifications') {
+        return true;
+      }
+      return defaultValue;
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('shows orange dot and notification when a long task completes while panel is not active', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    // Simulate stream chunk to set agentStartTime
+    streamChunkCallbackRef.current?.('chunk');
+
+    // Advance time past 20s threshold
+    vi.advanceTimersByTime(25_000);
+
+    // Trigger endTurn
+    endTurnCallbackRef.current?.('end_turn');
+
+    // Orange dot should be set
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-orange.png'),
+      }),
+    );
+
+    // Notification should be shown
+    expect(mockShowInformationMessage).toHaveBeenCalledWith(
+      'Qwen Code: Waiting for your input.',
+      'Show',
+    );
+  });
+
+  it('does not show notification for short tasks (< 20s)', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(5_000); // only 5s
+    endTurnCallbackRef.current?.('end_turn');
+
+    // Orange dot should still appear (no duration requirement for dot)
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-orange.png'),
+      }),
+    );
+
+    // But NO notification for short task
+    expect(mockShowInformationMessage).not.toHaveBeenCalled();
+  });
+
+  it('does not show notification when user is watching the panel', async () => {
+    const mockPanel = {
+      active: true,
+      visible: true,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = true;
+
+    await setupAttachedProvider();
+
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(25_000);
+    endTurnCallbackRef.current?.('end_turn');
+
+    // No dot (panel is active)
+    expect(mockPanel.iconPath).toBeUndefined();
+    // No notification (user is watching)
+    expect(mockShowInformationMessage).not.toHaveBeenCalled();
+  });
+
+  it('shows blue dot and notification for permission requests when panel is not active', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    // Trigger permission request — don't await, it blocks on user response
+    void permissionRequestCallbackRef.current?.({
+      toolCall: { title: 'Bash' },
+      options: [],
+    });
+
+    // Blue dot
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-blue.png'),
+      }),
+    );
+
+    // Notification with tool name
+    expect(mockShowInformationMessage).toHaveBeenCalledWith(
+      'Qwen Code: Needs your permission to use Bash.',
+      'Show',
+    );
+  });
+
+  it('blue dot takes priority over orange dot', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    // First: task completes, orange dot
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(25_000);
+    endTurnCallbackRef.current?.('end_turn');
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-orange.png'),
+      }),
+    );
+
+    // Then: permission request, should upgrade to blue
+    void permissionRequestCallbackRef.current?.({
+      toolCall: { title: 'Read' },
+      options: [],
+    });
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-blue.png'),
+      }),
+    );
+
+    // Another endTurn should NOT downgrade back to orange
+    endTurnCallbackRef.current?.('end_turn');
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-blue.png'),
+      }),
+    );
+  });
+
+  it('does not send duplicate idle notifications for multi-turn tasks', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(25_000);
+
+    // First endTurn (intermediate)
+    endTurnCallbackRef.current?.('end_turn');
+    expect(mockShowInformationMessage).toHaveBeenCalledTimes(1);
+
+    // Second endTurn (final) — should NOT fire another notification
+    endTurnCallbackRef.current?.('end_turn');
+    expect(mockShowInformationMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not notify when notifications setting is disabled', async () => {
+    mockConfigGet.mockImplementation((key: string, defaultValue?: unknown) => {
+      if (key === 'notifications') {
+        return false;
+      }
+      if (key === 'dotIndicator') {
+        return true;
+      }
+      return defaultValue;
+    });
+
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(25_000);
+    endTurnCallbackRef.current?.('end_turn');
+
+    // Dot should still appear
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-orange.png'),
+      }),
+    );
+    // But no notification
+    expect(mockShowInformationMessage).not.toHaveBeenCalled();
+  });
+
+  it('cancellation resets agentStartTime so the next short task does not trigger phantom notification', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    const { messageHandler } = await setupAttachedProvider({
+      captureMessageHandler: true,
+    });
+
+    // Start a task
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(30_000);
+
+    // User sends a new message (resets timer)
+    await messageHandler?.({ type: 'sendMessage', data: { text: 'hello' } });
+
+    // Short task starts and completes quickly
+    streamChunkCallbackRef.current?.('chunk2');
+    vi.advanceTimersByTime(2_000);
+    endTurnCallbackRef.current?.('end_turn');
+
+    // Should NOT send notification (only 2s)
+    expect(mockShowInformationMessage).not.toHaveBeenCalled();
+  });
+
+  it('does not show dot when dotIndicator setting is disabled', async () => {
+    mockConfigGet.mockImplementation((key: string, defaultValue?: unknown) => {
+      if (key === 'dotIndicator') {
+        return false;
+      }
+      if (key === 'notifications') {
+        return true;
+      }
+      return defaultValue;
+    });
+
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(25_000);
+    endTurnCallbackRef.current?.('end_turn');
+
+    // Dot should NOT appear (setting disabled)
+    expect(mockPanel.iconPath).toBeUndefined();
+    // But notification should still fire
+    expect(mockShowInformationMessage).toHaveBeenCalled();
+  });
+
+  it('notifies when VS Code is focused but panel is not visible', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = true; // VS Code focused
+
+    await setupAttachedProvider();
+
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(25_000);
+    endTurnCallbackRef.current?.('end_turn');
+
+    // User is in VS Code but not looking at the panel — should notify
+    expect(mockShowInformationMessage).toHaveBeenCalledWith(
+      'Qwen Code: Waiting for your input.',
+      'Show',
+    );
+  });
+
+  it('notifies when VS Code is not focused but panel is visible', async () => {
+    const mockPanel = {
+      active: false,
+      visible: true,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false; // VS Code not focused
+
+    await setupAttachedProvider();
+
+    streamChunkCallbackRef.current?.('chunk');
+    vi.advanceTimersByTime(25_000);
+    endTurnCallbackRef.current?.('end_turn');
+
+    // User left VS Code — should notify even though panel is visible
+    expect(mockShowInformationMessage).toHaveBeenCalledWith(
+      'Qwen Code: Waiting for your input.',
+      'Show',
+    );
+  });
+
+  it('shows blue dot and notification for askUserQuestion when panel is not active', async () => {
+    const mockPanel = {
+      active: false,
+      visible: false,
+      webview: { postMessage: vi.fn() },
+      iconPath: undefined as unknown,
+    };
+    mockGetPanel.mockReturnValue(mockPanel as never);
+    mockWindowState.focused = false;
+
+    await setupAttachedProvider();
+
+    // Trigger askUserQuestion — don't await, it blocks on user response
+    void askUserQuestionCallbackRef.current?.({
+      questions: [{ question: 'Which option?' }],
+    });
+
+    // Blue dot
+    expect(mockPanel.iconPath).toEqual(
+      expect.objectContaining({
+        fsPath: expect.stringContaining('icon-blue.png'),
+      }),
+    );
+
+    // Notification without tool name (generic message)
+    expect(mockShowInformationMessage).toHaveBeenCalledWith(
+      'Qwen Code: Waiting for your input.',
+      'Show',
+    );
+  });
+});
diff --git a/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.ts b/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.ts
index 2b24293c6..8922eed26 100644
--- a/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.ts
+++ b/packages/vscode-ide-companion/src/webview/providers/WebViewProvider.ts
@@ -5,6 +5,7 @@
  */
 
 import * as vscode from 'vscode';
+import { execFile } from 'child_process';
 import { QwenAgentManager } from '../../services/qwenAgentManager.js';
 import { ConversationStore } from '../../services/conversationStore.js';
 import type {
@@ -34,6 +35,25 @@ import {
 } from '../../services/settingsWriter.js';
 import { parseInsightMessage } from '@qwen-code/qwen-code-core';
 
+/** Threshold (ms) before a completed task triggers a notification. */
+const LONG_TASK_THRESHOLD_MS = 20_000;
+
+/** Possible tab-dot colours. */
+const DotColor = {
+  /** Task completed while tab was not active. */
+  Orange: 'orange',
+  /** Agent needs user input (permission / question). Higher priority than orange. */
+  Blue: 'blue',
+} as const;
+type DotColor = (typeof DotColor)[keyof typeof DotColor];
+
+/** Asset file names for tab dot icon states. */
+const DOT_ICON: Record<DotColor | 'default', string> = {
+  orange: 'icon-orange.png',
+  blue: 'icon-blue.png',
+  default: 'icon.png',
+};
+
 const AUTH_RELATED_QWEN_SETTINGS = [
   'qwen-code.provider',
   'qwen-code.apiKey',
@@ -91,6 +111,14 @@ export class WebViewProvider {
   private autoAuthTimer: ReturnType<typeof setTimeout> | null = null;
   /** Whether an explicit interactive auth flow is currently active */
   private authFlowActive = false;
+  /** Timestamp (ms) when the current agent task started (first stream chunk) */
+  private agentStartTime: number | null = null;
+  /** Current tab-dot state: null = no dot, 'orange' = task done, 'blue' = needs attention */
+  private dotState: DotColor | null = null;
+  /** Guard: attention notification already sent for the current permission/question request */
+  private attentionNotified = false;
+  /** Guard: idle notification already sent for the current task (prevents multi-turn duplicates) */
+  private idleNotificationSent = false;
 
   constructor(
     private context: vscode.ExtensionContext,
@@ -215,6 +243,9 @@ export class WebViewProvider {
     this.agentManager.onStreamChunk((chunk: string) => {
       // Always forward stream chunks; do not gate on checkpoint saves.
       // See note in onMessage() above.
+      if (this.agentStartTime === null) {
+        this.agentStartTime = Date.now();
+      }
       this.messageHandler.appendStreamContent(chunk);
       this.sendMessageToWebView({
         type: 'streamChunk',
@@ -372,6 +403,10 @@ export class WebViewProvider {
           reason: reason || 'end_turn',
         },
       });
+      // Fire the idle notification from here (authoritative "task done" event) rather
+      // than relying on the webview's isStreaming transition, which fires on every
+      // intermediate streamEnd in multi-tool-call sequences and on cancellation.
+      this.handleAgentIdle();
     });
 
     // Note: Tool call updates are handled in handleSessionUpdate within QwenAgentManager
@@ -414,6 +449,11 @@ export class WebViewProvider {
 
     this.agentManager.onPermissionRequest(
       async (request: RequestPermissionRequest) => {
+        // Notify the user immediately (dot + optional system notification)
+        const toolTitle = (request.toolCall as { title?: string } | undefined)
+          ?.title;
+        this.handleAgentNeedsAttention(toolTitle);
+
         // Send permission request to WebView
         this.sendMessageToWebView({
           type: 'permissionRequest',
@@ -484,6 +524,8 @@ export class WebViewProvider {
                     );
                   }
 
+                  this.agentStartTime = null;
+                  this.idleNotificationSent = false;
                   this.sendMessageToWebView({
                     type: 'streamEnd',
                     data: { timestamp: Date.now(), reason: 'user_cancelled' },
@@ -552,6 +594,9 @@ export class WebViewProvider {
 
     this.agentManager.onAskUserQuestion(
       async (request: AskUserQuestionRequest) => {
+        // Notify the user immediately (dot + optional system notification)
+        this.handleAgentNeedsAttention();
+
         // Send ask user question request to WebView
         this.sendMessageToWebView({
           type: 'askUserQuestion',
@@ -608,6 +653,9 @@ export class WebViewProvider {
       console.log(
         `[WebViewProvider] Agent disconnected (code: ${code}, signal: ${signal})`,
       );
+      // Reset task timing to prevent phantom notifications after reconnect.
+      this.agentStartTime = null;
+      this.idleNotificationSent = false;
       // Only auto-reconnect for unexpected disconnects
       if (this.agentInitialized && !this.isReconnecting) {
         this.attemptAutoReconnect();
@@ -758,7 +806,11 @@ export class WebViewProvider {
 
     // Re-initialize when the view becomes visible after being hidden,
     // in case the agent was never connected (e.g. sidebar opened but collapsed).
+    // Also reset dotState so it doesn't leak into a future editor-tab panel.
     webviewView.onDidChangeVisibility(() => {
+      if (webviewView.visible) {
+        this.dotState = null;
+      }
       if (webviewView.visible && !this.agentInitialized) {
         void this.attemptAuthStateRestoration();
       }
@@ -789,6 +841,9 @@ export class WebViewProvider {
       return;
     }
 
+    // Create new panel — reset stale dot state from a previous sidebar interaction.
+    this.dotState = null;
+
     // Create new panel
     const isNewPanel = await this.panelManager.createPanel();
 
@@ -802,11 +857,15 @@ export class WebViewProvider {
     }
 
     // Set up state serialization
-    newPanel.onDidChangeViewState(() => {
-      console.log(
-        '[WebViewProvider] Panel view state changed, triggering serialization check',
-      );
-    });
+    newPanel.onDidChangeViewState(
+      () => {
+        console.log(
+          '[WebViewProvider] Panel view state changed, triggering serialization check',
+        );
+      },
+      null,
+      this.disposables,
+    );
 
     // Capture the Tab that corresponds to our WebviewPanel
     this.panelManager.captureTab();
@@ -845,6 +904,17 @@ export class WebViewProvider {
       this.disposables,
     );
 
+    // Clear the tab dot when the user switches to this panel.
+    newPanel.onDidChangeViewState(
+      () => {
+        if (newPanel.visible) {
+          this.clearTabDot();
+        }
+      },
+      null,
+      this.disposables,
+    );
+
     // Listen for view state changes (no pin/lock; just keep tab reference fresh)
     this.panelManager.registerViewStateChangeHandler(this.disposables);
 
@@ -1674,6 +1744,236 @@ export class WebViewProvider {
     return true;
   }
 
+  /**
+   * Handle common webview message types shared across all host contexts
+   * (sidebar, new panel, restored panel). Returns true if the message was
+   * fully handled and the caller should skip further processing.
+   *
+   * Note: the `sendMessage` branch resets notification timers as a
+   * side effect but returns false so the message is still routed to
+   * handlers. This avoids duplicating the reset across 3 call sites.
+   */
+  private async handleCommonWebviewMessage(
+    message: { type: string; data?: unknown },
+    webview: vscode.Webview,
+  ): Promise<boolean> {
+    if (message.type === 'openDiff' && this.isAutoMode()) {
+      return true;
+    }
+    if (message.type === 'webviewReady') {
+      this.handleWebviewReady();
+      return true;
+    }
+    if (message.type === 'contextMenuTriggered') {
+      WebViewProvider.lastContextMenuProvider = this;
+      return true;
+    }
+    if (message.type === 'copyToClipboard') {
+      const { text } = message.data as { text: string };
+      await vscode.env.clipboard.writeText(text);
+      return true;
+    }
+    if (message.type === 'resolveImagePaths') {
+      this.handleResolveImagePaths(message.data, webview);
+      return true;
+    }
+    if (await this.handleOpenInsightReportMessage(message)) {
+      return true;
+    }
+    // Reset task timer and notification guard when user sends a new message.
+    // Falls through (returns false) so the message is still routed to handlers.
+    if (message.type === 'sendMessage') {
+      this.agentStartTime = null;
+      this.idleNotificationSent = false;
+    }
+    return false;
+  }
+
+  /** Update the tab-dot icon. Blue takes priority over orange. */
+  private setTabDot(color: DotColor): void {
+    const config = vscode.workspace.getConfiguration('qwen-code');
+    if (!config.get<boolean>('dotIndicator', true)) {
+      return;
+    }
+    // Blue takes priority; never downgrade from blue to orange.
+    if (this.dotState === DotColor.Blue && color === DotColor.Orange) {
+      return;
+    }
+    this.dotState = color;
+    const panel = this.panelManager.getPanel();
+    if (!panel) {
+      // No-op in sidebar mode: WebviewView has no iconPath property.
+      return;
+    }
+    panel.iconPath = vscode.Uri.joinPath(
+      this.extensionUri,
+      'assets',
+      DOT_ICON[color],
+    );
+  }
+
+  /** Clear the tab-dot icon, restoring the default icon. */
+  private clearTabDot(): void {
+    if (this.dotState === null) {
+      return;
+    }
+    this.dotState = null;
+    const panel = this.panelManager.getPanel();
+    if (!panel) {
+      return;
+    }
+    panel.iconPath = vscode.Uri.joinPath(
+      this.extensionUri,
+      'assets',
+      DOT_ICON.default,
+    );
+  }
+
+  /**
+   * Play the user's system alert / notification sound.
+   *
+   * SECURITY: all arguments to execFile are hardcoded string literals.
+   * Never interpolate user-supplied data into these arguments — execFile
+   * bypasses the shell but PowerShell still interprets its -c argument.
+   */
+  private playNotificationSound(): void {
+    const onError = (err: Error | null) => {
+      if (err) {
+        console.warn(
+          '[WebViewProvider] Notification sound failed:',
+          err.message,
+        );
+      }
+    };
+    if (process.platform === 'darwin') {
+      execFile('afplay', ['/System/Library/Sounds/Glass.aiff'], onError);
+    } else if (process.platform === 'win32') {
+      execFile(
+        'powershell',
+        ['-c', '[System.Media.SystemSounds]::Asterisk.Play()'],
+        onError,
+      );
+    } else {
+      // canberra-gtk-play is the most "native" option; fall back to paplay.
+      execFile('canberra-gtk-play', ['--id=bell'], (err) => {
+        if (err) {
+          execFile(
+            'paplay',
+            ['/usr/share/sounds/freedesktop/stereo/complete.oga'],
+            (paErr) => {
+              if (paErr) {
+                console.warn(
+                  '[WebViewProvider] paplay fallback failed:',
+                  paErr.message,
+                );
+              }
+            },
+          );
+        }
+      });
+    }
+  }
+
+  /**
+   * Show a VS Code notification with sound and a "Show" button that focuses
+   * the Qwen Code panel (or sidebar view) when clicked.
+   */
+  private notifyUser(message: string): void {
+    void vscode.window
+      .showInformationMessage(`Qwen Code: ${message}`, 'Show')
+      .then((action) => {
+        if (action === 'Show') {
+          const panel = this.panelManager.getPanel();
+          if (panel) {
+            panel.reveal();
+          } else if (this.isViewHost) {
+            // Sidebar / secondary bar — focus the view via its command.
+            void vscode.commands.executeCommand('qwen-code.focusChat');
+          }
+        }
+      });
+    this.playNotificationSound();
+  }
+
+  /**
+   * Whether the user can currently see the Qwen Code panel.
+   * Only true when VS Code is the foreground app AND the panel tab is visible.
+   * If either condition is false the user needs a notification.
+   */
+  private isUserWatchingPanel(): boolean {
+    const panel = this.panelManager.getPanel();
+    const panelVisible = panel?.visible ?? false;
+    const windowFocused = vscode.window.state.focused;
+    return windowFocused && panelVisible;
+  }
+
+  /** Whether the qwen-code.notifications setting is enabled. */
+  private isNotificationsEnabled(): boolean {
+    return vscode.workspace
+      .getConfiguration('qwen-code')
+      .get<boolean>('notifications', true);
+  }
+
+  /** Called when the agent finishes a turn (authoritative end-of-task event). */
+  private handleAgentIdle(): void {
+    // Read agentStartTime but do NOT reset it here — multi-turn tasks fire
+    // onEndTurn multiple times and resetting would lose the true start time.
+    // It is reset when the user sends the next message (see onDidReceiveMessage).
+    const startTime = this.agentStartTime;
+    this.attentionNotified = false; // reset for next permission/question cycle
+
+    const panel = this.panelManager.getPanel();
+    const panelActive = panel?.active ?? false;
+
+    // Show orange dot when the tab is not the active/focused editor.
+    if (!panelActive) {
+      this.setTabDot(DotColor.Orange);
+    }
+
+    // System notification.
+    if (!this.isNotificationsEnabled()) {
+      return;
+    }
+
+    const userWatching = this.isUserWatchingPanel();
+    const taskDurationMs = startTime !== null ? Date.now() - startTime : 0;
+
+    if (
+      !userWatching &&
+      taskDurationMs >= LONG_TASK_THRESHOLD_MS &&
+      !this.idleNotificationSent
+    ) {
+      this.idleNotificationSent = true;
+      this.notifyUser('Waiting for your input.');
+    }
+  }
+
+  /**
+   * Called when the agent needs user attention (permission request or ask-question).
+   * @param detail - optional context, e.g. the tool name that needs approval.
+   */
+  private handleAgentNeedsAttention(detail?: string): void {
+    const panel = this.panelManager.getPanel();
+    const panelActive = panel?.active ?? false;
+
+    if (!panelActive) {
+      this.setTabDot(DotColor.Blue);
+    }
+
+    const userWatching = this.isUserWatchingPanel();
+
+    // Notify once per request regardless of task duration.
+    if (!userWatching && !this.attentionNotified) {
+      this.attentionNotified = true;
+      if (this.isNotificationsEnabled()) {
+        const message = detail
+          ? `Needs your permission to use ${detail}.`
+          : 'Waiting for your input.';
+        this.notifyUser(message);
+      }
+    }
+  }
+
   /**
    * Send message to WebView
    */
@@ -1729,41 +2029,6 @@ export class WebViewProvider {
     return this.currentModeId;
   }
 
-  /**
-   * Handle common webview message types shared across all host contexts
-   * (sidebar view, editor panel, restored panel).
-   * Returns true if the message was handled and no further processing is needed.
-   */
-  private async handleCommonWebviewMessage(
-    message: { type: string; data?: unknown },
-    webview: vscode.Webview,
-  ): Promise<boolean> {
-    if (message.type === 'openDiff' && this.isAutoMode()) {
-      return true;
-    }
-    if (message.type === 'webviewReady') {
-      this.handleWebviewReady();
-      return true;
-    }
-    if (message.type === 'contextMenuTriggered') {
-      WebViewProvider.lastContextMenuProvider = this;
-      return true;
-    }
-    if (message.type === 'copyToClipboard') {
-      const { text } = message.data as { text: string };
-      await vscode.env.clipboard.writeText(text);
-      return true;
-    }
-    if (message.type === 'resolveImagePaths') {
-      this.handleResolveImagePaths(message.data, webview);
-      return true;
-    }
-    if (await this.handleOpenInsightReportMessage(message)) {
-      return true;
-    }
-    return false;
-  }
-
   /** True if diffs/permissions should be auto-handled without prompting. */
   isAutoMode(): boolean {
     return this.currentModeId === 'auto-edit' || this.currentModeId === 'yolo';
@@ -1869,12 +2134,18 @@ export class WebViewProvider {
     );
     this.panelManager.setPanel(panel);
 
-    // Ensure restored tab title starts from default label
+    // Ensure restored tab starts from default label and icon
+    this.dotState = null;
     try {
       panel.title = 'Qwen Code';
+      panel.iconPath = vscode.Uri.joinPath(
+        this.extensionUri,
+        'assets',
+        DOT_ICON.default,
+      );
     } catch (e) {
       console.warn(
-        '[WebViewProvider] Failed to reset restored panel title:',
+        '[WebViewProvider] Failed to reset restored panel title/icon:',
         e,
       );
     }
@@ -1928,6 +2199,17 @@ export class WebViewProvider {
       this.disposables,
     );
 
+    // Clear the tab dot when the user switches to this restored panel.
+    panel.onDidChangeViewState(
+      () => {
+        if (panel.visible) {
+          this.clearTabDot();
+        }
+      },
+      null,
+      this.disposables,
+    );
+
     // Register view state change handler
     this.panelManager.registerViewStateChangeHandler(this.disposables);
 
diff --git a/packages/webui/src/components/layout/InputForm.tsx b/packages/webui/src/components/layout/InputForm.tsx
index ca28e996e..09a8a71e7 100644
--- a/packages/webui/src/components/layout/InputForm.tsx
+++ b/packages/webui/src/components/layout/InputForm.tsx
@@ -23,6 +23,7 @@ import { ContextIndicator } from './ContextIndicator.js';
 import type { CompletionItem } from '../../types/completion.js';
 import type { ContextUsage } from './ContextIndicator.js';
 import type { FollowupState } from '../../types/followup.js';
+import { stripZeroWidthSpaces } from '../../utils/inputPlaceholder.js';
 
 /**
  * Edit mode display information
@@ -203,7 +204,7 @@ export const InputForm: FC<InputFormProps> = ({
 }) => {
   const composerDisabled = isStreaming || isWaitingForResponse;
   const hasDraftContent =
-    canSubmit ?? inputText.replace(/\u200B/g, '').trim().length > 0;
+    canSubmit ?? stripZeroWidthSpaces(inputText).trim().length > 0;
   const completionItemsResolved = completionItems ?? [];
   const completionActive =
     completionIsOpen &&
@@ -337,14 +338,14 @@ export const InputForm: FC<InputFormProps> = ({
               // Use a data flag so CSS can show placeholder even if the browser
               // inserts an invisible <br> into contentEditable (so :empty no longer matches)
               data-empty={
-                inputText.replace(/\u200B/g, '').trim().length === 0
+                stripZeroWidthSpaces(inputText).trim().length === 0
                   ? 'true'
                   : 'false'
               }
               onInput={(e) => {
                 const target = e.target as HTMLDivElement;
                 // Filter out zero-width space that we use to maintain height
-                const text = target.textContent?.replace(/\u200B/g, '') || '';
+                const text = stripZeroWidthSpaces(target.textContent ?? '');
                 onInputChange(text);
                 // Dismiss follow-up suggestion when user starts typing
                 if (hasFollowup && !inputText && text) {
diff --git a/packages/webui/src/index.ts b/packages/webui/src/index.ts
index 06acc35ac..56bbc89aa 100644
--- a/packages/webui/src/index.ts
+++ b/packages/webui/src/index.ts
@@ -260,6 +260,10 @@ export type { CompletionItem, CompletionItemType } from './types/completion';
 // Utils
 export { groupSessionsByDate, getTimeAgo } from './utils/sessionGrouping';
 export type { SessionGroup } from './utils/sessionGrouping';
+export {
+  ZERO_WIDTH_SPACE,
+  stripZeroWidthSpaces,
+} from './utils/inputPlaceholder';
 
 // Adapters - for normalizing different data formats
 export {
diff --git a/packages/webui/src/utils/inputPlaceholder.ts b/packages/webui/src/utils/inputPlaceholder.ts
new file mode 100644
index 000000000..44acf3c3a
--- /dev/null
+++ b/packages/webui/src/utils/inputPlaceholder.ts
@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Zero-width space used as a height placeholder in contentEditable inputs.
+ *
+ * After clearing a contentEditable element (e.g. on message submit), setting
+ * its textContent to this character keeps the element at its normal line height
+ * instead of collapsing to zero height. All downstream consumers must strip
+ * this character before treating the text as real user input.
+ */
+export const ZERO_WIDTH_SPACE = '\u200B';
+
+/**
+ * Strip {@link ZERO_WIDTH_SPACE} placeholders from text.
+ *
+ * @param text - raw text that may contain zero-width spaces
+ * @returns text with all zero-width spaces removed
+ */
+export function stripZeroWidthSpaces(text: string): string {
+  return text.replace(/\u200B/g, '');
+}
diff --git a/scripts/benchmark-api-latency.mjs b/scripts/benchmark-api-latency.mjs
new file mode 100644
index 000000000..3ed38c4c3
--- /dev/null
+++ b/scripts/benchmark-api-latency.mjs
@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * API Preconnect Latency Benchmark
+ *
+ * Measures the real TCP+TLS connection reuse benefit of preconnect by using
+ * undici (the same library as apiPreconnect.ts) within a single process.
+ *
+ * Unlike the previous curl-based approach, this correctly measures connection
+ * pool reuse: the same dispatcher instance is shared between the preconnect
+ * HEAD request and the subsequent measured request, just like in production.
+ *
+ * Usage:
+ *   node scripts/benchmark-api-latency.mjs
+ *
+ * Environment variables:
+ *   ITERATIONS=3              Number of cold/warm pairs per endpoint (default: 3)
+ *   REQUEST_TIMEOUT_MS=5000   Per-request timeout in ms (default: 5000)
+ *   BENCHMARK_URLS            Space-separated extra URLs to benchmark
+ */
+
+import { createRequire } from 'module';
+import { performance } from 'perf_hooks';
+
+// Resolve undici from the core package (same version used by preconnect)
+const require = createRequire(import.meta.url);
+const { Agent } = require('../packages/core/node_modules/undici/index.js');
+
+const ITERATIONS = parseInt(process.env['ITERATIONS'] ?? '3', 10);
+const REQUEST_TIMEOUT_MS = parseInt(process.env['REQUEST_TIMEOUT_MS'] ?? '5000', 10);
+
+const DEFAULT_ENDPOINTS = [
+  { url: 'https://api.openai.com',                              label: 'OpenAI' },
+  { url: 'https://api.anthropic.com',                          label: 'Anthropic' },
+  { url: 'https://dashscope.aliyuncs.com/compatible-mode/v1', label: 'DashScope (openai-compatible)' },
+];
+
+const extraUrls = process.env['BENCHMARK_URLS']
+  ? process.env['BENCHMARK_URLS'].split(' ').filter(Boolean).map((url) => ({ url, label: url }))
+  : [];
+
+const ENDPOINTS = [...DEFAULT_ENDPOINTS, ...extraUrls];
+
+// ---------------------------------------------------------------------------
+
+function newDispatcher() {
+  return new Agent({
+    headersTimeout: 0,
+    bodyTimeout: 0,
+    keepAliveTimeout: 60_000,
+  });
+}
+
+async function fetchOnce(url, dispatcher, method = 'HEAD') {
+  const start = performance.now();
+  try {
+    await fetch(url, {
+      method,
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      headers: { 'User-Agent': 'QwenCode-Benchmark/1.0' },
+      dispatcher,
+    });
+  } catch (err) {
+    // Timeouts and non-2xx are fine — we only care about connection timing
+    if (err?.name === 'TimeoutError') {
+      return performance.now() - start; // still records the time spent
+    }
+  }
+  return performance.now() - start;
+}
+
+/**
+ * Cold measurement: brand-new dispatcher, no preconnect.
+ * Returns elapsed ms of the measured request.
+ */
+async function measureCold(url) {
+  const dispatcher = newDispatcher();
+  return fetchOnce(url, dispatcher, 'HEAD');
+}
+
+/**
+ * Warm measurement: same dispatcher for preconnect HEAD + measured request.
+ * Returns elapsed ms of the measured request only (not the preconnect time).
+ */
+async function measureWarm(url) {
+  const dispatcher = newDispatcher();
+  // Preconnect — mirrors apiPreconnect.ts behaviour
+  await fetchOnce(url, dispatcher, 'HEAD').catch(() => {});
+  // Measured request reuses the warmed connection from the same pool
+  return fetchOnce(url, dispatcher, 'HEAD');
+}
+
+// ---------------------------------------------------------------------------
+
+function fmt(ms) {
+  return `${ms.toFixed(1)}ms`;
+}
+
+function avg(arr) {
+  return arr.reduce((a, b) => a + b, 0) / arr.length;
+}
+
+async function benchmarkEndpoint({ url, label }) {
+  console.log(`\n  ${label}`);
+  console.log(`  ${url}`);
+
+  const coldTimes = [];
+  const warmTimes = [];
+
+  for (let i = 0; i < ITERATIONS; i++) {
+    const cold = await measureCold(url);
+    coldTimes.push(cold);
+
+    // Brief pause so the OS can release the cold connection
+    await new Promise((r) => setTimeout(r, 500));
+
+    const warm = await measureWarm(url);
+    warmTimes.push(warm);
+
+    console.log(`    run ${i + 1}: cold=${fmt(cold)}  warm=${fmt(warm)}`);
+
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  const avgCold = avg(coldTimes);
+  const avgWarm = avg(warmTimes);
+  const saved = avgCold - avgWarm;
+  const pct = avgCold > 0 ? (saved / avgCold) * 100 : 0;
+
+  return { label, url, avgCold, avgWarm, saved, pct };
+}
+
+// ---------------------------------------------------------------------------
+
+console.log('=== Qwen Code API Preconnect Latency Benchmark ===');
+console.log(`Iterations per endpoint : ${ITERATIONS}`);
+console.log(`Request timeout         : ${REQUEST_TIMEOUT_MS}ms`);
+console.log('\nRunning...');
+
+const results = [];
+for (const endpoint of ENDPOINTS) {
+  const result = await benchmarkEndpoint(endpoint);
+  results.push(result);
+}
+
+// Summary table
+console.log('\n\n=== Results ===\n');
+console.log(
+  'Endpoint'.padEnd(36) +
+  'Cold (avg)'.padStart(12) +
+  'Warm (avg)'.padStart(12) +
+  'Saved'.padStart(10) +
+  'Improvement'.padStart(13),
+);
+console.log('─'.repeat(83));
+
+for (const r of results) {
+  const status = r.pct >= 30 ? '✓' : r.pct >= 10 ? '~' : '✗';
+  console.log(
+    r.label.slice(0, 35).padEnd(36) +
+    fmt(r.avgCold).padStart(12) +
+    fmt(r.avgWarm).padStart(12) +
+    fmt(r.saved).padStart(10) +
+    `${r.pct.toFixed(1)}% ${status}`.padStart(13),
+  );
+}
+
+console.log('\nLegend: ✓ ≥30% improvement   ~ 10–30%   ✗ <10%');
diff --git a/scripts/test-rewind-e2e.sh b/scripts/test-rewind-e2e.sh
new file mode 100755
index 000000000..394780372
--- /dev/null
+++ b/scripts/test-rewind-e2e.sh
@@ -0,0 +1,472 @@
+#!/usr/bin/env bash
+# =============================================================================
+# test-rewind-e2e.sh — tmux-based E2E verification for the conversation rewind
+# feature (PR #3441).
+#
+# Covers all 5 manual test items from the PR description:
+#   1. /rewind command → pick turn → UI truncated, input pre-populated
+#   2. Double-ESC on empty prompt → selector opens → rewind → continue
+#   3. ESC during streaming → cancels request, does NOT open selector
+#   4. /rewind with no history → selector does not open
+#   5. After rewind, model does not reference removed turns
+#
+# Prerequisites:
+#   - tmux installed
+#   - CLI already built:  npm run build && npm run bundle
+#   - Valid model API credentials in environment
+#
+# Usage:
+#   bash scripts/test-rewind-e2e.sh
+# =============================================================================
+
+set -uo pipefail
+
+SESSION="test-rewind-$$"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+BUNDLE="$PROJECT_DIR/dist/cli.js"
+WORKDIR="$(mktemp -d)"
+PASS_COUNT=0
+FAIL_COUNT=0
+TIMEOUT=${REWIND_TEST_TIMEOUT:-120}  # seconds per wait_for call
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+cleanup() {
+  tmux kill-session -t "$SESSION" 2>/dev/null || true
+  rm -rf "$WORKDIR"
+}
+trap cleanup EXIT
+
+start_session() {
+  # Deliver ESC immediately — without this, tmux holds ESC for up to 500ms
+  # thinking it might be the start of an escape sequence, which breaks
+  # double-ESC detection and other ESC-dependent interactions.
+  # Must be set as a server option (not session) in tmux 2.6+.
+  tmux set-option -sg escape-time 0 2>/dev/null || true
+  tmux new-session -d -s "$SESSION" -x 120 -y 40 \
+    "cd '$WORKDIR' && node '$BUNDLE' --approval-mode yolo 2>'$WORKDIR/stderr.log'"
+  wait_for_prompt 60
+}
+
+kill_session() {
+  tmux kill-session -t "$SESSION" 2>/dev/null || true
+  sleep 1
+}
+
+# Capture entire pane including scrollback (for content assertions)
+capture() {
+  tmux capture-pane -t "$SESSION" -p -S -200 2>/dev/null || true
+}
+
+# Capture only the visible pane (for prompt detection)
+capture_visible() {
+  tmux capture-pane -t "$SESSION" -p 2>/dev/null || true
+}
+
+send() {
+  # Type text using literal mode then press Enter
+  tmux send-keys -t "$SESSION" -l "$1"
+  sleep 0.5
+  tmux send-keys -t "$SESSION" Enter
+}
+
+send_keys() {
+  tmux send-keys -t "$SESSION" "$@"
+}
+
+# Wait for "Type your message" to appear on the visible pane.
+wait_for_prompt() {
+  local timeout="${1:-$TIMEOUT}"
+  local elapsed=0
+
+  while [ $elapsed -lt "$timeout" ]; do
+    if capture_visible | grep -qF "Type your message"; then
+      return 0
+    fi
+    sleep 2
+    elapsed=$((elapsed + 2))
+  done
+  echo -e "${RED}TIMEOUT waiting for prompt (Type your message)${RESET}" >&2
+  echo "--- Visible pane ---" >&2
+  capture_visible >&2
+  echo "--- End ---" >&2
+  return 1
+}
+
+# Wait for the CLI to be truly idle:
+#   1. "Type your message" is visible (prompt ready)
+#   2. No "esc to cancel" on screen (no btw/side-query running)
+#   3. Screen content unchanged for 3 consecutive seconds
+wait_idle() {
+  local timeout="${1:-$TIMEOUT}"
+  local elapsed=0
+  local last_hash=""
+  local stable_count=0
+
+  while [ $elapsed -lt "$timeout" ]; do
+    local screen
+    screen=$(capture_visible)
+
+    # Must have prompt visible
+    if ! echo "$screen" | grep -qF "Type your message"; then
+      stable_count=0
+      last_hash=""
+      sleep 2
+      elapsed=$((elapsed + 2))
+      continue
+    fi
+
+    # Must not have btw side-query running
+    if echo "$screen" | grep -qF "esc to cancel"; then
+      stable_count=0
+      last_hash=""
+      sleep 2
+      elapsed=$((elapsed + 2))
+      continue
+    fi
+
+    # Check screen stability
+    local current
+    current=$(echo "$screen" | md5sum | cut -d' ' -f1)
+    if [ "$current" = "$last_hash" ]; then
+      stable_count=$((stable_count + 1))
+      if [ $stable_count -ge 3 ]; then
+        return 0
+      fi
+    else
+      last_hash="$current"
+      stable_count=0
+    fi
+    sleep 1
+    elapsed=$((elapsed + 1))
+  done
+  echo -e "${RED}TIMEOUT waiting for idle${RESET}" >&2
+  echo "--- Visible pane ---" >&2
+  capture_visible >&2
+  echo "--- End ---" >&2
+  return 1
+}
+
+# Wait for text to appear on the visible pane
+wait_for() {
+  local text="$1"
+  local timeout="${2:-$TIMEOUT}"
+  local elapsed=0
+  while [ $elapsed -lt "$timeout" ]; do
+    if capture_visible | grep -qF "$text"; then
+      return 0
+    fi
+    sleep 2
+    elapsed=$((elapsed + 2))
+  done
+  echo -e "${RED}TIMEOUT waiting for: ${text}${RESET}" >&2
+  echo "--- Visible pane ---" >&2
+  capture_visible >&2
+  echo "--- End ---" >&2
+  return 1
+}
+
+# Assert text IS on visible pane
+assert_screen() {
+  local text="$1"
+  if capture_visible | grep -qF "$text"; then
+    return 0
+  fi
+  echo -e "${RED}ASSERT FAILED: expected '${text}' on screen${RESET}" >&2
+  echo "--- Visible pane ---" >&2
+  capture_visible >&2
+  echo "--- End ---" >&2
+  return 1
+}
+
+# Assert text IS on full capture (including scrollback)
+assert_scrollback() {
+  local text="$1"
+  if capture | grep -qF "$text"; then
+    return 0
+  fi
+  echo -e "${RED}ASSERT FAILED: expected '${text}' in scrollback${RESET}" >&2
+  return 1
+}
+
+# Assert text is NOT on visible pane
+assert_no_screen() {
+  local text="$1"
+  if capture_visible | grep -qF "$text"; then
+    echo -e "${RED}ASSERT FAILED: did NOT expect '${text}' on screen${RESET}" >&2
+    echo "--- Visible pane ---" >&2
+    capture_visible >&2
+    echo "--- End ---" >&2
+    return 1
+  fi
+  return 0
+}
+
+pass() {
+  echo -e "${GREEN}[PASS]${RESET} $1"
+  PASS_COUNT=$((PASS_COUNT + 1))
+}
+
+fail() {
+  echo -e "${RED}[FAIL]${RESET} $1: $2"
+  FAIL_COUNT=$((FAIL_COUNT + 1))
+}
+
+# Run a test function, capturing its exit code properly.
+# Usage: run_test "Test Name" test_function_name
+run_test() {
+  local name="$1"
+  local func="$2"
+  local rc=0
+  local errmsg=""
+
+  errmsg=$($func 2>&1) || rc=$?
+
+  if [ $rc -eq 0 ]; then
+    pass "$name"
+  else
+    # Extract last meaningful error line from stderr
+    local last_err
+    last_err=$(echo "$errmsg" | grep -E 'TIMEOUT|ASSERT FAILED' | tail -1)
+    fail "$name" "${last_err:-exit code $rc}"
+    echo "$errmsg" | head -30
+  fi
+
+  # Always clean up the session between tests
+  kill_session 2>/dev/null || true
+}
+
+# ---------------------------------------------------------------------------
+# Pre-flight checks
+# ---------------------------------------------------------------------------
+
+if ! command -v tmux &>/dev/null; then
+  echo -e "${RED}Error: tmux is not installed${RESET}" >&2
+  exit 1
+fi
+
+if [ ! -f "$BUNDLE" ]; then
+  echo -e "${YELLOW}Bundle not found at $BUNDLE, building...${RESET}"
+  (cd "$PROJECT_DIR" && npm run build && npm run bundle)
+fi
+
+echo -e "${BOLD}=== Rewind Feature E2E Tests (tmux) ===${RESET}"
+echo "Session: $SESSION"
+echo "Workdir: $WORKDIR"
+echo ""
+
+# ---------------------------------------------------------------------------
+# Test 1: /rewind command flow
+# ---------------------------------------------------------------------------
+
+test_rewind_command() {
+  start_session
+
+  # Build 3-turn conversation with unique markers
+  send "say exactly ALPHA1 and nothing else"
+  wait_idle || return 1
+
+  send "say exactly BETA2 and nothing else"
+  wait_idle || return 1
+
+  send "say exactly GAMMA3 and nothing else"
+  wait_idle || return 1
+
+  # Open rewind selector via /rewind command
+  send "/rewind"
+  wait_for "Rewind Conversation" || return 1
+
+  # Navigate up to select BETA2 turn (selector starts at last turn GAMMA3)
+  send_keys Up
+  sleep 0.5
+
+  # Select the turn
+  send_keys Enter
+  sleep 1
+  wait_for "confirm" 15 || return 1
+
+  # Confirm rewind
+  send_keys y
+  wait_for "Conversation rewound" || return 1
+
+  # After rewind: pressing Up once from the initial selection (GAMMA3, the last
+  # real user turn) lands on BETA2. Rewind targets BETA2, so its text gets
+  # pre-populated into the input bar. Slash commands like /rewind are excluded
+  # from the turn list by isRealUserTurn().
+  assert_screen "say exactly BETA2" || return 1
+  # Verify the earlier turn (ALPHA1) is still in conversation
+  assert_scrollback "ALPHA1" || return 1
+}
+
+run_test "Test 1: /rewind command flow" test_rewind_command
+
+# ---------------------------------------------------------------------------
+# Test 2: Double-ESC opens selector
+# ---------------------------------------------------------------------------
+
+test_double_esc() {
+  start_session
+
+  send "say exactly DELTA4 and nothing else"
+  wait_idle || return 1
+
+  send "say exactly EPSILON5 and nothing else"
+  wait_idle || return 1
+
+  # Double-ESC to open rewind selector.
+  # Complication: a btw side-question (prompt suggestion) may be active after
+  # the model responds. If btwItem is non-null, the first ESC cancels the btw
+  # (AppContainer.tsx:1896) and never reaches the rewind handler. We send
+  # 3 ESCs with proper timing to handle both btw-present and btw-absent cases:
+  #   ESC #1: cancels btw (if present), or starts rewind pending (if absent)
+  #   sleep 1.5s: >800ms to reset any rewind pending from ESC #1
+  #   ESC #2: starts rewind pending (btw now dismissed)
+  #   sleep 0.3s: within 800ms window
+  #   ESC #3: triggers rewind selector
+  send_keys Escape
+  sleep 1.5
+  send_keys Escape
+  sleep 0.5
+  wait_for "Esc again to rewind" 15 || return 1
+
+  # Third ESC within 800ms — should open selector
+  send_keys Escape
+  wait_for "Rewind Conversation" || return 1
+
+  # Select last turn (pre-selected) & confirm
+  send_keys Enter
+  sleep 1
+  send_keys y
+  wait_for "Conversation rewound" || return 1
+
+  # Continue conversation after rewind — verify model still works
+  send "say exactly ZETA6 and nothing else"
+  wait_idle || return 1
+  assert_scrollback "ZETA6" || return 1
+}
+
+run_test "Test 2: Double-ESC opens selector" test_double_esc
+
+# ---------------------------------------------------------------------------
+# Test 3: ESC during streaming cancels (no rewind)
+# ---------------------------------------------------------------------------
+
+test_esc_during_streaming() {
+  start_session
+
+  # Send a prompt that will generate a long response
+  send "write a detailed 500 word essay about the history of computing from 1940 to 2000"
+
+  # Wait for streaming to start (prompt disappears)
+  sleep 4
+
+  # Single ESC while streaming — should cancel, NOT open rewind
+  send_keys Escape
+
+  # Verify rewind selector did NOT open
+  sleep 3
+  assert_no_screen "Rewind Conversation" || return 1
+
+  # Should eventually return to idle
+  wait_idle || return 1
+}
+
+run_test "Test 3: ESC during streaming cancels (no rewind)" test_esc_during_streaming
+
+# ---------------------------------------------------------------------------
+# Test 4: /rewind with no prior conversation
+# ---------------------------------------------------------------------------
+
+test_rewind_no_history() {
+  start_session
+
+  # Immediately try /rewind with no conversation history.
+  # The /rewind text itself gets recorded as a user turn before the slash
+  # command handler runs, so the guard (≥1 user turn) passes and the
+  # selector opens showing only the "/rewind" entry — which is not a
+  # meaningful rewindable turn. We verify the selector has only 1 turn.
+  send "/rewind"
+  sleep 3
+
+  # The selector may or may not open depending on implementation.
+  # If it opens, it should show exactly "1 turns" (only the /rewind itself).
+  if capture_visible | grep -qF "Rewind Conversation"; then
+    assert_screen "1 turns" || return 1
+    # Close the selector with ESC
+    send_keys Escape
+    sleep 1
+  fi
+
+  # Either way, after dismissing we should be back at the prompt
+  wait_for_prompt 10 || return 1
+}
+
+run_test "Test 4: /rewind with no prior conversation" test_rewind_no_history
+
+# ---------------------------------------------------------------------------
+# Test 5: After rewind, model ignores removed turns
+# ---------------------------------------------------------------------------
+
+test_rewind_context_isolation() {
+  start_session
+
+  # First turn: give model a unique fact
+  send "The secret code for this session is XRAY99. Just confirm you received it by saying OK."
+  wait_idle || return 1
+
+  # Second turn: different content
+  send "say exactly YANKEEZ and nothing else"
+  wait_idle || return 1
+
+  # Rewind to remove the YANKEEZ turn
+  send "/rewind"
+  wait_for "Rewind Conversation" || return 1
+
+  # Select the most recent turn (YANKEEZ) and confirm
+  send_keys Enter
+  sleep 1
+  send_keys y
+  wait_for "Conversation rewound" || return 1
+
+  # Clear pre-populated input (Ctrl-U clears line in most terminals)
+  send_keys C-u
+  sleep 0.5
+
+  # Ask the model what it remembers
+  send "What was the secret code I told you? Reply with just the code, nothing else."
+  wait_idle || return 1
+
+  # Model should reference XRAY99 (surviving turn)
+  assert_scrollback "XRAY99" || return 1
+}
+
+run_test "Test 5: After rewind, model ignores removed turns" test_rewind_context_isolation
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+echo ""
+echo -e "${BOLD}=== Results ===${RESET}"
+echo -e "${GREEN}Passed: ${PASS_COUNT}${RESET}"
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  echo -e "${RED}Failed: ${FAIL_COUNT}${RESET}"
+else
+  echo -e "Failed: 0"
+fi
+
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  exit 1
+fi
+
+echo -e "${GREEN}All ${PASS_COUNT} tests passed.${RESET}"