Changes on 2026-04-22

Let me analyze this changelog update for version 2.1.118. The diff shows a new version entry (2.1.118) being added to the CHANGELOG.md.md file. This is a substantial update with many new features and bug fixes. Let me categorize the changes: **New Features:** 1. Vim visual mode (v) and visual-line mode (V) - editor features 2. Merged `/cost` and `/stats` into `/usage` - UX improvement 3. Custom themes support - theming capability 4. Hooks can invoke MCP tools directly via `type: "mcp_tool"` 5. `DISABLE_UPDATES` env var for stricter update control 6. WSL can inherit Windows settings via `wslInheritsWindowsSettings` 7. Auto mode improvements with `$defaults` support 8. "Don't ask again" option for auto mode opt-in 9. `claude plugin tag` command for release tags 10. `--continue`/`--resume` improvements for session finding 11. `/color` syncs to claude.ai/code 12. `/model` picker honors custom env var overrides **Bug Fixes (many related to MCP/OAuth):** - `/mcp` menu OAuth issues - MCP OAuth token expiry issues - MCP step-up authorization issues - OAuth token refresh race conditions - macOS keychain race conditions - Credential save crash on Linux/Windows - `/login` issues with env tokens - UI readability issues - Plan acceptance dialog issues - Agent-type hooks issues - Prompt hooks re-firing - `/fork` disk writing optimization - Alt+key shortcuts freezing - Remote session overwriting local settings - Typeahead errors - Plugin install dependency issues - File watcher errors - Remote Control session archiving - Subagent cwd restoration **Key themes:** 1. Vim editing enhancements 2. MCP (Model Context Protocol) improvements - especially OAuth/authentication 3. Theme customization 4. Plugin development workflow 5. Auto mode configuration 6. Cross-platform improvements (WSL, Linux, Windows, macOS) 7. Various UX and stability fixes **Impact level:** This is a significant update. While there are no obvious breaking changes, there are substantial new features and many important bug fixes, especially around authentication and MCP. The OAuth/MCP fixes are critical for stability. **Action items for developers:** 1. If using MCP servers with OAuth, this update fixes several authentication bugs 2. If developing plugins, can now use `claude plugin tag` and ship themes 3. If using hooks, can now invoke MCP tools directly 4. If on WSL, can now inherit Windows settings 5. Various stability improvements for remote sessions and subagents Let me write a concise analysis in Chinese.

1. **分析请求：** * **角色：** 世界级程序员，专门从事开发者工具和文档分析。 * **任务：** 分析一批文档变更（`network-config.md` 和 `CHANGELOG.md.md`）。 * **输出格式：** 简洁、有见地的 Markdown 分析。 * **语言：** 中文。 * **具体板块：** 1. 整体摘要（1-2 句话）。 2. 关键主题（要点）。 3. 影响等级（低/中/高/破坏性）及理由。 4. 开发者操作项（最多 5 个要点）。 2. **分析变更：** * **文件 1：`network-config.md`** * *变更：* 重构了“网络访问要求”部分。 * *格式：* 从无序列表改为表格，以便更清晰地展示 URL 及其用途。 * *新增内容：* `bridge.claudeusercontent.com`。 * *优化：* 阐明了第三方提供商（Bedrock、Vertex、Foundry）的流量路由。优化了关于 `downloads.claude.ai` 和 `storage.googleapis.com`（旧版）的说明。添加了 `max-version` 注释。 * *删除内容：* 一些冗长的段落被精简进表格。 * **文件 2：`CHANGELOG.md.md`** * *变更：* 新增条目：“Claude Code 和安装程序现在使用 `https://downloads.claude.ai/claude-code-releases` 而非 `https://storage.googleapis.com/...`。” * **交叉引用/关联：** * CHANGELOG 中提到的从 Google Storage 迁移到 `downloads.claude.ai` 直接解释了 `network-config.md` 为什么更新了 URL 列表和关于“旧版”使用的描述。 * *主题：* 基础设施/网络变更（下载主机的迁移）以及文档清晰度的提升（表格格式）。 3. **起草内容（中文思维草稿）：** * *整体摘要：* 此次变更更新了网络配置文档，将下载主机从 Google Storage 迁移至 Anthropic 域名，并优化了 URL 要求的可读性。 * *关键主题：* * 基础设施变更：安装/更新流量重定向。 * 文档结构化：使用表格代替列表以提高清晰度。 * 阐明旧版与当前行为。 * *影响等级：* 低到中。为什么？这是内部基础设施迁移，但严格的企业防火墙可能需要更新 allowlists。现有的 Google Storage URL 标记为“旧版”，所以如果更新频繁，这不算破坏性变更，但旧版本依赖它。 * *操作项：* * 更新防火墙/代理规则以包含 `downloads.claude.ai`。 * 意识到 `storage.googleapis.com` 适用于旧版本（在最终更新前需保留）。 * 检查 `bridge.claudeusercontent.com` 是否用于 Chrome 扩展。 4. **润色与格式化（中文）：** * *摘要：* 此次更新主要集中在将下载流量从 Google Storage 迁移至 Anthropic 自有域名，并重构了网络配置文档以提升表格形式的可读性。 * *主题：* * **基础设施迁移**：下载源从 `storage.googleapis.com` 迁移至 `downloads.claude.ai`。 * **文档结构优化**：将 URL 列表表格化，明确区分各 URL 的用途（如认证、API、插件下载等）。 * **兼容性说明**：明确了旧版本客户端对旧域名的依赖，以及 Chrome 扩展的 WebSocket 需求。 * *影响：* **中等**。虽然对于普通用户影响不大，但对于严格配置防火墙或代理的企业环境，必须更新 allowlists 以确保新版本的下载和自动更新功能正常。旧版依赖 `storage.googleapis.com`，短期内仍需保留旧域名的白名单。 * *操作项：* * 在防火墙和代理规则中将 `downloads.claude.ai` 加入白名单。 * 保留 `storage.googleapis.com` 的白名单设置，直到所有客户端更新至新版本（支持旧版下载）。 * 如果使用 Chrome 扩展，确保 `bridge.claudeusercontent.com` 允许 WebSocket 连接。 * 更新内部网络文档，以反映 `api.anthropic.com` 现在主要用于 WebFetch 的安全检查（当使用第三方提供商时）。 5. **最终打磨（对照约束条件检查）：** * Markdown 格式？是。 * 简洁？是。 * 中文？是。 * 最多 5 个操作项？是。 *起草过程中的自我纠正：* 在变更日志中，URL 路径是 `/claude-code-releases`。在网络配置文档中，它只是说了 `downloads.claude.ai`。我应该确认是只需要域名还是需要完整路径。通常，对于白名单，域名是标准的，但了解路径会有所帮助。我将根据文档变更坚持使用域名。 *影响推理：* 我将其定为“中等”。虽然是一个简单的 URL 变更，但在企业环境中，“安装程序无法更新”是一个阻碍问题。这是破坏性变更吗？不是，因为旧版 URL 仍然支持旧版，而且新版本会切换。但在企业环境中，这需要采取行动。 6. **最终输出生成**（继续生成回复）。

1. **Analyze the Request**: * **Role**: World-class programmer, expert in dev tools/documentation. * **Task**: Analyze documentation changes as a single batch. * **Format**: Markdown (Summary, Key Themes, Impact Level, Action Items). * **Language**: Chinese. * **Input**: A single diff from `hooks.md` describing the behavior of the `"defer"` return value in hooks. 2. **Analyze the Diff**: * **Context**: Hooks documentation, specifically regarding the `"defer"` return mechanism. * **Original Text**: "There is no timeout or retry limit. The session remains on disk until you resume it..." * **New Text**: "...The session remains on disk until you resume it, subject to the [`cleanupPeriodDays`](/en/settings#available-settings) retention sweep that deletes session files after 30 days by default..." * **Change**: Added clarification about session persistence limits. Specifically, sessions aren't kept *forever*; they are subject to a cleanup policy (default 30 days). 3. **Synthesize the Analysis**: * **Overall Summary**: The documentation update clarifies that sessions created when using the `"defer"` hook are not permanent; they are subject to an automatic cleanup policy (default 30 days), despite previously suggesting they remain indefinitely until resumed. * **Key Themes**: * **Data Retention/Lifecycle**: Clarifying the lifecycle of deferred sessions. * **Configuration Cleanup**: Introducing the concept of a retention sweep (`cleanupPeriodDays`). * **Impact Level**: **Medium**. * *Reasoning*: While not a breaking code change, it corrects a potential misconception. Developers relying on `"defer"` for long-term state persistence (e.g., thinking a session waits for weeks for approval) might lose data if the session expires. It changes the expectation from "indefinite" to "finite (30 days default)". * **Action Items**: * Review configuration settings for `cleanupPeriodDays` if 30 days is insufficient for your workflow. * Adjust user expectations or implementation if your workflow requires deferring actions for longer than the default retention period. * Ensure logic handles cases where a deferred session might be deleted before resumption. 4. **Drafting the Response (in Chinese)**: * *Summary*: 文档更新了关于 `"defer"` 行为的说明，明确了会话文件并非永久保留，而是受 `cleanupPeriodDays` 设置（默认 30 天）的清理策略影响。 * *Themes*: * 会话生命周期管理 * 清理策略与配置 * *Impact*: Medium. 原文暗示“无限期保留”，现在明确了“有 30 天默认限制”。这意味着如果开发者依赖 `defer` 进行长期挂起（超过 30 天），可能会丢失上下文。 * *Action Items*: * 检查 `cleanupPeriodDays` 设置是否符合业务需求。 * 评估现有的 Hook 逻辑是否能承受会话在 30 天后被自动清理。 * 通知相关团队关于会话丢失的潜在风险。 5. **Refining the Output**: * Ensure the tone is professional and concise. * Verify the markdown structure. *Drafting final output:* 1. **Overall Summary**: 文档更正了 `defer` 行为的描述，明确指出会话并非永久保留，而是受默认 30 天的保留策略（`cleanupPeriodDays`）限制，过期会被自动清理。 2. **Key Themes**: * **会话生命周期**：修正了“无限期保留”的误导，明确了会话数据的存储上限。 * **清理策略**：引入了 `cleanupPeriodDays` 配置项对 `defer` 会话的具体影响。 3. **Impact Level**: **Medium** * **Reasoning**: 虽然不是 API 代码层面的破坏性变更，但它纠正了一个关键假设。如果开发者之前认为会话会永久等待（例如用于审批流超过 30 天的场景），此变更意味着如果不调整配置，会话数据将会丢失。 4. **Action items for developers**: * 审查当前的 `cleanupPeriodDays` 设置，确认默认的 30 天保留期是否满足业务场景。 * 如果工作流涉及超过 30 天的挂起，需相应调整配置或改变实现方式。 * 在相关代码中增加对“会话可能已被清理”的错误处理逻辑。 6. **Final Polish**: The response looks good and meets all constraints.

1. **Analyze the Request**: * **Role**: World-class programmer analyzing documentation changes. * **Input**: 4 pages of diffs (`desktop.md`, `google-vertex-ai.md`, `interactive-mode.md`, `settings.md`). * **Output Format**: Markdown with 4 specific sections (Summary, Key Themes, Impact Level, Action Items). * **Language**: Chinese (as requested: "请用中文回复"). * **Tone**: Concise, insightful, developer-focused. 2. **Analyze the Diffs**: * **Page: `desktop.md`**: * Change: Link update for `autoMode`. * Old: `.../permissions#configure-the-auto-mode-classifier` * New: `.../auto-mode-config` * Context: Documentation structure change (URL slug change). * **Page: `google-vertex-ai.md`**: * Change 1: Clarification on region configuration. * Old: "global and regional endpoints". * New: "global, multi-region, and regional endpoints." * Addition: Mentions `CLOUD_ML_REGION` setting details (eu, us, us-east5) and hostnames (`aiplatform.eu.rep.googleapis.com`). * Change 2: Note update about model availability. * Old: "default models in all regions or on global endpoints". * New: "default models on every endpoint type. Model availability varies across specific regions, multi-region locations, and global endpoints." * Change 3: Troubleshooting "model not found" errors. * Update: "Verify the model is available in the location you specified..." mentioning `global` or `multi-region` constraints. * Update: "Set a region or multi-region location..." (instead of just regional). * Context: Better handling of Google Vertex AI's distinct endpoint types (global vs multi-region vs regional). * **Page: `interactive-mode.md`**: * Change: Voice input shortcut description. * Old: "Push-to-talk dictation", "Hold Space". * New: "Voice dictation", "Hold or tap Space", "Hold to record, or run `/voice tap` for tap-to-toggle." * Link update: "rebind-the-push-to-talk-key" -> "rebind-the-dictation-key". * Context: Feature enhancement/enabling tap behavior for voice input, not just hold. * **Page: `settings.md`**: * Change: Link update for `autoMode` description. * Old: `.../permissions#configure-the-auto-mode-classifier` * New: `.../auto-mode-config` * Context: Same link update as `desktop.md`. * *Note*: The diff cuts off at `voiceEnabled`, but the `autoMode` line is the main change visible. 3. **Synthesize Findings**: * *Theme 1: Documentation Structure/URL migration*. The `autoMode` configuration link changed from `/permissions#...` to `/auto-mode-config`. This suggests a reorganization of docs. * *Theme 2: Google Vertex AI Integration*. Significant clarification on endpoint types (Global, Multi-region, Regional). This is likely due to updates in Google Cloud's capabilities or Claude Code's support for them. * *Theme 3: UX/Voice Input*. The "tap-to-toggle" feature for voice input is now highlighted as a supported interaction method alongside "push-to-talk". 4. **Draft Content (Internal Monologue -> Chinese)**: * **Summary**: Documentation updates focus on improving clarity for Google Vertex AI endpoint configurations and reorganizing internal links for auto mode settings. Also highlights a new voice input interaction method. * *Chinese*: 文档更新主要集中在明确 Google Vertex AI 的端点配置细节、重组自动模式配置的内部链接，并引入了语音输入的新交互方式。 * **Key Themes**: * *Link Migration*: Moving Auto Mode config docs. * *Cloud Provider Specifics*: Better distinction between Global, Multi-region, and Regional endpoints for Vertex AI. * *UX Enhancements*: "Tap-to-toggle" for voice input is now officially supported/documented. * *Chinese*: * **文档结构重组**: 将“自动模式分类器”的配置链接迁移至新路径 (`auto-mode-config`)。 * **Google Vertex AI 集成增强**: 明确区分了 Global、Multi-region 和 Regional 端点类型，并更新了 `CLOUD_ML_REGION` 的配置说明及故障排查建议。 * **交互功能更新**: 语音输入支持“点击切换”模式，不再局限于“按住说话”。 * **Impact Level**: Low. These are mostly documentation corrections and clarifications. No API changes or breaking code changes for developers using the tool, unless they were relying on the specific docs link. * *Chinese*: Low (低)。主要是文档链接更新和说明澄清，未涉及 API 变更或破坏性代码更改。 * **Action Items**: * Update internal wikis if they reference the old `autoMode` config link. * If using Vertex AI, verify region settings (especially regarding multi-region vs specific regional availability). * Try the new `/voice tap` command for hands-free dictation. * *Chinese*: * 更新内部知识库中关于 `autoMode` 配置的旧链接。 * 若使用 Google Vertex AI，请检查区域设置，特别是多区域和特定区域的模型可用性差异。 * 尝试使用 `/voice tap` 命令体验新的点击切换语音输入功能。 5. **Refine and Polish**: * Ensure the tone is professional ("world-class programmer"). * Check markdown formatting. * Verify the constraint "single batch analysis". 6. **Final Output Generation** (Matches the thought process above).

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Input:** A batch of diffs from 9 documentation pages (`common-workflows.md`, `mcp.md`, `memory.md`, `model-config.md`, `monitoring-usage.md`, `plugin-marketplaces.md`, `settings.md`, `sub-agents.md`, `vs-code.md`). * **Output:** Concise, insightful analysis in Markdown format, focusing on what matters to developers, in *Chinese*. * **Specifics:** Overall summary, key themes, impact level, action items. 2. **Analyze the Diffs (Page by Page):** * **Page 1: `common-workflows.md`** * *Change:* Added a note about resuming sessions. If an old/large session consumes too many tokens, `/resume`, `--resume`, and `--continue` offer to resume from a *summary* instead of the full transcript. * *Exception:* Not available on Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. * *Impact:* Improves usability/cost saving for long sessions. * **Page 2: `mcp.md`** * *Change:* Updated the "Connect to GitHub" example. Previously implied an interactive authentication flow. Now explicitly requires passing a Personal Access Token (PAT) via a `--header` flag. * *Impact:* Breaking change in workflow for GitHub MCP users. Explicit auth is now required. * **Page 3: `memory.md`** * *Change:* Updated guidance for large `CLAUDE.md` files. Previously recommended splitting into imports or `.claude/rules/`. Now explicitly states that imports *still consume context at launch*. Recommends using "path-scoped rules" to only load instructions when relevant. * *Impact:* Performance optimization advice. Clarifies a common misconception about imports saving tokens. * **Page 4: `model-config.md`** * *Change 1:* `/model` selection persists across restarts (saved to user settings). v2.1.117+ writes to `.claude/settings.local.json` if the project has a pinned model. * *Change 2:* Startup header shows *where* the model setting came from if it's not user-selected. * *Change 3:* Updated default effort levels. v2.1.117: Opus 4.7 -> `xhigh`, Opus 4.6/Sonnet 4.6 -> `high`. Removed the specific Pro/Max mention (or simplified it). * *Impact:* Configuration behavior changes (persistence) and default settings shift (effort levels). * **Page 5: `monitoring-usage.md`** * *Change 1:* `OTEL_LOG_TOOL_DETAILS` now includes custom/plugin/MCP command names on `user_prompt` events. * *Change 2:* Added `effort` attribute to metrics (Token counter, API request/response events). * *Change 3:* Added `command_name` and `command_source` to `user_prompt` events. Notes that custom/MCP names collapse unless `OTEL_LOG_TOOL_DETAILS=1`. * *Impact:* Enhanced observability/telemetry. Better tracking of effort levels and command types. * **Page 6: `plugin-marketplaces.md`** * *Change:* Clarified that marketplace restrictions (allowlist/blocklist) are checked on *add*, *install*, *update*, *refresh*, and *auto-update*. If a marketplace was added *before* the policy, it's blocked from fetching new plugins. * *Impact:* Security tightening. Explicitly handles grandfathered marketplaces. * **Page 7: `settings.md`** * *Change:* Updated `blockedMarketplaces` description to match page 6 (enforcement on add, install, update, refresh, auto-update). * *Impact:* Consistency with marketplace changes. * **Page 8: `sub-agents.md`** * *Change:* Clarified that `mcpServers` in agent files applies *both* when the agent is spawned as a subagent AND when launched as the main session (`--agent`). * *Impact:* Documentation clarification. Defines scope of `mcpServers` config better. * **Page 9: `vs-code.md`** * *Change:* Updated the MCP add example to match `mcp.md` (GitHub PAT header requirement). * *Impact:* Consistency with MCP changes. 3. **Synthesize Key Themes:** * **Performance & Cost Efficiency:** Large session summaries, path-scoped rules for memory, context management. * **Configuration Persistence:** `/model` settings saving behavior, effort level defaults. * **Security & Auth:** GitHub MCP now requires explicit PAT via header. * **Observability:** New telemetry attributes (`effort`, `command_name`). * **Policy Enforcement:** Stricter checks on plugin marketplaces (pre/post policy). 4. **Draft the Analysis (in Chinese):** * *Overall Summary:* This update focuses on optimizing resource usage (context window/tokens), refining model configuration persistence, and tightening security/observability regarding MCP and plugins. * *Key Themes:* * **Context Optimization:** Resuming large sessions via summaries, clarification on imports vs. path-scoped rules. * **Configuration & Defaults:** Model selection persistence, updated default `effort` levels for Opus 4.7/4.6. * **Security & Auth:** GitHub MCP integration now requires a Bearer token. * **Observability:** New telemetry fields for effort levels and command sources. * **Policy Enforcement:** Stricter marketplace restriction checks across all plugin operations. * *Impact Level:* Medium. There are behavior changes in auth (GitHub MCP) and defaults (effort levels), plus new persistence logic. * *Action Items:* * Update GitHub MCP workflows to include `--header "Authorization: Bearer YOUR_GITHUB_PAT"`. * Review `CLAUDE.md` structure; use path-scoped rules instead of just imports to save context. * Be aware that `/model` choices now persist in `.claude/settings.local.json`. * Note the new default `effort` levels (`xhigh` for Opus 4.7). 5. **Refine Language (Polishing the Chinese):** * "Resume from a summary" -> 支持通过摘要恢复旧会话. * "Path-scoped rules" -> 路径限定规则. * "Observability" -> 可观测性. 6. **Final Review against constraints:** * Concise? Yes. * Insightful? Yes, highlights the import misconception and the auth change. * Markdown? Yes. * Chinese? Yes. 7. **Construct Final Output.** (Proceeding to generate output based on step 4 & 5).

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Input:** A single documentation diff (build-with-claude/vision.md) with a small addition (+1 line). * **Constraint:** Concise, insightful, markdown format, Chinese language response. * **Output Structure:** 1. Overall Summary 2. Key Themes 3. Impact Level 4. Action Items 2. **Analyze the Diff:** * **File:** `build-with-claude/vision.md` (Documentation for Claude's Vision API). * **Change:** Added one bullet point under a list of best practices/tips. * **Content:** "Image compression: Compressing images... can reduce latency... However, this can introduce artifacts... detrimental to model performance... especially multiple compression passes... Confirm your compression settings..." * **Context:** The previous points covered clarity, text legibility, and resizing. This new point addresses *compression*. 3. **Drafting the Analysis (Internal Monologue/Drafting):** * *Overall Summary:* The docs added a tip about image compression. It warns that while compression helps speed (latency), it can hurt accuracy (artifacts), especially for text. * *Key Themes:* Performance vs. Accuracy trade-offs, Image preprocessing best practices. * *Impact Level:* Low/Medium. It's informational guidance, not a breaking change. It helps devs optimize but doesn't break existing code. * *Action Items:* * Check if you are compressing images. * If you do, inspect the output. * Balance file size vs. quality. * Avoid multiple compression passes. 4. **Translating and Refining to Chinese:** * *Summary:* 文档新增了关于图像压缩的指导建议，指出了压缩在降低延迟与影响模型性能（尤其是文字识别）之间的权衡。 * *Themes:* * 图像预处理最佳实践 * 性能优化（延迟）与模型准确率的平衡 * *Impact:* Medium. Reasoning: 虽然不是破坏性变更，但对追求高性能和高准确率的开发者有重要的指导意义。 * *Action Items:* * 检查当前的图像压缩策略（如 JPEG/WebP）。 * 确认发送给 API 的图像质量是否因压缩而下降（特别是文字模糊）。 * 避免进行多次压缩。 * 在请求速度和识别效果之间找到平衡点。 5. **Final Review against Constraints:** * Concise? Yes. * Insightful? Yes, highlights the trade-off. * Markdown? Yes. * Chinese? Yes. 6. **Final Output Generation** (Proceed to generate the markdown response).