[DOCS] [Python SDK] `disable_parallel_tool_use` in `tool_choice` is ignored by the CLI transport logic

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use#parallel-tool-use

Section/Topic

The section "Parallel tool use" and the "Forcing tool use" table.

Current Documentation

The documentation states:

"By default, Claude may use multiple tools to answer a user query. You can disable this behavior by: - Setting disable_parallel_tool_use=true when tool_choice type is auto... - Setting disable_parallel_tool_use=true when tool_choice type is any or tool..."

Furthermore, the Python SDK types.py file correctly defines the ToolChoice variants (ToolChoiceAuto, ToolChoiceAny, ToolChoiceTool) to include an optional disable_parallel_tool_use: bool field.

What's Wrong or Missing?

While the documentation and the SDK's public type definitions suggest this feature is supported, the internal logic that actually communicates with the Claude Code CLI is missing the implementation.

In src/claude_agent_sdk/_internal/transport/subprocess_cli.py, the _build_command method (responsible for translating ClaudeAgentOptions into CLI flags) does not check for or pass a flag related to disabling parallel tool use. Even if a user sets disable_parallel_tool_use=True in their Python code, the underlying claude binary never receives this instruction, resulting in the model still attempting parallel tool calls.

Suggested Improvement

The documentation for implementing tool use should clarify if disable_parallel_tool_use is currently supported via the Agent SDK's CLI transport.

Technically, the SDK implementation needs to be updated to match the documentation.
In src/claude_agent_sdk/_internal/transport/subprocess_cli.py, logic should be added to detect the flag within the tool_choice object.

Suggested internal logic fix:

# Inside SubprocessCLITransport._build_command
if self._options.tool_choice and isinstance(self._options.tool_choice, dict):
    if self._options.tool_choice.get("disable_parallel_tool_use"):
        cmd.append("--disable-parallel-tool-use")

If the CLI does not yet support a --disable-parallel-tool-use flag, the documentation should be updated to include a warning that this specific parameter is currently ignored when using the Python Agent SDK.

Impact

High - Prevents users from using a feature

Additional Context

• Code Evidence: In src/claude_agent_sdk/types.py, ToolChoiceAuto is defined as:

``python
class ToolChoiceAuto(TypedDict):
type: Literal["auto"]
disable_parallel_tool_use: NotRequired[bool]
``

• The Gap: src/claude_agent_sdk/_internal/transport/subprocess_cli.py (Lines 310-335 in the current version) handles permission_mode, model, and max_turns, but completely omits any reference to the disable_parallel_tool_use property found in the tool_choice types.
• Related Docs: The documentation currently suggests using a "batch tool" workaround for Sonnet 3.7, but for newer models where this is a native parameter, the SDK should ideally pass the bit through to the CLI.