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

オープン
#1,244 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement
主要言語
Python
スター
8.1k
フォーク
1.3k
PR マージ指標
PR 指標を取得中

説明

## 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.

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。