@fitlab-ai/agent-infra 0.9.0 → 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,12 +19,19 @@ import {
   sandboxImageConfigLabel,
   sandboxImageRefreshLabel,
   sandboxLabel,
+  sandboxRuntimeCapabilityLabel,
   shareBranchDir,
   shareCommonDir,
   shellConfigDir,
   worktreeDirCandidates
 } from '../constants.ts';
 import { prepareDockerfile } from '../dockerfile.ts';
+import {
+  assertBuildProxyCompatibility,
+  buildProxyFailureHint,
+  prepareBuildProxy,
+  redactBuildProxyValues
+} from '../build-proxy.ts';
 import { detectEngine, ensureDocker } from '../engine.ts';
 import {
   commandForEngine,
@@ -37,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,
@@ -55,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,
@@ -70,32 +84,16 @@ 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]
+const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>] [--no-refresh] [--inherit-proxy|-P] [--inherit-build-proxy|-B]
 
 Host aliases:
   ${'~'}/.agent-infra/aliases/sandbox.sh is auto-created on first run and exposed
@@ -105,7 +103,9 @@ Host aliases:
 
 Proxy:
   --inherit-proxy, -P  Copy non-empty standard host proxy variables into the
-                       container environment through the private env file.`;
+                       container environment through the private env file.
+  --inherit-build-proxy, -B  Pass uppercase HTTP_PROXY, HTTPS_PROXY, and NO_PROXY
+                             to managed image build steps for this invocation.`;
 const HOST_PROXY_ENV_KEYS = [
   'http_proxy',
   'HTTP_PROXY',
@@ -116,6 +116,15 @@ const HOST_PROXY_ENV_KEYS = [
   'no_proxy',
   'NO_PROXY'
 ] as const;
+const MANAGED_GITHUB_GIT_CONFIG = [
+  '[credential]',
+  '\thelper = !gh auth git-credential',
+  '[credential "https://github.com"]',
+  '\thelper =',
+  '\thelper = !gh auth git-credential',
+  '[url "https://github.com/"]',
+  '\tinsteadOf = git@github.com:'
+];
 
 type SandboxCreateConfig = ReturnType<typeof loadConfig>;
 type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
@@ -134,9 +143,9 @@ type ExecSyncOptions = ExecFileSyncOptions & {
 };
 type ExecSyncFn = (cmd: string, args: string[], options?: ExecSyncOptions) => Buffer | string;
 type EngineExecFn = (engine: string, cmd: string, args: string[], opts?: ExecFileSyncOptions) => Buffer | string;
-type EngineRunFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string }) => string;
+type EngineRunFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string; env?: NodeJS.ProcessEnv }) => string;
 type EngineRunSafeFn = EngineRunFn;
-type EngineRunVerboseFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string }) => void;
+type EngineRunVerboseFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string; env?: NodeJS.ProcessEnv }) => void;
 type DirectRunFn = (cmd: string, args: string[], opts?: { cwd?: string }) => string;
 type DirectRunSafeFn = DirectRunFn;
 type DirectRunVerboseFn = (cmd: string, args: string[], opts?: { cwd?: string }) => void;
@@ -255,6 +264,16 @@ function normalizeContainerHomeSeparators(content: string): string {
   return content.replace(containerHomePattern, (value) => value.replaceAll('\\', '/'));
 }
 
+function isGitHubCliCredentialHelper(line: string): boolean {
+  const helperMatch = line.match(/^\s*helper\s*=\s*(.+?)\s*$/i);
+  if (!helperMatch) {
+    return false;
+  }
+
+  const helper = (helperMatch[1] ?? '').trim().replace(/^"(.*)"$/, '$1');
+  return /^!\s*(?:"[^"]*[\\/]+gh"|(?:\S*[\\/]+)?gh)\s+auth\s+git-credential(?:\s|$)/i.test(helper);
+}
+
 export function sanitizeGitConfig(
   gitconfig: string,
   home: string,
@@ -272,11 +291,13 @@ export function sanitizeGitConfig(
   const sanitized = [];
   let inGpgSection = false;
   let currentSection = '';
+  let currentSectionName = '';
 
   for (const line of lines) {
     const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
     if (sectionMatch) {
       const sectionName = (sectionMatch[1] ?? '').trim();
+      currentSectionName = sectionName;
       currentSection = ((sectionName.match(/^([^\s"]+)/)?.[1]) ?? '').toLowerCase();
       inGpgSection = /^gpg(?:\s+"[^"]+")?$/i.test(sectionName);
       if (stripGpg && inGpgSection) {
@@ -304,11 +325,23 @@ export function sanitizeGitConfig(
     if (stripGpg && currentSection === 'user' && /^\s*signingKey\s*=.*$/i.test(line)) {
       continue;
     }
+    if (currentSection === 'credential' && isGitHubCliCredentialHelper(line)) {
+      continue;
+    }
+    if (
+      /^url\s+"https:\/\/github\.com\/"$/i.test(currentSectionName)
+      && /^\s*insteadOf\s*=\s*git@github\.com:\s*$/i.test(line)
+    ) {
+      continue;
+    }
 
     sanitized.push(line);
   }
 
-  return appendSafeDirectories(sanitized, repoRoot).join('\n');
+  return [
+    ...appendSafeDirectories(sanitized, repoRoot),
+    ...MANAGED_GITHUB_GIT_CONFIG
+  ].join('\n');
 }
 
 export function hostHasGpgKeys(home: string, execFn: ExecSyncFn = execFileSync): boolean {
@@ -369,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({
@@ -418,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;
   }
 }
 
@@ -673,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;
@@ -930,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;
@@ -1148,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())
@@ -1158,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 = '';
@@ -1173,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
@@ -1231,7 +1144,9 @@ export function buildImage(
     runVerboseFn = runVerboseEngine,
     env = process.env,
     refresh = false,
-    lastRefresh
+    lastRefresh,
+    buildProxyArgs = [],
+    buildEnv
   }: {
     engine?: string;
     runFn?: EngineRunFn;
@@ -1240,6 +1155,8 @@ export function buildImage(
     env?: NodeJS.ProcessEnv;
     refresh?: boolean;
     lastRefresh?: number;
+    buildProxyArgs?: string[];
+    buildEnv?: NodeJS.ProcessEnv;
   } = {}
 ): void {
   const selectedEngine = engine ?? detectEngine({ engine: config.engine });
@@ -1252,9 +1169,10 @@ export function buildImage(
       runSafeFn,
       env,
       refresh,
-      lastRefresh
+      lastRefresh,
+      buildProxyArgs
     }),
-    { cwd: config.repoRoot }
+    { cwd: config.repoRoot, env: buildEnv }
   );
 }
 
@@ -1278,6 +1196,7 @@ export async function create(args: string[]): Promise<void> {
       memory: { type: 'string' },
       'no-refresh': { type: 'boolean' },
       'inherit-proxy': { type: 'boolean', short: 'P' },
+      'inherit-build-proxy': { type: 'boolean', short: 'B' },
       help: { type: 'boolean', short: 'h' }
     }
   });
@@ -1308,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);
@@ -1345,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}`);
     });
@@ -1363,6 +1291,15 @@ export async function create(args: string[]): Promise<void> {
     const needsImageBuild = signatureStale || refreshDue;
 
     if (needsImageBuild) {
+      if (values['inherit-build-proxy'] && effectiveConfig.dockerfile) {
+        throw new Error('Build proxy inheritance is unavailable with a custom sandbox Dockerfile.');
+      }
+      const buildProxy = prepareBuildProxy(
+        values['inherit-build-proxy'] ?? false,
+        process.env,
+        engine
+      );
+      if (values['inherit-build-proxy']) assertBuildProxyCompatibility(engine);
       const buildRefresh = !imageExists || refreshDue;
       const buildLastRefresh = buildRefresh ? now : currentLastRefresh || 0;
 
@@ -1379,7 +1316,13 @@ export async function create(args: string[]): Promise<void> {
           tools,
           preparedDockerfile.path,
           expectedImageSignature,
-          { engine, refresh: buildRefresh, lastRefresh: buildLastRefresh }
+          {
+            engine,
+            refresh: buildRefresh,
+            lastRefresh: buildLastRefresh,
+            buildProxyArgs: buildProxy.args,
+            buildEnv: buildProxy.env
+          }
         );
         p.log.success(
           refreshDue
@@ -1392,10 +1335,14 @@ export async function create(args: string[]): Promise<void> {
         if (refreshDue && !signatureStale && imageExists) {
           p.log.warn(
             'Scheduled sandbox image refresh failed; continuing with the existing image. ' +
-            commandErrorMessage(error)
+            redactBuildProxyValues(commandErrorMessage(error), buildProxy.redactionValues)
+            + (values['inherit-build-proxy'] ? ` ${buildProxyFailureHint(engine)}` : '')
           );
         } else {
-          throw error;
+          const hint = values['inherit-build-proxy'] ? `\n${buildProxyFailureHint(engine)}` : '';
+          throw new Error(
+            `${redactBuildProxyValues(commandErrorMessage(error), buildProxy.redactionValues)}${hint}`
+          );
         }
       }
     } else {
@@ -1410,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', [
@@ -1507,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}`);
           }
@@ -1543,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);
@@ -1551,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);
@@ -1643,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',
@@ -1739,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);