@cat-factory/executor-harness 1.64.4 → 1.68.0

package/README.md

@@ -88,6 +88,36 @@ 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.
 
+### Skills and tool servers
+
+A job body may carry `skills[]` (procedural playbooks) and `mcpServers[]` (MCP tool servers) — the
+harness MATERIALISES both and decides nothing about them; the backend has already resolved which
+apply and dropped what this harness cannot serve (see
+[`backend/docs/adr/0029-agent-kind-capabilities.md`](../../docs/adr/0029-agent-kind-capabilities.md)).
+
+- **Skills** install natively under `CLAUDE_CONFIG_DIR/skills/<name>/` for a leased-credential
+  claude-code run (the CLI discovers and invokes them), and under
+  `.cat-context/skill/<name>/` in the checkout for Pi, Codex, and an AMBIENT claude-code run —
+  whose prompt carries the instructions instead, because there is no isolated config home to
+  install into and the runner refuses to write into the developer's own `~/.claude`.
+- **Tool servers** become a per-run `--mcp-config` file plus `--strict-mcp-config` for claude-code
+  (so an ambient run never picks up the developer's personal servers), and `[mcp_servers.*]` blocks
+  in the per-run `CODEX_HOME/config.toml` for Codex — stdio only, and skipped entirely under
+  ambient auth, which has no per-run home to write into. `--allowedTools` is passed ONLY when a
+  server actually narrows its tools, and then carries the CLI's built-in tool names alongside the
+  `mcp__*` patterns — an allow-list is whole-session, not MCP-scoped, so a bare list of MCP
+  patterns would leave the agent unable to read, edit or build anything. Whether the CLI gates on
+  that list at all is permission-mode dependent, so treat the narrowing as scoping rather than
+  enforcement; the prompt states it either way.
+- **An `http` tool server must be `https`, or loopback.** Its headers carry a resolved credential,
+  so the job boundary refuses a cleartext off-box URL (the backend refuses the same at
+  registration). `secretKeys` names which `env`/`headers` entries are credentials, so exactly those
+  values are registered for redaction — scrubbing the whole map would turn ordinary config strings
+  into `***` in every later log line.
+
+Both config files carry this job's resolved credentials, so they are written to a per-job directory
+(mode `0600`) and never into the checkout or a HOME-global path — see the next section.
+
 ## Per-job state: never a process- or HOME-global
 
 A job's staging state (the tester's secrets, private-registry auth, a repo-sourced Claude
@@ -153,6 +183,9 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/captured-command.ts` | The one way the harness runs a declared shell command on its own behalf: `sh -c` with a per-command watchdog, abort handling, conventional exit codes (124/127/130) and a scrub-then-bound output capture. Shared by both pre-PR verification phases so a fix to one cannot miss the other. |
 | `src/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic — keyed off the job body, never the agent kind. |
 | `src/reproduction-proof.ts` | Bugfix reproduction proof: runs the job's declared reproduction command against two symmetric fresh worktrees (the pre-fix tree and the final tree) and computes red-then-green from the exit codes, with a repair loop that never fails the run. Generic — keyed off the job body, never the agent kind. |
+| `src/agent-capabilities.ts` | The agent CAPABILITIES a job body carries — the run's `skills` (a `SKILL.md` payload + resources) and its `mcpServers` (tool servers) — with their defensive parsing and the per-CLI config writers (`--mcp-config` JSON for claude-code, `[mcp_servers.*]` TOML for Codex). Backend-authored data the harness only MATERIALISES: adding a skill or a tool server is a backend registration, never a harness change. |
+| `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/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 
 ## Runner lifecycle knobs

package/dist/agent-capabilities.js

@@ -0,0 +1,354 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * The credential values carried by a run's tool servers, for {@link registerKnownSecrets}. An MCP
+ * server that fails to start routinely echoes its own argv or request headers into stderr, and
+ * that tail reaches the step's diagnostics — so these have to be scrubbed exactly like the leased
+ * subscription token. Only the keys the backend MARKED as secret are read (see `secretKeys`).
+ */
+export function mcpServerSecretValues(servers) {
+    const values = [];
+    for (const server of servers) {
+        for (const key of server.secretKeys ?? []) {
+            const value = server.env?.[key] ?? server.headers?.[key];
+            if (value)
+                values.push(value);
+        }
+    }
+    return values;
+}
+// ---------------------------------------------------------------------------
+// Parsing (the job-body boundary)
+// ---------------------------------------------------------------------------
+/**
+ * Sanitize a skill resource's relative path: keep the subdirectory structure (so
+ * `templates/report.md` materialises nested) but reject anything that could escape the skill
+ * directory — absolute paths, `..` traversal, backslashes, empty/dot segments. Returns undefined
+ * for an unsafe path (the resource is then dropped).
+ */
+function sanitizeSkillRelPath(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const segments = value.replace(/\\/g, '/').split('/');
+    const clean = [];
+    for (const seg of segments) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            return undefined;
+        // Same character class as a context-file name, per segment.
+        const c = seg.replace(/[^A-Za-z0-9._-]/g, '');
+        if (!c || c === '.' || c === '..' || c.startsWith('.'))
+            return undefined;
+        clean.push(c);
+    }
+    return clean.length ? clean.join('/') : undefined;
+}
+/**
+ * Fallback native-skill directory name when the authored name has no id-safe characters (e.g. a
+ * purely non-ASCII skill name). The name is only a path segment / manifest label, so a safe
+ * default keeps the skill installable rather than dropping it — which, on the claude-code path,
+ * would leave the prompt pointing at a skill that was never installed (a blind run).
+ */
+const FALLBACK_SKILL_NAME = 'skill';
+/** A skill's own directory name, sanitized to a safe single path segment (undefined if empty). */
+function sanitizeSkillName(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const base = value.replace(/\\/g, '/').split('/').pop() ?? '';
+    const cleaned = base.replace(/[^A-Za-z0-9._-]/g, '');
+    if (!cleaned || cleaned === '.' || cleaned === '..' || cleaned.startsWith('.'))
+        return undefined;
+    return cleaned;
+}
+/** Validate one entry of the `skills` field, or undefined when malformed. */
+function parseSkillSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    const instructions = typeof o.instructions === 'string' ? o.instructions : undefined;
+    // No instructions ⇒ there is nothing to run — drop the skill (the prompt still carries the
+    // folded-in directive on the Pi/codex path). An unsafe/empty NAME only affects the install
+    // directory, so fall back to a safe default rather than dropping the whole skill.
+    if (!instructions)
+        return undefined;
+    const name = sanitizeSkillName(o.name) ?? FALLBACK_SKILL_NAME;
+    const description = typeof o.description === 'string' ? o.description : '';
+    const resources = [];
+    if (Array.isArray(o.resources)) {
+        const used = new Set();
+        for (const entry of o.resources) {
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            const e = entry;
+            const relPath = sanitizeSkillRelPath(e.relPath);
+            if (!relPath || used.has(relPath))
+                continue;
+            if (typeof e.content !== 'string')
+                continue;
+            used.add(relPath);
+            resources.push({ relPath, content: e.content });
+        }
+    }
+    return { name, description, instructions, resources };
+}
+/**
+ * Validate the optional `skills` field. Names are de-duplicated: two skills sharing a directory
+ * name would overwrite each other's `SKILL.md`, leaving the agent pointed at whichever landed
+ * last — so the first wins and the collision is dropped rather than silently mixing two playbooks.
+ */
+export function parseSkillSpecs(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const skills = [];
+    const used = new Set();
+    for (const entry of value) {
+        const skill = parseSkillSpec(entry);
+        if (!skill || used.has(skill.name))
+            continue;
+        used.add(skill.name);
+        skills.push(skill);
+    }
+    return skills.length ? skills : undefined;
+}
+/**
+ * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
+ *
+ * Kept byte-identical to kernel's `MCP_SERVER_ID_PATTERN` (the harness image is built from `src/`
+ * plus typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
+ * against it by `test/agent-capabilities.conformity.test.ts` — the same copy-plus-pin arrangement
+ * `src/host-markdown.ts` uses.
+ */
+export const MCP_SERVER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+function sanitizeServerId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return MCP_SERVER_ID_PATTERN.test(value) ? value : undefined;
+}
+/**
+ * Whether an HTTP tool server's URL may be started. Mirrors kernel's `isAllowedMcpHttpUrl` (see
+ * {@link MCP_SERVER_ID_PATTERN} for why it is a copy, and the conformity suite that pins it):
+ * `https` anywhere, plain `http` only on loopback, since the headers carry a resolved credential.
+ * The backend refuses the same URLs at registration — this is the boundary check, so a body that
+ * reached the container by any other route is held to the rule too.
+ */
+export function isAllowedMcpHttpUrl(raw) {
+    const match = /^(https?):\/\/([^/?#]*)/i.exec(raw);
+    if (!match)
+        return false;
+    if (match[1].toLowerCase() === 'https')
+        return true;
+    // Plain http from here: the host must be loopback. Strip userinfo FIRST and from the LAST `@`,
+    // or `http://127.0.0.1@evil.example` reads as loopback while the request goes to evil.example.
+    const authority = match[2];
+    const hostPort = authority.slice(authority.lastIndexOf('@') + 1);
+    const closingBracket = hostPort.indexOf(']');
+    const host = (hostPort.startsWith('[') && closingBracket !== -1
+        ? hostPort.slice(1, closingBracket) // IPv6 literal, e.g. [::1]:8080
+        : (hostPort.split(':')[0] ?? '')).toLowerCase();
+    return host === 'localhost' || host === '::1' || /^127\.\d+\.\d+\.\d+$/.test(host);
+}
+/** A string→string record, dropping any non-string entry. Undefined when nothing survives. */
+function parseStringRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw === 'string')
+            out[key] = raw;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** A string array, dropping non-string entries. Undefined when nothing survives. */
+function parseStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value.filter((v) => typeof v === 'string');
+    return out.length ? out : undefined;
+}
+/** Validate one `mcpServers` entry, or undefined when malformed for its transport. */
+function parseMcpServerSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    const id = sanitizeServerId(o.id);
+    if (!id)
+        return undefined;
+    const allowedTools = parseStringArray(o.allowedTools);
+    const secretKeys = parseStringArray(o.secretKeys);
+    if (o.transport === 'http') {
+        // https anywhere, plain http only on loopback: the CLI would happily be pointed at a
+        // `file:`/`ws:` URL, and the headers below carry this job's resolved credential.
+        const url = typeof o.url === 'string' && isAllowedMcpHttpUrl(o.url) ? o.url : undefined;
+        if (!url)
+            return undefined;
+        const headers = parseStringRecord(o.headers);
+        return {
+            id,
+            transport: 'http',
+            url,
+            ...(headers ? { headers } : {}),
+            ...(allowedTools ? { allowedTools } : {}),
+            ...(secretKeys ? { secretKeys } : {}),
+        };
+    }
+    const command = typeof o.command === 'string' && o.command ? o.command : undefined;
+    if (!command)
+        return undefined;
+    const args = parseStringArray(o.args);
+    const env = parseStringRecord(o.env);
+    return {
+        id,
+        transport: 'stdio',
+        command,
+        ...(args ? { args } : {}),
+        ...(env ? { env } : {}),
+        ...(allowedTools ? { allowedTools } : {}),
+        ...(secretKeys ? { secretKeys } : {}),
+    };
+}
+/** Validate the optional `mcpServers` field, dropping malformed entries and duplicate ids. */
+export function parseMcpServerSpecs(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const servers = [];
+    const used = new Set();
+    for (const entry of value) {
+        const server = parseMcpServerSpec(entry);
+        if (!server || used.has(server.id))
+            continue;
+        used.add(server.id);
+        servers.push(server);
+    }
+    return servers.length ? servers : undefined;
+}
+// ---------------------------------------------------------------------------
+// Materialisation (per CLI)
+// ---------------------------------------------------------------------------
+/**
+ * The `--mcp-config` document Claude Code reads: `{ "mcpServers": { "<id>": {...} } }`. An `http`
+ * server declares `type: "http"` with its headers; a `stdio` one declares its command/args/env.
+ */
+export function claudeMcpConfig(servers) {
+    const mcpServers = {};
+    for (const server of servers) {
+        mcpServers[server.id] =
+            server.transport === 'http'
+                ? { type: 'http', url: server.url, ...(server.headers ? { headers: server.headers } : {}) }
+                : {
+                    type: 'stdio',
+                    command: server.command,
+                    ...(server.args ? { args: server.args } : {}),
+                    ...(server.env ? { env: server.env } : {}),
+                };
+    }
+    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.
+ *
+ * Returns undefined when NO server restricts its tools — there is then nothing to narrow, and the
+ * safest list is the one we never send.
+ *
+ * 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.
+ */
+export function claudeAllowedToolPatterns(servers) {
+    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];
+}
+/** Escape a string as a TOML basic string (Codex config is TOML, not JSON). */
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * 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 — the backend states such a server as
+ * unavailable when it declares `harnesses: ['claude-code']`, and a deployment that wires an HTTP
+ * server for Codex gets a no-op rather than a malformed config.
+ */
+export function codexMcpConfigToml(servers) {
+    const blocks = [];
+    for (const server of servers) {
+        if (server.transport !== 'stdio')
+            continue;
+        const lines = [`[mcp_servers.${server.id}]`, `command = ${tomlString(server.command)}`];
+        if (server.args?.length) {
+            lines.push(`args = [${server.args.map(tomlString).join(', ')}]`);
+        }
+        if (server.env) {
+            const entries = Object.entries(server.env).map(([k, v]) => `${tomlString(k)} = ${tomlString(v)}`);
+            if (entries.length)
+                lines.push(`env = { ${entries.join(', ')} }`);
+        }
+        blocks.push(lines.join('\n'));
+    }
+    return blocks.length ? `${blocks.join('\n\n')}\n` : '';
+}
+/**
+ * Write the Claude Code MCP config for this run and return its path, or undefined when there are
+ * no servers. The file is written into the caller's PER-RUN directory (an isolated config home, or
+ * an ambient job's own scratch dir) — never the checkout (it would land in a commit) and never a
+ * HOME-global path (a second concurrent job would clobber it, and it carries this job's credentials).
+ */
+export async function writeClaudeMcpConfig(dir, servers) {
+    if (!servers.length)
+        return undefined;
+    const path = join(dir, 'mcp-servers.json');
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(claudeMcpConfig(servers), null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    return path;
+}

package/dist/agent-runner.js

@@ -5,9 +5,10 @@ import { dirname, join } from 'node:path';
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js';
 import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js';
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
+import { claudeAllowedToolPatterns, codexMcpConfigToml, mcpServerSecretValues, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { ProgressGuard } from './progress-guard.js';
 import { killChildProcess, spawnDetached } from './process.js';
-import { redact, secretsToRedact } from './redact.js';
+import { redact, registerKnownSecrets, 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';
@@ -200,6 +201,48 @@ async function writeNativeSkill(skillsRoot, skill) {
         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,
+    };
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -381,16 +424,21 @@ export async function runClaudeCode(opts) {
         await writeOnboardingPreseed(configHome);
         await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log);
     }
-    // Repo-sourced Claude Skill (slice 2): install it 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 from
-    // different repos would clobber each other. An ambient run reads the skill from the checkout
-    // instead (`.cat-context/skill/`, materialised by the caller). Best-effort: a write failure must
-    // not wedge the run — the prompt still names the skill.
-    if (opts.skill && configHome) {
-        await writeNativeSkill(join(configHome, 'skills'), opts.skill).catch(() => { });
+    // 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);
     const env = buildClaudeEnv(opts, configHome);
     // 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
@@ -430,6 +478,7 @@ export async function runClaudeCode(opts) {
                 'bypassPermissions',
                 '--model',
                 opts.model,
+                ...mcp.args,
                 ...appendArgs,
             ],
         }, prompt, { ...opts, signal: runSignal }, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
@@ -466,6 +515,8 @@ export async function runClaudeCode(opts) {
     }
     finally {
         await subagents?.stop();
+        // The ambient-mode MCP config dir (credential-bearing) never outlives the run.
+        await mcp.cleanup();
         if (configHome) {
             // 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
@@ -574,7 +625,11 @@ function claudeUsage(raw) {
 export async function runCodex(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
-    let usage;
+    // The running CUMULATIVE total, kept in its reported (inclusive) form plus the cached share
+    // it contains. `PiRunOutcome.usage` needs the inclusive figure — it is the key-rotation
+    // weight — while the fallback call metric below needs the split, so both are derived from
+    // this one value rather than one being reconstructed from the other.
+    let cumulative;
     // Codex reads its credentials from $CODEX_HOME/auth.json with file-backed
     // storage. CRITICAL: this home must live OUTSIDE the cloned checkout (`opts.cwd`)
     // — the blueprint/requirements/conflict-resolver handlers finish with
@@ -601,7 +656,17 @@ export async function runCodex(opts) {
     const codexHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-codex-'));
     if (codexHome) {
         await writeFile(join(codexHome, 'auth.json'), opts.subscriptionToken, { mode: 0o600 });
-        await writeFile(join(codexHome, 'config.toml'), 'cli_auth_credentials_store = "file"\n', 'utf8');
+        // Tool servers (MCP) ride the SAME per-run config.toml, so they are scoped to this job and
+        // torn down with the home. Under AMBIENT auth there is no per-run home — and writing servers
+        // into the developer's own `~/.codex/config.toml` would outlive the run and race a concurrent
+        // job — so an ambient codex run gets no MCP servers; the backend states them as unavailable
+        // the same way it does for a harness with no MCP client at all.
+        // Registered before the CLI starts, for the same reason the claude path does it: a server that
+        // fails to launch puts its own command line into the stderr tail we keep.
+        if (opts.mcpServers?.length)
+            registerKnownSecrets(mcpServerSecretValues(opts.mcpServers));
+        const mcpToml = opts.mcpServers?.length ? codexMcpConfigToml(opts.mcpServers) : '';
+        await writeFile(join(codexHome, 'config.toml'), `cli_auth_credentials_store = "file"\n${mcpToml ? `\n${mcpToml}` : ''}`, { encoding: 'utf8', mode: 0o600 });
     }
     // Codex has no system-prompt flag, so fold the composed role + best-practice
     // context into the prompt itself (Claude Code instead rides --append-system-prompt,
@@ -635,7 +700,7 @@ export async function runCodex(opts) {
             opts.onProgress(progress);
         const turnUsage = codexUsage(event);
         if (turnUsage)
-            usage = turnUsage;
+            cumulative = turnUsage;
         // A `token_count` event closes a model turn: pair its per-turn usage with the
         // assistant text seen since the previous turn as one telemetry call.
         const perTurn = codexLastTurnUsage(event);
@@ -647,7 +712,8 @@ export async function runCodex(opts) {
                 responseText: redactBody(pendingText, secrets),
                 reasoningText: '',
                 inputTokens: perTurn.inputTokens,
-                cachedInputTokens: perTurn.cachedInputTokens,
+                cacheReadTokens: perTurn.cacheReadTokens,
+                cacheWriteTokens: perTurn.cacheWriteTokens,
                 outputTokens: perTurn.outputTokens,
                 finishReason: null,
             }, opts.onCallMetric);
@@ -673,19 +739,29 @@ export async function runCodex(opts) {
         }, prompt, opts, { ...opts.extraEnv, ...(codexHome ? { CODEX_HOME: codexHome } : {}) }, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
         // single call from the cumulative total + final text so the run is still observable.
-        if (calls.length === 0 && (usage || summary)) {
+        // The cumulative total is inclusive of its cached share exactly as a per-turn one is, so
+        // it is split the same way rather than being filed wholesale as fresh — which would report
+        // a cache-heavy run as if nothing had been cached, the one reading this telemetry exists
+        // to rule out.
+        if (calls.length === 0 && (cumulative || summary)) {
             publishCallMetric(calls, {
                 model: opts.model,
                 promptText: redactBody(JSON.stringify(messages), secrets),
                 messageCount: messages.length,
                 responseText: redactBody(summary, secrets),
                 reasoningText: '',
-                inputTokens: usage?.inputTokens ?? 0,
-                cachedInputTokens: 0,
-                outputTokens: usage?.outputTokens ?? 0,
+                inputTokens: Math.max(0, (cumulative?.inputTokens ?? 0) - (cumulative?.cachedInputTokens ?? 0)),
+                cacheReadTokens: cumulative?.cachedInputTokens ?? 0,
+                // Codex reports no separate cache-WRITE class; 0 rather than guessed.
+                cacheWriteTokens: 0,
+                outputTokens: cumulative?.outputTokens ?? 0,
                 finishReason: null,
             }, opts.onCallMetric);
         }
+        // The outcome's usage is the key-rotation WEIGHT, so it keeps the inclusive input count.
+        const usage = cumulative
+            ? { inputTokens: cumulative.inputTokens, outputTokens: cumulative.outputTokens }
+            : undefined;
         return {
             summary,
             stats,
@@ -765,8 +841,6 @@ function codexPlanProgress(event) {
  * other shapes put it on `usage` / `info.usage` directly. We read the cumulative
  * total when present so the caller can simply overwrite (not sum) — summing
  * cumulative totals across events would multiply-count. Checked most-likely first.
- * `input_tokens` is the TOTAL prompt count (OpenAI semantics: `cached_input_tokens`
- * is a subset already inside it), so it is NOT summed with the cached share.
  */
 function codexUsage(event) {
     const info = isObject(event.info) ? event.info : undefined;
@@ -780,14 +854,21 @@ function codexUsage(event) {
     const output = numberOf(raw.output_tokens);
     if (input === 0 && output === 0)
         return undefined;
-    return { inputTokens: input, outputTokens: output };
+    return {
+        inputTokens: input,
+        cachedInputTokens: numberOf(raw.cached_input_tokens),
+        outputTokens: output,
+    };
 }
 /**
  * Per-TURN Codex token usage off a `token_count` event's `info.last_token_usage` (the
  * delta for the turn just completed, as opposed to `codexUsage`'s cumulative total).
- * `input_tokens` is the total prompt count for the turn and already INCLUDES the cached
- * share (OpenAI semantics), so `cachedInputTokens` is surfaced as the subset it is —
- * NOT added on top (adding it would double-count every cached token).
+ *
+ * OpenAI semantics: `input_tokens` is the turn's WHOLE prompt count and already INCLUDES
+ * the cached share, so the fresh figure is the difference. Clamped at 0 because the two
+ * counts come off the same event and a vendor inconsistency must not mint a negative token
+ * count. Codex reports no separate cache-WRITE class, so that class is 0 here rather than
+ * guessed.
  */
 function codexLastTurnUsage(event) {
     const info = isObject(event.info) ? event.info : undefined;
@@ -799,7 +880,12 @@ function codexLastTurnUsage(event) {
     const output = numberOf(raw.output_tokens);
     if (input === 0 && output === 0)
         return undefined;
-    return { inputTokens: input, cachedInputTokens: cached, outputTokens: output };
+    return {
+        inputTokens: Math.max(0, input - cached),
+        cacheReadTokens: cached,
+        cacheWriteTokens: 0,
+        outputTokens: output,
+    };
 }
 /** Dispatch to the configured subscription harness runner. */
 export function runSubscriptionHarness(harness, opts) {

package/dist/agent-shared.js

@@ -0,0 +1,23 @@
+// Small helpers shared by every agent MODE (explore / coding / bootstrap / preview). They live
+// apart from `agent.ts` so the bootstrap mode — a whole flow of its own — could move to its own
+// module without either file importing the other.
+/**
+ * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
+ * onto its final result. Every container mode routes its result through this so the report reaches
+ * the backend uniformly. A run that wrote no report passes through unchanged.
+ */
+export function mergeEffort(result, effortReport) {
+    return effortReport ? { ...result, effortReport } : result;
+}
+/**
+ * The agent-capability fields (skills + tool servers) 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 or tool server — the failure mode is invisible
+ * (the agent simply works without it) and would only show up as degraded output.
+ */
+export function agentCapabilities(job) {
+    return {
+        ...(job.skills?.length ? { skills: job.skills } : {}),
+        ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
+    };
+}