@cleocode/core 2026.3.41 → 2026.3.43

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAsC,MAAM,qBAAqB,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,yBAAyB,CAAC;AAG5E;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAqDD;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAGjE,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IASH;;;;OAIG;IACH,WAAW,IAAI,SAAS;IAgBxB;;;;OAIG;IACH,gBAAgB,IAAI,cAAc;IAmBlC,4EAA4E;IAC5E,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAajC;;;OAGG;IACH,OAAO,CAAC,aAAa;CAetB"}

package/dist/hooks/handlers/error-hooks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Error Hook Handlers - Wave 2 of T5237
+ *
+ * Captures operation errors to BRAIN via memory.observe.
+ * Includes infinite-loop guard to prevent onError triggering onError.
+ * Auto-registers on module load.
+ */
+import type { OnErrorPayload } from '../types.js';
+/**
+ * Handle onError - capture operation errors to BRAIN
+ *
+ * Includes infinite-loop guard: if the payload has _fromHook marker,
+ * the handler skips to prevent onError -> observeBrain -> onError loops.
+ * Additionally, ALL observeBrain errors are silently suppressed to prevent
+ * re-entrant hook firing.
+ */
+export declare function handleError(projectRoot: string, payload: OnErrorPayload): Promise<void>;
+//# sourceMappingURL=error-hooks.d.ts.map

package/dist/hooks/handlers/error-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/error-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB7F"}

package/dist/hooks/handlers/file-hooks.d.ts

@@ -0,0 +1,20 @@
+/**
+ * File Change Hook Handlers - Wave 2 of T5237
+ *
+ * Captures file change events to BRAIN via memory.observe.
+ * Includes 5-second dedup and path-based filtering to avoid noisy writes.
+ * Auto-registers on module load.
+ *
+ * Disabled by default. Set CLEO_BRAIN_CAPTURE_FILES=true to enable.
+ */
+import type { OnFileChangePayload } from '../types.js';
+/**
+ * Handle onFileChange - capture file changes to BRAIN
+ *
+ * Gated behind CLEO_BRAIN_CAPTURE_FILES=true env var.
+ * Deduplicates rapid writes to the same file within a 5-second window.
+ * Filters out .cleo/ internal files and test temp directories.
+ * Converts absolute paths to project-relative paths.
+ */
+export declare function handleFileChange(projectRoot: string, payload: OnFileChangePayload): Promise<void>;
+//# sourceMappingURL=file-hooks.d.ts.map

package/dist/hooks/handlers/file-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/file-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA6BvD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/hooks/handlers/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hook Handlers Index - Phase 2D of T5237
+ *
+ * Barrel export for all hook handlers. Importing this module will
+ * auto-register all handlers with the hook registry.
+ */
+import './session-hooks.js';
+import './task-hooks.js';
+import './error-hooks.js';
+import './file-hooks.js';
+import './mcp-hooks.js';
+export { handleError } from './error-hooks.js';
+export { handleFileChange } from './file-hooks.js';
+export { handlePromptSubmit, handleResponseComplete } from './mcp-hooks.js';
+export { handleSessionEnd, handleSessionStart } from './session-hooks.js';
+export { handleToolComplete, handleToolStart } from './task-hooks.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/handlers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,oBAAoB,CAAC;AAC5B,OAAO,iBAAiB,CAAC;AACzB,OAAO,kBAAkB,CAAC;AAC1B,OAAO,iBAAiB,CAAC;AACzB,OAAO,gBAAgB,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/hooks/handlers/mcp-hooks.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP Prompt/Response Hook Handlers - Wave 2 of T5237
+ *
+ * Handlers for onPromptSubmit and onResponseComplete events.
+ * By default, NO brain capture (too noisy). Brain observation is
+ * opt-in via CLEO_BRAIN_CAPTURE_MCP=true environment variable.
+ * Auto-registers on module load.
+ */
+import type { OnPromptSubmitPayload, OnResponseCompletePayload } from '../types.js';
+/**
+ * Handle onPromptSubmit - optionally capture prompt events to BRAIN
+ *
+ * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ */
+export declare function handlePromptSubmit(projectRoot: string, payload: OnPromptSubmitPayload): Promise<void>;
+/**
+ * Handle onResponseComplete - optionally capture response events to BRAIN
+ *
+ * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ */
+export declare function handleResponseComplete(projectRoot: string, payload: OnResponseCompletePayload): Promise<void>;
+//# sourceMappingURL=mcp-hooks.d.ts.map

package/dist/hooks/handlers/mcp-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/mcp-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAgBpF;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/hooks/handlers/session-hooks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Session Hook Handlers - Phase 2D of T5237
+ *
+ * Handlers that capture session lifecycle events to BRAIN via memory.observe.
+ * Auto-registers on module load.
+ */
+import type { OnSessionEndPayload, OnSessionStartPayload } from '../types.js';
+/**
+ * Handle onSessionStart - capture initial session context
+ */
+export declare function handleSessionStart(projectRoot: string, payload: OnSessionStartPayload): Promise<void>;
+/**
+ * Handle onSessionEnd - capture session summary
+ */
+export declare function handleSessionEnd(projectRoot: string, payload: OnSessionEndPayload): Promise<void>;
+//# sourceMappingURL=session-hooks.d.ts.map

package/dist/hooks/handlers/session-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/session-hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAQ9E;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/hooks/handlers/task-hooks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Task Hook Handlers - Phase 2D of T5237
+ *
+ * Handlers that capture task lifecycle events to BRAIN via memory.observe.
+ * Auto-registers on module load.
+ */
+import type { OnToolCompletePayload, OnToolStartPayload } from '../types.js';
+/**
+ * Handle onToolStart (maps to task.start in CLEO)
+ */
+export declare function handleToolStart(projectRoot: string, payload: OnToolStartPayload): Promise<void>;
+/**
+ * Handle onToolComplete (maps to task.complete in CLEO)
+ */
+export declare function handleToolComplete(projectRoot: string, payload: OnToolCompletePayload): Promise<void>;
+//# sourceMappingURL=task-hooks.d.ts.map

package/dist/hooks/handlers/task-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-hooks.d.ts","sourceRoot":"","sources":["../../../src/hooks/handlers/task-hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAQ7E;;GAEG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hooks System - Barrel Export
+ *
+ * Central export point for the CLEO hooks system.
+ * Import from here to access the hook registry, types, and handlers.
+ *
+ * @module @cleocode/cleo/hooks
+ */
+export * from './handlers/index.js';
+export { HookRegistry, hooks } from './registry.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACpD,mBAAmB,YAAY,CAAC"}

package/dist/hooks/provider-hooks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Provider Hook Capabilities - Phase 2C of T5237
+ *
+ * Helper functions for querying which providers support which hook events.
+ * Wraps CAAMP's provider discovery functions with CLEO-specific helpers.
+ *
+ * @module @cleocode/cleo/hooks/provider-hooks
+ */
+import { type HookEvent as CAAMPHookEvent, getCommonHookEvents, getProvidersByHookEvent } from '@cleocode/caamp';
+import { type HookEvent } from './types.js';
+/**
+ * Get all providers that support a specific hook event
+ *
+ * @param event - The hook event to query
+ * @returns Array of provider IDs that support this event
+ */
+export declare function getHookCapableProviders(event: HookEvent): string[];
+/**
+ * Get hook events supported by all specified providers
+ *
+ * @param providerIds - Optional array of provider IDs (uses all active providers if omitted)
+ * @returns Array of hook events supported by all specified providers
+ */
+export declare function getSharedHookEvents(providerIds?: string[]): CAAMPHookEvent[];
+export type { CAAMPHookEvent as ProviderHookEvent, HookEvent };
+export { getCommonHookEvents, getProvidersByHookEvent };
+//# sourceMappingURL=provider-hooks.d.ts.map

package/dist/hooks/provider-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-hooks.d.ts","sourceRoot":"","sources":["../../src/hooks/provider-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,SAAS,IAAI,cAAc,EAChC,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,YAAY,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAMlE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAE5E;AAED,YAAY,EAAE,cAAc,IAAI,iBAAiB,EAAE,SAAS,EAAE,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,CAAC"}

package/dist/hooks/registry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Hook Registry System - Phase 2C of T5237
+ *
+ * Central registry for managing hook handlers with priority-based execution,
+ * async dispatch, and best-effort error handling. Integrates with CAAMP 1.6.0
+ * event definitions while providing CLEO's execution engine.
+ *
+ * @module @cleocode/cleo/hooks/registry
+ */
+import type { HookConfig, HookEvent, HookPayload, HookRegistration } from './types.js';
+/**
+ * Central registry for hook handlers.
+ *
+ * Manages registration, priority-based ordering, and async dispatch
+ * of hook handlers. Provides best-effort execution where errors in
+ * one handler do not block others.
+ */
+export declare class HookRegistry {
+    private handlers;
+    private config;
+    /**
+     * Register a hook handler for a specific event.
+     *
+     * Handlers are sorted by priority (highest first) and executed
+     * in parallel when the event is dispatched.
+     *
+     * @param registration - The hook registration containing event, handler, priority, and ID
+     * @returns A function to unregister the handler
+     *
+     * @example
+     * ```typescript
+     * const unregister = hooks.register({
+     *   id: 'my-handler',
+     *   event: 'onSessionStart',
+     *   handler: async (root, payload) => { console.log('Session started'); },
+     *   priority: 100
+     * });
+     *
+     * // Later: unregister()
+     * ```
+     */
+    register<T extends HookPayload>(registration: HookRegistration<T>): () => void;
+    /**
+     * Dispatch an event to all registered handlers.
+     *
+     * Executes handlers in parallel using Promise.allSettled for best-effort
+     * execution. Errors in individual handlers are logged but do not block
+     * other handlers or propagate to the caller.
+     *
+     * @param event - The CAAMP hook event to dispatch
+     * @param projectRoot - The project root directory path
+     * @param payload - The event payload (typed by event)
+     * @returns Promise that resolves when all handlers have completed
+     *
+     * @example
+     * ```typescript
+     * await hooks.dispatch('onSessionStart', '/project', {
+     *   timestamp: new Date().toISOString(),
+     *   sessionId: 'sess-123',
+     *   name: 'My Session',
+     *   scope: 'feature'
+     * });
+     * ```
+     */
+    dispatch<T extends HookPayload>(event: HookEvent, projectRoot: string, payload: T): Promise<void>;
+    /**
+     * Check if a specific event is currently enabled.
+     *
+     * Both the global enabled flag and the per-event flag must be true.
+     *
+     * @param event - The CAAMP hook event to check
+     * @returns True if the event is enabled
+     */
+    isEnabled(event: HookEvent): boolean;
+    /**
+     * Update the hook system configuration.
+     *
+     * Merges the provided config with the existing config.
+     *
+     * @param config - Partial configuration to apply
+     *
+     * @example
+     * ```typescript
+     * hooks.setConfig({ enabled: false }); // Disable all hooks
+     * hooks.setConfig({ events: { onError: false } }); // Disable specific event
+     * ```
+     */
+    setConfig(config: Partial<HookConfig>): void;
+    /**
+     * Get the current hook configuration.
+     *
+     * @returns A copy of the current configuration
+     */
+    getConfig(): HookConfig;
+    /**
+     * List all registered handlers for a specific event.
+     *
+     * Returns handlers in priority order (highest first).
+     *
+     * @param event - The CAAMP hook event
+     * @returns Array of hook registrations
+     */
+    listHandlers(event: HookEvent): HookRegistration[];
+}
+/**
+ * Singleton instance of the HookRegistry.
+ *
+ * Use this instance for all hook operations throughout the application.
+ */
+export declare const hooks: HookRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/hooks/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/hooks/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAyBvF;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,MAAM,CAAmC;IAEjD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,CAAC,SAAS,WAAW,EAAE,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAiB9E;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,QAAQ,CAAC,CAAC,SAAS,WAAW,EAClC,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,IAAI,CAAC;IAuBhB;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAIpC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAI5C;;;;OAIG;IACH,SAAS,IAAI,UAAU;IAIvB;;;;;;;OAOG;IACH,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,gBAAgB,EAAE;CAGnD;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,cAAqB,CAAC"}

package/dist/hooks/types.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Universal Hooks Core Types - Phase 2B of T5237
+ *
+ * This module defines the core type system for CLEO's Universal Hooks
+ * integration with CAAMP 1.6.0. CLEO builds the hook registry and
+ * execution system while CAAMP provides the event definitions.
+ *
+ * @module @cleocode/cleo/hooks/types
+ */
+import type { HookEvent as CAAMPHookEvent } from '@cleocode/caamp';
+export { getCommonHookEvents, getProvidersByHookEvent } from '@cleocode/caamp';
+/**
+ * CAAMP-defined hook events supported by provider capability discovery.
+ */
+export type ProviderHookEvent = CAAMPHookEvent;
+/**
+ * CLEO-local coordination events used by the autonomous runtime.
+ *
+ * These are internal lifecycle signals for worker orchestration and are not
+ * surfaced through CAAMP's provider capability registry.
+ */
+export declare const INTERNAL_HOOK_EVENTS: readonly ["onWorkAvailable", "onAgentSpawn", "onAgentComplete", "onCascadeStart", "onPatrol"];
+export type InternalHookEvent = (typeof INTERNAL_HOOK_EVENTS)[number];
+/**
+ * Full CLEO hook event union.
+ *
+ * CAAMP defines provider-facing events; CLEO extends the registry with local
+ * coordination events for autonomous execution.
+ */
+export type HookEvent = ProviderHookEvent | InternalHookEvent;
+/**
+ * Type guard for CAAMP/provider-discoverable hook events.
+ */
+export declare function isProviderHookEvent(event: HookEvent): event is ProviderHookEvent;
+/**
+ * Type guard for CLEO-local coordination hook events.
+ */
+export declare function isInternalHookEvent(event: HookEvent): event is InternalHookEvent;
+/**
+ * Base interface for all hook payloads
+ * Provides common fields available across all hook events
+ */
+export interface HookPayload {
+    /** ISO 8601 timestamp when the hook fired */
+    timestamp: string;
+    /** Optional session ID if firing within a session context */
+    sessionId?: string;
+    /** Optional task ID if firing within a task context */
+    taskId?: string;
+    /** Optional provider ID that triggered the hook */
+    providerId?: string;
+    /** Optional metadata for extensibility */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Payload for onSessionStart hook
+ * Fired when a CLEO session begins
+ */
+export interface OnSessionStartPayload extends HookPayload {
+    /** Session identifier (required for session events) */
+    sessionId: string;
+    /** Human-readable session name */
+    name: string;
+    /** Session scope/area of work */
+    scope: string;
+    /** Optional agent identifier */
+    agent?: string;
+}
+/**
+ * Payload for onSessionEnd hook
+ * Fired when a CLEO session ends
+ */
+export interface OnSessionEndPayload extends HookPayload {
+    /** Session identifier */
+    sessionId: string;
+    /** Session duration in seconds */
+    duration: number;
+    /** Array of task IDs completed during this session */
+    tasksCompleted: string[];
+}
+/**
+ * Payload for onToolStart hook
+ * Fired when a task/tool operation begins
+ */
+export interface OnToolStartPayload extends HookPayload {
+    /** Task identifier */
+    taskId: string;
+    /** Human-readable task title */
+    taskTitle: string;
+    /** Optional ID of the previous task if sequential */
+    previousTask?: string;
+}
+/**
+ * Payload for onToolComplete hook
+ * Fired when a task/tool operation completes
+ */
+export interface OnToolCompletePayload extends HookPayload {
+    /** Task identifier */
+    taskId: string;
+    /** Human-readable task title */
+    taskTitle: string;
+    /** Final status of the completed task */
+    status: 'done' | 'archived' | 'cancelled';
+}
+/**
+ * Handler function type for hook events
+ * Handlers receive project root and typed payload
+ */
+export type HookHandler<T extends HookPayload = HookPayload> = (projectRoot: string, payload: T) => Promise<void> | void;
+/**
+ * Hook registration metadata
+ * Tracks registered handlers with priority and event binding
+ */
+export interface HookRegistration<T extends HookPayload = HookPayload> {
+    /** Unique identifier for this registration */
+    id: string;
+    /** CAAMP hook event this handler listens for */
+    event: HookEvent;
+    /** Handler function to execute when event fires */
+    handler: HookHandler<T>;
+    /** Priority for execution order (higher = earlier) */
+    priority: number;
+}
+/**
+ * Configuration for the hook system
+ * Controls which events are enabled/disabled
+ */
+export interface HookConfig {
+    /** Master switch for hook system */
+    enabled: boolean;
+    /** Per-event enable/disable configuration */
+    events: Record<HookEvent, boolean>;
+}
+/**
+ * Payload for onFileChange hook
+ * Fired when a tracked file is written, created, or deleted
+ */
+export interface OnFileChangePayload extends HookPayload {
+    /** Absolute or project-relative path of the changed file */
+    filePath: string;
+    /** Kind of filesystem change */
+    changeType: 'write' | 'create' | 'delete';
+    /** File size in bytes after the change (absent for deletes) */
+    sizeBytes?: number;
+}
+/**
+ * Payload for onError hook
+ * Fired when an operation fails with a structured error
+ */
+export interface OnErrorPayload extends HookPayload {
+    /** Numeric exit code or string error code */
+    errorCode: number | string;
+    /** Human-readable error message */
+    message: string;
+    /** Domain where the error occurred */
+    domain?: string;
+    /** Operation that failed */
+    operation?: string;
+    /** Gateway (query / mutate) that received the error */
+    gateway?: string;
+    /** Optional stack trace */
+    stack?: string;
+}
+/**
+ * Payload for onPromptSubmit hook
+ * Fired when an agent submits a prompt through a gateway
+ */
+export interface OnPromptSubmitPayload extends HookPayload {
+    /** Gateway that received the prompt (query / mutate) */
+    gateway: string;
+    /** Target domain */
+    domain: string;
+    /** Target operation */
+    operation: string;
+    /** Optional source identifier (e.g. agent name) */
+    source?: string;
+}
+/**
+ * Payload for onResponseComplete hook
+ * Fired when a gateway operation finishes (success or failure)
+ */
+export interface OnResponseCompletePayload extends HookPayload {
+    /** Gateway that handled the operation */
+    gateway: string;
+    /** Target domain */
+    domain: string;
+    /** Target operation */
+    operation: string;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Wall-clock duration in milliseconds */
+    durationMs?: number;
+    /** Error code if the operation failed */
+    errorCode?: string;
+}
+/**
+ * Payload for onWorkAvailable hook
+ * Fired when the system detects ready work on a Loom/Tapestry
+ */
+export interface OnWorkAvailablePayload extends HookPayload {
+    /** IDs of tasks now ready for execution */
+    taskIds: string[];
+    /** Optional epic / Loom identifier */
+    epicId?: string;
+    /** Optional chain or tessera instance identifier */
+    chainId?: string;
+    /** Why the work became available */
+    reason?: 'dependency-cleared' | 'new-task' | 'retry' | 'manual' | 'patrol';
+}
+/**
+ * Payload for onAgentSpawn hook
+ * Fired when a worker session/process is launched
+ */
+export interface OnAgentSpawnPayload extends HookPayload {
+    /** Worker or session identifier */
+    agentId: string;
+    /** Worker role / archetype name */
+    role: string;
+    /** Provider or adapter used to launch the worker */
+    adapterId?: string;
+    /** Optional task assignment at spawn time */
+    taskId?: string;
+}
+/**
+ * Payload for onAgentComplete hook
+ * Fired when a worker finishes its assigned run
+ */
+export interface OnAgentCompletePayload extends HookPayload {
+    /** Worker or session identifier */
+    agentId: string;
+    /** Worker role / archetype name */
+    role: string;
+    /** Completion status for the run */
+    status: 'complete' | 'partial' | 'blocked' | 'failed';
+    /** Optional task assignment that was completed */
+    taskId?: string;
+    /** Optional summary or manifest reference */
+    summary?: string;
+}
+/**
+ * Payload for onCascadeStart hook
+ * Fired when autonomous execution begins flowing through a chain or wave
+ */
+export interface OnCascadeStartPayload extends HookPayload {
+    /** Identifier for the cascade / execution wave */
+    cascadeId: string;
+    /** Optional chain identifier */
+    chainId?: string;
+    /** Optional tessera template / instance identifier */
+    tesseraId?: string;
+    /** Task IDs participating in the cascade */
+    taskIds?: string[];
+}
+/**
+ * Payload for onPatrol hook
+ * Fired when a watcher performs a periodic health/sweep cycle
+ */
+export interface OnPatrolPayload extends HookPayload {
+    /** Watcher / patrol identifier */
+    watcherId: string;
+    /** Patrol category */
+    patrolType: 'health' | 'sweep' | 'refinery' | 'watcher' | 'custom';
+    /** Optional scope being patrolled */
+    scope?: string;
+}
+/**
+ * Mapping from CLEO internal lifecycle events to CAAMP hook events
+ * This is where CLEO connects its lifecycle to CAAMP's event definitions
+ */
+export declare const CLEO_TO_CAAMP_HOOK_MAP: {
+    readonly 'session.start': "onSessionStart";
+    readonly 'session.end': "onSessionEnd";
+    readonly 'task.start': "onToolStart";
+    readonly 'task.complete': "onToolComplete";
+    readonly 'file.change': "onFileChange";
+    readonly 'system.error': "onError";
+    readonly 'prompt.submit': "onPromptSubmit";
+    readonly 'response.complete': "onResponseComplete";
+};
+/**
+ * Internal CLEO lifecycle events that drive autonomous coordination.
+ */
+export declare const CLEO_INTERNAL_HOOK_MAP: {
+    readonly 'agent.work.available': "onWorkAvailable";
+    readonly 'agent.spawn': "onAgentSpawn";
+    readonly 'agent.complete': "onAgentComplete";
+    readonly 'cascade.start': "onCascadeStart";
+    readonly 'watcher.patrol': "onPatrol";
+};
+/**
+ * Type for CLEO lifecycle event names
+ * These are the internal events CLEO fires that get mapped to CAAMP events
+ */
+export type CLEOLifecycleEvent = keyof typeof CLEO_TO_CAAMP_HOOK_MAP;
+/**
+ * Type for autonomous CLEO lifecycle events.
+ */
+export type CLEOAutonomousLifecycleEvent = keyof typeof CLEO_INTERNAL_HOOK_MAP;
+//# sourceMappingURL=types.d.ts.map

package/dist/hooks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/hooks/types.ts"],"names":[],"mappings":"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"}

package/dist/hooks.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Git hook management utilities.
+ *
+ * Extracted from init.ts to enable shared use across init, upgrade, and
+ * doctor/health-check workflows.
+ *
+ * Handles installation, update, and verification of managed git hooks
+ * from the package's templates/git-hooks/ directory.
+ */
+export interface ScaffoldResult {
+    action: 'created' | 'repaired' | 'skipped';
+    path: string;
+    details?: string;
+}
+export interface HookCheckResult {
+    hook: string;
+    installed: boolean;
+    current: boolean;
+    sourcePath: string;
+    installedPath: string;
+}
+export interface EnsureGitHooksOptions {
+    force?: boolean;
+}
+/** Git hooks managed by CLEO. */
+export declare const MANAGED_HOOKS: readonly ["commit-msg", "pre-commit", "pre-push"];
+export type ManagedHook = (typeof MANAGED_HOOKS)[number];
+/**
+ * Install or update managed git hooks from templates/git-hooks/ into .git/hooks/.
+ *
+ * Handles:
+ * - No .git directory (skips gracefully)
+ * - No source templates directory (skips gracefully)
+ * - Hooks already installed (skips unless force)
+ * - Sets executable permissions on installed hooks
+ */
+export declare function ensureGitHooks(projectRoot: string, opts?: EnsureGitHooksOptions): Promise<ScaffoldResult>;
+/**
+ * Verify managed hooks are installed and current.
+ *
+ * Compares installed hooks in .git/hooks/ against source templates in the
+ * package's templates/git-hooks/ directory. Returns per-hook status including
+ * whether the hook is installed and whether its content matches the source.
+ */
+export declare function checkGitHooks(projectRoot: string): Promise<HookCheckResult[]>;
+//# sourceMappingURL=hooks.d.ts.map