feat(sandbox): inherit Claude settings (#556)

- Merge Claude Code provider env from host settings.
- Preserve sandbox overrides with first-write semantics.
- Cover DeepSeek example mappings and invalid env cases.
- Document the settings inheritance boundary.

Co-authored-by: Codex <noreply@openai.com>

Author: CodeCasterX

docs/en/sandbox.md

@@ -22,6 +22,8 @@ When you run the sandbox from a remote Mac over SSH, use `ai cp <ssh-alias>` on
 
 `ai sandbox exec` and `ai sandbox refresh` reconcile Claude Code credentials in both directions across the host credential store and every sandbox project copy under `~/.agent-infra/credentials/*`. When a long-running sandbox refreshes OAuth tokens first, the next entry or refresh command writes the freshest valid copy back to the host Keychain or `~/.claude/.credentials.json`; when the host is fresher, it updates the project copies. If every copy is stale, `ai sandbox refresh` probes `claude /status` and asks you to log in only when the probe cannot recover credentials.
 
+When Claude Code is enabled, `ai sandbox create` also merges model and API provider settings from the host `~/.claude/settings.json` into the sandbox Claude Code settings. Existing sandbox values take precedence, so local sandbox overrides are preserved. Credentials still use the dedicated credentials channel above; provider environment settings are copied only as Claude Code settings values.
+
 ## Host-sandbox file exchange
 
 `ai sandbox create` mounts two writable directories for dropping files between

docs/zh-CN/sandbox.md

@@ -22,6 +22,8 @@
 
 `ai sandbox exec` 和 `ai sandbox refresh` 会在宿主机凭证存储与 `~/.agent-infra/credentials/*` 下的所有沙箱项目副本之间做双向 reconcile。长时间运行的沙箱如果先刷新了 OAuth token，下一次进入或刷新命令会把最新有效副本回写到宿主 Keychain 或 `~/.claude/.credentials.json`；宿主机更新时也会继续覆盖项目副本。如果所有副本都已失效，`ai sandbox refresh` 会尝试 `claude /status` 探活，只有探活无法恢复时才提示重新登录。
 
+启用 Claude Code 时，`ai sandbox create` 还会把宿主机 `~/.claude/settings.json` 中的模型和 API provider 设置合并到沙箱内的 Claude Code settings。已有的沙箱值优先，因此沙箱内的本地覆盖会被保留。凭证仍使用上面的专用 credentials 通道；provider 环境设置只会作为 Claude Code settings 值复制。
+
 ## 宿主-沙箱文件交换
 
 `ai sandbox create` 会自动挂载两个可读写目录，方便宿主与容器之间互相 drop 文件，不污染 git 工作树：

lib/sandbox/commands/create.ts

@@ -740,6 +740,63 @@ function readHostJsonSafe(filePath: string): JsonObject | 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;
+}
+
 export function ensureClaudeOnboarding(toolDir: string, hostHomeDir?: string): void {
   const claudeJsonPath = path.join(toolDir, '.claude.json');
   let data: JsonObject & {
@@ -810,7 +867,7 @@ export function ensureClaudeOnboarding(toolDir: string, hostHomeDir?: string): v
 
 export function ensureClaudeSettings(toolDir: string, hostHomeDir?: string): void {
   const settingsPath = path.join(toolDir, 'settings.json');
-  let data: JsonObject & { skipDangerousModePermissionPrompt?: boolean; effortLevel?: string } = {};
+  let data: JsonObject & { skipDangerousModePermissionPrompt?: boolean } = {};
   if (fs.existsSync(settingsPath)) {
     try {
       data = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) as typeof data;
@@ -825,14 +882,9 @@ export function ensureClaudeSettings(toolDir: string, hostHomeDir?: string): voi
   }
   if (hostHomeDir) {
     const hostSettings = readHostJsonSafe(path.join(hostHomeDir, '.claude', 'settings.json'));
-    if (
-      hostSettings
-      && typeof hostSettings.effortLevel === 'string'
-      && hostSettings.effortLevel !== ''
-      && !Object.hasOwn(data, 'effortLevel')
-    ) {
-      data.effortLevel = hostSettings.effortLevel;
-      changed = true;
+    if (hostSettings) {
+      changed = mergeMissingStringEnvFields(data, hostSettings) || changed;
+      changed = mergeMissingTopLevelSettings(data, hostSettings) || changed;
     }
   }
   if (changed) {

tests/integration/cli/sandbox-inheritance.test.ts

@@ -445,6 +445,191 @@ test("ensureClaudeSettings skips empty host effort level", async () => {
   }
 });
 
+test("ensureClaudeSettings inherits host provider env and model settings", async () => {
+  const sandboxCreate = await loadFreshEsm<SandboxCreateModule>("lib/sandbox/commands/create.js");
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-settings-provider-"));
+  const hostHome = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-host-provider-"));
+
+  try {
+    fs.mkdirSync(path.join(hostHome, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(hostHome, ".claude", "settings.json"),
+      JSON.stringify({
+        env: {
+          ANTHROPIC_BASE_URL: "https://api.deepseek.example/anthropic",
+          ANTHROPIC_AUTH_TOKEN: "test-token-redacted",
+          ANTHROPIC_MODEL: "deepseek-v4-pro[1m]",
+          ANTHROPIC_OPUS_MODEL: "deepseek-v4-pro[1m]",
+          ANTHROPIC_SONNET_MODEL: "deepseek-v4-flash",
+          ANTHROPIC_HAIKU_MODEL: "deepseek-v4-flash",
+          ANTHROPIC_SMALL_FAST_MODEL: "deepseek-v4-flash",
+          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
+        },
+        model: "deepseek-v4-pro[1m]",
+        fallbackModel: "deepseek-v4-flash",
+        availableModels: ["deepseek-v4-pro[1m]", "deepseek-v4-flash"],
+        modelOverrides: {
+          opus: "deepseek-v4-pro[1m]",
+          sonnet: "deepseek-v4-flash",
+          haiku: "deepseek-v4-flash",
+          subagent: "deepseek-v4-flash"
+        },
+        enforceAvailableModels: true,
+        advisorModel: "deepseek-v4-flash",
+        apiKeyHelper: "printf test-token-redacted",
+        theme: "dark"
+      }),
+      "utf8"
+    );
+
+    sandboxCreate.ensureClaudeSettings(tmpDir, hostHome);
+    const data = JSON.parse(fs.readFileSync(path.join(tmpDir, "settings.json"), "utf8"));
+    assert.deepEqual(data.env, {
+      ANTHROPIC_BASE_URL: "https://api.deepseek.example/anthropic",
+      ANTHROPIC_AUTH_TOKEN: "test-token-redacted",
+      ANTHROPIC_MODEL: "deepseek-v4-pro[1m]",
+      ANTHROPIC_OPUS_MODEL: "deepseek-v4-pro[1m]",
+      ANTHROPIC_SONNET_MODEL: "deepseek-v4-flash",
+      ANTHROPIC_HAIKU_MODEL: "deepseek-v4-flash",
+      ANTHROPIC_SMALL_FAST_MODEL: "deepseek-v4-flash",
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
+    });
+    assert.equal(data.model, "deepseek-v4-pro[1m]");
+    assert.equal(data.fallbackModel, "deepseek-v4-flash");
+    assert.deepEqual(data.availableModels, ["deepseek-v4-pro[1m]", "deepseek-v4-flash"]);
+    assert.deepEqual(data.modelOverrides, {
+      opus: "deepseek-v4-pro[1m]",
+      sonnet: "deepseek-v4-flash",
+      haiku: "deepseek-v4-flash",
+      subagent: "deepseek-v4-flash"
+    });
+    assert.equal(data.enforceAvailableModels, true);
+    assert.equal(data.advisorModel, "deepseek-v4-flash");
+    assert.equal(data.apiKeyHelper, "printf test-token-redacted");
+    assert.equal(Object.hasOwn(data, "theme"), false);
+    assert.equal(data.skipDangerousModePermissionPrompt, true);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(hostHome, { recursive: true, force: true });
+  }
+});
+
+test("ensureClaudeSettings preserves sandbox provider fields and fills missing env", async () => {
+  const sandboxCreate = await loadFreshEsm<SandboxCreateModule>("lib/sandbox/commands/create.js");
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-settings-provider-keep-"));
+  const hostHome = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-host-provider-keep-"));
+
+  try {
+    fs.mkdirSync(path.join(hostHome, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(hostHome, ".claude", "settings.json"),
+      JSON.stringify({
+        env: {
+          ANTHROPIC_MODEL: "host-model",
+          ANTHROPIC_SMALL_FAST_MODEL: "host-fast-model"
+        },
+        model: "host-top-level-model",
+        fallbackModel: "host-fallback-model"
+      }),
+      "utf8"
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, "settings.json"),
+      JSON.stringify({
+        skipDangerousModePermissionPrompt: true,
+        env: {
+          ANTHROPIC_MODEL: "sandbox-model"
+        },
+        model: "sandbox-top-level-model"
+      }),
+      "utf8"
+    );
+
+    sandboxCreate.ensureClaudeSettings(tmpDir, hostHome);
+    const data = JSON.parse(fs.readFileSync(path.join(tmpDir, "settings.json"), "utf8"));
+    assert.deepEqual(data.env, {
+      ANTHROPIC_MODEL: "sandbox-model",
+      ANTHROPIC_SMALL_FAST_MODEL: "host-fast-model"
+    });
+    assert.equal(data.model, "sandbox-top-level-model");
+    assert.equal(data.fallbackModel, "host-fallback-model");
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(hostHome, { recursive: true, force: true });
+  }
+});
+
+test("ensureClaudeSettings skips invalid host env values and non-object sandbox env", async () => {
+  const sandboxCreate = await loadFreshEsm<SandboxCreateModule>("lib/sandbox/commands/create.js");
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-settings-provider-invalid-"));
+  const hostHome = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-host-provider-invalid-"));
+
+  try {
+    fs.mkdirSync(path.join(hostHome, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(hostHome, ".claude", "settings.json"),
+      JSON.stringify({
+        env: {
+          ANTHROPIC_BASE_URL: "https://api.example.test",
+          ANTHROPIC_AUTH_TOKEN: "",
+          ANTHROPIC_MODEL: ["not", "a", "string"],
+          ANTHROPIC_SMALL_FAST_MODEL: false
+        }
+      }),
+      "utf8"
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, "settings.json"),
+      JSON.stringify({
+        skipDangerousModePermissionPrompt: true,
+        env: "keep-local-env-value"
+      }),
+      "utf8"
+    );
+
+    sandboxCreate.ensureClaudeSettings(tmpDir, hostHome);
+    const data = JSON.parse(fs.readFileSync(path.join(tmpDir, "settings.json"), "utf8"));
+    assert.equal(data.env, "keep-local-env-value");
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(hostHome, { recursive: true, force: true });
+  }
+});
+
+test("ensureClaudeSettings skips non-object host env without defaulting effort env", async () => {
+  const sandboxCreate = await loadFreshEsm<SandboxCreateModule>("lib/sandbox/commands/create.js");
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-settings-host-env-invalid-"));
+  const hostHome = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-host-env-invalid-"));
+
+  try {
+    fs.mkdirSync(path.join(hostHome, ".claude"), { recursive: true });
+    fs.writeFileSync(path.join(hostHome, ".claude", "settings.json"), JSON.stringify({ env: "invalid" }), "utf8");
+    sandboxCreate.ensureClaudeSettings(tmpDir, hostHome);
+    const data = JSON.parse(fs.readFileSync(path.join(tmpDir, "settings.json"), "utf8"));
+    assert.equal(Object.hasOwn(data, "env"), false);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(hostHome, { recursive: true, force: true });
+  }
+});
+
+test("ensureClaudeSettings skips malformed host settings", async () => {
+  const sandboxCreate = await loadFreshEsm<SandboxCreateModule>("lib/sandbox/commands/create.js");
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-settings-malformed-host-"));
+  const hostHome = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-claude-host-malformed-settings-"));
+
+  try {
+    fs.mkdirSync(path.join(hostHome, ".claude"), { recursive: true });
+    fs.writeFileSync(path.join(hostHome, ".claude", "settings.json"), "{not-json:test-token-redacted", "utf8");
+    sandboxCreate.ensureClaudeSettings(tmpDir, hostHome);
+    const data = JSON.parse(fs.readFileSync(path.join(tmpDir, "settings.json"), "utf8"));
+    assert.deepEqual(data, { skipDangerousModePermissionPrompt: true });
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(hostHome, { recursive: true, force: true });
+  }
+});
+
 test("ensureCodexModelInheritance creates config with host model fields", async () => {
   const sandboxCreate = await loadFreshEsm<SandboxCreateModule>("lib/sandbox/commands/create.js");
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-infra-codex-model-"));