Add extra_args field to ClaudeCodeOptions for forward compatibility

- Add extra_args dict field to pass arbitrary CLI flags
- Support both valued flags (--flag value) and boolean flags (--flag)
- Add comprehensive tests for the new functionality
- Allows SDK to work with future CLI flags without code changes

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/claude_code_sdk/_internal/transport/subprocess_cli.py

@@ -134,6 +134,15 @@ class SubprocessCLITransport(Transport):
                 ["--mcp-config", json.dumps({"mcpServers": self._options.mcp_servers})]
             )
 
+        # Add extra args for future CLI flags
+        for flag, value in self._options.extra_args.items():
+            if value is None:
+                # Boolean flag without value
+                cmd.append(f"--{flag}")
+            else:
+                # Flag with value
+                cmd.extend([f"--{flag}", str(value)])
+
         # Add prompt handling based on mode
         if self._is_streaming:
             # Streaming mode: use --input-format stream-json

src/claude_code_sdk/types.py

@@ -128,3 +128,6 @@ class ClaudeCodeOptions:
     cwd: str | Path | None = None
     settings: str | None = None
     add_dirs: list[str | Path] = field(default_factory=list)
+    extra_args: dict[str, str | None] = field(
+        default_factory=dict
+    )  # Pass arbitrary CLI flags

tests/test_transport.py

@@ -174,3 +174,56 @@ class TestSubprocessCLITransport:
             assert "/this/directory/does/not/exist" in str(exc_info.value)
 
         anyio.run(_test)
+
+    def test_build_command_with_settings_file(self):
+        """Test building CLI command with settings as file path."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=ClaudeCodeOptions(settings="/path/to/settings.json"),
+            cli_path="/usr/bin/claude",
+        )
+
+        cmd = transport._build_command()
+        assert "--settings" in cmd
+        assert "/path/to/settings.json" in cmd
+
+    def test_build_command_with_settings_json(self):
+        """Test building CLI command with settings as JSON object."""
+        settings_json = '{"permissions": {"allow": ["Bash(ls:*)"]}}'
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=ClaudeCodeOptions(settings=settings_json),
+            cli_path="/usr/bin/claude",
+        )
+
+        cmd = transport._build_command()
+        assert "--settings" in cmd
+        assert settings_json in cmd
+
+    def test_build_command_with_extra_args(self):
+        """Test building CLI command with extra_args for future flags."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=ClaudeCodeOptions(
+                extra_args={
+                    "new-flag": "value",
+                    "boolean-flag": None,
+                    "another-option": "test-value",
+                }
+            ),
+            cli_path="/usr/bin/claude",
+        )
+
+        cmd = transport._build_command()
+        cmd_str = " ".join(cmd)
+
+        # Check flags with values
+        assert "--new-flag value" in cmd_str
+        assert "--another-option test-value" in cmd_str
+
+        # Check boolean flag (no value)
+        assert "--boolean-flag" in cmd
+        # Make sure boolean flag doesn't have a value after it
+        boolean_idx = cmd.index("--boolean-flag")
+        # Either it's the last element or the next element is another flag
+        assert boolean_idx == len(cmd) - 1 or cmd[boolean_idx + 1].startswith("--")