@qwen-code/qwen-code 0.15.12-preview.2 → 0.16.0-nightly.20260522.48b0a8bfc

package/bundled/qc-helper/docs/features/structured-output.md

@@ -0,0 +1,309 @@
+# Structured Output (`--json-schema`)
+
+Constrain the model's final answer to a JSON Schema you supply. Qwen
+Code registers a synthetic terminal tool the model is required to call,
+parses the call's arguments against your schema, and exposes the
+validated payload on stdout (or in the JSON / stream-json result
+envelope). The first valid call ends the run.
+
+Headless only — works with `qwen -p`, a positional prompt, or a prompt
+piped via stdin.
+
+## Quick start
+
+```bash
+qwen --prompt "Summarize the changes in HEAD with risk_level" \
+  --json-schema '{
+    "type": "object",
+    "properties": {
+      "summary":    { "type": "string" },
+      "risk_level": { "type": "string", "enum": ["low", "medium", "high"] }
+    },
+    "required": ["summary", "risk_level"],
+    "additionalProperties": false
+  }'
+```
+
+Output on stdout (default `--output-format text`):
+
+```json
+{ "summary": "…", "risk_level": "low" }
+```
+
+The line is exactly the JSON-stringified payload + newline — no
+envelope, no event log. Pipe it straight into `jq` or another consumer.
+
+In **text** mode, stdout is reserved for the JSON payload on success
+and is empty on failure; error messages and log lines go to stderr.
+That makes `$(qwen --json-schema …) || exit 1` capture patterns safe
+under text mode — failures land in stderr, not mixed into the captured
+variable. The model's incidental prose during planning is **not**
+mirrored to stderr either — text mode discards it; reach for
+`--output-format json` or `stream-json` if you need to see it.
+
+In `--output-format json` and `stream-json`, the failure result
+message is emitted on **stdout** alongside the success path (as the
+final element of the JSON array, or the terminating `result` line on
+the JSONL stream). Not all failure modes emit a result to stdout —
+max-session-turns (exit 53) and signal interrupts (exit 130) exit with
+stderr output only. Check the exit code first; `is_error` on the
+result object disambiguates within the subset of failures that do
+produce a result event.
+
+> **Empty schema:** Passing `{}` produces `{}` (an empty JSON object)
+> on stdout. The model calls `structured_output` with no arguments;
+> the upstream argument-normalisation path turns the empty function
+> call into an empty-object payload, which passes validation against
+> the empty schema and is emitted verbatim.
+
+## Supplying the schema
+
+Two equivalent forms:
+
+```bash
+# Inline JSON literal
+qwen -p "…" --json-schema '{"type":"object", "properties":{…}}'
+
+# Read from a file
+qwen -p "…" --json-schema @./schemas/summary.json
+```
+
+The `@path` form expands `~`, normalizes the path, and reads the file
+with `utf8` encoding.
+
+> **Latency note:** Successful runs incur a shutdown holdback **capped
+> at ~500 ms** while in-flight background agents flush their final
+> notifications before the result is emitted. The holdback exits early
+> if no background tasks are pending, so simple runs barely notice it;
+> batch pipelines that fan out hundreds of `--json-schema` invocations
+> against busy agents should account for this upper bound.
+
+> **Security note:** Schemas may contain user-supplied regular
+> expressions in `pattern` keywords. Ajv compiles these with the
+> ECMAScript regex engine, which is vulnerable to catastrophic
+> backtracking. Because tool arguments are always objects, the
+> `pattern` keyword only fires inside string properties — a malicious
+> schema like
+> `{"type":"object","properties":{"value":{"type":"string","pattern":"(a+)+b"}}}`
+> can hang the CLI when the model supplies a moderately long
+> matching value. Only run `--json-schema` with schemas from sources
+> you trust.
+
+Validation at parse time:
+
+- The file must be a regular file (no FIFOs, character devices, or
+  directories).
+- File size is capped at 4 MiB. Real-world JSON schemas are well under
+  this; multi-MiB files almost always indicate a wrong-path mistake.
+- The schema must be valid JSON. For `@path` input, the parse error is
+  generic ("content of `<path>` is not valid JSON") rather than echoing
+  the SyntaxError detail, so a wrapping process that surfaces stderr
+  can't read a prefix of the file's contents back from the error.
+- The schema must compile under the strict Ajv configuration —
+  typos like `propertees` are surfaced, but spec-valid patterns
+  (e.g. `required` without listing every key in `properties`) are
+  accepted.
+- The schema root must accept object-typed values. Function-calling
+  APIs (Gemini, OpenAI, Anthropic) all require tool arguments to be
+  JSON objects, so a non-object root would register an unusable tool.
+
+The root-acceptance check walks `type`, `const`, `enum`, `anyOf`,
+`oneOf`, `allOf`, `not`, and `if`/`then`/`else` (best-effort for the
+decidable cases). When in doubt it defers to Ajv at runtime.
+
+> **Root `$ref` is rejected** by the parse-time check. If your schema
+> reuses a definition via `$ref`, wrap it in `allOf`:
+>
+> ```jsonc
+> // Rejected:
+> { "$ref": "#/$defs/MyObj", "$defs": { "MyObj": { "type": "object", "properties": { "name": { "type": "string" } } } } }
+>
+> // Accepted (root accepts objects via the allOf branch):
+> { "allOf": [{ "$ref": "#/$defs/MyObj" }], "$defs": { "MyObj": { "type": "object", "properties": { "name": { "type": "string" } } } } }
+> ```
+>
+> `$ref` inside `anyOf` / `oneOf` / `allOf` is deferred to Ajv at
+> runtime, so the wrapped form passes the root-acceptance check.
+
+## Output shape per format
+
+| `--output-format` | What goes to stdout                                                                                                                                                                                                   |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `text` (default)  | `JSON.stringify(payload) + "\n"` — one line, the validated object.                                                                                                                                                    |
+| `json`            | A single JSON **array** of message objects (the full event log). The final element is the `type: "result"` message, which carries both `result` (`JSON.stringify(payload)`) and `structured_result` (the raw object). |
+| `stream-json`     | Each event on its own line as JSONL. The terminating `result` line carries `result` (stringified) and `structured_result` (raw object).                                                                               |
+
+In both JSON formats, prefer reading `structured_result` over `result`
+when you want the object; `result` is the stringified form provided for
+consumers that always expect a string in that field. For `--output-format
+json`, read the last element of the array and pull `structured_result`
+from there (e.g. `jq '.[-1].structured_result'`); for `stream-json`,
+read the final `type: "result"` line on the stream.
+
+## Restrictions
+
+| Combination                                       | Behavior                                                                                                                                                                                                                     |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--json-schema` + `-i` / `--prompt-interactive`   | Rejected at parse time. The synthetic tool's "session ends now" message has no terminator in the TUI loop.                                                                                                                   |
+| `--json-schema` + `--input-format stream-json`    | Rejected at parse time. The single-shot terminal contract is incompatible with the long-lived stream-json input protocol.                                                                                                    |
+| `--json-schema` + `--acp` / `--experimental-acp`  | Rejected at parse time. ACP runs its own turn loop that doesn't honor the synthetic-tool terminal contract.                                                                                                                  |
+| `--json-schema` with no prompt and no piped stdin | Rejected at parse time. Headless mode needs a prompt — pass `-p`, a positional argument, or pipe one in.                                                                                                                     |
+| `--bare` + `--json-schema`                        | Supported. The synthetic tool is registered alongside the bare three (`read_file`, `edit`, `run_shell_command`).                                                                                                             |
+| `--json-schema` inside a subagent                 | Tool is NOT registered. Only the main / drain turns of the top-level run honor the terminal contract; a subagent calling the tool would receive "session ends now" and then keep running because its loop has no terminator. |
+
+## Retry and failure modes
+
+> **Cost note.** Two things multiply token spend in a `--json-schema`
+> run, both worth designing for:
+>
+> - **Schema embedded in every turn.** The schema ships as the
+>   `structured_output` function declaration's `parameters` block on
+>   every model request, not just the first. Large schemas (up to the
+>   4 MiB parse cap) proportionally increase per-turn input tokens
+>   for the entire run.
+> - **Each validation retry is a full model turn.** A schema the
+>   model misses repeatedly is multiplied per failure (request +
+>   inference + response). Keep schemas constrained enough to guide
+>   the model and simple enough to nail on the first try; raise
+>   `--max-session-turns` when retries are expected.
+
+The session ends on the first valid call. Until then:
+
+- **Args fail validation.** `structured_output` returns a tool-result
+  error with Ajv's message, the model sees it on the next turn, and
+  may correct the arguments and call again.
+- **Model calls a side-effecting tool in the same turn as
+  `structured_output`.** The pre-scan suppresses the sibling — it
+  never runs, regardless of whether the structured call ultimately
+  validates. The two paths split on what the model sees next:
+  - **Validation succeeds:** the run ends immediately, and the model
+    never gets another turn — the suppressed sibling is silently
+    discarded.
+  - **Validation fails:** the model gets another turn and sees a
+    synthesised "Skipped:" `tool_result` for the suppressed call,
+    so it can re-issue that call in a **separate turn** (one that
+    does not include `structured_output`).
+- **Model emits plain text instead of calling
+  `structured_output`.** Exit code `1`. The error message includes
+  the turn count and a truncated preview of the model's output so
+  you can see what it actually said.
+- **Run reaches `maxSessionTurns`.** Exit code `53`. Standard
+  "Reached max session turns" exit, plus a `--json-schema`-specific
+  hint that points at the three common stuck-run causes: model never
+  called the tool, `structured_output` is denied by permission rules,
+  or the schema is unsatisfiable.
+- **Run is interrupted (SIGINT / Ctrl-C).** Exit code `130`. The
+  structured result is normally not emitted, but the shutdown
+  holdback loop does not poll the abort signal, so a SIGINT that
+  arrives after a successful call has been captured but before the
+  result reaches stdout may still land on stdout. Treat the exit
+  code as the source of truth.
+
+## Privacy
+
+The args you submit through `structured_output` ARE the structured
+payload — already emitted on stdout. To avoid persisting the same
+payload a second time into on-device surfaces that may be exported off
+the machine, args are redacted with the placeholder
+`{ __redacted: 'structured_output payload (see stdout result)' }` on:
+
+- The `ToolCallEvent` telemetry path (OTLP exports, QwenLogger,
+  ui-telemetry stream, chat-recording UI event mirror).
+- The on-disk chat-recording JSONL at
+  `~/.qwen/projects/<sanitized-cwd>/chats/<sessionId>.jsonl` (re-fed
+  into model context on `--continue` / `--resume`), including every
+  validation-failure retry.
+
+Tool-call metrics (duration, success, decision) and surrounding event
+metadata are preserved.
+
+> **Schema is sent to the model provider.** Redaction covers the
+> _call arguments_ on local surfaces only. The schema itself rides
+> on every model request as the `structured_output` function
+> declaration's `parameters` block — so any literal values you put
+> inside it (`enum`, `const`, `default`, `examples`, `description`,
+> `$comment`, etc.) reach the provider in cleartext just like prompt
+> text. Schemas should describe shape and constraints; treat them as
+> public toward the provider and keep secrets, customer records, and
+> other sensitive payloads out of the schema body.
+
+> **Hooks see raw args.** The redaction described above only applies
+> to telemetry and chat-recording. `PreToolUse`, `PostToolUse`, and
+> `PostToolUseFailure` hooks (including HTTP hooks that can forward
+> payloads off-device) receive the unredacted `tool_input` for
+> `structured_output`, since the hook contract is "see what the tool
+> sees." If you operate audit-style catch-all hooks, either disable
+> them for `structured_output` (filter on `tool_name`) or add
+> hook-side redaction before running `--json-schema` against
+> sensitive data.
+
+## Session resumption (`--continue` / `--resume`)
+
+`--json-schema` is a per-run flag, not a per-session property. The
+synthetic tool is registered when the CLI parses its arguments, so:
+
+- Re-pass `--json-schema` on every `--continue` / `--resume` you want
+  the terminal contract to apply to. The same schema as the original
+  run is the safe default — a mid-session schema swap is allowed but
+  changes the contract the model is being held to.
+- If you `--continue` without `--json-schema`, the resumed run is an
+  ordinary headless session: `structured_output` simply doesn't
+  exist as a tool, and the model will respond in free-form text.
+- The `__redacted` placeholder in the resumed chat-recording does
+  not affect resumability in practice. A successful `structured_output`
+  call terminates the session immediately, so the only redacted args
+  a resumed run could see are from failed attempts. The model still
+  has each attempt's Ajv validation error in the recorded `tool_result`
+  and the live parameter schema (re-registered from `--json-schema`),
+  which is enough to retry.
+
+## Permission gating
+
+`structured_output` deliberately bypasses the `--core-tools` allowlist:
+the tool only exists when `--json-schema` is set, so excluding it
+would leave the run with no terminal contract.
+
+Explicit `permissions.deny` rules and `--exclude-tools` settings DO
+take effect — both use the same deny mechanism and both prevent
+`structured_output` from being registered, so the model never sees
+the tool declaration. The typical result is that the model answers in
+plain text (exit 1). If the model loops through other tools without
+ever producing text, it will eventually hit `maxSessionTurns`
+(exit 53) and the `--json-schema` hint in the error message tells you
+where to look.
+
+> **`--bare` caveat.** Bare mode ignores most settings-derived inputs,
+> including settings-level `permissions.deny` and `tools.exclude`. The
+> synthetic tool stays registered, so a settings-only deny of
+> `structured_output` will silently no-op under `--bare`. Argv-level
+> `--exclude-tools structured_output` still applies in bare mode — use
+> the flag rather than settings if you need to lock down a bare run.
+
+## Conflict with MCP tools
+
+If an MCP server registers a tool literally named `structured_output`,
+the tool-registry collision check renames the MCP tool to
+`mcp__<server-name>__structured_output` so the synthetic tool keeps
+the bare name. The user-supplied schema is always the one the model
+sees.
+
+## Example: gating a multi-step run on the structured output
+
+```bash
+RESULT=$(qwen --prompt "Audit this diff and rate its risk." \
+  --json-schema @./schemas/audit.json) || exit 1
+
+risk=$(jq -r '.risk_level' <<<"$RESULT")
+if [ "$risk" = "high" ]; then
+  echo "High-risk diff; pausing pipeline." >&2
+  exit 2
+fi
+```
+
+## See also
+
+- [Headless Mode](headless.md) — the `-p`-based flow `--json-schema`
+  builds on.
+- [Dual Output](dual-output.md) — records a JSON-event sidecar
+  alongside the TUI (a different approach to machine-readable output;
+  does not require `--json-schema`).

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

@@ -134,7 +134,7 @@ Subagents are configured using Markdown files with YAML frontmatter. This format
 ---
 name: agent-name
 description: Brief description of when and how to use this agent
-model: inherit # Optional: inherit or model-id
+model: inherit # Optional: inherit, fast, modelId, or authType:modelId
 approvalMode: auto-edit # Optional: default, plan, auto-edit, yolo
 tools:         # Optional: allowlist of tools
   - tool1
@@ -151,10 +151,48 @@ Multiple paragraphs are supported.
 
 Use the optional `model` frontmatter field to control which model a subagent uses:
 
-- `inherit`: Use the same model as the main conversation
-- Omit the field: Same as `inherit`
-- `glm-5`: Use that model ID with the main conversation's auth type
-- `openai:gpt-4o`: Use a different provider (resolves credentials from env vars)
+- `inherit`: Use the same model as the main conversation.
+- Omit the field: Same as `inherit`.
+- `fast`: Use the configured `fastModel`. If no valid fast model is configured,
+  the subagent falls back to `inherit`.
+- `glm-5`: Use that model ID. Qwen Code first checks the main conversation's
+  auth type; if the model is not available there, it can resolve the model from
+  another configured provider.
+- `openai:gpt-4o`: Use an explicit provider and model ID. This is useful when a
+  subagent should run on a model registered under a different auth type from the
+  main conversation.
+
+For example:
+
+```
+---
+name: fast-reviewer
+description: Reviews small diffs with the configured fast model
+model: fast
+tools:
+  - read_file
+  - grep_search
+---
+```
+
+```
+---
+name: openai-researcher
+description: Uses an OpenAI-compatible provider for research tasks
+model: openai:gpt-4o
+tools:
+  - read_file
+  - grep_search
+  - glob
+---
+```
+
+The `fast` selector uses the same `fastModel` setting configured in
+`settings.json` or with `/model --fast`. That setting may itself refer to a
+model under another configured auth type, such as `openai:deepseek-v4-flash`.
+When the selector resolves to another auth type, Qwen Code creates a dedicated
+runtime provider for that subagent request and sends the provider only the bare
+model ID.
 
 #### Permission Mode
 
@@ -620,6 +658,10 @@ Always follow these standards:
 
 - **Tool Restrictions**: Use `tools` to limit which tools a subagent can access, or `disallowedTools` to block specific tools while inheriting everything else
 - **Permission Mode**: Subagents inherit their parent's permission mode by default. Plan-mode sessions cannot escalate to auto-edit through delegated agents. Privileged modes (auto-edit, yolo) are blocked in untrusted folders.
+- **Provider Selection**: A subagent with `model: authType:modelId`, or
+  `model: fast` where `fastModel` resolves to another auth type, sends that
+  subagent's model requests to the selected provider. Make sure that provider is
+  appropriate for the subagent's task and data.
 - **Sandboxing**: All tool execution follows the same security model as direct tool use
 - **Audit Trail**: All Subagents actions are logged and visible in real-time
 - **Access Control**: Project and user-level separation provides appropriate boundaries