@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/lib/sandbox/commands/create.ts

@@ -7,7 +7,8 @@ import type { ExecFileSyncOptions, StdioOptions } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import * as toml from 'smol-toml';
+import { listAgentClientAdapters } from '../../agent-clients/registry.ts';
+import type { SandboxAlias } from '../tool-types.ts';
 import { loadConfig } from '../config.ts';
 import {
   assertValidBranchName,
@@ -18,6 +19,7 @@ import {
   sandboxImageConfigLabel,
   sandboxImageRefreshLabel,
   sandboxLabel,
+  sandboxRuntimeCapabilityLabel,
   shareBranchDir,
   shareCommonDir,
   shellConfigDir,
@@ -43,6 +45,11 @@ import {
   runVerboseEngine
 } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
+import {
+  createSandboxCapabilityPlan,
+  runSandboxHooks,
+  runBoundedSandboxHookCommand
+} from '../agent-client-reconciler.ts';
 import {
   resolveTools,
   tmpfsSeedStagingPath,
@@ -61,6 +68,7 @@ import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import { ensureSandboxDiscoveryReadmes } from '../readme-scaffold.ts';
+import { removeDirRecursive } from '../../remove-dir.ts';
 import {
   prepareClaudeCredentials,
   redactCommandError,
@@ -76,29 +84,13 @@ import {
   parseRefreshTimestamp
 } from '../image-build.ts';
 
-const OPENCODE_YOLO_PERMISSION = '{"*":"allow","read":"allow","bash":"allow","edit":"allow","webfetch":"allow","external_directory":"allow","doom_loop":"allow"}';
+export {
+  ensureCodexModelInheritance,
+  ensureCodexWorkspaceTrust
+} from '../../agent-clients/adapters/codex-sandbox.ts';
+
 const SANDBOX_ALIAS_BLOCK_BEGIN = '# >>> agent-infra managed aliases >>>';
 const SANDBOX_ALIAS_BLOCK_END = '# <<< agent-infra managed aliases <<<';
-const SANDBOX_ALIAS_NAMES = [
-  'claude-yolo',
-  'opencode-yolo',
-  'codex-yolo',
-  'gemini-yolo',
-  'cy',
-  'oy',
-  'xy',
-  'gy'
-];
-const DEFAULT_SANDBOX_ALIASES = `alias claude-yolo='claude --dangerously-skip-permissions; tput ed'
-alias opencode-yolo='OPENCODE_PERMISSION='\\''${OPENCODE_YOLO_PERMISSION}'\\'' opencode; tput ed'
-alias codex-yolo='codex --yolo; tput ed'
-alias gemini-yolo='gemini --yolo; tput ed'
-
-alias cy='claude --dangerously-skip-permissions; tput ed'
-alias oy='OPENCODE_PERMISSION='\\''${OPENCODE_YOLO_PERMISSION}'\\'' opencode; tput ed'
-alias xy='codex --yolo; tput ed'
-alias gy='gemini --yolo; tput ed'
-`;
 const CONTAINER_HOME = '/home/devuser';
 const CONTAINER_SHELL_CONFIG_MOUNT = `${CONTAINER_HOME}/.host-shell-config`;
 const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>] [--no-refresh] [--inherit-proxy|-P] [--inherit-build-proxy|-B]
@@ -410,7 +402,7 @@ export function prepareHostShellConfig({
   repoRoot: string;
 }): HostShellConfig {
   const hostDir = hostShellConfigDir(home, project, branch);
-  fs.rmSync(hostDir, { recursive: true, force: true });
+  removeDirRecursive(hostDir);
   fs.mkdirSync(hostDir, { recursive: true });
 
   writeSanitizedGitconfig({
@@ -459,10 +451,19 @@ function normalizeWorktreePath(worktreePath: string): string {
     return '';
   }
 
+  const wslMount = process.platform === 'win32'
+    ? worktreePath.match(/^\/mnt\/([A-Za-z])(?:\/(.*))?$/)
+    : null;
+  const hostPath = wslMount
+    ? `${wslMount[1]!.toUpperCase()}:\\${(wslMount[2] ?? '').replace(/\//g, '\\')}`
+    : worktreePath;
+
   try {
-    return fs.existsSync(worktreePath) ? fs.realpathSync(worktreePath) : path.resolve(worktreePath);
+    const normalized = fs.existsSync(hostPath) ? fs.realpathSync(hostPath) : path.resolve(hostPath);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
   } catch {
-    return path.resolve(worktreePath);
+    const normalized = path.resolve(hostPath);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
   }
 }
 
@@ -714,7 +715,7 @@ export function buildContainerEnvFile(
     mkdtempFn = fs.mkdtempSync,
     writeFileFn = fs.writeFileSync,
     chmodFn = fs.chmodSync,
-    rmFn = fs.rmSync,
+    rmFn = removeDirRecursive as typeof fs.rmSync,
     tmpDir = os.tmpdir(),
     runSafeFn = runSafe
   } = options;
@@ -971,154 +972,6 @@ export function ensureClaudeSettings(toolDir: string, hostHomeDir?: string): voi
   }
 }
 
-function resolveHostCatalogPath(value: unknown, hostHomeDir: string): string | null {
-  if (typeof value !== 'string' || value === '') {
-    return null;
-  }
-  let resolved: string;
-  if (value === '~' || value.startsWith('~/') || value.startsWith('~\\')) {
-    resolved = path.join(hostHomeDir, value.slice(1).replace(/^[/\\]+/, ''));
-  } else if (path.isAbsolute(value)) {
-    resolved = value;
-  } else {
-    resolved = path.join(hostHomeDir, '.codex', value);
-  }
-  try {
-    if (!fs.statSync(resolved).isFile()) {
-      return null;
-    }
-    fs.accessSync(resolved, fs.constants.R_OK);
-    return resolved;
-  } catch {
-    return null;
-  }
-}
-
-const CODEX_DISABLED_FEATURE_FLAGS = ['apps', 'enable_mcp_apps'] as const;
-
-function removeCodexMcpServers(sandboxParsed: JsonObject): boolean {
-  if (!Object.hasOwn(sandboxParsed, 'mcp_servers')) {
-    return false;
-  }
-  delete sandboxParsed.mcp_servers;
-  return true;
-}
-
-function inheritDisabledCodexFeatureFlags(sandboxParsed: JsonObject, hostParsed: JsonObject): boolean {
-  if (!isJsonObjectRecord(hostParsed.features)) {
-    return false;
-  }
-  if (Object.hasOwn(sandboxParsed, 'features') && !isJsonObjectRecord(sandboxParsed.features)) {
-    return false;
-  }
-
-  let sandboxFeatures = sandboxParsed.features as JsonObject | undefined;
-  let changed = false;
-  for (const key of CODEX_DISABLED_FEATURE_FLAGS) {
-    if (hostParsed.features[key] !== false) {
-      continue;
-    }
-    if (!sandboxFeatures) {
-      sandboxFeatures = {};
-      sandboxParsed.features = sandboxFeatures;
-    }
-    if (sandboxFeatures[key] !== false) {
-      sandboxFeatures[key] = false;
-      changed = true;
-    }
-  }
-  return changed;
-}
-
-export function ensureCodexModelInheritance(
-  toolDir: string,
-  hostHomeDir?: string,
-  containerCodexDir: string = '/home/devuser/.codex'
-): void {
-  if (!hostHomeDir) {
-    return;
-  }
-
-  const hostConfigPath = path.join(hostHomeDir, '.codex', 'config.toml');
-  if (!fs.existsSync(hostConfigPath)) {
-    return;
-  }
-
-  let hostParsed: JsonObject;
-  try {
-    hostParsed = toml.parse(fs.readFileSync(hostConfigPath, 'utf8')) as JsonObject;
-  } catch {
-    return;
-  }
-
-  const sandboxConfigPath = path.join(toolDir, 'config.toml');
-  // This rewrites sandbox-side TOML and drops comments; the host config stays untouched.
-  let sandboxParsed: JsonObject = {};
-  if (fs.existsSync(sandboxConfigPath)) {
-    try {
-      sandboxParsed = toml.parse(fs.readFileSync(sandboxConfigPath, 'utf8')) as JsonObject;
-    } catch {
-      return;
-    }
-  }
-
-  let changed = removeCodexMcpServers(sandboxParsed);
-  changed = inheritDisabledCodexFeatureFlags(sandboxParsed, hostParsed) || changed;
-
-  const inheritSpecs: Array<readonly [string, 'string' | 'number']> = [
-    ['model', 'string'],
-    ['model_reasoning_effort', 'string'],
-    ['model_auto_compact_token_limit', 'number']
-  ];
-
-  for (const [key, type] of inheritSpecs) {
-    if (Object.hasOwn(sandboxParsed, key)) {
-      continue;
-    }
-    const value = hostParsed[key];
-    if (type === 'string' && (typeof value !== 'string' || value === '')) {
-      continue;
-    }
-    if (type === 'number' && (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)) {
-      continue;
-    }
-    sandboxParsed[key] = value;
-    changed = true;
-  }
-
-  if (!Object.hasOwn(sandboxParsed, 'model_catalog_json')) {
-    const hostCatalogPath = resolveHostCatalogPath(hostParsed['model_catalog_json'], hostHomeDir);
-    if (hostCatalogPath) {
-      try {
-        const basename = path.basename(hostCatalogPath);
-        const destDir = path.join(toolDir, 'model-catalogs');
-        fs.mkdirSync(destDir, { recursive: true });
-        fs.copyFileSync(hostCatalogPath, path.join(destDir, basename));
-        sandboxParsed['model_catalog_json'] = path.posix.join(containerCodexDir, 'model-catalogs', basename);
-        changed = true;
-      } catch {
-        // Copy failed (e.g. permissions): skip catalog, keep scalar inheritance intact.
-      }
-    }
-  }
-
-  if (changed) {
-    fs.writeFileSync(sandboxConfigPath, `${toml.stringify(sandboxParsed)}\n`, 'utf8');
-  }
-}
-
-export function ensureCodexWorkspaceTrust(toolDir: string): void {
-  const configPath = path.join(toolDir, 'config.toml');
-  let content = '';
-  if (fs.existsSync(configPath)) {
-    content = fs.readFileSync(configPath, 'utf8');
-  }
-  if (!content.includes('[projects."/workspace"]')) {
-    const entry = '\n[projects."/workspace"]\ntrust_level = "trusted"\n';
-    fs.writeFileSync(configPath, content + entry, 'utf8');
-  }
-}
-
 export function ensureOpenCodeModelInheritance(toolDir: string, hostHomeDir?: string): void {
   if (!hostHomeDir) {
     return;
@@ -1189,7 +1042,10 @@ function stripManagedSandboxAliasBlocks(content: string): string {
   return content.replace(blockPattern, '').trimEnd();
 }
 
-function isLegacyManagedSandboxAliasFile(content: string): boolean {
+function isLegacyManagedSandboxAliasFile(
+  content: string,
+  aliases: readonly SandboxAlias[]
+): boolean {
   const lines = content
     .split(/\r?\n/)
     .map((line) => line.trim())
@@ -1199,13 +1055,29 @@ function isLegacyManagedSandboxAliasFile(content: string): boolean {
     return false;
   }
 
-  const aliasPattern = new RegExp(`^alias (${SANDBOX_ALIAS_NAMES.map(escapeRegExp).join('|')})=`);
+  const aliasPattern = new RegExp(
+    `^alias (${aliases.map((alias) => escapeRegExp(alias.name)).join('|')})=`
+  );
   return lines.every((line) => aliasPattern.test(line));
 }
 
-export function ensureSandboxAliasesFile(home: string): { created: boolean; path: string } {
+function registrySandboxAliases(): readonly SandboxAlias[] {
+  return listAgentClientAdapters().flatMap((adapter) => adapter.sandbox.aliases);
+}
+
+function renderSandboxAliases(aliases: readonly SandboxAlias[]): string {
+  return `${aliases.map((alias) =>
+    `alias ${alias.name}='${alias.command.replaceAll("'", "'\\''")}'`
+  ).join('\n')}\n`;
+}
+
+export function ensureSandboxAliasesFile(
+  home: string,
+  aliases: readonly SandboxAlias[] = registrySandboxAliases()
+): { created: boolean; path: string } {
   const aliasesPath = sandboxAliasesPath(home);
-  const managedBlock = `${SANDBOX_ALIAS_BLOCK_BEGIN}\n${DEFAULT_SANDBOX_ALIASES}${SANDBOX_ALIAS_BLOCK_END}\n`;
+  const managedBlock =
+    `${SANDBOX_ALIAS_BLOCK_BEGIN}\n${renderSandboxAliases(aliases)}${SANDBOX_ALIAS_BLOCK_END}\n`;
   fs.mkdirSync(path.dirname(aliasesPath), { recursive: true });
   const created = !fs.existsSync(aliasesPath);
   let existing = '';
@@ -1214,7 +1086,7 @@ export function ensureSandboxAliasesFile(home: string): { created: boolean; path
     existing = fs.readFileSync(aliasesPath, 'utf8');
   }
 
-  const userContent = isLegacyManagedSandboxAliasFile(existing)
+  const userContent = isLegacyManagedSandboxAliasFile(existing, aliases)
     ? ''
     : stripManagedSandboxAliasBlocks(existing);
   const nextContent = userContent
@@ -1355,19 +1227,18 @@ export async function create(args: string[]): Promise<void> {
   };
   const worktreeCandidates = worktreeDirCandidates(effectiveConfig, branch);
   assertBranchAvailable(config.repoRoot, branch, { allowedWorktrees: worktreeCandidates });
-  const tools = resolveTools(effectiveConfig);
+  const capabilityPlan = createSandboxCapabilityPlan(effectiveConfig);
+  const tools = [...capabilityPlan.tools];
   const resolvedTools = resolveToolDirs(effectiveConfig, tools, branch);
   // Fatal credential states still fail before filesystem/docker side effects.
-  // A genuinely missing Claude Code credential only removes Claude Code's
-  // sandbox config and credential mounts for this create run.
+  // Missing credentials leave the selected Claude Code capability installed
+  // and mounted; only the absent live credential file is omitted.
   const credentialOutcome = prepareClaudeCredentials(
     effectiveConfig.home,
     effectiveConfig.project,
     resolvedTools
   );
-  const effectiveResolvedTools = credentialOutcome.status === 'SKIPPED'
-    ? resolvedTools.filter(({ tool }) => tool.id !== 'claude-code')
-    : resolvedTools;
+  const effectiveResolvedTools = resolvedTools;
   const container = containerName(effectiveConfig, branch);
   const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
   const shareCommon = shareCommonDir(effectiveConfig);
@@ -1392,6 +1263,16 @@ export async function create(args: string[]): Promise<void> {
 
   try {
     p.log.step('Checking container engine...');
+    const prepareHookResults = await runSandboxHooks({
+      hooks: capabilityPlan.hooksByPhase.prepare,
+      phase: 'prepare',
+      context: { config: effectiveConfig, plan: capabilityPlan },
+      runCommand: runBoundedSandboxHookCommand
+    });
+    const prepareFailure = prepareHookResults.find((result) => result.status === 'fatal');
+    if (prepareFailure) {
+      throw new Error(prepareFailure.message ?? `Sandbox hook '${prepareFailure.hookId}' failed.`);
+    }
     await ensureDocker(effectiveConfig, (detail: string) => {
       p.log.info(`  ${detail}`);
     });
@@ -1476,7 +1357,7 @@ export async function create(args: string[]): Promise<void> {
             if (fs.readdirSync(worktree).length > 0) {
               return `Worktree exists at ${worktree}`;
             }
-            fs.rmSync(worktree, { recursive: true, force: true });
+            removeDirRecursive(worktree);
           }
 
           const branchExists = runOk('git', [
@@ -1573,7 +1454,10 @@ export async function create(args: string[]): Promise<void> {
             }
           }
 
-          const aliasesFile = ensureSandboxAliasesFile(effectiveConfig.home);
+          const aliasesFile = ensureSandboxAliasesFile(
+            effectiveConfig.home,
+            capabilityPlan.aliases
+          );
           if (aliasesFile.created) {
             message(`Created default sandbox aliases at ${aliasesFile.path}`);
           }
@@ -1609,6 +1493,28 @@ export async function create(args: string[]): Promise<void> {
           let hostShellConfig: HostShellConfig;
           let tmpfsSeedPlan: TmpfsSeedPlanEntry[] = [];
           try {
+            const beforeCreateResults = await runSandboxHooks({
+              hooks: capabilityPlan.hooksByPhase['before-container-create'],
+              phase: 'before-container-create',
+              context: {
+                config: effectiveConfig,
+                plan: capabilityPlan,
+                create: {
+                  hostHome: effectiveConfig.home,
+                  resolvedTools: effectiveResolvedTools
+                }
+              },
+              runCommand: runBoundedSandboxHookCommand
+            });
+            const beforeCreateFailure = beforeCreateResults.find(
+              (result) => result.status === 'fatal'
+            );
+            if (beforeCreateFailure) {
+              throw new Error(
+                beforeCreateFailure.message
+                ?? `Sandbox hook '${beforeCreateFailure.hookId}' failed.`
+              );
+            }
             const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
             if (claudeCodeEntry) {
               ensureClaudeOnboarding(claudeCodeEntry.dir, effectiveConfig.home);
@@ -1617,11 +1523,6 @@ export async function create(args: string[]): Promise<void> {
               // provider/API settings are enough for Claude Code. If no usable
               // auth was present, the claude-code entry was removed above.
             }
-            const codexEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'codex');
-            if (codexEntry) {
-              ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home, codexEntry.tool.containerMount);
-              ensureCodexWorkspaceTrust(codexEntry.dir);
-            }
             const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
             if (geminiEntry) {
               ensureGeminiWorkspaceTrust(geminiEntry.dir);
@@ -1709,6 +1610,8 @@ export async function create(args: string[]): Promise<void> {
               sandboxLabel(effectiveConfig),
               '--label',
               `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
+              '--label',
+              `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
               ...coreVolumes,
               ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
               '-v',
@@ -1805,6 +1708,22 @@ export async function create(args: string[]): Promise<void> {
             }
           }
 
+          const afterStartResults = await runSandboxHooks({
+            hooks: capabilityPlan.hooksByPhase['after-container-start'],
+            phase: 'after-container-start',
+            context: { config: effectiveConfig, plan: capabilityPlan },
+            runCommand: runBoundedSandboxHookCommand
+          });
+          const afterStartFailure = afterStartResults.find(
+            (result) => result.status === 'fatal'
+          );
+          if (afterStartFailure) {
+            throw new Error(
+              afterStartFailure.message
+              ?? `Sandbox hook '${afterStartFailure.hookId}' failed.`
+            );
+          }
+
           return 'Container started';
         }
       }

package/lib/sandbox/commands/enter.ts

@@ -7,6 +7,11 @@ import {
 } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import { ensureSandboxReady } from '../recovery.ts';
+import {
+  createSandboxCapabilityPlan,
+  runBoundedSandboxHookCommand,
+  runSandboxHooks
+} from '../agent-client-reconciler.ts';
 import {
   formatCredentialWarnings,
   formatRemaining,
@@ -186,8 +191,25 @@ export async function enter(args: string[]): Promise<number> {
   });
   const container = ready.container;
   const cmd = parsed.command;
+  const capabilityPlan = createSandboxCapabilityPlan(config);
+  const enterHookResults = await runSandboxHooks({
+    hooks: capabilityPlan.hooksByPhase['before-enter'],
+    phase: 'before-enter',
+    context: { config, plan: capabilityPlan },
+    runCommand: runBoundedSandboxHookCommand
+  });
+  for (const result of enterHookResults) {
+    if (result.status === 'fatal') {
+      throw new Error(result.message ?? `Sandbox hook '${result.hookId}' failed.`);
+    }
+    if (result.status === 'warning') {
+      process.stderr.write(
+        `Warning: ${result.message ?? `Sandbox hook '${result.hookId}' did not complete.`}\n`
+      );
+    }
+  }
 
-  if (config.tools.includes('claude-code')) {
+  if (capabilityPlan.selectedAgentClients.some((adapter) => adapter.id === 'claude-code')) {
     try {
       // Scan all projects so a refresh from a neighbouring sandbox can still flow back to the host.
       const providerAuthAvailable = hasClaudeProviderAuth(config.home);

package/lib/sandbox/commands/prune.ts

@@ -11,7 +11,7 @@ import { hostJoin } from '../engines/wsl2-paths.ts';
 import { removeManagedDir, removeWorktreeDir } from '../managed-fs.ts';
 import { parseLabels } from './ls.ts';
 import { runEngine, runSafe } from '../shell.ts';
-import { resolveTools } from '../tools.ts';
+import { createSandboxCapabilityPlan } from '../agent-client-reconciler.ts';
 import type { SandboxTool } from '../tools.ts';
 
 const USAGE = `Usage: ai sandbox prune [--dry-run]`;
@@ -158,7 +158,7 @@ export async function prune(args: string[]): Promise<void> {
   }
 
   const config = loadConfig();
-  const tools = resolveTools(config);
+  const tools = [...createSandboxCapabilityPlan(config).cleanupInventory];
   const engine = detectEngine(config);
   const psArgs = [
     'ps',

package/lib/sandbox/commands/rm.ts

@@ -19,7 +19,8 @@ import { pruneSandboxDanglingImages } from '../image-prune.ts';
 import { removeManagedDir, removeWorktreeDir } from '../managed-fs.ts';
 import { runOk, runSafe, runSafeEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
-import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.ts';
+import { toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.ts';
+import { createSandboxCapabilityPlan } from '../agent-client-reconciler.ts';
 import type { SandboxTool } from '../tools.ts';
 import { fetchSandboxRows } from './list-running.ts';
 import { lookupShortIdByBranch } from '../../task/short-id.ts';
@@ -353,7 +354,7 @@ export async function rm(args: string[]): Promise<void> {
   }
 
   const config = loadConfig();
-  const tools = resolveTools(config);
+  const tools = [...createSandboxCapabilityPlan(config).cleanupInventory];
 
   if (values.purge) {
     await rmPurge(config, tools);

package/lib/sandbox/config.ts

@@ -3,6 +3,9 @@ import path from 'node:path';
 import { homedir, platform } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import pc from 'picocolors';
+import { normalizeAgentClients } from '../agent-clients/config.ts';
+import { isAgentClientId } from '../agent-clients/types.ts';
+import type { AgentClientState } from '../agent-clients/types.ts';
 import { validateSandboxEngine } from './engine.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
 import { findRuntimeEngineMismatches } from './runtime-engines.ts';
@@ -12,7 +15,7 @@ import type { SandboxTool } from './tools.ts';
 const DEFAULTS = Object.freeze({
   engine: null,
   runtimes: ['node22'],
-  tools: ['agent-infra', 'claude-code', 'codex', 'gemini-cli', 'opencode'],
+  tools: ['agent-infra'],
   refreshIntervalDays: 7,
   dockerfile: null,
   vm: {
@@ -57,6 +60,8 @@ export type SandboxConfig = {
   runtimes: string[];
   tools: string[];
   customTools: SandboxTool[];
+  agentClientState: AgentClientState;
+  agentClientSource: 'canonical' | 'legacy';
   refreshIntervalDays: number;
   dockerfile: string | null;
   vm: SandboxVmConfig;
@@ -65,6 +70,8 @@ export type SandboxConfig = {
 type AircConfig = {
   project?: unknown;
   org?: unknown;
+  agentClients?: unknown;
+  tuis?: unknown;
   sandbox?: SandboxConfigInput;
 };
 
@@ -98,6 +105,23 @@ function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes:
   };
 }
 
+function resolveSandboxToolIds(
+  sandbox: SandboxConfigInput,
+  agentClients: ReturnType<typeof normalizeAgentClients>,
+  defaults: readonly string[]
+): string[] {
+  if (Array.isArray(sandbox.tools)) {
+    const tools = sandbox.tools.filter((tool): tool is string => typeof tool === 'string');
+    return agentClients.source === 'canonical'
+      ? tools.filter((tool) => !isAgentClientId(tool))
+      : tools;
+  }
+  if (agentClients.remainingSandboxTools !== undefined) {
+    return [...agentClients.remainingSandboxTools];
+  }
+  return [...defaults];
+}
+
 export function loadConfig({
   platformFn = platform,
   writeStderr = (chunk) => process.stderr.write(chunk)
@@ -115,6 +139,8 @@ export function loadConfig({
   }
 
   const airc = JSON.parse(fs.readFileSync(configPath, 'utf8')) as AircConfig;
+  const sandboxInput = airc.sandbox;
+  const agentClients = normalizeAgentClients(airc);
   const defaults = cloneDefaults();
   const sandbox = airc.sandbox ?? {};
   const engine = validateSandboxEngine(sandbox.engine ?? defaults.engine, { platformFn });
@@ -149,6 +175,7 @@ export function loadConfig({
   }
 
   const customTools = parseCustomTools(sandbox.customTools, { home });
+  const tools = resolveSandboxToolIds(sandbox, agentClients, defaults.tools);
 
   return {
     repoRoot,
@@ -164,10 +191,10 @@ export function loadConfig({
     dotfilesDir: hostJoin(home, '.agent-infra', 'dotfiles'),
     engine,
     runtimes,
-    tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
-      ? [...sandbox.tools]
-      : defaults.tools,
+    tools,
     customTools,
+    agentClientState: agentClients.state,
+    agentClientSource: agentClients.source,
     refreshIntervalDays: asNonNegativeIntegerOrDefault(
       sandbox.refreshIntervalDays,
       defaults.refreshIntervalDays

package/lib/sandbox/constants.ts

@@ -111,6 +111,12 @@ export function sandboxImageRefreshLabel(config: Pick<SandboxPathConfig, 'projec
   return `${sandboxLabel(config)}.last-refresh`;
 }
 
+export function sandboxRuntimeCapabilityLabel(
+  config: Pick<SandboxPathConfig, 'project'>
+): string {
+  return `agent-infra.sandbox.runtime-capability.${config.project}`;
+}
+
 export function parsePositiveIntegerOption(value: unknown, optionName: string): number | undefined {
   if (value === undefined || value === null) {
     return undefined;

package/lib/sandbox/dockerfile.ts

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { removeDirRecursive } from '../remove-dir.ts';
 
 const RUNTIMES_DIR = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -88,7 +89,7 @@ export function prepareDockerfile(config: DockerfileConfig): { path: string; sig
     path: tempPath,
     signature: dockerfileSignature(config),
     cleanup() {
-      fs.rmSync(tempDir, { recursive: true, force: true });
+      removeDirRecursive(tempDir);
     }
   };
 }