@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/agents/definitions.mjs

@@ -0,0 +1,343 @@
+/**
+ * lib/engine/agents/definitions.mjs — subagent definitions: parsing, discovery,
+ * and the pure policy a child run is built from.
+ *
+ * A subagent is a Markdown file with YAML frontmatter (the publicly documented
+ * subagent file format):
+ *
+ *   ---
+ *   name: code-reader
+ *   description: When to hand work to this agent.
+ *   tools: Read, Grep, Glob          (optional; absent = every tool the parent has)
+ *   disallowedTools: Bash            (optional)
+ *   model: haiku                     (optional; absent or "inherit" = the parent's tier)
+ *   permissionMode: plan             (optional; never looser than the parent's)
+ *   maxTurns: 20                     (optional)
+ *   ---
+ *   The body is the subagent's own instructions.
+ *
+ * Unknown frontmatter keys are ignored. `tools` may be a comma/space separated
+ * string or a YAML list (maestro's `agents/<id>/agent.md` uses a JSON-style list).
+ *
+ * Where definitions come from, in precedence order (the first with a name wins):
+ *   cli       --agents '{"name":{"description","prompt","tools","model"}}'
+ *   project   <cwd>/.claude/agents/*.md
+ *   seat      $AGENT_ROOT/agents/<id>/agent.md  (maestro; read only when AGENT_ROOT is set)
+ *   user      ~/.claude/agents/*.md
+ *   plugin    <plugin root>/agents/*.md, named `<plugin>:<name>`
+ *   builtin   general-purpose
+ * With --bare only cli, plugin (explicit --plugin-dir) and builtin are read.
+ *
+ * Everything here is pure except `discoverAgents`, which reads through an
+ * injected fs.
+ *
+ * @module lib/engine/agents/definitions
+ */
+
+import path from "node:path";
+import { parseSkillFile } from "../skills/index.mjs";
+import { PERMISSION_MODES } from "../permissions.mjs";
+
+/** The tool names that start or manage subagents. */
+export const AGENT_TOOL_NAMES = Object.freeze(["Task", "Agent", "TaskOutput", "TaskStop"]);
+
+/** The workflow tools (W4-A2): the main run's only, never a subagent's. */
+export const WORKFLOW_TOOL_NAMES = Object.freeze(["Workflow", "WorkflowStatus"]);
+
+/**
+ * Anthropic-slot aliases → Cohort tiers. Pinned equal to
+ * lib/runtime/adapter.mjs DEFAULT_COHORT_TIER_MAP (and so to
+ * lib/model-router/catalog/cohort.yaml `tier_map`) by agents.test.mjs.
+ */
+export const DEFAULT_TIER_MAP = Object.freeze({ fable: "cohort-reason", opus: "cohort-agentic", sonnet: "cohort-agentic", haiku: "cohort-fast" });
+
+/**
+ * @typedef {Object} AgentDefinition
+ * @property {string} name
+ * @property {string} description
+ * @property {string} prompt
+ * @property {string[]|null} tools            null = inherit every parent tool
+ * @property {string[]} disallowedTools
+ * @property {string|null} model              null = the parent's tier
+ * @property {string|null} permissionMode
+ * @property {number|null} maxTurns
+ * @property {'cli'|'project'|'seat'|'user'|'plugin'|'builtin'} source
+ * @property {string|null} file
+ */
+
+/** Authorship: written for Cohort Engine by the Cohort team, 2026-09-14. */
+export const GENERAL_PURPOSE_PROMPT =
+  "Work the task you were given through to a result using the tools you have. Search widely when you are not sure where something is, and read before you conclude. " +
+  "Your final message is the only thing the agent that started you will see, so make it complete on its own: what you found or did, with file paths and specifics.";
+
+/** @type {AgentDefinition} */
+export const GENERAL_PURPOSE_AGENT = Object.freeze({
+  name: "general-purpose",
+  description: "A general agent for multi-step research and implementation work, with every tool the caller has.",
+  prompt: GENERAL_PURPOSE_PROMPT,
+  tools: null,
+  disallowedTools: [],
+  model: null,
+  permissionMode: null,
+  maxTurns: null,
+  source: "builtin",
+  file: null,
+});
+
+/** @param {unknown} v @returns {string[]|null} */
+export function toolList(v) {
+  if (v === undefined || v === null) return null;
+  if (Array.isArray(v)) return v.map((s) => String(s).trim()).filter(Boolean);
+  if (typeof v === "string") {
+    const s = v.trim();
+    if (s === "" || s === "*") return s === "*" ? null : [];
+    if (s.startsWith("[")) {
+      try {
+        const arr = JSON.parse(s);
+        if (Array.isArray(arr)) return arr.map((x) => String(x).trim()).filter(Boolean);
+      } catch {
+        /* not JSON after all: split below */
+      }
+    }
+    return s.split(/[,\s]+/).map((x) => x.trim()).filter(Boolean);
+  }
+  return null;
+}
+
+/**
+ * Build a definition from already-parsed fields. Returns an error for a
+ * definition that cannot be offered (no name or no description).
+ * @param {Record<string, unknown>} fm
+ * @param {{body:string, source:AgentDefinition['source'], file:string|null, fallbackName:string, namespace?:string|null}} o
+ * @returns {{ok:true, agent:AgentDefinition}|{ok:false, error:string}}
+ */
+export function definitionFrom(fm, { body, source, file, fallbackName, namespace = null }) {
+  const base = typeof fm.name === "string" && fm.name.trim() !== "" ? fm.name.trim() : fallbackName;
+  if (!base) return { ok: false, error: `${file ?? source}: a subagent needs a name` };
+  const description = typeof fm.description === "string" ? fm.description.trim() : "";
+  if (description === "") return { ok: false, error: `${file ?? source}: subagent "${base}" needs a description` };
+  const model = typeof fm.model === "string" && fm.model.trim() !== "" && fm.model.trim().toLowerCase() !== "inherit" ? fm.model.trim() : null;
+  const mode = typeof fm.permissionMode === "string" && PERMISSION_MODES.includes(fm.permissionMode) ? fm.permissionMode : null;
+  const turns = Number(fm.maxTurns);
+  return {
+    ok: true,
+    agent: {
+      name: namespace ? `${namespace}:${base}` : base,
+      description,
+      prompt: String(body ?? "").trim(),
+      tools: toolList(fm.tools),
+      disallowedTools: toolList(fm.disallowedTools ?? fm["disallowed-tools"]) ?? [],
+      model,
+      permissionMode: mode,
+      maxTurns: Number.isInteger(turns) && turns > 0 ? turns : null,
+      source,
+      file,
+    },
+  };
+}
+
+/**
+ * @param {{file:string, text:string, source:AgentDefinition['source'], fallbackName:string, namespace?:string|null}} p
+ */
+export function parseAgentFile({ file, text, source, fallbackName, namespace = null }) {
+  const { frontmatter, body } = parseSkillFile(text);
+  return definitionFrom(frontmatter, { body, source, file, fallbackName, namespace });
+}
+
+/**
+ * Parse the `--agents` flag: a JSON object of name → {description, prompt?,
+ * tools?, disallowedTools?, model?, permissionMode?, maxTurns?}.
+ * @param {string} text
+ * @returns {{ok:true, agents:AgentDefinition[]}|{ok:false, error:string}}
+ */
+export function parseAgentsJson(text) {
+  let doc;
+  try {
+    doc = JSON.parse(String(text));
+  } catch (e) {
+    return { ok: false, error: `--agents is not valid JSON (${e instanceof Error ? e.message : e})` };
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return { ok: false, error: "--agents must be a JSON object of name → definition" };
+  const agents = [];
+  for (const [name, spec] of Object.entries(doc)) {
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) return { ok: false, error: `--agents: "${name}" must be an object` };
+    if (spec.prompt !== undefined && typeof spec.prompt !== "string") return { ok: false, error: `--agents: "${name}".prompt must be a string` };
+    const r = definitionFrom({ ...spec, name }, { body: spec.prompt ?? "", source: "cli", file: null, fallbackName: name });
+    if (!r.ok) return { ok: false, error: `--agents: ${r.error.replace(/^cli: /, "")}` };
+    agents.push(r.agent);
+  }
+  return { ok: true, agents };
+}
+
+/**
+ * @typedef {Object} AgentFs
+ * @property {(p:string)=>string} readFile
+ * @property {(p:string)=>string[]} readdir
+ * @property {(p:string)=>boolean} isFile
+ * @property {(p:string)=>boolean} isDir
+ */
+
+/**
+ * @param {object} p
+ * @param {AgentDefinition[]} [p.cliAgents]
+ * @param {string|null} p.userDir          ~/.claude
+ * @param {string} p.cwd
+ * @param {string|null} [p.seatRoot]       maestro agent root (agents/<id>/agent.md); null = no seat source
+ * @param {Array<{dir:string}>} [p.pluginDirs]
+ * @param {boolean} [p.bare]
+ * @param {AgentFs} p.fs
+ * @returns {{agents: AgentDefinition[], errors: string[]}}
+ */
+export function discoverAgents({ cliAgents = [], userDir, cwd, seatRoot = null, pluginDirs = [], bare = false, fs }) {
+  /** @type {AgentDefinition[]} */
+  const agents = [];
+  const errors = [];
+  const byName = new Map();
+  const names = (/** @type string */ dir) => {
+    try {
+      return fs.readdir(dir).sort();
+    } catch {
+      return [];
+    }
+  };
+  const add = (/** @type {AgentDefinition} */ a) => {
+    if (byName.has(a.name)) {
+      if (a.source !== "builtin") errors.push(`subagent "${a.name}"${a.file ? ` at ${a.file}` : ""} is shadowed by the ${byName.get(a.name).source} definition`);
+      return;
+    }
+    byName.set(a.name, a);
+    agents.push(a);
+  };
+  const fromFile = (/** @type string */ file, /** @type {AgentDefinition['source']} */ source, /** @type string */ fallbackName, /** @type {string|null} */ namespace) => {
+    let text;
+    try {
+      text = fs.readFile(file);
+    } catch (e) {
+      errors.push(`subagent ${file}: cannot read (${e instanceof Error ? e.message : e})`);
+      return;
+    }
+    const r = parseAgentFile({ file, text, source, fallbackName, namespace });
+    if (r.ok) add(r.agent);
+    else errors.push(r.error);
+  };
+  const flatDir = (/** @type string */ dir, /** @type {AgentDefinition['source']} */ source, /** @type {string|null} */ namespace) => {
+    if (!fs.isDir(dir)) return;
+    for (const entry of names(dir)) {
+      const full = path.join(dir, entry);
+      if (entry.endsWith(".md") && fs.isFile(full)) fromFile(full, source, entry.slice(0, -3), namespace);
+    }
+  };
+
+  for (const a of cliAgents) add(a);
+  if (!bare) {
+    flatDir(path.join(cwd, ".claude", "agents"), "project", null);
+    if (seatRoot) {
+      const dir = path.join(seatRoot, "agents");
+      if (fs.isDir(dir)) {
+        for (const id of names(dir)) {
+          const file = path.join(dir, id, "agent.md");
+          if (fs.isFile(file)) fromFile(file, "seat", id, null);
+        }
+      }
+    }
+    if (userDir) flatDir(path.join(userDir, "agents"), "user", null);
+  }
+  for (const { dir } of pluginDirs) {
+    if (!fs.isDir(dir)) continue;
+    let plugin = path.basename(dir);
+    const manifest = path.join(dir, "plugin.json");
+    if (fs.isFile(manifest)) {
+      try {
+        const doc = JSON.parse(fs.readFile(manifest));
+        if (typeof doc?.name === "string" && doc.name.trim() !== "") plugin = doc.name.trim();
+      } catch {
+        /* the skills loader reports a bad manifest; the directory name stands in */
+      }
+    }
+    flatDir(path.join(dir, "agents"), "plugin", plugin);
+  }
+  add(GENERAL_PURPOSE_AGENT);
+  return { agents, errors };
+}
+
+/**
+ * Find a definition by the name the model passed (trimmed): exact, then a
+ * unique plugin agent whose unqualified name matches. Permission rules see the
+ * same spellings (permissions.mjs `subagentTypeMatches`), and the Task tool
+ * re-checks the resolved name.
+ * @param {AgentDefinition[]} agents @param {unknown} requested
+ * @returns {{ok:true, agent:AgentDefinition}|{ok:false, error:string}}
+ */
+export function findAgent(agents, requested) {
+  const want = String(requested ?? "").trim();
+  const exact = agents.find((a) => a.name === want);
+  if (exact) return { ok: true, agent: exact };
+  const suffix = want.includes(":") ? [] : agents.filter((a) => a.name.endsWith(`:${want}`));
+  if (suffix.length === 1) return { ok: true, agent: suffix[0] };
+  return { ok: false, error: `There is no subagent type "${want}". Available: ${agents.map((a) => a.name).join(", ")}.` };
+}
+
+/**
+ * The tier a child runs on: a cohort-* tier as given; an Anthropic-slot alias
+ * (or a model id containing one, e.g. claude-sonnet-4-6) through the tier map;
+ * anything else — and no model — runs on the parent's tier.
+ * @param {string|null} model @param {string} parentModel @param {Record<string,string>} [tierMap]
+ * @returns {{model:string, note:string|null}}
+ */
+export function resolveAgentModel(model, parentModel, tierMap = DEFAULT_TIER_MAP) {
+  const m = typeof model === "string" ? model.trim().toLowerCase() : "";
+  if (m === "" || m === "inherit") return { model: parentModel, note: null };
+  if (m.startsWith("cohort-")) return { model: m, note: null };
+  for (const slot of ["fable", "opus", "sonnet", "haiku"]) {
+    if (m.includes(slot) && tierMap[slot]) return { model: tierMap[slot], note: null };
+  }
+  return { model: parentModel, note: `model "${model}" has no Cohort tier; running on ${parentModel}` };
+}
+
+/** Permission modes from loosest to strictest. */
+const MODE_RANK = Object.freeze({ bypassPermissions: 0, acceptEdits: 1, default: 2, dontAsk: 3, plan: 4 });
+
+/**
+ * A child never runs looser than its parent: the stricter of the two modes.
+ * @param {string} parentMode @param {string|null} requested
+ */
+export function clampPermissionMode(parentMode, requested) {
+  if (!requested || !(requested in MODE_RANK)) return parentMode;
+  const p = MODE_RANK[/** @type {keyof MODE_RANK} */ (parentMode)] ?? MODE_RANK.default;
+  return MODE_RANK[/** @type {keyof MODE_RANK} */ (requested)] > p ? requested : parentMode;
+}
+
+/**
+ * Does a name in a definition's tool list cover this tool? Exact names;
+ * `mcp__server` / `mcp__server__*` for a whole server; Task and Agent are one tool.
+ * @param {string} entry @param {string} toolName
+ */
+export function toolEntryMatches(entry, toolName) {
+  const e = entry.replace(/\(.*\)$/, "");
+  if (e === toolName) return true;
+  if ((e === "Task" || e === "Agent") && (toolName === "Task" || toolName === "Agent")) return true;
+  if (e.startsWith("mcp__")) {
+    const rest = e.slice(5).replace(/__\*$/, "");
+    if (!rest.includes("__")) return toolName.startsWith(`mcp__${rest}__`);
+  }
+  return false;
+}
+
+/**
+ * The tool names a child gets: the definition's list (or every parent tool)
+ * intersected with the parent's tools, minus its disallowed tools, minus the
+ * subagent tools when the depth limit is reached. Pure.
+ * @param {string[]} parentToolNames
+ * @param {AgentDefinition} def
+ * @param {{canSpawn:boolean}} o
+ * @returns {{names:string[], missing:string[]}}  `missing`: listed tools the parent does not have
+ */
+export function childToolNames(parentToolNames, def, { canSpawn }) {
+  const listed = def.tools;
+  let names = listed === null ? [...parentToolNames] : parentToolNames.filter((n) => listed.some((e) => toolEntryMatches(e, n)));
+  names = names.filter((n) => !def.disallowedTools.some((e) => toolEntryMatches(e, n)) && !WORKFLOW_TOOL_NAMES.includes(n));
+  // Subagent tools travel together: TaskOutput/TaskStop only with Task or Agent.
+  if (!canSpawn || !names.some((n) => n === "Task" || n === "Agent")) names = names.filter((n) => !AGENT_TOOL_NAMES.includes(n));
+  const missing = listed === null ? [] : listed.filter((e) => !parentToolNames.some((n) => toolEntryMatches(e, n)));
+  return { names, missing };
+}

package/lib/engine/agents/persist.mjs

@@ -0,0 +1,275 @@
+/**
+ * lib/engine/agents/persist.mjs — a subagent task's state on disk, so it
+ * survives the engine process (W4-E2, conformance row 23, CF-50).
+ *
+ *   <sessions>/subagents/<session id>/<agent id>.state.json   (this module)
+ *   <sessions>/subagents/<session id>/<agent id>.jsonl        the sidechain transcript
+ *
+ * A task started with the Task tool writes its state when it starts and every
+ * time it changes (it ends, it is read or stopped, its notification is
+ * delivered). Each write replaces the whole file atomically
+ * (fs-atomic `writeJsonAtomic`), so a crash leaves the previous state, never a
+ * torn one.
+ *
+ * When a session is continued (`--resume`, a reused `--session-id`), the agent
+ * runtime reads the states of its session back (`readTaskStates`) and
+ * reconciles each one (`reconcileTaskState`, pure): a task recorded as running
+ * whose process is gone was cut off, and is `interrupted`. The process is
+ * judged by PID, a per-process nonce and the OS start time
+ * (process-identity.mjs), so neither a restarted engine that got the same PID
+ * nor an unrelated process that reuses a recorded PID is mistaken for the
+ * writer. Its sidechain transcript is what `Task {resume}` continues from.
+ *
+ * The state holds a snapshot of the definition the child ran with and the
+ * permission mode it was clamped to, so a resumed child can never run looser
+ * than it did before (`definitionForResume`): its tools are the snapshot's
+ * intersected with the definition of that name today, its disallowed tools
+ * both lists, its `permissionMode` and `maxTurns` the stricter of the two; the
+ * runtime then clamps the mode to the recorded one and intersects the tools
+ * with the resuming run's tools.
+ *
+ * @module lib/engine/agents/persist
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { writeJsonAtomic } from "../../fs-atomic.mjs";
+import { judgeOwner } from "../process-identity.mjs";
+import { clampPermissionMode, toolEntryMatches } from "./definitions.mjs";
+
+export const TASK_STATE_VERSION = 1;
+export const TASK_STATUSES = Object.freeze(["running", "completed", "failed", "stopped", "interrupted"]);
+const AGENT_ID_RE = /^agent-[0-9a-f]{16}$/;
+/** A task's final text and prompt kept in its state file (the transcript has everything). */
+export const MAX_STATE_TEXT_CHARS = 200_000;
+
+/**
+ * @typedef {Object} TaskState
+ * @property {number} version
+ * @property {string} agentId
+ * @property {string} sessionId
+ * @property {string} parentAgentId
+ * @property {string|null} parentToolUseId
+ * @property {string} agentType
+ * @property {import('./definitions.mjs').AgentDefinition} definition  a snapshot
+ * @property {string} description
+ * @property {string} prompt              the first prompt
+ * @property {string|null} lastPrompt     the prompt of the latest resume
+ * @property {string} mode                the permission mode the child ran in (its ceiling)
+ * @property {string} model               its tier
+ * @property {boolean} background
+ * @property {string} transcriptPath
+ * @property {'running'|'completed'|'failed'|'stopped'|'interrupted'} status
+ * @property {string} text
+ * @property {string|null} error
+ * @property {boolean} notified
+ * @property {number} pid                 the process that last ran it
+ * @property {string|null} [nonce]        that process's nonce (process-identity.mjs PROCESS_NONCE)
+ * @property {string|null} [startToken]   that process's OS start time, when it could be read
+ * @property {number} resumes
+ * @property {string} startedAt
+ * @property {string|null} endedAt
+ */
+
+/** @param {unknown} id @returns {id is string} */
+export function isAgentId(id) {
+  return typeof id === "string" && AGENT_ID_RE.test(id);
+}
+
+/** @param {string} sessionsDir @param {string} sessionId */
+export function subagentDir(sessionsDir, sessionId) {
+  return path.join(sessionsDir, "subagents", sessionId);
+}
+
+/** @param {string} sessionsDir @param {string} sessionId @param {string} agentId */
+export function taskStatePath(sessionsDir, sessionId, agentId) {
+  return path.join(subagentDir(sessionsDir, sessionId), `${agentId}.state.json`);
+}
+
+/** @param {string} s */
+const cap = (s) => (s.length <= MAX_STATE_TEXT_CHARS ? s : `${s.slice(0, MAX_STATE_TEXT_CHARS)}\n… [cut; the whole text is in the transcript]`);
+
+/**
+ * Write a state. False when the write failed (the run goes on; the task just
+ * cannot be recovered after a restart).
+ * @param {string} sessionsDir @param {TaskState} state
+ */
+export function writeTaskState(sessionsDir, state) {
+  try {
+    writeJsonAtomic(taskStatePath(sessionsDir, state.sessionId, state.agentId), { ...state, text: cap(state.text ?? ""), prompt: cap(state.prompt ?? "") });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is a parsed object a usable state for this session? Pure.
+ * @param {any} s @param {string} sessionId
+ * @returns {s is TaskState}
+ */
+export function isTaskState(s, sessionId) {
+  return Boolean(
+    s &&
+      typeof s === "object" &&
+      s.version === TASK_STATE_VERSION &&
+      isAgentId(s.agentId) &&
+      s.sessionId === sessionId &&
+      typeof s.parentAgentId === "string" &&
+      typeof s.agentType === "string" &&
+      s.definition && typeof s.definition === "object" && typeof s.definition.name === "string" &&
+      typeof s.mode === "string" &&
+      typeof s.transcriptPath === "string" &&
+      TASK_STATUSES.includes(s.status) &&
+      Number.isInteger(s.pid),
+  );
+}
+
+/**
+ * Every state of a session, oldest start first.
+ * @param {string} sessionsDir @param {string} sessionId
+ * @returns {{states: TaskState[], errors: string[]}}
+ */
+export function readTaskStates(sessionsDir, sessionId) {
+  const dir = subagentDir(sessionsDir, sessionId);
+  let names;
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith(".state.json")).sort();
+  } catch {
+    return { states: [], errors: [] };
+  }
+  const states = [];
+  const errors = [];
+  for (const name of names) {
+    try {
+      const s = JSON.parse(readFileSync(path.join(dir, name), "utf8"));
+      if (isTaskState(s, sessionId) && `${s.agentId}.state.json` === name) states.push(s);
+      else errors.push(`${name}: not a task state of session ${sessionId}`);
+    } catch (e) {
+      errors.push(`${name}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  states.sort((a, b) => (a.startedAt < b.startedAt ? -1 : a.startedAt > b.startedAt ? 1 : 0));
+  return { states, errors };
+}
+
+/**
+ * Read one state of a session (null when there is none or it is unusable).
+ * @param {string} sessionsDir @param {string} sessionId @param {string} agentId
+ * @returns {TaskState|null}
+ */
+export function readTaskState(sessionsDir, sessionId, agentId) {
+  if (!isAgentId(agentId)) return null;
+  try {
+    const s = JSON.parse(readFileSync(taskStatePath(sessionsDir, sessionId, agentId), "utf8"));
+    return isTaskState(s, sessionId) && s.agentId === agentId ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @typedef {Object} OwnerCheck  how this process judges a recorded owner (process-identity.mjs)
+ * @property {{pid:number, nonce:string}} self
+ * @property {{isAlive:(pid:number)=>boolean, startToken:(pid:number)=>string|null}} probe
+ * @property {(agentId:string) => boolean} heldHere  whether a runtime in THIS process is running that task now
+ */
+
+/**
+ * Where a task recorded as running is really running. Pure.
+ *   'here-elsewhere'  this process, in another runtime that still holds it
+ *   'elsewhere'       another live process
+ *   'gone'            its process stopped (or this process wrote it and no runtime holds it any more)
+ * @param {TaskState} s @param {OwnerCheck} o
+ * @returns {'here-elsewhere'|'elsewhere'|'gone'}
+ */
+export function taskOwnerState(s, { self, probe, heldHere }) {
+  const owner = judgeOwner({ pid: s.pid, nonce: s.nonce ?? null, startToken: s.startToken ?? null }, self, probe);
+  if (owner === "self") return heldHere(s.agentId) ? "here-elsewhere" : "gone";
+  return owner === "alive" ? "elsewhere" : "gone";
+}
+
+/**
+ * A restored state as this process sees it. Pure.
+ *   running, and its process is gone (see `taskOwnerState`)          → interrupted
+ *   running in another live process, or in another runtime of this one → running elsewhere
+ * @param {TaskState} s
+ * @param {OwnerCheck & {now:string}} o
+ * @returns {{state: TaskState, changed: boolean, elsewhere: boolean}}
+ */
+export function reconcileTaskState(s, o) {
+  if (s.status !== "running") return { state: s, changed: false, elsewhere: false };
+  if (taskOwnerState(s, o) !== "gone") return { state: s, changed: false, elsewhere: true };
+  return {
+    state: { ...s, status: "interrupted", error: `the engine process running it (pid ${s.pid}) stopped before it finished`, notified: false, endedAt: o.now },
+    changed: true,
+    elsewhere: false,
+  };
+}
+
+/**
+ * A state's definition snapshot, normalised to a definition's shape. Pure.
+ * @param {TaskState} s
+ * @returns {import('./definitions.mjs').AgentDefinition}
+ */
+export function snapshotDefinition(s) {
+  const d = /** @type any */ (s.definition);
+  const strings = (/** @type unknown */ v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : null);
+  return {
+    name: s.agentType,
+    description: typeof d.description === "string" ? d.description : s.agentType,
+    prompt: typeof d.prompt === "string" ? d.prompt : "",
+    tools: strings(d.tools),
+    disallowedTools: strings(d.disallowedTools) ?? [],
+    model: typeof d.model === "string" ? d.model : null,
+    permissionMode: typeof d.permissionMode === "string" ? d.permissionMode : null,
+    maxTurns: Number.isInteger(d.maxTurns) && d.maxTurns > 0 ? d.maxTurns : null,
+    source: typeof d.source === "string" ? d.source : "cli",
+    file: typeof d.file === "string" ? d.file : null,
+  };
+}
+
+/**
+ * Two tool lists' intersection (null = no restriction). An entry is kept when
+ * the other list covers it (exact names, `mcp__server` covering its tools), so
+ * `["mcp__srv"]` ∩ `["mcp__srv__one", "Read"]` is `["mcp__srv__one"]`. Pure.
+ * @param {string[]|null} a @param {string[]|null} b
+ * @returns {string[]|null}
+ */
+export function intersectToolLists(a, b) {
+  if (a === null) return b === null ? null : [...b];
+  if (b === null) return [...a];
+  const bare = (/** @type string */ e) => e.replace(/\(.*\)$/, "");
+  const out = [...b.filter((e) => a.some((x) => toolEntryMatches(x, bare(e)))), ...a.filter((e) => b.some((x) => toolEntryMatches(x, bare(e))))];
+  return [...new Set(out)];
+}
+
+/**
+ * The definition a resumed child runs with (W4-E2 review). The definition
+ * this run knows by that name may have changed since the child started — been
+ * edited, or shadowed by a project file of the same name — so it can only
+ * narrow the snapshot, never widen it: tools are the intersection, disallowed
+ * tools the union, `permissionMode` the stricter and `maxTurns` the smaller.
+ * Its prompt, description and model are today's. With no definition of that
+ * name, the snapshot. Pure.
+ * @param {TaskState} s @param {import('./definitions.mjs').AgentDefinition[]} agents
+ * @param {(agents:any[], name:string)=>{ok:boolean, agent?:any}} findAgent
+ * @returns {import('./definitions.mjs').AgentDefinition}
+ */
+export function definitionForResume(s, agents, findAgent) {
+  const snap = snapshotDefinition(s);
+  const known = findAgent(agents, s.agentType);
+  if (!(known.ok && known.agent && known.agent.name === s.agentType)) return snap;
+  /** @type {import('./definitions.mjs').AgentDefinition} */
+  const now = known.agent;
+  const modes = [snap.permissionMode, now.permissionMode].filter((m) => typeof m === "string");
+  const turns = [snap.maxTurns, now.maxTurns].filter((n) => Number.isInteger(n) && /** @type number */ (n) > 0);
+  return {
+    ...now,
+    tools: intersectToolLists(snap.tools, now.tools ?? null),
+    disallowedTools: [...new Set([...snap.disallowedTools, ...(now.disallowedTools ?? [])])],
+    permissionMode: modes.length === 0 ? null : modes.length === 1 ? modes[0] : clampPermissionMode(modes[0], modes[1]),
+    maxTurns: turns.length ? Math.min(.../** @type number[] */ (turns)) : null,
+    model: now.model ?? snap.model,
+  };
+}