@qwen-code/qwen-code 0.16.0-preview.0 → 0.16.1

package/bundled/qc-helper/docs/features/auto-mode.md

@@ -0,0 +1,263 @@
+# Auto Mode
+
+Auto Mode uses an LLM classifier to evaluate each tool call and decide
+whether to auto-approve it. It sits between Auto-Edit (which only
+auto-approves file edits) and YOLO (which auto-approves everything).
+
+This page is the reference for configuring and troubleshooting Auto Mode.
+For an introduction, see the
+[Approval Mode overview](./approval-mode.md#4-auto-mode---classifier-driven-approval).
+
+## How it works
+
+When you're in Auto Mode and the agent tries to run a tool, Qwen Code
+walks three layers in order:
+
+1. **acceptEdits fast-path** — Edit / Write whose target path is inside
+   the workspace is auto-approved without invoking the classifier.
+2. **Safe-tool allowlist** — Read-only and metadata-only built-in tools
+   (Read, Grep, Glob, LS, LSP, TodoWrite, AskUserQuestion, etc.) are
+   auto-approved without invoking the classifier.
+3. **LLM classifier** — Everything else (shell commands, web fetches,
+   sub-agent spawns, edits outside the workspace, MCP tools) is sent to
+   a two-stage classifier:
+   - **Stage 1 (fast)** — outputs `{ shouldBlock }` only. Around ~300ms.
+     If `shouldBlock` is `false`, the action is allowed and the call
+     proceeds.
+   - **Stage 2 (thinking)** — only runs when Stage 1 said block. Uses
+     chain-of-thought review to reduce Stage 1 false positives. Can
+     downgrade Stage 1's block to allow. Outputs the user-visible
+     `reason` on block.
+
+The classifier uses your configured fast model
+(`/model --fast`). If no fast model is configured, the main session
+model is used instead.
+
+## Hard rules still win
+
+Auto Mode does **not** replace hard permission rules. Before the classifier
+runs:
+
+- `permissions.deny` rules block the action with the rule's reason. The
+  classifier never sees it.
+- `permissions.allow` rules with specific specifiers (e.g.
+  `Bash(git status)`, `Read(./docs/**)`) still auto-allow without the
+  classifier.
+- `permissions.ask` rules force manual confirmation even in Auto Mode.
+
+## Over-broad allow rules are stripped while in Auto Mode
+
+Rules like the following would let the agent execute arbitrary code
+without classifier review:
+
+- `Bash` / `Bash(*)` / `Bash()` — auto-allow every shell command
+- `Bash(python:*)`, `Bash(node*)`, `Bash(bash*)` — interpreter wildcards
+- `Agent` / `Agent(coder)` — any allow on the Agent tool
+- `Skill` / `Skill(pdf)` — any allow on the Skill tool
+
+When you enter Auto Mode, Qwen Code temporarily removes these rules from
+the active permission set and prints a notice listing them. The rules
+come back the moment you leave Auto Mode. `settings.json` is never
+modified.
+
+If you genuinely need these broad rules, use YOLO mode instead.
+
+## Configuring hints
+
+Auto Mode reads `permissions.autoMode` from your `settings.json`. The
+entries are natural-language descriptions, not rule patterns — they are
+injected additively into the classifier's system prompt alongside the
+built-in defaults.
+
+```json
+{
+  "permissions": {
+    "autoMode": {
+      "hints": {
+        "allow": [
+          "Running poetry install and poetry update in this Python project",
+          "Cleaning build artifacts under ./dist or ./build",
+          "Reading any file under /Users/me/code/"
+        ],
+        "deny": [
+          "Any network call to intranet.example.com endpoints",
+          "Modifying anything under ~/.ssh or ~/.aws",
+          "Running migration scripts that touch the production DB"
+        ]
+      },
+      "environment": [
+        "This is a private monorepo with strict commit signing",
+        "Production credentials live in 1Password, never in plain files"
+      ]
+    }
+  }
+}
+```
+
+### Length and count limits
+
+To keep the classifier system prompt small:
+
+- Each entry is capped at 200 characters (longer entries are truncated
+  with a warning).
+- `hints.allow` and `hints.deny` accept up to 50 entries each.
+- `environment` accepts up to 20 entries.
+
+### Layering across settings files
+
+`autoMode` is merged across system / user / workspace settings the same
+way other permission settings are: arrays are concatenated and
+de-duplicated.
+
+## Reading the decision
+
+When the classifier blocks an action, the tool call fails with one of
+the following error texts:
+
+- **`Blocked by auto mode policy: <reason>`** — the classifier judged
+  the action unsafe. The reason comes from Stage 2 of the classifier.
+- **`Auto mode classifier unavailable; action blocked for safety`** —
+  the classifier API was unreachable, timed out, or returned an
+  un-parseable response. This is fail-closed behavior: when in doubt,
+  block.
+
+The main LLM sees the same message in the tool result and adjusts its
+approach (asks you, switches tactic, gives up).
+
+### Classifier reason language
+
+Classifier reasons are produced by the LLM and are not translated. If you
+want non-English reasons, add a hint like
+`Respond reasons in Chinese` to `permissions.autoMode.environment`.
+
+## Fallback to manual approval
+
+Auto Mode protects you from getting stuck:
+
+- After **3 consecutive policy blocks** the next tool call falls back to
+  the standard manual-approval prompt. This catches the case where the
+  agent keeps trying minor variants of a forbidden command.
+- After **2 consecutive unavailable** results (classifier API failures)
+  the next tool call also falls back. This avoids waiting on a broken
+  classifier.
+
+The session itself stays in Auto Mode — only the single fallback call
+goes through manual approval. The counters reset when you approve the
+fallback call or switch modes.
+
+If you find yourself constantly hitting fallback, the most likely causes
+are an outage on the classifier API or hints that need tuning. Switch to
+Default Mode while you investigate.
+
+## Troubleshooting
+
+**"Auto mode keeps blocking my commands"**
+
+Look at the reason in the error message. If the classifier is being too
+conservative for your context, add an entry to
+`permissions.autoMode.hints.allow` describing the pattern in
+natural-language. Examples:
+
+- `"Building Docker images for this project (docker build ...)"`
+- `"Running database migrations against the local test DB"`
+
+**"Auto mode classifier unavailable"**
+
+The classifier API didn't respond. Possible causes:
+
+- Network issue between you and the model endpoint.
+- The configured fast model is no longer available — check `/model --fast`.
+- The transcript is too long and exceeds the fast-model context window.
+
+While diagnosing, switch back to Default Mode: `/approval-mode default`.
+
+**"Falling back to manual approval"**
+
+You've hit either the 3-consecutive-block or 2-consecutive-unavailable
+guard. Approve or reject the prompt as you normally would. After one
+approved fallback the consecutive counter resets.
+
+**The classifier sees sensitive data in my prompts**
+
+Tool inputs are projected through each tool's `toAutoClassifierInput`
+method before they reach the classifier. Long edit content, web fetch
+prompts, and sub-agent prompts are truncated. Tool results (file
+contents, web pages) are never sent to the classifier — only the user's
+text and assistant tool-use calls go through.
+
+If a specific tool is exposing fields you'd rather redact, file an issue
+with the tool name; the projection is per-tool and is meant to be
+tightened over time.
+
+## Limitations
+
+- **Not offline-capable.** The classifier requires an LLM call.
+- **Adds latency on the slow path.** Allowlist + acceptEdits cover most
+  calls without latency, but a `run_shell_command` typically adds
+  ~300ms (fast classifier path) or ~3-5s (slow path with thinking
+  review).
+- **Not a substitute for `deny` rules.** The classifier is best-effort.
+  For commands you're sure should never run, put them in
+  `permissions.deny`.
+- **MCP tools default to conservative blocking.** Third-party MCP tools
+  (`mcp__*`) opt-in to argument forwarding via the
+  `toAutoClassifierInput` override. Tools that have not opted in expose
+  only their name to the classifier — most such calls are
+  conservatively blocked unless you've written an explicit `allow`
+  rule. This is fail-closed by design (credentials and voluminous
+  content do not leak into the classifier LLM). If you trust a
+  specific MCP tool, add `permissions.allow: ["mcp__server__tool"]` so
+  it bypasses the classifier entirely.
+
+## FAQ
+
+**Does Auto Mode send my code to a third party?**
+
+Auto Mode reuses your existing model configuration — same endpoint as
+the main agent. If you've configured Qwen Code to use a self-hosted
+model, the classifier runs against that endpoint too.
+
+**Will my secrets / `.env` contents reach the classifier?**
+
+The classifier sees only what each tool's `toAutoClassifierInput`
+projection exposes:
+
+- `read_file` and other read-only tools: not invoked (they're on the
+  fast-path allowlist).
+- `edit` / `write_file`: file_path plus the first 80 characters of
+  old/new content. Full content is not forwarded.
+- `run_shell_command`: the full command (it has to — that's what the
+  classifier judges).
+- `web_fetch`: the URL only. The prompt field is not forwarded.
+- `agent`: subagent type plus the full prompt. The prompt is the
+  instruction the sub-agent will follow, so the classifier needs it
+  in full to detect attacks that would steer the sub-agent toward
+  destructive actions — same reason `run_shell_command` forwards the
+  full command.
+
+Tool results (the actual content returned by tools) are stripped from
+the classifier transcript entirely.
+
+MCP tools (`mcp__*`) follow a stricter default: their parameters are
+not forwarded unless the MCP tool author explicitly opted in via the
+`toAutoClassifierInput` override. The classifier sees the tool name
+but no arguments, so most MCP calls will be conservatively blocked
+unless the user has written an explicit allow rule. This is fail-
+closed by design — third-party tools should not leak credentials or
+voluminous file content into the classifier LLM without intent.
+
+**Can I disable the first-time information message?**
+
+It only shows once per user-settings file. After dismissal,
+`ui.autoModeAcknowledged: true` is set in your user settings.
+
+**How is this different from Auto-Edit?**
+
+Auto-Edit auto-approves file edits and nothing else — shell commands
+still ask. Auto Mode uses a classifier to also auto-approve safe shell
+commands and other tool calls while still blocking risky ones.
+
+**How is this different from YOLO?**
+
+YOLO auto-approves everything without any review. Auto Mode has the
+classifier in the loop and blocks risky actions.

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

@@ -212,16 +212,17 @@ this setting.
 
 Commands for obtaining information and performing system settings.
 
-| Command     | Description                                     | Usage Examples                   |
-| ----------- | ----------------------------------------------- | -------------------------------- |
-| `/help`     | Display help information for available commands | `/help` or `/?`                  |
-| `/about`    | Display version information                     | `/about`                         |
-| `/stats`    | Display detailed statistics for current session | `/stats`                         |
-| `/settings` | Open settings editor                            | `/settings`                      |
-| `/auth`     | Change authentication method                    | `/auth`                          |
-| `/bug`      | Submit issue about Qwen Code                    | `/bug Button click unresponsive` |
-| `/copy`     | Copy last output content to clipboard           | `/copy`                          |
-| `/quit`     | Exit Qwen Code immediately                      | `/quit` or `/exit`               |
+| Command         | Description                                     | Usage Examples                   |
+| --------------- | ----------------------------------------------- | -------------------------------- |
+| `/help`         | Display help information for available commands | `/help` or `/?`                  |
+| `/status`       | Display version information                     | `/status` or `/about`            |
+| `/status paths` | Display current session file and log paths      | `/status paths`                  |
+| `/stats`        | Display detailed statistics for current session | `/stats`                         |
+| `/settings`     | Open settings editor                            | `/settings`                      |
+| `/auth`         | Change authentication method                    | `/auth`                          |
+| `/bug`          | Submit issue about Qwen Code                    | `/bug Button click unresponsive` |
+| `/copy`         | Copy last output content to clipboard           | `/copy`                          |
+| `/quit`         | Exit Qwen Code immediately                      | `/quit` or `/exit`               |
 
 ### 1.9 Common Shortcuts
 

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

@@ -74,6 +74,7 @@ Create a `SKILL.md` file with YAML frontmatter and Markdown content:
 ---
 name: your-skill-name
 description: Brief description of what this Skill does and when to use it
+priority: 10
 ---
 
 # Your Skill Name
@@ -91,11 +92,13 @@ Qwen Code currently validates that:
 
 - `name` is a non-empty string matching `/^[\p{L}\p{N}_:.-]+$/u` — Unicode letters and digits (CJK / Cyrillic / accented Latin all OK), plus `_`, `:`, `.`, `-`. Whitespace, slashes, brackets and other structurally unsafe characters are rejected at parse time.
 - `description` is a non-empty string
+- `priority` is optional. When present, it must be a finite number. Higher values sort earlier in the `/skills` listing only — slash-command completion (typing `/`) and the `/help` custom commands view stay alphabetical, so a high-priority Skill never reorders built-in commands. Omitted or invalid values are treated as unset, which behaves like `0`.
 
 Recommended conventions:
 
 - Prefer lowercase ASCII with hyphens for shareable names (e.g. `tsx-helper`)
 - Make `description` specific: include both **what** the Skill does and **when** to use it (key words users will naturally mention)
+- Use `priority` sparingly for Skills that should reliably appear before the default alphabetical order in `/skills`. Negative priorities are allowed and sort below unset Skills.
 
 ### Optional: gate a Skill on file paths (`paths:`)
 

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`).