bare-agent 0.26.2 → 0.28.0

package/src/provider-anthropic.js

@@ -4,6 +4,7 @@ const https = require('https');
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @param {string} hostname @returns {boolean} */
 function isLoopbackHost(hostname) {
@@ -20,7 +21,11 @@ function isLoopbackHost(hostname) {
  * @property {string} [apiKey] - Anthropic API key (required).
  * @property {string} [model='claude-haiku-4-5-20251001'] - Model ID.
  * @property {string} [baseUrl='https://api.anthropic.com/v1'] - API base (override for proxies/gateways; the request posts to `${baseUrl}/messages`).
- * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`.
+ * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`. NOTE: on its own this rarely helps a tool loop — Anthropic's minimum cacheable prefix is 1024–4096 tokens (model-dependent) and a typical system persona is a few hundred, so it silently never caches. The transcript is where a tool loop's tokens actually live — see `cacheMessages`.
+ * @property {boolean} [cacheMessages=false] - Opt-in TRANSCRIPT caching (BA-1): roll a `cache_control` breakpoint onto the last content block of the last message, so Anthropic caches the whole conversation prefix and the loop stops re-buying it at full price every round. In a tool loop the transcript IS the tool results (file bodies from `shell_read`) and it always ENDS on one, which `_toAnthropicMessage` rebuilds from scratch — so no caller-side seam (`assemble` included) can reach it, and this has to live in the provider. Measured on `claude-sonnet-5` with a ~15k-token tool-result transcript (`poc/ba1-message-caching.mjs`): steady state **$0.0753 → $0.0110 per round, 6.8x cheaper**; round 1 pays a 1.25x cache WRITE once. Off by default — it changes the wire format, so adopters opt in. Overridable per call via `generate(..., { cacheMessages })`. **Interaction:** a destructive `trim`/stash fold that rewrites the transcript PREFIX invalidates the cache (the prefix is the cache key), so a fold must keep the head stable or you re-pay the write premium every round for nothing.
+ * @property {any} [thinking] - Opt-in extended thinking (BA-7), forwarded to `body.thinking` VERBATIM and unvalidated — e.g. `{ type: 'adaptive' }`, or `{ type: 'adaptive', display: 'summarized' }` to surface the reasoning (the default `display` is `'omitted'`). Deliberately opaque: this parameter has already broken once (`budget_tokens` was removed and now 400s on `claude-sonnet-5` / Opus 4.7+), and a library that reshapes it would need a release every time the API moves. Overridable per call via `generate(..., { thinking })`; pass `null` there to suppress an instance default.
+ *
+ *   **MEASURED CAVEAT — this option does not "turn thinking on".** On `claude-sonnet-5` adaptive thinking is ALREADY the default: sending this changed the observed thinking rate not at all (2/10 rounds with it vs 3/10 without — `poc/ba7-adaptive-default.mjs`). Its real use is pinning the mode and reaching `display`/`effort`. The change that mattered is that thinking blocks are now PRESERVED and replayed (see `Message.providerBlocks`), which happens whether or not you ever set this.
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
  */
 
@@ -38,6 +43,13 @@ class AnthropicProvider {
     // Anthropic caches it (unlike OpenAI/Gemini, Anthropic does NOT auto-cache — without this its
     // cache_read/cache_creation tiers are always 0). Default off keeps requests byte-identical to before.
     this.cacheSystem = options.cacheSystem === true;
+    this.cacheMessages = options.cacheMessages === true;
+    // BA-7: forwarded to `body.thinking` VERBATIM — deliberately unvalidated and un-reshaped. This
+    // parameter has already broken once (`budget_tokens` was removed and now 400s on sonnet-5 /
+    // Opus 4.7+; `{type:'adaptive'}` replaced it). A library that parses it would have to ship a
+    // release every time Anthropic moves; passing it through means the caller can always express
+    // the current API. Omit it to keep today's body byte-identical.
+    this.thinking = options.thinking != null ? options.thinking : null;
     // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
     this.exposeErrorBody = options.exposeErrorBody === true;
   }
@@ -76,6 +88,33 @@ class AnthropicProvider {
       system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
     }
 
+    // BA-1: roll a cache breakpoint onto the LAST content block of the LAST message. Anthropic caches the
+    // whole prefix up to the mark, and rolling it forward each round keeps the GROWING transcript cached
+    // — otherwise a tool loop re-buys its entire history at full input price, every single round.
+    //
+    // This MUST live here, not in a caller-side seam: in a tool loop the transcript IS the tool results,
+    // it always ENDS on one, and `_toAnthropicMessage` rebuilds `role:'tool'` messages into fresh
+    // `tool_result` blocks — discarding anything a caller attached. There is no other reachable seam.
+    //
+    // Copy-on-write, deliberately: a caller's `content` array is passed through by reference, so marking
+    // it in place would mutate the caller's own message objects and leave a stale breakpoint behind on
+    // every later round (Anthropic allows at most 4, and a stray one silently shifts the cache key).
+    const cacheMessages = options.cacheMessages != null ? options.cacheMessages === true : this.cacheMessages;
+    if (cacheMessages && msgs.length > 0) {
+      const i = msgs.length - 1;
+      const last = msgs[i];
+      if (Array.isArray(last.content) && last.content.length > 0) {
+        const blocks = last.content.slice();
+        blocks[blocks.length - 1] = { ...blocks[blocks.length - 1], cache_control: { type: 'ephemeral' } };
+        msgs[i] = { ...last, content: blocks };
+      } else if (typeof last.content === 'string' && last.content.length > 0) {
+        msgs[i] = { ...last, content: [{ type: 'text', text: last.content, cache_control: { type: 'ephemeral' } }] };
+      }
+      // An empty-content message gets no mark — there is no block to hang it on, and a synthesized empty
+      // one would be a wire error. Under the cache minimum (1024–4096 tok, model-dependent) Anthropic
+      // silently doesn't cache: harmless, just no saving. Never an error.
+    }
+
     /** @type {Record<string, any>} */
     const body = {
       model: this.model,
@@ -84,6 +123,14 @@ class AnthropicProvider {
       ...(system && { system }),
       ...(options.temperature != null && { temperature: options.temperature }),
     };
+
+    // BA-7 (b). Measured caveat, and it matters: on `claude-sonnet-5` adaptive thinking is ALREADY
+    // the default — sending this changed the thinking rate not at all (2/10 vs 3/10 rounds,
+    // `poc/ba7-adaptive-default.mjs`). So this option does NOT "turn thinking on"; it lets you pin
+    // the mode and reach `display`/`effort`. The fix that actually mattered is the preservation
+    // above, which applies whether or not you ever set this.
+    const thinking = options.thinking !== undefined ? options.thinking : this.thinking;
+    if (thinking) body.thinking = thinking;
     if (tools.length > 0) {
       body.tools = tools.map(t => ({
         name: t.name,
@@ -105,17 +152,34 @@ class AnthropicProvider {
     let text = '';
     /** @type {import('../types').ToolCall[]} */
     const toolCalls = [];
+    // BA-7: everything that is NOT text/tool_use is a block our normalized {text, toolCalls} shape
+    // cannot express — today that means `thinking` and `redacted_thinking`. We used to drop these on
+    // the floor. Anthropic's contract is that they are echoed back UNCHANGED (signature included) when
+    // continuing a tool-use conversation, so they are collected OPAQUELY here: whatever the block is,
+    // we keep its bytes. Deliberately not a `block.type === 'thinking'` check — a future block type
+    // would be silently dropped again, which is the exact bug being fixed.
+    /** @type {any[]} */
+    const nativeBlocks = [];
     for (const block of data.content) {
       if (block.type === 'text') text += block.text;
-      if (block.type === 'tool_use') {
-        toolCalls.push({ id: block.id, name: block.name, arguments: block.input });
-      }
+      else if (block.type === 'tool_use') toolCalls.push({ id: block.id, name: block.name, arguments: block.input });
+      else nativeBlocks.push(block);
     }
 
     return {
       text,
       toolCalls,
       model: data.model || this.model,
+      // BA-6: why generation ended. `max_tokens` here means the API CUT THIS ROUND OFF — the Loop must
+      // not read it as a finished turn, and must not execute any tool call it carries (a complete call
+      // arrives as `tool_use`; one riding a `max_tokens` round was cut off mid-generation).
+      stopReason: normalizeStopReason(data.stop_reason, 'anthropic', { hasToolCalls: toolCalls.length > 0 }),
+      // BA-7: the opaque blocks, tagged so they can only ever be replayed to the model that signed
+      // them. A thinking `signature` is model-bound; on a mismatch we drop them and degrade to the
+      // pre-BA-7 behavior (a lossy request that still succeeds) rather than risk a 400.
+      ...(nativeBlocks.length > 0 && {
+        providerBlocks: { provider: 'anthropic', model: this.model, blocks: nativeBlocks },
+      }),
       // Anthropic's `input_tokens` is ALREADY the uncached remainder (cached tokens are reported
       // separately, not folded in — verified live), so no subtraction here, unlike OpenAI/Gemini.
       usage: {
@@ -135,6 +199,29 @@ class AnthropicProvider {
     console.warn(`[AnthropicProvider] '${this.model}' rejected a non-default 'temperature' (unsupported/deprecated) — retrying without it. Further drops from this provider instance are silent.`);
   }
 
+  /**
+   * BA-7: the provider-native blocks to replay at the FRONT of an assistant turn's content, or `[]`.
+   *
+   * Only ever returns blocks this model itself produced. The tag carries `this.model` (the CONFIGURED
+   * id, not the response's resolved one — those can differ by date suffix, and a mismatch there would
+   * silently disable preservation, which is the very bug class BA-7 exists to close).
+   *
+   * Front, because Anthropic requires `thinking` to lead the content array — the verbatim order we
+   * measured a successful round-trip on (`poc/ba7-thinking-contract.mjs`, R3).
+   *
+   * @param {Message} msg
+   * @returns {any[]}
+   */
+  _nativeBlocks(msg) {
+    const pb = /** @type {any} */ (msg).providerBlocks;
+    if (!pb || pb.provider !== 'anthropic' || !Array.isArray(pb.blocks) || pb.blocks.length === 0) return [];
+    // A thinking signature is bound to the model that issued it. Swap models mid-transcript and these
+    // blocks are not ours to replay: drop them (lossy but valid) rather than send a signature this
+    // model will reject.
+    if (pb.model !== this.model) return [];
+    return pb.blocks;
+  }
+
   /**
    * @param {Message} msg
    * @returns {any}
@@ -155,6 +242,11 @@ class AnthropicProvider {
     if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
       /** @type {any[]} */
       const content = [];
+      // BA-7: thinking blocks lead, then text, then tool_use — this is THE turn the contract is about
+      // (continuing a tool-use conversation). Note the normalized `content`/`tool_calls` stay the
+      // source of truth: we replay only the opaque blocks, never a cached copy of the text, so a
+      // `trim`/`assemble` seam that rewrites this message is not silently undone.
+      content.push(...this._nativeBlocks(msg));
       if (msg.content) content.push({ type: 'text', text: msg.content });
       for (const tc of msg.tool_calls) {
         content.push({
@@ -168,6 +260,16 @@ class AnthropicProvider {
       }
       return { role: 'assistant', content };
     }
+    // A tool-call-free assistant turn can still carry thinking (a final answer, or an earlier turn a
+    // caller replays into a fresh run). Same rule: native blocks lead.
+    if (msg.role === 'assistant') {
+      const native = this._nativeBlocks(msg);
+      if (native.length > 0) {
+        const content = [...native];
+        if (msg.content) content.push({ type: 'text', text: msg.content });
+        return { role: 'assistant', content };
+      }
+    }
     return { role: msg.role, content: msg.content };
   }
 

package/src/provider-gemini.js

@@ -4,6 +4,7 @@ const https = require('https');
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -130,6 +131,15 @@ class GeminiProvider {
       text,
       toolCalls,
       model: data.modelVersion || this.model,
+      // BA-6: `MAX_TOKENS` ⇒ cut off at the output cap. VERIFIED LIVE on `gemini-2.5-flash`
+      // (`poc/ba6-stop-reason-gemini-ollama.mjs`): STOP→end_turn, MAX_TOKENS→max_tokens. An unrecognized
+      // value still falls through to `null` (today's behavior), never to a false truncation.
+      //
+      // Gemini has NO tool_use finish reason — a complete function call comes back as `STOP` (measured).
+      // `hasToolCalls` lets the normalizer report the round for what it was: a round that stopped to CALL
+      // A TOOL, not one the model chose to end. Without it, `stopReason` would say `end_turn` here and
+      // `tool_use` on Anthropic/OpenAI for the identical event.
+      stopReason: normalizeStopReason(data.candidates?.[0]?.finishReason, 'gemini', { hasToolCalls: toolCalls.length > 0 }),
       usage: this._normalizeUsage(data.usageMetadata),
       ...(temperatureDropped && { temperatureDropped: true }),
     };

package/src/provider-ollama.d.ts

@@ -27,7 +27,7 @@ export class OllamaProvider {
      * Generate a response from a local Ollama instance.
      * @param {Message[]} messages - Conversation messages.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
-     * @param {Record<string, any>} [options={}] - Options (temperature).
+     * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`).
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
      */

package/src/provider-ollama.js

@@ -3,6 +3,7 @@
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -30,17 +31,29 @@ class OllamaProvider {
    * Generate a response from a local Ollama instance.
    * @param {Message[]} messages - Conversation messages.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
-   * @param {Record<string, any>} [options={}] - Options (temperature).
+   * @param {Record<string, any>} [options={}] - Options (`temperature`, `maxTokens`).
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
    */
   async generate(messages, tools = [], options = {}) {
+    // Ollama nests generation params under `options` (its `num_predict` is the output cap — the
+    // equivalent of `max_tokens` everywhere else).
+    //
+    // `maxTokens` was NOT forwarded here before, while every other provider honoured it — so a caller
+    // capping output on Ollama was silently ignored and generated unbounded. Found by the BA-6 map
+    // probe: a 16-token cap produced `done_reason: 'stop'` because nothing ever truncated. The map was
+    // right; the cap never reached the wire.
+    /** @type {Record<string, any>} */
+    const genOptions = {
+      ...(options.temperature != null && { temperature: options.temperature }),
+      ...(options.maxTokens != null && { num_predict: options.maxTokens }),
+    };
     /** @type {Record<string, any>} */
     const body = {
       model: this.model,
       messages,
       stream: false,
-      ...(options.temperature != null && { options: { temperature: options.temperature } }),
+      ...(Object.keys(genOptions).length > 0 && { options: genOptions }),
     };
     if (tools.length > 0) {
       body.tools = tools.map(t => ({
@@ -59,16 +72,26 @@ class OllamaProvider {
     });
     const msg = data.message || {};
 
+    /** @type {import('../types').ToolCall[]} */
+    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+      id: tc.id || `call_${Date.now()}`,
+      name: tc.function.name,
+      arguments: typeof tc.function.arguments === 'string'
+        ? JSON.parse(tc.function.arguments)
+        : tc.function.arguments,
+    }));
+
     return {
       text: msg.content || '',
-      toolCalls: (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
-        id: tc.id || `call_${Date.now()}`,
-        name: tc.function.name,
-        arguments: typeof tc.function.arguments === 'string'
-          ? JSON.parse(tc.function.arguments)
-          : tc.function.arguments,
-      })),
+      toolCalls,
       model: data.model || this.model,
+      // BA-6: `length` ⇒ cut off at num_predict. VERIFIED LIVE on qwen2.5:0.5b
+      // (`poc/ba6-stop-reason-gemini-ollama.mjs`): stop→end_turn, length→max_tokens. Lifecycle values
+      // (`load`/`unload`) stay deliberately unmapped rather than forced into the vocabulary.
+      //
+      // Like Gemini, Ollama has NO tool_use done_reason — a complete tool call returns `stop` (measured).
+      // `hasToolCalls` lets the normalizer say so, instead of reporting a tool round as a clean finish.
+      stopReason: normalizeStopReason(data.done_reason, 'ollama', { hasToolCalls: toolCalls.length > 0 }),
       usage: {
         inputTokens: data.prompt_eval_count || 0,
         outputTokens: data.eval_count || 0,

package/src/provider-openai.js

@@ -4,6 +4,7 @@ const https = require('https');
 const http = require('http');
 const { ProviderError } = require('./errors');
 const { requestWithTemperatureFallback } = require('./provider-temperature');
+const { normalizeStopReason } = require('./provider-stop-reason');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -73,14 +74,22 @@ class OpenAIProvider {
     const choice = data.choices[0];
     const msg = choice.message;
 
+    /** @type {import('../types').ToolCall[]} */
+    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: JSON.parse(tc.function.arguments),
+    }));
+
     return {
       text: msg.content || '',
-      toolCalls: (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
-        id: tc.id,
-        name: tc.function.name,
-        arguments: JSON.parse(tc.function.arguments),
-      })),
+      toolCalls,
       model: data.model || this.model,
+      // BA-6: `length` ⇒ cut off at the output cap (normalized to 'max_tokens'). Note OpenAI refuses to
+      // emit a tool call it cannot finish — it 400s instead — so a truncated round here carries no
+      // tool calls at all; the Loop's refusal to execute them is a no-op on this provider, and a
+      // load-bearing guard on Anthropic, which DOES emit the cut-off call.
+      stopReason: normalizeStopReason(choice?.finish_reason, 'openai', { hasToolCalls: toolCalls.length > 0 }),
       usage: this._normalizeUsage(data.usage),
       ...(temperatureDropped && { temperatureDropped: true }),
     };

package/src/provider-stop-reason.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Map a provider's native finish-reason value onto the neutral vocabulary.
+ *
+ * @param {string|null|undefined} raw - the provider's native value (`stop_reason` / `finish_reason` /
+ *   `finishReason` / `done_reason`). Absent or non-string ⇒ `null` (pre-BA-6 behavior).
+ * @param {'anthropic'|'openai'|'gemini'|'ollama'} provider - which table to read.
+ * @param {{hasToolCalls?: boolean}} [ctx] - what the round actually CARRIED. See below: two providers
+ *   cannot express "stopped to call a tool" in their finish-reason field at all, so the round's own
+ *   content is the only place that fact exists.
+ * @returns {string|null} a neutral value, an unrecognized value passed through verbatim, or `null`.
+ */
+export function normalizeStopReason(raw: string | null | undefined, provider: "anthropic" | "openai" | "gemini" | "ollama", ctx?: {
+    hasToolCalls?: boolean;
+}): string | null;
+/**
+ * Did this round get CUT OFF at the output-token cap?
+ *
+ * The one predicate the Loop acts on. Deliberately narrow: `context_exceeded`, `refusal` and
+ * `pause_turn` are all "not a normal finish" but they are NOT output-cap truncations and must not be
+ * folded in here — `pause_turn` in particular is a RESUMABLE state, and erroring on it would break
+ * server-side tool flows that are working exactly as designed.
+ *
+ * Retained for back-compat (it was the Loop's original BA-6 gate). The Loop now routes through
+ * {@link classifyStopReason} instead — `isTruncated(x)` is exactly `classifyStopReason(x) === 'truncated'`.
+ *
+ * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
+ * @returns {boolean}
+ */
+export function isTruncated(stopReason: string | null | undefined): boolean;
+/**
+ * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
+ * @returns {'truncated'|'refusal'|'context_exceeded'|'resume'|null}
+ */
+export function classifyStopReason(stopReason: string | null | undefined): "truncated" | "refusal" | "context_exceeded" | "resume" | null;

package/src/provider-stop-reason.js

@@ -0,0 +1,200 @@
+/**
+ * BA-6 — normalize each provider's native finish-reason field to one neutral vocabulary.
+ *
+ * Every provider tells you WHY generation ended. Before this, bare-agent read the field on none of
+ * them (`grep -rn 'stop_reason\|finish_reason\|done_reason' src/` → zero hits), so a round the API
+ * CUT OFF at the token cap was indistinguishable from one the model chose to end — the Loop's rule is
+ * "no tool calls ⇒ final answer", and a truncation has no tool calls, so it returned as a clean finish
+ * with `error: null`. A truncation was laundered into a completion.
+ *
+ * The neutral vocabulary (what the Loop is allowed to reason about):
+ *
+ *   'end_turn'         the model finished of its own accord — the ONLY clean finish
+ *   'max_tokens'       CUT OFF at the output cap. NOT a finish. Load-bearing (see below).
+ *   'tool_use'         stopped to call a tool, and the call is COMPLETE
+ *   'stop_sequence'    hit a caller-supplied stop string — a legitimate finish
+ *   'refusal'          declined on safety grounds (Anthropic `refusal`, OpenAI `content_filter`, …)
+ *   'pause_turn'       server-side tool loop paused; the caller is expected to RESUME, not to error
+ *   'context_exceeded' ran out of CONTEXT WINDOW (distinct from running out of output budget)
+ *   null               provider didn't say / we don't recognize it
+ *
+ * `null` is the safe default and it is deliberate: an unmapped or absent value reproduces the
+ * pre-BA-6 behavior exactly. A wrong guess therefore degrades to the status quo rather than inventing
+ * a false truncation error on a healthy run. Unknown-but-present values pass through verbatim (a
+ * caller can still see them) but the Loop only ever ACTS on the values above.
+ *
+ * ── Why 'max_tokens' vs 'tool_use' is the load-bearing distinction (measured, not assumed) ──
+ *
+ * `poc/ba6-stop-reason-mapping.mjs`, real API, claude-sonnet-5 + gpt-4o-mini:
+ *
+ *   a COMPLETE tool call ALWAYS arrives tagged 'tool_use' — never 'max_tokens'.
+ *
+ * Anthropic returned `stop_reason: "tool_use"` with intact arguments even at a tight 1024-token cap;
+ * OpenAI refuses outright (HTTP 400) rather than emit a tool call it could not finish. Neither ever
+ * handed back a COMPLETE tool call tagged as truncated.
+ *
+ * The converse is the dangerous case, and it is not hypothetical — it is the BA-4 file-zeroing bug one
+ * layer up: a round tagged 'max_tokens' that CARRIES a tool call carries a tool call that was cut off
+ * mid-generation, whose arguments are missing keys. That is precisely how a `claude-haiku-4-5` worker
+ * emptied a 1789-line file — it hit the output cap mid-`shell_write`, the `content` argument never
+ * arrived, and the truncated call was executed as if whole. So the Loop must NEVER execute the tool
+ * calls of a 'max_tokens' round. Refusing costs nothing legitimate (complete calls come back
+ * 'tool_use') and closes the data-loss path at the protocol layer, for every tool, not just
+ * `shell_write`.
+ */
+
+/** Anthropic `stop_reason` → neutral. */
+const ANTHROPIC = {
+  end_turn: 'end_turn',
+  max_tokens: 'max_tokens',
+  tool_use: 'tool_use',
+  stop_sequence: 'stop_sequence',
+  refusal: 'refusal',
+  pause_turn: 'pause_turn',
+  model_context_window_exceeded: 'context_exceeded',
+};
+
+/** OpenAI (and OpenAI-compatible) `finish_reason` → neutral. */
+const OPENAI = {
+  stop: 'end_turn',
+  length: 'max_tokens',
+  tool_calls: 'tool_use',
+  function_call: 'tool_use',
+  content_filter: 'refusal',
+};
+
+/**
+ * Gemini `finishReason` → neutral. Gemini does NOT tag a function call specially — a complete tool call
+ * comes back as `STOP` with a `functionCall` part (measured live) — so there is no `tool_use` row here
+ * by design. `normalizeStopReason` derives it from `hasToolCalls` instead; see the note there.
+ */
+const GEMINI = {
+  STOP: 'end_turn',
+  MAX_TOKENS: 'max_tokens',
+  SAFETY: 'refusal',
+  RECITATION: 'refusal',
+  BLOCKLIST: 'refusal',
+  PROHIBITED_CONTENT: 'refusal',
+  SPII: 'refusal',
+};
+
+/**
+ * Ollama `done_reason` → neutral. `load`/`unload` are lifecycle values, not completions — they map to
+ * null (unknown) rather than being forced into the vocabulary.
+ */
+const OLLAMA = {
+  stop: 'end_turn',
+  length: 'max_tokens',
+};
+
+const TABLES = {
+  anthropic: ANTHROPIC,
+  openai: OPENAI,
+  gemini: GEMINI,
+  ollama: OLLAMA,
+};
+
+/**
+ * Map a provider's native finish-reason value onto the neutral vocabulary.
+ *
+ * @param {string|null|undefined} raw - the provider's native value (`stop_reason` / `finish_reason` /
+ *   `finishReason` / `done_reason`). Absent or non-string ⇒ `null` (pre-BA-6 behavior).
+ * @param {'anthropic'|'openai'|'gemini'|'ollama'} provider - which table to read.
+ * @param {{hasToolCalls?: boolean}} [ctx] - what the round actually CARRIED. See below: two providers
+ *   cannot express "stopped to call a tool" in their finish-reason field at all, so the round's own
+ *   content is the only place that fact exists.
+ * @returns {string|null} a neutral value, an unrecognized value passed through verbatim, or `null`.
+ */
+function normalizeStopReason(raw, provider, ctx = {}) {
+  if (typeof raw !== 'string' || raw === '') return null;
+  const table = TABLES[provider];
+  if (!table) return raw;
+  // An unrecognized-but-present value passes through: the caller can still SEE it, and the Loop only
+  // acts on the known vocabulary — so a new upstream value can never be mistaken for a truncation.
+  // Own-property only (mirror of classifyStopReason): `raw` is a provider/proxy-supplied field, so a
+  // value like 'toString'/'constructor' would otherwise resolve `table[raw]` to an inherited
+  // Object.prototype function (truthy) and be returned in place of the verbatim string.
+  const mapped = Object.prototype.hasOwnProperty.call(table, raw) ? table[raw] : raw;
+
+  // GEMINI AND OLLAMA HAVE NO `tool_use` FINISH REASON (both measured live: Gemini returns
+  // `finishReason: STOP` and Ollama `done_reason: 'stop'` on a round that emitted a complete function
+  // call). Reported verbatim, a round that stopped TO CALL A TOOL would come back as `end_turn` — "the
+  // model finished of its own accord" — on 2 of 5 providers and `tool_use` on the other 3.
+  //
+  // That is the BA-6 defect class in miniature: a round that is NOT a finish, reporting as a finish.
+  // An adopter branching on `stopReason === 'end_turn'` would be right on Anthropic/OpenAI and wrong
+  // on Gemini/Ollama. So derive it from what the round CARRIED — the model did stop to call a tool,
+  // and that is a report, not an invention.
+  //
+  // Narrow on purpose: only ever promotes `end_turn` → `tool_use`. It cannot touch `max_tokens` (a
+  // truncated round carrying a half-generated call must stay TRUNCATED — that is BA-4's mechanism),
+  // nor `refusal`/`pause_turn`/`context_exceeded`, nor an unrecognized passthrough value.
+  if (mapped === 'end_turn' && ctx.hasToolCalls === true) return 'tool_use';
+  return mapped;
+}
+
+/**
+ * Did this round get CUT OFF at the output-token cap?
+ *
+ * The one predicate the Loop acts on. Deliberately narrow: `context_exceeded`, `refusal` and
+ * `pause_turn` are all "not a normal finish" but they are NOT output-cap truncations and must not be
+ * folded in here — `pause_turn` in particular is a RESUMABLE state, and erroring on it would break
+ * server-side tool flows that are working exactly as designed.
+ *
+ * Retained for back-compat (it was the Loop's original BA-6 gate). The Loop now routes through
+ * {@link classifyStopReason} instead — `isTruncated(x)` is exactly `classifyStopReason(x) === 'truncated'`.
+ *
+ * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
+ * @returns {boolean}
+ */
+function isTruncated(stopReason) {
+  return stopReason === 'max_tokens';
+}
+
+/**
+ * BA-13 — classify a round's NEUTRAL stop reason into the terminal ACTION the Loop must take.
+ *
+ * BA-6 short-circuited exactly one non-clean stop reason (`max_tokens`). Every OTHER non-clean reason
+ * — `refusal`, `context_exceeded`, `pause_turn` — fell through the Loop's "no tool calls ⇒ final
+ * answer" rule and was laundered into a clean `error: null` empty success (the BA-4/5/6/7 bug class:
+ * an under-modeled boundary round rounding optimistically toward "done"). A `RECITATION` refusal fires
+ * on entirely BENIGN prompts, so this was reachable on ordinary runs, and it propagated up `recurse`'s
+ * agent tree as a converged sub-task.
+ *
+ * One table with an EXPLICIT pass-through default replaces the single `if (isTruncated)` — the BA-7
+ * lesson ("don't parse-key on a closed set") applied to termination: BA-6 added one leg, BA-13 adds
+ * two terminals plus one resume, and the NEXT new stop reason degrades to pass-through (status quo)
+ * rather than re-breeding the bug.
+ *
+ *   'truncated'         `max_tokens` — cut off at the output cap (BA-6). Loop returns `error:'truncated:max_tokens'`.
+ *   'refusal'           declined on safety grounds. Loop returns `error:'refusal'` + partial text.
+ *   'context_exceeded'  ran out of context window. Loop returns `error:'context_exceeded'` + partial text.
+ *   'resume'            `pause_turn` — a RESUMABLE server-tool pause. NOT terminal, NOT an error: the
+ *                       Loop CONTINUES the round loop (bounded by HARD_ROUND_LIMIT / the gate's maxTurns).
+ *   null                pass-through: `end_turn` / `stop_sequence` / `tool_use` / an unrecognized value /
+ *                       absent. The Loop's existing tool-exec / final-answer logic runs unchanged.
+ *
+ * NB: `tool_use` is already derived by {@link normalizeStopReason} from what the round carried, so it
+ * needs no row here — a round that stopped to call a complete tool passes through to tool execution.
+ */
+const TERMINAL_ACTIONS = /** @type {Record<string, 'truncated'|'refusal'|'context_exceeded'|'resume'>} */ ({
+  max_tokens: 'truncated',
+  refusal: 'refusal',
+  context_exceeded: 'context_exceeded',
+  pause_turn: 'resume',
+});
+/**
+ * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
+ * @returns {'truncated'|'refusal'|'context_exceeded'|'resume'|null}
+ */
+function classifyStopReason(stopReason) {
+  if (typeof stopReason !== 'string') return null;
+  // Own-property only: `normalizeStopReason` passes an unrecognized value through verbatim, so a
+  // provider/proxy emitting stop_reason:'toString'/'constructor'/etc. would otherwise resolve to an
+  // inherited Object.prototype function (truthy) and be mistaken for a terminal action.
+  return Object.prototype.hasOwnProperty.call(TERMINAL_ACTIONS, stopReason)
+    ? TERMINAL_ACTIONS[stopReason]
+    : null;
+}
+
+module.exports = { normalizeStopReason, isTruncated, classifyStopReason };

package/src/recurse-retrieval.d.ts

@@ -143,7 +143,7 @@ export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts:
 /**
  * Build a SCAN slice-source backed by a litectx-RESIDENT corpus (facts/episodes the agent already accrued) —
  * the §10-step-7 deferral un-blocked by litectx 0.26's `enumerate` verb (spec:
- * docs/01-product/litectx-enumerate-spec.md). Returns the generic async slice-source recurse's scan reads: a
+ * docs/01-product/prd.md). Returns the generic async slice-source recurse's scan reads: a
  * `() => Promise<Slice[]>` that pages through EVERY row of `kind` via `enumerate` (exhaustive — the rank-free
  * read `recall` structurally cannot do) and maps each to `{id: item.path, text: item.body}`. recurse stays
  * litectx-agnostic: it depends on this source SHAPE, never on litectx (same stance as `remember`'s Store

package/src/recurse-retrieval.js

@@ -16,7 +16,7 @@
 //
 // THE CORPUS FOR SCAN IS A GENERIC ARRAY SLICE-SOURCE (`opts.corpus`), NOT litectx: litectx has no exhaustive,
 // rank-free enumerate verb today (every read is FTS-gated). The "corpus that already LIVES in litectx" case
-// waits on the litectx `enumerate` verb (docs/01-product/litectx-enumerate-spec.md) and drops in behind this
+// waits on the litectx `enumerate` verb (docs/01-product/prd.md) and drops in behind this
 // same slice-source socket with ZERO recurse changes — the same backend-agnostic stance as `remember`'s Store
 // socket. Composes AROUND a Loop; NEVER imported by loop.js.
 
@@ -326,7 +326,7 @@ const ENUM_PAGE = 200;
 /**
  * Build a SCAN slice-source backed by a litectx-RESIDENT corpus (facts/episodes the agent already accrued) —
  * the §10-step-7 deferral un-blocked by litectx 0.26's `enumerate` verb (spec:
- * docs/01-product/litectx-enumerate-spec.md). Returns the generic async slice-source recurse's scan reads: a
+ * docs/01-product/prd.md). Returns the generic async slice-source recurse's scan reads: a
  * `() => Promise<Slice[]>` that pages through EVERY row of `kind` via `enumerate` (exhaustive — the rank-free
  * read `recall` structurally cannot do) and maps each to `{id: item.path, text: item.body}`. recurse stays
  * litectx-agnostic: it depends on this source SHAPE, never on litectx (same stance as `remember`'s Store

package/src/recurse-synthesize.js

@@ -62,8 +62,17 @@ async function mergeReduce(task, results, opts) {
   if (typeof out.error === 'string' && out.error.startsWith('halt:')) {
     throw new HaltError('[synthesize] merge halted by governance', { rule: out.error.slice('halt:'.length) });
   }
-  // A non-halt fault (e.g. provider error) is non-fatal here — fall back to the lossless concat rather than
-  // losing the partials entirely. recurse still reports honest completeness via its own paths.
+  // A non-halt fault (e.g. provider error, deny short-circuit, the hard round limit) is non-fatal here — fall
+  // back to the LOSSLESS concat rather than losing the partials entirely. recurse still reports honest
+  // completeness via its own paths.
+  //
+  // Branch on `out.error`, NOT on the falsiness of `out.text` (BA-5). Since the Loop now preserves the text a
+  // bounded run produced, a faulted merge returns its PARTIAL, aborted prose — so `out.text || concat` would
+  // silently ship that fragment as the synthesized answer and every child result would be lost. Proven
+  // reachable: the merge Loop registers no tools, so a hallucinated tool call is fed back as
+  // `[Loop] Unknown tool` and the round loop CONTINUES — round 1 emits prose, round 2 dies, and the fallback
+  // never fires. `error` is the sole success signal; text-falsiness never was one.
+  if (out.error) return concatReduce(results);
   return out.text || concatReduce(results);
 }
 

package/src/recurse.js

@@ -708,7 +708,7 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
  * never folded into the count as a zero; a governance HaltError mid-scan → clean incomplete.
  *
  * The corpus is the generic array slice-source `opts.corpus`. Absent it, scan has nothing to read — litectx's
- * resident-corpus enumerate path is deferred (docs/01-product/litectx-enumerate-spec.md) — so we return an
+ * resident-corpus enumerate path is deferred (docs/01-product/prd.md) — so we return an
  * honest incomplete, never a fabricated zero.
  * @param {string} task
  * @param {RecurseCtx} ctx