total-recall-brain 3.43.3 → 3.45.0

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/router.mjs

@@ -1,5 +1,5 @@
 /**
- * Meta Harness Smart Router
+ * Metaharness Smart Router
  * Manages honest quota/readiness tracking, benchmark matrices, RouteLLM complexity routing,
  * and cost-vs-frontier harness selection.
  *
@@ -21,6 +21,7 @@ import { getModelCatalog, joinHarnessModels } from './model-catalog.mjs';
 import { readReceipts, activeQuotaWalls, activeCredentialBlocks } from './learner.mjs';
 import { resolvePool, exclusionReason, isLocalExecutionNode } from './pool.mjs';
 import { readCodexRateLimits, measuredWalls } from './telemetry.mjs';
+import { claudeProofCurrent, INCLUDED_AGENTS, readIncludedPolicy } from './included-usage.mjs';
 import { derivedDir } from './paths.mjs';
 
 /**
@@ -97,7 +98,7 @@ async function cachedMeteredQuota(options) {
 async function readMeteredQuota(options) {
   let meteredQuota = { billingModel: 'metered', creditRemainingUSD: null, usageUSD: null, usageDailyUSD: null, usageWeeklyUSD: null, usagePercent: null, quotaNote: 'No OpenRouter key in the auth store', status: 'unconfigured' };
   try {
-    const key = options.openRouterKey !== undefined ? options.openRouterKey : (runHostCli(['auth', 'secret', 'get', 'DEVELOPER_OPENROUTER_API_KEY']) || runHostCli(['auth', 'secret', 'get', 'OPENROUTER_API_KEY']));
+    const key = options.openRouterKey !== undefined ? options.openRouterKey : runHostCli(['auth', 'secret', 'get', 'OPENROUTER_API_KEY']);
     if (key) {
       const response = await (options.fetchImpl || fetch)('https://openrouter.ai/api/v1/auth/key', { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(6000) });
       if (!response.ok) throw new Error(`HTTP ${response.status}`);
@@ -139,6 +140,7 @@ async function readMeteredQuota(options) {
  * Never fabricates or hardcodes synthetic subscription percentages.
  */
 export async function inspectQuotas(options = {}) {
+  const policy = options.policy || await readIncludedPolicy();
   const quotas = {};
   const remote = options.node && options.node !== 'local';
   const fleet = (options.fleet || fleetTelemetry)();
@@ -162,27 +164,37 @@ export async function inspectQuotas(options = {}) {
   }
 
   // Harness state comes from the selected machine. Quota walls are this machine's receipts.
-  const inspected = remote ? await (options.inspectNodeFn || inspectNode)(options.node) : await (options.inspect || inspectAgents)({ env: process.env });
+  const claudePlan = policy.enabled ? policy.claudePlan?.organization : undefined;
+  const inspected = remote ? await (options.inspectNodeFn || inspectNode)(options.node) :
+    await (options.inspect || inspectAgents)({ env: process.env, cwd: options.cwd, claudePlan });
   const codexLimits = remote ? null : readCodexRateLimits();
-  const walls = remote ? {} : { ...activeQuotaWalls(await readReceipts()), ...measuredWalls(codexLimits) };
+  const receipts = remote ? [] : (await readReceipts()).filter(run => !policy.enabled || run.billingMode === 'included');
+  const walls = remote ? {} : { ...activeQuotaWalls(receipts), ...(!policy.enabled ? measuredWalls(codexLimits) : {}) };
   const metered = METERED_HARNESSES;
 
-  const blocks = remote ? {} : activeCredentialBlocks(await readReceipts());
-  for (const agent of inspected.agents || []) {
+  const blocks = activeCredentialBlocks(receipts);
+  for (const installed of inspected.agents || []) {
+    const agent = policy.enabled && !remote && installed.id === 'claude' && !claudePlan ?
+      { ...installed, authenticated: claudeProofCurrent(policy) } : installed;
     const wall = walls[agent.id];
     const block = blocks[agent.id];
-    const reason = exclusionReason(agent, wall, block);
+    const policyBlocked = policy.enabled && !INCLUDED_AGENTS.includes(agent.id);
+    const explicitOpenRouter = !remote && Boolean(policy.openRouter?.[agent.id]);
+    const reason = policyBlocked ? (explicitOpenRouter ? 'available through explicit OpenRouter dispatch' : 'outside the included usage route') : exclusionReason(agent, wall, block);
     let status = 'ready';
     if (!agent.installed) status = 'not_installed';
+    else if (policyBlocked) status = 'blocked';
     else if (agent.authenticated === false || block) status = 'needs_auth';
     else if (agent.blockedBy) status = 'blocked';
     else if (wall) status = 'exhausted';
     else if (agent.authenticated === 'unknown') status = 'unverified';
     const quota = {
       installed: Boolean(agent.installed), version: agent.version || null,
-      billingModel: agent.id === 'ollama' ? 'local' : metered.has(agent.id) ? 'metered' : 'subscription',
+      billingModel: policy.enabled && !remote && !claudePlan && agent.id === 'claude' ? 'included-api-credits' :
+        agent.id === 'ollama' ? 'local' : metered.has(agent.id) ? 'metered' : 'subscription',
       rolling5hUsedPercent: null, weeklyUsedPercent: null, usagePercent: null,
       quotaSource: 'none', quotaNote: reason || 'No usage figure is available from this harness', status,
+      ...(explicitOpenRouter ? { explicitOpenRouter: true } : {}),
       ...(wall ? { resetsAt: wall.until, wallMessage: wall.message } : {}),
     };
     if (agent.id === 'codex' && codexLimits) {
@@ -196,7 +208,7 @@ export async function inspectQuotas(options = {}) {
     quotas[agent.id] = quota;
   }
 
-  const meteredQuota = options.skipMetered
+  const meteredQuota = options.skipMetered || policy.enabled
     ? { billingModel: 'metered', status: 'not-read', quotaNote: 'Not read: no metered harness is in this route pool' }
     : await cachedMeteredQuota(options);
   quotas.metered = meteredQuota;
@@ -241,9 +253,10 @@ export function placeLocalWork(fleet = {}) {
 }
 
 export async function routeTask(taskDescription, options = {}) {
+  const policy = await readIncludedPolicy();
   let complexity = classifyTaskComplexity(taskDescription, options);
   let classifier = { source: 'heuristic' };
-  if (options.jev) {
+  if (options.jev && !policy.enabled) {
     try {
       const decided = classifyWithDecision(taskDescription, options.decisionRun);
       complexity = { ...complexity, tier: decided.tier, isFrontierRecommended: decided.tier === 'frontier', isLocalRecommended: decided.tier === 'local' };
@@ -260,17 +273,19 @@ export async function routeTask(taskDescription, options = {}) {
   // fleet telemetry places local work, and the balance matters only to a metered harness.
   const shared = scoped.inspect ? null : inspectAgents({ env: process.env });
   const lean = shared ? { ...scoped, inspect: () => shared } : scoped;
-  const [pool, receipts] = await Promise.all([resolvePool(lean), readReceipts()]);
+  const [pool, receipts] = await Promise.all([resolvePool({ ...lean, policy }), readReceipts()]);
   const quotaReport = await inspectQuotas({
     ...lean,
+    policy,
     meteredTtlMs: METERED_TTL_MS,
-    skipMetered: lean.openRouterKey === undefined && !pool.ready.some(h => METERED_HARNESSES.has(h.id)),
+    skipMetered: policy.enabled || (lean.openRouterKey === undefined && !pool.ready.some(h => METERED_HARNESSES.has(h.id))),
     ...(remote || lean.fleet ? {} : { fleet: complexity.tier === 'local' ? cachedFleet : () => ({ ok: false, error: 'Not read: this route places no local work', nodes: [] }) }),
   });
   const quotas = quotaReport.quotas;
   const routing = selectOptimalHarness(taskDescription, pool.ready.map(h => h.id), quotas, { ...options, tierOverride: complexity.tier, empiricalScorecard: computeEmpiricalScorecard(receipts) });
   const selectedQuota = quotas[routing.selected] || {};
   const warnings = [];
+  if (policy.enabled && options.jev) warnings.push('Included usage policy uses the local task classifier.');
   if (typeof selectedQuota.usagePercent === 'number' && selectedQuota.usagePercent > 85) warnings.push(`${routing.selected} is at ${selectedQuota.usagePercent}% measured usage.`);
   if (selectedQuota.status === 'unverified') warnings.push(`${routing.selected} has no login probe; only a completed run proves it works.`);
   if (selectedQuota.billingModel === 'metered') warnings.push(`${routing.selected} bills per token.`);
@@ -278,6 +293,7 @@ export async function routeTask(taskDescription, options = {}) {
   return {
     ok: Boolean(routing.selected), task: taskDescription, classifier, complexity,
     selected: routing.selected, tier: complexity.tier, candidates: routing.candidates, excluded: pool.excluded,
+    ...(policy.enabled && !routing.selected ? { deferred: pool.excluded.find(row => row.failureKind === 'quota') || null } : {}),
     placement: complexity.tier === 'local' ? placeLocalWork(quotaReport.fleet) : null,
     scoring: 'Adapter quality and cost scores are configured priors, adjusted by pass rates measured on this machine.',
     quotaSnapshot: { selectedHarnessStatus: selectedQuota.status || null, selectedHarnessUsage: selectedQuota.usagePercent ?? null, freeMemGB: quotas.system.freeMemGB ?? null },

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/runtime.mjs

@@ -1,15 +1,37 @@
-/** One native runtime-management boundary for every installed agent. */
+/** Runtime observations and explicit maintenance. Agent work belongs to dispatch. */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { getActiveAdapters, findBinary, runProcess, agentEnvironment } from './worker.mjs';
 
+const DSH_OBSERVATIONS = ['status', 'sessions', 'tools', 'models', 'model', 'plugins', 'help'];
+const MAINTENANCE = new Map([
+  ['claude', [['auth', 'status']]],
+  ['codex', [['login', 'status']]],
+  ['cursor', [['status']]],
+  ['dsh', [...DSH_OBSERVATIONS.map(operation => [operation]), ['model', '--cache']]],
+  ['hermes', [['status'], ['status', '--full'], ['gateway', 'status'], ['skills', 'list'], ['plugins', 'list'], ['auth']]],
+  ['ollama', [['list'], ['ps']]],
+  ['openclaw', [['status'], ['health'], ['gateway', 'status'], ['plugins', 'list']]],
+]);
+
+export function validateRuntimeOperation(agent, args = []) {
+  if (typeof agent !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(agent)) throw new Error('Invalid agent adapter');
+  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 8192)) throw new Error('Invalid native runtime arguments');
+  if (args.some(arg => /(?:api[-_]?key|password|secret|access[-_]?token|refresh[-_]?token)/i.test(arg))) throw new Error('Credential values and mutations belong to the auth owner, never runtime argv');
+  const command = args.length ? args : [agent === 'dsh' ? 'status' : '--help'];
+  const supported = [['--help'], ['-h'], ['--version'], ...(MAINTENANCE.get(agent) || [])];
+  if (!supported.some(tuple => tuple.length === command.length && tuple.every((word, index) => word === command[index]))) {
+    throw new Error('Runtime accepts only supported maintenance commands. Use meta-harness dispatch or route --execute for agent work, or the owning plugin for service changes.');
+  }
+  return command;
+}
+
 export async function manageRuntime(agent, args = [], { env = process.env, probe = runProcess, cwd = process.cwd() } = {}) {
+  args = validateRuntimeOperation(agent, args);
   const adapter = getActiveAdapters().find(item => item.id === agent);
   if (!adapter) throw new Error('Unknown agent adapter');
-  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 8192)) throw new Error('Invalid native runtime arguments');
-  if (args.some(arg => /(?:api[-_]?key|password|secret|access[-_]?token|refresh[-_]?token)/i.test(arg))) throw new Error('Credential values and mutations belong to the auth owner, never runtime argv');
-  if (agent === 'dsh' && ['status','sessions','tools','models','model','plugins','help','--help','-h'].includes(args[0] || 'status')) {
+  if (agent === 'dsh' && DSH_OBSERVATIONS.includes(args[0])) {
     const { run } = await import('./adapters/dsh.mjs');
     const lines = [], errors = [], log = console.log, error = console.error;
     const previous = process.exitCode;
@@ -31,6 +53,6 @@ export async function manageRuntime(agent, args = [], { env = process.env, probe
   }
   const binary = findBinary(adapter.binary, env);
   if (!binary) throw new Error(`${adapter.name} is not installed on the selected node`);
-  const result = await probe(binary, args.length ? args : ['--help'], { cwd, timeoutMs:60000, env:agentEnvironment(env) });
-  return { ok:result.exitCode===0 && !result.reason, agent, exitCode:result.exitCode, output:result.stdout, error:result.reason || (result.exitCode ? result.stderr || 'Runtime command failed' : undefined) };
+  const result = await probe(binary, args, { cwd, timeoutMs:60000, env:agentEnvironment(env) });
+  return { ok:result.exitCode===0 && !result.reason, agent, exitCode:result.exitCode, output:result.stdout || (result.exitCode === 0 ? result.stderr : ''), error:result.reason || (result.exitCode ? result.stderr || 'Runtime command failed' : undefined) };
 }

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/session/claude.mjs

@@ -0,0 +1,319 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline';
+
+// Protocol sources: code.claude.com/docs/en/{cli-reference,headless}.md and
+// agent-sdk/{streaming-vs-single-mode,typescript}.md (read 2026-11-09).
+const controls = ['reply', 'interrupt', 'answer', 'fork', 'goal', 'limits', 'schema', 'review'];
+const ownedValues = new Set(['--input-format', '--output-format', '--session-id', '--name', '-n',
+  '--max-turns', '--max-budget-usd', '--json-schema', '--effort', '--fallback-model', '--mcp-config',
+  '--permission-prompt-tool']);
+const ownedSwitches = new Set(['-p', '--print', '--verbose', '--replay-user-messages',
+  '--include-hook-events', '--forward-subagent-text']);
+const textOf = content => typeof content === 'string' ? content : Array.isArray(content)
+  ? content.filter(block => block.type === 'text').map(block => block.text).join('\n') : '';
+const failureKind = (text, subtype) => /error_max_(turns|budget_usd)/.test(subtype || '') ? 'limit'
+  : /quota|rate.?limit|usage limit|credit|\b429\b/i.test(text) ? 'quota'
+  : /not (?:logged|signed) in|authenticat|invalid api key|\b401\b/i.test(text) ? 'auth' : 'agent';
+
+/** Own one Claude stream-json process. Only Node built-ins are used on remote nodes. */
+export function createClaudeDriver({ harness, binary, args = [], cwd, env, job,
+  options = {}, onEvent = () => {}, onFrame = () => {}, spawnFn = spawn } = {}) {
+  const capabilities = Object.fromEntries(controls.map(key => [key, 'unsupported']));
+  let sessionId = options.forkSession ? randomUUID() : options.sessionId || randomUUID();
+  let child, lines, started = false, closing = false, exited = false, initialized = false;
+  let settled = false, stderr = '', response = '', closePromise, continuation;
+  let usage = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+  let resolveReady, rejectReady, resolveDone, resolveExit;
+  const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+  ready.catch(() => {}); // start() is the public reader of startup errors.
+  let done = new Promise(resolve => { resolveDone = resolve; });
+  const exit = new Promise(resolve => { resolveExit = resolve; });
+  const signal = name => {
+    try { if (process.platform !== 'win32' && child?.pid) process.kill(-child.pid, name); else child?.kill(name); return true; }
+    catch { return false; }
+  };
+  const pending = new Map();
+  const requests = new Map();
+  const emit = (kind, fields = {}) => { try { onEvent({ kind, text: '', ...fields }); } catch { /* observers do not own the process */ } };
+  const rejectPending = error => {
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(error); }
+    pending.clear();
+    requests.clear();
+  };
+  const complete = result => {
+    if (settled) return;
+    settled = true;
+    resolveDone({ ok: false, response, sessionId, usage: { ...usage }, structured: undefined,
+      error: null, failureKind: null, ...result });
+  };
+  const fail = error => {
+    const message = String(error?.message || error);
+    rejectReady(new Error(message));
+    rejectPending(new Error(message));
+    emit('error', { text: message });
+    complete({ error: message, failureKind: failureKind(message) });
+  };
+  const writable = () => {
+    if (!started || closing || exited || !child?.stdin?.writable) throw new Error('Claude session is not open.');
+  };
+  const write = frame => {
+    writable();
+    child.stdin.write(`${JSON.stringify(frame)}\n`, error => { if (error) fail(error); });
+  };
+  const userMessage = text => ({ type: 'user', uuid: randomUUID(), session_id: sessionId,
+    message: { role: 'user', content: text }, parent_tool_use_id: null });
+  const acknowledge = (id, value) => {
+    const entry = pending.get(id);
+    if (!entry) return;
+    pending.delete(id); clearTimeout(entry.timer);
+    emit('ack', { command: entry.command, requestId: id, via: 'native' });
+    entry.resolve(value);
+  };
+  const handle = frame => {
+    onFrame(frame);
+    if (!frame || typeof frame !== 'object') throw new Error('Invalid Claude stream message.');
+    const parent = frame.parent_tool_use_id;
+    const parentFields = parent ? { parent_tool_use_id: parent } : {};
+    if (frame.type === 'system' && frame.subtype === 'init') {
+      sessionId = frame.session_id || sessionId;
+      const reported = Array.isArray(frame.capabilities) ? frame.capabilities : [];
+      Object.assign(capabilities, { reply: 'native',
+        interrupt: reported.includes('interrupt_receipt_v1') || reported.includes('interrupt_cancel_queued_v1') ? 'native' : 'metaharness',
+        answer: 'metaharness', fork: 'native', goal: 'metaharness', limits: 'native', schema: 'native', review: 'metaharness' });
+      initialized = true;
+      emit('session', { text: `Claude session ${sessionId}`, sessionId, session: sessionId,
+        capabilities: { ...capabilities }, nativeCapabilities: [...reported], model: frame.model });
+      resolveReady();
+      return;
+    }
+    if (frame.type === 'control_response') {
+      const receipt = frame.response;
+      const entry = pending.get(receipt?.request_id);
+      if (entry?.command !== 'interrupt') return;
+      if (receipt.subtype === 'error') {
+        pending.delete(receipt.request_id); clearTimeout(entry.timer);
+        entry.reject(new Error(receipt.error || 'Claude rejected the interrupt.'));
+      } else acknowledge(receipt.request_id, { ack: true, via: 'native', ...receipt.response });
+      return;
+    }
+    if (frame.type === 'control_request') {
+      if (frame.request?.subtype === 'can_use_tool') {
+        requests.set(frame.request_id, frame.request);
+        emit('approval', { text: `Approval for ${frame.request.tool_name}`, requestId: frame.request_id, request: frame.request });
+      }
+      return;
+    }
+    if (frame.type === 'system' && frame.subtype === 'api_retry') {
+      emit('error', { text: `API retry ${frame.attempt}/${frame.max_retries}: ${frame.error}`,
+        retry: true, attempt: frame.attempt, maxRetries: frame.max_retries,
+        retryDelayMs: frame.retry_delay_ms, errorStatus: frame.error_status });
+      return;
+    }
+    if (frame.type === 'system' && ['hook_started', 'hook_progress', 'hook_response'].includes(frame.subtype)) {
+      emit('hook', { text: frame.output || frame.hook_name || '', name: frame.hook_name,
+        phase: frame.subtype.slice(5), hookId: frame.hook_id, hookEvent: frame.hook_event,
+        outcome: frame.outcome, stdout: frame.stdout, stderr: frame.stderr, exitCode: frame.exit_code });
+      return;
+    }
+    if (frame.type === 'system' && frame.subtype === 'permission_denied') {
+      emit('error', { text: `Permission denied: ${frame.tool_name || frame.message || ''}` });
+      return;
+    }
+    if (frame.type === 'assistant' || frame.type === 'user') {
+      const content = frame.message?.content;
+      const blocks = Array.isArray(content) ? content : typeof content === 'string' ? [{ type: 'text', text: content }] : [];
+      if (frame.type === 'user' && !parent && !blocks.some(block => block.type === 'tool_result')) {
+        // Only a replay with our UUID acknowledges delivery. Tool results and subagent
+        // prompts must not acknowledge a user's pending message with the same text.
+        if (pending.get(frame.uuid)?.command === 'reply') acknowledge(frame.uuid, { ack: true, via: 'native' });
+        return;
+      }
+      for (const block of blocks) {
+        if (frame.type === 'assistant' && block.type === 'tool_use') {
+          emit('step-start', { text: `${block.name}: ${JSON.stringify(block.input || {})}`,
+            toolUseId: block.id, tool: block.name, input: block.input, ...parentFields });
+        } else if (block.type === 'tool_result') {
+          emit('step-end', { text: textOf(block.content) || (block.is_error ? 'Tool returned an error' : 'Tool finished'),
+            toolUseId: block.tool_use_id, isError: block.is_error === true, ...parentFields });
+        } else if (block.type === 'text' || (parent && block.type === 'thinking')) {
+          const text = block.text || block.thinking || '';
+          if (parent) emit('subagent', { text, ...parentFields });
+          else if (frame.type === 'assistant') {
+            response += text;
+            emit('message', { text });
+          }
+        }
+      }
+      if (frame.error) emit('error', { text: String(frame.error), ...parentFields });
+      return;
+    }
+    if (frame.type === 'result') {
+      sessionId = frame.session_id || sessionId;
+      usage = { inputTokens: frame.usage?.input_tokens ?? 0,
+        outputTokens: frame.usage?.output_tokens ?? 0, costUsd: frame.total_cost_usd ?? 0 };
+      const ok = frame.subtype === 'success' && !frame.is_error;
+      const error = ok ? null : frame.errors?.join('\n') || frame.result || frame.subtype || 'Claude reported failure.';
+      const result = { ok, response: frame.result ?? response, sessionId, usage: { ...usage },
+        ...(options.trackTurns ? { turns: frame.num_turns || 1 } : {}),
+        structured: frame.structured_output, error, failureKind: ok ? null : failureKind(error, frame.subtype) };
+      emit('usage', { ...usage });
+      emit('finish', { text: ok ? 'Finished' : error, ...result });
+      complete(result);
+      response = '';
+      return;
+    }
+    if (frame.type === 'error') emit('error', { text: String(frame.error?.message || frame.message || frame.error) });
+  };
+
+  function launchArgs() {
+    const result = [];
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i].split('=')[0];
+      if (ownedValues.has(flag)) { if (!args[i].includes('=')) i++; continue; }
+      if (ownedSwitches.has(flag)) continue;
+      // The MCP prompt tool must get approval requests under an operator/rules policy.
+      if (options.approvalPolicy && options.approvalPolicy !== 'auto') {
+        if (flag === '--dangerously-skip-permissions') continue;
+        if (flag === '--permission-mode') { if (!args[i].includes('=')) i++; continue; }
+      }
+      result.push(args[i]);
+    }
+    result.push('-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+      '--replay-user-messages', '--include-hook-events', '--forward-subagent-text');
+    if (options.resumeSession) result.push('--resume', options.sessionId);
+    else result.push('--session-id', sessionId);
+    if (options.forkSession) {
+      if (options.atTurn !== undefined) throw new Error('Claude CLI cannot fork at a selected turn.');
+      result.push('--fork-session');
+      result.push('--session-id', sessionId);
+    }
+    const name = options.name ?? (typeof job === 'string' ? job : job?.id ?? job?.job);
+    for (const [flag, value] of [['--name', name], ['--max-turns', options.maxTurns],
+      ['--max-budget-usd', options.maxBudgetUsd], ['--json-schema', options.resultSchema],
+      ['--effort', options.effort], ['--fallback-model', options.fallbackModel], ['--mcp-config', options.mcpConfig]]) {
+      if (value !== undefined && value !== null) result.push(flag, typeof value === 'object' ? JSON.stringify(value) : String(value));
+    }
+    result.push('--permission-prompt-tool', 'mcp__metaharness__approve');
+    return result;
+  }
+
+  return {
+    capabilities, get done() { return done; },
+    async next(text, { resultSchema, maxTurns = options.maxTurns, maxBudgetUsd = options.maxBudgetUsd } = {}) {
+      if (continuation) return continuation.next(text, { resultSchema, maxTurns, maxBudgetUsd });
+      writable();
+      if (!settled) throw new Error('The current turn has not finished.');
+      // The schema is a process flag. Reopen the same native session when a
+      // goal-check turn needs a different schema from the requested result.
+      if (JSON.stringify(resultSchema) !== JSON.stringify(options.resultSchema) || maxTurns !== options.maxTurns || maxBudgetUsd !== options.maxBudgetUsd) {
+        await this.close();
+        continuation = createClaudeDriver({ harness, binary, args, cwd, env, job, spawnFn, onEvent, onFrame,
+          options: { ...options, sessionId, resumeSession: true, forkSession: false, resultSchema, maxTurns, maxBudgetUsd } });
+        await continuation.start(text);
+        done = continuation.done;
+        return done;
+      }
+      settled = false; response = '';
+      done = new Promise(resolve => { resolveDone = resolve; });
+      write(userMessage(text));
+      return done;
+    },
+    async start(brief) {
+      if (started) return ready;
+      if (closing) throw new Error('Claude session is closed.');
+      if (typeof brief !== 'string') throw new TypeError('The brief must be text.');
+      started = true;
+      try {
+        child = spawnFn(binary || harness?.binary || 'claude', launchArgs(), {
+          cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        child.once('error', error => { fail(error); if (!child.pid) { exited = true; resolveExit(); } });
+        child.stdin.on('error', error => { if (!closing && !exited) fail(error); });
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-65536); });
+        lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        lines.on('line', line => {
+          if (!line.trim()) return;
+          try { handle(JSON.parse(line)); }
+          catch (error) { fail(new Error(`Invalid Claude stream: ${error.message}`)); signal('SIGTERM'); }
+        });
+        child.once('close', (code, signal) => {
+          exited = true; lines.close(); resolveExit();
+          const error = new Error(stderr.trim() || `Claude closed without a result (${signal || code}).`);
+          rejectPending(error);
+          if (!initialized) rejectReady(error);
+          if (!settled) fail(error);
+        });
+        // The CLI reads its first user message before it emits system/init.
+        write(userMessage(brief));
+      } catch (error) { exited = true; resolveExit(); fail(error); }
+      return ready;
+    },
+    async send(text) {
+      if (continuation) return continuation.send(text);
+      if (typeof text !== 'string') throw new TypeError('The reply must be text.');
+      writable();
+      const frame = userMessage(text);
+      return new Promise((resolve, reject) => {
+        pending.set(frame.uuid, { command: 'reply', resolve, reject });
+        try { write(frame); } catch (error) { pending.delete(frame.uuid); reject(error); }
+      });
+    },
+    async interrupt() {
+      if (continuation) return continuation.interrupt();
+      writable();
+      if (!initialized) throw new Error('Claude session is not live.');
+      if (capabilities.interrupt !== 'native') {
+        if (!signal('SIGTERM')) throw new Error('Cannot interrupt Claude.');
+        emit('ack', { command: 'interrupt', via: 'metaharness' });
+        return { ack: true, via: 'metaharness' };
+      }
+      const requestId = randomUUID();
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(requestId); reject(new Error('Claude interrupt receipt timed out.')); }, 30000);
+        pending.set(requestId, { command: 'interrupt', resolve, reject, timer });
+        try { write({ type: 'control_request', request_id: requestId, request: { subtype: 'interrupt' } }); }
+        catch (error) { clearTimeout(timer); pending.delete(requestId); reject(error); }
+      });
+    },
+    async answer(requestId, value) {
+      if (continuation) return continuation.answer(requestId, value);
+      if (!requests.has(requestId)) throw new Error('No native approval has this ID. Answer MCP requests through the Metaharness inbox.');
+      write({ type: 'control_response', response: { subtype: 'success', request_id: requestId, response: value } });
+      requests.delete(requestId);
+      emit('ack', { command: 'approve', requestId, via: 'native' });
+      return { ack: true, via: 'native' };
+    },
+    async fork({ atTurn } = {}) {
+      if (continuation) return continuation.fork({ atTurn });
+      if (!initialized) throw new Error('Claude session is not live.');
+      if (atTurn !== undefined) throw new Error('Claude CLI cannot fork at a selected turn.');
+      const fork = createClaudeDriver({ harness, binary, args,
+        cwd, env, job, options: { ...options, sessionId, resumeSession: true, forkSession: true }, spawnFn });
+      try {
+        // /rename is a documented local print-mode command. It materializes the fork
+        // without replaying the brief or asking a model to do more work.
+        await fork.start(`/rename ${options.name || 'Metaharness fork'}`);
+        const result = await fork.done;
+        if (!result.ok) throw new Error(result.error);
+        return { sessionId: result.sessionId };
+      } finally { await fork.close(); }
+    },
+    async close() {
+      if (continuation) return continuation.close();
+      if (closePromise) return closePromise;
+      closing = true;
+      rejectPending(new Error('Claude session is closed.'));
+      if (!started) { exited = true; rejectReady(new Error('Claude session is closed.')); complete({ error: 'Claude session was not started.', failureKind: 'agent' }); resolveExit(); }
+      closePromise = (async () => {
+        if (exited) return;
+        child.stdin.end();
+        const term = setTimeout(() => signal('SIGTERM'), 1000);
+        const kill = setTimeout(() => signal('SIGKILL'), 2000);
+        try { await exit; } finally { signal('SIGKILL'); clearTimeout(term); clearTimeout(kill); }
+      })();
+      return closePromise;
+    },
+  };
+}