bare-agent 0.31.0 → 0.33.0

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,78 @@ 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. 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) Maps to the CLI's `--max-turns`. The bound stop is NAMED
+     * (`error_max_turns` → `session.error:'max_turns'`), never a silent clean success.
+     */
+    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 */
@@ -48,6 +120,51 @@ 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'|'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.
  */
 export class CLIPipeProvider {
     /**
@@ -64,10 +181,41 @@ 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[];
+        parseResult(stdout: string): ParsedEnvelope;
+        probe: {
+            system: string;
+            user: string;
+            isCapable: (parsed: ParsedEnvelope) => boolean;
+        };
+    } | null;
+    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.
+     * 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 +224,50 @@ 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;
+    /**
+     * 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
+     * `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