@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/diagnostics/cadence-output-freshness.mjs

@@ -0,0 +1,288 @@
+/**
+ * lib/diagnostics/cadence-output-freshness.mjs — did the cadence actually PRODUCE
+ * anything, or did it merely finish?
+ *
+ * WHY THIS EXISTS
+ *
+ * The daily evening wrap — which its own trigger calls the most important
+ * maintenance workflow — ran on 4 of the 9 days from 26 Aug to 3 Sep 2026. It
+ * missed 25, 29, 30, 31 Aug and 1 Sep, and NOTHING NOTICED, because the five
+ * misses failed four different ways and only two of them look like failure from
+ * the cadence bus:
+ *
+ *   29 Aug  enqueued, claimed 17x, escalated 2x, subsession_timeout,
+ *           subsession_failed, retry_requeued, 15x skipped_backoff — and then
+ *           stage "processed". THE BUS RECORDED SUCCESS FOR A RUN THAT PRODUCED
+ *           NO BRIEF AND NO WORKFLOW LOG.
+ *   30 Aug  attempts=2, routed to the DLQ. Honest — but nothing reads the DLQ.
+ *   31 Aug  ditto.
+ *    1 Sep  one line in the bus log, `enqueued:1`, and nothing further. Never
+ *           claimed at all.
+ *
+ * That first mode is the one that makes this module necessary. Any alert keyed
+ * on the bus's own decision is GREEN during the outage, because the bus cannot
+ * distinguish a completed wrap from a timed-out one — `stage=processed` fired on
+ * a run that wrote nothing. A guard that reads the same field the lane writes
+ * agrees with that lane forever.
+ *
+ * So this check is deliberately derived from a DIFFERENT SOURCE than the lane it
+ * judges: the OUTPUT ARTEFACTS on disk. It asks one question — for the day in
+ * question, do the files this workflow is supposed to leave behind exist, and are
+ * they non-trivial? That was the only signal that caught all four modes, and it
+ * is independent by construction: the bus can say whatever it likes, a brief that
+ * was never written is still absent.
+ *
+ * WHAT "NON-TRIVIAL" MEANS, AND WHY IT IS NOT `run_end`
+ *
+ * The tempting discriminator is a terminal event — assert the workflow log ends
+ * with `{"event":"run_end","status":"completed"}`. MEASURED, THAT IS WRONG: of
+ * the five wraps that genuinely ran and produced full briefs, only ONE
+ * (2026-09-02) carries a `run_end` line at all. Pinning on it would have fired on
+ * 4 of the 5 healthy days — an 80% false-positive rate on the exact signal this
+ * module exists to make trustworthy. A checker that cries wolf on most good days
+ * gets muted, and then it is worth less than nothing.
+ *
+ * The same trap caught a second candidate. Pinning the JSONL on its `workflow`
+ * FIELD VALUE (`workflow == "daily-evening-wrap"`) looks like the careful choice —
+ * it reads a value rather than grepping a token. Replayed over the real corpus it
+ * failed on THREE of the five healthy days: 26 Aug writes `"workflow":
+ * "evening-wrap"` and 27-28 Aug carry no `workflow` key at all, only `step`. The
+ * workflow log is hand-authored per run and HAS NO STABLE INTERNAL SCHEMA. No
+ * assertion about a named event, status or cadence field survives the corpus, so
+ * none of them belongs in a guard.
+ *
+ * What does survive, measured across all five logs: every one of the 61 lines
+ * parses as a JSON object and every one carries a `ts`. So the honest bar is size
+ * plus that schema-agnostic shape — the file must be a JSONL of timestamped
+ * records, not merely a file. Floors are calibrated against what real runs
+ * actually produced (briefs 5115-10906 bytes, logs 8-17 lines / 2722-5459 bytes)
+ * with roughly an order of magnitude of headroom beneath the observed minimum. A
+ * healthy run clears it comfortably; an absent file, an empty file, a truncated
+ * file or a plain-text stub from a session that died mid-run does not.
+ *
+ * The general rule, learned twice here: VALIDATE A CANDIDATE DISCRIMINATOR AGAINST
+ * THE KNOWN-GOOD DAYS BEFORE SHIPPING IT. A check is only as good as its false
+ * positive rate on healthy input, and both of the discriminators that read like
+ * the rigorous choice would have fired on most of the days the workflow worked.
+ *
+ * WHICH DAY, AND WHY UTC
+ *
+ * Artefact filenames are keyed by UTC date. The wrap fires at 18:00 GST = 14:00
+ * UTC, so a run always writes the file for its own UTC day with ~10h of clearance
+ * on either side of the boundary — there is no hour at which "yesterday, UTC" is
+ * racing a run in progress. Checking YESTERDAY rather than today is what keeps
+ * this quiet: today's wrap has not happened yet for most of the day, and its
+ * absence at 09:00 is not a fault.
+ *
+ * `notBefore` exists so a widened lookback cannot claim a miss for a day on which
+ * the cadence did not yet exist. It is a declared constant, NOT derived from the
+ * artefacts — deriving it from the oldest file present would make the check agree
+ * with itself.
+ *
+ * Invariant: NEVER throws. A missing directory, an unreadable file, a bad clock
+ * all degrade to a verdict. Diagnostics must not be able to crash the path that
+ * observes them. But the fail-open direction is chosen per case: when a file
+ * cannot be read at all we report it MISSING, because the bug being fixed is
+ * silence, and the worst case of a wrong alert is one redundant message.
+ *
+ * Constraints (CLAUDE.md): ESM, Node built-ins only, injectable clock + paths so
+ * tests are hermetic and need no real outputs/ or logs/ on disk.
+ *
+ * @module lib/diagnostics/cadence-output-freshness
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * What each watched cadence must leave on disk for a day it ran.
+ *
+ * Floors are calibrated against observed healthy runs with ~10x headroom (see the
+ * module header). `jsonLineField` makes the check read a FIELD VALUE rather than
+ * grep for a token, so an empty or corrupt log cannot pass on a coincidental
+ * substring.
+ *
+ * @type {Readonly<object>}
+ */
+export const DEFAULT_OUTPUT_CONTRACTS = Object.freeze({
+  "daily-evening-wrap": Object.freeze({
+    label: "evening wrap",
+    // The cadence's first completed run. Declared, not derived from disk.
+    notBefore: "2026-08-26",
+    artefacts: Object.freeze([
+      Object.freeze({
+        // Written by the brief-writing step.
+        path: "outputs/briefs/{date}-evening-wrap.md",
+        minBytes: 500,
+        minLines: 5,
+      }),
+      Object.freeze({
+        // Written by the run-logging step — a DIFFERENT step, so the two
+        // artefacts corroborate rather than restate one another.
+        path: "logs/workflows/{date}-evening-wrap.jsonl",
+        minBytes: 200,
+        minLines: 3,
+        // Schema-agnostic on purpose: assert only that it IS a JSONL of
+        // timestamped records. Every field richer than this varies run to run
+        // (see header) and would fire on healthy days.
+        minJsonRecords: Object.freeze({ count: 3, requireField: "ts" }),
+      }),
+    ]),
+  }),
+});
+
+/** How many days back to check. 1 = yesterday only (see header: today is not yet due). */
+export const DEFAULT_LOOKBACK_DAYS = 1;
+
+/**
+ * Resolve the agent root the same way every other maestro module does.
+ * @param {object} [cfg]
+ * @returns {string}
+ */
+function agentRoot(cfg = {}) {
+  return resolve(
+    cfg.agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+}
+
+/**
+ * UTC day key `YYYY-MM-DD`, `back` days before `now`. UTC because artefact
+ * filenames are UTC-keyed (module header).
+ * @param {number} now epoch ms
+ * @param {number} back days back
+ * @returns {string}
+ */
+export function dayKeyUTC(now, back = 0) {
+  return new Date(now - back * MS_PER_DAY).toISOString().slice(0, 10);
+}
+
+/**
+ * Inspect one artefact. Returns `null` when it satisfies its contract, else a
+ * reason record. Never throws: an unreadable file is reported as a fault, not
+ * swallowed.
+ * @param {string} root
+ * @param {object} spec
+ * @param {string} day
+ * @returns {null|{path:string, reason:string, bytes:number|null, lines:number|null}}
+ */
+function inspectArtefact(root, spec, day) {
+  const rel = String(spec.path || "").replace(/\{date\}/g, day);
+  const abs = join(root, rel);
+  const fault = (reason, bytes = null, lines = null) => ({ path: rel, reason, bytes, lines });
+
+  if (!existsSync(abs)) return fault("absent");
+
+  let bytes;
+  try {
+    bytes = statSync(abs).size;
+  } catch (err) {
+    return fault(`unstatable: ${err && err.message ? err.message : String(err)}`);
+  }
+
+  const minBytes = Number.isFinite(spec.minBytes) ? spec.minBytes : 0;
+  if (bytes < minBytes) return fault(`stub: ${bytes} bytes < ${minBytes} floor`, bytes);
+
+  let body;
+  try {
+    body = readFileSync(abs, "utf-8");
+  } catch (err) {
+    return fault(`unreadable: ${err && err.message ? err.message : String(err)}`, bytes);
+  }
+
+  const lines = body.split("\n").filter((l) => l.trim().length > 0);
+  const minLines = Number.isFinite(spec.minLines) ? spec.minLines : 0;
+  if (lines.length < minLines) {
+    return fault(`stub: ${lines.length} non-empty lines < ${minLines} floor`, bytes, lines.length);
+  }
+
+  // Structural bar for JSONL: enough PARSEABLE objects each carrying the required
+  // field. Tests parseability and a field's PRESENCE, never a field's name as a
+  // substring and never a value that varies between healthy runs.
+  const jr = spec.minJsonRecords;
+  if (jr && Number.isFinite(jr.count)) {
+    let records = 0;
+    for (const l of lines) {
+      let o;
+      try { o = JSON.parse(l); } catch { continue; }
+      if (!o || typeof o !== "object" || Array.isArray(o)) continue;
+      if (jr.requireField && o[jr.requireField] === undefined) continue;
+      records++;
+    }
+    if (records < jr.count) {
+      const q = jr.requireField ? ` carrying "${jr.requireField}"` : "";
+      return fault(
+        `only ${records} parseable JSON record(s)${q} < ${jr.count} floor`,
+        bytes,
+        lines.length
+      );
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Did the watched cadences produce their output artefacts?
+ *
+ * @param {object}  [cfg]
+ * @param {string}  [cfg.agentRoot]      agent root (default resolved as usual)
+ * @param {object}  [cfg.contracts]      override DEFAULT_OUTPUT_CONTRACTS
+ * @param {number}  [cfg.lookbackDays]   days back to check (default 1 = yesterday)
+ * @param {number}  [cfg.now]            clock in epoch ms (default Date.now())
+ * @returns {{ok:boolean, days:string[], checked:number,
+ *            missing:Array<{cadence:string,label:string,day:string,path:string,reason:string}>}}
+ */
+export function cadenceOutputFreshness(cfg = {}) {
+  const missing = [];
+  const days = [];
+  let checked = 0;
+  try {
+    const root = agentRoot(cfg);
+    const contracts = cfg.contracts && typeof cfg.contracts === "object"
+      ? cfg.contracts
+      : DEFAULT_OUTPUT_CONTRACTS;
+    const lookback = Number.isFinite(cfg.lookbackDays) && cfg.lookbackDays > 0
+      ? Math.floor(cfg.lookbackDays)
+      : DEFAULT_LOOKBACK_DAYS;
+    const now = Number.isFinite(cfg.now) ? cfg.now : Date.now();
+
+    for (let back = 1; back <= lookback; back++) days.push(dayKeyUTC(now, back));
+
+    for (const [cadence, contract] of Object.entries(contracts)) {
+      if (!contract || !Array.isArray(contract.artefacts)) continue;
+      for (const day of days) {
+        // A day before the cadence existed cannot be a miss.
+        if (contract.notBefore && day < contract.notBefore) continue;
+        for (const spec of contract.artefacts) {
+          checked++;
+          const fault = inspectArtefact(root, spec, day);
+          if (fault) {
+            missing.push({
+              cadence,
+              label: contract.label || cadence,
+              day,
+              path: fault.path,
+              reason: fault.reason,
+            });
+          }
+        }
+      }
+    }
+  } catch {
+    // Never throw. Whatever was accumulated before the failure is still valid.
+  }
+
+  // Deterministic order so an upstream de-dupe can key on the list.
+  missing.sort((a, b) =>
+    a.day < b.day ? -1 : a.day > b.day ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0
+  );
+
+  return { ok: missing.length === 0, days, checked, missing };
+}
+
+export default { cadenceOutputFreshness, dayKeyUTC, DEFAULT_OUTPUT_CONTRACTS, DEFAULT_LOOKBACK_DAYS };

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 };
+}