pi-critique-model 1.0.1 → 1.1.0

package/README.md

@@ -8,6 +8,8 @@
 
 **Critique questions the last work step with a separate model and can challenge user instructions before the model starts.** It is not limited to code: it can review implementation work, writing, plans, research, data analysis, ops, or any other project work. Optionally, Critique also runs a fast pre-flight check on sufficiently rich user prompts and shows a short `Critique` widget when the instruction deserves pushback. The feedback is **non-mandatory**: the user and the working model remain the final judges.
 
+Additionally, the **Questions** feature detects ambiguous user input and offers clarifying suggestions before the model acts on it.
+
 ---
 
 ## Features
@@ -27,6 +29,8 @@
 - **Prompt-critique model source** — use either the active working model or the configured critique model
 - **Interactive Critique widget** — ultra-short one-sentence advice in the user's interaction language with `Accept`, `Discard`, or `Reply`; auto-discards after 30 seconds
 - **Persistent config** — `~/.pi/agent/critique.json` stores model choice, auto-inject, and automatic prompt-critique settings across all projects
+- **Questions feature** — optional clarifying widget that detects ambiguous user input and offers three options: two suggested interpretations and a free-text answer; auto-discards after 30 seconds
+- **Questions frequency** — three sensitivity levels: `Essential only` (minimal), `Normal` (moderate), or `Many questions` (high sensitivity)
 
 ## Install
 
@@ -87,7 +91,7 @@ To focus the review:
 | `/critique view` | Show the review only, without injecting it |
 | `/critique view <focus>` | View-only, with a focus note |
 | `/critique view N` | View-only, last `N` steps |
-| `/critique config` | Open the editable settings menu for model, auto-inject, and automatic prompt critique |
+| `/critique config` | Open the editable settings menu for model, auto-inject, prompt critique, and questions |
 
 **Argument parsing:**
 
@@ -166,6 +170,29 @@ If critique is useful, pi shows an ultra-short `Critique` widget in the user's i
 
 Automatic prompt critique can use either the active working model or the configured critique model. It does not require a separate model.
 
+### 5. Optional Questions feature
+
+When enabled in `/critique config`, Critique analyzes user input for ambiguity — unclear pronouns, vague directives, or scope-unclear requests — and shows a `Questions` widget before the model receives the prompt.
+
+The widget presents three options in the user's interaction language:
+
+- **A** — a suggested interpretation (e.g., "Focus on the primary task")
+- **B** — an alternative interpretation (e.g., "Address all aspects comprehensively")
+- **C** — the user types their own answer in a free-text editor
+- **Dismiss** — send the original prompt unchanged (auto-dismisses after 30 seconds)
+
+The selected answer is prepended to the user's prompt as a clarification, so the working model receives a more precise instruction.
+
+#### Questions Frequency
+
+The sensitivity of the Questions feature is controlled by the **Questions frequency** setting:
+
+| Level | Description |
+|-------|-------------|
+| **Essential only** | Only ask when the input is clearly ambiguous (long, multi-sentence, or contains unclear pronouns/references) |
+| **Normal** | Moderate sensitivity; ask for most inputs that could benefit from clarification |
+| **Many questions** | High sensitivity; ask frequently, even for shorter or mildly ambiguous inputs |
+
 ## Model Selection
 
 `/critique config` opens an editable settings menu. Select a setting to change only that value, toggle booleans directly, or choose `Done`/`Esc` to close. Changes are persisted as soon as each setting is edited.
@@ -188,7 +215,9 @@ The config is persisted as JSON at `~/.pi/agent/critique.json`:
   "autoInject": true,
   "autoPromptCritique": false,
   "autoPromptCritiqueLevel": "inconsistencies",
-  "autoPromptCritiqueModel": "working"
+  "autoPromptCritiqueModel": "working",
+  "questions": false,
+  "questionsFrequency": "normal"
 }
 ```
 
@@ -197,6 +226,8 @@ The config is persisted as JSON at `~/.pi/agent/critique.json`:
 - **`autoPromptCritique`** — when `true`, sufficiently rich user instructions are challenged before the model starts.
 - **`autoPromptCritiqueLevel`** — `inconsistencies` only flags real misunderstanding risks; `critical` is moderate; `corrosive` is highly sensitive and skips only clearly logical/complete prompts.
 - **`autoPromptCritiqueModel`** — `working` uses the active model; `critique` uses the configured critique model.
+- **`questions`** — when `true`, ambiguous user input triggers a clarifying Questions widget before the model receives the prompt.
+- **`questionsFrequency`** — sensitivity of the Questions feature: `essential` (minimal), `normal` (moderate), or `verbose` (high; "many questions").
 
 The settings menu offers any model with configured auth that's available in pi's registry; the config persists per-machine (in `getAgentDir()`), shared across all projects.
 
@@ -213,7 +244,7 @@ critique/
 └── src/
     ├── index.ts             # /critique command surface, config UI, review UI, input hook
     ├── config.ts            # persistence + model resolution: pinned, auto, fallback
-    ├── prompt-critique.ts   # automatic user-prompt critique prompt, gate, model call
+    ├── prompt-critique.ts   # automatic user-prompt critique prompt, gate, model call, questions detection
     ├── work-step.ts         # episode splitting + token-budgeted serialization
     └── review.ts            # reviewer prompt + model call + injected-message builder
 ```
@@ -225,12 +256,13 @@ Five-file extension with zero external dependencies (only pi's bundled `@earendi
 - **Reviewer call** — tool-free `ctx.modelRegistry.complete()` with a domain-general structured prompt
 - **Advisory formatter** — wraps the review in a "non-mandatory" envelope before injecting as a follow-up user message
 - **Prompt critique** — optional input hook with local trivial-prompt gate, three challenge levels, and ultra-short JSON model output
-- **UI** — lazy-loaded pickers/viewers/loaders + 30-second Critique widget
+- **Questions detection** — heuristic ambiguity detector with three frequency levels; shows a clarifying widget with A/B/C options
+- **UI** — lazy-loaded pickers/viewers/loaders + 30-second Critique widget + 30-second Questions widget
 
 ## Notes
 
 - The critique model runs with **no tools** and never touches the filesystem. It judges purely from the serialized work step, whatever the domain.
-- In TUI mode the review runs behind a cancelable loader (Esc aborts) and `/critique view` opens a scrollable Markdown viewer. Automatic prompt critique appears as a compact `Critique` widget with a 30-second auto-discard timeout. In RPC mode reviews are surfaced through notifications/dialogs; print mode logs manual reviews to stdout and skips automatic prompt critique.
+- In TUI mode the review runs behind a cancelable loader (Esc aborts) and `/critique view` opens a scrollable Markdown viewer. Automatic prompt critique appears as a compact `Critique` widget with a 30-second auto-discard timeout. The Questions feature appears as a `Questions` widget with the same timeout. In RPC mode reviews are surfaced through notifications/dialogs; print mode logs manual reviews to stdout and skips automatic prompt critique and questions.
 - Provider errors (bad keys, insufficient balance, rate limit) are surfaced as errors instead of silently producing empty reviews.
 - Reviews are capped at 16,000 chars to keep the injected follow-up reasonable; longer reviews are truncated with `… [review truncated]`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-critique-model",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "pi critique: work review + prompt challenge.",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -16,6 +16,8 @@ import type {
   AutoPromptCritiqueModelSource,
 } from "./prompt-critique.ts";
 
+export type QuestionsFrequency = "essential" | "normal" | "verbose";
+
 export interface CritiqueConfig {
   /** Canonical "provider/modelId" of the critique model. Empty string = auto. */
   model: string;
@@ -27,6 +29,10 @@ export interface CritiqueConfig {
   autoPromptCritiqueLevel: AutoPromptCritiqueLevel;
   /** Which model is used for automatic prompt critique. */
   autoPromptCritiqueModel: AutoPromptCritiqueModelSource;
+  /** Ask clarifying questions when user input is ambiguous. */
+  questions: boolean;
+  /** Sensitivity level for the questions feature. */
+  questionsFrequency: QuestionsFrequency;
 }
 
 export const DEFAULT_CONFIG: CritiqueConfig = {
@@ -35,6 +41,8 @@ export const DEFAULT_CONFIG: CritiqueConfig = {
   autoPromptCritique: false,
   autoPromptCritiqueLevel: "inconsistencies",
   autoPromptCritiqueModel: "working",
+  questions: false,
+  questionsFrequency: "normal",
 };
 
 export function configFilePath(): string {
@@ -46,6 +54,7 @@ export function loadConfig(): CritiqueConfig {
     const raw = JSON.parse(readFileSync(configFilePath(), "utf8")) as Partial<CritiqueConfig>;
     const level = raw.autoPromptCritiqueLevel;
     const modelSource = raw.autoPromptCritiqueModel;
+    const frequency = raw.questionsFrequency;
     return {
       model: typeof raw.model === "string" ? raw.model : DEFAULT_CONFIG.model,
       autoInject:
@@ -62,6 +71,12 @@ export function loadConfig(): CritiqueConfig {
         modelSource === "working" || modelSource === "critique"
           ? modelSource
           : DEFAULT_CONFIG.autoPromptCritiqueModel,
+      questions:
+        typeof raw.questions === "boolean" ? raw.questions : DEFAULT_CONFIG.questions,
+      questionsFrequency:
+        frequency === "essential" || frequency === "normal" || frequency === "verbose"
+          ? frequency
+          : DEFAULT_CONFIG.questionsFrequency,
     };
   } catch {
     return { ...DEFAULT_CONFIG };

package/src/index.ts

@@ -22,6 +22,19 @@ import {
   saveConfig,
 } from "./config.ts";
 
+import {
+  detectAmbiguity,
+  isPromptCritiqueCandidate,
+  runAutoPromptCritique,
+  buildAcceptedPromptCritiqueMessage,
+  buildPromptCritiqueReplyMessage,
+  buildQuestionsMessage,
+  questionsFrequencyLabel,
+  type QuestionsFrequency,
+  type AutoPromptCritiqueLevel,
+  type AutoPromptCritiqueModelSource,
+} from "./prompt-critique.ts";
+
 type Mode = "config" | "review" | "view";
 
 interface ParsedArgs {
@@ -82,9 +95,11 @@ async function runWithLoader(
 type AutoPromptCritiqueLevel = ReturnType<typeof loadConfig>["autoPromptCritiqueLevel"];
 type AutoPromptCritiqueModelSource = ReturnType<typeof loadConfig>["autoPromptCritiqueModel"];
 type PromptCritiqueAction = "accept" | "discard" | "reply";
+type QuestionAction = "a" | "b" | "c" | "dismiss";
 
 const MAX_VISIBLE_MODELS = 10;
 const PROMPT_CRITIQUE_TIMEOUT_MS = 30_000;
+const QUESTIONS_TIMEOUT_MS = 30_000;
 
 function autoPromptCritiqueLevelLabel(level: AutoPromptCritiqueLevel): string {
   return level === "inconsistencies" ? "Inconsistencies" : level === "critical" ? "Critical" : "Corrosive";
@@ -99,7 +114,7 @@ function updateCritiqueStatus(ctx: ExtensionContext): void {
   const config = loadConfig();
   ctx.ui.setStatus(
     "critique",
-    config.autoPromptCritique ? `critique:${autoPromptCritiqueLevelLabel(config.autoPromptCritiqueLevel)}` : undefined,
+    config.autoPromptCritique ? "🧠 critique:on" : undefined,
   );
 }
 
@@ -294,6 +309,89 @@ async function showPromptCritiqueWidget(
   }, { overlay: true, overlayOptions: { anchor: "bottom-center", width: "90%", minWidth: 20 } });
 }
 
+async function showQuestionsWidget(
+  ctx: ExtensionContext,
+  interpretationA: string,
+  interpretationB: string,
+): Promise<QuestionAction> {
+  if (ctx.mode !== "tui") {
+    const choice = await ctx.ui.select(
+      "What did you mean?",
+      [
+        `A: ${interpretationA}`,
+        `B: ${interpretationB}`,
+        "C: My own answer",
+        "Dismiss (send as-is)",
+      ],
+      { timeout: QUESTIONS_TIMEOUT_MS },
+    );
+    if (choice === "A") return "a";
+    if (choice === "B") return "b";
+    if (choice === "C") return "c";
+    return "dismiss";
+  }
+
+  const { matchesKey } = await import("@earendil-works/pi-tui");
+
+  return ctx.ui.custom<QuestionAction>((tui, theme, _kb, done) => {
+    const started = Date.now();
+    let remaining = QUESTIONS_TIMEOUT_MS;
+    let closed = false;
+
+    const finish = (action: QuestionAction) => {
+      if (closed) return;
+      closed = true;
+      clearInterval(interval);
+      clearTimeout(timeout);
+      done(action);
+    };
+
+    const timeout = setTimeout(() => finish("dismiss"), QUESTIONS_TIMEOUT_MS);
+    const interval = setInterval(() => {
+      remaining = QUESTIONS_TIMEOUT_MS - (Date.now() - started);
+      tui.requestRender();
+    }, 250);
+
+    return {
+      render: (width: number) => {
+        const actualWidth = Math.max(20, Math.min(width, 100));
+        const color = (s: string) => theme.fg("accent", s);
+        const lines: string[] = [];
+        lines.push(frameBorder(actualWidth, "╭", "╮", ` Questions (${formatRemaining(remaining)}) `, color));
+        lines.push(frameLine("", actualWidth, color));
+        lines.push(frameLine("What did you mean?", actualWidth, color));
+        lines.push(frameLine("", actualWidth, color));
+        lines.push(frameLine(`A) ${interpretationA}`, actualWidth, color));
+        lines.push(frameLine(`B) ${interpretationB}`, actualWidth, color));
+        lines.push(frameLine(`C) My own answer`, actualWidth, color));
+        lines.push(frameLine("", actualWidth, color));
+        lines.push(
+          frameLine(
+            "A/B/C choice · Esc dismiss",
+            actualWidth,
+            color,
+          ),
+        );
+        lines.push(frameBorder(actualWidth, "╰", "╯", "", color));
+        return lines;
+      },
+      invalidate: () => {},
+      handleInput: (data: string) => {
+        if (data === "a" || data === "A") finish("a");
+        else if (data === "b" || data === "B") finish("b");
+        else if (data === "c" || data === "C") finish("c"); else if (data === "d" || data === "D" || matchesKey(data, "escape")) {
+          finish("dismiss");
+        }
+        tui.requestRender();
+      },
+      dispose: () => {
+        clearInterval(interval);
+        clearTimeout(timeout);
+      },
+    };
+  }, { overlay: true, overlayOptions: { anchor: "bottom-center", width: "90%", minWidth: 20 } });
+}
+
 async function handleAutomaticPromptCritique(
   ctx: ExtensionContext,
   text: string,
@@ -303,13 +401,6 @@ async function handleAutomaticPromptCritique(
   if (!config.autoPromptCritique) return null;
   if (!ctx.hasUI) return null;
 
-  const {
-    buildAcceptedPromptCritiqueMessage,
-    buildPromptCritiqueReplyMessage,
-    isPromptCritiqueCandidate,
-    runAutoPromptCritique,
-  } = await import("./prompt-critique.ts");
-
   if (!isPromptCritiqueCandidate(text, (images?.length ?? 0) > 0, config.autoPromptCritiqueLevel)) return null;
 
   const model = resolveAutoPromptCritiqueModel(ctx, config);
@@ -348,6 +439,30 @@ async function handleAutomaticPromptCritique(
   return null;
 }
 
+async function handleQuestions(
+  ctx: ExtensionContext,
+  text: string,
+): Promise<string | null> {
+  const config = loadConfig();
+  if (!config.questions) return null;
+  if (!ctx.hasUI) return null;
+
+  const ambiguity = detectAmbiguity(text, false, config.questionsFrequency);
+  if (!ambiguity) return null;
+
+  const action = await showQuestionsWidget(ctx, ambiguity.interpretationA, ambiguity.interpretationB);
+  if (action === "dismiss") return null;
+
+  let customAnswer = "";
+  if (action === "c") {
+    const reply = await ctx.ui.editor("Your interpretation", "");
+    if (!reply?.trim()) return null;
+    customAnswer = reply.trim();
+  }
+
+  return buildQuestionsMessage(text, ambiguity.interpretationA, ambiguity.interpretationB, action, customAnswer);
+}
+
 async function runReview(pi: ExtensionAPI, ctx: ExtensionCommandContext, parsed: ParsedArgs): Promise<void> {
   const config = loadConfig();
 
@@ -432,7 +547,10 @@ function configSummary(config: ReturnType<typeof loadConfig>): string {
   const promptCritique = config.autoPromptCritique
     ? `${autoPromptCritiqueLevelLabel(config.autoPromptCritiqueLevel)} via ${autoPromptCritiqueModelSourceLabel(config.autoPromptCritiqueModel)}`
     : "off";
-  return `model:${config.model || "auto"} | inject:${config.autoInject ? "on" : "off"} | prompt:${promptCritique}`;
+  const questions = config.questions
+    ? `on (${questionsFrequencyLabel(config.questionsFrequency)})`
+    : "off";
+  return `model:${config.model || "auto"} | inject:${config.autoInject ? "on" : "off"} | prompt:${promptCritique} | questions:${questions}`;
 }
 
 function configMenuItems(config: ReturnType<typeof loadConfig>): SelectItem[] {
@@ -462,6 +580,16 @@ function configMenuItems(config: ReturnType<typeof loadConfig>): SelectItem[] {
       label: "Prompt model",
       description: autoPromptCritiqueModelSourceLabel(config.autoPromptCritiqueModel),
     },
+    {
+      value: "questions",
+      label: "Questions",
+      description: config.questions ? "on" : "off",
+    },
+    {
+      value: "questionsFrequency",
+      label: "Questions frequency",
+      description: questionsFrequencyLabel(config.questionsFrequency),
+    },
     {
       value: "done",
       label: "Done",
@@ -592,6 +720,13 @@ async function handleConfig(ctx: ExtensionCommandContext): Promise<void> {
       case "autoPromptCritiqueModel":
         changed = await editPromptCritiqueModel(ctx, config);
         break;
+      case "questions":
+        config.questions = !config.questions;
+        changed = true;
+        break;
+      case "questionsFrequency":
+        changed = await editQuestionsFrequency(ctx, config);
+        break;
     }
 
     if (changed) {
@@ -606,6 +741,38 @@ async function handleConfig(ctx: ExtensionCommandContext): Promise<void> {
   ctx.ui.notify(`Critique config closed — ${configSummary(config)}`, "info");
 }
 
+async function editQuestionsFrequency(
+  ctx: ExtensionCommandContext,
+  config: ReturnType<typeof loadConfig>,
+): Promise<boolean> {
+  const freqItems: SelectItem[] = [
+    {
+      value: "essential",
+      label: "Essential only",
+      description: "only ask when truly necessary",
+    },
+    {
+      value: "normal",
+      label: "Normal",
+      description: "moderate sensitivity",
+    },
+    {
+      value: "verbose",
+      label: "Many questions",
+      description: "high sensitivity; ask often",
+    },
+  ];
+  const choice = await chooseConfigItem(
+    ctx,
+    "Questions frequency",
+    freqItems,
+    config.questionsFrequency,
+  );
+  if (choice === undefined) return false;
+  config.questionsFrequency = choice as QuestionsFrequency;
+  return true;
+}
+
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     updateCritiqueStatus(ctx);
@@ -613,6 +780,14 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("input", async (event, ctx) => {
     if (event.source === "extension") return { action: "continue" as const };
+
+    // First, check if the questions feature wants to ask a clarifying question.
+    const questionsTransformed = await handleQuestions(ctx, event.text);
+    if (questionsTransformed) {
+      return { action: "transform" as const, text: questionsTransformed, images: event.images };
+    }
+
+    // Then, check if automatic prompt critique wants to challenge the prompt.
     const transformed = await handleAutomaticPromptCritique(ctx, event.text, event.images);
     if (!transformed) return { action: "continue" as const };
     return { action: "transform" as const, text: transformed, images: event.images };

package/src/prompt-critique.ts

@@ -1,9 +1,12 @@
 /**
- * Critique — automatic user-prompt critique.
+ * Critique — automatic user-prompt critique and questions.
  *
  * This module judges user instructions before the working model receives them.
  * It is intentionally lightweight: a cheap heuristic avoids trivial prompts,
  * then a tool-free model call decides whether there is anything worth showing.
+ *
+ * It also provides the "questions" feature: when user input is ambiguous,
+ * a clarifying widget offers three options (two suggestions + free text).
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -11,6 +14,7 @@ import { type Message, type Model, uuidv7 } from "@earendil-works/pi-ai";
 
 export type AutoPromptCritiqueLevel = "inconsistencies" | "critical" | "corrosive";
 export type AutoPromptCritiqueModelSource = "working" | "critique";
+export type QuestionsFrequency = "essential" | "normal" | "verbose";
 
 export const AUTO_PROMPT_CRITIQUE_LEVELS: AutoPromptCritiqueLevel[] = [
   "inconsistencies",
@@ -34,6 +38,19 @@ export interface AutoPromptCritiqueAdvice {
   solution: string;
 }
 
+export interface QuestionOption {
+  label: string;
+  description: string;
+  value: string;
+}
+
+export interface QuestionResult {
+  /** "a", "b", or "c" */
+  choice: string;
+  /** Free-text answer when choice is "c". */
+  customAnswer: string;
+}
+
 const LEVEL_GUIDANCE: Record<AutoPromptCritiqueLevel, string> = {
   inconsistencies:
     "Low sensitivity. True contradiction/gap/ambiguity likely to make model misunderstand. Otherwise skip.",
@@ -43,6 +60,12 @@ const LEVEL_GUIDANCE: Record<AutoPromptCritiqueLevel, string> = {
     "High sensitivity. Hunt weak logic/inconsistency/vagueness/overreach. Skip only clearly logical+complete prompts.",
 };
 
+const QUESTIONS_FREQUENCY_LABELS: Record<QuestionsFrequency, string> = {
+  essential: "Essential only",
+  normal: "Normal",
+  verbose: "Verbose",
+};
+
 export function autoPromptCritiqueLevelLabel(level: AutoPromptCritiqueLevel): string {
   switch (level) {
     case "inconsistencies":
@@ -58,6 +81,111 @@ export function autoPromptCritiqueModelSourceLabel(source: AutoPromptCritiqueMod
   return source === "working" ? "Working model" : "Critique model";
 }
 
+export function questionsFrequencyLabel(freq: QuestionsFrequency): string {
+  return QUESTIONS_FREQUENCY_LABELS[freq];
+}
+
+/**
+ * Detect whether the user's input is ambiguous enough to warrant a
+ * clarifying question. Returns a suggested interpretation pair when one is
+ * found, or null when the input is clear.
+ */
+export function detectAmbiguity(
+  text: string,
+  hasImages: boolean,
+  level: QuestionsFrequency,
+): { interpretationA: string; interpretationB: string } | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[.!?¡¿,;:()\[\]{}"'`´]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  // Skip trivial/acknowledgement inputs.
+  const bareReplies = new Set([
+    "ok",
+    "okay",
+    "yes",
+    "no",
+    "y",
+    "n",
+    "thanks",
+    "thank you",
+    "gracias",
+    "vale",
+    "sí",
+    "si",
+    "sigue",
+    "continua",
+    "continúa",
+    "continue",
+    "stop",
+    "para",
+    "no hagas eso",
+  ]);
+  if (bareReplies.has(normalized)) return null;
+
+  const words = normalized.split(/\s+/).filter(Boolean);
+  const wordCount = words.length;
+  const charCount = trimmed.length;
+
+  // Thresholds vary by frequency level.
+  const thresholds = {
+    essential: { minChars: 120, minWords: 14, hasNewlineBonus: true },
+    normal: { minChars: 70, minWords: 9, hasNewlineBonus: true },
+    verbose: { minChars: 40, minWords: 6, hasNewlineBonus: false },
+  };
+  const t = thresholds[level];
+
+  // Basic length/word check.
+  if (charCount < t.minChars && wordCount < t.minWords) return null;
+
+  // Newlines increase the chance of ambiguity (multi-sentence or structured input).
+  const hasNewline = trimmed.includes("\n");
+  if (hasNewline && t.hasNewlineBonus) {
+    // Already passed thresholds; proceed to ambiguity detection.
+  } else if (!hasNewline && charCount < t.minChars) {
+    return null;
+  }
+
+  // Heuristic ambiguity patterns:
+  // 1. Pronouns without clear referent ("it", "this", "that", "them")
+  // 2. Vague directives ("fix it", "improve this", "make it better")
+  // 3. Short ambiguous requests with unclear scope
+
+  const ambiguousPatterns = [
+    // Pronoun-heavy patterns
+    { pattern: /\b(it|this|that|them|those)\b/, interpretationA: "The most recently mentioned item/topic", interpretationB: "The overall task or goal" },
+    // Vague improvement requests
+    { pattern: /\b(fix|improve|change|adjust|modify|refactor)\b.*\b(it|this|that|them)\b/, interpretationA: "Fix the code/logic errors", interpretationB: "Improve the overall quality/style" },
+    // Scope-ambiguous requests
+    { pattern: /\b(make|do|handle|deal with|address)\b.*\b(it|this|that|them|the\b)/, interpretationA: "Focus on the primary/most obvious aspect", interpretationB: "Cover all aspects comprehensively" },
+    // Unclear referent with "the"
+    { pattern: /\b(the\s+\w+\s+\w+)\b.*\b(needs|requires|should|must)\b/, interpretationA: "The specific item mentioned", interpretationB: "The broader system or context" },
+    // General ambiguity with "something"
+    { pattern: /\b(something|anything|somewhere|someone)\b/, interpretationA: "The most relevant/obvious option", interpretationB: "Explore all possible options" },
+  ];
+
+  for (const ap of ambiguousPatterns) {
+    if (ap.pattern.test(normalized)) {
+      return { interpretationA: ap.interpretationA, interpretationB: ap.interpretationB };
+    }
+  }
+
+  // If we got here and the input is long enough, it's ambiguous by default.
+  if (charCount >= t.minChars * 1.5 && wordCount >= t.minWords * 1.5) {
+    return {
+      interpretationA: "Focus on the primary task or request",
+      interpretationB: "Address all aspects and edge cases",
+    };
+  }
+
+  return null;
+}
+
 /** Fast local gate: avoid paying a model call for acknowledgements and tiny commands. */
 export function isPromptCritiqueCandidate(
   text: string,
@@ -70,7 +198,8 @@ export function isPromptCritiqueCandidate(
   if (
     trimmed.includes("[Critique accepted by the user]") ||
     trimmed.includes("[Critique solution accepted by the user]") ||
-    trimmed.includes("[User reply to Critique]")
+    trimmed.includes("[User reply to Critique]") ||
+    trimmed.includes("[Questions answer]")
   ) {
     return false;
   }
@@ -271,3 +400,28 @@ export function buildPromptCritiqueReplyMessage(
     reply.trim(),
   ].join("\n");
 }
+
+export function buildQuestionsMessage(
+  originalPrompt: string,
+  interpretationA: string,
+  interpretationB: string,
+  choice: string,
+  customAnswer: string,
+): string {
+  const base = [
+    originalPrompt,
+    "",
+    "[Questions answer]",
+    `What the user meant:`,
+  ];
+
+  if (choice === "a") {
+    base.push(`Interpretation A: ${interpretationA}`);
+  } else if (choice === "b") {
+    base.push(`Interpretation B: ${interpretationB}`);
+  } else if (choice === "c") {
+    base.push(`User's own interpretation: ${customAnswer.trim()}`);
+  }
+
+  return base.join("\n");
+}