feat(user-interaction): declare a plan-review presentation intent on questions

A question may now carry `intent`, a tagged declaration that it IS a decision
of a known shape, so a UI that recognises the tag can present it as such
instead of as a generic option list. The one member is
`{ kind: 'plan-review', approve }`, which plan-mode sets on the exit_plan_mode
review.

An intent shapes presentation only: a UI honouring it answers with the same
option labels a generic UI would send, so the tool reads one answer shape
either way, and a UI that does not know the tag renders the generic flow.
`approve` names the affirmative option rather than relying on option order;
since no type can tie that label to the question's own option list, `ask()`
rejects a mismatch as BAD_INTENT, and the wire schema rejects an unknown tag
outright rather than silently rendering generic.

plan-mode also stops reporting a dismissed review as "the user cancelled
ask_user_question" — a tool it never called. A dismissal now tells the model
the user took the turn back to speak, and to stay in plan mode and wait; every
other ask failure keeps its own message.

packages/ui/user-interaction/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/user-interaction/README.md
-README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32
-README.zh.md: c89210b6955a661313ca9e0e82e43da5a4d1db79
+README.md: f134e912149190efb81ea9f64c5d63632ce8c626
+README.zh.md: ab6432dcbddc36d3ef9ca957b3901cb76257539a

packages/ui/user-interaction/README.md

@@ -13,14 +13,19 @@ Abstract user-interaction seam. It owns `ctx.userInteraction`, the service a mod
 
 ### Key Types
 
-- `AskUserQuestionRequest` — `{ questions: [{ id, question, detail?, header?, options?, multiSelect? }], agent?, signal? }`; `detail` supplies supporting text that providers render with the question without turning it into an option label.
+- `AskUserQuestionRequest` — `{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`; `detail` supplies supporting text that providers render with the question without turning it into an option label.
 - `AskUserQuestionOption` — `{ label, description? }`.
+- `AskUserQuestionIntent` — `{ kind: 'plan-review', approve }`; the tagged presentation intent below.
 - `AskUserQuestionAnswer` — `{ answers: [{ id, selected, custom? }] }`.
 - `UserInteractionProvider` — UI implementation with `ask(request)`.
-- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`.
+- `UserInteractionError` — `HarnessError` subclass with codes such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `DUPLICATE_PROVIDER`, and `ASK_ABORTED`.
 
 When an answer includes `custom`, `selected` is empty; custom text is an override rather than a supplement to selected choices. A UI may preserve a skipped item as `{ id, selected: [] }`, keeping the existing answer shape while retaining other answers in the batch.
 
+### Presentation intent
+
+`intent` declares that a question IS a decision of a known shape, so a UI that recognises the tag may present it as such — `plan-review` says `detail` is a plan under review, and `dsh-plan-mode` sets it on the `exit_plan_mode` question. An intent shapes presentation only: a UI honouring it answers with the same option labels a generic UI would send, and a UI that does not know the tag renders the generic option list, so callers read one answer shape either way. `approve` names the label that approves rather than relying on option order; `ask()` rejects an intent whose `approve` names none of that question's own options with `BAD_INTENT`, since no type can tie the two together.
+
 ## Role
 
 This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-tool-ask-user` depend on this seam; `dsh-tui` and the host runtime provide interactive implementations. The loop stays unchanged: a tool call awaits a promise, and the tool result resumes the normal agent loop.

packages/ui/user-interaction/README.zh.md

@@ -13,14 +13,19 @@
 
 ### 关键类型
 
-- `AskUserQuestionRequest`：`{ questions: [{ id, question, detail?, header?, options?, multiSelect? }], agent?, signal? }`；`detail` 提供辅助文本，提供方会将其随问题一起渲染，而不会将其变成选项标签。
+- `AskUserQuestionRequest`：`{ questions: [{ id, question, detail?, header?, options?, multiSelect?, intent? }], agent?, signal? }`；`detail` 提供辅助文本，提供方会将其随问题一起渲染，而不会将其变成选项标签。
 - `AskUserQuestionOption`：`{ label, description? }`。
+- `AskUserQuestionIntent`：`{ kind: 'plan-review', approve }`；即下文的带标签呈现意图。
 - `AskUserQuestionAnswer`：`{ answers: [{ id, selected, custom? }] }`。
 - `UserInteractionProvider`：包含 `ask(request)` 的 UI 实现。
-- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`NO_PROVIDER`、`DUPLICATE_PROVIDER` 和 `ASK_ABORTED` 等代码。
+- `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`DUPLICATE_PROVIDER` 和 `ASK_ABORTED` 等代码。
 
 当回答包含 `custom` 时，`selected` 为空；自定义文本是所选选项的替代，而不是补充。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。
 
+### 呈现意图
+
+`intent` 声明某个问题本身就是一次已知形状的决定，因此认识该标签的 UI 可以照此呈现 —— `plan-review` 表示 `detail` 是一份待审阅的计划，`dsh-plan-mode` 会在 `exit_plan_mode` 的问题上设置它。意图只塑造呈现：遵循它的 UI 回答的仍是通用 UI 会发送的那些选项标签，不认识该标签的 UI 渲染通用选项列表，因此调用方两种情况下读到的都是同一种回答形态。`approve` 指名表示批准的标签，而不依赖选项顺序；由于没有类型能把两者绑定起来，`ask()` 会以 `BAD_INTENT` 拒绝 `approve` 未命中该问题自身任一选项的意图。
+
 ## 职责
 
 这是接口包（package）。`@deepseek-ai/dsh-tool-ask-user` 等面向模型的消费方依赖此 seam；`dsh-tui` 和宿主运行时提供交互式实现。循环保持不变：工具调用等待 Promise，工具结果随后恢复正常的 agent loop（智能体循环）。

packages/ui/user-interaction/src/index.ts

@@ -20,7 +20,8 @@ declare module 'cordis' {
 import type { AskUserQuestionAnswer, AskUserQuestionItem } from './types.ts'
 
 export type {
-  AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionOption,
+  AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionIntent, AskUserQuestionItem,
+  AskUserQuestionOption,
 } from './types.ts'
 
 /** Request for a human answer. */
@@ -86,6 +87,20 @@ export class UserInteractionService extends Service {
     if (request.questions.length === 0) {
       throw new UserInteractionError('ask_user_question requires at least one question', 'EMPTY_QUESTIONS')
     }
+    // A presentation intent names an option label the types cannot pin to its
+    // own question's option list. A UI honouring the intent answers with that
+    // label, so a name matching nothing would answer a choice the asker never
+    // offered — caught here, at the asker, rather than in a UI.
+    for (const question of request.questions) {
+      const intent = question.intent
+      if (intent === undefined) continue
+      if (!(question.options ?? []).some(option => option.label === intent.approve)) {
+        throw new UserInteractionError(
+          `question ${question.id} declares intent ${intent.kind} whose approve label `
+          + `${JSON.stringify(intent.approve)} names none of its options`,
+          'BAD_INTENT')
+      }
+    }
     if (this.provider === undefined) {
       throw new UserInteractionError('no user-interaction provider is registered', 'NO_PROVIDER')
     }

packages/ui/user-interaction/src/types.ts

@@ -13,6 +13,24 @@ export interface AskUserQuestionOption {
   description?: string
 }
 
+/**
+ * A caller-declared presentation intent: the question IS a decision of this
+ * shape, so a UI that recognises the tag may present it as such instead of as a
+ * generic option list. Tagged so further intents can be added; a UI that does
+ * not know a tag renders the generic flow, and the answer encoding is identical
+ * either way — an intent shapes presentation only, never the protocol.
+ */
+export type AskUserQuestionIntent = {
+  /** A plan submitted for review: `detail` is the plan markdown, and the decision approves or declines it. */
+  kind: 'plan-review'
+  /**
+   * The option label that approves the plan; every other option declines it.
+   * Named rather than positional so no UI infers the verdict from option order.
+   * An `approve` naming no option of its own question is rejected at `ask()`.
+   */
+  approve: string
+}
+
 /** One question in a user-interaction request. */
 export interface AskUserQuestionItem {
   /** Stable caller-provided question id, echoed in the answer. */
@@ -27,6 +45,8 @@ export interface AskUserQuestionItem {
   options?: AskUserQuestionOption[]
   /** Whether more than one option may be selected. Defaults to single-select. */
   multiSelect?: boolean
+  /** Optional presentation intent for capable UIs; absent asks for the generic option list. */
+  intent?: AskUserQuestionIntent
 }
 
 /** Answer to one question. */

packages/ui/user-interaction/tests/user-interaction.spec.ts

@@ -83,4 +83,45 @@ describe('UserInteractionService', () => {
       .rejects.toMatchObject({ name: 'UserInteractionError', code: 'EMPTY_QUESTIONS' })
     expect(p.ask).not.toHaveBeenCalled()
   })
+
+  it('rejects an intent whose approve label names none of its own options', async () => {
+    const ctx = new Context()
+    await ctx.plugin(UserInteractionService)
+    const p = { ask: vi.fn(async () => ({ answers: [] })) }
+    ctx.userInteraction.registerProvider(p)
+    const question = { id: 'plan-review', question: 'Approve?', detail: '# Plan' }
+
+    // A wrong label among offered options, and no options offered at all.
+    for (const options of [[{ label: 'Approve' }], undefined]) {
+      await expect(ctx.userInteraction.ask({
+        questions: [{
+          ...question,
+          ...(options === undefined ? {} : { options }),
+          intent: { kind: 'plan-review', approve: 'Ship it' },
+        }],
+      })).rejects.toMatchObject({ name: 'UserInteractionError', code: 'BAD_INTENT' })
+    }
+    expect(p.ask).not.toHaveBeenCalled()
+  })
+
+  it('passes an intent through once its approve label names an offered option', async () => {
+    const ctx = new Context()
+    await ctx.plugin(UserInteractionService)
+    const p = provider('Approve')
+    ctx.userInteraction.registerProvider(p)
+    const intent = { kind: 'plan-review', approve: 'Approve' } as const
+
+    const result = await ctx.userInteraction.ask({
+      questions: [
+        { id: 'plain', question: 'Proceed?' },
+        {
+          id: 'plan-review', question: 'Approve?', detail: '# Plan',
+          options: [{ label: 'Approve' }, { label: 'Keep planning' }], intent,
+        },
+      ],
+    })
+
+    expect(result.answers).toEqual([{ id: 'plain', selected: ['Approve'] }])
+    expect(p.seen[0]?.questions[1]?.intent).toEqual(intent)
+  })
 })