bare-agent 0.31.0 → 0.33.0

package/src/provider-clipipe.js

@@ -1,7 +1,9 @@
 'use strict';
 
 const { spawn } = require('child_process');
-const { ProviderError } = require('./errors');
+const { ProviderError, HaltError } = require('./errors');
+const { buildToolSystemPrompt, renderTranscript, resolveToolProtocol, mapClaudeMeta } = require('./provider-clipipe-tools');
+const { createBridge, resolveSessionError, runSession } = require('./provider-clipipe-mcp');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -17,6 +19,51 @@ 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'|'claude-mcp'} [toolProtocol] - Opt into TOOL MODE. Two modes, and the choice is
+ *   about COST, not capability. `'claude-mcp'` (BA-16, NATIVE — prefer this on the claude CLI): one CLI
+ *   session per call, the caller's `tools` exposed to it as a real MCP server whose handlers call back
+ *   into your own in-process closures. The CLI owns the inner cycle and caches its transcript
+ *   session-side. `'claude'` (v0.32.0, EMULATION): one CLI spawn per round with the whole transcript
+ *   re-rendered and re-sent, parsed back through a JSON envelope. Emulation re-buys the full prefix
+ *   every turn, which the adopter measured at **$0.25–0.55/round** against **~$0.006/turn** native — so
+ *   it is the right instrument only for a CLI with NO MCP support, not a default. NOT claimed for
+ *   native: better output quality (n=2 suggestive evidence exists and is deliberately unminted).
+ *   Native mode sets {@link CLIPipeProvider#ownsCycle}, which makes the Loop REFUSE options it could
+ *   never honor (`assemble`/`trim`/`cacheMessages`, and a Loop-level `policy`) instead of leaving them
+ *   silently dead. See the native-only properties below.
+ * @property {(tool: string, args: any, ctx?: any) => any} [policy] - (native mode) The gate, same contract as `Loop({policy})`: only `true`
+ *   allows, a string is the deny reason fed back verbatim, a thrown `HaltError` is a clean governance
+ *   exit. REQUIRED here rather than on the Loop, because in native mode no tool call ever reaches the
+ *   Loop — a `Loop({policy})` would be a fence that is silently not there (the Loop throws instead).
+ *   Wiring the same `wireGate(gate).policy` keeps audit rows byte-shape-identical, with zero gate changes.
+ * @property {Function} [onTurn] - (native mode) Called with `{model, provider, usage, costUsd, pricing,
+ *   durationMs, ctx, kind}` for EACH completed CLI turn as it arrives (`kind:'turn'`, four cache tiers,
+ *   `costUsd:null` — the CLI prices the session, not the turn), then once at session end
+ *   (`kind:'session'`) carrying the authoritative total cost with zero usage. Streaming, never
+ *   sum-at-end: a session that dies mid-run must already have surfaced every completed turn's spend or
+ *   the gate loses all of it. The event shape mirrors `Loop({onLlmResult})`, so `wireGate(gate).onLlmResult`
+ *   drops straight in — and when it is wired the Loop skips its own forward, so nothing is billed twice.
+ * @property {number} [maxTurns] - (native mode) Maps to the CLI's `--max-turns`. The bound stop is NAMED
+ *   (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
+ * @property {number} [maxConsecutiveDenials=3] - (native mode) BA-11 at the bridge: a single deny stays
+ *   advisory so the model can pivot to an allowed tool; N in a row with no allowed call between ends the
+ *   session with `denied:<tool>`. `0`/`Infinity` disables.
+ * @property {number} [maxIdenticalToolErrors=3] - (native mode) BA-12 at the bridge: only a BYTE-IDENTICAL
+ *   repeat (name + JSON args) counts, so a model varying its args while recovering is never punished. N in
+ *   a row ends the session with `stuck:<tool>`. `0`/`Infinity` disables.
+ * @property {number} [sessionTimeout=600000] - (native mode) Wall-clock ceiling for one whole session. The
+ *   30s `timeout` default is for one-shot text and would kill an agentic session mid-run.
+ * @property {number} [bridgeTimeoutMs] - (native mode) Ceiling for ONE tool-handler round-trip across the
+ *   bridge. A hung handler becomes an error tool result rather than a hung session (default 120s).
+ *
+ *   Either mode: a non-empty `tools` array on `generate()` routes to tool mode; an empty one stays
+ *   plain text. With NO `toolProtocol`, `tools` are IGNORED (plain-text, the long-standing behavior —
+ *   a non-tool-calling CLI legitimately sits in a Loop with tools mounted) plus a one-time `console.warn`.
+ *   Emulation additionally requires a capable model (weak ones answer in prose; see `probeCapability`);
+ *   native mode needs no such probe, because the CLI's own tool channel does not depend on the model
+ *   agreeing to fill in a JSON questionnaire. The claude-specific parts of each live in
+ *   `provider-clipipe-tools.js` / `provider-clipipe-mcp.js`, so a second CLI slots in behind the same seams.
+ * @property {boolean} [probeCapability=true] - (EMULATION tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
  */
 
 class CLIPipeProvider {
@@ -38,12 +85,53 @@ 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).
+    // BA-16 native tool mode. `claude-mcp` is NOT an envelope protocol — the CLI runs its own
+    // multi-turn session and executes the caller's tools natively over MCP — so it is resolved on a
+    // separate axis rather than being forced through `resolveToolProtocol`'s emulation shape.
+    this.nativeTools = options.toolProtocol === 'claude-mcp';
+    /**
+     * Declares to the Loop that this provider runs its OWN turn cycle. The Loop reads it to refuse
+     * options it could never honor (assemble/trim/cacheMessages) and to require the fence be wired
+     * where it can actually run. Generic provider-contract flag; nothing here is claude-specific.
+     */
+    this.ownsCycle = this.nativeTools;
+    this.toolProtocol = (options.toolProtocol && !this.nativeTools) ? resolveToolProtocol(options.toolProtocol) : null;
+    this.probeCapability = options.probeCapability !== false;
+    /** @type {Promise<void>|null} */
+    this._toolCapability = null;
+
+    if (this.nativeTools) {
+      // The gate CANNOT ride on the Loop in native mode: no tool call ever reaches the Loop, so a
+      // `Loop({policy})` would be a fence that silently is not there. It must be wired HERE, at the
+      // bridge, which is the one seam every tool call crosses.
+      if (options.policy != null && typeof options.policy !== 'function') {
+        throw new Error('[CLIPipeProvider] options.policy must be a function (tool, args, ctx) => true|string');
+      }
+      this.policy = options.policy || null;
+      this.onTurn = options.onTurn || null;
+      if (this.onTurn != null && typeof this.onTurn !== 'function') {
+        throw new Error('[CLIPipeProvider] options.onTurn must be a function');
+      }
+      this.maxTurns = options.maxTurns ?? null;
+      this.maxConsecutiveDenials = options.maxConsecutiveDenials;
+      this.maxIdenticalToolErrors = options.maxIdenticalToolErrors;
+      // A session is a whole agentic run, not one prompt — the 30s one-shot default would kill it.
+      this.sessionTimeout = options.sessionTimeout ?? 600000;
+      this.bridgeTimeoutMs = options.bridgeTimeoutMs ?? 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 +140,25 @@ 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.nativeTools) return this._generateWithMcp(messages, tools, options);
+      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 +192,209 @@ 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;
+  }
+
+  /**
+   * BA-16 native tool mode — run ONE whole CLI session and report it honestly as one call.
+   *
+   * The CLI owns the inner cycle here: it calls the caller's tools natively over an MCP bridge and
+   * keeps going until it answers or hits a bound. So this returns `toolCalls: []` always (there is
+   * nothing left for the Loop to execute) plus a `session` block describing what really happened —
+   * the real turn count, the real tool-call count, and any terminal the Loop must surface as the
+   * run's `error`.
+   *
+   * Ordering of terminals is deliberate. A governance halt outranks everything (it is a clean exit,
+   * not a fault). A tripped guard outranks the CLI's own subtype, because the guard is why we killed
+   * the session. And `bridgeDown` outranks a reported `success`, because a session whose tools were
+   * all broken still ends `subtype:'success'` — measured, and the reason this block exists.
+   *
+   * @param {Message[]} messages
+   * @param {ToolDef[]} tools
+   * @param {Record<string, any>} options - the Loop's run options (`ctx` is read from here).
+   * @returns {Promise<GenerateResult>}
+   */
+  async _generateWithMcp(messages, tools, options = {}) {
+    if (options.cacheMessages) {
+      throw new Error(
+        '[CLIPipeProvider] cacheMessages cannot apply in native tool mode — the CLI owns the transcript '
+        + 'and caches it session-side, so there is no request body for a breakpoint to ride on. Remove the option.',
+      );
+    }
+    const sysMsg = messages.find((m) => m.role === 'system');
+    const systemPrompt = (sysMsg && typeof sysMsg.content === 'string' && sysMsg.content)
+      || 'You are an agent. Use the tools provided over MCP when they are needed.';
+
+    const bridge = await createBridge({
+      tools,
+      policy: this.policy,
+      ctx: options.ctx,
+      maxConsecutiveDenials: this.maxConsecutiveDenials,
+      maxIdenticalToolErrors: this.maxIdenticalToolErrors,
+    });
+
+    let r;
+    try {
+      r = await runSession({
+        command: this.command,
+        baseArgs: this.args,
+        systemPrompt,
+        task: renderTranscript(messages),
+        sockPath: bridge.sockPath,
+        maxTurns: this.maxTurns,
+        timeoutMs: this.sessionTimeout,
+        bridgeTimeoutMs: this.bridgeTimeoutMs,
+        onTurn: this.onTurn,
+        ctx: options.ctx,
+        cwd: this.cwd,
+        env: this.env,
+      });
+    } finally {
+      bridge.close();
+    }
+
+    const st = bridge.state;
+    // A governance halt is a CLEAN exit and must reach the Loop as a HaltError, not as a session
+    // error tag — the Loop is the thing that knows a halt seals the transcript rather than faulting.
+    if (st.halt) throw st.halt;
+    if (r.turnHalt) throw r.turnHalt;
+    if (r.spawnError) {
+      throw new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${r.spawnError.message}`, /** @type {any} */ ({ status: 0 }));
+    }
+
+    /** @type {import('../types').Usage} */
+    const usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+    for (const t of r.turns) {
+      usage.inputTokens += t.inputTokens || 0;
+      usage.outputTokens += t.outputTokens || 0;
+      usage.cacheReadTokens += t.cacheReadTokens || 0;
+      usage.cacheCreationTokens += t.cacheCreationTokens || 0;
+    }
+
+    const { stopReason, error } = resolveSessionError({
+      terminal: st.terminal,
+      bridgeDown: st.bridgeDown,
+      attempted: r.attempted,
+      served: st.toolCalls,
+      timedOut: Boolean(r.timedOut),
+      subtype: r.final && r.final.subtype,
+    });
+
+    const costUsd = (r.final && Number.isFinite(r.final.total_cost_usd)) ? r.final.total_cost_usd : null;
+
+    // The authoritative price arrives only at session end (the CLI prices the SESSION, not the turn),
+    // so when per-turn streaming is wired it gets one closing event carrying the cost with zero
+    // usage — the tokens were already streamed, and double-counting either axis would be a lie.
+    if (this.onTurn) {
+      try {
+        await this.onTurn({
+          model: (r.final && r.final.model) || null,
+          provider: 'clipipe',
+          usage: { inputTokens: 0, outputTokens: 0 },
+          costUsd,
+          pricing: costUsd === null ? 'unpriced' : 'priced',
+          durationMs: r.ms,
+          ctx: options.ctx,
+          kind: 'session',
+        });
+      } catch (err) {
+        if (err instanceof HaltError) throw err;
+      }
+    }
+
+    /** @type {GenerateResult} */
+    const result = {
+      text: (r.final && typeof r.final.result === 'string') ? r.final.result : '',
+      toolCalls: [],
+      usage,
+      model: (r.final && r.final.model) || null,
+      stopReason,
+      session: {
+        turns: r.turns.length,
+        toolCalls: st.toolCalls,
+        error,
+        // Only true when we ACTUALLY streamed — unwired, the Loop must still forward the total or
+        // the gate would see this session as free.
+        usageReported: Boolean(this.onTurn),
+      },
+    };
+    if (costUsd !== null) result.costUsd = costUsd;
+    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 +419,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 +427,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

package/types/index.d.ts

@@ -34,6 +34,13 @@ export interface RunMetrics {
   turns: number;
   /** Total tool calls the model made (every invocation, including denied/unknown). */
   toolCalls: number;
+  /**
+   * BA-16 — turns that happened INSIDE a cycle-owning provider's own session (CLIPipe native tool
+   * mode). Such a session is ONE Loop round however many turns it really took, so `turns` alone
+   * would report a 14-turn session as 1 — a round count that reads far cheaper and shorter than the
+   * run actually was. 0 for every provider whose cycle the Loop drives.
+   */
+  sessionTurns: number;
   /** Per-tool invocation counts, keyed by tool name. */
   byTool: Record<string, number>;
   /** Cumulative token spend across all rounds (incl. summarize calls), by tier. */
@@ -97,6 +104,26 @@ export interface GenerateResult {
    *   pre-BA-6 behavior exactly, so an unmapped provider degrades to the status quo.
    */
   stopReason?: string | null;
+  /**
+   * BA-16 — present ONLY when the provider ran its own multi-turn session for this single call
+   * (`Provider.ownsCycle`), e.g. CLIPipe native tool mode, where the CLI executes the caller's tools
+   * natively over MCP and keeps going until it answers or hits a bound.
+   *
+   * It exists so the Loop can stay honest about a call that was not one turn:
+   * - `turns` / `toolCalls` — what really happened, so `metrics` cannot report a 14-turn session as 1.
+   * - `error` — a terminal the provider detected INSIDE the session (a turn bound, a deny/stuck
+   *   streak, a broken tool bridge). The Loop surfaces it as the run's `error`, never merely as a
+   *   field: every downstream consumer branches on `error` as the sole success signal, so surfacing
+   *   alone would let a session in which no tool call ever succeeded propagate as converged.
+   * - `usageReported` — the provider ALREADY forwarded this call's usage per internal turn, so the
+   *   Loop must not forward the summed total again and bill the gate twice.
+   */
+  session?: {
+    turns: number;
+    toolCalls: number;
+    error: string | null;
+    usageReported: boolean;
+  };
   /**
    * True when the requested `temperature` was rejected by the model (400, unsupported/deprecated) and
    * the request was retried without it (BA-10). The response was produced at the model's DEFAULT
@@ -165,6 +192,19 @@ export interface Provider {
   model?: string | null;
   /** Provider name, surfaced in onLlmResult. */
   name?: string | null;
+  /**
+   * BA-16 — true when the provider runs its OWN multi-turn cycle inside a single `generate()` call
+   * (CLIPipe native tool mode), executing the caller's tools itself rather than returning
+   * `toolCalls` for the Loop to run.
+   *
+   * The Loop reads this to REFUSE options it could never honor rather than accept them and leave
+   * them silently dead: `assemble`/`trim` (the provider owns the transcript) and, most importantly,
+   * a Loop-level `policy` — no tool call reaches the Loop, so that fence would simply not be there
+   * while the run still looked governed. Such a provider must carry its own `policy`.
+   */
+  ownsCycle?: boolean;
+  /** Gate chokepoint for a cycle-owning provider — same contract as `Loop({policy})`. */
+  policy?: ((tool: string, args: any, ctx?: any) => any) | null;
   generate(
     messages: Message[],
     tools?: ToolDef[],