@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/ask-user/clipboard.ts

@@ -0,0 +1,50 @@
+/**
+ * @pi-unipi/ask-user — read an image from the system clipboard into a temp file
+ *
+ * pi's own clipboard reader is not exported, so Ctrl+V inside "Other" uses the
+ * usual tools: wl-paste (Wayland), xclip (X11), pngpaste (macOS). Returns the
+ * file path, or undefined when there is no image (or no clipboard — e.g. SSH).
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+function run(cmd: string, args: string[]): Buffer | undefined {
+  try {
+    const r = spawnSync(cmd, args, { timeout: 3000, maxBuffer: 64 * 1024 * 1024 });
+    return r.status === 0 && r.stdout && r.stdout.length > 0 ? r.stdout : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+const EXT: Record<string, string> = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp", "image/gif": ".gif" };
+
+export function readClipboardImageFile(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  let data: Buffer | undefined;
+  let type = "image/png";
+  if (process.platform === "darwin") {
+    data = run("pngpaste", ["-"]);
+  } else {
+    const wayland = !!env.WAYLAND_DISPLAY;
+    const listed = wayland
+      ? run("wl-paste", ["--list-types"])?.toString()
+      : run("xclip", ["-selection", "clipboard", "-t", "TARGETS", "-o"])?.toString();
+    const found = TYPES.find((t) => listed?.split(/\s+/).includes(t));
+    if (!found) return undefined;
+    type = found;
+    data = wayland ? run("wl-paste", ["--type", found]) : run("xclip", ["-selection", "clipboard", "-t", found, "-o"]);
+  }
+  if (!data) return undefined;
+  const file = join(tmpdir(), `unipi-ask-${randomUUID()}${EXT[type] ?? ".png"}`);
+  try {
+    writeFileSync(file, data);
+    return file;
+  } catch {
+    return undefined;
+  }
+}

package/packages/ask-user/config.ts

@@ -1,55 +1,41 @@
 /**
- * @pi-unipi/ask-user — Config system
+ * @pi-unipi/ask-user — settings (namespace `ask-user`, /unipi:settings → Ask User)
  *
- * Reads/writes ask-user settings in ~/.pi/agent/settings.json
- * under the "unipi.askUser" key.
+ *   enabled        — give the agent the ask_user tool (OFF by default)
+ *   notifyOnAsk    — notification when the agent stops to ask
+ *   escape         — stop: Esc stops the agent's turn (Devin)
+ *                    send: Esc sends what's answered, the rest as skipped
+ *   digitAdvance   — a number key in a single-choice question also moves on
+ *   helpLine       — show "? Not ready to answer, help me out!"
+ *   other          — agent: the agent decides (on unless it sets other:false)
+ *                    always / never: override the agent
+ *   maxQuestions   — questions per call the agent may ask (1–4)
+ *
+ * Read fresh on every call, so changes in the hub apply to the next question.
  */
 
 import { getSettings, registerSettings, setSettings } from "@pi-unipi/core";
 
-/** Ask-user settings */
 export interface AskUserSettings {
-  /** Whether the ask_user tool is enabled */
   enabled: boolean;
-  /** Allowed question formats */
-  allowedFormats: {
-    /** Allow single-select questions */
-    singleSelect: boolean;
-    /** Allow multi-select questions */
-    multiSelect: boolean;
-    /** Allow freeform text input */
-    freeform: boolean;
-  };
-  /** Send notification when agent pauses to ask a question */
   notifyOnAsk: boolean;
+  escape: "stop" | "send";
+  digitAdvance: boolean;
+  helpLine: boolean;
+  other: "agent" | "always" | "never";
+  maxQuestions: number;
 }
 
-/** Default settings */
 export const DEFAULT_SETTINGS: AskUserSettings = {
-  enabled: true,
-  allowedFormats: {
-    singleSelect: true,
-    multiSelect: true,
-    freeform: true,
-  },
+  enabled: false,
   notifyOnAsk: true,
+  escape: "stop",
+  digitAdvance: true,
+  helpLine: true,
+  other: "agent",
+  maxQuestions: 4,
 };
 
-
-let cachedSettings: AskUserSettings | null = null;
-
-/**
- * Check if value is a plain object.
- */
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * Get ask-user settings from settings.json.
- */
-// Registered with the unified settings hub. The engine's migration imports
-// the legacy ~/.pi/agent/settings.json unipi.askUser block once automatically.
 registerSettings({
   namespace: "ask-user",
   label: "Ask User",
@@ -58,58 +44,68 @@ registerSettings({
     {
       title: "Tool",
       fields: [
-        { key: "enabled", type: "boolean", label: "Enable ask_user tool", description: "Allow the agent to ask structured questions" },
-        { key: "notifyOnAsk", type: "boolean", label: "Notify on ask", description: "Send a notification when the agent pauses to ask" },
+        { key: "enabled", type: "boolean", label: "Enable ask_user", description: "Let the agent stop and ask you multiple-choice questions" },
+        { key: "notifyOnAsk", type: "boolean", label: "Notify when asked", description: "Send a notification when the agent is waiting for your answer" },
+        { key: "maxQuestions", type: "number", label: "Questions per call", min: 1, max: 4, description: "How many questions one dialog may hold (applies to new sessions)" },
       ],
     },
     {
-      title: "Allowed formats",
+      title: "Dialog",
+      description: "How the question dialog behaves",
       fields: [
-        { key: "allowedFormats.singleSelect", type: "boolean", label: "Single-select", description: "Questions with one correct answer" },
-        { key: "allowedFormats.multiSelect", type: "boolean", label: "Multi-select", description: "Questions with several answers" },
-        { key: "allowedFormats.freeform", type: "boolean", label: "Freeform", description: "Plain text input" },
+        {
+          key: "escape",
+          type: "enum",
+          label: "Esc",
+          options: [
+            { value: "stop", label: "stop the agent's turn" },
+            { value: "send", label: "send what's answered (rest skipped)" },
+          ],
+          description: "What Esc does in the dialog",
+        },
+        { key: "digitAdvance", type: "boolean", label: "Number keys move on", description: "In a single-choice question, picking with 1–9 also goes to the next question" },
+        {
+          key: "other",
+          type: "enum",
+          label: "\"Other\" choice",
+          options: [
+            { value: "agent", label: "agent decides (default on)" },
+            { value: "always", label: "always offer it" },
+            { value: "never", label: "never offer it" },
+          ],
+          description: "The free-text \"Other (type your own)\" row",
+        },
+        { key: "helpLine", type: "boolean", label: "\"Not ready\" line", description: "Show \"? Not ready to answer, help me out!\" under the dialog" },
       ],
     },
   ],
 });
 
-export function getAskUserSettings(): AskUserSettings {
-  if (cachedSettings) return cachedSettings;
-  const askUser = getSettings("ask-user", process.cwd()) as Record<string, unknown>;
-  if (!isRecord(askUser)) {
-    cachedSettings = { ...DEFAULT_SETTINGS };
-    return cachedSettings;
-  }
-
-  const enabled = typeof askUser.enabled === "boolean" ? askUser.enabled : DEFAULT_SETTINGS.enabled;
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
-  let allowedFormats = DEFAULT_SETTINGS.allowedFormats;
-  if (isRecord(askUser.allowedFormats)) {
-    const fmt = askUser.allowedFormats;
-    allowedFormats = {
-      singleSelect: typeof fmt.singleSelect === "boolean" ? fmt.singleSelect : DEFAULT_SETTINGS.allowedFormats.singleSelect,
-      multiSelect: typeof fmt.multiSelect === "boolean" ? fmt.multiSelect : DEFAULT_SETTINGS.allowedFormats.multiSelect,
-      freeform: typeof fmt.freeform === "boolean" ? fmt.freeform : DEFAULT_SETTINGS.allowedFormats.freeform,
-    };
+export function getAskUserSettings(cwd: string = process.cwd()): AskUserSettings {
+  let raw: Record<string, unknown> = {};
+  try {
+    const s = getSettings("ask-user", cwd);
+    if (isRecord(s)) raw = s;
+  } catch {
+    // defaults
   }
-
-  const notifyOnAsk = typeof askUser.notifyOnAsk === "boolean" ? askUser.notifyOnAsk : DEFAULT_SETTINGS.notifyOnAsk;
-
-  cachedSettings = { enabled, allowedFormats, notifyOnAsk };
-  return cachedSettings;
+  const bool = (v: unknown, d: boolean) => (typeof v === "boolean" ? v : d);
+  const max = typeof raw.maxQuestions === "number" ? Math.min(4, Math.max(1, Math.floor(raw.maxQuestions))) : DEFAULT_SETTINGS.maxQuestions;
+  return {
+    enabled: bool(raw.enabled, DEFAULT_SETTINGS.enabled),
+    notifyOnAsk: bool(raw.notifyOnAsk, DEFAULT_SETTINGS.notifyOnAsk),
+    escape: raw.escape === "send" ? "send" : "stop",
+    digitAdvance: bool(raw.digitAdvance, DEFAULT_SETTINGS.digitAdvance),
+    helpLine: bool(raw.helpLine, DEFAULT_SETTINGS.helpLine),
+    other: raw.other === "always" || raw.other === "never" ? raw.other : "agent",
+    maxQuestions: max,
+  };
 }
 
-/**
- * Save ask-user settings to settings.json.
- */
-export function saveAskUserSettings(settings: AskUserSettings): void {
-  setSettings("ask-user", settings as unknown as Record<string, unknown>, "global", process.cwd());
-  cachedSettings = settings;
+export function saveAskUserSettings(settings: Partial<AskUserSettings>, cwd: string = process.cwd()): void {
+  setSettings("ask-user", settings as Record<string, unknown>, "global", cwd);
 }
-
-/**
- * Clear cached settings (for testing or reload).
- */
-export function clearSettingsCache(): void {
-  cachedSettings = null;
-}

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2"
+    "@pi-unipi/core": "3.0.0-alpha.21"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/ask-user/questions.ts

@@ -0,0 +1,151 @@
+/**
+ * @pi-unipi/ask-user — questions: schema shape, legacy conversion, answers (pure)
+ *
+ * One ask_user call carries 1–4 questions (Devin's ask shape):
+ *   { questions: [{ question, header, options: [{ label, description }], multi_select }] }
+ * An "Other" free-text choice is always added unless a question sets
+ * other: false. Older single-question calls ({ question, context, options,
+ * allowMultiple, allowFreeform, timeout }) are converted by `prepareArgs`.
+ */
+
+export const MAX_QUESTIONS = 4;
+export const HEADER_MAX = 16;
+
+export interface AskOption {
+  label: string;
+  description?: string;
+  /** Returned instead of the label when set. */
+  value?: string;
+  /** end_turn: stop the agent · new_session: hand off to `prefill`. */
+  action?: "end_turn" | "new_session";
+  prefill?: string;
+}
+
+export interface AskQuestion {
+  question: string;
+  header: string;
+  options: AskOption[];
+  multi_select?: boolean;
+  /** Offer "Other (type your own)" (default true). */
+  other?: boolean;
+}
+
+export interface AskParams {
+  questions: AskQuestion[];
+}
+
+/** What the user did with one question. */
+export interface QuestionAnswer {
+  /** Chosen option values (single: at most one). */
+  selected: string[];
+  /** "Other" text (may contain [Image #N] tokens). */
+  custom_text?: string;
+  skipped: boolean;
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : v === undefined || v === null ? "" : String(v);
+}
+
+/** A short chip label for a question that came without one. */
+export function deriveHeader(question: string, index: number): string {
+  const words = question.replace(/[^\p{L}\p{N}\s-]/gu, " ").split(/\s+/).filter((w) => w.length > 2 && !/^(what|which|who|how|should|would|could|does|do|you|your|the|and|for|want|like|prefer)$/i.test(w));
+  const pick = words.slice(0, 2).map((w) => w[0]!.toUpperCase() + w.slice(1)).join(" ");
+  return (pick || `Question ${index + 1}`).slice(0, HEADER_MAX);
+}
+
+function normalizeOption(raw: unknown): AskOption | null {
+  if (typeof raw === "string") return raw.trim() ? { label: raw.trim() } : null;
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  const label = str(o.label ?? o.value).trim();
+  if (!label) return null;
+  const out: AskOption = { label };
+  if (str(o.description).trim()) out.description = str(o.description).trim();
+  if (str(o.value).trim() && str(o.value).trim() !== label) out.value = str(o.value).trim();
+  if (o.action === "end_turn" || o.action === "new_session") out.action = o.action;
+  if (str(o.prefill).trim()) out.prefill = str(o.prefill).trim();
+  return out;
+}
+
+function normalizeQuestion(raw: Record<string, unknown>, index: number): AskQuestion | null {
+  const question = str(raw.question).trim();
+  if (!question) return null;
+  const options = (Array.isArray(raw.options) ? raw.options : []).map(normalizeOption).filter((o): o is AskOption => o !== null);
+  const header = (str(raw.header).trim() || deriveHeader(question, index)).slice(0, HEADER_MAX);
+  const multi = raw.multi_select ?? raw.multiSelect ?? raw.allowMultiple;
+  const other = raw.other ?? raw.allowFreeform;
+  return {
+    question,
+    header,
+    options,
+    ...(multi === true ? { multi_select: true } : {}),
+    ...(other === false && options.length > 0 ? { other: false } : {}),
+  };
+}
+
+/**
+ * Tool-call arguments → { questions }. Accepts the current shape and the
+ * legacy single-question one (context is folded into the question text;
+ * timeout is dropped — the user answers in their own time).
+ */
+export function prepareArgs(args: unknown): AskParams {
+  const a = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+  let raw: Record<string, unknown>[];
+  if (Array.isArray(a.questions)) raw = a.questions.filter((q): q is Record<string, unknown> => !!q && typeof q === "object");
+  else if (typeof a.question === "string") {
+    const context = str(a.context).trim();
+    raw = [{ ...a, header: str(a.header).trim() || deriveHeader(a.question, 0), question: context ? `${context}\n\n${a.question}` : a.question }];
+  } else raw = [];
+  const questions = raw.map(normalizeQuestion).filter((q): q is AskQuestion => q !== null).slice(0, MAX_QUESTIONS);
+  return { questions };
+}
+
+export function optionValue(o: AskOption): string {
+  return o.value ?? o.label;
+}
+
+export function isAnswered(a: QuestionAnswer | undefined): boolean {
+  return !!a && (a.selected.length > 0 || !!a.custom_text?.trim());
+}
+
+/** "Planet: Jupiter moon" — the one-line summary of an answer. */
+export function answerSummary(q: AskQuestion, a: QuestionAnswer | undefined): string {
+  if (!isAnswered(a)) return "(skipped)";
+  const labels = a!.selected.map((v) => q.options.find((o) => optionValue(o) === v)?.label ?? v);
+  const parts = [...labels];
+  if (a!.custom_text?.trim()) parts.push(a!.custom_text.trim());
+  return parts.join(", ");
+}
+
+/**
+ * The tool result the agent reads. Mirrors Devin's:
+ *   User answered your questions:
+ *   { "<question>": { "selected": [...], "custom_text": "...", "skipped": false } }
+ */
+export function answersText(questions: readonly AskQuestion[], answers: readonly (QuestionAnswer | undefined)[], images: readonly string[] = []): string {
+  const body: Record<string, QuestionAnswer> = {};
+  questions.forEach((q, i) => {
+    const a = answers[i];
+    const answered = isAnswered(a);
+    body[q.question] = {
+      selected: answered ? a!.selected : [],
+      ...(answered && a!.custom_text?.trim() ? { custom_text: a!.custom_text.trim() } : {}),
+      skipped: !answered,
+    };
+  });
+  const lines = [`User answered your questions:`, JSON.stringify(body, null, 2)];
+  if (images.length) lines.push(`Attached: ${images.join(", ")} (shown below).`);
+  if (questions.some((_, i) => !isAnswered(answers[i]))) lines.push("Skipped questions were left unanswered on purpose — don't ask them again unless you must.");
+  return lines.join("\n");
+}
+
+/** The "? help me out" result: nothing is decided, the user wants to talk first. */
+export function clarifyText(questions: readonly AskQuestion[], answers: readonly (QuestionAnswer | undefined)[]): string {
+  return [
+    "The user is not ready to answer and wants to clarify these questions first.",
+    "They may have more information, context or questions for you. Start by asking what they would like to clarify, then reformulate the questions if needed.",
+    "Questions asked:",
+    ...questions.flatMap((q, i) => [`- "${q.question}"`, `  ${isAnswered(answers[i]) ? `Answer so far: ${answerSummary(q, answers[i])}` : "(No answer provided)"}`]),
+  ].join("\n");
+}

package/packages/ask-user/skills/ask-user/SKILL.md

@@ -1,164 +1,90 @@
 ---
 name: ask-user
 description: >
-  Interactive decision-gating tool for structured user input.
-  Use ask_user when you need user confirmation, preferences, or decisions
-  before proceeding with high-impact or ambiguous choices.
+  Ask the user multiple-choice questions with the ask_user tool (1–4 questions
+  in one dialog, an "Other" free-text choice always included). Use when a
+  decision, preference or clarification needs the user before you continue.
 allowed-tools:
   - ask_user
 ---
 
 # Ask User
 
-Use the `ask_user` tool to collect structured input from the user.
+`ask_user` shows one dialog with 1–4 questions and waits for the answers. If the tool call says it's turned off, ask in your reply — don't retry it.
 
-## When to use ask_user
+## When to ask
 
-- Architectural trade-offs with high impact
-- Requirements are ambiguous or conflicting
-- Assumptions would materially change implementation
-- User preferences needed (style, approach, priority)
-- Confirming before destructive operations
+- A choice with lasting impact (architecture, data model, naming, destructive steps)
+- Requirements that are ambiguous or conflict
+- A preference only the user can state
 
-## Decision Handshake Flow
+Ordinary engineering detail is not a reason to ask — decide and verify.
 
-1. Gather evidence and summarize context
-2. Ask ONE focused question via `ask_user`
-3. Wait for explicit user choice
-4. Confirm the decision, then proceed
+## How to ask
 
-## Parameters
+- **One call, every question you need now.** Never several `ask_user` calls at once.
+- Each question: a full `question`, a short `header` (≤16 chars, shown as a chip), 2–4 `options` with a `label` (1–5 words) and a `description` (what it means or costs).
+- Don't add an "Other" option — one is added automatically (`other: false` removes it when free text makes no sense).
+- `multi_select: true` when several answers can apply.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `question` | string | required | The question to ask |
-| `context` | string? | — | Additional context shown before question |
-| `options` | array? | [] | Multiple-choice options with labels, descriptions, values |
-| `allowMultiple` | boolean? | false | Enable multi-select |
-| `allowFreeform` | boolean? | true | Add "Custom response" checkable option |
-| `timeout` | number? | — | Auto-dismiss after N ms |
-
-### Option Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `label` | string | required | Display label |
-| `description` | string? | — | Description shown below label |
-| `value` | string? | label | Value returned when selected |
-| `allowCustom` | boolean? | false | Allow user to add custom text for this option (shorthand for `action: "input"`) |
-| `action` | string? | "select" | Special action: `"select"`, `"input"`, `"end_turn"`, `"new_session"` |
-| `prefill` | string? | — | Prefill message for `"new_session"` action |
-
-### Action Types
-
-| Action | Behavior |
-|--------|----------|
-| `"select"` | Normal selection (default). Returns immediately. |
-| `"input"` | Enters text input mode. Returns `combined` response with selection + text. |
-| `"end_turn"` | Signals end of agent turn. Returns `end_turn` response kind. |
-| `"new_session"` | Starts a handoff. Returns `new_session` response kind with optional `prefill`. Shows a launcher overlay offering **Compact & run** (compact first, then queue/submit the prefill) or **Run directly** (queue/submit immediately). The current LLM follow-up is aborted after a successful queue or editor fallback. |
-
-## Examples
-
-Single choice:
-```
+```ts
 ask_user({
-  question: "Which database should we use?",
-  options: [
-    { label: "PostgreSQL", description: "Reliable, feature-rich" },
-    { label: "SQLite", description: "Simple, serverless" }
-  ]
-})
-```
-
-Multi-select:
-```
-ask_user({
-  question: "Which features to implement?",
-  options: [
-    { label: "Auth", value: "auth" },
-    { label: "Cache", value: "cache" },
-    { label: "Logging", value: "logging" }
+  questions: [
+    {
+      header: "Database",
+      question: "Which database should the service use?",
+      options: [
+        { label: "Postgres", description: "JSON columns, full-text search, one more service to run" },
+        { label: "SQLite", description: "Zero setup; single writer" },
+      ],
+    },
+    {
+      header: "Features",
+      question: "Which features ship in v1?",
+      multi_select: true,
+      options: [
+        { label: "Search", description: "Full-text over notes" },
+        { label: "Sharing", description: "Read-only links" },
+        { label: "Export", description: "Markdown and JSON" },
+      ],
+    },
   ],
-  allowMultiple: true
 })
 ```
 
-With context:
-```
-ask_user({
-  question: "Which approach?",
-  context: "Current bottleneck: network I/O. Goal: reduce latency.",
-  options: [
-    { label: "Cache-first" },
-    { label: "DB-first" }
-  ]
-})
-```
+## What comes back
 
-Freeform only:
 ```
-ask_user({
-  question: "What should we name this module?",
-  options: [],
-  allowFreeform: true
-})
+User answered your questions:
+{
+  "Which database should the service use?": { "selected": ["Postgres"], "skipped": false },
+  "Which features ship in v1?": { "selected": ["Search"], "custom_text": "and tags", "skipped": false }
+}
 ```
 
-Combined (multi-select + freeform):
-```
-ask_user({
-  question: "Which features and what custom feature?",
-  options: [
-    { label: "Auth", value: "auth" },
-    { label: "Cache", value: "cache" }
-  ],
-  allowMultiple: true,
-  allowFreeform: true
-})
-```
-User can check "Auth", "Cache", and "Custom response" to type additional features.
+- `custom_text` is what the user typed under "Other". It may reference attached files as `[Image #N]` (the image follows in the result) or `[File #N: /path]`.
+- `skipped: true` — the user chose not to answer. Respect it; don't ask again unless you must.
+- "Not ready to answer" — the user wants to talk first. Ask what they want to clarify; don't re-send the same questions.
+- Cancelled — the user stopped the turn. Wait for their next message.
 
-With per-option custom text:
-```
-ask_user({
-  question: "Does this look right?",
-  options: [
-    { label: "Yes", value: "yes" },
-    { label: "Partially", value: "partial", allowCustom: true },
-    { label: "No", value: "no", allowCustom: true }
-  ],
-  allowFreeform: false
-})
-```
-Selecting "Partially" or "No" enters text input so the user can explain what needs to change.
+## Workflow handoffs
 
-With end_turn and new_session actions:
-```
+An option can carry `action: "end_turn"` (picking it stops the turn) or `action: "new_session"` with a `prefill` (a message or `/command`). Picking a `new_session` option opens a launcher: **Compact & run** or **Run directly**.
+
+```ts
 ask_user({
-  question: "How would you like to proceed?",
-  options: [
-    { label: "Looks good, proceed", value: "proceed" },
-    { label: "I want changes", value: "changes", action: "input" },
-    { label: "Done for now", value: "done", action: "end_turn" },
-    { label: "Start fresh", value: "new", action: "new_session", prefill: "Let's redesign the..." }
-  ],
-  allowFreeform: false
+  questions: [{
+    header: "Next step",
+    question: "What would you like to do next?",
+    options: [
+      { label: "Implement the plan", description: "Start work in a fresh session", action: "new_session", prefill: "/unipi:work specs:2026-09-28-auth-plan" },
+      { label: "Done for now", description: "Return later", action: "end_turn" },
+    ],
+    other: false,
+  }],
 })
 ```
-- "Looks good" returns immediately with selection
-- "I want changes" enters text input mode for the user to explain
-- "Done for now" signals the agent to end its turn
-- "Start fresh" opens the launcher; **Compact & run** or **Run directly** queues the prefill message automatically
-
-## Session Launcher
-
-When a user selects a `new_session` option, a secondary launcher overlay appears with three choices:
 
-| Choice | Behavior |
-|--------|----------|
-| 🧹 Compact & run | Starts `ctx.compact()` without waiting in the tool spinner, then queues/submits the prefill as a follow-up message after compaction or a short fallback timer |
-| ▶ Run directly | Queues/submits the prefill immediately as a follow-up message, without compaction |
-| ✕ Cancel | Cancels the session launch; no prefill is queued |
+## Without a UI
 
-The prefill can be a slash command (for example `the implementation step specs:...`) or any non-empty message. If automatic delivery fails, ask_user places the prefill in the editor and warns the user to press Enter. This two-step flow lets the user manage context window usage before starting a new task while avoiding unnecessary LLM follow-up in the old session.
+In non-interactive runs, or when the tool is turned off, `ask_user` returns a notice instead of a dialog — ask in your reply. Inside a subagent it fails: put the question, the options and your recommendation in your report for the lead.