@zhushanwen/pi-subagent-workflow 5.0.2 → 7.0.0

package/src/execution/__tests__/execute-options-mapper.test.ts

@@ -115,13 +115,13 @@ describe("mapToExecuteOptions (D-A2)", () => {
     expect(result.thinkingLevel).toBeUndefined();
   });
 
-  it("systemPromptFiles → appendSystemPrompt 映射 (M2)", () => {
-    const opts: AgentCallOpts = { ...baseOpts, systemPromptFiles: ["/tmp/a.md"] };
+  it("appendSystemPrompt → appendSystemPrompt 透传", () => {
+    const opts: AgentCallOpts = { ...baseOpts, appendSystemPrompt: ["SO instruction content"] };
     const result = mapToExecuteOptions(opts);
-    expect(result.appendSystemPrompt).toEqual(["/tmp/a.md"]);
+    expect(result.appendSystemPrompt).toEqual(["SO instruction content"]);
   });
 
-  it("systemPromptFiles 不传 → appendSystemPrompt undefined", () => {
+  it("appendSystemPrompt 不传 → appendSystemPrompt undefined", () => {
     const result = mapToExecuteOptions(baseOpts);
     expect(result.appendSystemPrompt).toBeUndefined();
   });

package/src/execution/__tests__/index-session-start.test.ts

@@ -101,7 +101,6 @@ vi.mock("../subagent-service.ts", () => ({
 vi.mock("../model-config-service.ts", () => ({
   ModelConfigService: class {
     initModel = vi.fn();
-    getAgentRegistry = () => ({ get: () => undefined, list: () => [] });
     setCtxModel = vi.fn();
   },
   getModelConfigService: () => null,

package/src/execution/__tests__/model-resolver.test.ts

@@ -278,6 +278,20 @@ describe("resolveModel — not-found error suggests similar models (B)", () => {
     expect(msg).toMatch(/models\.json/);
     expect(msg).not.toMatch(/Similar available models/); // auth 错误不列 model
   });
+
+  it("P1: resolves model passed with ':max' suffix (THINKING_ORDER includes 'max')", () => {
+    const m = makeModel({ id: "mock-model", provider: "p1", reasoning: true, thinkingLevelMap: { max: 4 } });
+    const reg = makeRegistry([m]);
+    const r = resolveModel(
+      { name: "worker", systemPrompt: "" },
+      reg,
+      { model: "p1/mock-model:max" },
+      ctxModel,
+    );
+    expect(r.model).toBeTruthy();
+    expect(r.model.id).toBe("mock-model");
+    expect(r.thinkingLevel).toBe("max");
+  });
 });
 
 describe("availableThinkingLevels", () => {
@@ -292,6 +306,12 @@ describe("availableThinkingLevels", () => {
       availableThinkingLevels({ reasoning: true, thinkingLevelMap: { off: 0, high: 2, low: 1, xhigh: 3 } }),
     ).toEqual(["off", "low", "high", "xhigh"]);
   });
+
+  it("P2: includes 'max' as the last level (THINKING_ORDER SSOT derived)", () => {
+    const levels = availableThinkingLevels({ reasoning: true, thinkingLevelMap: { off: 0, low: 1, high: 2, xhigh: 3, max: 4 } });
+    expect(levels).toEqual(["off", "low", "high", "xhigh", "max"]);
+    expect(levels.slice(-3)).toEqual(["high", "xhigh", "max"]);
+  });
 });
 
 // ============================================================

package/src/execution/__tests__/session-start-reaper.test.ts

@@ -72,8 +72,6 @@ const { mockInitModel, mockInitSession, mockSetUiRequestHandler, mockSetModelCon
 vi.mock("../model-config-service.ts", () => ({
   ModelConfigService: class {
     initModel = mockInitModel;
-    // F-4/D-003: index.ts 复用 modelService.getAgentRegistry()，stub 返回最小结构
-    getAgentRegistry = () => ({ get: () => undefined, list: () => [] });
   },
   getModelConfigService: () => null,
   setModelConfigService: mockSetModelConfigService,

package/src/execution/__tests__/subprocess-agent-runner.test.ts

@@ -59,7 +59,7 @@ function makeBaseOpts(): AgentCallOpts {
     timeoutMs: undefined,
     skill: undefined,
     skillPath: undefined,
-    systemPromptFiles: undefined,
+    appendSystemPrompt: undefined,
     schemaEnv: undefined,
   };
 }

package/src/execution/agent-registry.ts

@@ -7,77 +7,28 @@
 //
 // builtin agent（包内 agents/*.md）走 pi.agents manifest（与 npm 包内发现规则一致）。
 
-import * as fs from "node:fs";
+
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import {
-  type DiscoveredResource,
-  discoverResourcesSync,
-  type ScanConfig,
+  getCachedFile,
 } from "../shared/resource-discovery.ts";
+import { normalizeRef, AGENT_REF_EXT } from "../shared/agent-ref.ts";
+import { parseResourceMeta } from "../shared/meta-parser.ts";
+import { lintAgentMeta } from "../orchestration/script-lint.ts";
+import type { AgentMeta } from "../shared/resource-meta.ts";
 import type { AgentConfig } from "./model-resolver.ts";
 
 const logger = getLogger("subagents");
 
-/** 内置 agent（代码硬编码，如 default worker）。 */
-export interface BuiltinAgentRegistry {
-  get(name: string): AgentConfig | undefined;
-  list(): string[];
-}
-
-/**
- * 包内自带 agents（与 src/ 同级的 agents/ 目录）。
- *
- * 走 pi.agents manifest（package.json 的 pi.agents 字段），与 npm 包内发现规则一致。
- * manifest 缺失时 fallback 扫约定目录 agents/。
- *
- * [HISTORICAL] 此前 discoverAll 从未被调用，agentRegistry 永远为空——包内
- * agents/*.md（worker/reviewer/explorer 等）pi install 后开箱不可用。修复：构造时扫描
- * 包内 agents/ 作为 builtin（优先级最低，被用户同名文件覆盖）。
- */
-export function createPackageBuiltinRegistry(): BuiltinAgentRegistry {
-  const packageRoot = path.resolve(
-    path.dirname(fileURLToPath(import.meta.url)),
-    "..",
-    "..",
-  );
-  const cache = new Map<string, AgentConfig>();
-  try {
-    const config = discoverPackageAgentsSync(packageRoot);
-    for (const resource of config) {
-      if (!resource.available) continue;
-      try {
-        const raw = fs.readFileSync(resource.path, "utf-8");
-        const agentConfig = parseAgentFrontmatter(resource.path, raw);
-        if (agentConfig) cache.set(agentConfig.name, agentConfig);
-      } catch (err) {
-        // 单个 builtin agent 文件损坏不影响其他——降级跳过该文件。
-        void err;
-        logger.warn(`[subagents] skip malformed builtin agent: ${resource.path}`, {
-          detail: err instanceof Error ? err.message : String(err),
-        });
-      }
-    }
-  } catch (err) {
-    // agents/ 目录不存在（打包遗漏）→ 空 builtin，不崩。
-    void err;
-    logger.warn("[subagents] builtin agents/ directory unreadable, falling back to empty set", {
-      detail: err instanceof Error ? err.message : String(err),
-    });
-  }
-  return {
-    get: (name) => cache.get(name),
-    list: () => [...cache.keys()],
-  };
-}
-
-/** mtime 缓存条目（跨 discoverAll 保留，靠 mtime 判失效）。 */
+/** mtime 缓存条目（跨 loadByPath 保留，靠 mtime 判失效）。 */
 interface FileCacheEntry {
   mtimeMs: number;
   config: AgentConfig;
+  /** AgentMeta（W4 lint 用——cache-miss 时 lint 一次，warn 随 mtime 变化刷）。 */
+  meta: AgentMeta | null;
 }
 
 // ============================================================
@@ -92,11 +43,22 @@ const FM_DELIM = "---";
  * 兼容简单 YAML（key: value 单行格式）。body 作为 systemPrompt。
  */
 export function parseAgentFrontmatter(filePath: string, content: string): AgentConfig {
+  return parseAgentWithMeta(filePath, content).config;
+}
+
+/**
+ * 解析 agent .md → { config, meta } 二元组（m5 T2：W4 lint 需要 AgentMeta——
+ * AgentConfig 投影时 examples 被丢弃，meta 供 lintAgentMeta 使用）。
+ */
+export function parseAgentWithMeta(
+  filePath: string,
+  content: string,
+): { config: AgentConfig; meta: AgentMeta | null } {
   const name = path.basename(filePath, ".md");
 
   // 无 frontmatter → 整个内容作为 systemPrompt
   if (!content.startsWith(FM_DELIM)) {
-    return { name, systemPrompt: content.trim() };
+    return { config: { name, systemPrompt: content.trim() }, meta: null };
   }
 
   const closeIdx = content.indexOf(FM_DELIM, FM_DELIM.length);
@@ -104,28 +66,53 @@ export function parseAgentFrontmatter(filePath: string, content: string): AgentC
     // 未闭合 frontmatter：提取 name，其余作为 systemPrompt
     const yamlBlock = content.slice(FM_DELIM.length);
     return {
-      name: extractYamlField(yamlBlock, "name") ?? name,
-      systemPrompt: content.trim(),
+      config: {
+        name: extractYamlField(yamlBlock, "name") ?? name,
+        systemPrompt: content.trim(),
+      },
+      meta: null,
     };
   }
 
   const yamlBlock = content.slice(FM_DELIM.length, closeIdx);
   const body = content.slice(closeIdx + FM_DELIM.length).trim();
 
-  const toolsRaw = extractYamlField(yamlBlock, "tools");
-  const tools = toolsRaw
-    ? toolsRaw.split(",").map((s) => s.trim()).filter(Boolean)
+  // m2：结构化路由字段（name/model/tools）经 IF1 parseResourceMeta（统一 parser），
+  // 消灭本地 frontmatter parser 与 subagent-list-injector 的重复。thinkingLevel/defaultBackground
+  // 是执行配置（非 AgentMeta 路由字段），仍用 extractYamlField 取。
+  const meta = parseResourceMeta(content, "agent");
+  const agentMeta = meta?.kind === "agent" ? meta : null;
+  // MF-3 regression fix：agentMeta=null（IF1 要求 name/description 必填，缺则 parseResourceMeta
+  // 返 null）时，model/tools 不能静默丢失——fallback 用 extractYamlField 取（保留重构前行为）。
+  // 注入路由可见性由 discovery/injector 按 available 标志决定，与本处（direct-path loadByPath）无关。
+  const modelFallback = extractYamlField(yamlBlock, "model");
+  const toolsFallbackRaw = extractYamlField(yamlBlock, "tools");
+  const toolsFallback = toolsFallbackRaw
+    ? toolsFallbackRaw.split(",").map((s) => s.trim()).filter(Boolean)
     : undefined;
-
+  if (!agentMeta && /^model:|^tools:/m.test(yamlBlock)) {
+    // m2 exec-review MINOR-2 + MF-3：IF1 未通过（缺 name/description）→ model/tools 经 legacy
+    // fallback 取（direct-path loadByPath 不丢配置，与重构前一致）；但结构化路由注入不可见，
+    // 建议 agent 作者补 description 以满足 IF1。
+    logger.warn(
+      `[agent-registry] ${filePath}: agent frontmatter 缺 name/description（IF1 必填），` +
+        "model/tools 经 legacy fallback 生效（直接路径不丢配置），但结构化路由不可见——请补充 description",
+    );
+  }
   const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
 
   return {
-    name: extractYamlField(yamlBlock, "name") ?? name,
-    systemPrompt: body,
-    model: extractYamlField(yamlBlock, "model") ?? undefined,
-    thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
-    tools: tools && tools.length > 0 ? tools : undefined,
-    defaultBackground: defaultBackgroundRaw === "true" ? true : undefined,
+    config: {
+      name: agentMeta?.name ?? name,
+      systemPrompt: body,
+      model: agentMeta?.model ?? modelFallback ?? undefined,
+      thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
+      tools: agentMeta?.tools && agentMeta.tools.length > 0
+        ? agentMeta.tools
+        : (toolsFallback && toolsFallback.length > 0 ? toolsFallback : undefined),
+      defaultBackground: defaultBackgroundRaw === "true" ? true : undefined,
+    },
+    meta: agentMeta,
   };
 }
 
@@ -145,116 +132,52 @@ function extractYamlField(yaml: string, key: string): string | undefined {
 // AgentRegistry
 // ============================================================
 
-/**
- * 发现配置：用于统一资源发现的扫描参数。
- */
-export interface AgentDiscoveryConfig {
-  /** 项目根目录（findWorkspaceRoot 推导结果） */
-  workspaceRoot: string;
-  /** agent 配置目录（getAgentDir() 结果） */
-  agentDir: string;
-}
-
-/**
- * agent 注册表。通过统一资源发现（shared/resource-discovery）扫描所有源。
- * hot-reload：每次 discoverAll 重扫，mtime 未变的文件跳过 read+parse。
- *
- * 优先级（低→高）：user .pi/agent → user .agents → npm global → npm dev →
- * project .pi → project .agents。builtin（包内）优先级最低。
- * 详见 ADR-031。
- */
 export class AgentRegistry {
-  private readonly cache = new Map<string, AgentConfig>();
-  /** 文件级 mtime 缓存（key=绝对路径，跨 discoverAll 保留）。 */
+  /** 文件级 mtime 缓存（key=绝对路径，跨 loadByPath 保留）。 */
   private readonly fileCache = new Map<string, FileCacheEntry>();
-  /** 本轮扫描到的路径集（清理已删除文件的缓存）。 */
-  private currentScanPaths = new Set<string>();
-
-  constructor(private readonly discoveryConfig: AgentDiscoveryConfig) {}
 
-  /** 扫描所有源 + 合并 builtin（hot-reload，每次重扫）。 */
-  discoverAll(builtin: BuiltinAgentRegistry): void {
-    this.cache.clear();
-    this.currentScanPaths = new Set();
-
-    const scanConfig: ScanConfig = {
-      kind: "agents",
-      workspaceRoot: this.discoveryConfig.workspaceRoot,
-      agentDir: this.discoveryConfig.agentDir,
-    };
-    const resources = discoverResourcesSync(scanConfig);
-
-    for (const resource of resources) {
-      if (!resource.available) continue;
-      this.currentScanPaths.add(resource.path);
-      try {
-        const config = this.loadWithMtimeCache(resource.path);
-        if (config) this.cache.set(config.name, config);
-      } catch (_err) {
-        // 有意吞掉：文件不可读/解析失败 → 跳过（不阻断其他 agent 发现）
-        void _err;
-      }
-    }
-
-    // builtin 优先级最低（先写入，被文件 agent 覆盖）
-    for (const agentName of builtin.list()) {
-      if (!this.cache.has(agentName)) {
-        const config = builtin.get(agentName);
-        if (config) this.cache.set(agentName, config);
+  /**
+   * 按绝对路径加载 agent（agentRef 统一解析入口——S2 路径统一）。
+   *
+   * - ~/ 前缀展开；相对路径/非 .md 引用返回 undefined（引用唯一形态 = 绝对路径）
+   * - 文件不可读/不存在 → 驱逐缓存 + 返回 undefined（调用方给错误指引）
+   * - mtime 未变复用 config 缓存；cache-miss 时 W4 lint 一次
+   */
+  loadByPath(ref: string, require?: boolean): AgentConfig | undefined {
+    const filePath = normalizeRef(ref, AGENT_REF_EXT);
+    if (filePath === null) {
+      if (require) {
+        throw new Error(
+          `Invalid agent ref: ${ref}. Agent refs must be absolute paths to .md files (use <location> from <available_subagents>).`,
+        );
       }
+      return undefined;
     }
 
-    // 清理本轮未扫描到的文件缓存条目（文件被删除/移走）
-    for (const cachedPath of this.fileCache.keys()) {
-      if (!this.currentScanPaths.has(cachedPath)) {
-        this.fileCache.delete(cachedPath);
+    const file = getCachedFile(filePath);
+    if (file === null) {
+      // ENOENT/不可读 → 驱逐（mtime 缓存下文件删除不自愈的修复）
+      this.fileCache.delete(filePath);
+      if (require) {
+        throw new Error(
+          `Agent file not found or unreadable: ${filePath}. Use an absolute path from <available_subagents> <location>.`,
+        );
       }
+      return undefined;
     }
-  }
-
-  /** 按 name 查找。require=false 时找不到返回 undefined；true 时抛错。 */
-  get(name: string, require?: boolean): AgentConfig | undefined {
-    const config = this.cache.get(name);
-    if (!config && require) {
-      throw new Error(
-        `Agent "${name}" not found. Discovered: ${[...this.cache.keys()].join(", ") || "(none)"}`,
-      );
-    }
-    return config;
-  }
-
-  /** 列出所有已发现 agent 名（诊断/wizard 用）。 */
-  list(): string[] {
-    return [...this.cache.keys()];
-  }
-
-  // ── 内部 ──────────────────────────────────────────────────
 
-  /** 带 mtime 缓存的单文件加载。mtime 未变复用缓存，否则 read+parse。 */
-  private loadWithMtimeCache(filePath: string): AgentConfig | undefined {
-    const stat = fs.statSync(filePath);
-    const mtimeMs = stat.mtimeMs;
     const cached = this.fileCache.get(filePath);
-    if (cached && cached.mtimeMs === mtimeMs) {
+    if (cached && cached.mtimeMs === file.mtimeMs) {
       return cached.config;
     }
-    const content = fs.readFileSync(filePath, "utf-8");
-    const config = parseAgentFrontmatter(filePath, content);
-    this.fileCache.set(filePath, { mtimeMs, config });
+
+    const { config, meta } = parseAgentWithMeta(filePath, file.content);
+    // W4 lint：cache-miss（parse 时一次）——warn 只随 mtime 变化刷
+    const lintFindings = meta ? lintAgentMeta(meta) : [];
+    for (const finding of lintFindings) {
+      logger.warn(`[agent-registry] ${filePath}: ${finding.message}`);
+    }
+    this.fileCache.set(filePath, { mtimeMs: file.mtimeMs, config, meta });
     return config;
   }
 }
-
-// ============================================================
-// 包内 agent 发现（builtin 用，走 pi.agents manifest）
-// ============================================================
-
-import { processPackageSync } from "../shared/resource-discovery.ts";
-
-/**
- * 发现包内 agent 文件（走 pi.agents manifest 或约定目录 agents/）。
- * builtin 专用——不参与优先级合并，优先级最低。
- */
-function discoverPackageAgentsSync(packageRoot: string): DiscoveredResource[] {
-  return processPackageSync(packageRoot, "agents");
-}

package/src/execution/execute-options-mapper.ts

@@ -34,7 +34,7 @@ export const SLUG_MAX_LENGTH = 35;
  *   ctxModel        → ctxModel（完整 ModelInfo 对象透传，让 resolveModel 走第 3 层透明传递）
  *   skillPath       → skillPath
  *   thinkingLevel   → thinkingLevel（M1: 否则下游 subagent-service 读到 undefined）
- *   systemPromptFiles → appendSystemPrompt（M2: resolveAgentOpts 写盘的临时文件需被 session-runner 消费）
+ *   appendSystemPrompt → appendSystemPrompt（内容数组，同名同义透传）
  *
  * 忽略字段（委托后由 executeAndAwait 内部机制替代）：
  *   timeoutMs         —— mergeTimeoutSignal 单独处理
@@ -61,7 +61,7 @@ export function mapToExecuteOptions(
     ctxModel,
     skillPath: opts.skillPath,
     thinkingLevel: opts.thinkingLevel,
-    appendSystemPrompt: opts.systemPromptFiles,
+    appendSystemPrompt: opts.appendSystemPrompt,
   };
 }
 

package/src/execution/model-config-service.ts

@@ -6,8 +6,7 @@
 // 上游：SubagentService.execute 内部调 resolveModel。
 // session_start 时经 initModel 注入 modelRegistry。
 
-import { findWorkspaceRoot } from "../shared/resource-discovery.ts";
-import { AgentRegistry, createPackageBuiltinRegistry } from "./agent-registry.ts";
+import { AgentRegistry } from "./agent-registry.ts";
 import {
   loadGlobalConfig,
 } from "./config.ts";
@@ -69,25 +68,15 @@ export class ModelConfigService {
   private globalConfig: SubagentsGlobalConfig;
   private readonly agentRegistry: AgentRegistry;
   private readonly agentRegistryDir: string;
-  private readonly workspaceRoot: string;
   private modelRegistry: ModelRegistryLike | null = null;
   private _sessionId: string | undefined;
   /** 主 agent 当前 model 缓存（session_start 注入，model_select 刷新）。 */
   private _ctxModel: ModelInfo | undefined;
 
-  /** 包内 builtin agent（agents/*.md，优先级最低，被用户覆盖）。 */
-  private readonly builtinRegistry = createPackageBuiltinRegistry();
-
   constructor(init: ModelConfigServiceInit) {
     this.agentRegistryDir = init.agentDir;
-    this.workspaceRoot = findWorkspaceRoot(init.cwd);
     this.globalConfig = loadGlobalConfig(init.agentDir);
-    // 统一资源发现（ADR-031）：扫描源由 workspaceRoot + agentDir 推导
-    this.agentRegistry = new AgentRegistry({
-      workspaceRoot: this.workspaceRoot,
-      agentDir: this.agentRegistryDir,
-    });
-    this.agentRegistry.discoverAll(this.builtinRegistry);
+    this.agentRegistry = new AgentRegistry();
   }
 
   // ── 生命周期（index.ts 调）──────────────────────────────
@@ -99,9 +88,8 @@ export class ModelConfigService {
    *   3. setSessionId
    */
   initModel(init: ModelServiceSessionInit): void {
-    // 1. 重载配置 + 重扫 agent（hot-reload：用户可能新增/修改 agent .md）
+    // 1. 重载配置（agent 按需 loadByPath，无预热扫描）
     this.globalConfig = loadGlobalConfig(this.agentRegistryDir);
-    this.agentRegistry.discoverAll(this.builtinRegistry);
 
     // 2. modelRegistry（fail-fast）
     if (init.modelRegistry === null) {
@@ -127,24 +115,26 @@ export class ModelConfigService {
   /**
    * 解析 agent 的模型（三层：override → agentConfig → 主 agent model）。
    *
-   * @param agentName     agent 名（查 agentConfig.model override）
-   * @param override      调用方显式 override（最高优先级）
-   * @param ctxModel      主 agent 当前模型（兜底，直接透传）
+   * @param agentRef   agent 引用（.md 绝对路径；查 agentConfig 的 model override）
+   * @param override   调用方显式 override（最高优先级）
+   * @param ctxModel   主 agent 当前模型（兜底，直接透传）
    */
   resolveModel(
-    agentName: string,
+    agentRef: string,
     override?: { model?: string; thinkingLevel?: string },
     ctxModel?: ModelInfo,
+    /** 已解析的 agent 配置（调用方已加载时复用，避免同一 agentRef 二次 loadByPath）。 */
+    agentConfig?: AgentConfig,
   ): ResolvedModel {
     this.assertReady();
-    const agentConfig = this.agentRegistry.get(agentName);
+    const config = agentConfig ?? (agentRef ? this.agentRegistry.loadByPath(agentRef) : undefined);
     // ctxModel 优先用显式传入（execute 路径），其次用 session 缓存（renderCall 路径）
-    return resolveModel(agentConfig, this.modelRegistry!, override, ctxModel ?? this._ctxModel);
+    return resolveModel(config, this.modelRegistry!, override, ctxModel ?? this._ctxModel);
   }
 
   /** 查询 agent 配置（SubagentService 内部判定 defaultBackground 用）。 */
-  getAgentConfig(name?: string): AgentConfig | undefined {
-    return name ? this.agentRegistry.get(name) : undefined;
+  getAgentConfig(agentRef?: string): AgentConfig | undefined {
+    return agentRef ? this.agentRegistry.loadByPath(agentRef) : undefined;
   }
 
   // ── 配置读取（subagent-service 调）────────────────────────
@@ -164,17 +154,6 @@ export class ModelConfigService {
     return this.agentRegistryDir;
   }
 
-  /**
-   * AgentRegistry 实例（workflow 域复用，F-4/D-003 统一）。
-   *
-   * workflow 域（resolveAgentOpts via LifecycleDeps.agentRegistry）需要与 subagents 域
-   * 完全相同的 agent 名→config 解析，复用本实例避免二次扫描。registry 在 initModel
-   * （每次 session_start）调 discoverAll hot-reload，两域共享同一份发现结果。
-   */
-  getAgentRegistry(): AgentRegistry {
-    return this.agentRegistry;
-  }
-
   /** modelRegistry（SubagentService 构造 factoryCtx 时读）。已注入保证非 null。 */
   getModelRegistry(): ModelRegistryLike {
     if (this.modelRegistry === null) {

package/src/execution/model-resolver.ts

@@ -60,8 +60,10 @@ export interface ResolvedModel {
 // 常量
 // ============================================================
 
-/** thinking level 支持顺序（低→高），用于 clamp 到 model 可用级别。 */
-const THINKING_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+/** thinking level 支持顺序（低→高），用于 clamp 到 model 可用级别。
+ *  SSOT（单一权威源）：新增 thinking 级别只改此处，subagent-tool 的 thinkingLevel 枚举
+ *  从本常量派生，避免两处硬编码不同步。 */
+export const THINKING_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
 /** 解析失败时错误信息列出的可用模型上限（防超长错误信息）。 */
 const MODEL_LIST_LIMIT = 20;
@@ -102,7 +104,7 @@ export function resolveModel(
   if (paramOverride?.model) {
     return lookupAndResolve(
       paramOverride.model,
-      paramOverride.thinkingLevel,
+      paramOverride.thinkingLevel ?? agentConfig?.thinkingLevel,
       modelRegistry,
       "paramOverride",
     );

package/src/execution/subagent-service.ts

@@ -394,8 +394,9 @@ export class SubagentService {
     agent: string,
     override?: { model?: string; thinkingLevel?: string },
     ctxModel?: ModelInfo,
+    agentConfig?: AgentConfig,
   ): ResolvedModel {
-    return this.modelService.resolveModel(agent, override, ctxModel);
+    return this.modelService.resolveModel(agent, override, ctxModel, agentConfig);
   }
 
   /**
@@ -599,7 +600,7 @@ export class SubagentService {
     //   - **不可作为后续 agent 的 cwd**——目录已删，复用会 ENOENT。
     //   - wave 内 worktree 复用（spec-w §2 "wave 内 8 action 共享 worktree"）在 pi 当前架构下
     //     不可行：worktree 绑定单次 agent() record，每次 executeAndAwait 结束 finalizeRecord
-    //     无条件 cleanup，worktree 无法跨 action 存活。wave 改用主 cwd（见 recursive-split.js）。
+    //     无条件 cleanup，worktree 无法跨 action 存活。wave 改用主 cwd。
     wfResult.worktreePath = record.worktreeHandle?.path;
     return wfResult;
   }
@@ -626,15 +627,17 @@ export class SubagentService {
 
   /** 步骤 1：身份解析。agentConfig → resolveModel（三层：override → agentConfig → 主 agent model）。 */
   private async resolveIdentity(opts: ExecuteOptions): Promise<ResolvedIdentity> {
-    // 未显式指定 agent 时兜底为 DEFAULT_AGENT_NAME（与 TUI 层 extractAgentName 共用同一常量，
-    // 保证 block 标题显示的名与实际加载的 agent.md 一致）。见 types.ts 常量注释。
+    // agentRef 语义（S2）：agent 参数 = .md 绝对路径；不传 = 不加载 agentConfig，
+    // 直接用 override → 主 agent model。DEFAULT_AGENT_NAME 仅作 record 显示名
+    // （TUI 层 extractAgentName 共用，保证显示一致）。
     const agent = opts.agent ?? DEFAULT_AGENT_NAME;
-    const agentConfig = this.modelService.getAgentConfig(agent);
+    const agentConfig = opts.agent ? this.modelService.getAgentConfig(opts.agent) : undefined;
 
     const resolved = this.modelService.resolveModel(
-      agent,
+      opts.agent ?? "",
       { model: opts.model, thinkingLevel: opts.thinkingLevel },
       opts.ctxModel,
+      agentConfig,
     );
 
     return { agent, agentConfig, resolved };

package/src/execution/subprocess-agent-runner.ts

@@ -32,8 +32,9 @@ import type { ExecuteOptions } from "./types.ts";
  *   - subagentService: 进程单例（getSubagentService()），委托目标
  *   - ctxModel: 当前 session 主 agent 模型（D-008 model 填底，opts.model 空时用此）
  *
- * 不含 agentRegistry/sessionDir/activeTempFiles——resolveAgentOpts 在 orchestration 层
- * 完成（D-A3），结果已填进 AgentCallOpts.skillPath/schemaEnv，SAR 收已解析的 opts。
+ * resolveAgentOpts 在 orchestration 层完成（M2 修正后单参数，只处理 schema SO 指令 + skill），
+ * 结果填进 AgentCallOpts.skillPath/schemaEnv/appendSystemPrompt，SAR 收已解析的 opts。
+ * 不含 agent/session 目录/临时文件集合依赖（agent ref 交 resolveIdentity，无临时文件）。
  */
 export interface SubprocessAgentRunnerDeps {
   subagentService: SubagentService;