@cleocode/core 2026.4.0 → 2026.4.2

package/src/conduit/__tests__/sse-transport.test.js

@@ -0,0 +1,291 @@
+/**
+ * SseTransport test scenarios.
+ *
+ * Tests for the Server-Sent Events transport implementation.
+ * SseTransport extends HTTP polling with real-time push via SSE,
+ * falling back to HTTP polling when SSE is unavailable.
+ *
+ * @see packages/contracts/src/transport.ts — Transport interface
+ * @see packages/contracts/src/conduit.ts — ConduitState types
+ * @task T216
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { SseTransport } from '../sse-transport.js';
+// ============================================================================
+// Test helpers
+// ============================================================================
+/** Mock SSE event source that simulates server-sent events. */
+function createMockEventSource() {
+    const handlers = {};
+    return {
+        addEventListener: vi.fn((type, handler) => {
+            handlers[type] = handlers[type] || [];
+            handlers[type].push(handler);
+        }),
+        removeEventListener: vi.fn(),
+        close: vi.fn(),
+        readyState: 0, // CONNECTING
+        /** Simulate receiving an SSE event. */
+        _emit(type, data) {
+            for (const h of handlers[type] || []) {
+                h(new MessageEvent(type, { data }));
+            }
+        },
+        /** Simulate connection open. */
+        _open() {
+            this.readyState = 1; // OPEN
+            for (const h of handlers['open'] || []) {
+                h(new MessageEvent('open', { data: '' }));
+            }
+        },
+        /** Simulate connection error. */
+        _error() {
+            this.readyState = 2; // CLOSED
+            for (const h of handlers['error'] || []) {
+                h(new MessageEvent('error', { data: '' }));
+            }
+        },
+    };
+}
+/** Standard test config for SseTransport. */
+const TEST_CONFIG = {
+    agentId: 'test-agent',
+    apiKey: 'sk_live_test123',
+    apiBaseUrl: 'https://api.signaldock.io',
+    sseEndpoint: 'https://api.signaldock.io/sse',
+};
+// ============================================================================
+// Connection lifecycle
+// ============================================================================
+describe('SseTransport', () => {
+    describe('connect', () => {
+        it.todo('should establish SSE connection to sseEndpoint');
+        // Expected behavior:
+        // - Creates EventSource to config.sseEndpoint with auth headers
+        // - Sets transport name to 'sse'
+        // - Transitions state: disconnected → connecting → connected
+        // - Resolves when EventSource 'open' event fires
+        it.todo('should fall back to HTTP polling when SSE endpoint is unreachable');
+        // Expected behavior:
+        // - Attempts SSE connection
+        // - On connection error, transitions to HTTP polling mode
+        // - State: disconnected → connecting → connected (via HTTP fallback)
+        // - Logs warning: "SSE unavailable, falling back to HTTP polling"
+        // - poll() still works via HTTP
+        it.todo('should include auth headers in SSE connection');
+        // Expected behavior:
+        // - EventSource URL includes ?token=<apiKey> (SSE doesn't support custom headers)
+        // - Or uses a pre-flight auth endpoint to get a session token
+        // - X-Agent-Id is conveyed via query param or pre-flight
+        it.todo('should reject connect when no sseEndpoint or apiBaseUrl is configured');
+        // Expected behavior:
+        // - Throws Error with message indicating missing config
+        // - State remains 'disconnected'
+        it('rejects connect when no sseEndpoint or apiBaseUrl provided', async () => {
+            const transport = new SseTransport();
+            await expect(transport.connect({ agentId: 'test', apiKey: 'key', apiBaseUrl: '' })).rejects.toThrow('requires');
+        });
+        it.todo('should reject connect when already connected');
+        // Expected behavior:
+        // - Second connect() call throws or is no-op
+        // - Does not create duplicate EventSource instances
+        it('has name "sse"', () => {
+            const transport = new SseTransport();
+            expect(transport.name).toBe('sse');
+        });
+    });
+    // ============================================================================
+    // Disconnect
+    // ============================================================================
+    describe('disconnect', () => {
+        it.todo('should close SSE connection and clear state');
+        // Expected behavior:
+        // - Calls EventSource.close()
+        // - Clears internal state
+        // - State: connected → disconnected
+        // - Subsequent push/poll calls throw "not connected"
+        it.todo('should be idempotent when already disconnected');
+        // Expected behavior:
+        // - No error when calling disconnect() on already disconnected transport
+        // - State remains 'disconnected'
+        it('is safe to call disconnect when not connected', async () => {
+            const transport = new SseTransport();
+            await transport.disconnect(); // Should not throw
+            await transport.disconnect(); // Still should not throw
+        });
+        it.todo('should cancel any pending poll timers');
+        // Expected behavior:
+        // - If HTTP fallback polling is active, clears interval
+        // - No orphaned timers after disconnect
+    });
+    // ============================================================================
+    // Reconnect
+    // ============================================================================
+    describe('reconnect', () => {
+        it.todo('should automatically reconnect on SSE connection drop');
+        // Expected behavior:
+        // - When EventSource fires 'error' and readyState becomes CLOSED
+        // - State: connected → reconnecting
+        // - Exponential backoff: 1s, 2s, 4s, 8s, max 30s
+        // - On successful reconnect: state → connected
+        // - Messages received during reconnect are not lost (server-side cursor)
+        it.todo('should fall back to HTTP polling after N failed SSE reconnects');
+        // Expected behavior:
+        // - After 3 failed SSE reconnect attempts
+        // - Permanently switches to HTTP polling mode for this session
+        // - State: reconnecting → connected (via HTTP)
+        // - Logs: "SSE reconnect failed 3 times, switching to HTTP polling"
+        it.todo('should preserve message cursor across reconnect');
+        // Expected behavior:
+        // - Tracks last received message ID or timestamp
+        // - Reconnect URL includes ?lastEventId=<cursor>
+        // - Server replays missed messages from cursor
+        // - No duplicate messages delivered to consumer
+        it.todo('should emit state change events during reconnect cycle');
+        // Expected behavior:
+        // - onStateChange fires: connected → reconnecting → connected
+        // - Or: connected → reconnecting → error (if max retries exceeded)
+    });
+    // ============================================================================
+    // Message receive (SSE mode)
+    // ============================================================================
+    describe('message receive via SSE', () => {
+        it.todo('should deliver incoming SSE messages via poll() return');
+        // Expected behavior:
+        // - SSE 'message' events are buffered internally
+        // - poll() returns buffered messages and clears buffer
+        // - Messages conform to ConduitMessage interface
+        it.todo('should parse SSE data field as JSON ConduitMessage');
+        // Expected behavior:
+        // - SSE data: {"id":"msg-1","from":"agent-a","content":"hello","timestamp":"..."}
+        // - Parsed into ConduitMessage with all fields populated
+        it.todo('should handle malformed SSE data gracefully');
+        // Expected behavior:
+        // - Invalid JSON in SSE data field does not crash transport
+        // - Malformed messages are logged and skipped
+        // - poll() returns only valid messages
+        it.todo('should filter self-sent messages');
+        // Expected behavior:
+        // - Messages where from === config.agentId are excluded from poll()
+        // - Prevents echo of own messages
+        it.todo('should support SSE event types for different message categories');
+        // Expected behavior:
+        // - 'message' event: standard agent messages
+        // - 'heartbeat' event: keep-alive (ignored in poll output)
+        // - 'system' event: system notifications (e.g., agent online/offline)
+    });
+    // ============================================================================
+    // Send with SSE down (fallback to HTTP)
+    // ============================================================================
+    describe('send (push)', () => {
+        it.todo('should send messages via HTTP POST regardless of SSE state');
+        // Expected behavior:
+        // - push() always uses HTTP POST (SSE is receive-only)
+        // - POST /conversations/{conversationId}/messages or /agents/{to}/messages
+        // - Returns { messageId } from response
+        // - Works whether SSE is connected, reconnecting, or fallen back to HTTP
+        it.todo('should send messages when SSE is connected');
+        // Expected behavior:
+        // - SSE connection is active for receiving
+        // - push() uses HTTP POST for sending (SSE is unidirectional)
+        // - Both channels work simultaneously
+        it.todo('should send messages when SSE is down and in HTTP fallback mode');
+        // Expected behavior:
+        // - SSE connection has failed, transport is in HTTP polling mode
+        // - push() still works via HTTP POST
+        // - No difference in send behavior between SSE and HTTP modes
+        it.todo('should retry failed sends with exponential backoff');
+        // Expected behavior:
+        // - On HTTP 5xx or network error, retry up to 3 times
+        // - Backoff: 500ms, 1s, 2s
+        // - On 4xx (client error), fail immediately (no retry)
+        // - Returns error after max retries
+        it.todo('should throw when not connected');
+        // Expected behavior:
+        // - push() before connect() throws "Transport not connected"
+        // - push() after disconnect() throws "Transport not connected"
+        it('throws when push is called before connect', async () => {
+            const transport = new SseTransport();
+            await expect(transport.push('to', 'msg')).rejects.toThrow('not connected');
+        });
+        it('throws when poll is called before connect', async () => {
+            const transport = new SseTransport();
+            await expect(transport.poll()).rejects.toThrow('not connected');
+        });
+        it('throws when ack is called before connect', async () => {
+            const transport = new SseTransport();
+            await expect(transport.ack(['id'])).rejects.toThrow('not connected');
+        });
+    });
+    // ============================================================================
+    // Poll (hybrid mode)
+    // ============================================================================
+    describe('poll', () => {
+        it.todo('should return SSE-buffered messages when SSE is active');
+        // Expected behavior:
+        // - In SSE mode, poll() drains the internal message buffer
+        // - Does NOT make an HTTP request (messages arrive via SSE push)
+        // - Returns empty array if no new messages since last poll
+        it.todo('should fall back to HTTP polling when SSE is down');
+        // Expected behavior:
+        // - In HTTP fallback mode, poll() makes GET /messages/peek
+        // - Behaves identically to HttpTransport.poll()
+        // - Respects limit and since options
+        it.todo('should respect since parameter for cursor-based retrieval');
+        // Expected behavior:
+        // - poll({ since: '2026-03-30T20:00:00Z' }) returns only newer messages
+        // - In SSE mode: filters buffer by timestamp
+        // - In HTTP mode: passes as query param
+    });
+    // ============================================================================
+    // Acknowledge
+    // ============================================================================
+    describe('ack', () => {
+        it.todo('should acknowledge messages via HTTP POST');
+        // Expected behavior:
+        // - ack(['msg-1', 'msg-2']) sends POST /messages/ack
+        // - Works in both SSE and HTTP modes (always HTTP for ack)
+        // - Acknowledged messages are not returned by subsequent poll()
+    });
+    // ============================================================================
+    // Heartbeat
+    // ============================================================================
+    describe('heartbeat', () => {
+        it.todo('should send heartbeat via HTTP POST');
+        // Expected behavior:
+        // - POST /agents/{agentId}/heartbeat
+        // - Works in both SSE and HTTP modes
+        // - Does not depend on SSE connection state
+        it.todo('should detect SSE connection health from heartbeat response');
+        // Expected behavior:
+        // - Heartbeat response may include SSE connection status
+        // - If server reports SSE session expired, trigger reconnect
+    });
+    // ============================================================================
+    // Edge cases
+    // ============================================================================
+    describe('edge cases', () => {
+        it.todo('should handle rapid connect/disconnect cycles');
+        // Expected behavior:
+        // - connect() → disconnect() → connect() in quick succession
+        // - No resource leaks (EventSource properly closed)
+        // - Final state is consistent
+        it.todo('should handle server-initiated SSE close');
+        // Expected behavior:
+        // - Server sends SSE close/shutdown event
+        // - Transport transitions to reconnecting or HTTP fallback
+        // - No unhandled errors
+        it.todo('should handle network going offline then online');
+        // Expected behavior:
+        // - SSE connection drops (network offline)
+        // - Reconnect attempts fail (network offline)
+        // - When network returns, reconnect succeeds
+        // - Messages buffered server-side are delivered
+        it.todo('should not leak EventSource instances on repeated reconnects');
+        // Expected behavior:
+        // - Each reconnect properly closes the previous EventSource
+        // - No accumulation of open connections
+        // - Memory usage stays constant
+    });
+});
+//# sourceMappingURL=sse-transport.test.js.map

package/src/conduit/__tests__/sse-transport.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-transport.test.js","sourceRoot":"","sources":["sse-transport.test.ts"],"names":[],"mappings":"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"}

package/src/conduit/__tests__/sse-transport.test.ts

@@ -10,7 +10,7 @@
  * @task T216
  */
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
 import { SseTransport } from '../sse-transport.js';
 

package/src/conduit/conduit-client.ts

@@ -74,6 +74,11 @@ export class ConduitClient implements Conduit {
     };
   }
 
+  /** One-shot poll for new messages. Delegates to the transport's poll method. */
+  async poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]> {
+    return this.transport.poll(options);
+  }
+
   /** Subscribe to incoming messages. Uses real-time transport when available, else polls. */
   onMessage(handler: (message: ConduitMessage) => void): ConduitUnsubscribe {
     // Prefer real-time subscription if transport supports it

package/src/conduit/factory.ts

@@ -14,18 +14,35 @@ import { HttpTransport } from './http-transport.js';
 import { LocalTransport } from './local-transport.js';
 import { SseTransport } from './sse-transport.js';
 
-/** Resolve the best available transport for a credential. */
+/**
+ * Resolve the best available transport for a credential.
+ *
+ * Cloud-backed agents (apiBaseUrl is a remote URL) use HttpTransport
+ * so they can receive messages from the SignalDock cloud relay.
+ * LocalTransport is only used when the agent is explicitly local-only
+ * (apiBaseUrl is 'local' or absent), since local signaldock.db doesn't
+ * sync with the cloud.
+ */
 export function resolveTransport(credential: AgentCredential): Transport {
-  // Priority: Local (SQLite) > WebSocket > SSE > HTTP polling
+  const isCloudBacked =
+    credential.apiBaseUrl &&
+    credential.apiBaseUrl !== 'local' &&
+    credential.apiBaseUrl.startsWith('http');
+
+  // Cloud-backed agents must use network transports to receive cloud messages
+  if (isCloudBacked) {
+    if (credential.transportConfig.sseEndpoint) {
+      return new SseTransport();
+    }
+    return new HttpTransport();
+  }
+
+  // Local-only agents use LocalTransport when signaldock.db is available
   if (LocalTransport.isAvailable()) {
     return new LocalTransport();
   }
-  if (credential.transportConfig.wsUrl) {
-    // WsTransport — fall through to SSE/HTTP for now
-  }
-  if (credential.transportConfig.sseEndpoint) {
-    return new SseTransport();
-  }
+
+  // Fallback to HTTP
   return new HttpTransport();
 }
 

package/src/conduit/http-transport.ts

@@ -101,12 +101,13 @@ export class HttpTransport implements Transport {
     return { messageId };
   }
 
-  /** Poll for new messages mentioning this agent. Returns empty array on HTTP error. */
+  /** Poll for new messages for this agent. Returns empty array on HTTP error. */
   async poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]> {
     this.ensureConnected();
 
     const params = new URLSearchParams();
-    params.set('mentioned', this.state!.agentId);
+    // Don't filter by mentioned — the API already scopes by X-Agent-Id header.
+    // Using mentioned= misses messages sent TO this agent without @-mentions.
     if (options?.limit) params.set('limit', String(options.limit));
     if (options?.since) params.set('since', options.since);
 

package/src/crypto/credentials.ts

@@ -15,6 +15,7 @@
  * @module crypto/credentials
  */
 
+import { execFileSync } from 'node:child_process';
 import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto';
 import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
@@ -34,14 +35,24 @@ const CIPHERTEXT_VERSION = 0x01;
  * @throws If HOME/USERPROFILE are unset (F-002: never fall back to /tmp).
  */
 function getMachineKeyPath(): string {
-  const home = process.env['HOME'] ?? process.env['USERPROFILE'];
-  if (!home) {
+  // Use platform-aware data directory: XDG on Linux, Library on macOS, %LOCALAPPDATA% on Windows
+  if (process.platform === 'win32') {
+    const appData = process.env['LOCALAPPDATA'] ?? process.env['APPDATA'];
+    if (appData) return join(appData, 'cleo', 'Data', 'machine-key');
+  } else if (process.platform === 'darwin') {
+    const home = process.env['HOME'];
+    if (home) return join(home, 'Library', 'Application Support', 'cleo', 'machine-key');
+  }
+  // Linux / fallback: XDG_DATA_HOME or ~/.local/share
+  const dataHome =
+    process.env['XDG_DATA_HOME'] ?? join(process.env['HOME'] ?? '', '.local', 'share');
+  if (!dataHome) {
     throw new Error(
-      'Cannot determine home directory. Set HOME or USERPROFILE environment variable. ' +
-        'Machine key cannot be stored securely without a persistent home directory.',
+      'Cannot determine data directory. Set HOME or XDG_DATA_HOME environment variable. ' +
+        'Machine key cannot be stored securely without a persistent data directory.',
     );
   }
-  return join(home, '.local', 'share', 'cleo', 'machine-key');
+  return join(dataHome, 'cleo', 'machine-key');
 }
 
 /**
@@ -54,14 +65,31 @@ async function getMachineKey(): Promise<Buffer> {
   const keyPath = getMachineKeyPath();
 
   try {
-    // Check existing key
+    // Verify key file permissions
     const stats = await stat(keyPath);
-    const mode = stats.mode & 0o777;
-    if (mode !== 0o600) {
-      throw new Error(
-        `Machine key has unsafe permissions (${mode.toString(8)}). Expected 0600. ` +
-          `Fix with: chmod 600 ${keyPath}`,
-      );
+    if (process.platform === 'win32') {
+      // Windows: use icacls to verify the key is not world-readable.
+      try {
+        const output = execFileSync('icacls', [keyPath], { encoding: 'utf-8', timeout: 5000 });
+        const unsafePatterns = /\\(Users|Everyone|Authenticated Users):/i;
+        if (unsafePatterns.test(output)) {
+          throw new Error(
+            `Machine key has unsafe Windows ACLs (accessible to other users). ` +
+              `Fix with: icacls "${keyPath}" /inheritance:r /grant:r "%USERNAME%":F`,
+          );
+        }
+      } catch (aclErr) {
+        if (aclErr instanceof Error && aclErr.message.includes('unsafe')) throw aclErr;
+      }
+    } else {
+      // Unix: verify 0600 permissions
+      const mode = stats.mode & 0o777;
+      if (mode !== 0o600) {
+        throw new Error(
+          `Machine key has unsafe permissions (${mode.toString(8)}). Expected 0600. ` +
+            `Fix with: chmod 600 ${keyPath}`,
+        );
+      }
     }
     const key = await readFile(keyPath);
     // F-004: validate key length
@@ -78,7 +106,25 @@ async function getMachineKey(): Promise<Buffer> {
       const key = randomBytes(KEY_LENGTH);
       await mkdir(dirname(keyPath), { recursive: true });
       await writeFile(keyPath, key, { mode: 0o600 });
-      await chmod(keyPath, 0o600); // Ensure perms even on existing dirs
+      if (process.platform === 'win32') {
+        // Lock down Windows ACLs: remove inherited permissions, grant only current user
+        try {
+          execFileSync(
+            'icacls',
+            [
+              keyPath,
+              '/inheritance:r',
+              '/grant:r',
+              `${process.env['USERNAME'] ?? 'CURRENT_USER'}:F`,
+            ],
+            { timeout: 5000 },
+          );
+        } catch {
+          // Best-effort — icacls may not be available in all environments
+        }
+      } else {
+        await chmod(keyPath, 0o600);
+      }
       return key;
     }
     throw err;

package/src/error-catalog.ts

@@ -1,8 +1,8 @@
 /**
  * Unified Error Catalog -- single source of truth for all CLEO error definitions.
  *
- * Merges previously scattered error registries (error-registry.ts, _error.ts,
- * mcp/lib/exit-codes.ts) into one canonical catalog keyed by ExitCode.
+ * Merges previously scattered error registries into one canonical catalog
+ * keyed by ExitCode.
  *
  * Consumers should import from here instead of the legacy registries.
  *
@@ -26,7 +26,7 @@ export interface ErrorDefinition {
   message: string;
   /** Default fix suggestion (copy-paste command or instruction). */
   fix?: string;
-  /** HTTP status code for API/MCP responses. */
+  /** HTTP status code for API responses. */
   httpStatus: number;
   /** Whether retry may succeed. */
   recoverable: boolean;

package/src/errors.ts

@@ -13,7 +13,7 @@ import { getErrorDefinition } from './error-catalog.js';
 
 /**
  * RFC 9457 Problem Details object.
- * Structured error representation for API/MCP responses.
+ * Structured error representation for API responses.
  *
  * @task T5240
  */

package/src/hooks/__tests__/provider-hooks.test.js

@@ -19,15 +19,15 @@ describe('provider hook capability helpers', () => {
     });
     it('delegates provider-backed hook events to CAAMP', () => {
         getProvidersByHookEventMock.mockReturnValue([{ id: 'claude-code' }, { id: 'opencode' }]);
-        const providers = getHookCapableProviders('onToolStart');
-        expect(getProvidersByHookEventMock).toHaveBeenCalledWith('onToolStart');
+        const providers = getHookCapableProviders('PreToolUse');
+        expect(getProvidersByHookEventMock).toHaveBeenCalledWith('PreToolUse');
         expect(providers).toEqual(['claude-code', 'opencode']);
     });
     it('returns common provider hook events from CAAMP', () => {
-        getCommonHookEventsMock.mockReturnValue(['onSessionStart', 'onToolComplete']);
+        getCommonHookEventsMock.mockReturnValue(['SessionStart', 'PostToolUse']);
         const events = getSharedHookEvents(['claude-code', 'opencode']);
         expect(getCommonHookEventsMock).toHaveBeenCalledWith(['claude-code', 'opencode']);
-        expect(events).toEqual(['onSessionStart', 'onToolComplete']);
+        expect(events).toEqual(['SessionStart', 'PostToolUse']);
     });
 });
 //# sourceMappingURL=provider-hooks.test.js.map

package/src/hooks/__tests__/provider-hooks.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-hooks.test.js","sourceRoot":"","sources":["provider-hooks.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9D,MAAM,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACjF,2BAA2B,EAAE,EAAE,CAAC,EAAE,EAAE;IACpC,uBAAuB,EAAE,EAAE,CAAC,EAAE,EAAE;CACjC,CAAC,CAAC,CAAC;AAEJ,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,CAAC;IAChC,uBAAuB,EAAE,2BAA2B;IACpD,mBAAmB,EAAE,uBAAuB;CAC7C,CAAC,CAAC,CAAC;AAEJ,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEpF,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAChD,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,SAAS,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;QAE7D,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,2BAA2B,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,2BAA2B,CAAC,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;QAEzF,MAAM,SAAS,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAC;QAEzD,MAAM,CAAC,2BAA2B,CAAC,CAAC,oBAAoB,CAAC,aAAa,CAAC,CAAC;QACxE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,uBAAuB,CAAC,eAAe,CAAC,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;QAE9E,MAAM,MAAM,GAAG,mBAAmB,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;QAEhE,MAAM,CAAC,uBAAuB,CAAC,CAAC,oBAAoB,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;QAClF,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"provider-hooks.test.js","sourceRoot":"","sources":["provider-hooks.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9D,MAAM,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACjF,2BAA2B,EAAE,EAAE,CAAC,EAAE,EAAE;IACpC,uBAAuB,EAAE,EAAE,CAAC,EAAE,EAAE;CACjC,CAAC,CAAC,CAAC;AAEJ,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,CAAC;IAChC,uBAAuB,EAAE,2BAA2B;IACpD,mBAAmB,EAAE,uBAAuB;CAC7C,CAAC,CAAC,CAAC;AAEJ,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEpF,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAChD,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,SAAS,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;QAE7D,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,2BAA2B,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,2BAA2B,CAAC,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;QAEzF,MAAM,SAAS,GAAG,uBAAuB,CAAC,YAAY,CAAC,CAAC;QAExD,MAAM,CAAC,2BAA2B,CAAC,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAC;QACvE,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,uBAAuB,CAAC,eAAe,CAAC,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC,CAAC;QAEzE,MAAM,MAAM,GAAG,mBAAmB,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;QAEhE,MAAM,CAAC,uBAAuB,CAAC,CAAC,oBAAoB,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;QAClF,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/src/hooks/__tests__/provider-hooks.test.ts

@@ -27,18 +27,18 @@ describe('provider hook capability helpers', () => {
   it('delegates provider-backed hook events to CAAMP', () => {
     getProvidersByHookEventMock.mockReturnValue([{ id: 'claude-code' }, { id: 'opencode' }]);
 
-    const providers = getHookCapableProviders('onToolStart');
+    const providers = getHookCapableProviders('PreToolUse');
 
-    expect(getProvidersByHookEventMock).toHaveBeenCalledWith('onToolStart');
+    expect(getProvidersByHookEventMock).toHaveBeenCalledWith('PreToolUse');
     expect(providers).toEqual(['claude-code', 'opencode']);
   });
 
   it('returns common provider hook events from CAAMP', () => {
-    getCommonHookEventsMock.mockReturnValue(['onSessionStart', 'onToolComplete']);
+    getCommonHookEventsMock.mockReturnValue(['SessionStart', 'PostToolUse']);
 
     const events = getSharedHookEvents(['claude-code', 'opencode']);
 
     expect(getCommonHookEventsMock).toHaveBeenCalledWith(['claude-code', 'opencode']);
-    expect(events).toEqual(['onSessionStart', 'onToolComplete']);
+    expect(events).toEqual(['SessionStart', 'PostToolUse']);
   });
 });

package/src/hooks/handlers/__tests__/hook-automation-e2e.test.js

@@ -31,8 +31,8 @@ import * as configModule from '../../../config.js';
 import * as brainRetrieval from '../../../memory/brain-retrieval.js';
 import { handleSubagentStart, handleSubagentStop } from '../agent-hooks.js';
 import { handlePostCompact, handlePreCompact } from '../context-hooks.js';
-import { handleSystemNotification } from '../mcp-hooks.js';
 import * as bridgeRefresh from '../memory-bridge-refresh.js';
+import { handleSystemNotification } from '../notification-hooks.js';
 import { handleSessionEnd, handleSessionStart } from '../session-hooks.js';
 import { handleToolComplete, handleToolStart } from '../task-hooks.js';
 import { handleWorkPromptSubmit, handleWorkResponseComplete } from '../work-capture-hooks.js';
@@ -64,7 +64,7 @@ const TIMESTAMP = '2026-03-24T00:00:00.000Z';
 // ---------------------------------------------------------------------------
 describe('hook automation E2E', () => {
     beforeEach(() => {
-        observeBrainMock.mockReset().mockResolvedValue(undefined);
+        observeBrainMock.mockReset().mockResolvedValue({ id: 'O-test', type: 'observation', createdAt: '2026-01-01 00:00:00' });
         loadConfigMock.mockReset().mockResolvedValue(makeConfig());
         maybeRefreshMemoryBridgeMock.mockReset().mockResolvedValue(undefined);
         // Clear work-capture env var