@cat-factory/executor-harness 1.134.0 → 1.137.0

package/README.md

@@ -116,6 +116,51 @@ Bootstrap differs at the ends: it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a
 PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 
+### The environment is probed once, not by the agent
+
+Before any mode branches, `handleAgent` probes the machine it is about to run on and appends an
+`ENVIRONMENT INVENTORY` block to the job's system prompt (`src/environment-inventory.ts`). It names
+the toolchain that answered and its versions, the curated list of tools that did not, and whether a
+Docker DAEMON is actually reachable.
+
+It exists because the platform used to ask every agent to find this out for itself, and every agent
+did: in one measured run an architect ran `for c in docker kubectl helm kustomize; …` and then
+`docker info`, and the coder it handed off to rediscovered both answers thirty calls later. Four
+calls out of a forty-call budget for facts this process holds before the agent's first turn. The
+backend cannot hold them (it composes its prompt before a transport is chosen, and the same body
+reaches this image, a deployment's own image variant and, under `LOCAL_NATIVE_AGENTS`, the
+developer's own machine), so it states the POLICY and names no tooling at all.
+
+Three rules bind anything added to it:
+
+- **A failed probe is not an absence.** Only `ENOENT` means "not installed"; a timeout or a refused
+  spawn renders on its own line as could-not-be-determined, because the two lead an agent to
+  opposite next moves.
+- **An unlisted tool is unknown too**, which the block's last line says. The probe list is curated,
+  so silence about `terraform` must not read as its absence.
+- **The Docker daemon is answered by running `docker info`**, never by finding the CLI. The CLI is
+  installed in this image unconditionally, `entrypoint.sh` starts the rootless daemon best-effort
+  and execs the server without waiting for it, so at job start this probe is the only thing that
+  knows how that went.
+- **A daemon that is STARTING is not a daemon that is absent.** Because the entrypoint does not
+  wait, the backend dispatches seconds before there is a socket, and `docker info` is then refused
+  at once rather than slowly. So a refusal is read against `DOCKER_HOST`, which the entrypoint sets
+  whenever something is meant to serve a daemon here: unset means nothing was coming and the
+  absence is stated definitively, set means one short retry and then could-not-be-determined. The
+  absent wording tells an agent `docker compose up` "will fail here whatever the CLI reports", which
+  is a prohibition, so it may only be reached where nothing is going to answer.
+- **A tool the platform did not provide is not installable system-wide either**, since the job runs
+  unprivileged. The line says that instead of banning installation outright: `pnpm` is absent from
+  this image (only the UI variant carries it), so it is routinely the package manager the job's own
+  repository declares, and a flat prohibition pushed agents onto `npm install` against a pnpm
+  lockfile. Reaching a project's own manager for that project alone is allowed and named.
+
+Composed at exactly ONE point, onto the job's own `systemPrompt`, which every mode already forwards
+and all three CLIs already carry (claude-code's `--append-system-prompt` and its oversized-argv
+fallback, Codex's fold, Pi's `AGENTS.md`). `test/environment-inventory.coverage.test.ts` pins that:
+a mode that folded its own copy would state the machine twice, and one that folded none would leave
+its agent probing, with nothing failing either way.
+
 ### The work-branch push is CHECKPOINTED, so it is lease-guarded
 
 Step 8's push is not the run's first: every `JOB_CHECKPOINT_INTERVAL_MS` (60s) the harness pushes
@@ -377,6 +422,8 @@ verdict is stated.
 | `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
 | `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc; the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
 | `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`): talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
+| `src/claude-cli.ts` | The claude-code CLI's INVOCATION surface: the built-in tools a run DECLARES with `--tools` (the CLI's headless default has no `Grep`/`Glob` and no plan tools, and does carry a dozen an ephemeral container can act on none of), the argv that declares them, and the read-back of the CLI's `init` event that warns when a required capability was granted no tool. The list is over-inclusive on purpose, which `--tools` makes safe: an unknown name is dropped silently and a RETIRED one is an alias onto its successor, so one pinned image can face several CLI versions. The web tools are unconditional, being served by the vendor the leased subscription pays rather than by this deployment's search proxy. The same list also rides the `--allowedTools` re-grant, which is ADDITIVE rather than inert, so the two are one value threaded rather than two lists. |
+| `src/claude-home.ts` | The PER-RUN claude-code config home (`codex-home.ts`'s sibling): the isolated `CLAUDE_CONFIG_DIR` outside the checkout, its onboarding pre-seed, the run's natively-installed skills, its `--mcp-config`, the child env carrying the leased credential, and the teardown that lifts the session transcripts out before deleting it. |
 | `src/claude-call-aggregator.ts` | Folds Claude Code's per-CONTENT-BLOCK `stream-json` envelopes back into the model calls they belong to (by `message.id`), reconstructs each call's request transcript, and routes subagent turns off the parent's chain. **Exported as the `./claude-call-aggregator` subpath and driven by the BACKEND too** (`runtimes/local`, for an inline step running on the developer's host `claude`), so it stays the ONE implementation: the per-envelope over-count it fixes inflated a measured 1.47M tokens to 5.53M, and both drivers have to learn that only once. That second driver is why the transcript is retained only to `MAX_TRANSCRIPT_CHARS` (stating what it stopped retaining) and why assembling bodies at all is a `bodies` switch: in a container the reconstruction is one job's memory in a box sized for it, in the backend it is per concurrent inline step in the orchestrator process. Unlike the compile-only `./embed`, this subpath is a `dist` import, which is why the package emits declarations, and why a consumer's typecheck depends on Turbo's `^build` edge having built this package first (see `tsconfig.json`'s `comment:buildOrder`). |
 | `src/usage-attribution.ts` | Reconciles a subscription CLI's TWO token channels: the per-turn usage its stream narrates and the cumulative total its terminal event reports. They disagree routinely and in one direction (Claude Code's per-turn `output_tokens` is the message-START snapshot, single digits), so whatever the turns did not account for becomes ONE extra metric standing for the job (`standsForJob`, filed with a null turn index) rather than tokens grafted onto a real turn, which would make a derived number read as a measured one. Reconciled against the PARENT loop's calls alone, since the terminal cumulative covers only that conversation. |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
@@ -391,6 +438,7 @@ verdict is stated.
 | `src/bootstrap-mode.ts` | The repo-bootstrap MODE: clone-a-reference-or-scaffold → run the agent → refuse to push an empty tree → reinit + force-push to the pre-created target repo. |
 | `src/artifact-upload.ts` | The OUTBOUND half of the artifact seam: parses the body's `artifactUpload` and projects it onto the agent's env as `ARTIFACT_UPLOAD_URL` / `ARTIFACT_UPLOAD_TOKEN`, registering the token for redaction first. Passes through what the body carries and decides nothing: which kinds get the seam is the backend's call. |
 | `src/codex-images.ts` | Codex's own `image_gen` output, staged where the agent can reach it: creates `$CODEX_HOME/generated_images` as a symlink into `.cat-context/binary-output/generated/` before the CLI starts, sweeps anything a failed redirect left behind, and unlinks (never follows) the redirect at teardown — a failed unlink is REPORTED, because that unlink is what stops the recursive delete reaching the checkout. Exists because codex exposes no path for what it generated AND `$CODEX_HOME` holds the run's decrypted credential, so neither asking the agent nor sending it there is available. |
+| `src/environment-inventory.ts` | What the MACHINE holds, probed once per job and appended to the agent's system prompt as an ENVIRONMENT INVENTORY block. The only layer that can state it: the backend composes its prompt before a transport is chosen, and the same body serves this image, a deployment's own variant and the developer's laptop under `LOCAL_NATIVE_AGENTS`. Three-valued on purpose, so a probe that failed renders as unknown rather than as an absence, and the Docker DAEMON is answered by running `docker info` rather than by finding the CLI, which is installed here either way. See [The environment is probed once, not by the agent](#the-environment-is-probed-once-not-by-the-agent). |
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 | `src/docker-status.ts` | This container's own verdict about its Docker daemon, as recorded by `entrypoint.sh`. Three-valued on purpose: a daemon that FAILED and a daemon nobody asked about are different facts, and only a DECIDED absence refuses a stand-up. See [Local infra: the container's Docker daemon](#local-infra-the-containers-docker-daemon). |

package/dist/agent-capabilities.d.ts

@@ -173,39 +173,36 @@ export declare function parseMcpServerSpecs(value: unknown): McpServerSpec[] | u
 export declare function claudeMcpConfig(servers: McpServerSpec[]): {
     mcpServers: Record<string, Record<string, unknown>>;
 };
-/**
- * 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 declare const CLAUDE_BUILT_IN_TOOLS: readonly string[];
 /**
  * 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 declare function claudeAllowedToolPatterns(servers: McpServerSpec[]): string[] | undefined;
+export declare function claudeAllowedToolPatterns(servers: McpServerSpec[], builtIns: readonly string[]): string[] | undefined;
 /**
  * The `[mcp_servers.<id>]` TOML block Codex reads from its `CODEX_HOME/config.toml`. Codex's MCP
  * client is stdio-only, so an `http` server is skipped here.

package/dist/agent-capabilities.js

@@ -418,68 +418,40 @@ export function claudeMcpConfig(servers) {
     }
     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 = [
-    '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) {
+export function claudeAllowedToolPatterns(servers, builtIns) {
     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). */
 function tomlString(value) {

package/dist/agent-runner.d.ts

@@ -161,6 +161,13 @@ export declare function carryClaudeSystemPrompt(systemPrompt: string, userPrompt
     prompt: string;
     folded: boolean;
 };
+/**
+ * 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 declare function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome>;
 /**
  * Run the Codex CLI headlessly against `opts.cwd`, authenticated with the leased

package/dist/agent-runner.js

@@ -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 { createClaudeRunTelemetry, subagentDispatchId, } from './claude-call-aggregator.js';
@@ -9,7 +7,8 @@ import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js'
 import { log } from './logger.js';
 import { NO_TOOL_WINDOW } from './tool-silence.js';
 import { publishCallMetric, } from './pi.js';
-import { claudeAllowedToolPatterns, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
+import { observeClaudeMcpInit, } from './agent-capabilities.js';
+import { openClaudeRunHome } from './claude-home.js';
 import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js';
 import { createClaudeProgressGuard } from './guard-driver.js';
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js';
@@ -17,11 +16,10 @@ 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 } from './subagents.js';
 import { createTaskPlanTracker, mergeProgress, normalizeStatus, pickProgress, 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';
 /**
  * Drive one CLI subprocess to completion, streaming LF-framed JSONL from stdout
  * through `onEvent`. Mirrors `runPi`'s lifecycle: prompt over stdin (out-of-band,
@@ -256,80 +254,6 @@ export function carryClaudeSystemPrompt(systemPrompt, userPrompt) {
 // ---------------------------------------------------------------------------
 // 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, skill) {
-    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, configHome) {
-    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 () => {
-        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.
@@ -475,6 +399,13 @@ function openClaudeCallCapture(opts, stream) {
         },
     };
 }
+/**
+ * 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) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -491,6 +422,9 @@ export async function runClaudeCode(opts) {
             bytes: Buffer.byteLength(opts.systemPrompt, 'utf8'),
         });
     }
+    // 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;
@@ -532,6 +466,9 @@ export async function runClaudeCode(opts) {
     const onEvent = (event, meta) => {
         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
@@ -593,7 +530,7 @@ export async function runClaudeCode(opts) {
             terminalReport = claudeResultReport(event) || terminalReport;
         }
     };
-    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
     // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
@@ -623,22 +560,7 @@ export async function runClaudeCode(opts) {
     try {
         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 }, home.env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // The stream has ended, so the last call has no successor envelope to complete it.
         telemetry.flush();
@@ -687,91 +609,6 @@ export async function runClaudeCode(opts) {
         await home.dispose();
     }
 }
-async function openClaudeRunHome(opts) {
-    // 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, configHome) {
-    // 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
@@ -924,6 +761,12 @@ export async function runCodex(opts) {
                 '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/dist/agent-shared.d.ts

@@ -7,11 +7,18 @@ import type { EffortReport } from './effort.js';
  */
 export declare function mergeEffort(result: AgentResult, effortReport: EffortReport | undefined): AgentResult;
 /**
- * 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 declare function agentCapabilities(job: AgentJob): {
     skills?: SkillSpec[];
@@ -19,4 +26,6 @@ export declare function agentCapabilities(job: AgentJob): {
     generateImages?: boolean;
     referenceScreenshots?: ImageManifestSpec;
     designImages?: ImageManifestSpec;
+    webSearchProxy?: boolean;
+    webToolsGuidance?: string;
 };

package/dist/agent-shared.js

@@ -10,11 +10,18 @@ export function mergeEffort(result, effortReport) {
     return effortReport ? { ...result, effortReport } : result;
 }
 /**
- * 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) {
     return {
@@ -23,5 +30,7 @@ export function agentCapabilities(job) {
         ...(job.generateImages ? { generateImages: true } : {}),
         ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
         ...(job.designImages ? { designImages: job.designImages } : {}),
+        ...(job.webSearch ? { webSearchProxy: true } : {}),
+        ...(job.webToolsGuidance ? { webToolsGuidance: job.webToolsGuidance } : {}),
     };
 }