Claude Code 2.1.228: The Settings-Merge Bug That Put Custom Headers in the Wrong Tier

The most consequential change in Claude Code 2.1.228 is not the one most operators are reading about. Vertex AI's new fast credential failure gets attention because it shortens a painful retry loop from minutes to seconds. But the settings-merge bug fix has a subtler blast radius: in any deployment where a marketplace entry was redefined at a higher-precedence settings tier, that entry could silently inherit custom-headers from the lower-tier definition — and there was no warning.

What happened

Claude Code 2.1.228 shipped on August 11, 2026 with a cluster of fixes across three operational surfaces:

Settings tier isolation (security). A marketplace entry that exists in multiple settings tiers — for example, defined globally in the workspace settings and then overridden in a user settings file — should use only the headers defined at the higher-precedence tier. The bug meant that the custom-headers field from the lower-precedence entry could bleed into the higher-precedence one. Marketplace entries now merge as whole entries, not field-by-field.

Vertex AI credential fail-fast. Expired or missing Google Cloud credentials when using CLAUDE_CODE_USE_VERTEX=1 previously caused Claude Code to retry for several minutes before surfacing an error. They now fail within seconds. The fix is in the credential handshake, not in the retry count — the SDK now short-circuits on known-bad ADC state rather than exhausting the full backoff ladder.

Skill hardening from claude.ai sync. Skills synced from claude.ai can no longer shadow local commands or MCP prompts. Their descriptions are sanitized and labeled. On local machines, synced skill bodies cannot run ! shell commands or expand @ file references. This closes a supply-chain path where a malicious or misconfigured cloud-synced skill could execute arbitrary commands or exfiltrate file content through the expansion mechanism.

Write tool scope change. Newer model versions can now overwrite an existing file they have not read in the current session, matching what the Edit tool already allowed. Older model versions still require a prior read. This is a capability expansion, not a permission change — the tool permission model is unchanged.

Why it matters for AI engineering teams

The headers-bleed bug matters precisely because it is invisible. No warning fires. No error appears in logs. An operator who defined different authentication headers for a marketplace integration at the workspace level and then added a user-level override would find that the user-level entry might carry workspace-level auth headers into requests — the opposite of least-privilege.

The failure mode is asymmetric: it only triggers when the same marketplace entry ID exists in two or more settings tiers and the lower-precedence tier includes custom-headers. Teams that use a single settings tier, or who do not use marketplace with per-tier header overrides, are unaffected. But the bug is the kind that quietly changes security posture without surfacing in any observability pipeline.

The Vertex AI fix matters for a different reason: it changes how errors route in operator pipelines. If your Claude Code deployment includes Vertex AI as one provider path, previously a bad credential would stall the session for minutes before falling through to a fallback. That latency was long enough to time out upstream callers, generate spurious errors, and make credential rotation look like an outage. Seconds-fast failure means a routing layer can detect and redirect within a normal request budget.

The router/operator angle

Audit your marketplace settings tiers now. Run claude settings list across all your settings tiers and compare custom-headers values in any marketplace entry that appears in more than one tier. If they differ from what you expect at the higher-precedence tier, you were affected by this bug before 2.1.228. The fix changes merge behavior going forward but does not retroactively correct any sessions that ran under the old behavior.

Vertex AI fail-fast changes your error classification budget. If you run Vertex AI alongside other providers and rely on a fallback policy — for example, fall back from Vertex to a direct API endpoint when Vertex fails — the pre-228 behavior meant a Vertex credential failure would consume several minutes of your retry budget before triggering the fallback. Post-228, credential failures now surface fast enough that a well-configured router can make the fallback decision inside a single request timeout. The implication: if you currently set a generous per-provider timeout specifically to absorb Vertex credential retry loops, you can tighten that window without losing valid requests.

Skill sync hardening is a supply-chain boundary. The previous behavior allowed a skill that synced from claude.ai to shadow a local MCP prompt of the same name and to run ! commands in its body on local machines. In a multi-operator deployment where different teams share a Claude Code enterprise account, one team's uploaded skill could affect another team's local MCP setup. Post-228, synced skills are sandboxed: no shadowing, no shell execution, sanitized descriptions. If you have automation that relies on skill bodies running ! commands after syncing from claude.ai, those bodies will no longer execute — update them to explicit tool calls instead.

Write tool change requires model-version awareness. If your agent pipeline pins to older model versions and has workflows that intentionally read a file before writing it as a correctness check, those workflows are unaffected. If you use newer models and relied on the read-before-write requirement as an implicit safety gate, that gate is now gone for the Write tool. Explicit gates — either through pre-write read assertions in your orchestration layer or through operator-defined tool restrictions — remain the correct approach.

What TheRouter users should watch or try

Check whether any of your Claude Code deployments use marketplace entries with per-tier custom-headers configuration. If you route Claude Code through multiple settings contexts — for example, a team-level workspace config plus per-developer user configs — the 2.1.228 update changes what happens when those tiers define the same marketplace entry.

For Vertex AI routing: after upgrading to 2.1.228, re-measure your p99 error latency on the Vertex path with intentionally expired credentials. The new behavior should shift that latency from the two-to-four minute range to under fifteen seconds. That measurement tells you whether you can safely reduce your Vertex-specific timeout in the routing config to match your other provider timeout targets.

For background reading on Claude Code self-hosted runner deployment, see previous coverage in the TheRouter news section.