Administrative Effort Ceilings for Reasoning Budget¶
An administrative effort ceiling caps reasoning effort above every operator control, so a higher request runs at the cap instead of being refused.
Set an effort ceiling when the levels you remove are ones your workload does not need. Claude Code shipped the control in v2.1.267 on 9 September 2026 (changelog). maxEffortLevel caps the effort level a session can use, and any higher level "runs at the cap instead, including one from /effort, the /model picker, --effort, CLAUDE_CODE_EFFORT_LEVEL, a skill's or subagent's effort frontmatter, or the model's own default" (settings reference). Where task difficulty varies widely, the ceiling takes depth the work needed, and the docs describe no warning when maxEffortLevel clamps a run.
What makes it a ceiling rather than a default¶
Claude Code resolves a session's effort from an explicit choice (CLAUDE_CODE_EFFORT_LEVEL, --effort, or /effort), then a held model default, then your saved settings, then the model's own default (model configuration). Every entry in that chain is a preference, and a higher-precedence source replaces a lower one.
maxEffortLevel does not join the chain. It composes by minimum: "When several scopes set a cap, the lowest applies, so a cap set in one scope can't be raised from another" (settings reference). That sentence is the whole distinction, and it is the merge rule behind most-restrictive-wins fusion applied to a scalar. An organization that deploys the key in managed settings gets a bound no user file can lift. A developer who sets it in ~/.claude/settings.json binds themselves on identical terms.
Why it works¶
The clamp runs in the client. Claude Code "applies the cap itself before each request, so it holds on every provider, including Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry" (settings reference). Enforcing before the request is what makes the cap portable, and it is the difference between the two routes an organization has. Per-role effort limits are a Claude Enterprise feature delivered from the server, while maxEffortLevel applies on any plan and any provider and caps effort on the client (model configuration). Where both reach the same model, "the lower cap applies".
When this backfires¶
- The workload needs the tier you cut. On GameEngineBench's C++ runtime tasks, "Increasing reasoning effort from medium to high to xhigh raises pass@1 from 9.1% to 19.1% to 29.1%" (GameEngineBench). A ceiling at medium buys that 20-point gap on work of that shape.
- Nobody sees the clamp. The docs describe no warning for the
maxEffortLevelclient cap. For Enterprise per-role limits, a plain-text--printrun with--effortabove the cap writes a warning to stderr naming the requested and applied levels. Interactive sessions,jsonorstream-jsonoutput, and background agents send it to the debug log instead (model configuration). Unattended runs are the case least able to notice. - The cap lowers the depth ultracode runs at. From v2.1.284, an effort cap such as
maxEffortLevel"lowers that level without turning ultracode off", so Claude still plans workflows, each at the capped level. Before v2.1.284, a cap belowxhighkept ultracode off (settings reference). - Effort was not the binding constraint. Capping to curb overthinking assumes effort drives the behavior you dislike. On FixedBench, correct-abstention across four effort levels moved from 61.5% to 65.8%, a change "notably smaller than the confidence intervals of ∼±7.0%" (Coding Agents Don't Know When to Act).
The rival control bounds volume instead of depth. GitHub's premium request overage policy offers an enterprise or organization two options, one of which is to "Block usage when your included premium requests are exhausted" (GitHub Changelog). A quota fails loudly. Work stops and somebody asks why. A ceiling fails quietly, and with no documented warning for the client cap you learn about it at review.
Example¶
{
"maxEffortLevel": "medium",
"modelSettings": {
"claude-sonnet-4-6": {
"maxEffortLevel": "max"
}
}
}
This caps every model at medium and exempts Sonnet 4.6, because a "max" value sets no cap (settings reference). Deployed in managed settings, no user file raises either value.
Key Takeaways¶
- A cap composes by minimum across settings scopes while an
effortLevelresolves by precedence, so setting the cap anywhere binds every source that sets it higher. - The clamp runs client-side before each request, which is why it holds on Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry.
- The docs describe no warning when
maxEffortLevelclamps a run. Enterprise per-role limits warn on stderr only for plain-text--printruns with--effort. If you cap and also run agents in CI, check the applied level yourself rather than assuming the requested one ran. - From v2.1.284 a cap lowers the level ultracode runs at without switching it off. Before that version, a cap below
xhighkept ultracode off.
Related¶
- Interactive Effort Sliders: Per-Turn Reasoning-Budget Controls — the per-turn operator control a ceiling bounds
- Heuristic-Based Effort Scaling in Agent System Prompts — effort sized from task cues rather than from policy
- Reasoning Budget Allocation: The Reasoning Sandwich — phase-varying effort, which a low ceiling flattens
- Tenant Model Policy: Organization-Scoped Rules for AI Model Selection — the same admin tier applied to model choice
- Codified Effort and Escalation Policy in the Instruction File — the written default that a ceiling is not
- Subagent Effort Floors Instead of Session Inheritance — the default underneath the chain, where the ceiling is the bound above it