feat: add ThinkingConfig types and effort option to ClaudeAgentOptions

- Add ThinkingConfigAdaptive, ThinkingConfigEnabled, ThinkingConfigDisabled
  TypedDict types and a ThinkingConfig union type in types.py
- Add `thinking: ThinkingConfig | None` field to ClaudeAgentOptions,
  which takes precedence over the deprecated `max_thinking_tokens`
- Add `effort: Literal["low", "medium", "high", "max"] | None` field
  to ClaudeAgentOptions, passed via --effort CLI flag
- Update subprocess_cli.py to resolve thinking config into
  --max-thinking-tokens: adaptive defaults to 32_000, enabled uses
  budget_tokens, disabled uses 0
- Export new ThinkingConfig types from the top-level package

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ashwin-ant

src/claude_agent_sdk/__init__.py

@@ -60,6 +60,10 @@
     SystemMessage,
     TextBlock,
     ThinkingBlock,
+    ThinkingConfig,
+    ThinkingConfigAdaptive,
+    ThinkingConfigDisabled,
+    ThinkingConfigEnabled,
     ToolPermissionContext,
     ToolResultBlock,
     ToolUseBlock,
@@ -334,6 +338,10 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "ClaudeAgentOptions",
     "TextBlock",
     "ThinkingBlock",
+    "ThinkingConfig",
+    "ThinkingConfigAdaptive",
+    "ThinkingConfigEnabled",
+    "ThinkingConfigDisabled",
     "ToolUseBlock",
     "ToolResultBlock",
     "ContentBlock",

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -297,10 +297,23 @@ def _build_command(self) -> list[str]:
                 # Flag with value
                 cmd.extend([f"--{flag}", str(value)])
 
-        if self._options.max_thinking_tokens is not None:
-            cmd.extend(
-                ["--max-thinking-tokens", str(self._options.max_thinking_tokens)]
-            )
+        # Resolve thinking config → --max-thinking-tokens
+        # `thinking` takes precedence over the deprecated `max_thinking_tokens`
+        resolved_max_thinking_tokens = self._options.max_thinking_tokens
+        if self._options.thinking is not None:
+            t = self._options.thinking
+            if t["type"] == "adaptive":
+                if resolved_max_thinking_tokens is None:
+                    resolved_max_thinking_tokens = 32_000
+            elif t["type"] == "enabled":
+                resolved_max_thinking_tokens = t["budget_tokens"]
+            elif t["type"] == "disabled":
+                resolved_max_thinking_tokens = 0
+        if resolved_max_thinking_tokens is not None:
+            cmd.extend(["--max-thinking-tokens", str(resolved_max_thinking_tokens)])
+
+        if self._options.effort is not None:
+            cmd.extend(["--effort", self._options.effort])
 
         # Extract schema from output_format structure if provided
         # Expected: {"type": "json_schema", "schema": {...}}

src/claude_agent_sdk/types.py

@@ -696,6 +696,22 @@ class StreamEvent:
 Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent
 
 
+class ThinkingConfigAdaptive(TypedDict):
+    type: Literal["adaptive"]
+
+
+class ThinkingConfigEnabled(TypedDict):
+    type: Literal["enabled"]
+    budget_tokens: int
+
+
+class ThinkingConfigDisabled(TypedDict):
+    type: Literal["disabled"]
+
+
+ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled
+
+
 @dataclass
 class ClaudeAgentOptions:
     """Query options for Claude SDK."""
@@ -753,7 +769,12 @@ class ClaudeAgentOptions:
     # Plugin configurations for custom plugins
     plugins: list[SdkPluginConfig] = field(default_factory=list)
     # Max tokens for thinking blocks
+    # @deprecated Use `thinking` instead.
     max_thinking_tokens: int | None = None
+    # Controls extended thinking behavior. Takes precedence over max_thinking_tokens.
+    thinking: ThinkingConfig | None = None
+    # Effort level for thinking depth.
+    effort: Literal["low", "medium", "high", "max"] | None = None
     # Output format for structured outputs (matches Messages API structure)
     # Example: {"type": "json_schema", "schema": {"type": "object", "properties": {...}}}
     output_format: dict[str, Any] | None = None