[FEATURE] Environment variables for default and max effort level (shared-host admin use case)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code currently exposes effort level via CLAUDE_CODE_EFFORT_LEVEL (env), effortLevel (settings.json), --effort (CLI), and /effort / /model (in-session). None of these combine to solve the shared-host admin case:

• CLAUDE_CODE_EFFORT_LEVEL set at the system level cannot be overridden by a user's settings.json, --effort, or /effort — once set by the admin, it is effectively a hard-coded value, not a default. This makes it unusable for expressing "a default that users can override."
• effortLevel in a managed settings.json behaves the same way: managed settings override user settings, so it cannot express a default either.
• /effort during a session persists back to settings.json, so users who override a system default must remember to restore their preferred value afterward — and users who prefer a specific level see it silently rewritten by transient overrides.
• --effort is per-invocation only and does not help with interactive sessions started without it.

The net effect on shared development hosts (CI runners, shared VMs, Rocky Linux managed by a system admin) is that admins must choose between:

1. Setting a hard cap via CLAUDE_CODE_EFFORT_LEVEL or managed settings.json — which users cannot raise even temporarily for a task that warrants it.
2. Setting nothing — leaving every session at the model default (xhigh on Opus 4.7), which rapidly consumes shared quota, especially for autonomous multi-agent workflows that restart frequently.
3. Wrapping claude in a shell script that injects --effort — fragile, easy to bypass, and doesn't survive /effort changes mid-session.

What's missing is the ANTHROPIC_DEFAULT_OPUS_MODEL pattern: a default that applies at session start but remains overridable, plus (optionally) a separate ceiling that enforces quota boundaries without locking in a single value.

Proposed Solution

Two new environment variables, modeled on ANTHROPIC_DEFAULT_*_MODEL:

CLAUDE_CODE_DEFAULT_EFFORT_LEVEL

• Sets the session's starting effort level
• Overridable per-session via --effort, /effort, /model
• Does not persist to settings.json (session-scoped)
• Overrides any persisted effortLevel at session start when set
• Example: CLAUDE_CODE_DEFAULT_EFFORT_LEVEL=high

CLAUDE_CODE_MAX_EFFORT_LEVEL (optional; could ship as v2)

• Sets a ceiling above which effort cannot go
• Silently caps: if MAX=high and user runs /effort xhigh, applies as high
• Ignored if below DEFAULT (e.g., MAX=low DEFAULT=high → uses high)
• Allows admins to enforce quota boundaries

Both should follow the existing settings precedence: system-managed > user-scoped.

Alternative Solutions

Alternative: Repurpose CLAUDE_CODE_EFFORT_LEVEL

The MAX variable could be avoided entirely by changing the semantics of the existing CLAUDE_CODE_EFFORT_LEVEL to behave as a ceiling rather than a hard-coded value:

• If CLAUDE_CODE_EFFORT_LEVEL is set, treat it as the maximum allowable effort. Users and /effort may set any level at or below it; attempts to exceed it silently cap.
• Combined with CLAUDE_CODE_DEFAULT_EFFORT_LEVEL, this gives admins a clean two-variable model (DEFAULT + existing EFFORT_LEVEL-as-ceiling) without introducing a third name.

This is technically a behavior change for existing users of CLAUDE_CODE_EFFORT_LEVEL, but the practical impact is minimal: today the var acts as a hard pin, and the new behavior only differs when a user tries to set a lower effort (which currently fails silently and would now succeed). Users who want the old "hard pin" behavior can achieve it by setting DEFAULT and EFFORT_LEVEL (ceiling) to the same value.

If a clean break is undesirable, CLAUDE_CODE_MAX_EFFORT_LEVEL remains a viable additive alternative.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Example Usage

# System-wide wrapper or systemd env
export CLAUDE_CODE_DEFAULT_EFFORT_LEVEL=high

# User can still override mid-session
claude           # starts at high
/effort xhigh    # overrides for this session, does NOT persist
# next session starts at high again

Additional Context

Preconditions

This depends on fixes to existing bugs:

• #52534 — Opus 4.7 ignores CLAUDE_CODE_EFFORT_LEVEL on session start
• #54249 — settings.json rejects "max" even though --effort max is valid

Without these, the new env vars would inherit the same broken precedence at startup.

Analogy

This mirrors ANTHROPIC_DEFAULT_OPUS_MODEL but for effort levels. Unlike /effort which persists, CLAUDE_CODE_DEFAULT_EFFORT_LEVEL is ephemeral (session-scoped), so admins can set safe defaults without hijacking user preferences.

Open Questions

• Should /effort gain a --session-only flag, or should the env var simply suppress persistence while it is set?
• max/xhigh are not valid on all models (e.g., Haiku 4.5). Should MAX_EFFORT_LEVEL silently cap per-model capabilities, or should this land alongside a per-model effort config (see #51059)?