@foldrun/core 0.6.0 → 1.0.0

package/dist/src/step-exec.js

@@ -7,6 +7,7 @@
 // assembles the system prompt and builds MCP servers, then hands this the
 // results. That is what lets the same function run somewhere the vault, the
 // library and the account do not exist.
+import { runHook, runToolCallHooks, matchesTool, hookLine, resolveHooks } from "./hooks.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -169,8 +170,49 @@ async function executeStepInner(opts, runQuery) {
     // `limits:` — this step's counts. A new step, a retry of one, or a
     // fan-out instance each start from zero.
     const counter = new CallCounter(opts.limits);
+    // Hooks (hooks.ts): the person's own code at this dispatch, same on every
+    // model. Each runs in the agent's directory with a bare environment.
+    let hooks = opts.hooks ?? [];
+    if (opts.hookNames?.length) {
+        const r = resolveHooks({ workspaceRoot, libraryRoot, names: opts.hookNames });
+        const bad = [...r.missing.map((n) => `no hook named ${n} in hooks/ or the library`), ...r.errors];
+        if (bad.length) {
+            emit("error", `hooks: ${bad.join("; ")} — the step is refused rather than run without its hooks`);
+            return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+        }
+        hooks = [...hooks, ...r.hooks];
+    }
+    const hookBase = { ...(opts.hookBase ?? {}) };
+    const callHook = (hook, event) => runHook(hook, event, { cwd: agentDir, env: opts.env });
+    const record = (r, via) => emit(r.did === "error" || r.did === "deny" ? "error" : "info", hookLine(r), { hook: r, ...(via ? { subagent: via } : {}) });
+    // step.start — a gate: context it returns goes in front of the task; a
+    // hook that fails refuses the step rather than run it unguarded.
+    let prompt = opts.prompt;
+    for (const hook of hooks.filter((h) => h.on === "step.start")) {
+        const a = await callHook(hook, { ...hookBase, event: "step.start", hook: hook.name, prompt });
+        if (!a.ok) {
+            record({ hook: hook.name, event: "step.start", did: "error", reason: `${a.failure}, so the step is refused`, ms: a.ms });
+            return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+        }
+        // Exit 2 is a deny on every event (runHook). On a gate that means the
+        // step does not run — it used to come back ok with no context, and the
+        // step went ahead as if the hook had agreed.
+        if (a.decision === "deny") {
+            record({ hook: hook.name, event: "step.start", did: "deny", reason: `${a.reason}, so the step is refused`, ms: a.ms });
+            return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+        }
+        if (a.context) {
+            prompt = `${prompt}\n\n${a.context}`;
+            record({ hook: hook.name, event: "step.start", did: "context", ms: a.ms });
+        }
+        else if (a.note) {
+            record({ hook: hook.name, event: "step.start", did: "note", reason: a.note, ms: a.ms });
+        }
+    }
+    const toolHooks = hooks.filter((h) => h.on === "tool.call");
+    const resultHooks = hooks.filter((h) => h.on === "tool.result");
     const q = runQuery({
-        prompt: opts.prompt,
+        prompt,
         options: {
             cwd: agentDir,
             abortController: abort,
@@ -188,6 +230,13 @@ async function executeStepInner(opts, runQuery) {
             // declares no tools gets none, instead of seeing the full Claude
             // Code toolset and burning turns on denied calls.
             tools: opts.allowed,
+            // Stated, never left to the SDK. Unset, it chose its own mode for the
+            // login it ran under, and in auto mode its classifier refused a granted
+            // script before canUseTool saw it: "denied by the Claude Code auto mode
+            // classifier. Reason: [Irreversible Local Destruction]" for backlink-
+            // desk's outreach_reset, which only marks old bodies STALE (2026-10-04
+            // and 05). The decision is ours: canUseTool and the PreToolUse hook.
+            permissionMode: "default",
             // Deliberately NOT allowedTools: listing them there auto-approves and
             // skips canUseTool entirely, which is where confinement happens. The
             // toolset is still restricted by `tools` above.
@@ -265,6 +314,46 @@ async function executeStepInner(opts, runQuery) {
                                         return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: refusal.message } };
                                     }
                                 }
+                                // tool.call hooks — after foldrun's own checks, so a hook never
+                                // sees a call that was going to be refused anyway, and handed the
+                                // input as the tool would get it (the workspace/ prefix expanded).
+                                if (toolHooks.length) {
+                                    const input = (verdict?.updatedInput ?? hookInput.tool_input ?? {});
+                                    // A sub-agent's call says so: a hook that guards the step's own
+                                    // model differently from its delegates can tell them apart.
+                                    const v = await runToolCallHooks(toolHooks, { tool: hookInput.tool_name, input, base: via ? { ...hookBase, subagent: via } : hookBase }, callHook);
+                                    for (const r of v.records)
+                                        record(r, via);
+                                    const refundCall = () => { if (counter.active)
+                                        counter.refund(limitKeysFor(hookInput.tool_name, hookInput.tool_input, opts.toolOwners)); };
+                                    if (v.decision === "deny") {
+                                        refundCall();
+                                        return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: v.reason } };
+                                    }
+                                    if (v.input) {
+                                        // A rewritten call is answered "allow", and an allow skips
+                                        // canUseTool — where the shell and path confinement live. So
+                                        // the rewrite goes through the same checks here: a hook can
+                                        // narrow what the agent does, never widen it.
+                                        const again = hookInput.tool_name === "Bash"
+                                            ? checkBash(String(v.input.command ?? ""))
+                                            : isFilesystemTool(hookInput.tool_name)
+                                                ? checkPaths(hookInput.tool_name, v.input, { agentDir, workspaceRoot, libraryRoot })
+                                                : { ok: true };
+                                        const granted = opts.allowed.includes(hookInput.tool_name) || opts.mcpNames.some((n) => hookInput.tool_name.startsWith(`mcp__${n}__`));
+                                        // The sub-agent guard read the ORIGINAL input: a rewrite of a
+                                        // delegation could otherwise swap subagent_type for one this
+                                        // step never declared (or the SDK's general-purpose).
+                                        const delegation = guardSubagent ? guardSubagent({ agentId, agentType, tool: hookInput.tool_name, input: v.input }) : null;
+                                        if (!again.ok || !granted || delegation) {
+                                            refundCall();
+                                            const why = !granted ? `Tool ${hookInput.tool_name} is not enabled for this agent.` : delegation ? `the rewritten call: ${delegation}` : `the rewritten call: ${again.reason}`;
+                                            emit("error", why, via ? { subagent: via } : undefined);
+                                            return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: why } };
+                                        }
+                                        return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: again.updatedInput ?? v.input } };
+                                    }
+                                }
                                 if (!verdict?.updatedInput)
                                     return {};
                                 return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: verdict.updatedInput } };
@@ -274,12 +363,26 @@ async function executeStepInner(opts, runQuery) {
                 // after its next tool call, as context — never as a change to what it
                 // may do. A model that is only writing, calling no tools, hears it at
                 // the next call it makes.
-                ...(opts.inbox
+                ...(opts.inbox || resultHooks.length
                     ? {
                         PostToolUse: [{
                                 hooks: [async (hookInput) => {
                                         if (hookInput.hook_event_name !== "PostToolUse")
                                             return {};
+                                        // tool.result hooks watch: the call has happened, so one
+                                        // that fails is recorded and the step goes on.
+                                        for (const hook of resultHooks) {
+                                            if (!matchesTool(hook.tool, hookInput.tool_name))
+                                                continue;
+                                            const response = hookInput.tool_response;
+                                            const a = await callHook(hook, { ...hookBase, event: "tool.result", hook: hook.name, tool: { name: hookInput.tool_name, input: hookInput.tool_input ?? {} }, result: response ?? null });
+                                            if (!a.ok)
+                                                record({ hook: hook.name, event: "tool.result", did: "error", tool: hookInput.tool_name, reason: a.failure, ms: a.ms });
+                                            else if (a.note)
+                                                record({ hook: hook.name, event: "tool.result", did: "note", tool: hookInput.tool_name, reason: a.note, ms: a.ms });
+                                        }
+                                        if (!opts.inbox)
+                                            return {};
                                         // A sub-agent's call: the message is for the step's own
                                         // model, and draining it here would hand it to a context
                                         // that ends with the delegation — and lose it.
@@ -511,12 +614,25 @@ async function executeStepInner(opts, runQuery) {
                             ...(block.is_error ? { err: true } : {}),
                             ...(open.subagent ? { subagent: open.subagent } : {}),
                         });
+                        // Why it failed, on the trail. The span above carried only `err`,
+                        // so a refused call left the agent's own guess as the only account
+                        // of it: backlink-desk's outreach_reset "denied by the permission
+                        // classifier" (run-muufboma-2t6l, 2026-10-05) could not be checked.
+                        if (block.is_error) {
+                            const why = toolResultText(block.content).replace(/\s+/g, " ").trim().slice(0, 300);
+                            if (why)
+                                emit("error", `${open.name}: ${why}`, { call: block.tool_use_id, ...(open.subagent ? { subagent: open.subagent } : {}) });
+                        }
                         readPod(block.tool_use_id);
                     }
                 }
             }
             else if (message.type === "result") {
                 status = message.subtype === "success" ? "completed" : "failed";
+                // Calls the SDK itself refused, which canUseTool never saw.
+                for (const d of ("permission_denials" in message && Array.isArray(message.permission_denials) ? message.permission_denials : [])) {
+                    emit("error", `refused before it ran: ${String(d.tool_name ?? "a tool")}`);
+                }
                 if (message.subtype === "error_max_turns") {
                     emit("error", `stopped after ${opts.maxTurns ?? "its"} turns (max_turns: in the flow file) — the step did not finish`);
                 }
@@ -594,6 +710,21 @@ async function executeStepInner(opts, runQuery) {
         status = "failed";
         emit("error", "the model stream ended without a result — the model process likely died (out of memory?)");
     }
+    // step.end hooks watch the reply, and may rewrite it. One that fails is
+    // recorded and the reply stands: the work it describes is done.
+    if (status === "completed") {
+        for (const hook of hooks.filter((h) => h.on === "step.end")) {
+            const a = await callHook(hook, { ...hookBase, event: "step.end", hook: hook.name, reply: texts.join("\n").trim() });
+            if (!a.ok)
+                record({ hook: hook.name, event: "step.end", did: "error", reason: a.failure, ms: a.ms });
+            else if (a.reply !== undefined) {
+                texts.splice(0, texts.length, a.reply);
+                record({ hook: hook.name, event: "step.end", did: "reply", ms: a.ms });
+            }
+            else if (a.note)
+                record({ hook: hook.name, event: "step.end", did: "note", reason: a.note, ms: a.ms });
+        }
+    }
     const result = texts.join("\n").trim() || null;
     // A step's reply is not one message: the model narrates ("Now let me read
     // the outputs…"), calls tools, and answers last. Joining those and reading
@@ -801,7 +932,13 @@ export async function checkVerify(agentDir, verify, ctx) {
             return { ok, headline: ok ? "present and non-empty" : `${value} is missing or empty`, detail: "" };
         }
         case "judge": {
-            const verdict = await judgeReply(value, output, ctx.modelEnv ?? {}, ctx.signal);
+            // The reply is the final turn, as everywhere else; every turn goes
+            // beside it as the work, so a claim about what the step did can still
+            // be checked. Both as one <reply> failed `judge: the reply opens with
+            // GOOD` on a reply that did (fix-desk, run-muwevg72-7mza): the joined
+            // text opened with the narration before it.
+            const reply = ctx.conclusion?.trim() ? ctx.conclusion : output;
+            const verdict = await judgeReply(value, reply, output, ctx.modelEnv ?? {}, ctx.signal);
             const ok = /^\s*PASS\b/i.test(verdict);
             return { ok, headline: ok ? "PASS" : "FAIL", detail: verdict.slice(0, 300) };
         }
@@ -813,7 +950,18 @@ export async function checkVerify(agentDir, verify, ctx) {
  * Same shape as the eval judge, and answered with one word first so the
  * verdict is a prefix test rather than a reading.
  */
-async function judgeReply(rubric, output, env, signal) {
+export function judgePrompt(rubric, reply, work) {
+    const shown = reply.slice(0, 20_000);
+    const context = work.trim() && work.trim() !== reply.trim()
+        ? `Everything the step wrote while working, for context. "The reply" means only the reply block below, ` +
+            `never this:\n<work>\n${work.slice(-20_000)}\n</work>\n\n`
+        : "";
+    return (`You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
+        `first word, then one sentence of reason.\n\nRequirement: ${rubric}\n\n` +
+        context +
+        `<reply>\n${shown}\n</reply>`);
+}
+async function judgeReply(rubric, reply, work, env, signal) {
     const texts = [];
     const abortController = new AbortController();
     if (signal?.aborted)
@@ -821,9 +969,7 @@ async function judgeReply(rubric, output, env, signal) {
     signal?.addEventListener("abort", () => abortController.abort(), { once: true });
     try {
         const q = query({
-            prompt: `You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
-                `first word, then one sentence of reason.\n\nRequirement: ${rubric}\n\n` +
-                `<reply>\n${output.slice(0, 40_000)}\n</reply>`,
+            prompt: judgePrompt(rubric, reply, work),
             options: {
                 model: "haiku",
                 systemPrompt: "You grade text against a stated requirement. Be strict and literal.",
@@ -914,3 +1060,15 @@ function runVerify(agentDir, command, env, data, signal) {
 export function sdkEnv(base, extra = {}) {
     return { ...(base ?? process.env), ...extra, ENABLE_CLAUDEAI_MCP_SERVERS: "false" };
 }
+/** The text of a tool result, whichever shape it came in: a string, or a
+ *  list of content blocks of which only the text ones say anything. */
+export function toolResultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((b) => !!b && b.type === "text" && typeof b.text === "string")
+        .map((b) => b.text)
+        .join(" ");
+}

package/dist/src/storage.d.ts

@@ -128,6 +128,10 @@ export declare function uploadUrl(tenant: string, workspace: string, rel: string
  * is worth writing when a workspace actually outgrows its quota, not before.
  */
 export declare function materializeFiles(tenant: string, workspace: string): Promise<string[]>;
+/** path → sha of every stored file: what `storage/` holds once
+ *  materializeFiles has run. A run keeps it to tell its own writes from the
+ *  files it was handed. */
+export declare function storageBaseline(tenant: string, workspace: string): Record<string, string>;
 /**
  * Take what the run left in `storage/` back into the store, stamped with the
  * run that wrote it.
@@ -136,7 +140,9 @@ export declare function materializeFiles(tenant: string, workspace: string): Pro
  * derived from the index, so anything on disk that the index does not already
  * describe with the same size and hash is, by construction, new work.
  */
-export declare function harvestFiles(tenant: string, workspace: string, by: string): Promise<{
+export declare function harvestFiles(tenant: string, workspace: string, by: string, opts?: {
+    changedFrom?: Record<string, string>;
+}): Promise<{
     saved: string[];
     errors: string[];
 }>;

package/dist/src/storage.js

@@ -686,6 +686,14 @@ export async function materializeFiles(tenant, workspace) {
     fs.mkdirSync(root, { recursive: true });
     return brought;
 }
+/** path → sha of every stored file: what `storage/` holds once
+ *  materializeFiles has run. A run keeps it to tell its own writes from the
+ *  files it was handed. */
+export function storageBaseline(tenant, workspace) {
+    if (!fileStoreEnabled())
+        return {};
+    return Object.fromEntries(readIndex(tenant, workspace).files.map((f) => [f.path, f.sha]));
+}
 /**
  * Take what the run left in `storage/` back into the store, stamped with the
  * run that wrote it.
@@ -694,7 +702,7 @@ export async function materializeFiles(tenant, workspace) {
  * derived from the index, so anything on disk that the index does not already
  * describe with the same size and hash is, by construction, new work.
  */
-export async function harvestFiles(tenant, workspace, by) {
+export async function harvestFiles(tenant, workspace, by, opts = {}) {
     if (!fileStoreEnabled())
         return { saved: [], errors: [] };
     adoptLegacyFilesDir(workspaceDir(tenant, workspace));
@@ -729,6 +737,11 @@ export async function harvestFiles(tenant, workspace, by) {
                 if (sha256(fs.readFileSync(abs)) === previous.sha)
                     continue;
             }
+            // Only what the run itself changed: a file still holding the bytes it
+            // was handed is not this run's work, and the index may have moved on
+            // since (an upload while the run was going) — that must win.
+            if (opts.changedFrom && opts.changedFrom[norm] === sha256(fs.readFileSync(abs)))
+                continue;
             await putFileQuietly(tenant, workspace, norm, fs.readFileSync(abs), by);
             saved.push(norm);
         }

package/dist/src/store.d.ts

@@ -20,7 +20,7 @@ import { type WireFormat, type AuthShape } from "./providers.ts";
  * core needs to know about which one it's in.
  */
 export { singleWorkspace };
-export declare const WORKSPACE_DIRS: readonly ["agents", "flows", "evals", "skills", "memory", "knowledge", "tools", "scripts", "state"];
+export declare const WORKSPACE_DIRS: readonly ["agents", "flows", "evals", "skills", "memory", "knowledge", "tools", "scripts", "hooks", "state"];
 export declare const STORAGE_DIR = "storage";
 /** What this directory was called before. Read-only: nothing writes here any
  *  more, but installs created before the rename have bytes under it, and a
@@ -188,6 +188,15 @@ export declare function fencedCodeBlock(body: string): {
  * failure costs something that cannot be taken back. See `lintFlow`.
  */
 export declare function toolIsOutward(data: Record<string, unknown>): boolean;
+/** How much of a tool.md body rides to the model with the tool. */
+export declare const TOOL_GUIDE_MAX = 6000;
+/**
+ * The prose under a tool.md's frontmatter: how to call it, what it refuses,
+ * what its output means. Only `description:` used to reach the model, so
+ * agents invented what the body documented (5 Oct 2026). The fenced program
+ * of a single-file tool is code, not guidance, and stays out.
+ */
+export declare function toolGuide(body: string | undefined, inlineProgram?: boolean): string | undefined;
 export declare function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null;
 /**
  * Tools in a directory, in both shapes.
@@ -234,6 +243,8 @@ export interface ApiSpec {
     name: string;
     base: string;
     description: string;
+    /** The tool.md body, for the model (see toolGuide). */
+    guide?: string;
     headers: Record<string, string>;
     query: Record<string, string>;
     methods: string[];
@@ -846,6 +857,9 @@ export declare function setWorkspaceDescription(tenant: string, workspace: strin
  * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
  * so every workspace made from the dashboard was born in the old format.
  */
+/** What the dashboard's "Create workspace" makes: blank (blankWorkspaceFiles),
+ *  minus the laptop-only files, for the same reason as templateFiles. */
+export declare function blankTemplateFiles(workspace: string): DeployFile[];
 export declare function templateFiles(workspace: string): DeployFile[];
 export declare const AGENT_TEMPLATE: (name: string) => string;
 export declare const FLOW_TEMPLATE: (name: string, firstAgent: string) => string;
@@ -879,6 +893,16 @@ export interface RunEvent {
      *  detail), `output: json`, a schema. What the runner reads to decline a
      *  retry of an outward step whose tools already ran. */
     check?: boolean;
+    /** Set on the line a hook wrote — a deny, a rewrite, context, a failure
+     *  (hooks.ts). The run page and the Hooks page read these. */
+    hook?: {
+        hook: string;
+        event: string;
+        did: string;
+        tool?: string;
+        reason?: string;
+        ms: number;
+    };
 }
 /** A question an agent asked a person while its step ran (tools: [ask]). */
 export interface StepQuestion {
@@ -1341,6 +1365,12 @@ export declare function runCost(run: RunRecord): number;
  * fan-out template is a row in the trace rather than work — billing any of
  * them would charge for steps the customer can see never executed, which is
  * the fastest way to lose an argument about an invoice.
+ *
+ * Tokens count only for steps that ran on the platform's own model
+ * credential. A step on the account's own key (`credential` "provider: …" —
+ * a provider: block, or Settings → Model) was paid for at the provider, and
+ * billing it again here charged a BYOK customer twice. And a carried step's
+ * tokens were billed where it ran, like its compute.
  */
 export declare function runMeter(run: RunRecord): {
     tokenCostUsd: number;

package/dist/src/store.js

@@ -19,6 +19,7 @@
 // or an agent, and belongs in git.
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
+import { expandPlatformVars } from "./host-env.js";
 import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
@@ -50,7 +51,7 @@ import { localeProblems } from "./locale.js";
 import { readBundle, syncIndex, appendLog, provenanceMarks, syncWorkspaceBundles, } from "./okf.js";
 import { readTransport, KINDS } from "./kinds.js";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS } from "./providers.js";
-import { starterFiles, accountFiles } from "./starter.js";
+import { starterFiles, accountFiles, blankWorkspaceFiles } from "./starter.js";
 import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.js";
 // Where workspaces live. The hosted app keeps many under data/; the CLI runs
 // against one folder, which is what `foldrun run ./my-desk` has to mean.
@@ -73,6 +74,7 @@ export const WORKSPACE_DIRS = [
     "knowledge",
     "tools",
     "scripts",
+    "hooks",
     "state",
 ];
 const IN_WORKSPACE_DIR = new RegExp(`^(${WORKSPACE_DIRS.join("|")})/`);
@@ -288,6 +290,18 @@ export function assertCanonicalCase(rel) {
 // trigger-log.jsonl: the scheduler's record of why a flow did or did not
 // fire (trigger-log.ts). Before it was listed here every deploy erased it.
 export const PLATFORM_FILES = ["secrets.json", "hooks.json", "hook-deliveries.jsonl", ".repo.json", "trigger-log.jsonl"];
+// The agent engine's own home files. Each step's sandbox runs the Claude
+// Agent SDK — the engine, whatever model answers — with its home in the
+// agent's folder, and the engine writes its settings (.claude.json, its
+// backups), plugin caches and the full transcript of every session
+// (.claude/projects/*.jsonl) there. Nothing in foldrun reads them. Copied
+// back after every step, they had piled up to 5,274 files and 19 MB in one
+// agent's folder on the box by 6 Oct 2026, carried every past conversation
+// into every sandbox, and their clashing rewrites were the "write-back
+// conflict on .claude.json" lines (and the big merges) of that day. A
+// workspace's own .claude/agents/*.md — Claude Code subagents an author
+// writes, imported as agents — sits at the workspace root and is untouched.
+const ENGINE_HOME_RE = /^agents\/[^/]+\/\.claude([./]|$)/;
 /** True for anything the platform, not the author or the agent, writes. */
 export function isPlatformPath(rel) {
     const norm = rel.replaceAll("\\", "/");
@@ -299,6 +313,8 @@ export function isPlatformPath(rel) {
         return true;
     if (norm === "trigger-log.jsonl.tmp")
         return true;
+    if (ENGINE_HOME_RE.test(norm))
+        return true;
     return norm === "runs" || norm.startsWith("runs/") || norm === ".foldrun" || norm.startsWith(".foldrun/");
 }
 /** What a deploy keeps whatever it ships — the rule above saveWorkspace's
@@ -547,6 +563,28 @@ export function fencedCodeBlock(body) {
 export function toolIsOutward(data) {
     return data.outward === true;
 }
+/** How much of a tool.md body rides to the model with the tool. */
+export const TOOL_GUIDE_MAX = 6000;
+/**
+ * The prose under a tool.md's frontmatter: how to call it, what it refuses,
+ * what its output means. Only `description:` used to reach the model, so
+ * agents invented what the body documented (5 Oct 2026). The fenced program
+ * of a single-file tool is code, not guidance, and stays out.
+ */
+export function toolGuide(body, inlineProgram = false) {
+    if (!body)
+        return undefined;
+    let text = body.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+    // Only a single-file tool's program is cut; in a `run:` tool every fenced
+    // block is an example of a call, which is exactly what the model needs.
+    const inline = inlineProgram ? fencedCodeBlock(text) : null;
+    if (inline)
+        text = text.slice(0, inline.start) + text.slice(inline.end);
+    text = text.trim();
+    if (!text)
+        return undefined;
+    return text.length > TOOL_GUIDE_MAX ? `${text.slice(0, TOOL_GUIDE_MAX)}\n\n[the rest of tool.md is cut here]` : text;
+}
 export function parseToolDef(data, fallbackName, body) {
     const name = typeof data.name === "string" ? data.name : fallbackName;
     // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -580,18 +618,28 @@ export function parseToolDef(data, fallbackName, body) {
         };
     }
     if (kind === "script") {
+        // `guide` is the body's, never the frontmatter's: an author's `guide:`
+        // would otherwise ride to the model in place of the manual.
+        if ("guide" in data) {
+            data = { ...data };
+            delete data.guide;
+        }
         // The program is a run: path, or the file's own fenced code block — the
         // single-file form, which is what lets a script tool read and edit like
         // every other markdown document.
-        if (typeof data.run === "string")
-            return { kind: "script", name, spec: { ...data, name } };
+        if (typeof data.run === "string") {
+            const guide = toolGuide(body);
+            return { kind: "script", name, spec: { ...data, name, ...(guide ? { guide } : {}) } };
+        }
         const inline = body ? fencedCode(body) : null;
         if (!inline)
             return null;
-        return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext } };
+        const guide = toolGuide(body, true);
+        return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext, ...(guide ? { guide } : {}) } };
     }
     const [spec] = parseApis([{ ...data, name }]);
-    return spec ? { kind: "http", name, spec } : null;
+    const guide = toolGuide(body);
+    return spec ? { kind: "http", name, spec: guide ? { ...spec, guide } : spec } : null;
 }
 /**
  * Tools in a directory, in both shapes.
@@ -955,7 +1003,9 @@ export function parseApis(raw) {
         out.push({
             name: name.replace(/[^a-zA-Z0-9_]/g, "_"),
             ...(Number(e.timeout) > 0 ? { timeout: Number(e.timeout) } : {}),
-            base: trimSlashes(base),
+            // `${FOLDRUN_API_URL}` and `${FOLDRUN_PUBLIC_URL}` are the install's own
+            // addresses, filled here on the host so a desk never names one.
+            base: trimSlashes(expandPlatformVars(base)),
             description: typeof e.description === "string" ? e.description : "",
             headers: asRecordLocal(e.headers),
             query: asRecordLocal(e.query),
@@ -2430,6 +2480,11 @@ export function setWorkspaceDescription(tenant, workspace, description) {
  * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
  * so every workspace made from the dashboard was born in the old format.
  */
+/** What the dashboard's "Create workspace" makes: blank (blankWorkspaceFiles),
+ *  minus the laptop-only files, for the same reason as templateFiles. */
+export function blankTemplateFiles(workspace) {
+    return blankWorkspaceFiles(workspace).filter((f) => f.path === "AGENTS.md" || IN_WORKSPACE_DIR.test(f.path));
+}
 export function templateFiles(workspace) {
     // The starter minus what only matters on a laptop's disk: .gitignore
     // guards a local clone's secrets, but the hosted store never keeps
@@ -2579,7 +2634,25 @@ export function runOutputPath(tenant, workspace, runId, agent, rel) {
 }
 export function readRun(tenant, workspace, runId) {
     const p = runFilePath(tenant, workspace, runId);
-    return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+    // EFS/NFS: writeRun() replaces this file by rename, so an open()+read()
+    // here can land on the just-unlinked inode and come back ESTALE (errno
+    // -116, surfaced by Node as "Unknown system error -116", syscall read).
+    // That isn't corruption — the next open() by path sees the committed new
+    // inode — so re-read a few times on ESTALE and rethrow anything else.
+    // (On dev-aws this surfaced as a CLI `--wait` call returning HTTP 500
+    // from waitForRun's poll while the run itself completed fine.)
+    const attempts = 5;
+    for (let i = 1;; i++) {
+        try {
+            return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+        }
+        catch (e) {
+            const err = e;
+            if ((err.code === "ESTALE" || err.errno === -116) && i < attempts)
+                continue;
+            throw e;
+        }
+    }
 }
 export function writeRun(tenant, workspace, run) {
     const p = runFilePath(tenant, workspace, run.id);
@@ -2825,12 +2898,19 @@ export function runCost(run) {
  * fan-out template is a row in the trace rather than work — billing any of
  * them would charge for steps the customer can see never executed, which is
  * the fastest way to lose an argument about an invoice.
+ *
+ * Tokens count only for steps that ran on the platform's own model
+ * credential. A step on the account's own key (`credential` "provider: …" —
+ * a provider: block, or Settings → Model) was paid for at the provider, and
+ * billing it again here charged a BYOK customer twice. And a carried step's
+ * tokens were billed where it ran, like its compute.
  */
 export function runMeter(run) {
     let steps = 0;
     let computeSecs = 0;
     let smallSecs = 0;
     let netBytes = 0;
+    let tokenCostUsd = 0;
     for (const s of run.steps) {
         if (s.status !== "completed" && s.status !== "failed")
             continue;
@@ -2838,13 +2918,15 @@ export function runMeter(run) {
         if (s.carriedFrom)
             continue;
         steps += 1;
+        if (!(s.credential ?? "").startsWith("provider:"))
+            tokenCostUsd += s.costUsd ?? 0;
         const secs = s.computeSecs ?? 0;
         computeSecs += secs;
         if (s.size === "small")
             smallSecs += secs;
         netBytes += (s.actual?.rxBytes ?? 0) + (s.actual?.txBytes ?? 0);
     }
-    return { tokenCostUsd: runCost(run), steps, computeSecs, smallSecs, netBytes };
+    return { tokenCostUsd, steps, computeSecs, smallSecs, netBytes };
 }
 /**
  * The compute meter for hold+work pricing: core-seconds and GiB-seconds

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

@@ -12,7 +12,9 @@ export declare const RETIRED_TOOLS: Record<string, string>;
  *  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. */
+/** The platform's own groups, served in-process rather than by the SDK.
+ *  `install` is granted to every agent anyway (install-tool.ts); naming it is
+ *  accepted so a file that says so is not flagged. */
 export declare const PLATFORM_GROUPS: Set<string>;
 /** 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. */

package/dist/src/tool-names.js

@@ -44,8 +44,10 @@ export const BUILTIN_TOOLS = new Set([
     "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash",
     "NotebookEdit", "TodoWrite",
 ]);
-/** The platform's own groups, served in-process rather than by the SDK. */
-export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask"]);
+/** The platform's own groups, served in-process rather than by the SDK.
+ *  `install` is granted to every agent anyway (install-tool.ts); naming it is
+ *  accepted so a file that says so is not flagged. */
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask", "install"]);
 /** 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. */
 export function isRuntimeTool(name) {

package/dist/src/tool-test.js

@@ -229,7 +229,14 @@ export async function testTool(tenant, workspace, def, input = {}) {
                 detail: `looked for ${file}\n\nThis is the commonest way to get a tool that silently never loads.`,
             });
         }
-        const names = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+        // The tool's own secrets, and the calling agent's `secrets:` — a run
+        // hands a script both. Testing gbp_read (whose agent, not the tool,
+        // declares GBP_OAUTH) said "GBP_OAUTH is not set" while every run of the
+        // same call worked (9 Oct 2026). Only an agent that grants the tool: the
+        // agents[0] stand-in above is there for its depth, not its keys.
+        const own = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+        const granting = caller && caller.ownTools.includes(def.name) ? caller.secrets : [];
+        const names = [...new Set([...own, ...granting])];
         const { env: stored, missing } = resolveSecrets(tenant, names, workspace);
         const live = await liveSecrets(stored, { tenant, workspace });
         if ("error" in live) {

package/dist/src/zip.d.ts

@@ -0,0 +1,17 @@
+export interface ZipEntry {
+    path: string;
+    data: Buffer;
+}
+export declare class ZipError extends Error {
+}
+export interface UnzipLimits {
+    /** Most entries the archive may hold. */
+    maxEntries?: number;
+    /** Largest one file, uncompressed. */
+    maxFileBytes?: number;
+    /** All files together, uncompressed. */
+    maxTotalBytes?: number;
+}
+export declare function crc32(buf: Buffer): number;
+export declare function zip(entries: ZipEntry[], now?: Date): Buffer;
+export declare function unzip(buf: Buffer, limits?: UnzipLimits): ZipEntry[];