@zhushanwen/pi-subagent-workflow 9.1.1 → 9.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "9.1.1",
+  "version": "9.2.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -62,8 +62,8 @@
     "@zhushanwen/session-delivery": "1.0.0",
     "@zhushanwen/pi-ext-guards": "0.4.2",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-notify-ledger-host": "0.2.2",
-    "@zhushanwen/subagent-core": "1.1.0",
+    "@zhushanwen/pi-notify-ledger-host": "0.2.4",
+    "@zhushanwen/subagent-core": "1.2.1",
     "@zhushanwen/pi-subagent-cli": "0.5.0",
     "@zhushanwen/zcode-subagent-cli": "0.4.4"
   },

package/src/host/__tests__/staged-discovery.test.ts

@@ -0,0 +1,147 @@
+// staged-discovery.test.ts — 打包态内置资产**发现结果**门禁（档 2，2026-10-03 B′）
+//
+// 为什么单独建这个文件：本次事故（打包版 `subagents` 批量工具报
+// "Built-in workflow 'fan-out' is not available"）的根因是**发现层面**——esbuild
+// 自包含 bundle 下 `require.resolve("@zhushanwen/subagent-core/…")` 必败，staged 布局
+// 又无 node_modules，于是孝在包里的 `workflows/` 无人能扫到。既有门禁全是“文件在不在”
+// 级断言（dry-run import 不调工厂、TC8 只比字节），对本类失效天然失明。
+//
+// 本文件的断言对象是**发现结果**（6 内置 workflow + 10 内置 agent 真的被列出来），
+// 而非“文件存在”：前者才能拦住“路径/产物层”回归。两条通路都被锁：
+//   ① 纯函数：bundle 形态模块路径 → scope 根；dev/异常形态 → undefined（不误触发）；
+//   ② 集成：以合成 bundle 模块路径调 `corePackageNpmRoot()`（resolve 必败 → 回退分支），
+//      再把回退根当 npm 槽根跑**真实** `discoverResources`，断言结果与源目录逐文件一致。
+//
+// 资产集不写死数量（口径：与 `packages/subagent-core/{workflows,agents}` 源目录集合比对，
+// 源增删自动跟随）。
+
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { discoverResources, isTargetFile } from "@zhushanwen/subagent-core";
+import { afterAll, describe, expect, it, vi } from "vitest";
+
+// pi 宿主协作件 mock：本文件只跑发现链，日志面给可调用桩（回退分支会走 debug）。
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => process.env.PI_CODING_AGENT_DIR ?? "/mock/agent-dir",
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+
+const { corePackageNpmRoot, stagedScopeRootFromModuleUrl } = await import("../pi-host.ts");
+
+/** 本仓 `packages/subagent-core`（源单源：断言口径由此推导，不写死数量）。
+ *  路径经与生产同一锚点解析得出（禁止手数 `..` 层级）。 */
+const CORE_PKG = dirname(
+  dirname(createRequire(import.meta.url).resolve("@zhushanwen/subagent-core/workflows/README.md")),
+);
+
+const tmpDirs: string[] = [];
+function makeTmp(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  tmpDirs.push(dir);
+  return dir;
+}
+afterAll(() => {
+  for (const d of tmpDirs) {
+    // teardown 递归删除补 maxRetries：与在途异步写竞争时 ENOTEMPTY 满载 flake
+    rmSync(d, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  }
+});
+
+/** 合成 staged 布局：<tmp>/@zhushanwen/pi-subagent-workflow/{index.js,workflows,agents}。 */
+function makeStagedLayout(): { scopeDir: string; moduleUrl: string } {
+  const root = makeTmp("staged-discovery-");
+  const pkgDir = join(root, "@zhushanwen", "pi-subagent-workflow");
+  mkdirSync(pkgDir, { recursive: true });
+  const indexJs = join(pkgDir, "index.js");
+  writeFileSync(indexJs, "// staged bundle placeholder\n", "utf8");
+  for (const kind of ["workflows", "agents"] as const) {
+    cpSync(join(CORE_PKG, kind), join(pkgDir, kind), { recursive: true });
+  }
+  return { scopeDir: join(root, "@zhushanwen"), moduleUrl: pathToFileURL(indexJs).href };
+}
+
+/** 源目录内可发现文件的集合——判据直接复用发现层导出的 isTargetFile（同一份
+ *  函数，发现层口径变化时期望集自动跟随，无双源）。 */
+function sourceExpected(kind: "workflows" | "agents"): string[] {
+  return readdirSync(join(CORE_PKG, kind))
+    .filter((f) => isTargetFile(f, kind))
+    .sort();
+}
+
+describe("B′：staged/bundle 形态的 core 资产发现根", () => {
+  it("stagedScopeRootFromModuleUrl：bundle 形态（<scope>/<pkg>/index.js）→ 返回 scope 目录", () => {
+    const { scopeDir, moduleUrl } = makeStagedLayout();
+    expect(stagedScopeRootFromModuleUrl(moduleUrl)).toBe(scopeDir);
+  });
+
+  it("stagedScopeRootFromModuleUrl：dev 形态（非 scope 布局）→ undefined（不误触发回退）", () => {
+    const devLike = pathToFileURL(join(CORE_PKG, "workflows", "fan-out.js")).href;
+    expect(stagedScopeRootFromModuleUrl(devLike)).toBeUndefined();
+  });
+
+  it("corePackageNpmRoot：dev/workspace 形态走 resolve 通路（不回退）", () => {
+    const root = corePackageNpmRoot();
+    expect(root).toBeDefined();
+    // workspace 形态：scope 根下必须有 subagent-core 包目录（resolve 命中锚点的上三级）
+    expect(readdirSync(root as string)).toContain("subagent-core");
+  });
+
+  it("corePackageNpmRoot：bundle 形态 resolve 必败 → 回退到 scope 根", () => {
+    const { scopeDir, moduleUrl } = makeStagedLayout();
+    expect(corePackageNpmRoot(moduleUrl)).toBe(scopeDir);
+  });
+});
+
+describe("B′：回退根下的**发现结果**（本批防复发的核心断言）", () => {
+  it("workflows：发现结果与源目录集合逐文件一致（内置模板全部可派发）", async () => {
+    const { scopeDir } = makeStagedLayout();
+    const found = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: scopeDir,
+      hostRoots: [{ dir: scopeDir, source: "npm" }],
+    });
+    // 只断言**回退根下**的发现结果（发现面还包括真实用户目录 ~/.agents/workflows
+    // 等宿主/约定根——本用例的主题是回退根本身，故按路径范围收窄，噪声不介入）
+    const names = found
+      .filter((r) => r.available && r.path.startsWith(scopeDir))
+      .map((r) => r.path.split("/").pop() as string)
+      .sort();
+    expect(names).toEqual(sourceExpected("workflows"));
+    // 回归锚：批量入口的固定执行体必须在列
+    expect(names).toContain("fan-out.js");
+  });
+
+  it("agents：发现结果与源目录集合逐文件一致（10 内置角色全部可选）", async () => {
+    const { scopeDir } = makeStagedLayout();
+    const found = await discoverResources({
+      kind: "agents",
+      workspaceRoot: scopeDir,
+      hostRoots: [{ dir: scopeDir, source: "npm" }],
+    });
+    const names = found
+      .filter((r) => r.available && r.path.startsWith(scopeDir))
+      .map((r) => r.path.split("/").pop() as string)
+      .sort();
+    expect(names).toEqual(sourceExpected("agents"));
+    expect(names).toContain("general-purpose.md");
+  });
+
+  it("负向：源资产缺席时发现结果为空（门禁失败方向正确，不会假绿）", async () => {
+    const root = makeTmp("staged-discovery-empty-");
+    const pkgDir = join(root, "@zhushanwen", "pi-subagent-workflow");
+    mkdirSync(pkgDir, { recursive: true });
+    writeFileSync(join(pkgDir, "index.js"), "// no assets\n", "utf8");
+    const found = await discoverResources({
+      kind: "workflows",
+      workspaceRoot: join(root, "@zhushanwen"),
+      hostRoots: [{ dir: join(root, "@zhushanwen"), source: "npm" }],
+    });
+    expect(found.filter((r) => r.available)).toEqual([]);
+  });
+});

package/src/host/pi-host.ts

@@ -62,20 +62,34 @@ import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
  * realpath 去重吸收）。
  *
  * 每次调用现解析（不 memo）：发现调用点稀疏（session_start + 缓存 miss），解析
- * 成本可忽略；失败（异常布局/解析器不可用）降级为不注入并 warn——绝不因资产
- * 接线失败阻断发现主链。
+ * 成本可忽略；两种形态各有通路，都不阻断发现主链：
+ *   - **dev / npm 形态**：`require.resolve` 沿本包依赖解析链命中 core 包；
+ *   - **bundle / staged 打包形态**（2026-10-03 B′ 修复）：esbuild 自包含 bundle 把
+ *     core inline、staged 布局无 node_modules ⇒ resolve 必败（实证：pi-host 日志全天
+ *     202 条 'Cannot find module … workflows/README.md'，内置 6 workflow + 10 agent
+ *     整体不可发现、`subagents` 批量工具报 'Built-in workflow fan-out is not available'）。
+ *     此时回退到 staged scope 根（见 stagedScopeRootFromModuleUrl）——仅当回退也不
+ *     成立（异常布局/解析器不可用）才降级为不注入并 warn。
  */
-function corePackageNpmRoot(): string | undefined {
+export function corePackageNpmRoot(moduleUrl: string = import.meta.url): string | undefined {
   try {
     // createRequire 锚定本模块（jiti 加载器下 import.meta.url 可用；不可用则随
     // catch 降级）。require.resolve 沿 pi-sw 自身的依赖解析链——workspace 与发布态
     // 都从本包出发命中 core。
-    const require = createRequire(import.meta.url);
+    const require = createRequire(moduleUrl);
     const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
     return dirname(dirname(dirname(anchor)));
   } catch (err) {
-    // getLogger 惰性调用（catch 是冷路径——测试环境对 pi-extension-logger 的
-    // module-level mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+    const stagedRoot = stagedScopeRootFromModuleUrl(moduleUrl);
+    if (stagedRoot !== undefined) {
+      // getLogger 惰性调用（冷路径：测试环境对 pi-extension-logger 的 module-level
+      // mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+      getLogger("pi-host").debug(
+        "[pi-host] core 包经 staged scope 根注入（bundle 形态，无 node_modules 解析面）",
+        { root: stagedRoot },
+      );
+      return stagedRoot;
+    }
     getLogger("pi-host").warn(
       "[pi-host] core 包 agents/ 注入根解析失败——10 内置角色可能不可发现",
       { reason: toErrorMessage(err) },
@@ -84,6 +98,40 @@ function corePackageNpmRoot(): string | undefined {
   }
 }
 
+/**
+ * bundle / staged 形态的 core 资产注入根（2026-10-03 B′）。
+ *
+ * 打包态扩展被 esbuild 打成**自包含 index.js**（core 被 inline），staged 布局内无
+ * node_modules ⇒ `require.resolve` 锚点必败。但此时模块位置是
+ * `<stagedScope>/<pkg>/index.js`（如
+ * `<Resources>/extensions/@zhushanwen/pi-subagent-workflow/index.js`），其**父目录**
+ * 正是 `@zhushanwen` scope 目录——npm 槽语义（"一级子项 = 包目录"）恰好成立，
+ * 于是可直接当 npm 槽根用：约定目录扫描即命中
+ * `pi-subagent-workflow/{workflows,agents}`（两目录由 `scripts/bundle-extensions.mjs`
+ * 随包拷贝；`pi.agents`/`pi.workflows` manifest 约定及其"声明路径不存在 → 整包失败
+ * 占位"语义是 subagent-core resource-discovery 的 taiji 自建规则，权威源 =
+ * resource-discovery.ts processPackage——pi 上游 manifest 只有
+ * extensions/skills/prompts/themes 四字段，无 agents/workflows 概念。已核仓内无任何
+ * 包声明该字段，故扫描面内所有包都走约定目录分支，不进 manifest 失败分支）。
+ *
+ * 与 dev/npm 形态的既有语义一致：npm 槽根扫的就是 scope 下全部包目录（因此本包自带
+ * 的 workflows/agents 在 dev/npm 形态同样入发现面），非新增语义。
+ *
+ * 形态判据 = 父目录名以 `@` 开头：dev（模块在 `extensions/universal/...`）与 npm
+ * 安装形态都先走 resolve 成功分支，本回退不可达；仅 bundle/staged 形态命中。
+ */
+export function stagedScopeRootFromModuleUrl(moduleUrl: string): string | undefined {
+  try {
+    const pkgDir = dirname(fileURLToPath(moduleUrl));
+    const scopeDir = dirname(pkgDir);
+    if (scopeDir === pkgDir) return undefined;
+    const scopeName = scopeDir.split(/[\\/]/).pop() ?? "";
+    return scopeName.startsWith("@") ? scopeDir : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** agents/workflows 共享的 agentDir 派生根（末级目录名由 kind 决定）。
  *  顺序与 source 标签逐项对齐 resource-discovery.ts buildScanTargets 的
  *  user-pi → npm → npm-dev 段（根列表按优先级低→高排列，D2 语义边界）。

package/src/injectors/__tests__/workflow-list-injector.test.ts

@@ -243,7 +243,7 @@ describe("formatAgentList CA2 快照（agent guide 壳自有文案唯一字节
 		// guide 段硬编码（锁文本）：期望值不插值生产常量——改写 SUBAGENT_LIST_GUIDE
 		// 即红灯，避免「两侧同源插值」下文案漂移无守卫
 		expect(out).toBe(
-			`\n\n<available_subagents>\nThe following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agents from this list — pass the <location> path (absolute .md path) as the agent param. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.\n${expectedItems.join("\n")}\n</available_subagents>`,
+			`\n\n<available_subagents>\nThe following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, pass the <location> path from this list as the agent param (usually the right choice); an absolute .md path outside this list also works if the file is a readable agent definition. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.\n${expectedItems.join("\n")}\n</available_subagents>`,
 		);
 
 		// location 前缀替换（资产来源迁移：pi-sw 安装目录 → core 包）后其余字节零变化

package/src/injectors/subagent-list-injector.ts

@@ -43,7 +43,7 @@ import { createResourceListInjector } from "./resource-list-injector.ts";
  * 动态指引经 task 文本 / appendSystemPrompt 参数承载。
  */
 export const SUBAGENT_LIST_GUIDE =
-	"The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agents from this list — pass the <location> path (absolute .md path) as the agent param. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.";
+	"The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, pass the <location> path from this list as the agent param (usually the right choice); an absolute .md path outside this list also works if the file is a readable agent definition. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.";
 
 /**
  * agent 清单实例：缓存生命周期 / 三 handler 经工厂骨架；装配循环经 assemble 覆写

package/src/interface/gui/subagent-actions.ts

@@ -139,7 +139,11 @@ export function buildGuiComponent(
     const listResp = input.domain;
     return guiComponent("list-tree", {
       items: listResp.response.items.map((it) => ({
-        label: it.slug ? `${it.agent} · ${it.slug} · ${it.subagentId}` : `${it.agent} · ${it.subagentId}`,
+        // GUI 详情层：label 保留完整 agent ref（摘要短名的取舍见 TUI compact/expanded
+        // 分层——GUI list-tree 是详情展示，全路径信息优先）
+        label: it.slug
+          ? `${it.agent} · ${it.slug} · ${it.subagentId}`
+          : `${it.agent} · ${it.subagentId}`,
         status: mapRunStatus(it.status),
         icon: mapRunIcon(it.status),
       })),

package/src/interface/tool/__tests__/tool-render.test.ts

@@ -200,7 +200,7 @@ describe("renderSubagentResult — expanded 与 compact 的分支关系（字节
     expect(expanded.join("\n")).toContain("/tmp/sessions/old-abc.jsonl");
   });
 
-  it("list：expanded 在 compact 之上追加 session 行（差异锁定）", () => {
+  it("list：expanded agent 用完整 ref、并追加 session 行；compact agent 用 basename 短名（分层锁定）", () => {
     const details = {
       action: "list",
       subagentId: null,
@@ -209,7 +209,7 @@ describe("renderSubagentResult — expanded 与 compact 的分支关系（字节
         running: 1,
         items: [{
           subagentId: "sa-1",
-          agent: "worker",
+          agent: "/Users/x/.agents/agents/worker.md",
           slug: "scan",
           status: "running",
           duration: 12,
@@ -218,10 +218,18 @@ describe("renderSubagentResult — expanded 与 compact 的分支关系（字节
       },
     };
     const { compact, expanded } = renderBoth(details);
+    // compact：basename 短名（无目录、无 .md），无 session 行。强断言带边界形态：
+    // agent 值以完整 accent 包裹出现（防 "worker" 作为其他字段子串命中弱化回归）
+    expect(compact.join("\n")).toMatch(/<accent>worker<\/accent>/);
+    expect(compact.join("\n")).not.toContain("/Users/x/.agents/");
+    expect(compact.join("\n")).not.toContain(".md");
     expect(compact.join("\n")).not.toContain("session: ");
+    // expanded：agent 完整 ref（详情层）+ session 路径行
+    expect(expanded.join("\n")).toContain("/Users/x/.agents/agents/worker.md");
+    expect(expanded.join("\n")).toContain("session: ");
     expect(expanded.join("\n")).toContain("/tmp/sessions/sa-1.jsonl");
-    expect(compact.join("\n")).not.toContain("/tmp/sessions/sa-1.jsonl");
-    // compact 的行是 expanded 的前缀（追加不修改既有行）
-    expect(expanded.slice(0, compact.length)).toEqual(compact);
+    // 标题行两态一致（首行），差异只在 item agent 行与追加 session 行
+    expect(expanded[0]).toBe(compact[0]);
+    expect(expanded.length).toBe(compact.length + 1);
   });
 });

package/src/interface/tool/__tests__/tool-workflow.test.ts

@@ -906,3 +906,66 @@ describe("TC3i: 宿主 TOOL_TOP_LEVEL reservedKeys 接线锚（M-3 回归）", (
     expect(argKeysFromMeta(rflParams(), OPT).exact.has("name")).toBe(false);
   });
 });
+
+// ══════════════════════════════════════════════════════════════
+// renderCall 标题行（displayWorkflowName 短名 + runId/slug 不受影响）
+// ══════════════════════════════════════════════════════════════
+//
+// 锁 2026-09 display 分层：name 是绝对 .js 路径，标题行只出 basename 短名
+// （displayWorkflowName）；runId 截断预览与 slug 后缀形态不变。
+
+/** 最小 theme stub（fg/bold 直包文本——断言不依赖真实着色映射）。 */
+function makeRenderTheme(): Record<string, (color: string | ((t: string) => string), text?: string) => string> {
+  return {
+    fg: (_color, text) => (typeof text === "string" ? `<${_color}>${text}</${_color}>` : ""),
+    bold: (text) => (typeof text === "string" ? `<b>${text}</b>` : ""),
+  } as never;
+}
+
+/** pi-tui Text 反射取构造串（tool-render.test.ts 同款 helper——本文件独立内联）。 */
+function textOf(component: unknown): string {
+  const obj = component as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const v = obj[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return "";
+}
+
+describe("renderCall 标题行：displayWorkflowName 短名 + runId/slug 不受影响", () => {
+  const tool = captureWorkflowTool(makeDeps(stubRegistry()), { isProcessing: false });
+  const theme = makeRenderTheme();
+
+  it("绝对路径 name → basename 短名（去 .js、去目录）", () => {
+    const out = textOf(
+      (tool as unknown as { renderCall: (args: Record<string, unknown>, theme: unknown) => unknown })
+        .renderCall({ action: "run", name: "/home/u/wf/batch-report.js" }, theme),
+    );
+    expect(out).toMatch(/batch-report<\/accent>/); // name 落在 accent 段收口前（前缀空格也在段内）
+    expect(out).not.toContain("/home/u/wf/");
+    expect(out).not.toContain(".js");
+  });
+
+  it("runId / slug 后缀不受短名影响（runId 截断预览 + slug 全文）", () => {
+    const out = textOf(
+      (tool as unknown as { renderCall: (args: Record<string, unknown>, theme: unknown) => unknown })
+        .renderCall(
+          { action: "run", name: "/home/u/wf/batch-report.js", slug: "nightly", runId: "wf-run-0123456789" },
+          theme,
+        ),
+    );
+    // 短名 + slug 全文在位
+    expect(out).toContain("batch-report");
+    expect(out).toContain("nightly");
+    // runId 只出截断预览（ID_PREVIEW_LENGTH = 8 → "wf-run-0"），不泄漏全文
+    expect(out).toContain("wf-run-0");
+    expect(out).not.toContain("wf-run-0123456789");
+  });
+
+  it("缺 name（status 等无参 action）不崩、不出短名", () => {
+    expect(() =>
+      (tool as unknown as { renderCall: (args: Record<string, unknown>, theme: unknown) => unknown })
+        .renderCall({ action: "status" }, theme),
+    ).not.toThrow();
+  });
+});

package/src/interface/tool/subagent-tool-schema.ts

@@ -55,7 +55,7 @@ export const SubagentParams = Type.Object({
     maxLength: SLUG_MAX_LENGTH,
   })),
   agent: Type.Optional(Type.String({
-    description: 'Agent ref: absolute path to the agent .md file (use <location> from <available_subagents>). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Do not invent names — only use paths from the injected list.',
+    description: 'Agent ref: absolute path to an agent .md file — usually a <location> from <available_subagents>, but ANY absolute .md path works if the file is a readable agent definition (the list is not required). Relative paths and bare names are rejected. If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context.',
   })),
   model: Type.Optional(Type.String({
     description: 'Model override in "provider/modelId" format. CASE-SENSITIVE: the string must equal a registry entry exactly, including letter case (e.g. "zai-coding-cn/GLM-5.3-Flash", NOT "zai-coding-cn/glm-5.3-flash"). A non-exact match is rejected immediately with "Did you mean" suggestions — retry with the exact suggested string; the system never auto-corrects your input. Resolution order (top wins): (1) this param, (2) agent .md frontmatter model, (3) the main agent\'s current model (zero-config default). An explicit model (param or frontmatter) that is missing or unauthorized THROWS — there is no silent fallback to the main model. Omit this param to inherit the main model.',

package/src/interface/tool/subagent-tool.ts

@@ -149,7 +149,7 @@ export function registerSubagentTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
-    promptSnippet: "Delegate to specialized subagents (agentRef = absolute .md path from <available_subagents>)",
+    promptSnippet: "Delegate to specialized subagents (agentRef = absolute .md path, e.g. a <location> from <available_subagents>)",
     description: `Delegate a task to a specialized subagent — when to delegate rather than do it yourself.
 
 CRITICAL — executionMode "sequential": multiple \`subagent\` calls in the SAME message run one-after-another. For concurrency, start runs in background and tasks run concurrently in the pool (default maxConcurrent=6).

package/src/interface/tool/tool-render.ts

@@ -230,7 +230,8 @@ function buildCompactLines(d: SubagentToolResult, theme: ThemeLike): string[] {
 /**
  * 展开视图行内容生成。除下列两个特例外与 compact 逐字节相同（一次性 block 无
  * 细节可展开），测试锁字节等价：
- * - list：compact 结果之上每 item 追加 sessionFile 路径行（renderListExpanded）
+ * - list：每 item agent 用完整 ref（compact 用 basename 短名），并追加 sessionFile 路径行
+ *   （renderListExpanded）
  * - fork-from：源文件用完整路径（compact 用 basename 短标签）
  */
 function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
@@ -309,8 +310,14 @@ function getStringText(item: unknown): string | undefined {
 // list 渲染 helper（action:"list" 分支）
 // ============================================================
 
-/** list compact：标题行 + 每行一个 item 摘要（glyph + agent + slug + mode + status + duration）。 */
-function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number): string[] {
+/**
+ * list compact：标题行 + 每行一个 item 摘要（glyph + agent + slug + mode + status + duration）。
+ *
+ * agent 展示分层（同 fork-from 先例：compact 短标签 / expanded 完整路径——摘要行
+ * 单行宽度优先，详情行信息完整优先）：`shortAgent: false`（expanded）输出完整 ref。
+ */
+function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number, opts?: { shortAgent?: boolean }): string[] {
+  const shortAgent = opts?.shortAgent ?? true;
   if (resp.items.length === 0) {
     return [truncLine(theme.fg("dim", `No subagents (running: ${resp.running})`), width)];
   }
@@ -323,16 +330,21 @@ function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number):
     const mode = "bg";
     // slug 非空时在 agent 后展示（· 分隔），空串时省略。
     const slugPart = it.slug ? `${theme.fg("dim", " · ")}${theme.fg("accent", it.slug)}` : "";
-    const line = `${theme.fg(glyph.color, icon)} ${theme.fg("accent", it.agent)}${slugPart}`
+    // compact 摘要：basename 短名（同 renderSubagentCall 标题行）；expanded 详情：完整 ref
+    const agent = shortAgent ? displayAgentName(it.agent) : it.agent;
+    const line = `${theme.fg(glyph.color, icon)} ${theme.fg("accent", agent)}${slugPart}`
       + ` ${theme.fg("dim", `· ${mode} · ${it.status} · ${formatElapsedSeconds(it.duration)}`)}`;
     lines.push(truncLine(`${STREAM_PREFIX}${line}`, width));
   }
   return lines;
 }
 
-/** list expanded：compact 基础上每 item 追加 sessionFile 路径行。 */
+/**
+ * list expanded：compact 基础之上每 item agent 用完整 ref（详情层信息优先），并追加
+ * sessionFile 路径行。
+ */
 function renderListExpanded(resp: ListResponse, theme: ThemeLike, width: number): string[] {
-  const lines = renderListCompact(resp, theme, width);
+  const lines = renderListCompact(resp, theme, width, { shortAgent: false });
   for (const it of resp.items) {
     if (it.sessionFile) {
       lines.push(truncLine(`${theme.fg("dim", `${FOOTER_PREFIX}session: `)}${it.sessionFile}`, width));

package/src/interface/tool/tool-subagents.ts

@@ -82,7 +82,7 @@ const SubagentsParams = Type.Object({
   }),
   agents: Type.Optional(Type.String({
     description:
-      "Comma-separated absolute paths to agent .md files (use <location> from <available_subagents>). " +
+      "Comma-separated absolute paths to agent .md files (usually <location> values from <available_subagents>; arbitrary absolute .md paths also work). " +
       "One path applies to every member; N paths map one-to-one onto tasks in the same order. " +
       "When more than one path is given it MUST equal the number of tasks — a mismatch fails the run fast (never a silent persona swap). " +
       "Omit for the default (general-purpose) executor.",

package/src/interface/tool/tool-workflow.ts

@@ -30,6 +30,7 @@ import { type Static, Type } from "typebox";
 
 import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core";
 import { THINKING_ORDER } from "@zhushanwen/subagent-core";
+import { displayWorkflowName } from "@zhushanwen/subagent-core";
 import type { LauncherDeps } from "@zhushanwen/subagent-core";
 import { abortRun, resumeRun, runWorkflow } from "@zhushanwen/subagent-core";
 import type { ResumeRunOptions } from "@zhushanwen/subagent-core";
@@ -86,7 +87,7 @@ const WORKFLOW_ACTIONS: readonly WorkflowAction[] = [
 const WorkflowParams = Type.Object({
   action: StringEnum(WORKFLOW_ACTIONS, { description: "Workflow action to execute" }),
   name: Type.Optional(
-    Type.String({ description: "Workflow ref: absolute path to the .js script — use the <location> value from <available_workflows> (bare names are rejected; run action)" }),
+    Type.String({ description: "Workflow ref: absolute path to a .js script — normally the <location> of a workflow from <available_workflows>, but ANY absolute .js path works if the file declares `@pi-meta kind: \"workflow\"` (the list is not required). Relative paths and bare names are rejected (run action)" }),
   ),
   slug: Type.Optional(
     Type.String({
@@ -224,7 +225,7 @@ export function registerWorkflowTool(
       "<available_workflows> (injected each turn). For parameter details, read the <location> " +
       "script file (script header has @pi-meta parameters + usage + phases). Do NOT use " +
       "workflow-script generate for patterns already covered by available workflows.",
-      "run: pass the workflow ref as name — ALWAYS the <location> absolute .js path from <available_workflows> (bare names are rejected with a not-found error listing locations).",
+      "run: pass the workflow ref as name — normally the <location> absolute .js path from <available_workflows>, but any absolute .js path with a valid @pi-meta also works (the list is not required). Bare names and relative paths are rejected with a not-found error listing locations.",
       "DO NOT bash sleep or poll status after starting — results appear automatically via notifyDone.",
       "Runs are one-shot: there is no pause — to stop a run early use abort; for a fresh result start a new run. " +
       "resume is ONLY for runs whose status is interrupted (crash or session-switch during execution): it replays " +
@@ -241,7 +242,7 @@ export function registerWorkflowTool(
       "Model/thinkingLevel: omit by default (inherit main agent's model). Only set model/thinkingLevel when the user explicitly requests a specific model or thinking depth for this run.",
       "Anti-patterns: Flattening args sub-fields (task/items/...) to the top level — they belong inside args. Calling {\"action\":\"run\"} without name.",
       "CRITICAL: For orchestration patterns, ALWAYS use action:run with the <location> absolute " +
-      "path of a listed workflow — NEVER use workflow-script action:generate to recreate patterns " +
+      "path of the matching listed workflow — NEVER use workflow-script action:generate to recreate patterns " +
       "already covered by available workflows. workflow-script generate is ONLY for novel patterns.",
     ],
     parameters: WorkflowParams,
@@ -296,7 +297,9 @@ export function registerWorkflowTool(
 
     renderCall(args: Record<string, unknown>, theme: Theme, _context?: unknown) {
       const action = String(args.action ?? "");
-      const name = args.name ? ` ${String(args.name)}` : "";
+      // workflow ref 是绝对路径，标题行显示取 basename 短名（displayWorkflowName，
+      // 与 subagent 标题行的 displayAgentName 对称）；runId/slug 不受影响。
+      const name = args.name ? ` ${displayWorkflowName(String(args.name))}` : "";
       // run action 可选 slug：在 name 后追加 · slug（accent 色）
       const slug = optionSlugSuffix(args.slug, theme);
       const runId = args.runId ? ` ${String(args.runId).slice(0, ID_PREVIEW_LENGTH)}` : "";
@@ -325,7 +328,7 @@ export async function actionRun(
   const name = params.name;
   if (!name) {
     throw new Error(
-      "run requires 'name' parameter (absolute .js path from <available_workflows> <location>). Correct: {\"action\":\"run\",\"name\":\"<ref>\"}",
+      "run requires 'name' parameter (an absolute .js path, e.g. a <location> from <available_workflows>). Correct: {\"action\":\"run\",\"name\":\"<ref>\"}",
     );
   }
   // 弱模型常见误用（P0 静默失败）：把 task/items 等 args 子字段平铺到 workflow params