|
| 1 | +# Saved workflow slash-command completion |
| 2 | + |
| 3 | +[English](2026-09-21-workflow-slash-completion.md) | [简体中文](2026-09-21-workflow-slash-completion.zh-CN.md) |
| 4 | + |
| 5 | +Status: implementation under review in [#12415](https://github.com/QwenLM/qwen-code/pull/12415), addressing [#12176](https://github.com/QwenLM/qwen-code/issues/12176). |
| 6 | + |
| 7 | +## Problem |
| 8 | + |
| 9 | +A saved-workflow slash command starts a client-initiated tool call. Its foreground result does not continue the model turn, and the registry emits completion notifications only for background runs. The result can exist on disk without reaching the conversation. |
| 10 | + |
| 11 | +## Decision |
| 12 | + |
| 13 | +Keep saved slash commands in the foreground. Separate completion delivery from execution mode: the scheduler passes an internal notification flag to notification-aware invocations when `executionOrigin.kind` is `client`. Missing or model provenance does not opt in, including nested code-mode calls whose results return to their parent. The overloaded `isClientInitiated` flag does not determine delivery. The Workflow invocation passes the delivery flag to its runner and registry entry. It is not a model-facing tool parameter or a persisted execution-mode setting. Both initial scheduling and rebuilding an invocation after a `PermissionRequest` hook edits its arguments preserve the flag. |
| 14 | + |
| 15 | +A completed or failed client-started run uses the existing completion callback and notification queue. Model-started foreground runs retain their tool-result return path; background runs retain their existing notification path. Cancellation produces no completion notification. Terminal-state guards prevent a run from reporting twice. |
| 16 | + |
| 17 | +The runner refreshes the tool card with its terminal state before execution settles. After Esc cancellation, the card retains its run ID and phase history with `status: "cancelled"`, replacing stale running progress. The active-progress guidance disappears once the run settles. This display refresh does not enqueue a completion notification. |
| 18 | + |
| 19 | +Foreground progress stays in the live tool card, with a run ID and guidance pointing to that card. `/workflows <runId>` can inspect the run after it settles; the command is queued during foreground execution. Its completion notice displays the run ID, status, a result preview or error capped at 4,096 characters per block, including the truncation marker, recorded subagent failures, and explicit lines for nonempty top-level `failed`, `errors`, or `error` values on structured object results. Read these fields from the original object, including when another field cannot be serialized or its getter throws. The shared failure formatter limits each reported field and recorded dispatch error to 400 characters, including any truncation marker, without splitting Unicode code points. Empty objects, arrays, Maps, Sets, and text containing only whitespace or terminal controls do not create reported-failure entries. Native Error values render as `Name: message` without runtime stack frames, including sandbox-created Errors and Errors nested in structured results. Nonempty Maps render as lists of key/value pairs and Sets as value lists, preserving their contents and nested Error reasons within the existing preview limits. The same reported lines are included in a separate `<reported-failures>` model element outside the result preview; they do not change runtime dispatch counts. Plain strings are not parsed as JSON failure reports. These fields are displayed as reported data, not used to reinterpret a completed run as a runtime failure. Arbitrary application-specific result schemas remain uninterpreted. A run without a return value displays `(workflow returned no value)` and sends no model result element. |
| 20 | + |
| 21 | +Foreground and background completion notifications cap the model result preview at 25,000 XML-escaped characters, independent of tool-output settings. The model-facing tool result, terminal tool card, and completion notification share Error and collection serialization semantics while retaining their existing pretty and compact formatting. If a value cannot be serialized, the tool card retains the run metadata and replaces only the affected top-level field with a placeholder. Result text, reported failure fields, and recorded dispatch errors share ANSI/control normalization, including Unicode bidirectional embedding, override, and isolate controls, preserving newlines and expanding tabs to spaces. Labels and thrown errors pass through the same normalization, and both complete notification projections are sanitized before delivery; workflow messages and approval script excerpts use the same normalization helper. Escaping is limited to the preview; truncation never splits a Unicode code point or XML entity, using the same bounded XML helper as sub-session notifications. A truncation notice carries the absolute snapshot destination provided by storage, independent of the journal. It states that the snapshot is available after finalization if persistence succeeds: notification emission precedes the snapshot write. The notice explains that snapshots use plain JSON and do not preserve native Error, Map, or Set contents, and that result and reported-failure previews may also be truncated. Neither the snapshot nor the previews promise recovery of every omitted detail. Without a destination, it directs the reader to inspect the settled run without promising a full result or inventing a relative file path. Existing diagnostics retain the per-agent journal path. The registry result and persisted snapshot are not shortened. Background summaries retain their original wrapper quotes and escaped labels. |
| 22 | + |
| 23 | +The TUI displays this foreground notice when the callback arrives, before waiting for model admission or a response. The same notification is then delivered through the existing queue and recorded in the conversation. A later question has the returned result in model context. The slash-command dispatch record may still have empty `outputHistoryItems`: the completion has its own notification record. |
| 24 | + |
| 25 | +## Alternatives and tradeoff |
| 26 | + |
| 27 | +Removing the foreground guard for every run would add notifications to model-started runs that already return a tool result. Forcing slash commands into background mode would change inline progress and foreground cancellation. The internal delivery flag preserves those behaviors while reusing the notification channel. |
| 28 | + |
| 29 | +Letting client tools through the normal tool-result continuation would also require handling their missing model-authored tool call, turn ownership, and cancellation. Expanding the command into a model prompt would add an invocation before execution and give the model control over the requested arguments. Neither is needed for this fix. |
| 30 | + |
| 31 | +The existing notification channel starts a model response and consumes tokens; this proposal preserves that report-back behavior requested by the issue. A configurable silent-context update or optional automatic summary is a separate feature, not implied by preserving foreground execution. The visible result does not depend on the model successfully generating a summary. |
| 32 | + |
| 33 | +## Scope |
| 34 | + |
| 35 | +In the ink renderer, interactive saved workflow commands keep their script-path/name-only choice, arguments, approvals, foreground progress, and cancellation. Headless and ACP commands retain prompt expansion. Code-mode nested calls return to their parent; ordinary model calls do not gain notifications. No public tool schema, configuration option, or persisted-schema migration is added. Snapshot serialization is unchanged: native Error, Map, and Set contents are not preserved by its plain JSON serializer. This repair preserves those values in notifications and model-facing and displayed tool results; it does not add snapshot persistence for their contents. |
| 36 | + |
| 37 | +OpenTUI's separate unwired `schedule_tool` handler and a new persisted-result viewer in workflow history remain outside this change. Both authoring skills scope slash-command guidance to ink and advise asking the model to call `Workflow({ name: '<name>' })` in OpenTUI. |
| 38 | + |
| 39 | +## Validation |
| 40 | + |
| 41 | +Use an isolated interactive session and a recording synthetic model endpoint. Verify foreground progress before a controlled agent finishes, visible completion data and real subagent failures, exactly one result notification, persistence of JSON-compatible result data, and result retention on a follow-up question. Include a large XML-heavy result with the failed field beyond the preview: the explicit failure line survives in both the display and model context, and the bounded model preview, absolute snapshot destination, and separate failure element remain in follow-up context. Exercise thrown script errors, cancellation, and approval refusal. Use model-initiated foreground execution as a control: one tool response and no completion notification. Preserve loader coverage for arguments, name-only dispatch, headless, and ACP. Share the existing 90-second read-only `/about` readiness probe with the command-output visibility test. |
| 42 | + |
| 43 | +Unit regressions cover authoritative provenance during initial scheduling and hook argument rebuilds, JSON-looking strings, non-serializable objects with valid failure fields, all three conventional error keys, sandbox-created and nested Errors, multiple Error reasons within one failure field, populated Maps/Sets, matching card/model result content, per-field degradation for BigInt/circular values, empty failure values, multiline failure text, no-return results, background summary escaping, throwing field getters, ANSI-heavy multiline results, intact Unicode/XML boundaries, and snapshot paths, persistence conditions, and missing-content qualifications for foreground/background runs with and without journals. The built-CLI large-result case verifies that the missing-content qualification reaches the model and remains in follow-up context. |
| 44 | + |
| 45 | +Run targeted unit and terminal regressions, build/type checks, and checks for changed files. No local repository-wide test suite is part of this revision. Evidence belongs in the PR verification report and must distinguish synthetic transport checks from real-model summary quality and the reporter's original nine-agent workload. |
0 commit comments