/**
 * Recovery hints for structured CLI errors.
 *
 * Recovery metadata is consumed by coding agents through JSON stderr output.
 * Hints describe the deterministic next step the caller can take to fix the
 * failure: the exact command to run, whether host shell access is required,
 * and (optionally) related docs links.
 *
 * Keep hints conservative: only include `command` when the next action is
 * unambiguous and safe. When the correct next step depends on user intent,
 * provide `description` only.
 */
import type { InteractionMode } from './interaction-mode.js';
export interface RecoveryHint {
    /** Human-readable next step for both humans and agents. */
    description: string;
    /** Exact command to run, when deterministic. */
    command?: string;
    /** True when the command must run on the user's host shell, not in the current sandbox. */
    hostShellRequired?: boolean;
    /** Optional documentation URL. */
    docsUrl?: string;
    /** Optional markdown-capable documentation URL. Only set when route support is verified. */
    docsMarkdownUrl?: string;
}
export interface RecoveryHints {
    hints: RecoveryHint[];
}
/** Build mode-aware recovery hints for `auth_required` errors. */
export declare function authLoginRecovery(options: {
    mode: InteractionMode;
    env?: NodeJS.ProcessEnv;
}): RecoveryHints;
/** Build a `confirmation_required` recovery hint, attaching a command only when the exact rerun is known. */
export declare function confirmationRecovery(command?: string): RecoveryHints;
/** Build a `missing_args` recovery hint, attaching a command only when it is directly runnable. */
export declare function missingArgsRecovery(command: string | undefined, description: string): RecoveryHints;