@pi-unipi/subagents 2.6.1 → 2.9.0

package/src/tool-handler.ts

@@ -0,0 +1,1144 @@
+/**
+ * @pi-unipi/subagents — spawn_helper parity handler
+ *
+ * Routes the extended spawn_helper surface: management actions, workflowScript
+ * execution, and legacy single-child launches (type/prompt aliases). Applies
+ * the Phase 2 libraries: agent resolution + aliases, enablement, budgets,
+ * depth guard, context policy, spawn budgets, timeout defaults, and output
+ * truncation. The render/notify plumbing stays in index.ts — this module only
+ * decides and executes.
+ */
+
+import { existsSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agent-manager.js";
+import type { SubagentsConfig, AgentConfig } from "./types.js";
+import { SUBAGENT_ACTIONS } from "./parity-types.js";
+import { runWorkflowScript, type WorkflowScriptChildResult } from "./workflow-script.js";
+import {
+  resolveTurnBudgetConfig,
+  validateToolBudgetConfig,
+  validateUsageBudgetConfig,
+  appendTurnBudgetSystemPrompt,
+} from "./budgets.js";
+import {
+  createRunFanoutBudget,
+  claimRunFanoutBatch,
+  getRunFanoutBudgetSnapshot,
+  formatRunFanoutBudget,
+} from "./run-fanout-budget.js";
+import { truncateOutput, resolveMaxOutput } from "./output-limits.js";
+import {
+  resolveContext,
+  assertForegroundContextSupported,
+  resolveMaxSubagentDepth,
+  depthExceeded,
+  isFanoutChild,
+  withChildBoundaryInstructions,
+} from "./child-safety.js";
+import { listRetainedChildren, formatRetainedChildren, resolveResumeTarget } from "./retained-children.js";
+import { ASYNC_DIR, TEMP_ROOT_DIR, RESULTS_DIR } from "./parity-types.js";
+import { buildGuideText } from "./guide.js";
+import { ScheduledRunManager } from "./scheduled-runs.js";
+import {
+  validateAcceptanceInput,
+  normalizeAcceptanceInput,
+  normalizeGateAcceptance,
+  evaluateAcceptance,
+  stripAcceptanceReport,
+} from "./acceptance.js";
+import type { AcceptanceConfig } from "./acceptance.js";
+import {
+  resolveMissionStoreLocation,
+  createMission,
+  readMission,
+  listMissions,
+  updateMission,
+  MissionNotFoundError,
+  type MissionStoreConfig,
+  type MissionStatus,
+} from "./mission-store.js";
+
+export interface HandlerDeps {
+  pi: ExtensionAPI;
+  manager: AgentManager;
+  config: SubagentsConfig;
+  /** Legacy single-child spawn (foreground). */
+  spawnForeground: (
+    ctx: ExtensionContext,
+    agentName: string,
+    prompt: string,
+    options: {
+      description?: string;
+      maxTurns?: number;
+      modelInput?: string;
+      thinkingLevel?: unknown;
+      signal?: AbortSignal;
+    },
+  ) => Promise<{ ok: boolean; output: string; error?: string; toolUses: number; durationMs: number }>;
+  /** Legacy single-child spawn (background). */
+  spawnBackground: (
+    ctx: ExtensionContext,
+    agentName: string,
+    prompt: string,
+    options: {
+      description?: string;
+      maxTurns?: number;
+      modelInput?: string;
+      thinkingLevel?: unknown;
+    },
+  ) => string;
+  /** Session-wide cumulative spawn accounting (maxSubagentSpawnsPerSession). */
+  spawnAccounting?: {
+    used(): number;
+    cap(): number | undefined;
+    consume(count: number): void;
+  };
+  /** Depth env for the recursion guard. */
+  env?: NodeJS.ProcessEnv;
+  /** Retained-children dir override (defaults to our async temp root). */
+  retainedDir?: string;
+  /** Mission store config (from OUR subagents.json). */
+  missionConfig?: MissionStoreConfig;
+  /** Project root for mission records. */
+  projectRoot?: string;
+  /** Async process runner (Phase 3). When present, background launches and
+   *  fork contexts run as child pi processes; when absent they error with
+   *  guidance (test environments). */
+  runAsync?: (launch: {
+    agentName: string;
+    task: string;
+    description?: string;
+    model?: string;
+    thinking?: string | false;
+    context: "fresh" | "fork";
+    timeoutMs?: number;
+    maxTurns?: number;
+    /** Resume: continue a retained child in its stored session. */
+    resumeSessionFile?: string;
+    /** Worktree isolation: launch the child in a managed git worktree. */
+    worktree?: boolean;
+  }) => Promise<{
+    runId: string;
+    status: string;
+    output?: string;
+    error?: string;
+  }>;
+}
+
+function textResult(msg: string, details?: unknown) {
+  return { content: [{ type: "text" as const, text: msg }], details };
+}
+
+/**
+ * Resolve the effective acceptance config: explicit gate shorthand wins over
+ * acceptance; agent-level defaultAcceptance fills gaps. Returns undefined for
+ * no gate. Errors are visible strings.
+ */
+function resolveEffectiveAcceptance(
+  args: Record<string, unknown>,
+): { ok: true; acceptance?: AcceptanceConfig } | { ok: false; error: string } {
+  if (args.gate !== undefined && args.acceptance !== undefined) {
+    return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." };
+  }
+  if (args.gate !== undefined) {
+    const normalized = normalizeGateAcceptance(args.gate);
+    if (!normalized) return { ok: false, error: "gate must be a non-empty command string." };
+    return { ok: true, acceptance: normalized };
+  }
+  if (args.acceptance === undefined) return { ok: true, acceptance: undefined };
+  const errors = validateAcceptanceInput(args.acceptance);
+  if (errors.length > 0) return { ok: false, error: errors.join(" ") };
+  return { ok: true, acceptance: normalizeAcceptanceInput(args.acceptance) };
+}
+
+/** Post-run acceptance evaluation wrapper. */
+async function evaluateRunAcceptance(
+  acceptance: AcceptanceConfig | undefined,
+  output: string,
+  cwd: string,
+): Promise<{ output: string; ledger?: Awaited<ReturnType<typeof evaluateAcceptance>> }> {
+  if (!acceptance || acceptance.level === "auto") return { output };
+  const ledger = await evaluateAcceptance({ acceptance, output, cwd });
+  const cleanOutput = stripAcceptanceReport(output);
+  if (ledger.status === "rejected") {
+    return { output: cleanOutput, ledger };
+  }
+  return { output: cleanOutput, ledger };
+}
+
+/** Parse + validate everything, resolve the agent, or return an error result. */
+function preflight(
+  deps: HandlerDeps,
+  args: Record<string, unknown>,
+): { ok: true; agent: AgentConfig; agentName: string; prompt: string } | { ok: false; error: string } {
+  const agentNameRaw = (args.agent ?? args.type) as string | undefined;
+  const prompt = (args.task ?? args.prompt) as string | undefined;
+
+  if (!agentNameRaw || typeof agentNameRaw !== "string") {
+    return { ok: false, error: "spawn_helper requires an agent (or legacy type) parameter." };
+  }
+
+  const agentName = deps.manager.resolveAlias(agentNameRaw);
+  const agent = deps.manager.getAgentConfig(agentName);
+  if (!agent) {
+    const known = deps.manager.getKnownTypes().join(", ");
+    return { ok: false, error: `Unknown agent type "${agentNameRaw}". Known types: ${known}` };
+  }
+  if (!deps.manager.isTypeEnabled(agentName)) {
+    return { ok: false, error: `Agent type "${agentName}" is disabled by configuration.` };
+  }
+
+  // Depth guard
+  const env = deps.env ?? process.env;
+  const maxDepth = resolveMaxSubagentDepth(agent, deps.config, env);
+  if (depthExceeded(env, maxDepth)) {
+    return {
+      ok: false,
+      error: `Subagent depth cap reached (maxSubagentDepth ${maxDepth}). This child cannot spawn further subagents for its assigned fanout.`,
+    };
+  }
+
+  if (!prompt || typeof prompt !== "string" || !prompt.trim()) {
+    return { ok: false, error: "spawn_helper requires a task (or legacy prompt) parameter." };
+  }
+
+  return { ok: true, agent, agentName, prompt };
+}
+
+/**
+ * Main entry: route a spawn_helper invocation.
+ * Returns a tool result; never throws.
+ */
+export async function handleSpawnHelper(
+  deps: HandlerDeps,
+  ctx: ExtensionContext,
+  args: Record<string, unknown>,
+  signal?: AbortSignal,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
+  try {
+    // ---- Management actions ----
+    const action = args.action as string | undefined;
+    if (action !== undefined) {
+      return await handleAction(deps, ctx, action, args);
+    }
+
+    // ---- workflowScript execution ----
+    const workflowScript = args.workflowScript as string | undefined;
+    if (workflowScript !== undefined) {
+      return await handleWorkflowScript(deps, ctx, workflowScript, args, signal);
+    }
+
+    // ---- Single-child launch (legacy + reference params) ----
+    return await handleSingleChild(deps, ctx, args, signal);
+  } catch (error) {
+    return textResult(
+      `spawn_helper failed: ${error instanceof Error ? error.message : String(error)}`,
+      { status: "error", error: error instanceof Error ? error.message : String(error) },
+    );
+  }
+}
+
+// ============================================================================
+// Management actions
+// ============================================================================
+
+async function handleAction(
+  deps: HandlerDeps,
+  _ctx: ExtensionContext,
+  action: string,
+  args: Record<string, unknown>,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
+  if (!(SUBAGENT_ACTIONS as readonly string[]).includes(action)) {
+    return textResult(
+      `Unknown action "${action}". Supported actions: ${SUBAGENT_ACTIONS.join(", ")}.`,
+      { status: "error" },
+    );
+  }
+
+  switch (action) {
+    case "list": {
+      const types = deps.manager.getKnownTypes();
+      const lines = types.map((type) => {
+        const agent = deps.manager.getAgentConfig(type);
+        const enabled = deps.manager.isTypeEnabled(type);
+        const scope = agent?.source ?? "config";
+        const desc = agent?.description ?? "";
+        return `- ${type}${agent?.aliases?.length ? ` (aliases: ${agent.aliases.join(", ")})` : ""} [${scope}]${enabled ? "" : " [disabled]"}: ${desc}`;
+      });
+      return textResult(`Available subagents:\n${lines.join("\n")}`);
+    }
+
+    case "get": {
+      const target = (args.agent ?? args.type ?? args.id) as string | undefined;
+      if (!target) return textResult("action 'get' requires an agent name.");
+      const agentName = deps.manager.resolveAlias(target);
+      const agent = deps.manager.getAgentConfig(agentName);
+      if (!agent) return textResult(`Unknown agent "${target}".`);
+      return textResult(
+        [
+          `Agent: ${agent.name}`,
+          ...(agent.aliases?.length ? [`Aliases: ${agent.aliases.join(", ")}`] : []),
+          `Description: ${agent.description}`,
+          `Source: ${agent.source ?? "builtin"}`,
+          `Tools: ${agent.builtinToolNames?.join(", ") || "(all builtins)"}`,
+          ...(agent.disallowedTools?.length ? [`Disallowed: ${agent.disallowedTools.join(", ")}`] : []),
+          `Prompt mode: ${agent.promptMode}`,
+          ...(agent.model ? [`Model: ${agent.model}`] : []),
+          ...(agent.thinking !== undefined ? [`Thinking: ${String(agent.thinking)}`] : []),
+          ...(agent.defaultContext ? [`Default context: ${agent.defaultContext}`] : []),
+          ...(agent.timeoutMs ? [`Timeout: ${agent.timeoutMs}ms`] : []),
+          `Enabled: ${deps.manager.isTypeEnabled(agentName)}`,
+        ].join("\n"),
+      );
+    }
+
+    case "status": {
+      const accounting = deps.spawnAccounting;
+      const sessionCap = accounting?.cap();
+      const used = accounting?.used() ?? 0;
+      const lines = [
+        `Active agents: ${deps.manager.listAgents().filter((a) => a.status === "running" || a.status === "queued").length}`,
+        `Max concurrent: ${deps.manager.getMaxConcurrent()}`,
+      ];
+      if (sessionCap !== undefined) {
+        lines.push(
+          `Session spawn budget: ${used}/${sessionCap} used, ${Math.max(0, sessionCap - used)} remaining`,
+        );
+      } else {
+        lines.push("Session spawn budget: unlimited");
+      }
+      const running = deps.manager.listAgents().filter((a) => a.status === "running" || a.status === "queued");
+      for (const record of running) {
+        lines.push(`- ${record.id} [${record.type}] ${record.status}: ${record.description}`);
+      }
+      return textResult(lines.join("\n"));
+    }
+
+    case "children.list": {
+      const retained = listRetainedChildren(deps.retainedDir ?? ASYNC_DIR);
+      if (retained.length === 0) {
+        // Fall back to in-process completed agents from this session.
+        const recent = deps.manager
+          .listAgents()
+          .filter((a) => a.status !== "running" && a.status !== "queued")
+          .slice(-10);
+        if (recent.length === 0) return textResult("No completed children in this session yet.");
+        return textResult(
+          recent.map((r) => `- ${r.id} [${r.type}] ${r.status}: ${r.description}`).join("\n"),
+        );
+      }
+      return textResult(formatRetainedChildren(retained));
+    }
+
+    case "resume": {
+      const id = args.id as string | undefined;
+      const message = args.message as string | undefined;
+      if (!id) return textResult("action 'resume' requires an id (retained run id or prefix).");
+      if (!message || !message.trim()) return textResult("action 'resume' requires a non-empty follow-up message.");
+      if (!deps.runAsync) {
+        return textResult("action 'resume' requires the background process runner, which is unavailable in this host.", { status: "error" });
+      }
+      const target = resolveResumeTarget(deps.retainedDir ?? ASYNC_DIR, id);
+      if (!target.ok) return textResult(target.error, { status: "error" });
+      const result = await deps.runAsync({
+        agentName: target.agent,
+        task: message.trim(),
+        description: `resume ${target.runId.slice(-8)}`,
+        context: "fresh",
+        resumeSessionFile: target.sessionFile,
+      });
+      return textResult(
+        `Resumed ${target.runId} as ${result.runId} (agent: ${target.agent}, stored session contract kept).\nUse get_helper_result to retrieve results.`,
+        { status: "background", runId: result.runId },
+      );
+    }
+
+    case "stop": {
+      const id = args.id as string | undefined;
+      if (!id) return textResult("action 'stop' requires an id.");
+      const record = deps.manager.getRecord(id);
+      if (!record) return textResult(`Run not found: "${id}".`);
+      record.abortController?.abort();
+      return textResult(`Stop requested for ${id} (${record.type}, ${record.status}).`);
+    }
+
+    case "grant-spawn-budget": {
+      const accounting = deps.spawnAccounting;
+      if (!accounting) return textResult("Spawn budget accounting is unavailable in this host.");
+      const cap = accounting.cap();
+      if (cap === undefined) return textResult("Session spawn budget is unlimited; nothing to grant.");
+      const additional = args.additional as number | undefined;
+      if (typeof additional !== "number" || !Number.isInteger(additional) || additional < 1) {
+        return textResult("action 'grant-spawn-budget' requires a positive integer 'additional'.");
+      }
+      // Grants require interactive confirmation — delegated to the host via pi.
+      return textResult(
+        `grant-spawn-budget requires native user confirmation; requested +${additional} against cap ${cap}. ` +
+          `This action needs the interactive parent; run it from the root session.`,
+      );
+    }
+
+    case "doctor": {
+      const lines: string[] = [
+        "Subagents doctor report",
+        "",
+        "Runtime",
+        `- cwd: ${process.cwd()}`,
+        `- async runner: ${deps.runAsync ? "available (child pi processes)" : "unavailable"}`,
+        "",
+        "Filesystem",
+        `- temp root: ${TEMP_ROOT_DIR}${existsSync(TEMP_ROOT_DIR) ? "" : " (created on first run)"}`,
+        `- async runs: ${ASYNC_DIR}`,
+        `- results: ${RESULTS_DIR}`,
+        "",
+        "Discovery",
+        `- known agent types: ${deps.manager.getKnownTypes().length}`,
+        ...deps.manager.getKnownTypes().map((type) => {
+          const agent = deps.manager.getAgentConfig(type);
+          const enabled = deps.manager.isTypeEnabled(type);
+          return `  - ${type} [${agent?.source ?? "config"}]${enabled ? "" : " [disabled]"}${agent?.aliases?.length ? ` (aliases: ${agent.aliases.join(", ")})` : ""}`;
+        }),
+        "",
+        "Budgets",
+        `- run timeout default: ${deps.config.timeoutMs ?? "30min (default)"}`,
+        `- tool timeout: ${deps.config.toolTimeoutMs ?? "env/known-fast defaults"}`,
+        `- spawn caps: run=${deps.config.maxSubagentSpawnsPerRun ?? 64}, session=${deps.config.maxSubagentSpawnsPerSession ?? "unlimited"}, active-async=${deps.config.maxActiveAsyncRunsPerSession ?? "unlimited"}`,
+        `- depth cap: ${resolveMaxSubagentDepth(undefined, deps.config, deps.env ?? process.env)}`,
+        "",
+        "Concurrency",
+        `- maxConcurrent: ${deps.config.maxConcurrent}`,
+        `- active in-process: ${deps.manager.listAgents().filter((a) => a.status === "running" || a.status === "queued").length}`,
+        `- retained children: ${listRetainedChildren(deps.retainedDir ?? ASYNC_DIR).length}`,
+      ];
+      return textResult(lines.join("\n"));
+    }
+
+    case "guide": {
+      const topic = (args.topic as string | undefined) ?? "overview";
+      return textResult(buildGuideText(topic));
+    }
+
+    case "mission.create": {
+      const location = resolveMissionStoreLocation({
+        projectRoot: deps.projectRoot ?? process.cwd(),
+        config: deps.missionConfig,
+      });
+      const missionInput = (args.mission ?? {}) as Record<string, unknown>;
+      const title = (missionInput.title ?? args.name) as string | undefined;
+      if (!title || typeof title !== "string" || !title.trim()) {
+        return textResult("action 'mission.create' requires mission.title (or name).", { status: "error" });
+      }
+      const objective = (missionInput.objective as string | undefined) ?? `${title}`;
+      try {
+        const record = createMission(location, {
+          title: title.trim(),
+          objective: objective.trim(),
+          ...(missionInput.goal === true ? { goal: true } : {}),
+          ...(missionInput.budget ? { budget: missionInput.budget as { tokens: number } } : {}),
+          ...(typeof missionInput.labels === "object" ? { labels: missionInput.labels as string[] } : {}),
+        });
+        return textResult(
+          `Mission created: ${record.id}\nTitle: ${record.title}\nStatus: ${record.status}\nAttach runs with missionId: ${record.id}`,
+          { status: "completed", missionId: record.id },
+        );
+      } catch (error) {
+        return textResult(`mission.create failed: ${error instanceof Error ? error.message : String(error)}`, { status: "error" });
+      }
+    }
+
+    case "mission.list": {
+      const location = resolveMissionStoreLocation({
+        projectRoot: deps.projectRoot ?? process.cwd(),
+        config: deps.missionConfig,
+      });
+      const { records, warnings } = listMissions(location);
+      if (records.length === 0) return textResult("No missions for this project.");
+      const lines = records.map((r) => `- ${r.id} [${r.status}] ${r.title}${r.summary ? ` — ${r.summary.slice(0, 80)}` : ""}`);
+      return textResult(
+        [`Missions (${records.length}):`, ...lines, ...(warnings.length ? ["", ...warnings] : [])].join("\n"),
+      );
+    }
+
+    case "mission.show":
+    case "mission.update":
+    case "mission.resolve-decision":
+    case "mission.attach-run":
+    case "mission.close": {
+      const missionId = args.missionId as string | undefined;
+      if (!missionId) return textResult(`action '${action}' requires missionId.`, { status: "error" });
+      const location = resolveMissionStoreLocation({
+        projectRoot: deps.projectRoot ?? process.cwd(),
+        config: deps.missionConfig,
+      });
+      try {
+        if (action === "mission.show") {
+          const record = readMission(location, missionId);
+          return textResult(
+            [
+              `Mission ${record.id} [${record.status}]`,
+              `Title: ${record.title}`,
+              `Objective: ${record.objective}`,
+              ...(record.goal ? [`Goal: ${record.goal.status}${record.budget ? ` (${record.usage?.tokens ?? 0}/${record.budget.tokens} tokens)` : ""}`] : []),
+              `Runs: ${record.runs.length} | Decisions: ${record.decisions.filter((d) => d.status === "open").length} open / ${record.decisions.length} total`,
+              ...(record.summary ? [`Summary: ${record.summary}`] : []),
+              ...(record.runs.length ? ["", "Runs:", ...record.runs.map((r) => `- ${r.runId}${r.agent ? ` (${r.agent})` : ""} ${r.status ?? ""}`)] : []),
+            ].join("\n"),
+          );
+        }
+        if (action === "mission.close") {
+          const summary = args.summary as string | undefined;
+          const status: MissionStatus = (args.missionStatus as MissionStatus | undefined) ?? (summary ? "completed" : "cancelled");
+          const record = updateMission(location, missionId, { status, ...(summary ? { summary } : {}) });
+          return textResult(`Mission ${record.id} closed as ${record.status}.`, { status: "completed", missionId: record.id });
+        }
+        if (action === "mission.attach-run") {
+          const runId = (args.runId ?? args.id) as string | undefined;
+          if (!runId) return textResult("mission.attach-run requires runId (or id).", { status: "error" });
+          const record = updateMission(location, missionId, {
+            addRun: { runId, ...(typeof args.missionStatus === "string" ? { status: args.missionStatus } : {}) },
+          });
+          return textResult(`Run ${runId} attached to mission ${record.id}.`, { status: "completed", missionId: record.id });
+        }
+        if (action === "mission.resolve-decision") {
+          const decisionId = args.id as string | undefined;
+          const resolution = args.message as string | undefined;
+          if (!decisionId || !resolution) {
+            return textResult("mission.resolve-decision requires id (decision id) and message (resolution).", { status: "error" });
+          }
+          const record = updateMission(location, missionId, { resolveDecision: { id: decisionId, resolution } });
+          return textResult(`Decision ${decisionId} resolved on mission ${record.id}.`, { status: "completed" });
+        }
+        // mission.update: generic field updates
+        const record = updateMission(location, missionId, {
+          ...(typeof args.summary === "string" ? { summary: args.summary } : {}),
+          ...(typeof args.missionStatus === "string" ? { status: args.missionStatus as MissionStatus } : {}),
+        });
+        return textResult(`Mission ${record.id} updated.`, { status: "completed", missionId: record.id });
+      } catch (error) {
+        if (error instanceof MissionNotFoundError) return textResult(error.message, { status: "error" });
+        return textResult(`${action} failed: ${error instanceof Error ? error.message : String(error)}`, { status: "error" });
+      }
+    }
+
+    case "schedule.create":
+    case "schedule.list":
+    case "schedule.show":
+    case "schedule.history":
+    case "schedule.pause":
+    case "schedule.resume":
+    case "schedule.run":
+    case "schedule.run-due":
+    case "schedule.delete": {
+      if (!deps.runAsync) {
+        return textResult("Schedule actions require the background process runner, which is unavailable in this host.", { status: "error" });
+      }
+      const manager = new ScheduledRunManager(deps.projectRoot ?? process.cwd(), {
+        storeRoot: deps.config.scheduledRuns?.storeRoot,
+        maxPending: deps.config.scheduledRuns?.maxPending,
+        launch: async (record) => {
+          const result = await deps.runAsync!({
+            agentName: record.agent,
+            task: record.task,
+            description: `schedule: ${record.name}`,
+            context: "fresh",
+            timeoutMs: record.timeoutMs,
+          });
+          return result.runId;
+        },
+      });
+
+      try {
+        switch (action) {
+          case "schedule.create": {
+            const record = manager.create({
+              name: (args.name as string | undefined) ?? `schedule-${Date.now().toString(36)}`,
+              agent: (args.agent ?? args.type) as string,
+              task: (args.task ?? args.prompt) as string,
+              at: args.at as string | undefined,
+              every: args.every as string | undefined,
+              catchUp: args.catchUp as "none" | "latest" | undefined,
+              timeoutMs: args.timeoutMs as number | undefined,
+            });
+            const next = record.trigger.kind === "once"
+              ? new Date(record.trigger.atMs).toISOString()
+              : record.trigger.nextRunAt;
+            return textResult(
+              `Schedule created: ${record.id}\nName: ${record.name}\nAgent: ${record.agent}\nTrigger: ${record.trigger.kind === "once" ? `once at ${next}` : `every ${record.trigger.every}`}\nNext run: ${next}`,
+              { status: "completed", scheduleId: record.id },
+            );
+          }
+          case "schedule.list": {
+            const all = manager.list();
+            if (all.length === 0) return textResult("No schedules for this project.");
+            return textResult(
+              [
+                `Schedules (${all.length}):`,
+                ...all.map((r) => {
+                  const next = r.trigger.kind === "once" ? r.trigger.atMs : r.trigger.nextRunAt;
+                  return `- ${r.id} "${r.name}" [${r.paused ? "paused" : "active"}] ${r.trigger.kind} → ${r.agent}: ${r.trigger.kind === "once" ? new Date(next).toISOString() : `every ${r.trigger.every}`}`;
+                }),
+              ].join("\n"),
+            );
+          }
+          case "schedule.show": {
+            const id = args.id as string | undefined;
+            if (!id) return textResult("schedule.show requires id.", { status: "error" });
+            const record = manager.show(id);
+            if (!record) return textResult(`No schedule matches "${id}".`, { status: "error" });
+            const history = manager.readHistory(id);
+            return textResult(
+              [
+                `Schedule ${record.id} "${record.name}" [${record.paused ? "paused" : "active"}]`,
+                `Agent: ${record.agent}`,
+                `Task: ${record.task.slice(0, 200)}`,
+                `Trigger: ${record.trigger.kind === "once" ? `once at ${record.trigger.at}` : `every ${record.trigger.every}`}`,
+                `Overlap: ${record.overlap} | catchUp: ${record.catchUp}`,
+                `Runs: ${history.length}`,
+                ...history.slice(-5).map((r) => `- ${r.id} ${r.state}${r.error ? ` (${r.error})` : ""}`),
+              ].join("\n"),
+            );
+          }
+          case "schedule.history": {
+            const id = args.id as string | undefined;
+            if (!id) return textResult("schedule.history requires id.", { status: "error" });
+            const history = manager.readHistory(id);
+            if (history.length === 0) return textResult("No runs recorded for this schedule.");
+            return textResult(
+              ["Schedule runs (newest last):", ...history.map((r) => `- ${r.id} ${r.state} ${r.plannedAt}${r.error ? ` (${r.error})` : ""}`)].join("\n"),
+            );
+          }
+          case "schedule.pause":
+          case "schedule.resume": {
+            const id = args.id as string | undefined;
+            if (!id) return textResult(`${action} requires id.`, { status: "error" });
+            const record = manager.setPaused(id, action === "schedule.pause");
+            return textResult(`Schedule ${record.id} "${record.name}" ${record.paused ? "paused" : "resumed"}.`);
+          }
+          case "schedule.run": {
+            const id = args.id as string | undefined;
+            if (!id) return textResult("schedule.run requires id.", { status: "error" });
+            const run = await manager.runNow(id);
+            return textResult(
+              run.state === "completed"
+                ? `Schedule ran: async run ${run.asyncRunId}`
+                : `Schedule run ${run.state}${run.error ? `: ${run.error}` : ""}`,
+              { status: run.state === "completed" ? "completed" : "error" },
+            );
+          }
+          case "schedule.run-due": {
+            const runs = await manager.runDue();
+            return textResult(`${runs.length} due schedule(s) executed.`);
+          }
+          case "schedule.delete": {
+            const id = args.id as string | undefined;
+            if (!id) return textResult("schedule.delete requires id.", { status: "error" });
+            const removed = manager.delete(id);
+            return textResult(removed ? `Schedule ${id} deleted.` : `No schedule matches "${id}".`, { status: removed ? "completed" : "error" });
+          }
+          default:
+            return textResult(`Unknown schedule action.`, { status: "error" });
+        }
+      } catch (error) {
+        return textResult(`${action} failed: ${error instanceof Error ? error.message : String(error)}`, { status: "error" });
+      }
+    }
+
+    default:
+      // Actions that belong to later phases report their status clearly.
+      return textResult(
+        `action "${action}" is recognized but not yet implemented in this build (planned phase).`,
+        { status: "error" },
+      );
+  }
+}
+
+// ============================================================================
+// workflowScript execution (foreground)
+// ============================================================================
+
+async function handleWorkflowScript(
+  deps: HandlerDeps,
+  ctx: ExtensionContext,
+  script: string,
+  args: Record<string, unknown>,
+  signal: AbortSignal | undefined,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
+  const asyncRequested = (args.async as boolean | undefined) ?? deps.config.asyncByDefault ?? true;
+  if (asyncRequested) {
+    return handleAsyncWorkflowScript(deps, ctx, script, args, signal);
+  }
+
+  // Validate call-level budgets up front (reference behavior).
+  if (args.turnBudget !== undefined) {
+    const { error } = resolveTurnBudgetConfig(args.turnBudget);
+    if (error) return textResult(error, { status: "error" });
+  }
+  if (args.toolBudget !== undefined) {
+    const { error } = validateToolBudgetConfig(args.toolBudget);
+    if (error) return textResult(error, { status: "error" });
+  }
+  if (args.usageBudget !== undefined) {
+    const { error } = validateUsageBudgetConfig(args.usageBudget);
+    if (error) return textResult(error, { status: "error" });
+  }
+
+  // Spawn budget: one fanout budget per top-level workflow run.
+  const perRunCap = deps.config.maxSubagentSpawnsPerRun ?? 64;
+  const budget = createRunFanoutBudget(`workflow-${Date.now()}`, perRunCap);
+
+  const sessionAccounting = deps.spawnAccounting;
+  const sessionCap = sessionAccounting?.cap();
+
+  const admit = (calls: Array<{ key: string; params: Record<string, unknown> }>): void => {
+    if (calls.length === 0) return;
+    // Per-run budget: atomic group admission.
+    claimRunFanoutBatch(budget, calls.map((call) => call.key));
+    // Session budget: cumulative.
+    if (sessionCap !== undefined && sessionAccounting) {
+      const used = sessionAccounting.used();
+      if (used + calls.length > sessionCap) {
+        throw new Error(
+          `Session spawn budget exhausted: ${used}/${sessionCap} used, ${calls.length} requested. ` +
+            `Use spawn_helper ({ action: "grant-spawn-budget", additional: N }) from the interactive parent to extend.`,
+        );
+      }
+      sessionAccounting.consume(calls.length);
+    }
+  };
+
+  const launch = async (
+    key: string,
+    params: Record<string, unknown>,
+    childSignal: AbortSignal,
+  ): Promise<WorkflowScriptChildResult> => {
+    const agentNameRaw = params.agent as string | undefined;
+    const task = params.task as string | undefined;
+    if (!agentNameRaw || !task) {
+      return { key, ok: false, output: "runs.run requires agent and task.", error: "missing agent/task", artifactPaths: [] };
+    }
+    const agentName = deps.manager.resolveAlias(agentNameRaw);
+    const agent = deps.manager.getAgentConfig(agentName);
+    if (!agent) {
+      return { key, ok: false, output: `Unknown agent "${agentNameRaw}".`, error: "unknown agent", artifactPaths: [] };
+    }
+    if (!deps.manager.isTypeEnabled(agentName)) {
+      return { key, ok: false, output: `Agent "${agentName}" is disabled.`, error: "disabled", artifactPaths: [] };
+    }
+
+    // Context policy (foreground = fresh only).
+    const contextMode = resolveContext(params.context as string | undefined, agent, deps.config);
+    if (contextMode === "fork") {
+      return {
+        key,
+        ok: false,
+        output: 'context "fork" requires background execution; foreground workflow children are fresh-context.',
+        error: "fork unavailable in foreground",
+        artifactPaths: [],
+      };
+    }
+
+    // Turn budget: wrap-up block in the child prompt.
+    let childTask = task;
+    const turnBudgetResult = resolveTurnBudgetConfig(params.turnBudget ?? args.turnBudget);
+    if (turnBudgetResult.turnBudget) {
+      childTask = appendTurnBudgetSystemPrompt(task, turnBudgetResult.turnBudget);
+    }
+
+    // Boundary instructions (plain or fanout child).
+    childTask = withChildBoundaryInstructions(childTask, agent);
+
+    const result = await deps.spawnForeground(ctx, agentName, childTask, {
+      description: (params.label as string | undefined) ?? key,
+      maxTurns: (params.maxTurns as number | undefined) ?? (turnBudgetResult.turnBudget?.maxTurns),
+      modelInput: (params.model as string | undefined) ?? agent.model,
+      thinkingLevel: agent.thinking,
+      signal: childSignal,
+    });
+
+    return {
+      key,
+      ok: result.ok,
+      output: result.output,
+      ...(result.error ? { error: result.error } : {}),
+      ...(agentName ? { agent: agentName } : {}),
+      artifactPaths: [],
+    };
+  };
+
+  const status = async (keyOrRunId: string): Promise<WorkflowScriptChildResult> => {
+    const record = deps.manager.getRecord(keyOrRunId);
+    if (record) {
+      return {
+        key: keyOrRunId,
+        ok: record.status === "completed",
+        output: record.result ?? record.status,
+        ...(record.error ? { error: record.error } : {}),
+        artifactPaths: [],
+      };
+    }
+    return { key: keyOrRunId, ok: true, output: "ok", artifactPaths: [] };
+  };
+
+  try {
+    const result = await runWorkflowScript({
+      script,
+      timeoutMs: args.timeoutMs as number | undefined,
+      signal,
+      admit,
+      launch,
+      status,
+    });
+
+    const maxOutput = resolveMaxOutput(args.maxOutput as never, deps.config);
+    const summary =
+      typeof result.value === "string"
+        ? result.value
+        : JSON.stringify(result.value, null, 2) ?? "null";
+    const truncated = truncateOutput(summary, maxOutput);
+    return textResult(truncated.text, {
+      status: "completed",
+      children: result.children.length,
+      fanout: formatRunFanoutBudget(getRunFanoutBudgetSnapshot(budget)),
+      truncated: truncated.truncated,
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "WorkflowScriptError") {
+      const partial = (error as { partial?: { children?: unknown[] } }).partial;
+      return textResult(
+        `Workflow failed: ${error.message}`,
+        { status: "error", children: partial?.children?.length ?? 0 },
+      );
+    }
+    throw error;
+  }
+}
+
+// ============================================================================
+// Single-child launch (legacy + reference)
+// ============================================================================
+
+async function handleSingleChild(
+  deps: HandlerDeps,
+  ctx: ExtensionContext,
+  args: Record<string, unknown>,
+  signal: AbortSignal | undefined,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
+  const pre = preflight(deps, args);
+  if (!pre.ok) return textResult(pre.error, { status: "error" });
+
+  const { agent, agentName, prompt } = pre;
+  const asyncRequested =
+    (args.async as boolean | undefined) ??
+    (args.run_in_background as boolean | undefined) ??
+    agent.runInBackground ??
+    false;
+
+  // Context policy. EXPLICIT fork never silently downgrades (reference rule);
+  // implicit fork (agent/config default) falls back to fresh when the in-process
+  // path cannot fork (reference: implicit fork needs a persisted parent session,
+  // else fresh).
+  const explicitContext = args.context as string | undefined;
+  const contextMode = resolveContext(explicitContext, agent, deps.config);
+  if (contextMode === "fork" && (explicitContext === "fork" || deps.config.defaultSubagentContext === "fork")) {
+    if (!asyncRequested) {
+      return textResult(
+        'context: "fork" requires background execution (run_in_background: true); the in-process foreground path is fresh-context only.',
+        { status: "error" },
+      );
+    }
+    if (!deps.runAsync) {
+      return textResult(
+        'context: "fork" requires the background process runner, which is unavailable in this host. Re-run without context, or use context: "fresh".',
+        { status: "error" },
+      );
+    }
+  }
+
+  // Budgets: validate + decorate.
+  let childPrompt = prompt;
+  const turnBudgetResult = resolveTurnBudgetConfig(args.turnBudget);
+  if (turnBudgetResult.error) return textResult(turnBudgetResult.error, { status: "error" });
+  if (turnBudgetResult.turnBudget) {
+    childPrompt = appendTurnBudgetSystemPrompt(childPrompt, turnBudgetResult.turnBudget);
+  }
+  const toolBudgetResult = validateToolBudgetConfig(args.toolBudget);
+  if (toolBudgetResult.error) return textResult(toolBudgetResult.error, { status: "error" });
+  const usageBudgetResult = validateUsageBudgetConfig(args.usageBudget);
+  if (usageBudgetResult.error) return textResult(usageBudgetResult.error, { status: "error" });
+
+  // Acceptance gates (gate shorthand + acceptance object).
+  const acceptanceResolved = resolveEffectiveAcceptance(args);
+  if (!acceptanceResolved.ok) return textResult(acceptanceResolved.error, { status: "error" });
+
+  // Boundary instructions (unless the agent is a fanout child).
+  if (!isFanoutChild(agent)) {
+    childPrompt = withChildBoundaryInstructions(childPrompt, agent);
+  }
+
+  // Session spawn budget.
+  const sessionAccounting = deps.spawnAccounting;
+  if (sessionAccounting) {
+    const cap = sessionAccounting.cap();
+    if (cap !== undefined && sessionAccounting.used() >= cap) {
+      return textResult(
+        `Session spawn budget exhausted: ${sessionAccounting.used()}/${cap} used. ` +
+          `Use spawn_helper ({ action: "grant-spawn-budget", additional: N }) from the interactive parent to extend.`,
+        { status: "error" },
+      );
+    }
+    sessionAccounting.consume(1);
+  }
+
+  const description = (args.description as string | undefined) ?? `${agentName} task`;
+
+  if (asyncRequested) {
+    // Fork context requires the process runner; fresh background runs prefer
+    // it too when available (survives parent exit), else fall back in-process.
+    const wantsProcessRunner = contextMode === "fork" || deps.config.asyncByDefault === true;
+    if (deps.runAsync && (contextMode === "fork" || wantsProcessRunner)) {
+      const result = await deps.runAsync({
+        agentName,
+        task: childPrompt,
+        description,
+        model: (args.model as string | undefined) ?? agent.model,
+        thinking: (args.thinking as string | undefined) ?? (typeof agent.thinking === "string" ? agent.thinking : undefined),
+        context: contextMode,
+        timeoutMs: (args.timeoutMs as number | undefined) ?? agent.timeoutMs,
+        maxTurns: (args.max_turns as number | undefined) ?? (args.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
+      });
+      return textResult(
+        `Agent started in background (process mode).\nRun ID: ${result.runId}\nType: ${agentName}\nDescription: ${description}\n\nYou will be notified when this agent completes.\nUse get_helper_result with the run ID to retrieve results.`,
+        { status: "background", runId: result.runId, agentId: result.runId },
+      );
+    }
+    const id = deps.spawnBackground(ctx, agentName, childPrompt, {
+      description,
+      maxTurns: (args.max_turns as number | undefined) ?? (args.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
+      modelInput: (args.model as string | undefined) ?? agent.model,
+      thinkingLevel: args.thinking ?? agent.thinking,
+    });
+    return textResult(
+      `Agent started in background.\nID: ${id}\nType: ${agentName}\nDescription: ${description}\n\nYou will be notified when this agent completes.\nUse get_helper_result to retrieve full results.`,
+      { status: "background", agentId: id },
+    );
+  }
+
+  const result = await deps.spawnForeground(ctx, agentName, childPrompt, {
+    description,
+    maxTurns: (args.max_turns as number | undefined) ?? (args.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
+    modelInput: (args.model as string | undefined) ?? agent.model,
+    thinkingLevel: args.thinking ?? agent.thinking,
+    signal,
+  });
+
+  if (!result.ok) {
+    return textResult(`Agent failed: ${result.error ?? result.output}`, {
+      status: "error",
+      error: result.error,
+      toolUses: result.toolUses,
+      durationMs: result.durationMs,
+    });
+  }
+
+  // Acceptance gate evaluation (host-side verify commands + report checks).
+  let finalOutput = result.output;
+  let ledgerDetails: unknown;
+  if (acceptanceResolved.acceptance) {
+    const evaluated = await evaluateRunAcceptance(acceptanceResolved.acceptance, result.output, process.cwd());
+    finalOutput = evaluated.output;
+    ledgerDetails = evaluated.ledger;
+    if (evaluated.ledger?.status === "rejected") {
+      return textResult(
+        `Agent completed but acceptance rejected:\n${evaluated.ledger.failureMessage}\n\nOutput:\n${finalOutput.slice(0, 2000)}`,
+        { status: "error", acceptance: evaluated.ledger.status, failureMessage: evaluated.ledger.failureMessage },
+      );
+    }
+  }
+
+  // Output truncation with maxOutput config (reference default 200KB/5000 lines).
+  const maxOutput = resolveMaxOutput(args.maxOutput as never, deps.config);
+  const truncated = truncateOutput(finalOutput, maxOutput);
+
+  return textResult(
+    `Agent completed in ${(result.durationMs / 1000).toFixed(1)}s (${result.toolUses} tool uses).\n\n${truncated.text}`,
+    {
+      status: "completed",
+      toolUses: result.toolUses,
+      durationMs: result.durationMs,
+      ...(ledgerDetails ? { acceptance: (ledgerDetails as { status: string }).status } : {}),
+      truncated: truncated.truncated,
+      originalBytes: truncated.originalBytes,
+    },
+  );
+}
+
+
+// ============================================================================
+// Async workflowScript (process-backed children)
+// ============================================================================
+
+/**
+ * Run a workflow with every child launched through the process runner
+ * (child pi processes). The workflow runtime is identical; only the launch
+ * transport differs. The tool call blocks until the workflow settles — the
+ * parent gets the full result. (Fully detached async workflows with live
+ * status polling land with the Phase 4 fleet work.)
+ */
+async function handleAsyncWorkflowScript(
+  deps: HandlerDeps,
+  ctx: ExtensionContext,
+  script: string,
+  args: Record<string, unknown>,
+  signal: AbortSignal | undefined,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
+  if (!deps.runAsync) {
+    return textResult(
+      "Async workflowScript requires the background process runner, which is unavailable in this host. " +
+        "Re-run with async: false to execute the workflow in-process in the foreground.",
+      { status: "error" },
+    );
+  }
+
+  // Validate call-level budgets up front.
+  if (args.turnBudget !== undefined) {
+    const { error } = resolveTurnBudgetConfig(args.turnBudget);
+    if (error) return textResult(error, { status: "error" });
+  }
+  if (args.toolBudget !== undefined) {
+    const { error } = validateToolBudgetConfig(args.toolBudget);
+    if (error) return textResult(error, { status: "error" });
+  }
+  if (args.usageBudget !== undefined) {
+    const { error } = validateUsageBudgetConfig(args.usageBudget);
+    if (error) return textResult(error, { status: "error" });
+  }
+
+  const perRunCap = deps.config.maxSubagentSpawnsPerRun ?? 64;
+  const budget = createRunFanoutBudget(`workflow-async-${Date.now()}`, perRunCap);
+  const sessionAccounting = deps.spawnAccounting;
+  const sessionCap = sessionAccounting?.cap();
+
+  const admit = (calls: Array<{ key: string; params: Record<string, unknown> }>): void => {
+    if (calls.length === 0) return;
+    claimRunFanoutBatch(budget, calls.map((call) => call.key));
+    if (sessionCap !== undefined && sessionAccounting) {
+      const used = sessionAccounting.used();
+      if (used + calls.length > sessionCap) {
+        throw new Error(
+          `Session spawn budget exhausted: ${used}/${sessionCap} used, ${calls.length} requested.`,
+        );
+      }
+      sessionAccounting.consume(calls.length);
+    }
+  };
+
+  const launch = async (
+    key: string,
+    params: Record<string, unknown>,
+    childSignal: AbortSignal,
+  ): Promise<WorkflowScriptChildResult> => {
+    const agentNameRaw = params.agent as string | undefined;
+    const task = params.task as string | undefined;
+    if (!agentNameRaw || !task) {
+      return { key, ok: false, output: "runs.run requires agent and task.", error: "missing agent/task", artifactPaths: [] };
+    }
+    const agentName = deps.manager.resolveAlias(agentNameRaw);
+    const agent = deps.manager.getAgentConfig(agentName);
+    if (!agent) {
+      return { key, ok: false, output: `Unknown agent "${agentNameRaw}".`, error: "unknown agent", artifactPaths: [] };
+    }
+    if (!deps.manager.isTypeEnabled(agentName)) {
+      return { key, ok: false, output: `Agent "${agentName}" is disabled.`, error: "disabled", artifactPaths: [] };
+    }
+
+    // Context policy: fork children get branched sessions via the process runner.
+    const contextMode = resolveContext(params.context as string | undefined, agent, deps.config);
+
+    let childTask = task;
+    const turnBudgetResult = resolveTurnBudgetConfig(params.turnBudget ?? args.turnBudget);
+    if (turnBudgetResult.turnBudget) {
+      childTask = appendTurnBudgetSystemPrompt(task, turnBudgetResult.turnBudget);
+    }
+    childTask = withChildBoundaryInstructions(childTask, agent);
+
+    try {
+      const worktreeRequested =
+        (params.worktree as boolean | undefined) ??
+        (args.worktree as boolean | undefined) ??
+        (args.isolation === "worktree" ? true : undefined);
+      const result = await deps.runAsync!({
+        agentName,
+        task: childTask,
+        description: (params.label as string | undefined) ?? key,
+        model: (params.model as string | undefined) ?? agent.model,
+        thinking: typeof agent.thinking === "string" ? agent.thinking : undefined,
+        context: contextMode,
+        timeoutMs: (params.timeoutMs as number | undefined) ?? agent.timeoutMs,
+        maxTurns: (params.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
+        ...(worktreeRequested === true ? { worktree: true } : {}),
+      });
+      void childSignal; // process-level abort handled by the runner's controller
+      return {
+        key,
+        ok: result.status === "completed",
+        output: result.output ?? result.error ?? result.status,
+        ...(result.error ? { error: result.error } : {}),
+        agent: agentName,
+        ...(result.runId ? { runId: result.runId } : {}),
+        artifactPaths: [],
+      };
+    } catch (error) {
+      const text = error instanceof Error ? error.message : String(error);
+      return { key, ok: false, output: text, error: text, artifactPaths: [] };
+    }
+  };
+
+  const status = async (keyOrRunId: string): Promise<WorkflowScriptChildResult> => {
+    const record = deps.manager.getRecord(keyOrRunId);
+    if (record) {
+      return {
+        key: keyOrRunId,
+        ok: record.status === "completed",
+        output: record.result ?? record.status,
+        ...(record.error ? { error: record.error } : {}),
+        artifactPaths: [],
+      };
+    }
+    return { key: keyOrRunId, ok: true, output: "ok", artifactPaths: [] };
+  };
+
+  try {
+    const result = await runWorkflowScript({
+      script,
+      timeoutMs: args.timeoutMs as number | undefined,
+      signal,
+      admit,
+      launch,
+      status,
+    });
+
+    const maxOutput = resolveMaxOutput(args.maxOutput as never, deps.config);
+    const summary =
+      typeof result.value === "string"
+        ? result.value
+        : JSON.stringify(result.value, null, 2) ?? "null";
+    const truncated = truncateOutput(summary, maxOutput);
+    return textResult(truncated.text, {
+      status: "completed",
+      mode: "async-workflow",
+      children: result.children.length,
+      fanout: formatRunFanoutBudget(getRunFanoutBudgetSnapshot(budget)),
+      truncated: truncated.truncated,
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "WorkflowScriptError") {
+      const partial = (error as { partial?: { children?: unknown[] } }).partial;
+      return textResult(
+        `Workflow failed: ${error.message}`,
+        { status: "error", mode: "async-workflow", children: partial?.children?.length ?? 0 },
+      );
+    }
+    throw error;
+  }
+}