@goodandready/dsh-approval-gate 0.1.20 → 0.1.22

package/lib/engine.js

@@ -13,13 +13,17 @@ import { DeclarativeRulesEngine } from "./rules-loader.js";
 import { BlockCounters } from "./counters.js";
 import { ContractGuard } from "./contract-guard.js";
 import { OverengineeringGuard } from "./overengineering.js";
-import { extractFilePath, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
+import { extractFilePath, DEFAULT_BASH_TOOL, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
 import { categorizeRiskBucket, extractRiskTags } from "./risk.js";
 import { ClassifierLatencyTracker } from "./latency.js";
 import { ArtifactRegistry } from "./artifacts.js";
 import { isRmCommand, extractRmTargets, suggestTrashAlternative } from "./trash.js";
 import { VersionGuard } from "./version-guard.js";
 import { loadAgentsRules, evaluateAgentsRules } from "./agents-parser.js";
+import { classifyMeasureKind } from "./measure-kinds.js";
+import { SnapshotManager } from "./snapshots.js";
+import { LineageManager } from "./lineage.js";
+import { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification } from "./escalation.js";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -79,7 +83,7 @@ export class SecurityEngine {
     this.classifier = options.classifier || null;
     this.timeoutPolicy = options.timeoutPolicy === "permissive" ? "permissive" : "strict";
     this.grantRegistry = options.grantRegistry || new SessionGrantStore(options);
-    this.defaultVerdict = options.defaultVerdict || "allow";
+    this.defaultVerdict = options.defaultVerdict || "ask";
 
     this.dryRun = Boolean(options.dryRun || options.shadowMode);
     this.auditFailClosed = options.auditFailClosed === true;
@@ -87,33 +91,19 @@ export class SecurityEngine {
     this.retryGuard = options.retryGuard !== undefined ? options.retryGuard : new RetryExhaustionGuard();
     this.ledger = options.ledger !== undefined ? options.ledger : new QualityLedger();
     this.counters = options.counters || new BlockCounters();
-    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger({
-      failClosed: this.auditFailClosed,
-    });
-    if (this.auditFailClosed && this.auditLogger) {
-      this.auditLogger.failClosed = true;
-    }
-    this.declarativeRules = options.declarativeRules || new DeclarativeRulesEngine({
-      workspaceDir: this.inspectConfig?.workspaceDir,
-    });
-    this.contractGuard = options.contractGuard !== undefined
-      ? options.contractGuard
-      : (options.taskContract ? new ContractGuard(options.taskContract) : null);
-    this.overengineeringGuard = options.overengineeringGuard !== undefined
-      ? options.overengineeringGuard
-      : (options.maxFilesPerSession !== undefined || options.maxCreatedFilesPerSession !== undefined
-          ? new OverengineeringGuard(options)
-          : null);
+    this.auditLogger = options.auditLogger !== undefined ? options.auditLogger : new AuditLogger({ failClosed: this.auditFailClosed });
+    if (this.auditFailClosed && this.auditLogger) this.auditLogger.failClosed = true;
+    this.declarativeRules = options.declarativeRules || new DeclarativeRulesEngine({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.contractGuard = options.contractGuard !== undefined ? options.contractGuard : (options.taskContract ? new ContractGuard(options.taskContract) : null);
+    this.overengineeringGuard = options.overengineeringGuard !== undefined ? options.overengineeringGuard : (options.maxFilesPerSession !== undefined || options.maxCreatedFilesPerSession !== undefined ? new OverengineeringGuard(options) : null);
     this.latencyTracker = options.latencyTracker || new ClassifierLatencyTracker(options);
-    this.artifactRegistry = options.artifactRegistry !== undefined
-      ? options.artifactRegistry
-      : new ArtifactRegistry({ workspaceDir: this.inspectConfig?.workspaceDir });
-    this.versionGuard = options.versionGuard !== undefined
-      ? options.versionGuard
-      : new VersionGuard({ workspaceDir: this.inspectConfig?.workspaceDir });
-    this.agentsRules = options.agentsRules !== undefined
-      ? options.agentsRules
-      : (loadAgentsRules(this.inspectConfig?.workspaceDir)?.rules || null);
+    this.artifactRegistry = options.artifactRegistry !== undefined ? options.artifactRegistry : new ArtifactRegistry({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.versionGuard = options.versionGuard !== undefined ? options.versionGuard : new VersionGuard({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.agentsRules = options.agentsRules !== undefined ? options.agentsRules : (loadAgentsRules(this.inspectConfig?.workspaceDir)?.rules || null);
+    this.snapshotManager = options.snapshotManager !== undefined ? options.snapshotManager : new SnapshotManager({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.lineage = options.lineage !== undefined ? options.lineage : new LineageManager();
+    this.enableRedundantSandboxRecovery = options.enableRedundantSandboxRecovery !== false;
+    this.requireJustification = options.requireJustification === true;
   }
 
   /**
@@ -447,7 +437,34 @@ export class SecurityEngine {
       return res;
     }
 
-    // P2: Static Rules / Safe Allow
+    // Redundant Sandbox Recovery (#101)
+    if (this.enableRedundantSandboxRecovery && isRedundantSandboxRequest(command, context?.sandboxMode || context?.preset, { toolName, args: execution?.arguments })) {
+      const advice = buildRedundantSandboxRemediation(command);
+      const hit = { ask: true, reason: "redundant-sandbox-privilege", detail: advice, snippet: command };
+      const res = { verdict: "ask", stage: "P4", reason: "redundant-sandbox-privilege", detail: advice, redundantSandbox: true, hit };
+      this._applyLockedAskIfCritical(res, toolName, command, execution);
+      return res;
+    }
+
+    // P2: Static Rules / Safe Allow (Bands Engine)
+    if (bandVerdict === "allow" && !this.requireJustification) {
+      this.breaker.resetConsecutive(sessionId);
+      return { verdict: "allow", stage: "P2", reason: "safe-allow", hit };
+    }
+
+    // Escalation Justification Protocol (#107)
+    const just = checkEscalationJustification(command, toolName, execution?.arguments, {
+      context,
+      justification: context?.justification || execution?.justification || execution?.arguments?.justification,
+      requireJustification: this.requireJustification,
+    });
+    if (just.required && !just.valid) {
+      const hit = { ask: true, reason: just.reason, detail: just.detail, snippet: command || toolName };
+      const res = { verdict: "ask", stage: "P4", reason: just.reason, detail: just.detail, justificationAdvice: just.advice, hit };
+      this._applyLockedAskIfCritical(res, toolName, command, execution);
+      return res;
+    }
+
     if (bandVerdict === "allow") {
       this.breaker.resetConsecutive(sessionId);
       return { verdict: "allow", stage: "P2", reason: "safe-allow", hit };
@@ -493,8 +510,10 @@ export class SecurityEngine {
       }
     }
 
-    // Default verdict for unclassified commands (#163)
-    if (this.defaultVerdict === "ask") {
+    // Default verdict for unclassified commands (#163, #172)
+    const bashTool = this.inspectConfig?.toolName || DEFAULT_BASH_TOOL;
+    const isBashTool = toolName === bashTool || !toolName;
+    if (isBashTool && this.defaultVerdict === "ask") {
       const askHit = { ask: true, reason: "unmatched-ask", snippet: command || toolName };
       const res = { verdict: "ask", stage: "P4", reason: "unmatched-ask", hit: askHit };
       this._applyLockedAskIfCritical(res, toolName, command, execution);
@@ -517,40 +536,13 @@ export class SecurityEngine {
     }
   }
 
-  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 [];
-  }
-
-  getLedgerSummary(sessionId) {
-    return this.ledger ? this.ledger.getSummary(sessionId) : null;
-  }
-
-  isRetryExhausted(sessionId) {
-    return this.retryGuard ? this.retryGuard.isExhausted(sessionId) : false;
-  }
-
-  clearCache() {
-    if (this.cache) this.cache.clear();
-  }
-
-  getCounters() {
-    return this.counters ? this.counters.getSnapshot() : null;
-  }
-
-  resetCounters() {
-    if (this.counters) this.counters.reset();
-  }
-
+  addGrant(options) { return this.grantRegistry?.addGrant ? this.grantRegistry.addGrant(options) : null; }
+  getGrants(sessionId) { return this.grantRegistry?.getGrants ? this.grantRegistry.getGrants(sessionId) : []; }
+  getLedgerSummary(sessionId) { return this.ledger ? this.ledger.getSummary(sessionId) : null; }
+  isRetryExhausted(sessionId) { return this.retryGuard ? this.retryGuard.isExhausted(sessionId) : false; }
+  clearCache() { if (this.cache) this.cache.clear(); }
+  getCounters() { return this.counters ? this.counters.getSnapshot() : null; }
+  resetCounters() { if (this.counters) this.counters.reset(); }
   resume(sessionId, reason) {
     if (this.retryGuard) this.retryGuard.reset(sessionId);
     if (this.overengineeringGuard) this.overengineeringGuard.reset(sessionId);
@@ -566,28 +558,31 @@ export class SecurityEngine {
     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.measureKind) decision.measureKind = classifyMeasureKind(execution, context);
     const command = execution && execution.arguments && execution.arguments.command;
     if (command && isRmCommand(command)) {
       decision.trashAlternative = suggestTrashAlternative(command, this.inspectConfig?.workspaceDir, context?.sessionId);
     }
+    const callId = context?.callId || execution?.callId || execution?.id || context?.execution?.id || null;
+    const agentId = context?.agentId || context?.agent?.id || context?.session?.agentId || execution?.agentId || null;
+    const subagentId = context?.subagentId || context?.session?.subagentId || execution?.subagentId || null;
+    if (callId) decision.callId = callId;
+    if (agentId) decision.agentId = agentId;
+    if (subagentId) decision.subagentId = subagentId;
     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;
-  }
-
-  resetLatencyTracker() {
-    if (this.latencyTracker) this.latencyTracker.reset();
-  }
+  getArtifacts(sessionId) { return this.artifactRegistry ? this.artifactRegistry.getArtifacts(sessionId) : []; }
+  clearArtifacts(sessionId) { if (this.artifactRegistry) this.artifactRegistry.clearSession(sessionId); }
+  getLatencyMetrics() { return this.latencyTracker ? this.latencyTracker.getMetrics() : null; }
+  resetLatencyTracker() { if (this.latencyTracker) this.latencyTracker.reset(); }
+  takeSnapshot(targetPath, meta) { return this.snapshotManager ? this.snapshotManager.takeSnapshot(targetPath, meta) : null; }
+  rollbackSnapshot(id) { return this.snapshotManager ? this.snapshotManager.rollbackSnapshot(id) : { success: false, error: "no-snapshot-manager" }; }
+  getSnapshots(sessionId) { return this.snapshotManager ? this.snapshotManager.getSnapshots(sessionId) : []; }
+  clearSnapshots(sessionId) { return this.snapshotManager ? this.snapshotManager.clearSnapshots(sessionId) : { cleared: 0 }; }
+  clearAllSnapshots() { return this.snapshotManager ? this.snapshotManager.clearAllSnapshots() : { cleared: 0 }; }
+  getLineage(sessionId) { return this.lineage ? this.lineage.getLineage(sessionId) : [sessionId]; }
+  registerLineage(child, parent, root) { return this.lineage ? this.lineage.registerLineage(child, parent, root) : false; }
 }
 
 

package/lib/escalation.js

@@ -0,0 +1,151 @@
+// lib/escalation.js
+// Redundant sandbox recovery (#101) and privilege escalation justification (#107).
+// Prevents unnecessary danger-full-access requests and enforces accountable escalation justifications.
+
+import { isSystemLevelExecution } from "./measure-kinds.js";
+
+export const REDUNDANT_SANDBOX_REASON = "redundant-sandbox-privilege";
+export const MISSING_JUSTIFICATION_REASON = "missing-escalation-justification";
+export const INSUFFICIENT_JUSTIFICATION_REASON = "insufficient-escalation-justification";
+
+const PLACEHOLDER_JUSTIFICATIONS = new Set([
+  "none",
+  "n/a",
+  "na",
+  "test",
+  "testing",
+  "sudo",
+  "fix",
+  "run",
+  "escalate",
+  "please",
+  "bypass",
+  "temp",
+]);
+
+const INTERNAL_SAFE_COMMAND_REGEX = /^(?:git\s+(?:status|diff|log|branch|show)|npm\s+(?:test|run\s+test|run\s+lint)|pnpm\s+(?:test|run\s+test)|node\s+[\w\-./]+\.m?[jt]s|cat\s+|head\s+|tail\s+|grep\s+|find\s+|ls\b|pwd\b|echo\b)/i;
+
+/**
+ * Checks whether an elevated sandbox request is redundant for a safe internal command (#101).
+ *
+ * @param {string} [command]
+ * @param {string} [requestedMode]
+ * @param {{ toolName?: string, args?: any }} [options]
+ * @returns {boolean}
+ */
+export function isRedundantSandboxRequest(command, requestedMode, options = {}) {
+  const mode = String(requestedMode || options.sandboxMode || "").toLowerCase();
+  const isElevated = mode === "danger-full-access" || mode === "full-access" || mode === "danger" || mode === "unrestricted";
+  if (!isElevated) return false;
+
+  const cmd = String(command || "").trim();
+  if (!cmd) return false;
+
+  // If command is system-level, escalation might be genuine (not redundant)
+  if (isSystemLevelExecution(cmd, options.toolName, options.args)) {
+    return false;
+  }
+
+  // If command contains explicit dangerous tokens, it's not a redundant request
+  if (/\b(?:sudo|docker|systemctl|service|apt|apt-get|apk|dnf|pacman|chown|chmod\s+-R)\b/i.test(cmd)) {
+    return false;
+  }
+
+  // Safe internal commands: reading, status, unit testing
+  return INTERNAL_SAFE_COMMAND_REGEX.test(cmd);
+}
+
+/**
+ * Builds actionable remediation advice for redundant sandbox requests (#101).
+ *
+ * @param {string} command
+ * @param {"en" | "ru" | "zh"} [lang="en"]
+ * @returns {string}
+ */
+export function buildRedundantSandboxRemediation(command, lang = "en") {
+  const cmd = String(command || "").trim();
+  if (lang === "ru") {
+    return `Избыточный запрос привилегий песочницы: команда '${cmd}' является безопасной внутрипроектной операцией. Повторите вызов в стандартном режиме песочницы без 'danger-full-access'.`;
+  }
+  if (lang === "zh") {
+    return `请求了冗余的沙箱提权：命令 '${cmd}' 为工作区内部安全操作。请以普通沙箱模式重新执行，无需 'danger-full-access'。`;
+  }
+  return `Redundant sandbox elevation requested: command '${cmd}' is workspace-internal and safe. Repeat the command in standard sandbox mode without 'danger-full-access'.`;
+}
+
+/**
+ * Checks whether privilege escalation requires justification and whether provided justification is valid (#107).
+ *
+ * @param {string} [command]
+ * @param {string} [toolName]
+ * @param {any} [args]
+ * @param {{
+ *   justification?: string,
+ *   context?: any,
+ *   requireJustification?: boolean,
+ *   lang?: "en" | "ru" | "zh"
+ * }} [options]
+ * @returns {{
+ *   required: boolean,
+ *   valid: boolean,
+ *   reason?: string,
+ *   detail?: string,
+ *   advice?: string
+ * }}
+ */
+export function checkEscalationJustification(command, toolName, args, options = {}) {
+  const cmd = String(command || "").trim();
+  const execObj = { name: toolName || "bash", arguments: { ...(args || {}), command: cmd } };
+  const isSystem = isSystemLevelExecution(execObj, options.context);
+  const explicitRequire = options.requireJustification === true || options.context?.requireJustification === true;
+  const isEscalatedSandbox = Boolean(options.context?.sandboxMode && options.context.sandboxMode !== "sandboxed");
+
+  // Escalation justification is required when explicitly required OR when escalated sandbox mode is requested for system operations
+  const escalationRequired = explicitRequire || (isEscalatedSandbox && isSystem);
+  if (!escalationRequired) {
+    return { required: false, valid: true };
+  }
+
+  const rawJustification =
+    (typeof options.justification === "string" && options.justification) ||
+    (typeof args?.justification === "string" && args.justification) ||
+    (typeof options.context?.justification === "string" && options.context.justification) ||
+    "";
+
+  const justification = rawJustification.trim();
+  const lang = options.lang || "en";
+
+  if (!justification) {
+    return {
+      required: true,
+      valid: false,
+      reason: MISSING_JUSTIFICATION_REASON,
+      detail: `Privilege escalation for '${cmd || toolName}' requires an explicit justification.`,
+      advice: lang === "ru"
+        ? "Укажите поле 'justification' с объяснением необходимости системных привилегий."
+        : lang === "zh"
+        ? "执行系统级操作必须提供 'justification' 理由说明。"
+        : "Provide a 'justification' field explaining why elevated privileges are necessary.",
+    };
+  }
+
+  if (justification.length < 10 || PLACEHOLDER_JUSTIFICATIONS.has(justification.toLowerCase())) {
+    return {
+      required: true,
+      valid: false,
+      reason: INSUFFICIENT_JUSTIFICATION_REASON,
+      detail: `Justification '${justification}' is too short or generic (minimum 10 non-placeholder characters required).`,
+      advice: lang === "ru"
+        ? "Обоснование слишком короткое или шаблонное. Опишите конкретную причину эскалации."
+        : lang === "zh"
+        ? "理由说明过短或为占位符。请详细描述提权的实际原因（至少10个字符）。"
+        : "Justification is too brief or placeholder. Describe the specific reason for privilege escalation.",
+    };
+  }
+
+  return {
+    required: true,
+    valid: true,
+    justification,
+  };
+}

package/lib/guidance.js

@@ -0,0 +1,119 @@
+// lib/guidance.js
+// Dynamic security guidance for system prompts (AUTO_MODE_AGENT_GUIDANCE) (#99).
+// Injects structured execution expectations and gate constraints directly into agent context.
+
+export const GUIDANCE_MARKER = "<!-- dsh-approval-gate:guidance -->";
+
+/**
+ * Generates structured agent safety guidance.
+ *
+ * @param {{
+ *   language?: "en" | "ru" | "zh",
+ *   failClosed?: boolean,
+ *   trashEnabled?: boolean,
+ *   snapshotsEnabled?: boolean,
+ *   justificationRequired?: boolean,
+ *   redundantSandboxRecovery?: boolean,
+ *   workspaceDir?: string
+ * }} [options]
+ * @returns {string}
+ */
+export function generateAgentGuidance(options = {}) {
+  const lang = options.language || "en";
+  const failClosed = options.failClosed !== false;
+  const trash = options.trashEnabled !== false;
+  const snapshots = options.snapshotsEnabled !== false;
+  const justification = options.justificationRequired !== false;
+
+  if (lang === "ru") {
+    return [
+      GUIDANCE_MARKER,
+      "### Инструкции безопасности среды выполнения (dsh-approval-gate)",
+      failClosed
+        ? "- **Режим выполнения**: Включен строгий контроль (fail-closed). Нераспознанные шелл-команды требуют ручного подтверждения."
+        : "- **Режим выполнения**: Стандартный контроль команд.",
+      snapshots
+        ? "- **Снимки файлов**: Перед изменением файлов автоматически создаются pre-execution снимки. Избегайте слепой перезаписи."
+        : "",
+      trash
+        ? "- **Удаление файлов**: Запрещено безусловное `rm -rf`. Используйте перемещение в сессионную корзину `.dsh/trash/<session>/` или очистку сессионных артефактов."
+        : "- **Удаление файлов**: Удаляйте файлы строго в границах текущего рабочего каталога.",
+      "- **Песочница**: Не запрашивайте `danger-full-access` или выход из песочницы для стандартных задач внутри проекта.",
+      justification
+        ? "- **Эскалация привилегий**: Любая системная операция (apt, systemctl, сетевые вызовы) требует обязательного поля `justification` с обоснованием."
+        : "",
+      "- **Безопасные команды**: Чтение файлов, `git status`, `git diff`, `npm test` выполняются быстро и без запроса подтверждения.",
+    ].filter(Boolean).join("\n");
+  }
+
+  if (lang === "zh") {
+    return [
+      GUIDANCE_MARKER,
+      "### 执行环境安全指引 (dsh-approval-gate)",
+      failClosed
+        ? "- **执行模式**: 已启用严格安全保护 (fail-closed)。未识别的命令需人工确认。"
+        : "- **执行模式**: 标准命令控制。",
+      snapshots
+        ? "- **文件快照**: 修改文件前会自动生成执行前快照。请避免盲目覆盖文件。"
+        : "",
+      trash
+        ? "- **文件删除**: 禁止盲目运行 `rm -rf`。优先移动至会话回收站 `.dsh/trash/<session>/`。"
+        : "- **文件删除**: 请确保仅在项目工作区内删除文件。",
+      "- **沙箱权限**: 请勿对常规项目任务请求 `danger-full-access` 或沙箱提升。",
+      justification
+        ? "- **权限提升**: 任何系统级操作或跨目录访问必须附带明确的 `justification` 说明。"
+        : "",
+      "- **安全检查**: `git status`、`git diff`、`npm test` 等检查操作自动放行。",
+    ].filter(Boolean).join("\n");
+  }
+
+  // Default: English
+  return [
+    GUIDANCE_MARKER,
+    "### Security & Execution Guidance (dsh-approval-gate)",
+    failClosed
+      ? "- **Execution Mode**: Strict fail-closed policy is active. Unrecognized shell commands require human approval."
+      : "- **Execution Mode**: Standard execution controls active.",
+    snapshots
+      ? "- **File Mutations**: Pre-execution snapshots are captured automatically before writes. Avoid blind destructive overwrites."
+      : "",
+    trash
+      ? "- **Deletion Policy**: Do NOT run unconditional `rm -rf`. Prefer moving to session trash `.dsh/trash/<session>/` or safe artifact cleanup."
+      : "- **Deletion Policy**: Keep all deletions strictly within the workspace boundary.",
+    "- **Sandbox Boundaries**: Do NOT request `danger-full-access` or sandbox elevation for standard internal project tasks.",
+    justification
+      ? "- **Privilege Escalation**: Any system-level command or out-of-workspace access requires an explicit `justification` explanation."
+      : "",
+    "- **Safe Inspection**: Inspection commands (`git status`, `git diff`, `npm test`, `cat`, `ls`) are fast-tracked and safe.",
+  ].filter(Boolean).join("\n");
+}
+
+/**
+ * Injects guidance into system prompt idempotently.
+ *
+ * @param {string} systemPrompt
+ * @param {Parameters<typeof generateAgentGuidance>[0]} [options]
+ * @returns {string}
+ */
+export function injectAgentGuidance(systemPrompt, options = {}) {
+  if (typeof systemPrompt !== "string") {
+    return generateAgentGuidance(options);
+  }
+  if (systemPrompt.includes(GUIDANCE_MARKER)) {
+    return systemPrompt;
+  }
+  const guidance = generateAgentGuidance(options);
+  return `${systemPrompt.trimEnd()}\n\n${guidance}`;
+}
+
+/**
+ * Extracts injected guidance block from prompt if present.
+ * @param {string} prompt
+ * @returns {string|null}
+ */
+export function extractGuidance(prompt) {
+  if (typeof prompt !== "string") return null;
+  const idx = prompt.indexOf(GUIDANCE_MARKER);
+  if (idx === -1) return null;
+  return prompt.slice(idx);
+}