/**
 * MCP (Model Context Protocol) server authorization.
 *
 * Provides types, parsers, and permission check helpers for securing
 * MCP tool calls across all harness plugins. Each harness represents
 * MCP tools differently — parsers normalize them into McpToolIdentifier,
 * and checkMcpPermission runs server-level (and optionally tool-level)
 * Ory permission checks.
 */
import type { OryAgentClient } from "./client.js";
import type { UserSubjectRef } from "./subject.js";
export interface McpToolIdentifier {
    /** The MCP server name (e.g., "github", "slack", "postgres"). */
    serverName: string;
    /** The tool name within the server (e.g., "create_issue", "query"). */
    toolName: string;
}
export interface McpPermissionCheckOptions {
    /**
     * Subject for the permission check. Either a direct SubjectID
     * (e.g. `session:abc123`) or a SubjectSet (e.g. `User:<UUID>`).
     * Build with `resolveUserSubject(client, fallback)`.
     */
    subject: UserSubjectRef;
    /** Namespace for server-level checks. Default: "mcp_servers". */
    serverNamespace?: string;
    /** Namespace for tool-level checks. Default: "mcp_tools". */
    toolNamespace?: string;
    /** Whether to also check tool-level permission. Default: false. */
    checkToolLevel?: boolean;
    /**
     * Attributes merged into the permission.check / permission.batch_check
     * activity events. Use this to carry the harness-side tool name and any
     * other context the Zanzibar tuple shape doesn't capture.
     */
    activityAttributes?: Record<string, unknown>;
}
export interface McpPermissionResult {
    /** Whether the server-level check passed. */
    serverAllowed: boolean;
    /** Whether the tool-level check passed (true if not checked). */
    toolAllowed: boolean;
    /** Combined result: both server and tool (if checked) must be allowed. */
    allowed: boolean;
    checkedAt: string;
    mcpTool: McpToolIdentifier;
}
/**
 * Parse a Claude Code MCP tool name of the form `mcp__<server>__<tool>`.
 * Returns null if the name doesn't match the MCP pattern.
 *
 * Claude Code uses double underscores as delimiters. The first `__` after
 * the `mcp__` prefix separates the server name from the tool name. Server
 * names may contain single underscores.
 */
export declare function parseClaudeCodeMcpTool(toolName: string): McpToolIdentifier | null;
/**
 * Parse MCP context from Gemini CLI hook input.
 * Gemini provides server info via the `mcp_context` field.
 */
export declare function parseGeminiMcpTool(toolName: string, mcpContext?: Record<string, unknown>): McpToolIdentifier | null;
/**
 * Generic MCP tool parser for harnesses that use a `mcp:<server>:<tool>`
 * convention. Returns null if the tool ID doesn't start with the prefix.
 */
export declare function parseMcpToolGeneric(toolId: string, mcpPrefix?: string): McpToolIdentifier | null;
/**
 * Check MCP server-level (and optionally tool-level) permissions.
 *
 * Server check: namespace=mcp_servers, object=<serverName>, relation=use
 * Tool check:   namespace=mcp_tools,   object=<server>:<tool>, relation=invoke
 *
 * The subject is whatever the caller resolved (SubjectSet or direct ID).
 * Throws on API errors — callers handle fail-open behavior.
 */
export declare function checkMcpPermission(client: OryAgentClient, mcpTool: McpToolIdentifier, options: McpPermissionCheckOptions): Promise<McpPermissionResult>;