toolnexus 0.14.0 → 0.15.0

package/dist/agents/agent.d.ts

@@ -1,5 +1,8 @@
 import type { Answer, Request, Tool } from "../types.js";
 import { AgentRuntime, type AgentDef, type Budget, type RuntimeOptions, type TaskResult } from "./runtime.js";
+import { Loop, type Completion, type Guardrail } from "./loop.js";
+import type { ClientOptions } from "../client.js";
+import type { Toolkit } from "../toolkit.js";
 /** The declarative agent spec (§7D Level-1 surface). */
 export interface AgentSpec {
     /** Required routing description — what a delegating model sees. */
@@ -28,6 +31,15 @@ export interface AgentSpec {
     /** §8 observability sink for this agent. Set ⇒ replaces the runtime-wide
      * `onMetric` for this agent; resolves independently of `hooks`. */
     onMetric?: AgentDef["onMetric"];
+    /** POLICY checks on tool calls — "may it?", never "is it right?". They compile
+     * into one `beforeTool` with FIRST-DENY-WINS: a later guardrail can never widen
+     * an earlier denial. Composed with `hooks.beforeTool`, which runs only if every
+     * guardrail allows. Empty ⇒ byte-identical. */
+    guardrails?: Guardrail[];
+    /** When set, the gate that stops this agent claiming `done` before its work
+     * verifies. It travels WITH the agent, so a caller that delegates via `task`
+     * inherits it — which a host-side retry loop cannot do. Omitted ⇒ byte-identical. */
+    completion?: Completion;
 }
 /** Runtime options for a one-shot `run`/`asTool` (the registry is derived). */
 export type AgentRunOptions = Omit<RuntimeOptions, "registry">;
@@ -46,6 +58,12 @@ export declare class Agent {
      * the registry IS the reachable graph; unreachable agents are not present.
      */
     registry(acc?: Record<string, AgentDef>): Record<string, AgentDef>;
+    /**
+     * Open a LIVE EXECUTION of this agent. Takes client OPTIONS rather than a built
+     * client, because a per-call `model` override must be able to change the model —
+     * which is fixed when a client is constructed.
+     */
+    loop(options: ClientOptions, toolkit: Toolkit): Loop;
     /** Build a runtime scoped to this agent's reachable team graph. */
     createRuntime(opts?: AgentRunOptions): AgentRuntime;
     /**
@@ -64,3 +82,10 @@ export declare class Agent {
 }
 /** The one new noun: define an agent. */
 export declare function agent(name: string, spec: AgentSpec): Agent;
+/**
+ * `Harness` is a NAME, not a type. An agent spec already IS the harness — tools,
+ * soul, team, budget, model, policy, ceilings — so this is the word landing in the
+ * API without a second concept to learn or migrate to. A spec built through
+ * `harness` and one written inline are indistinguishable.
+ */
+export declare function harness(spec: AgentSpec): AgentSpec;

package/dist/agents/agent.js

@@ -10,6 +10,7 @@
 import fs from "node:fs";
 import { defineTool } from "../native.js";
 import { AgentRuntime, isVerbError } from "./runtime.js";
+import { Loop, guardedHooks } from "./loop.js";
 export class Agent {
     name;
     spec;
@@ -38,13 +39,24 @@ export class Agent {
             waitFor: this.spec.waitFor,
             onSpawn: this.spec.onSpawn,
             onClose: this.spec.onClose,
-            hooks: this.spec.hooks,
+            // Guardrails are compiled into the hook HERE, at the registry boundary, so a
+            // delegated child is governed by them too — not only a directly-driven one.
+            hooks: guardedHooks(this.spec.guardrails, this.spec.hooks),
             onMetric: this.spec.onMetric,
+            completion: this.spec.completion,
         };
         for (const t of this.spec.team ?? [])
             t.registry(acc);
         return acc;
     }
+    /**
+     * Open a LIVE EXECUTION of this agent. Takes client OPTIONS rather than a built
+     * client, because a per-call `model` override must be able to change the model —
+     * which is fixed when a client is constructed.
+     */
+    loop(options, toolkit) {
+        return new Loop(this, options, toolkit);
+    }
     /** Build a runtime scoped to this agent's reachable team graph. */
     createRuntime(opts = {}) {
         return new AgentRuntime({ ...opts, registry: this.registry() });
@@ -99,3 +111,12 @@ export class Agent {
 export function agent(name, spec) {
     return new Agent(name, spec);
 }
+/**
+ * `Harness` is a NAME, not a type. An agent spec already IS the harness — tools,
+ * soul, team, budget, model, policy, ceilings — so this is the word landing in the
+ * API without a second concept to learn or migrate to. A spec built through
+ * `harness` and one written inline are indistinguishable.
+ */
+export function harness(spec) {
+    return spec;
+}

package/dist/agents/index.d.ts

@@ -8,3 +8,4 @@ export * from "./runtime.js";
 export * from "./agent.js";
 export * from "./home.js";
 export * from "./compaction.js";
+export * from "./loop.js";

package/dist/agents/index.js

@@ -8,3 +8,4 @@ export * from "./runtime.js";
 export * from "./agent.js";
 export * from "./home.js";
 export * from "./compaction.js";
+export * from "./loop.js";

package/dist/agents/loop.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Loop — a live execution of an Agent, and the completion gate that stops it
+ * claiming `done` too early. A layer over the shipped §8 client: nothing here
+ * changes existing behaviour.
+ *
+ * The placement law this encodes:
+ *
+ *   AgentSpec (the harness) answers "MAY it?"    — capability, ceilings. Per problem.
+ *   RunOptions             answers "with WHAT?"  — model for this call.  Per call.
+ *   Loop                   answers "DID it?"     — status, turns.        Observed.
+ *   none of them           answers "is it RIGHT?"— a tool, skill or agent.
+ *
+ * So Loop takes no options: it is read, not configured.
+ */
+import { type ClientOptions, type Hooks, type RunResult } from "../client.js";
+import type { Toolkit } from "../toolkit.js";
+import type { Agent } from "./agent.js";
+/** A POLICY check on a tool call — "may it?", never "is it right?".
+ *  Return `"allow"` (or nothing) to permit; any other string DENIES with that reason. */
+export type Guardrail = (ev: {
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+    turn: number;
+}) => string | undefined | void;
+/** The verdict a completion verifier returns. */
+export interface Verdict {
+    ok: boolean;
+    reason?: string;
+}
+/** The gate that stops an agent claiming `done` before its work verifies. */
+export interface Completion {
+    /** Judges the run. Receives the tool calls ACCUMULATED across attempts. */
+    verify: (result: RunResult) => Verdict | Promise<Verdict>;
+    /** REQUIRED. An unbounded verify loop is a denial-of-service on the caller's bill. */
+    maxAttempts: number;
+}
+/** What varies PER CALL. `model` is here — not on the spec's default and not on the
+ *  Loop — so the same conversation may change model between turns. */
+export interface LoopRunOptions {
+    /** Overrides the agent's model for this call only. Omitted ⇒ the agent's. */
+    model?: string;
+}
+/** What a run reports. `status` reuses the SHIPPED vocabulary — no new status
+ *  strings are minted (SPEC.md pins TaskStatus identical across ports). */
+export interface Outcome {
+    text: string;
+    status: "done" | "incomplete" | "pending" | "error";
+    /** Named whenever `status` is not `done` — never a silent stop. */
+    stoppedBy?: string;
+    attempts: number;
+    turns: number;
+    result?: RunResult;
+}
+/**
+ * Compiles a spec's guardrails into one `beforeTool` with FIRST-DENY-WINS,
+ * composed ahead of any hook the spec already set. No guardrails ⇒ the spec's
+ * hooks are returned untouched, so absent is byte-identical.
+ */
+export declare function guardedHooks(guardrails: Guardrail[] | undefined, hooks: Hooks | undefined): Hooks | undefined;
+/**
+ * The built-in completion verifier. Reads the SHIPPED `todowrite` builtin's
+ * result metadata and requires every item to be checked.
+ *
+ * Structural, not domain: it counts unchecked boxes and never learns what a todo
+ * means, so the loop stays domain-blind. No plan declared ⇒ nothing to verify ⇒
+ * pass, so the gate never punishes an agent that does not use the builtin.
+ */
+export declare function allTodosDone(result: RunResult): Verdict;
+/**
+ * Wraps a client run with the completion gate. SHARED by the standalone Loop and
+ * the §7D runtime turn, so a delegated child gets exactly the same guarantee as a
+ * directly-driven one.
+ *
+ * Rule 2 in force: a run that is `pending` (suspended on a human) or otherwise
+ * non-done already carries its own reason, so the gate never re-judges it. That
+ * keeps `pending` and `incomplete` distinct — the caller can always tell whether
+ * it owes an Answer or a fix.
+ */
+export declare function runGated(ask: (prompt: string) => Promise<RunResult>, prompt: string, completion: Completion | undefined): Promise<RunResult>;
+/** A live execution of an Agent. Its only verbs are `run` and reading state. */
+export declare class Loop {
+    #private;
+    private readonly agent;
+    /** CLIENT OPTIONS rather than a built client, because a per-call `model`
+     *  override must be able to change the model — which is fixed at construction. */
+    private readonly options;
+    private readonly toolkit;
+    constructor(agent: Agent, 
+    /** CLIENT OPTIONS rather than a built client, because a per-call `model`
+     *  override must be able to change the model — which is fixed at construction. */
+    options: ClientOptions, toolkit: Toolkit);
+    /** Observed, never set by the caller. */
+    get status(): string;
+    /** Model round trips this loop has spent. */
+    get turns(): number;
+    run(prompt: string, opts?: LoopRunOptions): Promise<Outcome>;
+}

package/dist/agents/loop.js

@@ -0,0 +1,179 @@
+/**
+ * Loop — a live execution of an Agent, and the completion gate that stops it
+ * claiming `done` too early. A layer over the shipped §8 client: nothing here
+ * changes existing behaviour.
+ *
+ * The placement law this encodes:
+ *
+ *   AgentSpec (the harness) answers "MAY it?"    — capability, ceilings. Per problem.
+ *   RunOptions             answers "with WHAT?"  — model for this call.  Per call.
+ *   Loop                   answers "DID it?"     — status, turns.        Observed.
+ *   none of them           answers "is it RIGHT?"— a tool, skill or agent.
+ *
+ * So Loop takes no options: it is read, not configured.
+ */
+import { createClient } from "../client.js";
+/**
+ * Compiles a spec's guardrails into one `beforeTool` with FIRST-DENY-WINS,
+ * composed ahead of any hook the spec already set. No guardrails ⇒ the spec's
+ * hooks are returned untouched, so absent is byte-identical.
+ */
+export function guardedHooks(guardrails, hooks) {
+    if (!guardrails || guardrails.length === 0)
+        return hooks;
+    const prior = hooks?.beforeTool;
+    return {
+        ...(hooks ?? {}),
+        beforeTool: async (ev) => {
+            for (const g of guardrails) {
+                const verdict = g(ev);
+                if (verdict && verdict !== "allow") {
+                    return { result: { output: `denied: ${verdict}`, isError: true } };
+                }
+            }
+            return prior ? prior(ev) : undefined;
+        },
+    };
+}
+/**
+ * The built-in completion verifier. Reads the SHIPPED `todowrite` builtin's
+ * result metadata and requires every item to be checked.
+ *
+ * Structural, not domain: it counts unchecked boxes and never learns what a todo
+ * means, so the loop stays domain-blind. No plan declared ⇒ nothing to verify ⇒
+ * pass, so the gate never punishes an agent that does not use the builtin.
+ */
+export function allTodosDone(result) {
+    for (let i = result.toolCalls.length - 1; i >= 0; i--) {
+        if (result.toolCalls[i].name !== "todowrite")
+            continue;
+        const todos = result.toolCalls[i].metadata?.todos;
+        if (!Array.isArray(todos))
+            return { ok: true };
+        const open = todos
+            .filter((t) => !t?.completed)
+            .map((t) => String(t?.text ?? ""));
+        return open.length > 0
+            ? { ok: false, reason: `${open.length} item(s) still open: ${open.join("; ")}` }
+            : { ok: true };
+    }
+    return { ok: true };
+}
+/**
+ * Wraps a client run with the completion gate. SHARED by the standalone Loop and
+ * the §7D runtime turn, so a delegated child gets exactly the same guarantee as a
+ * directly-driven one.
+ *
+ * Rule 2 in force: a run that is `pending` (suspended on a human) or otherwise
+ * non-done already carries its own reason, so the gate never re-judges it. That
+ * keeps `pending` and `incomplete` distinct — the caller can always tell whether
+ * it owes an Answer or a fix.
+ */
+export async function runGated(ask, prompt, completion) {
+    if (!completion)
+        return ask(prompt);
+    const { maxAttempts } = completion;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new Error("toolnexus: completion.maxAttempts must be an integer >= 1");
+    }
+    if (typeof completion.verify !== "function") {
+        throw new Error("toolnexus: completion.verify is required");
+    }
+    let accumulated = [];
+    let last;
+    let reason = "";
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const p = attempt === 1 ? prompt : `Your work did not verify: ${reason}. Fix it and finish.`;
+        const r = await ask(p);
+        // The gate judges the ACCUMULATED work, so an agent cannot escape it by
+        // declining to re-declare its plan on a retry.
+        accumulated = [...accumulated, ...r.toolCalls];
+        const judged = { ...r, toolCalls: accumulated };
+        last = judged;
+        if (r.status && r.status !== "done") {
+            // The run stopped for its own reason (suspension, budget). If the gate was
+            // mid-retry the caller must learn BOTH — otherwise a budget stop masks the
+            // verification failure and they never see why it was looping.
+            if (reason && r.status !== "pending") {
+                judged.text = `${r.text} [while verifying: attempt ${attempt} last failed: ${reason}]`;
+            }
+            return judged;
+        }
+        const verdict = await completion.verify(judged);
+        if (verdict.ok)
+            return judged;
+        reason = verdict.reason ?? "unspecified";
+    }
+    // Structured, not prose: `limit` is how a caller (and the §7D runtime) tells
+    // WHICH limit stopped the run. `text` carries the human reason.
+    return {
+        ...last,
+        status: "incomplete",
+        limit: "completion",
+        text: `completion.verify failed ${maxAttempts}×: ${reason}`,
+    };
+}
+/** A live execution of an Agent. Its only verbs are `run` and reading state. */
+export class Loop {
+    agent;
+    options;
+    toolkit;
+    #status = "idle";
+    #turns = 0;
+    constructor(agent, 
+    /** CLIENT OPTIONS rather than a built client, because a per-call `model`
+     *  override must be able to change the model — which is fixed at construction. */
+    options, toolkit) {
+        this.agent = agent;
+        this.options = options;
+        this.toolkit = toolkit;
+    }
+    /** Observed, never set by the caller. */
+    get status() {
+        return this.#status;
+    }
+    /** Model round trips this loop has spent. */
+    get turns() {
+        return this.#turns;
+    }
+    async run(prompt, opts = {}) {
+        const completion = this.agent.spec.completion;
+        const client = createClient(this.#clientOptions(opts));
+        this.#status = "running";
+        let attempts = 0;
+        let history = [];
+        const ask = async (p) => {
+            attempts++;
+            const r = await client.run(p, { toolkit: this.toolkit, history });
+            this.#turns += r.turns;
+            history = r.messages;
+            return r;
+        };
+        try {
+            const r = await runGated(ask, prompt, completion);
+            if (r.status && r.status !== "done") {
+                this.#status = r.status;
+                const stoppedBy = r.limit === "completion" ? r.text : `run reported ${r.status}`;
+                return { text: r.text, status: r.status, stoppedBy, attempts, turns: this.#turns, result: r };
+            }
+            this.#status = "idle";
+            return { text: r.text, status: "done", attempts, turns: this.#turns, result: r };
+        }
+        catch (e) {
+            this.#status = "error";
+            throw e;
+        }
+    }
+    /** Applies a per-call model override via `requestParams` (`model` is not in the
+     *  forbidden set — the client forbids only messages/tools/stream). */
+    #clientOptions(opts) {
+        const base = {
+            ...this.options,
+            systemPrompt: this.agent.spec.soul ?? this.options.systemPrompt,
+            hooks: guardedHooks(this.agent.spec.guardrails, this.agent.spec.hooks ?? this.options.hooks),
+        };
+        if (!opts.model)
+            return base;
+        return { ...base, requestParams: { ...(base.requestParams ?? {}), model: opts.model } };
+    }
+}

package/dist/agents/runtime.d.ts

@@ -15,6 +15,7 @@
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
 import { type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js";
+import { type Completion } from "./loop.js";
 import type { Answer, Request, Tool } from "../types.js";
 /** Injectable time source. All runtime timers, timeouts, and deadlines use it. */
 export interface Clock {
@@ -76,6 +77,10 @@ export interface AgentDef {
     /** §8 observability sink for THIS agent's client. Set ⇒ REPLACES the runtime-wide
      * `onMetric` for this agent. Resolves independently of `hooks`. Forwarded verbatim. */
     onMetric?: (ev: MetricEvent) => void;
+    /** §7D completion gate, projected from the agent spec. Present ⇒ this agent's
+     * turns run through the gate even when it is a DELEGATED child — which is what a
+     * host-side retry loop cannot do. */
+    completion?: Completion;
 }
 /** An unsolicited inbox item. Delivered ONLY as part of a fresh turn's coalesced
  * drain, with provenance rendered per item (non-ancestor senders are untrusted). */

package/dist/agents/runtime.js

@@ -15,6 +15,7 @@
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
 import { createClient, InMemoryConversationStore } from "../client.js";
+import { runGated } from "./loop.js";
 import { createToolkit } from "../toolkit.js";
 import { defineTool } from "../native.js";
 /** The real clock (default). Timers are unref'd so they never hold the process open. */
@@ -584,7 +585,9 @@ export class AgentRuntime {
                 hooks: h.def.hooks ?? this.opts.hooks,
                 onMetric: h.def.onMetric ?? this.opts.onMetric,
             });
-            const r = await client.ask(input, { toolkit, id: h.id, signal: h.abort.signal });
+            // The gate runs HERE, inside the runtime turn, which is what makes it reach a
+            // delegated child: `task` executes the child through this same path.
+            const r = await runGated((p) => client.ask(p, { toolkit, id: h.id, signal: h.abort.signal }), input, h.def.completion);
             h.turnsTotal += r.turns;
             this.rollUp(h, r.usage.totalTokens, r.toolCallCount);
             if (r.status === "pending" && r.pending) {
@@ -604,7 +607,12 @@ export class AgentRuntime {
                 h.state = "idle";
                 h.drained = [];
                 this.t(`${h.id}: running→idle (incomplete: ${r.limit ?? "maxTurns"})`);
-                result = { text: "hit maxTurns without a final answer", isError: true, status: "incomplete", turns: r.turns, totalTokens: r.usage.totalTokens };
+                // A completion stop carries its own reason; only a maxTurns stop gets the
+                // generic sentence. Reading `limit` is how the runtime tells them apart.
+                result = {
+                    text: r.limit === "completion" ? r.text : "hit maxTurns without a final answer",
+                    isError: true, status: "incomplete", turns: r.turns, totalTokens: r.usage.totalTokens,
+                };
             }
             else {
                 h.state = "idle";

package/dist/client.js

@@ -12,6 +12,28 @@ export class InMemoryConversationStore {
     }
 }
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+/** ~68 years; the widest whole-second count all seven ports represent exactly. */
+const RETRY_AFTER_MAX_SECONDS = 2147483647;
+/**
+ * Honour `Retry-After` only in its delay-seconds form: a run of ASCII digits
+ * (RFC 9110 §10.2.3) in 0…2147483647, returned in milliseconds.
+ *
+ * `Number()` is far too permissive for this — it accepts `"0.5"`, `"-5"`, `"1e3"`
+ * and `" "` (as 0), which is how this port came to wait for fractional seconds
+ * that five of the other six rejected outright. Fractional, signed, HTTP-date and
+ * out-of-range values are not delays we can honour, so the caller falls back to
+ * backoff rather than guessing. `0` is a real answer, so it returns `0`, not
+ * `null`, and callers must use `??` rather than `||`.
+ */
+function retryAfterMs(raw) {
+    if (raw == null)
+        return null;
+    const s = raw.trim();
+    if (!/^[0-9]+$/.test(s))
+        return null;
+    const secs = Number(s);
+    return secs <= RETRY_AFTER_MAX_SECONDS ? secs * 1000 : null;
+}
 function delay(ms, signal) {
     return new Promise((resolve, reject) => {
         const t = setTimeout(resolve, ms);
@@ -457,8 +479,9 @@ export class Client {
                 const tier = classify({ status: res.status, attempt, retryable });
                 if (tier === "fail" || attempt === retries)
                     return res; // caller surfaces the non-ok status
-                const ra = Number(res.headers.get("retry-after"));
-                await delay(ra ? ra * 1000 : base * 2 ** attempt + Math.random() * 100, signal);
+                const ra = retryAfterMs(res.headers.get("retry-after"));
+                // `?? `, not `|| `: Retry-After: 0 means "retry now", not "no opinion".
+                await delay(ra ?? base * 2 ** attempt + Math.random() * 100, signal);
             }
             catch (e) {
                 if (signal.aborted)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/home.test.ts test/compaction.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts"
   },
   "keywords": [

package/src/agents/agent.ts

@@ -11,6 +11,9 @@ import fs from "node:fs"
 import { defineTool } from "../native.js"
 import type { Answer, Request, Tool } from "../types.js"
 import { AgentRuntime, isVerbError, type AgentDef, type Budget, type Handle, type RuntimeOptions, type TaskResult } from "./runtime.js"
+import { Loop, guardedHooks, type Completion, type Guardrail } from "./loop.js"
+import type { ClientOptions } from "../client.js"
+import type { Toolkit } from "../toolkit.js"
 
 /** The declarative agent spec (§7D Level-1 surface). */
 export interface AgentSpec {
@@ -38,6 +41,15 @@ export interface AgentSpec {
   /** §8 observability sink for this agent. Set ⇒ replaces the runtime-wide
    * `onMetric` for this agent; resolves independently of `hooks`. */
   onMetric?: AgentDef["onMetric"]
+  /** POLICY checks on tool calls — "may it?", never "is it right?". They compile
+   * into one `beforeTool` with FIRST-DENY-WINS: a later guardrail can never widen
+   * an earlier denial. Composed with `hooks.beforeTool`, which runs only if every
+   * guardrail allows. Empty ⇒ byte-identical. */
+  guardrails?: Guardrail[]
+  /** When set, the gate that stops this agent claiming `done` before its work
+   * verifies. It travels WITH the agent, so a caller that delegates via `task`
+   * inherits it — which a host-side retry loop cannot do. Omitted ⇒ byte-identical. */
+  completion?: Completion
 }
 
 /** Runtime options for a one-shot `run`/`asTool` (the registry is derived). */
@@ -72,13 +84,25 @@ export class Agent {
       waitFor: this.spec.waitFor,
       onSpawn: this.spec.onSpawn,
       onClose: this.spec.onClose,
-      hooks: this.spec.hooks,
+      // Guardrails are compiled into the hook HERE, at the registry boundary, so a
+      // delegated child is governed by them too — not only a directly-driven one.
+      hooks: guardedHooks(this.spec.guardrails, this.spec.hooks),
       onMetric: this.spec.onMetric,
+      completion: this.spec.completion,
     }
     for (const t of this.spec.team ?? []) t.registry(acc)
     return acc
   }
 
+  /**
+   * Open a LIVE EXECUTION of this agent. Takes client OPTIONS rather than a built
+   * client, because a per-call `model` override must be able to change the model —
+   * which is fixed when a client is constructed.
+   */
+  loop(options: ClientOptions, toolkit: Toolkit): Loop {
+    return new Loop(this, options, toolkit)
+  }
+
   /** Build a runtime scoped to this agent's reachable team graph. */
   createRuntime(opts: AgentRunOptions = {}): AgentRuntime {
     return new AgentRuntime({ ...opts, registry: this.registry() })
@@ -135,3 +159,13 @@ export class Agent {
 export function agent(name: string, spec: AgentSpec): Agent {
   return new Agent(name, spec)
 }
+
+/**
+ * `Harness` is a NAME, not a type. An agent spec already IS the harness — tools,
+ * soul, team, budget, model, policy, ceilings — so this is the word landing in the
+ * API without a second concept to learn or migrate to. A spec built through
+ * `harness` and one written inline are indistinguishable.
+ */
+export function harness(spec: AgentSpec): AgentSpec {
+  return spec
+}

package/src/agents/index.ts

@@ -8,3 +8,4 @@ export * from "./runtime.js"
 export * from "./agent.js"
 export * from "./home.js"
 export * from "./compaction.js"
+export * from "./loop.js"

package/src/agents/loop.ts

@@ -0,0 +1,232 @@
+/**
+ * Loop — a live execution of an Agent, and the completion gate that stops it
+ * claiming `done` too early. A layer over the shipped §8 client: nothing here
+ * changes existing behaviour.
+ *
+ * The placement law this encodes:
+ *
+ *   AgentSpec (the harness) answers "MAY it?"    — capability, ceilings. Per problem.
+ *   RunOptions             answers "with WHAT?"  — model for this call.  Per call.
+ *   Loop                   answers "DID it?"     — status, turns.        Observed.
+ *   none of them           answers "is it RIGHT?"— a tool, skill or agent.
+ *
+ * So Loop takes no options: it is read, not configured.
+ */
+import { createClient, type ClientOptions, type Hooks, type RunResult } from "../client.js"
+import type { Toolkit } from "../toolkit.js"
+import type { Agent } from "./agent.js"
+
+/** A POLICY check on a tool call — "may it?", never "is it right?".
+ *  Return `"allow"` (or nothing) to permit; any other string DENIES with that reason. */
+export type Guardrail = (ev: {
+  name: string
+  args: Record<string, unknown>
+  id?: string
+  turn: number
+}) => string | undefined | void
+
+/** The verdict a completion verifier returns. */
+export interface Verdict {
+  ok: boolean
+  reason?: string
+}
+
+/** The gate that stops an agent claiming `done` before its work verifies. */
+export interface Completion {
+  /** Judges the run. Receives the tool calls ACCUMULATED across attempts. */
+  verify: (result: RunResult) => Verdict | Promise<Verdict>
+  /** REQUIRED. An unbounded verify loop is a denial-of-service on the caller's bill. */
+  maxAttempts: number
+}
+
+/** What varies PER CALL. `model` is here — not on the spec's default and not on the
+ *  Loop — so the same conversation may change model between turns. */
+export interface LoopRunOptions {
+  /** Overrides the agent's model for this call only. Omitted ⇒ the agent's. */
+  model?: string
+}
+
+/** What a run reports. `status` reuses the SHIPPED vocabulary — no new status
+ *  strings are minted (SPEC.md pins TaskStatus identical across ports). */
+export interface Outcome {
+  text: string
+  status: "done" | "incomplete" | "pending" | "error"
+  /** Named whenever `status` is not `done` — never a silent stop. */
+  stoppedBy?: string
+  attempts: number
+  turns: number
+  result?: RunResult
+}
+
+/**
+ * Compiles a spec's guardrails into one `beforeTool` with FIRST-DENY-WINS,
+ * composed ahead of any hook the spec already set. No guardrails ⇒ the spec's
+ * hooks are returned untouched, so absent is byte-identical.
+ */
+export function guardedHooks(guardrails: Guardrail[] | undefined, hooks: Hooks | undefined): Hooks | undefined {
+  if (!guardrails || guardrails.length === 0) return hooks
+  const prior = hooks?.beforeTool
+  return {
+    ...(hooks ?? {}),
+    beforeTool: async (ev) => {
+      for (const g of guardrails) {
+        const verdict = g(ev)
+        if (verdict && verdict !== "allow") {
+          return { result: { output: `denied: ${verdict}`, isError: true } }
+        }
+      }
+      return prior ? prior(ev) : undefined
+    },
+  }
+}
+
+/**
+ * The built-in completion verifier. Reads the SHIPPED `todowrite` builtin's
+ * result metadata and requires every item to be checked.
+ *
+ * Structural, not domain: it counts unchecked boxes and never learns what a todo
+ * means, so the loop stays domain-blind. No plan declared ⇒ nothing to verify ⇒
+ * pass, so the gate never punishes an agent that does not use the builtin.
+ */
+export function allTodosDone(result: RunResult): Verdict {
+  for (let i = result.toolCalls.length - 1; i >= 0; i--) {
+    if (result.toolCalls[i].name !== "todowrite") continue
+    const todos = result.toolCalls[i].metadata?.todos
+    if (!Array.isArray(todos)) return { ok: true }
+    const open = todos
+      .filter((t: any) => !t?.completed)
+      .map((t: any) => String(t?.text ?? ""))
+    return open.length > 0
+      ? { ok: false, reason: `${open.length} item(s) still open: ${open.join("; ")}` }
+      : { ok: true }
+  }
+  return { ok: true }
+}
+
+/**
+ * Wraps a client run with the completion gate. SHARED by the standalone Loop and
+ * the §7D runtime turn, so a delegated child gets exactly the same guarantee as a
+ * directly-driven one.
+ *
+ * Rule 2 in force: a run that is `pending` (suspended on a human) or otherwise
+ * non-done already carries its own reason, so the gate never re-judges it. That
+ * keeps `pending` and `incomplete` distinct — the caller can always tell whether
+ * it owes an Answer or a fix.
+ */
+export async function runGated(
+  ask: (prompt: string) => Promise<RunResult>,
+  prompt: string,
+  completion: Completion | undefined,
+): Promise<RunResult> {
+  if (!completion) return ask(prompt)
+  const { maxAttempts } = completion
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new Error("toolnexus: completion.maxAttempts must be an integer >= 1")
+  }
+  if (typeof completion.verify !== "function") {
+    throw new Error("toolnexus: completion.verify is required")
+  }
+
+  let accumulated: RunResult["toolCalls"] = []
+  let last: RunResult | undefined
+  let reason = ""
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const p = attempt === 1 ? prompt : `Your work did not verify: ${reason}. Fix it and finish.`
+    const r = await ask(p)
+    // The gate judges the ACCUMULATED work, so an agent cannot escape it by
+    // declining to re-declare its plan on a retry.
+    accumulated = [...accumulated, ...r.toolCalls]
+    const judged: RunResult = { ...r, toolCalls: accumulated }
+    last = judged
+
+    if (r.status && r.status !== "done") {
+      // The run stopped for its own reason (suspension, budget). If the gate was
+      // mid-retry the caller must learn BOTH — otherwise a budget stop masks the
+      // verification failure and they never see why it was looping.
+      if (reason && r.status !== "pending") {
+        judged.text = `${r.text} [while verifying: attempt ${attempt} last failed: ${reason}]`
+      }
+      return judged
+    }
+
+    const verdict = await completion.verify(judged)
+    if (verdict.ok) return judged
+    reason = verdict.reason ?? "unspecified"
+  }
+
+  // Structured, not prose: `limit` is how a caller (and the §7D runtime) tells
+  // WHICH limit stopped the run. `text` carries the human reason.
+  return {
+    ...(last as RunResult),
+    status: "incomplete",
+    limit: "completion",
+    text: `completion.verify failed ${maxAttempts}×: ${reason}`,
+  }
+}
+
+/** A live execution of an Agent. Its only verbs are `run` and reading state. */
+export class Loop {
+  #status: Outcome["status"] | "idle" | "running" = "idle"
+  #turns = 0
+
+  constructor(
+    private readonly agent: Agent,
+    /** CLIENT OPTIONS rather than a built client, because a per-call `model`
+     *  override must be able to change the model — which is fixed at construction. */
+    private readonly options: ClientOptions,
+    private readonly toolkit: Toolkit,
+  ) {}
+
+  /** Observed, never set by the caller. */
+  get status(): string {
+    return this.#status
+  }
+
+  /** Model round trips this loop has spent. */
+  get turns(): number {
+    return this.#turns
+  }
+
+  async run(prompt: string, opts: LoopRunOptions = {}): Promise<Outcome> {
+    const completion = this.agent.spec.completion
+    const client = createClient(this.#clientOptions(opts))
+    this.#status = "running"
+
+    let attempts = 0
+    let history: any[] = []
+    const ask = async (p: string): Promise<RunResult> => {
+      attempts++
+      const r = await client.run(p, { toolkit: this.toolkit, history })
+      this.#turns += r.turns
+      history = r.messages
+      return r
+    }
+
+    try {
+      const r = await runGated(ask, prompt, completion)
+      if (r.status && r.status !== "done") {
+        this.#status = r.status as Outcome["status"]
+        const stoppedBy =
+          r.limit === "completion" ? r.text : `run reported ${r.status}`
+        return { text: r.text, status: r.status as Outcome["status"], stoppedBy, attempts, turns: this.#turns, result: r }
+      }
+      this.#status = "idle"
+      return { text: r.text, status: "done", attempts, turns: this.#turns, result: r }
+    } catch (e) {
+      this.#status = "error"
+      throw e
+    }
+  }
+
+  /** Applies a per-call model override via `requestParams` (`model` is not in the
+   *  forbidden set — the client forbids only messages/tools/stream). */
+  #clientOptions(opts: LoopRunOptions): ClientOptions {
+    const base: ClientOptions = {
+      ...this.options,
+      systemPrompt: this.agent.spec.soul ?? this.options.systemPrompt,
+      hooks: guardedHooks(this.agent.spec.guardrails, this.agent.spec.hooks ?? this.options.hooks),
+    }
+    if (!opts.model) return base
+    return { ...base, requestParams: { ...(base.requestParams ?? {}), model: opts.model } }
+  }
+}

package/src/agents/runtime.ts

@@ -15,6 +15,7 @@
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
 import { createClient, InMemoryConversationStore, type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js"
+import { runGated, type Completion } from "./loop.js"
 import { createToolkit, type Toolkit } from "../toolkit.js"
 import { defineTool } from "../native.js"
 import type { Answer, Request, Tool, ToolResult } from "../types.js"
@@ -98,6 +99,10 @@ export interface AgentDef {
   /** §8 observability sink for THIS agent's client. Set ⇒ REPLACES the runtime-wide
    * `onMetric` for this agent. Resolves independently of `hooks`. Forwarded verbatim. */
   onMetric?: (ev: MetricEvent) => void
+  /** §7D completion gate, projected from the agent spec. Present ⇒ this agent's
+   * turns run through the gate even when it is a DELEGATED child — which is what a
+   * host-side retry loop cannot do. */
+  completion?: Completion
 }
 
 /** An unsolicited inbox item. Delivered ONLY as part of a fresh turn's coalesced
@@ -768,7 +773,13 @@ export class AgentRuntime {
         hooks: h.def.hooks ?? this.opts.hooks,
         onMetric: h.def.onMetric ?? this.opts.onMetric,
       })
-      const r = await client.ask(input, { toolkit, id: h.id, signal: h.abort!.signal })
+      // The gate runs HERE, inside the runtime turn, which is what makes it reach a
+      // delegated child: `task` executes the child through this same path.
+      const r = await runGated(
+        (p) => client.ask(p, { toolkit, id: h.id, signal: h.abort!.signal }),
+        input,
+        h.def.completion,
+      )
       h.turnsTotal += r.turns
       this.rollUp(h, r.usage.totalTokens, r.toolCallCount)
       if (r.status === "pending" && r.pending) {
@@ -787,7 +798,12 @@ export class AgentRuntime {
         h.state = "idle"
         h.drained = []
         this.t(`${h.id}: running→idle (incomplete: ${r.limit ?? "maxTurns"})`)
-        result = { text: "hit maxTurns without a final answer", isError: true, status: "incomplete", turns: r.turns, totalTokens: r.usage.totalTokens }
+        // A completion stop carries its own reason; only a maxTurns stop gets the
+        // generic sentence. Reading `limit` is how the runtime tells them apart.
+        result = {
+          text: r.limit === "completion" ? r.text : "hit maxTurns without a final answer",
+          isError: true, status: "incomplete", turns: r.turns, totalTokens: r.usage.totalTokens,
+        }
       } else {
         h.state = "idle"
         h.drained = []

package/src/client.ts

@@ -114,6 +114,28 @@ export class InMemoryConversationStore implements ConversationStore {
 
 const RETRYABLE = new Set([429, 500, 502, 503, 504])
 
+/** ~68 years; the widest whole-second count all seven ports represent exactly. */
+const RETRY_AFTER_MAX_SECONDS = 2147483647
+
+/**
+ * Honour `Retry-After` only in its delay-seconds form: a run of ASCII digits
+ * (RFC 9110 §10.2.3) in 0…2147483647, returned in milliseconds.
+ *
+ * `Number()` is far too permissive for this — it accepts `"0.5"`, `"-5"`, `"1e3"`
+ * and `" "` (as 0), which is how this port came to wait for fractional seconds
+ * that five of the other six rejected outright. Fractional, signed, HTTP-date and
+ * out-of-range values are not delays we can honour, so the caller falls back to
+ * backoff rather than guessing. `0` is a real answer, so it returns `0`, not
+ * `null`, and callers must use `??` rather than `||`.
+ */
+function retryAfterMs(raw: string | null | undefined): number | null {
+  if (raw == null) return null
+  const s = raw.trim()
+  if (!/^[0-9]+$/.test(s)) return null
+  const secs = Number(s)
+  return secs <= RETRY_AFTER_MAX_SECONDS ? secs * 1000 : null
+}
+
 function delay(ms: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     const t = setTimeout(resolve, ms)
@@ -643,8 +665,9 @@ export class Client {
         const retryable = RETRYABLE.has(res.status)
         const tier = classify({ status: res.status, attempt, retryable })
         if (tier === "fail" || attempt === retries) return res // caller surfaces the non-ok status
-        const ra = Number(res.headers.get("retry-after"))
-        await delay(ra ? ra * 1000 : base * 2 ** attempt + Math.random() * 100, signal)
+        const ra = retryAfterMs(res.headers.get("retry-after"))
+        // `?? `, not `|| `: Retry-After: 0 means "retry now", not "no opinion".
+        await delay(ra ?? base * 2 ** attempt + Math.random() * 100, signal)
       } catch (e) {
         if (signal.aborted) throw e // abort/timeout: don't retry
         lastErr = e