From b0a525e75010f7cd2526da529a58398771c92b5e Mon Sep 17 00:00:00 2001
From: Ron Mordechai <ronmrdechai@fb.com>
Date: Thu, 19 Feb 2026 17:50:02 +0200
Subject: [PATCH] Add SystemPromptFile support for --system-prompt-file CLI
 flag

Allow users to specify a file path for the system prompt via a new
SystemPromptFile TypedDict, which passes --system-prompt-file to the CLI.
---
 .../_internal/transport/subprocess_cli.py         |  2 ++
 src/claude_agent_sdk/types.py                     |  9 ++++++++-
 tests/test_transport.py                           | 15 +++++++++++++++
 tests/test_types.py                               | 10 ++++++++++
 4 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
index 1f0aac58..d9d5fb30 100644
--- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
+++ b/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:
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index 3ea89d5a..43cdfd12 100644
--- a/src/claude_agent_sdk/types.py
+++ b/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
diff --git a/tests/test_transport.py b/tests/test_transport.py
index 65e6ada7..0763f269 100644
--- a/tests/test_transport.py
+++ b/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(
diff --git a/tests/test_types.py b/tests/test_types.py
index 95a88bfa..b2578e24 100644
--- a/tests/test_types.py
+++ b/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")