@cleocode/adapters 2026.4.38 → 2026.4.40

package/src/cant-context.ts

@@ -0,0 +1,379 @@
+/**
+ * Shared CANT context builder for all spawn providers.
+ *
+ * Extracts the Pi bridge's CANT discovery/compile/inject logic into a reusable
+ * module that any spawn provider (Claude Code, OpenCode, Cursor, etc.) can call
+ * to enrich agent prompts with:
+ *
+ * 1. Compiled CANT bundle (team topology, agent personas, tool ACLs)
+ * 2. Memory bridge (recent decisions, handoff notes, key patterns)
+ * 3. Mental model injection (validate-on-load agent-specific observations)
+ *
+ * All operations are best-effort: if any step fails (missing packages, empty
+ * directories, compilation errors), the base prompt is returned unchanged.
+ * This guarantees agents always spawn — CANT context is an enrichment, not a gate.
+ *
+ * Reference implementation: packages/cleo-os/extensions/cleo-cant-bridge.ts
+ * (Pi-only; this module generalizes the same logic for all providers)
+ *
+ * @task T555
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Per-tier file counts for diagnostic reporting. */
+export interface TierDiscoveryStats {
+  global: number;
+  user: number;
+  project: number;
+  overrides: number;
+  merged: number;
+}
+
+/** Minimal observation shape returned by memoryFind / searchBrainCompact. */
+export interface MentalModelObservation {
+  id: string;
+  type: string;
+  title: string;
+  date?: string;
+}
+
+/** Options for the main enrichment function. */
+export interface BuildCantEnrichedPromptOptions {
+  /** Project root directory for .cleo/cant/ discovery and brain.db access. */
+  projectDir: string;
+  /** The raw prompt to enrich. Returned unchanged if no CANT context is available. */
+  basePrompt: string;
+  /** Agent name for mental model injection. Omit to skip mental model fetch. */
+  agentName?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Preamble text injected when an agent has mental model observations.
+ * The agent MUST re-evaluate each observation against current project state.
+ */
+const VALIDATE_ON_LOAD_PREAMBLE =
+  '===== MENTAL MODEL (validate-on-load) =====\n' +
+  'These are your prior observations, patterns, and learnings for this project.\n' +
+  'Before acting, you MUST re-evaluate each entry against current project state.\n' +
+  'If an entry is stale, note it and proceed with fresh understanding.';
+
+// ---------------------------------------------------------------------------
+// Discovery functions (ported from cleo-cant-bridge.ts lines 418-526)
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively discover `.cant` files in a directory.
+ *
+ * @param dir - The directory to scan recursively.
+ * @returns An array of absolute paths to `.cant` files found.
+ */
+export function discoverCantFiles(dir: string): string[] {
+  try {
+    const entries = readdirSync(dir, { recursive: true, withFileTypes: true });
+    const files: string[] = [];
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.cant')) {
+        const parent = (entry as unknown as { parentPath?: string }).parentPath ?? dir;
+        files.push(join(parent, entry.name));
+      }
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve XDG-compliant paths for the 3-tier CANT hierarchy.
+ *
+ * Respects `XDG_DATA_HOME` and `XDG_CONFIG_HOME` environment variables.
+ * Falls back to XDG defaults (`~/.local/share/` and `~/.config/`).
+ *
+ * @param projectDir - The project root directory (for the project tier).
+ * @returns An object with `global`, `user`, and `project` CANT directory paths.
+ */
+export function resolveThreeTierPaths(projectDir: string): {
+  global: string;
+  user: string;
+  project: string;
+} {
+  const home = homedir();
+  const xdgData = process.env['XDG_DATA_HOME'] ?? join(home, '.local', 'share');
+  const xdgConfig = process.env['XDG_CONFIG_HOME'] ?? join(home, '.config');
+
+  return {
+    global: join(xdgData, 'cleo', 'cant'),
+    user: join(xdgConfig, 'cleo', 'cant'),
+    project: join(projectDir, '.cleo', 'cant'),
+  };
+}
+
+/**
+ * Discover `.cant` files across all three tiers with override semantics.
+ *
+ * Scans global, user, and project tiers. Files in higher-precedence tiers
+ * override files in lower-precedence tiers that share the same basename.
+ * The precedence order is: project > user > global.
+ *
+ * @param projectDir - The project root directory.
+ * @returns An object containing the merged file list and per-tier statistics.
+ */
+export function discoverCantFilesMultiTier(projectDir: string): {
+  files: string[];
+  stats: TierDiscoveryStats;
+} {
+  const paths = resolveThreeTierPaths(projectDir);
+
+  const globalFiles = discoverCantFiles(paths.global);
+  const userFiles = discoverCantFiles(paths.user);
+  const projectFiles = discoverCantFiles(paths.project);
+
+  // Build basename-keyed map; lowest precedence first so higher tiers override
+  const fileMap = new Map<string, string>();
+
+  for (const file of globalFiles) {
+    fileMap.set(basename(file), file);
+  }
+
+  for (const file of userFiles) {
+    fileMap.set(basename(file), file);
+  }
+
+  for (const file of projectFiles) {
+    fileMap.set(basename(file), file);
+  }
+
+  const totalUniqueInputs = globalFiles.length + userFiles.length + projectFiles.length;
+  const overrides = totalUniqueInputs - fileMap.size;
+
+  return {
+    files: Array.from(fileMap.values()),
+    stats: {
+      global: globalFiles.length,
+      user: userFiles.length,
+      project: projectFiles.length,
+      overrides,
+      merged: fileMap.size,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Memory bridge (ported from cleo-cant-bridge.ts lines 376-404)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the memory bridge file from a project's .cleo/ directory.
+ *
+ * @param projectDir - The project root directory.
+ * @returns The memory bridge content, or null if not found or empty.
+ */
+export function readMemoryBridge(projectDir: string): string | null {
+  try {
+    const bridgePath = join(projectDir, '.cleo', 'memory-bridge.md');
+    if (!existsSync(bridgePath)) return null;
+    const content = readFileSync(bridgePath, 'utf-8');
+    return content.length > 0 ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the memory-bridge system-prompt block appended to every agent.
+ *
+ * Wraps the raw memory-bridge.md content in a clearly labeled section
+ * so the agent knows this is the CLEO project memory context.
+ *
+ * @param content - The raw memory-bridge.md content.
+ * @returns The formatted memory-bridge block for system prompt injection.
+ */
+export function buildMemoryBridgeBlock(content: string): string {
+  return (
+    '\n\n===== CLEO MEMORY BRIDGE =====\n' +
+    'This is your project memory context from .cleo/memory-bridge.md.\n' +
+    'Use it to understand recent decisions, handoff notes, and key patterns.\n\n' +
+    content.trim() +
+    '\n===== END MEMORY BRIDGE ====='
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Mental model injection (ported from cleo-cant-bridge.ts lines 113-135, 543-589)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the validate-on-load mental-model injection string.
+ *
+ * Pure function — no I/O, safe to call in tests without a real DB.
+ *
+ * @param agentName - Name of the spawned agent (used in the header line).
+ * @param observations - Prior mental-model observations to list.
+ * @returns System-prompt block with preamble and numbered observations,
+ *          or empty string when `observations` is empty.
+ */
+export function buildMentalModelInjection(
+  agentName: string,
+  observations: MentalModelObservation[],
+): string {
+  if (observations.length === 0) return '';
+
+  const lines: string[] = ['', `// Agent: ${agentName}`, VALIDATE_ON_LOAD_PREAMBLE, ''];
+
+  for (let i = 0; i < observations.length; i++) {
+    const obs = observations[i];
+    const datePart = obs.date ? ` [${obs.date}]` : '';
+    lines.push(`${i + 1}. [${obs.id}] (${obs.type})${datePart}: ${obs.title}`);
+  }
+
+  lines.push('===== END MENTAL MODEL =====');
+  return lines.join('\n');
+}
+
+/**
+ * Fetch mental model observations for an agent from brain.db.
+ *
+ * Uses dynamic import of `@cleocode/core` to avoid circular dependencies.
+ * Returns empty string on any failure (best-effort, never throws).
+ *
+ * @param agentName - The agent's name for scoped observation lookup.
+ * @param projectRoot - Project root directory for brain.db access.
+ * @returns The validate-on-load system-prompt block, or "" on failure/empty.
+ */
+async function fetchMentalModelInjection(agentName: string, projectRoot: string): Promise<string> {
+  try {
+    // Dynamic import — @cleocode/core is NOT a compile-time dependency of adapters.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const coreModule = (await import(/* webpackIgnore: true */ '@cleocode/core' as string)) as {
+      memoryFind?: (
+        params: {
+          query: string;
+          agent?: string;
+          limit?: number;
+          tables?: string[];
+        },
+        projectRoot?: string,
+      ) => Promise<{
+        success: boolean;
+        data?: {
+          results?: MentalModelObservation[];
+        };
+      }>;
+    };
+
+    if (typeof coreModule.memoryFind !== 'function') return '';
+
+    const result = await coreModule.memoryFind(
+      {
+        query: agentName,
+        agent: agentName,
+        limit: 10,
+        tables: ['observations'],
+      },
+      projectRoot,
+    );
+
+    if (!result.success || !result.data?.results?.length) return '';
+
+    return buildMentalModelInjection(agentName, result.data.results);
+  } catch {
+    return '';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an enriched prompt with CANT context, memory bridge, and mental model.
+ *
+ * This is the universal entry point for all spawn providers. It performs the
+ * same operations as the Pi bridge (cleo-cant-bridge.ts) but returns a string
+ * rather than hooking into Pi events:
+ *
+ * 1. Discovers `.cant` files across 3 tiers (global → user → project)
+ * 2. Compiles the CANT bundle via `@cleocode/cant`'s `compileBundle()`
+ * 3. Renders the compiled system prompt
+ * 4. Reads the memory bridge from `.cleo/memory-bridge.md`
+ * 5. Fetches mental model observations for the named agent
+ * 6. Concatenates: basePrompt + CANT bundle + memory bridge + mental model
+ *
+ * All operations are best-effort. If any step fails, the base prompt is
+ * returned unchanged. CANT context is an enrichment, not a gate — agents
+ * always spawn regardless of CANT availability.
+ *
+ * @param options - Project dir, base prompt, and optional agent name.
+ * @returns The enriched prompt string, or basePrompt unchanged on failure.
+ */
+export async function buildCantEnrichedPrompt(
+  options: BuildCantEnrichedPromptOptions,
+): Promise<string> {
+  const { projectDir, basePrompt, agentName } = options;
+  let appendix = '';
+
+  // Step 1-3: Discover and compile CANT bundle
+  try {
+    const { files } = discoverCantFilesMultiTier(projectDir);
+
+    if (files.length > 0) {
+      // Dynamic import — @cleocode/cant is NOT a compile-time dependency of adapters.
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const cantModule = (await import(/* webpackIgnore: true */ '@cleocode/cant' as string)) as {
+        compileBundle?: (paths: string[]) => {
+          renderSystemPrompt: () => string;
+          valid: boolean;
+          diagnostics: unknown[];
+        };
+      };
+
+      if (typeof cantModule.compileBundle === 'function') {
+        const bundle = cantModule.compileBundle(files);
+        if (bundle.valid) {
+          const rendered = bundle.renderSystemPrompt();
+          if (rendered) {
+            appendix += `\n\n${rendered}`;
+          }
+        }
+      }
+    }
+  } catch {
+    // CANT compilation failure — continue without bundle context
+  }
+
+  // Step 4: Append memory bridge
+  try {
+    const bridge = readMemoryBridge(projectDir);
+    if (bridge) {
+      appendix += buildMemoryBridgeBlock(bridge);
+    }
+  } catch {
+    // Memory bridge read failure — non-fatal
+  }
+
+  // Step 5: Append mental model for named agent
+  if (agentName) {
+    try {
+      const mentalModel = await fetchMentalModelInjection(agentName, projectDir);
+      if (mentalModel) {
+        appendix += `\n\n${mentalModel}`;
+      }
+    } catch {
+      // Mental model fetch failure — non-fatal
+    }
+  }
+
+  // Step 6: Return enriched prompt (or unchanged basePrompt if no context found)
+  return appendix ? basePrompt + appendix : basePrompt;
+}

package/src/index.ts

@@ -13,6 +13,9 @@
  * registry enable dynamic adapter loading by AdapterManager.
  */
 
+export type { BuildCantEnrichedPromptOptions, TierDiscoveryStats } from './cant-context.js';
+// Shared CANT context builder — used by all spawn providers
+export { buildCantEnrichedPrompt } from './cant-context.js';
 // Re-export adapter classes for direct use
 // Per-provider factory functions (renamed to avoid collisions)
 export {

package/src/providers/claude-code/adapter.ts

@@ -123,6 +123,10 @@ export class ClaudeCodeAdapter implements CLEOProviderAdapter {
   async initialize(projectDir: string): Promise<void> {
     this.projectDir = projectDir;
     this.initialized = true;
+
+    // Activate CLEO hook bridge for this project — connects Claude Code
+    // native events to CLEO's internal hook dispatch (T555).
+    await this.hooks.registerNativeHooks(projectDir);
   }
 
   /**

package/src/providers/claude-code/hooks.ts

@@ -16,7 +16,9 @@
  * @epic T134
  */
 
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { AdapterHookProvider } from '@cleocode/contracts';
 
@@ -107,33 +109,146 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
     return CLAUDE_CODE_EVENT_MAP[providerEvent] ?? null;
   }
 
+  /** Project directory this hook provider was registered for. */
+  private projectDir: string | null = null;
+
   /**
    * Register native hooks for a project.
    *
-   * For Claude Code, hooks are registered via the config system
-   * (`~/.claude/settings.json`), managed by the install provider.
-   * This method marks hooks as registered without performing filesystem operations.
+   * Writes CLEO hook entries to `~/.claude/settings.json` so that Claude Code's
+   * native event system calls cleo CLI commands when events fire. This bridges
+   * Claude Code's event loop to CLEO's internal hook dispatch.
    *
-   * Iterating supported events is handled at install time using
-   * `getSupportedCanonicalEvents()` to enumerate all 14 supported hooks.
+   * Idempotent: skips writing if CLEO hooks already exist in settings.json.
    *
-   * @param _projectDir - Project directory (unused; Claude Code uses global config)
-   * @task T164
+   * Hook entries registered:
+   * - `Stop` → `cleo session end --quiet` (triggers LLM extraction, reflector, consolidation)
+   * - `PostToolUse` (Write|Edit) → brain observation for file modifications
+   * - `SubagentStop` → brain observation for agent completion
+   *
+   * @param projectDir - Project directory for context-scoped hook commands
+   * @task T164 @task T555
    */
-  async registerNativeHooks(_projectDir: string): Promise<void> {
+  async registerNativeHooks(projectDir: string): Promise<void> {
+    this.projectDir = projectDir;
     this.registered = true;
+
+    // Write CLEO hook entries to ~/.claude/settings.json (idempotent)
+    try {
+      const home = homedir();
+      const settingsPath = join(home, '.claude', 'settings.json');
+
+      let settings: Record<string, unknown> = {};
+      if (existsSync(settingsPath)) {
+        try {
+          settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        } catch {
+          // Start fresh if settings.json is corrupt
+        }
+      }
+
+      const hooks = (settings.hooks ?? {}) as Record<string, unknown[]>;
+
+      // Check if CLEO hooks already registered (look for our marker comment in commands)
+      const alreadyRegistered = Object.values(hooks).some(
+        (entries) =>
+          Array.isArray(entries) &&
+          entries.some(
+            (e) =>
+              typeof e === 'object' &&
+              e !== null &&
+              Array.isArray((e as Record<string, unknown>).hooks) &&
+              ((e as Record<string, unknown>).hooks as Array<Record<string, string>>).some(
+                (h) => typeof h.command === 'string' && h.command.includes('# cleo-hook'),
+              ),
+          ),
+      );
+
+      if (alreadyRegistered) {
+        return; // Already wired — idempotent
+      }
+
+      // Register Stop hook → triggers cleo session end (LLM extraction, reflector, consolidation)
+      if (!hooks.Stop) hooks.Stop = [];
+      (hooks.Stop as unknown[]).push({
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `cleo session end --quiet # cleo-hook`,
+          },
+        ],
+      });
+
+      // Register PostToolUse hook → brain observation for file writes
+      if (!hooks.PostToolUse) hooks.PostToolUse = [];
+      (hooks.PostToolUse as unknown[]).push({
+        matcher: 'Write|Edit',
+        hooks: [
+          {
+            type: 'command',
+            command: `cleo observe "File modified via $TOOL_NAME" --title "tool-use" --quiet # cleo-hook`,
+          },
+        ],
+      });
+
+      settings.hooks = hooks;
+      mkdirSync(join(home, '.claude'), { recursive: true });
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    } catch {
+      // Settings write failure is non-fatal — hooks can be registered manually
+    }
   }
 
   /**
    * Unregister native hooks.
    *
-   * For Claude Code, this is a no-op since hooks are managed through the config
-   * system. Unregistration happens via the install provider's uninstall method.
+   * Removes CLEO hook entries from `~/.claude/settings.json` by filtering out
+   * entries containing the `# cleo-hook` marker.
    *
-   * @task T164
+   * @task T164 @task T555
    */
   async unregisterNativeHooks(): Promise<void> {
     this.registered = false;
+    this.projectDir = null;
+
+    try {
+      const home = homedir();
+      const settingsPath = join(home, '.claude', 'settings.json');
+      if (!existsSync(settingsPath)) return;
+
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
+      const hooks = settings.hooks as Record<string, unknown[]> | undefined;
+      if (!hooks) return;
+
+      // Filter out entries with the cleo-hook marker
+      let changed = false;
+      for (const [event, entries] of Object.entries(hooks)) {
+        if (!Array.isArray(entries)) continue;
+        const filtered = entries.filter(
+          (e) =>
+            !(
+              typeof e === 'object' &&
+              e !== null &&
+              Array.isArray((e as Record<string, unknown>).hooks) &&
+              ((e as Record<string, unknown>).hooks as Array<Record<string, string>>).some(
+                (h) => typeof h.command === 'string' && h.command.includes('# cleo-hook'),
+              )
+            ),
+        );
+        if (filtered.length !== entries.length) {
+          hooks[event] = filtered;
+          changed = true;
+        }
+      }
+
+      if (changed) {
+        settings.hooks = hooks;
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+      }
+    } catch {
+      // Cleanup failure is non-fatal
+    }
   }
 
   /**
@@ -143,6 +258,15 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
     return this.registered;
   }
 
+  /**
+   * Get the project directory this hook provider was registered for.
+   *
+   * Returns null if hooks have not been registered yet.
+   */
+  getProjectDir(): string | null {
+    return this.projectDir;
+  }
+
   /**
    * Get the native→canonical event mapping for introspection and debugging.
    *

package/src/providers/claude-code/spawn.ts

@@ -74,8 +74,22 @@ export class ClaudeCodeSpawnProvider implements AdapterSpawnProvider {
     let tmpFile: string | undefined;
 
     try {
+      // Enrich prompt with CANT bundle, memory bridge, and mental model (T555).
+      // Best-effort: if CANT context is unavailable, the raw prompt is used.
+      let enrichedPrompt = context.prompt;
+      try {
+        const { buildCantEnrichedPrompt } = await import('../../cant-context.js');
+        enrichedPrompt = await buildCantEnrichedPrompt({
+          projectDir: context.workingDirectory ?? process.cwd(),
+          basePrompt: context.prompt,
+          agentName: (context.options?.agentName as string) ?? undefined,
+        });
+      } catch {
+        // CANT enrichment unavailable — use raw prompt
+      }
+
       tmpFile = `/tmp/claude-spawn-${instanceId}.txt`;
-      await writeFile(tmpFile, context.prompt, 'utf-8');
+      await writeFile(tmpFile, enrichedPrompt, 'utf-8');
 
       const args = ['--allow-insecure', '--no-upgrade-check', tmpFile];
       const spawnOpts: Parameters<typeof nodeSpawn>[2] = {

package/src/providers/opencode/spawn.ts

@@ -80,18 +80,23 @@ export function buildOpenCodeAgentMarkdown(description: string, instructions: st
  * @param workingDirectory - Project root directory
  * @returns The agent name to use for spawning
  */
-async function ensureSubagentDefinition(workingDirectory: string): Promise<string> {
+async function ensureSubagentDefinition(
+  workingDirectory: string,
+  enrichedInstructions?: string,
+): Promise<string> {
   const agentDir = join(workingDirectory, '.opencode', 'agent');
   const agentPath = join(agentDir, `${OPENCODE_SUBAGENT_NAME}.md`);
-  const description = 'CLEO task executor with protocol compliance.';
-  const instructions = [
-    '# CLEO Subagent',
-    '',
-    'You are a CLEO subagent executing a delegated task.',
-    'Follow the CLEO protocol and complete the assigned work.',
-    '',
-    '@~/.cleo/templates/CLEO-INJECTION.md',
-  ].join('\n');
+  const description = 'CLEO task executor with protocol compliance and CANT context.';
+  const instructions =
+    enrichedInstructions ??
+    [
+      '# CLEO Subagent',
+      '',
+      'You are a CLEO subagent executing a delegated task.',
+      'Follow the CLEO protocol and complete the assigned work.',
+      '',
+      '@~/.cleo/templates/CLEO-INJECTION.md',
+    ].join('\n');
 
   const content = buildOpenCodeAgentMarkdown(description, instructions);
 
@@ -160,9 +165,23 @@ export class OpenCodeSpawnProvider implements AdapterSpawnProvider {
     const workingDirectory = context.workingDirectory ?? process.cwd();
 
     try {
+      // Enrich prompt with CANT bundle, memory bridge, and mental model (T555).
+      // Best-effort: if CANT context is unavailable, the raw prompt is used.
+      let enrichedInstructions: string | undefined;
+      try {
+        const { buildCantEnrichedPrompt } = await import('../../cant-context.js');
+        enrichedInstructions = await buildCantEnrichedPrompt({
+          projectDir: workingDirectory,
+          basePrompt: context.prompt,
+          agentName: (context.options?.agentName as string) ?? undefined,
+        });
+      } catch {
+        // CANT enrichment unavailable — use raw prompt
+      }
+
       let agentName: string;
       try {
-        agentName = await ensureSubagentDefinition(workingDirectory);
+        agentName = await ensureSubagentDefinition(workingDirectory, enrichedInstructions);
       } catch {
         agentName = OPENCODE_FALLBACK_AGENT;
       }