@qwen-code/qwen-code 0.21.5 → 0.21.6

package/bundled/qc-helper/docs/configuration/model-providers.md

@@ -583,14 +583,14 @@ The optional `reasoning` field under `generationConfig` controls how aggressivel
 
 ### Per-provider behavior
 
-| Protocol / provider                                           | Wire shape                                                           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **OpenAI / DashScope** (`qwen3.8-max`, `qwen3.8-max-preview`) | Flat `reasoning_effort: <effort>` body parameter                     | The five `/effort` tiers (`low`, `medium`, `high`, `xhigh`, `max`) are passed through verbatim; DashScope applies any model-specific mapping. Do not also configure `thinking_budget`, because DashScope rejects requests containing both fields. Other Qwen models continue to map a selected effort to `enable_thinking: true`.                                                                                                |
-| **OpenAI / DeepSeek** (`api.deepseek.com`)                    | Flat `reasoning_effort: <effort>` body parameter                     | When `reasoning.effort` is set in the nested config shape, it's rewritten to flat `reasoning_effort` and `'low'`/`'medium'` are normalized to `'high'`, `'xhigh'` to `'max'` — mirroring DeepSeek's [server-side back-compat](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion). Top-level `samplingParams.reasoning_effort` or `extra_body.reasoning_effort` overrides skip this normalization and ship verbatim. |
-| **OpenAI** (other compatible servers)                         | `reasoning: { effort, ... }` passed through verbatim                 | Set via `samplingParams` (e.g. `samplingParams.reasoning_effort` for GPT-5/o-series) when the provider expects a different shape.                                                                                                                                                                                                                                                                                                |
-| **Anthropic** (real `api.anthropic.com`)                      | `output_config: { effort }` plus the `effort-2025-11-24` beta header | Real Anthropic accepts `'low'`/`'medium'`/`'high'` only. `'max'` is **clamped to `'high'`** with a `debugLogger.warn` line (once per generator); if you want max effort, switch the baseURL to a DeepSeek-compatible endpoint that supports it.                                                                                                                                                                                  |
-| **Anthropic** (`api.deepseek.com/anthropic`)                  | Same `output_config: { effort }` + beta header                       | `'max'` is passed through unchanged.                                                                                                                                                                                                                                                                                                                                                                                             |
-| **Gemini** (`@google/genai`)                                  | `thinkingConfig: { includeThoughts: true, thinkingLevel }`           | `'low'` → `LOW`, `'high'`/`'max'` → `HIGH`, others → `THINKING_LEVEL_UNSPECIFIED` (Gemini has no `MAX` tier).                                                                                                                                                                                                                                                                                                                    |
+| Protocol / provider                           | Wire shape                                                           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **OpenAI / DashScope** (`qwen3.8-max` family) | Flat `reasoning_effort: <effort>` body parameter                     | The five `/effort` tiers (`low`, `medium`, `high`, `xhigh`, `max`) are passed through verbatim for any model id starting with `qwen3.8-max` (including dated snapshots and `-latest` aliases); DashScope applies any model-specific mapping. For this family the tier ships alone: a conflicting `enable_thinking` or `thinking_budget` is dropped (warn-logged, once per generator) — DashScope rejects requests combining `reasoning_effort` with `thinking_budget`, and two thinking controls should not ship together. An explicit `enable_thinking: false` in `extra_body` is honoured rather than dropped: it overrides the configured tier as `reasoning_effort: 'none'`, one of the few places `extra_body` does not win verbatim. Other Qwen models continue to map a selected effort to `enable_thinking: true`; a `reasoning_effort` override passes through there unless it conflicts with a `thinking_budget` (a pair DashScope rejects), in which case the inert `reasoning_effort` is dropped and both `enable_thinking` and `thinking_budget` survive. |
+| **OpenAI / DeepSeek** (`api.deepseek.com`)    | Flat `reasoning_effort: <effort>` body parameter                     | When `reasoning.effort` is set in the nested config shape, it's rewritten to flat `reasoning_effort` and `'low'`/`'medium'` are normalized to `'high'`, `'xhigh'` to `'max'` — mirroring DeepSeek's [server-side back-compat](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion). Top-level `samplingParams.reasoning_effort` or `extra_body.reasoning_effort` overrides skip this normalization and ship verbatim.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **OpenAI** (other compatible servers)         | `reasoning: { effort, ... }` passed through verbatim                 | Set via `samplingParams` (e.g. `samplingParams.reasoning_effort` for GPT-5/o-series) when the provider expects a different shape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **Anthropic** (real `api.anthropic.com`)      | `output_config: { effort }` plus the `effort-2025-11-24` beta header | Real Anthropic accepts `'low'`/`'medium'`/`'high'` only. `'max'` is **clamped to `'high'`** with a `debugLogger.warn` line (once per generator); if you want max effort, switch the baseURL to a DeepSeek-compatible endpoint that supports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **Anthropic** (`api.deepseek.com/anthropic`)  | Same `output_config: { effort }` + beta header                       | `'max'` is passed through unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| **Gemini** (`@google/genai`)                  | `thinkingConfig: { includeThoughts: true, thinkingLevel }`           | `'low'` → `LOW`, `'high'`/`'max'` → `HIGH`, others → `THINKING_LEVEL_UNSPECIFIED` (Gemini has no `MAX` tier).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 ### `reasoning: false`
 

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

@@ -302,21 +302,21 @@ The `extra_body` field allows you to add custom parameters to the request body s
 
 #### context
 
-| Setting                                                     | Type                       | Description                                                                                                                                                                                                                                                                                                                                                                          | Default                          |
-| ----------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
-| `context.fileName`                                          | string or array of strings | The name of the context file(s).                                                                                                                                                                                                                                                                                                                                                     | `undefined`                      |
-| `context.autoCompactThreshold`                              | number                     | Target fraction of the context window at which auto-compaction triggers. Must be greater than 0 and at most 1. Default is `0.85` (85%). Acts as a ceiling on the trigger: on large windows it is the effective trigger (~85%), while on smaller windows compaction may fire earlier to leave room to summarize. Replaces the old `model.chatCompression.contextPercentageThreshold`. | `undefined` (uses internal 0.85) |
-| `context.importFormat`                                      | string                     | The format to use when importing memory.                                                                                                                                                                                                                                                                                                                                             | `undefined`                      |
-| `context.includeDirectories`                                | array                      | Additional directories to include in the workspace context. Specifies an array of additional absolute or relative paths to include in the workspace context. Missing directories will be skipped with a warning by default. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag.                | `[]`                             |
-| `context.loadFromIncludeDirectories`                        | boolean                    | Controls the behavior of the `/memory refresh` command. If set to `true`, `QWEN.md` files should be loaded from all directories that are added. If set to `false`, `QWEN.md` should only be loaded from the current directory.                                                                                                                                                       | `false`                          |
-| `context.fileFiltering.respectGitIgnore`                    | boolean                    | Respect .gitignore files when searching.                                                                                                                                                                                                                                                                                                                                             | `true`                           |
-| `context.fileFiltering.respectQwenIgnore`                   | boolean                    | Respect .qwenignore and configured custom ignore files when searching.                                                                                                                                                                                                                                                                                                               | `true`                           |
-| `context.fileFiltering.customIgnoreFiles`                   | array                      | Project-root-relative ignore files to use instead of the default compatibility files (`.agentignore`, `.aiignore`) when `respectQwenIgnore` is enabled. `.qwenignore` is always included.                                                                                                                                                                                            | `[".agentignore", ".aiignore"]`  |
-| `context.fileFiltering.enableRecursiveFileSearch`           | boolean                    | Whether to enable searching recursively for filenames under the current tree when completing `@` prefixes in the prompt.                                                                                                                                                                                                                                                             | `true`                           |
-| `context.fileFiltering.enableFuzzySearch`                   | boolean                    | When `true`, enables fuzzy search capabilities when searching for files. Set to `false` to improve performance on projects with a large number of files.                                                                                                                                                                                                                             | `true`                           |
-| `context.clearContextOnIdle.toolResultsThresholdMinutes`    | number                     | Minutes of inactivity before clearing old tool result content. Use `-1` to disable the idle trigger.                                                                                                                                                                                                                                                                                 | `60`                             |
-| `context.clearContextOnIdle.toolResultsNumToKeep`           | integer                    | Integer number of most-recent compactable tool results to preserve when clearing. Values below 1 are floored to 1.                                                                                                                                                                                                                                                                   | `5`                              |
-| `context.clearContextOnIdle.toolResultsTotalCharsThreshold` | number                     | Total compactable tool result output characters allowed in history before clearing oldest results. Use `-1` to disable the size trigger. This is a soft threshold: protected recent tool results may keep the total above it.                                                                                                                                                        | `500000`                         |
+| Setting                                                     | Type                       | Description                                                                                                                                                                                                                                                                                                                                                                                                      | Default                          |
+| ----------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `context.fileName`                                          | string or array of strings | The name of the context file(s).                                                                                                                                                                                                                                                                                                                                                                                 | `undefined`                      |
+| `context.autoCompactThreshold`                              | number                     | Target fraction of the context window at which auto-compaction triggers. Must be greater than 0 and at most 1. Default is `0.85` (85%). Acts as a ceiling on the trigger: on large windows it is the effective trigger (~85%), while on smaller windows compaction may fire earlier to leave room to summarize. Replaces the old `model.chatCompression.contextPercentageThreshold`.                             | `undefined` (uses internal 0.85) |
+| `context.importFormat`                                      | string                     | The format to use when importing memory.                                                                                                                                                                                                                                                                                                                                                                         | `undefined`                      |
+| `context.includeDirectories`                                | array                      | Additional directories to include in the workspace context. Specifies an array of additional absolute or relative paths to include in the workspace context. Missing directories will be skipped with a warning by default. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag.                                            | `[]`                             |
+| `context.loadFromIncludeDirectories`                        | boolean                    | Controls the behavior of the `/memory refresh` command. If set to `true`, `QWEN.md` files should be loaded from all directories that are added. If set to `false`, `QWEN.md` should only be loaded from the current directory.                                                                                                                                                                                   | `false`                          |
+| `context.fileFiltering.respectGitIgnore`                    | boolean                    | Respect .gitignore files when searching.                                                                                                                                                                                                                                                                                                                                                                         | `true`                           |
+| `context.fileFiltering.respectQwenIgnore`                   | boolean                    | Respect .qwenignore and configured custom ignore files when searching.                                                                                                                                                                                                                                                                                                                                           | `true`                           |
+| `context.fileFiltering.customIgnoreFiles`                   | array                      | Project-root-relative ignore files to use instead of the default compatibility files (`.agentignore`, `.aiignore`) when `respectQwenIgnore` is enabled. `.qwenignore` is always included.                                                                                                                                                                                                                        | `[".agentignore", ".aiignore"]`  |
+| `context.fileFiltering.enableRecursiveFileSearch`           | boolean                    | Whether to enable searching recursively for filenames under the current tree when completing `@` prefixes in the prompt.                                                                                                                                                                                                                                                                                         | `true`                           |
+| `context.fileFiltering.enableFuzzySearch`                   | boolean                    | When `true`, enables fuzzy search capabilities when searching for files. Set to `false` to improve performance on projects with a large number of files.                                                                                                                                                                                                                                                         | `true`                           |
+| `context.clearContextOnIdle.toolResultsThresholdMinutes`    | number                     | Minutes of inactivity before clearing old tool result content. Use `-1` to disable the idle trigger.                                                                                                                                                                                                                                                                                                             | `60`                             |
+| `context.clearContextOnIdle.toolResultsNumToKeep`           | integer                    | Integer number of most-recent compactable tool results to preserve when clearing. Values below 1 are floored to 1.                                                                                                                                                                                                                                                                                               | `5`                              |
+| `context.clearContextOnIdle.toolResultsTotalCharsThreshold` | number                     | Total compactable tool result output characters allowed in history before clearing oldest results. When exceeded, oldest results are cleared down to half this threshold (best effort) so later turns keep reusing the provider prompt cache instead of rewriting history every turn. Use `-1` to disable the size trigger. This is a soft threshold: protected recent tool results may keep the total above it. | `500000`                         |
 
 #### Troubleshooting File Search Performance
 

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

@@ -4,17 +4,31 @@ This guide covers setting up a Qwen Code channel that monitors GitHub notificati
 
 ## Prerequisites
 
-- A GitHub account for the channel. Use a dedicated bot account when the PAT
-  owner also needs to operate the channel.
-- A GitHub Personal Access Token (PAT) with `notifications` and `public_repo` (or `repo`) scopes
+- A GitHub account authenticated with the permissions needed to read notifications and post comments
+- The [GitHub CLI](https://cli.github.com/) installed on the host running Qwen Code when using local `gh` authentication
 
-## Creating a Token
+Use a dedicated bot account when the authenticated account also needs to operate the channel. GitHub does not generate a usable notification for the account's own activity, and the adapter ignores its own comments to prevent reply loops.
 
-1. Go to **Settings → Developer settings → Personal access tokens → Tokens (classic)**
-2. Generate a token with these scopes:
-   - **notifications** — read notification threads
-   - **public_repo** (or **repo** for private repos) — post comments
-3. Save the token securely as an environment variable
+## Authentication
+
+To reuse the GitHub CLI login on the Qwen Code host, authenticate `gh` and explicitly set `useLocalGh: true` in the channel configuration:
+
+```bash
+gh auth login
+```
+
+Local `gh` authentication is account-wide and may expose notifications from every repository visible to that GitHub account. Enable it only when the workspace operator is trusted to use that account. Otherwise, configure a dedicated PAT.
+
+For GitHub Enterprise Server, authenticate the same host used by `baseUrl`:
+
+```bash
+gh auth login --hostname github.example.com
+```
+
+You can instead configure a classic personal access token (PAT). An explicit `token` overrides local `gh` authentication. The PAT needs these scopes:
+
+- **notifications** — read notification threads
+- **public_repo** (or **repo** for private repos) — post comments
 
 ## Configuration
 
@@ -25,7 +39,7 @@ Add the channel to `~/.qwen/settings.json`:
   "channels": {
     "my-github": {
       "type": "github",
-      "token": "$GITHUB_TOKEN",
+      "useLocalGh": true,
       "pollInterval": 60000,
       "reasonFilter": ["mention", "review_requested", "assign"],
       "senderPolicy": "allowlist",
@@ -42,18 +56,13 @@ Add the channel to `~/.qwen/settings.json`:
 }
 ```
 
-Set the token as an environment variable:
+To override local `gh` authentication with a PAT, add `"token": "$GITHUB_TOKEN"` to the channel and set the environment variable before starting Qwen Code:
 
 ```bash
 export GITHUB_TOKEN="ghp_your_token_here"
 ```
 
-The PAT owner cannot trigger its own channel: GitHub self-activity does not
-provide a usable notification, and the adapter intentionally ignores its own
-comments to prevent reply loops. If the PAT owner needs to operate the channel,
-use a separate bot-owned PAT and put only operator accounts in `allowedUsers`.
-Startup rejects an allowlist containing only the PAT owner and warns when the
-PAT owner appears alongside other operators.
+The authenticated account cannot trigger its own channel. If that account needs to operate the channel, authenticate a separate bot account and put only operator accounts in `allowedUsers`. Startup rejects an allowlist containing only the authenticated account and warns when it appears alongside other operators.
 
 ### GitHub Enterprise
 
@@ -65,11 +74,14 @@ For GitHub Enterprise Server, set `baseUrl`:
 }
 ```
 
+Local `gh` authentication requires an HTTPS `baseUrl` so the daemon host credential cannot be sent over plaintext HTTP.
+
 ## Configuration Options
 
 | Option                    | Default                  | Description                                                                                   |
 | ------------------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
-| `token`                   | (required)               | Classic PAT with `notifications` scope                                                        |
+| `token`                   | unset                    | Optional classic PAT with `notifications` scope; overrides local `gh` authentication          |
+| `useLocalGh`              | `false`                  | Explicitly reuse the daemon host's account-wide GitHub CLI authentication                     |
 | `pollInterval`            | `60000`                  | Poll interval in ms                                                                           |
 | `baseUrl`                 | `https://api.github.com` | API base URL (for GHE)                                                                        |
 | `groupPolicy`             | `"disabled"`             | Must be `"open"` for notifications to flow                                                    |
@@ -141,7 +153,7 @@ not retried automatically because GitHub may have created the comment.
 - If a user marks a notification as read on github.com before the bot's poll cycle, the bot will not process it.
 - The bot does not read comments before the current polling window; `author` and `comment` notifications may aggregate up to 20 comments from that window.
 - Inline PR review comments and review summary bodies are not enumerated; only issue/PR comments are processed.
-- Requires a classic PAT with `notifications` scope. Fine-grained PATs do not support the notifications API.
+- The selected credential must support the Notifications API. Fine-grained PATs do not support it; use local `gh` authentication or a classic PAT with `notifications` scope.
 
 ## Starting the Channel
 

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

@@ -238,7 +238,9 @@ export QWEN_REVIEW_ASSETS_REPO=your-org/your-repo   # a repo you can push to
 
 Maintainers typically point it at the repo under review; anyone else can use a fork or a scratch repo. Images land on the `pr-assets/<pr>-review` branch with content-hashed names, and comments reference them by **commit-pinned** URL — immutable even if the branch later moves, and working unchanged on GitHub Enterprise.
 
-The publishing is gated exactly like posting: no designated repo means no publish, and an unauthorized run (no effective `--comment`) is refused the same way `submit` refuses. Only image types are accepted (SVG is excluded deliberately), with size caps, and a manifest records every file pushed. Without a designation, findings keep their evidence as local file paths in the terminal and saved report — nothing breaks, comments just stay text-only.
+For GitHub-triggered reviews (the PR-review workflow), the same variable is wired from a **repository variable** of the same name: with the variable unset the workflow passes an empty value and publishing refuses — nothing changes. A maintainer who sets `QWEN_REVIEW_ASSETS_REPO` in the repository's Actions variables (typically to the repository itself) enables review comments to embed capture PNGs; the branches it writes are cleaned up by the visuals cleanup workflow when the variable points at the same repository, while a fork or scratch destination manages its own retention.
+
+The publishing is gated exactly like posting: no designated repo means no publish, and an unauthorized run (no effective `--comment`) is refused the same way `submit` refuses. Only image types are accepted (SVG is excluded deliberately), with size caps, and each file's bytes must match the format its extension claims — mislabeled or unrecognized content is refused. A manifest records every file pushed. Without a designation, findings keep their evidence as local file paths in the terminal and saved report — nothing breaks, comments just stay text-only.
 
 ## Follow-up Actions
 
@@ -352,6 +354,8 @@ The exit code is the contract a gate should read:
 
 `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.
 
+A time-budgeted run can also export a **soft** deadline so the review stops its open-ended reverse-audit loop while there is still time to verify, compose and post: `QWEN_REVIEW_DEADLINE_EPOCH` is the Unix-seconds moment the run will be killed, and `QWEN_REVIEW_DEADLINE_RESERVE_SECONDS` (default 3600; `0` keeps only the round estimate) is the tail that must remain for the last round's verification, `compose-review` and submission. When the remaining budget no longer fits another round plus that tail, the round builder refuses to build it, and the composed verdict discloses the truncated audit (an otherwise-Approve verdict is capped at Comment). A missing or malformed deadline leaves the review ungated — the outer timeout still bounds the run.
+
 ## 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/headless.md

@@ -58,6 +58,37 @@ qwen --resume 123e4567-e89b-12d3-a456-426614174000 -p "Apply the follow-up refac
 > - Session data is project-scoped JSONL under `~/.qwen/projects/<sanitized-cwd>/chats`.
 > - Restores conversation history, tool outputs, and chat-compression checkpoints before sending the new prompt.
 
+## Run a Persistent Goal
+
+Headless mode accepts `/goal` as the entire prompt. Goal state is stored with the session, so use `--continue` or `--resume <sessionId>` to inspect or control the same Goal from a later process. This requires `general.chatRecording` to remain enabled (the default).
+
+```bash
+# Create a Goal and start its worker
+qwen -p "/goal Finish the release checklist"
+
+# Inspect its saved state in the same session
+qwen --continue -p "/goal"
+```
+
+Use the same `qwen --continue -p "<control>"` pattern for the other operations:
+
+| Control                              | Behavior                                                                                 |
+| ------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `/goal`                              | Report the stored state without calling the model.                                       |
+| `/goal <objective>` or `/goal set …` | Create or replace the Goal and start headless Goal work.                                 |
+| `/goal edit <objective>`             | Revise a non-completed Goal; work starts immediately when the resulting state is active. |
+| `/goal pause`                        | Pause an active Goal without calling the model.                                          |
+| `/goal resume`                       | Resume an eligible Goal and start headless Goal work.                                    |
+| `/goal clear`                        | Clear the Goal without confirmation or a model call.                                     |
+
+Runtime-scheduled Goal continuation segments do not count against `--max-session-turns`, but real user prompts still do. Explicit `--max-wall-time` and `--max-tool-calls` budgets continue to apply; exceeding either pauses active Goal work before the run exits with the budget-specific error.
+
+With `--output-format stream-json`, each Goal status change emits a `stream_event` whose `event.type` is `goal_state`. This canonical state event is emitted even without `--include-partial-messages`. When partial messages are enabled, the older `active_goal` event follows as a compatibility projection; automation should treat `goal_state` as authoritative.
+
+> [!note]
+>
+> This behavior applies to standard headless CLI runs. ACP still uses the legacy Goal command path.
+
 ## Customize the Main Session Prompt
 
 You can change the main session system prompt for a single CLI run without editing shared memory files.

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

@@ -402,6 +402,9 @@ Notes:
 | `--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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `--external-tool-guard-mode <m>`        | `off`              | Managed ACP external pre-execution policy. `off` makes no provider calls and advertises no capability. `required` fails startup unless a compatible provider completes the v1 handshake, then fails every supported top-level tool invocation closed unless its single prepare request is allowed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `--external-tool-guard-endpoint <url>`  | —                  | Origin-only loopback HTTP(S) provider URL used in `required` mode, for example `http://127.0.0.1:8787`. Paths, URL credentials, redirects, non-loopback hosts, and proxy routing are not accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `--external-tool-guard-timeout-ms <n>`  | `3000`             | Integer `100..30000`; applies independently to the startup handshake and each prepare request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `--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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `--initialize-timeout-ms <n>`           | `10000`            | ACP child request timeout, including the `initialize` handshake (ms). Must be a positive integer up to `2147483647`. Values above the JS timer ceiling (`2^31-1`) are rejected at boot because Node silently compresses them to 1 ms. Cold-container deployments that need extra headroom for child startup can raise this; the same value governs `newSession`, workspace-status polls, and other ACP ext-method deadlines.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `--allow-origin <pat>`                  | —                  | T2.4 ([#4514](https://github.com/QwenLM/qwen-code/issues/4514)). Cross-origin allowlist for browser webui clients. Repeatable. Each value is `*` (any origin — boot refuses if no bearer token is configured; `--require-auth` on loopback is recommended so `/health` and `/demo` are also bearer-gated, since both are pre-auth on loopback by default) or a canonical URL origin (`<scheme>://<host>[:<port>]`, no trailing slash / path / userinfo / query). **Subdomain wildcards (`https://*.example.com`) are intentionally unsupported** — list each subdomain explicitly, or use `*` with a configured token (and `--require-auth` for full hardening). Matched origins receive CORS response headers (`Access-Control-Allow-Origin`, `Vary: Origin`, methods, headers, max-age, and exposed `Retry-After`); unmatched origins still get a 403 with the same envelope as today's wall. `Origin: null` (sandboxed iframes, file:// docs) is always rejected, even under `*`. Pre-flight via `caps.features.allow_origin`. Loopback self-origin hits are unaffected. |
@@ -427,6 +430,78 @@ Notes:
 >   matched case-sensitively by yargs `choices` (`--memory-project-scope
 Workspace` is rejected). Use lowercase values when copying between the two.
 
+### Required external Tool Guard
+
+This opt-in is for managed ACP deployments that need an external allow/deny
+decision at the final tool-executor boundary. It is fully dark unless
+`--external-tool-guard-mode=required` is present:
+
+```sh
+export QWEN_CODE_EXTERNAL_TOOL_GUARD_TOKEN='replace-with-local-secret'
+
+qwen serve \
+  --external-tool-guard-mode=required \
+  --external-tool-guard-endpoint=http://127.0.0.1:8787 \
+  --external-tool-guard-timeout-ms=3000
+```
+
+The provider must expose `POST /v1/handshake` and `POST /v1/prepare`, require
+`Authorization: Bearer <token>`, return JSON, echo the supplied nonce or
+request ID, and use protocol version `1`. The token must be non-blank, at most
+8192 UTF-16 code units, and contain no control characters. Requests are limited
+to 1 MiB, responses to 64 KiB, and optional denial reasons to 500 UTF-16 code
+units without control characters. A successful prepare response is:
+
+```json
+{ "protocolVersion": 1, "requestId": "<echo>", "allowed": true }
+```
+
+A denial uses `allowed:false` and may add a short `reason`. For each supported
+top-level tool invocation that passes existing permission and `PreToolUse`
+gates and reaches the final execution boundary, Qwen Code sends one prepare
+request and never retries it. An earlier permission/hook denial sends no
+prepare request. Timeout, cancellation, transport failure, malformed or
+mismatched responses, and explicit denial prevent the executor from running.
+Each spawned ACP channel must also acknowledge that it installed the required
+callback; a missing or incompatible acknowledgement rejects the channel before
+Session creation.
+The provider request carries `sessionId`, `promptId`, `toolCallId`, canonical
+`toolName`, and final `arguments`; `toolCallId` is a correlation label, not an
+authentication identity or standalone idempotency key.
+
+Final arguments can contain sensitive application data. Treat them as such in
+provider logs and audit storage.
+
+`PreToolUse` hooks run before this final executor decision. Required Guard mode
+does not authorize or sandbox hook behavior; deployments that need a boundary
+around every possible side effect must disable hooks or govern their
+implementations separately.
+
+Slash-command actions also run before model/tool scheduling and are not Guard
+invocations. Some built-ins can directly change files or settings. A managed
+deployment that needs an all-effects boundary must reject slash-command input
+or disable every non-approved command through `slashCommands.disabled` or
+`--disabled-slash-commands`.
+
+The v1 managed scope is top-level tools invoked by an active foreground
+managed Prompt. Nested or delegating `agent`, `workflow`,
+`create_sub_session`, `send_message`, direct `/fork`, and agent-backed
+workspace memory remember/dream controls are rejected while required mode is
+active. A top-level background shell or monitor start is still one guarded
+invocation and its final arguments reach the provider, but this feature does
+not continuously authorize the process or add a process-completion audit
+protocol; a policy that requires foreground completion should deny those
+shapes. Guarded MCP calls also disable automatic reconnect/replay after a
+transport error. After a successful startup handshake, `/capabilities`
+advertises `external_tool_guard`; its absence means clients must not assume
+enforcement.
+
+This feature does not authorize explicit daemon REST/ACP management calls;
+those continue to use the daemon's existing authentication and route
+contracts. It also does not make an allowed tool or shell command
+deterministic or sandbox its internals; managed deployments must combine the
+provider decision with their normal tool policy and isolation boundary.
+
 > **Sizing the load knobs.** `--max-sessions` is the per-workspace fresh-session cap. `--max-total-sessions`, when set, is the daemon-wide fresh-session cap.
 > Three other layers also limit load — when sizing for a high-concurrency
 > deployment, tune them together: