@goodandready/dsh-approval-gate 0.1.20 → 0.1.22

package/lib/index.js

@@ -5,6 +5,12 @@ 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 { LineageManager } from "./lineage.js";
+import { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
+import { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification } from "./escalation.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -180,6 +186,16 @@ export function readKnobs(ctx, execution) {
     }
   }
 
+  // 5b. Lineage authority inheritance (#98)
+  if (!policy && session && (session.parentSession || session.parentId || session.parentSessionId)) {
+    const parent = session.parentSession || { id: session.parentId || session.parentSessionId };
+    if (typeof parent.approvalPolicy === "string") {
+      policy = parent.approvalPolicy;
+    } else if (approval && typeof approval.effectivePolicy === "function") {
+      try { policy = approval.effectivePolicy(parent) || ""; } catch {}
+    }
+  }
+
   // 6. Global static fallback from approval service config
   if (!policy && approval && approval.config && approval.config.policy) {
     policy = approval.config.policy;
@@ -208,8 +224,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). */
@@ -246,6 +266,10 @@ export const Config = Schema.object({
   agentsRules: Schema.boolean().default(true).volatile(),
   /** Enforce human confirmation on breaking major dependency bumps in package.json (#95). */
   versionGuard: Schema.boolean().default(true).volatile(),
+  /** Require explicit justification for privilege escalation (#107). */
+  requireJustification: Schema.boolean().default(false).volatile(),
+  /** Enable automatic remediation advice for redundant sandbox privilege requests (#101). */
+  enableRedundantSandboxRecovery: Schema.boolean().default(true).volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -313,7 +337,10 @@ export function apply(ctx, config) {
     latencyTracker: new ClassifierLatencyTracker({
       slaMs: cfg.classifierSlaMs !== undefined ? cfg.classifierSlaMs : 2000,
     }),
-    defaultVerdict: cfg.defaultVerdict || "allow",
+    defaultVerdict: cfg.defaultVerdict || "ask",
+    requireJustification: cfg.requireJustification === true,
+    enableRedundantSandboxRecovery: cfg.enableRedundantSandboxRecovery !== false,
+    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 +369,26 @@ 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),
+    lineage: engine.lineage,
+    registerLineage: (child, parent, root) => engine.registerLineage(child, parent, root),
+    getLineage: (id) => engine.getLineage(id),
+    guidance: {
+      generate: (opts) => generateAgentGuidance(opts),
+      inject: (prompt, opts) => injectAgentGuidance(prompt, opts),
+      extract: (prompt) => extractGuidance(prompt),
+    },
+    getAgentGuidance: (opts) => generateAgentGuidance(opts),
+    redundantSandbox: {
+      check: (cmd, mode, opts) => isRedundantSandboxRequest(cmd, mode, opts),
+      remediation: (cmd, lang) => buildRedundantSandboxRemediation(cmd, lang),
+    },
+    checkEscalationJustification: (cmd, tool, args, opts) => checkEscalationJustification(cmd, tool, args, opts),
     getSnapshot: () => ({
       active: true,
       dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
@@ -353,6 +400,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,
     }),
   };
@@ -364,9 +412,12 @@ export function apply(ctx, config) {
       const knobs = readKnobs(ctx, execution);
       const who = sessionTag(execution);
       const sessionId = resolveSessionId(execution);
+      const callId = execution?.callId || execution?.id || null;
+      const agentId = execution?.agent?.id || execution?.agentId || null;
+      const subagentId = execution?.agent?.subagentId || execution?.subagentId || null;
       let decision;
       try {
-        decision = engine.decide(execution, { sessionId, knobs });
+        decision = engine.decide(execution, { sessionId, knobs, callId, agentId, subagentId, sandboxMode: knobs.sandbox, preset: knobs.preset });
       } catch (err) {
         const hit = {
           ask: true,
@@ -418,6 +469,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();
     });
   }
@@ -425,9 +480,12 @@ export function apply(ctx, config) {
   const guard = function (execution) {
     const who = sessionTag(execution);
     const sessionId = resolveSessionId(execution);
+    const callId = execution?.callId || execution?.id || null;
+    const agentId = execution?.agent?.id || execution?.agentId || null;
+    const subagentId = execution?.agent?.subagentId || execution?.subagentId || null;
     let decision;
     try {
-      decision = engine.decide(execution, { sessionId });
+      decision = engine.decide(execution, { sessionId, callId, agentId, subagentId });
     } catch (err) {
       const hit = {
         deny: true,
@@ -455,6 +513,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 +538,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 +570,11 @@ 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";
+export { LineageManager } from "./lineage.js";
+export { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
+export { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification, REDUNDANT_SANDBOX_REASON, MISSING_JUSTIFICATION_REASON, INSUFFICIENT_JUSTIFICATION_REASON } from "./escalation.js";
+
 
 

package/lib/lineage.js

@@ -0,0 +1,182 @@
+// lib/lineage.js
+// Subagent hierarchy and parentSession lineage authority (#98).
+// Tracks session ancestry trees and propagates authority/policies down the lineage chain.
+
+export class LineageManager {
+  constructor() {
+    /** @type {Map<string, string>} childSessionId -> parentSessionId */
+    this.parentMap = new Map();
+    /** @type {Map<string, string>} childSessionId -> explicit rootSessionId */
+    this.rootMap = new Map();
+    /** @type {Map<string, Set<string>>} parentSessionId -> Set of childSessionIds */
+    this.childrenMap = new Map();
+  }
+
+  /**
+   * Registers parent-child session relationship.
+   * Prevents circular parent-child references.
+   *
+   * @param {string} childSessionId
+   * @param {string} parentSessionId
+   * @param {string} [rootSessionId]
+   * @returns {boolean} True if successfully registered, false if invalid or circular
+   */
+  registerLineage(childSessionId, parentSessionId, rootSessionId = null) {
+    if (!childSessionId || !parentSessionId) return false;
+    if (childSessionId === parentSessionId) return false;
+
+    // Check circular references: walking upwards from parent must not reach child
+    let curr = parentSessionId;
+    const visited = new Set([childSessionId]);
+    while (curr) {
+      if (visited.has(curr)) return false;
+      visited.add(curr);
+      curr = this.parentMap.get(curr);
+    }
+
+    this.parentMap.set(childSessionId, parentSessionId);
+    if (rootSessionId && rootSessionId !== childSessionId) {
+      this.rootMap.set(childSessionId, rootSessionId);
+    }
+
+    if (!this.childrenMap.has(parentSessionId)) {
+      this.childrenMap.set(parentSessionId, new Set());
+    }
+    this.childrenMap.get(parentSessionId).add(childSessionId);
+
+    return true;
+  }
+
+  /**
+   * Retrieves the direct parent session ID for a session.
+   * @param {string} sessionId
+   * @returns {string|null}
+   */
+  getParent(sessionId) {
+    if (!sessionId) return null;
+    return this.parentMap.get(sessionId) || null;
+  }
+
+  /**
+   * Retrieves the ultimate root session ID for a session.
+   * @param {string} sessionId
+   * @returns {string}
+   */
+  getRoot(sessionId) {
+    if (!sessionId) return "";
+    if (this.rootMap.has(sessionId)) {
+      return this.rootMap.get(sessionId);
+    }
+
+    let curr = sessionId;
+    const visited = new Set();
+    while (curr && !visited.has(curr)) {
+      visited.add(curr);
+      const parent = this.parentMap.get(curr);
+      if (!parent) break;
+      curr = parent;
+    }
+    return curr;
+  }
+
+  /**
+   * Returns ancestry array from current session up to root: [sessionId, parentId, ..., rootId].
+   * @param {string} sessionId
+   * @returns {string[]}
+   */
+  getLineage(sessionId) {
+    if (!sessionId) return [];
+    const chain = [];
+    let curr = sessionId;
+    const visited = new Set();
+
+    while (curr && !visited.has(curr)) {
+      visited.add(curr);
+      chain.push(curr);
+      curr = this.parentMap.get(curr);
+    }
+
+    return chain;
+  }
+
+  /**
+   * Checks whether ancestorSessionId is an ancestor of childSessionId.
+   * @param {string} childSessionId
+   * @param {string} ancestorSessionId
+   * @returns {boolean}
+   */
+  hasLineageAuthority(childSessionId, ancestorSessionId) {
+    if (!childSessionId || !ancestorSessionId) return false;
+    if (childSessionId === ancestorSessionId) return true;
+
+    const lineage = this.getLineage(childSessionId);
+    return lineage.includes(ancestorSessionId);
+  }
+
+  /**
+   * Resolves effective policy walking up the lineage hierarchy.
+   * Evaluates getPolicyFn(sessionId). If undefined or null, falls back to parent, then root.
+   *
+   * @param {string} sessionId
+   * @param {(id: string) => any} getPolicyFn
+   * @returns {any}
+   */
+  resolveEffectivePolicy(sessionId, getPolicyFn) {
+    if (!sessionId || typeof getPolicyFn !== "function") return null;
+
+    const lineage = this.getLineage(sessionId);
+    for (const sid of lineage) {
+      try {
+        const policy = getPolicyFn(sid);
+        if (policy !== undefined && policy !== null) {
+          return {
+            policy,
+            sourceSessionId: sid,
+            inherited: sid !== sessionId,
+          };
+        }
+      } catch {
+        // Continue upward traversal on error
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Removes tracking for a session and unlinks from its parent.
+   * @param {string} sessionId
+   * @returns {boolean}
+   */
+  clearSession(sessionId) {
+    if (!sessionId) return false;
+    const parent = this.parentMap.get(sessionId);
+    if (parent && this.childrenMap.has(parent)) {
+      this.childrenMap.get(parent).delete(sessionId);
+    }
+    this.parentMap.delete(sessionId);
+    this.rootMap.delete(sessionId);
+    this.childrenMap.delete(sessionId);
+    return true;
+  }
+
+  /**
+   * Clears all lineage mappings.
+   */
+  clearAll() {
+    this.parentMap.clear();
+    this.rootMap.clear();
+    this.childrenMap.clear();
+  }
+
+  /**
+   * Returns current statistics for debugging and auditing.
+   * @returns {{ trackedSessions: number, rootSessions: number }}
+   */
+  getStats() {
+    return {
+      trackedSessions: this.parentMap.size,
+      parentCount: this.childrenMap.size,
+    };
+  }
+}

package/lib/measure-kinds.js

@@ -0,0 +1,138 @@
+// 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;
+  if (typeof execution === "string") {
+    execution = { name: "bash", arguments: { command: execution } };
+  }
+
+  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;
+}