Changes on 2026-03-17

1. **Analyze the Request**: * Role: World-class programmer. * Task: Analyze a batch of documentation changes (7 pages). * Output Format: Markdown, concise, insightful, Chinese. * Content: Diffs for `hooks.md`, `mcp.md`, `plugin-marketplaces.md`, `plugins-reference.md`, `settings.md`, `sub-agents.md`, `CHANGELOG.md.md`. 2. **Analyze Each Diff**: * **hooks.md**: * *Change*: Updated description of `${CLAUDE_PLUGIN_ROOT}` (adds "Changes on each plugin update"). Added new variable `${CLAUDE_PLUGIN_DATA}` for persistent data/state that survives updates. * *Context*: Managing plugin lifecycle and file persistence. * **mcp.md**: * *Change*: Updated "Environment variables" section. Clarifies `${CLAUDE_PLUGIN_ROOT}` for bundled files and introduces `${CLAUDE_PLUGIN_DATA}` for persistent state. * *Context*: MCP server configuration within plugins. * **plugin-marketplaces.md**: * *Change*: Clarified `${CLAUDE_PLUGIN_ROOT}` usage. Added recommendation to use `${CLAUDE_PLUGIN_DATA}` for dependencies/state that needs to survive updates. * *Context*: Plugin marketplace configuration. * **plugins-reference.md**: * *Change*: Major update to Environment Variables section. * Distinguishes between `ROOT` (bundled, volatile) and `DATA` (persistent). * Added "Persistent data directory" section explaining the path structure (`~/.claude/plugins/data/{id}/`). * Added complex code examples for managing dependencies (checking `package.json` diff to trigger `npm install`). * Updated `plugin uninstall` command to include `--keep-data` flag and warning about data deletion. * *Context*: The core reference for plugin developers. * **settings.md**: * *Change*: Added `agent` setting to run the main thread as a named subagent. * *Context*: Global configuration. * **sub-agents.md**: * *Change*: New section "Invoke subagents explicitly". Details three patterns: natural language, @-mention (syntax: `@agent-name`), and session-wide via `--agent` flag or `agent` setting. * *Context*: Agent usage and control flow. * **CHANGELOG.md.md**: * *Change*: Added entry for version 2.1.78. * *Key items confirming docs*: * Added `${CLAUDE_PLUGIN_DATA}` variable. * `plugin uninstall` prompts for deletion. * Added `effort`, `maxTurns`, `disallowedTools` frontmatter for agents. * Bug fixes (git log, infinite loop, sandbox, etc.). 3. **Synthesize and Group**: * *Theme 1: Plugin Data Persistence & Lifecycle*. The biggest change. Developers now need to distinguish between files bundled with the plugin (`ROOT`) and user-generated/dependency data (`DATA`). This prevents data loss during updates. * *Theme 2: Subagent Control*. Expanded capabilities to run the whole session as a specific subagent (`--agent` flag, `agent` setting) and explicit invocation via @-mentions. * *Theme 3: Minor Fixes & Refinements*. Changelog lists various bug fixes (security, git, sandbox, voice mode). 4. **Draft the Analysis (Iterative Refinement)**: * *Summary*: This update significantly enhances plugin lifecycle management by introducing persistent storage for dependencies, and expands developer control over subagents by allowing session-wide agent invocation. * *Key Themes*: * **Plugin Data Persistence**: Introduced `${CLAUDE_PLUGIN_DATA}` to separate volatile bundled files from persistent state (like `node_modules`), solving data loss issues on plugin updates. * **Explicit Subagent Invocation**: Added support for running the entire session as a specific agent (`--agent`, `agent` setting) and explicit @-mentioning agents. * **Plugin Maintenance**: Added `--keep-data` flag for uninstall commands to prevent accidental data loss. * *Impact*: **High** (for plugin developers). This is a breaking pattern change for plugin authors who currently write state to `ROOT`. They *must* migrate to `DATA` to avoid user data loss during updates. For general users, impact is **Medium** (new agent controls). * *Action Items*: * Update plugin scripts to use `${CLAUDE_PLUGIN_DATA}` for dependencies and state. * Modify `plugin uninstall` workflows or inform users about the new data deletion prompts. * Explore using the `agent` setting or `--agent` flag for dedicated sessions (e.g., code review). 5. **Format into Markdown (Translate to Chinese)**: * *Overall Summary*: 本次更新重点优化了插件的生命周期管理，引入了持久化存储目录以解决更新时数据丢失的问题，同时增强了 Subagent 的控制能力，支持会话级别的显式调用。 * *Key Themes*: * **插件数据持久化**: 新增 `${CLAUDE_PLUGIN_DATA}` 环境变量，用于存放依赖（如 `node_modules`）和状态文件，确保在插件更新时数据不丢失。 * **显式 Subagent 调用**: 新增通过 `--agent` 参数或 `agent` 配置项将整个会话以特定 Subagent 身份运行，并支持通过 `@` 提及显式调用。 * **插件卸载改进**: 卸载插件时默认会提示删除持久化数据，新增 `--keep-data` 选项以保留数据。 * *Impact*: **High (for Plugin Devs)** / **Medium (for Users)**. * Reasoning: Plugin developers必须调整目录结构以适应新的持久化机制，否则用户更新插件时将丢失关键数据（如虚拟环境）。普通用户获得了更强大的角色控制能力。 * *Action Items*: * [迁移插件状态存储] 将所有需要持久化的数据（依赖、缓存、配置）从 `${CLAUDE_PLUGIN_ROOT}` 迁移至 `${CLAUDE_PLUGIN_DATA}`。 * [更新依赖安装脚本] 参考文档中的 `diff` 模式，实现仅在依赖清单变更时重新安装依赖的逻辑。 * [利用 Subagent 模式] 尝试在 `.claude/settings.json` 中配置 `agent` 字段，为特定项目（如代码审查）预设专用 Agent。 6. **Final Review**: Does the content match the diffs? Yes. Is it concise? Yes. Is it in Chinese? Yes. 7. **Final Output Generation** (matches the thought process above).

1. **分析请求：** * **角色：** 世界级程序员，专注于开发者工具和文档。 * **任务：** 将文档变更作为一个批次进行分析。 * **输入：** 三个文件的变更：`amazon-bedrock.md`、`google-vertex-ai.md`、`memory.md`。 * **输出格式：** Markdown。 * **输出板块：** 1. 整体摘要（1-2 句话）。 2. 跨页关键主题（项目符号）。 3. 影响级别（低/中/高/破坏性）及理由。 4. 开发者行动项（项目符号，最多 5 个）。 * **语言：** 中文。 2. **分析变更：** * **`amazon-bedrock.md`：** * *变更：* 将环境变量 `ANTHROPIC_SMALL_FAST_MODEL` 重命名为 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。 * *语境：* 用于推理配置。 * **`google-vertex-ai.md`：** * *变更：* 将环境变量 `ANTHROPIC_SMALL_FAST_MODEL` 重命名为 `ANTHROPIC_DEFAULT_HAIKU_MODEL`（两处：代码块和故障排查文本）。 * *语境：* 用于模型配置和区域端点故障排查。 * **`memory.md`：** * *变更：* 增加了一个新的部分/表格，对比了“托管 CLAUDE.md”与“托管设置”。 * *语境：* 澄清了技术强制执行（设置）与行为指导之间的区别。 * *细节：* 包含了一个表格，将具体关注点（权限、环境变量与代码风格、数据处理）映射到正确的配置机制。 3. **综合变更：** * *主题 1：变量重命名。* 从 `ANTHROPIC_SMALL_FAST_MODEL` 到 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的一致性更改。这看起来像是一个跨提供商的标准化命名约定。 * *主题 2：文档澄清。* 在 `memory.md` 中增加了关于配置设置的指南。这是一个功能性增强，旨在减少开发者关于如何强制实施规则与提供指导的困惑。 4. **起草回复（内心独白/尝试）：** * *整体摘要：* 文档对 Bedrock 和 Vertex AI 的环境变量命名进行了标准化，具体是将 `ANTHROPIC_SMALL_FAST_MODEL` 重命名为 `ANTHROPIC_DEFAULT_HAIKU_MODEL`，并阐明了设置与 CLAUDE.md 之间的区别。 * *关键主题：* * 变量重命名的标准化。 * 强制执行（设置）与指导之间的区别。 * *影响级别：* 中/高？这是一个环境变量更改。如果开发者的脚本中使用了旧变量，将会中断。这很可能是一个破坏性变更，因此“高”是恰当的。 * *行动项：* * 更新脚本/环境文件中的变量名。 * 查看新的配置表以了解最佳实践。 * 检查是否需要将权限从 CLAUDE.md 迁移到设置。 5. **翻译成中文并格式化：** * *摘要：* 此次更新统一了 Amazon Bedrock 和 Google Vertex AI 的环境变量命名标准，将 `ANTHROPIC_SMALL_FAST_MODEL` 重命名为 `ANTHROPIC_DEFAULT_HAIKU_MODEL`；同时增加了关于“托管设置”与“托管 CLAUDE.md”功能区别的详细指南。 * *主题：* * **变量重命名与标准化**：跨两个云提供商文档，将旧的模型配置变量名替换为更具体的新名称。 * **配置机制澄清**：新增内容区分了技术强制执行与行为指导，帮助开发者更准确地使用配置文件。 * *影响级别：* **高**。虽然主要是文档更新，但它暗示了环境变量 API 的破坏性变更。继续使用旧的变量名可能会导致应用无法正确读取配置。 * *行动项：* * 更新所有 Shell 配置文件（如 `.bashrc`, `.zshrc`）或 CI/CD 管道中的 `ANTHROPIC_SMALL_FAST_MODEL` 为 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。 * 检查并迁移现有的安全策略（如路径阻断、沙箱隔离），确保它们配置在“托管设置”中而非 CLAUDE.md 中。 * 阅读新增的配置对比表，以确保团队对技术限制和行为指导的定义保持一致。 6. **最终润色：** 确保语气专业且简洁。 * *关于“破坏性”的修正：* 提示要求的是“文档变更”。如果 SDK 仍然支持旧变量，那就是低影响。通常，*仅*当变更暗示了破坏性 API 变更时，文档变更才会被视为“高”影响。鉴于变量名发生了变化，并且明确出现在代码块中作为“操作方法”，极有可能旧变量已被弃用或移除。将其归类为“高”以警告开发者是最稳妥的做法。*等等，再看一遍 diff。* 是 `+1/-2`。这是文本替换。这很可能是 SDK 中的一个破坏性变更。我将其标记为“高”，因为它涉及环境变量。 7. **生成最终输出**（匹配要求的结构）。 * *起草时的自我修正：* 务必突出具体的新变量名。 （用中文起草回复...） 标题：文档变更分析 摘要：... 关键主题：... 影响级别：... 行动项：... *优化行动项使其可执行：* 1. 更新环境变量。 2. 审查配置策略。 3. 查看新指南。 *优化影响级别：* 高（理由：环境变量变更通常会破坏现有的部署脚本）。 8. **对照约束条件进行最终审查：** * 简洁？是。 * 洞察深刻？是。 * Markdown 格式？是。 * 聚焦开发者？是。 * 中文？是。

1. **Understand the Goal:** The user wants a concise, insightful analysis of 13 documentation changes for a developer tool (Claude Code). The output must be in Markdown and in Chinese. 2. **Analyze the Changes (Page by Page):** * `common-workflows.md`: * Plan Mode: Auto-naming sessions based on plan content (preserving existing names). * Thinking Mode: Refinement on `MAX_THINKING_TOKENS`. Newer models (Opus 4.6/Sonnet 4.6) use adaptive reasoning. `MAX_THINKING_TOKENS` is mostly ignored unless set to 0 or `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` is set. Older models use fixed budgets. Clarified per-model ceilings. * Sessions: Added `/branch` to the list of session types. Minor text changes. * Container text: "Clone our..." -> "Clone the...". * `costs.md`: * Updated "Adjust extended thinking" text to remove specific token count (31,999) and clarify that budgets vary by model. * `headless.md`: * New event: `system/api_retry`. Emits info about retries (attempt number, max retries, delay, error status, etc.). Useful for custom backoff or progress UI. * `hooks.md`: * `InstructionsLoaded`: Added `"compact"` to `load_reason`. * `PreToolUse`: Clarified that returning `"allow"` skips the *interactive* prompt but *does not* override deny/ask rules (including enterprise managed deny lists). * `hooks-guide.md`: * Reinforced the `PreToolUse` behavior: `"allow"` skips interactive prompts but strict permission rules (deny lists) still take precedence. * `iam.md`: * Slow helper notice: Warns if `apiKeyHelper` takes > 10s. * Clarified that `apiKeyHelper` and API keys only apply to CLI, not Desktop/remote (which use OAuth). * `interactive-mode.md`: * Background tasks: Auto-terminated if output exceeds 5GB. * `memory.md`: * `/init`: New env var `CLAUDE_CODE_NEW_INIT=true` enables a multi-phase interactive flow (setup CLAUDE.md, skills, hooks, subagent exploration, reviewable proposal). * `plugin-marketplaces.md`: * **New Feature**: Pre-populate plugins for containers using `CLAUDE_CODE_PLUGIN_SEED_DIR`. Mirrors `~/.claude/plugins` structure. Read-only. Seed entries take precedence. * Validation: Enhanced validator now checks frontmatter (YAML) and `hooks/hooks.json`, not just JSON. * Added specific errors for YAML parsing and JSON hooks. * Added warning about Kebab-case naming for Claude.ai marketplace sync. * `plugins-reference.md`: * Troubleshooting: Updated "Plugin not loading" to reflect the enhanced validator (checks frontmatter/hooks). * `sandboxing.md`: * **New Feature**: `sandbox.filesystem.allowRead`. Can re-allow specific paths within a `denyRead` region. * Merging behavior: Now applies to `allowRead` too. * Clarification: When `allowManagedReadPathsOnly` is on, only managed `allowRead` entries count. * `settings.md`: * Added `sandbox.filesystem.allowRead` to the config table. (Note: The diff cuts off at the table, but the change is clear based on `sandboxing.md` and the start of the row). * `sub-agents.md`: * Resuming subagents: Clarified that if a background subagent fails due to permissions, start a *new* foreground one rather than "resuming" (likely because resuming a failed one might be tricky or just phrasing update). * Clarified how `SendMessage` works with stopped subagents (auto-resumes in background). 3. **Synthesize and Group Themes:** * **Sandboxing & Security**: New `allowRead` capability, clear precedence rules for permissions in hooks. * **Plugin System**: Container pre-seeding (`PLUGIN_SEED_DIR`), robust validation (YAML/hooks), naming conventions. * **Thinking/Cost**: Clarification on adaptive reasoning vs. fixed budgets across model versions. * **Infrastructure/Operations**: Headless mode retries (`api_retry`), slow credential warnings, background task limits (5GB). * **Workflow Enhancements**: Session naming, new `/init` flow, subagent resumption details. 4. **Assess Impact:** * **High**: The plugin pre-seeding and sandbox `allowRead` are significant structural changes for enterprise/container users. The permission rule precedence clarification in hooks is critical for security configurations. * **Medium**: Thinking token clarifications affect cost management. The `/init` flow change alters the developer onboarding experience. * **Low**: Text tweaks, minor bug fixes (like subagent resumption phrasing), 5GB background task limit (edge case). *Overall Verdict*: **High** because of the container support for plugins and the refined sandboxing permissions, plus the critical security clarification regarding hooks. 5. **Draft Action Items:** * Review hook configurations if they rely on `PreToolUse` returning `"allow"` bypassing *all* security (it doesn't anymore/never did for managed rules). * Consider using `CLAUDE_CODE_PLUGIN_SEED_DIR` for container images/Dockerfiles. * Check sandbox settings to utilize `allowRead` if using broad `denyRead`. * Update scripts/documentation regarding `MAX_THINKING_TOKENS` for newer models. * Use the new `/init` flow for better project setup. 6. **Translate to Chinese and Format:** * *Summary*: 此次更新聚焦于增强插件系统的容器化支持、细化沙箱权限控制、澄清成本与推理模型的令牌行为，并改进了会话管理和自动化初始化流程。 * *Themes*: 插件系统, 沙箱与安全, 成本与推理, 基础设施. * *Impact*: High. * *Actions*: Update Dockerfiles for plugins, review hook permissions, adjust thinking token settings, try new `/init`, check sandbox configs. 7. **Refine the Output (Self-Correction during drafting):** * Ensure distinction between "Breaking" and "High". It's not "Breaking" code, but "High" impact for maintainers/admins. * Make sure to emphasize the `allowRead` addition in sandboxing as it's a new capability. * The change regarding `PreToolUse` hook clarifying that "allow" doesn't bypass deny lists is a security nuance that matters significantly to enterprise users. 8. **Final Polish (Markdown Structure):** Matches the user's request.

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Input:** A single diff for `plugin-marketplaces.md`. * **Constraint:** Concise, insightful analysis in markdown. Focus on developer impact. Reply in Chinese. * **Structure:** Overall Summary, Key Themes, Impact Level, Action Items. 2. **Analyze the Input Diff:** * **File:** `plugin-marketplaces.md`. * **Context:** A table describing different source types for plugins (Relative path, github, url, git-subdir, npm, pip). * **Changes:** * Rows: `url` and `git-subdir`. * Specific Change: Removed the requirement "must end .git" from the `url` source description. * Formatting: Slight column width adjustments (whitespace changes). 3. **Interpret the Change:** * **Removal of "must end .git":** This is the substantive change. Previously, developers using the `url` source type *had* to ensure their URL ended with `.git`. Now, that restriction is lifted. This aligns `url` behavior closer to standard git behavior (which often accepts URLs with or without `.git`). * **Why it matters:** It reduces validation errors or configuration headaches for developers defining plugin sources. It's a relaxation of constraints, usually a positive usability change. 4. **Draft the Analysis (Internal Monologue/Drafting in Chinese):** * *Overall Summary:* The documentation for the `url` plugin source has been updated. Specifically, the requirement that the URL must end in `.git` has been removed. * Chinese: 文档更新了 `url` 插件源的规范，移除了 URL 必须以 `.git` 结尾的硬性要求。 * *Key Themes:* * Relaxation of validation rules. * Git URL standardization/flexibility. * Chinese: 灵活性提升，校验规则放宽。 * *Impact Level:* * Is it breaking? No. Removing a restriction usually means previously valid configs remain valid, and previously invalid ones might now work. * Is it high? No. It's a small detail in a table. * Chinese: Low (低)。这属于规则放宽而非破坏性变更，提升了配置的容错性。 * *Action Items:* * Do developers *need* to do anything? Not really. Maybe update their configs if they were adding `.git` just to satisfy the rule (though adding it is still fine). * Actually, action items should be: "Review current plugin URLs" (optional), or "Note the flexibility". * Wait, if the doc removed it, developers can now use URLs without `.git`. So the action is: You can now use standard Git URLs without the `.git` suffix if you prefer. * Chinese: 无强制性操作。可选：如果之前为了兼容性添加了 `.git` 后缀，现在可以移除（但保留也没问题）。 5. **Refine and Format Output (Chinese):** * **1. Overall Summary**: 文档移除了 `url` 插件源配置中 URL 必须以 `.git` 结尾的限制，实现了与标准 Git URL 行为的对齐。 * **2. Key Themes**: * **约束放宽**: 删除了对特定文件后缀的硬性校验要求。 * **兼容性提升**: 支持更灵活的 Git URL 格式输入。 * **3. Impact level**: **Low** (低)。 * **Reasoning**: 这是一个非破坏性变更（non-breaking change）。移除限制意味着之前合规的配置依然有效，而之前可能被拒绝的配置现在可以被接受，从而降低配置门槛。 * **4. Action items for developers**: * 无需立即采取行动。 * 在配置 `url` 类型的插件源时，不必再强制检查或添加 `.git` 后缀。 6. **Final Review:** Does this meet the "world-class programmer" persona? Yes, it's precise, technical, and correctly identifies that this is likely a bug fix or UX improvement regarding validation rules. 7. **Final Output Generation.** (Proceed to generate output based on step 5).