feat: v0.8 roadmap — Codex MCP/plugin integration and explicit session wake #46

Prerequisites: #44 (v0.6 Codex adapter) and #45 (v0.7 diagnostics and reply/status semantics).

Motivation

An agent using session-peer through shell commands has to assemble executable paths, environment overrides, session IDs, and SSH arguments. It can also encounter sandbox restrictions even when the destination exists. A structured tool interface would make this integration easier to configure and inspect.

Target v0.8: a Codex-facing MCP integration and plugin packaging, plus a separately opt-in --wake capability for queued Codex sessions.

Does the official path already cover it?

Codex provides native queueing, MCP integration, and session-resume facilities. Reuse those supported mechanisms rather than inventing a model runner or terminal-input transport. The new value is exposing session-peer's cross-agent/local/SSH capabilities as narrow tools and offering explicit activation when a user chooses it.

An MCP process having different access from a Codex shell sandbox is a hypothesis to verify, not a reason to describe MCP as an approval bypass.

Proposed behaviour

• Expose structured session listing and message sending through MCP; expose status/wait only where the underlying implementation can provide it. Reuse the CLI's target resolution, result semantics, and errors.
• Package the integration for Codex with setup and usage instructions. Keep core CLI operation available without MCP/plugin dependencies; isolate optional integration requirements.
• Configure allowed destinations and capabilities rather than exposing arbitrary shell execution through a tool. Preserve the host application's approval model and existing SSH authentication.
• Add explicit session-peer send --to codex:<thread-uuid> --wake "message" support using supported activation/resume mechanisms. Plain send must remain queue-only.
• Explain that wake can incur model usage and modify session history. Resolve the selected home and original working directory before activation; do not silently bypass project trust, enable unsafe approval flags, fork the thread, or create concurrent writers.
• Define already-active, inactive, missing/uninitialised, archived, and locked-session behaviour from native capabilities and tests. Fail clearly when safe activation cannot be established. A queue-success/wake-failure result must preserve the queue ID so callers do not resend.

Evidence and limits

Earlier manual testing queued messages for a remote Codex session and processed them through explicit resume in the original project directory. A resume attempt outside that directory failed its project-trust check. A Codex-to-Claude UDS send was denied in one sandbox configuration and succeeded through approved execution in another.

These are feasibility observations, not a guarantee that one resume consumes an entire queue, that lock-file presence proves activity, or that MCP removes access restrictions. Establish those boundaries before shipping automatic activation.

Acceptance criteria

• A Codex MCP client lists and messages Claude/Codex targets locally and over a configured SSH route using the same core behaviour as the CLI.
• Installation, optional dependencies, destination restrictions, and approval behaviour are documented and exercised; actual UDS access from the MCP process is measured.
• Plain send never activates a session; --wake is explicit and tested for inactive, active, missing, and locked targets without concurrent resume or duplicate submission.
• Wake uses the selected Codex home and correct project directory; trust/approval failures are surfaced without automatic bypass.
• Queue success and activation failure remain distinguishable in human/JSON/tool results; no automatic resend on timeout or ambiguous outcome.
• Optional plugin/MCP installation does not change the standalone CLI's dependency requirements; integration tests and PR verification describe supported versions/platforms.

Implementation follows linked issue → branch → PR changes; delivery is a roadmap target, not an automatic configuration change on users' machines.