import type { SandboxHandle } from "../manager";
import type { SandboxSearch } from "../contracts/search";
import type { MimeResolver } from "../contracts/mime_resolver";
import type { Tool as AdkTool } from "../../../lib/classes/tool";
import type { MediaTrustTier } from "../../../common";
import type { SandboxFileSystem } from "../contracts/file_system";
import type { PathTranslator } from "../contracts/path_translator";
import type { ArtifactMinter } from "../contracts/artifact_minter";
import type { DispatchContext } from "../../../lib/contracts/dispatch_context";
type GateVerdict = {
    approved: true;
} | {
    approved: false;
    note?: string;
};
type Gate = (ctx: DispatchContext, call: {
    tool: string;
    args: unknown;
}) => GateVerdict | void | Promise<GateVerdict | void>;
/** Options for constructing the sandbox's eight untrusted filesystem tools. */
export interface SandboxToolsOptions {
    /**
     * The handle that owns this tool set and issues its reader epoch.
     *
     * @remarks
     * File-backed readers retain this epoch and check it before every operation. After
     * {@link SandboxHandle.dispose} they fail with `E_SANDBOX_NOT_INITIALIZED` rather than
     * falling through to the host filesystem.
     */
    handle: SandboxHandle;
    /** The filesystem capability used for stat, traversal, reads, and writes. */
    fileSystem: SandboxFileSystem;
    /** Translates model-visible paths into the sandbox backend and back. */
    pathTranslator: PathTranslator;
    /**
     * Required approval callback for every tool, including reads and searches.
     *
     * @remarks
     * A read of `.env` is an exfiltration event, and `search_files` is a secret-discovery
     * primitive, so construction rejects a missing gate with `E_SANDBOX_GATE_REQUIRED`.
     * Calling the gate is a real suspension: a harness without a decider leaves the turn
     * waiting rather than silently allowing the operation.
     */
    gate: Gate;
    /**
     * Search backend for `search_files` and `find_files`.
     *
     * @remarks
     * These tools spawn `rg` through the sandbox enforcer and are OS-enforced; they do not
     * have the in-process filesystem tools' weaker enforcement boundary.
     */
    search?: SandboxSearch;
    /** Factory for artifacts returned by file-query tools; defaults to the battery minter. */
    artifactMinter?: ArtifactMinter;
    /** Resolves MIME types while staging a file; defaults to the extension resolver. */
    mimeResolver?: MimeResolver;
    /** Explicit host write root; it is never inferred. */
    writeRoot: string;
    /**
     * Configuration-supplied provenance for staged media.
     *
     * @remarks
     * This value cannot be inferred from `source`: core requires an explicit trust tier and
     * batteries must not auto-classify content.
     */
    trustTier: MediaTrustTier;
    /** Tools which are not registered are not named in descriptions. */
    registeredTools?: readonly string[];
}
/**
 * Run a `PathTranslator` operation and narrate any refusal it raises.
 *
 * @remarks
 * EVERY translator call must go through here, not just the obvious `toRelative`. `toBackendPath` and
 * `assertNoSymlinkComponents` both reject — the latter is the symlinked-component refusal, which is a
 * security control — and a bare call lets that escape as the translator's native error, bypassing the
 * narrator seam the whole battery depends on. The model then receives an unactionable message for the
 * one class of failure it could actually correct.
 *
 * An already-narrated exception passes through untouched, so wrapping a call that itself narrates is
 * safe and the outcome is never rendered twice.
 *
 * @param operation - The translator call.
 * @param input - The model-supplied path, echoed back in the outcome.
 * @param reason - The `path-rejected` reason to narrate.
 * @returns The operation's result.
 */
export declare const narratingPath: <T>(operation: () => T | Promise<T>, input: string) => Promise<T>;
declare const descriptions: {
    open: string;
    stage: string;
    save: string;
};
/**
 * Construct the sandbox's file, media, directory, and search tools.
 *
 * @remarks
 * All returned tools are untrusted and gate their operations, including reads. The factory
 * keeps the supplied handle, filesystem, path translator, search backend, and configuration
 * together so the tools cannot accidentally bypass the sandbox boundary.
 *
 * @param options - Capabilities and configuration for the sandbox tool set.
 * @returns The eight tools registered for a sandbox handle.
 */
export declare const createSandboxTools: (options: SandboxToolsOptions) => Promise<AdkTool[]>;
/** Alias for {@link createSandboxTools}, used by tool-forging integrations. */
export declare const forgeSandboxTools: (options: SandboxToolsOptions) => Promise<AdkTool[]>;
/** Human-readable descriptions shared by the sandbox's workspace tools. */
export { descriptions as sandboxToolDescriptions };