@foldrun/core 0.3.0 → 0.5.0

package/dist/src/subagents.d.ts

@@ -0,0 +1,75 @@
+/** 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 declare const DELEGATE_TOOLS: readonly ["Agent", "Task"];
+export declare const DELEGATE_TOOL = "Agent";
+/** The named sub-agents' folders, host-side. Unknown names are reported. */
+export declare function gatherSubagents(workspaceRoot: string, names: unknown): {
+    found: {
+        name: string;
+        dir: string;
+    }[];
+    missing: string[];
+};
+/**
+ * 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 declare function subagentTools(own: string[], parent: string[]): string[];
+/** 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 declare function subagentPrompt(o: {
+    body: string;
+    name: string;
+    parent: string;
+    workspace: string;
+    shared?: string | null;
+}): string;
+/** 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 declare function toAgentDefinitions(specs: SubagentSpec[]): Record<string, {
+    description: string;
+    prompt: string;
+    tools: string[];
+    disallowedTools: string[];
+    model: string;
+}>;
+/** 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 declare function subagentGuard(specs: SubagentSpec[]): (call: GuardedCall) => string | 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 declare function grantedNames(tools: string[]): Set<string>;
+export declare function checkOverlap(parentTools: string[], subTools: string[]): string[];

package/dist/src/subagents.js

@@ -0,0 +1,149 @@
+// 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.js";
+import { TOOL_MAP } from "./tool-names.js";
+/** 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"];
+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, names) {
+    const found = [];
+    const missing = [];
+    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, parent) {
+    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 = [];
+    for (const t of own) {
+        if (DELEGATE_TOOLS.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) {
+    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) {
+    const out = {};
+    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;
+}
+/**
+ * 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) {
+    const by = new Map(specs.map((s) => [s.name, s]));
+    const declared = specs.map((s) => s.name).join(", ");
+    const isDelegate = (tool) => DELEGATE_TOOLS.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) {
+    const out = new Set();
+    for (const t of tools) {
+        for (const n of TOOL_MAP[t] ?? [t])
+            out.add(n);
+    }
+    return out;
+}
+export function checkOverlap(parentTools, subTools) {
+    const parent = grantedNames(parentTools);
+    return [...grantedNames(subTools)].filter((t) => parent.has(t) && !DELEGATE_TOOLS.includes(t));
+}

package/dist/src/tar.js

@@ -9,6 +9,7 @@
 // 512-byte blocks with an octal size field, and a reader is shorter than the
 // argument about which library to add.
 import zlib from "node:zlib";
+import { trimSlashes } from "./paths.js";
 const BLOCK = 512;
 const str = (b, off, len) => {
     const raw = b.subarray(off, off + len);
@@ -86,7 +87,7 @@ export function stripRoot(entries) {
  * case, since a repo usually holds more than one thing.
  */
 export function filesFromTarball(gz, subdir = "") {
-    const prefix = subdir.replace(/^\/+|\/+$/g, "");
+    const prefix = trimSlashes(subdir, "both");
     const out = [];
     for (const entry of stripRoot(readTarGz(gz))) {
         let rel = entry.path;

package/dist/src/test-mode.d.ts

@@ -0,0 +1,111 @@
+/** Where a test run's email actually goes — Resend's delivered sink. */
+export declare const TEST_SINK_EMAIL = "delivered@resend.dev";
+/** Prefixed to every subject a test run sends, so the sink is readable. */
+export declare const TEST_SUBJECT_PREFIX = "[TEST] ";
+/** What a withheld secret's env var reads as inside the sandbox. */
+export declare 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 declare const TEST_MODE_ENV = "FOLDRUN_TEST_MODE";
+export declare const RUN_TEST_ENV = "FOLDRUN_RUN_TEST";
+/** Under runs/<id>/, where diverted state/ and storage/ writes land. */
+export declare const TEST_WRITES_DIR = "test-writes";
+/** The workspace directories a test run may not write for real. */
+export declare const TEST_DIVERTED_DIRS: readonly ["state", "storage"];
+/** 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;
+}
+/**
+ * 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 declare const SEND_CAPABLE_SECRETS: RegExp[];
+export declare function isSendCapableSecret(name: string): boolean;
+/**
+ * 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 declare function withholdSecrets(secrets: Record<string, string>, opts?: {
+    outward?: boolean;
+    allow?: boolean;
+}): {
+    env: Record<string, string>;
+    withheld: string[];
+};
+/**
+ * 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 declare const READ_SAFE_HOSTS: string[];
+export declare function isReadSafeHost(host: string): boolean;
+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 declare function testPolicy(method: string, host: string, path: string): TestPolicy;
+/**
+ * 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 declare function rewriteResendEmail(body: string): {
+    body: string;
+    to: string[];
+} | null;
+/** 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 declare function bodySummary(body: string, max?: number): string;
+/** The recipient field of a body, if it has one — for `would_have.to`. */
+export declare function recipientsOf(body: string): string | string[] | 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 declare function refusalBody(method: string, host: string, path: string, body: string): string;
+/** Is this workspace-relative path one a test run diverts? */
+export declare function isDivertedPath(rel: string): boolean;
+/** The line the trace and the run page show for one diverted write. */
+export declare function divertedSummary(rel: string, was: Buffer | null, next: Buffer): string;
+/**
+ * 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 declare function snapshotDivertedDirs(wsRoot: string): Map<string, Buffer>;
+/** 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 declare function restoreDivertedDirs(wsRoot: string, before: Map<string, Buffer>, to: string, note: (rel: string, summary: string) => void): string[];
+/** `[test] ` in front of a headline, once. */
+export declare function testHeadline(summary: string): string;
+/** The env every test-run sandbox gets, beside its secrets. */
+export declare function testModeEnv(): Record<string, string>;

package/dist/src/test-mode.js

@@ -0,0 +1,285 @@
+// 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"];
+// ---------------------------------------------------------------- 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 = [
+    /^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) {
+    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, opts = {}) {
+    const env = {};
+    const withheld = [];
+    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 = [
+    // 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) {
+    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);
+}
+/**
+ * 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, host, path) {
+    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) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const mail = parsed;
+    const to = [];
+    for (const field of ["to", "cc", "bcc"]) {
+        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, max = 200) {
+    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) {
+    try {
+        const parsed = JSON.parse(body);
+        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;
+            }
+        }
+    }
+    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, host, path, body) {
+    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) {
+    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, was, next) {
+    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) {
+    const snap = new Map();
+    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, before, to, note) {
+    const now = snapshotDivertedDirs(wsRoot);
+    const aside = [];
+    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) {
+    return summary.startsWith("[test]") ? summary : `[test] ${summary}`;
+}
+/** The env every test-run sandbox gets, beside its secrets. */
+export function testModeEnv() {
+    return { [TEST_MODE_ENV]: "1", [RUN_TEST_ENV]: "1" };
+}

package/dist/src/tool-names.d.ts

@@ -1,9 +1,16 @@
 import { type Ref } from "./refs.ts";
 /** Groups: one word an author can hold in their head, expanded to SDK names. */
 export declare const TOOL_MAP: Record<string, string[]>;
+/** 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 declare const RETIRED_TOOLS: Record<string, string>;
 /** 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 declare const BUILTIN_TOOLS: Set<string>;
 /** The platform's own groups, served in-process rather than by the SDK. */
 export declare const PLATFORM_GROUPS: Set<string>;
@@ -34,6 +41,11 @@ export declare function ownToolNames(front: ToolFrontmatter): string[];
 /** What a file still says under the removed `use:` key — nothing is granted
  *  for these; they exist so the error can quote the exact `tools:` line. */
 export declare function legacyUseNames(front: ToolFrontmatter): string[];
+/** Retired names written bare in `tools:`, deduped. A `[[link]]` is the
+ *  author's own file, so it is never one of these. */
+export declare function retiredToolNames(front: ToolFrontmatter): string[];
+/** The one sentence every reader of a retired name says. */
+export declare function retiredToolError(name: string): string;
 /** The one sentence every reader of a `use:` key says. */
 export declare function legacyUseError(names: string[]): string;
 export {};