rovecode 0.4.0-beta.3 → 0.4.0

package/src/core/token-scale.ts

@@ -0,0 +1,108 @@
+/** How wrong our token estimate is for a given model, measured rather than assumed.
+ *
+ *  rovecode budgets with two estimators and neither is the tokenizer that decides: `estimateTokens`
+ *  (chars/4) drives compaction, `countTokens` (o200k, OpenAI's tokenizer) drives the reports. For an
+ *  OpenAI model o200k is the truth by construction. For everyone else it is a stand-in, and the size of
+ *  the error is not a detail — compaction fires on the estimate, so an estimate that reads low compacts
+ *  too late and the provider rejects the request that follows.
+ *
+ *  The numbers below were measured with `bun scripts/measure-tokenizer.ts`, which sends real samples to
+ *  Anthropic's own `/v1/messages/count_tokens` and divides. Rerun it to check them; that is the point of
+ *  keeping the script. Measured 2026-09-05 over twenty samples — the system prompt, the tool schemas, a
+ *  TypeScript file, English prose, Turkish prose, a JSON tool result, and fourteen market documentation
+ *  bodies:
+ *
+ *      claude-opus-5, claude-sonnet-5     chars/4 1.33–1.81×   o200k 1.43–1.79×
+ *      claude-haiku-4-5                   chars/4 1.00–1.46×   o200k 1.08–1.29×
+ *
+ *  The market documents were added after nimbus-24, independently measuring 19 skill bodies, found
+ *  ratios above the ceiling the first six samples produced. They were right, and the reason matters:
+ *  markdown documentation — headings, bullets, fenced code and tables in one file — tokenizes worse
+ *  than either prose or code alone, and it is precisely what lands in a window when a model opens a
+ *  skill. Their worst case (mcp-builder, 1.792) reproduces here at 1.791. A sample set that omits the
+ *  commonest content is not conservative; it is wrong in the expensive direction.
+ *
+ *  Two things that table settles. The Claude 5 models share one tokenizer — Opus 5 and Sonnet 5 returned
+ *  identical counts on every sample — so the factor belongs to a generation, not to a model name.
+ *  And 4.5 is a different, older one: applying the 5-generation figure to Haiku would over-correct by two
+ *  fifths, which wastes window rather than overflowing it, but is still a wrong number.
+ *
+ *  Each factor is the **maximum** ratio across the samples, not the mean. The two errors are not
+ *  symmetric: a budget that reads high merely leaves some window unused, while one that reads low sends
+ *  a request the provider refuses and loses the turn. Rounded up to two decimals, and rounded up rather
+ *  than to nearest, for the same reason.
+ *
+ *  A model nobody has measured gets 1 and says so. A guessed multiplier is worse than none: it moves the
+ *  budget by an amount whose provenance no one can explain, and hides the fact that the number is unknown. */
+
+export interface TokenScale {
+  /** multiply an o200k estimate (`countTokens`) by this to approximate what the provider will count;
+   *  1 when unmeasured */
+  scale: number;
+  /** the same for the OTHER estimator, `estimateTokens` (chars/4), which is what compaction and context
+   *  assembly measure with. It is a different approximation with a different error, so it needs its own
+   *  number: on Claude 4.5 the o200k figure is 1.29x while chars/4 needs 1.46x, and using the first to
+   *  size a budget the second is compared against under-corrects by an eighth — which is the direction
+   *  that overflows the window. Measured in the same run, from the same samples. */
+  charScale: number;
+  /** true when the number came from a measurement rather than from the default */
+  measured: boolean;
+  /** one line for the reader: where the number is from, or that there is none */
+  note: string;
+}
+
+const UNMEASURED: TokenScale = {
+  scale: 1,
+  charScale: 1,
+  measured: false,
+  note: "no measurement for this model — the estimate is used as-is; bun scripts/measure-tokenizer.ts measures it",
+};
+
+/** o200k is OpenAI's own tokenizer, so `scale` is exactly 1 — but chars/4 is nobody's tokenizer, and
+ *  the budget is compared against chars/4. Left at 1 because it has not been measured against an
+ *  OpenAI model, and an unmeasured number is what this file refuses to invent. */
+const EXACT: TokenScale = {
+  scale: 1,
+  charScale: 1,
+  measured: true,
+  note: "o200k is this vendor's own tokenizer — the estimate is exact",
+};
+
+interface Row { provider: string; match: RegExp; scale: number; charScale: number; note: string }
+
+const MEASURED: Row[] = [
+  {
+    provider: "anthropic",
+    // the 5 generation: opus-5, sonnet-5, fable-5.x, and the dated snapshots of each
+    match: /(opus-5|sonnet-5|fable-5|mythos-5)/,
+    scale: 1.80,
+    charScale: 1.82,
+    note: "measured 2026-09-05 against /v1/messages/count_tokens over 20 samples — o200k reads up to 1.79× low on Claude 5",
+  },
+  {
+    provider: "anthropic",
+    match: /(haiku-4-5|opus-4-5|sonnet-4-6)/,
+    scale: 1.29,
+    charScale: 1.46,
+    note: "measured 2026-09-05 against /v1/messages/count_tokens over 20 samples — o200k reads up to 1.29× low on Claude 4.5/4.6",
+  },
+];
+
+/** OpenAI's own models are counted with OpenAI's own tokenizer; there is nothing to correct. */
+const EXACT_PROVIDERS = new Set(["openai"]);
+
+/** The scale for a model, by provider and model id. Unknown models get 1 with a note saying so —
+ *  never a factor borrowed from a neighbouring model, which would be a guess dressed as a measurement. */
+export function tokenScaleFor(ref: { provider: string; model: string }): TokenScale {
+  const provider = ref.provider.toLowerCase();
+  const model = ref.model.toLowerCase();
+  if (EXACT_PROVIDERS.has(provider)) return EXACT;
+  const row = MEASURED.find((r) => r.provider === provider && r.match.test(model));
+  return row ? { scale: row.scale, charScale: row.charScale, measured: true, note: row.note } : UNMEASURED;
+}
+
+/** An estimate corrected towards what the provider will count. Rounds up: a token of slack costs
+ *  nothing, a token of shortfall is a rejected request. */
+export function scaleEstimate(tokens: number, ref: { provider: string; model: string }): number {
+  return Math.ceil(tokens * tokenScaleFor(ref).scale);
+}

package/src/core/tool-output-budget.ts

@@ -0,0 +1,166 @@
+/** Unified tool-output budget policy (P0-3; research: docs/research/harness-architecture-research.md G3).
+ *
+ *  Before this module every tool invented its own ceiling — bash truncates at 10k chars
+ *  (coding/hashline.ts), MCP at OUTPUT_MAX (mcp/client.ts), webfetch at MAX_BYTES, evalcell at
+ *  64 KiB, and `read` (2000 lines of unbounded width — one minified line is unbounded output)
+ *  had none. The strategy differed too: hard clips lose the tail, and the tail is where the
+ *  error usually is (test summaries, stack traces, "n lines omitted" footers).
+ *
+ *  One policy now backs them all:
+ *    - at/under the cap the output passes BYTE-VERBATIM — a tool result the policy did nothing
+ *      to is byte-identical, so nothing downstream (reflection, guardrails, transcripts) sees
+ *      a difference;
+ *    - over the cap the MIDDLE goes: head + tail are kept (the tail carries the diagnosis, the
+ *      head carries the orientation), joined by a marker that names what was removed — chars
+ *      and their estimate in the loop's own unit (estimateTokens, chars/4) — and how to see the
+ *      omitted span (a narrower range/query; the read tool's offset/limit);
+ *    - the cut is UTF-8/grapheme safe: it never splits a surrogate pair, a combining-mark
+ *      sequence, a ZWJ emoji chain or a flag pair. A boundary that lands inside one backs off
+ *      to the last whole grapheme — the model is never handed half an emoji.
+ *
+ *  Where it runs: the loop applies it ONCE per batch to the results it persists and re-sends
+ *  (core/loop.ts, after dispatchBatch settles). Tool-side caps stay — a tighter tool cap wins
+ *  by construction (its output is already under the ceiling). The live `tool_execution_end`
+ *  event carries the RAW output (surface fidelity; the human can handle a wall of text, the
+ *  context window cannot) — an accepted, documented divergence.
+ *
+ *  Sizing: DEFAULT_OUTPUT_CAP is a ceiling, not a target — it exists for the pathological
+ *  output (a 2 MB log cat'd whole), not to shave normal ones. 32 KiB ≈ 8k tokens ≈ the room
+ *  a whole small file takes; beyond it the middle of a tool result is almost never what the
+ *  next turn needs. */
+
+import { estimateTokens } from "./context.ts";
+
+export interface OutputBudgetOptions {
+  /** ceiling for a tool result in UTF-16 code units (string.length), default DEFAULT_OUTPUT_CAP */
+  defaultCap?: number;
+  /** per-tool ceilings; unlisted tools get defaultCap. A tool's own tighter cap wins by
+   *  construction (its output never reaches the ceiling). */
+  perTool?: Record<string, number>;
+  /** share of the kept budget spent on the head; the tail gets the rest (0..1, default 0.7) */
+  headShare?: number;
+}
+
+export interface TruncatedOutput {
+  text: string;
+  truncated: boolean;
+  originalChars: number;
+  /** chars of payload kept (head + tail, marker excluded) */
+  keptChars: number;
+  /** removed payload, estimated with the loop's own unit (estimateTokens) */
+  estTokensCut: number;
+}
+
+export const DEFAULT_OUTPUT_CAP = 32_768;
+export const DEFAULT_HEAD_SHARE = 0.7;
+/** the marker opens with this — tests and the idempotence note key on it */
+export const TRUNCATION_MARK = "[…output budget:";
+
+const ZWJ = "‍";
+const isCombining = (ch: string): boolean => /\p{M}/u.test(ch);
+const isRI = (ch: string): boolean => /\p{Regional_Indicator}/u.test(ch);
+
+/** Whole-grapheme slice by UTF-16 budget: take code points until `units` are spent, then back
+ *  the boundary off so it never lands inside a combining sequence, a ZWJ chain, or a flag pair. */
+function takeUnits(cps: string[], from: number, dir: 1 | -1, units: number): number {
+  let i = from;
+  let spent = 0;
+  while (i >= 0 && i < cps.length) {
+    const w = cps[i]!.length; // 1 or 2 UTF-16 units — a code point is never split
+    if (spent + w > units) break;
+    spent += w;
+    i += dir;
+  }
+  // back off: not after a ZWJ, not before/after a combining mark run, not inside a flag pair
+  if (dir === 1) {
+    let end = i; // exclusive
+    while (end > from && (cps[end - 1] === ZWJ || (end < cps.length && isCombining(cps[end]!)))) end--;
+    // flag pairs: an odd run of regional indicators before the cut means the last one is unpaired
+    if (end > from && end < cps.length && isRI(cps[end - 1]!) && isRI(cps[end]!)) {
+      let run = 0;
+      for (let j = end - 1; j >= 0 && isRI(cps[j]!); j--) run++;
+      if (run % 2 === 1) end--;
+    }
+    return end;
+  }
+  let start = i + 1; // inclusive
+  while (start <= from && (cps[start] === ZWJ || isCombining(cps[start]!))) start++;
+  if (start > 0 && start < cps.length && isRI(cps[start - 1]!) && isRI(cps[start]!)) {
+    let run = 0;
+    for (let j = start; j < cps.length && isRI(cps[j]!); j++) run++;
+    if (run % 2 === 1) start++;
+  }
+  return start;
+}
+
+function marker(removedChars: number, originalChars: number): string {
+  const est = estimateTokens("x".repeat(removedChars));
+  return `\n\n${TRUNCATION_MARK} removed ${removedChars} of ${originalChars} chars (~${est} tokens) from the middle — re-run the tool with a narrower range/query (read: offset/limit) to see any part in full…]\n\n`;
+}
+
+/** The pure core: one output, one cap. Two-pass because the marker names the cut and is itself
+ *  bounded by the cap — the second pass sizes the cut against the real marker length. */
+export function applyBudget(output: string, cap: number, headShare: number = DEFAULT_HEAD_SHARE): TruncatedOutput {
+  const originalChars = output.length;
+  const verbatim: TruncatedOutput = { text: output, truncated: false, originalChars, keptChars: originalChars, estTokensCut: 0 };
+  if (originalChars <= cap) return verbatim;
+  if (cap < 32) {
+    // degenerate: no room for a useful marker — hard-clip with an ellipsis, still bounded
+    const text = output.slice(0, Math.max(0, cap - 1)) + "…";
+    return { text, truncated: true, originalChars, keptChars: text.length, estTokensCut: estimateTokens("x".repeat(originalChars - text.length)) };
+  }
+  const cps = Array.from(output);
+  // pass 1 with an estimated marker, pass 2 with the real one (digit-count stable)
+  let mk = marker(0, originalChars);
+  let headEnd = 0, tailStart = cps.length;
+  for (let pass = 0; pass < 2; pass++) {
+    const room = Math.max(0, cap - mk.length);
+    const headUnits = Math.floor(room * Math.min(1, Math.max(0, headShare)));
+    headEnd = takeUnits(cps, 0, 1, headUnits);
+    tailStart = takeUnits(cps, cps.length - 1, -1, room - unitsOf(cps, 0, headEnd));
+    if (tailStart <= headEnd) tailStart = headEnd; // pathological: marker ≈ cap → no tail
+    const removedUnits = unitsOf(cps, headEnd, tailStart);
+    mk = marker(removedUnits, originalChars);
+  }
+  const head = cps.slice(0, headEnd).join("");
+  const tail = cps.slice(tailStart).join("");
+  const text = head + mk + tail;
+  const removed = originalChars - (head.length + tail.length);
+  return {
+    text,
+    truncated: true,
+    originalChars,
+    keptChars: head.length + tail.length,
+    estTokensCut: estimateTokens("x".repeat(removed)),
+  };
+}
+
+function unitsOf(cps: string[], from: number, to: number): number {
+  let n = 0;
+  for (let i = from; i < to; i++) n += cps[i]!.length;
+  return n;
+}
+
+/** The first `units` UTF-16 units of text, cut at a whole-grapheme boundary (compaction.ts's prune
+ *  stub head reuses it — a stub prefix must never open with half an emoji either). */
+export function safeHead(text: string, units: number): string {
+  const cps = Array.from(text);
+  return cps.slice(0, takeUnits(cps, 0, 1, units)).join("");
+}
+
+export interface ToolOutputBudgetPolicy {
+  capFor(tool: string): number;
+  apply(tool: string, output: string): TruncatedOutput;
+}
+
+/** The policy the loop holds for a run. `undefined` options = the defaults; the policy is a pure
+ *  function of its options — no I/O, no clock, no state. */
+export function createOutputBudget(opts: OutputBudgetOptions = {}): ToolOutputBudgetPolicy {
+  const defaultCap = opts.defaultCap ?? DEFAULT_OUTPUT_CAP;
+  const headShare = opts.headShare ?? DEFAULT_HEAD_SHARE;
+  const capFor = (tool: string): number => opts.perTool?.[tool] ?? defaultCap;
+  return {
+    capFor,
+    apply: (tool, output) => applyBudget(output, capFor(tool), headShare),
+  };
+}

package/src/core/tools.ts

@@ -0,0 +1,288 @@
+/** Tool pipeline: validate → revise (extension hooks) → policy → [pre_tool hook] → approve (the
+ *  ApprovalFn chain: execpolicy → [approval hook] → human, composed in cli/runtime.ts buildCfg) →
+ *  execute → [post_tool hook] (ADR-005; hooks v2 = port #29).
+ *  Tool calls are recorded BEFORE execution; truncated responses fail calls unexecuted. */
+
+import type {
+  Tool, ToolContext, ToolOutput, PermissionRule, PermissionDecision,
+  ApprovalRequest, ToolCallPart, RunEvent,
+} from "./types.ts";
+import type { ToolGuard } from "./guardrails.ts";
+import { formatIssues, validateArgs } from "./validate.ts";
+import { cloneForHook, type HookCtx, type HookRunner } from "./hooks.ts";
+import { isAbsolute, join } from "node:path";
+
+export interface ExtensionHooks {
+  /** May revise args; returns revised args (omp revision gate). */
+  reviseToolArgs?: (tool: string, args: unknown) => Promise<unknown>;
+  onToolResult?: (tool: string, args: unknown, out: ToolOutput) => Promise<void>;
+  /** port #29 typed hook set (core/hooks.ts; a HookRunner satisfies this seam): pre_tool / post_tool
+   *  ride dispatch at the seams below, timeout-bounded + isolated by the runner; the approval hook
+   *  rides the ApprovalFn chain instead (HookRunner.approver — after execpolicy, before the human); the
+   *  loop taps the run-level hooks (pre_run / compaction / post_run / on_event) through observer(). */
+  run?: HookRunner["run"];
+  observer?: HookRunner["observer"];
+}
+
+/** Output of a tool_call that never executed because the run aborted (port
+ *  #21): a queued sibling in an aborted batch, or an approval answered after
+ *  the abort. Same text loop.ts synthesizes for calls a batch never delivered
+ *  (opencode session/processor.ts:587; codex normalize.rs:51-67). */
+export const ABORTED_TOOL_RESULT = "Tool execution aborted";
+/** port #29: the small ctx hooks receive — cwd, session, run; no registry/store handles */
+const hookCtx = (c: ToolContext): HookCtx =>
+  ({ cwd: c.cwd, sessionId: c.sessionId, ...(c.runId !== undefined ? { runId: c.runId } : {}) });
+
+/** Deny-by-default wildcard rules, last match wins (opencode permission.ts:126). */
+export function evaluatePermissions(rules: PermissionRule[], action: string, resource: string): PermissionDecision {
+  let decision: PermissionDecision = { effect: "deny", reason: `no rule allows ${action}` };
+  for (const r of rules) {
+    if (matchesGlob(r.action, action) && matchesGlob(r.resource, resource)) {
+      decision = r.effect === "allow" ? { effect: "allow" }
+        : r.effect === "deny" ? { effect: "deny", reason: `denied by rule ${r.action} ${r.resource}` }
+        : { effect: "prompt", prompt: `permission required for ${action} ${resource}` };
+    }
+  }
+  return decision;
+}
+
+function matchesGlob(pattern: string, value: string): boolean {
+  if (pattern === "*") return true;
+  const rx = new RegExp("^" + pattern.split("*").map(escapeRx).join(".*") + "$");
+  return rx.test(value);
+}
+function escapeRx(s: string): string { return s.replace(/[.+^${}()|[\]\\]/g, "\\$&"); }
+
+export class ToolRegistry {
+  private tools = new Map<string, Tool>();
+  private approvalCache = new Map<string, "once" | "always">();
+
+  register(...tools: Tool[]): void { for (const t of tools) this.tools.set(t.schema.name, t); }
+  list(): Tool[] { return [...this.tools.values()]; }
+
+  /** ADR-005 ladder. Emits events; never lets tool exceptions escape as control flow. */
+  async dispatch(
+    call: ToolCallPart,
+    ctx: ToolContext,
+    hooks: ExtensionHooks | undefined,
+    rules: PermissionRule[],
+    approve: ((req: ApprovalRequest) => Promise<"once" | "always" | "deny">) | undefined,
+    emit: (e: RunEvent) => void,
+    guard?: ToolGuard,
+  ): Promise<ToolOutput> {
+    const t0 = Date.now();
+    const tool = this.tools.get(call.tool);
+    if (!tool) {
+      emit({ type: "tool_call_failed", callId: call.id, reason: "not_found", detail: `unknown tool ${call.tool}` });
+      return { ok: false, output: `Error: unknown tool '${call.tool}'` };
+    }
+
+    // 1. extension revision
+    let args = call.args;
+    if (hooks?.reviseToolArgs) args = await hooks.reviseToolArgs(call.tool, args);
+
+    // 1a. validate against the tool's OWN published schema (ADR-005's first step; core/validate.ts).
+    // After revision, so a hook that repairs args is judged on what it produced; before the guard and
+    // policy, because a call that cannot execute should not consume a loop-guard slot, an approval
+    // card, or the human's attention. The failure shape matches the others here: a tool_call_failed
+    // event and an ok:false result the model reads and corrects on the next turn.
+    const issues = validateArgs(tool.schema.args, args);
+    if (issues.length > 0) {
+      const detail = formatIssues(call.tool, issues);
+      emit({ type: "tool_call_failed", callId: call.id, reason: "invalid_args", detail });
+      return { ok: false, output: detail };
+    }
+
+    // 1b. loop guard (port #4, hermes): stub repeated identical calls BEFORE the user is
+    // prompted for them; warn notes ride along on the result
+    let warnNote: string | undefined;
+    if (guard) {
+      const verdict = guard.checkCall(call.tool, args);
+      if (verdict.action === "stub") {
+        const note = verdict.note ?? "call blocked by loop guard: identical call repeated too often";
+        emit({ type: "tool_execution_start", callId: call.id, tool: call.tool, args });
+        emit({ type: "tool_execution_end", callId: call.id, ok: false, output: note, durationMs: 0 });
+        return { ok: false, output: note };
+      }
+      if (verdict.action === "warn") warnNote = verdict.note;
+    }
+
+    // 2. policy (deny-default)
+    const resource = describeResource(tool, args, ctx.cwd);
+    const decision = evaluatePermissions(rules, actionFor(tool), resource);
+    if (decision.effect === "deny") {
+      emit({ type: "tool_call_failed", callId: call.id, reason: "permission_denied", detail: decision.reason });
+      return { ok: false, output: `Permission denied: ${decision.reason}` };
+    }
+
+    // 2b. pre_tool hook (port #29) — AFTER policy: the rule deny above is never un-denied and hooks
+    // never see rule-rejected calls; a hook deny applies in every mode incl. yolo (the user's own
+    // stricter layer) and takes the policy-deny failure shape with the hook's reason. Hooks see a COPY
+    // of the args (hooks.ts cloneForHook): mutating it cannot re-aim what policy just evaluated
+    const veto = await hooks?.run?.("pre_tool", hookCtx(ctx), { id: call.id, tool: call.tool, args: cloneForHook(args) });
+    if (veto) {
+      emit({ type: "tool_call_failed", callId: call.id, reason: "permission_denied", detail: veto.deny });
+      return { ok: false, output: `Permission denied by hook: ${veto.deny}` };
+    }
+
+    // 3. approval — always resolved against the REVISED args (omp wrapper.ts:205-247). The approver
+    // IS the chain: execpolicy refinement → approval hook → human (cli/runtime.ts buildCfg), so a
+    // hook is consulted only where the human would be — never ahead of a forbidden-argv hard stop
+    if (decision.effect === "prompt") {
+      // "always" is remembered by what the RULES are about — action + resource — not by the whole
+      // argument blob. Keyed on the args, an "always" on `write {path, content}` never matched again:
+      // the next write to the same file carries different content, so the cache missed and the card
+      // came back. The pair below is the same identity evaluatePermissions just decided on, so
+      // "always" now means what the card says: this action, on this file / this command / this host.
+      const key = approvalKey(actionFor(tool), resource, tool.schema.name, args);
+      const cached = this.approvalCache.get(key);
+      if (!cached) {
+        if (!approve) {
+          emit({ type: "tool_call_failed", callId: call.id, reason: "permission_denied", detail: "approval required but no approver connected" });
+          return { ok: false, output: "Permission denied: approval required, no approver available" };
+        }
+        const verdict = await approve({ tool: call.tool, args, revisedArgs: args, reason: decision.prompt });
+        if (verdict === "deny") {
+          emit({ type: "tool_call_failed", callId: call.id, reason: "permission_denied", detail: "user denied" });
+          return { ok: false, output: "Permission denied by user" };
+        }
+        // "once" means once: only "always" verdicts persist across calls
+        if (verdict === "always") this.approvalCache.set(key, verdict);
+      }
+    }
+
+    // 3b. abort re-check (port #21 LOW-1): the approver may answer long after
+    // the run aborted — the loop has already synthesized ABORTED for this call
+    // and returned, so executing now would run the tool detached from any run.
+    // Nothing above touches the workspace; this is the last gate before the
+    // tool's side effect. (An "always" verdict is still cached: it is the
+    // user's decision about the tool+args, not about this run.)
+    if (ctx.signal.aborted) return { ok: false, output: ABORTED_TOOL_RESULT };
+
+    // 4. execute with typed error capture; ctx.onUpdate is wired here so a
+    // tool's progress notes (MCP onprogress, LSP/checkpoint updates) become
+    // real tool_execution_update events for ALL tools (port #3 LOW-6)
+    emit({ type: "tool_execution_start", callId: call.id, tool: call.tool, args });
+    let out: ToolOutput;
+    try {
+      out = await tool.execute(args, { ...ctx, onUpdate: (note) => emit({ type: "tool_execution_update", callId: call.id, note }) });
+    } catch (e) {
+      out = { ok: false, output: `Error: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    // 4b. loop guard result pass: byte-identical duplicate results become stubs.
+    // out.ok is threaded through so FAILED results are never stubbed (hermes
+    // keeps errors verbatim) even when the text dodges the string sniff.
+    if (guard) {
+      const r = guard.checkResult(call.tool, args, out.output, out.ok);
+      if (r.deduped) out = { ...out, output: r.output };
+    }
+    if (warnNote) out = { ...out, output: `${out.output}\n\n[loop-guard] ${warnNote}` };
+    // port #29: post_tool may annotate/replace what the model will see (growth-bounded in the runner);
+    // tool_execution_end below carries the final text, like the guard's stub/warn rewrites above. The
+    // hook gets a copy of the result: only its RETURNED {output} counts (an assignment dodges no bound)
+    const ann = await hooks?.run?.("post_tool", hookCtx(ctx), { id: call.id, tool: call.tool, args: cloneForHook(args) }, { ...out });
+    if (ann?.output !== undefined) out = { ...out, output: ann.output };
+    emit({ type: "tool_execution_end", callId: call.id, ok: out.ok, output: out.output, durationMs: Date.now() - t0 });
+    if (hooks?.onToolResult) await hooks.onToolResult(call.tool, args, out).catch(() => {});
+    return out;
+  }
+
+  /** Batch executor: concurrent for parallel-safe tools, sequential otherwise (pi executionMode). */
+  async dispatchBatch(
+    calls: ToolCallPart[],
+    ctx: ToolContext,
+    hooks: ExtensionHooks | undefined,
+    rules: PermissionRule[],
+    approve: ((req: ApprovalRequest) => Promise<"once" | "always" | "deny">) | undefined,
+    emit: (e: RunEvent) => void,
+    parallelEnabled: boolean,
+    guard?: ToolGuard,
+  ): Promise<Map<string, ToolOutput>> {
+    const results = new Map<string, ToolOutput>();
+    const run = async (c: ToolCallPart) => { results.set(c.id, await this.dispatch(c, ctx, hooks, rules, approve, emit, guard)); };
+    if (!parallelEnabled || calls.some((c) => this.tools.get(c.tool)?.sequential !== false)) {
+      for (const c of calls) {
+        // port #21 MED-2: an abort that landed during the previous call must not
+        // START the next one — nor prompt for it. It gets the aborted synthesis
+        // HERE: the loop's batch-finally only synthesizes for a batch that never
+        // settled, and a killed bash settles well inside the loop's grace.
+        if (ctx.signal.aborted) { results.set(c.id, { ok: false, output: ABORTED_TOOL_RESULT }); continue; }
+        await run(c);
+      }
+    } else {
+      await Promise.all(calls.map(run));
+    }
+    return results;
+  }
+}
+
+function actionFor(tool: Tool): string {
+  switch (tool.kind) {
+    case "read": return "file.read";
+    case "write": return "file.write";
+    case "execute": return "shell.exec";
+    case "spawn": return "spawn";
+    case "memory": return "memory.write";
+    case "network": return "net.fetch"; // port #31: outbound requests; resource = URL host
+    default: return `tool.${tool.schema.name}`;
+  }
+}
+
+/** Resource for policy rules. An args key is only honored when the tool's
+ *  DECLARED schema has that property: args are not schema-validated before
+ *  policy, so a smuggled key ({query, path:"/tmp/x"} on recall, whose schema
+ *  has no `path`) must not re-aim a tool-targeted deny rule at another
+ *  resource. Policy runs pre-execute, so per-tool arg-stripping can't repair
+ *  this — the gate belongs here.
+ *  For a path-declared tool the resource is the path the tool will actually
+ *  touch: a missing/empty `path` defaults to ctx.cwd and a relative one
+ *  resolves against it (the tools' own resolvePath rule), so neither omitting
+ *  nor relativizing the arg can dodge a path-targeted rule (port #22 MED-4).
+ *  Consequently path resources are ALWAYS absolute, so a permission rule's
+ *  pattern must match the full absolute path (matchesGlob anchors it): an
+ *  absolute path/glob or `*` — a cwd-relative pattern such as
+ *  `deny file.write ".env*"` can never match via dispatch.
+ *  Command resources and the tool-name fallback are untouched. */
+function describeResource(tool: Tool, args: unknown, cwd: string): string {
+  // a tool that declares its own mode wins: a path/command/url says WHAT is touched, but a tool
+  // whose modes differ in what they may do has to be able to say WHICH mode (types.ts Tool.resource)
+  if (typeof tool.resource === "function") return tool.resource(args);
+  const props = tool.schema.args["properties"];
+  const declared = (key: string): boolean =>
+    typeof props === "object" && props !== null && key in (props as Record<string, unknown>);
+  const a = args && typeof args === "object" ? (args as Record<string, unknown>) : undefined;
+  if (declared("path")) {
+    const p = a?.["path"];
+    if (p === undefined || p === null || p === "") return cwd;
+    return isAbsolute(String(p)) ? String(p) : join(cwd, String(p));
+  }
+  if (a && declared("command") && "command" in a) return String(a["command"]);
+  if (a && declared("url") && "url" in a) return hostOf(String(a["url"]));
+  return tool.schema.name;
+}
+
+/** Policy resource for url-declared tools (port #31): the URL's hostname — no
+ *  scheme/port/credentials/path — so `allow net.fetch docs.example.com` and
+ *  `deny net.fetch *` read naturally. The host is CANONICAL (lowercased, trailing
+ *  dot stripped — the form the tool's own SSRF guard checks), so `evil.com.`
+ *  cannot dodge a `deny net.fetch evil.com` rule. The decision covers this host
+ *  only: web_fetch stops at a redirect to a different host and reports the
+ *  target URL, so that host comes back through this gate as its own call.
+ *  Unparseable URLs keep the raw string (the tool rejects them anyway), so `*`
+ *  rules still see a stable resource. */
+function hostOf(url: string): string {
+  try { const h = new URL(url).hostname; return (h.endsWith(".") ? h.slice(0, -1) : h).toLowerCase() || url; } catch { return url; }
+}
+
+/** The identity an "always" verdict is remembered under.
+ *
+ *  Where the card names a real target — a path, a shell command, a host — that pair IS the decision
+ *  the human made ("always allow writing THIS file"), and it is the same identity the rules evaluate.
+ *  Where the tool declares none of those, describeResource falls back to the tool NAME, and widening
+ *  to it would turn "always" on one `mcp_call` into "always" on every MCP call. So those keep the
+ *  exact-arguments key they always had: the narrow reading is the safe one when the card cannot say
+ *  what the decision is about. */
+function approvalKey(action: string, resource: string, toolName: string, args: unknown): string {
+  const base = action + "|" + resource;
+  return resource === toolName ? base + "|" + JSON.stringify(args) : base;
+}