@qwen-code/qwen-code 0.21.1-simplify-system-prompt.0 → 0.21.2

package/bundled/qc-helper/docs/features/channels/overview.md

@@ -2,6 +2,8 @@
 
 Channels let you interact with a Qwen Code agent from messaging platforms like Telegram, WeChat, QQ, DingTalk, WeCom, or Feishu, instead of the terminal. You send messages from your phone or desktop chat app, and the agent responds just like it would in the CLI.
 
+Code-hosting platforms (starting with [GitHub](./github)) are also supported via polling adapters — the agent monitors notifications and responds to @mentions on issues and pull requests.
+
 ## How It Works
 
 When you run `qwen channel start`, Qwen Code:
@@ -15,7 +17,7 @@ All channels share one agent process with isolated sessions per user. Each chann
 
 ## Quick Start
 
-1. Set up a bot on your messaging platform (see channel-specific guides: [Telegram](./telegram), [WeChat](./weixin), [QQ Bot](./qqbot), [DingTalk](./dingtalk), [WeCom](./wecom), [Feishu](./feishu))
+1. Set up a bot on your messaging platform (see channel-specific guides: [Telegram](./telegram), [WeChat](./weixin), [QQ Bot](./qqbot), [DingTalk](./dingtalk), [WeCom](./wecom), [Feishu](./feishu), [GitHub](./github))
 2. Add the channel configuration to `~/.qwen/settings.json`
 3. Run `qwen channel start` to start all channels, or `qwen channel start <name>` for a single channel
 
@@ -50,7 +52,7 @@ Channels are configured under the `channels` key in `settings.json`. Each channe
 
 | Option                   | Required         | Description                                                                                                                                                            |
 | ------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`                   | Yes              | Channel type: `telegram`, `weixin`, `qq`, `dingtalk`, `wecom`, `feishu`, or a custom type from an extension (see [Plugins](./plugins))                                 |
+| `type`                   | Yes              | Channel type: `telegram`, `weixin`, `qq`, `dingtalk`, `wecom`, `feishu`, `github`, or a custom type from an extension (see [Plugins](./plugins))                       |
 | `token`                  | Telegram         | Bot token. Supports `$ENV_VAR` syntax to read from environment variables. Not needed for WeChat, DingTalk, WeCom, or Feishu                                            |
 | `clientId`               | DingTalk, Feishu | DingTalk AppKey or Feishu App ID. Supports `$ENV_VAR` syntax                                                                                                           |
 | `clientSecret`           | DingTalk, Feishu | DingTalk AppSecret or Feishu App Secret. Supports `$ENV_VAR` syntax                                                                                                    |
@@ -61,7 +63,9 @@ Channels are configured under the `channels` key in `settings.json`. Each channe
 | `allowedUsers`           | No               | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies)                                                                                   |
 | `sessionScope`           | No               | How sessions are scoped: `user` (default), `thread`, or `single`                                                                                                       |
 | `cwd`                    | No               | Working directory for the agent. Defaults to the current directory                                                                                                     |
+| `approvalMode`           | No               | Tool approval mode for channel sessions. Unattended webhook tasks require `yolo`; the setting applies to every session on the channel                                  |
 | `instructions`           | No               | Custom instructions prepended to the first message of each session                                                                                                     |
+| `webhooks`               | No               | Webhook sources and delivery targets for daemon-managed channels. See [Webhook-triggered tasks](#webhook-triggered-tasks)                                              |
 | `groupPolicy`            | No               | Group chat access: `disabled` (default), `allowlist`, or `open`. See [Group Chats](#group-chats)                                                                       |
 | `dmPolicy`               | No               | Private/DM access: `open` (default) or `disabled` (silently drop all DMs). Useful for group-only bots                                                                  |
 | `groupHistoryLimit`      | No               | Opt-in group history backfill. `0` or omitted disables it. A positive number persists that many authorized, unmentioned group messages for the next bot mention/reply. |
@@ -140,9 +144,14 @@ Existing legacy `CHANNEL.md` memory is migrated automatically to structured
 standalone channel and daemon-managed channel restarts, and is injected when a
 fresh target-scoped session starts, including after `/clear`.
 
-Memory remains keyed to the current chat or thread. It is not injected into a
-`sessionScope: single` session, because that session is shared across the whole
-channel rather than scoped to one target.
+After that initial injection, each accepted message also recalls up to three
+relevant entries for that message. This keeps durable facts available during a
+long-running session without adding every stored entry to every turn. Recall is
+based on the current message and does not modify the stored memory.
+
+Memory remains keyed to the current chat or thread. It is not injected or
+recalled in a `sessionScope: single` session, because that session is shared
+across the whole channel rather than scoped to one target.
 
 Channel memory does not automatically learn facts from normal conversation or
 accept `第一个` as confirmation for an ambiguous natural reference. Use a clear
@@ -387,6 +396,48 @@ By default, the agent works for a while and then sends one large response. With
 
 Only `blockStreaming` is required. The chunk and coalesce settings are optional and have sensible defaults.
 
+## Scheduled Channel Loops
+
+Channels have a persistent scheduler for prompts that should run later and push
+their result back to the same chat. You can ask the agent naturally, for
+example, `Every 15 minutes, check the deployment and report any change`, or use
+the local commands directly:
+
+```text
+/loop add "*/15 * * * *" check the deployment and report any change
+/loop list
+/loop inspect <id>
+/loop cancel <id>
+```
+
+The agent uses the `channel_loop_create`, `channel_loop_list`, and
+`channel_loop_cancel` tools when it manages these jobs for you. Schedules use
+standard five-field cron expressions in the machine's local time. The job runs
+unattended and its final response is delivered automatically to the chat that
+created it.
+
+Channel loops differ from the session-scoped tasks described in
+[Run Prompts on a Schedule](../scheduled-tasks):
+
+- They are stored under `$QWEN_HOME/channels/` — standalone channels use
+  `cron.json` directly, while daemon-managed channels use a per-workspace file
+  under `daemon/`. Both survive channel restarts.
+- They are scoped to the current channel chat or thread. Each target can have up
+  to 10 enabled loops, and each prompt is limited to 4,000 characters.
+- They require an adapter and target that support proactive delivery. Telegram,
+  DingTalk, Feishu, and WeCom opt in, subject to platform-specific target
+  restrictions.
+- They are unavailable with `sessionScope: "single"` because that scope is not
+  tied to one chat target.
+- A saved loop is disabled if its target is no longer authorized when it is due.
+
+## Background Agent Results
+
+When the agent delegates work to a background subagent or fork, the completion
+result is delivered back to the channel chat that owns the session. Delivery
+can happen after the original turn has ended, so keep the channel service or
+daemon running while background work is active.
+
 ## Slash Commands
 
 Channels support slash commands. These are handled locally (no agent round-trip):
@@ -394,10 +445,14 @@ Channels support slash commands. These are handled locally (no agent round-trip)
 - `/help` — List available commands
 - `/clear` — Clear your session and start fresh (aliases: `/reset`, `/new`)
 - `/status` — Show session info and access policy
+- `/loop add "<cron>" <prompt>` — Create a persistent scheduled channel loop
+- `/loop list` — List loops for the current chat
+- `/loop inspect <id>` — Show loop status and run details
+- `/loop cancel <id>` — Disable a loop
 
 All other slash commands (e.g., `/compress`, `/summary`) are forwarded to the agent.
 
-These commands work on all channel types (Telegram, WeChat, QQ, DingTalk, WeCom, Feishu).
+These commands work on all channel types (Telegram, WeChat, QQ, DingTalk, WeCom, Feishu, GitHub), although loop creation also requires proactive delivery support for the current adapter and target.
 
 ## Running
 

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

@@ -273,10 +273,30 @@ Reports include: timestamp, diff stats, build/test results, all findings with ve
 
 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`.
+**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`, `comment-status`, `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.
 
+## Headless runs (`qwen review run`)
+
+`/review` is interactive. When a script or CI job needs to run a review and act on its outcome, use the headless wrapper:
+
+```bash
+qwen review run [target] [--json] [--fail-on request-changes] [--comment] [--quiet]
+```
+
+`target` is a PR number, a PR URL, or a file path; omit it to review the local working tree. The command runs this build's own CLI non-interactively (with stdin closed, so slash-command detection survives), streams the child's progress to **stderr**, and prints the verdict to **stdout** — or, with `--json`, the full result object. The verdict is read from the artifact `compose-review` writes (the same JSON the skill treats as the verdict authority), never parsed from the model's prose.
+
+The exit code is the contract a gate should read:
+
+| Exit | Meaning                                                                                           |
+| ---- | ------------------------------------------------------------------------------------------------- |
+| `0`  | The review completed (whatever it decided)                                                        |
+| `1`  | It never reached a verdict — the child failed, timed out, or left no composed artifact            |
+| `3`  | It completed with `REQUEST_CHANGES` **and** `--fail-on request-changes` was set (opt-in blocking) |
+
+`3` (not `2`) lets a gate distinguish "the review is blocking" from "the tool broke" — yargs already uses `1` for usage errors — without parsing any output. `--timeout-minutes` (default 120, floored at 1) terminates a hung review and exits `1`, and cancelling the command (Ctrl+C / SIGTERM) terminates the review's process group rather than orphaning it.
+
 ## Cross-file Impact Analysis
 
 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:

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

@@ -103,6 +103,24 @@ HTTP hooks send hook input as POST requests to specified URLs. They support URL
 - **DNS Validation**: Validates domain resolution before requests to prevent DNS rebinding attacks
 - **Environment Variable Interpolation**: `${VAR}` syntax, only allows variables in `allowedEnvVars` whitelist
 
+#### Allowing private-network hooks (managed environments only)
+
+By default, HTTP hooks cannot target private or link-local IP ranges. In platform-managed environments where the hook receiver is a first-party, VPC-internal endpoint (for example, an internal API gateway resolving to `172.16.0.0/12`), you can relax the IP-range checks with:
+
+```json
+{
+  "security": {
+    "allowPrivateNetworkHooks": true
+  }
+}
+```
+
+- This setting is **only honored from User, System, and SystemDefaults settings scopes**. A value set in Workspace (project) settings is ignored and logged as a warning, so a cloned repository can never self-grant this bypass.
+- The flag relaxes only the general private/CGNAT/link-local **range** checks. Cloud metadata endpoints stay blocked in every configuration: the `BLOCKED_HOSTS` list is matched literally (`metadata.google.internal`, `metadata.azure.internal`, ...), and the metadata IPs `169.254.169.254` and `100.100.100.200` are blocked in all serialized forms (including IPv4-mapped IPv6 such as `::ffff:a9fe:a9fe`) and after DNS resolution.
+- The `security.allowedHttpHookUrls` whitelist still applies independently. In managed environments, pair this flag with a whitelist so only the intended internal endpoints are reachable.
+
+> **Warning:** Enabling this flag lets hooks reach internal infrastructure on your network. Enable it only in trusted, managed settings — never in a repository you do not control.
+
 **Example:**
 
 ```json
@@ -139,6 +157,8 @@ Function hooks directly call registered JavaScript/TypeScript functions. They ar
 
 Prompt hooks use an LLM to evaluate hook input and return a decision. This is useful for making intelligent decisions based on context, such as determining whether to allow or block an operation.
 
+> **Data handling:** A prompt hook sends its event input to the configured model provider. When file-backed debug logging is enabled, the fully expanded prompt-hook request is also written to the session debug log. Treat hook input and debug logs as potentially sensitive.
+
 **How it works:**
 
 1. The hook input JSON is injected into your prompt using the `$ARGUMENTS` placeholder
@@ -184,7 +204,7 @@ Prompt hooks can be used with most hook events, including:
 - `PostToolUse` - Evaluate tool results and potentially inject context
 - `Stop` - Determine whether to continue or stop
 - `SubagentStop` - Evaluate subagent results
-- `UserPromptSubmit` - Evaluate or enrich user prompts
+- `UserPromptSubmit` - Evaluate or enrich eligible model-bound prompts
 
 **Example: Stop Hook**
 
@@ -240,7 +260,7 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 | `PreToolUse`         | Before tool execution                     | Tool id (`write_file`, `read_file`, `run_shell_command`, etc.) |
 | `PostToolUse`        | After successful tool execution           | Tool id                                                        |
 | `PostToolUseFailure` | After tool execution fails                | Tool id                                                        |
-| `UserPromptSubmit`   | After user submits prompt                 | None (always fires)                                            |
+| `UserPromptSubmit`   | Before supported model invocations        | None                                                           |
 | `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)                                            |
@@ -327,7 +347,18 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 
 ### Hook Input Structure
 
-All hooks receive standardized input in JSON format through stdin (command) or POST body (http).
+All hook executors receive the standardized event input. The delivery boundary depends on the executor:
+
+| Hook type  | Input recipient                                                 |
+| :--------- | :-------------------------------------------------------------- |
+| `command`  | Child process through JSON on `stdin`                           |
+| `http`     | Configured endpoint through a JSON `POST` body                  |
+| `function` | Trusted in-process callback                                     |
+| `prompt`   | Configured model provider after the input replaces `$ARGUMENTS` |
+
+Function hooks are trusted code running in the Qwen process. They receive an in-process object, so fields must not be treated as immutable against a function hook.
+
+Qwen does not control whether a hook process, endpoint, callback, or model provider retains or forwards its input. Review each configured executor's data-handling policy.
 
 **Common Fields:**
 
@@ -343,6 +374,8 @@ All hooks receive standardized input in JSON format through stdin (command) or P
 
 Event-specific fields are added based on the hook type. When running in a subagent, `agent_id` and `agent_type` are additionally included.
 
+Hook input is a forward-extensible JSON contract: new optional fields can be added to existing events. Consumers should ignore unknown fields. A strict decoder that rejects unknown properties must be updated to explicitly allow each new optional field before upgrading Qwen Code. For security-sensitive hooks, a decoder failure can change fail-open or fail-closed behavior, so administrators must validate the upgraded payload against the deployed hook before rollout.
+
 ### Hook Output Structure
 
 Hook output is returned via `stdout` (command) or HTTP response body (http) as JSON.
@@ -491,22 +524,41 @@ The `permissionDecision` value controls whether the tool runs:
 
 #### UserPromptSubmit
 
-**Purpose**: Executed when the user submits a prompt to modify, validate, or enrich the input.
+**Purpose**: Executed before supported model invocations to validate, block, or enrich the current model-bound prompt. The event currently covers `UserQuery`, `ToolResult`, and `Hook` sends, while `Retry`, `Steer`, `Cron`, `Notification`, and `Teammate` sends are skipped. It can therefore occur on continuation paths, and `prompt` must not be assumed to be raw user input.
 
 **Event-specific fields**:
 
 ```json
 {
-  "prompt": "the user's submitted prompt text"
+  "prompt": "current model-bound prompt for this hook invocation",
+  "submitted_prompt": "optional user text captured at a supported interactive TUI submission boundary"
 }
 ```
 
+`submitted_prompt` is optional. It is present only when Qwen can carry provenance from a supported interactive TUI submission to a fresh `UserQuery`. It is omitted for unsupported producers and machine-driven paths such as same-turn steering, tool-result continuations, retries, cron, notifications, and teammate traffic. ACP, headless, `serve`, SDK, and remote-input paths do not produce it in this version.
+
+Deferred input can retain the field when its provenance remains complete. A combined batch retains provenance only when every constituent item has it; edited, partially known, or otherwise ambiguous input omits the field. Prompt, command, and shell-history navigation or selected search matches, cross-restart stash restores, and conversation rewind restores also omit it because those paths can surface model-bound text without its original provenance. Consumers that require user-submitted text should treat absence as unavailable rather than falling back to `prompt`.
+
+After restored or provenance-unavailable model-bound input is cleared or submitted, the composer also clears its undo and redo history. This prevents undo from restoring expanded text after its marker or sidecar has been consumed.
+
+Large-paste placeholders remain compact in `submitted_prompt`; the expanded pasted content appears only in `prompt`. Consumers should treat the field as a TUI text projection rather than a byte-for-byte record of clipboard input.
+
+Any non-empty input present while Vim mode is enabled omits `submitted_prompt`, including after Vim is disabled, because Vim registers do not carry provenance in this version. This conservative rule also covers drafts entered before enabling Vim. Clearing the composer starts a new eligible input.
+
+This field is provenance, not authentication, tenant identity, authorization, or DLP. It is caller-supplied data. Every executor configured for this event receives it; in particular, HTTP hooks send it to their endpoint and prompt hooks send it to their model provider.
+
+When both fields are present, prompt-hook payloads contain overlapping text and can consume additional model input tokens. There is no per-hook field suppression in this version.
+
+Sequential UserPromptSubmit hooks can append `additionalContext` to `prompt`; `submitted_prompt` continues to represent the captured submission. Function hooks are trusted same-process code and are not constrained by an immutability guarantee.
+
 **Output Options**:
 
 - `decision`: "allow", "deny", "block", or "ask"
 - `reason`: human-readable explanation for the decision
 - `hookSpecificOutput.additionalContext`: additional context to append to the prompt (optional)
 
+When sent to the model, injected `additionalContext` is appended as its own message part wrapped in a reserved `<qwen:user-prompt-submit-context>...</qwen:user-prompt-submit-context>` tag, so it stays distinguishable from user-authored text in model history and session transcripts. Angle brackets in hook output are escaped before wrapping, so hook content cannot close or forge the tag. The session transcript also records the user's original prompt text separately; the interactive TUI and the ACP/export transcript-replay path display that original text rather than the injected context.
+
 **Note**: Since UserPromptSubmitOutput extends HookOutput, all standard fields are available but only additionalContext in hookSpecificOutput is specifically defined for this event.
 
 **Example Output**:
@@ -633,13 +685,13 @@ The `context_usage`, `context_limit`, and `input_tokens` fields allow hook scrip
 
 #### StopFailure
 
-**Purpose**: Executed when the turn ends due to an API error (instead of Stop). This is a **fire-and-forget** event - hook output and exit codes are ignored.
+**Purpose**: Executed when the turn ends due to an API error or loop detection (instead of Stop). This is a **fire-and-forget** event - hook output and exit codes are ignored.
 
 **Event-specific fields**:
 
 ```json
 {
-  "error": "rate_limit | authentication_failed | billing_error | invalid_request | server_error | max_output_tokens | unknown",
+  "error": "rate_limit | authentication_failed | billing_error | invalid_request | server_error | max_output_tokens | loop_detected | unknown",
   "error_details": "detailed error message (optional)",
   "last_assistant_message": "the last message from the assistant before the error (optional)"
 }
@@ -1289,9 +1341,11 @@ A PostToolUse HTTP hook that sends all tool execution records to a remote audit
 }
 ```
 
-### Example 3: User Prompt Validation Hook
+### Example 3: Interactive TUI Submitted Prompt Validation Hook
+
+To inspect the current model-bound content instead, read `prompt`. That field can include generated or expanded content, is not the original user input, and does not imply that `UserPromptSubmit` covers every model send. Do not silently fall back from `submitted_prompt` to `prompt` when source provenance is required.
 
-A UserPromptSubmit hook that validates user prompts for sensitive information and provides context for long prompts:
+A UserPromptSubmit hook that validates supported interactive TUI submissions for sensitive information and provides context for long prompts. It skips invocations where source provenance is unavailable. The keyword check is illustrative and is not a complete DLP policy:
 
 **prompt_validator.py**
 
@@ -1305,9 +1359,12 @@ try:
     input_data = json.load(sys.stdin)
 except json.JSONDecodeError as e:
     print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
-    exit(1)
+    sys.exit(1)
 
-user_prompt = input_data.get("prompt", "")
+user_prompt = input_data.get("submitted_prompt")
+if user_prompt is None:
+    # Do not mistake model-bound or machine-generated content for raw input.
+    sys.exit(0)
 
 # Sensitive words list
 sensitive_words = ["password", "secret", "token", "api_key"]
@@ -1324,7 +1381,7 @@ for word in sensitive_words:
             }
         }
         print(json.dumps(output))
-        exit(0)
+        sys.exit(0)
 
 # Check prompt length and add warning context if too long
 if len(user_prompt) > 1000:
@@ -1335,10 +1392,10 @@ if len(user_prompt) > 1000:
         }
     }
     print(json.dumps(output))
-    exit(0)
+    sys.exit(0)
 
 # No processing needed for normal cases
-exit(0)
+sys.exit(0)
 ```
 
 ## Troubleshooting
@@ -1347,5 +1404,5 @@ exit(0)
 - Verify hook script permissions and executability
 - Ensure proper JSON formatting in hook outputs
 - Use specific matcher patterns to avoid unintended hook execution
-- Use `--debug` mode to see detailed hook matching and execution information
+- Use `--debug` mode to see detailed hook matching and execution information. Prompt-hook inputs can be written to the session debug log, so apply appropriate access and retention controls.
 - Temporarily disable all hooks: add `"disableAllHooks": true` in settings

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

@@ -295,7 +295,7 @@ The OAuth flow requires a redirect URI where the authorization provider sends th
 
 - **Local development**: By default, Qwen Code uses `http://localhost:7777/oauth/callback`. This works when running Qwen Code on your local machine with a local browser.
 
-- **Remote/cloud deployments**: When running Qwen Code on remote servers, cloud IDEs, or web terminals, the default `localhost` redirect will NOT work. You MUST configure `--oauth-redirect-uri` to point to a publicly accessible URL that can receive the OAuth callback.
+- **Remote/cloud deployments**: When running Qwen Code on remote servers, cloud IDEs, or web terminals, the default `localhost` redirect will NOT work. Configure `--oauth-redirect-uri` with a public URL ending in `/oauth/callback`, then reverse-proxy that path to `http://127.0.0.1:7777/oauth/callback` on the machine running Qwen Code. Qwen Code does not terminate TLS; the proxy must do so.
 
 Example for remote servers:
 
@@ -304,6 +304,14 @@ qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
   --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback
 ```
 
+For example, a reverse proxy can forward only this callback path to the local listener:
+
+```nginx
+location = /oauth/callback {
+  proxy_pass http://127.0.0.1:7777;
+}
+```
+
 #### Manual configuration via settings.json
 
 You can also configure OAuth by editing `settings.json` directly:

package/bundled/qc-helper/docs/features/scheduled-tasks.md

@@ -4,7 +4,9 @@
 
 Scheduled tasks let Qwen Code re-run a prompt automatically on an interval. Use them to poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
 
-Tasks are session-scoped: they live in the current Qwen Code process and are gone when you exit. Nothing is written to disk.
+Tasks created from the terminal are session-scoped: they live in the current Qwen Code process and are gone when you exit. Nothing is written to disk.
+
+Messaging channels use a separate persistent scheduler so results can be pushed back to the originating chat after the current turn. See [Scheduled Channel Loops](./channels/overview#scheduled-channel-loops) for the channel commands, persistence behavior, and delivery constraints.
 
 > **Tip:** Scheduled tasks are enabled by default. To disable them, set `experimental.cron: false` in your [settings](../configuration/settings.md), or set `QWEN_CODE_DISABLE_CRON=1` in your environment.
 

package/bundled/qc-helper/docs/features/sub-agents.md

@@ -25,14 +25,28 @@ Only `subagent_type: "fork"` accepts `fork_turns`:
 
 Tool responses and pure system reminders do not count as user turns. Regular named subagents and agent-team teammates do not accept `fork_turns`; they keep their separate conversation context.
 
+## Restricting Fork Tool Execution with `fork_tools`
+
+Only `subagent_type: "fork"` accepts `fork_tools`. The array may contain exact canonical tool names, such as `read_file` and `grep_search`, or MCP server patterns such as `mcp__github`. The fork still receives the same model-visible tool declarations as an unrestricted fork, preserving its prompt-cache prefix, but its task prompt identifies the restriction and a call not matched by `fork_tools` is rejected before scheduling or approval.
+
+- Omitting `fork_tools` preserves unrestricted fork execution.
+- An empty array rejects every tool call.
+- `*` is not accepted; omit `fork_tools` when unrestricted execution is intended.
+- Tool names cannot have surrounding whitespace. Wildcards are accepted only as `mcp__*` or as a trailing MCP tool-prefix pattern such as `mcp__github__read_*`.
+- `mcp__*` intentionally allows every MCP tool while still denying unlisted built-in tools.
+- Shell command argument patterns are not supported. Listing `run_shell_command` allows that tool to proceed through its normal permission checks but does not pre-approve any command.
+
+This is a per-invocation restriction supplied by the caller. It narrows a child fork's capabilities but is not an administrator-enforced security sandbox because the caller can omit or expand the list.
+
 ### How Fork Differs from Named Subagents
 
-|               | Named Subagent                                                 | Fork Subagent                                                                           |
-| ------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| Context       | Starts fresh with no parent conversation history               | Inherits all parent history by default; `fork_turns` can select a bounded recent window |
-| System prompt | Uses its own configured prompt                                 | Uses parent's exact system prompt (for cache sharing)                                   |
-| Execution     | Background by default; supports an explicit foreground opt-out | Always detached; parent continues immediately                                           |
-| Use case      | Specialized tasks (testing, docs)                              | Parallel tasks that need the current context                                            |
+|               | Named Subagent                                                 | Fork Subagent                                                                                                       |
+| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| Context       | Starts fresh with no parent conversation history               | Inherits all parent history by default; `fork_turns` can select a bounded recent window                             |
+| System prompt | Uses its own configured prompt                                 | Uses parent's exact system prompt (for cache sharing)                                                               |
+| Tools         | Configured declaration set                                     | Keeps the parent-derived declaration set; `fork_tools` can independently narrow execution without changing that set |
+| Execution     | Background by default; supports an explicit foreground opt-out | Always detached; parent continues immediately                                                                       |
+| Use case      | Specialized tasks (testing, docs)                              | Parallel tasks that need the current context                                                                        |
 
 ### When Fork is Used
 
@@ -46,9 +60,9 @@ The AI automatically uses fork when it needs to:
 
 All forks share the parent's exact API request prefix (system prompt, tools, conversation history), enabling DashScope prompt cache hits. When 3 forks run in parallel, the shared prefix is cached once and reused — saving 80%+ token costs compared to independent subagents.
 
-### Recursive Fork Prevention
+### Recursive Delegation Prevention
 
-Fork children cannot create further forks. This is enforced at runtime — if a fork attempts to spawn another fork, it receives an error instructing it to execute tasks directly.
+Fork children cannot spawn any further sub-agent. This is enforced at runtime — if a fork calls the Agent tool, it receives an error instructing it to execute tasks directly.
 
 ### Current Limitation
 
@@ -242,6 +256,26 @@ This setting accepts the same selectors described above. It is applied only
 when Qwen Code resolves the built-in Explore definition; a session, project,
 user, or extension agent named Explore keeps its own `model` setting.
 
+To let the model select from user-defined grades without exposing concrete
+model IDs, configure `agents.modelGrades` and optionally restrict them with
+`agents.allowedGrades`:
+
+```json
+{
+  "agents": {
+    "modelGrades": {
+      "small": "fast",
+      "high": "qwen-max"
+    },
+    "allowedGrades": ["small", "high"]
+  }
+}
+```
+
+The Agent tool then accepts `model: "small"` or `model: "high"` for regular
+subagents. Unknown, disallowed, fork, and named-teammate grade selections are
+rejected. A custom agent's explicit model still takes precedence over a grade.
+
 #### Permission Mode
 
 Use the optional `approvalMode` frontmatter field to control how a subagent's tool calls are approved. Valid values:

package/bundled/qc-helper/docs/qwen-serve.md

@@ -192,7 +192,7 @@ idle daemon returns `initialized: false` with an empty snapshot. Once a
 session is alive they switch to `initialized: true` and surface the real
 state.
 
-To mirror the CLI `/skills` panel remotely, call `POST /workspace/skills/:name/enable` with `{ "enabled": true | false }` after checking the `workspace_skill_toggle` capability. The route writes only workspace `skills.disabled`, rejects unknown, hidden, inactive-extension, higher-scope-locked, and untrusted targets, and immediately refreshes active ACP sessions. A `deferred` response means the setting was saved while no ACP child was running; it will apply when the child starts. `skills.disabled` disables both manual and model use, unlike `disable-model-invocation: true`, which keeps direct `/skill-name` invocation available.
+To mirror the CLI `/skills` panel remotely, call `POST /workspace/skills/:name/enable` with `{ "enabled": true | false }` after checking the `workspace_skill_toggle` capability. The route updates workspace `skills.disabled` and `skills.enabled` as needed, rejects unknown, hidden, inactive-extension, higher-scope-locked, and untrusted targets, and immediately refreshes active ACP sessions. Enabling a `skills.defaultDisabled` skill writes a canonical opt-in to `skills.enabled`; a hard `skills.disabled` entry inherited from a higher scope still cannot be overridden. Skill status cells expose `disabledReason` (`hard`, `default`, or `inactive_extension`) and an optional `lockedScope`. A `deferred` response means the setting was saved while no ACP child was running; it will apply when the child starts. `skills.disabled` disables both manual and model use, unlike `disable-model-invocation: true`, which keeps direct `/skill-name` invocation available.
 
 `GET /workspace/env` and `GET /workspace/preflight` always answer with
 `initialized: true` regardless of ACP state. `env` never consults ACP
@@ -218,17 +218,19 @@ remediation.
 
 The daemon also exposes workspace file helpers:
 
-- `GET /file` reads text files and returns a raw-byte `sha256:<hex>` hash.
+- `GET /file` reads text files. Full-snapshot responses return a raw-byte
+  `sha256:<hex>` hash; finite-line windows from files above 256 KiB omit it.
 - `GET /file/bytes` reads bounded raw byte windows and returns base64 content.
 - `POST /file/write` creates or replaces text files.
 - `POST /file/edit` applies one exact text replacement.
 
 Write/edit are **strict mutation routes**: even on loopback they require a
 configured bearer token, otherwise they return `token_required`. Replacements
-and edits require the latest `expectedHash` from `GET /file` (or a full-window
-`GET /file/bytes`). `create` never overwrites. Explicit writes to ignored paths
-are allowed but audited. Binary writes, delete/move/mkdir, and recursive parent
-creation are not part of this surface.
+and edits require the latest `expectedHash` from a full-snapshot `GET /file`
+(or a full-window `GET /file/bytes`). A partial large-file window cannot be
+used as an optimistic-concurrency token. `create` never overwrites. Explicit
+writes to ignored paths are allowed but audited. Binary writes,
+delete/move/mkdir, and recursive parent creation are not part of this surface.
 
 ### 3. Open a session
 
@@ -393,7 +395,9 @@ Notes:
 | `--channel <name\|all>`                 | —               | Experimental daemon-managed channel worker. Repeat the flag to select multiple configured channels, or pass `all` to start every configured channel. `all` cannot be combined with named channels. Selected channel `cwd` values must resolve to a registered workspace; a multi-workspace daemon runs one worker per owning workspace. The worker is owned by `qwen serve`; stop the daemon to stop serve-managed channels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `--max-connections <n>`                 | `256`           | Listener-level TCP connection cap (`server.maxConnections`). Bounds raw socket count irrespective of session count — slow / phantom SSE clients get rejected at accept time once full. Raise alongside `--max-sessions` if your deployment expects many SSE subscribers per session.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `--event-ring-size <n>`                 | `8000`          | Per-session SSE replay ring depth (#3803 §02 target). Sets the backlog available to `GET /session/:id/events` with `Last-Event-ID: N`. Larger = more reconnect headroom at the cost of a few hundred KB extra RAM per session. SDK clients can additionally request a larger per-subscriber backlog cap on a specific subscription via `?maxQueued=N` (range `[16, 2048]`, default 256). Daemons also emit a non-terminal `slow_client_warning` SSE frame at 75% queue fill so clients can drain / reconnect before getting evicted. Pre-flight `caps.features.slow_client_warning`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `--compacted-replay-max-bytes <n>`      | `4194304`       | Per-live-session byte cap for the retained replay events in the bounded snapshot returned by `POST /session/:id/load`. The cap applies to `compactedReplay`; the current in-flight `liveJournal` remains uncapped. Values must be positive safe integers; invalid values fail at boot, and the hard ceiling is 256 MiB. When older retained replay is dropped, the snapshot begins with `history_truncated`. This does not limit the on-disk transcript.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `--compacted-replay-max-bytes <n>`      | `4194304`       | Per-live-session byte cap for the retained replay events in the bounded snapshot returned by `POST /session/:id/load`. The cap applies to `compactedReplay`; the current in-flight `liveJournal` is separately capped by `--max-journal-events` and `--max-journal-bytes`. Values must be positive safe integers; invalid values fail at boot, and the hard ceiling is 256 MiB. When older retained replay is dropped, the snapshot begins with `history_truncated`. This does not limit the on-disk transcript.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `--max-journal-events <n>`              | `10000`         | Per-session cap on the number of raw events retained in the in-flight live journal (the current unfinished turn). When exceeded, the oldest journal entries are dropped and a `history_truncated` marker is prepended. Must be a positive safe integer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `--max-journal-bytes <n>`               | `8388608`       | Per-session byte cap on the in-flight live journal. When exceeded, the oldest journal entries are dropped (at least one entry is always kept). Must be a positive safe integer. Defaults to 8 MiB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `--mcp-client-budget <n>`               | —               | Positive integer cap on live MCP clients. When `mcp_workspace_pool` is advertised, the cap and transports are shared per workspace runtime; when the tag is absent, the legacy per-session manager enforces it. Combine with `--mcp-budget-mode`. When unset, no accounting-driven enforcement (but `GET /workspace/mcp` still reports `clientCount`). Distinct from claude-code's `MCP_SERVER_CONNECTION_BATCH_SIZE`, which gates startup concurrency rather than total live clients. Pre-flight `caps.features.mcp_guardrails` and `caps.features.mcp_workspace_pool`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `--mcp-budget-mode <m>`                 | `warn` / `off`  | How `--mcp-client-budget` is enforced. `warn` (default when budget set): no refusal, snapshot's `budgets[0].status` flips to `warning` at ≥75% of budget. `enforce`: connects past the cap are refused, per-server cell shows `disabledReason: 'budget'`, deterministic by `mcpServers` declaration order. `off` (default when budget unset): pure observability. Boot rejects `enforce` without a budget.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `--http-bridge`                         | `true`          | Stage 1 mode: production attempts to preheat one primary `qwen --acp` child for compatibility and retries on first use after failure, while each trusted secondary can start one child on demand. Sessions targeting a runtime multiplex onto its child via ACP `newSession()`; untrusted secondaries cannot start ACP. Stage 2 native in-process becomes available later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

package/bundled/qc-helper/docs/reference/keyboard-shortcuts.md

@@ -69,7 +69,7 @@ This document lists the available keyboard shortcuts in Qwen Code.
 
 ## History scrollback
 
-Active only when `ui.useTerminalBuffer` is enabled (Settings → UI → Virtualized History). In that mode conversation history is rendered inside an in-app viewport instead of the host terminal scrollback, so the keys below replace the terminal's native scroll.
+Active when `ui.useTerminalBuffer` is enabled (Settings → UI → Virtualized History), screen reader mode is off, and Qwen Code is running in a compatible interactive terminal (`stdout` is a TTY, CI is inactive, and `TERM` is not `dumb`), which is the default for ordinary non-screen-reader sessions. In that mode conversation history is rendered inside an in-app viewport instead of the host terminal scrollback, so the keys below replace the terminal's native scroll.
 
 | Shortcut        | Description                                          |
 | --------------- | ---------------------------------------------------- |
@@ -87,7 +87,7 @@ When `ui.useTerminalBuffer` is on, the terminal forwards mouse events to qwen-co
 
 Inside tmux, some terminals translate trackpad or wheel gestures into plain `Up Arrow` and `Down Arrow` sequences before qwen-code sees them. Those bytes are identical to real arrow-key presses, so qwen-code cannot tell whether you meant to scroll the viewport or navigate prompt history.
 
-If trackpad scrolling changes the prompt history in tmux, enable `ui.useTerminalBuffer`; then use `Shift+Up` / `Shift+Down`, or the mouse wheel when tmux forwards wheel events to the app. If you prefer host scrollback, adjust your tmux mouse bindings for wheel events.
+If trackpad scrolling changes the prompt history in tmux, make sure `ui.useTerminalBuffer` is enabled; then use `Shift+Up` / `Shift+Down`, or the mouse wheel when tmux forwards wheel events to the app. If you prefer host scrollback, adjust your tmux mouse bindings for wheel events.
 
 ## IDE Integration
 

package/bundled/qc-helper/docs/support/troubleshooting.md

@@ -59,6 +59,7 @@ This guide provides solutions to common issues and debugging tips, including top
   - A: Start Qwen Code with the `--safe-mode` flag to disable all customizations — context files, hooks, extensions, skills, MCP servers, custom subagents (only built-in subagents load), permission rules, settings-sourced approval mode overrides, memory features, and sandbox settings — for the session. Note: the CLI flags `--yolo` and `--approval-mode` still take effect in safe mode. If the problem disappears in safe mode, re-enable your customizations one at a time to find the culprit.
     - Example: `qwen --safe-mode`
     - Alternative: set the environment variable `QWEN_CODE_SAFE_MODE=true` if the CLI cannot accept flags.
+    - Note: "MCP servers" here means servers configured in `settings.json` / project `.mcp.json` — local, ambient state that safe mode is meant to isolate against. MCP servers you explicitly supply for the current invocation (an embedding ACP client's `session/new` `mcpServers`, or `--mcp-config`) are not local/ambient state and are still honored under safe mode.
 
 ## Common error messages and solutions
 
@@ -99,7 +100,7 @@ This guide provides solutions to common issues and debugging tips, including top
 - **Trackpad scrolling in tmux changes prompt history instead of scrolling the conversation**
   - **Issue:** In a tmux session, trackpad or wheel scrolling may cycle through previous prompts, similar to pressing `Up Arrow` or `Down Arrow`.
   - **Cause:** tmux can translate wheel gestures into plain arrow-key sequences. Those sequences are indistinguishable from real arrow-key presses by the time qwen-code receives them.
-  - **Solution:** Enable `ui.useTerminalBuffer`; then use `Shift+Up` / `Shift+Down`, or the mouse wheel when tmux forwards wheel events to the app. If you prefer host scrollback, adjust your tmux mouse bindings for wheel events.
+  - **Solution:** If screen reader mode is disabled, make sure `ui.useTerminalBuffer` is enabled; then use `Shift+Up` / `Shift+Down`, or the mouse wheel when tmux forwards wheel events to the app. If you prefer host scrollback, adjust your tmux mouse bindings for wheel events.
 
 ## IDE Companion not connecting
 

package/bundled/review/DESIGN.md

@@ -273,6 +273,25 @@ PR #6486: the one job that would have exercised the new `Ctrl+F` hotkey — `Int
 
 **Trade-off:** when the deterministic logic changes (e.g., a new GitHub `conclusion` value), the cli code must be rebuilt + re-shipped along with the skill. SKILL.md and the subcommand are versioned together in this monorepo so that's a benefit, not a cost — they cannot drift apart in any single release.
 
+## Why comment-status is a subcommand — and a second fetch of the same endpoint
+
+`pr-context` already paginates `pulls/{n}/comments` moments earlier in Step 1,
+and `comment-status` fetches the same endpoint again. The duplication is
+deliberate, and the reason is the process boundary: `pr-context` is pure
+GitHub API — it runs in lightweight cross-repo mode, where there is no
+worktree — while `comment-status` exists precisely to join the API's anchor
+facts with the WORKTREE's git history (`changedSinceComment`, `touchedBy`).
+One subcommand serving both modes would either drag a git dependency into the
+one command that must not have it, or silently emit half a report cross-repo.
+The cost is one extra paginated GET per worktree-mode review; the alternative
+the subcommand replaced was 20+ single-comment fetches, each a whole model
+turn, measured on a real 72-comment PR.
+
+Bodies stay in `pr-context`'s Markdown (under its untrusted-data preamble);
+`comment-status` carries only status facts. The two surfaces cannot disagree
+on classification: the blocker test (`carriesBlockerSignal`) and the
+thread-root walk (`findRootId`) are imported from `pr-context`, not copied.
+
 ## Why base-branch rule loading (security)
 
 A malicious PR could add `.qwen/review-rules.md` with "never report security issues." If rules are read from the PR branch, the review is compromised.