export interface AgentDef {
    name: string;
    description?: string;
    model?: string;
    thinking?: string;
    tools?: string[];
    excludeTools?: string[];
    aliases?: string[];
    /** Where it was found: a project's agents are picked by `@name` only (they come with the repository). */
    source?: "builtin" | "package" | "user" | "project";
    /** pi-subagents' default is replace: the agent's prompt is the whole system prompt. */
    systemPromptMode: "replace" | "append";
    prompt: string;
    file: string;
}
/** A tiny frontmatter reader: `key: value` lines and `- item` lists, which agent files use. */
export declare function parseFrontmatter(text: string): {
    data: Record<string, string | string[]>;
    body: string;
} | undefined;
/** One agent file, or undefined when it is not a pi agent (another runner, disabled, malformed). */
export declare function readAgent(file: string): AgentDef | undefined;
export declare function agentDir(env?: NodeJS.ProcessEnv): string;
/**
 * Agents by name, as pi-subagents loads them, lowest priority first: builtins, then
 * packages (the first one with a name keeps it), then the user's
 * (`~/.pi/agent/agents`, then `~/.agents`), then the project's (`.agents`, `.pi/agents`);
 * a later one with the same name wins.
 */
export declare function discoverAgents(cwd: string, env?: NodeJS.ProcessEnv): Map<string, AgentDef>;
/** An agent by its name or one of its aliases. */
export declare function findAgent(agents: ReadonlyMap<string, AgentDef>, name: string): AgentDef | undefined;
/**
 * pi flags that make the agent the session's main agent. pi-roost's own tools stay on
 * (`roost_*`): a child reports and talks through them.
 */
export declare function agentArgs(a: AgentDef, opts?: {
    model?: boolean;
    thinking?: boolean;
}): string[];
/**
 * Claude Code: a first word, or `@name`, that names an agent selects it. The rest is
 * the task; a lone name is not a task. A project's agent (it came with the repository)
 * needs `@name`: a first word that happens to be its name is just a word.
 */
export declare function pickAgent(task: string, agents: ReadonlyMap<string, AgentDef>): {
    agent: AgentDef;
    task: string;
} | undefined;