@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

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

@@ -0,0 +1,156 @@
+// src/interface/subagent-tool-schema.ts
+//
+// `subagent` 工具的参数 schema 纯常量叶子（零运行时依赖，先例 shared/schema-env.ts）。
+//
+// 抽取自 subagent-tool.ts（跨包契约另一半）：subagent-tool 依赖树沉重（pi SDK /
+// handler / render 链），structured-output 侧的跨包契约测试若从它 import schema
+// 会把整条依赖树拖进测试进程。本模块只含 schema 常量，运行时 import 仅
+// typebox（Type 构造）与 pi-ai（StringEnum helper），为 structured-output 侧
+//（及任何消费者）的跨包契约测试提供稳定 import 点。
+//
+// [跨包契约] structured-output 的 cross-package-contract.test.ts 经真实 typebox
+// 编译本 schema 并断言 required/description/enum/pattern 存活——SW 自身测试环境
+// 把 typebox alias 到 mock（丢 options），SO 侧测试以真实构造为对照基准。
+//
+// 层归属：Interface（工具 schema 的家）。SLUG_MAX_LENGTH 随 schema 迁入：
+// 它的唯一语义就是 tool schema 的 maxLength（见原 execute-options-mapper 注释），
+// execution 侧经 re-export 保持既有 import 路径不变。
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+import { THINKING_ORDER } from "../shared/model-ref.ts";
+
+/**
+ * slug 最大长度（字符）。subagent/workflow 创建时 slug 超过此值会被截断。
+ * subagent/workflow tool schema 的 maxLength 引用此常量（单一真相，勿再硬编码）。
+ * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/"fix-subagent-wf-tools"（21）
+ * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
+ */
+export const SLUG_MAX_LENGTH = 35;
+
+// Params schema（跨包契约测试的真实 typebox 校验入口）。
+//
+// 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。
+export const SubagentParams = Type.Object({
+  action: StringEnum(["start", "list", "cancel", "message", "close"], {
+    description: "Operation: 'start' runs a subagent, 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to a running subagent (one-shot subagents are auto-upgraded to conversation mode on first message), 'close' ends a running subagent (conversation-mode or one-shot).",
+  }),
+  // ── 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.)
+  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 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.',
+  })),
+  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.',
+  })),
+  thinkingLevel: Type.Optional(StringEnum(THINKING_ORDER, {
+    description: "Thinking depth override (derived from THINKING_ORDER SSOT, includes 'max'). Omit to default to the model's highest available level (not the main agent's level).",
+  })),
+  skillPath: Type.Optional(Type.String({
+    description:
+      "Absolute path to a skill directory, injected into the subagent's pi process via --skill " +
+      "(e.g. a path under .agents/skills/ already resolved for the caller). Must be an absolute path; " +
+      "'..' traversal segments are rejected.",
+    pattern: "^/",
+  })),
+  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; independent of worktree (file-system isolation, see worktree param). When to use: only when the task extends from the parent and genuinely needs key information from the parent's conversation history that a self-contained task prompt cannot carry — most tasks a plain prompt can describe do NOT need fork, so keep false by default and enable only when the user explicitly asks or the task truly depends on seeing prior turns. Caveat: fork drags in the parent's dispatch records and unrelated task context, polluting the subagent (it cannot tell 'context meant for me' from 'parent dispatching me'); when state lives in an external store the subagent can query (e.g., cw handoff), prefer that over fork.",
+  })),
+  worktree: Type.Optional(Type.Boolean({
+    description: "Worktree isolation: run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session (prevents concurrent file-write conflicts). Independent of fork — worktree may be combined with fork:false (file isolation does not require context inheritance). When to use: parallel development scenarios where multiple agents write files concurrently and need isolated working directories (each gets its own checkout; merge later); leave false for single-agent or read-only tasks.",
+  })),
+  cwd: Type.Optional(Type.String({
+    description: 'Override the working directory for the subagent execution. Must be an absolute path (no "~" shorthand, no relative paths); ".." segments are rejected. Defaults to the parent session\'s cwd.',
+    pattern: "^/",
+  })),
+  conversation: Type.Optional(Type.Boolean({
+    description:
+      "Enable continuous chat with this subagent. When true, the subagent stays available after each reply — you can send follow-up messages (action:'message') and it keeps the full conversation context across rounds, with no need to re-spawn or re-explain. " +
+      "\nUse conversation:true for: multi-round collaboration (iterative review-fix loops, back-and-forth refinement), any task where you expect to send follow-up messages after the initial result. " +
+      "\nOmit (or false) for: one-shot tasks — single exploration, lookup, file read, code generation that needs no follow-up. The subagent runs once, notifies on completion, and is cleaned up automatically (default). " +
+      "\nFor long-interval collaboration (each round spaced >5min apart), set conversation:true AND increase idleTimeoutMs to avoid premature timeout. " +
+      "Cost: a conversation-mode subagent holds resources (memory, and a worktree if enabled) until you explicitly end it with action:'close'. Always close when done.",
+  })),
+  idleTimeoutMs: Type.Optional(Type.Number({
+    description:
+      "Idle timeout in milliseconds for conversation-mode subagents. Controls how long an idle subagent (between rounds) stays alive before automatic cleanup. " +
+      "Default: 300000 (5min). Override for long-interval collaboration where each round is spaced >5min apart. " +
+      "Pass 0 or a negative value to DISABLE idle cleanup entirely (subagent stays alive until explicitly closed). " +
+      "Only meaningful with conversation:true; ignored for one-shot subagents.",
+  })),
+  engine: Type.Optional(StringEnum(["pi", "zcode"], {
+    description:
+      "Execution engine for this subagent. Omit to inherit the global config. " +
+      "Three-layer priority: this parameter > agent .md frontmatter engine > config.json defaultEngine. " +
+      "Non-pi engines do not support conversation/fork/worktree (rejected before the subagent is created).",
+  })),
+  // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
+  listParam: Type.Optional(Type.Object({
+    includeFinished: Type.Optional(Type.Boolean({
+      description: "Include finished (done/failed/cancelled) records. Default false (running only).",
+    })),
+    limit: Type.Optional(Type.Number({
+      description: "Max items to return. Default 20, clamped to [1, 100].",
+    })),
+  })),
+  // action:"cancel" → cancelParam.subagentId REQUIRED. Throws if missing. Ignored by other actions.
+  cancelParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'cancel'. The subagentId to cancel. Throws if missing. Only background subagents can be cancelled.",
+    }),
+  })),
+  // action:"message" → messageParam.subagentId + text REQUIRED. Any RUNNING subagent works —
+  // one-shot subagents are auto-upgraded to conversation mode on first message (SP-5); ended ones throw.
+  messageParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'message'. The subagentId to message (any running subagent; a one-shot subagent is auto-upgraded to conversation mode on first message, so you may also message one-shot subagents that are still running).",
+    }),
+    text: Type.String({
+      description: "REQUIRED for action:'message'. The message to send. Whitespace-only throws.",
+    }),
+    interrupt: Type.Optional(Type.Boolean({
+      description: "If true, interrupt the subagent's current work immediately (in-progress output stops, it switches to your new message). If false (default), the message is queued and processed after the current round completes. When the subagent is idle (between rounds), interrupt has no effect — the message always starts a new round.",
+    })),
+  })),
+  // action:"close" → closeParam.subagentId REQUIRED. Ends a running subagent (conversation-mode
+  // or one-shot — closeSubagent behavior split covers both).
+  closeParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'close'. The subagentId to close (any running subagent, conversation-mode or one-shot).",
+    }),
+    force: Type.Optional(Type.Boolean({
+      description: "If true, terminate immediately even if mid-round (in-progress work is lost). If false (default), let the current round finish, then close. When idle, the subagent closes immediately regardless.",
+    })),
+  })),
+});
+
+/** Params schema 的 Static 投影（消费方经 `Static<typeof SubagentParams>` 使用，见 subagent-tool.ts）。 */
+export type SubagentParamsStatic = Static<typeof SubagentParams>;

package/src/interface/subagent-tool.ts

@@ -9,19 +9,19 @@
 // Theme、ExtensionContext）会触发 TS2307 误报（probe5d/5f 验证）。
 // 抽到顶层后参数类型由 alias 提供，绕过该 quirk。
 
+import { isAbsolute } from "node:path";
+
 import type { Component } from "@earendil-works/pi-tui";
-import { StringEnum } from "@earendil-works/pi-ai";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
-import { type Static, Type } from "typebox";
+import type { Static } from "typebox";
 
-import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
-import { THINKING_ORDER } from "../execution/model-resolver.ts";
 import { getSubagentService } from "../execution/subagent-service.ts";
 import type { SubagentToolResult } from "../execution/types.ts";
 import { extractAgentName } from "./format.ts";
 import { toGuiCtx } from "./gui-mappers.ts";
 import { adapter, cancelHandler, closeHandler, listHandler, messageHandler, startHandler } from "./subagent-actions.ts";
+import { SubagentParams } from "./subagent-tool-schema.ts";
 import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
 
 // ============================================================
@@ -54,122 +54,14 @@ type SubagentRenderResultCb = (
   ctx: RenderContext,
 ) => Component;
 
-// ============================================================
-// Params schema
-// ============================================================
-
-// Params schema（模块内消费，未导出）。
-//
-// 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", "message", "close"], {
-    description: "Operation: 'start' runs a subagent, 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to a running subagent (one-shot subagents are auto-upgraded to conversation mode on first message), 'close' ends a running subagent (conversation-mode or one-shot).",
-  }),
-  // ── 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.)
-  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 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.',
-  })),
-  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(THINKING_ORDER, {
-    description: "Thinking depth override (derived from THINKING_ORDER SSOT, includes 'max'). Omit to default to the model's highest available level (not the main agent's level).",
-  })),
-  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; independent of worktree (file-system isolation, see worktree param). When to use: only when the task extends from the parent and genuinely needs key information from the parent's conversation history that a self-contained task prompt cannot carry — most tasks a plain prompt can describe do NOT need fork, so keep false by default and enable only when the user explicitly asks or the task truly depends on seeing prior turns. Caveat: fork drags in the parent's dispatch records and unrelated task context, polluting the subagent (it cannot tell 'context meant for me' from 'parent dispatching me'); when state lives in an external store the subagent can query (e.g., cw handoff), prefer that over fork.",
-  })),
-  worktree: Type.Optional(Type.Boolean({
-    description: "Worktree isolation: run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session (prevents concurrent file-write conflicts). Independent of fork — worktree may be combined with fork:false (file isolation does not require context inheritance). When to use: parallel development scenarios where multiple agents write files concurrently and need isolated working directories (each gets its own checkout; merge later); leave false for single-agent or read-only tasks.",
-  })),
-  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.',
-  })),
-  conversation: Type.Optional(Type.Boolean({
-    description:
-      "Enable continuous chat with this subagent. When true, the subagent stays available after each reply — you can send follow-up messages (action:'message') and it keeps the full conversation context across rounds, with no need to re-spawn or re-explain. " +
-      "\nUse conversation:true for: multi-round collaboration (iterative review-fix loops, back-and-forth refinement), any task where you expect to send follow-up messages after the initial result. " +
-      "\nOmit (or false) for: one-shot tasks — single exploration, lookup, file read, code generation that needs no follow-up. The subagent runs once, notifies on completion, and is cleaned up automatically (default). " +
-      "\nFor long-interval collaboration (each round spaced >5min apart), set conversation:true AND increase idleTimeoutMs to avoid premature timeout. " +
-      "Cost: a conversation-mode subagent holds resources (memory, and a worktree if enabled) until you explicitly end it with action:'close'. Always close when done.",
-  })),
-  idleTimeoutMs: Type.Optional(Type.Number({
-    description:
-      "Idle timeout in milliseconds for conversation-mode subagents. Controls how long an idle subagent (between rounds) stays alive before automatic cleanup. " +
-      "Default: 300000 (5min). Override for long-interval collaboration where each round is spaced >5min apart. " +
-      "Only meaningful with conversation:true; ignored for one-shot subagents.",
-  })),
-  // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
-  listParam: Type.Optional(Type.Object({
-    includeFinished: Type.Optional(Type.Boolean({
-      description: "Include finished (done/failed/cancelled) records. Default false (running only).",
-    })),
-    limit: Type.Optional(Type.Number({
-      description: "Max items to return. Default 20, clamped to [1, 100].",
-    })),
-  })),
-  // action:"cancel" → cancelParam.subagentId REQUIRED. Throws if missing. Ignored by other actions.
-  cancelParam: Type.Optional(Type.Object({
-    subagentId: Type.String({
-      description: "REQUIRED for action:'cancel'. The subagentId to cancel. Throws if missing. Only background subagents can be cancelled.",
-    }),
-  })),
-  // action:"message" → messageParam.subagentId + text REQUIRED. Any RUNNING subagent works —
-  // one-shot subagents are auto-upgraded to conversation mode on first message (SP-5); ended ones throw.
-  messageParam: Type.Optional(Type.Object({
-    subagentId: Type.String({
-      description: "REQUIRED for action:'message'. The subagentId to message (any running subagent; a one-shot subagent is auto-upgraded to conversation mode on first message, so you may also message one-shot subagents that are still running).",
-    }),
-    text: Type.String({
-      description: "REQUIRED for action:'message'. The message to send. Whitespace-only throws.",
-    }),
-    interrupt: Type.Optional(Type.Boolean({
-      description: "If true, interrupt the subagent's current work immediately (in-progress output stops, it switches to your new message). If false (default), the message is queued and processed after the current round completes. When the subagent is idle (between rounds), interrupt has no effect — the message always starts a new round.",
-    })),
-  })),
-  // action:"close" → closeParam.subagentId REQUIRED. Ends a running subagent (conversation-mode
-  // or one-shot — closeSubagent behavior split covers both).
-  closeParam: Type.Optional(Type.Object({
-    subagentId: Type.String({
-      description: "REQUIRED for action:'close'. The subagentId to close (any running subagent, conversation-mode or one-shot).",
-    }),
-    force: Type.Optional(Type.Boolean({
-      description: "If true, terminate immediately even if mid-round (in-progress work is lost). If false (default), let the current round finish, then close. When idle, the subagent closes immediately regardless.",
-    })),
-  })),
-});
-
 // ============================================================
 // renderCall 预解析 helper
 // ============================================================
+//
+// Params schema（SubagentParams）定义在 ./subagent-tool-schema.ts 纯常量叶子：
+// subagent-tool 依赖树沉重，structured-output 侧跨包契约测试需要零依赖 import
+// schema 常量经真实 typebox 编译校验（SW 自身 vitest 把 typebox alias 到 mock，
+// 丢 options——required/description 断言必须以真实构造为基准）。
 
 // extractAgentName 已上移到 ../tui/format.ts 共享（tool-render / subagent-tool 复用）。
 
@@ -193,6 +85,47 @@ function isModelOverrideObj(a: unknown): a is { model?: unknown; thinkingLevel?:
   return typeof a === "object" && a !== null;
 }
 
+/**
+ * start 路径类参数（skillPath / cwd）运行时守卫：绝对路径 + 禁 `..` 穿越。
+ *
+ * 校验链事实（pi 0.84.1 实装，登记 PS-20）：pi agent-loop 对注册 typebox schema
+ * 有运行时强校验——agent-loop.js:403-404 在 beforeToolCall / execute 之前调
+ * validateToolArguments（pi-ai validation.js:247：Value.Convert :249 + Compile :210
+ * + Check :265，失败 throw `Validation failed for tool` :272-273）→ catch 走
+ * immediate error（agent-loop.js:445-451），execute 不被调用。schema 的
+ * pattern（skillPath/cwd `^/`）/ maxLength（slug 35）是运行时强制而非仅模型可见
+ * 契约；tool-definition-wrapper.js:11 只原样透传 params，校验发生在上游 agent-loop 层。
+ *
+ * 工具层守卫定位 = defense-in-depth + schema 表达力缺口，非「pi 无校验」：
+ *   - action 条件必填（task/slug 仅 action=start 必填）flat JSON Schema 表达不了，
+ *     只能在 startHandler 运行时校验
+ *   - `..` 穿越段拒绝超出 pattern 能力（`^/` 放行 "/a/../b"），穿越语义只能在
+ *     工具层判——与 slug maxLength 双闸同理（schema 强制之上再叠 handler 兜底）
+ *
+ * 规则：
+ *   - 绝对路径（isAbsolute；`~` 缩写不是绝对路径，拒绝并指引展开后重试——
+ *     下游 session-runner 把该值原样拼进 `--skill <path>` / spawn cwd，不展开 `~`）
+ *   - 任意 `..` 路径段拒绝（按 /[\\/] 分段判断而非子串——"a..b" 不是穿越）：
+ *     相对穿越让子进程读到意图外的目录
+ *
+ * 校验失败 immediate throw（与 action 枚举守卫同风格）：pi 只对 execute throw 置
+ * isError:true，错误文案原样进 toolResult。
+ */
+function assertSafeStartPath(value: string, param: "skillPath" | "cwd"): void {
+  if (value.split(/[\\/]/).includes("..")) {
+    throw new Error(
+      `${param} must not contain '..' path segments (got "${value}"). ` +
+      `Pass a normalized absolute path — traversal segments are rejected.`,
+    );
+  }
+  if (!isAbsolute(value)) {
+    throw new Error(
+      `${param} must be an absolute path (got "${value}"). ` +
+      `Expand '~' yourself and pass the full path, e.g. "/Users/me/project".`,
+    );
+  }
+}
+
 /** 从 unknown args 安全提取 model/thinkingLevel override（传给 resolveModel）。
  *  拍平后 args 已是顶层平铺结构（model/thinkingLevel 直接在 args 上）。 */
 function extractModelOverride(args: unknown): { model?: string; thinkingLevel?: string } | undefined {
@@ -237,7 +170,7 @@ action:"list" before action:"start" — a reusable running subagent may exist; c
 
 \`\`\`
 {"action":"start","task":"<your task>","slug":"<kebab-case>"}
-{"action":"start","task":"...","slug":"fix-login","agent":"coder","model":"anthropic/claude-3.5-sonnet","fork":true}
+{"action":"start","task":"...","slug":"fix-login","agent":"/abs/path/coder.md","model":"anthropic/claude-3.5-sonnet","fork":true}
 {"action":"start","task":"review iteratively","slug":"review","conversation":true}
 {"action":"message","messageParam":{"subagentId":"sa-550e8400","text":"now also handle the empty-list case"}}
 {"action":"message","messageParam":{"subagentId":"sa-550e8400","text":"stop, switch direction to X","interrupt":true}}
@@ -271,7 +204,7 @@ When to use:
 - ✅ Long-interval rounds (>5min apart) → conversation:true + idleTimeoutMs increased
 - ❌ Single exploration/lookup → default (one-shot)
 
-idleTimeoutMs: per-subagent idle timeout (default 300000 / 5min). Env XYZ_SUBAGENT_IDLE_TIMEOUT_MS sets the global default; per-call param takes precedence.
+idleTimeoutMs: per-subagent idle timeout (default 300000 / 5min). Env XYZ_SUBAGENT_IDLE_TIMEOUT_MS sets the global default; per-call param takes precedence. Pass 0 or a negative value to disable idle cleanup entirely.
 
 ## You cannot
 
@@ -375,6 +308,10 @@ const executeSubagent: SubagentExecuteCb = async (
   }
   switch (params.action) {
     case "start":
+      // 路径类参数守卫（三通道对称审查 + MF-13）：skillPath/cwd 在进入 handler 前
+      // immediate throw，不产生半启动 record（与 action 枚举守卫同风格）。
+      if (params.skillPath !== undefined) assertSafeStartPath(params.skillPath, "skillPath");
+      if (params.cwd !== undefined) assertSafeStartPath(params.cwd, "cwd");
       // 拍平后直接传顶层 params（StartHandlerInput 是 SubagentExecuteParams 子集，
       // action/listParam/cancelParam 被忽略；task/slug 必填性由 startHandler 校验）。
       return adapter({ action: "start", domain: await startHandler(service, params, signal, _ctx?.model) }, toGuiCtx(_ctx));

package/src/interface/subagents.ts

@@ -45,7 +45,7 @@ export interface SubagentDirectiveDetails {
  * 定向消息注入正在运行的主 agent LLM turn，违反「不经主 agent LLM 直达 subagent」。
  * 故按调用时刻的权威 streaming 状态（ctx.isIdle()，与 sendCustomMessage 内部
  * isStreaming 判据精确互补，含 agent_end 后 retry/continuation 窗口）分流：
- * - streaming（isMainAgentIdle=false）：传 { deliverAs: "nextTurn" }——消息入
+ * - streaming（isMainAgentIdle=false）：传 { deliverAs: "nextTurn" }——消息入（g4-allow: 交互注入——GUI 定向消息留痕分流，非结果语义通知）
  *   pi 内存 _pendingNextTurnMessages 队列，下个 turn 注入主 agent 上下文；不打断、
  *   不 steer 当前 turn。注意：该队列不落 entry，留痕延迟到下个 turn
  * - 非 streaming（isMainAgentIdle=true）：不传 options——立即 append entry 留痕
@@ -66,7 +66,7 @@ function emitSubagentDirective(
       display: false,
       details,
     },
-    isMainAgentIdle ? undefined : { deliverAs: "nextTurn" },
+    isMainAgentIdle ? undefined : { deliverAs: "nextTurn" }, // g4-allow: 交互注入——/subagents GUI 定向消息留痕，非结果语义（C-ext-19 禁令边界，见 emitSubagentDirective JSDoc）
   );
 }
 

package/src/orchestration/__tests__/__fixtures__/worker-template.snapshot.txt

@@ -12,7 +12,7 @@ const { parentPort: _parentPort, workerData: _workerData } = require("node:worke
 const _workerLogs = [];
 // IF6(#12): known agent() fields — hoisted to module scope, built once per worker
 // (was rebuilt inside agent() on every call; field set is call-invariant).
-const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);
+const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "maxTurns", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);
 function _pushWorkerLog(level, args) {
   try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }
 }
@@ -98,6 +98,8 @@ function _safePost(msg, context) {
         // 让 parallel() 下的脚本容错循环（parseResult → null → skip）自然接管。
         // 错误原因已由主线程 executeAgentCall → trace.update(result.error) 保留在 trace/TUI，
         // 不丢失。失败 resolve 为空字符串是既定容错策略。
+        // [MF-4] schema 模式下失败时 agent() 仍 resolve（content 回退、不 throw）——
+        // 需要检查错误时请用 returnMeta:true（resolve 值含 error 字段）。
         // parsedOutput: validated data object from structured-output execute().
         // Fallback to content (raw text) when no schema was requested or on error.
         // W2 改动 9(b)：returnMeta===true 时 resolve {value,sessionFile,worktreePath,error,usage,durationMs,sessionId}
@@ -153,6 +155,11 @@ function _safePost(msg, context) {
         scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,
         phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,
         thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || $THINKING_LEVEL,
+        // step 级 turn 上限（turn limiter；显式 0/负 = 显式不限，压过 spawn watchdog env 兑底，SP-6）
+        // ?? 语义保真：仅 null/undefined 归 undefined（走 env 兑底），显式 0 保留（U5 参数 > env）
+        maxTurns: (secondArg && typeof secondArg === "object" ? secondArg.maxTurns : undefined) ?? undefined,
+        // P4 D9③：step 级 engine 显式指定（仅限必须某引擎独有能力的场景）
+        engine: (secondArg && typeof secondArg === "object" && secondArg.engine) || undefined,
       };
     } else if (typeof firstArg === "object" && firstArg !== null) {
       if (firstArg.prompt) {
@@ -169,11 +176,13 @@ function _safePost(msg, context) {
           scene: firstArg.scene,
           skill: firstArg.skill,
           timeoutMs: firstArg.timeoutMs,
+          maxTurns: firstArg.maxTurns,
           cwd: firstArg.cwd,
           fork: firstArg.fork,
           worktree: firstArg.worktree,
           returnMeta: firstArg.returnMeta,
           thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL,
+          engine: firstArg.engine,
         };
       } else {
         opts = firstArg;
@@ -190,7 +199,7 @@ function _safePost(msg, context) {
     // Validate known agent() fields to catch API misuse early (_KNOWN_FIELDS at module scope)
     const _unknownFields = Object.keys(opts).filter((k) => !_KNOWN_FIELDS.has(k));
     if (_unknownFields.length > 0) {
-      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);
+      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, maxTurns, cwd, fork, worktree, returnMeta, thinkingLevel, engine"]);
     }
 
     const callId = _callIdCounter;
@@ -326,7 +335,14 @@ module.exports = { execute: async (ctx) => ctx.agent("finalize") };
   }
 })().then((result) => {
   const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";
-  _safePost({ type: "return", runId, result, workerLogs: _workerLogs }, "return");
+  if (!_safePost({ type: "return", runId, result, workerLogs: _workerLogs }, "return")) {
+    // [F1] return 值不可克隆（含 function/Symbol/循环引用 → DataCloneError）时 _safePost
+    // 只能记日志返回 false——若不补救，worker 将静默 exit(0)，主线程收不到任何终态消息，
+    // run 永久 running、runAndWait 悬挂。回发可克隆的 error 消息（DataCloneError 详情
+    // 已由 _safePost 记入 _workerLogs 随消息带回），让主线程 handleScriptError 接管，
+    // run 经既有重试矩阵收敛到终态 failed。
+    _safePost({ type: "error", runId, error: "Workflow return value could not be delivered (structured-clone failed) — see workerLogs for the postMessage error", workerLogs: _workerLogs }, "error");
+  }
 }).catch((err) => {
   const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";
   _safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");

package/src/orchestration/__tests__/agent-call-catch-fallback.test.ts

@@ -48,12 +48,6 @@ function makeRunningRun(runId: string): WorkflowRun {
     runtime: {
       controller,
       worker: { postMessage: vi.fn() },
-      gate: {
-        // 直接 await fn()：executeAgentCall 内 runner.run reject 会沿 withSlot → 外层 .catch
-        withSlot: vi.fn(async (fn: () => Promise<void>, _signal: AbortSignal) => {
-          await fn();
-        }),
-      },
     },
     transition: vi.fn(),
     replaceRuntime: vi.fn(),

package/src/orchestration/__tests__/agent-call-stream.test.ts

@@ -46,11 +46,6 @@ function makeRunningRun(runId: string): WorkflowRun {
     runtime: {
       controller,
       worker: { postMessage: vi.fn() },
-      gate: {
-        withSlot: vi.fn(async (fn: () => Promise<void>, _signal: AbortSignal) => {
-          await fn();
-        }),
-      },
     },
     transition: vi.fn(),
     replaceRuntime: vi.fn(),