# 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.