Sync exec, tools, sandbox, and external-agent substrate #307

Objective

Adopt compatible upstream execution, tool, sandbox, MCP, code-mode, workspace-root, and agent-control substrate after the canonical turn and auth foundations are stable, while preserving Code Bridge and Every Code external-agent backends as intentional product layers.

Finish Line

Commands, patches, MCP/code tools, worktree roots, approvals, sandbox limits, Code Bridge, and built-in third-party agents run on one coherent current substrate with bounded output, cancellation, accounting, and compatibility coverage.

Current Status

State: Complete.

PR #494 merged into #428's candidate as 317d01d56df23141c105781a2fcc668997d81f46 on July 29, 2026. The lane now has bounded structural apply_patch feedback, actionable mixed-version exec capability rejection, fail-closed release-profile keyring test coverage, and 21 resolved execution/agent convergence decisions without reviving the superseded agent-jobs subsystem.

Evidence: all 15 PR checks passed or intentionally skipped, including blocking CI and the macOS ARM64 app build. Focused protocol, workspace-root, sandbox, agent lifecycle, Code Bridge, app-server, migration, harness, and Project Validation suites passed. Convergence validation passed with 364 guarded paths, zero violations, zero stale waivers, and all historical snapshots reproducible. Focused Opus review was clean at P0-P2.

The next product lane is #308. Its first isolated failure is background-review-same-turn-commit, which is downstream TUI/Background Review lifecycle work rather than an execution-substrate blocker.

Blocked by: nothing.
Last verified: July 29, 2026 at candidate head 317d01d56df23141c105781a2fcc668997d81f46.

Scope

• In: PathUri/workspace roots, exec-server protocol, unified exec, approvals and permission profiles, sandbox/resource limits, MCP/catalog/OAuth/retry substrate, code mode/tool search, external-agent import/accounting, cancellation/status, and Code Bridge compatibility.
• Out: final TUI rendering, automatic validation provider policy, broad plugin adoption without active use, and weakening the managed permission boundary for convenience.

Acceptance Criteria

• Mixed-version app-server/exec-server behavior is capability-negotiated or fails fast with an actionable error.
• Workspace roots and linked-worktree Git metadata are propagated consistently to commands, patches, tools, agents, and Code Bridge.
• Approval and sandbox semantics preserve current managed boundaries while adopting upstream safety fixes.
• MCP and code-mode additions are classified by active product need rather than imported only because they are conflict-free.
• External-agent runs preserve selector identity, prompt delivery, bounded output, token/import accounting, status, cancellation, failure, and resume semantics.
• Code Bridge remains a first-class model-visible Every Code layer with no protocol collisions.
• Tool output and injected context retain hard per-item and aggregate caps.
• Focused core/app-server/exec/agent tests and exec-harness scenarios pass.

Relationships

• Parent: Sync Codex Lab with current openai/codex substrate #230.
• Candidate: Build upstream snapshot integration and canary branch #428.
• Contract authority: Define Every Code-owned convergence contracts #126.
• Blocked by: Sync canonical turn, context, history, and recovery substrate #305 and Sync subscription auth and multi-account substrate #306.
• Related: Restore Every Code auto-validation loop #284/Restore pluggable changed-file validation providers #310 validation provider runtime.
• Blocks: Sync TUI, Guardian, and CI substrate #308, Restore pluggable changed-file validation providers #310, Prove current-binary third-party-agent dogfood #312, Reduce managed approval friction in dogfood workflows #313, and Surface structured rate-limit diagnostics for Claude CLI agents #315.
• Completed safety evidence: Preserve managed exec policy after rule parse failures #389, Preserve unified-exec authorization across escalation #390, and Reject blocked PostToolUse results in code mode #391.

Validation

• Focused protocol, core, exec, app-server, MCP, agent, and Code Bridge tests.
• Exec-harness scenarios for mixed versions, linked worktrees, cancellation, bounded output, and failure recovery.
• Third-party CLI tests use deterministic fakes before any bounded live dogfood.
• Sandbox and approval tests verify no permission broadening.
• For any app-server/exec protocol or Desktop-facing overlay change, run just write-app-server-schema, prove codex-rs/app-server-protocol/schema is clean, then run just test -p codex-app-server-protocol and the README Desktop initialize/thread/CLI strict-config gates.

Decisions

• Reuse upstream execution substrate; preserve Code Bridge and external-agent backends as thin local product layers.
• Do not hide compatibility problems behind feature flags; use explicit protocol capability or version boundaries.

Open Questions

• Which upstream code-mode/plugin surfaces are needed for the next dogfood window versus deferred as add-only volume.