@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/loop.mjs

@@ -0,0 +1,560 @@
+/**
+ * lib/engine/loop.mjs — the agent loop.
+ *
+ * One run = model turn → (tool calls → tool results → model turn)* → answer.
+ *
+ * The loop owns ordering and stopping; it owns no I/O of its own. The model is
+ * an injected `callModel` (see `wire/index.mjs`) and tools are injected tool
+ * objects (see `tools/index.mjs`), so the whole loop runs in a test with a
+ * scripted fake model and no network.
+ *
+ * What it guarantees:
+ *   · Stop conditions are a union (`LoopStop`): completed | max_turns |
+ *     wall_clock | aborted | wire_error | loop_detected. Exactly one ends a run.
+ *   · Every assistant `tool_use` is answered by a `tool_result` before the next
+ *     model call or the end of the run, so the transcript is always resumable.
+ *   · Read-only tool calls that arrive together run in parallel (bounded);
+ *     anything that can mutate runs alone, in the order the model gave.
+ *   · Tool-argument JSON that did not parse gets one repair pass; a repaired
+ *     call is written back into the assistant message as valid JSON.
+ *   · The same call (tool + identical input) made turn after turn is flagged in
+ *     its result at `loopWarnAt` and ends the run at `loopStopAt`.
+ *   · A tool that THROWS (a defect in the tool) becomes an error result; one
+ *     buggy tool must not take down a seat's run.
+ *   · A turn that stopped at the output token limit (`stopReason max_tokens`)
+ *     runs none of its tool calls — a cut-off call can be "repaired" into a
+ *     valid one that silently lost its trailing fields — and asks for a resend.
+ *   · `costMicros` is exact or null: a request that failed after the gateway
+ *     accepted it may be billed with no figure, so it nulls the sum.
+ *   · The wall-clock timer and the outer abort listener are released even when
+ *     a defect throws out of the loop.
+ *   · With a `guard` (guard.mjs), no tool runs until permissions, in-process
+ *     gates and PreToolUse hooks have passed it; a refusal is the call's error
+ *     result. A guard that throws refuses the call (fail closed).
+ *   · MCP tools (`passthroughInput`) get their input checked for shape and
+ *     required keys only, and forwarded unchanged.
+ *   · With `onStop`, a Stop hook that asks for more work turns a finished run
+ *     into another turn, its reason sent as the next user message.
+ *   · With `context` (context/manager.mjs), each turn boundary may replace the
+ *     history (compaction), append user messages, and change the tools that
+ *     are sent (deferred loading, MCP list changes); text it returns after a
+ *     batch is appended to the tool-results message. Model calls made on the
+ *     run's behalf outside the turn loop (a compaction summary, WebFetch,
+ *     WebSearch) are reported through `toolContext.recordModelCall` and join
+ *     the run's usage, request ids and cost exactly like turns do.
+ *
+ * The pure decisions (`planBatches`, `nextStreaks`, `repairToolUses`,
+ * `failureMayBeBilled`) are exported and tested on their own.
+ *
+ * @module lib/engine/loop
+ */
+
+import { toolUses, messageText, stableStringify, userText } from "./messages.mjs";
+import { validateInput, repairToolJson } from "./tools/schema.mjs";
+import { toolDefinitions } from "./tools/index.mjs";
+import { emptyUsage, addUsage, readFrameUsage } from "./wire/usage.mjs";
+
+/**
+ * @typedef {{kind:'completed'} | {kind:'max_turns', maxTurns:number} | {kind:'wall_clock', wallClockMs:number}
+ *   | {kind:'aborted'} | {kind:'wire_error', error:any} | {kind:'loop_detected', tool:string, repeats:number}
+ *   | {kind:'hook_stopped', reason:string} | {kind:'max_budget', maxBudgetUsd:number, spentMicros:string}} LoopStop
+ */
+
+export const DEFAULTS = Object.freeze({
+  maxTurns: 50,
+  wallClockMs: 30 * 60_000,
+  maxParallel: 8,
+  loopWarnAt: 3,
+  loopStopAt: 5,
+  maxToolResultChars: 100_000,
+});
+
+/**
+ * Group tool calls into execution batches: runs of consecutive read-only calls
+ * (at most `maxParallel` each) run together; every other call is its own batch.
+ * @param {Array<{name:string}>} calls
+ * @param {(name:string) => boolean} isReadOnly
+ * @param {number} maxParallel
+ * @returns {number[][]} batches of indices into `calls`, in order
+ */
+export function planBatches(calls, isReadOnly, maxParallel) {
+  const batches = [];
+  let current = [];
+  calls.forEach((c, i) => {
+    if (isReadOnly(c.name)) {
+      if (current.length >= maxParallel) {
+        batches.push(current);
+        current = [];
+      }
+      current.push(i);
+    } else {
+      if (current.length > 0) batches.push(current);
+      current = [];
+      batches.push([i]);
+    }
+  });
+  if (current.length > 0) batches.push(current);
+  return batches;
+}
+
+/**
+ * Consecutive-turn streaks per call signature. A signature absent from this
+ * turn resets to zero (it is simply not carried forward).
+ * @param {Map<string, number>} prev
+ * @param {string[]} signatures  this turn's call signatures
+ * @returns {Map<string, number>}
+ */
+export function nextStreaks(prev, signatures) {
+  const next = new Map();
+  for (const s of new Set(signatures)) next.set(s, (prev.get(s) ?? 0) + 1);
+  return next;
+}
+
+/** @param {{name:string, input:unknown}} call */
+export function callSignature(call) {
+  return `${call.name}:${stableStringify(call.input ?? {})}`;
+}
+
+/**
+ * Repair unparseable tool arguments in an assistant message.
+ * @param {{role:string, content:any[]}} message
+ * @returns {{ message: {role:string, content:any[]}, unrepaired: Map<string, string> }}
+ *   `unrepaired` maps tool_use id → the parse error to report back.
+ */
+export function repairToolUses(message) {
+  const unrepaired = new Map();
+  const content = message.content.map((b) => {
+    if (b.type !== "tool_use" || !b.inputError) return b;
+    const r = repairToolJson(b.rawInput ?? "");
+    if (r.ok) return { type: "tool_use", id: b.id, name: b.name, input: r.value };
+    unrepaired.set(b.id, b.inputError);
+    return b;
+  });
+  return { message: { ...message, content }, unrepaired };
+}
+
+/**
+ * @param {object} p
+ * @param {(turn:{system:string, messages:any[], tools:any[], signal:AbortSignal}) => Promise<any>} p.callModel
+ * @param {string} p.system
+ * @param {any[]} p.messages          full history INCLUDING the new user prompt
+ * @param {import('./tools/index.mjs').Tool[]} p.tools
+ * @param {import('./tools/index.mjs').ToolContext} p.toolContext  its `signal` is replaced by the run's
+ * @param {number} [p.maxTurns]
+ * @param {number} [p.wallClockMs]
+ * @param {AbortSignal} [p.signal]
+ * @param {() => number} [p.now]
+ * @param {(message:any) => void} [p.onMessage]  called for every message the run appends
+ * @param {number} [p.maxParallel]
+ * @param {number} [p.loopWarnAt]
+ * @param {number} [p.loopStopAt]
+ * @param {number} [p.maxToolResultChars]
+ * @param {ReturnType<typeof import('./guard.mjs').createToolGuard>|null} [p.guard]
+ * @param {(s:{stopHookActive:boolean}) => Promise<{continueWith:string|null}|null>} [p.onStop]
+ * @param {() => string[]} [p.drainNotifications]  before each model call: messages to add as user turns
+ * @param {(signal:AbortSignal) => Promise<string[]>} [p.awaitNotifications]  when the model has finished:
+ *   waits for pending background work; a non-empty answer continues the run with those messages
+ * @param {{beforeTurn:(t:{system:string, messages:any[], signal:AbortSignal, recordModelCall:(res:any)=>void})=>Promise<{messages?:any[], append?:any[], tools?:any[], definitions?:any[]}|null>,
+ *          observe?:(o:{system:string, messages:any[], tools:any[], res:any})=>void,
+ *          afterTools?:(o:{calls:any[], results:any[], signal:AbortSignal})=>Promise<any[]|null>}|null} [p.context]
+ */
+export async function runLoop(p) {
+  const maxTurns = p.maxTurns ?? DEFAULTS.maxTurns;
+  const wallClockMs = p.wallClockMs ?? DEFAULTS.wallClockMs;
+  const maxParallel = p.maxParallel ?? DEFAULTS.maxParallel;
+  const loopWarnAt = p.loopWarnAt ?? DEFAULTS.loopWarnAt;
+  const loopStopAt = p.loopStopAt ?? DEFAULTS.loopStopAt;
+  const maxChars = p.maxToolResultChars ?? DEFAULTS.maxToolResultChars;
+  const now = p.now || Date.now;
+  const onMessage = p.onMessage || (() => {});
+
+  const messages = [...p.messages];
+  const newMessages = [];
+  const append = (m) => {
+    messages.push(m);
+    newMessages.push(m);
+    onMessage(m);
+  };
+
+  // One controller for the run: tripped by the caller's signal or the clock.
+  const controller = new AbortController();
+  let wallClockHit = false;
+  const timer = setTimeout(() => {
+    wallClockHit = true;
+    controller.abort();
+  }, wallClockMs);
+  const onOuterAbort = () => controller.abort();
+  if (p.signal?.aborted) controller.abort();
+  else p.signal?.addEventListener("abort", onOuterAbort, { once: true });
+  const signal = controller.signal;
+
+  // The timer and the outer listener are released however the run ends —
+  // including a defect that throws out of callModel, onMessage or a tool
+  // executor. A leaked 30-minute timer would hold the CLI process open.
+  try {
+    return await runTurns(p, {
+      signal,
+      append,
+      messages,
+      newMessages,
+      maxTurns,
+      wallClockMs,
+      maxParallel,
+      loopWarnAt,
+      loopStopAt,
+      maxChars,
+      isWallClock: () => wallClockHit,
+    });
+  } finally {
+    clearTimeout(timer);
+    p.signal?.removeEventListener("abort", onOuterAbort);
+  }
+}
+
+/**
+ * Did a failed model request possibly reach billing? Only a refusal the
+ * gateway answered BEFORE accepting the request (a non-2xx status) is known to
+ * be free. A failure after acceptance (`accepted:true` — a broken stream, an
+ * in-stream error, an abort mid-relay) or a transport fault with no status (the
+ * request may have been admitted before the socket died) may be billed, so the
+ * run's cost sum is no longer exact.
+ * @param {{accepted?:boolean, error?:{status?:number|null}}} res
+ */
+export function failureMayBeBilled(res) {
+  return res.accepted === true || res.error?.status == null;
+}
+
+/**
+ * The body of `runLoop`, separated so its caller can release the run's timer
+ * and listener in one `finally`.
+ * @param {Parameters<typeof runLoop>[0]} p
+ * @param {any} r
+ */
+async function runTurns(p, r) {
+  const { signal, append, messages, newMessages, maxTurns, wallClockMs, maxParallel, loopWarnAt, loopStopAt, maxChars } = r;
+  let toolsList = p.tools;
+  let toolsByName = new Map(toolsList.map((t) => [t.name, t]));
+  let defs = toolDefinitions(toolsList);
+  const ctx = { ...p.toolContext, signal };
+
+  let usage = emptyUsage("provider");
+  // CF-158: the gateway's OWN usage, off the terminal `event: cohort` frame,
+  // summed over this loop's requests. Deliberately a SECOND accumulator: it is
+  // the gateway's view of the same turns, near-equal to `usage` but not the
+  // same number, and conflating the two under one name is the CF-158 defect.
+  // Stays null while no frame reports any, so "not reported" ≠ "zero".
+  let gatewayUsage = null;
+  const requestIds = [];
+  let costTotal = 0n;
+  let costComplete = true;
+  let quota = null;
+  let modelTier = null;
+  let model = null;
+  let apiMs = 0;
+  let numTurns = 0;
+  let streaks = new Map();
+  let lastText = "";
+  let stopHookActive = false;
+  const guard = p.guard ?? null;
+
+  /**
+   * The model gave no tool calls. Ask the Stop hooks whether the run may end.
+   * @returns {Promise<LoopStop|null>} null = continue with another turn
+   */
+  const finishOrContinue = async () => {
+    // Background work still running (agents/runtime.mjs): its report becomes
+    // the next user message instead of the run ending without it.
+    if (p.awaitNotifications && !signal.aborted) {
+      const notes = await p.awaitNotifications(signal);
+      if (signal.aborted) return interrupted();
+      if (notes.length > 0) {
+        for (const n of notes) append(userText(n));
+        if (numTurns >= maxTurns) return { kind: "max_turns", maxTurns };
+        return null;
+      }
+    }
+    if (!p.onStop || signal.aborted) return { kind: "completed" };
+    const s = await p.onStop({ stopHookActive });
+    if (!s?.continueWith) return { kind: "completed" };
+    stopHookActive = true;
+    append(userText(`Before finishing, a Stop hook asked for more:\n${s.continueWith}`));
+    if (numTurns >= maxTurns) return { kind: "max_turns", maxTurns };
+    return null;
+  };
+
+  /** @param {LoopStop} stop */
+  const done = (stop) => {
+    return {
+      stop,
+      messages,
+      newMessages,
+      resultText: lastText,
+      numTurns,
+      usage,
+      // The gateway's own per-request counts (CF-158), or null if it reported
+      // none. Never merged into `usage` — that would double-count every turn.
+      gatewayUsage,
+      requestIds,
+      costMicros: costComplete && numTurns > 0 ? costTotal.toString() : null,
+      // false when a request may have been billed with no figure; a run with no
+      // turn and costComplete true was never billed (agents/usage.mjs).
+      costComplete,
+      quota,
+      modelTier,
+      model,
+      apiMs,
+    };
+  };
+  const interrupted = () => (r.isWallClock() ? { kind: "wall_clock", wallClockMs } : { kind: "aborted" });
+  // W4-E1 (row 24): a spend cap shared with the run's subagents (budget.mjs). Asked before
+  // every model call this loop makes; the tool results of the last turn are always finished.
+  const budget = p.budget ?? null;
+  const overBudget = () =>
+    budget && budget.exhausted() ? { kind: "max_budget", maxBudgetUsd: Number(budget.maxMicros) / 1e6, spentMicros: budget.spentMicros().toString() } : null;
+
+  /**
+   * Fold one gateway request into the run's accounting. `turn` is false for a
+   * request made on the run's behalf outside the turn loop (it counts toward
+   * usage, request ids and cost, but not turns, and does not name the tier).
+   * @param {any} res @param {boolean} turn
+   */
+  const account = (res, turn) => {
+    budget?.record(res);
+    apiMs += res.apiMs ?? 0;
+    if (res.cohort) {
+      if (res.cohort.requestId) requestIds.push(res.cohort.requestId);
+      if (turn && res.cohort.modelTier) modelTier = res.cohort.modelTier;
+      if (turn && hasQuota(res.cohort.quota)) quota = res.cohort.quota;
+      // CF-158. Read through readFrameUsage again even though the wire already
+      // normalised it: this accumulator must never take a malformed object from
+      // a future call site, and an unusable one leaves the total untouched
+      // rather than adding zeros.
+      const gu = readFrameUsage(res.cohort.usage);
+      if (gu) gatewayUsage = addUsage(gatewayUsage ?? emptyUsage("provider"), gu);
+    }
+    if (!res.ok) {
+      // A request that may have been billed has no cost figure, so the sum of
+      // the earlier turns would under-report the run: report no total instead.
+      if (failureMayBeBilled(res)) costComplete = false;
+      return;
+    }
+    if (res.value?.usage) usage = addUsage(usage, res.value.usage);
+    if (turn && res.value?.model) model = res.value.model;
+    if (res.cohort?.costMicros != null) costTotal += BigInt(res.cohort.costMicros);
+    else costComplete = false;
+  };
+  ctx.recordModelCall = (/** @type any */ res) => {
+    if (res && typeof res === "object") account(res, false);
+  };
+
+  for (;;) {
+    if (signal.aborted) return done(interrupted());
+    // Background tasks that ended since the last turn report as user messages
+    // (before the context manager measures the request, so they count toward it).
+    for (const n of p.drainNotifications?.() ?? []) append(userText(n));
+    {
+      const spent = overBudget();
+      if (spent) return done(spent);
+    }
+
+    if (p.context) {
+      const prep = await p.context.beforeTurn({ system: p.system, messages, signal, recordModelCall: ctx.recordModelCall });
+      if (prep?.messages) messages.splice(0, messages.length, ...prep.messages);
+      for (const m of prep?.append ?? []) append(m);
+      if (prep?.tools && prep.tools !== toolsList) {
+        toolsList = prep.tools;
+        toolsByName = new Map(toolsList.map((t) => [t.name, t]));
+      }
+      defs = prep?.definitions ?? toolDefinitions(toolsList);
+      if (signal.aborted) return done(interrupted());
+      // A compaction summary is a model call too: it may have spent the rest.
+      const spent = overBudget();
+      if (spent) return done(spent);
+    }
+
+    const res = await p.callModel({ system: p.system, messages, tools: defs, signal });
+    p.context?.observe?.({ system: p.system, messages, tools: defs, res });
+    account(res, true);
+    if (!res.ok) {
+      if (res.error?.kind === "aborted" || signal.aborted) return done(interrupted());
+      return done({ kind: "wire_error", error: res.error });
+    }
+    numTurns++;
+
+    // Output cut off by the token limit: any tool call in this turn may be
+    // missing trailing fields (a `replace_all`, a `timeout`) that bracket repair
+    // would silently drop. Nothing runs; the model is asked to resend.
+    if (res.value.stopReason === "max_tokens") {
+      const message = res.value.message;
+      append(message);
+      const text = messageText(message);
+      if (text !== "") lastText = text;
+      const calls = toolUses(message);
+      if (calls.length === 0) {
+        const stop = await finishOrContinue();
+        if (stop) return done(stop);
+        continue;
+      }
+      streaks = nextStreaks(streaks, []);
+      append({ role: "user", content: calls.map((c) => errorResult(c.id, TRUNCATED_CALL)) });
+      if (signal.aborted) return done(interrupted());
+      if (numTurns >= maxTurns) return done({ kind: "max_turns", maxTurns });
+      continue;
+    }
+
+    const { message, unrepaired } = repairToolUses(res.value.message);
+    append(message);
+    const text = messageText(message);
+    if (text !== "") lastText = text;
+
+    const calls = toolUses(message);
+    if (calls.length === 0) {
+      const stop = await finishOrContinue();
+      if (stop) return done(stop);
+      continue;
+    }
+
+    streaks = nextStreaks(streaks, calls.filter((c) => !unrepaired.has(c.id)).map(callSignature));
+    const worst = calls.reduce(
+      (acc, c) => {
+        const n = unrepaired.has(c.id) ? 0 : streaks.get(callSignature(c)) ?? 0;
+        return n > acc.n ? { n, tool: c.name } : acc;
+      },
+      { n: 0, tool: "" },
+    );
+
+    /** @type {Array<{type:'tool_result', tool_use_id:string, content:string, is_error?:boolean}>} */
+    const results = new Array(calls.length);
+    if (worst.n >= loopStopAt) {
+      calls.forEach((c, i) => {
+        results[i] = errorResult(c.id, "Not run: this exact call was repeated too many times in a row and the run was stopped.");
+      });
+      append({ role: "user", content: results });
+      return done({ kind: "loop_detected", tool: worst.tool, repeats: worst.n });
+    }
+
+    for (const batch of planBatches(calls, (n) => Boolean(toolsByName.get(n)?.readOnly), maxParallel)) {
+      await Promise.all(
+        batch.map(async (i) => {
+          const c = calls[i];
+          const r = await executeCall(c, unrepaired.get(c.id), toolsByName, ctx, signal, guard);
+          const streak = unrepaired.has(c.id) ? 0 : streaks.get(callSignature(c)) ?? 0;
+          const note =
+            streak >= loopWarnAt
+              ? `\n\n[This identical call has now been made ${streak} times in a row. The result will not change; try a different approach.]`
+              : "";
+          const body = clip((r.ok ? r.content : r.error) + note, maxChars);
+          const images = r.ok && Array.isArray(/** @type any */ (r).images) && /** @type any */ (r).images.length > 0 ? /** @type any */ (r).images : null;
+          results[i] = r.ok ? { type: "tool_result", tool_use_id: c.id, content: body, ...(images ? { images } : {}) } : errorResult(c.id, body);
+        }),
+      );
+    }
+    const extra = p.context?.afterTools ? await p.context.afterTools({ calls, results, signal }) : null;
+    append({ role: "user", content: extra && extra.length > 0 ? [...results, ...extra] : results });
+
+    if (signal.aborted) return done(interrupted());
+    if (guard?.stopReason) return done({ kind: "hook_stopped", reason: guard.stopReason });
+    if (numTurns >= maxTurns) return done({ kind: "max_turns", maxTurns });
+  }
+}
+
+/**
+ * The input check for a tool whose schema belongs to someone else (an MCP
+ * server): an object carrying its required keys, forwarded unchanged.
+ * @param {any} schema @param {unknown} input
+ * @returns {{ok:true, value:Record<string,unknown>}|{ok:false, error:string}}
+ */
+export function checkPassthroughInput(schema, input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return { ok: false, error: "input must be a JSON object" };
+  const missing = (Array.isArray(schema?.required) ? schema.required : []).filter((k) => /** @type any */ (input)[k] === undefined || /** @type any */ (input)[k] === null);
+  if (missing.length > 0) return { ok: false, error: missing.map((k) => `missing required parameter "${k}"`).join("; ") };
+  return { ok: true, value: /** @type any */ (input) };
+}
+
+export const TRUNCATED_CALL =
+  "Not run: your response reached the output token limit while this tool call was being written, so its arguments may be incomplete. " +
+  "Send the call again with shorter arguments; split large content across several calls.";
+
+/** @param {any} q */
+function hasQuota(q) {
+  return Boolean(q && (Object.keys(q.windows || {}).length > 0 || q.creditsRemainingMicros != null || q.funding != null));
+}
+
+/** @param {string} id @param {string} content */
+function errorResult(id, content) {
+  return { type: "tool_result", tool_use_id: id, content, is_error: true };
+}
+
+/** @param {string} s @param {number} max */
+function clip(s, max) {
+  return s.length <= max ? s : `${s.slice(0, max)}\n… [tool result truncated at ${max} characters]`;
+}
+
+/**
+ * @param {{id:string, name:string, input:any}} call
+ * @param {string|undefined} parseError
+ * @param {Map<string, import('./tools/index.mjs').Tool>} toolsByName
+ * @param {import('./tools/index.mjs').ToolContext} ctx
+ * @param {AbortSignal} signal
+ * @param {ReturnType<typeof import('./guard.mjs').createToolGuard>|null} guard
+ * @returns {Promise<{ok:true, content:string}|{ok:false, error:string}>}
+ */
+async function executeCall(call, parseError, toolsByName, ctx, signal, guard) {
+  if (parseError !== undefined) {
+    return {
+      ok: false,
+      error: `The arguments for ${call.name} were not valid JSON (${parseError}). Send the call again with a JSON object that matches the tool's schema.`,
+    };
+  }
+  const tool = toolsByName.get(call.name);
+  if (!tool) {
+    return { ok: false, error: `There is no tool named "${call.name}". Available tools: ${[...toolsByName.keys()].join(", ") || "none"}.` };
+  }
+  if (signal.aborted) return { ok: false, error: "Not run: the run was interrupted." };
+  const check = (/** @type unknown */ input) => (/** @type any */ (tool).passthroughInput ? checkPassthroughInput(tool.input_schema, input) : validateInput(tool.input_schema, input));
+  const v = check(call.input);
+  if (!v.ok) return { ok: false, error: `Invalid input for ${tool.name}: ${v.error}.` };
+
+  let input = v.value;
+  let hookContext = null;
+  if (guard) {
+    let g;
+    try {
+      g = await guard.before({ call, tool, input, signal });
+    } catch (e) {
+      return { ok: false, error: `Not run: the permission check for ${tool.name} failed unexpectedly (${e instanceof Error ? e.message : String(e)}).` };
+    }
+    if (!g.ok) return { ok: false, error: g.error };
+    if (g.input !== input) {
+      const again = check(g.input);
+      if (!again.ok) return { ok: false, error: `Invalid input for ${tool.name} after a hook changed it: ${again.error}.` };
+      input = again.value;
+    }
+    hookContext = g.context;
+    if (signal.aborted) return { ok: false, error: "Not run: the run was interrupted." };
+  }
+
+  /** @type {{ok:true, content:string}|{ok:false, error:string}} */
+  let r;
+  try {
+    r = await tool.run(input, { ...ctx, toolUseId: call.id }); // a subagent's events name the call that started it
+  } catch (e) {
+    // A tool throwing is a defect in that tool; contain it to this call so the
+    // model can route around it and the transcript stays well-formed.
+    r = { ok: false, error: `${tool.name} failed unexpectedly: ${e instanceof Error ? e.message : String(e)}` };
+  }
+
+  const notes = [];
+  if (hookContext) notes.push(`[PreToolUse hook context]\n${hookContext}`);
+  if (guard) {
+    try {
+      const extra = await guard.after({ call, tool, input, result: r, signal });
+      if (extra) notes.push(extra);
+    } catch {
+      /* a PostToolUse defect cannot undo a call that already ran */
+    }
+  }
+  if (notes.length === 0) return r;
+  const tail = `\n\n${notes.join("\n\n")}`;
+  return r.ok ? { ...r, content: r.content + tail } : { ok: false, error: r.error + tail };
+}