/**
 * Tool Lifecycle Hooks System
 *
 * OpenClaw-inspired hook system for intercepting tool execution at multiple stages:
 * - before_tool_call: Modify parameters before execution
 * - after_tool_call: Process results after execution
 * - tool_result_persist: Transform results before transcript storage
 *
 * Features:
 * - Priority-based hook ordering
 * - Async hook execution
 * - Hook chaining with result passing
 * - Error isolation (one hook failure doesn't stop others)
 * - Plugin-prefixed hooks for tracking
 */
import { EventEmitter } from 'events';
/**
 * Hook execution stages
 */
export type ToolHookStage = 'before_tool_call' | 'after_tool_call' | 'tool_result_persist' | 'tool_error' | 'tool_timeout' | 'tool_denied';
/**
 * Tool execution context passed to hooks
 */
export interface ToolHookContext {
    /** Tool name */
    toolName: string;
    /** Original arguments */
    originalArgs: Record<string, unknown>;
    /** Current arguments (may be modified by previous hooks) */
    args: Record<string, unknown>;
    /** Tool call ID */
    toolCallId: string;
    /** Session ID */
    sessionId?: string;
    /** Agent ID */
    agentId?: string;
    /** Timestamp */
    timestamp: number;
    /** Custom metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Tool result passed to after hooks
 */
export interface ToolHookResult {
    /** Success status */
    success: boolean;
    /** Output content */
    output?: string;
    /** Error message */
    error?: string;
    /** Execution time in ms */
    executionTimeMs?: number;
    /** Whether result was modified by hooks */
    modified?: boolean;
    /** Provider-specific data */
    providerData?: Record<string, unknown>;
}
/**
 * Hook handler function type
 */
export type BeforeToolHook = (context: ToolHookContext) => Promise<ToolHookContext | void> | ToolHookContext | void;
export type AfterToolHook = (context: ToolHookContext, result: ToolHookResult) => Promise<ToolHookResult | void> | ToolHookResult | void;
export type PersistHook = (context: ToolHookContext, result: ToolHookResult) => ToolHookResult;
export type ErrorHook = (context: ToolHookContext, error: Error) => Promise<void> | void;
/**
 * Registered hook entry
 */
export interface RegisteredHook<T> {
    /** Hook ID */
    id: string;
    /** Hook name for display */
    name: string;
    /** Priority (higher = runs first) */
    priority: number;
    /** Hook handler */
    handler: T;
    /** Plugin ID if from plugin */
    pluginId?: string;
    /** Is hook enabled */
    enabled: boolean;
}
/**
 * Hook manager configuration
 */
export interface ToolHooksConfig {
    /** Enable hook system */
    enabled: boolean;
    /** Continue on hook error */
    continueOnError: boolean;
    /** Hook timeout in ms */
    hookTimeoutMs: number;
    /** Maximum hooks per stage */
    maxHooksPerStage: number;
    /** Enable hook metrics */
    enableMetrics: boolean;
}
/**
 * Default configuration
 */
export declare const DEFAULT_TOOL_HOOKS_CONFIG: ToolHooksConfig;
/**
 * Hook execution metrics
 */
export interface HookMetrics {
    /** Total executions */
    executions: number;
    /** Total errors */
    errors: number;
    /** Total timeouts */
    timeouts: number;
    /** Average execution time */
    avgExecutionTimeMs: number;
    /** Last execution time */
    lastExecutionTimeMs: number;
}
/**
 * Hook manager events
 */
export interface ToolHooksEvents {
    'hook:registered': (stage: ToolHookStage, hookId: string) => void;
    'hook:unregistered': (stage: ToolHookStage, hookId: string) => void;
    'hook:executed': (stage: ToolHookStage, hookId: string, durationMs: number) => void;
    'hook:error': (stage: ToolHookStage, hookId: string, error: Error) => void;
    'hook:timeout': (stage: ToolHookStage, hookId: string) => void;
}
/**
 * Manages tool lifecycle hooks
 */
export declare class ToolHooksManager extends EventEmitter {
    private config;
    private beforeHooks;
    private afterHooks;
    private persistHooks;
    private errorHooks;
    private timeoutHooks;
    private deniedHooks;
    private metrics;
    constructor(config?: Partial<ToolHooksConfig>);
    /**
     * Register a before_tool_call hook
     */
    registerBeforeHook(id: string, handler: BeforeToolHook, options?: {
        name?: string;
        priority?: number;
        pluginId?: string;
    }): void;
    /**
     * Register an after_tool_call hook
     */
    registerAfterHook(id: string, handler: AfterToolHook, options?: {
        name?: string;
        priority?: number;
        pluginId?: string;
    }): void;
    /**
     * Register a tool_result_persist hook (synchronous)
     */
    registerPersistHook(id: string, handler: PersistHook, options?: {
        name?: string;
        priority?: number;
        pluginId?: string;
    }): void;
    /**
     * Register a tool_error hook
     */
    registerErrorHook(id: string, handler: ErrorHook, options?: {
        name?: string;
        priority?: number;
        pluginId?: string;
    }): void;
    /**
     * Register a tool_timeout hook
     */
    registerTimeoutHook(id: string, handler: ErrorHook, options?: {
        name?: string;
        priority?: number;
        pluginId?: string;
    }): void;
    /**
     * Register a tool_denied hook
     */
    registerDeniedHook(id: string, handler: ErrorHook, options?: {
        name?: string;
        priority?: number;
        pluginId?: string;
    }): void;
    /**
     * Generic hook registration
     */
    private registerHook;
    /**
     * Unregister a hook
     */
    unregisterHook(stage: ToolHookStage, id: string): boolean;
    /**
     * Unregister all hooks from a plugin
     */
    unregisterPluginHooks(pluginId: string): number;
    /**
     * Enable/disable a hook
     */
    setHookEnabled(stage: ToolHookStage, id: string, enabled: boolean): boolean;
    /**
     * Execute before_tool_call hooks
     * Returns modified context or original if no modifications
     */
    executeBeforeHooks(context: ToolHookContext): Promise<ToolHookContext>;
    /**
     * Execute after_tool_call hooks
     * Returns modified result or original if no modifications
     */
    executeAfterHooks(context: ToolHookContext, result: ToolHookResult): Promise<ToolHookResult>;
    /**
     * Execute tool_result_persist hooks (synchronous)
     * Returns transformed result for transcript storage
     */
    executePersistHooks(context: ToolHookContext, result: ToolHookResult): ToolHookResult;
    /**
     * Execute tool_error hooks
     */
    executeErrorHooks(context: ToolHookContext, error: Error): Promise<void>;
    /**
     * Execute tool_timeout hooks
     */
    executeTimeoutHooks(context: ToolHookContext, error: Error): Promise<void>;
    /**
     * Execute tool_denied hooks
     */
    executeDeniedHooks(context: ToolHookContext, error: Error): Promise<void>;
    /**
     * Execute notification-style hooks (error, timeout, denied)
     */
    private executeNotificationHooks;
    /**
     * Get sorted hooks by priority (descending)
     */
    private getSortedHooks;
    /**
     * Get registry for a stage
     */
    private getRegistry;
    /**
     * Execute with timeout
     */
    private executeWithTimeout;
    /**
     * Handle hook error
     */
    private handleHookError;
    /**
     * Initialize metrics for a hook
     */
    private initMetrics;
    /**
     * Record hook execution metrics
     */
    private recordMetrics;
    /**
     * Get hook count by stage
     */
    getHookCounts(): Record<ToolHookStage, number>;
    /**
     * Get all registered hooks info
     */
    getRegisteredHooks(): Array<{
        stage: ToolHookStage;
        id: string;
        name: string;
        priority: number;
        enabled: boolean;
        pluginId?: string;
    }>;
    /**
     * Get metrics for a hook
     */
    getHookMetrics(hookId: string): HookMetrics | undefined;
    /**
     * Get all metrics
     */
    getAllMetrics(): Map<string, HookMetrics>;
    /**
     * Clear all hooks
     */
    clearAll(): void;
}
/**
 * Get the tool hooks manager instance
 */
export declare function getToolHooksManager(config?: Partial<ToolHooksConfig>): ToolHooksManager;
/**
 * Reset the tool hooks manager
 */
export declare function resetToolHooksManager(): void;
export default ToolHooksManager;
