@goodandready/dsh-approval-gate 0.1.20 → 0.1.21

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.21
+
+- Feature: Автоматические легковесные пре-снимки файлов (`Pre-execution Snapshots` в `lib/snapshots.js`) перед выполнением мутирующих инструментов с отслеживанием размера и FIFO-вытеснением по сессиям (Refs: #77).
+- Feature: Однократный откат изменений (`Undo this change` / `rollbackSnapshot`) из сохраненного пре-снимка с восстановлением исходного контента или удалением созданного файла (Refs: #76).
+- Feature: Двухуровневая очистка файловых снимков (`clearSnapshots` для безопасной очистки текущей сессии без влияния на соседние диалоги vs `clearAllSnapshots` для глобального сброса) (Refs: #78).
+- Feature: Многоуровневая категоризация масштаба влияния операций (`Measure Kinds` в `lib/measure-kinds.js`: `local-single`, `workspace-wide`, `system-level`) с обогащением вердикта и фиксацией в аудите (Refs: #97).
+- Security: Завершение перехода #163 — перевод конфигурации по умолчанию в строгий fail-closed режим (`defaultVerdict: 'ask'`) для неизвестных команд оболочки (Refs: #172).
+
 ## 0.1.20
 
 - Feature: Безопасная альтернатива необратимому удалению (`Reversible Trash Move` в `lib/trash.js`) с переносом удаляемых файлов в изолированную сессионную корзину `<workspace>/.dsh/trash/<session_id>/` вместо деструктивного `rm` (Refs: #104).

package/lib/bands.js

@@ -1,239 +1,243 @@
-// lib/bands.js
-// Two-band deterministic filtering engine for dsh-approval-gate.
-// Band 0: Hard Deny (fast regexes for exfiltration, fork-bombs, disk wipes)
-// Band 1: Safe Allow (prefix globs & curated safe read-only inspection commands and tools)
-
-export const DEFAULT_DENY_PATTERNS = Object.freeze([
-  /\b(?:nc|ncat|netcat)\s+.*-e\s+/i,
-  /\/dev\/tcp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
-  /\/dev\/udp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
-  /\bmkfs(?:\.[a-z0-9]+)?\s+/i,
-  /\bdd\s+.*of=\/dev\/(?:sd|hd|vd|xvd|nvme|mmcblk|loop|mapper)/i,
-  /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/,
-  /\bchmod\s+(?:-R\s+)?(?:0?777|a\+rwx)\s+\/(?!tmp)/i,
-  /\bchown\s+(?:-R\s+)?root\b/i,
-  /\b(?:shutdown|reboot|poweroff|halt)\s*(?:-|$)/i,
-]);
-
-export const DEFAULT_ALLOW_GLOBS = Object.freeze([
-  // Git inspection commands
-  "git status*",
-  "git diff*",
-  "git log*",
-  "git branch*",
-  "git show*",
-  "git remote*",
-  "git tag*",
-  "git rev-parse*",
-
-  // File viewing & analysis
-  "cat *",
-  "head *",
-  "tail *",
-  "more *",
-  "less *",
-  "wc *",
-  "file *",
-  "stat *",
-  "diff *",
-
-  // Search & finding
-  "grep *",
-  "fgrep *",
-  "egrep *",
-  "rg *",
-  "ag *",
-  "find *",
-
-  // Directory listing & environment info
-  "ls*",
-  "dir*",
-  "pwd*",
-  "which *",
-  "whereis *",
-  "whoami*",
-  "hostname*",
-  "uname*",
-  "date*",
-  "uptime*",
-  "echo *",
-  "printf *",
-
-  // Language / runtime versions & test runners
-  "node --version*",
-  "node -v*",
-  "npm test*",
-  "npm --version*",
-  "npm -v*",
-  "pnpm test*",
-  "pnpm --version*",
-  "pnpm -v*",
-  "yarn test*",
-  "cargo test*",
-  "cargo check*",
-  "cargo --version*",
-  "pytest*",
-  "python --version*",
-  "python3 --version*",
-]);
-
-export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
-  "read",
-  "read_file",
-  "readFile",
-  "read_file_content",
-  "view_file",
-  "view",
-  "show",
-  "glob",
-  "grep",
-  "find_files",
-  "find_by_name",
-  "search_code",
-  "file_search",
-  "list_dir",
-  "list_directory",
-  "directory_list",
-  "tree",
-  "read_url_content",
-  "fetch_web_page",
-  "web_search",
-  "search_web",
-  "list_resources",
-  "read_resource",
-]);
-
-/**
- * Compile a prefix-glob into an anchored RegExp.
- * @param {string} pattern
- * @returns {RegExp}
- */
-export function compileGlob(pattern) {
-  let source = "";
-  for (const ch of pattern) {
-    if (ch === "*") source += ".*";
-    else if (ch === "?") source += ".";
-    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-  }
-  return new RegExp(`^${source}$`, "i");
-}
-
-export class BandsEngine {
-  /**
-   * @param {{
-   *   denyPatterns?: Array<RegExp|string>,
-   *   allowGlobs?: Array<RegExp|string>,
-   *   readOnlyTools?: Array<string>
-   * }} [options]
-   */
-  constructor(options = {}) {
-    this.denyPatterns = (options.denyPatterns || DEFAULT_DENY_PATTERNS).map((p) =>
-      typeof p === "string" ? new RegExp(p, "i") : p
-    );
-    this.allowGlobs = (options.allowGlobs || DEFAULT_ALLOW_GLOBS).map((g) =>
-      typeof g === "string" ? compileGlob(g) : g
-    );
-    this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
-
-    // Derive read-only tools dynamically from host tool registry if provided (#156)
-    if (options.toolRegistry) {
-      try {
-        const tools = typeof options.toolRegistry.getTools === "function"
-          ? options.toolRegistry.getTools()
-          : (Array.isArray(options.toolRegistry) ? options.toolRegistry : []);
-        for (const t of tools) {
-          if (t && (t.readOnly || t.readonly || t.isReadOnly) && typeof t.name === "string") {
-            this.readOnlyTools.add(t.name);
-          }
-        }
-      } catch {
-        // ignore
-      }
-    }
-  }
-
-  /**
-   * Check if a tool is configured as an unconditional read-only tool.
-   * @param {string} tool
-   * @returns {boolean}
-   */
-  isReadOnlyTool(tool) {
-    return typeof tool === "string" && this.readOnlyTools.has(tool.trim());
-  }
-
-  /**
-   * Check if a command matches safe inspection patterns.
-   * @param {string} command
-   * @returns {boolean}
-   */
-  isSafeInspectionCommand(command) {
-    if (typeof command !== "string" || command.trim() === "") return false;
-    const text = command.trim();
-    // Chained commands, subshells, substitutions, and redirections cannot match whole-string safe-allow
-    if (/[\n;&|`<>]|\$\([\s\S]*\)|\$\{[\s\S]*\}/.test(text)) {
-      return false;
-    }
-    for (const pattern of this.denyPatterns) {
-      if (pattern.test(text)) return false;
-    }
-    for (const glob of this.allowGlobs) {
-      if (glob.test(text)) return true;
-    }
-    return false;
-  }
-
-  /**
-   * Register an additional read-only tool name.
-   * @param {string} tool
-   */
-  addReadOnlyTool(tool) {
-    if (typeof tool === "string" && tool.trim()) {
-      this.readOnlyTools.add(tool.trim());
-    }
-  }
-
-  /**
-   * Register an additional allow-glob pattern.
-   * @param {string} globPattern
-   */
-  addAllowGlob(globPattern) {
-    if (typeof globPattern === "string" && globPattern.trim()) {
-      this.allowGlobs.push(compileGlob(globPattern.trim()));
-    }
-  }
-
-  /**
-   * Evaluates an execution request through Band 0 and Band 1.
-   * @param {string} tool - Tool name
-   * @param {string} [command] - Normalized command text (for bash)
-   * @returns {"deny" | "allow" | "unmatched"}
-   */
-  evaluate(tool, command) {
-    if (this.isReadOnlyTool(tool)) {
-      return "allow";
-    }
-
-    if (typeof command === "string" && command.trim().length > 0) {
-      const text = command.trim();
-
-      // Band 0: Hard Deny
-      for (const pattern of this.denyPatterns) {
-        if (pattern.test(text)) {
-          return "deny";
-        }
-      }
-
-      // Band 1: Safe Allow (applies strictly to single commands without chaining, subshells or redirects)
-      if (!/[\n;&|`<>]|\$\([\s\S]*\)|\$\{[\s\S]*\}/.test(text)) {
-        for (const glob of this.allowGlobs) {
-          if (glob.test(text)) {
-            return "allow";
-          }
-        }
-      }
-    }
-
-    return "unmatched";
-  }
-}
-
+// lib/bands.js
+// Two-band deterministic filtering engine for dsh-approval-gate.
+// Band 0: Hard Deny (fast regexes for exfiltration, fork-bombs, disk wipes)
+// Band 1: Safe Allow (prefix globs & curated safe read-only inspection commands and tools)
+
+export const DEFAULT_DENY_PATTERNS = Object.freeze([
+  /\b(?:nc|ncat|netcat)\s+.*-e\s+/i,
+  /\/dev\/tcp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
+  /\/dev\/udp\/\d+\.\d+\.\d+\.\d+\/\d+/i,
+  /\bmkfs(?:\.[a-z0-9]+)?\s+/i,
+  /\bdd\s+.*of=\/dev\/(?:sd|hd|vd|xvd|nvme|mmcblk|loop|mapper)/i,
+  /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/,
+  /\bchmod\s+(?:-R\s+)?(?:0?777|a\+rwx)\s+\/(?!tmp)/i,
+  /\bchown\s+(?:-R\s+)?root\b/i,
+  /\b(?:shutdown|reboot|poweroff|halt)\s*(?:-|$)/i,
+]);
+
+export const DEFAULT_ALLOW_GLOBS = Object.freeze([
+  // Git inspection commands
+  "git status*",
+  "git diff*",
+  "git log*",
+  "git branch*",
+  "git show*",
+  "git remote*",
+  "git tag*",
+  "git rev-parse*",
+
+  // File viewing & analysis
+  "cat *",
+  "head *",
+  "tail *",
+  "more *",
+  "less *",
+  "wc *",
+  "file *",
+  "stat *",
+  "diff *",
+
+  // Search & finding
+  "grep *",
+  "fgrep *",
+  "egrep *",
+  "rg *",
+  "ag *",
+  "find *",
+
+  // Directory listing & environment info
+  "ls*",
+  "dir*",
+  "pwd*",
+  "which *",
+  "whereis *",
+  "whoami*",
+  "hostname*",
+  "uname*",
+  "date*",
+  "uptime*",
+  "echo *",
+  "printf *",
+
+  // Language / runtime versions & test runners
+  "node --version*",
+  "node -v*",
+  "npm test*",
+  "npm --version*",
+  "npm -v*",
+  "pnpm test*",
+  "pnpm --version*",
+  "pnpm -v*",
+  "yarn test*",
+  "cargo test*",
+  "cargo check*",
+  "cargo --version*",
+  "pytest*",
+  "python --version*",
+  "python3 --version*",
+
+  // Service status inspection
+  "systemctl is-active*",
+  "systemctl status*",
+]);
+
+export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
+  "read",
+  "read_file",
+  "readFile",
+  "read_file_content",
+  "view_file",
+  "view",
+  "show",
+  "glob",
+  "grep",
+  "find_files",
+  "find_by_name",
+  "search_code",
+  "file_search",
+  "list_dir",
+  "list_directory",
+  "directory_list",
+  "tree",
+  "read_url_content",
+  "fetch_web_page",
+  "web_search",
+  "search_web",
+  "list_resources",
+  "read_resource",
+]);
+
+/**
+ * Compile a prefix-glob into an anchored RegExp.
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+export function compileGlob(pattern) {
+  let source = "";
+  for (const ch of pattern) {
+    if (ch === "*") source += ".*";
+    else if (ch === "?") source += ".";
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`, "i");
+}
+
+export class BandsEngine {
+  /**
+   * @param {{
+   *   denyPatterns?: Array<RegExp|string>,
+   *   allowGlobs?: Array<RegExp|string>,
+   *   readOnlyTools?: Array<string>
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.denyPatterns = (options.denyPatterns || DEFAULT_DENY_PATTERNS).map((p) =>
+      typeof p === "string" ? new RegExp(p, "i") : p
+    );
+    this.allowGlobs = (options.allowGlobs || DEFAULT_ALLOW_GLOBS).map((g) =>
+      typeof g === "string" ? compileGlob(g) : g
+    );
+    this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
+
+    // Derive read-only tools dynamically from host tool registry if provided (#156)
+    if (options.toolRegistry) {
+      try {
+        const tools = typeof options.toolRegistry.getTools === "function"
+          ? options.toolRegistry.getTools()
+          : (Array.isArray(options.toolRegistry) ? options.toolRegistry : []);
+        for (const t of tools) {
+          if (t && (t.readOnly || t.readonly || t.isReadOnly) && typeof t.name === "string") {
+            this.readOnlyTools.add(t.name);
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  /**
+   * Check if a tool is configured as an unconditional read-only tool.
+   * @param {string} tool
+   * @returns {boolean}
+   */
+  isReadOnlyTool(tool) {
+    return typeof tool === "string" && this.readOnlyTools.has(tool.trim());
+  }
+
+  /**
+   * Check if a command matches safe inspection patterns.
+   * @param {string} command
+   * @returns {boolean}
+   */
+  isSafeInspectionCommand(command) {
+    if (typeof command !== "string" || command.trim() === "") return false;
+    const text = command.trim();
+    // Chained commands, subshells, substitutions, and redirections cannot match whole-string safe-allow
+    if (/[\n;&|`<>]|\$\([\s\S]*\)|\$\{[\s\S]*\}/.test(text)) {
+      return false;
+    }
+    for (const pattern of this.denyPatterns) {
+      if (pattern.test(text)) return false;
+    }
+    for (const glob of this.allowGlobs) {
+      if (glob.test(text)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Register an additional read-only tool name.
+   * @param {string} tool
+   */
+  addReadOnlyTool(tool) {
+    if (typeof tool === "string" && tool.trim()) {
+      this.readOnlyTools.add(tool.trim());
+    }
+  }
+
+  /**
+   * Register an additional allow-glob pattern.
+   * @param {string} globPattern
+   */
+  addAllowGlob(globPattern) {
+    if (typeof globPattern === "string" && globPattern.trim()) {
+      this.allowGlobs.push(compileGlob(globPattern.trim()));
+    }
+  }
+
+  /**
+   * Evaluates an execution request through Band 0 and Band 1.
+   * @param {string} tool - Tool name
+   * @param {string} [command] - Normalized command text (for bash)
+   * @returns {"deny" | "allow" | "unmatched"}
+   */
+  evaluate(tool, command) {
+    if (this.isReadOnlyTool(tool)) {
+      return "allow";
+    }
+
+    if (typeof command === "string" && command.trim().length > 0) {
+      const text = command.trim();
+
+      // Band 0: Hard Deny
+      for (const pattern of this.denyPatterns) {
+        if (pattern.test(text)) {
+          return "deny";
+        }
+      }
+
+      // Band 1: Safe Allow (applies strictly to single commands without chaining, subshells or redirects)
+      if (!/[\n;&|`<>]|\$\([\s\S]*\)|\$\{[\s\S]*\}/.test(text)) {
+        for (const glob of this.allowGlobs) {
+          if (glob.test(text)) {
+            return "allow";
+          }
+        }
+      }
+    }
+
+    return "unmatched";
+  }
+}
+

package/lib/engine.js

@@ -13,13 +13,15 @@ import { DeclarativeRulesEngine } from "./rules-loader.js";
 import { BlockCounters } from "./counters.js";
 import { ContractGuard } from "./contract-guard.js";
 import { OverengineeringGuard } from "./overengineering.js";
-import { extractFilePath, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
+import { extractFilePath, DEFAULT_BASH_TOOL, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
 import { categorizeRiskBucket, extractRiskTags } from "./risk.js";
 import { ClassifierLatencyTracker } from "./latency.js";
 import { ArtifactRegistry } from "./artifacts.js";
 import { isRmCommand, extractRmTargets, suggestTrashAlternative } from "./trash.js";
 import { VersionGuard } from "./version-guard.js";
 import { loadAgentsRules, evaluateAgentsRules } from "./agents-parser.js";
+import { classifyMeasureKind } from "./measure-kinds.js";
+import { SnapshotManager } from "./snapshots.js";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -79,7 +81,7 @@ export class SecurityEngine {
     this.classifier = options.classifier || null;
     this.timeoutPolicy = options.timeoutPolicy === "permissive" ? "permissive" : "strict";
     this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
-    this.defaultVerdict = options.defaultVerdict || "allow";
+    this.defaultVerdict = options.defaultVerdict || "ask";
 
     this.dryRun = Boolean(options.dryRun || options.shadowMode);
     this.auditFailClosed = options.auditFailClosed === true;
@@ -87,33 +89,16 @@ export class SecurityEngine {
     this.retryGuard = options.retryGuard !== undefined ? options.retryGuard : new RetryExhaustionGuard();
     this.ledger = options.ledger !== undefined ? options.ledger : new QualityLedger();
     this.counters = options.counters || new BlockCounters();
-    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger({
-      failClosed: this.auditFailClosed,
-    });
-    if (this.auditFailClosed && this.auditLogger) {
-      this.auditLogger.failClosed = true;
-    }
-    this.declarativeRules = options.declarativeRules || new DeclarativeRulesEngine({
-      workspaceDir: this.inspectConfig?.workspaceDir,
-    });
-    this.contractGuard = options.contractGuard !== undefined
-      ? options.contractGuard
-      : (options.taskContract ? new ContractGuard(options.taskContract) : null);
-    this.overengineeringGuard = options.overengineeringGuard !== undefined
-      ? options.overengineeringGuard
-      : (options.maxFilesPerSession !== undefined || options.maxCreatedFilesPerSession !== undefined
-          ? new OverengineeringGuard(options)
-          : null);
+    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger({ failClosed: this.auditFailClosed });
+    if (this.auditFailClosed && this.auditLogger) this.auditLogger.failClosed = true;
+    this.declarativeRules = options.declarativeRules || new DeclarativeRulesEngine({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.contractGuard = options.contractGuard !== undefined ? options.contractGuard : (options.taskContract ? new ContractGuard(options.taskContract) : null);
+    this.overengineeringGuard = options.overengineeringGuard !== undefined ? options.overengineeringGuard : (options.maxFilesPerSession !== undefined || options.maxCreatedFilesPerSession !== undefined ? new OverengineeringGuard(options) : null);
     this.latencyTracker = options.latencyTracker || new ClassifierLatencyTracker(options);
-    this.artifactRegistry = options.artifactRegistry !== undefined
-      ? options.artifactRegistry
-      : new ArtifactRegistry({ workspaceDir: this.inspectConfig?.workspaceDir });
-    this.versionGuard = options.versionGuard !== undefined
-      ? options.versionGuard
-      : new VersionGuard({ workspaceDir: this.inspectConfig?.workspaceDir });
-    this.agentsRules = options.agentsRules !== undefined
-      ? options.agentsRules
-      : (loadAgentsRules(this.inspectConfig?.workspaceDir)?.rules || null);
+    this.artifactRegistry = options.artifactRegistry !== undefined ? options.artifactRegistry : new ArtifactRegistry({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.versionGuard = options.versionGuard !== undefined ? options.versionGuard : new VersionGuard({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.agentsRules = options.agentsRules !== undefined ? options.agentsRules : (loadAgentsRules(this.inspectConfig?.workspaceDir)?.rules || null);
+    this.snapshotManager = options.snapshotManager !== undefined ? options.snapshotManager : new SnapshotManager({ workspaceDir: this.inspectConfig?.workspaceDir });
   }
 
   /**
@@ -493,8 +478,10 @@ export class SecurityEngine {
       }
     }
 
-    // Default verdict for unclassified commands (#163)
-    if (this.defaultVerdict === "ask") {
+    // Default verdict for unclassified commands (#163, #172)
+    const bashTool = this.inspectConfig?.toolName || DEFAULT_BASH_TOOL;
+    const isBashTool = toolName === bashTool || !toolName;
+    if (isBashTool && this.defaultVerdict === "ask") {
       const askHit = { ask: true, reason: "unmatched-ask", snippet: command || toolName };
       const res = { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
       this._applyLockedAskIfCritical(res, toolName, command, execution);
@@ -566,6 +553,7 @@ export class SecurityEngine {
     if (!decision) return decision;
     if (!decision.riskBucket) decision.riskBucket = categorizeRiskBucket(execution, context);
     if (!decision.riskTags || !Array.isArray(decision.riskTags)) decision.riskTags = extractRiskTags(execution, context);
+    if (!decision.measureKind) decision.measureKind = classifyMeasureKind(execution, context);
     const command = execution && execution.arguments && execution.arguments.command;
     if (command && isRmCommand(command)) {
       decision.trashAlternative = suggestTrashAlternative(command, this.inspectConfig?.workspaceDir, context?.sessionId);
@@ -573,21 +561,15 @@ export class SecurityEngine {
     return decision;
   }
 
-  getArtifacts(sessionId) {
-    return this.artifactRegistry ? this.artifactRegistry.getArtifacts(sessionId) : [];
-  }
-
-  clearArtifacts(sessionId) {
-    if (this.artifactRegistry) this.artifactRegistry.clearSession(sessionId);
-  }
-
-  getLatencyMetrics() {
-    return this.latencyTracker ? this.latencyTracker.getMetrics() : null;
-  }
-
-  resetLatencyTracker() {
-    if (this.latencyTracker) this.latencyTracker.reset();
-  }
+  getArtifacts(sessionId) { return this.artifactRegistry ? this.artifactRegistry.getArtifacts(sessionId) : []; }
+  clearArtifacts(sessionId) { if (this.artifactRegistry) this.artifactRegistry.clearSession(sessionId); }
+  getLatencyMetrics() { return this.latencyTracker ? this.latencyTracker.getMetrics() : null; }
+  resetLatencyTracker() { if (this.latencyTracker) this.latencyTracker.reset(); }
+  takeSnapshot(targetPath, meta) { return this.snapshotManager ? this.snapshotManager.takeSnapshot(targetPath, meta) : null; }
+  rollbackSnapshot(id) { return this.snapshotManager ? this.snapshotManager.rollbackSnapshot(id) : { success: false, error: "no-snapshot-manager" }; }
+  getSnapshots(sessionId) { return this.snapshotManager ? this.snapshotManager.getSnapshots(sessionId) : []; }
+  clearSnapshots(sessionId) { return this.snapshotManager ? this.snapshotManager.clearSnapshots(sessionId) : { cleared: 0 }; }
+  clearAllSnapshots() { return this.snapshotManager ? this.snapshotManager.clearAllSnapshots() : { cleared: 0 }; }
 }
 
 

package/lib/index.js

@@ -5,6 +5,9 @@ import { DeclarativeRulesEngine } from "./rules-loader.js";
 import { LlmClassifier } from "./classifier.js";
 import { ClassifierLatencyTracker } from "./latency.js";
 import { assertHarnessCompatibility, provideServicePolyfill } from "./compat.js";
+import { extractFilePath } from "./dispatcher.js";
+import { SnapshotManager } from "./snapshots.js";
+import { MEASURE_KINDS, classifyMeasureKind } from "./measure-kinds.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -208,8 +211,12 @@ export const Config = Schema.object({
   unattended: Schema.boolean().default(false).volatile(),
   /** Workspace directory for path traversal boundary checks. */
   workspaceDir: Schema.string().default("").volatile(),
-  /** Default verdict for unclassified commands: 'allow' (default) or 'ask' (fail-closed) (#163). */
-  defaultVerdict: Schema.union(["allow", "ask"]).default("allow").volatile(),
+  /** Default verdict for unclassified commands: 'ask' (default, fail-closed) or 'allow' (#163, #172). */
+  defaultVerdict: Schema.union(["allow", "ask"]).default("ask").volatile(),
+  /** Maximum retained file snapshots per session (#78). */
+  maxSnapshotsPerSession: Schema.number().default(50).volatile(),
+  /** Maximum file size in bytes for pre-execution snapshots (#77). */
+  maxSnapshotBytes: Schema.number().default(1048576).volatile(),
   /** Dry-run / shadow mode for safe testing of rules on production (#128). */
   dryRun: Schema.boolean().default(false).volatile(),
   /** Shadow mode alias for dryRun (#128). */
@@ -313,7 +320,8 @@ export function apply(ctx, config) {
     latencyTracker: new ClassifierLatencyTracker({
       slaMs: cfg.classifierSlaMs !== undefined ? cfg.classifierSlaMs : 2000,
     }),
-    defaultVerdict: cfg.defaultVerdict || "allow",
+    defaultVerdict: cfg.defaultVerdict || "ask",
+    snapshotManager: new SnapshotManager({ workspaceDir: cfg.workspaceDir || "", maxSnapshotsPerSession: cfg.maxSnapshotsPerSession, maxSnapshotBytes: cfg.maxSnapshotBytes }),
     dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
     auditFailClosed: Boolean(cfg.auditFailClosed),
     auditLogger: new AuditLogger({
@@ -342,6 +350,12 @@ export function apply(ctx, config) {
     resetLatencyTracker: () => (engine.resetLatencyTracker ? engine.resetLatencyTracker() : undefined),
     getArtifacts: (sessionId) => (engine.getArtifacts ? engine.getArtifacts(sessionId) : []),
     clearArtifacts: (sessionId) => (engine.clearArtifacts ? engine.clearArtifacts(sessionId) : undefined),
+    takeSnapshot: (targetPath, meta) => (engine.takeSnapshot ? engine.takeSnapshot(targetPath, meta) : null),
+    rollbackSnapshot: (id) => (engine.rollbackSnapshot ? engine.rollbackSnapshot(id) : { success: false, error: "no-engine" }),
+    getSnapshots: (sessionId) => (engine.getSnapshots ? engine.getSnapshots(sessionId) : []),
+    clearSnapshots: (sessionId) => (engine.clearSnapshots ? engine.clearSnapshots(sessionId) : { cleared: 0 }),
+    clearAllSnapshots: () => (engine.clearAllSnapshots ? engine.clearAllSnapshots() : { cleared: 0 }),
+    getSnapshotStats: () => (engine.snapshotManager ? engine.snapshotManager.getStats() : null),
     getSnapshot: () => ({
       active: true,
       dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
@@ -353,6 +367,7 @@ export function apply(ctx, config) {
       cacheStats: engine.cache ? engine.cache.stats() : null,
       breakerState: engine.breaker ? engine.breaker.getState() : null,
       latencyMetrics: engine.getLatencyMetrics ? engine.getLatencyMetrics() : null,
+      snapshots: engine.snapshotManager ? engine.snapshotManager.getStats() : null,
       harnessCompat: compat.capabilities,
     }),
   };
@@ -418,6 +433,10 @@ export function apply(ctx, config) {
         };
         return { kind: "ask", reason: askMessage(hit, who, translate, ctx && ctx.logger) };
       }
+      if (engine.snapshotManager) {
+        const targetPath = extractFilePath(execution && execution.arguments);
+        if (targetPath) engine.takeSnapshot(targetPath, { sessionId, callId: execution && (execution.callId || execution.id), tool: execution && execution.name });
+      }
       return next();
     });
   }
@@ -455,6 +474,10 @@ export function apply(ctx, config) {
       logBlocked(ctx, hit, who);
       return denyMessage(hit, who, translate, ctx && ctx.logger);
     }
+    if (engine.snapshotManager) {
+      const targetPath = extractFilePath(execution && execution.arguments);
+      if (targetPath) engine.takeSnapshot(targetPath, { sessionId, callId: execution && (execution.callId || execution.id), tool: execution && execution.name });
+    }
     return undefined;
   };
 
@@ -476,96 +499,27 @@ export {
   CIRCUIT_STATE_TRIPPED,
   CIRCUIT_STATE_RESUMED,
 } from "./breaker.js";
-export {
-  SessionGrantStore,
-  DEFAULT_GRANT_TTL_MS,
-  DEFAULT_GRANT_MAX_USES,
-  matchGrantCriteria,
-} from "./grants.js";
-export {
-  canonicalizeCall,
-  canonicalString,
-  hashCall,
-  sortKeys,
-} from "./canonical.js";
+export { SessionGrantStore, DEFAULT_GRANT_TTL_MS, DEFAULT_GRANT_MAX_USES, matchGrantCriteria } from "./grants.js";
+export { canonicalizeCall, canonicalString, hashCall, sortKeys } from "./canonical.js";
 export { expandHome, resolveSafePath, isPathTraversal, canonicalizeFsPath } from "./paths.js";
 export { splitSubcommands } from "./tokenizer.js";
 export { redactCredentials, redactUrl } from "./redact.js";
-export {
-  CommandDispatcher,
-  isReviewerAgent,
-  extractFilePath,
-  TOOL_KIND_SHELL,
-  TOOL_KIND_FILE_WRITE,
-  TOOL_KIND_FILE_READ,
-  TOOL_KIND_NETWORK,
-  TOOL_KIND_GENERIC,
-} from "./dispatcher.js";
-export {
-  parseGitArgv,
-  classifyGitOperation,
-  inspectGitCommand,
-  GIT_CATEGORY_READ,
-  GIT_CATEGORY_MUTATE_LOCAL,
-  GIT_CATEGORY_REMOTE,
-  GIT_CATEGORY_DESTRUCTIVE,
-} from "./parsers/git.js";
-export {
-  isDevicePath,
-  extractRedirects,
-  inspectRedirectSecurity,
-  inspectSilentErrors,
-  inspectPipelines,
-} from "./parsers/shell-cmds.js";
-export {
-  isLoopbackHost,
-  isLoopbackUrl,
-  isLoopbackCommand,
-} from "./loopback.js";
-export {
-  computeFingerprint,
-  computeFingerprintHash,
-  normalizeCommandString,
-} from "./fingerprint.js";
-export {
-  VerdictCache,
-  DEFAULT_CACHE_MAX_SIZE,
-  DEFAULT_CACHE_TTL_MS,
-} from "./cache.js";
-export {
-  RetryExhaustionGuard,
-  DEFAULT_MAX_RETRY_ATTEMPTS,
-} from "./retry-exhaustion.js";
-export {
-  QualityLedger,
-  MAX_LEDGER_EVENTS_PER_SESSION,
-} from "./ledger.js";
-export {
-  AuditLogger,
-  DEFAULT_AUDIT_LOG_RELATIVE,
-  DEFAULT_MAX_AUDIT_BYTES,
-  DEFAULT_MAX_AUDIT_LINES,
-  DEFAULT_RETAIN_LINES,
-  auditRotateContent,
-} from "./audit-log.js";
+export { CommandDispatcher, isReviewerAgent, extractFilePath, TOOL_KIND_SHELL, TOOL_KIND_FILE_WRITE, TOOL_KIND_FILE_READ, TOOL_KIND_NETWORK, TOOL_KIND_GENERIC } from "./dispatcher.js";
+export { parseGitArgv, classifyGitOperation, inspectGitCommand, GIT_CATEGORY_READ, GIT_CATEGORY_MUTATE_LOCAL, GIT_CATEGORY_REMOTE, GIT_CATEGORY_DESTRUCTIVE } from "./parsers/git.js";
+export { isDevicePath, extractRedirects, inspectRedirectSecurity, inspectSilentErrors, inspectPipelines } from "./parsers/shell-cmds.js";
+export { isLoopbackHost, isLoopbackUrl, isLoopbackCommand } from "./loopback.js";
+export { computeFingerprint, computeFingerprintHash, normalizeCommandString } from "./fingerprint.js";
+export { VerdictCache, DEFAULT_CACHE_MAX_SIZE, DEFAULT_CACHE_TTL_MS } from "./cache.js";
+export { RetryExhaustionGuard, DEFAULT_MAX_RETRY_ATTEMPTS } from "./retry-exhaustion.js";
+export { QualityLedger, MAX_LEDGER_EVENTS_PER_SESSION } from "./ledger.js";
+export { AuditLogger, DEFAULT_AUDIT_LOG_RELATIVE, DEFAULT_MAX_AUDIT_BYTES, DEFAULT_MAX_AUDIT_LINES, DEFAULT_RETAIN_LINES, auditRotateContent } from "./audit-log.js";
 export { BlockCounters, categorizeReason } from "./counters.js";
 export { isCriticalOperation } from "./engine.js";
 export { parseYaml, parseScalar, stripComment } from "./yaml-parser.js";
 export { matchConditionValue, evaluateWhen } from "./when-matcher.js";
 export { HotwordsMatcher, DEFAULT_HOTWORDS, extractWords } from "./hotwords.js";
 export { DeclarativeRulesEngine, BUILTIN_RULES_FILE, WORKSPACE_RULES_REL, USER_RULES_REL } from "./rules-loader.js";
-export {
-  normalizeChatCompletionsUrl,
-  withLlmRetry,
-  sanitizeClassifierInput,
-  truncateClassifierContext,
-  isLowRiskExecution,
-  isShapeRejectError,
-  extractJsonPayload,
-  ClassifierVerdictSchema,
-  validateClassifierResponse,
-  LlmClassifier,
-} from "./classifier.js";
+export { normalizeChatCompletionsUrl, withLlmRetry, sanitizeClassifierInput, truncateClassifierContext, isLowRiskExecution, isShapeRejectError, extractJsonPayload, ClassifierVerdictSchema, validateClassifierResponse, LlmClassifier } from "./classifier.js";
 export { ContractGuard } from "./contract-guard.js";
 export { OverengineeringGuard, DEFAULT_MAX_FILES_PER_SESSION } from "./overengineering.js";
 export { resolveTempRoot, isGlobalTempPath, checkTempIsolation } from "./paths.js";
@@ -577,5 +531,8 @@ export { ArtifactRegistry, normalizeArtifactPath } from "./artifacts.js";
 export { parseAgentsSecurityRules, loadAgentsRules, evaluateAgentsRules } from "./agents-parser.js";
 export { detectHarnessCapabilities, assertHarnessCompatibility, provideServicePolyfill, registerHookPolyfill } from "./compat.js";
 export { parseSemver, isMajorBump, inspectPackageJsonDiff, VersionGuard } from "./version-guard.js";
+export { SnapshotManager, DEFAULT_MAX_SNAPSHOTS_PER_SESSION, DEFAULT_MAX_SNAPSHOT_BYTES } from "./snapshots.js";
+export { MEASURE_KINDS, classifyMeasureKind, isSystemLevelExecution, isWorkspaceWideExecution } from "./measure-kinds.js";
+
 
 

package/lib/measure-kinds.js

@@ -0,0 +1,135 @@
+// lib/measure-kinds.js
+// Multi-level operational impact scale categorization (#97).
+// Classifies execution into:
+// - 'local-single': operation affects exactly one file or inspects local state
+// - 'workspace-wide': operation affects the entire workspace/repository or multiple files
+// - 'system-level': operation accesses or mutates OS-level, network, or environment state
+
+export const MEASURE_KINDS = Object.freeze({
+  LOCAL_SINGLE: "local-single",
+  WORKSPACE_WIDE: "workspace-wide",
+  SYSTEM_LEVEL: "system-level",
+});
+
+const SYSTEM_BINARIES = new Set([
+  "sudo", "su", "doas",
+  "systemctl", "service", "journalctl", "init",
+  "apt", "apt-get", "dpkg", "apk", "dnf", "yum", "pacman", "zypper",
+  "curl", "wget", "nc", "netcat", "ncat", "telnet", "ssh", "scp", "sftp", "rsync",
+  "iptables", "nftables", "ufw", "firewall-cmd",
+  "crontab", "at",
+  "reboot", "shutdown", "poweroff", "halt",
+  "mount", "umount", "fdisk", "parted", "mkfs", "dd",
+  "insmod", "rmmod", "modprobe",
+  "docker", "podman", "containerd", "runc", "crictl", "kubectl",
+  "passwd", "useradd", "userdel", "usermod", "groupadd",
+  "kill", "killall", "pkill", "xkill",
+]);
+
+const SYSTEM_PATH_REGEX = /((\/|\b)(etc|boot|sys|proc|dev|usr|var\/log|root)(\/|\b)|~?\/\.(ssh|gnupg|bashrc|zshrc|profile)(\/|\b))/i;
+
+const WORKSPACE_COMMAND_PATTERNS = [
+  /^(npm|pnpm|yarn|bun)\s+(install|add|remove|uninstall|update|upgrade|ci|build|pack|publish|run)/i,
+  /^(cargo|go|dotnet|mvn|gradle)\s+(build|test|clean|install|run)/i,
+  /^git\s+(checkout|switch|merge|rebase|pull|push|reset|clean|branch|tag|stash|restore|clone)/i,
+  /^(find|grep|ripgrep|rg|ack|ag)\s+/i,
+  /\b(make|ninja|cmake|meson)\b/i,
+];
+
+const SINGLE_FILE_TOOLS = new Set([
+  "view_file", "read_file", "view",
+  "write_to_file", "create_file", "write",
+  "replace_file_content", "edit_file", "patch_file",
+  "inspect_file",
+]);
+
+const SYSTEM_LEVEL_TOOLS = new Set([
+  "read_url_content", "search_web", "web_search",
+  "browse", "http_request", "network_fetch",
+]);
+
+/**
+ * Classifies the operational impact scale for a tool call execution.
+ * @param {Record<string, any>} execution
+ * @param {Record<string, any>} [context]
+ * @returns {'local-single' | 'workspace-wide' | 'system-level'}
+ */
+export function classifyMeasureKind(execution, context = {}) {
+  if (!execution) return MEASURE_KINDS.LOCAL_SINGLE;
+
+  const toolName = execution.name || execution.tool || "";
+  const args = execution.arguments || {};
+
+  // 1. Tool-level system categorization
+  if (SYSTEM_LEVEL_TOOLS.has(toolName)) {
+    return MEASURE_KINDS.SYSTEM_LEVEL;
+  }
+
+  // 2. Tool-level single-file mutations / reads
+  if (SINGLE_FILE_TOOLS.has(toolName)) {
+    const target = args.TargetFile || args.targetPath || args.path || args.file || "";
+    if (typeof target === "string" && SYSTEM_PATH_REGEX.test(target)) {
+      return MEASURE_KINDS.SYSTEM_LEVEL;
+    }
+    return MEASURE_KINDS.LOCAL_SINGLE;
+  }
+
+  // 3. Shell / command inspection
+  const command = typeof args.command === "string" ? args.command.trim() : "";
+  if (!command) {
+    return MEASURE_KINDS.LOCAL_SINGLE;
+  }
+
+  // Fast check: first word
+  const firstWord = command.split(/\s+/)[0]?.toLowerCase();
+  if (SYSTEM_BINARIES.has(firstWord)) {
+    return MEASURE_KINDS.SYSTEM_LEVEL;
+  }
+  if ((command.includes("/") || command.includes(".")) && SYSTEM_PATH_REGEX.test(command)) {
+    return MEASURE_KINDS.SYSTEM_LEVEL;
+  }
+
+  // Check subcommands or pipes for system binaries only if operators present
+  if (/[|;&]/.test(command)) {
+    const tokens = command.split(/[\s|;&]+/);
+    for (const token of tokens) {
+      if (SYSTEM_BINARIES.has(token.toLowerCase())) {
+        return MEASURE_KINDS.SYSTEM_LEVEL;
+      }
+    }
+  }
+
+  // Check workspace-wide patterns
+  for (const pattern of WORKSPACE_COMMAND_PATTERNS) {
+    if (pattern.test(command)) {
+      return MEASURE_KINDS.WORKSPACE_WIDE;
+    }
+  }
+
+  // Multi-target rm or recursive rm
+  if (/^rm\s+/i.test(command)) {
+    if (/\s-[a-zA-Z]*r/i.test(command) || command.includes("*") || command.split(/\s+/).length > 3) {
+      return MEASURE_KINDS.WORKSPACE_WIDE;
+    }
+    return MEASURE_KINDS.LOCAL_SINGLE;
+  }
+
+  // Simple single-target commands
+  if (/^(cat|head|tail|sed|awk|echo|touch|ls|stat|file)\b/i.test(command)) {
+    if (command.includes("*") || command.includes(";")) {
+      return MEASURE_KINDS.WORKSPACE_WIDE;
+    }
+    return MEASURE_KINDS.LOCAL_SINGLE;
+  }
+
+  // Default fallback for unrecognized operations
+  return MEASURE_KINDS.LOCAL_SINGLE;
+}
+
+export function isSystemLevelExecution(execution, context) {
+  return classifyMeasureKind(execution, context) === MEASURE_KINDS.SYSTEM_LEVEL;
+}
+
+export function isWorkspaceWideExecution(execution, context) {
+  return classifyMeasureKind(execution, context) === MEASURE_KINDS.WORKSPACE_WIDE;
+}

package/lib/messages.js

@@ -22,6 +22,7 @@ export const MESSAGES = Object.freeze({
     detailUnsupported: "unsupported shell syntax",
     approvalRequired: "Approval required",
     askUnknown: "The command could not be fully inspected; review it before allowing",
+    askUnmatched: "The operation was not recognized by safety rules; human confirmation is required by default",
     askUnparseable: "Shell syntax could not be fully inspected; review it before allowing",
     askUnknownFormat: "The tool call format could not be inspected; review it before allowing",
     askUnknownWriteTarget: "The file write target could not be identified; review it before allowing",
@@ -107,6 +108,7 @@ export const MESSAGES = Object.freeze({
     hintTrashAlternative: "Move files to reversible .dsh/trash/<session>/ directory instead of rm",
     hintAgentsMdProhibited: "Review project-specific guidelines and constraints defined in AGENTS.md",
     hintMajorVersionBump: "Verify compatibility before bumping major dependency versions in package.json",
+    hintUnmatchedAsk: "Unrecognized operations default to fail-closed approval under defaultVerdict='ask'",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -128,6 +130,7 @@ export const MESSAGES = Object.freeze({
     detailUnsupported: "不支持的 shell 语法",
     approvalRequired: "需要批准",
     askUnknown: "命令无法完整检查；请在允许前进行审查",
+    askUnmatched: "该操作未被安全规则识别；默认需要人工确认",
     askUnparseable: "Shell 语法无法完整检查；请在允许前进行审查",
     askUnknownFormat: "工具调用格式无法检查；请在允许前进行审查",
     askUnknownWriteTarget: "无法识别文件写入目标；请在允许前进行审查",
@@ -213,6 +216,7 @@ export const MESSAGES = Object.freeze({
     hintTrashAlternative: "建议将文件移动到可逆的 .dsh/trash/<session>/ 目录，避免直接 rm",
     hintAgentsMdProhibited: "请核对项目根目录 AGENTS.md 中定义的安全约束和禁止指令",
     hintMajorVersionBump: "在升级 package.json 依赖主版本前请确认破坏性变更与兼容性",
+    hintUnmatchedAsk: "在 defaultVerdict='ask' 模式下，未识别的操作默认需要人工审核确认",
   },
 });
 
@@ -317,12 +321,14 @@ const HINT_KEYS = Object.freeze({
   "agents-md-prohibited-command": "hintAgentsMdProhibited",
   "agents-md-prohibited-path": "hintAgentsMdProhibited",
   "major-version-bump": "hintMajorVersionBump",
+  "unmatched-ask": "hintUnmatchedAsk",
 });
 
 const ASK_KEYS = Object.freeze({
   unparseable: "askUnparseable",
   "unknown-format": "askUnknownFormat",
   "unknown-write-target": "askUnknownWriteTarget",
+  "unmatched-ask": "askUnmatched",
   "dynamic-command": "askDynamicCommand",
   "dynamic-arguments": "askDynamicArguments",
   "dynamic-redirect": "askDynamicRedirect",

package/lib/snapshots.js

@@ -0,0 +1,268 @@
+// lib/snapshots.js
+// Pre-execution Snapshots (#77), Undo/Rollback (#76), and Dual-level Cleanup (#78).
+// Zero external dependencies; safe filesystem operations with in-memory metadata.
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const DEFAULT_MAX_SNAPSHOTS_PER_SESSION = 50;
+export const DEFAULT_MAX_SNAPSHOT_BYTES = 1024 * 1024; // 1 MB
+
+export class SnapshotManager {
+  /**
+   * @param {Record<string, any>} [options]
+   */
+  constructor(options = {}) {
+    this.maxSnapshotsPerSession = Number(options.maxSnapshotsPerSession) || DEFAULT_MAX_SNAPSHOTS_PER_SESSION;
+    this.maxSnapshotBytes = Number(options.maxSnapshotBytes) || DEFAULT_MAX_SNAPSHOT_BYTES;
+    this.workspaceDir = options.workspaceDir ? path.resolve(options.workspaceDir) : "";
+
+    /** @type {Map<string, Record<string, any>>} snapshotId -> Snapshot */
+    this.snapshots = new Map();
+    /** @type {Map<string, string[]>} sessionId -> [snapshotId, ...] */
+    this.sessionIndex = new Map();
+    /** @type {Map<string, string>} callId -> snapshotId */
+    this.callIndex = new Map();
+  }
+
+  /**
+   * Resolves absolute file path within workspace or host.
+   * @param {string} targetPath
+   * @returns {string}
+   */
+  resolvePath(targetPath) {
+    if (!targetPath || typeof targetPath !== "string") return "";
+    if (path.isAbsolute(targetPath)) return path.normalize(targetPath);
+    if (this.workspaceDir) return path.resolve(this.workspaceDir, targetPath);
+    return path.resolve(targetPath);
+  }
+
+  /**
+   * Captures a pre-execution snapshot before file mutation (#77).
+   * @param {string} targetPath - Relative or absolute path to target file
+   * @param {Record<string, any>} [meta] - Metadata (sessionId, callId, tool)
+   * @returns {Record<string, any>} Created snapshot record
+   */
+  takeSnapshot(targetPath, meta = {}) {
+    const resolved = this.resolvePath(targetPath);
+    if (!resolved) {
+      return { success: false, error: "invalid-target-path" };
+    }
+
+    const sessionId = String(meta.sessionId || "default");
+    const callId = meta.callId ? String(meta.callId) : null;
+    const tool = meta.tool ? String(meta.tool) : "unknown";
+
+    let existed = false;
+    let content = null;
+    let tooLarge = false;
+    let size = 0;
+
+    try {
+      if (fs.existsSync(resolved)) {
+        existed = true;
+        const stat = fs.statSync(resolved);
+        size = stat.size;
+        if (size > this.maxSnapshotBytes) {
+          tooLarge = true;
+        } else {
+          content = fs.readFileSync(resolved, "utf8");
+        }
+      }
+    } catch {
+      // If file unreadable or permission error, proceed safely
+      existed = false;
+    }
+
+    const id = "snap_" + Date.now() + "_" + crypto.randomBytes(4).toString("hex");
+    const snapshot = {
+      id,
+      sessionId,
+      callId,
+      tool,
+      targetPath: resolved,
+      originalPath: targetPath,
+      existed,
+      content,
+      size,
+      tooLarge,
+      createdAt: Date.now(),
+      rolledBack: false,
+      rolledBackAt: null,
+    };
+
+    this.snapshots.set(id, snapshot);
+
+    if (callId) {
+      this.callIndex.set(callId, id);
+    }
+
+    if (!this.sessionIndex.has(sessionId)) {
+      this.sessionIndex.set(sessionId, []);
+    }
+    const sessionList = this.sessionIndex.get(sessionId);
+    sessionList.push(id);
+
+    // Evict oldest if exceeding maxSnapshotsPerSession
+    if (sessionList.length > this.maxSnapshotsPerSession) {
+      const evictedId = sessionList.shift();
+      if (evictedId) {
+        const evicted = this.snapshots.get(evictedId);
+        if (evicted && evicted.callId) {
+          this.callIndex.delete(evicted.callId);
+        }
+        this.snapshots.delete(evictedId);
+      }
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Retrieves a snapshot by ID.
+   * @param {string} id
+   * @returns {Record<string, any> | null}
+   */
+  getSnapshot(id) {
+    return this.snapshots.get(id) || null;
+  }
+
+  /**
+   * Retrieves a snapshot by tool callId.
+   * @param {string} callId
+   * @returns {Record<string, any> | null}
+   */
+  getSnapshotByCallId(callId) {
+    const id = this.callIndex.get(String(callId));
+    return id ? this.getSnapshot(id) : null;
+  }
+
+  /**
+   * Retrieves all snapshots for a session.
+   * @param {string} sessionId
+   * @returns {Record<string, any>[]}
+   */
+  getSnapshots(sessionId) {
+    const ids = this.sessionIndex.get(String(sessionId)) || [];
+    const res = [];
+    for (const id of ids) {
+      const snap = this.snapshots.get(id);
+      if (snap) res.push(snap);
+    }
+    return res;
+  }
+
+  /**
+   * Undoes a file change by rolling back to its pre-execution snapshot (#76).
+   * @param {string} snapshotIdOrCallback - Snapshot ID or Call ID
+   * @returns {{ success: boolean, error?: string, snapshotId?: string, targetPath?: string, restoredExisted?: boolean }}
+   */
+  rollbackSnapshot(snapshotIdOrCallback) {
+    if (!snapshotIdOrCallback) {
+      return { success: false, error: "snapshot-id-required" };
+    }
+
+    let snap = this.snapshots.get(snapshotIdOrCallback);
+    if (!snap) {
+      const id = this.callIndex.get(String(snapshotIdOrCallback));
+      if (id) snap = this.snapshots.get(id);
+    }
+
+    if (!snap) {
+      return { success: false, error: "snapshot-not-found" };
+    }
+
+    if (snap.rolledBack) {
+      return { success: false, error: "snapshot-already-rolled-back", snapshotId: snap.id };
+    }
+
+    if (snap.tooLarge) {
+      return { success: false, error: "snapshot-size-limit-exceeded", snapshotId: snap.id };
+    }
+
+    try {
+      if (snap.existed && snap.content !== null) {
+        // Restore previous content
+        const dir = path.dirname(snap.targetPath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(snap.targetPath, snap.content, "utf8");
+      } else if (!snap.existed) {
+        // File was newly created by this call: delete it to undo
+        if (fs.existsSync(snap.targetPath)) {
+          fs.unlinkSync(snap.targetPath);
+        }
+      }
+
+      snap.rolledBack = true;
+      snap.rolledBackAt = Date.now();
+
+      return {
+        success: true,
+        snapshotId: snap.id,
+        targetPath: snap.targetPath,
+        restoredExisted: snap.existed,
+        rolledBackAt: snap.rolledBackAt,
+      };
+    } catch (err) {
+      return {
+        success: false,
+        error: "rollback-io-error",
+        detail: String(err && err.message || err),
+        snapshotId: snap.id,
+      };
+    }
+  }
+
+  /**
+   * Cleans up snapshots for a single session safely (#78).
+   * @param {string} sessionId
+   * @returns {{ cleared: number, sessionId: string }}
+   */
+  clearSnapshots(sessionId) {
+    const sId = String(sessionId || "default");
+    const ids = this.sessionIndex.get(sId) || [];
+    let cleared = 0;
+    for (const id of ids) {
+      const snap = this.snapshots.get(id);
+      if (snap && snap.callId) {
+        this.callIndex.delete(snap.callId);
+      }
+      if (this.snapshots.delete(id)) {
+        cleared++;
+      }
+    }
+    this.sessionIndex.delete(sId);
+    return { cleared, sessionId: sId };
+  }
+
+  /**
+   * Cleans up snapshots globally across all sessions (#78).
+   * @returns {{ cleared: number }}
+   */
+  clearAllSnapshots() {
+    const total = this.snapshots.size;
+    this.snapshots.clear();
+    this.sessionIndex.clear();
+    this.callIndex.clear();
+    return { cleared: total };
+  }
+
+  /**
+   * Returns snapshot usage metrics and statistics.
+   * @returns {{ totalSnapshots: number, sessionCount: number, totalBytes: number }}
+   */
+  getStats() {
+    let totalBytes = 0;
+    for (const snap of this.snapshots.values()) {
+      totalBytes += snap.size || 0;
+    }
+    return {
+      totalSnapshots: this.snapshots.size,
+      sessionCount: this.sessionIndex.size,
+      totalBytes,
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
   "type": "module",
   "main": "lib/index.js",