@foldrun/core 0.7.0 → 1.0.0

package/src/runner.ts

@@ -3,6 +3,7 @@
 // fail without failing the flow. A direct agent run is a one-step ad-hoc
 // flow, so there is a single execution path.
 
+import { hookNames } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -1341,6 +1342,7 @@ export function agentContext(
     ...(browseSettings.webgpu ? { FOLDRUN_BROWSER_WEBGPU: "1" } : {}),
     ...(browseSettings.ignore_https_errors ? { FOLDRUN_BROWSER_IGNORE_HTTPS_ERRORS: "1" } : {}),
     ...(browseSettings.state_key ? { FOLDRUN_BROWSER_STATE_KEY: browseSettings.state_key } : {}),
+    ...(browseSettings.state ? { FOLDRUN_BROWSER_STATE: browseSettings.state } : {}),
     ...(browseSettings.video ? { FOLDRUN_BROWSER_VIDEO: "1" } : {}),
     ...(browseSettings.live_view === false ? { FOLDRUN_BROWSER_LIVE_VIEW: "0" } : {}),
   };
@@ -2355,6 +2357,17 @@ async function runStep(
     const limitOwners = toolOwners(apiTools.owners, scriptSpecs);
     const limitOpts = Object.keys(stepLimits).length ? { limits: stepLimits, toolOwners: limitOwners } : {};
     if (limitOpts.limits) push("info", `limits: ${Object.entries(stepLimits).map(([k, n]) => `${k} ${n}`).join(", ")} — per step; a call past one is refused`);
+    // `hooks:` — the account's, the workspace's, then the agent's own, each
+    // once; resolved and run inside the step (hooks.ts, step-exec.ts).
+    const stepHookNames = [...new Set([
+      ...hookNames(readAgentsMd(accountDir(tenant))?.data?.hooks),
+      ...hookNames(readAgentsMd(workspaceRootOf(agentDir))?.data?.hooks),
+      ...hookNames(front.hooks),
+    ])];
+    const hookOpts = stepHookNames.length
+      ? { hookNames: stepHookNames, hookBase: { run_id: runId ?? null, step: stepIndex ?? null, agent: step.agent, workspace: path.basename(workspaceRootOf(agentDir)) } }
+      : {};
+    if (stepHookNames.length) push("info", `hooks: ${stepHookNames.join(", ")}`);
 
     const isolation = process.env.FOLDRUN_RUN_ISOLATION;
     if (isolatedRun()) {
@@ -2521,6 +2534,7 @@ async function runStep(
           schema: resolvedSchema ?? undefined,
           maxTurns: step.maxTurns,
           ...limitOpts,
+          ...hookOpts,
           translator: keyName === MODEL_KEY_NAME ? primaryTranslator : secondTranslator,
           // Outward steps keep a browser of their own: an executor that
           // could browse from the slim image through the account's pod
@@ -2885,6 +2899,7 @@ async function runStep(
         schema: resolvedSchema ?? undefined,
         maxTurns: step.maxTurns,
         ...limitOpts,
+        ...hookOpts,
         stopRequested,
         // What the scripts saw, the verify sees: a flow can then check that
         // the proof a step left names THIS run, not one that came before —

package/src/starter.ts

@@ -279,6 +279,7 @@ only when they asked for exactly that deletion.
 | \`memory/\` | what past runs learned — agents write here themselves |
 | \`evals/\` | tests for agents, same idea as unit tests |
 | \`skills/\` | a procedure an agent can follow, named in \`skills:\` |
+| \`hooks/\` | your code at every tool call, step start or step end (\`hook.md\` + \`run.mjs\`), turned on with \`hooks:\` — refuse, rewrite, add context; same on every model |
 | \`tools/\` | a folder tool: its definition and its code together |
 | \`scripts/\` | code the agents call, referenced by \`scripts:\` |
 | \`state/\` | what runs accumulate. Yours to read, never deployed over |
@@ -455,6 +456,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/src/step-exec.ts

@@ -8,6 +8,7 @@
 // results. That is what lets the same function run somewhere the vault, the
 // library and the account do not exist.
 
+import { runHook, runToolCallHooks, matchesTool, hookLine, resolveHooks, type HookDef, type HookRecord } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -57,6 +58,14 @@ export interface ExecOutcome {
 }
 
 export interface ExecOptions {
+  /** `hooks:` resolved host-side (hooks.ts): run at this step's own dispatch,
+   *  inside its sandbox. `hookBase` is what every hook event carries. */
+  hooks?: HookDef[];
+  /** Or the names (`hooks:` from the account, workspace and agent), resolved
+   *  here against this step's own roots — in a sandbox those are not the
+   *  host's paths. A name that resolves to nothing refuses the step. */
+  hookNames?: string[];
+  hookBase?: Record<string, unknown>;
   agentDir: string;
   workspaceRoot: string;
   libraryRoot: string;
@@ -158,7 +167,7 @@ export type QueryLike = AsyncIterable<unknown> & { interrupt(): Promise<unknown>
 export type QueryFn = (args: { prompt: string; options: Record<string, unknown> }) => QueryLike;
 
 /** The pairing fields on a tool event — see RunEvent in store.ts. */
-export type EventExtra = { call?: string; ms?: number; err?: boolean; effect?: TestEffect; operator?: OperatorEvent; subagent?: string; check?: boolean };
+export type EventExtra = { call?: string; ms?: number; err?: boolean; effect?: TestEffect; operator?: OperatorEvent; subagent?: string; check?: boolean; hook?: HookRecord };
 
 /** The tag on every event a failed check writes — `verify:`, `output: json`,
  *  a schema — headline and detail alike. The runner's no-retry rule for
@@ -310,8 +319,51 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
   // fan-out instance each start from zero.
   const counter = new CallCounter(opts.limits);
 
+  // Hooks (hooks.ts): the person's own code at this dispatch, same on every
+  // model. Each runs in the agent's directory with a bare environment.
+  let hooks = opts.hooks ?? [];
+  if (opts.hookNames?.length) {
+    const r = resolveHooks({ workspaceRoot, libraryRoot, names: opts.hookNames });
+    const bad = [...r.missing.map((n) => `no hook named ${n} in hooks/ or the library`), ...r.errors];
+    if (bad.length) {
+      emit("error", `hooks: ${bad.join("; ")} — the step is refused rather than run without its hooks`);
+      return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+    }
+    hooks = [...hooks, ...r.hooks];
+  }
+  const hookBase = { ...(opts.hookBase ?? {}) };
+  const callHook = (hook: HookDef, event: Record<string, unknown>) => runHook(hook, event, { cwd: agentDir, env: opts.env });
+  const record = (r: HookRecord, via?: string) =>
+    emit(r.did === "error" || r.did === "deny" ? "error" : "info", hookLine(r), { hook: r, ...(via ? { subagent: via } : {}) });
+
+  // step.start — a gate: context it returns goes in front of the task; a
+  // hook that fails refuses the step rather than run it unguarded.
+  let prompt = opts.prompt;
+  for (const hook of hooks.filter((h) => h.on === "step.start")) {
+    const a = await callHook(hook, { ...hookBase, event: "step.start", hook: hook.name, prompt });
+    if (!a.ok) {
+      record({ hook: hook.name, event: "step.start", did: "error", reason: `${a.failure}, so the step is refused`, ms: a.ms });
+      return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+    }
+    // Exit 2 is a deny on every event (runHook). On a gate that means the
+    // step does not run — it used to come back ok with no context, and the
+    // step went ahead as if the hook had agreed.
+    if (a.decision === "deny") {
+      record({ hook: hook.name, event: "step.start", did: "deny", reason: `${a.reason}, so the step is refused`, ms: a.ms });
+      return { status: "failed", result: null, conclusion: null, costUsd: null, usage: null };
+    }
+    if (a.context) {
+      prompt = `${prompt}\n\n${a.context}`;
+      record({ hook: hook.name, event: "step.start", did: "context", ms: a.ms });
+    } else if (a.note) {
+      record({ hook: hook.name, event: "step.start", did: "note", reason: a.note, ms: a.ms });
+    }
+  }
+  const toolHooks = hooks.filter((h) => h.on === "tool.call");
+  const resultHooks = hooks.filter((h) => h.on === "tool.result");
+
   const q = runQuery({
-    prompt: opts.prompt,
+    prompt,
     options: {
       cwd: agentDir,
       abortController: abort,
@@ -411,6 +463,44 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
                 return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: refusal.message } };
               }
             }
+            // tool.call hooks — after foldrun's own checks, so a hook never
+            // sees a call that was going to be refused anyway, and handed the
+            // input as the tool would get it (the workspace/ prefix expanded).
+            if (toolHooks.length) {
+              const input = (verdict?.updatedInput ?? hookInput.tool_input ?? {}) as Record<string, unknown>;
+              // A sub-agent's call says so: a hook that guards the step's own
+              // model differently from its delegates can tell them apart.
+              const v = await runToolCallHooks(toolHooks, { tool: hookInput.tool_name, input, base: via ? { ...hookBase, subagent: via } : hookBase }, callHook);
+              for (const r of v.records) record(r, via);
+              const refundCall = () => { if (counter.active) counter.refund(limitKeysFor(hookInput.tool_name, hookInput.tool_input as Record<string, unknown>, opts.toolOwners)); };
+              if (v.decision === "deny") {
+                refundCall();
+                return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: v.reason! } };
+              }
+              if (v.input) {
+                // A rewritten call is answered "allow", and an allow skips
+                // canUseTool — where the shell and path confinement live. So
+                // the rewrite goes through the same checks here: a hook can
+                // narrow what the agent does, never widen it.
+                const again = hookInput.tool_name === "Bash"
+                  ? checkBash(String(v.input.command ?? ""))
+                  : isFilesystemTool(hookInput.tool_name)
+                    ? checkPaths(hookInput.tool_name, v.input, { agentDir, workspaceRoot, libraryRoot })
+                    : { ok: true as const };
+                const granted = opts.allowed.includes(hookInput.tool_name) || opts.mcpNames.some((n) => hookInput.tool_name.startsWith(`mcp__${n}__`));
+                // The sub-agent guard read the ORIGINAL input: a rewrite of a
+                // delegation could otherwise swap subagent_type for one this
+                // step never declared (or the SDK's general-purpose).
+                const delegation = guardSubagent ? guardSubagent({ agentId, agentType, tool: hookInput.tool_name, input: v.input }) : null;
+                if (!again.ok || !granted || delegation) {
+                  refundCall();
+                  const why = !granted ? `Tool ${hookInput.tool_name} is not enabled for this agent.` : delegation ? `the rewritten call: ${delegation}` : `the rewritten call: ${again.reason}`;
+                  emit("error", why, via ? { subagent: via } : undefined);
+                  return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: why } };
+                }
+                return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "allow" as const, updatedInput: again.updatedInput ?? v.input } };
+              }
+            }
             if (!verdict?.updatedInput) return {};
             return { hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "allow" as const, updatedInput: verdict.updatedInput } };
           }],
@@ -419,11 +509,21 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
         // after its next tool call, as context — never as a change to what it
         // may do. A model that is only writing, calling no tools, hears it at
         // the next call it makes.
-        ...(opts.inbox
+        ...(opts.inbox || resultHooks.length
           ? {
               PostToolUse: [{
                 hooks: [async (hookInput: HookInput) => {
                   if (hookInput.hook_event_name !== "PostToolUse") return {};
+                  // tool.result hooks watch: the call has happened, so one
+                  // that fails is recorded and the step goes on.
+                  for (const hook of resultHooks) {
+                    if (!matchesTool(hook.tool, hookInput.tool_name)) continue;
+                    const response = (hookInput as { tool_response?: unknown }).tool_response;
+                    const a = await callHook(hook, { ...hookBase, event: "tool.result", hook: hook.name, tool: { name: hookInput.tool_name, input: hookInput.tool_input ?? {} }, result: response ?? null });
+                    if (!a.ok) record({ hook: hook.name, event: "tool.result", did: "error", tool: hookInput.tool_name, reason: a.failure, ms: a.ms });
+                    else if (a.note) record({ hook: hook.name, event: "tool.result", did: "note", tool: hookInput.tool_name, reason: a.note, ms: a.ms });
+                  }
+                  if (!opts.inbox) return {};
                   // A sub-agent's call: the message is for the step's own
                   // model, and draining it here would hand it to a context
                   // that ends with the delegation — and lose it.
@@ -730,6 +830,18 @@ async function executeStepInner(opts: ExecOptions, runQuery: QueryFn): Promise<E
       "the model stream ended without a result — the model process likely died (out of memory?)",
     );
   }
+  // step.end hooks watch the reply, and may rewrite it. One that fails is
+  // recorded and the reply stands: the work it describes is done.
+  if (status === "completed") {
+    for (const hook of hooks.filter((h) => h.on === "step.end")) {
+      const a = await callHook(hook, { ...hookBase, event: "step.end", hook: hook.name, reply: texts.join("\n").trim() });
+      if (!a.ok) record({ hook: hook.name, event: "step.end", did: "error", reason: a.failure, ms: a.ms });
+      else if (a.reply !== undefined) {
+        texts.splice(0, texts.length, a.reply);
+        record({ hook: hook.name, event: "step.end", did: "reply", ms: a.ms });
+      } else if (a.note) record({ hook: hook.name, event: "step.end", did: "note", reason: a.note, ms: a.ms });
+    }
+  }
   const result = texts.join("\n").trim() || null;
   // A step's reply is not one message: the model narrates ("Now let me read
   // the outputs…"), calls tools, and answers last. Joining those and reading

package/src/store.ts

@@ -84,6 +84,7 @@ export const WORKSPACE_DIRS = [
   "knowledge",
   "tools",
   "scripts",
+  "hooks",
   "state",
 ] as const;
 
@@ -3024,6 +3025,9 @@ 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]). */