@goodandready/dsh-approval-gate 0.1.17 → 0.1.19

package/lib/dispatcher.js

@@ -1,208 +1,210 @@
-// lib/dispatcher.js
-// Command Dispatcher: architectural isolation of command parsing and syntactic dispatch
-// from the safety evaluation engine.
-// Resolves: #133, #65
-
-import { tokenize, splitSubcommands } from "./tokenizer.js";
-import { parseGitArgv, classifyGitOperation } from "./parsers/git.js";
-import { extractRedirects, inspectRedirectSecurity, inspectSilentErrors, inspectPipelines } from "./parsers/shell-cmds.js";
-import { isLoopbackCommand, isLoopbackUrl } from "./loopback.js";
-import { resolveSafePath, isPathTraversal, isProtectedConfigPath } from "./paths.js";
-
-export const TOOL_KIND_SHELL = "shell";
-export const TOOL_KIND_FILE_WRITE = "file_write";
-export const TOOL_KIND_FILE_READ = "file_read";
-export const TOOL_KIND_NETWORK = "network";
-export const TOOL_KIND_GENERIC = "generic";
-
-export const DEFAULT_BASH_TOOL = "bash";
-export const DEFAULT_FILE_WRITE_TOOLS = Object.freeze([
-  "write",
-  "edit",
-  "Write",
-  "Edit",
-  "str_replace_editor",
-  "str_replace",
-  "apply_patch",
-]);
-
-export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
-  "read_file",
-  "view_file",
-  "read_url_content",
-  "search_web",
-  "list_dir",
-  "glob",
-  "grep",
-]);
-
-export const DEFAULT_NETWORK_TOOLS = Object.freeze([
-  "fetch",
-  "web_fetch",
-  "http_request",
-  "read_url_content",
-]);
-
-/**
- * Extracts target file path from various tool argument schemas.
- *
- * @param {any} args
- * @returns {string | null}
- */
-export function extractFilePath(args) {
-  if (typeof args === "string") return args;
-  if (!args || typeof args !== "object") return null;
-  const keys = [
-    "path",
-    "file_path",
-    "filePath",
-    "file",
-    "filename",
-    "target",
-    "to",
-    "TargetFile",
-    "AbsolutePath",
-  ];
-  for (const k of keys) {
-    if (typeof args[k] === "string" && args[k].trim()) {
-      return args[k].trim();
-    }
-  }
-  return null;
-}
-
-/**
- * Checks whether an execution originates from a designated read-only reviewer agent.
- * Resolves: #65 (strict read-only reviewer subagent isolation).
- *
- * @param {any} execution
- * @param {any} [options]
- * @returns {boolean}
- */
-export function isReviewerAgent(execution, options = {}) {
-  if (options && options.reviewerMode === true) return true;
-  const agent = execution && execution.agent;
-  if (!agent) return false;
-
-  const role = typeof agent.role === "string" ? agent.role.toLowerCase() : "";
-  const name = typeof agent.name === "string" ? agent.name.toLowerCase() : "";
-  const type = typeof agent.type === "string" ? agent.type.toLowerCase() : "";
-
-  return role.includes("review") || name.includes("review") || type.includes("review");
-}
-
-export class CommandDispatcher {
-  /**
-   * @param {{
-   *   toolName?: string,
-   *   fileWriteTools?: string[] | Set<string>,
-   *   readOnlyTools?: string[] | Set<string>,
-   *   networkTools?: string[] | Set<string>,
-   *   workspaceDir?: string
-   * }} [options]
-   */
-  constructor(options = {}) {
-    this.toolName = options.toolName || DEFAULT_BASH_TOOL;
-    this.fileWriteTools = new Set(options.fileWriteTools || DEFAULT_FILE_WRITE_TOOLS);
-    this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
-    this.networkTools = new Set(options.networkTools || DEFAULT_NETWORK_TOOLS);
-    this.workspaceDir = options.workspaceDir || process.cwd();
-  }
-
-  /**
-   * Categorizes the tool name into functional kind.
-   *
-   * @param {string} name
-   * @returns {"shell" | "file_write" | "file_read" | "network" | "generic"}
-   */
-  classifyTool(name) {
-    if (!name) return TOOL_KIND_GENERIC;
-    if (name === this.toolName) return TOOL_KIND_SHELL;
-    if (this.fileWriteTools.has(name)) return TOOL_KIND_FILE_WRITE;
-    if (this.readOnlyTools.has(name)) return TOOL_KIND_FILE_READ;
-    if (this.networkTools.has(name)) return TOOL_KIND_NETWORK;
-    return TOOL_KIND_GENERIC;
-  }
-
-  /**
-   * Dispatches and normalizes a tool execution request into a structured descriptor.
-   *
-   * @param {any} execution - The tool execution event carrying name, arguments, agent, session
-   * @param {any} [options] - Dynamic context overrides
-   * @returns {{
-   *   tool: string,
-   *   kind: "shell" | "file_write" | "file_read" | "network" | "generic",
-   *   isMutating: boolean,
-   *   reviewerViolation: boolean,
-   *   command?: string,
-   *   tokens?: any[],
-   *   subcommands?: string[],
-   *   git?: any,
-   *   silentError?: any,
-   *   loopback?: any,
-   *   filePath?: string,
-   *   pathSafety?: any
-   * }}
-   */
-  dispatch(execution, options = {}) {
-    const name = execution && execution.name ? String(execution.name).trim() : "";
-    const args = execution ? execution.arguments : undefined;
-    const kind = this.classifyTool(name);
-    const isReviewer = isReviewerAgent(execution, options);
-
-    const isMutating = kind === TOOL_KIND_SHELL || kind === TOOL_KIND_FILE_WRITE;
-    const reviewerViolation = isReviewer && isMutating;
-
-    const descriptor = {
-      tool: name,
-      kind,
-      isMutating,
-      reviewerViolation,
-    };
-
-    if (kind === TOOL_KIND_SHELL) {
-      const rawCommand = args && typeof args === "object" ? args.command : (typeof args === "string" ? args : "");
-      descriptor.command = typeof rawCommand === "string" ? rawCommand : "";
-
-      if (descriptor.command) {
-        const tokenized = tokenize(descriptor.command);
-        descriptor.tokens = tokenized.tokens || [];
-        descriptor.tokenizerOk = tokenized.ok;
-        descriptor.tokenizerReason = tokenized.reason;
-
-        // Subcommands breakdown
-        descriptor.subcommands = splitSubcommands(descriptor.command);
-
-        // Silent errors inspection (#90)
-        descriptor.silentError = inspectSilentErrors(descriptor.command);
-
-        // Git inspection (#125, #103)
-        if (/\bgit\b/.test(descriptor.command)) {
-          const firstWords = descriptor.command.trim().split(/\s+/);
-          descriptor.git = parseGitArgv(firstWords);
-          descriptor.gitClassification = classifyGitOperation(descriptor.git.verb, descriptor.git.args);
-        }
-
-        // Loopback detection (#40)
-        descriptor.loopback = isLoopbackCommand(descriptor.command.trim().split(/\s+/));
-      }
-    } else if (kind === TOOL_KIND_FILE_WRITE) {
-      const filePath = extractFilePath(args);
-      descriptor.filePath = filePath;
-      if (filePath) {
-        const ws = options.workspaceDir || this.workspaceDir;
-        descriptor.pathSafety = resolveSafePath(filePath, ws);
-        descriptor.isProtected = isProtectedConfigPath(descriptor.pathSafety.canonical || filePath);
-        descriptor.isTraversal = !descriptor.pathSafety.safe;
-      }
-    } else if (kind === TOOL_KIND_NETWORK) {
-      const url = args && typeof args === "object" ? (args.url || args.Url || args.uri || args.Uri) : "";
-      descriptor.url = typeof url === "string" ? url : "";
-      if (descriptor.url) {
-        descriptor.isLoopback = isLoopbackUrl(descriptor.url);
-      }
-    }
-
-    return descriptor;
-  }
+// lib/dispatcher.js
+// Command Dispatcher: architectural isolation of command parsing and syntactic dispatch
+// from the safety evaluation engine.
+// Resolves: #133, #65
+
+import { tokenize, splitSubcommands } from "./tokenizer.js";
+import { parseGitArgv, classifyGitOperation } from "./parsers/git.js";
+import { extractRedirects, inspectRedirectSecurity, inspectSilentErrors, inspectPipelines } from "./parsers/shell-cmds.js";
+import { isLoopbackCommand, isLoopbackUrl } from "./loopback.js";
+import { resolveSafePath, isPathTraversal, isProtectedConfigPath } from "./paths.js";
+
+export const TOOL_KIND_SHELL = "shell";
+export const TOOL_KIND_FILE_WRITE = "file_write";
+export const TOOL_KIND_FILE_READ = "file_read";
+export const TOOL_KIND_NETWORK = "network";
+export const TOOL_KIND_GENERIC = "generic";
+
+export const DEFAULT_BASH_TOOL = "bash";
+export const DEFAULT_FILE_WRITE_TOOLS = Object.freeze([
+  "write",
+  "edit",
+  "Write",
+  "Edit",
+  "write_to_file",
+  "replace_file_content",
+  "str_replace_editor",
+  "str_replace",
+  "apply_patch",
+]);
+
+export const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
+  "read_file",
+  "view_file",
+  "read_url_content",
+  "search_web",
+  "list_dir",
+  "glob",
+  "grep",
+]);
+
+export const DEFAULT_NETWORK_TOOLS = Object.freeze([
+  "fetch",
+  "web_fetch",
+  "http_request",
+  "read_url_content",
+]);
+
+/**
+ * Extracts target file path from various tool argument schemas.
+ *
+ * @param {any} args
+ * @returns {string | null}
+ */
+export function extractFilePath(args) {
+  if (typeof args === "string") return args;
+  if (!args || typeof args !== "object") return null;
+  const keys = [
+    "path",
+    "file_path",
+    "filePath",
+    "file",
+    "filename",
+    "target",
+    "to",
+    "TargetFile",
+    "AbsolutePath",
+  ];
+  for (const k of keys) {
+    if (typeof args[k] === "string" && args[k].trim()) {
+      return args[k].trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Checks whether an execution originates from a designated read-only reviewer agent.
+ * Resolves: #65 (strict read-only reviewer subagent isolation).
+ *
+ * @param {any} execution
+ * @param {any} [options]
+ * @returns {boolean}
+ */
+export function isReviewerAgent(execution, options = {}) {
+  if (options && options.reviewerMode === true) return true;
+  const agent = execution && execution.agent;
+  if (!agent) return false;
+
+  const role = typeof agent.role === "string" ? agent.role.toLowerCase() : "";
+  const name = typeof agent.name === "string" ? agent.name.toLowerCase() : "";
+  const type = typeof agent.type === "string" ? agent.type.toLowerCase() : "";
+
+  return role.includes("review") || name.includes("review") || type.includes("review");
+}
+
+export class CommandDispatcher {
+  /**
+   * @param {{
+   *   toolName?: string,
+   *   fileWriteTools?: string[] | Set<string>,
+   *   readOnlyTools?: string[] | Set<string>,
+   *   networkTools?: string[] | Set<string>,
+   *   workspaceDir?: string
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.toolName = options.toolName || DEFAULT_BASH_TOOL;
+    this.fileWriteTools = new Set(options.fileWriteTools || DEFAULT_FILE_WRITE_TOOLS);
+    this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
+    this.networkTools = new Set(options.networkTools || DEFAULT_NETWORK_TOOLS);
+    this.workspaceDir = options.workspaceDir || process.cwd();
+  }
+
+  /**
+   * Categorizes the tool name into functional kind.
+   *
+   * @param {string} name
+   * @returns {"shell" | "file_write" | "file_read" | "network" | "generic"}
+   */
+  classifyTool(name) {
+    if (!name) return TOOL_KIND_GENERIC;
+    if (name === this.toolName) return TOOL_KIND_SHELL;
+    if (this.fileWriteTools.has(name)) return TOOL_KIND_FILE_WRITE;
+    if (this.readOnlyTools.has(name)) return TOOL_KIND_FILE_READ;
+    if (this.networkTools.has(name)) return TOOL_KIND_NETWORK;
+    return TOOL_KIND_GENERIC;
+  }
+
+  /**
+   * Dispatches and normalizes a tool execution request into a structured descriptor.
+   *
+   * @param {any} execution - The tool execution event carrying name, arguments, agent, session
+   * @param {any} [options] - Dynamic context overrides
+   * @returns {{
+   *   tool: string,
+   *   kind: "shell" | "file_write" | "file_read" | "network" | "generic",
+   *   isMutating: boolean,
+   *   reviewerViolation: boolean,
+   *   command?: string,
+   *   tokens?: any[],
+   *   subcommands?: string[],
+   *   git?: any,
+   *   silentError?: any,
+   *   loopback?: any,
+   *   filePath?: string,
+   *   pathSafety?: any
+   * }}
+   */
+  dispatch(execution, options = {}) {
+    const name = execution && execution.name ? String(execution.name).trim() : "";
+    const args = execution ? execution.arguments : undefined;
+    const kind = this.classifyTool(name);
+    const isReviewer = isReviewerAgent(execution, options);
+
+    const isMutating = kind === TOOL_KIND_SHELL || kind === TOOL_KIND_FILE_WRITE;
+    const reviewerViolation = isReviewer && isMutating;
+
+    const descriptor = {
+      tool: name,
+      kind,
+      isMutating,
+      reviewerViolation,
+    };
+
+    if (kind === TOOL_KIND_SHELL) {
+      const rawCommand = args && typeof args === "object" ? args.command : (typeof args === "string" ? args : "");
+      descriptor.command = typeof rawCommand === "string" ? rawCommand : "";
+
+      if (descriptor.command) {
+        const tokenized = tokenize(descriptor.command);
+        descriptor.tokens = tokenized.tokens || [];
+        descriptor.tokenizerOk = tokenized.ok;
+        descriptor.tokenizerReason = tokenized.reason;
+
+        // Subcommands breakdown
+        descriptor.subcommands = splitSubcommands(descriptor.command);
+
+        // Silent errors inspection (#90)
+        descriptor.silentError = inspectSilentErrors(descriptor.command);
+
+        // Git inspection (#125, #103)
+        if (/\bgit\b/.test(descriptor.command)) {
+          const firstWords = descriptor.command.trim().split(/\s+/);
+          descriptor.git = parseGitArgv(firstWords);
+          descriptor.gitClassification = classifyGitOperation(descriptor.git.verb, descriptor.git.args);
+        }
+
+        // Loopback detection (#40)
+        descriptor.loopback = isLoopbackCommand(descriptor.command.trim().split(/\s+/));
+      }
+    } else if (kind === TOOL_KIND_FILE_WRITE) {
+      const filePath = extractFilePath(args);
+      descriptor.filePath = filePath;
+      if (filePath) {
+        const ws = options.workspaceDir || this.workspaceDir;
+        descriptor.pathSafety = resolveSafePath(filePath, ws);
+        descriptor.isProtected = isProtectedConfigPath(descriptor.pathSafety.canonical || filePath);
+        descriptor.isTraversal = !descriptor.pathSafety.safe;
+      }
+    } else if (kind === TOOL_KIND_NETWORK) {
+      const url = args && typeof args === "object" ? (args.url || args.Url || args.uri || args.Uri) : "";
+      descriptor.url = typeof url === "string" ? url : "";
+      if (descriptor.url) {
+        descriptor.isLoopback = isLoopbackUrl(descriptor.url);
+      }
+    }
+
+    return descriptor;
+  }
 }

package/lib/engine.js

@@ -17,6 +17,11 @@ import { QualityLedger } from "./ledger.js";
 import { AuditLogger } from "./audit-log.js";
 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 { categorizeRiskBucket, extractRiskTags } from "./risk.js";
+import { ClassifierLatencyTracker } from "./latency.js";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -112,6 +117,15 @@ export class SecurityEngine {
     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);
   }
 
   /**
@@ -141,9 +155,9 @@ export class SecurityEngine {
         if (this.auditLogger) this.auditLogger.appendAuditLine({ 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 this._enrichDecision({ verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit }, execution, context);
         }
-        return exhDecision;
+        return this._enrichDecision(exhDecision, execution, context);
       }
 
       // Check Verdict Cache (#63, #119)
@@ -152,7 +166,7 @@ export class SecurityEngine {
         const cached = this.cache.get(cacheKey);
         if (cached) {
           if (this.dryRun && (cached.verdict === "deny" || cached.verdict === "ask")) {
-            return {
+            return this._enrichDecision({
               verdict: "allow",
               stage: cached.stage,
               dryRun: true,
@@ -161,14 +175,15 @@ export class SecurityEngine {
               detail: cached.detail,
               hit: cached.hit,
               cached: true,
-            };
+            }, execution, context);
           }
           if (this.counters) this.counters.record(cached, execution);
-          return cached;
+          return this._enrichDecision(cached, execution, context);
         }
       }
 
       let decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
+      this._enrichDecision(decision, execution, context);
 
       // Post-decision hooks: ledger, retryGuard, cache
       if (decision.verdict === "deny") {
@@ -201,6 +216,7 @@ export class SecurityEngine {
             hit: auditDenyHit,
             auditFailed: true,
           };
+          this._enrichDecision(decision, execution, context);
         }
       }
 
@@ -211,7 +227,7 @@ export class SecurityEngine {
 
       // Shadow Mode (#128)
       if (this.dryRun && (decision.verdict === "deny" || decision.verdict === "ask")) {
-        return {
+        return this._enrichDecision({
           verdict: "allow",
           stage: decision.stage,
           dryRun: true,
@@ -220,7 +236,7 @@ export class SecurityEngine {
           detail: decision.detail,
           hit: decision.hit,
           lockedAsk: decision.lockedAsk,
-        };
+        }, execution, context);
       }
 
       return decision;
@@ -233,12 +249,12 @@ export class SecurityEngine {
         hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
       };
       if (this.counters) this.counters.record(errDecision, execution);
-      return errDecision;
+      return this._enrichDecision(errDecision, execution, context);
     }
   }
 
   /**
-   * Asynchronous evaluation supporting async classifiers (#129, #118).
+   * Asynchronous evaluation supporting async classifiers and latency SLA tracking (#129, #118, #57).
    *
    * @param {{ name: string, arguments?: any }} execution
    * @param {{ sessionId?: string, knobs?: any, cwd?: string }} [context]
@@ -248,15 +264,31 @@ export class SecurityEngine {
     if (this.classifier) {
       let resolvedVerdict = null;
       let caughtError = null;
-      try {
-        if (typeof this.classifier.classify === "function") {
-          resolvedVerdict = await this.classifier.classify(execution, context);
-        } else if (typeof this.classifier === "function") {
-          const res = this.classifier(execution, context);
-          resolvedVerdict = res && typeof res.then === "function" ? await res : res;
+
+      if (this.latencyTracker && this.latencyTracker.isDegraded()) {
+        resolvedVerdict = {
+          verdict: "ask",
+          reason: "classifier-sla-fallback",
+          detail: `Classifier latency p95 (${this.latencyTracker.getP95()}ms) exceeded SLA (${this.latencyTracker.slaMs}ms) (#57)`,
+        };
+      } else {
+        const start = Date.now();
+        try {
+          if (typeof this.classifier.classify === "function") {
+            resolvedVerdict = await this.classifier.classify(execution, context);
+          } else if (typeof this.classifier === "function") {
+            const res = this.classifier(execution, context);
+            resolvedVerdict = res && typeof res.then === "function" ? await res : res;
+          }
+          if (this.latencyTracker) {
+            this.latencyTracker.recordSample(Date.now() - start);
+          }
+        } catch (err) {
+          caughtError = err;
+          if (this.latencyTracker) {
+            this.latencyTracker.recordSample(Date.now() - start);
+          }
         }
-      } catch (err) {
-        caughtError = err;
       }
 
       const originalClassifier = this.classifier;
@@ -316,6 +348,42 @@ export class SecurityEngine {
       return { verdict: "deny", stage: "P0", reason: hit.reason || "hard-deny", detail: hit.detail || hit.snippet, hit };
     }
 
+    // Task Contract Guard (#87)
+    if (this.contractGuard) {
+      const cg = this.contractGuard.check(toolName, command, execution);
+      if (!cg.allowed) {
+        const cgHit = {
+          ask: true,
+          reason: cg.reason || "contract-violation",
+          detail: cg.detail,
+          snippet: cg.snippet || command || toolName,
+        };
+        const res = { verdict: "ask", stage: "P4", reason: cg.reason || "contract-violation", detail: cg.detail, hit: cgHit };
+        this._applyLockedAskIfCritical(res, toolName, command, execution);
+        return res;
+      }
+    }
+
+    // Overengineering Guard (#89)
+    const fileTools = new Set(this.inspectConfig?.fileWriteTools || DEFAULT_FILE_WRITE_TOOLS);
+    if (this.overengineeringGuard && typeof toolName === "string" && fileTools.has(toolName)) {
+      const targetPath = extractFilePath(execution ? execution.arguments : undefined);
+      if (targetPath) {
+        const og = this.overengineeringGuard.checkAndRecord(sessionId, targetPath);
+        if (!og.allowed) {
+          const ogHit = {
+            ask: true,
+            reason: og.reason || "overengineering-file-limit",
+            detail: og.detail,
+            snippet: targetPath,
+          };
+          const res = { verdict: "ask", stage: "P4", reason: og.reason || "overengineering-file-limit", detail: og.detail, hit: ogHit };
+          this._applyLockedAskIfCritical(res, toolName, command, execution);
+          return res;
+        }
+      }
+    }
+
     // P1: Session Grants
     if (this.grantRegistry && typeof this.grantRegistry.decide === "function") {
       const grantMatch = this.grantRegistry.decide(toolName, execution.arguments, context);
@@ -458,7 +526,32 @@ export class SecurityEngine {
 
   resume(sessionId, reason) {
     if (this.retryGuard) this.retryGuard.reset(sessionId);
+    if (this.overengineeringGuard) this.overengineeringGuard.reset(sessionId);
     if (this.cache) this.cache.clearSession(sessionId);
     return this.breaker.resume(sessionId, reason);
   }
+
+  /**
+   * Enriches decision with risk bucket (#58) and operational risk tags (#70).
+   * @private
+   */
+  _enrichDecision(decision, execution, context) {
+    if (!decision) return decision;
+    if (!decision.riskBucket) {
+      decision.riskBucket = categorizeRiskBucket(execution, context);
+    }
+    if (!decision.riskTags || !Array.isArray(decision.riskTags)) {
+      decision.riskTags = extractRiskTags(execution, context);
+    }
+    return decision;
+  }
+
+  getLatencyMetrics() {
+    return this.latencyTracker ? this.latencyTracker.getMetrics() : null;
+  }
+
+  resetLatencyTracker() {
+    if (this.latencyTracker) this.latencyTracker.reset();
+  }
 }
+