From d58615df0719370a60757018ca8085e9f22b2fcd Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Sat, 9 May 2026 19:54:40 +0500 Subject: [PATCH] =?UTF-8?q?chore(claude-settings):=20drift=20refresh=20to?= =?UTF-8?q?=20v2.1.138=20=E2=80=94=20add=207=20settings=20keys=20+=206=20e?= =?UTF-8?q?nv=20vars?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bump report version badge and body header from v2.1.126 → v2.1.138 (12-version gap). Add 7 settings keys: worktree.baseRef (v2.1.133), sandbox.bwrapPath / sandbox.socatPath (v2.1.133, managed Linux/WSL), skillOverrides (v2.1.129), parentSettingsBehavior (v2.1.133) and policyHelper (v2.1.136) in a new "Dynamic & Parent-Tier Policy" subsection under Settings Hierarchy. Extend autoMode description with the hard_deny array (v2.1.136). Add 6 new env vars (CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN, CLAUDE_CODE_FORCE_SYNC_OUTPUT, CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY, CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL). Co-Authored-By: Claude --- best-practice/claude-settings.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/best-practice/claude-settings.md b/best-practice/claude-settings.md index b8c5352..e936c73 100644 --- a/best-practice/claude-settings.md +++ b/best-practice/claude-settings.md @@ -1,9 +1,9 @@ # Settings Best Practice -![Last Updated](https://img.shields.io/badge/Last_Updated-May%2001%2C%202026%203%3A29%20PM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.126-blue?style=flat&labelColor=555)
+![Last Updated](https://img.shields.io/badge/Last_Updated-May%2009%2C%202026%206%3A58%20PM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.138-blue?style=flat&labelColor=555)
[![Implemented](https://img.shields.io/badge/Implemented-2ea44f?style=flat)](../.claude/settings.json) -A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.126, Claude Code exposes **60+ settings** and **175+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). +A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.138, Claude Code exposes **60+ settings** and **175+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). @@ -54,6 +54,15 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies > > **Note (v2.1.126):** `/config` now persists changes to `~/.claude/settings.json` instead of holding them in memory only. Edits made through the interactive Config UI survive restarts. +### Dynamic & Parent-Tier Policy (Managed Only) + +These keys live in the managed tier and shape how managed settings themselves are computed and merged. They do not appear in user, project, or local settings. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `parentSettingsBehavior` | string | `"first-wins"` | Controls how the SDK `managedSettings` parent tier merges with the local managed file. `"first-wins"` keeps the existing precedence — the first non-empty managed source provides all values. `"merge"` deep-merges the parent tier on top of the local managed file so admins can layer org-wide policy on a managed base (v2.1.133) | +| `policyHelper` | object | - | Managed executable that computes managed settings dynamically at runtime. Object fields: `path` (string — absolute path to the helper binary), `timeoutMs` (number — abort the helper after this many ms), `refreshIntervalMs` (number — re-run the helper after this many ms to refresh policy). Output is parsed as JSON and treated as if it were the contents of `managed-settings.json`. Use to compute org policy from external systems (LDAP groups, asset DB, etc.) without redeploying static files (v2.1.136) | + **Important**: - `deny` rules have highest safety precedence and cannot be overridden by lower-priority allow/ask rules. - Managed settings may lock or override local behavior even if local files specify different values. @@ -87,6 +96,7 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies > | `disableDeepLinkRegistration` | string | - | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt via `claude-cli://open?q=...`. The `q` parameter supports multi-line prompts using URL-encoded newlines (`%0A`). Useful in environments where protocol handler registration is restricted or managed separately | | `showThinkingSummaries` | boolean | `false` | Show extended thinking summaries in interactive sessions. When unset or `false` (default in interactive mode), thinking blocks are redacted by the API and shown as a collapsed stub. Redaction only changes what you see, not what the model generates — to reduce thinking spend, lower the budget or disable thinking instead. Non-interactive mode (`-p`) and SDK callers always receive summaries regardless of this setting | | `disableSkillShellExecution` | boolean | `false` | Disable inline shell execution for `` !`...` `` and `` ```! `` blocks in skills and custom commands from user, project, plugin, or additional-directory sources. Commands are replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected (v2.1.91) | +| `skillOverrides` | string | - | Control automatic skill invocation behavior. Values: `"off"` (skills are not invoked at all), `"user-invocable-only"` (only skills the user explicitly invokes via `/skill-name` run; auto-discovery via skill descriptions is disabled), `"name-only"` (skills are matched by exact name only; description-based auto-discovery is disabled). Use to keep a tighter rein on which skills the model loads or runs (v2.1.129) | | `forceRemoteSettingsRefresh` | boolean | `false` | **(Managed only)** Block CLI startup until remote managed settings are freshly fetched. If the fetch fails, the CLI exits (fail-closed). Use in enterprise environments where policy enforcement must be up-to-date before any session begins (v2.1.92) | | `wslInheritsWindowsSettings` | boolean | `false` | **(Windows managed settings only)** When `true`, Claude Code on WSL reads managed settings from the Windows policy chain (HKLM registry + `C:\Program Files\ClaudeCode\managed-settings.json`) in addition to `/etc/claude-code`, with Windows sources taking priority. Only honored when set in the HKLM registry key or `C:\Program Files\ClaudeCode\managed-settings.json`, both of which require Windows admin to write. For HKCU policy to also apply on WSL, the flag must additionally be set in HKCU itself. Has no effect on native Windows (v2.1.118) | | `tui` | string | `"default"` | Rendering mode: `"fullscreen"` or `"default"`. Set via `/tui fullscreen` for flicker-free alt-screen rendering (v2.1.110) | @@ -131,6 +141,7 @@ Configure how `--worktree` creates and manages git worktrees. Useful for reducin |-----|------|---------|-------------| | `worktree.symlinkDirectories` | array | `[]` | Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk | | `worktree.sparsePaths` | array | `[]` | Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk | +| `worktree.baseRef` | string | `"fresh"` | Branch source for new worktrees: `"fresh"` creates the worktree from a fresh fetch of the main branch HEAD; `"head"` branches from the current HEAD of the calling repository. Use `"head"` when you want the worktree to inherit your in-progress work (v2.1.133) | **Example:** ```json @@ -236,7 +247,7 @@ Control what tools and operations Claude can perform. | `permissions.disableBypassPermissionsMode` | string | Prevent bypass mode activation | | `permissions.skipDangerousModePermissionPrompt` | boolean | Skip the confirmation prompt shown before entering bypass permissions mode via `--dangerously-skip-permissions` or `defaultMode: "bypassPermissions"`. Ignored when set in project settings (`.claude/settings.json`) to prevent untrusted repositories from auto-bypassing the prompt | | `allowManagedPermissionRulesOnly` | boolean | **(Managed only)** Only managed permission rules apply; user/project `allow`, `ask`, `deny` rules are ignored | -| `autoMode` | object | Customize what the [auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment` (trusted infrastructure descriptions), `allow` (exceptions to block rules), and `soft_deny` (block rules) — all arrays of prose strings. **Not read from shared project settings** (`.claude/settings.json`) to prevent repo injection. Available in user, local, and managed settings. Setting `allow` or `soft_deny` **replaces** the entire default list for that section unless you include the literal string `"$defaults"` in the array — the sentinel inherits the built-in rules at that position so custom entries are added alongside them (v2.1.118). Run `claude auto-mode defaults` to see built-in rules before customizing | +| `autoMode` | object | Customize what the [auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment` (trusted infrastructure descriptions), `allow` (exceptions to block rules), `soft_deny` (block rules), and `hard_deny` (unconditional block rules — sibling to `soft_deny` but cannot be overridden by `allow` exceptions or the `"$defaults"` sentinel; v2.1.136) — all arrays of prose strings. **Not read from shared project settings** (`.claude/settings.json`) to prevent repo injection. Available in user, local, and managed settings. Setting `allow`, `soft_deny`, or `hard_deny` **replaces** the entire default list for that section unless you include the literal string `"$defaults"` in the array — the sentinel inherits the built-in rules at that position so custom entries are added alongside them (v2.1.118). Run `claude auto-mode defaults` to see built-in rules before customizing | | `disableAutoMode` | string | Set to `"disable"` to prevent [auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode) from being activated. Removes `auto` from the `Shift+Tab` cycle and rejects `--permission-mode auto` at startup. Can be set at any settings level; most useful in managed settings where users cannot override it | | `useAutoModeDuringPlan` | boolean | Whether plan mode uses auto mode semantics when auto mode is available. Default: `true`. Not read from shared project settings (`.claude/settings.json`). Appears in `/config` as "Use auto mode during plan" | @@ -418,6 +429,8 @@ Configure bash command sandboxing for security. | `sandbox.filesystem.allowRead` | array | `[]` | Paths to re-allow read access within `denyRead` regions. Takes precedence over `denyRead`. Arrays are merged across all settings scopes. Same path prefix conventions as `allowWrite` | | `sandbox.filesystem.allowManagedReadPathsOnly` | boolean | `false` | **(Managed only)** Only `allowRead` paths from managed settings are respected. `allowRead` entries from user, project, and local settings are ignored | | `sandbox.enableWeakerNetworkIsolation` | boolean | `false` | (macOS only) Allow access to system TLS trust (`com.apple.trustd.agent`); reduces security | +| `sandbox.bwrapPath` | string | - | **(Linux/WSL managed-only)** Custom path to the `bwrap` (bubblewrap) binary used to create the sandbox. Use when `bwrap` is installed at a non-standard location or shipped via a managed image. Honored only from managed settings (v2.1.133) | +| `sandbox.socatPath` | string | - | **(Linux/WSL managed-only)** Custom path to the `socat` binary used by the sandbox network proxy. Use when `socat` is installed at a non-standard location or shipped via a managed image. Honored only from managed settings (v2.1.133) | **Example:** ```json @@ -803,6 +816,7 @@ Set environment variables for all Claude Code sessions. | `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | Customize the Haiku entry description in the `/model` picker. Defaults to `Custom model ()` | | `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | Override capability detection for a pinned Haiku model. Comma-separated values (e.g., `effort,thinking`). Required when the pinned model supports features the auto-detection cannot confirm | | `CLAUDECODE` | Set to `1` in shell environments Claude Code spawns (Bash tool, tmux sessions). Not set in hooks or status line commands. Use to detect when a script is running inside a Claude Code shell | +| `CLAUDE_CODE_SESSION_ID` | Read-only. Set automatically in the Bash subprocess environment to the current Claude Code session's ID. Use from a Bash command, hook, or skill helper to correlate logs, metrics, or telemetry with a specific session without parsing the transcript path (v2.1.132) | | `AI_AGENT` | Set automatically by Claude Code in subprocess environments (Bash tool, hooks, MCP stdio servers). Generic flag identifying the parent process as an AI agent — useful for tools that adapt behavior when invoked from any AI agent rather than checking each agent-specific variable like `CLAUDECODE` *(in v2.1.120 changelog, not yet on official env-vars page)* | | `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | Set to `1` to allow fast mode when the organization status check fails due to a network error. Useful when a corporate proxy blocks the status endpoint | | `CLAUDE_CODE_USE_BEDROCK` | Use AWS Bedrock (`1` to enable) | @@ -936,8 +950,13 @@ Set environment variables for all Claude Code sessions. | `CLAUDE_CODE_NO_FLICKER` | Set to `1` to enable flicker-free alt-screen rendering. Eliminates visual flicker during fullscreen redraws (v2.1.88) | | `CLAUDE_CODE_SCROLL_SPEED` | Mouse wheel scroll multiplier for fullscreen rendering. Increase for faster scrolling, decrease for finer control | | `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Set to `1` to disable virtual scrolling in fullscreen rendering and render every message in the transcript. Use if scrolling in fullscreen mode shows blank regions where messages should appear | +| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Set to `1` to opt out of the alternate-screen (fullscreen) renderer entirely and use the classic scrollback renderer. Useful when terminal multiplexers, recording tools, or accessibility tooling do not handle the alt-screen buffer cleanly (v2.1.132) | | `CLAUDE_CODE_DISABLE_MOUSE` | Set to `1` to disable mouse tracking in fullscreen rendering. Useful when mouse events interfere with terminal multiplexers or accessibility tools | | `CLAUDE_CODE_HIDE_CWD` | Set to `1` to hide the current working directory in the Claude Code startup logo banner. Useful in screen recordings, demos, or shared sessions where the CWD path leaks information about the host or project layout (v2.1.119) | +| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Set to `1` to force synchronous output flushing for Claude Code's writes to the terminal. Defaults to async/buffered output for performance. Use as a debugging aid when terminal output appears interleaved or out-of-order with subprocess output (v2.1.129) | +| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | Control background package-manager-based auto-update checking for Claude Code. Set to `0` to disable the background check (Claude Code will not poll the package manager for newer versions); set to `1` (default) to keep the background check enabled. Independent of `DISABLE_AUTOUPDATER`, which gates the npm-registry auto-updater (v2.1.129) | +| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Set to `1` to opt into fetching the available-models list from the configured LLM gateway (e.g., a corporate proxy in front of Bedrock/Vertex). When enabled, the `/model` picker is populated from the gateway's discovery endpoint instead of the built-in alias list. Use when your gateway exposes a curated subset of models the user should choose from (v2.1.129) | +| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | Set to `1` to re-enable the in-session quality survey for OpenTelemetry-enabled enterprises. The survey is suppressed by default when `OTEL_*` env vars or `feedbackSurveyRate` are configured to avoid leaking survey traffic into enterprise telemetry pipelines. Use when admins want sampled survey data despite an OTel deployment (v2.1.136) | | `CLAUDE_CODE_ACCESSIBILITY` | Set to `1` to keep native terminal cursor visible for screen readers and accessibility tools | | `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Set to `0` to disable syntax highlighting in diff output | | `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip automatic IDE extension installation (`1` to skip) |