@bastani/atomic 0.8.20-0 → 0.8.21-0

package/dist/builtin/workflows/src/runs/foreground/stage-runner.ts

@@ -199,16 +199,63 @@ function extractMessageText(message: AgentSession["messages"][number]): string {
   return "";
 }
 
-function lastOutputTextFromMessages(messages: AgentSession["messages"]): string | undefined {
+function lastAssistantTextFromMessages(messages: AgentSession["messages"]): string | undefined {
   for (let index = messages.length - 1; index >= 0; index -= 1) {
     const message = messages[index];
-    if (!message || (message.role !== "assistant" && message.role !== "toolResult")) continue;
+    // Only assistant prose is a valid non-terminating turn output. A tool
+    // result is the turn output ONLY when its tool terminated the turn, which
+    // is handled separately by `terminatingToolResultText`.
+    if (!message || message.role !== "assistant") continue;
     const text = extractMessageText(message).trim();
     if (text) return text;
   }
   return undefined;
 }
 
+/**
+ * When an agent turn ends on a tool that returned `terminate: true`, control
+ * returns with the tool result as the final conversational message and no
+ * trailing assistant response (see the structured-output contract in the
+ * Atomic extension docs). That tool result is the deterministic output of the
+ * turn, so it must win over any prose the model emitted *before* the tool call
+ * in the same assistant message (which `getLastAssistantText()` would otherwise
+ * surface). This keeps terminating structured-output tools such as the `goal`
+ * and `ralph` review gates' `review_decision` tool deterministic regardless of
+ * surrounding narration.
+ *
+ * Returns the trailing tool-result text ONLY when the most recent
+ * conversational message is a tool result whose tool call actually returned
+ * `terminate: true` (tracked at runtime from the session's tool_execution_end
+ * events — see `terminatingToolCallIds`). Returns `undefined` for a turn that
+ * ended on an assistant response, OR on a tool result from a non-terminating
+ * tool (e.g. a turn aborted/errored right after a tool call) — both fall back
+ * to the last assistant message.
+ */
+function terminatingToolResultText(
+  messages: AgentSession["messages"],
+  terminatingToolCallIds: ReadonlySet<string>,
+): string | undefined {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!message) continue;
+    if (message.role === "toolResult") {
+      // The trailing message is a tool result. It is the deterministic turn
+      // output only if THIS tool call returned `terminate: true`; otherwise the
+      // turn ended on this tool for another reason (abort/error) and the last
+      // assistant message is the real output.
+      const toolCallId = (message as { toolCallId?: unknown }).toolCallId;
+      if (typeof toolCallId !== "string" || !terminatingToolCallIds.has(toolCallId)) {
+        return undefined;
+      }
+      const text = extractMessageText(message).trim();
+      return text.length > 0 ? text : undefined;
+    }
+    if (message.role === "assistant") return undefined;
+    // Skip non-conversational roles (system/user) while locating the tail.
+  }
+  return undefined;
+}
+
 function asAgentSession(activeSession: StageSessionRuntime | undefined): AgentSession | undefined {
   if (!activeSession) return undefined;
   const candidate = activeSession as StageSessionRuntime & Partial<Pick<AgentSession, "state" | "sessionManager" | "modelRegistry" | "getContextUsage">>;
@@ -226,11 +273,21 @@ function asAgentSession(activeSession: StageSessionRuntime | undefined): AgentSe
 function lastAssistantTextFromSession(
   activeSession: StageSessionRuntime | undefined,
   fallback: string | undefined,
+  terminatingToolCallIds: ReadonlySet<string>,
 ): string | undefined {
   if (!activeSession) return fallback;
+  // A tool that returned `terminate: true` ends the turn with its tool result
+  // as the final message; that result is the deterministic stage output and
+  // wins over prose emitted before the terminating tool call. Detection is by
+  // the tool call's actual runtime terminate flag — NOT merely "the last
+  // message is a tool result".
+  const terminatingText = terminatingToolResultText(activeSession.messages, terminatingToolCallIds);
+  if (terminatingText !== undefined) return terminatingText;
+  // Otherwise the turn output is the last assistant message — never a tool
+  // result from a non-terminating tool.
   const direct = activeSession.getLastAssistantText?.();
   if (direct !== undefined && direct.trim()) return direct;
-  return lastOutputTextFromMessages(activeSession.messages) ?? direct ?? fallback;
+  return lastAssistantTextFromMessages(activeSession.messages) ?? direct ?? fallback;
 }
 
 const DEFAULT_MAX_OUTPUT_BYTES = 200 * 1024;
@@ -378,6 +435,26 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
   let session: StageSessionRuntime | undefined;
   let sessionPromise: Promise<StageSessionRuntime> | undefined;
   let lastAssistantText: string | undefined;
+  // Tool-call ids whose tool returned `terminate: true` at runtime, observed
+  // from the session's `tool_execution_end` events. The SDK ends the turn on a
+  // terminating tool, so its tool result is the deterministic stage output; a
+  // trailing tool result from any other tool is NOT. See
+  // `lastAssistantTextFromSession`. The tool result *message* does not carry the
+  // terminate flag, so it must be tracked from the live event stream.
+  const terminatingToolCallIds = new Set<string>();
+  let unsubscribeTerminateWatcher: (() => void) | undefined;
+  const recordTerminatingToolCall = (event: unknown): void => {
+    if (event === null || typeof event !== "object") return;
+    const record = event as Record<string, unknown>;
+    if (record["type"] !== "tool_execution_end") return;
+    const result = record["result"];
+    if (result === null || typeof result !== "object") return;
+    if ((result as Record<string, unknown>)["terminate"] !== true) return;
+    const callId = record["toolCallId"];
+    if (typeof callId === "string" && callId.length > 0) {
+      terminatingToolCallIds.add(callId);
+    }
+  };
   let adapterMessages: AgentSession["messages"] = [];
   let disposed = false;
   let pendingThinkingLevel: Parameters<StageContext["setThinkingLevel"]>[0] | undefined;
@@ -463,6 +540,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     for (const listener of pendingListeners) {
       listenerUnsubscribes.set(listener, created.subscribe(listener));
     }
+    // Track terminating tool calls for this session so the stage result text is
+    // derived deterministically from a tool that actually ended the turn.
+    unsubscribeTerminateWatcher?.();
+    unsubscribeTerminateWatcher = created.subscribe((event) => recordTerminatingToolCall(event));
     return created;
   }
 
@@ -501,6 +582,9 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     sessionPromise = undefined;
     for (const unsubscribe of listenerUnsubscribes.values()) unsubscribe();
     listenerUnsubscribes.clear();
+    unsubscribeTerminateWatcher?.();
+    unsubscribeTerminateWatcher = undefined;
+    terminatingToolCallIds.clear();
     await current?.dispose();
   }
 
@@ -604,7 +688,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
         return lastAssistantText;
       }
       await promptWithFallback(text, sdkOptions);
-      const rawText = lastAssistantTextFromSession(session, lastAssistantText) ?? "";
+      const rawText = lastAssistantTextFromSession(session, lastAssistantText, terminatingToolCallIds) ?? "";
       lastAssistantText = await finalizePromptOutput(rawText, outputOptions, runtimeCwd);
       return lastAssistantText;
     },
@@ -628,7 +712,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       // `ctx.complete()` can still use the stage AgentSession for simple text
       // completions. Completion-specific options require the dedicated adapter.
       await promptWithFallback(text, undefined, "complete");
-      lastAssistantText = lastAssistantTextFromSession(session, lastAssistantText) ?? "";
+      lastAssistantText = lastAssistantTextFromSession(session, lastAssistantText, terminatingToolCallIds) ?? "";
       return lastAssistantText;
     },
 
@@ -717,15 +801,18 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       for (const unsubscribe of listenerUnsubscribes.values()) unsubscribe();
       listenerUnsubscribes.clear();
       pendingListeners.clear();
+      unsubscribeTerminateWatcher?.();
+      unsubscribeTerminateWatcher = undefined;
+      terminatingToolCallIds.clear();
       await session?.dispose();
     },
 
     __getLastAssistantText() {
-      return lastAssistantTextFromSession(session, lastAssistantText);
+      return lastAssistantTextFromSession(session, lastAssistantText, terminatingToolCallIds);
     },
 
     getLastAssistantText() {
-      return lastAssistantTextFromSession(session, lastAssistantText);
+      return lastAssistantTextFromSession(session, lastAssistantText, terminatingToolCallIds);
     },
 
     async __ensureSession() {

package/dist/builtin/workflows/src/shared/stage-prompt.ts

@@ -0,0 +1,326 @@
+/**
+ * stage-prompt — headless answering for brokered in-stage prompts.
+ *
+ * A workflow stage's agent can call the `ask_user_question` tool, and the
+ * executor raises a deterministic readiness gate after such a turn. Both
+ * render their UI through {@link StageUiBroker.requestCustomUi} and resolve the
+ * tool's `ctx.ui.custom<QuestionnaireResult>()` promise with a
+ * `QuestionnaireResult`-shaped value. That value is normally produced by the
+ * interactive TUI component.
+ *
+ * For programmatic / non-interactive control (e.g. an orchestrating agent
+ * answering via `workflow send`), we need to synthesize the same value WITHOUT
+ * the TUI. This module:
+ *   1. Parses the `ask_user_question` tool args into a serializable
+ *      {@link StageInputRequest} descriptor (surfaced on the stage snapshot so
+ *      `workflow send` / status can show the questions + options).
+ *   2. Produces a {@link StagePromptAdapter} whose `buildResult` maps a simple
+ *      answer (free text, an option label, an option index, or a pre-built raw
+ *      result) into the `QuestionnaireResult` the tool expects.
+ *
+ * cross-ref:
+ *   - packages/coding-agent/src/core/tools/ask-user-question/tool/types.ts
+ *       QuestionnaireResult / QuestionAnswer (the result shape mirrored here)
+ *   - src/shared/stage-ui-broker.ts  provideStagePrompt / answerStagePrompt
+ *   - src/runs/foreground/executor.ts  ask_user_question watcher + readiness gate
+ */
+
+import type {
+  StageInputKind,
+  StageInputQuestion,
+  StageInputRequest,
+} from "./store-types.js";
+
+/**
+ * A simple, transport-friendly answer to a brokered stage prompt. Exactly one
+ * of the fields is typically populated:
+ *   - `raw`: a pre-built `QuestionnaireResult`-shaped value, forwarded verbatim.
+ *   - `optionLabels`: explicit option label(s) (one for single-select, many for
+ *     multi-select).
+ *   - `text`: free text — matched against option labels / 1-based indices, and
+ *     otherwise treated as a typed ("custom") answer.
+ */
+export interface StageInputAnswer {
+  readonly text?: string;
+  readonly optionLabels?: readonly string[];
+  readonly raw?: unknown;
+}
+
+/** Result shape mirrored from the coding-agent ask_user_question tool. */
+interface BuiltAnswer {
+  questionIndex: number;
+  question: string;
+  kind: "option" | "custom" | "chat" | "multi";
+  answer: string | null;
+  selected?: string[];
+}
+interface BuiltResult {
+  answers: BuiltAnswer[];
+  cancelled: boolean;
+}
+
+/**
+ * Couples the serializable {@link StageInputRequest} descriptor with a
+ * `buildResult` that turns a {@link StageInputAnswer} into the value used to
+ * resolve the brokered `ctx.ui.custom` promise.
+ */
+export interface StagePromptAdapter {
+  readonly prompt: StageInputRequest;
+  buildResult(answer: StageInputAnswer): unknown;
+}
+
+function normalizeLabel(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function readStringArray(value: unknown): readonly string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value.filter(
+    (item): item is string => typeof item === "string" && item.trim().length > 0,
+  );
+  return out.length > 0 ? out : undefined;
+}
+
+function readFirstString(...values: readonly unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/** True when the answer carries a value the adapter can resolve. */
+export function hasStageInputAnswerContent(answer: StageInputAnswer): boolean {
+  return (
+    answer.text !== undefined || answer.optionLabels !== undefined || answer.raw !== undefined
+  );
+}
+
+/**
+ * Coerce a loosely-typed answer payload — as delivered by `workflow send`
+ * (`text` / `response` / `message`) — into a normalized {@link StageInputAnswer}
+ * the {@link StagePromptAdapter} can resolve against a question's options.
+ *
+ * Recognized inputs:
+ *   - a plain string (option label, 1-based index, or free text);
+ *   - a JSON-encoded string of any structured shape below;
+ *   - a fully-formed `QuestionnaireResult` (every answer carries a numeric
+ *     `questionIndex`), forwarded raw;
+ *   - the orchestrator-friendly `{ answers: [{ answer | label | selected }] }`
+ *     or `{ questions: [{ answer | label | selected }] }`;
+ *   - a flat `{ answer | response | label | selected | optionLabels }`;
+ *   - a string array (multi-select labels).
+ *
+ * Without this, a structured `response` was forwarded verbatim as the brokered
+ * result, violating the `QuestionnaireResult` contract and leaving the readiness
+ * gate (and any brokered prompt) unable to resolve to a matching option.
+ */
+export function coerceStageInputAnswer(value: unknown): StageInputAnswer {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      try {
+        const parsed: unknown = JSON.parse(trimmed);
+        if (parsed !== null && typeof parsed === "object") {
+          const coerced = coerceStageInputAnswer(parsed);
+          if (hasStageInputAnswerContent(coerced)) return coerced;
+        }
+      } catch {
+        // Not JSON — fall through and treat the string as a literal answer.
+      }
+    }
+    return { text: value };
+  }
+  if (Array.isArray(value)) {
+    const labels = readStringArray(value);
+    return labels !== undefined ? { optionLabels: labels } : {};
+  }
+  if (value === null || typeof value !== "object") return {};
+
+  const record = value as Record<string, unknown>;
+
+  // Forward verbatim ONLY a fully-formed QuestionnaireResult — every answer
+  // entry must carry a numeric `questionIndex`. A loosely-shaped `answers[]`
+  // (e.g. `{ answers: [{ question, answer }] }`) is NOT genuine: forwarding it
+  // raw makes the tool envelope match no question index and reply
+  // "User declined to answer questions", stranding the prompt.
+  const answersArray = Array.isArray(record["answers"])
+    ? (record["answers"] as readonly unknown[])
+    : undefined;
+  if (
+    answersArray !== undefined &&
+    answersArray.length > 0 &&
+    answersArray.every(
+      (entry) =>
+        entry !== null &&
+        typeof entry === "object" &&
+        typeof (entry as Record<string, unknown>)["questionIndex"] === "number",
+    )
+  ) {
+    return { raw: value };
+  }
+
+  // Otherwise locate the answer-bearing record — the first `answers[]` or
+  // `questions[]` entry when present, else the object itself — and extract a
+  // value the adapter can resolve against the question's options (so it assigns
+  // the correct questionIndex), rather than forwarding an unusable result.
+  const source = answerBearingRecord(record);
+  const labels = readStringArray(source["optionLabels"]) ?? readStringArray(source["selected"]);
+  if (labels !== undefined) return { optionLabels: labels };
+
+  const text = readFirstString(
+    source["answer"],
+    source["response"],
+    source["label"],
+    source["text"],
+  );
+  if (text !== undefined) return { text };
+
+  // Nothing resolvable — decline rather than forward an unusable result.
+  return {};
+}
+
+function firstObjectOf(value: unknown): Record<string, unknown> | undefined {
+  const first = Array.isArray(value) ? value[0] : undefined;
+  return first !== null && typeof first === "object"
+    ? (first as Record<string, unknown>)
+    : undefined;
+}
+
+function answerBearingRecord(record: Record<string, unknown>): Record<string, unknown> {
+  return firstObjectOf(record["answers"]) ?? firstObjectOf(record["questions"]) ?? record;
+}
+
+function parseOption(value: unknown): StageInputQuestion["options"][number] | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  const record = value as Record<string, unknown>;
+  const label = asString(record["label"]);
+  if (label === undefined) return undefined;
+  const description = asString(record["description"]);
+  return description !== undefined ? { label, description } : { label };
+}
+
+function parseQuestion(value: unknown): StageInputQuestion | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  const record = value as Record<string, unknown>;
+  const question = asString(record["question"]);
+  if (question === undefined) return undefined;
+  const rawOptions = Array.isArray(record["options"]) ? record["options"] : [];
+  const options = rawOptions
+    .map(parseOption)
+    .filter((option): option is StageInputQuestion["options"][number] => option !== undefined);
+  const header = asString(record["header"]);
+  const multiSelect = record["multiSelect"] === true;
+  return {
+    question,
+    ...(header !== undefined ? { header } : {}),
+    ...(multiSelect ? { multiSelect: true } : {}),
+    options,
+  };
+}
+
+/**
+ * Parse `ask_user_question` tool args (`{ questions: [...] }`) into the
+ * serializable question descriptors. Returns `undefined` when no well-formed
+ * question is present.
+ */
+export function parseAskUserQuestionArgs(
+  args: unknown,
+): readonly StageInputQuestion[] | undefined {
+  if (args === null || typeof args !== "object") return undefined;
+  const rawQuestions = (args as Record<string, unknown>)["questions"];
+  if (!Array.isArray(rawQuestions)) return undefined;
+  const questions = rawQuestions
+    .map(parseQuestion)
+    .filter((question): question is StageInputQuestion => question !== undefined);
+  return questions.length > 0 ? questions : undefined;
+}
+
+/**
+ * Resolve a desired answer string against a single-select question's options.
+ * Matches a case-insensitive option label, then a 1-based option index, then
+ * falls back to a typed ("custom") answer.
+ */
+function answerSingle(question: StageInputQuestion, desired: string): BuiltAnswer {
+  const normalized = normalizeLabel(desired);
+  const byLabel = question.options.find((option) => normalizeLabel(option.label) === normalized);
+  if (byLabel) {
+    return { questionIndex: 0, question: question.question, kind: "option", answer: byLabel.label };
+  }
+  const asIndex = Number.parseInt(desired.trim(), 10);
+  if (
+    Number.isInteger(asIndex) &&
+    asIndex >= 1 &&
+    asIndex <= question.options.length &&
+    String(asIndex) === desired.trim()
+  ) {
+    const option = question.options[asIndex - 1]!;
+    return { questionIndex: 0, question: question.question, kind: "option", answer: option.label };
+  }
+  return { questionIndex: 0, question: question.question, kind: "custom", answer: desired };
+}
+
+function answerMulti(question: StageInputQuestion, candidates: readonly string[]): BuiltAnswer {
+  const selected: string[] = [];
+  for (const candidate of candidates) {
+    const normalized = normalizeLabel(candidate);
+    const byLabel = question.options.find((option) => normalizeLabel(option.label) === normalized);
+    if (byLabel) {
+      if (!selected.includes(byLabel.label)) selected.push(byLabel.label);
+      continue;
+    }
+    const asIndex = Number.parseInt(candidate.trim(), 10);
+    if (Number.isInteger(asIndex) && asIndex >= 1 && asIndex <= question.options.length) {
+      const option = question.options[asIndex - 1]!;
+      if (!selected.includes(option.label)) selected.push(option.label);
+    }
+  }
+  return { questionIndex: 0, question: question.question, kind: "multi", answer: null, selected };
+}
+
+function buildResult(
+  questions: readonly StageInputQuestion[],
+  answer: StageInputAnswer,
+): unknown {
+  if (answer.raw !== undefined) return answer.raw;
+  const question = questions[0];
+  if (question === undefined) return { answers: [], cancelled: true } satisfies BuiltResult;
+
+  const multi = question.multiSelect === true;
+  if (multi) {
+    const candidates =
+      answer.optionLabels !== undefined
+        ? answer.optionLabels
+        : (answer.text ?? "").split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+    return { answers: [answerMulti(question, candidates)], cancelled: false } satisfies BuiltResult;
+  }
+
+  const desired = answer.optionLabels?.[0] ?? answer.text;
+  if (desired === undefined || desired.length === 0) {
+    return { answers: [], cancelled: true } satisfies BuiltResult;
+  }
+  return { answers: [answerSingle(question, desired)], cancelled: false } satisfies BuiltResult;
+}
+
+/**
+ * Build a {@link StagePromptAdapter} from `ask_user_question` tool args. Returns
+ * `undefined` when the args contain no parseable question (the prompt then
+ * stays TUI-only).
+ */
+export function buildStagePromptAdapter(
+  id: string,
+  kind: StageInputKind,
+  args: unknown,
+  createdAt: number,
+): StagePromptAdapter | undefined {
+  const questions = parseAskUserQuestionArgs(args);
+  if (questions === undefined) return undefined;
+  const prompt: StageInputRequest = { id, kind, questions, createdAt };
+  return {
+    prompt,
+    buildResult: (answer) => buildResult(questions, answer),
+  };
+}

package/dist/builtin/workflows/src/shared/stage-ui-broker.ts

@@ -2,6 +2,8 @@ import { randomUUID } from "node:crypto";
 import type { Component, Focusable, TUI } from "@earendil-works/pi-tui";
 import type { Store } from "./store.js";
 import { store as defaultStore } from "./store.js";
+import type { StageInputRequest } from "./store-types.js";
+import type { StageInputAnswer, StagePromptAdapter } from "./stage-prompt.js";
 import type { PiCustomOverlayFactory, PiCustomOverlayOptions, PiKeybindings, PiTheme } from "../extension/wiring.js";
 
 export interface StageCustomUiRequest<T = unknown> {
@@ -32,11 +34,61 @@ export class StageUiBroker {
   private readonly store: Store;
   private readonly pending = new Map<string, StageCustomUiRequest>();
   private readonly hosts = new Map<string, StageCustomUiHost>();
+  // Headless-answer adapters keyed by (runId, stageId). Populated by the
+  // executor's ask_user_question watcher and the readiness gate so a brokered
+  // custom-UI prompt can be answered programmatically (e.g. via `workflow
+  // send`) without a TUI host rendering the interactive component.
+  private readonly adapters = new Map<string, StagePromptAdapter>();
 
   constructor(store: Store = defaultStore) {
     this.store = store;
   }
 
+  /**
+   * Register the structured descriptor + headless result builder for the
+   * prompt a stage is about to raise (or has just raised) via
+   * `requestCustomUi`. Surfaces the descriptor on the stage snapshot so
+   * `workflow send` / status can see and answer it. Safe to call before or
+   * after the matching `requestCustomUi`; the (runId, stageId) key joins them.
+   */
+  provideStagePrompt(runId: string, stageId: string, adapter: StagePromptAdapter): void {
+    this.adapters.set(key(runId, stageId), adapter);
+    this.store.recordStageInputRequest(runId, stageId, adapter.prompt);
+  }
+
+  /** Drop a stage's headless-answer adapter and clear its snapshot descriptor. */
+  clearStagePrompt(runId: string, stageId: string): void {
+    if (this.adapters.delete(key(runId, stageId))) {
+      this.store.clearStageInputRequest(runId, stageId);
+    }
+  }
+
+  /**
+   * Return the structured descriptor for a stage's brokered prompt when BOTH a
+   * headless-answer adapter and a live pending request exist for it — i.e. when
+   * `answerStagePrompt` can actually resolve something right now.
+   */
+  peekStagePrompt(runId: string, stageId: string): StageInputRequest | undefined {
+    const hostKey = key(runId, stageId);
+    const adapter = this.adapters.get(hostKey);
+    if (adapter && this.pending.has(hostKey)) return adapter.prompt;
+    return undefined;
+  }
+
+  /**
+   * Headlessly answer a stage's pending brokered prompt. Resolves the awaiting
+   * `ctx.ui.custom` promise with the adapter-built result. Returns `false` when
+   * there is no adapter+request pair for the stage.
+   */
+  answerStagePrompt(runId: string, stageId: string, answer: StageInputAnswer): boolean {
+    const hostKey = key(runId, stageId);
+    const adapter = this.adapters.get(hostKey);
+    const request = this.pending.get(hostKey);
+    if (!adapter || !request) return false;
+    this.resolve(request, adapter.buildResult(answer));
+    return true;
+  }
+
   private hideHost(host: StageCustomUiHost | undefined, request: StageCustomUiRequest, reason: unknown): void {
     try {
       host?.hideCustomUi?.(request, reason);
@@ -70,13 +122,12 @@ export class StageUiBroker {
     return () => {
       if (this.hosts.get(hostKey) !== host) return;
       this.hosts.delete(hostKey);
-      const pendingRequest = this.pending.get(hostKey);
-      if (pendingRequest) {
-        this.reject(
-          pendingRequest,
-          new Error(`pi-workflows: stage ${stageId} custom UI host unregistered`),
-        );
-      }
+      // Unregistering a host means it stops *displaying* the request — not that
+      // the request is cancelled. A stage-scoped human-input request (e.g.
+      // ask_user_question / readiness gate) outlives any one attached chat:
+      // detaching leaves it pending (the stage stays awaiting_input) and a
+      // future host re-displays it. The request is settled only by the user
+      // answering (resolve) or the run aborting (its AbortSignal -> reject).
     };
   }
 
@@ -132,6 +183,8 @@ export class StageUiBroker {
     const hostKey = key(request.runId, request.stageId);
     if (this.pending.get(hostKey)?.id !== request.id) return;
     this.pending.delete(hostKey);
+    this.adapters.delete(hostKey);
+    this.store.clearStageInputRequest(request.runId, request.stageId);
     this.store.recordStageAwaitingInput(request.runId, request.stageId, false);
     this.hideHost(this.hosts.get(hostKey), request, undefined);
     request.resolve(value);
@@ -141,6 +194,8 @@ export class StageUiBroker {
     const hostKey = key(request.runId, request.stageId);
     if (this.pending.get(hostKey)?.id !== request.id) return;
     this.pending.delete(hostKey);
+    this.adapters.delete(hostKey);
+    this.store.clearStageInputRequest(request.runId, request.stageId);
     this.store.recordStageAwaitingInput(request.runId, request.stageId, false);
     this.hideHost(this.hosts.get(hostKey), request, reason);
     request.reject(reason);

package/dist/builtin/workflows/src/shared/store-types.ts

@@ -42,6 +42,41 @@ export interface PendingPrompt {
   readonly createdAt: number;
 }
 
+/** Discriminates the brokered structured-prompt source. */
+export type StageInputKind = "ask_user_question" | "readiness_gate";
+
+/** One selectable option in a {@link StageInputQuestion}. */
+export interface StageInputOption {
+  readonly label: string;
+  readonly description?: string;
+}
+
+/** One question in a {@link StageInputRequest}. */
+export interface StageInputQuestion {
+  readonly question: string;
+  readonly header?: string;
+  readonly multiSelect?: boolean;
+  readonly options: readonly StageInputOption[];
+}
+
+/**
+ * Serializable descriptor of an in-stage `ask_user_question` (or readiness
+ * gate) prompt brokered through `StageUiBroker`. Unlike {@link PendingPrompt}
+ * (the simple input/confirm/select/editor HIL model), this mirrors the richer
+ * structured ask_user_question shape so `workflow send` and status inspection
+ * can see the questions/options and answer the prompt without the TUI.
+ *
+ * Resolution lives in `StageUiBroker` (the awaiting `ctx.ui.custom` promise);
+ * only this JSON-cloneable descriptor lives on the snapshot.
+ */
+export interface StageInputRequest {
+  readonly id: string;
+  readonly kind: StageInputKind;
+  readonly questions: readonly StageInputQuestion[];
+  /** Issue timestamp (ms since epoch). */
+  readonly createdAt: number;
+}
+
 export interface ToolEvent {
   name: string;
   input?: Record<string, unknown>;
@@ -95,6 +130,14 @@ export interface StageSnapshot {
   awaitingInputSince?: number;
   /** Pending human-in-the-loop prompt owned by this workflow stage/node. */
   pendingPrompt?: PendingPrompt;
+  /**
+   * Structured descriptor of a brokered ask_user_question / readiness-gate
+   * prompt awaiting an answer. Set while the stage's `ctx.ui.custom` promise is
+   * pending; resolution lives in `StageUiBroker`. Lets `workflow send` answer
+   * the prompt headlessly. Distinct from {@link pendingPrompt}, which models
+   * the simpler input/confirm/select/editor HIL prompts.
+   */
+  inputRequest?: StageInputRequest;
   blockedByStageId?: string;
   notices?: StageNotice[];
   /**