feat: add Codex ACP backend

[llamojha]

Problem / Motivation

Kiro Crew public builds currently start new chats through the Kiro ACP harness only. Users who already use the Codex CLI cannot select its ACP adapter from the dashboard while keeping the existing agent.provider = "acp" contract.

Why it matters

A selectable Codex harness lets users use their existing local Codex setup without introducing a second provider abstraction or weakening Kiro's default behavior and security boundaries. Persisted backend changes also need a clear restart/new-chat boundary so they cannot silently alter already-running sessions.

What changed (motivation → approach → change)

Kiro remains the default, first-class ACP backend. Codex is added as an adapted harness selected through agent.acp_backend, with selection occurring only at the provider-registry seam.

• Adds a dedicated CodexAcpClient and CodexAcpProvider for Codex transport, lifecycle, model discovery/selection, MCP descriptors, auth diagnostics, and capability handling.
• Preserves the upstream Kiro construction path and keeps Codex-specific spawn, handshake, and advertised-model behavior in the dedicated adapter path.
• Keeps backend capabilities explicit and fail-closed, including Kiro Crew sandboxing for Codex and Kiro-only prerequisite/identity behavior.
• Snapshots the running backend in SessionManager, so model listing, usage reporting, and readiness follow the active gateway runtime rather than a pending persisted switch.
• Adds Settings → System → AI Backend, where Kiro remains selected by default and Codex can be selected for new chats after a gateway restart. Existing chats are not migrated in place.
• Updates config/schema defaults, command-palette routing, translations, and the ACP/provider/dashboard/harness-parity specifications.

Tests

• Added Codex coverage for provider-registry selection, dedicated construction paths, spawn/transport behavior, protocol capabilities, model gating, MCP wiring, session resume, auth/readiness boundaries, and running-backend snapshots.
• Added H13 regressions proving Kiro's startup-model branch remains explicit while Codex gating stays in the dedicated initializer.
• After rebasing onto current upstream 213db2e56, focused Codex/harness/trust-read/i18n-style tests pass.
• isort, flake8, Linux mypy, harness parity against current upstream, documentation lint, and git diff --check passed.
• Frontend TypeScript typecheck and ESLint passed with existing warnings only; targeted settings tests passed, and the production Vite build passed.
• The full backend suite exceeded two hours without finishing and was not rerun. Focused post-rebase backend, static, frontend, and build validation was used instead.

Manual verification

• Verified the AI Backend selector through an isolated worktree preview on port 15476.
• Confirmed Kiro remains the default and Codex can be selected with restart/new-chat guidance.
• The live gateway on port 5476 and production data were not touched.

Screenshots / video

The AI Backend selector, showing Settings → System → AI Backend with the ACP backend dropdown expanded (Kiro selected, Codex and Kiro Agent Server available):

Related Issues

no linked issue: this feature was developed directly and does not resolve a filed issue.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing affected tests pass and new tests were added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated
• No secrets, credentials, or internal references in the diff

[llamojha]

• rebutted — H13 ProviderRegistry construction-path claim

The claim does not hold. agent.provider remains fixed to acp; agent.acp_backend selects an adapted harness inside the existing ACP provider factory. Codex-only behavior is positively gated, while the empty-string Kiro backend remains in every Kiro capability set, so normal Kiro construction is unchanged. scripts/check_harness_parity.py passes against origin/main, the Kiro-path regression matrix passes, and the independent Opus falsification pass confirmed the construction path is behavior-preserving. Reverting backend propagation from the ACP factory would remove the requested adapted-harness seam rather than repair a widened Kiro path.

[github-actions]

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

Reviewed b56fdf24b466b14082dceea62d1912b868c412a6 via the fork AI-review pipeline; updated in place on each push.

BLOCKING -- src/kiro_crew/platform/defaults.py:44 -- Codex dispatch alters the Kiro construction path

if cfg.agent.acp_backend == ACP_BACKEND_CODEX: ... return create_codex_provider_factory(cfg)
Kiro config -> build_provider_factory -> new adapter conditional -> construction is no longer additive.
Anchor: harness-parity H13
Fix: Revert lines 42–47, leaving create_factory() as an identity call.
[BLOCK-MERGE] b56fdf2
[GPT-REVIEWED] b56fdf2

[llamojha]

Re: GPT 5.6 Review BLOCK-MERGE on src/kiro_crew/platform/defaults.py:44 (DefaultProviderRegistry.create_factory), reposted on head b56fdf24b466b14082dceea62d1912b868c412a6.

Same finding as the prior round (see comment above at cb22349878d6/2657ad710): the flagged code is unchanged by this push — this round only rebased onto fresh upstream main and added the AI Backend screenshot, it did not touch defaults.py.

Standing on the prior rebuttal: H13 explicitly names the ProviderRegistry seam (create_factory) as the sanctioned additive point, distinct from the Kiro construction path (create_provider_factory), which this PR does not modify (grep -n "ACP_BACKEND_CODEX" src/kiro_crew/config/loader.py returns zero matches, confirmed again on this head). test_codex_is_selected_only_at_provider_registry_seam and test_shared_acp_client_construction_has_no_codex_dispatch (both already in this PR) assert exactly this boundary.

No code change proposed; treating this as a persistent false positive from the review lane, not a new finding.

[bolichen97]

Full-diff overlap audit (current head b56fdf24b466b14082dceea62d1912b868c412a6): pending #6307 is the broader competing implementation of this Codex ACP capability. #5349 adds Codex-specific resolution/spawn/session branches (_resolve_codex_acp_argv*, CodexAcpClient, provider/model/effort/auth/UI wiring). #6307 changes the same acp/client.py, ACP types, provider factory, config and session inheritance paths, but implements Codex through BackendDescriptor/registry, SpecAdapterAcpClient/provider, staged admission and tool gates, alongside Claude, Goose, OpenCode and Pi.

These are not patch-identical, but they should not both land as independent backend models. Please treat #6307's registry/descriptor/admission design as the integration base, then port any #5349-only Codex UX, resolver diagnostics or tests that remain valuable and supersede this special-case path. #6390 is a related architecture decision (per-crew arbitrary command/env interfaces), not a Codex duplicate; its selection granularity must also be reconciled with the registry rather than mechanically stacked.

[NicholasRBowers]

🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been stale with failing CI. I reviewed the blockers but they require input beyond automated triage:

• At 3,256 added lines across 61 files introducing a new subsystem (Codex ACP backend), this exceeds the surface an automated drive can reason about safely — it stays with the author/maintainers.
• The GPT lane's blocking finding on platform/defaults.py:44 (harness-parity H13) has persisted across rounds against your standing rebuttal that create_factory is the sanctioned additive ProviderRegistry seam. On a fork PR the /ai-review override mechanism cannot clear it (fork review lanes re-derive the verdict on each run), so resolution needs a maintainer ruling: human review past the readiness label citing your rebuttal, re-homing the branch as a same-repo PR, or a code change.
• The branch conflicts with current main, and the maintainer overlap audit (2026-08-29) flags feat: add staged acp adapter admission #6307 as the broader competing implementation of this capability — coordination on which PR proceeds is needed before conflict resolution is meaningful.

When these are addressed, the pipeline will re-assess on its next cycle.

[bolichen97]

Audit note — three open PRs are building the same ACP-harness seam

This is a consolidation request, not a duplicate finding: #5349, #6307 and #6777
all add a non-kiro-cli ACP harness at the same seams, and they disagree with each other in
ways that mean only one design can land. Each of the three also carries substantial work
the other two do not, so none of them should simply be closed.

What the audit verified by reading all three merge-base diffs:

• feat: add Codex ACP backend #5349 ↔ feat: add staged acp adapter admission #6307 — Verified on both cached heads that these implement one capability -- drive the operator-installed codex-acp adapter as a harness chosen at agent.acp_backend, with a dashboard picker -- at the same seams with mutually exclusive contracts. Both add ACP_BACKEND_CODEX and PROVIDER_LABEL_CODEX to acp/types.py, then disagree on ACP_BACKENDS_SELECTABLE (each pinned by its own test); both rewrite DefaultProviderRegistry.create_factory with incompatible bodies (feat: add Codex ACP backend #5349 an if cfg.agent.acp_backend == ACP_BACKEND_CODEX branch, feat: add staged acp adapter admission #6307 _create_adapter_dispatch_factory on Dialect.KIRO/SPEC); both add SessionManager.acp_backend with contradictory semantics (restart-only snapshot that writes cfg.agent.acp_backend back, vs a live read plus live_harness); both add the same unlanded kiro-readiness bypass so a foreign-adapter operator is not told to sign into kiro-cli; both add codex adapter/sign-in rows to doctor; and both ship a harness selector carrying the same 'new chats only' disclosure (aiBackendPanel.* vs acpBackend.*). Since the earlier rounds ran, main landed the plumbing itself: feat(config): one registry for selectable ACP backends instead of three literals #6593 added acp_backends.py (BASELINE_SELECTABLE_BACKENDS, register_selectable_backend, one selectability gate) and feat(acp): add a dormant Codex ACP backend seam and name the harness-onboarding sequence #7813 added the dormant codex seam (_is_codex, PROTOCOL_VERSION_CODEX, _resolve_codex_acp_bin, a _spawn branch, _codex_session_mcp_servers, plus ACP_BACKENDS_EFFORT_VIA_CONFIG_OPTION / _MODEL_VIA_CONFIG_OPTION / _KIRO_SLASH_COMMANDS replacing the is_claude_backend negations), with codex known but withheld from the baseline. That landed shape is feat: add staged acp adapter admission #6307's -- in-place dispatch, membership sets, one gate, a create_factory documented to register nothing -- and it contradicts each of feat: add Codex ACP backend #5349's three signature choices: the create_factory special case (its standing, non-overridable BLOCK-MERGE), the CodexAcpClient spawn-path fork, and the restart-only snapshot (main computes _bg_runtime_backends() per call). Neither PR closes either documented admission blocker: feat: add Codex ACP backend #5349 has no tool gate or read routing at all, and neither touches agent_sdk/backend_install.py, the exact gap landed main names as the reason codex is not selectable. So only one design can land and feat: add staged acp adapter admission #6307 is the base -- but it is stale against main's landed seam and still carries an unaddressed CHANGES_REQUESTED whose item 3 asks for Codex in the first admitted set, which is what feat: add Codex ACP backend #5349's remainder feeds.

• feat: add staged acp adapter admission #6307 ↔ feat(acp): add OpenCode harness #6777 — Both PRs are still OPEN (the issue/PR reference check), so neither can have superseded the other. Reading the two merge-base diffs directly, I confirmed nine collisions inside the SAME functions, not merely the same files: build_permission_event's two rawInput fallback chains are byte-identical additions on both sides; api_sessions_usage gains the identical return web.json_response({"usage": {"available": False}}) at the same position ahead of reject_if_kiro_unverified; api_kiro_prerequisite_status gains the same asdict(PrerequisiteStatus(...)) + legacy_idle_operation() pre-probe bypass; reject_if_kiro_unverified is scoped off the same pre-existing ACP_BACKENDS_KIRO_IDENTITY_STORE set by two mutually exclusive shapes (inline live-slot resolution vs. a new selected_backend_uses_kiro_identity() helper plus a keyword on the function); AcpClient._spawn gains an OpenCode arm and protocol 1 twice by incompatible schemes (PROTOCOL_VERSION_CLAUDE renamed to PROTOCOL_VERSION_SPEC and mapped per-Dialect vs. a new PROTOCOL_VERSION_OPENCODE and a third elif); LLMProvider gains one new property under two names (backend vs acp_backend) with the same None default and the same rationale, and AcpProvider.is_opencode_backend is added twice with identical bodies; and the managed-MCP projection onto an adapted harness is implemented twice, in acp/spec_servers.py and mcp_gateway/session_servers.py, both reduced to (name, command, args, env) with the same user-server-exclusion rationale. test/test_harness_parity.py carries directly opposed edits. Only one design can own each of those seams, so a consolidation decision is owed. the first adjudication's nomination of feat: add staged acp adapter admission #6307 as survivor is nevertheless wrong: feat: add staged acp adapter admission #6307 pins ACP_BACKENDS_SELECTABLE == frozenset({KIRO, KAS}) with an equality assertion and its own docs row reads | OpenCode | opencode | opencode auth login | Described, not selectable |, and selectable_ids() returns that frozen set, so "opencode" can never be persisted and every non-Kiro branch it adds (models, usage, prerequisite, readiness) is unreachable code at its HEAD. Current state cuts under both: acp_backends.py landed between the two merge bases (absent at e48ea42, present at 588ae92), main now ships BASELINE_SELECTABLE_BACKENDS = {kiro, claude, kas} with claude deliberately selectable, and both branches rewrite that same line in opposite directions - feat: add staged acp adapter admission #6307 to {kiro, kas}, feat(acp): add OpenCode harness #6777 to {kiro, kas, opencode} - which is the one decision the consolidation has to make.

Why this needs a decision rather than a merge order

The three collide inside the same functions, not merely in the same files, and each pins its
own answer with its own test — so whichever lands second does not conflict textually so much as
contradict a test the first one added. In particular the ACP_BACKENDS_SELECTABLE / selectable-set
question is answered three different ways.

Two things must not be lost whichever design wins

From #5349, carry before consolidating: (1) website/src/pages/settings/AiBackendPanel.tsx plus website/src/test/AiBackendPanel.test.tsx -- the Settings -> System -> AI Backend picker with per-backend descriptions and the restart/new-chat disclosure (aiBackendPanel.restart_new_chats_description), together with its command-palette wiring in website/src/components/commandPalette/settingsRegistry.gen.ts and settingsTabLabel.ts; this is closer to the maintainer's 'the provider switch has its own page, keep consistent with the internal version' than #6307's preview-gated Developer -> ACP Adapters tab (AcpBackendCard.tsx). (2) src/kiro_crew/dashboard/kiro_readiness.py::running_backend_requires_kiro_prerequisite -- keep its fail-closed rule (an absent or unknown backend still demands kiro readiness) as the behaviour #6307's live resolver must preserve. (3) src/kiro_crew/cli_doctor.py's actionable codex rows ('Codex ACP adapter not found', Fix: npm i -g @agentclientprotocol/codex-acp), folded into acp/doctor.py::_report_adapter, and reused as the basis for the missing agent_sdk/backend_install.py codex probe that landed main names as codex's selectability blocker. (4) From test/test_acp_backend_codex.py, the design-independent cases only: codex advertised-model gating, session/new MCP descriptor wiring, session resume, and the auth-required / readiness boundary. Do NOT carry CodexAcpClient, CodexAcpProvider / create_codex_provider_factory, the create_factory codex branch, the ACP_BACKENDS_SELECTABLE edit, CODEX_EFFORT_CONFIG_ID = 'reasoning_effort', or the restart-only SessionManager.acp_backend snapshot -- each is superseded by, or contradicted by, landed main.

One security-relevant note

Nothing needs harvesting for a closure - neither PR is closed. For the consolidation, two items must not be lost whichever design wins. From #6307: src/kiro_crew/acp/opencode.py's ensure_routed_settings() with PERMISSION_ASK / PERMISSION_BYPASS_VALUES, which writes permission: "ask" into the session work_dir (opencode.json or .opencode/opencode.json, never ~/.config/opencode) and reads it back, because OpenCode's own default is permissive so an unseeded work_dir emits no session/request_permission and privileged tool calls never reach Crew's PreToolUse gate - I grepped #6777's whole diff and it has no counterpart (0 hits for opencode.json), so OpenCode must not become selectable without this. From #6777: AcpClient.opencode_mcp_identity / remember_opencode_mcp_servers, which reverse OpenCode's sanitize(server)+''+sanitize(tool) wire key with fail-closed prefix-collision handling (#6307's parser handles only the mcp___ shape); website/src/components/KiroPrerequisiteGate.tsx's switchBackendMutation escape hatch plus its five en.json keys and 52 test lines, the only first-run path a kiro-cli-less operator can reach; the AgentBackendTab.tsx fourth row; _cold_opencode_models (opencode models, 1 MB cap, ^[^\s/]+/[^\s]+$, dedup) so the picker fills before any session exists; agent.py's MANAGED_MCP_SERVER_NAMES + materialized_agent_spec capped reader; the opencode addition to scripts/check_harness_parity.py's HARNESS_LITERAL; and the live evidence in the PR body (opencode 1.18.23, real ses* session, stream_events -> end_turn) that is precisely what maintainer iamwhatever's CHANGES_REQUESTED point 3 asked for before any adapter is admitted.

Suggested next step: a maintainer picks the seam design (the registry-dispatch shape vs. the
per-backend branch shape), then the other two rebase onto it as harness additions rather than
as competing seams — which is also what the harness-parity rule in AGENTS.md asks for
("an added harness ADAPTS, it does not widen").

---

_{From a repository-wide duplicate/overlap audit of every pull request open against main (2026-09-02, 330 PRs, one reviewer per PR). Each PR was read as its full merge-base diff plus its description and every comment and review, then compared against each candidate PR's own diff and against origin/main at 1a765b88ceb7. This PR is not being closed — the note is informational. If the reading is wrong, please correct the reasoning rather than just the conclusion.}

[bolichen97]

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

• This PR is OVERLAPPING with PR #6307. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #5349: MERGE_DISCUSSION. The maintainer overlap audits on 2026-08-29 and 2026-09-02 name 6307 as the broader competing implementation of this capability and ask for a seam-design decision before either proceeds; both PRs carry work the other lacks, so neither should simply be closed. Files: src/kiro_crew/platform/defaults.py, src/kiro_crew/acp/types.py, src/kiro_crew/dashboard/kiro_readiness.py.
• This PR is OVERLAPPING with PR #6777. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #5349: MERGE_DISCUSSION. Adding a second non-Kiro harness at the same seams in a different shape; the shared scaffolding (readiness scoping, usage endpoint, managed-MCP projection, protocol dispatch, harness-parity tests) must be owned once. Files: src/kiro_crew/dashboard/kiro_readiness.py, src/kiro_crew/dashboard/handlers/sessions.py, src/kiro_crew/mcp_gateway/session_servers.py, src/kiro_crew/acp/client.py, test/test_harness_parity.py.
• This PR is OVERLAPPING with PR #7963. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #5349: MERGE_DISCUSSION. 7963 is the current-upstream continuation of the same capability on the landed seam and additionally closes the two documented admission blockers this PR leaves open; landing both would produce two Codex client paths, one of them ungated. Files: src/kiro_crew/acp_backends.py, src/kiro_crew/acp/client.py.
• This PR is OVERLAPPING with PR #8255. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #5349: MERGE_DISCUSSION. The two disagree about where harness selection lives (per-backend enum and capability sets versus descriptor registry and selection module); the PR's selection edits would be rewritten by 8255. Files: src/kiro_crew/acp/types.py, src/kiro_crew/config/loader.py.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.

[bolichen97]

@llamojha Thanks for this, and sorry for the long wait. This should not be closed, but it does need re-scoping.

The Codex selection half has since landed on main through #6593, #7813, #7963, #8684 and #8791. Codex is already in BASELINE_SELECTABLE_BACKENDS, spawns from the shared AcpClient in src/kiro_crew/acp/client.py, is admitted only behind acp_tool_gate, and has an install probe plus a governance policy id. Main also chose the opposite shape at two seams you edit: platform/defaults.py::create_factory is now the identity call return cfg.create_provider_factory(), and PATCH agent.acp_backend hot-switches new sessions via refresh_defaults() rather than a restart-only snapshot. Please drop src/kiro_crew/providers/codex.py, CodexAcpClient, create_codex_provider_factory, the create_factory branch, the ACP_BACKENDS_SELECTABLE literal and SessionManager.acp_backend.

What is genuinely not on main is the runtime behaviour of a Codex gateway, and that part is worth landing. _codex_session_mcp_servers is still return []. reject_if_kiro_unverified has no backend gate, so a Codex gateway is blocked on Kiro readiness for /api/models, /api/sessions/usage and the destructive reruns. /api/models falls through to a kiro-cli --list-models spawn, KiroPrerequisiteService.warm_up still probes, a Codex auth failure latches Kiro signed out, Codex receives the full fs and terminal ACP_CLIENT_CAPABILITIES, there is no codex login remediation, set_model gating is Kiro-only, cli_doctor.py has zero Codex awareness, and main pushes effort as effort where you push reasoning_effort.

Could you rebase onto main and narrow this to that remainder, expressed against main's live-config model? Please also drop temp-screenshots/codex-acp/ai-backend-selector.png and the .github/black-baseline.txt churn. The readiness, usage and managed-MCP seams overlap #6777, so we will reconcile those together.

Posted from the 2026-09-08 open-PR relationship audit (read-only, one auditor per PR); reply here if any of this is wrong.