@cat-factory/executor-harness 1.134.0 → 1.135.0

package/dist/pi-workspace.js

@@ -132,6 +132,80 @@ export async function checkoutHasBlueprints(dir, multiRepo) {
     const checks = await Promise.all(legs.filter((e) => e.isDirectory()).map((e) => isBlueprintDir(join(dir, e.name))));
     return checks.some(Boolean);
 }
+/**
+ * Run one pass on a SUBSCRIPTION harness (Claude Code / Codex): the leased-credential path, which
+ * shares only the checkout preparation with the Pi one.
+ *
+ * Split out of {@link runAgentInWorkspace} for its cyclomatic budget. It is also the honest seam:
+ * everything here is a decision about what the vendor's own CLI is handed, while everything left
+ * behind is about the proxy-backed Pi run.
+ */
+async function runSubscriptionInWorkspace(harness, spec, opts, prepared) {
+    const { contextFiles, imageGuidance, workspaceProbe } = prepared;
+    // Ambient (native) mode authenticates with the developer's own CLI login, so no
+    // leased token is required; otherwise the leased subscription token is mandatory.
+    if (!spec.ambientAuth && !spec.subscriptionToken) {
+        throw new Error(`The ${harness} harness requires a subscription token`);
+    }
+    const subOutcome = await runSubscriptionHarness(harness, {
+        cwd: spec.dir,
+        model: spec.model,
+        systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${imageGuidance}`,
+        userPrompt: spec.userPrompt,
+        ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
+        subscriptionBaseUrl: spec.subscriptionBaseUrl,
+        ...(spec.ambientAuth ? { ambientAuth: true } : {}),
+        ...(spec.skills?.length ? { skills: spec.skills } : {}),
+        ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
+        // Codex's own image tool. Passed for both subscription harnesses because the option lives on
+        // the shared run options; `runClaudeCode` ignores it, since claude-code has no such tool and
+        // (unlike an MCP server) there is nothing to report as unservable — the backend never
+        // resolves a codex-served generator onto a claude-code step, because admission refuses it.
+        ...(spec.generateImages ? { generateImages: true } : {}),
+        // `spec.webSearchProxy` is deliberately NOT forwarded. It states whether OUR PROXY serves web
+        // research for this run's account, which is what Pi's tools ride and what they would fail
+        // without; neither subscription CLI touches that proxy. Claude Code's `WebSearch`/`WebFetch`
+        // are served by the vendor the leased subscription already pays and are declared
+        // unconditionally (see `CLAUDE_TOOL_SET`), and Codex's surface is per-tool config rather than
+        // a list. Passing the proxy's availability here would withhold working tools on the strength
+        // of an unrelated deployment's wiring.
+        ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
+        signal: opts.signal,
+        // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
+        // defaults merged loosen-only with the kind's tuning + the backend's complexity-scaled
+        // no-edit allowance, so a claude-code run that stops making progress is killed early
+        // instead of burning the full wall-clock budget. The claude runner consumes it; codex
+        // ignores it for now (its stream isn't wired to the guard).
+        guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
+        expectsEdits: spec.expectsEdits ?? true,
+        // What the guard's no-edit bound actually decides on (see `buildWorkspaceProbe`).
+        workspaceProbe,
+        onActivity: opts.onActivity,
+        onProgress: opts.onProgress,
+        // The run's tool-call trajectory, the same hook the Pi path feeds — so a subscription run
+        // and a proxied one produce the same evidence rather than one of them producing none.
+        onSpan: opts.onSpan,
+        // The tool-silence window (stuck-run audit F13), opened by whichever CLI actually runs.
+        // Wired for BOTH subscription harnesses: each reports tool activity on its own stream, so
+        // each can beat the window it opens.
+        beginToolWindow: opts.beginToolWindow,
+        // Per-slice review capture, so a parallel review's finished slices are persisted as they
+        // land rather than only in the terminal output. Only the subscription runners fan work out
+        // across subagents, so this is the only path that can produce it.
+        onSliceReviews: opts.onSliceReviews,
+        // What the CLI reported about the tool servers it loaded. Wired for BOTH subscription
+        // harnesses even though only claude-code's stream carries the report today: the hook is a
+        // pass-through, and a codex run that never calls it leaves the backend's record honestly
+        // absent rather than claiming every server it wired failed to start.
+        onToolServers: opts.onToolServers,
+        // Stream this run's per-call telemetry to the job's live drain. The subscription
+        // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
+        // proxy as they happen), so this is the only path that needs the hook.
+        onCallMetric: opts.onCallMetric,
+        ...(opts.log ? { log: opts.log } : {}),
+    });
+    return withEffortReport(spec.dir, subOutcome);
+}
 /**
  * Write Pi's global agent context (`~/.pi/agent/AGENTS.md`) + provider config,
  * then run Pi once in `spec.dir` and return its summary/stats/stderr. The context
@@ -181,67 +255,15 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // bootstrap) has no HEAD to read; the probe then rides on the dirty-tree half alone, which is
     // the half that matters there anyway.
     const workspaceProbe = await buildWorkspaceProbe(spec, opts.signal);
-    // Subscription harnesses (Claude Code / Codex) authenticate with the leased
-    // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
-    // system prompt is passed straight to the CLI; everything around this (clone,
-    // push, watchdogs) is unchanged.
+    // Subscription harnesses (Claude Code / Codex) authenticate with the leased token and talk
+    // direct to the vendor: no proxy config, no AGENTS.md. The system prompt is passed straight to
+    // the CLI; everything around this (clone, push, watchdogs) is unchanged.
     if (spec.harness === 'claude-code' || spec.harness === 'codex') {
-        // Ambient (native) mode authenticates with the developer's own CLI login, so no
-        // leased token is required; otherwise the leased subscription token is mandatory.
-        if (!spec.ambientAuth && !spec.subscriptionToken) {
-            throw new Error(`The ${spec.harness} harness requires a subscription token`);
-        }
-        const subOutcome = await runSubscriptionHarness(spec.harness, {
-            cwd: spec.dir,
-            model: spec.model,
-            systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${imageGuidance}`,
-            userPrompt: spec.userPrompt,
-            ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
-            subscriptionBaseUrl: spec.subscriptionBaseUrl,
-            ...(spec.ambientAuth ? { ambientAuth: true } : {}),
-            ...(spec.skills?.length ? { skills: spec.skills } : {}),
-            ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
-            // Codex's own image tool. Passed for both subscription harnesses because the option lives on
-            // the shared run options; `runClaudeCode` ignores it, since claude-code has no such tool and
-            // (unlike an MCP server) there is nothing to report as unservable — the backend never
-            // resolves a codex-served generator onto a claude-code step, because admission refuses it.
-            ...(spec.generateImages ? { generateImages: true } : {}),
-            ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
-            signal: opts.signal,
-            // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
-            // defaults merged loosen-only with the kind's tuning + the backend's complexity-scaled
-            // no-edit allowance, so a claude-code run that stops making progress is killed early
-            // instead of burning the full wall-clock budget. The claude runner consumes it; codex
-            // ignores it for now (its stream isn't wired to the guard).
-            guardLimits: mergeGuardLimits(progressGuardLimitsFromEnv(), spec.guardLimits),
-            expectsEdits: spec.expectsEdits ?? true,
-            // What the guard's no-edit bound actually decides on (see `buildWorkspaceProbe`).
+        return await runSubscriptionInWorkspace(spec.harness, spec, opts, {
+            contextFiles,
+            imageGuidance,
             workspaceProbe,
-            onActivity: opts.onActivity,
-            onProgress: opts.onProgress,
-            // The run's tool-call trajectory, the same hook the Pi path feeds — so a subscription run
-            // and a proxied one produce the same evidence rather than one of them producing none.
-            onSpan: opts.onSpan,
-            // The tool-silence window (stuck-run audit F13), opened by whichever CLI actually runs.
-            // Wired for BOTH subscription harnesses: each reports tool activity on its own stream, so
-            // each can beat the window it opens.
-            beginToolWindow: opts.beginToolWindow,
-            // Per-slice review capture, so a parallel review's finished slices are persisted as they
-            // land rather than only in the terminal output. Only the subscription runners fan work out
-            // across subagents, so this is the only path that can produce it.
-            onSliceReviews: opts.onSliceReviews,
-            // What the CLI reported about the tool servers it loaded. Wired for BOTH subscription
-            // harnesses even though only claude-code's stream carries the report today: the hook is a
-            // pass-through, and a codex run that never calls it leaves the backend's record honestly
-            // absent rather than claiming every server it wired failed to start.
-            onToolServers: opts.onToolServers,
-            // Stream this run's per-call telemetry to the job's live drain. The subscription
-            // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
-            // proxy as they happen), so this is the only path that needs the hook.
-            onCallMetric: opts.onCallMetric,
-            ...(opts.log ? { log: opts.log } : {}),
         });
-        return withEffortReport(spec.dir, subOutcome);
     }
     if (!spec.proxyBaseUrl || !spec.sessionToken) {
         throw new Error('The Pi harness requires proxyBaseUrl and sessionToken');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.134.0",
+  "version": "1.135.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",

package/src/agent-capabilities.ts

@@ -519,70 +519,44 @@ export function claudeMcpConfig(servers: McpServerSpec[]): {
   return { mcpServers }
 }
 
-/**
- * The claude-code CLI's own tools, named so an `--allowedTools` list can never take them away.
- *
- * An allow-list is whole-session: it does not scope itself to MCP just because every entry we
- * generate happens to be an `mcp__*` pattern. So the moment one tool server narrows its tools, the
- * list has to re-grant the agent's built-in file/bash/search tools or the run is handed a narrowed
- * MCP surface AND no way to read, edit or build anything.
- *
- * Bias this list toward OVER-inclusion. A name the CLI does not have is inert; a name it has and
- * this list lacks is a tool silently removed from a run — which surfaces as an agent that cannot
- * do its work, far from the registration that caused it. Historical/renamed spellings are kept for
- * the same reason: the harness image is pinned per workspace, so one image faces several CLI
- * versions. When the CLI gains a tool, add it here.
- */
-export const CLAUDE_BUILT_IN_TOOLS: readonly string[] = [
-  'Agent',
-  'Bash',
-  'BashOutput',
-  'Edit',
-  'ExitPlanMode',
-  'Glob',
-  'Grep',
-  'KillBash',
-  'KillShell',
-  'ListMcpResources',
-  'MultiEdit',
-  'NotebookEdit',
-  'NotebookRead',
-  'Read',
-  'ReadMcpResource',
-  'SlashCommand',
-  'Skill',
-  'Task',
-  'TaskCreate',
-  'TaskUpdate',
-  'TodoWrite',
-  'WebFetch',
-  'WebSearch',
-  'Write',
-]
-
 /**
  * The tool-name list for `--allowedTools`: every declared server's tools in the CLI's
- * `mcp__<server>__<tool>` convention, PLUS {@link CLAUDE_BUILT_IN_TOOLS}. A server with no
- * restriction contributes the whole-server pattern, so an allow-list stays one entry per server.
+ * `mcp__<server>__<tool>` convention, PLUS the built-in tools this run declared with `--tools`
+ * (`CLAUDE_TOOL_SET`). A server with no restriction contributes the whole-server pattern, so
+ * an allow-list stays one entry per server.
  *
  * Returns undefined when NO server restricts its tools — there is then nothing to narrow, and the
  * safest list is the one we never send.
  *
+ * An allow-list is whole-session, not MCP-scoped: it does not confine itself to MCP just because
+ * every entry we generate happens to be an `mcp__*` pattern. So the moment one tool server narrows
+ * its tools, the list has to carry the built-in file/bash/search tools too or the run is handed a
+ * narrowed MCP surface AND no way to read, edit or build anything.
+ *
+ * And carrying them is not merely a re-grant. MEASURED against CLI 2.1.245, the list is ADDITIVE:
+ * `--allowedTools "Bash,Grep"` yields the CLI's default set PLUS `Glob` and `Grep`, and an EMPTY
+ * list yields the default set plus `Glob`, `Grep` and the four `Task*` tools. A name here UNLOCKS
+ * a tool. That is why `builtIns` is the run's OWN declared set passed by reference rather than a
+ * constant re-read here: a separately-derived list would silently re-grant exactly what the
+ * `--tools` declaration withheld, and only on the runs that happen to wire a narrowing tool
+ * server.
+ *
  * Whether the CLI ENFORCES this list is permission-mode dependent and not a contract we control:
  * the run uses `--permission-mode bypassPermissions` (the container is the sandbox and no human is
- * there to approve a call), under which an allow-list grants rather than gates. So this is written
- * to be correct under BOTH readings — if the list gates, the narrowing is real and the built-ins
- * survive it; if it is inert, sending it costs nothing. The always-present channel is the PROMPT,
- * which states each server's permitted tool names on every harness. Treat `allowedTools` as
- * scoping, not as a security boundary: a server the agent must not reach fully should not be
- * wired for that kind at all.
+ * there to approve a call), under which an allow-list grants rather than gates. The always-present
+ * channel is the PROMPT, which states each server's permitted tool names on every harness. Treat
+ * `allowedTools` as scoping, not as a security boundary: a server the agent must not reach fully
+ * should not be wired for that kind at all.
  */
-export function claudeAllowedToolPatterns(servers: McpServerSpec[]): string[] | undefined {
+export function claudeAllowedToolPatterns(
+  servers: McpServerSpec[],
+  builtIns: readonly string[],
+): string[] | undefined {
   if (!servers.some((s) => s.allowedTools?.length)) return undefined
   const mcp = servers.flatMap((s) =>
     s.allowedTools?.length ? s.allowedTools.map((t) => `mcp__${s.id}__${t}`) : [`mcp__${s.id}`],
   )
-  return [...mcp, ...CLAUDE_BUILT_IN_TOOLS]
+  return [...mcp, ...builtIns]
 }
 
 /** Escape a string as a TOML basic string (Codex config is TOML, not JSON). */

package/src/agent-runner.ts

@@ -1,7 +1,5 @@
 import { spawn } from 'node:child_process'
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { join } from 'node:path'
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js'
 import { claudeUsage, unaccountedUsageCall } from './usage-attribution.js'
 import {
@@ -25,14 +23,12 @@ import {
 } from './pi.js'
 import type { PiRunStats } from './pi-reduction.js'
 import {
-  claudeAllowedToolPatterns,
-  mcpServerSecretValues,
   observeClaudeMcpInit,
-  writeClaudeMcpConfig,
   type McpServerSpec,
   type ObservedMcpServer,
   type SkillSpec,
 } from './agent-capabilities.js'
+import { openClaudeRunHome } from './claude-home.js'
 import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js'
 import type { ProgressGuardLimits } from './progress-guard.js'
 import { createClaudeProgressGuard } from './guard-driver.js'
@@ -42,7 +38,7 @@ import { killChildProcess, spawnDetached } from './process.js'
 import { agentChildEnv } from './agent-env.js'
 import { abortReasonOf } from './failure.js'
 import { describeProcessExit } from './process-exit.js'
-import { redact, registerKnownSecrets, secretsToRedact } from './redact.js'
+import { redact, secretsToRedact } from './redact.js'
 import { createSliceTracker, startSubagentWatcher, type SliceReview } from './subagents.js'
 import {
   createTaskPlanTracker,
@@ -52,8 +48,7 @@ import {
   toProgress,
   todosToProgress,
 } from './progress.js'
-import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
-import { retainSessionTranscripts } from './transcript-retention.js'
+import { assertClaudeToolsCurrent, claudeCliArgs, CLAUDE_TOOL_SET } from './claude-cli.js'
 
 // The alternate (subscription) harness runners. The Pi harness reaches models
 // through the LLM proxy with a model-locked session token; the Claude Code and
@@ -481,82 +476,6 @@ export function carryClaudeSystemPrompt(
 // Claude Code
 // ---------------------------------------------------------------------------
 
-/**
- * Run the Claude Code CLI headlessly against `opts.cwd`, authenticated with the
- * leased subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN), talking direct to
- * api.anthropic.com. Streams `--output-format stream-json`, mapping the
- * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
- * onto the summary + usage.
- */
-/**
- * Write a repo-sourced skill as a NATIVE Claude Code skill under `<skillsRoot>/<name>/`: a
- * `SKILL.md` (YAML frontmatter `name`/`description` + the instructions body, the format the CLI
- * expects) plus every resource file at its path within the skill directory. Resource sub-paths
- * were sanitized at the job boundary (no traversal), so nested dirs are created as needed.
- *
- * The frontmatter `name`/`description` values are emitted as JSON-encoded (double-quoted) YAML
- * scalars, not bare plain scalars: an author's description routinely contains `: ` (colon-space)
- * or a leading YAML indicator (`#`, `-`, `[`, `{`, `"`, …), which is invalid as a plain scalar and
- * would make the CLI fail to parse the frontmatter and silently skip the skill. A JSON string is a
- * valid YAML double-quoted scalar, so quoting makes the manifest robust to arbitrary text.
- */
-async function writeNativeSkill(skillsRoot: string, skill: SkillSpec): Promise<void> {
-  const dir = join(skillsRoot, skill.name)
-  await mkdir(dir, { recursive: true })
-  const name = JSON.stringify(skill.name)
-  const description = JSON.stringify(skill.description.replace(/\r?\n/g, ' '))
-  const frontmatter = `---\nname: ${name}\ndescription: ${description}\n---\n`
-  await writeFile(join(dir, 'SKILL.md'), `${frontmatter}\n${skill.instructions}\n`, 'utf8')
-  for (const resource of skill.resources) {
-    const dest = join(dir, resource.relPath)
-    await mkdir(dirname(dest), { recursive: true })
-    await writeFile(dest, resource.content, 'utf8')
-  }
-}
-
-/**
- * Prepare the Claude Code CLI's MCP wiring for one run: write the servers to a PER-RUN config and
- * return the argv that points the CLI at it, plus the cleanup for a directory we had to mint.
- *
- * Two decisions live here. `--strict-mcp-config` makes that file the ONLY source of servers, so an
- * ambient run on a developer's own machine can never silently hand the agent their personal ones.
- * And `--allowedTools` is passed ONLY when a server actually narrows its tools — an allow-list is
- * whole-session, not MCP-scoped, so `claudeAllowedToolPatterns` re-grants the CLI's built-in
- * file/bash tools in the same list; see it for why that holds whichever way the run's permission
- * mode treats an allow-list.
- *
- * The config carries this job's resolved credentials, so it goes in the isolated config home when
- * we own one and a throwaway per-JOB directory otherwise — never the checkout (it would land in a
- * commit) and never a shared HOME path (a concurrent job would clobber it).
- */
-async function setUpClaudeMcp(
-  servers: McpServerSpec[] | undefined,
-  configHome: string | undefined,
-): Promise<{ args: string[]; cleanup: () => Promise<void> }> {
-  const noop = { args: [], cleanup: async () => {} }
-  if (!servers?.length) return noop
-  // Before anything can spawn: a failing MCP server echoes its own argv/headers into stderr, and
-  // that tail is carried onto the step's diagnostics.
-  registerKnownSecrets(mcpServerSecretValues(servers))
-  const home = configHome ?? (await mkdtemp(join(tmpdir(), 'cf-claude-mcp-')))
-  const owned = home === configHome ? undefined : home
-  const cleanup = async (): Promise<void> => {
-    if (owned) await rm(owned, { recursive: true, force: true }).catch(() => {})
-  }
-  const configPath = await writeClaudeMcpConfig(home, servers)
-  if (!configPath) return { args: [], cleanup }
-  const allowedTools = claudeAllowedToolPatterns(servers)
-  return {
-    args: [
-      '--mcp-config',
-      configPath,
-      '--strict-mcp-config',
-      ...(allowedTools?.length ? ['--allowedTools', allowedTools.join(',')] : []),
-    ],
-    cleanup,
-  }
-}
-
 /**
  * The LIVE publishers of a claude-code run: everything the stream has revealed so far that the
  * backend should see before the run ends, rather than only in its terminal result.
@@ -736,6 +655,13 @@ function openClaudeCallCapture(
   }
 }
 
+/**
+ * Run the Claude Code CLI headlessly against `opts.cwd`, authenticated with the
+ * leased subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN), talking direct to
+ * api.anthropic.com. Streams `--output-format stream-json`, mapping the
+ * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
+ * onto the summary + usage.
+ */
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -754,6 +680,10 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     })
   }
 
+  // The built-in tools this run declares, named ONCE: the same list rides `--tools` and the
+  // `--allowedTools` re-grant, which is additive rather than inert (see `claudeAllowedToolPatterns`).
+  const tools = CLAUDE_TOOL_SET
+
   const secrets = opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : []
   const capture = openClaudeCallCapture(opts, { prompt, folded, secrets })
   const telemetry = capture.telemetry
@@ -798,6 +728,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   const onEvent = (event: Record<string, unknown>, meta?: { final?: boolean }): void => {
     const type = event.type
     reportToolServerStartup(event, opts.onToolServers)
+    // The same startup event answers what the CLI granted of what we asked for; a capability it
+    // named no tool for is a silent capability loss otherwise (see `assertClaudeToolsCurrent`).
+    assertClaudeToolsCurrent(event, tools, opts.log)
     // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
     // `telemetry` routes them off the parent's chain (and decides who bills them). Progress, slice
     // tracking, the guard and `stats` below deliberately see EVERY event: a subagent grinding on
@@ -853,7 +786,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     }
   }
 
-  const home = await openClaudeRunHome(opts)
+  const home = await openClaudeRunHome(opts, tools)
   const { configHome } = home
 
   // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
@@ -887,22 +820,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     const { stderrTail } = await streamCli(
       {
         command: 'claude',
-        args: [
-          '-p',
-          '--output-format',
-          'stream-json',
-          '--verbose',
-          // The per-run container IS the sandbox, and the run is fully headless (no one
-          // to approve a tool call) — so bypass permissions entirely. `acceptEdits`
-          // would auto-accept file edits but still gate Bash, which in `-p` mode is then
-          // denied, leaving the agent unable to run builds/tests/git to verify its work.
-          '--permission-mode',
-          'bypassPermissions',
-          '--model',
-          opts.model,
-          ...home.mcpArgs,
-          ...appendArgs,
-        ],
+        args: claudeCliArgs({ model: opts.model, tools, mcpArgs: home.mcpArgs, appendArgs }),
       },
       prompt,
       { ...opts, signal: runSignal },
@@ -959,118 +877,6 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   }
 }
 
-/**
- * The isolated, per-run home the `claude` CLI runs against: a temp config dir OUTSIDE the cloned
- * checkout, pre-seeded past the first-launch prompts, carrying the run's native skills and MCP
- * config, plus the child env pointing the CLI at it. {@link ClaudeRunHome.dispose} is the other
- * half of the same concern — the leased credential must never outlive the run — so acquisition
- * and teardown are defined together rather than split across a `finally` forty lines away.
- *
- * Ambient (native) mode has NO home: the developer's installed CLI uses its own `~/.claude`
- * login, so nothing is created, nothing is pre-seeded, and `dispose` only clears the MCP config.
- */
-interface ClaudeRunHome {
-  /** The per-run config dir; `undefined` in ambient mode (the developer's own login is used). */
-  configHome: string | undefined
-  /** The CLI argv selecting the run's tool servers; empty when it has none. */
-  mcpArgs: string[]
-  /** The child-process env (see {@link buildClaudeEnv}). */
-  env: Record<string, string>
-  dispose: () => Promise<void>
-}
-
-async function openClaudeRunHome(opts: SubscriptionRunOptions): Promise<ClaudeRunHome> {
-  // Native (ambient) mode: run the developer's installed `claude` with its OWN login —
-  // no isolated config home, no injected credential, no onboarding pre-seed. Otherwise,
-  // Claude Code persists user config/credentials under its config dir; point that at an
-  // isolated, per-run temp dir OUTSIDE the cloned checkout (`opts.cwd`). Otherwise the
-  // agents that finish with `git add -A` (blueprint/requirements/bootstrap) could stage a
-  // stray `.claude/` directory — and any cached credential in it — into the pushed branch.
-  // Mirrors the Codex CODEX_HOME isolation below; removed by `dispose`.
-  if (!opts.ambientAuth && !opts.subscriptionToken) {
-    throw new Error('claude-code harness requires a subscription token (or ambientAuth)')
-  }
-  const configHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-claude-'))
-
-  // The config dir is brand-new every run, so Claude Code would otherwise treat this
-  // as a first launch and BLOCK on the interactive onboarding / "trust this folder" /
-  // bypass-permissions acknowledgement prompts — which never get answered headlessly,
-  // hanging the job until the watchdog kills it. Pre-seed the config that marks those
-  // as already accepted so `-p` starts straight into the run. Best-effort: written
-  // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
-  // (Ambient mode skips this — the developer's own config is already onboarded.)
-  // ADR 0026 D4: assert the pinned onboarding keys landed and log them with the CLI
-  // version, so a future first-run gate this set doesn't cover (which looks identical to
-  // a healthy-but-quiet subagent start) is diffable when the cold-start watchdog fires.
-  if (configHome) {
-    await writeOnboardingPreseed(configHome)
-    await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log)
-  }
-
-  // Skills: install each as a native skill under the config dir's `skills/<name>/` so the CLI
-  // discovers and can invoke it. ONLY into the isolated per-run config home — never the
-  // developer's own `~/.claude` (ambient/native mode), where it would persist in their personal
-  // setup after the run and two concurrent jobs carrying same-named skills would clobber each
-  // other. An ambient run reads the skills from the checkout instead (`.cat-context/skill/<name>/`,
-  // materialised by the caller). Best-effort: a write failure must not wedge the run — the prompt
-  // still names the skills.
-  if (configHome) {
-    for (const skill of opts.skills ?? []) {
-      await writeNativeSkill(join(configHome, 'skills'), skill).catch(() => {})
-    }
-  }
-
-  // Tool servers (MCP): the CLI is pointed at a per-run config rather than discovering an ambient
-  // one. See `setUpClaudeMcp` for why that matters and what has to be cleaned up afterwards.
-  const mcp = await setUpClaudeMcp(opts.mcpServers, configHome)
-
-  return {
-    configHome,
-    mcpArgs: mcp.args,
-    env: buildClaudeEnv(opts, configHome),
-    dispose: async () => {
-      // The ambient-mode MCP config dir (credential-bearing) never outlives the run.
-      await mcp.cleanup()
-      if (!configHome) return
-      // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
-      // home is deleted — the credential lives at the home root, never in `projects/`, so this
-      // keeps the debugging artifact without leaking the token. Best-effort; never throws.
-      await retainSessionTranscripts(configHome, ['projects'], {
-        label: 'claude-code',
-        ...(opts.log ? { log: opts.log } : {}),
-      })
-      // Never leave the config dir (and any cached credential) on disk past the run.
-      await rm(configHome, { recursive: true, force: true }).catch(() => {})
-    },
-  }
-}
-
-/**
- * Build the child-process env for the `claude` CLI: an isolated config home plus subscription
- * auth (Anthropic OAuth token, or an Anthropic-compatible base URL + auth token for a
- * non-Anthropic Claude-Code vendor like GLM/Kimi/DeepSeek), or an empty env in ambient mode
- * (the developer's own logged-in `~/.claude` is used). Extracted from {@link runClaudeCode} to
- * keep its cyclomatic complexity down; behaviour is a straight move of the original expression.
- */
-function buildClaudeEnv(
-  opts: SubscriptionRunOptions,
-  configHome: string | undefined,
-): Record<string, string> {
-  // The job-scoped env rides along in BOTH modes; the credential/config vars below are what
-  // ambient mode drops (the developer's own logged-in `~/.claude` is used instead).
-  if (opts.ambientAuth) return { ...opts.extraEnv }
-  return {
-    ...opts.extraEnv,
-    CLAUDE_CONFIG_DIR: configHome!,
-    ...(opts.subscriptionBaseUrl
-      ? {
-          ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
-          ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken!,
-        }
-      : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
-  }
-}
-
 /**
  * Merge the parent-loop telemetry with the subagents' out-of-band usage + per-call metrics into
  * the run outcome. INVARIANT (do not "fix" this into a double count): the run total is the parent
@@ -1257,6 +1063,12 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
           'exec',
           '--json',
           '--skip-git-repo-check',
+          // No `--tools` analogue here, and its absence is a FINDING rather than an oversight:
+          // codex has no flag that declares a built-in tool set, because it has no set to choose
+          // from. Its surface is shell + apply_patch + the plan tool, and the optional extras are
+          // individual `CODEX_HOME/config.toml` switches the harness already sets deliberately
+          // (`[features] image_generation`, see `codex-home.ts`). So there is nothing here that
+          // silently drifts with a CLI version the way claude-code's headless default did.
           // The per-run container IS the sandbox; let Codex write files and reach the
           // vendor unrestricted, with no approval prompts (the run is headless).
           '--dangerously-bypass-approvals-and-sandbox',

package/src/agent-shared.ts

@@ -18,11 +18,18 @@ export function mergeEffort(
 }
 
 /**
- * The agent-capability fields (skills, tool servers, reference designs) every agent-running flow
- * forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow
- * cannot silently be the one that drops a kind's declared playbook, tool server or reference
- * gallery: the failure mode is invisible (the agent simply works without it) and would only show
- * up as degraded output.
+ * The agent-capability fields (skills, tool servers, reference designs, web research) every
+ * agent-running flow forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow
+ * spread, so a flow cannot silently be the one that drops a kind's declared playbook, tool server,
+ * reference gallery or web access: the failure mode is invisible (the agent simply works without
+ * it) and would only show up as degraded output.
+ *
+ * Web research joined the helper after the conflict-resolver and bootstrap flows were found to be
+ * forwarding neither half of it: both build their own spec literal, and the two web fields were
+ * hand-written at the four sites that remembered them. That is exactly the drift this helper
+ * exists to make unrepresentable, so they are read here rather than at each call site. Both halves
+ * travel together on purpose: the guidance NAMES the tools, so a flow carrying one without the
+ * other either describes tools the run was never given or hands it tools nothing introduced.
  */
 export function agentCapabilities(job: AgentJob): {
   skills?: SkillSpec[]
@@ -30,6 +37,8 @@ export function agentCapabilities(job: AgentJob): {
   generateImages?: boolean
   referenceScreenshots?: ImageManifestSpec
   designImages?: ImageManifestSpec
+  webSearchProxy?: boolean
+  webToolsGuidance?: string
 } {
   return {
     ...(job.skills?.length ? { skills: job.skills } : {}),
@@ -37,5 +46,7 @@ export function agentCapabilities(job: AgentJob): {
     ...(job.generateImages ? { generateImages: true } : {}),
     ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
     ...(job.designImages ? { designImages: job.designImages } : {}),
+    ...(job.webSearch ? { webSearchProxy: true } : {}),
+    ...(job.webToolsGuidance ? { webToolsGuidance: job.webToolsGuidance } : {}),
   }
 }

package/src/agent.ts

@@ -495,8 +495,6 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
             // Read-only: it inspects and reports, making no edits — so the no-progress
             // guard's no-edit bound must not fire on its legitimately edit-free run.
             expectsEdits: false,
-            webToolsGuidance: job.webToolsGuidance,
-            webSearchProxy: job.webSearch,
             contextFiles: job.contextFiles,
             guardLimits: job.guardLimits,
             ...agentCapabilities(job),
@@ -746,8 +744,6 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
         sessionToken: job.sessionToken,
         // Read-only: no edits expected, so the no-progress guard's no-edit bound must not fire.
         expectsEdits: false,
-        webToolsGuidance: job.webToolsGuidance,
-        webSearchProxy: job.webSearch,
         ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
         guardLimits: job.guardLimits,
         ...agentCapabilities(job),
@@ -868,8 +864,6 @@ export function buildSingleRepoCodingSpec(
     proxyPhasePath: job.proxyPhasePath,
     sessionToken: job.sessionToken,
     commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
-    webToolsGuidance: job.webToolsGuidance,
-    webSearchProxy: job.webSearch,
     guardLimits: job.guardLimits,
     ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
     ...(job.streamFollowUps ? { streamFollowUps: true } : {}),