@cleocode/adapters 2026.4.67 → 2026.4.68

package/dist/providers/codex/index.d.ts

@@ -11,6 +11,7 @@ import { CodexAdapter } from './adapter.js';
 export { CodexAdapter } from './adapter.js';
 export { CodexHookProvider } from './hooks.js';
 export { CodexInstallProvider } from './install.js';
+export { CodexSpawnProvider } from './spawn.js';
 export default CodexAdapter;
 /**
  * Factory function for creating adapter instances.

package/dist/providers/codex/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,eAAe,YAAY,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAE5C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAe,YAAY,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAE5C"}

package/dist/providers/codex/spawn.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Codex CLI Spawn Provider
+ *
+ * Implements `AdapterSpawnProvider` for the OpenAI Codex CLI (`codex` binary).
+ *
+ * The `codex` binary is the OpenAI Codex CLI agent, available at:
+ * https://github.com/openai/codex
+ *
+ * Invocation: `codex --full-auto <prompt-file>`
+ *
+ * The provider uses `--full-auto` (non-interactive, auto-approve all actions)
+ * which is the headless equivalent of the Claude Code `--dangerously-skip-permissions`
+ * flag. Processes run detached and are tracked by PID for listing and termination.
+ *
+ * If the `codex` binary is not found, `canSpawn()` returns `false` with a
+ * graceful error — no crash.
+ *
+ * @remarks
+ * As of 2026, the Codex CLI is the successor to the original OpenAI Codex
+ * playground. It reads prompts from stdin or file arguments and emits output
+ * to stdout. The `--full-auto` flag suppresses interactive approval prompts.
+ * Install: `npm install -g @openai/codex` or see the GitHub repo above.
+ *
+ * @task T648
+ */
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+/**
+ * Spawn provider for the OpenAI Codex CLI.
+ *
+ * Spawns detached Codex CLI processes for subagent execution. Each spawn
+ * writes its prompt to a temporary file, then runs
+ * `codex --full-auto <tmpFile>` as a detached, unref'd child process.
+ *
+ * @remarks
+ * `canSpawn()` returns `false` (with no crash) when the `codex` binary is
+ * not found in PATH. Install instructions are emitted via `console.warn`
+ * once to help operators discover the binary is missing.
+ *
+ * Processes are tracked by instance ID in an in-memory map and verified
+ * via `kill(pid, 0)` liveness checks.
+ *
+ * @task T648
+ */
+export declare class CodexSpawnProvider implements AdapterSpawnProvider {
+    /** Map of instance IDs to tracked process info. */
+    private processMap;
+    /**
+     * Check if the Codex CLI is available in PATH.
+     *
+     * @returns `true` if `codex` is found via `which`
+     */
+    canSpawn(): Promise<boolean>;
+    /**
+     * Spawn a subagent via the Codex CLI.
+     *
+     * Writes the prompt to a temporary file and spawns a detached Codex
+     * process. The process runs independently of the parent.
+     *
+     * @param context - Spawn context with taskId, prompt, and options
+     * @returns Spawn result with instance ID and status
+     */
+    spawn(context: SpawnContext): Promise<SpawnResult>;
+    /**
+     * List currently running Codex subagent processes.
+     *
+     * Checks each tracked process via kill(pid, 0) to verify it is still alive.
+     * Dead processes are automatically cleaned from the tracking map.
+     *
+     * @returns Array of spawn results for running processes
+     */
+    listRunning(): Promise<SpawnResult[]>;
+    /**
+     * Terminate a running spawn by instance ID.
+     *
+     * Sends SIGTERM to the tracked process. If the process is not found
+     * or has already exited, this is a no-op.
+     *
+     * @param instanceId - ID of the spawn instance to terminate
+     */
+    terminate(instanceId: string): Promise<void>;
+}
+//# sourceMappingURL=spawn.d.ts.map

package/dist/providers/codex/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAY3F;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAmB,YAAW,oBAAoB;IAC7D,mDAAmD;IACnD,OAAO,CAAC,UAAU,CAAqC;IAEvD;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAclC;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAqFxD;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAqB3C;;;;;;;OAOG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAWnD"}

package/dist/providers/gemini-cli/index.d.ts

@@ -11,6 +11,7 @@ import { GeminiCliAdapter } from './adapter.js';
 export { GeminiCliAdapter } from './adapter.js';
 export { GeminiCliHookProvider } from './hooks.js';
 export { GeminiCliInstallProvider } from './install.js';
+export { GeminiCliSpawnProvider } from './spawn.js';
 export default GeminiCliAdapter;
 /**
  * Factory function for creating adapter instances.

package/dist/providers/gemini-cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/gemini-cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,eAAe,gBAAgB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,CAEhD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/gemini-cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAe,gBAAgB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,CAEhD"}

package/dist/providers/gemini-cli/spawn.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Gemini CLI Spawn Provider
+ *
+ * Implements `AdapterSpawnProvider` for the Google Gemini CLI (`gemini` binary).
+ *
+ * The `gemini` binary is the Google Gemini CLI agent, available at:
+ * https://github.com/google-gemini/gemini-cli
+ *
+ * Invocation: `gemini --yolo < <prompt-file>`
+ *
+ * The provider pipes the prompt via stdin using the `--yolo` flag, which
+ * enables non-interactive mode (auto-approve all actions). Processes run
+ * detached and are tracked by PID for listing and termination.
+ *
+ * If the `gemini` binary is not found, `canSpawn()` returns `false` with a
+ * graceful error — no crash.
+ *
+ * @remarks
+ * The Gemini CLI supports a `--model` flag to select the model family and a
+ * `--yolo` flag for non-interactive headless execution (equivalent to Claude
+ * Code's `--dangerously-skip-permissions`). Prompts are supplied via stdin
+ * when run in `--yolo` mode. Install: `npm install -g @google/gemini-cli`
+ * or see the GitHub repo above.
+ *
+ * @task T648
+ */
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+/**
+ * Spawn provider for the Google Gemini CLI.
+ *
+ * Spawns detached Gemini CLI processes for subagent execution. Each spawn
+ * pipes its prompt via stdin, then runs
+ * `gemini --yolo --model <model>` as a detached, unref'd child process.
+ *
+ * @remarks
+ * `canSpawn()` returns `false` (with no crash) when the `gemini` binary is
+ * not found in PATH. Install instructions are emitted via `console.warn`
+ * once to help operators discover the binary is missing.
+ *
+ * Processes are tracked by instance ID in an in-memory map and verified
+ * via `kill(pid, 0)` liveness checks.
+ *
+ * @task T648
+ */
+export declare class GeminiCliSpawnProvider implements AdapterSpawnProvider {
+    /** Map of instance IDs to tracked process info. */
+    private processMap;
+    /**
+     * Check if the Gemini CLI is available in PATH.
+     *
+     * @returns `true` if `gemini` is found via `which`
+     */
+    canSpawn(): Promise<boolean>;
+    /**
+     * Spawn a subagent via the Gemini CLI.
+     *
+     * Pipes the enriched prompt to stdin and spawns a detached Gemini
+     * process. The process runs independently of the parent.
+     *
+     * @param context - Spawn context with taskId, prompt, and options
+     * @returns Spawn result with instance ID and status
+     */
+    spawn(context: SpawnContext): Promise<SpawnResult>;
+    /**
+     * List currently running Gemini CLI subagent processes.
+     *
+     * Checks each tracked process via kill(pid, 0) to verify it is still alive.
+     * Dead processes are automatically cleaned from the tracking map.
+     *
+     * @returns Array of spawn results for running processes
+     */
+    listRunning(): Promise<SpawnResult[]>;
+    /**
+     * Terminate a running spawn by instance ID.
+     *
+     * Sends SIGTERM to the tracked process. If the process is not found
+     * or has already exited, this is a no-op.
+     *
+     * @param instanceId - ID of the spawn instance to terminate
+     */
+    terminate(instanceId: string): Promise<void>;
+}
+//# sourceMappingURL=spawn.d.ts.map

package/dist/providers/gemini-cli/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../src/providers/gemini-cli/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAe3F;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,mDAAmD;IACnD,OAAO,CAAC,UAAU,CAAqC;IAEvD;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAclC;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IA8ExD;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAqB3C;;;;;;;OAOG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAWnD"}

package/dist/providers/kimi/index.d.ts

@@ -11,6 +11,7 @@ import { KimiAdapter } from './adapter.js';
 export { KimiAdapter } from './adapter.js';
 export { KimiHookProvider } from './hooks.js';
 export { KimiInstallProvider } from './install.js';
+export { KimiSpawnProvider } from './spawn.js';
 export default KimiAdapter;
 /**
  * Factory function for creating adapter instances.

package/dist/providers/kimi/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/kimi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,eAAe,WAAW,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,IAAI,WAAW,CAE3C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/kimi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAe,WAAW,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,IAAI,WAAW,CAE3C"}

package/dist/providers/kimi/spawn.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Kimi (Moonshot AI) Spawn Provider
+ *
+ * Implements `AdapterSpawnProvider` for Moonshot AI's Kimi models.
+ *
+ * There is no widely-distributed standalone Kimi CLI binary. This provider
+ * uses the Moonshot AI Chat Completions API directly (REST, no extra SDK
+ * dependency) when `MOONSHOT_API_KEY` is present in the environment.
+ *
+ * API documentation: https://platform.moonshot.cn/docs/api/chat
+ * Endpoint: https://api.moonshot.cn/v1/chat/completions
+ *
+ * `canSpawn()` returns `true` only when:
+ * 1. `MOONSHOT_API_KEY` is set in the environment, OR
+ * 2. A `kimi` binary is found in PATH (future CLI support)
+ *
+ * If neither condition holds, `canSpawn()` returns `false` with a clear
+ * message — no crash.
+ *
+ * @remarks
+ * Unlike the CLI-based providers (codex, gemini-cli), Kimi spawn runs the
+ * API call to completion before returning (`status: 'completed'` or
+ * `status: 'failed'`). This mirrors the claude-sdk and openai-sdk providers.
+ * The API call uses Node's built-in `fetch` (Node 18+) with no extra
+ * dependencies.
+ *
+ * @task T648
+ */
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+/**
+ * Spawn provider for Moonshot AI Kimi.
+ *
+ * Uses the Moonshot AI Chat Completions REST API to run subagent prompts.
+ * Each `spawn()` call completes synchronously (awaits the API response) and
+ * returns `status: 'completed'` or `status: 'failed'`.
+ *
+ * In-flight runs are tracked by instance ID so `listRunning()` reflects
+ * concurrent spawns correctly.
+ *
+ * @remarks
+ * `canSpawn()` checks for `MOONSHOT_API_KEY` first (API mode), then falls
+ * back to checking for a `kimi` CLI binary (CLI mode, future). If neither is
+ * available, `canSpawn()` returns `false` and `spawn()` throws a descriptive
+ * error rather than crashing silently.
+ *
+ * @task T648
+ */
+export declare class KimiSpawnProvider implements AdapterSpawnProvider {
+    /** In-flight run tracking set. */
+    private readonly runningInstances;
+    /**
+     * Check whether Kimi spawning is available in the current environment.
+     *
+     * Returns `true` when either:
+     * - `MOONSHOT_API_KEY` is set (API mode), or
+     * - A `kimi` binary is found in PATH (CLI mode — future)
+     *
+     * @returns `true` when any Kimi access method is available
+     */
+    canSpawn(): Promise<boolean>;
+    /**
+     * Spawn a subagent via the Moonshot AI Kimi API.
+     *
+     * Enriches the prompt with CANT context (best-effort), then calls
+     * the Moonshot Chat Completions API. The call is awaited to completion.
+     *
+     * @param context - Spawn context with taskId, prompt, and options
+     * @returns Resolved spawn result with `status: 'completed'` or `'failed'`
+     */
+    spawn(context: SpawnContext): Promise<SpawnResult>;
+    /**
+     * List currently in-flight Kimi API calls.
+     *
+     * Because each `spawn()` call awaits the API response, this list is
+     * typically empty unless concurrent spawns are in flight.
+     *
+     * @returns Array of in-progress spawn results
+     */
+    listRunning(): Promise<SpawnResult[]>;
+    /**
+     * Remove an instance from the running-instances tracking map.
+     *
+     * The underlying fetch call cannot be cancelled externally once started.
+     * This method removes the entry so it will no longer appear in
+     * `listRunning()`, but does not abort the in-progress HTTP request.
+     *
+     * @param instanceId - ID of the spawn instance to terminate
+     */
+    terminate(instanceId: string): Promise<void>;
+}
+//# sourceMappingURL=spawn.d.ts.map

package/dist/providers/kimi/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../src/providers/kimi/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AA8D3F;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,YAAW,oBAAoB;IAC5D,kCAAkC;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAiC;IAElE;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAYlC;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAkGxD;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAU3C;;;;;;;;OAQG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.4.67",
+  "version": "2026.4.68",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -14,8 +14,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.108",
     "@openai/agents": "0.8.3",
-    "@cleocode/caamp": "2026.4.67",
-    "@cleocode/contracts": "2026.4.67"
+    "@cleocode/caamp": "2026.4.68",
+    "@cleocode/contracts": "2026.4.68"
   },
   "license": "MIT",
   "engines": {

package/src/providers/codex/index.ts

@@ -13,6 +13,7 @@ import { CodexAdapter } from './adapter.js';
 export { CodexAdapter } from './adapter.js';
 export { CodexHookProvider } from './hooks.js';
 export { CodexInstallProvider } from './install.js';
+export { CodexSpawnProvider } from './spawn.js';
 
 export default CodexAdapter;
 

package/src/providers/codex/spawn.ts

@@ -0,0 +1,224 @@
+/**
+ * Codex CLI Spawn Provider
+ *
+ * Implements `AdapterSpawnProvider` for the OpenAI Codex CLI (`codex` binary).
+ *
+ * The `codex` binary is the OpenAI Codex CLI agent, available at:
+ * https://github.com/openai/codex
+ *
+ * Invocation: `codex --full-auto <prompt-file>`
+ *
+ * The provider uses `--full-auto` (non-interactive, auto-approve all actions)
+ * which is the headless equivalent of the Claude Code `--dangerously-skip-permissions`
+ * flag. Processes run detached and are tracked by PID for listing and termination.
+ *
+ * If the `codex` binary is not found, `canSpawn()` returns `false` with a
+ * graceful error — no crash.
+ *
+ * @remarks
+ * As of 2026, the Codex CLI is the successor to the original OpenAI Codex
+ * playground. It reads prompts from stdin or file arguments and emits output
+ * to stdout. The `--full-auto` flag suppresses interactive approval prompts.
+ * Install: `npm install -g @openai/codex` or see the GitHub repo above.
+ *
+ * @task T648
+ */
+
+import { exec, spawn as nodeSpawn } from 'node:child_process';
+import { unlink, writeFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+import { getErrorMessage } from '@cleocode/contracts';
+
+const execAsync = promisify(exec);
+
+/** Internal tracking entry for a spawned process. */
+interface TrackedProcess {
+  pid: number;
+  taskId: string;
+  startTime: string;
+}
+
+/**
+ * Spawn provider for the OpenAI Codex CLI.
+ *
+ * Spawns detached Codex CLI processes for subagent execution. Each spawn
+ * writes its prompt to a temporary file, then runs
+ * `codex --full-auto <tmpFile>` as a detached, unref'd child process.
+ *
+ * @remarks
+ * `canSpawn()` returns `false` (with no crash) when the `codex` binary is
+ * not found in PATH. Install instructions are emitted via `console.warn`
+ * once to help operators discover the binary is missing.
+ *
+ * Processes are tracked by instance ID in an in-memory map and verified
+ * via `kill(pid, 0)` liveness checks.
+ *
+ * @task T648
+ */
+export class CodexSpawnProvider implements AdapterSpawnProvider {
+  /** Map of instance IDs to tracked process info. */
+  private processMap = new Map<string, TrackedProcess>();
+
+  /**
+   * Check if the Codex CLI is available in PATH.
+   *
+   * @returns `true` if `codex` is found via `which`
+   */
+  async canSpawn(): Promise<boolean> {
+    try {
+      await execAsync('which codex');
+      return true;
+    } catch {
+      console.warn(
+        '[CodexSpawnProvider] codex CLI not found. ' +
+          'Install: npm install -g @openai/codex  ' +
+          'Docs: https://github.com/openai/codex',
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Spawn a subagent via the Codex CLI.
+   *
+   * Writes the prompt to a temporary file and spawns a detached Codex
+   * process. The process runs independently of the parent.
+   *
+   * @param context - Spawn context with taskId, prompt, and options
+   * @returns Spawn result with instance ID and status
+   */
+  async spawn(context: SpawnContext): Promise<SpawnResult> {
+    const instanceId = `codex-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    const startTime = new Date().toISOString();
+    let tmpFile: string | undefined;
+
+    try {
+      // Enrich prompt with CANT bundle, memory bridge, and mental model.
+      // 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/codex-spawn-${instanceId}.txt`;
+      await writeFile(tmpFile, enrichedPrompt, 'utf-8');
+
+      // --full-auto: non-interactive batch mode (auto-approve all actions)
+      const args = ['--full-auto', tmpFile];
+      const spawnOpts: Parameters<typeof nodeSpawn>[2] = {
+        detached: true,
+        stdio: 'ignore',
+      };
+
+      if (context.workingDirectory) {
+        spawnOpts.cwd = context.workingDirectory;
+      }
+
+      const child = nodeSpawn('codex', args, spawnOpts);
+      child.unref();
+
+      if (child.pid) {
+        this.processMap.set(instanceId, {
+          pid: child.pid,
+          taskId: context.taskId,
+          startTime,
+        });
+      }
+
+      const capturedTmpFile = tmpFile;
+      child.on('exit', async () => {
+        this.processMap.delete(instanceId);
+        try {
+          await unlink(capturedTmpFile);
+        } catch {
+          // Ignore cleanup errors
+        }
+      });
+
+      return {
+        instanceId,
+        taskId: context.taskId,
+        providerId: 'codex',
+        status: 'running',
+        startTime,
+      };
+    } catch (error) {
+      console.error(`[CodexSpawnProvider] Failed to spawn: ${getErrorMessage(error)}`);
+
+      if (tmpFile) {
+        try {
+          await unlink(tmpFile);
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+
+      return {
+        instanceId,
+        taskId: context.taskId,
+        providerId: 'codex',
+        status: 'failed',
+        startTime,
+        endTime: new Date().toISOString(),
+        error: getErrorMessage(error),
+      };
+    }
+  }
+
+  /**
+   * List currently running Codex subagent processes.
+   *
+   * Checks each tracked process via kill(pid, 0) to verify it is still alive.
+   * Dead processes are automatically cleaned from the tracking map.
+   *
+   * @returns Array of spawn results for running processes
+   */
+  async listRunning(): Promise<SpawnResult[]> {
+    const running: SpawnResult[] = [];
+
+    for (const [instanceId, tracked] of this.processMap.entries()) {
+      try {
+        process.kill(tracked.pid, 0);
+        running.push({
+          instanceId,
+          taskId: tracked.taskId,
+          providerId: 'codex',
+          status: 'running',
+          startTime: tracked.startTime,
+        });
+      } catch {
+        this.processMap.delete(instanceId);
+      }
+    }
+
+    return running;
+  }
+
+  /**
+   * Terminate a running spawn by instance ID.
+   *
+   * Sends SIGTERM to the tracked process. If the process is not found
+   * or has already exited, this is a no-op.
+   *
+   * @param instanceId - ID of the spawn instance to terminate
+   */
+  async terminate(instanceId: string): Promise<void> {
+    const tracked = this.processMap.get(instanceId);
+    if (!tracked) return;
+
+    try {
+      process.kill(tracked.pid, 'SIGTERM');
+    } catch {
+      // Process may have already exited
+    }
+    this.processMap.delete(instanceId);
+  }
+}

package/src/providers/gemini-cli/index.ts

@@ -13,6 +13,7 @@ import { GeminiCliAdapter } from './adapter.js';
 export { GeminiCliAdapter } from './adapter.js';
 export { GeminiCliHookProvider } from './hooks.js';
 export { GeminiCliInstallProvider } from './install.js';
+export { GeminiCliSpawnProvider } from './spawn.js';
 
 export default GeminiCliAdapter;