@fitlab-ai/agent-infra 0.9.0 → 0.9.2

package/dist/lib/sandbox/commands/create.js

@@ -6,13 +6,15 @@ import { execFileSync } 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.js';
 import { loadConfig } from '../config.js';
-import { assertValidBranchName, containerName, containerNameCandidates, parsePositiveIntegerOption, sandboxBranchLabel, sandboxImageConfigLabel, sandboxImageRefreshLabel, sandboxLabel, shareBranchDir, shareCommonDir, shellConfigDir, worktreeDirCandidates } from '../constants.js';
+import { assertValidBranchName, containerName, containerNameCandidates, parsePositiveIntegerOption, sandboxBranchLabel, sandboxImageConfigLabel, sandboxImageRefreshLabel, sandboxLabel, sandboxRuntimeCapabilityLabel, shareBranchDir, shareCommonDir, shellConfigDir, worktreeDirCandidates } from '../constants.js';
 import { prepareDockerfile } from '../dockerfile.js';
+import { assertBuildProxyCompatibility, buildProxyFailureHint, prepareBuildProxy, redactBuildProxyValues } from '../build-proxy.js';
 import { detectEngine, ensureDocker } from '../engine.js';
 import { commandForEngine, execEngine, run, runEngine, runOk, runOkEngine, runSafe, runSafeEngine, runVerboseEngine } from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
+import { createSandboxCapabilityPlan, runSandboxHooks, runBoundedSandboxHookCommand } from '../agent-client-reconciler.js';
 import { resolveTools, tmpfsSeedStagingPath, tmpfsSeedTargetPath, toolConfigDirCandidates } from '../tools.js';
 import { assertFreshSandboxReady, hydrateTmpfsSeedEntries, prepareTmpfsMounts } from '../recovery.js';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
@@ -21,35 +23,16 @@ import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.
 import { validateSelinuxDisableEnv } from '../engines/selinux.js';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
 import { ensureSandboxDiscoveryReadmes } from '../readme-scaffold.js';
+import { removeDirRecursive } from '../../remove-dir.js';
 import { prepareClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from '../credentials.js';
 import { detectHostTimezone } from '../host-timezone.js';
 import { buildImageSignature, buildSandboxImageArgs, isRefreshDisabled, isRefreshDue, parseImageLabels, parseRefreshTimestamp } from '../image-build.js';
-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.js';
 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
@@ -59,7 +42,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',
@@ -70,6 +55,15 @@ const HOST_PROXY_ENV_KEYS = [
     'no_proxy',
     'NO_PROXY'
 ];
+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:'
+];
 function resolveToolDirs(config, tools, branch) {
     return tools.map((tool) => {
         const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -158,6 +152,14 @@ function normalizeContainerHomeSeparators(content) {
     const containerHomePattern = new RegExp(`${escapeRegExp(CONTAINER_HOME)}\\S*`, 'g');
     return content.replace(containerHomePattern, (value) => value.replaceAll('\\', '/'));
 }
+function isGitHubCliCredentialHelper(line) {
+    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, home, { stripGpg = false, repoRoot = '' } = {}) {
     const posixHome = home.replaceAll('\\', '/');
     const normalizedGitconfig = gitconfig
@@ -170,10 +172,12 @@ export function sanitizeGitConfig(gitconfig, home, { stripGpg = false, repoRoot
     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) {
@@ -199,9 +203,19 @@ export function sanitizeGitConfig(gitconfig, home, { stripGpg = false, repoRoot
         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, execFn = execFileSync) {
     return currentKeyringFingerprint(home, execFn) !== null;
@@ -236,7 +250,7 @@ export function ensureShellConfigSymlinks(engine, container, execFn = execEngine
 }
 export function prepareHostShellConfig({ home, project, branch, repoRoot }) {
     const hostDir = hostShellConfigDir(home, project, branch);
-    fs.rmSync(hostDir, { recursive: true, force: true });
+    removeDirRecursive(hostDir);
     fs.mkdirSync(hostDir, { recursive: true });
     writeSanitizedGitconfig({
         home,
@@ -274,11 +288,19 @@ function normalizeWorktreePath(worktreePath) {
     if (!worktreePath) {
         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;
     }
 }
 export function getGitSigningKey({ home, repoPath = null, execFn = execFileSync } = {}) {
@@ -449,7 +471,7 @@ export function collectHostProxyEntries(env) {
     });
 }
 export function buildContainerEnvFile(resolvedTools, engine, runSafeEngineFn = runSafeEngine, options = {}) {
-    const { additionalEntries = [], mkdtempFn = fs.mkdtempSync, writeFileFn = fs.writeFileSync, chmodFn = fs.chmodSync, rmFn = fs.rmSync, tmpDir = os.tmpdir(), runSafeFn = runSafe } = options;
+    const { additionalEntries = [], mkdtempFn = fs.mkdtempSync, writeFileFn = fs.writeFileSync, chmodFn = fs.chmodSync, rmFn = removeDirRecursive, tmpDir = os.tmpdir(), runSafeFn = runSafe } = options;
     const entries = resolvedTools.flatMap(({ tool }) => Object.entries(tool.envVars ?? {}));
     entries.push(...additionalEntries);
     let ghToken = runSafeEngineFn(engine, 'gh', ['auth', 'token']);
@@ -673,141 +695,6 @@ export function ensureClaudeSettings(toolDir, hostHomeDir) {
         fs.writeFileSync(settingsPath, JSON.stringify(data, null, 4), 'utf8');
     }
 }
-function resolveHostCatalogPath(value, hostHomeDir) {
-    if (typeof value !== 'string' || value === '') {
-        return null;
-    }
-    let resolved;
-    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'];
-function removeCodexMcpServers(sandboxParsed) {
-    if (!Object.hasOwn(sandboxParsed, 'mcp_servers')) {
-        return false;
-    }
-    delete sandboxParsed.mcp_servers;
-    return true;
-}
-function inheritDisabledCodexFeatureFlags(sandboxParsed, hostParsed) {
-    if (!isJsonObjectRecord(hostParsed.features)) {
-        return false;
-    }
-    if (Object.hasOwn(sandboxParsed, 'features') && !isJsonObjectRecord(sandboxParsed.features)) {
-        return false;
-    }
-    let sandboxFeatures = sandboxParsed.features;
-    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, hostHomeDir, containerCodexDir = '/home/devuser/.codex') {
-    if (!hostHomeDir) {
-        return;
-    }
-    const hostConfigPath = path.join(hostHomeDir, '.codex', 'config.toml');
-    if (!fs.existsSync(hostConfigPath)) {
-        return;
-    }
-    let hostParsed;
-    try {
-        hostParsed = toml.parse(fs.readFileSync(hostConfigPath, 'utf8'));
-    }
-    catch {
-        return;
-    }
-    const sandboxConfigPath = path.join(toolDir, 'config.toml');
-    // This rewrites sandbox-side TOML and drops comments; the host config stays untouched.
-    let sandboxParsed = {};
-    if (fs.existsSync(sandboxConfigPath)) {
-        try {
-            sandboxParsed = toml.parse(fs.readFileSync(sandboxConfigPath, 'utf8'));
-        }
-        catch {
-            return;
-        }
-    }
-    let changed = removeCodexMcpServers(sandboxParsed);
-    changed = inheritDisabledCodexFeatureFlags(sandboxParsed, hostParsed) || changed;
-    const inheritSpecs = [
-        ['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) {
-    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, hostHomeDir) {
     if (!hostHomeDir) {
         return;
@@ -868,7 +755,7 @@ function stripManagedSandboxAliasBlocks(content) {
     const blockPattern = new RegExp(`${escapeRegExp(SANDBOX_ALIAS_BLOCK_BEGIN)}[\\s\\S]*?${escapeRegExp(SANDBOX_ALIAS_BLOCK_END)}\\n?`, 'g');
     return content.replace(blockPattern, '').trimEnd();
 }
-function isLegacyManagedSandboxAliasFile(content) {
+function isLegacyManagedSandboxAliasFile(content, aliases) {
     const lines = content
         .split(/\r?\n/)
         .map((line) => line.trim())
@@ -876,19 +763,25 @@ function isLegacyManagedSandboxAliasFile(content) {
     if (lines.length === 0) {
         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) {
+function registrySandboxAliases() {
+    return listAgentClientAdapters().flatMap((adapter) => adapter.sandbox.aliases);
+}
+function renderSandboxAliases(aliases) {
+    return `${aliases.map((alias) => `alias ${alias.name}='${alias.command.replaceAll("'", "'\\''")}'`).join('\n')}\n`;
+}
+export function ensureSandboxAliasesFile(home, aliases = registrySandboxAliases()) {
     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 = '';
     if (!created) {
         existing = fs.readFileSync(aliasesPath, 'utf8');
     }
-    const userContent = isLegacyManagedSandboxAliasFile(existing)
+    const userContent = isLegacyManagedSandboxAliasFile(existing, aliases)
         ? ''
         : stripManagedSandboxAliasBlocks(existing);
     const nextContent = userContent
@@ -928,7 +821,7 @@ export function buildTmpfsRunArgs(containerMount, tmpfs) {
     const size = tmpfs.size ?? '512m';
     return ['--tmpfs', `${containerMount}:rw,size=${size}`];
 }
-export function buildImage(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, runVerboseFn = runVerboseEngine, env = process.env, refresh = false, lastRefresh } = {}) {
+export function buildImage(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, runVerboseFn = runVerboseEngine, env = process.env, refresh = false, lastRefresh, buildProxyArgs = [], buildEnv } = {}) {
     const selectedEngine = engine ?? detectEngine({ engine: config.engine });
     runVerboseFn(selectedEngine, 'docker', buildSandboxImageArgs(config, tools, dockerfilePath, imageSignature, {
         engine: selectedEngine,
@@ -936,8 +829,9 @@ export function buildImage(config, tools, dockerfilePath, imageSignature, { engi
         runSafeFn,
         env,
         refresh,
-        lastRefresh
-    }), { cwd: config.repoRoot });
+        lastRefresh,
+        buildProxyArgs
+    }), { cwd: config.repoRoot, env: buildEnv });
 }
 function readImageLabels(config, engine) {
     return parseImageLabels(runSafeEngine(engine, 'docker', [
@@ -958,6 +852,7 @@ export async function create(args) {
             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' }
         }
     });
@@ -984,15 +879,14 @@ export async function create(args) {
     };
     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);
@@ -1011,6 +905,16 @@ export async function create(args) {
     }
     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) => {
             p.log.info(`  ${detail}`);
         });
@@ -1027,6 +931,12 @@ export async function create(args) {
             && isRefreshDue(currentLastRefresh, now, effectiveConfig.refreshIntervalDays);
         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;
             p.log.step(refreshDue
@@ -1035,7 +945,13 @@ export async function create(args) {
                     ? 'Rebuilding stale image...'
                     : 'Building image for first use...');
             try {
-                buildImage(effectiveConfig, tools, preparedDockerfile.path, expectedImageSignature, { engine, refresh: buildRefresh, lastRefresh: buildLastRefresh });
+                buildImage(effectiveConfig, tools, preparedDockerfile.path, expectedImageSignature, {
+                    engine,
+                    refresh: buildRefresh,
+                    lastRefresh: buildLastRefresh,
+                    buildProxyArgs: buildProxy.args,
+                    buildEnv: buildProxy.env
+                });
                 p.log.success(refreshDue
                     ? 'Image refreshed'
                     : imageExists
@@ -1045,10 +961,12 @@ export async function create(args) {
             catch (error) {
                 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}`);
                 }
             }
         }
@@ -1063,7 +981,7 @@ export async function create(args) {
                         if (fs.readdirSync(worktree).length > 0) {
                             return `Worktree exists at ${worktree}`;
                         }
-                        fs.rmSync(worktree, { recursive: true, force: true });
+                        removeDirRecursive(worktree);
                     }
                     const branchExists = runOk('git', [
                         '-C',
@@ -1152,7 +1070,7 @@ export async function create(args) {
                             runSafeEngine(engine, 'docker', ['rm', name]);
                         }
                     }
-                    const aliasesFile = ensureSandboxAliasesFile(effectiveConfig.home);
+                    const aliasesFile = ensureSandboxAliasesFile(effectiveConfig.home, capabilityPlan.aliases);
                     if (aliasesFile.created) {
                         message(`Created default sandbox aliases at ${aliasesFile.path}`);
                     }
@@ -1181,6 +1099,24 @@ export async function create(args) {
                     let hostShellConfig;
                     let tmpfsSeedPlan = [];
                     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);
@@ -1189,11 +1125,6 @@ export async function create(args) {
                             // 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);
@@ -1267,6 +1198,8 @@ export async function create(args) {
                             sandboxLabel(effectiveConfig),
                             '--label',
                             `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
+                            '--label',
+                            `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
                             ...coreVolumes,
                             ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
                             '-v',
@@ -1344,6 +1277,17 @@ export async function create(args) {
                             runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
                         }
                     }
+                    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/dist/lib/sandbox/commands/enter.js

@@ -2,6 +2,7 @@ import { loadConfig } from '../config.js';
 import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from '../constants.js';
 import { detectEngine } from '../engine.js';
 import { ensureSandboxReady } from '../recovery.js';
+import { createSandboxCapabilityPlan, runBoundedSandboxHookCommand, runSandboxHooks } from '../agent-client-reconciler.js';
 import { formatCredentialWarnings, formatRemaining, hasClaudeProviderAuth, reconcileClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from '../credentials.js';
 import { runInteractiveEngine } from '../shell.js';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
@@ -123,7 +124,22 @@ export async function enter(args) {
     });
     const container = ready.container;
     const cmd = parsed.command;
-    if (config.tools.includes('claude-code')) {
+    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 (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/dist/lib/sandbox/commands/prune.js

@@ -10,7 +10,7 @@ import { hostJoin } from '../engines/wsl2-paths.js';
 import { removeManagedDir, removeWorktreeDir } from '../managed-fs.js';
 import { parseLabels } from './ls.js';
 import { runEngine, runSafe } from '../shell.js';
-import { resolveTools } from '../tools.js';
+import { createSandboxCapabilityPlan } from '../agent-client-reconciler.js';
 const USAGE = `Usage: ai sandbox prune [--dry-run]`;
 function listChildDirs(base) {
     if (!fs.existsSync(base)) {
@@ -129,7 +129,7 @@ export async function prune(args) {
         return;
     }
     const config = loadConfig();
-    const tools = resolveTools(config);
+    const tools = [...createSandboxCapabilityPlan(config).cleanupInventory];
     const engine = detectEngine(config);
     const psArgs = [
         'ps',

package/dist/lib/sandbox/commands/rebuild.js

@@ -9,15 +9,17 @@ import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shel
 import { pruneSandboxDanglingImages } from '../image-prune.js';
 import { resolveTools } from '../tools.js';
 import { buildImageSignature, buildSandboxImageArgs, parseImageLabels, parseRefreshTimestamp } from '../image-build.js';
-const USAGE = `Usage: ai sandbox rebuild [--quiet] [--refresh]`;
-export function buildArgs(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, env = process.env, refresh = false, lastRefresh } = {}) {
+import { assertBuildProxyCompatibility, buildProxyFailureHint, prepareBuildProxy, redactBuildProxyValues } from '../build-proxy.js';
+const USAGE = `Usage: ai sandbox rebuild [--quiet] [--refresh] [--inherit-build-proxy|-B]`;
+export function buildArgs(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, env = process.env, refresh = false, lastRefresh, buildProxyArgs = [] } = {}) {
     return buildSandboxImageArgs(config, tools, dockerfilePath, imageSignature, {
         engine: engine ?? detectEngine(config),
         runFn,
         runSafeFn,
         env,
         refresh,
-        lastRefresh
+        lastRefresh,
+        buildProxyArgs
     });
 }
 function readExistingLastRefresh(config, engine) {
@@ -41,6 +43,7 @@ export async function rebuild(args) {
         options: {
             refresh: { type: 'boolean' },
             quiet: { type: 'boolean', short: 'q' },
+            'inherit-build-proxy': { type: 'boolean', short: 'B' },
             help: { type: 'boolean', short: 'h' }
         }
     });
@@ -56,6 +59,12 @@ export async function rebuild(args) {
     const refresh = values.refresh ?? false;
     const engine = detectEngine(config);
     await ensureDocker(config, undefined);
+    if (values['inherit-build-proxy'] && config.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 lastRefresh = refresh ? Date.now() : readExistingLastRefresh(config, engine);
     p.intro(pc.cyan('Rebuilding sandbox image'));
     try {
@@ -65,9 +74,11 @@ export async function rebuild(args) {
             runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, {
                 engine,
                 refresh,
-                lastRefresh
+                lastRefresh,
+                buildProxyArgs: buildProxy.args
             }), {
-                cwd: config.repoRoot
+                cwd: config.repoRoot,
+                env: buildProxy.env
             });
             spinner.stop(pc.green('Sandbox image rebuilt'));
         }
@@ -76,12 +87,18 @@ export async function rebuild(args) {
             runVerboseEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, {
                 engine,
                 refresh,
-                lastRefresh
-            }), { cwd: config.repoRoot });
+                lastRefresh,
+                buildProxyArgs: buildProxy.args
+            }), { cwd: config.repoRoot, env: buildProxy.env });
             p.log.success(pc.green('Sandbox image rebuilt'));
         }
         pruneSandboxDanglingImages(config, engine);
     }
+    catch (error) {
+        const message = redactBuildProxyValues(error instanceof Error ? error.message : String(error), buildProxy.redactionValues);
+        const hint = values['inherit-build-proxy'] ? `\n${buildProxyFailureHint(engine)}` : '';
+        throw new Error(`${message}${hint}`);
+    }
     finally {
         preparedDockerfile.cleanup();
     }