@cat-factory/executor-harness 1.134.0 → 1.135.0

package/src/claude-cli.ts

@@ -0,0 +1,217 @@
+import type { Logger } from './logger.js'
+
+// ---------------------------------------------------------------------------
+// The Claude Code CLI's INVOCATION surface: which of its built-in tools a run asks for, the argv
+// that asks, and the read-back that says what the CLI actually granted.
+//
+// The three belong together because they are one decision seen from three sides. Before this
+// module the harness declared nothing and took whatever the CLI's headless default happened to
+// be, which drifted across CLI versions: 2.1.226 offered the plan tools, 2.1.245 did not, and
+// nothing in the run said so. Both halves of that default were wrong for a disposable container:
+// no `Grep`/`Glob` (so every search went through `Bash` and counted against the progress guard's
+// no-edit budget), no plan tools (so `step.progress` had no signal to lift), and a dozen tools
+// (`CronCreate`, `DesignSync`, `EnterWorktree`, `ScheduleWakeup`, `SendMessage`, `Workflow`,
+// `ReportFindings`, …) an agent in a per-run container can act on none of.
+//
+// Declaring a set therefore has to be measured against the default it replaces, not just against
+// the issue that asked for it: everything the default carried and a container CAN use has to be
+// asked for by name, or the declaration is itself a capability loss. That is what `Monitor` and
+// the web tools are doing in the list below.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every built-in tool a run asks the CLI for, and the ONE value that rides both `--tools` and the
+ * `--allowedTools` re-grant.
+ *
+ * One value rather than two derived ones, because the allow-list turned out to be ADDITIVE rather
+ * than inert: a name in it is UNLOCKED, not merely re-permitted (measured: `--allowedTools
+ * "Bash,Grep"` yields the default set PLUS `Glob` and `Grep`). Two independently-computed lists
+ * would therefore not merely disagree, they would silently re-grant what the other withheld.
+ *
+ * Deliberately OVER-inclusive, and safe to be, because a name the build does not have is dropped
+ * silently rather than refused. The cost is one-directional: a name the CLI HAS and this list
+ * LACKS is a capability silently removed from every run. So the list is measured against the
+ * headless default it replaces, not only against what was wanted, and when the CLI gains a tool a
+ * container agent can use, it is added here.
+ *
+ * A name 2.1.246 does not serve is kept for one of two measured reasons, and they are different
+ * facts worth keeping apart (each probed alone, reading the `init` event's own `tools` array):
+ *
+ *  - ALIASED onto a successor, so the old spelling still buys the capability: `BashOutput` grants
+ *    `TaskOutput`, `KillBash` and `KillShell` both grant `TaskStop`, `Agent` grants `Task`.
+ *  - DROPPED outright (`ListMcpResources`, `ReadMcpResource`, `MultiEdit`, `NotebookRead`,
+ *    `TodoWrite`), and kept only because the harness image is pinned per workspace, so one build
+ *    of this source faces several CLI versions and an older one still serves them.
+ *
+ * The second category is why the CURRENT spelling has to be listed beside the old one rather than
+ * instead of it: `ListMcpResources`/`ReadMcpResource` were carried alone, and since neither is an
+ * alias, every tool-server run reached its resources through nothing at all.
+ *
+ * `WebSearch`/`WebFetch` are unconditional, which is a deliberate reversal of the first cut of this
+ * module. They were gated on the job's `webSearch` flag, which states whether OUR PROXY can serve
+ * web research for the run's account (see `resolveWebSearchAvailability`, whose whole rationale is
+ * that Pi's proxy-backed tools "would just fail/return nothing" without a key). The CLI's web tools
+ * are not proxy-backed: the vendor the leased subscription already pays serves them, and they work
+ * on a deployment with no search provider wired at all. Gating them on that flag therefore withheld
+ * a WORKING capability on the strength of an unrelated fact, which is the opposite of the
+ * pass-through an unwired capability owes. The flag that would legitimately withhold them is a
+ * per-run "may this run reach the web" POLICY, which this platform does not have today; when it
+ * gains one, it gates here and on the Pi path together.
+ */
+export const CLAUDE_TOOL_SET: readonly string[] = [
+  'Agent',
+  'Bash',
+  'BashOutput',
+  'Edit',
+  'Glob',
+  'Grep',
+  'KillBash',
+  'KillShell',
+  'ListMcpResources',
+  'ListMcpResourcesTool',
+  // Waits on the background shells `Bash(run_in_background)` starts. A tool in its own right
+  // (measured: `Monitor` grants `Monitor`), not an alias of the retired kill/output pair, and it
+  // is in the headless default, so omitting it was this declaration's own capability loss.
+  'Monitor',
+  'MultiEdit',
+  'NotebookEdit',
+  'NotebookRead',
+  'Read',
+  'ReadMcpResource',
+  'ReadMcpResourceTool',
+  'Skill',
+  'Task',
+  'TaskCreate',
+  'TaskGet',
+  'TaskList',
+  'TaskOutput',
+  'TaskStop',
+  'TaskUpdate',
+  'TodoWrite',
+  // Loads the schemas of tools a build defers rather than declaring up front. Dropped by 2.1.246
+  // (measured, with and without a tool server wired), and asked for anyway under the
+  // over-inclusive rule: a run wiring several tool servers is exactly the shape a build that
+  // defers tool schemas would hand one to.
+  'ToolSearch',
+  'WebFetch',
+  'WebSearch',
+  'Write',
+]
+
+/**
+ * One capability the run genuinely cannot do without, and every CLI spelling that satisfies it.
+ *
+ * The floor is expressed as CAPABILITIES rather than as names because {@link CLAUDE_TOOL_SET}
+ * is over-inclusive on purpose: a literal "warn on anything requested but absent" would fire on
+ * every single run for the alternate spellings this image carries for other CLI versions, and a
+ * warning that is always on is one nobody reads. A capability with no granted spelling is the
+ * fact worth a line: it means an upstream rename or removal took a tool out of every run of this
+ * image, which otherwise surfaces days later as an agent behaving oddly.
+ */
+interface ClaudeToolCapability {
+  capability: string
+  spellings: readonly string[]
+}
+
+const CLAUDE_TOOL_FLOOR: readonly ClaudeToolCapability[] = [
+  { capability: 'shell', spellings: ['Bash'] },
+  { capability: 'read', spellings: ['Read'] },
+  { capability: 'write', spellings: ['Write'] },
+  { capability: 'edit', spellings: ['Edit', 'MultiEdit'] },
+  { capability: 'search', spellings: ['Grep'] },
+  { capability: 'glob', spellings: ['Glob'] },
+  { capability: 'subagents', spellings: ['Task', 'Agent'] },
+  // The plan signal the harness lifts into `step.subtasks` / `step.progress`, in the two
+  // vocabularies the CLI has used for it (see `progress.ts`, which reads both).
+  { capability: 'plan', spellings: ['TaskCreate', 'TodoWrite'] },
+]
+
+/** The floor, exported so a test can assert every spelling is one this harness actually asks for. */
+export const CLAUDE_TOOL_CAPABILITIES: readonly ClaudeToolCapability[] = CLAUDE_TOOL_FLOOR
+
+/**
+ * The `claude` argv for one run, in the order the CLI's variadic flags require.
+ *
+ * `--tools` and `--allowedTools` are both declared `<tools...>`, so each swallows any trailing
+ * POSITIONAL argument as another tool name; only a following `--flag` terminates them. The prompt
+ * therefore stays on stdin (see `streamCli`) and every flag here is placed before the variadic
+ * pair or introduced by its own `--`, so a new flag cannot be eaten by the one in front of it.
+ */
+export function claudeCliArgs(opts: {
+  model: string
+  /** The built-in tools this run asks for; see {@link CLAUDE_TOOL_SET}. */
+  tools: readonly string[]
+  /** `--mcp-config` + `--strict-mcp-config` + any `--allowedTools`; empty when no server is wired. */
+  mcpArgs: readonly string[]
+  /** `--append-system-prompt <prompt>`, or empty when the prompt was folded into stdin. */
+  appendArgs: readonly string[]
+}): string[] {
+  return [
+    '-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,
+    // Declared rather than defaulted: see this module's header for what the default set costs.
+    '--tools',
+    opts.tools.join(','),
+    ...opts.mcpArgs,
+    ...opts.appendArgs,
+  ]
+}
+
+/**
+ * Read the CLI's startup report (`{"type":"system","subtype":"init"}`) back against what this run
+ * asked for, and say when a required capability is missing.
+ *
+ * The same pairing, and for the same reason, as `assertOnboardingKeysCurrent`: the CLI is the only
+ * one who knows what it granted, it says so exactly once before the first model call, and pairing
+ * that answer with the CLI version is what makes an upstream rename diffable instead of a mystery.
+ * The version comes off the event itself (`claude_code_version`) rather than an env var the image
+ * would have to remember to bake.
+ *
+ * Best-effort and never throws: a run whose tool surface is short is still a run, and the honest
+ * disposition for a floor this image cannot verify is to SAY it could not be read, not to fail the
+ * job and not to stay silent (which reads exactly like a satisfied request).
+ */
+export function assertClaudeToolsCurrent(
+  event: Record<string, unknown>,
+  requested: readonly string[],
+  log: Logger | undefined,
+): void {
+  if (!log || event.type !== 'system' || event.subtype !== 'init') return
+  const version =
+    typeof event.claude_code_version === 'string' ? event.claude_code_version : undefined
+  const cliVersion = version ? { cliVersion: version } : {}
+  if (!Array.isArray(event.tools)) {
+    log.warn('claude-code announced no tool list, so this run has an unverified tool surface', {
+      requestedTools: [...requested],
+      ...cliVersion,
+    })
+    return
+  }
+  const granted = new Set(event.tools.filter((t): t is string => typeof t === 'string'))
+  const missing = CLAUDE_TOOL_FLOOR.filter((c) => !c.spellings.some((s) => granted.has(s))).map(
+    (c) => c.capability,
+  )
+  const fields = {
+    requestedTools: [...requested],
+    grantedTools: [...granted].sort(),
+    ...cliVersion,
+  }
+  if (missing.length > 0) {
+    log.warn('claude-code granted no tool for a capability this run requires', {
+      ...fields,
+      missingCapabilities: missing,
+    })
+    return
+  }
+  log.info('claude-code tool set granted', fields)
+}

package/src/claude-home.ts

@@ -0,0 +1,233 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import {
+  claudeAllowedToolPatterns,
+  mcpServerSecretValues,
+  writeClaudeMcpConfig,
+  type McpServerSpec,
+  type SkillSpec,
+} from './agent-capabilities.js'
+import type { Logger } from './logger.js'
+import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
+import { registerKnownSecrets } from './redact.js'
+import { retainSessionTranscripts } from './transcript-retention.js'
+
+// ---------------------------------------------------------------------------
+// The PER-RUN Claude Code config home: everything written for one claude-code job and torn down
+// with it — the isolated `CLAUDE_CONFIG_DIR`, its onboarding pre-seed, the run's native skills,
+// its MCP config, and the child env that points the CLI at all of it.
+//
+// The sibling of `codex-home.ts`, extracted from `runClaudeCode` for the same reason: the run
+// loop's own job is streaming and reducing the CLI's events, while this is a directory with a
+// lifecycle that holds a credential.
+//
+// CRITICAL, and why it is a temp dir rather than anything under the checkout: several handlers
+// finish with `git add -A` + push, so a `.claude/` directory inside `opts.cwd` would publish any
+// cached credential to the PR branch.
+// ---------------------------------------------------------------------------
+
+/** What one claude-code job needs written into its own home. */
+export interface ClaudeHomeOptions {
+  /** The decrypted subscription OAuth token. Required unless `ambientAuth`. */
+  subscriptionToken?: string
+  /**
+   * Anthropic-compatible base URL for a non-Anthropic Claude-Code vendor (GLM/Kimi): present ⇒
+   * ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN, absent ⇒ CLAUDE_CODE_OAUTH_TOKEN.
+   */
+  subscriptionBaseUrl?: string
+  /** Run the developer's own CLI login instead: no isolated home, nothing installed. */
+  ambientAuth?: boolean
+  /** Skills to install natively under `<configHome>/skills/<name>/`. */
+  skills?: SkillSpec[]
+  /** Tool servers to scope to this job's config. */
+  mcpServers?: McpServerSpec[]
+  /** Job-scoped child env (tester secrets, a private-registry npmrc pointer). */
+  extraEnv?: Record<string, string>
+  log?: Logger
+}
+
+/**
+ * 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 it carries `builtIns`, the SAME list this run declared with
+ * `--tools`, in the same entry; see `claudeAllowedToolPatterns` for why that list is threaded in
+ * rather than re-derived, and how 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,
+  builtIns: readonly string[],
+): 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, builtIns)
+  return {
+    args: [
+      '--mcp-config',
+      configPath,
+      '--strict-mcp-config',
+      ...(allowedTools?.length ? ['--allowedTools', allowedTools.join(',')] : []),
+    ],
+    cleanup,
+  }
+}
+
+/**
+ * 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.
+ */
+export 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>
+}
+
+export async function openClaudeRunHome(
+  opts: ClaudeHomeOptions,
+  tools: readonly string[],
+): 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 (`codex-home.ts`); 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, tools)
+
+  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: ClaudeHomeOptions,
+  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! }),
+  }
+}

package/src/multi-repo-coding.ts

@@ -23,6 +23,7 @@ import { runAgentInWorkspace, withWorkspace } from './pi-workspace.js'
 import type { RunOptions } from './runner.js'
 import { log, type Logger } from './logger.js'
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js'
+import { agentCapabilities } from './agent-shared.js'
 import {
   resolvePrTemplateNote,
   withPrTemplateNote,
@@ -201,16 +202,13 @@ export async function runMultiRepoCoding(
           proxyBaseUrl: job.proxyBaseUrl,
           proxyPhasePath: job.proxyPhasePath,
           sessionToken: job.sessionToken,
-          webToolsGuidance: job.webToolsGuidance,
-          webSearchProxy: job.webSearch,
           guardLimits: job.guardLimits,
           ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
-          // Skills + tool servers apply to a multi-repo run exactly as to a single-repo one: they
-          // are properties of the AGENT KIND, not of the checkout layout.
-          ...(job.skills?.length ? { skills: job.skills } : {}),
-          ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
-          ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
-          ...(job.designImages ? { designImages: job.designImages } : {}),
+          // Skills, tool servers and web research apply to a multi-repo run exactly as to a
+          // single-repo one: they are properties of the AGENT KIND, not of the checkout layout.
+          // Through the shared helper rather than re-spread here, which is what let this flow
+          // drift from the single-repo one in the first place.
+          ...agentCapabilities(job),
           multiRepo: true,
           // What the no-progress guard's working-tree bound decides on: see {@link probeDirsForLegs}.
           repoDirs: probeDirsForLegs(legs),

package/src/pi-workspace.ts

@@ -308,6 +308,90 @@ export async function checkoutHasBlueprints(dir: string, multiRepo: boolean): Pr
   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: 'claude-code' | 'codex',
+  spec: AgentRunSpec,
+  opts: RunOptions,
+  prepared: {
+    contextFiles: ContextFileInfo[]
+    imageGuidance: string
+    workspaceProbe: WorkspaceProbe
+  },
+): Promise<PiRunOutcome> {
+  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
@@ -362,67 +446,15 @@ export async function runAgentInWorkspace(
   // 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')