[DOCS] Missing `effort` parameter in `ClaudeAgentOptions` (Python SDK)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/python - https://platform.claude.com/docs/en/build-with-claude/effort

Section/Topic

The ClaudeAgentOptions parameter list within the Python Agent SDK reference.

Current Documentation

The Effort guide (https://platform.claude.com/docs/en/build-with-claude/effort) states:

"Claude Opus 4.5 is the only model that supports the effort parameter... include the beta header effort-2025-11-24."

However, the Agent SDK reference - Python (https://platform.claude.com/docs/en/agent-sdk/python#claudeagentoptions) lists all available fields for the ClaudeAgentOptions dataclass but does not mention effort or an output_config parameter.

What's Wrong or Missing?

The effort parameter is a core feature for the new Claude Opus 4.5 model, allowing users to trade off between response thoroughness and token efficiency. While the feature is documented in the "Build with Claude" section, it is completely omitted from the Python SDK's ClaudeAgentOptions definition.

Reviewing the provided source code confirms this omission:

• src/claude_agent_sdk/types.py: The ClaudeAgentOptions dataclass lacks an effort or output_config field.
• src/claude_agent_sdk/_internal/transport/subprocess_cli.py: The _build_command method contains no logic to map an effort parameter to a CLI flag (e.g., --effort).

Suggested Improvement

1. Update the Python SDK Reference: Add effort to the ClaudeAgentOptions table.
2. Add Type Definitions: Update the documentation to show the parameter in the dataclass:

``python
@dataclass
class ClaudeAgentOptions:
# ... existing fields ...
effort: Literal["low", "medium", "high"] | None = None
``

1. Update Parameters Table:

| Property | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| effort | Literal["low", "medium", "high"] \| None | None | Control how many tokens Claude uses when responding. Requires Claude Opus 4.5 and the effort-2025-11-24 beta header. |

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: https://platform.claude.com/docs/en/build-with-claude/effort
• Discrepancy: The "Effort" guide shows a code example using output_config={"effort": "medium"}, but the Python SDK ClaudeAgentOptions does not support this structure, and the SDK reference lists neither effort nor output_config.
• Note: The TypeScript SDK reference (https://platform.claude.com/docs/en/agent-sdk/typescript) also appears to lack this parameter in its Options type definition.