@foldrun/core 2.4.0 → 2.6.0

package/dist/src/runs-filter.d.ts

@@ -0,0 +1,48 @@
+export interface RunFilter {
+    /** A step called a tool whose name contains this (`web`, `crm_export`). */
+    tool?: string;
+    /** A tool call errored. */
+    toolError?: boolean;
+    /** A step was this agent. */
+    agent?: string;
+    /** A step ran a model whose name contains this (`haiku`, `opus`). */
+    model?: string;
+    /** The run read at least this many input tokens, all steps together. */
+    minTokens?: number;
+    /** The run took at least this many seconds. */
+    minSecs?: number;
+}
+/** The query parameters a filter comes from: tool, tool_error, agent,
+ *  model, min_tokens, min_secs. Unreadable numbers are refused in words. */
+export declare function parseRunFilter(q: {
+    get(name: string): string | null;
+}): {
+    filter: RunFilter;
+    problems: string[];
+};
+export declare const isEmptyFilter: (f: RunFilter) => boolean;
+type FilterableStep = {
+    agent: string;
+    model?: string;
+    tools?: string[];
+    toolErrors?: number;
+    /** A whole record has events instead of the index's tools/toolErrors. */
+    events?: {
+        type: string;
+        text: string;
+        ms?: number;
+        err?: boolean;
+    }[];
+    tokens?: {
+        input?: number;
+    } | null;
+    startedAt?: string;
+    finishedAt?: string;
+};
+type FilterableRun = {
+    startedAt: string;
+    finishedAt?: string | null;
+    steps: FilterableStep[];
+};
+export declare function matchesRunFilter(run: FilterableRun, f: RunFilter, now?: number): boolean;
+export {};

package/dist/src/runs-filter.js

@@ -0,0 +1,73 @@
+// Search over runs (FOL-72 step 9): one filter for the runs API, the runs
+// pages and `foldrun runs`, read off the run index — the tools each step
+// called, its tool errors, its agent and model, tokens and how long it took.
+// Pure.
+/** The query parameters a filter comes from: tool, tool_error, agent,
+ *  model, min_tokens, min_secs. Unreadable numbers are refused in words. */
+export function parseRunFilter(q) {
+    const filter = {};
+    const problems = [];
+    const text = (k) => q.get(k)?.trim() || undefined;
+    const tool = text("tool");
+    if (tool)
+        filter.tool = tool.toLowerCase();
+    const te = text("tool_error");
+    if (te)
+        filter.toolError = te === "1" || te === "true" || te === "yes";
+    const agent = text("agent");
+    if (agent)
+        filter.agent = agent;
+    const model = text("model");
+    if (model)
+        filter.model = model.toLowerCase();
+    for (const [k, field] of [["min_tokens", "minTokens"], ["min_secs", "minSecs"]]) {
+        const v = text(k);
+        if (v === undefined)
+            continue;
+        // "50k" and "1.5k" are thousands (Codex review: "1.5k" read as 1.5).
+        const kilo = /^(\d+(?:\.\d+)?)k$/i.exec(v);
+        const n = kilo ? Number(kilo[1]) * 1000 : Number(v);
+        if (!Number.isFinite(n) || n < 0)
+            problems.push(`${k} is a number (${k === "min_tokens" ? "50000 or 50k" : "seconds"}), not ${v}`);
+        else
+            filter[field] = n;
+    }
+    return { filter, problems };
+}
+export const isEmptyFilter = (f) => Object.keys(f).length === 0;
+/** The index's facts, or worked out from a whole record's events (Codex
+ *  review: the workspace runs page reads whole records). */
+function factsOf(s) {
+    if (s.tools !== undefined || s.toolErrors !== undefined || !s.events)
+        return { tools: s.tools ?? [], toolErrors: s.toolErrors ?? 0 };
+    const tools = new Set();
+    let errs = 0;
+    for (const e of s.events) {
+        if (e.type !== "tool")
+            continue;
+        if (e.ms == null)
+            tools.add(e.text);
+        else if (e.err)
+            errs++;
+    }
+    return { tools: [...tools], toolErrors: errs };
+}
+export function matchesRunFilter(run, f, now = Date.now()) {
+    const steps = (run.steps ?? []).map((s) => ({ ...s, ...factsOf(s) }));
+    if (f.tool && !steps.some((s) => (s.tools ?? []).some((t) => t.toLowerCase().includes(f.tool))))
+        return false;
+    if (f.toolError !== undefined && steps.some((s) => (s.toolErrors ?? 0) > 0) !== f.toolError)
+        return false;
+    if (f.agent && !steps.some((s) => s.agent === f.agent))
+        return false;
+    if (f.model && !steps.some((s) => (s.model ?? "").toLowerCase().includes(f.model)))
+        return false;
+    if (f.minTokens !== undefined && steps.reduce((n, s) => n + (s.tokens?.input ?? 0), 0) < f.minTokens)
+        return false;
+    if (f.minSecs !== undefined) {
+        const secs = ((run.finishedAt ? Date.parse(run.finishedAt) : now) - Date.parse(run.startedAt)) / 1000;
+        if (!(secs >= f.minSecs))
+            return false;
+    }
+    return true;
+}

package/dist/src/scan.d.ts

@@ -25,6 +25,10 @@ export interface ScanFinding {
     message: string;
     /** Stable across edits elsewhere in the file: rule + file + line text. */
     fingerprint: string;
+    /** This rule had more to say in this file than PER_FILE_RULE: this
+     *  finding counts the rest, so what is not listed is not resolved. Its
+     *  fingerprint is of everything it counts, so a change among them is new. */
+    truncated?: true;
 }
 export interface ScanOptions {
     /** Tool names whose definition says `outward: true` — the CLI and the
@@ -66,11 +70,36 @@ export declare function redactSecret(secret: string): string;
 /** The text with every credential in it redacted — for a finding that
  *  quotes source, so no message ever carries a key whole. */
 export declare function redactText(text: string): string;
+/**
+ * Text from outside the workspace — what a remote MCP server says about its
+ * tools — through the content rules with nothing the text itself can turn
+ * off: no foldrun-ignore, no binary or vendored-path skip, no fences
+ * (FOL-58, Codex review: each of those let a server silence its own finding).
+ */
+export declare function untrustedTextFindings(text: string): {
+    rule: string;
+    line: number;
+    message: string;
+}[];
 /** The known field a key was probably meant to be, or null. */
 export declare function nearestField(key: string, known: readonly string[]): string | null;
+/** What a run leaves in an agent's folder — the Claude CLI's `.cache/` logs,
+ *  package caches — and copies back with it. Nobody wrote these, so they are
+ *  not checked as prompts or code; they are still searched for credentials,
+ *  since a key in a log here is a key in the workspace (seen live on
+ *  17 Oct 2026: zero-width characters in a CLI MCP log, reported as hidden
+ *  text). */
+/** The definition files a deploy refuses outright when their frontmatter does
+ *  not parse (deploy.ts deployIssues): the workspace's own, by these paths.
+ *  Everything else the platform reads frontmatter from — skills, and the
+ *  account library's agents, tools and hooks — is the scanner's to report. */
+export declare const STRICT_FRONTMATTER_PATH: RegExp;
+/** How many times one rule is listed for one file before the rest are counted. */
+export declare const PER_FILE_RULE = 100;
 /**
  * Every finding in these files, ignores applied. Findings are sorted by file
- * then line, and one rule says one thing once per line.
+ * then line, and one rule says one thing once per line, and at most
+ * PER_FILE_RULE times in one file.
  */
 export declare function scanFiles(files: ScanFile[], options?: ScanOptions): ScanFinding[];
 /**

package/dist/src/scan.js

@@ -26,7 +26,7 @@
 // The reason is required: an ignore without one ignores nothing and is itself
 // reported, because "why is this allowed?" is the question a reviewer asks.
 import crypto from "node:crypto";
-import matter from "gray-matter";
+import matter, { frontmatterErrorLine, frontmatterErrorText, parseLenient, configMatter } from "./matter.js";
 import { refNames } from "./refs.js";
 import { resolveNetwork } from "./network.js";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.js";
@@ -117,6 +117,24 @@ export const SCAN_RULES = [
             "so a run tomorrow uses what was tested today.",
         owasp: ["ASI04"],
     },
+    {
+        id: "supply-chain/known-vulnerability",
+        category: "supply-chain",
+        level: "warn",
+        title: "A pinned runtime package with known vulnerabilities",
+        help: "OSV.dev lists vulnerabilities for this exact version. Upgrade to a fixed one. An online check: `foldrun check --to <ws> --online`, " +
+            "Checks → Check online, and the daily rescan.",
+        owasp: ["ASI04"],
+    },
+    {
+        id: "content/mcp-tool-text",
+        category: "content",
+        level: "warn",
+        title: "An MCP server's tool text carries hidden or injected instructions",
+        help: "What a remote MCP server says about its tools reaches the model as instructions. Hidden characters or an order in a tool " +
+            "description is a server steering your agent. An online check, for servers reached by URL; a command server is never run to check it.",
+        owasp: ["ASI01", "ASI04"],
+    },
     {
         id: "config/unknown-field",
         category: "config",
@@ -141,6 +159,32 @@ export const SCAN_RULES = [
         help: "`effort: extreme`, `size: giant`, `trigger: sometimes`, a cron the scheduler cannot read: each is ignored or falls back, " +
             "so the agent or flow quietly does something else. The message lists what the field takes.",
     },
+    {
+        id: "config/conflict",
+        category: "config",
+        level: "error",
+        title: "A field set twice: at the top and inside its job block",
+        help: "`limits:` at the top and `limits:` inside `guardrail:` cannot both be meant. The top one would be read and the other " +
+            "quietly ignored, so the file is refused until one is removed.",
+    },
+    {
+        id: "config/misplaced",
+        category: "config",
+        level: "error",
+        title: "A field inside the wrong job block",
+        help: "Each of the four blocks (governance, guardrail, observability, evaluation) holds its own fields. A setting written in " +
+            "another block is not read — a guardrail under governance: guards nothing — so the file is refused until it is moved " +
+            "to the block the message names, or to the top. A word foldrun does not read at all is only a note.",
+    },
+    {
+        id: "config/invalid-frontmatter",
+        category: "config",
+        level: "warn",
+        title: "Frontmatter that YAML cannot read",
+        help: "A value with a colon followed by a space (`description: the format (Markdown, ::: directives)`) ends the YAML. " +
+            "foldrun reads a skill like that by quoting the value, but the dashboard editor and the source API refuse to save it, " +
+            "and other tools that read the file may not. Quote the value: `description: \"…\"`.",
+    },
     {
         id: "config/missing-field",
         category: "config",
@@ -399,13 +443,15 @@ const INJECTION = [
     /\b(?:send|post|upload|exfiltrate)\s+(?:all\s+|the\s+|every\s+)?(?:secrets?|credentials|api\s+keys?|tokens?|env(?:ironment)?\s+variables)\s+to\b/i,
 ];
 const BLOB = /[A-Za-z0-9+/]{300,}={0,2}/g;
-function scanContent(file, lines, push) {
-    const md = /\.md$/i.test(file.path);
-    const data = isDataDoc(file.path);
+function scanContent(file, lines, push, untrusted = false) {
+    // Untrusted text (a remote server's) is read as data, every line: it
+    // cannot fence an order off as an "example" either.
+    const md = untrusted || /\.md$/i.test(file.path);
+    const data = untrusted || isDataDoc(file.path);
     let fenced = false;
     for (let i = 0; i < lines.length; i++) {
         const line = i === 0 ? lines[i].replace(/^/, "") : lines[i];
-        if (/^\s*(?:```|~~~)/.test(line))
+        if (!untrusted && /^\s*(?:```|~~~)/.test(line))
             fenced = !fenced;
         HIDDEN.lastIndex = 0;
         if (HIDDEN.test(line)) {
@@ -431,6 +477,17 @@ function scanContent(file, lines, push) {
         }
     }
 }
+/**
+ * Text from outside the workspace — what a remote MCP server says about its
+ * tools — through the content rules with nothing the text itself can turn
+ * off: no foldrun-ignore, no binary or vendored-path skip, no fences
+ * (FOL-58, Codex review: each of those let a server silence its own finding).
+ */
+export function untrustedTextFindings(text) {
+    const out = [];
+    scanContent({ path: "untrusted", content: text }, text.split(/\r?\n/), (rule, _file, line, _text, message) => out.push({ rule, line: line ?? 0, message }), true);
+    return out;
+}
 /** The text hidden in tag characters: each is U+E0000 + an ASCII code. */
 function decodeTags(s) {
     let out = "";
@@ -513,17 +570,35 @@ export function nearestField(key, known) {
     return bestD <= allowed ? best : null;
 }
 function keyLine(lines, key) {
-    const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`);
-    const i = lines.findIndex((l) => re.test(l));
-    return i >= 0 ? i + 1 : undefined;
+    const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const top = new RegExp(`^${k}\\s*:`);
+    const i = lines.findIndex((l) => top.test(l));
+    if (i >= 0)
+        return i + 1;
+    // A key inside one of the four job blocks: indented, under its header.
+    const inner = new RegExp(`^\\s+${k}\\s*:`);
+    let inBlock = false;
+    for (let n = 0; n < lines.length; n++) {
+        const l = lines[n];
+        if (/^(governance|guardrail|observability|evaluation)\s*:\s*(#.*)?$/.test(l))
+            inBlock = true;
+        else if (/^\S/.test(l))
+            inBlock = false;
+        else if (inBlock && inner.test(l))
+            return n + 1;
+    }
+    return undefined;
 }
 /** Read-only: gray-matter caches by content, so two files with the same
  *  text share one object, and writing to it would leak between them. */
-function frontOf(content) {
+function frontOf(content, filePath) {
     if (!/^?---\r?\n/.test(content))
         return null;
     try {
-        return matter(content).data;
+        // An agent, a flow or AGENTS.md reads its job blocks as flat keys, as
+        // the runtime does; every other document is read as written.
+        const kind = filePath ? schemaKindOf(filePath) : null;
+        return (kind === "agent" || kind === "flow" || kind === "agents-md" ? configMatter(content) : matter(content)).data;
     }
     catch {
         return null; // a frontmatter YAML cannot read is check's finding, not ours
@@ -652,14 +727,25 @@ const VENDORED = /(?:^|\/)(?:node_modules|\.venv|venv|site-packages|__pycache__|
  *  since a key in a log here is a key in the workspace (seen live on
  *  17 Oct 2026: zero-width characters in a CLI MCP log, reported as hidden
  *  text). */
+/** The definition files a deploy refuses outright when their frontmatter does
+ *  not parse (deploy.ts deployIssues): the workspace's own, by these paths.
+ *  Everything else the platform reads frontmatter from — skills, and the
+ *  account library's agents, tools and hooks — is the scanner's to report. */
+export const STRICT_FRONTMATTER_PATH = /^(AGENTS\.md|agents\/[^/]+\/agent\.md|flows\/[^/]+\.md|tools\/[^/]+\.md|tools\/[^/]+\/tool\.md|evals\/[^/]+\.md|hooks\/[^/]+\/hook\.md|\.claude\/agents\/[^/]+\.md)$/;
+/** A skill file in either layout the runtime discovers: <name>/SKILL.md, or
+ *  the flat <name>.md, under skills/ or .agents/skills/, in the library too. */
+const SKILL_FILE = /(?:^|\/)skills\/(?:[^/]+\/SKILL\.md|[^/]+\.md)$/;
 const RUNTIME_WRITTEN = /(?:^|\/)(?:\.cache|\.npm|\.local|\.pnpm-store|\.yarn|\.foldrun)\//;
 /** Text files only — a PNG read as UTF-8 is noise to every rule here. */
 function isText(f) {
     return !VENDORED.test(f.path) && !f.content.slice(0, 8000).includes("\u0000") && !/\.(?:png|jpe?g|gif|webp|ico|pdf|zip|gz|woff2?|ttf|mp[34]|mov|wasm)$/i.test(f.path);
 }
+/** How many times one rule is listed for one file before the rest are counted. */
+export const PER_FILE_RULE = 100;
 /**
  * Every finding in these files, ignores applied. Findings are sorted by file
- * then line, and one rule says one thing once per line.
+ * then line, and one rule says one thing once per line, and at most
+ * PER_FILE_RULE times in one file.
  */
 export function scanFiles(files, options = {}) {
     const want = options.only?.length ? new Set(options.only) : null;
@@ -667,6 +753,11 @@ export function scanFiles(files, options = {}) {
     const findings = [];
     const seen = new Set();
     const ignoresByFile = new Map();
+    // One rule in one file says it PER_FILE_RULE times, then counts the rest:
+    // a million lines of hidden characters is one problem, not a million
+    // findings held in memory (Codex review of the 20 Oct rescan outage).
+    const perFileRule = new Map();
+    const more = new Map();
     const push = (rule, file, line, text, message, level) => {
         if (!enabled(rule))
             return;
@@ -676,6 +767,16 @@ export function scanFiles(files, options = {}) {
         const key = `${rule}\0${file}\0${line ?? ""}\0${message}`;
         if (seen.has(key))
             return;
+        const rf = `${rule}\0${file}`;
+        const said = perFileRule.get(rf) ?? 0;
+        if (said >= PER_FILE_RULE) {
+            const m = more.get(rf) ?? { rule, file, level, n: 0, hash: crypto.createHash("sha256") };
+            m.n++;
+            m.hash.update(`${findingFingerprint(rule, file, text)}\0`);
+            more.set(rf, m);
+            return;
+        }
+        perFileRule.set(rf, said + 1);
         seen.add(key);
         findings.push({ rule, level: level ?? scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
     };
@@ -691,9 +792,35 @@ export function scanFiles(files, options = {}) {
         scanContent(f, lines, push);
         scanSupplyChain(f, lines, push);
         const schema = schemaKindOf(f.path);
+        // Frontmatter YAML cannot read. Until 2026-10-21 nothing reported it for
+        // a skill or a library file: frontOf below reads it as "no frontmatter"
+        // and moves on, and the deploy's own refusal covers only the workspace's
+        // definition files. A vaza.ai skill with `description: … (Markdown,
+        // frontmatter, ::: directives) …` deployed clean, ran (the runtime quotes
+        // the value and retries), and was refused by the source API on its next
+        // save.
+        if ((schema || SKILL_FILE.test(f.path)) && !STRICT_FRONTMATTER_PATH.test(f.path) && /^\uFEFF?---\r?\n/.test(f.content)) {
+            let err = null;
+            try {
+                matter(f.content);
+            }
+            catch (e) {
+                err = e;
+            }
+            if (err) {
+                const isSkill = schema === "skill" || SKILL_FILE.test(f.path);
+                const read = parseLenient(f.content);
+                const what = isSkill && !read.failed
+                    ? "foldrun reads this skill anyway by quoting the value, but the dashboard editor and the source API refuse to save it, and other skills clients may not load it"
+                    : isSkill
+                        ? "the runtime reads it as empty, so the skill has no name or description and is never loaded"
+                        : "the runtime cannot read this file";
+                push("config/invalid-frontmatter", f.path, frontmatterErrorLine(err), `config/invalid-frontmatter ${frontmatterErrorText(err)}`, `${frontmatterErrorText(err)} ${what === "the runtime cannot read this file" ? "The runtime cannot read this file" : what.replace(/^foldrun/, "foldrun").replace(/^the/, "The")}.`);
+            }
+        }
         // A skill with no frontmatter at all is the clearest one that never
         // loads: read it as empty, so its required fields are reported.
-        const data = schema || docKind(f.path) ? (frontOf(f.content) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
+        const data = schema || docKind(f.path) ? (frontOf(f.content, f.path) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
         if (!data)
             continue;
         if (schema) {
@@ -719,8 +846,12 @@ export function scanFiles(files, options = {}) {
             toolDefs.set(f.path, { data, lines });
         }
     }
-    const workspaceMd = files.find((f) => f.path === "AGENTS.md");
-    scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
+    // project.md is the older name the runtime still reads (Codex review, FOL-58).
+    const workspaceMd = files.find((f) => f.path === "AGENTS.md") ?? files.find((f) => f.path === "project.md");
+    scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content, "AGENTS.md")?.network : undefined });
+    for (const m of more.values()) {
+        findings.push({ rule: m.rule, level: m.level ?? scanRule(m.rule)?.level ?? "warn", file: m.file, message: `and ${m.n} more like this in this file, not listed`, fingerprint: m.hash.digest("hex").slice(0, 16), truncated: true });
+    }
     return findings.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
 }
 /**

package/dist/src/starter.js

@@ -55,6 +55,22 @@ foldrun_version: "0.1"
 #
 # The token is sent as a bearer credential. A gateway that wants it as a key
 # header asks for that by name: headers: { x-api-key: \${THE_SECRET} }.
+#
+# The four jobs of running agents, each a block — or write the same keys at
+# the top; one place or the other, never both:
+#
+# governance:          # who answers for it, what it may spend and ship
+#   owner: you@example.com
+#   budget: 60/month
+#   deploy_block: secrets
+# guardrail:           # what agents may reach and call
+#   limits: {calls: 300, repeat: 5}
+#   network: trusted
+# observability:       # what is recorded, and who is told
+#   notify: {email: you@example.com, events: [failed]}
+#   alerts: {failure_rate: 30%}
+# evaluation:          # how work is judged
+#   judge: {model: fast}
 ---
 
 # ${account}
@@ -357,7 +373,7 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/assistant\` | POST | ask the assistant, or have it write agents, flows, tools and skills — from the docs only; proposals come back, nothing is written |
 
 Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/schedule\`,
-\`/api/approvals\`, \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
+\`/api/approvals\`, \`/api/issues\` (what went wrong, open until resolved), \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
 \`/api/me/notifications\` (what mail you get; a key acts for whoever minted it),
 \`/api/account/backups\` (snapshots, restore requests), \`/api/me/onboarding\` (getting started),
 \`/api/healthz\` and \`/api/version\` (open), \`/api/changelog\` (release notes)
@@ -391,6 +407,7 @@ subflow), \`foldrun flow rm-step\` removes a step, and \`foldrun agent link
 trigger: manual          # manual | schedule | webhook
 schedule: "0 9 * * 1"    # cron, when trigger: schedule
 timezone: Australia/Sydney
+owner: ana@example.com   # who answers for it; else the workspace's, else the account's
 model: default           # a default for every step here
 effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
@@ -448,10 +465,11 @@ by a model: what this role is for, what it must not do, what good looks like.
 ---
 name: researcher
 description: Finds and summarises sources.
+owner: ana@example.com      # who answers for it; else the workspace's, else the account's
 model: default              # fast | default | max
 effort: low                 # how hard to think about it
 size: large                 # small | large | heavy — the sandbox it rents
-tools: [web, read, ask, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step
+tools: [web, read, ask, peers, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step, \`peers\` lets it message the steps running beside it
 disallowedTools: [Bash]     # subtract from what it would otherwise have
 skills: [house-style]       # from skills/
 hooks: [no-force-push]      # from hooks/ or the library: code at every tool call
@@ -474,6 +492,13 @@ runtime:                    # only if scripts need packages
 You research a topic and report what you found...
 \`\`\`
 
+The fields that do one of the four jobs of running agents may be grouped
+under it — \`governance:\` (owner, budget), \`guardrail:\` (limits, network,
+hooks, disallowedTools, permissionMode, secrets), and in AGENTS.md also
+\`observability:\` (alerts, telemetry, notify, capture) and \`evaluation:\`
+(judge). A block reads exactly as the same keys at the top; a key written
+both ways is refused (\`config/conflict\`). \`foldrun docs four-jobs\`.
+
 Only \`name\` and the prose are required. Every other field widens or narrows
 what the agent can reach, and the default is narrow.
 

package/dist/src/step-exec.d.ts

@@ -1,6 +1,6 @@
 import { type HookDef, type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
-import type { Effort } from "./store.ts";
+import { type Effort, type ModelCall } from "./store.ts";
 import { type TokenPrice } from "./catalog.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { OperatorEvent } from "./operator.ts";
@@ -57,6 +57,11 @@ export interface ExecOutcome {
     browserPod?: BrowserPodOutcome;
 }
 export interface ExecOptions {
+    /** What the step reports beyond its events (FOL-54 step 4): `metadata`
+     *  sends each model call (`turn`); `full` also sends each tool call's input
+     *  and output (`io`). Unset sends neither — the consult, the probe and any
+     *  caller that does not store them. */
+    capture?: "metadata" | "full";
     /** `hooks:` resolved host-side (hooks.ts): run at this step's own dispatch,
      *  inside its sandbox. `hookBase` is what every hook event carries. */
     hooks?: HookDef[];
@@ -99,6 +104,11 @@ export interface ExecOptions {
      *  `matches: re`, `file: path`, `judge: sentence`) — see checkVerify. */
     verify?: string;
     verifyEnv?: Record<string, string>;
+    /** The model `verify: judge:` grades with — the workspace's `judge:` from
+     *  AGENTS.md, resolved; absent, the fast tier. */
+    judgeModel?: string;
+    /** And how long it thinks — `judge: {effort}`; absent, the SDK's default. */
+    judgeEffort?: Effort;
     /** `output: json` — the reply must carry one JSON value; extracting it is
      *  part of finishing the step, and failing to is failing the step. */
     output?: "json";
@@ -175,7 +185,30 @@ export type EventExtra = {
     subagent?: string;
     check?: boolean;
     hook?: HookRecord;
+    /** A tool call's content, on its way to the runner (FOL-54 step 4): the
+     *  runner masks it, stores it beside the run and keeps only `captured` on
+     *  the event. Sent only under `capture: "full"`. */
+    io?: CallIo;
+    /** One model call, on its way to the runner's `step.calls` — not an event. */
+    turn?: ModelCall;
+    /** The model's first response of the step has begun streaming — the
+     *  moment the prompt cache entry its request wrote becomes readable. Sent
+     *  once; the runner's fan-out gate reads it. Not an event. */
+    responding?: true;
+    /** Set by the runner once it stored `io` (RunEvent.captured). */
+    captured?: boolean;
+    /** On a tool call: the model call (its message id) that asked for it. */
+    inCall?: string;
 };
+/** A tool call's input (on the call) or output (on its completion), capped. */
+export interface CallIo {
+    input?: string;
+    output?: string;
+    /** The whole input's / output's length, in characters, before any cut. */
+    inputChars?: number;
+    outputChars?: number;
+    truncated?: boolean;
+}
 /** Conservative per-token rates for a model nothing else can price — an
  *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
  *  still means something. Only ever reached when `knownPrice` below does
@@ -273,14 +306,17 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
     /** The step's own model environment, for `judge:` — it grades on the
      *  fast tier through the same credential the step rode. */
     modelEnv?: Record<string, string | undefined>;
+    /** The judge's model and effort (the workspace's `judge:`). */
+    judgeModel?: string;
+    judgeEffort?: Effort;
     /** Ends a shell check or a judge mid-way: the step's clock ran out, or a
      *  person asked the run to stop. */
     signal?: AbortSignal;
 }): Promise<VerifyVerdict>;
 /**
  * A toolless, fast-tier grading call: does the reply satisfy the sentence?
- * Same shape as the eval judge, and answered with one word first so the
- * verdict is a prefix test rather than a reading.
+ * Same shape as the eval judge: reasoning first, then the verdict alone on
+ * the last line (judge-verdict.ts says why).
  */
 export declare function judgePrompt(rubric: string, reply: string, work: string): string;
 /**