@duckmind/dm-linux-x64 0.65.5 → 0.65.6

package/extensions/dm-subagents/src/runs/shared/subagent-prompt-runtime.js

@@ -2,35 +2,26 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.js";
-import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.js";
-import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, PERMISSION_POLICY_ENV } from "./permissions.js";
-import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir } from "../background/control-channel.js";
-import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_FORK_CACHE_KEY_ENV, SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./dm-args.js";
-import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV, isRuntimeAcknowledgedExtensionId, writeRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.js";
-import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.js";
-import {
-  CHILD_TOOL_DIAGNOSTIC_PATH_ENV,
-  formatChildToolDiagnostic,
-  MCP_DIRECT_CHILD_TOOLS_ENV,
-  REQUIRED_CHILD_TOOLS_ENV,
-  writeChildToolDiagnostic
-} from "./tool-availability.js";
-import { TOOL_BUDGET_ENV, TOOL_BUDGET_ZERO_AUTH_ENV, decodeToolBudgetEnv, shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.js";
+import { permissionDecision } from "./permissions.js";
+import { RUNTIME_EXTENSION_ACK_EVENT, isRuntimeAcknowledgedExtensionId } from "./runtime-acknowledged-extensions.js";
+import { createStructuredOutputToolParameters, MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR, validateStructuredOutputValue } from "./structured-output.js";
+import { validateAcceptanceReport } from "./acceptance.js";
+import { formatChildToolDiagnostic } from "./tool-availability.js";
+import { shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.js";
+import { INTERCOM_SESSION_IDENTITY_EVENT } from "../../shared/types.js";
 import { resolveCurrentSessionId } from "../../shared/session-identity.js";
-import { getAgentDir, resolveWatchPath } from "../../shared/utils.js";
+import { getAgentDir } from "../../shared/utils.js";
 import { registerChildWatchdog } from "../../watchdog/register-child.js";
-import { CHILD_WATCHDOG_CONFIG_ENV, decodeChildWatchdogConfig } from "../../watchdog/child-status.js";
 import { requestWatchdogPermission } from "../../watchdog/permission-arbiter.js";
 import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.js";
-import { resolveWaitToolConfig } from "../background/wait-config.js";
+import { captureWatchdogDiffBaseline, createWatchdogDiffTool, WATCHDOG_DIFF_TOOL_NAME } from "../../watchdog/diff-tool.js";
+import { inheritedNestedRouteOf } from "./nested-events.js";
 import { registerWaitTool } from "../background/wait-tool.js";
 import { drainOutstandingWork } from "../background/auto-drain.js";
-const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "DM_SUBAGENT_INHERIT_PROJECT_CONTEXT";
-const SUBAGENT_INHERIT_SKILLS_ENV = "DM_SUBAGENT_INHERIT_SKILLS";
-export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "DM_SUBAGENT_INTERCOM_SESSION_NAME";
-export const SUBAGENT_SESSION_NAME_ENV = "DM_SUBAGENT_SESSION_NAME";
-const STEERING_LEGACY_SETTLE_FALLBACK_MS = 1000;
-const STEERING_SAFETY_POLL_INTERVAL_MS = 5000;
+import {
+  childSupervisorMetadata,
+  evaluateChildToolDiagnostic
+} from "./child-runtime-config.js";
 const STRUCTURED_OUTPUT_INSTRUCTIONS = [
   "This subagent step has a strict structured output contract.",
   "Your final action must be to call the `structured_output` tool with JSON matching the provided schema.",
@@ -81,46 +72,8 @@ const SKILLS_HEADER = `
 The following skills provide specialized instructions for specific tasks.`;
 const DATE_HEADER = `
 Current date:`;
-function readBooleanEnv(name) {
-  const value = process.env[name];
-  if (value === undefined)
-    return;
-  return value !== "0";
-}
-function readRequiredChildTools() {
-  const encoded = process.env[REQUIRED_CHILD_TOOLS_ENV]?.trim();
-  if (!encoded)
-    return;
-  const required = JSON.parse(encoded);
-  if (!Array.isArray(required) || required.some((name) => typeof name !== "string" || !name)) {
-    throw new Error(`Invalid ${REQUIRED_CHILD_TOOLS_ENV} payload.`);
-  }
-  return required;
-}
-function readMcpDirectChildTools() {
-  const encoded = process.env[MCP_DIRECT_CHILD_TOOLS_ENV]?.trim();
-  if (!encoded)
-    return;
-  try {
-    const tools = JSON.parse(encoded);
-    if (!Array.isArray(tools) || tools.some((name) => typeof name !== "string" || !name))
-      return;
-    return tools;
-  } catch {
-    return;
-  }
-}
-function refreshChildToolDiagnostic(dm) {
-  const filePath = process.env[CHILD_TOOL_DIAGNOSTIC_PATH_ENV]?.trim();
-  const required = readRequiredChildTools();
-  if (!filePath || !required)
-    return;
-  const available = dm.getAllTools().map((tool) => tool.name);
-  return writeChildToolDiagnostic(filePath, required, available, process.env[SUBAGENT_CHILD_AGENT_ENV]?.trim(), readMcpDirectChildTools());
-}
-function registerRuntimeExtensionAcknowledgements(dm) {
-  const outputPath = process.env[RUNTIME_EXTENSION_ACK_PATH_ENV]?.trim();
-  if (!outputPath)
+function registerRuntimeExtensionAcknowledgements(dm, sink) {
+  if (!sink)
     return;
   const ids = [];
   let finalized = false;
@@ -136,7 +89,7 @@ function registerRuntimeExtensionAcknowledgements(dm) {
     if (finalized)
       return;
     finalized = true;
-    writeRuntimeAcknowledgedExtensions(outputPath, ids);
+    sink(ids);
     return;
   };
   try {
@@ -257,7 +210,7 @@ export function rewriteSubagentPrompt(prompt, options) {
   rewritten = stripSubagentOrchestrationSkill(rewritten);
   rewritten = stripChildBoundaryInstructions(rewritten);
   const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
-  const structured = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV] ? `
+  const structured = options.structuredOutput ? `
 
 ${STRUCTURED_OUTPUT_INSTRUCTIONS}` : "";
   return `${boundary}${structured}
@@ -294,9 +247,9 @@ const PROMPT_CACHE_KEY_APIS = new Set([
   "openai-completions",
   "openai-responses"
 ]);
-export function rewriteForkCacheProviderRequest(event, ctx) {
-  const forkCacheKey = process.env[SUBAGENT_FORK_CACHE_KEY_ENV]?.trim();
-  if (!forkCacheKey || !PROMPT_CACHE_KEY_APIS.has(ctx?.model?.api ?? ""))
+export function rewriteForkCacheProviderRequest(event, ctx, forkCacheKey) {
+  const key = forkCacheKey?.trim();
+  if (!key || !PROMPT_CACHE_KEY_APIS.has(ctx?.model?.api ?? ""))
     return;
   if (!event || typeof event !== "object")
     return;
@@ -305,7 +258,7 @@ export function rewriteForkCacheProviderRequest(event, ctx) {
     return;
   if (typeof payload.prompt_cache_key !== "string")
     return;
-  return { ...payload, prompt_cache_key: forkCacheKey };
+  return { ...payload, prompt_cache_key: key };
 }
 function portableToolId(id) {
   if (PORTABLE_TOOL_ID_PATTERN.test(id) && id.length <= MAX_PORTABLE_TOOL_ID_LENGTH)
@@ -348,7 +301,7 @@ function stripAssistantSubagentToolCallBlocks(message) {
   return { ...m, content: filteredContent };
 }
 export function stripParentOnlySubagentMessages(messages, options = {}) {
-  const preserveCurrentFanoutToolHistory = process.env[SUBAGENT_FANOUT_CHILD_ENV] === "1";
+  const preserveCurrentFanoutToolHistory = options.preserveFanoutToolHistory === true;
   const sanitizeToolIds = options.sanitizeToolIds ?? true;
   let changed = false;
   const filtered = [];
@@ -379,10 +332,12 @@ export function formatSteerMessage(request) {
   ].join(`
 `);
 }
-export function registerPermissionGate(dm, requestPermission = requestWatchdogPermission) {
-  const rules = decodePermissionRules(process.env[PERMISSION_POLICY_ENV]);
-  if (!rules)
+export function registerPermissionGate(dm, permissions, childWatchdog, requestPermission = requestWatchdogPermission) {
+  const rules = permissions?.rules;
+  if (!rules || Object.keys(rules).length === 0)
     return;
+  const rawWatchdogConfig = childWatchdog ? JSON.stringify(childWatchdog) : undefined;
+  const timeoutMs = childWatchdog?.agentEndTimeoutMs ?? 30000;
   const onRuntimeEvent = dm.on;
   onRuntimeEvent("tool_call", async (event, ctx) => {
     const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
@@ -391,11 +346,6 @@ export function registerPermissionGate(dm, requestPermission = requestWatchdogPe
       return;
     if (decision === "deny")
       return { block: true, reason: `Blocked by dm-subagents permission rule: '${toolName}' is denied.` };
-    const rawWatchdogConfig = process.env[CHILD_WATCHDOG_CONFIG_ENV];
-    let timeoutMs = 30000;
-    try {
-      timeoutMs = decodeChildWatchdogConfig(rawWatchdogConfig)?.agentEndTimeoutMs ?? timeoutMs;
-    } catch {}
     if (ctx.signal?.aborted)
       return { block: true, reason: "Blocked by dm-subagents permission rule: Watchdog permission decision was cancelled." };
     let timeout;
@@ -408,7 +358,7 @@ export function registerPermissionGate(dm, requestPermission = requestWatchdogPe
           toolName,
           args: event.input ?? {},
           rawWatchdogConfig,
-          auditPath: process.env[PERMISSION_AUDIT_PATH_ENV],
+          auditPath: permissions.auditPath,
           ...ctx.signal ? { signal: ctx.signal } : {}
         }),
         new Promise((resolve) => {
@@ -456,260 +406,59 @@ function registerToolBudget(dm, budget) {
     return { block: true, reason: toolBudgetBlockedMessage(budget, toolName, toolCount) };
   });
 }
-export function registerSteeringInbox(dm, deps = {}) {
-  const steerInbox = process.env[SUBAGENT_STEER_INBOX_ENV]?.trim();
-  if (!steerInbox)
-    return;
-  const capabilityPath = process.env[SUBAGENT_STEER_CAPABILITY_ENV]?.trim();
-  const ackDir = process.env[SUBAGENT_STEER_ACK_DIR_ENV]?.trim();
-  const sendUserMessage = dm.sendUserMessage;
-  const childIndex = Number(process.env[SUBAGENT_CHILD_INDEX_ENV]);
-  const pending = new Map;
-  const queued = [];
-  let disposed = false;
-  let agentRunning = false;
-  let inTurn = false;
-  let awaitingSettlement = false;
-  let flushing = false;
-  let started = false;
-  let canSteer = typeof sendUserMessage === "function";
-  let watcher;
-  let interval;
-  let safetyInterval;
-  let settleFallback;
-  const legacySettleFallbackMs = deps.legacySettleFallbackMs ?? STEERING_LEGACY_SETTLE_FALLBACK_MS;
-  const acknowledge = (request, state, message, deliveryStatus) => {
-    if (!ackDir || !Number.isInteger(childIndex) || childIndex < 0)
-      return;
-    writeSteerAckAt(steerAckPathFromDir(ackDir, request.id), {
-      requestId: request.id,
-      index: childIndex,
-      ts: Date.now(),
-      state,
-      ...deliveryStatus ? { deliveryStatus } : {},
-      message
-    });
-  };
-  const publishCapability = () => {
-    if (!capabilityPath || !Number.isInteger(childIndex) || childIndex < 0)
-      return;
-    writeSteerCapabilityAt(capabilityPath, { index: childIndex, pid: process.pid, readyAt: Date.now(), supported: canSteer });
-  };
-  const flush = () => {
-    if (disposed || flushing)
-      return;
-    flushing = true;
-    try {
-      const requests = consumeSteerRequestsFromDir(steerInbox);
-      for (let index = 0;index < requests.length; index++) {
-        const request = requests[index];
-        if (!canSteer || typeof sendUserMessage !== "function") {
-          acknowledge(request, "failed", "Child DM session does not support sendUserMessage steering.");
-          continue;
-        }
-        const requestedMode = request.mode ?? "steer";
-        const autoCanUseIdle = requestedMode === "auto" && !agentRunning && !awaitingSettlement;
-        const delivery = requestedMode === "follow_up" || requestedMode === "auto" && (inTurn || awaitingSettlement) ? "followUp" : "steer";
-        const pendingFollowUps = [...pending.values()].reduce((count, entries) => count + entries.filter((entry) => entry.deliveryStatus === "queued").length, 0);
-        if (delivery === "followUp" && queued.length + pendingFollowUps >= MAX_STEER_QUEUE_SIZE) {
-          acknowledge(request, "failed", `Follow-up queue is full (${MAX_STEER_QUEUE_SIZE} messages).`);
-          continue;
-        }
-        const formatted = formatSteerMessage(request);
-        const entries = pending.get(formatted) ?? [];
-        entries.push({ request, deliveryStatus: delivery === "followUp" ? "queued" : "delivered" });
-        pending.set(formatted, entries);
-        try {
-          sendUserMessage(formatted, autoCanUseIdle ? undefined : { deliverAs: delivery });
-        } catch (error) {
-          entries.pop();
-          if (entries.length === 0)
-            pending.delete(formatted);
-          acknowledge(request, "failed", error instanceof Error ? error.message : String(error));
-          for (const retry of requests.slice(index + 1))
-            writeSteerRequestToDir(steerInbox, retry);
-          break;
-        }
+function registerStructuredOutputTool(dm, structured) {
+  const terminalState = structured.terminalState ??= { captured: false };
+  const required = structured.acceptanceReport === "required";
+  const parameters = createStructuredOutputToolParameters(structured.schema, { acceptanceReport: structured.acceptanceReport });
+  const registerTool = dm.registerTool;
+  registerTool({
+    name: "structured_output",
+    label: "Structured Output",
+    description: "Submit the required final structured output for this subagent step. This terminates the step.",
+    parameters,
+    async execute(_id, params) {
+      const validation = await validateStructuredOutputValue(structured.schema, params.value);
+      if (validation.status === "invalid") {
+        throw new Error(`Structured output validation failed: ${validation.message}`);
       }
-    } finally {
-      flushing = false;
-    }
-  };
-  const onInput = (event) => {
-    if (disposed || !event || typeof event !== "object")
-      return;
-    const input = event;
-    if (input.source !== "extension")
-      return;
-    const text = typeof input.text === "string" ? input.text : typeof input.content === "string" ? input.content : undefined;
-    if (!text)
-      return;
-    const entries = pending.get(text);
-    const entry = entries?.shift();
-    if (!entry)
-      return;
-    if (entries?.length === 0)
-      pending.delete(text);
-    if (entry.deliveryStatus === "queued") {
-      queued.push({ request: entry.request, ready: !inTurn });
-      acknowledge(entry.request, "queued", "DM queued the correlated follow-up input.", "queued");
-    } else {
-      acknowledge(entry.request, "delivered", "DM accepted the correlated steering input.", "delivered");
-    }
-    return;
-  };
-  const start = () => {
-    if (started || disposed)
-      return;
-    try {
-      fs.mkdirSync(steerInbox, { recursive: true });
-      publishCapability();
-    } catch {
-      return;
-    }
-    started = true;
-    const startPolling = () => {
-      if (interval || disposed)
-        return;
-      interval = (deps.timers?.setInterval ?? setInterval)(flush, 250);
-      interval.unref?.();
-    };
-    const startSafetyPolling = () => {
-      if (safetyInterval || disposed)
-        return;
-      safetyInterval = (deps.timers?.setInterval ?? setInterval)(flush, deps.safetyPollIntervalMs ?? STEERING_SAFETY_POLL_INTERVAL_MS);
-      safetyInterval.unref?.();
-    };
-    if (!shouldUseNativeFsWatch("child-steering-inbox", deps.platform)) {
-      startPolling();
-    } else {
-      try {
-        watcher = (deps.watch ?? fs.watch)(resolveWatchPath(steerInbox, deps.nativeRealpath), () => flush());
-        watcher.on("error", startPolling);
-        startSafetyPolling();
-      } catch {
-        watcher = undefined;
-        startPolling();
+      if (required && params.acceptanceReport === undefined) {
+        throw new Error(MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR);
       }
-    }
-  };
-  const activate = () => {
-    start();
-    flush();
-    return;
-  };
-  const clearSettleFallback = () => {
-    if (!settleFallback)
-      return;
-    clearTimeout(settleFallback);
-    settleFallback = undefined;
-  };
-  const markSettled = () => {
-    clearSettleFallback();
-    agentRunning = false;
-    inTurn = false;
-    awaitingSettlement = false;
-    return activate();
-  };
-  const armLegacySettleFallback = () => {
-    clearSettleFallback();
-    settleFallback = setTimeout(() => {
-      settleFallback = undefined;
-      if (disposed || !awaitingSettlement)
-        return;
-      agentRunning = false;
-      inTurn = false;
-      awaitingSettlement = false;
-      activate();
-    }, legacySettleFallbackMs);
-    settleFallback.unref?.();
-  };
-  const onRuntimeEvent = dm.on;
-  onRuntimeEvent("input", onInput);
-  onRuntimeEvent("session_start", () => start());
-  onRuntimeEvent("agent_start", () => {
-    clearSettleFallback();
-    agentRunning = true;
-    awaitingSettlement = false;
-    return activate();
-  });
-  onRuntimeEvent("agent_end", (event) => {
-    inTurn = false;
-    if (event?.willRetry === true) {
-      clearSettleFallback();
-      agentRunning = true;
-      awaitingSettlement = true;
-      return activate();
-    }
-    agentRunning = true;
-    awaitingSettlement = true;
-    armLegacySettleFallback();
-    return activate();
-  });
-  onRuntimeEvent("agent_settled", markSettled);
-  onRuntimeEvent("session_compact", () => {
-    const unresolved = [...pending.values()].flat();
-    pending.clear();
-    for (const entry of unresolved) {
-      try {
-        writeSteerRequestToDir(steerInbox, { ...entry.request, mode: "follow_up" });
-      } catch (error) {
-        acknowledge(entry.request, "failed", `Could not retry steering after compaction: ${error instanceof Error ? error.message : String(error)}`);
+      if (required && params.acceptanceReport !== undefined) {
+        const acceptanceValidation = validateAcceptanceReport(params.acceptanceReport, "acceptanceReport");
+        if (!acceptanceValidation.report) {
+          throw new Error(`Invalid structured output acceptance report: ${acceptanceValidation.errors.join("; ")}`);
+        }
       }
+      structured.capture(params.value, structured.acceptanceReport ? params.acceptanceReport : undefined);
+      terminalState.captured = true;
+      return {
+        content: [{ type: "text", text: "Structured output captured." }],
+        details: {},
+        terminate: true
+      };
     }
-    return activate();
-  });
-  onRuntimeEvent("turn_start", () => {
-    clearSettleFallback();
-    agentRunning = true;
-    awaitingSettlement = false;
-    inTurn = true;
-    const next = queued.findIndex((entry) => entry.ready);
-    if (next >= 0) {
-      const [entry] = queued.splice(next, 1);
-      if (entry)
-        acknowledge(entry.request, "delivered", "DM delivered the queued follow-up at a turn boundary.", "delivered");
-    }
-    return activate();
-  });
-  onRuntimeEvent("turn_end", () => {
-    inTurn = false;
-    for (const entry of queued)
-      entry.ready = true;
-    return activate();
-  });
-  for (const eventName of ["message_start", "message_update", "message_end", "tool_execution_start", "tool_execution_end"]) {
-    onRuntimeEvent(eventName, activate);
-  }
-  onRuntimeEvent("session_shutdown", () => {
-    for (const entry of queued)
-      acknowledge(entry.request, "failed", "Run ended before queued follow-up delivery.", "queued");
-    for (const entries of pending.values()) {
-      for (const entry of entries)
-        acknowledge(entry.request, "failed", "Run ended before DM confirmed steering input delivery.");
-    }
-    disposed = true;
-    clearSettleFallback();
-    try {
-      watcher?.close();
-    } catch {}
-    if (interval)
-      (deps.timers?.clearInterval ?? clearInterval)(interval);
-    if (safetyInterval)
-      (deps.timers?.clearInterval ?? clearInterval)(safetyInterval);
   });
 }
-export default function registerSubagentPromptRuntime(dm) {
-  registerRuntimeExtensionAcknowledgements(dm);
-  registerSteeringInbox(dm);
-  registerPermissionGate(dm);
-  registerToolBudget(dm, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV], { allowZero: process.env[TOOL_BUDGET_ZERO_AUTH_ENV] === "1" }));
-  registerChildWatchdog(dm);
-  const waitToolConfig = resolveWaitToolConfig();
-  const waitState = {
+export default function registerSubagentPromptRuntime(dm, config, drainObservation) {
+  if (!config)
+    return;
+  registerRuntimeExtensionAcknowledgements(dm, config.runtimeAcknowledgements);
+  registerPermissionGate(dm, config.permissions, config.childWatchdog);
+  registerToolBudget(dm, config.toolBudget);
+  if (config.structuredOutput && !config.structuredOutput.terminalState)
+    config.structuredOutput.terminalState = { captured: false };
+  registerChildWatchdog(dm, config.childWatchdog, config.watchdogStatus, config.structuredOutput?.terminalState);
+  const requestedWatchdogDiff = config.requiredTools?.includes(WATCHDOG_DIFF_TOOL_NAME);
+  const reviewerLaunchBaseline = requestedWatchdogDiff && config.cwd ? captureWatchdogDiffBaseline(config.cwd) : undefined;
+  if (requestedWatchdogDiff && typeof dm.registerTool === "function") {
+    dm.registerTool(createWatchdogDiffTool(reviewerLaunchBaseline, { workingTreeAtLaunch: true }));
+  }
+  const waitState = config.runtimeState ?? {
     baseCwd: "",
     currentSessionId: null,
     asyncJobs: new Map,
+    foregroundRuns: new Map,
     foregroundControls: new Map,
     lastForegroundControlId: null,
     cleanupTimers: new Map,
@@ -720,14 +469,16 @@ export default function registerSubagentPromptRuntime(dm) {
     watcherRestartTimer: null,
     resultFileCoalescer: { schedule: () => false, clear: () => {} }
   };
+  const nestedRootRunId = inheritedNestedRouteOf(config)?.rootRunId;
   if (typeof dm.registerTool === "function")
-    registerWaitTool(dm, waitState, waitToolConfig.enabled, undefined, waitToolConfig.defaultTimeoutMs);
+    registerWaitTool(dm, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs, { nestedRootRunId });
+  const supervisorMetadata = childSupervisorMetadata(config);
   let nativeSupervisorClientRegistered = false;
   const registerNativeSupervisorClientOnce = () => {
     if (nativeSupervisorClientRegistered)
       return;
     nativeSupervisorClientRegistered = true;
-    registerNativeSupervisorClient(dm);
+    registerNativeSupervisorClient(dm, supervisorMetadata);
   };
   const onRuntimeEvent = dm.on;
   onRuntimeEvent("session_start", (_event, ctx) => {
@@ -736,77 +487,73 @@ export default function registerSubagentPromptRuntime(dm) {
     registerNativeSupervisorClientOnce();
   });
   onRuntimeEvent("agent_start", () => {
-    const diagnostic = refreshChildToolDiagnostic(dm);
+    if (!config.requiredTools)
+      return;
+    const diagnostic = evaluateChildToolDiagnostic(config, dm.getAllTools().map((tool) => tool.name));
+    config.toolDiagnostic?.(diagnostic);
     if (diagnostic)
       throw new Error(formatChildToolDiagnostic(diagnostic));
   });
   onRuntimeEvent("agent_end", async (_event, ctx) => {
     if (ctx?.hasUI === true)
-      return;
-    await drainOutstandingWork({ state: waitState, events: dm.events });
-  });
-  const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
-  const structuredAcceptanceReportPath = process.env[STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV];
-  const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
-  if (structuredOutputPath && structuredSchemaPath) {
-    const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8"));
-    const parameters = createStructuredOutputToolParameters(schema, { acceptanceReport: Boolean(structuredAcceptanceReportPath) });
-    const registerTool = dm.registerTool;
-    registerTool({
-      name: "structured_output",
-      label: "Structured Output",
-      description: "Submit the required final structured output for this subagent step. This terminates the step.",
-      parameters,
-      async execute(_id, params) {
-        const validation = await validateStructuredOutputValue(schema, params.value);
-        if (validation.status === "invalid") {
-          throw new Error(`Structured output validation failed: ${validation.message}`);
-        }
-        fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
-        fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 384 });
-        if (structuredAcceptanceReportPath && params.acceptanceReport !== undefined) {
-          fs.writeFileSync(structuredAcceptanceReportPath, JSON.stringify(params.acceptanceReport), { mode: 384 });
-        }
-        return {
-          content: [{ type: "text", text: "Structured output captured." }],
-          details: { path: structuredOutputPath },
-          terminate: true
-        };
+      drainObservation?.deny();
+    if (drainObservation) {
+      try {
+        if (ctx?.sessionManager?.getSessionFile() !== waitState.currentSessionId)
+          drainObservation.deny();
+      } catch {
+        drainObservation.deny();
       }
-    });
-  }
-  onRuntimeEvent("before_provider_request", (event, ctx) => rewriteForkCacheProviderRequest(event, ctx));
+    }
+    config.holdFinalDrain?.(true);
+    try {
+      await drainOutstandingWork({ state: waitState, events: dm.events, nestedRootRunId, hasPendingSupervisorRequest: config.hasPendingSupervisorRequest }, drainObservation);
+    } finally {
+      config.holdFinalDrain?.(false);
+    }
+  });
+  if (config.structuredOutput)
+    registerStructuredOutputTool(dm, config.structuredOutput);
+  onRuntimeEvent("before_provider_request", (event, ctx) => rewriteForkCacheProviderRequest(event, ctx, config.forkCacheKey));
   onRuntimeEvent("context", (event, ctx) => {
     if (!event || typeof event !== "object" || !("messages" in event) || !Array.isArray(event.messages))
       return;
     const messages = stripParentOnlySubagentMessages(event.messages, {
-      sanitizeToolIds: !COMPOSITE_TOOL_ID_APIS.has(ctx?.model?.api ?? "")
+      sanitizeToolIds: !COMPOSITE_TOOL_ID_APIS.has(ctx?.model?.api ?? ""),
+      preserveFanoutToolHistory: config.fanoutChild
     });
     if (messages === event.messages)
       return;
     return { messages };
   });
+  const routingName = config.intercomSessionName;
+  let intercomIdClaimed = false;
+  if (routingName) {
+    dm.events.on(INTERCOM_SESSION_IDENTITY_EVENT, (request) => {
+      if (!request || typeof request !== "object" || !("version" in request) || request.version !== 1 || !("claim" in request) || typeof request.claim !== "function")
+        return;
+      request.claim(routingName);
+      intercomIdClaimed = true;
+    });
+  }
   onRuntimeEvent("before_agent_start", async (event) => {
     if (!event || typeof event !== "object" || !("systemPrompt" in event) || typeof event.systemPrompt !== "string")
       return;
     registerNativeSupervisorClientOnce();
-    const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
-    const displaySessionName = process.env[SUBAGENT_SESSION_NAME_ENV]?.trim();
-    const childSessionName = intercomSessionName || displaySessionName;
+    const childSessionName = intercomIdClaimed ? config.sessionName || routingName : routingName || config.sessionName;
     if (childSessionName && typeof dm.setSessionName === "function") {
       dm.setSessionName(childSessionName);
     }
-    const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
-    const inheritGlobalContext = readBooleanEnv(SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV);
-    const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
-    const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
+    const { inheritProjectContext, inheritGlobalContext, inheritSkills } = config;
+    const fanoutChild = config.fanoutChild;
     let rewritten = event.systemPrompt;
-    if (inheritProjectContext !== undefined || inheritGlobalContext !== undefined || inheritSkills !== undefined || fanoutChild !== undefined) {
+    if (inheritProjectContext !== undefined || inheritGlobalContext !== undefined || inheritSkills !== undefined || fanoutChild) {
       rewritten = rewriteSubagentPrompt(event.systemPrompt, {
         inheritProjectContext: inheritProjectContext ?? true,
         inheritGlobalContext: inheritGlobalContext ?? true,
         inheritSkills: inheritSkills ?? true,
-        fanoutChild: fanoutChild === true
+        fanoutChild,
+        structuredOutput: Boolean(config.structuredOutput)
       });
     }
     if (rewritten === event.systemPrompt)