/**
 * Maps role allowedTools to pi-coding-agent CLI flags.
 *
 * Tools come from two sources (defined in .bobbit/config/tools/<group>/*.yaml `provider` field):
 * 1. **Builtin tools** (pi-coding-agent built-in): read, bash, edit, write, grep, find, ls
 *    → Controlled via `--tools` flag
 * 2. **Bobbit extensions** (.bobbit/config/tools/<group>/extension.ts): delegate, browser_*, web_*, task_*, gate_*, team_*, bash_bg
 *    → Resolved from .bobbit/config/tools/<groupDir>/extension.ts, controlled via `--extension` flag
 *    → Goal/team extensions are also added separately by session-manager (duplicates are harmless)
 *
 * Provider info is read from .bobbit/config/tools/<group>/*.yaml via ToolManager instead of hardcoded maps.
 * All sessions use `--no-extensions` so Bobbit has complete control over extension loading.
 *
 * Access control is handled by a single tool_call guard extension (see tool-guard-extension.ts)
 * instead of stub extensions and error regex matching.
 */
import type { ToolManager } from "./tool-manager.js";
import type { McpManager } from "../mcp/mcp-manager.js";
import type { GrantPolicy } from "./role-store.js";
import { type ToolPolicyEntry } from "./tool-guard-extension.js";
import type { McpToolDef } from "../mcp/mcp-types.js";
/** Interface for the group policy store to avoid circular dependency on the class. */
export interface GroupPolicyProvider {
    getGroupPolicy(group: string): GrantPolicy | null;
    /** Optional bulk-read used by cache fingerprinting. */
    getAll?(): Record<string, GrantPolicy>;
}
/**
 * Resolve the effective grant policy for a tool.
 * Priority: role tool-specific > role group-level > tool YAML default > group default > system fallback.
 * Always returns a concrete policy (never null).
 *
 * Normalizes old policy values internally: `always-allow`→allow, `ask-once`/`always-ask`→ask, `never-ask`→never.
 */
export declare function resolveGrantPolicy(toolName: string, toolGroup: string | undefined, role: {
    toolPolicies?: Record<string, GrantPolicy>;
} | undefined, toolManager: ToolManager | undefined, groupPolicyStore?: GroupPolicyProvider): GrantPolicy;
/**
 * Two-level MCP policy keys derived from a tool name. Used by
 * `resolveGrantPolicy` to consult the most-specific match first.
 *
 *   - `group` covers an entire MCP server (every sub-namespace under it).
 *   - `tool`  covers one sub-namespace meta-tool (or, for flat servers,
 *             equals `group`).
 *
 * Examples (all four name shapes):
 *
 *   | Tool name                                   | group              | tool                          |
 *   |---------------------------------------------|--------------------|-------------------------------|
 *   | `mcp__gr__ai-adoption__list-articles`       | `mcp__gr`          | `mcp__gr__ai-adoption`        |
 *   | `mcp__playwright__click` (flat)             | `mcp__playwright`  | `mcp__playwright`             |
 *   | `mcp_gr__ai-adoption` (meta + sub)          | `mcp__gr`          | `mcp__gr__ai-adoption`        |
 *   | `mcp_playwright` (meta flat)                | `mcp__playwright`  | `mcp__playwright`             |
 */
export interface McpPolicyKeys {
    group: string;
    tool: string;
}
/**
 * Compute the `{group, tool}` policy keys for a Bobbit tool name. Returns
 * `undefined` for non-MCP tool names. Single source of truth — callers
 * should not parse MCP names directly.
 */
export declare function mcpPolicyKeys(toolName: string): McpPolicyKeys | undefined;
/**
 * Backward-compat helper — returns the **group**-level MCP policy key for a
 * tool name, or `undefined` for non-MCP names. New code should call
 * `mcpPolicyKeys` to also get the tool-level key.
 *
 * Unchanged for legacy callers: `mcp__<server>__<op>` → `mcp__<server>`,
 * `mcp_<server>` → `mcp__<server>`.
 */
export declare function mcpPolicyPrefix(toolName: string): string | undefined;
/**
 * Tagged tool name. The activation pipeline must distinguish between two
 * fundamentally different kinds of tools that look identical at the string
 * level:
 *
 *   - `yaml`: a builtin or bobbit-extension tool with a YAML provider
 *     definition under `defaults/tools/<group>/*.yaml`. Resolvable through
 *     `ToolManager.getToolProviders()`. Includes `mcp_describe` (which is
 *     a builtin discovery tool with its own YAML).
 *   - `mcp`:  an MCP meta-tool name (`mcp_<server>` or
 *     `mcp_<server>__<sub>`) — NOT registered in the YAML provider registry.
 *     Served externally via `writeMcpProxyExtensions()` whose generated
 *     extension files are passed to `computeToolActivationArgs()` as the
 *     `mcpExtensionPaths` argument and emitted as `--extension <path>` flags.
 *
 * Each consumer must dispatch on `kind`. Yaml entries flow through the
 * provider registry; mcp entries are no-ops there. The `EffectiveTool[]`
 * shape removes the implicit name-shape detection that previously caused
 * `computeToolActivationArgs` to log spurious `"has no provider"` warnings
 * for every MCP meta-tool on every session spawn.
 */
export type EffectiveTool = {
    kind: "yaml";
    name: string;
} | {
    kind: "mcp";
    name: string;
};
/**
 * Tag a flat tool name into an `EffectiveTool` at the boundary where a
 * caller has only a `string[]` (e.g. session restoration, where
 * `session.allowedTools` is persisted as plain strings, or grant flows where
 * the user grants a tool by name). Centralised so the kind-detection logic
 * lives in exactly one place.
 *
 * Resolution order:
 *   1. If `toolManager` knows a provider for `name` → `yaml` (covers
 *      builtin/extension tools AND `mcp_describe`).
 *   2. Otherwise, if `name` parses as an MCP meta-tool shape → `mcp`.
 *   3. Otherwise → `yaml` (so unknown-tool typos still surface through the
 *      provider-lookup `"has no provider"` warn in `computeToolActivationArgs`).
 */
export declare function tagAllowedTool(name: string, toolManager?: ToolManager): EffectiveTool;
/**
 * Compute the effective allowed tools for a role by running every known tool
 * through the full resolveGrantPolicy cascade. Tools whose resolved policy
 * is `allow` OR `ask` are returned (both need to be registered — the guard
 * controls access for `ask` tools).
 *
 * Only `never` tools are excluded.
 *
 * Returns `EffectiveTool[]` — each entry is tagged at the producer with the
 * kind that determines downstream resolution (`yaml` via provider registry,
 * `mcp` via `mcpExtensionPaths`). See `EffectiveTool` for the contract.
 */
export declare function computeEffectiveAllowedTools(toolManager: ToolManager, role: {
    toolPolicies?: Record<string, GrantPolicy>;
} | undefined, groupPolicyStore?: GroupPolicyProvider, mcpManager?: {
    getToolInfos(): Array<{
        name: string;
        group: string;
        serverName: string;
    }>;
}): EffectiveTool[];
export interface ToolActivationResult {
    /** CLI args to add (e.g. ["--no-builtin-tools", "--no-extensions", "--extension", "/path/to/ext"]) */
    args: string[];
    /**
     * Env vars to set on the spawned agent process. Currently used only for
     * `BOBBIT_BUILTIN_TOOLS`, which the `_builtins` extension reads to decide
     * which pi file-tool builtins to re-register for this session.
     *
     * Always present (even when empty): for sessions with no builtin tools the
     * value is `""` so the extension registers nothing.
     */
    env: Record<string, string>;
}
/** Convert a JSON Schema object to a TypeBox code string. */
export declare function jsonSchemaToTypeBox(schema: Record<string, unknown>): string;
/**
 * Generate a pi-coding-agent extension that proxies MCP tool calls through the gateway.
 *
 * @deprecated Use `generateMcpMetaExtension` (track E of the MCP meta-tool
 * aggregation design). This per-op generator is retained for one cycle so any
 * out-of-tree consumers surface as TS deprecation warnings rather than
 * silently breaking. No in-tree callers remain.
 */
export declare function generateMcpProxyExtension(serverName: string, tools: Array<{
    name: string;
    bobbitName: string;
    description?: string;
    inputSchema: Record<string, unknown>;
}>): string;
/**
 * Generate a pi-coding-agent extension that registers ONE meta-tool
 * `mcp_<serverName>` covering all of `ops`. Replaces the per-op registrations
 * produced by `generateMcpProxyExtension`.
 *
 * The model sees a single tool with `operation` constrained to a
 * `Type.Union([Type.Literal(...)])` over valid op names, plus an opaque
 * `args` object. The generated execute body POSTs the canonical per-op
 * tool name `mcp__<server>__<operation>` to `/api/internal/mcp-call` —
 * the dispatcher and on-disk routing identifier are completely unchanged.
 *
 * When `unavailableReason` is provided OR `ops` is empty, emits a stub
 * meta-tool whose execute returns a structured unavailable message. The
 * agent turn never aborts at the protocol level when an MCP server is
 * down — the model gets a text result and moves on. (See §5.3 of the
 * MCP meta-tool aggregation design doc.)
 */
export declare function generateMcpMetaExtension(serverName: string, ops: McpToolDef[], unavailableReason?: string, sub?: string): string;
/**
 * Compute the effective policy and group for every known tool.
 * Returns a map of tool name → { policy: 'allow'|'ask'|'never', group }.
 */
export declare function computeToolPolicies(toolManager: ToolManager, mcpManager: McpManager | undefined, role: {
    toolPolicies?: Record<string, GrantPolicy>;
} | undefined, groupPolicyStore?: GroupPolicyProvider): Record<string, ToolPolicyEntry>;
/**
 * Write the tool_call guard extension if any tools have 'ask' policy.
 * Returns the file path of the written extension, or undefined if no guard is needed.
 */
export declare function writeToolGuardExtension(sessionId: string, toolManager: ToolManager, mcpManager: McpManager | undefined, role: {
    toolPolicies?: Record<string, GrantPolicy>;
} | undefined, groupPolicyStore?: GroupPolicyProvider, grantedTools?: string[]): string | undefined;
/**
 * Write proxy extension files for all connected MCP servers.
 * Returns array of written file paths.
 *
 * Generates proxy extensions for ALL MCP tools except those with `never` policy.
 * Access control for `ask` tools is handled by the tool_call guard extension,
 * not by stub extensions.
 */
export declare function writeMcpProxyExtensions(mcpManager: McpManager, allowedTools?: string[], role?: {
    toolPolicies?: Record<string, GrantPolicy>;
}, toolManager?: ToolManager, groupPolicyStore?: GroupPolicyProvider): string[];
/**
 * Given a role's allowedTools list and a ToolManager, compute the CLI args needed
 * to activate exactly those tools.
 *
 * If allowedTools is empty or undefined, all tools are enabled (all builtins + all bobbit extensions).
 * Always adds `--no-extensions` so Bobbit has complete control over extension loading.
 *
 * No leaked tool detection — the tool_call guard extension handles access control.
 */
export declare function computeToolActivationArgs(allowedTools?: EffectiveTool[], toolManager?: ToolManager, _cwd?: string, mcpExtensionPaths?: string[]): ToolActivationResult;
//# sourceMappingURL=tool-activation.d.ts.map