chore: Update CHANGELOG.md

docs: add examples/settings

CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## 2.1.30
+
+- Added `pages` parameter to the Read tool for PDFs, allowing specific page ranges to be read (e.g., `pages: "1-5"`). Large PDFs (>10 pages) now return a lightweight reference when `@` mentioned instead of being inlined into context.
+- Added pre-configured OAuth client credentials for MCP servers that don't support Dynamic Client Registration (e.g., Slack). Use `--client-id` and `--client-secret` with `claude mcp add`.
+- Added `/debug` for Claude to help troubleshoot the current session
+- Added support for additional `git log` and `git show` flags in read-only mode (e.g., `--topo-order`, `--cherry-pick`, `--format`, `--raw`)
+- Added token count, tool uses, and duration metrics to Task tool results
+- Added reduced motion mode to the config
+- Fixed phantom "(no content)" text blocks appearing in API conversation history, reducing token waste and potential model confusion
+- Fixed prompt cache not correctly invalidating when tool descriptions or input schemas changed, only when tool names changed
+- Fixed 400 errors that could occur after running `/login` when the conversation contained thinking blocks
+- Fixed a hang when resuming sessions with corrupted transcript files containing `parentUuid` cycles
+- Fixed rate limit message showing incorrect "/upgrade" suggestion for Max 20x users when extra-usage is unavailable
+- Fixed permission dialogs stealing focus while actively typing
+- Fixed subagents not being able to access SDK-provided MCP tools because they were not synced to the shared application state
+- Fixed a regression where Windows users with a `.bashrc` file could not run bash commands
+- Improved memory usage for `--resume` (68% reduction for users with many sessions) by replacing the session index with lightweight stat-based loading and progressive enrichment
+- Improved `TaskStop` tool to display the stopped command/task description in the result line instead of a generic "Task stopped" message
+- Changed `/model` to execute immediately instead of being queued
+- [VSCode] Added multiline input support to the "Other" text input in question dialogs (use Shift+Enter for new lines)
+- [VSCode] Fixed duplicate sessions appearing in the session list when starting a new conversation
+
+## 2.1.29
+
+- Fixed startup performance issues when resuming sessions that have `saved_hook_context`
+
+## 2.1.27
+
+- Added tool call failures and denials to debug logs
+- Fixed context management validation error for gateway users, ensuring `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` avoids the error
+- Added `--from-pr` flag to resume sessions linked to a specific GitHub PR number or URL
+- Sessions are now automatically linked to PRs when created via `gh pr create`
+- Fixed /context command not displaying colored output
+- Fixed status bar duplicating background task indicator when PR status was shown
+- Windows: Fixed bash command execution failing for users with `.bashrc` files
+- Windows: Fixed console windows flashing when spawning child processes
+- VSCode: Fixed OAuth token expiration causing 401 errors after extended sessions
+
+## 2.1.25
+
+- Fixed beta header validation error for gateway users on Bedrock and Vertex, ensuring `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` avoids the error
+
+## 2.1.23
+
+- Added customizable spinner verbs setting (`spinnerVerbs`)
+- Fixed mTLS and proxy connectivity for users behind corporate proxies or using client certificates
+- Fixed per-user temp directory isolation to prevent permission conflicts on shared systems
+- Fixed a race condition that could cause 400 errors when prompt caching scope was enabled
+- Fixed pending async hooks not being cancelled when headless streaming sessions ended
+- Fixed tab completion not updating the input field when accepting a suggestion
+- Fixed ripgrep search timeouts silently returning empty results instead of reporting errors
+- Improved terminal rendering performance with optimized screen data layout
+- Changed Bash commands to show timeout duration alongside elapsed time
+- Changed merged pull requests to show a purple status indicator in the prompt footer
+- [IDE] Fixed model options displaying incorrect region strings for Bedrock users in headless mode
+
+## 2.1.22
+
+- Fixed structured outputs for non-interactive (-p) mode
+
+## 2.1.21
+
+- Added support for full-width (zenkaku) number input from Japanese IME in option selection prompts
+- Fixed shell completion cache files being truncated on exit
+- Fixed API errors when resuming sessions that were interrupted during tool execution
+- Fixed auto-compact triggering too early on models with large output token limits
+- Fixed task IDs potentially being reused after deletion
+- Fixed file search not working in VS Code extension on Windows
+- Improved read/search progress indicators to show "Reading…" while in progress and "Read" when complete
+- Improved Claude to prefer file operation tools (Read, Edit, Write) over bash equivalents (cat, sed, awk)
+- [VSCode] Added automatic Python virtual environment activation, ensuring `python` and `pip` commands use the correct interpreter (configurable via `claudeCode.usePythonEnvironment` setting)
+- [VSCode] Fixed message action buttons having incorrect background colors
+
+## 2.1.20
+
+- Added arrow key history navigation in vim normal mode when cursor cannot move further
+- Added external editor shortcut (Ctrl+G) to the help menu for better discoverability
+- Added PR review status indicator to the prompt footer, showing the current branch's PR state (approved, changes requested, pending, or draft) as a colored dot with a clickable link
+- Added support for loading `CLAUDE.md` files from additional directories specified via `--add-dir` flag (requires setting `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`)
+- Added ability to delete tasks via the `TaskUpdate` tool
+- Fixed session compaction issues that could cause resume to load full history instead of the compact summary
+- Fixed agents sometimes ignoring user messages sent while actively working on a task
+- Fixed wide character (emoji, CJK) rendering artifacts where trailing columns were not cleared when replaced by narrower characters
+- Fixed JSON parsing errors when MCP tool responses contain special Unicode characters
+- Fixed up/down arrow keys in multi-line and wrapped text input to prioritize cursor movement over history navigation
+- Fixed draft prompt being lost when pressing UP arrow to navigate command history
+- Fixed ghost text flickering when typing slash commands mid-input
+- Fixed marketplace source removal not properly deleting settings
+- Fixed duplicate output in some commands like `/context`
+- Fixed task list sometimes showing outside the main conversation view
+- Fixed syntax highlighting for diffs occurring within multiline constructs like Python docstrings
+- Fixed crashes when cancelling tool use
+- Improved `/sandbox` command UI to show dependency status with installation instructions when dependencies are missing
+- Improved thinking status text with a subtle shimmer animation
+- Improved task list to dynamically adjust visible items based on terminal height
+- Improved fork conversation hint to show how to resume the original session
+- Changed collapsed read/search groups to show present tense ("Reading", "Searching for") while in progress, and past tense ("Read", "Searched for") when complete
+- Changed `ToolSearch` results to appear as a brief notification instead of inline in the conversation
+- Changed the `/commit-push-pr` skill to automatically post PR URLs to Slack channels when configured via MCP tools
+- Changed the `/copy` command to be available to all users
+- Changed background agents to prompt for tool permissions before launching
+- Changed permission rules like `Bash(*)` to be accepted and treated as equivalent to `Bash`
+- Changed config backups to be timestamped and rotated (keeping 5 most recent) to prevent data loss
+
 ## 2.1.19
 
 - Added env var `CLAUDE_CODE_ENABLE_TASKS`, set to `false` to keep the old system temporarily
@@ -343,7 +447,7 @@
 - Added loading indicator when resuming conversations for better feedback
 - Fixed `/context` command not respecting custom system prompts in non-interactive mode
 - Fixed order of consecutive Ctrl+K lines when pasting with Ctrl+Y
-- Improved @ mention file suggestion speed (~3x faster in git repositories)
+- Improved @ mention file suggestion speed (~3× faster in git repositories)
 - Improved file suggestion performance in repos with `.ignore` or `.rgignore` files
 - Improved settings validation errors to be more prominent
 - Changed thinking toggle from Tab to Alt+T to avoid accidental triggers

examples/settings/README.md

@@ -0,0 +1,31 @@
+# Settings Examples
+
+Example Claude Code settings files, primarily intended for organization-wide deployments. Use these are starting points — adjust them to fit your needs.
+
+These may be applied at any level of the [settings hierarchy](https://code.claude.com/docs/en/settings#settings-files), though certain properties only take effect if specified in enterprise settings (e.g. `strictKnownMarketplaces`, `allowManagedHooksOnly`, `allowManagedPermissionRulesOnly`).
+
+
+## Configuration Examples
+
+> [!WARNING]
+> These examples are community-maintained snippets which may be unsupported or incorrect. You are responsible for the correctness of your own settings configuration.
+
+| Setting | [`settings-lax.json`](./settings-lax.json) | [`settings-strict.json`](./settings-strict.json) | [`settings-bash-sandbox.json`](./settings-bash-sandbox.json) |
+|---------|:---:|:---:|:---:|
+| Disable `--dangerously-skip-permissions` | ✅ | ✅ | |
+| Block plugin marketplaces | ✅ | ✅ | |
+| Block user and project-defined permission `allow` / `ask` / `deny` | | ✅ | ✅ |
+| Block user and project-defined hooks | | ✅ | |
+| Deny web fetch and search tools | | ✅ | |
+| Bash tool requires approval | | ✅ | |
+| Bash tool must run inside of sandbox | | | ✅ |
+
+## Tips
+- Consider merging snippets of the above examples to reach your desired configuration
+- Settings files must be valid JSON
+- Before deploying configuration files to your organization, test them locally by applying to `managed-settings.json`, `settings.json` or `settings.local.json`
+- The `sandbox` property only applies to the `Bash` tool; it does not apply to other tools (like Read, Write, WebSearch, WebFetch, MCPs), hooks, or internal commands
+
+## Full Documentation
+
+See https://code.claude.com/docs/en/settings for complete documentation on all available managed settings.

examples/settings/settings-bash-sandbox.json

@@ -0,0 +1,18 @@
+{
+  "allowManagedPermissionRulesOnly": true,
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": false,
+    "allowUnsandboxedCommands": false,
+    "excludedCommands": [],
+    "network": {
+      "allowUnixSockets": [],
+      "allowAllUnixSockets": false,
+      "allowLocalBinding": false,
+      "allowedDomains": [],
+      "httpProxyPort": null,
+      "socksProxyPort": null
+    },
+    "enableWeakerNestedSandbox": false
+  }
+}

examples/settings/settings-lax.json

@@ -0,0 +1,6 @@
+{
+  "permissions": {
+    "disableBypassPermissionsMode": "disable"
+  },
+  "strictKnownMarketplaces": []
+}

examples/settings/settings-strict.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "disableBypassPermissionsMode": "disable",
+    "ask": [
+      "Bash"
+    ],
+    "deny": [
+      "WebSearch",
+      "WebFetch"
+    ]
+  },
+  "allowManagedPermissionRulesOnly": true,
+  "allowManagedHooksOnly": true,
+  "strictKnownMarketplaces": [],
+  "sandbox": {
+    "autoAllowBashIfSandboxed": false,
+    "excludedCommands": [],
+    "network": {
+      "allowUnixSockets": [],
+      "allowAllUnixSockets": false,
+      "allowLocalBinding": false,
+      "allowedDomains": [],
+      "httpProxyPort": null,
+      "socksProxyPort": null
+    },
+    "enableWeakerNestedSandbox": false
+  }
+}