@foldrun/core 0.7.0 → 1.1.0

package/src/runner.ts

@@ -3,6 +3,7 @@
 // fail without failing the flow. A direct agent run is a one-step ad-hoc
 // flow, so there is a single execution path.
 
+import { hookNames } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -80,7 +81,8 @@ import {
   runCost,
 } from "./store.ts";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, type Catalog } from "./catalog.ts";
-import { resolveSecrets, getSecret, materializeSecrets } from "./secrets.ts";
+import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.ts";
+import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.ts";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.ts";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.ts";
 import { attachOperations, prefetchOpenApi } from "./openapi.ts";
@@ -108,6 +110,30 @@ export { localDate } from "./clock.ts";
 // An MCP tool definition becomes an SDK server config. ${SECRET} placeholders
 // in env and headers resolve server-side, so a credential reaches the server
 // process without ever entering the model's context.
+/** Remote MCP servers with each bound secret's value put back as its
+ *  `${NAME}`, granted to that server's host — the sandbox then holds the
+ *  name and the proxy fills it, as for an http tool. */
+function unbindMcpHeaders(
+  servers: Record<string, McpServerConfig>,
+  bound: string[],
+  values: Record<string, string>,
+  grant: EgressGrant,
+): Record<string, McpServerConfig> {
+  const known = Object.fromEntries(bound.filter((n) => n in values).map((n) => [n, values[n]]));
+  const out: Record<string, McpServerConfig> = {};
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.type !== "http" || !server.headers) {
+      out[name] = server;
+      continue;
+    }
+    const host = hostOf(server.url);
+    out[name] = host
+      ? { ...server, headers: Object.fromEntries(Object.entries(server.headers).map(([k, v]) => [k, unsubstitute(v, known, host, grant)])) }
+      : server;
+  }
+  return out;
+}
+
 function mcpConfig(spec: McpSpec, tenant: string, workspace: string): McpServerConfig {
   const fill = (values: Record<string, string>) => {
     const out: Record<string, string> = {};
@@ -1341,6 +1367,7 @@ export function agentContext(
     ...(browseSettings.webgpu ? { FOLDRUN_BROWSER_WEBGPU: "1" } : {}),
     ...(browseSettings.ignore_https_errors ? { FOLDRUN_BROWSER_IGNORE_HTTPS_ERRORS: "1" } : {}),
     ...(browseSettings.state_key ? { FOLDRUN_BROWSER_STATE_KEY: browseSettings.state_key } : {}),
+    ...(browseSettings.state ? { FOLDRUN_BROWSER_STATE: browseSettings.state } : {}),
     ...(browseSettings.video ? { FOLDRUN_BROWSER_VIDEO: "1" } : {}),
     ...(browseSettings.live_view === false ? { FOLDRUN_BROWSER_LIVE_VIEW: "0" } : {}),
   };
@@ -2355,6 +2382,17 @@ async function runStep(
     const limitOwners = toolOwners(apiTools.owners, scriptSpecs);
     const limitOpts = Object.keys(stepLimits).length ? { limits: stepLimits, toolOwners: limitOwners } : {};
     if (limitOpts.limits) push("info", `limits: ${Object.entries(stepLimits).map(([k, n]) => `${k} ${n}`).join(", ")} — per step; a call past one is refused`);
+    // `hooks:` — the account's, the workspace's, then the agent's own, each
+    // once; resolved and run inside the step (hooks.ts, step-exec.ts).
+    const stepHookNames = [...new Set([
+      ...hookNames(readAgentsMd(accountDir(tenant))?.data?.hooks),
+      ...hookNames(readAgentsMd(workspaceRootOf(agentDir))?.data?.hooks),
+      ...hookNames(front.hooks),
+    ])];
+    const hookOpts = stepHookNames.length
+      ? { hookNames: stepHookNames, hookBase: { run_id: runId ?? null, step: stepIndex ?? null, agent: step.agent, workspace: path.basename(workspaceRootOf(agentDir)) } }
+      : {};
+    if (stepHookNames.length) push("info", `hooks: ${stepHookNames.join(", ")}`);
 
     const isolation = process.env.FOLDRUN_RUN_ISOLATION;
     if (isolatedRun()) {
@@ -2407,7 +2445,45 @@ async function runStep(
           }
         }
       }
+      // `network:` — which sites the sandbox may reach (network.ts). Resolved
+      // before the lease, because the proxy holds the list per request. A
+      // step that may fetch or browse the open web defaults to open; every
+      // other to the trusted list plus what it declares.
+      const workspaceName = path.basename(workspaceRootOf(agentDir));
+      const readsWeb = scriptSpecs.some((sc) => sc.name === "web") && (!web.actions || web.actions.some((a) => a === "fetch" || a === "browse"));
+      // Secrets bound to sites in the vault: filled by the proxy for those
+      // sites alone, never put in the sandbox (egress.ts).
+      const boundSites = secretSites(tenant, Object.keys(liveSecrets), workspaceName);
+      const network = resolveNetwork({
+        account: readAgentsMd(accountDir(tenant))?.data?.network,
+        workspace: readAgentsMd(workspaceRootOf(agentDir))?.data?.network,
+        agent: front.network,
+        readsWeb,
+        implied: [
+          ...apiSpecs.map((a) => hostOf(a.base)).filter((h): h is string => !!h),
+          ...Object.values(mcpServers).map((m) => ("url" in m && typeof m.url === "string" ? hostOf(m.url) : null)).filter((h): h is string => !!h),
+          ...Object.values(grant.secrets).flatMap((g) => g.hosts),
+          ...Object.values(boundSites).flat(),
+        ],
+      });
+      grant.network = { level: network.level, hosts: network.hosts };
       const lease = await platform.egress.lease({ tenant, runId: runId ?? "adhoc", grant, test: testRun, ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}) });
+      // The forward door: every program in the sandbox sends through the
+      // proxy, which holds the site list and fills bound secrets. A proxy
+      // without the door (an older platform) leaves programs going direct.
+      // A step that may browse gets no proxy variables: the browser in it
+      // reads HTTPS_PROXY too, and Chromium cannot send credentials written
+      // into a proxy URL — every page failed ERR_INVALID_AUTH_CREDENTIALS
+      // (14 Oct 2026, the reel posters). Such a step is open by default,
+      // and its bound secrets materialise as they did before the door.
+      const browses = scriptSpecs.some((sc) => sc.name === "web") && (!web.actions || web.actions.includes("browse"));
+      const forward = lease?.proxy && !browses ? lease : null;
+      push("info", networkLine(network, forward ? forward.enforce === true : null));
+      const bound = forward ? Object.keys(boundSites).filter((name) => name in liveSecrets) : [];
+      for (const name of bound) {
+        for (const site of boundSites[name]) addGrant(grant, name, liveSecrets[name], site);
+        (grant.healthKeys ??= {})[name] = healthKey(name, secretScopes[name] === "workspace" ? "workspace" : "account", workspaceName);
+      }
       // Which secrets must still be real inside the sandbox: a script tool
       // reads them from its environment, and unless it says `secrets:
       // proxied` it needs the value, not the name. bash is a script by
@@ -2419,22 +2495,27 @@ async function runStep(
         ...(scriptSpecs.some((sc) => sc.name === "web") && (!web.actions || web.actions.includes("browse")) ? ["web (browse)"] : []),
         ...(allowed.includes("Bash") ? ["bash"] : []),
       ];
-      const materialise = !lease || materialisers.length > 0;
       const declared = Object.keys(liveSecrets);
+      // A bound secret is never materialised, whatever the step grants.
+      const unbound = declared.filter((name) => !bound.includes(name));
+      const materialise = (!lease || materialisers.length > 0) && unbound.length > 0;
       if (lease) {
+        const boundNote = bound.length ? `${bound.join(", ")} bound to sites — filled by the egress proxy, never in the sandbox` : "";
         push(
           "info",
           declared.length
             ? materialise
-              ? `secrets: ${declared.join(", ")} materialised in the sandbox for ${materialisers.join(", ")}; api tools and the model key go through the egress proxy`
-              : `secrets: ${declared.join(", ")} proxied — nothing in the sandbox but the names`
+              ? `secrets: ${unbound.join(", ")} materialised in the sandbox for ${materialisers.join(", ")}${boundNote ? `; ${boundNote}` : ""}; api tools and the model key go through the egress proxy`
+              : `secrets: ${declared.join(", ")} proxied — nothing in the sandbox but the names${boundNote ? ` (${boundNote})` : ""}`
             : "secrets: none declared; the model key goes through the egress proxy",
         );
       }
       // Sandbox env for the declared secrets: the value, or its own name as
       // a placeholder that the proxy fills on the way out.
       const placeholders = Object.fromEntries(declared.map((name) => [name, `\${${name}}`]));
-      let sandboxSecrets: Record<string, string> = materialise ? liveSecrets : placeholders;
+      let sandboxSecrets: Record<string, string> = materialise
+        ? { ...liveSecrets, ...Object.fromEntries(bound.map((name) => [name, placeholders[name]])) }
+        : placeholders;
       // A test run hands the sandbox no send-capable value. The env var is
       // still there, reading TEST_MODE_WITHHELD, so a script that never
       // checked FOLDRUN_TEST_MODE fails at the provider's door with an auth
@@ -2442,11 +2523,13 @@ async function runStep(
       // has a declared sender (everything withheld) or a declared reader
       // (nothing withheld); see test-mode.ts for the order.
       if (testRun && materialise) {
-        const held = withholdSecrets(liveSecrets, {
+        const held = withholdSecrets(Object.fromEntries(unbound.map((name) => [name, liveSecrets[name]])), {
           outward: scriptSpecs.some((sc) => sc.outward),
           allow: scriptSpecs.some((sc) => sc.testMode === "allow"),
         });
-        sandboxSecrets = held.env;
+        // Bound secrets stay placeholders: the proxy, which holds the test
+        // policy, is the only party that ever fills them.
+        sandboxSecrets = { ...held.env, ...Object.fromEntries(bound.map((name) => [name, placeholders[name]])) };
         for (const name of held.withheld) {
           push("info", `test: ${name} withheld from the sandbox — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
         }
@@ -2504,7 +2587,9 @@ async function runStep(
           systemPrompt,
           allowed,
           mcpNames: consultNames,
-          mcpServers,
+          // A remote MCP server's headers had their secrets filled host-side;
+          // a bound one goes back to its ${NAME} for the proxy to fill.
+          mcpServers: bound.length ? unbindMcpHeaders(mcpServers, bound, liveSecrets, grant) : mcpServers,
           apis: substitutedApis,
           scripts: scriptSpecs,
           // The merged spec, not `front.runtime` — see the plan's `runtime`
@@ -2521,6 +2606,7 @@ async function runStep(
           schema: resolvedSchema ?? undefined,
           maxTurns: step.maxTurns,
           ...limitOpts,
+          ...hookOpts,
           translator: keyName === MODEL_KEY_NAME ? primaryTranslator : secondTranslator,
           // Outward steps keep a browser of their own: an executor that
           // could browse from the slim image through the account's pod
@@ -2547,6 +2633,14 @@ async function runStep(
             // after and carries the agent's chosen endpoint + token.
             ...proxied(Object.keys(providerEnv).length === 0 ? modelEnv : providerEnv, keyName),
             ...(lease ? { [EGRESS_ENV]: lease.url } : {}),
+            // Every program's HTTP(S) through the proxy's forward door, and
+            // the CA it signs bound sites with, for the sandbox to trust.
+            ...(forward ? proxyEnv(forward.proxy!) : {}),
+            // Only a step with a bound secret has a site the proxy
+            // intercepts, so only that step's TLS clients are pointed at a
+            // bundle with the egress CA in it; every other step's are as
+            // they always were.
+            ...(forward?.ca && bound.length ? { [EGRESS_CA_ENV]: Buffer.from(forward.ca).toString("base64") } : {}),
             ...clockEnv,
             // Who is running: the in-process path stamps scripts with these
             // host-side, but a container rebuilds its tools from its own
@@ -2564,6 +2658,9 @@ async function runStep(
         // Stamps the sandbox, so stopping this run can destroy it.
         runId,
         size,
+        // The pod's network, for the executor's own wall (the k8s tier's
+        // network policy): a filtered pod reaches the proxy and DNS only.
+        network: { level: network.level, enforced: forward?.enforce === true },
         // A test run's state/ and storage/ changes come out under the run.
         divert: testRun && runId ? divertFor(runId) : undefined,
         test: testRun,
@@ -2885,6 +2982,7 @@ async function runStep(
         schema: resolvedSchema ?? undefined,
         maxTurns: step.maxTurns,
         ...limitOpts,
+        ...hookOpts,
         stopRequested,
         // What the scripts saw, the verify sees: a flow can then check that
         // the proof a step left names THIS run, not one that came before —
@@ -4543,9 +4641,12 @@ function driveRunInner(
         // Not after a stop: the failure a stop leaves behind is not one a
         // rescuer should take over. The merge in save() surfaces the flag.
         save();
-        for (const step of freshGroup) {
-          if (run.stopRequested) break;
-          if (step.status !== "failed" || !step.onFail) continue;
+        // One rescue of one failed step. Also used when an evaluator loop
+        // runs out of cycles below, which used to fail the run without ever
+        // reaching the step's on-fail (medium-desk's claim-trimmer was
+        // written for exactly that case and could never run).
+        const rescueStep = async (step: StepRecord): Promise<void> => {
+          if (!step.onFail) return;
           const rescuerDir = path.join(pDir, "agents", step.onFail);
           if (!fs.existsSync(path.join(rescuerDir, "agent.md"))) {
             step.events.push({
@@ -4553,7 +4654,7 @@ function driveRunInner(
               type: "error",
               text: `on-fail: "${step.onFail}" is not an agent in this workspace — no rescue`,
             });
-            continue;
+            return;
           }
           step.events.push({
             t: new Date().toISOString(),
@@ -4561,11 +4662,22 @@ function driveRunInner(
             text: `failed — handing to [[${step.onFail}]] (on-fail)`,
           });
           const failure = (step.result ?? step.events.filter((e) => e.type === "error").map((e) => e.text).join("\n")).slice(0, 4000);
+          // A gated step's approval travels with it: the rescuer acts inside
+          // the same answer the failed agent had, and must be told what it
+          // was. Fixers used to dig it out of the run record, and stop when
+          // they could not (15 Oct 2026).
+          const approved = step.approvedAt
+            ? `\nA person approved this step before it ran${step.approvalNote ? " — their answer is below" : ", with no note: a plain yes"}. Act within that approval and nothing wider.`
+            : "";
+          const owesMarker = step.until ? `\nThe step's loop ended without its marker: your reply must end with a line saying ${step.until}.` : "";
           const rescue: StepRecord = {
             agent: step.onFail,
             instruction:
               `${step.instruction}\n\n<rescue>\nYou are taking this step over: [[${step.agent}]] attempted it and failed. ` +
-              `Its failure, for whatever it is worth:\n${failure}\n</rescue>`,
+              `Its failure, for whatever it is worth:\n${failure}${approved}${owesMarker}\n</rescue>`,
+            ...(step.ask ? { ask: step.ask } : {}),
+            ...(step.approvedAt ? { approvedAt: step.approvedAt } : {}),
+            ...(step.approvalNote ? { approvalNote: step.approvalNote } : {}),
             group: step.group,
             optional: false,
             model: step.model,
@@ -4611,6 +4723,11 @@ function driveRunInner(
             });
           }
           save();
+        };
+        for (const step of freshGroup) {
+          if (run.stopRequested) break;
+          if (step.status !== "failed" || !step.onFail) continue;
+          await rescueStep(step);
         }
 
         // A step carried into a re-run failed in the run it came from, not
@@ -4711,7 +4828,21 @@ function driveRunInner(
             text: `loop exhausted: after ${looper.loop} cycle${looper.loop === 1 ? "" : "s"} the result still does not say "${looper.until}"`,
           });
           save();
-          if (!looper.optional) {
+          if (looper.onFail && !run.stopRequested) {
+            await rescueStep(looper);
+            // The rescuer owes what the loop owed: its marker.
+            // rescueStep mutates the status; widen past TS's "failed" narrowing.
+            if ((looper.status as string) === "completed" && !saysUntilMarker(looper.result ?? null, looper.until)) {
+              looper.status = "failed";
+              looper.events.push({
+                t: new Date().toISOString(),
+                type: "error",
+                text: `on-fail: [[${looper.onFail}]]'s result does not say "${looper.until}" either`,
+              });
+              save();
+            }
+          }
+          if ((looper.status as string) === "failed" && !looper.optional) {
             run.status = "failed";
             break;
           }

package/src/secrets.ts

@@ -42,6 +42,7 @@ const tenantKey = (tenant: string) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.ts";
 import { trimSlashes } from "./paths.ts";
+import { SITE } from "./network.ts";
 
 const keyFile = () => path.join(dataRoot(), ".secret-key");
 
@@ -99,6 +100,11 @@ interface StoredSecret {
    *  record written before per-account keys existed is encrypted with — so an
    *  old vault stays readable without a migration having to run first. */
   k?: "tenant";
+  /** The sites this secret is bound to (network.ts SITE shape). A bound
+   *  secret never enters a sandbox: the egress proxy fills its `${NAME}` for
+   *  these sites alone. Metadata, not a value, so it is stored in the clear
+   *  beside the ciphertext and survives the value being set again. */
+  sites?: string[];
 }
 
 type SecretsFile = Record<string, StoredSecret>;
@@ -195,15 +201,67 @@ export function setSecret(
   if (value.length > 8192) throw new Error("secret too long");
   const sealed = encryptValue(tenant, value);
   mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+    // A new value keeps the sites the old one was bound to: binding is a
+    // property of the credential's use, not of its current value, and a
+    // rotation that silently unbound it would put the new value in pods.
+    const sites = all[name]?.sites;
     all[name] = {
       ...sealed,
       updatedAt: new Date().toISOString(),
       ...(kind ? { kind } : {}),
+      ...(sites?.length ? { sites } : {}),
     };
     return all;
   });
 }
 
+/**
+ * Bind a secret to sites, or unbind it (an empty list). The secret must
+ * exist in that scope. Sites are `api.example.com` or `*.example.com` — no
+ * scheme, path or port. Returns the list as stored.
+ */
+export function setSecretSites(tenant: string, name: string, sites: string[], workspace?: string): string[] {
+  const clean = [...new Set(sites.map((x) => x.trim().toLowerCase()).filter(Boolean))];
+  for (const site of clean) {
+    if (!SITE.test(site)) throw new Error(`"${site}" is not a site — a domain like api.example.com or *.example.com, no scheme, path or port`);
+  }
+  let found = false;
+  mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+    const rec = all[name];
+    if (!rec) return null;
+    found = true;
+    // A file, an ssh key or an @api header set is not a value that travels
+    // in a header — it is unpacked inside the sandbox, so there is nothing
+    // for the proxy to fill.
+    if (clean.length && (rec.kind === "file" || rec.kind === "ssh" || rec.kind === "api")) {
+      throw new Error(`${name} is a ${rec.kind} secret, unpacked inside the sandbox — only a value sent in a request can be bound to sites`);
+    }
+    if (clean.length) rec.sites = clean;
+    else delete rec.sites;
+    return all;
+  });
+  if (!found) throw new Error(`no secret ${name}${workspace ? ` in workspace ${workspace}` : " in the account"}`);
+  return clean;
+}
+
+/**
+ * The sites each named secret is bound to, nearest scope first — the same
+ * record getSecret would read the value from. A name with no binding (or
+ * no secret) is absent from the answer.
+ */
+export function secretSites(tenant: string, names: string[], workspace?: string): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  const own = workspace ? read(tenant, workspace) : {};
+  const source = workspace ? platform.previewSourceOf(tenant, workspace) : null;
+  const inherited = source ? read(tenant, source) : {};
+  const account = read(tenant);
+  for (const name of names) {
+    const rec = own[name] ?? inherited[name] ?? account[name];
+    if (rec?.sites?.length) out[name] = [...rec.sites];
+  }
+  return out;
+}
+
 /**
  * Which key writes this account's records.
  *
@@ -321,6 +379,9 @@ export interface SecretEntry {
   /** How this credential works: auto-refreshing oauth2, a signed service
    *  account, a file/ssh/api materialised into runs — absent for static values. */
   kind?: SecretKind;
+  /** The sites it is bound to — the proxy fills it for these and no other,
+   *  and it never enters a sandbox. Absent when unbound. */
+  sites?: string[];
 }
 
 // Metadata only — never values. Without a workspace this lists the account
@@ -332,6 +393,7 @@ export function listSecrets(tenant: string, workspace?: string): SecretEntry[] {
     updatedAt: rec.updatedAt,
     scope: "account" as const,
     ...(rec.kind ? { kind: rec.kind } : {}),
+    ...(rec.sites?.length ? { sites: [...rec.sites] } : {}),
   }));
   if (!workspace) return account.sort((a, b) => a.name.localeCompare(b.name));
 
@@ -341,6 +403,7 @@ export function listSecrets(tenant: string, workspace?: string): SecretEntry[] {
     scope: "workspace" as const,
     shadowed: account.some((a) => a.name === name),
     ...(rec.kind ? { kind: rec.kind } : {}),
+    ...(rec.sites?.length ? { sites: [...rec.sites] } : {}),
   }));
   const ownNames = new Set(own.map((s) => s.name));
   return [...own, ...account.filter((a) => !ownNames.has(a.name))].sort((a, b) =>
@@ -913,7 +976,12 @@ export function rewrapTenantSecrets(tenant: string): { moved: number; unreadable
       if (plain.size === 0 || unreadableHere.length) return null;
       const next: SecretsFile = { ...all };
       for (const [name, value] of plain) {
-        next[name] = { ...encryptValue(tenant, value), updatedAt: all[name].updatedAt, ...(all[name].kind ? { kind: all[name].kind } : {}) };
+        next[name] = {
+          ...encryptValue(tenant, value),
+          updatedAt: all[name].updatedAt,
+          ...(all[name].kind ? { kind: all[name].kind } : {}),
+          ...(all[name].sites?.length ? { sites: all[name].sites } : {}),
+        };
       }
       moved += plain.size;
       return next;

package/src/starter.ts

@@ -279,6 +279,7 @@ only when they asked for exactly that deletion.
 | \`memory/\` | what past runs learned — agents write here themselves |
 | \`evals/\` | tests for agents, same idea as unit tests |
 | \`skills/\` | a procedure an agent can follow, named in \`skills:\` |
+| \`hooks/\` | your code at every tool call, step start or step end (\`hook.md\` + \`run.mjs\`), turned on with \`hooks:\` — refuse, rewrite, add context; same on every model |
 | \`tools/\` | a folder tool: its definition and its code together |
 | \`scripts/\` | code the agents call, referenced by \`scripts:\` |
 | \`state/\` | what runs accumulate. Yours to read, never deployed over |
@@ -310,7 +311,11 @@ memory an agent wrote that your push does not mention. Those belong to the platf
 reverted what an agent learned would make every run a little dumber.
 
 Secrets never go in these files. \`foldrun secrets\` puts them in the vault, and
-agents reference them by name.
+agents reference them by name. Bind one to the sites it is for
+(\`foldrun secrets sites NAME api.example.com\`) and it never enters a sandbox:
+the egress proxy fills \`\${NAME}\` in requests to those sites alone. Which sites
+a sandbox may reach at all is \`network:\` — open for an agent that reads the web,
+the trusted list plus what it declares for every other (\`foldrun agent network\`).
 
 ## Talking to a deployed workspace
 
@@ -356,6 +361,7 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/export\` · \`/import\` | GET · POST | the workspace, a flow (\`?kind=flow&name=\`) or an agent as a .zip; take one in (\`?dryRun=1\` first, \`?overwrite=1\` to replace) |
 | \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
+| \`/assistant\` | POST | ask the assistant, or have it write agents, flows, tools and skills — from the docs only; proposals come back, nothing is written |
 
 Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/schedule\`,
 \`/api/approvals\`, \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
@@ -455,6 +461,7 @@ size: large                 # small | large | heavy — the sandbox it rents
 tools: [web, read, ask, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step
 disallowedTools: [Bash]     # subtract from what it would otherwise have
 skills: [house-style]       # from skills/
+hooks: [no-force-push]      # from hooks/ or the library: code at every tool call
 scripts: [summarise.py]     # from scripts/, each becomes a callable tool
 apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
@@ -462,6 +469,7 @@ agents: [writer]            # colleagues this one may consult (an answer, no too
 subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
 secrets: [CRM_TOKEN]        # keys the agent uses itself; a tool's own come with the tool
 limits: {web.search: 40, crm: 20, calls: 300}  # per step; a call past a limit is refused, never run
+network: [api.example.com]  # sites its sandbox may reach, added to the trusted list; open | trusted | none
 timezone: Australia/Sydney  # the calendar it works to — IANA name or UTC+10
 provider: {}                # BYOK for this agent; account-wide: \`foldrun account model set\`
 permissionMode: plan        # plan first, act once approved

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,
@@ -411,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 } };
           }],
@@ -419,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.
@@ -730,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