@fitlab-ai/agent-infra 0.9.3 → 0.9.4

package/lib/agent-clients/adapter.ts

@@ -12,6 +12,7 @@ import {
 } from '../sandbox/tool-types.ts';
 import type {
   AgentClientSandboxRecoveryCheck,
+  AgentClientSandboxImageDescriptor,
   AgentClientSandboxDescriptor,
   SandboxAlias,
   SandboxTool,
@@ -50,12 +51,21 @@ type AgentClientSeedCommand = Readonly<{
   target: string;
 }>;
 
+type AgentClientCustomCommandDescriptor = Readonly<{
+  target: string;
+  frontmatter: Readonly<Record<string, string | boolean>>;
+  argumentsToken?: string;
+  includeUsage?: boolean;
+  inheritDisableModelInvocation?: boolean;
+}>;
+
 type AgentClientProjectDescriptor = Readonly<{
   ownedPathPrefixes: readonly string[];
   managed: readonly string[];
   merged: readonly string[];
   ejected: readonly string[];
   seedCommands: readonly AgentClientSeedCommand[];
+  customCommand?: AgentClientCustomCommandDescriptor;
 }>;
 
 type AgentClientAdapter = Readonly<{
@@ -81,12 +91,59 @@ type AgentClientManifestEntry = Readonly<{
   managed: readonly string[];
   merged: readonly string[];
   ejected: readonly string[];
+  customCommand?: AgentClientCustomCommandDescriptor;
 }>;
 
 const PROJECT_ASSET_CATEGORIES = ['managed', 'merged', 'ejected'] as const;
 const MAX_SANDBOX_HOOK_TIMEOUT_MS = 300_000;
 const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 
+function freezeSandboxImageDescriptor(
+  id: AgentClientId,
+  value: AgentClientSandboxImageDescriptor | undefined
+): AgentClientSandboxImageDescriptor | undefined {
+  if (value === undefined) return undefined;
+  const keys = value && typeof value === 'object' && !Array.isArray(value)
+    ? Object.keys(value)
+    : [];
+  const fragment = value?.dockerfileFragment;
+  const exclusions = value?.dotfilesExclusions;
+  const validExclusion = (entry: unknown): entry is string => {
+    if (
+      typeof entry !== 'string'
+      || entry === ''
+      || entry.startsWith('/')
+      || entry.endsWith('/')
+      || entry.includes('\\')
+      || /[*?[\]]/.test(entry)
+    ) {
+      return false;
+    }
+    return entry.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+  };
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || keys.length === 0
+    || keys.some((key) => !['dockerfileFragment', 'dotfilesExclusions'].includes(key))
+    || (fragment !== undefined && (typeof fragment !== 'string' || !TOOL_ID_PATTERN.test(fragment)))
+    || (exclusions !== undefined && (
+      !Array.isArray(exclusions)
+      || exclusions.some((entry) => !validExclusion(entry))
+      || new Set(exclusions).size !== exclusions.length
+    ))
+  ) {
+    throw new Error(`Agent Client '${id}' has an invalid sandbox image descriptor`);
+  }
+  return Object.freeze({
+    ...(fragment === undefined ? {} : { dockerfileFragment: fragment }),
+    ...(exclusions === undefined
+      ? {}
+      : { dotfilesExclusions: Object.freeze([...exclusions]) })
+  });
+}
+
 function freezeRecoveryProbe(
   id: AgentClientId,
   checkId: string,
@@ -394,9 +451,68 @@ function defineAgentClientAdapter(
     });
   });
 
+  let customCommand: AgentClientCustomCommandDescriptor | undefined;
+  if (candidate.project.customCommand !== undefined) {
+    const descriptor = candidate.project.customCommand;
+    const placeholders = typeof descriptor?.target === 'string'
+      ? [...descriptor.target.matchAll(/\$\{([^}]+)\}/g)].map((match) => match[1])
+      : [];
+    const targetProbe = typeof descriptor?.target === 'string'
+      ? descriptor.target.replaceAll('${skillName}', 'skill')
+      : '';
+    const frontmatter = descriptor?.frontmatter;
+    if (
+      !descriptor
+      || typeof descriptor !== 'object'
+      || placeholders.length !== 1
+      || placeholders[0] !== 'skillName'
+      || targetProbe.includes('${')
+      || !isProjectRelativeLiteral(targetProbe)
+      || !paths.some((prefix) => targetProbe.startsWith(prefix))
+      || !frontmatter
+      || typeof frontmatter !== 'object'
+      || Array.isArray(frontmatter)
+      || Object.values(frontmatter).some((value) =>
+        typeof value !== 'string' && typeof value !== 'boolean'
+      )
+      || (
+        descriptor.argumentsToken !== undefined
+        && (
+          typeof descriptor.argumentsToken !== 'string'
+          || descriptor.argumentsToken === ''
+          || /[\r\n]/.test(descriptor.argumentsToken)
+        )
+      )
+      || (
+        descriptor.includeUsage !== undefined
+        && typeof descriptor.includeUsage !== 'boolean'
+      )
+      || (
+        descriptor.inheritDisableModelInvocation !== undefined
+        && typeof descriptor.inheritDisableModelInvocation !== 'boolean'
+      )
+    ) {
+      throw new Error(`Agent Client '${candidate.id}' has an invalid custom command`);
+    }
+    customCommand = Object.freeze({
+      target: descriptor.target,
+      frontmatter: Object.freeze({ ...frontmatter }),
+      ...(descriptor.argumentsToken === undefined
+        ? {}
+        : { argumentsToken: descriptor.argumentsToken }),
+      ...(descriptor.includeUsage === undefined
+        ? {}
+        : { includeUsage: descriptor.includeUsage }),
+      ...(descriptor.inheritDisableModelInvocation === undefined
+        ? {}
+        : { inheritDisableModelInvocation: descriptor.inheritDisableModelInvocation })
+    });
+  }
+
   if (!candidate.sandbox || typeof candidate.sandbox.createTool !== 'function') {
     throw new Error(`Agent Client '${candidate.id}' requires a sandbox descriptor`);
   }
+  const image = freezeSandboxImageDescriptor(candidate.id, candidate.sandbox.image);
   const hookIds = new Set<string>();
   const hooks = Object.freeze(candidate.sandbox.hooks.map((hook) => {
     if (
@@ -515,9 +631,16 @@ function defineAgentClientAdapter(
     project: Object.freeze({
       ownedPathPrefixes: Object.freeze(paths),
       ...projectAssets,
-      seedCommands: Object.freeze(seedCommands)
+      seedCommands: Object.freeze(seedCommands),
+      ...(customCommand === undefined ? {} : { customCommand })
     }),
-    sandbox: Object.freeze({ createTool, aliases, hooks, recoveryChecks })
+    sandbox: Object.freeze({
+      createTool,
+      aliases,
+      hooks,
+      recoveryChecks,
+      ...(image === undefined ? {} : { image })
+    })
   });
 }
 
@@ -525,6 +648,7 @@ export { defineAgentClientAdapter };
 export type {
   AgentClientAdapter,
   AgentClientCapabilities,
+  AgentClientCustomCommandDescriptor,
   AgentClientDelegationEvidence,
   AgentClientManifestEntry,
   AgentClientModelSelectionContext,

package/lib/{sandbox/credentials.ts → agent-clients/adapters/claude-code-credentials.ts}

@@ -2,7 +2,8 @@ import { execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { hostJoin } from './engines/wsl2-paths.ts';
+import { hostJoin } from '../../sandbox/engines/wsl2-paths.ts';
+import { redactCommandError } from '../../sandbox/redaction.ts';
 
 type ExecFn = (file: string, args: string[], options?: Record<string, unknown>) => string | Buffer | void;
 type ReadFn = (targetPath: string) => string;
@@ -112,12 +113,6 @@ type CredentialPayload = {
 
 const LOCKED_PATTERN = /errSecInteractionNotAllowed|User interaction is not allowed/i;
 const NOT_FOUND_PATTERN = /errSecItemNotFound|specified item could not be found/i;
-const REDACTION_PATTERNS = [
-  { pattern: /\{[^{}]*"claudeAiOauth"[\s\S]*?\}\s*\}/g, replacement: '[REDACTED credentials blob]' },
-  { pattern: /sk-ant-[A-Za-z0-9_-]{20,}/g, replacement: '[REDACTED claude token]' },
-  { pattern: /gh[psoru]_[A-Za-z0-9]{30,}/g, replacement: '[REDACTED github token]' },
-  { pattern: /Bearer\s+[A-Za-z0-9._~+/=-]{20,}/gi, replacement: 'Bearer [REDACTED]' }
-];
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -131,18 +126,8 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : 'unknown error';
 }
 
-export function redactCommandError(text: unknown): string {
-  if (!text || typeof text !== 'string') {
-    return '';
-  }
-
-  return REDACTION_PATTERNS.reduce(
-    (result, { pattern, replacement }) => result.replace(pattern, replacement),
-    text
-  );
-}
-
 export const redactSecurityOutput = redactCommandError;
+export { redactCommandError };
 
 function extractStderrSafely(error: unknown): string {
   const stderr = typeof error === 'object' && error !== null && 'stderr' in error

package/lib/agent-clients/adapters/claude-code-refresh.ts

@@ -0,0 +1,128 @@
+import { homedir } from 'node:os';
+import { parseArgs } from 'node:util';
+import {
+  buildLockedGuidance,
+  discoverProjects,
+  formatCredentialWarnings,
+  formatRemaining,
+  reconcileClaudeCredentials,
+  redactCommandError,
+  validateClaudeCredentialsEnvOverride
+} from './claude-code-credentials.ts';
+import { runProbe } from '../../sandbox/shell.ts';
+
+const USAGE = 'Usage: ai sandbox refresh';
+
+type ReconcileOptions = NonNullable<Parameters<typeof reconcileClaudeCredentials>[1]>;
+
+type RefreshDeps = Partial<ReconcileOptions> & {
+  spawnFn?: typeof runProbe;
+  discoverFn?: typeof discoverProjects;
+  writeStdout?: (chunk: string) => unknown;
+  writeStderr?: (chunk: string) => unknown;
+};
+
+export function probeClaudeStatus(spawnFn: typeof runProbe = runProbe): { ok: boolean; stderr: string; error: string | null } {
+  const result = spawnFn('claude', ['/status'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 30_000
+  });
+  return {
+    ok: result.status === 0,
+    stderr: result.stderr?.toString() ?? '',
+    error: result.error?.message ?? null
+  };
+}
+
+export async function runClaudeCodeRefresh(args: string[], deps: RefreshDeps = {}): Promise<number> {
+  const {
+    spawnFn = runProbe,
+    execFn,
+    readFn,
+    existsFn,
+    writeFn,
+    writeHostFn,
+    discoverFn = discoverProjects,
+    writeStdout = (chunk: string) => process.stdout.write(chunk),
+    writeStderr = (chunk: string) => process.stderr.write(chunk)
+  } = deps;
+
+  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    writeStdout(`${USAGE}\n`);
+    return 0;
+  }
+
+  const { positionals } = parseArgs({ args, allowPositionals: true, strict: true });
+  if (positionals.length > 0) {
+    throw new Error(USAGE);
+  }
+  validateClaudeCredentialsEnvOverride();
+
+  const home = homedir();
+  if (!home) {
+    throw new Error('sandbox: home directory is required');
+  }
+
+  const projects = discoverFn(home);
+  if (projects.length === 0) {
+    writeStdout('No project credentials to refresh.\n');
+    return 0;
+  }
+
+  const reconcileOptions = { execFn, readFn, existsFn, writeFn, writeHostFn, projects };
+  let result = reconcileClaudeCredentials(home, reconcileOptions);
+  if (result.status === 'STALE_ACCESS' && result.authoritative === null) {
+    writeStdout('Host credentials appear stale; probing claude /status to trigger refresh...\n');
+    const probe = probeClaudeStatus(spawnFn);
+    if (!probe.ok) {
+      writeStderr(`Probe failed: ${redactCommandError(probe.stderr || probe.error || 'unknown error')}\n`);
+      writeStderr('Run "claude /login" on the host to renew credentials.\n');
+      return 1;
+    }
+    writeStdout('Probe succeeded; re-inspecting host credentials.\n');
+    result = reconcileClaudeCredentials(home, reconcileOptions);
+  }
+
+  if (result.status === 'MISSING') {
+    writeStderr('No Claude Code credentials found on host.\n');
+    writeStderr('Run "claude /login" on the host to authenticate.\n');
+    return 1;
+  }
+
+  if (result.status === 'KEYCHAIN_LOCKED') {
+    writeStderr(`${buildLockedGuidance()}\n`);
+    return 1;
+  }
+
+  if (result.status === 'KEYCHAIN_ERROR') {
+    writeStderr(`Host keychain error: ${redactCommandError(result.detail || 'unknown error')}\n`);
+    writeStderr(`${buildLockedGuidance()}\n`);
+    return 1;
+  }
+
+  if (result.status === 'KEYCHAIN_WRITE_FAILED') {
+    writeStderr(`[host] keychain write failed: ${formatCredentialWarnings(result.warnings) || 'unknown error'}\n`);
+    return 1;
+  }
+
+  if (result.status !== 'OK') {
+    writeStderr('Host credentials still invalid after probe; run "claude /login".\n');
+    return 1;
+  }
+
+  if (result.authoritative && result.authoritative !== 'host' && result.hostWritten) {
+    writeStdout(`[host] reconciled from ${result.authoritative}\n`);
+  }
+
+  for (const project of projects) {
+    const action = result.filesWritten.includes(project) ? 'updated' : 'unchanged';
+    writeStdout(`[${project}] ${action}; expires in ${formatRemaining(result.expiresAt)}\n`);
+  }
+
+  for (const failure of result.fileErrors) {
+    writeStderr(`[${failure.project}] sync failed: ${failure.error}\n`);
+  }
+
+  return result.fileErrors.length > 0 ? 1 : 0;
+}

package/lib/agent-clients/adapters/claude-code-sandbox.ts

@@ -0,0 +1,295 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type {
+  AgentClientSandboxHook,
+  SandboxHookCreateContext,
+  SandboxHookEnterContext
+} from '../../sandbox/tool-types.ts';
+import {
+  formatCredentialWarnings,
+  formatRemaining,
+  hasClaudeProviderAuth,
+  inspectClaudeKeychainStatus,
+  prepareClaudeCredentials,
+  reconcileClaudeCredentials,
+  redactCommandError,
+  validateClaudeCredentialsEnvOverride
+} from './claude-code-credentials.ts';
+
+type JsonObject = Record<string, unknown>;
+
+function readHostJsonSafe(filePath: string): JsonObject | null {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as JsonObject
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+const CLAUDE_SETTINGS_INHERIT_TOP_LEVEL_KEYS = [
+  'model',
+  'fallbackModel',
+  'availableModels',
+  'modelOverrides',
+  'enforceAvailableModels',
+  'advisorModel',
+  'apiKeyHelper',
+  'effortLevel'
+];
+
+function isJsonObjectRecord(value: unknown): value is JsonObject {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeMissingStringEnvFields(target: JsonObject, source: JsonObject): boolean {
+  if (!isJsonObjectRecord(source.env)) return false;
+  if (Object.hasOwn(target, 'env') && !isJsonObjectRecord(target.env)) return false;
+
+  let targetEnv = target.env as JsonObject | undefined;
+  let changed = false;
+  for (const [key, value] of Object.entries(source.env)) {
+    if (typeof value !== 'string' || value === '') continue;
+    if (!targetEnv) {
+      targetEnv = {};
+      target.env = targetEnv;
+    }
+    if (!Object.hasOwn(targetEnv, key)) {
+      targetEnv[key] = value;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function mergeMissingTopLevelSettings(target: JsonObject, source: JsonObject): boolean {
+  let changed = false;
+  for (const key of CLAUDE_SETTINGS_INHERIT_TOP_LEVEL_KEYS) {
+    if (!Object.hasOwn(source, key) || Object.hasOwn(target, key)) continue;
+    const value = source[key];
+    if (value === null || value === undefined || value === '') continue;
+    target[key] = value;
+    changed = true;
+  }
+  return changed;
+}
+
+function requireCreateContext(
+  context: SandboxHookCreateContext | undefined,
+  hookId: string
+): SandboxHookCreateContext {
+  if (!context) throw new Error(`${hookId} requires create context`);
+  return context;
+}
+
+function requireEnterContext(
+  context: SandboxHookEnterContext | undefined,
+  hookId: string
+): SandboxHookEnterContext {
+  if (!context) throw new Error(`${hookId} requires enter context`);
+  return context;
+}
+
+export function ensureClaudeOnboarding(toolDir: string, hostHomeDir?: string): void {
+  const claudeJsonPath = path.join(toolDir, '.claude.json');
+  let data: JsonObject & {
+    hasCompletedOnboarding?: boolean;
+    projects?: Record<string, { hasTrustDialogAccepted?: boolean }>;
+    model?: string;
+  } = {};
+  if (fs.existsSync(claudeJsonPath)) {
+    try {
+      data = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8')) as typeof data;
+    } catch {
+      // Malformed JSON is replaced with a valid managed sandbox baseline.
+    }
+  }
+  let changed = false;
+  if (!data.hasCompletedOnboarding) {
+    data.hasCompletedOnboarding = true;
+    changed = true;
+  }
+  if (!data.projects) {
+    data.projects = {};
+    changed = true;
+  }
+  if (!data.projects['/workspace']) {
+    data.projects['/workspace'] = {};
+    changed = true;
+  }
+  if (!data.projects['/workspace'].hasTrustDialogAccepted) {
+    data.projects['/workspace'].hasTrustDialogAccepted = true;
+    changed = true;
+  }
+  if (hostHomeDir) {
+    const hostClaudeJson = readHostJsonSafe(path.join(hostHomeDir, '.claude.json'));
+    if (
+      hostClaudeJson
+      && typeof hostClaudeJson.model === 'string'
+      && hostClaudeJson.model !== ''
+      && !Object.hasOwn(data, 'model')
+    ) {
+      data.model = hostClaudeJson.model;
+      changed = true;
+    }
+    if (hostClaudeJson) {
+      for (const key of Object.keys(hostClaudeJson)) {
+        if (
+          /^unpin.*LaunchEffort$/.test(key)
+          && hostClaudeJson[key] === true
+          && !Object.hasOwn(data, key)
+        ) {
+          data[key] = true;
+          changed = true;
+        }
+      }
+    }
+  }
+  if (changed) fs.writeFileSync(claudeJsonPath, JSON.stringify(data, null, 4), 'utf8');
+}
+
+export function ensureClaudeSettings(toolDir: string, hostHomeDir?: string): void {
+  const settingsPath = path.join(toolDir, 'settings.json');
+  let data: JsonObject & { skipDangerousModePermissionPrompt?: boolean } = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      data = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) as typeof data;
+    } catch {
+      // Malformed JSON is replaced with a valid managed sandbox baseline.
+    }
+  }
+  let changed = false;
+  if (data.skipDangerousModePermissionPrompt !== true) {
+    data.skipDangerousModePermissionPrompt = true;
+    changed = true;
+  }
+  if (hostHomeDir) {
+    const hostSettings = readHostJsonSafe(path.join(hostHomeDir, '.claude', 'settings.json'));
+    if (hostSettings) {
+      changed = mergeMissingStringEnvFields(data, hostSettings) || changed;
+      changed = mergeMissingTopLevelSettings(data, hostSettings) || changed;
+    }
+  }
+  if (changed) fs.writeFileSync(settingsPath, JSON.stringify(data, null, 4), 'utf8');
+}
+
+export function formatCredentialSyncStatus(
+  result: ReturnType<typeof reconcileClaudeCredentials>,
+  isTTY = process.stderr.isTTY,
+  providerAuthAvailable = false
+): string | null {
+  if (providerAuthAvailable && (result.status === 'STALE_ACCESS' || result.status === 'MISSING')) return null;
+  if (result.status === 'STALE_ACCESS') {
+    return 'Warning: Claude Code credentials on host appear stale. Run "ai sandbox refresh" or "claude /login" to renew.\n';
+  }
+  if (result.status === 'MISSING') {
+    return 'Warning: Claude Code credentials missing on host. Run "claude /login" to authenticate.\n';
+  }
+  if (result.status === 'KEYCHAIN_WRITE_FAILED') {
+    return `Warning: A sandbox refresh produced newer credentials but host Keychain write failed (${formatCredentialWarnings(result.warnings)}). Run "ai sandbox refresh" again or "claude /status" on the host to retry.\n`;
+  }
+  if (result.status === 'KEYCHAIN_LOCKED' || result.status === 'KEYCHAIN_ERROR') {
+    return 'Warning: Host keychain is unavailable; Claude credential sync skipped. Run "ai sandbox refresh" for details.\n';
+  }
+  if (result.status === 'OK' && result.authoritative !== 'host') {
+    const message = `Synced Claude Code credentials from sandbox refresh back to host (expires in ${formatRemaining(result.expiresAt)})`;
+    return isTTY ? `\x1b[2m${message}\x1b[0m\n` : `${message}\n`;
+  }
+  if (result.status === 'OK' && result.filesWritten.length > 0) {
+    const message = `Synced Claude Code credentials from host Keychain (expires in ${formatRemaining(result.expiresAt)})`;
+    return isTTY ? `\x1b[2m${message}\x1b[0m\n` : `${message}\n`;
+  }
+  return null;
+}
+
+const claudeCodeCredentialPreflightHook: AgentClientSandboxHook = {
+  id: 'claude-code-credential-preflight',
+  phase: 'prepare',
+  run: async ({ create }) => {
+    const { hostHome, hostEnv, project, resolvedTools } = requireCreateContext(
+      create,
+      'claude-code-credential-preflight'
+    );
+    try {
+      validateClaudeCredentialsEnvOverride(hostEnv);
+      const outcome = prepareClaudeCredentials(
+        hostHome,
+        project,
+        [...resolvedTools],
+        undefined,
+        undefined,
+        (home) => inspectClaudeKeychainStatus(home, undefined, { envFn: () => ({ ...hostEnv }) })
+      );
+      if (outcome.status === 'SKIPPED') {
+        return {
+          status: 'warning',
+          message: 'Claude Code credentials not found on host - creating this sandbox WITHOUT Claude Code credentials.\n'
+            + '  Claude Code is still installed in the image but will not be authenticated.\n'
+            + '  To enable it: run "claude" once on the host to complete login, then re-run "ai sandbox create".'
+        };
+      }
+      return { status: 'ready' };
+    } catch (error) {
+      return {
+        status: 'fatal',
+        message: redactCommandError(error instanceof Error ? error.message : 'unknown credential error')
+      };
+    }
+  }
+};
+
+const claudeCodeBeforeContainerCreateHook: AgentClientSandboxHook = {
+  id: 'claude-code-before-container-create',
+  phase: 'before-container-create',
+  run: async ({ create }) => {
+    const { hostHome, resolvedTools } = requireCreateContext(
+      create,
+      'claude-code-before-container-create'
+    );
+    const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
+    if (claudeCodeEntry) {
+      ensureClaudeOnboarding(claudeCodeEntry.dir, hostHome);
+      ensureClaudeSettings(claudeCodeEntry.dir, hostHome);
+    }
+    return { status: 'ready' };
+  }
+};
+
+const claudeCodeBeforeEnterHook: AgentClientSandboxHook = {
+  id: 'claude-code-before-enter',
+  phase: 'before-enter',
+  run: async ({ enter }) => {
+    const { hostHome, hostEnv } = requireEnterContext(enter, 'claude-code-before-enter');
+    try {
+      validateClaudeCredentialsEnvOverride(hostEnv);
+    } catch (error) {
+      return {
+        status: 'fatal',
+        message: redactCommandError(error instanceof Error ? error.message : 'invalid credentials override')
+      };
+    }
+    try {
+      const providerAuthAvailable = hasClaudeProviderAuth(hostHome);
+      const result = reconcileClaudeCredentials(hostHome, { envFn: () => ({ ...hostEnv }) });
+      const message = formatCredentialSyncStatus(result, process.stderr.isTTY, providerAuthAvailable);
+      return {
+        status: 'ready',
+        ...(message === null ? {} : { message })
+      };
+    } catch (error) {
+      return {
+        status: 'warning',
+        message: `Failed to sync Claude Code credentials: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}`
+      };
+    }
+  }
+};
+
+export {
+  claudeCodeBeforeContainerCreateHook,
+  claudeCodeBeforeEnterHook,
+  claudeCodeCredentialPreflightHook
+};

package/lib/agent-clients/adapters/claude-code.ts

@@ -1,5 +1,10 @@
 import { defineAgentClientAdapter } from '../adapter.ts';
 import { hostJoin } from '../../sandbox/engines/wsl2-paths.ts';
+import {
+  claudeCodeBeforeContainerCreateHook,
+  claudeCodeBeforeEnterHook,
+  claudeCodeCredentialPreflightHook
+} from './claude-code-sandbox.ts';
 
 const claudeCodeAdapter = defineAgentClientAdapter({
   id: 'claude-code',
@@ -26,7 +31,7 @@ const claudeCodeAdapter = defineAgentClientAdapter({
   },
   project: {
     ownedPathPrefixes: ['.claude/'],
-    managed: ['.claude/commands/', '.claude/agents/'],
+    managed: ['.claude/commands/', '.claude/agents/', '.claude/rules/'],
     merged: ['.claude/settings.json'],
     ejected: [],
     seedCommands: [{
@@ -35,9 +40,18 @@ const claudeCodeAdapter = defineAgentClientAdapter({
         'zh-CN': '.claude/commands/update-agent-infra.zh-CN.md'
       },
       target: '.claude/commands/update-agent-infra.md'
-    }]
+    }],
+    customCommand: {
+      target: '.claude/commands/${skillName}.md',
+      frontmatter: {},
+      includeUsage: true,
+      inheritDisableModelInvocation: true
+    }
   },
   sandbox: {
+    image: {
+      dockerfileFragment: 'claude-code'
+    },
     createTool: ({ home, project }) => ({
       id: 'claude-code',
       name: 'Claude Code',
@@ -72,7 +86,11 @@ const claudeCodeAdapter = defineAgentClientAdapter({
       { name: 'claude-yolo', command: 'claude --dangerously-skip-permissions; tput ed' },
       { name: 'cy', command: 'claude --dangerously-skip-permissions; tput ed' }
     ],
-    hooks: []
+    hooks: [
+      claudeCodeCredentialPreflightHook,
+      claudeCodeBeforeContainerCreateHook,
+      claudeCodeBeforeEnterHook
+    ]
   }
 });