Add fallback model support to Python SDK

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -112,6 +112,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

@@ -348,6 +348,7 @@ class ClaudeAgentOptions:
     max_turns: int | 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
     settings: str | None = None

tests/test_transport.py

@@ -125,6 +125,39 @@ 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=ClaudeAgentOptions(
+                model="claude-sonnet-4-5",
+                fallback_model="claude-haiku-4-1",
+            ),
+            cli_path="/usr/bin/claude",
+        )
+
+        cmd = transport._build_command()
+        assert "--model" in cmd
+        assert "claude-sonnet-4-5" in cmd
+        assert "--fallback-model" in cmd
+        assert "claude-haiku-4-1" in cmd
+
+    def test_build_command_without_fallback_model(self):
+        """Test building CLI command without fallback model (should be omitted)."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=ClaudeAgentOptions(
+                model="claude-sonnet-4-5",
+                # No fallback_model specified
+            ),
+            cli_path="/usr/bin/claude",
+        )
+
+        cmd = transport._build_command()
+        assert "--model" in cmd
+        assert "claude-sonnet-4-5" in cmd
+        assert "--fallback-model" not in cmd
+
     def test_build_command_with_add_dirs(self):
         """Test building CLI command with add_dirs option."""
         from pathlib import Path

tests/test_types.py

@@ -149,3 +149,17 @@ def test_claude_code_options_with_model_specification(self):
         )
         assert options.model == "claude-sonnet-4-5"
         assert options.permission_prompt_tool_name == "CustomTool"
+
+    def test_claude_code_options_with_fallback_model(self):
+        """Test Options with fallback model specification."""
+        options = ClaudeAgentOptions(
+            model="claude-sonnet-4-5", fallback_model="claude-haiku-4-1"
+        )
+        assert options.model == "claude-sonnet-4-5"
+        assert options.fallback_model == "claude-haiku-4-1"
+
+    def test_claude_code_options_fallback_model_defaults_to_none(self):
+        """Test Options fallback model defaults to None."""
+        options = ClaudeAgentOptions(model="claude-sonnet-4-5")
+        assert options.model == "claude-sonnet-4-5"
+        assert options.fallback_model is None