Extract Codex Lab runtime behind extension and native agent-provider boundaries

[shiny-code-bot]

Current Status

Decision recorded on August 22, 2026: Codex Lab will not depend on OpenAI accepting downstream code changes. The current upstream contribution policy does not accept external pull requests, so all required native product behavior must remain maintainable inside cbusillo/codex-lab.

The extraction target is a Codex Lab-owned runtime layer, using codex-lab-* crate names. Existing upstream extension APIs should be consumed through adapters where they preserve behavior, while first-class third-party agents remain native through a downstream-owned provider registry. codex-skills remains the home for portable instructions, references, and helper scripts only.

This is not a prerequisite to migrate every existing feature before normal product work resumes. The first bounded stage establishes the ownership boundary, proves registration/reachability, and migrates one representative extension plus the existing external-agent path without changing behavior. Later hot-spot migrations are prioritized by measured convergence conflict cost.

Finish Line

Codex Lab owns a tested extension composition root and native agent-provider boundary that preserves current internal and third-party agent behavior, keeps concrete providers outside upstream orchestration files, fails closed when required providers/extensions are not registered, and establishes a ratchet that reduces recurring shared-file conflicts without requiring upstream code acceptance.

Acceptance Criteria

• Inventory current downstream divergences as: supported upstream extension, missing Codex Lab seam, or irreducible native contract.
• Define the Codex Lab-owned crate/module namespace using codex-lab-*; do not introduce an every-code-* runtime namespace.
• Add a Codex Lab extension composition root that can wrap upstream ExtensionRegistry contributions without forking the upstream registry API unnecessarily.
• Define a native agent-provider contract from the existing working internal/external agent lifecycle: selector, capability discovery, auth/quota state, spawn, status/events, input/follow-up, wait, cancel/interrupt/close, typed result/failure, persistence/resume, and provenance.
• Adapt the existing internal and external-command paths behind the provider boundary without changing user-visible behavior.
• Add non-skippable registration and reachability evidence before removing any existing native wiring.
• Migrate one low-risk tool/context/lifecycle feature through the extension composition root as the reference pattern.
• Keep concrete Claude, Antigravity, and external-command providers in Codex Lab-owned crates; do not move runtime implementations into codex-skills.
• Record a baseline and ratchet for modified upstream files and the recurring conflict hot set.
• Land each complex stage below 500 changed lines and remove replaced native paths rather than retaining dual implementations.

Relationships

• Sub-issue of Sync Codex Lab with current openai/codex substrate #230.
• Uses Implement native third-party agent dogfood path #58 as the native external-agent behavior baseline.
• Related to Audit native Auto Review and third-party agent path #54 and Plugin lifecycle hooks for workspace preparation and quality providers #149 for the prior plugin/native-agent decision and plugin lifecycle.
• Requires the registration/reachability evidence introduced through Detect code-present-but-unreachable regressions during upstream convergence #664.
• Runs alongside the recurring convergence automation owned by Automate low-token recurring upstream convergence #634.

• related: Detect code-present-but-unreachable regressions during upstream convergence #664 - Detect code-present-but-unreachable regressions during upstream convergence #664
• related: Automate low-token recurring upstream convergence #634 - Automate low-token recurring upstream convergence #634
• related: Implement native third-party agent dogfood path #58 - Implement native third-party agent dogfood path #58