@goodandready/dsh-approval-gate 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.15
+
+- Rules: Каскадный декларативный YAML-конфиг правил `rules.yaml` (`.dsh/rules.yaml` в проекте и `~/.dsh/rules.yaml` пользователя) с поддержкой allow/deny/ask политик (Refs: #38).
+- Rules: Вынесение каталога встроенных критических угроз нулевого уровня (P0) в отчуждаемый версионируемый каталог `rules/builtin-high-risk.yaml` (Refs: #45).
+- Rules: Условные предикаты правил `when` с сопоставлением контекста окружения (ОС `os`, git-ветка `branch`, переменные окружения `env` и инструмент `tool`) с поддержкой отрицания `!` (Refs: #44).
+- Performance: Высокоскоростной пре-фильтр ключевых слов `HotwordsMatcher` (rm, kill, shadow, sudoers, curl, format и др.) для микросекундного пропуска безопасных команд (Refs: #93).
+- Testing: Корпус тестовых векторов `test/vectors/corpus.json` из 110+ команд с автотестом контроля регрессий (FPR=0, FNR=0) (Refs: #46).
+
+## 0.1.14
+
+- Feature: Режим теневого аудита (`dryRun: true` / `shadowMode: true`) в `Config` и `SecurityEngine` для безопасного тестирования правил на проде без блокировки выполнения процессов агента (Refs: #128).
+- Security: Генерация канонического отпечатка операции (`lib/fingerprint.js`) в формате `tool:normalize(cmd):target_path` со строгой дифференциацией флагов, аргументов и путей (Refs: #80).
+- Performance: Семантический LRU/TTL кэш вердиктов безопасности (`lib/cache.js`) по хэшу нормализованных аргументов и сессионный кэш с детерминированным O(1) временем ответа (Refs: #63, #119).
+- Security: Предохранитель повторных попыток обхода (`lib/retry-exhaustion.js` `RetryExhaustionGuard`) с блокировкой и требованием вмешательства человека при 3 последовательных попытках вызова запрещенных команд (Refs: #96).
+- Resilience: Исключение сетевых сбоев, таймаутов LLM и ошибок парсинга классификатора из срабатывания предохранителя `CircuitBreaker` (`countDeny` с опцией исключения сбоев) (Refs: #111).
+- Quality: Журнал аномалий и качества сессии (`lib/ledger.js` `QualityLedger`) с фиксацией повторных отказов, расчетом qualityScore и предупреждениями о деградации (Refs: #88).
+- Security: Изоляция журнала аудита от контекста сессии (`lib/audit-log.js` `AuditLogger`) с записью в append-only файл `~/.dsh/approval-gate-audit.jsonl` для предотвращения indirect prompt injection (Refs: #56).
+
 ## 0.1.13
 
 - Architecture: выделение `CommandDispatcher` (`lib/dispatcher.js`) для полной изоляции синтаксического разбора аргументов и классификации типов инструментов от движка принятия решений `SecurityEngine` (Refs: #133).
@@ -33,19 +51,14 @@
 - Policy: оптимизация сканирования истории событий сессии в `readKnobs` — однопроходный поиск, ограничение глубины до 100 событий и кэширование политики сессии на `_gateCachedPolicy` (Refs: #148).
 - Schema: поддержка `.volatile()` на полях конфигурации, явные поля `workspaceDir` и `engine`, полифилл для DSH UI формы настроек и функция разворачивания реактивных боксов `plainConfig` (Refs: #142, #150, #151).
 - Engine: методы `addGrant`, `getGrants` и `resume` на `SecurityEngine` и экспорт `ctx.approvalGate` для управления грантами и сбросом предохранителя (Refs: #152).
-- Tokenizer: исправление передачи маркера heredoc (`marker: heredoc.delimiter`) в токенизаторе и корректная реконструкция в `splitSubcommands` (Refs: #146).
-- Tests: матрица проверок на обходные векторы через операторы конвейеров и allow-префиксы (Refs: #164).
 
 ## 0.1.10
 
-- Policy: точное определение сессионной политики апрува в `readKnobs` через `approval.effectivePolicy(session)`, историю событий `session.eventAt` и пресет `danger-full-access` (Refs: #140).
-- Execution: корректный пропуск некритичных команд в режиме «Полный доступ» (`never`) без ложного поднятия `ask` и автоматического отказа DSH `Error: the user rejected tool` (Refs: #140).
-- Observability: форматирование `sessionTag` с получением строкового идентификатора сессии `session.id` / `session.name` вместо `[object Object]` (Refs: #140).
+- Performance: lazy compilation of regular expressions in `inspectArgv` (Refs: #140).
+- Test: fix path traversal tests on Windows by dynamically reading root drive (Refs: #141).
 
 ## 0.1.9
 
-- Inspect: декомпозиция `lib/inspect.js` с выносом `checkEnvExfiltration` в `lib/inspect-env.js`, строгое соблюдение порога 600 строк (Refs: #35).
-- Security: автоматическое маскирование и redaction чувствительных данных, токенов и паролей в сетевых URL и аудиторских логах `redactUrl` и `redactCredentials` (Refs: #42).
 - Paths: интеграция `resolveSafePath` как основного примитива безопасности файловых путей и защита от symlink и path traversal обходов (Refs: #94, #137).
 - Engine: интеграция 5-уровневого каскада принятия решений `SecurityEngine` (P0 Hard-Deny -> P1 Grants -> P2 Static -> P3 LLM -> P4 Ask) в хук `tools/pre-execute` и рантайм-гард `tools.guard` (Refs: #122).
 - Messages: расширенная мультиязычная локализация причин блокировки (ru, en, zh) с контекстными подсказками безопасных альтернатив `hintPrefix` и `ruleHints` (Refs: #131).

package/lib/audit-log.js

@@ -0,0 +1,76 @@
+// lib/audit-log.js
+// Isolated append-only audit logger for dsh-approval-gate (#56).
+// Logs gate decisions to ~/.dsh/approval-gate-audit.jsonl out-of-band to prevent prompt injection.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { computeFingerprint } from "./fingerprint.js";
+import { redactCredentials } from "./redact.js";
+
+export const DEFAULT_AUDIT_LOG_RELATIVE = path.join(".dsh", "approval-gate-audit.jsonl");
+
+export class AuditLogger {
+  /**
+   * @param {{ logPath?: string, disabled?: boolean }} [options]
+   */
+  constructor(options = {}) {
+    this.disabled = options.disabled === true;
+    if (options.logPath) {
+      this.logPath = options.logPath;
+    } else {
+      const home = os.homedir ? os.homedir() : (process.env.HOME || process.env.USERPROFILE || "");
+      this.logPath = home ? path.join(home, DEFAULT_AUDIT_LOG_RELATIVE) : "";
+    }
+  }
+
+  /**
+   * Write an audit record to the isolated log file.
+   *
+   * @param {{
+   *   sessionId?: string,
+   *   execution?: any,
+   *   decision: { verdict: string, stage?: string, reason?: string, detail?: string, dryRun?: boolean },
+   *   dryRun?: boolean
+   * }} record
+   */
+  log(record) {
+    if (this.disabled || !this.logPath) return;
+
+    try {
+      const now = Date.now();
+      const execution = record.execution || {};
+      const decision = record.decision || {};
+      const tool = String(execution.name || execution.tool || "").trim();
+      const rawCmd = execution.arguments && typeof execution.arguments.command === "string"
+        ? execution.arguments.command
+        : "";
+      const redactedCmd = rawCmd ? redactCredentials(rawCmd) : undefined;
+      const fp = computeFingerprint(execution);
+
+      const entry = {
+        timestamp: now,
+        iso: new Date(now).toISOString(),
+        sessionId: record.sessionId || "default",
+        tool,
+        command: redactedCmd,
+        verdict: decision.verdict,
+        stage: decision.stage,
+        reason: decision.reason,
+        detail: decision.detail,
+        fingerprint: fp,
+        dryRun: Boolean(record.dryRun || decision.dryRun),
+      };
+
+      const line = JSON.stringify(entry) + "\n";
+      const dir = path.dirname(this.logPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.appendFileSync(this.logPath, line, "utf8");
+    } catch {
+      // Security audit failures fail open to prevent DoS,
+      // but never leak errors into agent prompt.
+    }
+  }
+}

package/lib/breaker.js

@@ -166,10 +166,16 @@ export class CircuitBreaker {
 
   /**
    * Record a security denial. Returns true if this call tripped the breaker.
+   * Excludes network faults and classifier errors from tripping the breaker (#111).
+   *
    * @param {string} [sessionId]
+   * @param {{ isNetworkFault?: boolean, isClassifierError?: boolean }} [options]
    * @returns {boolean}
    */
-  countDeny(sessionId) {
+  countDeny(sessionId, options = {}) {
+    if (options && (options.isNetworkFault || options.isClassifierError)) {
+      return false;
+    }
     const key = sessionId || "default";
     const state = this._getOrCreate(key);
     state.consecutive += 1;
@@ -191,6 +197,25 @@ export class CircuitBreaker {
     return false;
   }
 
+  /**
+   * Identifies whether an error represents a network fault or classifier timeout (#111).
+   * @param {any} err
+   * @returns {boolean}
+   */
+  static isFaultOrTimeout(err) {
+    if (!err) return false;
+    const msg = String(err.message || err).toLowerCase();
+    return (
+      msg.includes("timeout") ||
+      msg.includes("econnrefused") ||
+      msg.includes("enotfound") ||
+      msg.includes("etimedout") ||
+      msg.includes("network") ||
+      msg.includes("fetch failed") ||
+      msg.includes("socket hang up")
+    );
+  }
+
   /**
    * Reset the consecutive counter on an allowed operation.
    * @param {string} [sessionId]
@@ -231,4 +256,3 @@ export class CircuitBreaker {
     this.sessions.clear();
   }
 }
-

package/lib/cache.js

@@ -0,0 +1,146 @@
+// lib/cache.js
+// Semantic LRU/TTL verdict cache for dsh-approval-gate (#63, #119).
+// Caches deterministic security decisions by canonical operation fingerprint.
+
+import { computeFingerprintHash } from "./fingerprint.js";
+
+export const DEFAULT_CACHE_MAX_SIZE = 1000;
+export const DEFAULT_CACHE_TTL_MS = 300_000; // 5 minutes
+
+export class VerdictCache {
+  /**
+   * @param {{ maxSize?: number, defaultTtlMs?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxSize = options.maxSize || DEFAULT_CACHE_MAX_SIZE;
+    this.defaultTtlMs = options.defaultTtlMs !== undefined ? options.defaultTtlMs : DEFAULT_CACHE_TTL_MS;
+    /** @type {Map<string, { decision: any, expiresAt: number, sessionId?: string, timestamp: number }>} */
+    this.entries = new Map();
+  }
+
+  /**
+   * Generates a stable cache key for execution in a session context.
+   *
+   * @param {any} execution
+   * @param {{ sessionId?: string, cwd?: string, sessionScoped?: boolean }} [context]
+   * @returns {string}
+   */
+  makeKey(execution, context = {}) {
+    const hash = computeFingerprintHash(execution, { cwd: context.cwd });
+    if (context.sessionScoped && context.sessionId) {
+      return `${context.sessionId}:${hash}`;
+    }
+    return hash;
+  }
+
+  /**
+   * Retrieves a cached verdict if present and not expired.
+   * Promotes the entry to most recently used.
+   *
+   * @param {string} key
+   * @returns {any | undefined} Cached decision object or undefined
+   */
+  get(key) {
+    if (!this.entries.has(key)) return undefined;
+    const entry = this.entries.get(key);
+    const now = Date.now();
+
+    if (entry.expiresAt > 0 && now > entry.expiresAt) {
+      this.entries.delete(key);
+      return undefined;
+    }
+
+    // Refresh LRU order: delete and re-insert
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+
+    return { ...entry.decision, cached: true, cacheHitAt: now };
+  }
+
+  /**
+   * Stores a decision in the cache.
+   * Only caches deterministic verdicts ("allow" or "deny").
+   *
+   * @param {string} key
+   * @param {any} decision
+   * @param {{ ttlMs?: number, sessionId?: string }} [options]
+   */
+  set(key, decision, options = {}) {
+    if (!key || !decision) return;
+    // Do not cache transient or uncertain verdicts unless explicit
+    if (decision.verdict !== "allow" && decision.verdict !== "deny") {
+      return;
+    }
+
+    const ttl = options.ttlMs !== undefined ? options.ttlMs : this.defaultTtlMs;
+    const now = Date.now();
+    const expiresAt = ttl > 0 ? now + ttl : 0;
+
+    // If key already exists, delete it first to ensure correct insertion order
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    } else if (this.entries.size >= this.maxSize) {
+      // Evict oldest (first key in iteration)
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.entries.delete(oldestKey);
+      }
+    }
+
+    this.entries.set(key, {
+      decision: {
+        verdict: decision.verdict,
+        stage: decision.stage,
+        reason: decision.reason,
+        detail: decision.detail,
+        hit: decision.hit,
+      },
+      expiresAt,
+      sessionId: options.sessionId,
+      timestamp: now,
+    });
+  }
+
+  has(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return false;
+    if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
+      this.entries.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  delete(key) {
+    return this.entries.delete(key);
+  }
+
+  clear() {
+    this.entries.clear();
+  }
+
+  clearSession(sessionId) {
+    if (!sessionId) return;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.sessionId === sessionId || key.startsWith(`${sessionId}:`)) {
+        this.entries.delete(key);
+      }
+    }
+  }
+
+  prune() {
+    const now = Date.now();
+    let count = 0;
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.expiresAt > 0 && now > entry.expiresAt) {
+        this.entries.delete(key);
+        count += 1;
+      }
+    }
+    return count;
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+}

package/lib/engine.js

@@ -1,25 +1,38 @@
 // lib/engine.js
 // 5-tier Security Decision Engine for dsh-approval-gate.
 // Waterfall:
-// P0: Hard Deny (Bands Band 0 + inspectExecution hard denials + protected files)
-// P1: Session Grants (scoped temporary allowances)
+// P0: Hard Deny (Bands Band 0 + Declarative Rules Deny + inspectExecution hard denials + protected files + retry exhaustion)
+// P1: Session Grants & Declarative Allow (scoped temporary allowances and whitelists)
 // P2: Static Rules / Safe Allow (Bands Band 1 + safe read-only commands)
 // P3: Optional Semantic Classifier
-// P4: Human Ask Fallback (uncertain syntax / ambiguous commands / tripped breaker)
+// P4: Human Ask Fallback (uncertain syntax / ambiguous commands / tripped breaker / declarative ask)
 
 import { BandsEngine } from "./bands.js";
 import { CircuitBreaker } from "./breaker.js";
 import { SessionGrantStore } from "./grants.js";
 import { inspectExecution } from "./inspect.js";
+import { VerdictCache } from "./cache.js";
+import { RetryExhaustionGuard } from "./retry-exhaustion.js";
+import { QualityLedger } from "./ledger.js";
+import { AuditLogger } from "./audit-log.js";
+import { DeclarativeRulesEngine } from "./rules-loader.js";
 
 export class SecurityEngine {
   /**
    * @param {{
    *   bands?: BandsEngine,
    *   breaker?: CircuitBreaker,
-   *   inspectConfig?: { toolName?: string, fileWriteTools?: string[] },
+   *   cache?: VerdictCache,
+   *   retryGuard?: RetryExhaustionGuard,
+   *   ledger?: QualityLedger,
+   *   auditLogger?: AuditLogger,
+   *   declarativeRules?: DeclarativeRulesEngine,
+   *   inspectConfig?: { toolName?: string, fileWriteTools?: string[], workspaceDir?: string },
    *   classifier?: ((execution: any, context?: any) => { verdict: "allow"|"deny", reason?: string }),
-   *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" }
+   *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" },
+   *   dryRun?: boolean,
+   *   shadowMode?: boolean,
+   *   defaultVerdict?: "allow" | "ask"
    * }} [options]
    */
   constructor(options = {}) {
@@ -29,21 +42,118 @@ export class SecurityEngine {
     this.classifier = options.classifier || null;
     this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
     this.defaultVerdict = options.defaultVerdict || "allow";
+
+    this.dryRun = Boolean(options.dryRun || options.shadowMode);
+    this.cache = options.cache !== undefined ? options.cache : new VerdictCache();
+    this.retryGuard = options.retryGuard !== undefined ? options.retryGuard : new RetryExhaustionGuard();
+    this.ledger = options.ledger !== undefined ? options.ledger : new QualityLedger();
+    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger();
+    this.declarativeRules = options.declarativeRules || new DeclarativeRulesEngine({
+      workspaceDir: this.inspectConfig?.workspaceDir,
+    });
   }
 
   /**
    * Evaluates an execution request through the P0-P4 waterfall.
    *
    * @param {{ name: string, arguments?: any }} execution - Tool call
-   * @param {{ sessionId?: string, knobs?: any }} [context] - Context options
-   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string, hit?: any }}
+   * @param {{ sessionId?: string, knobs?: any, cwd?: string }} [context] - Context options
+   * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string, hit?: any, dryRun?: boolean, cached?: boolean }}
    */
   decide(execution, context = {}) {
     try {
       const sessionId = context.sessionId || "default";
-    const toolName = execution && execution.name;
-    const command = execution && execution.arguments && execution.arguments.command;
+      const toolName = execution && execution.name;
+      const command = execution && execution.arguments && execution.arguments.command;
+
+      // Check Retry Exhaustion guard (#96)
+      if (this.retryGuard && this.retryGuard.isExhausted(sessionId)) {
+        const exhHit = {
+          deny: true,
+          reason: "retry-exhaustion",
+          detail: "Retry exhaustion: consecutive blocked attempts exceeded threshold",
+          snippet: command || toolName,
+        };
+        const exhDecision = { verdict: "deny", stage: "P0", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
+        if (this.ledger) this.ledger.record(sessionId, "exhaustion", { reason: "retry-exhaustion", tool: toolName });
+        if (this.auditLogger) this.auditLogger.log({ sessionId, execution, decision: exhDecision, dryRun: this.dryRun });
+
+        if (this.dryRun) {
+          return { verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
+        }
+        return exhDecision;
+      }
+
+      // Check Verdict Cache (#63, #119)
+      const cacheKey = this.cache ? this.cache.makeKey(execution, context) : null;
+      if (this.cache && cacheKey) {
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+          if (this.dryRun && (cached.verdict === "deny" || cached.verdict === "ask")) {
+            return {
+              verdict: "allow",
+              stage: cached.stage,
+              dryRun: true,
+              originalVerdict: cached.verdict,
+              reason: cached.reason,
+              detail: cached.detail,
+              hit: cached.hit,
+              cached: true,
+            };
+          }
+          return cached;
+        }
+      }
+
+      const decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
+
+      // Post-decision hooks: ledger, retryGuard, cache, audit
+      if (decision.verdict === "deny") {
+        if (this.retryGuard) this.retryGuard.recordVerdict(sessionId, execution, "deny");
+        if (this.ledger) this.ledger.record(sessionId, "deny", { reason: decision.reason, detail: decision.detail, tool: toolName });
+        if (this.cache && cacheKey) this.cache.set(cacheKey, decision, { sessionId });
+      } else if (decision.verdict === "allow") {
+        if (this.retryGuard) this.retryGuard.recordVerdict(sessionId, execution, "allow");
+        if (this.ledger) this.ledger.record(sessionId, "allow", { reason: decision.reason, detail: decision.detail, tool: toolName });
+        if (this.cache && cacheKey) this.cache.set(cacheKey, decision, { sessionId });
+      } else if (decision.verdict === "ask") {
+        if (this.ledger) this.ledger.record(sessionId, "ask", { reason: decision.reason, detail: decision.detail, tool: toolName });
+      }
+
+      if (this.auditLogger) {
+        this.auditLogger.log({ sessionId, execution, decision, dryRun: this.dryRun });
+      }
+
+      // Shadow Mode (#128)
+      if (this.dryRun && (decision.verdict === "deny" || decision.verdict === "ask")) {
+        return {
+          verdict: "allow",
+          stage: decision.stage,
+          dryRun: true,
+          originalVerdict: decision.verdict,
+          reason: decision.reason,
+          detail: decision.detail,
+          hit: decision.hit,
+        };
+      }
+
+      return decision;
+    } catch (err) {
+      return {
+        verdict: "ask",
+        stage: "P4",
+        reason: "inspect-error",
+        detail: String(err && err.message || err),
+        hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
+      };
+    }
+  }
 
+  /**
+   * Internal evaluation of P0-P4 waterfall.
+   * @private
+   */
+  _evaluateWaterfall(execution, context, sessionId, toolName, command) {
     // Fast-path Band 0 Hard Deny
     const bandVerdict = this.bands.evaluate(toolName, command);
     if (bandVerdict === "deny") {
@@ -52,6 +162,26 @@ export class SecurityEngine {
       return { verdict: "deny", stage: "P0", reason: "band-hard-deny", detail: command, hit };
     }
 
+    // Declarative YAML Rules evaluation (#38, #45, #44)
+    if (this.declarativeRules && command) {
+      const decl = this.declarativeRules.evaluate(toolName, command, context);
+      if (decl.match) {
+        if (decl.verdict === "deny") {
+          this.breaker.countDeny(sessionId);
+          const hit = { deny: true, reason: decl.reason || "declarative-deny", detail: command, snippet: command, ruleId: decl.ruleId };
+          return { verdict: "deny", stage: "P0", reason: decl.reason || "declarative-deny", detail: command, hit };
+        }
+        if (decl.verdict === "allow") {
+          this.breaker.resetConsecutive(sessionId);
+          return { verdict: "allow", stage: "P1", reason: decl.reason || "declarative-allow", hit: null };
+        }
+        if (decl.verdict === "ask") {
+          const hit = { ask: true, reason: decl.reason || "declarative-ask", detail: command, snippet: command, ruleId: decl.ruleId };
+          return { verdict: "ask", stage: "P4", reason: decl.reason || "declarative-ask", detail: command, hit };
+        }
+      }
+    }
+
     // Inspect execution for hard denials and syntax checks
     const hit = inspectExecution(execution, this.inspectConfig);
     if (hit.deny) {
@@ -70,6 +200,7 @@ export class SecurityEngine {
 
     // If Circuit Breaker is tripped, suspend auto-mode and force P4 Human Ask
     if (this.breaker.isTripped(sessionId)) {
+      if (this.ledger) this.ledger.record(sessionId, "breaker", { reason: "circuit-breaker-tripped", tool: toolName });
       const breakerHit = {
         ask: true,
         reason: "circuit-breaker-tripped",
@@ -110,7 +241,8 @@ export class SecurityEngine {
           return { verdict: "deny", stage: "P3", reason: cls.reason || "classifier-deny", detail: cls.reason, hit: clsHit };
         }
       } catch (err) {
-        // Classifier error fails closed to P4 Ask
+        // Classifier error fails closed to P4 Ask (#111: does not trip breaker)
+        if (this.ledger) this.ledger.record(sessionId, "error", { reason: "classifier-error", detail: String(err && err.message || err), tool: toolName });
         return { verdict: "ask", stage: "P4", reason: "classifier-error", detail: String(err && err.message || err), hit: null };
       }
     }
@@ -121,15 +253,6 @@ export class SecurityEngine {
       return { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
     }
     return { verdict: "allow", stage: "P2", reason: "unmatched-allow", hit };
-    } catch (err) {
-      return {
-        verdict: "ask",
-        stage: "P4",
-        reason: "inspect-error",
-        detail: String(err && err.message || err),
-        hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
-      };
-    }
   }
 
   addGrant(options) {
@@ -146,7 +269,21 @@ export class SecurityEngine {
     return [];
   }
 
+  getLedgerSummary(sessionId) {
+    return this.ledger ? this.ledger.getSummary(sessionId) : null;
+  }
+
+  isRetryExhausted(sessionId) {
+    return this.retryGuard ? this.retryGuard.isExhausted(sessionId) : false;
+  }
+
+  clearCache() {
+    if (this.cache) this.cache.clear();
+  }
+
   resume(sessionId, reason) {
+    if (this.retryGuard) this.retryGuard.reset(sessionId);
+    if (this.cache) this.cache.clearSession(sessionId);
     return this.breaker.resume(sessionId, reason);
   }
 }

package/lib/fingerprint.js

@@ -0,0 +1,100 @@
+// lib/fingerprint.js
+// Canonical operation fingerprint generator for dsh-approval-gate (#80).
+// Format: tool:normalize(cmd):target_path
+// Strict: flag or argument variations produce distinct fingerprints.
+
+import { createHash } from "node:crypto";
+import { extractFilePath } from "./dispatcher.js";
+import { canonicalizeFsPath, normalizeSeparators } from "./paths.js";
+
+/**
+ * Normalizes command whitespace while preserving quotes.
+ *
+ * @param {string} cmd
+ * @returns {string}
+ */
+export function normalizeCommandString(cmd) {
+  if (typeof cmd !== "string") return "";
+  const trimmed = cmd.trim();
+  if (!trimmed) return "";
+
+  let result = "";
+  let inSingle = false;
+  let inDouble = false;
+  let lastWasSpace = false;
+
+  for (let i = 0; i < trimmed.length; i += 1) {
+    const ch = trimmed[i];
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+      result += ch;
+      lastWasSpace = false;
+    } else if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+      result += ch;
+      lastWasSpace = false;
+    } else if (/\s/.test(ch) && !inSingle && !inDouble) {
+      if (!lastWasSpace) {
+        result += " ";
+        lastWasSpace = true;
+      }
+    } else {
+      result += ch;
+      lastWasSpace = false;
+    }
+  }
+
+  return result.trim();
+}
+
+/**
+ * Generates a canonical fingerprint for an operation.
+ * Format: tool:normalized_cmd:target_path
+ *
+ * @param {{ name?: string, tool?: string, arguments?: any } | string} execution
+ * @param {{ cwd?: string }} [options]
+ * @returns {string}
+ */
+export function computeFingerprint(execution, options = {}) {
+  let tool = "";
+  let args = {};
+
+  if (typeof execution === "string") {
+    tool = execution.trim().toLowerCase();
+  } else if (execution && typeof execution === "object") {
+    tool = String(execution.name || execution.tool || "").trim().toLowerCase();
+    args = execution.arguments || {};
+    if (typeof args === "string") {
+      try {
+        args = JSON.parse(args);
+      } catch {
+        args = { raw: args };
+      }
+    }
+  }
+
+  const rawCmd = args && typeof args.command === "string" ? args.command : "";
+  const normalizedCmd = normalizeCommandString(rawCmd);
+
+  let targetPath = (args && (args.cwd || extractFilePath(args))) || options.cwd || "";
+  if (typeof targetPath === "string" && targetPath.trim()) {
+    targetPath = canonicalizeFsPath(normalizeSeparators(targetPath.trim()));
+  } else {
+    targetPath = "";
+  }
+
+  return `${tool}:${normalizedCmd}:${targetPath}`;
+}
+
+/**
+ * Computes sha256 hash of the canonical operation fingerprint.
+ *
+ * @param {{ name?: string, tool?: string, arguments?: any } | string} execution
+ * @param {{ cwd?: string, algorithm?: string }} [options]
+ * @returns {string}
+ */
+export function computeFingerprintHash(execution, options = {}) {
+  const fp = computeFingerprint(execution, options);
+  const algo = options.algorithm || "sha256";
+  return createHash(algo).update(fp, "utf8").digest("hex");
+}