@goodandready/dsh-approval-gate 0.1.21 → 0.1.22

package/lib/engine.js

@@ -22,6 +22,8 @@ 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).
@@ -99,6 +101,9 @@ export class SecurityEngine {
     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;
   }
 
   /**
@@ -432,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 };
@@ -504,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);
@@ -558,6 +563,12 @@ export class SecurityEngine {
     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;
   }
 
@@ -570,6 +581,8 @@ export class SecurityEngine {
   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);
+}

package/lib/index.js

@@ -8,6 +8,9 @@ import { assertHarnessCompatibility, provideServicePolyfill } from "./compat.js"
 import { extractFilePath } from "./dispatcher.js";
 import { SnapshotManager } from "./snapshots.js";
 import { MEASURE_KINDS, classifyMeasureKind } from "./measure-kinds.js";
+import { LineageManager } from "./lineage.js";
+import { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
+import { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification } from "./escalation.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -183,6 +186,16 @@ export function readKnobs(ctx, execution) {
     }
   }
 
+  // 5b. Lineage authority inheritance (#98)
+  if (!policy && session && (session.parentSession || session.parentId || session.parentSessionId)) {
+    const parent = session.parentSession || { id: session.parentId || session.parentSessionId };
+    if (typeof parent.approvalPolicy === "string") {
+      policy = parent.approvalPolicy;
+    } else if (approval && typeof approval.effectivePolicy === "function") {
+      try { policy = approval.effectivePolicy(parent) || ""; } catch {}
+    }
+  }
+
   // 6. Global static fallback from approval service config
   if (!policy && approval && approval.config && approval.config.policy) {
     policy = approval.config.policy;
@@ -253,6 +266,10 @@ export const Config = Schema.object({
   agentsRules: Schema.boolean().default(true).volatile(),
   /** Enforce human confirmation on breaking major dependency bumps in package.json (#95). */
   versionGuard: Schema.boolean().default(true).volatile(),
+  /** Require explicit justification for privilege escalation (#107). */
+  requireJustification: Schema.boolean().default(false).volatile(),
+  /** Enable automatic remediation advice for redundant sandbox privilege requests (#101). */
+  enableRedundantSandboxRecovery: Schema.boolean().default(true).volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -321,6 +338,8 @@ export function apply(ctx, config) {
       slaMs: cfg.classifierSlaMs !== undefined ? cfg.classifierSlaMs : 2000,
     }),
     defaultVerdict: cfg.defaultVerdict || "ask",
+    requireJustification: cfg.requireJustification === true,
+    enableRedundantSandboxRecovery: cfg.enableRedundantSandboxRecovery !== false,
     snapshotManager: new SnapshotManager({ workspaceDir: cfg.workspaceDir || "", maxSnapshotsPerSession: cfg.maxSnapshotsPerSession, maxSnapshotBytes: cfg.maxSnapshotBytes }),
     dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
     auditFailClosed: Boolean(cfg.auditFailClosed),
@@ -356,6 +375,20 @@ export function apply(ctx, config) {
     clearSnapshots: (sessionId) => (engine.clearSnapshots ? engine.clearSnapshots(sessionId) : { cleared: 0 }),
     clearAllSnapshots: () => (engine.clearAllSnapshots ? engine.clearAllSnapshots() : { cleared: 0 }),
     getSnapshotStats: () => (engine.snapshotManager ? engine.snapshotManager.getStats() : null),
+    lineage: engine.lineage,
+    registerLineage: (child, parent, root) => engine.registerLineage(child, parent, root),
+    getLineage: (id) => engine.getLineage(id),
+    guidance: {
+      generate: (opts) => generateAgentGuidance(opts),
+      inject: (prompt, opts) => injectAgentGuidance(prompt, opts),
+      extract: (prompt) => extractGuidance(prompt),
+    },
+    getAgentGuidance: (opts) => generateAgentGuidance(opts),
+    redundantSandbox: {
+      check: (cmd, mode, opts) => isRedundantSandboxRequest(cmd, mode, opts),
+      remediation: (cmd, lang) => buildRedundantSandboxRemediation(cmd, lang),
+    },
+    checkEscalationJustification: (cmd, tool, args, opts) => checkEscalationJustification(cmd, tool, args, opts),
     getSnapshot: () => ({
       active: true,
       dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
@@ -379,9 +412,12 @@ export function apply(ctx, config) {
       const knobs = readKnobs(ctx, execution);
       const who = sessionTag(execution);
       const sessionId = resolveSessionId(execution);
+      const callId = execution?.callId || execution?.id || null;
+      const agentId = execution?.agent?.id || execution?.agentId || null;
+      const subagentId = execution?.agent?.subagentId || execution?.subagentId || null;
       let decision;
       try {
-        decision = engine.decide(execution, { sessionId, knobs });
+        decision = engine.decide(execution, { sessionId, knobs, callId, agentId, subagentId, sandboxMode: knobs.sandbox, preset: knobs.preset });
       } catch (err) {
         const hit = {
           ask: true,
@@ -444,9 +480,12 @@ export function apply(ctx, config) {
   const guard = function (execution) {
     const who = sessionTag(execution);
     const sessionId = resolveSessionId(execution);
+    const callId = execution?.callId || execution?.id || null;
+    const agentId = execution?.agent?.id || execution?.agentId || null;
+    const subagentId = execution?.agent?.subagentId || execution?.subagentId || null;
     let decision;
     try {
-      decision = engine.decide(execution, { sessionId });
+      decision = engine.decide(execution, { sessionId, callId, agentId, subagentId });
     } catch (err) {
       const hit = {
         deny: true,
@@ -533,6 +572,9 @@ export { detectHarnessCapabilities, assertHarnessCompatibility, provideServicePo
 export { parseSemver, isMajorBump, inspectPackageJsonDiff, VersionGuard } from "./version-guard.js";
 export { SnapshotManager, DEFAULT_MAX_SNAPSHOTS_PER_SESSION, DEFAULT_MAX_SNAPSHOT_BYTES } from "./snapshots.js";
 export { MEASURE_KINDS, classifyMeasureKind, isSystemLevelExecution, isWorkspaceWideExecution } from "./measure-kinds.js";
+export { LineageManager } from "./lineage.js";
+export { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
+export { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification, REDUNDANT_SANDBOX_REASON, MISSING_JUSTIFICATION_REASON, INSUFFICIENT_JUSTIFICATION_REASON } from "./escalation.js";
 
 
 

package/lib/lineage.js

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