foldrun 0.9.0 → 1.0.0

package/src/commands.mjs

@@ -1,6 +1,7 @@
 // CLI commands. Kept separate from bin/ so the environment is set before the
 // core is imported — single-workspace mode is read at module load.
 
+import { writeExact } from "./terminal.mjs";
 import dns from "node:dns";
 import fs from "node:fs";
 import crypto from "node:crypto";
@@ -710,8 +711,10 @@ async function platformLibrary(flags) {
     return new Set((body.entries ?? []).map((e) => e.name).filter(Boolean));
   };
   try {
-    const [tools, skills] = await Promise.all([names("tools"), names("skills")]);
-    return { url, tools, skills, warning: null };
+    // Hooks are newer than the library route on some platforms: a platform
+    // that does not list them leaves the set empty rather than failing check.
+    const [tools, skills, hooks] = await Promise.all([names("tools"), names("skills"), names("hooks").catch(() => new Set())]);
+    return { url, tools, skills, hooks, warning: null };
   } catch (err) {
     return { url, tools: new Set(), skills: new Set(), warning: `could not read the library on ${url} (${err instanceof Error ? err.message : err}) — tools defined there will be reported missing` };
   }
@@ -772,6 +775,11 @@ async function checkAccount(layout, flags) {
   const problems = [];
   const note = (level, where, message) => problems.push({ level, where, message });
   validateSkills(path.join(layout.accountRoot, "library"), note);
+  const hc = await hooksCore();
+  for (const p of hc ? hc.checkHooksDir(path.join(layout.accountRoot, "library", "hooks"), "account") : []) {
+    const m = /^(hooks\/[^/:]+(?:\/hook\.md)?): (.*)$/s.exec(p);
+    note("error", m ? m[1] : "hooks/", m ? m[2] : p);
+  }
   const counts = LIBRARY_KINDS.map((k) => ({ kind: k, n: files.filter((f) => f.kind === k).length })).filter((x) => x.n > 0);
   console.log(`\n  ${c.bold("library")}  ${c.dim(counts.length ? counts.map((x) => `${x.n} ${x.kind}`).join(" · ") : "empty")}`);
   for (const p of problems) {
@@ -1053,6 +1061,8 @@ async function checkProblems(workspace, flags = {}) {
     }
   }
 
+  await checkHooks(workspace, agents, libraryDir(T), platform, note);
+
   // A script tool whose `run:` resolves to nothing parses, counts, and is
   // offered to the agent — then fails inside a turn. Checking it here is the
   // difference between a typo found in CI and a flow that quietly stops
@@ -1162,6 +1172,68 @@ async function checkProblems(workspace, flags = {}) {
   return { problems, summary };
 }
 
+/**
+ * Hooks, checked with core's own reader so check and a run agree: a hook
+ * folder that is not a hook, a `hooks:` name that resolves to nothing (a run
+ * refuses that step rather than run it unguarded), and a tool.call hook on an
+ * agent whose web search or fetch the model provider runs on its own servers
+ * — those calls never pass foldrun's dispatch, so the hook never sees them.
+ * A core from before hooks has no reader, and then there is nothing to say.
+ */
+async function checkHooks(workspace, agents, libraryRoot, platform, note) {
+  const h = await hooksCore();
+  if (!h) return;
+  for (const p of h.checkHooksDir(path.join(workspace, "hooks"), "workspace")) {
+    const m = /^(hooks\/[^/:]+(?:\/hook\.md)?): (.*)$/s.exec(p);
+    note("error", m ? m[1] : "hooks/", m ? m[2] : p);
+  }
+  const matter = (await import("gray-matter")).default;
+  const front = (file) => {
+    try {
+      return fs.existsSync(file) ? matter(fs.readFileSync(file, "utf8")).data ?? {} : {};
+    } catch {
+      return {}; // an unreadable file is reported by its own check
+    }
+  };
+  const exists = (n) =>
+    fs.existsSync(path.join(workspace, "hooks", n)) || fs.existsSync(path.join(libraryRoot, "hooks", n)) || platform.hooks?.has(n);
+  const missing = (where, names) => {
+    for (const n of names) {
+      if (!exists(n)) note("error", where, `hooks: [${n}] — no hooks/${n}/hook.md in this workspace or the account library`);
+    }
+  };
+  const accountNames = h.hookNames(front(path.join(path.dirname(libraryRoot), "AGENTS.md")).hooks);
+  const workspaceNames = h.hookNames(front(path.join(workspace, "AGENTS.md")).hooks);
+  missing("account AGENTS.md", accountNames);
+  missing("AGENTS.md", workspaceNames);
+
+  let resolveSearch = null;
+  try {
+    ({ resolveSearch } = /** @type {any} */ (await import("@foldrun/core/providers")));
+  } catch {
+    // no provider table: the provider-side search warning is skipped
+  }
+  for (const a of agents) {
+    const f = front(path.join(workspace, "agents", a.name, "agent.md"));
+    const own = h.hookNames(f.hooks);
+    missing(`agents/${a.name}`, own);
+    if (!resolveSearch || !f.web || typeof f.web !== "object" || Array.isArray(f.web)) continue;
+    const { hooks } = h.resolveHooks({ workspaceRoot: workspace, libraryRoot, names: [...accountNames, ...workspaceNames, ...own] });
+    const gates = hooks.filter((x) => x.on === "tool.call").map((x) => x.name);
+    if (!gates.length) continue;
+    for (const action of ["search", "fetch"]) {
+      if (f.web[action] === undefined) continue;
+      const r = resolveSearch(f.web[action], action);
+      if (!r?.provider || r.error || r.shape === "direct") continue;
+      note(
+        "warn",
+        `agents/${a.name}`,
+        `web.${action}: ${r.provider} runs on the model provider's servers, so tool.call hook${gates.length === 1 ? "" : "s"} ${gates.join(", ")} never see${gates.length === 1 ? "s" : ""} those calls — leave web.${action}: unset (or name a ${action} API) for foldrun's own dispatch, which hooks guard`,
+      );
+    }
+  }
+}
+
 /** The web tool the platform's gallery serves: built in, and the only
  *  built-in that takes a provider. */
 const WEB_TOOL = "web";
@@ -1907,7 +1979,47 @@ export function semverNewer(a, b) {
   for (let i = 0; i < 3; i++) if (x.n[i] !== y.n[i]) return x.n[i] > y.n[i];
   if (x.pre && !y.pre) return false;
   if (!x.pre && y.pre) return true;
-  return (x.pre ?? "") > (y.pre ?? "");
+  if (!x.pre) return false;
+  // SemVer 2.0.0 §11: dot-separated identifiers compared one by one — numbers
+  // as numbers (rc.10 > rc.9), a number before a word, and a shorter list
+  // before a longer one it begins.
+  const xs = x.pre.slice(1).split(".");
+  const ys = y.pre.slice(1).split(".");
+  for (let i = 0; i < Math.max(xs.length, ys.length); i++) {
+    if (xs[i] == null || ys[i] == null) return ys[i] == null;
+    const xn = /^\d+$/.test(xs[i]);
+    const yn = /^\d+$/.test(ys[i]);
+    if (xn && yn) {
+      if (Number(xs[i]) !== Number(ys[i])) return Number(xs[i]) > Number(ys[i]);
+    } else if (xn !== yn) return yn;
+    else if (xs[i] !== ys[i]) return xs[i] > ys[i];
+  }
+  return false;
+}
+
+/**
+ * Is `latest` an update worth telling someone running `current` about? Newer,
+ * and not a pre-release offered to someone on a stable release: npm keeps
+ * pre-releases off `latest`, so `npm i -g foldrun@latest` would not even
+ * install it.
+ * @param {string} latest @param {string} current
+ */
+export function updateTo(latest, current) {
+  // The whole header must be a version: it is printed, and a platform that
+  // could append to it could write to the terminal.
+  if (!/^v?\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(String(latest ?? "").trim())) return false;
+  const pre = (v) => /^v?\d+\.\d+\.\d+-/.test(String(v ?? "").trim());
+  return semverNewer(latest, current) && !(pre(latest) && !pre(current));
+}
+
+/**
+ * Text from a platform, made safe to print: no escape sequences or other
+ * control characters, so a hostile or broken server cannot move the cursor,
+ * retitle the terminal, write the clipboard (OSC 52) or disguise a link.
+ * @param {unknown} s
+ */
+export function printable(s) {
+  return String(s ?? "").replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
 }
 
 const UPDATE_EVERY_MS = 24 * 60 * 60 * 1000;
@@ -1927,14 +2039,14 @@ function updateNotice(res) {
     if (env("FOLDRUN_NO_UPDATE_NOTICE")) return;
     if (!(process.stderr.isTTY || env("FOLDRUN_FORCE_TTY") === "1")) return;
     const latest = res.headers.get("x-foldrun-cli");
-    if (!latest || !semverNewer(latest, CLI_VERSION)) return;
+    if (!latest || !updateTo(latest, CLI_VERSION)) return;
     noticeDone = true;
     const file = path.join(credentialsDir(), "version-check.json");
     try {
       const last = JSON.parse(fs.readFileSync(file, "utf8"));
       if (Date.now() - Date.parse(last.notifiedAt) < UPDATE_EVERY_MS) return;
     } catch {}
-    const platform = res.headers.get("x-foldrun-version");
+    const platform = printable(res.headers.get("x-foldrun-version") ?? "") || null;
     console.error(`  ${c.dim(`foldrun ${latest} is out (this is ${CLI_VERSION})${platform ? `, released with platform ${platform}` : ""} — npm i -g foldrun@latest`)}`);
     fs.mkdirSync(credentialsDir(), { recursive: true });
     fs.writeFileSync(file, JSON.stringify({ notifiedAt: new Date().toISOString(), cli: latest, platform }) + "\n");
@@ -1968,7 +2080,7 @@ async function versionCmd(flags) {
     }
   }
   const latestCli = platform?.packages?.cli ?? null;
-  const behind = latestCli ? semverNewer(latestCli, CLI_VERSION) : false;
+  const behind = latestCli ? updateTo(latestCli, CLI_VERSION) : false;
   if (flags.json === true) {
     console.log(JSON.stringify({ cli: CLI_VERSION, core, platform: platform ?? (url ? { url, error: unreachable } : null) }, null, 2));
     if (behind) console.error(`foldrun ${latestCli} is out (this is ${CLI_VERSION}) — npm i -g foldrun@latest`);
@@ -3625,7 +3737,7 @@ async function auditCmd(positional, flags) {
     q.set("format", "csv");
     const { bytes, name } = await remoteBytes(url, flags, `/api/audit?${q}`, "the audit log");
     if (typeof flags.file !== "string") {
-      process.stdout.write(bytes);
+      writeExact(bytes);
       return 0;
     }
     return writeDownload(bytes, name ?? "audit.csv", flags, "the audit log");
@@ -3701,7 +3813,7 @@ async function sourceCmd(positional, flags) {
   if (verb === "cat" || verb === "read" || verb === "get") {
     if (!a) throw new Error("which file? foldrun source cat flows/daily.md --to <workspace>");
     const { content } = await remoteCall(url, flags, `${base}?path=${encodeURIComponent(a)}`);
-    process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+    writeExact(content.endsWith("\n") ? content : `${content}\n`);
     return 0;
   }
   if (verb === "put" || verb === "write") {
@@ -4706,7 +4818,7 @@ async function storageCmd(positional, flags, layout) {
     if (bytes.includes(0)) {
       throw new Error(`${rel} is not text (${humanBytes(bytes.length)}) — \`foldrun storage cat ${rel} --preview\` reads what is in it, \`foldrun storage get ${rel}\` writes it to a file`);
     }
-    process.stdout.write(bytes.toString("utf8"));
+    writeExact(bytes);
     return 0;
   }
 
@@ -6122,6 +6234,308 @@ async function checkRemote(flags, layout) {
   }
 }
 
+// ---------------------------------------------------------------- hooks
+
+/**
+ * Core's hooks module — readHookDef, runHook, the event list — or null on a
+ * core from before hooks, where `check` then says nothing about them and the
+ * `hook` verbs say which core they need.
+ */
+async function hooksCore() {
+  try {
+    return /** @type {any} */ (await import("@foldrun/core/hooks"));
+  } catch {
+    return null;
+  }
+}
+async function needHooksCore() {
+  const h = await hooksCore();
+  if (!h) throw new Error("this CLI's @foldrun/core has no hooks — update it (npm i -g foldrun@latest)");
+  return h;
+}
+
+/** The account library a hook verb works on: the folder beside workspaces/. */
+const libraryRootOf = (layout) => path.join(layout.accountRoot, "library");
+
+/** What a new run.mjs answers, per event: a gate allows, a watcher notes nothing. */
+const HOOK_ANSWER = {
+  "tool.call": `{ decision: "allow" }`,
+  "tool.result": `{}`,
+  "step.start": `{}`,
+  "step.end": `{}`,
+};
+
+/** A sample event per kind, for `hook test` with no --event. */
+const HOOK_SAMPLE = {
+  "tool.call": { tool: { name: "Bash", input: { command: "ls" } } },
+  "tool.result": { tool: { name: "Bash", input: { command: "ls" }, result: "agent.md\n" } },
+  "step.start": { prompt: "Find three sources." },
+  "step.end": { reply: "Done." },
+};
+
+function hookRunTemplate(name, on) {
+  return `// ${name} — a foldrun hook (on: ${on}). Self-contained: Node's built-ins only,
+// no relative imports — it runs from a copy taken when the step starts.
+//
+// In:  one JSON object on stdin — the event:
+//        { event, hook, run_id, step, agent, workspace,
+//          tool: { name, input }        (tool.call, tool.result; + result on tool.result)
+//          prompt                       (step.start)
+//          reply                        (step.end) }
+// Out: one JSON object on stdout, the last line printed:
+//        tool.call    { decision: "allow" | "deny", reason, input, note }
+//                     input replaces the tool's whole input; a deny needs a reason
+//        step.start   { context, note }   context is added to the step's prompt
+//        step.end     { reply, note }     reply replaces the step's reply
+//        tool.result  { note }            a line on the run's trail
+// Exit 0 with an answer. Exit 2 denies, with stderr as the reason.
+// Anything else is a failure: a gate (tool.call, step.start) that fails
+// refuses; a watcher (tool.result, step.end) that fails is recorded.
+// No secrets and no model key reach this process.
+
+let raw = "";
+for await (const chunk of process.stdin) raw += chunk;
+const event = JSON.parse(raw || "{}");
+
+// Decide here. This one allows everything.
+void event;
+console.log(JSON.stringify(${HOOK_ANSWER[on]}));
+`;
+}
+
+/** `foldrun hook <ls|add|test|rm>` — hooks in this workspace and the library. */
+async function hookCmd(positional, flags, layout) {
+  const [verb = "ls"] = positional;
+  if (verb === "ls" || verb === "list") return hookLsCmd(flags, layout);
+  if (verb === "add" || verb === "new") return hookAddCmd(positional, flags, layout);
+  if (verb === "test") return hookTestCmd(positional, flags, layout);
+  if (verb === "rm") return hookRmCmd(positional, flags, layout);
+  throw new Error(`unknown hook verb "${verb}" — ls, add <name> --on <event>, test <name>, rm <name>`);
+}
+
+/** Every hook folder here, the workspace's first, each read the way a run reads it. */
+async function hooksHere(flags, layout) {
+  const h = await needHooksCore();
+  const ws = workspaceDirFor(flags, layout);
+  const out = [];
+  const seen = new Set();
+  for (const [root, scope] of [[ws, "workspace"], [libraryRootOf(layout), "account"]]) {
+    for (const dir of h.listHookDirs(path.join(root, "hooks"))) {
+      const name = path.basename(dir);
+      const def = h.readHookDef(dir, scope);
+      const row = "error" in def
+        ? { name, scope, error: def.error }
+        : { name, scope, on: def.on, tool: def.tool ?? null, timeout: def.timeoutSec, description: def.description ?? null };
+      // A workspace hook of the same name is the one a run resolves.
+      out.push({ ...row, ...(seen.has(name) ? { shadowed: true } : {}) });
+      seen.add(name);
+    }
+  }
+  return { h, ws, hooks: out };
+}
+
+/** `hook ls --to <ws>`: the DEPLOYED workspace's hooks and what they did
+ *  lately — GET /api/workspaces/<ws>/hooks, the dashboard's Hooks panel. */
+async function hookLsRemote(flags) {
+  const url = platformFor(flags, "hook ls");
+  const ws = String(flags.to);
+  const q = new URLSearchParams();
+  if (flags.all === true) q.set("all", "1");
+  if (flags.runs !== undefined) q.set("runs", String(flags.runs));
+  const r = /** @type {{ hooks: any[], recent: any[] }} */ (await remoteCall(url, flags, `/api/workspaces/${encodeURIComponent(ws)}/hooks${q.size ? `?${q}` : ""}`));
+  if (flags.json === true) {
+    console.log(JSON.stringify(r, null, 2));
+    return 0;
+  }
+  const hooks = r.hooks ?? [];
+  if (!hooks.length) console.log(`\n  ${c.dim(`no hooks in ${ws} or the account library`)}`);
+  else {
+    console.log();
+    const w = Math.max(...hooks.map((x) => x.name.length));
+    for (const x of hooks) {
+      const where = x.scope === "account" ? "library" : "workspace";
+      if (x.error) {
+        console.log(`  ${c.red("✗")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${x.error}`);
+        continue;
+      }
+      const on = (x.onFor ?? []).length ? `on for ${x.onFor.join(", ")}` : "turned on by nobody";
+      const note = x.shadowed ? "(the workspace's own of this name is the one that runs)" : `${on}${x.description ? ` — ${x.description}` : ""}`;
+      console.log(`  ${c.green("✓")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${String(x.on).padEnd(11)}  ${String(x.tool ?? "*").padEnd(12)}  ${c.dim(note)}`);
+    }
+  }
+  const recent = r.recent ?? [];
+  console.log(`\n  ${c.bold("lately")}  ${c.dim(recent.length ? `${recent.length} ${flags.all === true ? "hook decision" : "deny, rewrite or failure"}${recent.length === 1 ? "" : "s"}, newest first` : flags.all === true ? "no hook ran" : "nothing denied, rewritten or failed (--all for every decision)")}`);
+  for (const e of recent.slice(0, 20)) {
+    const rec = e.record ?? {};
+    console.log(`  ${c.dim(String(e.t).slice(0, 16).replace("T", " "))}  ${rec.hook} ${rec.did} ${rec.event}${rec.tool ? ` ${rec.tool}` : ""}  ${c.dim(`${e.runId} step ${e.step} ${e.agent}`)}${rec.reason ? ` — ${firstLine(rec.reason, 80)}` : ""}`);
+  }
+  console.log(`\n  ${c.dim("--runs <n> reads further back (default 50) · --all for every decision · --json")}\n`);
+  return hooks.some((x) => x.error) ? 1 : 0;
+}
+
+async function hookLsCmd(flags, layout) {
+  if (typeof flags.to === "string") return hookLsRemote(flags);
+  const { hooks } = await hooksHere(flags, layout);
+  if (flags.json === true) {
+    console.log(JSON.stringify(hooks, null, 2));
+    return 0;
+  }
+  if (!hooks.length) {
+    console.log(`\n  ${c.dim("no hooks — `foldrun hook add <name> --on tool.call` makes one")}\n`);
+    return 0;
+  }
+  console.log();
+  const w = Math.max(...hooks.map((x) => x.name.length));
+  for (const x of hooks) {
+    const where = x.scope === "account" ? "library" : "workspace";
+    if (x.error) {
+      console.log(`  ${c.red("✗")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${x.error}`);
+      continue;
+    }
+    const what = `${x.on.padEnd(11)}  ${(x.tool ?? "*").padEnd(12)}`;
+    const note = x.shadowed ? c.dim("(the workspace's own of this name is the one that runs)") : c.dim(x.description ?? "");
+    console.log(`  ${c.green("✓")} ${c.bold(x.name.padEnd(w))}  ${c.dim(where.padEnd(9))}  ${what}  ${note}`);
+  }
+  console.log(`\n  ${c.dim("an agent turns one on with hooks: [name]; AGENTS.md hooks: turns it on for every agent under it")}\n`);
+  return hooks.some((x) => x.error) ? 1 : 0;
+}
+
+async function hookAddCmd(positional, flags, layout) {
+  const h = await needHooksCore();
+  const name = positional[1];
+  if (!name) throw new Error("which hook? `foldrun hook add <name> --on tool.call|tool.result|step.start|step.end`");
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
+    throw new Error(`"${name}" is not a hook name — lowercase letters, digits and dashes, e.g. no-rm-rf`);
+  }
+  const on = flags.on;
+  if (typeof on !== "string" || !h.HOOK_EVENTS.includes(on)) {
+    throw new Error(`--on takes ${h.HOOK_EVENTS.join(", ")}${typeof on === "string" ? ` — not "${on}"` : ""}`);
+  }
+  const tool = typeof flags.tool === "string" ? flags.tool.trim() : undefined;
+  if (flags.tool !== undefined && !tool) throw new Error("--tool takes a tool name or pattern, like Bash, Write|Edit or mcp__*");
+  if (tool && on !== "tool.call" && on !== "tool.result") {
+    throw new Error(`--tool only means something on tool.call and tool.result, not ${on}`);
+  }
+  const root = flags.library === true ? libraryRootOf(layout) : workspaceDirFor(flags, layout);
+  const rel = `hooks/${name}`;
+  const front = [
+    "---",
+    `on: ${on}`,
+    ...(tool ? [`tool: ${/[|*:]/.test(tool) ? JSON.stringify(tool) : tool}`] : []),
+    `description: What ${name} checks, in one line.`,
+    "---",
+    "",
+    `What ${name} is for, and what it refuses or rewrites. The code is run.mjs beside this file.`,
+    "",
+  ].join("\n");
+  writeFiles(root, [
+    { path: `${rel}/hook.md`, content: front },
+    { path: `${rel}/run.mjs`, content: hookRunTemplate(name, on) },
+  ], flags.library === true ? "the library" : path.basename(root));
+  const where = path.relative(process.cwd(), path.join(root, rel)) || rel;
+  console.log(`\n  ${c.green("created")} hook ${c.bold(name)} ${c.dim(`(${on}${tool ? ` · ${tool}` : ""})`)} in ${where}\n`);
+  console.log(`    ${c.dim(`${rel}/hook.md`)}\n    ${c.dim(`${rel}/run.mjs`)}`);
+  console.log(`\n  ${c.bold("Next")}
+    edit ${path.join(where, "run.mjs")}
+    hooks: [${name}]${" ".repeat(4)}${c.dim("in an agent's frontmatter — or in AGENTS.md for every agent")}
+    foldrun hook test ${name}${" ".repeat(4)}${c.dim("run it on a sample event, here")}\n`);
+  return 0;
+}
+
+/** --event: inline JSON, or @file. */
+function readHookEvent(raw, on) {
+  if (raw === undefined) return { event: HOOK_SAMPLE[on] ?? {}, sample: true };
+  if (typeof raw !== "string") throw new Error("--event takes a JSON object, or @file");
+  const text = raw.startsWith("@") ? fs.readFileSync(raw.slice(1), "utf8") : raw;
+  let event;
+  try { event = JSON.parse(text); } catch (err) {
+    throw new Error(`--event is not JSON (${err instanceof Error ? err.message : err})`);
+  }
+  if (!event || typeof event !== "object" || Array.isArray(event)) throw new Error("--event is one JSON object — the event the hook reads on stdin");
+  return { event, sample: false };
+}
+
+function printHookAnswer(name, on, a, where) {
+  const mark = !a.ok ? c.red("✗") : a.decision === "deny" ? c.amber("■") : c.green("✓");
+  console.log(`\n  ${mark} ${c.bold(name)}  ${c.dim(`${on ?? "?"} · ${where} · ${a.ms ?? 0}ms`)}`);
+  if (!a.ok) console.log(`  ${c.red("failed")}  ${a.failure ?? "no reason given"}${on === "tool.call" || on === "step.start" ? c.dim(" — a gate that fails refuses") : ""}`);
+  if (a.decision) console.log(`  ${pad("decision", 9)} ${a.decision === "deny" ? c.amber("deny") : "allow"}`);
+  if (a.reason) console.log(`  ${pad("reason", 9)} ${a.reason}`);
+  if (a.input) console.log(`  ${pad("input", 9)} ${JSON.stringify(a.input)}`);
+  if (a.context) console.log(`  ${pad("context", 9)} ${a.context}`);
+  if (a.reply !== undefined) console.log(`  ${pad("reply", 9)} ${a.reply}`);
+  if (a.note) console.log(`  ${pad("note", 9)} ${a.note}`);
+  console.log();
+  return a.ok ? 0 : 1;
+}
+
+/**
+ * `foldrun hook test <name> [--event '<json>']` — run one hook on one event,
+ * here, the way a step runs it (core's runHook: the event on stdin, a
+ * stripped environment, its timeout). `--to <workspace>` asks the platform
+ * to run the deployed one instead.
+ */
+async function hookTestCmd(positional, flags, layout) {
+  const name = positional[1];
+  if (!name) throw new Error("which hook? `foldrun hook test <name> --event '<json>'` — `foldrun hook ls` lists them");
+  if (typeof flags.to === "string") {
+    const url = platformFor(flags, "hook test");
+    const ws = flags.to;
+    let event = {};
+    if (flags.event !== undefined) event = readHookEvent(flags.event, "tool.call").event;
+    const r = /** @type {any} */ (await remoteCall(
+      url,
+      flags,
+      `/api/workspaces/${enc(ws)}/hooks/${enc(name)}/test`,
+      { method: "POST", body: JSON.stringify({ event }) },
+    ));
+    const a = r?.answer ?? r ?? {};
+    return printHookAnswer(name, r?.on ?? a.on, { ok: a.ok !== false, ...a }, ws);
+  }
+  const h = await needHooksCore();
+  const ws = workspaceDirFor({ ...flags, to: undefined }, layout);
+  const r = h.resolveHooks({ workspaceRoot: ws, libraryRoot: libraryRootOf(layout), names: [name] });
+  if (r.missing.length) throw new Error(`no hook named ${name} in hooks/ or the library — \`foldrun hook ls\` lists them`);
+  if (r.errors.length) throw new Error(r.errors[0]);
+  const def = r.hooks[0];
+  const { event, sample } = readHookEvent(flags.event, def.on);
+  if (sample) console.log(`\n  ${c.dim(`no --event, so a sample ${def.on} event: ${JSON.stringify(event)}`)}`);
+  const full = { event: def.on, hook: def.name, run_id: null, step: null, agent: null, workspace: path.basename(ws), ...event };
+  const a = await h.runHook(def, full, { cwd: ws, env: process.env });
+  return printHookAnswer(name, def.on, a, def.scope === "account" ? "library" : path.basename(ws));
+}
+
+async function hookRmCmd(positional, flags, layout) {
+  const h = await needHooksCore();
+  const name = positional[1];
+  if (!name) throw new Error("which hook? `foldrun hook rm <name>` (--library for the account's)");
+  const root = flags.library === true ? libraryRootOf(layout) : workspaceDirFor(flags, layout);
+  const dir = path.join(root, "hooks", name);
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name) || !fs.existsSync(dir)) {
+    throw new Error(`no hooks/${name} in ${flags.library === true ? "the library" : path.basename(root)} — \`foldrun hook ls\` lists them`);
+  }
+  // Who still turns it on: they fail check, and their steps are refused.
+  const users = [];
+  const wsRoots = flags.library === true
+    ? (layout.workspacesDir ? layout.workspaces.map((w) => path.join(layout.workspacesDir, w)) : [layout.workspaceDir].filter(Boolean))
+    : [root];
+  const matter = (await import("gray-matter")).default;
+  const names = (file) => {
+    try { return h.hookNames(matter(fs.readFileSync(file, "utf8")).data?.hooks); } catch { return []; }
+  };
+  for (const w of wsRoots) {
+    if (names(path.join(w, "AGENTS.md")).includes(name)) users.push(`${path.basename(w)}/AGENTS.md`);
+    for (const a of ls(path.join(w, "agents"))) {
+      if (names(path.join(w, "agents", a, "agent.md")).includes(name)) users.push(`${path.basename(w)}/agents/${a}`);
+    }
+  }
+  const still = users.length ? ` — still turned on by ${users.join(", ")}, whose steps will be refused until it goes from their hooks:` : "";
+  if (!(await sureToDelete(flags, "hook rm", `${flags.library === true ? "library/" : ""}hooks/${name}${still}`))) return 1;
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log(`\n  ${c.green("✓")} removed hooks/${name}${users.length ? c.dim(` — take it out of: ${users.join(", ")}`) : ""}\n`);
+  return 0;
+}
+
 // ------------------------------------------- flows and teams, as the canvas edits them
 //
 // The dashboard's flow canvas turns every palette block into a small, exact
@@ -7138,7 +7552,7 @@ async function runRmCmd(runId, flags, layout) {
 /** Where downloaded bytes go: --file (or - for stdout), else a default name. Refuses to clobber. */
 function writeDownload(bytes, fallback, flags, from) {
   if (flags.file === "-") {
-    process.stdout.write(bytes);
+    writeExact(bytes);
     return 0;
   }
   const to = typeof flags.file === "string" ? flags.file : fallback;
@@ -7174,7 +7588,7 @@ async function apiCmd(positional, flags) {
   const out = typeof flags.out === "string" ? flags.out : typeof flags.file === "string" ? flags.file : "-";
   const pretty = JSON.stringify(doc, null, 2) + "\n";
   if (out === "-") {
-    process.stdout.write(pretty);
+    writeExact(pretty);
     return 0;
   }
   fs.writeFileSync(out, pretty);
@@ -7461,7 +7875,7 @@ async function billingVerbCmd(positional, flags) {
     if (flags.csv === true) {
       const { bytes, name } = await remoteBytes(url, flags, `/api/billing/statement?month=${month}&format=csv`, `statement ${month}`);
       if (typeof flags.file !== "string") {
-        process.stdout.write(bytes);
+        writeExact(bytes);
         return 0;
       }
       return writeDownload(bytes, name ?? `foldrun-${month}.csv`, flags, `the ${month} statement`);
@@ -8495,7 +8909,7 @@ async function scheduleTickCmd(flags) {
   return 0;
 }
 
-const LIBRARY_KINDS_CLI = ["skills", "tools", "scripts", "knowledge", "memory"];
+const LIBRARY_KINDS_CLI = ["skills", "tools", "hooks", "scripts", "knowledge", "memory"];
 
 /**
  * `foldrun library [ls [kind]] | cat <kind>/<path> | put <kind>/<path> | rm
@@ -8515,9 +8929,16 @@ async function libraryCmd(positional, flags) {
   if (verb === "ls" || verb === "list") {
     const kinds = spec ? [spec] : LIBRARY_KINDS_CLI;
     for (const k of kinds) if (!LIBRARY_KINDS_CLI.includes(k)) throw new Error(`no library kind "${k}" — ${LIBRARY_KINDS_CLI.join(", ")}`);
-    const lists = await Promise.all(kinds.map((k) => remoteCall(url, flags, `/api/library/${k}`)));
+    // Listing everything, a kind an older platform does not have yet (hooks
+    // before 11 Oct 2026) is left out rather than failing the whole list;
+    // asked for by name, it fails with the platform's own answer.
+    const lists = await Promise.all(kinds.map((k) => remoteCall(url, flags, `/api/library/${k}`).catch((err) => {
+      if (spec) throw err;
+      return null;
+    })));
     console.log();
     lists.forEach((l, n) => {
+      if (!l) return;
       const entries = l.entries ?? [];
       console.log(`  ${c.bold(kinds[n])} ${c.dim(`${entries.length}`)}`);
       for (const e of entries) console.log(`    ${pad(e.name ?? e.path ?? "", 28)} ${c.dim(firstLine(e.description ?? "", 70))}`);
@@ -8528,7 +8949,7 @@ async function libraryCmd(positional, flags) {
   if (verb === "cat") {
     const { kind, rel } = split(spec);
     const { content } = await remoteCall(url, flags, `/api/library/${kind}?path=${enc(rel)}`);
-    process.stdout.write(content ?? "");
+    writeExact(content ?? "");
     return 0;
   }
   if (verb === "put") {
@@ -8797,10 +9218,29 @@ async function apiVersionCmd(positional, flags) {
   console.log(`\n  ${c.bold("API version")}  ${v.effective}  ${c.dim(v.pinned ? `pinned (current is ${v.current})` : "current — not pinned")}`);
   console.log(`  ${c.dim(`served: ${(v.supported ?? []).join(", ") || "—"} · each for ${v.supportMonths ?? "?"} months after the next · this CLI sends ${API_VERSION}`)}`);
   if (l.perCredential) console.log(`  ${c.bold("rate limits")}  ${c.dim(`${l.plan} · per key ${l.perCredential.read} reads / ${l.perCredential.write} writes, per account ${l.perAccount?.read} / ${l.perAccount?.write} — every ${l.windowSeconds}s`)}`);
+  apiUsageLines(facts.usage);
   console.log(`\n  ${c.dim("foldrun api version pin YYYY-MM-DD · unpin")}\n`);
   return 0;
 }
 
+/** The account's use of the API, last 30 days: requests by version, and any
+ *  deprecated route it still calls, by whom, and when it stops. An older
+ *  platform sends no `usage`; null means it could not be read. */
+function apiUsageLines(usage) {
+  if (usage === undefined) return;
+  if (usage === null) {
+    console.log(`  ${c.bold("your use")}  ${c.dim("could not be read just now")}`);
+    return;
+  }
+  const total = (usage.versions ?? []).reduce((s, v) => s + (v.requests ?? 0), 0);
+  const day = (iso) => String(iso ?? "").slice(0, 10);
+  console.log(`  ${c.bold("your use")}  ${c.dim(total ? `last ${usage.days} days: ` + usage.versions.map((v) => `${v.version} ${v.requests} (last ${day(v.lastSeen)})`).join(" · ") : `no API requests in the last ${usage.days} days`)}`);
+  for (const d of usage.deprecated ?? []) {
+    console.log(`  ${c.amber("deprecated")}  ${d.route} — ${d.requests} request${d.requests === 1 ? "" : "s"}, last ${day(d.lastSeen)}; ${d.sunsetAt ? `stops answering ${day(d.sunsetAt)}` : "no end date yet"}${d.link ? ` · ${d.link}` : ""}`);
+    for (const who of d.callers ?? []) console.log(`    ${c.dim(`${who.credential || "an unknown caller"}: ${who.requests}, last ${day(who.lastSeen)}`)}`);
+  }
+}
+
 const THEMES_CLI = ["system", "light", "dark"];
 
 /**
@@ -8828,7 +9268,8 @@ async function preferencesCmd(positional, flags) {
   return 0;
 }
 
-/** `foldrun changelog [--limit n]` — What's new: each release and what it changed. */
+/** `foldrun changelog [--limit n]` — What's new: the API's versions, what each
+ *  broke and what is deprecated, then each release and what it changed. */
 async function changelogCmd(flags) {
   const url = platformFor(flags, "changelog");
   const limit = Number(flags.limit) > 0 ? Math.min(50, Math.floor(Number(flags.limit))) : 5;
@@ -8837,6 +9278,7 @@ async function changelogCmd(flags) {
     console.log(JSON.stringify(r, null, 2));
     return 0;
   }
+  if (r.api) apiChangelogLines(r.api);
   const releases = r.releases ?? [];
   if (!releases.length) {
     console.log(`\n  ${c.dim(`no release notes on this install (it runs ${r.version ?? "an unreleased build"})`)}\n`);
@@ -8859,6 +9301,25 @@ async function changelogCmd(flags) {
   return 0;
 }
 
+/** The API part of What's new: the current version, the breaking changes by
+ *  version, and routes on their way out. Older platforms send no `api`. */
+function apiChangelogLines(api) {
+  const p = printable;
+  const broke = (api.versions ?? []).filter((v) => v.changes?.length);
+  const deps = api.deprecations ?? [];
+  console.log(`\n  ${c.bold(`API ${p(api.current)}`)}  ${c.dim(`each version works ${Number(api.supportMonths) || 12} months or more after the next · pin: foldrun api version pin <date>`)}`);
+  if (!broke.length && !deps.length) {
+    console.log(`    ${c.dim("nothing existing code would break on, and nothing deprecated")}`);
+    return;
+  }
+  if (broke.length) console.log(`    ${c.dim("breaking changes")}`);
+  for (const v of broke) for (const ch of v.changes) console.log(`    · ${p(v.version)}  ${firstLine(p(ch), 100)}`);
+  if (deps.length) console.log(`    ${c.dim("deprecated")}`);
+  for (const d of deps) {
+    console.log(`    · ${p(d.route)} — since ${p(d.deprecatedAt)}, ${d.sunsetAt ? `stops answering ${p(d.sunsetAt)}` : "no end date yet"}${d.link ? ` · ${p(d.link)}` : ""}`);
+  }
+}
+
 /**
  * `foldrun find <query>` — the ⌘K search: workspaces, agents, flows, tools,
  * skills, knowledge, memory and runs across the account, ranked as the
@@ -9065,7 +9526,7 @@ function printPreview(p, rel) {
     case "text":
     case "html":
     case "svg":
-      process.stdout.write(`${p.text ?? p.html ?? p.svg ?? ""}`.replace(/\n?$/, "\n"));
+      writeExact(`${p.text ?? p.html ?? p.svg ?? ""}`.replace(/\n?$/, "\n"));
       if (p.truncated) out(c.dim("… (truncated)"));
       return;
     case "table":
@@ -9335,6 +9796,9 @@ export async function run(command, positional, flags, workspace, layout) {
       return positional[0] === "test"
         ? toolTestCmd(positional, flags, layout)
         : scaffoldCmd("tools", positional, flags, layout);
+    case "hook":
+    case "hooks":
+      return hookCmd(positional, flags, layout);
     case "invoke":
       return invoke(positional[0], flags);
     case "source":