Changes on 2026-07-02

1. **Analyze the Request:** * **Role:** World-class programmer/developer tools expert. * **Task:** Analyze documentation changes for 2 pages (`costs.md` and `CHANGELOG.md.md`). * **Output:** Concise, insightful analysis in Markdown, Chinese. * **Structure:** Overall Summary, Key Themes, Impact Level, Action Items. 2. **Analyze `costs.md` Changes:** * *Change 1:* Clarified `CLAUDE.md` file location ("at the root of your project"). *Impact: Clarity/Usability.* * *Change 2:* Added specific setup instructions for the `filter-test-output.sh` hook (create folder, save path, chmod +x). *Impact: Usability/Ease of setup.* * *Change 3:* Updated the description for `MAX_THINKING_TOKENS`. Changed from "lowering the budget with..." to "lowering the budget by setting the `MAX_THINKING_TOKENS` [environment variable](/en/env-vars)...". Added a link to environment variables docs. *Impact: Technical accuracy/clarity.* 3. **Analyze `CHANGELOG.md.md` Changes:** * *Version 2.1.199 (New):* * *Feature:* Stacked slash-skill invocations (load all leading skills). * *Bug Fixes:* SSL cert errors fail fast (saving retries), keep partial stream output on error, subagents return partial work on errors, subagent error reporting (not hiding errors), Linux background-agent daemon fix (corrupt worker record), macOS SSH cold-start fix, `claude stop` race condition fix, progress indicators fix, low memory error clarity, UI fixes (agent view), hooks stderr visibility, `dangerously-skip-permissions` fix, `SendMessage` routing fix, transcript file growth fix, `/color` persistence fix, config recovery backup fix, Chrome reconnect page fix, plan mode browser tool calls fix, automatic retry for server 429s (subscribers), environment variables for retry watchdog (`CLAUDE_CODE_RETRY_WATCHDOG`, `CLAUDE_CODE_MAX_RETRIES`), UI tweak for PR links. * *Version 2.1.198 (Minor addition):* * *Feature:* Subagents run in background by default (general availability). 4. **Synthesize Key Themes:** * **Stability & Robustness:** Massive focus on fixing background agents, subagent error handling, and retry logic. * **Configuration & Environment:** Better docs on variables (`MAX_THINKING_TOKENS`) and config recovery. * **Cost & Efficiency:** Explicit cost controls (thinking tokens), retry mechanisms to avoid wasting attempts, efficient hooks. * **Usability:** Clearer instructions for setup (scripts, paths), improved error messages, and UI polish. 5. **Determine Impact Level:** * *Reasoning:* While there are no "Breaking Changes" (API breaking), the sheer number of bug fixes related to stability (background agents crashing, subagents failing silently, SSL retries) significantly improves the reliability of the tool. The change to subagents running in the background by default changes workflow slightly but positively. The clarity improvements in `costs.md` help devs save money. * *Rating:* **Medium-High** (Bordering on High for reliability, but sticking to Medium-High as they are mostly fixes/refinements). Let's go with **Medium** for documentation changes (usually low) but since this includes a Changelog with critical fixes, I'll classify it as **Medium** to be safe, or **High** regarding stability. Let's stick to **Medium** generally, but mention the reliability boost. Actually, looking at the scope of fixes (background agents, SSH, retries), it's a significant maintenance release. I'll say **Medium**. 6. **Draft Action Items (Chinese):** * Update environment variable usage if setting thinking tokens. * Check hook setup scripts permissions/path. * Review background agent behavior (default now). * (Implicit) Upgrade to 2.1.199 for stability fixes. 7. **Drafting the Response (Iterative refinement in Chinese):** * *Overall Summary:* 此次更新主要集中在提升 CLI 的稳定性、错误处理能力和配置文档的清晰度。修复了后台代理和子代理中的多个关键 Bug，并优化了成本控制相关的说明。 * *Key Themes:* * **稳定性增强:** 修复了 Linux/macOS 后台代理崩溃、子代理失败静默处理、以及重试逻辑浪费配额等问题。 * **错误处理改进:** 流式响应中断保留部分结果、SSL 证书错误即时反馈、低内存显式提示。 * **文档与配置优化:** 明确了环境变量设置方式、Hook 脚本的具体创建步骤及 CLAUDE.md 路径。 * **子代理默认行为:** 子代理现在默认在后台运行（已在 2.1.198 推广）。 * *Impact Level:* **Medium**.（理由：主要是 Bug 修复和文档优化，显著提升了工具的可靠性，但不包含破坏性 API 变更。） * *Action Items:* * 检查并更新配置 `MAX_THINKING_TOKENS` 环境变量的方式。 * 按照新文档指引为 `filter-test-output.sh` Hook 设置正确的路径和执行权限。 * 升级到 2.1.199 以解决后台代理在 macOS SSH 和 Linux 守护进程中的崩溃问题。 * 利用新的堆叠斜杠技能功能（如 `/skill-a /skill-b`）以提升工作流效率。 8. **Review against constraints:** * Concise? Yes. * Insightful? Yes, highlights stability and cost efficiency. * Markdown format? Yes. * Chinese language? Yes. 9. **Final Polish:** Ensure the distinction between the *docs* changes and the *features* described in the docs is clear. The user asked to analyze documentation changes. * Page 1 (`costs.md`): Improved clarity on where to put config and how to run scripts. * Page 2 (`CHANGELOG.md.md`): Highlights a new version packed with fixes. *Self-Correction during drafting:* The prompt asks to analyze the documentation changes as a single batch. * Summary: Focus on the batch aspect (docs + changelog entry). * Themes: Mix of clarity (docs) and reliability (changelog). * Impact: The changelog indicates a major maintenance release, so impact is higher than just a doc typo fix. 10. **Final Output Generation** (similar to step 7).

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Task:** Analyze a batch of documentation changes (17 pages total). * **Format:** Markdown, concise, insightful. * **Language:** Chinese (as requested: "请用中文回复"). * **Content:** Summary, Key Themes, Impact Level, Action Items. 2. **Scan the Input Data (Diff Analysis):** * `interactive-mode.md`: Clarified `Ctrl+T` toggles "Claude's task checklist" vs "background-task view". Refined task list description (to-do checklist). * `plugins.md`: Added clarification on plugin directory location for quickstart paths. * `get-started.md`: Java SDK version bump (2.47.0 -> 2.47.1). * `about-claude/models/overview.md`: Model ID updates (Claude Opus 4.8, Sonnet 5, Haiku 4.5). Added specific pricing details (though diff shows some table formatting changes, the main update is model availability/pricing). * `about-claude/models/migration-guide.md`: Clarification on new tokenizer (token increase depends on content). Clarified migration steps. * `about-claude/pricing.md`: Clarification on tokenizer token increase variance. * `api/beta-headers.md`: Minor wording change ("released" vs "released"). * `build-with-claude/overview.md`: Removed specific Beta footnote qualifier. * `build-with-claude/text-generation.md`: Same as above (removed Beta footnote). * `build-with-claude/files.md`: Updated model reference from `ClaudeOpus4_6` to `ClaudeOpus4_8`. * `build-with-claude/claude-on-amazon-bedrock.md`: Java SDK version bump (2.47.0 -> 2.47.1). * `build-with-claude/claude-on-vertex-ai.md`: Java SDK version bump (2.47.0 -> 2.47.1). * `build-with-claude/claude-in-microsoft-foundry.md`: Java SDK version bump (2.47.0 -> 2.47.1). Updated Azure model availability (added Sonnet 5). Changed Claude Sonnet 5 status from preview to GA. * `agents-and-tools/tool-use/computer-use-tool.md`: Significant refactoring/clarification. Removed WebArena benchmark reference. Added recursive `$ref` warning (wait, that was in programmatic tool calling, let me check that file again... actually, the recursive warning is in `programmatic-tool-calling.md`, this file has general cleanup and code example updates). Updated Go SDK comments. Added import for `Model` in Java example. * `agents-and-tools/tool-use/web-search-tool.md`: Updated search tool versions (using `web_search_20260318`). Clarified dynamic filtering mechanics (runs inside code execution). Updated client instantiation names (consistency). * `agents-and-tools/tool-use/web-fetch-tool.md`: Updated fetch tool versions (`web_fetch_20260318`). * `agents-and-tools/tool-use/programmatic-tool-calling.md`: Added **Input schema limitations** section regarding recursive `$ref` causing 400 errors with programmatic calling. 3. **Synthesize and Structure (Mental Draft):** * *Summary:* This update primarily focuses on clarifying user interface distinctions (task lists), SDK version bumps, and refining documentation for new tool capabilities (web search/fetch, programmatic calling), along with model availability updates (Sonnet 5 GA). * *Themes:* * SDK/Tool Version Updates: Java SDK 2.47.1, Web Search/Fetch tool versions (`20260318`). * Model Availability: Claude Sonnet 5 is GA on Foundry, Opus 4.8 references added. * Clarifications & UX: Distinction between task checklists and background tasks; tokenizer cost variance notes. * Bug Fixes/Limitations: Recursive schema limitation in programmatic tool calling. * *Impact Level:* Medium. There are version updates and a specific schema limitation that might break existing implementations if they hit that edge case. Sonnet 5 GA is significant. * *Action Items:* * Update Java dependencies. * Update tool versions in code (web_search/web_fetch). * Review schemas for recursive refs if using programmatic tool calling. * Note the tokenizer cost variance for budgeting. 4. **Translate and Refine (Chinese):** * *Summary:* 此次文档更新主要涉及 SDK 版本升级（Java）、模型可用性更新，以及对工具行为和界面交互的澄清。 * *Themes:* * **SDK 与工具版本迭代**: Java SDK 升级至 2.47.1，Web Search 和 Web Fetch 工具推荐使用最新日期版本（`20260318`）。 * **模型与可用性变更**: Claude Sonnet 5 在 Microsoft Foundry 上转为正式发布（GA），文档更新了 Opus 4.8 的引用。 * **澄清与说明**: 明确区分了“Claude 的任务清单”与后台任务视图；细化了新 Tokenizer 对成本影响的描述（取决于具体内容）。 * **新增限制**: 明确了递归 `$ref` 模式在程序化工具调用中的限制。 * *Impact:* Medium (中等). 包含依赖升级和潜在的 Schema 兼容性问题。 * *Action Items:* * 升级 Java SDK 依赖至 2.47.1。 * 更新代码中 Web Search/Fetch 工具的版本字符串。 * 检查自定义工具的 `input_schema` 是否包含递归引用，以避免程序化调用报错。 * 针对成本敏感的应用，重新评估基于 Token 的预算，留意 Tokenizer 的增量波动。 5. **Final Polish:** Check against the specific diffs provided. * `programmatic-tool-calling.md` adds the recursive `$ref` constraint. This is a "gotcha". * `interactive-mode.md` changes are UX/UI docs, good for users but less "code breaking". * SDK bumps are standard maintenance. 6. **Construct Final Output:** 1. **Summary:** 此次更新主要涵盖了 SDK 版本升级、工具版本迭代（Web Search/Fetch）、模型可用性更新，以及对程序化工具调用中潜在 Schema 限制的重要补充说明。 2. **Key Themes:** * **依赖与版本更新**：Java SDK 统一升级至 `2.47.1`；Web Search 和 Web Fetch 工具示例更新为 `20260318` 版本；模型引用更新为 Claude Opus 4.8。 * **模型状态变更**：Claude Sonnet 5 在 Microsoft Foundry（Azure 托管）上状态由预览转为正式发布（GA）。 * **程序化工具调用限制**：新增对递归 `input_schema`（`$ref`）在程序化调用中会导致 400 错误的说明及变通方案。 * **功能澄清**：进一步明确了任务清单与后台任务的区别，以及新 Tokenizer 导致 Token 增量的不确定性。 3. **Impact Level:** **Medium (中等影响)** * **Reasoning:** 虽然主要是文档清理和版本更新，但新增的递归 Schema 限制可能影响现有的程序化工具调用实现。此外，工具版本号的更新建议跟进。 4. **Action Items:** * **升级依赖**：将 Java 相关依赖更新至 `2.47.1`。 * **更新工具版本**：在代码中将 Web Search 和 Web Fetch 工具的 `type` 更新为 `20260318` 以使用最新特性。 * **检查 Schema 定义**：若使用了程序化工具调用（`allowed_callers`），请检查自定义工具的 `input_schema` 是否包含递归引用，并按文档建议进行解构或改为直接调用。 * **重估 Token 预算**：鉴于新 Tokenizer 的增量取决于具体内容，建议对成本敏感的应用重新评估 `max_tokens` 限制和预算。 7. **Self-Correction during drafting:** Ensure I mention the "recursive $ref" part clearly, as that's the most "developer breaking" piece of info in the batch. The SDK bumps are routine. 8. **Final Output Generation** (matches the thought process above).