/**
 * Common flag parser for query/execute commands.
 *
 * Supports both `--flag=value` and `--flag value` forms.
 * Handles: --thread, --provider, --metadata, --verbose, --config/-c,
 *          --output-format, --effort, --prompt-file/-f.
 *
 * Strict mode: unknown --xxx tokens after known flags are consumed throw an
 * error instead of silently leaking into the message prompt.
 * Use `--` sentinel to pass literal flag-like tokens as positional args.
 */
export interface CommonFlags {
    /** Thread name for conversation continuity. */
    thread?: string;
    /** Provider override (e.g., cli/claude). */
    provider?: string;
    /** Raw metadata JSON string. */
    metadata?: string;
    /** Enable verbose/debug output mode. */
    verbose: boolean;
    /** Config file path override. */
    config?: string;
    /** Output format (json | text | stream-json). */
    outputFormat?: string;
    /** Model effort level (high | medium | low). */
    effort?: string;
    /** Path to a file whose content is used as the prompt body (-f/--prompt-file). */
    promptFile?: string;
    /** Template variables from --var key=value flags. */
    vars: Record<string, string>;
    /** Remaining non-flag positional arguments. */
    rest: string[];
}
/**
 * Thrown by parseCommonFlags when an unrecognized --xxx flag is encountered.
 * Callers can distinguish this from other errors to map to exit code 2.
 */
export declare class UnknownOptionError extends Error {
    constructor(message: string);
}
/**
 * Parse common CLI flags from an args array.
 *
 * Strict mode: any unconsumed `--xxx` token (outside a `--` escape block)
 * throws `UnknownOptionError: Unknown option: --xxx.`
 *
 * Tokens after `--` are treated as positional and included in `rest` as-is.
 * The `--` sentinel itself is NOT included in `rest`.
 */
export declare function parseCommonFlags(args: string[]): CommonFlags;
/**
 * Parse metadata JSON string from --metadata flag.
 * Returns empty object when no raw value provided.
 * Throws Error on invalid JSON or non-object values (fail-fast).
 */
export declare function parseMetadata(raw?: string): Record<string, unknown>;