fix review findings: document ask-user recommendation convention

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

@@ -10,7 +10,7 @@ Model-facing `ask_user_question` tool over `ctx.userInteraction`. It lets the mo
 - `id` — required stable id on each question, echoed in the answer.
 - `question` — required question text for each question.
 - `header` — optional short heading.
-- `options` — optional choices with `label` and `description`.
+- `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 JSON text shaped as `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`. `selected` contains option labels; `custom` is present only for a free-form answer and overrides selected choices.

packages/ui/tool-ask-user/src/index.ts

@@ -36,7 +36,7 @@ export function apply(ctx: Context): void {
             },
             options: {
               type: 'array',
-              description: 'Optional choices to show the user.',
+              description: 'Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label.',
               items: {
                 type: 'object',
                 properties: {

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

@@ -99,6 +99,37 @@ describe('ask_user_question tool', () => {
     }])
   })
 
+  it('passes recommended option labels through without adding schema fields', async () => {
+    const ctx = await setup()
+    const seen: AskUserQuestionRequest[] = []
+    ctx.userInteraction.registerProvider({
+      async ask(request) {
+        seen.push(request)
+        return { answers: [{ id: 'pkg', selected: ['pnpm (Recommended)'] }] }
+      },
+    })
+
+    await ctx.tools.execute({
+      callId: CallId('ask-recommended'),
+      name: 'ask_user_question',
+      arguments: {
+        questions: [{
+          id: 'pkg',
+          question: 'Which package manager should I use?',
+          options: [
+            { label: 'pnpm (Recommended)' },
+            { label: 'npm' },
+          ],
+        }],
+      },
+    })
+
+    expect(seen[0]?.questions[0]?.options).toEqual([
+      { label: 'pnpm (Recommended)' },
+      { label: 'npm' },
+    ])
+  })
+
   it('projects custom answers and multi-select choices', async () => {
     const ctx = await setup()
     ctx.userInteraction.registerProvider({