@foldrun/core 0.7.0 → 1.1.0

package/dist/src/run-container.d.ts

@@ -1,7 +1,9 @@
+import { type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { type ApiSpec, type Effort } from "./store.ts";
 import type { EventExtra } from "./step-exec.ts";
 import { type RuntimeSpec } from "./runtime.ts";
+import { type NetworkLevel } from "./network.ts";
 import type { ScriptSpec } from "./script-tools.ts";
 import type { ConsultSpec } from "./agent-tools.ts";
 import type { SubagentSpec } from "./subagents.ts";
@@ -52,6 +54,9 @@ export interface ContainerStepInput {
     /** `limits:` resolved host-side, and the SDK-name → foldrun-name map the
      *  count reads (limits.ts) — enforced in the pod by the same hook. */
     limits?: Record<string, number>;
+    /** `hooks:` names, resolved inside the sandbox against its own roots. */
+    hookNames?: string[];
+    hookBase?: Record<string, unknown>;
     toolOwners?: Record<string, string>;
     /** tools: [search] — the directories to search, as paths INSIDE the
      *  container (/workspace/…, /library/…). */
@@ -340,6 +345,7 @@ export declare function parseDriverLine(line: string): {
     operator?: OperatorEvent;
     subagent?: string;
     check?: boolean;
+    hook?: HookRecord;
 } | ({
     e: "done";
 } & ContainerStepOutcome) | null;
@@ -354,6 +360,13 @@ export interface RunInContainerArgs {
     input: ContainerStepInput;
     /** Secret + provider env — crosses as an env file, never argv. */
     env: Record<string, string>;
+    /** The step's network (network.ts), for an executor that can wall the
+     *  sandbox in itself: the k8s tier labels a filtered pod so its policy
+     *  admits the proxy and DNS alone. `enforced` false is report-only. */
+    network?: {
+        level: NetworkLevel;
+        enforced: boolean;
+    };
     emit: (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
     /** The run this step belongs to. Stamped on the sandbox as a label so a
      *  person stopping the run can reach the thing actually burning money —

package/dist/src/run-container.js

@@ -17,6 +17,7 @@
 //
 // The runner image bundles @foldrun/core itself, so the driver runs the same
 // executeStep the server would — one implementation, two homes.
+import { isHookRecord } from "./hooks.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -26,6 +27,7 @@ import { isPlatformPath } from "./store.js";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.js";
 import { isFileValue, fileContent } from "./secrets.js";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET } from "./runtime.js";
+import { egressCaSh } from "./network.js";
 import { isOperatorEvent } from "./operator.js";
 import { parseBrowserPod } from "./browser-pod.js";
 /**
@@ -42,7 +44,9 @@ const cli = () => process.env.FOLDRUN_CONTAINER_CLI ?? "docker";
 // there: everything platform-owned (store.ts#isPlatformPath — also never
 // copied in), plus knowledge/, which goes in for reading and is dropped on
 // the way out, and .git/.
-const DENY_BACK = ["knowledge/", ".git/"];
+// hooks/: a step must not rewrite the code that guards it — for this run (the
+// code is read into memory before the model starts, hooks.ts) or the next.
+const DENY_BACK = ["knowledge/", "hooks/", ".git/"];
 // A .git ANYWHERE in the tree, not just at the root. A step that clones a
 // repository into a shared area (files/site, say) was shipping the entire
 // object store back to the workspace, where the harvest then filed thousands
@@ -531,6 +535,7 @@ try {
     schema: input.schema,
     maxTurns: input.maxTurns,
     ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),
+    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),
     // Slim browsing: the platform put this step on the slim image to browse
     // through the account's pod, and named the file the web tool logs its
     // reconnects to. A lost pod stops the step; what it wrote decides what
@@ -808,6 +813,7 @@ ${CORE_INSTALL}`;
 // reads the status file and fails the step with apt's own words.
 const ENTRY = `#!/bin/sh
 set +e
+${egressCaSh("/opt/runner/job")}
 ${SYSTEM_FROM_INPUT_SH}
 ${systemInstallSh(RUNTIME_CACHE)}
 ${INSTALL_HELPER_SH}
@@ -983,6 +989,7 @@ export function parseDriverLine(line) {
                 ...(isOperatorEvent(parsed.operator) ? { operator: parsed.operator } : {}),
                 ...(typeof parsed.subagent === "string" && /^[a-z0-9-]{1,64}$/.test(parsed.subagent) ? { subagent: parsed.subagent } : {}),
                 ...(parsed.check === true ? { check: true } : {}),
+                ...(isHookRecord(parsed.hook) ? { hook: parsed.hook } : {}),
             };
         }
         if (parsed.e === "done") {

package/dist/src/runner.d.ts

@@ -250,6 +250,7 @@ grantsOnly?: boolean): {
         FOLDRUN_BROWSER_WEBGPU?: string | undefined;
         FOLDRUN_BROWSER_IGNORE_HTTPS_ERRORS?: string | undefined;
         FOLDRUN_BROWSER_STATE_KEY?: string | undefined;
+        FOLDRUN_BROWSER_STATE?: string | undefined;
         FOLDRUN_BROWSER_VIDEO?: string | undefined;
         FOLDRUN_BROWSER_LIVE_VIEW?: string | undefined;
     };

package/dist/src/runner.js

@@ -2,6 +2,7 @@
 // group receives every prior result, labeled per agent. Optional steps ("2?")
 // 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.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -34,7 +35,8 @@ import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacy
 import { refNames } from "./refs.js";
 import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel } from "./catalog.js";
-import { resolveSecrets, getSecret, materializeSecrets } from "./secrets.js";
+import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.js";
+import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.js";
 import { attachOperations, prefetchOpenApi } from "./openapi.js";
@@ -59,6 +61,24 @@ export { localDate } from "./clock.js";
 // 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, bound, values, grant) {
+    const known = Object.fromEntries(bound.filter((n) => n in values).map((n) => [n, values[n]]));
+    const out = {};
+    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, tenant, workspace) {
     const fill = (values) => {
         const out = {};
@@ -1214,6 +1234,7 @@ grantsOnly = false) {
         ...(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" } : {}),
     };
@@ -2167,6 +2188,18 @@ stepIndex) {
         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()) {
             // The isolated path: the whole loop — model, built-in tools, scripts —
@@ -2217,7 +2250,46 @@ stepIndex) {
                     }
                 }
             }
+            // `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),
+                    ...Object.values(mcpServers).map((m) => ("url" in m && typeof m.url === "string" ? hostOf(m.url) : null)).filter((h) => !!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
@@ -2229,19 +2301,24 @@ stepIndex) {
                 ...(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 = materialise ? liveSecrets : placeholders;
+            let sandboxSecrets = 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
@@ -2249,11 +2326,13 @@ stepIndex) {
             // 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` } });
                 }
@@ -2308,7 +2387,9 @@ stepIndex) {
                     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`
@@ -2325,6 +2406,7 @@ stepIndex) {
                     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
@@ -2350,6 +2432,14 @@ stepIndex) {
                     // 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
@@ -2366,6 +2456,9 @@ stepIndex) {
                 // 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,
@@ -2683,6 +2776,7 @@ stepIndex) {
                 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 —
@@ -4281,11 +4375,13 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // 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) => {
+                    if (!step.onFail)
+                        return;
                     const rescuerDir = path.join(pDir, "agents", step.onFail);
                     if (!fs.existsSync(path.join(rescuerDir, "agent.md"))) {
                         step.events.push({
@@ -4293,7 +4389,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                             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(),
@@ -4301,10 +4397,21 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         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 = {
                         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,
@@ -4352,6 +4459,13 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         });
                     }
                     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
                 // here: the person chose to start after it. Counting it stopped
@@ -4451,7 +4565,21 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         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 === "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 === "failed" && !looper.optional) {
                         run.status = "failed";
                         break;
                     }

package/dist/src/secrets.d.ts

@@ -26,6 +26,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>;
 /**
@@ -36,6 +41,18 @@ type SecretsFile = Record<string, StoredSecret>;
 export declare function mutateVaultFile(file: string, change: (all: SecretsFile) => SecretsFile | null): SecretsFile;
 export declare const SECRET_NAME: RegExp;
 export declare function setSecret(tenant: string, name: string, value: string, workspace?: string, kind?: SecretKind): void;
+/**
+ * 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 declare function setSecretSites(tenant: string, name: string, sites: string[], workspace?: string): string[];
+/**
+ * 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 declare function secretSites(tenant: string, names: string[], workspace?: string): Record<string, string[]>;
 /** Encrypt one value for an account — the same envelope secrets use, exported
  *  so sibling stores (OAuth clients) don't invent a second crypto path. */
 export declare function encryptValue(tenant: string, value: string): {
@@ -65,6 +82,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[];
 }
 export declare function listSecrets(tenant: string, workspace?: string): SecretEntry[];
 export declare function resolveSecrets(tenant: string, names: string[], workspace?: string): {

package/dist/src/secrets.js

@@ -39,6 +39,7 @@ const tenantKey = (tenant) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.js";
 import { trimSlashes } from "./paths.js";
+import { SITE } from "./network.js";
 const keyFile = () => path.join(dataRoot(), ".secret-key");
 /**
  * The install's root secret, as text: FOLDRUN_SECRET_KEY when set, else the
@@ -163,14 +164,70 @@ export function setSecret(tenant, name, value, workspace, kind) {
         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, name, sites, workspace) {
+    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, names, workspace) {
+    const out = {};
+    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.
  *
@@ -271,6 +328,7 @@ export function listSecrets(tenant, workspace) {
         updatedAt: rec.updatedAt,
         scope: "account",
         ...(rec.kind ? { kind: rec.kind } : {}),
+        ...(rec.sites?.length ? { sites: [...rec.sites] } : {}),
     }));
     if (!workspace)
         return account.sort((a, b) => a.name.localeCompare(b.name));
@@ -280,6 +338,7 @@ export function listSecrets(tenant, workspace) {
         scope: "workspace",
         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) => a.name.localeCompare(b.name));
@@ -748,7 +807,12 @@ export function rewrapTenantSecrets(tenant) {
                 return null;
             const next = { ...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/dist/src/starter.js

@@ -263,6 +263,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 |
@@ -294,7 +295,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
 
@@ -340,6 +345,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\`,
@@ -439,6 +445,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
@@ -446,6 +453,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/dist/src/step-exec.d.ts

@@ -1,3 +1,4 @@
+import { type HookDef, type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
 import type { TestEffect } from "./test-mode.ts";
@@ -40,6 +41,14 @@ export interface ExecOutcome {
     browserPod?: BrowserPodOutcome;
 }
 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;
@@ -151,6 +160,7 @@ export type EventExtra = {
     operator?: OperatorEvent;
     subagent?: string;
     check?: boolean;
+    hook?: HookRecord;
 };
 /** Conservative per-token rates for a model nothing else can price — an
  *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling