@zhushanwen/pi-permission 1.6.3 → 1.6.5

package/README.md

@@ -354,7 +354,7 @@ publish 规则在后，last-match-wins 时 deny 胜出。
 - 查看决策来源：`PermissionDecision.source`（`mode` / `rule` / `ai` / `user`），区分是模式直接放行、规则命中、AI 分类还是人工审批（AST 分析不直接产生决策，只改变后续评估路径）
 - 查看命中规则：`PermissionDecision.matchedRule`（命中时携带 Rule 对象），从 `id` 可判断是 `builtin-safe`（白名单虚拟规则）、`bd-<n>`（内置危险）还是 `user-<n>`（用户规则）
 - 故意写一条 `deny` + 带 `description` 的用户规则触发拦截，从 tool_result 的 block reason 文案反查命中的是哪条规则
-- 规则 pattern 编译失败不会静默跳过：`resolvePattern` 无容错，非法 pattern 抛出的异常由 tool_call handler 兜底 fail-closed block（该次调用被拦）。实际触发面极窄——`source` 非 `user`/`builtin-safe`/`builtin-danger` 时归一化为 `user`，走 wildcard 编译（特殊字符自动转义，几乎不会失败）；只有手写配置把 `source` 写成 `builtin-danger` 且 pattern 恰为非法正则时才会抛异常。怀疑某条规则没生效时先检查 JSON 语法与 wildcard 写法
+- 规则 pattern 编译失败不会静默跳过：`resolvePattern` 无容错，非法 pattern 抛出的异常由 tool_call handler 兜底 fail-closed block（该次调用被拦）。实际触发范围极窄——`source` 非 `user`/`builtin-safe`/`builtin-danger` 时归一化为 `user`，走 wildcard 编译（特殊字符自动转义，几乎不会失败）；只有手写配置把 `source` 写成 `builtin-danger` 且 pattern 恰为非法正则时才会抛异常。怀疑某条规则没生效时先检查 JSON 语法与 wildcard 写法
 
 ## AI Classifier
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-permission",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "description": "Pi permission extension — four permission modes (yolo/auto/approve/strict) with three-layer pipeline (AST + rules + AI classifier).",
   "type": "module",
   "main": "src/index.ts",
@@ -52,7 +52,7 @@
     "web-tree-sitter": "^0.26.11",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-llm-shared": "0.11.3"
+    "@zhushanwen/pi-llm-shared": "0.12.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^1.0.0",

package/src/__tests__/approval.test.ts

@@ -286,7 +286,7 @@ describe("ApprovalComponent（G4 invalidate）", () => {
 		expect(result.approved).toBe(false);
 	});
 
-	it("handleInput 在 resolved 后 no-op（守卫）", () => {
+	it("handleInput 在 resolved 后 no-op（检查）", () => {
 		const done = vi.fn();
 		const comp = new ApprovalComponent(req, { requestRender: vi.fn() }, done);
 		comp.handleInput("\r"); // 首次 approve（Enter）

package/src/__tests__/footer-provider.test.ts

@@ -96,7 +96,7 @@ function makeRegistry(): MockFooterRegistry {
 	};
 }
 
-/** 读当前 slot（version 守卫后）。 */
+/** 读当前 slot（version 检查后）。 */
 function getRawSlot(): unknown {
 	return Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY);
 }

package/src/__tests__/index-integration.test.ts

@@ -23,7 +23,7 @@ import permissionExtension from "../index.js";
 import { FOOTER_HANDSHAKE_KEY, REQUEST_RENDER_KEY } from "../footer-provider.js";
 
 // migrateLegacyConfig 包 spy 计数（透传真实实现，行为零改变）：迁移接线用例的
-// 操作级去重断言（双派发 spy = 1）经此观测，文件面断言（mtime/内容不变）同源有效。
+// 操作级去重断言（双派发 spy = 1）经此观测，文件侧断言（mtime/内容不变）同源有效。
 const { spyMigrateLegacyConfig } = vi.hoisted(() => ({
 	spyMigrateLegacyConfig: vi.fn(),
 }));
@@ -295,7 +295,7 @@ describe("W8 /permission rule 命令集成", () => {
 		const { pi, calls } = createMockPi();
 		permissionExtension(pi);
 		const handler = getPermissionHandler(calls);
-		// notify spy 注入 ctx（commands.test.ts 同款 vi.fn 形态）：headless 降级提示的可观测面
+		// notify spy 注入 ctx（commands.test.ts 同款 vi.fn 形态）：headless 降级提示的可观测范围
 		const notify = vi.fn();
 		const ctx = {
 			mode: "json",
@@ -406,13 +406,13 @@ describe("footer line 注册", () => {
 });
 
 // ──────────────────────── session_start 配置路径迁移接线（index.ts migrateLegacyConfig 调用）────────────────────────
-// 迁移经 oncePerProcess 守卫（u-audit-fix 收编原内联 once flag），守卫的模块级 Map
+// 迁移经 oncePerProcess 检查（u-audit-fix 收编原内联 once flag），检查的模块级 Map
 // 跨用例残留：用 vi.resetModules() + 动态 import 取新鲜模块实例，否则前面用例已触发过
 // session_start，迁移分支永不执行（静默不测）。
-// 末两条为守卫双派发实测（u-audit-fix 探针）：
+// 末两条为检查双派发实测（u-audit-fix 探针）：
 //   a) 操作级去重：双派发下 spy migrateLegacyConfig 调用 = 1（warn 在 migrateLegacyConfig
 //      调用点内部，调用 = 1 构造性蕴含 warn ≤ 1，不另设断言）；
-//   b) 文件面：第二次派发后重建的旧文件原样保留、新路径 mtime/内容严格不变；
+//   b) 文件侧：第二次派发后重建的旧文件原样保留、新路径 mtime/内容严格不变；
 //   c) 豁免项防误伤：footer 注册为纯内存初始化（registry.register 同 id 覆盖），不在
 //      包装范围——双派发仍每次执行（pending push ×2）。
 describe("session_start 配置路径迁移接线", () => {
@@ -453,7 +453,7 @@ describe("session_start 配置路径迁移接线", () => {
 		expect(existsSync(LEGACY_PATH)).toBe(false);
 	});
 
-	it("once 守卫：同进程第二次 session_start 不重复迁移（重建旧文件不动）", async () => {
+	it("once 检查：同进程第二次 session_start 不重复迁移（重建旧文件不动）", async () => {
 		rmSync(CONFIG_PATH, { force: true });
 		writeLegacyConfig("auto");
 
@@ -464,7 +464,7 @@ describe("session_start 配置路径迁移接线", () => {
 		handler({}, makeCtx("json"));
 		expect(existsSync(LEGACY_PATH)).toBe(false); // 首次已迁移
 
-		// 重建旧文件（模拟外部残留），再次触发 session_start → oncePerProcess 守卫跳过迁移
+		// 重建旧文件（模拟外部残留），再次触发 session_start → oncePerProcess 检查跳过迁移
 		writeLegacyConfig("yolo");
 		handler({}, makeCtx("json"));
 		expect(existsSync(LEGACY_PATH)).toBe(true); // 未被再次消费
@@ -498,8 +498,8 @@ describe("session_start 配置路径迁移接线", () => {
 		expect(existsSync(CONFIG_PATH)).toBe(false); // 迁移不凭空造新配置
 	});
 
-	// ── oncePerProcess 守卫双派发实测（u-audit-fix 探针）──
-	it("双派发下 migrateLegacyConfig 仅执行一次：spy = 1，文件面首次迁移到位、第二次 mtime/内容不变", async () => {
+	// ── oncePerProcess 检查双派发实测（u-audit-fix 探针）──
+	it("双派发下 migrateLegacyConfig 仅执行一次：spy = 1，文件侧首次迁移到位、第二次 mtime/内容不变", async () => {
 		// spy 是文件级单例（跨 resetModules 保留计数），前面用例已触发过迁移 → 先清零
 		spyMigrateLegacyConfig.mockClear();
 		// 预置旧路径文件（新路径不存在 → 走 renameSync 迁移分支）
@@ -520,11 +520,11 @@ describe("session_start 配置路径迁移接线", () => {
 		const contentAfterFirst = readFileSync(CONFIG_PATH, "utf-8");
 
 		// 第二次派发（factory 二调/handler 累积形态：同一 handler 引用再调）：
-		// 重建旧路径文件模拟外部残留——守卫已消费 key，不得再次触碰任何文件。
+		// 重建旧路径文件模拟外部残留——检查已消费 key，不得再次触碰任何文件。
 		writeLegacyConfig("yolo");
 		handler({}, makeCtx("json"));
 
-		// 探针 a：操作级去重（spy 透传真实实现，文件面与计数同源）
+		// 探针 a：操作级去重（spy 透传真实实现，文件侧与计数同源）
 		expect(spyMigrateLegacyConfig).toHaveBeenCalledTimes(1);
 		// 探针 b：第二次后重建的旧文件原样保留、新路径 mtime/内容严格不变
 		expect(existsSync(LEGACY_PATH)).toBe(true);

package/src/__tests__/legacy-tool-names.test.ts

@@ -14,6 +14,9 @@
  *     注册，D3「旧名不保留别名」），不对其迁移后结论作断言；
  *  5b. 反向混合集（wildcard deny 在前、精确 allow 在后）——与分支5互为镜像，
  *     区分度弱，承重位置锚 = 精确条目仍在 wildcard 之前。
+ *  6. subagents → subagent_batch（2026-10-23 批量工具改名入表）——单目标展开：
+ *     展开正确 + 字段保留 + 幂等 + 保序位置锚 + 真实 matcher 结论等价四维度合并
+ *     锁定（单元素展开无次序承重，四维度一用例足够）。
  *
  * 匹配器行为注释：matchNonBashTool 的 tool 字段经 wildcardToRegExp 全锚定匹配
  * （精确名 = 精确匹配，'*' = 匹配全部）；pattern 对 path 匹配（path 缺省时对
@@ -34,7 +37,7 @@ function userRule(overrides: Partial<Rule> & { id: string; tool: string }): Rule
 	};
 }
 
-describe("旧工具名精确规则迁移（D3）— 表驱动六用例（五分支 + 分支5b 反向混合集）", () => {
+describe("旧工具名精确规则迁移（D3）— 表驱动七用例（六分支 + 分支5b 反向混合集）", () => {
 	it("分支1：精确旧名展开（subagent 三条 + workflow 两条，展开顺序承重，其余字段保留）", () => {
 		const rules: Rule[] = [
 			userRule({ id: "user-1", tool: "subagent", pattern: "*", action: "deny", description: "no subagent" }),
@@ -163,7 +166,7 @@ describe("旧工具名精确规则迁移（D3）— 表驱动六用例（五分
 	it("分支5b：反向混合集（wildcard deny 在前、精确 allow 在后）保序——新名结论 = 旧名结论", () => {
 		// 与分支5互为镜像：旧名调用结论 = deny（尾部精确 allow 被…不——allow 在
 		// wildcard deny 之后，last-match-wins 下 allow 胜。若错误追加，新名 allow
-		// 落在最后 → 仍 allow，本场景区分度弱；承重面是「精确条目仍在 wildcard
+		// 落在最后 → 仍 allow，本场景区分度弱；关键部分是「精确条目仍在 wildcard
 		// 之前」的位置锚 + 与分支5合并覆盖两个方向）。
 		const mixed: Rule[] = [
 			userRule({ id: "user-1", tool: "*", pattern: "*", action: "deny" }),
@@ -196,4 +199,36 @@ describe("旧工具名精确规则迁移（D3）— 表驱动六用例（五分
 		expect(matchNonBashTool("bash", "/x", migrated).action).toBe(matchNonBashTool("bash", "/x", mixed).action);
 		expect(matchNonBashTool("bash", "/x", mixed).action).toBe("deny");
 	});
+
+	it("分支6：subagents → subagent_batch（2026-10-23 批量工具改名入表）— 展开 + 幂等 + 保序 + matcher 结论等价", () => {
+		// 展开正确 + 字段保留：单目标展开（一条旧名规则 → 一条 subagent_batch）
+		const rules: Rule[] = [
+			userRule({ id: "user-1", tool: "subagents", pattern: "*", action: "deny", description: "no batch" }),
+			userRule({ id: "user-2", tool: "*", pattern: "*", action: "allow" }),
+		];
+		const migrated = migrateLegacyToolRules(rules);
+
+		// 保序位置锚：展开条目原位替换，wildcard 仍在后（单目标无展开次序承重）
+		expect(migrated).toHaveLength(2);
+		expect(migrated.map((r) => r.tool)).toEqual(["subagent_batch", "*"]);
+		// pattern/action/source/description 保留（只换 tool 名与 id）
+		expect(migrated[0]).toMatchObject({ pattern: "*", action: "deny", source: "user", description: "no batch" });
+		// 新 id（D3 契约②）：不克隆原 id，形态 user-N
+		expect(migrated[0]?.id).not.toBe("user-1");
+		expect(migrated[0]?.id).toMatch(/^user-\d+$/);
+		// 纯函数：原数组不改写
+		expect(rules).toHaveLength(2);
+		expect(rules[0]?.tool).toBe("subagents");
+
+		// 幂等：新名不在旧名集合，再迁移深度相等
+		expect(migrateLegacyToolRules(migrated)).toEqual(migrated);
+
+		// 真实 matcher 结论等价：场景同分支5（尾部 wildcard allow 覆盖精确 deny）——
+		// 若实装错误地把展开条目追加到数组尾部，subagent_batch deny 落到 wildcard
+		// allow 之后 → 结论翻成 deny ≠ 迁移前 allow，本断言即红灯。
+		const beforeSubagents = matchNonBashTool("subagents", "/x", rules).action;
+		const afterBatch = matchNonBashTool("subagent_batch", "/x", migrated).action;
+		expect(beforeSubagents).toBe("allow");
+		expect(afterBatch).toBe(beforeSubagents);
+	});
 });

package/src/__tests__/model-picker.test.ts

@@ -285,7 +285,7 @@ describe("MPT5: ProviderModelSelectorComponent model onSelect", () => {
 		expect(comp.render(80).join("\n")).toContain("Select Provider"); // 回到 provider stage
 	});
 
-	it("_resolved 守卫：done 后再 handleInput no-op", () => {
+	it("_resolved 检查：done 后再 handleInput no-op", () => {
 		const done = vi.fn();
 		const models = makeModelsMap({ "co": [makeEntry("co", "m1")] });
 		const comp = new ProviderModelSelectorComponent("auto", ["co"], models, done);

package/src/__tests__/production.test.ts

@@ -1,12 +1,12 @@
 /**
  * production.test.ts — createProductionClassifier + createPipelineDeps 装配测试。
  *
- * C1a 收口后 createProductionClassifier(ctx) 的 resolveModel 注入走 llm-shared resolveModel
+ * C1a 收敛后 createProductionClassifier(ctx) 的 resolveModel 注入走 llm-shared resolveModel
  * （不再预检凭证），callLLM 注入闭包捕获 ctx（凭证在 callLLM 内部 getApiKeyAndHeaders）。
  * 测试用 mock ctx.modelRegistry + vi.mock llm-shared（resolveModel + callLLM）精确控制，覆盖：
  *  - TC1: toSelector 任意字符串 → ref 精确选择器（'auto' 不走 selector，由 resolveModel 注入层本地处理）
  *  - TC3: 'auto' 且 getAvailable 空 → resolveModel 返回 null → fail-closed ask（不触达 callLLM）
- *  - TC4（静态断言）: production.ts 收口完成——无 getApiProvider/streamSimple/@ts-ignore，走 callLLM
+ *  - TC4（静态断言）: production.ts 收敛完成——无 getApiProvider/streamSimple/@ts-ignore，走 callLLM
  *  - TC4（装配）: resolveModel 命中 → callLLM 收到 model → ok:true 正常分类（链路通）
  *  - TC5: callLLM 返回 ok:false（LLM 调用失败）→ classifier fail-closed fallback
  *  - TC7: 'auto' 直接取 getAvailable() 首个（permission 本地解析，不经过 llm-shared 非精确 selector）
@@ -129,7 +129,7 @@ describe("createProductionClassifier", () => {
 	});
 });
 
-// ──────────────────────── resolveModel 装配（C3 + C1a 收口） ────────────────────────
+// ──────────────────────── resolveModel 装配（C3 + C1a 收敛） ────────────────────────
 
 describe("resolveModel 装配（resolveModel + callLLM）", () => {
 	const CTX = { toolName: "bash", command: "ls", cwd: "/tmp" };
@@ -147,19 +147,19 @@ describe("resolveModel 装配（resolveModel + callLLM）", () => {
 		expect(callLLMShared).not.toHaveBeenCalled();
 	});
 
-	it("TC4（静态断言）: production.ts 收口完成——无 getApiProvider/streamSimple/@ts-ignore，classifier 走 callLLM", () => {
+	it("TC4（静态断言）: production.ts 收敛完成——无 getApiProvider/streamSimple/@ts-ignore，classifier 走 callLLM", () => {
 		const source = readFileSync(new URL("../production.ts", import.meta.url), "utf-8");
 		// 匹配代码形式（import 调用 / 字段定义），注释里的历史描述不算残留
 		expect(source).not.toMatch(/getApiProvider\s*\(/);
 		expect(source).not.toMatch(/streamSimple\s*[:=]/);
 		expect(source).not.toMatch(/\/\/\s*@ts-ignore/);
 		expect(source).not.toMatch(/import\s*\{[^}]*getApiProvider/);
-		// classifier LLM 调用收口到 llm-shared callLLM（注入闭包捕获 ctx）
+		// classifier LLM 调用收敛到 llm-shared callLLM（注入闭包捕获 ctx）
 		expect(source).toMatch(/callLLM\s*:/);
 		expect(source).toContain('from "@zhushanwen/pi-llm-shared"');
 	});
 
-	it("TC4（装配）: ref resolveModel 命中 → callLLM 收到 model → ok:true 正常分类（收口链路通）", async () => {
+	it("TC4（装配）: ref resolveModel 命中 → callLLM 收到 model → ok:true 正常分类（收敛链路通）", async () => {
 		vi.mocked(resolveModelShared).mockReturnValue(MOCK_MODEL_A);
 		vi.mocked(callLLMShared).mockResolvedValue({
 			ok: true,
@@ -168,7 +168,7 @@ describe("resolveModel 装配（resolveModel + callLLM）", () => {
 		const classifier = createProductionClassifier(makeMockCtx());
 		const result = await classifier.classifyRisk(CTX, CFG_REF);
 		expect(result.outcome).toBe("allow");
-		// 关键：resolveModel 返回 model 后，callLLM 被调用且收到该 model（收口链路 resolve→callLLM 通）
+		// 关键：resolveModel 返回 model 后，callLLM 被调用且收到该 model（收敛链路 resolve→callLLM 通）
 		expect(callLLMShared).toHaveBeenCalledOnce();
 		// callLLM(ctx, opts) 两个参数：mock.calls[0] = [ctx, opts]
 		const opts = vi.mocked(callLLMShared).mock.calls[0]![1];

package/src/__tests__/rule-editor-component.test.ts

@@ -7,7 +7,7 @@
  *  - list stage [+ Add] → add stage
  *  - add stage 选模板 → fill stage
  *  - [Done] → settle ops
- *  - _resolved 守卫
+ *  - _resolved 检查
  *  - currentListRules 实时反映 ops（G2）
  *  - WR1 handleInput 锁定（Container override 委托）
  *  - Tab 焦点路由（WR8）
@@ -134,9 +134,9 @@ describe("REC4: fill stage 命令选择 + commitFill", () => {
 	});
 });
 
-// ──────────────────────── _resolved 守卫 ────────────────────────
+// ──────────────────────── _resolved 检查 ────────────────────────
 
-describe("REC5: _resolved 守卫", () => {
+describe("REC5: _resolved 检查", () => {
 	it("settle 后再 handleInput no-op（done 只调一次）", () => {
 		const { comp, done } = createComp();
 		// 选 [Done]
@@ -226,7 +226,7 @@ describe("REC9: cancel", () => {
 		expect(done).toHaveBeenCalledOnce();
 	});
 
-	it("cancel 后 _resolved 守卫生效", () => {
+	it("cancel 后 _resolved 检查生效", () => {
 		const { comp, done } = createComp();
 		comp.cancel();
 		comp.cancel();

package/src/approval.ts

@@ -12,7 +12,7 @@
  * ApprovalComponent 是简化版 TUI 组件（参考 ask-user AskUserComponent）：
  *  - 显示工具名 + 命令 + 触发原因 + 可选 AI 预分类。
  *  - Enter/approve、Esc/deny。
- *  - signal abort → comp.cancel()（复用 _resolved 守卫，避免二次 done）。
+ *  - signal abort → comp.cancel()（复用 _resolved 检查，避免二次 done）。
  *
  * W6 T9 G3 Reject-with-Reason：用户拒绝时，若 ctx.ui.input 存在则弹出文本输入框
  * 采集真实拒绝理由（回传给 agent，辅助理解为何被拒）；ctx.ui.input 不存在则 fallback
@@ -105,7 +105,7 @@ async function requestTui(
 
 	return approvalCtx.ui.custom<UserDecision>((tui, _theme, _kb, done) => {
 		const comp = new ApprovalComponent(req, tui as TuiLike, done);
-		// signal abort → comp.cancel()（复用 _resolved 守卫，避免二次 done）
+		// signal abort → comp.cancel()（复用 _resolved 检查，避免二次 done）
 		if (signal) {
 			signal.addEventListener("abort", () => comp.cancel(), { once: true });
 		}
@@ -275,7 +275,7 @@ interface TuiLike {
  * 键位：Enter → approve；Esc → deny/cancel（y/n 快捷键已移除，测试钉住 no-op）。
  *
  * G4：implements Component，补 invalidate()（调 tui.requestRender()）。
- * signal abort → cancel()（复用 _resolved 守卫）。
+ * signal abort → cancel()（复用 _resolved 检查）。
  *
  * TODO W6：若需更丰富的 TUI（方向键选择 once/session/always scope、高亮风险等级、
  * Reject-with-Reason 的内联文本输入），参考 ask-user AskUserComponent 的 SelectList
@@ -345,7 +345,7 @@ export class ApprovalComponent implements Component {
 		this.done({ approved: false, reason: "denied via tui" });
 	}
 
-	/** 取消（signal abort 调用）。复用 _resolved 守卫，避免二次 done。 */
+	/** 取消（signal abort 调用）。复用 _resolved 检查，避免二次 done。 */
 	cancel(): void {
 		if (this._resolved) return;
 		this._resolved = true;

package/src/ast/__tests__/analyzer.test.ts

@@ -153,7 +153,7 @@ describe("WT16-WT19: malformed 语法（parseError=true）", () => {
 		expect(r.clean).toBe(false);
 	});
 
-	it("WT18: unclosed \" —— 未闭合双引号", async () => {
+	it("WT18: unclosed \" —— 未结束的双引号", async () => {
 		const r = await analyzeBashStructure('echo "unclosed');
 		expect(r.parseError).toBe(true);
 		expect(r.clean).toBe(false);

package/src/ast/analyzer.ts

@@ -181,7 +181,7 @@ function parseChildToken(child: Node): string | null {
 /**
  * 从一个 command 节点提取 argv（对应 Rust parse_plain_command_from_node）。
  *
- * 主函数编排：类型守卫 → 逐 named child 分发（parseChildToken）→ 组装 words。
+ * 主函数编排：类型检查 → 逐 named child 分发（parseChildToken）→ 组装 words。
  * 任一 child 解析失败 → 返回 null。
  */
 function parsePlainCommand(cmd: Node): string[] | null {

package/src/classifier/__tests__/classifier.test.ts

@@ -1,7 +1,7 @@
 /**
  * CT 系列：classifier.ts 单元测试（createClassifier + classifyRisk 主流程）。
  *
- * C1a 收口后 classifier 的 LLM 调用走 llm-shared callLLM（依赖注入 deps.callLLM，
+ * C1a 收敛后 classifier 的 LLM 调用走 llm-shared callLLM（依赖注入 deps.callLLM，
  * mock 返回 CallLLMResult 判别联合）。stopReason 归一化在 callLLM 层完成，
  * classifier 消费 ok:false + stopReason 透传字段保留日志区分。
  *

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

@@ -1,7 +1,7 @@
 /**
  * MRT 系列：model-resolver.ts 单元测试（picker 相关 API）。
  *
- * E2（CL-picker-scope 收口）后 listAvailableModels 改走 ctx.modelRegistry.getAll() +
+ * E2（CL-picker-scope 收敛）后 listAvailableModels 改走 ctx.modelRegistry.getAll() +
  * hasConfiguredAuth() 过滤（不再读 models.json），loadModelsJson / flattenModels 已删除。
  * E1：ResolvedModelEntry.apiKey / hasApiKey 已删。
  *

package/src/classifier/classifier.ts

@@ -7,7 +7,7 @@
  *
  * 关键设计：
  *   - 依赖注入 ClassifierDeps（callLLM 注入，便于测试 mock，不直接 import）
- *   - C1a 收口：LLM 调用走 llm-shared callLLM（内部完成凭证 getApiKeyAndHeaders +
+ *   - C1a 收敛：LLM 调用走 llm-shared callLLM（内部完成凭证 getApiKeyAndHeaders +
  *     completeSimple + stopReason 归一化：error/aborted → {ok:false,
  *     stopReason 透传}），不再走 production.ts 的 streamSimple
  *   - G3 修正（由 callLLM 承接）：completeSimple 的 EventStream.result() 只 resolve 不 reject，
@@ -51,9 +51,9 @@ const CLASSIFY_FALLBACK_RESULT: ClassifierResult = {
  * Classifier 的外部依赖（DI 便于测试 mock）。
  *
  * - resolveModel（async）：把 ClassifierConfig.model 解析为 Model<Api>（或 null）。
- *   P3 收口后 model 解析走 llm-shared resolveModel（ctx.modelRegistry 三源合并）。
+ *   P3 收敛后 model 解析走 llm-shared resolveModel（ctx.modelRegistry 三源合并）。
  * - callLLM：llm-shared 的 LLM 调用封装（内部完成凭证 getApiKeyAndHeaders +
- *   completeSimple + stopReason 归一化）。C1a 收口替代原 streamSimple 注入。
+ *   completeSimple + stopReason 归一化）。C1a 收敛替代原 streamSimple 注入。
  * - onLog：可选日志回调（调试/审计）
  */
 export interface ClassifierDeps {

package/src/classifier/model-resolver.ts

@@ -1,13 +1,13 @@
 /**
  * model picker 的模型列表（picker 用，非 classifier）。
  *
- * P3 收口后 classifier 不再自读 models.json（改走 llm-shared resolveModel +
+ * P3 收敛后 classifier 不再自读 models.json（改走 llm-shared resolveModel +
  * ctx.modelRegistry，见 classifier.ts / production.ts）。
  *
- * E2（CL-picker-scope 收口）：listAvailableModels 改走 ctx.modelRegistry.getAll() +
+ * E2（CL-picker-scope 收敛）：listAvailableModels 改走 ctx.modelRegistry.getAll() +
  * hasConfiguredAuth() 过滤——用户只经 `pi auth login` 配的内置/OAuth provider 同样可见，
  * 不再自读 models.json（loadModelsJson / flattenModels 已删除）。
- * E1：ResolvedModelEntry.apiKey 死字段已删（P3 收口后凭证走 modelRegistry，无消费者）。
+ * E1：ResolvedModelEntry.apiKey 死字段已删（P3 收敛后凭证走 modelRegistry，无消费者）。
  * E5：name/baseUrl/cost 死字段已删（picker 只读 id/api）。
  */
 

package/src/commands.ts

@@ -126,7 +126,7 @@ function modeHighlight(mode: PermissionMode): string {
  *  2. pickModelViaOverlay：TUI/RPC/headless 三模式分发。
  *  3. 写回：save(newConfig)。失败 → notify error。
  *
- * save 为普通函数参数（唯一真实变化轴：保存 + footer 重绘副作用）。
+ * save 为普通函数参数（唯一真实变化原因：保存 + footer 重绘副作用）。
  * ctx 用 ModelPickerContext 子集（mode + modelRegistry + ui.notify/custom/select）。
  */
 export async function handlePermissionModelCommand(
@@ -181,7 +181,7 @@ export async function handlePermissionModelCommand(
  *  2. ops 非空 → applyOps + saveConfig + notify。
  *  3. 空 → notify no changes。
  *
- * save 为普通函数参数（唯一真实变化轴：保存 + footer 重绘副作用，与同步路径 onSave 同款）。
+ * save 为普通函数参数（唯一真实变化原因：保存 + footer 重绘副作用，与同步路径 onSave 同款）。
  */
 export async function handlePermissionRuleCommand(
 	ctx: RuleEditorContext,

package/src/config.ts

@@ -145,7 +145,7 @@ function warnLegacyConfigIfExists(): void {
  * D3：subagent/workflow 拆分改名后，持久化的旧名精确规则原地展开为新名规则——
  * 原地替换保序 + makeNextIdCounter 新 id + 幂等；只内存展开，不回写落盘，加载路径纯读）。
  * 所有配置消费方（pipeline / rule-editor / statusline / commands）都经本入口取 config，
- * 迁移单点在此即全消费面生效。
+ * 迁移单点在此即全部消费方生效。
  */
 export function loadAndWatchConfig(onWarning?: (msg: string) => void): PermissionConfig {
 	const configPath = getConfigPath();

package/src/footer-provider.ts

@@ -68,7 +68,7 @@ interface FooterHandshakeSlot {
 	pending: PendingEntry[];
 }
 
-// ── Slot 读取（version + 结构守卫）──
+// ── Slot 读取（version + 结构检查）──
 
 /**
  * 从 globalThis 读 slot；version !== 1 或结构不合规视为无 slot（返回 undefined）。
@@ -80,7 +80,7 @@ function readSlot(): FooterHandshakeSlot | undefined {
 	const slot = Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY);
 	if (slot === undefined) return undefined;
 	if (typeof slot !== "object" || slot === null) return undefined;
-	// 双字段 in 守卫：version + pending 都在才视为 slot 雏形（避免 as 到全可选类型的无校验断言）
+	// 双字段 in 检查：version + pending 都在才视为 slot 雏形（避免 as 到全可选类型的无校验断言）
 	if (!("version" in slot) || !("pending" in slot)) return undefined;
 	const loose = slot as { version: unknown; pending: unknown };
 	if (loose.version !== HANDSHAKE_VERSION) {

package/src/index.ts

@@ -43,7 +43,7 @@ import { paletteFromTheme, type PermissionPalette } from "./statusline-palette.j
 // Added in v1.0.0. Remove after v2.0.0 (one major past).
 // session_start 首次触发时把旧路径 permission-config.json 迁到 config/permission-ext-config.json。
 // 幂等、best-effort（migrateLegacyConfig 见 @zhushanwen/pi-llm-shared）。
-// 写 agentDir 全局配置文件属跨 session 副作用——oncePerProcess 守卫防 factory 二调/handler
+// 写 agentDir 全局配置文件属跨 session 副作用——oncePerProcess 检查防 factory 二调/handler
 // 累积双跑（u-audit-fix 收编原内联 once flag；key 带包名前缀避撞，见 pi-ext-guards JSDoc）。
 // agentDir 由 getAgentDir() 推导（尊重 PI_CODING_AGENT_DIR）。
 
@@ -90,7 +90,7 @@ const _UI_OPTIONS_PARAM_INDEX = 2;
  *
  * select/input 的 opts 类型经 `Parameters<typeof ...>[typeof _UI_OPTIONS_PARAM_INDEX]`
  * 索引提取（字面量索引会触发 no-magic-numbers，typeof 常量索引语义等价）。
- * input 可选守卫展开：SDK 提供，mock/headless 可能缺失——rule-editor custom 模板
+ * input 可选检查展开：SDK 提供，mock/headless 可能缺失——rule-editor custom 模板
  * 文本输入与 Reject-with-Reason（approval.ts collectRejectReason）都依赖此透传。
  */
 function makeUiAdapter(ui: ExtensionUIContext) {

package/src/model-picker.ts

@@ -16,7 +16,7 @@
  *  - ProviderModelSelectorComponent extends Container：Container 无 handleInput，必须 override
  *    委托给当前 stage 的 SelectList（WC9/WC15 critical）。
  *  - stage 切换用 clear() + addChild 重建（两态状态机）。
- *  - _resolved 守卫防二次 done（switchToModelStage 等异步路径可能重复触发）。
+ *  - _resolved 检查防二次 done（switchToModelStage 等异步路径可能重复触发）。
  */
 
 import { type Component, Container, type SelectItem, SelectList, type SelectListTheme, truncateToWidth } from "@earendil-works/pi-tui";
@@ -79,7 +79,7 @@ class TextLines implements Component {
  * 测试 WR1：直接调 comp.handleInput('\r') 验证 SelectList.onSelect 被触发（锁定键盘委托通路）。
  *
  * done 桥接：comp 构造时传入 done（由 ctx.ui.custom 的 factory 提供），内部 onSelect/onCancel
- * 最终调 done（参考 ApprovalComponent）。_resolved 守卫防二次 done。
+ * 最终调 done（参考 ApprovalComponent）。_resolved 检查防二次 done。
  */
 export class ProviderModelSelectorComponent extends Container {
 	private stage: "provider" | "model" = "provider";

package/src/production.ts

@@ -1,11 +1,11 @@
 /**
  * 生产装配层（W5 集成层）。
  *
- * P3 收口：classifier 的 model 解析改走 llm-shared resolveModel（三源合并含 OAuth/env/auth.json），
+ * P3 收敛：classifier 的 model 解析改走 llm-shared resolveModel（三源合并含 OAuth/env/auth.json），
  * 废弃自读 models.json。'auto' 由 permission 本地处理：直接取 ctx.modelRegistry.getAvailable()[0]
  * （不经过 llm-shared 的非精确 selector），与下方 createProductionClassifier JSDoc 一致。
  *
- * C1a 收口：classifier 的 LLM 调用改走 llm-shared callLLM（凭证 getApiKeyAndHeaders +
+ * C1a 收敛：classifier 的 LLM 调用改走 llm-shared callLLM（凭证 getApiKeyAndHeaders +
  * completeSimple + stopReason 归一化都在 callLLM 内部完成），删除 getApiProvider +
  * streamSimple（@ts-ignore 随之消除）。
  *
@@ -54,7 +54,7 @@ export function toSelector(modelSpec: string): ModelSelector {
  *  - model 仍 null → 返回 null（fail-closed）。
  *
  * callLLM 注入（C1a）：闭包捕获 ctx，把 llm-shared callLLM 绑定为 classifier 的 LLM 调用。
- * 凭证获取（getApiKeyAndHeaders）在 callLLM 内部完成（C1a 收口后不再在 resolveModel 层预检）。
+ * 凭证获取（getApiKeyAndHeaders）在 callLLM 内部完成（C1a 收敛后不再在 resolveModel 层预检）。
  */
 export function createProductionClassifier(ctx: ExtensionContext): {
 	classifyRisk: ReturnType<typeof createClassifier>["classifyRisk"];

package/src/rule-editor-component.ts

@@ -75,7 +75,7 @@ type FillKind =
  * TUI overlay 组件：规则 CRUD 编辑器。
  *
  * Container override handleInput（W7 模式）：按 stage 委托给当前子组件。
- * settle 用 _resolved 守卫防二次 done。
+ * settle 用 _resolved 检查防二次 done。
  */
 export class RuleEditorComponent extends Container {
 	private stage: Stage = "list";
@@ -244,7 +244,7 @@ export class RuleEditorComponent extends Container {
 		this.settle();
 	}
 
-	/** settle：_resolved 守卫 + done(this.ops)。 */
+	/** settle：_resolved 检查 + done(this.ops)。 */
 	private settle(): void {
 		if (this._resolved) return;
 		this._resolved = true;

package/src/rules/__tests__/matcher.test.ts

@@ -173,8 +173,8 @@ describe("MT-last-match-wins: 后匹配的规则胜出", () => {
 // ──────────────────────── matchRules 退化路径 ────────────────────────
 
 describe("MT-matchRules: 退化路径（command 字符串）", () => {
-	// E11：toolName 参数与 '!== bash' 守卫已删（生产调用点恒在 bash 分支内，
-	// 非 bash 由 pipeline.matchNonBashTool 承接），对应守卫用例随之移除。
+	// E11：toolName 参数与 '!== bash' 检查已删（生产调用点恒在 bash 分支内，
+	// 非 bash 由 pipeline.matchNonBashTool 承接），对应检查用例随之移除。
 
 	it("command === undefined → ask", () => {
 		const r = matchRules(undefined, getDefaultRules());

package/src/rules/index.ts

@@ -1,7 +1,7 @@
 /**
  * rules 模块 barrel —— 只 re-export 有真实消费的公开 API（E10 收敛）。
  *
- * 生产消费面 = production.ts：getDefaultRules（内置规则拼接）+ matchRulesForArgv
+ * 生产消费方 = production.ts：getDefaultRules（内置规则拼接）+ matchRulesForArgv
  * （bash argv 匹配）。其余符号（matchRules / resolvePattern / wildcardToRegExp /
  * builtins 数据）无 barrel 消费——pipeline.ts 与各测试均走深路径 import；
  * 类型一律直接从 ../types.js import，barrel 不做类型 re-export。

package/src/rules/legacy-tool-names.ts

@@ -5,6 +5,7 @@
  * subagent_start/subagent_manage/subagent_message 与 workflow_run/workflow_control，
  * 旧名不保留别名（探针 PB-fork）。用户权限规则按工具名匹配（`Rule.tool`）并持久化
  * 落盘（config.ts saveConfig），旧名精确规则随改名失配——deny 静默退化成 ask/AI 分类。
+ * 批量工具 `subagents` → `subagent_batch` 改名（2026-10-23）同机制入表。
  *
  * 迁移语义（D3 两条契约）：
  *  ① 展开落位与保序——精确匹配旧名的用户规则**原地替换**为其新名展开（展开顺序
@@ -38,6 +39,7 @@ import { makeNextIdCounter } from "../rule-templates.js";
 const LEGACY_TOOL_NAME_EXPANSION: Readonly<Record<string, readonly string[]>> = {
 	subagent: ["subagent_start", "subagent_manage", "subagent_message"],
 	workflow: ["workflow_run", "workflow_control"],
+	subagents: ["subagent_batch"],
 };
 
 /**

package/src/rules/matcher.ts

@@ -149,8 +149,8 @@ export function matchRulesForArgv(argv: string[], rules: readonly Rule[]): RuleM
  *  - 遍历 rules（last-match-wins），对每条用 resolvePattern(rule).test(command)
  *  - 无匹配 → ask（G1）
  *
- * E11：toolName 参数与 `toolName !== 'bash'` 守卫已删——生产调用点（pipeline.runLayer2）
- * 恒在 bash 分支内调用，非 bash 由 matchNonBashTool 承接，守卫是不可达的投机分支。
+ * E11：toolName 参数与 `toolName !== 'bash'` 检查已删——生产调用点（pipeline.runLayer2）
+ * 恒在 bash 分支内调用，非 bash 由 matchNonBashTool 承接，检查是不可达的投机分支。
  *
  * 不调 isKnownSafeCommand（不查白名单）：command 字符串无法可靠提取 argv
  * （含引号/转义/管道），argv 级白名单判断由 matchRulesForArgv 在 happy path 负责。

package/src/types.ts

@@ -30,7 +30,7 @@ export const MODE_LABELS: Record<PermissionMode, string> = {
 	strict: "Strict",
 };
 
-/** PermissionMode 类型守卫 */
+/** PermissionMode 类型检查 */
 export function isValidPermissionMode(value: unknown): value is PermissionMode {
 	return typeof value === "string" && PERMISSION_MODES.includes(value as PermissionMode);
 }