@qwen-code/qwen-code 0.23.2 → 0.23.3-nightly.20260910.c46cb85cf2

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

@@ -36,7 +36,7 @@ These commands help you save, restore, and summarize work progress.
 
 > [!note]
 >
-> Opening an HTML export loads the renderer for that exact Qwen Code version from `unpkg.com`. If the version has not been published or the renderer cannot be reached, the file shows a load error. Markdown, JSON, and JSONL exports remain self-contained.
+> Opening an HTML export loads the renderer and stylesheet for that exact Qwen Code version from `unpkg.com`. If the version has not been published or either asset cannot be reached, the file shows a load error. Markdown, JSON, and JSONL exports remain self-contained.
 
 > [!note]
 >
@@ -757,12 +757,11 @@ qwen sessions list --json | jq .
 
 #### `qwen sessions ps`
 
-Lists the interactive Qwen Code sessions running on this machine right
-now. `sessions list` walks saved transcripts ("what have I worked on");
-this walks the live-process registry ("what is running at this moment").
-Records left behind by a killed session are swept as they are found.
-Headless sessions (`qwen -p`) do not register with the live-process
-registry, so they are not shown.
+Lists the Qwen Code sessions registered on this machine right now.
+`sessions list` walks saved transcripts ("what have I worked on"); this
+walks the live-process registry ("what is running at this moment").
+Records left behind by a killed session are swept as they are found. A
+one-shot `qwen -p` run never registers, so it is never shown.
 
 **Flags:**
 
@@ -772,7 +771,19 @@ registry, so they are not shown.
 
 **Human-readable output (default):**
 
-A table with columns: NAME, PID, AGE, DIRECTORY.
+A table with columns: NAME, KIND, PID, AGE, DIRECTORY.
+
+KIND says what registered the session — `tui` for someone at a terminal,
+`external` for a program that is not a Qwen Code session at all (a voice
+front-end, a relay), and `headless` or `serve` for a session another
+program drives. Several `serve` or `headless` rows can share one PID: a
+`qwen --acp` child hosts all its sessions in one process — `serve` when
+the daemon spawned it, `headless` when a client is driving it directly —
+and each of them registers separately. It is a self-report, like NAME and DIRECTORY: every field
+here was written by the process it describes, and nothing about what a
+session is allowed to do depends on it. See
+[Cross-Session Protocol](./cross-session-protocol.md) for the record
+format and for how to register a program of your own.
 
 **JSON output (`--json`):**
 
@@ -781,7 +792,7 @@ object with fields:
 
 ```
 schemaVersion, pid, procStart, pidNs, sessionId, cwd, name, startedAt,
-qwenVersion, ipcPath (when peer messaging is available)
+qwenVersion, kind, ipcPath (when peer messaging is available)
 ```
 
 Nothing else is written to stdout — an empty listing prints nothing at
@@ -1018,3 +1029,40 @@ on your behalf.
 Anyone who holds the token can send as that controller, so treat it like
 any other credential: give it to one program, keep it out of shared
 config, and revoke it when that program is done.
+
+### Sessions a program drives over ACP
+
+Any `qwen --acp` child registers each session it hosts — as `serve` when
+the daemon spawned the process, as `headless` when an editor or another
+client is driving `qwen --acp` directly — and the session appears in
+`qwen sessions ps` and in another session's `list_agents` like any
+other. It can send: its model can call `send_message` to reach a terminal
+you have open. Several of them share one process and one inbox, so a
+sender has to name the session it means — every Qwen Code session does
+that automatically.
+
+Messages sent _to_ one are refused rather than held. Holding is a
+question put to a person, and nobody is watching a held-message list on a
+driven session's behalf; a sender is told at once instead of
+waiting out an expiry. Where a held message should surface for those
+sessions is not settled yet.
+
+A session registers only while its own settings have
+`agents.crossSessionMessaging` on. With it off it stays invisible,
+because the only reason to list a session nobody can message would be to
+advertise an address that never answers.
+
+### Programs that are not Qwen Code sessions
+
+Everything above works between sessions, but nothing in it is specific to
+one. A program that writes a registry record for itself and binds an
+inbox the same way is listed by `qwen sessions ps` and by `list_agents`,
+can be addressed by name from `send_message`, and receives delivery
+receipts for what it sends — a voice front-end, a relay, a build watcher.
+It should record `kind: "external"` so a listing can say what it is.
+
+[Cross-Session Protocol](./cross-session-protocol.md) is the contract for
+writing one: the record schema and how liveness is judged, the socket
+paths and framing, the auth line, every frame field, the receipt states
+and their transitions, and what a receiver does with a message before its
+model sees it.

package/bundled/qc-helper/docs/features/computer-use.md

@@ -26,7 +26,7 @@ When first used, the skill runs these commands itself:
 
 ```bash
 qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.3
-npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.4
+npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.5
 ```
 
 Restart Qwen Code after the MCP server is first added. The skill then resumes

package/bundled/qc-helper/docs/features/cross-session-protocol.md

@@ -0,0 +1,320 @@
+# Cross-Session Protocol
+
+This page is the contract for a program that wants to take part in
+cross-session messaging without being a Qwen Code session: a voice
+front-end, a relay daemon, a script that watches a build. It describes
+what a session writes to the registry, what its inbox reads off a
+connection, and what it sends back. Everything here is what the code
+does today at schema version 1 and frame version 1; the last section
+says what may change and how you will know.
+
+Every value that crosses a process boundary is untrusted on arrival and
+validated by the reader. Where this page says a field "must" have some
+shape, a value that does not is dropped, never rejected with an error.
+
+## 1. The session registry
+
+A running session publishes one record:
+
+```
+$QWEN_HOME/sessions/<pid>.json            (directory 0700, file 0600)
+$QWEN_HOME/sessions/<pid>-<8 hex>.json    (a process hosting several sessions)
+```
+
+`$QWEN_HOME` defaults to `~/.qwen`. The file name is keyed by the
+writer's PID — either the bare PID, or the PID, a dash, and eight
+lowercase hex characters minted at registration (see "Several records
+from one process" below). A record whose `pid` field disagrees with the
+PID prefix of its file name — compared in canonical decimal form, so a
+zero-padded name agrees with nothing — is ignored.
+
+```json
+{
+  "schemaVersion": 1,
+  "pid": 41337,
+  "procStart": "a1b2c3d4-…-boot-uuid:8895124",
+  "pidNs": 4026531836,
+  "sessionId": "8e016be8-5b48-4c13-ad22-1f5326ae64ac",
+  "cwd": "/home/me/project",
+  "name": "project-3f",
+  "startedAt": 1788959000000,
+  "qwenVersion": "0.23.0",
+  "kind": "tui",
+  "ipcPath": "/run/user/1000/qwen-socks/41337.sock",
+  "ipcToken": "c0ffee…64 hex…"
+}
+```
+
+| Field           | Meaning                                                                                                                                                                                                                                                                                               |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schemaVersion` | Always `1`. A reader skips a record with a higher version and never deletes it.                                                                                                                                                                                                                       |
+| `pid`           | The writer's process id. Must equal the PID the file name is keyed by: the whole name for the bare form, the digits before the `-<8 hex>` suffix for the minted one.                                                                                                                                  |
+| `procStart`     | `<boot id>:<process start ticks>` on Linux (`/proc/sys/kernel/random/boot_id` and field 22 of `/proc/<pid>/stat`); `null` elsewhere. Guards against PID reuse, and against records written on another machine that shares this home directory.                                                        |
+| `pidNs`         | Inode number of `/proc/self/ns/pid` on Linux; `null` elsewhere. A reader only lists and sweeps records from its own namespace.                                                                                                                                                                        |
+| `sessionId`     | The session's id. `/clear` and `/resume` swap it under the same PID, so re-read the record before each send.                                                                                                                                                                                          |
+| `cwd`           | Working directory at registration.                                                                                                                                                                                                                                                                    |
+| `name`          | Display name. Derived from the cwd basename (Unicode letters, marks, digits, `.`, `_`, `-`; up to 32 code points) plus `-` and the first two hex characters of `sha256(sessionId)`, unless the writer chose one. Not unique.                                                                          |
+| `startedAt`     | Epoch milliseconds. Newest first is the listing order and the tie-break between twins.                                                                                                                                                                                                                |
+| `qwenVersion`   | Free text or `null`.                                                                                                                                                                                                                                                                                  |
+| `kind`          | What registered: `tui` (someone at a terminal), `headless`, `serve`, `external`. Lowercase ASCII, digits and dashes, at most 16 characters; anything else is dropped on read. Absent means a writer older than the field, which reads as `tui`. A label for listings — never a credential; see below. |
+| `ipcPath`       | The inbox socket, present only while it is bound. Absent means discoverable but not messageable.                                                                                                                                                                                                      |
+| `ipcToken`      | 64 hex characters. What a connection to `ipcPath` presents on its auth line. Absent means the inbox requires none (records from older builds).                                                                                                                                                        |
+
+**A record is a self-report.** Every field in it was written by the
+process it describes, so `name`, `cwd` and `kind` are claims, not facts a
+reader can lean on. Nothing that decides what a sender may do reads
+them — that is settled by what a connection presents (§3) and by the
+receiving session's own policy (§6). Set `kind` so a listing can group
+sessions honestly; do not expect it to buy you anything.
+
+**Writing your own record.** An external process that wants to be
+found — listed by `qwen sessions ps`, addressable from `send_message`,
+able to receive receipts — writes the same record for itself: its own
+`pid`, `procStart` and `pidNs` computed the same way, a `sessionId` it
+mints (any UUID), `kind: "external"`, a `name` (yours, or derived the
+same way; it is flattened to one line and bounded when displayed), and
+`ipcPath` + `ipcToken` for an inbox it binds itself (§2). Write to a
+temp file in the same directory and `rename` over the target; create the
+file 0600; refuse to write through a symlink. Remove the record on exit.
+A record whose process is gone is swept by the next session that lists,
+but only when `procStart` proves the PID is not merely reused.
+
+**Reading.** Anything that can read the directory can read every record,
+including tokens: being able to discover a session and being able to
+authenticate to it are one capability by design. Do not print
+`ipcToken` anywhere a model or a log can see it.
+
+**Liveness.** A record is live when all of these hold: the file name is
+`<pid>.json` or `<pid>-<8 hex>.json` and its PID prefix equals `pid`;
+`pidNs` equals the reader's; the boot id inside
+`procStart` equals the reader's (or `procStart` is `null`); and the PID
+is alive with the same start ticks. A live record with an `ipcPath`
+still has to be dialed before it is advertised as reachable — a socket
+file outlives a crash.
+
+**Refs.** Displayed handles use `ref = sha256(sessionId)[0:6]`. Two
+sessions may share a `name`; the address grammar a sender types is
+`name`, `name [ref]`, `[ref]` or the bare `ref`, and an ambiguous
+`name` is an error rather than a guess.
+
+**Several records from one process.** Any `qwen --acp` child — spawned
+by the daemon, or driven directly by an editor or another client —
+writes one record per session, named `<pid>-<8 hex>.json`, from its
+first session on. The suffix is minted at
+registration and never changes; a session id swapped underneath is a
+patch to the record, not a rename of it. Every one of them carries the
+same `ipcPath`, because the process binds one inbox for all its sessions
+and tells them apart by the `toSessionId` on each frame — so **always
+send `toSessionId`**: a frame without one that reaches such a process is
+answered `misaddressed`, since there is no single session it could have
+meant. Liveness, sweeping and the namespace and boot guards read the
+record exactly as they do for the bare name; only the PID/filename
+agreement check differs, and only in comparing `pid` against the digits
+before the suffix rather than the whole name.
+
+## 2. The inbox socket
+
+One UNIX domain socket per session, at the first of these that binds:
+
+1. `$XDG_RUNTIME_DIR/qwen-socks/<pid>.sock`
+2. `$TMPDIR/qwen-socks-<16 hex>/<pid>.sock`
+3. `/tmp/qwen-socks-<16 hex>/<pid>.sock`
+
+The directory is 0700 and the socket 0600. A path longer than 103 bytes
+is skipped. When the PID-keyed name is already held by a live listener
+(two PID namespaces sharing a runtime directory), the session binds
+`<pid>-<8 hex>.sock` next to it instead. Peers never derive a socket
+path; they read `ipcPath` from the record.
+
+A connection carries newline-delimited JSON, one object per line, UTF-8.
+A single line longer than 1 MiB (measured in UTF-16 code units) drops
+the connection. A connection that goes 30 seconds without completing a
+line that parses is dropped; junk lines do not extend the deadline. The
+listener accepts at most 64 connections at once.
+
+The expected exchange is one message per connection: connect, write the
+auth line and the frame in one write, half-close, wait for the peer to
+close. The receiver never writes on the same connection; anything it
+has to say comes back as a separate connection to your own `ipcPath`.
+
+## 3. The auth line
+
+When the target record has an `ipcToken`, the first line must be:
+
+```json
+{ "msgV": 1, "type": "auth", "token": "<token>" }
+```
+
+Three kinds of token are accepted, and the inbox remembers which one it
+saw:
+
+| Presented                                                                     | The inbox concludes            | Effect                                                                           |
+| ----------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------- |
+| The `ipcToken` from the target's registry record                              | an ordinary peer               | subject to policy and mode parity (§6)                                           |
+| `QWEN_CODE_MESSAGING_TOKEN` from the target's own environment                 | a process that session started | delivered under the parity default; `origin="own-process"`                       |
+| A controller token `qpc_<64 hex>` minted with `qwen sessions controllers add` | a program the user trusts      | delivered under the parity default; `origin="controller"` with the grant's label |
+
+A first line that is not an auth line, or that presents a token matching
+none of the three, drops the connection silently. When the record has no
+`ipcToken`, do not send an auth line; an older inbox reads it as an
+unknown frame type and skips it, so leading with one is always safe.
+
+Nothing here authenticates the _sender_: a token proves the connection is
+allowed, not who opened it. `from`, `fromName`, `fromMode` and every
+field of the record are claims.
+
+This is also the whole of the trust model. A program the user wants
+driving their sessions gets a controller token, minted by hand and given
+to that one program; it is what makes the difference between a message
+that is delivered and one that waits for review. Writing
+`kind: "external"` or a familiar-looking `name` buys nothing.
+
+## 4. The user frame
+
+```json
+{
+  "msgV": 1,
+  "msgId": "5f1d0c9e-3b2a-4e8f-9c7d-1a2b3c4d5e6f",
+  "type": "user",
+  "from": "/run/user/1000/qwen-socks/40011.sock",
+  "replyToken": "<my own ipcToken>",
+  "fromName": "project-3f",
+  "fromMode": "prompting",
+  "toSessionId": "8e016be8-…",
+  "priority": "next",
+  "message": { "role": "user", "content": "build finished, 0 failures" }
+}
+```
+
+| Field         | Rule                                                                                                                                                                                                                          |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `msgV`        | Number. Must be ≤ 1; higher is dropped.                                                                                                                                                                                       |
+| `msgId`       | `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`, and must not canonicalize (dashes stripped, lower-cased) to `all`. Use a fresh UUID per message: the receiver remembers ids it has settled and repeats the old verdict for a re-sent one. |
+| `type`        | `"user"`.                                                                                                                                                                                                                     |
+| `from`        | Your `ipcPath`, if you have one. Where receipts go. Absent means no receipts.                                                                                                                                                 |
+| `replyToken`  | Your `ipcToken`, so the receiver can authenticate its receipts to you.                                                                                                                                                        |
+| `fromName`    | Display name; flattened to one line, at most 200 characters.                                                                                                                                                                  |
+| `fromMode`    | `"prompting"` (a person reviews each action) or `"bypass"` (some actions apply without review). Absent means "asserts nothing", which is held for review (§6).                                                                |
+| `toSessionId` | The `sessionId` you read from the record. A receiver holding a different id answers `misaddressed`. Always send it.                                                                                                           |
+| `priority`    | `"now"` or `"next"`; anything else reads as `"next"`. Carried for a future interrupt path; today the receiver queues both for the next turn.                                                                                  |
+| `message`     | `role` must be `"user"`; `content` a non-empty string.                                                                                                                                                                        |
+
+Unknown fields are ignored.
+
+## 5. The delivery-status frame
+
+The receiver reports what became of a message with one control frame per
+outcome, sent to the message's `from` and authenticated with its
+`replyToken`:
+
+```json
+{
+  "msgV": 1,
+  "msgId": "<fresh id>",
+  "type": "control",
+  "action": "delivery_status",
+  "status": "held",
+  "origMsgId": "5f1d0c9e-…",
+  "from": "/run/user/1000/qwen-socks/41337.sock",
+  "reason": "Your message is held for the recipient user to review …"
+}
+```
+
+| `status`       | When                                                                                                                                                      | What to do                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `held`         | Parked for the user to review. Repeated on a retry, and on a release that could not be queued.                                                            | Wait; a decision or an expiry follows.                                             |
+| `delivered`    | Queued for the model.                                                                                                                                     | Nothing. Not proof it was read.                                                    |
+| `denied`       | A person reviewed it and said no.                                                                                                                         | Do not re-send.                                                                    |
+| `refused`      | The session's policy turns peer messages away; nobody saw it. Only ever the first receipt.                                                                | Stop; reach that user another way.                                                 |
+| `expired`      | A held message ran out its wait, the session exited with it unread, or it arrived while that session was shutting down. Can follow `held` or `delivered`. | Re-send later if it still matters.                                                 |
+| `misaddressed` | `toSessionId` does not match the session at that address.                                                                                                 | Re-read the registry.                                                              |
+| `dropped`      | The inbox turned it away before any policy ran (§6).                                                                                                      | Treat as unsent. Do not retry in a loop; fold what matters into one later message. |
+
+A `dropped` receipt carries two more fields. `dropReason` is
+`rate-limited`, `duplicate` or `queue-full`. `droppedMsgIds` lists up to
+256 further ids the same receipt settles: a burst is answered with one
+receipt rather than one each, so a sender moves every message it lost to
+a terminal state from a single frame. Both are meaningless on any other
+status and are ignored there.
+
+`reason` is free text for a human. Order of receipts is not guaranteed
+across connections; apply them as state transitions:
+
+```
+pending   → held | delivered | denied | refused | expired | misaddressed | dropped
+held      → delivered | denied | expired | misaddressed
+delivered → expired | misaddressed
+```
+
+Anything else is a repeat and should be ignored. A receipt for an id you
+never sent is noise; ignore it. Receipts are best-effort on the
+receiver's side: a full outbound limit or a dead `from` loses them
+silently, so a sender must tolerate never hearing back.
+
+Your own inbox receives these frames from the sessions you messaged. If
+you only ever send, bind an inbox and give `from` anyway: without one you
+are blind to every outcome above.
+
+## 6. What the receiver does with a message
+
+In order:
+
+1. **Admission.** Per sender: a burst of 30, then one message every two seconds. All senders together: a burst of 32, then one a second — a sender names itself on the frame, so rotating that name buys a fresh allowance from the first limit but not the second. The same body from another session inside 30 seconds is a `duplicate`; a process the session started and a trusted controller are exempt from that check, and rate-limited like everyone else. A dropped message is never held, never delivered, and leaves no record, so a sender that waits out its burst and retries still lands.
+2. **Settled ids.** A `msgId` the gate already decided repeats its earlier verdict.
+3. **Policy.** `agents.crossSessionInbound` set to `accept`, `hold` or `refuse` wins. Unset: a process the session started or a trusted controller is accepted; otherwise a message is accepted only when `fromMode` names the same review class the receiver is in, and held in every other case, including when `fromMode` is absent.
+4. **Hold.** Up to 50 messages wait. A message arriving at a full buffer is `dropped` with `queue-full` rather than evicting one already parked. A held message expires after `agents.crossSessionHeldExpiry` (`1m`, `5m`, `10m`, `never`; default `5m`). The user releases or denies from `/peers`; a mode change re-evaluates the backlog.
+5. **Queue.** An accepted message joins the session's input queue, which holds at most 50 from peers. A full queue is `dropped` with `queue-full` too.
+
+A sender does not have to discover the limits the hard way: a Qwen Code
+session mirrors them per address and refuses its own send before writing
+it, telling its model to batch instead.
+
+The model sees a delivered message as:
+
+```
+<cross_session_message from="/run/user/1000/qwen-socks/40011.sock" name="project-3f">
+build finished, 0 failures
+</cross_session_message>
+```
+
+followed by a notice stating the sender's authority. `origin="own-process"`
+or `origin="controller" controller="<label>"` is added by the receiver
+from what the connection presented, never from the frame; a controller's
+label comes from the grant the user minted, not from `fromName`. Tags
+that look like the envelope are defanged inside `content`.
+
+## 7. Compatibility
+
+- A reader ignores fields it does not know. Adding a field to a record or
+  a frame is not a breaking change.
+- `schemaVersion` and `msgV` are bumped only for a change to the shape of
+  existing fields. A reader drops a frame or skips a record with a
+  version above what it knows, and never deletes such a record.
+- New `status` values may appear; treat an unknown one as "no transition"
+  and keep waiting. The same goes for a `kind` you do not recognize:
+  show it, do not correct it.
+- Constants that may change without notice: the burst and rate figures,
+  the hold ceiling and expiry choices, the 1 MiB line cap, the 30-second
+  line deadline, the 64-connection cap.
+
+## 8. Not settled yet
+
+- **Name yielding.** Two sessions in one directory can register the same
+  `name`; today they are told apart only by `ref`. A registration that
+  yields to a live name, and a control frame that tells peers a session
+  renamed itself, are both still to come.
+- **Same-name reporting.** `qwen sessions ps` and `list_agents` do not
+  flag records that still collide.
+- **Inbound messages to ACP-driven sessions.** A session a program
+  drives over ACP — daemon-spawned or not — registers and can send, but
+  answers `refused` to anything sent to it: a hold is a question put to
+  a person, and nobody is watching a hold list on its behalf. Where a
+  held message should surface for those sessions — its client, or the
+  daemon's own API — is still open.
+- **Sessions behind one inbox are one sender to every peer.** A process
+  hosting several sessions sends with one `from` address, so a
+  receiver's per-sender budget and duplicate window (§6) are shared by
+  all of that process's sessions at once: a busy sibling can spend
+  another's allowance, and a body just sent to one cannot be repeated
+  to its sibling inside the window. Per-session accounting would have
+  to trust a frame-asserted field, which §3's trust model rules out.

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

@@ -20,7 +20,7 @@ Once a Goal has billed a turn, the footer pill and every status card show what i
 
 Each turn the session takes on its own reports what the Goal has spent so far, how many turns are behind it, and — unless the Goal runs unbounded — the window it is allowed. Every such turn except the final wind-down hand-off also carries standing instructions to re-check the workspace rather than trust earlier turns' reports, to work toward the end state the objective asks for, to do something different when the previous turn changed nothing (from the second turn on, once there is a previous turn to judge), and to check every requirement against citable evidence before proposing that the Goal is done.
 
-A long Goal periodically compresses the evidence it has recorded into checkpoint claims with a side model call, so later turns and the verifier still have it to cite. That call is bounded by [`model.goalCheckpointTimeoutSeconds`](../configuration/settings.md), 180 seconds by default; a checkpoint that does not finish in time is abandoned as an inconclusive check — the checkpoint stall streak is preserved rather than incremented — and a later turn retries it. The call is streamed, so the per-request transport timeout bounds only connect and first response, and the ceiling itself stops at the stream guards' 15-minute lifetime cap because past that the guard, not the setting, ends the call. That 15-minute limit on the setting is fixed, and raising the stream guard's own cap does not lift it.
+A long Goal periodically compresses the evidence it has recorded into checkpoint claims with a side model check, so later turns and the verifier still have it to cite. The check is bounded by [`model.goalCheckpointTimeoutSeconds`](../configuration/settings.md), 180 seconds by default. If its claims overrun the aggregate byte budget, or include a claim over the per-claim character limit, it makes one corrective model call and both calls share that ceiling. A check that does not finish in time is abandoned as inconclusive; it counts toward the checkpoint stall limit only when the evidence window has overflowed, while a non-overflowing check preserves the streak and retries on a later turn. The calls are streamed, so the per-request transport timeout bounds only connect and first response, and the ceiling itself stops at the stream guards' 15-minute lifetime cap because past that the guard, not the setting, ends the check. That 15-minute limit on the setting is fixed, and raising the stream guard's own cap does not lift it.
 
 ## Interrupting a Goal
 
@@ -73,13 +73,13 @@ For an audit, completion means covering the agreed scenarios and reporting evide
 
 If a success criterion, command, input path, or essential decision cannot be established, the skill returns a draft marked "Needs clarification" with `<TODO: …>` items. It does not offer that draft for approval or print a runnable `/goal set` or `/goal edit` command. Nonessential defaults are marked `[ASSUMPTION]`; they do not stand in for missing success criteria.
 
-Once the objective is ready, an interactive terminal session can show the `propose_goal` approval dialog described below. Web Shell and other ACP clients, headless runs, sessions with the tool disabled, and sessions with an active Goal receive a command to run manually instead. The hand-off says that the draft has not been applied. The skill never starts the work itself, and nothing is set without your approval.
+Once the objective is ready, an interactive terminal or Web Shell session can show the `propose_goal` approval dialog described below. Clients without Goal proposal support, headless runs, sessions with the tool disabled, and sessions with an active Goal receive a command to run manually instead. The hand-off says that the draft has not been applied. The skill never starts the work itself, and nothing is set without your approval.
 
 Pass an existing objective to tighten it: `/goal-draft all tests pass and the lint is clean`. For an active Goal, an explicit request to tighten it produces `/goal edit`; a replacement uses `/goal set`. If the intended operation is unclear, the skill includes that choice in its single round of questions.
 
 ### Approve a Goal the model proposes
 
-In an interactive terminal session the model has a `propose_goal` tool. When `/goal-draft` finishes, or when you ask for an outcome that spans several turns, it can propose the objective instead of printing a `/goal set …` line for you to copy. The proposal appears as an approval dialog showing the full objective. Approving it sets the Goal exactly as `/goal set` would, the moment the current turn ends (the model acknowledges and stops; the first Goal turn then starts on its own), and declining sets nothing — the model sees only that the tool call was not allowed, and its instructions tell it not to ask why and not to propose the same objective again. The approval is bound to the turn that asked for it: if that turn is cancelled or otherwise never reaches its end, the approval is dropped rather than applied under a later message or an automated turn. No permission rule or approval mode (including YOLO) skips this dialog, and the tool refuses while another Goal is active, in plan mode, and in untrusted folders; subagents are never offered it. It is not available in headless runs, nor yet in Web Shell or other ACP-driven sessions (they do not pass through the turn boundary that applies the approval); there the printed `/goal set` line remains the hand-off.
+In an interactive terminal or a Web Shell turn with an attached client, the model has a `propose_goal` tool. When `/goal-draft` finishes, or when you ask for an outcome that spans several turns, it can propose the objective instead of printing a `/goal set …` line for you to copy. The proposal appears as an approval dialog showing the full objective. Approving it sets the Goal exactly as `/goal set` would, the moment the current turn ends (the model acknowledges and stops; the first Goal turn then starts on its own), and declining sets nothing — the model sees only that the tool call was not allowed, and its instructions tell it not to ask why and not to propose the same objective again. The approval is bound to the turn that asked for it: if that turn is cancelled or otherwise never reaches its end, the approval is dropped rather than applied under a later message or an automated turn. No permission rule or approval mode (including YOLO) skips this dialog, and the tool refuses while another Goal is active, in plan mode, and in untrusted folders; subagents are never offered it. Web Shell uses its existing Allow/Reject permission panel. A stopped Goal can be replaced only if it still matches the version shown for approval; changing it invalidates the proposal. Headless runs, Web Shell channel deliveries and automatic turns, and ACP clients without the required approval and turn-lifecycle support retain the printed `/goal set` hand-off.
 
 Turn it off with `goals.modelProposed: "disabled"` in your user settings. Because the setting decides whether the model may ask you to start an autonomous loop, it is honored only from user and system scope; a workspace `.qwen/settings.json` value is ignored with a warning.
 

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

@@ -610,24 +610,28 @@ For `"ask"`, the TUI displays `permissionDecisionReason` as literal text rather
 
 #### UserPromptSubmit
 
-**Purpose**: Executed before supported model invocations to validate, block, or enrich the current model-bound prompt. The event currently covers `UserQuery`, `ToolResult`, and `Hook` sends, while `Retry`, `Steer`, `Cron`, `Notification`, and `Teammate` sends are skipped. It can therefore occur on continuation paths, and `prompt` must not be assumed to be raw user input.
+**Purpose**: Executed before supported model invocations to validate, block, or enrich their input. On the core/headless path, the event currently covers `UserQuery`, `ToolResult`, and `Hook` sends, while `Retry`, `Steer`, `Cron`, `Notification`, and `Teammate` sends are skipped. It can therefore occur on continuation paths, and `prompt` must not be assumed to be raw user input. The ACP session path has its own invocation policy: retries and newly dispatched background tasks can still invoke legacy hooks; continue, restored-question, and runtime-goal turns do not.
 
 **Event-specific fields**:
 
 ```json
 {
-  "prompt": "current model-bound prompt for this hook invocation",
-  "submitted_prompt": "optional user text captured at a supported interactive TUI submission boundary"
+  "prompt": "legacy prompt for this invocation; semantics depend on the execution path",
+  "submitted_prompt": "optional user text captured at a supported submission boundary"
 }
 ```
 
-`submitted_prompt` is optional. It is present only when Qwen can carry provenance from a supported interactive TUI submission to a fresh `UserQuery`. It is omitted for unsupported producers and machine-driven paths such as same-turn steering, tool-result continuations, retries, cron, notifications, and teammate traffic. ACP, headless, `serve`, SDK, and remote-input paths do not produce it in this version.
+`submitted_prompt` is optional. It is present on supported interactive TUI submissions and first-turn headless `UserQuery` sends. On the ACP session path used by ACP clients, `serve`, and daemon hosts, a fresh turn must carry an explicit submission declaration. Missing, non-string, empty, or whitespace-only declarations omit the field; the value is never reconstructed from `prompt` or a display label. Retries, continuations, and channel-classified turns omit it. The channel exclusion includes both automated events and human messages relayed through channel adapters.
 
-Deferred input can retain the field when its provenance remains complete. A combined batch retains provenance only when every constituent item has it; edited, partially known, or otherwise ambiguous input omits the field. Prompt, command, and shell-history navigation or selected search matches, cross-restart stash restores, and conversation rewind restores also omit it because those paths can surface model-bound text without its original provenance. Consumers that require user-submitted text should treat absence as unavailable rather than falling back to `prompt`.
+Web Shell provides the original composer text at its submission boundary. Realtime voice handoffs do not declare provenance because their request text comes from model-generated tool arguments. Other ACP/daemon SDK clients can opt in per request with `_meta: { "qwen.submittedPrompt": "original submitted text" }`, captured before resource or model-only expansion. Existing clients without this declaration continue running legacy hooks but do not trigger provenance-gated Auto Recall. Do not add the declaration globally to an SDK transport: scheduled tasks, Live task runs, sub-session spawns, model-authored cross-session messages, and promoted mid-turn messages must not acquire it automatically. The private `qwen.daemon.submittedPrompt` key is reserved for the daemon-to-child hop and is stripped from external callers. These declarations are caller-supplied provenance, not proof of human authorship or authorization.
+
+On the ACP path, the initial legacy `prompt` is the request's text blocks joined with a space before resource, attachment, slash-command, or model-only expansion. It does not expose the complete expanded model input. `submitted_prompt` can equal that text, but comes only from the explicit declaration and preserves its original whitespace. On the core/headless path, legacy `prompt` represents the current model-bound text for the hook invocation. Neither field is a complete DLP inspection surface.
+
+The following composer rules apply to the interactive TUI, not to ACP clients. Deferred input can retain the field when its provenance remains complete. A combined batch retains provenance only when every constituent item has it; edited, partially known, or otherwise ambiguous input omits the field. Prompt, command, and shell-history navigation or selected search matches, cross-restart stash restores, and conversation rewind restores also omit it because those paths can surface model-bound text without its original provenance. Consumers that require user-submitted text should treat absence as unavailable rather than falling back to `prompt`.
 
 After restored or provenance-unavailable model-bound input is cleared or submitted, the composer also clears its undo and redo history. This prevents undo from restoring expanded text after its marker or sidecar has been consumed.
 
-Large-paste placeholders remain compact in `submitted_prompt`; the expanded pasted content appears only in `prompt`. Consumers should treat the field as a TUI text projection rather than a byte-for-byte record of clipboard input.
+Large-paste placeholders remain compact in `submitted_prompt`; the expanded pasted content appears only in `prompt`. On that TUI path, consumers should treat the field as a text projection rather than a byte-for-byte record of clipboard input. ACP clients have no equivalent built-in Vim, paste-placeholder, history, or rewind provenance tracking; they own whether restored or edited text retains a valid submission declaration.
 
 Any non-empty input present while Vim mode is enabled omits `submitted_prompt`, including after Vim is disabled, because Vim registers do not carry provenance in this version. This conservative rule also covers drafts entered before enabling Vim. Clearing the composer starts a new eligible input.
 
@@ -665,10 +669,7 @@ This two-field payload is written only for this kind of user-prompt record.
 `hookContext` intentionally duplicates the tagged part so offline and
 third-party consumers can identify its provenance without parsing model text.
 `displayText` is the pre-hook display projection and never includes the hook
-context. For a supported interactive TUI submission it is the raw composer
-projection carried by `submitted_prompt`; ACP, headless, `serve`, SDK, remote
-input, and other paths without that provenance record the expanded pre-hook
-prompt instead.
+context. On the core/headless path it is the submitted projection when available, otherwise the expanded pre-hook prompt. ACP records the trusted display projection or raw request text before expansion when a projection or attachment references require a payload; otherwise it records the user message without `systemPayload` or `displayText`.
 
 Transcript display consumers treat `displayText` as this user-prompt projection
 when `systemPayload.hookContext` is a string. For compatibility with released
@@ -1495,11 +1496,11 @@ A PostToolUse HTTP hook that sends all tool execution records to a remote audit
 }
 ```
 
-### Example 3: Interactive TUI Submitted Prompt Validation Hook
+### Example 3: Submitted Prompt Validation Hook
 
-To inspect the current model-bound content instead, read `prompt`. That field can include generated or expanded content, is not the original user input, and does not imply that `UserPromptSubmit` covers every model send. Do not silently fall back from `submitted_prompt` to `prompt` when source provenance is required.
+On the core/headless path, `prompt` can include generated or expanded content rather than original user input. On ACP it starts with the pre-expansion request text, so reading it does not inspect attachment bodies or the complete model input. `UserPromptSubmit` does not cover every model send. Do not silently fall back from `submitted_prompt` to `prompt` when source provenance is required.
 
-A UserPromptSubmit hook that validates supported interactive TUI submissions for sensitive information and provides context for long prompts. It skips invocations where source provenance is unavailable. The keyword check is illustrative and is not a complete DLP policy:
+A UserPromptSubmit hook that validates supported submitted text and provides context for long prompts. It also runs on headless submissions and explicitly declared ACP/daemon submissions; it is not TUI-only. It skips invocations where source provenance is unavailable. A blocking result stops the affected invocation, including on these non-TUI paths. The keyword check is illustrative and is not a complete DLP policy:
 
 **prompt_validator.py**