@goodandready/dsh-approval-gate 0.1.19 → 0.1.21

package/lib/engine.js

@@ -1,11 +1,5 @@
 // lib/engine.js
-// 5-tier Security Decision Engine for dsh-approval-gate.
-// Waterfall:
-// P0: Hard Deny (Bands Band 0 + Declarative Rules Deny + inspectExecution hard denials + protected files + retry exhaustion + fail-closed audit)
-// 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 / declarative ask / lockedAsk)
+// 5-tier Security Decision Engine for dsh-approval-gate (P0-P4 Waterfall).
 
 import { BandsEngine } from "./bands.js";
 import { CircuitBreaker } from "./breaker.js";
@@ -19,9 +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).
@@ -73,26 +73,7 @@ export function isCriticalOperation(toolName, command, execution) {
 }
 
 export class SecurityEngine {
-  /**
-   * @param {{
-   *   bands?: BandsEngine,
-   *   breaker?: CircuitBreaker,
-   *   cache?: VerdictCache,
-   *   retryGuard?: RetryExhaustionGuard,
-   *   ledger?: QualityLedger,
-   *   auditLogger?: AuditLogger,
-   *   declarativeRules?: DeclarativeRulesEngine,
-   *   counters?: BlockCounters,
-   *   auditFailClosed?: boolean,
-   *   timeoutPolicy?: "strict" | "permissive",
-   *   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" },
-   *   dryRun?: boolean,
-   *   shadowMode?: boolean,
-   *   defaultVerdict?: "allow" | "ask"
-   * }} [options]
-   */
+  /** @param {Record<string, any>} [options] */
   constructor(options = {}) {
     this.bands = options.bands || new BandsEngine(options);
     this.breaker = options.breaker || new CircuitBreaker(options);
@@ -100,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;
@@ -108,24 +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.snapshotManager = options.snapshotManager !== undefined ? options.snapshotManager : new SnapshotManager({ workspaceDir: this.inspectConfig?.workspaceDir });
   }
 
   /**
@@ -194,6 +167,10 @@ export class SecurityEngine {
         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 });
+        if (this.artifactRegistry) {
+          const targetPath = extractFilePath(execution && execution.arguments);
+          if (targetPath) this.artifactRegistry.recordArtifact(sessionId, targetPath);
+        }
       } else if (decision.verdict === "ask") {
         if (this.ledger) this.ledger.record(sessionId, "ask", { reason: decision.reason, detail: decision.detail, tool: toolName });
       }
@@ -341,6 +318,16 @@ export class SecurityEngine {
       }
     }
 
+    // AGENTS.md rules (#91)
+    if (this.agentsRules) {
+      const ag = evaluateAgentsRules(this.agentsRules, execution, extractFilePath(execution && execution.arguments));
+      if (ag.match) {
+        this.breaker.countDeny(sessionId);
+        const agHit = { deny: true, reason: ag.reason, detail: ag.rule?.text, snippet: command || toolName };
+        return { verdict: "deny", stage: "P0", reason: ag.reason, detail: ag.rule?.text, hit: agHit };
+      }
+    }
+
     // Inspect execution for hard denials and syntax checks
     const hit = inspectExecution(execution, this.inspectConfig);
     if (hit.deny) {
@@ -384,6 +371,31 @@ export class SecurityEngine {
       }
     }
 
+    // VersionGuard: major version bump control (#95)
+    if (this.versionGuard && typeof toolName === "string" && fileTools.has(toolName)) {
+      const targetPath = extractFilePath(execution ? execution.arguments : undefined);
+      const content = execution?.arguments?.content || execution?.arguments?.code || execution?.arguments?.CodeContent || execution?.arguments?.text;
+      if (targetPath && content) {
+        const vg = this.versionGuard.inspectWrite(targetPath, content);
+        if (vg.majorBump) {
+          const vgHit = { ask: true, reason: "major-version-bump", detail: vg.detail, snippet: targetPath };
+          const res = { verdict: "ask", stage: "P4", reason: "major-version-bump", detail: vg.detail, hit: vgHit };
+          this._applyLockedAskIfCritical(res, toolName, command, execution);
+          return res;
+        }
+      }
+    }
+
+    // P1: Session Artifact Cleanup Whitelist (#100)
+    if (command && isRmCommand(command)) {
+      const targets = extractRmTargets(command);
+      if (targets.length > 0 && this.artifactRegistry && this.artifactRegistry.areAllSessionArtifacts(sessionId, targets)) {
+        this.breaker.resetConsecutive(sessionId);
+        const artHit = { allow: true, reason: "session-artifact-cleanup", snippet: command };
+        return { verdict: "allow", stage: "P1", reason: "session-artifact-cleanup", hit: artHit };
+      }
+    }
+
     // P1: Session Grants
     if (this.grantRegistry && typeof this.grantRegistry.decide === "function") {
       const grantMatch = this.grantRegistry.decide(toolName, execution.arguments, context);
@@ -466,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);
@@ -537,21 +551,25 @@ export class SecurityEngine {
    */
   _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);
+    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);
     }
     return decision;
   }
 
-  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

@@ -4,6 +4,10 @@ import { AuditLogger } from "./audit-log.js";
 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") {
@@ -207,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). */
@@ -241,6 +249,10 @@ export const Config = Schema.object({
   classifierSlaMs: Schema.number().default(2000).volatile(),
   /** Task contract boundary rules (#87). */
   taskContract: Schema.any().volatile(),
+  /** Enforce project rules and constraints parsed from AGENTS.md (#91). */
+  agentsRules: Schema.boolean().default(true).volatile(),
+  /** Enforce human confirmation on breaking major dependency bumps in package.json (#95). */
+  versionGuard: Schema.boolean().default(true).volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -251,6 +263,7 @@ function logBlocked(ctx, hit, who) {
 }
 
 export function apply(ctx, config) {
+  const compat = assertHarnessCompatibility(ctx);
   const cfg = plainConfig(Config(plainConfig(config) || {}) || {});
   const toolName = cfg.toolName || DEFAULT_BASH_TOOL;
   const fileWriteTools = cfg.fileWriteTools || DEFAULT_FILE_WRITE_TOOLS.slice();
@@ -307,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({
@@ -334,6 +348,14 @@ export function apply(ctx, config) {
     getLedgerSummary: (sessionId) => engine.getLedgerSummary(sessionId),
     getLatencyMetrics: () => (engine.getLatencyMetrics ? engine.getLatencyMetrics() : null),
     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),
@@ -345,15 +367,11 @@ 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,
     }),
   };
-  if (ctx && typeof ctx === "object") {
-    if (typeof ctx.provide === "function") {
-      ctx.provide("approvalGate", gateService);
-    } else {
-      ctx.approvalGate = gateService;
-    }
-  }
+  provideServicePolyfill(ctx, "approvalGate", gateService);
 
   const hasPreExecute = ctx && typeof ctx.on === "function";
   if (hasPreExecute) {
@@ -415,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();
     });
   }
@@ -452,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;
   };
 
@@ -473,105 +499,40 @@ 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 { 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 { ContractGuard } from "./contract-guard.js";
 export { OverengineeringGuard, DEFAULT_MAX_FILES_PER_SESSION } from "./overengineering.js";
 export { resolveTempRoot, isGlobalTempPath, checkTempIsolation } from "./paths.js";
 export { computePayloadSize, scanPromptInjection } from "./inspect.js";
 export { RISK_BUCKETS, RISK_TAGS, categorizeRiskBucket, extractRiskTags } from "./risk.js";
 export { ClassifierLatencyTracker, DEFAULT_CLASSIFIER_SLA_MS } from "./latency.js";
+export { resolveTrashDir, isRmCommand, extractRmTargets, buildTrashCommand, suggestTrashAlternative } from "./trash.js";
+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;
+}