@cleocode/adapters 2026.4.0 → 2026.4.2

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

@@ -94,8 +94,8 @@ describe('ClaudeCodeAdapter', () => {
       expect(adapter.capabilities.supportsInstall).toBe(true);
     });
 
-    it('supports MCP', () => {
-      expect(adapter.capabilities.supportsMcp).toBe(true);
+    it('does not support MCP (removed)', () => {
+      expect(adapter.capabilities.supportsMcp).toBe(false);
     });
 
     it('supports instruction files with CLAUDE.md pattern', () => {
@@ -103,10 +103,22 @@ describe('ClaudeCodeAdapter', () => {
       expect(adapter.capabilities.instructionFilePattern).toBe('CLAUDE.md');
     });
 
-    it('declares expected hook events', () => {
-      expect(adapter.capabilities.supportedHookEvents).toContain('onSessionStart');
-      expect(adapter.capabilities.supportedHookEvents).toContain('onSessionEnd');
-      expect(adapter.capabilities.supportedHookEvents).toContain('onToolComplete');
+    it('declares expected hook events (14 CAAMP canonical events)', () => {
+      expect(adapter.capabilities.supportedHookEvents).toContain('SessionStart');
+      expect(adapter.capabilities.supportedHookEvents).toContain('SessionEnd');
+      expect(adapter.capabilities.supportedHookEvents).toContain('PromptSubmit');
+      expect(adapter.capabilities.supportedHookEvents).toContain('ResponseComplete');
+      expect(adapter.capabilities.supportedHookEvents).toContain('PreToolUse');
+      expect(adapter.capabilities.supportedHookEvents).toContain('PostToolUse');
+      expect(adapter.capabilities.supportedHookEvents).toContain('PostToolUseFailure');
+      expect(adapter.capabilities.supportedHookEvents).toContain('PermissionRequest');
+      expect(adapter.capabilities.supportedHookEvents).toContain('SubagentStart');
+      expect(adapter.capabilities.supportedHookEvents).toContain('SubagentStop');
+      expect(adapter.capabilities.supportedHookEvents).toContain('PreCompact');
+      expect(adapter.capabilities.supportedHookEvents).toContain('PostCompact');
+      expect(adapter.capabilities.supportedHookEvents).toContain('Notification');
+      expect(adapter.capabilities.supportedHookEvents).toContain('ConfigChange');
+      expect(adapter.capabilities.supportedHookEvents).toHaveLength(14);
     });
   });
 
@@ -171,20 +183,28 @@ describe('ClaudeCodeHookProvider', () => {
   });
 
   describe('mapProviderEvent', () => {
-    it('maps SessionStart to onSessionStart', () => {
-      expect(hooks.mapProviderEvent('SessionStart')).toBe('onSessionStart');
+    it('maps SessionStart to SessionStart (identity)', () => {
+      expect(hooks.mapProviderEvent('SessionStart')).toBe('SessionStart');
     });
 
-    it('maps PostToolUse to onToolComplete', () => {
-      expect(hooks.mapProviderEvent('PostToolUse')).toBe('onToolComplete');
+    it('maps PostToolUse to PostToolUse (identity)', () => {
+      expect(hooks.mapProviderEvent('PostToolUse')).toBe('PostToolUse');
     });
 
-    it('maps UserPromptSubmit to onPromptSubmit', () => {
-      expect(hooks.mapProviderEvent('UserPromptSubmit')).toBe('onPromptSubmit');
+    it('maps UserPromptSubmit to PromptSubmit', () => {
+      expect(hooks.mapProviderEvent('UserPromptSubmit')).toBe('PromptSubmit');
     });
 
-    it('maps Stop to onSessionEnd', () => {
-      expect(hooks.mapProviderEvent('Stop')).toBe('onSessionEnd');
+    it('maps Stop to ResponseComplete', () => {
+      expect(hooks.mapProviderEvent('Stop')).toBe('ResponseComplete');
+    });
+
+    it('maps PreToolUse to PreToolUse (identity)', () => {
+      expect(hooks.mapProviderEvent('PreToolUse')).toBe('PreToolUse');
+    });
+
+    it('maps PermissionRequest to PermissionRequest (identity)', () => {
+      expect(hooks.mapProviderEvent('PermissionRequest')).toBe('PermissionRequest');
     });
 
     it('returns null for unknown events', () => {
@@ -210,13 +230,23 @@ describe('ClaudeCodeHookProvider', () => {
   });
 
   describe('getEventMap', () => {
-    it('returns all mapped events', () => {
+    it('returns all 14 mapped events', () => {
       const map = hooks.getEventMap();
-      expect(Object.keys(map)).toHaveLength(4);
-      expect(map.SessionStart).toBe('onSessionStart');
-      expect(map.PostToolUse).toBe('onToolComplete');
-      expect(map.UserPromptSubmit).toBe('onPromptSubmit');
-      expect(map.Stop).toBe('onSessionEnd');
+      expect(Object.keys(map)).toHaveLength(14);
+      expect(map.SessionStart).toBe('SessionStart');
+      expect(map.SessionEnd).toBe('SessionEnd');
+      expect(map.UserPromptSubmit).toBe('PromptSubmit');
+      expect(map.Stop).toBe('ResponseComplete');
+      expect(map.PreToolUse).toBe('PreToolUse');
+      expect(map.PostToolUse).toBe('PostToolUse');
+      expect(map.PostToolUseFailure).toBe('PostToolUseFailure');
+      expect(map.PermissionRequest).toBe('PermissionRequest');
+      expect(map.SubagentStart).toBe('SubagentStart');
+      expect(map.SubagentStop).toBe('SubagentStop');
+      expect(map.PreCompact).toBe('PreCompact');
+      expect(map.PostCompact).toBe('PostCompact');
+      expect(map.Notification).toBe('Notification');
+      expect(map.ConfigChange).toBe('ConfigChange');
     });
   });
 });
@@ -274,12 +304,11 @@ describe('ClaudeCodeInstallProvider', () => {
       expect(typeof result.mcpRegistered).toBe('boolean');
     });
 
-    it('registers MCP when mcpServerPath provided', async () => {
+    it('does not register MCP when only projectDir is provided', async () => {
       const result = await installProvider.install({
         projectDir: '/tmp/test-project',
-        mcpServerPath: '/path/to/mcp-server.js',
       });
-      expect(result.mcpRegistered).toBe(true);
+      expect(result.mcpRegistered).toBe(false);
     });
   });
 

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

@@ -33,13 +33,24 @@ const execAsync = promisify(exec);
  * Bridges CLEO's adapter system with Claude Code's native capabilities:
  * - Hooks: Maps Claude Code events (SessionStart, PostToolUse, etc.) to CAAMP events
  * - Spawn: Launches subagent processes via the `claude` CLI
- * - Install: Registers MCP server, instruction files, and brain observation plugin
+ * - Install: Manages instruction files and brain observation plugin registration
+ *
+ * @remarks
+ * This is the most feature-complete adapter in the CLEO system, supporting
+ * 14 of 16 CAAMP canonical events, subagent spawning via the `claude` CLI,
+ * context monitoring with statusline integration, task sync via TodoWrite,
+ * and inter-agent transport. It serves as the reference implementation for
+ * other provider adapters.
  */
 export class ClaudeCodeAdapter implements CLEOProviderAdapter {
+  /** Unique provider identifier. */
   readonly id = 'claude-code';
+  /** Human-readable provider name. */
   readonly name = 'Claude Code';
+  /** Adapter version string. */
   readonly version = '1.0.0';
 
+  /** Declared capabilities for this provider. */
   capabilities: AdapterCapabilities = {
     supportsHooks: true,
     // 14/16 canonical events — derived from getProviderHookProfile('claude-code') in CAAMP 1.9.1.
@@ -62,7 +73,7 @@ export class ClaudeCodeAdapter implements CLEOProviderAdapter {
     ],
     supportsSpawn: true,
     supportsInstall: true,
-    supportsMcp: true,
+    supportsMcp: false,
     supportsInstructionFiles: true,
     instructionFilePattern: 'CLAUDE.md',
     supportsContextMonitor: true,
@@ -72,15 +83,24 @@ export class ClaudeCodeAdapter implements CLEOProviderAdapter {
     supportsTaskSync: true,
   };
 
+  /** Hook provider for CAAMP event mapping and registration. */
   hooks: ClaudeCodeHookProvider;
+  /** Spawn provider for launching subagent processes via `claude` CLI. */
   spawn: ClaudeCodeSpawnProvider;
+  /** Install provider for managing instruction files and plugin registration. */
   install: ClaudeCodeInstallProvider;
+  /** Path provider for resolving Claude Code directory locations. */
   paths: ClaudeCodePathProvider;
+  /** Context monitor for tracking context window usage and statusline output. */
   contextMonitor: ClaudeCodeContextMonitorProvider;
+  /** Transport provider for inter-agent communication. */
   transport: ClaudeCodeTransportProvider;
+  /** Task sync provider bridging Claude's TodoWrite format to CLEO tasks. */
   taskSync: ClaudeCodeTaskSyncProvider;
 
+  /** Project directory this adapter was initialized with, or null. */
   private projectDir: string | null = null;
+  /** Whether {@link initialize} has been called. */
   private initialized = false;
 
   constructor() {

package/src/providers/claude-code/context-monitor.ts

@@ -51,10 +51,18 @@ function getContextStatusFromPercentage(percentage: number): ContextStatus {
  * Processes context window JSON from Claude Code and writes state files
  * for statusline display. Also provides statusline configuration
  * and setup instructions specific to Claude Code's settings.json.
+ *
+ * @remarks
+ * The provider writes a JSON state file to `.cleo/context-states/.context-state.json`
+ * which can be read by external statusline scripts (e.g. tmux, starship).
+ * Context thresholds at 50%, 70%, 85%, and 95% map to warning, caution,
+ * critical, and emergency status levels respectively.
  */
 export class ClaudeCodeContextMonitorProvider implements AdapterContextMonitorProvider {
+  /** Path provider for resolving Claude Code directory locations. */
   private pathProvider = new ClaudeCodePathProvider();
 
+  /** Process raw context window JSON and return a formatted summary string. */
   async processContextInput(input: unknown, cwd?: string): Promise<string> {
     const typed = input as ContextWindowInput;
     const contextSize = typed.context_window?.context_window_size ?? 200000;
@@ -113,6 +121,7 @@ export class ClaudeCodeContextMonitorProvider implements AdapterContextMonitorPr
     return `${percentage}% | ${totalTokens}/${contextSize}`;
   }
 
+  /** Check the current statusline integration status in Claude Code settings. */
   checkStatuslineIntegration(): 'configured' | 'not_configured' | 'custom_no_cleo' | 'no_settings' {
     const settingsPath = this.pathProvider.getSettingsPath();
     if (!settingsPath || !existsSync(settingsPath)) return 'no_settings';
@@ -151,6 +160,7 @@ export class ClaudeCodeContextMonitorProvider implements AdapterContextMonitorPr
     }
   }
 
+  /** Get the recommended statusline configuration object for Claude Code settings. */
   getStatuslineConfig(): Record<string, unknown> {
     return {
       statusLine: {
@@ -160,6 +170,7 @@ export class ClaudeCodeContextMonitorProvider implements AdapterContextMonitorPr
     };
   }
 
+  /** Get human-readable setup instructions for enabling context monitoring. */
   getSetupInstructions(): string {
     const settingsPath = this.pathProvider.getSettingsPath() ?? '~/.claude/settings.json';
 

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

@@ -78,10 +78,17 @@ const CLAUDE_CODE_EVENT_MAP: Record<string, string> = {
  * provider), `registerNativeHooks` and `unregisterNativeHooks` track registration
  * state without performing filesystem operations.
  *
+ * @remarks
+ * Claude Code is the only provider that supports all 14 of its declared
+ * canonical events at runtime. The static event map is maintained as a
+ * synchronous fallback; async methods like {@link getSupportedCanonicalEvents}
+ * and {@link getProviderProfile} call CAAMP directly when available.
+ *
  * @task T164
  * @epic T134
  */
 export class ClaudeCodeHookProvider implements AdapterHookProvider {
+  /** Whether hooks have been registered for the current session. */
   private registered = false;
 
   /**

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

@@ -1,5 +1,5 @@
 /**
- * Claude Code provider adapter.
+ * @packageDocumentation
  *
  * CLEO provider adapter for Anthropic Claude Code CLI.
  * Default export is the adapter class for dynamic loading by AdapterManager.
@@ -27,6 +27,21 @@ export default ClaudeCodeAdapter;
 /**
  * Factory function for creating adapter instances.
  * Used by AdapterManager's dynamic import fallback.
+ *
+ * @remarks
+ * This is the primary entry point for dynamic adapter loading.
+ * AdapterManager calls this function when it resolves the claude-code
+ * provider via its import-based discovery mechanism.
+ *
+ * @returns A new {@link ClaudeCodeAdapter} instance ready for initialization
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@cleocode/adapters/providers/claude-code';
+ *
+ * const adapter = createAdapter();
+ * await adapter.initialize('/path/to/project');
+ * ```
  */
 export function createAdapter(): ClaudeCodeAdapter {
   return new ClaudeCodeAdapter();

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

@@ -2,7 +2,6 @@
  * Claude Code Install Provider
  *
  * Handles CLEO installation into Claude Code environments:
- * - Registers CLEO MCP server in .mcp.json
  * - Ensures CLAUDE.md has CLEO @-references
  * - Manages plugin registration in ~/.claude/settings.json
  *
@@ -19,60 +18,49 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
 /** Lines that should appear in CLAUDE.md to reference CLEO. */
 const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
 
-/** MCP server registration key used in .mcp.json. */
-const MCP_SERVER_KEY = 'cleo';
-
 /**
  * Install provider for Claude Code.
  *
  * Manages CLEO's integration with Claude Code by:
- * 1. Registering the CLEO MCP server in the project's .mcp.json
- * 2. Ensuring CLAUDE.md contains @-references to CLEO instruction files
- * 3. Registering the brain observation plugin in ~/.claude/settings.json
+ * 1. Ensuring CLAUDE.md contains @-references to CLEO instruction files
+ * 2. Registering the brain observation plugin in ~/.claude/settings.json
+ *
+ * @remarks
+ * Installation is idempotent -- running install multiple times on the same
+ * project produces the same result. The provider disables the legacy
+ * `claude-mem\@thedotmack` plugin if present and enables the unified
+ * `cleo\@cleocode` plugin instead.
  */
 export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
-  private installedProjectDir: string | null = null;
-
   /**
    * Install CLEO into a Claude Code project.
    *
-   * @param options - Installation options including project directory and MCP server path
+   * @param options - Installation options including project directory
    * @returns Result describing what was installed
    */
   async install(options: InstallOptions): Promise<InstallResult> {
-    const { projectDir, mcpServerPath } = options;
+    const { projectDir } = options;
     const installedAt = new Date().toISOString();
     let instructionFileUpdated = false;
-    let mcpRegistered = false;
     const details: Record<string, unknown> = {};
 
-    // Step 1: Register MCP server in .mcp.json
-    if (mcpServerPath) {
-      mcpRegistered = this.registerMcpServer(projectDir, mcpServerPath);
-      if (mcpRegistered) {
-        details.mcpConfigPath = join(projectDir, '.mcp.json');
-      }
-    }
-
-    // Step 2: Ensure CLAUDE.md has @-references
+    // Step 1: Ensure CLAUDE.md has @-references
     instructionFileUpdated = this.updateInstructionFile(projectDir);
     if (instructionFileUpdated) {
       details.instructionFile = join(projectDir, 'CLAUDE.md');
     }
 
-    // Step 3: Register plugin in ~/.claude/settings.json
+    // Step 2: Register plugin in ~/.claude/settings.json
     const pluginResult = this.registerPlugin();
     if (pluginResult) {
       details.plugin = pluginResult;
     }
 
-    this.installedProjectDir = projectDir;
-
     return {
       success: true,
       installedAt,
       instructionFileUpdated,
-      mcpRegistered,
+      mcpRegistered: false,
       details,
     };
   }
@@ -80,38 +68,14 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
   /**
    * Uninstall CLEO from the current Claude Code project.
    *
-   * Removes the MCP server registration from .mcp.json.
    * Does not remove CLAUDE.md references (they are harmless if CLEO is not present).
    */
-  async uninstall(): Promise<void> {
-    if (!this.installedProjectDir) return;
-
-    const mcpPath = join(this.installedProjectDir, '.mcp.json');
-    if (existsSync(mcpPath)) {
-      try {
-        const raw = readFileSync(mcpPath, 'utf-8');
-        const config = JSON.parse(raw) as Record<string, unknown>;
-        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
-        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
-          delete mcpServers[MCP_SERVER_KEY];
-          writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-        }
-      } catch {
-        // Ignore errors during uninstall
-      }
-    }
-
-    this.installedProjectDir = null;
-  }
+  async uninstall(): Promise<void> {}
 
   /**
    * Check whether CLEO is installed in the current environment.
    *
-   * Checks for:
-   * 1. MCP server registered in .mcp.json
-   * 2. Plugin enabled in ~/.claude/settings.json
-   *
-   * Returns true if either condition is met (partial install counts).
+   * Checks for plugin enabled in ~/.claude/settings.json.
    */
   async isInstalled(): Promise<boolean> {
     // Check ~/.claude/settings.json for plugin registration
@@ -128,20 +92,6 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       }
     }
 
-    // Check current directory for .mcp.json with cleo server
-    const mcpPath = join(process.cwd(), '.mcp.json');
-    if (existsSync(mcpPath)) {
-      try {
-        const config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
-        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
-        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
-          return true;
-        }
-      } catch {
-        // Fall through
-      }
-    }
-
     return false;
   }
 
@@ -156,37 +106,6 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
     this.updateInstructionFile(projectDir);
   }
 
-  /**
-   * Register the CLEO MCP server in .mcp.json.
-   *
-   * @returns true if registration was performed or updated
-   */
-  private registerMcpServer(projectDir: string, mcpServerPath: string): boolean {
-    const mcpPath = join(projectDir, '.mcp.json');
-    let config: Record<string, unknown> = {};
-
-    if (existsSync(mcpPath)) {
-      try {
-        config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
-      } catch {
-        // Start fresh on parse error
-      }
-    }
-
-    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
-      config.mcpServers = {};
-    }
-
-    const mcpServers = config.mcpServers as Record<string, unknown>;
-    mcpServers[MCP_SERVER_KEY] = {
-      command: 'node',
-      args: [mcpServerPath],
-    };
-
-    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-    return true;
-  }
-
   /**
    * Update CLAUDE.md with CLEO @-references.
    *

package/src/providers/claude-code/manifest.json

@@ -10,7 +10,7 @@
     "supportedHookEvents": ["onSessionStart", "onSessionEnd", "onToolStart", "onToolComplete", "onError"],
     "supportsSpawn": true,
     "supportsInstall": true,
-    "supportsMcp": true,
+    "supportsMcp": false,
     "supportsInstructionFiles": true,
     "instructionFilePattern": "CLAUDE.md",
     "supportsContextMonitor": true,

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

@@ -18,20 +18,28 @@ import type { AdapterPathProvider } from '@cleocode/contracts';
  * - Settings: ~/.claude/settings.json (or CLAUDE_SETTINGS)
  * - Agents: ~/.claude/agents
  * - Memory DB: ~/.claude-mem/claude-mem.db (or CLAUDE_MEM_DB)
+ *
+ * @remarks
+ * All paths respect environment variable overrides for CI and non-standard
+ * installations. When env vars are unset, the canonical default paths are used.
  */
 export class ClaudeCodePathProvider implements AdapterPathProvider {
+  /** Get the provider's root configuration directory. */
   getProviderDir(): string {
     return process.env['CLAUDE_HOME'] ?? join(homedir(), '.claude');
   }
 
+  /** Get the path to the provider's settings file, or null if unavailable. */
   getSettingsPath(): string | null {
     return process.env['CLAUDE_SETTINGS'] ?? join(this.getProviderDir(), 'settings.json');
   }
 
+  /** Get the directory where agents are installed, or null if unsupported. */
   getAgentInstallDir(): string | null {
     return join(this.getProviderDir(), 'agents');
   }
 
+  /** Get the path to the provider's memory database, or null if unsupported. */
   getMemoryDbPath(): string | null {
     return process.env['CLAUDE_MEM_DB'] ?? join(homedir(), '.claude-mem', 'claude-mem.db');
   }

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

@@ -33,6 +33,13 @@ interface TrackedProcess {
  * Each spawn writes its prompt to a temporary file, then runs
  * `claude --allow-insecure --no-upgrade-check <tmpFile>` as a
  * detached, unref'd child process.
+ *
+ * @remarks
+ * The provider uses `--allow-insecure --no-upgrade-check` flags to
+ * ensure the Claude CLI starts without interactive prompts. Prompts are
+ * written to temporary files under `/tmp/` and cleaned up after the
+ * child process exits. Processes are tracked by instance ID in an
+ * in-memory map and verified via `kill(pid, 0)` liveness checks.
  */
 export class ClaudeCodeSpawnProvider implements AdapterSpawnProvider {
   /** Map of instance IDs to tracked process info. */

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

@@ -27,6 +27,22 @@ function getClaudeSettingsPath(): string {
 /**
  * Check if statusline integration is configured.
  * Returns the current integration status.
+ *
+ * @remarks
+ * Reads Claude Code's settings.json and inspects the `statusLine` field
+ * to determine whether CLEO context monitoring is active.
+ *
+ * @returns One of: 'configured', 'not_configured', 'custom_no_cleo', 'no_settings'
+ *
+ * @example
+ * ```typescript
+ * import { checkStatuslineIntegration } from './statusline.js';
+ *
+ * const status = checkStatuslineIntegration();
+ * if (status === 'not_configured') {
+ *   console.log('Run cleo install to set up context monitoring');
+ * }
+ * ```
  */
 export function checkStatuslineIntegration(): StatuslineStatus {
   const settingsPath = getClaudeSettingsPath();
@@ -72,6 +88,20 @@ export function checkStatuslineIntegration(): StatuslineStatus {
 
 /**
  * Get the statusline setup command for Claude Code settings.
+ *
+ * @remarks
+ * Returns a JSON-serializable object that can be merged into
+ * Claude Code's settings.json to enable context monitoring.
+ *
+ * @param cleoHome - Absolute path to the CLEO home directory
+ * @returns Settings object containing the statusLine configuration
+ *
+ * @example
+ * ```typescript
+ * import { getStatuslineConfig } from './statusline.js';
+ *
+ * const config = getStatuslineConfig('/home/user/.cleo');
+ * ```
  */
 export function getStatuslineConfig(cleoHome: string): Record<string, unknown> {
   return {
@@ -84,6 +114,20 @@ export function getStatuslineConfig(cleoHome: string): Record<string, unknown> {
 
 /**
  * Get human-readable setup instructions.
+ *
+ * @remarks
+ * Returns a multi-line string with file path, JSON config, and explanation
+ * suitable for display to the user.
+ *
+ * @param cleoHome - Absolute path to the CLEO home directory
+ * @returns Formatted setup instructions string
+ *
+ * @example
+ * ```typescript
+ * import { getSetupInstructions } from './statusline.js';
+ *
+ * console.log(getSetupInstructions('/home/user/.cleo'));
+ * ```
  */
 export function getSetupInstructions(cleoHome: string): string {
   const settingsPath = getClaudeSettingsPath();

package/src/providers/claude-code/task-sync.ts

@@ -82,14 +82,22 @@ function getTodoWriteFilePath(projectDir: string): string {
  * and status, and returns normalized ExternalTask[].
  *
  * Optional: accepts a custom file path for testing.
+ *
+ * @remarks
+ * TodoWrite items with `[T001]`-style prefixes are mapped to their CLEO
+ * task IDs. Items without a prefix receive a synthetic `tw-new-N` ID
+ * for reconciliation. The provider reads from
+ * `.cleo/sync/todowrite-state.json` by default.
  */
 export class ClaudeCodeTaskSyncProvider implements ExternalTaskProvider {
+  /** Optional override path for the TodoWrite state file (used in tests). */
   private readonly customFilePath?: string;
 
   constructor(options?: { filePath?: string }) {
     this.customFilePath = options?.filePath;
   }
 
+  /** Retrieve external tasks from Claude's TodoWrite state file. */
   async getExternalTasks(projectDir: string): Promise<ExternalTask[]> {
     const filePath = this.customFilePath ?? getTodoWriteFilePath(projectDir);
 

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

@@ -9,9 +9,20 @@
 
 import type { AdapterTransportProvider } from '@cleocode/contracts';
 
+/**
+ * Transport provider for Claude Code inter-agent communication.
+ *
+ * @remarks
+ * Currently returns null from {@link createTransport} because actual transport
+ * creation is handled by the signaldock factory which checks for this adapter's
+ * transport capability flag. Full wiring will be completed in Phase 5 of the
+ * adapter system rollout.
+ */
 export class ClaudeCodeTransportProvider implements AdapterTransportProvider {
+  /** Provider-specific transport name used for capability negotiation. */
   readonly transportName = 'claude-code';
 
+  /** Create a transport instance for inter-agent messaging. */
   createTransport(): unknown {
     // Returns null — actual transport creation is handled by the signaldock factory
     // which checks for this adapter's transport capability.

package/src/providers/codex/adapter.ts

@@ -28,22 +28,31 @@ const execAsync = promisify(exec);
  *
  * Bridges CLEO's adapter system with Codex CLI's native capabilities:
  * - Hooks: Maps Codex events (SessionStart, PromptSubmit, ResponseComplete) to CAAMP events
- * - Install: Registers MCP server in ~/.codex/config.json and ensures AGENTS.md references
+ * - Install: Ensures AGENTS.md references for CLEO instruction files
+ *
+ * @remarks
+ * Codex CLI supports only 3 canonical events (SessionStart, PromptSubmit,
+ * ResponseComplete) and has no spawn or transport capabilities. Integration
+ * is primarily through instruction files (AGENTS.md).
  *
  * @task T162
  * @epic T134
  */
 export class CodexAdapter implements CLEOProviderAdapter {
+  /** Unique provider identifier. */
   readonly id = 'codex';
+  /** Human-readable provider name. */
   readonly name = 'Codex';
+  /** Adapter version string. */
   readonly version = '1.0.0';
 
+  /** Declared capabilities for this provider. */
   capabilities: AdapterCapabilities = {
     supportsHooks: true,
     supportedHookEvents: ['SessionStart', 'UserPromptSubmit', 'Stop'],
     supportsSpawn: false,
     supportsInstall: true,
-    supportsMcp: true,
+    supportsMcp: false,
     supportsInstructionFiles: false,
     supportsContextMonitor: false,
     supportsStatusline: false,
@@ -52,10 +61,14 @@ export class CodexAdapter implements CLEOProviderAdapter {
     supportsTaskSync: false,
   };
 
+  /** Hook provider for CAAMP event mapping. */
   hooks: CodexHookProvider;
+  /** Install provider for managing instruction files. */
   install: CodexInstallProvider;
 
+  /** Project directory this adapter was initialized with, or null. */
   private projectDir: string | null = null;
+  /** Whether {@link initialize} has been called. */
   private initialized = false;
 
   constructor() {