Merge remote-tracking branch 'origin/master' into codex/rfc-subagent-background-tasks

Adopts #185 (dsh-timeout: clampTimeout/deadline/timeoutOf drive bash
run() timeout classification; runBash loses its own timer) and #108
(ask_user_question) across the task-runtime rework: bash-local keeps
the BashProcess handle shape with master's deadline mechanics, tool
catalogs/expectations carry both the task_* and ask-user tools, and
generated docs are regenerated on the union.

docs/core-data-structures/core.md

@@ -19,6 +19,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, the turn-enclosure invariant |
 | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, the `tools/pre-execute`/`tools/post-execute` pipeline |
+| [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
 | [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, the background `BashProcess` handle |
 | [tasks.md](tasks.md) | the background task runtime: `TaskId`, `TaskRegistration`, `TaskOutcome`, `TaskSnapshot`/`TaskRead`, owner isolation, the control-tool surface |
 | [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |

docs/core-data-structures/tools.md

@@ -11,6 +11,14 @@ A `ToolSchema` (the model-facing fields) plus the `execute` function and optiona
 ```ts type-equiv
 interface ToolDefinition extends ToolSchema {
   execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>
+  /**
+   * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
+   * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
+   * is NEVER sent to the model — `schemas()` whitelists only name/description/
+   * parameters. Declaring it asserts this tool forwards `exec.signal` to a
+   * cooperative implementation that can reach quiescence when the signal aborts.
+   */
+  timeoutMs?: number
   /**
    * Optional: how to present the PENDING state of one call in a UI, derived from
    * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows

docs/core-data-structures/user-interaction.md

@@ -0,0 +1,97 @@
+# User Interaction
+
+The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-stdio-agent` renders questions in readline, and `dsh-acp` maps them to ACP form elicitations.
+
+Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)
+
+## Question options
+
+`AskUserQuestionOption` is the selectable-choice shape. `label` is the user-facing option text and also the model-facing selected value; `description` is optional UI help text.
+
+```ts type-equiv
+interface AskUserQuestionOption {
+  /** User-facing label. */
+  label: string
+  /** Optional extra context rendered by capable UIs. */
+  description?: string
+}
+```
+
+## Question item
+
+`AskUserQuestionItem` is one question in a request. The model supplies a stable `id`, which is echoed back with the answer so batched questions remain routable.
+
+```ts type-equiv
+interface AskUserQuestionItem {
+  /** Stable model-provided question id, echoed in the answer. */
+  id: string
+  /** The question to display. */
+  question: 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
+}
+```
+
+## 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.
+
+```ts type-equiv
+interface AskUserQuestionRequest {
+  /** Questions to display. */
+  questions: AskUserQuestionItem[]
+  /** Calling agent, when the request came from an agent tool call. */
+  agent?: Agent
+  /** Abort signal for the owning tool/step. */
+  signal?: AbortSignal
+}
+```
+
+## Answer
+
+Providers return one answer per answered question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. When `custom` is present, `selected` is empty; custom text is an answer override, not a supplement to selected choices.
+
+```ts type-equiv
+interface AskUserQuestionAnswerItem {
+  /** The answered question id. */
+  id: string
+  /** Selected option labels. Empty when the answer is purely custom text. */
+  selected: string[]
+  /** Optional free-text "Other" answer. */
+  custom?: string
+}
+```
+
+```ts type-equiv
+interface AskUserQuestionAnswer {
+  /** Structured answers keyed by question id. */
+  answers: AskUserQuestionAnswerItem[]
+}
+```
+
+## Provider
+
+Only one provider may be active in a context. Provider registration is effect-bound so HMR/disposal removes the active UI.
+
+```ts type-equiv
+interface UserInteractionProvider {
+  ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+}
+```
+
+## Errors
+
+`UserInteractionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `ASK_ABORTED`, or ACP-side cancellation.
+
+```ts type-equiv
+class UserInteractionError extends HarnessError {
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, code, options)
+    this.name = 'UserInteractionError'
+  }
+}
+```