@foldrun/core 0.3.0 → 0.5.0

package/src/subagents.ts

@@ -0,0 +1,189 @@
+// Sub-agents: delegate a job to a colleague with its OWN context and its own
+// tools, inside the step that asked.
+//
+//   agents: [editor]          # consult: a quick opinion, no tools (agent-tools.ts)
+//   subagents: [researcher]   # delegate: own context, own tools
+//
+// Built on the Agent SDK's native sub-agents (query()'s `agents` option and
+// its Agent tool), so a delegation behaves as it does in Claude Code: a fresh
+// context does the work — reads forty pages, runs the checks — and hands back
+// a summary, keeping the parent's context on its own job.
+//
+// What keeps it the platform's and not a second, wider agent:
+//   - never wider than the parent: a sub-agent's tools are its own `tools:`
+//     resolved exactly as a step's, INTERSECTED with what the parent step
+//     holds — and always an explicit list: the SDK gives a definition with
+//     no `tools` every tool the parent has
+//   - depth one: the Agent/Task tool is never in a sub-agent's list, so it
+//     cannot delegate again
+//   - the same step: same sandbox, files, secrets, egress lease, and the
+//     parent's hooks — the SDK runs a sub-agent's tool calls through the
+//     session's PreToolUse and canUseTool (tagged agent_id/agent_type), so
+//     confinement applies unchanged; subagentGuard() below refuses anything
+//     outside the sub-agent's own list there too, belt and braces
+//   - cost and trace land on the parent step; flows still decide what runs
+//     next — a sub-agent is a helper inside one step, never a step.
+
+import fs from "node:fs";
+import path from "node:path";
+import { refNames } from "./refs.ts";
+import { TOOL_MAP } from "./tool-names.ts";
+
+/** Plain JSON: this crosses into the run container. */
+export interface SubagentSpec {
+  name: string;
+  description: string;
+  prompt: string;
+  /** Always explicit — never absent, never inherited. */
+  tools: string[];
+  disallowedTools: string[];
+  /** A model alias (haiku/sonnet/opus, remapped by the step's provider like
+   *  the step's own) or "inherit". */
+  model: string;
+}
+
+/** The SDK's delegation tool, under both names it has had. Never granted to a
+ *  sub-agent: that is what makes the depth one. */
+export const DELEGATE_TOOLS = ["Agent", "Task"] as const;
+export const DELEGATE_TOOL = "Agent";
+
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** The named sub-agents' folders, host-side. Unknown names are reported. */
+export function gatherSubagents(
+  workspaceRoot: string,
+  names: unknown,
+): { found: { name: string; dir: string }[]; missing: string[] } {
+  const found: { name: string; dir: string }[] = [];
+  const missing: string[] = [];
+  for (const name of refNames(names)) {
+    const dir = path.join(workspaceRoot, "agents", name);
+    if (!NAME.test(name) || !fs.existsSync(path.join(dir, "agent.md"))) missing.push(name);
+    else if (!found.some((f) => f.name === name)) found.push({ name, dir });
+  }
+  return { found, missing };
+}
+
+/**
+ * A sub-agent's tools: its own, only where the parent holds them too. An MCP
+ * tool is held when the parent holds that exact name or its whole server
+ * (`mcp__<server>` / `mcp__<server>__*`). The delegate tool never passes.
+ */
+export function subagentTools(own: string[], parent: string[]): string[] {
+  const held = new Set(parent);
+  const servers = new Set(
+    parent.filter((t) => /^mcp__[^_]/.test(t)).map((t) => t.replace(/__\*$/, "")).filter((t) => !t.slice(5).includes("__")),
+  );
+  const out: string[] = [];
+  for (const t of own) {
+    if ((DELEGATE_TOOLS as readonly string[]).includes(t) || out.includes(t)) continue;
+    const server = /^mcp__([^_].*?)__/.exec(t)?.[1];
+    if (held.has(t) || (server && servers.has(`mcp__${server}`))) out.push(t);
+  }
+  return out;
+}
+
+/** The sub-agent's system prompt: its own prose, told where it stands. It
+ *  works in the PARENT's directory — the SDK shares the session's cwd. */
+export function subagentPrompt(o: {
+  body: string;
+  name: string;
+  parent: string;
+  workspace: string;
+  shared?: string | null;
+}): string {
+  return [
+    o.body.trim(),
+    `# Where you are\n\n` +
+      `You are ${o.name}, a sub-agent started by ${o.parent} to do one job and report back. ` +
+      `You work in ${o.parent}'s directory, \`agents/${o.parent}/\` in the \`${o.workspace}\` workspace: ` +
+      `\`../../\` is the workspace root, its knowledge is at \`../../knowledge/\`, and absolute paths are refused. ` +
+      `You have only the tools listed for you. When the job is done, reply with what you found or made — ` +
+      `your reply is all ${o.parent} sees of your work, so put the facts and file paths in it.`,
+    ...(o.shared?.trim() ? [o.shared.trim()] : []),
+  ].join("\n\n");
+}
+
+/** SDK definitions. `tools` is always set — an absent list inherits every
+ *  tool the parent has, which is the one thing this module exists to stop. */
+export function toAgentDefinitions(specs: SubagentSpec[]): Record<string, {
+  description: string;
+  prompt: string;
+  tools: string[];
+  disallowedTools: string[];
+  model: string;
+}> {
+  const out: Record<string, { description: string; prompt: string; tools: string[]; disallowedTools: string[]; model: string }> = {};
+  for (const s of specs) {
+    out[s.name] = {
+      description: s.description,
+      prompt: s.prompt,
+      tools: [...s.tools],
+      disallowedTools: [...new Set([...s.disallowedTools, ...DELEGATE_TOOLS])],
+      model: s.model || "inherit",
+    };
+  }
+  return out;
+}
+
+/** One tool call as the parent's PreToolUse hook sees it. */
+export interface GuardedCall {
+  /** The SDK's agent_id: set when the call comes from inside a sub-agent. */
+  agentId?: string;
+  /** The SDK's agent_type: which sub-agent. */
+  agentType?: string;
+  tool: string;
+  input: Record<string, unknown>;
+}
+
+/**
+ * For the parent's PreToolUse hook, on a step that has sub-agents: a reason
+ * to refuse the call — or null.
+ *
+ * Only DECLARED sub-agents may run. The SDK also offers its built-ins
+ * (general-purpose and the rest, with every tool the session has); they are
+ * switched off in executeStep, and refused here too. A call from inside a
+ * sub-agent whose type is missing or not declared used to pass unjudged —
+ * `general-purpose` was a way round every sub-agent's own list.
+ */
+export function subagentGuard(specs: SubagentSpec[]): (call: GuardedCall) => string | null {
+  const by = new Map(specs.map((s) => [s.name, s]));
+  const declared = specs.map((s) => s.name).join(", ");
+  const isDelegate = (tool: string) => (DELEGATE_TOOLS as readonly string[]).includes(tool);
+  return ({ agentId, agentType, tool, input }) => {
+    if (!agentId) {
+      // The main thread: its tools are canUseTool's business — except the
+      // delegation itself, which may name only a declared sub-agent.
+      if (!isDelegate(tool)) return null;
+      const to = typeof input.subagent_type === "string" ? input.subagent_type : "";
+      if (by.has(to)) return null;
+      return `${to ? `"${to}" is not a sub-agent this step declared` : "name the sub-agent to delegate to"} — subagent_type must be one of: ${declared}`;
+    }
+    const s = agentType ? by.get(agentType) : undefined;
+    if (!s) return `${agentType ? `"${agentType}"` : "an unnamed sub-agent"} is not declared in subagents: for this step (only ${declared}) — its calls are refused`;
+    if (isDelegate(tool)) {
+      return `${s.name} is a sub-agent and cannot start another — do the work with your own tools`;
+    }
+    if (s.disallowedTools.includes(tool)) return `${tool} is disallowed for ${s.name}`;
+    if (subagentTools([tool], s.tools).length === 0) return `${tool} is not one of ${s.name}'s tools`;
+    return null;
+  };
+}
+
+/**
+ * What `foldrun check` can say without running anything: the SDK and built-in
+ * tool names two `tools:` lists grant, and their overlap. Own tools compare by
+ * name. Used to warn when a sub-agent would be left with nothing.
+ */
+export function grantedNames(tools: string[]): Set<string> {
+  const out = new Set<string>();
+  for (const t of tools) {
+    for (const n of TOOL_MAP[t] ?? [t]) out.add(n);
+  }
+  return out;
+}
+
+export function checkOverlap(parentTools: string[], subTools: string[]): string[] {
+  const parent = grantedNames(parentTools);
+  return [...grantedNames(subTools)].filter((t) => parent.has(t) && !(DELEGATE_TOOLS as readonly string[]).includes(t));
+}

package/src/tar.ts

@@ -10,6 +10,7 @@
 // argument about which library to add.
 
 import zlib from "node:zlib";
+import { trimSlashes } from "./paths.ts";
 
 const BLOCK = 512;
 
@@ -100,7 +101,7 @@ export function stripRoot(entries: TarEntry[]): TarEntry[] {
  * case, since a repo usually holds more than one thing.
  */
 export function filesFromTarball(gz: Buffer, subdir = ""): { path: string; content: string }[] {
-  const prefix = subdir.replace(/^\/+|\/+$/g, "");
+  const prefix = trimSlashes(subdir, "both");
   const out: { path: string; content: string }[] = [];
 
   for (const entry of stripRoot(readTarGz(gz))) {

package/src/test-mode.ts

@@ -0,0 +1,311 @@
+// Test mode: a run that exercises everything and changes nothing outside.
+//
+// Every desk that sends — email, SMS, orders, posts — grew its own test
+// switch inside its own script: a `test_to` address here, a `mode: test`
+// there. On 2026-09-14 a send step edited its own gate file to get past a
+// script's guard and texted 25 customers. A guard the script can reach is a
+// guard the script can move; this one lives where the script cannot: on the
+// run record, at the egress proxy, and in what the sandbox is handed.
+//
+// The rule has one table (below) so it is testable without a server, and
+// three enforcement points that all read it:
+//
+//   - the egress proxy: on a test lease, an outward write to a host that is
+//     not read-safe or a model provider is refused with 403 and a JSON body
+//     naming what would have been sent; Resend's sink address is the one
+//     exception, so a desk still gets a real message id back
+//   - the runner: send-capable secrets never enter the sandbox as values on
+//     a test run; the env var says TEST_MODE_WITHHELD instead, so a script
+//     that forgot to check fails at the provider with an auth error
+//   - the write-back: state/ and storage/ go INTO the sandbox as usual and
+//     come out into runs/<id>/test-writes/ instead of the real directories
+//
+// Nothing here weakens a live run: every function is a no-op unless the run
+// says `test: true`.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Where a test run's email actually goes — Resend's delivered sink. */
+export const TEST_SINK_EMAIL = "delivered@resend.dev";
+/** Prefixed to every subject a test run sends, so the sink is readable. */
+export const TEST_SUBJECT_PREFIX = "[TEST] ";
+/** What a withheld secret's env var reads as inside the sandbox. */
+export const WITHHELD = "TEST_MODE_WITHHELD";
+/** Both are set to "1" in a test run's sandbox: the first is what a script
+ *  checks, the second is the run-level spelling for verifies and flows. */
+export const TEST_MODE_ENV = "FOLDRUN_TEST_MODE";
+export const RUN_TEST_ENV = "FOLDRUN_RUN_TEST";
+/** Under runs/<id>/, where diverted state/ and storage/ writes land. */
+export const TEST_WRITES_DIR = "test-writes";
+/** The workspace directories a test run may not write for real. */
+export const TEST_DIVERTED_DIRS = ["state", "storage"] as const;
+
+/** What a test run did instead of the real thing — one per intervention,
+ *  on the run event that reports it, so the run page can list them. */
+export interface TestEffect {
+  kind: "refused" | "redirected" | "diverted" | "withheld";
+  host?: string;
+  method?: string;
+  path?: string;
+  summary: string;
+}
+
+// ---------------------------------------------------------------- secrets
+
+/**
+ * Secret names that can make something happen outside. Matched by name
+ * because the name is all the runner knows before the value is used: the
+ * vault does not say what a key can do, and the provider hosts are only
+ * known for http tools, not for the scripts these are withheld from.
+ */
+export const SEND_CAPABLE_SECRETS: RegExp[] = [
+  /^RESEND_API_KEY$/,
+  /^TWILIO_/,
+  /^GETREACH_API_KEY$/,
+  /^GITHUB_TOKEN$/,
+  /^MONDAY_API_TOKEN$/,
+  /^OI_CRM_API_KEY$/,
+  /^CLOUDFLARE_/,
+  /^LINKEDIN_/,
+  /^MEDIUM_COOKIES$/,
+  /^TIKTOK_/,
+];
+
+export function isSendCapableSecret(name: string): boolean {
+  return SEND_CAPABLE_SECRETS.some((re) => re.test(name));
+}
+
+/**
+ * The secrets a test-run sandbox is handed, and which were withheld.
+ *
+ * `outward` — the step grants a script tool whose file says `outward: true`:
+ * then every secret is withheld, because a tool that declared itself a
+ * sender is not one to hand anything real. `allow` — a script tool said
+ * `test_mode: allow` (a reader that happens to use a listed key): the list
+ * is not applied. Outward wins over allow, because a step that has both
+ * has a sender in it.
+ */
+export function withholdSecrets(
+  secrets: Record<string, string>,
+  opts: { outward?: boolean; allow?: boolean } = {},
+): { env: Record<string, string>; withheld: string[] } {
+  const env: Record<string, string> = {};
+  const withheld: string[] = [];
+  for (const [name, value] of Object.entries(secrets)) {
+    const hold = opts.outward || (!opts.allow && isSendCapableSecret(name));
+    env[name] = hold ? WITHHELD : value;
+    if (hold) withheld.push(name);
+  }
+  return { env, withheld };
+}
+
+// ---------------------------------------------------------------- the proxy
+
+/** Methods that read. Anything else is a write until the host says otherwise. */
+const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * Hosts an outward write may reach on a test run: model providers (the run
+ * cannot happen without them, and nothing there is a send), and read-only
+ * services whose POSTs are queries. A host is matched exactly, or by a
+ * leading `*.` for its subdomains. The list is deliberately short — the
+ * default is refusal, and a host earns its place here by having no way to
+ * reach a customer.
+ */
+export const READ_SAFE_HOSTS: string[] = [
+  // model providers
+  "api.anthropic.com",
+  "openrouter.ai",
+  "api.openai.com",
+  "generativelanguage.googleapis.com",
+  "api.groq.com",
+  "api.mistral.ai",
+  "api.together.xyz",
+  "api.deepseek.com",
+  "api.x.ai",
+  "api.fireworks.ai",
+  "api.cerebras.ai",
+  "api.perplexity.ai",
+  "*.openai.azure.com",
+  // queries that are POSTs
+  "api.dataforseo.com",
+  "*.dataforseo.com",
+  "*.svc.cluster.local",
+];
+
+export function isReadSafeHost(host: string): boolean {
+  const h = host.toLowerCase().replace(/:\d+$/, "");
+  return READ_SAFE_HOSTS.some((rule) =>
+    rule.startsWith("*.") ? h.endsWith(rule.slice(1)) && h !== rule.slice(2) : h === rule,
+  );
+}
+
+export type TestPolicy =
+  | { action: "allow" }
+  | { action: "refuse" }
+  | { action: "rewrite"; rewrite: "resend-email" };
+
+/**
+ * What the proxy does with one request on a test lease. Pure: method, host
+ * and path in, a verdict out. Reads always pass — a test run has to be able
+ * to look at the world it is not allowed to change.
+ */
+export function testPolicy(method: string, host: string, path: string): TestPolicy {
+  const m = method.toUpperCase();
+  if (READ_METHODS.has(m)) return { action: "allow" };
+  const h = host.toLowerCase().replace(/:\d+$/, "");
+  // Resend's sink: the message really goes out, to an address that keeps
+  // it, with the subject marked — so the desk sees a real id and a real
+  // 200, and nobody receives anything.
+  if (h === "api.resend.com" && /^\/emails(\/|$|\?)/.test(path)) return { action: "rewrite", rewrite: "resend-email" };
+  if (isReadSafeHost(h)) return { action: "allow" };
+  return { action: "refuse" };
+}
+
+/**
+ * A Resend `POST /emails` body with its recipients pointed at the sink and
+ * the subject marked. Returns the recipients it replaced, for the trace.
+ * Null when the body is not a JSON object — then there is nothing safe to
+ * rewrite, and the caller refuses instead.
+ */
+export function rewriteResendEmail(body: string): { body: string; to: string[] } | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const mail = parsed as Record<string, unknown>;
+  const to: string[] = [];
+  for (const field of ["to", "cc", "bcc"] as const) {
+    const v = mail[field];
+    if (v === undefined || v === null) continue;
+    for (const addr of Array.isArray(v) ? v : [v]) to.push(String(addr));
+    // One sink address for the lot: two copies of the same test mail teach
+    // nobody anything, and cc/bcc to the sink would be exactly that.
+    if (field === "to") mail[field] = [TEST_SINK_EMAIL];
+    else delete mail[field];
+  }
+  if (!Array.isArray(mail.to) || mail.to.length === 0) mail.to = [TEST_SINK_EMAIL];
+  const subject = typeof mail.subject === "string" ? mail.subject : "";
+  mail.subject = subject.startsWith(TEST_SUBJECT_PREFIX) ? subject : `${TEST_SUBJECT_PREFIX}${subject}`;
+  return { body: JSON.stringify(mail), to };
+}
+
+/** The first `max` characters of a body, whitespace collapsed — enough to
+ *  say what would have gone out, not enough to be the thing itself. The
+ *  caller redacts; this only cuts. */
+export function bodySummary(body: string, max = 200): string {
+  const flat = body.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+/** The recipient field of a body, if it has one — for `would_have.to`. */
+export function recipientsOf(body: string): string | string[] | null {
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>;
+    if (parsed && typeof parsed === "object") {
+      for (const key of ["to", "To", "recipient", "phone", "email"]) {
+        const v = parsed[key];
+        if (typeof v === "string" || Array.isArray(v)) return v as string | string[];
+      }
+    }
+  } catch {
+    // a form body: Twilio's Messages endpoint
+    const m = body.match(/(?:^|&)To=([^&]*)/);
+    if (m) return decodeURIComponent(m[1].replace(/\+/g, " "));
+  }
+  return null;
+}
+
+/** The 403 a refused write is answered with. JSON, so a script that parses
+ *  the error sees `test_mode` and can say so instead of retrying. */
+export function refusalBody(method: string, host: string, path: string, body: string): string {
+  return JSON.stringify({
+    test_mode: true,
+    error: { type: "test_mode", message: `test run: ${method} ${host}${path} refused — nothing was sent` },
+    would_have: { method, host, path, to: recipientsOf(body), body: bodySummary(body) },
+  });
+}
+
+// ---------------------------------------------------------------- write-back
+
+/** Is this workspace-relative path one a test run diverts? */
+export function isDivertedPath(rel: string): boolean {
+  const norm = rel.replaceAll("\\", "/");
+  return TEST_DIVERTED_DIRS.some((d) => norm === d || norm.startsWith(`${d}/`));
+}
+
+/** The line the trace and the run page show for one diverted write. */
+export function divertedSummary(rel: string, was: Buffer | null, next: Buffer): string {
+  if (was === null) return `would have created ${rel} (${next.length} bytes)`;
+  const before = was.toString("utf8").split("\n").length;
+  const after = next.toString("utf8").split("\n").length;
+  const delta = after - before;
+  return `would have written ${rel}${delta > 0 ? `, +${delta} line${delta === 1 ? "" : "s"}` : delta < 0 ? `, ${delta} lines` : ""}`;
+}
+
+/**
+ * The in-process path has no copy-in and copy-out — a step writes the
+ * workspace directly — so a test run there snapshots state/ and storage/
+ * before the step and, after it, moves what changed under the run and
+ * puts the originals back. Same outcome as the sandbox's divert, reached
+ * from the other side. Used by `foldrun run --test`.
+ */
+export function snapshotDivertedDirs(wsRoot: string): Map<string, Buffer> {
+  const snap = new Map<string, Buffer>();
+  for (const dir of TEST_DIVERTED_DIRS) {
+    const root = path.join(wsRoot, dir);
+    if (!fs.existsSync(root)) continue;
+    for (const entry of fs.readdirSync(root, { recursive: true, withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const abs = path.join(entry.parentPath, entry.name);
+      snap.set(path.relative(wsRoot, abs).replaceAll("\\", "/"), fs.readFileSync(abs));
+    }
+  }
+  return snap;
+}
+
+/** Undo a step's writes to the diverted directories, keeping each changed
+ *  or new file under `to` by its workspace-relative path. Deletions are
+ *  undone too — the original is put back. Returns what was set aside. */
+export function restoreDivertedDirs(
+  wsRoot: string,
+  before: Map<string, Buffer>,
+  to: string,
+  note: (rel: string, summary: string) => void,
+): string[] {
+  const now = snapshotDivertedDirs(wsRoot);
+  const aside: string[] = [];
+  for (const [rel, next] of now) {
+    const was = before.get(rel) ?? null;
+    if (was && was.equals(next)) continue;
+    const dest = path.join(to, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, next);
+    aside.push(rel);
+    note(rel, divertedSummary(rel, was, next));
+    if (was) fs.writeFileSync(path.join(wsRoot, rel), was);
+    else fs.rmSync(path.join(wsRoot, rel), { force: true });
+  }
+  for (const [rel, was] of before) {
+    if (now.has(rel)) continue;
+    fs.mkdirSync(path.dirname(path.join(wsRoot, rel)), { recursive: true });
+    fs.writeFileSync(path.join(wsRoot, rel), was);
+    note(rel, `would have deleted ${rel}`);
+    aside.push(rel);
+  }
+  return aside;
+}
+
+/** `[test] ` in front of a headline, once. */
+export function testHeadline(summary: string): string {
+  return summary.startsWith("[test]") ? summary : `[test] ${summary}`;
+}
+
+/** The env every test-run sandbox gets, beside its secrets. */
+export function testModeEnv(): Record<string, string> {
+  return { [TEST_MODE_ENV]: "1", [RUN_TEST_ENV]: "1" };
+}

package/src/tool-names.ts

@@ -14,29 +14,43 @@ import { refList, refNames, type Ref } from "./refs.ts";
 
 /** Groups: one word an author can hold in their head, expanded to SDK names. */
 export const TOOL_MAP: Record<string, string[]> = {
-  // `web` includes Anthropic's server-side WebSearch, the one built-in tool
-  // that runs off the box and bills per call. `fetch` is the local half only:
-  // an agent that searches through the account's own `websearch` tool and
-  // reads pages with WebFetch never leaves the box for anything but tokens.
-  web: ["WebSearch", "WebFetch"],
-  fetch: ["WebFetch"],
-  // `read` is deliberately separate from `files`: an agent that may inspect a
-  // repository but must never modify it is a real and common design.
+  // The web is one tool of ours, `web` — search, fetch, browse, crawl, map,
+  // extract, answer, monitor, served from the gallery and on the run record
+  // whichever model is driving. So `web` is deliberately NOT here: a name in
+  // TOOL_MAP shadows a real tool of the same name (see runner.ts).
+  // `read` is deliberately separate from `write`: an agent that may inspect a
+  // repository but must never modify it is a real and common design. The pair
+  // says what it grants. `files` and `bash` were the old names for `write`
+  // and `code` (`code`, because it is not only shell — anything in the
+  // sandbox runs through it); both are retired, below.
   read: ["Read", "Glob", "Grep"],
+  write: ["Read", "Write", "Edit", "Glob", "Grep"],
   files: ["Read", "Write", "Edit", "Glob", "Grep"],
+  code: ["Bash"],
   bash: ["Bash"],
 };
 
+/** Names an author may no longer write, and what to write instead. They are
+ *  still granted, so nothing deployed breaks; `check` and the run log say the
+ *  rewrite. */
+export const RETIRED_TOOLS: Record<string, string> = {
+  files: "write",
+  bash: "code",
+};
+
 /** Exact SDK tool names, accepted alongside the group aliases so a Claude Code
  *  subagent's `tools: Read, Grep` works unchanged. The aliases exist because
- *  vendors rename tools; `web` survives a rename that `WebSearch` would not. */
+ *  vendors rename tools; `write` survives a rename that `Write` would not.
+ *  The SDK's WebSearch and WebFetch are not here: the web is our `web` tool,
+ *  and a model provider's own search (`web: {search: zai}`) is the runtime's
+ *  to swap in, not the author's to name. */
 export const BUILTIN_TOOLS = new Set([
   "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash",
-  "WebSearch", "WebFetch", "NotebookEdit", "TodoWrite",
+  "NotebookEdit", "TodoWrite",
 ]);
 
 /** The platform's own groups, served in-process rather than by the SDK. */
-export const PLATFORM_GROUPS = new Set(["search", "history", "desks"]);
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask"]);
 
 /** Would this name resolve to something the runtime provides? Built-ins win a
  *  clash, so a tool file of the same name is shadowed rather than granted. */
@@ -85,6 +99,21 @@ export function legacyUseNames(front: ToolFrontmatter): string[] {
   return refNames(front.use);
 }
 
+/** Retired names written bare in `tools:`, deduped. A `[[link]]` is the
+ *  author's own file, so it is never one of these. */
+export function retiredToolNames(front: ToolFrontmatter): string[] {
+  const out: string[] = [];
+  for (const ref of toolRefs(front)) {
+    if (!ref.linked && RETIRED_TOOLS[ref.name] && !out.includes(ref.name)) out.push(ref.name);
+  }
+  return out;
+}
+
+/** The one sentence every reader of a retired name says. */
+export function retiredToolError(name: string): string {
+  return `tools: "${name}" is retired — use ${RETIRED_TOOLS[name]} instead: the same grant, under the name that says what it does. It is still granted for now.`;
+}
+
 /** The one sentence every reader of a `use:` key says. */
 export function legacyUseError(names: string[]): string {
   return `\`use:\` is no longer read — write \`tools: [${names.join(", ")}]\` instead (scripts/migrate-use-to-tools.mjs rewrites every agent). Nothing was granted for it.`;