@foldrun/core 0.6.0 → 1.0.0

package/README.md

@@ -222,9 +222,22 @@ allow products built on its Agent SDK to offer claude.ai login unless
 Anthropic has approved them, so check that the terms cover your use before
 you rely on a login token.
 
+## Versions
+
+[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html): a patch is
+a bug fix, a minor adds something and breaks nothing, a major breaks
+something and says what. The promise covers the **public API**, the entry
+points listed in `package.json` under `foldrun.publicApi`: `@foldrun/core`
+itself and the subpaths the `foldrun` CLI imports. Every other module under
+`@foldrun/core/*` can be reached, because the runner image imports its own
+copy by name, but it is internal and may change in any release. Deprecated
+names say so in their doc comment for at least one minor before a major
+removes them. Pre-releases are on npm's `next` tag. How a release decides
+its number: [CONTRIBUTING.md](CONTRIBUTING.md#versions).
+
 ## Status
 
-v0.1. Local and hosted runs work. Hosted runs go through a durable on-disk
+Local and hosted runs work. Hosted runs go through a durable on-disk
 queue (survives restarts, parks at approval gates), the dashboard has
 accounts and sessions (scrypt + signed cookies; first signup is free, then
 `FOLDRUN_OPEN_SIGNUP=1`), spending lands in an append-only per-account

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export * from "./src/linkable.ts";
 export * from "./src/refs.ts";
 export * from "./src/tool-names.ts";
 export * from "./src/history.ts";
+export * from "./src/zip.ts";
+export * from "./src/package.ts";
 export * from "./src/gitrepo.ts";
 export * from "./src/storage.ts";
 export * from "./src/secrets.ts";
@@ -31,6 +33,7 @@ export * from "./src/notify.ts";
 export * from "./src/webhook.ts";
 export * from "./src/approvals.ts";
 export * from "./src/deploy.ts";
+export * from "./src/agent-import.ts";
 export * from "./src/account.ts";
 export * from "./src/tar.ts";
 export * from "./src/git.ts";

package/dist/index.js

@@ -33,6 +33,8 @@ export * from "./src/linkable.js";
 export * from "./src/refs.js";
 export * from "./src/tool-names.js";
 export * from "./src/history.js";
+export * from "./src/zip.js";
+export * from "./src/package.js";
 export * from "./src/gitrepo.js";
 export * from "./src/storage.js";
 export * from "./src/secrets.js";
@@ -42,6 +44,7 @@ export * from "./src/notify.js";
 export * from "./src/webhook.js";
 export * from "./src/approvals.js";
 export * from "./src/deploy.js";
+export * from "./src/agent-import.js";
 export * from "./src/account.js";
 export * from "./src/tar.js";
 export * from "./src/git.js";

package/dist/src/agent-import.d.ts

@@ -0,0 +1,21 @@
+export interface AgentImportResult {
+    /** The name the agent has in the target workspace. */
+    name: string;
+    /** Workspace-relative paths written. */
+    files: string[];
+    /** What the copy refers to that the target workspace does not have. The
+     *  import still happens: a missing secret is set in a minute, and refusing
+     *  would make the person copy the file by hand instead. */
+    warnings: string[];
+}
+/** An error the API layer turns into a status rather than a 500. */
+export declare class AgentImportError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** The files `importAgent` would copy, without writing anything. */
+export declare function agentSourceFiles(tenant: string, from: string, agent: string): string[];
+export declare function importAgent(tenant: string, from: string, agent: string, to: string, opts?: {
+    as?: string;
+    by?: string;
+}): AgentImportResult;

package/dist/src/agent-import.js

@@ -0,0 +1,116 @@
+// Bring an agent you already have into another workspace of the same account.
+//
+// A new workspace starts blank (blankWorkspaceFiles), and the agents worth
+// having in it are usually ones already written and tuned elsewhere — a
+// researcher from one desk, a reviewer from another. Copying them by hand
+// meant opening each file, and missing the skills and scripts that live in
+// the agent's own folder. This copies the folder: what the agent IS, never
+// what it has accumulated.
+//
+// Copied: agents/<name>/agent.md and everything authored beside it — its own
+// skills/, scripts/, knowledge/. Not copied: memory/ (what it learned in the
+// other workspace's runs), outputs/, state/, the step's workspace link, and
+// the SDK's .claude session files. A fresh copy starts with no lessons that
+// were about somebody else's desk.
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { assertSafeName, listWorkspaceFiles, readWorkspaceFile, writeWorkspaceFile, workspaceDir, workspaceTools, listWorkspaces, } from "./store.js";
+import { libraryDir, libraryTools } from "./library.js";
+import { isRuntimeTool, toolEntryName } from "./tool-names.js";
+import { discoverSkills } from "./runner.js";
+import { listSecrets } from "./secrets.js";
+/** An error the API layer turns into a status rather than a 500. */
+export class AgentImportError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Accumulated or generated, not authored — never carried to another workspace. */
+const NOT_COPIED = /^agents\/[^/]+\/(memory|outputs|state|workspace|\.claude)(\/|$)|^agents\/[^/]+\/\.claude\.json$/;
+/** The files `importAgent` would copy, without writing anything. */
+export function agentSourceFiles(tenant, from, agent) {
+    const prefix = `agents/${agent}/`;
+    return listWorkspaceFiles(tenant, from).filter((p) => p.startsWith(prefix) && !NOT_COPIED.test(p));
+}
+const list = (v) => Array.isArray(v) ? v.map((x) => toolEntryName(x)).filter(Boolean) : typeof v === "string" && v.trim() ? [v.trim()] : [];
+export function importAgent(tenant, from, agent, to, opts = {}) {
+    assertSafeName(from, "workspace");
+    assertSafeName(to, "workspace");
+    assertSafeName(agent, "agent");
+    const name = opts.as?.trim() || agent;
+    assertSafeName(name, "agent");
+    const known = new Set(listWorkspaces(tenant).map((w) => w.name));
+    if (!known.has(from))
+        throw new AgentImportError(`no workspace called "${from}" in this account`, 404);
+    if (!known.has(to))
+        throw new AgentImportError(`no workspace called "${to}" in this account`, 404);
+    if (from === to && name === agent) {
+        throw new AgentImportError(`${agent} is already in ${to} — give the copy another name with "as"`, 409);
+    }
+    const files = agentSourceFiles(tenant, from, agent);
+    if (!files.includes(`agents/${agent}/agent.md`)) {
+        throw new AgentImportError(`no agent called "${agent}" in ${from}`, 404);
+    }
+    if (fs.existsSync(path.join(workspaceDir(tenant, to), "agents", name))) {
+        throw new AgentImportError(`${to} already has an agent called "${name}" — import it under another name with "as"`, 409);
+    }
+    const written = [];
+    const message = `import agents/${agent} from ${from}${name !== agent ? ` as ${name}` : ""}`;
+    let front = {};
+    for (const src of files) {
+        let content = readWorkspaceFile(tenant, from, src);
+        const rel = src.slice(`agents/${agent}/`.length);
+        if (rel === "agent.md") {
+            front = matter(content).data;
+            // The folder is the name flows address; a `name:` that disagrees with
+            // it is the first thing check would complain about.
+            if (name !== agent)
+                content = content.replace(/^(---\r?\n(?:[\s\S]*?\r?\n)?)name:[^\n]*$/m, `$1name: ${name}`);
+        }
+        const dest = `agents/${name}/${rel}`;
+        writeWorkspaceFile(tenant, to, dest, content, { ...(opts.by ? { by: opts.by } : {}), message });
+        written.push(dest);
+    }
+    return { name, files: written, warnings: missingFor(tenant, to, name, front) };
+}
+/** What the imported agent names that the target workspace cannot provide. */
+function missingFor(tenant, to, name, front) {
+    const out = [];
+    const ws = workspaceDir(tenant, to);
+    const tools = { ...libraryTools(tenant), ...workspaceTools(tenant, to) };
+    const noTool = list(front.tools).filter((t) => !isRuntimeTool(t) && !tools[t]);
+    if (noTool.length)
+        out.push(`tools not in ${to} or the account library: ${noTool.join(", ")} — import or add them under tools/`);
+    const skills = new Set();
+    for (const [base, sub] of [
+        [path.join(ws, "agents", name), "skills"],
+        [ws, "skills"],
+        [ws, ".agents/skills"],
+        [libraryDir(tenant), "skills"],
+    ]) {
+        for (const s of discoverSkills(base, sub))
+            skills.add(s.name);
+    }
+    const noSkill = list(front.skills).filter((s) => !skills.has(s));
+    if (noSkill.length)
+        out.push(`skills not in ${to} or the account library: ${noSkill.join(", ")}`);
+    const scripts = list(front.scripts).filter((s) => !fs.existsSync(path.join(ws, "agents", name, "scripts", s)) &&
+        !fs.existsSync(path.join(ws, "scripts", s)) &&
+        !fs.existsSync(path.join(libraryDir(tenant), "scripts", s)));
+    if (scripts.length)
+        out.push(`scripts not in ${to}: ${scripts.join(", ")} — copy them into scripts/`);
+    let have;
+    try {
+        have = new Set(listSecrets(tenant, to).map((s) => s.name));
+    }
+    catch {
+        have = new Set();
+    }
+    const noSecret = list(front.secrets).filter((s) => !have.has(s));
+    if (noSecret.length)
+        out.push(`secrets not set for ${to}: ${noSecret.join(", ")} — add them with \`foldrun secrets set\` or Settings → Secrets`);
+    return out;
+}

package/dist/src/api-tools.js

@@ -240,7 +240,8 @@ function genericTool(api, env, bucket, log) {
         `Allowed methods: ${api.methods.join(", ")}. Provide only the path after the base URL. ` +
         `Authentication is added automatically — never ask the user for credentials.` +
         typed +
-        rateSentence(api), {
+        rateSentence(api) +
+        (api.guide ? `\n\nHow to use it (from its tool.md):\n${api.guide}` : ""), {
         method: z.enum(api.methods).describe("HTTP method"),
         path: z.string().describe("Path appended to the base URL, e.g. /customers/123/campaigns"),
         query: z.record(z.string(), z.string()).optional().describe("Query parameters"),
@@ -291,6 +292,14 @@ resolved) {
                 `so no tool is exposed. Report it as blocked; do not reach this API another way.`);
             continue;
         }
+        // A base still holding `${FOLDRUN_API_URL}` was not filled: this install
+        // has no public address configured (a laptop, usually). Say so rather
+        // than hand the model a URL that cannot resolve.
+        if (/\$\{[A-Z_]+\}/.test(api.base)) {
+            promptLines.push(`- **${api.name}** — unavailable this run: its base \`${api.base}\` names a variable this ` +
+                `install does not set (FOLDRUN_API_URL or FOLDRUN_PUBLIC_URL). Report it as blocked.`);
+            continue;
+        }
         const typedNames = [];
         for (const op of ops) {
             tools.push(typedTool(api, op, env, bucket, log));
@@ -311,7 +320,10 @@ resolved) {
             promptLines.push(`- **${api.name}** — ${api.description} Base URL \`${api.base}\`. ` +
                 `${ops.length} typed tool${ops.length === 1 ? "" : "s"}` +
                 (withGeneric ? `, plus \`call_${api.name}\` for anything they do not cover` : "") +
-                `. Credentials are injected for you.${rateLine}`, ...listed, ...more);
+                `. Credentials are injected for you.${rateLine}`, ...listed, ...more, 
+            // Typed-only (an `operations:` allowlist) has no generic tool whose
+            // description could carry the guide, so it rides here.
+            ...(!withGeneric && api.guide ? [`  How to use it (from its tool.md):\n${api.guide}`] : []));
         }
         else {
             promptLines.push(`- **${api.name}** — call with the \`call_${api.name}\` tool. ${api.description} ` +

package/dist/src/approvals.d.ts

@@ -135,8 +135,15 @@ export declare function expireStaleGate(tenant: string, workspace: string, run:
  *
  * Only steps waiting on an event are released: a run that is also asking a
  * person a question keeps asking.
+ *
+ * `by` names who delivered it when that is known — a signed-in person or a
+ * key through the dashboard's approve route — and `step` releases one
+ * waiting step rather than all of them.
  */
-export declare function deliverEvent(tenant: string, workspace: string, runId: string, payload: string): Promise<{
+export declare function deliverEvent(tenant: string, workspace: string, runId: string, payload: string, opts?: {
+    by?: string;
+    step?: number;
+}): Promise<{
     run: RunRecord;
     steps: number[];
 }>;

package/dist/src/approvals.js

@@ -271,22 +271,27 @@ export async function expireStaleGate(tenant, workspace, run, now = Date.now())
  *
  * Only steps waiting on an event are released: a run that is also asking a
  * person a question keeps asking.
+ *
+ * `by` names who delivered it when that is known — a signed-in person or a
+ * key through the dashboard's approve route — and `step` releases one
+ * waiting step rather than all of them.
  */
-export async function deliverEvent(tenant, workspace, runId, payload) {
+export async function deliverEvent(tenant, workspace, runId, payload, opts = {}) {
     const run = readRun(tenant, workspace, runId);
     if (!run)
         throw new ApprovalError("run not found", 404);
     const waiting = run.steps
         .map((s, i) => ({ s, i }))
-        .filter(({ s }) => s.status === "awaiting-approval" && s.waitFor === "event");
-    if (waiting.length === 0)
-        throw new ApprovalError("this run is not waiting for an event", 409);
+        .filter(({ s, i }) => s.status === "awaiting-approval" && s.waitFor === "event" && (opts.step === undefined || opts.step === i));
+    if (waiting.length === 0) {
+        throw new ApprovalError(opts.step === undefined ? "this run is not waiting for an event" : `step ${opts.step} is not waiting for an event`, 409);
+    }
     for (const { s } of waiting)
         s.eventPayload = payload.slice(0, 20_000);
     writeRun(tenant, workspace, run);
     let decided = [];
     for (const { i } of waiting) {
-        const out = await decideApproval(tenant, workspace, runId, { decision: "approve", step: i, by: "by an external event" });
+        const out = await decideApproval(tenant, workspace, runId, { decision: "approve", step: i, by: opts.by ?? "by an external event" });
         decided = decided.concat(out.steps);
     }
     return { run: readRun(tenant, workspace, runId) ?? run, steps: decided };

package/dist/src/completions.js

@@ -36,6 +36,7 @@ const TOOL_GROUPS = [
     { label: "code", hint: "Bash — runs anything in the sandbox" },
     { label: "web", hint: "search, fetch, browse, crawl, map, extract, answer, monitor — providers under web:" },
     { label: "ask", hint: "ask_person — ask the person running the desk mid-step, and wait for the answer" },
+    { label: "install", hint: "install apt, pip or npm packages mid-step — every agent has it; disallowedTools: [install] removes it" },
 ];
 const SDK_TOOL_NAMES = [
     { label: "Read", hint: "exact SDK name" },

package/dist/src/confine.d.ts

@@ -36,6 +36,7 @@ export declare function isWithin(root: string, abs: string): boolean;
 export declare function expandVirtual(raw: string, roots: Roots): {
     abs: string;
     readOnly: boolean;
+    prefix: string;
 } | null;
 export declare function checkPaths(toolName: string, input: Record<string, unknown>, roots: Roots): ConfineVerdict;
 export declare function checkBash(command: string): ConfineVerdict;

package/dist/src/confine.js

@@ -176,11 +176,22 @@ export function expandVirtual(raw, roots) {
     const candidate = rel !== null && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : raw;
     for (const v of VIRTUAL) {
         if (candidate.startsWith(v.prefix)) {
-            return { abs: path.resolve(v.root(roots), candidate.slice(v.prefix.length)), readOnly: v.readOnly };
+            return { abs: path.resolve(v.root(roots), candidate.slice(v.prefix.length)), readOnly: v.readOnly, prefix: v.prefix };
         }
     }
     return null;
 }
+/** Whether `<agentDir>/workspace` is the step's link to the workspace root
+ *  (linkWorkspace), so a `workspace/…` path opens the right file as written. */
+function linkedWorkspace(roots) {
+    const link = path.join(roots.agentDir, "workspace");
+    try {
+        return fs.lstatSync(link).isSymbolicLink() && real(link) === real(path.resolve(roots.workspaceRoot));
+    }
+    catch {
+        return false;
+    }
+}
 export function checkPaths(toolName, input, roots) {
     const workspace = real(path.resolve(roots.workspaceRoot));
     const library = real(path.resolve(roots.libraryRoot));
@@ -264,9 +275,16 @@ export function checkPaths(toolName, input, roots) {
             };
         }
         // Hand the real path back to the tool, so the virtual prefix the prompt
-        // advertises is one the agent can actually open.
-        if (virtual)
+        // advertises is one the agent can actually open — unless the step's
+        // `workspace` link already opens it. Then the path is left as written,
+        // because the SDK remembers what was Read under the path the tool ran
+        // with but checks an Edit against the one the model wrote, before this
+        // hook sees it: Read workspace/x (rewritten) then Edit workspace/x was
+        // refused "File has not been read yet" on every try, and blog-desk's
+        // fact-checker spent a pass on it (run-muuhguk3-vhrg, 2026-10-05).
+        if (virtual && !(virtual.prefix === "workspace/" && linkedWorkspace(roots))) {
             rewritten = { ...(rewritten ?? input), [key]: abs };
+        }
     }
     // Glob searches from `path` (the cwd when absent) and its PATTERN never
     // climbs: `../../storage/draft/*.md` answered "No files found" with the
@@ -350,6 +368,16 @@ const PROTECTED_BASH = [
             "instead.",
     },
 ];
+/**
+ * A web address, which names a place on a server rather than in the workspace.
+ *
+ * The protected-path patterns match a bare `runs/`, so an agent calling the
+ * platform's own API — `curl https://…/api/workspaces/x/runs/<id>` — was told
+ * it was reading the run journal. The weekly retros read their week through
+ * that API and were refused on 9 Oct 2026. Only http(s): a `file://` URL is a
+ * path, and stays checked.
+ */
+const WEB_URL = /\bhttps?:\/\/[^\s'"`)]+/gi;
 export function checkBash(command) {
     for (const re of BASH_ESCAPES) {
         if (re.test(command)) {
@@ -366,10 +394,11 @@ export function checkBash(command) {
         if (!segment.trim())
             continue;
         const writes = WRITES_TO_A_FILE.test(segment);
+        const paths = segment.replace(WEB_URL, " ");
         for (const rule of PROTECTED_BASH) {
             if (rule.writeOnly && !writes)
                 continue;
-            if (rule.re.test(segment))
+            if (rule.re.test(paths))
                 return { ok: false, reason: `Bash was denied: ${rule.reason}` };
         }
     }

package/dist/src/deploy.d.ts

@@ -60,6 +60,15 @@ export declare function readTree(dir: string): DeployFile[];
  *  only the deployed files, so a library or gallery outward tool is not seen
  *  here — `foldrun check`, which resolves every scope, remains the real gate.
  *  Non-blocking by decision: the deploy proceeds and says so. */
+/**
+ * A frontmatter block that lost its opening `---`: `key: value` lines, then a
+ * lone `---`, with nothing above them. Nothing is read from it — the parser
+ * sees prose — so the agent runs with no tools and the default model, and a
+ * model told to call a tool it was never given writes the call out as text.
+ * seo-digest's editor did that every Sunday from 20 Sep to 5 Oct 2026.
+ * Returns the problem, or null.
+ */
+export declare function unopenedFrontmatter(raw: string): string | null;
 export declare function deployWarnings(files: DeployFile[]): DeployIssue[];
 export declare function deployIssues(files: DeployFile[]): DeployIssue[];
 /**

package/dist/src/deploy.js

@@ -164,6 +164,27 @@ export function readTree(dir) {
  *  only the deployed files, so a library or gallery outward tool is not seen
  *  here — `foldrun check`, which resolves every scope, remains the real gate.
  *  Non-blocking by decision: the deploy proceeds and says so. */
+/**
+ * A frontmatter block that lost its opening `---`: `key: value` lines, then a
+ * lone `---`, with nothing above them. Nothing is read from it — the parser
+ * sees prose — so the agent runs with no tools and the default model, and a
+ * model told to call a tool it was never given writes the call out as text.
+ * seo-digest's editor did that every Sunday from 20 Sep to 5 Oct 2026.
+ * Returns the problem, or null.
+ */
+export function unopenedFrontmatter(raw) {
+    const text = raw.replace(/^\uFEFF/, "");
+    if (/^---\r?\n/.test(text))
+        return null;
+    const lines = text.split(/\r?\n/);
+    const close = lines.findIndex((l) => l.trim() === "---");
+    if (close < 1)
+        return null;
+    const above = lines.slice(0, close).filter((l) => l.trim() && !l.trim().startsWith("#"));
+    if (!above.length || !above.every((l) => /^[A-Za-z_][\w-]*:(\s|$)/.test(l) || /^\s+\S/.test(l)))
+        return null;
+    return "the frontmatter has no opening `---`, so none of it is read: the agent runs with no tools and the default model. Add `---` as the first line.";
+}
 export function deployWarnings(files) {
     const front = (content) => {
         try {
@@ -190,6 +211,9 @@ export function deployWarnings(files) {
     const outwardAgents = [];
     const agentNames = [];
     const out = [];
+    if (!files.some((f) => /^agents\/[^/]+\/agent\.md$/.test(f.path)) && !files.some((f) => /^\.(claude|agents)\/agents\/[^/]+\.md$/.test(f.path))) {
+        out.push({ where: "agents/", message: "no agents yet — add one (agents/<name>/agent.md), or import one from another workspace" });
+    }
     // The web: warnings check prints — the old session: key, and a pinned
     // user agent behind the runner image's Chrome, which the platform knows
     // from FOLDRUN_RUNNER_ENGINES (the deploy read it from the image).
@@ -257,6 +281,9 @@ export function deployIssues(files) {
     for (const f of files) {
         if (!/^(AGENTS\.md|agents\/[^/]+\/agent\.md)$/.test(f.path))
             continue;
+        const unopened = unopenedFrontmatter(f.content);
+        if (unopened)
+            at(f.path, unopened);
         let front = {};
         try {
             front = matter(f.content).data;
@@ -285,9 +312,10 @@ export function deployIssues(files) {
         for (const w of localeProblems(front))
             at(f.path, w);
     }
-    if (agents.size === 0) {
-        at("agents/", "no agents — a workspace needs at least one agents/<name>/agent.md");
-    }
+    // No agents is a workspace that has not started yet — "Create workspace"
+    // makes exactly that — and deploying it is harmless: a flow that names an
+    // agent this push lacks is refused below, step by step. deployWarnings says
+    // it, so the empty state is visible without blocking the first push.
     // Flows, parsed from the incoming text rather than from disk. A step naming
     // an agent that this push does not ship is the single most common way a
     // deploy breaks a schedule, and it is free to catch here.

package/dist/src/evals.js

@@ -30,6 +30,7 @@
 // Deterministic checks run first and cost nothing. The judge only runs if
 // they pass — no point paying a model to grade output already known to be
 // wrong.
+import { accountModelEnv } from "./model-env.js";
 import { sdkEnv } from "./step-exec.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -353,7 +354,7 @@ function shell(command, cwd) {
 // The judge gets the rubric and the output, and must answer with one word.
 // Constrained output beats asking for a score: "PASS" or "FAIL" can't be
 // misread, where "7/10" needs a threshold nobody agreed on.
-async function judge(rubric, output, model, effort) {
+async function judge(rubric, output, model, effort, env) {
     const prompt = `You are grading one piece of output against one criterion. Answer with exactly ` +
         `PASS or FAIL on the first line, then one short sentence of reason.\n\n` +
         `Criterion: ${rubric}\n\n<output>\n${output.slice(0, 20000)}\n</output>`;
@@ -367,7 +368,7 @@ async function judge(rubric, output, model, effort) {
             allowedTools: [],
             settingSources: [],
             strictMcpConfig: true,
-            env: sdkEnv(undefined),
+            env,
             maxTurns: 1,
         },
     });
@@ -381,7 +382,7 @@ async function judge(rubric, output, model, effort) {
     }
     return text.trim();
 }
-async function checkAssertion(assertion, output, agentDir, model, effort) {
+async function checkAssertion(assertion, output, agentDir, model, effort, judgeEnv = () => sdkEnv(undefined)) {
     const hay = output.toLowerCase();
     switch (assertion.type) {
         case "contains": {
@@ -414,7 +415,16 @@ async function checkAssertion(assertion, output, agentDir, model, effort) {
             return { assertion, passed: code === 0, detail: `exit ${code ?? "error"}${out ? ` — ${out.slice(0, 200)}` : ""}` };
         }
         case "judge": {
-            const verdict = await judge(assertion.value, output, model, effort);
+            // The judge runs on the account's own model key, never quietly on the
+            // platform's: a customer's eval is not the operator's bill.
+            let env;
+            try {
+                env = judgeEnv();
+            }
+            catch (err) {
+                return { assertion, passed: false, detail: `judge not run — ${err instanceof Error ? err.message : String(err)}` };
+            }
+            const verdict = await judge(assertion.value, output, model, effort, env);
             const passed = /^\s*PASS\b/i.test(verdict);
             return { assertion, passed, detail: verdict.slice(0, 300) || "judge returned nothing" };
         }
@@ -485,8 +495,15 @@ export async function runEval(tenant, workspace, info) {
             for (const a of cheap)
                 assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort));
             if (assertions.every((r) => r.passed)) {
+                const judgeEnv = () => {
+                    const m = accountModelEnv(tenant, workspace, () => sdkEnv(undefined));
+                    if (m.format !== "anthropic") {
+                        throw new Error(`this account's provider speaks ${m.format}; a judge needs an Anthropic-format provider`);
+                    }
+                    return m.env;
+                };
                 for (const a of judges)
-                    assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort));
+                    assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort, judgeEnv));
             }
             else {
                 for (const a of judges) {

package/dist/src/hooks.d.ts

@@ -0,0 +1,114 @@
+export declare const HOOK_EVENTS: readonly ["tool.call", "tool.result", "step.start", "step.end"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+export declare const HOOK_TIMEOUT_DEFAULT: {
+    readonly gate: 30;
+    readonly watch: 60;
+};
+export declare const HOOK_TIMEOUT_MAX = 120;
+export declare const HOOK_CODE_MAX: number;
+export interface HookDef {
+    name: string;
+    /** The folder holding hook.md and run.mjs. */
+    dir: string;
+    scope: "workspace" | "account";
+    on: HookEvent;
+    /** `tool:` — which tools a tool.call / tool.result hook sees. Unset is all. */
+    tool?: string;
+    timeoutSec: number;
+    description?: string;
+    /** run.mjs as it was when the step started. The hook runs from this copy,
+     *  so an agent that edits the file mid-step changes nothing that runs. */
+    code: string;
+}
+/** Read hook.md, or say in one sentence why it is not a hook. */
+export declare function readHookDef(dir: string, scope: HookDef["scope"]): HookDef | {
+    error: string;
+};
+/** Every hook folder in a hooks/ directory. */
+export declare function listHookDirs(hooksDir: string): string[];
+/** The names a frontmatter `hooks:` holds — a list, or one name. */
+export declare function hookNames(raw: unknown): string[];
+/**
+ * The hooks one agent runs, in order: what the account turned on, then the
+ * workspace, then the agent itself, each name once. A name resolves to the
+ * workspace's own hooks/ first, then the library's. Names that resolve to
+ * nothing come back in `missing` — `foldrun check` errors on them, and a run
+ * refuses to start the step rather than run unguarded.
+ */
+export declare function resolveHooks(args: {
+    workspaceRoot: string;
+    libraryRoot: string;
+    names: string[];
+}): {
+    hooks: HookDef[];
+    missing: string[];
+    errors: string[];
+};
+/**
+ * Does `pattern` name this tool? Alternatives split on `|`, `*` matches any
+ * run of characters. A pattern without `__` also matches a tool's short
+ * name, so `web` catches `mcp__foldrun_scripts__web` and `Bash` catches Bash.
+ */
+export declare function matchesTool(pattern: string | undefined, tool: string): boolean;
+/** What one hook said, normalised. */
+export interface HookAnswer {
+    ok: boolean;
+    /** tool.call */
+    decision?: "allow" | "deny";
+    reason?: string;
+    input?: Record<string, unknown>;
+    /** step.start */
+    context?: string;
+    /** step.end */
+    reply?: string;
+    /** tool.result / anything: a line for the trail */
+    note?: string;
+    /** Why it failed — threw, timed out, wrong shape. */
+    failure?: string;
+    ms: number;
+}
+export declare function hookEnv(from: Record<string, string | undefined>, hook: HookDef): Record<string, string>;
+/** Run one hook on one event. Never throws: a failure is an answer. */
+export declare function runHook(hook: HookDef, event: Record<string, unknown>, opts: {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    node?: string;
+}): Promise<HookAnswer>;
+/** The last JSON object a hook printed, checked against its event's shape. */
+export declare function parseAnswer(on: HookEvent, stdout: string): Omit<HookAnswer, "ms">;
+/** What a run of tool.call hooks decided for one call. */
+export interface ToolCallVerdict {
+    decision: "allow" | "deny";
+    reason?: string;
+    /** The input after every rewrite, when any hook rewrote it. */
+    input?: Record<string, unknown>;
+    /** One line per hook that did something, for the trail. */
+    records: HookRecord[];
+}
+/** One hook's effect, as the trail keeps it. */
+export interface HookRecord {
+    hook: string;
+    event: HookEvent;
+    /** deny | rewrite | context | reply | note | error */
+    did: "deny" | "rewrite" | "context" | "reply" | "note" | "error";
+    tool?: string;
+    reason?: string;
+    ms: number;
+}
+/** A hook record as it crosses from the sandbox: checked, never trusted. */
+export declare function isHookRecord(x: unknown): x is HookRecord;
+export declare function isGate(on: HookEvent): boolean;
+/**
+ * tool.call: every matching hook in order. The first deny ends it — the most
+ * restrictive answer wins; a rewrite is handed on to the next hook, so they
+ * chain in the order they were turned on. A hook that fails denies.
+ */
+export declare function runToolCallHooks(hooks: HookDef[], call: {
+    tool: string;
+    input: Record<string, unknown>;
+    base: Record<string, unknown>;
+}, run: (hook: HookDef, event: Record<string, unknown>) => Promise<HookAnswer>): Promise<ToolCallVerdict>;
+/** The trail's line for a record. */
+export declare function hookLine(r: HookRecord): string;
+/** For `foldrun check`: every problem with the hooks/ folder of one root. */
+export declare function checkHooksDir(hooksDir: string, scope: HookDef["scope"]): string[];