@goodandready/dsh-approval-gate 0.1.19 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.20
+
+- Feature: Безопасная альтернатива необратимому удалению (`Reversible Trash Move` в `lib/trash.js`) с переносом удаляемых файлов в изолированную сессионную корзину `<workspace>/.dsh/trash/<session_id>/` вместо деструктивного `rm` (Refs: #104).
+- Feature: Реестр сессионных артефактов (`ArtifactRegistry` в `lib/artifacts.js`) для автоматического отслеживания и безопасного разрешения очистки временных файлов текущей сессии на стадии P1 без спама подтверждениями (Refs: #100).
+- Security: Парсер проектных правил безопасности из `AGENTS.md` (`lib/agents-parser.js`) с жестким перехватом запрещенных команд и путей на стадии P0 (`agents-md-prohibited-command`, `agents-md-prohibited-path` -> `deny`) (Refs: #91).
+- Resilience: Проверка совместимости версий хоста DSH (`assertHarnessCompatibility` в `lib/compat.js`) и безопасные полифилы `provideServicePolyfill` / `registerHookPolyfill` для бесшовной работы на различных версиях Cordis (Refs: #106).
+- Security: Страж зависимостей проекта (`VersionGuard` в `lib/version-guard.js`) с автоматическим обнаружением мажорных обновлений в `package.json` и переводом их на ручное подтверждение человеком (`major-version-bump` -> `ask`) (Refs: #95).
+
 ## 0.1.19
 
 - Security: Структурированная категоризация рисков операций по 5 стандартизированным бакетам (`READ_ONLY`, `WORKSPACE`, `EGRESS`, `SYSTEM`, `SECRETS`) в `lib/risk.js` с приоритетной оценкой чувствительности путей, команд и сетевых направлений (Refs: #58).

package/lib/agents-parser.js

@@ -0,0 +1,183 @@
+// lib/agents-parser.js
+// Parser and enforcement for local project safety rules from AGENTS.md / CLAUDE.md (#91).
+
+import fs from "node:fs";
+import path from "node:path";
+
+const AGENTS_FILENAMES = ["AGENTS.md", ".dsh/AGENTS.md", "CLAUDE.md"];
+
+const SECURITY_HEADING_REGEX = /^(?:#{1,3})\s*(?:security|safety|rules|constraints|prohibited|forbidden|restrictions|do\s+not|never)\b/i;
+
+const FORBIDDEN_DIRECTIVE_REGEX = /(?:(?:never|do\s+not|don't|prohibit(?:ed)?|forbid(?:den)?|cannot|must\s+not)\s+(?:run|execute|use|modify|delete|touch|access|call|write)|forbidden:\s*|prohibited:\s*)/i;
+
+/**
+ * Parses markdown text of AGENTS.md and extracts active security constraints (#91).
+ *
+ * @param {string} content - Markdown document text
+ * @returns {{
+ *   rules: Array<{ type: "command" | "path" | "keyword" | "directive", pattern: string, text: string }>,
+ *   rawDirectives: string[]
+ * }}
+ */
+export function parseAgentsSecurityRules(content) {
+  if (typeof content !== "string" || !content.trim()) {
+    return { rules: [], rawDirectives: [] };
+  }
+
+  const lines = content.split(/\r?\n/);
+  const rules = [];
+  const rawDirectives = [];
+
+  let inSecuritySection = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    const trimmed = rawLine.trim();
+
+    // Check headings
+    if (trimmed.startsWith("#")) {
+      inSecuritySection = SECURITY_HEADING_REGEX.test(trimmed);
+      continue;
+    }
+
+    if (!trimmed) continue;
+
+    // Check bullet points or bold directives in security section or explicit global directives
+    const isBullet = /^[-*+]\s+/.test(trimmed) || /^\d+\.\s+/.test(trimmed);
+    const cleanText = trimmed.replace(/^[-*+]\s+/, "").replace(/^\d+\.\s+/, "").trim();
+
+    if ((inSecuritySection && isBullet) || FORBIDDEN_DIRECTIVE_REGEX.test(cleanText)) {
+      rawDirectives.push(cleanText);
+
+      // 1. Check for command / tool restriction: e.g. `Never run rm -rf`, `Do not execute curl`
+      const cmdMatch = /(?:run|execute|use|call)\s+(?:`([^`]+)`|"([^"]+)"|([a-zA-Z0-9_\-\.\/]+(?:\s+[a-zA-Z0-9_\-\.\/]+)?))/i.exec(cleanText);
+      if (cmdMatch) {
+        const cmdPattern = (cmdMatch[1] || cmdMatch[2] || cmdMatch[3]).trim();
+        if (cmdPattern && !["to", "the", "a", "an", "any", "this"].includes(cmdPattern.toLowerCase())) {
+          rules.push({
+            type: "command",
+            pattern: cmdPattern,
+            text: cleanText,
+          });
+          continue;
+        }
+      }
+
+      // 2. Check for path restriction: e.g. `Do not modify package.json`, `Do not touch .env`
+      const pathMatch = /(?:modify|edit|delete|write|overwrite|touch)\s+(?:`([^`]+)`|"([^"]+)"|([a-zA-Z0-9_\-\.\/\*]+))/i.exec(cleanText);
+      if (pathMatch) {
+        const pathPattern = (pathMatch[1] || pathMatch[2] || pathMatch[3]).trim();
+        if (pathPattern && !["to", "the", "a", "an", "any", "this"].includes(pathPattern.toLowerCase())) {
+          rules.push({
+            type: "path",
+            pattern: pathPattern,
+            text: cleanText,
+          });
+          continue;
+        }
+      }
+
+      // 3. Fallback general directive
+      rules.push({
+        type: "directive",
+        pattern: cleanText,
+        text: cleanText,
+      });
+    }
+  }
+
+  return { rules, rawDirectives };
+}
+
+/**
+ * Loads and parses AGENTS.md rules from a workspace directory (#91).
+ *
+ * @param {string} [workspaceDir]
+ * @returns {{ rules: Array<any>, rawDirectives: string[], filePath?: string } | null}
+ */
+export function loadAgentsRules(workspaceDir) {
+  const ws = workspaceDir && typeof workspaceDir === "string" ? workspaceDir : process.cwd();
+
+  for (const rel of AGENTS_FILENAMES) {
+    const fullPath = path.resolve(ws, rel);
+    try {
+      if (fs.existsSync(fullPath)) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        const parsed = parseAgentsSecurityRules(content);
+        return {
+          rules: parsed.rules,
+          rawDirectives: parsed.rawDirectives,
+          filePath: fullPath,
+        };
+      }
+    } catch {
+      // ignore read faults
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Evaluates an execution against active AGENTS.md rules (#91).
+ *
+ * @param {Array<any>} rules - Parsed rules from parseAgentsSecurityRules
+ * @param {{ name?: string, arguments?: any }} execution
+ * @param {string} [targetPath]
+ * @returns {{ match: boolean, reason?: string, rule?: any }}
+ */
+export function evaluateAgentsRules(rules, execution, targetPath) {
+  if (!Array.isArray(rules) || rules.length === 0) {
+    return { match: false };
+  }
+
+  const args = execution && execution.arguments;
+  const command = (args && typeof args === "object" && typeof args.command === "string")
+    ? args.command.trim()
+    : (typeof args === "string" ? args.trim() : "");
+  const toolName = String((execution && execution.name) || "").trim();
+  const pathToCheck = String(targetPath || (args && (args.path || args.file || args.TargetFile)) || "").trim();
+
+  for (const rule of rules) {
+    if (rule.type === "command") {
+      const pat = rule.pattern.toLowerCase();
+      if (command && command.toLowerCase().includes(pat)) {
+        return {
+          match: true,
+          reason: "agents-md-prohibited-command",
+          rule,
+        };
+      }
+      if (toolName && toolName.toLowerCase() === pat) {
+        return {
+          match: true,
+          reason: "agents-md-prohibited-command",
+          rule,
+        };
+      }
+    }
+
+    if (rule.type === "path" && pathToCheck) {
+      const pat = rule.pattern.replace(/\\/g, "/");
+      const normPath = pathToCheck.replace(/\\/g, "/");
+      if (pat.endsWith("*")) {
+        const prefix = pat.slice(0, -1);
+        if (normPath.startsWith(prefix) || normPath.includes(prefix)) {
+          return {
+            match: true,
+            reason: "agents-md-prohibited-path",
+            rule,
+          };
+        }
+      } else if (normPath.endsWith(pat) || normPath === pat) {
+        return {
+          match: true,
+          reason: "agents-md-prohibited-path",
+          rule,
+        };
+      }
+    }
+  }
+
+  return { match: false };
+}

package/lib/artifacts.js

@@ -0,0 +1,162 @@
+// lib/artifacts.js
+// Session Artifact Registry: tracks files created during current session
+// to permit safe auto-cleanup of temporary artifacts without approval prompt spam (#100).
+
+import path from "node:path";
+
+/**
+ * Normalizes file paths for consistent artifact matching across relative and absolute forms.
+ *
+ * @param {string} filePath
+ * @param {string} [workspaceDir]
+ * @returns {string}
+ */
+export function normalizeArtifactPath(filePath, workspaceDir) {
+  if (typeof filePath !== "string" || !filePath.trim()) return "";
+  let p = filePath.trim().replace(/^["']|["']$/g, "");
+  p = p.replace(/\\/g, "/");
+
+  if (workspaceDir && typeof workspaceDir === "string") {
+    const ws = workspaceDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (p.startsWith(ws + "/")) {
+      p = p.slice(ws.length + 1);
+    }
+  }
+
+  p = p.replace(/^\.\//, "");
+  return p;
+}
+
+/**
+ * Registry tracking temporary artifacts created within agent sessions (#100).
+ */
+export class ArtifactRegistry {
+  /**
+   * @param {{ workspaceDir?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.workspaceDir = options.workspaceDir || "";
+    /** @type {Map<string, Set<string>>} */
+    this._sessions = new Map();
+  }
+
+  /**
+   * Records a created or written artifact for a session.
+   *
+   * @param {string} sessionId
+   * @param {string} filePath
+   * @returns {boolean} True if new artifact added, false if already tracked or invalid
+   */
+  recordArtifact(sessionId, filePath) {
+    const sid = String(sessionId || "default");
+    const norm = normalizeArtifactPath(filePath, this.workspaceDir);
+    if (!norm) return false;
+
+    let set = this._sessions.get(sid);
+    if (!set) {
+      set = new Set();
+      this._sessions.set(sid, set);
+    }
+    const had = set.has(norm);
+    set.add(norm);
+    return !had;
+  }
+
+  /**
+   * Checks whether a specific file was created as an artifact in the given session.
+   *
+   * @param {string} sessionId
+   * @param {string} filePath
+   * @returns {boolean}
+   */
+  isSessionArtifact(sessionId, filePath) {
+    const sid = String(sessionId || "default");
+    const norm = normalizeArtifactPath(filePath, this.workspaceDir);
+    if (!norm) return false;
+
+    const set = this._sessions.get(sid);
+    if (!set) return false;
+    return set.has(norm);
+  }
+
+  /**
+   * Checks whether ALL provided files are artifacts created in the given session.
+   *
+   * @param {string} sessionId
+   * @param {string[]} filePaths
+   * @returns {boolean}
+   */
+  areAllSessionArtifacts(sessionId, filePaths) {
+    if (!Array.isArray(filePaths) || filePaths.length === 0) return false;
+    const sid = String(sessionId || "default");
+    const set = this._sessions.get(sid);
+    if (!set || set.size === 0) return false;
+
+    for (const fp of filePaths) {
+      const norm = normalizeArtifactPath(fp, this.workspaceDir);
+      if (!norm || !set.has(norm)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Removes an artifact from session tracking (e.g. after deletion).
+   *
+   * @param {string} sessionId
+   * @param {string} filePath
+   * @returns {boolean}
+   */
+  removeArtifact(sessionId, filePath) {
+    const sid = String(sessionId || "default");
+    const norm = normalizeArtifactPath(filePath, this.workspaceDir);
+    if (!norm) return false;
+
+    const set = this._sessions.get(sid);
+    if (!set) return false;
+    return set.delete(norm);
+  }
+
+  /**
+   * Returns list of recorded artifacts for a session.
+   *
+   * @param {string} sessionId
+   * @returns {string[]}
+   */
+  getArtifacts(sessionId) {
+    const sid = String(sessionId || "default");
+    const set = this._sessions.get(sid);
+    if (!set) return [];
+    return Array.from(set);
+  }
+
+  /**
+   * Returns total count of artifacts recorded for a session.
+   *
+   * @param {string} sessionId
+   * @returns {number}
+   */
+  count(sessionId) {
+    const sid = String(sessionId || "default");
+    const set = this._sessions.get(sid);
+    return set ? set.size : 0;
+  }
+
+  /**
+   * Clears tracked artifacts for a specific session.
+   *
+   * @param {string} sessionId
+   */
+  clearSession(sessionId) {
+    const sid = String(sessionId || "default");
+    this._sessions.delete(sid);
+  }
+
+  /**
+   * Clears all session artifacts across the entire registry.
+   */
+  clearAll() {
+    this._sessions.clear();
+  }
+}

package/lib/compat.js

@@ -0,0 +1,124 @@
+// lib/compat.js
+// Host compatibility checks and polyfills across DeepSeek Harness minor versions (#106).
+
+/**
+ * Detects available runtime capabilities and services in the Cordis host context (#106).
+ *
+ * @param {any} ctx - Cordis / DSH host context
+ * @returns {{
+ *   hasContext: boolean,
+ *   hasToolsService: boolean,
+ *   hasPreExecuteHook: boolean,
+ *   hasProvideApi: boolean,
+ *   hasLocaleService: boolean,
+ *   harnessVersion: string | null
+ * }}
+ */
+export function detectHarnessCapabilities(ctx) {
+  if (!ctx || typeof ctx !== "object") {
+    return {
+      hasContext: false,
+      hasToolsService: false,
+      hasPreExecuteHook: false,
+      hasProvideApi: false,
+      hasLocaleService: false,
+      harnessVersion: null,
+    };
+  }
+
+  const getService = (name) => {
+    try {
+      if (typeof ctx.get === "function") return ctx.get(name);
+    } catch {
+      // ignore
+    }
+    return ctx[name];
+  };
+
+  const tools = getService("tools");
+  const locale = getService("locale");
+
+  const harnessVersion =
+    (typeof ctx.version === "string" && ctx.version) ||
+    (typeof process.env.DSH_VERSION === "string" && process.env.DSH_VERSION) ||
+    null;
+
+  return {
+    hasContext: true,
+    hasToolsService: Boolean(tools),
+    hasPreExecuteHook: typeof ctx.on === "function",
+    hasProvideApi: typeof ctx.provide === "function",
+    hasLocaleService: Boolean(locale && typeof locale.register === "function"),
+    harnessVersion,
+  };
+}
+
+/**
+ * Asserts host compatibility and identifies missing optional or required features (#106).
+ *
+ * @param {any} ctx
+ * @param {{ requireTools?: boolean }} [options]
+ * @returns {{ compatible: boolean, issues: string[], capabilities: ReturnType<typeof detectHarnessCapabilities> }}
+ */
+export function assertHarnessCompatibility(ctx, options = {}) {
+  const caps = detectHarnessCapabilities(ctx);
+  const issues = [];
+
+  if (!caps.hasContext) {
+    issues.push("Invalid or missing Cordis context object");
+  }
+
+  if (options.requireTools && !caps.hasToolsService) {
+    issues.push("Missing tools service in host context");
+  }
+
+  return {
+    compatible: issues.length === 0,
+    issues,
+    capabilities: caps,
+  };
+}
+
+/**
+ * Safely provides a service to the host context with backward-compatible polyfill (#106).
+ *
+ * @param {any} ctx
+ * @param {string} serviceName
+ * @param {any} serviceInstance
+ * @returns {boolean} True if successfully registered
+ */
+export function provideServicePolyfill(ctx, serviceName, serviceInstance) {
+  if (!ctx || typeof ctx !== "object" || !serviceName) return false;
+
+  if (typeof ctx.provide === "function") {
+    try {
+      ctx.provide(serviceName, serviceInstance);
+      return true;
+    } catch {
+      // fallback to property assignment below
+    }
+  }
+
+  ctx[serviceName] = serviceInstance;
+  return true;
+}
+
+/**
+ * Safely attaches an event hook to the host context with error boundary (#106).
+ *
+ * @param {any} ctx
+ * @param {string} event
+ * @param {(...args: any[]) => any} handler
+ * @returns {(() => void) | null} Unsubscribe dispose function or null
+ */
+export function registerHookPolyfill(ctx, event, handler) {
+  if (!ctx || typeof ctx.on !== "function" || typeof handler !== "function") {
+    return null;
+  }
+
+  try {
+    return ctx.on(event, handler);
+  } catch {
+    return null;
+  }
+}

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";
@@ -22,6 +16,10 @@ 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";
+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";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -73,26 +71,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);
@@ -126,6 +105,15 @@ export class SecurityEngine {
           ? 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);
   }
 
   /**
@@ -194,6 +182,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 +333,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 +386,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);
@@ -537,15 +564,23 @@ 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);
+    const command = execution && execution.arguments && execution.arguments.command;
+    if (command && isRmCommand(command)) {
+      decision.trashAlternative = suggestTrashAlternative(command, this.inspectConfig?.workspaceDir, context?.sessionId);
     }
     return decision;
   }
 
+  getArtifacts(sessionId) {
+    return this.artifactRegistry ? this.artifactRegistry.getArtifacts(sessionId) : [];
+  }
+
+  clearArtifacts(sessionId) {
+    if (this.artifactRegistry) this.artifactRegistry.clearSession(sessionId);
+  }
+
   getLatencyMetrics() {
     return this.latencyTracker ? this.latencyTracker.getMetrics() : null;
   }
@@ -555,3 +590,4 @@ export class SecurityEngine {
   }
 }
 
+

package/lib/index.js

@@ -4,6 +4,7 @@ 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 Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -241,6 +242,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 +256,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();
@@ -334,6 +340,8 @@ 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),
     getSnapshot: () => ({
       active: true,
       dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
@@ -345,15 +353,10 @@ 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,
+      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) {
@@ -550,12 +553,7 @@ 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 { DeclarativeRulesEngine, BUILTIN_RULES_FILE, WORKSPACE_RULES_REL, USER_RULES_REL } from "./rules-loader.js";
 export {
   normalizeChatCompletionsUrl,
   withLlmRetry,
@@ -574,4 +572,10 @@ export { resolveTempRoot, isGlobalTempPath, checkTempIsolation } from "./paths.j
 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";
+
 

package/lib/messages.js

@@ -77,6 +77,10 @@ export const MESSAGES = Object.freeze({
     ruleUnisolatedTempPath: "Target path uses unisolated global temp directory",
     askOverengineeringLimit: "Session file creation limit exceeded; potential overengineering requires review before allowing",
     ruleOverengineeringLimit: "Session exceeded maximum allowed created files limit",
+    ruleAgentsMdProhibitedCommand: "Command execution prohibited by rules in AGENTS.md",
+    ruleAgentsMdProhibitedPath: "File modification prohibited by rules in AGENTS.md",
+    askMajorVersionBump: "Package.json modification contains major dependency bump; review before allowing",
+    ruleMajorVersionBump: "Unauthorized major dependency version bump",
     hintRecursiveRm: "Specify exact target files instead of recursive deletion",
     hintPathTraversal: "Keep operations strictly within the project directory",
     hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
@@ -100,6 +104,9 @@ export const MESSAGES = Object.freeze({
     hintContractViolation: "Confine operations to permitted task tools and project scope",
     hintUnisolatedTempPath: "Use workspace-isolated temporary directory (<workspace>/.dsh/tmp)",
     hintOverengineeringLimit: "Reuse existing files and avoid creating redundant abstractions or boilerplate",
+    hintTrashAlternative: "Move files to reversible .dsh/trash/<session>/ directory instead of rm",
+    hintAgentsMdProhibited: "Review project-specific guidelines and constraints defined in AGENTS.md",
+    hintMajorVersionBump: "Verify compatibility before bumping major dependency versions in package.json",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -176,6 +183,10 @@ export const MESSAGES = Object.freeze({
     ruleUnisolatedTempPath: "目标路径使用未隔离的全局临时目录",
     askOverengineeringLimit: "会话创建文件数超过限制；潜在的过度工程需要人工审查",
     ruleOverengineeringLimit: "会话超出最大允许创建文件数限制",
+    ruleAgentsMdProhibitedCommand: "命令执行被 AGENTS.md 中的规则明确禁止",
+    ruleAgentsMdProhibitedPath: "文件修改被 AGENTS.md 中的规则明确禁止",
+    askMajorVersionBump: "package.json 包含破坏性依赖主版本升级；请在允许前进行审查",
+    ruleMajorVersionBump: "未授权的依赖包主版本升级",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -199,6 +210,9 @@ export const MESSAGES = Object.freeze({
     hintContractViolation: "将操作限制在允许的任务工具和项目范围内",
     hintUnisolatedTempPath: "使用工作区隔离的临时目录 (<workspace>/.dsh/tmp)",
     hintOverengineeringLimit: "复用现有文件，避免创建多余的抽象或样板代码",
+    hintTrashAlternative: "建议将文件移动到可逆的 .dsh/trash/<session>/ 目录，避免直接 rm",
+    hintAgentsMdProhibited: "请核对项目根目录 AGENTS.md 中定义的安全约束和禁止指令",
+    hintMajorVersionBump: "在升级 package.json 依赖主版本前请确认破坏性变更与兼容性",
   },
 });
 
@@ -270,10 +284,13 @@ const RULE_KEYS = Object.freeze({
   "contract-violation": "ruleContractViolation",
   "unisolated-temp-path": "ruleUnisolatedTempPath",
   "overengineering-file-limit": "ruleOverengineeringLimit",
+  "agents-md-prohibited-command": "ruleAgentsMdProhibitedCommand",
+  "agents-md-prohibited-path": "ruleAgentsMdProhibitedPath",
+  "major-version-bump": "askMajorVersionBump",
 });
 
 const HINT_KEYS = Object.freeze({
-  "recursive-rm": "hintRecursiveRm",
+  "recursive-rm": "hintTrashAlternative",
   "path-traversal": "hintPathTraversal",
   "secret-write": "hintSecretWrite",
   "env-dump-leak": "hintEnvDumpLeak",
@@ -297,6 +314,9 @@ const HINT_KEYS = Object.freeze({
   "contract-violation": "hintContractViolation",
   "unisolated-temp-path": "hintUnisolatedTempPath",
   "overengineering-file-limit": "hintOverengineeringLimit",
+  "agents-md-prohibited-command": "hintAgentsMdProhibited",
+  "agents-md-prohibited-path": "hintAgentsMdProhibited",
+  "major-version-bump": "hintMajorVersionBump",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -321,6 +341,7 @@ const ASK_KEYS = Object.freeze({
   "contract-violation": "askContractViolation",
   "unisolated-temp-path": "askUnisolatedTempPath",
   "overengineering-file-limit": "askOverengineeringLimit",
+  "major-version-bump": "askMajorVersionBump",
 });
 
 const DETAIL_KEYS = Object.freeze({

package/lib/trash.js

@@ -0,0 +1,119 @@
+// lib/trash.js
+// Reversible Trash Move: safe alternative to destructive rm commands (#104).
+
+import path from "node:path";
+
+const RM_COMMAND_PATTERN = /^\s*rm\b/i;
+const RM_FLAGS_PATTERN = /^-[a-zA-Z0-9_\-]+$/;
+
+/**
+ * Resolves the isolated trash directory for a workspace and session (#104).
+ * Default path: <workspaceDir>/.dsh/trash/<sessionId>
+ *
+ * @param {string} [workspaceDir]
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function resolveTrashDir(workspaceDir, sessionId = "default") {
+  const base = workspaceDir && typeof workspaceDir === "string" ? workspaceDir : ".";
+  const session = String(sessionId || "default").replace(/[^a-zA-Z0-9_\-]/g, "_");
+  return path.join(base, ".dsh", "trash", session);
+}
+
+/**
+ * Checks if a shell command is an rm command (#104).
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isRmCommand(command) {
+  if (typeof command !== "string") return false;
+  return RM_COMMAND_PATTERN.test(command.trim());
+}
+
+/**
+ * Extracts target file and directory paths from an rm command string (#104).
+ *
+ * @param {string} command
+ * @returns {string[]}
+ */
+export function extractRmTargets(command) {
+  if (typeof command !== "string") return [];
+  const trimmed = command.trim();
+  if (!RM_COMMAND_PATTERN.test(trimmed)) return [];
+
+  const parts = trimmed.split(/\s+/);
+  const targets = [];
+
+  // Skip leading "rm" and any option flags (-r, -f, -rf, --recursive, etc.)
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    if (part.startsWith("-")) {
+      continue;
+    }
+    // Stop if shell control operators occur
+    if (/[;&|]/.test(part)) {
+      break;
+    }
+    targets.push(part);
+  }
+
+  return targets;
+}
+
+/**
+ * Builds a reversible trash move command replacing destructive rm (#104).
+ *
+ * @param {string[]} targetPaths
+ * @param {string} trashDir
+ * @returns {string}
+ */
+export function buildTrashCommand(targetPaths, trashDir) {
+  if (!Array.isArray(targetPaths) || targetPaths.length === 0) {
+    return "";
+  }
+  const cleanTargets = targetPaths
+    .map((t) => String(t || "").trim())
+    .filter((t) => t.length > 0 && !t.startsWith("-"));
+
+  if (cleanTargets.length === 0) {
+    return "";
+  }
+
+  const quotedTargets = cleanTargets.map((t) => (t.includes(" ") ? `"${t}"` : t)).join(" ");
+  const normalizedTrash = String(trashDir || ".dsh/trash").trim();
+  const quotedTrash = normalizedTrash.includes(" ") ? `"${normalizedTrash}"` : normalizedTrash;
+
+  return `mkdir -p ${quotedTrash} && mv ${quotedTargets} ${quotedTrash}/`;
+}
+
+/**
+ * Suggests a safe trash alternative for an rm execution (#104).
+ *
+ * @param {string} command
+ * @param {string} [workspaceDir]
+ * @param {string} [sessionId]
+ * @returns {{ isRm: boolean, targets: string[], trashDir: string, suggestedCommand: string | null }}
+ */
+export function suggestTrashAlternative(command, workspaceDir, sessionId) {
+  const isRm = isRmCommand(command);
+  if (!isRm) {
+    return {
+      isRm: false,
+      targets: [],
+      trashDir: "",
+      suggestedCommand: null,
+    };
+  }
+
+  const targets = extractRmTargets(command);
+  const trashDir = resolveTrashDir(workspaceDir, sessionId);
+  const suggestedCommand = targets.length > 0 ? buildTrashCommand(targets, trashDir) : null;
+
+  return {
+    isRm: true,
+    targets,
+    trashDir,
+    suggestedCommand,
+  };
+}

package/lib/version-guard.js

@@ -0,0 +1,177 @@
+// lib/version-guard.js
+// Dependency version guard: detects unauthorized major dependency bumps in package.json (#95).
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DEPENDENCY_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+];
+
+const SEMVER_REGEX = /^(?:[\^~>=<v\s]*?)(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+
+/**
+ * Parses semver string into numeric major, minor, and patch components (#95).
+ *
+ * @param {string} ver
+ * @returns {{ major: number, minor: number, patch: number } | null}
+ */
+export function parseSemver(ver) {
+  if (typeof ver !== "string" || !ver.trim()) return null;
+  const match = SEMVER_REGEX.exec(ver.trim());
+  if (!match) return null;
+
+  return {
+    major: parseInt(match[1], 10),
+    minor: match[2] !== undefined ? parseInt(match[2], 10) : 0,
+    patch: match[3] !== undefined ? parseInt(match[3], 10) : 0,
+  };
+}
+
+/**
+ * Determines whether a version transition represents a major version bump (#95).
+ *
+ * @param {string} oldVer
+ * @param {string} newVer
+ * @returns {boolean}
+ */
+export function isMajorBump(oldVer, newVer) {
+  const oldParsed = parseSemver(oldVer);
+  const newParsed = parseSemver(newVer);
+  if (!oldParsed || !newParsed) return false;
+
+  return newParsed.major > oldParsed.major;
+}
+
+/**
+ * Compares two dependency maps and returns detected major bumps (#95).
+ *
+ * @param {Record<string, string>} [oldDeps]
+ * @param {Record<string, string>} [newDeps]
+ * @param {string} [section="dependencies"]
+ * @returns {Array<{ pkg: string, from: string, to: string, section: string }>}
+ */
+export function compareDependencySection(oldDeps = {}, newDeps = {}, section = "dependencies") {
+  if (!oldDeps || !newDeps) return [];
+  const bumps = [];
+
+  for (const [pkg, newVer] of Object.entries(newDeps)) {
+    const oldVer = oldDeps[pkg];
+    if (typeof oldVer === "string" && typeof newVer === "string") {
+      if (isMajorBump(oldVer, newVer)) {
+        bumps.push({
+          pkg,
+          from: oldVer,
+          to: newVer,
+          section,
+        });
+      }
+    }
+  }
+
+  return bumps;
+}
+
+/**
+ * Inspects a mutation between two package.json objects for major dependency bumps (#95).
+ *
+ * @param {any} oldPkg
+ * @param {any} newPkg
+ * @returns {{ hasMajorBump: boolean, bumps: Array<{ pkg: string, from: string, to: string, section: string }> }}
+ */
+export function inspectPackageJsonDiff(oldPkg, newPkg) {
+  if (!oldPkg || typeof oldPkg !== "object" || !newPkg || typeof newPkg !== "object") {
+    return { hasMajorBump: false, bumps: [] };
+  }
+
+  const allBumps = [];
+
+  for (const section of DEPENDENCY_SECTIONS) {
+    const oldSec = oldPkg[section] || {};
+    const newSec = newPkg[section] || {};
+    const sectionBumps = compareDependencySection(oldSec, newSec, section);
+    allBumps.push(...sectionBumps);
+  }
+
+  return {
+    hasMajorBump: allBumps.length > 0,
+    bumps: allBumps,
+  };
+}
+
+/**
+ * Guard enforcing human confirmation on major dependency version updates (#95).
+ */
+export class VersionGuard {
+  /**
+   * @param {{ workspaceDir?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.workspaceDir = options.workspaceDir || "";
+  }
+
+  /**
+   * Inspects a file write operation to detect major dependency bumps in package.json (#95).
+   *
+   * @param {string} targetPath - Path of file being written
+   * @param {string | object} newContent - Incoming content or parsed JSON
+   * @returns {{ majorBump: boolean, bumps: Array<any>, detail?: string }}
+   */
+  inspectWrite(targetPath, newContent) {
+    if (typeof targetPath !== "string") {
+      return { majorBump: false, bumps: [] };
+    }
+
+    const basename = path.basename(targetPath);
+    if (basename !== "package.json") {
+      return { majorBump: false, bumps: [] };
+    }
+
+    let parsedNew;
+    if (typeof newContent === "string") {
+      try {
+        parsedNew = JSON.parse(newContent);
+      } catch {
+        return { majorBump: false, bumps: [] };
+      }
+    } else if (newContent && typeof newContent === "object") {
+      parsedNew = newContent;
+    } else {
+      return { majorBump: false, bumps: [] };
+    }
+
+    // Attempt reading existing package.json
+    let existingPkg = null;
+    const resolvedPath = path.isAbsolute(targetPath)
+      ? targetPath
+      : path.resolve(this.workspaceDir || process.cwd(), targetPath);
+
+    try {
+      if (fs.existsSync(resolvedPath)) {
+        const raw = fs.readFileSync(resolvedPath, "utf-8");
+        existingPkg = JSON.parse(raw);
+      }
+    } catch {
+      // ignore read/parse error on existing file
+    }
+
+    if (!existingPkg) {
+      return { majorBump: false, bumps: [] };
+    }
+
+    const diff = inspectPackageJsonDiff(existingPkg, parsedNew);
+    if (diff.hasMajorBump) {
+      const descriptions = diff.bumps.map((b) => `${b.pkg} (${b.from} -> ${b.to})`).join(", ");
+      return {
+        majorBump: true,
+        bumps: diff.bumps,
+        detail: `Major dependency version bump detected: ${descriptions}`,
+      };
+    }
+
+    return { majorBump: false, bumps: [] };
+  }
+}

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.19",
-  "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./package.json": "./package.json",
-    "./cordis.patch.yml": "./cordis.patch.yml"
-  },
-  "files": [
-    "lib",
-    "rules",
-    "cordis.patch.yml",
-    "README.md",
-    "README.zh.md",
-    "README.ru.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "license": "MIT",
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/GooDAnDReaDY/dsh-approval-gate.git"
-  },
-  "homepage": "https://github.com/GooDAnDReaDY/dsh-approval-gate#readme",
-  "bugs": {
-    "url": "https://github.com/GooDAnDReaDY/dsh-approval-gate/issues"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek-harness",
-    "security",
-    "approval-gate",
-    "safety"
-  ]
-}
+{
+  "name": "@goodandready/dsh-approval-gate",
+  "version": "0.1.20",
+  "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "rules",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.ru.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GooDAnDReaDY/dsh-approval-gate.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-approval-gate#readme",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-approval-gate/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "security",
+    "approval-gate",
+    "safety"
+  ]
+}