dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/site/en/reference/subsystems/user-questions.md

@@ -1,311 +1,330 @@
----
-editSource: "docs/subsystems/user-questions.md"
-rawMarkdownPath: "en/reference/subsystems/user-questions.md"
-outline: [2,3]
----
-
-# User Interaction
-
-The user-questions seam of [dsh-user-questions](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/interaction/user-questions). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. Agent-scoped waterfall listeners compose the available UI surfaces, including listeners relayed to a connected client.
-
-Source: [`packages/interaction/user-questions/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/index.ts)
-
-## Question options
-
-`AskUserQuestionOption` contains one selectable choice. `label` is the user-facing option text and also the model-facing selected value; `description` is optional UI help text.
-
-```ts type-equiv
-/** One selectable answer offered to the user. */
-interface AskUserQuestionOption {
-  /** User-facing label. */
-  label: string
-  /** Optional extra context rendered by capable UIs. */
-  description?: string
-}
-```
-
-## Presentation intent
-
-`AskUserQuestionIntent` optionally declares a known decision kind. It is tagged on `kind` so intents can be added; a UI that does not recognise a tag renders the generic option list. An intent changes presentation only — a UI honouring it answers with the same option labels a generic UI would send, so the caller reads the same answer fields either way. `approve` names the affirmative option instead of relying on option order. `ask()` rejects the two assertions no type can carry: an `approve` naming none of its own question's options, and an intent on a question with no `detail`.
-
-```ts type-equiv
-/**
- * A caller-declared presentation intent: the question IS this kind of
- * decision, 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 changes presentation only, never the protocol.
- */
-type AskUserQuestionIntent = {
-  /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, 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
-  /** Logged tool invocation whose arguments contain the reviewed plan. */
-  callId?: ToolCallId
-}
-```
-
-## Question item
-
-`AskUserQuestionItem` is one question in a request. The caller supplies a stable `id`, which is echoed back with the answer so batched questions remain routable. Optional `detail` carries supporting text that providers render with the question but keep out of selectable option labels.
-
-```ts type-equiv
-/** One question in a user-questions request. */
-interface AskUserQuestionItem {
-  /** Stable caller-provided question id, echoed in the answer. */
-  id: string
-  /** The question to display. */
-  question: string
-  /** Optional supporting detail rendered with the question but kept out of option labels. */
-  detail?: string
-  /** Optional short heading/group label. */
-  header?: string
-  /** Optional choices the UI can render as a menu. */
-  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
-}
-```
-
-## Ask request
-
-`AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer. When present, `agent` is the exact live caller; the interaction seam admits it only while the live registry identifies that instance as a runtime root.
-
-```ts type-equiv
-/** Request for a human answer. */
-interface AskUserQuestionRequest extends AskUserQuestionRequestEvent {}
-```
-
-## Answer
-
-Providers return one answer item per question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. For a single-select question, `custom` overrides the selected choice and `selected` is empty. For a multi-select question, `custom` may supplement the labels in `selected`. A UI may also use an item with empty `selected` and no `custom` to preserve a skipped question in an otherwise completed batch.
-
-```ts type-equiv
-/** Answer to one question. */
-interface AskUserQuestionAnswerItem {
-  /** The answered question id. */
-  id: string
-  /** Selected option labels. May accompany custom text for a multi-select question. */
-  selected: string[]
-  /** Optional free-text "Other" answer. */
-  custom?: string
-}
-```
-
-```ts type-equiv
-/** The human's answer. */
-interface AskUserQuestionAnswer {
-  /** Structured answers keyed by question id. */
-  answers: AskUserQuestionAnswerItem[]
-}
-```
-
-Timed answerers receive `wait: { callId, timed: true }`. The call id identifies the card and the foreground wait. The Client calls `attachWait` to claim the wait and obtain its remaining duration; transport forwards the original event without inspecting or rewriting these fields. A `wait` without `timed` identifies an indefinite card-keyed request. An absent `wait` identifies a blocking request without a card key.
-
-```ts type-equiv
-/** Client-safe payload declared for the user-question answerer waterfall. */
-interface AskUserQuestionRequestEvent {
-  /** Questions to display. */
-  questions: AskUserQuestionItem[]
-  /** Agent identity projected to the corresponding Client Context in transit. */
-  agent?: Agent
-  /** Cancellation lifetime of the pending request. */
-  signal?: AbortSignal
-  /**
-   * Tool call the Client card is keyed by. Timed answerers attach to the
-   * business wait stream before starting their local countdown.
-   */
-  wait?: {
-    /** Tool call the Client card is keyed by. */
-    callId: ToolCallId
-    /** True for a foreground wait that requires a Client claim; absent for indefinite waits. */
-    timed?: boolean
-  }
-}
-```
-
-## Timed questions and late replies
-
-A timed question waits for a bounded foreground window and then lets the agent continue independent work. If the user answers inside the window, the tool returns the answer batch; otherwise `TimedUserQuestionResult` is `{ pending: true, callId }`. Pending means the question is still answerable; it is not an empty answer, a refusal, a confirmation, or permission.
-
-```ts type-equiv
-/** Timed ask result returned when the foreground answer window closes. */
-type TimedUserQuestionResult = AskUserQuestionAnswer | { pending: true; callId: ToolCallId }
-```
-
-A Client claim is a business Remote stream, not a Gateway delivery. `TimedQuestionWait` holds the original Host deadline and runs its timer only while no claim exists. Its `attachWait` stream yields the current remaining duration, and the Client counts down with its own clock. Focus, editing, and Take time stay local. Stream cancellation releases that claim; after the last claim leaves, the Host resumes the original deadline. An unattended timeout aborts the foreground waterfall's private signal and returns pending without cancelling the Turn. Gateway and `api-remotes` contain no question-specific timing policy.
-
-The `userQuestions` Session projection folds existing events into the answerable question set and the settled one; no wait state, focus state, or deadline is logged. Each `request/header` records the exact tool schemas the model saw. Native calls are tracked only when that header declares the timed `ask_user_question` schema with a `timeout` parameter; the blocking legacy tool never declares it. A native `tool/call` opens a question. A `tool/result` marks it `continued` only when it carries the pending payload or is the synthetic `TOOL_OUTCOME_UNKNOWN` result Session resume repair appends; an answer batch moves it into `settled` with that batch, and any failure drops it. A `run_code` PTC sub-call enters the projection when its `tool/ptc-dispatch` result is pending, even though the request header exposes only `run_code`. A late reply moves a continued question into `settled` when its message is admitted as `user/message`, together with the answer batch read out of that message: the timed call's own result recorded the timeout, so a transcript row has nowhere else to read what the user finally chose. A queued reply can be canceled before admission and leaves the question answerable. A reply whose text carries no readable batch settles the call with no answers; one naming a call that is not active changes nothing.
-
-```ts type-equiv
-/** `open` while the tool call may still return the answer; `continued` once the answer can only arrive as a new turn. */
-type UserQuestionState = 'open' | 'continued'
-```
-
-```ts type-equiv
-/** One unanswered timed `ask_user_question` call reconstructed from the Session log. */
-interface PendingUserQuestion {
-  readonly callId: ToolCallId
-  readonly questions: readonly AskUserQuestionItem[]
-  readonly state: UserQuestionState
-}
-```
-
-```ts type-equiv
-/**
- * One timed `ask_user_question` call and the answers it settled with: the
- * batch its own result carried when the user answered inside the window,
- * otherwise the batch its late reply carried, because that call's own result
- * recorded the timeout. A transcript row reads what the user finally answered
- * from here, and only a call listed here was a timed one.
- */
-interface SettledUserQuestion {
-  /** The settled call. */
-  readonly callId: ToolCallId
-  /** The recorded batch, one entry per question; empty when the late reply carried none. */
-  readonly answers: readonly AskUserQuestionAnswerItem[]
-}
-```
-
-```ts type-equiv
-/**
- * Both halves of one Session's timed `ask_user_question` state, as every
- * Client reads them. A call made while the blocking legacy tool was in
- * effect appears in neither half.
- */
-interface UserQuestionProjectionView {
-  /** Calls that can still take an answer, in ask order. */
-  readonly active: readonly PendingUserQuestion[]
-  /** Calls an answer settled, in settlement order. */
-  readonly settled: readonly SettledUserQuestion[]
-}
-```
-
-An open question accepts answers only through the waterfall. Once it is `continued`, the `answer` Remote method queues a user message for the owning agent and wakes it if idle. The message has source `user-question-reply`, outcome `answered`, and an `answer_to_pending_question` payload. The method returns `false` for an open or unknown call, rejects a second queued reply with `REPLY_QUEUED` even after a Host restart, and rejects incomplete or duplicate answer batches with `BAD_ANSWER`.
-
-Closing the Client panel sends nothing. A foreground timeout ends only the tool wait. Continued questions have no deadline; they stay answerable until a reply is admitted.
-
-After a Host restart, the Remote layer resumes the root agent when the Session reopens. A late reply then enters a new turn.
-
-## Errors
-
-`UserQuestionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `ASK_ABORTED`, or UI-side cancellation.
-
-```ts type-equiv
-/** Stable error taxonomy for user-questions failures. */
-class UserQuestionError extends HarnessError {
-  constructor(message: string, code: string, options?: ErrorOptions) {
-    super(message, code, options)
-    this.name = 'UserQuestionError'
-  }
-}
-```
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxuserquestions--userquestionservice"></a>
-
-### `ctx.userQuestions` — `UserQuestionService`
-
-`ctx.userQuestions`: validation plus the scoped answerer waterfall.
-
-```ts cordis-catalog
-/**
- * Answer a continued question. The reply is steered into the agent as a
- * user message whose source names the call; that message is also the
- * record that closes the question in the projection.
- * @param agent - Live root agent for the owning Session.
- * @param callId - Continued question identity.
- * @param answer - Complete structured answer batch, one item per question of the call.
- * @returns Whether the question is still continued; an accepted reply stays
- *   queued until the agent admits its user message.
- * @throws {UserQuestionError} `BAD_ANSWER` when the batch does not name each
- *   question of the call exactly once, or `REPLY_QUEUED` when a reply is
- *   already waiting for admission.
- */
-@Remote answer(agent: Agent, callId: ToolCallId, answer: AskUserQuestionAnswer): boolean
-
-/**
- * Let one answer UI hold a live timed wait. Closing the stream releases its claim.
- * @param agent - Live root agent owning the question.
- * @param callId - Foreground tool call to attach to.
- * @param signal - Remote stream cancellation, including Client disconnect.
- * @returns One Host-computed remaining duration, or no frames once the wait ended.
- */
-@Remote({ mode: 'stream' }) async *attachWait(agent: Agent, callId: ToolCallId, signal: AbortSignal): AsyncIterable<{ remainingMs: number }>
-
-/**
- * Foreground wait whose first settlement the Client decides: the Client
- * rejects with `ASK_TIMED_OUT` when its countdown ends, and this method maps
- * that code to the pending result.
- * @param request - Questions, live owner agent, and abort signal.
- * @param callId - Tool call identity the Client card is keyed by.
- * @param timeoutMs - Positive foreground wait in milliseconds.
- * @returns The answer when it arrives inside the window, otherwise a pending
- *   result, also when no connected Client claimed the request by the deadline.
- * @throws {UserQuestionError} `BAD_TIMEOUT` for a non-integer, non-positive,
- *   or oversized wait.
- */
-async askTimed( request: AskUserQuestionRequest & { agent: Agent }, callId: ToolCallId, timeoutMs: number, ): Promise<TimedUserQuestionResult>
-
-/**
- * Ask the scoped answerer waterfall and wait for the user's answer.
- *
- * When a caller supplies an agent, human interaction is valid only for the
- * exact live runtime root. Runtime ownership, not durable session lineage,
- * decides this boundary: an owned child has no human answerer and would
- * block forever, while a lineage-bearing session resumed as a new runtime
- * root may ask normally.
- *
- * @param request Questions, owner agent, and abort signal.
- * @returns The answer chosen or typed by the human.
- * @throws {UserQuestionError} code `ASK_ABORTED` when the supplied signal
- *   is already or becomes aborted, `CALLER_NOT_LIVE` when a supplied agent
- *   is not the registry's exact live instance, or `DELEGATED_CALLER` when
- *   that live agent is owned by another agent.
- */
-async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
-```
-
-Types: [Agent](./core.md) · [ToolCallId](./core.md)
-
-Source: [`packages/interaction/user-questions/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/index.ts)
-
-<a id="user-questions-events"></a>
-
-### `user-questions/*` events
-
-<a id="user-questionsrequest--waterfall"></a>
-
-#### `user-questions/request` — waterfall
-
-Ask composed answerers for structured user input. Return an answer to claim the request or call `next()` to delegate. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-
-```ts cordis-catalog
-/**
- * Ask composed answerers for structured user input. Return an answer to
- * claim the request or call `next()` to delegate. Scope-filtered dispatch
- * (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param request - pending user-question request.
- * @mode waterfall
- */
-'user-questions/request'( this: Scoped<Agent>, request: AskUserQuestionRequestEvent, next: () => Promise<AskUserQuestionAnswer>, ): Promise<AskUserQuestionAnswer>
-```
-
-Types: [Agent](./core.md) · [Scoped](./scope.md)
-
-Source: [`packages/interaction/user-questions/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/types.ts)
-<!-- END GENERATED cordis-surface -->
+---
+editSource: "docs/subsystems/user-questions.md"
+rawMarkdownPath: "en/reference/subsystems/user-questions.md"
+outline: [2,3]
+---
+
+# User Interaction
+
+The user-questions seam of [dsh-user-questions](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/interaction/user-questions). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. Agent-scoped waterfall listeners compose the available UI surfaces, including listeners relayed to a connected client.
+
+Source: [`packages/interaction/user-questions/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/index.ts)
+
+## Question options
+
+`AskUserQuestionOption` contains one selectable choice. `label` is the user-facing option text and also the model-facing selected value; `description` is optional UI help text.
+
+```ts type-equiv
+/** One selectable answer offered to the user. */
+interface AskUserQuestionOption {
+  /** User-facing label. */
+  label: string
+  /** Optional extra context rendered by capable UIs. */
+  description?: string
+}
+```
+
+## Presentation intent
+
+`AskUserQuestionIntent` changes presentation while preserving option labels and the caller’s decision policy. `plan-review` names the approve option and requires plan detail. `approval` requires one blocking question with detail and distinct reject, approve and optional always-allow labels covering exactly the offered options. It rejects multi-select and timed waits. The CUA frontend renders its fixed approvals through the existing composer chain; ordinary questions and plan review keep their existing renderers.
+
+```ts type-equiv
+/**
+ * A caller-declared presentation intent: the question IS this kind of
+ * decision, 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 changes presentation only, never the protocol.
+ */
+type AskUserQuestionIntent = {
+  /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, 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
+  /** Logged tool invocation whose arguments contain the reviewed plan. */
+  callId?: ToolCallId
+} | {
+  /** A blocking permission decision with fixed actions and no free-text answer. */
+  kind: 'approval'
+  /** Option label granting the scope described by the caller. */
+  approve: string
+  /** Option label refusing the requested access. */
+  reject: string
+  /** Optional persistent grant offered only when the caller supports it. */
+  always?: string
+  /** Metadata for human recognition; the caller admits icon sources, which the UI may load as URLs. Never an authorization identity. */
+  subject?: { name: string; icon?: string }
+  /** Localized question and limited-grant label; fixed cards own reject/always wording. Option labels remain answer values. */
+  display?: {
+    question: { en: string; [locale: string]: string }
+    detail?: { en: string; [locale: string]: string }
+    approve?: { en: string; [locale: string]: string }
+  }
+}
+```
+
+## Question item
+
+`AskUserQuestionItem` is one question in a request. The caller supplies a stable `id`, which is echoed back with the answer so batched questions remain routable. Optional `detail` carries supporting text that providers render with the question but keep out of selectable option labels.
+
+```ts type-equiv
+/** One question in a user-questions request. */
+interface AskUserQuestionItem {
+  /** Stable caller-provided question id, echoed in the answer. */
+  id: string
+  /** The question to display. */
+  question: string
+  /** Optional supporting detail rendered with the question but kept out of option labels. */
+  detail?: string
+  /** Optional short heading/group label. */
+  header?: string
+  /** Optional choices the UI can render as a menu. */
+  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
+}
+```
+
+## Ask request
+
+`AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer. When present, `agent` is the exact live caller; the interaction seam admits it only while the live registry identifies that instance as a runtime root.
+
+```ts type-equiv
+/** Request for a human answer. */
+interface AskUserQuestionRequest extends AskUserQuestionRequestEvent {}
+```
+
+## Answer
+
+Providers return one answer item per question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. For a single-select question, `custom` overrides the selected choice and `selected` is empty. For a multi-select question, `custom` may supplement the labels in `selected`. A UI may also use an item with empty `selected` and no `custom` to preserve a skipped question in an otherwise completed batch.
+
+```ts type-equiv
+/** Answer to one question. */
+interface AskUserQuestionAnswerItem {
+  /** The answered question id. */
+  id: string
+  /** Selected option labels. May accompany custom text for a multi-select question. */
+  selected: string[]
+  /** Optional free-text "Other" answer. */
+  custom?: string
+}
+```
+
+```ts type-equiv
+/** The human's answer. */
+interface AskUserQuestionAnswer {
+  /** Structured answers keyed by question id. */
+  answers: AskUserQuestionAnswerItem[]
+}
+```
+
+Timed answerers receive `wait: { callId, timed: true }`. The call id identifies the card and the foreground wait. The Client calls `attachWait` to claim the wait and obtain its remaining duration; transport forwards the original event without inspecting or rewriting these fields. A `wait` without `timed` identifies an indefinite card-keyed request. An absent `wait` identifies a blocking request without a card key.
+
+```ts type-equiv
+/** Client-safe payload declared for the user-question answerer waterfall. */
+interface AskUserQuestionRequestEvent {
+  /** Questions to display. */
+  questions: AskUserQuestionItem[]
+  /** Agent identity projected to the corresponding Client Context in transit. */
+  agent?: Agent
+  /** Cancellation lifetime of the pending request. */
+  signal?: AbortSignal
+  /**
+   * Tool call the Client card is keyed by. Timed answerers attach to the
+   * business wait stream before starting their local countdown.
+   */
+  wait?: {
+    /** Tool call the Client card is keyed by. */
+    callId: ToolCallId
+    /** True for a foreground wait that requires a Client claim; absent for indefinite waits. */
+    timed?: boolean
+  }
+}
+```
+
+## Timed questions and late replies
+
+A timed question waits for a bounded foreground window and then lets the agent continue independent work. If the user answers inside the window, the tool returns the answer batch; otherwise `TimedUserQuestionResult` is `{ pending: true, callId }`. Pending means the question is still answerable; it is not an empty answer, a refusal, a confirmation, or permission.
+
+```ts type-equiv
+/** Timed ask result returned when the foreground answer window closes. */
+type TimedUserQuestionResult = AskUserQuestionAnswer | { pending: true; callId: ToolCallId }
+```
+
+A Client claim is a business Remote stream, not a Gateway delivery. `TimedQuestionWait` holds the original Host deadline and runs its timer only while no claim exists. Its `attachWait` stream yields the current remaining duration, and the Client counts down with its own clock. Focus, editing, and Take time stay local. Stream cancellation releases that claim; after the last claim leaves, the Host resumes the original deadline. An unattended timeout aborts the foreground waterfall's private signal and returns pending without cancelling the Turn. Gateway and `api-remotes` contain no question-specific timing policy.
+
+The `userQuestions` Session projection folds existing events into the answerable question set and the settled one; no wait state, focus state, or deadline is logged. Each `request/header` records the exact tool schemas the model saw. Native calls are tracked only when that header declares the timed `ask_user_question` schema with a `timeout` parameter; the blocking legacy tool never declares it. A native `tool/call` opens a question. A `tool/result` marks it `continued` only when it carries the pending payload or is the synthetic `TOOL_OUTCOME_UNKNOWN` result Session resume repair appends; an answer batch moves it into `settled` with that batch, and any failure drops it. A `run_code` PTC sub-call enters the projection when its `tool/ptc-dispatch` result is pending, even though the request header exposes only `run_code`. A late reply moves a continued question into `settled` when its message is admitted as `user/message`, together with the answer batch read out of that message: the timed call's own result recorded the timeout, so a transcript row has nowhere else to read what the user finally chose. A queued reply can be canceled before admission and leaves the question answerable. A reply whose text carries no readable batch settles the call with no answers; one naming a call that is not active changes nothing.
+
+```ts type-equiv
+/** `open` while the tool call may still return the answer; `continued` once the answer can only arrive as a new turn. */
+type UserQuestionState = 'open' | 'continued'
+```
+
+```ts type-equiv
+/** One unanswered timed `ask_user_question` call reconstructed from the Session log. */
+interface PendingUserQuestion {
+  readonly callId: ToolCallId
+  readonly questions: readonly AskUserQuestionItem[]
+  readonly state: UserQuestionState
+}
+```
+
+```ts type-equiv
+/**
+ * One timed `ask_user_question` call and the answers it settled with: the
+ * batch its own result carried when the user answered inside the window,
+ * otherwise the batch its late reply carried, because that call's own result
+ * recorded the timeout. A transcript row reads what the user finally answered
+ * from here, and only a call listed here was a timed one.
+ */
+interface SettledUserQuestion {
+  /** The settled call. */
+  readonly callId: ToolCallId
+  /** The recorded batch, one entry per question; empty when the late reply carried none. */
+  readonly answers: readonly AskUserQuestionAnswerItem[]
+}
+```
+
+```ts type-equiv
+/**
+ * Both halves of one Session's timed `ask_user_question` state, as every
+ * Client reads them. A call made while the blocking legacy tool was in
+ * effect appears in neither half.
+ */
+interface UserQuestionProjectionView {
+  /** Calls that can still take an answer, in ask order. */
+  readonly active: readonly PendingUserQuestion[]
+  /** Calls an answer settled, in settlement order. */
+  readonly settled: readonly SettledUserQuestion[]
+}
+```
+
+An open question accepts answers only through the waterfall. Once it is `continued`, the `answer` Remote method queues a user message for the owning agent and wakes it if idle. The message has source `user-question-reply`, outcome `answered`, and an `answer_to_pending_question` payload. The method returns `false` for an open or unknown call, rejects a second queued reply with `REPLY_QUEUED` even after a Host restart, and rejects incomplete or duplicate answer batches with `BAD_ANSWER`.
+
+Closing the Client panel sends nothing. A foreground timeout ends only the tool wait. Continued questions have no deadline; they stay answerable until a reply is admitted.
+
+After a Host restart, the Remote layer resumes the root agent when the Session reopens. A late reply then enters a new turn.
+
+## Errors
+
+`UserQuestionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `ASK_ABORTED`, or UI-side cancellation. An answerer failure that is not a `HarnessError` becomes `PROVIDER_ERROR` with the original message and the original as `cause`; another `HarnessError` keeps its own `name` and `code`.
+
+```ts type-equiv
+/** Stable error taxonomy for user-questions failures. */
+class UserQuestionError extends HarnessError {
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, code, options)
+    this.name = 'UserQuestionError'
+  }
+}
+```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxuserquestions--userquestionservice"></a>
+
+### `ctx.userQuestions` — `UserQuestionService`
+
+`ctx.userQuestions`: validation plus the scoped answerer waterfall.
+
+```ts cordis-catalog
+/**
+ * Answer a continued question. The reply is steered into the agent as a
+ * user message whose source names the call; that message is also the
+ * record that closes the question in the projection.
+ * @param agent - Live root agent for the owning Session.
+ * @param callId - Continued question identity.
+ * @param answer - Complete structured answer batch, one item per question of the call.
+ * @returns Whether the question is still continued; an accepted reply stays
+ *   queued until the agent admits its user message.
+ * @throws {UserQuestionError} `BAD_ANSWER` when the batch does not name each
+ *   question of the call exactly once, or `REPLY_QUEUED` when a reply is
+ *   already waiting for admission.
+ */
+@Remote answer(agent: Agent, callId: ToolCallId, answer: AskUserQuestionAnswer): boolean
+
+/**
+ * Let one answer UI hold a live timed wait. Closing the stream releases its claim.
+ * @param agent - Live root agent owning the question.
+ * @param callId - Foreground tool call to attach to.
+ * @param signal - Remote stream cancellation, including Client disconnect.
+ * @returns One Host-computed remaining duration, or no frames once the wait ended.
+ */
+@Remote({ mode: 'stream' }) async *attachWait(agent: Agent, callId: ToolCallId, signal: AbortSignal): AsyncIterable<{ remainingMs: number }>
+
+/**
+ * Foreground wait whose first settlement the Client decides: the Client
+ * rejects with `ASK_TIMED_OUT` when its countdown ends, and this method maps
+ * that code to the pending result.
+ * @param request - Questions, live owner agent, and abort signal.
+ * @param callId - Tool call identity the Client card is keyed by.
+ * @param timeoutMs - Positive foreground wait in milliseconds.
+ * @returns The answer when it arrives inside the window, otherwise a pending
+ *   result, also when no connected Client claimed the request by the deadline.
+ * @throws {UserQuestionError} `BAD_TIMEOUT` for a non-integer, non-positive,
+ *   or oversized wait.
+ */
+async askTimed( request: AskUserQuestionRequest & { agent: Agent }, callId: ToolCallId, timeoutMs: number, ): Promise<TimedUserQuestionResult>
+
+/**
+ * Ask the scoped answerer waterfall and wait for the user's answer.
+ *
+ * When a caller supplies an agent, human interaction is valid only for the
+ * exact live instance of an ordinary Session. Explicit subagent origin
+ * rejects delegated callers; historical ordinary forks may retain parent
+ * metadata and still ask normally.
+ *
+ * @param request Questions, owner agent, and abort signal.
+ * @returns The answer chosen or typed by the human.
+ * @throws {UserQuestionError} code `ASK_ABORTED` when the supplied signal
+ *   is already or becomes aborted, `CALLER_NOT_LIVE` when a supplied agent
+ *   is not the registry's exact live instance, `DELEGATED_CALLER` when
+ *   that live agent has subagent origin, or `PROVIDER_ERROR`, keeping the
+ *   original message, when an answerer fails with a value that is not a
+ *   `HarnessError`; a coded `HarnessError` from an answerer keeps its `name`
+ *   and `code`.
+ */
+async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+```
+
+Types: [Agent](./core.md) · [ToolCallId](./core.md)
+
+Source: [`packages/interaction/user-questions/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/index.ts)
+
+<a id="user-questions-events"></a>
+
+### `user-questions/*` events
+
+<a id="user-questionsrequest--waterfall"></a>
+
+#### `user-questions/request` — waterfall
+
+Ask composed answerers for structured user input. Return an answer to claim the request or call `next()` to delegate. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+
+```ts cordis-catalog
+/**
+ * Ask composed answerers for structured user input. Return an answer to
+ * claim the request or call `next()` to delegate. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param request - pending user-question request.
+ * @mode waterfall
+ */
+'user-questions/request'( this: Scoped<Agent>, request: AskUserQuestionRequestEvent, next: () => Promise<AskUserQuestionAnswer>, ): Promise<AskUserQuestionAnswer>
+```
+
+Types: [Agent](./core.md) · [Scoped](./scope.md)
+
+Source: [`packages/interaction/user-questions/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/types.ts)
+<!-- END GENERATED cordis-surface -->