@zhushanwen/pi-subagent-workflow 0.3.2 → 0.4.0

package/src/interface/__tests__/detectors.test.ts

@@ -7,40 +7,15 @@
 // literal string alive.
 //
 // Covers the detectors added in the weak-model-robustness PR:
-//   - subagent hasFlattenedStartFields (startParam envelope missing)
 //   - workflow findFlattenedArgKeys (args sub-fields flattened to top level — P0)
+//
+// NOTE: subagent hasFlattenedStartFields detector 已随 wave 3 拍平删除——
+// startParam envelope 不再存在，task/slug 平铺到顶层是合法形态，原 detector 无意义。
 
 import { describe, expect, it } from "vitest";
 
-import { hasFlattenedStartFields } from "../subagent-tool";
 import { findFlattenedArgKeys } from "../tool-workflow";
 
-describe("hasFlattenedStartFields (subagent startParam flatten detector)", () => {
-  it("triggers when task/slug flattened to top level (the original failure mode)", () => {
-    expect(hasFlattenedStartFields({ action: "start", task: "x", slug: "s" })).toBe(true);
-    expect(hasFlattenedStartFields({ action: "start", task: "x" })).toBe(true);
-    expect(hasFlattenedStartFields({ action: "start", slug: "s" })).toBe(true);
-  });
-
-  it("does NOT trigger when startParam envelope is present (correct nesting)", () => {
-    expect(
-      hasFlattenedStartFields({ action: "start", startParam: { task: "x", slug: "s" } }),
-    ).toBe(false);
-  });
-
-  it("does NOT trigger when neither task nor slug is present", () => {
-    expect(hasFlattenedStartFields({ action: "start" })).toBe(false);
-    expect(hasFlattenedStartFields({ action: "list" })).toBe(false);
-  });
-
-  it("returns false for non-object input", () => {
-    expect(hasFlattenedStartFields(null)).toBe(false);
-    expect(hasFlattenedStartFields(undefined)).toBe(false);
-    expect(hasFlattenedStartFields("start")).toBe(false);
-    expect(hasFlattenedStartFields(42)).toBe(false);
-  });
-});
-
 describe("findFlattenedArgKeys (workflow args flatten detector — P0)", () => {
   it("triggers when args sub-fields flattened to top level", () => {
     expect(findFlattenedArgKeys({ action: "run", name: "chain", task: "x" })).toEqual(["task"]);

package/src/interface/__tests__/subagent-tool-prompt.test.ts

@@ -85,23 +85,66 @@ describe("subagent tool description — 行为约束器（非功能说明书）"
     expect(DESCRIPTION).toMatch(/SAME message/i);
   });
 
-  it("Examples 段含完整 JSON 正例（含 startParam 嵌套结构）", () => {
-    // 弱模型信任 schema 结构信号 > 文本信号，容易把 task/slug 平铺到顶层。
-    // description 必须有完整 JSON 正例，让模型能直接照抄 startParam 嵌套结构。
-    expect(DESCRIPTION).toContain('{"action":"start","startParam"');
+  it("Examples 段含平铺 JSON 正例（task/slug 在顶层，无 startParam envelope）", () => {
+    // 弱模型信任 schema 结构信号 > 文本信号，原本嵌套 startParam 容器经常被省略。
+    // 现已拍平：task/slug 等 13 字段直接放在顶层。description 必须有完整平铺 JSON 正例，
+    // 让模型能直接照抄。强约束：startParam envelope 必须从 description 中彻底消失。
+    expect(DESCRIPTION).toContain('"action":"start","task"');
+    expect(DESCRIPTION).not.toContain('"startParam"');
   });
 
-  it("Anti-patterns 段含参数结构反例（top level 平铺 task/slug）", () => {
-    // 显式说明 task/slug 不能平铺到顶层，必须嵌在 startParam 里。
-    expect(DESCRIPTION).toContain("top level");
+  it("cancel 示例 subagentId 用 sa- 连字符前缀（与 subagent-service.ts 实际生成格式一致）", () => {
+    // subagent-service.ts:600 生成 `sa-${crypto.randomUUID()}`（连字符）。
+    // description 示例必须与实际生成格式一致——弱模型会照抄示例，前缀错（如 sa_ 下划线）
+    // 会导致 subagentId 永远匹配不到真实 record。
+    expect(DESCRIPTION).toContain('"subagentId":"sa-');
+    expect(DESCRIPTION).not.toContain('"sa_');
+  });
+
+  it("agent 枚举（schema 字段 description）包含全部 9 个内置 agent（含 orchestrator，防漏）", () => {
+    // 包内有 9 个 agent .md（含 orchestrator）。schema 的 agent 字段 description 必须全部列出，
+    // 否则 LLM 无法选中未列出的 agent（功能回归）。cr-fix 防回归锁定。
+    // 注意：agent 列表在 schema field description 里，不在主 description: 模板字符串里——
+    // 断言源码全文（含 schema field description）而非 DESCRIPTION。
+    const expected = [
+      "general-purpose", "worker", "researcher", "explorer",
+      "planner", "reviewer", "oracle", "context-builder", "orchestrator",
+    ];
+    for (const name of expected) {
+      expect(SUBAGENT_TOOL_SRC).toContain(name);
+    }
+  });
+
+  it("Anti-patterns 段明确 list/cancel 仍 nested（防过度泛化 flatten）", () => {
+    // PR 只拍平 start，listParam/cancelParam 仍 nested。description 必须明确这一不对称性，
+    // 否则弱模型学了「subagent tool 现在平铺」会过度泛化发 {"action":"list","includeFinished":true}。
+    const apIdx = DESCRIPTION.indexOf("## Anti-patterns");
+    expect(apIdx).toBeGreaterThan(-1);
+    const afterAp = DESCRIPTION.slice(apIdx);
+    const nextSection = afterAp.indexOf("##", "## Anti-patterns".length);
+    const apSection = nextSection > -1 ? afterAp.slice(0, nextSection) : afterAp;
+    expect(apSection).toMatch(/list.*nested.*listParam|listParam.*nested/i);
   });
 });
 
 describe("subagent tool runtime handler — 错误文案含纠正正例", () => {
-  // 读源码文本断言 executeSubagent 的平铺检测 throw 含 Correct 正例，
+  // 读源码文本断言 startHandler throw 含 Correct 正例，
   // 让弱模型撞错后第二次能直接照抄正确形态。
-  it("subagent-tool.ts 含 runtime 平铺检测 throw + Correct 纠正正例", () => {
-    expect(SUBAGENT_TOOL_SRC).toContain("Correct:");
-    expect(SUBAGENT_TOOL_SRC).toContain("params.action === \"start\" && !params.startParam");
+  // 拍平后：startParam envelope 删除，平铺 task/slug 是合法形态；
+  // 平铺检测 guard（hasFlattenedStartFields）已删除，源码不应再含此表达式。
+  it("subagent-actions.ts startHandler throw 含 Correct 纠正正例（平铺形态）", () => {
+    const actionsSrc = readFileSync(
+      join(__dirname, "../subagent-actions.ts"),
+      "utf-8",
+    );
+    // 三处 throw（input 缺失 / task 空白 / slug 空白）都应含 Correct 正例。
+    // 用 occurrences 计数——至少 3 处。
+    const occurrences = (actionsSrc.match(/Correct: \{"action":"start"/g) ?? []).length;
+    expect(occurrences).toBeGreaterThanOrEqual(3);
+  });
+
+  it("平铺检测 guard（hasFlattenedStartFields）已从 subagent-tool.ts 删除", () => {
+    expect(SUBAGENT_TOOL_SRC).not.toContain('params.action === "start" && !params.startParam');
+    expect(SUBAGENT_TOOL_SRC).not.toContain("hasFlattenedStartFields");
   });
 });

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

@@ -0,0 +1,122 @@
+// src/interface/__tests__/tool-render.test.ts
+//
+// renderSubagentCall 行为测试：拍平后从顶层 args 提取 agent/slug/task。
+//
+// 背景：wave 3 flatten 把 task/slug/agent 等 13 字段从 args.startParam 嵌套层
+// 移到 args 顶层。renderSubagentCall 的提取逻辑跟着改了，但之前无行为测试覆盖
+// （sdk-contract.test.ts 只断言 renderCall 是 function，不断言行为）。此测试
+// 锁住「拍平形态的 args 能被 renderSubagentCall 正确提取」——若有人改回
+// args.startParam 路径，测试立即红。
+//
+// 不走 registerSubagentTool 注册路径——renderSubagentCall 是纯函数，直接 import
+// 测试，避免 mock pi-ai/typebox/pi-tui 整条链。
+
+import { describe, expect, it } from "vitest";
+
+import type { Component } from "@earendil-works/pi-tui";
+
+import { type RenderContext, renderSubagentCall } from "../tool-render.ts";
+
+// ── 最小 ThemeLike stub ──
+// renderSubagentCall 只用 theme.fg/bold/dim（都是 (token, text) => string）。
+// 不依赖真实 pi-tui 着色——我们只断言提取出的字符串出现在结果里。
+function makeTheme(): {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+} {
+  return {
+    // 把 token 作为 [token:...] 包裹器返回，便于断言时不依赖颜色映射。
+    fg: (_color, text) => `<${_color}>${text}</${_color}>`,
+    bold: (text) => `<b>${text}</b>`,
+  };
+}
+
+// Text.render() 是 pi-tui 的方法。tool-render 返回 new Text(parts.join(""), 0, 0)。
+// 测试只关心 parts.join("") 的文本内容——用反射取构造时传入的字符串。
+// Component 类型在 pi-tui 中是 opaque，这里用最小的反射 helper。
+function renderText(component: Component): string {
+  // Text 实例在 pi-tui v0.x 把构造首参存为 .text 或私有字段；
+  // 通过遍历可枚举属性找到首个 string 字段（绕过具体字段名差异）。
+  const obj = component as unknown 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 "";
+}
+
+const CTX: RenderContext = {
+  state: {} as Record<string, never>,
+  invalidate: () => {},
+};
+
+describe("renderSubagentCall — 拍平形态提取（regression for wave 3 flatten）", () => {
+  it("从顶层 args 提取 agent（默认 general-purpose）", () => {
+    const out = renderText(renderSubagentCall(
+      { action: "start", task: "do stuff", slug: "x" },
+      makeTheme() as never,
+      CTX,
+    ));
+    // 默认 agent 名（DEFAULT_AGENT_NAME）出现在结果里
+    expect(out).toContain("general-purpose");
+  });
+
+  it("从顶层 args 提取显式 agent 名", () => {
+    const out = renderText(renderSubagentCall(
+      { action: "start", agent: "worker", task: "do stuff", slug: "x" },
+      makeTheme() as never,
+      CTX,
+    ));
+    expect(out).toContain("worker");
+  });
+
+  it("从顶层 args 提取 slug 并在 agent 后展示", () => {
+    const out = renderText(renderSubagentCall(
+      { action: "start", agent: "worker", task: "do stuff", slug: "fix-login" },
+      makeTheme() as never,
+      CTX,
+    ));
+    expect(out).toContain("worker");
+    expect(out).toContain("fix-login");
+  });
+
+  it("从顶层 args 提取 task 作为 preview 行（含换行）", () => {
+    const out = renderText(renderSubagentCall(
+      { action: "start", agent: "worker", task: "Analyze the bug in parser", slug: "fix-parser" },
+      makeTheme() as never,
+      CTX,
+    ));
+    // task preview 出现在结果里（首行非空，截断到 60 字符）
+    expect(out).toContain("Analyze the bug in parser");
+  });
+
+  it("task 含换行时只取首个非空行（不破坏单行渲染）", () => {
+    const out = renderText(renderSubagentCall(
+      { action: "start", task: "first line\nsecond line", slug: "x" },
+      makeTheme() as never,
+      CTX,
+    ));
+    expect(out).toContain("first line");
+    expect(out).not.toContain("second line");
+  });
+
+  // 关键回归：若有人把提取路径改回 args.startParam，这些顶层调用都会失败
+  // （agent/slug/task 取不到，全用默认值）。此测试用顶层数据形态锁住 flatten。
+  it("REGRESSION: 顶层 args 形态完整提取（防止回退到 startParam envelope）", () => {
+    const out = renderText(renderSubagentCall(
+      { action: "start", agent: "researcher", task: "search docs", slug: "search-docs" },
+      makeTheme() as never,
+      CTX,
+    ));
+    // 三个字段都应被提取（默认值 fallback 也能过单字段断言，但同时命中的
+    // 概率只有联合 fallback 才有——researcher/search-docs 都不是默认值）
+    expect(out).toContain("researcher");
+    expect(out).toContain("search-docs");
+    expect(out).toContain("search docs");
+  });
+
+  it("args 缺所有字段时不崩（最防御）", () => {
+    expect(() => renderSubagentCall({}, makeTheme() as never, CTX)).not.toThrow();
+    expect(() => renderSubagentCall(undefined, makeTheme() as never, CTX)).not.toThrow();
+  });
+});

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

@@ -44,7 +44,7 @@ describe("U1: workflow tool prompt mentions built-in workflows", () => {
     expect(TOOL_WORKFLOW_SRC).toMatch(/workflow run .+--args/i);
   });
 
-  it("promptGuidelines 含 JSON 调用正例（run/status/lifecycle/retry-node）", () => {
+  it("promptGuidelines 含 JSON 调用正例（run/status/lifecycle）", () => {
     // 弱模型信任 schema 结构信号 > 文本信号，容易把 args 子字段平铺到顶层。
     // promptGuidelines 必须有完整 JSON 调用正例，让模型能直接照抄 {"action":"run",...} 嵌套结构。
     expect(TOOL_WORKFLOW_SRC).toContain('{"action":"run"');

package/src/interface/format.ts

@@ -95,15 +95,19 @@ const SHORT_ID_BG_SEGMENTS = 3;
 /**
  * 从完整 record id 提取短编号用于列表展示.
  *
- * id 格式（subagent-service.ts:422 生成）:
- *   - sync:       `run-${seq}`                  (如 run-1) → 原样（2 段）
- *   - background: `bg-${tag}-${seq}-${ts}`      (如 bg-f6f731-10-1719500000000)
- *                 → 取前 3 段得 bg-f6f731-10（丢弃冗长时间戳）
- *
- * 按段数分支：sync（2 段）原样返回；background（≥3 段）取前 3 段（bg/tag/seq）。
- * seq 进程内递增唯一,作为「编号」足够区分;完整 id(含时间戳)在右列预览给出供精确引用.
+ * id 格式:
+ *   - subagent:   `sa-<uuid>`                   (如 sa-550e8400-e29b-41d4-a716-446655440000)
+ *                 → sa- 前缀 + UUID 前 3 段（sa-550e8400-e29b-41d4）
+ *   - workflow:   `wf-<ts>-<rand>`               (如 wf-1719500000000-a1b2c3，3 段)
+ *                 → 3 段 ≤ 2 不成立，取前 3 段 = 原样
+ *   - sync:       `run-${seq}`                   (如 run-1，2 段) → 原样返回
+ *   - 旧纯 UUID:  `<uuid>`                       (5 段) → 取前 3 段（向后兼容）
  */
 export function shortId(id: string): string {
+  // sa- 前缀的 subagent ID：保留前缀 + UUID 前 3 段（与纯 UUID 的 3 段信息量等价）
+  if (id.startsWith("sa-")) {
+    return "sa-" + id.slice(3).split("-").slice(0, SHORT_ID_BG_SEGMENTS).join("-");
+  }
   const segments = id.split("-");
   if (segments.length <= SHORT_ID_SYNC_SEGMENTS) return id;
   return segments.slice(0, SHORT_ID_BG_SEGMENTS).join("-");

package/src/interface/subagent-actions.ts

@@ -49,7 +49,9 @@ const SUBAGENT_ID_PREVIEW = 8;
 // 入参 / 出参类型
 // ============================================================
 
-/** start 入参（从 tool params.startParam 来，task + slug 必填）。 */
+/** start 入参（拍平后从 tool params 顶层来，task + slug 必填）。
+ *  StartHandlerInput 是 SubagentExecuteParams 的子集（13 字段全 optional）；
+ *  调用方传整个 params（含 action/listParam/cancelParam），多余字段被忽略。 */
 export interface StartHandlerInput {
   task?: string;
   /** 短标签（≤35 字符，kebab-case），必填。 */
@@ -137,14 +139,23 @@ export async function startHandler(
   signal: AbortSignal | undefined,
   ctxModel?: ModelInfo,
 ): Promise<StartHandlerResult> {
-  if (!input) throw new Error("startParam is required for action:'start'");
+  if (!input) throw new Error(
+    "action:'start' requires task and slug (top-level fields). " +
+    'Correct: {"action":"start","task":"<your task>","slug":"<kebab-case>"}',
+  );
   // task 必填 + 空白校验（G-008）
   const task = input.task?.trim();
-  if (!task) throw new Error("startParam.task is required (and must not be whitespace-only)");
+  if (!task) throw new Error(
+    "task is required for action:'start' (top-level field, must not be whitespace-only). " +
+    'Correct: {"action":"start","task":"...","slug":"..."}',
+  );
   // slug 必填 + 空白校验 + 长度校验（≤ SLUG_MAX_LENGTH 字符）
   const slug = input.slug?.trim();
-  if (!slug) throw new Error("startParam.slug is required (and must not be whitespace-only)");
-  if (slug.length > SLUG_MAX_LENGTH) throw new Error(`startParam.slug must be ≤${SLUG_MAX_LENGTH} chars (got ${slug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`);
+  if (!slug) throw new Error(
+    "slug is required for action:'start' (top-level field, must not be whitespace-only). " +
+    'Correct: {"action":"start","task":"...","slug":"<kebab-case>"}',
+  );
+  if (slug.length > SLUG_MAX_LENGTH) throw new Error(`slug must be ≤${SLUG_MAX_LENGTH} chars (got ${slug.length}). Shorten to a kebab-case label, e.g. "fix-login", "extract-urls".`);
 
   const handle = await service.execute({
     task,

package/src/interface/subagent-tool.ts

@@ -31,23 +31,6 @@ import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./t
  * 无法从 SubagentParams schema 反向推断参数类型）。
  * action 与对应 param 不匹配时 handler 内 throw。
  */
-interface StartParam {
-  task: string;
-  /** 短标签（≤35 字符，kebab-case），必填。展示在 TUI 标题行/列表。 */
-  slug: string;
-  agent?: string;
-  model?: string;
-  thinkingLevel?: string;
-  skillPath?: string;
-  appendSystemPrompt?: string[];
-  schema?: Record<string, unknown>;
-  maxTurns?: number;
-  graceTurns?: number;
-  fork?: boolean;
-  worktree?: boolean;
-  cwd?: string;
-}
-
 interface ListParam {
   includeFinished?: boolean;
   limit?: number;
@@ -59,7 +42,22 @@ interface CancelParam {
 
 interface SubagentExecuteParams {
   action: "start" | "list" | "cancel";
-  startParam?: StartParam;
+  // action:"start" 的 13 字段拍平到顶层（弱模型常省略 startParam 嵌套层导致调用失败）。
+  // 拍平后这些字段直接在顶层（全部 optional——schema flat 无法表达「action 条件必填」，
+  // 由 startHandler runtime 校验 task/slug 必填）。
+  task?: string;
+  slug?: string;
+  agent?: string;
+  model?: string;
+  thinkingLevel?: string;
+  skillPath?: string;
+  appendSystemPrompt?: string[];
+  schema?: Record<string, unknown>;
+  maxTurns?: number;
+  graceTurns?: number;
+  fork?: boolean;
+  worktree?: boolean;
+  cwd?: string;
   listParam?: ListParam;
   cancelParam?: CancelParam;
 }
@@ -89,54 +87,56 @@ type SubagentRenderResultCb = (
 
 // Params schema（模块内消费，未导出）。
 //
-// TODO(long-term, option-A): startParam/listParam/cancelParam 全标 Optional 是 flat
-// JSON Schema 表达「action 分发的条件必填」的妥协——required[] 只能表达静态必填，
-// 无法表达「action:"start" 时 startParam 必填、action:"list" 时不需要」。长期方案是
-// 拆成 3 个独立 tool（subagent_start / subagent_list / subagent_cancel），让每个 tool
-// 的 schema 真实反映必填性，消除全新上下文下的字段误判。当前靠 description 强标记 +
-// runtime guard（subagent-actions.ts startHandler/cancelHandler throw）兜底。
-// 勿在此基础上继续堆 action 条件逻辑——要加就拆 tool。
+// action:"start" 的 13 字段（task/slug/agent/model/...）拍平在顶层，不再用 startParam
+// 嵌套容器包。原因：弱模型（GLM/DeepSeek）信任 schema 结构信号 > 文本信号，经常省略
+// startParam 嵌套层把 task/slug 直接平铺到顶层导致调用失败。拍平后 schema 结构与模型
+// 的自然倾向一致，消除这层误用。task/slug 必填性由 startHandler runtime 校验（flat
+// JSON Schema 无法表达「action 条件必填」）。
+//
+// TODO(long-term, option-A): listParam/cancelParam 仍标 Optional 也是 flat JSON Schema
+// 表达「action 分发条件必填」的妥协——长期方案是拆成 3 个独立 tool
+// （subagent_start / subagent_list / subagent_cancel），让每个 tool 的 schema 真实
+// 反映必填性。勿在此基础上继续堆 action 条件逻辑——要加就拆 tool。
 const SubagentParams = Type.Object({
   action: StringEnum(["start", "list", "cancel"], {
     description: "Operation: 'start' runs a subagent, 'list' shows running subagents (optional includeFinished), 'cancel' stops a background subagent by id.",
   }),
-  // action:"start" → startParam REQUIRED. Missing/empty task or slug throws at runtime.
+  // ── action:"start" fields (flattened to top level). task/slug REQUIRED for start. ──
+  // Missing/empty task or slug throws at runtime (startHandler).
   // (flat JSON Schema can't express conditional requirement — see file-level TODO.)
-  startParam: Type.Optional(Type.Object({
-    task: Type.String({
-      description: "REQUIRED for action:'start'. The task for the subagent to execute. Throws if missing or whitespace-only.",
-    }),
-    slug: Type.String({
-      description:
-        "REQUIRED for action:'start'. Short label (≤35 chars) for this subagent, e.g. 'fix-login', 'extract-urls'. " +
-        "Shown in TUI to distinguish concurrent subagents.",
-      maxLength: SLUG_MAX_LENGTH,
-    }),
-    agent: Type.Optional(Type.String({
-      description: 'Agent name (system prompt + tools). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Available: general-purpose (default fallback), worker, researcher, explorer, planner, reviewer, oracle, context-builder. Custom agents configurable.',
-    })),
-    model: Type.Optional(Type.String({
-      description: 'Model override in "provider/modelId" format. 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.',
-    })),
-    thinkingLevel: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const)),
-    skillPath: Type.Optional(Type.String()),
-    appendSystemPrompt: Type.Optional(Type.Array(Type.String())),
-    schema: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-    maxTurns: Type.Optional(Type.Number({
-      description: "Turn limit. The subagent is terminated via SIGTERM after maxTurns turn_end events + graceTurns of slack. There is no graceful wrap-up message — the process is killed. 0 or omitted = unlimited.",
-    })),
-    graceTurns: Type.Optional(Type.Number({
-      description: "Extra turns allowed after maxTurns is reached before SIGTERM (default 2). Only meaningful when maxTurns is set.",
-    })),
-    fork: Type.Optional(Type.Boolean({
-      description: "Fork mode: inherit the parent's conversation context. When true, the subagent receives the parent's session file via --fork and builds a branched conversation (it sees prior turns/messages). The subagent still runs in a separate spawned child process (process isolation) — fork is about context inheritance, not process sharing. Use worktree:true (requires fork:true) for file-system isolation.",
-    })),
-    worktree: Type.Optional(Type.Boolean({
-      description: "Worktree isolation (requires fork:true): run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session. Prevents concurrent file-write conflicts between parent and subagent. Only takes effect when fork:true; passing worktree:true without fork:true throws an error.",
-    })),
-    cwd: Type.Optional(Type.String({
-      description: 'Override the working directory for the subagent execution. Must be an absolute path. Defaults to the parent session\'s cwd.',
-    })),
+  task: Type.Optional(Type.String({
+    description: "REQUIRED for action:'start'. The task for the subagent to execute. Throws if missing or whitespace-only.",
+  })),
+  slug: Type.Optional(Type.String({
+    description:
+      "REQUIRED for action:'start'. Short label (≤35 chars) for this subagent, e.g. 'fix-login', 'extract-urls'. " +
+      "Shown in TUI to distinguish concurrent subagents.",
+    maxLength: SLUG_MAX_LENGTH,
+  })),
+  agent: Type.Optional(Type.String({
+    description: 'Agent name (system prompt + tools). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Available: general-purpose (default fallback), worker, researcher, explorer, planner, reviewer, oracle, context-builder, orchestrator. Custom agents configurable.',
+  })),
+  model: Type.Optional(Type.String({
+    description: 'Model override in "provider/modelId" format. 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.',
+  })),
+  thinkingLevel: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const)),
+  skillPath: Type.Optional(Type.String()),
+  appendSystemPrompt: Type.Optional(Type.Array(Type.String())),
+  schema: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  maxTurns: Type.Optional(Type.Number({
+    description: "Turn limit. The subagent is terminated via SIGTERM after maxTurns turn_end events + graceTurns of slack. There is no graceful wrap-up message — the process is killed. 0 or omitted = unlimited.",
+  })),
+  graceTurns: Type.Optional(Type.Number({
+    description: "Extra turns allowed after maxTurns is reached before SIGTERM (default 2). Only meaningful when maxTurns is set.",
+  })),
+  fork: Type.Optional(Type.Boolean({
+    description: "Fork mode: inherit the parent's conversation context. When true, the subagent receives the parent's session file via --fork and builds a branched conversation (it sees prior turns/messages). The subagent still runs in a separate spawned child process (process isolation) — fork is about context inheritance, not process sharing. Use worktree:true (requires fork:true) for file-system isolation.",
+  })),
+  worktree: Type.Optional(Type.Boolean({
+    description: "Worktree isolation (requires fork:true): run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session. Prevents concurrent file-write conflicts between parent and subagent. Only takes effect when fork:true; passing worktree:true without fork:true throws an error.",
+  })),
+  cwd: Type.Optional(Type.String({
+    description: 'Override the working directory for the subagent execution. Must be an absolute path. Defaults to the parent session\'s cwd.',
   })),
   // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
   listParam: Type.Optional(Type.Object({
@@ -171,22 +171,8 @@ function isModelOverrideObj(a: unknown): a is { model?: unknown; thinkingLevel?:
   return typeof a === "object" && a !== null;
 }
 
-/** unknown args 是否含 startParam（类型守卫，替代 `in` 后的 `as`）。 */
-function hasStartParam(a: unknown): a is { startParam?: unknown } {
-  return typeof a === "object" && a !== null && "startParam" in a;
-}
-
-/** action:'start' 入参是否把 task/slug 平铺到顶层（弱模型常见误用：缺 startParam 嵌套）。 */
-/**
- * action:'start' 入参是否把 task/slug 平铺到顶层（弱模型常见误用：缺 startParam 嵌套）。
- * export 供 behavioral 测试（trigger/no-trigger），不改变运行时行为。
- */
-export function hasFlattenedStartFields(a: unknown): boolean {
-  if (typeof a !== "object" || a === null) return false;
-  return "task" in a || "slug" in a;
-}
-
-/** 从 unknown args 安全提取 model/thinkingLevel override（传给 resolveModel）。 */
+/** 从 unknown args 安全提取 model/thinkingLevel override（传给 resolveModel）。
+ *  拍平后 args 已是顶层平铺结构（model/thinkingLevel 直接在 args 上）。 */
 function extractModelOverride(args: unknown): { model?: string; thinkingLevel?: string } | undefined {
   if (!isModelOverrideObj(args)) return undefined;
   const override: { model?: string; thinkingLevel?: string } = {};
@@ -214,17 +200,17 @@ Delegate when the task needs a distinct role (researcher/worker), context isolat
 
 ## Actions
 
-- action:"start" — run a subagent. REQUIRED startParam: { task, slug, ... } (task and slug REQUIRED). Background only: returns a subagentId immediately, notifies on completion.
+- action:"start" — run a subagent. Pass task and slug as top-level fields (REQUIRED). Optional: agent, model, thinkingLevel, skillPath, appendSystemPrompt, schema, maxTurns, graceTurns, fork, worktree, cwd. Background only: returns a subagentId immediately, notifies on completion.
 - action:"list" — list subagents. Pass listParam: { includeFinished?, limit? } (all optional). Read an item's sessionFile for full detail.
 - action:"cancel" — cancel a background subagent. REQUIRED cancelParam: { subagentId }.
 
 ## Examples
 
 \`\`\`
-{"action":"start","startParam":{"task":"<your task>","slug":"<kebab-case>"}}
-{"action":"start","startParam":{"task":"...","slug":"fix-login","agent":"worker","model":"anthropic/claude-3.5-sonnet","fork":true}}
+{"action":"start","task":"<your task>","slug":"<kebab-case>"}
+{"action":"start","task":"...","slug":"fix-login","agent":"worker","model":"anthropic/claude-3.5-sonnet","fork":true}
 {"action":"list","listParam":{"includeFinished":false,"limit":20}}
-{"action":"cancel","cancelParam":{"subagentId":"sa_abc123"}}
+{"action":"cancel","cancelParam":{"subagentId":"sa-550e8400"}}
 \`\`\`
 
 ## After launching — do NOT wait
@@ -237,7 +223,8 @@ Completion auto-notifies you (steer wakes next turn, even mid-poll). So:
 
 ## Anti-patterns
 
-- Putting task/slug at the top level instead of inside startParam — the tool reads startParam.task, not a top-level task.
+- Forgetting the REQUIRED top-level task/slug fields for action:"start" — both must be present at the top level (not nested).
+- Over-generalizing the flatten: ONLY start fields are top-level. list and cancel params stay nested under listParam / cancelParam (e.g. {"action":"list","listParam":{"includeFinished":true}}, NOT {"action":"list","includeFinished":true}).
 - Launching background, then sleeping/polling instead of working or stopping.
 - Treating subagent results as authoritative without verification.
 - Delegating trivial tasks you could do faster yourself.
@@ -278,9 +265,10 @@ const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
   // 主 agent model 由 ModelConfigService 缓存（session_start 注入，model_select 刷新），
   // 补偿 renderCall 的 ToolRenderContext 不含 model 的 SDK 限制。
   // service 未就绪 / 缓存为空 / 解析失败 → 降级不显示 model。
-  const startParam = hasStartParam(args) ? args.startParam : undefined;
-  const agent = extractAgentName(startParam);
-  const override = extractModelOverride(startParam);
+  // 拍平后 args 已是顶层平铺结构（agent/model/thinkingLevel 直接在 args 上），
+  // extractAgentName / extractModelOverride 都是 unknown-safe 顶层读取，对平铺形态天然兼容。
+  const agent = extractAgentName(args);
+  const override = extractModelOverride(args);
   let resolved: { model: string; thinkingLevel?: string } | undefined;
   try {
     const service = getSubagentService();
@@ -309,7 +297,7 @@ const subagentRenderResult: SubagentRenderResultCb = (result, options, theme, ct
  *   ║  service = getSubagentService() —— 未初始化 throw                  ║
  *   ║                                                                    ║
  *   ║  switch(params.action):                                           ║
- *   ║    "start"  → startHandler(service, params.startParam, signal) → 领域对象  ║
+ *   ║    "start"  → startHandler(service, params, signal) → 领域对象       ║
  *   ║    "list"   → listHandler(service, params.listParam) → 领域对象    ║
  *   ║    "cancel" → cancelHandler(service, params.cancelParam) → 领域对象║
  *   ║                                                                    ║
@@ -317,6 +305,10 @@ const subagentRenderResult: SubagentRenderResultCb = (result, options, theme, ct
  *   ║  return { content: [{text: JSON.stringify(result)}], details: result }║
  *   ╚══════════════════════════════════════════════════════════════════╝
  *
+ * 拍平后 startHandler 直接接收顶层 params（13 字段已在顶层）。startHandler 的入参
+ * 类型 StartHandlerInput 是 SubagentExecuteParams 的子集（13 字段全 optional），
+ * 结构兼容——SubagentExecuteParams 多出的 action/listParam/cancelParam 被忽略。
+ *
  * handler 返回纯领域对象（不碰 {content, details}），adapter 唯一包装。
  * content（JSON 字符串）给 LLM，details（领域对象 + action）给 renderResult，同源。
  */
@@ -332,20 +324,11 @@ const executeSubagent: SubagentExecuteCb = async (
   const service = getSubagentService();
   if (!service) throw new Error("subagents runtime not initialized");
 
-  // 弱模型常见误用：action:'start' 时把 task/slug 平铺到顶层（缺 startParam 嵌套层）。
-  // schema 用 Type.Optional 表达条件必填（flat JSON Schema 无法表达），弱模型信任
-  // 结构信号 > 文本信号，倾向省略嵌套层。这里在进 startHandler 之前拦截平铺形态，
-  // throw 带 Correct 正例，让弱模型撞错后第二次能直接照抄。
-  if (params.action === "start" && !params.startParam && hasFlattenedStartFields(params)) {
-    throw new Error(
-      "startParam is required for action:'start' — wrap task/slug inside startParam. " +
-      "Correct: {\"action\":\"start\",\"startParam\":{\"task\":\"<your task>\",\"slug\":\"<kebab-case>\"}}",
-    );
-  }
-
   switch (params.action) {
     case "start":
-      return adapter({ action: "start", domain: await startHandler(service, params.startParam, signal, _ctx?.model) }, toGuiCtx(_ctx));
+      // 拍平后直接传顶层 params（StartHandlerInput 是 SubagentExecuteParams 子集，
+      // action/listParam/cancelParam 被忽略；task/slug 必填性由 startHandler 校验）。
+      return adapter({ action: "start", domain: await startHandler(service, params, signal, _ctx?.model) }, toGuiCtx(_ctx));
     case "list":
       return adapter({ action: "list", domain: listHandler(service, params.listParam) }, toGuiCtx(_ctx));
     case "cancel":

package/src/interface/tool-render.ts

@@ -92,15 +92,13 @@ export function renderSubagentCall(
   resolved?: { model: string; thinkingLevel?: string },
 ): Component {
   const t = theme as ThemeLike;
-  // args 结构：{ action:"start", startParam:{ agent, task, ... } }（见 subagent-tool.ts schema）。
-  // 从 startParam 提取 agent + task，对齐 nicobailon 的 renderCall 多行布局。
-  const startParam = typeof args === "object" && args !== null && "startParam" in args
-    ? (args as { startParam?: unknown }).startParam
-    : undefined;
-  const agent = extractAgentName(startParam);
-  // slug：从 startParam 提取（必填字段），非空时在 agent 后用 · 分隔展示。
-  const slug = typeof startParam === "object" && startParam !== null && "slug" in startParam
-    ? (startParam as { slug?: unknown }).slug
+  // args 结构（拍平后）：{ action:"start", agent, task, slug, ... }（见 subagent-tool.ts schema）。
+  // 13 字段直接在顶层，extractAgentName / slug / task 都从 args 顶层提取，
+  // 对齐 nicobailon 的 renderCall 多行布局。
+  const agent = extractAgentName(args);
+  // slug：从顶层 args 提取（必填字段），非空时在 agent 后用 · 分隔展示。
+  const slug = typeof args === "object" && args !== null && "slug" in args
+    ? (args as { slug?: unknown }).slug
     : undefined;
   const slugStr = typeof slug === "string" ? slug.trim() : "";
   const parts = slugStr
@@ -122,8 +120,8 @@ export function renderSubagentCall(
   // task preview 行——对齐 nicobailon：renderCall 输出多行（标题 + \n + task 预览）。
   // 实验假设：call 多行让首帧（无 result）与后续帧（有 result）的高度跳变模式
   // 与 nicobailon 一致，可能影响 pi diff 引擎的行对齐路径。preview 截断到 60 字符。
-  const task = typeof startParam === "object" && startParam !== null && "task" in startParam
-    ? (startParam as { task?: unknown }).task
+  const task = typeof args === "object" && args !== null && "task" in args
+    ? (args as { task?: unknown }).task
     : undefined;
   if (typeof task === "string" && task.length > 0) {
     // task 取首行——prompt 常含换行（多行指令），直接 slice 会保留 \n，