@pify/ask-question 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @pify/ask-question
+
+Let the model ask instead of guessing — a Claude Code `AskUserQuestion`-shaped tool for [pi](https://github.com/earendil-works/pi): 1-4 structured questions, written-out options with trade-offs, multi-select, and an "Other…" free-text path.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install ask-question`](https://github.com/pifydev/cli) or `pi install npm:@pify/ask-question`.
+
+## What it does
+
+- **`ask_question`** — the agent batches up to 4 questions, each with up to 4 options (`label` + `description` trade-offs, recommendation marked "(Recommended)" and listed first), optional `multiSelect`, and free-text via "Other…".
+- **Built entirely on pi's built-in dialogs** (`select`/`input`) — no custom TUI overlay, so it works identically in the terminal and RPC/GUI hosts and can't break with pi UI changes. Multi-select is a checkbox toggle loop with `✓ Done`.
+- **Discipline encoded in the tool description** (zhushanwen's three conditions): only when 2+ reasonable approaches exist, context is already gathered, and a wrong pick means rework. Never for permissions or things the agent can look up.
+- **Declining is an answer**: Esc cleanly reports "the user declined" for the rest of the batch — no error, no re-asking. Headless runs get "proceed with your best judgment and state the assumption" instead of a failure (asking is advisory, unlike the fail-closed safety gates).
+- Structured results return to the model as both readable text and `details.answers`.
+
+## Why no fancy overlay?
+
+The three big prior arts (6-16k lines each) all build custom TUI overlays — tabbed questionnaires, split-pane previews, searchable lists. They're impressive and fragile. `@henryqw/pi-ask-question` proved 256 lines of built-in dialogs covers the core; this package takes that floor and adds the CC schema, multi-select, and discipline. The overlay experience can return as v0.2 if demand appears.
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/ask-question.ts

@@ -0,0 +1,147 @@
+/**
+ * @pify/ask-question — let the model ask instead of guessing.
+ *
+ * One tool, Claude Code AskUserQuestion-shaped: 1-4 questions with up to 4
+ * written-out options each, multi-select, and an "Other…" free-text path.
+ * Built ENTIRELY on pi's built-in dialogs (ui.select / ui.input) — no custom
+ * TUI overlay, so it works identically in the terminal and in RPC/GUI hosts
+ * and cannot break with pi UI changes (HenryQW's floor, deliberately chosen
+ * over the 6-16k-line overlay implementations).
+ *
+ * Asking is advisory, not a gate: declining is a clean answer, and headless
+ * runs get "proceed with your best judgment" instead of an error.
+ *
+ * Design synthesis: calling discipline (@zhushanwen/pi-ask-user), 4-question
+ * batching + recommended convention (rpiv-ask-user-question, Claude Code),
+ * multi-select (edlsh/pi-ask-user), built-in-dialog minimalism
+ * (@henryqw/pi-ask-question).
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  DONE_LABEL,
+  OTHER_LABEL,
+  formatAnswers,
+  labelFromDisplay,
+  optionDisplay,
+  parseToggleRow,
+  toggleRows,
+  validateQuestions,
+  type AskAnswer,
+  type AskQuestion,
+} from "../src/ask.ts";
+
+type UiContext = ExtensionContext;
+
+export default function askQuestion(pi: ExtensionAPI) {
+  async function askSingle(ctx: UiContext, q: AskQuestion): Promise<AskAnswer> {
+    const rows = [...q.options.map(optionDisplay), ...(q.allowOther ? [OTHER_LABEL] : [])];
+    const picked = await ctx.ui.select(q.question, rows);
+    if (picked === undefined) return { question: q.question, answers: [], declined: true };
+    if (picked === OTHER_LABEL) {
+      const text = await ctx.ui.input(q.question, "Type your answer");
+      if (text === undefined || !text.trim()) {
+        return { question: q.question, answers: [], declined: true };
+      }
+      return { question: q.question, answers: [], other: text.trim() };
+    }
+    const label = labelFromDisplay(picked, q.options);
+    return { question: q.question, answers: label ? [label] : [] };
+  }
+
+  async function askMulti(ctx: UiContext, q: AskQuestion): Promise<AskAnswer> {
+    const selected = new Set<number>();
+    let other: string | undefined;
+    for (;;) {
+      const picked = await ctx.ui.select(
+        `${q.question}\n(toggle options, then ${DONE_LABEL})`,
+        toggleRows(q.options, selected, q.allowOther),
+      );
+      if (picked === undefined) return { question: q.question, answers: [], declined: true };
+      const action = parseToggleRow(picked, q.options);
+      if (!action) continue;
+      if (action.kind === "done") break;
+      if (action.kind === "other") {
+        const text = await ctx.ui.input(q.question, "Type your answer");
+        if (text?.trim()) other = text.trim();
+        continue;
+      }
+      if (selected.has(action.index)) selected.delete(action.index);
+      else selected.add(action.index);
+    }
+    return {
+      question: q.question,
+      answers: [...selected].sort((a, b) => a - b).map((i) => q.options[i]!.label),
+      ...(other ? { other } : {}),
+    };
+  }
+
+  pi.registerTool({
+    name: "ask_question",
+    label: "Ask the user",
+    description:
+      "Ask the user 1-4 structured questions, each with up to 4 written-out options (mark your " +
+      "recommendation by appending ' (Recommended)' to its label and putting it first), optional " +
+      "multiSelect, and an Other free-text path (allowOther, default true). " +
+      "Call ONLY when all three hold: the request has 2+ reasonable approaches; you have already " +
+      "gathered context (read/grep) and it is still genuinely ambiguous; and picking wrong means " +
+      "redoing real work. Never use it for permissions, for things you can look up yourself, or to " +
+      "confirm a plan you are confident in. A declined answer is an answer — respect it and proceed.",
+    parameters: Type.Object({
+      questions: Type.Array(
+        Type.Object({
+          question: Type.String({ description: "The complete question, ending with a question mark" }),
+          options: Type.Optional(
+            Type.Array(
+              Type.Object({
+                label: Type.String({ description: "Concise choice (1-6 words)" }),
+                description: Type.Optional(Type.String({ description: "Trade-offs of this choice" })),
+              }),
+              { maxItems: 4 },
+            ),
+          ),
+          multiSelect: Type.Optional(Type.Boolean({ description: "Allow selecting several options" })),
+          allowOther: Type.Optional(Type.Boolean({ description: "Offer a free-text Other path (default true)" })),
+        }),
+        { minItems: 1, maxItems: 4 },
+      ),
+    }),
+    async execute(_id, params: { questions: unknown }, _signal, _onUpdate, ctx) {
+      const uiCtx = ctx as UiContext;
+      const result = validateQuestions(params.questions);
+      if (result.error) throw new Error(result.error);
+
+      if (!uiCtx.hasUI) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No UI is available to ask the user. Proceed with your best judgment and clearly state the assumption you made.",
+            },
+          ],
+          details: { headless: true },
+        };
+      }
+
+      const answers: AskAnswer[] = [];
+      for (const q of result.questions) {
+        const answer = q.multiSelect ? await askMulti(uiCtx, q) : await askSingle(uiCtx, q);
+        answers.push(answer);
+        if (answer.declined) {
+          // Esc aborts the rest — the user is opting out of the questionnaire.
+          for (const rest of result.questions.slice(answers.length)) {
+            answers.push({ question: rest.question, answers: [], declined: true });
+          }
+          break;
+        }
+      }
+
+      const text = [
+        formatAnswers(answers),
+        ...(result.warnings.length > 0 ? [`Warnings: ${result.warnings.join("; ")}`] : []),
+      ].join("\n\n");
+      return { content: [{ type: "text", text }], details: { answers } };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@pify/ask-question",
+  "version": "0.1.0",
+  "description": "Let the model ask instead of guessing: CC AskUserQuestion-shaped tool on built-in dialogs - 1-4 questions, multi-select, Other free-text, works in TUI and RPC",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "ask",
+    "question",
+    "interactive"
+  ],
+  "homepage": "https://github.com/pifydev/ask-question#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/ask-question/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/ask-question.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/ask-question.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/ask-question/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ask-question
+description: Use when a decision is genuinely ambiguous after gathering context and picking wrong means rework - explains the ask_question discipline and how to write good options
+---
+
+# Asking the user
+
+This project has the `@pify/ask-question` extension installed: `ask_question`
+presents 1-4 structured questions through pi's dialogs.
+
+## The three conditions (all must hold)
+
+1. The request has 2+ reasonable approaches.
+2. You already gathered context (read/grep) and it is STILL ambiguous.
+3. Picking wrong means redoing real work.
+
+If any fails: don't ask. Look it up, or pick the obvious option and say so.
+
+## Never use it for
+
+- Permissions or approvals (safety gates own that).
+- Facts you can verify in the codebase yourself.
+- Confirming a plan you are confident in ("shall I proceed?").
+- More than one call per decision point — batch related questions (max 4).
+
+## Writing good questions
+
+- Complete question ending with "?"; options are concise (1-6 words) with
+  trade-offs in descriptions.
+- Put your recommendation FIRST and append " (Recommended)" to its label.
+- Use multiSelect only when choices are not mutually exclusive.
+- Leave allowOther on unless free text makes no sense.
+
+## Respecting answers
+
+- A declined answer (Esc) is an answer: proceed on your best judgment,
+  state the assumption, and do not re-ask.
+- With no UI (headless), the tool tells you to proceed — do that, and make
+  the assumption explicit in your reply.

package/src/ask.ts

@@ -0,0 +1,134 @@
+/**
+ * Pure logic for @pify/ask-question.
+ * No imports from pi packages; fully unit-testable.
+ */
+
+export interface AskOption {
+  label: string;
+  description?: string;
+}
+
+export interface AskQuestion {
+  question: string;
+  options: AskOption[];
+  multiSelect: boolean;
+  allowOther: boolean;
+}
+
+export interface AskAnswer {
+  question: string;
+  /** Selected option labels (empty when only `other` was given). */
+  answers: string[];
+  /** Free-text answer via "Other…", when used. */
+  other?: string;
+  declined?: boolean;
+}
+
+export const MAX_QUESTIONS = 4;
+export const MAX_OPTIONS = 4;
+export const OTHER_LABEL = "Other…";
+export const DONE_LABEL = "✓ Done";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export interface ValidationResult {
+  questions: AskQuestion[];
+  warnings: string[];
+  error: string | null;
+}
+
+export function validateQuestions(raw: unknown): ValidationResult {
+  const warnings: string[] = [];
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return { questions: [], warnings, error: "questions must be a non-empty array" };
+  }
+  if (raw.length > MAX_QUESTIONS) warnings.push(`capped at ${MAX_QUESTIONS} questions`);
+
+  const questions: AskQuestion[] = [];
+  for (const entry of raw.slice(0, MAX_QUESTIONS)) {
+    if (!isRecord(entry) || typeof entry.question !== "string" || !entry.question.trim()) {
+      warnings.push("dropped a question without text");
+      continue;
+    }
+    const options: AskOption[] = [];
+    if (Array.isArray(entry.options)) {
+      for (const opt of entry.options.slice(0, MAX_OPTIONS)) {
+        if (isRecord(opt) && typeof opt.label === "string" && opt.label.trim()) {
+          options.push({
+            label: opt.label.trim(),
+            ...(typeof opt.description === "string" && opt.description.trim()
+              ? { description: opt.description.trim() }
+              : {}),
+          });
+        } else {
+          warnings.push("dropped an option without a label");
+        }
+      }
+      if (entry.options.length > MAX_OPTIONS) {
+        warnings.push(`options capped at ${MAX_OPTIONS} per question`);
+      }
+    }
+    const allowOther = entry.allowOther !== false;
+    if (options.length === 0 && !allowOther) {
+      warnings.push(`question "${entry.question.slice(0, 30)}" has no options and allowOther=false — dropped`);
+      continue;
+    }
+    questions.push({
+      question: entry.question.trim(),
+      options,
+      multiSelect: entry.multiSelect === true,
+      allowOther,
+    });
+  }
+
+  if (questions.length === 0) {
+    return { questions, warnings, error: "no valid questions remained" };
+  }
+  return { questions, warnings, error: null };
+}
+
+/** Display string for one option in the select dialog. */
+export function optionDisplay(option: AskOption): string {
+  const desc = option.description
+    ? ` — ${option.description.length > 60 ? `${option.description.slice(0, 60)}…` : option.description}`
+    : "";
+  return `${option.label}${desc}`;
+}
+
+/** Map a picked display string back to its option label. */
+export function labelFromDisplay(display: string, options: AskOption[]): string | null {
+  const found = options.find((o) => optionDisplay(o) === display);
+  return found ? found.label : null;
+}
+
+/** Rows for one round of the multi-select toggle loop. */
+export function toggleRows(options: AskOption[], selected: ReadonlySet<number>, allowOther: boolean): string[] {
+  const rows = options.map((o, i) => `[${selected.has(i) ? "x" : " "}] ${optionDisplay(o)}`);
+  rows.push(DONE_LABEL);
+  if (allowOther) rows.push(OTHER_LABEL);
+  return rows;
+}
+
+export type ToggleAction = { kind: "toggle"; index: number } | { kind: "done" } | { kind: "other" };
+
+export function parseToggleRow(row: string, options: AskOption[]): ToggleAction | null {
+  if (row === DONE_LABEL) return { kind: "done" };
+  if (row === OTHER_LABEL) return { kind: "other" };
+  const body = row.replace(/^\[[x ]\] /, "");
+  const index = options.findIndex((o) => optionDisplay(o) === body);
+  return index >= 0 ? { kind: "toggle", index } : null;
+}
+
+/** Text block the model receives. */
+export function formatAnswers(answers: AskAnswer[]): string {
+  return answers
+    .map((a) => {
+      if (a.declined) return `Q: ${a.question}\nA: (the user declined to answer)`;
+      const parts = [...a.answers];
+      if (a.other) parts.push(`Other: ${a.other}`);
+      return `Q: ${a.question}\nA: ${parts.length > 0 ? parts.join("; ") : "(no selection)"}`;
+    })
+    .join("\n\n");
+}