Add fallback model handling for parity with TypeScript SDK (#317)

Add support for automatic model fallback when primary model is
overloaded. The Python SDK passes the fallback_model parameter to the
Claude CLI, which handles the validation and fallback logic.

Changes:
- Add fallback_model parameter to ClaudeAgentOptions
- Pass --fallback-model to CLI subprocess
- Add test for fallback model command building

The validation that fallback_model != model happens at the CLI layer,
keeping the SDK implementation simple and focused on parameter passing.

---------

Co-authored-by: Claude <[email protected]>

Author: szwang

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -125,6 +125,9 @@ def _build_command(self) -> list[str]:
         if self._options.model:
             cmd.extend(["--model", self._options.model])
 
+        if self._options.fallback_model:
+            cmd.extend(["--fallback-model", self._options.fallback_model])
+
         if self._options.permission_prompt_tool_name:
             cmd.extend(
                 ["--permission-prompt-tool", self._options.permission_prompt_tool_name]

src/claude_agent_sdk/types.py

@@ -521,6 +521,7 @@ class ClaudeAgentOptions:
     max_budget_usd: float | None = None
     disallowed_tools: list[str] = field(default_factory=list)
     model: str | None = None
+    fallback_model: str | None = None
     permission_prompt_tool_name: str | None = None
     cwd: str | Path | None = None
     cli_path: str | Path | None = None

tests/test_transport.py

@@ -131,6 +131,22 @@ def test_build_command_with_options(self):
         assert "--max-turns" in cmd
         assert "5" in cmd
 
+    def test_build_command_with_fallback_model(self):
+        """Test building CLI command with fallback_model option."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(
+                model="opus",
+                fallback_model="sonnet",
+            ),
+        )
+
+        cmd = transport._build_command()
+        assert "--model" in cmd
+        assert "opus" in cmd
+        assert "--fallback-model" in cmd
+        assert "sonnet" in cmd
+
     def test_build_command_with_max_thinking_tokens(self):
         """Test building CLI command with max_thinking_tokens option."""
         transport = SubprocessCLITransport(