From 44c6f5503a9b54066e44c7be2c3eecad1384220e Mon Sep 17 00:00:00 2001 From: Ash Prabaker Date: Mon, 3 Nov 2025 13:17:48 +0000 Subject: [PATCH] feat: add tool_choice support Adds first_turn_tool_choice and ensure_tool_usage options to ClaudeAgentOptions for controlling tool usage in agentic loops. --- .../_internal/transport/subprocess_cli.py | 8 ++++++++ src/claude_agent_sdk/types.py | 7 +++++++ 2 files changed, 15 insertions(+) diff --git a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py index 0fc02b5..7ec8ebe 100644 --- a/src/claude_agent_sdk/_internal/transport/subprocess_cli.py +++ b/src/claude_agent_sdk/_internal/transport/subprocess_cli.py @@ -225,6 +225,14 @@ class SubprocessCLITransport(Transport): ["--max-thinking-tokens", str(self._options.max_thinking_tokens)] ) + if self._options.first_turn_tool_choice is not None: + cmd.extend( + ["--first-turn-tool-choice", json.dumps(self._options.first_turn_tool_choice)] + ) + + if self._options.ensure_tool_usage: + cmd.append("--ensure-tool-usage") + # Check if command line is too long (Windows limitation) cmd_str = " ".join(cmd) if len(cmd_str) > _CMD_LENGTH_LIMIT and self._options.agents: diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py index 17c1a98..08f285e 100644 --- a/src/claude_agent_sdk/types.py +++ b/src/claude_agent_sdk/types.py @@ -17,6 +17,9 @@ PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"] # Agent definitions SettingSource = Literal["user", "project", "local"] +# Tool choice types +ToolChoice = Literal["auto", "any", "none"] | dict[str, str] + class SystemPromptPreset(TypedDict): """System prompt preset configuration.""" @@ -557,6 +560,10 @@ class ClaudeAgentOptions: plugins: list[SdkPluginConfig] = field(default_factory=list) # Max tokens for thinking blocks max_thinking_tokens: int | None = None + # Tool choice for first turn only + first_turn_tool_choice: ToolChoice | None = None + # Ensure at least one tool is used before conversation ends + ensure_tool_usage: bool = False # SDK Control Protocol