@cleocode/core 2026.3.71 → 2026.3.73

package/src/hooks/handlers/work-capture-hooks.ts

@@ -17,7 +17,7 @@
  */
 
 import { hooks } from '../registry.js';
-import type { OnPromptSubmitPayload, OnResponseCompletePayload } from '../types.js';
+import type { PromptSubmitPayload, ResponseCompletePayload } from '../types.js';
 
 // ---------------------------------------------------------------------------
 // Shared helpers
@@ -60,9 +60,9 @@ async function isWorkCaptureEnabled(projectRoot: string): Promise<boolean> {
  * Mutations that represent novel work not already captured by lifecycle hooks.
  *
  * Excluded (already captured elsewhere):
- *   - tasks.complete  → task-hooks.ts (onToolComplete)
- *   - session.start   → session-hooks.ts (onSessionStart)
- *   - session.end     → session-hooks.ts (onSessionEnd)
+ *   - tasks.complete  → task-hooks.ts (PostToolUse)
+ *   - session.start   → session-hooks.ts (SessionStart)
+ *   - session.end     → session-hooks.ts (SessionEnd)
  *   - memory.brain.observe → observeBrain itself writes to brain; self-loop
  *
  * All query gateway operations are excluded by the gateway check before
@@ -100,17 +100,17 @@ function shouldCapture(gateway: string, domain: string, operation: string): bool
 // ---------------------------------------------------------------------------
 
 /**
- * Handle onPromptSubmit — log incoming mutation intents to BRAIN.
+ * Handle PromptSubmit — log incoming mutation intents to BRAIN.
  *
  * Only fires for mutate operations in CAPTURE_OPERATIONS.
  * Gated behind brain.captureWork config (or CLEO_BRAIN_CAPTURE_WORK env).
  *
  * @param projectRoot - Absolute path to the project root
- * @param payload     - onPromptSubmit event payload
+ * @param payload     - PromptSubmit event payload
  */
 export async function handleWorkPromptSubmit(
   projectRoot: string,
-  payload: OnPromptSubmitPayload,
+  payload: PromptSubmitPayload,
 ): Promise<void> {
   if (!shouldCapture(payload.gateway, payload.domain, payload.operation)) return;
   if (!(await isWorkCaptureEnabled(projectRoot))) return;
@@ -130,18 +130,18 @@ export async function handleWorkPromptSubmit(
 }
 
 /**
- * Handle onResponseComplete — capture completed mutations to BRAIN.
+ * Handle ResponseComplete — capture completed mutations to BRAIN.
  *
  * Only fires for successful mutate operations in CAPTURE_OPERATIONS.
  * Failures are skipped — the intent was already captured by handleWorkPromptSubmit.
  * Gated behind brain.captureWork config (or CLEO_BRAIN_CAPTURE_WORK env).
  *
  * @param projectRoot - Absolute path to the project root
- * @param payload     - onResponseComplete event payload
+ * @param payload     - ResponseComplete event payload
  */
 export async function handleWorkResponseComplete(
   projectRoot: string,
-  payload: OnResponseCompletePayload,
+  payload: ResponseCompletePayload,
 ): Promise<void> {
   if (!shouldCapture(payload.gateway, payload.domain, payload.operation)) return;
   // Only capture successful completions — failures are noise
@@ -171,14 +171,14 @@ export async function handleWorkResponseComplete(
 // handlers always run first.
 hooks.register({
   id: 'work-capture-prompt-submit',
-  event: 'onPromptSubmit',
+  event: 'PromptSubmit',
   handler: handleWorkPromptSubmit,
   priority: 90,
 });
 
 hooks.register({
   id: 'work-capture-response-complete',
-  event: 'onResponseComplete',
+  event: 'ResponseComplete',
   handler: handleWorkResponseComplete,
   priority: 90,
 });

package/src/hooks/payload-schemas.ts

@@ -28,44 +28,63 @@ export const HookPayloadSchema = z.object({
 // CAAMP-mapped Event Payload Schemas
 // ============================================================================
 
-/** Zod schema for {@link OnSessionStartPayload}. */
-export const OnSessionStartPayloadSchema = HookPayloadSchema.extend({
+/** Zod schema for {@link SessionStartPayload}. */
+export const SessionStartPayloadSchema = HookPayloadSchema.extend({
   sessionId: z.string(),
   name: z.string(),
   scope: z.string(),
   agent: z.string().optional(),
 });
 
-/** Zod schema for {@link OnSessionEndPayload}. */
-export const OnSessionEndPayloadSchema = HookPayloadSchema.extend({
+/** @deprecated Use {@link SessionStartPayloadSchema}. Kept for backward compatibility. */
+export const OnSessionStartPayloadSchema = SessionStartPayloadSchema;
+
+/** Zod schema for {@link SessionEndPayload}. */
+export const SessionEndPayloadSchema = HookPayloadSchema.extend({
   sessionId: z.string(),
   duration: z.number(),
   tasksCompleted: z.array(z.string()),
 });
 
-/** Zod schema for {@link OnToolStartPayload}. */
-export const OnToolStartPayloadSchema = HookPayloadSchema.extend({
+/** @deprecated Use {@link SessionEndPayloadSchema}. Kept for backward compatibility. */
+export const OnSessionEndPayloadSchema = SessionEndPayloadSchema;
+
+/** Zod schema for {@link PreToolUsePayload}. */
+export const PreToolUsePayloadSchema = HookPayloadSchema.extend({
   taskId: z.string(),
   taskTitle: z.string(),
   previousTask: z.string().optional(),
+  toolName: z.string().optional(),
+  toolInput: z.record(z.string(), z.unknown()).optional(),
 });
 
-/** Zod schema for {@link OnToolCompletePayload}. */
-export const OnToolCompletePayloadSchema = HookPayloadSchema.extend({
+/** @deprecated Use {@link PreToolUsePayloadSchema}. Kept for backward compatibility. */
+export const OnToolStartPayloadSchema = PreToolUsePayloadSchema;
+
+/** Zod schema for {@link PostToolUsePayload}. */
+export const PostToolUsePayloadSchema = HookPayloadSchema.extend({
   taskId: z.string(),
   taskTitle: z.string(),
   status: z.enum(['done', 'archived', 'cancelled']),
+  toolResult: z.record(z.string(), z.unknown()).optional(),
 });
 
-/** Zod schema for {@link OnFileChangePayload}. */
-export const OnFileChangePayloadSchema = HookPayloadSchema.extend({
-  filePath: z.string(),
-  changeType: z.enum(['write', 'create', 'delete']),
+/** @deprecated Use {@link PostToolUsePayloadSchema}. Kept for backward compatibility. */
+export const OnToolCompletePayloadSchema = PostToolUsePayloadSchema;
+
+/** Zod schema for {@link NotificationPayload}. */
+export const NotificationPayloadSchema = HookPayloadSchema.extend({
+  filePath: z.string().optional(),
+  changeType: z.enum(['write', 'create', 'delete']).optional(),
   sizeBytes: z.number().optional(),
+  message: z.string().optional(),
 });
 
-/** Zod schema for {@link OnErrorPayload}. */
-export const OnErrorPayloadSchema = HookPayloadSchema.extend({
+/** @deprecated Use {@link NotificationPayloadSchema}. Kept for backward compatibility. */
+export const OnFileChangePayloadSchema = NotificationPayloadSchema;
+
+/** Zod schema for {@link PostToolUseFailurePayload}. */
+export const PostToolUseFailurePayloadSchema = HookPayloadSchema.extend({
   errorCode: z.union([z.number(), z.string()]),
   message: z.string(),
   domain: z.string().optional(),
@@ -74,16 +93,22 @@ export const OnErrorPayloadSchema = HookPayloadSchema.extend({
   stack: z.string().optional(),
 });
 
-/** Zod schema for {@link OnPromptSubmitPayload}. */
-export const OnPromptSubmitPayloadSchema = HookPayloadSchema.extend({
+/** @deprecated Use {@link PostToolUseFailurePayloadSchema}. Kept for backward compatibility. */
+export const OnErrorPayloadSchema = PostToolUseFailurePayloadSchema;
+
+/** Zod schema for {@link PromptSubmitPayload}. */
+export const PromptSubmitPayloadSchema = HookPayloadSchema.extend({
   gateway: z.string(),
   domain: z.string(),
   operation: z.string(),
   source: z.string().optional(),
 });
 
-/** Zod schema for {@link OnResponseCompletePayload}. */
-export const OnResponseCompletePayloadSchema = HookPayloadSchema.extend({
+/** @deprecated Use {@link PromptSubmitPayloadSchema}. Kept for backward compatibility. */
+export const OnPromptSubmitPayloadSchema = PromptSubmitPayloadSchema;
+
+/** Zod schema for {@link ResponseCompletePayload}. */
+export const ResponseCompletePayloadSchema = HookPayloadSchema.extend({
   gateway: z.string(),
   domain: z.string(),
   operation: z.string(),
@@ -92,6 +117,44 @@ export const OnResponseCompletePayloadSchema = HookPayloadSchema.extend({
   errorCode: z.string().optional(),
 });
 
+/** @deprecated Use {@link ResponseCompletePayloadSchema}. Kept for backward compatibility. */
+export const OnResponseCompletePayloadSchema = ResponseCompletePayloadSchema;
+
+/** Zod schema for {@link SubagentStartPayload}. */
+export const SubagentStartPayloadSchema = HookPayloadSchema.extend({
+  agentId: z.string(),
+  role: z.string().optional(),
+  taskId: z.string().optional(),
+});
+
+/** Zod schema for {@link SubagentStopPayload}. */
+export const SubagentStopPayloadSchema = HookPayloadSchema.extend({
+  agentId: z.string(),
+  status: z.enum(['complete', 'partial', 'blocked', 'failed']).optional(),
+  taskId: z.string().optional(),
+  summary: z.string().optional(),
+});
+
+/** Zod schema for {@link PreCompactPayload}. */
+export const PreCompactPayloadSchema = HookPayloadSchema.extend({
+  tokensBefore: z.number().optional(),
+  reason: z.string().optional(),
+});
+
+/** Zod schema for {@link PostCompactPayload}. */
+export const PostCompactPayloadSchema = HookPayloadSchema.extend({
+  tokensBefore: z.number().optional(),
+  tokensAfter: z.number().optional(),
+  success: z.boolean(),
+});
+
+/** Zod schema for {@link ConfigChangePayload}. */
+export const ConfigChangePayloadSchema = HookPayloadSchema.extend({
+  key: z.string(),
+  previousValue: z.unknown().optional(),
+  newValue: z.unknown().optional(),
+});
+
 // ============================================================================
 // CLEO Internal Event Payload Schemas
 // ============================================================================
@@ -147,14 +210,21 @@ export const OnPatrolPayloadSchema = HookPayloadSchema.extend({
  * this map fall back to the base {@link HookPayloadSchema}.
  */
 const EVENT_SCHEMA_MAP: Partial<Record<HookEvent, z.ZodType>> = {
-  onSessionStart: OnSessionStartPayloadSchema,
-  onSessionEnd: OnSessionEndPayloadSchema,
-  onToolStart: OnToolStartPayloadSchema,
-  onToolComplete: OnToolCompletePayloadSchema,
-  onFileChange: OnFileChangePayloadSchema,
-  onError: OnErrorPayloadSchema,
-  onPromptSubmit: OnPromptSubmitPayloadSchema,
-  onResponseComplete: OnResponseCompletePayloadSchema,
+  // CAAMP canonical events (16)
+  SessionStart: SessionStartPayloadSchema,
+  SessionEnd: SessionEndPayloadSchema,
+  PreToolUse: PreToolUsePayloadSchema,
+  PostToolUse: PostToolUsePayloadSchema,
+  Notification: NotificationPayloadSchema,
+  PostToolUseFailure: PostToolUseFailurePayloadSchema,
+  PromptSubmit: PromptSubmitPayloadSchema,
+  ResponseComplete: ResponseCompletePayloadSchema,
+  SubagentStart: SubagentStartPayloadSchema,
+  SubagentStop: SubagentStopPayloadSchema,
+  PreCompact: PreCompactPayloadSchema,
+  PostCompact: PostCompactPayloadSchema,
+  ConfigChange: ConfigChangePayloadSchema,
+  // CLEO internal coordination events (5)
   onWorkAvailable: OnWorkAvailablePayloadSchema,
   onAgentSpawn: OnAgentSpawnPayloadSchema,
   onAgentComplete: OnAgentCompletePayloadSchema,

package/src/hooks/provider-hooks.ts

@@ -2,29 +2,34 @@
  * 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.
+ * Wraps CAAMP's provider discovery and normalizer functions with CLEO-specific helpers.
+ *
+ * Updated for CAAMP 1.9.1: uses CanonicalHookEvent and toNative/toCanonical normalizers.
  *
  * @module @cleocode/cleo/hooks/provider-hooks
  */
 
 import {
-  type HookEvent as CAAMPHookEvent,
+  type CanonicalHookEvent,
   getCommonHookEvents,
   getProvidersByHookEvent,
+  supportsHook,
+  toCanonical,
+  toNative,
 } from '@cleocode/caamp';
 import { type HookEvent, isProviderHookEvent } from './types.js';
 
 /**
  * Get all providers that support a specific hook event
  *
- * @param event - The hook event to query
+ * @param event - The hook event to query (canonical or internal)
  * @returns Array of provider IDs that support this event
  */
 export function getHookCapableProviders(event: HookEvent): string[] {
   if (!isProviderHookEvent(event)) {
     return [];
   }
-  const providers = getProvidersByHookEvent(event);
+  const providers = getProvidersByHookEvent(event as CanonicalHookEvent);
   return providers.map((p) => p.id);
 }
 
@@ -32,11 +37,47 @@ export 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
+ * @returns Array of canonical hook events supported by all specified providers
+ */
+export function getSharedHookEvents(providerIds?: string[]): CanonicalHookEvent[] {
+  return getCommonHookEvents(providerIds) as CanonicalHookEvent[];
+}
+
+/**
+ * Translate a canonical hook event to a provider-native event name.
+ *
+ * @param event - The canonical CAAMP event name
+ * @param providerId - The provider to translate for
+ * @returns The native event name, or null if the provider doesn't support it
+ */
+export function toNativeHookEvent(event: CanonicalHookEvent, providerId: string): string | null {
+  return toNative(event, providerId);
+}
+
+/**
+ * Translate a provider-native event name back to its canonical equivalent.
+ *
+ * @param nativeEvent - The provider-specific event name
+ * @param providerId - The provider this event belongs to
+ * @returns The canonical event name, or null if no mapping exists
+ */
+export function toCanonicalHookEvent(
+  nativeEvent: string,
+  providerId: string,
+): CanonicalHookEvent | null {
+  return toCanonical(nativeEvent, providerId);
+}
+
+/**
+ * Check if a provider supports a specific canonical hook event.
+ *
+ * @param event - The canonical event name
+ * @param providerId - The provider to check
+ * @returns True if the provider supports this event
  */
-export function getSharedHookEvents(providerIds?: string[]): CAAMPHookEvent[] {
-  return getCommonHookEvents(providerIds);
+export function providerSupportsHookEvent(event: CanonicalHookEvent, providerId: string): boolean {
+  return supportsHook(event, providerId);
 }
 
-export type { CAAMPHookEvent as ProviderHookEvent, HookEvent };
-export { getCommonHookEvents, getProvidersByHookEvent };
+export type { CanonicalHookEvent as ProviderHookEvent, HookEvent };
+export { getCommonHookEvents, getProvidersByHookEvent, supportsHook, toCanonical, toNative };

package/src/hooks/registry.ts

@@ -2,8 +2,8 @@
  * 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.
+ * async dispatch, and best-effort error handling. Integrates with CAAMP 1.9.1
+ * canonical event definitions while providing CLEO's execution engine.
  *
  * @module @cleocode/cleo/hooks/registry
  */
@@ -11,6 +11,18 @@
 import { getLogger } from '../logger.js';
 import type { HookConfig, HookEvent, HookPayload, HookRegistration } from './types.js';
 
+/** Map from old `on`-prefix event names to new canonical names. Used for backward compat. */
+const LEGACY_EVENT_MAP: Record<string, HookEvent> = {
+  onSessionStart: 'SessionStart',
+  onSessionEnd: 'SessionEnd',
+  onToolStart: 'PreToolUse',
+  onToolComplete: 'PostToolUse',
+  onFileChange: 'Notification',
+  onError: 'PostToolUseFailure',
+  onPromptSubmit: 'PromptSubmit',
+  onResponseComplete: 'ResponseComplete',
+};
+
 /**
  * Default configuration for the hook system.
  * All events are enabled by default.
@@ -18,14 +30,24 @@ import type { HookConfig, HookEvent, HookPayload, HookRegistration } from './typ
 const DEFAULT_HOOK_CONFIG: HookConfig = {
   enabled: true,
   events: {
-    onSessionStart: true,
-    onSessionEnd: true,
-    onToolStart: true,
-    onToolComplete: true,
-    onFileChange: true,
-    onError: true,
-    onPromptSubmit: true,
-    onResponseComplete: true,
+    // CAAMP canonical events (16)
+    SessionStart: true,
+    SessionEnd: true,
+    PromptSubmit: true,
+    ResponseComplete: true,
+    PreToolUse: true,
+    PostToolUse: true,
+    PostToolUseFailure: true,
+    PermissionRequest: true,
+    SubagentStart: true,
+    SubagentStop: true,
+    PreModel: true,
+    PostModel: true,
+    PreCompact: true,
+    PostCompact: true,
+    Notification: true,
+    ConfigChange: true,
+    // CLEO internal coordination events (5)
     onWorkAvailable: true,
     onAgentSpawn: true,
     onAgentComplete: true,
@@ -40,17 +62,43 @@ const DEFAULT_HOOK_CONFIG: HookConfig = {
  * Manages registration, priority-based ordering, and async dispatch
  * of hook handlers. Provides best-effort execution where errors in
  * one handler do not block others.
+ *
+ * Backward compatibility: handlers registered with legacy `on`-prefix
+ * event names (e.g. `onSessionStart`) are automatically remapped to their
+ * canonical equivalents (e.g. `SessionStart`) with a deprecation warning.
  */
 export class HookRegistry {
   private handlers: Map<HookEvent, HookRegistration[]> = new Map();
   private config: HookConfig = DEFAULT_HOOK_CONFIG;
 
+  /**
+   * Resolve a potentially-legacy event name to its canonical equivalent.
+   *
+   * If the event name matches a known legacy `on`-prefix name, it is
+   * remapped and a deprecation warning is logged. Unknown names pass through
+   * unchanged so callers using the new canonical names are unaffected.
+   */
+  private resolveEvent(event: string): HookEvent {
+    const canonical = LEGACY_EVENT_MAP[event];
+    if (canonical) {
+      getLogger('hooks').warn(
+        { legacyEvent: event, canonicalEvent: canonical },
+        `[DEPRECATED] Hook event '${event}' has been renamed to '${canonical}'. Update your handler registration.`,
+      );
+      return canonical;
+    }
+    return event as HookEvent;
+  }
+
   /**
    * Register a hook handler for a specific event.
    *
    * Handlers are sorted by priority (highest first) and executed
    * in parallel when the event is dispatched.
    *
+   * Backward compatibility: legacy `on`-prefix event names are automatically
+   * remapped to their canonical equivalents.
+   *
    * @param registration - The hook registration containing event, handler, priority, and ID
    * @returns A function to unregister the handler
    *
@@ -58,7 +106,7 @@ export class HookRegistry {
    * ```typescript
    * const unregister = hooks.register({
    *   id: 'my-handler',
-   *   event: 'onSessionStart',
+   *   event: 'SessionStart',
    *   handler: async (root, payload) => { console.log('Session started'); },
    *   priority: 100
    * });
@@ -67,15 +115,18 @@ export class HookRegistry {
    * ```
    */
   register<T extends HookPayload>(registration: HookRegistration<T>): () => void {
-    const list = this.handlers.get(registration.event) || [];
-    list.push(registration as HookRegistration);
+    const resolvedEvent = this.resolveEvent(registration.event as string);
+    const resolvedRegistration = { ...registration, event: resolvedEvent } as HookRegistration;
+
+    const list = this.handlers.get(resolvedEvent) || [];
+    list.push(resolvedRegistration);
     // Sort by priority (highest first)
     list.sort((a, b) => b.priority - a.priority);
-    this.handlers.set(registration.event, list);
+    this.handlers.set(resolvedEvent, list);
 
     // Return unregister function
     return () => {
-      const handlers = this.handlers.get(registration.event);
+      const handlers = this.handlers.get(resolvedEvent);
       if (handlers) {
         const idx = handlers.findIndex((h) => h.id === registration.id);
         if (idx !== -1) handlers.splice(idx, 1);
@@ -90,14 +141,17 @@ export class HookRegistry {
    * 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
+   * Backward compatibility: legacy `on`-prefix event names are automatically
+   * remapped to their canonical equivalents.
+   *
+   * @param event - The CAAMP canonical 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', {
+   * await hooks.dispatch('SessionStart', '/project', {
    *   timestamp: new Date().toISOString(),
    *   sessionId: 'sess-123',
    *   name: 'My Session',
@@ -113,10 +167,12 @@ export class HookRegistry {
     // Check if hooks enabled globally
     if (!this.config.enabled) return;
 
+    const resolvedEvent = this.resolveEvent(event as string);
+
     // Check if this event enabled
-    if (!this.config.events[event]) return;
+    if (!this.config.events[resolvedEvent]) return;
 
-    const handlers = this.handlers.get(event);
+    const handlers = this.handlers.get(resolvedEvent);
     if (!handlers || handlers.length === 0) return;
 
     // Execute all handlers in parallel (best-effort)
@@ -126,7 +182,10 @@ export class HookRegistry {
           await reg.handler(projectRoot, payload);
         } catch (error) {
           // Hooks are best-effort - log but don't throw
-          getLogger('hooks').warn({ err: error, hookId: reg.id, event }, 'Hook handler failed');
+          getLogger('hooks').warn(
+            { err: error, hookId: reg.id, event: resolvedEvent },
+            'Hook handler failed',
+          );
         }
       }),
     );
@@ -136,12 +195,14 @@ export class HookRegistry {
    * Check if a specific event is currently enabled.
    *
    * Both the global enabled flag and the per-event flag must be true.
+   * Automatically resolves legacy `on`-prefix event names.
    *
    * @param event - The CAAMP hook event to check
    * @returns True if the event is enabled
    */
   isEnabled(event: HookEvent): boolean {
-    return this.config.enabled && this.config.events[event];
+    const resolvedEvent = this.resolveEvent(event as string);
+    return this.config.enabled && this.config.events[resolvedEvent];
   }
 
   /**
@@ -154,7 +215,7 @@ export class HookRegistry {
    * @example
    * ```typescript
    * hooks.setConfig({ enabled: false }); // Disable all hooks
-   * hooks.setConfig({ events: { onError: false } }); // Disable specific event
+   * hooks.setConfig({ events: { PostToolUseFailure: false } }); // Disable specific event
    * ```
    */
   setConfig(config: Partial<HookConfig>): void {
@@ -174,12 +235,14 @@ export class HookRegistry {
    * List all registered handlers for a specific event.
    *
    * Returns handlers in priority order (highest first).
+   * Automatically resolves legacy `on`-prefix event names.
    *
    * @param event - The CAAMP hook event
    * @returns Array of hook registrations
    */
   listHandlers(event: HookEvent): HookRegistration[] {
-    return [...(this.handlers.get(event) || [])];
+    const resolvedEvent = this.resolveEvent(event as string);
+    return [...(this.handlers.get(resolvedEvent) || [])];
   }
 }