The best way to control Claude Code, Codex and more from any computer or phone
fix(server): Claude --settings launch args merge with T3's settings instead of being dropped (#22864)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 27, 2026 at 15:01 UTC
8d94203c17285aed0e089390d700907d23770d0b
4 files changed
+182
-36
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
+95
-23
@@ -606,6 +606,19 @@ describe("ClaudeAdapterV2 native protocol logging", () => {
606
assert.equal(logged.hasMcpServers, true);
607
assert.notInclude(JSON.stringify(logged), "secret-claude-token");
608
});
609
+
610
+ it("logs --settings key names without their values", () => {
611
+ const options = ClaudeAdapterV2.makeClaudeQueryOptions({
612
+ modelSelection: CLAUDE_TEST_MODEL_SELECTION,
613
+ nativeThreadId: "native-thread-claude-settings-log",
614
+ resume: false,
615
+ cwd: "/workspace",
616
+ sdkSettings: { env: { ANTHROPIC_API_KEY: "secret-settings-key" } },
617
+ });
618
+ const logged = ClaudeAdapterV2.loggedClaudeQueryOptions(options);
619
+ assert.deepEqual(logged.settingKeys, ["env", "showThinkingSummaries"]);
620
+ assert.notInclude(JSON.stringify(logged), "secret-settings-key");
621
+ });
622
});
623
624
describe("ClaudeAdapterV2 context usage", () => {
@@ -949,6 +962,34 @@ describe("ClaudeAdapterV2 append-system-prompt-file launch argument", () => {
962
),
963
);
964
965
+ // regression: #15073 the SDK replaced the --settings launch argument with T3's settings
966
+ it.effect.each([
967
+ `--settings '{"skillOverrides":{"lint":"off"},"showThinkingSummaries":false}'`,
968
+ "--settings user-settings.json",
969
+ ])("merges %s beneath T3's settings", (launchArgs) =>
970
+ Effect.scoped(
971
+ Effect.gen(function* () {
972
+ const fileSystem = yield* FileSystem.FileSystem;
973
+ const cwd = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-claude-settings-" });
974
+ yield* fileSystem.writeFileString(
975
+ NodePath.join(cwd, "user-settings.json"),
976
+ '{"skillOverrides":{"lint":"off"},"showThinkingSummaries":false}',
977
+ );
978
+ const { exit, opened } = yield* startTurnWithLaunchArgs(launchArgs, cwd);
979
+ assert.isTrue(Exit.isSuccess(exit));
980
+ assert.deepInclude(opened[0]!.settings, {
981
+ skillOverrides: { lint: "off" },
982
+ showThinkingSummaries: true,
983
+ });
984
+ assert.isUndefined(opened[0]!.extraArgs?.["settings"]);
985
+ }).pipe(
986
+ Effect.provide(
987
+ Layer.mergeAll(IdAllocator.layer, McpProviderSessions.layer, NodeServices.layer),
988
+ ),
989
+ ),
990
+ ),
991
+ );
992
+
993
// regression: #20413 malformed append-system-prompt launch args fail before a query opens
994
it.effect.each([
995
[
@@ -979,6 +1020,19 @@ describe("ClaudeAdapterV2 append-system-prompt-file launch argument", () => {
1020
flag: "--append-system-prompt",
1021
}).message,
1022
],
1023
+ [
1024
+ "--settings missing.json",
1025
+ (cwd: string) =>
1026
+ new ClaudeAdapterV2.ClaudeSettingsLaunchArgError({
1027
+ path: NodePath.join(cwd, "missing.json"),
1028
+ }).message,
1029
+ ],
1030
+ ["--settings '{not json}'", () => new ClaudeAdapterV2.ClaudeSettingsLaunchArgError({}).message],
1031
+ // Without a closing brace this must not become a file path that echoes the secret.
1032
+ [
1033
+ `--settings '{"env":{"ANTHROPIC_API_KEY":"secret-settings-key"},'`,
1034
+ () => new ClaudeAdapterV2.ClaudeSettingsLaunchArgError({}).message,
1035
+ ],
1036
] as const)("fails the turn before opening Claude for %s", ([launchArgs, expectedMessage]) =>
1037
Effect.scoped(
1038
Effect.gen(function* () {
@@ -3284,29 +3338,31 @@ describe("ClaudeAdapterV2 background wake turns", () => {
3338
vi.importActual<typeof ClaudeSdk>("@anthropic-ai/claude-agent-sdk"),
3339
);
3340
vi.mocked(ClaudeSdk.resolveSettings).mockImplementation(sdk.resolveSettings);
3287
- const open = Effect.scoped(
3288
- Effect.gen(function* () {
3289
- const harness = yield* makeWakeHarnessWithOptions({
3290
- settings: { ...DEFAULT_CLAUDE_SETTINGS, homePath: home },
3291
- });
3292
- yield* harness.runtime.startTurn(
3293
- makeClaudeTestTurnInput({
3294
- threadId: harness.threadId,
3295
- providerThread: harness.providerThread,
3296
- now: yield* DateTime.now,
3297
- attemptId: RunAttemptId.make("attempt-cached-managed-policy"),
3298
- text: "Run git status.",
3299
- attachments: [],
3300
- runtimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
3301
- runtimeMode: "full-access",
3302
- interactionMode: "default",
3303
- cwd,
3341
+ const openWith = (launchArgs: string) =>
3342
+ Effect.scoped(
3343
+ Effect.gen(function* () {
3344
+ const harness = yield* makeWakeHarnessWithOptions({
3345
+ settings: { ...DEFAULT_CLAUDE_SETTINGS, homePath: home, launchArgs },
3346
+ });
3347
+ yield* harness.runtime.startTurn(
3348
+ makeClaudeTestTurnInput({
3349
+ threadId: harness.threadId,
3350
+ providerThread: harness.providerThread,
3351
+ now: yield* DateTime.now,
3352
+ attemptId: RunAttemptId.make("attempt-cached-managed-policy"),
3353
+ text: "Run git status.",
3354
+ attachments: [],
3355
+ runtimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
3356
+ runtimeMode: "full-access",
3357
+ interactionMode: "default",
3358
+ cwd,
3359
+ }),
3360
}),
3305
- }),
3306
- );
3307
- return harness.getOpenedOptions()!;
3308
- }),
3309
- );
3361
+ );
3362
+ return harness.getOpenedOptions()!;
3363
+ }),
3364
+ );
3365
+ const open = openWith("");
3366
yield* fileSystem.writeFileString(
3367
remoteFile,
3368
JSON.stringify({
@@ -3320,6 +3376,11 @@ describe("ClaudeAdapterV2 background wake turns", () => {
3376
assert.isUndefined(restricted.allowDangerouslySkipPermissions);
3377
yield* fileSystem.remove(remoteFile);
3378
assert.equal((yield* open).permissionMode, "bypassPermissions");
3379
+ const launchRestricted = yield* openWith(
3380
+ `--settings '{"permissions":{"disableBypassPermissionsMode":"disable"}}'`,
3381
+ );
3382
+ assert.equal(launchRestricted.permissionMode, "auto");
3383
+ assert.isUndefined(launchRestricted.allowDangerouslySkipPermissions);
3384
yield* fileSystem.writeFileString(remoteFile, "{ invalid json");
3385
assert.equal((yield* open).permissionMode, "auto");
3386
yield* fileSystem.remove(remoteFile);
@@ -3740,12 +3801,13 @@ describe("ClaudeAdapterV2 background wake turns", () => {
3801
settingsJson: string,
3802
cwd = CLAUDE_TEST_RUNTIME_POLICY.cwd,
3803
environment?: NodeJS.ProcessEnv,
3804
+ launchArgs = "",
3805
) =>
3806
Effect.scoped(
3807
Effect.gen(function* () {
3808
yield* fileSystem.writeFileString(path.join(home, "settings.json"), settingsJson);
3809
const harness = yield* makeWakeHarnessWithOptions({
3748
- settings: { ...DEFAULT_CLAUDE_SETTINGS, homePath: home },
3810
+ settings: { ...DEFAULT_CLAUDE_SETTINGS, homePath: home, launchArgs },
3811
...(environment === undefined ? {} : { environment }),
3812
});
3813
yield* harness.runtime.startTurn(
@@ -3769,6 +3831,16 @@ describe("ClaudeAdapterV2 background wake turns", () => {
3831
assert.equal(yield* openedToolSearch('{"env":{"ENABLE_TOOL_SEARCH":"auto"}}'), "true");
3832
assert.isUndefined(yield* openedToolSearch('{"env":{"ENABLE_TOOL_SEARCH":"false"}}'));
3833
assert.isUndefined(yield* openedToolSearch("{}"));
3834
+ // --settings beats local, project, and user settings.
3835
+ assert.equal(
3836
+ yield* openedToolSearch(
3837
+ '{"env":{"ENABLE_TOOL_SEARCH":"auto"}}',
3838
+ CLAUDE_TEST_RUNTIME_POLICY.cwd,
3839
+ undefined,
3840
+ `--settings '{"env":{"ENABLE_TOOL_SEARCH":"false"}}'`,
3841
+ ),
3842
+ "false",
3843
+ );
3844
3845
// Claude Code keeps the local file at the repository root, the main checkout's root in a
3846
// worktree, and that file beats the user's settings.
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+83
-11
@@ -573,6 +573,18 @@ export class ClaudeAppendSystemPromptMissingValueError extends Schema.TaggedErro
573
}
574
}
575
576
+export class ClaudeSettingsLaunchArgError extends Schema.TaggedError<ClaudeSettingsLaunchArgError>()(
577
+ "ClaudeSettingsLaunchArgError",
578
+ {
579
+ path: Schema.optional(Schema.String),
580
+ cause: Schema.optional(Schema.Defect()),
581
+ },
582
+) {
583
+ override get message(): string {
584
+ return `Claude could not read the --settings launch argument${this.path === undefined ? "" : ` at ${this.path}`} as a JSON object. Fix it in the Claude launch arguments, then send the message again.`;
585
+ }
586
+}
587
+
588
export interface ClaudeAgentSdkQueryRunnerShape {
589
readonly allocateSessionId: Effect.Effect<string, ClaudeAgentSdkQueryRunnerError>;
590
readonly open: (
@@ -648,7 +660,7 @@ export interface ClaudeAgentSdkLoggedQueryOptions {
660
readonly cwd?: ClaudeAgentSdkQueryOptions["cwd"];
661
readonly allowedTools?: ClaudeAgentSdkQueryOptions["allowedTools"];
662
readonly disallowedTools?: ClaudeAgentSdkQueryOptions["disallowedTools"];
651
- readonly settings?: ClaudeAgentSdkQueryOptions["settings"];
663
+ readonly settingKeys?: ReadonlyArray<string>;
664
readonly effort?: ClaudeAgentSdkQueryOptions["effort"];
665
readonly includePartialMessages?: true;
666
readonly pathToClaudeCodeExecutable?: ClaudeAgentSdkQueryOptions["pathToClaudeCodeExecutable"];
@@ -787,7 +799,10 @@ export function loggedClaudeQueryOptions(
799
...(options.cwd === undefined ? {} : { cwd: options.cwd }),
800
...(options.allowedTools === undefined ? {} : { allowedTools: options.allowedTools }),
801
...(options.disallowedTools === undefined ? {} : { disallowedTools: options.disallowedTools }),
790
- ...(options.settings === undefined ? {} : { settings: options.settings }),
802
+ // Settings can carry the user's --settings values, such as an env block with credentials.
803
+ ...(typeof options.settings === "object" && options.settings !== null
804
+ ? { settingKeys: Object.keys(options.settings) }
805
+ : {}),
806
...(options.effort === undefined ? {} : { effort: options.effort }),
807
...(options.includePartialMessages === true ? { includePartialMessages: true } : {}),
808
...(options.pathToClaudeCodeExecutable === undefined
@@ -1431,6 +1446,8 @@ export function makeClaudeQueryOptions(input: {
1446
"dangerously-skip-permissions": launchArgSkipPermissions,
1447
"append-system-prompt": launchArgAppendSystemPrompt,
1448
"append-system-prompt-file": _launchArgAppendSystemPromptFile,
1449
+ // The SDK replaces this flag with options.settings, so it arrives read as sdkSettings.
1450
+ settings: _launchArgSettings,
1451
...extraArgs
1452
} = input.settings === undefined ? {} : parseCliArgs(input.settings.launchArgs).flags;
1453
// Claude Code overwrites its CLI append text with the SDK's initialize
@@ -1579,6 +1596,42 @@ const readClaudeAppendSystemPromptFile = Effect.fnUntraced(function* (input: {
1596
);
1597
});
1598
1599
+const decodeClaudeLaunchArgSettings = Schema.decodeUnknownEffect(
1600
+ fromLenientJson(Schema.Record(Schema.String, Schema.Unknown)),
1601
+);
1602
+
1603
+/**
1604
+ * Reads the --settings launch argument: a value starting with a brace is inline
1605
+ * JSON, anything else is a file path relative to the cwd. makeClaudeQueryOptions
1606
+ * merges the result beneath T3's own settings.
1607
+ */
1608
+const readClaudeLaunchArgSettings = Effect.fn("ClaudeAdapterV2.readLaunchArgSettings")(
1609
+ function* (input: {
1610
+ readonly settings: ClaudeSettings | undefined;
1611
+ readonly cwd: string | null;
1612
+ readonly fileSystem: FileSystem.FileSystem;
1613
+ readonly path: Path.Path;
1614
+ }) {
1615
+ if (input.settings === undefined) return undefined;
1616
+ const value = parseCliArgs(input.settings.launchArgs).flags.settings;
1617
+ if (value === undefined) return undefined;
1618
+ const trimmed = value?.trim() ?? "";
1619
+ if (trimmed.length === 0) return yield* new ClaudeSettingsLaunchArgError({});
1620
+ // The CLI also wants a closing brace, but then malformed JSON, secrets included, would
1621
+ // become the file path in the error message.
1622
+ if (trimmed.startsWith("{")) {
1623
+ return (yield* decodeClaudeLaunchArgSettings(trimmed).pipe(
1624
+ Effect.mapError((cause) => new ClaudeSettingsLaunchArgError({ cause })),
1625
+ )) as ClaudeSdkSettings;
1626
+ }
1627
+ const filePath = input.path.resolve(input.cwd ?? ".", trimmed);
1628
+ return (yield* input.fileSystem.readFileString(filePath).pipe(
1629
+ Effect.flatMap(decodeClaudeLaunchArgSettings),
1630
+ Effect.mapError((cause) => new ClaudeSettingsLaunchArgError({ path: filePath, cause })),
1631
+ )) as ClaudeSdkSettings;
1632
+ },
1633
+);
1634
+
1635
export const CLAUDE_T3_MCP_TOOL_WILDCARD = "mcp__t3-code__*";
1636
1637
// Keep in sync with OrchestratorToolkit Tool.Readonly annotations; ClaudeAdapterV2.test.ts checks this.
@@ -2507,6 +2560,7 @@ const ClaudeBypassSettings = Schema.StructWithRest(
2560
const decodeClaudeBypassSettings = Schema.decodeUnknownEffect(
2561
fromLenientJson(ClaudeBypassSettings),
2562
);
2563
+const decodeClaudeLaunchArgBypassSettings = Schema.decodeUnknownEffect(ClaudeBypassSettings);
2564
2565
const ClaudePromptCacheTtl = Schema.Literals(["5m", "1h"]);
2566
const decodeClaudePromptCacheTtl = Schema.decodeUnknownOption(ClaudePromptCacheTtl);
@@ -4279,12 +4333,17 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
4333
serverManagedSettings: remote,
4334
}),
4335
);
4282
- const cascade = claudeBypassAvailability(resolved.effective);
4283
- const user = claudeBypassAvailability(home);
4284
- const cached = claudeBypassAvailability(remote);
4336
+ const launchArgSettings = yield* readClaudeLaunchArgSettings({
4337
+ settings: adapterOptions.settings,
4338
+ cwd,
4339
+ fileSystem,
4340
+ path,
4341
+ });
4342
+ const launch = yield* decodeClaudeLaunchArgBypassSettings(launchArgSettings ?? {});
4343
+ const sources = [resolved.effective, home, remote, launch].map(claudeBypassAvailability);
4344
return {
4286
- bypassDisabled: cascade.bypassDisabled || user.bypassDisabled || cached.bypassDisabled,
4287
- autoDisabled: cascade.autoDisabled || user.autoDisabled || cached.autoDisabled,
4345
+ bypassDisabled: sources.some((source) => source.bypassDisabled),
4346
+ autoDisabled: sources.some((source) => source.autoDisabled),
4347
};
4348
},
4349
);
@@ -4357,10 +4416,13 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
4416
if (path.dirname(directory) === directory) return cwd;
4417
}
4418
});
4360
- // Settings env beats the process env, local over project over user, and a local file an older
4361
- // Claude Code left in cwd applies under the root one. resolveSettings reads local from cwd only.
4419
+ // Settings env beats the process env, --settings over local over project over user, and a local
4420
+ // file an older Claude Code left in cwd applies under the root one. resolveSettings reads local
4421
+ // from cwd only.
4422
const resolveToolSearchOverride = Effect.fn("ClaudeAdapterV2.resolveToolSearchOverride")(
4363
- function* (cwd: string | null) {
4423
+ function* (cwd: string | null, launchArgSettings: ClaudeSdkSettings | undefined) {
4424
+ const launchValue = launchArgSettings?.env?.ENABLE_TOOL_SEARCH;
4425
+ if (typeof launchValue === "string") return claudeToolSearchOverride(launchValue);
4426
const localDirectory = cwd === null ? null : yield* localSettingsDirectory(cwd);
4427
const settingsFiles = [
4428
...(cwd === null || localDirectory === null
@@ -9711,6 +9773,12 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
9773
fileSystem,
9774
path,
9775
});
9776
+ const launchArgSettings = yield* readClaudeLaunchArgSettings({
9777
+ settings: adapterOptions.settings,
9778
+ cwd: turnInput.runtimePolicy.cwd,
9779
+ fileSystem,
9780
+ path,
9781
+ });
9782
const closedExistingNativeThreadId = existing !== null ? existing.nativeThreadId : null;
9783
if (existing !== null) {
9784
yield* existing.query.close.pipe(Effect.ignore);
@@ -9728,7 +9796,10 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
9796
turnInput.nativeThreadHasTurns ?? turnInput.providerTurnOrdinal > 1;
9797
const shouldResume =
9798
resumeSessionAt !== undefined || openedWithResume || hasPersistedProviderTurn;
9731
- const toolSearchOverride = yield* resolveToolSearchOverride(turnInput.runtimePolicy.cwd);
9799
+ const toolSearchOverride = yield* resolveToolSearchOverride(
9800
+ turnInput.runtimePolicy.cwd,
9801
+ launchArgSettings,
9802
+ );
9803
const queryOptions = makeClaudeQueryOptions({
9804
modelSelection: turnInput.modelSelection,
9805
nativeThreadId,
@@ -9737,6 +9808,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
9808
cwd: turnInput.runtimePolicy.cwd,
9809
attachmentsDir,
9810
settings: adapterOptions.settings,
9811
+ ...(launchArgSettings === undefined ? {} : { sdkSettings: launchArgSettings }),
9812
environment: claudeQueryEnvironment(
9813
adapterOptions.environment,
9814
turnInput.appThread,
apps/server/src/orchestration-v2/ProviderTurnStartService.ts
+3
-2
@@ -95,13 +95,14 @@ const isProviderTurnStartError = Schema.is(ProviderTurnStartError);
95
96
/**
97
* Claude refuses these before it reads the prompt: replacing a process running background work,
98
- * launch arguments whose appended system prompt cannot be read, or MCP registration that never
99
- * answers while the query opens.
98
+ * launch arguments whose appended system prompt or settings cannot be read, or MCP registration
99
+ * that never answers while the query opens.
100
*/
101
const PROMPT_REFUSAL_TAGS = [
102
"ClaudeBackgroundWorkBlocksQueryReplacementError",
103
"ClaudeAppendSystemPromptFileError",
104
"ClaudeAppendSystemPromptMissingValueError",
105
+ "ClaudeSettingsLaunchArgError",
106
"ClaudeMcpRegistrationTimeoutError",
107
] as const;
108
packages/provider-core/src/server/failure.ts
+1
@@ -105,6 +105,7 @@ function curatedCauseMessages(cause: unknown): {
105
case "ClaudeBackgroundWorkBlocksQueryReplacementError":
106
case "ClaudeAppendSystemPromptFileError":
107
case "ClaudeAppendSystemPromptMissingValueError":
108
+ case "ClaudeSettingsLaunchArgError":
109
case "ClaudeMcpRegistrationTimeoutError":
110
case "CursorModelUnavailableError":
111
return { known: stringField(cause, "message"), category: categoryMessage() };