Effort fallback (xhigh -> high off Opus 4.7) is silent and unobservable: expose effective effort or a strict mode

[cameronalizadeh-distyl]

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 <value> 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

• ClaudeAgentOptions.effort typings are outdated, and CLI validation failures are surfaced as opaque ProcessError #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.

[Yu-Haikuo]

Hi I am investigating a Python SDK contribution for this issue and found a possible gap between the Claude Code CLI’s internal messages and the messages it sends to the SDK.

One possible approach is to add an optional field to AssistantMessage:

@dataclass
class AssistantMessage:
    # Existing fields...
    effort: EffortLevel | None = None

The parser would read it from the incoming JSON:

effort=data.get("effort")

However, this only helps if the Claude Code CLI actually sends effort.

Findings from Claude Code CLI 2.1.261

In the inspected Claude Code CLI 2.1.261 implementation, internal assistant messages can contain effort, but the functions that build SDK output messages omit it for both the main agent and subagents.

To check this, I copied those functions from the installed Claude Code CLI 2.1.261 executable on my computer into a small Node.js test script. I replaced unrelated content-processing helpers with simple test substitutes, then supplied this input:

{
  "type": "assistant",
  "effort": "high",
  "message": {
    "model": "test-model",
    "content": [{ "type": "text", "text": "OK" }]
  }
}

Running the main-agent output function produced the following JSON, with unrelated metadata omitted here:

{
  "type": "assistant",
  "message": {
    "model": "test-model",
    "content": [{ "type": "text", "text": "OK" }]
  },
  "parent_tool_use_id": null
}

The subagent output also omitted effort, while retaining its parent_tool_use_id.

Test excerpt

The extracted function definitions and test helpers are omitted from this excerpt, so it cannot run by itself. Please note that XLe and Hmn are internal names from this Claude Code CLI build, not public SDK APIs.

The relevant calls were:

const input = {
  type: "assistant",
  effort: "high",
  uuid: "test-message",
  message: {
    model: "test-model",
    content: [{ type: "text", text: "OK" }]
  }
};

// XLe builds SDK output for the main agent's assistant messages.
// This function was extracted from the installed CLI 2.1.261 executable.
const primary = [...XLe(input, {}, [])][0];

// Hmn forwards a subagent's messages to the SDK with its parent tool-use ID.
// This function was extracted from the same executable.
const subagent = [...Hmn({
  parentToolUseID: "test-parent-tool",
  data: {
    message: input,
    agentType: "test-agent"
  }
}, [])][0];

console.log(Object.hasOwn(primary, "effort"));  // false
console.log(Object.hasOwn(subagent, "effort")); // false

When Python parses these outputs, effort is missing, so the proposed field becomes None. Tests that manually include "effort": "high" in the input pass, but they do not show whether the Claude Code CLI actually sends that field.

Clarifications

Before taking the Python implementation further, may I kindly have the following clarifications:

1. Am I correct that CLI 2.1.261 does not expose effective effort in SDK assistant messages, or is there another supported way to retrieve it?
2. If effective effort is available, does it also cover subagent responses and model changes within the same session?
3. If reporting effective effort requires a CLI change, would adding a Python API to query a model’s supported effort levels be a useful contribution toward this issue?

These clarifications would help avoid adding a Python field that remains None because the CLI does not send the corresponding data.