/**
 * Shell AST guard for the exec tool.
 *
 * Integrates the Shell AST normalization pipeline with the exec tool to
 * provide per-segment verdict evaluation and user-facing denial explanations.
 *
 * When AST command parsing is on (permissions.commandParser 'ast', the default), every exec
 * command is parsed into an AST, evaluated segment-by-segment, and denied
 * with a structured explanation if any segment fails policy.
 *
 * When the flag is disabled, this module falls back to the baseline
 * flat-token segmentation path.
 *
 * @module tools/exec/ast-guard
 */
import type { CompoundVerdict } from '../../runtime/permissions/normalization/verdict.js';
import type { CommandClassification } from '../../runtime/permissions/normalization/types.js';
import type { FeatureFlagManager } from '../../runtime/feature-flags/index.js';
type FlagManagerLike = Pick<FeatureFlagManager, 'isEnabled'>;
/**
 * The result of an AST guard evaluation for a single exec command.
 */
export interface ASTGuardResult {
    /** Whether the command is permitted by the AST guard. */
    allowed: boolean;
    /**
     * Human-readable denial explanation for user display.
     * Only set when `allowed` is false.
     */
    denialMessage?: string | undefined;
    /**
     * The full CompoundVerdict, available for upstream audit logging.
     * Only set when AST normalization is active.
     */
    verdict?: CompoundVerdict | undefined;
    /** Whether AST normalization was active. */
    astModeActive: boolean;
}
/**
 * Evaluates a shell command string through the AST guard.
 *
 * Routes to the AST pipeline when the `shell-ast-normalization` gate
 * is enabled, otherwise falls back to the baseline segmentation path.
 *
 * @param command        - The raw shell command string to evaluate.
 * @param allowedClasses - Classification tiers the caller permits (honored in
 *                         both AST and baseline modes). Callers fronted by the
 *                         permission layer pass ALL_COMMAND_CLASSES so class
 *                         risk is decided by user settings, not this guard.
 * @returns ASTGuardResult with allow/deny decision and optional denial message.
 *
 * @example
 * const result = guardExecCommand('ls /tmp && rm -rf /');
 * if (!result.allowed) {
 *   console.error(result.denialMessage);
 * }
 */
export declare function guardExecCommand(command: string, allowedClasses?: ReadonlySet<CommandClassification>, flagManager?: FlagManagerLike | null): Promise<ASTGuardResult>;
/**
 * Formats an ASTGuardResult denial into a structured exec tool error response.
 *
 * @param result - A denied ASTGuardResult.
 * @param cmd    - The original command string (for the error message).
 * @returns A structured error object suitable for returning from the exec tool.
 */
export declare function formatDenialResponse(result: ASTGuardResult, cmd: string): Record<string, unknown>;
export {};
//# sourceMappingURL=ast-guard.d.ts.map