@qwen-code/qwen-code 0.16.1 → 0.16.2

package/bundled/new-app/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: new-app
+description: Workflow for creating new applications from scratch. Covers requirements gathering, tech stack selection, scaffolding, implementation, and delivery of a functional prototype.
+when_to_use: When the user asks to create a new application, project, website, game, mobile app, CLI tool, or library from scratch.
+---
+
+**Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype. Utilize all tools at your disposal to implement the application. Some tools you may especially find useful are 'write_file', 'edit' and 'run_shell_command'.
+
+1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions. Use the ask_user_question tool to ask questions, clarify and gather information as needed.
+2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. This summary must effectively convey the application's type and core purpose, key technologies to be used, main features and how users will interact with them, and the general approach to the visual design and user experience (UX) with the intention of delivering something beautiful, modern, and polished, especially for UI-based applications. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns, or open-source assets if feasible and licenses permit) to ensure a visually complete initial prototype. Ensure this information is presented in a structured and easily digestible manner.
+   - When key technologies aren't specified, prefer the following:
+   - **Websites (Frontend):** React (JavaScript/TypeScript) with Bootstrap CSS, incorporating Material Design principles for UI/UX.
+   - **Back-End APIs:** Node.js with Express.js (JavaScript/TypeScript) or Python with FastAPI.
+   - **Full-stack:** Next.js (React/Node.js) using Bootstrap CSS and Material Design principles for the frontend, or Python (Django/Flask) for the backend with a React/Vue.js frontend styled with Bootstrap CSS and Material Design principles.
+   - **CLIs:** Python or Go.
+   - **Mobile App:** Compose Multiplatform (Kotlin Multiplatform) or Flutter (Dart) using Material Design libraries and principles, when sharing code between Android and iOS. Jetpack Compose (Kotlin JVM) with Material Design principles or SwiftUI (Swift) for native apps targeted at either Android or iOS, respectively.
+   - **3D Games:** HTML/CSS/JavaScript with Three.js.
+   - **2D Games:** HTML/CSS/JavaScript.
+3. **User Approval:** Obtain user approval for the proposed plan.
+4. **Implementation:** Use the 'todo_write' tool to convert the approved plan into a structured todo list with specific, actionable tasks, then autonomously implement each task utilizing all available tools. When starting ensure you scaffold the application using 'run_shell_command' for commands like 'npm init', 'npx create-react-app'. Aim for full scope completion. Proactively create or source necessary placeholder assets (e.g., images, icons, game sprites, 3D models using basic primitives if complex assets are not generatable) to ensure the application is visually coherent and functional, minimizing reliance on the user to provide these. If the model can generate simple assets (e.g., a uniformly colored square sprite, a simple 3D cube), it should do so. Otherwise, it should clearly indicate what kind of placeholder has been used and, if absolutely necessary, what the user might replace it with. Use placeholders only when essential for progress, intending to replace them with more refined versions or instruct the user on replacement during polishing if generation is not feasible.
+5. **Verify:** Review work against the original request, the approved plan. Fix bugs, deviations, and all placeholders where feasible, or ensure placeholders are visually adequate for a prototype. Ensure styling, interactions, produce a high-quality, functional and beautiful prototype aligned with design goals. Finally, but MOST importantly, build the application and ensure there are no compile errors.
+6. **Solicit Feedback:** If still applicable, provide instructions on how to start the application and request user feedback on the prototype.

package/bundled/qc-helper/docs/configuration/settings.md

@@ -143,10 +143,12 @@ Settings are organized into categories. Most settings should be placed within th
 | -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
 | `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.maxWallTimeSeconds`                         | number  | Wall-clock budget for headless / unattended runs, in seconds. `-1` means unlimited. Overridable per-invocation via `--max-wall-time`, which requires a positive duration (`90`, `30s`, `5m`, `1h`, `1.5h`); the minimum is 1 second — sub-second values (`500ms`, `0.5`) are rejected as typos. Omit the flag to fall back to this setting. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                          | `-1`        |
+| `model.maxToolCalls`                               | number  | Cumulative tool-call budget for a run (counts every executed tool, success or failure; `structured_output` under `--json-schema` is exempt). `-1` means unlimited; `0` means "no tool calls allowed". Capped at 1,000,000 to catch typos. Overridable via `--max-tool-calls`. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                                                                                        | `-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.chatCompression.contextPercentageThreshold` | number  | **REMOVED.** Auto-compaction now uses a three-tier threshold ladder (warn / auto / hard) computed internally from the model's context window via the `computeThresholds()` function — no longer user-configurable. Setting this field in `settings.json` is silently ignored, and a one-line deprecation warning is emitted to stderr at startup. There is currently no replacement for "disable compression entirely" — reactive overflow recovery remains the safety net at the API layer if compression itself fails. (See PR #4345 / `docs/design/auto-compaction-threshold-redesign.md` for the redesign rationale.)                                                                                                                                    | `N/A`       |
 | `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.skipLoopDetection`                          | boolean | Disables streaming loop detection checks. Defaults to `true` (loop detection is skipped) to avoid false positives interrupting legitimate workflows. Set to `false` to re-enable streaming loop detection — useful as a guardrail in headless / non-interactive runs where stuck repetition can otherwise waste budget.                                                                                                                                                                                                                                                                                                                                                                                                                                      | `true`      |
 | `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` |
@@ -272,7 +274,8 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
 | Setting                          | Type    | Description                                                                       | Default |
 | -------------------------------- | ------- | --------------------------------------------------------------------------------- | ------- |
 | `memory.enableManagedAutoMemory` | boolean | Enable background extraction of memories from conversations.                      | `true`  |
-| `memory.enableManagedAutoDream`  | boolean | Enable automatic consolidation (deduplication and cleanup) of collected memories. | `false` |
+| `memory.enableManagedAutoDream`  | boolean | Enable automatic consolidation (deduplication and cleanup) of collected memories. | `true`  |
+| `memory.enableAutoSkill`         | boolean | Enable background review for reusable project skills after tool-heavy sessions.   | `true`  |
 
 See [Memory](../features/memory) for details on how auto-memory works and how to use the `/memory`, `/remember`, and `/dream` commands.
 
@@ -703,7 +706,9 @@ Qwen Code can execute potentially unsafe operations (like shell commands and fil
 
 - Using `--sandbox` or `-s` flag.
 - Setting `QWEN_SANDBOX` environment variable.
-- Sandbox is enabled when using `--yolo` or `--approval-mode=yolo` by default.
+- Setting `tools.sandbox` in settings.
+
+> ⚠️ **`--yolo` does _not_ automatically enable a sandbox.** YOLO mode only auto-approves tool calls; sandboxing must still be opted into via `--sandbox`, `QWEN_SANDBOX`, or `tools.sandbox`. In headless / non-interactive runs with `--yolo` (or `--approval-mode=yolo`) and no sandbox, the model can execute shell, write, and edit tools at the current process's privilege level — Qwen Code prints a warning to stderr in that case. Suppress with `QWEN_CODE_SUPPRESS_YOLO_WARNING=1` once you've reviewed the trade-off.
 
 By default, it uses a pre-built `qwen-code-sandbox` Docker image.
 

package/bundled/qc-helper/docs/features/_meta.ts

@@ -16,6 +16,7 @@ export default {
   },
   'approval-mode': 'Approval Mode',
   'auto-mode': 'Auto Mode',
+  worktree: 'Worktrees',
   mcp: 'MCP',
   lsp: 'LSP (Language Server Protocol)',
   'token-caching': 'Token Caching',

package/bundled/qc-helper/docs/features/headless.md

@@ -238,9 +238,41 @@ Key command-line options for headless usage:
 | `--approval-mode`            | Set approval mode                                                        | `qwen -p "query" --approval-mode auto_edit`                              |
 | `--continue`                 | Resume the most recent session for this project                          | `qwen --continue -p "Pick up where we left off"`                         |
 | `--resume [sessionId]`       | Resume a specific session (or choose interactively)                      | `qwen --resume 123e... -p "Finish the refactor"`                         |
+| `--max-session-turns`        | Cap the number of user/model/tool turns in the run                       | `qwen -p "..." --max-session-turns 30`                                   |
+| `--max-wall-time`            | Wall-clock budget; accepts `90` (s), `30s`, `5m`, `1h`, `1.5h`           | `qwen -p "..." --max-wall-time 10m`                                      |
+| `--max-tool-calls`           | Cumulative tool-call budget for the run                                  | `qwen -p "..." --max-tool-calls 50`                                      |
 
 For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../configuration/settings).
 
+## Safety in unattended runs
+
+Headless / CI runs combined with `--yolo` (or `--approval-mode=yolo`) auto-approve every tool call, including `shell`, `write`, and `edit`. **`--yolo` does not enable a sandbox** — those tools run at the host process's privilege level. When Qwen Code detects this combination with no sandbox configured, it prints a one-line warning to stderr at startup. Suppress the warning with `QWEN_CODE_SUPPRESS_YOLO_WARNING=1` once you've reviewed the trade-off.
+
+### Run-level budgets
+
+Qwen Code can abort an unattended run when it crosses one of the following thresholds. Each is `-1` (unlimited) by default; setting any one is enough to bound runaway behavior. They are enforced cooperatively against the same `AbortController` that already carries SIGINT, so a budget abort emits a structured `FatalBudgetExceededError` (exit code **55**) — distinct from the turn-cap exit code 53 and SIGINT's 130 so CI scripts can branch on the reason.
+
+| Flag                  | Settings key               | What it bounds                                                                                                                                                                                                |
+| --------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--max-wall-time`     | `model.maxWallTimeSeconds` | Wall-clock duration of the whole run. Flag accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` (fractional units supported). Minimum 1s — sub-second values are rejected as typos. Settings is seconds.               |
+| `--max-tool-calls`    | `model.maxToolCalls`       | Cumulative top-level tool calls dispatched by the main run loop (counts successes _and_ failures — the model still consumes tokens on errors). See "Scope" below for subagent / structured-output exemptions. |
+| `--max-session-turns` | `model.maxSessionTurns`    | Number of user/model/tool turns; pre-existing. Exits with code 53 on overrun (distinct from budget exit 55).                                                                                                  |
+
+#### Scope
+
+- **`--max-tool-calls` counts top-level dispatches only.** When the model calls the `agent` tool, the dispatch counts as **1**; inner tool calls performed by the spawned subagent are **not** counted. A model that funnels work through subagents can do unbounded inner work under a small top-level budget. Combine with `--exclude-tools agent` if you need a tighter cap.
+- **`structured_output` is exempt from `--max-tool-calls`.** Under `--json-schema`, the model's terminal `structured_output` call is the "I'm done" contract, not real work — it doesn't count against `--max-tool-calls` so a budget-edge completion isn't aborted as a false positive. The exemption is unconditional (including failed Ajv validations), so a model stuck in a malformed-output retry loop is NOT bounded by `--max-tool-calls`; combine with `--max-session-turns` or `--max-wall-time` to cap retries.
+- **`structured_output` is NOT exempt from `--max-session-turns`.** That counter is pre-existing and bumps for every turn including the terminal contract. Size `--max-session-turns` to `N+1` if you want to allow `N` real-work turns under `--json-schema`.
+- **Single-shot vs `--input-format stream-json`:** in stream-json input mode the daemon resets the budget counters at the start of every user message; the budget is per-message, not per-process.
+- **`qwen serve` / ACP sessions:** the daemon ACP session path does NOT currently consult `--max-wall-time` / `--max-tool-calls` from settings.json. These budgets only apply to single-shot `qwen -p` runs and to `--input-format stream-json` sessions. (`qwen serve` does emit the YOLO-no-sandbox warning at boot if `tools.approvalMode: 'yolo'` is set in settings.)
+
+### Recommended combinations
+
+- **Trusted, isolated environment (ephemeral CI runner, container):** `qwen -p "..." --yolo --max-session-turns N --max-wall-time 10m --output-format json`. Pin a turn budget and a wall-clock budget so a stuck agent can't burn through your CI minutes, and capture `--output-format json` for post-run usage / tool-call auditing.
+- **Local machine or shared infra:** also pass `--sandbox` (or set `QWEN_SANDBOX=1`) so shell / write / edit tools run inside the sandbox image.
+- **Long-running CI with retry-on-rate-limit:** combine `QWEN_CODE_UNATTENDED_RETRY=1` with `--max-wall-time`. The retry env keeps the run alive past transient 429 / 529 responses; the wall-clock budget ensures a persistently-failing provider can't extend the job indefinitely.
+- **Bounded auditing / exploration:** for read-only tasks, `--max-tool-calls 25` caps how aggressively the model can grep / read. Combine with `--exclude-tools shell,write,edit` to make the bound meaningful.
+
 ## Examples
 
 ### Code review

package/bundled/qc-helper/docs/features/memory.md

@@ -24,15 +24,32 @@ Don't include things Qwen can figure out by reading your code. QWEN.md works bes
 
 ### Where to create QWEN.md
 
-| File                          | Who it applies to                             |
-| ----------------------------- | --------------------------------------------- |
-| `~/.qwen/QWEN.md`             | You, across all your projects                 |
-| `QWEN.md` in the project root | Your whole team (commit it to source control) |
+| File                          | Who it applies to                                |
+| ----------------------------- | ------------------------------------------------ |
+| `~/.qwen/QWEN.md`             | You, across all your projects                    |
+| `QWEN.md` in the project root | Your whole team (commit it to source control)    |
+| `.qwen/QWEN.local.md`         | Only you, only in this project (keep out of git) |
 
-You can have both. Qwen loads all QWEN.md files it finds when you start a session — your personal one plus any in the project.
+You can have any combination of these. Qwen loads all of them when you start a session.
 
 If your repository already has an `AGENTS.md` file for other AI tools, Qwen reads that too. No need to duplicate instructions.
 
+#### When to use `.qwen/QWEN.local.md`
+
+Use it for **project-specific but personal** instructions — things that belong to this project but shouldn't be shared with the team:
+
+- Your own cluster ID, container registry namespace, or cloud account
+- A personal debug command that hardcodes your local environment
+- Notes you want Qwen to know about your work-in-progress, but not commit
+
+It loads **after** the shared project `QWEN.md`, so your local instructions can supplement or override the team's.
+
+**You must gitignore it yourself.** Although `.qwen/` is often treated as a local directory, qwen-code does not generate a `.gitignore` for you, and some projects commit `.qwen/settings.json`. Add this line to your `.gitignore` (or to your global git ignore):
+
+```
+.qwen/QWEN.local.md
+```
+
 ### Generate one automatically with `/init`
 
 Run `/init` and Qwen will analyze your codebase to create a starter QWEN.md with build commands, test instructions, and conventions it finds. If one already exists, it suggests additions instead of overwriting.

package/bundled/qc-helper/docs/features/worktree.md

@@ -0,0 +1,345 @@
+# Worktrees
+
+> Isolate experimental work in a temporary [git worktree](https://git-scm.com/docs/git-worktree) without leaving your current session. Useful when the model is about to make wide-ranging edits you want to keep separate from your main checkout, or when you want a subagent to work in a sandbox of its own.
+
+## Quick Start
+
+### Start the session inside a worktree (`--worktree` flag)
+
+If you know up front that the entire session should run inside a worktree, pass `--worktree` at launch:
+
+```bash
+# Auto-generated slug (e.g. tender-jemison-037f0a)
+qwen --worktree
+
+# Explicit name
+qwen --worktree my-feature
+
+# `=` form (recommended when also passing a positional prompt — see tip below)
+qwen --worktree=my-feature
+
+# PR reference — fetches refs/pull/<N>/head from `origin`
+qwen --worktree=#4174
+qwen --worktree https://github.com/QwenLM/qwen-code/pull/4174
+
+# Continue a previous --worktree session — re-attaches to the existing dir
+qwen --resume <session-id> --worktree=my-feature
+```
+
+> **Tip — bare `--worktree` followed by a positional prompt is ambiguous.** Because `--worktree` takes an optional value, `qwen --worktree "say hi"` makes yargs consume `"say hi"` as the slug (and reject it because of the space). Use one of:
+>
+> - `qwen --worktree=my-feature "say hi"` (always works — explicit slug via `=`)
+> - `qwen "say hi" --worktree` (positional first, flag at the end → auto slug)
+> - `qwen --worktree --approval-mode yolo "say hi"` (any flag between them anchors the bare form)
+
+> **Tip — `qwen --resume --worktree foo` (no session ID) shows an empty picker on first use.** The picker scopes to the chosen worktree's session storage; sessions started outside that worktree are not listed. To resume a session that was started inside `foo`, use `qwen --resume <id> --worktree foo` directly — the CLI re-attaches to the existing `foo/` directory rather than re-creating it.
+
+`process.cwd()` and the model's workspace are switched to the worktree before the first turn runs. Exit with `Ctrl+C` twice and the [Exit Dialog](#exit-dialog-ctrlc--ctrld) prompts to keep or remove the worktree.
+
+The `--worktree` flag cannot be combined with `--acp`/`--experimental-acp` — for ACP hosts (like Zed), pass the worktree path as the `cwd` of the `loadSession`/`newSession` request instead.
+
+### Or ask mid-session
+
+Alternatively, ask Qwen Code in plain language to create a worktree from inside an existing session:
+
+```text
+> start a worktree called experiment-a
+Worktree experiment-a created on branch worktree-experiment-a
+.qwen/worktrees/experiment-a
+```
+
+From this point on, the model routes every file edit and shell command through `.qwen/worktrees/experiment-a/`. Your original working directory is untouched.
+
+When you are done:
+
+```text
+> exit the worktree and remove it
+Removed worktree experiment-a (branch worktree-experiment-a)
+```
+
+If you want to come back later, ask to exit with the worktree kept on disk instead:
+
+```text
+> exit the worktree but keep it
+Kept worktree experiment-a at .qwen/worktrees/experiment-a
+```
+
+## When Worktrees Are Used
+
+Worktrees are activated in four independent paths:
+
+| Trigger                                         | What happens                                                                                                                   |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| You launch with `--worktree`                    | The CLI creates the worktree before any model turn runs and chdirs the session into it. PR forms (`#N`, full URL) fetch first. |
+| You explicitly ask for a worktree mid-session   | Model calls `enter_worktree`; subsequent file edits go inside it.                                                              |
+| You explicitly ask to leave                     | Model calls `exit_worktree` with `keep` or `remove`.                                                                           |
+| Model spawns a sub-agent with isolation enabled | A throwaway worktree (`agent-<hex>`) is created automatically and cleaned up if the agent has no diffs.                        |
+
+The two mid-session tools (`enter_worktree` / `exit_worktree`) are deliberately gated behind explicit phrasing — saying "fix this bug" or "create a branch" will **not** trigger them. You must say something like "use a worktree", "start a worktree", or "in a worktree". The `--worktree` CLI flag has no such guard; it always creates one when present.
+
+## What Gets Created
+
+Every Qwen-managed worktree is placed under your project's `.qwen` directory:
+
+```
+<repoRoot>/.qwen/worktrees/<slug>/         # Working directory
+                          ↳ branch worktree-<slug>   # Created off your current branch
+```
+
+- **Slug** — letters, digits, dot, underscore, hyphen; max 64 chars. If you don't specify a name, an `<adjective>-<noun>-<6hex>` slug is auto-generated (e.g. `tender-jemison-037f0a`). PR references produce `pr-<N>`.
+- **Branch** — always `worktree-<slug>`, branched from whichever branch you have checked out when you ask for the worktree (not necessarily the main working tree's `HEAD`). For PR worktrees the branch is `worktree-pr-<N>` and is based on `FETCH_HEAD` (the PR's tip on the GitHub side) rather than your local branch.
+- **Hooks** — the worktree's `core.hooksPath` is automatically pointed at the main repo's `.husky/` (preferred) or `.git/hooks/` so commits inside the worktree still trigger your existing pre-commit / commit-msg hooks.
+- **Optional symlinks** — directories listed in `worktree.symlinkDirectories` (see [Settings](#settings)) are symlinked from the main repo into the new worktree so heavy dirs like `node_modules` can be reused without reinstalling.
+
+The general-purpose worktree path is **not configurable** — it must live under `<repoRoot>/.qwen/worktrees/` so the CLI can find it on restart and on stale-cleanup sweeps. (The unrelated `agents.arena.worktreeBaseDir` setting controls only [Agent Arena](./arena.md) worktrees, which use a separate path tree under `~/.qwen/arena/`.)
+
+## Footer and Status Line
+
+When a worktree is active, the Footer shows a dim indicator on its own row:
+
+```
+⎇ worktree-experiment-a (experiment-a)
+```
+
+If you use a [custom status line script](./status-line.md), it also receives a `worktree` object in the JSON payload piped to stdin:
+
+```json
+{
+  "worktree": {
+    "name": "experiment-a",
+    "path": "/path/to/repo/.qwen/worktrees/experiment-a",
+    "branch": "worktree-experiment-a",
+    "original_cwd": "/path/to/repo",
+    "original_branch": "main"
+  }
+}
+```
+
+The payload field is present **only** when a worktree is active, so a `null`-check (`input.worktree?.name`) is enough.
+
+If your custom status line already renders worktree info, you can hide the built-in Footer row to avoid duplication — see [Settings](#settings) below.
+
+## Exit Dialog (Ctrl+C / Ctrl+D)
+
+Pressing the quit shortcut twice while a worktree is active opens the **Worktree Exit Dialog** instead of closing the CLI:
+
+```
+⎇ Active worktree: "experiment-a" (worktree-experiment-a)
+
+  • 2 new commit(s) on worktree-experiment-a
+  • 3 uncommitted file(s)
+  Removing the worktree will discard everything above.
+
+What would you like to do?
+  ○ Keep worktree (exit without deleting)
+  ○ Remove worktree and branch (discards 2 commit(s), 3 file(s))
+  ○ Cancel (stay in session)
+```
+
+The dialog inspects the worktree on open (`git status --porcelain` + `git rev-list <baseHEAD>..HEAD`) and surfaces both counts so you know exactly what you'd be discarding. `ESC` cancels.
+
+If `git status` itself fails (e.g. corrupt index, worktree directory was removed under the CLI), the dialog shows a `⚠ Could not measure worktree state` warning and the counts may be unreliable — choose **Keep** or **Cancel** until you've diagnosed the underlying repo problem.
+
+## `--resume` Restore
+
+The active worktree binding is persisted to a sidecar file alongside your session transcript:
+
+```
+<chatsDir>/<sessionId>.worktree.json
+```
+
+When you launch the CLI with `--resume <sessionId>` (or pick the session from `/resume`), three things happen consistently across **interactive TUI**, **headless `-p`**, and **ACP/Zed** modes:
+
+1. The sidecar is loaded and the worktree directory is verified to still exist on disk.
+2. If alive, the model receives a one-shot reminder on its very next prompt:
+   ```
+   [Resumed] Active worktree: "<slug>" at <path> (branch: <branch>). Continue using this path for all file operations.
+   ```
+3. If the worktree directory was deleted between sessions, the stale sidecar is cleaned up automatically — no error, the resume just continues without worktree context.
+
+Each mode chooses its own injection mechanism, but the user-visible behavior is identical:
+
+| Mode              | Mechanism                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------ |
+| Interactive (TUI) | `INFO` history item + system-reminder prefix on the next user prompt.                                  |
+| Headless (`-p`)   | `<system-reminder>` prefix on the prompt + `worktree_restored` JSON system event in the output stream. |
+| ACP (e.g. Zed)    | Pending notice attached to the next `prompt()` call.                                                   |
+
+The model is **not** automatically `chdir`'d into the worktree — the reminder is what keeps it routing edits through the worktree path.
+
+## Sub-Agent Isolation
+
+The `agent` tool accepts an optional `isolation: "worktree"` parameter. When set, Qwen Code creates an ephemeral worktree at `<repoRoot>/.qwen/worktrees/agent-<7hex>/` before the sub-agent starts, and:
+
+- **No changes** → the worktree is automatically removed when the agent finishes.
+- **Has changes** → the worktree is preserved; its path and branch are appended to the agent's result, e.g.
+  ```
+  …agent output…
+  [worktree preserved: /path/to/.qwen/worktrees/agent-3f2a1b9 (branch worktree-agent-3f2a1b9)]
+  ```
+  Review the diff and merge or delete it manually.
+
+Two constraints:
+
+- `isolation: "worktree"` requires a `subagent_type` — forked sub-agents (no `subagent_type`) reuse the parent's full conversation context, so isolating them would split intent from working tree.
+- Background agents (`run_in_background: true`) work fine with isolation; the cleanup runs when the agent reports completion.
+
+### Automatic Stale Cleanup
+
+Ephemeral agent worktrees that survived a crash or `--no-cleanup` shutdown are reaped on every CLI startup, with conservative fail-closed rules:
+
+| Guard                                  | Behavior                                       |
+| -------------------------------------- | ---------------------------------------------- |
+| Slug must match `agent-<7hex>` pattern | Named worktrees you created are never touched. |
+| Directory `mtime` > 30 days            | Newer entries are skipped.                     |
+| Any uncommitted tracked change         | Skip the entry (don't delete).                 |
+| Any commit not reachable from a remote | Skip the entry (don't delete).                 |
+| Any error reading git state            | Skip the entry (don't delete).                 |
+
+Named user worktrees (`enter_worktree` slugs) are **never** auto-cleaned — you keep them around until you ask to remove them.
+
+## Safety Guards on `exit_worktree action="remove"`
+
+Three independent guards trigger before the directory and branch are deleted:
+
+1. **Session ownership** — each worktree carries a sidecar marker with the session ID that created it. A different session trying to remove it is refused with a clear error pointing at `git worktree remove` for the manual escape hatch.
+2. **Dirty working tree** — uncommitted tracked or untracked changes block removal. Pass `discard_changes: true` to override. (Bypass requires explicit user confirmation — `action: "remove"` is never auto-approved in AUTO_EDIT mode.)
+3. **Unmerged commits** — commits on `worktree-<slug>` that no other local branch or remote ref points at block removal unconditionally; there is no "discard commits" flag because losing committed work is rarely what users mean. Merge, push, or rename the branch elsewhere first.
+
+The same three guards apply to the `WorktreeExitDialog → Remove` button.
+
+## Settings
+
+Two settings shape the general-purpose worktree experience:
+
+| Key                               | Type       | Default     | Effect                                                                                                                                                                                                                                                                     |
+| --------------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ui.hideBuiltinWorktreeIndicator` | boolean    | `false`     | Hides the built-in `⎇ worktree-… (…)` Footer row. The `worktree` field is still delivered to custom status line scripts. Set to `true` only if your status line already renders the worktree — otherwise you lose all UI affordance.                                       |
+| `worktree.symlinkDirectories`     | `string[]` | `undefined` | Directories under the main repo to symlink into every general-purpose worktree on creation. Paths are relative to the repo root; absolute paths and any entry containing `..` are rejected. Missing sources and existing destinations are silently skipped (no overwrite). |
+
+Example:
+
+```jsonc
+// ~/.qwen/settings.json or <repo>/.qwen/settings.json
+{
+  "worktree": {
+    "symlinkDirectories": ["node_modules", ".turbo", "dist"],
+  },
+}
+```
+
+Applies to ALL worktree-creation paths: `--worktree` flag, `enter_worktree` tool, and `agent isolation: "worktree"`.
+
+Settings unrelated to general worktrees but worth knowing about:
+
+- `agents.arena.worktreeBaseDir` — controls **Agent Arena** worktree placement (default `~/.qwen/arena`). Does not affect general-purpose worktrees, which always live under `<repoRoot>/.qwen/worktrees/`.
+
+There is no schema for `worktree.sparsePaths` yet — that's a roadmap item (see [Limitations](#limitations)).
+
+## Tool Reference
+
+### `enter_worktree`
+
+```json
+{ "name": "experiment-a" }
+```
+
+| Field  | Type   | Required | Notes                                                                                      |
+| ------ | ------ | -------- | ------------------------------------------------------------------------------------------ |
+| `name` | string | no       | Slug. Letters, digits, dot, underscore, hyphen; max 64 chars. Auto-generated when omitted. |
+
+Refuses to run when:
+
+- The CLI is not in a git repository.
+- The current working directory is already inside `.qwen/worktrees/` (no nested worktrees).
+
+### `exit_worktree`
+
+```json
+{ "name": "experiment-a", "action": "remove", "discard_changes": false }
+```
+
+| Field             | Type                   | Required                              | Notes                                                              |
+| ----------------- | ---------------------- | ------------------------------------- | ------------------------------------------------------------------ |
+| `name`            | string                 | yes                                   | Must match the slug used in `enter_worktree`.                      |
+| `action`          | `"keep"` \| `"remove"` | yes                                   | `keep` preserves dir + branch; `remove` deletes both.              |
+| `discard_changes` | boolean                | only when `action="remove"` and dirty | Overrides the dirty-tree guard. Has no effect for `action="keep"`. |
+
+`action: "remove"` always prompts for confirmation, including under `AUTO_EDIT` approval mode — it is treated as a destructive shell operation, not an info-only tool.
+
+### `agent` — `isolation` parameter
+
+```json
+{
+  "subagent_type": "my-agent",
+  "description": "…",
+  "prompt": "…",
+  "isolation": "worktree"
+}
+```
+
+| Field       | Type         | Required | Notes                                                                                             |
+| ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `isolation` | `"worktree"` | no       | Runs the agent in a fresh `agent-<7hex>` worktree. Requires `subagent_type` to be set (no forks). |
+
+See [Sub-Agents](./sub-agents.md) for the rest of the agent tool reference.
+
+## CLI Reference
+
+### `--worktree [name | #N | url]`
+
+```bash
+qwen --worktree                                               # auto-generate slug
+qwen --worktree my-feature                                    # explicit slug
+qwen --worktree=my-feature                                    # = form
+qwen --worktree=#123                                          # PR reference
+qwen --worktree https://github.com/owner/repo/pull/123        # PR URL
+```
+
+| Input                         | Result                                                                                                                |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Bare flag (no value)          | Auto slug `<adjective>-<noun>-<6hex>`, branch `worktree-<slug>`, base = current branch.                               |
+| Plain slug                    | Branch `worktree-<slug>`, base = current branch. Slug validation: letters/digits/dot/underscore/hyphen, max 64 chars. |
+| `#N` or `<github-url>/pull/N` | Slug `pr-<N>`, branch `worktree-pr-<N>`, base = `FETCH_HEAD` after `git fetch origin pull/<N>/head` (30s timeout).    |
+
+`--worktree` cannot be combined with `--acp` / `--experimental-acp`.
+
+When `--worktree` is combined with `--resume <session-id>`, the worktree wins: the resumed session's saved worktree (if any) is overridden and a stderr line + first-prompt reminder report the override.
+
+For interactive (TUI) and headless (`-p`) modes the worktree is automatically created and the session chdirs into it before the first turn.
+
+PR-fetch failure modes (exit code != 0, no worktree created):
+
+| Cause                         | Message excerpt                                            |
+| ----------------------------- | ---------------------------------------------------------- |
+| Missing `origin` remote       | `requires an "origin" remote that points at GitHub`        |
+| PR doesn't exist on origin    | `Failed to fetch PR #<N>: the PR does not exist on origin` |
+| 30s network timeout           | `Failed to fetch PR #<N>: timed out after 30s`             |
+| PR number out of range / zero | `Invalid PR number`                                        |
+
+## Limitations
+
+The following items are intentionally not implemented in the current phase:
+
+- **No sparse checkout.** Large monorepos check out the full tree. (`worktree.sparsePaths` is a roadmap item.)
+- **No tmux integration.** The CLI does not spawn worktree sessions in new tmux windows.
+- **Worktrees are separate "projects" for session storage.** Sessions started with `--worktree foo` are saved under that worktree's chats dir; to resume them later you must pass `--worktree foo` again. Sessions started without `--worktree` are saved under the main checkout and won't appear in the worktree's resume picker.
+- **No cross-slug session override.** `qwen --resume <sid> --worktree second` where `<sid>` was created with `--worktree first` will fail to find the session — sessions and worktrees are tightly bound by `projectHash(cwd)`. To switch worktrees on an existing session you must exit, then re-launch with the new `--worktree` and a fresh prompt. A future architectural change (anchoring storage at the repo root instead of `cwd`) would lift this constraint.
+- **Mid-session `enter_worktree` does NOT switch `process.cwd()` or `Config.targetDir`.** That tool uses the model-context-only convention (see [Sub-Agents](./sub-agents.md)). Only the startup `--worktree` flag actually switches the process working directory.
+- **Relative paths in other arg fields are resolved BEFORE the worktree chdir.** Path-taking flags (`--mcp-config`, `--openai-logging-dir`, `--json-file`, `--input-file`, `--telemetry-outfile`, `--include-directories`) are normalized to absolute paths against the launch cwd when `--worktree` is set. Other path-shaped argv fields not in this list still resolve against the worktree cwd — use absolute paths to be safe.
+
+Track the roadmap in `docs/design/worktree.md`.
+
+## Troubleshooting
+
+**The Footer shows no worktree indicator even though I just created one.**
+Check that `ui.hideBuiltinWorktreeIndicator` is not set to `true`. Also confirm the slug is non-empty in the tool's success message.
+
+**`--resume` does not restore my worktree.**
+Check `<chatsDir>/<sessionId>.worktree.json` exists. The CLI deletes the sidecar automatically when the worktree directory is gone, so a missing sidecar plus a missing directory is the normal "no worktree to restore" state — not a bug. Run with `--debug` and grep for `restoreWorktreeContext` to see the reason.
+
+**`exit_worktree` says "created by a different session".**
+This is the session-ownership guard. Resume the original session and exit from there, or run the suggested `git worktree remove …` command manually.
+
+**Stale `agent-<hex>` worktrees keep piling up.**
+The 30-day cutoff is conservative; sweep manually with `git worktree list && git worktree remove <path>`, or wait — the next CLI startup after the 30-day mark will reap them as long as they are clean and pushed.

package/chunks/{agent-2JCG7FDJ.js → agent-RY5EB3XR.js}

@@ -7,30 +7,30 @@ import {
   hasRebuiltToolRegistry,
   rebuildToolRegistryOnOverride,
   resolveSubagentApprovalMode
-} from "./chunk-BAZDG3QU.js";
+} from "./chunk-7HM6OB7M.js";
 import "./chunk-K5PGHDBN.js";
 import "./chunk-O4PICXES.js";
 import "./chunk-TW522KN6.js";
 import "./chunk-MLZQVCF3.js";
-import "./chunk-CAVZVZX6.js";
-import "./chunk-G7YTSRES.js";
-import "./chunk-4AOCVI6J.js";
+import "./chunk-C27V5A2J.js";
+import "./chunk-EY6BDW7Y.js";
+import "./chunk-K72FHBFO.js";
 import "./chunk-77WXWU44.js";
-import "./chunk-F23NCRJ2.js";
-import "./chunk-CSWBPY3P.js";
-import "./chunk-JCR2WRXZ.js";
+import "./chunk-GVWPJCXU.js";
+import "./chunk-JVD46YJV.js";
+import "./chunk-4YNZFYJY.js";
 import "./chunk-UWCTAVOD.js";
 import "./chunk-OFEVLU4C.js";
-import "./chunk-PR4T27R7.js";
-import "./chunk-MAY32HXD.js";
-import "./chunk-D5NTAHYL.js";
+import "./chunk-NQ3E7YLD.js";
+import "./chunk-6NUSWV4M.js";
+import "./chunk-ODPVJ6JJ.js";
 import "./chunk-T4VD6OJ4.js";
 import "./chunk-RDYWTWEM.js";
-import "./chunk-YJLGXDQJ.js";
-import "./chunk-PVVL5Q3W.js";
-import "./chunk-GGNTZ2NH.js";
-import "./chunk-KXZ4TJB4.js";
-import "./chunk-XP27SJMH.js";
+import "./chunk-FO7BIVSR.js";
+import "./chunk-YMDXEEOW.js";
+import "./chunk-7YJIR2FX.js";
+import "./chunk-OIL7KDWV.js";
+import "./chunk-ACBGEKB7.js";
 import "./chunk-E7E2MFYM.js";
 import "./chunk-ZERZSAZL.js";
 import "./chunk-QN5NZ3UQ.js";

package/chunks/{anthropicContentGenerator-RQJNXJIY.js → anthropicContentGenerator-LYI3OHBB.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-KQIKOTQJ.js";
 import {
   RequestTokenizer
-} from "./chunk-DMIMF3CG.js";
+} from "./chunk-VMOWXTRC.js";
 import {
   Blob,
   File,
@@ -16,7 +16,7 @@ import {
 import {
   buildRuntimeFetchOptions,
   redactProxyError
-} from "./chunk-CSWBPY3P.js";
+} from "./chunk-JVD46YJV.js";
 import {
   CAPPED_DEFAULT_MAX_TOKENS,
   DEFAULT_TIMEOUT,
@@ -25,7 +25,7 @@ import {
   runtimeDiagnostics,
   safeJsonParse,
   tokenLimit
-} from "./chunk-MAY32HXD.js";
+} from "./chunk-6NUSWV4M.js";
 import {
   FinishReason,
   GenerateContentResponse
@@ -33,7 +33,7 @@ import {
 import "./chunk-RDYWTWEM.js";
 import {
   createDebugLogger
-} from "./chunk-XP27SJMH.js";
+} from "./chunk-ACBGEKB7.js";
 import "./chunk-E7E2MFYM.js";
 import {
   require_ms

package/chunks/{askUserQuestion-PQPMPNM3.js → askUserQuestion-R3MKD2JT.js}

@@ -6,10 +6,10 @@ import {
   BaseToolInvocation,
   ToolDisplayNames,
   ToolNames
-} from "./chunk-PVVL5Q3W.js";
+} from "./chunk-YMDXEEOW.js";
 import {
   createDebugLogger
-} from "./chunk-XP27SJMH.js";
+} from "./chunk-ACBGEKB7.js";
 import "./chunk-QWSRH265.js";
 import {
   init_esbuild_shims