Add SystemPromptFile support for --system-prompt-file CLI flag

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -179,6 +179,8 @@ def _build_command(self) -> list[str]:
                 cmd.extend(
                     ["--append-system-prompt", self._options.system_prompt["append"]]
                 )
+            elif self._options.system_prompt.get("type") == "file":
+                cmd.extend(["--system-prompt-file", self._options.system_prompt["path"]])
 
         # Handle tools option (base set of tools)
         if self._options.tools is not None:

src/claude_agent_sdk/types.py

@@ -32,6 +32,13 @@ class SystemPromptPreset(TypedDict):
     append: NotRequired[str]
 
 
+class SystemPromptFile(TypedDict):
+    """System prompt file configuration."""
+
+    type: Literal["file"]
+    path: str
+
+
 class ToolsPreset(TypedDict):
     """Tools preset configuration."""
 
@@ -718,7 +725,7 @@ class ClaudeAgentOptions:
 
     tools: list[str] | ToolsPreset | None = None
     allowed_tools: list[str] = field(default_factory=list)
-    system_prompt: str | SystemPromptPreset | None = None
+    system_prompt: str | SystemPromptPreset | SystemPromptFile | None = None
     mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
     permission_mode: PermissionMode | None = None
     continue_conversation: bool = False

tests/test_transport.py

@@ -108,6 +108,21 @@ def test_build_command_with_system_prompt_preset_and_append(self):
         assert "--append-system-prompt" in cmd
         assert "Be concise." in cmd
 
+    def test_build_command_with_system_prompt_file(self):
+        """Test building CLI command with system prompt file."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(
+                system_prompt={"type": "file", "path": "/path/to/prompt.md"},
+            ),
+        )
+
+        cmd = transport._build_command()
+        assert "--system-prompt" not in cmd
+        assert "--append-system-prompt" not in cmd
+        assert "--system-prompt-file" in cmd
+        assert "/path/to/prompt.md" in cmd
+
     def test_build_command_with_options(self):
         """Test building CLI command with options."""
         transport = SubprocessCLITransport(

tests/test_types.py

@@ -144,6 +144,16 @@ def test_claude_code_options_with_system_prompt_preset_and_append(self):
             "append": "Be concise.",
         }
 
+    def test_claude_code_options_with_system_prompt_file(self):
+        """Test Options with system prompt file."""
+        options = ClaudeAgentOptions(
+            system_prompt={"type": "file", "path": "/path/to/prompt.md"},
+        )
+        assert options.system_prompt == {
+            "type": "file",
+            "path": "/path/to/prompt.md",
+        }
+
     def test_claude_code_options_with_session_continuation(self):
         """Test Options with session continuation."""
         options = ClaudeAgentOptions(continue_conversation=True, resume="session-123")