/**
 * OpenClaw-inspired Tool Lifecycle Hook System
 *
 * Implements priority-ordered, typed hooks for tool execution:
 *
 * Execution Models:
 * - Void Hooks (parallel): Fire-and-forget, run all handlers simultaneously
 * - Modifying Hooks (sequential): Execute in priority order, can transform data
 *
 * Tool-specific hooks:
 * - before_tool_call: Modify or block tool calls (sequential)
 * - after_tool_call: Observer hook post-execution (parallel)
 * - tool_result_persist: Synchronous hook for transcript persistence
 */
import { EventEmitter } from 'events';
export type HookEvent = 'before_tool_call' | 'after_tool_call' | 'tool_result_persist' | 'agent_start' | 'agent_end' | 'message_received' | 'message_sending';
export type HookExecutionMode = 'parallel' | 'sequential' | 'sync';
export interface HookContext {
    toolName?: string;
    toolArgs?: Record<string, unknown>;
    toolCallId?: string;
    sessionId?: string;
    agentId?: string;
    timestamp: Date;
}
export interface ToolCallContext extends HookContext {
    toolName: string;
    toolArgs: Record<string, unknown>;
    toolCallId: string;
}
export interface ToolResultContext extends ToolCallContext {
    result: {
        success: boolean;
        output?: string;
        error?: string;
    };
    durationMs: number;
}
export interface BeforeToolCallResult {
    /** If true, block the tool call */
    blocked?: boolean;
    /** Reason for blocking */
    blockReason?: string;
    /** Modified arguments to use instead */
    modifiedArgs?: Record<string, unknown>;
    /** Additional context to pass through */
    metadata?: Record<string, unknown>;
}
export interface HookHandler<TContext = HookContext, TResult = void> {
    /** Unique identifier for this handler */
    id: string;
    /** Higher priority handlers execute first */
    priority: number;
    /** The handler function */
    handler: (context: TContext) => TResult | Promise<TResult>;
    /** Whether to catch errors (log instead of propagate) */
    catchErrors?: boolean;
    /** Description for debugging */
    description?: string;
}
export declare class ToolLifecycleHooks extends EventEmitter {
    private hooks;
    private executionStats;
    constructor();
    /**
     * Register a hook handler
     */
    register<TContext = HookContext, TResult = void>(event: HookEvent, handler: HookHandler<TContext, TResult>): () => void;
    /**
     * Unregister a hook handler
     */
    unregister(event: HookEvent, handlerId: string): boolean;
    /**
     * Execute before_tool_call hooks (sequential, can block/modify)
     */
    executeBeforeToolCall(context: ToolCallContext): Promise<BeforeToolCallResult>;
    /**
     * Execute after_tool_call hooks (parallel, fire-and-forget)
     */
    executeAfterToolCall(context: ToolResultContext): Promise<void>;
    /**
     * Execute tool_result_persist hooks (SYNCHRONOUS - for hot paths)
     * WARNING: Handlers MUST be synchronous. Async handlers will trigger a warning.
     */
    executeToolResultPersist(context: ToolResultContext): void;
    /**
     * Execute generic hooks based on their mode
     */
    executeHooks(event: HookEvent, context: HookContext): Promise<void>;
    /**
     * Execute a handler with error handling
     */
    private executeHandler;
    /**
     * Execute handler with safe error handling
     */
    private executeHandlerSafe;
    /**
     * Execute handler synchronously
     */
    private executeHandlerSync;
    /**
     * Record execution statistics
     */
    private recordExecution;
    /**
     * Check if any hooks are registered for an event
     */
    hasHooks(event: HookEvent): boolean;
    /**
     * Get the number of hooks for an event
     */
    getHookCount(event: HookEvent): number;
    /**
     * Get all registered handlers for an event
     */
    getHandlers(event: HookEvent): HookHandler<any, any>[];
    /**
     * Get execution statistics
     */
    getStats(): Map<string, {
        calls: number;
        errors: number;
        totalMs: number;
        avgMs: number;
    }>;
    /**
     * Clear all hooks
     */
    clearAll(): void;
    /**
     * Clear hooks for a specific event
     */
    clearEvent(event: HookEvent): void;
}
export declare function getToolLifecycleHooks(): ToolLifecycleHooks;
export declare function resetToolLifecycleHooks(): void;
/**
 * Convenience: Register a before_tool_call hook
 */
export declare function onBeforeToolCall(id: string, handler: (context: ToolCallContext) => BeforeToolCallResult | Promise<BeforeToolCallResult>, options?: {
    priority?: number;
    catchErrors?: boolean;
    description?: string;
}): () => void;
/**
 * Convenience: Register an after_tool_call hook
 */
export declare function onAfterToolCall(id: string, handler: (context: ToolResultContext) => void | Promise<void>, options?: {
    priority?: number;
    catchErrors?: boolean;
    description?: string;
}): () => void;
/**
 * Convenience: Register a tool_result_persist hook (SYNC ONLY)
 */
export declare function onToolResultPersist(id: string, handler: (context: ToolResultContext) => void, options?: {
    priority?: number;
    catchErrors?: boolean;
    description?: string;
}): () => void;
/**
 * Create a logging hook for tool calls
 */
export declare function createLoggingHook(logFn?: (msg: string) => void): {
    before: () => void;
    after: () => void;
};
/**
 * Create a rate limiting hook
 */
export declare function createRateLimitHook(maxCallsPerMinute: number, toolPattern?: RegExp): () => void;
/**
 * Create an argument sanitization hook
 */
export declare function createSanitizationHook(sanitizers: Record<string, (args: Record<string, unknown>) => Record<string, unknown>>): () => void;
