@zooique/memora 2.0.0 → 3.0.0

package/dist/security/pathGuard.d.ts

@@ -1,13 +1,13 @@
 export type Permission = 'owner' | 'guest';
 export type WriteDecision = 'confirmed' | 'declined' | 'auto-approved' | 'auto-denied';
 export interface AuditEvent {
-    /** 事件类型 */
+    /** 事件类型：路径允许/拒绝、写入确认/拒绝/自动 */
     type: 'path-allow' | 'path-deny' | 'write-confirm' | 'write-decline' | 'write-auto';
     /** 涉及的绝对路径 */
     path: string;
     /** 工具名（read_file / write_file / 自定义工具名） */
     tool?: string;
-    /** 调用链来源（builtin / custom / system），标记安全检查的触发方 */
+    /** 调用链来源，标记安全检查的触发方 */
     source?: 'builtin' | 'custom' | 'system';
     /** 用户决策（写入二次确认场景） */
     decision?: WriteDecision;
@@ -16,19 +16,11 @@ export interface AuditEvent {
     /** 时间戳（ISO 8601） */
     timestamp: string;
 }
-/**
- * 审计日志订阅器
- * 默认输出到 pino logger；可被业务层重定向到独立审计文件
- */
+/** 审计日志订阅器：默认经内核 logger 单例输出，可被业务层重定向到独立审计文件 */
 export type AuditListener = (event: AuditEvent) => void;
 /**
- * 写入确认请求
- *
- * 宿主程序在非交互式环境（WebUI/桌宠/无终端服务）需要自定义确认 UI。
- * 注入此回调后，SecurityGuard.requestWriteConfirmation() 会调用它而不是直接读 stdin。
- *
- * 返回 true 确认写入，false 拒绝写入。
- * 抛错视为拒绝（fail-closed，安全优先）。
+ * 写入确认请求：宿主在非交互式环境（WebUI/桌宠/无终端）注入自定义确认 UI，
+ * 走此回调而非直接读 stdin。返回 true 确认 / false 拒绝；抛错视为拒绝（fail-closed）。
  */
 export type WriteConfirmationRequest = (info: WriteConfirmationInfo) => Promise<boolean>;
 /** 写入确认请求的载荷 */
@@ -37,107 +29,112 @@ export interface WriteConfirmationInfo {
     targetPath: string;
     /** 工具名（如 write_file） */
     tool: string;
-    /** 人类可读的描述（"写入 100 字符到 foo.md"） */
+    /** 人类可读描述（"写入 100 字符到 foo.md"） */
     description?: string;
     /** 权限模式（owner / guest） */
     permission: Permission;
-    /** 是否需要确认（owner + confirmWrites=false 时为 false，宿主可跳过弹窗） */
+    /** 是否需确认（owner+confirmWrites=false 时为 false，宿主可跳过弹窗） */
     needsConfirm: boolean;
-    /** 文件当前内容预览（截断到 10KB，null 表示新文件）—— 供宿主 UI 展示 diff */
+    /** 文件当前内容预览（截断到 10KB，null 表示新文件）——供宿主 UI 展示 diff */
     beforeContent?: string | null;
-    /** 写入后内容预览（截断到 10KB）—— 供宿主 UI 展示 diff */
+    /** 写入后内容预览（截断到 10KB）——供宿主 UI 展示 diff */
     afterContent?: string;
 }
+/** diff 内容最大长度（10KB），防大文件撑爆 IPC 传输和 UI 渲染。宿主 UI 展示上限从本常量 import 对齐（唯一真源） */
+export declare const MAX_DIFF_CONTENT_LENGTH = 10240;
 export declare class SecurityGuard {
-    /** owner 是否启用写入二次确认；guest 强制开启 */
-    readonly confirmWrites: boolean;
     /** 权限模式 */
     readonly permission: Permission;
     private readonly listeners;
-    /** 审计事件缓冲（最近 N 条，供调试与回溯） */
-    private readonly auditBuffer;
-    private readonly bufferLimit;
     /**
-     * 注入式写入确认回调。
-     * 宿主注册后，requestWriteConfirmation() 走自定义 UI；
-     * 不注册时回退到终端 readline（CLI 场景）。
+     * 注入式写入确认回调：宿主注册后走自定义 UI；不注册时回退到终端 readline（CLI 场景）。
      */
     private confirmationHandler;
-    /** 允许访问的根目录列表（白名单） */
-    private readonly allowedRoots;
-    constructor(projectPath: string, memoraDir: string, extraAllowedPaths?: string[], 
-    /** owner 是否启用写入二次确认；guest 强制开启 */
-    confirmWrites?: boolean, 
+    /** 基准信任根（projectPath/memoraDir/configDir/agentDataDir，构造器固化，运行时不可移除） */
+    private readonly baseRoots;
+    /** 用户额外白名单（运行时经 setAllowedPaths 热更新） */
+    private extraRoots;
+    /** 允许访问的根目录列表（白名单）= baseRoots + extraRoots（派生，断言时遍历） */
+    private allowedRoots;
+    /** owner 是否启用写入二次确认；guest 强制开启（可运行时切换） */
+    confirmWrites: boolean;
+    /** 是否对脚本/代码执行启用确认（owner 模式；guest 强制开启；默认 false = 默认不弹窗） */
+    confirmScripts: boolean;
+    constructor(projectPath: string, memoraDir: string, extraAllowedPaths?: string[], confirmWrites?: boolean, 
     /** 权限模式 */
     permission?: Permission, 
+    /** 脚本执行确认开关（独立于写入确认，供对 run_code/run_project_script 单独收紧） */
+    confirmScripts?: boolean, 
     /** Agent 级配置目录（personas/rules/skills 所在目录） */
     configDir?: string, 
-    /** Agent 级数据目录（memora.db/vectors 所在目录） */
+    /** Agent 级数据目录（宿主传入；内核不假设其下的文件形态） */
     agentDataDir?: string);
+    /** 注册自定义写入确认回调（宿主接入）；取消注册传入 null。WebUI/桌宠等无终端场景走此回调而非读 stdin */
+    onWriteConfirmation(handler: WriteConfirmationRequest | null): void;
     /**
-     * 注册自定义写入确认回调（宿主程序接入）
-     *
-     * 适用于 WebUI/桌宠/无终端服务。注册后，requestWriteConfirmation()
-     * 不再直接读 stdin，而是回调此函数让宿主决定如何提示用户。
-     *
-     * 取消注册：传入 null。
+     * 运行时切换写入二次确认开关（宿主设置面板热更新）
      *
-     * @example
-     *   securityGuard.onWriteConfirmation(async (info) => {
-     *     return await showConfirmDialog(info.targetPath, info.description);
-     *   });
+     * 开启后：owner 模式下写文件前会触发 confirmationHandler 弹窗审批；
+     * 关闭后：owner 模式下写文件自动批准（审计仍会记录）。
+     * guest 模式不受影响——始终需要确认。
      */
-    onWriteConfirmation(handler: WriteConfirmationRequest | null): void;
+    setConfirmWrites(value: boolean): void;
     /**
-     * 订阅审计事件
-     * @returns 取消订阅函数
+     * 运行时切换脚本/代码执行确认开关（宿主设置面板热更新）
+     *
+     * 开启后：owner 模式下 run_code/run_project_script 执行前会触发 confirmationHandler 弹窗审批；
+     * 关闭后：owner 模式下脚本自动批准（审计仍会记录）。
+     * guest 模式不受影响——脚本执行始终需要确认。
      */
-    onAudit(listener: AuditListener): () => void;
+    setConfirmScripts(value: boolean): void;
     /**
-     * 获取最近的审计事件（深拷贝，外部不可修改内部缓冲）
+     * 运行时设置「用户额外白名单」（宿主设置面板热更新）
+     *
+     * 仅操作额外项（extraRoots），基准信任根（baseRoots）永不被触碰——守住安全显式性：
+     * 项目目录、memora 数据目录、配置/数据目录始终允许访问，用户无法误删。
+     * 传空数组 = 清空额外项（仅留基准根，等价「重置」）。
+     * 黑名单（BLOCKED_PATTERNS）对新增路径仍强制生效——白名单是允许列表，非绕过黑名单的通行证。
      */
-    getRecentAudits(limit?: number): AuditEvent[];
+    setAllowedPaths(extraPaths: string[]): void;
+    /** 订阅审计事件；@returns 取消订阅函数 */
+    onAudit(listener: AuditListener): () => void;
     /**
-     * 断言路径允许访问
-     * @throws Error 不在白名单时
-     * @param source 调用链来源标记
+     * 断言路径允许访问（命中即拒绝）；黑名单优先，其次白名单前缀匹配（追加 sep 防兄弟目录绕过）。
+     * @throws 不在白名单时
      */
     assertPathAllowed(absolutePath: string, tool?: string, source?: 'builtin' | 'custom' | 'system'): void;
     /**
-     * 写入操作前请求用户确认
-     *
-     * 规则：
-     *   - guest 模式：始终要求确认
-     *   - owner + confirmWrites=true：要求确认
-     *   - owner + confirmWrites=false：自动批准
-     *
-     * 决策（fail-closed）：
-     *   - 需要确认时，必须通过 onWriteConfirmation() 注入 confirmationHandler
-     *   - 未注入 handler 时，**直接拒绝写入**（返回 false）
-     *   - 理由：内核纯逻辑库不应依赖交互式终端 I/O；宿主程序负责提供确认 UI
-     *   - 安全优先：未配置 = 拒绝，避免无意识放行
-     *
-     * @returns true 确认通过；false 用户拒绝或未注入 handler（fail-closed）
+     * 写入前请求用户确认。guest 或 confirmWrites 需确认；未注入 confirmationHandler 时 fail-closed 拒绝（返回 false），
+     * 理由：内核纯逻辑库不依赖交互式终端 I/O，宿主负责确认 UI；安全优先：未配置 = 拒绝。
      */
     requestWriteConfirmation(targetPath: string, tool: string, description?: string, 
-    /** diff 内容选项（供宿主 UI 展示变更预览，自动截断到 10KB） */
+    /** diff 内容选项（宿主 UI 变更预览用，自动截断到 10KB） */
     options?: {
         beforeContent?: string | null;
         afterContent?: string;
     }): Promise<boolean>;
     /**
-     * 通过宿主注入的 confirmationHandler 进行写入确认
+     * 脚本/代码执行前确认（run_code / run_project_script 的执行闸）
      *
-     * 从 requestWriteConfirmation 拆分。抛错视为拒绝（fail-closed 安全优先）。
-     * 此方法是唯一的确认执行路径。
+     * 判据与写入确认同构：guest 模式或 confirmScripts 需确认；未注入 confirmationHandler 时
+     * fail-closed 拒绝。owner + confirmScripts=false 自动批准（默认），审计仍记录。
+     * target 为脚本绝对路径（run_project_script）或描述型标识（run_code 内联代码无落盘路径）。
+     */
+    confirmScriptRun(targetPath: string, tool: string, description?: string): Promise<boolean>;
+    /**
+     * 确认闸公共核心（SSOT：写入确认与脚本执行确认的唯一执行路径）
      *
-     * @param info 确认信息（含 diff 内容）
-     * @returns true 确认通过；false 用户拒绝或回调异常
+     * needConfirm=false → 自动批准（审计 write-auto）；为 true 且未注入 confirmationHandler
+     * → fail-closed 拒绝（审计 write-decline）；否则经 confirmViaHandler 走宿主确认 UI。
+     * diff 仅写入场景有，脚本执行不传（域留空）。
      */
-    private confirmViaHandler;
+    private confirmGate;
     /**
-     * 触发审计事件 + 写入日志 + 通知订阅者
+     * 通过宿主注入的 confirmationHandler 执行写入确认（唯一确认执行路径）。
+     * 抛错视为拒绝（fail-closed 安全优先）。
      */
+    private confirmViaHandler;
+    /** 触发审计事件：写日志 + 通知订阅者 */
     private emitAudit;
 }
 //# sourceMappingURL=pathGuard.d.ts.map

package/dist/security/pathGuard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pathGuard.d.ts","sourceRoot":"","sources":["../../src/security/pathGuard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pathGuard.d.ts","sourceRoot":"","sources":["../../src/security/pathGuard.ts"],"names":[],"mappings":"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"}

package/dist/security/pathGuard.js

@@ -1,32 +1,20 @@
 /**
  * 路径白名单 + 审计日志
- *
- * 4 类允许根 + 28 类禁止规则
- * 详见 ADR-006 · 安全模型
- *
- * 写入二次确认 + 审计日志：未注入 confirmationHandler 时 fail-closed 拒绝写入。
- * 内核纯逻辑库不应依赖交互式终端 I/O（node:readline/promises + node:process），
- * 宿主程序应通过 onWriteConfirmation() 注入自己的确认 UI（Electron/Web/CLI 各自实现）。
+ * 4 类允许根 + 28 类禁止规则。
+ * 写入需二次确认 + 审计日志：未注入 confirmationHandler 时 fail-closed 拒绝写入。
+ * 内核纯逻辑库不依赖交互式终端 I/O，宿主应通过 onWriteConfirmation() 注入自己的确认 UI。
  */
 import { resolve, sep, dirname, basename, join } from 'node:path';
 import { realpathSync } from 'node:fs';
 import { logger } from '../logging/logger.js';
-import { securityError, toError } from '../utils/errors.js';
+import { securityError } from '../utils/errors.js';
+import { toError } from '../utils/toError.js';
 import { expandHome } from '../utils/path.js';
 import { nowIso } from '../utils/time.js';
 /**
- * 解析路径的真实绝对路径（解析符号链接链）
- *
- * 安全考量：若不解析符号链接，攻击者可在项目内放置指向 /etc 的符号链接，
- * 绕过白名单前缀匹配访问任意系统目录（P0 符号链接逃逸漏洞）。
- *
- * 策略：
- * - 路径存在时：realpathSync 解析完整符号链接链
- * - 路径不存在时（写入新文件场景）：逐级向上查找已存在的父目录并 realpath，再拼接不存在部分
- * - 全程不存在时：回退到 resolve()（白名单/黑名单仍会兜底校验）
- *
- * @param p 任意路径（相对或绝对）
- * @returns 解析符号链接后的真实绝对路径
+ * 解析符号链接后的真实绝对路径。
+ * 安全考量：不解析符号链接时，攻击者可用项目内指向 /etc 的符号链接绕过白名单前缀匹配访问任意系统目录（路径穿越逃逸）。
+ * 不存在时（写新文件）逐级向上解析已存在父目录再拼接；全程不存在时回退 resolve()（白名单/黑名单仍兜底校验）。
  */
 function resolveRealpath(p) {
     const resolved = resolve(p);
@@ -34,7 +22,7 @@ function resolveRealpath(p) {
         return realpathSync(resolved);
     }
     catch {
-        // 路径不存在 - 递归解析已存在的父目录
+        // 路径不存在：递归解析已存在的父目录
         const parent = dirname(resolved);
         const base = basename(resolved);
         try {
@@ -42,123 +30,159 @@ function resolveRealpath(p) {
             return join(realParent, base);
         }
         catch {
-            // 父目录也不存在 - 继续向上递归
+            // 父目录也不存在：继续向上递归
             const realGrandParent = resolveRealpath(parent);
             return join(realGrandParent, base);
         }
     }
 }
 const BLOCKED_PATTERNS = [
-    // ─── 系统凭证文件（跨平台，路径段匹配）───
+    // 系统凭证文件（跨平台，路径段匹配）
     /(^|[\\/])\.ssh([\\/]|$)/i,
     /(^|[\\/])\.gnupg([\\/]|$)/i,
     /(^|[\\/])\.netrc$/i,
     /(^|[\\/])\.pgpass$/i,
-    // ─── 包管理器凭证 ───
-    /(^|[\\/])\.gitconfig$/i, // Git 配置（可能含 credential helper token）
-    /(^|[\\/])\.git-credentials$/i, // Git credential store 明文存储
-    /(^|[\\/])\.npmrc$/i, // npm authToken
-    /(^|[\\/])\.pypirc$/i, // PyPI 上传凭证
-    /(^|[\\/])\.gem[\\/]credentials$/i, // RubyGems push 凭证
-    /(^|[\\/])\.composer[\\/]auth\.json$/i, // Composer 凭证
-    /(^|[\\/])\.htpasswd$/i, // Apache Basic Auth 凭证
-    // ─── Linux/macOS 特定凭证文件（向后兼容保留）───
-    /[\\/]etc[\\/]passwd/i, // 用户密码哈希
+    // 包管理器凭证：多为明文存储，可含推发令牌
+    /(^|[\\/])\.gitconfig$/i,
+    /(^|[\\/])\.git-credentials$/i,
+    /(^|[\\/])\.npmrc$/i,
+    /(^|[\\/])\.pypirc$/i,
+    /(^|[\\/])\.gem[\\/]credentials$/i,
+    /(^|[\\/])\.composer[\\/]auth\.json$/i,
+    /(^|[\\/])\.htpasswd$/i,
+    // Linux/macOS 系统账户文件
+    /[\\/]etc[\\/]passwd/i,
     /[\\/]etc[\\/]shadow/i,
-    /[\\/]etc[\\/]gshadow/i, // 组密码哈希
-    /[\\/]etc[\\/]sudoers/i, // sudo 配置
-    // ─── 云服务凭证 ───
+    /[\\/]etc[\\/]gshadow/i,
+    /[\\/]etc[\\/]sudoers/i,
+    // 云服务与容器凭证
     /(^|[\\/])\.aws([\\/]|$)/i,
     /(^|[\\/])\.azure([\\/]|$)/i,
     /(^|[\\/])\.docker([\\/]|$)/i,
     /(^|[\\/])\.kube([\\/]|$)/i,
-    /(^|[\\/])\.config[\\/]gcloud([\\/]|$)/i, // gcloud 配置（加 .config 前缀边界，避免误拦用户 gcloud-tools 目录）
-    // ─── 环境变量文件（.env / .env.local / .env.production.local 等多段后缀）───
+    /(^|[\\/])\.config[\\/]gcloud([\\/]|$)/i,
+    // 环境变量文件（.env / .env.local / .env.production.local 等多段后缀；.envrc 独立于 .env.* 后缀模式）
     /(^|[\\/])\.env(\.[^\\/]+)?$/i,
-    // .envrc（direnv 配置，可含环境变量和密钥，独立于 .env.* 后缀模式）
     /(^|[\\/])\.envrc$/i,
-    // ─── Windows 系统目录 ───
-    /[\\/]Windows([\\/]|$)/i, // C:\Windows（含 System、System32 等子目录）
-    /[\\/]Program Files([\\/]|$)/i, // C:\Program Files
-    /[\\/]Program Files \(x86\)([\\/]|$)/i, // C:\Program Files (x86)
-    /[\\/]ProgramData([\\/]|$)/i, // C:\ProgramData（系统级应用数据）
-    // ─── Linux/macOS 系统目录（根目录锚定 ^/，避免误伤项目内同名目录）───
+    // Windows 系统目录
+    /[\\/]Windows([\\/]|$)/i,
+    /[\\/]Program Files([\\/]|$)/i,
+    /[\\/]Program Files \(x86\)([\\/]|$)/i,
+    /[\\/]ProgramData([\\/]|$)/i,
+    // Linux/macOS 系统目录（根目录锚定 ^/，避免误伤项目内同名目录）
     /^\/(etc|usr|bin|sbin|var|root|home|lib|lib64|opt)([\\/]|$)/i,
-    // ─── Linux/macOS 虚拟文件系统 + 启动目录（根目录锚定）───
+    // 虚拟文件系统 + 启动目录（根目录锚定）
     /^\/(proc|sys|boot)([\\/]|$)/i,
 ];
-/** diff 内容最大长度（10KB），防止大文件内容撑爆 IPC 传输和 UI 渲染 */
-const MAX_DIFF_CONTENT_LENGTH = 10240;
+/** 运行时动态白名单（setAllowedPaths）最大条数，与 config/loader.ts 同值，防白名单膨胀 */
+const MAX_EXTRA_ALLOWED_PATHS = 50;
+/** diff 内容最大长度（10KB），防大文件撑爆 IPC 传输和 UI 渲染。宿主 UI 展示上限从本常量 import 对齐（唯一真源） */
+export const MAX_DIFF_CONTENT_LENGTH = 10240;
 function truncateForDiff(content) {
     if (content === null || content === undefined)
         return content;
     if (content.length <= MAX_DIFF_CONTENT_LENGTH)
         return content;
-    // 超过上限时截断并追加标记，让用户知道内容被裁剪
+    // 超限截断并追加标记，让用户知道内容被裁剪
     return content.slice(0, MAX_DIFF_CONTENT_LENGTH) + `\n...（已截断，共 ${content.length} 字符）`;
 }
 export class SecurityGuard {
-    confirmWrites;
     permission;
     listeners = [];
-    /** 审计事件缓冲（最近 N 条，供调试与回溯） */
-    auditBuffer = [];
-    bufferLimit = 100;
     /**
-     * 注入式写入确认回调。
-     * 宿主注册后，requestWriteConfirmation() 走自定义 UI；
-     * 不注册时回退到终端 readline（CLI 场景）。
+     * 注入式写入确认回调：宿主注册后走自定义 UI；不注册时回退到终端 readline（CLI 场景）。
      */
     confirmationHandler = null;
-    /** 允许访问的根目录列表（白名单） */
+    /** 基准信任根（projectPath/memoraDir/configDir/agentDataDir，构造器固化，运行时不可移除） */
+    baseRoots;
+    /** 用户额外白名单（运行时经 setAllowedPaths 热更新） */
+    extraRoots;
+    /** 允许访问的根目录列表（白名单）= baseRoots + extraRoots（派生，断言时遍历） */
     allowedRoots;
-    constructor(projectPath, memoraDir, extraAllowedPaths = [], 
-    /** owner 是否启用写入二次确认；guest 强制开启 */
-    confirmWrites = false, 
+    /** owner 是否启用写入二次确认；guest 强制开启（可运行时切换） */
+    confirmWrites;
+    /** 是否对脚本/代码执行启用确认（owner 模式；guest 强制开启；默认 false = 默认不弹窗） */
+    confirmScripts;
+    constructor(projectPath, memoraDir, extraAllowedPaths = [], confirmWrites = false, 
     /** 权限模式 */
     permission = 'owner', 
+    /** 脚本执行确认开关（独立于写入确认，供对 run_code/run_project_script 单独收紧） */
+    confirmScripts = false, 
     /** Agent 级配置目录（personas/rules/skills 所在目录） */
     configDir, 
-    /** Agent 级数据目录（memora.db/vectors 所在目录） */
+    /** Agent 级数据目录（宿主传入；内核不假设其下的文件形态） */
     agentDataDir) {
-        this.confirmWrites = confirmWrites;
         this.permission = permission;
-        // 构建白名单根目录列表：使用 resolveRealpath 解析符号链接，
-        // 确保白名单基准是真实路径，与 assertPathAllowed 中的 resolveRealpath 对齐
-        this.allowedRoots = [
+        // 基准信任根用真实路径（resolveRealpath），与 assertPathAllowed 对齐，避免前缀匹配错位
+        this.baseRoots = [
             resolveRealpath(expandHome(projectPath)),
             resolveRealpath(expandHome(memoraDir)),
         ];
         if (configDir) {
-            this.allowedRoots.push(resolveRealpath(expandHome(configDir)));
+            this.baseRoots.push(resolveRealpath(expandHome(configDir)));
         }
         if (agentDataDir) {
-            this.allowedRoots.push(resolveRealpath(expandHome(agentDataDir)));
-        }
-        for (const p of extraAllowedPaths) {
-            this.allowedRoots.push(resolveRealpath(expandHome(p)));
+            this.baseRoots.push(resolveRealpath(expandHome(agentDataDir)));
         }
+        this.confirmWrites = confirmWrites;
+        // 脚本执行确认开关（独立于写入确认）
+        this.confirmScripts = confirmScripts;
+        // 用户额外白名单（构造器注入），基准根与额外项分离以便 setAllowedPaths 仅改额外项
+        this.extraRoots = extraAllowedPaths.map((p) => resolveRealpath(expandHome(p)));
+        this.allowedRoots = [...this.baseRoots, ...this.extraRoots];
+    }
+    /** 注册自定义写入确认回调（宿主接入）；取消注册传入 null。WebUI/桌宠等无终端场景走此回调而非读 stdin */
+    onWriteConfirmation(handler) {
+        this.confirmationHandler = handler;
     }
     /**
-     * 注册自定义写入确认回调（宿主程序接入）
-     *
-     * 适用于 WebUI/桌宠/无终端服务。注册后，requestWriteConfirmation()
-     * 不再直接读 stdin，而是回调此函数让宿主决定如何提示用户。
+     * 运行时切换写入二次确认开关（宿主设置面板热更新）
      *
-     * 取消注册：传入 null。
+     * 开启后：owner 模式下写文件前会触发 confirmationHandler 弹窗审批；
+     * 关闭后：owner 模式下写文件自动批准（审计仍会记录）。
+     * guest 模式不受影响——始终需要确认。
+     */
+    setConfirmWrites(value) {
+        this.confirmWrites = value;
+    }
+    /**
+     * 运行时切换脚本/代码执行确认开关（宿主设置面板热更新）
      *
-     * @example
-     *   securityGuard.onWriteConfirmation(async (info) => {
-     *     return await showConfirmDialog(info.targetPath, info.description);
-     *   });
+     * 开启后：owner 模式下 run_code/run_project_script 执行前会触发 confirmationHandler 弹窗审批；
+     * 关闭后：owner 模式下脚本自动批准（审计仍会记录）。
+     * guest 模式不受影响——脚本执行始终需要确认。
      */
-    onWriteConfirmation(handler) {
-        this.confirmationHandler = handler;
+    setConfirmScripts(value) {
+        this.confirmScripts = value;
     }
     /**
-     * 订阅审计事件
-     * @returns 取消订阅函数
+     * 运行时设置「用户额外白名单」（宿主设置面板热更新）
+     *
+     * 仅操作额外项（extraRoots），基准信任根（baseRoots）永不被触碰——守住安全显式性：
+     * 项目目录、memora 数据目录、配置/数据目录始终允许访问，用户无法误删。
+     * 传空数组 = 清空额外项（仅留基准根，等价「重置」）。
+     * 黑名单（BLOCKED_PATTERNS）对新增路径仍强制生效——白名单是允许列表，非绕过黑名单的通行证。
      */
+    setAllowedPaths(extraPaths) {
+        if (!Array.isArray(extraPaths)) {
+            throw securityError('allowedPaths 必须为数组', 'setAllowedPaths 入参不是数组', [
+                '请传入字符串数组',
+            ]);
+        }
+        const normalized = [];
+        for (let i = 0; i < extraPaths.length && normalized.length < MAX_EXTRA_ALLOWED_PATHS; i++) {
+            const p = extraPaths[i];
+            if (typeof p !== 'string') {
+                throw securityError('allowedPaths 每项必须为字符串', `allowedPaths[${i}] 不是字符串`, [
+                    'allowedPaths 每项必须为字符串路径',
+                ]);
+            }
+            normalized.push(resolveRealpath(expandHome(p)));
+        }
+        this.extraRoots = normalized;
+        this.allowedRoots = [...this.baseRoots, ...this.extraRoots];
+    }
+    /** 订阅审计事件；@returns 取消订阅函数 */
     onAudit(listener) {
         this.listeners.push(listener);
         return () => {
@@ -168,20 +192,13 @@ export class SecurityGuard {
         };
     }
     /**
-     * 获取最近的审计事件（深拷贝，外部不可修改内部缓冲）
-     */
-    getRecentAudits(limit = 10) {
-        return this.auditBuffer.slice(-limit).map((e) => ({ ...e }));
-    }
-    /**
-     * 断言路径允许访问
-     * @throws Error 不在白名单时
-     * @param source 调用链来源标记
+     * 断言路径允许访问（命中即拒绝）；黑名单优先，其次白名单前缀匹配（追加 sep 防兄弟目录绕过）。
+     * @throws 不在白名单时
      */
     assertPathAllowed(absolutePath, tool, source) {
-        // NFKC 规范化，防止全角字符（如 ．．/）绕过黑名单正则
+        // NFKC 规范化，防全角字符（如 ．．/）绕过黑名单正则
         const normalized = absolutePath.normalize('NFKC');
-        // resolveRealpath 解析符号链接，防止通过项目内符号链接逃逸到系统目录
+        // 解析符号链接，防项目内符号链接逃逸到系统目录
         const resolved = resolveRealpath(normalized);
         // 1. 黑名单优先
         for (const pattern of BLOCKED_PATTERNS) {
@@ -197,7 +214,7 @@ export class SecurityGuard {
                 throw securityError('禁止访问：路径命中黑名单', `路径 ${resolved} 命中黑名单规则 (${pattern})`, ['检查路径是否正确', '如需访问该路径，请联系管理员添加白名单']);
             }
         }
-        // 2. 白名单：遍历所有允许的根目录（严格前缀匹配，追加 sep 防止兄弟目录绕过）
+        // 2. 白名单：严格前缀匹配（追加 sep 防兄弟目录绕过）
         for (const allowedRoot of this.allowedRoots) {
             if (resolved === allowedRoot || resolved.startsWith(allowedRoot + sep)) {
                 this.emitAudit({
@@ -224,25 +241,41 @@ export class SecurityGuard {
         ]);
     }
     /**
-     * 写入操作前请求用户确认
-     *
-     * 规则：
-     *   - guest 模式：始终要求确认
-     *   - owner + confirmWrites=true：要求确认
-     *   - owner + confirmWrites=false：自动批准
-     *
-     * 决策（fail-closed）：
-     *   - 需要确认时，必须通过 onWriteConfirmation() 注入 confirmationHandler
-     *   - 未注入 handler 时，**直接拒绝写入**（返回 false）
-     *   - 理由：内核纯逻辑库不应依赖交互式终端 I/O；宿主程序负责提供确认 UI
-     *   - 安全优先：未配置 = 拒绝，避免无意识放行
-     *
-     * @returns true 确认通过；false 用户拒绝或未注入 handler（fail-closed）
+     * 写入前请求用户确认。guest 或 confirmWrites 需确认；未注入 confirmationHandler 时 fail-closed 拒绝（返回 false），
+     * 理由：内核纯逻辑库不依赖交互式终端 I/O，宿主负责确认 UI；安全优先：未配置 = 拒绝。
      */
     async requestWriteConfirmation(targetPath, tool, description, 
-    /** diff 内容选项（供宿主 UI 展示变更预览，自动截断到 10KB） */
+    /** diff 内容选项（宿主 UI 变更预览用，自动截断到 10KB） */
     options) {
-        const needConfirm = this.permission === 'guest' || this.confirmWrites;
+        return this.confirmGate(targetPath, tool, description, 
+        // 写入确认判据：guest 或 confirmWrites
+        this.permission === 'guest' || this.confirmWrites, 
+        // diff 预览（仅写入场景有；脚本执行无内容预览）
+        {
+            beforeContent: truncateForDiff(options?.beforeContent),
+            afterContent: truncateForDiff(options?.afterContent),
+        });
+    }
+    /**
+     * 脚本/代码执行前确认（run_code / run_project_script 的执行闸）
+     *
+     * 判据与写入确认同构：guest 模式或 confirmScripts 需确认；未注入 confirmationHandler 时
+     * fail-closed 拒绝。owner + confirmScripts=false 自动批准（默认），审计仍记录。
+     * target 为脚本绝对路径（run_project_script）或描述型标识（run_code 内联代码无落盘路径）。
+     */
+    async confirmScriptRun(targetPath, tool, description) {
+        return this.confirmGate(targetPath, tool, description, 
+        // 脚本执行确认判据：guest 或 confirmScripts（独立于写入确认）
+        this.permission === 'guest' || this.confirmScripts);
+    }
+    /**
+     * 确认闸公共核心（SSOT：写入确认与脚本执行确认的唯一执行路径）
+     *
+     * needConfirm=false → 自动批准（审计 write-auto）；为 true 且未注入 confirmationHandler
+     * → fail-closed 拒绝（审计 write-decline）；否则经 confirmViaHandler 走宿主确认 UI。
+     * diff 仅写入场景有，脚本执行不传（域留空）。
+     */
+    async confirmGate(targetPath, tool, description, needConfirm, diff) {
         // 无需确认：直接放行并记录审计
         if (!needConfirm) {
             this.emitAudit({
@@ -254,19 +287,19 @@ export class SecurityGuard {
             });
             return true;
         }
-        // 构建确认信息（透传 diff 内容，供宿主 UI 展示变更预览）
+        // 构建确认信息（写入场景透传 diff 内容，供宿主 UI 展示变更预览）
         const info = {
             targetPath,
             tool,
             description,
             permission: this.permission,
             needsConfirm: needConfirm,
-            beforeContent: truncateForDiff(options?.beforeContent),
-            afterContent: truncateForDiff(options?.afterContent),
+            beforeContent: diff?.beforeContent,
+            afterContent: diff?.afterContent,
         };
         // 未注入 confirmationHandler 时 fail-closed 拒绝
         if (!this.confirmationHandler) {
-            logger.warn({ targetPath, tool, permission: this.permission }, '写入确认失败：未注入 confirmationHandler，fail-closed 拒绝写入');
+            logger.warn({ targetPath, tool, permission: this.permission }, '执行确认失败：未注入 confirmationHandler，fail-closed 拒绝');
             this.emitAudit({
                 type: 'write-decline',
                 path: targetPath,
@@ -281,13 +314,8 @@ export class SecurityGuard {
         return this.confirmViaHandler(info, targetPath, tool);
     }
     /**
-     * 通过宿主注入的 confirmationHandler 进行写入确认
-     *
-     * 从 requestWriteConfirmation 拆分。抛错视为拒绝（fail-closed 安全优先）。
-     * 此方法是唯一的确认执行路径。
-     *
-     * @param info 确认信息（含 diff 内容）
-     * @returns true 确认通过；false 用户拒绝或回调异常
+     * 通过宿主注入的 confirmationHandler 执行写入确认（唯一确认执行路径）。
+     * 抛错视为拒绝（fail-closed 安全优先）。
      */
     async confirmViaHandler(info, targetPath, tool) {
         try {
@@ -315,16 +343,8 @@ export class SecurityGuard {
             return false;
         }
     }
-    /**
-     * 触发审计事件 + 写入日志 + 通知订阅者
-     */
+    /** 触发审计事件：写日志 + 通知订阅者 */
     emitAudit(event) {
-        // 缓冲
-        this.auditBuffer.push(event);
-        if (this.auditBuffer.length > this.bufferLimit) {
-            this.auditBuffer.shift();
-        }
-        // 写到 pino（结构化日志，方便后续检索）
         if (event.type === 'path-deny' || event.type === 'write-decline') {
             logger.warn({ audit: event }, '安全审计：拒绝');
         }