pi-ask-popup 0.2.0 → 0.3.0

package/README.md

@@ -25,7 +25,7 @@ Give the model a task with a real decision in it:
 
 > Add caching to the API client.
 
-Rather than picking for you, the model calls `ask_user_question` and a dialog takes over the bottom of your terminal. Move with `Up` and `Down`, pick with `Enter`, or land on `Type something.` to answer in your own words. While typing, `Shift+Enter` adds a line, `Ctrl+G` opens Pi's external editor, `Ctrl+U` clears the draft, and `Esc` cancels the whole questionnaire. Pressing `n` adds a note to the current question. The questionnaire stays in one place until you submit.
+Rather than picking for you, the model calls `ask_user_question` and a dialog takes over the bottom of your terminal. Move with `Up` and `Down`, pick with `Enter`, or land on `Type something.` to answer in your own words. If the question needs a conversation instead of an answer, `Chat about this` closes the dialog and the two of you talk it out in chat. While typing, `Shift+Enter` adds a line, `Ctrl+G` opens Pi's external editor, `Ctrl+U` clears the draft, and `Esc` cancels the whole questionnaire. Pressing `n` adds a note to the current question. The questionnaire stays in one place until you submit.
 
 When the model asks several things at once, `Tab` moves between questions and a Submit tab reviews everything before it goes back:
 
@@ -39,6 +39,7 @@ A note written on a question you never answer still reaches the model, and a glo
 
 - **Typed options, not a wall of prose.** Each question carries 2 to 4 authored choices, and every choice explains what it means or what it costs you.
 - **You can always answer in your own words.** A `Type something.` row is added to every question and widens to the full pane while you type. On a multi-select question it ticks itself the moment you type into it, and what you wrote is submitted alongside whatever boxes you ticked. Clear the text and the tick goes with it.
+- **Talk instead of guessing.** A `Chat about this` row sits on every question. Pick it when the question itself needs discussing: the dialog closes, your answers so far stay with the model, and it waits for what you type next in chat before answering that question.
 - **Compare artifacts, not labels.** An option can carry a markdown `preview` that renders in a bordered box beside the option list.
 - **One interruption, not five.** Up to four questions arrive in a single tabbed dialog, and a Submit tab names anything still blank before you commit.
 - **Notes on any answer, or on all of them.** `n` opens a note editor on any question tab, and on the Submit tab it writes one note covering everything. A written note stays on its tab, dimmed, and the tab bar marks which tabs carry one. A note on a question you never answer still reaches the model as `unansweredNotes`.

package/docs/hosts.md

@@ -31,7 +31,7 @@ The walk asks one question per dialog and returns the same result shape the TUI
 - No side by side preview pane. Previews are folded into the dialog title instead, truncated at 600 characters each.
 - No tab bar and no Submit review tab. One dialog per question, in order.
 - No notes. Both note types, per-question `n` on a question tab and global `n` on the Submit tab, are terminal-only. The host's native `select` and `input` have no note field.
-- Multi-select is a free-text input: type the option numbers, comma separated (`1,3`). Any token that is not a valid option index is treated as a typed custom answer, which is how the `Type something.` escape survives. An empty input commits an empty selection, matching `Next` with nothing checked.
+- Multi-select is a free-text input: type the option numbers, comma separated (`1,3`). Any token that is not a valid option index is treated as a typed custom answer, which is how the `Type something.` escape survives. An empty input commits an empty selection, matching `Next` with nothing checked. The exact word `chat` (any capitalisation) is the `Chat about this` escape: it closes the walk with a `chatRequested` marker for that question, like the row does in the TUI.
 - Closing any dialog cancels the whole questionnaire, the same as `Esc` in the TUI.
 
 If the host can render neither custom UI nor dialogs, the call returns `error: "no_custom_ui"` with text telling the model the user never saw the questions and to ask them as plain chat text instead. This is not a decline.
@@ -49,6 +49,7 @@ Some parts of the dialog only appear when the conditions are right:
 | Tab bar and Submit tab | The call carries more than one question |
 | `Next` row | The question is multi-select |
 | `Type something.` row | Always |
+| `Chat about this` row | Always; on the RPC multi-select path, the word `chat` in the input |
 | Side by side preview | An option carries a `preview`, and terminal and pane are both at least 100 columns |
 | Preview pane at all | Single-select questions only |
 | Collapse shortcut | `collapseKey` is not `"off"` |

package/docs/keyboard.md

@@ -21,7 +21,7 @@ The table names the default keys. The dialog follows your Pi keybindings. Confir
 
 In a multi-select question, `Enter` on a regular row toggles its checkbox just like `Space`. It does not submit. Committing the question means focusing the `Next` row and pressing `Enter`. That is intentional: it makes `Enter` a cheap way to flip boxes without leaving the home row.
 
-`Space` is blocked on two rows: `Next` is a command, not a choice, and `Type something.` is a text input where the space character belongs to your answer.
+`Space` is blocked on three rows: `Next` and `Chat about this` are commands, not choices, and `Type something.` is a text input where the space character belongs to your answer.
 
 Timeout: if the call included a `timeout`, a live countdown shows in the footer and in the collapsed hint row, like `12s left`. The first keystroke you make cancels the timer. It does not reset, it stops.
 
@@ -30,11 +30,14 @@ Timeout: if the call included a `timeout`, a live countdown shows in the footer
 | Row | Label | Added to |
 | --- | --- | --- |
 | Custom answer | `Type something.` | Every question, single-select and multi-select, with or without previews |
+| Chat escape | `Chat about this` | Every question, single-select and multi-select |
 | Commit | `Next` | Multi-select questions only |
 
 Focusing `Type something.` turns the row into an inline multiline editor. In preview mode it expands to the full pane width while you type, so a long custom answer is not squeezed into the narrow options column. `Shift+Enter` inserts a line break. Vertical arrows move between lines and return to row navigation at the top and bottom of the draft. The draft replaces the static row label while you browse other options and is kept per question. `Ctrl+G` sends it through Pi's configured external editor and brings the result back. `Ctrl+U` clears it. `Esc` is the way to cancel the questionnaire. Confirming the row produces an answer of `kind: "custom"`.
 
-Both labels are reserved. The model cannot use them as option labels. The check always compares against the English strings.
+Confirming `Chat about this` produces no answer at all: the dialog closes and the result carries a `chatRequested` marker for that question instead. The row is numbered like the rows above it but drawn under a full-width rule, because it ends the questionnaire rather than answering it. See [Tool schema](./tool-schema.md).
+
+All three labels are reserved. The model cannot use them as option labels. The check always compares against the English strings.
 
 ## Notes
 

package/docs/tool-schema.md

@@ -45,7 +45,7 @@ The two `maxLength` limits are checked by the param schema before `execute` runs
 
 ### Reserved option labels
 
-Using any of `"Other"`, `"Type something."`, or `"Next"` as an option label is rejected with `reserved_label`. The last two are the rows the dialog adds itself. `"Other"` is reserved because models are often primed to reach for it. Reservation is unconditional. A single-select question rejects `"Next"` even though that row is never added there.
+Using any of `"Other"`, `"Type something."`, `"Chat about this"`, or `"Next"` as an option label is rejected with `reserved_label`. The last three are the rows the dialog adds itself. `"Other"` is reserved because models are often primed to reach for it. Reservation is unconditional. A single-select question rejects `"Next"` even though that row is never added there.
 
 ## Validation errors
 
@@ -89,12 +89,16 @@ Every rejection returns `cancelled: true`, an empty `answers` array, and an `err
       question: string,
       note: string,
     }>,
+    chatRequested?: {              // set when the user picked "Chat about this"
+      questionIndex: number,       // the question they want to discuss first
+      question: string,
+    },
     error?: QuestionnaireError,    // one of the codes above
   }
 }
 ```
 
-`globalNote` and `unansweredNotes` use a conditional spread. The key only appears when the value is non-empty. A result with no notes has no such key at all, so `!("globalNote" in result)` holds.
+`globalNote`, `unansweredNotes` and `chatRequested` use a conditional spread. The key only appears when the value is non-empty. A result with no notes has no such key at all, so `!("globalNote" in result)` holds.
 
 ### Envelope text
 
@@ -102,23 +106,28 @@ On success the text reads `User has answered your questions: "<question>"="<answ
 
 Cancelling, and any result with no answer segments, no unanswered note segments, and no global note, both collapse to the single string `User declined to answer questions` so the model sees one clear signal. Partial submission is allowed: unanswered questions simply add no segment. A cancelled result always reads as the decline in text. Its notes, if any, survive only in `details.globalNote` and `details.unansweredNotes`.
 
+A chat request never reads as the decline. When the user picks the `Chat about this` row, the dialog closes at once and the text reads `User picked "Chat about this" on question N: "<question>"` followed by the answers already given, if any, in the same segment shape as a normal envelope. It carries no instruction — what the model should do (ask the user what they want to clarify, then wait) is stated once, in the tool description, rather than repeated in text the model reads back to itself. A custom `guidance.description` (see the config docs) replaces that instruction along with every other behavioural note the default description carries. The details carry `cancelled: true` and `chatRequested`; the picked question itself gains no answer.
+
 When `error` is `timed_out`, the text is `Questionnaire timed out, the user did not respond within the configured timeout. The user never saw a decline; do NOT treat this as a rejection. Ask the questions as plain chat text instead or retry.` The details keep `cancelled: true` and `error: "timed_out"` alongside any notes or answers the user left.
 
 ## Events
 
-The package emits one event on Pi's event bus, after validation passes and before the dialog shows. Import it from the `./events` subpath:
+The package emits lifecycle events on Pi's event bus after validation passes. Import their names and payload types from the `./events` subpath:
 
 ```ts
 import {
   ASK_POPUP_PROMPT_EVENT,
   ASK_POPUP_BLOCKED_EVENT,
+  HERDR_BLOCKED_EVENT,
   type AskPopupPromptEventPayload,
   type AskPopupBlockedEventPayload,
 } from "pi-ask-popup/events";
 ```
 
-`ASK_POPUP_PROMPT_EVENT` channel is `pi-ask-popup:prompt`. Payload is `questions[].{ question, header, multiSelect, options[] }` where each option is `{ label, description, hasPreview }`. Preview content is not shipped, only `hasPreview: boolean`, so listeners that forward the event stay small.
+`ASK_POPUP_PROMPT_EVENT` is `pi-ask-popup:prompt`. It fires once before the dialog shows. Its payload is `questions[].{ question, header, multiSelect, options[] }`, where each option is `{ label, description, hasPreview }`. Preview content is not shipped, only `hasPreview: boolean`, so listeners that forward the event stay small.
+
+`ASK_POPUP_BLOCKED_EVENT` is `pi-ask-popup:blocked`. Its payload is `{ active: boolean }`. It brackets the wait with `true` when the questionnaire starts and `false` when it resolves, so status or footer extensions can show that the agent is waiting.
 
-`ASK_POPUP_BLOCKED_EVENT` channel is `pi-ask-popup:blocked`. Payload is `{ blocked: boolean }`. It brackets the wait, true when the questionnaire starts and false when it resolves, so status or footer extensions can show that the agent is waiting.
+`HERDR_BLOCKED_EVENT` is `herdr:blocked`. It receives the same blocked payload at the same points. Herdr's Pi integration consumes this channel to mark the agent as waiting for input and issue its configured request notification. Nothing happens when Herdr is absent.
 
-Both payloads are JSON-safe. Channel names are stable. Changes are append-only and optional, and any breaking change ships as a new channel rather than a version field.
+The payloads are JSON-safe. Channel names are stable. Changes are append-only and optional, and any breaking change ships as a new channel rather than a version field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-popup",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pi extension. A tabbed terminal questionnaire the model can put to you when it would otherwise guess, with typed options, markdown previews and notes instead of free-form replies.",
   "type": "module",
   "license": "MIT",

package/src/ask-user-question.ts

@@ -22,6 +22,7 @@ import {
   ASK_POPUP_BLOCKED_EVENT,
   ASK_POPUP_PROMPT_EVENT,
   buildBlockedPayload,
+  HERDR_BLOCKED_EVENT,
   buildPromptPayload,
 } from "./events.js";
 // Static import: the walker pulls only types, none of the render graph the
@@ -88,7 +89,9 @@ function emitPrompt(pi: ExtensionAPI, params: QuestionParams): void {
 }
 
 function emitBlocked(pi: ExtensionAPI, active: boolean): void {
-  pi.events.emit(ASK_POPUP_BLOCKED_EVENT, buildBlockedPayload(active));
+  const payload = buildBlockedPayload(active);
+  pi.events.emit(ASK_POPUP_BLOCKED_EVENT, payload);
+  pi.events.emit(HERDR_BLOCKED_EVENT, payload);
 }
 
 /** The backstop for a host with no UI at all; the reconciler normally strips the tool first. */
@@ -323,7 +326,7 @@ export const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} struc
 export const DEFAULT_PROMPT_GUIDELINES: string[] = [
   `Use ask_user_question when the user's request is underspecified and you would otherwise decide for them. "I could guess and carry on" is the situation this tool exists for, not a reason to skip it — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,
   `Prefer ask_user_question over asking in prose whenever you can name the candidate answers: which approach, which library, what to call it, how far to take it, which trade-off to accept. Ask in plain text only when the answer is open-ended enough that ${MIN_OPTIONS} concrete options cannot be written.`,
-  `Each ask_user_question question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer via the automatically appended "Type something." row on every question, or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.`,
+  `Each ask_user_question question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer via the automatically appended "Type something." row on every question, or press Esc to abandon the questionnaire. Every question also carries a "Chat about this" row: if the user picks it, the dialog closes with that question unanswered, and you should open with "What would you like to clarify about that question?" and wait — never re-ask or answer over it. Do NOT author "Other", "Type something." or "Chat about this" labels yourself — reserved labels are rejected at runtime.`,
   `In ask_user_question, set multiSelect: true when multiple answers are valid. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. The "Type something." row is appended to every question; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column. If you recommend a specific option, make that the first option and append "(Recommended)" to its label.`,
   "Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.",
 ];
@@ -336,6 +339,7 @@ export const DEFAULT_TOOL_DESCRIPTION = `Ask the user one or more structured que
 
 Usage notes:
 - Users can type a custom answer via the automatically appended "Type something." row on every question or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
+- Every question also carries an automatically appended "Chat about this" row. When the user picks it, the dialog closes with that question unanswered and the tool result names it. Open by asking "What would you like to clarify about that question?" and wait. Do not answer it for them and do not re-ask it as a questionnaire. Questions answered before the pick stay answered — once the discussion resolves, put only the still-missing questions in a new ask_user_question call.
 - Use multiSelect: true when multiple answers are valid. The "Type something." row is available on every question, including when options carry a \`preview\`; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column.
 - If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label.
 

package/src/events.ts

@@ -4,11 +4,11 @@
  * This module deliberately imports nothing. A footer, statusline or notifier
  * subscribes to these channels to know what is being asked and whether the
  * agent is waiting on a person; it should not have to load a render graph, or
- * a schema compiler, to read two strings and four interfaces. Adding an import
+ * a schema compiler, to read three strings and four interfaces. Adding an import
  * here defeats the reason the `./events` subpath exists, so there is a test
  * that fails if one appears.
  *
- * Stability rules for both channels:
+ * Stability rules for these channels:
  *
  *   1. Channel names never change once published. Subscribers hardcode them.
  *   2. Payload changes are append-only, and new fields ship optional.
@@ -29,6 +29,12 @@ export const ASK_POPUP_PROMPT_EVENT = "pi-ask-popup:prompt" as const;
 /** Fired true before the wait and false when it ends, however it ends. */
 export const ASK_POPUP_BLOCKED_EVENT = "pi-ask-popup:blocked" as const;
 
+/**
+ * Herdr's Pi integration listens on this shared channel for nested UI that
+ * needs a decision. Emitting it is inert when Herdr is not installed.
+ */
+export const HERDR_BLOCKED_EVENT = "herdr:blocked" as const;
+
 export interface AskPopupPromptOption {
   label: string;
   description: string;

package/src/index.ts

@@ -13,6 +13,7 @@ import { registerAskPopupReconciler } from "./reconcile.js";
 export {
   ASK_POPUP_BLOCKED_EVENT,
   ASK_POPUP_PROMPT_EVENT,
+  HERDR_BLOCKED_EVENT,
   type AskPopupBlockedEventPayload,
   type AskPopupPromptEventPayload,
   type AskPopupPromptOption,

package/src/rpc-fallback.ts

@@ -18,7 +18,9 @@
  * for them, and inventing a second dialog to collect one would double the
  * number of prompts for something most answers never use.
  *
- * The "Type something." escape does survive, on both variants.
+ * The "Type something." escape and the "Chat about this" escape both survive,
+ * on both variants: the select lists carry both rows, and the multi-select
+ * input accepts the word `chat` as the row's counterpart.
  */
 
 import { ROW_INTENT_META } from "./state/row-intent.js";
@@ -30,9 +32,11 @@ import type {
 } from "./tool/types.js";
 
 const MULTI_SELECT_INSTRUCTIONS =
-  'Enter the numbers of all that apply, comma-separated (e.g. "1,3"), or type a custom answer as plain text.';
+  'Enter the numbers of all that apply, comma-separated (e.g. "1,3"), or type a custom answer as plain text. Reply "chat" to set this question aside and discuss it in chat instead.';
 const CUSTOM_ANSWER_TITLE = "Type your answer:";
 const MULTI_SELECT_PLACEHOLDER = "1,3";
+/** The word a multi-select input reply must equal to trigger the chat escape. */
+const CHAT_KEYWORD = "chat";
 
 /** How much of an option's preview is folded into a select title before truncation. */
 const MAX_PREVIEW_CHARS = 600;
@@ -80,6 +84,7 @@ export function hasDialogUI(ui: unknown): ui is DialogUI {
  */
 type AskOutcome =
   | { kind: "answer"; answer: QuestionAnswer }
+  | { kind: "chat"; question: string }
   | { kind: "dismissed" }
   | { kind: "host_error"; detail: string };
 
@@ -138,6 +143,16 @@ export async function runRpcQuestionnaire(
     if (outcome.kind === "dismissed") {
       return { answers, cancelled: true };
     }
+    if (outcome.kind === "chat") {
+      // Same shape the overlay's chat row produces: everything answered before
+      // this question rides along, the marker names this one, and the rest of
+      // the walk is abandoned.
+      return {
+        answers,
+        cancelled: true,
+        chatRequested: { questionIndex: qi, question: outcome.question },
+      };
+    }
     if (outcome.kind === "host_error") {
       return { answers, cancelled: true, error: "host_error", hostErrorDetail: outcome.detail };
     }
@@ -156,6 +171,7 @@ async function askSingleSelect(
 ): Promise<AskOutcome> {
   const options = q.options.map(formatOptionLine);
   options.push(`${q.options.length + 1}. ${ROW_INTENT_META.other.label}`);
+  options.push(`${q.options.length + 2}. ${ROW_INTENT_META.chat.label}`);
   const chosen = await ui.select(`${header}${q.question}${buildPreviewBlock(q)}`, options, opts);
   if (chosen === undefined || chosen === null) {
     return DISMISSED;
@@ -182,6 +198,11 @@ async function askSingleSelect(
     }
     return { kind: "answer", answer };
   }
+  // The "Chat about this" row, one index past the authored options plus the
+  // free-text row.
+  if (idx === q.options.length + 1) {
+    return { kind: "chat", question: q.question };
+  }
   // The "Type something." row, which is the one index past the authored options.
   const typed = await ui.input(`${header}${q.question}\n\n${CUSTOM_ANSWER_TITLE}`, "", opts);
   if (typed === undefined || typed === null) {
@@ -227,6 +248,15 @@ async function askMultiSelect(
       answer: { questionIndex, question: q.question, kind: "multi", answer: null, selected: [] },
     };
   }
+  // The chat escape. There is no row to focus in an input dialog, so the word
+  // itself is the affordance, and it is matched exactly rather than split into
+  // tokens: a reply of "1, chat, 3" is a custom answer naming the word, not a
+  // mixed selection, and pretending otherwise would answer a question the user
+  // asked to set aside. Case-insensitive because the instructions show it
+  // lowercase and no dialog here punishes capitalisation anywhere else.
+  if (trimmed.toLowerCase() === CHAT_KEYWORD) {
+    return { kind: "chat", question: q.question };
+  }
   const tokens = trimmed.split(/[,\s]+/).filter((tok) => tok.length > 0);
   const indices = tokens.map((tok) =>
     /^\d+\.?$/.test(tok) ? parseIndex(tok, q.options.length) : null,

package/src/state/key-router.ts

@@ -40,6 +40,13 @@ export type QuestionnaireAction =
   | { kind: "confirm"; answer: QuestionAnswer; autoAdvanceTab?: number | undefined }
   | { kind: "toggle"; index: number }
   | { kind: "multi_confirm"; selected: string[]; autoAdvanceTab?: number | undefined }
+  /**
+   * The user picked the "Chat about this" row on the current tab: close the
+   * dialog, keep the answers already given, and mark this question as the one
+   * they want to discuss before answering. Ends the questionnaire like
+   * `cancel`, but with the marker attached.
+   */
+  | { kind: "chat_request" }
   | { kind: "cancel" }
   | { kind: "notes_enter" }
   | { kind: "notes_exit" }
@@ -127,6 +134,12 @@ function buildSingleSelectAnswer(
   if (item.kind === "other") {
     return null;
   }
+  if (item.kind === "chat") {
+    // Not an answer. Enter on this row is intercepted in routeSingleSelectTab
+    // before it gets here; this branch is the defensive backstop that keeps a
+    // chat row from ever minting an answer.
+    return null;
+  }
   if (item.kind === "next") {
     return null;
   }
@@ -363,6 +376,14 @@ function routeMultiSelectTab(
     if (!focusedMeta?.autoSubmitsInMulti) {
       return { kind: "toggle", index: state.optionIndex };
     }
+    // Enter on the chat row ends the questionnaire with the current tab marked
+    // for discussion, keeping whatever boxes are ticked as its answer. It
+    // shares `autoSubmitsInMulti` with Next but performs a different commit,
+    // so it is dispatched by kind rather than falling through to
+    // `multi_confirm`, which would advance instead of closing.
+    if (focusedKind === "chat") {
+      return { kind: "chat_request" };
+    }
     // Enter on Next: carry autoAdvanceTab so the host can advance to the next tab in
     // multi-question mode, OR submit the dialog in single-question mode
     // (autoAdvanceTab === undefined when !isMulti). Without this, a single multi-select
@@ -386,6 +407,10 @@ function routeSingleSelectTab(
   runtime: QuestionnaireRuntime,
 ): QuestionnaireAction {
   if (isConfirm(kb, data)) {
+    // Enter on the chat row abandons the questionnaire instead of answering.
+    if (runtime.currentItem?.kind === "chat") {
+      return { kind: "chat_request" };
+    }
     const answer = buildSingleSelectAnswer(state, runtime);
     if (!answer) {
       return { kind: "ignore" };

package/src/state/row-intent.ts

@@ -11,15 +11,19 @@ import type { QuestionData } from "../tool/types.js";
  * `Record<RowKind, ...>`) AND every exhaustive switch in the renderer, so a new
  * row cannot ship half-wired.
  */
-export type RowKind = "option" | "other" | "next";
+export type RowKind = "option" | "other" | "chat" | "next";
 
 /**
  * Sentinel kinds: the protocol-driven rows, as opposed to author-defined
  * `option` rows. The auto-append walker, the reserved-label derivation and
  * `LABELS_BY_KIND` all iterate this list.
+ *
+ * Order is the append order on every question: options, the free-text row, the
+ * chat row, the commit row. The chat row sits before "Next" because it reads
+ * as another way out, not as the primary action.
  */
 export type SentinelKind = Exclude<RowKind, "option">;
-export const SENTINEL_KINDS: readonly SentinelKind[] = ["other", "next"];
+export const SENTINEL_KINDS: readonly SentinelKind[] = ["other", "chat", "next"];
 
 /**
  * One renderable row. Lives here rather than in the view because it is the
@@ -56,13 +60,16 @@ export interface WrappingSelectItem {
  *   validation time. `RESERVED_LABEL_SET` derives from this flag.
  * - `livesInMainList` — the row appears in the tab's item array.
  * - `numbered` — the row contributes to main-list numbering. The multi-select
- *   `Next` row is the only listed row that does not.
+ *   `Next` row is drawn bare by `MultiSelectView`, which does its own
+ *   numbering; the `chat` row keeps its number there too.
  * - `activatesInputMode` — focusing the row flips `state.inputMode`, turning it
  *   into an inline editor. Read by the reducer's `nav` case.
  * - `blocksMultiToggle` — in multi-select, Space and Enter-as-toggle are
- *   suppressed on this row. `Next` only.
+ *   suppressed on this row. `Next` and `chat` only.
  * - `autoSubmitsInMulti` — in multi-select, Enter on this row commits the
- *   question. `Next` only.
+ *   question. `Next` and `chat` only.
+ * - `separatorAbove` — the renderer draws a full-width rule above the row,
+ *   setting it off from the answer list. `chat` only.
  * - `autoAppendOnSingleSelect` / `autoAppendOnMultiSelect` — whether the item
  *   builder appends this row in that mode.
  */
@@ -76,6 +83,7 @@ export interface RowIntentMeta {
   autoSubmitsInMulti: boolean;
   autoAppendOnSingleSelect: boolean;
   autoAppendOnMultiSelect: boolean;
+  separatorAbove: boolean;
 }
 
 export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
@@ -89,6 +97,7 @@ export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
     autoSubmitsInMulti: false,
     autoAppendOnSingleSelect: false,
     autoAppendOnMultiSelect: false,
+    separatorAbove: false,
   },
   other: {
     label: "Type something.",
@@ -100,6 +109,32 @@ export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
     autoSubmitsInMulti: false,
     autoAppendOnSingleSelect: true,
     autoAppendOnMultiSelect: true,
+    separatorAbove: false,
+  },
+  /**
+   * The "Chat about this" row. Selecting it abandons the questionnaire: the
+   * dialog closes and the tool result carries a `chatRequested` marker for the
+   * question it was picked on, so the model stops and treats the user's next
+   * chat message as a clarification of that question. It is a decision, not an
+   * answer — no `QuestionAnswer` is minted for it.
+   *
+   * It is numbered like the rows above it but sits under a full-width rule,
+   * because it is not one of the answers: it ends the questionnaire. In
+   * multi-select it shares `autoSubmitsInMulti` and `blocksMultiToggle` with
+   * `next`, even though the commit it performs closes the dialog rather than
+   * advancing a tab.
+   */
+  chat: {
+    label: "Chat about this",
+    reserved: true,
+    livesInMainList: true,
+    numbered: true,
+    activatesInputMode: false,
+    blocksMultiToggle: true,
+    autoSubmitsInMulti: true,
+    autoAppendOnSingleSelect: true,
+    autoAppendOnMultiSelect: true,
+    separatorAbove: true,
   },
   next: {
     label: "Next",
@@ -111,6 +146,7 @@ export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
     autoSubmitsInMulti: true,
     autoAppendOnSingleSelect: false,
     autoAppendOnMultiSelect: true,
+    separatorAbove: false,
   },
 };
 
@@ -120,6 +156,7 @@ export const ROW_INTENT_META: Record<RowKind, RowIntentMeta> = {
  */
 export const LABELS_BY_KIND: { readonly [K in SentinelKind]: string } = {
   other: ROW_INTENT_META.other.label,
+  chat: ROW_INTENT_META.chat.label,
   next: ROW_INTENT_META.next.label,
 };
 
@@ -131,7 +168,9 @@ export const LABELS_BY_KIND: { readonly [K in SentinelKind]: string } = {
  */
 export const RESERVED_LABEL_SET: ReadonlySet<string> = new Set<string>([
   "Other",
-  ...SENTINEL_KINDS.filter((k) => ROW_INTENT_META[k].reserved).map((k) => ROW_INTENT_META[k].label),
+  // A flatMap because the filter and the projection read the same meta entry;
+  // two passes would walk SENTINEL_KINDS twice for one set.
+  ...SENTINEL_KINDS.flatMap((k) => (ROW_INTENT_META[k].reserved ? [ROW_INTENT_META[k].label] : [])),
 ]);
 
 /**

package/src/state/selectors/projections.ts

@@ -27,6 +27,7 @@ function emptyMultiSelectProps(ctx: PerTabBindingContext): MultiSelectViewProps
       inputBuffer: ctx.inputBuffer,
       inputCursorOffset: ctx.inputCursorOffset,
     },
+    chatActive: false,
     nextActive: false,
     nextLabel: LABELS_BY_KIND.next,
   };
@@ -66,7 +67,10 @@ export const selectMultiSelectProps: PerTabSelector<MultiSelectViewProps> = (sta
       inputBuffer: ctx.inputBuffer,
       inputCursorOffset: ctx.inputCursorOffset,
     },
-    nextActive: focused && state.optionIndex === question.options.length + 1,
+    // Row order below the options is the free-text row, then the chat row,
+    // then the commit row — `SENTINEL_KINDS` order.
+    chatActive: focused && state.optionIndex === question.options.length + 1,
+    nextActive: focused && state.optionIndex === question.options.length + 2,
     nextLabel: nextLabelFor(ctx),
   };
 };

package/src/state/state-reducer.ts

@@ -1,4 +1,5 @@
 import type {
+  ChatRequested,
   QuestionAnswer,
   QuestionData,
   QuestionnaireResult,
@@ -216,7 +217,19 @@ function switchTabResult(
   };
 }
 
-function doneFor(state: QuestionnaireState, ctx: ApplyContext, cancelled: boolean): ApplyResult {
+/**
+ * Lift the dialog's state into its terminal `QuestionnaireResult`.
+ *
+ * `chatRequested` rides only on a chat-request close, which is why it is a
+ * parameter and not a state read: nothing else that lands here — submit,
+ * cancel, confirm's final tab, timeout — carries one.
+ */
+function doneFor(
+  state: QuestionnaireState,
+  ctx: ApplyContext,
+  cancelled: boolean,
+  chatRequested?: ChatRequested,
+): ApplyResult {
   // Global note lift: the Submit-tab note lives at the `questions.length` pseudo-index
   // in `notesByTab` — question tabs only occupy 0..questions.length-1, so this can never
   // cross-contaminate a per-question note. Attached regardless of `cancelled` (the
@@ -231,6 +244,12 @@ function doneFor(state: QuestionnaireState, ctx: ApplyContext, cancelled: boolea
     answers: orderedAnswers(state, ctx.questions),
     cancelled,
   };
+  if (chatRequested) {
+    // SAFETY: conditional spread by assignment — chatRequested is present only when the
+    // caller passed one, keeping note-free results byte-identical like globalNote.
+    (result as QuestionnaireResult & { chatRequested: ChatRequested }).chatRequested =
+      chatRequested;
+  }
   if (globalNote && globalNote.length > 0) {
     // SAFETY: globalNote is optional per QuestionnaireResult; present only when non-empty.
     (result as QuestionnaireResult & { globalNote: string }).globalNote = globalNote;
@@ -407,6 +426,28 @@ const notesExitHandler: Handler<"notes_exit"> = (state, _action, _ctx) => {
 };
 
 const cancelHandler: Handler<"cancel"> = (s, _a, c) => doneFor(s, c, true);
+/**
+ * Enter on the "Chat about this" row.
+ *
+ * The current tab's multi-select state is persisted first, so the ticked boxes
+ * (and any text typed on the "Type something." row) stay the question's answer
+ * — picking the row means "discuss before I answer this one", not "forget what
+ * I ticked". On a single-select tab there is nothing in flight to persist, and
+ * the call is a no-op by construction. The marker names the tab the row was
+ * picked on; tabs after it stay unanswered.
+ */
+const chatRequestHandler: Handler<"chat_request"> = (state, _action, ctx) => {
+  const q = ctx.questions[state.currentTab];
+  if (!q) {
+    return { state, effects: [] };
+  }
+  const answers = persistMultiSelectAnswer(state, ctx);
+  const next: QuestionnaireState = { ...state, answers };
+  return doneFor(next, ctx, true, {
+    questionIndex: state.currentTab,
+    question: q.question,
+  });
+};
 const submitHandler: Handler<"submit"> = (s, _a, c) => doneFor(s, c, false);
 const submitNavHandler: Handler<"submit_nav"> = (s, a, _c) => ({
   state: { ...s, submitChoiceIndex: a.nextIndex },
@@ -458,6 +499,7 @@ const HANDLERS = {
   toggle: toggleHandler,
   multi_confirm: multiConfirmHandler,
   cancel: cancelHandler,
+  chat_request: chatRequestHandler,
   notes_enter: notesEnterHandler,
   notes_exit: notesExitHandler,
   notes_forward: notesForwardHandler,

package/src/tool/response-envelope.ts

@@ -1,5 +1,7 @@
 import { formatAnswerScalar } from "./format-answer.js";
+import { ROW_INTENT_META } from "../state/row-intent.js";
 import type {
+  ChatRequested,
   QuestionAnswer,
   QuestionnaireResult,
   QuestionParams,
@@ -70,6 +72,27 @@ export function buildQuestionnaireResponse(
     }
     return buildToolResult(HOST_ERROR_MESSAGE, details);
   }
+  if (result?.chatRequested) {
+    // A chat request is a decision, so it must not reach the decline collapse
+    // below: the model would read "User declined to answer questions" for a
+    // user who asked to talk. Segments are built for the answered questions
+    // even though the marker alone already makes the result non-empty — a
+    // chat close with nothing answered is still a chat close.
+    const cr = result.chatRequested;
+    const details: QuestionnaireResult = {
+      answers: result.answers,
+      cancelled: true,
+      chatRequested: cr,
+    };
+    if (result.globalNote && result.globalNote.length > 0) {
+      (details as { globalNote: string }).globalNote = result.globalNote;
+    }
+    if (result.unansweredNotes && result.unansweredNotes.length > 0) {
+      (details as { unansweredNotes: typeof result.unansweredNotes }).unansweredNotes =
+        result.unansweredNotes;
+    }
+    return buildToolResult(buildChatRequestMessage(cr, collectSegments(result, params)), details);
+  }
   if (!result || result.cancelled) {
     // The decline text stays canonical even when a global note rides a
     // cancelled result. The note survives in `details`, like partial answers.
@@ -90,51 +113,79 @@ export function buildQuestionnaireResponse(
     return buildToolResult(DECLINE_MESSAGE, details);
   }
 
-  // Indexed once rather than scanned per question. Both sides are keyed by
-  // `questionIndex`, which is what the loop below asks for, and it is the same
-  // shape `orderedAnswers` uses in the reducer. A first entry wins, so a
-  // duplicated index reads as the earlier `find` did.
+  // Indexed once per segment walk inside `collectSegments`; nothing here needs
+  // the maps directly.
+  const segments = collectSegments(result, params);
+  if (segments.length === 0) {
+    return buildToolResult(DECLINE_MESSAGE, { answers: result.answers, cancelled: true });
+  }
+  return buildToolResult(`${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`, result);
+}
+
+/** First entry per `questionIndex` wins, which is what `Array.find` did. */
+function byQuestionIndex<T extends { questionIndex: number }>(items: readonly T[]): Map<number, T> {
+  const out = new Map<number, T>();
+  for (const item of items) {
+    if (!out.has(item.questionIndex)) {
+      out.set(item.questionIndex, item);
+    }
+  }
+  return out;
+}
+
+/**
+ * The envelope segments for one result, in ask order.
+ *
+ * Iterates the questions rather than the answers so segments always follow the
+ * order the model asked in, whatever order the user filled tabs. A note with no
+ * answer behind it still belongs in ask order, so it is emitted inline rather
+ * than grouped at the end — which is also why a questionnaire submitted with
+ * nothing but such a note counts as answered rather than declined. The global
+ * note rides last, echoed raw with a trailing period matching an answer
+ * segment's shape.
+ */
+function collectSegments(result: QuestionnaireResult, params: QuestionParams): string[] {
   const answerByIndex = byQuestionIndex(result.answers);
   const noteByIndex = byQuestionIndex(result.unansweredNotes ?? []);
-
   const segments: string[] = [];
-  // Iterate the questions rather than the answers so segments always follow the
-  // order the model asked in, whatever order the user filled tabs.
   for (let i = 0; i < params.questions.length; i++) {
     const a = answerByIndex.get(i);
     if (a) {
       segments.push(buildAnswerSegment(a));
       continue;
     }
-    // A note with no answer behind it still belongs in ask order, so it is
-    // emitted here rather than grouped at the end. Because this loop runs
-    // before the "nothing to report" check below, a questionnaire submitted
-    // with nothing but such a note counts as answered rather than declined.
     const n = noteByIndex.get(i);
     if (n) {
       segments.push(buildUnansweredNoteSegment(n));
     }
   }
   if (result.globalNote && result.globalNote.length > 0) {
-    // Raw multiline echo, no reformatting, trailing period matching the shape
-    // of an answer segment.
     segments.push(`global note: ${result.globalNote}.`);
   }
-  if (segments.length === 0) {
-    return buildToolResult(DECLINE_MESSAGE, { answers: result.answers, cancelled: true });
-  }
-  return buildToolResult(`${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`, result);
+  return segments;
 }
 
-/** First entry per `questionIndex` wins, which is what `Array.find` did. */
-function byQuestionIndex<T extends { questionIndex: number }>(items: readonly T[]): Map<number, T> {
-  const out = new Map<number, T>();
-  for (const item of items) {
-    if (!out.has(item.questionIndex)) {
-      out.set(item.questionIndex, item);
-    }
+/**
+ * The envelope for a "Chat about this" close.
+ *
+ * States facts only — which question, and the answers already given in ask
+ * order — with no instruction to act on them. What the model does next (ask
+ * the user what they want to clarify, then wait) lives in the tool description
+ * and prompt guidelines, the standing-instruction channels, not here. An
+ * imperative placed in this text got echoed verbatim as the model's reply, so
+ * this string carries none.
+ */
+function buildChatRequestMessage(
+  chatRequested: ChatRequested,
+  segments: readonly string[],
+): string {
+  const parts: string[] = [
+    `User picked "${ROW_INTENT_META.chat.label}" on question ${chatRequested.questionIndex + 1}: "${chatRequested.question}"`,
+  ];
+  if (segments.length > 0) {
+    parts.push(segments.join(" "));
   }
-  return out;
+  return parts.join(" ");
 }
 
 /**

package/src/tool/types.ts

@@ -40,6 +40,7 @@ export type SentinelLabel = (typeof SENTINEL_LABELS)[keyof typeof SENTINEL_LABEL
 export const RESERVED_LABELS = [
   "Other",
   ROW_INTENT_META.other.label,
+  ROW_INTENT_META.chat.label,
   ROW_INTENT_META.next.label,
 ] as const;
 export type ReservedLabel = (typeof RESERVED_LABELS)[number];
@@ -74,7 +75,7 @@ export const QuestionSchema = Type.Object({
     minItems: MIN_OPTIONS,
     maxItems: MAX_OPTIONS,
     description:
-      "The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). The 'Type something.' row is appended automatically — do NOT author it.",
+      "The available choices for this question. Must have 2-4 options. Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). The 'Type something.' row and the 'Chat about this' row are appended automatically — do NOT author them.",
   }),
   multiSelect: Type.Optional(
     Type.Boolean({
@@ -113,6 +114,10 @@ export type QuestionParams = Static<typeof QuestionParamsSchema>;
  * - `option` — the user picked an authored option. `answer` is its label.
  * - `custom` — the user typed free text in the "Type something." row.
  *   `answer` is the text, or null when they committed nothing.
+ *
+ * A "Chat about this" selection never becomes one of these: it is a decision
+ * to stop and discuss, and it travels on `QuestionnaireResult.chatRequested`
+ * instead of minting a pseudo-answer here.
  * - `multi` — the user committed multi-select choices. `selected` carries the
  *   chosen labels and `answer` is null. Text typed on the "Type something." row
  *   appears in `selected` too, as its own trimmed entry: on a multi-select
@@ -168,9 +173,26 @@ export type QuestionnaireError =
   | "timed_out"
   | "host_error";
 
+export interface ChatRequested {
+  questionIndex: number;
+  question: string;
+}
+
 export interface QuestionnaireResult {
   answers: QuestionAnswer[];
   cancelled: boolean;
+  /**
+   * The user selected the "Chat about this" sentinel, closing the dialog
+   * without answering this question, and wants to discuss it in chat first.
+   * Attached only on a chat-request result — never on a submit, decline or
+   * timeout.
+   *
+   * Same conditional-spread contract as `globalNote`: the key appears only via
+   * conditional spread of a non-empty value, is never assigned `undefined`, and
+   * so a result with no chat request stays byte-identical and
+   * `!("chatRequested" in result)` holds.
+   */
+  chatRequested?: ChatRequested;
   /**
    * A note covering the whole questionnaire rather than one question, authored
    * on the Submit tab. Attached on cancel as well as submit, mirroring

package/src/view/components/multi-select-view.ts

@@ -37,6 +37,7 @@ export interface MultiSelectOtherRowProps {
 export interface MultiSelectViewProps {
   rows: ReadonlyArray<{ checked: boolean; active: boolean }>;
   other: MultiSelectOtherRowProps;
+  chatActive: boolean;
   nextActive: boolean;
   nextLabel: string;
 }
@@ -80,6 +81,7 @@ export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
         inputBuffer: "",
         inputCursorOffset: undefined,
       },
+      chatActive: false,
       nextActive: false,
       nextLabel: ROW_INTENT_META.next.label,
     };
@@ -115,7 +117,8 @@ export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
 
     const build: MultiSelectBuild = { lines: [], focusedRange: [0, 0] };
     const contentWidth = Math.max(1, width - this.prefixVisibleWidth());
-    const numberWidth = String(Math.max(1, this.question.options.length + 1)).length;
+    // Fits the chat row's N+2, the highest number the list can draw.
+    const numberWidth = String(Math.max(1, this.question.options.length + 2)).length;
 
     this.appendOptionRows(build, width, contentWidth, numberWidth);
 
@@ -125,6 +128,8 @@ export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
       build.focusedRange = [otherStart, build.lines.length];
     }
 
+    this.appendChatRow(build, width, numberWidth);
+
     this.appendNextRow(build, width);
 
     const value = { lines: build.lines, focusedRange: build.focusedRange };
@@ -171,6 +176,32 @@ export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
     }
   }
 
+  /**
+   * The "Chat about this" row, drawn bare like the commit row: no number, no
+   * checkbox. It closes the dialog rather than toggling anything, so painting
+   * it as a box would promise a behavior it does not have. It keeps its place
+   * in the numbering (N+2, after the free-text row's N+1) but sits under a
+   * full-width rule, matching the single-select list's separator. Sits between
+   * the free-text row and the commit row, matching `SENTINEL_KINDS` order.
+   */
+  private appendChatRow(build: MultiSelectBuild, width: number, numberWidth: number): void {
+    const chatStart = build.lines.length;
+    build.lines.push("\u2500".repeat(Math.max(0, width)));
+    const chatPointer = this.props.chatActive
+      ? this.theme.fg("accent", ACTIVE_POINTER)
+      : INACTIVE_POINTER;
+    const number = String(this.question.options.length + 2).padStart(numberWidth, " ");
+    const chatLabel = this.props.chatActive
+      ? this.theme.fg("accent", this.theme.bold(ROW_INTENT_META.chat.label))
+      : ROW_INTENT_META.chat.label;
+    build.lines.push(
+      truncateToWidth(`${chatPointer}${number}${NUMBER_SEPARATOR}${chatLabel}`, width, ""),
+    );
+    if (this.props.chatActive) {
+      build.focusedRange = [chatStart, build.lines.length];
+    }
+  }
+
   private appendNextRow(build: MultiSelectBuild, width: number): void {
     const nextStart = build.lines.length;
     const nextPointer = this.props.nextActive
@@ -219,11 +250,11 @@ export class MultiSelectView implements StatefulView<MultiSelectViewProps> {
     // Canonical prefix for OPTION rows: INACTIVE_POINTER + numberWidth digits + NUMBER_SEPARATOR
     // + UNCHECKED + BOX_LABEL_GAP. State-independent because ACTIVE/INACTIVE pointer share
     // visibleWidth, CHECKED/UNCHECKED share visibleWidth, and numberWidth is constant per question.
-    // The number column fits `options.length + 1` so the "Type something." row's N+1 number
+    // The number column fits `options.length + 2` so the "Chat about this" row's N+2 number
     // is never clipped. The Next sentinel uses a bare `pointer + "Next"` shape — its width
     // never exceeds this prefix at any reasonable terminal width, so it's safe to leave it
     // out of the canonical computation.
-    const numberWidth = String(Math.max(1, this.question.options.length + 1)).length;
+    const numberWidth = String(Math.max(1, this.question.options.length + 2)).length;
     return (
       visibleWidth(INACTIVE_POINTER) +
       numberWidth +

package/src/view/components/wrapping-select.ts

@@ -1,4 +1,5 @@
 import type { WrappingSelectItem } from "../../state/row-intent.js";
+import { ROW_INTENT_META } from "../../state/row-intent.js";
 import type { Component } from "@earendil-works/pi-tui";
 import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { renderInlineInputRow } from "./inline-input.js";
@@ -286,14 +287,27 @@ export class WrappingSelect implements Component {
       width - visibleWidth(rowPrefix),
     );
 
+    // A row that ends the questionnaire rather than answering it is drawn
+    // under a full-width rule, so it reads as outside the answer list. The
+    // rule is part of the item's own render, which keeps the visible-window
+    // arithmetic honest: the rule scrolls with the row and the focused range
+    // covers both.
+    const separator = ROW_INTENT_META[item.kind].separatorAbove
+      ? [this.theme.scrollInfo("\u2500".repeat(Math.max(0, width)))]
+      : [];
+
     if (this.shouldRenderAsInlineInput(item, isActive)) {
-      return this.renderInlineInputRow(rowPrefix, continuationPrefix, contentWidth);
+      return [
+        ...separator,
+        ...this.renderInlineInputRow(rowPrefix, continuationPrefix, contentWidth),
+      ];
     }
 
     const { label, isConfirmed } = this.deriveConfirmedState(item, index);
     const applySelectedStyle = isActive || isConfirmed;
 
     return [
+      ...separator,
       ...this.renderLabelBlock(
         label,
         rowPrefix,