@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/agents/runtime.mjs

@@ -0,0 +1,748 @@
+/**
+ * lib/engine/agents/runtime.mjs — running subagents: the Task tool (also named
+ * Agent), TaskOutput, TaskStop, background tasks and their notifications.
+ *
+ * A subagent run is a child loop (loop.mjs) with:
+ *   · a fresh context: its first message is the Task prompt; its system prompt
+ *     is the engine's base prompt, the run's instructions, and the definition's
+ *     own prompt (see `subagentPrompt`);
+ *   · the parent's rules, gates and hooks: its guard is built from the same
+ *     settings, in the STRICTER of the parent's mode and the definition's
+ *     `permissionMode` — a child can never loosen its parent's posture;
+ *   · tools: the definition's list intersected with the parent's tools, minus
+ *     its disallowed tools. A tool with `forChild()` (the session Bash, TodoWrite)
+ *     is given as the child's own copy;
+ *   · a tier from its `model` through the tier map (definitions.mjs);
+ *   · depth: the main run is depth 0 and a child may start children only while
+ *     depth + 1 < maxDepth (default 1: subagents cannot start subagents);
+ *   · attribution headers on every model request: x-cohort-session-id (the main
+ *     session), x-cohort-agent-id (this child), x-cohort-parent-agent-id (the
+ *     main session id, or the agent that started it);
+ *   · SubagentStop hooks consulted before it ends (a blocking hook gives the
+ *     child another turn, exactly as Stop does for the main run); the input adds
+ *     agent_id, agent_type and agent_transcript_path;
+ *   · the permission check repeated on the RESOLVED definition name before a
+ *     child starts (`checkSubagent`), so a padded or unqualified spelling cannot
+ *     pass a `Task(<type>)` deny or ask rule the guard matched by spelling;
+ *   · a sidechain transcript: <sessions>/subagents/<session id>/<agent id>.jsonl,
+ *     whose header record carries isSidechain, parentSessionId, parentAgentId,
+ *     parentToolUseId and agentType;
+ *   · a usage record (tier, usage, cost micros, request ids) handed to the owner
+ *     for the parent's result (usage.mjs); permission refusals are added to the
+ *     parent's `permission_denials`. Model calls the child's run makes outside
+ *     its turns (a compaction summary, WebFetch, WebSearch) reach the child
+ *     loop's `recordModelCall`, so they are in that record too;
+ *   · its own context (`prepareChild`, W3 integration): a context manager for
+ *     the child's tier and tools, so a long child compacts on its own, and its
+ *     own deferred-tool state when its MCP tools are deferred;
+ *
+ * Foreground: the Task call returns the child's final text. Background
+ * (`run_in_background`): the call returns a task id at once; when the child
+ * ends, a notification is queued and the loop delivers it as the next user
+ * message (`drainNotifications`). A loop whose model has finished while a
+ * background task is still running waits for it (`awaitNotifications`), within
+ * the run's time limit, so a headless run never ends with unreported work.
+ * TaskOutput {task_id, block?, timeout?} reads a task (or a background shell,
+ * or a workflow run) early; TaskStop {task_id} stops one. A task read or
+ * stopped by the model is not notified again.
+ *
+ * Surviving a restart (W4-E2, conformance row 23). Every task the Task tool
+ * starts keeps its state in <agent id>.state.json beside its transcript
+ * (persist.mjs): definition snapshot, prompt, the mode it was clamped to,
+ * status, final text, whether it was reported. A runtime created for a
+ * continued session reads its session's states back: finished tasks answer
+ * TaskOutput as before, and a task recorded as running by a process that is
+ * gone is `interrupted` — reported once as a notification and by TaskOutput,
+ * with the way to continue it. `Task {resume: <agent id>, prompt}` continues a
+ * task that is not running from its sidechain transcript: the same agent id and
+ * transcript, the definition of that name (or its snapshot), in the stricter of
+ * the mode it ran in and the mode this run would give it, with this run's tools
+ * at most. Workflow `agent()` children are not tasks: a workflow recovers from
+ * its journal (`resumeFromRunId`).
+ *
+ * Tool descriptions are original (see docs/engine/clean-room.md).
+ *
+ * @module lib/engine/agents/runtime
+ */
+
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { runLoop } from "../loop.mjs";
+import { userText } from "../messages.mjs";
+import { classifyStop } from "../output/json.mjs";
+import { appendMessage, appendResult, openSession, sessionPath } from "../session/store.mjs";
+import { AGENT_TOOL_NAMES, DEFAULT_TIER_MAP, childToolNames, clampPermissionMode, findAgent, resolveAgentModel } from "./definitions.mjs";
+import { recordFromOutcome } from "./usage.mjs";
+import { transcriptMessage } from "../context/images.mjs";
+import { resumeHistory } from "../context/compaction.mjs";
+import { TASK_STATE_VERSION, definitionForResume, isAgentId, readTaskState, readTaskStates, reconcileTaskState, subagentDir, taskOwnerState, writeTaskState } from "./persist.mjs";
+import { PROCESS_NONCE, processAlive, processStartToken } from "../process-identity.mjs";
+
+/** Agent ids with a child running in THIS process, whichever runtime started it (a host may rebuild one). */
+const PROCESS_LIVE_TASKS = new Set();
+
+export const DEFAULT_MAX_AGENT_DEPTH = 1;
+export const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30_000;
+export const TASK_OUTPUT_MAX_TIMEOUT_MS = 600_000;
+const STOP_WAIT_MS = 10_000;
+const LISTED_DESCRIPTION_CHARS = 300;
+const WORKFLOW_RUN_ID_RE = /^wf_[0-9a-f]{12}$/;
+
+/**
+ * The part of a child's system prompt that makes it a subagent.
+ * Authorship: written for Cohort Engine by the Cohort team, 2026-09-14.
+ * @param {import('./definitions.mjs').AgentDefinition} def
+ */
+export function subagentPrompt(def) {
+  const own = def.prompt || def.description;
+  return `You are running as the "${def.name}" subagent: another agent handed you one task. It cannot see your working, only your final message, so end with a complete report of what you found or did.\n\n${own}`;
+}
+
+/** @param {import('./definitions.mjs').AgentDefinition[]} agents */
+export function formatAgentListing(agents) {
+  return agents
+    .map((a) => {
+      const d = a.description.length <= LISTED_DESCRIPTION_CHARS ? a.description : `${a.description.slice(0, LISTED_DESCRIPTION_CHARS - 1)}…`;
+      return `- ${a.name}: ${d}`;
+    })
+    .join("\n");
+}
+
+export function newAgentId() {
+  return `agent-${randomBytes(8).toString("hex")}`;
+}
+
+/**
+ * How the model continues an interrupted or finished task (pure).
+ * @param {string} id
+ */
+export function resumeHint(id) {
+  return `Task {"resume":"${id}","description":"<a short label>","prompt":"<what to do next>"} continues it from its transcript.`;
+}
+
+/**
+ * @typedef {Object} WorkflowRuns  the session's workflow runtime, as TaskOutput and TaskStop use it
+ * @property {(runId:string) => boolean} has
+ * @property {(runId:string, o:{block?:boolean, timeoutMs?:number, signal?:AbortSignal}) => Promise<any>} status
+ * @property {(runId:string) => Promise<{ok:true, content:string}|{ok:false, error:string}>} stop
+ * @property {(runId:string) => ({ok:true, content:string, running:boolean}|{ok:false, error:string})} [diskStatus]
+ */
+
+/**
+ * @typedef {Object} AgentRuntimeDeps
+ * @property {import('./definitions.mjs').AgentDefinition[]} agents
+ * @property {string} sessionId
+ * @property {string} sessionsDir
+ * @property {string} cwd
+ * @property {string} wire
+ * @property {string} parentModel      the tier of the run that owns this runtime
+ * @property {string} parentMode
+ * @property {string} parentAgentId    the session id at depth 0
+ * @property {number} [depth]
+ * @property {number} [maxDepth]
+ * @property {(o:{model:string, headers:Record<string,string>, parentToolUseId:string|null}) => (turn:any)=>Promise<any>} createCaller
+ * @property {(o:{mode:string, agentId?:string, cwd?:string}) => any} createGuard
+ * @property {(o:{def:import('./definitions.mjs').AgentDefinition, toolNames:string[], notes?:string|null}) => string} buildSystem
+ * @property {(o:{headers:Record<string,string>, agentId:string}) => any} createToolContext  the child's tool context; web tools attribute their requests with `headers`
+ * @property {(o:{def:import('./definitions.mjs').AgentDefinition, model:string, tools:any[], headers:Record<string,string>, agentId:string, parentToolUseId:string|null, onCompact:(message:any)=>void}) => ({tools:any[], sent:any[], notes:string|null, context:any}|null)} [prepareChild]
+ *           the child's tool list (ToolSearch bound to its own state), the tools whose definitions are sent,
+ *           system-prompt notes and the loop's `context`; null = the tools as given, no context manager
+ * @property {any} [hooks]
+ * @property {(message:any, o:{parentToolUseId:string|null, agentId:string}) => void} [onMessage]
+ * @property {(denials:any[], meta:{turn:number|null}) => void} [onDenials]  `turn`: `currentTurn()` when the child started
+ * @property {() => number} [currentTurn]
+ * @property {(o:{toolName:string, input:any, mode:string}) => {behavior:'allow'|'deny'|'ask', reason:string}} [checkSubagent]
+ *           the owner's permission evaluation for a Task call (permissions.mjs evaluatePermission)
+ * @property {(record:any) => void} [onRecord]
+ * @property {() => void} [onNotify]  a background task's notification was queued (W4-A1: wakes an idle `cohort session`)
+ * @property {(line:string) => void} [log]
+ * @property {Record<string,string>} [tierMap]
+ * @property {number} [maxTurns]
+ * @property {import('../budget.mjs').BudgetMeter|null} [budget]  the run's spend cap, shared with every child (W4-E1)
+ * @property {number} [wallClockMs]
+ * @property {() => number} [now]
+ * @property {{has:(id:string)=>boolean, read:(id:string, f?:string)=>any, wait:(id:string, ms:number, s?:AbortSignal)=>Promise<void>, kill:(id:string)=>Promise<any>}|null} [shells]
+ * @property {number} [pid]                              this process (default process.pid): recorded in task states
+ * @property {string} [nonce]                            this process's nonce (default process-identity.mjs PROCESS_NONCE)
+ * @property {(pid:number) => boolean} [isProcessAlive]  whether a restored running task's process still lives
+ * @property {(pid:number) => string|null} [processStartToken]  the OS start time of a PID, to catch a reused PID
+ * @property {boolean} [restore]                         read the session's task states back (default: at depth 0)
+ */
+
+/**
+ * @typedef {Object} BackgroundTask
+ * @property {string} id
+ * @property {string} agentType
+ * @property {string} description
+ * @property {'running'|'completed'|'failed'|'stopped'|'interrupted'} status
+ * @property {string} text
+ * @property {string|null} error
+ * @property {boolean} notified
+ * @property {boolean} stopRequested
+ * @property {AbortController} controller
+ * @property {Promise<void>} done
+ * @property {boolean} background
+ * @property {import('./persist.mjs').TaskState|null} state   what is kept on disk
+ * @property {boolean} elsewhere   restored as running in another live process: not this run's to wait for or stop
+ */
+
+/** @param {AgentRuntimeDeps} d */
+export function createAgentRuntime(d) {
+  const depth = d.depth ?? 0;
+  const maxDepth = d.maxDepth ?? DEFAULT_MAX_AGENT_DEPTH;
+  const now = d.now ?? Date.now;
+  const pid = d.pid ?? process.pid;
+  const nonce = d.nonce ?? PROCESS_NONCE;
+  const isAlive = d.isProcessAlive ?? processAlive;
+  const startTokenOf = d.processStartToken ?? processStartToken;
+  /** How a recorded owner is judged (W4-E2 review: PID, nonce and start time, not the PID alone). */
+  const ownerCheck = { self: { pid, nonce }, probe: { isAlive, startToken: startTokenOf }, heldHere: (/** @type string */ agentId) => PROCESS_LIVE_TASKS.has(agentId) };
+  const iso = () => new Date(now()).toISOString();
+  const canSpawn = depth + 1 < maxDepth;
+  /** @type {Map<string, BackgroundTask>} */
+  const tasks = new Map();
+  /** Agent ids with a child running in this process (foreground or background). */
+  const live = new Set();
+  /** @type {Array<{taskId:string, text:string}>} */
+  const queue = [];
+  /** @type {Set<() => void>} */
+  const waiters = new Set();
+  /** Usage records of finished children (this runtime's and nested ones). */
+  const records = [];
+  /** @type {() => any[]} */
+  let parentTools = () => [];
+  /** @type {WorkflowRuns|null} */
+  let workflowRuns = null;
+  let saveFailureLogged = false;
+
+  const addRecord = (/** @type any */ r) => {
+    records.push(r);
+    d.onRecord?.(r);
+  };
+  const wake = () => {
+    for (const w of [...waiters]) w();
+    waiters.clear();
+  };
+  /** A task this run is responsible for waiting on and stopping: one it holds a live child for. @param {BackgroundTask} t */
+  const runningHere = (t) => t.status === "running" && !t.elsewhere && live.has(t.id);
+  /** @param {string} id */
+  const hold = (id) => {
+    live.add(id);
+    PROCESS_LIVE_TASKS.add(id);
+  };
+  /** @param {string} id */
+  const release = (id) => {
+    live.delete(id);
+    PROCESS_LIVE_TASKS.delete(id);
+  };
+  /** Where a task restored as running is running, for the model. @param {BackgroundTask} t */
+  const elsewhereText = (t) => (t.state?.pid === pid ? "in another session runtime of this engine process" : `in another engine process (pid ${t.state?.pid})`);
+
+  /** Write a task's state (W4-E2). A failed write is logged once and costs only recoverability. @param {BackgroundTask} t */
+  const save = (t) => {
+    if (!t.state) return;
+    t.state = { ...t.state, status: t.status, text: t.text, error: t.error, notified: t.notified, endedAt: t.status === "running" ? null : (t.state.endedAt ?? iso()) };
+    if (!writeTaskState(d.sessionsDir, t.state) && !saveFailureLogged) {
+      saveFailureLogged = true;
+      d.log?.(`subagent ${t.agentType}: its state could not be written under ${subagentDir(d.sessionsDir, d.sessionId)}; it will not be recoverable after a restart`);
+    }
+  };
+
+  /**
+   * W4-A2 (workflow children): `extraTools` are added to the child's tools after the definition's
+   * filter (a StructuredOutput tool); `effort` overrides the run's --effort for this child; `cwd`
+   * runs the child in another directory (a git worktree) — its tools, guard, prompt and Bash.
+   * W4-E2: `resume` continues the child's existing transcript (its history is the child's
+   * conversation so far, then `prompt`); `ceilingMode` clamps the child's mode further.
+   * @param {{def:import('./definitions.mjs').AgentDefinition, prompt:string, description:string, parentToolUseId:string|null, signal?:AbortSignal, agentId?:string, background:boolean, extraTools?:any[], effort?:string|null, cwd?:string|null, resume?:boolean, ceilingMode?:string|null}} p
+   * @returns {Promise<{ok:boolean, agentId:string, text:string, error:string|null, stopKind:string, record:any}>}
+   */
+  async function runChild({ def, prompt, description, parentToolUseId, signal, agentId = newAgentId(), background, extraTools = [], effort = null, cwd = null, resume = false, ceilingMode = null }) {
+    const at = cwd ? { cwd } : {};
+    const turn = d.currentTurn ? d.currentTurn() : null;
+    const { model, note } = resolveAgentModel(def.model, d.parentModel, d.tierMap ?? DEFAULT_TIER_MAP);
+    if (note) d.log?.(`subagent ${def.name}: ${note}`);
+    const clamped = clampPermissionMode(d.parentMode, def.permissionMode);
+    const mode = ceilingMode ? clampPermissionMode(clamped, ceilingMode) : clamped;
+
+    const opened = openSession({
+      dir: subagentDir(d.sessionsDir, d.sessionId),
+      sessionId: agentId,
+      mode: resume ? "resume" : "new",
+      meta: { cwd: cwd ?? d.cwd, model, wire: d.wire, isSidechain: true, parentSessionId: d.sessionId, parentAgentId: d.parentAgentId, parentToolUseId, agentType: def.name, description, background },
+      now,
+    });
+    if (!opened.ok && resume) {
+      return { ok: false, agentId, text: "", error: `its transcript could not be reopened (${opened.error.message})`, stopKind: "error", record: null };
+    }
+    const transcript = opened.ok ? opened.session : null;
+    if (!opened.ok) d.log?.(`subagent ${def.name}: transcript not written (${opened.error.message})`);
+    const history = resume && transcript ? resumeHistory(transcript.messages) : [];
+
+    const available = parentTools();
+    const { names, missing } = childToolNames(available.map((t) => t.name), def, { canSpawn });
+    if (missing.length) d.log?.(`subagent ${def.name}: not available to it (the parent does not have them): ${missing.join(", ")}`);
+
+    const nested = canSpawn && names.some((n) => AGENT_TOOL_NAMES.includes(n))
+      ? createAgentRuntime({ ...d, depth: depth + 1, parentModel: model, parentMode: mode, parentAgentId: agentId, onRecord: addRecord, onDenials: d.onDenials, restore: false })
+      : null;
+    const nestedTools = new Map((nested?.tools() ?? []).map((t) => [t.name, t]));
+    const granted = names
+      .map((n) => {
+        if (AGENT_TOOL_NAMES.includes(n)) return nestedTools.get(n);
+        const t = available.find((x) => x.name === n);
+        return typeof t?.forChild === "function" ? t.forChild(cwd ? { cwd } : undefined) : t;
+      })
+      .filter(Boolean);
+    granted.push(...extraTools);
+
+    const headers = { "x-cohort-surface": "engine", "x-cohort-session-id": d.sessionId, "x-cohort-agent-id": agentId, "x-cohort-parent-agent-id": d.parentAgentId };
+    const callModel = d.createCaller({ model, headers, parentToolUseId, ...(effort ? { effort } : {}) });
+    const guard = d.createGuard({ mode, agentId, ...at });
+
+    const first = userText(prompt);
+    if (transcript) appendMessage(transcript, first, now);
+
+    // The child's own context: tools (with its own ToolSearch state), the definitions it is sent, a context manager.
+    const prepared = d.prepareChild
+      ? d.prepareChild({ def, model, tools: granted, headers, agentId, parentToolUseId, onCompact: (m) => transcript && appendMessage(transcript, transcriptMessage(m), now) })
+      : null;
+    const tools = prepared?.tools ?? granted;
+    nested?.setParentTools(() => tools);
+    const system = d.buildSystem({ def, toolNames: (prepared?.sent ?? tools).map((t) => t.name), notes: prepared?.notes ?? null, ...at });
+
+    let outcome;
+    try {
+      outcome = await runLoop({
+        callModel,
+        system,
+        messages: [...history, first],
+        tools,
+        toolContext: d.createToolContext({ headers, agentId, ...at }),
+        maxTurns: def.maxTurns ?? d.maxTurns,
+        wallClockMs: d.wallClockMs,
+        signal,
+        now,
+        guard,
+        onMessage: (m) => {
+          if (transcript) appendMessage(transcript, transcriptMessage(m), now);
+          d.onMessage?.(m, { parentToolUseId, agentId });
+        },
+        onStop: d.hooks ? ({ stopHookActive }) => d.hooks.stop({ stopHookActive, event: "SubagentStop", fields: { agent_id: agentId, agent_type: def.name, agent_transcript_path: transcript?.path ?? null } }) : undefined,
+        drainNotifications: nested?.drainNotifications,
+        awaitNotifications: nested?.awaitNotifications,
+        context: prepared?.context ?? null,
+        // W4-E1 (row 24): the run's --max-budget-usd meter, shared by every child.
+        budget: d.budget ?? null,
+      });
+    } finally {
+      if (nested) await nested.stopAll();
+      if (guard.denials.length) d.onDenials?.(guard.denials, { turn });
+    }
+
+    const record = { ...recordFromOutcome(outcome, model), agentId, agentType: def.name, background, stop: outcome.stop.kind, numTurns: outcome.numTurns };
+    addRecord(record);
+    const c = classifyStop(outcome.stop);
+    if (transcript) {
+      appendResult(
+        transcript,
+        { type: "result", subtype: c.subtype, is_error: c.isError, result: c.isError ? c.message : outcome.resultText, agent_id: agentId, num_turns: outcome.numTurns, cohort: { modelTier: record.tier, costMicros: record.costMicros, usage: record.usage, requestIds: record.requestIds, stop: outcome.stop.kind } },
+        now,
+      );
+    }
+    return { ok: !c.isError, agentId, text: outcome.resultText, error: c.message, stopKind: outcome.stop.kind, record };
+  }
+
+  /** @param {BackgroundTask} t */
+  const notificationText = (t) => {
+    const kind = t.background ? "Background task" : "Task";
+    if (t.status === "completed") return `[${kind} ${t.id} finished] The ${t.agentType} subagent working on "${t.description}" completed. Its report:\n\n${t.text || "(no final message)"}`;
+    if (t.status === "interrupted") return `[${kind} ${t.id} interrupted] The ${t.agentType} subagent working on "${t.description}" did not finish: ${t.error ?? "the engine stopped"}.${t.text ? `\n\nIts last message:\n${t.text}` : ""}\n\n${resumeHint(t.id)}`;
+    return `[${kind} ${t.id} ended] The ${t.agentType} subagent working on "${t.description}" did not finish: ${t.error ?? "unknown error"}${t.text ? `\n\nIts last message:\n${t.text}` : ""}`;
+  };
+
+  /** @param {BackgroundTask} t */
+  const consume = (t) => {
+    t.notified = true;
+    const i = queue.findIndex((q) => q.taskId === t.id);
+    if (i !== -1) queue.splice(i, 1);
+    save(t);
+  };
+
+  // ── W4-E2: the session's earlier tasks, read back when the session is continued ──
+  if (d.restore ?? depth === 0) {
+    const { states, errors } = readTaskStates(d.sessionsDir, d.sessionId);
+    for (const e of errors) d.log?.(`subagent state ${e}`);
+    for (const s0 of states) {
+      if (s0.parentAgentId !== d.parentAgentId) continue;
+      const { state, changed, elsewhere } = reconcileTaskState(s0, { ...ownerCheck, now: iso() });
+      /** @type {BackgroundTask} */
+      const t = { id: state.agentId, agentType: state.agentType, description: state.description, status: state.status, text: state.text ?? "", error: state.error ?? null, notified: state.notified === true, stopRequested: false, controller: new AbortController(), done: Promise.resolve(), background: state.background === true, state, elsewhere };
+      tasks.set(t.id, t);
+      if (changed) save(t);
+      // Reported once: a task cut off by the restart, and a background report the old process never delivered.
+      if (!t.notified && (t.status === "interrupted" || (t.background && (t.status === "completed" || t.status === "failed")))) queue.push({ taskId: t.id, text: notificationText(t) });
+    }
+  }
+
+  const taskSchema = {
+    type: "object",
+    properties: {
+      description: { type: "string", description: "A short label for the task (three to five words)." },
+      prompt: { type: "string", description: "The complete task for the subagent, with everything it needs to know. With `resume`, what it should do next." },
+      subagent_type: { type: "string", description: "Which subagent to use, from the listed types. Not needed with `resume`." },
+      run_in_background: { type: "boolean", description: "Return a task id at once; the report arrives in a later message." },
+      resume: { type: "string", description: "The id of an earlier task of this session that is not running (finished, stopped or interrupted): continue that subagent from its transcript." },
+    },
+    required: ["description", "prompt"],
+  };
+
+  /**
+   * Check a `resume` request (W4-E2).
+   * @param {string} id @param {any} input
+   * @returns {{ok:true, def:import('./definitions.mjs').AgentDefinition, state:import('./persist.mjs').TaskState}|{ok:false, error:string}}
+   */
+  const prepareResume = (id, input) => {
+    if (!isAgentId(id)) return { ok: false, error: `resume takes the id of an earlier task (agent- and 16 hex digits), got "${id}".` };
+    if (live.has(id)) return { ok: false, error: `Task ${id} is still running; read it with TaskOutput or stop it with TaskStop before resuming it.` };
+    const state = readTaskState(d.sessionsDir, d.sessionId, id);
+    if (!state || state.parentAgentId !== d.parentAgentId) return { ok: false, error: `There is no task ${id} of this session to resume.` };
+    if (state.status === "running") {
+      const where = taskOwnerState(state, ownerCheck);
+      if (where === "elsewhere") return { ok: false, error: `Task ${id} is still running in another engine process (pid ${state.pid}); it cannot be resumed from here.` };
+      if (where === "here-elsewhere") return { ok: false, error: `Task ${id} is still running in another session runtime of this engine process; it cannot be resumed from here.` };
+    }
+    const def = definitionForResume(state, d.agents, findAgent);
+    if (typeof input.subagent_type === "string" && input.subagent_type.trim() !== "") {
+      const f = findAgent(d.agents, input.subagent_type);
+      const asked = f.ok ? f.agent.name : input.subagent_type.trim();
+      if (asked !== state.agentType) return { ok: false, error: `Task ${id} is a ${state.agentType} subagent; resume it without subagent_type, or with that type (got "${input.subagent_type}").` };
+    }
+    return { ok: true, def, state };
+  };
+
+  /** @param {'Task'|'Agent'} name */
+  const startTool = (name) => ({
+    name,
+    // Starting a subagent changes nothing by itself: every call the subagent
+    // makes passes the same guard. Several subagents in one reply run together.
+    readOnly: true,
+    description:
+      name === "Task"
+        ? "Hand a self-contained piece of work to a subagent. It runs with a fresh context and its own tools, and returns one final report, which becomes this call's result. " +
+          "It cannot see this conversation: put everything it needs in `prompt`. Several Task calls in one reply run at the same time. " +
+          "With `run_in_background` the call returns a task id at once and the report arrives in a later message (TaskOutput reads it earlier, TaskStop stops it). " +
+          "`resume` with an earlier task's id continues that subagent, with its conversation so far, on a new `prompt`.\n\n" +
+          `Subagent types:\n${formatAgentListing(d.agents)}`
+        : "The same tool as Task under another name: start a subagent with a fresh context and receive its final report. See Task for the subagent types.",
+    input_schema: taskSchema,
+    /** @param {{description:string, prompt:string, subagent_type?:string, run_in_background?:boolean, resume?:string}} input @param {any} ctx */
+    async run(input, ctx) {
+      /** @type {import('./definitions.mjs').AgentDefinition} */
+      let def;
+      /** @type {import('./persist.mjs').TaskState|null} */
+      let resumeState = null;
+      if (typeof input.resume === "string" && input.resume.trim() !== "") {
+        const r = prepareResume(input.resume.trim(), input);
+        if (!r.ok) return r;
+        def = r.def;
+        resumeState = r.state;
+      } else {
+        if (typeof input.subagent_type !== "string" || input.subagent_type.trim() === "") return { ok: false, error: "subagent_type is required (or resume, with the id of an earlier task)." };
+        const found = findAgent(d.agents, input.subagent_type);
+        if (!found.ok) return { ok: false, error: found.error };
+        def = found.agent;
+      }
+      const parentToolUseId = ctx?.toolUseId ?? null;
+      if (d.checkSubagent) {
+        const v = d.checkSubagent({ toolName: name, input: { ...input, subagent_type: def.name }, mode: d.parentMode });
+        if (v.behavior !== "allow") {
+          d.onDenials?.([{ tool_name: name, tool_use_id: parentToolUseId ?? "", tool_input: input }], { turn: d.currentTurn ? d.currentTurn() : null });
+          return { ok: false, error: `Permission denied: the ${def.name} subagent ${v.behavior === "deny" ? "is refused" : "needs approval, which this run cannot ask for"} (${v.reason}).` };
+        }
+      }
+
+      const background = Boolean(input.run_in_background);
+      const id = resumeState?.agentId ?? newAgentId();
+      const description = typeof input.description === "string" && input.description.trim() !== "" ? input.description : (resumeState?.description ?? def.name);
+      // The mode this child runs in; a resumed child never runs looser than it did before.
+      const clamped = clampPermissionMode(d.parentMode, def.permissionMode);
+      const ceiling = resumeState ? clampPermissionMode(clamped, resumeState.mode) : clamped;
+      const { model } = resolveAgentModel(def.model, d.parentModel, d.tierMap ?? DEFAULT_TIER_MAP);
+      const controller = new AbortController();
+      /** @type {BackgroundTask} */
+      const task = {
+        id,
+        agentType: def.name,
+        description,
+        status: "running",
+        text: "",
+        error: null,
+        notified: false,
+        stopRequested: false,
+        controller,
+        done: Promise.resolve(),
+        background,
+        elsewhere: false,
+        state: {
+          version: TASK_STATE_VERSION,
+          agentId: id,
+          sessionId: d.sessionId,
+          parentAgentId: d.parentAgentId,
+          parentToolUseId,
+          agentType: def.name,
+          definition: { ...def },
+          description,
+          prompt: resumeState?.prompt ?? input.prompt,
+          lastPrompt: resumeState ? input.prompt : null,
+          mode: ceiling,
+          model,
+          background,
+          transcriptPath: sessionPath(subagentDir(d.sessionsDir, d.sessionId), id),
+          status: "running",
+          text: "",
+          error: null,
+          notified: false,
+          pid,
+          nonce,
+          startToken: startTokenOf(pid),
+          resumes: resumeState ? (resumeState.resumes ?? 0) + 1 : 0,
+          startedAt: resumeState?.startedAt ?? iso(),
+          endedAt: null,
+        },
+      };
+      // A resumed task's restored entry is replaced by the running one (its notification, if queued, is dropped).
+      const earlier = tasks.get(id);
+      if (earlier) {
+        const i = queue.findIndex((q) => q.taskId === id);
+        if (i !== -1) queue.splice(i, 1);
+        tasks.delete(id);
+      }
+      hold(id);
+      save(task);
+      const child = { def, prompt: input.prompt, description, parentToolUseId, agentId: id, background, resume: Boolean(resumeState), ceilingMode: ceiling };
+      const resumedNote = resumeState ? ` (resumed from its transcript)` : "";
+
+      if (!background) {
+        /** @type {Awaited<ReturnType<typeof runChild>>} */
+        let r;
+        try {
+          r = await runChild({ ...child, signal: ctx?.signal });
+        } catch (e) {
+          task.status = "failed";
+          task.error = `the subagent failed unexpectedly (${e instanceof Error ? e.message : e})`;
+          throw e;
+        } finally {
+          release(id);
+          if (task.status === "running") {
+            task.text = r?.text ?? "";
+            task.error = r?.ok ? null : (r?.error ?? null);
+            task.status = r?.ok ? "completed" : ctx?.signal?.aborted ? "stopped" : "failed";
+          }
+          task.notified = true; // its result is this call's result
+          tasks.set(id, task);
+          save(task);
+        }
+        if (r.ok) return { ok: true, content: `${resumeState ? `[Task ${id}${resumedNote}]\n\n` : ""}${r.text || "(the subagent finished without a final message)"}` };
+        return { ok: false, error: `The ${def.name} subagent${resumeState ? ` (task ${id}, resumed)` : ""} did not finish: ${r.error}${r.text ? `\n\nIts last message:\n${r.text}` : ""}` };
+      }
+
+      const outer = /** @type {AbortSignal|undefined} */ (ctx?.signal);
+      const onOuter = () => controller.abort();
+      if (outer?.aborted) controller.abort();
+      else outer?.addEventListener("abort", onOuter, { once: true });
+      tasks.set(id, task);
+      task.done = runChild({ ...child, signal: controller.signal })
+        .then(
+          (r) => {
+            task.text = r.text;
+            task.error = r.ok ? null : r.error;
+            task.status = task.stopRequested ? "stopped" : r.ok ? "completed" : "failed";
+          },
+          (e) => {
+            task.error = `the subagent failed unexpectedly (${e instanceof Error ? e.message : e})`;
+            task.status = task.stopRequested ? "stopped" : "failed";
+          },
+        )
+        .finally(() => {
+          outer?.removeEventListener("abort", onOuter);
+          release(id);
+          if (!task.notified && task.status !== "stopped") {
+            queue.push({ taskId: id, text: notificationText(task) });
+            d.onNotify?.();
+          }
+          save(task);
+          wake();
+        });
+      return {
+        ok: true,
+        content: `${resumeState ? "Resumed" : "Started"} background task ${id}: the ${def.name} subagent is working on "${description}"${resumedNote}. Its report arrives in a later message when it finishes. TaskOutput {"task_id":"${id}"} waits for it or reads it early; TaskStop {"task_id":"${id}"} stops it.`,
+      };
+    },
+  });
+
+  /** TaskOutput for a workflow run id (W4-E2). @param {string} runId @param {boolean} block @param {number} ms @param {AbortSignal} [signal] */
+  const workflowOutput = async (runId, block, ms, signal) => {
+    if (workflowRuns?.has(runId)) {
+      const r = await workflowRuns.status(runId, { block, timeoutMs: ms, signal });
+      if (!r.ok) return r;
+      const v = r.view;
+      return { ok: true, content: `Workflow ${runId} ("${v.name}") is ${v.status}.\n\n${JSON.stringify(v, null, 2)}${r.result !== null ? `\n\nResult:\n${r.result}` : ""}` };
+    }
+    const disk = workflowRuns?.diskStatus?.(runId);
+    return disk && disk.ok ? { ok: true, content: disk.content } : null;
+  };
+
+  const outputTool = {
+    name: "TaskOutput",
+    readOnly: true,
+    description:
+      "Read the result of a background task: a subagent started with run_in_background, a background shell, or a workflow run (its wf_ id). With `block` (the default) it waits until the task ends or `timeout` milliseconds pass " +
+      `(default ${TASK_OUTPUT_DEFAULT_TIMEOUT_MS}). A task read here is not reported again later. A subagent task that was interrupted by an engine restart says how to resume it.`,
+    input_schema: {
+      type: "object",
+      properties: {
+        task_id: { type: "string", description: "The task id (or shell id, or workflow run id)." },
+        block: { type: "boolean", description: "Wait for the task to end. Default true." },
+        timeout: { type: "integer", minimum: 0, maximum: TASK_OUTPUT_MAX_TIMEOUT_MS, description: "How long to wait, in milliseconds." },
+      },
+      required: ["task_id"],
+    },
+    /** @param {{task_id:string, block?:boolean, timeout?:number}} input @param {any} ctx */
+    async run(input, ctx) {
+      const ms = Math.min(input.timeout ?? TASK_OUTPUT_DEFAULT_TIMEOUT_MS, TASK_OUTPUT_MAX_TIMEOUT_MS);
+      const block = input.block !== false;
+      const task = tasks.get(input.task_id);
+      if (!task) {
+        if (d.shells?.has(input.task_id)) {
+          if (block) await d.shells.wait(input.task_id, ms, ctx?.signal);
+          const r = d.shells.read(input.task_id);
+          return r.ok ? { ok: true, content: r.content } : r;
+        }
+        if (WORKFLOW_RUN_ID_RE.test(input.task_id)) {
+          const w = await workflowOutput(input.task_id, block, ms, ctx?.signal);
+          if (w) return w;
+        }
+        return { ok: false, error: `There is no background task "${input.task_id}". Known: ${[...tasks.keys()].join(", ") || "none"}.` };
+      }
+      if (task.elsewhere && task.status === "running") return { ok: true, content: `Task ${task.id} (${task.agentType}, "${task.description}") is running ${elsewhereText(task)}; it can be read here once it has ended.` };
+      if (task.status === "running" && block) await waitFor(task.done, ms, ctx?.signal);
+      if (task.status === "running") return { ok: true, content: `Task ${task.id} (${task.agentType}, "${task.description}") is still running.` };
+      consume(task);
+      if (task.status === "completed") return { ok: true, content: `Task ${task.id} completed. Its report:\n\n${task.text || "(no final message)"}` };
+      if (task.status === "interrupted") return { ok: true, content: `Task ${task.id} (${task.agentType}, "${task.description}") was interrupted: ${task.error ?? "the engine stopped"}.${task.text ? `\n\nIts last message:\n${task.text}` : ""}\n\n${resumeHint(task.id)}` };
+      return { ok: true, content: `Task ${task.id} ${task.status === "stopped" ? "was stopped" : "did not finish"}: ${task.error ?? "stopped on request"}${task.text ? `\n\nIts last message:\n${task.text}` : ""}` };
+    },
+  };
+
+  const stopTool = {
+    name: "TaskStop",
+    // Stops only work this run started.
+    readOnly: true,
+    description: "Stop a background task: a subagent started with run_in_background, a background shell, or a workflow run (its wf_ id: the run's script and its agents are stopped).",
+    input_schema: {
+      type: "object",
+      properties: { task_id: { type: "string", description: "The task id (or shell id, or workflow run id)." } },
+      required: ["task_id"],
+    },
+    /** @param {{task_id:string}} input */
+    async run(input) {
+      const task = tasks.get(input.task_id);
+      if (!task) {
+        if (d.shells?.has(input.task_id)) return d.shells.kill(input.task_id);
+        if (WORKFLOW_RUN_ID_RE.test(input.task_id) && workflowRuns) {
+          if (workflowRuns.has(input.task_id)) return workflowRuns.stop(input.task_id);
+          const disk = workflowRuns.diskStatus?.(input.task_id);
+          if (disk?.ok) return disk.running ? { ok: false, error: `Workflow ${input.task_id} is not running in this process, so it cannot be stopped from here.\n\n${disk.content}` } : { ok: true, content: `Workflow ${input.task_id} is not running; nothing to stop.\n\n${disk.content}` };
+        }
+        return { ok: false, error: `There is no background task "${input.task_id}".` };
+      }
+      if (task.elsewhere && task.status === "running") return { ok: false, error: `Task ${task.id} is running ${elsewhereText(task)}; it cannot be stopped from here.` };
+      if (task.status !== "running") {
+        consume(task);
+        return { ok: true, content: `Task ${task.id} had already ${task.status === "completed" ? "completed" : task.status === "interrupted" ? `been interrupted; ${resumeHint(task.id)}` : "ended"}.` };
+      }
+      task.stopRequested = true;
+      consume(task);
+      task.controller.abort();
+      await waitFor(task.done, STOP_WAIT_MS);
+      return { ok: true, content: `Stopped task ${task.id} (${task.agentType}, "${task.description}").` };
+    },
+  };
+
+  const drainNotifications = () => {
+    const out = queue.splice(0);
+    for (const n of out) {
+      const t = tasks.get(n.taskId);
+      if (t) {
+        t.notified = true;
+        save(t);
+      }
+    }
+    return out.map((n) => n.text);
+  };
+
+  return {
+    /** The subagent tools, in a stable order. */
+    tools: () => [startTool("Task"), startTool("Agent"), outputTool, stopTool],
+    /** @param {() => any[]} fn  the tool list the owning run exposes */
+    setParentTools(fn) {
+      parentTools = fn;
+    },
+    /** W4-E2: TaskOutput and TaskStop also take this session's workflow run ids. @param {WorkflowRuns|null} w */
+    setWorkflowRuns(w) {
+      workflowRuns = w;
+    },
+    drainNotifications,
+    /**
+     * Notifications ready now; otherwise, while a background task runs, wait
+     * for the next one to end (or the signal). Empty when nothing is running.
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<string[]>}
+     */
+    async awaitNotifications(signal) {
+      if (queue.length) return drainNotifications();
+      if (![...tasks.values()].some(runningHere)) return [];
+      await new Promise((resolve) => {
+        const done = () => {
+          signal?.removeEventListener("abort", done);
+          waiters.delete(done);
+          resolve(undefined);
+        };
+        waiters.add(done);
+        if (signal?.aborted) done();
+        else signal?.addEventListener("abort", done, { once: true });
+      });
+      return drainNotifications();
+    },
+    hasRunning: () => [...tasks.values()].some(runningHere),
+    /** Stop every running background task and wait for it to end. */
+    async stopAll() {
+      const running = [...tasks.values()].filter(runningHere);
+      for (const t of running) {
+        t.stopRequested = true;
+        t.notified = true;
+        t.controller.abort();
+      }
+      await Promise.all(running.map((t) => waitFor(t.done, STOP_WAIT_MS)));
+    },
+    /** Usage records of the children that finished since the last call. */
+    drainRecords: () => records.splice(0),
+    runChild,
+  };
+}
+
+/** @param {Promise<unknown>} p @param {number} ms @param {AbortSignal} [signal] */
+function waitFor(p, ms, signal) {
+  return new Promise((resolve) => {
+    const t = setTimeout(done, ms);
+    const onAbort = () => done();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    p.then(done, done);
+    function done() {
+      clearTimeout(t);
+      signal?.removeEventListener("abort", onAbort);
+      resolve(undefined);
+    }
+  });
+}