Let Claude sessions pass structured launch arguments (#5206)

Expose Claude Agent SDK's documented extraArgs map through providerOptions so Claude-specific flags such as --chrome reach the CLI.

Document boolean and valued flags, link the upstream contract, and validate through schema tests, the public session interface, and a real Claude launch.

packages/server/src/server/agent/provider-options.test.ts

@@ -51,6 +51,7 @@ describe("provider-owned option schemas", () => {
       ClaudeProviderOptionsSchema.parse({
         allowedTools: ["Read"],
         disallowedTools: ["Bash(rm *)"],
+        extraArgs: { chrome: null, model: "x" },
         sandbox: {
           enabled: true,
           failIfUnavailable: true,
@@ -63,7 +64,26 @@ describe("provider-owned option schemas", () => {
         },
         settings: { permissions: { ask: ["Bash(*)"], deny: ["Edit(.env)"] } },
       }),
-    ).toMatchObject({ sandbox: { enabled: true, failIfUnavailable: true } });
+    ).toMatchObject({
+      extraArgs: { chrome: null, model: "x" },
+      sandbox: { enabled: true, failIfUnavailable: true },
+    });
+  });
+
+  test.each([true, 42, ["x"]])("rejects invalid Claude extra argument values: %j", (value) => {
+    expect(() =>
+      validateProviderOptions("claude", ClaudeProviderOptionsSchema, {
+        extraArgs: { chrome: value },
+      }),
+    ).toThrow("providerOptions.extraArgs.chrome");
+  });
+
+  test("rejects a raw argument list for the SDK argument map", () => {
+    expect(() =>
+      validateProviderOptions("claude", ClaudeProviderOptionsSchema, {
+        extraArgs: ["--chrome"],
+      }),
+    ).toThrow("providerOptions.extraArgs");
   });
 
   test("reports the exact invalid Claude option path", () => {

packages/server/src/server/agent/providers/claude/agent.test.ts

@@ -785,6 +785,29 @@ describe("ClaudeAgentSession features", () => {
     await session.close();
   });
 
+  test("passes extra Claude Code CLI arguments to the SDK", async () => {
+    const { queryFactory, launches } = createQueryMock();
+    const client = new ClaudeAgentClient({
+      logger,
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      providerOptions: {
+        extraArgs: { chrome: null, model: "x" },
+      },
+    });
+
+    await expect(session.startTurn("hello")).resolves.toEqual({
+      turnId: expect.stringMatching(/^foreground-turn-/),
+    });
+
+    expect(launches[0]?.options.extraArgs).toEqual({ chrome: null, model: "x" });
+    await session.close();
+  });
+
   test("lists fast mode only for supported Opus models", async () => {
     const client = new ClaudeAgentClient({ logger, resolveBinary: async () => "/test/claude/bin" });
 

packages/server/src/server/agent/providers/claude/options.ts

@@ -48,6 +48,7 @@ export const ClaudeProviderOptionsSchema = z
     allowedTools: z.array(z.string()).optional(),
     disallowedTools: z.array(z.string()).optional(),
     additionalDirectories: z.array(z.string()).optional(),
+    extraArgs: z.record(z.string(), z.string().nullable()).optional(),
     sandbox: z
       .object({
         enabled: z.boolean().optional(),