Changes on 2026-08-16

1. **Analyze the Request**: * **Role**: World-class programmer with deep expertise in developer tools and documentation. * **Task**: Analyze documentation changes (3 pages: hooks.md, hooks-guide.md, settings.md) as a single batch. * **Output Format**: Concise batch analysis in Markdown. * **Language**: Chinese. * **Sections**: Overall Summary, Key Themes, Impact Level, Action Items. 2. **Analyze the Changes**: * **Page: hooks.md** (+12 / -7): * *Change 1*: Clarified the wording for `permission_prompt` notification timing. Changed "about 6 seconds without terminal input" to "after the prompt has waited about six seconds". * *Change 2*: Updated the `Notification` matcher table. Similar wording updates for `permission_prompt`, `elicitation_dialog`, and `elicitation_url_dialog` (6 seconds -> six seconds). * *Change 3*: Updated the `<Note>` section regarding notification timing. Clarified that these share timing with desktop notifications. Changed "when you appear to be away from the terminal" to "in terminal sessions you only see them when you appear to be away from the terminal". * *Change 4*: Added a new paragraph describing different behavior for `permission_prompt` in sessions using Agent SDK (like Claude Desktop/VS Code). It states it fires 6s after asking for permission, *not* deferred by typing (unlike terminal). It also mentions a new env var `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` and notes that this functionality didn't exist before v2.1.233. * **Page: hooks-guide.md** (+4 / -3): * *Change 1*: Updated the Notification matcher table to match the changes in hooks.md (wording: "prompt has waited about six seconds"). * *Change 2*: Added a paragraph pointing out that `permission_prompt` behaves differently in terminals vs. Desktop/VS Code, referring to hooks.md for details. * **Page: settings.md** (+9 / -1): * *Change 1*: Updated the description for `strictKnownMarketplaces`. Added a note about the `allowedMarketplaces` alias requiring v2.1.232 or later. 3. **Synthesize and Structure the Output**: * **Overall Summary**: These changes refine documentation regarding notification hook timing, specifically distinguishing behavior between terminal sessions and Agent SDK hosts (Desktop/VS Code), and update version requirements for specific settings. * *Draft (CN)*: 此次更新主要澄清了 `permission_prompt` 和相关通知钩子的触发时机，特别是区分了终端会话与 Agent SDK 环境（如 Claude Desktop/VS Code）的不同行为，并补充了特定配置项的版本要求说明。 * **Key Themes**: * **Behavioral Clarification of `permission_prompt`**: Distinction between terminal sessions (timer resets on typing) and Agent SDK hosts (timer does *not* reset on typing). * **Feature Availability/Versioning**: Added info about `permission_prompt` in Agent SDK sessions being new in v2.1.233 and `allowedMarketplaces` alias needing v2.1.232. * **New Environment Variable**: Introduction of `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`. * **Documentation Precision**: Consistent wording updates ("six seconds" vs "6 seconds"). * **Impact Level**: * *Assessment*: This is mostly clarification and bugfix documentation (feature that didn't exist before is now documented). No breaking changes to existing code, but understanding the difference in timing is crucial for developers relying on these hooks in different environments. * *Rating*: Medium. It changes how developers might expect hooks to behave in Desktop/VS Code vs. Terminal. * **Action Items**: * Review hook logic if you rely on `permission_prompt` in Claude Desktop/VS Code. * Check environment variable usage if you need to disable these specific hooks in Agent SDK hosts. * Ensure you are on v2.1.232+ if using the `allowedMarketplaces` alias. * Be aware of the version bump (v2.1.233) for `permission_prompt` support in non-terminal environments. 4. **Refine the Output (Chinese)**: * *Summary*: 此次更新主要澄清了通知钩子（特别是 `permission_prompt`）的触发逻辑，明确区分了终端环境与 Agent SDK 托管环境（如 Desktop/VS Code）中的不同计时行为，并补充了新功能的版本要求说明。 * *Themes*: * **环境行为差异化**: 明确指出 `permission_prompt` 在终端会话中会因用户打字而重置计时器，但在 Desktop/VS Code 等 Agent SDK 环境中不会重置。 * **新功能与版本依赖**: 新增了 `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` 环境变量，并指出 `allowedMarketplaces` 别名需 v2.1.232+ 版本支持，Agent SDK 中的 `permission_prompt` 行为需 v2.1.233+。 * **文档措辞统一**: 统一将时间描述调整为 "six seconds"，并细化了等待机制的解释。 * *Impact*: **Medium**。虽然主要是澄清，但改变了开发者对钩子在非终端环境下触发的预期。依赖此行为的开发者需要调整代码逻辑以适应不同环境的差异。 * *Action Items*: * 检查你的 `permission_prompt` 钩子逻辑，确认其在 Claude Desktop 或 VS Code 扩展中的行为是否符合预期（6秒后必定触发，不因打字重置）。 * 如果不希望在 Agent SDK 环境中触发 `permission_prompt`，请配置环境变量 `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1`。 * 使用 `allowedMarketplaces` 别名时，确保升级至 v2.1.232 或更高版本。 5. **Final Review**: Does it meet the constraints? Yes, markdown, concise, Chinese, specific sections. 6. **Construct Final Output**. (Proceeding to generate response).