@foldrun/core 0.7.0 → 1.0.0

package/README.md

@@ -222,9 +222,22 @@ allow products built on its Agent SDK to offer claude.ai login unless
 Anthropic has approved them, so check that the terms cover your use before
 you rely on a login token.
 
+## Versions
+
+[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html): a patch is
+a bug fix, a minor adds something and breaks nothing, a major breaks
+something and says what. The promise covers the **public API**, the entry
+points listed in `package.json` under `foldrun.publicApi`: `@foldrun/core`
+itself and the subpaths the `foldrun` CLI imports. Every other module under
+`@foldrun/core/*` can be reached, because the runner image imports its own
+copy by name, but it is internal and may change in any release. Deprecated
+names say so in their doc comment for at least one minor before a major
+removes them. Pre-releases are on npm's `next` tag. How a release decides
+its number: [CONTRIBUTING.md](CONTRIBUTING.md#versions).
+
 ## Status
 
-v0.1. Local and hosted runs work. Hosted runs go through a durable on-disk
+Local and hosted runs work. Hosted runs go through a durable on-disk
 queue (survives restarts, parks at approval gates), the dashboard has
 accounts and sessions (scrypt + signed cookies; first signup is free, then
 `FOLDRUN_OPEN_SIGNUP=1`), spending lands in an append-only per-account

package/dist/src/hooks.d.ts

@@ -0,0 +1,114 @@
+export declare const HOOK_EVENTS: readonly ["tool.call", "tool.result", "step.start", "step.end"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+export declare const HOOK_TIMEOUT_DEFAULT: {
+    readonly gate: 30;
+    readonly watch: 60;
+};
+export declare const HOOK_TIMEOUT_MAX = 120;
+export declare const HOOK_CODE_MAX: number;
+export interface HookDef {
+    name: string;
+    /** The folder holding hook.md and run.mjs. */
+    dir: string;
+    scope: "workspace" | "account";
+    on: HookEvent;
+    /** `tool:` — which tools a tool.call / tool.result hook sees. Unset is all. */
+    tool?: string;
+    timeoutSec: number;
+    description?: string;
+    /** run.mjs as it was when the step started. The hook runs from this copy,
+     *  so an agent that edits the file mid-step changes nothing that runs. */
+    code: string;
+}
+/** Read hook.md, or say in one sentence why it is not a hook. */
+export declare function readHookDef(dir: string, scope: HookDef["scope"]): HookDef | {
+    error: string;
+};
+/** Every hook folder in a hooks/ directory. */
+export declare function listHookDirs(hooksDir: string): string[];
+/** The names a frontmatter `hooks:` holds — a list, or one name. */
+export declare function hookNames(raw: unknown): string[];
+/**
+ * The hooks one agent runs, in order: what the account turned on, then the
+ * workspace, then the agent itself, each name once. A name resolves to the
+ * workspace's own hooks/ first, then the library's. Names that resolve to
+ * nothing come back in `missing` — `foldrun check` errors on them, and a run
+ * refuses to start the step rather than run unguarded.
+ */
+export declare function resolveHooks(args: {
+    workspaceRoot: string;
+    libraryRoot: string;
+    names: string[];
+}): {
+    hooks: HookDef[];
+    missing: string[];
+    errors: string[];
+};
+/**
+ * Does `pattern` name this tool? Alternatives split on `|`, `*` matches any
+ * run of characters. A pattern without `__` also matches a tool's short
+ * name, so `web` catches `mcp__foldrun_scripts__web` and `Bash` catches Bash.
+ */
+export declare function matchesTool(pattern: string | undefined, tool: string): boolean;
+/** What one hook said, normalised. */
+export interface HookAnswer {
+    ok: boolean;
+    /** tool.call */
+    decision?: "allow" | "deny";
+    reason?: string;
+    input?: Record<string, unknown>;
+    /** step.start */
+    context?: string;
+    /** step.end */
+    reply?: string;
+    /** tool.result / anything: a line for the trail */
+    note?: string;
+    /** Why it failed — threw, timed out, wrong shape. */
+    failure?: string;
+    ms: number;
+}
+export declare function hookEnv(from: Record<string, string | undefined>, hook: HookDef): Record<string, string>;
+/** Run one hook on one event. Never throws: a failure is an answer. */
+export declare function runHook(hook: HookDef, event: Record<string, unknown>, opts: {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    node?: string;
+}): Promise<HookAnswer>;
+/** The last JSON object a hook printed, checked against its event's shape. */
+export declare function parseAnswer(on: HookEvent, stdout: string): Omit<HookAnswer, "ms">;
+/** What a run of tool.call hooks decided for one call. */
+export interface ToolCallVerdict {
+    decision: "allow" | "deny";
+    reason?: string;
+    /** The input after every rewrite, when any hook rewrote it. */
+    input?: Record<string, unknown>;
+    /** One line per hook that did something, for the trail. */
+    records: HookRecord[];
+}
+/** One hook's effect, as the trail keeps it. */
+export interface HookRecord {
+    hook: string;
+    event: HookEvent;
+    /** deny | rewrite | context | reply | note | error */
+    did: "deny" | "rewrite" | "context" | "reply" | "note" | "error";
+    tool?: string;
+    reason?: string;
+    ms: number;
+}
+/** A hook record as it crosses from the sandbox: checked, never trusted. */
+export declare function isHookRecord(x: unknown): x is HookRecord;
+export declare function isGate(on: HookEvent): boolean;
+/**
+ * tool.call: every matching hook in order. The first deny ends it — the most
+ * restrictive answer wins; a rewrite is handed on to the next hook, so they
+ * chain in the order they were turned on. A hook that fails denies.
+ */
+export declare function runToolCallHooks(hooks: HookDef[], call: {
+    tool: string;
+    input: Record<string, unknown>;
+    base: Record<string, unknown>;
+}, run: (hook: HookDef, event: Record<string, unknown>) => Promise<HookAnswer>): Promise<ToolCallVerdict>;
+/** The trail's line for a record. */
+export declare function hookLine(r: HookRecord): string;
+/** For `foldrun check`: every problem with the hooks/ folder of one root. */
+export declare function checkHooksDir(hooksDir: string, scope: HookDef["scope"]): string[];

package/dist/src/hooks.js

@@ -0,0 +1,370 @@
+// Hooks: a person's own code at the points every model's step passes through.
+//
+// A hook is a folder — `hooks/<name>/hook.md` (what it listens for) beside
+// `run.mjs` (what it does) — in a workspace, or in the account library for
+// every workspace. An agent turns one on with `hooks: [name]`; a workspace's
+// or the account's AGENTS.md turns one on for every agent under it.
+//
+// Where they run, and why there: at foldrun's own dispatch, the step's
+// PreToolUse / PostToolUse callbacks in step-exec.ts. Every model goes
+// through that one loop — another provider's model is the same loop with the
+// translator changing the wire format underneath — so one hook decides the
+// same way on every model. Nothing here is tied to one provider's features
+// (thinking blocks, effort, server tools).
+//
+// The contract, kept to what the established agent tools agree on (Claude
+// Code, the Agent SDK, Cursor, Copilot, Gemini CLI): the event goes in as
+// one JSON object on stdin, an answer comes back as one JSON object on
+// stdout. Exit 0 with an answer; exit 2 denies with stderr as the reason
+// (the common convention); anything else is a failure.
+//
+// Gates fail closed. A tool.call or step.start hook that throws, times out or
+// answers with the wrong shape refuses the call — a guard that crashes must
+// not become an open door. A watcher (tool.result, step.end) that fails is
+// recorded and the step goes on: what it watches has already happened.
+//
+// A hook has no more reach than the agent: it runs as a child of the step,
+// inside the step's own sandbox, in the agent's directory, with an
+// environment stripped to the basics — no secrets, no model key.
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawn } from "node:child_process";
+import matter from "gray-matter";
+export const HOOK_EVENTS = ["tool.call", "tool.result", "step.start", "step.end"];
+/** Events that decide something before it happens: a failure refuses. */
+const GATES = new Set(["tool.call", "step.start"]);
+export const HOOK_TIMEOUT_DEFAULT = { gate: 30, watch: 60 };
+export const HOOK_TIMEOUT_MAX = 120;
+export const HOOK_CODE_MAX = 100 * 1024;
+const NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Read hook.md, or say in one sentence why it is not a hook. */
+export function readHookDef(dir, scope) {
+    const name = path.basename(dir);
+    if (!NAME.test(name))
+        return { error: `hooks/${name}: a hook's folder name is lowercase letters, digits and dashes` };
+    const md = path.join(dir, "hook.md");
+    if (!fs.existsSync(md))
+        return { error: `hooks/${name}: no hook.md` };
+    if (!fs.existsSync(path.join(dir, "run.mjs")))
+        return { error: `hooks/${name}: no run.mjs beside hook.md` };
+    let data;
+    try {
+        data = (matter(fs.readFileSync(md, "utf8")).data ?? {});
+    }
+    catch (err) {
+        return { error: `hooks/${name}/hook.md: frontmatter does not parse (${err.message.split("\n")[0]})` };
+    }
+    const on = data.on;
+    if (typeof on !== "string" || !HOOK_EVENTS.includes(on)) {
+        return { error: `hooks/${name}/hook.md: on: must be one of ${HOOK_EVENTS.join(", ")}${on === "run.end" ? " (run.end is not available yet)" : ""}` };
+    }
+    const event = on;
+    if (data.tool !== undefined && (typeof data.tool !== "string" || !data.tool.trim())) {
+        return { error: `hooks/${name}/hook.md: tool: is a tool name or pattern, like Bash, Write|Edit or mcp__*` };
+    }
+    if (data.tool !== undefined && event !== "tool.call" && event !== "tool.result") {
+        return { error: `hooks/${name}/hook.md: tool: only means something on tool.call and tool.result` };
+    }
+    // It runs through `node --eval`, one argument, which Linux caps at 128 KB.
+    const code = fs.readFileSync(path.join(dir, "run.mjs"), "utf8");
+    if (Buffer.byteLength(code) > HOOK_CODE_MAX) {
+        return { error: `hooks/${name}/run.mjs is ${Math.round(Buffer.byteLength(code) / 1024)} KB — a hook is one small self-contained module, at most ${HOOK_CODE_MAX / 1024} KB` };
+    }
+    const deflt = GATES.has(event) ? HOOK_TIMEOUT_DEFAULT.gate : HOOK_TIMEOUT_DEFAULT.watch;
+    const timeout = data.timeout === undefined ? deflt : Number(data.timeout);
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > HOOK_TIMEOUT_MAX) {
+        return { error: `hooks/${name}/hook.md: timeout: is seconds, 1 to ${HOOK_TIMEOUT_MAX}` };
+    }
+    return {
+        name,
+        dir,
+        scope,
+        on: event,
+        ...(typeof data.tool === "string" ? { tool: data.tool.trim() } : {}),
+        timeoutSec: timeout,
+        ...(typeof data.description === "string" ? { description: data.description } : {}),
+        code,
+    };
+}
+/** Every hook folder in a hooks/ directory. */
+export function listHookDirs(hooksDir) {
+    if (!fs.existsSync(hooksDir))
+        return [];
+    return fs.readdirSync(hooksDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+        .map((d) => path.join(hooksDir, d.name))
+        .sort();
+}
+/** The names a frontmatter `hooks:` holds — a list, or one name. */
+export function hookNames(raw) {
+    const list = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(",") : [];
+    return list.map((x) => String(x).trim()).filter(Boolean);
+}
+/**
+ * The hooks one agent runs, in order: what the account turned on, then the
+ * workspace, then the agent itself, each name once. A name resolves to the
+ * workspace's own hooks/ first, then the library's. Names that resolve to
+ * nothing come back in `missing` — `foldrun check` errors on them, and a run
+ * refuses to start the step rather than run unguarded.
+ */
+export function resolveHooks(args) {
+    const hooks = [];
+    const missing = [];
+    const errors = [];
+    const seen = new Set();
+    for (const name of args.names) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const own = path.join(args.workspaceRoot, "hooks", name);
+        const shared = path.join(args.libraryRoot, "hooks", name);
+        const dir = fs.existsSync(own) ? own : fs.existsSync(shared) ? shared : null;
+        if (!dir) {
+            missing.push(name);
+            continue;
+        }
+        const def = readHookDef(dir, dir === own ? "workspace" : "account");
+        if ("error" in def)
+            errors.push(def.error);
+        else
+            hooks.push(def);
+    }
+    return { hooks, missing, errors };
+}
+/**
+ * Does `pattern` name this tool? Alternatives split on `|`, `*` matches any
+ * run of characters. A pattern without `__` also matches a tool's short
+ * name, so `web` catches `mcp__foldrun_scripts__web` and `Bash` catches Bash.
+ */
+export function matchesTool(pattern, tool) {
+    if (!pattern)
+        return true;
+    const short = tool.includes("__") ? tool.slice(tool.lastIndexOf("__") + 2) : tool;
+    return pattern.split("|").map((p) => p.trim()).filter(Boolean).some((p) => {
+        const re = new RegExp(`^${p.replace(/[.+?^${}()[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`);
+        return re.test(tool) || (!p.includes("__") && re.test(short));
+    });
+}
+/** Only these reach a hook's process: enough to run node, nothing to act with. */
+const PASSED_ENV = ["PATH", "LANG", "LC_ALL", "TZ", "TMPDIR", "NODE_PATH"];
+/** One empty home per hook name, made once: a hook reads no dotfile the
+ *  step's own home holds (a CLI login, a cached token). */
+function hookHome(hook) {
+    const dir = path.join(os.tmpdir(), "foldrun-hook-home", hook.name);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+export function hookEnv(from, hook) {
+    const env = {};
+    for (const k of PASSED_ENV)
+        if (from[k])
+            env[k] = from[k];
+    env.HOME = hookHome(hook);
+    env.FOLDRUN_HOOK = hook.name;
+    env.FOLDRUN_HOOK_EVENT = hook.on;
+    return env;
+}
+/** Run one hook on one event. Never throws: a failure is an answer. */
+export async function runHook(hook, event, opts) {
+    const started = Date.now();
+    const done = (a) => ({ ...a, ms: Date.now() - started });
+    return new Promise((resolve) => {
+        let out = "";
+        let err = "";
+        let settled = false;
+        const finish = (a) => { if (!settled) {
+            settled = true;
+            resolve(done(a));
+        } };
+        // Typed: untyped, a stricter tsc (foldrun-web compiles this file) narrows
+        // it to never after the catch that returns.
+        let child;
+        try {
+            // From the copy taken at the start of the step, never the file: what
+            // guards the step cannot be edited by the step. One self-contained
+            // module — Node's built-ins only, no relative imports.
+            child = spawn(opts.node ?? process.execPath, ["--input-type=module", "--eval", hook.code], {
+                cwd: opts.cwd,
+                // Cast: Next's typings (foldrun-web compiles this file) make NODE_ENV
+                // required on ProcessEnv; a hook deliberately gets only hookEnv's keys.
+                env: hookEnv(opts.env, hook),
+                stdio: ["pipe", "pipe", "pipe"],
+                // Its own process group, so a timeout can kill what the hook started
+                // too: SIGKILL to node alone left a `sleep` or a curl it spawned
+                // running in the sandbox after the call had been refused.
+                detached: process.platform !== "win32",
+            });
+        }
+        catch (e) {
+            return finish({ ok: false, failure: `could not start: ${e.message}` });
+        }
+        const killAll = () => {
+            try {
+                if (child.pid && process.platform !== "win32")
+                    process.kill(-child.pid, "SIGKILL");
+                else
+                    child.kill("SIGKILL");
+            }
+            catch {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { /* already gone */ }
+            }
+        };
+        const timer = setTimeout(() => {
+            killAll();
+            finish({ ok: false, failure: `timed out after ${hook.timeoutSec}s` });
+        }, hook.timeoutSec * 1000);
+        // Keep the TAIL of each stream, not the head: the answer is the last
+        // line of stdout and the reason the last lines of stderr, so a hook that
+        // logged a megabyte first lost its answer under a head cap and failed.
+        // Decoded by the stream, so a character split across two chunks is not
+        // turned into replacement characters inside the JSON answer.
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (b) => { out += b; if (out.length > 1_000_000)
+            out = out.slice(-1_000_000); });
+        child.stderr.on("data", (b) => { err += b; if (err.length > 20_000)
+            err = err.slice(-20_000); });
+        child.on("error", (e) => { clearTimeout(timer); finish({ ok: false, failure: `could not start: ${e.message}` }); });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            // A hook is one shot: whatever it left running in the background goes
+            // with it, rather than outlive the call it was asked about.
+            if (!settled)
+                killAll();
+            const stderr = err.trim().split("\n").slice(-3).join(" ").slice(0, 500);
+            if (code === 2)
+                return finish({ ok: true, decision: "deny", reason: stderr || `${hook.name} refused it` });
+            if (code !== 0) {
+                // An uncaught throw ends stderr with stack frames and "Node.js vN":
+                // the last three lines named neither the error nor its message.
+                const lines = err.split("\n").map((l) => l.trim()).filter((l) => l && !/^Node\.js v\d/.test(l) && !/^at /.test(l));
+                const thrown = [...lines].reverse().find((l) => /^[A-Za-z]*Error\b.*:/.test(l));
+                const why = (thrown ?? lines.slice(-3).join(" ")).slice(0, 500);
+                return finish({ ok: false, failure: `exited ${code ?? "on a signal"}${why ? `: ${why}` : ""}` });
+            }
+            finish(parseAnswer(hook.on, out));
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(JSON.stringify(event));
+    });
+}
+/** The last JSON object a hook printed, checked against its event's shape. */
+export function parseAnswer(on, stdout) {
+    const lines = stdout.trim().split("\n").map((l) => l.trim()).filter(Boolean);
+    if (!lines.length)
+        return { ok: true, decision: on === "tool.call" ? "allow" : undefined };
+    let a;
+    try {
+        a = JSON.parse(lines[lines.length - 1]);
+    }
+    catch {
+        return { ok: false, failure: "its last line of output is not JSON" };
+    }
+    if (!a || typeof a !== "object" || Array.isArray(a))
+        return { ok: false, failure: "it answered with something other than a JSON object" };
+    const o = a;
+    const str = (k) => (o[k] === undefined ? undefined : typeof o[k] === "string" ? o[k] : null);
+    const note = str("note");
+    if (note === null)
+        return { ok: false, failure: "note must be text" };
+    if (on === "tool.call") {
+        const decision = o.decision ?? "allow";
+        if (decision !== "allow" && decision !== "deny")
+            return { ok: false, failure: `decision must be allow or deny, not ${JSON.stringify(decision)}` };
+        const reason = str("reason");
+        if (reason === null)
+            return { ok: false, failure: "reason must be text" };
+        if (decision === "deny" && !reason)
+            return { ok: false, failure: "a deny needs a reason — the model reads it" };
+        if (o.input !== undefined && (!o.input || typeof o.input !== "object" || Array.isArray(o.input)))
+            return { ok: false, failure: "input must be the tool's whole input, as an object" };
+        return { ok: true, decision, ...(reason ? { reason } : {}), ...(o.input ? { input: o.input } : {}), ...(note ? { note } : {}) };
+    }
+    if (on === "step.start") {
+        const context = str("context");
+        if (context === null)
+            return { ok: false, failure: "context must be text" };
+        return { ok: true, ...(context ? { context } : {}), ...(note ? { note } : {}) };
+    }
+    if (on === "step.end") {
+        const reply = str("reply");
+        if (reply === null)
+            return { ok: false, failure: "reply must be text" };
+        return { ok: true, ...(reply !== undefined ? { reply } : {}), ...(note ? { note } : {}) };
+    }
+    return { ok: true, ...(note ? { note } : {}) };
+}
+/** A hook record as it crosses from the sandbox: checked, never trusted. */
+export function isHookRecord(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const r = x;
+    return typeof r.hook === "string" && NAME.test(r.hook)
+        && typeof r.event === "string" && HOOK_EVENTS.includes(r.event)
+        && typeof r.did === "string" && ["deny", "rewrite", "context", "reply", "note", "error"].includes(r.did)
+        && typeof r.ms === "number"
+        && (r.tool === undefined || typeof r.tool === "string")
+        && (r.reason === undefined || typeof r.reason === "string");
+}
+export function isGate(on) {
+    return GATES.has(on);
+}
+/**
+ * tool.call: every matching hook in order. The first deny ends it — the most
+ * restrictive answer wins; a rewrite is handed on to the next hook, so they
+ * chain in the order they were turned on. A hook that fails denies.
+ */
+export async function runToolCallHooks(hooks, call, run) {
+    const records = [];
+    let input = call.input;
+    let rewritten = false;
+    for (const hook of hooks) {
+        if (hook.on !== "tool.call" || !matchesTool(hook.tool, call.tool))
+            continue;
+        const a = await run(hook, { ...call.base, event: "tool.call", hook: hook.name, tool: { name: call.tool, input } });
+        if (!a.ok) {
+            const reason = `hook ${hook.name} failed (${a.failure}), so the call is refused`;
+            records.push({ hook: hook.name, event: "tool.call", did: "error", tool: call.tool, reason, ms: a.ms });
+            return { decision: "deny", reason, records };
+        }
+        if (a.decision === "deny") {
+            records.push({ hook: hook.name, event: "tool.call", did: "deny", tool: call.tool, reason: a.reason, ms: a.ms });
+            return { decision: "deny", reason: `hook ${hook.name}: ${a.reason}`, records };
+        }
+        if (a.input) {
+            input = a.input;
+            rewritten = true;
+            records.push({ hook: hook.name, event: "tool.call", did: "rewrite", tool: call.tool, ...(a.reason ? { reason: a.reason } : {}), ms: a.ms });
+        }
+        else if (a.note) {
+            records.push({ hook: hook.name, event: "tool.call", did: "note", tool: call.tool, reason: a.note, ms: a.ms });
+        }
+    }
+    return { decision: "allow", ...(rewritten ? { input } : {}), records };
+}
+/** The trail's line for a record. */
+export function hookLine(r) {
+    const what = r.tool ? ` ${r.tool}` : "";
+    switch (r.did) {
+        case "deny": return `hook ${r.hook} denied${what}: ${r.reason}`;
+        case "rewrite": return `hook ${r.hook} rewrote${what}${r.reason ? `: ${r.reason}` : ""}`;
+        case "context": return `hook ${r.hook} added context to the step`;
+        case "reply": return `hook ${r.hook} rewrote the step's reply`;
+        case "note": return `hook ${r.hook}${what}: ${r.reason}`;
+        case "error": return `hook ${r.hook} failed on ${r.event}${what}: ${r.reason}`;
+    }
+}
+/** For `foldrun check`: every problem with the hooks/ folder of one root. */
+export function checkHooksDir(hooksDir, scope) {
+    const problems = [];
+    for (const dir of listHookDirs(hooksDir)) {
+        const def = readHookDef(dir, scope);
+        if ("error" in def)
+            problems.push(def.error);
+    }
+    return problems;
+}

package/dist/src/kinds.d.ts

@@ -1,6 +1,6 @@
 /** Where a document can live. Nearest wins at read time. */
 export type Scope = "account" | "workspace" | "agent";
-export type Kind = "agents" | "flows" | "evals" | "tools" | "skills" | "memory" | "knowledge" | "scripts";
+export type Kind = "agents" | "flows" | "evals" | "tools" | "hooks" | "skills" | "memory" | "knowledge" | "scripts";
 export interface KindMeta {
     kind: Kind;
     /** Singular noun, for buttons and prose. */

package/dist/src/kinds.js

@@ -135,6 +135,32 @@ Notes for whoever maintains this. Agents opt in with:
 \`\`\`yaml
 tools: [${name}]
 \`\`\`
+`,
+    },
+    hooks: {
+        kind: "hooks",
+        one: "hook",
+        docType: null,
+        docKey: null,
+        // Turned on per agent (`hooks:`), or for every agent from an AGENTS.md;
+        // shared ones live in the account library.
+        scopes: ["account", "workspace"],
+        placeholder: "no-force-push",
+        hint: "Your code at every tool call, step start or step end — on every model. Folder: hook.md and run.mjs.",
+        file: (name) => `hooks/${name}/hook.md`,
+        template: (name) => `---
+name: ${name}
+on: tool.call
+tool: Bash
+description: What this hook guards, in one line.
+---
+
+# ${name}
+
+What it refuses or rewrites, and why. The code is run.mjs beside this file:
+it reads the event as JSON on stdin and prints one JSON answer —
+{"decision": "deny", "reason": "..."} to refuse, {"input": {...}} to rewrite,
+{} to let the call through. A hook that fails refuses the call.
 `,
     },
     // Last, and not navigable: a folder tool holds its own code, so scripts

package/dist/src/library.d.ts

@@ -1,5 +1,5 @@
 import { type ToolDef } from "./store.ts";
-export type LibraryKind = "skills" | "scripts" | "memory" | "knowledge" | "tools";
+export type LibraryKind = "skills" | "scripts" | "memory" | "knowledge" | "tools" | "hooks";
 export declare const LIBRARY_KINDS: LibraryKind[];
 export declare function libraryDir(tenant: string, kind?: LibraryKind): string;
 export interface LibraryEntry {

package/dist/src/library.js

@@ -22,7 +22,7 @@ import { assertSafeName, assertCanonicalCase, buildMemoryIndex, parseToolDef, re
 // Order matters and is asserted: it is the order every noun list in the
 // product uses. Tools then scripts, because a script is material a tool
 // points at — see the KINDS table, which is where the order is declared.
-export const LIBRARY_KINDS = ["tools", "knowledge", "memory", "skills", "scripts"];
+export const LIBRARY_KINDS = ["tools", "hooks", "knowledge", "memory", "skills", "scripts"];
 export function libraryDir(tenant, kind) {
     // Alongside the workspace in single-workspace mode: ./library, so a shared
     // library is still possible on a laptop without inventing a home directory.
@@ -117,6 +117,22 @@ export function listLibrary(tenant, kind) {
         }
         return out.sort((a, b) => a.path.localeCompare(b.path));
     }
+    // A hook is a folder: hook.md says when it runs, run.mjs is the code.
+    if (kind === "hooks") {
+        for (const entry of fs.readdirSync(dir).sort()) {
+            const full = path.join(dir, entry);
+            const hookMd = path.join(full, "hook.md");
+            if (!fs.statSync(full).isDirectory() || !fs.existsSync(hookMd))
+                continue;
+            out.push({
+                ...describe(hookMd, entry),
+                path: `${entry}/hook.md`,
+                files: folderFiles(full, entry),
+                updatedAt: fs.statSync(hookMd).mtime.toISOString(),
+            });
+        }
+        return out;
+    }
     if (kind === "skills") {
         for (const entry of fs.readdirSync(dir).sort()) {
             const full = path.join(dir, entry);

package/dist/src/mail.js

@@ -56,7 +56,7 @@ export const MAIL_CATEGORIES = [
         label: "Account notices",
         required: true,
         perWorkspace: false,
-        description: "Something about the account stopped working on its own — a notification webhook switched off after days of failures, a close request.",
+        description: "Something about the account stopped working on its own, or is about to — a notification webhook switched off after days of failures, a close request, an API route it still calls being switched off.",
         why: "each one is the only message saying a thing you rely on has stopped",
     },
     {

package/dist/src/notify.d.ts

@@ -46,6 +46,14 @@ export interface NotifyConfig {
     signingSecret?: string;
 }
 export declare function notifyConfig(tenant: string, workspace: string): NotifyConfig | null;
+/**
+ * The version of the webhook body's shape, sent on every delivery as
+ * `x-foldrun-webhook-version` (and in the user agent). Within a version the
+ * body only gains fields — a receiver must ignore the ones it does not know.
+ * A field removed, renamed or retyped is a new version, announced in What's
+ * new at least six months before the old shape stops being sent.
+ */
+export declare const WEBHOOK_PAYLOAD_VERSION = 1;
 /**
  * The headers that prove a delivery came from this install.
  *

package/dist/src/notify.js

@@ -120,6 +120,14 @@ export function notifyConfig(tenant, workspace) {
 // Said once per process, not once per run: the fix is one env edit, and a
 // line per parked run would bury the failures around it.
 let warnedNoPublicUrl = false;
+/**
+ * The version of the webhook body's shape, sent on every delivery as
+ * `x-foldrun-webhook-version` (and in the user agent). Within a version the
+ * body only gains fields — a receiver must ignore the ones it does not know.
+ * A field removed, renamed or retyped is a new version, announced in What's
+ * new at least six months before the old shape stops being sent.
+ */
+export const WEBHOOK_PAYLOAD_VERSION = 1;
 /**
  * The headers that prove a delivery came from this install.
  *
@@ -205,7 +213,8 @@ export async function attemptWebhook(tenant, workspace, d) {
             method: "POST",
             headers: {
                 "content-type": "application/json",
-                "user-agent": "foldrun-webhooks/1",
+                "user-agent": `foldrun-webhooks/${WEBHOOK_PAYLOAD_VERSION}`,
+                "x-foldrun-webhook-version": String(WEBHOOK_PAYLOAD_VERSION),
                 "x-foldrun-delivery": d.id,
                 "x-foldrun-event": d.event,
                 "x-foldrun-attempt": String(d.attempt),

package/dist/src/providers.d.ts

@@ -346,6 +346,11 @@ export interface BrowseSettings {
     ignore_https_errors?: boolean;
     /** The NAME of a vault secret whose value encrypts state= logins at rest. */
     state_key?: string;
+    /** A saved login every call uses by default: loaded from
+     *  workspace/state/browser/<name>.json and saved back when the call ends.
+     *  Beside `cookies:` (with `state_key:`), the secret seeds it once and the
+     *  session the site keeps rotating is what later runs load. */
+    state?: string;
     /** true records every call, so the run page always has the recording to play. */
     video?: boolean;
     /** false stops the tool streaming its page to the run page while the step