@xingular/harness 2.1.1 → 3.0.0

package/src/terminal/tui/piAdapter.ts

@@ -1,10 +1,12 @@
 // Pi 1.2.0 omits CLI builtins, rich builtin renderers, clipboard reads and the global theme setter
 // from its public exports. Keep those version-sensitive presentation hooks here; session/runtime
 // work uses public APIs. Clipboard helpers are only called for an explicit user paste.
-import { getPackageDir, VERSION, type InlineExtension, type Theme, type ToolRenderers } from '@earendil-works/pi-coding-agent'
+import type { InlineExtension, Theme, ToolRenderers } from '@earendil-works/pi-coding-agent'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
+import { loadPi, PINNED_PI_VERSION } from '../../pi/runtime'
+
 export interface PiAdapter {
   builtins: InlineExtension[]
   setTheme(theme: Theme): void
@@ -19,13 +21,14 @@ let adapter: PiAdapter | undefined
 let loading: Promise<PiAdapter> | undefined
 
 export function assertPiAdapterVersion(version: string): void {
-  if (version !== '1.2.0') throw new Error(`The Harness terminal adapter requires Pi 1.2.0; found ${version}. Install the Harness package's pinned dependencies.`)
+  if (version !== PINNED_PI_VERSION) throw new Error(`The Harness terminal adapter requires Pi ${PINNED_PI_VERSION}; found ${version}. Install the Harness package's pinned dependencies.`)
 }
 
 export function loadPiAdapter(): Promise<PiAdapter> {
   loading ??= (async () => {
-    assertPiAdapterVersion(VERSION)
-    const root = getPackageDir()
+    const pi = await loadPi()
+    assertPiAdapterVersion(pi.VERSION)
+    const root = pi.getPackageDir()
     const [extensions, theme, renderers, clipboard, images] = await Promise.all([
       import(pathToFileURL(join(root, 'dist/extensions/index.js')).href),
       import(pathToFileURL(join(root, 'dist/modes/interactive/theme/theme.js')).href),

package/src/terminal/tui/questionPicker.ts

@@ -0,0 +1,168 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { SelectList, stripTerminalSequences, truncateToWidth, visibleWidth, type Component, type Focusable, type SelectListTheme, type TUI } from '@earendil-works/pi-tui'
+
+import type { QuestionOption } from '../../sessions/contracts'
+import { DialogPanel } from './dialogs'
+
+const RECOMMENDED = '(Recommended)'
+
+type DisplayOption = { option: QuestionOption; index: number }
+
+export type QuestionPickerResult =
+  | { type: 'answer'; selected: string[] }
+  | { type: 'text'; selected: string[] }
+  | { type: 'cancel' }
+
+export function questionOptionsInDisplayOrder(options: readonly QuestionOption[]): DisplayOption[] {
+  const indexed = options.map((option, index) => ({ option, index }))
+  return [...indexed.filter(({ option }) => option.recommended), ...indexed.filter(({ option }) => !option.recommended)]
+}
+
+function recommendedSelectTheme(theme: Theme): SelectListTheme {
+  return {
+    selectedPrefix: text => theme.fg('accent', text),
+    selectedText: text => {
+      const marker = text.lastIndexOf(RECOMMENDED)
+      if (marker < 0) return theme.fg('accent', text.replace(/^→/, '❯'))
+      const afterMarker = marker + RECOMMENDED.length
+      return theme.fg('accent', text.slice(0, marker).replace(/^→/, '❯')) + theme.fg('warning', RECOMMENDED) + theme.fg('accent', text.slice(afterMarker))
+    },
+    description: text => theme.fg('muted', text),
+    scrollInfo: text => theme.fg('dim', text),
+    noMatch: text => theme.fg('warning', text.replace('commands', 'options'))
+  }
+}
+
+class QuestionPickerContent implements Component, Focusable {
+  private list!: SelectList
+  private selectedIndexes: number[]
+  private focusedValue = false
+  private readonly displayOptions: DisplayOption[]
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    private readonly options: readonly QuestionOption[],
+    private readonly multiSelect: boolean,
+    private readonly allowText: boolean,
+    selected: readonly string[],
+    private readonly done: (result: QuestionPickerResult) => void
+  ) {
+    this.displayOptions = questionOptionsInDisplayOrder(options)
+    this.selectedIndexes = []
+    const remaining = [...selected]
+    options.forEach((option, index) => {
+      const selectedIndex = remaining.indexOf(option.label)
+      if (selectedIndex >= 0) {
+        this.selectedIndexes.push(index)
+        remaining.splice(selectedIndex, 1)
+      }
+    })
+    this.rebuild()
+  }
+
+  get focused(): boolean { return this.focusedValue }
+  set focused(value: boolean) { this.focusedValue = value }
+
+  private labels(): string[] {
+    return this.selectedIndexes.map(index => this.options[index]!.label)
+  }
+
+  private rebuild(): void {
+    const selectedValue = this.list?.getSelectedItem()?.value
+    const items = this.displayOptions.map(({ option }, displayIndex) => ({
+      value: `option:${displayIndex}`,
+      label: `${displayIndex + 1}. ${this.selectedIndexes.includes(this.displayOptions[displayIndex]!.index) ? '✓ ' : ''}${option.label}${option.recommended ? ` ${RECOMMENDED}` : ''}`,
+      description: option.description
+    }))
+    if (this.allowText) items.push({ value: 'write', label: 'Write an answer', description: undefined })
+    if (this.multiSelect) items.push({ value: 'submit', label: 'Submit choices', description: undefined })
+
+    const maxVisible = Math.min(12, Math.max(1, Math.floor(this.tui.terminal.rows * 0.6) - 5))
+    const theme = recommendedSelectTheme(this.theme)
+    this.list = new SelectList(items, maxVisible, theme, {
+      minPrimaryColumnWidth: 1,
+      maxPrimaryColumnWidth: 60,
+      truncatePrimary: ({ text, maxWidth, isSelected }) => {
+        const marker = text.lastIndexOf(RECOMMENDED)
+        if (marker < 0) return truncateToWidth(text, maxWidth, '')
+        const label = text.slice(0, marker).trimEnd()
+        const suffix = text.slice(marker)
+        const suffixWidth = visibleWidth(suffix)
+        const shortened = suffixWidth >= maxWidth ? truncateToWidth(suffix, maxWidth, '') : `${truncateToWidth(label, Math.max(1, maxWidth - suffixWidth), '…')} ${suffix}`
+        if (isSelected) return shortened
+        const shortenedMarker = shortened.lastIndexOf(RECOMMENDED)
+        return shortenedMarker < 0
+          ? shortened
+          : shortened.slice(0, shortenedMarker) + this.theme.fg('warning', shortened.slice(shortenedMarker))
+      }
+    })
+    if (selectedValue) {
+      const index = items.findIndex(item => item.value === selectedValue)
+      if (index >= 0) this.list.setSelectedIndex(index)
+    }
+    this.list.onSelect = item => {
+      if (item.value === 'write') {
+        this.done({ type: 'text', selected: this.labels() })
+        return
+      }
+      if (item.value === 'submit') {
+        this.done({ type: 'answer', selected: this.labels() })
+        return
+      }
+      const displayIndex = Number(item.value.slice('option:'.length))
+      const originalIndex = this.displayOptions[displayIndex]?.index
+      if (originalIndex === undefined) return
+      if (!this.multiSelect) {
+        this.done({ type: 'answer', selected: [this.options[originalIndex]!.label] })
+        return
+      }
+      const selectedIndex = this.selectedIndexes.indexOf(originalIndex)
+      if (selectedIndex >= 0) this.selectedIndexes.splice(selectedIndex, 1)
+      else this.selectedIndexes.push(originalIndex)
+      this.rebuild()
+      this.tui.requestRender()
+    }
+    this.list.onCancel = () => this.done({ type: 'cancel' })
+  }
+
+  invalidate(): void { this.list.invalidate() }
+  handleInput(data: string): void {
+    if (/^[1-9]$/.test(data)) {
+      const index = Number(data) - 1
+      if (index >= 0 && index < this.displayOptions.length) {
+        this.list.setSelectedIndex(index)
+        this.list.handleInput('\r')
+        return
+      }
+    }
+    this.list.handleInput(data === 'j' ? '\x1b[B' : data === 'k' ? '\x1b[A' : data)
+  }
+
+  render(width: number): string[] {
+    return this.list.render(width).map(line => {
+      const bounded = truncateToWidth(line, width, '')
+      return stripTerminalSequences(line).startsWith('❯')
+        ? this.theme.bg('selectedBg', bounded + ' '.repeat(Math.max(0, width - visibleWidth(bounded))))
+        : bounded
+    })
+  }
+}
+
+export function createQuestionPicker(
+  tui: TUI,
+  theme: Theme,
+  title: string,
+  question: string | undefined,
+  options: readonly QuestionOption[],
+  multiSelect: boolean,
+  allowText: boolean,
+  selected: readonly string[],
+  done: (result: QuestionPickerResult) => void
+): DialogPanel {
+  const content = new QuestionPickerContent(tui, theme, options, multiSelect, allowText, selected, done)
+  const hint = multiSelect ? '↑/↓ select · Enter toggle · Submit choices · Esc cancel' : '↑/↓ select · Enter choose · Esc cancel'
+  const panel = new DialogPanel(title, content, () => theme, hint, question)
+  panel.maxRows = () => Math.max(3, Math.floor(tui.terminal.rows * 0.8))
+  return panel
+}

package/src/terminal/tui/questions.test.ts

@@ -1,41 +1,108 @@
-import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
+import type { ExtensionUIContext, KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent'
+import type { Component, TUI } from '@earendil-works/pi-tui'
+import { stripTerminalSequences } from '@earendil-works/pi-tui'
 import { describe, expect, it, vi } from 'vitest'
 import { answerTerminalQuestion } from './questions'
 
 function fixture() {
-  const ui = { select: vi.fn(), input: vi.fn() }
-  return { ui, context: ui as unknown as ExtensionUIContext, signal: new AbortController().signal }
+  const tui = { terminal: { rows: 24 }, requestRender: vi.fn() } as unknown as TUI
+  const theme = {
+    fg: (color: string, text: string) => color === 'warning' ? `\x1b[33m${text}\x1b[39m` : text,
+    bg: (_color: string, text: string) => text,
+    bold: (text: string) => text
+  } as unknown as Theme
+  let active: Component | undefined
+  const custom = vi.fn((factory: Parameters<ExtensionUIContext['custom']>[0]) => new Promise<unknown>((resolve) => {
+    active = factory(tui, theme, {} as KeybindingsManager, resolve) as Component
+  }))
+  const ui = { custom, input: vi.fn() }
+  return { ui, context: ui as unknown as ExtensionUIContext, signal: new AbortController().signal, getActive: () => active }
 }
 
 describe('terminal question answers', () => {
   it('keeps action-like option labels distinct from dialog actions', async () => {
-    const { ui, context, signal } = fixture()
-    ui.select.mockResolvedValue('1. Write an answer — Actual choice')
-    expect(await answerTerminalQuestion(context, { requestId: 'q', question: 'Choose?', options: [{ label: 'Write an answer', description: 'Actual choice' }] }, signal)).toEqual({ selected: ['Write an answer'] })
+    const { ui, context, signal, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, { requestId: 'q', question: 'Choose?', options: [{ label: 'Write an answer', description: 'Actual choice' }] }, signal)
+    expect(stripTerminalSequences(getActive()!.render(80).join('\n'))).toContain('1. Write an answer')
+    getActive()!.handleInput?.('\r')
+    await expect(answer).resolves.toEqual({ selected: ['Write an answer'] })
     expect(ui.input).not.toHaveBeenCalled()
   })
 
-  it('returns to choices when text entry is cancelled and retains multiple selections', async () => {
-    const { ui, context, signal } = fixture()
-    ui.select.mockResolvedValueOnce('1. A').mockResolvedValueOnce('Write an answer').mockResolvedValueOnce('Submit choices')
+  it('returns the original label when a recommended choice is selected', async () => {
+    const { context, signal, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [{ label: 'Plan A' }, { label: 'Plan B', recommended: true }], allowText: false
+    }, signal)
+    getActive()!.handleInput?.('\r')
+    await expect(answer).resolves.toEqual({ selected: ['Plan B'] })
+  })
+
+  it('keeps numeric choice shortcuts aligned with the displayed recommendation-first order', async () => {
+    const { context, signal, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [{ label: 'Plan A' }, { label: 'Plan B', recommended: true }], allowText: false
+    }, signal)
+    getActive()!.handleInput?.('2')
+    await expect(answer).resolves.toEqual({ selected: ['Plan A'] })
+  })
+
+  it('returns to choices after text entry is cancelled and retains multiple selections', async () => {
+    const { ui, context, signal, getActive } = fixture()
     ui.input.mockResolvedValue(undefined)
-    expect(await answerTerminalQuestion(context, { requestId: 'q', question: 'Choose?', options: [{ label: 'A' }], multiSelect: true }, signal)).toEqual({ selected: ['A'] })
-    expect(ui.select).toHaveBeenCalledTimes(3)
-    expect(ui.select.mock.calls[2][1]).toContain('1. ✓ A')
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [{ label: 'A' }], multiSelect: true
+    }, signal)
+    getActive()!.handleInput?.('\r')
+    getActive()!.handleInput?.('\x1b[B')
+    getActive()!.handleInput?.('\r')
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(ui.custom).toHaveBeenCalledTimes(2)
+    getActive()!.handleInput?.('\x1b[B')
+    getActive()!.handleInput?.('\x1b[B')
+    getActive()!.handleInput?.('\r')
+    await expect(answer).resolves.toEqual({ selected: ['A'] })
+  })
+
+  it('shows recommended options first with a yellow marker, without modifying the labels', async () => {
+    const controller = new AbortController()
+    const { ui, context, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Choose?', options: [
+        { label: 'Plan A' },
+        { label: 'Plan B', recommended: true },
+        { label: 'Plan C', recommended: true }
+      ], multiSelect: true
+    }, controller.signal)
+    const rendered = getActive()!.render(100).join('\n')
+    const plain = stripTerminalSequences(rendered)
+    expect(plain.indexOf('Plan B')).toBeLessThan(plain.indexOf('Plan A'))
+    expect(plain.indexOf('Plan C')).toBeLessThan(plain.indexOf('Plan A'))
+    expect(rendered).toContain('\x1b[33m(Recommended)\x1b[39m')
+    controller.abort()
+    await expect(answer).resolves.toBeUndefined()
+    expect(ui.custom).toHaveBeenCalledOnce()
   })
 
-  it('shows real batch progress and returns cancellation without inventing an answer', async () => {
+  it('shows batch progress and the full question in text entry', async () => {
     const { ui, context, signal } = fixture()
     ui.input.mockResolvedValue(undefined)
-    expect(await answerTerminalQuestion(context, { requestId: 'q', question: 'Why?', summary: 'Reason', batchId: 'batch', batchIndex: 2, batchCount: 3 }, signal)).toBeUndefined()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', question: 'Why?', summary: 'Reason', batchId: 'batch', batchIndex: 2, batchCount: 3
+    }, signal)
+    await expect(answer).resolves.toBeUndefined()
     expect(ui.input).toHaveBeenCalledWith('2 of 3 · Reason: Why?', undefined, { signal })
   })
 
-  it('honors text restrictions and ignores answers after expiry', async () => {
-    const { ui, context } = fixture()
+  it('honors text restrictions and cancels the picker when the question expires', async () => {
     const controller = new AbortController()
-    ui.select.mockImplementation(async () => { controller.abort(); return '1. A' })
-    expect(await answerTerminalQuestion(context, { requestId: 'q', options: [{ label: 'A' }], allowText: false }, controller.signal)).toBeUndefined()
-    expect(ui.select.mock.calls[0][1]).toEqual(['1. A'])
+    const { ui, context, getActive } = fixture()
+    const answer = answerTerminalQuestion(context, {
+      requestId: 'q', options: [{ label: 'A' }], allowText: false
+    }, controller.signal)
+    expect(stripTerminalSequences(getActive()!.render(80).join('\n'))).not.toContain('Write an answer')
+    controller.abort()
+    await expect(answer).resolves.toBeUndefined()
+    expect(ui.custom).toHaveBeenCalledOnce()
   })
 })

package/src/terminal/tui/questions.ts

@@ -1,11 +1,12 @@
 import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
 import type { QuestionAnswer } from '../../sessions/registry'
+import { createQuestionPicker, type QuestionPickerResult } from './questionPicker'
 
 export interface TerminalQuestion {
   requestId: string
   question?: string
   summary?: string
-  options?: { label: string; description?: string }[]
+  options?: { label: string; description?: string; recommended?: boolean }[]
   multiSelect?: boolean
   allowText?: boolean
   batchId?: string
@@ -16,32 +17,36 @@ export interface TerminalQuestion {
 /** Answers stay local until the complete group can be submitted to the registry. */
 export async function answerTerminalQuestion(ui: ExtensionUIContext, request: TerminalQuestion, signal: AbortSignal): Promise<QuestionAnswer | undefined> {
   const choices = request.options ?? []
-  const selected: string[] = []
   const progress = request.batchId ? `${request.batchIndex} of ${request.batchCount} · ` : ''
-  const title = `${progress}${request.summary ? request.summary + ': ' : ''}${request.question ?? 'Question'}`
+  const title = `${progress}${request.summary ?? 'Question'}`
+  const inputTitle = `${progress}${request.summary ? `${request.summary}: ` : ''}${request.question ?? 'Question'}`
   if (!choices.length) {
-    if (request.allowText === false) return { selected }
-    const text = await ui.input(title, undefined, { signal })
-    return text === undefined || signal.aborted ? undefined : { selected, text }
+    if (request.allowText === false) return { selected: [] }
+    const text = await ui.input(inputTitle, undefined, { signal })
+    return text === undefined || signal.aborted ? undefined : { selected: [], text }
   }
+  let selected: string[] = []
   while (!signal.aborted) {
-    const labels = choices.map((option, index) => `${index + 1}. ${selected.includes(option.label) ? '✓ ' : ''}${option.label}${option.description ? ' — ' + option.description : ''}`)
-    const menu = [...labels, ...(request.allowText !== false ? ['Write an answer'] : []), ...(request.multiSelect ? ['Submit choices'] : [])]
-    const choice = await ui.select(title, menu, { signal })
-    if (choice === undefined || signal.aborted) return undefined
-    if (choice === 'Submit choices') return { selected }
-    if (choice === 'Write an answer') {
-      const text = await ui.input(title, undefined, { signal })
-      if (signal.aborted) return undefined
-      if (text !== undefined) return { selected, text }
-      continue
+    let cancelPicker = () => {}
+    const onAbort = () => cancelPicker()
+    signal.addEventListener('abort', onAbort, { once: true })
+    const picker = ui.custom<QuestionPickerResult>((tui, theme, _keybindings, done) => {
+      cancelPicker = () => done({ type: 'cancel' })
+      if (signal.aborted) cancelPicker()
+      return createQuestionPicker(tui, theme, title, request.question, choices, request.multiSelect === true, request.allowText !== false, selected, done)
+    })
+    let result: QuestionPickerResult | undefined
+    try {
+      result = await picker
+    } finally {
+      signal.removeEventListener('abort', onAbort)
     }
-    const index = labels.indexOf(choice)
-    if (index < 0) throw new Error('Choose one of the displayed answers.')
-    const label = choices[index]!.label
-    if (selected.includes(label)) selected.splice(selected.indexOf(label), 1)
-    else selected.push(label)
-    if (!request.multiSelect) return { selected }
+    if (!result || result.type === 'cancel' || signal.aborted) return undefined
+    selected = result.selected
+    if (result.type === 'answer') return { selected }
+    const text = await ui.input(inputTitle, undefined, { signal })
+    if (signal.aborted) return undefined
+    if (text !== undefined) return { selected, text }
   }
   return undefined
 }

package/src/terminal/tui/runtime.ts

@@ -11,6 +11,7 @@ import terminalExtension, { type TerminalPlanRunState } from '../piExtension'
 import { planModeTools } from './planMode'
 import { claimTerminalControl, controlCall } from '../control'
 import { loadPiAdapter } from './piAdapter'
+import { loadPi } from '../../pi/runtime'
 import type { SessionAccount } from '../accountsMenu'
 import type { QuestionAnswer } from '../../sessions/registry'
 import type { TerminalQuestion } from './questions'
@@ -174,6 +175,7 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
     assertTerminalSessionScope(resume, cwd)
   }
 
+  await loadPi()
   // Claim before loading any plugin code and retain it in the trusted process across reloads.
   await claimTerminalControl()
   const identity = await controlCall<SessionAccount>('accounts.session').catch(() => null)

package/src/tools/askUser.test.ts

@@ -1,3 +1,4 @@
+import { Type } from 'typebox'
 import { expect, test } from 'vitest'
 
 import type { ActiveRun, QuestionInput } from '../sessions/registry'
@@ -16,24 +17,43 @@ test('ask_user requests one to five summarized questions and returns answers in
   } as unknown as ActiveRun)
 
   const response = await tool.execute({ questions: [
-    { summary: 'Navigation style', question: 'Which navigation?', options: [{ label: 'Keyboard', description: 'Move through controls with keys.' }, { label: 'Pointer', description: 'Select controls with a mouse or trackpad.' }], multiSelect: true },
+    { summary: 'Navigation style', question: 'Which navigation?', options: [{ label: 'Keyboard', description: 'Move through controls with keys.', recommended: true }, { label: 'Pointer', description: 'Select controls with a mouse or trackpad.', recommended: true }], multiSelect: true },
     { summary: 'Delivery timing', question: 'When?', options: [{ label: 'Today', description: 'Start immediately.' }, { label: 'Next week', description: 'Start after the current week.' }], allowText: true }
   ] })
 
   expect(requested).toMatchObject([
-    { summary: 'Navigation style', question: 'Which navigation?', multiSelect: true, allowText: true },
+    { summary: 'Navigation style', question: 'Which navigation?', options: [{ label: 'Keyboard', recommended: true }, { label: 'Pointer', recommended: true }], multiSelect: true, allowText: true },
     { summary: 'Delivery timing', question: 'When?', multiSelect: false, allowText: true }
   ])
   expect(response).toContain('Navigation style: The user chose: Keyboard. Their note for Keyboard: Keep it accessible.')
   expect(response).toContain('Delivery timing: The user answered: Next week')
 })
 
+test('ask_user exposes optional recommendation metadata in its option schema', () => {
+  const tool = askUserTool({ requestAnswers: async () => [] } as unknown as ActiveRun)
+  const schema = tool.parameters(Type) as any
+  const option = schema.properties.questions.items.properties.options.items
+  expect(option.properties.recommended).toMatchObject({ type: 'boolean' })
+  expect(option.required).not.toContain('recommended')
+})
+
 test('ask_user rejects empty questions and summaries', async () => {
   const tool = askUserTool({ requestAnswers: async () => [] } as unknown as ActiveRun)
   await expect(tool.execute({ questions: [] })).resolves.toBe('Ask between one and five questions.')
   await expect(tool.execute({ questions: [{ summary: '', question: 'Pick one' }] })).resolves.toBe('Each question needs a short summary of no more than 100 characters.')
 })
 
+test('ask_user rejects multiple recommendations on a single-choice question', async () => {
+  let requested = false
+  const tool = askUserTool({ requestAnswers: async () => { requested = true; return [] } } as unknown as ActiveRun)
+  await expect(tool.execute({ questions: [{
+    summary: 'Plan choice',
+    question: 'Which plan?',
+    options: [{ label: 'Plan A', description: 'First plan.', recommended: true }, { label: 'Plan B', description: 'Second plan.', recommended: true }]
+  }] })).resolves.toBe('A single-choice question may recommend at most one option.')
+  expect(requested).toBe(false)
+})
+
 test('ask_user requires a description for every choice', async () => {
   let requested = false
   const tool = askUserTool({ requestAnswers: async () => { requested = true; return [] } } as unknown as ActiveRun)
@@ -62,6 +82,7 @@ test('ask_user treats 25 words as guidance for questions and choice descriptions
   expect(response).toContain('Reply detail: The user chose: Detailed.')
   expect(tool.description).toContain('aim to keep each question to 25 words or fewer')
   expect(tool.description).toContain('every option must include a helpful description of 25 words or fewer')
+  expect(tool.description).toContain('recommended: true')
 })
 
 test('describeAnswer includes choice-specific notes', () => {

package/src/tools/askUser.ts

@@ -22,7 +22,7 @@ export function askUserTool(run: Pick<ActiveRun, 'requestAnswers'>): ToolSpec {
     label: 'Ask the user',
     description:
       'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 2–3 word summary and aim to keep each question to 25 words or fewer. ' +
-      'Offer up to 6 short options when the choices are clear; every option must include a helpful description of 25 words or fewer. Every question includes a free-text “Something else” answer. Set multiSelect when several can apply. Use it when you need a decision, not for small talk.',
+      'Offer up to 6 short options when the choices are clear; every option must include a helpful description of 25 words or fewer. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark a recommended option with recommended: true instead of changing its label; mark at most one for a single-choice question, or several when multiSelect is true. Every question includes a free-text “Something else” answer. Set multiSelect when several can apply. Use it when you need a decision, not for small talk.',
     parameters: (Type) =>
       Type.Object({
         questions: Type.Array(Type.Object({
@@ -30,8 +30,9 @@ export function askUserTool(run: Pick<ActiveRun, 'requestAnswers'>): ToolSpec {
           question: Type.String({ description: 'A clear, standalone question; aim for 25 words or fewer' }),
           options: Type.Optional(
             Type.Array(Type.Object({
-              label: Type.String({ description: 'A short choice' }),
-              description: Type.String({ description: 'Required. Briefly explain this choice in 25 words or fewer.' })
+              label: Type.String({ description: 'A short choice; do not add a recommendation suffix to the label' }),
+              description: Type.String({ description: 'Required. Briefly explain this choice in 25 words or fewer.' }),
+              recommended: Type.Optional(Type.Boolean({ description: 'Whether to show this choice as a visual recommendation; it is not preselected, and answers use the original label' }))
             }), { maxItems: MAX_OPTIONS })
           ),
           multiSelect: Type.Optional(Type.Boolean())
@@ -44,13 +45,22 @@ export function askUserTool(run: Pick<ActiveRun, 'requestAnswers'>): ToolSpec {
         const summary = text(item.summary)
         const question = text(item.question)
         const options = (Array.isArray(item.options) ? item.options : [])
-          .map((option) => ({ label: text((option as { label?: unknown }).label), description: text((option as { description?: unknown }).description) }))
+          .map((option) => {
+            const choice = option as { label?: unknown; description?: unknown; recommended?: unknown }
+            return {
+              label: text(choice.label),
+              description: text(choice.description),
+              ...(choice.recommended === true ? { recommended: true } : {})
+            }
+          })
           .filter((option) => option.label)
           .slice(0, MAX_OPTIONS)
-        return { summary, question, options, multiSelect: options.length > 1 && item.multiSelect === true, allowText: true }
+        const multiSelect = options.length > 1 && item.multiSelect === true
+        return { summary, question, options, multiSelect, allowText: true }
       })
       if (questions.some((question) => !question.summary || question.summary.length > 100)) return 'Each question needs a short summary of no more than 100 characters.'
       if (questions.some((question) => !question.question)) return 'Every question needs a question sentence.'
+      if (questions.some((question) => !question.multiSelect && question.options.filter((option) => option.recommended).length > 1)) return 'A single-choice question may recommend at most one option.'
       if (questions.some((question) => question.options.some((option) => !option.description))) return 'Every choice needs a short description. Aim for 25 words or fewer.'
       const answers = await run.requestAnswers(questions)
       return questions.map((question, index) => `${question.summary}: ${describeAnswer(answers[index])}`).join('\n')