feat(workflows): let the model invoke extension workflows that declare whenToUse - #11957

What this PR does

An extension workflow whose script declares meta.whenToUse is now listed for the model. Its command appears in the model's skill listing with the description and that condition, so the model can start the workflow when a request matches, through the Skill tool and then Workflow({ name }). Every run still goes through the workflow approval. A workflow without whenToUse stays out of the model's listing, and project and user workflows are unchanged.

whenToUse is carried on ExtensionWorkflowDefinition and SavedWorkflowEntry, trimmed and shortened to 500 characters like the description; a blank value counts as absent.

Outside the interactive UI a {type:'tool'} command return cannot run. That covers the model invoking the command through the Skill tool, headless qwen -p, and ACP. There, a saved-workflow command now expands to a prompt: Run the "<name>" workflow., the description, the condition, and Invoke: Workflow({ name: "<name>", args: … }). The prompt uses the qualified workflow name, so a command renamed on a collision with its extension's skill still runs the right workflow. Typing /<name> in the interactive UI still dispatches the tool with the script path, unchanged. Because every mode can now run the command, it no longer restricts itself to interactive mode.

The Workflow tool's opt-in rule now reads: "A skill or slash command that ran — invoked by the user, or by you through the Skill tool — instructs you to use this tool."

Why it's needed

An extension that ships a workflow had no way to let the model choose it. The command was never model-invocable, and the three model-invocable command executors accept only submit_prompt, so even a listed command would have come back as "not found". The opt-in rule also counted only commands the user invoked. The only way to get the model to run an extension workflow was an instruction in QWEN.md telling it to, which the opt-in rule does not accept and which fires on every matching request regardless of what the extension author intended.

Claude Code wraps every workflow as a prompt command with its whenToUse, expanding to "Run the … workflow … Invoke: Workflow({name})". This follows the same shape, but lists only extension workflows whose author wrote the condition: the author says when it applies, the user consented to the extension, workflows are enabled, and the run is approved.

Reviewer Test Plan

How to verify

Enable workflows, install or link an extension with workflows/analysis.js declaring whenToUse, and a second script without it. Start a session and ask a question that matches the condition. The model should call the Skill tool with the workflow's name, receive the "Run the … workflow" text, and call Workflow({ name }), which opens the usual approval with Saved workflow: <name>. The workflow without whenToUse does not appear in the model's skill listing.

Type /dataworks:analysis in the interactive UI: it starts the workflow directly, as before. Run qwen -p '/dataworks:analysis': the command is no longer rejected as unsupported, and the model runs the workflow by name.

Unit tests:

cd packages/core && npx vitest run src/agents/runtime/workflow-extension.test.ts src/agents/runtime/workflow-saved.test.ts src/tools/workflow/workflow.test.ts src/tools/workflow/workflow-description.test.ts src/skills/bundled/workflow-authoring/SKILL.test.ts
cd packages/cli && npx vitest run src/services/saved-workflow-loader.test.ts src/services/CommandService.test.ts src/services/commandMetadata.test.ts src/nonInteractiveCliCommands.test.ts

330 core and 137 cli tests pass locally, as do the core type check and ESLint on the changed files. The cli type check is left to CI: locally it reads the other workspace packages' built output, which predates this change.

Evidence (Before & After)

Output from the real modules on this branch: an extension discovered from disk with loadExtensionWorkflows, adapted by SavedWorkflowLoader, registered in CommandService, and rendered with the skill-listing renderer. Before this change the listing had no entry for either workflow, the command action returned the tool dispatch in every context (which the executors turn into "not found" and headless turns into "Tool execution from slash commands is not supported in non-interactive mode."), and both commands were listed for the interactive mode only.

--- <available_skills> entries from the model-invocable commands ---
<skill>
<name>
dataworks:analysis
</name>
<description>
Answers a data question end to end — When the user asks a question that needs querying, analysing and charting warehouse data
</description>
</skill>

--- Skill({ skill: "dataworks:analysis", args: '{"table":"orders"}' }) through the executor (non_interactive context) ---
Run the "dataworks:analysis" workflow.

Answers a data question end to end

When the user asks a question that needs querying, analysing and charting warehouse data

Invoke: Workflow({ name: "dataworks:analysis", args: {"table":"orders"} })

--- /dataworks:analysis typed in the interactive UI ---
{"type":"tool","toolName":"workflow","toolArgs":{"scriptPath":"/tmp/ev/ext/workflows/analysis.js"}}

--- commands per mode ---
interactive: dataworks:analysis, dataworks:export
non_interactive: dataworks:analysis, dataworks:export
acp: dataworks:analysis, dataworks:export

--- Workflow tool opt-in rule, third bullet ---
- A skill or slash command that ran — invoked by the user, or by you through the Skill tool — instructs you to use this tool.

Tested on

Environment (optional)

Unit tests, the core type check, and a throwaway vitest file driving the real modules. No interactive TUI session was run.

Risk & Scope

• Main risk or tradeoff: the model can start a third-party extension's multi-agent run without the user typing the command. That needs all of: the author declared whenToUse, the user consented to the extension, tools.workflowsEnabled is on (off by default), and the user approves the run. whenToUse lives in the script, so changing it changes the content digest and the next update asks for consent again. Headless and ACP /<name> now go through one model turn instead of being refused, which matches how skills and file commands behave there.
• Not validated: an interactive session with a real model deciding to invoke the workflow; the unit tests and the evidence cover the listing, the expansion and the dispatch.
• Out of scope: model invocation of project and user workflows (their discovery does not read the script, so there is no whenToUse to go on); a disableModelInvocation meta field; switching the interactive /<name> path from scriptPath to name, which would stop existing Workflow(scriptPath:…) rules from matching it.

Linked Issues / Bugs

Part of #11013

中文说明

这个 PR 做了什么

脚本 meta 声明了 whenToUse 的扩展 workflow 现在会列给模型。它的命令带着描述和适用条件出现在模型的技能列表里，请求匹配时模型可以经 Skill 工具、再调用 Workflow({ name }) 发起运行。每次运行仍走 workflow 审批。没写 whenToUse 的 workflow 不进模型的列表，project 和 user workflow 不变。

ExtensionWorkflowDefinition 与 SavedWorkflowEntry 带上 whenToUse，去掉首尾空白，并与描述一样截到 500 字符；空白值视为未声明。

在交互界面之外，命令返回的 {type:'tool'} 无法执行，包括模型经 Skill 工具调起命令、headless qwen -p 和 ACP。这些场景下，已保存 workflow 的命令现在展开为一段提示：Run the "<name>" workflow.、描述、适用条件，以及 Invoke: Workflow({ name: "<name>", args: … })。提示里用的是限定名，所以命令和同扩展的同名 skill 撞名被改名后，仍然运行正确的 workflow。在交互界面里敲 /<name> 仍按脚本路径直接调度工具，行为不变。既然所有模式都能运行，命令也不再只声明交互模式。

Workflow 工具显式请求规则的第 3 条改为："A skill or slash command that ran — invoked by the user, or by you through the Skill tool — instructs you to use this tool."

为什么需要

扩展随附的 workflow 没有办法让模型自行选用。命令从来不是模型可调用的；三处模型可调用命令执行器只接受 submit_prompt，即便列出来也会返回"找不到"；规则也只承认用户调起的命令。想让模型跑扩展 workflow，只能在 QWEN.md 里要求它这么做，而这既不被显式请求规则承认，也不管扩展作者的意图，匹配就触发。

Claude Code 把每个 workflow 包装成带 whenToUse 的 prompt 命令，展开为 "Run the … workflow … Invoke: Workflow({name})"。本 PR 采用相同形态，但只列出作者写了适用条件的扩展 workflow：作者说明何时适用、用户同意安装扩展、workflows 已开启、运行经过审批。

验证方式

开启 workflows，安装或链接一个扩展：workflows/analysis.js 声明 whenToUse，另一个脚本不声明。开一个会话，问一个符合条件的问题。模型应以 workflow 名调用 Skill 工具，拿到 "Run the … workflow" 文本，再调用 Workflow({ name })，弹出常规审批，标题为 Saved workflow: <name>。没写 whenToUse 的 workflow 不出现在模型的技能列表里。

在交互界面敲 /dataworks:analysis：和之前一样直接启动。运行 qwen -p '/dataworks:analysis'：命令不再被判为不支持，而是由模型按名运行 workflow。

单元测试命令见英文部分。本地 core 330 个、cli 137 个测试通过，core 类型检查与改动文件的 ESLint 通过。cli 类型检查交给 CI：本地它读取其他 workspace 包的旧构建产物。

证据

见英文部分代码块：用本分支真实模块从磁盘发现扩展、经 SavedWorkflowLoader 适配、注册到 CommandService，并用技能列表渲染器输出。改动之前，列表里两个 workflow 都没有条目；命令在任何上下文都返回工具调度，执行器会把它变成"找不到"，headless 会报 "Tool execution from slash commands is not supported in non-interactive mode."；两个命令都只在交互模式下列出。

测试平台

Linux ✅；macOS ⚠️；Windows ⚠️。

风险与范围

• 主要风险/取舍：模型可以在用户没敲命令的情况下发起第三方扩展的多 agent 运行。前提是同时满足：作者声明了 whenToUse、用户同意安装扩展、tools.workflowsEnabled 已开启（默认关闭）、用户批准这次运行。whenToUse 写在脚本里，改动它会改变内容摘要，下次更新会重新征求同意。headless 与 ACP 的 /<name> 现在经模型一轮运行，而不是被拒绝，与 skill 和文件命令在这些场景的行为一致。
• 未验证：真实模型在交互会话中自行决定调用 workflow；单元测试与证据覆盖了列表、展开和调度。
• 范围之外：project 和 user workflow 的模型可调用（其发现阶段不读脚本，没有 whenToUse 可依据）；disableModelInvocation meta 字段；把交互式 /<name> 从 scriptPath 改为 name，那会让已有的 Workflow(scriptPath:…) 规则不再匹配。

关联 Issue

Part of #11013