@zhushanwen/pi-subagent-workflow 5.0.2 → 7.0.0

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

@@ -1,11 +1,52 @@
 // workflow-list-injector 单测
 //
-// 覆盖纯函数：summarizeDescription（截断）+ parseWorkflowMeta（meta 块解析）+
-// formatWorkflowList（B2 注入段格式 + 引导语）。discoverAllWorkflows 依赖文件系统
-// + resource-discovery，属集成层，此处聚焦可快速回归的格式化契约。
+// 两类覆盖（与 subagent-list-injector.test.ts 对称）：
+// 1. 纯函数：summarizeDescription（截断）+ parseWorkflowMeta（meta 块解析）+
+//    formatWorkflowList（B2 注入段格式 + 引导语）。discoverAllWorkflows 依赖文件系统
+//    + resource-discovery，属集成层，此处聚焦可快速回归的格式化契约（TC5 回归保护）。
+// 2. session 级缓存行为（TC1-TC4）：与 subagent 对称，mock shared/resource-discovery
+//    的 discoverResources + getCachedFileContent，mock pi.on 捕获三 handler 手动触发；
+//    模块级缓存靠 vi.resetModules + 动态 import 重置。
 
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { DiscoveredResource } from "../../shared/resource-discovery.ts";
+
+// ── 稳定 spy（vi.hoisted 保证 resetModules 后引用不变，见 subagent 测试同款注释） ──
+const spies = vi.hoisted(() => ({
+	discoverResources: vi.fn(),
+	getCachedFileContent: vi.fn(),
+}));
+
+vi.mock("../../shared/resource-discovery.ts", () => ({
+	discoverResources: spies.discoverResources,
+	findWorkspaceRoot: () => "/ws",
+	getCachedFileContent: spies.getCachedFileContent,
+}));
+
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => ({
+		debug: () => {
+			/* no-op */
+		},
+		info: () => {
+			/* no-op */
+		},
+		warn: () => {
+			/* no-op */
+		},
+		error: () => {
+			/* no-op */
+		},
+	}),
+	setPiHandle: () => {
+		/* no-op */
+	},
+}));
+
+// ── 纯函数测试：静态 import（模块级缓存状态不影响纯函数） ──
 import {
 	formatWorkflowList,
 	parseWorkflowMeta,
@@ -34,28 +75,31 @@ describe("summarizeDescription", () => {
 });
 
 describe("parseWorkflowMeta", () => {
-	it("从 meta 块解析 name + description", () => {
+	it("从 @pi-meta 块解析 name + description", () => {
 		const src = `// header comment
-const meta = {
-  name: "chain",
-  description: "通用编排：三步链",
-  phases: ["a", "b"],
-};
+/* @pi-meta
+name: chain
+description: 通用编排：三步链
+phases: [a, b]
+*/
 rest of code`;
 		expect(parseWorkflowMeta(src)).toEqual({
 			name: "chain",
 			description: "通用编排：三步链",
+			path: "",
 		});
 	});
 
-	it("单引号包裹的值也能解析", () => {
-		const src = `const meta = {
-  name: 'parallel',
-  description: '多视角并行',
-};`;
+	it("双引号包裹的值也能解析", () => {
+		const src = `/* @pi-meta
+name: "parallel"
+description: "多视角并行"
+phases: []
+*/`;
 		expect(parseWorkflowMeta(src)).toEqual({
 			name: "parallel",
 			description: "多视角并行",
+			path: "",
 		});
 	});
 
@@ -63,14 +107,14 @@ rest of code`;
 		expect(parseWorkflowMeta("// no meta here")).toBeNull();
 	});
 
-	it("meta 块缺 name 或 description 返回 null", () => {
-		expect(parseWorkflowMeta('const meta = { name: "x" };')).toBeNull();
-		expect(parseWorkflowMeta('const meta = { description: "x" };')).toBeNull();
+	it("@pi-meta 缺 name 或 description 返回 null", () => {
+		expect(parseWorkflowMeta("/* @pi-meta\ndescription: x\nphases: []\n*/")).toBeNull();
+		expect(parseWorkflowMeta("/* @pi-meta\nname: x\nphases: []\n*/")).toBeNull();
 	});
 
 	it("超长 description 被截断为摘要", () => {
 		const longDesc = "详".repeat(300);
-		const src = `const meta = {\n  name: "rfl",\n  description: "${longDesc}",\n};`;
+		const src = `/* @pi-meta\nname: rfl\ndescription: ${longDesc}\nphases: []\n*/`;
 		const r = parseWorkflowMeta(src);
 		expect(r).not.toBeNull();
 		expect(r!.name).toBe("rfl");
@@ -78,14 +122,14 @@ rest of code`;
 	});
 
 	it("review-fix-loop 风格的 meta（长 description 含关键 args）被合理截断", () => {
-		const src = `const meta = {
-  name: "review-fix-loop",
-  description: "审查-修复循环：多批串行（批内并行 review → aggregate → fix → 重审直到 clean）。必填 targetType（git-diff/file/dir/text）+ target。批次由必填参数 batch1..batchN 控制（无默认，至少传一个；agents 为单批简写；如 batch1=fallow-scan batch2=reviewer）。更多细节省略。",
-};`;
+		const src = `/* @pi-meta
+name: review-fix-loop
+description: 审查-修复循环：多批串行（批内并行 review → aggregate → fix → 重审直到 clean）。必填 targetType（git-diff/file/dir/text）+ target。批次由必填参数 batch1..batchN 控制（无默认，至少传一个；agents 为单批简写；如 batch1=fallow-scan batch2=reviewer）。更多细节省略。
+phases: [Review, Fix]
+*/`;
 		const r = parseWorkflowMeta(src);
 		expect(r).not.toBeNull();
 		expect(r!.name).toBe("review-fix-loop");
-		// 截断后仍含关键 args 信息（targetType）
 		expect(r!.description).toContain("targetType");
 		expect(r!.description.length).toBeLessThanOrEqual(161);
 	});
@@ -98,31 +142,191 @@ describe("formatWorkflowList", () => {
 
 	it("用 <available_workflows> 标签包裹并列出每个 workflow", () => {
 		const out = formatWorkflowList([
-			{ name: "chain", description: "三步链" },
-			{ name: "parallel", description: "并行分析" },
+			{ name: "chain", description: "三步链", path: "/workflows/chain.js" },
+			{ name: "parallel", description: "并行分析", path: "/workflows/parallel.js" },
 		]);
 		expect(out).toContain("<available_workflows>");
 		expect(out).toContain("</available_workflows>");
 		expect(out).toContain("<name>chain</name>");
 		expect(out).toContain("<description>三步链</description>");
 		expect(out).toContain("<name>parallel</name>");
+		// S1：每项含 <location> 完整路径（agentRef，模型直接引用）
+		expect(out).toContain("<location>/workflows/chain.js</location>");
+		expect(out).toContain("<location>/workflows/parallel.js</location>");
 	});
 
 	it("包含 'Do NOT call list to discover available workflows' 引导语", () => {
-		const out = formatWorkflowList([{ name: "chain", description: "d" }]);
+		const out = formatWorkflowList([{ name: "chain", description: "d", path: "/workflows/chain.js" }]);
 		expect(out).toContain("Do NOT call list to discover available workflows");
 		expect(out).toContain("use list only for running state");
 	});
 
-	it("点名 builtin workflow 可直接 run", () => {
-		const out = formatWorkflowList([{ name: "chain", description: "d" }]);
-		expect(out).toContain("run directly");
-		expect(out).toContain("review-fix-loop");
+	it("引导语通用化：不写死内置 workflow 名，含 info 回收指引", () => {
+		const out = formatWorkflowList([{ name: "chain", description: "d", path: "/workflows/chain.js" }]);
+		expect(out).toContain("All listed workflows run directly via action:run");
+		expect(out).toContain("read the <location> script file");
+		// 通用化约束：引导语不点名具体 workflow（名字由 @pi-meta 动态注入，
+		// 写死内置名会在新增/移除 workflow 时与列表漂移）
+		expect(out).not.toMatch(/review-fix-loop|scatter-gather|map-reduce/);
 	});
 
 	it("转义 XML 特殊字符", () => {
-		const out = formatWorkflowList([{ name: "a&b", description: "<x>" }]);
+		const out = formatWorkflowList([{ name: "a&b", description: "<x>", path: "/workflows/a&b.js" }]);
 		expect(out).toContain("<name>a&amp;b</name>");
 		expect(out).toContain("&lt;x&gt;");
 	});
 });
+
+// ──────────────────────────────────────────────────────────────
+// session 级缓存行为（TC1-TC4，与 subagent 对称）
+// ──────────────────────────────────────────────────────────────
+
+/** before_agent_start handler 的返回结构（取 systemPrompt 断言）。 */
+interface BeforeAgentResult {
+	systemPrompt: string;
+}
+
+/** 三 handler 捕获引用（setupWorkflowListInjector 注册后填充）。 */
+interface CapturedHandlers {
+	sessionStart?: (event: unknown, ctx: unknown) => Promise<void> | void;
+	beforeAgentStart?: (event: { systemPrompt: string }, ctx: unknown) => Promise<BeforeAgentResult | void> | BeforeAgentResult | void;
+	sessionShutdown?: (event: unknown, ctx: unknown) => void;
+}
+
+/** 构造 mock pi：捕获三 handler 引用，其余 prop 走 noop（仅 on 被调用）。 */
+function createMockPi(handlers: CapturedHandlers): ExtensionAPI {
+	const on = (event: string, handler: (...args: unknown[]) => unknown): void => {
+		if (event === "session_start") {
+			handlers.sessionStart = handler as CapturedHandlers["sessionStart"];
+		} else if (event === "before_agent_start") {
+			handlers.beforeAgentStart = handler as CapturedHandlers["beforeAgentStart"];
+		} else if (event === "session_shutdown") {
+			handlers.sessionShutdown = handler as CapturedHandlers["sessionShutdown"];
+		}
+	};
+	const noop = (): void => {
+		/* mock */
+	};
+	return { on, appendEntry: noop, registerTool: noop, registerCommand: noop, registerMessageRenderer: noop, events: { emit: noop, on: noop } } as unknown as ExtensionAPI;
+}
+
+/** 最小 ctx mock（注入器只读 ctx.cwd）。 */
+function createMockCtx(): Record<string, unknown> {
+	return { cwd: "/ws", mode: "tui" };
+}
+
+/** fixture：单个 workflow 的 DiscoveredResource。 */
+function workflowResource(path: string): DiscoveredResource {
+	return { path, source: "project-pi-tmp", available: true };
+}
+
+/** fixture：workflow .js @pi-meta 内容。 */
+function workflowJs(name: string, description: string): string {
+	return `/* @pi-meta\nname: ${name}\ndescription: ${description}\nphases: [a]\n*/\nrest`;
+}
+
+describe("workflow-list-injector session 级缓存", () => {
+	let setupWorkflowListInjector: typeof import("../workflow-list-injector").setupWorkflowListInjector;
+	let handlers: CapturedHandlers;
+
+	beforeEach(async () => {
+		// resetModules + 动态 import：拿 fresh 模块实例 → 模块级 workflowCache 重置为 null
+		vi.resetModules();
+		spies.discoverResources.mockReset();
+		spies.getCachedFileContent.mockReset();
+		spies.discoverResources.mockResolvedValue([]);
+		spies.getCachedFileContent.mockReturnValue(null);
+		handlers = {};
+		const mod = await import("../workflow-list-injector");
+		setupWorkflowListInjector = mod.setupWorkflowListInjector;
+		setupWorkflowListInjector(createMockPi(handlers));
+	});
+
+	it("TC1: session_start 发现+缓存后，两次 before_agent_start 命中缓存（discoverResources 只调 1 次）", async () => {
+		spies.discoverResources.mockResolvedValue([workflowResource("/ws/.pi/workflows/chain.js")]);
+		spies.getCachedFileContent.mockReturnValue(workflowJs("chain", "三步链"));
+
+		await handlers.sessionStart!({ type: "session_start", reason: "new" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(1);
+
+		const r1 = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+		const r2 = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(1);
+
+		expect(r1?.systemPrompt).toContain("<available_workflows>");
+		expect(r1?.systemPrompt).toContain("<name>chain</name>");
+		expect(r2?.systemPrompt).toBe(r1?.systemPrompt);
+	});
+
+	it("TC2: session_shutdown 清缓存后 before_agent_start miss → fallback 重新发现+缓存", async () => {
+		spies.discoverResources.mockResolvedValue([workflowResource("/ws/.pi/workflows/chain.js")]);
+		spies.getCachedFileContent.mockReturnValue(workflowJs("chain", "三步链"));
+
+		await handlers.sessionStart!({ type: "session_start", reason: "new" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(1);
+
+		handlers.sessionShutdown!({ type: "session_shutdown", reason: "quit" }, createMockCtx());
+
+		const r1 = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(2);
+		expect(r1?.systemPrompt).toContain("<name>chain</name>");
+
+		const r2 = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(2);
+		expect(r2?.systemPrompt).toBe(r1?.systemPrompt);
+	});
+
+	it("TC3: 无 session_start 直接 before_agent_start（miss fallback）→ 发现+缓存", async () => {
+		spies.discoverResources.mockResolvedValue([workflowResource("/ws/.pi/workflows/chain.js")]);
+		spies.getCachedFileContent.mockReturnValue(workflowJs("chain", "三步链"));
+
+		const r1 = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+		const r2 = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+
+		expect(spies.discoverResources).toHaveBeenCalledTimes(1);
+		expect(r1?.systemPrompt).toContain("<name>chain</name>");
+		expect(r2?.systemPrompt).toBe(r1?.systemPrompt);
+	});
+
+	it("TC4: session_start(reload) 覆盖缓存（新资源生效）", async () => {
+		spies.discoverResources.mockResolvedValue([workflowResource("/ws/.pi/workflows/chain.js")]);
+		spies.getCachedFileContent.mockReturnValue(workflowJs("chain", "三步链"));
+		await handlers.sessionStart!({ type: "session_start", reason: "new" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(1);
+
+		// 资源变化：改返回 parallel
+		spies.discoverResources.mockResolvedValue([workflowResource("/ws/.pi/workflows/parallel.js")]);
+		spies.getCachedFileContent.mockReturnValue(workflowJs("parallel", "并行分析"));
+
+		await handlers.sessionStart!({ type: "session_start", reason: "reload" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(2);
+
+		const r = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(2);
+		expect(r?.systemPrompt).toContain("<name>parallel</name>");
+		expect(r?.systemPrompt).not.toContain("chain");
+	});
+
+	it("session_start 发现空列表缓存后 before_agent_start 命中（不重扫，不注入）", async () => {
+		spies.discoverResources.mockResolvedValue([]);
+		await handlers.sessionStart!({ type: "session_start", reason: "new" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(1);
+
+		const r1 = await handlers.beforeAgentStart!({ systemPrompt: "base" }, createMockCtx());
+		const r2 = await handlers.beforeAgentStart!({ systemPrompt: "base" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(1);
+		expect(r1).toBeUndefined();
+		expect(r2).toBeUndefined();
+	});
+
+	it("session_start 发现异常不阻断（fail-safe，缓存保持 null，before_agent_start fallback）", async () => {
+		spies.discoverResources.mockRejectedValueOnce(new Error("disk io"));
+		await handlers.sessionStart!({ type: "session_start", reason: "new" }, createMockCtx());
+
+		spies.discoverResources.mockResolvedValue([workflowResource("/ws/.pi/workflows/chain.js")]);
+		spies.getCachedFileContent.mockReturnValue(workflowJs("chain", "三步链"));
+		const r = await handlers.beforeAgentStart!({ systemPrompt: "" }, createMockCtx());
+		expect(spies.discoverResources).toHaveBeenCalledTimes(2);
+		expect(r?.systemPrompt).toContain("<name>chain</name>");
+	});
+});

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

@@ -18,13 +18,15 @@
  * 与同包 resource-discovery 同包后可直接 import，消除跨包依赖。
  */
 
-import * as fs from "node:fs";
+
 
 import type {
 	BeforeAgentStartEvent,
 	BeforeAgentStartEventResult,
 	ExtensionAPI,
 	ExtensionContext,
+	SessionShutdownEvent,
+	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
@@ -32,54 +34,50 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 import {
 	discoverResources,
 	findWorkspaceRoot,
+	getCachedFileContent,
 } from "../shared/resource-discovery.ts";
+import { parseResourceMeta } from "../shared/meta-parser.ts";
 
 const logger = getLogger("injector");
 
-/** 从 .md frontmatter 提取的最小 agent 信息 */
+/**
+ * Session 级 agent 列表缓存（per-process = per-session）。
+ *
+ * xyz-agent session-pool 模型下每 pi 子进程 = 一 session = 独立扩展实例，模块级缓存
+ * 天然 per-session 隔离（split mode 多 session 各自独立进程）。session_start（含
+ * reload）触发发现覆盖缓存（刷新节奏对齐 pi skill）；session_shutdown 清空；
+ * before_agent_start 读缓存，miss（session_start 未触发/缓存被清）则 fallback
+ * 重新发现——保证鲁棒。
+ */
+let agentCache: AgentEntry[] | null = null;
+
+/** 从 .md frontmatter 提取的最小 agent 信息（m5：+ when/examples 路由样本；S1：+ path） */
 export interface AgentEntry {
 	name: string;
 	description: string;
+	when?: string;
+	examples?: Array<{ match: string; action: string; positive: boolean }>;
+	/** agentRef：agent .md 文件的绝对路径（注入段 <location>，模型直接引用） */
+	path: string;
 }
 
 /**
- * 解析 markdown 文件的 YAML frontmatter。
- * 无有效 frontmatter 或缺 name/description 时返回 null。
+ * 解析 markdown 文件的 YAML frontmatter（name + description）。
  *
- * 沿用 unified-hooks 原实现：仅支持单行 key:value（builtin pi-subagents 用单行带引号
- * description）。block scalar（`>-` / `|`）不在支持范围——保持与原行为一致。
+ * m2 收敛：删本地单行 key:value parser，改调 shared/meta-parser.ts parseResourceMeta
+ * （IF1 统一 parser，支持 block scalar）。无有效 frontmatter 或缺 name/description 返 null。
+ * 投影 {name, description} 注入用（examples 注入留 m5）。
  */
 export function parseAgentFrontmatter(content: string): AgentEntry | null {
-	if (!content.startsWith("---")) return null;
-
-	const FRONTMATTER_OPEN_LEN = 3;
-	const endIndex = content.indexOf("\n---", FRONTMATTER_OPEN_LEN);
-	if (endIndex === -1) return null;
-
-	const block = content.slice(FRONTMATTER_OPEN_LEN, endIndex);
-	let name = "";
-	let description = "";
-
-	for (const line of block.split("\n")) {
-		const match = line.match(/^([\w-]+):\s*(.*)$/);
-		if (!match) continue;
-
-		const key = match[1]!;
-		let value = match[2]!.trim();
-		// 去除包裹引号
-		if (
-			(value.startsWith('"') && value.endsWith('"')) ||
-			(value.startsWith("'") && value.endsWith("'"))
-		) {
-			value = value.slice(1, -1);
-		}
-
-		if (key === "name") name = value;
-		if (key === "description") description = value;
-	}
-
-	if (!name || !description) return null;
-	return { name, description };
+	const meta = parseResourceMeta(content, "agent");
+	if (!meta || meta.kind !== "agent") return null;
+	return {
+		name: meta.name,
+		description: meta.description,
+		when: meta.when,
+		examples: meta.examples,
+		path: "", // 由 discoverAllAgents 从 DiscoveredResource.path 填充
+	};
 }
 
 /**
@@ -106,10 +104,17 @@ export async function discoverAllAgents(
 	for (const resource of resources) {
 		if (!resource.available) continue;
 		try {
-			const content = fs.readFileSync(resource.path, "utf8");
+			const content = getCachedFileContent(resource.path) ?? "";
 			const agent = parseAgentFrontmatter(content);
 			if (agent) {
-				agentMap.set(agent.name, agent);
+				agentMap.set(agent.name, { ...agent, path: resource.path });
+			} else if (content.trimStart().startsWith("---")) {
+				// m5（评审 M3/F2 + minor-5）：仅「有 frontmatter 但解析失败」才 warn
+				// （缺 name/description/examples 单条非法致整体 reject）——README 等
+				// 无 frontmatter 的 .md 不刷 warn（每 turn 扫描）。
+				logger.warn(
+					`[subagent-list-injector] ${resource.path}: agent frontmatter 解析失败（IF1 校验不通过）——agent 未注入`,
+				);
 			}
 		} catch (err) {
 			// 单个文件读失败不阻断整条 agent 列表注入
@@ -146,21 +151,57 @@ export function formatAgentList(agents: AgentEntry[]): string {
 		"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 agent names from this list. If no agent matches your task, pass systemPrompt alongside the agent name to create a dynamic agent.",
 	];
 	for (const agent of agents) {
-		lines.push(
-			`  <agent><name>${escapeXml(agent.name)}</name><description>${escapeXml(agent.description)}</description></agent>`,
-		);
+		let block = `  <agent><name>${escapeXml(agent.name)}</name><description>${escapeXml(agent.description)}</description>`;
+		// m5：路由样本（when + examples 正反原样渲染——negative 的 action 由作者写
+		// 「不调用（原因）」，渲染器不硬编码；全部内容 escapeXml 防 XML 注入段破坏）
+		if (agent.when) {
+			block += `<when>${escapeXml(agent.when)}</when>`;
+		}
+		if (agent.examples && agent.examples.length > 0) {
+			// 两极性原样渲染——negative 的 action 由作者写「不调用（原因）」，
+			// 渲染器不硬编码后缀（exec-review major-1：曾追加「（不调用）」致双后缀）
+			const exampleLines = agent.examples.map(
+				(e) => `      - "${escapeXml(e.match)}" → ${escapeXml(e.action)}`,
+			);
+			block += `\n    <examples>\n${exampleLines.join("\n")}\n    </examples>`;
+		}
+		block += `<location>${escapeXml(agent.path)}</location></agent>`;
+		lines.push(block);
 	}
 	lines.push("</available_subagents>");
 	return lines.join("\n");
 }
 
 /**
- * 注册 before_agent_start handler，注入 `<available_subagents>` 段。
+ * 注册 session 生命周期 handler，注入 `<available_subagents>` 段。
+ *
+ * 三 handler 自管缓存生命周期（不耦合 index.ts session 逻辑）：
+ * - session_start：发现+缓存赋值（fail-safe，异常不阻断，缓存保持 null）
+ * - before_agent_start：读缓存渲染注入；miss 则 fallback 发现+赋值；空列表/空注入不返回
+ *   systemPrompt；任何异常被吞掉（记日志），不阻断 agent turn
+ * - session_shutdown：清缓存
  *
  * pi 支持 async handler，且同一 event 多 handler 链式（前者返回的 systemPrompt 作
- * 后者输入）。本 handler 异步发现 + 注入；任何异常被吞掉（记日志），不阻断 agent turn。
+ * 后者输入）。
  */
 export function setupSubagentListInjector(pi: ExtensionAPI): void {
+	pi.on(
+		"session_start",
+		async (_event: SessionStartEvent, ctx: ExtensionContext): Promise<void> => {
+			try {
+				agentCache = await discoverAllAgents(
+					findWorkspaceRoot(ctx.cwd),
+					getAgentDir(),
+				);
+			} catch (err) {
+				// fail-safe：发现异常不阻断 session，缓存保持 null（before_agent_start 会 fallback）
+				logger.error("[subagent-list-injector] session_start discover failed", {
+					reason: err instanceof Error ? err.message : String(err),
+				});
+			}
+		},
+	);
+
 	pi.on(
 		"before_agent_start",
 		async (
@@ -168,11 +209,14 @@ export function setupSubagentListInjector(pi: ExtensionAPI): void {
 			ctx: ExtensionContext,
 		): Promise<BeforeAgentStartEventResult | void> => {
 			try {
-				const agents = await discoverAllAgents(
-					findWorkspaceRoot(ctx.cwd),
-					getAgentDir(),
-				);
-				const injection = formatAgentList(agents);
+				// 读缓存；miss（session_start 未触发/缓存被清）则 fallback 重新发现+赋值
+				if (agentCache === null) {
+					agentCache = await discoverAllAgents(
+						findWorkspaceRoot(ctx.cwd),
+						getAgentDir(),
+					);
+				}
+				const injection = formatAgentList(agentCache);
 				if (!injection) return;
 				return { systemPrompt: event.systemPrompt + injection };
 			} catch (err) {
@@ -182,4 +226,11 @@ export function setupSubagentListInjector(pi: ExtensionAPI): void {
 			}
 		},
 	);
+
+	pi.on(
+		"session_shutdown",
+		(_event: SessionShutdownEvent, _ctx: ExtensionContext): void => {
+			agentCache = null;
+		},
+	);
 }