Claude Code 2.1.267: Operator Effort Caps, Prompt-Cache Stability, and a Marketplace Containment Fix

Version 2.1.267 ships three changes that touch operator configuration directly, alongside a batch of prompt-cache stability fixes whose aggregate effect on token costs is large enough to be worth mapping out. This isn't a single-headline release; the value is in understanding which changes require operator action and which are passive improvements.

Effort governance: what maxEffortLevel actually enforces

The new maxEffortLevel setting can be placed at the top level of claude.json or under a specific model's entry inside modelSettings. It caps the effort level ceiling for every provider the operator routes through — including Bedrock, Vertex, and Foundry — not just Anthropic direct.

The critical behavior to understand: users can still pick a lower effort level than the cap. They cannot pick a higher one. This is a ceiling, not a floor and not a fixed value.

Why this matters for cost governance: effort levels on extended-thinking models have a compounding effect on token consumption. A user who runs every session at maximum effort in a fleet deployment can produce costs that are an order of magnitude above baseline. Previously, the only controls were organization-wide managed settings or model-tier restrictions. Neither gave operators a way to say "this deployment runs on opus-4.7, but effort tops out at medium."

Configuration shape:

// Top-level cap — applies to every model
{
  "maxEffortLevel": "medium"
}

// Per-model cap — useful when the fleet uses mixed model tiers
{
  "modelSettings": {
    "claude-opus-4-7": {
      "maxEffortLevel": "high"
    },
    "claude-fable-5-1": {
      "maxEffortLevel": "low"
    }
  }
}

The cross-provider scope is the important part. Before this setting, operators routing through Bedrock or Vertex had no effort-level control that survived a provider switch. The cap now travels with the session regardless of which backend ultimately handles the request.

--system-prompt-snapshot off and iterative prompt workflows

Claude Code records the system prompt at session start and replays the snapshot on subsequent turns. This is good for prompt-cache stability but breaks iterative workflows where the operator is actively modifying the system prompt between runs and wants the model to see the current version on every request rather than the one recorded at session open.

--system-prompt-snapshot off disables the recording step. The system prompt is read fresh from the configuration file at each request boundary. The tradeoff is explicit: prompt-cache reuse for the system prefix drops to zero, because the prefix is no longer stable between turns. For deployment-time iteration and A/B testing of system prompt variants, this is the correct tradeoff. For production steady-state, leave it on.

This flag is useful specifically during the period when an operator is tuning a deployed system prompt and running evaluation sessions against live user inputs. Without it, the recorded snapshot means each evaluation session is testing a different prompt than the one currently on disk, which produces misleading signal.

Marketplace containment bypass: what broke and who is affected

A marketplace entry path containing a backslash could bypass the containment check for fetched marketplaces on macOS and Linux. The check validates that the resolved path stays inside the configured marketplace root; the backslash caused the path normalization to produce a string that passed the check while resolving to a location outside the root.

Affected: any operator running a self-hosted Claude Code deployment with a custom marketplace, where the marketplace entry manifests contain paths with backslashes. This is uncommon on Unix systems — backslashes in paths are rare — but possible if marketplace entries were authored on Windows or generated by tooling that uses backslash separators.

The fix normalizes the path before the containment check rather than after. No operator action is required unless you have existing marketplace entries that contained intentional or unintentional backslash paths, in which case you should audit those entries now. An identical fix was already shipped in 2.1.265 for plugin paths under --plugin-dir; this closes the same class of issue in the marketplace fetch path.

Prompt-cache stability: twelve fixes, one budget impact

2.1.267 contains twelve separate fixes for prompt-cache break conditions. Listing them individually understates the impact; the pattern they address is worth naming.

The core issue: Claude Code caches the system prompt prefix and tool definitions at session start. Any event that causes these to be re-rendered mid-session — a model switch, a tool reconnection, an MCP server reconnect, a subagent fork, a session resume — breaks the cache and bills the prefix tokens again as uncached input. At $3–15 per million cached tokens versus $15–75 per million uncached, repeated breaks in a long session or a high-volume pipeline accumulate fast.

The fixes address specific trigger conditions:

• Model switch via /model: previously re-sent every tool definition, causing a full cache miss. Now the tool list is stable across model changes.
• MCP server reconnect mid-session: previously added reconnected tools to the list in a way that broke the stable prefix. Fixed for models with tool search support (deferred definitions) and others.
• Subagent fork and resume: subagent start context and preloaded skills were being moved out of the prompt prefix on later turns, invalidating the cache for the agent's own subsequent requests.
• Session resume after /compact: a spurious "Continue from where you left off" turn was inserted, changing the system prompt prefix and invalidating the cache for the entire resumed session.
• --system-prompt and --append-system-prompt sessions: these now record the system prompt and tool definitions once instead of re-rendering on each turn.

For operators running workflows with long-lived sessions, frequent /model switches, or MCP connectors that reconnect on failures, the aggregate effect of these fixes will be measurable in the token billing breakdown. The prompt-cache hit rate for multi-turn sessions should increase after upgrading.

What to do

• maxEffortLevel: set it if you have cost governance requirements for extended-thinking model deployments. The per-model granularity under modelSettings is useful for mixed-tier fleets. No action needed if you are not using extended-thinking models.
• --system-prompt-snapshot off: useful during active system prompt iteration; revert to default behavior once the prompt is stable.
• Marketplace audit: if your marketplace entries contain backslash-delimited paths, audit them. The fix is in 2.1.267; entries with backslash paths would have been passing the containment check before this release.
• Upgrade for cache stability: if prompt-cache miss rate is a cost concern, 2.1.267 is a meaningful improvement. No configuration change needed; the fixes are behavioral.