/**
 * Hook system types for the Agent Runtime.
 *
 * Hooks allow hosts and middleware to intercept, modify, or observe events
 * at well-defined lifecycle points during session, turn, and tool execution.
 */
/**
 * All supported hook points in the Agent Runtime lifecycle.
 */
export type HookPoint = "session.created" | "session.ended" | "turn.submitted" | "turn.before_inference" | "turn.after_inference" | "turn.completed" | "turn.failed" | "tool.before_invoke" | "tool.after_invoke" | "tool.invoke_failed" | "approval.requested" | "approval.responded" | "permission.denied" | "context.before_compact" | "context.after_compact" | "memory.before_recall" | "memory.after_recall" | "subagent.started" | "subagent.stopped" | "stop" | "stop.failed" | "stop.failure" | "task.created" | "task.completed" | "file.changed" | "cwd.changed" | "config.changed" | "instructions.loaded";
export interface HookSessionContext {
    sessionId: string;
    gatewayId?: string;
    deviceId?: string;
    mode?: string;
}
export interface HookTurnContext extends HookSessionContext {
    turnId: string;
    executionId?: string;
    rootExecutionId?: string;
}
export interface HookToolContext extends HookTurnContext {
    callId: string;
    toolName: string;
    arguments?: Record<string, unknown>;
}
export interface HookApprovalContext extends HookTurnContext {
    approvalId: string;
    callId?: string;
    toolName?: string;
    decision?: "allow" | "deny" | "expired" | "cancelled";
}
export interface HookSubagentContext extends HookTurnContext {
    subagentId: string;
    agentType?: string;
    parentExecutionId?: string;
    /** Exit reason when stopped (normal / error / timeout) */
    reason?: string;
    error?: string;
}
export interface HookStopContext extends HookSessionContext {
    reason?: string;
    error?: string;
}
export interface HookTaskContext extends HookSessionContext {
    taskId: string;
    taskType?: string;
    label?: string;
    error?: string;
}
export interface HookFileChangedContext extends HookSessionContext {
    filePath: string;
    changeType: "created" | "modified" | "deleted";
}
export interface HookCwdChangedContext extends HookSessionContext {
    oldCwd: string;
    newCwd: string;
}
export interface HookConfigChangedContext extends HookSessionContext {
    key: string;
    oldValue?: unknown;
    newValue?: unknown;
}
export interface HookInstructionsLoadedContext extends HookSessionContext {
    source: string;
    fileCount: number;
}
export interface HookContextMap {
    "session.created": HookSessionContext;
    "session.ended": HookSessionContext;
    "turn.submitted": HookTurnContext & {
        prompt?: string;
    };
    "turn.before_inference": HookTurnContext & {
        model?: string;
        messages?: unknown[];
    };
    "turn.after_inference": HookTurnContext & {
        model?: string;
        response?: unknown;
        success?: boolean;
        error?: string;
    };
    "turn.completed": HookTurnContext & {
        outcomeId?: string;
    };
    "turn.failed": HookTurnContext & {
        code?: string;
        error?: string;
    };
    "tool.before_invoke": HookToolContext;
    "tool.after_invoke": HookToolContext & {
        result?: unknown;
        ok: boolean;
    };
    "tool.invoke_failed": HookToolContext & {
        error?: string;
    };
    "approval.requested": HookApprovalContext;
    "approval.responded": HookApprovalContext;
    "permission.denied": HookApprovalContext & {
        reason?: string;
    };
    "context.before_compact": HookTurnContext & {
        tokenCount?: number;
        messageCount?: number;
    };
    "context.after_compact": HookTurnContext & {
        tokenCount?: number;
        removedCount?: number;
    };
    "memory.before_recall": HookTurnContext & {
        query?: string;
        recalledMemories?: Array<{
            text: string;
            score?: number;
            category?: string | null;
            source?: string;
            label?: string;
        }>;
        preferredCategories?: string[];
        deprioritizedCategories?: string[];
    };
    "memory.after_recall": HookTurnContext & {
        blockCount?: number;
    };
    "subagent.started": HookSubagentContext;
    "subagent.stopped": HookSubagentContext;
    "stop": HookStopContext;
    "stop.failed": HookStopContext;
    "stop.failure": HookStopContext & {
        errorDetails?: string;
    };
    "task.created": HookTaskContext;
    "task.completed": HookTaskContext;
    "file.changed": HookFileChangedContext;
    "cwd.changed": HookCwdChangedContext;
    "config.changed": HookConfigChangedContext;
    "instructions.loaded": HookInstructionsLoadedContext;
}
/**
 * Result of a hook handler invocation.
 *
 * - `continue`: proceed normally (optionally with modified context)
 * - `abort`: stop execution (for "before" hooks only)
 * - `skip`: skip this step but continue the overall flow
 */
export interface HookResult<T = unknown> {
    action: "continue" | "abort" | "skip" | "prevent";
    /** Modified context to pass downstream (only for "continue") */
    context?: T;
    /** Reason for abort/skip/prevent (for logging) */
    reason?: string;
}
/**
 * A hook handler function.
 *
 * @param point - The hook point being invoked
 * @param context - Event-specific context data
 * @returns A HookResult or void (treated as "continue")
 */
export type HookHandler<P extends HookPoint = HookPoint> = (point: P, context: HookContextMap[P]) => HookResult<HookContextMap[P]> | void | Promise<HookResult<HookContextMap[P]> | void>;
/**
 * Hook registration entry.
 */
export interface HookRegistration<P extends HookPoint = HookPoint> {
    point: P;
    handler: HookHandler<P>;
    /** Priority (lower = earlier). Default: 100 */
    priority?: number;
    /** Optional label for debugging */
    label?: string;
    /**
     * Critical hooks are part of the execution preflight. If they throw, the
     * registry returns an abort result instead of treating the failure as a
     * non-blocking observer error.
     */
    critical?: boolean;
}
/**
 * Interface for a hook registry that manages hook handlers.
 */
export interface HookRegistry {
    register<P extends HookPoint>(registration: HookRegistration<P>): () => void;
    invoke<P extends HookPoint>(point: P, context: HookContextMap[P]): Promise<HookResult<HookContextMap[P]>>;
}
