@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/runs/foreground/foreground-memory.ts

@@ -0,0 +1,132 @@
+import { formatRunIdAmbiguity } from "../shared/run-id-ambiguity.ts";
+import { buildManagementControl, formatRunAction } from "../../shared/status-format.ts";
+import type {
+  ReadonlyForegroundResumeRun,
+  ReadonlySubagentState,
+  SubagentExecutionResult,
+} from "../../shared/types.ts";
+
+const LATEST_ALIASES = new Set(["last", "latest"]);
+export function resolveRememberedForegroundRun(
+  requested: string | undefined,
+  state: ReadonlySubagentState,
+): ReadonlyForegroundResumeRun | undefined {
+  if (requested === undefined) {
+    return;
+  }
+  const normalized = requested.trim();
+  if (normalized.length === 0) {
+    return;
+  }
+  const runs = [...(state.foregroundRuns?.values() ?? [])];
+  if (LATEST_ALIASES.has(normalized)) {
+    return runs.sort((left, right) => right.updatedAt - left.updatedAt).at(0);
+  }
+  const direct = state.foregroundRuns?.get(normalized);
+  const matches = direct ? [direct] : runs.filter((run) => run.runId.startsWith(normalized));
+  if (matches.length > 1) {
+    throw new Error(
+      formatRunIdAmbiguity(
+        "foreground",
+        normalized,
+        matches.map((run) => run.runId),
+      ),
+    );
+  }
+  return matches.at(0);
+}
+function resumeGuidance(run: ReadonlyForegroundResumeRun, childSafe: boolean): string {
+  const child = run.children.find(
+    (entry) =>
+      entry.sessionFile !== undefined &&
+      entry.sessionFile.length > 0 &&
+      entry.status !== "detached",
+  );
+  if (!child && run.children.some((entry) => entry.status === "detached")) {
+    return `Completion unconfirmed. Check ${formatRunAction("questions", run.runId, {}, childSafe)} before continuing.`;
+  }
+  if (run.children.length === 1 && child) {
+    return `Continue: ${formatRunAction("resume", run.runId, { message: "..." }, childSafe)}`;
+  }
+  if (!child) {
+    return "Revive: unavailable; no child session file was persisted.";
+  }
+  return `Continue child: ${formatRunAction("resume", run.runId, { index: child.index, message: "..." }, childSafe)}`;
+}
+function rememberedState(
+  run: ReadonlyForegroundResumeRun,
+): "completed" | "paused" | "blocked" | "failed" | "unknown" {
+  if (run.error !== undefined && run.error.length > 0) {
+    return "failed";
+  }
+  if (run.children.some((child) => child.status === "failed" || child.status === "timed-out")) {
+    return "failed";
+  }
+  if (run.children.some((child) => child.status === "blocked")) {
+    return "blocked";
+  }
+  if (run.children.some((child) => child.status === "paused")) {
+    return "paused";
+  }
+  if (run.children.some((child) => child.status === "detached")) {
+    return "unknown";
+  }
+  return run.pausedReason !== undefined && run.pausedReason.length > 0 ? "paused" : "completed";
+}
+function compact(text: string): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length > 240 ? `${normalized.slice(0, 239)}…` : normalized;
+}
+function childLine(child: ReadonlyForegroundResumeRun["children"][number]): string {
+  const parts = [`  ${child.index + 1}. ${child.agent} ${child.status}`];
+  if (child.sessionFile !== undefined && child.sessionFile.length > 0) {
+    parts.push(`session: ${child.sessionFile}`);
+  }
+  if (child.artifactPath !== undefined && child.artifactPath.length > 0) {
+    parts.push(`artifact: ${child.artifactPath}`);
+  }
+  if (child.summary !== undefined && child.summary.length > 0) {
+    parts.push(`final: ${compact(child.summary)}`);
+  }
+  return parts.join(", ");
+}
+export function rememberedForegroundStatusResult(
+  run: ReadonlyForegroundResumeRun,
+  childSafe = false,
+): SubagentExecutionResult {
+  const state = rememberedState(run);
+  const resumable = run.children.find(
+    (child) =>
+      child.sessionFile !== undefined &&
+      child.sessionFile.length > 0 &&
+      child.status !== "detached",
+  );
+  const lines = [`Run: ${run.runId}`, "State: remembered foreground", `Outcome: ${state}`];
+  if (run.error !== undefined && run.error.length > 0) {
+    lines.push(`Error: ${run.error}`);
+  } else if (state === "paused" && run.pausedReason !== undefined && run.pausedReason.length > 0) {
+    lines.push(run.pausedReason);
+  }
+  lines.push(
+    `Mode: ${run.mode}`,
+    `Updated: ${new Date(run.updatedAt).toISOString()}`,
+    `Launch cwd: ${run.cwd}`,
+    "Children:",
+    ...run.children.map(childLine),
+    resumeGuidance(run, childSafe),
+    `Status: ${formatRunAction("status", run.runId, {}, childSafe)}`,
+  );
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    details: {
+      mode: "management",
+      results: [],
+      managementControl: buildManagementControl({
+        state,
+        runId: run.runId,
+        index: resumable?.index,
+        canResume: resumable !== undefined,
+      }),
+    },
+  };
+}

package/src/runs/foreground/invocation-context.ts

@@ -0,0 +1,88 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
+import { providerQualifiedModelId, toModelInfo } from "../../shared/model-info.ts";
+import { collectInvocationAgentNames } from "../../shared/settings.ts";
+import {
+  buildFlatAgentNameResolver,
+  invocationUsesForkContext,
+  resolveAgentContext,
+  validateForkContextModelPolicy,
+} from "../../shared/agent-context-policy.ts";
+import { resolveModelCandidate } from "../shared/model-fallback.ts";
+import type { AgentConfig, ModelInfo, SubagentExecutionResult } from "../../shared/types.ts";
+import type { ExecutorReadDeps, SubagentParamsLike } from "./subagent-params.ts";
+import { toExecutionErrorResult } from "./execution-input.ts";
+
+export interface AgentInvocation {
+  readonly agents: readonly AgentConfig[];
+  readonly discovered: readonly AgentConfig[];
+  readonly context: SubagentParamsLike["context"];
+  readonly resolveContextForAgent: (name: string | undefined) => "fresh" | "fork";
+  readonly resolveContextForIndex: (index?: number) => "fresh" | "fork";
+}
+/** Resolve profiles and fork policy without owning journals, session directories, or launch state. */
+export function discoverInvocation(
+  params: SubagentParamsLike,
+  cwd: string,
+  ctx: ExtensionContext,
+  deps: Readonly<Pick<ExecutorReadDeps, "discoverAgents">>,
+): AgentInvocation {
+  const inherited = providerQualifiedModelId(ctx.model?.provider, ctx.model?.id);
+  const discovered = deps
+    .discoverAgents(cwd, resolveExecutionAgentScope(params.agentScope), {
+      projectTrusted: ctx.isProjectTrusted(),
+    })
+    .agents.map((agent) => inheritModel(agent, inherited));
+  const context = invocationUsesForkContext(
+    params.context,
+    collectInvocationAgentNames(params),
+    discovered,
+  )
+    ? "fork"
+    : undefined;
+  const atIndex = buildFlatAgentNameResolver(params);
+  const forAgent = (name: string | undefined) =>
+    resolveAgentContext(params.context, name, discovered);
+  const agents: AgentConfig[] = [];
+  for (const agent of discovered) {
+    agents.push({ ...agent, defaultContext: forAgent(agent.name) });
+  }
+  return {
+    agents,
+    discovered,
+    context,
+    resolveContextForAgent: forAgent,
+    resolveContextForIndex: (index) => forAgent(atIndex(index ?? 0)),
+  };
+}
+function inheritModel(agent: AgentConfig, model: string | undefined): AgentConfig {
+  if (
+    (agent.model !== undefined && agent.model.length > 0) ||
+    model === undefined ||
+    model.length === 0
+  ) {
+    return agent;
+  }
+  return { ...agent, model };
+}
+export function validateInvocationForkModel(
+  params: SubagentParamsLike,
+  agents: AgentInvocation,
+  ctx: ExtensionContext,
+): SubagentExecutionResult | undefined {
+  if (agents.context !== "fork") {
+    return;
+  }
+  let available: readonly ModelInfo[];
+  try {
+    available = ctx.modelRegistry.getAvailable().map(toModelInfo);
+  } catch (error) {
+    return toExecutionErrorResult(params, error, agents.context);
+  }
+  const invalid = validateForkContextModelPolicy(params, agents.discovered, (model) =>
+    resolveModelCandidate(model, available, ctx.model?.provider),
+  );
+  return invalid !== undefined && invalid.length > 0
+    ? toExecutionErrorResult(params, new Error(invalid), agents.context)
+    : undefined;
+}

package/src/runs/foreground/invocation-execution.ts

@@ -0,0 +1,465 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getArtifactsDir } from "../../shared/artifacts.ts";
+import { isParallelStep, isDynamicParallelStep } from "../../shared/settings.ts";
+import { createPerAgentForkContextResolver } from "../../shared/agent-context-policy.ts";
+import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
+import {
+  resolveIntercomBridge,
+  resolveIntercomSessionTarget,
+  resolveOrchestratorIntercomTarget,
+  type IntercomBridgeState,
+} from "../../intercom/intercom-bridge.ts";
+import { resolveControlConfig } from "../shared/subagent-control.ts";
+import { createNestedRoute, resolveInheritedNestedRouteFromEnv } from "../shared/nested-events.ts";
+import { applyForceTopLevelAsyncOverride } from "../background/top-level-async.ts";
+import { saveQuestionOwner } from "../shared/supervisor-questions.ts";
+import { buildWorkflowGraphSnapshot, workflowAgentNodes } from "../shared/workflow-graph.ts";
+import { rememberOwnedRun, workflowChildren } from "../shared/run-records.ts";
+import { errorMessage } from "../../shared/unknown.ts";
+import {
+  type SubagentExecutionResult,
+  type SubagentExecutionUpdateCallback,
+  type SubagentRunMode,
+  type ReadonlyInput,
+  checkSubagentDepth,
+} from "../../shared/types.ts";
+import {
+  type ExecutionContextData,
+  type ExecutorDeps,
+  type SubagentParamsLike,
+  resolveAsyncExecutionMode,
+} from "./subagent-params.ts";
+import {
+  buildRequestedModeError,
+  normalizeRepeatedParallelCounts,
+  normalizeRoleForegroundTimeout,
+  resolveForegroundTimeoutMs,
+  toExecutionErrorResult,
+  validateExecutionInput,
+  withForkContext,
+} from "./execution-input.ts";
+import { runAsyncPath } from "./run-async-path.ts";
+import { canClarifyInvocation, clarifyInvocation } from "./clarify-invocation.ts";
+import { waitForOwnedRun } from "./wait-run.ts";
+
+export interface ExecutionInvocation {
+  readonly params: SubagentParamsLike;
+  readonly invocationCwd: string;
+  readonly ctx: ExtensionContext;
+  readonly signal?: AbortSignal;
+  readonly onUpdate?: SubagentExecutionUpdateCallback;
+}
+import {
+  discoverInvocation,
+  validateInvocationForkModel,
+  type AgentInvocation,
+} from "./invocation-context.ts";
+interface LaunchPreparation {
+  readonly call: ExecutionInvocation;
+  readonly params: SubagentParamsLike;
+  readonly cwd: string;
+  readonly parentSessionFile: string | null;
+  readonly agents: AgentInvocation;
+  readonly runId: string;
+  readonly intercomBridge: Readonly<IntercomBridgeState>;
+  readonly nestedRoute: NonNullable<ExecutionContextData["nestedRoute"]>;
+}
+interface SessionLayout {
+  readonly root: string;
+  readonly dir: (index?: number) => string;
+}
+interface LaunchResources {
+  readonly sessions: Readonly<ReturnType<typeof createPerAgentForkContextResolver>>;
+  readonly policy: AsyncPolicy;
+  readonly layout: SessionLayout;
+  readonly artifactsDir: string;
+  readonly controlConfig: ExecutionContextData["controlConfig"];
+}
+type Assignments = readonly {
+  readonly agent: string;
+  readonly task?: string;
+  readonly label?: string;
+}[];
+interface AsyncPolicy {
+  readonly backgroundRequestedWhileClarifying: boolean;
+  readonly effectiveAsync: boolean;
+  readonly foregroundTimeoutMs?: number;
+}
+function mode(params: SubagentParamsLike): SubagentRunMode {
+  if ((params.chain?.length ?? 0) > 0) {
+    return "chain";
+  }
+  if ((params.tasks?.length ?? 0) > 0) {
+    return "parallel";
+  }
+  return "single";
+}
+function invocationModes(params: SubagentParamsLike, ctx: ExtensionContext) {
+  const hasChain = (params.chain?.length ?? 0) > 0,
+    hasTasks = (params.tasks?.length ?? 0) > 0;
+  return {
+    hasChain,
+    hasTasks,
+    hasSingle: !hasChain && !hasTasks && params.agent !== undefined && params.agent.length > 0,
+    allowClarifyTaskPrompt: hasChain && canClarifyInvocation(params, ctx),
+  };
+}
+/** Owns launch planning and its durable registration, not management or existing-run waits. */
+export class InvocationExecution {
+  private readonly deps: ExecutorDeps;
+  constructor(
+    // Launch owns the current session identity and tracked/durable run records through these dependencies.
+    deps: ExecutorDeps,
+  ) {
+    this.deps = deps;
+  }
+  async execute(call: ExecutionInvocation): Promise<SubagentExecutionResult> {
+    const depth = checkSubagentDepth(this.deps.config.maxSubagentDepth);
+    if (depth.blocked) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Nested subagent call blocked (depth=${depth.depth}, max=${depth.maxDepth}). You are running at the maximum subagent nesting depth. Complete your current task directly without delegating to further subagents.`,
+          },
+        ],
+        isError: true,
+        details: { mode: "single", results: [] },
+      };
+    }
+    const normalized = normalizeRepeatedParallelCounts(call.params);
+    if (normalized.error) {
+      return normalized.error;
+    }
+    if (!normalized.params) {
+      throw new Error("Task normalization did not return launch input.");
+    }
+    const params = applyForceTopLevelAsyncOverride(
+      normalized.params,
+      depth.depth,
+      this.deps.config.forceTopLevelAsync === true,
+    );
+    const cwd = params.cwd ?? call.invocationCwd;
+    const parentSessionFile = call.ctx.sessionManager.getSessionFile() ?? null;
+    this.deps.state.currentSessionId = resolveCurrentSessionId(call.ctx.sessionManager);
+    const agents = discoverInvocation(params, cwd, call.ctx, this.deps);
+    const fallback = resolveIntercomSessionTarget(
+      this.deps.pi.getSessionName(),
+      call.ctx.sessionManager.getSessionId(),
+    );
+    const intercomBridge = resolveIntercomBridge(
+      resolveOrchestratorIntercomTarget(this.deps.pi.events, fallback),
+    );
+    const runId = randomUUID();
+    const nestedRoute = resolveInheritedNestedRouteFromEnv() ?? createNestedRoute(runId);
+    const invalid =
+      validateExecutionInput(params, agents.agents, invocationModes(params, call.ctx)) ??
+      validateInvocationForkModel(params, agents, call.ctx);
+    if (invalid) {
+      return invalid;
+    }
+    return this.prepareLaunch({
+      call,
+      params,
+      agents,
+      cwd,
+      runId,
+      parentSessionFile,
+      intercomBridge,
+      nestedRoute,
+    });
+  }
+  private async prepareLaunch(input: LaunchPreparation): Promise<SubagentExecutionResult> {
+    const { call, params, agents, cwd, runId, parentSessionFile } = input;
+    const clarified = await this.clarify(params, agents, {
+      ctx: call.ctx,
+      signal: call.signal,
+      cwd,
+      runId,
+    });
+    if ("details" in clarified) {
+      return clarified;
+    }
+    const sessions = this.resolveForkSessions(agents, call.ctx, clarified);
+    if ("details" in sessions) {
+      return sessions;
+    }
+    const policy = this.asyncPolicy(clarified);
+    if ("details" in policy) {
+      return policy;
+    }
+    const controlConfig = resolveControlConfig(this.deps.config.control, clarified.control);
+    const artifactsDir = policy.effectiveAsync
+      ? this.deps.tempArtifactsDir
+      : getArtifactsDir(parentSessionFile);
+    const layout = this.sessionLayout(clarified, parentSessionFile, runId, agents.context);
+    if ("details" in layout) {
+      return layout;
+    }
+    return this.launch(
+      this.executionData(input, clarified, {
+        sessions,
+        policy,
+        layout,
+        artifactsDir,
+        controlConfig,
+      }),
+      agents.context,
+    );
+  }
+  private executionData(
+    input: LaunchPreparation,
+    clarified: SubagentParamsLike,
+    resources: LaunchResources,
+  ): ExecutionContextData {
+    const { call, agents, cwd, runId, intercomBridge, nestedRoute } = input;
+    const { sessions, policy, layout, artifactsDir, controlConfig } = resources;
+    const update = this.progressUpdate(runId, agents.context, call.onUpdate);
+    return {
+      params: clarified,
+      effectiveCwd: cwd,
+      ctx: call.ctx,
+      signal: call.signal,
+      onUpdate: update,
+      agents: agents.agents,
+      runId,
+      shareEnabled: clarified.share === true,
+      sessionRoot: layout.root,
+      sessionDirForIndex: layout.dir,
+      sessionFileForIndex: (index) =>
+        sessions.sessionFileForIndex(index) ?? path.join(layout.dir(index), "session.jsonl"),
+      sessionFileForAgentIndex: (agent, index) =>
+        sessions.sessionFileForAgentIndex(agent, index) ??
+        path.join(layout.dir(index), "session.jsonl"),
+      artifactsEnabled: clarified.artifacts !== false,
+      artifactsDir,
+      ...policy,
+      controlConfig,
+      intercomBridge,
+      nestedRoute,
+    };
+  }
+  private async clarify(
+    params: SubagentParamsLike,
+    agents: AgentInvocation,
+    call: {
+      readonly ctx: ExtensionContext;
+      readonly signal?: AbortSignal;
+      readonly cwd: string;
+      readonly runId: string;
+    },
+  ): Promise<SubagentParamsLike | SubagentExecutionResult> {
+    try {
+      const clarified = await clarifyInvocation({
+        params,
+        agents: agents.agents,
+        ctx: call.ctx,
+        cwd: call.cwd,
+        runId: call.runId,
+      });
+      if (!clarified) {
+        return {
+          content: [{ type: "text", text: "Cancelled" }],
+          details: { mode: mode(params), results: [] },
+        };
+      }
+      if (call.signal?.aborted === true) {
+        return toExecutionErrorResult(
+          clarified,
+          new Error("Subagent cancelled before launch."),
+          agents.context,
+        );
+      }
+      return clarified;
+    } catch (error) {
+      return toExecutionErrorResult(params, error, agents.context);
+    }
+  }
+  private resolveForkSessions(
+    agents: AgentInvocation,
+    ctx: ExtensionContext,
+    params: SubagentParamsLike,
+  ): ReturnType<typeof createPerAgentForkContextResolver> | SubagentExecutionResult {
+    try {
+      return createPerAgentForkContextResolver(ctx.sessionManager, agents.resolveContextForIndex, {
+        resolveContextForAgentIndex: (name) => agents.resolveContextForAgent(name),
+      });
+    } catch (error) {
+      return toExecutionErrorResult(params, error, agents.context);
+    }
+  }
+  private asyncPolicy(params: SubagentParamsLike): AsyncPolicy | SubagentExecutionResult {
+    const async = resolveAsyncExecutionMode(params, this.deps.asyncByDefault);
+    const timeout = resolveForegroundTimeoutMs(params);
+    if (timeout.error !== undefined) {
+      return buildRequestedModeError(params, timeout.error);
+    }
+    if (async.effectiveAsync && timeout.timeoutMs !== undefined) {
+      return buildRequestedModeError(
+        params,
+        "timeoutMs/maxRuntimeMs only applies to foreground subagent runs. Set async:false or use action:'interrupt' for background runs.",
+      );
+    }
+    return {
+      effectiveAsync: async.effectiveAsync,
+      backgroundRequestedWhileClarifying:
+        mode(params) !== "single" && async.backgroundRequestedWhileClarifying,
+      foregroundTimeoutMs: async.effectiveAsync
+        ? timeout.timeoutMs
+        : normalizeRoleForegroundTimeout(params, timeout.timeoutMs),
+    };
+  }
+  private sessionLayout(
+    params: SubagentParamsLike,
+    parent: string | null,
+    runId: string,
+    context: SubagentParamsLike["context"],
+  ): { readonly root: string; readonly dir: (index?: number) => string } | SubagentExecutionResult {
+    const requested = params.sessionDir;
+    const configured = this.deps.config.defaultSessionDir;
+    let root: string;
+    if (requested !== undefined && requested.length > 0) {
+      root = path.resolve(this.deps.expandTilde(requested));
+    } else {
+      const base =
+        configured !== undefined && configured.length > 0
+          ? path.resolve(this.deps.expandTilde(configured))
+          : this.deps.getSubagentSessionRoot(parent);
+      root = path.join(base, runId);
+    }
+    try {
+      fs.mkdirSync(root, { recursive: true });
+    } catch (error) {
+      return toExecutionErrorResult(
+        params,
+        new Error(`Failed to create session directory '${root}': ${errorMessage(error)}`),
+        context,
+      );
+    }
+    return { root, dir: (index) => path.join(root, `run-${index ?? 0}`) };
+  }
+  private progressUpdate(
+    runId: string,
+    context: SubagentParamsLike["context"],
+    onUpdate: SubagentExecutionUpdateCallback | undefined,
+  ): SubagentExecutionUpdateCallback {
+    return (result) => {
+      const owned = this.deps.state.ownedRuns?.get(runId);
+      if (owned && result.details.workflowGraph) {
+        rememberOwnedRun(this.deps.state, {
+          ...owned,
+          children: workflowChildren(owned.children, result.details.workflowGraph),
+        });
+      }
+      onUpdate?.(withForkContext(result, context));
+    };
+  }
+  private rememberLaunch(
+    data: ExecutionContextData,
+    result: SubagentExecutionResult,
+    nodes: ReadonlyInput<ReturnType<typeof workflowAgentNodes>> | undefined,
+    assignments: Assignments,
+  ): void {
+    const params = data.params;
+    rememberOwnedRun(this.deps.state, {
+      runId: data.runId,
+      ownerSessionId: data.ctx.sessionManager.getSessionId(),
+      rootRunId: data.runId,
+      source: "async",
+      mode: mode(params),
+      cwd: data.effectiveCwd,
+      task:
+        params.task ?? params.tasks?.map((task) => task.task).join("\n") ?? "Delegated workflow",
+      asyncDir: result.details.asyncDir,
+      pid: result.details.asyncPid ?? this.deps.state.asyncJobs.get(data.runId)?.pid,
+      startedAt: Date.now(),
+      children: assignments.map((assignment, index) => ({
+        agent: assignment.agent,
+        index,
+        task: assignment.task,
+        label: assignment.label,
+        workflowNodeId: nodes?.at(index)?.id,
+      })),
+    });
+  }
+  private assignments(params: SubagentParamsLike): Assignments {
+    if (params.tasks) {
+      return params.tasks;
+    }
+    if (params.chain) {
+      return params.chain.flatMap((step) => {
+        if (isParallelStep(step)) {
+          return step.parallel;
+        }
+        return isDynamicParallelStep(step) ? [step.parallel] : [step];
+      });
+    }
+    if (params.agent === undefined) {
+      throw new Error("Single launch requires an agent.");
+    }
+    return [{ agent: params.agent, task: params.task, label: params.label }];
+  }
+  private async launch(
+    data: ExecutionContextData,
+    context: SubagentParamsLike["context"],
+  ): Promise<SubagentExecutionResult> {
+    const graph = data.params.chain
+      ? buildWorkflowGraphSnapshot({ runId: data.runId, steps: data.params.chain })
+      : undefined;
+    const nodes = graph ? workflowAgentNodes(graph) : undefined;
+    const assignments = this.assignments(data.params);
+    saveQuestionOwner(data.runId, data.ctx.sessionManager.getSessionId());
+    try {
+      const result = runAsyncPath(data, this.deps);
+      if (!result) {
+        throw new Error("Invalid subagent execution mode.");
+      }
+      if (result.isError === true) {
+        return withForkContext(result, context);
+      }
+      this.rememberLaunch(data, result, nodes, assignments);
+      if (this.foregroundWaitNeeded(data, result)) {
+        return withForkContext(
+          await waitForOwnedRun({
+            id: data.runId,
+            deps: this.deps,
+            ctx: data.ctx,
+            signal: data.signal,
+            onUpdate: data.onUpdate,
+            cancelNewRun: true,
+            executionResult: true,
+            includeProgress: data.params.includeProgress,
+          }),
+          context,
+        );
+      }
+      return withForkContext(result, context);
+    } catch (error) {
+      const result = toExecutionErrorResult(data.params, error, context);
+      this.rememberLaunchFailure(data.runId, result);
+      return result;
+    }
+  }
+  private foregroundWaitNeeded(
+    data: ExecutionContextData,
+    result: SubagentExecutionResult,
+  ): boolean {
+    const id = result.details.asyncId;
+    return !data.effectiveAsync && id !== undefined && id.length > 0;
+  }
+  private rememberLaunchFailure(runId: string, result: SubagentExecutionResult): void {
+    const owned = this.deps.state.ownedRuns?.get(runId);
+    if (owned) {
+      rememberOwnedRun(this.deps.state, {
+        ...owned,
+        error: result.content
+          .filter((part) => part.type === "text")
+          .map((part) => part.text)
+          .join("\n"),
+      });
+    }
+  }
+}