anthropics / anthropics/claude-agent-sdk-python
Effort fallback (xhigh -> high off Opus 4.7) is silent and unobservable: expose effective effort or a strict mode
- Dominant language
- Python
- Stars
- 8.1k
- Forks
- 1.3k
- PR merge metrics
- PR metrics pending
Description
## Summary
`ClaudeAgentOptions.effort` documents a model-dependent fallback, but the SDK gives callers no way to detect when it happens.
From `types.py` at v0.2.94:
> - ``"xhigh"`` — Extended reasoning depth (Opus 4.7 only; falls back to ``"high"`` on other models).
The SDK forwards `--effort ` to the CLI verbatim (`_internal/transport/subprocess_cli.py`), and nothing in the resulting message stream reports the effort that was actually applied. So a caller who requests `xhigh` on a non-Opus-4.7 model gets a silently downgraded session that is indistinguishable from an honored one.
## Why this matters
We operate a service that fronts the SDK and offers callers a per-conversation effort setting with the contract "an explicit value is honored or refused, never silently changed." We can enforce that for the *vocabulary* (create-time validation against `EffortLevel`, and #834 covers surfacing CLI rejections), but not for the *model-dependent* half: the fallback documented above is invisible at the API surface, so the contract cannot be implemented on top of the SDK today. Maintaining our own model→supported-efforts table is not a real option — it goes stale with every model release.
Note the constraint that makes this non-trivial: one subprocess spans multiple models (subagents, per-turn model switches), so failing at spawn time for an unsupported (effort, model) pair may be the wrong shape. Observability may fit better than strictness.
## Ask (any of these would close the gap)
1. **Report effective effort** — include the applied effort level in the init and/or result messages (alongside the model that ran), so a downgrade is at least detectable per turn.
2. **Opt-in strict mode** — an option that turns the documented fallback into an error when the requested effort cannot apply to the resolved primary model.
3. **Queryable capability surface** — a way to ask the SDK/CLI which effort levels the selected model supports, so integrators can refuse up front without hand-maintaining a model table.
## Affected version
- `claude-agent-sdk==0.2.94` (SDK-bundled CLI)
## Related
- #834 — the value-level counterpart (typing drift and opaque CLI rejection). This issue is about the model-level fallback, which is documented rather than an error, and therefore currently silent by design.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.