Changes on 2026-04-28

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Input:** 5 specific pages of documentation diffs (`hooks-guide.md`, `monitoring-usage.md`, `overview.md`, `quickstart.md`, `setup.md`). * **Output Format:** Markdown, concise, insightful, focused on developer impact, in *Chinese*. * **Structure:** 1. Overall Summary (1-2 sentences). 2. Key Themes (bullets). 3. Impact Level (Low/Medium/High/Breaking) with reasoning. 4. Action Items (bullets, max 5). 2. **Analyze the Diffs:** * **Page 1: `hooks-guide.md`** * *Change:* Added a `<Note>` block explaining that Claude can modify files via the `Bash` tool (e.g., running scripts, echo, sed) not just `Edit`/`Write` tools. * *Developer Impact:* Hooks matching `Edit|Write` will miss file changes made via Bash commands. Developers needing full audit trails need to adjust their hook strategies (use `Stop` hooks or match `Bash`). * **Page 2: `monitoring-usage.md`** * *Change:* Clarified telemetry. Changed "Telemetry is opt-in..." to "OpenTelemetry export to your backend is opt-in...". Added a reference to Anthropic's separate operational telemetry. * *Developer Impact:* Clarifies that while *sending data to your own backend* requires config, Anthropic's own internal telemetry might exist separately (with a link on how to disable it). Reduces confusion about data privacy. * **Page 3, 4, 5: `overview.md`, `quickstart.md`, `setup.md` (Windows Shell Changes)** * *Change:* Updated language regarding Windows requirements. * *Old:* "Git for Windows is required on native Windows..." * *New:* "Git for Windows is recommended... PowerShell is used if Git Bash is absent." * *Change in `setup.md`:* Updated the table comparing Native Windows vs WSL. Updated the PowerShell rollout description (implies it's a fallback or parallel option now). * *Developer Impact:* Lowers the barrier to entry on Windows. Developers don't strictly need Git for Windows anymore; PowerShell acts as a fallback. This is a UX improvement for Windows users. 3. **Synthesize & Translate to Chinese:** * *Overall Summary:* 此次更新主要优化了 Windows 上的 Shell 兼容性（将 Git Bash 改为“推荐”而非“必须”），并澄清了遥测数据的处理方式及 Hooks 对文件变更捕获的局限性。 (This update mainly optimizes Shell compatibility on Windows (changing Git Bash from "required" to "recommended"), and clarifies telemetry handling and the limitations of Hooks in capturing file changes.) * *Key Themes:* * **Windows 依赖放宽:** Git for Windows 不再是硬性要求，PowerShell 将作为备选方案。 * **Hooks 边界情况:** 明确了通过 Bash 命令修改的文件不会被 `Edit`/`Write` Hooks 捕获。 * **遥测隐私澄清:** 区分了用户导出的遥测数据与 Anthropic 的运营遥测数据。 * *Impact Level:* Low to Medium. It removes a barrier for Windows users (good) but reveals a potential gap in audit hooks for security-conscious users (need to act). * Let's stick to **Medium** because of the potential security implication in `hooks-guide.md` regarding missing file changes. * *Action Items:* * **Windows 用户:** 如果没有安装 Git for Windows，现在可以直接使用 PowerShell 运行 Claude Code。 * **安全审计/合规团队:** 检查现有的 Hooks 配置，如果需要记录*所有*文件变更，请按照文档建议添加 `Stop` Hook 或监听 `Bash` 工具。 * **所有用户:** 查看 Data Usage 页面以了解如何完全禁用 Anthropic 的运营遥测（如果之前误以为设置遥测配置即代表所有数据都不发送）。 4. **Drafting the Content (Iterative refinement):** * *Summary:* 本次文档更新降低了 Windows 平台的安装门槛，将 Git for Windows 从“必须”改为“推荐”并引入 PowerShell 作为回退方案。同时，它修正了关于遥测数据发送的描述，并指出了 Hooks 在捕获通过 Bash 命令进行的文件修改时的局限性。 * *Themes:* * **Windows 平台易用性提升**：放宽了对 Git Bash 的硬性依赖，允许直接使用 PowerShell。 * **Hooks 监控完整性**：指出了 Hook 仅捕获工具调用，可能遗漏 Bash 脚本导致的文件修改。 * **隐私与合规澄清**：明确了“导出遥测”与“厂商运营遥测”的区别，避免误解。 * *Impact:* **Medium**。理由：虽然移除了 Windows 硬件依赖降低了使用门槛，但 Hooks 指南的更新对于有严格审计要求的开发者至关重要，忽视此点可能导致安全盲区。 * *Action Items:* * 如果你在 Windows 上不想安装 Git，可以直接使用 Claude Code，系统会自动使用 PowerShell。 * **重要**：如果你的 Hooks 用于合规审计，请务必配置 `Stop` Hook 或监听 `Bash` 工具，否则无法捕获通过 Shell 命令（如 `sed`, `echo`）修改的文件。 * 检查并更新团队内部关于“Claude Code 遥测默认关闭”的理解，注意区分第三方后端导出和 Anthropic 内部运营数据。 5. **Final Review:** Does it meet the "Concise, Insightful, Focus on what matters" criteria? Yes. Is it in Chinese? Yes. 6. **Final Polish (Markdown formatting):** Ensure clear headers and bullet points. (Self-correction: Make sure the specific advice about `git status --porcelain` is implied or briefly mentioned in the summary of the action). * *Refining Action Item 2:* Make it specific. "Update hooks logic to include `Bash` inspection or use `Stop` hooks for full coverage." 7. **Output Generation.** (Proceed to generate output based on the drafted points).

1. **Understand the Goal:** The user wants a concise analysis of a set of documentation changes for "Claude Code". The analysis needs to cover the summary, key themes, impact level, and action items, all in Chinese. 2. **Analyze the Source Data (Diff Batch):** * `cli-reference.md`: * `--init` and `--maintenance` flags changed behavior. They used to start interactive mode, now they run hooks in print mode (`-p`) or specific scenarios (`--init-only`). * Links added for "Setup hooks". * `common-workflows.md`: * Added new notification matchers related to MCP (Model Context Protocol) elicitation: `elicitation_complete`, `elicitation_response`. * `hooks.md`: * New event: `Setup` (triggered by `--init-only`, `--init` in print mode, or `--maintenance`). * Updated lifecycle diagram. * Added new `Notification` types for elicitation. * Updated `SubagentStart` agent type from `Bash` to `general-purpose`. * `hooks-guide.md`: * Added `Setup` event. * Updated `Notification` types. * Updated `SubagentStart` agent type. * Clarified Exit 2 behavior for specific events like `Setup` and `SessionStart`. * `iam.md`: * Changed link from `troubleshooting` to `troubleshoot-install`. * `jetbrains.md`: * Major restructuring of WSL troubleshooting. * Added detailed steps for Windows Firewall rules and Mirrored Networking for WSL2. * Updated general language (capitalization changes). * Changed verification command from `npm list` to `claude --version`. * `overview.md`: * Changed "Git for Windows is recommended" to "required". * Updated links to `troubleshoot-install`. * `plugins-reference.md`: * Added `Setup` event to the table. * `quickstart.md`: * Changed "Git for Windows is recommended" to "required". * Updated links to `troubleshoot-install`. * `sandboxing.md`: * Added warnings about WSL1 not supporting sandboxing. * Added note about WSL2 blocking Windows binaries (`/mnt/c/`) inside sandbox. * `settings.md`: * Updated link to `troubleshoot-install`. * `setup.md`: * Changed "Git for Windows is recommended" to "required". * Updated links to `troubleshoot-install`. * Updated table regarding requirements. * Updated `claude doctor` description. * `troubleshooting.md`: * Drastic content reduction. Moved installation specific troubleshooting to a new section (likely `troubleshoot-install` inferred from links, though the page name change isn't explicitly shown in *this* diff block for the new file, the links point there). * Refocused on performance/stability issues. * `CHANGELOG.md.md`: * Version 2.1.122. * `ANTHROPIC_BEDROCK_SERVICE_TIER` env var. * `/resume` now finds PR-linked sessions. * Hooks fixes (rewound timelines, malformed entries). * Vertex AI / Bedrock fixes. * Bug fixes: ToolSearch, bash mode exit, image resizing, remote control idle status, etc. 3. **Synthesize Key Themes:** * **Hooks & Lifecycle:** Introduction of the `Setup` event, refined `--init`/`--maintenance` behavior (mostly for CI/Scripts), and new MCP elicitation events. * **Windows/WSL Requirements:** Git for Windows is now "required" for native Windows, not recommended. Enhanced WSL2 troubleshooting (firewall, networking). * **Documentation Reorg:** Troubleshooting split into install vs. performance. * **Bug Fixes & Polish:** Various bug fixes related to agents, tools, and UI (changelog). 4. **Determine Impact:** * **Medium.** The change to `--init` and `--maintenance` flags alters existing behavior (interactive -> print mode/hooks only), which could break scripts expecting interaction. The "Git for Windows required" change affects Windows users. The new hooks features are additive. 5. **Draft Action Items:** * Update CI scripts relying on `--init` or `--maintenance` to expect print mode behavior. * Ensure Git for Windows is installed for native Windows setups. * Review hooks for potential optimization using the new `Setup` event. * Apply WSL2 firewall rules if encountering IDE detection issues. 6. **Translate and Format (Markdown/Chinese):** * *Summary:* 本次文档更新主要引入了新的 `Setup` Hook 生命周期事件，调整了 `--init` 等参数的行为以适配 CI/脚本场景，并强化了 Windows (特别是 WSL2) 环境的安装要求与故障排查指南。 * *Themes:* * Hooks & 自动化：新增 `Setup` 事件，明确 `--init` 和 `--maintenance` 在 print 模式下的行为。 * Windows & WSL2：Git for Windows 变为“强制要求”，扩充了 WSL2 网络和防火墙配置的排查步骤。 * 文档重构：将安装与登录问题从通用故障排查中分离。 * Bug 修复：修复了 `/resume`、ToolSearch、Vertex AI 等多项问题。 * *Impact:* Medium。`--init` 和 `--maintenance` 参数行为发生变更，Windows 安装前置条件更严格。 * *Action Items:* * 检查依赖 `--init` 或 `--maintenance` 的 CI 脚本，适配新的 print 模式行为。 * 原生 Windows 用户确保安装了 Git for Windows。 * 若遇到 WSL2 IDE 检测问题，应用新的防火墙规则或镜像网络配置。 * 利用新的 `Setup` Hook 优化环境初始化流程。 7. **Refine:** Make it punchy and concise. Ensure the tone is "world-class programmer". * *Self-Correction on `--init` change:* The diff shows `--init` moved from "Run initialization hooks and start interactive mode" to "Run Setup hooks... (print mode only)". This is a breaking change if someone used it expecting an interactive shell. * *Self-Correction on WSL:* The WSL section in `jetbrains.md` was significantly rewritten with explicit PowerShell commands. This is high value for devs using that stack. 8. **Final Output Generation** (Matching the prompt's requested structure).

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Format:** Concise, insightful analysis in markdown. * **Language:** Chinese (as requested in the system prompt override). * **Input:** Three pages of diffs (`hooks.md`, `llm-gateway.md`, `plugins.md`). * **Required Sections:** Overall Summary, Key Themes, Impact Level (with reasoning), Action Items (max 5). 2. **Analyze the Diffs:** * **`hooks.md` (Major changes):** * **New Section:** "Add context for Claude" (新增“为 Claude 添加上下文”章节). This explains a new field `additionalContext` in hooks. It allows injecting dynamic context (like branch info, CI status) into Claude's context window at specific points (SessionStart, ToolUse, etc.). * **Details:** It differentiates between static context (use `CLAUDE.md`) and dynamic context (use hooks). It warns about prompt injection phrasing (use facts, not commands). It explains persistence on resume (`SessionStart` runs again, mid-session hooks use cached text). * **Updates to specific event tables:** * `SessionStart`: Updated `additionalContext` description to link to the new section. Updated example JSON to be more realistic. * `UserPromptSubmit`: Updated `additionalContext` description. * `UserPromptExpansion`: Updated `additionalContext` description. * **Observation:** This is a significant feature addition for hook functionality, enhancing developer control over what Claude knows during a session. * **`llm-gateway.md` (Minor change):** * **New Note:** Mentions that Claude Code now prepends an attribution block (client version, fingerprint) to the system prompt. * **Important Detail:** The Anthropic API strips this, so it doesn't affect *their* prompt caching. However, if a custom gateway implements its own caching keyed on the *full* request body, this block changes the hash/cost money. Solution: Set `CLAUDE_CODE_ATTRIBUTION_HEADER=0`. * **Observation:** Technical nuance for proxy/gateway maintainers regarding caching costs/efficiency. * **`plugins.md` (Trivial change):** * **Text tweak:** Added a sentence about hosting private marketplaces in private repositories to keep plugins internal. * **Observation:** Documentation polish/clarification. 3. **Synthesize and Structure the Analysis:** * **Overall Summary:** The documentation updates primarily introduce a powerful new "dynamic context" mechanism for hooks (`additionalContext`), enabling richer environment-aware interactions. Minor updates clarify system prompt attribution behavior for LLM gateways and internal plugin hosting options. * **Key Themes:** * **Enhanced Context Control:** Moving beyond static `CLAUDE.md` to dynamic, event-driven context injection via hooks. * **Dynamic vs. Static State:** Clear distinction between permanent project rules and runtime environment data (e.g., current branch, CI status). * **Gateway Caching Optimization:** Addressing a specific edge case where internal metadata affects proxy-based prompt caching. * **Impact Level:** * *High* for developers building custom hooks/integrations (new capability). * *Low* for general plugin users or standard gateway users (unless they implement custom body-based caching). * *Overall:* Medium-High. Let's go with **High** because the `additionalContext` feature changes how developers can architect their Claude Code automation. * **Action Items:** * Review existing hooks to see if `additionalContext` can replace hardcoded stdout or JSON logic. * Update custom gateway implementations to check if `CLAUDE_CODE_ATTRIBUTION_HEADER=0` is needed for prompt caching efficiency. * Refactor `CLAUDE.md` by moving dynamic rules (e.g., "Current branch is...") into `SessionStart` hooks. 4. **Drafting the Content (in Chinese):** * *Summary:* 文档更新重点引入了钩子系统中的“动态上下文”功能，允许开发者通过 `additionalContext` 向 Claude 注入运行时环境信息。同时，针对 LLM 网关的提示词缓存机制和插件的私有化部署进行了细节澄清。 * *Themes:* * 动态上下文注入：Hooks 新增 `additionalContext` 字段，区分静态配置与动态环境状态。 * 系统提示词归属元数据：解释了 Claude Code 如何在系统提示词中添加版本指纹，及其对自定义网关缓存的影响。 * 插件生态：完善了私有插件市场的部署指引。 * *Impact:* High. The `additionalContext` feature fundamentally changes how environment data is fed into Claude, offering significant automation potential. Gateway change is technical but niche. * *Action Items:* * 利用 `additionalContext` 字段优化 Hooks：将分支状态、CI 结果等动态信息从静态文档移至 `SessionStart` 或 `PostToolUse` 等钩子中。 * 检查自定义 LLM 网关：如果您的网关实现了基于完整请求体的缓存，请设置 `CLAUDE_CODE_ATTRIBUTION_HEADER=0` 以避免哈希失效。 * 遵循上下文编写规范：使用陈述性语气而非指令性语气编写注入文本，以避免触发 Claude 的防御机制。 5. **Review and Refine:** * The summary captures the essence. * Themes are distinct. * Impact level is justified. * Action items are actionable and specific. 6. **Final Polish:** Ensure markdown formatting is clean. (Proceed to generate output).

用户希望我分析一批文档变更。这是一组关于 Claude Code 工具（可能是一个 AI 编程助手）的 markdown 文件的变更。我需要提供简洁、有见地的分析，使用中文，并关注对开发者最重要的事情。 让我浏览所有变更，然后总结关键点。 **变更概览：** 1. **amazon-bedrock.md**: 添加了 `bedrock:GetInferenceProfile` 权限的解释。这可以让 Claude Code 解析应用推理配置文件 ARN 到其后端基础模型。如果没有这个权限，Claude Code 会自动重试一次，但这会增加往返次数。 2. **claude-code-on-the-web.md**: 添加了关于组织 IP 白名单的信息。云会话从 Anthropic 管理的基础设施调用 API，而不是从用户的网络。如果组织启用了 IP 白名单，云会话会因认证错误而失败。 3. **cli-reference.md**: 表格列宽调整，"Start in" 可能被截断了，看起来只是格式变更。 4. **data-usage.md**: 关于会话质量调查的重要更新。现在明确说明，在评分提示之后，可能会看到一个单独的后续提示询问是否允许查看会话记录。这是可选的第二步。如果选择"Yes"，会上传会话记录、子代理记录和原始会话日志文件。API 密钥和令牌模式会被编辑。源代码和文件内容原样上传。共享记录最多保留 6 个月。 5. **google-vertex-ai.md**: Claude Code v2.1.121 或更高版本支持基于 X.509 证书的工作负载身份联合。 6. **hooks.md**: 对 `PostToolUse` 钩子的重大更新。添加了 `updatedToolOutput` 字段，可以替换工具的输出。警告信息强调这只会改变 Claude 看到的内容，工具实际上已经运行了。 7. **interactive-mode.md**: 将 "Bash mode" 改名为 "Shell mode"，更加准确。 8. **legal-and-compliance.md**: 更新了 HackerOne 漏洞报告的 URL。 9. **mcp.md**: - MCP 服务器初始连接的重试行为更新（v2.1.121） - 添加了 `alwaysLoad` 配置选项，可以免除某些服务器或工具的延迟加载 10. **monitoring-usage.md**: - 添加了 `stop_reason` 和 `gen_ai.response.finish_reasons` 属性 - 添加了关于 `user_system_prompt` 的信息 11. **overview.md**: 关于 Windows 上 Git for Windows 的更新。不再是必需的，而是推荐的。如果没有安装，Claude Code 会使用 PowerShell 作为 shell 工具。 12. **plugin-marketplaces.md**: 市场清单的更新，`description` 和 `version` 现在是顶层字段，向后兼容 `metadata` 下的字段。 13. **plugins-reference.md**: 类似的市场清单更新，添加了 `$schema` 字段。 14. **quickstart.md**: 与 overview.md 类似的 Windows Git 更新。 15. **security.md**: HackerOne URL 更新。 16. **setup.md**: 与 overview.md 和 quickstart.md 类似的 Windows Git 更新。 17. **skills.md**: 添加了 `${CLAUDE_EFFORT}` 占位符，包含当前的努力级别。 18. **slash-commands.md**: 与 skills.md 类似。 19. **statusline.md**: 添加了 `hideVimModeIndicator` 字段。 20. **sub-agents.md**: 更新了 `CLAUDE_CODE_FORK_SUBAGENT` 变量的行为说明。 21. **terminal-config.md**: 添加了 iTerm2 设置的说明。 22. **troubleshooting.md**: Windows 故障排除的更新，反映了 PowerShell 作为后备选项的变更。 **关键主题：** 1. **Windows Shell 支持**：从严格要求 Git Bash 变为支持 Git Bash 或 PowerShell 作为后备 2. **数据隐私透明度**：更新了会话调查的数据收集说明，更加透明 3. **MCP 服务器配置**：添加了 `alwaysLoad` 选项和更好的重试行为 4. **钩子功能增强**：`PostToolUse` 钩子现在可以修改工具输出 5. **监控属性扩展**：添加了更多 OpenTelemetry 属性 6. **Bedrock/Vertex AI 集成**：添加了新的权限和认证支持 **影响级别：** 中等 - 主要是增强和澄清，没有破坏性变更。 **行动项：** 1. 审查新的 `PostToolUse` 钩子功能，看看是否能改进工作流 2. 如果使用 AWS Bedrock，考虑添加 `bedrock:GetInferenceProfile` 权限以提高性能 3. 如果在 Windows 上，现在可以使用 PowerShell 而不一定需要 Git Bash 4. 如果使用 MCP 服务器，考虑使用 `alwaysLoad` 选项来优化工具加载 5. 了解新的会话调查数据收集行为