lazyclaw 6.3.0 → 6.4.0

package/providers/registry.mjs

@@ -191,9 +191,8 @@ export const PROVIDER_INFO = {
     requiresApiKey: false,
     docs: 'Anthropic via the local `claude` CLI (Pro / Max subscription). No API key — auth flows through whatever account `claude` is logged in with. Requires Claude Code installed.',
     endpoint: 'subprocess: claude -p',
-    defaultModel: 'claude-opus-4-7',
+    defaultModel: 'claude-opus-4-8',
     suggestedModels: [
-      'claude-fable-5',
       'claude-opus-4-8',
       'claude-opus-4-7',
       'claude-opus-4-6',
@@ -207,18 +206,26 @@ export const PROVIDER_INFO = {
   'gemini-cli': {
     name: 'gemini-cli',
     requiresApiKey: false,
-    docs: 'Google Gemini via the local `gemini` CLI (free Google-account login). No API key — auth flows through whatever account `gemini` is logged in with. Requires @google/gemini-cli installed.',
+    docs: 'Google Gemini via the local `gemini` CLI (free Google-account login). No API key — auth flows through whatever account `gemini` is logged in with. Requires @google/gemini-cli installed. defaultModel is null on purpose: the set of models a given Google login may use is decided server-side, so by default lazyclaw passes no `-m` and lets the CLI pick the account-appropriate model. The suggestedModels below are optional power-user overrides.',
     endpoint: 'subprocess: gemini -p',
-    defaultModel: 'gemini-2.5-pro',
+    defaultModel: null,
     suggestedModels: ['gemini-2.5-pro', 'gemini-2.5-flash', 'pro', 'flash'],
   },
   'codex-cli': {
     name: 'codex-cli',
     requiresApiKey: false,
-    docs: 'OpenAI via the local `codex` CLI (ChatGPT Plus/Pro subscription). No API key — auth flows through `codex` login. Requires the codex CLI installed.',
+    // defaultModel is null by design. A ChatGPT-account codex login only
+    // accepts the models that plan is entitled to (read from ~/.codex/
+    // config.toml, e.g. "gpt-5.5"); forcing a marketing id like the old
+    // default "gpt-5-codex" makes the API reject the turn with HTTP 400
+    // "The '<model>' model is not supported when using Codex with a ChatGPT
+    // account." So by default we pass NO `-m` and let codex use its own
+    // account default. suggestedModels is a single best-effort hint; the
+    // reliable path is the picker's "use the provider's own default" entry.
+    docs: 'OpenAI via the local `codex` CLI (ChatGPT Plus/Pro subscription). No API key — auth flows through `codex` login. Requires the codex CLI installed. By default no model is forced: codex uses the account default from ~/.codex/config.toml (a ChatGPT-plan login rejects models it is not entitled to). Override only with a model your plan allows.',
     endpoint: 'subprocess: codex exec',
-    defaultModel: 'gpt-5-codex',
-    suggestedModels: ['gpt-5-codex', 'gpt-5', 'o3'],
+    defaultModel: null,
+    suggestedModels: ['gpt-5.5'],
   },
   anthropic: {
     name: 'anthropic',
@@ -226,9 +233,8 @@ export const PROVIDER_INFO = {
     keyPrefix: 'sk-ant-',
     docs: 'Anthropic Messages API (pay-per-token, requires sk-ant- key). Supports streaming + extended thinking. For subscription billing, use the `claude-cli` provider instead.',
     endpoint: 'https://api.anthropic.com/v1/messages',
-    defaultModel: 'claude-opus-4-7',
+    defaultModel: 'claude-opus-4-8',
     suggestedModels: [
-      'claude-fable-5',
       'claude-opus-4-8',
       'claude-opus-4-7',
       'claude-opus-4-6',

package/providers/retry.mjs

@@ -24,6 +24,17 @@ const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_MAX_BACKOFF_MS = 60_000;
 const ABSOLUTE_MAX_BACKOFF_MS = 5 * 60_000;  // hard ceiling, ignores caller
 
+// Errors safe to retry before the first chunk: rate limits AND transient
+// server-overload / 5xx. Anthropic surfaces overload as HTTP 529
+// (overloaded_error); generic upstreams use 5xx. 4xx other than 429 are
+// caller-fault and never retried.
+function isRetriableError(err) {
+  const code = err?.code;
+  if (code === 'RATE_LIMIT' || code === 'OVERLOADED' || code === 'SERVER_ERROR') return true;
+  const status = err?.status;
+  return Number.isFinite(status) && status >= 500 && status < 600;
+}
+
 function clampBackoff(retryAfterMs, max) {
   const ceiling = Math.min(max, ABSOLUTE_MAX_BACKOFF_MS);
   if (!Number.isFinite(retryAfterMs) || retryAfterMs < 0) return ceiling;
@@ -85,8 +96,9 @@ export function withRateLimitRetry(provider, retryOpts = {}) {
           lastErr = err;
           // Mid-stream errors cannot be retried: we'd produce duplicate text.
           if (yieldedAny) throw err;
-          // Only retry RATE_LIMIT and only if we still have attempts left.
-          if (err?.code !== 'RATE_LIMIT' || attempt >= attempts) throw err;
+          // Retry rate-limit AND transient server-overload/5xx, only while
+          // attempts remain. 4xx other than 429 bubble unchanged.
+          if (!isRetriableError(err) || attempt >= attempts) throw err;
           const wait = clampBackoff(err.retryAfterMs, maxBackoffMs);
           if (typeof onRetry === 'function') {
             try { onRetry({ attempt: attempt + 1, retryAfterMs: wait, err }); } catch { /* swallow */ }

package/providers/tool_use/anthropic.mjs

@@ -68,7 +68,7 @@ export async function callOnce({
   const url = `${(baseUrl || DEFAULT_BASE).replace(/\/$/, '')}/messages`;
   const fetchFn = fetchImpl || globalThis.fetch;
   const body = {
-    model: model || 'claude-opus-4-7',
+    model: model || 'claude-opus-4-8',
     max_tokens: maxTokens,
     messages,
   };
@@ -137,10 +137,24 @@ export function parseResponse(json) {
     }
   }
   const text = textParts.join('');
+  // The model hit the output token ceiling mid-turn: the text or tool_use
+  // block is partial/garbage. Flag it so the runner stops instead of acting on
+  // a cut-off final answer or an incomplete tool call.
+  const truncated = json?.stop_reason === 'max_tokens';
+  // Normalize token usage so agent_turn can accumulate spend across the loop
+  // (and team turns can feed the cost cap). null when the response omits it.
+  const usage = json?.usage
+    ? {
+        inputTokens: json.usage.input_tokens || 0,
+        outputTokens: json.usage.output_tokens || 0,
+        cacheCreationInputTokens: json.usage.cache_creation_input_tokens || 0,
+        cacheReadInputTokens: json.usage.cache_read_input_tokens || 0,
+      }
+    : null;
   if (calls.length === 0) {
-    return { kind: 'final', text, raw: json };
+    return { kind: 'final', text, truncated, usage, raw: json };
   }
-  return { kind: 'tool_calls', text, calls, assistantContent: content, raw: json };
+  return { kind: 'tool_calls', text, calls, truncated, usage, assistantContent: content, raw: json };
 }
 
 // Anthropic accepts the agent_turn-native {role, content} shape

package/providers/tool_use/claude_cli.mjs

@@ -25,6 +25,7 @@
 //     point at a deterministic shim script.
 
 import { spawn } from 'node:child_process';
+import { classifyCliExit } from '../cli_error.mjs';
 
 const DEFAULT_BIN = 'claude';
 const LAZYCLAW_TO_CLAUDE_TOOL = {
@@ -107,6 +108,11 @@ async function readUntilDone(proc) {
     let acc = '';
     let assistantFallback = '';
     let resultText = '';
+    // Per-turn usage rides the `assistant` event (the streaming `result` event
+    // reports zero tokens); cost rides the result event. Accumulate so the cost
+    // cap can account for this default subscription path.
+    const u = { input: 0, output: 0, cacheCreate: 0, cacheRead: 0, cost: 0, saw: false };
+    let truncated = false;   // a --max-turns cap hit (result subtype error_max_turns)
     proc.stdout.setEncoding('utf8');
     proc.stderr.setEncoding('utf8');
     proc.stdout.on('data', (chunk) => {
@@ -131,22 +137,80 @@ async function readUntilDone(proc) {
         if (obj?.type === 'result' && typeof obj.result === 'string') {
           resultText = obj.result;
         }
+        if (obj?.type === 'assistant' && obj?.message?.usage) {
+          const mu = obj.message.usage;
+          u.input += mu.input_tokens || 0;
+          u.output += mu.output_tokens || 0;
+          u.cacheCreate += mu.cache_creation_input_tokens || 0;
+          u.cacheRead += mu.cache_read_input_tokens || 0;
+          u.saw = true;
+        }
+        if (obj?.type === 'result' && Number.isFinite(obj.total_cost_usd)) u.cost = obj.total_cost_usd;
+        if (obj?.type === 'result' && obj.is_error && /max_turns/.test(String(obj.subtype || ''))) truncated = true;
       }
     });
     proc.stderr.on('data', (chunk) => { stderr += chunk; });
     proc.on('error', reject);
+    const buildUsage = () => ((u.saw || u.cost)
+      ? {
+          inputTokens: u.input, outputTokens: u.output,
+          cacheCreationInputTokens: u.cacheCreate, cacheReadInputTokens: u.cacheRead,
+          totalCostUsd: u.cost,
+        }
+      : null);
     proc.on('close', (code) => {
-      if (code !== 0) {
-        return reject(new ClaudeCliToolUseError(`claude CLI exit ${code}: ${stderr.slice(0, 300)}`, 'CLAUDE_CLI_EXIT', stderr));
+      // A --max-turns cap hit exits non-zero but is NOT a failure to surface as
+      // an error — return it as truncated so agent_turn stops cleanly with
+      // stoppedBy:'truncated' ("raise maxTokens") rather than a CLI exit error.
+      if (code !== 0 && !truncated) {
+        // Transient upstream throttle → retriable RATE_LIMIT; otherwise keep
+        // the non-retriable CLAUDE_CLI_EXIT code.
+        const cls = classifyCliExit(stderr);
+        const exitCode = cls.code === 'RATE_LIMIT' ? 'RATE_LIMIT' : 'CLAUDE_CLI_EXIT';
+        const err = new ClaudeCliToolUseError(`claude CLI exit ${code}: ${stderr.slice(0, 300)}`, exitCode, stderr);
+        if (cls.retryAfterMs !== undefined) err.retryAfterMs = cls.retryAfterMs;
+        return reject(err);
       }
       // Prefer accumulated stream deltas; fall back to the assistant
       // record or the final result text when streaming was disabled.
       const text = acc || assistantFallback || resultText || '';
-      resolve(text);
+      resolve({ text, usage: buildUsage(), truncated });
     });
   });
 }
 
+// Build the `claude` argv for the tool-use path. Runs LEAN by default —
+// single-sourced with providers/claude_cli.mjs's policy — so this path (agentic
+// chat / every mention-router team turn / the per-turn trainer calls) does NOT
+// re-load the user's CLAUDE.md/skills/hooks/MCP (~180k tokens/spawn, measured).
+// It previously omitted the lean flags, which is why the streaming provider's
+// lean fix didn't help these paths. Pass lean:false to restore the full env.
+export function buildToolUseArgs({ prompt, model, system, tools = [], permissionMode = 'bypassPermissions', lean, maxTurns } = {}) {
+  const args = [
+    '-p', prompt,
+    '--output-format', 'stream-json',
+    '--include-partial-messages',
+    '--verbose',
+    '--permission-mode', permissionMode,
+  ];
+  if (lean !== false) {
+    args.push('--setting-sources', '', '--strict-mcp-config');
+  }
+  // Bound Claude Code's internal autonomous loop. This adapter DOES let the
+  // agent use tools (--tools whitelist below), but the internal loop was
+  // otherwise uncapped (lazyclaw's own maxIterations is a no-op for claude-cli).
+  const cap = maxTurns == null ? 16 : maxTurns;
+  if (cap > 0) args.push('--max-turns', String(cap));
+  if (model) args.push('--model', model);
+  if (system && String(system).trim()) {
+    args.push('--system-prompt', String(system));
+  }
+  // Phase 19: pass the lazyclaw whitelist through to claude's --tools even when
+  // empty (an empty string explicitly disables every tool).
+  args.push('--tools', toClaudeTools(tools));
+  return args;
+}
+
 export async function callOnce({
   messages,
   tools = [],
@@ -158,6 +222,8 @@ export async function callOnce({
   signal,
   bin,
   cwd,
+  lean,
+  maxTurns,
   permissionMode = 'bypassPermissions',
 } = {}) {
   if (!Array.isArray(messages) || messages.length === 0) {
@@ -167,21 +233,7 @@ export async function callOnce({
   if (!prompt) {
     throw new ClaudeCliToolUseError('messages produced an empty prompt', 'NO_PROMPT');
   }
-  const args = [
-    '-p', prompt,
-    '--output-format', 'stream-json',
-    '--include-partial-messages',
-    '--verbose',
-    '--permission-mode', permissionMode,
-  ];
-  if (model) args.push('--model', model);
-  if (system && String(system).trim()) {
-    args.push('--system-prompt', String(system));
-  }
-  // Phase 19: pass the lazyclaw whitelist through to claude's --tools
-  // even when empty (an empty string explicitly disables every tool).
-  const toolsArg = toClaudeTools(tools);
-  args.push('--tools', toolsArg);
+  const args = buildToolUseArgs({ prompt, model, system, tools, permissionMode, lean, maxTurns });
 
   const binPath = bin || process.env.LAZYCLAW_CLAUDE_BIN || DEFAULT_BIN;
   let proc;
@@ -200,8 +252,8 @@ export async function callOnce({
   const onAbort = () => { try { proc.kill('SIGTERM'); } catch { /* gone */ } };
   if (signal) signal.addEventListener('abort', onAbort);
   try {
-    const text = await readUntilDone(proc);
-    return { kind: 'final', text, raw: null };
+    const { text, usage, truncated } = await readUntilDone(proc);
+    return { kind: 'final', text, usage, truncated, raw: null };
   } finally {
     if (signal) signal.removeEventListener('abort', onAbort);
   }

package/providers/tool_use/gemini.mjs

@@ -88,7 +88,7 @@ export async function callOnce({
   if (!apiKey) {
     throw new GeminiToolUseError('apiKey is required', 'NO_API_KEY');
   }
-  const m = model || 'gemini-2.5-flash';
+  const m = model || 'gemini-2.5-pro';
   const url = `${(baseUrl || DEFAULT_BASE).replace(/\/$/, '')}/models/${encodeURIComponent(m)}:generateContent`;
   const fetchFn = fetchImpl || globalThis.fetch;
 
@@ -137,15 +137,31 @@ export function parseResponse(json) {
     }
   }
   const text = textParts.join('');
+  // finishReason MAX_TOKENS = the turn was cut at the output ceiling; the text
+  // or functionCall args are partial. Flag it so the runner stops.
+  const fr = candidate?.finishReason;
+  const truncated = fr === 'MAX_TOKENS' || fr === 'SAFETY' || fr === 'RECITATION';
+  // Normalize token usage so agent_turn can accumulate spend across the loop
+  // (and team turns can feed the cost cap). null when the response omits it.
+  const um = json?.usageMetadata;
+  const usage = um
+    ? {
+        inputTokens: um.promptTokenCount || 0,
+        outputTokens: um.candidatesTokenCount || 0,
+        cacheReadInputTokens: um.cachedContentTokenCount || 0,
+      }
+    : null;
   if (calls.length === 0) {
-    return { kind: 'final', text, raw: json };
+    return { kind: 'final', text, truncated, usage, raw: json };
   }
   // assistantContent is the entire model turn so the runner can echo it
   // back into `contents` for the next request.
   return {
     kind: 'tool_calls',
     text,
+    truncated,
     calls,
+    usage,
     assistantContent: candidate?.content || { role: 'model', parts },
     raw: json,
   };

package/providers/tool_use/openai.mjs

@@ -18,6 +18,12 @@
 const DEFAULT_BASE = 'https://api.openai.com/v1';
 const DEFAULT_MAX_TOKENS = 4096;
 
+// OpenAI o-series reasoning models (o1/o3/o4...) reject `max_tokens` with
+// HTTP 400 'Unsupported parameter: max_tokens, use max_completion_tokens'.
+function isReasoningModel(model) {
+  return /^o\d/i.test(String(model || ''));
+}
+
 export class OpenAIToolUseError extends Error {
   constructor(message, code, body) {
     super(message);
@@ -71,8 +77,11 @@ export async function callOnce({
   const body = {
     model: model || 'gpt-4.1',
     messages: fullMessages,
-    max_tokens: maxTokens,
   };
+  // Reasoning models take max_completion_tokens; everything else takes
+  // max_tokens. Never emit both — the o-series rejects max_tokens.
+  if (isReasoningModel(body.model)) body.max_completion_tokens = maxTokens;
+  else body.max_tokens = maxTokens;
   if (tools && tools.length) body.tools = tools;
 
   const res = await fetchFn(url, {
@@ -98,20 +107,34 @@ export function parseResponse(json) {
   const msg = choice?.message || {};
   const rawToolCalls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
   const text = typeof msg.content === 'string' ? msg.content : '';
+  // finish_reason 'length' = the response was cut at the token ceiling, so the
+  // content or a tool_call's arguments JSON is partial. Flag it so the runner
+  // stops instead of acting on truncated output / empty-parsed args.
+  const truncated = choice?.finish_reason === 'length';
+  // Normalize token usage so agent_turn can accumulate spend across the loop
+  // (and team turns can feed the cost cap). null when the response omits it.
+  const usage = json?.usage
+    ? { inputTokens: json.usage.prompt_tokens || 0, outputTokens: json.usage.completion_tokens || 0 }
+    : null;
   if (rawToolCalls.length === 0) {
-    return { kind: 'final', text, raw: json };
+    return { kind: 'final', text, truncated, usage, raw: json };
   }
   const calls = rawToolCalls.map((tc) => {
     let input = {};
+    let parseError = null;
     const a = tc?.function?.arguments;
     if (typeof a === 'string') {
-      try { input = JSON.parse(a); } catch { input = {}; }
+      // Empty-string args mean "no arguments" → {}. A non-empty string that
+      // fails to parse is malformed: record the error so agent_turn surfaces a
+      // tool failure instead of silently running the tool with {}.
+      if (a.trim() === '') input = {};
+      else { try { input = JSON.parse(a); } catch (e) { input = {}; parseError = `malformed tool arguments: ${e.message}`; } }
     } else if (a && typeof a === 'object') {
       input = a;
     }
-    return { id: tc.id, name: tc?.function?.name, input };
+    return { id: tc.id, name: tc?.function?.name, input, ...(parseError ? { parseError } : {}) };
   });
-  return { kind: 'tool_calls', text, calls, assistantContent: msg, raw: json };
+  return { kind: 'tool_calls', text, calls, truncated, usage, assistantContent: msg, raw: json };
 }
 
 // OpenAI accepts the agent_turn-native {role, content} shape directly.

package/sandbox/confiners/seatbelt.mjs

@@ -3,12 +3,23 @@
 
 import { execFileSync } from 'node:child_process';
 
-export function available() {
-  if (process.platform !== 'darwin') return false;
-  try { execFileSync('sandbox-exec', ['-h'], { stdio: 'ignore' }); return true; }
+// Probe whether a usable `sandbox-exec` is present. The argument object is a
+// test seam: `platform` overrides the OS gate and `probe` overrides the real
+// invocation so the try/catch semantics are verifiable without a host sandbox.
+export function available({ platform = process.platform, probe = _realProbe } = {}) {
+  if (platform !== 'darwin') return false;
+  try { probe(); return true; }
   catch { return false; }
 }
 
+// Run a no-op (`/usr/bin/true`) under a permissive profile. This actually
+// exercises the sandboxing path. NOTE: `-h` is NOT a help flag on macOS — it is
+// an illegal option that exits non-zero, so the previous `sandbox-exec -h`
+// probe reported seatbelt unavailable on every mac.
+function _realProbe() {
+  execFileSync('sandbox-exec', ['-p', '(version 1)(allow default)', '/usr/bin/true'], { stdio: 'ignore' });
+}
+
 // Escape a path for an SBPL double-quoted string literal. Without this a path
 // containing `"` (or a backslash) could close the string and inject arbitrary
 // SBPL directives — e.g. re-enabling `(allow network*)` or widening file
@@ -25,20 +36,34 @@ function sbplPath(p) {
   return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
 
+// Temp dirs are always writable — interpreters and tools need scratch space, and
+// confining writes to the workspace alone breaks too much (e.g. node/npm caches).
+const TMP_WRITABLE = ['/tmp', '/private/tmp', '/private/var/folders'];
+
+// Build a FILESYSTEM-CONFINEMENT profile, not a strict deny-default one. A
+// `(deny default)` profile silently kills dynamically-linked binaries (python3,
+// node, git) at the dyld/mach bootstrap stage on modern macOS — confinement that
+// breaks every real interpreter is worse than none. Instead we start from
+// `(allow default)` and carve out the high-value protections: writes are denied
+// everywhere except the workspace + temp, and named secret dirs stay unreadable
+// even though reads are otherwise allowed. Network is allowed unless opts.allowNet
+// is explicitly false.
+//
+//   opts.readWrite : string[]  workspace roots that may be written (default [cwd])
+//   opts.denyRead  : string[]  dirs whose reads are blocked (e.g. ~/.ssh, ~/.aws)
+//   opts.allowNet  : boolean   default false → adds (deny network*)
 export function buildArgv(argv, opts = {}) {
-  const readOnly = opts.readOnly || [];
   const readWrite = opts.readWrite || [process.cwd()];
+  const denyRead = opts.denyRead || [];
   const allowNet = opts.allowNet === true;
+  const writable = [...TMP_WRITABLE, ...readWrite];
   const profile = [
     '(version 1)',
-    '(deny default)',
-    '(allow process-fork)',
-    '(allow process-exec)',
-    '(allow signal)',
-    '(allow sysctl-read)',
-    allowNet ? '(allow network*)' : '(deny network*)',
-    ...readOnly.map(p => `(allow file-read* (subpath "${sbplPath(p)}"))`),
-    ...readWrite.map(p => `(allow file-read* file-write* (subpath "${sbplPath(p)}"))`),
+    '(allow default)',
+    '(deny file-write*)',
+    `(allow file-write* ${writable.map(p => `(subpath "${sbplPath(p)}")`).join(' ')})`,
+    ...denyRead.map(p => `(deny file-read* (subpath "${sbplPath(p)}"))`),
+    ...(allowNet ? [] : ['(deny network*)']),
   ].join('\n');
   return ['sandbox-exec', '-p', profile, ...argv];
 }

package/sandbox/index.mjs

@@ -16,6 +16,8 @@
 //     bindings:     { '<workerName>': '<kind>' | { kind, ...overrides } },
 //   }
 
+import os from 'node:os';
+import path from 'node:path';
 import { SANDBOX_KINDS, SandboxError } from './base.mjs';
 import { LocalSandbox } from './local.mjs';
 import { DockerSandbox, parseSandboxSpec } from './docker.mjs';
@@ -65,3 +67,50 @@ export function resolveSandbox(cfg, workerName) {
   };
   return new CTORS[kind](spec);
 }
+
+// Directories whose reads are blocked inside a confined child even though reads
+// are otherwise allowed — credential stores + the lazyclaw config dir (which
+// holds auth profiles and channel tokens).
+function defaultDenyRead(homeDir, configDir) {
+  const h = homeDir || os.homedir();
+  const dirs = [
+    path.join(h, '.ssh'),
+    path.join(h, '.aws'),
+    path.join(h, '.gnupg'),
+    path.join(h, '.config', 'gcloud'),
+    path.join(h, '.docker'),
+    path.join(h, '.kube'),
+    path.join(h, '.npmrc'),
+    path.join(h, '.netrc'),
+  ];
+  if (configDir) dirs.push(configDir);
+  return dirs;
+}
+
+// Build the flat sandbox spec applied BY DEFAULT to sensitive tool execution
+// (the tool hot path: bash, python_exec/node_exec, git_*, os_*). Returns null to
+// mean "no confinement" (bare host).
+//
+// Default-on policy (operator-chosen): confine every sensitive child-spawning
+// tool, with the filesystem confined to the workspace (cwd) + temp, secret dirs
+// unreadable, and network ALLOWED. Opt out with cfg.sandbox.confine === false or
+// cfg.sandbox.default of 'off'/'none'. An explicitly-configured docker backend
+// is honoured instead of local confinement.
+//
+// This is threaded in by the production entrypoints (task tick, agentic chat,
+// task_spawn); the library defaults of runTool/runAgentTurn stay null so direct
+// API callers and unit tests remain byte-stable.
+export function defaultSandboxSpec(cfg, { cwd, configDir } = {}) {
+  const sb = (cfg && cfg.sandbox) || {};
+  if (sb.confine === false || sb.default === 'off' || sb.default === 'none') return null;
+  if (sb.default === 'docker' && sb.docker && sb.docker.image) {
+    return { kind: 'docker', ...sb.docker };
+  }
+  return {
+    kind: 'local',
+    confiner: sb.local?.confiner || 'auto',
+    readWrite: [cwd || process.cwd()],
+    denyRead: defaultDenyRead(sb.homeDir, configDir),
+    allowNet: sb.allowNet !== false,
+  };
+}

package/sandbox/local.mjs

@@ -3,6 +3,7 @@
 
 import { spawn, spawnSync } from 'node:child_process';
 import { Sandbox, SandboxSession, SandboxError } from './base.mjs';
+import { pickAvailableConfiner } from './spawn.mjs';
 import * as seatbelt from './confiners/seatbelt.mjs';
 import * as bubblewrap from './confiners/bubblewrap.mjs';
 import * as firejail from './confiners/firejail.mjs';
@@ -45,7 +46,12 @@ class LocalSession extends SandboxSession {
 export class LocalSandbox extends Sandbox {
   constructor(spec) {
     super(spec);
-    const key = spec.confiner || 'none';
+    // Resolve 'auto' to a concrete confiner (or none) at construction so
+    // _wrap() never sees 'auto' and the genuinely-unknown-key guard below
+    // still fires for typos. 'auto' that resolves to 'none' → no wrapping.
+    const key = spec.confiner === 'auto'
+      ? pickAvailableConfiner()
+      : (spec.confiner || 'none');
     if (key !== 'none' && !(key in CONFINERS)) {
       throw new SandboxError(`unknown confiner "${key}"`, 'SANDBOX_BAD_CONFINER');
     }