@foldrun/core 0.7.0 → 1.1.0

package/dist/src/step-exec.js

@@ -7,6 +7,7 @@
 // assembles the system prompt and builds MCP servers, then hands this the
 // results. That is what lets the same function run somewhere the vault, the
 // library and the account do not exist.
+import { runHook, runToolCallHooks, matchesTool, hookLine, resolveHooks } from "./hooks.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -169,8 +170,49 @@ async function executeStepInner(opts, runQuery) {
     // `limits:` — this step's counts. A new step, a retry of one, or a
     // fan-out instance each start from zero.
     const counter = new CallCounter(opts.limits);
+    // Hooks (hooks.ts): the person's own code at this dispatch, same on every
+    // model. Each runs in the agent's directory with a bare environment.
+    let hooks = opts.hooks ?? [];
+    if (opts.hookNames?.length) {
+        const r = resolveHooks({ workspaceRoot, libraryRoot, names: opts.hookNames });
+        const bad = [...r.missing.map((n) => `no hook named ${n} in hooks/ or the library`), ...r.errors];
+        if (bad.length) {
+            emit("error", `hooks: ${bad.join("; ")} — the step is refused rather than run without its hooks`);
+            return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+        }
+        hooks = [...hooks, ...r.hooks];
+    }
+    const hookBase = { ...(opts.hookBase ?? {}) };
+    const callHook = (hook, event) => runHook(hook, event, { cwd: agentDir, env: opts.env });
+    const record = (r, via) => emit(r.did === "error" || r.did === "deny" ? "error" : "info", hookLine(r), { hook: r, ...(via ? { subagent: via } : {}) });
+    // step.start — a gate: context it returns goes in front of the task; a
+    // hook that fails refuses the step rather than run it unguarded.
+    let prompt = opts.prompt;
+    for (const hook of hooks.filter((h) => h.on === "step.start")) {
+        const a = await callHook(hook, { ...hookBase, event: "step.start", hook: hook.name, prompt });
+        if (!a.ok) {
+            record({ hook: hook.name, event: "step.start", did: "error", reason: `${a.failure}, so the step is refused`, ms: a.ms });
+            return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+        }
+        // Exit 2 is a deny on every event (runHook). On a gate that means the
+        // step does not run — it used to come back ok with no context, and the
+        // step went ahead as if the hook had agreed.
+        if (a.decision === "deny") {
+            record({ hook: hook.name, event: "step.start", did: "deny", reason: `${a.reason}, so the step is refused`, ms: a.ms });
+            return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+        }
+        if (a.context) {
+            prompt = `${prompt}\n\n${a.context}`;
+            record({ hook: hook.name, event: "step.start", did: "context", ms: a.ms });
+        }
+        else if (a.note) {
+            record({ hook: hook.name, event: "step.start", did: "note", reason: a.note, ms: a.ms });
+        }
+    }
+    const toolHooks = hooks.filter((h) => h.on === "tool.call");
+    const resultHooks = hooks.filter((h) => h.on === "tool.result");
     const q = runQuery({
-        prompt: opts.prompt,
+        prompt,
         options: {
             cwd: agentDir,
             abortController: abort,
@@ -272,6 +314,46 @@ async function executeStepInner(opts, runQuery) {
                                         return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: refusal.message } };
                                     }
                                 }
+                                // tool.call hooks — after foldrun's own checks, so a hook never
+                                // sees a call that was going to be refused anyway, and handed the
+                                // input as the tool would get it (the workspace/ prefix expanded).
+                                if (toolHooks.length) {
+                                    const input = (verdict?.updatedInput ?? hookInput.tool_input ?? {});
+                                    // A sub-agent's call says so: a hook that guards the step's own
+                                    // model differently from its delegates can tell them apart.
+                                    const v = await runToolCallHooks(toolHooks, { tool: hookInput.tool_name, input, base: via ? { ...hookBase, subagent: via } : hookBase }, callHook);
+                                    for (const r of v.records)
+                                        record(r, via);
+                                    const refundCall = () => { if (counter.active)
+                                        counter.refund(limitKeysFor(hookInput.tool_name, hookInput.tool_input, opts.toolOwners)); };
+                                    if (v.decision === "deny") {
+                                        refundCall();
+                                        return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: v.reason } };
+                                    }
+                                    if (v.input) {
+                                        // A rewritten call is answered "allow", and an allow skips
+                                        // canUseTool — where the shell and path confinement live. So
+                                        // the rewrite goes through the same checks here: a hook can
+                                        // narrow what the agent does, never widen it.
+                                        const again = hookInput.tool_name === "Bash"
+                                            ? checkBash(String(v.input.command ?? ""))
+                                            : isFilesystemTool(hookInput.tool_name)
+                                                ? checkPaths(hookInput.tool_name, v.input, { agentDir, workspaceRoot, libraryRoot })
+                                                : { ok: true };
+                                        const granted = opts.allowed.includes(hookInput.tool_name) || opts.mcpNames.some((n) => hookInput.tool_name.startsWith(`mcp__${n}__`));
+                                        // The sub-agent guard read the ORIGINAL input: a rewrite of a
+                                        // delegation could otherwise swap subagent_type for one this
+                                        // step never declared (or the SDK's general-purpose).
+                                        const delegation = guardSubagent ? guardSubagent({ agentId, agentType, tool: hookInput.tool_name, input: v.input }) : null;
+                                        if (!again.ok || !granted || delegation) {
+                                            refundCall();
+                                            const why = !granted ? `Tool ${hookInput.tool_name} is not enabled for this agent.` : delegation ? `the rewritten call: ${delegation}` : `the rewritten call: ${again.reason}`;
+                                            emit("error", why, via ? { subagent: via } : undefined);
+                                            return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: why } };
+                                        }
+                                        return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: again.updatedInput ?? v.input } };
+                                    }
+                                }
                                 if (!verdict?.updatedInput)
                                     return {};
                                 return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: verdict.updatedInput } };
@@ -281,12 +363,26 @@ async function executeStepInner(opts, runQuery) {
                 // after its next tool call, as context — never as a change to what it
                 // may do. A model that is only writing, calling no tools, hears it at
                 // the next call it makes.
-                ...(opts.inbox
+                ...(opts.inbox || resultHooks.length
                     ? {
                         PostToolUse: [{
                                 hooks: [async (hookInput) => {
                                         if (hookInput.hook_event_name !== "PostToolUse")
                                             return {};
+                                        // tool.result hooks watch: the call has happened, so one
+                                        // that fails is recorded and the step goes on.
+                                        for (const hook of resultHooks) {
+                                            if (!matchesTool(hook.tool, hookInput.tool_name))
+                                                continue;
+                                            const response = hookInput.tool_response;
+                                            const a = await callHook(hook, { ...hookBase, event: "tool.result", hook: hook.name, tool: { name: hookInput.tool_name, input: hookInput.tool_input ?? {} }, result: response ?? null });
+                                            if (!a.ok)
+                                                record({ hook: hook.name, event: "tool.result", did: "error", tool: hookInput.tool_name, reason: a.failure, ms: a.ms });
+                                            else if (a.note)
+                                                record({ hook: hook.name, event: "tool.result", did: "note", tool: hookInput.tool_name, reason: a.note, ms: a.ms });
+                                        }
+                                        if (!opts.inbox)
+                                            return {};
                                         // A sub-agent's call: the message is for the step's own
                                         // model, and draining it here would hand it to a context
                                         // that ends with the delegation — and lose it.
@@ -614,6 +710,21 @@ async function executeStepInner(opts, runQuery) {
         status = "failed";
         emit("error", "the model stream ended without a result — the model process likely died (out of memory?)");
     }
+    // step.end hooks watch the reply, and may rewrite it. One that fails is
+    // recorded and the reply stands: the work it describes is done.
+    if (status === "completed") {
+        for (const hook of hooks.filter((h) => h.on === "step.end")) {
+            const a = await callHook(hook, { ...hookBase, event: "step.end", hook: hook.name, reply: texts.join("\n").trim() });
+            if (!a.ok)
+                record({ hook: hook.name, event: "step.end", did: "error", reason: a.failure, ms: a.ms });
+            else if (a.reply !== undefined) {
+                texts.splice(0, texts.length, a.reply);
+                record({ hook: hook.name, event: "step.end", did: "reply", ms: a.ms });
+            }
+            else if (a.note)
+                record({ hook: hook.name, event: "step.end", did: "note", reason: a.note, ms: a.ms });
+        }
+    }
     const result = texts.join("\n").trim() || null;
     // A step's reply is not one message: the model narrates ("Now let me read
     // the outputs…"), calls tools, and answers last. Joining those and reading

package/dist/src/store.d.ts

@@ -12,6 +12,7 @@ import type { OperatorEvent } from "./operator.ts";
  * the runtime, and there is nothing to fail to import.
  */
 export declare function readFrontmatter(file: string): Record<string, unknown>;
+import { type NetworkPolicy } from "./network.ts";
 import { type WireFormat, type AuthShape } from "./providers.ts";
 /**
  * Single-workspace mode. When set, the workspace IS this directory — no
@@ -20,7 +21,7 @@ import { type WireFormat, type AuthShape } from "./providers.ts";
  * core needs to know about which one it's in.
  */
 export { singleWorkspace };
-export declare const WORKSPACE_DIRS: readonly ["agents", "flows", "evals", "skills", "memory", "knowledge", "tools", "scripts", "state"];
+export declare const WORKSPACE_DIRS: readonly ["agents", "flows", "evals", "skills", "memory", "knowledge", "tools", "scripts", "hooks", "state"];
 export declare const STORAGE_DIR = "storage";
 /** What this directory was called before. Read-only: nothing writes here any
  *  more, but installs created before the rename have bytes under it, and a
@@ -331,6 +332,17 @@ export interface AgentInfo {
     /** What is wrong with the `limits:` block's shape; key-vs-grant problems
      *  need the tool lists, and `check` adds them (limits.ts limitKeyProblems). */
     limitProblems: string[];
+    /** What cannot be read in `network:` (network.ts) — a level that is not
+     *  one, a site with a scheme or a path. */
+    networkProblems: string[];
+    /** The sites this agent's steps may reach, resolved the way a run
+     *  resolves them — its `network:`, the workspace's, the account's, and
+     *  the default (open when it may fetch or browse the web, else trusted).
+     *  `implied` here is its `apis:` hosts; a run also adds its MCP servers',
+     *  its web providers' and its bound secrets' sites. */
+    network: NetworkPolicy & {
+        readsWeb: boolean;
+    };
     /** Tools this agent declares inline rather than in `tools:` — `apis:`,
      *  `scripts:` and `mcpServers:` names — which a limit may also name. */
     inlineTools: string[];
@@ -893,6 +905,16 @@ export interface RunEvent {
      *  detail), `output: json`, a schema. What the runner reads to decline a
      *  retry of an outward step whose tools already ran. */
     check?: boolean;
+    /** Set on the line a hook wrote — a deny, a rewrite, context, a failure
+     *  (hooks.ts). The run page and the Hooks page read these. */
+    hook?: {
+        hook: string;
+        event: string;
+        did: string;
+        tool?: string;
+        reason?: string;
+        ms: number;
+    };
 }
 /** A question an agent asked a person while its step ran (tools: [ask]). */
 export interface StepQuestion {

package/dist/src/store.js

@@ -44,7 +44,8 @@ import { refNames } from "./refs.js";
 import { parseBudget, budgetProblem } from "./budget.js";
 import { timezoneProblem } from "./clock.js";
 import { parseStepLimits, readLimits } from "./limits.js";
-import { webProblems, webWarnings, runnerEngines } from "./providers.js";
+import { networkProblems, resolveNetwork } from "./network.js";
+import { webProblems, webWarnings, runnerEngines, webConfig } from "./providers.js";
 import { actionProblems } from "./web-actions.js";
 import { languageProblem } from "./language.js";
 import { localeProblems } from "./locale.js";
@@ -74,6 +75,7 @@ export const WORKSPACE_DIRS = [
     "knowledge",
     "tools",
     "scripts",
+    "hooks",
     "state",
 ];
 const IN_WORKSPACE_DIR = new RegExp(`^(${WORKSPACE_DIRS.join("|")})/`);
@@ -1094,6 +1096,17 @@ export function listAgents(tenant, workspace) {
     const dir = path.join(workspaceDir(tenant, workspace), "agents");
     if (!fs.existsSync(dir))
         return [];
+    // The two levels above every agent, for the network: cascade.
+    const frontOf = (file) => {
+        try {
+            return readFrontmatter(file);
+        }
+        catch {
+            return {}; // no AGENTS.md at that level, or one that does not parse
+        }
+    };
+    const accountFront = frontOf(path.join(accountDir(tenant), "AGENTS.md"));
+    const workspaceFront = frontOf(path.join(workspaceDir(tenant, workspace), "AGENTS.md"));
     return fs
         .readdirSync(dir)
         .filter((n) => fs.existsSync(path.join(dir, n, "agent.md")))
@@ -1101,7 +1114,25 @@ export function listAgents(tenant, workspace) {
         .map((name) => {
         const { data } = matter(fs.readFileSync(path.join(dir, name, "agent.md"), "utf8"));
         const tools = refNames(data.tools);
+        const actions = webConfig(data, { ...accountFront, ...workspaceFront }).actions;
+        const readsWeb = tools.includes("web") && (!actions || actions.some((a) => a === "fetch" || a === "browse"));
+        const network = {
+            ...resolveNetwork({
+                account: accountFront.network,
+                workspace: workspaceFront.network,
+                agent: data.network,
+                readsWeb,
+                implied: parseApis(data.apis).map((a) => { try {
+                    return new URL(a.base).host;
+                }
+                catch {
+                    return "";
+                } }),
+            }),
+            readsWeb,
+        };
         return {
+            network,
             name,
             description: data.description ?? "",
             model: data.model ?? "default",
@@ -1125,6 +1156,7 @@ export function listAgents(tenant, workspace) {
             webWarnings: webWarnings(data, { chrome: runnerEngines()?.chrome, chromium: runnerEngines()?.chromium }),
             scheduleProblem: agentScheduleProblem(data),
             ...(() => { const l = readLimits(data.limits); return { limits: l.limits, limitProblems: l.problems }; })(),
+            networkProblems: networkProblems(data.network),
             inlineTools: inlineToolNames(data),
         };
     });

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

@@ -0,0 +1,45 @@
+/** One string argument: what it means, whether it may be left out, how long it may be. */
+export interface LoopArg {
+    description?: string;
+    optional?: boolean;
+    max?: number;
+}
+export interface LoopTool {
+    name: string;
+    description: string;
+    args: Record<string, LoopArg>;
+    /** The answer the model reads. A throw becomes an error result, not a crash. */
+    run: (args: Record<string, string | undefined>) => Promise<string> | string;
+}
+export interface LoopUsage {
+    /** Everything sent, cache reads and writes included. */
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+export interface LoopResult {
+    /** The last turn's text — the answer, not the thinking aloud between tool calls. */
+    text: string;
+    /** What the SDK reports the query cost; 0 when it never reported (killed). */
+    costUsd: number;
+    usage: LoopUsage | null;
+    /** Why it ended, when it did not end well: max turns, budget, wall clock. */
+    stopped: string | null;
+}
+export interface LoopOptions {
+    system: string;
+    prompt: string;
+    tools: LoopTool[];
+    model: string;
+    /** The model credential and anything else the SDK process needs. */
+    env: Record<string, string | undefined>;
+    maxTurns: number;
+    maxBudgetUsd: number;
+    maxOutputTokens: number;
+    wallSeconds: number;
+    /** The reply as it is written, for a live view. */
+    onText?: (delta: string) => void;
+}
+/** The Agent SDK's name for one of our tools. */
+export declare const loopToolName: (name: string) => string;
+export declare function runToolLoop(o: LoopOptions): Promise<LoopResult>;

package/dist/src/tool-loop.js

@@ -0,0 +1,133 @@
+// A model with tools that live in this process, and nothing else.
+//
+// What the platform's assistant needs (and what the eval judge and the flow
+// draft are a toolless special case of): one Agent SDK query whose ONLY
+// tools are the ones the caller passes — no built-in tool, no file system,
+// no shell, no sub-agent, no MCP server the machine happens to have — run in
+// a throwaway directory, inside a turn, dollar and wall-clock ceiling.
+//
+// The tools run here, in the caller's process, so whatever they read they
+// read with the caller's own scoping; the model only ever sees what a tool
+// returns. That is why this needs no sandbox pod: nothing the model asks for
+// is executed as code.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { query, createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { hostSafeEnv } from "./host-env.js";
+const SERVER = "foldrun_tools";
+/** The Agent SDK's name for one of our tools. */
+export const loopToolName = (name) => `mcp__${SERVER}__${name}`;
+function schemaOf(args) {
+    return Object.fromEntries(Object.entries(args).map(([name, a]) => {
+        let s = z.string().min(a.optional ? 0 : 1);
+        if (a.max)
+            s = s.max(a.max);
+        if (a.description)
+            s = s.describe(a.description);
+        return [name, a.optional ? s.optional() : s];
+    }));
+}
+export async function runToolLoop(o) {
+    const server = createSdkMcpServer({
+        name: SERVER,
+        version: "1.0.0",
+        tools: o.tools.map((t) => tool(t.name, t.description, schemaOf(t.args), async (args) => {
+            try {
+                const plain = Object.fromEntries(Object.entries(args).map(([k, v]) => [k, v === undefined ? undefined : String(v)]));
+                return { content: [{ type: "text", text: await t.run(plain) }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+            }
+        })),
+    });
+    // Homeless on purpose: there are no file tools, and a throwaway cwd means
+    // even a confused call has no tree to touch.
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-loop-"));
+    const abort = new AbortController();
+    let killed = false;
+    const watchdog = setTimeout(() => {
+        killed = true;
+        abort.abort();
+    }, o.wallSeconds * 1000);
+    watchdog.unref?.();
+    let text = "";
+    let costUsd = 0;
+    let usage = null;
+    let stopped = null;
+    try {
+        const q = query({
+            prompt: o.prompt,
+            options: {
+                model: o.model,
+                systemPrompt: o.system,
+                // No built-in tool at all (no Task, so no sub-agents either) — only
+                // ours, each pre-approved; anything else is refused unasked.
+                tools: [],
+                mcpServers: { [SERVER]: server },
+                strictMcpConfig: true,
+                allowedTools: o.tools.map((t) => loopToolName(t.name)),
+                permissionMode: "dontAsk",
+                settingSources: [],
+                persistSession: false,
+                maxTurns: o.maxTurns,
+                maxBudgetUsd: o.maxBudgetUsd,
+                includePartialMessages: true,
+                cwd: scratch,
+                abortController: abort,
+                env: { ...hostSafeEnv(), ...o.env, CLAUDE_CODE_MAX_OUTPUT_TOKENS: String(o.maxOutputTokens) },
+            },
+        });
+        let turn = "";
+        for await (const message of q) {
+            if (message.type === "stream_event") {
+                const e = message.event;
+                if (e.type === "message_start")
+                    turn = "";
+                if (e.type === "content_block_delta" && e.delta.type === "text_delta") {
+                    turn += e.delta.text;
+                    o.onText?.(e.delta.text);
+                }
+            }
+            else if (message.type === "assistant") {
+                const said = message.message.content
+                    .filter((b) => b.type === "text")
+                    .map((b) => b.text)
+                    .join("");
+                if (said.trim())
+                    text = said;
+            }
+            else if (message.type === "result") {
+                costUsd = message.total_cost_usd ?? 0;
+                const models = Object.values(message.modelUsage ?? {});
+                usage = {
+                    inputTokens: models.reduce((n, m) => n + (m.inputTokens ?? 0) + (m.cacheReadInputTokens ?? 0) + (m.cacheCreationInputTokens ?? 0), 0),
+                    outputTokens: models.reduce((n, m) => n + (m.outputTokens ?? 0), 0),
+                    costUsd,
+                };
+                if (message.subtype === "success") {
+                    if (message.result?.trim())
+                        text = message.result;
+                }
+                else {
+                    stopped = message.subtype;
+                    if (!text)
+                        text = turn;
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (!killed)
+            throw err;
+    }
+    finally {
+        clearTimeout(watchdog);
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+    if (killed)
+        stopped = `ran past ${o.wallSeconds}s`;
+    return { text, costUsd, usage, stopped };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "0.7.0",
+  "version": "1.1.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,6 +15,24 @@
       "default": "./dist/src/*.js"
     }
   },
+  "foldrun": {
+    "publicApi": [
+      ".",
+      "./git-hook",
+      "./agents-md",
+      "./browser-pod",
+      "./flow-patterns",
+      "./history",
+      "./hooks",
+      "./kinds",
+      "./layout",
+      "./limits",
+      "./network",
+      "./providers",
+      "./subagents",
+      "./tool-names"
+    ]
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [

package/src/completions.ts

@@ -147,6 +147,7 @@ const FIELDS: Record<string, Completion[]> = {
     { label: "disallowedTools", insert: "disallowedTools:\n  - " },
     { label: "subagents", insert: "subagents:\n  - ", hint: "colleagues it may delegate a job to — own context, own tools, no wider than its own" },
     { label: "limits", insert: "limits:\n  web.search: 40\n  calls: 300", hint: "per step: a call past a limit is refused, never run" },
+    { label: "network", insert: "network:\n  - api.example.com", hint: "sites the sandbox may reach: open | trusted | none, or a list added to the trusted list" },
     {
       label: "provider",
       insert: "provider:\n  name: \n  token: ${PROVIDER_TOKEN}",

package/src/deploy.ts

@@ -40,6 +40,7 @@ import { conformanceIssues } from "./okf.ts";
 import { timezoneProblem } from "./clock.ts";
 import { webProblems, webWarnings, runnerEngines } from "./providers.ts";
 import { readLimits } from "./limits.ts";
+import { networkProblems } from "./network.ts";
 import { actionProblems } from "./web-actions.ts";
 import { languageProblem } from "./language.ts";
 import { localeProblems } from "./locale.ts";
@@ -326,6 +327,9 @@ export function deployIssues(files: DeployFile[]): DeployIssue[] {
     // `limits:` that cannot be read — a count of 0, a word, web.<not an
     // action> — would run uncapped where the author meant a cap.
     for (const w of readLimits(front.limits).problems) at(f.path, w);
+    // `network:` that cannot be read would leave the step on the level
+    // above it — wider or narrower than the author wrote.
+    for (const w of networkProblems(front.network)) at(f.path, w);
     const lang = languageProblem(front.language);
     if (lang) at(f.path, lang);
     for (const w of localeProblems(front)) at(f.path, w);

package/src/egress.ts

@@ -31,12 +31,21 @@
 // `FOLDRUN_EGRESS` instead, and sends through the proxy like everything
 // else.
 //
+// A secret BOUND to sites in the vault (`foldrun secrets set NAME --site
+// api.example.com`) is never materialised, whatever the step grants: the
+// pod's programs all send through the proxy's forward door (HTTPS_PROXY),
+// and for a bound site the door terminates TLS with the platform's egress CA
+// — which the sandbox trusts — and fills `${NAME}` in the URL and headers on
+// the way out, the way Anthropic's cloud sandboxes attach a network secret.
+// Every other site is a tunnel the proxy does not read.
+//
 // This file is the vocabulary both sides share. The server is the
 // platform's (it needs a long-lived process and a Service); the pod side is
 // here in core, because it is what the runner image runs.
 
 import { trimSlashes } from "./paths.ts";
 import type { TestEffect } from "./test-mode.ts";
+import type { NetworkLevel } from "./network.ts";
 
 /** `${NAME}` — the shape a secret reference takes everywhere in foldrun. */
 export const PLACEHOLDER = /\$\{([A-Z][A-Z0-9_]*)\}/g;
@@ -99,11 +108,28 @@ export interface EgressGrant {
    *  that has to put a rate-limit reset into words — and a reset time is
    *  only useful in the calendar the step works to. See refusal.ts. */
   timezone?: string;
+  /** Which sites the step may reach through the proxy's forward door
+   *  (network.ts). Absent on a grant from a runner that predates it: the
+   *  forward door then allows only the hosts the secrets were granted to. */
+  network?: { level: NetworkLevel; hosts: string[] };
+  /** Refuse a site off the list (true), or allow it and name it in the
+   *  trace (false: report only). Set by the platform when it leases. */
+  enforce?: boolean;
 }
 
 export interface EgressLease {
   /** The base the pod sends through: `http://…/e/<token>`. */
   url: string;
+  /** The forward-proxy address for HTTP_PROXY / HTTPS_PROXY —
+   *  `http://foldrun:<token>@host:port` — when the platform's proxy has the
+   *  forward door. Absent on an older proxy: programs then go direct. */
+  proxy?: string;
+  /** The PEM of the CA the forward door signs with for a host a secret is
+   *  bound to, so the sandbox can trust exactly those interceptions. */
+  ca?: string;
+  /** Whether a site off the step's list is refused (true) or only named
+   *  in the trace (false). */
+  enforce?: boolean;
   /** The grant is finished being built — publish it. The runner keeps
    *  adding grants after the lease exists (the model key's host needs the
    *  lease URL first), so a store that is not this process's memory has