agent-ecosystem/docs/research/codex-native-runtime-integration-decision.md

# Codex Native Runtime Integration Decision

**Status**: Decision  
**Date**: 2026-04-19  
**Owner repos**:

- `claude_team`
- `agent_teams_orchestrator`
- `plugin-kit-ai`

## Purpose

Record the chosen direction for improving Codex integration in the multimodel runtime without losing native Codex capabilities such as plugins, skills, and MCP.

## Chosen Plan Assessment

- Chosen plan: normalized internal event/log layer plus staged `Codex-native` backend lane
- Assessment: `🎯 9   🛡️ 9   🧠 7`
- Estimated first serious wave: `2200-4500` lines across `agent_teams_orchestrator`, `claude_team`, and `plugin-kit-ai`

## Current Reality

Today, `Codex` inside our multimodel runtime is **not** executed through the real Codex runtime.

Instead, the current path is:

- `claude_team`
- `agent_teams_orchestrator`
- internal Codex backend
- OpenAI Responses API

In practice this means:

- the orchestrator keeps Anthropic-style streaming semantics
- `Codex` is treated as a model backend, not as a native runtime
- native Codex plugins are not honestly end-to-end supported
- current `Codex` capability support is limited by our adapter, not by the real Codex runtime

## What We Learned

After deep code and docs analysis, the most important conclusions are:

1. `@openai/codex-sdk` and `codex exec --json` are the real official execution seam for embedded Codex runtime usage.
2. `codex exec` supports API-key mode, so API-key mode itself is not the blocker.
3. `Codex` native plugins, apps, skills, and MCP are part of the real Codex runtime flow.
4. Our current `agent_teams_orchestrator` query loop is deeply coupled to Anthropic-style events and tool semantics.
5. A full drop-in swap from the current Codex adapter to `@openai/codex-sdk / codex exec` would not be a safe transport-only change. It would change runtime semantics.
6. `plugin-kit-ai` is a good fit for plugin management and native plugin placement.
7. `codex app-server` is promising for richer control-plane features, but should not be the foundation of the first production rollout for plugin management.

## Chosen Direction

We will **not** force Codex into the current Anthropic-shaped runtime contract.

We will instead:

- add a new **internal normalized event/log layer**
- keep execution semantics provider-native where needed
- add a separate **Codex-native runtime lane**
- use `plugin-kit-ai` for plugin management and native plugin placement

In practical terms:

- current Codex path stays available as the fallback/default path at first
- real Codex runtime execution becomes a separate lane instead of a drop-in replacement
- unified logs come from normalization, not from pretending every provider has Anthropic-native runtime semantics

## Decision Summary

### We are doing this

- keep the current Codex adapter path as the fallback/default path initially
- introduce a new `Codex-native` backend lane using `@openai/codex-sdk / codex exec`
- introduce a normalized internal event/log format for all providers
- map Anthropic, Gemini, and future Codex-native events into that normalized format
- keep unified logging, transcript projection, analytics, and UI-facing event handling on top of the normalized layer
- use `plugin-kit-ai` for:
  - install
  - update
  - remove
  - repair
  - discover
  - catalog
  - native Codex plugin placement through native marketplace/filesystem layout

### We are not doing this

- not replacing the whole multimodel runtime in one shot
- not forcing real Codex runtime execution into fake Anthropic transport semantics
- not pretending a full `@openai/codex-sdk / codex exec` swap is a drop-in backend replacement
- not making `app-server plugin/*` the first production seam

## Why We Chose This

### Main benefit

This path gives us both:

- unified internal logs/events
- a real path to native Codex runtime capabilities

without requiring a full rewrite of the current multimodel runtime.

### Main reason against a direct full swap

The current orchestrator is deeply coupled to Anthropic-shaped runtime behavior:

- `tool_use`
- `tool_result`
- `content_block_start`
- `input_json_delta`
- `message_delta`
- current permission and sandbox flow
- current synthetic tool/result handling
- current transcript persistence and resume logic

`codex exec` emits a different event model:

- `thread.started`
- `turn.started`
- `turn.completed`
- `turn.failed`
- `item.started`
- `item.updated`
- `item.completed`

and item types such as:

- `agent_message`
- `reasoning`
- `command_execution`
- `file_change`
- `mcp_tool_call`

That is not just a different wire format. It is a different runtime shape.

## What Changes Per Repo

### `agent_teams_orchestrator`

This repo takes the biggest change.

We want to:

- introduce a provider-neutral normalized event/log model
- add adapter mappers from current Anthropic/Gemini style streams into that model
- add a separate `Codex-native` backend lane through `@openai/codex-sdk / codex exec`
- keep the current Codex adapter path alive as fallback during migration
- avoid forcing `codex exec` events into fake `tool_use/tool_result` transport semantics

We do **not** want to:

- replace the current Codex backend in one shot
- rewrite all providers around Codex-native semantics
- make transcript/log normalization depend on Anthropic wire events

### `claude_team`

This repo should stay relatively stable compared with the orchestrator.

We want to:

- keep one multimodel runtime concept
- stay capability-aware per provider/backend lane
- consume normalized runtime/log DTOs rather than assuming one provider-shaped event model
- integrate plugin management through `plugin-kit-ai`
- keep Codex plugin support gated behind the real Codex-native lane

We do **not** want to:

- invent a fake Codex plugin support state while execution still goes through the old adapter lane
- force UI logic to infer runtime truth from provider labels alone

### `plugin-kit-ai`

This repo remains the management engine, not the execution engine.

We want to:

- use it for catalog
- use it for discover
- use it for install/update/remove/repair
- use it for native Codex plugin placement through native marketplace/filesystem layout

We do **not** want to:

- make it responsible for running Codex plugins inside sessions
- blur installation and execution into one concern

## Target Architecture

### Runtime execution

- `Anthropic` can continue on the current path for now
- `Gemini` can continue on the current path for now
- `Codex-native` gets a dedicated backend lane through `@openai/codex-sdk / codex exec`

### Internal normalization

All runtime backends must project into a shared internal event/log model.

The normalized layer should represent concepts such as:

- turn started
- assistant text
- reasoning
- command execution
- MCP call
- file change
- approval request
- turn completed
- turn failed

The normalized format is the source of truth for:

- logs
- transcript projection
- analytics
- UI-facing activity/event summaries

The normalized format is **not** required to preserve provider-native wire semantics.

## Codex Plugins Strategy

For Codex plugins we want:

- native Codex runtime execution
- native Codex marketplace/filesystem placement
- provider-aware plugin management in `claude_team`

Therefore:

- `plugin-kit-ai` is the management engine
- real Codex runtime is the execution engine

This is important because plugin installation and plugin execution are different concerns.

Installing a native Codex plugin is not enough by itself if the session still runs through our current Responses API adapter path.

## App Server Position

`codex app-server` remains relevant, but not as the first critical path for this migration.

It is better positioned as a later control-plane enhancement for things like:

- auth state
- MCP status and OAuth flows
- skills/config inspection
- external config import

For the first production rollout, it should not be the hard dependency for plugin lifecycle management.

## Implementation Phases

### Phase 1

- design and introduce the normalized internal event/log layer
- keep current backends working
- define the internal mapping contract clearly

### Phase 2

- add a `Codex-native` backend lane through `@openai/codex-sdk / codex exec`
- keep the current Codex adapter as fallback
- validate API-key mode, working directory behavior, sandbox mode, approval policy, thread resume, and streaming

### Phase 3

- integrate `plugin-kit-ai` for provider-aware plugin management
- add native Codex plugin placement through native marketplace/filesystem model
- keep current UI provider-aware and capability-aware

### Phase 4

- optionally add selective `codex app-server` control-plane integration where it provides clear value

## Main Risks And Guardrails

### Risk 1 - treating `codex-sdk/exec` as a transport-only swap

This is the most dangerous mistake.

Guardrail:

- treat `Codex-native` as a separate runtime lane
- normalize logs/events above it
- do not assume the current Anthropic-shaped tool loop can be preserved unchanged

### Risk 2 - claiming Codex plugin support too early

Installing native Codex plugins is not enough if execution still runs through the current adapter path.

Guardrail:

- only advertise Codex plugin support when the session actually runs through the Codex-native lane

### Risk 3 - overcommitting to `app-server` too early

`codex app-server` is useful, but it should not become a hard dependency for the first production plugin rollout.

Guardrail:

- use it later for selective control-plane features
- do not block the first migration on `app-server plugin/*`

## Practical Rule

If we need **unified logs**, we normalize events.

If we need **native Codex capabilities**, we do not fake Codex into Anthropic runtime semantics.

That is the core architectural rule for this migration.