ClaudeAgentOptions.effort typings are outdated, and CLI validation failures are surfaced as opaque ProcessError

[oubeichen]

Summary

ClaudeAgentOptions.effort in the Python SDK does not include "xhigh" in its type definition, even though current Claude Code CLI versions support it.

In addition, when the SDK is used with a Claude Code CLI version that does not support a newer --effort value, the failure is surfaced only as a generic ProcessError with:

Command failed with exit code 1
Error output: Check stderr output for details

This makes debugging unnecessarily difficult.

Why this matters

There are currently two separate issues:

1. Outdated Python type definitions

   • ClaudeAgentOptions.effort is typed as:
     • Literal["low", "medium", "high", "max"] | None
   • but current Claude Code CLI help includes:
     • low, medium, high, xhigh, max

2. Poor error surfacing

   • the SDK forwards --effort <value> directly to the CLI
   • if the installed CLI is older and rejects that value, the SDK raises only a generic ProcessError
   • the actual stderr reason is not included in the exception text

This creates a confusing failure mode:

• newer effort values appear unsupported from the Python types
• and if users try them anyway, failures are hard to diagnose

Affected version

Observed with:

• claude-agent-sdk==0.1.61

Relevant code locations

Outdated type definition

In claude_agent_sdk/types.py:

effort: Literal["low", "medium", "high", "max"] | None = None