foldrun 0.9.0 → 1.1.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) {
@@ -881,6 +889,10 @@ async function checkProblems(workspace, flags = {}) {
     const { readAgentsMd } = await core();
     const { readLimits } = await import("@foldrun/core/limits");
     for (const w of readLimits(readAgentsMd(workspace)?.data?.limits).problems) note("error", "AGENTS.md", w);
+    // `network:` here is every agent's default: a value nobody can read
+    // leaves them on the account's, or the platform's.
+    const net = await import("@foldrun/core/network").catch(() => null);
+    for (const w of net ? net.networkProblems(readAgentsMd(workspace)?.data?.network) : []) note("error", "AGENTS.md", w);
   }
 
   const { unopenedFrontmatter } = /** @type {any} */ (await core());
@@ -904,6 +916,9 @@ async function checkProblems(workspace, flags = {}) {
     // written into the file. The run would say so in its trail and carry
     // on; the deploy refuses it; this is where a person hears it first.
     for (const w of a.webProblems ?? []) note("error", `agents/${a.name}`, w);
+    // A network: value that cannot be read leaves the agent on the level
+    // above it — the deploy refuses it, so check says so first.
+    for (const w of a.networkProblems ?? []) note("error", `agents/${a.name}`, w);
     // What works but should change: the old `session:` key, and a pinned
     // user_agent whose Chrome is not the runner image's (the platform's
     // /api/version says which Chrome; FOLDRUN_RUNNER_ENGINES on a server).
@@ -1053,6 +1068,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 +1179,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 +1986,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 +2046,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 +2087,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`);
@@ -2686,6 +2805,19 @@ async function readStorage(page, origin) {
     .catch(() => empty);
 }
 
+/** Bind on this machine's vault — a core from before site binding says so. */
+async function localSetSites(name, sites, scope) {
+  const k = await core();
+  if (typeof k.setSecretSites !== "function") throw new Error("binding a secret to sites needs @foldrun/core 1.1 or later — update foldrun");
+  return k.setSecretSites("default", name, sites, scope);
+}
+
+/** `--site a.com --site "*.b.org"` or `--site a.com,b.org`, as one list. */
+function siteFlags(flags) {
+  const raw = flags.site === undefined ? [] : Array.isArray(flags.site) ? flags.site : [flags.site];
+  return raw.filter((v) => typeof v === "string").flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
+}
+
 async function secretsCmd(positional, flags, layout) {
   // --local: this machine's store even when signed in, the same escape
   // hatch deploy and keys have. Without it, a signed-in laptop sent every
@@ -2716,7 +2848,7 @@ async function secretsCmd(positional, flags, layout) {
     console.log();
     for (const s of entries) {
       console.log(
-        `  ${c.bold(s.name)}  ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}`)}`,
+        `  ${c.bold(s.name)}  ${c.dim(`${s.scope}${s.shadowed ? " · shadowed" : ""} · ${s.updatedAt ?? ""}${s.sites?.length ? ` · sent only to ${s.sites.join(", ")}` : ""}`)}`,
       );
     }
     console.log();
@@ -2751,6 +2883,31 @@ async function secretsCmd(positional, flags, layout) {
 
   if (!name) throw new Error(`which secret? try \`foldrun secrets ${verb} NAME\``);
 
+  // A secret bound to sites never enters a sandbox: steps hold `${NAME}` and
+  // the egress proxy fills it in requests to those sites alone.
+  if (verb === "sites") {
+    const given = [...positional.slice(2), ...siteFlags(flags)];
+    if (!given.length && flags.clear !== true) {
+      const entries = url
+        ? (await remoteCall(url, flags, `/api/secrets${scope ? `?workspace=${encodeURIComponent(scope)}` : ""}`)).secrets
+        : (await core()).listSecrets("default", scope);
+      const hit = entries.find((s) => s.name === name);
+      if (!hit) throw new Error(`no secret ${name}${scope ? ` in workspace ${scope}` : " in the account"}`);
+      console.log(hit.sites?.length
+        ? `\n  ${c.bold(name)} is sent only to ${hit.sites.join(", ")} — on the platform it never enters a sandbox\n`
+        : `\n  ${c.bold(name)} is not bound to sites — a step with a script or Bash gets its real value. Bind it: foldrun secrets sites ${name} api.example.com\n`);
+      return 0;
+    }
+    const sites = flags.clear === true ? [] : given;
+    const stored = url
+      ? (await remoteCall(url, flags, "/api/secrets", { method: "PATCH", body: JSON.stringify({ name, sites, workspace: scope }) })).sites
+      : await localSetSites(name, sites, scope);
+    console.log(stored.length
+      ? `\n  ${c.green("✓")} ${name} is sent only to ${stored.join(", ")} — on the platform the egress proxy fills it, and it never enters a sandbox\n`
+      : `\n  ${c.green("✓")} ${name} unbound — a step with a script or Bash gets its real value again\n`);
+    return 0;
+  }
+
   if (verb === "set") {
     // --kind: the other shapes the Connections form stores — a file, an SSH
     // login, API headers, a service account's key, a client-credentials app.
@@ -2786,15 +2943,18 @@ async function secretsCmd(positional, flags, layout) {
     const value =
       typeof flags.value === "string" ? flags.value : await promptHidden(`  value for ${name}: `);
     if (!value) throw new Error("empty value — nothing stored");
+    const sites = siteFlags(flags);
     if (url) {
       await remoteCall(url, flags, "/api/secrets", {
         method: "PUT",
-        body: JSON.stringify({ name, value, workspace: scope }),
+        body: JSON.stringify({ name, value, workspace: scope, ...(sites.length ? { sites } : {}) }),
       });
     } else {
-      (await core()).setSecret("default", name, value, scope);
+      const k = await core();
+      k.setSecret("default", name, value, scope);
+      if (sites.length) await localSetSites(name, sites, scope);
     }
-    console.log(`\n  ${c.green("✓")} ${name} stored — declare it in agent.md under \`secrets:\` to use it\n`);
+    console.log(`\n  ${c.green("✓")} ${name} stored${sites.length ? ` and sent only to ${sites.join(", ")}` : ""} — declare it in agent.md under \`secrets:\` to use it\n`);
     return 0;
   }
 
@@ -3625,7 +3785,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 +3861,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 +4866,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 +6282,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
@@ -6829,6 +7291,84 @@ async function agentLinkCmd(positional, flags, layout) {
   return 0;
 }
 
+/**
+ * `foldrun agent network <agent> [open|trusted|none|inherit] [--add <site>]…
+ * [--remove <site>]…` — which sites the agent's sandbox may reach, its
+ * `network:` line, edited the way the dashboard's Network card edits it
+ * (core network.ts setNetworkSetting: that one line, nothing else). With no
+ * level and no site it prints what a run resolves.
+ */
+async function agentNetworkCmd(positional, flags, layout) {
+  const name = positional[1];
+  const word = positional[2];
+  const usage = "`foldrun agent network <agent> [open|trusted|none|inherit] [--add <site>]… [--remove <site>]…`";
+  if (!name) throw new Error(usage);
+  if (word !== undefined && !["open", "trusted", "none", "inherit"].includes(word)) throw new Error(`${usage} — "${word}" is not a level`);
+  const net = await import("@foldrun/core/network").catch(() => null);
+  if (!net) throw new Error("agent network needs @foldrun/core 1.1 or later — update foldrun");
+  const desk = await openDesk(flags, layout, `agent network ${name}`);
+  const rel = `agents/${name}/agent.md`;
+  if (!desk.files.has(rel)) {
+    const agents = [...desk.files.keys()].map((r) => /^agents\/([^/]+)\/agent\.md$/.exec(r)?.[1]).filter(Boolean);
+    throw new Error(`no agent "${name}" in ${desk.label} — it has ${agents.join(", ") || "none"}`);
+  }
+  const resolve = (files) =>
+    inTree(desk, files, async (dir) => {
+      const { listAgents, readFrontmatter } = await core();
+      return {
+        info: listAgents("default", "workspace").find((a) => a.name === name),
+        own: net.readNetwork(readFrontmatter(path.join(dir, rel)).network).setting,
+      };
+    });
+  const show = (info) => {
+    const p = info?.network;
+    if (!p) return;
+    console.log(`  ${net.networkLine(p, true)}`);
+    if (p.level !== "open") console.log(`  ${c.dim("a run also allows its MCP servers, its web providers and the sites its secrets are bound to")}`);
+  };
+  const raw = desk.files.get(rel);
+  const now = await resolve(desk.files);
+  const list = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v]).filter((x) => typeof x === "string").flatMap((x) => x.split(",")).map((x) => x.trim().toLowerCase()).filter(Boolean);
+  const adds = list(flags.add);
+  const removes = list(flags.remove);
+  if (word === undefined && !adds.length && !removes.length) {
+    console.log(`\n  ${c.bold(name)} ${c.dim(`· ${desk.label}`)}`);
+    show(now.info);
+    console.log();
+    return 0;
+  }
+  const own = now.own ?? { allow: [] };
+  const level = word === "inherit" ? undefined : word ?? own.level;
+  const allow = [...new Set([...own.allow, ...adds])].filter((x) => !removes.includes(x));
+  const setting = level || allow.length || own.defaults === false
+    ? { ...(level ? { level } : {}), allow, ...(own.defaults === false ? { defaults: false } : {}) }
+    : null;
+  const problems = setting ? net.readNetwork(setting).problems : [];
+  if (problems.length) throw new Error(problems.join(" "));
+  const next = net.setNetworkSetting(raw, setting);
+  if (next === raw) {
+    console.log(`\n  ${c.dim(`${name}'s network: already says that — nothing to change`)}\n`);
+    return 0;
+  }
+  console.log(`\n  ${c.bold(name)} ${c.dim(`· network · ${desk.label}`)}\n`);
+  await printDiff(rel, raw, next);
+  if (flags["dry-run"] === true) {
+    console.log(`\n  ${c.dim("--dry-run: nothing written")}\n`);
+    return 0;
+  }
+  if (desk.platform) {
+    await remoteCall(desk.url, flags, `/api/workspaces/${enc(desk.ws)}/agents/${enc(name)}`, { method: "PATCH", body: JSON.stringify({ network: setting }) });
+  } else {
+    assertUnchanged(desk, rel, raw);
+    writeIfUnchanged(desk, rel, raw, next);
+  }
+  const after = await resolve(new Map([...desk.files, [rel, next]]));
+  console.log();
+  show(after.info);
+  console.log(`\n  ${c.green("✓")} ${rel} ${c.dim(desk.platform ? `in ${desk.ws} — a revision on the platform` : "— `foldrun deploy` ships it")}\n`);
+  return 0;
+}
+
 /**
  * `foldrun flow show <flow>` — the canvas, in a terminal: the trigger, one
  * block per group, each step's chips, the team under its agent, and what
@@ -7138,7 +7678,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 +7714,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 +8001,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`);
@@ -8441,6 +8981,295 @@ async function flowDraftCmd(positional, flags, layout) {
   return 0;
 }
 
+/** `foldrun assistant history` — your kept conversations, newest first
+ *  (`--q` searches them, `--workspace` narrows to one, `--json`). */
+async function assistantHistoryCmd(url, flags) {
+  const q = new URLSearchParams();
+  if (typeof flags.q === "string" && flags.q.trim()) q.set("q", flags.q.trim());
+  if (typeof flags.workspace === "string") q.set("workspace", flags.workspace);
+  if (typeof flags.limit === "string") q.set("limit", flags.limit);
+  const d = await remoteCall(url, flags, `/api/assistant/conversations${q.size ? `?${q}` : ""}`);
+  const list = d.conversations ?? [];
+  if (flags.json) {
+    console.log(JSON.stringify(d, null, 2));
+    return 0;
+  }
+  if (!list.length) {
+    console.log(`\n  ${c.dim(flags.q ? "nothing matches" : "no conversations yet")}\n`);
+    return 0;
+  }
+  console.log();
+  for (const x of list) {
+    console.log(`  ${c.bold(x.id)}  ${x.workspace}  ${c.dim(`${ago(x.updatedAt)} ago · ${x.messages} message${x.messages === 1 ? "" : "s"}${x.unsaved ? ` · ${x.unsaved} unsaved` : ""}`)}`);
+    console.log(`    ${x.title}`);
+  }
+  console.log(`\n  ${c.dim("foldrun assistant show <id> · foldrun assistant --conversation <id> \"…\" · foldrun assistant rm <id>")}\n`);
+  return 0;
+}
+
+/** `foldrun assistant show <id>` — one kept conversation, whole. */
+async function assistantShowCmd(url, flags, id) {
+  const d = await remoteCall(url, flags, `/api/assistant/conversations/${enc(id)}`);
+  if (flags.json) {
+    console.log(JSON.stringify(d, null, 2));
+    return 0;
+  }
+  console.log(`\n  ${c.bold(d.title)}  ${c.dim(`${d.workspace} · ${ago(d.updatedAt)} ago`)}\n`);
+  for (const m of d.messages ?? []) {
+    console.log(`  ${m.role === "user" ? c.bold("you ›") : c.dim("assistant ›")}`);
+    console.log(`${String(m.content).split("\n").map((l) => `    ${l}`).join("\n")}\n`);
+  }
+  if ((d.files ?? []).length) console.log(`  ${c.dim(`${d.files.length} proposed file${d.files.length === 1 ? "" : "s"} not saved: ${d.files.map((f) => f.path).join(", ")}`)}\n`);
+  return 0;
+}
+
+/** `foldrun assistant rm <id>` — delete one kept conversation (asks; --yes). */
+async function assistantRmCmd(url, flags, id) {
+  if (!(await sureToDelete(flags, "assistant rm", `Delete the conversation ${id}`))) return 0;
+  await remoteCall(url, flags, `/api/assistant/conversations/${enc(id)}`, { method: "DELETE" });
+  console.log(`  ${c.green("✓")} deleted ${id}\n`);
+  return 0;
+}
+
+/**
+ * `foldrun assistant ["<message>"] --to <ws>` (also `foldrun ai`) — the
+ * dashboard's assistant from a terminal: it answers from foldrun's docs and
+ * the deployed workspace's files only, and writes agents, flows, tools and
+ * skills as proposals (POST …/assistant). With a message it answers once;
+ * with none, in a terminal, it is a conversation (/save, /files, /drop
+ * <path>, /new, /quit). Proposals are shown as diffs with what the check
+ * finds and saved only on yes (--yes; --dry-run never), each through
+ * `PUT …/source` with ifMatch, so a file that changed meanwhile is refused.
+ * --json prints the platform's answer as it is.
+ */
+async function assistantCmd(positional, flags, layout) {
+  const url = platformFor(flags, "assistant");
+  // The kept conversations: `history`, `show <id>`, `rm <id>`.
+  const sub = positional[0];
+  if (sub === "history" && positional.length === 1) return assistantHistoryCmd(url, flags);
+  if ((sub === "show" || sub === "rm") && positional.length === 2 && /^c_[a-z0-9]{8,40}$/.test(positional[1])) {
+    return sub === "show" ? assistantShowCmd(url, flags, positional[1]) : assistantRmCmd(url, flags, positional[1]);
+  }
+  // A kept conversation knows its workspace; --to may still say another.
+  let ws = typeof flags.conversation === "string" && typeof flags.to !== "string" ? "" : platformWorkspace(flags, layout, "assistant");
+  const first = positional.join(" ").trim();
+  /** A new workspace the last reply proposed.
+   *  @type {{ name: string, purpose: string } | null} */
+  let proposedWs = null;
+  if (!first && !process.stdin.isTTY) {
+    throw new Error('`foldrun assistant "<question or what to build>" --to <workspace>` — with no message it needs a terminal to talk in');
+  }
+  /** @type {{ role: "user" | "assistant", content: string }[]} */
+  let messages = [];
+  /** @type {{ path: string, content: string, before: string | null, sha256: string | null }[]} */
+  let files = [];
+  /** @type {{ where: string, message: string, level: string }[]} */
+  let issues = [];
+  /** The kept conversation this one continues; null until the first reply. */
+  let conversation = typeof flags.conversation === "string" ? flags.conversation : null;
+  if (conversation) {
+    // Carry a kept one on: its messages and its unsaved files come back.
+    const kept = await remoteCall(url, flags, `/api/assistant/conversations/${enc(conversation)}`);
+    messages = (kept.messages ?? []).map((m) => ({ role: m.role, content: m.content }));
+    files = kept.files ?? [];
+    if (!ws) ws = kept.workspace;
+    if (!flags.json) console.log(`\n  ${c.dim(`carrying on "${kept.title}" in ${kept.workspace} — ${messages.length} message${messages.length === 1 ? "" : "s"}`)}`);
+  }
+
+  const showFiles = async () => {
+    for (const f of files) {
+      console.log(`  ${c.dim(f.before === null ? "new" : "replaces")}`);
+      await printDiff(f.path, f.before ?? "", f.content);
+      console.log();
+    }
+    for (const i of issues) console.log(`  ${i.level === "error" ? c.red("error") : c.amber(" warn")}  ${c.bold(i.where)}  ${i.message}`);
+    if (issues.length) console.log();
+  };
+
+  const ask = async (text) => {
+    messages.push({ role: "user", content: text });
+    if (!flags.json) console.log(`\n  ${c.dim("reading the docs and the workspace — one reply, charged like a step…")}`);
+    let d;
+    try {
+      d = await remoteCall(
+        url,
+        flags,
+        `/api/workspaces/${enc(ws)}/assistant`,
+        { method: "POST", body: JSON.stringify({ messages, files: files.map(({ path: p, content }) => ({ path: p, content })), ...(conversation ? { conversation } : {}) }) },
+        { seconds: Math.max(timeoutSeconds(flags), 300) },
+      );
+    } catch (err) {
+      messages.pop();
+      throw err;
+    }
+    messages.push({ role: "assistant", content: d.reply ?? "" });
+    files = d.files ?? [];
+    issues = d.issues ?? [];
+    proposedWs = d.workspace ?? null;
+    if (typeof d.conversation === "string" && d.conversation) conversation = d.conversation;
+    if (flags.json) {
+      console.log(JSON.stringify(d, null, 2));
+      return;
+    }
+    console.log(`\n${(d.reply ?? "").split("\n").map((l) => `  ${l}`).join("\n")}\n`);
+    if ((d.sources ?? []).length) console.log(`  ${c.dim(`read: ${d.sources.map((s) => `${s.doc} › ${s.section}`).join(" · ")}`)}\n`);
+    if (conversation) console.log(`  ${c.dim(`kept as ${conversation} — carry on with --conversation ${conversation}`)}\n`);
+    if (d.usage) {
+      const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+      const paid = d.supply === "provider" ? "on your own model key" : typeof d.chargedUsd === "number" ? `$${d.chargedUsd.toFixed(d.chargedUsd > 0 && d.chargedUsd < 0.01 ? 4 : 2)} charged` : "";
+      console.log(`  ${c.dim(`${k(d.usage.inputTokens)} tokens in · ${k(d.usage.outputTokens)} out${paid ? ` · ${paid}` : ""}`)}\n`);
+    }
+    if (proposedWs) console.log(`  ${c.bold("new workspace")} ${proposedWs.name} ${c.dim(`— ${proposedWs.purpose}`)}\n`);
+    await showFiles();
+  };
+
+  /** What the last reply proposed — read through a call, because ask()
+   *  sets it and a type checker narrowing the variable cannot see that. */
+  const proposal = () => proposedWs;
+
+  /** Create the proposed workspace, blank, as the dashboard does — after a
+   *  yes, and never over one that exists (the same POST deploys over it).
+   *  @param {{ name: string, purpose: string }} p */
+  const createProposed = async (p) => {
+    const name = p.name;
+    if (!(await confirmed(flags, "assistant", `Create the workspace ${name}? [y/N] `))) {
+      console.log(`\n  ${c.dim("not created")}\n`);
+      return false;
+    }
+    // ifAbsent: the server refuses a name that exists (409) rather than
+    // deploying over it — atomically, where a list-then-create could race.
+    try {
+      await remoteCall(url, flags, "/api/workspaces", { method: "POST", body: JSON.stringify({ name, template: true, ifAbsent: true }) });
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 409) {
+        console.log(`  ${c.red("✗")} a workspace called ${name} exists — nothing created\n`);
+        return false;
+      }
+      throw err;
+    }
+    console.log(`  ${c.green("✓")} created ${name}\n`);
+    proposedWs = null;
+    return name;
+  };
+
+  const save = async (note) => {
+    if (!files.length) {
+      console.log(`  ${c.dim("nothing proposed to save")}\n`);
+      return true;
+    }
+    if (!(await confirmed(flags, "assistant", `Save ${files.length} file${files.length === 1 ? "" : "s"} to ${ws}${files.some((f) => f.before !== null) ? " (replacing what is there)" : ""}? [y/N] `))) {
+      console.log(`\n  ${c.dim("nothing saved")}\n`);
+      return true;
+    }
+    const message = `written with the assistant: ${note.replace(/\s+/g, " ").slice(0, 80)}`;
+    for (const f of [...files]) {
+      try {
+        await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/source`, { method: "PUT", body: JSON.stringify({ path: f.path, content: f.content, message, ifMatch: f.sha256 ?? null }) });
+        console.log(`  ${c.green("✓")} ${f.path}`);
+        files = files.filter((x) => x.path !== f.path);
+        issues = issues.filter((i) => !(i.where === f.path || i.where.startsWith(`${f.path}:`)));
+      } catch (err) {
+        console.log(`  ${c.red("✗")} ${f.path} — ${err instanceof Error ? err.message : err}`);
+        return false;
+      }
+    }
+    console.log(`\n  ${c.dim(`each is a revision — \`foldrun history --to ${ws}\` · \`foldrun check --to ${ws}\``)}\n`);
+    return true;
+  };
+
+  if (first) {
+    await ask(first);
+    const p = proposal();
+    if (p && !flags.json) {
+      if (flags["dry-run"] === true) {
+        console.log(`  ${c.dim("--dry-run: no workspace created")}\n`);
+        return 0;
+      }
+      if (flags.yes !== true && !process.stdin.isTTY) {
+        console.log(`  ${c.dim(`not a terminal to ask — no workspace created; run it again with --yes, or create it with \`foldrun new ${p.name}\` and deploy`)}\n`);
+        return 1;
+      }
+      const made = await createProposed(p);
+      if (made) console.log(`  ${c.dim(`carry on there: foldrun assistant --to ${made} "<what it should do>"`)}\n`);
+      return made ? 0 : 1;
+    }
+    if (!files.length || flags.json) return 0;
+    if (flags["dry-run"] === true) {
+      console.log(`  ${c.dim("--dry-run: nothing saved")}\n`);
+      return 0;
+    }
+    if (flags.yes !== true && !process.stdin.isTTY) {
+      console.log(`  ${c.dim(`the reply was made (charged like a step), but this is not a terminal to ask — nothing saved — run it again with --yes to save ${files.length === 1 ? "this file" : `these ${files.length} files`}, or save them with \`foldrun source put\``)}\n`);
+      return 1;
+    }
+    return (await save(first)) ? 0 : 1;
+  }
+
+  const { createInterface } = await import("node:readline/promises");
+  console.log(`\n  ${c.bold("foldrun assistant")} ${c.dim(`· ${ws} · answers from the foldrun docs; nothing is saved until you /save`)}`);
+  console.log(`  ${c.dim("/save  /files  /drop <path>  /new  /quit")}\n`);
+  for (;;) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let line;
+    try {
+      line = (await rl.question(`${c.bold("you ›")} `)).trim();
+    } catch {
+      line = "/quit"; // the input closed (Ctrl-D)
+    } finally {
+      rl.close();
+    }
+    if (!line) continue;
+    if (line === "/quit" || line === "/exit") {
+      if (files.length) console.log(`\n  ${c.dim(`${files.length} proposed file${files.length === 1 ? "" : "s"} not saved`)}`);
+      console.log();
+      return 0;
+    }
+    if (line === "/new") {
+      messages = [];
+      files = [];
+      issues = [];
+      conversation = null;
+      console.log(`  ${c.dim("a new conversation")}\n`);
+      continue;
+    }
+    if (line === "/files") {
+      if (files.length) await showFiles();
+      else console.log(`  ${c.dim("nothing proposed")}\n`);
+      continue;
+    }
+    if (line.startsWith("/drop")) {
+      const target = line.slice(5).trim();
+      const before = files.length;
+      files = files.filter((f) => f.path !== target);
+      issues = issues.filter((i) => !(i.where === target || i.where.startsWith(`${target}:`)));
+      console.log(`  ${c.dim(files.length < before ? `dropped ${target}` : `${target || "(no path)"} is not proposed`)}\n`);
+      continue;
+    }
+    if (line === "/save") {
+      await save(messages.find((m) => m.role === "user")?.content ?? "");
+      continue;
+    }
+    try {
+      await ask(line);
+      const p = proposal();
+      if (p) {
+        const made = await createProposed(p);
+        if (made) {
+          // The conversation moves into the new workspace and carries on.
+          ws = made;
+          files = [];
+          issues = [];
+          messages.push({ role: "assistant", content: `Created the workspace \`${made}\`.` });
+          console.log(`  ${c.dim(`now working in ${made}`)}`);
+          await ask(`The workspace "${made}" now exists and you are working in it. Carry on with what I asked for: write its agents, flows, tools and skills.`);
+        }
+      }
+    } catch (err) {
+      console.log(`\n  ${c.red("✗")} ${err instanceof Error ? err.message : err}\n`);
+    }
+  }
+}
+
 /**
  * `foldrun history restore <path> --id <revision> --to <ws>` — the History
  * drawer's "Restore this version": the file is rewritten with that
@@ -8495,7 +9324,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 +9344,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 +9364,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 +9633,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 +9683,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 +9693,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 +9716,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 +9941,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":
@@ -9308,11 +10184,15 @@ export async function run(command, positional, flags, workspace, layout) {
       // `new` scaffolds one here; `run` runs one there. The noun is the same
       // thing in both cases, which is why they share a command.
       if (positional[0] === "link" || positional[0] === "unlink") return agentLinkCmd(positional, flags, layout);
+      if (positional[0] === "network") return agentNetworkCmd(positional, flags, layout);
       if (positional[0] === "import") return agentImportCmd(positional, flags, layout);
       if (positional[0] === "ls" || positional[0] === "list") return remoteListCmd("agents", flags, layout);
       return positional[0] === "run"
         ? agentRunCmd(positional, flags, layout)
         : scaffoldCmd("agents", positional, flags, layout);
+    case "assistant":
+    case "ai":
+      return assistantCmd(positional, flags, layout);
     case "flow":
       // `new` scaffolds a file; `add`, `rm-step` and `show` are the canvas; `run` is
       // `invoke`, spelled the way `agent run` is; `rotate-hook` a new URL.
@@ -9335,6 +10215,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":