/**
 * Permission-mode catalog for a harness.
 *
 * Source of truth is AGENTS[id].capabilities.modes plus the native CLI flags
 * in AGENT_COMMANDS.modeFlags. This is the modes analog of the model catalog
 * (`agents models`) — what a human or orchestrating agent reads before
 * `agents run <agent> --mode …` / `agents teams add … --mode …`.
 */
import type { AgentId, Mode } from './types.js';
/** Human description for each canonical permission mode. */
export declare const MODE_DESCRIPTIONS: Record<Mode, string>;
export interface AgentModeEntry {
    mode: Mode;
    /** Native CLI flags agents-cli forwards for this mode (empty = harness default). */
    flags: string[];
    description: string;
    /** First entry in capabilities.modes — the safest native mode. */
    isDefault: boolean;
}
export interface AgentModesCatalog {
    agent: AgentId;
    /** Modes this harness natively supports, in declaration order. */
    modes: AgentModeEntry[];
    /** capabilities.modes[0] — safest native mode; run may still default elsewhere (e.g. CLI plan, teams edit). */
    defaultMode: Mode;
    /**
     * Configured run.defaults mode for this agent@version, when set.
     * Null means no pin — CLI default (plan for most harnesses) or modes[0] applies.
     */
    configuredMode: Mode | null;
    configuredModeSource: string | null;
    /**
     * Whether plan works in a headless (`-p` / prompt) run. false means a headless
     * --mode plan degrades (see resolveHeadlessMode). undefined = assumed true.
     */
    headlessPlan: boolean;
    /** Canonical modes this harness does NOT list in capabilities.modes. */
    unsupported: Mode[];
    /** Notes an orchestrator should read before picking a mode. */
    notes: string[];
}
/**
 * Build the permission-mode catalog for one harness.
 * `version` only affects the configured run.defaults lookup (modes themselves
 * are per-agent today, not version-gated).
 */
export declare function getAgentModesCatalog(agent: AgentId, version?: string | null, cwd?: string): AgentModesCatalog;
/** Format native flags for display, e.g. `--permission-mode plan` or `(harness default)`. */
export declare function formatModeFlags(flags: string[]): string;
