# RFD D30: Multi-question ask\_user forms with branching and cancel UX - **Status**: Draft - **Category**: Design - **Authors**: Jean Mertz - **Date**: 2026-04-17 - **Extends**: [RFD 083] ## Summary Extend the `ask_user` built-in tool from [RFD 083] to collect multi-question forms in a single tool call, with predicate-gated branching, a unified cancel UX (`Reply` / `End Turn` / `Back`), and support for `boolean`, `select`, `multi_select`, `text`, and `schema` answer types. The LLM fills in a constrained meta-schema that defines the question flow; the coordinator walks it, prompting the user and collecting answers. ## Motivation [RFD 083] makes `ask_user` a single-question tool. In practice, user-facing flows often need several related answers (e.g. "which directory, and with what permissions?"). Today, the LLM collects them with multiple `ask_user` calls, paying an LLM round-trip per call. For linear or branching forms where the questions are predictable, this is wasteful — the LLM already knows what it wants to ask. A single `ask_user` call with multiple questions and predicate-gated follow-ups collapses the round-trips. Combined with a typed-schema answer ([RFD D13]), it also unlocks lightweight user-facing forms (e.g. "give me the structured config for this migration") without tool authors having to build one-off prompts. Independently, [RFD 083] left the cancel UX sparse: the user can answer or Ctrl+C. This RFD fills in the discoverable options — `Reply`, `End Turn`, `Back` — which become useful enough on their own that they apply to single-question `ask_user` calls too. ## Design ### User-visible behavior The assistant submits a list of questions; the user answers them in order, with the ability to go back, cancel with a reply, or end the turn: ```jsonc { "name": "ask_user", "arguments": { "questions": [ { "id": "apply", "text": "Apply the proposed migration?", "answer_type": "boolean" }, { "id": "env", "text": "Which environment?", "answer_type": "select", "options": ["staging", "production"], "when": { "question_id": "apply", "equals": true } }, { "id": "note", "text": "Optional note for the migration log", "answer_type": "text", "when": { "question_id": "apply", "equals": true } } ] } } ``` The user sees each prompt in sequence, prefixed with a progress indicator (`[1/3]`, `[2/3]`, …). Questions whose `when` predicate evaluates false are skipped silently. ### Tool arguments meta-schema The `ask_user` tool's own argument schema describes what the LLM can submit. [RFD 083]'s single-question shape becomes the common case where `questions` contains one entry; this RFD expands that shape. ```jsonc { "type": "object", "properties": { "questions": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "answer_type": { "enum": ["boolean", "select", "multi_select", "text", "schema"] }, "options": { "type": "array", "items": { "type": "string" } }, "schema": { "type": "object" }, "default": true, "when": { "type": "object", "properties": { "question_id": { "type": "string" }, "equals": true }, "required": ["question_id", "equals"] } }, "required": ["id", "text", "answer_type"] } } }, "required": ["questions"] } ``` We control the branching model by constraining the meta-schema. LLMs fill it in; they do not generate arbitrary JSON Schema. This prevents the rendering complexity of generic `oneOf`/discriminator flows while still supporting typical branching use cases. Validation (at submit time, returning a structured error back to the LLM on failure): - `id` values are unique. - `options` is required iff `answer_type` is `select` or `multi_select`. - `schema` is required iff `answer_type` is `schema`. - `when.question_id` references an `id` earlier in the list (no forward references; prevents cycles structurally). ### Branching: the `when` predicate Each question has an optional `when` predicate: ```jsonc { "question_id": "", "equals": } ``` At runtime, when the walker reaches a question, it evaluates the predicate against the collected answers so far. If the predicate is absent or true, the question is prompted. If false, the question is skipped and its slot in the return map is `null`. Only `equals` is supported in v1. Future extensions (`not_equals`, `one_of`, nested predicates) are left to follow-up RFDs if real usage demands them. ### Cancel UX Every prompt offers three cancel paths alongside the answer: | Option | Effect | | ---------- | ---------------------------------------------------------- | | `Reply` | Cancel the form, return to the LLM with a cancel marker; | | | turn continues. | | `End Turn` | End the turn immediately. Same effect as Ctrl+C, but an | | | explicit, discoverable option. | | `Back` | Re-prompt the previous *answered* question. Omitted on the | | | first question. | The surface depends on the answer type: - **Boolean**: inline-select extends the existing git-style keys: `y` / `Y` / `n` / `N` / `b` / `r` / `s`. - **Select**: inline-select appends `b` / `r` / `s` to the option keys. - **MultiSelect**: `inquire::MultiSelect` submits on Enter; Esc jumps to a cancel menu `[Back / Reply / End Turn]`. - **Text**: a pre-prompt select `[Answer / Back / Reply / End Turn]` is shown first; `Answer` opens the text input. - **Schema**: same pre-prompt select as Text; `Answer` opens a JSON editor (validated against the question's schema on submit). The `Back` option is omitted when there is no prior answered question. ### Back navigation and answer invalidation `Back` re-prompts the previous answered question with the current answer pre-populated. On re-submit, the walker continues from that position, **discarding all answers collected after it**. This keeps predicate evaluation consistent: a changed answer at Q1 naturally re-gates Q2/Q3. If the re-answer changes a predicate's branch (so a different set of later questions applies), the walker discovers this as it re-walks forward. ### Return shape The tool returns a JSON object mapping `question_id` → answer. Skipped or `Back`-invalidated-but-not-re-answered questions map to `null`. ```jsonc { "apply": true, "env": "production", "note": null } ``` This gives the LLM a uniform, parseable shape. Skipped questions appear as `null`, which the LLM can distinguish from absent questions by inspecting the submitted `questions` list. ### Cancel return shape On `Reply`, the tool returns a structured cancel marker so the LLM can decide whether to proceed with partial information or re-ask: ```jsonc { "cancelled": true, "answered": { "apply": true } } ``` The `answered` map contains whatever was collected before the cancel. On `End Turn`, the tool does not return — the turn ends before the tool response is delivered. This matches the Ctrl+C path. ### `AnswerType::Schema` integration This RFD adds the `Schema` variant to `jp_tool::AnswerType`: ```rust pub enum AnswerType { Boolean, Select { options: Vec }, MultiSelect { options: Vec }, Text, Schema { schema: Value }, } ``` The variant is a small addition that can land independently; if [RFD D13] (which defines the same variant for tool-authored questions) lands first, this RFD consumes the existing definition instead of introducing one. The v1 renderer is a JSON editor pre-populated with the question's `default` (if any) and validated against the schema on submit. Rich schema-to-form UI is explicitly out of scope — a JSON editor with validation is sufficient for the initial release. ### Multi-select Uses `inquire::MultiSelect` directly. No wrapper in `jp_inquire` unless a specific custom behavior is later needed. The answer value is a `Vec` of selected option values. ### Progress indicator Rendered as `[N/M]` before each prompt, where `N` is the 1-indexed position of the current question and `M` is the total number of questions in the submitted list. Hidden when `M == 1` (no indicator for single-question calls, preserving [RFD 083]'s simple UX for the common case). ## Drawbacks - **Meta-schema expands the LLM surface for getting things wrong.** Duplicate `id`s, forward-referencing `when` predicates, `options` on a `text` question — all are possible errors. They are caught at submit time and returned as structured errors, but the LLM burns tokens correcting them. - **Back + invalidation adds coordinator state.** The walker needs to track collected answers by position, not just by id, so `Back` can discard the right tail. - **Schema answer UX is minimal.** A JSON editor is functional but not user-friendly for anything beyond small objects. Iteration is expected. - **MultiSelect cancel is less uniform** than the inline-select path used for Boolean and Select. Esc → cancel menu is the cleanest option but requires users to learn one extra binding. ## Alternatives ### LLM-driven branching via multiple `ask_user` calls The LLM calls `ask_user` with one question, reads the answer, calls again with the next question tailored to the response. Already possible under [RFD 083] — no new work needed. Rejected as the *only* approach because it costs one LLM round-trip per question. For forms the LLM can predict in advance (most of them), the round-trips are waste. The `when` predicate collapses them into a single call. ### Full JSON Schema branching (`oneOf` / discriminators / `$ref`) Allow the LLM to submit arbitrary JSON Schema with `oneOf` branches, nested refs, and discriminator-based dispatch. Rejected: the rendering complexity explodes (generic schema-to-form is a significant library, not a walker), and LLMs are inconsistent when constructing `oneOf` schemas. The constrained `when` predicate handles the common cases at a fraction of the implementation cost. ### Skip the cancel menu; keep Ctrl+C Keep [RFD 083]'s existing behavior: answer or Ctrl+C. Rejected: Ctrl+C is a power-user signal, not discoverable. Explicit `Reply` / `End Turn` / `Back` options in the prompt UI are a meaningful UX improvement and are cheap to add once every prompt is already a select (direct for Boolean/Select, pre-prompt for Text/Schema, Esc-driven for MultiSelect). ### Pre/post-prompt narration Add optional narrative text before or after each prompt, surfaced as part of the tool arguments. Rejected: the LLM can already produce narrative content inline, before or between tool calls. Post-prompt narration also breaks the "prompt at the bottom of the terminal" expectation. ## Non-Goals - **Forward-referencing `when` predicates.** Structural constraint: a question's predicate can only reference earlier questions. Prevents cycles and keeps the walker O(n). - **Predicate operators beyond `equals`.** `not_equals`, `one_of`, compound predicates (`and`/`or`) are deferred. Add them if real usage demands. - **Rich form UI for schema-typed answers.** JSON editor only in v1. - **Timeout / deadline handling.** [RFD 049]'s territory. - **Nested forms.** A question's `schema` type does not allow embedding another `ask_user` call. The LLM can still make a follow-up `ask_user` call after the current one returns. ## Risks and Open Questions - **Meta-schema invalid-submission rate in practice.** Until we have telemetry, we don't know how often LLMs produce invalid `when` refs or duplicate `id`s. Submit-time validation must return errors clear enough for the LLM to self-correct on retry. - **Schema answer UX iteration.** JSON-editor-plus-validation is the v1 story, but any real usage will surface sharp edges quickly. Plan for a follow-up UX pass if adoption warrants. - **`MultiSelect` value shape.** Returns a `Vec` of selected option values. If options are heterogeneous (some string, some integer), the return is a heterogeneous array. Document the expectation and validate. - **Single-question call parity with [RFD 083].** A submitted `questions` list of length 1 should render identically to the single-question tool call in [RFD 083] (no progress indicator, direct prompt). This must be verified with snapshot tests. ## Implementation Plan ### Phase 1: Multi-question walker (flat, no branching) Update `AskUser` to accept `{ questions: [...] }`. Walk the list in order, collecting answers into a `Map`. Return the map as the tool result. No `when`, no `Back`, no cancel menu — just the existing [RFD 083] prompt paths applied N times in sequence. Validation: unique `id`s; `options`/`schema` required-ness per `answer_type`. Depends on [RFD 083] Phase 2. Can be merged independently. ### Phase 2: `when` predicate Add `when: { question_id, equals }` to the meta-schema. At each question, evaluate the predicate against collected answers; skip if false. No-forward- reference validation at submit time. Skipped questions map to `null` in the return shape. Depends on Phase 1. Can be merged independently of Phase 3. ### Phase 3: Cancel menu and Back Add the `Reply` / `End Turn` / `Back` options. Wire Boolean and Select to extend their inline-select keys (`b`/`r`/`s`). Wire Text and Schema to use a pre-prompt select. Wire MultiSelect's Esc binding to the cancel menu. `Back` pops all answers at positions ≥ the back target; re-prompts with the previous answer pre-populated; re-walks forward. `Reply` returns `{ cancelled: true, answered: {...partial...} }`. `End Turn` ends the turn. Depends on Phase 1. ### Phase 4: `AnswerType::Schema` Add the `Schema { schema: Value }` variant. Implement the JSON editor flow: pre-prompt select → JSON editor → validate against schema → accept or re-prompt on failure. If [RFD D13] lands first, consume its variant definition instead of introducing one here. Depends on Phase 1. Can be merged independently of Phases 2 and 3. ### Phase 5: Multi-select Integrate `inquire::MultiSelect`. Add `MultiSelect { options }` to `AnswerType`. Esc → cancel menu. Depends on Phase 3 (for the cancel menu behavior). ### Phase 6: Progress indicator Render `[N/M]` before each prompt; hide when `M == 1`. Depends on Phase 1. ## References - [RFD 083] — the single-question `ask_user` tool this RFD extends. - [RFD D13] — defines `AnswerType::Schema` (shared variant). - [RFD 028] — the inquiry coordinator, walker foundation. - [RFD 034] — inquiry-specific assistant configuration (relevant for schema-typed answers routed through sub-agents, though `ask_user` itself stays user-facing). - [RFD 049] — `exclusive` flag and detached-policy cascade, inherited from [RFD 083]. [RFD 028]: ../028-structured-inquiry-system-for-tool-questions.md [RFD 034]: ../034-inquiry-specific-assistant-configuration.md [RFD 049]: ../049-non-interactive-mode-and-detached-prompt-policy.md [RFD 083]: ../083-built-in-ask_user-tool-for-assistant-initiated-inquiries.md [RFD D13]: D13-schema-answer-type-and-inherit-model-alias.md