Planu — Codex Host Adapter

Decision Gate: MCP vs REST Shim

Outcome: MCP-over-stdio (native). REST shim not needed.

Investigation conducted 2026-04-21:

• OpenAI's official Codex documentation at developers.openai.com/codex/mcp confirms support for both STDIO and Streamable HTTP MCP servers.
• Codex stores MCP config in config.toml. Both CLI and IDE extension share this config.
• In April 2026, Codex expanded MCP support: namespaced MCP registration, parallel-call opt-in, and sandbox-state metadata for MCP servers.
• Enterprise deployments (Codex via ChatGPT Enterprise) support custom MCP connectors with read/write capabilities.

The rest-shim.ts file exists as a documented stub. If future Codex enterprise versions restrict stdio access (e.g., cloud-only deployments), implement a Node.js node:http HTTPS endpoint there — no new runtime deps are needed.

---

Architecture Overview

Codex CLI / IDE extension
        |
        | MCP-over-stdio (native)
        v
  Planu MCP server (index.ts)
        |
        +-- src/hosts/codex/adapter.ts       — detection + activation
        +-- src/hosts/codex/enterprise-auth.ts — SAML/OIDC + RBAC gate
        +-- src/hosts/codex/workspace-scope.ts — per-user path scoping
        +-- src/hosts/codex/config-scaffold.ts — .openai/ scaffold

The hosts/ layer depends on types/, engine/, storage/, and tools/ (for audit-log-export). It never imports from other hosts/ modules — zero shared state with the Gemini adapter (SPEC-591).

---

Quick Start (End User)

1. Install Planu MCP in your Codex workspace:

# .openai/config.toml
[[mcp.servers]]
name = "planu"
transport = "stdio"
command = "planu"
args = ["serve"]

2. Run init_project with your project path. For Codex workspaces, the adapter auto-detects the .openai/ directory and activates.

3. Use Planu tools as usual (create_spec, update_status, validate, etc.).

---

Enterprise Setup (Admin)

SSO / RBAC Configuration

The adapter reads identity from Codex enterprise environment variables:

Variable	Description
OPENAI_USER_ID	Unique user ID from IdP (required for RBAC)
OPENAI_USER_EMAIL	User email (informational only)
OPENAI_USER_ROLES	Comma-separated roles: owner,admin,member,viewer
OPENAI_ENTERPRISE_TENANT	Tenant ID for workspace isolation
OPENAI_WORKSPACE_ID	Workspace ID for detection

These are forwarded by Codex enterprise from your SAML/OIDC IdP. No Planu-side SSO configuration is required — Planu reads the passthrough identity.

Role Hierarchy

owner > admin > member > viewer

The minimum role for destructive tools (e.g., delete_spec) can be set in .openai/config.toml under [access].min_role_for_mutations. Default: member.

Audit Log

Every tool invocation, RBAC decision, and adapter lifecycle event is appended to data/global/audit-trail.jsonl (EU AI Act Article 12 chain). Export via export_audit_trail tool. All entries include projectPath, userId, and tenantId.

---

Multi-User Workspace Isolation

Codex enterprise workspaces are shared across users. Planu prevents cross-workspace spec leakage by scoping project paths per user:

<workspaceRoot>/<tenantId>/<userId>/

list_specs, search_specs, and resource enumeration only return specs under the caller's scoped path. Paths outside the scope are silently excluded (zero leakage).

---

Feature Fallback

Tools with no Codex-native equivalent fall back to single-turn inline execution:

Tool	Reason	Fallback
execute_sdd_flow	Requires multi-agent teams	Inline single-turn
plan_mode	Requires multi-turn planning	Inline single-turn
agent_swarm_status	Requires persistent subagent state	Inline single-turn

A single-line info message is logged for each fallback, and the event is recorded in the audit trail.

---

Language Stack Compatibility

The adapter operates on MCP protocol and file metadata only. It has no dependency on the project's programming language. All Planu tools work identically across: TypeScript, Python, Go, Rust, Java, Swift, PHP, Ruby, C#, and Dart projects.