@qwen-code/qwen-code 0.19.8 → 0.19.9-nightly.20260714.9dd8389eb

package/bundled/qc-helper/docs/features/code-review.md

@@ -17,48 +17,105 @@
 
 # Review a specific file
 /review src/utils/auth.ts
+
+# Quick unverified pass (no subagents)
+/review --effort low
+/review 123 --effort medium
 ```
 
 If there are no uncommitted changes, `/review` will let you know and stop — no agents are launched.
 
+## Effort Levels
+
+`--effort low|medium|high` trades depth for speed:
+
+| Level    | What runs                                                                                                                                                                 | Findings cap        | Verdict                             | Posts to PR      |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------- | ---------------- |
+| `low`    | One inline pass over the diff — no subagents, no build/test, no project rules                                                                                             | 8 (unverified)      | None                                | Never            |
+| `medium` | Finder angles run sequentially in one context: line-by-line, removed-behavior, cross-file trace (same-repo only), quality/altitude, performance, project-rule conventions | 12 (unverified)     | None                                | Never            |
+| `high`   | Full pipeline: 12 parallel agents → sharded verification → iterative reverse audit                                                                                        | Uncapped (verified) | Approve / Request changes / Comment | With `--comment` |
+
+Defaults: **high** for PR reviews, **medium** for local and file reviews. An effective `--comment` forces high (posted comments must survive verification) — on a non-PR target `--comment` is ignored with a warning and does **not** change the effort. Medium runs no dedicated security or test-coverage pass — use `--effort high` for security-sensitive changes. Worktree isolation applies to same-repo PR reviews; cross-repo PRs run in lightweight mode (diff-only, no worktree or build/test). Quick passes are labeled unverified, never emit a verdict, and never write the incremental review cache, so a later `--effort high` run is never skipped as "already reviewed". The diff-obtaining mechanics are identical at every level — PR reviews always use the isolated worktree and the same base resolution, so the review is never against the wrong base. One scope difference remains: the incremental cache is high-only, so a high re-review may cover just the new commits (`lastCommitSha..HEAD`) while low/medium always review the full PR diff.
+
 ## How It Works
 
 The `/review` command runs a multi-stage pipeline:
 
 ```
-Step 1:  Determine scope (local diff / PR worktree / file)
-Step 2:  Load project review rules
-Step 3:  10 parallel review agents                         [10 LLM calls]
+Step 1:  Determine scope + effort level (local diff / PR worktree / file)
+         Capture the diff to a file + partition it into chunks
+Step 2:  Load project review rules (medium/high)
+Step 3C: low/medium effort: inline pass, no subagents  [0 subagent calls]
+Step 3A: high, <=500 src AND <=3200 total: 12 agents       [12+ LLM calls]
            |-- Agent 0: Issue Fidelity & Root-Cause Ownership
-           |-- Agent 1: Correctness
+           |-- Agent 1a: Correctness — line-by-line scan
+           |     (incl. language-pitfall + wrapper-routing checks)
+           |-- Agent 1b: Correctness — removed-behavior audit
+           |-- Agent 1c: Correctness — cross-file tracer
            |-- Agent 2: Security
-           |-- Agent 3: Code Quality
+           |-- Agent 3: Code Quality (incl. altitude)
            |-- Agent 4: Performance & Efficiency
            |-- Agent 5: Test Coverage
            |-- Agent 6: Undirected Audit (3 personas: 6a/6b/6c)
+           |-- Agent 8: Diff-specialized finders (0-2, only when
+           |     the diff's domain calls for them)
            '-- Agent 7: Build & Test (runs shell commands)
-Step 4:  Deduplicate --> Batch verify --> Aggregate         [1 LLM call]
-Step 5:  Iterative reverse audit (1-3 rounds, gap finding) [1-3 LLM calls]
-Step 6:  Present findings + verdict
-Step 7:  Submit PR review (inline comments, if requested)
-Step 8:  Save report + incremental cache
+Step 3B: high, >500 src OR >3200 total: territory x dim.   [N+5..7+3H calls]
+           (N chunks, 5-7 whole-diff agents, 3 invariant
+            agents per heavy file H)
+           |-- 1 chunk agent per ~400 diff lines (all dimensions,
+           |     its territory only, returns a coverage receipt)
+           |-- 3 invariant agents per heavily-rewritten source
+           |     file (whole file; state/timers, counters/
+           |      returns/errors, config/early-returns)
+           |-- Agent 0: Issue Fidelity      (whole diff)
+           |-- Agent 7: Build & Test        (whole repo)
+           |-- Agent 1b: Removed-behavior   (whole diff — the
+           |     cross-chunk half; chunks keep the local half)
+           |-- Agent 1c: Cross-file tracer  (whole diff)
+           |-- Agent 8: Specialized finders (whole diff, 0-2)
+           '-- Test coverage matrix         (whole diff)
+Step 4:  Deduplicate --> Sharded verify (<=8 findings each)
+           --> Aggregate                    [ceil(F/8) calls, F=findings]
+Step 5:  Iterative reverse audit, fanned out per chunk;
+           stop after 2 consecutive dry rounds (cap 5)
+Step 6:  Present findings + verdict (high; quick passes: findings only)
+Step 7:  Submit PR review (inline comments, if requested; high only)
+Step 8:  Save report + incremental cache (cache: high only)
 Step 9:  Clean up (remove worktree + temp files)
 ```
 
+Steps 3A/3B/4/5 are the high-effort pipeline; at `--effort low|medium` a single inline pass (Step 3C) replaces them.
+
 ### Review Agents
 
-| Agent                             | Focus                                                                                       |
-| --------------------------------- | ------------------------------------------------------------------------------------------- |
-| Agent 0: Issue Fidelity           | Linked issue evidence, root-cause ownership, and whether the PR solves the reported problem |
-| Agent 1: Correctness              | Logic errors, edge cases, null handling, race conditions, type safety                       |
-| Agent 2: Security                 | Injection, XSS, SSRF, auth bypass, sensitive data exposure                                  |
-| Agent 3: Code Quality             | Style consistency, naming, duplication, dead code                                           |
-| Agent 4: Performance & Efficiency | N+1 queries, memory leaks, unnecessary re-renders, bundle size                              |
-| Agent 5: Test Coverage            | Untested code paths in the diff, missing branch coverage, weak assertions                   |
-| Agent 6: Undirected Audit         | 3 parallel personas (attacker / 3am-oncall / maintainer) — catches cross-dimensional issues |
-| Agent 7: Build & Test             | Runs build and test commands, reports failures                                              |
+| Agent                             | Focus                                                                                                                                                                                                                                                                                           |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Agent 0: Issue Fidelity           | Linked issue evidence, root-cause ownership, and whether the PR solves the reported problem                                                                                                                                                                                                     |
+| Agent 1a: Line-by-line scan       | Walks every hunk plus its enclosing function: wrong conditions, off-by-one, missing `await`, language-specific pitfalls, wrapper/proxy routing                                                                                                                                                  |
+| Agent 1b: Removed-behavior audit  | Walks every deleted/replaced line: names the invariant it enforced and hunts for where the new code re-establishes it — including removed **exports**, whose replacement often lives in another file and quietly changed a default. In 3B it runs whole-diff (chunk agents keep the local half) |
+| Agent 1c: Cross-file tracer       | Walks every changed symbol's callers (consumer direction) and every added field's read sites (producer direction), plus same-PR callee changes                                                                                                                                                  |
+| Agent 2: Security                 | Injection, XSS, SSRF, auth bypass, sensitive data exposure                                                                                                                                                                                                                                      |
+| Agent 3: Code Quality             | Style consistency, naming, duplication/reuse, altitude (fix at the right depth, not a bandaid on shared infrastructure), dead code                                                                                                                                                              |
+| Agent 4: Performance & Efficiency | N+1 queries, memory leaks, unnecessary re-renders, bundle size                                                                                                                                                                                                                                  |
+| Agent 5: Test Coverage            | Untested code paths in the diff, missing branch coverage, weak assertions                                                                                                                                                                                                                       |
+| Agent 6: Undirected Audit         | 3 parallel personas (attacker / 3am-oncall / maintainer) — catches cross-dimensional issues                                                                                                                                                                                                     |
+| Agent 7: Build & Test             | Runs build and test commands, reports failures                                                                                                                                                                                                                                                  |
+| Agent 8: Diff-specialized finders | 0-2 extra finders written per-review when the diff concentrates in a domain with known failure modes (reconnect logic, module loaders, schedulers, codecs)                                                                                                                                      |
+
+The three Correctness agents are **procedural**: each is defined by how it walks the diff (line-by-line / deleted lines / cross-file edges), not by a bug taxonomy — so their coverage is complementary instead of overlapping. All agents run in parallel (Agent 1 launches 3 procedural variants and Agent 6 launches 3 persona variants concurrently, totaling 12 parallel tasks for same-repo PR reviews, plus 0-2 Agent 8 finders when the diff's domain calls for them — so 12-14 in practice; Agent 0 is skipped for local-diff and file-path reviews, which run 11-13; cross-repo lightweight mode also skips Agents 1c and 7, running 10-12).
+
+Every finding must state a **failure scenario** — the concrete input, state, or timing that triggers it and the wrong outcome that results (for quality findings, the concrete cost instead). A finding that cannot name its scenario is dropped at the source, and verification re-traces the claimed scenario through the real code rather than judging the finding's prose.
 
-All agents run in parallel (Agent 6 launches 3 persona variants concurrently, totaling 10 parallel tasks for same-repo PR reviews; Agent 0 is skipped for local-diff and file-path reviews, which run 9). Findings from Agents 0-6 are verified in a **single batch verification pass** (one agent reviews all findings at once, keeping verification cost fixed regardless of finding count). After verification, **iterative reverse audit** runs 1-3 rounds of gap-finding — each round receives the cumulative finding list from prior rounds, so successive rounds focus on whatever's left undiscovered. The loop stops as soon as a round returns "No issues found", or after 3 rounds (hard cap). Reverse audit findings skip verification (the agent already has full context) and are included as high-confidence results.
+Once a PR carries more than 500 lines of **source** change — or more than 3 200 diff lines in total, past which the eleven whole-diff readers are each too diluted to read carefully (an attention bound, not a promise of fewer calls — heavy files and specialized finders can make 3B cost more) — this dimension fan-out is replaced by a **territory × dimension** fan-out: the diff is split into ~400-line chunks — boundaries fall on hunk boundaries, and a hunk too large to fit is split only at a top-level declaration, never inside a function — and each chunk gets its own agent that applies every review dimension to that chunk alone.
+
+The gate deliberately counts source lines rather than diff lines. Test code, prose and lockfiles dominate diff size — across this repo's last 40 merged PRs the median diff is 41% tests — so a gate on raw size would carve a 173-line production change into territories just because it shipped 489 lines of new tests, leaving that production code with one reviewer instead of ten lenses (the diff-reading dimension agents — twelve minus Issue Fidelity and Build & Test). Chunking still covers every line either way, tests included; what the gate decides is how many reviewers there are and what each is asked to do. Ten diff-reading lenses all walking one large diff read the same early hunks ten times over; one agent per chunk means every line of the diff has exactly one accountable reviewer. Each chunk agent returns a `Covered:` receipt, and a chunk with no receipt is re-reviewed before the run proceeds — so "no blockers" can never be reported over code that nobody read.
+
+A **source** file that is largely rewritten (an existing file of 300+ lines that is now 40%+ new, or has 800+ changed lines) also gets **three whole-file invariant agents**. Test and generated files never qualify — the checklist asks about fields, timers, and error taxonomies, which a rewritten test file does not have. Its bugs are usually not inside any one hunk but _between_ the new lines — a timer armed near the top of the file and a teardown path two thousand lines below. Each agent reads the whole post-change file and walks two or three items of a fixed checklist: mutable fields cleared on every exit path, timers cancelled on every close (and cancellation not discarding captured data), map inserts matched by deletes, retry counters incremented at every entry, status return values actually checked, error codes exhaustively classified permanent vs transient, config fields honoured on every path, and early returns that skip a required side effect.
+
+The checklist is split three ways on purpose. Handing one agent all eight checks over a 2 400-line file gets one of them done properly; three agents with two or three checks each get all of them done. Chunk agents do not substitute for this — on PR #6457 they held every one of these defects inside their assigned territory and reported none. What they lacked was not the lines but the question.
+
+Findings are verified in **sharded batches** (at most 8 findings per verification agent, all launched together). A verifier may reject a Critical only by quoting the code that contradicts it (or when the diff's own comments document the flagged behavior as deliberate); anything less certain is downgraded to low confidence rather than deleted — a silently rejected Critical is invisible to every later stage, while a downgraded one still reaches a human. After verification, **iterative reverse audit** hunts for gaps, fanned out one auditor per chunk per round, each with the cumulative finding list. The loop stops after **two consecutive dry rounds** (or 5 rounds, hard cap — reported as such rather than as convergence). One dry round is not evidence of convergence, and reverse-audit findings are verified like any other.
 
 ## Severity Levels
 
@@ -92,13 +149,14 @@ You can review PRs from other repositories by passing the full URL:
 
 This runs in **lightweight mode** — no worktree, no build/test. The review is based on the diff text only (fetched via GitHub API). PR comments can still be posted if you have write access.
 
-| Capability                                                 | Same-repo | Cross-repo                    |
-| ---------------------------------------------------------- | --------- | ----------------------------- |
-| LLM review (Agents 0-6 + verify + iterative reverse audit) | ✅        | ✅                            |
-| Agent 7: Build & test                                      | ✅        | ❌ (no local codebase)        |
-| Cross-file impact analysis                                 | ✅        | ❌                            |
-| PR inline comments                                         | ✅        | ✅ (if you have write access) |
-| Incremental review cache                                   | ✅        | ❌                            |
+| Capability                                                            | Same-repo | Cross-repo                     |
+| --------------------------------------------------------------------- | --------- | ------------------------------ |
+| LLM review (Agents 0, 1a, 1b, 2-6 + verify + iterative reverse audit) | ✅        | ✅                             |
+| Agent 1c: Cross-file tracer                                           | ✅        | ❌ (no local codebase to grep) |
+| Agent 7: Build & test                                                 | ✅        | ❌ (no local codebase)         |
+| Agent 8: Diff-specialized finders (0-2, when the domain calls for it) | ✅        | ✅ (needs only the diff)       |
+| PR inline comments                                                    | ✅        | ✅ (if you have write access)  |
+| Incremental review cache                                              | ✅        | ❌                             |
 
 ## PR Inline Comments
 
@@ -112,7 +170,8 @@ Or, after running `/review 123`, type `post comments` to publish findings withou
 
 **What gets posted:**
 
-- High-confidence Critical and Suggestion findings as inline comments on specific lines
+- High-confidence Critical and Suggestion findings as inline comments on specific lines, each prefixed with `**[Critical]**` or `**[Suggestion]**` so blockers are distinguishable from recommendations
+- Where the fix is a single localized edit, a ` ```suggestion ` block you can apply in one click
 - For Approve/Request changes verdicts: a review summary with the verdict
 - For Comment verdict with all inline comments posted: no separate summary (inline comments are sufficient)
 - Model attribution footer on each comment (e.g., _— qwen3-coder via Qwen Code /review_)
@@ -199,7 +258,7 @@ If you switch models (via `/model`) and re-review the same PR, `/review` detects
 # → "Previous review used qwen3-coder. Running full review with gpt-4o for a second opinion."
 ```
 
-Cache is stored in `.qwen/review-cache/` and tracks both the commit SHA and model ID. Make sure this directory is in your `.gitignore` (a broader rule like `.qwen/*` also works). If the cached commit was rebased away, it falls back to a full review.
+Cache is stored in `.qwen/review-cache/` and tracks both the commit SHA and model ID. Make sure this directory is in your `.gitignore` (a broader rule like `.qwen/*` also works). If the cached commit was rebased away, it falls back to a full review. Only high-effort reviews consult or write the cache — a `--effort low|medium` quick pass never counts as "already reviewed".
 
 ## Review Reports
 
@@ -212,29 +271,37 @@ For same-repo reviews, results are saved as a Markdown file in your project's `.
 
 Reports include: timestamp, diff stats, build/test results, all findings with verification status, and the verdict.
 
+The deterministic halves of the pipeline — argument parsing (`qwen review parse-args`) and the event/body decision (`qwen review compose-review`) — are tested subcommands rather than prompt text, so `--effort` grammar, `--comment` forcing, verdict caps, and downgrade behavior are pinned by unit tests and cannot drift with the model.
+
+**GitHub Enterprise:** reviewing a PR URL on a non-`github.com` host routes every GitHub call at that host — the review subcommands (`fetch-pr`, `pr-context`, `presubmit`) accept `--host` and set it in code, so a forgotten host cannot silently retarget the review at `github.com`.
+
+Every run ends with one machine-readable line (`Review complete: <target> — <disposition>`), so scripts and CI wrappers can detect completion and outcome with a single `^Review complete: ` match.
+
 ## Cross-file Impact Analysis
 
-When code changes modify exported functions, classes, or interfaces, the review agents automatically search for all callers and check compatibility:
+A dedicated cross-file tracer (Agent 1c) owns this walk end-to-end. When code changes modify exported functions, classes, or interfaces, it searches for all callers and checks compatibility:
 
 - Parameter count/type changes
 - Return type changes
 - Removed or renamed public methods
 - Breaking API changes
 
-For large diffs (>10 modified symbols), analysis prioritizes functions with signature changes.
+It also walks the **producer direction**: every field, option, or optional parameter the diff adds is traced to its read sites — including files the diff never touches. A live code path reading a field that nothing populates means the feature it gates silently does nothing, and that is flagged as Critical at the read site.
+
+For large diffs (>10 modified symbols), the caller-direction analysis prioritizes functions with signature changes; the producer direction is never budget-limited, because an unchanged signature is exactly its point.
 
 ## Token Efficiency
 
-The review pipeline uses a bounded number of LLM calls regardless of how many findings are produced:
+The high-effort pipeline bounds each stage (shard size, audit rounds), but total calls scale with findings — `ceil(F/8)` verification shards — and, under 3B, with chunk count (reverse audit runs per chunk per round). Typical 3A profile:
 
-| Stage                            | LLM calls         | Notes                                               |
-| -------------------------------- | ----------------- | --------------------------------------------------- |
-| Review agents (Step 3)           | 10 (or 9)         | Run in parallel; Agent 7 skipped in cross-repo mode |
-| Batch verification (Step 4)      | 1                 | Single agent verifies all findings at once          |
-| Iterative reverse audit (Step 5) | 1-3               | Loops until "No issues found" or 3-round cap        |
-| **Total**                        | **12-14 (11-13)** | Same-repo: 12-14; cross-repo: 11-13 (no Agent 7)    |
+| Stage                            | LLM calls                      | Notes                                                                                                          |
+| -------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| Review agents (Step 3)           | 12 (+0-2)                      | Run in parallel; cross-repo skips Agents 1c and 7 (10), local/file skips Agent 0 (11)                          |
+| Sharded verification (Step 4)    | ceil(F/8)                      | F = findings; at most 8 per verification agent, launched together                                              |
+| Iterative reverse audit (Step 5) | 2-5 (3A); rounds × chunks (3B) | Two consecutive dry rounds to stop (cap 5); 3B fans out one auditor per chunk per round                        |
+| **Total**                        | **~15-21 (~13-20)**            | 3A same-repo: ~15-21 (typical ~15-17); cross-repo or local/file: ~13-20; 3B scales with chunks (see DESIGN.md) |
 
-Most PRs converge to the lower end of the range (1 reverse audit round); the cap prevents runaway cost on pathological cases.
+Most PRs converge to the lower end of the range; the caps prevent runaway cost on pathological cases. At `--effort low|medium` the review runs entirely inline — **0 subagent calls**.
 
 ## What's NOT Flagged
 
@@ -252,6 +319,7 @@ The review intentionally excludes:
 > **Silence is better than noise.** Every comment should be worth the reader's time.
 
 - If unsure whether something is a problem → don't report it
+- Every finding names a concrete failure scenario (trigger → wrong outcome) or a concrete cost — a finding that can't is dropped before it reaches you
 - Same pattern across N files → aggregated into one finding
-- PR comments are high-confidence only
+- PR comments are high-confidence only (and only from high-effort, verified reviews)
 - Cosmetic style/formatting matching codebase conventions is excluded

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

@@ -76,42 +76,43 @@ Commands specifically for controlling interface and output language.
 
 Commands for managing AI tools and models.
 
-| Command           | Description                                                                      | Usage Examples                                                                                            |
-| ----------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `/mcp`            | List configured MCP servers and tools                                            | `/mcp`, `/mcp desc`, `/mcp nodesc`, `/mcp schema`                                                         |
-| `/import-config`  | Import MCP servers from Claude configs                                           | `/import-config all`, `/import-config claude-code`, `/import-config claude-desktop --scope user\|project` |
-| `/tools`          | Display currently available tool list                                            | `/tools`, `/tools desc`                                                                                   |
-| `/skills`         | Open the Skills panel to browse, search, toggle, and launch skills               | `/skills`, `/<skill-name>`                                                                                |
-| `/plan`           | Switch to plan mode or exit plan mode                                            | `/plan`, `/plan <task>`, `/plan exit`                                                                     |
-| `/approval-mode`  | Change the tool-approval mode (current session only)                             | `/approval-mode`, `/approval-mode auto-edit`                                                              |
-| → `plan`          | Analysis only, no execution (secure review)                                      | `/approval-mode plan`                                                                                     |
-| → `default`       | Require approval for edits (daily use)                                           | `/approval-mode default`                                                                                  |
-| → `auto-edit`     | Auto-approve edits (trusted environment)                                         | `/approval-mode auto-edit`                                                                                |
-| → `auto`          | Classifier-evaluated approval (autonomous)                                       | `/approval-mode auto`                                                                                     |
-| → `yolo`          | Auto-approve everything (quick prototyping)                                      | `/approval-mode yolo`                                                                                     |
-| `/model`          | Switch model used in current session                                             | `/model`, `/model <model-id>` (switch immediately)                                                        |
-| `/model --fast`   | Set a lighter model for prompt suggestions                                       | `/model --fast qwen3-coder-flash`                                                                         |
-| `/model --voice`  | Set the model used for voice transcription                                       | `/model --voice <model-id>`                                                                               |
-| `/model --vision` | Set the vision-bridge model used to transcribe images for a text-only main model | `/model --vision <model-id>`                                                                              |
-| `/effort`         | Set reasoning effort for thinking-capable models                                 | `/effort` (opens picker), `/effort high` (low/medium/high/xhigh/max; mapped & clamped per provider)       |
-| `/extensions`     | Manage extensions                                                                | `/extensions list`, `/extensions manage`                                                                  |
-| → `list`          | List installed extensions                                                        | `/extensions list`                                                                                        |
-| → `manage`        | Manage installed extensions (interactive)                                        | `/extensions manage`                                                                                      |
-| → `explore`       | Open extensions page in browser                                                  | `/extensions explore <Gemini\|ClaudeCode>`                                                                |
-| → `install`       | Install an extension from a git repo or path                                     | `/extensions install <repo-or-path>`                                                                      |
-| `/memory`         | Open the Memory Manager dialog                                                   | `/memory`                                                                                                 |
-| `/remember`       | Save a durable memory                                                            | `/remember Prefer terse responses`                                                                        |
-| `/forget`         | Remove matching entries from auto-memory                                         | `/forget <query>`                                                                                         |
-| `/dream`          | Manually run auto-memory consolidation                                           | `/dream`                                                                                                  |
-| `/hooks`          | Manage Qwen Code hooks                                                           | `/hooks`, `/hooks list`                                                                                   |
-| `/permissions`    | Manage permission rules                                                          | `/permissions`                                                                                            |
-| `/agents`         | Manage subagents                                                                 | `/agents manage`, `/agents create`                                                                        |
-| `/arena`          | Manage Arena sessions                                                            | `/arena start`, `/arena stop`, `/arena status`, `/arena select` (alias `choose`)                          |
-| `/goal`           | Set a goal — keep working until condition met                                    | `/goal <condition>`, `/goal clear`                                                                        |
-| `/tasks`          | List background tasks                                                            | `/tasks`                                                                                                  |
-| `/workflows`      | Inspect workflow runs                                                            | `/workflows`, `/workflows <runId>`                                                                        |
-| `/lsp`            | Show LSP server status                                                           | `/lsp`                                                                                                    |
-| `/trust`          | Manage folder trust settings                                                     | `/trust`                                                                                                  |
+| Command           | Description                                                                           | Usage Examples                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `/mcp`            | List configured MCP servers and tools                                                 | `/mcp`, `/mcp desc`, `/mcp nodesc`, `/mcp schema`                                                         |
+| `/import-config`  | Import MCP servers from Claude configs                                                | `/import-config all`, `/import-config claude-code`, `/import-config claude-desktop --scope user\|project` |
+| `/tools`          | Display currently available tool list                                                 | `/tools`, `/tools desc`                                                                                   |
+| `/skills`         | Open the Skills panel to browse, search, toggle, and launch skills                    | `/skills`, `/<skill-name>`                                                                                |
+| `/plan`           | Switch to plan mode or exit plan mode                                                 | `/plan`, `/plan <task>`, `/plan exit`                                                                     |
+| `/approval-mode`  | Change the tool-approval mode (current session only)                                  | `/approval-mode`, `/approval-mode auto-edit`                                                              |
+| → `plan`          | Analysis only, no execution (secure review)                                           | `/approval-mode plan`                                                                                     |
+| → `default`       | Require approval for edits (daily use)                                                | `/approval-mode default`                                                                                  |
+| → `auto-edit`     | Auto-approve edits (trusted environment)                                              | `/approval-mode auto-edit`                                                                                |
+| → `auto`          | Classifier-evaluated approval (autonomous)                                            | `/approval-mode auto`                                                                                     |
+| → `yolo`          | Auto-approve everything (quick prototyping)                                           | `/approval-mode yolo`                                                                                     |
+| `/model`          | Switch model used in current session                                                  | `/model`, `/model <model-id>` (switch immediately)                                                        |
+| `/model --fast`   | Set a lighter model for prompt suggestions                                            | `/model --fast qwen3-coder-flash`                                                                         |
+| `/model --voice`  | Set the model used for voice transcription                                            | `/model --voice <model-id>`                                                                               |
+| `/model --vision` | Set the vision-bridge model used to transcribe images for a text-only main model      | `/model --vision <model-id>`                                                                              |
+| `/effort`         | Set reasoning effort for thinking-capable models                                      | `/effort` (opens picker), `/effort high` (low/medium/high/xhigh/max; mapped & clamped per provider)       |
+| `/extensions`     | Manage extensions                                                                     | `/extensions list`, `/extensions manage`                                                                  |
+| → `list`          | List installed extensions                                                             | `/extensions list`                                                                                        |
+| → `manage`        | Manage installed extensions (interactive)                                             | `/extensions manage`                                                                                      |
+| → `explore`       | Open extensions page in browser                                                       | `/extensions explore <Gemini\|ClaudeCode>`                                                                |
+| → `install`       | Install an extension from a git repo or path                                          | `/extensions install <repo-or-path>`                                                                      |
+| `/memory`         | Open the Memory Manager dialog                                                        | `/memory`                                                                                                 |
+| `/remember`       | Save a durable memory                                                                 | `/remember Prefer terse responses`                                                                        |
+| `/forget`         | Remove matching entries from auto-memory                                              | `/forget <query>`                                                                                         |
+| `/dream`          | Manually run auto-memory consolidation                                                | `/dream`                                                                                                  |
+| `/hooks`          | Manage Qwen Code hooks                                                                | `/hooks`, `/hooks list`                                                                                   |
+| `/reload-plugins` | Reload extension changes (commands, skills, agents, hooks, MCP/LSP servers) from disk | `/reload-plugins`                                                                                         |
+| `/permissions`    | Manage permission rules                                                               | `/permissions`                                                                                            |
+| `/agents`         | Manage subagents                                                                      | `/agents manage`, `/agents create`                                                                        |
+| `/arena`          | Manage Arena sessions                                                                 | `/arena start`, `/arena stop`, `/arena status`, `/arena select` (alias `choose`)                          |
+| `/goal`           | Set a goal — keep working until condition met                                         | `/goal <condition>`, `/goal clear`                                                                        |
+| `/tasks`          | List background tasks                                                                 | `/tasks`                                                                                                  |
+| `/workflows`      | Inspect workflow runs                                                                 | `/workflows`, `/workflows <runId>`                                                                        |
+| `/lsp`            | Show LSP server status                                                                | `/lsp`                                                                                                    |
+| `/trust`          | Manage folder trust settings                                                          | `/trust`                                                                                                  |
 
 > [!warning]
 >
@@ -123,18 +124,18 @@ Commands for managing AI tools and models.
 
 > [!note]
 >
-> `/workflows`, `/lsp`, and `/trust` are registered only when their feature is enabled — via the `QWEN_CODE_ENABLE_WORKFLOWS=1` env var, the `--experimental-lsp` CLI flag, and the `security.folderTrust.enabled` setting respectively. When disabled they won't appear and will report an unknown command.
+> `/workflows`, `/lsp`, and `/trust` are registered only when their feature is enabled — via the `QWEN_CODE_ENABLE_WORKFLOWS=1` env var, the `--experimental-lsp` CLI flag, and the `security.folderTrust.enabled` setting respectively. When disabled they won't appear and will report an unknown command. Similarly, `/dream` and `/forget` are registered only when managed auto-memory is available; without it they won't appear.
 
 ### 1.5 Built-in Skills
 
 These commands invoke bundled skills that provide specialized workflows.
 
-| Command      | Description                                                 | Usage Examples                                    |
-| ------------ | ----------------------------------------------------------- | ------------------------------------------------- |
-| `/review`    | Review code changes with 9 parallel review agents           | `/review`, `/review 123`, `/review 123 --comment` |
-| `/loop`      | Run a prompt on a recurring schedule                        | `/loop 5m check the build`                        |
-| `/simplify`  | Review recent changes and apply safe cleanup edits directly | `/simplify`, `/simplify focus on duplication`     |
-| `/qc-helper` | Answer questions about Qwen Code usage and configuration    | `/qc-helper how do I configure MCP?`              |
+| Command      | Description                                                 | Usage Examples                                                            |
+| ------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `/review`    | Multi-agent code review (12 parallel agents at high effort) | `/review`, `/review 123`, `/review 123 --comment`, `/review --effort low` |
+| `/loop`      | Run a prompt on a recurring schedule                        | `/loop 5m check the build`                                                |
+| `/simplify`  | Review recent changes and apply safe cleanup edits directly | `/simplify`, `/simplify focus on duplication`                             |
+| `/qc-helper` | Answer questions about Qwen Code usage and configuration    | `/qc-helper how do I configure MCP?`                                      |
 
 See [Code Review](./code-review.md) for full `/review` documentation.
 
@@ -326,7 +327,7 @@ Commands for obtaining information and performing system settings.
 | `/stats monthly` | Show monthly token usage statistics                                                                                            | `/stats monthly` (alias `month`), `/stats month [YYYY-MM]`                          |
 | `/stats export`  | Export usage statistics to CSV or JSON                                                                                         | `/stats export <daily\|monthly> [date\|month] [--format csv\|json] [--output path]` |
 | `/settings`      | Open settings editor                                                                                                           | `/settings`                                                                         |
-| `/config`        | Get or set any setting by dot-path key (writes to user settings)                                                              | `/config` (list all), `/config <key>`, `/config <key>=<value>`                      |
+| `/config`        | Get or set any setting by dot-path key (writes to user settings)                                                               | `/config` (list all), `/config <key>`, `/config <key>=<value>`                      |
 | `/auth`          | Change authentication method                                                                                                   | `/auth`, `/connect`, `/login`                                                       |
 | `/doctor`        | Run installation and environment diagnostics                                                                                   | `/doctor`, `/doctor memory`                                                         |
 | → `memory`       | Show current process memory diagnostics                                                                                        | `/doctor memory [--json] [--sample] [--snapshot]`                                   |

package/bundled/qc-helper/docs/features/computer-use.md

@@ -0,0 +1,77 @@
+# Computer Use
+
+Qwen Code ships built-in **Computer Use** tools that let the agent drive your desktop — clicking, typing, scrolling, launching apps, reading window contents, and taking screenshots. This turns Qwen Code into a general desktop automation agent, not just a coding assistant confined to the terminal.
+
+Computer Use is powered by the [`cua-driver`](https://github.com/trycua/cua) native driver. The tools are registered as deferred (lazy-loaded) built-ins under the `computer_use__` prefix, so they only cost prompt space once the model actually reaches for them.
+
+> [!warning]
+>
+> Computer Use gives the agent control of your mouse, keyboard, and windows, and lets it read the contents of your screen. Only use it with trusted prompts and, where possible, in a sandboxed or disposable environment. The action tools (click, type, drag, etc.) go through the normal [approval flow](./approval-mode.md); read-only tools such as listing windows may run without a prompt.
+
+## Enabling and disabling
+
+Computer Use is **enabled by default**. The `computer_use__*` tools are registered automatically at startup.
+
+To disable it entirely — which also prevents the native driver from being downloaded or spawned — set `tools.computerUse.enabled` to `false` in your `settings.json`:
+
+```jsonc
+{
+  "tools": {
+    "computerUse": {
+      "enabled": false,
+    },
+  },
+}
+```
+
+This setting requires a restart to take effect.
+
+## First run and the native driver
+
+The first time the agent invokes a Computer Use tool, Qwen Code downloads a pinned, signed `cua-driver` binary (~20 MB) into `~/.qwen/computer-use/` and spawns it as a local process. Prebuilt binaries are published for macOS (Apple Silicon and Intel), Linux (x86_64), and Windows (x86_64).
+
+### macOS permissions
+
+On macOS, desktop automation requires two system permissions:
+
+- **Accessibility** — to read window/UI state and synthesize input
+- **Screen Recording** — to capture screenshots
+
+On first use the driver walks you through granting these via the standard macOS system dialogs. The agent can also check permission status on demand (the `check_permissions` tool). Because macOS attributes permission grants to the _responsible_ process, grants may need to be given to the terminal or IDE that launched Qwen Code.
+
+## What the agent can do
+
+The full `cua-driver` tool surface is exposed. Highlights:
+
+| Category      | Tools (a selection)                                                                |
+| ------------- | ---------------------------------------------------------------------------------- |
+| Mouse         | `click`, `double_click`, `right_click`, `drag`, `move_cursor`, `scroll`            |
+| Keyboard      | `type_text`, `press_key`, `hotkey`                                                 |
+| Windows / UI  | `list_windows`, `get_window_state`, `get_accessibility_tree`, `set_value`, `zoom`  |
+| Apps          | `launch_app`, `list_apps`, `bring_to_front`, `kill_app`                            |
+| Browser pages | `page` (execute JavaScript, read text, query the DOM, click elements)              |
+| Screenshots   | `get_window_state` (captures a PNG), `page`                                        |
+| Recording     | `start_recording`, `stop_recording`, `replay_trajectory` (record/replay a session) |
+| Sessions      | `start_session`, `end_session`, agent-cursor overlay controls                      |
+
+Element-addressed actions are preferred over raw pixel coordinates: `get_window_state` returns a Markdown rendering of a window's accessibility tree with a stable `element_index` for each actionable element, which the input tools can target directly.
+
+Support is most complete on macOS; some tools are platform-specific (for example, `bring_to_front` is Windows-only, and `launch_app` targets macOS apps).
+
+## Configuration
+
+All Computer Use settings live under `tools.computerUse` in `settings.json`. See the [Settings reference](../configuration/settings.md) for the authoritative list.
+
+| Setting                               | Type    | Default  | Description                                                                                                                                                                                                                                               |
+| ------------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tools.computerUse.enabled`           | boolean | `true`   | Register the `computer_use__*` tools. When `false`, the driver is never downloaded or spawned.                                                                                                                                                            |
+| `tools.computerUse.maxImageDimension` | number  | `-1`     | Longest-edge pixel cap for screenshots. `-1` keeps the driver's default (1568); `0` disables resizing (full resolution); a positive value caps the longest edge. Lower caps cut vision-token cost. Env override: `QWEN_COMPUTER_USE_MAX_IMAGE_DIMENSION`. |
+| `tools.computerUse.idleTimeoutMs`     | number  | `300000` | Milliseconds to keep the driver process alive after the last `computer_use__*` call (default 5 minutes). `0` keeps it running until Qwen Code exits.                                                                                                      |
+
+All three settings require a restart to take effect.
+
+## See also
+
+- [Approval Mode](./approval-mode.md) — how tool executions are gated
+- [Sandboxing](./sandbox.md) — isolating what tools can touch
+- [Settings reference](../configuration/settings.md) — the full `tools.computerUse.*` schema

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

@@ -243,6 +243,7 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 | `UserPromptSubmit`   | After user submits prompt                 | None (always fires)                                            |
 | `SessionStart`       | When session starts or resumes            | Source (`startup`, `resume`, `clear`, `compact`)               |
 | `SessionEnd`         | When session ends                         | Reason (`clear`, `logout`, `prompt_input_exit`, etc.)          |
+| `MessageDisplay`     | Repeatedly, as the reply streams          | None (always fires)                                            |
 | `Stop`               | When Claude prepares to conclude response | None (always fires)                                            |
 | `SubagentStart`      | When subagent starts                      | Agent type (`Bash`, `Explorer`, `Plan`, etc.)                  |
 | `SubagentStop`       | When subagent stops                       | Agent type                                                     |
@@ -268,6 +269,7 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 | Todo Events         | `TodoCreated`, `TodoCompleted`                                                             | ❌ No           | N/A                                                           |
 | Prompt Events       | `UserPromptSubmit`                                                                         | ❌ No           | N/A                                                           |
 | Stop Events         | `Stop`                                                                                     | ❌ No           | N/A                                                           |
+| Message Display     | `MessageDisplay`                                                                           | ❌ No           | N/A                                                           |
 
 **Matcher Syntax:**
 
@@ -565,6 +567,33 @@ The `permissionDecision` value controls whether the tool runs:
 
 - Standard hook output fields (typically not used for blocking)
 
+#### MessageDisplay
+
+**Purpose**: Fires repeatedly as the assistant's reply streams — before `Stop`, which fires once at the end of the turn. Useful for live narration, incremental logging, or any consumer that wants to react to the reply as it's written rather than after the fact. This is a **fire-and-forget** event - hook output and exit codes are ignored.
+
+**Event-specific fields**:
+
+```json
+{
+  "message_id": "stable id for the whole streamed message",
+  "displayed_text": "the CUMULATIVE text streamed so far for this message (not a delta)",
+  "is_final": "true on the last firing for this message, false otherwise"
+}
+```
+
+`displayed_text` is cumulative rather than a delta so hook scripts never need to reassemble chunks themselves — each firing carries the full text so far. Firing is debounced (at most every ~200ms) except for the final firing (`is_final: true`), which always fires once the message ends, so the reply's tail is never dropped waiting on the debounce window.
+
+**Delivery semantics** — what a hook script can rely on:
+
+- **Slow hooks see fewer, newer payloads.** At most one mid-stream hook execution per message is in flight at a time; while one runs, newer debounced payloads _replace_ the queued one rather than piling up behind it. A hook slower than the debounce window therefore skips intermediate snapshots — lossless, since each payload carries the full cumulative text.
+- **`is_final` is never queued behind a stale delivery.** The final payload is dispatched the moment the message ends — alongside a still-running mid-stream execution if there is one (the one exception to the one-at-a-time rule, justified the same way: the final cumulative text strictly supersedes whatever that execution is processing). Your hook always receives the `is_final` payload, and receives it before the `Stop` hook fires. One consequence for stateful hooks: when the final execution overlaps a superseded mid-stream one, their _completion_ order is unspecified — the stale execution may finish after the final one (even after `Stop`). Treat `is_final` as terminal per `message_id` and let the cumulative text win, rather than assuming the last execution to finish carries the newest state.
+- **The turn waits for `is_final` delivery to complete — but not forever.** The turn's end (and the `Stop` hook, when it fires) waits up to 5 seconds for the final delivery to finish. A hook that completes within that budget keeps the strongest guarantee: a headless run (`qwen -p ...`) exits only after the hook finished, and the `is_final` execution completes before `Stop` starts. A slower hook still receives `is_final` first — only the wait for its completion is bounded: in the terminal UI or an ACP session the execution simply finishes in the background, while a headless run exits without waiting. The hook process is not killed on exit; it is left to finish on its own, so a script chaining `qwen -p … && next-step` can observe `next-step` starting while a slow hook is still running. Hitting this timeout prints a warning on stderr.
+- **Cancellation behaviour depends on timing.** A turn cancelled _before `is_final` dispatches_ fires no `is_final` — the message is treated as abandoned, and a consumer that buffers until `is_final` should treat cancellation-silence as its flush/discard signal (e.g. a timeout fallback). The criterion is the abort signal's state at the moment the turn ends, not whether every chunk had already streamed — an abort landing in the brief gap before that check can still suppress `is_final` for a message whose text had, in practice, finished arriving. Cancelling _after `is_final` has dispatched_ (during the drain wait) is different: the still-running hook execution may be terminated mid-flight (SIGTERM), but the payload itself has already been delivered.
+- **`displayed_text` is provisional until `is_final`.** It reflects what has streamed so far; treat intermediate payloads as display state, not as authoritative final content.
+- **A tool-using turn produces multiple messages.** Each model call gets its own `message_id` with its own `is_final: true` firing: the text before a tool call is one message, the continuation after the tool result is another. Model calls that produce no displayed text (tool-call-only) fire nothing.
+
+**Note**: Fires in the terminal UI, headless (`-p`), and ACP (IDE/editor/`qwen serve`) sessions, with the same payload contract on every surface.
+
 #### Stop
 
 **Purpose**: Executed before Qwen concludes its response to provide final feedback or summaries.