@goodandready/dsh-approval-gate 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.12
+
+- Fix: корректная регистрация сервиса `approvalGate` в Cordis через `ctx.provide('approvalGate', ...)` и экспорт `export const provide = ['approvalGate']`, устраняющая ошибку `cannot set property "approvalGate" without provide` при старте хоста DSH.
+- Policy: надежное определение режима «Полный доступ» (`danger-full-access` / `never`) в `readKnobs` и `isUnattended` даже при отсутствии предварительного события `approval/policy` в сессии (приоритет пресета и sandbox режима над дефолтным `ask` от `ApprovalService`), предотвращающая ложный отказ `the user rejected tool` на всех командах агента.
+- Localization: удаление захардкоженного русского словаря из `lib/messages.js` в строгом соответствии со стандартом разработки DSH плагинов (только `en` и `zh`, русская локализация централизованно обслуживается `dsh-russian-lang`) с защитной обработкой `locale.register` в `apply` (Refs: #153, #162).
+- Bands: динамическое расширение списка read-only инструментов из хостового `toolRegistry` (`options.toolRegistry`) с поддержкой аннотаций `readOnly` / `readonly` (Refs: #156).
+- Engine: настраиваемый дефолтный вердикт для нераспознанных команд `defaultVerdict` (`allow` по умолчанию, опциональный fail-closed `ask`) с добавлением в схему `Config` (Refs: #163).
+- Session: гарантированное извлечение строкового `sessionId` в `resolveSessionId` для любых структур объекта `agent` / `session`.
+
+## 0.1.11
+
+- Security: проверка абсолютных путей перенаправлений shell на выход за пределы рабочего каталога `workspaceDir` с исключением canonical устройств (`/dev/null`) и временных каталогов (`/tmp`) (Refs: #143).
+- Security: инспекция инструмента `str_replace_editor` как модификатора файлов с проверкой секретов и границ каталога (Refs: #144).
+- Security: блокировка обхода через составные префиксы `{`, `}`, `!` в начале shell-команд (Refs: #147).
+- Bands: строгий отказ Band 1 Safe Allow для составных команд, конвейеров и операторов цепочек (`&&`, `||`, `;`, `|`, `>`, `$()`) с перенаправлением на полную сегментную инспекцию (Refs: #155, #158).
+- Paths: безопасное раскрытие переменной `$HOME` с привязкой к границе сегмента пути (`/\${HOME\}|\$HOME(?=$|[\/\\])/g`), предотвращающее повреждение путей вроде `/opt/$HOME-backup` (Refs: #154).
+- Engine: строгий fail-closed fallback в `P4 Ask` при исключениях семантического классификатора (`reason: 'classifier-error'`) и полная изоляция `decide()` и хуков рантайма в защитные блоки `try/catch` с гарантией `inspect-error` (Refs: #145, #159, #161).
+- Breaker: блокировка обхода сработавшего Circuit Breaker в unattended/full-access режиме — взведенный предохранитель принудительно возвращает `deny` вместо пропуска в `next()` (Refs: #157, #160).
+- Breaker: ограничение размера истории состояний (`MAX_TRACKED_SESSIONS = 500`, `MAX_SESSION_HISTORY = 100`) и пассивные методы проверки без утечки памяти (Refs: #149).
+- Policy: оптимизация сканирования истории событий сессии в `readKnobs` — однопроходный поиск, ограничение глубины до 100 событий и кэширование политики сессии на `_gateCachedPolicy` (Refs: #148).
+- Schema: поддержка `.volatile()` на полях конфигурации, явные поля `workspaceDir` и `engine`, полифилл для DSH UI формы настроек и функция разворачивания реактивных боксов `plainConfig` (Refs: #142, #150, #151).
+- Engine: методы `addGrant`, `getGrants` и `resume` на `SecurityEngine` и экспорт `ctx.approvalGate` для управления грантами и сбросом предохранителя (Refs: #152).
+- Tokenizer: исправление передачи маркера heredoc (`marker: heredoc.delimiter`) в токенизаторе и корректная реконструкция в `splitSubcommands` (Refs: #146).
+- Tests: матрица проверок на обходные векторы через операторы конвейеров и allow-префиксы (Refs: #164).
+
 ## 0.1.10
 
 - Policy: точное определение сессионной политики апрува в `readKnobs` через `approval.effectivePolicy(session)`, историю событий `session.eventAt` и пресет `danger-full-access` (Refs: #140).

package/lib/bands.js

@@ -134,6 +134,22 @@ export class BandsEngine {
       typeof g === "string" ? compileGlob(g) : g
     );
     this.readOnlyTools = new Set(options.readOnlyTools || DEFAULT_READ_ONLY_TOOLS);
+
+    // Derive read-only tools dynamically from host tool registry if provided (#156)
+    if (options.toolRegistry) {
+      try {
+        const tools = typeof options.toolRegistry.getTools === "function"
+          ? options.toolRegistry.getTools()
+          : (Array.isArray(options.toolRegistry) ? options.toolRegistry : []);
+        for (const t of tools) {
+          if (t && (t.readOnly || t.readonly || t.isReadOnly) && typeof t.name === "string") {
+            this.readOnlyTools.add(t.name);
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
   }
 
   /**
@@ -153,6 +169,10 @@ export class BandsEngine {
   isSafeInspectionCommand(command) {
     if (typeof command !== "string" || command.trim() === "") return false;
     const text = command.trim();
+    // Chained commands, subshells, substitutions, and redirections cannot match whole-string safe-allow
+    if (/[\n;&|`<>]|\$\([\s\S]*\)|\$\{[\s\S]*\}/.test(text)) {
+      return false;
+    }
     for (const pattern of this.denyPatterns) {
       if (pattern.test(text)) return false;
     }
@@ -203,10 +223,12 @@ export class BandsEngine {
         }
       }
 
-      // Band 1: Safe Allow
-      for (const glob of this.allowGlobs) {
-        if (glob.test(text)) {
-          return "allow";
+      // Band 1: Safe Allow (applies strictly to single commands without chaining, subshells or redirects)
+      if (!/[\n;&|`<>]|\$\([\s\S]*\)|\$\{[\s\S]*\}/.test(text)) {
+        for (const glob of this.allowGlobs) {
+          if (glob.test(text)) {
+            return "allow";
+          }
         }
       }
     }
@@ -214,4 +236,4 @@ export class BandsEngine {
     return "unmatched";
   }
 }
-
+

package/lib/breaker.js

@@ -4,6 +4,8 @@
 
 export const DEFAULT_MAX_CONSECUTIVE_DENIES = 3;
 export const DEFAULT_MAX_TOTAL_DENIES = 20;
+export const MAX_TRACKED_SESSIONS = 500;
+export const MAX_SESSION_HISTORY = 100;
 
 export const CIRCUIT_STATE_ACTIVE = "active";
 export const CIRCUIT_STATE_TRIPPED = "tripped";
@@ -70,6 +72,9 @@ export class CircuitBreaker {
 
     sessionState.state = to;
     sessionState.history.push(event);
+    if (sessionState.history.length > MAX_SESSION_HISTORY) {
+      sessionState.history.shift();
+    }
 
     if (this.logger) {
       const logLine = `[dsh-approval-gate:breaker] session=${sessionId} state=${to} (was ${from}) reason=${reason} consecutive=${sessionState.consecutive} total=${sessionState.total}`;
@@ -97,6 +102,10 @@ export class CircuitBreaker {
     const key = sessionId || "default";
     let state = this.sessions.get(key);
     if (!state) {
+      if (this.sessions.size >= MAX_TRACKED_SESSIONS) {
+        const oldestKey = this.sessions.keys().next().value;
+        this.sessions.delete(oldestKey);
+      }
       state = {
         consecutive: 0,
         total: 0,
@@ -115,12 +124,11 @@ export class CircuitBreaker {
    * @returns {{ consecutive: number, total: number, tripped: boolean }}
    */
   get(sessionId) {
-    const state = this._getOrCreate(sessionId);
-    return {
-      consecutive: state.consecutive,
-      total: state.total,
-      tripped: state.tripped,
-    };
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return state
+      ? { consecutive: state.consecutive, total: state.total, tripped: state.tripped }
+      : { consecutive: 0, total: 0, tripped: false };
   }
 
   /**
@@ -129,8 +137,9 @@ export class CircuitBreaker {
    * @returns {string}
    */
   getState(sessionId) {
-    const state = this._getOrCreate(sessionId);
-    return state.state;
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return state ? state.state : CIRCUIT_STATE_ACTIVE;
   }
 
   /**
@@ -139,8 +148,9 @@ export class CircuitBreaker {
    * @returns {CircuitTransitionEvent[]}
    */
   getHistory(sessionId) {
-    const state = this._getOrCreate(sessionId);
-    return state.history.map((ev) => ({ ...ev }));
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
+    return state ? state.history.map((ev) => ({ ...ev })) : [];
   }
 
   /**
@@ -149,7 +159,8 @@ export class CircuitBreaker {
    * @returns {boolean}
    */
   isTripped(sessionId) {
-    const state = this._getOrCreate(sessionId);
+    const key = sessionId || "default";
+    const state = this.sessions.get(key);
     return Boolean(state && state.tripped);
   }
 

package/lib/engine.js

@@ -28,6 +28,7 @@ export class SecurityEngine {
     this.inspectConfig = options.inspectConfig || {};
     this.classifier = options.classifier || null;
     this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
+    this.defaultVerdict = options.defaultVerdict || "allow";
   }
 
   /**
@@ -38,7 +39,8 @@ export class SecurityEngine {
    * @returns {{ verdict: "allow" | "deny" | "ask", stage: "P0" | "P1" | "P2" | "P3" | "P4", reason: string, detail?: string, hit?: any }}
    */
   decide(execution, context = {}) {
-    const sessionId = context.sessionId || "default";
+    try {
+      const sessionId = context.sessionId || "default";
     const toolName = execution && execution.name;
     const command = execution && execution.arguments && execution.arguments.command;
 
@@ -109,10 +111,42 @@ export class SecurityEngine {
         }
       } catch (err) {
         // Classifier error fails closed to P4 Ask
+        return { verdict: "ask", stage: "P4", reason: "classifier-error", detail: String(err && err.message || err), hit: null };
       }
     }
 
-    // Safe default for unclassified commands
+    // Default verdict for unclassified commands (#163)
+    if (this.defaultVerdict === "ask") {
+      const askHit = { ask: true, reason: "unmatched-ask", snippet: command || toolName };
+      return { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
+    }
     return { verdict: "allow", stage: "P2", reason: "unmatched-allow", hit };
+    } catch (err) {
+      return {
+        verdict: "ask",
+        stage: "P4",
+        reason: "inspect-error",
+        detail: String(err && err.message || err),
+        hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
+      };
+    }
+  }
+
+  addGrant(options) {
+    if (this.grantRegistry && typeof this.grantRegistry.addGrant === "function") {
+      return this.grantRegistry.addGrant(options);
+    }
+    return null;
+  }
+
+  getGrants(sessionId) {
+    if (this.grantRegistry && typeof this.grantRegistry.getGrants === "function") {
+      return this.grantRegistry.getGrants(sessionId);
+    }
+    return [];
+  }
+
+  resume(sessionId, reason) {
+    return this.breaker.resume(sessionId, reason);
   }
 }

package/lib/index.js

@@ -1,18 +1,26 @@
 import { SecurityEngine } from "./engine.js";
-// dsh-approval-gate - approval gate for DeepSeek Harness.
-//
-// Registers tools.guard on the tool runtime and denies dangerous bash
-// commands and writes to secret files even when sandbox mode would allow
-// them. A guard return value (non-undefined) denies execution, so the
-// dangerous call never runs on its own - it needs an explicit owner
-// Approval is handled by DSH's native flow; no separate word is implemented. When the
-// effective approval policy cannot be answered ("never", i.e. the full-access preset),
-// the gate does not raise an ask at all: an allowed command proceeds instead of dying as
-// a rejection nobody could consent to. Denials never depend on the policy.
-//
-// Only the agent tool calls pass through the guard (cron/systemd scripts
-// do not), so legitimate unattended operations are unaffected.
+import { BandsEngine } from "./bands.js";
 import Schema from "@deepseek-ai/schemastery";
+
+if (typeof Schema.prototype?.volatile !== "function") {
+  if (Schema.prototype) {
+    Schema.prototype.volatile = function volatile() {
+      if (this.meta && this.meta.volatile) return this;
+      return typeof this.extra === "function" ? this.extra("volatile", true) : this;
+    };
+  }
+}
+
+function isVolatileRef(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.get === "function";
+}
+
+export function plainConfig(value) {
+  if (isVolatileRef(value)) return plainConfig(value.get());
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(plainConfig);
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plainConfig(v)]));
+}
 import {
   DEFAULT_BASH_TOOL,
   DEFAULT_FILE_WRITE_TOOLS,
@@ -25,6 +33,7 @@ import { LOCALE_NS, MESSAGES } from "./messages.js";
 
 export const name = "dsh-approval-gate";
 export const inject = ["tools"];
+export const provide = ["approvalGate"];
 
 /** Policies under which a prompt cannot be answered, so raising one is a silent denial. */
 export const DEFAULT_UNATTENDED_POLICIES = ["never"];
@@ -32,25 +41,48 @@ export const DEFAULT_UNATTENDED_POLICIES = ["never"];
 /**
  * Whether a raised ask would be answerable in this session.
  *
- * `policy` comes from the approval service (`ctx.approval.config.policy`); an empty value
- * means the knob is unknown and the gate keeps asking, which is the safe direction.
- * @param {{policy?: string, unattendedPolicies?: string[]}} knobs
+ * Checks explicit unattended policies, as well as preset and sandbox modes.
+ * In 'danger-full-access' mode, approval prompts are disabled by host design.
+ * @param {{policy?: string, preset?: string, sandbox?: string, unattendedPolicies?: string[]}} knobs
  * @returns {boolean}
  */
 export function isUnattended(knobs) {
-  const policy = knobs && knobs.policy;
+  if (!knobs) return false;
+  if (knobs.preset === "danger-full-access" || knobs.sandbox === "danger-full-access") return true;
+  const policy = knobs.policy;
   const policies = (knobs && knobs.unattendedPolicies) || DEFAULT_UNATTENDED_POLICIES;
   if (typeof policy !== "string" || policy === "") return false;
   return policies.includes(policy);
 }
 
+/**
+ * Extracts a clean string session identifier from an execution object.
+ * @param {any} execution
+ * @returns {string}
+ */
+export function resolveSessionId(execution) {
+  const agent = execution && execution.agent;
+  const session = agent && agent.session;
+  if (session) {
+    if (typeof session === "string") return session;
+    if (typeof session.id === "string") return session.id;
+    if (typeof session.sessionId === "string") return session.sessionId;
+    if (typeof session.sessionKey === "string") return session.sessionKey;
+  }
+  if (agent) {
+    if (typeof agent === "string") return agent;
+    if (typeof agent.id === "string") return agent.id;
+  }
+  return "default";
+}
+
 /**
  * Effective permission knobs, as the harness exposes them.
- * Resolves session-level approval policy if an active execution carrying a session is provided.
+ * Resolves session-level approval policy, preset, and sandbox mode.
  *
  * @param {any} ctx - Cordis context
  * @param {any} [execution] - Optional tool execution carrying agent/session
- * @returns {{ policy: string, sandbox: string }}
+ * @returns {{ policy: string, sandbox: string, preset: string }}
  */
 export function readKnobs(ctx, execution) {
   const read = (name) => {
@@ -67,67 +99,77 @@ export function readKnobs(ctx, execution) {
   const session = agent && (agent.session || (typeof agent === "object" && typeof agent.eventAt === "function" ? agent : undefined));
 
   let policy = "";
+  let preset = "";
+  let sessionSandbox = "";
 
-  // 1. Live approval service effectivePolicy(session)
-  if (approval && session && typeof approval.effectivePolicy === "function") {
-    try {
-      policy = approval.effectivePolicy(session) || "";
-    } catch {
-      // ignore
+  // 1. Inspect session events backwards (bounded to last 100 events) with sequence caching
+  if (session && typeof session.eventAt === "function" && typeof session.seq === "number") {
+    if (session._gateCachedSeq === session.seq && session._gateCachedPolicy !== undefined) {
+      policy = session._gateCachedPolicy;
+      preset = session._gateCachedPreset || "";
+      sessionSandbox = session._gateCachedSandbox || "";
+    } else {
+      try {
+        const minSeq = Math.max(0, session.seq - 100);
+        for (let seq = session.seq - 1; seq >= minSeq; seq -= 1) {
+          const event = session.eventAt(seq);
+          if (!policy && event && event.type === "approval/policy" && event.data && event.data.policy) {
+            policy = event.data.policy;
+          }
+          if (!preset && event && event.type === "permission/preset" && event.data && event.data.preset) {
+            preset = event.data.preset;
+          }
+          if (!sessionSandbox && event && event.type === "sandbox/mode" && event.data && event.data.mode) {
+            sessionSandbox = event.data.mode;
+          }
+          if (policy && preset && sessionSandbox) break;
+        }
+        session._gateCachedSeq = session.seq;
+        session._gateCachedPolicy = policy || "";
+        session._gateCachedPreset = preset || "";
+        session._gateCachedSandbox = sessionSandbox || "";
+      } catch {
+        // ignore
+      }
     }
   }
 
-  // 2. Direct session property fallback
-  if (!policy && session && typeof session.approvalPolicy === "string") {
-    policy = session.approvalPolicy;
-  }
-
-  // 3. Fallback: inspect session events backwards for approval/policy
-  if (!policy && session && typeof session.eventAt === "function" && typeof session.seq === "number") {
+  // 2. In-memory session.events array fallback (common in mocks / tests)
+  if (session && Array.isArray(session.events)) {
     try {
-      for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
-        const event = session.eventAt(seq);
-        if (event && event.type === "approval/policy" && event.data && event.data.policy) {
+      const minIdx = Math.max(0, session.events.length - 100);
+      for (let i = session.events.length - 1; i >= minIdx; i -= 1) {
+        const event = session.events[i];
+        if (!policy && event && event.type === "approval/policy" && event.data && event.data.policy) {
           policy = event.data.policy;
-          break;
         }
+        if (!preset && event && event.type === "permission/preset" && event.data && event.data.preset) {
+          preset = event.data.preset;
+        }
+        if (!sessionSandbox && event && event.type === "sandbox/mode" && event.data && event.data.mode) {
+          sessionSandbox = event.data.mode;
+        }
+        if (policy && preset && sessionSandbox) break;
       }
     } catch {
       // ignore
     }
   }
 
-  // 4. Fallback: inspect session events for permission/preset === 'danger-full-access'
-  if (!policy && session && typeof session.eventAt === "function" && typeof session.seq === "number") {
-    try {
-      for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
-        const event = session.eventAt(seq);
-        if (event && event.type === "permission/preset" && event.data && event.data.preset) {
-          if (event.data.preset === "danger-full-access") {
-            policy = "never";
-          }
-          break;
-        }
-      }
-    } catch {
-      // ignore
-    }
+  // 3. Preset / sandbox direct values: danger-full-access implies "never" approval
+  if (preset === "danger-full-access" || sessionSandbox === "danger-full-access") {
+    policy = "never";
   }
 
-  // 5. In-memory session.events array fallback (common in mocks / tests)
-  if (!policy && session && Array.isArray(session.events)) {
+  // 4. Direct session property fallback
+  if (!policy && session && typeof session.approvalPolicy === "string") {
+    policy = session.approvalPolicy;
+  }
+
+  // 5. Live approval service effectivePolicy(session)
+  if (!policy && approval && session && typeof approval.effectivePolicy === "function") {
     try {
-      for (let i = session.events.length - 1; i >= 0; i -= 1) {
-        const event = session.events[i];
-        if (event && event.type === "approval/policy" && event.data && event.data.policy) {
-          policy = event.data.policy;
-          break;
-        }
-        if (event && event.type === "permission/preset" && event.data && event.data.preset === "danger-full-access") {
-          policy = "never";
-          break;
-        }
-      }
+      policy = approval.effectivePolicy(session) || "";
     } catch {
       // ignore
     }
@@ -138,21 +180,33 @@ export function readKnobs(ctx, execution) {
     policy = approval.config.policy;
   }
 
+  const sandbox = sessionSandbox || (shell && shell.sandboxMode) || "";
+  if (sandbox === "danger-full-access" && !policy) {
+    policy = "never";
+  }
+
   return {
     policy: policy || "",
-    sandbox: (shell && shell.sandboxMode) || "",
+    sandbox: sandbox || "",
+    preset: preset || "",
   };
 }
 
 export const Config = Schema.object({
   /** Name of the tool whose `command` arg is inspected (the DSH bash tool). */
-  toolName: Schema.string().default(DEFAULT_BASH_TOOL),
+  toolName: Schema.string().default(DEFAULT_BASH_TOOL).volatile(),
   /** Extra tool names treated as file writes; paths are matched against secret files. */
-  fileWriteTools: Schema.array(Schema.string()).default(DEFAULT_FILE_WRITE_TOOLS.slice()),
+  fileWriteTools: Schema.array(Schema.string()).default(DEFAULT_FILE_WRITE_TOOLS.slice()).volatile(),
   /** Approval policies under which an ask could not be answered, so it is not raised. */
-  unattendedPolicies: Schema.array(Schema.string()).default(DEFAULT_UNATTENDED_POLICIES.slice()),
+  unattendedPolicies: Schema.array(Schema.string()).default(DEFAULT_UNATTENDED_POLICIES.slice()).volatile(),
   /** Force unattended behaviour where the approval policy is not visible. */
-  unattended: Schema.boolean().default(false),
+  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(),
+  /** Security engine instance (internal/testing). */
+  engine: Schema.any().hidden(),
 });
 
 function logBlocked(ctx, hit, who) {
@@ -161,7 +215,7 @@ function logBlocked(ctx, hit, who) {
 }
 
 export function apply(ctx, config) {
-  const cfg = Config(config || {}) || {};
+  const cfg = plainConfig(Config(plainConfig(config) || {}) || {});
   const toolName = cfg.toolName || DEFAULT_BASH_TOOL;
   const fileWriteTools = cfg.fileWriteTools || DEFAULT_FILE_WRITE_TOOLS.slice();
   const getLocale = function () {
@@ -170,7 +224,15 @@ export function apply(ctx, config) {
   };
   const registerLocale = function () {
     const locale = getLocale();
-    if (locale && typeof locale.register === "function") return locale.register(LOCALE_NS, MESSAGES);
+    if (locale && typeof locale.register === "function") {
+      try {
+        return locale.register(LOCALE_NS, MESSAGES);
+      } catch (err) {
+        if (ctx && ctx.logger && typeof ctx.logger.warn === "function") {
+          ctx.logger.warn("[dsh-approval-gate] locale registration skipped: " + (err && err.message || err));
+        }
+      }
+    }
   };
   if (ctx && typeof ctx.effect === "function") ctx.effect(registerLocale, "dsh-approval-gate: dictionaries");
   else registerLocale();
@@ -182,20 +244,56 @@ export function apply(ctx, config) {
   };
   const unattendedPolicies = cfg.unattendedPolicies || DEFAULT_UNATTENDED_POLICIES.slice();
   const forcedUnattended = cfg.unattended === true;
-  const engine = cfg.engine || new SecurityEngine({
-    inspectConfig: { toolName: toolName, fileWriteTools: fileWriteTools },
+  const engine = (config && config.engine) || cfg.engine || new SecurityEngine({
+    inspectConfig: { toolName: toolName, fileWriteTools: fileWriteTools, workspaceDir: cfg.workspaceDir || "" },
+    bands: new BandsEngine({ toolRegistry: ctx && ctx.tools }),
+    defaultVerdict: cfg.defaultVerdict || "allow",
   });
 
+  const gateService = {
+    engine,
+    addGrant: (options) => engine.addGrant(options),
+    resume: (sessionId, reason) => engine.resume(sessionId, reason),
+  };
+  if (ctx && typeof ctx === "object") {
+    if (typeof ctx.provide === "function") {
+      ctx.provide("approvalGate", gateService);
+    } else {
+      ctx.approvalGate = gateService;
+    }
+  }
+
   const hasPreExecute = ctx && typeof ctx.on === "function";
   if (hasPreExecute) {
     ctx.on("tools/pre-execute", function (execution, next) {
       const knobs = readKnobs(ctx, execution);
       const who = sessionTag(execution);
-      const sessionId = (execution && execution.agent && (execution.agent.session || execution.agent)) || "default";
-      const decision = engine.decide(execution, { sessionId, knobs });
+      const sessionId = resolveSessionId(execution);
+      let decision;
+      try {
+        decision = engine.decide(execution, { sessionId, knobs });
+      } catch (err) {
+        const hit = {
+          ask: true,
+          reason: "inspect-error",
+          detail: String(err && err.message || err),
+          snippet: (execution && execution.arguments && execution.arguments.command) || execution.name,
+        };
+        return { kind: "ask", reason: askMessage(hit, who, translate, ctx && ctx.logger) };
+      }
 
       if (decision.verdict === "ask") {
-        if (forcedUnattended || isUnattended({ policy: knobs.policy, unattendedPolicies })) {
+        if (decision.reason === "circuit-breaker-tripped") {
+          const hit = decision.hit || {
+            deny: true,
+            reason: "circuit-breaker-tripped",
+            detail: decision.detail,
+            snippet: (execution && execution.arguments && execution.arguments.command) || execution.name,
+          };
+          logBlocked(ctx, hit, who);
+          return denyMessage(hit, who, translate, ctx && ctx.logger);
+        }
+        if (forcedUnattended || isUnattended({ policy: knobs.policy, preset: knobs.preset, sandbox: knobs.sandbox, unattendedPolicies })) {
           return next();
         }
         const hit = decision.hit || {
@@ -212,8 +310,20 @@ export function apply(ctx, config) {
 
   const guard = function (execution) {
     const who = sessionTag(execution);
-    const sessionId = (execution && execution.agent && (execution.agent.session || execution.agent)) || "default";
-    const decision = engine.decide(execution, { sessionId });
+    const sessionId = resolveSessionId(execution);
+    let decision;
+    try {
+      decision = engine.decide(execution, { sessionId });
+    } catch (err) {
+      const hit = {
+        deny: true,
+        reason: "inspect-error",
+        detail: String(err && err.message || err),
+        snippet: (execution && execution.arguments && execution.arguments.command) || execution.name,
+      };
+      logBlocked(ctx, hit, who);
+      return denyMessage(hit, who, translate, ctx && ctx.logger);
+    }
 
     if (decision.verdict === "deny" || (decision.verdict === "ask" && !hasPreExecute)) {
       const hit = decision.hit || {
@@ -259,6 +369,4 @@ export {
 } from "./canonical.js";
 export { expandHome, resolveSafePath, isPathTraversal, canonicalizeFsPath } from "./paths.js";
 export { splitSubcommands } from "./tokenizer.js";
-
-
 export { redactCredentials, redactUrl } from "./redact.js";

package/lib/inspect.js

@@ -17,11 +17,12 @@ export const DEFAULT_FILE_WRITE_TOOLS = Object.freeze([
   "edit",
   "Write",
   "Edit",
+  "str_replace_editor",
   "str_replace",
   "apply_patch",
 ]);
 
-const PREFIXES = new Set(["then", "do"]);
+const PREFIXES = new Set(["then", "do", "{", "}", "!"]);
 const SHELLS = new Set(["bash", "sh", "dash", "zsh", "ksh", "ash"]);
 const INTERPRETERS = new Set(["python", "python2", "python3", "node", "nodejs", "perl", "ruby", "php"]);
 const DB_CLIENTS = new Set([
@@ -81,7 +82,7 @@ function splitSegments(tokens) {
 }
 
 function stripPrefixes(argv) {
-  const out = argv.slice();
+  const out = argv.filter(function (a) { return a !== "}" && a !== ";"; });
   while (out.length) {
     const head = out[0];
     if (PREFIXES.has(head)) { out.shift(); continue; }
@@ -175,7 +176,7 @@ function inspectInterpreterPayload(cmd, payload) {
   return allow();
 }
 
-function inspectArgv(argv, depth, hasHeredoc) {
+function inspectArgv(argv, depth, hasHeredoc, config = {}) {
   if (!argv.length) return allow();
   const cmd = basename(argv[0]);
   const rest = argv.slice(1);
@@ -188,7 +189,7 @@ function inspectArgv(argv, depth, hasHeredoc) {
   if (cmd === "env") {
     const sub = rest.filter(a => !a.startsWith("-") && !a.includes("="));
     if (sub.length > 0) {
-      return inspectArgv(sub, depth, hasHeredoc);
+      return inspectArgv(sub, depth, hasHeredoc, config);
     }
   }
 
@@ -197,7 +198,7 @@ function inspectArgv(argv, depth, hasHeredoc) {
     let next = skipWrapper(rest, arity);
     if (cmd === "timeout" && next.length) next = next.slice(1);
     if (cmd === "nice" && next.length && /^[0-9-]+$/.test(next[0])) next = next.slice(1);
-    return inspectArgv(next, depth, hasHeredoc);
+    return inspectArgv(next, depth, hasHeredoc, config);
   }
 
   if (cmd === "eval") return deny("eval", argv.join(" "));
@@ -256,7 +257,7 @@ function inspectArgv(argv, depth, hasHeredoc) {
     const script = scriptAfterDashC(rest);
     if (typeof script === "string") {
       if (depth > 4) return deny("nested-shell", script);
-      return inspectBashCommand(script, depth + 1);
+      return inspectBashCommand(script, depth + 1, config);
     }
     const scriptFile = rest.find(function (a) { return a && a[0] !== "-"; });
     if (scriptFile) return ask("script-file", "shell script contents are not available to the guard", scriptFile);
@@ -359,7 +360,7 @@ function commandNameFromSegment(seg) {
   return token ? basename(token.value) : "";
 }
 
-function inspectEmbeddedExpansions(source, depth) {
+function inspectEmbeddedExpansions(source, depth, config = {}) {
   if (depth > 8) return ask("unparseable", "nesting-depth", source);
   for (let i = 0; i < source.length; i += 1) {
     if (source[i] === "\\") { i += 1; continue; }
@@ -368,7 +369,7 @@ function inspectEmbeddedExpansions(source, depth) {
         ? readCommandSubstitution(source, i)
         : readBacktick(source, i);
       if (!sub) return ask("unparseable", "unclosed-command-substitution", source.slice(i));
-      const nested = inspectBashCommand(sub.script, depth + 1);
+      const nested = inspectBashCommand(sub.script, depth + 1, config);
       if (nested.deny || nested.ask) return nested;
       i = sub.end - 1;
       continue;
@@ -377,7 +378,7 @@ function inspectEmbeddedExpansions(source, depth) {
       const expansion = readParameterExpansion(source, i);
       if (!expansion) return ask("unparseable", "unclosed-parameter-expansion", source.slice(i));
       if (expansion.body !== undefined) {
-        const nested = inspectEmbeddedExpansions(expansion.body, depth + 1);
+        const nested = inspectEmbeddedExpansions(expansion.body, depth + 1, config);
         if (nested.deny || nested.ask) return nested;
       }
       i = expansion.end - 1;
@@ -386,7 +387,7 @@ function inspectEmbeddedExpansions(source, depth) {
   return allow();
 }
 
-function inspectPipelineHeredocs(tokens, depth) {
+function inspectPipelineHeredocs(tokens, depth, config = {}) {
   let group = [];
   let segment = [];
   function finishGroup() {
@@ -395,7 +396,7 @@ function inspectPipelineHeredocs(tokens, depth) {
     if (hasShell) {
       for (const part of group) {
         for (const heredoc of part.filter(function (t) { return t.kind === "heredoc"; })) {
-          const nested = inspectBashCommand(heredoc.body, depth + 1);
+          const nested = inspectBashCommand(heredoc.body, depth + 1, config);
           if (nested.deny || nested.ask) return nested;
         }
       }
@@ -440,7 +441,7 @@ function inspectUnparsedDanger(command) {
   return null;
 }
 
-export function inspectBashCommand(command, depth) {
+export function inspectBashCommand(command, depth = 0, config = {}) {
   if (depth === undefined) depth = 0;
   if (depth > 8) return ask("unparseable", "nesting-depth", String(command || ""));
   if (typeof command !== "string") return ask("unknown-format", "command is not a string", "non-string command");
@@ -453,7 +454,7 @@ export function inspectBashCommand(command, depth) {
   }
   if (hasDangerousPipeline(tokens)) return deny("curl-pipe", command);
   if (hasDestructiveSqlPipeline(tokens)) return deny("destructive-sql", command);
-  const pipelineHeredocHit = inspectPipelineHeredocs(tokens, depth);
+  const pipelineHeredocHit = inspectPipelineHeredocs(tokens, depth, config);
   if (pipelineHeredocHit.deny || pipelineHeredocHit.ask) return pipelineHeredocHit;
 
   const segs = splitSegments(tokens);
@@ -472,19 +473,19 @@ export function inspectBashCommand(command, depth) {
     for (const token of wordTokens) {
       for (const substitution of token.substitutions || []) {
         const nested = substitution.kind === "parameter-expansion"
-          ? inspectEmbeddedExpansions(substitution.script, depth + 1)
-          : inspectBashCommand(substitution.script, depth + 1);
+          ? inspectEmbeddedExpansions(substitution.script, depth + 1, config)
+          : inspectBashCommand(substitution.script, depth + 1, config);
         if (nested.deny || nested.ask) return nested;
       }
     }
 
     for (const redirect of redirectsOf(seg)) {
       if (redirect.dynamic) return ask("dynamic-redirect", "expanded redirect target cannot be verified", redirect.path);
-      const isRel = !/^(?:\/|[A-Za-z]:\/|\/\/)/.test(normalizeSeparators(redirect.path));
-      if (isRel && isPathTraversal(redirect.path, process.cwd())) {
-        return deny("path-traversal", redirect.path);
-      }
-      if (!isRel && isPathTraversal(redirect.path, "/")) {
+      const baseDir = (config && config.workspaceDir) || process.cwd();
+      const norm = normalizeSeparators(redirect.path);
+      const isRel = !/^(?:\/|[A-Za-z]:\/|\/\/)/.test(norm);
+      const isExempt = !isRel && (/^\/dev\/(?:null|zero|stdout|stderr|fd\/\d+)$/.test(norm) || /^(?:\/tmp|\/var\/tmp)(?:\/|$)/i.test(norm));
+      if (!isExempt && isPathTraversal(redirect.path, baseDir)) {
         return deny("path-traversal", redirect.path);
       }
       if (isProtectedPath(redirect.path)) return deny("secret-write", redirect.path);
@@ -504,13 +505,13 @@ export function inspectBashCommand(command, depth) {
     if (heredocs.length) {
       for (const heredoc of heredocs) {
         if (!heredoc.quoted) {
-          const expansionHit = inspectEmbeddedExpansions(heredoc.body, depth);
+          const expansionHit = inspectEmbeddedExpansions(heredoc.body, depth, config);
           if (expansionHit.deny || expansionHit.ask) return expansionHit;
         }
       }
       if (SHELLS.has(commandName)) {
         for (const heredoc of heredocs) {
-          const nested = inspectBashCommand(heredoc.body, depth + 1);
+          const nested = inspectBashCommand(heredoc.body, depth + 1, config);
           if (nested.deny || nested.ask) return nested;
         }
       } else if (INTERPRETERS.has(commandName)) {
@@ -527,7 +528,7 @@ export function inspectBashCommand(command, depth) {
       }
     }
 
-    const hit = inspectArgv(argv, depth, heredocs.length > 0);
+    const hit = inspectArgv(argv, depth, heredocs.length > 0, config);
     if (hit.deny || hit.ask) return hit;
   }
 
@@ -556,7 +557,7 @@ export function inspectExecution(execution, config) {
     const command = args && typeof args === "object" ? args.command : undefined;
     if (command === undefined || command === null || command === "") return allow();
     if (typeof command !== "string") return ask("unknown-format", "command is not a string", "non-string command");
-    return inspectBashCommand(command);
+    return inspectBashCommand(command, 0, config);
   }
   if (typeof name === "string" && fileTools.has(name)) {
     const path = pathFromArgs(args);

package/lib/messages.js

@@ -116,63 +116,6 @@ export const MESSAGES = Object.freeze({
     hintDestructiveSql: "请使用版本化数据库迁移，或执行非破坏性查询",
     hintCurlPipe: "先将脚本下载到本地检查内容，再安全执行",
   },
-  ru: {
-    blockedPrefix: "Заблокировано правилом dsh-approval-gate",
-    detectedLabel: "Обнаружено",
-    commandLabel: "Команда",
-    parseReasonLabel: "Причина разбора",
-    hintPrefix: "Подсказка",
-    detailProcessSubstitution: "подстановка процесса требует подтверждения",
-    detailUnclosedProcessSubstitution: "незакрытая подстановка процесса",
-    detailUnclosedCommandSubstitution: "незакрытая подстановка команды",
-    detailUnclosedBacktick: "незакрытая подстановка в обратных кавычках",
-    detailUnclosedParameterExpansion: "незакрытое расширение параметра",
-    detailUnclosedSingleQuote: "незакрытая одинарная кавычка",
-    detailUnclosedDoubleQuote: "незакрытая двойная кавычка",
-    detailDanglingEscape: "незавершённое экранирование",
-    detailInvalidHeredoc: "неверный разделитель here-document",
-    detailUnterminatedHeredoc: "ограничитель here-document не найден",
-    detailUnsupportedGrouping: "группировка shell не поддерживается анализатором",
-    detailUnsupported: "неподдерживаемый синтаксис shell",
-    approvalRequired: "Требуется подтверждение",
-    askUnknown: "Команда не может быть проверена полностью; проверьте её перед подтверждением",
-    askUnparseable: "Синтаксис shell не может быть проверен полностью; проверьте его перед подтверждением",
-    askUnknownFormat: "Формат вызова инструмента не может быть проверен; проверьте его перед подтверждением",
-    askUnknownWriteTarget: "Цель записи файла не может быть определена; проверьте её перед подтверждением",
-    askDynamicCommand: "Развёрнутое имя команды не может быть проверено; проверьте его перед подтверждением",
-    askDynamicArguments: "Развёрнутые аргументы чувствительной команды не могут быть проверены; проверьте их перед подтверждением",
-    askDynamicRedirect: "Развёрнутая цель перенаправления не может быть проверена; проверьте её перед подтверждением",
-    askScriptFile: "Содержимое файла скрипта недоступно для гейта; проверьте его перед подтверждением",
-    askShellStdin: "Ввод шелла недоступен для гейта в полном объёме; проверьте его перед подтверждением",
-    askInterpreterPayload: "Побочные эффекты интерпретатора не могут быть полностью проанализированы; проверьте их перед подтверждением",
-    askCredentialInArgv: "Развёрнутые учётные данные передаются как аргументы процесса; используйте безопасный API или проверьте перед подтверждением",
-    ruleUnknown: "Сработало защитное правило блокировки",
-    ruleRecursiveRm: "Рекурсивное удаление файлов",
-    ruleProcessSignal: "Завершение процесса",
-    ruleServiceControl: "Изменение состояния службы",
-    ruleGitClean: "Разрушительный git clean",
-    ruleGitResetHard: "Разрушительный git reset --hard",
-    ruleFindDelete: "find -delete",
-    ruleDestructiveSql: "Разрушительный SQL",
-    ruleSecretWrite: "Запись в защищённый файл с секретами",
-    ruleDeviceWrite: "Запись в системное устройство или защищённый файл",
-    ruleMkfsDevice: "Форматирование файловой системы",
-    ruleCurlPipe: "Передача скачанного содержимого в шелл",
-    ruleEval: "Динамическое выполнение шелла (eval)",
-    ruleNestedShell: "Превышен лимит вложенности шелла",
-    ruleInterpreterPayload: "Небезопасный исполняемый код интерпретатора",
-    ruleEnvDumpLeak: "Попытка утечки переменных окружения и секретов",
-    rulePathTraversal: "Обнаружена попытка обхода каталогов (path traversal)",
-    ruleBandHardDeny: "Команда заблокирована критическим списком безопасности Band 0",
-    ruleCircuitBreakerTripped: "Предохранитель сессии сработал из-за повторяющихся блокировок",
-    hintRecursiveRm: "Указывайте конкретные файлы вместо рекурсивного удаления",
-    hintPathTraversal: "Ограничьте операции пределами рабочего каталога проекта",
-    hintSecretWrite: "Изменяйте настройки через UI или переменные окружения, не перезаписывайте секретные файлы напрямую",
-    hintEnvDumpLeak: "Запрашивайте конкретные несекретные переменные по отдельности",
-    hintCircuitBreakerTripped: "Запросите подтверждение оператора перед повторной отправкой системных команд",
-    hintDestructiveSql: "Используйте версионированные миграции или выполняйте неразрушающие запросы",
-    hintCurlPipe: "Скачайте скрипт локально, проверьте его содержимое и выполните безопасно",
-  },
 });
 
 export function sessionTag(execution) {

package/lib/paths.js

@@ -69,7 +69,7 @@ export function expandHome(p, env = process.env) {
   // Expand leading ~ or ~/ or ~\
   res = res.replace(/^~(?=$|[/\\])/, cleanHome);
   // Expand ${HOME} and $HOME
-  res = res.replace(/\$\{HOME\}|\$HOME/g, cleanHome);
+  res = res.replace(/\$\{HOME\}|\$HOME(?=\$|[\/\\])/g, cleanHome);
   // Expand %USERPROFILE% (Windows)
   res = res.replace(/%USERPROFILE%/gi, cleanHome);
   return res;

package/lib/tokenizer.js

@@ -170,7 +170,7 @@ export function tokenize(src) {
             i = lineEnd + 1;
           }
           if (!found) return lexFail(src, i, "unterminated-heredoc", tokens);
-          tokens.push({ kind: "heredoc", body: body, quoted: heredoc.quoted });
+          tokens.push({ kind: "heredoc", body: body, quoted: heredoc.quoted, marker: heredoc.delimiter });
         }
         pendingHeredocs.length = 0;
         tokens.push({ kind: "op", value: ";" });
@@ -340,7 +340,7 @@ export function splitSubcommands(command) {
       .map((t) => t.value);
     const subStr = tokens
       .map((t) => {
-        if (t.kind === "heredoc") return `<<${t.marker}`;
+        if (t.kind === "heredoc") return `<<${t.marker || t.body || ""}`;
         return t.value;
       })
       .join(" ")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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",