feat: expose session_id in ClaudeAgentOptions

Add session_id field to ClaudeAgentOptions that maps to the CLI's
--session-id flag, allowing server-side applications to control the
session file name for deterministic session file paths.

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

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: mike-nebari

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -233,6 +233,9 @@ def _build_command(self) -> list[str]:
         if self._options.resume:
             cmd.extend(["--resume", self._options.resume])
 
+        if self._options.session_id:
+            cmd.extend(["--session-id", self._options.session_id])
+
         # Handle settings and sandbox: merge sandbox into settings if both are provided
         settings_value = self._build_settings_value()
         if settings_value:

src/claude_agent_sdk/types.py

@@ -622,6 +622,7 @@ class ClaudeAgentOptions:
     system_prompt: str | SystemPromptPreset | None = None
     mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
     permission_mode: PermissionMode | None = None
+    session_id: str | None = None
     continue_conversation: bool = False
     resume: str | None = None
     max_turns: int | None = None

tests/test_transport.py

@@ -193,6 +193,17 @@ def test_session_continuation(self):
         assert "--resume" in cmd
         assert "session-123" in cmd
 
+    def test_build_command_with_session_id(self):
+        """Test building CLI command with session_id option."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(session_id="my-session-uuid"),
+        )
+
+        cmd = transport._build_command()
+        assert "--session-id" in cmd
+        assert "my-session-uuid" in cmd
+
     def test_connect_close(self):
         """Test connect and close lifecycle."""