@foldrun/core 0.6.0 → 1.0.0

package/src/step-exec.ts

@@ -8,6 +8,7 @@
 // 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, type HookDef, type HookRecord } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -57,6 +58,14 @@ export interface ExecOutcome {
 }
 
 export interface ExecOptions {
+  /** `hooks:` resolved host-side (hooks.ts): run at this step's own dispatch,
+   *  inside its sandbox. `hookBase` is what every hook event carries. */
+  hooks?: HookDef[];
+  /** Or the names (`hooks:` from the account, workspace and agent), resolved
+   *  here against this step's own roots — in a sandbox those are not the
+   *  host's paths. A name that resolves to nothing refuses the step. */
+  hookNames?: string[];
+  hookBase?: Record<string, unknown>;
   agentDir: string;
   workspaceRoot: string;
   libraryRoot: string;
@@ -158,7 +167,7 @@ export type QueryLike = AsyncIterable<unknown> & { interrupt(): Promise<unknown>
 export type QueryFn = (args: { prompt: string; options: Record<string, unknown> }) => QueryLike;
 
 /** The pairing fields on a tool event — see RunEvent in store.ts. */
-export type EventExtra = { call?: string; ms?: number; err?: boolean; effect?: TestEffect; operator?: OperatorEvent; subagent?: string; check?: boolean };
+export type EventExtra = { call?: string; ms?: number; err?: boolean; effect?: TestEffect; operator?: OperatorEvent; subagent?: string; check?: boolean; hook?: HookRecord };
 
 /** The tag on every event a failed check writes — `verify:`, `output: json`,
  *  a schema — headline and detail alike. The runner's no-retry rule for
@@ -310,8 +319,51 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
   // 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: HookDef, event: Record<string, unknown>) => runHook(hook, event, { cwd: agentDir, env: opts.env });
+  const record = (r: HookRecord, via?: string) =>
+    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,
@@ -329,6 +381,13 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
       // 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.
@@ -404,6 +463,44 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
                 return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, 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 ?? {}) as Record<string, unknown>;
+              // 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 as Record<string, unknown>, opts.toolOwners)); };
+              if (v.decision === "deny") {
+                refundCall();
+                return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, 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 as const };
+                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" as const, permissionDecision: "deny" as const, permissionDecisionReason: why } };
+                }
+                return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "allow" as const, updatedInput: again.updatedInput ?? v.input } };
+              }
+            }
             if (!verdict?.updatedInput) return {};
             return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "allow" as const, updatedInput: verdict.updatedInput } };
           }],
@@ -412,11 +509,21 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
         // 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: 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 as { tool_response?: unknown }).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.
@@ -632,11 +739,23 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
             ...(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 as { tool_name?: unknown }).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`);
       }
@@ -711,6 +830,18 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
       "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
@@ -877,8 +1008,8 @@ export async function checkVerify(
      *  and `matches:` test this, because it is also what the run's headline
      *  is read from: a reporter that narrated between tool calls ("Now let
      *  me write the report…") failed `matches: ^BAD\b` with a correct
-     *  headline while the check read every turn joined. `judge:` still grades
-     *  the whole result. */
+     *  headline while the check read every turn joined. `judge:` grades this
+     *  too, as "the reply", with the whole result beside it as the work. */
     conclusion?: string | null;
     data?: unknown;
     /** The step's own model environment, for `judge:` — it grades on the
@@ -941,7 +1072,13 @@ export async function checkVerify(
       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) };
     }
@@ -954,9 +1091,24 @@ export async function checkVerify(
  * Same shape as the eval judge, and answered with one word first so the
  * verdict is a prefix test rather than a reading.
  */
+export function judgePrompt(rubric: string, reply: string, work: string): string {
+  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: string,
-  output: string,
+  reply: string,
+  work: string,
   env: Record<string, string | undefined>,
   signal?: AbortSignal,
 ): Promise<string> {
@@ -966,10 +1118,7 @@ async function judgeReply(
   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.",
@@ -1060,3 +1209,14 @@ function runVerify(
 export function sdkEnv(base: Record<string, string | undefined> | undefined, extra: Record<string, string> = {}): Record<string, string | undefined> {
   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: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b): b is { type: "text"; text: string } => !!b && (b as { type?: unknown }).type === "text" && typeof (b as { text?: unknown }).text === "string")
+    .map((b) => b.text)
+    .join(" ");
+}

package/src/storage.ts

@@ -839,6 +839,14 @@ export async function materializeFiles(tenant: string, workspace: string): Promi
   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: string, workspace: string): Record<string, string> {
+  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.
@@ -851,6 +859,7 @@ export async function harvestFiles(
   tenant: string,
   workspace: string,
   by: string,
+  opts: { changedFrom?: Record<string, string> } = {},
 ): Promise<{ saved: string[]; errors: string[] }> {
   if (!fileStoreEnabled()) return { saved: [], errors: [] };
   adoptLegacyFilesDir(workspaceDir(tenant, workspace));
@@ -885,6 +894,10 @@ export async function harvestFiles(
         // Same size is not proof, so confirm by hash before skipping a write.
         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);
     } catch (err) {

package/src/store.ts

@@ -20,6 +20,7 @@
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 
+import { expandPlatformVars } from "./host-env.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
 import fs from "node:fs";
 import path from "node:path";
@@ -57,7 +58,7 @@ import {
 } from "./okf.ts";
 import { readTransport, KINDS } from "./kinds.ts";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS, type WireFormat, type AuthShape } from "./providers.ts";
-import { starterFiles, accountFiles } from "./starter.ts";
+import { starterFiles, accountFiles, blankWorkspaceFiles } from "./starter.ts";
 import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.ts";
 
 // Where workspaces live. The hosted app keeps many under data/; the CLI runs
@@ -83,6 +84,7 @@ export const WORKSPACE_DIRS = [
   "knowledge",
   "tools",
   "scripts",
+  "hooks",
   "state",
 ] as const;
 
@@ -317,6 +319,19 @@ export function assertCanonicalCase(rel: string) {
 // 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: string): boolean {
   const norm = rel.replaceAll("\\", "/");
@@ -325,6 +340,7 @@ export function isPlatformPath(rel: string): boolean {
   // are the vault, as far as anything outside the platform is concerned.
   if (/(^|\/)secrets\.json\./.test(norm)) 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/");
 }
 
@@ -625,6 +641,27 @@ export function toolIsOutward(data: Record<string, unknown>): boolean {
   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: string | undefined, inlineProgram = false): string | undefined {
+  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: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null {
   const name = typeof data.name === "string" ? data.name : fallbackName;
   // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -659,16 +696,24 @@ export function parseToolDef(data: Record<string, unknown>, fallbackName: string
     };
   }
   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;
 }
 
 /**
@@ -864,6 +909,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>; // values may contain ${SECRET_NAME}
   query: Record<string, string>; // always-appended query params (e.g. api keys)
   methods: string[]; // allowed HTTP methods; default GET only
@@ -1136,7 +1183,9 @@ export function parseApis(raw: unknown): ApiSpec[] {
     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),
@@ -2875,6 +2924,12 @@ export function setWorkspaceDescription(tenant: string, workspace: string, descr
  * 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: string): DeployFile[] {
+  return blankWorkspaceFiles(workspace).filter((f) => f.path === "AGENTS.md" || IN_WORKSPACE_DIR.test(f.path));
+}
+
 export function templateFiles(workspace: string): DeployFile[] {
   // The starter minus what only matters on a laptop's disk: .gitignore
   // guards a local clone's secrets, but the hosted store never keeps
@@ -2970,6 +3025,9 @@ 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]). */
@@ -3388,7 +3446,23 @@ export function runOutputPath(
 
 export function readRun(tenant: string, workspace: string, runId: string): RunRecord | null {
   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 as NodeJS.ErrnoException;
+      if ((err.code === "ESTALE" || err.errno === -116) && i < attempts) continue;
+      throw e;
+    }
+  }
 }
 
 export function writeRun(tenant: string, workspace: string, run: RunRecord) {
@@ -3706,6 +3780,12 @@ export 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 function runMeter(run: RunRecord): {
   tokenCostUsd: number;
@@ -3720,17 +3800,19 @@ export function runMeter(run: RunRecord): {
   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;
     // A carried step ran — and was billed — in the run it was carried from.
     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 };
 }
 
 /**

package/src/tool-names.ts

@@ -49,8 +49,10 @@ export const BUILTIN_TOOLS = new Set([
   "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. */

package/src/tool-test.ts

@@ -277,7 +277,14 @@ export async function testTool(
       });
     }
 
-    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) {