Track Codex plugin manifest, hooks, marketplace, and policy parity

[ScriptedAlchemy]

Summary

Documentation-coverage follow-up for the current Codex plugin system observed on 2026-09-01. This is the Codex-specific child of #100/#107. It excludes Skill IR work already tracked by #108, canonical event-family routing on #97, schema adoption on #133, and end-user installation on #181/#101.

The current adapter emits .codex-plugin/plugin.json, .mcp.json, hooks/hooks.json, skills, and a local marketplace through packages/agent-bundle/src/adapters/codex.ts, but its pinned schema/capability record only models a subset of the now-documented surface.

Sources

Observed 2026-09-01:

• https://learn.chatgpt.com/docs/plugins
• https://learn.chatgpt.com/docs/build-plugins
• https://learn.chatgpt.com/docs/build-skills
• https://learn.chatgpt.com/docs/hooks
• https://learn.chatgpt.com/docs/enterprise/managed-configuration
• https://learn.chatgpt.com/docs/developer-commands?surface=cli
• https://developers.openai.com/plugins/concepts/plugins
• https://developers.openai.com/plugins/build/plugins
• https://developers.openai.com/plugins/build/mcp-server
• https://developers.openai.com/plugins/deploy/submission
• https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated

Checklist

Every item must become implemented, explicitly delegated, or recorded in the Codex capability table as unavailable/deferred with a reason.

Manifest/package

• Full .codex-plugin/plugin.json metadata (author details, homepage, repository, license, keywords)
• Complete interface fields: display/short/long descriptions, developer, category, capabilities, legal/site URLs, starter prompts, brand color, icons/logo/screenshots
• apps / .app.json registered MCP mapping compatibility surface
• mcpServers, skills, and hooks as documented path forms; hooks allow path, path array, inline object, or inline-object array
• Optional assets and submission-facing package constraints
• MCP server policy under plugins.<plugin>.mcp_servers.<server> (enabled/tools/approval modes)
• PLUGIN_ROOT/PLUGIN_DATA plus CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA compatibility environment

Hook contract

• Pin the release-documented events: SessionStart, SessionEnd, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStart, SubagentStop, and Stop
• Credit the running SubagentStart/SubagentStop correction lane; do not reimplement it here
• Reconcile generated-schema-only Interrupt as deferred until the release behavior docs support it
• Support or explicitly reject handler types: command and mcp_tool; keep parsed-but-skipped prompt/agent truthful
• mcp_tool structured input expansion, connected-server requirement, synchronous/non-recursive execution, and timeout behavior
• async command hooks, eight-per-session concurrency, cancellation at session end, and non-controlling output rules
• additionalContextLimit spill behavior and configuration diagnostics
• commandWindows/command_windows, statusMessage, and per-event timeout rules
• Exact matcher semantics by event, including ignored matchers, apply_patch aliases (Edit/Write), local-function coverage, and hosted-tool exclusions
• Trust-by-current-hash review, /hooks control, plugin hooks skipped until trusted, managed hooks immutable
• Validate event I/O against the generated schemas under codex-rs/hooks/schema/generated rather than the current open-ended event map

Marketplace/install/policy

• Repo/personal marketplace discovery and legacy .claude-plugin/marketplace.json compatibility
• Local, Git root, git-subdir, and npm sources; path containment, ref/SHA, lifecycle-script prohibition, and unresolved-entry behavior
• Marketplace interface, plugin policy.installation, policy.authentication, category, cache layout, and enable state in config.toml
• CLI codex plugin add/list/remove and marketplace add/list/upgrade/remove JSON contracts
• features.plugins, features.hooks, deprecated codex_hooks, inline [hooks], and managed requirements.toml
• allow_managed_hooks_only and marketplace restrict_to_allowed_sources behavior
• Public submission/publish controls and requirements are documented as distribution policy, not claimed as local compiler behavior

Acceptance

• No documented Codex surface remains implicit: each has a four-state capability row with dated evidence.
• Requested unsupported behavior fails before publication rather than being dropped by permissive schemas.
• Compile semantic Agent event routes into native host hooks #97 owns canonical event-route expansion; this issue owns native Codex manifest/hook/lifecycle fidelity.

Related: #107 #100 #97 #101 #108 #133 #181

[ScriptedAlchemy]

Two overview-level capabilities also need explicit status rows:

• Optional MCP UI is implemented only where Agent Bundle's MCP Apps contract genuinely matches the host; .app.json registered-connection mapping remains separate and is already in this issue.
• The public Plugins overview names browser extensions and scheduled-task templates, but the package/manifest reference read on 2026-09-01 does not publish authoring fields for them. Record both as host-managed / unavailable pending a schema-backed package contract; do not infer fields.

Source: https://learn.chatgpt.com/docs/plugins (read 2026-09-01).

[ScriptedAlchemy]

Decision (2026-09-01): systematic parity pass adopted — every stable documented surface gets implemented, host by host, Claude (#187) first. Recorded gate deferrals (e.g. G5 agents via #220) stand unless explicitly lifted. Slice 1 of #187 is in flight. Queued after #187 slices.

[ScriptedAlchemy]

Codex relevance from the Agent Plugins adoption work: the portable target now carries pinned Agent Plugins 1.0.0 evidence (spec repo agentplugins/agent-plugins-spec@ff8ab5e39), and Codex is on the standard's native-client roster, so the portable artifact is the natural Codex-facing package for skills+MCP. Note the known precedence hazard remains: Codex prioritizes a root plugin.json, which is why the multi-host plugin target still deliberately omits one — Codex consumers should take the portable artifact (or the dedicated codex target for sidecar-enriched skills), not a hybrid. The portable emission is validated against the pinned spec schemas at build time with a repeatable installer/filesystem proof in CI.

[ScriptedAlchemy]

Starting the systematic Codex parity pass (same slice discipline as the #187 Claude pass, which is now closed). Baseline: codex.ts adapter revision 1.2.0, capability table codex-0.147.0.json, pinned schemas under schemas/codex/ including the generated app-server hook schemas; local codex-cli 0.147.0 on PATH for native probes. Codex publishes no plugin validate command (recorded in the capability table), so native proofs take the form of CLI lifecycle probes in isolated homes, app-server generate-json-schema comparisons, and config/cache inspection rather than validator runs.

Slice plan:

• Slice 1 — manifest/package (2 PRs):
  1. Full .codex-plugin/plugin.json metadata (author details, homepage, repository, license, keywords), documented component path forms (mcpServers, skills, hooks as path / path array / inline object / inline-object array), and optional assets + submission-facing package constraints.
  2. interface fields (display/short/long descriptions, developer, category, capabilities, legal/site URLs, starter prompts, brand color, icons/logo/screenshots), apps / .app.json registered-MCP compatibility surface, MCP server policy under plugins.<plugin>.mcp_servers.<server> (enabled/tools/approval modes), and the PLUGIN_ROOT/PLUGIN_DATA + CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA compatibility environment.
• Slice 2 — hook contract (2 PRs):
  1. Pin the eleven release-documented events; reconcile generated-schema-only Interrupt as deferred; handler types (command/mcp_tool supported, prompt/agent kept truthfully parsed-but-skipped); validate event I/O against the generated schemas under codex-rs/hooks/schema/generated instead of the open-ended event map. Credits the running SubagentStart/SubagentStop correction lane without reimplementing it.
  2. mcp_tool structured input expansion, connected-server requirement, synchronous/non-recursive execution and timeouts; async command hooks (eight-per-session concurrency, session-end cancellation, non-controlling output); additionalContextLimit spill behavior; commandWindows/command_windows, statusMessage, per-event timeout rules; exact matcher semantics by event (ignored matchers, apply_patch aliases, local-function coverage, hosted-tool exclusions); trust-by-current-hash, /hooks control, plugin-hooks-skipped-until-trusted, managed hooks immutable.
• Slice 3 — marketplace/install/policy (2 PRs):
  1. Repo/personal marketplace discovery + legacy .claude-plugin/marketplace.json compatibility; source matrix (local, git root, git-subdir, npm; path containment, ref/SHA, lifecycle-script prohibition, unresolved-entry behavior); marketplace interface, plugin policy.installation/policy.authentication, category, cache layout, enable state in config.toml.
  2. CLI codex plugin add/list/remove and marketplace add/list/upgrade/remove JSON contracts; features.plugins, features.hooks, deprecated codex_hooks, inline [hooks], managed requirements.toml; allow_managed_hooks_only and restrict_to_allowed_sources; submission/publish controls recorded as distribution policy, not claimed as local compiler behavior.

Conventions carried over from the Claude pass: codex.* dotted diagnostics only; every capability row four-state with dated (retrieved) evidence citing the specific documented behavior; closed schemas pinned in PROVENANCE with byte/sha pins; honest tightenings recorded; serial adapterRevision adjudication; all gates run locally per PR (scoped suites + native Codex probes + typecheck + lint).

Progress will be checked off on the issue checklist per slice with a remaining-slice status after each.

[ScriptedAlchemy]

Slice 1 (manifest/package) — merged

• PR feat(codex): complete plugin manifest metadata contract #350 (15a7854de): full .codex-plugin/plugin.json metadata (author object, homepage, repository, license, keywords) with closed codex.manifest.* compile-time validation; pinned plugin.schema.json widened to the documented component path forms for mcpServers/skills/hooks (path, path array, inline object, inline-object array); manifestPackage capability rows (manifest metadata, paths, optional assets, submission policy — submission recorded as distribution policy, not compiler behavior). First native Codex proofs: registers/installs/lists an emitted plugin with authored metadata against real codex-cli 0.147.0 (--json contracts pinned; metadata not echoed by plugin list).
• PR feat(codex): interface fields, registered MCP apps, and policy/env capability evidence (#188 S1) #352 (9e941160b): complete interface install-surface block (identity, descriptions, developer, category/capabilities, legal/site URLs, starter prompts, six-digit brand color, plugin-root-contained icons/logo, ./assets/-relative PNG screenshots) via codex.interface.* diagnostics; apps registered-MCP mappings emitted as .app.json (pinned app.schema.json, codex.apps.* diagnostics); capability rows for the install-time MCP approval policy under plugins.<plugin>.mcp_servers.<server> (unavailable: enforced by the host at install, not a compile artifact) and the hook compatibility environment (PLUGIN_ROOT, PLUGIN_DATA, CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA — supported with dated hook-doc evidence). Native proof installs and lists a full-interface plugin and pins that the 0.147.0 CLI has no plugin validate subcommand.

Revisions: codex adapter 1.3.0 → 1.5.0, unified plugin 1.18.0 → 1.20.0 (serialized over the #351 events lane, which took 1.4.0/1.19.0 mid-slice). Unified rows keep the established convention: every Codex-only surface intersects to an honest unavailable for the other hosts.

Orchestrator interventions this slice: rebased PR #352 over #350 + #351 (both landed mid-flight) resolving 7-file conflicts; corrected the unified adapter from pass-through Codex rows to intersections; deduplicated the second runCodex helper onto the stdout/stderr shape; serialized both adapter revisions past the events lane.

Remaining slices

• Slice 2 — hook contract: release-documented event pinning (crediting the SubagentStart/SubagentStop lane, deferring generated-only Interrupt), handler types (command/mcp_tool, truthful parsed-but-skipped prompt/agent), mcp_tool expansion/timeout, async concurrency rules, additionalContextLimit, commandWindows/statusMessage/timeouts, exact matcher semantics, trust gates, generated-schema I/O validation.
• Slice 3 — marketplace/install/policy: marketplace discovery + legacy .claude-plugin/marketplace.json compat, source forms with containment/ref/lifecycle-script rules, config.toml policy/cache/enable state, CLI JSON contracts, feature flags + managed requirements.toml, allow_managed_hooks_only/restrict_to_allowed_sources, submission-as-policy.