@pensar/apex 2.5.0 → 2.6.1-canary.025b1ecf

package/src/core/agents/offSecAgent/offensiveSecurityAgent.ts

@@ -0,0 +1,1610 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { SpanStatusCode } from "@opentelemetry/api";
+import type {
+  ModelMessage,
+  StopCondition,
+  StreamTextResult,
+  TextStreamPart,
+  ToolSet,
+} from "ai";
+import { hasToolCall } from "ai";
+import { normalizeStepUsage, streamResponse } from "../../ai";
+import { AgentEventBus, type StreamIdContext } from "../../eventBus";
+import { newMessageId, newPartId } from "../../id/id";
+import { createLogger } from "../../logger/structured";
+import {
+  getApexTracer,
+  registerActiveRootSpan,
+  shouldRecordAiPayloads,
+  unregisterActiveRootSpan,
+  withSubagentSessionBaggage,
+} from "../../observability";
+import type { ApprovalGate } from "../../operator";
+import { ApprovalDeniedError } from "../../operator";
+import type { RunContextRecorder } from "../../runtime/runContext";
+import { create as createSession, type SessionInfo } from "../../session";
+import { scopedLogger } from "../../util/lazyLogger";
+import {
+  createInterruptedStepFinalizer,
+  type FinalizeInterruptedStepInput,
+} from "./interruptedStepFinalization";
+import { AgentMessageWriter } from "./messagePersistence";
+import { buildBaseSystemPrompt, buildSessionWorkspaceSection } from "./prompt";
+import { wrapRecordedTools } from "./recordedTools";
+import {
+  buildBundledAssetsSection,
+  buildRuntimeContextSection,
+  peekSettledRuntimeFacts,
+  probeRuntimeFacts,
+  type RuntimeExecutionFacts,
+  resolveCommandPlatform,
+  UNKNOWN_FACTS,
+} from "./runtimeContext";
+import { responseArgBytes, StreamDiagnostics } from "./streamDiagnostics";
+import { inProcessSubagentSpawner } from "./subagentSpawner";
+import { ToolLifecycleTracker } from "./toolLifecycle";
+import {
+  ASK_USER_QUESTIONS_TOOL_NAME,
+  CallbackListenerRegistry,
+  createResponseTool,
+  createToolsForNames,
+  EMAIL_TOOL_NAMES_ACTIVE,
+  FAST_STRIKE_EXCLUDED_TOOL_NAMES,
+  listToolRegistryNames,
+  PerCommandShell,
+  PLAN_MODE_TOOL_NAMES,
+  PlaywrightMcpSession,
+  RESPONSE_TOOL_NAME,
+  resolveBrowserHeaderPolicy,
+  SEND_EMAIL_TOOL_NAME,
+  SMS_TOOL_NAMES_ACTIVE,
+  sessionHasSmsPasswordless,
+  WORKSPACE_TOOL_NAMES,
+  WORKSPACE_WRITE_TOOL_NAMES,
+} from "./tools";
+import type { ToolContext } from "./tools/types";
+import { StepTraceWriter } from "./trace";
+import type {
+  AgentMode,
+  CreateAgentInput,
+  OffensiveSecurityAgentInput,
+  StreamIdFactory,
+} from "./types";
+
+function isGenericAbortError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.name === "AbortError" &&
+    error.cause === undefined &&
+    /^(?:Aborted|Agent aborted by user|(?:This|The) operation was aborted|The user aborted a request)\.?$/.test(
+      error.message,
+    )
+  );
+}
+
+function agentAbortReason(signal: AbortSignal): unknown {
+  const reason: unknown = signal.reason;
+  return reason === undefined || isGenericAbortError(reason)
+    ? new DOMException("Agent aborted by user", "AbortError")
+    : reason;
+}
+
+const log = scopedLogger(() => createLogger("approval-gate"));
+
+// Opt-in `response` tool lifecycle tracer (RESPONSE_DEBUG=1) for the empty-`{}` / "Tool call did not complete" loop on threat-model sub-agents.
+const RESPONSE_DEBUG =
+  process.env.RESPONSE_DEBUG === "1" || process.env.RESPONSE_DEBUG === "true";
+const rlog = scopedLogger(() => createLogger("response-debug"));
+
+const WORKSPACE_TOOL_NAME_SET = new Set<string>(WORKSPACE_TOOL_NAMES);
+const WORKSPACE_WRITE_TOOL_NAME_SET = new Set<string>(
+  WORKSPACE_WRITE_TOOL_NAMES,
+);
+
+// Tools whose presence means backend-probed execution facts can change what
+// the agent should attempt: command execution, native file tools, and PoC
+// runs. Agents holding none of these skip the runtime probe entirely.
+const RUNTIME_CAPABLE_TOOL_NAMES = new Set<string>([
+  "execute_command",
+  "read_file",
+  "list_files",
+  "glob",
+  "grep",
+  "create_file",
+  "update_file",
+  "delete_file",
+  "apply_patch",
+  "document_vulnerability",
+]);
+
+const WORKSPACE_TARGET_RE = /\b(?:console|workspace)\b/i;
+const WORKSPACE_NOUN_RE =
+  /\b(?:domains?|apps?|applications?|endpoints?|threat\s+models?|attack\s+surfaces?)\b/i;
+const WORKSPACE_READ_REQUEST_RE =
+  /(?:\b(?:list|show|find|search|get)\s+(?:(?:me|a|an|the|my|our|all|any|list|of|for|in|within|registered|existing|available|console|workspace|which)\s+){0,8}(?:domains?|apps?|applications?|endpoints?)\b|\b(?:what|which)\s+(?:(?:of|a|an|the|my|our|all|any|are|is|do|does|we|i|have|has|there|registered|existing|available|console|workspace)\s+){0,8}(?:domains?|apps?|applications?|endpoints?)\b)/i;
+const WORKSPACE_WRITE_ACTION = String.raw`(?:add|create|register|import|update|edit|change|set|correct|repair|link|unlink|rename|break\s+down)`;
+const WORKSPACE_EXPLICIT_WRITE_REQUEST_RE = new RegExp(
+  String.raw`(?:^\s*|[.?!;\n]\s*|\b(?:please|kindly)\s+|\b(?:can|could|would|will)\s+you\s+|\b(?:i|we)\s+(?:want|need)\s+(?:you\s+)?to\s+|\bi(?:['’]d| would)\s+like\s+(?:you\s+)?to\s+|\blet['’]s\s+|\bgo\s+ahead\s+and\s+)${WORKSPACE_WRITE_ACTION}\b`,
+  "i",
+);
+const WORKSPACE_NEGATED_WRITE_REQUEST_RE = new RegExp(
+  String.raw`\b(?:do\s+not|don't|never|avoid)\b[^.?!;\n]{0,40}\b${WORKSPACE_WRITE_ACTION}\b`,
+  "i",
+);
+const WORKSPACE_CLAUSE_BOUNDARY_RE = new RegExp(
+  String.raw`(?:[.!?;]+(?=\s|$)\s*|\n+|\s+(?:but|however)\s+|\s+and\s+(?=(?:(?:do\s+not|don't|never|avoid)\s+)?${WORKSPACE_WRITE_ACTION}\b))`,
+  "i",
+);
+// Sentence delimiters only (never splits `example.com`), so a leading
+// capability question can be scoped to the whole sentence before the
+// clause-level `and`/`but` split runs.
+const WORKSPACE_SENTENCE_BOUNDARY_RE = /(?:[.!?;]+(?=\s|$)\s*|\n+)/;
+// Capability/permission questions ("Can I … and create …", "How do I …")
+// stay read-only: the interrogative governs every coordinated clause, so the
+// clause split must not let a trailing bare write verb pass as an imperative.
+// Requests aimed at the agent ("Can you …", "Please …", "I'd like to …") are
+// not questions and are handled by WORKSPACE_EXPLICIT_WRITE_REQUEST_RE.
+const WORKSPACE_CAPABILITY_QUESTION_RE =
+  /^\s*(?:(?:so|and|also|then|ok|okay|well|hey|hi|actually|but)[,\s]+)*(?:is\s+it\s+possible\b|what\s+if\b|how\s+(?:do|can|could|should|would|shall|might)\s+(?:i|we)\b|(?:can|could|should|would|may|will|do|does|did|am|are|is|shall|have|has)\s+(?:i|we)\b)/i;
+const WORKSPACE_CREATE_REQUEST_RE =
+  /\b(?:add|create|register|import)\s+(?:(?:the|this|that|a|an|my|our|existing|new|current|connected|authenticated|console|workspace|attached|provided)\s+){0,4}(?:domains?|apps?|applications?|endpoints?|threat\s+models?|attack\s+surfaces?)\b/i;
+const WORKSPACE_DOMAIN_HOST_WRITE_RE =
+  /\b(?:add|create|register|import|link)\s+(?:https?:\/\/)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}(?::\d+)?(?:\/\S*)?\s+(?:to|in|under)\s+(?:(?:the|my|our|connected|authenticated)\s+)?(?:console|workspace)\b/i;
+const WORKSPACE_APP_FIELD_UPDATE_RE =
+  /\b(?:update|edit|change|set|correct|repair)\s+(?:(?:the|this|that|my|our|existing|current|connected|authenticated|console|workspace)\s+){0,4}(?:apps?|applications?)(?:['’]s)?\s+(?:name|description|type|framework|domain|disallowed\s+actions?)\s+(?:(?:to|as|with|from)\b|[:=])/i;
+const WORKSPACE_ENDPOINT_FIELD_UPDATE_RE =
+  /\b(?:update|edit|change|set|correct|repair)\s+(?:(?:the|this|that|my|our|existing|current|connected|authenticated|console|workspace)\s+){0,4}endpoints?(?:['’]s)?\s+(?:path|route|url|description|type|transport|location|source(?:\s+location)?|start\s+line|end\s+line|line\s+numbers?|objectives?|authentication(?:\s+requirements?)?|business\s+logic|threat\s+model|parent\s+application)\s+(?:(?:to|as|with|from)\b|[:=])/i;
+const WORKSPACE_LINK_CLAUSE_GAP = String.raw`[^.?!;\n]{0,80}`;
+const WORKSPACE_APP_RESOURCE = String.raw`\b(?:apps?|applications?)\b`;
+const WORKSPACE_DOMAIN_RESOURCE = String.raw`\b(?:domains?|(?:https?:\/\/)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,})\b`;
+const WORKSPACE_APP_DOMAIN_LINK_RE = new RegExp(
+  String.raw`(?:\blink\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_APP_RESOURCE}${WORKSPACE_LINK_CLAUSE_GAP}\bto\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_DOMAIN_RESOURCE}|\blink\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_DOMAIN_RESOURCE}${WORKSPACE_LINK_CLAUSE_GAP}\bto\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_APP_RESOURCE}|\bunlink\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_APP_RESOURCE}${WORKSPACE_LINK_CLAUSE_GAP}\bfrom\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_DOMAIN_RESOURCE}|\bunlink\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_DOMAIN_RESOURCE}${WORKSPACE_LINK_CLAUSE_GAP}\bfrom\b${WORKSPACE_LINK_CLAUSE_GAP}${WORKSPACE_APP_RESOURCE})`,
+  "i",
+);
+const WORKSPACE_APP_RENAME_RE =
+  /\brename\s+(?:(?:the|this|that|my|our|existing|current|connected|authenticated|console|workspace)\s+){0,4}(?:apps?|applications?)\b[^.?!;\n]{0,60}\b(?:to|as)\b/i;
+const WORKSPACE_BREAK_DOWN_IMPORT_RE =
+  /\bbreak\s+down\b[^.?!;\n]{0,100}\b(?:threat\s+models?|attack\s+surfaces?)\b[^.?!;\n]{0,100}\b(?:into|as)\b[^.?!;\n]{0,40}\b(?:apps?|applications?|endpoints?)\b/i;
+
+function hasExplicitWorkspaceWriteRequest(
+  prompt: string,
+  targetsWorkspace: boolean,
+): boolean {
+  return prompt.split(WORKSPACE_SENTENCE_BOUNDARY_RE).some((sentence) => {
+    // A capability question governs its whole sentence, so its clauses stay
+    // read-only even when `and`/`but` splits a bare write verb off the front.
+    if (WORKSPACE_CAPABILITY_QUESTION_RE.test(sentence)) return false;
+
+    return sentence.split(WORKSPACE_CLAUSE_BOUNDARY_RE).some((clause) => {
+      if (
+        !WORKSPACE_EXPLICIT_WRITE_REQUEST_RE.test(clause) ||
+        WORKSPACE_NEGATED_WRITE_REQUEST_RE.test(clause)
+      ) {
+        return false;
+      }
+
+      return (
+        WORKSPACE_DOMAIN_HOST_WRITE_RE.test(clause) ||
+        (targetsWorkspace &&
+          (WORKSPACE_CREATE_REQUEST_RE.test(clause) ||
+            WORKSPACE_APP_FIELD_UPDATE_RE.test(clause) ||
+            WORKSPACE_ENDPOINT_FIELD_UPDATE_RE.test(clause) ||
+            WORKSPACE_APP_DOMAIN_LINK_RE.test(clause) ||
+            WORKSPACE_APP_RENAME_RE.test(clause) ||
+            WORKSPACE_BREAK_DOWN_IMPORT_RE.test(clause)))
+      );
+    });
+  });
+}
+
+// ponytail: current-message opt-in avoids persistent workspace capability state.
+//
+// Read (`list_*`) and write (`create_*` / `update_*`) tools are gated
+// separately: recon phrasing (find/search/show/list a domain, app, or endpoint on the "console"/
+// "workspace") is common in ordinary Operator pentests, so it must never
+// expose mutation tools. Write tools require an explicit mutation request —
+// a write verb, a "break down …" import, or a direct tool-name mention.
+export function filterWorkspaceToolsForRun(
+  activeTools: string[],
+  prompt: string,
+  hasInteractiveApprovalGate: boolean,
+): string[] {
+  const gated =
+    hasInteractiveApprovalGate && !prompt.trimStart().startsWith("<skill ");
+
+  if (!gated) {
+    return activeTools.filter((name) => !WORKSPACE_TOOL_NAME_SET.has(name));
+  }
+
+  const targetsWorkspace =
+    WORKSPACE_TARGET_RE.test(prompt) && WORKSPACE_NOUN_RE.test(prompt);
+
+  const writeRequested =
+    WORKSPACE_WRITE_TOOL_NAMES.some((name) => prompt.includes(name)) ||
+    hasExplicitWorkspaceWriteRequest(prompt, targetsWorkspace);
+
+  const readRequested =
+    writeRequested ||
+    WORKSPACE_TOOL_NAMES.some((name) => prompt.includes(name)) ||
+    (targetsWorkspace && WORKSPACE_READ_REQUEST_RE.test(prompt));
+
+  return activeTools.filter((name) => {
+    if (WORKSPACE_WRITE_TOOL_NAME_SET.has(name)) return writeRequested;
+    if (WORKSPACE_TOOL_NAME_SET.has(name)) return readRequested;
+    return true;
+  });
+}
+
+/**
+ * General-purpose offensive security agent harness.
+ *
+ * The agent **owns tool creation** — all available tools are built from
+ * the session context, and specific agents select which ones to activate
+ * via the `activeTools` array (passed through to the AI SDK).
+ *
+ * The stream is created lazily on first consumption (see {@link streamReady}
+ * and {@link streamResult}) — after backend-probed runtime facts settle —
+ * so the AI SDK telemetry nests under this agent's span — no separate `.run()`.
+ *
+ * @typeParam TResult - The type returned by {@link consume}. When the input
+ *   includes a `resolveResult` function, `consume()` awaits it after the
+ *   stream finishes and returns the value. Defaults to `void`.
+ *
+ * ## Consumption (pick one — stream is single-read)
+ *
+ * **1. Emit to EventBus via `.consume()` → `TResult`**
+ * ```ts
+ * const bus = new AgentEventBus();
+ * bus.on("text-delta", (e) => process.stdout.write(e.text));
+ * bus.on("tool-call-complete", (e) => console.log(`→ ${e.toolName}`));
+ * const agent = new OffensiveSecurityAgent({ ..., eventBus: bus });
+ * const result = await agent.consume();
+ * ```
+ *
+ * **2. `for await` directly on the agent**
+ * ```ts
+ * for await (const chunk of agent) { ... }
+ * ```
+ *
+ * **3. Raw stream access**
+ * ```ts
+ * for await (const chunk of agent.fullStream) { ... }
+ * ```
+ */
+export class OffensiveSecurityAgent<TResult = void> {
+  /** The real SDK stream result — created exactly once, with backend-probed facts via {@link streamReady} or settled-or-unknown facts via the sync escape hatch. */
+  private _streamResult: StreamTextResult<ToolSet, never> | null = null;
+
+  /** Composes the final system prompt, writes the trace init record, and calls `streamResponse`. Invoked at most once; both creation paths guard on `_streamResult`. */
+  private readonly createStream: (
+    facts: RuntimeExecutionFacts | null,
+  ) => StreamTextResult<ToolSet, never>;
+
+  /** Lazy runtime probe, then `createStream`; memoized by {@link streamInit}. */
+  private readonly initializeStreamOnce: () => Promise<void>;
+
+  /** Memoized {@link streamReady} promise; initialization runs at most once. */
+  private streamInit: Promise<void> | null = null;
+
+  /** True when this agent's tool selection can use backend-probed execution facts. */
+  private readonly probesRuntime: boolean;
+
+  /** The tool context whose runtime scope keys fact discovery and the sync fallback. */
+  private readonly toolCtx: ToolContext;
+
+  /** The event bus for this agent's streaming output. */
+  public readonly eventBus: AgentEventBus;
+
+  private readonly resolveResult?: (
+    streamResult: StreamTextResult<ToolSet, never>,
+  ) => TResult | Promise<TResult>;
+
+  /** The structured result captured by the `response` tool, or `null` until it fires. */
+  private _capturedResponse: TResult | null = null;
+
+  /** Set synchronously when `response` fires, ahead of any async `resolveResult`, to distinguish a clean finish from an abort. */
+  private _responseToolFired = false;
+
+  /** Raw structured result submitted to the response tool, retained for root-span output. */
+  private _responseToolResult: unknown;
+
+  /** Resolves the instant `response` captures the result, so {@link consume} can return early and drain in the background. */
+  private _resolveResponseCaptured!: (result: TResult) => void;
+  private _rejectResponseCaptured!: (err: unknown) => void;
+  public readonly responseCaptured: Promise<TResult> = new Promise(
+    (resolve, reject) => {
+      this._resolveResponseCaptured = resolve;
+      this._rejectResponseCaptured = reject;
+    },
+  );
+
+  /** Rejects when the background drain errors, so a custom resolver racing `streamResult.response` isn't blocked by a wedged stream. */
+  private _drainRejection: Promise<never> = new Promise<never>(() => {});
+
+  /** Settles when the background drain (including its synthetic-close finally) has fully finished. */
+  public drained: Promise<void> = Promise.resolve();
+
+  /** Identifier for this agent when it is running as a subagent. */
+  private readonly subagentId?: string;
+
+  /** Display label for span name / `gen_ai.agent.name`; the id stays the join key. */
+  private readonly subagentName?: string;
+  /** Operating mode (tools surface); used for run-span attribution. */
+  private readonly agentMode: AgentMode;
+  /** The current open assistant message id (`msg_…`); minted on `start-step` in {@link consume}, `null` between steps. */
+  private currentMessageId: string | null = null;
+
+  /** Per-run stream counters for deterministic id derivation via {@link streamIdFactory}. */
+  private streamStepIndex = -1;
+
+  private streamTextPartIndex = 0;
+
+  /** Per-command executor for local-mode command execution; disposed on consume() completion. */
+  private readonly commandShell?: PerCommandShell;
+
+  /**
+   * This agent's Playwright MCP browser session. Either constructed fresh
+   * by this agent (when no `browserSession` was passed in) or supplied by
+   * the caller (e.g. `spawn_pentest_agent` constructs a fresh, isolated
+   * session for each worker, seeds it with a snapshot of the orchestrator's
+   * cookies + localStorage, and hands the seeded session in here so this
+   * agent's browser tools operate against an authenticated-but-isolated
+   * Chromium).
+   *
+   * Exposed publicly so spawn tools can read this agent's session (e.g.
+   * the pentest orchestrator's `browserSession` is what `spawn_pentest_agent`
+   * snapshots when it builds the worker's seeded clone). The session
+   * object is NOT shared between agents at runtime — each agent gets its
+   * own isolated Chromium so a sub-agent can't clobber its parent's DOM,
+   * cookies, or navigation state.
+   *
+   * Only populated for non-sandbox (local MCP) mode. In sandbox mode,
+   * browser state is already shared via the sandbox's per-sandbox
+   * Playwright user-data directory, so no host-side session object is
+   * needed.
+   */
+  public readonly browserSession?: PlaywrightMcpSession;
+
+  /**
+   * True when this agent constructed its own {@link browserSession} (no
+   * `browserSession` was passed in). Only the owner disconnects it on
+   * `consume()` completion — an inherited session is torn down by whoever
+   * created it (e.g. `spawn_pentest_agent` for worker clones), so we must
+   * never disconnect a session we don't own.
+   */
+  private readonly ownsBrowserSession: boolean;
+
+  /** Guards against double force-kill across the drain-finally and result-capture paths. */
+  private browserDisconnected = false;
+  private shellDisposed = false;
+
+  /** Listeners started by this agent's callback helper tools; drained on finalization. */
+  private readonly callbackListeners = new CallbackListenerRegistry();
+  // Cached dispose barrier — repeat disposeOwnedShell() calls return the
+  // same settlement wait instead of a fire-and-forget.
+  private shellDisposeBarrier: Promise<void> | null = null;
+
+  private readonly abortSignal?: AbortSignal;
+
+  private readonly streamIdFactory?: StreamIdFactory;
+
+  /** Recorded-run durable context authority; flushed (and failing) in finalizeRun. */
+  private readonly contextRecorder?: RunContextRecorder;
+
+  /** The user-facing prompt passed to the model. */
+  public readonly userPrompt: string;
+
+  /** The session this agent is operating within. */
+  private readonly _session: SessionInfo;
+
+  /** Agent-local message persistence (debounce + serialized writes). */
+  private readonly writer!: AgentMessageWriter;
+
+  /** Closes an interrupted step: synthetic results, reconstruction, write. */
+  private readonly finalizeInterruptedStep!: (
+    input: FinalizeInterruptedStepInput,
+  ) => Promise<void>;
+
+  private messagesPath: string | null = null;
+
+  /** Serializes agent-owned messages.json writes in enqueue order. */
+  /**
+   * Async factory that creates a session when one is not provided,
+   * then constructs the agent. Use this instead of `new` when you
+   * want the agent to own session lifecycle.
+   *
+   * Pass an existing `session` to reuse one (console integration,
+   * subagent spawning, etc.).
+   */
+  static async create<TResult = void>(
+    input: CreateAgentInput<TResult>,
+  ): Promise<OffensiveSecurityAgent<TResult>> {
+    let session = input.session;
+    if (!session) {
+      session = await createSession({
+        targets: input.target ? [input.target] : [],
+        config: input.sessionConfig,
+        model: input.model,
+        authConfig: input.authConfig,
+        userMessage: input.prompt,
+        onNameGenerated: input.onNameGenerated,
+      });
+    }
+    return new OffensiveSecurityAgent({ ...input, session });
+  }
+
+  /** The session this agent is operating within. */
+  get session(): SessionInfo {
+    return this._session;
+  }
+
+  /** This agent's identity on the event bus (subagent's session id, or the root session's id). */
+  private get busSessionId(): string {
+    return this.subagentId ?? this._session.id;
+  }
+
+  constructor(input: OffensiveSecurityAgentInput<TResult>) {
+    this._session = input.session;
+    this.subagentId = input.subagentId;
+    this.subagentName = input.subagentName;
+    this.agentMode = input.mode ?? "default";
+    this.abortSignal = input.abortSignal;
+    this.streamIdFactory = input.streamIdFactory;
+    this.contextRecorder = input.contextRecorder;
+    this.userPrompt = input.prompt;
+    this.eventBus = input.eventBus ?? new AgentEventBus();
+
+    // -- Resolve agent working directory ----------------------------------------
+    // Explicit input wins over session config; command cwd and file-tool
+    // scoping (fileWorkspaceRoot) are independent and resolved separately.
+    const agentCwd =
+      input.agentCwd ??
+      input.session.config?.agentCwd ??
+      input.session.rootPath;
+    // Same precedence for the file-tool workspace: an explicit root (e.g. a
+    // child agent's helper directory) wins over the session's remote root.
+    const fileWorkspaceRoot =
+      input.fileWorkspaceRoot ?? input.session.config?.remoteFileWorkspaceRoot;
+
+    // -- Per-command executor (local mode only) -------------------------------
+    // Shell survives command cancellation; only disposed in consume() after the
+    // stream ends, or when the agent is fully killed.
+    if (!input.sandbox) {
+      this.commandShell = new PerCommandShell({
+        cwd: agentCwd,
+        env: input.environmentVariables,
+      });
+      if (input.commandCancelHandle) {
+        const shell = this.commandShell;
+        input.commandCancelHandle.cancel = () => shell.cancelCurrentCommand();
+      }
+    }
+
+    // -- Browser session (local MCP mode only) -------------------------------
+    // Either inherit from the parent agent (e.g. pentest orchestrator handing
+    // its authenticated context down via spawn_pentest_agent) or construct a
+    // fresh one. The session itself does not spawn the MCP child / Chromium
+    // until the first browser tool call, so eager construction is cheap even
+    // for agents that never use browser tools. Sandbox-mode agents already
+    // share browser state via the sandbox's per-sandbox Playwright user-data
+    // dir, so they don't need a session object on the host.
+    if (!input.sandbox) {
+      this.ownsBrowserSession = !input.browserSession;
+      this.browserSession =
+        input.browserSession ??
+        new PlaywrightMcpSession({
+          headerPolicy: resolveBrowserHeaderPolicy(input.session, input.target),
+          display: input.display,
+          engine: input.browserEngine,
+        });
+      // Owned sessions aren't wired through createBrowserTools' abort path
+      // (existingSession skips that listener). Disconnect on abort so timeout/
+      // pause reaps Camoufox even when consume()'s drain is still unwinding.
+      if (this.ownsBrowserSession && this.abortSignal) {
+        const onAbort = () => {
+          void this.disconnectOwnedBrowser();
+        };
+        if (this.abortSignal.aborted) onAbort();
+        else
+          this.abortSignal.addEventListener("abort", onAbort, { once: true });
+      }
+    } else {
+      this.ownsBrowserSession = false;
+    }
+
+    // -- Step trace (trace.jsonl) ---------------------------------------------
+    // Created before tools so the checkpoint_state tool can reference it.
+    const messagesDir =
+      input.messagesDir ??
+      (input.subagentId
+        ? join(input.session.rootPath, "subagents", input.subagentId)
+        : input.session.rootPath);
+    const tracePath = input.subagentId
+      ? join(
+          input.session.rootPath,
+          "subagents",
+          `${input.subagentId}.trace.jsonl`,
+        )
+      : join(messagesDir, "trace.jsonl");
+    const traceWriter = new StepTraceWriter({
+      tracePath,
+      agentId: input.subagentId ?? null,
+      eventBus: this.eventBus,
+    });
+
+    // -- Task directory (per-agent tasks, opt-in via taskDriven config) -------
+    const taskDriven = input.session.config?.taskDriven ?? false;
+    const tasksDir =
+      input.tasksDir ??
+      (taskDriven
+        ? input.subagentId
+          ? join(
+              input.session.rootPath,
+              "subagents",
+              `${input.subagentId}-tasks`,
+            )
+          : join(input.session.rootPath, "tasks")
+        : undefined);
+
+    // -- Tools ----------------------------------------------------------------
+    const credentialManager =
+      input.credentialManager ?? input.session.credentialManager;
+
+    const toolCtx = {
+      ...(input.attackSurfaceArtifactsPath
+        ? { attackSurfaceArtifactsPath: input.attackSurfaceArtifactsPath }
+        : {}),
+      session: input.session,
+      agentCwd,
+      fileWorkspaceRoot,
+      target: input.target,
+      grpc: input.grpc,
+      systemScope: input.systemScope,
+      abortSignal: input.abortSignal,
+      model: input.model,
+      authConfig: input.authConfig,
+      eventBus: this.eventBus,
+      onStepFinish: input.forwardUsageCallbacksToSpawnedAgents
+        ? input.onStepFinish
+        : undefined,
+      onCacheMetrics: input.forwardUsageCallbacksToSpawnedAgents
+        ? input.onCacheMetrics
+        : undefined,
+      sandbox: input.sandbox,
+      backends: input.backends,
+      findingsRegistry: input.findingsRegistry,
+      attackSurfaceRegistry: input.attackSurfaceRegistry,
+      credentialManager,
+      secretValues: input.secretValues,
+      environmentVariables: input.environmentVariables,
+      commandShell: this.commandShell,
+      skillsRegistry: input.skillsRegistry,
+      promptInjectionLibrary: input.promptInjectionLibrary,
+      promptInjectionLibrarySource:
+        input.promptInjectionLibrarySource ??
+        input.session.config?.promptInjectionLibrarySource,
+      traceWriter,
+      tasksDir,
+      enableThinking: input.enableThinking,
+      thinkingEffort: input.thinkingEffort,
+      openAIReasoningEffort: input.openAIReasoningEffort,
+      surfaceIntegrationEnabled: input.surfaceIntegrationEnabled,
+      projectThreatModel: input.projectThreatModel,
+      planSubagentId: input.planSubagentId,
+      subagentId: input.subagentId,
+      browserSession: this.browserSession,
+      // Propagate this agent's display so spawned workers run on the SAME
+      // virtual desktop (their browsers belong to the same endpoint's stream),
+      // rather than falling back to the process-wide DISPLAY (:0).
+      display: input.display,
+      // Spawn seam + durable hooks inherited by any sub-agent this agent spawns.
+      // Resolve the default once here so every tool sees a guaranteed spawner.
+      subagentSpawner: input.subagentSpawner ?? inProcessSubagentSpawner,
+      // Owned-listener cleanup seam: drained by finalizeRun/abortAndDrain.
+      callbackListeners: this.callbackListeners,
+      smsInbox: input.smsInbox,
+      emailAdapterFor: input.emailAdapterFor,
+      languageModelMiddleware: input.languageModelMiddleware,
+      usageRecorder: input.usageRecorder,
+      streamIdFactory: input.streamIdFactory,
+    };
+
+    // -- Effective tool selection (names only — factories run below) ---------
+    // Resolved BEFORE construction so inactive factories never run. Fast
+    // strike enumerates the live registry (conditional availability plus
+    // any extra tools) exactly as Object.keys on the merged map did.
+    const hasEmail =
+      (input.session.config?.emailIntegration?.inboxes?.length ?? 0) > 0;
+    const hasSmtp = !!input.session.config?.smtpConfig;
+    const emailToolSet = new Set<string>(EMAIL_TOOL_NAMES_ACTIVE);
+    const smsToolSet = new Set<string>(SMS_TOOL_NAMES_ACTIVE);
+    const hasSms = sessionHasSmsPasswordless(input.session);
+    const passesEmailSmsGates = (t: string): boolean => {
+      if (smsToolSet.has(t)) return hasSms;
+      if (!emailToolSet.has(t)) return true;
+      if (t === SEND_EMAIL_TOOL_NAME) return hasSmtp;
+      return hasEmail;
+    };
+
+    let activeTools = (input.activeTools as string[]).filter(
+      passesEmailSmsGates,
+    );
+    if (input.mode === "plan") {
+      const planSet = new Set<string>(PLAN_MODE_TOOL_NAMES);
+      activeTools = activeTools.filter((t) => planSet.has(t));
+    } else if (input.mode === "fast-strike") {
+      const excluded = new Set<string>(FAST_STRIKE_EXCLUDED_TOOL_NAMES);
+      // Mirror Object.keys({...builtins, ...extras}): an own extra replaces
+      // the builtin's value but keeps its insertion position; new extras
+      // append. Object.keys already yields own enumerable keys only.
+      const mergedNames = input.extraTools
+        ? Object.keys({
+            ...Object.fromEntries(
+              listToolRegistryNames(toolCtx).map((n) => [n, null]),
+            ),
+            ...input.extraTools,
+          })
+        : listToolRegistryNames(toolCtx);
+      activeTools = mergedNames.filter((t) => {
+        if (excluded.has(t)) return false;
+        return passesEmailSmsGates(t);
+      });
+      // Baseline enumerated Object.keys(tools) AFTER response injection, so
+      // fast-strike + responseSchema activates the injected response tool
+      // even when the input list omits it. Default mode stays caller-explicit.
+      if (input.responseSchema && !activeTools.includes(RESPONSE_TOOL_NAME)) {
+        activeTools = [...activeTools, RESPONSE_TOOL_NAME];
+      }
+    }
+
+    activeTools = filterWorkspaceToolsForRun(
+      activeTools,
+      input.prompt,
+      input.approvalGate !== undefined,
+    );
+
+    const builtinTools = createToolsForNames(toolCtx, activeTools);
+
+    let tools: ToolSet = input.extraTools
+      ? { ...builtinTools, ...input.extraTools }
+      : { ...builtinTools };
+
+    // Only approved calls may reach the execution journal.
+    if (input.toolExecutionRecorder) {
+      tools = wrapRecordedTools(tools, input.toolExecutionRecorder);
+    }
+
+    // -- Approval gate wrapping -----------------------------------------------
+    if (input.approvalGate) {
+      tools = wrapToolsWithApprovalGate(
+        tools,
+        input.approvalGate,
+        AGENT_PAUSE_TOOLS,
+      );
+    }
+
+    // -- Response schema → auto capture / stop / resolve ----------------------
+    if (input.responseSchema) {
+      tools = {
+        ...tools,
+        [RESPONSE_TOOL_NAME]: createResponseTool(
+          input.responseSchema,
+          (result) => {
+            this._responseToolFired = true;
+            this._responseToolResult = result;
+            if (RESPONSE_DEBUG) {
+              rlog.warn(
+                `[response-debug] response tool EXECUTED (captured) session=${this.busSessionId} ` +
+                  `resultBytes=${responseArgBytes(result)} — happy path`,
+              );
+            }
+            // With a custom resolveResult (e.g. TargetedPentestAgent), the raw schema result must be funnelled through it before fulfilling consume()'s race.
+            const customResolve = input.resolveResult;
+            if (customResolve) {
+              void Promise.resolve()
+                .then(() => {
+                  // Race .response against _drainRejection so a wedged stream can't hang a resolver awaiting it.
+                  const sr = this.streamResult;
+                  const guarded = Object.create(sr, {
+                    response: {
+                      get: () =>
+                        Promise.race([sr.response, this._drainRejection]),
+                    },
+                  });
+                  return customResolve(guarded);
+                })
+                .then((resolved) => {
+                  this._capturedResponse = resolved;
+                  this._resolveResponseCaptured(resolved);
+                })
+                .catch((err) => {
+                  this._rejectResponseCaptured(err);
+                });
+              return;
+            }
+            this._capturedResponse = result as TResult;
+            this._resolveResponseCaptured(result as TResult);
+          },
+        ),
+      };
+    }
+
+    if (input.resolveResult) {
+      this.resolveResult = input.resolveResult;
+    } else if (input.responseSchema) {
+      this.resolveResult = () => {
+        if (this._capturedResponse !== null) return this._capturedResponse;
+        return undefined as TResult;
+      };
+    }
+
+    let stopWhen = input.stopWhen;
+    if (input.responseSchema) {
+      const responseStop = hasToolCall(
+        RESPONSE_TOOL_NAME,
+      ) as StopCondition<ToolSet>;
+      if (!stopWhen) {
+        stopWhen = responseStop;
+      } else if (Array.isArray(stopWhen)) {
+        stopWhen = [...stopWhen, responseStop];
+      } else {
+        stopWhen = [stopWhen, responseStop];
+      }
+    }
+
+    // -- Messages persistence -------------------------------------------------
+    if (!existsSync(messagesDir)) {
+      mkdirSync(messagesDir, { recursive: true });
+    }
+    this.messagesPath = join(messagesDir, "messages.json");
+
+    // Mutable so that summarization can clear stale history.
+    const initialMessagesRef: { current: ModelMessage[] } = {
+      current: input.messages
+        ? [...input.messages]
+        : [
+            {
+              role: "user" as const,
+              content: [{ type: "text", text: input.prompt }],
+            },
+          ],
+    };
+
+    // Agent-local persistence: debounce, latest snapshot, and the
+    // serialized write queue live in the writer (see ./messagePersistence).
+    this.writer = new AgentMessageWriter({ messagesPath: this.messagesPath });
+    this.finalizeInterruptedStep = createInterruptedStepFinalizer({
+      eventBus: this.eventBus,
+      sessionId: this.busSessionId,
+      subagentId: this.subagentId,
+      writer: this.writer,
+      responseToolName: RESPONSE_TOOL_NAME,
+      responseToolFired: () => this._responseToolFired,
+      ...(RESPONSE_DEBUG
+        ? { debugLog: (message: string) => rlog.warn(message) }
+        : {}),
+    });
+    const schedulePersist = () => this.writer.schedulePersist();
+
+    // -- System prompt ---------------------------------------------------------
+    // Persona first; execution facts and the workspace section are appended by
+    // the harness for every persona, so custom prompts no longer bypass them.
+    // Facts are probed through the agent's actual command backend (see
+    // ./runtimeContext) — asynchronous, so the stream is created once they settle.
+    const baseSystemPrompt =
+      input.system ??
+      buildBaseSystemPrompt({
+        sandboxMode: agentCwd === input.session.rootPath,
+      });
+    const commandPlatform = resolveCommandPlatform(toolCtx);
+    const workspaceSection = buildSessionWorkspaceSection(
+      input.session,
+      agentCwd,
+      activeTools,
+      fileWorkspaceRoot,
+    );
+    // Bundled wordlist paths are host-local: advertise them only when
+    // commands execute locally.
+    const bundledAssets =
+      input.backends || input.sandbox ? null : buildBundledAssetsSection();
+    const assembleBaseSystemPrompt = (
+      facts: RuntimeExecutionFacts | null,
+    ): string => {
+      const sections: string[] = [baseSystemPrompt];
+      if (facts) {
+        sections.push(
+          buildRuntimeContextSection(facts, { platform: commandPlatform }),
+        );
+      }
+      if (bundledAssets) sections.push(bundledAssets);
+      return sections.join("\n\n");
+    };
+    this.toolCtx = toolCtx;
+    // Only agents whose tools can execute commands, touch files, or run
+    // PoCs get a runtime probe — for anyone else the facts are noise and the
+    // probe is a wasted subprocess.
+    this.probesRuntime = activeTools.some((name) =>
+      RUNTIME_CAPABLE_TOOL_NAMES.has(name),
+    );
+
+    // -- Init record + stream --------------------------------------------------
+    // Created by async initialization (streamReady) so the AI SDK telemetry
+    // binds to the span active at first consumption (this agent's
+    // invoke_agent span in consume()) and the system prompt can embed
+    // backend-probed facts. The synchronous escape hatch calls the same
+    // factory with settled-or-unknown facts — never host facts — guarded so
+    // exactly one model stream exists either way.
+    this.createStream = (facts) => {
+      // Hash only the base system prompt (excluding session workspace paths)
+      // so the hash is stable across runs with identical prompt versions. No
+      // step record can precede this init line: steps only originate from the
+      // stream created below.
+      const baseWithFacts = assembleBaseSystemPrompt(facts);
+      traceWriter.writeInit({
+        model: input.model,
+        systemPrompt: baseWithFacts,
+        activeTools,
+        sessionId: input.session.id,
+        target: input.target,
+      });
+      return streamResponse({
+        prompt: input.prompt,
+        system: baseWithFacts + workspaceSection,
+        model: input.model,
+        messages: input.messages,
+        tools,
+        activeTools,
+        stopWhen,
+        toolChoice: "auto",
+        languageModelMiddleware: input.languageModelMiddleware,
+        usageRecorder: input.usageRecorder,
+        contextRecorder: input.contextRecorder,
+        inferenceRecorder: input.inferenceRecorder,
+        // Per-subagent so the overflow tool-result dumps land next to this
+        // agent's messages.json (`subagents/{id}/tool-results/`) and a host
+        // can reclaim them when the subagent finishes, instead of piling up
+        // at the shared session root for the whole scan (ENOSPC). Falls back
+        // to the session root for the root/operator agent.
+        sessionPath: messagesDir,
+        sessionId: this.busSessionId,
+        onStepFinish: async (event) => {
+          const auxiliaryModelEvent =
+            event.response.id === "summarization" ||
+            event.response.id === "tool-repair";
+          const stepUsage = normalizeStepUsage(event);
+
+          if (auxiliaryModelEvent) {
+            traceWriter.recordStep([], stepUsage, { usageOnly: true });
+            await input.onStepFinish?.(event);
+            return;
+          }
+
+          // Recorded runs project the canonical committed context; the
+          // legacy path reconstructs from the (possibly stale after a fit)
+          // initial prefix. Canonical latest() already includes this step's
+          // messages — committing happens upstream in the ai layer's
+          // onStepFinish wrapper, before this user callback runs.
+          const canonical = input.contextRecorder?.latest() ?? [
+            ...initialMessagesRef.current,
+            ...event.response.messages,
+          ];
+          this.writer.setLatest(canonical);
+          schedulePersist();
+          traceWriter.recordStep(
+            event.response.messages as ModelMessage[],
+            stepUsage,
+          );
+          this.eventBus.emit("step-finish", {
+            messages: event.response.messages,
+            subagentId: this.subagentId,
+            sessionId: this.busSessionId,
+            messageId: this.currentMessageId ?? undefined,
+          });
+          this.currentMessageId = null;
+          await input.onStepFinish?.(event);
+        },
+        onSummarized: () => {
+          // Context was reset by summarization — discard the old history so
+          // subsequent onStepFinish writes only persist post-summary messages.
+          initialMessagesRef.current = [];
+          traceWriter.markSummarized();
+        },
+        onFinish: async (event) => {
+          // Flush any pending persistence before finishing
+          this.writer.cancelTimer();
+          // Skip if the interrupted-step finalizer already wrote the abort snapshot.
+          if (!this.writer.syntheticsPersisted) {
+            const finalMessages = input.contextRecorder?.latest() ??
+              this.writer.latest ?? [
+                ...initialMessagesRef.current,
+                ...event.response.messages,
+              ];
+            this.writer.setLatest(finalMessages);
+            await this.writer.enqueueWrite(finalMessages).catch(() => {});
+          }
+          await input.onFinish?.(event);
+        },
+        abortSignal: input.abortSignal,
+        authConfig: input.authConfig,
+        onCacheMetrics: input.onCacheMetrics,
+        enableThinking: input.enableThinking,
+        thinkingEffort: input.thinkingEffort,
+        openAIReasoningEffort: input.openAIReasoningEffort,
+        silent: true,
+      });
+    };
+    this.initializeStreamOnce = async () => {
+      // The sync escape hatch may have created the stream while discovery was
+      // pending — never a second model stream.
+      if (this._streamResult !== null) return;
+      // Abort-before-start skips the probe but still creates the stream so the
+      // SDK surfaces the abort normally; a probe failure degrades the prompt
+      // to unknown facts rather than failing the stream.
+      const facts =
+        this.probesRuntime && !this.abortSignal?.aborted
+          ? await probeRuntimeFacts(toolCtx).catch(
+              (): RuntimeExecutionFacts => UNKNOWN_FACTS,
+            )
+          : null;
+      // Re-check after the await: the escape hatch may have raced the probe.
+      if (this._streamResult !== null) return;
+      this._streamResult = this.createStream(facts);
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Stream access
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Asynchronous initialization seam: probe runtime facts through this
+   * agent's command backend (only when its selected tools can use them), then
+   * create the stream. Idempotent; every consumption entry point awaits it,
+   * so the AI layer's prompt budgeting and recovery see the actual final
+   * system text.
+   */
+  streamReady(): Promise<void> {
+    this.streamInit ??= this.initializeStreamOnce();
+    return this.streamInit;
+  }
+
+  /**
+   * The underlying Vercel AI SDK stream result — synchronous escape hatch.
+   * Always a real SDK result. Cold access creates it immediately with facts
+   * already settled for this runtime scope, else explicit unknown facts —
+   * never host facts; callers needing freshly probed facts await
+   * {@link streamReady}, `consume()`, or `fullStream` iteration instead.
+   * Guarded so a cold access racing an in-flight probe never creates a
+   * second model stream.
+   */
+  get streamResult(): StreamTextResult<ToolSet, never> {
+    if (this._streamResult === null) {
+      const facts = this.probesRuntime
+        ? (peekSettledRuntimeFacts(this.toolCtx) ?? UNKNOWN_FACTS)
+        : null;
+      this._streamResult = this.createStream(facts);
+    }
+    return this._streamResult;
+  }
+
+  /**
+   * The raw async-iterable stream of chunks.
+   * Equivalent to `streamResult.fullStream`; before initialization it
+   * settles {@link streamReady} on first iteration, then delegates to the
+   * real stream.
+   */
+  get fullStream(): AsyncIterable<TextStreamPart<ToolSet>> {
+    if (this._streamResult !== null) {
+      return this._streamResult.fullStream;
+    }
+    const self = this;
+    return (async function* () {
+      await self.streamReady();
+      const stream = self._streamResult;
+      if (stream === null) {
+        throw new Error("Stream initialization did not produce a stream");
+      }
+      yield* stream.fullStream;
+    })();
+  }
+
+  /**
+   * Makes the agent instance itself async-iterable so callers can write:
+   * ```ts
+   * for await (const chunk of agent) { ... }
+   * ```
+   *
+   * **Note:** The underlying stream can only be consumed once.
+   */
+  async *[Symbol.asyncIterator](): AsyncIterator<TextStreamPart<ToolSet>> {
+    await this.streamReady();
+    for await (const chunk of this.streamResult.fullStream) {
+      yield chunk;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Convenience helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Consume the stream, emitting each chunk on the {@link eventBus}, then
+   * resolve the final result.
+   *
+   * Each AI SDK stream part is forwarded to the bus via
+   * {@link AgentEventBus.emitStreamPart}, tagged with this agent's
+   * `subagentId` when present.
+   *
+   * @returns The value produced by `resolveResult`, or `void` if none was provided.
+   */
+  async consume(): Promise<TResult> {
+    const sid = this.subagentId;
+    const bus = this.eventBus;
+
+    const runConsume = async (): Promise<TResult> => {
+      // Reset per-run stream counters so a replayed run derives the same ids.
+      this.streamStepIndex = -1;
+      this.streamTextPartIndex = 0;
+      // Tool-call part ids are minted once and reused for the WHOLE session, never reset per step.
+      const toolParts = new Map<string, string>();
+      const ids: StreamIdContext = {
+        // The TUI routes any event with a subagentId into a subagent panel, so
+        // the orchestrator must leave it undefined; only real subagents set it.
+        subagentId: this.subagentId,
+        sessionId: this.busSessionId,
+        messageId: undefined,
+        textPartId: undefined,
+        toolPartId: (toolCallId: string) => {
+          let p = toolParts.get(toolCallId);
+          if (!p) {
+            p =
+              this.streamIdFactory?.({ kind: "tool-part", toolCallId }) ??
+              newPartId();
+            toolParts.set(toolCallId, p);
+          }
+          return p;
+        },
+      };
+
+      // Tool lifecycle state: in-flight calls awaiting a result, completed but
+      // unpersisted results (PR #779), streamed arg text, and deferred tool
+      // errors — all owned by the tracker (see ./toolLifecycle).
+      const tracker = new ToolLifecycleTracker();
+      let streamError: unknown;
+      let hasStreamError = false;
+
+      // Opt-in stall watchdog + response-tool tracer (see ./streamDiagnostics).
+      const diagnostics = new StreamDiagnostics({
+        sessionId: this._session.id,
+        subagentId: sid,
+        inFlightTools: () => tracker.inFlightTools,
+        responseToolFired: () => this._responseToolFired,
+        responseToolName: RESPONSE_TOOL_NAME,
+      });
+      diagnostics.start();
+
+      try {
+        // Initialize (runtime probe + stream creation) inside the span so
+        // telemetry binds to this agent's invoke_agent span.
+        await this.streamReady();
+        // 1–3. Iterate the stream: observe diagnostics, apply the part (id
+        // bookkeeping, tracker updates, step-close emissions), forward it.
+        for await (const chunk of this.streamResult.fullStream) {
+          diagnostics.observeChunk(chunk);
+          this.applyStreamPart(chunk, { ids, tracker, diagnostics });
+          bus.emitStreamPart(chunk, ids);
+        }
+        // The tracker keeps completed results: an abort with no trailing
+        // finish-step needs them for the finalization snapshot.
+      } catch (err) {
+        // 4. Capture the error; finalization below still runs.
+        streamError =
+          this.abortSignal?.aborted && isGenericAbortError(err)
+            ? agentAbortReason(this.abortSignal)
+            : err;
+        hasStreamError = true;
+      } finally {
+        // Preserve an already-observed abort if cleanup subsequently fails.
+        if (!hasStreamError && this.abortSignal?.aborted) {
+          streamError = agentAbortReason(this.abortSignal);
+          hasStreamError = true;
+        }
+        // 5–7. Close the interrupted step, dispose owned resources, settle.
+        const finalizeError = await this.finalizeRun({
+          tracker,
+          diagnostics,
+          ids,
+          streamError,
+        });
+        // Teardown failures must not replace the originating run failure.
+        if (!hasStreamError && finalizeError !== null) {
+          streamError = finalizeError;
+          hasStreamError = true;
+        }
+      }
+
+      if (hasStreamError) {
+        throw streamError;
+      }
+
+      if (this.abortSignal?.aborted) {
+        throw agentAbortReason(this.abortSignal);
+      }
+
+      if (this.resolveResult) {
+        if (this._responseToolFired) {
+          return undefined as TResult;
+        }
+        return this.resolveResult(this.streamResult);
+      }
+      return undefined as TResult;
+    };
+
+    // One invoke_agent span per execution. The conversation/root id stays
+    // stable across the tree while each span identifies its current agent.
+    const isSubagent = Boolean(sid);
+    const spanLabel = isSubagent
+      ? (this.subagentName ?? sid ?? "subagent")
+      : this.agentMode;
+    const rootSessionId = this._session.id;
+    const agentSessionId = this.busSessionId;
+    const runSpanAttributes: Record<string, string> = {
+      "gen_ai.operation.name": "invoke_agent",
+      "gen_ai.agent.id": agentSessionId,
+      "gen_ai.agent.name": spanLabel,
+      "gen_ai.conversation.id": rootSessionId,
+      "session.id": rootSessionId,
+      "pensar.session.id": agentSessionId,
+      "pensar.root_session.id": rootSessionId,
+      ...(!isSubagent ? { "pensar.agent.mode": this.agentMode } : {}),
+    };
+
+    const runInSpan = () =>
+      getApexTracer().startActiveSpan(
+        `invoke_agent ${spanLabel}`,
+        { attributes: runSpanAttributes },
+        async (span) => {
+          // Root runs register so process-exit shutdown can end an
+          // in-flight run's span before the final flush.
+          if (!isSubagent) registerActiveRootSpan(span);
+          // Root-level input/output for trace previews — ONLY under full
+          // payload capture (sensitive: objectives can name internal hosts).
+          // Fast Strike uses a synthetic subagent id for UI routing but is the
+          // primary run in that workflow.
+          const recordRootIO =
+            (!isSubagent || this.agentMode === "fast-strike") &&
+            shouldRecordAiPayloads();
+          if (recordRootIO && this.userPrompt) {
+            span.setAttribute("gen_ai.prompt", this.userPrompt);
+          }
+          try {
+            const result = await runConsume();
+            const completedResult =
+              result === undefined && this._responseToolFired
+                ? this._responseToolResult
+                : result;
+            if (
+              recordRootIO &&
+              completedResult !== undefined &&
+              completedResult !== null
+            ) {
+              span.setAttribute(
+                "gen_ai.completion",
+                safePreview(completedResult),
+              );
+            }
+            return result;
+          } catch (err) {
+            // Record once, keep the cardinality low, preserve the original.
+            span.recordException(err as Error);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            span.setAttribute(
+              "error.type",
+              err instanceof Error ? err.name : "Error",
+            );
+            if (recordRootIO) {
+              span.setAttribute(
+                "gen_ai.completion",
+                this._responseToolFired
+                  ? safePreview(this._responseToolResult)
+                  : `Failure: ${err instanceof Error ? err.message : String(err)}`,
+              );
+            }
+            throw err;
+          } finally {
+            unregisterActiveRootSpan(span);
+            // Ends only after runConsume's finalization (persistence +
+            // owned-resource disposal) has settled. Shutdown may have already
+            // ended it while that finalization was still in flight.
+            if (span.isRecording()) span.end();
+          }
+        },
+      );
+
+    const drain = !isSubagent
+      ? runInSpan()
+      : withSubagentSessionBaggage(sid, runInSpan);
+
+    // Decouple the result from stream teardown: with a `response` schema, return as soon as it's captured rather than waiting for the stream to close (which can wedge).
+    let rejectDrain: ((err: unknown) => void) | undefined;
+    this._drainRejection = new Promise<never>((_, reject) => {
+      rejectDrain = reject;
+    });
+    this._drainRejection.catch(() => {});
+
+    // Lets a caller that aborts after capturing the result await the drain's finally (in-flight tool closes) before completing.
+    this.drained = drain.then(
+      () => {},
+      () => {},
+    );
+
+    // Don't let drain's settle (reject OR resolve) mask an already-captured
+    // response; unblock the resolver's streamResult.response wait either way.
+    const guardedDrain = drain
+      .then((result) => {
+        if (this._responseToolFired) {
+          rejectDrain?.(new Error("drain resolved"));
+          return this.responseCaptured;
+        }
+        return result;
+      })
+      .catch((err) => {
+        rejectDrain?.(err);
+        if (!this._responseToolFired) throw err;
+        return this.responseCaptured;
+      });
+    guardedDrain.catch(() => {});
+
+    const result = await Promise.race([guardedDrain, this.responseCaptured]);
+    // Free the browser on result capture; the drain can wedge and leak camoufox.
+    await this.disconnectOwnedBrowser();
+    return result;
+  }
+
+  /**
+   * Apply one stream part: part-id bookkeeping, lifecycle-tracker updates,
+   * and the finish-step close-out emissions. Pure projection of the part
+   * onto run state; forwarding to the bus is the caller's job.
+   */
+  private applyStreamPart(
+    chunk: TextStreamPart<ToolSet>,
+    ctx: {
+      ids: StreamIdContext;
+      tracker: ToolLifecycleTracker;
+      diagnostics: StreamDiagnostics;
+    },
+  ): void {
+    const { ids, tracker, diagnostics } = ctx;
+    const sid = this.subagentId;
+    const bus = this.eventBus;
+    switch (chunk.type) {
+      case "start-step":
+        this.streamStepIndex++;
+        this.streamTextPartIndex = 0;
+        ids.messageId =
+          this.streamIdFactory?.({
+            kind: "message",
+            stepIndex: this.streamStepIndex,
+          }) ?? newMessageId();
+        this.currentMessageId = ids.messageId;
+        ids.textPartId = undefined;
+        break;
+      case "text-start":
+        ids.textPartId =
+          this.streamIdFactory?.({
+            kind: "text-part",
+            stepIndex: this.streamStepIndex,
+            textPartIndex: this.streamTextPartIndex,
+          }) ?? newPartId();
+        this.streamTextPartIndex++;
+        break;
+      case "text-end":
+        ids.textPartId = undefined;
+        break;
+      case "finish-step": {
+        tracker.onStepPersisted();
+        const finishReason = (chunk as { finishReason?: string }).finishReason;
+        const truncated = finishReason === "length";
+
+        for (const [toolCallId, info] of tracker.toolErrors) {
+          diagnostics.logSurfacedToolError({
+            toolCallId,
+            toolName: info.toolName,
+            message: info.message,
+            streamedArgChars: (tracker.streamedArgText.get(toolCallId) ?? "")
+              .length,
+            finishReason,
+            truncated,
+          });
+          bus.emit("tool-result", {
+            toolCallId,
+            toolName: info.toolName,
+            result: {
+              type: "error-text",
+              value: truncated
+                ? `Tool call failed: the model's output was truncated at its max output tokens before the "${info.toolName}" arguments were complete. ${info.message}`
+                : `Tool call failed: ${info.message}`,
+            },
+            sessionId: this.busSessionId,
+            subagentId: sid,
+            partId: ids.toolPartId?.(toolCallId),
+            messageId: ids.messageId,
+          });
+        }
+        tracker.clearToolErrors();
+
+        // Close any call still in flight (args never finalized) so it doesn't render stuck "running".
+        for (const [toolCallId, toolName] of tracker.inFlightTools) {
+          diagnostics.logClosingInFlightTool({
+            toolCallId,
+            toolName,
+            finishReason,
+            truncated,
+          });
+          // Already-fired response: mark submitted, not "did not complete".
+          const result =
+            toolName === RESPONSE_TOOL_NAME && this._responseToolFired
+              ? { type: "text" as const, value: "Response submitted." }
+              : {
+                  type: "error-text" as const,
+                  value: truncated
+                    ? "Tool call did not complete: the model's output was truncated at its max output tokens before the arguments were finalized."
+                    : "Tool call did not complete",
+                };
+          bus.emit("tool-result", {
+            toolCallId,
+            toolName,
+            result,
+            sessionId: this.busSessionId,
+            subagentId: sid,
+            partId: ids.toolPartId?.(toolCallId),
+            messageId: ids.messageId,
+          });
+        }
+        tracker.clearInFlight();
+        break;
+      }
+      default:
+        // Tool-input/delta, tool-call, tool-error, tool-result → tracker.
+        tracker.observePart(chunk);
+    }
+  }
+
+  /**
+   * Finalize a finished (or failed) run: stop diagnostics, dispose the owned
+   * shell, surface deferred tool errors, close the interrupted step, and
+   * disconnect the owned browser on every path. Returns the first
+   * finalization error (or null) — the caller keeps the stream error
+   * primary.
+   */
+  private async finalizeRun(input: {
+    tracker: ToolLifecycleTracker;
+    diagnostics: StreamDiagnostics;
+    ids: StreamIdContext;
+    streamError: unknown;
+  }): Promise<unknown> {
+    const { tracker, diagnostics, ids, streamError } = input;
+    const sid = this.subagentId;
+    const bus = this.eventBus;
+
+    // Stop the stall watchdog so it never leaks past stream end / throw.
+    diagnostics.stop();
+    let finalizationError: unknown;
+    let hasFinalizationError = false;
+    const recordFinalizationError = (error: unknown) => {
+      if (hasFinalizationError) return;
+      finalizationError = error;
+      hasFinalizationError = true;
+    };
+
+    try {
+      // Dispose first — the 3s kill protocol is awaited, never
+      // fire-and-forget: hosts rely on drained before closeout, so an
+      // active command must settle (bounded) before finalization continues.
+      try {
+        await this.disposeOwnedShell();
+      } catch (error) {
+        recordFinalizationError(error);
+      }
+      // Stop this agent's callback listeners (each outcome independent;
+      // the seam clears the abort signal so cleanup still runs post-abort).
+      try {
+        const outcomes = await this.callbackListeners.stopAll();
+        const failed = outcomes.find((o) => o.error);
+        if (failed) {
+          recordFinalizationError(
+            new Error(
+              `callback listener cleanup failed for ${failed.jobId}: ${failed.error}`,
+            ),
+          );
+        }
+      } catch (error) {
+        recordFinalizationError(error);
+      }
+      // Flush after disposal: surfaces the latched step-commit failure (the
+      // SDK swallows onStepFinish errors) without skipping owned cleanup.
+      if (this.contextRecorder) {
+        try {
+          await this.contextRecorder.flush();
+        } catch (error) {
+          recordFinalizationError(error);
+        }
+      }
+      // Flush tool-errors that never reached a finish-step into the snapshot.
+      for (const [toolCallId, info] of tracker.flushToolErrorsToResults()) {
+        const result = {
+          type: "error-text" as const,
+          value: `Tool call failed: ${info.message}`,
+        };
+        try {
+          bus.emit("tool-result", {
+            toolCallId,
+            toolName: info.toolName,
+            result,
+            sessionId: this.busSessionId,
+            subagentId: sid,
+            partId: ids.toolPartId?.(toolCallId),
+            messageId: ids.messageId,
+          });
+        } catch (error) {
+          recordFinalizationError(error);
+        }
+      }
+      // Snapshot unpersisted step state: open tools get synthetic closes,
+      // completed/errored results get written.
+      if (tracker.hasUnpersistedState()) {
+        const failure =
+          streamError ??
+          (this.abortSignal?.aborted
+            ? agentAbortReason(this.abortSignal)
+            : undefined);
+        const reason =
+          failure instanceof Error && failure.message
+            ? failure.message
+            : failure !== undefined
+              ? String(failure)
+              : "Stream terminated unexpectedly";
+        try {
+          await this.finalizeInterruptedStep({
+            snapshot: tracker.snapshot(),
+            reason,
+            partIdFor: ids.toolPartId,
+            messageId: ids.messageId,
+          });
+        } catch (error) {
+          recordFinalizationError(error);
+        }
+      }
+    } catch (error) {
+      recordFinalizationError(error);
+    } finally {
+      // Tear down the Chromium child process we own. Without this, a
+      // naturally-finishing agent leaks its Playwright MCP browser — over a
+      // long single-process scan (many endpoints) the leaked Chromium
+      // processes exhaust memory and OOM the run. disconnect() force-kills
+      // and never hangs, so awaiting here is safe.
+      await this.disconnectOwnedBrowser();
+    }
+    return hasFinalizationError ? finalizationError : null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Owned-resource disposal — explicit idempotent operations; the
+  // finalization path and host teardown (abortAndDrain) coordinate them
+  // without knowing the shell/browser implementations.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Disposes the owned per-command executor exactly once; safe to call from
+   * multiple teardown paths. Returns the same cached barrier on repeat
+   * calls; the barrier resolves once a killed invocation's bounded
+   * termination protocol has settled, so closeout never races an active
+   * command.
+   */
+  disposeOwnedShell(): Promise<void> {
+    if (this.shellDisposed) {
+      return this.shellDisposeBarrier ?? Promise.resolve();
+    }
+    this.shellDisposed = true;
+    this.shellDisposeBarrier =
+      this.commandShell?.dispose() ?? Promise.resolve();
+    return this.shellDisposeBarrier;
+  }
+
+  /** Force-kills the owned Chromium child process exactly once; safe to call from multiple teardown paths. */
+  private async disconnectOwnedBrowser(): Promise<void> {
+    if (this.browserDisconnected) return;
+    if (!this.ownsBrowserSession || !this.browserSession) return;
+    this.browserDisconnected = true;
+    await this.browserSession.disconnect().catch(() => {});
+  }
+
+  /**
+   * Idempotent teardown for hosts that abort before `consume()` settles
+   * (Console `settleOnAbort` on timeout/pause). Force-disconnects the owned
+   * browser, awaits the shell's bounded kill barrier, then awaits the drain
+   * so owned work settles before the host starts closeout.
+   */
+  async abortAndDrain(): Promise<void> {
+    await this.disconnectOwnedBrowser();
+    await this.disposeOwnedShell().catch(() => {});
+    await this.callbackListeners.stopAll().catch(() => {});
+    await this.drained.catch(() => {});
+  }
+
+  /**
+   * Promise that resolves to the final response metadata once the stream
+   * has been fully consumed. Await this *after* iterating the stream.
+   */
+  get response() {
+    return this.streamReady().then(() => this.streamResult.response);
+  }
+}
+
+// These tools pause the agent and surface their own UI to the operator.
+// Gating them through the approval gate would double-prompt.
+const AGENT_PAUSE_TOOLS = new Set<string>([ASK_USER_QUESTIONS_TOOL_NAME]);
+
+function wrapToolsWithApprovalGate(
+  tools: ToolSet,
+  gate: ApprovalGate,
+  exemptToolNames?: Set<string>,
+): ToolSet {
+  const wrapped: ToolSet = {};
+
+  for (const [name, coreTool] of Object.entries(tools)) {
+    if (exemptToolNames?.has(name)) {
+      wrapped[name] = coreTool;
+      continue;
+    }
+
+    // biome-ignore lint/suspicious/noExplicitAny: ai-sdk CoreTool is a discriminated union that requires runtime narrowing for the approval gate wrapper.
+    const t = coreTool as any;
+
+    if (!t.execute) {
+      wrapped[name] = coreTool;
+      continue;
+    }
+
+    const originalExecute = t.execute;
+
+    wrapped[name] = {
+      ...t,
+      // biome-ignore lint/suspicious/noExplicitAny: ai-sdk tool execute receives an opaque ExecuteContext we don't need to narrow.
+      execute: async (args: Record<string, unknown>, options: any) => {
+        const toolCallId =
+          args.toolCallId ??
+          `tc_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+        log.debug(`${name} (${toolCallId}): checking`);
+        try {
+          await gate.check(name, String(toolCallId), args);
+        } catch (err) {
+          if (err instanceof ApprovalDeniedError) {
+            log.debug(`${name} (${toolCallId}): denied`);
+            return { blocked: true, reason: "Denied by operator" };
+          }
+          throw err;
+        }
+        log.debug(`${name} (${toolCallId}): approved, executing`);
+
+        const result = await originalExecute(args, options);
+        log.debug(`${name} (${toolCallId}): execute finished`);
+        return result;
+      },
+    };
+  }
+
+  return wrapped;
+}
+
+/** Bounded, crash-safe JSON preview of a run result for span output. */
+function safePreview(value: unknown): string {
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined ? String(value) : text.slice(0, 2000);
+  } catch {
+    return "[unserializable result]";
+  }
+}