bare-agent 0.31.0 → 0.32.0

package/README.md

@@ -121,7 +121,7 @@ console.log(result.count, result.matchedIds);   // a code-derived count + the id
 
 **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' }`. The same bound covers a tool that keeps *failing*: `maxIdenticalToolErrors` (default 3) stops a model re-sending a byte-identical call that cannot succeed, with `error:'stuck:<tool>'`. `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.
+**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. **CLIPipe can drive a full agentic Loop — tools and turns — over a CLI *subscription* instead of the metered API** (`CLIPipeProvider({ command:'claude', args:['-p','--model','sonnet'], toolProtocol:'claude' })`): schema-validated tool emulation with the Loop keeping governance, and a capable model enforced upfront (v0.32.0, sonnet-class+ for tools; Claude CLI for now).
 
 **The run tells you the truth about what happened on the wire.** Every provider reports **why** generation ended (`stopReason`, normalized across all of them and surfaced on **every** `Loop.run()` return), so a round the API **cut off at the token cap** can no longer masquerade as a finished answer: it returns `error: 'truncated:max_tokens'` with the partial text preserved, instead of a silent `error: null` (BA-6). Its tool calls are **refused, never executed** — a *complete* tool call always arrives tagged `tool_use`, so one riding a truncated round was cut off mid-generation with arguments missing, which is exactly how a truncated `shell_write` can zero a file. The same honesty now covers **every** non-clean terminal signal (BA-13): a safety `refusal` returns `error: 'refusal'` and a blown context window returns `error: 'context_exceeded'` (both were previously laundered into an empty success), while a resumable `pause_turn` makes the loop resume rather than terminate. `error` is the sole success signal; a bound firing preserves the model's work rather than discarding it (BA-5).
 

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.31.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
+> v0.32.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -60,6 +60,7 @@ Eight entry points:
 | 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' }) |
+| Drive tools over a CLI subscription (no metered API) | CLIPipeProvider({ toolProtocol: 'claude' }) |
 | 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`) |
@@ -800,6 +801,12 @@ new CLIPipe({ command: 'claude', args: ['--print'], systemPromptFlag: '--system-
 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' })
+// CLIPipe TOOL MODE (v0.32.0+) — drive a Loop's tools over a CLI SUBSCRIPTION (no metered API).
+// toolProtocol enables schema-validated tool emulation; the Loop keeps governance/round-accounting.
+// Tools are auto-used when passed; a weak model (e.g. haiku) is rejected UPFRONT by a capability
+// probe (needs sonnet-class+ for tools; haiku is fine for plain text). setting-sources '' is applied
+// internally for an ~18x cost drop. Claude-only for now.
+new CLIPipe({ command: 'claude', args: ['-p', '--model', 'sonnet'], toolProtocol: 'claude' })
 ```
 
 All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model?, costUsd? }`. The optional `model` (v0.16.1+) is the id the response was produced by — Loop prefers it over `provider.model` for cost accounting. By default CLIPipe returns `toolCalls: []` and zero usage (CLI tools don't report tokens) and omits `model`. **Structured output (v0.26.0+):** set `parse: 'claude-json'` (a preset for `claude -p --output-format json`) — or a `(stdout) => Partial<GenerateResult>` function for any other CLI — and CLIPipe maps the CLI's JSON envelope onto real `usage`, `model`, and `costUsd`, throwing `ProviderError` on a malformed/error envelope (never a silent raw-text fall-back). `costUsd` (optional `GenerateResult` field) is an **authoritative** per-call price the provider reports itself; when finite the Loop prefers it over the internal rate-table `estimateCost`, so a CLI-piped run enforces a bareguard USD cap with no local pricing table (a `0` counts as priced, distinct from null/unpriced). `toolCalls` stays `[]` regardless (CLIPipe is tool-free).

package/package.json

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

package/src/evaluator.d.ts

@@ -53,6 +53,9 @@ export type EvaluatorOptions = {
 export type Criteria = {
     /**
      * - Deterministic check, no tokens.
+     * MUST return a boolean. A non-boolean return THROWS a `ValidationError` (it is not coerced): a truthy
+     * object/string/number — e.g. a test-runner result returned by mistake — would otherwise launder a
+     * FAILING check into a PASS. Thrown, it routes to `broken-verifier` at recurse's verify slot.
      */
     predicate?: ((result: any) => boolean | Promise<boolean>) | undefined;
     /**

package/src/evaluator.js

@@ -35,6 +35,9 @@ const { Loop } = require('./loop');
 /**
  * @typedef {object} Criteria
  * @property {(result: any) => boolean | Promise<boolean>} [predicate] - Deterministic check, no tokens.
+ *   MUST return a boolean. A non-boolean return THROWS a `ValidationError` (it is not coerced): a truthy
+ *   object/string/number — e.g. a test-runner result returned by mistake — would otherwise launder a
+ *   FAILING check into a PASS. Thrown, it routes to `broken-verifier` at recurse's verify slot.
  * @property {string} [rubric] - Natural-language grading criteria an LLM scores. Exactly one of predicate|rubric|agentic.
  * @property {string} [agentic] - Instructions for a tool-running critic (D9): how to EXERCISE the live artifact
  *   (open it, click, read console/network) and what would make it fail. Runs an ISOLATED Loop with the scoped
@@ -127,7 +130,30 @@ class Evaluator {
     }
 
     if (predicate) {
-      const pass = !!(await predicate(result));
+      // BA-15 family (predicate seam): the contract is `=> boolean`. The OLD `!!(await predicate(...))`
+      // coerced ANY truthy return to a PASS — so a predicate that returned a test-runner RESULT instead
+      // of a boolean (`{exitCode:1,failures:3}`, `'3 failing'`, a count) laundered a FAILING check into
+      // `{status:'satisfied'}` (the optimistic-rounding class of BA-4/5/6/7/13; proven by
+      // `poc/rlmplans-predicate-coercion.mjs`). There is no safe non-boolean subset — an object is always
+      // truthy, a non-empty string is truthy regardless of meaning, a failure-count is truthy — so the
+      // ONLY correct return is a genuine boolean. A non-boolean is a broken arbiter: NAME it loudly rather
+      // than coerce it (BA-15's principle). Thrown here, it routes to `broken-verifier` at recurse's verify
+      // slot (`runArbiter` catches any non-Halt throw) and surfaces as a clean ValidationError standalone.
+      const raw = await predicate(result);
+      if (typeof raw !== 'boolean') {
+        // Name the TYPE only, never the value — an error string can reach a wired gate's audit log (F16/BA-1).
+        const got = raw === null ? 'null'
+          : raw === undefined ? 'undefined'
+          : Array.isArray(raw) ? 'an array'
+          : typeof raw === 'object' ? 'an object'
+          : `a ${typeof raw}`;
+        throw new ValidationError(
+          `[Evaluator] predicate must return a boolean, got ${got}. A truthy non-boolean ` +
+          '(a test-runner result object, a summary string, a failure count) would otherwise coerce to a ' +
+          'PASS — return true/false explicitly.',
+        );
+      }
+      const pass = raw;
       return {
         status: pass ? 'satisfied' : 'needs_revision',
         pass,

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

@@ -0,0 +1,121 @@
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type ParsedEnvelope = {
+    action: "tool_call" | "final_answer";
+    toolName?: string | undefined;
+    toolArguments?: Record<string, any> | undefined;
+    answer?: string | undefined;
+    usage: import("../types").Usage;
+    model?: string | null | undefined;
+    costUsd?: number | undefined;
+};
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/**
+ * The JSON envelope the CLI is constrained to (claude `--json-schema`). `tool_call` carries the
+ * name + args; `final_answer` carries prose. A closed `action` enum is the discriminator.
+ * @type {string}
+ */
+export const ENVELOPE_SCHEMA: string;
+/**
+ * One tool's signature line for the manifest. Protocol-agnostic.
+ * @param {ToolDef} t
+ * @returns {string}
+ */
+export function toolLine(t: ToolDef): string;
+/**
+ * Build the tool-mode system prompt: the caller's own system stance (if any) + the tool manifest +
+ * the envelope contract. The contract text is load-bearing — the step-2 probe showed a weak model
+ * that BELIEVES it must execute the tool itself answers in prose ("I attempted… I failed"), so the
+ * prompt states plainly that EMITTING the envelope IS the call and "attempting/failing" is not a
+ * thing it can do. Protocol-agnostic (the envelope vocabulary is shared across CLIs).
+ * @param {string|null} baseSystem - the caller's system message content, or null.
+ * @param {ToolDef[]} tools
+ * @returns {string}
+ */
+export function buildToolSystemPrompt(baseSystem: string | null, tools: ToolDef[]): string;
+/**
+ * Render the Loop's OpenAI-shaped transcript into a plain-text conversation a CLI can read. The
+ * load-bearing part: assistant `tool_calls` and `role:'tool'` results must SURVIVE (the default
+ * `_formatPrompt` drops them), and each result must trace to the call that produced it (id → name).
+ * Protocol-agnostic. The system message is excluded here — it rides the CLI's system-prompt flag.
+ * @param {Message[]} messages
+ * @returns {string}
+ */
+export function renderTranscript(messages: Message[]): string;
+/**
+ * Map the claude `--output-format json` OUTER envelope's usage / model / cost onto neutral shapes.
+ * Shared by tool-mode {@link CLAUDE_TOOL_PROTOCOL.parseResult} and the plain-text `_parseClaudeJson`
+ * preset so the claude usage contract (token tiers, `modelUsage` first-key, `total_cost_usd`) lives
+ * in exactly ONE place — a future CLI format change touches this function, not two copies.
+ * @param {any} outer - the parsed outer CLI envelope (already validated non-null by the caller).
+ * @returns {{usage: import('../types').Usage, model: string|null, costUsd?: number}}
+ */
+export function mapClaudeMeta(outer: any): {
+    usage: import("../types").Usage;
+    model: string | null;
+    costUsd?: number;
+};
+export namespace CLAUDE_TOOL_PROTOCOL {
+    let name: string;
+    /**
+     * The extra CLI args for one tool-mode turn, appended after the caller's base args (`-p --model X`).
+     * `--tools ''` + `--strict-mcp-config` strip the CLI's own tools/MCP to a bare brain (step 1);
+     * `--setting-sources ''` suppresses cwd CLAUDE.md/memory/settings auto-discovery — a MEASURED
+     * ~18× cost drop (37,423 → 2,026 tokens/turn, step 2), load-bearing for a subscription strategy;
+     * `--system-prompt` REPLACES the CLI's prompt (vs --append); `--json-schema` + `--output-format
+     * json` force the parseable envelope.
+     * @param {string} systemPrompt
+     * @returns {string[]}
+     */
+    function turnArgs(systemPrompt: string): string[];
+    /**
+     * Parse claude's `--output-format json` stdout into a neutral {@link ParsedEnvelope}. A malformed
+     * or error envelope is a LOUD `ProviderError` — NEVER a silent fall-through to prose (the whole
+     * point is that a broken tool turn cannot masquerade as a final answer, the BA-6 failure shape).
+     * @param {string} stdout
+     * @returns {ParsedEnvelope}
+     */
+    function parseResult(stdout: string): ParsedEnvelope;
+    namespace probe {
+        let system: string;
+        let user: string;
+        function isCapable(parsed: ParsedEnvelope): boolean;
+    }
+}
+/** Resolve a `toolProtocol` option to an adapter. Claude-only for now; unknown names throw. */
+export function resolveToolProtocol(name: any): {
+    name: string;
+    /**
+     * The extra CLI args for one tool-mode turn, appended after the caller's base args (`-p --model X`).
+     * `--tools ''` + `--strict-mcp-config` strip the CLI's own tools/MCP to a bare brain (step 1);
+     * `--setting-sources ''` suppresses cwd CLAUDE.md/memory/settings auto-discovery — a MEASURED
+     * ~18× cost drop (37,423 → 2,026 tokens/turn, step 2), load-bearing for a subscription strategy;
+     * `--system-prompt` REPLACES the CLI's prompt (vs --append); `--json-schema` + `--output-format
+     * json` force the parseable envelope.
+     * @param {string} systemPrompt
+     * @returns {string[]}
+     */
+    turnArgs(systemPrompt: string): string[];
+    /**
+     * Parse claude's `--output-format json` stdout into a neutral {@link ParsedEnvelope}. A malformed
+     * or error envelope is a LOUD `ProviderError` — NEVER a silent fall-through to prose (the whole
+     * point is that a broken tool turn cannot masquerade as a final answer, the BA-6 failure shape).
+     * @param {string} stdout
+     * @returns {ParsedEnvelope}
+     */
+    parseResult(stdout: string): ParsedEnvelope;
+    /**
+     * Capability-probe assets. The probe mirrors REAL-TASK shape — a question whose answer the model
+     * cannot know, with a tool that yields it, and NO "call the tool" instruction — because a trivial
+     * "call capability_ping" instruction is a FALSE POSITIVE: haiku emits it 4/4 yet fails real tasks
+     * 0/5 (proven in `poc/clipipe-tools-04-capability-probe.mjs`). The question shape sorts cleanly:
+     * sonnet CAPABLE 4/4, haiku INCAPABLE 0/4, stable. Capable iff it emits a `tool_call` for the tool.
+     */
+    probe: {
+        system: string;
+        user: string;
+        /** @param {ParsedEnvelope} parsed @returns {boolean} */
+        isCapable: (parsed: ParsedEnvelope) => boolean;
+    };
+};

package/src/provider-clipipe-tools.js

@@ -0,0 +1,271 @@
+'use strict';
+
+const { ProviderError } = require('./errors');
+
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+
+// CLIPipe tool-mode support (v0.32.0). A subscription CLI (`claude -p`, …) is a plain
+// TURN-provider: it takes text and returns text, with no native channel for a caller's tools. This
+// module adds Option C — SCHEMA-VALIDATED TOOL EMULATION: the caller's tools are described in the
+// system prompt, the CLI is constrained to a JSON envelope, and the envelope is parsed back into
+// normalized `toolCalls` so bareagent's own `Loop` keeps ownership of the agentic cycle (round
+// accounting, spin guards, stop-reason classification all still apply — unlike an MCP-callback
+// design where the CLI would own the turns). Proven end-to-end through a real Loop in
+// `poc/clipipe-tools-03-through-loop.mjs` (sonnet, multi-round).
+//
+// Two layers, deliberately split so a SECOND CLI (codex/gemini) slots in behind the same seam
+// without touching the generic provider (the "keep the claude-specific parts isolated" constraint):
+//   - PROTOCOL-AGNOSTIC (renderTranscript / buildToolSystemPrompt): produce the text a CLI is fed.
+//   - PROTOCOL-SPECIFIC (CLAUDE_TOOL_PROTOCOL): the claude-CLI flags, the envelope schema, the
+//     result parse, and the capability-probe assets. Claude-only for now, by design.
+
+/**
+ * The JSON envelope the CLI is constrained to (claude `--json-schema`). `tool_call` carries the
+ * name + args; `final_answer` carries prose. A closed `action` enum is the discriminator.
+ * @type {string}
+ */
+const ENVELOPE_SCHEMA = JSON.stringify({
+  type: 'object',
+  properties: {
+    action: { type: 'string', enum: ['tool_call', 'final_answer'] },
+    tool_name: { type: 'string' },
+    tool_arguments: { type: 'object' },
+    answer: { type: 'string' },
+  },
+  required: ['action'],
+});
+
+/**
+ * One tool's signature line for the manifest. Protocol-agnostic.
+ * @param {ToolDef} t
+ * @returns {string}
+ */
+function toolLine(t) {
+  const props = (t.parameters && t.parameters.properties) || {};
+  const args = Object.keys(props).map((k) => `${k}: ${props[k].type || 'any'}`).join(', ');
+  return `- ${t.name}(${args})${t.description ? ` — ${t.description}` : ''}`;
+}
+
+/**
+ * Build the tool-mode system prompt: the caller's own system stance (if any) + the tool manifest +
+ * the envelope contract. The contract text is load-bearing — the step-2 probe showed a weak model
+ * that BELIEVES it must execute the tool itself answers in prose ("I attempted… I failed"), so the
+ * prompt states plainly that EMITTING the envelope IS the call and "attempting/failing" is not a
+ * thing it can do. Protocol-agnostic (the envelope vocabulary is shared across CLIs).
+ * @param {string|null} baseSystem - the caller's system message content, or null.
+ * @param {ToolDef[]} tools
+ * @returns {string}
+ */
+function buildToolSystemPrompt(baseSystem, tools) {
+  const manifest = tools.length
+    ? ['You can use these tools:', ...tools.map(toolLine)].join('\n')
+    : 'You have no tools.';
+  return [
+    baseSystem ? String(baseSystem) : 'You are the reasoning half of a tool-using system.',
+    '',
+    manifest,
+    '',
+    'An external runtime executes tools for you. Emitting a tool_call envelope IS how a tool runs —',
+    'you never execute one yourself, and "attempting" or "failing" to call a tool is not something',
+    'you can do. To use a tool: action="tool_call" with tool_name and tool_arguments. When the tool',
+    'results you need are already present in the conversation, reply action="final_answer" with the',
+    'answer. Reply ONLY with the JSON envelope.',
+  ].join('\n');
+}
+
+/**
+ * Render the Loop's OpenAI-shaped transcript into a plain-text conversation a CLI can read. The
+ * load-bearing part: assistant `tool_calls` and `role:'tool'` results must SURVIVE (the default
+ * `_formatPrompt` drops them), and each result must trace to the call that produced it (id → name).
+ * Protocol-agnostic. The system message is excluded here — it rides the CLI's system-prompt flag.
+ * @param {Message[]} messages
+ * @returns {string}
+ */
+function renderTranscript(messages) {
+  /** @type {Map<string,string>} */
+  const idToName = new Map();
+  for (const m of messages) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls)) {
+      for (const tc of m.tool_calls) {
+        if (!tc.id) continue;
+        const nm = (tc.function && tc.function.name) || tc.name || '?';
+        idToName.set(String(tc.id), String(nm));
+      }
+    }
+  }
+  const lines = [];
+  for (const m of messages) {
+    if (m.role === 'system') continue;
+    if (m.role === 'user') { lines.push(`User: ${m.content}`); continue; }
+    if (m.role === 'assistant') {
+      let s = m.content ? `Assistant: ${m.content}` : 'Assistant:';
+      if (Array.isArray(m.tool_calls)) {
+        for (const tc of m.tool_calls) {
+          const fn = tc.function || {};
+          const args = typeof fn.arguments === 'string' ? fn.arguments : JSON.stringify(fn.arguments || {});
+          s += `\n  (you called ${fn.name || tc.name}(${args}))`;
+        }
+      }
+      lines.push(s);
+      continue;
+    }
+    if (m.role === 'tool') {
+      const name = idToName.get(m.tool_call_id || '') || '?';
+      lines.push(`Tool result from ${name}: ${m.content}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Map the claude `--output-format json` OUTER envelope's usage / model / cost onto neutral shapes.
+ * Shared by tool-mode {@link CLAUDE_TOOL_PROTOCOL.parseResult} and the plain-text `_parseClaudeJson`
+ * preset so the claude usage contract (token tiers, `modelUsage` first-key, `total_cost_usd`) lives
+ * in exactly ONE place — a future CLI format change touches this function, not two copies.
+ * @param {any} outer - the parsed outer CLI envelope (already validated non-null by the caller).
+ * @returns {{usage: import('../types').Usage, model: string|null, costUsd?: number}}
+ */
+function mapClaudeMeta(outer) {
+  const u = (outer.usage && typeof outer.usage === 'object') ? outer.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 = (outer.modelUsage && typeof outer.modelUsage === 'object')
+    ? (Object.keys(outer.modelUsage)[0] ?? null)
+    : null;
+  /** @type {{usage: import('../types').Usage, model: string|null, costUsd?: number}} */
+  const meta = { usage, model };
+  // The CLI's own price is authoritative (a subscription run reports 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(outer.total_cost_usd)) meta.costUsd = outer.total_cost_usd;
+  return meta;
+}
+
+/**
+ * @typedef {object} ParsedEnvelope
+ * @property {'tool_call'|'final_answer'} action
+ * @property {string} [toolName]
+ * @property {Record<string, any>} [toolArguments]
+ * @property {string} [answer]
+ * @property {import('../types').Usage} usage
+ * @property {string|null} [model]
+ * @property {number} [costUsd]
+ */
+
+/**
+ * The claude-CLI tool protocol. Everything CLI-shaped lives here; a second CLI is a sibling object
+ * implementing the same three members. Isolated so the generic provider never grows a claude branch.
+ */
+const CLAUDE_TOOL_PROTOCOL = {
+  name: 'claude',
+
+  /**
+   * The extra CLI args for one tool-mode turn, appended after the caller's base args (`-p --model X`).
+   * `--tools ''` + `--strict-mcp-config` strip the CLI's own tools/MCP to a bare brain (step 1);
+   * `--setting-sources ''` suppresses cwd CLAUDE.md/memory/settings auto-discovery — a MEASURED
+   * ~18× cost drop (37,423 → 2,026 tokens/turn, step 2), load-bearing for a subscription strategy;
+   * `--system-prompt` REPLACES the CLI's prompt (vs --append); `--json-schema` + `--output-format
+   * json` force the parseable envelope.
+   * @param {string} systemPrompt
+   * @returns {string[]}
+   */
+  turnArgs(systemPrompt) {
+    return [
+      '--tools', '', '--strict-mcp-config', '--setting-sources', '',
+      '--system-prompt', systemPrompt,
+      '--json-schema', ENVELOPE_SCHEMA,
+      '--output-format', 'json',
+    ];
+  },
+
+  /**
+   * Parse claude's `--output-format json` stdout into a neutral {@link ParsedEnvelope}. A malformed
+   * or error envelope is a LOUD `ProviderError` — NEVER a silent fall-through to prose (the whole
+   * point is that a broken tool turn cannot masquerade as a final answer, the BA-6 failure shape).
+   * @param {string} stdout
+   * @returns {ParsedEnvelope}
+   */
+  parseResult(stdout) {
+    let outer;
+    try {
+      outer = JSON.parse(stdout);
+    } catch (_) {
+      const preview = stdout.length > 200 ? `${stdout.slice(0, 200)}…` : stdout;
+      throw new ProviderError(`[CLIPipeProvider] tool-mode expected JSON on stdout, got: ${preview}`, /** @type {any} */ ({ status: 0 }));
+    }
+    if (!outer || typeof outer !== 'object' || outer.is_error === true || outer.subtype !== 'success') {
+      const detail = outer && typeof outer.result === 'string' ? outer.result : JSON.stringify(outer && outer.subtype);
+      throw new ProviderError(`[CLIPipeProvider] claude CLI reported failure (subtype='${outer && outer.subtype}'): ${detail}`, /** @type {any} */ ({ status: 0 }));
+    }
+    let env;
+    try {
+      env = JSON.parse(outer.result);
+    } catch (_) {
+      throw new ProviderError(`[CLIPipeProvider] tool-mode envelope was not valid JSON: ${String(outer.result).slice(0, 200)}`, /** @type {any} */ ({ status: 0 }));
+    }
+    if (!env || (env.action !== 'tool_call' && env.action !== 'final_answer')) {
+      throw new ProviderError(`[CLIPipeProvider] tool-mode envelope missing a valid action (got ${env && JSON.stringify(env.action)})`, /** @type {any} */ ({ status: 0 }));
+    }
+    if (env.action === 'tool_call' && (typeof env.tool_name !== 'string' || !env.tool_name)) {
+      throw new ProviderError('[CLIPipeProvider] tool-mode tool_call envelope has no tool_name', /** @type {any} */ ({ status: 0 }));
+    }
+
+    const { usage, model, costUsd } = mapClaudeMeta(outer);
+    /** @type {ParsedEnvelope} */
+    const parsed = { action: env.action, usage, model };
+    if (costUsd !== undefined) parsed.costUsd = costUsd;
+    if (env.action === 'tool_call') {
+      parsed.toolName = env.tool_name;
+      parsed.toolArguments = (env.tool_arguments && typeof env.tool_arguments === 'object') ? env.tool_arguments : {};
+    } else {
+      parsed.answer = typeof env.answer === 'string' ? env.answer : '';
+    }
+    return parsed;
+  },
+
+  /**
+   * Capability-probe assets. The probe mirrors REAL-TASK shape — a question whose answer the model
+   * cannot know, with a tool that yields it, and NO "call the tool" instruction — because a trivial
+   * "call capability_ping" instruction is a FALSE POSITIVE: haiku emits it 4/4 yet fails real tasks
+   * 0/5 (proven in `poc/clipipe-tools-04-capability-probe.mjs`). The question shape sorts cleanly:
+   * sonnet CAPABLE 4/4, haiku INCAPABLE 0/4, stable. Capable iff it emits a `tool_call` for the tool.
+   */
+  probe: {
+    system: [
+      'You are the reasoning half of a tool-using system. An external runtime executes tools for you.',
+      '',
+      'Tool available:',
+      '- lookup_code(name: string) — returns the secret verification code for a given name.',
+      '',
+      'You have NO knowledge of verification codes; the ONLY way to obtain one is to emit a tool_call.',
+      'Emitting a tool_call envelope IS how a tool runs; you never execute one yourself, and you cannot',
+      '"attempt" or "fail" to call one. Reply ONLY with the JSON envelope.',
+    ].join('\n'),
+    user: 'What is the verification code for "orchard-42"?',
+    /** @param {ParsedEnvelope} parsed @returns {boolean} */
+    isCapable: (parsed) => parsed.action === 'tool_call' && parsed.toolName === 'lookup_code',
+  },
+};
+
+/** Resolve a `toolProtocol` option to an adapter. Claude-only for now; unknown names throw. */
+function resolveToolProtocol(name) {
+  if (name === 'claude') return CLAUDE_TOOL_PROTOCOL;
+  throw new Error(`[CLIPipeProvider] unknown toolProtocol '${name}' — only 'claude' is supported`);
+}
+
+module.exports = {
+  ENVELOPE_SCHEMA,
+  toolLine,
+  buildToolSystemPrompt,
+  renderTranscript,
+  mapClaudeMeta,
+  CLAUDE_TOOL_PROTOCOL,
+  resolveToolProtocol,
+};

package/src/provider-clipipe.d.ts

@@ -34,6 +34,14 @@ export type CLIPipeOptions = {
      * - 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;
+    /**
+     * - Opt into TOOL MODE (v0.32.0). A subscription CLI is a plain turn-provider with no native tool channel; this enables schema-validated tool EMULATION so a caller's `tools` work over the CLI (letting a Claude/etc. subscription drive an agentic Loop without metered-API spend). When set, ANY `generate(msgs, tools)` call with a non-empty `tools` array auto-uses emulation (the caller's own system stance + a tool manifest + a JSON envelope, parsed back into normalized `toolCalls`); an empty `tools` array is unchanged plain-text. When NOT set, `tools` are IGNORED (plain-text mode, the long-standing behavior — a non-tool-calling CLI can legitimately sit in a Loop that has tools mounted) with a one-time `console.warn` for visibility. Claude-only for now (`'claude'`); the claude-specific flags/schema/parse live in `provider-clipipe-tools.js` so a second CLI slots in behind the same seam. NOTE: tool mode requires a capable model — weak models (e.g. haiku) answer in prose instead of calling tools; see `probeCapability`.
+     */
+    toolProtocol?: "claude" | undefined;
+    /**
+     * - (tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
+     */
+    probeCapability?: boolean | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -48,6 +56,8 @@ export type CLIPipeOptions = {
  * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
  * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
  * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
+ * @property {'claude'} [toolProtocol] - Opt into TOOL MODE (v0.32.0). A subscription CLI is a plain turn-provider with no native tool channel; this enables schema-validated tool EMULATION so a caller's `tools` work over the CLI (letting a Claude/etc. subscription drive an agentic Loop without metered-API spend). When set, ANY `generate(msgs, tools)` call with a non-empty `tools` array auto-uses emulation (the caller's own system stance + a tool manifest + a JSON envelope, parsed back into normalized `toolCalls`); an empty `tools` array is unchanged plain-text. When NOT set, `tools` are IGNORED (plain-text mode, the long-standing behavior — a non-tool-calling CLI can legitimately sit in a Loop that has tools mounted) with a one-time `console.warn` for visibility. Claude-only for now (`'claude'`); the claude-specific flags/schema/parse live in `provider-clipipe-tools.js` so a second CLI slots in behind the same seam. NOTE: tool mode requires a capable model — weak models (e.g. haiku) answer in prose instead of calling tools; see `probeCapability`.
+ * @property {boolean} [probeCapability=true] - (tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
  */
 export class CLIPipeProvider {
     /**
@@ -64,10 +74,27 @@ export class CLIPipeProvider {
     systemPromptFlag: string | null;
     onChunk: ((chunk: string) => void) | null;
     parse: "claude-json" | ((stdout: string) => Partial<GenerateResult>) | null;
+    toolProtocol: {
+        name: string;
+        turnArgs(systemPrompt: string): string[];
+        parseResult(stdout: string): ParsedEnvelope;
+        probe: {
+            system: string;
+            user: string;
+            isCapable: (parsed: ParsedEnvelope) => boolean;
+        };
+    } | null;
+    probeCapability: boolean;
+    /** @type {Promise<void>|null} */
+    _toolCapability: Promise<void> | null;
     /**
-     * Generate a response by piping messages to the CLI command.
+     * Generate a response by piping messages to the CLI command. With a `toolProtocol` configured and
+     * a non-empty `tools` array, routes to schema-validated tool EMULATION (v0.32.0); otherwise the
+     * plain-text path below (unchanged). Passing `tools` with no `toolProtocol` warns ONCE and ignores
+     * them (a non-tool-calling CLI legitimately coexists in a Loop with tools mounted); the loud
+     * failure for a genuinely tool-incapable model lives in the tool-mode capability probe.
      * @param {Message[]} messages - Conversation messages in OpenAI format.
-     * @param {ToolDef[]} [tools=[]] - Unused (CLI commands don't support tools).
+     * @param {ToolDef[]} [tools=[]] - Caller tools. Honored only in tool mode (`toolProtocol` set).
      * @param {Record<string, any>} [options={}] - Unused.
      * @returns {Promise<GenerateResult>}
      * @throws {Error} `[CLIPipeProvider] failed to spawn "cmd": ...` — when the command cannot be found or executed.
@@ -76,6 +103,30 @@ 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>;
+    _warnedNoProtocol: boolean | undefined;
+    /**
+     * Tool mode (v0.32.0) — one turn of schema-validated tool emulation. Renders the Loop's
+     * OpenAI-shaped transcript to text, injects the caller's system stance + a tool manifest + the
+     * envelope contract, spawns the CLI under the protocol's flags, and parses the envelope back into
+     * normalized `toolCalls` (a `tool_call`) or `text` (a `final_answer`). The Loop drives the cycle.
+     * @param {Message[]} messages
+     * @param {ToolDef[]} tools
+     * @returns {Promise<GenerateResult>}
+     */
+    _generateWithTools(messages: Message[], tools: ToolDef[]): Promise<GenerateResult>;
+    _toolCallSeq: any;
+    /**
+     * Run the upfront capability probe ONCE per instance (cached), unless `probeCapability` is off.
+     * A model that answers the probe in prose instead of emitting a tool_call throws a loud
+     * `ProviderError` — fail fast, never silently degrade to a no-tools run mid-conversation.
+     * NOTE: the probe is a single internal CLI turn whose token usage/cost is NOT surfaced to the Loop
+     * (it never flows to `onLlmResult`), so a wired budget gate does not see it — negligible for the
+     * subscription use case this exists for (flat cost, one probe per instance), by design.
+     * @returns {Promise<void>}
+     */
+    _ensureToolCapability(): Promise<void>;
+    /** Best-effort model id from `--model X` in the base args, for a clearer probe-failure message. */
+    _modelFromArgs(): string | null;
     /**
      * 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

package/src/provider-clipipe.js

@@ -2,6 +2,7 @@
 
 const { spawn } = require('child_process');
 const { ProviderError } = require('./errors');
+const { buildToolSystemPrompt, renderTranscript, resolveToolProtocol, mapClaudeMeta } = require('./provider-clipipe-tools');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -17,6 +18,8 @@ const { ProviderError } = require('./errors');
  * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
  * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
  * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
+ * @property {'claude'} [toolProtocol] - Opt into TOOL MODE (v0.32.0). A subscription CLI is a plain turn-provider with no native tool channel; this enables schema-validated tool EMULATION so a caller's `tools` work over the CLI (letting a Claude/etc. subscription drive an agentic Loop without metered-API spend). When set, ANY `generate(msgs, tools)` call with a non-empty `tools` array auto-uses emulation (the caller's own system stance + a tool manifest + a JSON envelope, parsed back into normalized `toolCalls`); an empty `tools` array is unchanged plain-text. When NOT set, `tools` are IGNORED (plain-text mode, the long-standing behavior — a non-tool-calling CLI can legitimately sit in a Loop that has tools mounted) with a one-time `console.warn` for visibility. Claude-only for now (`'claude'`); the claude-specific flags/schema/parse live in `provider-clipipe-tools.js` so a second CLI slots in behind the same seam. NOTE: tool mode requires a capable model — weak models (e.g. haiku) answer in prose instead of calling tools; see `probeCapability`.
+ * @property {boolean} [probeCapability=true] - (tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
  */
 
 class CLIPipeProvider {
@@ -38,12 +41,23 @@ class CLIPipeProvider {
       throw new Error("[CLIPipeProvider] options.parse must be 'claude-json' or a function");
     }
     this.parse = options.parse || null;
+    // Tool mode (v0.32.0). Resolve the protocol adapter eagerly so an unknown name fails at
+    // construction, not mid-run. `_toolCapability` caches the upfront probe verdict per instance
+    // (null = not yet probed; a Promise while in flight; true once confirmed capable).
+    this.toolProtocol = options.toolProtocol ? resolveToolProtocol(options.toolProtocol) : null;
+    this.probeCapability = options.probeCapability !== false;
+    /** @type {Promise<void>|null} */
+    this._toolCapability = null;
   }
 
   /**
-   * Generate a response by piping messages to the CLI command.
+   * Generate a response by piping messages to the CLI command. With a `toolProtocol` configured and
+   * a non-empty `tools` array, routes to schema-validated tool EMULATION (v0.32.0); otherwise the
+   * plain-text path below (unchanged). Passing `tools` with no `toolProtocol` warns ONCE and ignores
+   * them (a non-tool-calling CLI legitimately coexists in a Loop with tools mounted); the loud
+   * failure for a genuinely tool-incapable model lives in the tool-mode capability probe.
    * @param {Message[]} messages - Conversation messages in OpenAI format.
-   * @param {ToolDef[]} [tools=[]] - Unused (CLI commands don't support tools).
+   * @param {ToolDef[]} [tools=[]] - Caller tools. Honored only in tool mode (`toolProtocol` set).
    * @param {Record<string, any>} [options={}] - Unused.
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[CLIPipeProvider] failed to spawn "cmd": ...` — when the command cannot be found or executed.
@@ -52,6 +66,24 @@ class CLIPipeProvider {
    * @throws {Error} `[CLIPipeProvider] process produced no output` — when stdout is empty.
    */
   async generate(messages, tools = [], options = {}) {
+    if (Array.isArray(tools) && tools.length > 0) {
+      if (this.toolProtocol) return this._generateWithTools(messages, tools);
+      // No protocol configured → plain-text mode, tools IGNORED — the long-standing behavior, kept
+      // for backward compatibility (a non-tool-calling CLI legitimately coexists in a Loop that has
+      // tools mounted, e.g. via MCP; the Loop's contract lets a provider simply not call them).
+      // A silent ignore is the trap the caller might not notice, so warn ONCE per instance (the
+      // provider-temperature BA-10 pattern) — visible, not fatal. Genuine loud-failure for tool
+      // mode lives in the capability probe, where a weak model that SHOULD call tools cannot.
+      if (!this._warnedNoProtocol) {
+        this._warnedNoProtocol = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[CLIPipeProvider] received tools but no toolProtocol is configured — tools are IGNORED ' +
+          "(plain-text mode). Construct with { toolProtocol: 'claude' } to enable tool emulation.",
+        );
+      }
+    }
+
     /** @type {string[]} */
     let extraArgs = [];
     let promptMessages = messages;
@@ -85,6 +117,82 @@ class CLIPipeProvider {
     };
   }
 
+  /**
+   * Tool mode (v0.32.0) — one turn of schema-validated tool emulation. Renders the Loop's
+   * OpenAI-shaped transcript to text, injects the caller's system stance + a tool manifest + the
+   * envelope contract, spawns the CLI under the protocol's flags, and parses the envelope back into
+   * normalized `toolCalls` (a `tool_call`) or `text` (a `final_answer`). The Loop drives the cycle.
+   * @param {Message[]} messages
+   * @param {ToolDef[]} tools
+   * @returns {Promise<GenerateResult>}
+   */
+  async _generateWithTools(messages, tools) {
+    await this._ensureToolCapability();
+    const proto = this.toolProtocol;
+    if (!proto) throw new ProviderError('[CLIPipeProvider] tool mode not configured', /** @type {any} */ ({ status: 0 })); // unreachable: only called from the tools branch
+    const sysMsg = messages.find((m) => m.role === 'system');
+    const systemPrompt = buildToolSystemPrompt(sysMsg && typeof sysMsg.content === 'string' ? sysMsg.content : null, tools);
+    const stdout = await this._spawn(renderTranscript(messages), proto.turnArgs(systemPrompt));
+    const parsed = proto.parseResult(stdout);
+
+    /** @type {GenerateResult} */
+    const result = { text: '', toolCalls: [], usage: parsed.usage, model: parsed.model ?? null };
+    if (Number.isFinite(parsed.costUsd)) result.costUsd = parsed.costUsd;
+    if (parsed.action === 'tool_call') {
+      this._toolCallSeq = (this._toolCallSeq || 0) + 1;
+      result.toolCalls = [{ id: `cli_${this._toolCallSeq}`, name: parsed.toolName || '', arguments: parsed.toolArguments || {} }];
+    } else {
+      result.text = parsed.answer || '';
+    }
+    return result;
+  }
+
+  /**
+   * Run the upfront capability probe ONCE per instance (cached), unless `probeCapability` is off.
+   * A model that answers the probe in prose instead of emitting a tool_call throws a loud
+   * `ProviderError` — fail fast, never silently degrade to a no-tools run mid-conversation.
+   * NOTE: the probe is a single internal CLI turn whose token usage/cost is NOT surfaced to the Loop
+   * (it never flows to `onLlmResult`), so a wired budget gate does not see it — negligible for the
+   * subscription use case this exists for (flat cost, one probe per instance), by design.
+   * @returns {Promise<void>}
+   */
+  _ensureToolCapability() {
+    if (!this.probeCapability) return Promise.resolve();
+    // Cache the in-flight promise so concurrent first-calls share one probe, and a resolved
+    // capable verdict is never re-probed.
+    if (this._toolCapability) return this._toolCapability;
+    const proto = this.toolProtocol;
+    if (!proto) return Promise.resolve(); // unreachable: only called from the tools branch
+    this._toolCapability = (async () => {
+      const stdout = await this._spawn(proto.probe.user, proto.turnArgs(proto.probe.system));
+      let parsed;
+      try {
+        parsed = proto.parseResult(stdout);
+      } catch (err) {
+        // A malformed probe response is itself an incapability signal — name it as such.
+        this._toolCapability = null; // allow a retry on a transient parse failure
+        throw new ProviderError(`[CLIPipeProvider] tool-mode capability probe failed to parse: ${/** @type {Error} */ (err).message}`, /** @type {any} */ ({ status: 0 }));
+      }
+      if (!proto.probe.isCapable(parsed)) {
+        const model = this._modelFromArgs();
+        throw new ProviderError(
+          `[CLIPipeProvider] the CLI model${model ? ` '${model}'` : ''} is not capable of tool use: the ` +
+          'capability probe answered in prose instead of emitting a tool_call. Weak models (e.g. haiku) ' +
+          'cannot drive tool emulation reliably — use a stronger model for tool mode, or run without ' +
+          'tools for plain-text. (Set { probeCapability: false } to skip this check.)',
+          /** @type {any} */ ({ status: 0 }),
+        );
+      }
+    })();
+    return this._toolCapability;
+  }
+
+  /** Best-effort model id from `--model X` in the base args, for a clearer probe-failure message. */
+  _modelFromArgs() {
+    const i = this.args.indexOf('--model');
+    return i >= 0 && i + 1 < this.args.length ? this.args[i + 1] : null;
+  }
+
   /**
    * 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
@@ -109,21 +217,7 @@ class CLIPipeProvider {
       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;
-
+    const { usage, model, costUsd } = mapClaudeMeta(obj);
     /** @type {GenerateResult} */
     const result = {
       text: typeof obj.result === 'string' ? obj.result : '',
@@ -131,9 +225,7 @@ class CLIPipeProvider {
       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;
+    if (costUsd !== undefined) result.costUsd = costUsd;
     return result;
   }
 

package/src/recurse.d.ts

@@ -113,7 +113,7 @@ export type RecurseOptions = {
      * (+ `receipts.blockerDetail`), with `best` preserving the model's last attempt. A `HaltError` thrown by the
      * sensor stays a clean governance halt. The sensor's EXECUTION environment is the caller's: run untrusted /
      * model-generated checks in an isolated child process WITH A TIMEOUT — a sensor that hangs forever hangs the
-     * leaf (no bareguard checkpoint fires between sensor start and return).
+     * leaf (no bareguard checkpoint fires between sensor start and return; confirmed by `poc/rlmplans-hung-sensor.mjs`).
      * **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
      * surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
      * STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation
@@ -456,7 +456,7 @@ export type Slice = {
  *   (+ `receipts.blockerDetail`), with `best` preserving the model's last attempt. A `HaltError` thrown by the
  *   sensor stays a clean governance halt. The sensor's EXECUTION environment is the caller's: run untrusted /
  *   model-generated checks in an isolated child process WITH A TIMEOUT — a sensor that hangs forever hangs the
- *   leaf (no bareguard checkpoint fires between sensor start and return).
+ *   leaf (no bareguard checkpoint fires between sensor start and return; confirmed by `poc/rlmplans-hung-sensor.mjs`).
  *   **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
  *   surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
  *   STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation

package/src/recurse.js

@@ -244,7 +244,7 @@ function auditSafeCtx(ctx, overrides = {}) {
  *   (+ `receipts.blockerDetail`), with `best` preserving the model's last attempt. A `HaltError` thrown by the
  *   sensor stays a clean governance halt. The sensor's EXECUTION environment is the caller's: run untrusted /
  *   model-generated checks in an isolated child process WITH A TIMEOUT — a sensor that hangs forever hangs the
- *   leaf (no bareguard checkpoint fires between sensor start and return).
+ *   leaf (no bareguard checkpoint fires between sensor start and return; confirmed by `poc/rlmplans-hung-sensor.mjs`).
  *   **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
  *   surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
  *   STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation