What this read moved
1–6 of 6changelog Changed · +69 / -0 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 6
66
77Run `claude --version` to check your installed version.
88
9<Update label="2.1.260" description="September 3, 2026">
10 * Added a diff panel that opens beside the conversation in fullscreen mode and shows your uncommitted changes as Claude edits; toggle it with `/diff`
11 * Added a likely cause for prompt-cache misses (e.g. tool definitions or system prompt changed, idle past the TTL) to `/cost` and the status line's `prompt_cache` field
12 * Added `/reload-plugins` to headless sessions, so it appears in the Claude Code Desktop and SDK command lists
13 * Added a text form of `/advisor` (`/advisor`, `/advisor <model>`, `/advisor off`) for the desktop app, Remote Control, and other headless (`-p`/Agent SDK) sessions
14 * Added `oidc.scope_on_refresh` to the Claude apps gateway for IdPs that return an id\_token on refresh only when asked for `openid` again
15 * Added Claude apps gateway support for newer Claude Desktop keys in `desktop` policy blocks, including `userPluginMarketplacesEnabled` and `userPluginUploadsEnabled`
16 * Fixed `Edit`/`Write`/`Read` permission rules whose path contains parentheses being dropped as invalid or ignored by the Bash sandbox, which left "read-only" folders writable
17 * Fixed one file permission rule with an uncompilable pattern (e.g. an unclosed `[`) making every file edit fail with `Invalid regular expression`; such a deny rule now guards the literal path it spells
18 * Fixed Bash permission checks auto-approving zsh commands that hide a command substitution in a REPORTTIME, REPORTMEMORY or DIRSTACKSIZE assignment; these now prompt for approval
19 * Fixed Bedrock model discovery, token counting and AWS SSO/STS credential calls failing with "unable to get local issuer certificate" when the corporate root CA is only in the OS certificate store
20 * Fixed `permissions.blockReadsOutsideWorkingDirectories` on macOS hiding the user's git config from sandboxed git and hiding a worktree-isolated sub-agent's own checkout
21 * Fixed managed settings not loading for claude.ai Enterprise/Team users who also had a leftover API key from an earlier `/login`
22 * Fixed `/status` listing a signed-in claude.ai account and a configured API key as if both were in effect; the credential not in use is now marked
23 * Fixed managed `skillOverrides` entries keyed on a bundled skill's alias (e.g. `checkup` for `/doctor`) not applying, and `Skill(name)` deny rules not covering a nested skill listed as `<dir>:name`
24 * Fixed `model: fable` agents ignoring the `[1m]` tag on an `ANTHROPIC_DEFAULT_FABLE_MODEL` pin and silently running with a 200K context window
25 * Fixed the `/model` picker not showing Fable 5.1 for organizations that can use it, which was only accepted when typed as `/model claude-fable-5-1`
26 * Fixed prompt caching on Claude Fable 5.1 not covering the context attached after tool results, so it was re-sent as uncached input on every tool-call turn
27 * Fixed model switching staying blocked for the rest of the session after a plugin hook load failure; each switch now re-checks and the refusal names the cause
28 * Fixed model switching being blocked for the session when an organization-managed plugin's marketplace could not be loaded
29 * Fixed SDK-provided MCP servers (e.g. Desktop connectors) sometimes missing from the first turn and only appearing on the next one
30 * Fixed Claude in Chrome tools failing with "Not connected" mid-task in cloud-hosted claude.ai sessions when a connector was added or removed
31 * Fixed flags, joined emoji and accented letters splitting across wrapped lines, and stale text staying on screen when a flag or joined emoji falls in the terminal's last two columns (now shown as `…`)
32 * Fixed Remote Control accepting a model pick that is not a valid model name; it is now refused with an error instead of failing on the next message
33 * Fixed `/rewind` and `--rewind-files` reporting success when checkpoint backup files were missing and nothing was actually restored
34 * Fixed `/rewind` leaving stale file-read tracking from the rewound-away turns, which caused "File unchanged since last read" stubs and full-file re-injection after external edits
35 * Fixed `-p --resume`/`--continue` (as used by the desktop app) failing on every retry once a session's worktree directory lost its git metadata; it now fails once, then resumes without the worktree
36 * Fixed a subagent that resumed another agent via SendMessage never being woken by that agent's completion (the notification went to the main conversation instead)
37 * Fixed agent teams: an in-process teammate's transcript losing messages, or going blank, during long API retry waits (e.g. under `CLAUDE_CODE_RETRY_WATCHDOG`) as retry notices evicted real messages
38 * Fixed a session that moved to the background appearing twice in ListAgents (once as a phantom "interactive" twin with the same name) and receiving SendMessage deliveries in the viewer
39 * Fixed intermittent "task output swap refused" errors when many sessions share a project directory
40 * Fixed Ctrl+Z in fullscreen leaving the shell on the alternate screen, drawn over the paused interface
41 * Fixed Workflow tool subagents being restarted as stalled while a long context compaction was still in progress
42 * Fixed plugins from a URL marketplace failing to install with "marketplace entry path does not stay inside the marketplace directory" when a host app (e.g. Claude Desktop) stores it as a directory
43 * Fixed an extra browser tab opening when an artifact is published in a session you're driving from claude.ai, the desktop app, or mobile (Remote Control)
44 * Fixed the Artifact tool's first call failing with an "Invalid tool parameters" validation error in some Cowork sessions
45 * Fixed IDE line selections being dropped when running a skill or slash command (the "N lines selected" context now reaches Claude)
46 * Fixed repository detection for GitLab projects in nested subgroups (e.g. `gitlab.com/group/subgroup/project`)
47 * Fixed `owner/repo#123` issue references in rendered output linking to github.com when working in a GitLab repository; they now link to the gitlab.com issue
48 * Glob/Grep: Fixed the search path being probed on disk before the permission check; a missing path is now reported after permission is decided, as Read does
49 * Reverted the 2.1.259 change applying `Read()` deny rules to Bash arguments; it denied `npm run build` under a `Read(./**/build/**)` rule in every mode and made `cd … && grep` prompt even in auto mode
50 * Improved structured output: Workflow `agent({schema})` rejects a JSON Schema that can never be satisfied up front, and retry-cap errors now include the last validation failure
51 * Improved deleting a background session whose worktree has unpushed commits: the message now names the branch and commit count, and deleting again discards the worktree
52 * Improved the Claude apps gateway's refresh-failure log to name the step that failed
53 * Improved idle CPU usage of non-interactive (`-p` / SDK) sessions
54 * Improved the Claude apps gateway on Amazon Bedrock: input tokens for an aborted request are now counted with AWS's free CountTokens API (grant `bedrock:CountTokens`) instead of a one-token request
55 * Improved the settings error for rules such as `Edit(C:\dir\(name)\**)`, where `\(` is read as an escaped parenthesis rather than a path separator, to suggest an unambiguous spelling
56 * Improved auto-compact for 1M-context models: Opus and Fable sessions now compact shortly before the 1M-token limit, and recovery compaction on very large contexts no longer times out at 10 minutes
57 * Improved `/ultrareview` and `claude ultrareview` to wait up to 45 minutes (previously 30) for long-running cloud reviews
58 * Improved `/effort` on Claude Fable 5.1 so changing effort mid-session no longer invalidates the prompt cache
59 * Updated the bundled `claude-api` skill so its Go, Java, and C# samples use current-generation model IDs, and clarified that cheaper worker or sub-agent models should be current-generation too
60 * Changed `ctrl+l` / `cmd+k` in fullscreen mode to clear the transcript view like a terminal `clear`; scroll up to see earlier messages
61 * Changed permission rules with text after the closing parenthesis (e.g. `Bash(ls) x`), which never matched anything, to be reported as invalid settings instead of being silently ignored
62 * Changed server-managed settings so a managed CLAUDE.md (`claudeMd`) no longer triggers the security approval dialog; hooks, shell-command, sandbox, and unsafe `env` settings still require approval
63 * Changed Claude in Chrome to follow your organization's Claude in Chrome admin setting; when an admin turns it off, `--chrome`, `/chrome` and the browser tools are unavailable
64 * Changed Claude apps gateway to send `orgPluginSettings` in the list form read by Claude Desktop 1.15200.0 and later; older desktops ignore it
65 * Changed Claude apps gateway to also refuse to start, naming the field, when a `desktop` policy misspells a field in a nested object of a `managedMcpServers` or `orgPluginSettings` entry
66 * Changed commands typed at the `!` bash-mode prompt to run outside the sandbox even when strict sandbox mode (`sandbox.allowUnsandboxedCommands: false`) is on, like typing into your own terminal
67 * Changed self-hosted runner `--kill-session-after-min` to release a session that is only waiting on its user (paused, resumable on the next message) instead of killing it and reporting a failure
68 * Removed the one-hour time limit on background commands started by subagents; they now run until they exit or are stopped, matching the main session
69 * \[VSCode] Added the selected effort level to the footer model pill, fixed a stale effort level after switching models, and returned the footer pills to their earlier compact size
70 * \[VSCode] Added Open and Closed to the session list's status filter menu
71 * \[VSCode] Fixed the welcome screen disappearing in a new session when Remote Control turns on automatically
72 * \[VSCode] Fixed the session history picker loading a session a second time when it is already open in another tab; it now switches to that tab
73 * \[VSCode] Fixed the session tab's Rename command silently doing nothing while the tab's view was reloading; it now always applies
74 * \[VSCode] Fixed a half-finished message, an empty tool card or an extra "Thought for" line staying on screen after Claude Code retried a dropped response
75 * \[VSCode] Fixed "Enable Remote Control for all sessions" not applying to a session tab that was still starting when the toggle was flipped
76</Update>
77
978<Update label="2.1.259" description="September 2, 2026">
1079 * Added `managedMcpServers` managed setting: organizations can provide HTTP/SSE MCP servers to every user (same entry shape as `.mcp.json`); entries that name a command to run are skipped
1180 * Added `--permission-prompts none` for unattended headless hosts: anything that would prompt is denied automatically while the active permission mode (including auto mode) keeps deciding
from line 2001
19322001<Update label="2.1.169" description="June 8, 2026">
19332002 * Added `--safe-mode` flag (and `CLAUDE_CODE_SAFE_MODE`) to start Claude Code with all customizations (CLAUDE.md, plugins, skills, hooks, MCP servers) disabled for troubleshooting
19342003 * Added `/cd` command to move a session to a new working directory without breaking the prompt cache mid-session
1935 * Added a `disableBundledSkills` setting and `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` environment variable to hide bundled skills, workflows, and built-in slash commands from the model
1936 * Fixed Up/Down arrows jumping to command history past the wrapped rows of a long input line — they now move through each visual row first, and history recall enters at the near edge
1937 * Fixed enterprise managed MCP policies (`allowedMcpServers`/`deniedMcpServers`) not being enforced on reconnect, IDE-typed configs, `--mcp-config` servers during the first session after install, or before remote settings loaded; also fixed slow cold starts for orgs without remote settings
1938 * Fixed a \~30-50ms UI stall at the start of each turn for macOS users logged in with claude.ai credentials
1939 * Fixed `claude -p` being slow or appearing to hang on Windows while waiting for the slash-command/skill scan (regression in 2.1.161)
1940 * Fixed Remote Control getting stuck on "reconnecting" after resuming a session when an OAuth token refresh happened at the same time
1941 * Fixed Git Credential Manager's "Connect to GitHub" popup appearing on Windows at startup when background git commands ran without cached credentials
1942 * Fixed footer hints (e.g. "esc to interrupt") not showing for users with a custom statusline
1943 * Fixed stale permission and dialog prompts reappearing every time you reattached to a remote session whose worker had died while waiting on them
1944 * Fixed `claude agents --json` omitting blocked and just-dispatched background sessions; added `--all` to include completed sessions, plus new `id` and `state` fields
1945 * Fixed agents view leaving a stale/garbled frame after navigating back from an agent on WSL in Windows Terminal
1946 * Fixed background agents ignoring project-level settings `env` values (e.g. `ANTHROPIC_MODEL`) when dispatched onto a pre-warmed worker
1947 * Fixed MCPB plugin cache being spuriously invalidated on Windows, causing unnecessary re-extraction
1948 * Fixed plugin `.in_use` PID lock files accumulating without bound; stale markers from crashed sessions are now swept once per day
1949 * Fixed untrusted project settings being able to set OTEL client-certificate paths without trust confirmation
1950 * `/workflows` now opens immediately even while a turn is in progress
1951 * Improved `TaskCreate` reliability: malformed inputs are repaired automatically and validation errors for unloaded tools include the schema
1952 * Improved the error message shown when your organization has disabled API key authentication, with guidance based on where the active API key comes from
1953 * Reduced CPU usage while responses stream and during spinner animations
1954 * Restored a default 5-minute idle timeout on Vertex/Foundry so a stalled stream aborts instead of hanging indefinitely; set `API_FORCE_IDLE_TIMEOUT=0` to opt out
1955 * Remote-managed settings with an invalid entry now apply their remaining valid policies and surface the validation error, instead of silently dropping the whole payload
1956 * Background sessions now preserve `--ide`, `--chrome`, `--bare`, `--remote-control`, and other flags across retire→wake, and respawn state validation was hardened
1957 * Background sessions are now told that shared-checkout edits are blocked until they enter a worktree, avoiding a wasted rejected edit before `EnterWorktree`
1958 * The "CLAUDE.md is too long" warning threshold now scales with the model's context window
1959 * Auto-updater on Windows now stops retrying within a session once `claude.exe` is held by another process
1960 * Improved color contrast for skill tags in the slash-command menu
1961 * Promo credit claims for Apple/Google-billed subscribers without a payment method now explain where to add one
1962 * Added a tip suggesting `claude agents` when running multiple concurrent sessions
1963</Update>
1964
1965<Update label="2.1.168" description="June 6, 2026">
1966 * Bug fixes and reliability improvements
1967</Update>
1968
1969<Update label="2.1.167" description="June 6, 2026">
1970 * Bug fixes and reliability improvements
1971</Update>
1972
1973<Update label="2.1.166" description="June 6, 2026">
1974 * Added `fallbackModel` setting to configure up to three fallback models tried in order when the primary model is overloaded or unavailable; `--fallback-model` now also applies to interactive sessions
1975 * Added glob pattern support in deny rule tool-name position (`"*"` denies all tools); allow rules reject non-MCP globs, and unknown tool names in deny rules warn at startup
1976 * Hardened cross-session messaging: messages relayed via `SendMessage` from other Claude sessions no longer carry user authority — receivers refuse relayed permission requests, and auto mode blocks them
1977 * `MAX_THINKING_TOKENS=0`, `--thinking disabled`, and the per-model thinking toggle now disable thinking on models that think by default via the Claude API (3P providers unchanged)
1978 * Claude Code now retries a turn once on the fallback model when the API rejects an unexpected non-retryable error; auth, rate-limit, request-size, and transport errors still surface immediately
1979 * `claude update` now announces the target version before downloading instead of going silent
1980 * `claude agents`: typing a URL into the list now filters to the session whose first prompt contained it
1981 * Fixed a recurring "image could not be processed" error and extra token usage when an unprocessable image was sent in a session
1982 * Fixed remote sessions becoming permanently stuck when a brief backend disruption occurred during worker registration at startup
1983 * Fixed flickering in JetBrains IDE terminals (IntelliJ, PyCharm, WebStorm, etc.) on 2026.1+ by enabling synchronized output
1984 * Fixed Shift+non-ASCII characters (e.g. Shift+ä → Ä) being dropped in terminals using the Kitty keyboard protocol (WezTerm, Ghostty, kitty)
1985 * Fixed PowerShell command validation occasionally hanging far past its time budget on Windows when a killed process's children held its output pipes
1986 * Fixed orphaned `claude --bg-pty-host` processes spinning at 100% CPU after the daemon dies while connected on macOS
1987 * Fixed voice mode requiring `/login` to clear a stale auth check after toggling `/voice`
1988 * Fixed managed settings with an invalid entry silently disabling enforcement of their remaining valid policies
1989 * Fixed managed-settings `allowedMcpServers`/`deniedMcpServers` predicates not matching when they use `${VAR}` references
1990 * Fixed background agent sessions that entered a git worktree crash-looping with "No conversation found" when reopened from `claude agents`
1991 * Fixed duplicated thinking text in the Ctrl+O transcript view while streaming
1992 * Fixed `/doctor` showing a contradictory failed "Not inside a remote session" check when run inside a remote session
1993 * Fixed the cursor sticking at the end of the first line when typing a multiline prompt in the `claude agents` dispatch and reply inputs
1994 * Fixed blank lines appearing between background agent rows in the task list on terminals without Unicode support
1995</Update>
1996
1997<Update label="2.1.165" description="June 5, 2026">
1998 * Bug fixes and reliability improvements
1999</Update>
2000
2001<Update label="2.1.163" description="June 4, 2026">
2002 * Added `requiredMinimumVersion` and `requiredMaximumVersion` managed settings — Claude Code refuses to start if its version is outside the allowed range and directs the user to an approved version
2003 * Added `/plugin list` command to list installed plugins, with `--enabled`/`--disabled` filters
2004 * Added a "c to copy" shortcut to `/btw` that copies the raw markdown answer to the clipboard, preserving formatting when pasted elsewhere
2005 * Hooks: Stop and SubagentStop hooks can now return `hookSpecificOutput.additionalContext` to give Claude feedback and keep the turn going without being labeled a hook error
2006 * Skills: added `\$` escape syntax to include a literal `$` before a digit in command bodies
2007 * stdio MCP servers now receive the same `CLAUDE_CODE_SESSION_ID` as hooks/Bash on `--resume`
2008 * Fixed `claude -p` hanging forever after its final result when a backgrounded command never exits — background shells are now stopped \~5s after the result once stdin closes
2009 * Fixed `claude -p` failing with "ANTHROPIC\_API\_KEY required" on Bedrock/Vertex/Foundry when `CI=true` and no Anthropic API key is set
2010 * Fixed bash commands failing under bazel and EDR-protected Go workflows: `$TMPDIR` was overridden to `/tmp/claude-{uid}` for all commands instead of only sandboxed ones (regression in 2.1.154)
2011 * Fixed Bash commands failing on Windows with "EEXIST: file already exists" on the session-env directory when it has the read-only attribute or is inside OneDrive
2012 * Fixed org-managed permission rules not applying for the entire session when the managed settings fetch completed during startup on a fresh config directory
2013 * Fixed background sessions in `claude agents` losing their running background tasks when reattached after a Claude Code update
2014 * Fixed terminal misalignment and a multi-second hang when exiting the agent view by pressing Esc
2015 * Fixed clicking Stop on a background-task chip in the desktop app not clearing the chip when the underlying process was already gone
2016 * Fixed keyboard input becoming permanently unresponsive after a paste operation whose end marker is dropped by the terminal
2017 * Fixed hook `if: "Bash(...)"` conditions firing on every Bash command containing `$()` or `$VAR`; the pattern now matches against commands inside subshells and backticks too
2018 * Fixed deny rules on home-directory paths (e.g. `Read(~/Desktop/**)`) not blocking Bash commands that reference the path via `$HOME`
2019 * Fixed a stray "(no content)" line left in the transcript after closing panel dialogs like /mcp and /plugins
2020 * Background agent sessions now update to a new Claude Code version in the background, so opening a session after an update no longer waits on a cold restart
2021 * Clearer descriptions for built-in commands and skills in the / menu
2022 * The subscription-switch suggestion now shows in the startup announcement slot instead of a toast
2023 * `claude agents` dispatching from the state-grouped view now starts the session in the directory the agent view was opened from
2024</Update>
2025
2026<Update label="2.1.162" description="June 3, 2026">
2027 * `claude agents --json` now includes `waitingFor` showing what a waiting session is blocked on (e.g. permission prompt)
2028 * `--tools`: explicitly listing Grep/Glob now provides the dedicated search tools on native builds with embedded search (previously these names were silently ignored)
2029 * `/effort` now confirms whe
2004 * Added a `disableBundledSkills` setting and `CL
errors Changed · +31 / -0 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 215
215215| `Agent descriptions are over the 15.0k-token limit` | [Configuration warnings](#agent-descriptions-are-over-the-15000-token-limit) |
216216| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |
217217| `Remote managed settings failed to load (<cause>)` | [Configuration warnings](#remote-managed-settings-failed-to-load) |
218| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |
219| `Managed settings drop-in directory could not be read` | [Configuration warnings](#managed-settings-document-could-not-be-parsed) |
218220| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [Configuration warnings](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |
219221| `headersHelper not run — this workspace has no persisted trust` | [Configuration warnings](#headershelper-not-run) |
220222| `... is not matched by file permission checks` | [Configuration warnings](#is-not-matched-by-file-permission-checks) |
from line 2370
23682370* `Couldn't read your Zed keymap, so it was left unchanged.`: Claude Code couldn't read the file, for example because of file permissions
23692371* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: the file read fine but doesn't parse as an array of keybinding blocks, even with `//` comments and trailing commas allowed
23702372* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code couldn't copy the file to a `.bak` backup beside it, so it changed nothing
2371* `Couldn't update your Zed keymap, so it was left unchanged.`: the merged result didn't verify as a valid keymap carrying the binding, so Claude Code discarded it instead of writing. A keybinding block with a duplicated key can cause this
2372
2373**What to do:**
2374
2375* Copy the block from the message into the top-level array in your `keymap.json` at the path the message names
2376* For `isn't a readable list of keybindings`, fix the syntax error, or make the file's top-level value an array, then run `/terminal-setup` again
2377
2378Before v2.1.247, `/terminal-setup` couldn't parse a Zed keymap that used `//` comments or trailing commas, and it replaced the entire file with only its own binding while reportin
2373* `Couldn't update your Zed keymap,
hooks Changed · +4 / -2 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 1827
18271827
18281828#### PermissionRequest input
18291829
1830PermissionRequest hooks receive `tool_name` and `tool_input` fields like PreToolUse hooks, but without `tool_use_id`. An optional `permission_suggestions` array contains the "always allow" options the user would normally see in the permission dialog.
1830PermissionRequest hooks receive `tool_name` and `tool_input` fields like PreToolUse hooks, but without `tool_use_id`. An optional `permission_suggestions` array contains the [permission updates](#permission-update-entries) Claude Code suggests for this request, such as adding an allow rule or changing the permission mode.
18311831
1832The permission dialog builds its "always allow" options from these suggestions, but the array isn't an exact list of the options you see. The dialog can withhold an option whose suggestion stays in the array, for example when [`allowManagedPermissionRulesOnly`](/docs/en/settings-reference#allowmanagedpermissionrulesonly) hides rule-saving options. It can also offer options that have no suggestion entry, such as [**Yes, and switch to auto mode**](/docs/en/permission-modes#switch-permission-modes), which changes the permission mode directly rather than through a permission update.
1833
18321834PreToolUse hooks run before every tool call, whether or not it needs permission. PermissionRequest hooks run only when Claude Code is about to ask you for permission, or when it would otherwise auto-deny a call that can't prompt. Neither event fires for [`EndConversation`](/docs/en/tools-reference#endconversation-tool-behavior).
18331835
18341836```json theme={null}
from line 1912
19101912| `projectSettings` | `.claude/settings.json` |
19111913| `userSettings` | `~/.claude/settings.json` |
19121914
1913A hook can echo one of the `permission_suggestions` it received as its own `updatedPermissions` output, which is equivalent to the user selecting that "always allow" option in the dialog.
1915A hook can echo one of the `permission_suggestions` it received as its own `updatedPermissions` output.
19141916
19151917### PostToolUse
19161918
from line 2813
28112813}
28122814```
28132815
2814The hook reads the changed file's absolute path from the `file_path` field of the [JSON input](#filechanged-input) on stdin. Its `grep` guard tests for the same thing `perl` removes, a CR at the end of a line, so the run after a normalization exits without touching the file. A looser guard loops forever, because `perl -i` rewrites the file even when it substitutes nothing and Claude Code runs the hook again after every rewrite. Save this script at `/path/to/normalize-line-endings.sh` and make it executable:
2815
2816```bash theme={null}
2817#!/bin/bash
2818FILE=$(jq -r .file_path)
2819if grep -q $'\r$' "$FILE"; then
2820 perl -pi -e 's/\r$//' "$FILE"
2821fi
2822```
2823
2824To confirm the hook works, ask Claude to append a CRLF line to `data.csv` with a `Bash` command. Claude Code r
2816The hook reads the changed file's absolute path from the `file_path` field of the [JSON input](#filechanged-input) on stdin. Its `grep` guard tests for the same thing `perl` remo
managed-settings Changed · +20 / -4 lines
from line 268
268268
269269When the policy isn't applying, the `Setting sources` line tells you which of two problems you have:
270270
271* **The line is missing**: Claude Code found no managed source that delivers a policy key. If you deployed a managed settings file, check that it sits at the path for the OS, that it's valid JSON, and that it contains a [policy key](#how-claude-code-combines-managed-sources) rather than only the control keys.
271* **The line is missing**: Claude Code found no managed source that delivers a policy key.
272272
273 If you deployed a managed settings file, check that it sits at the path for the OS and that it contains a [policy key](#how-claude-code-combines-managed-sources) rather than only the control keys. A file that isn't valid JSON doesn't produce this state; Claude Code [refuses to start](#find-entries-claude-code-dropped) instead.
274
273275 When you deployed through server-managed settings instead, run `claude doctor`, which reports the [fetch outcome](/docs/en/server-managed-settings#verify-settings-delivery).
274276* **The line names a source other than the one you deployed**: a higher-priority source is present and Claude Code ignored yours, and `Skipped sources` lists it. [How Claude Code combines managed sources](#how-claude-code-combines-managed-sources) gives the order.
275277
from line 279
277279
278280### Find entries Claude Code dropped
279281
280When a managed settings file, MDM profile, registry value, or server-managed payload fails schema validation, Claude Code first skips the individual entries it can repair, such as one invalid permission rule, with a warning for each, then drops any top-level key whose value still fails and keeps enforcing every remaining valid key. Claude Code is stricter with the `managedSettings` a [`policyHelper`](/docs/en/settings-reference#policyhelper) emits: it makes the same entry repairs, but any schema violation that survives fails the whole helper run, and at startup Claude Code refuses to start, the same as for a helper that exits non-zero. A managed settings file or drop-in file that isn't valid JSON contributes no settings at all; Claude Code reports it with the other validation errors and reads the remaining sources as usual.
282When a managed settings file, MDM profile, registry value, or server-managed payload fails schema validation, Claude Code first skips the individual entries it can repair, such as one invalid permission rule, with a warning for each, then drops any top-level key whose value still fails and keeps enforcing every remaining valid key.
281283
282If a managed settings file or drop-in file can't be read or parsed and no other admin source supplies a policy, sessions signed in with claude.ai or Claude Console credentials exit at startup with a message to contact an administrator.
284Claude Code is stricter with the `managedSettings` a [`policyHelper`](/docs/en/settings-reference#policyhelper) emits: it makes the same entry repairs, but any schema violation that survives fails the whole helper run, and at startup Claude Code refuses to start, the same as for a helper that exits non-zero.
285
286When a managed settings file, drop-in file, MDM plist, or HKLM registry value is present but can't be parsed as a JSON object, Claude Code refuses to start and prints [an error naming the source](/docs/en/errors#managed-settings-document-could-not-be-parsed), even when another admin source delivers a valid policy. Each source fails this way when:
287
288* **Managed settings file or drop-in file**: the file isn't valid JSON, or its top level isn't an object
289* **MDM plist**: macOS's `plutil` reports the plist malformed, or its converted content isn't a JSON object
290* **HKLM registry value**: the `Settings` value isn't a string, is empty, or doesn't hold a JSON object
291
292Three source states don't cause this refusal:
293
294* An absent file, profile, or registry value isn't a failure; Claude Code runs without that source.
295* An empty managed settings file counts as `{}`.
296* A malformed value in the user-writable HKCU registry key never blocks launch. Claude Code reports it as a notice in `/status` and `claude doctor` instead.
297
298If a managed settings file, drop-in file, or `managed-settings.d/` directory can't be read and no admin source supplies a policy, sessions signed in with claude.ai or Claude Console credentials exit at startup with a message to contact an administrator.
283299
284300To find a dropped entry, look in one of three places:
285301
monitoring-usage Changed · +1 / -1 lines
from line 1135
11351135
11361136Like every OTel event on this page, it goes only to the telemetry backend you configure. Requires Claude Code v2.1.227 or later.
11371137
1138When Claude Code can't safely determine the retention period, it pauses the sweep and emits the event with `result` set to `"skipped"` and a `skip_reason`. When [managed settings](/docs/en/server-managed-settings) set `cleanupPeriodDays`, the managed value pins the retention period and the sweep runs even when a settings file in a lower-priority scope is broken or invalid. When `managed-settings.json` itself can't be read or parsed, Claude Code still pauses the sweep unless the [managed tier](/docs/en/managed-settings#how-claude-code-combines-managed-sources) supplies `cleanupPeriodDays` from elsewhere, such as server-managed settings or a `managed-settings.d/` drop-in beside the broken file. The deletion counter attributes are present only when `result` is `"complete"`.
1138When Claude Code can't safely determine the retention period, it pauses the sweep and emits the event with `result` set to `"skipped"` and a `skip_reason`. When [managed settings](/docs/en/server-managed-settings) set `cleanupPeriodDays`, the managed value pins the retention period and the sweep runs even when a settings file in a lower-priority scope is broken or invalid. When `managed-settings.json` itself can't be read, Claude Code still pauses the sweep unless the [managed tier](/docs/en/managed-settings#how-claude-code-combines-managed-sources) supplies `cleanupPeriodDays` from elsewhere, such as server-managed settings or a `managed-settings.d/` drop-in beside the broken file. The deletion counter attributes are present only when `result` is `"complete"`.
11391139
11401140**Event Name**: `claude_code.retention_sweep`
11411141
server-managed-settings Changed · +1 / -1 lines
from line 180
180180
181181### Invalid entries in delivered settings
182182
183Delivered payloads parse tolerantly with the same rules as the other managed sources. When part of a payload fails schema validation, Claude Code surfaces a validation error and applies every remaining valid setting; [Invalid entries in managed settings](/docs/en/managed-settings#invalid-entries-in-managed-settings) says what it drops and which keys fall back to a stricter value. Requires Claude Code v2.1.169 or later.
183When part of a payload fails schema validation, Claude Code surfaces a validation error and applies every remaining valid setting; [Invalid entries in managed settings](/docs/en/managed-settings#invalid-entries-in-managed-settings) says what it drops and which keys fall back to a stricter value. Requires Claude Code v2.1.169 or later.
184184
185185Server-managed delivery adds these behaviors:
186186