feat: add session_id option to ClaudeAgentOptions (#750)

## Summary

Adds the `session_id` option to `ClaudeAgentOptions`, allowing users to
specify a custom session ID (UUID) rather than having one
auto-generated. This brings the Python SDK to parity with the TypeScript
SDK's `sessionId` option and the CLI's `--session-id` flag.

Fixes #338

## Problem

Users who want to control session IDs (e.g., for batch processing,
session tracking, or integration with external systems) currently have
to extract the auto-generated ID from the first `SystemMessage`:

```python
session_id = None
async for msg in query(prompt="..."):
    if hasattr(msg, "session_id"):
        session_id = msg.session_id  # awkward extraction
    ...
```

The CLI supports `--session-id <uuid>` and the TypeScript SDK exposes
`sessionId` in options, but the Python SDK had no equivalent.

## Fix

- **`types.py`**: Add `session_id: str | None = None` to
`ClaudeAgentOptions`
- **`subprocess_cli.py`**: Pass `--session-id` to the CLI when
`session_id` is set

```python
options = ClaudeAgentOptions(
    session_id="550e8400-e29b-41d4-a716-446655440000",
)
async for msg in query(prompt="...", options=options):
    # msg.session_id == "550e8400-e29b-41d4-a716-446655440000"
```

## Verification

**End-to-end with live SDK instance:**

```
Using custom session_id: f5e728c6-a604-48e2-8728-a08bde1f3c9e
  SystemMessage: session_id=N/A
  AssistantMessage: session_id=f5e728c6-a604-48e2-8728-a08bde1f3c9e
  AssistantMessage: session_id=f5e728c6-a604-48e2-8728-a08bde1f3c9e
  RateLimitEvent: session_id=f5e728c6-a604-48e2-8728-a08bde1f3c9e
  ResultMessage: session_id=f5e728c6-a604-48e2-8728-a08bde1f3c9e

Expected session_id: f5e728c6-a604-48e2-8728-a08bde1f3c9e
Actual session_id:   f5e728c6-a604-48e2-8728-a08bde1f3c9e
PASS: Session ID matches custom ID!
```

**Test suite:**
- 404 tests pass
- 2 unit tests added (`test_session_id`,
`test_session_id_not_set_by_default`)
- `ruff check` + `ruff format` clean
- `mypy src/` clean

Author: qing-ant

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

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

@@ -1088,6 +1088,7 @@ class ClaudeAgentOptions:
     permission_mode: PermissionMode | None = None
     continue_conversation: bool = False
     resume: str | None = None
+    session_id: str | None = None
     max_turns: int | None = None
     max_budget_usd: float | None = None
     disallowed_tools: list[str] = field(default_factory=list)

tests/test_transport.py

@@ -268,6 +268,28 @@ def test_session_continuation(self):
         assert "--resume" in cmd
         assert "session-123" in cmd
 
+    def test_session_id(self):
+        """Test custom session ID option."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(session_id="550e8400-e29b-41d4-a716-446655440000"),
+        )
+
+        cmd = transport._build_command()
+        assert "--session-id" in cmd
+        idx = cmd.index("--session-id")
+        assert cmd[idx + 1] == "550e8400-e29b-41d4-a716-446655440000"
+
+    def test_session_id_not_set_by_default(self):
+        """Test that --session-id is not passed when session_id is None."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(),
+        )
+
+        cmd = transport._build_command()
+        assert "--session-id" not in cmd
+
     def test_connect_close(self):
         """Test connect and close lifecycle."""