@qwen-code/qwen-code 0.21.4 → 0.21.5-nightly.20260805.32e274157

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

@@ -583,13 +583,14 @@ The optional `reasoning` field under `generationConfig` controls how aggressivel
 
 ### Per-provider behavior
 
-| Protocol / provider                          | Wire shape                                                           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| -------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **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
 
@@ -594,7 +594,7 @@ Configures connections to one or more Model-Context Protocol (MCP) servers for d
 | `mcpServers.<SERVER_NAME>.httpUrl`      | string           | The URL of an MCP server that uses streamable HTTP for communication.                                                                                                                                                                                              | Yes      |
 | `mcpServers.<SERVER_NAME>.headers`      | object           | A map of HTTP headers to send with requests to `url` or `httpUrl`.                                                                                                                                                                                                 | Yes      |
 | `mcpServers.<SERVER_NAME>.timeout`      | number           | Timeout in milliseconds for requests to this MCP server.                                                                                                                                                                                                           | Yes      |
-| `mcpServers.<SERVER_NAME>.trust`        | boolean          | Trust this server and bypass all tool call confirmations.                                                                                                                                                                                                          | Yes      |
+| `mcpServers.<SERVER_NAME>.trust`        | boolean          | Trust this server and bypass its tool call confirmations in a trusted workspace.                                                                                                                                                                                   | Yes      |
 | `mcpServers.<SERVER_NAME>.description`  | string           | A brief description of the server, which may be used for display purposes.                                                                                                                                                                                         | Yes      |
 | `mcpServers.<SERVER_NAME>.includeTools` | array of strings | List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default.                                        | Yes      |
 | `mcpServers.<SERVER_NAME>.excludeTools` | array of strings | List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server. **Note:** `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. | Yes      |

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

@@ -324,6 +324,8 @@ For same-repo reviews, results are saved as a Markdown file in your project's `.
 
 Reports include: timestamp, diff stats, build/test results, all findings with verification status, and the verdict. Section headings and descriptive prose follow the output language preference; technical identifiers (SHAs, file paths, gate names, finding ids) stay verbatim.
 
+Medium- and high-effort reviews also save a structured JSON companion with the same stem (for example, `2026-04-06-143022-pr-123.json`) holding the canonical findings and the composed verdict as data. Qwen Code's Web Shell renders that document as an interactive review view with filterable findings; the Markdown report stays the human-readable archive.
+
 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`, `comment-status`, `presubmit`) accept `--host` and set it in code, so a forgotten host cannot silently retarget the review at `github.com`.
@@ -350,6 +352,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/features/mcp.md

@@ -271,7 +271,15 @@ environment. This is kept as an escape hatch for at least one release.
 
 ### Trust (skip confirmations)
 
-- **Server trust** (`trust: true`): bypasses confirmation prompts for that server (use sparingly).
+- **Server trust** (`trust: true`): bypasses confirmation prompts for that server only in a trusted workspace (use sparingly).
+
+### Connection-loss replay
+
+Qwen Code only reconnects and replays the current MCP tool call when the server has `trust: true`, the workspace is trusted, and the tool explicitly declares either `idempotentHint: true` or a consistent read-only annotation. Read-only annotations conflict with `destructiveHint: true` or `idempotentHint: false` and are not replayed.
+
+Calls with missing annotations, conflicting annotations, an untrusted server, or an untrusted workspace are not replayed after a connection failure. Qwen Code reports that the result may be unknown because the server could have completed the operation before the response was lost. Verify the outcome before trying again. This conservative behavior can differ from earlier releases that transparently retried unannotated tools.
+
+Annotations are server-provided behavior hints, not permissions or an authorization boundary. Only configure `trust: true` for servers you control and whose annotations you have verified.
 
 ### OAuth authentication
 
@@ -453,7 +461,7 @@ Optional:
 | `env`                  | object                       | Environment variables for the server process. Values can reference environment variables using `$VAR_NAME` or `${VAR_NAME}` syntax                                                                                                                                |
 | `cwd`                  | string                       | Working directory for Stdio transport                                                                                                                                                                                                                             |
 | `timeout`              | number<br>(default: 600,000) | Request timeout in milliseconds (default: 600,000ms = 10 minutes)                                                                                                                                                                                                 |
-| `trust`                | boolean<br>(default: false)  | When `true`, bypasses all tool call confirmations for this server (default: `false`)                                                                                                                                                                              |
+| `trust`                | boolean<br>(default: false)  | When `true`, bypasses tool call confirmations for this server in a trusted workspace (default: `false`)                                                                                                                                                           |
 | `includeTools`         | array                        | List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default.                                       |
 | `excludeTools`         | array                        | List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server.<br>Note: `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. |
 | `targetAudience`       | string                       | The OAuth Client ID allowlisted on the IAP-protected application you are trying to access. Used with `authProviderType: 'service_account_impersonation'`.                                                                                                         |
@@ -481,7 +489,7 @@ qwen mcp add [options] <name> <commandOrUrl> [args...]
 | `-e`, `--env`               | Set environment variables.                                          | —                                      | `-e KEY=value`                                                     |
 | `-H`, `--header`            | Set HTTP headers for SSE and HTTP transports.                       | —                                      | `-H "X-Api-Key: abc123"`                                           |
 | `--timeout`                 | Set connection timeout in milliseconds.                             | —                                      | `--timeout 30000`                                                  |
-| `--trust`                   | Trust the server (bypass all tool call confirmation prompts).       | — (`false`)                            | `--trust`                                                          |
+| `--trust`                   | Trust the server; skip confirmations in trusted workspaces.         | — (`false`)                            | `--trust`                                                          |
 | `--description`             | Set the description for the server.                                 | —                                      | `--description "Local tools"`                                      |
 | `--include-tools`           | A comma-separated list of tools to include.                         | all tools included                     | `--include-tools mytool,othertool`                                 |
 | `--exclude-tools`           | A comma-separated list of tools to exclude.                         | none                                   | `--exclude-tools mytool`                                           |

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: