bare-agent 0.24.0 → 0.26.0

package/README.md

@@ -119,7 +119,7 @@ console.log(result.count, result.matchedIds);   // a code-derived count + the id
 
 > **⚠️ Cost is open by design — wire a cap.** `recurse()` adds no intrinsic total-work limit. On the model-driven default a node can spawn up to ~100 children per level, each recursing to `maxDepth` (default 3), so **token / $ spend compounds and is bounded only by your gate** — not by recurse. Run it **with bareguard** (`ctx.policy`, which enforces depth/budget/call caps) **or with some token/USD cap** for any non-trivial or untrusted task; ungoverned, a weak model that over-decomposes *will* burn tokens. For a hard local brake without a gate, set `maxDepth: 1` (flat, no nesting). The forced modes (`mode:'fanout'` / `'partition'`) are bounded by a deterministic count + concurrency cap; the open path is the model-driven default.
 
-**Govern — one gate over both axes.** `wireGate(gate)` routes every LLM + tool call through one bareguard policy + audit + budget. Denied tools never reach the model; halts (turn / budget / content caps) exit cleanly. `require('bare-agent/bareguard')`
+**Govern — one gate over both axes.** `wireGate(gate)` routes every LLM + tool call through one bareguard policy + audit + budget. Denied tools never reach the model; halts (turn / budget / content caps) exit cleanly. A plain deny stays advisory (the model can pivot to an allowed tool), but the Loop short-circuits a *spin* — `maxConsecutiveDenials` consecutive denials of the same action (default 3) stop the run with `error:'denied:<tool>'` instead of burning the budget to the cap; under `recurse` that surfaces as `{ incomplete, blocker:'governance-deny' }`. `require('bare-agent/bareguard')`
 
 **Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Gemini (native), Ollama, CLIPipe, Fallback — or bring your own (one `generate` method). All return the same shape; swap freely. Usage including prompt-cache tiers is normalized, so `result.metrics` reports honest cumulative tokens + cost — and `null`, never a silent `0`, for a model it couldn't price. A model that rejects a non-default `temperature` (e.g. `claude-sonnet-5`, OpenAI o1/gpt-5-class return a `400`) is handled gracefully — the provider drops the param and retries once rather than failing the call, surfacing `temperatureDropped` so a caller can report the effective value.
 

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.24.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
+> v0.26.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.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)
 
@@ -59,6 +59,7 @@ Eight entry points:
 | Catch typed errors programmatically | ProviderError, ToolError, TimeoutError, CircuitOpenError |
 | Cache identical planner calls | Planner({ cacheTTL: 60000 }) |
 | Stream CLIPipe output in real-time | CLIPipeProvider({ onChunk: fn }) |
+| Get real usage + cost from a CLI provider | CLIPipeProvider({ parse: 'claude-json' }) |
 | Browse the web (inline snapshots) | createBrowsingTools + Loop |
 | Browse the web (token-efficient, disk-based) | `barebrowse` CLI session — snapshots to `.barebrowse/*.yml` |
 | Assess website privacy risk | createBrowsingTools + Loop (requires `npm install wearehere`) |
@@ -379,6 +380,8 @@ if (result.error?.startsWith('halt:')) {
 
 Halt-severity decisions exit the loop cleanly via a typed `HaltError` — full mechanics (sealed `msgs`, `halt:<rule>` error token, `loop:done{halted:true}` event, `throwOnError:true` interaction, `halt:unknown` coalesce) are in the **Halt decisions throw `HaltError`** paragraph below. Short version: check `result.error?.startsWith('halt:')` after the run.
 
+**Deny-spin short-circuit (`maxConsecutiveDenials`, default 3, v0.25+).** A *non-halt* deny (a `policy` verdict that isn't `true` — e.g. a `humanChannel: deny`, an allowlist miss, a `content`/`fs.writeScope` block) is **advisory**: it's fed back to the model as a tool result so the model can pivot to a different allowed tool. But a model that keeps retrying the *same* denied action would otherwise spin every round until your `budget.maxCostUsd` finally halts it — burning the whole cap with no progress (this bit a coding agent whose write kept tripping `content.askPatterns`). The Loop now counts **consecutive** denials (any allowed call resets the streak, preserving the pivot) and short-circuits at `maxConsecutiveDenials` with `result.error === 'denied:<tool>'` (a clean return, transcript sealed — never a throw). Check `result.error?.startsWith('denied:')` to distinguish a governance block from a completed run; set `maxConsecutiveDenials: 0` (or `Infinity`) on `new Loop({...})` to restore the pure-advisory behavior. Under `recurse`, a short-circuited worker returns a **labeled** `{ incomplete: true, blocker: 'governance-deny' }` (and `receipts.blocker`) so you can widen scope / re-gate / escalate rather than read it as a model failure.
+
 Legacy `wrapTool` / `wrapTools` are retained as deprecation shims (one-shot console warning, removal in 1.0). Migration: replace `wrapTools(tools)` at `loop.run()` with `filterTools(tools)` once upfront + `onLlmResult` / `onToolResult` on `new Loop({...})` to pick up LLM-cost recording and `_ctx` threading.
 
 **`actionTranslator` for bash/fs primitive activation (v0.10.1+).** Bareguard's `bashCheck` / `fsCheck` / `netCheck` only fire when `action.type === 'bash'` / `'read'` / `'write'` / `'fetch'`. The default action shape is `{type: toolName, args, _ctx}` which matches `tools.denylist` / `tools.allowlist` but does NOT activate those primitives. Adopters who want both pass `wireGate(gate, { actionTranslator })`. Since bareguard 0.4.1+, the primitives read fields from either flat (`action.cmd`) or nested (`action.args.cmd` / `.command`) shapes, so you can pass args through verbatim:
@@ -737,9 +740,11 @@ new Ollama({ model: 'llama3.2', url: 'http://localhost:11434' })
 // CLIPipe — pipe prompts to any CLI tool via stdin/stdout
 new CLIPipe({ command: 'claude', args: ['--print'], systemPromptFlag: '--system-prompt', timeout: 30000 })
 new CLIPipe({ command: 'ollama', args: ['run', 'llama3.2'] })
+// CLIPipe structured output (v0.26.0+) — map a CLI's JSON envelope to real usage + cost
+new CLIPipe({ command: 'claude', args: ['-p', '--output-format', 'json'], parse: 'claude-json' })
 ```
 
-All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model? }`. The optional `model` (v0.16.1+) is the id the response was produced by — Loop prefers it over `provider.model` for cost accounting. CLIPipe always returns `toolCalls: []` and zero usage (CLI tools don't report tokens), and omits `model`.
+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).
 
 **Temperature graceful degradation (BA-10).** Newer models reject ANY non-default `temperature` with a `400` (`claude-sonnet-5`: `` `temperature` is deprecated for this model. ``; OpenAI o1/gpt-5-class: `Unsupported value: 'temperature' … Only the default (1) …`). All four providers detect that specific 400 (message names `temperature` as unsupported/deprecated AND a temperature was sent), **drop the param, warn once per instance, and retry once** — so a call that would otherwise throw succeeds at the model's default temperature. Keyed off the API error text, not a model list. A genuine out-of-range 400 is NOT degraded (it re-throws — dropping it would mask a caller bug). When a drop happens the result carries `temperatureDropped: true` (an optional `GenerateResult`/`Loop.run` field) so a caller can report the effective temperature — `recurse`'s `refineLeaf` uses it for an honest receipt. Dormant on models that accept temperature (byte-identical to before).
 

package/package.json

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

package/src/loop.d.ts

@@ -52,6 +52,16 @@ export type LoopOptions = {
      */
     onLlmResult?: Function | undefined;
     onToolResult?: Function | undefined;
+    /**
+     * - BA-11 safety net (default 3). Short-circuit the run when
+     * `policy` denies this many tool calls IN A ROW with no allowed call in between — a governance deny is
+     * not a recoverable tool error, so a model that keeps retrying variants of a denied action would
+     * otherwise burn the budget to the cap without progress (probe-16: 16 calls, sensor never reached). Any
+     * tool call that PASSES policy resets the streak, preserving allowlist-safe pivoting (deny X → allow Y).
+     * The run returns cleanly with `error: 'denied:<tool>'` (mirrors the halt return; never throws even under
+     * throwOnError). Set `0` or `Infinity` to disable (restores pre-BA-11 advisory-deny behavior).
+     */
+    maxConsecutiveDenials?: number | undefined;
     /**
      * - Removed in v0.8; presence throws a migration error.
      */
@@ -79,6 +89,7 @@ export class Loop {
     throwOnError: boolean;
     store: import("../types").Store | null;
     policy: Function | null;
+    maxConsecutiveDenials: number;
     assemble: Function | null;
     trim: Function | null;
     onLlmResult: Function | null;
@@ -228,6 +239,13 @@ export function estimateCost(model: string | null, usage: Usage | null): number
  *   gate.record (via wireGate). `event.kind` discriminates the source: `'turn'` for a main-loop round,
  *   `'summarize'` for an out-of-band `ctx.summarize` call (R-C6). Both count against the budget.
  * @property {Function} [onToolResult]
+ * @property {number} [maxConsecutiveDenials] - BA-11 safety net (default 3). Short-circuit the run when
+ *   `policy` denies this many tool calls IN A ROW with no allowed call in between — a governance deny is
+ *   not a recoverable tool error, so a model that keeps retrying variants of a denied action would
+ *   otherwise burn the budget to the cap without progress (probe-16: 16 calls, sensor never reached). Any
+ *   tool call that PASSES policy resets the streak, preserving allowlist-safe pivoting (deny X → allow Y).
+ *   The run returns cleanly with `error: 'denied:<tool>'` (mirrors the halt return; never throws even under
+ *   throwOnError). Set `0` or `Infinity` to disable (restores pre-BA-11 advisory-deny behavior).
  * @property {number} [maxRounds] - Removed in v0.8; presence throws a migration error.
  */
 /** @type {Record<string, {in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}>} */

package/src/loop.js

@@ -49,6 +49,13 @@ const { ToolError, HaltError } = require('./errors');
  *   gate.record (via wireGate). `event.kind` discriminates the source: `'turn'` for a main-loop round,
  *   `'summarize'` for an out-of-band `ctx.summarize` call (R-C6). Both count against the budget.
  * @property {Function} [onToolResult]
+ * @property {number} [maxConsecutiveDenials] - BA-11 safety net (default 3). Short-circuit the run when
+ *   `policy` denies this many tool calls IN A ROW with no allowed call in between — a governance deny is
+ *   not a recoverable tool error, so a model that keeps retrying variants of a denied action would
+ *   otherwise burn the budget to the cap without progress (probe-16: 16 calls, sensor never reached). Any
+ *   tool call that PASSES policy resets the streak, preserving allowlist-safe pivoting (deny X → allow Y).
+ *   The run returns cleanly with `error: 'denied:<tool>'` (mirrors the halt return; never throws even under
+ *   throwOnError). Set `0` or `Infinity` to disable (restores pre-BA-11 advisory-deny behavior).
  * @property {number} [maxRounds] - Removed in v0.8; presence throws a migration error.
  */
 
@@ -146,6 +153,23 @@ function estimateCost(model, usage) {
   return Number.isFinite(cost) ? cost : null;
 }
 
+/**
+ * Resolve the priced USD for a round. A provider MAY report its own authoritative `costUsd` on the
+ * GenerateResult (e.g. CLIPipeProvider `parse:'claude-json'` surfacing the claude CLI's own
+ * `total_cost_usd` — a real price with NO local rate table). When present as a FINITE number it wins
+ * over the rate-table estimate — including `0`, a valid priced value (a subscription/marginal-$0 run),
+ * which stays 'priced', never demoted to the null/unpriced sentinel. A non-finite provider cost
+ * (±Inf/NaN) is NOT a price → fall through to estimateCost (same couldn't-price guard as above).
+ * @param {any} result - the GenerateResult from provider.generate()
+ * @param {string|null} model
+ * @param {Usage|null} usage
+ * @returns {number|null}
+ */
+function resolveRoundCost(result, model, usage) {
+  if (result && Number.isFinite(result.costUsd)) return result.costUsd;
+  return estimateCost(model, usage);
+}
+
 // R-C6: default instruction for the provider-bound `ctx.summarize` lent to the assemble seam.
 const DEFAULT_SUMMARY_INSTRUCTION =
   'You are a precise conversation summarizer. Produce a concise, factual summary of the following ' +
@@ -212,6 +236,13 @@ class Loop {
       throw new Error('[Loop] options.policy must be a function (toolName, args, ctx) => true | string');
     }
     this.policy = options.policy || null;
+    // BA-11 deny-spin guard. Default 3; 0/Infinity/non-finite disables (restores advisory-deny behavior).
+    // Validated only if provided so an explicit 0 is honored as "off" (Infinity also disables).
+    if (options.maxConsecutiveDenials != null
+        && (typeof options.maxConsecutiveDenials !== 'number' || options.maxConsecutiveDenials < 0 || Number.isNaN(options.maxConsecutiveDenials))) {
+      throw new Error('[Loop] options.maxConsecutiveDenials must be a non-negative number (0 or Infinity disables)');
+    }
+    this.maxConsecutiveDenials = options.maxConsecutiveDenials != null ? options.maxConsecutiveDenials : 3;
     if (options.assemble != null && typeof options.assemble !== 'function') {
       throw new Error('[Loop] options.assemble must be a function (msgs, info) => msgs');
     }
@@ -360,6 +391,9 @@ class Loop {
     // unsupported/deprecated) and retried without it. Surfaced on the result so an upstream receipt
     // (recurse's refineLeaf) can report the EFFECTIVE temperature rather than the ignored request.
     let temperatureDropped = false;
+    // BA-11: consecutive policy-deny counter (reset by any tool call that PASSES policy). When it reaches
+    // this.maxConsecutiveDenials the run short-circuits cleanly — see the deny block below.
+    let consecutiveDenials = 0;
 
     // The meter (Feature 3): bareagent is the canonical run counter. Accumulates across rounds and is
     // returned as `result.metrics`. `tokens` is CUMULATIVE over all four tiers (fixes the last-round-only
@@ -455,7 +489,7 @@ class Loop {
         const result = await loop.provider.generate(prompt, [], { temperature: 0, ...genOpts });
         const usage = (result && result.usage) || null;
         const model = (result && result.model) || loop.provider.model || null;
-        const cost = estimateCost(model, usage);
+        const cost = resolveRoundCost(result, model, usage);
         if (cost !== null) { totalCost += cost; pricedAny = true; }
         addUsage(usage); // summarize tokens are real spend → count them in the cumulative meter
         metrics.context.summaries++; // §3.6 CE-activity rollup
@@ -599,7 +633,7 @@ class Loop {
       // Prefer the model the response reports (robust when provider.model is absent or varies per
       // response — e.g. FallbackProvider, or a CircuitBreaker-wrapped provider that drops .model).
       const model = result.model || this.provider.model || null;
-      const roundCost = estimateCost(model, lastUsage);
+      const roundCost = resolveRoundCost(result, model, lastUsage);
       if (roundCost !== null) totalCost += roundCost;
 
       // Meter this round: count the turn, accumulate the four token tiers, and classify pricing —
@@ -731,10 +765,30 @@ class Loop {
               : `[Loop] Tool "${tc.name}" denied by policy`;
             msgs.push({ role: 'tool', tool_call_id: tc.id, content: reason });
             this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, denied: true, reason } });
+            // BA-11: a governance deny is not a recoverable tool error. Count consecutive denials; when the
+            // model keeps retrying denied actions (proven live: 8 in a row before giving up) short-circuit the
+            // run rather than let it burn the budget to the cap. The streak resets on any ALLOWED tool call
+            // (below), so a legit deny-then-pivot (deny X → allow Y) never trips this. 0/Infinity disables.
+            consecutiveDenials += 1;
+            if (this.maxConsecutiveDenials > 0 && Number.isFinite(this.maxConsecutiveDenials)
+                && consecutiveDenials >= this.maxConsecutiveDenials) {
+              const denyTag = `denied:${tc.name}`;
+              // Pair any still-dangling tool_calls from this round so the returned transcript stays
+              // provider-valid (same seal the halt path uses), then exit cleanly — no throw even under
+              // throwOnError, mirroring the governance-halt contract.
+              sealDanglingToolCalls(msgs, denyTag);
+              this._reportError('denied', new Error(`policy denied ${consecutiveDenials} consecutive tool calls (${tc.name})`), { rule: denyTag, denials: consecutiveDenials });
+              this._safeEmit({ type: 'loop:done', data: { text: '', denied: true, rule: denyTag, cost: totalCost } });
+              return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, msgs, metrics: finalizeMetrics() };
+            }
             continue;
           }
         }
 
+        // BA-11: reaching here means this tool call PASSED policy (or there is no policy) — progress, so the
+        // consecutive-deny streak resets. A single deny followed by an allowed call never trips the guard.
+        consecutiveDenials = 0;
+
         const toolStartedAt = Date.now();
         let toolResult;
         let toolError;

package/src/provider-clipipe.d.ts

@@ -30,6 +30,10 @@ export type CLIPipeOptions = {
      * - Called with each stdout chunk as it streams.
      */
     onChunk?: ((chunk: string) => void) | undefined;
+    /**
+     * - 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.
+     */
+    parse?: "claude-json" | ((stdout: string) => Partial<GenerateResult>) | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -43,6 +47,7 @@ export type CLIPipeOptions = {
  * @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.
  */
 export class CLIPipeProvider {
     /**
@@ -58,6 +63,7 @@ export class CLIPipeProvider {
     timeout: number;
     systemPromptFlag: string | null;
     onChunk: ((chunk: string) => void) | null;
+    parse: "claude-json" | ((stdout: string) => Partial<GenerateResult>) | null;
     /**
      * Generate a response by piping messages to the CLI command.
      * @param {Message[]} messages - Conversation messages in OpenAI format.
@@ -70,6 +76,15 @@ export class CLIPipeProvider {
      * @throws {Error} `[CLIPipeProvider] process produced no output` — when stdout is empty.
      */
     generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * Map the `claude -p --output-format json` result envelope onto a normalized GenerateResult.
+     * The caller explicitly opted into structured output, so a malformed or error envelope is a LOUD
+     * ProviderError — never a silent fall-back to raw text.
+     * @param {string} stdout - Trimmed stdout from the CLI.
+     * @returns {GenerateResult}
+     * @throws {ProviderError} On non-JSON stdout, or an error envelope (`is_error` / non-success subtype).
+     */
+    _parseClaudeJson(stdout: string): GenerateResult;
     /**
      * Convert OpenAI-format messages to a plain text prompt.
      * @param {Message[]} messages

package/src/provider-clipipe.js

@@ -16,6 +16,7 @@ const { ProviderError } = require('./errors');
  * @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.
  */
 
 class CLIPipeProvider {
@@ -33,6 +34,10 @@ class CLIPipeProvider {
     this.timeout = options.timeout ?? 30000;
     this.systemPromptFlag = options.systemPromptFlag || null;
     this.onChunk = options.onChunk || null;
+    if (options.parse != null && options.parse !== 'claude-json' && typeof options.parse !== 'function') {
+      throw new Error("[CLIPipeProvider] options.parse must be 'claude-json' or a function");
+    }
+    this.parse = options.parse || null;
   }
 
   /**
@@ -61,14 +66,77 @@ class CLIPipeProvider {
     }
 
     const prompt = this._formatPrompt(promptMessages);
-    const text = await this._spawn(prompt, extraArgs);
+    const stdout = await this._spawn(prompt, extraArgs);
+
+    if (this.parse === 'claude-json') return this._parseClaudeJson(stdout);
+    if (typeof this.parse === 'function') {
+      const partial = this.parse(stdout) || {};
+      return {
+        text: '',
+        toolCalls: [],
+        ...partial,
+        usage: { inputTokens: 0, outputTokens: 0, ...(partial.usage || {}) },
+      };
+    }
     return {
-      text,
+      text: stdout,
       toolCalls: [],
       usage: { inputTokens: 0, outputTokens: 0 },
     };
   }
 
+  /**
+   * Map the `claude -p --output-format json` result envelope onto a normalized GenerateResult.
+   * The caller explicitly opted into structured output, so a malformed or error envelope is a LOUD
+   * ProviderError — never a silent fall-back to raw text.
+   * @param {string} stdout - Trimmed stdout from the CLI.
+   * @returns {GenerateResult}
+   * @throws {ProviderError} On non-JSON stdout, or an error envelope (`is_error` / non-success subtype).
+   */
+  _parseClaudeJson(stdout) {
+    let obj;
+    try {
+      obj = JSON.parse(stdout);
+    } catch (_) {
+      const preview = stdout.length > 200 ? `${stdout.slice(0, 200)}…` : stdout;
+      throw new ProviderError(`[CLIPipeProvider] parse:'claude-json' expected JSON on stdout, got: ${preview}`, /** @type {any} */ ({ status: 0 }));
+    }
+    if (!obj || typeof obj !== 'object') {
+      throw new ProviderError(`[CLIPipeProvider] parse:'claude-json' expected a JSON object, got ${obj === null ? 'null' : typeof obj}`, /** @type {any} */ ({ status: 0 }));
+    }
+    if (obj.is_error === true || obj.subtype !== 'success') {
+      const detail = typeof obj.result === 'string' ? obj.result : JSON.stringify(obj.result ?? null);
+      throw new ProviderError(`[CLIPipeProvider] claude CLI reported failure (subtype='${obj.subtype}'): ${detail}`, /** @type {any} */ ({ status: 0 }));
+    }
+
+    const u = (obj.usage && typeof obj.usage === 'object') ? obj.usage : {};
+    /** @type {import('../types').Usage} */
+    const usage = {
+      inputTokens: Number(u.input_tokens) || 0,
+      outputTokens: Number(u.output_tokens) || 0,
+    };
+    // Absent cache tiers mean the model didn't cache — omit rather than emit a synthetic 0 (per Usage docs).
+    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;
+
+    // `modelUsage` is an object keyed by model id (e.g. {"claude-opus-4-8[1m]": {...}}) — take the first key.
+    const model = (obj.modelUsage && typeof obj.modelUsage === 'object')
+      ? (Object.keys(obj.modelUsage)[0] ?? null)
+      : null;
+
+    /** @type {GenerateResult} */
+    const result = {
+      text: typeof obj.result === 'string' ? obj.result : '',
+      toolCalls: [],
+      usage,
+      model,
+    };
+    // The CLI's own price is authoritative (subscription runs report an equivalent cost even at $0
+    // marginal) — feeds bareguard's USD axis with no local rate table. Only a finite number counts.
+    if (Number.isFinite(obj.total_cost_usd)) result.costUsd = obj.total_cost_usd;
+    return result;
+  }
+
   /**
    * Convert OpenAI-format messages to a plain text prompt.
    * @param {Message[]} messages

package/src/recurse.d.ts

@@ -215,6 +215,11 @@ export type RecurseNode = {
     verdict: Verdict | null;
     incomplete: boolean;
     halted: boolean;
+    /**
+     * - (BA-11) set to `'governance-deny'` when this node stopped because its Loop
+     * short-circuited a consecutive-policy-deny spin (not a model failure). Mirrors `RecurseResult.blocker`.
+     */
+    blocker?: string | undefined;
     /**
      * - The worker Loop's `metrics.tokens`.
      */
@@ -287,6 +292,12 @@ export type RecurseResult = {
      * back incomplete (§9 scenario 1) — the anti-survivor-sum signal, not a quiet undercount.
      */
     missingSlices?: string[] | undefined;
+    /**
+     * - Present when `incomplete` for a specific, actionable reason. `'governance-deny'`
+     * (BA-11): the worker's Loop short-circuited after N consecutive policy denials rather than burn to the
+     * budget cap — the caller can widen scope / re-gate / escalate instead of reading it as a model failure.
+     */
+    blocker?: string | undefined;
     /**
      * - The audit node for this call (RC-10).
      */
@@ -424,6 +435,8 @@ export type Slice = {
  * @property {Verdict|null} verdict
  * @property {boolean} incomplete
  * @property {boolean} halted
+ * @property {string} [blocker] - (BA-11) set to `'governance-deny'` when this node stopped because its Loop
+ *   short-circuited a consecutive-policy-deny spin (not a model failure). Mirrors `RecurseResult.blocker`.
  * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
  * @property {{iterations: number, passed: boolean, temperatures: (number|null)[]}} [refineLeaf] - (BA-8) when this
  *   leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
@@ -449,6 +462,9 @@ export type Slice = {
  * @property {any} [best] - The best partial answer when `incomplete` (RC-9).
  * @property {string[]} [missingSlices] - When `incomplete` because a child failed: the sub-task(s) that came
  *   back incomplete (§9 scenario 1) — the anti-survivor-sum signal, not a quiet undercount.
+ * @property {string} [blocker] - Present when `incomplete` for a specific, actionable reason. `'governance-deny'`
+ *   (BA-11): the worker's Loop short-circuited after N consecutive policy denials rather than burn to the
+ *   budget cap — the caller can widen scope / re-gate / escalate instead of reading it as a model failure.
  * @property {RecurseNode} receipts - The audit node for this call (RC-10).
  */
 /**

package/src/recurse.js

@@ -290,6 +290,8 @@ function auditSafeCtx(ctx, overrides = {}) {
  * @property {Verdict|null} verdict
  * @property {boolean} incomplete
  * @property {boolean} halted
+ * @property {string} [blocker] - (BA-11) set to `'governance-deny'` when this node stopped because its Loop
+ *   short-circuited a consecutive-policy-deny spin (not a model failure). Mirrors `RecurseResult.blocker`.
  * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
  * @property {{iterations: number, passed: boolean, temperatures: (number|null)[]}} [refineLeaf] - (BA-8) when this
  *   leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
@@ -316,6 +318,9 @@ function auditSafeCtx(ctx, overrides = {}) {
  * @property {any} [best] - The best partial answer when `incomplete` (RC-9).
  * @property {string[]} [missingSlices] - When `incomplete` because a child failed: the sub-task(s) that came
  *   back incomplete (§9 scenario 1) — the anti-survivor-sum signal, not a quiet undercount.
+ * @property {string} [blocker] - Present when `incomplete` for a specific, actionable reason. `'governance-deny'`
+ *   (BA-11): the worker's Loop short-circuited after N consecutive policy denials rather than burn to the
+ *   budget cap — the caller can widen scope / re-gate / escalate instead of reading it as a model failure.
  * @property {RecurseNode} receipts - The audit node for this call (RC-10).
  */
 
@@ -510,6 +515,15 @@ async function recurse(task, ctx = {}, opts = {}) {
     node.incomplete = true;
     return { incomplete: true, best: out.text || null, receipts: node };
   }
+  // BA-11: a deny-spin short-circuit. The Loop stopped the worker after N consecutive governance denials
+  // (a governance deny is not a recoverable tool error — retrying variants would burn to the budget cap;
+  // probe-16: 16 calls, sensor never reached → incomplete). Surface it as a clean, LABELED incomplete so a
+  // caller can tell a governance block apart from a model failure and act (widen scope, re-gate, escalate).
+  if (typeof out.error === 'string' && out.error.startsWith('denied:')) {
+    node.incomplete = true;
+    node.blocker = 'governance-deny';
+    return { incomplete: true, best: out.text || null, blocker: 'governance-deny', receipts: node };
+  }
   if (out.error) {
     node.incomplete = true;
     return { incomplete: true, best: out.text || null, receipts: node };
@@ -673,6 +687,13 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
       node.incomplete = true;
       return { incomplete: true, best: null, receipts: node };
     }
+    // BA-11: a deny-spin inside a refine attempt (the Loop short-circuited after N consecutive governance
+    // denials, rethrown at recurse.js as `denied:<tool>`) is a LABELED governance block, not a model fault.
+    if (typeof err?.message === 'string' && err.message.startsWith('denied:')) {
+      node.incomplete = true;
+      node.blocker = 'governance-deny';
+      return { incomplete: true, best: null, blocker: 'governance-deny', receipts: node };
+    }
     node.incomplete = true;
     return { incomplete: true, best: null, receipts: node };
   }

package/types/index.d.ts

@@ -86,6 +86,14 @@ export interface GenerateResult {
    * temperature, not the one requested — callers reporting an effective temperature must honor this.
    */
   temperatureDropped?: boolean;
+  /**
+   * Authoritative per-call cost in USD, reported by the provider itself — e.g. CLIPipeProvider
+   * `parse:'claude-json'` surfacing the claude CLI's own `total_cost_usd`, a real price with no local
+   * rate table. When a FINITE number the Loop prefers it over `estimateCost` and treats the round as
+   * priced (feeding bareguard's USD budget axis). `0` is a valid priced value (a subscription/marginal-$0
+   * run) — distinct from omitted/null, which means "couldn't price" and falls back to the rate table.
+   */
+  costUsd?: number;
 }
 
 /** A conversation message in OpenAI chat format. */