@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/lib/sandbox/managed-fs.ts

@@ -1,6 +1,6 @@
-import fs from 'node:fs';
 import path from 'node:path';
-import { run } from './shell.ts';
+import { run, runSafe } from './shell.ts';
+import { removeDirRecursive } from '../remove-dir.ts';
 
 export function assertManagedPath(root: string, target: string): void {
   const resolvedRoot = path.resolve(root);
@@ -15,13 +15,26 @@ export function assertManagedPath(root: string, target: string): void {
 
 export function removeManagedDir(root: string, dir: string): void {
   assertManagedPath(root, dir);
-  fs.rmSync(dir, { recursive: true, force: true });
+  removeDirRecursive(dir);
 }
 
-export function removeWorktreeDir(repoRoot: string, worktreeBase: string, dir: string): void {
+export function removeWorktreeDir(
+  repoRoot: string,
+  worktreeBase: string,
+  dir: string,
+  { runFn = run, runSafeFn = runSafe }: {
+    runFn?: typeof run;
+    runSafeFn?: typeof runSafe;
+  } = {}
+): void {
   try {
-    run('git', ['-C', repoRoot, 'worktree', 'remove', dir, '--force']);
+    runFn('git', ['-C', repoRoot, 'worktree', 'remove', dir, '--force']);
   } catch {
+    // On WSL2 the worktree is registered under its `/mnt/<drive>/...` path, so
+    // `git worktree remove <windows-path>` cannot match it. Delete the managed
+    // directory directly, then prune the now-dangling worktree metadata so the
+    // branch is no longer reported as checked out.
     removeManagedDir(worktreeBase, dir);
+    runSafeFn('git', ['-C', repoRoot, 'worktree', 'prune']);
   }
 }

package/lib/sandbox/recovery.ts

@@ -1,6 +1,19 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from './constants.ts';
+import {
+  containerNameCandidates,
+  sandboxBranchLabel,
+  sandboxLabel,
+  sandboxRuntimeCapabilityLabel
+} from './constants.ts';
+import { isAgentClientId } from '../agent-clients/types.ts';
+import {
+  createSandboxCapabilityPlan
+} from './agent-client-reconciler.ts';
+import type {
+  SandboxRecoveryFindingDescriptor,
+  SandboxRecoveryRepair
+} from './tool-types.ts';
 import type { SandboxConfig } from './config.ts';
 import { toEnginePath } from './engines/wsl2-paths.ts';
 import { sandboxCoreBindMounts } from './mounts.ts';
@@ -9,6 +22,7 @@ import {
   declaredTmpfsSeedEntries,
   resolveTools,
   toolConfigDirCandidates,
+  type SandboxTool,
   type TmpfsSeedEntry
 } from './tools.ts';
 import {
@@ -23,10 +37,22 @@ export type SandboxRecoveryFinding = {
   message: string;
   path?: string;
   seed?: TmpfsSeedEntry;
+  repair?: SandboxRecoveryRepair;
+};
+
+type SandboxAgentClientCheckSnapshot = {
+  adapterId: string;
+  checkId: string;
+  applicable: boolean;
+  healthy: boolean;
+  finding: SandboxRecoveryFindingDescriptor;
+  repair?: SandboxRecoveryRepair;
 };
 
 export type SandboxRecoverySnapshot = {
   identityOk: boolean;
+  runtimeCapabilityOk?: boolean;
+  unexpectedCapabilityMounts?: string[];
   mounts: Array<{
     path: string;
     expectedType: string;
@@ -48,12 +74,7 @@ export type SandboxRecoverySnapshot = {
     targetState: 'ok' | 'missing' | 'wrong-type' | 'inaccessible';
   }>;
   aliasesReadable: boolean;
-  codex?: {
-    commandAvailable: boolean;
-    stateWritable: boolean;
-    promptsSourceExists: boolean;
-    promptsValid: boolean;
-  };
+  agentClientChecks: SandboxAgentClientCheckSnapshot[];
 };
 
 export type SandboxReadyResult = {
@@ -114,6 +135,19 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
       message: 'Container identity does not match the requested sandbox branch.'
     });
   }
+  if (snapshot.runtimeCapabilityOk === false) {
+    findings.push({
+      repairKind: 'hard-failure',
+      message: 'Container runtime capability signature does not match the current sandbox plan.'
+    });
+  }
+  for (const mountPath of snapshot.unexpectedCapabilityMounts ?? []) {
+    findings.push({
+      repairKind: 'hard-failure',
+      message: `Disabled Agent Client capability remains mounted at ${mountPath}.`,
+      path: mountPath
+    });
+  }
 
   for (const mount of snapshot.mounts) {
     if (
@@ -177,25 +211,11 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
     });
   }
 
-  if (snapshot.codex) {
-    if (!snapshot.codex.commandAvailable) {
+  for (const check of snapshot.agentClientChecks) {
+    if (check.applicable && !check.healthy) {
       findings.push({
-        repairKind: 'hard-failure',
-        message: 'Codex is not available on PATH inside the sandbox.'
-      });
-    }
-    if (!snapshot.codex.stateWritable) {
-      findings.push({
-        repairKind: 'permissions',
-        message: 'Codex state directory is not writable by devuser.',
-        path: '/home/devuser/.codex'
-      });
-    }
-    if (snapshot.codex.promptsSourceExists && !snapshot.codex.promptsValid) {
-      findings.push({
-        repairKind: 'builtin-link',
-        message: 'Codex prompts link does not point to the workspace commands directory.',
-        path: '/home/devuser/.codex/prompts'
+        ...check.finding,
+        ...(check.repair === undefined ? {} : { repair: check.repair })
       });
     }
   }
@@ -277,11 +297,10 @@ function hostSourceAccessible(hostPath: string, writable: boolean): boolean {
 function expectedMounts(params: {
   config: SandboxConfig;
   branch: string;
-  engine: string;
+  tools: readonly SandboxTool[];
   actualMounts: Map<string, DockerMount>;
 }): ExpectedMount[] {
-  const { config, branch, actualMounts } = params;
-  const tools = resolveTools(config);
+  const { config, branch, tools, actualMounts } = params;
   const core = sandboxCoreBindMounts(config, branch).map((mount) => ({
     path: mount.containerPath,
     expectedType: 'bind' as const,
@@ -301,7 +320,13 @@ function expectedMounts(params: {
     })
   );
   const persistentTools = tools
-    .filter((tool) => !tool.tmpfs && actualMounts.has(tool.containerMount))
+    .filter((tool) =>
+      !tool.tmpfs
+      && (
+        config.agentClientSource === 'canonical'
+        || actualMounts.has(tool.containerMount)
+      )
+    )
     .map((tool) => ({
       path: tool.containerMount,
       expectedType: 'bind' as const,
@@ -401,7 +426,8 @@ export function collectSandboxRecoverySnapshot(params: {
       });
     }
   }
-  const tools = resolveTools(params.config);
+  const capabilityPlan = createSandboxCapabilityPlan(params.config);
+  const tools = [...capabilityPlan.tools];
   const seeds = declaredTmpfsSeedEntries(tools).map((seed) => {
     const mounted = mountsByDestination.get(seed.stagingPath)?.Type === 'bind';
     return {
@@ -434,11 +460,18 @@ export function collectSandboxRecoverySnapshot(params: {
   }));
   const labels = inspection.Config?.Labels ?? {};
   const branchLabel = labels[sandboxBranchLabel(params.config)];
-  const hasCodex = tools.some((tool) => tool.id === 'codex');
+  const selectedToolIds = new Set(tools.map((tool) => tool.id));
+  const enforceCanonicalPlan = params.config.agentClientSource === 'canonical';
+  const unexpectedCapabilityMounts = enforceCanonicalPlan
+    ? capabilityPlan.cleanupInventory
+      .filter((tool) => isAgentClientId(tool.id) && !selectedToolIds.has(tool.id))
+      .map((tool) => tool.containerMount)
+      .filter((mountPath) => mountsByDestination.has(mountPath))
+    : [];
   const mountSnapshots = expectedMounts({
     config: params.config,
     branch: params.branch,
-    engine: params.engine,
+    tools,
     actualMounts: mountsByDestination
   }).map((expected) => {
     const actual = mountsByDestination.get(expected.path);
@@ -478,6 +511,10 @@ export function collectSandboxRecoverySnapshot(params: {
     identityOk: typeof inspection.Id === 'string'
       && inspection.Id.length > 0
       && branchLabel === params.branch,
+    runtimeCapabilityOk: enforceCanonicalPlan
+      ? labels[sandboxRuntimeCapabilityLabel(params.config)] === capabilityPlan.runtimeSignature
+      : undefined,
+    unexpectedCapabilityMounts,
     mounts: mountSnapshots,
     tmpfs,
     seeds,
@@ -488,38 +525,31 @@ export function collectSandboxRecoverySnapshot(params: {
       ['/home/devuser/.bash_aliases'],
       runOkFn
     ),
-    codex: hasCodex
-      ? {
-          commandAvailable: probe(
-            params.engine,
-            params.container,
-            'command -v codex',
-            [],
-            runOkFn
-          ),
-          stateWritable: probe(
-            params.engine,
-            params.container,
-            'probe="$1/.agent-infra-codex-state-$$"; trap \'rm -f -- "$probe"\' EXIT; : > "$probe"',
-            ['/home/devuser/.codex'],
-            runOkFn
-          ),
-          promptsSourceExists: probe(
-            params.engine,
-            params.container,
-            'test -d "$1"',
-            ['/workspace/.codex/commands'],
-            runOkFn
-          ),
-          promptsValid: probe(
-            params.engine,
-            params.container,
-            'test "$(readlink -- "$1")" = "$2"',
-            ['/home/devuser/.codex/prompts', '/workspace/.codex/commands'],
-            runOkFn
-          )
-        }
-      : undefined
+    agentClientChecks: capabilityPlan.recoveryChecks.map(({ adapterId, check }) => {
+      const applicable = check.when === undefined || probe(
+        params.engine,
+        params.container,
+        check.when.script,
+        [...check.when.args],
+        runOkFn,
+        check.when.user
+      );
+      return {
+        adapterId,
+        checkId: check.id,
+        applicable,
+        healthy: !applicable || probe(
+          params.engine,
+          params.container,
+          check.probe.script,
+          [...check.probe.args],
+          runOkFn,
+          check.probe.user
+        ),
+        finding: check.finding,
+        ...(check.repair === undefined ? {} : { repair: check.repair })
+      };
+    })
   };
 }
 
@@ -626,10 +656,11 @@ function repairFindings(params: {
     deps: params.deps
   });
   const runVerboseFn = params.deps?.runVerbose ?? runVerboseEngine;
-  if (params.findings.some((finding) => finding.repairKind === 'builtin-link')) {
+  for (const repair of params.findings.flatMap((finding) =>
+    finding.repair === undefined ? [] : [finding.repair]
+  )) {
     runVerboseFn(params.engine, 'docker', [
-      'exec', '--user', 'devuser', params.container, 'ln', '-sfn',
-      '/workspace/.codex/commands', '/home/devuser/.codex/prompts'
+      'exec', '--user', repair.user, params.container, repair.command, ...repair.args
     ]);
   }
 }

package/lib/sandbox/shell.ts

@@ -143,7 +143,7 @@ export function runSafe(cmd: string, args: string[], opts: CommandOptions = {}):
 export function commandForEngine(engine: string, cmd: string, args: string[] = []): { cmd: string; args: string[] } {
   if (engine === 'wsl2') {
     const resolvedWrapper = resolveCommand('wsl.exe');
-    return { cmd: resolvedWrapper, args: ['--', cmd, ...args] };
+    return { cmd: resolvedWrapper, args: ['--exec', cmd, ...args] };
   }
 
   if (cmd === 'docker') {

package/lib/sandbox/tool-types.ts

@@ -0,0 +1,143 @@
+type SandboxToolInstall =
+  | Readonly<{ type: 'npm'; cmd: string }>
+  | Readonly<{ type: 'shell'; cmd: string }>;
+
+type SandboxTool = {
+  id: string;
+  name: string;
+  install: SandboxToolInstall;
+  sandboxBase: string;
+  containerMount: string;
+  versionCmd: string;
+  setupHint: string;
+  envVars?: Record<string, string>;
+  hostPreSeedFiles?: Array<{ hostPath: string; sandboxName: string }>;
+  hostPreSeedDirs?: Array<{ hostDir: string; sandboxSubdir: string }>;
+  pathRewriteFiles?: string[];
+  hostLiveMounts?: Array<{ hostPath: string; containerSubpath: string }>;
+  postSetupCmds?: string[];
+  tmpfs?: { size?: string; seed?: string[] };
+};
+
+type SandboxAlias = Readonly<{
+  name: string;
+  command: string;
+}>;
+
+const SANDBOX_HOOK_PHASES = [
+  'prepare',
+  'before-container-create',
+  'after-container-start',
+  'before-enter'
+] as const;
+
+type SandboxHookPhase = (typeof SANDBOX_HOOK_PHASES)[number];
+
+type SandboxHookStatus =
+  | 'ready'
+  | 'skip-client-runtime'
+  | 'warning'
+  | 'fatal'
+  | 'healthy'
+  | 'hard-failure';
+
+type SandboxHookCommand = Readonly<{
+  command: string;
+  args?: readonly string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}>;
+
+type SandboxHookCommandResult = Readonly<{
+  stdout: string;
+}>;
+
+type AgentClientSandboxHookResult = Readonly<{
+  status: SandboxHookStatus;
+  message?: string;
+}>;
+
+type SandboxResolvedToolState = Readonly<{
+  tool: SandboxTool;
+  dir: string;
+}>;
+
+type SandboxHookCreateContext = Readonly<{
+  hostHome: string;
+  resolvedTools: readonly SandboxResolvedToolState[];
+}>;
+
+type AgentClientSandboxHookContext = Readonly<{
+  signal: AbortSignal;
+  runCommand(command: SandboxHookCommand): Promise<SandboxHookCommandResult>;
+  config?: Readonly<Record<string, unknown>>;
+  plan?: Readonly<Record<string, unknown>>;
+  create?: SandboxHookCreateContext;
+}>;
+
+type AgentClientSandboxHook = Readonly<{
+  id: string;
+  phase: SandboxHookPhase;
+  timeoutMs?: number;
+  run(context: AgentClientSandboxHookContext): Promise<AgentClientSandboxHookResult>;
+}>;
+
+type SandboxToolContext = Readonly<{
+  home: string;
+  project: string;
+}>;
+
+type SandboxRecoveryProbe = Readonly<{
+  script: string;
+  args: readonly string[];
+  user?: string;
+}>;
+
+type SandboxRecoveryFindingDescriptor = Readonly<{
+  repairKind: 'permissions' | 'builtin-link' | 'hard-failure';
+  message: string;
+  path?: string;
+}>;
+
+type SandboxRecoveryRepair = Readonly<{
+  user: string;
+  command: string;
+  args: readonly string[];
+}>;
+
+type AgentClientSandboxRecoveryCheck = Readonly<{
+  id: string;
+  when?: SandboxRecoveryProbe;
+  probe: SandboxRecoveryProbe;
+  finding: SandboxRecoveryFindingDescriptor;
+  repair?: SandboxRecoveryRepair;
+}>;
+
+type AgentClientSandboxDescriptor = Readonly<{
+  createTool(context: SandboxToolContext): SandboxTool;
+  aliases: readonly SandboxAlias[];
+  hooks: readonly AgentClientSandboxHook[];
+  recoveryChecks?: readonly AgentClientSandboxRecoveryCheck[];
+}>;
+
+export { SANDBOX_HOOK_PHASES };
+export type {
+  AgentClientSandboxDescriptor,
+  AgentClientSandboxHook,
+  AgentClientSandboxHookContext,
+  AgentClientSandboxHookResult,
+  AgentClientSandboxRecoveryCheck,
+  SandboxAlias,
+  SandboxHookCommand,
+  SandboxHookCommandResult,
+  SandboxHookPhase,
+  SandboxHookStatus,
+  SandboxHookCreateContext,
+  SandboxRecoveryFindingDescriptor,
+  SandboxRecoveryProbe,
+  SandboxRecoveryRepair,
+  SandboxResolvedToolState,
+  SandboxTool,
+  SandboxToolContext,
+  SandboxToolInstall
+};

package/lib/sandbox/tools.ts

@@ -1,33 +1,10 @@
 import path from 'node:path';
+import { createSandboxCapabilityPlan } from './agent-client-reconciler.ts';
 import { safeNameCandidates, sanitizeBranchName } from './constants.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
+import type { SandboxTool, SandboxToolInstall } from './tool-types.ts';
 
-export type SandboxToolInstall =
-  | { type: 'npm'; cmd: string }
-  | { type: 'shell'; cmd: string };
-
-export type SandboxTool = {
-  id: string;
-  name: string;
-  install: SandboxToolInstall;
-  sandboxBase: string;
-  containerMount: string;
-  versionCmd: string;
-  setupHint: string;
-  envVars?: Record<string, string>;
-  hostPreSeedFiles?: Array<{ hostPath: string; sandboxName: string }>;
-  hostPreSeedDirs?: Array<{ hostDir: string; sandboxSubdir: string }>;
-  pathRewriteFiles?: string[];
-  hostLiveMounts?: Array<{ hostPath: string; containerSubpath: string }>;
-  postSetupCmds?: string[];
-  // When set, containerMount is mounted as an in-container tmpfs (RAM) instead
-  // of bind-mounting the host config dir, keeping high-churn tool logs off the
-  // host disk. `seed` lists the host-dir entries (relative to the tool's config
-  // dir) to copy into the tmpfs when the container starts. It is an explicit
-  // allowlist so runtime files (e.g. logs_2.sqlite, sessions) left in the host
-  // dir stay out of the container and seeded config cannot write back.
-  tmpfs?: { size?: string; seed?: string[] };
-};
+export type { SandboxTool, SandboxToolInstall } from './tool-types.ts';
 
 export type TmpfsSeedEntry = {
   toolId: string;
@@ -64,114 +41,11 @@ type ToolsConfig = {
   project: string;
   tools: string[];
   customTools?: SandboxTool[];
+  agentClientState?: import('../agent-clients/types.ts').AgentClientState;
 };
 
 const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 
-function createBuiltinTools(home: string, project: string): Record<string, SandboxTool> {
-  return {
-    'claude-code': {
-      id: 'claude-code',
-      name: 'Claude Code',
-      install: { type: 'npm', cmd: '@anthropic-ai/claude-code@latest' },
-      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
-      containerMount: '/home/devuser/.claude',
-      versionCmd: 'claude --version',
-      setupHint: 'Authenticates via host credentials live-mounted at ~/.claude/.credentials.json',
-      // Claude Code stores user data (.claude.json — onboarding state, theme,
-      // workspace trust) at $HOME/.claude.json by default, which sits OUTSIDE
-      // the bind-mounted /home/devuser/.claude tree, so our preseeded
-      // .claude.json never gets read and the theme picker re-runs on every
-      // container start. Pinning CLAUDE_CONFIG_DIR to the tool mount relocates
-      // .claude.json into the same directory as .credentials.json/settings.json,
-      // letting ensureClaudeOnboarding actually take effect.
-      envVars: { CLAUDE_CONFIG_DIR: '/home/devuser/.claude' },
-      hostPreSeedDirs: [
-        { hostDir: hostJoin(home, '.claude', 'plugins'), sandboxSubdir: 'plugins' }
-      ],
-      pathRewriteFiles: [
-        'plugins/installed_plugins.json',
-        'plugins/known_marketplaces.json'
-      ],
-      hostLiveMounts: [
-        {
-          hostPath: hostJoin(home, '.agent-infra', 'credentials', project, 'claude-code', '.credentials.json'),
-          containerSubpath: '.credentials.json'
-        }
-      ]
-    },
-    codex: {
-      id: 'codex',
-      name: 'Codex',
-      install: { type: 'npm', cmd: '@openai/codex' },
-      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'codex'),
-      containerMount: '/home/devuser/.codex',
-      versionCmd: 'codex --version',
-      setupHint: 'Run codex once inside the container and choose Device Code login if needed.',
-      // codex churns ~/.codex/logs_2.sqlite heavily (upstream openai/codex#24275);
-      // a bind-mount would write-amplify onto the host SSD via virtiofs. Mount the
-      // codex home as tmpfs so those logs stay in RAM and die with the container.
-      // Seeded config (config.toml, model-catalogs) is copied into the tmpfs at
-      // startup; runtime files like logs_2.sqlite stay in RAM.
-      tmpfs: { size: '512m', seed: ['config.toml', 'model-catalogs'] },
-      hostLiveMounts: [
-        { hostPath: hostJoin(home, '.codex', 'auth.json'), containerSubpath: 'auth.json' }
-      ],
-      postSetupCmds: [
-        'test -d /workspace/.codex/commands && ln -sfn /workspace/.codex/commands /home/devuser/.codex/prompts || true'
-      ]
-    },
-    opencode: {
-      id: 'opencode',
-      name: 'OpenCode',
-      install: { type: 'npm', cmd: 'opencode-ai' },
-      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'opencode'),
-      containerMount: '/home/devuser/.local/share/opencode',
-      versionCmd: 'opencode version',
-      setupHint: 'Configure OpenCode credentials inside the container before first use.',
-      // OpenCode reads opencode.json from $XDG_CONFIG_HOME/opencode by default,
-      // outside this tool mount. Pin the config file path so the inherited
-      // sandbox opencode.json is the one the TUI actually reads.
-      envVars: { OPENCODE_CONFIG: '/home/devuser/.local/share/opencode/opencode.json' },
-      hostLiveMounts: [
-        {
-          hostPath: hostJoin(home, '.local', 'share', 'opencode', 'auth.json'),
-          containerSubpath: 'auth.json'
-        }
-      ]
-    },
-    'gemini-cli': {
-      id: 'gemini-cli',
-      name: 'Gemini CLI',
-      install: { type: 'npm', cmd: '@google/gemini-cli' },
-      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
-      containerMount: '/home/devuser/.gemini',
-      versionCmd: 'gemini --version',
-      setupHint: 'Run gemini inside the container to finish authentication.',
-      hostLiveMounts: [
-        { hostPath: hostJoin(home, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' }
-      ],
-      hostPreSeedFiles: [
-        { hostPath: hostJoin(home, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
-        { hostPath: hostJoin(home, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' }
-      ]
-    },
-    'agent-infra': {
-      id: 'agent-infra',
-      name: 'agent-infra CLI',
-      install: { type: 'npm', cmd: '@fitlab-ai/agent-infra@latest' },
-      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'agent-infra'),
-      containerMount: '/home/devuser/.agent-infra-cli',
-      versionCmd: 'ai version --raw',
-      setupHint: 'Provides the ai and agent-infra CLI commands inside the sandbox.'
-    }
-  };
-}
-
-export function builtinToolIds(): string[] {
-  return Object.keys(createBuiltinTools('', ''));
-}
-
 function validateTool(tool: SandboxTool): void {
   if (!tool.id || !TOOL_ID_PATTERN.test(tool.id)) {
     throw new Error(`Invalid sandbox tool id: ${String(tool.id)}`);
@@ -379,33 +253,7 @@ export function parseCustomTools(value: unknown, options: { home: string }): San
 }
 
 export function resolveTools(config: ToolsConfig): SandboxTool[] {
-  const builtins = createBuiltinTools(config.home, config.project);
-  const customs = config.customTools ?? [];
-
-  const seen = new Set<string>();
-  for (const tool of customs) {
-    if (builtins[tool.id]) {
-      throw new Error(`Custom sandbox tool id "${tool.id}" collides with a built-in tool`);
-    }
-    if (seen.has(tool.id)) {
-      throw new Error(`Duplicate sandbox tool id "${tool.id}" in customTools`);
-    }
-    seen.add(tool.id);
-  }
-
-  const merged: Record<string, SandboxTool> = { ...builtins };
-  for (const tool of customs) {
-    merged[tool.id] = tool;
-  }
-
-  return config.tools.map((id) => {
-    const tool = merged[id];
-    if (!tool) {
-      throw new Error(`Unknown sandbox tool: ${id}`);
-    }
-    validateTool(tool);
-    return tool;
-  });
+  return [...createSandboxCapabilityPlan(config).tools];
 }
 
 export function toolConfigDir(tool: SandboxTool, project: string, branch: string): string {