/**
 * clarify_with_user — given an ambiguous prompt, return 1–3 targeted
 * clarifying questions instead of guessing. The complement to optimize_prompt:
 * when the analyzer's confidence is `low`, or the prompt is short and vague,
 * the engine asks the user *first* rather than emitting a confident-but-wrong
 * rewrite.
 *
 * The module never blocks. If the user explicitly opts in (force=true), or
 * the analyzer's confidence is medium/low, we ask the LLM to surface the
 * most ambiguous dimensions (audience, scope, format, length, constraints,
 * tone) and return targeted questions WITH suggested defaults — so the
 * caller can always proceed without a back-and-forth if they choose to.
 *
 * On the LLM side we ask for STRICT JSON to keep this deterministic for
 * the eval harness; on parse failure we degrade gracefully to a generic
 * fallback question rather than throwing.
 */
import type { Category } from '../config/categories.js';
import type { AnalysisSignal } from '../context/types.js';
export interface ClarifyInputs {
    prompt: string;
    category?: Category;
    cwd?: string;
    filePath?: string;
    fileLanguage?: string;
    fileExcerpt?: string;
    userLocale?: string;
    /**
     * When true, generate questions even if the analyzer is highly confident.
     * Default: false (skip when confidence === 'high' AND prompt looks complete).
     */
    force?: boolean;
    /** Cap on returned questions. Default 3, hard max 5. */
    maxQuestions?: number;
    /**
     * Override the LLM model for this clarify call. When omitted, uses LLM_MODEL
     * from env. Useful with per-stage routing in compose_prompt — e.g. run
     * clarify on a cheap model and optimize on a frontier model.
     */
    model?: string;
    /** Per-call cancellation signal (1.10.0) — aborts the clarify LLM call. */
    signal?: AbortSignal;
}
export interface ClarifyQuestion {
    question: string;
    reasoning: string;
    /**
     * A reasonable default the caller can use verbatim to keep moving.
     * Always populated; falls back to "Use your best judgment based on context."
     * if the LLM declined to suggest one.
     */
    suggestedAnswer: string;
    /**
     * Optional 2–4 multiple-choice alternatives. Useful for chat/UI clients
     * that want to render quick-pick buttons instead of free-form input.
     */
    options?: string[];
    /** Which ambiguous dimension this question addresses. */
    dimension: ClarifyDimension;
}
export type ClarifyDimension = 'audience' | 'scope' | 'format' | 'length' | 'tone' | 'constraints' | 'goal' | 'platform' | 'other';
export interface ClarifyResult {
    clarificationNeeded: boolean;
    reason: string;
    questions: ClarifyQuestion[];
    analysis?: {
        category: AnalysisSignal['category'];
        intent: AnalysisSignal['intent'];
        confidence: AnalysisSignal['confidence'];
        recommendedMode: AnalysisSignal['recommendedMode'];
    };
    /** ms spent in this call (LLM + analysis). */
    latencyMs: number;
}
export declare function clarifyPrompt(inputs: ClarifyInputs): Promise<ClarifyResult>;