bare-agent 0.30.0 → 0.32.0

package/README.md

@@ -94,7 +94,7 @@ Every piece works alone — take what you need, ignore the rest. Two axes: **Act
 
 ### Recurse — break a hard task into a tree *(the RLM primitive)*
 
-`recurse(task, ctx, opts)` does **decompose → fan-out → verify → synthesize** in one call — Recursive Language Models as a single import, composed *around* the Loop (never a new engine). The default is **model-driven**: the worker is handed a `spawn_child` tool and decides whether to split, bounded by depth + bareguard (no second guard layer). Forced fan-out (`count` / `mode:'fanout'`) and data-driven width (`mode:'partition'`, measured from a corpus) are opt-in. Give workers a stance with `opts.persona` (prepended to every worker, carries down the tree, deliberately kept out of the isolated verifier), and tell them *where they are* with `opts.context` (a read-only paths/cwd blob threaded to every worker so a sliced child can locate its artifact — facts, not a stance). For a leaf that should self-correct, pass `opts.refineLeaf` (opt-in): a definite leaf becomes a bounded generate→sense→regenerate loop driven by *your* deterministic sensor (test/compile/lint — one that judges the *returned* result, never a worker side-effect it could game), feeding the gap back (with escalating temperature on models that accept it; on a temperature-fixed model like `claude-sonnet-5` the gap critique carries recovery, and the receipt records the effective temps). On a temperature-fixed model, `refineLeaf.rejectedBuffer` adds a second lever — it feeds the model's own prior *failed attempts* back verbatim ("write something structurally different"), the directed-diversity complement to temperature's random diversity (adaptive by default; the two are antagonistic, so it holds temperature flat when it engages). The headline guarantee: **aggregation is code, never a model-stated number**, and a dead worker or exhausted guard returns an honest `{ incomplete, missingSlices }` — never a faked pass.
+`recurse(task, ctx, opts)` does **decompose → fan-out → verify → synthesize** in one call — Recursive Language Models as a single import, composed *around* the Loop (never a new engine). The default is **model-driven**: the worker is handed a `spawn_child` tool and decides whether to split, bounded by depth + bareguard (no second guard layer). Forced fan-out (`count` / `mode:'fanout'`) and data-driven width (`mode:'partition'`, measured from a corpus) are opt-in. Give workers a stance with `opts.persona` (prepended to every worker, carries down the tree, deliberately kept out of the isolated verifier), and tell them *where they are* with `opts.context` (a read-only paths/cwd blob threaded to every worker so a sliced child can locate its artifact — facts, not a stance). For a leaf that should self-correct, pass `opts.refineLeaf` (opt-in): a definite leaf becomes a bounded generate→sense→regenerate loop driven by *your* deterministic sensor (test/compile/lint — one that judges the *returned* result, never a worker side-effect it could game), feeding the gap back (with escalating temperature on models that accept it; on a temperature-fixed model like `claude-sonnet-5` the gap critique carries recovery, and the receipt records the effective temps). On a temperature-fixed model, `refineLeaf.rejectedBuffer` adds a second lever — it feeds the model's own prior *failed attempts* back verbatim ("write something structurally different"), the directed-diversity complement to temperature's random diversity (adaptive by default; the two are antagonistic, so it holds temperature flat when it engages). A *broken* arbiter — a sensor or a caller `evaluate` that throws or returns a malformed verdict — is named, never blamed on the model: the node stops at the first broken close and returns `{ incomplete, blocker: 'broken-sensor' | 'broken-verifier' }` with the model's last output preserved. The headline guarantee: **aggregation is code, never a model-stated number**, and a dead worker or exhausted guard returns an honest `{ incomplete, missingSlices }` — never a faked pass.
 
 Over a corpus, context reaches a worker as a **handle routed by question shape** (`opts.retrieval`):
 
@@ -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.30.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`) |
@@ -710,7 +711,9 @@ const out = await recurse('Audit auth.js, billing.js, gateway.js for authz bugs'
 
 **Leaf self-correction (`opts.refineLeaf`, v0.23.0, opt-in):** turn a **definite leaf** (a node offered no `spawn_child` — `simple` tier or at `maxDepth`) into a bounded generate→sense→regenerate loop instead of a single pass: `{ sensor, maxIterations?, temperatures?, rejectedBuffer? }`. `sensor(result, { task, context, contract }) → Verdict` is YOUR **deterministic** close (test/compile/lint — not a model judge); on a non-pass its `critique` (the gap, not the transcript) is fed FRESH into the next attempt and — **on models that accept `temperature`** — the **retry temperature ESCALATES** (default `[0.2, 0.7, 1.0]` — load-bearing there: a weak model at a flat temperature regenerates identical wrong code and ignores even crisp feedback). On a **temperature-fixed model** (e.g. `claude-sonnet-5`, which 400s any non-default temperature) the provider silently drops the param (see below), the escalation lever is inert, and the fed-back gap critique carries recovery alone; `receipts.refineLeaf.temperatures` then records the EFFECTIVE temps — a `null` marks an attempt that ran at the model's default (never the ignored requested value). Each attempt is gate-checked + metered; a HaltError mid-loop → clean `{ incomplete }`; honest non-recovery → `receipts.refineLeaf.passed === false` (never a faked pass); `receipts.tokens` sums all attempts. The error-keyed `recall` stays YOUR tool (`opts.tools`), keyed off the fed-back critique — bareagent stays litectx-agnostic. Carries down (engages at the leaves). Absent ⇒ a leaf is a single pass.
 
-> **Sensor integrity (`refineLeaf.sensor`):** the sensor must judge the **returned result** (tamper-proof — build/run the returned string in isolation), never a worker **side-effect** a worker with edit tools could game (writing a passing file then returning junk, or editing the failing test itself). The loop optimizes against whatever the sensor reads — keep the close outside what the worker can write. (RSI field lesson: reward-hacking appeared in every optimization loop with a gameable close.)
+> **Sensor integrity (`refineLeaf.sensor`):** the sensor must judge the **returned result** (tamper-proof — build/run the returned string in isolation), never a worker **side-effect** a worker with edit tools could game (writing a passing file then returning junk, or editing the failing test itself). The loop optimizes against whatever the sensor reads — keep the close outside what the worker can write. (RSI field lesson: reward-hacking appeared in every optimization loop with a gameable close. **Demonstrated in-repo** — `poc/sensor-gaming-blocked.mjs`: the moment the honest path was blocked, `claude-sonnet-5` faked a pass on an unsatisfiable on-disk check **5/5** — both by editing the test and by making the returned function non-pure — while a tamper-proof close that runs the returned artifact in isolation was not gameable.)
+
+> **Broken arbiter ≠ failing model (BA-15):** a `refineLeaf.sensor` — or a caller `opts.evaluate` verifier — that **throws** (your test runner crashed — ENOENT, a harness syntax error) or returns a **malformed verdict** (anything with neither a usable `pass` nor a valid tri-state `status`) is a faulty **arbiter**, not a model failure. The loop stops at the **first** broken close (it never retries against a broken judge — each retry would carry zero feedback) and returns a labeled `{ incomplete, blocker: 'broken-sensor' | 'broken-verifier', blockerDetail }` (what the arbiter did; mirrored on `receipts`), with `best` preserving the model's last non-empty output (BA-5) — best-effort work the arbiter never graded, not a pass. The label names WHICH knob to fix. Check `out.blocker` before debugging the model: `'broken-sensor'` / `'broken-verifier'` mean fix your sensor / your `evaluate` and re-run; `'governance-deny'` means widen scope / re-gate. **`pass` may be any truthy/falsy value** (`true`, `1`, `0`) — only a verdict carrying *no* usable signal is malformed — and a verdict backed by a class/getters keeps its fields. **In a nested run** the label travels: `out.blocker` reports a descendant's fault with `out.blockerTask` naming which sub-task broke, while each ancestor's receipts record it as `blockerFrom` — an ancestor's own `blocker` always means *that* node broke, so it never accuses a node whose sensor never ran. The **default Evaluator rubric verifier is never labeled** (its failures are provider-class faults), and a `HaltError` thrown by either arbiter stays a clean governance halt. One thing stays YOURS: an arbiter that **hangs** hangs the node (no gate checkpoint fires inside your callback) — run untrusted or model-generated checks in an isolated child process **with a timeout**.
 
 > **`rejectedBuffer` (BA-14, v0.30.0):** a second lever for a **temperature-fixed** model, where escalation is inert. Instead of only the latest critique, it surfaces 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); escalation is **random** diversity, and the two are **antagonistic** — temperature monotonically degrades the buffer (`poc/ba14b`: flat-0.2 100% → 0.7 70% → 1.0 50%), so when the buffer engages the retry temperature is **held flat** at `temperatures[0]`, never escalated. Trigger: `true` = force on (also on temperature-accepting models); `false` = force off (pure BA-8 escalation); **unset = adaptive** — engage only once a prior attempt's temperature was dropped (i.e. a temp-fixed model where escalation is inert and the buffer is the sole lever). On a temperature-accepting model the default leaves behavior byte-identical. `receipts.refineLeaf.rejectedBuffer` reports whether it engaged. Efficacy is a **weak-model / fixation** phenomenon (live on `claude-sonnet-5` it engaged 6/6 but recovered no better than critique-only — cost-neutral, hence adaptive-not-always-on).
 
@@ -798,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.30.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