feat: add SDK beta support with SdkBeta type and betas option (#390)

Port the SdkBeta type and betas option from the TypeScript SDK to enable
SDK users to pass beta feature flags (e.g., 1M context window) to the
CLI.

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

Co-authored-by: Claude <[email protected]>

Author: ashwin-ant

src/claude_agent_sdk/__init__.py

@@ -42,6 +42,7 @@
     SandboxIgnoreViolations,
     SandboxNetworkConfig,
     SandboxSettings,
+    SdkBeta,
     SdkPluginConfig,
     SettingSource,
     StopHookInput,
@@ -345,6 +346,8 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "SettingSource",
     # Plugin support
     "SdkPluginConfig",
+    # Beta support
+    "SdkBeta",
     # Sandbox support
     "SandboxSettings",
     "SandboxNetworkConfig",

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -203,6 +203,9 @@ def _build_command(self) -> list[str]:
         if self._options.fallback_model:
             cmd.extend(["--fallback-model", self._options.fallback_model])
 
+        if self._options.betas:
+            cmd.extend(["--betas", ",".join(self._options.betas)])
+
         if self._options.permission_prompt_tool_name:
             cmd.extend(
                 ["--permission-prompt-tool", self._options.permission_prompt_tool_name]

src/claude_agent_sdk/types.py

@@ -14,6 +14,9 @@
 # Permission modes
 PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"]
 
+# SDK Beta features - see https://docs.anthropic.com/en/api/beta-headers
+SdkBeta = Literal["context-1m-2025-08-07"]
+
 # Agent definitions
 SettingSource = Literal["user", "project", "local"]
 
@@ -614,6 +617,8 @@ class ClaudeAgentOptions:
     disallowed_tools: list[str] = field(default_factory=list)
     model: str | None = None
     fallback_model: str | None = None
+    # Beta features - see https://docs.anthropic.com/en/api/beta-headers
+    betas: list[SdkBeta] = field(default_factory=list)
     permission_prompt_tool_name: str | None = None
     cwd: str | Path | None = None
     cli_path: str | Path | None = None