@cat-factory/executor-harness 1.134.0 → 1.135.0

package/dist/claude-cli.d.ts

@@ -0,0 +1,90 @@
+import type { Logger } from './logger.js';
+/**
+ * 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 declare const CLAUDE_TOOL_SET: readonly string[];
+/**
+ * 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[];
+}
+/** The floor, exported so a test can assert every spelling is one this harness actually asks for. */
+export declare const CLAUDE_TOOL_CAPABILITIES: readonly ClaudeToolCapability[];
+/**
+ * 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 declare 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[];
+/**
+ * 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 declare function assertClaudeToolsCurrent(event: Record<string, unknown>, requested: readonly string[], log: Logger | undefined): void;
+export {};

package/dist/claude-cli.js

@@ -0,0 +1,181 @@
+// ---------------------------------------------------------------------------
+// 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 = [
+    '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',
+];
+const CLAUDE_TOOL_FLOOR = [
+    { 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 = 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) {
+    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, requested, log) {
+    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) => 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/dist/claude-home.d.ts

@@ -0,0 +1,41 @@
+import { type McpServerSpec, type SkillSpec } from './agent-capabilities.js';
+import type { Logger } from './logger.js';
+/** 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;
+}
+/**
+ * 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 declare function openClaudeRunHome(opts: ClaudeHomeOptions, tools: readonly string[]): Promise<ClaudeRunHome>;

package/dist/claude-home.js

@@ -0,0 +1,159 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { claudeAllowedToolPatterns, mcpServerSecretValues, writeClaudeMcpConfig, } from './agent-capabilities.js';
+import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
+import { registerKnownSecrets } from './redact.js';
+import { retainSessionTranscripts } from './transcript-retention.js';
+/**
+ * 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 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, configHome, builtIns) {
+    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, builtIns);
+    return {
+        args: [
+            '--mcp-config',
+            configPath,
+            '--strict-mcp-config',
+            ...(allowedTools?.length ? ['--allowedTools', allowedTools.join(',')] : []),
+        ],
+        cleanup,
+    };
+}
+export async function openClaudeRunHome(opts, tools) {
+    // 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, 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 }),
+    };
+}

package/dist/multi-repo-coding.js

@@ -8,6 +8,7 @@ import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription } from './pr
 import { runAgentInWorkspace, withWorkspace } from './pi-workspace.js';
 import { log } from './logger.js';
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
+import { agentCapabilities } from './agent-shared.js';
 import { resolvePrTemplateNote, withPrTemplateNote, } from './pr-template.js';
 import { noChangesReason } from './coding-agent.js';
 /**
@@ -133,16 +134,13 @@ export async function runMultiRepoCoding(job, opts = {}) {
             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),