@nathapp/nax-agent 0.1.0

package/dist/native/session/handle-invalid-tool-call.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Detect an invalid tool-call input at the transport boundary (nax#2047).
+ *
+ * The model returned RunCommand calls with `values:""` 69 times in a row —
+ * the empty string produced no rejected keys, the loop never named "values"
+ * as the wrong type, so the spin breaker never saw the repetition as
+ * repetition. This module is the gate the loop was missing: validate the
+ * call against the tool's JSON Schema before any handler runs. On violation,
+ * name the property and offer a schema-conforming exemplar so the next round
+ * trip sees what the tool would have accepted.
+ *
+ * Where the exemplar goes (nax#2200): #2047 wrote it over the model's call in
+ * the assistant message, so the malformed value would not persist as a
+ * few-shot example. That kept the purpose but attributed a call the model never
+ * made — `refs: ["<FILL IN: refs>"]` — to the assistant. The recorded call is
+ * now the model's own input with ONLY the rejected property removed: the
+ * malformed value still never persists, nothing fabricated is attributed to
+ * the model, and the exemplar lives in the tool-result's error text, where it
+ * is plainly guidance from the harness.
+ *
+ * Since nax#2151 this decision is produced by a built-in `before_tool`
+ * handler (`loop-handlers.ts`) instead of an inline branch of the loop: the
+ * repair is a tool-call decision — answer without invoking — which is exactly
+ * what the seam's `block` outcome is for. What stays here is the decision and
+ * its per-turn budget; the transcript rewrite is the loop's, because that is
+ * where the message array lives.
+ *
+ * Returns `undefined` when the call is valid, or when the tool is not in the
+ * local catalogue (no schema → no validation, success path). The success path
+ * costs one function call and no allocation.
+ *
+ * The per-turn budget (Task 4) lives in `createInvalidCallBudget()` — three
+ * identical invalid calls (same tool, same `stableStringify`'d input) end the
+ * turn with `{kind: "stopped"}` and NO tool-result, matching the spin
+ * breaker's stop branch ("a result nobody reads only grows the transcript").
+ * The counter is per-key, cumulative across interleaved valid calls, and lives
+ * in the factory's closure.
+ */
+import type { ToolCall, ToolDefinition } from "@nathapp/nax-ai";
+import type { InvalidToolCallDetail } from "#src/session/session-types";
+import type { TranscriptMessage as NativeTranscriptMessage } from "./compaction.ts";
+/** Three identical invalid calls in a turn ends it (Task 4). */
+export declare const INVALID_CALL_BUDGET_THRESHOLD = 3;
+export type InvalidCallOutcome = 
+/**
+ * Answer the call with `content` instead of running it. `input` is what the
+ * transcript records for the call: the model's own input minus the rejected
+ * property (nax#2200), never a fabricated exemplar.
+ */
+{
+    readonly kind: "repair";
+    readonly input: Record<string, unknown>;
+    readonly content: string;
+}
+/** The per-key budget is spent: end the turn with no answer at all. */
+ | {
+    readonly kind: "stopped";
+    readonly detail: InvalidToolCallDetail;
+};
+export declare function decideInvalidToolCall(call: ToolCall, tools: readonly ToolDefinition[], counters: Map<string, number>): InvalidCallOutcome | undefined;
+/**
+ * The call's input with its `null`-valued optional properties removed, or
+ * `undefined` when the tool is not in the catalogue or nothing was removed
+ * (nax#2200). The validator already reads such a `null` as absent; this is
+ * what makes the tool's handler see the same thing.
+ */
+export declare function normalizeNullOptionals(call: ToolCall, tools: readonly ToolDefinition[]): Record<string, unknown> | undefined;
+/**
+ * Replace one `toolCalls` entry's input on the LAST assistant message.
+ *
+ * Composes onto the last assistant message rather than the last array entry:
+ * after iteration N of a multi-call assistant message, iteration N+1 sees a
+ * tool-result for iteration N at the tail, and a naive implementation would
+ * rewrite only the last of two invalid calls.
+ *
+ * Never mutates: the returned array and the rewritten message are fresh values,
+ * and thinking blocks survive byte-for-byte (ADR-028 §8 — Anthropic needs the
+ * exact thinking block back to continue a thinking conversation).
+ */
+export declare function rewriteToolCallInput(messages: readonly NativeTranscriptMessage[], callId: string, input: Record<string, unknown>): NativeTranscriptMessage[];
+/**
+ * Per-turn budget for repeated invalid tool calls (nax#2047, Task 4).
+ *
+ * The spin breaker's 50-call budget is for REPEATED *valid-shape* calls; a
+ * malformed shape is a stronger signal — the model will keep sending the
+ * same wrong shape for as long as it ignores the error result. This budget
+ * hard-stops a turn after three identical invalid calls (same tool, same
+ * `stableStringify`'d input) so the transcript never grows past the second
+ * error result.
+ *
+ * Per-key, cumulative across interleaved valid calls: a valid call does
+ * not reset the counter, and the same key returning later in the same turn
+ * keeps accumulating. Different keys do not stop each other — three distinct
+ * invalid calls (the model is exploring) are not a budget violation.
+ *
+ * On exceed, `observe()` returns `{kind: "stopped"}` and `exceeded` flips to
+ * `true`. The caller checks `exceeded` after the dispatch to break the batch
+ * with no tool-result and to set `TurnResult.invalidCallBudgetExceeded`,
+ * mirroring `spinStopped`'s reporting pattern.
+ */
+export interface InvalidCallBudget {
+    /** Whether the budget was tripped on any call so far. Read after the dispatch. */
+    readonly exceeded: boolean;
+    /**
+     * The call that tripped the budget — set together with `exceeded`, so the
+     * halt can be logged and classified by what was rejected (nax#2200).
+     */
+    readonly halt: InvalidToolCallDetail | undefined;
+    observe(call: ToolCall, tools: readonly ToolDefinition[]): InvalidCallOutcome | undefined;
+}
+export declare function createInvalidCallBudget(): InvalidCallBudget;

package/dist/native/session/handle-invalid-tool-call.js

@@ -0,0 +1,159 @@
+/**
+ * Detect an invalid tool-call input at the transport boundary (nax#2047).
+ *
+ * The model returned RunCommand calls with `values:""` 69 times in a row —
+ * the empty string produced no rejected keys, the loop never named "values"
+ * as the wrong type, so the spin breaker never saw the repetition as
+ * repetition. This module is the gate the loop was missing: validate the
+ * call against the tool's JSON Schema before any handler runs. On violation,
+ * name the property and offer a schema-conforming exemplar so the next round
+ * trip sees what the tool would have accepted.
+ *
+ * Where the exemplar goes (nax#2200): #2047 wrote it over the model's call in
+ * the assistant message, so the malformed value would not persist as a
+ * few-shot example. That kept the purpose but attributed a call the model never
+ * made — `refs: ["<FILL IN: refs>"]` — to the assistant. The recorded call is
+ * now the model's own input with ONLY the rejected property removed: the
+ * malformed value still never persists, nothing fabricated is attributed to
+ * the model, and the exemplar lives in the tool-result's error text, where it
+ * is plainly guidance from the harness.
+ *
+ * Since nax#2151 this decision is produced by a built-in `before_tool`
+ * handler (`loop-handlers.ts`) instead of an inline branch of the loop: the
+ * repair is a tool-call decision — answer without invoking — which is exactly
+ * what the seam's `block` outcome is for. What stays here is the decision and
+ * its per-turn budget; the transcript rewrite is the loop's, because that is
+ * where the message array lives.
+ *
+ * Returns `undefined` when the call is valid, or when the tool is not in the
+ * local catalogue (no schema → no validation, success path). The success path
+ * costs one function call and no allocation.
+ *
+ * The per-turn budget (Task 4) lives in `createInvalidCallBudget()` — three
+ * identical invalid calls (same tool, same `stableStringify`'d input) end the
+ * turn with `{kind: "stopped"}` and NO tool-result, matching the spin
+ * breaker's stop branch ("a result nobody reads only grows the transcript").
+ * The counter is per-key, cumulative across interleaved valid calls, and lives
+ * in the factory's closure.
+ */
+import { byCodePoint } from "#src/internal/sort";
+import { exemplarFor } from "./tool-input-exemplar.js";
+import { stripNullOptionals, validateToolInput } from "./tool-input-validation.js";
+/** Three identical invalid calls in a turn ends it (Task 4). */
+export const INVALID_CALL_BUDGET_THRESHOLD = 3;
+export function decideInvalidToolCall(call, tools, counters) {
+    const tool = tools.find((t) => t.name === call.name);
+    if (tool === undefined)
+        return undefined;
+    const violation = validateToolInput(tool.inputSchema, call.input);
+    if (violation === undefined)
+        return undefined;
+    // Per-key counter: tool name + stableStringify(input). Mutated in place
+    // so the next iteration sees the updated count without us having to
+    // thread the new map back through.
+    const counterKey = `${call.name}\u0000${stableStringify(call.input)}`;
+    const nextCount = (counters.get(counterKey) ?? 0) + 1;
+    counters.set(counterKey, nextCount);
+    if (nextCount >= INVALID_CALL_BUDGET_THRESHOLD) {
+        const { property, expected, actual } = violation;
+        return { kind: "stopped", detail: { tool: call.name, property, expected, actual } };
+    }
+    const original = call.input;
+    const exemplar = exemplarFor(tool.inputSchema, original, violation);
+    const recorded = withoutProperty(original, violation.property);
+    return { kind: "repair", input: recorded, content: invalidCallMessage(violation, exemplar, recorded !== original) };
+}
+/**
+ * The call's input with its `null`-valued optional properties removed, or
+ * `undefined` when the tool is not in the catalogue or nothing was removed
+ * (nax#2200). The validator already reads such a `null` as absent; this is
+ * what makes the tool's handler see the same thing.
+ */
+export function normalizeNullOptionals(call, tools) {
+    const tool = tools.find((t) => t.name === call.name);
+    if (tool === undefined)
+        return undefined;
+    return stripNullOptionals(tool.inputSchema, call.input);
+}
+/** `input` without `property`; the same object when the property is not there. */
+function withoutProperty(input, property) {
+    if (property === "" || !(property in input))
+        return input;
+    const { [property]: _rejected, ...rest } = input;
+    return rest;
+}
+/**
+ * Replace one `toolCalls` entry's input on the LAST assistant message.
+ *
+ * Composes onto the last assistant message rather than the last array entry:
+ * after iteration N of a multi-call assistant message, iteration N+1 sees a
+ * tool-result for iteration N at the tail, and a naive implementation would
+ * rewrite only the last of two invalid calls.
+ *
+ * Never mutates: the returned array and the rewritten message are fresh values,
+ * and thinking blocks survive byte-for-byte (ADR-028 §8 — Anthropic needs the
+ * exact thinking block back to continue a thinking conversation).
+ */
+export function rewriteToolCallInput(messages, callId, input) {
+    let lastAssistantIndex = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === "assistant") {
+            lastAssistantIndex = i;
+            break;
+        }
+    }
+    const lastAssistant = messages[lastAssistantIndex];
+    if (lastAssistant === undefined || lastAssistant.role !== "assistant")
+        return [...messages];
+    const toolCalls = (lastAssistant.toolCalls ?? []).map((tc) => (tc.id === callId ? { ...tc, input } : tc));
+    return [
+        ...messages.slice(0, lastAssistantIndex),
+        {
+            role: "assistant",
+            content: lastAssistant.content,
+            toolCalls,
+            ...(lastAssistant.thinking !== undefined ? { thinking: lastAssistant.thinking } : {}),
+        },
+        ...messages.slice(lastAssistantIndex + 1),
+    ];
+}
+function invalidCallMessage(violation, exemplar, removedFromRecord) {
+    return (`invalid tool call: property "${violation.property}" expected ${violation.expected}, ` +
+        `got ${violation.actual}. The call was not executed. ` +
+        (removedFromRecord ? `The rejected "${violation.property}" value was removed from the recorded call. ` : "") +
+        `An input of the expected shape looks like ${JSON.stringify(exemplar)} — ` +
+        "replace any <FILL IN> placeholder with a real value, and omit an optional property you have no value for.");
+}
+export function createInvalidCallBudget() {
+    const counters = new Map();
+    let halt;
+    return {
+        get exceeded() {
+            return halt !== undefined;
+        },
+        get halt() {
+            return halt;
+        },
+        observe(call, tools) {
+            const outcome = decideInvalidToolCall(call, tools, counters);
+            if (outcome?.kind === "stopped" && halt === undefined)
+                halt = outcome.detail;
+            return outcome;
+        },
+    };
+}
+/**
+ * Deterministic serializer independent of property insertion order, so
+ * `{a:1,b:2}` and `{b:2,a:1}` collide on the same counter key. Locally
+ * scoped on purpose — `src/runtime/spin-breaker` has its own private copy
+ * of the same algorithm. The two implementations are deliberately small and
+ * identical so a future extraction is a one-line move.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value).sort((a, b) => byCodePoint(a[0], b[0]));
+    return `{${entries.map(([key, val]) => `${JSON.stringify(key)}:${stableStringify(val)}`).join(",")}}`;
+}

package/dist/native/session/loop-events/cache-boundary.d.ts

@@ -0,0 +1,11 @@
+export declare function checkPrefixStable(before: readonly unknown[], after: readonly unknown[], anchorIndex: number | undefined): boolean;
+export declare function applyHistoryPatch<T>(args: {
+    readonly before: readonly T[];
+    readonly patched: readonly T[] | undefined;
+    readonly anchorIndex: number | undefined;
+    readonly boundary: boolean;
+    readonly event: string;
+}): {
+    readonly messages: readonly T[];
+    readonly honoured: boolean;
+};

package/dist/native/session/loop-events/cache-boundary.js

@@ -0,0 +1,29 @@
+import { getSafeLogger } from "#src/infra/index";
+export function checkPrefixStable(before, after, anchorIndex) {
+    // No anchor means no cached prefix to protect (spec 3.5).
+    if (anchorIndex === undefined)
+        return true;
+    const end = Math.min(anchorIndex, before.length - 1);
+    if (after.length <= end)
+        return false;
+    for (let i = 0; i <= end; i += 1) {
+        // Reference identity: an equal-valued rebuild still breaks the wire cache.
+        if (before[i] !== after[i])
+            return false;
+    }
+    return true;
+}
+export function applyHistoryPatch(args) {
+    const { before, patched, anchorIndex, boundary, event } = args;
+    if (patched === undefined)
+        return { messages: before, honoured: false };
+    if (boundary || checkPrefixStable(before, patched, anchorIndex)) {
+        return { messages: patched, honoured: true };
+    }
+    getSafeLogger()?.warn("native-loop-events", "history patch rejected: prefix rewritten off-boundary", {
+        event,
+        ...(anchorIndex !== undefined ? { anchorIndex } : {}),
+    });
+    // What stops is the PATCH, never the turn (spec 3.7).
+    return { messages: before, honoured: false };
+}

package/dist/native/session/loop-events/external-handler.d.ts

@@ -0,0 +1,38 @@
+/**
+ * US-002 — `wrapExternalHandler()`: bounded lifetime, context and attributed
+ * failure for plugin-contributed loop handlers.
+ *
+ * A `src/hooks/` handler is a child process with a 5s timeout; a plugin loop
+ * handler is an IN-PROCESS function called from inside `runNativeTurn`, so
+ * nothing bounds it and nothing catches it. A handler that never settles would
+ * hang the turn, and a handler that throws must not be able to silently pass a
+ * tool guard. This module answers both, for one staged entry at a time, and it
+ * never rethrows: a plugin's defect must not fail the turn.
+ *
+ * The payload is handed over untouched — including for `before_tool`, whose
+ * answer is a DECISION (`allow`/`nudge`/`block`/`terminate`) rather than a
+ * field patch. That answer is therefore validated rather than field-picked: a
+ * plugin module is plain JavaScript, is loaded from disk, and can return
+ * anything at all.
+ */
+import type { HandlerOf, LoopEvent, LoopHandlerContext, LoopHandlerEntry } from "./types.ts";
+/**
+ * How long a plugin handler may run before the wrapper answers for it. A
+ * constant by ruling, not a `NaxConfig` key: it bounds the turn's liveness, it
+ * is not a policy a project tunes per package.
+ */
+export declare const LOOP_HANDLER_TIMEOUT_MS = 10000;
+/**
+ * Test seam for the deadline only. Read at DISPATCH time, never captured when
+ * the handler is wrapped — a wrapped handler is installed once and dispatched
+ * many times.
+ */
+export declare const _externalHandlerDeps: {
+    timeoutMs: number;
+};
+/**
+ * Wrap one staged plugin registration into a built-in-shaped `HandlerOf<E>`:
+ * same payload, same patch, but with a bounded lifetime, the turn's context,
+ * and a failure that is attributed and never rethrown.
+ */
+export declare function wrapExternalHandler<E extends LoopEvent>(entry: LoopHandlerEntry, getCtx: () => LoopHandlerContext, signal: AbortSignal): HandlerOf<E>;

package/dist/native/session/loop-events/external-handler.js

@@ -0,0 +1,193 @@
+/**
+ * US-002 — `wrapExternalHandler()`: bounded lifetime, context and attributed
+ * failure for plugin-contributed loop handlers.
+ *
+ * A `src/hooks/` handler is a child process with a 5s timeout; a plugin loop
+ * handler is an IN-PROCESS function called from inside `runNativeTurn`, so
+ * nothing bounds it and nothing catches it. A handler that never settles would
+ * hang the turn, and a handler that throws must not be able to silently pass a
+ * tool guard. This module answers both, for one staged entry at a time, and it
+ * never rethrows: a plugin's defect must not fail the turn.
+ *
+ * The payload is handed over untouched — including for `before_tool`, whose
+ * answer is a DECISION (`allow`/`nudge`/`block`/`terminate`) rather than a
+ * field patch. That answer is therefore validated rather than field-picked: a
+ * plugin module is plain JavaScript, is loaded from disk, and can return
+ * anything at all.
+ */
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { isCompleteBeforeToolOutcome } from "./registry.js";
+/**
+ * How long a plugin handler may run before the wrapper answers for it. A
+ * constant by ruling, not a `NaxConfig` key: it bounds the turn's liveness, it
+ * is not a policy a project tunes per package.
+ */
+export const LOOP_HANDLER_TIMEOUT_MS = 10_000;
+/**
+ * Test seam for the deadline only. Read at DISPATCH time, never captured when
+ * the handler is wrapped — a wrapped handler is installed once and dispatched
+ * many times.
+ */
+export const _externalHandlerDeps = {
+    timeoutMs: LOOP_HANDLER_TIMEOUT_MS,
+};
+/**
+ * The patch fields whose presence is worth tracing: the ones a later
+ * `applyHistoryPatch` can reject, so a rejection is attributable to a plugin.
+ */
+const TRACED_PATCH_FIELDS = ["seed", "history", "messages", "summary"];
+/**
+ * Race the handler's settlement against the deadline and the turn's abort. The
+ * first to settle wins, every later settlement is discarded, and the timer is
+ * cleared the moment the race settles so an instant handler never holds the
+ * event loop open for the full deadline.
+ *
+ * The abort is honoured for the lifetime of THIS dispatch: the listener is
+ * wired synchronously, before the handler is called. A signal that was already
+ * aborted when the dispatch began is deliberately NOT honoured — one registry
+ * is installed once and repointed per turn (`./loop-handlers`), so a signal
+ * carried over from an earlier turn would otherwise fail-close every later
+ * `before_tool` dispatch to `block` without ever calling the handler. The
+ * deadline still bounds such a dispatch, so nothing hangs.
+ *
+ * `setTimeout` and not `Bun.sleep()`: the handle has to be cancelled mid-flight
+ * (`clearTimeout`), which is the sanctioned exception to the Bun-native delay
+ * rule.
+ */
+function raceSettlement(entry, payload, deps) {
+    const timeoutMs = _externalHandlerDeps.timeoutMs;
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            deps.signal.removeEventListener("abort", onAbort);
+            resolve(result);
+        };
+        const onAbort = () => finish({ ok: false, reason: "aborted before it settled" });
+        timer = setTimeout(() => finish({ ok: false, reason: `did not settle within ${timeoutMs}ms` }), timeoutMs);
+        deps.signal.addEventListener("abort", onAbort, { once: true });
+        // The context is read here, at dispatch, so a handler always sees the facts
+        // of the turn it is running in. Read in its OWN try: a `getCtx` throw is
+        // nax's own defect, and it must not be reported as the plugin's handler
+        // failing (US-002 review).
+        let ctx;
+        try {
+            ctx = deps.getCtx();
+        }
+        catch (err) {
+            finish({ ok: false, reason: `reading the handler context failed: ${errorMessage(err)}` });
+            return;
+        }
+        let returned;
+        try {
+            returned = entry.handler(payload, ctx);
+        }
+        catch (err) {
+            finish({ ok: false, reason: errorMessage(err) });
+            return;
+        }
+        Promise.resolve(returned).then((value) => finish({ ok: true, value }), (err) => finish({ ok: false, reason: errorMessage(err) }));
+    });
+}
+/**
+ * The attributed failure. On `before_tool` the call is answered with an error
+ * block — a failed guard must never read as a silent allow — and every other
+ * event answers `{}` (no patch). One warn per failure either way, naming the
+ * plugin the failure belongs to.
+ *
+ * The tool name is read defensively: this runs on the failure path, outside any
+ * try, and a wrapper whose contract is that it never rethrows must not throw
+ * from its own diagnosis of a malformed payload.
+ */
+function failure(entry, payload, reason) {
+    const logger = getSafeLogger();
+    if (entry.event === "before_tool") {
+        const tool = payload?.call?.name;
+        logger?.warn("native-loop-events", `plugin '${entry.plugin}' failed on before_tool; blocking the call`, {
+            plugin: entry.plugin,
+            event: entry.event,
+            ...(tool !== undefined ? { tool } : {}),
+            error: reason,
+        });
+        return {
+            kind: "block",
+            isError: true,
+            content: `Blocked: loop handler from plugin '${entry.plugin}' failed (${reason}).`,
+        };
+    }
+    logger?.warn("native-loop-events", `plugin '${entry.plugin}' failed on ${entry.event}`, {
+        plugin: entry.plugin,
+        event: entry.event,
+        error: reason,
+    });
+    return {};
+}
+/**
+ * Log which patch fields a handler carried, so a later `applyHistoryPatch`
+ * rejection can be traced back to the plugin that caused it. An empty patch
+ * traces nothing — there is no field to attribute.
+ */
+function tracePatch(entry, value) {
+    // A plain-JavaScript plugin can answer a non-object on any event; there is
+    // then no field to attribute, and reading one must not throw.
+    if (typeof value !== "object" || value === null)
+        return;
+    const patch = value;
+    const fields = TRACED_PATCH_FIELDS.filter((field) => patch[field] !== undefined);
+    if (fields.length === 0)
+        return;
+    getSafeLogger()?.debug("native-loop-events", `plugin '${entry.plugin}' patched ${entry.event}`, {
+        plugin: entry.plugin,
+        event: entry.event,
+        fields,
+    });
+}
+function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "object")
+        return "an object whose kind is not a before_tool outcome";
+    return `a ${typeof value} value`;
+}
+/** What a settled (non-failure) handler answer becomes. */
+function settled(entry, payload, value) {
+    if (entry.event === "before_tool") {
+        // `undefined` is the handler declining to decide, which is an allow.
+        if (value === undefined)
+            return { kind: "allow" };
+        // The plugin boundary, so the answer must be COMPLETE: a `kind` without
+        // the payload it promises (`block`/`terminate` content, `nudge` text) is
+        // malformed, not a decision.
+        if (!isCompleteBeforeToolOutcome(value))
+            return failure(entry, payload, `returned ${describeValue(value)}`);
+        return value;
+    }
+    if (value === undefined)
+        return {};
+    tracePatch(entry, value);
+    return value;
+}
+/**
+ * Wrap one staged plugin registration into a built-in-shaped `HandlerOf<E>`:
+ * same payload, same patch, but with a bounded lifetime, the turn's context,
+ * and a failure that is attributed and never rethrown.
+ */
+export function wrapExternalHandler(entry, getCtx, signal) {
+    return async (payload) => {
+        const settlement = await raceSettlement(entry, payload, { getCtx, signal });
+        // `entry.event` carries the event at runtime; the erased patch is the union
+        // the dispatcher re-narrows, because it registered this handler per event.
+        const answer = settlement.ok
+            ? settled(entry, payload, settlement.value)
+            : failure(entry, payload, settlement.reason);
+        return answer;
+    };
+}

package/dist/native/session/loop-events/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Barrel for the loop-event seam (spec 4.5): the single-file `loop-events.ts`
+ * module became a directory, and this re-exports every name it exported, so
+ * no importer churns.
+ */
+export { type BuildToolResultArgs, buildToolResult, type DenialInfo, type ToolResultMessage } from "../tool-result.ts";
+/**
+ * The external-handler surface (US-002). It is re-exported rather than reached
+ * through `./external-handler` because `check:alias-internals` rejects a VALUE
+ * import of `@/<dir>/<internal>` from `src/`, so the barrel is the only route
+ * US-003's installer and US-004's delivery code can take. Identity matters:
+ * `_externalHandlerDeps` is the object the wrapper reads at dispatch time.
+ */
+export { _externalHandlerDeps, LOOP_HANDLER_TIMEOUT_MS, wrapExternalHandler } from "./external-handler.ts";
+export { createLoopEventRegistry, LOOP_EVENTS, type LoopEventRegistry } from "./registry.ts";
+export type { AfterToolPatch, AfterToolPayload, BeforeToolOutcome, CompleteCallOptions, ExternalHandlerOf, LoopHandlerContext, LoopHandlerEntry, LoopHandlerSet, } from "./types.ts";

package/dist/native/session/loop-events/index.js

@@ -0,0 +1,15 @@
+/**
+ * Barrel for the loop-event seam (spec 4.5): the single-file `loop-events.ts`
+ * module became a directory, and this re-exports every name it exported, so
+ * no importer churns.
+ */
+export { buildToolResult } from "../tool-result.js";
+/**
+ * The external-handler surface (US-002). It is re-exported rather than reached
+ * through `./external-handler` because `check:alias-internals` rejects a VALUE
+ * import of `@/<dir>/<internal>` from `src/`, so the barrel is the only route
+ * US-003's installer and US-004's delivery code can take. Identity matters:
+ * `_externalHandlerDeps` is the object the wrapper reads at dispatch time.
+ */
+export { _externalHandlerDeps, LOOP_HANDLER_TIMEOUT_MS, wrapExternalHandler } from "./external-handler.js";
+export { createLoopEventRegistry, LOOP_EVENTS } from "./registry.js";

package/dist/native/session/loop-events/payload-guard.d.ts

@@ -0,0 +1,9 @@
+interface ArrayRecord {
+    readonly field: string;
+    readonly array: unknown[];
+    readonly saved: readonly unknown[];
+}
+export type ArraySnapshot = readonly ArrayRecord[];
+export declare function snapshotArrays(payload: object): ArraySnapshot;
+export declare function restoreMutated(snapshot: ArraySnapshot, event: string, handlerIndex: number): void;
+export {};

package/dist/native/session/loop-events/payload-guard.js

@@ -0,0 +1,31 @@
+/**
+ * Review #19: the cache boundary judges only RETURNED patches, but handlers
+ * receive the loop's live arrays (history, messages, tools). A handler that
+ * edits one in place would rewrite the transcript and the prompt-cache
+ * prefix unseen. Dispatch snapshots every array field before each handler and
+ * undoes an in-place change afterwards, keeping the SAME array object with
+ * its original elements.
+ *
+ * Not detected: edits INSIDE an element (a message's fields). Deep-freezing
+ * is not an option: the payload is live, and the loop itself pushes onto
+ * `messages` after a follow-up; freezing a clone would break the reference
+ * identity checkPrefixStable relies on.
+ */
+import { getSafeLogger } from "#src/infra/index";
+export function snapshotArrays(payload) {
+    return Object.entries(payload).flatMap(([field, value]) => Array.isArray(value) ? [{ field, array: value, saved: [...value] }] : []);
+}
+export function restoreMutated(snapshot, event, handlerIndex) {
+    for (const { field, array, saved } of snapshot) {
+        const changed = array.length !== saved.length || saved.some((item, i) => array[i] !== item);
+        if (!changed)
+            continue;
+        getSafeLogger()?.warn("native-loop-events", "handler mutated payload in place; restored", {
+            event,
+            handler: handlerIndex,
+            field,
+        });
+        // Deliberate in-place restore: the caller holds this exact array object.
+        array.splice(0, array.length, ...saved);
+    }
+}