bare-agent 0.32.0 → 0.33.1

package/src/provider-clipipe.d.ts

@@ -35,30 +35,86 @@ export type CLIPipeOptions = {
      */
     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.
+     * - 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.
+     */
+    toolProtocol?: "claude" | "claude-mcp" | undefined;
+    /**
+     * - (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.
+     */
+    policy?: ((tool: string, args: any, ctx?: any) => any) | undefined;
+    /**
+     * - (native mode) Called with `{model, provider, usage, costUsd, pricing,
+     * durationMs, ctx, kind}` for EACH completed CLI turn as it arrives (`kind:'turn'`, four cache tiers,
+     * `costUsd:null` — the CLI prices the session, not the turn), then once at session end
+     * (`kind:'session'`) carrying the authoritative total cost with zero usage. Streaming, never
+     * 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.
+     */
+    onTurn?: Function | undefined;
+    /**
+     * - (native mode) Bound on ASSISTANT/LLM TURNS — the same unit as the
+     * Loop path's turn bound, so a caller's `maxTurns` means one thing on both surfaces (BA-17). NOT a
+     * tool-call count: a single turn may issue a dozen parallel tool calls and still be one turn
+     * (measured: 12 calls across 2 turns, well inside `--max-turns 3`). Enforced twice on purpose —
+     * the CLI's own `--max-turns` stops the session cleanly at N and emits its result event (the only
+     * report of the session's real cost), and a parent-side counter kills it if a turn beyond N is
+     * ever observed, since that flag is undocumented in `claude --help` and a rename would otherwise
+     * silently unbound the session. Either way the stop is NAMED (`session.error:'max_turns'`,
+     * `stopReason:'max_turns'`) and carries the last turn's text forward, never a silent clean success
+     * and never an empty result.
+     */
+    maxTurns?: number | undefined;
+    /**
+     * - (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.
+     */
+    maxConsecutiveDenials?: number | undefined;
+    /**
+     * - (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.
+     */
+    maxIdenticalToolErrors?: number | undefined;
+    /**
+     * - (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.
+     */
+    sessionTimeout?: number | undefined;
+    /**
+     * - (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.
+     */
+    bridgeTimeoutMs?: number | undefined;
+    /**
+     * - (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.
      */
     probeCapability?: boolean | undefined;
 };
-/** @typedef {import('../types').Message} Message */
-/** @typedef {import('../types').ToolDef} ToolDef */
-/** @typedef {import('../types').GenerateResult} GenerateResult */
-/**
- * @typedef {object} CLIPipeOptions
- * @property {string} [command] - CLI command to spawn (required).
- * @property {string[]} [args=[]] - Arguments to pass to the command.
- * @property {string} [cwd] - Working directory for the child process.
- * @property {Record<string, string>} [env] - Environment variables for the child process.
- * @property {number} [timeout=30000] - Timeout in milliseconds.
- * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
- * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
- * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
- * @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 {
     /**
      * Provider that pipes prompts to a CLI command via stdin and reads stdout.
@@ -74,6 +130,13 @@ export class CLIPipeProvider {
     systemPromptFlag: string | null;
     onChunk: ((chunk: string) => void) | null;
     parse: "claude-json" | ((stdout: string) => Partial<GenerateResult>) | null;
+    nativeTools: boolean;
+    /**
+     * 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.
+     */
+    ownsCycle: boolean;
     toolProtocol: {
         name: string;
         turnArgs(systemPrompt: string): string[];
@@ -87,6 +150,13 @@ export class CLIPipeProvider {
     probeCapability: boolean;
     /** @type {Promise<void>|null} */
     _toolCapability: Promise<void> | null;
+    policy: ((tool: string, args: any, ctx?: any) => any) | null | undefined;
+    onTurn: Function | null | undefined;
+    maxTurns: number | null | undefined;
+    maxConsecutiveDenials: number | undefined;
+    maxIdenticalToolErrors: number | undefined;
+    sessionTimeout: number | undefined;
+    bridgeTimeoutMs: number | null | undefined;
     /**
      * 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
@@ -115,6 +185,26 @@ export class CLIPipeProvider {
      */
     _generateWithTools(messages: Message[], tools: ToolDef[]): Promise<GenerateResult>;
     _toolCallSeq: any;
+    /**
+     * 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>}
+     */
+    _generateWithMcp(messages: Message[], tools: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
     /**
      * 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

package/src/provider-clipipe.js

@@ -1,8 +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 */
@@ -18,10 +19,86 @@ const { buildToolSystemPrompt, renderTranscript, resolveToolProtocol, mapClaudeM
  * @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.
+ * @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) Bound on ASSISTANT/LLM TURNS — the same unit as the
+ *   Loop path's turn bound, so a caller's `maxTurns` means one thing on both surfaces (BA-17). NOT a
+ *   tool-call count: a single turn may issue a dozen parallel tool calls and still be one turn
+ *   (measured: 12 calls across 2 turns, well inside `--max-turns 3`). Enforced twice on purpose —
+ *   the CLI's own `--max-turns` stops the session cleanly at N and emits its result event (the only
+ *   report of the session's real cost), and a parent-side counter kills it if a turn beyond N is
+ *   ever observed, since that flag is undocumented in `claude --help` and a rename would otherwise
+ *   silently unbound the session. Either way the stop is NAMED (`session.error:'max_turns'`,
+ *   `stopReason:'max_turns'`) and carries the last turn's text forward, never a silent clean success
+ *   and never an empty result.
+ * @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.
  */
 
+/**
+ * Session total minus what the per-turn events already reported, per tier, floored at 0.
+ *
+ * Floored because a negative would be a CREDIT to a gate's running total — an under-count that
+ * silently widens a budget cap. If the streamed turns ever overshoot the session total, the honest
+ * report is "nothing further", never "give some back".
+ *
+ * @param {import('../types').Usage} total
+ * @param {import('../types').Usage[]} streamed
+ * @returns {import('../types').Usage}
+ */
+function subtractUsage(total, streamed) {
+  const sum = (/** @type {keyof import('../types').Usage} */ k) =>
+    streamed.reduce((a, t) => a + (Number(t[k]) || 0), 0);
+  const at = (/** @type {keyof import('../types').Usage} */ k) =>
+    Math.max(0, (Number(total[k]) || 0) - sum(k));
+  /** @type {import('../types').Usage} */
+  const out = { inputTokens: at('inputTokens'), outputTokens: at('outputTokens') };
+  // Only report a cache tier the session actually had — an absent tier stays absent, never a
+  // synthetic 0 (the Usage contract).
+  if (total.cacheReadTokens !== undefined) out.cacheReadTokens = at('cacheReadTokens');
+  if (total.cacheCreationTokens !== undefined) out.cacheCreationTokens = at('cacheCreationTokens');
+  return out;
+}
+
 class CLIPipeProvider {
   /**
    * Provider that pipes prompts to a CLI command via stdin and reads stdout.
@@ -44,10 +121,40 @@ class CLIPipeProvider {
     // 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;
+    // 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;
+    }
   }
 
   /**
@@ -67,6 +174,7 @@ class CLIPipeProvider {
    */
   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
@@ -147,6 +255,157 @@ class CLIPipeProvider {
     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 }));
+    }
+
+    // The result event carries the session's authoritative totals. It has no `model` key — the model
+    // id lives under `modelUsage` — which is exactly what `mapClaudeMeta` already unpacks for the
+    // emulation path, so the native path reuses it rather than re-deriving three fields by hand.
+    const meta = r.final ? mapClaudeMeta(r.final) : null;
+
+    // `result.usage` is the authoritative session total and is preferred when present: it also
+    // captures a turn the CLI billed but never emitted as an event (measured — a bounded session's
+    // cut-off turn). Summing the per-turn records is the fallback for a session we killed before its
+    // result event. Either way the arithmetic is per-TURN, never per block-event (BA-17).
+    const usage = (meta && r.final.usage) ? meta.usage : r.turns.reduce((/** @type {any} */ a, t) => ({
+      inputTokens: a.inputTokens + (t.inputTokens || 0),
+      outputTokens: a.outputTokens + (t.outputTokens || 0),
+      cacheReadTokens: a.cacheReadTokens + (t.cacheReadTokens || 0),
+      cacheCreationTokens: a.cacheCreationTokens + (t.cacheCreationTokens || 0),
+    }), { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 });
+
+    const { stopReason, error } = resolveSessionError({
+      // A bridge/guard terminal is more specific than the turn backstop, so it wins the tag.
+      terminal: st.terminal || r.terminal,
+      bridgeDown: st.bridgeDown,
+      attempted: r.attempted,
+      served: st.toolCalls,
+      timedOut: Boolean(r.timedOut),
+      subtype: r.final && r.final.subtype,
+    });
+
+    const costUsd = (meta && Number.isFinite(meta.costUsd)) ? /** @type {number} */ (meta.costUsd) : null;
+
+    // The authoritative figures arrive only at session end — the CLI prices the SESSION, not the
+    // turn — so when per-turn streaming is wired, one closing event RECONCILES both axes.
+    //
+    // Money: the whole cost, which no turn reported.
+    // Tokens: the RESIDUAL, not zero and not the total. A turn's `message.usage` is a snapshot taken
+    // when its first block was emitted and never revised (measured: a turn that emitted ~816 output
+    // tokens reported 2, identically on all 13 of its block-events), so the streamed per-turn sum is
+    // real but SHORT of the session total. Sending the difference makes a gate's token axis add up
+    // to exactly what the CLI itself reports — where sending the total would double-count everything
+    // already streamed, and sending zero would leave the axis quietly under-fed.
+    const residual = subtractUsage(usage, r.turns);
+    if (this.onTurn) {
+      try {
+        await this.onTurn({
+          model: (meta && meta.model) || null,
+          provider: 'clipipe',
+          usage: residual,
+          costUsd,
+          pricing: costUsd === null ? 'unpriced' : 'priced',
+          durationMs: r.ms,
+          ctx: options.ctx,
+          kind: 'session',
+        });
+      } catch (err) {
+        if (err instanceof HaltError) throw err;
+      }
+    }
+
+    // BA-5 on the native path: a bound or a tripped guard is normal termination for a bounded
+    // attempt, and the text is the ONLY channel from this attempt to the next. The CLI reports
+    // `result: null` when it stops on its own bound (measured), and a session we killed never emits
+    // a result at all — so fall back to the last assistant turn's own words rather than ''.
+    const finalText = (r.final && typeof r.final.result === 'string' && r.final.result)
+      ? r.final.result
+      : (r.lastText || '');
+
+    /** @type {GenerateResult} */
+    const result = {
+      text: finalText,
+      toolCalls: [],
+      usage,
+      model: (meta && meta.model) || null,
+      stopReason,
+      session: {
+        turns: r.turnCount,
+        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

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[],