@zhushanwen/pi-permission 1.3.4 → 1.4.0

package/README.md

@@ -21,7 +21,7 @@ Pi permission 扩展 — 四档权限模式（yolo / auto / approve / strict）+
 pi install npm:@zhushanwen/pi-permission
 
 # 本地开发（symlink；globalExtDir 平铺布局，目标不带分组层）
-ln -s /path/to/xyz-pi-extensions-workspace/feat-permission-and-auto-mode/extensions/universal/permission \
+ln -s /path/to/xyz-agent/extensions/universal/permission \
       ~/.pi/agent/extensions/permission
 ```
 
@@ -42,7 +42,8 @@ ln -s /path/to/xyz-pi-extensions-workspace/feat-permission-and-auto-mode/extensi
     "model": "auto",
     "timeout": 90,
     "autoApproveLowRisk": true,
-    "autoDenyHighRisk": true
+    "autoDenyHighRisk": true,
+    "thinkingLevel": "off"
   },
   "userRules": []
 }
@@ -52,11 +53,12 @@ ln -s /path/to/xyz-pi-extensions-workspace/feat-permission-and-auto-mode/extensi
 |------|--------|------|
 | `mode` | `"yolo"` | 当前权限模式（yolo/auto/approve/strict） |
 | `enabled` | `true` | 扩展是否启用（false=完全放行，等同 yolo 但保留配置） |
-| `classifier.enabled` | `true` | 是否启用 AI 层（auto 模式自动 true） |
-| `classifier.model` | `"auto"` | AI 模型（`auto` = scoped：取 settings.json enabledModels 首个可用，或 `provider/model-id`） |
+| `classifier.enabled` | `true` | 是否启用 AI 层（false 时 auto 模式跳过 AI，ask 直接转人工审批） |
+| `classifier.model` | `"auto"` | AI 模型（`auto` = 取 modelRegistry.getAvailable() 首个可用，或精确 `provider/model-id`） |
 | `classifier.timeout` | `90` | AI 分类超时秒数 |
 | `classifier.autoApproveLowRisk` | `true` | 低风险是否自动放行（false=转人工） |
 | `classifier.autoDenyHighRisk` | `true` | 高风险是否自动拦截（true=强制 deny） |
+| `classifier.thinkingLevel` | `"off"` | classifier LLM 的 thinking 级别（pi `ModelThinkingLevel`；`"off"`=不传 reasoning，`"minimal"`~`"max"` 透传） |
 | `userRules` | `[]` | 用户自定义规则数组 |
 
 ## 四档模式
@@ -93,6 +95,7 @@ ln -s /path/to/xyz-pi-extensions-workspace/feat-permission-and-auto-mode/extensi
 /permission approve      切换到 approve 模式
 /permission strict       切换到 strict 模式
 /permission status       显示详细配置
+/permission rule         overlay 编辑用户规则（增/删）
 /permission model        overlay 选择 AI classifier 模型（W7）
 ```
 
@@ -160,8 +163,8 @@ wc / whereis / who / whoami / which
 | `git` | 子命令属于 `status`/`log`/`diff`/`show`/`branch` 且只读 | 见下文 git 子表 |
 | `sed` | 仅 `sed -n {N\|M,N}p [file]`（argv 长度 ≤ 4） | 其余形式不放行 |
 | `sort` | 不含写文件 flag | 禁 `-o` / `--output` / `--output=*` / `-o*`（合并 flag） |
-| `iconv` | 不含写文件 flag | 禁 `-o` / `--output` / `--output=*` |
-| `shuf` | 不含写文件 flag | 禁 `-o` / `--output` / `--output=*` |
+| `iconv` | 不含写文件 flag | 禁 `-o` / `--output` / `--output=*` / `-o*`（合并 flag 如 `-fo`） |
+| `shuf` | 不含写文件 flag | 禁 `-o` / `--output` / `--output=*` / `-o*`（合并 flag 如 `-fo`） |
 | `date` | 不含设置时间 flag | 禁 `-s` / `--set` / `--set=*`（`-s` 设置系统时间需 root） |
 
 **git 子命令安全判定细则**：
@@ -181,14 +184,14 @@ wc / whereis / who / whoami / which
 
 | id | pattern（正则字面量）| description | 匹配示例 |
 |----|----------------------|-------------|----------|
-| bd-001 | `\brm\s+(-[^\s]*r\|--recursive)` | recursive delete | `rm -rf /`、`rm -fr x`、`rm --recursive y` |
+| bd-001 | `\brm\b.*(\s-(?:[a-zA-Z]*r)\|--recursive)` | recursive delete | `rm -rf /`、`rm -f -r /`（分离 flag）、`rm --recursive y` |
 | bd-002 | `\bsudo\b` | sudo | `sudo`、`sudo -E apt update` |
-| bd-003 | `\bchmod\b.*777` | world-writable permissions | `chmod 777 /tmp`、`chmod 0777 file` |
-| bd-004 | `>\s*/dev/[sh]d[a-z]` | raw device redirect | `dd ... > /dev/sda` |
+| bd-003 | `\bchmod\b.*(777\|a\+rwx\|ugo\+rwx\|ugo=rwx)` | world-writable permissions | `chmod 777 /tmp`、`chmod a+rwx file`、`chmod ugo=rwx file` |
+| bd-004 | `(>\s*/dev/(sd\|hd\|nvme\|mmcblk\|vd\|xvd)[a-z0-9]+\|of=/dev/(sd\|hd\|nvme\|mmcblk\|vd\|xvd)[a-z0-9]+)` | raw device write | `dd ... > /dev/sda`、`dd of=/dev/nvme0n1`、`> /dev/mmcblk0` |
 | bd-005 | `\bgit\s+push\s+.*(-f\b\|--force\b)` | force push | `git push --force`、`git push -f` |
 | bd-006 | `\bgit\s+reset\s+--hard\b` | hard reset | `git reset --hard HEAD~1` |
-| bd-007 | `\bgit\s+clean\s+-[^\s]*f` | git clean | `git clean -fd`、`git clean -dfx` |
-| bd-008 | `\bgit\s+checkout\s+\.\s*($\|[;&\|])` | git checkout (discard all) | `git checkout .` |
+| bd-007 | `\bgit\s+clean\b.*(\s-(?:[a-zA-Z]*f)\|--force)` | git clean --force | `git clean -fd`、`git clean -d -f`（分离 flag）、`git clean -fx` |
+| bd-008 | `\bgit\s+checkout\s+(--\s+)?\.\s*($\|[;&\|])` | git checkout . (discard all) | `git checkout .`、`git checkout -- .` |
 | bd-009 | `\bgit\s+restore\b` | git restore | `git restore file.txt` |
 | bd-010 | `\b(curl\|wget)\b.*\|\s*(ba)?sh\b` | pipe to shell | `curl http://x \| sh`、`wget x \| bash` |
 | bd-011 | `\bgh\s+repo\s+(create\|delete\|rename\|archive)\b` | modify GitHub repo | `gh repo delete foo` |
@@ -223,7 +226,7 @@ wc / whereis / who / whoami / which
 |------|------|------|------|
 | `id` | string | 是 | 唯一 id，用户规则建议 `user-<n>`（缺失会自动分配） |
 | `tool` | string | 是 | 工具名匹配，wildcard 语法。`bash` 精确匹配 bash 工具；`*` 匹配所有工具（含 Read/Write/Edit）；也可写具体工具名如 `read`、`write` |
-| `pattern` | string | 是 | 命令/目标匹配，wildcard 语法。bash 工具对 `argv.join(' ')` 匹配；非 bash 工具对 `toolName` 匹配 |
+| `pattern` | string | 是 | 命令/目标匹配，wildcard 语法。bash 工具对 `argv.join(' ')` 匹配；非 bash 工具对文件路径匹配（path 缺省时对工具名） |
 | `action` | `"allow"` \| `"deny"` \| `"ask"` | 是 | 决策动作，详见第 8 节 |
 | `source` | `"user"` | 是 | 规则来源，用户规则固定 `user`（写成其他值也会被归一化回 `user`） |
 | `description` | string | 否 | 人类可读描述，在 matchedRule 与拒绝理由中展示 |
@@ -344,22 +347,22 @@ publish 规则在后，last-match-wins 时 deny 胜出。
 - **路径**：`<agentDir>/config/permission-ext-config.json`（`<agentDir>` 可用 `PI_CODING_AGENT_DIR` 环境变量覆盖，默认 `~/.pi/agent`）
 - **首次创建**：扩展启动时若文件不存在，自动写入默认配置（`mode: "yolo"`、空 `userRules`）
 - **权限**：`0o600`（原子写：先写 `.tmp` 再 rename，避免半写状态）
-- **编辑方式**：目前需手动编辑 JSON 文件（未来计划提供 `/permission add-rule` 命令辅助编辑）
+- **编辑方式**：`/permission rule` 打开 overlay 编辑器（TUI 支持列表查看/模板新增/自定义表单；RPC 模式仅支持删除已有规则）；也可直接手动编辑 JSON 文件
 - **热重载**：每次 tool_call 都重读配置，用 `mtimeMs + size` 双 key 缓存检测变化（防 APFS 等 mtime 精度截断）。编辑保存后下一次命令即生效，无需重启
 
 ### 11. 调试技巧
 
 - `/permission status`：查看当前配置摘要（含 `userRules` 数量）
-- 查看决策来源：`PermissionDecision.source`（`mode` / `ast` / `rule` / `ai` / `user`），区分是模式直接放行、AST 拦截、规则命中、AI 分类还是人工审批
+- 查看决策来源：`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 编译失败会被静默跳过（regex 构造异常不阻塞管道），怀疑某条规则没生效时先用 `/^(\d+,)?\d+p$/` 这类标准语法自测
+- 规则 pattern 编译失败不会静默跳过：`resolvePattern` 无容错，非法 pattern 抛出的异常由 tool_call handler 兜底 fail-closed block（该次调用被拦）。实际触发面极窄——用户规则加载时 source 归一化为 `user`，走 wildcard 编译（特殊字符自动转义，几乎不会失败）；只有手写配置写出非法正则且恰好命中 `builtin-danger` 分支才会抛异常。怀疑某条规则没生效时先检查 JSON 语法与 wildcard 写法
 
 ## AI Classifier
 
 auto 模式下层 3 用 LLM 评估未知命令风险：
 
-- **模型**：`classifier.model`（`auto` = scoped：取 enabledModels 首个可用（空则 fallback available），或指定 `provider/model-id`）
+- **模型**：`classifier.model`（`auto` = 取 `modelRegistry.getAvailable()` 首个可用，或指定精确 `provider/model-id`）
 - **输出**：`risk_level`（low/medium/high）+ `outcome`（allow/deny/ask）+ `reasoning` + `confidence`
 - **override**（WT7 偏差补丁）：
   - `low + allow + autoApproveLowRisk=false` → 强制 `ask`（转人工）
@@ -370,14 +373,15 @@ auto 模式下层 3 用 LLM 评估未知命令风险：
 
 `/permission model` 弹出 overlay 选择 AI classifier 使用的模型，写回 `classifier.model`：
 
-- **第一级 provider 选择**：列出 `Auto`（自动：scoped 取 enabledModels 首个可用）+ 所有可用 provider（来自 `~/.pi/agent/models.json`，按字母序）。当前 `classifier.model` 预选高亮。
-- **第二级 model 选择**：选中具体 provider 后，列出该 provider 下所有可用 model（按 `cost.input` 升序，并列按 id 字母序）。`Esc` 回退到 provider 列表。
+- **数据源**：`ctx.modelRegistry.getAll()` + `hasConfiguredAuth()` 过滤（`pi auth login` 配置的内置/OAuth provider 同样可见，不读 `models.json`），整体按 provider + id 字典序排序。
+- **第一级 provider 选择**：列出 `Auto`（自动：取 `modelRegistry.getAvailable()` 首个可用）+ 所有可用 provider。当前 `classifier.model` 预选高亮。
+- **第二级 model 选择**：选中具体 provider 后，列出该 provider 下所有可用 model（provider + id 字典序）。`Esc` 回退到 provider 列表。
 - **键位**：`↑/↓` 导航、`Enter` 确认、`Esc` 取消（provider stage）或回退（model stage）。
 - **三模式分发**：
   - **TUI**：`ctx.ui.custom` 渲染 overlay（`ProviderModelSelectorComponent`，两级 `SelectList` 状态机）。
   - **RPC**：两次 `ctx.ui.select`（先 provider 含 `Auto`，再 model）。
   - **headless**（json/print）：无交互 UI，返回降级提示。
-- **无可用模型**：`models.json` 不存在 / 无 provider 配 `apiKey` / 解析失败时，`listAvailableModels` 返回空 Map，命令降级为提示 `No available models. Configure ~/.pi/agent/models.json first.`（不阻塞，不修改配置）。
+- **无可用模型**：`modelRegistry` 无模型或全部未配置 auth 时，`listAvailableModels` 返回空 Map，命令降级为提示 `No available models. Run `pi auth login` or configure provider API keys, then retry.`（不阻塞，不修改配置）。
 - **结果写回**：选中后 `classifier.model` 更新为 `auto` 或 `provider/model-id`，其余字段（mode/enabled/timeout/userRules）保留。
 
 ## 已知限制
@@ -422,7 +426,7 @@ bash? ──yes──→ AST 结构分析
 - **fail-closed**：任何异常 → block（绝不静默放行）
 - **checkPermission 永不 throw**：caller（tool_call handler）依赖此契约
 - **deps 注入**：所有外部依赖（AST/规则/AI/UI）通过 CheckPermissionDeps 注入，便于测试 mock
-- **session 隔离**：config 在 session_start 重建的闭包，每 session 独立
+- **配置读时刷新**：config 不持有跨调用缓存，每次需要时直接 `loadAndWatchConfig()` 读最新（llm-shared `mtimeMs + size` 去重，文件未变只 statSync），改文件即生效
 - **纯函数核心**：checkPermission / runLayer2 / applyAutoApproveOverrides 都是纯函数
 
 ## 开发

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-permission",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "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",
@@ -50,8 +50,9 @@
   "dependencies": {
     "tree-sitter-bash": "^0.25.1",
     "web-tree-sitter": "^0.26.11",
-    "@zhushanwen/pi-extension-logger": "0.3.1",
-    "@zhushanwen/pi-llm-shared": "0.4.2"
+    "@zhushanwen/pi-ext-guards": "0.2.0",
+    "@zhushanwen/pi-extension-logger": "0.4.0",
+    "@zhushanwen/pi-llm-shared": "0.5.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",

package/skills/permission-ext-config/SKILL.md

@@ -43,7 +43,7 @@ interface PermissionConfig {
 }
 
 interface ClassifierConfig {
-  enabled: boolean;           // AI 层开关，默认 true
+  enabled: boolean;           // AI 层开关，默认 true；false 时 auto 模式跳过 AI 直接人工审批
   model: string;              // 'auto' 或 'provider/model-id'，默认 "auto"
   timeout: number;            // 超时秒，默认 90
   autoApproveLowRisk: boolean;   // 低风险自动放行，默认 true
@@ -71,15 +71,16 @@ interface ClassifierConfig {
 
 ### auto 模式的风险判定（autoApproveLowRisk / autoDenyHighRisk）
 
-AI classifier 输出三档风险，对应处理：
+AI classifier 输出 `outcome`（allow/deny/ask）+ `risk_level`（low/medium/high），**outcome 直接生效**：allow 自动放行、deny 直接拒绝、ask 转人工。两个开关只拨动两条边界 override：
 
-| 风险 | autoApproveLowRisk=true | autoDenyHighRisk=true | 实际动作 |
-|---|---|---|---|
-| low | ✓ 自动放行 | — | allow |
-| **medium** | — | — | **ask（转人工审批）** |
-| high | — | ✓ 转人工审批 | ask |
+| AI 输出 | override 条件 | 实际动作 |
+|---|---|---|
+| allow + low | `autoApproveLowRisk=false` | 改 **ask**（转人工）；默认 true 时自动放行 |
+| allow + high | `autoDenyHighRisk=true` | 改 **deny**（不问人，直接拒绝）；false 时自动放行 |
+| allow + medium | — | **自动放行**（不经人工，不受这两个开关影响） |
+| deny / ask（任意风险） | — | 原样生效（deny 拒绝；ask 转人工） |
 
-> medium 风险**总是转人工审批**，不受这两个开关影响。两个开关只拨动 low/high 的边界。
+> 也就是说：medium + allow 会自动放行；只有 low+allow 与 high+allow 这两个边界会被开关改写。想让 medium 也转人工做不到（AI 说 allow 就放行），只能换 `approve` 模式去掉 AI 层。
 
 ## 默认值
 
@@ -139,7 +140,7 @@ auto 模式 + 指定 classifier 用 glm-4-flash + 自定义危险规则：
 
 每条规则：`{ id?, tool, pattern, action, source, description? }`
 - tool：工具名（`*` 匹配全部，`bash` 精确）
-- pattern：命令模式（wildcard，仅 bash 用）
+- pattern：bash 工具对命令行匹配；非 bash 工具对文件路径匹配（path 缺省时对工具名）（wildcard）
 - action：`allow` | `deny` | `ask`
 - source：`user`（用户规则；内置规则 builtin-safe/builtin-danger 在代码里不进配置）
 - id 省略时自动分配 `user-<n>`

package/src/__tests__/approval.test.ts

@@ -83,7 +83,6 @@ describe("requestUserApproval: rpc 模式", () => {
 		});
 		const decision = await requestUserApproval(req, ctx, undefined, approvalCtx);
 		expect(decision.approved).toBe(true);
-		expect(decision.scope).toBe("once");
 	});
 
 	it("用户选 Deny → approved=false", async () => {
@@ -180,7 +179,7 @@ describe("requestUserApproval: tui 模式", () => {
 			ui: {
 				notify: vi.fn(),
 				select: vi.fn(),
-				custom: vi.fn((_factory) => Promise.resolve({ approved: true, reason: "tui-ok", scope: "once" } as UserDecision)),
+				custom: vi.fn((_factory) => Promise.resolve({ approved: true, reason: "tui-ok" } as UserDecision)),
 			},
 		});
 		const decision = await requestUserApproval(req, ctx, undefined, approvalCtx);

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

@@ -374,8 +374,9 @@ describe("footer line 注册", () => {
 });
 
 // ──────────────────────── session_start 配置路径迁移接线（index.ts migrateLegacyConfig 调用）────────────────────────
-// 模块级 once flag（configMigrationChecked）跨用例残留：用 vi.resetModules() + 动态 import
-// 取新鲜模块实例，否则前面用例已触发过 session_start，迁移分支永不执行（静默不测）。
+// 迁移经 oncePerProcess 守卫（u-audit-fix 收编原内联 once flag），守卫的模块级 Map
+// 跨用例残留：用 vi.resetModules() + 动态 import 取新鲜模块实例，否则前面用例已触发过
+// session_start，迁移分支永不执行（静默不测）。
 describe("session_start 配置路径迁移接线", () => {
 	const LEGACY_PATH = join(AGENT_DIR, "permission-config.json");
 
@@ -414,7 +415,7 @@ describe("session_start 配置路径迁移接线", () => {
 		expect(existsSync(LEGACY_PATH)).toBe(false);
 	});
 
-	it("once flag：同进程第二次 session_start 不重复迁移（重建旧文件不动）", async () => {
+	it("once 守卫：同进程第二次 session_start 不重复迁移（重建旧文件不动）", async () => {
 		rmSync(CONFIG_PATH, { force: true });
 		writeLegacyConfig("auto");
 
@@ -425,7 +426,7 @@ describe("session_start 配置路径迁移接线", () => {
 		handler({}, makeCtx("json"));
 		expect(existsSync(LEGACY_PATH)).toBe(false); // 首次已迁移
 
-		// 重建旧文件（模拟外部残留），再次触发 session_start → once flag 跳过迁移
+		// 重建旧文件（模拟外部残留），再次触发 session_start → oncePerProcess 守卫跳过迁移
 		writeLegacyConfig("yolo");
 		handler({}, makeCtx("json"));
 		expect(existsSync(LEGACY_PATH)).toBe(true); // 未被再次消费

package/src/__tests__/pipeline.test.ts

@@ -329,6 +329,82 @@ describe("checkPermission: auto 模式（AST + 规则 + AI Racing）", () => {
 	});
 });
 
+// ──────────────────────── A2: classifier.enabled=false（AI 层关闭，跳过 racing） ────────────────────────
+
+describe("A2: classifier.enabled=false（AI 层关闭，直接人工审批）", () => {
+	it("auto + 规则 ask + enabled=false → 直接人工审批（不调 classifyRisk）", async () => {
+		const classify = vi.fn(() => Promise.resolve(allowClassifier()));
+		const approve = vi.fn(() => Promise.resolve<UserDecision>({ approved: true, reason: "user-ok" }));
+		const deps = makeDeps({
+			analyze: () => Promise.resolve(cleanAnalysis([["curl"]])),
+			matchArgv: () => ({ action: "ask", matchedRule: undefined }),
+			classify,
+			approve,
+		});
+		const decision = await checkPermission(
+			"bash",
+			{ command: "curl example.com" },
+			"auto",
+			{ ...DEFAULT_CFG, enabled: false },
+			[],
+			deps,
+			ctxBase,
+		);
+		expect(decision.action).toBe("allow");
+		expect(decision.source).toBe("user");
+		expect(classify).not.toHaveBeenCalled(); // AI 层被关闭，classifier 不启动
+		expect(approve).toHaveBeenCalledOnce(); // 直接走人工审批
+	});
+
+	it("enabled=false + 用户拒绝 → deny（source=user）", async () => {
+		const classify = vi.fn(() => Promise.resolve(denyClassifier("high")));
+		const deps = makeDeps({
+			analyze: () => Promise.resolve(cleanAnalysis([["curl"]])),
+			matchArgv: () => ({ action: "ask", matchedRule: undefined }),
+			classify,
+			approve: () => Promise.resolve<UserDecision>({ approved: false, reason: "no" }),
+		});
+		const decision = await checkPermission(
+			"bash",
+			{ command: "curl example.com" },
+			"auto",
+			{ ...DEFAULT_CFG, enabled: false },
+			[],
+			deps,
+			ctxBase,
+		);
+		expect(decision.action).toBe("deny");
+		expect(decision.source).toBe("user");
+		expect(decision.reason).toBe("no");
+		expect(classify).not.toHaveBeenCalled();
+	});
+
+	it("enabled=false + headless → 人工审批路径立即 fail-closed deny（无 AI 可兜底）", async () => {
+		const classify = vi.fn(() => Promise.resolve(allowClassifier()));
+		const approve = vi.fn(() => Promise.resolve<UserDecision>({ approved: false, reason: "headless auto-deny" }));
+		const deps = makeDeps({
+			analyze: () => Promise.resolve(cleanAnalysis([["curl"]])),
+			matchArgv: () => ({ action: "ask", matchedRule: undefined }),
+			classify,
+			approve,
+			isHeadless: () => true,
+		});
+		const decision = await checkPermission(
+			"bash",
+			{ command: "curl example.com" },
+			"auto",
+			{ ...DEFAULT_CFG, enabled: false },
+			[],
+			deps,
+			ctxBase,
+		);
+		expect(decision.action).toBe("deny");
+		expect(decision.source).toBe("user");
+		expect(classify).not.toHaveBeenCalled(); // 不等 AI（enabled=false 时无 AI 层可兜底）
+		expect(approve).toHaveBeenCalledOnce();
+	});
+});
+
 // ──────────────────────── G1: matchNonBashTool ────────────────────────
 
 describe("G1: matchNonBashTool（非 bash 工具规则匹配，M5 pattern 对 path 匹配）", () => {

package/src/__tests__/production.test.ts

@@ -4,12 +4,12 @@
  * C1a 收口后 createProductionClassifier(ctx) 的 resolveModel 注入走 llm-shared resolveModel
  * （不再预检凭证），callLLM 注入闭包捕获 ctx（凭证在 callLLM 内部 getApiKeyAndHeaders）。
  * 测试用 mock ctx.modelRegistry + vi.mock llm-shared（resolveModel + callLLM）精确控制，覆盖：
- *  - TC1/TC2: toSelector 映射（'auto'→scoped / 'provider/model-id'→ref）
- *  - TC3: scoped 全空 fail-closed（resolveModel null → classifyRisk fallback，不触达 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（装配）: resolveModel 命中 → callLLM 收到 model → ok:true 正常分类（链路通）
  *  - TC5: callLLM 返回 ok:false（LLM 调用失败）→ classifier fail-closed fallback
- *  - TC7: scoped 空 fallback available（CL-scoped-fallback 退化防护）
+ *  - TC7: 'auto' 直接取 getAvailable() 首个（permission 本地解析，不经过 llm-shared 非精确 selector）
  *  - m1: 每次 createPipelineDeps 创建独立 classifier（CL-classifier-singleton）
  */
 import { readFileSync } from "node:fs";
@@ -192,7 +192,7 @@ describe("resolveModel 装配（resolveModel + callLLM）", () => {
 
 	it("TC5: callLLM 返回 ok:false（LLM 调用失败）→ classifier fail-closed fallback（不 throw）", async () => {
 		vi.mocked(resolveModelShared).mockReturnValue(MOCK_MODEL_A);
-		vi.mocked(callLLMShared).mockResolvedValue({ ok: false, error: "token expired", recoverable: true });
+		vi.mocked(callLLMShared).mockResolvedValue({ ok: false, error: "token expired" });
 		const classifier = createProductionClassifier(makeMockCtx());
 		const result = await classifier.classifyRisk(CTX, CFG_REF);
 		expect(result.outcome).toBe("ask");

package/src/__tests__/rule-templates.test.ts

@@ -4,7 +4,6 @@
  * 覆盖：
  *  - PRESET_COMMANDS 结构（31 命令，7 类 + Other）
  *  - 5 个模板 build（G4 wildcard pattern）
- *  - classifyRuleTemplate（FAMILY_RE / SUBCMD_RE + action 映射）
  *  - applyOps（add / edit / delete，纯函数）
  *  - makeNextIdCounter（从已有规则提取最大 user-N）
  */
@@ -15,7 +14,6 @@ import {
 	allowSubcmdTemplate,
 	applyOps,
 	askBeforeTemplate,
-	classifyRuleTemplate,
 	customTemplate,
 	denyFamilyTemplate,
 	makeNextIdCounter,
@@ -145,38 +143,6 @@ describe("RT2: 模板 build（G4 wildcard pattern）", () => {
 	});
 });
 
-// ──────────────────────── classifyRuleTemplate ────────────────────────
-
-describe("RT3: classifyRuleTemplate", () => {
-	it("npm * + allow → allow-family", () => {
-		expect(classifyRuleTemplate(makeRule({ pattern: "npm *", action: "allow" }))).toBe("allow-family");
-	});
-
-	it("git * + deny → deny-family（any）", () => {
-		expect(classifyRuleTemplate(makeRule({ pattern: "git *", action: "deny" }))).toBe("deny-family");
-	});
-
-	it("git push * + deny → deny-family（specific）", () => {
-		expect(classifyRuleTemplate(makeRule({ pattern: "git push *", action: "deny" }))).toBe("deny-family");
-	});
-
-	it("docker * + ask → ask-before", () => {
-		expect(classifyRuleTemplate(makeRule({ pattern: "docker *", action: "ask" }))).toBe("ask-before");
-	});
-
-	it("git status * + allow → allow-subcmd", () => {
-		expect(classifyRuleTemplate(makeRule({ pattern: "git status *", action: "allow" }))).toBe("allow-subcmd");
-	});
-
-	it("不匹配已知格式 → custom", () => {
-		expect(classifyRuleTemplate(makeRule({ pattern: "rm -rf /tmp/*", action: "deny" }))).toBe("custom");
-	});
-
-	it("* alone + allow → custom（不匹配 FAMILY_RE，无 cmd 前缀）", () => {
-		expect(classifyRuleTemplate(makeRule({ pattern: "*", action: "allow" }))).toBe("custom");
-	});
-});
-
 // ──────────────────────── applyOps ────────────────────────
 
 describe("RT4: applyOps", () => {

package/src/__tests__/session-start-once-guard.test.ts

@@ -0,0 +1,147 @@
+/**
+ * session-start-once-guard.test.ts — u-audit-fix 探针实测（permission 侧）。
+ *
+ * 排查清单（docs/design/pi-session-start-handler-idempotency-audit.md §2 permission 行）
+ * 判定「必须接入」：migrateLegacyConfig 写 agentDir 全局配置文件，属跨 session 副作用，
+ * 已由 oncePerProcess 守卫收编原内联 once flag。本文件按清单探针验证点双派发实测：
+ *   a) 双派发（同一 factory 闭包直接调 handler 两次）下 spy migrateLegacyConfig 调用 = 1；
+ *   b) 文件面：tmp agentDir 预置旧路径文件 → 第一次 handler 后旧文件消失 + 新路径出现，
+ *      第二次 handler 后新路径 mtime/内容不变（守卫拦截 = 不触碰）；
+ *   c) migrated warn 仅一条：构造性蕴含于 a——warn 在 migrateLegacyConfig 调用点内部
+ *      （llm-shared migrate.ts "migrated" 分支），调用 = 1 ⟹ warn ≤ 1，不另设断言。
+ * 反向断言（豁免项防误伤）：footer 注册为纯内存初始化（registry.register 同 id 覆盖），
+ * 清单明令不包装——双派发仍每次执行（pending push ×2）。
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { FOOTER_HANDSHAKE_KEY } from "../footer-provider.js";
+
+// ── mock：migrateLegacyConfig 包 spy 计数（透传真实实现，文件面断言保留） ──
+
+const { spyMigrateLegacyConfig } = vi.hoisted(() => ({
+	spyMigrateLegacyConfig: vi.fn(),
+}));
+
+vi.mock("@zhushanwen/pi-llm-shared", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("@zhushanwen/pi-llm-shared")>();
+	spyMigrateLegacyConfig.mockImplementation((agentDir: string, oldRel: string, newRel: string) =>
+		actual.migrateLegacyConfig(agentDir, oldRel, newRel));
+	return { ...actual, migrateLegacyConfig: spyMigrateLegacyConfig };
+});
+
+// ── mock pi（对齐 index-integration.test.ts 自包含 helper 形态） ──
+
+function createMockPi(): { pi: Pick<ExtensionAPI, "on" | "registerCommand">; calls: { eventHandlers: Map<string, Array<(event?: unknown, ctx?: unknown) => unknown>> } } {
+	const eventHandlers = new Map<string, Array<(event?: unknown, ctx?: unknown) => unknown>>();
+	const pi = {
+		registerCommand(): void {
+			/* noop */
+		},
+		on(event: string, handler: (event?: unknown, ctx?: unknown) => unknown): void {
+			if (!eventHandlers.has(event)) eventHandlers.set(event, []);
+			eventHandlers.get(event)!.push(handler);
+		},
+	};
+	return { pi: pi as Pick<ExtensionAPI, "on" | "registerCommand">, calls: { eventHandlers } };
+}
+
+function getSessionStartHandler(calls: { eventHandlers: Map<string, Array<(event?: unknown, ctx?: unknown) => unknown>> }): (event: unknown, ctx: unknown) => unknown {
+	const handlers = calls.eventHandlers.get("session_start");
+	if (!handlers || handlers.length === 0) {
+		throw new Error("session_start handler not registered");
+	}
+	return handlers[0]!;
+}
+
+// ── tmp agentDir（getAgentDir 经 PI_CODING_AGENT_DIR 推导，对齐 index-integration.test.ts） ──
+
+const TMP_ROOT = join(tmpdir(), "pi-perm-once-guard-" + process.pid);
+const AGENT_DIR = join(TMP_ROOT, "agent");
+const LEGACY_PATH = join(AGENT_DIR, "permission-config.json");
+const CONFIG_PATH = join(AGENT_DIR, "config", "permission-ext-config.json");
+
+function writeLegacyConfig(mode: string): void {
+	mkdirSync(AGENT_DIR, { recursive: true });
+	writeFileSync(
+		LEGACY_PATH,
+		JSON.stringify({ mode, enabled: true, classifier: { enabled: true }, userRules: [] }, null, 2) + "\n",
+		{ mode: 0o600 },
+	);
+}
+
+/** oncePerProcess 的 Map 是模块级状态：每个用例 resetModules 取新鲜模块实例（对齐迁移接线测试先例）。 */
+async function freshExtension(): Promise<(pi: Pick<ExtensionAPI, "on" | "registerCommand">) => void> {
+	vi.resetModules();
+	const mod = await import("../index.js");
+	return mod.default as (pi: Pick<ExtensionAPI, "on" | "registerCommand">) => void;
+}
+
+beforeEach(() => {
+	Reflect.deleteProperty(globalThis, FOOTER_HANDSHAKE_KEY);
+	process.env.PI_CODING_AGENT_DIR = AGENT_DIR;
+	mkdirSync(AGENT_DIR, { recursive: true });
+});
+
+afterEach(() => {
+	delete process.env.PI_CODING_AGENT_DIR;
+	Reflect.deleteProperty(globalThis, FOOTER_HANDSHAKE_KEY);
+	if (existsSync(TMP_ROOT)) rmSync(TMP_ROOT, { recursive: true, force: true });
+});
+
+describe("session_start 双派发幂等守卫（oncePerProcess，u-audit-fix）", () => {
+	it("双派发下 migrateLegacyConfig 仅执行一次：spy = 1，文件面首次迁移到位、第二次 mtime/内容不变", async () => {
+		// 预置旧路径文件（新路径不存在 → 走 renameSync 迁移分支）
+		writeLegacyConfig("strict");
+
+		const extension = await freshExtension();
+		const { pi, calls } = createMockPi();
+		extension(pi);
+		const handler = getSessionStartHandler(calls);
+
+		// 第一次派发：迁移发生（旧文件消失 + 新路径出现，内容来自旧文件）
+		handler({}, { mode: "json", cwd: "/tmp", ui: {}, signal: undefined });
+		expect(existsSync(LEGACY_PATH)).toBe(false);
+		expect(existsSync(CONFIG_PATH)).toBe(true);
+		expect(JSON.parse(readFileSync(CONFIG_PATH, "utf-8")).mode).toBe("strict");
+		const mtimeAfterFirst = statSync(CONFIG_PATH).mtimeMs;
+		const contentAfterFirst = readFileSync(CONFIG_PATH, "utf-8");
+
+		// 第二次派发（factory 二调/handler 累积形态：同一 handler 引用再调）：
+		// 重建旧路径文件模拟外部残留——守卫已消费 key，不得再次触碰任何文件。
+		writeLegacyConfig("yolo");
+		handler({}, { mode: "json", cwd: "/tmp", ui: {}, signal: undefined });
+
+		// 探针 a：操作级去重（spy 透传真实实现，文件面与计数同源）
+		expect(spyMigrateLegacyConfig).toHaveBeenCalledTimes(1);
+		// 探针 b：第二次后重建的旧文件原样保留、新路径 mtime/内容严格不变
+		expect(existsSync(LEGACY_PATH)).toBe(true);
+		expect(statSync(CONFIG_PATH).mtimeMs).toBe(mtimeAfterFirst);
+		expect(readFileSync(CONFIG_PATH, "utf-8")).toBe(contentAfterFirst);
+	});
+
+	it("豁免项防误伤：footer 注册不包装，双派发仍每次执行（pending push ×2）", async () => {
+		writeLegacyConfig("strict");
+
+		const extension = await freshExtension();
+		const { pi, calls } = createMockPi();
+		extension(pi);
+		const handler = getSessionStartHandler(calls);
+
+		handler({}, { mode: "json", cwd: "/tmp", ui: {}, signal: undefined });
+		handler({}, { mode: "json", cwd: "/tmp", ui: {}, signal: undefined });
+
+		// 纯内存初始化（registry.register 同 id 覆盖 / pending push）保持每 session_start
+		// 执行——清单「粒度边界」明令不包装，挂进程级 flag 会杀 session 级语义。
+		const slot = Reflect.get(globalThis, FOOTER_HANDSHAKE_KEY) as {
+			pending: Array<{ id: string; renderer: unknown }>;
+		} | undefined;
+		expect(slot).toBeDefined();
+		expect(slot!.pending.length).toBe(2);
+		expect(slot!.pending[0]!.id).toBe("pi-permission");
+	});
+});

package/src/approval.ts

@@ -6,12 +6,12 @@
  *    G3：调 ctx.ui.custom 前先检查 signal.aborted 短路（AI 先于 UI factory 执行时
  *    controller.abort() 触发但 comp 尚未创建，cancel 落空）。
  *  - rpc：ctx.ui.select（GUI 对话框）。M2：接收 signal，abort 短路 + 透传给 ui.select。
- *  - headless（json/print）：无交互 UI。M1：返回永不主动 resolve 的 Promise（让 Racing 中的
- *    AI 有机会赢），仅在 signal abort 时 fail-closed deny（避免 headless 下 auto 退化为 strict）。
+ *  - headless（json/print）：无交互 UI，立即 fail-closed deny（requestHeadless）。auto 模式
+ *    Racing 不走此路径（pipeline runLayer3WithRacing 的 isHeadless 分支纯等 AI 判定）。
  *
  * ApprovalComponent 是简化版 TUI 组件（参考 ask-user AskUserComponent）：
  *  - 显示工具名 + 命令 + 触发原因 + 可选 AI 预分类。
- *  - y/approve、n/deny、Esc/cancel。
+ *  - Enter/approve、Esc/deny。
  *  - signal abort → comp.cancel()（复用 _resolved 守卫，避免二次 done）。
  *
  * W6 T9 G3 Reject-with-Reason：用户拒绝时，若 ctx.ui.input 存在则弹出文本输入框
@@ -123,7 +123,8 @@ async function requestRpc(
 ): Promise<UserDecision> {
 	const title = formatTitle(req);
 	// TODO: spec 未要求 session/always scope，当前仅支持 once。
-	// 未来如需扩展，options 加 "Approve (session)" / "Approve (always)"，UserDecision.scope 透传。
+	// 未来如需扩展，options 加 "Approve (session)" / "Approve (always)"，并在 UserDecision
+	// 上新增 scope 字段承载（当前 UserDecision 只有 approved/reason）。
 	const options = ["Approve (once)", "Deny"];
 	// M2：与 requestTui 一致——调 select 前检查 signal.aborted 短路（AI 先于对话框弹出赢 race 时，
 	// controller.abort() 已触发但 select 尚未发起，这里 fail-closed deny 避免弹出无意义对话框）。
@@ -137,7 +138,7 @@ async function requestRpc(
 		return { approved: false, reason: "user dismissed the prompt" };
 	}
 	if (choice.startsWith("Approve")) {
-		return { approved: true, reason: "approved via rpc", scope: "once" };
+		return { approved: true, reason: "approved via rpc" };
 	}
 	// W6 T9 G3：Reject-with-Reason。用户选 Deny 后，若 ctx.ui.input 存在则采集真实理由。
 	// 「受阻」可观测条件：typeof ctx.ui.input === 'function'。
@@ -226,7 +227,7 @@ interface TuiLike {
  * TUI 审批组件（简化版，参考 ask-user AskUserComponent）。
  *
  * 显示：标题 + 工具名 + 命令 + 原因 + 可选 AI 预分类 + 操作提示。
- * 键位：y/Enter → approve；n/Esc → deny/cancel。
+ * 键位：Enter → approve；Esc → deny/cancel（y/n 快捷键已移除，测试钉住 no-op）。
  *
  * G4：implements Component，补 invalidate()（调 tui.requestRender()）。
  * signal abort → cancel()（复用 _resolved 守卫）。
@@ -292,9 +293,10 @@ export class ApprovalComponent implements Component {
 	private approve(): void {
 		if (this._resolved) return;
 		this._resolved = true;
-		// TODO: spec 未要求 session/always scope，当前硬编码 "once"。未来如需扩展，
-		// 增加 handleInput 对应键位（如 's' → session、'a' → always）并透传 UserDecision.scope。
-		this.done({ approved: true, reason: "approved via tui", scope: "once" });
+	// TODO: spec 未要求 session/always scope，当前硬编码 "once"。未来如需扩展，
+	// 增加 handleInput 对应键位（如 's' → session、'a' → always），并在 UserDecision
+	// 上新增 scope 字段承载（当前 UserDecision 只有 approved/reason）。
+		this.done({ approved: true, reason: "approved via tui" });
 	}
 
 	private deny(): void {

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

@@ -60,7 +60,7 @@ function okResult(content: string): CallLLMResult {
 }
 
 function failResult(error: string, stopReason?: "error" | "aborted"): CallLLMResult {
-	return { ok: false, error, recoverable: true, ...(stopReason !== undefined ? { stopReason } : {}) };
+	return { ok: false, error, ...(stopReason !== undefined ? { stopReason } : {}) };
 }
 
 /** 构造「永不 resolve」的 mock callLLM（用于 timeout/abort 测试） */