dsh-rule-engine 0.5.8 → 0.5.10

package/README.md

@@ -1,7 +1,7 @@
 # dsh-rule-engine
 
 ![npm](https://img.shields.io/npm/v/dsh-rule-engine)
-![version](https://img.shields.io/badge/version-0.5.8-blue)
+![version](https://img.shields.io/badge/version-0.5.10-blue)
 
 DSH 规则执行引擎 v3 的插件实现。它把 `~/.dsh/AGENTS.md` 当作唯一真相源，自动解析规则四要素与执行等级，再通过「工具守卫 + 文本检测 + 时序检查 + 审计台账」执行用户规则，而不是内置一套与用户无关的安全清单。
 
@@ -42,10 +42,36 @@ DSH 规则执行引擎 v3 的插件实现。它把 `~/.dsh/AGENTS.md` 当作唯
 ## 质量与验证（2026-08-26，对齐官方 docs/testing.zh.md）
 
 - `npm run test`（全量单测；`test/run-all.mjs` 统一入口，注意 ESM 缓存顺序约定）；
-- `node scripts/verify-all.mjs` —— 交付前四层体检：语法（lib 全文件 `node --check`）→ 单元（run-all）→ **组合冒烟**（`test/loader-smoke.e2e.mjs`：真实引擎代码 + 真实审计文件，仅 mock LLM 边界，断言**外部世界**——审计文件里真的出现 judge-false/judge-pass 记录，而非自我报告）→ **真实判例**（近 24h 台账 judge-pass/false 记录数，0 条 = WARN 提示需实弹）；
+- `node scripts/verify-all.mjs` —— 交付前**五层**体检：语法（lib 全文件 `node --check`）→ 单元（run-all）→ **组合冒烟**（`test/loader-smoke.e2e.mjs`：真实引擎代码 + 真实审计文件，仅 mock LLM 边界，断言**外部世界**——审计文件里真的出现 judge-false/judge-pass 记录，而非自我报告）→ **工具箱覆盖**（`scripts/check-tool-coverage.mjs`：官方 tool-catalog 全集 vs 分类表，出现 unknown 即红）→ **真实判例**（近 24h 台账 judge-pass/false 记录数，0 条 = WARN 提示需实弹）；
 - `node scripts/health-audit.mjs` —— 找茬清单：近 24h 失败/降级类统计（intent-llm 失败、judge-unavailable、verify-gap、inject-skip…）+ 关键导出接线交叉（疑似未接线 = 告警）——"失败可见化"，不再有静默躺 20 小时的降级；
 - 执行协议（本仓库自身交付纪律）：方案冻结单（范围/影响面/测试计划/失败预测）→ todo 化 → 小步闭环（每改动立即 `node --check`）→ 对账交付（计划×实际逐项 ✅/❌/跳过原因）。
 
+## 0.5.10（2026-08-27 追加）
+
+> 收编：用户审查后的 real-legal 会话建议（建议 2/3/4/5，依据本手册知识条目 K-01~K-06 批判性审查）+ 分析通道（用户多次提出的"只读分析需要写临时脚本/输出"痛点）+ 统一入口加固（2026-08-27 手册损伤事故复盘）。
+
+- **分析通道（单真源 `isAnalysisOp`）**：严格只读 ∪ 分析脚本区（repo `scripts/*.mjs`）∪ 分析临时区写（`logs/` `.analysis-tmp/` `.backups/`）→ 任何回合放行 + 审计 `analysis-scratch`；**红线**（红线层在 guard-core）：受保护文件名/工作区外（isOutsideWorkspace）/删除移动/覆盖正式文件一律不豁免；
+- **写类判定单真源**：self-protect / 22 / 13A 统一走 `isMutationCommand`——修复 `Write-Output` 被 `write` 子串误杀（WGO654/ES3VCD 案例：纯读命令查受保护文件名被误拦）；
+- **只读词表补全**：ForEach-Object / Get-ItemProperty / Get-Variable / Get-FileHash（多行"读+筛选+循环"组合判只读）；
+- **统一入口加固**（dsh-manual-write.mjs）：① 转义事故特征检测——表格行内字面 `\n` / `\$`（PowerShell 单引号转义事故模式，2026-08-27 手册坏行事故）→ 拒绝；② 写后结构校验——表格块列宽一致（±2 容忍）+ 手册版本记录行存在，不通过自动回滚；
+- **误判打标闭环（建议 4）**：所有硬拦文案尾部附「误判可打标：/guard label <事件号> incorrect」指引；health-audit 新增 deny 总数 vs incorrect/correct 打标占比统计（词表迭代量化依据）；
+- **已知坑召回（建议 5）**：工具错误文本命中特征表（SEC_E_NO_CREDENTIALS / ECONNREFUSED:7890 / EPERM 管道 / ERR_MODULE_NOT_FOUND）→ 审计 `error-hint` + 注入指向知识库提示（本轮去重、走投递资格链，不违反注入噪音治理）；
+- **质保**：新增强力测试（写类判定/分析通道/临时区红线/转义检测 REFUSED 实测/召回特征）+ verify-all 五层全绿 + 工具箱覆盖门禁回归。
+
+## 0.5.9（2026-08-27 追加）
+
+> 修复方向（用户"整体审查"要求，依据手册知识条目 K-01~K-06）：静态工具清单漏分类官方工具
+> （`run_code` 事故——code 模式会话一切被拦）→ 单一真源 + 前缀规则 + 覆盖门禁 + 白名单可视化。
+
+- **工具分类单真源**：规则 24④ 守卫与 unknown 处置统一读 `lib/core/tool-catalog.js` 唯一分类表（废弃双表——run_code 正是双表都漏的受害者）；
+- **官方工具全集补全**：59 个官方 tool-catalog 工具名全覆盖（`cordis_*`/`terminal_*`/`session_*`/goal/jobs/子代理/团队/plan-mode/官方保留传输 `run_code` 等）——Code Mode 会话（模型只能直呼 `run_code`）不再被"未知工具"拦死；
+- **前缀规则**：`mcp__`（变更类走授权，照 Claude Code `mcp__*` 范式）、`esr_`/`dev_` 等生态命名空间自动归类——**将来新增插件工具遵循惯例即被覆盖**（不再依赖静态枚举）；
+- **unknown 首调处置 `unknownPolicy`**：默认 `deny`（保守：`ask` 弹窗模式需真实场景实弹验证后才可作默认；配置 `"ask"` 可切换官方弹窗——approval 弹窗 allowed-once，无审批通道自动拒绝，官方 fail-closed 语义）；
+- **白名单 v2 带元数据**：`~/.dsh/rule-engine-tools.json` 升级为 `[{name,time,session}]`（**谁、何时、在哪个会话被放行**——可视化基础）；旧 `["name"]` 格式兼容加载；历史条目显示"时间/来源未知"；
+- **`/guard tools` 命令**：查看白名单（永久 + 本会话新增，含时间/来源会话）+ `/guard tools revoke <工具名>` 撤销（持久化+会话集同步）；
+- **工具箱覆盖门禁**：`scripts/check-tool-coverage.mjs`（官方 tool-catalog vs 分类表，任一 unknown 即红——`run_code` 事故同类的机器防线）已挂入 `verify-all` 第五层；
+- **测试**：全量单测（新增 whitelist 格式 5 用例）+ loader-smoke 新增 E 场景（白名单 v2 真实落盘断言：对象数组/时间/来源会话/审计留痕）+ verify-all **五层**全绿。
+
 ## 0.5.8（2026-08-26 追加）
 
 - **白名单持久化**："允许使用 X"（未归类工具批准）落盘 `~/.dsh/rule-engine-tools.json`——此前为内存态，热重载/重启即清（用户需反复重发，实测 esr_task/esr_close 各被清一次）；
@@ -77,6 +103,8 @@ DSH 规则执行引擎 v3 的插件实现。它把 `~/.dsh/AGENTS.md` 当作唯
 | `/guard budget ...` | 设置预算（agents=N files=... deps=allow hash=allow） |
 | `/guard contract` | 查看当前任务契约 |
 | `/guard label <id> <label>` | 给审计记录打标（correct/incorrect/inconclusive） |
+| `/guard tools` | 查看工具放行白名单（永久+本会话，含时间/来源会话） |
+| `/guard tools revoke <名>` | 撤销白名单条目（持久化+会话集同步移除） |
 
 ## 装配方式
 

package/lib/core/guard-core.js

@@ -16,12 +16,17 @@ import {
   isBackupTool,
   isHighRiskEntryFile,
   isManualReadTool,
+  isMutationCommand,
+  isOutsideWorkspace,
   isProtectedConfigPath,
   isReadOnlyTool,
   isSensitiveToolCall,
   isVariablePath,
   isVerificationCommand,
   isLowRiskWorkspaceNew,
+  isAnalysisOp,
+  isAnalysisScratchPath,
+  extractAnalysisScratchPaths,
   pathTarget
 } from "./patterns.js";
 import { authMatches, describeAuth, describeOp, describeScopes, findMatchingAuth, operationOf, askQuestionText, inferPathPrefixFromText, inferTypeFromText, scopesFromIntents } from "./authorization.js";
@@ -61,20 +66,13 @@ function makeHit(cfg, reason) {
     ruleId: cfg.ruleId,
     title: cfg.title,
     action: "deny",
-    reason: `${reason}（规则 ${cfg.ruleId}｜放行：${hint}｜ERR-${errId}）`
+    reason: `${reason}（规则 ${cfg.ruleId}｜放行：${hint}｜ERR-${errId}｜误判可打标：/guard log 找该 ERR 码 → /guard label <事件号> incorrect）`
   };
 }
 
-export const COVERED_MUTATION_TOOLS = new Set([
-  "edit", "write", "str_replace_editor", "pwsh", "bash",
-  "dev_stage_add", "dev_stage_call", "dev_stage_promote", "dev_stage_demote"
-]);
-export const SAFE_UNCOVERED_TOOLS = new Set([
-  "ask_user_question", "todo_write", "subagent", "workflow", "visualize", "skill",
-  "read", "grep", "glob", "read_image", "job_list", "job_output", "list_agents",
-  "get_goal", "dev_plugin_status", "dev_reload_package", "dev_injected_list",
-  "dev_stage_list", "dev_router_status", "dev_self_test"
-]);
+// 0.5.9（单真源）：COVERED_MUTATION_TOOLS / SAFE_UNCOVERED_TOOLS 独立覆盖表已废弃——
+// 工具分类以 lib/core/tool-catalog.js 的唯一分类表为准（24④/22/unknown 全部读它），
+// 双表漂移即 run_code 事故根因（K-01/K-02/K-06 依据）。
 
 function looksLikeFileMutation(name, args) {
   const a = args || {};
@@ -249,9 +247,10 @@ export function guardDecision(state, exec, now = Date.now(), opts = {}) {
 
   // 阶段 C：硬拦 pwsh/bash 绕过统一入口直接写受保护文件（规则 19⑧/21⑨ 的机器执行层）
   // 合法通道 = 整条命令仅调用 dsh-manual-write.mjs（无 ; | & 链式/换行，防注释文本伪造放行）
+  // 0.5.10：写类判定改 isMutationCommand（单真源）——修复 `Write-Output` 被 `write` 子串误杀（WGO654/ES3VCD 同类）
   if (!unlock && (name === "pwsh" || name === "bash")) {
     const cmd = commandText(args) || "";
-    if (cmd && /(?:set-content|out-file|add-content|write|copy-item|move-item|rename-item|writefilesync|fs\.writefilesync)/i.test(cmd) && PROTECTED_FILENAME_RE.test(cmd)) {
+    if (cmd && isMutationCommand(cmd) && PROTECTED_FILENAME_RE.test(cmd)) {
       if (!isEntryChannelCommand(cmd)) {
         return makeHit(
           { ruleId: "__self-protect", title: "受保护文件禁止绕过统一入口直写", action: "deny" },
@@ -328,10 +327,20 @@ function matchRule(cfg, ctx) {
   //（"你的执行方案难道没问题吗？"虽含"执行"仍是疑问句——同形词不构成指令，不豁免）
   if (cfg.handler === "rule22-7-direct") {
     // 机制 B（2026-08-24）：工具分类制（纯函数，覆盖现有与未来插件注册的全部工具）——
-    // control（SAFE 无条件放行）/ analysis（只读分析放行）/ artifact（产物放行+审计）/
-    // unknown（物理不拦，由 pre-execute ask 层首调询问，防新插件绕过）；mutating 维持原有严格逻辑。
-    if (SAFE_UNCOVERED_TOOLS.has(name)) return null; // 授权/委托/技能/查询展示类 → 无条件放行
+    // analysis（只读分析放行）/ artifact（产物放行+审计）/ unknown（物理不拦，由 pre-execute
+    // ask/deny 层首调处置，防新插件绕过）；mutating 维持原有严格逻辑。0.5.9 单真源：唯一分类表。
     const cls = toolClass(name, args);
+    // 0.5.10 分析通道（用户多次提出：只读分析需要写临时脚本/输出——解压副本/聚合日志等）：
+    // 严格只读 ∪ 分析临时区写 ∪ 分析脚本区调用 → 任何回合放行 + 审计留痕。
+    // 红线：工作区外路径命中临时区段（如 C:\xxx\logs\）不豁免——落入常规变更判定。
+    if (isAnalysisOp(name, args)) {
+      const scratch = extractAnalysisScratchPaths(commandText(args) || "");
+      const outside = scratch.filter((p) => isOutsideWorkspace(p, sessionIdOf(exec)));
+      if (outside.length === 0) {
+        audit?.({ kind: "analysis-scratch", rule: cfg.ruleId, name: "分析通道放行", tool: name, reason: `分析类操作（只读/临时区/分析脚本区）放行：${describeOp(operationOf(name, args))}`, session: sessionIdOf(exec) });
+        return null;
+      }
+    }
     if (cls === "analysis") return null;
     if (cls === "artifact") {
       audit?.({ kind: "allow", rule: cfg.ruleId, name: "产物类工具放行", tool: name, reason: `分类 artifact（低风险产物写入，留痕可对账）：${describeOp(operationOf(name, args))}`, session: sessionIdOf(exec) });
@@ -359,7 +368,7 @@ function matchRule(cfg, ctx) {
     // 无用户消息/状态信号/ask 答复后回合仍不做规则 22 判定（由 12A/13A 把关）。
     if (!turnIntents || !turnIntents.hasExecute) return null;
     if (isReadOnlyTool(name, args)) return null;
-    if (!COVERED_MUTATION_TOOLS.has(name) && !looksLikeFileMutation(name, args)) return null;
+    if (cls === "mutating" || looksLikeFileMutation(name, args)) {} else return null;
     const op = operationOf(name, args);
     // v0.5.7 P0-1（用户拍板 2026-08-26）：验证类命令伴生放行——本回合已有 write/any/command
     // 授权（用户已批"修改/执行"）时，运行测试/冷加载/审计/语法检查属于该变更的验证闭环，
@@ -557,10 +566,11 @@ function matchRule(cfg, ctx) {
       return makeHit(cfg, `【硬拦截】${p} 的 dsh.profile.bundles 包含非 bundle/无法确认类型：${badBundles.join("；")}（规则 24）`);
     }
     // 规则 24④：所有能产生文件写入/删除/移动效果的工具都必须纳入统一守卫——
-    // 未覆盖的变更类工具运行时直接拒绝（防"改个新工具就绕过守卫"）
+    // 0.5.9 单真源：已分类（tool-catalog 唯一表）= 已纳入守卫，放行；未分类且疑似变更 = 运行时拒绝
+    // （防"改个新工具就绕过守卫"；与工具覆盖门禁 K-01/K-06 互补）
     if (isReadOnlyTool(name, args)) return null;
-    if (COVERED_MUTATION_TOOLS.has(name)) return null;
-    if (SAFE_UNCOVERED_TOOLS.has(name)) return null;
+    const cls24 = toolClass(name, args);
+    if (cls24 !== "unknown") return null;
     if (looksLikeFileMutation(name, args)) {
       return makeHit(cfg, `【硬拦截】未覆盖的变更类工具 ${name}，违反规则 24④：请先纳入统一守卫覆盖`);
     }

package/lib/core/patterns.js

@@ -237,10 +237,15 @@ export function isGetDateCommand(command) {
 
 const READ_ONLY_TOOLS = new Set(["read", "grep", "glob", "read_image"]);
 const READONLY_CMD_RE =
-  /(?:\b(?:Get-Content|Get-ChildItem|Get-Item|Get-Command|Get-Date|Select-String|Find-String|Test-Path|Get-Process|Get-Service|cat|type|dir|ls|grep|findstr|more|netstat|where|echo|Write-Output|Write-Host|Get-Location|pwd|cwd|Get-Help|help|Select-Object|Out-String|Format-Table|Format-List|Format-Wide|Measure-Object|Sort-Object|Where-Object|Group-Object|Out-Null|ConvertTo-Json|ConvertFrom-Json)\b)|(?:\bgit\s+(?:-[^\s]+\s+[^\s]+\s+|--[^\s]+\s+)*\b(?:status|log|diff|show|branch|tag|remote|rev-parse|diff-tree|ls-files)(?:\s|$))|(?:\bdsh\s+(?:--version|--help|--dump-config|plugin\s+(?:list|show|status))(?:\s|$))|(?:\bdsh\s+--profile\s+[^\s]+\s+(?:--dump-config|plugin\s+(?:list|show|status))(?:\s|$))|(?:\bnode\s+(?:--check|--test|--version)(?:\s|$))|(?:\bnpm\s+(?:test|run\s+test)(?:\s|$))|(?:\bpnpm\s+(?:test|run\s+test)(?:\s|$))|(?:\bgh\s+(?:auth\s+status|repo\s+view)(?:\s|$))|(?:\bnpm\s+(?:ls|view)(?:\s|$))/i;
+  /(?:\b(?:Get-Content|Get-ChildItem|Get-Item|Get-Command|Get-Date|Select-String|Find-String|Test-Path|Get-Process|Get-Service|Get-ItemProperty|Get-Variable|Get-FileHash|cat|type|dir|ls|grep|findstr|more|netstat|where|echo|Write-Output|Write-Host|Get-Location|pwd|cwd|Get-Help|help|Select-Object|Out-String|Format-Table|Format-List|Format-Wide|Measure-Object|Sort-Object|Where-Object|Group-Object|ForEach-Object|Out-Null|ConvertTo-Json|ConvertFrom-Json)\b)|(?:\bgit\s+(?:-[^\s]+\s+[^\s]+\s+|--[^\s]+\s+)*\b(?:status|log|diff|show|branch|tag|remote|rev-parse|diff-tree|ls-files)(?:\s|$))|(?:\bdsh\s+(?:--version|--help|--dump-config|plugin\s+(?:list|show|status))(?:\s|$))|(?:\bdsh\s+--profile\s+[^\s]+\s+(?:--dump-config|plugin\s+(?:list|show|status))(?:\s|$))|(?:\bnode\s+(?:--check|--test|--version)(?:\s|$))|(?:\bnpm\s+(?:test|run\s+test)(?:\s|$))|(?:\bpnpm\s+(?:test|run\s+test)(?:\s|$))|(?:\bgh\s+(?:auth\s+status|repo\s+view)(?:\s|$))|(?:\bnpm\s+(?:ls|view)(?:\s|$))/i;
 const MUTATING_CMD_RE =
   /(?:Set-Content|Add-Content|Out-File|Remove-Item|Move-Item|Copy-Item|Rename-Item|New-Item|Clear-Content|git\s+(?:push|commit)|rm\s+-r|rmdir\s+\/s|del\s+\/s|(?:^|[^0-9])>>|(?:^|[^0-9])>)/i;
 
+/** 写/删除/提交类命令判定（0.5.10 单真源：guard-core self-protect 等全部复用——修复 Write-Output 被 `write` 子串误杀） */
+export function isMutationCommand(command) {
+  return typeof command === "string" && MUTATING_CMD_RE.test(command);
+}
+
 /** 只读命令链按分隔符折段（机制 B，2026-08-24）：`; 换行 && || |`（管道前后是命令链；`2>&1`/`2>$null` 的 stderr 重定向不拆分） */
 function splitCommandSegments(command) {
   return String(command)
@@ -273,6 +278,74 @@ export function isReadOnlyTool(toolName, args) {
   return false;
 }
 
+// ═══════════ 0.5.10 分析通道（用户多次提出"只读分析需要写临时脚本/输出"）═══════════
+// 两类区：① 分析脚本区（scripts/analysis/*.mjs，仓库内可审查）② 分析临时区（logs/ .analysis-tmp/ .backups/，
+// 输出/解压副本/分析脚本产物——不纳入 git 跟踪、不属正式变更）。红线由 guard-core 追加（工作区外/受保护名/覆盖既有）。
+const ANALYSIS_SCRATCH_SEG_RE = /(?:^|[\\/])(?:logs|\.analysis-tmp|\.backups)[\\/]/i;
+// 分析脚本区：仓库内 scripts/ 任意 .mjs（可审查工具库——unzstd/聚合日志/诊断脚本）+ scripts/analysis/ 专用
+const ANALYSIS_SCRIPT_RE = /node\s+[^&;|]*[\\/]scripts[\\/][^\s&;|"]+\.mjs/i;
+
+/** 是否分析临时区路径（logs/.analysis-tmp/.backups 段；工作区外红线由 guard-core 用 isOutsideWorkspace 把关） */
+export function isAnalysisScratchPath(p) {
+  if (typeof p !== "string" || !p) return false;
+  return ANALYSIS_SCRATCH_SEG_RE.test(p.replace(/\\/g, "/"));
+}
+
+/** 提取命令文本中命中分析临时区的路径 token（保守：仅取带临时区特征的片段） */
+export function extractAnalysisScratchPaths(command) {
+  const n = String(command || "");
+  const out = [];
+  const re = /(?:logs|\.analysis-tmp|\.backups)[\\/][^\s"'&|;]+/gi;
+  let m;
+  while ((m = re.exec(n))) out.push(m[0].replace(/\\/g, "/"));
+  return out;
+}
+
+/**
+ * 分析类操作判定（0.5.10 单真源）：true = 可按 analysis 放行（无副作用，或副作用仅限分析临时区）。
+ * 场景：① 严格只读（isReadOnlyTool）；② 分析脚本区调用（node scripts/analysis/*.mjs）；
+ *      ③ 临时区写（命令含写特征且提取到的目标路径全部命中分析临时区，且无受保护文件名）。
+ * 红线（guard-core 追加，本函数不含）：工作区外路径（isOutsideWorkspace）、受保护名、覆盖既有正式文件。
+ */
+export function isAnalysisOp(toolName, args) {
+  const name = String(toolName || "");
+  if (isReadOnlyTool(name, args)) return true;
+  const cmd = commandText(args) || "";
+  if (name === "node" || name === "pwsh" || name === "bash") {
+    // ② 分析脚本区调用（脚本自身可写临时区/读全局；命令无其他副作用特征即可）
+    if (ANALYSIS_SCRIPT_RE.test(cmd)) {
+      const paths = extractAnalysisScratchPaths(cmd);
+      if (paths.every((p) => isAnalysisScratchPath(p)) && !PROTECTED_FILENAME_RE.test(cmd)) return true;
+    }
+    // ③ 临时区写：写命令（不含删除/移动——删除/移动属 13A 红线，不走分析豁免）+ 提取路径全部命中临时区 + 无受保护名
+    if (isMutationCommand(cmd) && !/(?:Remove-Item|Move-Item|Rename-Item|del\s|rm\s|git\s+push|git\s+commit)/i.test(cmd)) {
+      const paths = extractAnalysisScratchPaths(cmd);
+      if (paths.length > 0 && paths.every((p) => isAnalysisScratchPath(p)) && !PROTECTED_FILENAME_RE.test(cmd)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// ═══════════ 0.5.10 已知环境坑特征表（建议5——错误码自动召回，K-01/K-05 依据）═══════════
+// 工具/命令错误文本命中特征 → 审计 error-hint + 注入指向知识库的提示（低频：仅命中才提示；语义=指路不打扰）。
+const KNOWN_PITFALLS = [
+  { key: "SEC_E_NO_CREDENTIALS", re: /SEC_E_NO_CREDENTIALS/i, hint: "TLS 凭据失败（常见于沙箱/受限会话）——先查手册踩坑 60/89；Node fetch 配 NODE_USE_ENV_PROXY 可绕" },
+  { key: "proxy-7890-refused", re: /ECONNREFUSED[^\n]*7890/i, hint: "代理端口 7890 无监听——确认代理软件已启动；git/gh 可直连，npm registry 直连本机不可用（发布脚本默认直连，DSH_RELEASE_PROXY 可指定）" },
+  { key: "sandbox-pipe-EPERM", re: /EPERM/i, hint: "受限沙箱下子进程管道受限（踩坑 22⑤）——需 danger-full-access 运行" },
+  { key: "ERR_MODULE_NOT_FOUND", re: /ERR_MODULE_NOT_FOUND/i, hint: "模块缺失——检查依赖闭包/空壳目录（踩坑 54）" }
+];
+
+/** 已知坑特征匹配（纯函数）：错误文本命中特征表 → 返回条目；未命中 → null */
+export function matchKnownPitfall(text) {
+  const t = String(text || "");
+  for (const p of KNOWN_PITFALLS) if (p.re.test(t)) return p;
+  return null;
+}
+
+export { KNOWN_PITFALLS };
+
 /**
  * node -e 内联代码的危险特征判定（机制批 M4：diag-run 受控诊断工具使用）。
  * 黑名单命中任一 = 判定有写/网络/进程副作用（保守：宁可拒）。规则 9 正文不动（A2=B 方案）。

package/lib/core/state.js

@@ -54,7 +54,9 @@ export function createState() {
     llmIntentLast: null, // { text, verdict, at }（最近一次 LLM 采用/失败，/guard status 观测）
     verifyPass: [], // { at, sessionId, what }（测试通过/冷加载探针输出采集，交付闸门 M3 用）
     deniedKeys: new Set(), // 引擎 deny 的调用 key（规则 1 计数解耦）
-    unknownToolApproved: new Set() // 机制 B：已 ask 过的未归类工具（本会话内批准后不再重复询问）
+    unknownToolApproved: new Set(), // 机制 B：已 ask 过的未归类工具（本会话内批准后不再重复询问）
+    unknownToolApprovedMeta: new Map(), // v0.5.9：name → {name,time,session}（持久化元数据，/guard tools 可视化）
+    unknownToolSessionAdded: new Set() // v0.5.9：本会话新增的批准（与永久加载区分，/guard tools 展示）
   };
 }
 

package/lib/core/tool-catalog.js

@@ -1,15 +1,14 @@
-// tool-catalog.js - 工具分类制（机制 B，2026-08-24）
+// tool-catalog.js - 工具分类制（机制 B，2026-08-24；0.5.9 升级 2026-08-27）
 // 任何插件（现有/未来）注册的工具都按此分类：
 //   analysis  = 只读分析（无条件放行）
-//   artifact  = 写产物（低风险：放行 + 审计留痕；受保护路径仍由 13A/__self-protect 把关）
+//   artifact  = 写产物/会话态（低风险：放行 + 审计留痕；受保护路径仍由 13A/__self-protect 把关）
 //   mutating  = 变更类（维持现有严格授权：规则 22 粒度 / 12A / 13A）
-//   unknown   = 未归类（guard 不物理拦；由 index.js 的 pre-execute deny 层首调拦截，
-//                批次 3：ask 被 approval 层自动放行 → 改 deny，用户"允许使用 X"白名放行）
-// 设计原则：
-//   1. 不依赖 ctx.tools 运行时 API（纯静态表 + 命令文本分析，可独立测试）；
-//   2. 方向性修正：旧逻辑"按参数名猜写不写、猜不出就放行"（反向漏洞）→
-//      "未知默认 ask"（fail-closed，用户 2026-08-24 确认）；
-//   3. 分类表随实测/新插件逐步扩充（机制允许快速扩展，无需改逻辑）。
+//   unknown   = 未归类（由 index.js 的 pre-execute 层处置：unknownPolicy=ask（官方弹窗）或 deny + 提示）
+// 0.5.9 改动（用户"整体审查"要求，K-01~K-06 依据）：
+//   1. 补全官方全集（tool-catalog 镜像交叉：cordis_*/terminal_*/session_*/goal/jobs/子代理/团队/保留工具等）；
+//   2. 前缀规则（mcp__=mutating；esr_ 细化）——生态命名空间新工具自动覆盖，不再依赖静态枚举；
+//   3. 单一真源：24④ 守卫与 unknown 决策均读本表（废弃 guard-core 的独立覆盖表，杜绝双表漂移）；
+// 设计原则：工具名不是安全边界，内容才是（K-04）——归类只决定"识别"，内容审查（12C/13A）不因归类豁免。
 import { isReadOnlyTool } from "./patterns.js";
 
 // 只读分析类：无任何文件副作用（或仅有会话内状态），无条件放行
@@ -26,7 +25,15 @@ const ANALYSIS_TOOLS = new Set([
   "web_fetch", "web_search",
   // 子代理交付工具（官方 dsh-tool-subagent-report，2026-08-24 实测发现）：仅子代理环境注册，
   // 参数仅 output 文本 → 直接交付父代理，无文件副作用 → analysis（避免子代理交付被 unknown deny 阻断）
-  "report"
+  "report",
+  // 官方 0.5.9 补全（tool-catalog 镜像 2026-08-27 交叉）
+  "lsp",
+  "session_event_read", "session_event_search", "session_event_trace", "session_search", "session_trace",
+  "terminal_list", "terminal_read",
+  "cordis_inspect_list", "cordis_inspect_query", "cordis_inspect_self",
+  "ask_user_question",
+  // ESR 状态查询（读工作区记忆状态，无持久副作用）
+  "esr_status", "esr_ready", "esr_model"
 ]);
 
 // 产物类：工具自然行为会写文件（artifact/工作区/会话存储），低风险——放行 + 审计。
@@ -35,24 +42,56 @@ const ARTIFACT_TOOLS = new Set([
   // 视觉产物类（裁剪/截图/长图 OCR/矢量化/抠图/物化/展示 → 写 artifact）
   "vision_crop", "vision_pixel_diff", "vision_trace", "vision_extract_foreground",
   "vision_html_screenshot", "vision_long_screenshot_ocr", "vision_materialize", "vision_present",
-  // 记忆/日程（写引擎存储，低风险）
+  // 记忆/日程/目标/技能（写引擎/会话存储，低风险）
   "engram_store", "schedule_create", "schedule_delete",
+  "create_goal", "update_goal",
+  "skill", "todo_write", "visualize",
+  // 子代理/工作流协调（会话/子会话态，无文件副作用；内容审查另有其责）
+  "subagent", "subagent_fork", "send_message", "interrupt_agent", "workflow", "ralph",
+  // 官方 plan-mode 交互工具（参数为 markdown 计划，批准/继续规划，无文件副作用）
+  "exit_plan_mode",
   // 开发侧 staging（写 staging 区，dev_* 工具的自然行为）
-  "dev_stage_add", "dev_stage_call", "dev_stage_promote", "dev_stage_demote"
+  "dev_stage_add", "dev_stage_call", "dev_stage_promote", "dev_stage_demote",
+  // ESR 工程状态写操作（写工作区记忆存储，engram_store 同族）
+  "esr_task", "esr_node", "esr_link", "esr_claim", "esr_close", "esr_unclaim", "esr_dep", "esr_gc"
 ]);
 
 // 变更类：维持现有严格授权（规则 22 粒度比对 / 12A 敏感授权 / 13A 备份）
 const MUTATING_TOOLS = new Set([
-  "edit", "write", "str_replace_editor", "pwsh", "bash",
+  "edit", "write", "str_replace_editor", "pwsh", "bash", "upload_file",
   // 插件装配类（规则 24/27 管辖）
   "dev_install_package", "dev_inject_plugin", "dev_uninject_plugin", "dev_reload_package",
   "dev_fix_patch", "dev_heal_links",
-  // 提交/网络写类由命令文本与 12C 管辖，此处不重复枚举
-  "upload_file"
+  "dev_scaffold_plugin", "dev_build_plugin", "dev_release_plugin", "dev_clear_routes",
+  // 官方 0.5.9 补全（tool-catalog 镜像 2026-08-27 交叉）
+  "run_code",              // 官方保留传输（Code Mode 唯一入口，语义"不可限制"——归类=纳入统一守卫而非拦死）
+  "cordis_define", "cordis_run", "cordis_stop", "cordis_undefine",
+  "terminal_open", "terminal_send", "terminal_close", "terminal_signal",
+  "job_kill",
+  "followup_task", "spawn_teammate", "team_task_create", "team_task_get",
+  "team_task_list", "team_task_update", "wait_agent",
+  // 本机命名空间兜底（dev_ 前缀 = 开发侧工具，行为可写可管理；具体已枚举，前缀兜底未来新增）
+  "dev_router_status"
 ]);
 
+// 前缀规则：生态命名空间的工具自动归类（0.5.9 新）——将来的新插件遵循惯例即被覆盖。
+// 安全注记（K-03）：mcp__ 服务器段不做通配（Claude Code 同款约束）；mcp 工具按变更类走授权（保守）。
+const PREFIX_RULES = [
+  { prefix: "mcp__", cls: "mutating" },
+  { prefix: "esr_", cls: "artifact" },
+  { prefix: "vision_", cls: "analysis" },
+  { prefix: "engram_", cls: "artifact" },
+  { prefix: "dev_", cls: "mutating" },
+  { prefix: "schedule_", cls: "artifact" },
+  { prefix: "job_", cls: "analysis" },
+  { prefix: "terminal_", cls: "mutating" },
+  { prefix: "cordis_", cls: "mutating" },
+  { prefix: "session_", cls: "analysis" },
+  { prefix: "team_", cls: "mutating" }
+];
+
 /**
- * 工具分类判定（纯函数）。
+ * 工具分类判定（纯函数）。0.5.9 单一真源：24④ 守卫与 unknown 处置均读此结果。
  * @param {string} name 工具名
  * @param {object} args 工具参数（pwsh/bash 需要命令文本判读写）
  * @returns {'analysis'|'artifact'|'mutating'|'unknown'}
@@ -65,14 +104,19 @@ export function toolClass(name, args = {}) {
   if (ANALYSIS_TOOLS.has(n)) return "analysis";
   if (ARTIFACT_TOOLS.has(n)) return "artifact";
   if (MUTATING_TOOLS.has(n)) return "mutating";
+  // 前缀规则（细粒度集合优先；esr_ 状态查询放宽为 analysis）
+  if (n.startsWith("esr_") && ["esr_status", "esr_ready", "esr_model"].includes(n)) return "analysis";
+  for (const rule of PREFIX_RULES) {
+    if (n.startsWith(rule.prefix)) return rule.cls;
+  }
   return "unknown";
 }
 
 /**
  * unknown 工具的处置决策（pre-execute 层调用）。
- * 批次 3（2026-08-24，用户拍板分支 A）：ask → deny——实测 DSH approval 层自动放行 ask
- *（guardian ask 与 unknown 首调均无弹窗直接执行 = fail-open 洞），未知工具首调必须物理拦截；
- * 批准路径 = 用户明确"允许使用 X"（handleSessionEvent 写入会话白名）；白名后本会话放行。
+ * 0.5.9 修订（K-02/K-03 依据）：unknown 首调从物理 deny 改为由 index.js 按 unknownPolicy 走
+ * 官方 ask（弹窗，allowed-once）或 deny；本函数保留"未分类且未白名 → deny（需要处置）"的
+ * 对外契约（调用方翻译策略），已知分类或已白名 → null（放行）。
  * @param {string} name 工具名
  * @param {object} args 工具参数
  * @param {Set<string>|null} whitelist 会话内已批准工具集（可选）

package/lib/core/whitelist.js

@@ -0,0 +1,34 @@
+// whitelist.js - 工具白名单持久化 v2（0.5.9）：纯函数，可独立测试。
+// 存储格式：v2 = [{"name","time","session"}]（带元数据，可视化"谁/何时/哪个会话放行"）；
+// v1 = ["name"]（字符串数组，兼容读取）。v1 升级=v2 时旧条目 time/session 为 null（"未知"）。
+export function parseWhitelist(raw) {
+  try {
+    const arr = JSON.parse(raw || "[]");
+    if (!Array.isArray(arr)) return [];
+    return arr
+      .map((it) => {
+        if (typeof it === "string") return { name: it, time: null, session: null };
+        if (it && typeof it.name === "string") {
+          return {
+            name: it.name,
+            time: typeof it.time === "number" ? it.time : null,
+            session: typeof it.session === "string" ? it.session : null
+          };
+        }
+        return null;
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/** 合并既有元数据与新增名称（新增带当前时间和会话来源），保持既有条目历史不变 */
+export function mergeWhitelist(prevRows, names, sid, now = Date.now()) {
+  const map = new Map(prevRows.map((r) => [r.name, r]));
+  return names.map((n) => map.get(n) || { name: n, time: now, session: sid || null });
+}
+
+export function serializeWhitelist(rows) {
+  return JSON.stringify(rows);
+}

package/lib/index.js

@@ -23,6 +23,7 @@ import {
   isGetDateCommand,
   isManualReadTool,
   isReadOnlyTool,
+  matchKnownPitfall,
   needsApprovalReminder,
   PRIVATE_NETWORK_RE,
   setWorkspaceRoot,
@@ -54,8 +55,8 @@ import {
   reloadRules,
   resetTurn
 } from "./core/state.js";
-import { SAFE_UNCOVERED_TOOLS } from "./core/guard-core.js";
 import { toolClass } from "./core/tool-catalog.js";
+import { parseWhitelist, mergeWhitelist, serializeWhitelist } from "./core/whitelist.js";
 import { state } from "./core/runtime.js";
 import { detectViolations, extractAssistantText } from "./core/text-detect.js";
 import { shouldDetectTurn, shouldDeliver } from "./core/semantic.js";
@@ -306,15 +307,29 @@ function persistVerifyPass(state) {
   }
 }
 
-/** v0.5.7 后续（用户批准）：unknown 工具白名单持久化（~/.dsh/rule-engine-tools.json——"允许使用 X"重启/热重载不丢） */
-function persistToolWhitelist(state) {
+/** v0.5.7 后续（用户批准）：unknown 工具白名单持久化（~/.dsh/rule-engine-tools.json——"允许使用 X"重启/热重载不丢）
+ *  0.5.9 升级：存储格式 v2 带元数据 [{name,time,session}]——可视化"谁、何时、哪个会话放行"；
+ *  旧格式（字符串数组）兼容读取；持久化时合并既有 meta（历史条目不丢时间/来源）。 */
+function persistToolWhitelist(state, sid) {
   try {
-    writeFileSync(toolsWhitelistFilePath(), JSON.stringify([...(state.unknownToolApproved || [])]), "utf8");
+    const names = [...(state.unknownToolApproved || [])];
+    const prev = readWhitelistMeta();
+    const rows = mergeWhitelist([...prev.values()], names, sid);
+    writeFileSync(toolsWhitelistFilePath(), serializeWhitelist(rows), "utf8");
   } catch {
     // 持久化失败仅降级（内存态仍有效），不阻断
   }
 }
 
+/** 读取白名单文件并按元数据归 Map（v1 字符串数组 → {name,time:null,session:null}；v2 对象数组原样） */
+function readWhitelistMeta() {
+  const m = new Map();
+  let raw = null;
+  try { raw = readFileSync(toolsWhitelistFilePath(), "utf8"); } catch {}
+  for (const row of parseWhitelist(raw || "")) m.set(row.name, row);
+  return m;
+}
+
 export function handleSessionEvent(ctx, session, event) {
   maybeReloadIfChanged(state);
   const sid = session?.id || "global";
@@ -386,7 +401,11 @@ export function handleSessionEvent(ctx, session, event) {
       if (toolClass(toolName, {}) !== "unknown") continue; // 只对未归类工具有意义（已知工具不走 unknown 分支）
       const isNew = !state.unknownToolApproved.has(toolName);
       state.unknownToolApproved.add(toolName);
-      persistToolWhitelist(state); // v0.5.7 后续：白名单持久化（重启/热重载不丢——用户批准"这句不用每次发"）
+      if (isNew) {
+        if (!state.unknownToolSessionAdded) state.unknownToolSessionAdded = new Set();
+        state.unknownToolSessionAdded.add(toolName); // /guard tools 区分"本会话新增"
+      }
+      persistToolWhitelist(state, sid); // v0.5.7 后续：白名单持久化（重启/热重载不丢——用户批准"这句不用每次发"）
       audit({
         kind: "unknown-tool-whitelist",
         rule: "__unknown-tool",
@@ -558,6 +577,33 @@ export function handleSessionEvent(ctx, session, event) {
       }
     }
 
+    // 0.5.10 建议5（已知坑错误码召回）：错误结果文本命中特征表 → 审计 + 注入指向知识库的提示
+    //（本轮去重；仍走 maybeInject 资格链——真实用户在场/预算内才投递，不违反注入噪音治理）
+    if (isError) {
+      const errText = String(
+        resultBlock?.content?.map?.((c) => c?.text || "").join(" ") ||
+        d?.message?.content?.map?.((c) => c?.text || "").join(" ") ||
+        ""
+      );
+      const pit = matchKnownPitfall(errText);
+      if (pit) {
+        if (!s.turn.errorHints) s.turn.errorHints = new Set();
+        if (!s.turn.errorHints.has(pit.key)) {
+          s.turn.errorHints.add(pit.key);
+          audit({
+            kind: "error-hint",
+            rule: "__error-hint",
+            name: "已知坑召回",
+            event: "tool/result",
+            tool: pendingCall?.name || undefined,
+            reason: `${pit.key} 命中特征表（建议5：错误码→知识库）`,
+            session: sid
+          });
+          maybeInject(ctx, sid, { ruleId: "__error-hint", reason: pit.hint });
+        }
+      }
+    }
+
     // M8 双通道机制（2026-08-24）：dsh-manual-write 落盘成功 → 标记；同轮 engram_store 成功 → 标记
     if (!isError && pendingCall) {
       const cmd = pendingCall.args?.command || pendingCall.args?.code || "";
@@ -720,7 +766,11 @@ export function handleSessionEvent(ctx, session, event) {
           if (!state.unknownToolApproved) state.unknownToolApproved = new Set();
           const isNew = !state.unknownToolApproved.has(wname);
           state.unknownToolApproved.add(wname);
-          persistToolWhitelist(state); // v0.5.7 后续：白名单持久化（见上）
+          if (isNew) {
+            if (!state.unknownToolSessionAdded) state.unknownToolSessionAdded = new Set();
+            state.unknownToolSessionAdded.add(wname);
+          }
+          persistToolWhitelist(state, sid); // v0.5.7 后续：白名单持久化（见上）
           audit({
             kind: "unknown-tool-whitelist",
             rule: "__unknown-tool",
@@ -877,6 +927,8 @@ const USAGE = [
   "  /guard bypass [N]      临时整体放行 N 分钟（默认 5，仅用户）",
   "  /guard lock            立即恢复全部守卫（取消解锁/放行）",
   "  /guard revoke          撤销全部授权记录",
+  "  /guard tools           工具放行白名单（永久+本会话，含时间/来源会话）",
+  "  /guard tools revoke <工具名>  撤销白名单条目（持久化+会话集）",
   "  /guard reload          强制重解析 AGENTS.md",
   "  /guard mode <模式>     设置任务契约模式（review/answer/change/monitor/watch/off）",
   "  /guard budget ...      设置预算（agents=N files=... deps=allow hash=allow）",
@@ -904,6 +956,9 @@ function parseCommand(rawInput) {
   m = text.match(/^log\s*(\d+)?$/i);
   if (m) return { kind: "log", n: m[1] ? Number(m[1]) : 10 };
   if (/^reload$/i.test(text)) return { kind: "reload" };
+  if (/^tools$/i.test(text)) return { kind: "tools", action: "list" };
+  m = text.match(/^tools revoke\s+([A-Za-z_][A-Za-z0-9_:.-]*)$/i);
+  if (m) return { kind: "tools", action: "revoke", target: m[1] };
   if (/^mode\b/i.test(text)) {
     const parsed = parseModeCommand(text);
     if (parsed) return { kind: "mode", ...parsed };
@@ -1034,6 +1089,40 @@ async function executeGuard(ctx, invocation) {
           (saved.ok ? `\n理解产物已写入：${saved.path}` : `\n理解产物写入失败：${saved.error}`)
       };
     }
+    case "tools": {
+      // v0.5.9：白名单可视化——永久（元数据）+ 本会话新增；revoke = 从持久化文件与会话集移除
+      if (command.action === "revoke") {
+        const target = command.target;
+        const prev = readWhitelistMeta();
+        const existed = prev.delete(target);
+        writeFileSync(toolsWhitelistFilePath(), JSON.stringify([...prev.values()]), "utf8");
+        state.unknownToolApproved?.delete(target);
+        state.unknownToolSessionAdded?.delete(target);
+        audit({
+          kind: "guard-command",
+          rule: "__whitelist",
+          name: "白名单撤销",
+          event: "command",
+          reason: `/guard tools revoke ${target}（持久化+会话集同步移除）`,
+          session: invocation?.session?.id || "global"
+        });
+        return { kind: "success", text: `已撤销 ${target}${existed ? "" : "（原不在白名单）"}。` };
+      }
+      const meta = state.unknownToolApprovedMeta || new Map();
+      const sessionAdded = state.unknownToolSessionAdded || new Set();
+      const rows = [...(state.unknownToolApproved || [])].map((n) => {
+        const m = meta.get(n) || {};
+        let when = "未知";
+        if (typeof m.time === "number") {
+          try { when = new Date(m.time).toISOString(); } catch { when = "非法时间"; }
+        }
+        return `- ${n}${sessionAdded.has(n) ? "（本会话新增）" : ""} 时间=${when} 来源会话=${m.session || "未知"}`;
+      });
+      const text = rows.length
+        ? `工具放行白名单（/guard tools）：\n${rows.join("\n")}\n\n撤销：/guard tools revoke <工具名>`
+        : "工具放行白名单为空。";
+      return { kind: "success", text };
+    }
     case "mode": {
       if (!state.taskContract?.taskContractEnabled) return { kind: "error", text: "任务契约未启用：请先在规则引擎设置页开启总开关。" };
       const sid = invocation?.session?.id || "global";
@@ -1100,12 +1189,12 @@ export function apply(ctx) {
   }
 
   // v0.5.7 后续（用户批准）：加载白名单持久化（"允许使用 X"重启/热重载不丢）
+  // 0.5.9：v2 对象数组（带 meta）与 v1 字符串数组兼容；meta 供 /guard tools 可视化
   try {
     const wlRaw = readFileSync(toolsWhitelistFilePath(), "utf8");
-    const wlArr = JSON.parse(wlRaw);
-    if (Array.isArray(wlArr)) {
-      state.unknownToolApproved = new Set(wlArr.filter((n) => typeof n === "string"));
-    }
+    const rows = parseWhitelist(wlRaw);
+    state.unknownToolApproved = new Set(rows.map((r) => r.name));
+    state.unknownToolApprovedMeta = new Map(rows.map((r) => [r.name, r]));
   } catch {
     // 首次运行/无文件：空白名单
   }
@@ -1267,30 +1356,40 @@ export function apply(ctx) {
     return next();
   });
 
-  // 0.9 机制 B（2026-08-24）：未归类工具（新插件/新工具）首调 deny——fail-closed，防"approval 层自动放行 ask"的洞。
-  // 批次 3（2026-08-24 用户拍板分支 A）：实测未知工具首调 ask 被 DSH approval 层自动放行（无弹窗直接执行），
-  // 因此 unknown → 物理 deny；批准路径 = 用户明确"允许使用 X"（handleSessionEvent 写入会话白名），本会话内放行。
+  // 0.9 机制 B（2026-08-24；0.5.9 修订——K-02/K-03 依据）：未归类工具首调按 unknownPolicy 处置：
+  //   "ask"  = 官方 pre-execute ask 语义（approval 弹窗，allowed-once 才续行；无审批通道 → 官方自动 deny，
+  //            fail-closed 由官方保证）；"deny" = 物理拒绝 + 提示（"允许使用 X" 会话白名路径恒可用）。
+  //   历史教训（08-24 实测 ask 被自动放行 → 当时改 deny）：0.5.9 发布前必须实弹验证 ask 弹窗真实出现
+  //   （K-02 门禁），验证不过则发布时默认保持 deny。
   ctx.on("tools/pre-execute", async (exec, next) => {
     try {
-      if (SAFE_UNCOVERED_TOOLS.has(exec?.name)) return next(); // 控制类不进 unknown 判定（避免 ask 自身被 ask）
+      if ((state.unknownToolApproved || new Set()).has(exec?.name)) return next(); // 会话内用户已批准
       if (toolClass(exec?.name, exec?.arguments || {}) !== "unknown") return next();
-      if ((state.unknownToolApproved || new Set()).has(exec.name)) return next(); // 会话内用户已批准
+      // 0.5.9：unknownPolicy 默认 "deny"（K-02 门禁：ask 需实弹验证弹窗真实出现后才可默认；
+      // 当前无真实 unknown 工具可触发实弹——分类表已全覆盖，等待未来真实场景验证后经配置切换）
+      const policy = pluginConfig.unknownPolicy === "ask" ? "ask" : "deny";
       audit({
         kind: "unknown-tool",
         rule: "__unknown-tool",
-        name: "未归类工具拦截",
+        name: "未归类工具首调处置",
         event: "tools/pre-execute",
         tool: exec?.name,
         args: summarizeArgs(exec?.arguments),
-        reason: `工具 ${exec.name} 不在规则引擎分类表（可能是新装的插件）：已拦截（unknown→deny）。批准路径：用户明确"允许使用 ${exec.name}"后本会话放行；长期规则请补充工具分类表`,
+        reason: `工具 ${exec.name} 不在规则引擎分类表：按 unknownPolicy=${policy} 首调处置（批准路径：官方弹窗批准 / 用户明确"允许使用 ${exec.name}"写入会话白名单；长期规则请补充工具分类表）`,
         session: sessionIdOfExec(exec)
       });
+      if (policy === "ask") {
+        return {
+          kind: "ask",
+          reason: `工具 ${exec.name} 未登记在规则引擎分类表：批准本次后放行；如需本会话持续放行请说"允许使用 ${exec.name}"。`
+        };
+      }
       return {
         kind: "deny",
         reason: `工具 ${exec.name} 尚未归类（新装插件？）：已拦截。如需使用请向用户说明用途并获取其"允许使用 ${exec.name}"的明确答复后重试（批准后本会话内放行）。`
       };
     } catch (error) {
-      ctx.logger?.warn?.("[dsh-rule-engine] unknown-tool deny error", error);
+      ctx.logger?.warn?.("[dsh-rule-engine] unknown-tool handling error", error);
       return next();
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rule-engine",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "DSH 规则执行引擎 v3：容器解析 AGENTS.md + 理解器 + 匹配机 + 执行框架",
   "type": "module",
   "main": "lib/index.js",

package/scripts/check-tool-coverage.mjs

@@ -0,0 +1,41 @@
+// check-tool-coverage.mjs — 0.5.9 工具覆盖门禁（K-01/K-06 依据，仿官方 verify-tool-catalog）：
+// 官方 tool-catalog（生成器产物=权威全集）中的每个工具名都必须在分类表/前缀规则内被识别，
+// 任何一个 unknown = 该工具调用会被未知工具首调处置（ask/deny）→ 工程失败。
+// 用法：node scripts/check-tool-coverage.mjs
+import { readFileSync } from "node:fs";
+import { toolClass } from "../lib/core/tool-catalog.js";
+
+const CATALOG = "D:\\DeepSeek harness\\dsh-project\\docs-site-text\\en\\reference\\tool-catalog.txt";
+
+function parseNames() {
+  const names = new Set();
+  for (const line of readFileSync(CATALOG, "utf8").split("\n")) {
+    if (!line.includes("@deepseek-ai/dsh-")) continue;
+    const cols = line.split("|").map((c) => c.trim());
+    // 表列格式：| | <package> | <model-visible names> | <requires> | <writes> | <shipped aliases> | <note> |
+    if (!cols[2] || !cols[2].startsWith("@deepseek-ai")) continue;
+    const add = (s) => {
+      if (!s || s === "-") return;
+      for (const x of s.split(",")) {
+        const n = x.trim();
+        if (/^[A-Za-z_][A-Za-z0-9_:.-]*$/.test(n)) names.add(n);
+      }
+    };
+    add(cols[3]);
+    add(cols[6]);
+  }
+  return names;
+}
+
+const official = parseNames();
+const missing = [];
+for (const n of official) {
+  if (toolClass(n, {}) === "unknown") missing.push(n);
+}
+
+if (missing.length) {
+  console.error(`COVERAGE-FAIL：官方 tool-catalog 有 ${missing.length} 个工具未分类（会被未知工具首调处置）：`);
+  for (const n of missing) console.error("  - " + n);
+  process.exit(1);
+}
+console.log(`COVERAGE-OK：官方 tool-catalog 工具全覆盖（${official.size} 个工具名均被分类表/前缀规则识别）`);

package/scripts/health-audit.mjs

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const auditPath = join(process.env.DSH_HOME || join(process.env.USERPROFILE || "", ".dsh"), "rule-engine.log.jsonl");
 const now = Date.now();
-const cuts = { intentFail: 0, intentOk: 0, judgePass: 0, judgeFalse: 0, judgeUnavail: 0, verifyGap: 0, injectSkip: 0, sourceSkip: 0 };
+const cuts = { intentFail: 0, intentOk: 0, judgePass: 0, judgeFalse: 0, judgeUnavail: 0, verifyGap: 0, injectSkip: 0, sourceSkip: 0, denyTotal: 0, labelIncorrect: 0, labelCorrect: 0, errorHint: 0 };
 
 try {
   for (const line of readFileSync(auditPath, "utf8").split("\n")) {
@@ -24,6 +24,10 @@ try {
     if (line.includes('"kind":"verify-gap"')) cuts.verifyGap++;
     if (line.includes('"kind":"inject-skip"')) cuts.injectSkip++;
     if (line.includes('"kind":"source-skip"')) cuts.sourceSkip++;
+    if (line.includes('"kind":"deny"')) cuts.denyTotal++;
+    if (line.includes('"kind":"task-label"') && line.includes("incorrect")) cuts.labelIncorrect++;
+    if (line.includes('"kind":"task-label"') && line.includes("correct")) cuts.labelCorrect++;
+    if (line.includes('"kind":"error-hint"')) cuts.errorHint++;
   }
 } catch {
   // 无日志文件：一切 0
@@ -49,6 +53,8 @@ console.log("== 健康审计（近 24h）==");
 console.log(`intent-llm 失败降级 ${cuts.intentFail} 条 / 成功 ${cuts.intentOk} 条`);
 console.log(`judge-pass ${cuts.judgePass} 条 / judge-false ${cuts.judgeFalse} 条 / judge-unavailable ${cuts.judgeUnavail} 条`);
 console.log(`verify-gap ${cuts.verifyGap} 条 / inject-skip ${cuts.injectSkip} 条 / source-skip ${cuts.sourceSkip} 条`);
+console.log(`误判打标（建议4）：deny 总数 ${cuts.denyTotal} 条 → label incorrect ${cuts.labelIncorrect} 条 / correct ${cuts.labelCorrect} 条${cuts.denyTotal > 0 && cuts.labelIncorrect > 0 ? `（incorrect 占比 ${(cuts.labelIncorrect / cuts.denyTotal * 100).toFixed(1)}%）` : ""}——词表迭代量化依据`);
+console.log(`已知坑召回（建议5）：error-hint ${cuts.errorHint} 条`);
 console.log(`接线交叉：${EXPORTS.length} 个关键导出 → 疑似未接线 ${orphans.length ? orphans.join("、") : "0 个"}`);
 if (cuts.judgePass + cuts.judgeFalse === 0) {
   console.log("⚠️ 问题：近 24h 无真实判例——裁决器无运行证据（需实弹）");

package/scripts/verify-all.mjs

@@ -1,9 +1,11 @@
-// verify-all.mjs - 交付前体检报告（2026-08-26，对齐官方 docs/testing.zh.md 分层验证）。
-// 四层：① 语法（lib 全部 .js node --check）
+// verify-all.mjs - 交付前体检报告（2026-08-26，对齐官方 docs/testing.zh.md 分层验证；0.5.9 增第⑤层）。
+// 五层：① 语法（lib 全部 .js node --check）
 //       ② 单元（test/run-all.mjs——单元+机制层，不含 e2e）
 //       ③ 组合冒烟（test/loader-smoke.e2e.mjs——真实接线 + 外部世界断言）
 //       ④ 真实判例（外部世界：近 24h 台账中 judge-pass/judge-false 记录数；
 //          0 条 = WARN 提示需实弹，≥1 条 = 有真实裁决证据——读文件，不是自我报告）
+//       ⑤ 工具箱覆盖（scripts/check-tool-coverage.mjs——官方 tool-catalog 全集 vs 分类表，
+//          任何 unknown = 未知工具首调处置会拦用户 → 红色（run_code 事故同类，K-01/K-06 门禁））
 // 任一 ❌ → exit 1；⚠️（WARN）不阻塞但必须明示。
 // 注意：子进程输出捕获需完整权限运行（受限模式 EPERM）。
 import { execFileSync } from "node:child_process";
@@ -53,6 +55,9 @@ step("单元（test/run-all.mjs）", process.execPath, [join(root, "test", "run-
 // ── ③ 组合冒烟 ──
 step("组合冒烟（loader-smoke，真实接线+外部世界断言）", process.execPath, [join(root, "test", "loader-smoke.e2e.mjs")]);
 
+// ── ⑤ 工具箱覆盖（0.5.9 门禁） ──
+step("工具箱覆盖（官方 tool-catalog vs 分类表，缺失即红）", process.execPath, [join(root, "scripts", "check-tool-coverage.mjs")]);
+
 // ── ④ 真实判例（外部世界） ──
 let judgeReal = 0;
 const auditPath = join(process.env.DSH_HOME || join(process.env.USERPROFILE || "", ".dsh"), "rule-engine.log.jsonl");