feat(claude-code): sync settings and keybindings to Claude Code v2.1.251

[miteshashar]

Syncs claude-code-settings.json and claude-code-keybindings.json from the last synced v2.1.220 (#6131) up to v2.1.251.

The per-setting reference moved out of the settings page into a new settings-reference page (219 keys, one section each). Both pages remain; settings now covers settings files, precedence and scopes. Most settings#... anchors in this schema no longer resolved to per-key content. Additions were reconciled against that page's full table and the 346-row env-vars table, not just the changelog.

Schema

Correctness fix: sandbox credential masking was rejected outright

sandbox.credentials.files[].mode and .envVars[].mode were a closed enum of ["deny"], and both item schemas set additionalProperties: false — so every documented credential-masking config failed validation. "mode": "mask" has been documented since v2.1.199 for environment variables and v2.1.221 for files.

Adds "mask" to both enums, the documented mask fields (extract, onExtractNoMatch, decode, maskClaims, injectHosts, plus maskDuplicates on files only), and the two missing sibling objects awsPairs and sigv4 (both v2.1.224). Every constraint is taken from the doc's own "Mask fields for files" / "Mask fields for environment variables" tables rather than inferred from the neighbouring shape — see sandboxing#protect-credentials.

New settings properties (23)

autoCompactWindow, autoContinueAtUsageLimit (v2.1.234), crossSessionInbound (v2.1.224), desktopSessionCleanupPeriodDays (v2.1.248), dialogExpiry (v2.1.224), disableCommandPluginSources (v2.1.229), disableDesktopLocalSessions, enableWorkflows, feedbackDrafts, isolatePeerMachines (v2.1.224), keybindingFlavor (v2.1.238), managedSourcesBehavior (v2.1.242), modelPricing (v2.1.242), promptCacheTtl and subagentPromptCacheTtl (v2.1.242), promptSuggestionEnabled, remote.defaultEnvironmentId, skipAutoPermissionPrompt, spellcheck (v2.1.235), switchModelsOnFlag (v2.1.170), syncClaudeAiSkills, terminalTitleFromRename, ultracode.

ultracode was skipped in #6131 because settings.md then stated the key "isn't read from settings.json". settings-reference#ultracode now states the opposite — "Claude Code reads this key but never writes it", Scope Any file — so that skip is superseded by a documentation change rather than reversed on judgement.

Removed environment variables (12)

$.env.properties models the env block inside a settings file. These 11 are documented as set by Claude Code into subprocesses, not read from that block, so listing them advertised keys that do nothing there:

CLAUDECODE, CLAUDE_CODE_BRIDGE_SESSION_ID, CLAUDE_CODE_CHILD_SESSION, CLAUDE_CODE_REMOTE, CLAUDE_CODE_REMOTE_SESSION_ID, CLAUDE_CODE_SESSION_ID, CLAUDE_EFFORT, CLAUDE_PID, CLAUDE_PROJECT_DIR, CLAUDE_CODE_TEAM_NAME, CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST.

The last two rest on weaker evidence than the rest: CLAUDE_CODE_TEAM_NAME is documented nowhere, and CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST is described as set by embedding host platforms. CLAUDE_CODE_PROCESS_WRAPPER was deliberately kept — its row says to set it in the env block of user or managed settings, the opposite of the others.

Plus CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION, removed upstream in v2.1.224 and now a no-op.

$.env keeps additionalProperties, so none of these removals can invalidate an existing settings file.

Removed settings properties (3)

• teammateDefaultModel — removed upstream in v2.1.234; settings-reference carries a warning that setting it has no effect, and points at CLAUDE_CODE_SUBAGENT_MODEL instead.
• skippedMarketplaces, skippedPlugins — documented on no page, and absent from live settings files on a machine with many plugins installed and several explicitly disabled.

New environment variables (39)

Five appear on no reference table at all and are documented only on Agent SDK pages: CLAUDE_AGENT_SDK_CLIENT_APP, CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS, CLAUDE_CODE_REPL, TRACEPARENT, TRACESTATE.

MCP_PROTOCOL_NEGOTIATION and MCP_SDK_GENERATION get no enum even though the docs name their two accepted values, because the docs also say an unrecognized value is ignored with a debug warning rather than rejected.

permissionRule

Adds the 18 documented tools the pattern was missing, so deny rules naming them stop being flagged as invalid in editors — raised by @asgeirtj in #6236. All 14 tools marked "Permission required: Yes" in tools-reference were already present; the gap was entirely in the no-permission-required set, which is legitimately denyable. Cd, KillShell and MultiEdit are retained as before.

That thread also proposed splitting the pattern into separate allow and deny forms. That half is not done here — see Skipped.

Marketplace git URLs

Relaxes the .git suffix requirement on the git source of extraKnownMarketplaces and blockedMarketplaces, so Azure DevOps and AWS CodeCommit URLs validate. This is @esp0's work from #5874, folded in with credit after being deferred in #6131. Per plugin-marketplaces#git-repositories: "The .git suffix is optional, so Azure DevOps and AWS CodeCommit URLs without the suffix work." strictKnownMarketplaces's git variant already carried no such pattern, so the schema was internally inconsistent.

Accuracy fixes

• workflowSizeGuideline: default unrestricted → medium, with the documented small (<5) / medium (<15) / large (<50) agent bounds. v2.1.219 is also the first version that reads the key from a settings file.
• outputStyle: add Concise (v2.1.237).
• browserExternalPageTools: add disable, which the desktop app also accepts — the previous enum rejected a valid value.
• disableAutoMode: a session that would start in auto mode starts in default instead; it does not reject --permission-mode auto as the description claimed.
• allowManagedPermissionRulesOnly: the description omitted local and --settings files, --allowedTools, hiding always-allow choices, and no longer saving new rules.
• parentSettingsBehavior: covers any embedding host including IDE extensions, not just the SDK, and "merge" applies host settings through a restrictive-only filter.
• fallbackModel: does not merge across settings files — the highest-precedence file supplies the whole chain.
• availableModels: a managed list applies exclusively and is never merged with lower scopes.
• enableArtifact: Scope is Any file; the claim that it is ignored in project and local settings was wrong.
• disableArtifact: now documented as deprecated in favour of enableArtifact.
• managedMcpServers: also deliverable through a Claude apps gateway policy's desktop block (gateway needs v2.1.232+).
• CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH: default 1 → 3 since v2.1.219.
• CLAUDE_CODE_SYNC_SKILLS: skills download to ~/.claude/skills/synced/ since v2.1.227.
• forceLoginMethod / forceLoginOrgUUID / forceLoginGatewayUrl: documented scope restrictions, including that only a managed source enforces rather than pre-selects.
• ANTHROPIC_CUSTOM_HEADERS: invalid-character failure behaviour (v2.1.227).
• CLAUDE_CODE_RETRY_WATCHDOG: fails immediately on a 429 reporting a spend limit or exhausted usage credits (v2.1.239).

UNDOCUMENTED prefixes dropped (4)

Setup, DirectoryAdded, autoMode.classifyAllShell and sandbox.network.strictAllowlist are all now documented; three of the four were marked UNDOCUMENTED by me in #6131 and the docs have since caught up.

Links

Audited all 161 top-level properties. 65 links migrated to settings-reference anchors, and 13 properties plus 13 hook events that carried no doc link at all now have one — every top-level property is now linked. Every migrated anchor was verified present in the page source; nested keys use hyphens for dots (#worktree-baseref, #attribution-sessionurl).

94 properties keep a feature-page link rather than settings-reference, even though 92 of them now also have a settings-reference section, because the feature page is usually the more specific home (sandbox → sandboxing, processWrapper → corporate-launcher). Only managedMcpServers and requireCoworkFullVmSandbox have no settings-reference section at all, consistent with them living solely on feature pages.

permissionRule now points at permissions#permission-rule-syntax, which holds the full rule syntax.

Separately, 8 links pointed at anchors that no longer exist on their page. A docs page returns 200 whether or not the fragment resolves, so a reachability check never caught them: alwaysThinkingEnabled → model-config#extended-thinking; allowedMcpServers and deniedMcpServers → managed-mcp#policy-based-control-with-allowlists-and-denylists; FORCE_PROMPT_CACHING_5M → prompt-caching#choose-the-ttl-yourself; and sandbox.enabled, sandbox.failIfUnavailable, sandbox.filesystem.allowWrite, sandbox.filesystem.allowRead → their per-key settings-reference anchors. Every anchored link in the schema now resolves to a real heading or id.

Keybindings

• chat:queueSubmit — documented, requires v2.1.247.
• DiffPanel context and app:cycleDiffBase — UNDOCUMENTED. Both are present in the v2.1.251 generated defaults (ctrl+x b in the DiffPanel context) but appear on no documentation page and in no changelog entry. DiffPanel is distinct from the documented DiffDialog context, which the schema already carried. The builtinAction and context enums are flat string arrays sharing one description, so there is no per-value place to record the UNDOCUMENTED. marker used elsewhere in this schema.

Tests

• modern-complete-config.json: all 23 new properties with non-default values, plus a full sandbox.credentials masking configuration exercising mask, extract, decode/maskClaims, maskDuplicates, injectHosts, awsPairs and sigv4.
• env-variables.json: all 39 new environment variables.
• enum-coverage.json, edge-cases.json, basic-config.json, complete-config.json, managed-settings.json, permissions-advanced.json: the remaining enum values and non-default values needed to satisfy the coverage gate's enum and default-value checks.
• permissions-advanced.json also covers mode: "deny" and the warn/deny/error variants of onExtractNoMatch.
• marketplace-host-pattern.json, managed-settings.json: Azure DevOps marketplace URLs without a .git suffix, carried over from feat(claude-code-settings): allow git marketplace URLs without .git suffix #5874.
• claude-code-keybindings/all-contexts.json, current-actions.json: the DiffPanel context and both new actions.

Negative tests

• invalid-enum-values.json: invalid values for the new settings and environment-variable enums, and for sandbox.credentials mode, onExtractNoMatch and all three sigv4 keys.
• Removed invalid-blocked-marketplace-git-url.json and invalid-marketplace-host-pattern.json, which asserted that a missing .git suffix is invalid — carried over from feat(claude-code-settings): allow git marketplace URLs without .git suffix #5874.
• Entries in invalid-enum-values.json that relied on the removed environment variables were dropped. A negative test file fails as long as any one property is invalid, so leaving them would have left silently inert assertions behind.

Skipped

• modelPicker and spinnerTipsOverride's tipsFile/label — covered by @GeneralD's open PR feat(claude-code-settings): add modelPicker, spinnerTipsOverride tipsFile/label #6266, which is recent and passing CI. I independently verified modelPicker's shape as correct and deliberately left both out so that PR lands on its own merit. I have commented there about three documented numeric/length bounds it is missing.
• Splitting permissionRule into separate allow and deny patterns (proposed in claude-code-settings: add missing documented tools to permissionRule pattern #6236) — the right idea, but restricting allow to the 14 permission-required tools would remove 16 names that validate today, including Read, which appears in this schema's own examples and is the subject of fix(claude-code-settings): allow wildcard-only args like Read(*) and Skill(*) #5707. The docs do not say allow rejects a no-permission tool, only that such a rule has no effect. Deferred rather than tightened on an argument from silence.
• CLAUDE_CODE_MESSAGING_SOCKET, CLAUDE_CODE_MESSAGING_TOKEN, CLAUDE_CODE_PROJECT_DIR_NAME, CLAUDE_CODE_RESTRICTED — documented, but each states it is never read from a settings file's env block, so they do not belong in $.env.properties.
• Narrowing enabledPlugins — settings-reference documents only the Boolean map form, but the schema's anyOf also accepts an array of strings. Narrowing on absence of documentation risks rejecting a live legacy shape.
• CLAUDE_CODE_SUBAGENT_MODEL precedence — the v2.1.251 changelog says it now sets a default rather than overriding everything, but env-vars.md and sub-agents.md both still document the old resolution order. Left matching the docs.
• proxyAuthHelper — appears in settings-reference's managedSourcesBehavior merge-rules table but has no section of its own, so there is no type or description to cite.

🤖 Generated with Claude Code

[github-actions]

Thanks for the PR!

This section of the codebase is owned by @domdomegg, @bogini, and @sarahdeaton - if they write a comment saying "LGTM" then it will be merged.