import type { AgentTool } from "@kenkaiiii/gg-agent";
/**
 * Two-tier split of the built-in toolset.
 *
 * Every tool in `this.tools` ships its full JSON parameter schema on every
 * request, inside the cached prefix. A core tool earns that cost because it is
 * reached in most sessions. A deferred tool does not: it contributes one
 * `- **name**: hint` line to the system prompt's Tools section (~15-25 tokens)
 * instead of a full schema (~300-500 tokens), and `tool_search` promotes it
 * into the live toolset the moment the model asks for that capability.
 *
 * The index line is what makes deferral safe. Dropping a schema WITHOUT
 * advertising the capability trades tokens for capability blindness — the model
 * cannot search for a tool it does not know exists. That is why every deferred
 * name is required to carry a `TOOL_PROMPT_HINTS` entry (enforced by test).
 *
 * Tier membership rule: a tool stays core if it is reached in more than roughly
 * one in five sessions. Deferring a tool is only safe while capability-discovery
 * rates hold: measure that, not just the token saving, before moving a name.
 */
export declare const CORE_TOOL_NAMES: readonly string[];
/**
 * Built-ins that live in the catalog as index lines until `tool_search` is
 * called. Each one is either rare (image generation, screenshots, package
 * source resolution) or only reachable after another tool has already run
 * (the child-agent control cluster follows `spawn_agent`).
 */
export declare const DEFERRED_TOOL_NAMES: readonly string[];
export interface ToolTierPartition {
    /** Tools whose full schema stays in every request. */
    core: AgentTool[];
    /** Tools held in the deferred catalog until `tool_search` promotes them. */
    deferred: AgentTool[];
}
/**
 * Split a freshly built toolset into its two tiers, preserving input order
 * within each tier. An unrecognised name (a future built-in, an MCP tool that
 * reached this path) defaults to `core`: shipping one extra schema is a token
 * cost, whereas silently hiding an unknown capability is a behaviour loss.
 */
export declare function partitionToolsByTier(tools: readonly AgentTool[]): ToolTierPartition;
//# sourceMappingURL=tool-tiers.d.ts.map