@foldrun/core 0.7.0 → 1.0.0

package/dist/src/providers.js

@@ -352,7 +352,7 @@ export function browseEngineRefusal(engine, what) {
 }
 const BROWSE_SETTING_KEYS = [
     "engine", "user_agent", "device", "locale", "timezone", "cookies", "cookie_domain", "storage", "storage_origin", "identities", "headless", "version", "live",
-    "allowed_domains", "deny", "boundaries", "init", "extensions", "webgpu", "ignore_https_errors", "state_key",
+    "allowed_domains", "deny", "boundaries", "init", "extensions", "webgpu", "ignore_https_errors", "state_key", "state",
     "video", "live_view", "vendor_session",
     // Deprecated spelling of vendor_session (read, and warned about).
     "session",
@@ -696,6 +696,12 @@ export function readBrowseSettings(raw) {
                 settings[k] = list;
             continue;
         }
+        if (k === "state") {
+            if (typeof v !== "string" || !/^[A-Za-z0-9._-]{1,64}$/.test(v))
+                return { settings, rest: left(rest), error: "web.browse.state is a plain name (letters, digits, dot, dash, underscore), like youtube — the login is kept in workspace/state/browser/<name>.json." };
+            settings.state = v;
+            continue;
+        }
         if (k === "state_key") {
             if (typeof v !== "string" || !/^[A-Z][A-Z0-9_]{0,63}$/.test(v))
                 return { settings, rest: left(rest), error: "web.browse.state_key must be the NAME of a vault secret (CAPITALS), never the key — store it with `foldrun secrets set NAME` and declare it under secrets:." };
@@ -762,6 +768,20 @@ export function readBrowseSettings(raw) {
                 `would be sent to whatever site the call opens. Write \`cookie_domain: .example.com\`.`,
         };
     }
+    // A secret's cookies seeding a saved login: the login then sits in state/,
+    // a workspace file, so it must be encrypted with a key from the vault.
+    if (settings.state && settings.cookies && !settings.state_key) {
+        return {
+            settings,
+            rest: left(rest),
+            error: `web.browse.state beside cookies needs web.browse.state_key — the secret's session would be saved ` +
+                `to state/ where any step can read it. Store a key (\`foldrun secrets set BROWSER_STATE_KEY\`), ` +
+                `write \`state_key: BROWSER_STATE_KEY\` and declare it under secrets:.`,
+        };
+    }
+    if (settings.state && settings.storage) {
+        return { settings, rest: left(rest), error: "web.browse.state cannot be combined with storage: a secret's tokens would be written to state/." };
+    }
     // Storage is per origin, and seeding it into the wrong one would hand a
     // site another site's signed-in state — the same mistake `cookie_domain`
     // exists to prevent, one storage area over.

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

@@ -1,3 +1,4 @@
+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";
@@ -52,6 +53,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 +344,7 @@ export declare function parseDriverLine(line: string): {
     operator?: OperatorEvent;
     subagent?: string;
     check?: boolean;
+    hook?: HookRecord;
 } | ({
     e: "done";
 } & ContainerStepOutcome) | null;

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";
@@ -42,7 +43,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 +534,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
@@ -983,6 +987,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";
@@ -1214,6 +1215,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 +2169,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 —
@@ -2325,6 +2339,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
@@ -2683,6 +2698,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 —

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 |
@@ -439,6 +440,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

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

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

@@ -20,7 +20,7 @@ import { type WireFormat, type AuthShape } from "./providers.ts";
  * core needs to know about which one it's in.
  */
 export { singleWorkspace };
-export declare const WORKSPACE_DIRS: readonly ["agents", "flows", "evals", "skills", "memory", "knowledge", "tools", "scripts", "state"];
+export declare const WORKSPACE_DIRS: readonly ["agents", "flows", "evals", "skills", "memory", "knowledge", "tools", "scripts", "hooks", "state"];
 export declare const STORAGE_DIR = "storage";
 /** What this directory was called before. Read-only: nothing writes here any
  *  more, but installs created before the rename have bytes under it, and a
@@ -893,6 +893,16 @@ export interface RunEvent {
      *  detail), `output: json`, a schema. What the runner reads to decline a
      *  retry of an outward step whose tools already ran. */
     check?: boolean;
+    /** Set on the line a hook wrote — a deny, a rewrite, context, a failure
+     *  (hooks.ts). The run page and the Hooks page read these. */
+    hook?: {
+        hook: string;
+        event: string;
+        did: string;
+        tool?: string;
+        reason?: string;
+        ms: number;
+    };
 }
 /** A question an agent asked a person while its step ran (tools: [ask]). */
 export interface StepQuestion {

package/dist/src/store.js

@@ -74,6 +74,7 @@ export const WORKSPACE_DIRS = [
     "knowledge",
     "tools",
     "scripts",
+    "hooks",
     "state",
 ];
 const IN_WORKSPACE_DIR = new RegExp(`^(${WORKSPACE_DIRS.join("|")})/`);

package/package.json

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