@cleocode/core 2026.3.72 → 2026.3.73

package/src/hooks/handlers/agent-hooks.ts

@@ -0,0 +1,148 @@
+/**
+ * Agent (Subagent) Lifecycle Hook Handlers
+ *
+ * Captures SubagentStart and SubagentStop events to BRAIN so that
+ * multi-agent orchestration runs leave an auditable trail of which
+ * subagents were spawned, what tasks they were assigned, and how
+ * they completed.
+ *
+ * Gated behind brain.autoCapture config. Never throws — all errors are
+ * swallowed so that brain capture never blocks agent orchestration.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T166
+ * @epic T134
+ */
+
+import { hooks } from '../registry.js';
+import type { SubagentStartPayload, SubagentStopPayload } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function isMissingBrainSchemaError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const message = String(err.message || '').toLowerCase();
+  return message.includes('no such table') && message.includes('brain_');
+}
+
+/**
+ * Check whether brain auto-capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. brain.autoCapture project config value (via loadConfig cascade)
+ *
+ * Defaults to false when config is unreadable.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+async function isAutoCaptureEnabled(projectRoot: string): Promise<boolean> {
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.autoCapture ?? false;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle SubagentStart — log subagent spawn as a BRAIN observation.
+ *
+ * Records the agent ID, role, and task assignment so orchestrators can
+ * trace which agents were active in a given session.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - SubagentStart event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handleSubagentStart(
+  projectRoot: string,
+  payload: SubagentStartPayload,
+): Promise<void> {
+  if (!(await isAutoCaptureEnabled(projectRoot))) return;
+
+  const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+  const rolePart = payload.role ? ` role=${payload.role}` : '';
+  const taskPart = payload.taskId ? ` task=${payload.taskId}` : '';
+
+  try {
+    await observeBrain(projectRoot, {
+      text: `Subagent spawned: ${payload.agentId}${rolePart}${taskPart}`,
+      title: `Subagent start: ${payload.agentId}`,
+      type: 'discovery',
+      sourceSessionId: payload.sessionId,
+      sourceType: 'agent',
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError(err)) throw err;
+  }
+}
+
+/**
+ * Handle SubagentStop — log subagent completion result as a BRAIN observation.
+ *
+ * Records the agent ID, completion status, assigned task, and optional
+ * summary reference so orchestrators can audit subagent outcomes.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - SubagentStop event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handleSubagentStop(
+  projectRoot: string,
+  payload: SubagentStopPayload,
+): Promise<void> {
+  if (!(await isAutoCaptureEnabled(projectRoot))) return;
+
+  const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+  const statusPart = payload.status ? ` status=${payload.status}` : '';
+  const taskPart = payload.taskId ? ` task=${payload.taskId}` : '';
+  const summaryPart = payload.summary ? `\nSummary: ${payload.summary}` : '';
+
+  try {
+    await observeBrain(projectRoot, {
+      text: `Subagent completed: ${payload.agentId}${statusPart}${taskPart}${summaryPart}`,
+      title: `Subagent stop: ${payload.agentId}`,
+      type: 'change',
+      sourceSessionId: payload.sessionId,
+      sourceType: 'agent',
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError(err)) throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+
+hooks.register({
+  id: 'brain-subagent-start',
+  event: 'SubagentStart',
+  handler: handleSubagentStart,
+  priority: 100,
+});
+
+hooks.register({
+  id: 'brain-subagent-stop',
+  event: 'SubagentStop',
+  handler: handleSubagentStop,
+  priority: 100,
+});

package/src/hooks/handlers/context-hooks.ts

@@ -0,0 +1,156 @@
+/**
+ * Context Compaction Hook Handlers
+ *
+ * Captures PreCompact and PostCompact events to BRAIN so that agents
+ * can later observe when context compactions occurred and what state
+ * preceded them. This is especially useful for long sessions where
+ * context is compacted multiple times.
+ *
+ * PreCompact saves a session context snapshot before compaction begins.
+ * PostCompact records that compaction occurred and the resulting token counts.
+ *
+ * Gated behind brain.autoCapture config. Never throws — all errors are
+ * swallowed so brain capture never blocks context compaction.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T166
+ * @epic T134
+ */
+
+import { hooks } from '../registry.js';
+import type { PostCompactPayload, PreCompactPayload } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function isMissingBrainSchemaError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const message = String(err.message || '').toLowerCase();
+  return message.includes('no such table') && message.includes('brain_');
+}
+
+/**
+ * Check whether brain auto-capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. brain.autoCapture project config value (via loadConfig cascade)
+ *
+ * Defaults to false when config is unreadable.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+async function isAutoCaptureEnabled(projectRoot: string): Promise<boolean> {
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.autoCapture ?? false;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle PreCompact — snapshot current session memory context to BRAIN.
+ *
+ * Fires immediately before context compaction begins. Records the token
+ * count and compaction reason so the brain retains context about what
+ * was in scope before compaction.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PreCompact event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handlePreCompact(
+  projectRoot: string,
+  payload: PreCompactPayload,
+): Promise<void> {
+  if (!(await isAutoCaptureEnabled(projectRoot))) return;
+
+  const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+  const tokensPart =
+    payload.tokensBefore != null ? ` (~${payload.tokensBefore.toLocaleString()} tokens)` : '';
+  const reasonPart = payload.reason ? ` Reason: ${payload.reason}` : '';
+
+  try {
+    await observeBrain(projectRoot, {
+      text: `Context compaction about to begin${tokensPart}.${reasonPart}`,
+      title: 'Pre-compaction context snapshot',
+      type: 'discovery',
+      sourceSessionId: payload.sessionId,
+      sourceType: 'agent',
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError(err)) throw err;
+  }
+}
+
+/**
+ * Handle PostCompact — record compaction completion to BRAIN.
+ *
+ * Fires immediately after context compaction completes. Records the
+ * before/after token counts so agents can correlate observations made
+ * before compaction with those made after.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - PostCompact event payload.
+ *
+ * @task T166
+ * @epic T134
+ */
+export async function handlePostCompact(
+  projectRoot: string,
+  payload: PostCompactPayload,
+): Promise<void> {
+  if (!(await isAutoCaptureEnabled(projectRoot))) return;
+
+  const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+  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 observeBrain(projectRoot, {
+      text: `Context compaction ${statusPart}${beforePart}${afterPart}`,
+      title: 'Post-compaction record',
+      type: 'change',
+      sourceSessionId: payload.sessionId,
+      sourceType: 'agent',
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError(err)) throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+
+hooks.register({
+  id: 'brain-pre-compact',
+  event: 'PreCompact',
+  handler: handlePreCompact,
+  priority: 100,
+});
+
+hooks.register({
+  id: 'brain-post-compact',
+  event: 'PostCompact',
+  handler: handlePostCompact,
+  priority: 100,
+});

package/src/hooks/handlers/error-hooks.ts

@@ -7,17 +7,20 @@
  */
 
 import { hooks } from '../registry.js';
-import type { OnErrorPayload } from '../types.js';
+import type { PostToolUseFailurePayload } from '../types.js';
 
 /**
- * Handle onError - capture operation errors to BRAIN
+ * Handle PostToolUseFailure - capture operation errors to BRAIN
  *
  * Includes infinite-loop guard: if the payload has _fromHook marker,
- * the handler skips to prevent onError -> observeBrain -> onError loops.
+ * the handler skips to prevent PostToolUseFailure -> observeBrain -> PostToolUseFailure loops.
  * Additionally, ALL observeBrain errors are silently suppressed to prevent
  * re-entrant hook firing.
  */
-export async function handleError(projectRoot: string, payload: OnErrorPayload): Promise<void> {
+export async function handleError(
+  projectRoot: string,
+  payload: PostToolUseFailurePayload,
+): Promise<void> {
   // Infinite-loop guard: skip if this error originated from a hook
   if (payload.metadata?.['_fromHook']) return;
 
@@ -42,7 +45,7 @@ export async function handleError(projectRoot: string, payload: OnErrorPayload):
 // Register handler on module load
 hooks.register({
   id: 'brain-error',
-  event: 'onError',
+  event: 'PostToolUseFailure',
   handler: handleError,
   priority: 100,
 });

package/src/hooks/handlers/file-hooks.ts

@@ -12,7 +12,7 @@
 
 import { isAbsolute, relative } from 'node:path';
 import { hooks } from '../registry.js';
-import type { OnFileChangePayload } from '../types.js';
+import type { NotificationPayload } from '../types.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -65,7 +65,7 @@ async function isFileCaptureEnabled(projectRoot: string): Promise<boolean> {
 }
 
 /**
- * Handle onFileChange - capture file changes to BRAIN
+ * Handle Notification (file-change variant) - capture file changes to BRAIN
  *
  * Gated behind brain.captureFiles config or CLEO_BRAIN_CAPTURE_FILES env var.
  * Env var takes precedence over config for backward compatibility.
@@ -75,8 +75,10 @@ async function isFileCaptureEnabled(projectRoot: string): Promise<boolean> {
  */
 export async function handleFileChange(
   projectRoot: string,
-  payload: OnFileChangePayload,
+  payload: NotificationPayload,
 ): Promise<void> {
+  // Only handle file-change notifications
+  if (!payload.filePath || !payload.changeType) return;
   // Opt-in gate: disabled by default to prevent observation noise
   if (!(await isFileCaptureEnabled(projectRoot))) return;
 
@@ -111,7 +113,7 @@ export async function handleFileChange(
 // Register handler on module load
 hooks.register({
   id: 'brain-file-change',
-  event: 'onFileChange',
+  event: 'Notification',
   handler: handleFileChange,
   priority: 100,
 });

package/src/hooks/handlers/index.ts

@@ -3,6 +3,9 @@
  *
  * Barrel export for all hook handlers. Importing this module will
  * auto-register all handlers with the hook registry.
+ *
+ * @task T166
+ * @epic T134
  */
 
 // Import handlers to trigger auto-registration on module load
@@ -12,10 +15,18 @@ import './error-hooks.js';
 import './file-hooks.js';
 import './mcp-hooks.js';
 import './work-capture-hooks.js';
+import './agent-hooks.js';
+import './context-hooks.js';
 
+export { handleSubagentStart, handleSubagentStop } from './agent-hooks.js';
+export { handlePostCompact, handlePreCompact } from './context-hooks.js';
 export { handleError } from './error-hooks.js';
 export { handleFileChange } from './file-hooks.js';
-export { handlePromptSubmit, handleResponseComplete } from './mcp-hooks.js';
+export {
+  handlePromptSubmit,
+  handleResponseComplete,
+  handleSystemNotification,
+} from './mcp-hooks.js';
 // Re-export handler functions for explicit use
 export { handleSessionEnd, handleSessionStart } from './session-hooks.js';
 export { handleToolComplete, handleToolStart } from './task-hooks.js';

package/src/hooks/handlers/mcp-hooks.ts

@@ -1,16 +1,26 @@
 /**
  * MCP Prompt/Response Hook Handlers - Wave 2 of T5237
  *
- * Handlers for onPromptSubmit and onResponseComplete events that capture
- * ALL gateway operations (read and write) to BRAIN.
+ * Handlers for onPromptSubmit, onResponseComplete, and system Notification
+ * events that capture ALL gateway operations (read and write) to BRAIN.
  * By default, NO brain capture (too noisy). Enable via:
  *   - Config: brain.captureMcp = true  (checked first)
  *   - Env:    CLEO_BRAIN_CAPTURE_MCP=true  (overrides config)
  * Auto-registers on module load.
+ *
+ * Note: File-change Notification events (those with filePath + changeType) are
+ * handled by file-hooks.ts. This module handles message-bearing system
+ * notifications (Notification payloads with a message field).
+ *
+ * @task T166
  */
 
 import { hooks } from '../registry.js';
-import type { OnPromptSubmitPayload, OnResponseCompletePayload } from '../types.js';
+import type {
+  NotificationPayload,
+  PromptSubmitPayload,
+  ResponseCompletePayload,
+} from '../types.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -42,14 +52,14 @@ async function isBrainCaptureEnabled(projectRoot: string): Promise<boolean> {
 }
 
 /**
- * Handle onPromptSubmit - optionally capture ALL gateway prompt events to BRAIN.
+ * Handle PromptSubmit - optionally capture ALL gateway prompt events to BRAIN.
  *
  * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
  * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handlePromptSubmit(
   projectRoot: string,
-  payload: OnPromptSubmitPayload,
+  payload: PromptSubmitPayload,
 ): Promise<void> {
   if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
@@ -68,14 +78,14 @@ export async function handlePromptSubmit(
 }
 
 /**
- * Handle onResponseComplete - optionally capture ALL gateway response events to BRAIN.
+ * Handle ResponseComplete - optionally capture ALL gateway response events to BRAIN.
  *
  * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
  * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handleResponseComplete(
   projectRoot: string,
-  payload: OnResponseCompletePayload,
+  payload: ResponseCompletePayload,
 ): Promise<void> {
   if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
@@ -93,17 +103,72 @@ export async function handleResponseComplete(
   }
 }
 
+/**
+ * Handle Notification — capture system notifications as BRAIN observations.
+ *
+ * Only fires for Notification payloads that carry a message field (i.e. system
+ * notifications). File-change notifications (filePath + changeType) are
+ * handled exclusively by file-hooks.ts and are skipped here to avoid
+ * double-capture.
+ *
+ * Gated behind brain.autoCapture config. Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - Notification event payload.
+ *
+ * @task T166
+ */
+export async function handleSystemNotification(
+  projectRoot: string,
+  payload: NotificationPayload,
+): Promise<void> {
+  // File-change notifications are handled by file-hooks.ts
+  if (payload.filePath || payload.changeType) return;
+  // Only handle message-bearing system notifications
+  if (!payload.message) return;
+
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    if (!config.brain?.autoCapture) return;
+  } catch {
+    return;
+  }
+
+  const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+  try {
+    await observeBrain(projectRoot, {
+      text: `System notification: ${payload.message}`,
+      title: `Notification: ${payload.message.slice(0, 60)}`,
+      type: 'discovery',
+      sourceSessionId: payload.sessionId,
+      sourceType: 'agent',
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError(err)) throw err;
+  }
+}
+
 // Register handlers on module load
 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,
 });
+
+// Lower priority (90) so file-hooks.ts (100) runs first for Notification events
+hooks.register({
+  id: 'brain-system-notification',
+  event: 'Notification',
+  handler: handleSystemNotification,
+  priority: 90,
+});

package/src/hooks/handlers/session-hooks.ts

@@ -10,7 +10,7 @@
  */
 
 import { hooks } from '../registry.js';
-import type { OnSessionEndPayload, OnSessionStartPayload } from '../types.js';
+import type { SessionEndPayload, SessionStartPayload } from '../types.js';
 import { maybeRefreshMemoryBridge } from './memory-bridge-refresh.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
@@ -20,14 +20,14 @@ function isMissingBrainSchemaError(err: unknown): boolean {
 }
 
 /**
- * Handle onSessionStart - capture initial session context
+ * Handle SessionStart - capture initial session context
  *
  * T138: Refresh memory bridge on session start.
  * T139: Regenerate bridge with session scope context.
  */
 export async function handleSessionStart(
   projectRoot: string,
-  payload: OnSessionStartPayload,
+  payload: SessionStartPayload,
 ): Promise<void> {
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 
@@ -48,14 +48,14 @@ export async function handleSessionStart(
 }
 
 /**
- * Handle onSessionEnd - capture session summary
+ * Handle SessionEnd - capture session summary
  *
  * T138: Refresh memory bridge after session ends.
  * T144: Extract transcript observations via cross-provider adapter.
  */
 export async function handleSessionEnd(
   projectRoot: string,
-  payload: OnSessionEndPayload,
+  payload: SessionEndPayload,
 ): Promise<void> {
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 
@@ -107,14 +107,14 @@ export async function handleSessionEnd(
 // Register handlers on module load
 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,
 });

package/src/hooks/handlers/task-hooks.ts

@@ -8,7 +8,7 @@
  */
 
 import { hooks } from '../registry.js';
-import type { OnToolCompletePayload, OnToolStartPayload } from '../types.js';
+import type { PostToolUsePayload, PreToolUsePayload } from '../types.js';
 import { maybeRefreshMemoryBridge } from './memory-bridge-refresh.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
@@ -18,11 +18,11 @@ function isMissingBrainSchemaError(err: unknown): boolean {
 }
 
 /**
- * Handle onToolStart (maps to task.start in CLEO)
+ * Handle PreToolUse (maps to task.start in CLEO, canonical: was onToolStart)
  */
 export async function handleToolStart(
   projectRoot: string,
-  payload: OnToolStartPayload,
+  payload: PreToolUsePayload,
 ): Promise<void> {
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 
@@ -39,13 +39,13 @@ export async function handleToolStart(
 }
 
 /**
- * Handle onToolComplete (maps to task.complete in CLEO)
+ * Handle PostToolUse (maps to task.complete in CLEO, canonical: was onToolComplete)
  *
  * T138: Refresh memory bridge after task completion.
  */
 export async function handleToolComplete(
   projectRoot: string,
-  payload: OnToolCompletePayload,
+  payload: PostToolUsePayload,
 ): Promise<void> {
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 
@@ -67,14 +67,14 @@ export async function handleToolComplete(
 // Register handlers
 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,
 });