Merge remote-tracking branch 'origin/master' into worktree/fix-pr1145-revised-guard-20260808

# Conflicts:
#	packages/ui/tool-ask-user/README.i18n.yaml
#	packages/ui/user-interaction/README.i18n.yaml

packages/ui/tool-ask-user/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ui/tool-ask-user/README.md
-README.md: d7866ff018ebfed5afbf105b1a20714490bdb818
-README.zh.md: 18a1c8e9f958c174fc34f26a572d88b6c031d7f9
+README.md: cb1cc11bba4010c885f320fc5569509ff48fccc0
+README.zh.md: 7558816a2874509717c50e22b93a548697f86ef7

packages/ui/tool-ask-user/README.md

@@ -15,7 +15,7 @@ Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the mo
 - `options` — optional choices with `label` and `description`. If recommending a choice, put it first and append `(Recommended)` to that label.
 - `multi_select` — whether that question may return more than one selected option.
 
-The tool calls `ctx.userInteraction.ask()` and returns canonical `{ answers: [{ id, selected, custom? }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices. The Native renderer preserves the compact JSON text shape `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`.
+The tool calls `ctx.userInteraction.ask()` and returns canonical `{ answers: [{ id, selected, custom? }] }`. `selected` contains option labels; `custom` carries a free-form answer, supplementing `selected` for a multi-select question and overriding it for a single-select question. The Native renderer preserves the compact JSON text shape `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`.
 
 ## Role
 

packages/ui/tool-ask-user/README.zh.md

@@ -15,11 +15,11 @@
 - `options`：可选选项，包含 `label` 和 `description`。如需推荐某个选项，请将其置于首位，并在该标签末尾追加 `(Recommended)`。
 - `multi_select`：该问题是否可以返回多个选中的选项。
 
-工具调用 `ctx.userInteraction.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；仅当用户自由填写回答时才会出现 `custom`，并覆盖选中的选项。Native 渲染器会保留紧凑的 JSON 文本形式 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`。
+工具调用 `ctx.userInteraction.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；`custom` 携带自由填写的回答，对于多选题会补充 `selected`，对于单选题则会覆盖它。Native 渲染器会保留紧凑的 JSON 文本形式 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`。
 
 ## 职责
 
-此包（package）是用户交互 seam 的消费方。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。
+此包是用户交互 seam 的消费方。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。
 
 ## 模型体验
 
@@ -49,7 +49,7 @@
 
 #### KV Cache 影响
 
-仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
 
 ## 已知限制与暂缓事项
 

packages/ui/tool-ask-user/package.json

@@ -21,9 +21,7 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {

packages/ui/tool-ask-user/tests/tool-ask-user.spec.ts

@@ -141,7 +141,8 @@ describe('ask_user_question tool', () => {
       async ask() {
         return {
           answers: [
-            { id: 'targets', selected: ['tests', 'docs'] },
+            { id: 'targets', selected: ['tests', 'docs'], custom: 'release notes' },
+            { id: 'labels-only', selected: ['tests'] },
             { id: 'notes', selected: [], custom: 'ship today' },
           ],
         }
@@ -160,6 +161,12 @@ describe('ask_user_question tool', () => {
             options: [{ label: 'tests' }, { label: 'docs' }],
             multi_select: true,
           },
+          {
+            id: 'labels-only',
+            question: 'Which labels should I keep?',
+            options: [{ label: 'tests' }, { label: 'docs' }],
+            multi_select: true,
+          },
           { id: 'notes', question: 'Any note?' },
         ],
       },
@@ -169,13 +176,14 @@ describe('ask_user_question tool', () => {
     if (result.isError) throw new Error('expected ask_user_question success')
     expect(result.value).toEqual({
       answers: [
-        { id: 'targets', selected: ['tests', 'docs'] },
+        { id: 'targets', selected: ['tests', 'docs'], custom: 'release notes' },
+        { id: 'labels-only', selected: ['tests'] },
         { id: 'notes', selected: [], custom: 'ship today' },
       ],
     })
     expect(result.content).toEqual([{
       type: 'text',
-      text: '{"answers":[{"id":"targets","selected":["tests","docs"]},{"id":"notes","selected":[],"custom":"ship today"}]}',
+      text: '{"answers":[{"id":"targets","selected":["tests","docs"],"custom":"release notes"},{"id":"labels-only","selected":["tests"]},{"id":"notes","selected":[],"custom":"ship today"}]}',
     }])
   })