feat(types): add "xhigh" to effort Literal (#914)

## Summary

Adds `"xhigh"` to the `effort` `Literal` on both `ClaudeAgentOptions`
and `AgentDefinition`, matching the CLI (`claude --help` lists `low,
medium, high, xhigh, max`) and the TypeScript SDK's `EffortLevel` type.
The docstring is updated to note that `xhigh` is Opus 4.7-specific and
falls back to `high` on other models.

Previously, type checkers rejected `ClaudeAgentOptions(effort="xhigh")`
even though the CLI supports it:

```
error: Argument "effort" to "ClaudeAgentOptions" has incompatible type
"Literal['xhigh']"; expected "Literal['low', 'medium', 'high', 'max'] | None"
```

Addresses the typing half of #834. The error-surfacing half (CLI
validation failures surface as opaque `ProcessError` without stderr)
overlaps with #798.

## Relationship to #835

#835 also adds `xhigh` plus stderr retention, but is based on a pre-#885
main and now conflicts (it touches `_stderr_task_group`, which #885
removed). This PR is the minimal, conflict-free typing-only fix; the
stderr work can land via #828 or a rebased #835.

## Tests

- New `test_effort_accepts_xhigh_level` (AgentDefinition serialization)
and `test_build_command_with_effort_xhigh` (CLI flag construction).
- Full suite: 718 passed, 2 pre-existing failures in
`test_transcript_mirror.py` (eager-flush, from #905) — same baseline as
#908/#909/#911/#912.
- `ruff check` / `ruff format`: clean.
- `mypy src/`: clean.
- Live e2e proof in PR comment below.

## Changelog

### New Features

- Added `"xhigh"` to the `effort` Literal on `ClaudeAgentOptions` and
`AgentDefinition` (#914)

---
_Generated by [Claude
Code](https://claude.ai/code/session_012Qn9YazWceoUqnjM74eJvU)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: qing-ant

src/claude_agent_sdk/types.py

@@ -95,7 +95,7 @@ class AgentDefinition:
     initialPrompt: str | None = None  # noqa: N815
     maxTurns: int | None = None  # noqa: N815
     background: bool | None = None
-    effort: Literal["low", "medium", "high", "max"] | int | None = None
+    effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None
     permissionMode: PermissionMode | None = None  # noqa: N815
 
 
@@ -1776,14 +1776,16 @@ class ClaudeAgentOptions:
     See https://docs.anthropic.com/en/docs/build-with-claude/adaptive-thinking.
     """
 
-    effort: Literal["low", "medium", "high", "max"] | None = None
+    effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None
     """Controls how much effort Claude puts into its response.
 
     Works with adaptive thinking to guide thinking depth.
 
     - ``"low"`` — Minimal thinking, fastest responses.
     - ``"medium"`` — Moderate thinking.
     - ``"high"`` — Deep reasoning (default).
+    - ``"xhigh"`` — Extended reasoning depth (Opus 4.7 only; falls back to
+      ``"high"`` on other models).
     - ``"max"`` — Maximum effort.
 
     See https://docs.anthropic.com/en/docs/build-with-claude/effort.

tests/test_transport.py

@@ -101,6 +101,16 @@ def test_cli_path_accepts_pathlib_path(self):
         # Path object is converted to string, compare with str(path)
         assert transport._cli_path == str(path)
 
+    def test_build_command_with_effort_xhigh(self):
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(effort="xhigh"),
+        )
+
+        cmd = transport._build_command()
+        assert "--effort" in cmd
+        assert cmd[cmd.index("--effort") + 1] == "xhigh"
+
     def test_build_command_with_system_prompt_string(self):
         """Test building CLI command with system prompt as string."""
         transport = SubprocessCLITransport(

tests/test_types.py

@@ -599,6 +599,18 @@ def test_effort_accepts_named_level(self):
 
         assert payload["effort"] == "high"
 
+    def test_effort_accepts_xhigh_level(self):
+        from claude_agent_sdk import AgentDefinition
+
+        agent = AgentDefinition(
+            description="test",
+            prompt="p",
+            effort="xhigh",
+        )
+        payload = self._serialize(agent)
+
+        assert payload["effort"] == "xhigh"
+
     def test_effort_accepts_integer(self):
         from claude_agent_sdk import AgentDefinition