bare-agent 0.33.0 → 0.33.1

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.33.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
+> v0.33.1 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -817,11 +817,11 @@ new CLIPipe({ command: 'claude', args: ['-p', '--model', 'sonnet'], toolProtocol
 **CLIPipe NATIVE tool mode (BA-16, `toolProtocol:'claude-mcp'`).** The claude CLI has a real tool channel; native mode uses it instead of emulating one. The CLI runs its OWN multi-turn session per `generate()` call and executes your `tools` natively over an MCP bridge that calls back into your in-process `execute` closures. Because the CLI owns the inner cycle, the Loop's per-round machinery cannot run — so the governance you'd wire on `Loop` moves to the **provider**, at the one seam every tool call crosses:
 - `policy` — the SAME `(tool, args, ctx) => true|string` chokepoint as `Loop({policy})`, so a wired `wireGate(gate).policy` writes **audit rows of identical shape, zero gate changes**. A deny is a tool result (advisory); the handler never runs. **Required here** — a `Loop({policy})` in native mode would be a fence that is silently not there, so the Loop throws.
 - `maxConsecutiveDenials` (3) / `maxIdenticalToolErrors` (3) — BA-11/BA-12 guards at the bridge, same narrowest triggers; end the session `denied:<tool>` / `stuck:<tool>`.
-- `maxTurns` — maps to the CLI's `--max-turns`; the bound stop is `error:'max_turns'`, never a silent success.
-- `onTurn` — streams each completed turn's usage (four cache tiers, `costUsd:null` — the CLI prices the session) as it arrives, then one closing `kind:'session'` event with the authoritative total. Shape mirrors `onLlmResult`, so `wireGate(gate).onLlmResult` drops in; when wired the Loop skips its own forward (billed once, never starved).
+- `maxTurns` — a bound on **assistant/LLM turns**, the SAME unit as the Loop path, so one number means one thing on both surfaces (BA-17). NOT a tool-call count: one turn can fire a dozen parallel tool calls and still be one turn (measured: 12 calls across 2 turns, inside `--max-turns 3`). Enforced twice — the CLI's own `--max-turns` stops cleanly at N (and emits the result event that carries the session's real cost), plus a parent-side counter that kills the session if a turn beyond N is ever seen, since that flag is undocumented in `claude --help`. The stop is `error:'max_turns'` + `stopReason:'max_turns'` and **carries the last turn's text forward** — the CLI reports `result:null` on a bounded session, so an unfixed build returned `text:''`.
+- `onTurn` — fires once per **assistant turn** (BA-17: the CLI emits a separate stream event per content *block*, all repeating that message's usage — firing per event inflated a caller's turn axis ~5–7× and its token axis 5.04×), carrying four cache tiers and `costUsd:null` since the CLI prices the session, not the turn. Then one closing `kind:'session'` event carrying the authoritative cost **and the token residual** — a turn's `message.usage` is a snapshot taken at its first block and never revised (a turn that emitted ~816 output tokens reported 2), so the closing event makes the streamed tiers add up to exactly the CLI's own session total. Shape mirrors `onLlmResult`, so `wireGate(gate).onLlmResult` drops in; when wired the Loop skips its own forward (billed once, never starved).
 - `sessionTimeout` (600s) / `bridgeTimeoutMs` (120s) — whole-session and per-handler ceilings.
 
-`GenerateResult.session` (`{turns, toolCalls, error, usageReported}`) carries what really happened; `metrics.sessionTurns` reports the real turn count so a 14-turn session never reads as one round. A terminal the CLI detects inside the session (bound, guard, or a **broken tool bridge** — a dead bridge still ends `subtype:'success'`, so it is caught parent-side by attempted-vs-served tool calls) surfaces as the run's `error`, never a laundered clean finish. `assemble`/`trim`/`cacheMessages` and a Loop-level `policy` all THROW at construction in native mode (no silently-dead knobs — the CLI owns the transcript). The bridge is a unix socket (0600 in a 0700 dir), never a listening port. Claude-only for now; the CLI-specific parts live in `src/provider-clipipe-mcp.js` + `src/mcp-bridge-stub.js` behind the same seam as emulation.
+`GenerateResult.session` (`{turns, toolCalls, error, usageReported}`) carries what really happened; `metrics.sessionTurns` reports the real turn count — assistant *messages*, not stream events — so a 14-turn session never reads as one round, and a 2-turn session never reads as 14. A terminal the CLI detects inside the session (bound, guard, or a **broken tool bridge** — a dead bridge still ends `subtype:'success'`, so it is caught parent-side by attempted-vs-served tool calls) surfaces as the run's `error`, never a laundered clean finish. `assemble`/`trim`/`cacheMessages` and a Loop-level `policy` all THROW at construction in native mode (no silently-dead knobs — the CLI owns the transcript). The bridge is a unix socket (0600 in a 0700 dir), never a listening port. Claude-only for now; the CLI-specific parts live in `src/provider-clipipe-mcp.js` + `src/mcp-bridge-stub.js` behind the same seam as emulation.
 
 All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, costUsd? }`. The optional `model` (v0.16.1+) is the id the response was produced by — Loop prefers it over `provider.model` for cost accounting. By default CLIPipe returns `toolCalls: []` and zero usage (CLI tools don't report tokens) and omits `model`. **Structured output (v0.26.0+):** set `parse: 'claude-json'` (a preset for `claude -p --output-format json`) — or a `(stdout) => Partial<GenerateResult>` function for any other CLI — and CLIPipe maps the CLI's JSON envelope onto real `usage`, `model`, and `costUsd`, throwing `ProviderError` on a malformed/error envelope (never a silent raw-text fall-back). `costUsd` (optional `GenerateResult` field) is an **authoritative** per-call price the provider reports itself; when finite the Loop prefers it over the internal rate-table `estimateCost`, so a CLI-piped run enforces a bareguard USD cap with no local pricing table (a `0` counts as priced, distinct from null/unpriced). `toolCalls` stays `[]` regardless (CLIPipe is tool-free).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "files": [
     "index.js",
     "index.d.ts",

package/src/provider-clipipe-mcp.d.ts

@@ -89,6 +89,21 @@ export function resolveSessionError(facts: {
 /**
  * Line-oriented processor for the CLI's `stream-json` stdout.
  *
+ * ONE TURN IS ONE ASSISTANT MESSAGE, NOT ONE EVENT (BA-17). Measured on the real wire: the CLI
+ * emits a SEPARATE `assistant` event per content BLOCK of the same message, and every one of them
+ * repeats that message's `usage` verbatim — one 13-block message arrived as 13 events carrying the
+ * same numbers. Treating each event as a turn is wrong on both axes a caller meters:
+ *   - the TURN axis  — a caller whose attempt bound is an LLM-turn count sees 14 "turns" for 2 real
+ *                      ones (measured 7×; 4.4× on the adopter's failing run), so its net guillotines
+ *                      the session at a fraction of the allowance it advertised;
+ *   - the TOKEN axis — the same message's usage is added once per block (measured 5.04× inflated
+ *                      against the CLI's own session total), so a budget cap fires early on tokens
+ *                      that were never spent.
+ * So a RUN of consecutive events sharing `message.id` is ONE turn: usage is recorded once and one
+ * `onTurn` fires. Adjacent-run dedup, not a Set — an id that somehow recurred later must still count
+ * as a new turn (dropping a real turn is the failure that matters). An event with NO id degrades to
+ * one-turn-per-event: the pre-BA-17 behaviour, never a collapse of the whole session into one turn.
+ *
  * FRAMING IS SYNCHRONOUS. The obvious shape — an `async` stdout handler that `await`s `onTurn`
  * inside its parse loop — has a data-corruption bug: while the `await` is suspended, the next
  * `'data'` event re-enters the handler and mutates the SHARED line buffer, so the suspended parse
@@ -104,18 +119,32 @@ export function resolveSessionError(facts: {
  * @param {any} o.ctx
  * @param {number} o.startedAt
  * @param {(err: Error) => void} o.onHalt - called if a forwarded `onTurn` throws a HaltError.
+ * @param {number|null} [o.turnCap] - BA-17 backstop: fires `onLimit` the moment a turn BEYOND this
+ *   many is observed. Deliberately not `>=`: `--max-turns` is passed to the CLI too, and when it
+ *   works (measured: it does, and it counts assistant turns) the CLI ends the session ITSELF at the
+ *   cap and emits its `result` event — which is the only place the authoritative session cost
+ *   arrives. Killing the session at exactly N would throw that figure away on every bounded run. So
+ *   this fires ONLY on an overrun, i.e. only if the flag ever stops working — it is undocumented in
+ *   `claude --help`, so the guarantee cannot rest on it alone.
+ * @param {(() => void)} [o.onLimit] - called once when `turnCap` is exceeded.
  */
-export function createSessionStream({ onTurn, ctx, startedAt, onHalt }: {
+export function createSessionStream({ onTurn, ctx, startedAt, onHalt, turnCap, onLimit }: {
     onTurn: Function | null;
     ctx: any;
     startedAt: number;
     onHalt: (err: Error) => void;
+    turnCap?: number | null | undefined;
+    onLimit?: (() => void) | undefined;
 }): {
     /** Feed a stdout chunk. Pure synchronous framing — never awaits. */
     feed(chunk: Buffer | string): void;
     /** Await every queued per-turn forward — call before resolving the session. */
     flush(): Promise<void>;
     readonly turns: import("../types").Usage[];
+    /** Assistant TURNS observed — including any that carried no usage. */
+    readonly turnCount: number;
+    /** The last turn's text. The work a bounded/guard-stopped session still did (BA-5). */
+    readonly lastText: string;
     readonly attempted: number;
     readonly final: any;
 };

package/src/provider-clipipe-mcp.js

@@ -257,6 +257,13 @@ const SUBTYPE_MAP = {
   error_during_execution: { stopReason: null, error: 'session_error' },
 };
 
+/**
+ * Terminals WE impose that ARE stop reasons in the neutral vocabulary. A guard terminal
+ * (`denied:`/`stuck:`) is deliberately absent — those are faults, not stop reasons.
+ * @type {Record<string, string>}
+ */
+const TERMINAL_STOP = { max_turns: 'max_turns' };
+
 /**
  * @param {string|null|undefined} subtype
  * @returns {{stopReason: string|null, error: string|null}}
@@ -291,7 +298,15 @@ function classifySubtype(subtype) {
  */
 function resolveSessionError(facts) {
   const fromSubtype = classifySubtype(facts.subtype);
-  if (facts.terminal) return { stopReason: fromSubtype.stopReason, error: facts.terminal };
+  if (facts.terminal) {
+    // A terminal WE imposed kills the session before its `result` event, so there is no subtype to
+    // read a stop reason from. Where the terminal IS a stop reason in the neutral vocabulary, say so
+    // — a consumer branching on `stopReason` must not see `null` for a bound it asked for.
+    // Own-property only: same proto-key footgun as SUBTYPE_MAP.
+    const named = Object.prototype.hasOwnProperty.call(TERMINAL_STOP, facts.terminal)
+      ? TERMINAL_STOP[facts.terminal] : null;
+    return { stopReason: named || fromSubtype.stopReason, error: facts.terminal };
+  }
   const bridgeBroken = facts.bridgeDown
     || (Number.isFinite(facts.attempted) && Number.isFinite(facts.served) && facts.attempted > facts.served);
   if (bridgeBroken) return { stopReason: fromSubtype.stopReason, error: 'bridge-failed' };
@@ -302,6 +317,21 @@ function resolveSessionError(facts) {
 /**
  * Line-oriented processor for the CLI's `stream-json` stdout.
  *
+ * ONE TURN IS ONE ASSISTANT MESSAGE, NOT ONE EVENT (BA-17). Measured on the real wire: the CLI
+ * emits a SEPARATE `assistant` event per content BLOCK of the same message, and every one of them
+ * repeats that message's `usage` verbatim — one 13-block message arrived as 13 events carrying the
+ * same numbers. Treating each event as a turn is wrong on both axes a caller meters:
+ *   - the TURN axis  — a caller whose attempt bound is an LLM-turn count sees 14 "turns" for 2 real
+ *                      ones (measured 7×; 4.4× on the adopter's failing run), so its net guillotines
+ *                      the session at a fraction of the allowance it advertised;
+ *   - the TOKEN axis — the same message's usage is added once per block (measured 5.04× inflated
+ *                      against the CLI's own session total), so a budget cap fires early on tokens
+ *                      that were never spent.
+ * So a RUN of consecutive events sharing `message.id` is ONE turn: usage is recorded once and one
+ * `onTurn` fires. Adjacent-run dedup, not a Set — an id that somehow recurred later must still count
+ * as a new turn (dropping a real turn is the failure that matters). An event with NO id degrades to
+ * one-turn-per-event: the pre-BA-17 behaviour, never a collapse of the whole session into one turn.
+ *
  * FRAMING IS SYNCHRONOUS. The obvious shape — an `async` stdout handler that `await`s `onTurn`
  * inside its parse loop — has a data-corruption bug: while the `await` is suspended, the next
  * `'data'` event re-enters the handler and mutates the SHARED line buffer, so the suspended parse
@@ -317,11 +347,28 @@ function resolveSessionError(facts) {
  * @param {any} o.ctx
  * @param {number} o.startedAt
  * @param {(err: Error) => void} o.onHalt - called if a forwarded `onTurn` throws a HaltError.
+ * @param {number|null} [o.turnCap] - BA-17 backstop: fires `onLimit` the moment a turn BEYOND this
+ *   many is observed. Deliberately not `>=`: `--max-turns` is passed to the CLI too, and when it
+ *   works (measured: it does, and it counts assistant turns) the CLI ends the session ITSELF at the
+ *   cap and emits its `result` event — which is the only place the authoritative session cost
+ *   arrives. Killing the session at exactly N would throw that figure away on every bounded run. So
+ *   this fires ONLY on an overrun, i.e. only if the flag ever stops working — it is undocumented in
+ *   `claude --help`, so the guarantee cannot rest on it alone.
+ * @param {(() => void)} [o.onLimit] - called once when `turnCap` is exceeded.
  */
-function createSessionStream({ onTurn, ctx, startedAt, onHalt }) {
+function createSessionStream({ onTurn, ctx, startedAt, onHalt, turnCap = null, onLimit = () => {} }) {
   let buf = '';
   let attempted = 0;
   let final = null;
+  /** Adjacent-run dedup key: the `message.id` of the turn currently being emitted. */
+  let turnId = /** @type {string|null} */ (null);
+  /** Has the CURRENT turn already contributed its usage? Blocks of one message repeat it. */
+  let turnMetered = false;
+  let turnCount = 0;
+  let limitFired = false;
+  /** Text of the current turn, and the last turn that produced any — BA-5 work preservation. */
+  let curText = '';
+  let lastText = '';
   /** @type {import('../types').Usage[]} */ const turns = [];
   /** @type {any[]} */ const queue = [];
   /** @type {Promise<void>|null} */ let draining = null;
@@ -367,29 +414,59 @@ function createSessionStream({ onTurn, ctx, startedAt, onHalt }) {
           }
         }
 
-        if (ev.type === 'assistant' && ev.message && ev.message.usage) {
-          const u = ev.message.usage;
-          /** @type {import('../types').Usage} */
-          const usage = {
-            inputTokens: Number(u.input_tokens) || 0,
-            outputTokens: Number(u.output_tokens) || 0,
-          };
-          // Omit an absent tier rather than emit a synthetic 0 (per the Usage contract).
-          if (Number.isFinite(u.cache_read_input_tokens)) usage.cacheReadTokens = u.cache_read_input_tokens;
-          if (Number.isFinite(u.cache_creation_input_tokens)) usage.cacheCreationTokens = u.cache_creation_input_tokens;
-          turns.push(usage);
-          // Stream it: a session that dies mid-run must already have surfaced every completed turn's
-          // spend, or the gate loses it. Queued (not awaited here) so framing cannot race the buffer.
-          if (onTurn) queue.push({
-            model: (ev.message && ev.message.model) || null,
-            provider: 'clipipe',
-            usage,
-            costUsd: null, // the CLI prices the SESSION, not the turn — explicitly unpriced, never a synthetic 0.
-            pricing: 'unpriced',
-            durationMs: Date.now() - startedAt,
-            ctx, // what a wired gate records spend against — same as the Loop's onLlmResult.
-            kind: 'turn',
-          });
+        if (ev.type === 'assistant' && ev.message) {
+          // Is this event the start of a NEW assistant turn, or another block of the current one?
+          // No id at all ⇒ its own turn (degrade to the pre-BA-17 shape, never collapse into one).
+          const id = (typeof ev.message.id === 'string' && ev.message.id) ? ev.message.id : null;
+          if (id === null || id !== turnId) {
+            turnId = id;
+            turnMetered = false;
+            curText = '';
+            turnCount++;
+            // The overrun backstop. `>` not `>=`, so a CLI that honours --max-turns keeps its clean
+            // exit (and with it the only report of the session's real cost).
+            if (!limitFired && Number.isFinite(turnCap) && Number(turnCap) > 0 && turnCount > Number(turnCap)) {
+              limitFired = true;
+              onLimit();
+            }
+          }
+
+          // BA-5: keep the turn's own words, so a bound/guard stop still returns the work done. The
+          // CLI reports `result: null` on a bounded session — measured — so this is the ONLY source.
+          for (const block of (ev.message.content || [])) {
+            if (block && block.type === 'text' && typeof block.text === 'string' && block.text) {
+              curText += block.text;
+              lastText = curText;
+            }
+          }
+
+          // Usage rides on EVERY block-event of the message; count it once per turn. Read on any
+          // event of the turn (not just the first) — the first block need not be the one carrying it.
+          if (ev.message.usage && !turnMetered) {
+            turnMetered = true;
+            const u = ev.message.usage;
+            /** @type {import('../types').Usage} */
+            const usage = {
+              inputTokens: Number(u.input_tokens) || 0,
+              outputTokens: Number(u.output_tokens) || 0,
+            };
+            // Omit an absent tier rather than emit a synthetic 0 (per the Usage contract).
+            if (Number.isFinite(u.cache_read_input_tokens)) usage.cacheReadTokens = u.cache_read_input_tokens;
+            if (Number.isFinite(u.cache_creation_input_tokens)) usage.cacheCreationTokens = u.cache_creation_input_tokens;
+            turns.push(usage);
+            // Stream it: a session that dies mid-run must already have surfaced every completed turn's
+            // spend, or the gate loses it. Queued (not awaited here) so framing cannot race the buffer.
+            if (onTurn) queue.push({
+              model: ev.message.model || null,
+              provider: 'clipipe',
+              usage,
+              costUsd: null, // the CLI prices the SESSION, not the turn — explicitly unpriced, never a synthetic 0.
+              pricing: 'unpriced',
+              durationMs: Date.now() - startedAt,
+              ctx, // what a wired gate records spend against — same as the Loop's onLlmResult.
+              kind: 'turn',
+            });
+          }
         }
 
         if (ev.type === 'result') final = ev;
@@ -399,6 +476,10 @@ function createSessionStream({ onTurn, ctx, startedAt, onHalt }) {
     /** Await every queued per-turn forward — call before resolving the session. */
     async flush() { if (draining) await draining; await drain(); },
     get turns() { return turns; },
+    /** Assistant TURNS observed — including any that carried no usage. */
+    get turnCount() { return turnCount; },
+    /** The last turn's text. The work a bounded/guard-stopped session still did (BA-5). */
+    get lastText() { return lastText; },
     get attempted() { return attempted; },
     get final() { return final; },
   };
@@ -452,11 +533,18 @@ function runSession(opts) {
     const child = spawn(command, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
     let stderr = '', settled = false;
     /** @type {Error|null} */ let turnHalt = null;
+    /** @type {string|null} A terminal WE imposed from the stream (today: the BA-17 turn backstop). */
+    let terminal = null;
     const started = Date.now();
 
     /** Kill the session now — a guard tripped or governance halted mid-flight. */
     const abort = () => { try { child.kill('SIGTERM'); } catch (_) { /* already gone */ } };
-    const stream = createSessionStream({ onTurn, ctx, startedAt: started, onHalt: (err) => { turnHalt = err; abort(); } });
+    const stream = createSessionStream({
+      onTurn, ctx, startedAt: started,
+      onHalt: (err) => { turnHalt = err; abort(); },
+      turnCap: Number.isFinite(maxTurns) ? maxTurns : null,
+      onLimit: () => { terminal = 'max_turns'; abort(); },
+    });
 
     const done = async (extra = {}) => {
       if (settled) return;
@@ -465,7 +553,11 @@ function runSession(opts) {
       // Flush queued per-turn forwards before resolving — a session that ends while a forward is
       // pending must still surface that turn's spend to the gate (F12/F18).
       try { await stream.flush(); } catch (_) { /* onTurn failures are surfaced in-drain, never fatal */ }
-      resolve({ turns: stream.turns, final: stream.final, stderr, ms: Date.now() - started, turnHalt, attempted: stream.attempted, ...extra });
+      resolve({
+        turns: stream.turns, turnCount: stream.turnCount, lastText: stream.lastText,
+        final: stream.final, stderr, ms: Date.now() - started, turnHalt, terminal,
+        attempted: stream.attempted, ...extra,
+      });
     };
 
     const timer = setTimeout(() => {

package/src/provider-clipipe.d.ts

@@ -68,8 +68,16 @@ export type CLIPipeOptions = {
      */
     onTurn?: Function | undefined;
     /**
-     * - (native mode) Maps to the CLI's `--max-turns`. The bound stop is NAMED
-     * (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
+     * - (native mode) Bound on ASSISTANT/LLM TURNS — the same unit as the
+     * Loop path's turn bound, so a caller's `maxTurns` means one thing on both surfaces (BA-17). NOT a
+     * tool-call count: a single turn may issue a dozen parallel tool calls and still be one turn
+     * (measured: 12 calls across 2 turns, well inside `--max-turns 3`). Enforced twice on purpose —
+     * the CLI's own `--max-turns` stops the session cleanly at N and emits its result event (the only
+     * report of the session's real cost), and a parent-side counter kills it if a turn beyond N is
+     * ever observed, since that flag is undocumented in `claude --help` and a rename would otherwise
+     * silently unbound the session. Either way the stop is NAMED (`session.error:'max_turns'`,
+     * `stopReason:'max_turns'`) and carries the last turn's text forward, never a silent clean success
+     * and never an empty result.
      */
     maxTurns?: number | undefined;
     /**
@@ -107,65 +115,6 @@ export type CLIPipeOptions = {
      */
     probeCapability?: boolean | undefined;
 };
-/** @typedef {import('../types').Message} Message */
-/** @typedef {import('../types').ToolDef} ToolDef */
-/** @typedef {import('../types').GenerateResult} GenerateResult */
-/**
- * @typedef {object} CLIPipeOptions
- * @property {string} [command] - CLI command to spawn (required).
- * @property {string[]} [args=[]] - Arguments to pass to the command.
- * @property {string} [cwd] - Working directory for the child process.
- * @property {Record<string, string>} [env] - Environment variables for the child process.
- * @property {number} [timeout=30000] - Timeout in milliseconds.
- * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
- * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
- * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
- * @property {'claude'|'claude-mcp'} [toolProtocol] - Opt into TOOL MODE. Two modes, and the choice is
- *   about COST, not capability. `'claude-mcp'` (BA-16, NATIVE — prefer this on the claude CLI): one CLI
- *   session per call, the caller's `tools` exposed to it as a real MCP server whose handlers call back
- *   into your own in-process closures. The CLI owns the inner cycle and caches its transcript
- *   session-side. `'claude'` (v0.32.0, EMULATION): one CLI spawn per round with the whole transcript
- *   re-rendered and re-sent, parsed back through a JSON envelope. Emulation re-buys the full prefix
- *   every turn, which the adopter measured at **$0.25–0.55/round** against **~$0.006/turn** native — so
- *   it is the right instrument only for a CLI with NO MCP support, not a default. NOT claimed for
- *   native: better output quality (n=2 suggestive evidence exists and is deliberately unminted).
- *   Native mode sets {@link CLIPipeProvider#ownsCycle}, which makes the Loop REFUSE options it could
- *   never honor (`assemble`/`trim`/`cacheMessages`, and a Loop-level `policy`) instead of leaving them
- *   silently dead. See the native-only properties below.
- * @property {(tool: string, args: any, ctx?: any) => any} [policy] - (native mode) The gate, same contract as `Loop({policy})`: only `true`
- *   allows, a string is the deny reason fed back verbatim, a thrown `HaltError` is a clean governance
- *   exit. REQUIRED here rather than on the Loop, because in native mode no tool call ever reaches the
- *   Loop — a `Loop({policy})` would be a fence that is silently not there (the Loop throws instead).
- *   Wiring the same `wireGate(gate).policy` keeps audit rows byte-shape-identical, with zero gate changes.
- * @property {Function} [onTurn] - (native mode) Called with `{model, provider, usage, costUsd, pricing,
- *   durationMs, ctx, kind}` for EACH completed CLI turn as it arrives (`kind:'turn'`, four cache tiers,
- *   `costUsd:null` — the CLI prices the session, not the turn), then once at session end
- *   (`kind:'session'`) carrying the authoritative total cost with zero usage. Streaming, never
- *   sum-at-end: a session that dies mid-run must already have surfaced every completed turn's spend or
- *   the gate loses all of it. The event shape mirrors `Loop({onLlmResult})`, so `wireGate(gate).onLlmResult`
- *   drops straight in — and when it is wired the Loop skips its own forward, so nothing is billed twice.
- * @property {number} [maxTurns] - (native mode) Maps to the CLI's `--max-turns`. The bound stop is NAMED
- *   (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
- * @property {number} [maxConsecutiveDenials=3] - (native mode) BA-11 at the bridge: a single deny stays
- *   advisory so the model can pivot to an allowed tool; N in a row with no allowed call between ends the
- *   session with `denied:<tool>`. `0`/`Infinity` disables.
- * @property {number} [maxIdenticalToolErrors=3] - (native mode) BA-12 at the bridge: only a BYTE-IDENTICAL
- *   repeat (name + JSON args) counts, so a model varying its args while recovering is never punished. N in
- *   a row ends the session with `stuck:<tool>`. `0`/`Infinity` disables.
- * @property {number} [sessionTimeout=600000] - (native mode) Wall-clock ceiling for one whole session. The
- *   30s `timeout` default is for one-shot text and would kill an agentic session mid-run.
- * @property {number} [bridgeTimeoutMs] - (native mode) Ceiling for ONE tool-handler round-trip across the
- *   bridge. A hung handler becomes an error tool result rather than a hung session (default 120s).
- *
- *   Either mode: a non-empty `tools` array on `generate()` routes to tool mode; an empty one stays
- *   plain text. With NO `toolProtocol`, `tools` are IGNORED (plain-text, the long-standing behavior —
- *   a non-tool-calling CLI legitimately sits in a Loop with tools mounted) plus a one-time `console.warn`.
- *   Emulation additionally requires a capable model (weak ones answer in prose; see `probeCapability`);
- *   native mode needs no such probe, because the CLI's own tool channel does not depend on the model
- *   agreeing to fill in a JSON questionnaire. The claude-specific parts of each live in
- *   `provider-clipipe-tools.js` / `provider-clipipe-mcp.js`, so a second CLI slots in behind the same seams.
- * @property {boolean} [probeCapability=true] - (EMULATION tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
- */
 export class CLIPipeProvider {
     /**
      * Provider that pipes prompts to a CLI command via stdin and reads stdout.

package/src/provider-clipipe.js

@@ -43,8 +43,16 @@ const { createBridge, resolveSessionError, runSession } = require('./provider-cl
  *   sum-at-end: a session that dies mid-run must already have surfaced every completed turn's spend or
  *   the gate loses all of it. The event shape mirrors `Loop({onLlmResult})`, so `wireGate(gate).onLlmResult`
  *   drops straight in — and when it is wired the Loop skips its own forward, so nothing is billed twice.
- * @property {number} [maxTurns] - (native mode) Maps to the CLI's `--max-turns`. The bound stop is NAMED
- *   (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
+ * @property {number} [maxTurns] - (native mode) Bound on ASSISTANT/LLM TURNS — the same unit as the
+ *   Loop path's turn bound, so a caller's `maxTurns` means one thing on both surfaces (BA-17). NOT a
+ *   tool-call count: a single turn may issue a dozen parallel tool calls and still be one turn
+ *   (measured: 12 calls across 2 turns, well inside `--max-turns 3`). Enforced twice on purpose —
+ *   the CLI's own `--max-turns` stops the session cleanly at N and emits its result event (the only
+ *   report of the session's real cost), and a parent-side counter kills it if a turn beyond N is
+ *   ever observed, since that flag is undocumented in `claude --help` and a rename would otherwise
+ *   silently unbound the session. Either way the stop is NAMED (`session.error:'max_turns'`,
+ *   `stopReason:'max_turns'`) and carries the last turn's text forward, never a silent clean success
+ *   and never an empty result.
  * @property {number} [maxConsecutiveDenials=3] - (native mode) BA-11 at the bridge: a single deny stays
  *   advisory so the model can pivot to an allowed tool; N in a row with no allowed call between ends the
  *   session with `denied:<tool>`. `0`/`Infinity` disables.
@@ -66,6 +74,31 @@ const { createBridge, resolveSessionError, runSession } = require('./provider-cl
  * @property {boolean} [probeCapability=true] - (EMULATION tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
  */
 
+/**
+ * Session total minus what the per-turn events already reported, per tier, floored at 0.
+ *
+ * Floored because a negative would be a CREDIT to a gate's running total — an under-count that
+ * silently widens a budget cap. If the streamed turns ever overshoot the session total, the honest
+ * report is "nothing further", never "give some back".
+ *
+ * @param {import('../types').Usage} total
+ * @param {import('../types').Usage[]} streamed
+ * @returns {import('../types').Usage}
+ */
+function subtractUsage(total, streamed) {
+  const sum = (/** @type {keyof import('../types').Usage} */ k) =>
+    streamed.reduce((a, t) => a + (Number(t[k]) || 0), 0);
+  const at = (/** @type {keyof import('../types').Usage} */ k) =>
+    Math.max(0, (Number(total[k]) || 0) - sum(k));
+  /** @type {import('../types').Usage} */
+  const out = { inputTokens: at('inputTokens'), outputTokens: at('outputTokens') };
+  // Only report a cache tier the session actually had — an absent tier stays absent, never a
+  // synthetic 0 (the Usage contract).
+  if (total.cacheReadTokens !== undefined) out.cacheReadTokens = at('cacheReadTokens');
+  if (total.cacheCreationTokens !== undefined) out.cacheCreationTokens = at('cacheCreationTokens');
+  return out;
+}
+
 class CLIPipeProvider {
   /**
    * Provider that pipes prompts to a CLI command via stdin and reads stdout.
@@ -289,17 +322,25 @@ class CLIPipeProvider {
       throw new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${r.spawnError.message}`, /** @type {any} */ ({ status: 0 }));
     }
 
-    /** @type {import('../types').Usage} */
-    const usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
-    for (const t of r.turns) {
-      usage.inputTokens += t.inputTokens || 0;
-      usage.outputTokens += t.outputTokens || 0;
-      usage.cacheReadTokens += t.cacheReadTokens || 0;
-      usage.cacheCreationTokens += t.cacheCreationTokens || 0;
-    }
+    // The result event carries the session's authoritative totals. It has no `model` key — the model
+    // id lives under `modelUsage` — which is exactly what `mapClaudeMeta` already unpacks for the
+    // emulation path, so the native path reuses it rather than re-deriving three fields by hand.
+    const meta = r.final ? mapClaudeMeta(r.final) : null;
+
+    // `result.usage` is the authoritative session total and is preferred when present: it also
+    // captures a turn the CLI billed but never emitted as an event (measured — a bounded session's
+    // cut-off turn). Summing the per-turn records is the fallback for a session we killed before its
+    // result event. Either way the arithmetic is per-TURN, never per block-event (BA-17).
+    const usage = (meta && r.final.usage) ? meta.usage : r.turns.reduce((/** @type {any} */ a, t) => ({
+      inputTokens: a.inputTokens + (t.inputTokens || 0),
+      outputTokens: a.outputTokens + (t.outputTokens || 0),
+      cacheReadTokens: a.cacheReadTokens + (t.cacheReadTokens || 0),
+      cacheCreationTokens: a.cacheCreationTokens + (t.cacheCreationTokens || 0),
+    }), { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 });
 
     const { stopReason, error } = resolveSessionError({
-      terminal: st.terminal,
+      // A bridge/guard terminal is more specific than the turn backstop, so it wins the tag.
+      terminal: st.terminal || r.terminal,
       bridgeDown: st.bridgeDown,
       attempted: r.attempted,
       served: st.toolCalls,
@@ -307,17 +348,25 @@ class CLIPipeProvider {
       subtype: r.final && r.final.subtype,
     });
 
-    const costUsd = (r.final && Number.isFinite(r.final.total_cost_usd)) ? r.final.total_cost_usd : null;
-
-    // The authoritative price arrives only at session end (the CLI prices the SESSION, not the turn),
-    // so when per-turn streaming is wired it gets one closing event carrying the cost with zero
-    // usage — the tokens were already streamed, and double-counting either axis would be a lie.
+    const costUsd = (meta && Number.isFinite(meta.costUsd)) ? /** @type {number} */ (meta.costUsd) : null;
+
+    // The authoritative figures arrive only at session end — the CLI prices the SESSION, not the
+    // turn — so when per-turn streaming is wired, one closing event RECONCILES both axes.
+    //
+    // Money: the whole cost, which no turn reported.
+    // Tokens: the RESIDUAL, not zero and not the total. A turn's `message.usage` is a snapshot taken
+    // when its first block was emitted and never revised (measured: a turn that emitted ~816 output
+    // tokens reported 2, identically on all 13 of its block-events), so the streamed per-turn sum is
+    // real but SHORT of the session total. Sending the difference makes a gate's token axis add up
+    // to exactly what the CLI itself reports — where sending the total would double-count everything
+    // already streamed, and sending zero would leave the axis quietly under-fed.
+    const residual = subtractUsage(usage, r.turns);
     if (this.onTurn) {
       try {
         await this.onTurn({
-          model: (r.final && r.final.model) || null,
+          model: (meta && meta.model) || null,
           provider: 'clipipe',
-          usage: { inputTokens: 0, outputTokens: 0 },
+          usage: residual,
           costUsd,
           pricing: costUsd === null ? 'unpriced' : 'priced',
           durationMs: r.ms,
@@ -329,15 +378,23 @@ class CLIPipeProvider {
       }
     }
 
+    // BA-5 on the native path: a bound or a tripped guard is normal termination for a bounded
+    // attempt, and the text is the ONLY channel from this attempt to the next. The CLI reports
+    // `result: null` when it stops on its own bound (measured), and a session we killed never emits
+    // a result at all — so fall back to the last assistant turn's own words rather than ''.
+    const finalText = (r.final && typeof r.final.result === 'string' && r.final.result)
+      ? r.final.result
+      : (r.lastText || '');
+
     /** @type {GenerateResult} */
     const result = {
-      text: (r.final && typeof r.final.result === 'string') ? r.final.result : '',
+      text: finalText,
       toolCalls: [],
       usage,
-      model: (r.final && r.final.model) || null,
+      model: (meta && meta.model) || null,
       stopReason,
       session: {
-        turns: r.turns.length,
+        turns: r.turnCount,
         toolCalls: st.toolCalls,
         error,
         // Only true when we ACTUALLY streamed — unwired, the Loop must still forward the total or