@cleocode/cleo 2026.3.71 → 2026.3.73

package/dist/cli/index.js

@@ -733,22 +733,42 @@ __export(registry_exports, {
   HookRegistry: () => HookRegistry,
   hooks: () => hooks
 });
-var DEFAULT_HOOK_CONFIG, HookRegistry, hooks;
+var LEGACY_EVENT_MAP, DEFAULT_HOOK_CONFIG, HookRegistry, hooks;
 var init_registry = __esm({
   "packages/core/src/hooks/registry.ts"() {
     "use strict";
     init_logger();
+    LEGACY_EVENT_MAP = {
+      onSessionStart: "SessionStart",
+      onSessionEnd: "SessionEnd",
+      onToolStart: "PreToolUse",
+      onToolComplete: "PostToolUse",
+      onFileChange: "Notification",
+      onError: "PostToolUseFailure",
+      onPromptSubmit: "PromptSubmit",
+      onResponseComplete: "ResponseComplete"
+    };
     DEFAULT_HOOK_CONFIG = {
       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,
@@ -759,12 +779,33 @@ var init_registry = __esm({
     HookRegistry = class {
       handlers = /* @__PURE__ */ new Map();
       config = 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.
+       */
+      resolveEvent(event) {
+        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;
+      }
       /**
        * 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
        *
@@ -772,7 +813,7 @@ var init_registry = __esm({
        * ```typescript
        * const unregister = hooks.register({
        *   id: 'my-handler',
-       *   event: 'onSessionStart',
+       *   event: 'SessionStart',
        *   handler: async (root, payload) => { console.log('Session started'); },
        *   priority: 100
        * });
@@ -781,12 +822,14 @@ var init_registry = __esm({
        * ```
        */
       register(registration) {
-        const list = this.handlers.get(registration.event) || [];
-        list.push(registration);
+        const resolvedEvent = this.resolveEvent(registration.event);
+        const resolvedRegistration = { ...registration, event: resolvedEvent };
+        const list = this.handlers.get(resolvedEvent) || [];
+        list.push(resolvedRegistration);
         list.sort((a, b) => b.priority - a.priority);
-        this.handlers.set(registration.event, list);
+        this.handlers.set(resolvedEvent, list);
         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);
@@ -800,14 +843,17 @@ var init_registry = __esm({
        * 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',
@@ -817,15 +863,19 @@ var init_registry = __esm({
        */
       async dispatch(event, projectRoot, payload) {
         if (!this.config.enabled) return;
-        if (!this.config.events[event]) return;
-        const handlers = this.handlers.get(event);
+        const resolvedEvent = this.resolveEvent(event);
+        if (!this.config.events[resolvedEvent]) return;
+        const handlers = this.handlers.get(resolvedEvent);
         if (!handlers || handlers.length === 0) return;
         await Promise.allSettled(
           handlers.map(async (reg) => {
             try {
               await reg.handler(projectRoot, payload);
             } catch (error40) {
-              getLogger("hooks").warn({ err: error40, hookId: reg.id, event }, "Hook handler failed");
+              getLogger("hooks").warn(
+                { err: error40, hookId: reg.id, event: resolvedEvent },
+                "Hook handler failed"
+              );
             }
           })
         );
@@ -834,12 +884,14 @@ var init_registry = __esm({
        * 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) {
-        return this.config.enabled && this.config.events[event];
+        const resolvedEvent = this.resolveEvent(event);
+        return this.config.enabled && this.config.events[resolvedEvent];
       }
       /**
        * Update the hook system configuration.
@@ -851,7 +903,7 @@ var init_registry = __esm({
        * @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(config2) {
@@ -869,12 +921,14 @@ var init_registry = __esm({
        * 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) {
-        return [...this.handlers.get(event) || []];
+        const resolvedEvent = this.resolveEvent(event);
+        return [...this.handlers.get(resolvedEvent) || []];
       }
     };
     hooks = new HookRegistry();
@@ -13695,7 +13749,7 @@ async function saveJson(filePath, data, options) {
     }
     await atomicWriteJson(filePath, data, { indent: options?.indent });
     Promise.resolve().then(() => (init_registry(), registry_exports)).then(
-      ({ hooks: h }) => h.dispatch("onFileChange", process.cwd(), {
+      ({ hooks: h }) => h.dispatch("Notification", process.cwd(), {
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         filePath,
         changeType: "write"
@@ -20929,13 +20983,13 @@ var init_session_hooks = __esm({
     init_memory_bridge_refresh();
     hooks.register({
       id: "brain-session-start",
-      event: "onSessionStart",
+      event: "SessionStart",
       handler: handleSessionStart,
       priority: 100
     });
     hooks.register({
       id: "brain-session-end",
-      event: "onSessionEnd",
+      event: "SessionEnd",
       handler: handleSessionEnd,
       priority: 100
     });
@@ -20982,13 +21036,13 @@ var init_task_hooks = __esm({
     init_memory_bridge_refresh();
     hooks.register({
       id: "brain-tool-start",
-      event: "onToolStart",
+      event: "PreToolUse",
       handler: handleToolStart,
       priority: 100
     });
     hooks.register({
       id: "brain-tool-complete",
-      event: "onToolComplete",
+      event: "PostToolUse",
       handler: handleToolComplete,
       priority: 100
     });
@@ -21018,7 +21072,7 @@ var init_error_hooks = __esm({
     init_registry();
     hooks.register({
       id: "brain-error",
-      event: "onError",
+      event: "PostToolUseFailure",
       handler: handleError,
       priority: 100
     });
@@ -21049,6 +21103,7 @@ async function isFileCaptureEnabled(projectRoot) {
   }
 }
 async function handleFileChange(projectRoot, payload) {
+  if (!payload.filePath || !payload.changeType) return;
   if (!await isFileCaptureEnabled(projectRoot)) return;
   const now2 = Date.now();
   const lastWrite = recentWrites.get(payload.filePath);
@@ -21095,7 +21150,7 @@ var init_file_hooks = __esm({
     ];
     hooks.register({
       id: "brain-file-change",
-      event: "onFileChange",
+      event: "Notification",
       handler: handleFileChange,
       priority: 100
     });
@@ -21149,22 +21204,51 @@ async function handleResponseComplete(projectRoot, payload) {
     if (!isMissingBrainSchemaError4(err)) throw err;
   }
 }
+async function handleSystemNotification(projectRoot, payload) {
+  if (payload.filePath || payload.changeType) return;
+  if (!payload.message) return;
+  try {
+    const { loadConfig: loadConfig4 } = await Promise.resolve().then(() => (init_config(), config_exports));
+    const config2 = await loadConfig4(projectRoot);
+    if (!config2.brain?.autoCapture) return;
+  } catch {
+    return;
+  }
+  const { observeBrain: observeBrain2 } = await Promise.resolve().then(() => (init_brain_retrieval(), brain_retrieval_exports));
+  try {
+    await observeBrain2(projectRoot, {
+      text: `System notification: ${payload.message}`,
+      title: `Notification: ${payload.message.slice(0, 60)}`,
+      type: "discovery",
+      sourceSessionId: payload.sessionId,
+      sourceType: "agent"
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError4(err)) throw err;
+  }
+}
 var init_mcp_hooks = __esm({
   "packages/core/src/hooks/handlers/mcp-hooks.ts"() {
     "use strict";
     init_registry();
     hooks.register({
       id: "brain-prompt-submit",
-      event: "onPromptSubmit",
+      event: "PromptSubmit",
       handler: handlePromptSubmit,
       priority: 100
     });
     hooks.register({
       id: "brain-response-complete",
-      event: "onResponseComplete",
+      event: "ResponseComplete",
       handler: handleResponseComplete,
       priority: 100
     });
+    hooks.register({
+      id: "brain-system-notification",
+      event: "Notification",
+      handler: handleSystemNotification,
+      priority: 90
+    });
   }
 });
 
@@ -21241,19 +21325,158 @@ var init_work_capture_hooks = __esm({
     ]);
     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
     });
   }
 });
 
+// packages/core/src/hooks/handlers/agent-hooks.ts
+function isMissingBrainSchemaError6(err) {
+  if (!(err instanceof Error)) return false;
+  const message = String(err.message || "").toLowerCase();
+  return message.includes("no such table") && message.includes("brain_");
+}
+async function isAutoCaptureEnabled(projectRoot) {
+  try {
+    const { loadConfig: loadConfig4 } = await Promise.resolve().then(() => (init_config(), config_exports));
+    const config2 = await loadConfig4(projectRoot);
+    return config2.brain?.autoCapture ?? false;
+  } catch {
+    return false;
+  }
+}
+async function handleSubagentStart(projectRoot, payload) {
+  if (!await isAutoCaptureEnabled(projectRoot)) return;
+  const { observeBrain: observeBrain2 } = await Promise.resolve().then(() => (init_brain_retrieval(), brain_retrieval_exports));
+  const rolePart = payload.role ? ` role=${payload.role}` : "";
+  const taskPart = payload.taskId ? ` task=${payload.taskId}` : "";
+  try {
+    await observeBrain2(projectRoot, {
+      text: `Subagent spawned: ${payload.agentId}${rolePart}${taskPart}`,
+      title: `Subagent start: ${payload.agentId}`,
+      type: "discovery",
+      sourceSessionId: payload.sessionId,
+      sourceType: "agent"
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError6(err)) throw err;
+  }
+}
+async function handleSubagentStop(projectRoot, payload) {
+  if (!await isAutoCaptureEnabled(projectRoot)) return;
+  const { observeBrain: observeBrain2 } = await Promise.resolve().then(() => (init_brain_retrieval(), brain_retrieval_exports));
+  const statusPart = payload.status ? ` status=${payload.status}` : "";
+  const taskPart = payload.taskId ? ` task=${payload.taskId}` : "";
+  const summaryPart = payload.summary ? `
+Summary: ${payload.summary}` : "";
+  try {
+    await observeBrain2(projectRoot, {
+      text: `Subagent completed: ${payload.agentId}${statusPart}${taskPart}${summaryPart}`,
+      title: `Subagent stop: ${payload.agentId}`,
+      type: "change",
+      sourceSessionId: payload.sessionId,
+      sourceType: "agent"
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError6(err)) throw err;
+  }
+}
+var init_agent_hooks = __esm({
+  "packages/core/src/hooks/handlers/agent-hooks.ts"() {
+    "use strict";
+    init_registry();
+    hooks.register({
+      id: "brain-subagent-start",
+      event: "SubagentStart",
+      handler: handleSubagentStart,
+      priority: 100
+    });
+    hooks.register({
+      id: "brain-subagent-stop",
+      event: "SubagentStop",
+      handler: handleSubagentStop,
+      priority: 100
+    });
+  }
+});
+
+// packages/core/src/hooks/handlers/context-hooks.ts
+function isMissingBrainSchemaError7(err) {
+  if (!(err instanceof Error)) return false;
+  const message = String(err.message || "").toLowerCase();
+  return message.includes("no such table") && message.includes("brain_");
+}
+async function isAutoCaptureEnabled2(projectRoot) {
+  try {
+    const { loadConfig: loadConfig4 } = await Promise.resolve().then(() => (init_config(), config_exports));
+    const config2 = await loadConfig4(projectRoot);
+    return config2.brain?.autoCapture ?? false;
+  } catch {
+    return false;
+  }
+}
+async function handlePreCompact(projectRoot, payload) {
+  if (!await isAutoCaptureEnabled2(projectRoot)) return;
+  const { observeBrain: observeBrain2 } = await Promise.resolve().then(() => (init_brain_retrieval(), brain_retrieval_exports));
+  const tokensPart = payload.tokensBefore != null ? ` (~${payload.tokensBefore.toLocaleString()} tokens)` : "";
+  const reasonPart = payload.reason ? ` Reason: ${payload.reason}` : "";
+  try {
+    await observeBrain2(projectRoot, {
+      text: `Context compaction about to begin${tokensPart}.${reasonPart}`,
+      title: "Pre-compaction context snapshot",
+      type: "discovery",
+      sourceSessionId: payload.sessionId,
+      sourceType: "agent"
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError7(err)) throw err;
+  }
+}
+async function handlePostCompact(projectRoot, payload) {
+  if (!await isAutoCaptureEnabled2(projectRoot)) return;
+  const { observeBrain: observeBrain2 } = await Promise.resolve().then(() => (init_brain_retrieval(), brain_retrieval_exports));
+  const statusPart = payload.success ? "succeeded" : "failed";
+  const beforePart = payload.tokensBefore != null ? ` before=${payload.tokensBefore.toLocaleString()}` : "";
+  const afterPart = payload.tokensAfter != null ? ` after=${payload.tokensAfter.toLocaleString()}` : "";
+  try {
+    await observeBrain2(projectRoot, {
+      text: `Context compaction ${statusPart}${beforePart}${afterPart}`,
+      title: "Post-compaction record",
+      type: "change",
+      sourceSessionId: payload.sessionId,
+      sourceType: "agent"
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError7(err)) throw err;
+  }
+}
+var init_context_hooks = __esm({
+  "packages/core/src/hooks/handlers/context-hooks.ts"() {
+    "use strict";
+    init_registry();
+    hooks.register({
+      id: "brain-pre-compact",
+      event: "PreCompact",
+      handler: handlePreCompact,
+      priority: 100
+    });
+    hooks.register({
+      id: "brain-post-compact",
+      event: "PostCompact",
+      handler: handlePostCompact,
+      priority: 100
+    });
+  }
+});
+
 // packages/core/src/hooks/handlers/index.ts
 var init_handlers = __esm({
   "packages/core/src/hooks/handlers/index.ts"() {
@@ -21264,6 +21487,10 @@ var init_handlers = __esm({
     init_file_hooks();
     init_mcp_hooks();
     init_work_capture_hooks();
+    init_agent_hooks();
+    init_context_hooks();
+    init_agent_hooks();
+    init_context_hooks();
     init_error_hooks();
     init_file_hooks();
     init_mcp_hooks();
@@ -23114,7 +23341,7 @@ async function startSession(options, cwd, accessor) {
     });
   }
   const { hooks: hooks2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
-  hooks2.dispatch("onSessionStart", cwd ?? process.cwd(), {
+  hooks2.dispatch("SessionStart", cwd ?? process.cwd(), {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     sessionId: session.id,
     name: options.name,
@@ -23152,7 +23379,7 @@ async function endSession(options = {}, cwd, accessor) {
   session.endedAt = (/* @__PURE__ */ new Date()).toISOString();
   const duration3 = Math.floor((Date.now() - new Date(session.startedAt).getTime()) / 1e3);
   const { hooks: hooks2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
-  hooks2.dispatch("onSessionEnd", cwd ?? process.cwd(), {
+  hooks2.dispatch("SessionEnd", cwd ?? process.cwd(), {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     sessionId: session.id,
     duration: duration3,
@@ -35888,7 +36115,7 @@ function validatePayload(event, payload) {
   const errors = result.error.issues.map((issue2) => `${issue2.path.join(".")}: ${issue2.message}`);
   return { valid: false, errors };
 }
-var HookPayloadSchema, OnSessionStartPayloadSchema, OnSessionEndPayloadSchema, OnToolStartPayloadSchema, OnToolCompletePayloadSchema, OnFileChangePayloadSchema, OnErrorPayloadSchema, OnPromptSubmitPayloadSchema, OnResponseCompletePayloadSchema, OnWorkAvailablePayloadSchema, OnAgentSpawnPayloadSchema, OnAgentCompletePayloadSchema, OnCascadeStartPayloadSchema, OnPatrolPayloadSchema, EVENT_SCHEMA_MAP;
+var HookPayloadSchema, SessionStartPayloadSchema, OnSessionStartPayloadSchema, SessionEndPayloadSchema, OnSessionEndPayloadSchema, PreToolUsePayloadSchema, OnToolStartPayloadSchema, PostToolUsePayloadSchema, OnToolCompletePayloadSchema, NotificationPayloadSchema, OnFileChangePayloadSchema, PostToolUseFailurePayloadSchema, OnErrorPayloadSchema, PromptSubmitPayloadSchema, OnPromptSubmitPayloadSchema, ResponseCompletePayloadSchema, OnResponseCompletePayloadSchema, SubagentStartPayloadSchema, SubagentStopPayloadSchema, PreCompactPayloadSchema, PostCompactPayloadSchema, ConfigChangePayloadSchema, OnWorkAvailablePayloadSchema, OnAgentSpawnPayloadSchema, OnAgentCompletePayloadSchema, OnCascadeStartPayloadSchema, OnPatrolPayloadSchema, EVENT_SCHEMA_MAP;
 var init_payload_schemas = __esm({
   "packages/core/src/hooks/payload-schemas.ts"() {
     "use strict";
@@ -35900,33 +36127,42 @@ var init_payload_schemas = __esm({
       providerId: external_exports.string().optional(),
       metadata: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
     });
-    OnSessionStartPayloadSchema = HookPayloadSchema.extend({
+    SessionStartPayloadSchema = HookPayloadSchema.extend({
       sessionId: external_exports.string(),
       name: external_exports.string(),
       scope: external_exports.string(),
       agent: external_exports.string().optional()
     });
-    OnSessionEndPayloadSchema = HookPayloadSchema.extend({
+    OnSessionStartPayloadSchema = SessionStartPayloadSchema;
+    SessionEndPayloadSchema = HookPayloadSchema.extend({
       sessionId: external_exports.string(),
       duration: external_exports.number(),
       tasksCompleted: external_exports.array(external_exports.string())
     });
-    OnToolStartPayloadSchema = HookPayloadSchema.extend({
+    OnSessionEndPayloadSchema = SessionEndPayloadSchema;
+    PreToolUsePayloadSchema = HookPayloadSchema.extend({
       taskId: external_exports.string(),
       taskTitle: external_exports.string(),
-      previousTask: external_exports.string().optional()
+      previousTask: external_exports.string().optional(),
+      toolName: external_exports.string().optional(),
+      toolInput: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
     });
-    OnToolCompletePayloadSchema = HookPayloadSchema.extend({
+    OnToolStartPayloadSchema = PreToolUsePayloadSchema;
+    PostToolUsePayloadSchema = HookPayloadSchema.extend({
       taskId: external_exports.string(),
       taskTitle: external_exports.string(),
-      status: external_exports.enum(["done", "archived", "cancelled"])
+      status: external_exports.enum(["done", "archived", "cancelled"]),
+      toolResult: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
     });
-    OnFileChangePayloadSchema = HookPayloadSchema.extend({
-      filePath: external_exports.string(),
-      changeType: external_exports.enum(["write", "create", "delete"]),
-      sizeBytes: external_exports.number().optional()
+    OnToolCompletePayloadSchema = PostToolUsePayloadSchema;
+    NotificationPayloadSchema = HookPayloadSchema.extend({
+      filePath: external_exports.string().optional(),
+      changeType: external_exports.enum(["write", "create", "delete"]).optional(),
+      sizeBytes: external_exports.number().optional(),
+      message: external_exports.string().optional()
     });
-    OnErrorPayloadSchema = HookPayloadSchema.extend({
+    OnFileChangePayloadSchema = NotificationPayloadSchema;
+    PostToolUseFailurePayloadSchema = HookPayloadSchema.extend({
       errorCode: external_exports.union([external_exports.number(), external_exports.string()]),
       message: external_exports.string(),
       domain: external_exports.string().optional(),
@@ -35934,13 +36170,15 @@ var init_payload_schemas = __esm({
       gateway: external_exports.string().optional(),
       stack: external_exports.string().optional()
     });
-    OnPromptSubmitPayloadSchema = HookPayloadSchema.extend({
+    OnErrorPayloadSchema = PostToolUseFailurePayloadSchema;
+    PromptSubmitPayloadSchema = HookPayloadSchema.extend({
       gateway: external_exports.string(),
       domain: external_exports.string(),
       operation: external_exports.string(),
       source: external_exports.string().optional()
     });
-    OnResponseCompletePayloadSchema = HookPayloadSchema.extend({
+    OnPromptSubmitPayloadSchema = PromptSubmitPayloadSchema;
+    ResponseCompletePayloadSchema = HookPayloadSchema.extend({
       gateway: external_exports.string(),
       domain: external_exports.string(),
       operation: external_exports.string(),
@@ -35948,6 +36186,32 @@ var init_payload_schemas = __esm({
       durationMs: external_exports.number().optional(),
       errorCode: external_exports.string().optional()
     });
+    OnResponseCompletePayloadSchema = ResponseCompletePayloadSchema;
+    SubagentStartPayloadSchema = HookPayloadSchema.extend({
+      agentId: external_exports.string(),
+      role: external_exports.string().optional(),
+      taskId: external_exports.string().optional()
+    });
+    SubagentStopPayloadSchema = HookPayloadSchema.extend({
+      agentId: external_exports.string(),
+      status: external_exports.enum(["complete", "partial", "blocked", "failed"]).optional(),
+      taskId: external_exports.string().optional(),
+      summary: external_exports.string().optional()
+    });
+    PreCompactPayloadSchema = HookPayloadSchema.extend({
+      tokensBefore: external_exports.number().optional(),
+      reason: external_exports.string().optional()
+    });
+    PostCompactPayloadSchema = HookPayloadSchema.extend({
+      tokensBefore: external_exports.number().optional(),
+      tokensAfter: external_exports.number().optional(),
+      success: external_exports.boolean()
+    });
+    ConfigChangePayloadSchema = HookPayloadSchema.extend({
+      key: external_exports.string(),
+      previousValue: external_exports.unknown().optional(),
+      newValue: external_exports.unknown().optional()
+    });
     OnWorkAvailablePayloadSchema = HookPayloadSchema.extend({
       taskIds: external_exports.array(external_exports.string()),
       epicId: external_exports.string().optional(),
@@ -35979,14 +36243,21 @@ var init_payload_schemas = __esm({
       scope: external_exports.string().optional()
     });
     EVENT_SCHEMA_MAP = {
-      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,
@@ -36016,10 +36287,15 @@ __export(hooks_exports, {
   OnWorkAvailablePayloadSchema: () => OnWorkAvailablePayloadSchema,
   handleError: () => handleError,
   handleFileChange: () => handleFileChange,
+  handlePostCompact: () => handlePostCompact,
+  handlePreCompact: () => handlePreCompact,
   handlePromptSubmit: () => handlePromptSubmit,
   handleResponseComplete: () => handleResponseComplete,
   handleSessionEnd: () => handleSessionEnd,
   handleSessionStart: () => handleSessionStart,
+  handleSubagentStart: () => handleSubagentStart,
+  handleSubagentStop: () => handleSubagentStop,
+  handleSystemNotification: () => handleSystemNotification,
   handleToolComplete: () => handleToolComplete,
   handleToolStart: () => handleToolStart,
   handleWorkPromptSubmit: () => handleWorkPromptSubmit,
@@ -62451,7 +62727,7 @@ async function startTask(taskId, cwd, accessor) {
     accessor
   );
   const { hooks: hooks2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
-  hooks2.dispatch("onToolStart", cwd ?? process.cwd(), {
+  hooks2.dispatch("PreToolUse", cwd ?? process.cwd(), {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     taskId,
     taskTitle: task.title
@@ -62477,7 +62753,7 @@ async function stopTask(cwd, accessor) {
   const now2 = (/* @__PURE__ */ new Date()).toISOString();
   if (taskId && task) {
     const { hooks: hooks2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
-    hooks2.dispatch("onToolComplete", cwd ?? process.cwd(), {
+    hooks2.dispatch("PostToolUse", cwd ?? process.cwd(), {
       timestamp: now2,
       taskId,
       taskTitle: task.title,
@@ -67884,6 +68160,162 @@ var init_bootstrap = __esm({
   }
 });
 
+// packages/core/src/sessions/snapshot.ts
+async function serializeSession(projectRoot, options = {}, accessor) {
+  const acc = accessor ?? await getAccessor(projectRoot);
+  const maxObs = options.maxObservations ?? 10;
+  const maxDescLen = options.maxDescriptionLength ?? 500;
+  const sessions2 = await acc.loadSessions();
+  let session;
+  if (options.sessionId) {
+    session = sessions2.find((s) => s.id === options.sessionId);
+  } else {
+    session = sessions2.filter((s) => s.status === "active").sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime())[0];
+  }
+  if (!session) {
+    throw new CleoError(
+      31 /* SESSION_NOT_FOUND */,
+      options.sessionId ? `Session '${options.sessionId}' not found` : "No active session to serialize",
+      { fix: "Use 'cleo session list' to see available sessions" }
+    );
+  }
+  const handoff = await computeHandoff(projectRoot, { sessionId: session.id });
+  const decisionLog = await getDecisionLog(projectRoot, { sessionId: session.id });
+  const decisions = decisionLog.map((d) => ({
+    decision: d.decision,
+    rationale: d.rationale,
+    taskId: d.taskId,
+    recordedAt: d.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+  }));
+  let observations = [];
+  try {
+    const { searchBrainCompact: searchBrainCompact2 } = await Promise.resolve().then(() => (init_brain_retrieval(), brain_retrieval_exports));
+    const results = await searchBrainCompact2(projectRoot, {
+      query: session.id,
+      limit: maxObs,
+      tables: ["observations"]
+    });
+    if (Array.isArray(results)) {
+      observations = results.map(
+        (r) => ({
+          id: r.id,
+          text: r.text ?? "",
+          type: r.type ?? "discovery",
+          createdAt: r.createdAt ?? ""
+        })
+      );
+    }
+  } catch {
+  }
+  let activeTask = null;
+  if (session.taskWork?.taskId) {
+    try {
+      const { tasks: tasks2 } = await acc.queryTasks({});
+      const task = tasks2.find((t) => t.id === session.taskWork?.taskId);
+      if (task) {
+        const desc7 = task.description ?? "";
+        activeTask = {
+          taskId: task.id,
+          title: task.title,
+          status: task.status,
+          priority: task.priority ?? "medium",
+          description: desc7.length > maxDescLen ? desc7.slice(0, maxDescLen) + "..." : desc7,
+          acceptance: Array.isArray(task.acceptance) ? task.acceptance.join("\n") : task.acceptance ?? void 0
+        };
+      }
+    } catch {
+    }
+  }
+  const startTime = new Date(session.startedAt).getTime();
+  const now2 = Date.now();
+  const durationMinutes = Math.round((now2 - startTime) / 6e4);
+  return {
+    version: SNAPSHOT_VERSION,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    session,
+    handoff,
+    decisions,
+    observations,
+    activeTask,
+    durationMinutes
+  };
+}
+async function restoreSession(projectRoot, snapshot, options = {}, accessor) {
+  if (snapshot.version > SNAPSHOT_VERSION) {
+    throw new CleoError(
+      6 /* VALIDATION_ERROR */,
+      `Snapshot version ${snapshot.version} is newer than supported version ${SNAPSHOT_VERSION}`,
+      { fix: "Upgrade @cleocode/core to a newer version that supports this snapshot format" }
+    );
+  }
+  const acc = accessor ?? await getAccessor(projectRoot);
+  const activate = options.activate ?? true;
+  if (activate) {
+    const sessions2 = await acc.loadSessions();
+    const scope = snapshot.session.scope;
+    const activeConflict = sessions2.find(
+      (s) => s.status === "active" && s.scope.type === scope.type && s.scope.epicId === scope.epicId && s.id !== snapshot.session.id
+    );
+    if (activeConflict) {
+      throw new CleoError(
+        32 /* SCOPE_CONFLICT */,
+        `Active session '${activeConflict.id}' already exists for scope ${scope.type}${scope.epicId ? ":" + scope.epicId : ""}`,
+        {
+          fix: `End the active session first with 'cleo session end' or restore without activating`,
+          alternatives: [
+            { action: "End conflicting session", command: "cleo session end" },
+            { action: "Restore without activating", command: "Restore with activate: false" }
+          ]
+        }
+      );
+    }
+  }
+  const restoredSession = {
+    ...snapshot.session,
+    status: activate ? "active" : snapshot.session.status,
+    notes: [
+      ...snapshot.session.notes ?? [],
+      `Restored from snapshot at ${(/* @__PURE__ */ new Date()).toISOString()} (captured ${snapshot.capturedAt}, duration ${snapshot.durationMinutes}m)`
+    ],
+    resumeCount: (snapshot.session.resumeCount ?? 0) + 1
+  };
+  if (options.agent) {
+    restoredSession.agent = options.agent;
+    restoredSession.notes = [
+      ...restoredSession.notes ?? [],
+      `Agent handoff: ${snapshot.session.agent ?? "unknown"} \u2192 ${options.agent}`
+    ];
+  }
+  restoredSession.handoffJson = JSON.stringify(snapshot.handoff);
+  await acc.upsertSingleSession(restoredSession);
+  try {
+    const { hooks: hooks2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
+    await hooks2.dispatch("SessionStart", projectRoot, {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId: restoredSession.id,
+      name: restoredSession.name,
+      scope: restoredSession.scope,
+      agent: restoredSession.agent,
+      restored: true,
+      snapshotCapturedAt: snapshot.capturedAt
+    });
+  } catch {
+  }
+  return restoredSession;
+}
+var SNAPSHOT_VERSION;
+var init_snapshot2 = __esm({
+  "packages/core/src/sessions/snapshot.ts"() {
+    "use strict";
+    init_src();
+    init_errors3();
+    init_data_accessor();
+    init_decisions();
+    init_handoff();
+    SNAPSHOT_VERSION = 1;
+  }
+});
+
 // packages/core/src/cleo.ts
 import path from "node:path";
 var Cleo;
@@ -67906,6 +68338,7 @@ var init_cleo = __esm({
     init_link_store();
     init_release2();
     init_sessions();
+    init_snapshot2();
     init_sticky();
     init_data_accessor();
     init_task_work();
@@ -68015,7 +68448,15 @@ var init_cleo = __esm({
           recordAssumption: (p) => recordAssumption(root, p),
           contextDrift: (p) => getContextDrift(root, p),
           decisionLog: (p) => getDecisionLog(root, { sessionId: p?.sessionId, taskId: p?.taskId }),
-          lastHandoff: (scope) => getLastHandoff(root, scope)
+          lastHandoff: (scope) => getLastHandoff(root, scope),
+          serialize: (p) => serializeSession(root, {
+            sessionId: p?.sessionId,
+            maxObservations: p?.maxObservations
+          }),
+          restore: (snapshot, p) => restoreSession(root, snapshot, {
+            agent: p?.agent,
+            activate: p?.activate
+          })
         };
       }
       // === Memory ===
@@ -68371,6 +68812,7 @@ __export(src_exports, {
   remote: () => remote_exports,
   research: () => research_exports,
   resolveProjectPath: () => resolveProjectPath,
+  restoreSession: () => restoreSession,
   resumeSession: () => resumeSession,
   roadmap: () => roadmap_exports,
   routing: () => routing_exports,
@@ -68387,6 +68829,7 @@ __export(src_exports, {
   selectSessionSchema: () => selectSessionSchema,
   selectTaskSchema: () => selectTaskSchema,
   sequence: () => sequence_exports,
+  serializeSession: () => serializeSession,
   sessionStatus: () => sessionStatus,
   sessionStatusSchema: () => sessionStatusSchema,
   sessions: () => sessions_exports,
@@ -68497,6 +68940,7 @@ var init_src2 = __esm({
     init_migration();
     init_reconciliation();
     init_sessions();
+    init_snapshot2();
     init_migrate();
     init_storage_preflight();
     init_task_work();
@@ -69671,6 +70115,14 @@ var init_protocol_enforcement = __esm({
 });
 
 // packages/core/src/hooks/types.ts
+import {
+  buildHookMatrix,
+  CANONICAL_HOOK_EVENTS,
+  HOOK_CATEGORIES,
+  supportsHook,
+  toCanonical,
+  toNative
+} from "@cleocode/caamp";
 import { getCommonHookEvents, getProvidersByHookEvent } from "@cleocode/caamp";
 function isProviderHookEvent(event) {
   return !INTERNAL_HOOK_EVENT_SET.has(event);
@@ -79745,6 +80197,7 @@ __export(internal_exports, {
   resolveTask: () => resolveTask,
   restoreBackup: () => restoreBackup,
   restoreFromBackup: () => restoreFromBackup,
+  restoreSession: () => restoreSession,
   resumeSession: () => resumeSession,
   roadmap: () => roadmap_exports,
   rollbackRelease: () => rollbackRelease,
@@ -79772,6 +80225,7 @@ __export(internal_exports, {
   selectSessionSchema: () => selectSessionSchema,
   selectTaskSchema: () => selectTaskSchema,
   sequence: () => sequence_exports,
+  serializeSession: () => serializeSession,
   sessionStatus: () => sessionStatus,
   sessionStatusSchema: () => sessionStatusSchema,
   sessions: () => sessions_exports,
@@ -83405,6 +83859,30 @@ var init_registry5 = __esm({
         sessionRequired: false,
         requiredParams: []
       },
+      {
+        gateway: "query",
+        domain: "admin",
+        operation: "hooks.matrix",
+        description: "admin.hooks.matrix (query) \u2014 cross-provider hook support matrix using CAAMP canonical taxonomy",
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: [],
+        params: [
+          {
+            name: "providerIds",
+            type: "string",
+            required: false,
+            description: "Limit matrix to specific provider IDs (default: all mapped providers)"
+          },
+          {
+            name: "detectProvider",
+            type: "boolean",
+            required: false,
+            description: "Detect current runtime provider (default: true)"
+          }
+        ]
+      },
       {
         gateway: "query",
         domain: "admin",
@@ -84229,6 +84707,114 @@ var init_config_engine = __esm({
   }
 });
 
+// packages/cleo/src/dispatch/engines/hooks-engine.ts
+var hooks_engine_exports = {};
+__export(hooks_engine_exports, {
+  queryCommonHooks: () => queryCommonHooks,
+  queryHookProviders: () => queryHookProviders,
+  systemHooksMatrix: () => systemHooksMatrix
+});
+async function queryHookProviders(event) {
+  if (!isProviderHookEvent(event)) {
+    return engineSuccess({
+      event,
+      providers: []
+    });
+  }
+  const { getProvidersByHookEvent: getProvidersByHookEvent2 } = await import("@cleocode/caamp");
+  const providers = getProvidersByHookEvent2(event);
+  return engineSuccess({
+    event,
+    providers: providers.map((p) => ({
+      id: p.id,
+      name: p.name,
+      supportedHooks: p.capabilities?.hooks?.supported ?? []
+    }))
+  });
+}
+async function queryCommonHooks(providerIds) {
+  const { getCommonHookEvents: getCommonHookEvents2 } = await import("@cleocode/caamp");
+  const commonEvents = getCommonHookEvents2(providerIds);
+  return engineSuccess({
+    providerIds,
+    commonEvents
+  });
+}
+async function systemHooksMatrix(params) {
+  try {
+    const { buildHookMatrix: buildHookMatrix2, getProviderSummary, getHookMappingsVersion, detectAllProviders: detectAllProviders3 } = await import("@cleocode/caamp");
+    const caampVersion = getHookMappingsVersion();
+    const raw = buildHookMatrix2(params?.providerIds);
+    const boolMatrix = {};
+    for (const event of raw.events) {
+      boolMatrix[event] = {};
+      for (const providerId of raw.providers) {
+        const mapping = raw.matrix[event]?.[providerId];
+        boolMatrix[event][providerId] = mapping?.supported ?? false;
+      }
+    }
+    const summary = raw.providers.map((providerId) => {
+      const provSummary = getProviderSummary(providerId);
+      if (provSummary) {
+        return {
+          providerId,
+          supportedCount: provSummary.supportedCount,
+          totalCanonical: provSummary.totalCanonical,
+          coverage: provSummary.coverage,
+          supported: provSummary.supported,
+          unsupported: provSummary.unsupported
+        };
+      }
+      const supported = raw.events.filter((ev) => boolMatrix[ev]?.[providerId] === true);
+      const unsupported = raw.events.filter((ev) => boolMatrix[ev]?.[providerId] !== true);
+      const totalCanonical = raw.events.length;
+      const coverage = totalCanonical > 0 ? Math.round(supported.length / totalCanonical * 100) : 0;
+      return {
+        providerId,
+        supportedCount: supported.length,
+        totalCanonical,
+        coverage,
+        supported,
+        unsupported
+      };
+    });
+    let detectedProvider = null;
+    const shouldDetect = params?.detectProvider !== false;
+    if (shouldDetect) {
+      try {
+        const detectionResults = detectAllProviders3();
+        const detected = detectionResults.find((r) => r.installed && r.projectDetected);
+        if (detected) {
+          detectedProvider = detected.provider.id;
+        } else {
+          const anyInstalled = detectionResults.find((r) => r.installed);
+          if (anyInstalled) {
+            detectedProvider = anyInstalled.provider.id;
+          }
+        }
+      } catch {
+      }
+    }
+    return engineSuccess({
+      caampVersion,
+      events: raw.events,
+      providers: raw.providers,
+      matrix: boolMatrix,
+      summary,
+      detectedProvider
+    });
+  } catch (err) {
+    return engineError("E_GENERAL", err.message);
+  }
+}
+var init_hooks_engine = __esm({
+  "packages/cleo/src/dispatch/engines/hooks-engine.ts"() {
+    "use strict";
+    init_internal();
+    init_error();
+  }
+});
+
 // packages/cleo/src/dispatch/engines/init-engine.ts
 async function initProject2(projectRoot, options) {
   try {
@@ -87851,6 +88437,7 @@ var init_engine2 = __esm({
     init_internal();
     init_codebase_map_engine();
     init_config_engine();
+    init_hooks_engine();
     init_init_engine();
     init_lifecycle_engine();
     init_memory_engine();
@@ -88379,6 +88966,13 @@ var init_admin2 = __esm({
               const result = await systemSmoke();
               return wrapResult(result, "query", "admin", operation, startTime);
             }
+            case "hooks.matrix": {
+              const result = await systemHooksMatrix({
+                providerIds: params?.providerIds,
+                detectProvider: params?.detectProvider !== false
+              });
+              return wrapResult(result, "query", "admin", operation, startTime);
+            }
             default:
               return unsupportedOp("query", "admin", operation, startTime);
           }
@@ -88863,7 +89457,8 @@ var init_admin2 = __esm({
             "backup",
             "export",
             "map",
-            "smoke"
+            "smoke",
+            "hooks.matrix"
           ],
           mutate: [
             "init",
@@ -92595,46 +93190,6 @@ var init_tasks4 = __esm({
   }
 });
 
-// packages/cleo/src/dispatch/engines/hooks-engine.ts
-var hooks_engine_exports = {};
-__export(hooks_engine_exports, {
-  queryCommonHooks: () => queryCommonHooks,
-  queryHookProviders: () => queryHookProviders
-});
-async function queryHookProviders(event) {
-  if (!isProviderHookEvent(event)) {
-    return engineSuccess({
-      event,
-      providers: []
-    });
-  }
-  const { getProvidersByHookEvent: getProvidersByHookEvent2 } = await import("@cleocode/caamp");
-  const providers = getProvidersByHookEvent2(event);
-  return engineSuccess({
-    event,
-    providers: providers.map((p) => ({
-      id: p.id,
-      name: p.name,
-      supportedHooks: p.capabilities?.hooks?.supported ?? []
-    }))
-  });
-}
-async function queryCommonHooks(providerIds) {
-  const { getCommonHookEvents: getCommonHookEvents2 } = await import("@cleocode/caamp");
-  const commonEvents = getCommonHookEvents2(providerIds);
-  return engineSuccess({
-    providerIds,
-    commonEvents
-  });
-}
-var init_hooks_engine = __esm({
-  "packages/cleo/src/dispatch/engines/hooks-engine.ts"() {
-    "use strict";
-    init_internal();
-    init_error();
-  }
-});
-
 // packages/cleo/src/dispatch/engines/tools-engine.ts
 import {
   buildInjectionContent,
@@ -94224,7 +94779,7 @@ async function dispatchFromCli(gateway, domain2, operation, params, outputOpts)
   const dispatcher = getCliDispatcher();
   const projectRoot = getProjectRoot();
   const dispatchStart = Date.now();
-  hooks.dispatch("onPromptSubmit", projectRoot, {
+  hooks.dispatch("PromptSubmit", projectRoot, {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     gateway,
     domain: domain2,
@@ -94240,7 +94795,7 @@ async function dispatchFromCli(gateway, domain2, operation, params, outputOpts)
     source: "cli",
     requestId: randomUUID10()
   });
-  hooks.dispatch("onResponseComplete", projectRoot, {
+  hooks.dispatch("ResponseComplete", projectRoot, {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     gateway,
     domain: domain2,
@@ -94297,7 +94852,7 @@ async function dispatchRaw(gateway, domain2, operation, params) {
   const dispatcher = getCliDispatcher();
   const projectRoot = getProjectRoot();
   const dispatchStart = Date.now();
-  hooks.dispatch("onPromptSubmit", projectRoot, {
+  hooks.dispatch("PromptSubmit", projectRoot, {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     gateway,
     domain: domain2,
@@ -94313,7 +94868,7 @@ async function dispatchRaw(gateway, domain2, operation, params) {
     source: "cli",
     requestId: randomUUID10()
   });
-  hooks.dispatch("onResponseComplete", projectRoot, {
+  hooks.dispatch("ResponseComplete", projectRoot, {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     gateway,
     domain: domain2,
@@ -96684,15 +97239,84 @@ function createUpgradeProgress(enabled) {
 }
 
 // packages/cleo/src/cli/commands/doctor.ts
+function renderHookMatrixHuman(data) {
+  const { events, providers, matrix, summary, caampVersion, detectedProvider } = data;
+  process.stdout.write(`
+Provider Hook Matrix (CAAMP ${caampVersion} canonical taxonomy)
+
+`);
+  if (detectedProvider) {
+    process.stdout.write(`Detected provider: ${detectedProvider}
+
+`);
+  }
+  if (providers.length === 0) {
+    process.stdout.write("No providers found in CAAMP registry.\n");
+    return;
+  }
+  const EVENT_COL = Math.max(...events.map((e) => e.length), "Event".length);
+  const provCols = providers.map((p) => Math.max(p.length, 5));
+  const headerParts = [
+    "Event".padEnd(EVENT_COL),
+    ...providers.map((p, i) => p.padEnd(provCols[i]))
+  ];
+  process.stdout.write(`  ${headerParts.join("  ")}
+`);
+  const sepParts = ["-".repeat(EVENT_COL), ...provCols.map((w) => "-".repeat(w))];
+  process.stdout.write(`  ${sepParts.join("  ")}
+`);
+  for (const event of events) {
+    const cells = providers.map((p, i) => {
+      const supported = matrix[event]?.[p] === true;
+      const symbol2 = supported ? "\u2713" : "-";
+      return symbol2.padEnd(provCols[i]);
+    });
+    process.stdout.write(`  ${event.padEnd(EVENT_COL)}  ${cells.join("  ")}
+`);
+  }
+  process.stdout.write("\n");
+  const coverageParts = summary.map(
+    (s) => `${s.providerId} ${s.supportedCount}/${s.totalCanonical} (${s.coverage}%)`
+  );
+  process.stdout.write(`Coverage: ${coverageParts.join(", ")}
+
+`);
+}
 function registerDoctorCommand(program) {
-  program.command("doctor").description("Run system diagnostics and health checks").option("--detailed", "Show detailed health check results").option("--comprehensive", "Run comprehensive doctor report").option("--full", "Run operational smoke tests across all domains").option("--fix", "Auto-fix failed checks").option("--coherence", "Run coherence check across task data").action(async (opts, command) => {
+  program.command("doctor").description("Run system diagnostics and health checks").option("--detailed", "Show detailed health check results").option("--comprehensive", "Run comprehensive doctor report").option("--full", "Run operational smoke tests across all domains").option("--fix", "Auto-fix failed checks").option("--coherence", "Run coherence check across task data").option("--hooks", "Show cross-provider hook support matrix (CAAMP canonical taxonomy)").action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals ? command.optsWithGlobals() : command.opts();
     const mergedOpts = { ...globalOpts, ...opts };
     const isHuman = mergedOpts["human"] === true || !!process.stdout.isTTY && mergedOpts["json"] !== true;
     const progress = createDoctorProgress(isHuman);
     progress.start();
     try {
-      if (mergedOpts["full"]) {
+      if (mergedOpts["hooks"]) {
+        progress.step(0, "Building provider hook matrix");
+        if (isHuman) {
+          const response = await dispatchRaw("query", "admin", "hooks.matrix", {
+            detectProvider: true
+          });
+          progress.complete("Hook matrix complete");
+          if (response.success && response.data) {
+            renderHookMatrixHuman(response.data);
+          } else {
+            process.stderr.write(
+              `Error: ${response.error?.message ?? "Failed to build hook matrix"}
+`
+            );
+            process.exitCode = 1;
+          }
+        } else {
+          await dispatchFromCli(
+            "query",
+            "admin",
+            "hooks.matrix",
+            { detectProvider: true },
+            { command: "doctor", operation: "admin.hooks.matrix" }
+          );
+          progress.complete("Hook matrix complete");
+        }
+      } else if (mergedOpts["full"]) {
         progress.step(0, "Running operational smoke tests");
         await dispatchFromCli(
           "query",