bare-agent 0.36.1 → 0.38.1

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.36.1 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.14.0` optional peer for governance) | Apache 2.0
+> v0.38.1 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.14.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)
 
@@ -874,7 +874,7 @@ new CLIPipe({ command: 'claude', args: ['-p', '--model', 'sonnet'], toolProtocol
 - `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` — 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).
+- `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`/`rateSource: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. The session event stamps `rateSource:'provider'` when its cost is finite (BA-22 — the CLI's own `total_cost_usd`, no local rate table; a killed/unknown session carries `rateSource:null`, never a spurious `'provider'`). Shape mirrors `onLlmResult` (incl. `rateSource`), 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 — 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.
@@ -891,7 +891,7 @@ All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, cos
 
 **Plaintext-key warning (Unreleased):** the OpenAI provider's `baseUrl` accepts `http://` (for local/OpenAI-compatible endpoints), but a `Bearer` key sent over plaintext http to a **non-loopback** host is exposed on the wire. The provider now warns once when that happens. Loopback hosts (`localhost`/`127.0.0.0/8`/`::1` — local proxies, Ollama-style endpoints) stay silent, since that's the legitimate keyless-local case. The header is **not** stripped (some local proxies want a key), so use `https` for any remote endpoint, or drop `apiKey` when the local endpoint needs none.
 
-**Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. Pricing covers OpenAI and Anthropic models; unknown models use a default average. To adjust rates, edit `COST_PER_1K` at the top of `src/loop.js`. The model is resolved as `result.model || provider.model` (v0.16.1+) — providers now echo the model in their `generate()` result, so cost accounting holds even when `provider.model` is absent or varies per response, e.g. behind `FallbackProvider` or `CircuitBreaker.wrapProvider` (the wrapper also preserves `model`/`name` passthrough props). Wire `onLlmResult` (via `wireGate`) and a `budget.maxCostUsd` cap then halts on token-heavy workloads too.
+**Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. **Pricing honesty (BA-21, v0.37.0):** a token-bearing round is ALWAYS priced (guesstimate-and-run — a null/unknown model no longer forces `unpriced`); rates resolve as caller-supplied `new Loop({ rates: { in, out } })` (authoritative) → a recognized Claude tier from the model id (`haiku`/`sonnet`) → the **Sonnet-tier** ceiling default ($0.003/$0.015 per 1K, no per-model table). Every metering payload carries a `rateSource: 'provider' | 'caller' | 'tier' | 'default' | null` field so a consumer can tell an authoritative price from a guess — and (BA-21 follow-up, v0.38.0) a recognized-tier guess (`'tier'`) from a blind ceiling fallback (`'default'`); a round priced off either guesstimate emits ONE loud `console.warn` per Loop instance naming the actual source (silenced by passing `rates`). To set your own rates, construct `new Loop({ rates })` — there is no longer a `COST_PER_1K` table to edit. The model is resolved as `result.model || provider.model` (v0.16.1+) — providers now echo the model in their `generate()` result, so cost accounting holds even when `provider.model` is absent or varies per response, e.g. behind `FallbackProvider` or `CircuitBreaker.wrapProvider` (the wrapper also preserves `model`/`name` passthrough props). Wire `onLlmResult` (via `wireGate`) and a `budget.maxCostUsd` cap then halts on token-heavy workloads too.
 
 ## Store options
 
@@ -1047,7 +1047,7 @@ Stale example removed in 0.10.4: `examples/mcp-bridge-gov.js` (used a hard-coded
 16. **`bin/cli.js` uses BA1 callbacks since v0.10.3** — children record LLM cost into bareguard's audit, thread `_ctx`, and pre-filter tools via `gate.allows`. Pre-0.10.3 children used the deprecated `wrapTools` path which silently dropped LLM cost from `budget.maxCostUsd` and printed a deprecation warning per first tool call. No config change needed; the upgrade is transparent.
 17. **Halt-path `msgs` is sealed (v0.10.3+)** — when Loop catches `HaltError` mid-round, every dangling assistant `tool_calls.id` from the halted round gets a synthetic `{ role:'tool', tool_call_id, content: '[halted:<rule>]' }` appended so the returned `result.msgs` is valid OpenAI shape. Safe to feed back into another provider call without protocol errors. The `[halted:<rule>]` tag is lowercase — distinct from the legacy `[HALT:]` deny strings (removed in 0.10.0, do not match on the old form).
 18. **`HaltError` with no `rule` resolves to `halt:unknown` (v0.10.3+)** — `new HaltError('msg')` without a `{ rule }` option still produces a stable `result.error = 'halt:unknown'` and `loop:done{halted:true, rule:'unknown'}`. Pre-0.10.3 produced the literal `'halt:null'` which broke string-matching consumers. The `_reportError('halt', ...)` extra carries the same `rule:'unknown'` token.
-19. **Cost table is hand-curated** (`src/loop.js:COST_PER_1K`) — refreshed 2026-05-18 for Claude 4.x (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`) and the GPT-4.1 / o3-mini line. Unknown models fall through to `_default` ($0.002 in / $0.008 out per 1K). If you use a model not in the table and care about `result.cost` accuracy or `budget.maxCostUsd` enforcement via `onLlmResult`, add it.
+19. **Pricing is a two-tier guesstimate, not a per-model table (BA-21, v0.37.0)** — a recognized Claude tier in the model id prices at `haiku` ($0.001/$0.005) or `sonnet` ($0.003/$0.015) per 1K; anything else (incl. a null/unknown model) falls through to the **Sonnet-tier ceiling default** ($0.003/$0.015) and still gets priced (`rateSource: 'default'`), never silently `unpriced`. Both guesstimate cases emit one `console.warn` per Loop instance. The `rateSource` on every metering payload distinguishes them: `'tier'` (a recognized haiku/sonnet match — a confident guess) vs `'default'` (the blind ceiling for an unrecognized/absent model), alongside `'provider'`/`'caller'` (authoritative) and `null` (unpriced). If you use a model whose real rates differ and care about `result.cost` accuracy or `budget.maxCostUsd` enforcement via `onLlmResult`, pass `new Loop({ rates: { in, out, cacheReadMult?, cacheWriteMult? } })` — that's authoritative (`rateSource: 'caller'`) and silences the warning. There is no `COST_PER_1K` table to edit.
 
 ## Cross-language SDKs
 

package/package.json

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

package/src/judge.d.ts

@@ -14,6 +14,18 @@ export type JudgeOptions = {
      * option, because the http providers build the request from `this.model` and would silently ignore them.
      */
     provider: import("../types").Provider;
+    /**
+     * - BA-21: per-1K USD
+     * rates for the judge's own model, to price its call authoritatively (rateSource:'caller'). Omit → a flagged
+     * guesstimate (rateSource:'tier' for a recognized Claude tier, else 'default'). Bring your own rate, or take a
+     * guesstimate — never a silent guess.
+     */
+    rates?: {
+        in: number;
+        out: number;
+        cacheReadMult?: number;
+        cacheWriteMult?: number;
+    } | undefined;
     /**
      * - Cap on the judge's own output. A verdict truncated at the cap floors to
      * `broke`; 512 clears the mechanical `where` with headroom (measured), lower it only if you know the artifacts are small.
@@ -27,6 +39,7 @@ export type JudgeOptions = {
         model: string | null;
         kind: "judge";
         costUsd: number | null;
+        rateSource: "provider" | "caller" | "tier" | "default" | null;
     }) => any) | undefined;
 };
 /**
@@ -97,9 +110,15 @@ export type JudgeVerdict = {
      */
     parseError: boolean;
     /**
-     * - Real per-call cost. An HONEST null when the tier is unpriced (never coerced to 0).
+     * - Per-call cost. An HONEST null only when genuinely unpriced (never coerced to 0).
      */
     costUsd: number | null;
+    /**
+     * - WHERE costUsd came from (BA-21): 'provider'
+     * (real), 'caller' (your `rates`), 'tier' (recognized Claude tier — a confident guesstimate), 'default' (blind
+     * ceiling guesstimate — discount or override either guess), null (unpriced).
+     */
+    rateSource: "provider" | "caller" | "tier" | "default" | null;
     /**
      * - Neutral usage shape from the provider.
      */
@@ -121,9 +140,13 @@ export type JudgeVerdict = {
  * @property {import('../types').Provider} provider - LLM provider (bare-agent already owns the transport). To judge
  *   on a different tier, construct the provider FOR that tier — there is deliberately no per-call `model`/`effort`
  *   option, because the http providers build the request from `this.model` and would silently ignore them.
+ * @property {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}} [rates] - BA-21: per-1K USD
+ *   rates for the judge's own model, to price its call authoritatively (rateSource:'caller'). Omit → a flagged
+ *   guesstimate (rateSource:'tier' for a recognized Claude tier, else 'default'). Bring your own rate, or take a
+ *   guesstimate — never a silent guess.
  * @property {number} [maxTokens=512] - Cap on the judge's own output. A verdict truncated at the cap floors to
  *   `broke`; 512 clears the mechanical `where` with headroom (measured), lower it only if you know the artifacts are small.
- * @property {(payload: { usage: any, model: string|null, kind: 'judge', costUsd: number|null }) => any} [onLlmResult]
+ * @property {(payload: { usage: any, model: string|null, kind: 'judge', costUsd: number|null, rateSource: 'provider'|'caller'|'tier'|'default'|null }) => any} [onLlmResult]
  *   - Budget hook; each judge call forwards its usage/cost (mirror of Evaluator/remember).
  */
 /**
@@ -164,7 +187,10 @@ export function judge(options?: JudgeOptions): Promise<JudgeVerdict>;
  *   outcome (criterion 5): the verdict is floored to `broke` (fail toward surfacing) but callers/harnesses must EXCLUDE a
  *   truncated result from any graded denominator — never counted as a miss, never as a pass.
  * @property {boolean} parseError - The model did not return usable JSON. Floored to `broke`, flagged like truncation.
- * @property {number|null} costUsd - Real per-call cost. An HONEST null when the tier is unpriced (never coerced to 0).
+ * @property {number|null} costUsd - Per-call cost. An HONEST null only when genuinely unpriced (never coerced to 0).
+ * @property {'provider'|'caller'|'tier'|'default'|null} rateSource - WHERE costUsd came from (BA-21): 'provider'
+ *   (real), 'caller' (your `rates`), 'tier' (recognized Claude tier — a confident guesstimate), 'default' (blind
+ *   ceiling guesstimate — discount or override either guess), null (unpriced).
  * @property {any} usage - Neutral usage shape from the provider.
  * @property {string} model - The model that produced the verdict.
  * @property {string} raw - The model's raw text (for calibration/audit; scrub before persisting — contract 5).

package/src/judge.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { ValidationError, HaltError } = require('./errors');
-const { estimateCost, COST_PER_1K } = require('./loop');
+const { resolveRoundCost } = require('./loop');
 
 /**
  * The decisive return-time judge (BA-20 / bareguard E6i, PRD §9.2). It compares a
@@ -31,7 +31,10 @@ const { estimateCost, COST_PER_1K } = require('./loop');
  *   outcome (criterion 5): the verdict is floored to `broke` (fail toward surfacing) but callers/harnesses must EXCLUDE a
  *   truncated result from any graded denominator — never counted as a miss, never as a pass.
  * @property {boolean} parseError - The model did not return usable JSON. Floored to `broke`, flagged like truncation.
- * @property {number|null} costUsd - Real per-call cost. An HONEST null when the tier is unpriced (never coerced to 0).
+ * @property {number|null} costUsd - Per-call cost. An HONEST null only when genuinely unpriced (never coerced to 0).
+ * @property {'provider'|'caller'|'tier'|'default'|null} rateSource - WHERE costUsd came from (BA-21): 'provider'
+ *   (real), 'caller' (your `rates`), 'tier' (recognized Claude tier — a confident guesstimate), 'default' (blind
+ *   ceiling guesstimate — discount or override either guess), null (unpriced).
  * @property {any} usage - Neutral usage shape from the provider.
  * @property {string} model - The model that produced the verdict.
  * @property {string} raw - The model's raw text (for calibration/audit; scrub before persisting — contract 5).
@@ -124,9 +127,13 @@ function normalizeWhere(where) {
  * @property {import('../types').Provider} provider - LLM provider (bare-agent already owns the transport). To judge
  *   on a different tier, construct the provider FOR that tier — there is deliberately no per-call `model`/`effort`
  *   option, because the http providers build the request from `this.model` and would silently ignore them.
+ * @property {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}} [rates] - BA-21: per-1K USD
+ *   rates for the judge's own model, to price its call authoritatively (rateSource:'caller'). Omit → a flagged
+ *   guesstimate (rateSource:'tier' for a recognized Claude tier, else 'default'). Bring your own rate, or take a
+ *   guesstimate — never a silent guess.
  * @property {number} [maxTokens=512] - Cap on the judge's own output. A verdict truncated at the cap floors to
  *   `broke`; 512 clears the mechanical `where` with headroom (measured), lower it only if you know the artifacts are small.
- * @property {(payload: { usage: any, model: string|null, kind: 'judge', costUsd: number|null }) => any} [onLlmResult]
+ * @property {(payload: { usage: any, model: string|null, kind: 'judge', costUsd: number|null, rateSource: 'provider'|'caller'|'tier'|'default'|null }) => any} [onLlmResult]
  *   - Budget hook; each judge call forwards its usage/cost (mirror of Evaluator/remember).
  */
 
@@ -184,20 +191,16 @@ async function judge(options = /** @type {JudgeOptions} */ ({})) {
   const model = (out && out.model) || provider.model || null;
   const usage = (out && out.usage) || null;
 
-  // costUsd: prefer a finite provider-reported cost; else estimate ONLY when the tier is in the rate table; else
-  // an HONEST null (contract 1 / criterion 4). NEVER coerce to 0. Crucially, do NOT let `estimateCost` price an
-  // UNKNOWN model off its `_default` fallback — that returns a plausible number for an unpriced tier, silently
-  // violating "an unpriced call reds". A tier we cannot price must surface as null, not a made-up estimate.
-  let costUsd = null;
-  if (typeof out?.costUsd === 'number' && Number.isFinite(out.costUsd)) {
-    costUsd = out.costUsd;
-  } else if (model && usage && Object.prototype.hasOwnProperty.call(COST_PER_1K, model)) {
-    const est = estimateCost(model, usage);
-    if (typeof est === 'number' && Number.isFinite(est)) costUsd = est;
-  }
+  // costUsd (BA-21 uniform rule — "bring your own rate, or take a flagged guesstimate"): prefer a finite
+  // provider-reported cost (rateSource:'provider'); else caller `options.rates` (rateSource:'caller');
+  // else a built-in guesstimate (rateSource:'tier' for a recognized Claude tier, else 'default' for the
+  // blind ceiling) — never a silent guess, always flagged, never a refuse. NEVER coerce to 0. A consumer
+  // that wants the judge austere (no guess) reads rateSource 'tier'/'default' and discounts it, or passes
+  // its own rates. `null` only when genuinely unpriced.
+  const { cost: costUsd, source: rateSource } = resolveRoundCost(out, model, usage, options.rates || null);
   const onLlmResult = typeof options.onLlmResult === 'function' ? options.onLlmResult : null;
   if (onLlmResult) {
-    await onLlmResult({ usage, model, kind: 'judge', costUsd });
+    await onLlmResult({ usage, model, kind: 'judge', costUsd, rateSource });
   }
 
   // Truncation is a DISTINCT flagged outcome (contract 2 / criterion 5): the API cut the round off, or it came
@@ -217,6 +220,7 @@ async function judge(options = /** @type {JudgeOptions} */ ({})) {
     truncated,
     parseError,
     costUsd,
+    rateSource,
     usage,
     model: model || '',
     raw: text,

package/src/loop.d.ts

@@ -48,9 +48,25 @@ export type LoopOptions = {
     /**
      * - async (event) => void after each LLM call; forwards usage to
      * 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.
+     * `'summarize'` for an out-of-band `ctx.summarize` call (R-C6). Both count against the budget. Each
+     * event also carries `rateSource` ('provider'|'caller'|'tier'|'default'|null, BA-21) beside the
+     * unchanged two-value `pricing` — a 'tier'/'default' cost is a flagged guesstimate, never a silent
+     * guess ('tier' = recognized Claude tier, 'default' = blind ceiling fallback).
      */
     onLlmResult?: Function | undefined;
+    /**
+     * - BA-21:
+     * per-1K USD rates for THIS run's model (`in`/`out` required, finite, non-negative; cache multipliers
+     * default to Anthropic's 0.1×/1.25×). When set, every token-only round is priced from these
+     * (rateSource:'caller') instead of the built-in guesstimate. There is NO per-model rate table — bring
+     * your own rate, or take a flagged guesstimate (haiku/sonnet recognized, else the Sonnet-tier default).
+     */
+    rates?: {
+        in: number;
+        out: number;
+        cacheReadMult?: number;
+        cacheWriteMult?: number;
+    } | undefined;
     onToolResult?: Function | undefined;
     /**
      * - BA-12 safety net (default 3). Short-circuit the run when a
@@ -108,6 +124,12 @@ export class Loop {
     trim: Function | null;
     onLlmResult: Function | null;
     onToolResult: Function | null;
+    rates: {
+        in: number;
+        out: number;
+        cacheReadMult?: number;
+        cacheWriteMult?: number;
+    } | null;
     _stopped: boolean;
     /** @type {Message[]} */
     _history: Message[];
@@ -117,6 +139,9 @@ export class Loop {
      * @param {Record<string, any>} [extra]
      */
     _reportError(source: string, err: any, extra?: Record<string, any>): void;
+    /** @param {string|null} model @param {string} rateSource - 'tier' | 'default' */
+    _warnGuesstimateOnce(model: string | null, rateSource: string): void;
+    _warnedGuesstimate: boolean | undefined;
     /** @param {{type: string, data?: any, ts?: string}} event */
     _safeEmit(event: {
         type: string;
@@ -225,82 +250,69 @@ export class Loop {
  * Estimate the USD cost of one round's usage, pricing the FOUR token tiers separately (D9/L7):
  * uncached input, output, cache-read, and cache-creation. Folding cache tokens into the full input
  * rate mis-prices badly — a warm prompt is mostly cache-read (~0.1–0.5× input) and Anthropic's
- * cache-creation is a ~1.25× premium — so each tier gets its own rate. Returns null (not 0) when the
- * model is unknown/absent so the caller can mark the round `unpriced` rather than silently free.
+ * cache-creation is a ~1.25× premium — so each tier gets its own rate. The rate comes from
+ * `resolveRates` (caller `rates` → recognized tier → Sonnet-tier ceiling default), so a token-bearing
+ * round is ALWAYS priced (guesstimate-and-run per BA-21) — a null model no longer forces `unpriced`.
+ * Returns null ONLY when usage is absent, or the arithmetic is non-finite (runaway ±Infinity), the
+ * genuinely-unpriceable cases that must stay `unpriced` / fail-closed.
  * @param {string|null} model
  * @param {Usage|null} usage
+ * @param {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}|null} [callerRates]
  * @returns {number|null}
  */
-export function estimateCost(model: string | null, usage: Usage | null): number | null;
-/** @typedef {import('../types').Provider} Provider */
-/** @typedef {import('../types').Message} Message */
-/** @typedef {import('../types').ToolDef} ToolDef */
-/** @typedef {import('../types').ToolCall} ToolCall */
-/** @typedef {import('../types').Usage} Usage */
-/** @typedef {import('../types').RunMetrics} RunMetrics */
-/** @typedef {import('../types').GenerateResult} GenerateResult */
-/** @typedef {import('../types').Store} Store */
-/** @typedef {import('./checkpoint').Checkpoint} Checkpoint */
-/** @typedef {import('./retry').Retry} Retry */
-/** @typedef {import('./stream').Stream} Stream */
+export function estimateCost(model: string | null, usage: Usage | null, callerRates?: {
+    in: number;
+    out: number;
+    cacheReadMult?: number;
+    cacheWriteMult?: number;
+} | null): number | null;
+/**
+ * Resolve the effective per-1K rate for a round, and WHERE it came from. Caller-supplied `rates` win
+ * (authoritative to the caller, `'caller'`); else a recognized Claude tier matched by the model id
+ * (`'tier'` — a confident but non-caller-vouched guess); else the Sonnet-tier ceiling fallback
+ * (`'default'` — a blind guess for an unknown/absent model). A null model still resolves to the
+ * ceiling — we guesstimate and run, never refuse. `'tier'` and `'default'` are BOTH built-in
+ * guesstimates (see `isGuesstimateSource`); the split only lets a consumer tell a recognized-tier
+ * price from a blind ceiling in its own ledger (BA-21 follow-up, requested by the bareloop adopter).
+ * @param {string|null|undefined} model
+ * @param {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}|null} [callerRates]
+ * @returns {{rates: {in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}, source: 'caller'|'tier'|'default'}}
+ */
+export function resolveRates(model: string | null | undefined, callerRates?: {
+    in: number;
+    out: number;
+    cacheReadMult?: number;
+    cacheWriteMult?: number;
+} | null): {
+    rates: {
+        in: number;
+        out: number;
+        cacheReadMult?: number;
+        cacheWriteMult?: number;
+    };
+    source: "caller" | "tier" | "default";
+};
 /**
- * @typedef {object} LoopOptions
- * @property {Provider} provider
- * @property {string} [system]
- * @property {Checkpoint} [checkpoint]
- * @property {Retry} [retry]
- * @property {Stream} [stream]
- * @property {Store} [store]
- * @property {Function} [onToolCall]
- * @property {Function} [onText]
- * @property {Function} [onError]
- * @property {boolean} [throwOnError]
- * @property {Function} [policy]
- * @property {Function} [assemble] - async (msgs, ctx) => msgs. Context-assembly chokepoint: shape the
- *   window sent to the provider each round (e.g. a context-engineering library). Returns a VIEW — the
- *   canonical transcript is never mutated. Fail-open (a thrown error degrades to full context); a
- *   thrown HaltError propagates. `ctx` is the per-run opaque blob (`run(msgs, tools, { ctx })`), the
- *   same object forwarded to `policy`; litectx reads `ctx.task` (intent) and `ctx.budget`. The
- *   neutral-unit signature `assemble(units, ctx)` is provided by bareagent's msgs⇄units adapter
- *   (src/context-units.js), which composes over this msgs-level seam. When `ctx` is an object, the
- *   Loop also lends a provider-bound `ctx.summarize(excerpt, opts?) => Promise<string>` (R-C6,
- *   non-enumerable): assemble calls it to roll a summary window — bareagent makes the one model
- *   call, the consumer owns the trigger/N/splice. Its usage is forwarded to `onLlmResult` so the
- *   summary tokens count against the budget.
- * @property {Function} [trim] - async (msgs, ctx) => msgs. DESTRUCTIVE transcript-trim chokepoint (RT-2),
- *   the opposite of `assemble`: it BOUNDS the canonical transcript — the Loop replaces `msgs` with what
- *   this returns, evicting old turns AFTER they are harvested. Runs once per round before `assemble`.
- *   So eviction never drops un-persisted history, wire it via `unitTrimmer({ trim, onHarvest, policy })`
- *   (src/context-units.js), which performs the harvest-before-evict interlock over litectx's `trim` verb.
- *   An optional `.flush(msgs, ctx)` method is called on clean completion for the residual-window harvest.
- *   Fail-open (a trim fault degrades to no eviction that round); a thrown HaltError propagates.
- * @property {Function} [onLlmResult] - async (event) => void after each LLM call; forwards usage to
- *   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} [maxIdenticalToolErrors] - BA-12 safety net (default 3). Short-circuit the run when a
- *   tool's `execute` throws this many times IN A ROW for a BYTE-IDENTICAL call (same tool + same args). A
- *   tool error is deliberately fed back to the model so it can recover — that is the point of the feedback
- *   loop — but a model re-issuing the SAME impossible call verbatim can never succeed, and spins to the
- *   budget cap with no progress (observed live: `claude-sonnet-5` retried a rejected write 8/8 times).
- *   Deliberately the NARROWEST guard: any tool call that SUCCEEDS, or the same tool called with DIFFERENT
- *   arguments, resets the streak — a model adapting its input in response to an error is genuinely
- *   recovering and is never penalised. Returns cleanly with `error: 'stuck:<tool>'` (mirrors the deny/halt
- *   returns; never throws even under `throwOnError`; transcript sealed; the model's text preserved).
- *   `0`/`Infinity` disables (restores pre-BA-12 behavior: errors are advisory forever).
- * @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.
+ * Resolve the priced USD for a round AND its `rateSource`. A provider MAY report its own authoritative
+ * `costUsd` on the GenerateResult (e.g. CLIPipeProvider surfacing the claude CLI's `total_cost_usd` — a
+ * real price, `source:'provider'`). When present as a FINITE number it wins over any estimate —
+ * including `0`, a valid priced value (a subscription/marginal-$0 run), which stays priced. A non-finite
+ * provider cost (±Inf/NaN) is NOT a price → fall through to the rate-based estimate (`caller`/`default`).
+ * `source` is null only when the round is genuinely unpriced (no usage, or a non-finite estimate).
+ * A rate-estimated round is `'caller'` (caller rates), `'tier'` (recognized Claude tier), or `'default'`
+ * (blind ceiling fallback) — the last two are both built-in guesstimates (`isGuesstimateSource`).
+ * @param {any} result - the GenerateResult from provider.generate()
+ * @param {string|null} model
+ * @param {Usage|null} usage
+ * @param {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}|null} [callerRates]
+ * @returns {{cost: number|null, source: 'provider'|'caller'|'tier'|'default'|null}}
  */
-/** @type {Record<string, {in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}>} */
-export const COST_PER_1K: Record<string, {
+export function resolveRoundCost(result: any, model: string | null, usage: Usage | null, callerRates?: {
     in: number;
     out: number;
     cacheReadMult?: number;
     cacheWriteMult?: number;
-}>;
+} | null): {
+    cost: number | null;
+    source: "provider" | "caller" | "tier" | "default" | null;
+};

package/src/loop.js

@@ -48,7 +48,15 @@ const { classifyStopReason } = require('./provider-stop-reason');
  *   Fail-open (a trim fault degrades to no eviction that round); a thrown HaltError propagates.
  * @property {Function} [onLlmResult] - async (event) => void after each LLM call; forwards usage to
  *   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.
+ *   `'summarize'` for an out-of-band `ctx.summarize` call (R-C6). Both count against the budget. Each
+ *   event also carries `rateSource` ('provider'|'caller'|'tier'|'default'|null, BA-21) beside the
+ *   unchanged two-value `pricing` — a 'tier'/'default' cost is a flagged guesstimate, never a silent
+ *   guess ('tier' = recognized Claude tier, 'default' = blind ceiling fallback).
+ * @property {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}} [rates] - BA-21:
+ *   per-1K USD rates for THIS run's model (`in`/`out` required, finite, non-negative; cache multipliers
+ *   default to Anthropic's 0.1×/1.25×). When set, every token-only round is priced from these
+ *   (rateSource:'caller') instead of the built-in guesstimate. There is NO per-model rate table — bring
+ *   your own rate, or take a flagged guesstimate (haiku/sonnet recognized, else the Sonnet-tier default).
  * @property {Function} [onToolResult]
  * @property {number} [maxIdenticalToolErrors] - BA-12 safety net (default 3). Short-circuit the run when a
  *   tool's `execute` throws this many times IN A ROW for a BYTE-IDENTICAL call (same tool + same args). A
@@ -70,41 +78,70 @@ const { classifyStopReason } = require('./provider-stop-reason');
  * @property {number} [maxRounds] - Removed in v0.8; presence throws a migration error.
  */
 
-// Average pricing per 1K tokens (USD). Adjust these to match your provider's rates.
-// Last updated: 2026-06-22. Source: public provider pricing pages (Anthropic rates + cache multipliers
-// cross-checked against the claude-api reference). Rates are USD per 1K tokens. `cacheReadMult` /
-// `cacheWriteMult` are multipliers ON the input rate for the two cache tiers (see estimateCost); when
-// omitted they default to Anthropic's convention (read 0.1×, write 1.25×). OpenAI/Gemini have no
-// cache-WRITE surcharge (their providers report cacheCreationTokens=0), so only cacheReadMult matters
-// there. NOTE: OpenAI's cached discount is ~0.5× on the 4o family; some newer models (4.1/o-series) are
-// ~0.25× — set to 0.5× here as the documented general value; refine per-model against current pricing.
+// BA-21 — pricing is "bring your own rate, or take a flagged guesstimate", NOT a maintained per-model
+// table (a table rots: every new model + every price change is a code edit, and a stale row silently
+// misprices). No vanilla LLM API returns a price — every provider reports tokens only (the sole real $
+// in the codebase comes from the CLIPipe/Claude-CLI harness's own `total_cost_usd`, handled via the
+// provider `costUsd` path). So a token-only round is priced from a RATE, surfaced on every metering
+// payload as `rateSource` (four non-null values — two authoritative, two built-in guesstimates):
+//   'provider' — the provider reported an authoritative `costUsd` (real; e.g. the CLI harness).
+//   'caller'   — the caller passed `new Loop({ rates })` with its own model's numbers (authoritative to it).
+//   'tier'     — a recognized Claude tier (haiku/sonnet) matched by the model id: a confident but
+//                non-caller-vouched GUESSTIMATE (the hardcoded tier rate could drift from Anthropic's).
+//   'default'  — nobody supplied a rate and the model was unrecognized/absent, so we GUESSTIMATE and RUN
+//                off the ceiling, flagged as a blind guess (never a silent refuse — governance's job is
+//                to keep the user in the know, not to stop on a missing rate).
+// 'tier' and 'default' are BOTH guesstimates (`isGuesstimateSource`): they drive the pass-but-warn and
+// the `estimatedRounds` counter identically; the split only lets a consumer tell a recognized-tier price
+// from a blind ceiling in its own ledger (BA-21 follow-up, requested by the bareloop adopter).
+// The guesstimate recognizes the two Claude tiers in common use (haiku/sonnet) and otherwise falls to
+// the Sonnet-tier default — the common workhorse rate, "usually more expensive" than the cheap models
+// so a budget cap over- rather than under-reports on an unrecognized model, without the absurd
+// over-report an Opus ceiling would inflict on a cheap one. Any 'default'-priced round ALSO emits a
+// one-time loud warning per Loop instance (pass-but-warn) so the guess is never quietly relied on — a
+// caller pricing a different/cheaper model passes `rates` to correct it (and silence the warning).
+// Rates are USD per 1K tokens; `cacheReadMult`/`cacheWriteMult` are multipliers ON the input rate for
+// the two cache tiers (default to Anthropic's 0.1×/1.25× when omitted).
+/** @type {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}} */
+const DEFAULT_RATES = { in: 0.003, out: 0.015 }; // Sonnet-tier: the common workhorse rate, the guesstimate default
 /** @type {Record<string, {in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}>} */
-const COST_PER_1K = {
-  // OpenAI — cached input ~0.5× (no write tier)
-  'gpt-4o': { in: 0.0025, out: 0.01, cacheReadMult: 0.5 },
-  'gpt-4o-mini': { in: 0.00015, out: 0.0006, cacheReadMult: 0.5 },
-  'gpt-4.1': { in: 0.002, out: 0.008, cacheReadMult: 0.5 },
-  'gpt-4.1-mini': { in: 0.0004, out: 0.0016, cacheReadMult: 0.5 },
-  'gpt-4.1-nano': { in: 0.0001, out: 0.0004, cacheReadMult: 0.5 },
-  'o3-mini': { in: 0.0011, out: 0.0044, cacheReadMult: 0.5 },
-  // Anthropic — Claude current generation (2026-06). Cache tiers use the default 0.1×/1.25×.
-  'claude-fable-5': { in: 0.01, out: 0.05 },
-  'claude-opus-4-8': { in: 0.005, out: 0.025 },
-  'claude-opus-4-7': { in: 0.005, out: 0.025 },
-  'claude-opus-4-6': { in: 0.005, out: 0.025 },
-  'claude-sonnet-4-6': { in: 0.003, out: 0.015 },
-  'claude-haiku-4-5-20251001': { in: 0.001, out: 0.005 },
-  'claude-haiku-4-5': { in: 0.001, out: 0.005 },
-  // Anthropic — earlier snapshots (the original Opus 4 / Sonnet 4 generation, genuinely different rates)
-  'claude-sonnet-4-20250514': { in: 0.003, out: 0.015 },
-  'claude-opus-4-20250514': { in: 0.015, out: 0.075 },
-  // Google Gemini — cached content ~0.25× (no write tier). Native provider lands in a following piece.
-  'gemini-2.5-flash': { in: 0.0003, out: 0.0025, cacheReadMult: 0.25 },
-  'gemini-2.5-pro': { in: 0.00125, out: 0.01, cacheReadMult: 0.25 },
-  // Fallback average across popular models (~$0.002 in, ~$0.008 out per 1K)
-  '_default': { in: 0.002, out: 0.008 },
+const TIER_RATES = {
+  haiku: { in: 0.001, out: 0.005 },   // low tier (cheaper than the default — recognized so it isn't over-reported)
+  sonnet: { in: 0.003, out: 0.015 },  // middle tier (== the default; standing rate, over-reports vs the intro rate)
 };
 
+/**
+ * Resolve the effective per-1K rate for a round, and WHERE it came from. Caller-supplied `rates` win
+ * (authoritative to the caller, `'caller'`); else a recognized Claude tier matched by the model id
+ * (`'tier'` — a confident but non-caller-vouched guess); else the Sonnet-tier ceiling fallback
+ * (`'default'` — a blind guess for an unknown/absent model). A null model still resolves to the
+ * ceiling — we guesstimate and run, never refuse. `'tier'` and `'default'` are BOTH built-in
+ * guesstimates (see `isGuesstimateSource`); the split only lets a consumer tell a recognized-tier
+ * price from a blind ceiling in its own ledger (BA-21 follow-up, requested by the bareloop adopter).
+ * @param {string|null|undefined} model
+ * @param {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}|null} [callerRates]
+ * @returns {{rates: {in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}, source: 'caller'|'tier'|'default'}}
+ */
+function resolveRates(model, callerRates) {
+  if (callerRates) return { rates: callerRates, source: 'caller' };
+  if (model) {
+    const m = String(model).toLowerCase();
+    if (m.includes('haiku')) return { rates: TIER_RATES.haiku, source: 'tier' };
+    if (m.includes('sonnet')) return { rates: TIER_RATES.sonnet, source: 'tier' };
+  }
+  return { rates: DEFAULT_RATES, source: 'default' };
+}
+
+// BA-21 follow-up: a built-in guesstimate is either a recognized-tier match (`'tier'`) or the blind
+// ceiling fallback (`'default'`) — both are non-authoritative (unlike `'provider'`/`'caller'`), so both
+// drive the pass-but-warn and the `estimatedRounds` counter. One predicate keeps those two call sites
+// from drifting apart if the vocabulary grows again. Typed as a TS predicate so a guarded call narrows
+// `rateSource` to the two guesstimate literals (drops `null`) before it reaches the warn.
+/** @param {string|null} source @returns {source is 'tier'|'default'} */
+function isGuesstimateSource(source) {
+  return source === 'tier' || source === 'default';
+}
+
 // Internal safety net only — real iteration bounds come from a wired bareguard
 // Gate via `limits.maxTurns`. If you hit this without bareguard wired, you have
 // no governance and the LLM loop is unbounded by design — wire bareguard.
@@ -143,15 +180,19 @@ function sealDanglingToolCalls(msgs, marker) {
  * Estimate the USD cost of one round's usage, pricing the FOUR token tiers separately (D9/L7):
  * uncached input, output, cache-read, and cache-creation. Folding cache tokens into the full input
  * rate mis-prices badly — a warm prompt is mostly cache-read (~0.1–0.5× input) and Anthropic's
- * cache-creation is a ~1.25× premium — so each tier gets its own rate. Returns null (not 0) when the
- * model is unknown/absent so the caller can mark the round `unpriced` rather than silently free.
+ * cache-creation is a ~1.25× premium — so each tier gets its own rate. The rate comes from
+ * `resolveRates` (caller `rates` → recognized tier → Sonnet-tier ceiling default), so a token-bearing
+ * round is ALWAYS priced (guesstimate-and-run per BA-21) — a null model no longer forces `unpriced`.
+ * Returns null ONLY when usage is absent, or the arithmetic is non-finite (runaway ±Infinity), the
+ * genuinely-unpriceable cases that must stay `unpriced` / fail-closed.
  * @param {string|null} model
  * @param {Usage|null} usage
+ * @param {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}|null} [callerRates]
  * @returns {number|null}
  */
-function estimateCost(model, usage) {
-  if (!usage || !model) return null;
-  const rates = COST_PER_1K[model] || COST_PER_1K['_default'];
+function estimateCost(model, usage, callerRates) {
+  if (!usage) return null;
+  const { rates } = resolveRates(model, callerRates || null);
   const readMult = rates.cacheReadMult ?? 0.1;    // Anthropic convention when unspecified
   const writeMult = rates.cacheWriteMult ?? 1.25;
   const cost = (
@@ -160,29 +201,35 @@ function estimateCost(model, usage) {
     (usage.cacheReadTokens || 0) * rates.in * readMult +
     (usage.cacheCreationTokens || 0) * rates.in * writeMult
   ) / 1000;
-  // A non-finite cost (±Infinity from runaway token counts, NaN from a garbage rate-table entry) is a
+  // A non-finite cost (±Infinity from runaway token counts, NaN from a garbage caller rate) is a
   // COULDN'T-PRICE, not a price. Return null so the round is marked `unpriced` and the value never
   // poisons `totalCost`, `result.metrics.costUsd`, or — via onLlmResult → the gate — `spentUsd`. The
   // last is the dangerous one: `NaN >= cap` is false, which would DISABLE a budget cap, not just
-  // under-count it. Same silent-unenforceable class as a null model (§3.7).
+  // under-count it. This is the ONE fail-closed pricing case (§3.7).
   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).
+ * Resolve the priced USD for a round AND its `rateSource`. A provider MAY report its own authoritative
+ * `costUsd` on the GenerateResult (e.g. CLIPipeProvider surfacing the claude CLI's `total_cost_usd` — a
+ * real price, `source:'provider'`). When present as a FINITE number it wins over any estimate —
+ * including `0`, a valid priced value (a subscription/marginal-$0 run), which stays priced. A non-finite
+ * provider cost (±Inf/NaN) is NOT a price → fall through to the rate-based estimate (`caller`/`default`).
+ * `source` is null only when the round is genuinely unpriced (no usage, or a non-finite estimate).
+ * A rate-estimated round is `'caller'` (caller rates), `'tier'` (recognized Claude tier), or `'default'`
+ * (blind ceiling fallback) — the last two are both built-in guesstimates (`isGuesstimateSource`).
  * @param {any} result - the GenerateResult from provider.generate()
  * @param {string|null} model
  * @param {Usage|null} usage
- * @returns {number|null}
+ * @param {{in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}|null} [callerRates]
+ * @returns {{cost: number|null, source: 'provider'|'caller'|'tier'|'default'|null}}
  */
-function resolveRoundCost(result, model, usage) {
-  if (result && Number.isFinite(result.costUsd)) return result.costUsd;
-  return estimateCost(model, usage);
+function resolveRoundCost(result, model, usage, callerRates) {
+  if (result && Number.isFinite(result.costUsd)) return { cost: result.costUsd, source: 'provider' };
+  if (!usage) return { cost: null, source: null };
+  const { source } = resolveRates(model, callerRates || null);
+  const cost = estimateCost(model, usage, callerRates || null);
+  return { cost, source: cost === null ? null : source };
 }
 
 // R-C6: default instruction for the provider-bound `ctx.summarize` lent to the assemble seam.
@@ -309,6 +356,16 @@ class Loop {
     }
     this.onLlmResult = options.onLlmResult || null;
     this.onToolResult = options.onToolResult || null;
+    // BA-21: caller-supplied per-1K rates ({in, out, cacheReadMult?, cacheWriteMult?}) for THIS run's
+    // model. When set, they price every token-only round (rateSource:'caller') instead of the built-in
+    // guesstimate. `in`/`out` are required and must be finite non-negative numbers.
+    if (options.rates != null) {
+      const r = options.rates;
+      if (typeof r !== 'object' || !Number.isFinite(r.in) || !Number.isFinite(r.out) || r.in < 0 || r.out < 0) {
+        throw new Error('[Loop] options.rates must be { in, out, cacheReadMult?, cacheWriteMult? } with finite non-negative in/out (USD per 1K tokens)');
+      }
+    }
+    this.rates = options.rates || null;
     this._stopped = false;
     /** @type {Message[]} */
     this._history = []; // for chat() stateful mode
@@ -334,6 +391,28 @@ class Loop {
     }
   }
 
+  // BA-21 pass-but-warn: the FIRST round priced off a built-in guesstimate (rateSource:'tier' or
+  // 'default' — no provider cost, no caller `rates`) emits ONE loud warning per Loop instance. Loud
+  // because a silent guess is exactly the honesty gap BA-21 closes; once-per-instance because per-round
+  // would be noise. Fires for a recognized-tier price too (it is still non-authoritative), and the
+  // message names the ACTUAL source so a 'tier' round isn't mislabelled 'default'. Silenced entirely by
+  // passing `new Loop({ rates })`. `console.warn` mirrors the temperature-degrade precedent; the
+  // structured signal for programmatic consumers is `rateSource` on every payload.
+  /** @param {string|null} model @param {string} rateSource - 'tier' | 'default' */
+  _warnGuesstimateOnce(model, rateSource) {
+    if (this._warnedGuesstimate) return;
+    this._warnedGuesstimate = true;
+    // `model` is provider-reported (`result.model || provider.model`) — strip control chars/ANSI and
+    // clamp before it reaches stderr, so a loose/hostile provider can't inject terminal escapes or a
+    // giant string into this diagnostic. Log-hygiene only; no secret ever rides in a model id.
+    const safeModel = model ? String(model).replace(/[\x00-\x1f\x7f]/g, '').slice(0, 80) : null;
+    console.warn(
+      `[Loop] pricing with a built-in GUESSTIMATE rate (rateSource:'${rateSource}'${safeModel ? `, model '${safeModel}'` : ''}) — `
+      + 'cost/budget figures are approximate. Pass new Loop({ rates: { in, out } }) with your model\'s '
+      + 'USD-per-1K rates for an authoritative price (and to silence this warning).'
+    );
+  }
+
   // Swallow-proof stream emit: a throwing listener must not corrupt Loop state.
   /** @param {{type: string, data?: any, ts?: string}} event */
   _safeEmit(event) {
@@ -525,6 +604,10 @@ class Loop {
       byTool: {},
       tokens: { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 },
       unpricedRounds: 0,
+      // BA-21 — priced rounds whose rate was a built-in guesstimate (rateSource:'tier' or 'default'), i.e.
+      // no provider cost and no caller `rates`. Not unpriced (they DID price and count against budget); a
+      // guess flagged so a consumer can see how much of the spend was estimated vs a real/supplied rate.
+      estimatedRounds: 0,
       // §3.6 CE-activity rollup — convenience counts derived in-place from the same events already
       // on the Stream (loop:trim, loop:summarize), not a second source. `compactions` counts
       // destructive trim evictions; `summaries` counts ctx.summarize calls; `tokensTrimmed` is an
@@ -561,6 +644,7 @@ class Loop {
       tokens: { ...metrics.tokens },
       costUsd: pricedAny ? totalCost : null,
       unpricedRounds: metrics.unpricedRounds,
+      estimatedRounds: metrics.estimatedRounds, // BA-21 — rounds priced off the built-in guesstimate
       spawned: metrics.byTool.spawn || 0, // §3.6 — spawn-tool invocations (byTool counts every call, incl. denied)
       context: { ...metrics.context }, // §3.6 CE-activity rollup
       memory: { ...metrics.memory }, // §3.6 memory footprint (stashed/episodes/recalls/stored/facts; see init note)
@@ -606,7 +690,8 @@ 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 = resolveRoundCost(result, model, usage);
+        const { cost, source: rateSource } = resolveRoundCost(result, model, usage, loop.rates);
+        if (isGuesstimateSource(rateSource)) loop._warnGuesstimateOnce(model, rateSource);
         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
@@ -619,6 +704,7 @@ class Loop {
               usage,
               costUsd: cost,
               pricing: cost === null ? 'unpriced' : 'priced',
+              rateSource, // BA-21: 'provider'|'caller'|'tier'|'default'|null — 'tier'/'default' is a flagged guesstimate
               durationMs: Date.now() - startedAt,
               ctx,
               kind: 'summarize',
@@ -764,15 +850,25 @@ 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 = resolveRoundCost(result, model, lastUsage);
+      // BA-23: price THIS round's usage, never the stale `lastUsage` carry-over. `lastUsage` is a truthy
+      // zero-object seed (line 530) kept across null/absent-usage rounds (line 832) for the BA-5 returns +
+      // ctx.usage publish — but handing it to the resolver made its `if (!usage) return {cost:null}` branch
+      // (resolveRoundCost line ~229) DEAD: a genuinely no-usage round was laundered into costUsd:0/priced
+      // (against the "honest null if unpriced, never 0" contract), and a MID-RUN no-usage round was priced
+      // on the PREVIOUS round's tokens — a stale repeat charge. addUsage below already uses result.usage.
+      const { cost: roundCost, source: rateSource } = resolveRoundCost(result, model, result.usage ?? null, this.rates);
+      if (isGuesstimateSource(rateSource)) this._warnGuesstimateOnce(model, rateSource);
       if (roundCost !== null) totalCost += roundCost;
 
       // Meter this round: count the turn, accumulate the four token tiers, and classify pricing —
-      // an unpriced round (null cost: no model / no rate) is tallied so the run is observably
-      // unenforceable on budget rather than silently free (the #3 cost contract).
+      // an unpriced round (null cost: no usage, or a runaway non-finite estimate) is tallied so the run
+      // is observably unenforceable on budget rather than silently free (the #3 cost contract). A round
+      // priced off a built-in guesstimate (rateSource:'tier' or 'default') is counted as an estimate too,
+      // so a consumer can see how much of the spend was guessed (BA-21 — keep the user in the know).
       metrics.turns++;
       addUsage(result.usage);
       if (roundCost === null) metrics.unpricedRounds++; else pricedAny = true;
+      if (isGuesstimateSource(rateSource)) metrics.estimatedRounds++;
       // BA-16: a cycle-owning provider reports what really happened inside its session.
       const session = (result.session && typeof result.session === 'object') ? result.session : null;
       if (session) {
@@ -796,8 +892,11 @@ class Loop {
             usage: result.usage || null,
             costUsd: roundCost,
             // Priced vs unpriced is explicit so the gate never mistakes "couldn't price" (null) for
-            // "free" (0) — the silent-zero that made #3's budget cap a no-op. (D5 / §3.7.)
+            // "free" (0) — the silent-zero that made #3's budget cap a no-op. (D5 / §3.7.) `rateSource`
+            // is the honesty axis BESIDE it: 'default' means the number is a flagged guesstimate, never
+            // a silent guess stamped as if it were a real rate (BA-21). `pricing` keeps its two values.
             pricing: roundCost === null ? 'unpriced' : 'priced',
+            rateSource, // 'provider'|'caller'|'tier'|'default'|null
             durationMs: Date.now() - llmStartedAt,
             ctx,
             kind: 'turn',
@@ -1213,4 +1312,4 @@ class Loop {
   }
 }
 
-module.exports = { Loop, estimateCost, COST_PER_1K };
+module.exports = { Loop, estimateCost, resolveRates, resolveRoundCost };

package/src/provider-clipipe-mcp.js

@@ -462,6 +462,7 @@ function createSessionStream({ onTurn, ctx, startedAt, onHalt, turnCap = null, o
               usage,
               costUsd: null, // the CLI prices the SESSION, not the turn — explicitly unpriced, never a synthetic 0.
               pricing: 'unpriced',
+              rateSource: null, // BA-22: no price to vouch for → null, NEVER 'provider' (negative control); rides every payload
               durationMs: Date.now() - startedAt,
               ctx, // what a wired gate records spend against — same as the Loop's onLlmResult.
               kind: 'turn',

package/src/provider-clipipe.d.ts

@@ -59,9 +59,11 @@ export type CLIPipeOptions = {
     policy?: ((tool: string, args: any, ctx?: any) => any) | undefined;
     /**
      * - (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
+     * rateSource, durationMs, ctx, kind}` for EACH completed CLI turn as it arrives (`kind:'turn'`, four
+     * cache tiers, `costUsd:null`/`rateSource:null` — the CLI prices the session, not the turn), then once
+     * at session end (`kind:'session'`) carrying the authoritative total cost with zero usage and
+     * `rateSource:'provider'` when that cost is finite (BA-22 — the CLI's own `total_cost_usd`, no rate
+     * table; `null` cost → `rateSource:null`, never a spurious 'provider'). 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.

package/src/provider-clipipe.js

@@ -37,9 +37,11 @@ const { createBridge, resolveSessionError, runSession } = require('./provider-cl
  *   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
+ *   rateSource, durationMs, ctx, kind}` for EACH completed CLI turn as it arrives (`kind:'turn'`, four
+ *   cache tiers, `costUsd:null`/`rateSource:null` — the CLI prices the session, not the turn), then once
+ *   at session end (`kind:'session'`) carrying the authoritative total cost with zero usage and
+ *   `rateSource:'provider'` when that cost is finite (BA-22 — the CLI's own `total_cost_usd`, no rate
+ *   table; `null` cost → `rateSource:null`, never a spurious 'provider'). 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.
@@ -369,6 +371,11 @@ class CLIPipeProvider {
           usage: residual,
           costUsd,
           pricing: costUsd === null ? 'unpriced' : 'priced',
+          // BA-22: the session cost is the claude CLI's own `total_cost_usd` (no local rate table) — a
+          // provider reporting its authoritative cost, exactly what rateSource:'provider' means. Stamp it
+          // ONLY when finite (costUsd is finite-or-null per the guard above); a null cost never claims
+          // 'provider' provenance. Native mode bypasses the Loop's resolveRoundCost, so it stamps its own.
+          rateSource: costUsd === null ? null : 'provider',
           durationMs: r.ms,
           ctx: options.ctx,
           kind: 'session',

package/types/index.d.ts

@@ -47,8 +47,10 @@ export interface RunMetrics {
   tokens: { input: number; output: number; cacheCreation: number; cacheRead: number };
   /** Cumulative USD over priced rounds; null ONLY if nothing could be priced (explicit-unknown, not free). */
   costUsd: number | null;
-  /** Count of rounds whose cost could not be computed (no model / no rate) — the loud-unpriced signal. */
+  /** Count of rounds genuinely unpriceable (no usage, or a runaway non-finite estimate) — the loud-unpriced signal. */
   unpricedRounds: number;
+  /** BA-21: count of priced rounds whose rate was a built-in guesstimate (rateSource:'tier' or 'default'), not a real/supplied rate. */
+  estimatedRounds: number;
   /** Spawn-tool invocations this run (the `spawn` tool count — counts every call, incl. denied/failed). */
   spawned: number;
   /**