@cleocode/adapters 2026.4.47 → 2026.4.48

package/dist/providers/openai-sdk/install.d.ts

@@ -0,0 +1,61 @@
+/**
+ * OpenAI SDK Install Provider.
+ *
+ * Handles CLEO installation into OpenAI SDK environments:
+ * - Writes an AGENTS.md file with CLEO @-references
+ * - Creates a `.openai/` config stub if it does not exist
+ *
+ * @task T582
+ */
+import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+/**
+ * Install provider for the OpenAI Agents SDK.
+ *
+ * Manages CLEO's integration with OpenAI SDK projects by:
+ * 1. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ * 2. Creating the `.openai/` config directory stub if absent
+ *
+ * @remarks
+ * Installation is idempotent — running install multiple times on the same
+ * project produces the same result.
+ */
+export declare class OpenAiSdkInstallProvider implements AdapterInstallProvider {
+    /**
+     * Install CLEO into an OpenAI SDK project.
+     *
+     * @param options - Installation options including project directory.
+     * @returns Result describing what was installed.
+     */
+    install(options: InstallOptions): Promise<InstallResult>;
+    /**
+     * Uninstall CLEO from the current OpenAI SDK project.
+     *
+     * Does not remove AGENTS.md references (they are harmless if CLEO is absent).
+     */
+    uninstall(): Promise<void>;
+    /**
+     * Check whether CLEO is installed in the current OpenAI SDK environment.
+     *
+     * Checks for `@~/.cleo/templates/CLEO-INJECTION.md` in AGENTS.md.
+     */
+    isInstalled(): Promise<boolean>;
+    /**
+     * Ensure AGENTS.md contains @-references to CLEO instruction files.
+     *
+     * @param projectDir - Project root directory.
+     */
+    ensureInstructionReferences(projectDir: string): Promise<void>;
+    /**
+     * Update AGENTS.md with CLEO @-references.
+     *
+     * @returns `true` if the file was created or modified.
+     */
+    private updateInstructionFile;
+    /**
+     * Create the `.openai/` config directory if it does not exist.
+     *
+     * @returns `true` if the directory was created.
+     */
+    private ensureConfigDir;
+}
+//# sourceMappingURL=install.d.ts.map

package/dist/providers/openai-sdk/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-sdk/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKjG;;;;;;;;;;GAUG;AACH,qBAAa,wBAAyB,YAAW,sBAAsB;IACrE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAyB9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAMrC;;;;OAIG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpE;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;;;OAIG;IACH,OAAO,CAAC,eAAe;CAOxB"}

package/dist/providers/openai-sdk/spawn.d.ts

@@ -0,0 +1,146 @@
+/**
+ * OpenAI Agents SDK spawn provider.
+ *
+ * Implements `AdapterSpawnProvider` using the `@openai/agents` SDK runner.
+ * Unlike the Claude Code provider (detached fire-and-forget), this provider
+ * awaits the run and returns `status: 'completed'` or `status: 'failed'`
+ * so the orchestrator receives rich output immediately.
+ *
+ * Key features:
+ * - Tier-based model selection (lead → gpt-4.1, worker → gpt-4.1-mini)
+ * - Handoff topology built from `SpawnContext.options.handoffs`
+ * - CLEO path ACL guardrails applied at input stage
+ * - Default-on tracing via `CleoConduitTraceProcessor`
+ * - CANT prompt enrichment (best-effort, same as Claude Code provider)
+ *
+ * @task T582
+ */
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+/**
+ * OpenAI SDK-specific spawn options carried in `SpawnContext.options`.
+ *
+ * @remarks
+ * All fields are optional. Unknown fields are ignored.
+ */
+export interface OpenAiSdkSpawnOptions {
+    /**
+     * OpenAI model to use.
+     *
+     * @defaultValue Derived from `tier`:
+     *   - `'lead'` / `'orchestrator'` → `'gpt-4.1'`
+     *   - `'worker'` → `'gpt-4.1-mini'`
+     */
+    model?: string;
+    /**
+     * Agent archetype tier. Controls model selection and topology shape.
+     *
+     * @defaultValue `'worker'`
+     */
+    tier?: 'lead' | 'worker' | 'orchestrator';
+    /**
+     * Worker archetype names this agent may hand off to.
+     * References keys in `WORKER_ARCHETYPES` from `handoff.ts`.
+     *
+     * @defaultValue `[]`
+     */
+    handoffs?: string[];
+    /**
+     * File-path glob ACL allowlist. Paths outside this list trip the path guardrail.
+     *
+     * @defaultValue `[]` (all paths allowed)
+     */
+    allowedGlobs?: string[];
+    /**
+     * Tool name allowlist. Tools not in this list are documented but not enforced
+     * (enforcement is structural via the `tools` array on the Agent).
+     *
+     * @defaultValue `[]` (all tools allowed)
+     */
+    allowedTools?: string[];
+    /**
+     * Disable tracing to conduit.db.
+     *
+     * @defaultValue `false`
+     */
+    tracingDisabled?: boolean;
+    /**
+     * Agent display name used as the CANT persona.
+     */
+    agentName?: string;
+}
+/**
+ * Spawn provider for the OpenAI Agents SDK.
+ *
+ * Spawns SDK-backed agent runs for a given `SpawnContext`. The run is
+ * awaited synchronously and the result mapped to a `SpawnResult` with
+ * `status: 'completed'` or `status: 'failed'`. In-flight runs are tracked
+ * by instance ID so `listRunning()` and `terminate()` work correctly.
+ *
+ * @remarks
+ * The provider creates a fresh `Runner` per spawn so that `RunConfig`
+ * settings do not bleed across parallel spawns. Trace processors are
+ * registered globally via `addTraceProcessor` and removed by disabling
+ * tracing when the option is set.
+ *
+ * @example
+ * ```typescript
+ * const provider = new OpenAiSdkSpawnProvider();
+ * const result = await provider.spawn({
+ *   taskId: 'T582',
+ *   prompt: 'Implement feature X',
+ *   options: { tier: 'lead', handoffs: ['worker-read', 'worker-write'] },
+ * });
+ * console.log(result.status); // 'completed'
+ * ```
+ */
+export declare class OpenAiSdkSpawnProvider implements AdapterSpawnProvider {
+    /** Currently running instance IDs (completed runs are removed). */
+    private readonly runningInstances;
+    /**
+     * Check whether the OpenAI SDK can spawn in the current environment.
+     *
+     * Requires `OPENAI_API_KEY` to be set. Does not make a network call.
+     *
+     * @returns `true` when `OPENAI_API_KEY` is present in the environment.
+     */
+    canSpawn(): Promise<boolean>;
+    /**
+     * Spawn a subagent via the OpenAI Agents SDK runner.
+     *
+     * Awaits the run to completion and returns a fully-resolved `SpawnResult`.
+     *
+     * @param context - Spawn context with task ID, prompt, and options.
+     * @returns Resolved spawn result with `status: 'completed'` or `'failed'`.
+     */
+    spawn(context: SpawnContext): Promise<SpawnResult>;
+    /**
+     * List currently running OpenAI SDK agent instances.
+     *
+     * @returns Array of in-progress spawn results.
+     */
+    listRunning(): Promise<SpawnResult[]>;
+    /**
+     * Terminate a running spawn by instance ID.
+     *
+     * The OpenAI SDK runner does not support external termination of in-flight
+     * runs; this method removes the instance from the tracking set so it will
+     * no longer appear in `listRunning()`.
+     *
+     * @param instanceId - ID of the spawn instance to terminate.
+     */
+    terminate(instanceId: string): Promise<void>;
+    /**
+     * Parse and validate `SpawnContext.options` into typed `OpenAiSdkSpawnOptions`.
+     *
+     * Unknown fields are silently ignored.
+     */
+    private parseOptions;
+    /**
+     * Derive the default model for a given tier.
+     *
+     * @param tier - Agent tier.
+     * @returns Model identifier string.
+     */
+    private modelForTier;
+}
+//# sourceMappingURL=spawn.d.ts.map

package/dist/providers/openai-sdk/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-sdk/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAY3F;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,cAAc,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAaD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IAEtD;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAIlC;;;;;;;OAOG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAiFxD;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAU3C;;;;;;;;OAQG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlD;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAwBpB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAGrB"}

package/dist/providers/openai-sdk/tracing.d.ts

@@ -0,0 +1,89 @@
+/**
+ * OpenAI Agents SDK trace processor that writes spans to conduit.db.
+ *
+ * `CleoConduitTraceProcessor` implements the SDK `TracingProcessor` interface.
+ * On every span end it serialises the span and writes a structured event to
+ * conduit.db via the shared `conduit-trace-writer` transport layer.
+ *
+ * Tracing is on by default for all OpenAI SDK spawns. Set
+ * `options.tracingDisabled = true` in `SpawnContext.options` to opt out when
+ * conduit is unavailable.
+ *
+ * @task T582
+ */
+import type { Span, SpanData, Trace, TracingProcessor } from '@openai/agents';
+/**
+ * CLEO trace processor that persists OpenAI Agents SDK spans to conduit.db.
+ *
+ * Implements the `TracingProcessor` interface from `@openai/agents-core`.
+ * Each `onSpanEnd` call extracts span metadata and enqueues a write to
+ * conduit via the shared `conduit-trace-writer` module. Writes are
+ * fire-and-forget — failures are logged but never propagated to the caller.
+ *
+ * @remarks
+ * `onTraceEnd` performs a batch flush of any buffered spans. Individual
+ * `onSpanEnd` calls also write immediately so spans are not lost if the run
+ * is interrupted.
+ *
+ * @example
+ * ```typescript
+ * import { addTraceProcessor } from '@openai/agents';
+ * import { CleoConduitTraceProcessor } from './tracing.js';
+ *
+ * const processor = new CleoConduitTraceProcessor('T582');
+ * addTraceProcessor(processor);
+ * ```
+ */
+export declare class CleoConduitTraceProcessor implements TracingProcessor {
+    /** CLEO task ID included in every span event for correlation. */
+    private readonly taskId;
+    /** Pending span events buffered within the current trace. */
+    private pendingEvents;
+    /**
+     * @param taskId - CLEO task ID to attach to every written span.
+     */
+    constructor(taskId: string);
+    /**
+     * Called when a new trace starts. Resets the pending event buffer.
+     *
+     * @param _trace - The trace that just started (unused).
+     */
+    onTraceStart(_trace: Trace): Promise<void>;
+    /**
+     * Called when a trace ends. Flushes all pending span events to conduit.
+     *
+     * @param _trace - The trace that just ended (unused — spans were captured via `onSpanEnd`).
+     */
+    onTraceEnd(_trace: Trace): Promise<void>;
+    /**
+     * Called when a new span starts. No-op — we capture on end to have full timing.
+     *
+     * @param _span - The span that just started (unused).
+     */
+    onSpanStart(_span: Span<SpanData>): Promise<void>;
+    /**
+     * Called when a span ends. Serialises and writes the span to conduit.
+     *
+     * @param span - The completed span from the SDK.
+     */
+    onSpanEnd(span: Span<SpanData>): Promise<void>;
+    /**
+     * Called during graceful shutdown. Flushes any remaining pending events.
+     *
+     * @param _timeout - Shutdown timeout in milliseconds (unused).
+     */
+    shutdown(_timeout?: number): Promise<void>;
+    /**
+     * Force-flush all pending span events to conduit immediately.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Extract a {@link ConduitSpanEvent} from an SDK span, or `null` if the
+     * span cannot be meaningfully serialised.
+     *
+     * @param span - The SDK span to serialise.
+     * @returns A conduit span event or `null`.
+     */
+    private extractSpanEvent;
+}
+//# sourceMappingURL=tracing.d.ts.map

package/dist/providers/openai-sdk/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-sdk/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAQ9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,yBAA0B,YAAW,gBAAgB;IAChE,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,6DAA6D;IAC7D,OAAO,CAAC,aAAa,CAA0B;IAE/C;;OAEG;gBACS,MAAM,EAAE,MAAM;IAI1B;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;;;OAIG;IACG,UAAU,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD;;;;OAIG;IACG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAWjC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;CAuCzB"}

package/dist/providers/shared/conduit-trace-writer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared conduit trace writer for SDK-backed providers.
+ *
+ * Writes structured span events to conduit.db via the CLEO transport layer.
+ * Both T581 (Claude SDK) and T582 (OpenAI SDK) use this module so the
+ * conduit write path stays DRY.
+ *
+ * The writer is fire-and-forget: if conduit is unavailable, write failures are
+ * silently swallowed so that missing tracing never breaks agent execution.
+ *
+ * @task T582
+ */
+/**
+ * A single normalised span event written to conduit.
+ *
+ * @remarks
+ * This shape is intentionally minimal — only fields that both SDK providers
+ * can populate consistently are required. Provider-specific fields go into
+ * the `metadata` bag.
+ */
+export interface ConduitSpanEvent {
+    /** Unique identifier for this span (from the SDK). */
+    spanId: string;
+    /** The task ID this span belongs to. */
+    taskId: string;
+    /** The name of the agent that produced this span. */
+    agentName: string;
+    /** Type of span: `'agent'`, `'function'`, `'handoff'`, `'generation'`, etc. */
+    spanType: string;
+    /** ISO timestamp when the span started. */
+    startTime: string;
+    /** ISO timestamp when the span ended. */
+    endTime: string;
+    /** Optional tool name for function/tool spans. */
+    toolName?: string;
+    /** Optional handoff target agent name. */
+    handoffTarget?: string;
+    /** Extra provider-specific metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Conduit write result — only used internally for error handling. */
+interface WriteResult {
+    written: boolean;
+    error?: string;
+}
+/**
+ * Write a single span event to conduit via `cleo` CLI transport.
+ *
+ * Falls back gracefully when conduit is unavailable. All errors are caught
+ * and returned in the result rather than thrown.
+ *
+ * @param event - The span event to persist.
+ * @returns Result indicating whether the write succeeded.
+ *
+ * @remarks
+ * The current implementation writes to conduit using the `cleo conduit send`
+ * CLI command. This keeps the trace writer free of direct DB dependencies and
+ * consistent with the no-direct-SQLite rule (ADR).
+ *
+ * When conduit grows a native TS API this writer can be updated without
+ * changing caller code.
+ */
+export declare function writeSpanToConduit(event: ConduitSpanEvent): Promise<WriteResult>;
+/**
+ * Write multiple span events to conduit, swallowing individual write failures.
+ *
+ * @param events - Array of span events to persist.
+ * @returns Number of events successfully written.
+ */
+export declare function writeSpanBatchToConduit(events: ConduitSpanEvent[]): Promise<number>;
+export {};
+//# sourceMappingURL=conduit-trace-writer.d.ts.map

package/dist/providers/shared/conduit-trace-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conduit-trace-writer.d.ts","sourceRoot":"","sources":["../../../src/providers/shared/conduit-trace-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,sEAAsE;AACtE,UAAU,WAAW;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAoBtF;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOzF"}

package/dist/providers/shared/sdk-result-mapper.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared SDK result mapper for CLEO spawn providers.
+ *
+ * Normalises provider-specific run results (OpenAI Agents SDK, Claude Agent SDK)
+ * into the canonical {@link SpawnResult} contract used by CLEO orchestration.
+ *
+ * Both T581 (Claude SDK) and T582 (OpenAI SDK) import from this module so the
+ * mapping logic stays DRY.
+ *
+ * @task T582
+ */
+import type { SpawnResult } from '@cleocode/contracts';
+/**
+ * Raw run outcome from any SDK provider, normalised before mapping.
+ *
+ * @remarks
+ * Both `@anthropic-ai/claude-agent-sdk` and `@openai/agents` surface a
+ * `finalOutput` string plus an optional error. This interface captures the
+ * minimal shared shape so the mapper stays provider-agnostic.
+ */
+export interface RawSdkRunOutcome {
+    /** Final text produced by the agent run. Empty string when the run failed. */
+    finalOutput: string;
+    /** True when the run completed without error. */
+    succeeded: boolean;
+    /** Human-readable error message when `succeeded` is false. */
+    errorMessage?: string;
+    /** Exit / stop reason surfaced by the SDK (optional). */
+    stopReason?: string;
+}
+/**
+ * Map a raw SDK run outcome to the canonical CLEO {@link SpawnResult}.
+ *
+ * @param instanceId - Unique identifier for this spawn instance.
+ * @param taskId - CLEO task ID associated with the run.
+ * @param providerId - Identifier of the provider that performed the run (e.g. `'openai-sdk'`).
+ * @param startTime - ISO timestamp captured just before the run was started.
+ * @param outcome - Normalised run outcome from the SDK provider.
+ * @returns A fully-populated {@link SpawnResult} ready for return from `spawn()`.
+ *
+ * @example
+ * ```typescript
+ * const result = mapSdkRunOutcome('openai-sdk-123', 'T582', 'openai-sdk', start, {
+ *   finalOutput: 'Done',
+ *   succeeded: true,
+ * });
+ * // result.status === 'completed'
+ * ```
+ */
+export declare function mapSdkRunOutcome(instanceId: string, taskId: string, providerId: string, startTime: string, outcome: RawSdkRunOutcome): SpawnResult;
+//# sourceMappingURL=sdk-result-mapper.d.ts.map

package/dist/providers/shared/sdk-result-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-result-mapper.d.ts","sourceRoot":"","sources":["../../../src/providers/shared/sdk-result-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,GACxB,WAAW,CAwBb"}

package/package.json

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

package/src/index.ts

@@ -31,6 +31,14 @@ export {
   getSetupInstructions,
   getStatuslineConfig,
 } from './providers/claude-code/index.js';
+export type { McpServerMap, McpStdioConfig, SessionEntry } from './providers/claude-sdk/index.js';
+export {
+  ClaudeSDKSpawnProvider,
+  DEFAULT_TOOLS,
+  getServers,
+  resolveTools,
+  SessionStore,
+} from './providers/claude-sdk/index.js';
 export {
   CodexAdapter,
   CodexHookProvider,

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

@@ -15,8 +15,10 @@ import { promisify } from 'node:util';
 import type {
   AdapterCapabilities,
   AdapterHealthStatus,
+  AdapterSpawnProvider,
   CLEOProviderAdapter,
 } from '@cleocode/contracts';
+import { ClaudeSDKSpawnProvider } from '../claude-sdk/spawn.js';
 import { ClaudeCodeContextMonitorProvider } from './context-monitor.js';
 import { ClaudeCodeHookProvider } from './hooks.js';
 import { ClaudeCodeInstallProvider } from './install.js';
@@ -84,8 +86,14 @@ export class ClaudeCodeAdapter implements CLEOProviderAdapter {
 
   /** Hook provider for CAAMP event mapping and registration. */
   hooks: ClaudeCodeHookProvider;
-  /** Spawn provider for launching subagent processes via `claude` CLI. */
-  spawn: ClaudeCodeSpawnProvider;
+  /**
+   * Spawn provider for launching subagent processes.
+   *
+   * Defaults to `ClaudeCodeSpawnProvider` (CLI mode). When
+   * `provider.claude.mode === 'sdk'` is set in CLEO config, the adapter
+   * swaps this for `ClaudeSDKSpawnProvider` at initialization time.
+   */
+  spawn: AdapterSpawnProvider;
   /** Install provider for managing instruction files and plugin registration. */
   install: ClaudeCodeInstallProvider;
   /** Path provider for resolving Claude Code directory locations. */
@@ -115,8 +123,9 @@ export class ClaudeCodeAdapter implements CLEOProviderAdapter {
   /**
    * Initialize the adapter for a given project directory.
    *
-   * Validates the environment by checking for the Claude CLI
-   * and Claude Code configuration directory.
+   * Reads the CLEO config to determine the spawn mode and swaps the spawn
+   * provider to `ClaudeSDKSpawnProvider` when `provider.claude.mode === 'sdk'`.
+   * Defaults to `ClaudeCodeSpawnProvider` (CLI) for backwards compatibility.
    *
    * @param projectDir - Root directory of the project
    */
@@ -124,6 +133,34 @@ export class ClaudeCodeAdapter implements CLEOProviderAdapter {
     this.projectDir = projectDir;
     this.initialized = true;
 
+    // Determine spawn mode from CLEO config. Best-effort: any error falls
+    // back to the default CLI provider.
+    try {
+      const { execFile } = await import('node:child_process');
+      const { promisify: pfy } = await import('node:util');
+      const execFileAsync = pfy(execFile);
+      const { stdout } = await execFileAsync('cleo', [
+        'config',
+        'get',
+        'provider.claude.mode',
+        '--output',
+        'json',
+      ]);
+      const parsed: unknown = JSON.parse(stdout.trim());
+      const mode =
+        parsed !== null &&
+        typeof parsed === 'object' &&
+        'data' in parsed &&
+        typeof (parsed as Record<string, unknown>).data === 'string'
+          ? (parsed as Record<string, string>).data
+          : undefined;
+      if (mode === 'sdk') {
+        this.spawn = new ClaudeSDKSpawnProvider();
+      }
+    } catch {
+      // Config unavailable or mode is default 'cli' — keep CLI provider
+    }
+
     // Activate CLEO hook bridge for this project — connects Claude Code
     // native events to CLEO's internal hook dispatch (T555).
     await this.hooks.registerNativeHooks(projectDir);