Skip to content

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

Closed
Closed
Track Codex plugin manifest, hooks, marketplace, and policy parity#188
Labels
enhancementNew feature or requesthost-integrationAgent host capabilities, projection, discovery, and lifecyclemeta-frameworkAgent Bundle compiler-coupled meta-framework

Description

@ScriptedAlchemy
ScriptedAlchemy
opened on Sep 1, 2026

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:

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

Activity

  1. ScriptedAlchemy
    added
    enhancementNew feature or request
    meta-frameworkAgent Bundle compiler-coupled meta-framework
    host-integrationAgent host capabilities, projection, discovery, and lifecycle
    on Sep 1, 2026

  2. ScriptedAlchemy commented on Sep 1, 2026

    @ScriptedAlchemy
    ScriptedAlchemy
    on Sep 1, 2026
    OwnerAuthor

    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).

  3. ScriptedAlchemy commented on Sep 2, 2026

    @ScriptedAlchemy
    ScriptedAlchemy
    on Sep 2, 2026
    OwnerAuthor

    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.

  4. ScriptedAlchemy commented on Sep 2, 2026

    @ScriptedAlchemy
    ScriptedAlchemy
    on Sep 2, 2026
    OwnerAuthor

    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.

  5. ScriptedAlchemy commented on Sep 3, 2026

    @ScriptedAlchemy
    ScriptedAlchemy
    on Sep 3, 2026
    OwnerAuthor

    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.

  6. ScriptedAlchemy commented on Sep 3, 2026

    @ScriptedAlchemy
    ScriptedAlchemy
    on Sep 3, 2026
    OwnerAuthor

    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.
  7. ScriptedAlchemy
    added 5 commits that reference this issue on Sep 3, 2026

    feat(codex): pin the release hook contract, handler types, and genera…

    abf5d8c

    feat(codex): author marketplace policy and record distribution/instal…

    d7e0550

    fix(codex): accept any JSON tool_input/tool_response on Codex tool ho…

    c95091d

    feat(codex): marketplace source matrix, install policy, and distribut…

    325e7f4

    feat(codex): record plugins-overview parts (MCP UI, browser extension…

    08549c3

  8. ScriptedAlchemy commented on Sep 3, 2026

    @ScriptedAlchemy
    ScriptedAlchemy
    on Sep 3, 2026
    OwnerAuthor

    Slices 2–3 + overview rows — merged; closing

    All remaining checklist items are now implemented, explicitly delegated, or recorded in packages/agent-bundle/src/adapters/capabilities/codex-0.147.0.json as a four-state row with dated (retrieved 2026-09-02/03) evidence. Final revisions: codex adapter 1.9.0, unified plugin adapter 1.24.0. Every pinned schema (hooks.schema.json, marketplace.schema.json, plugin.schema.json, 21 generated rust-v0.147.0 hook schemas) carries byte/sha pins in schemas/codex/PROVENANCE.json and adapter-metadata.test.ts.

    PRs in this lane

    PR Merge Scope
    #378 abf5d8cbf Slice 2 — hook contract: 11 release events pinned, Interrupt deferred, handler types, mcp_tool/async/additionalContextLimit/commandWindows/statusMessage/timeout semantics, matcher rules, trust, generated-schema I/O validation
    #404 c95091d14 Follow-up to the #378 review: Codex tool_input/tool_response accept any JSON per the generated schemas
    #392 325e7f470 Slice 3 — marketplace source matrix, authored codex.marketplace policy/displayName/category, NOT_AVAILABLE rejection, distribution rows, live codex plugin / codex plugin marketplace JSON probes
    #415 08549c39c Overview-level rows (plugin.overviewSurfaces: MCP UI, browser extensions, scheduled task templates) + adapter revision bumps

    Hook contract

    Item Status Evidence
    Pin the 11 release events Implemented hooks.contract.releaseEvents supported; hooks.schema.json closes the hooks object to exactly those keys, so an unknown event fails before publication (#378)
    Credit SubagentStart/SubagentStop lane Delegated Events lane #351 owns the route correction; rows credit it, nothing re-implemented here
    Interrupt reconciliation Deferred (recorded) Stays in deferredNativeEvents with a dated reason (documented on the hooks page, no generated schema at rust-v0.147.0); authoring it fails with codex.native-hooks.event.deferred (#378)
    Handler types command / mcp_tool; truthful prompt/agent Implemented handlerCommand supported; handlerMcpTool degraded (admitted + validated in native docs, canonical hooks compile to command, connectivity unverifiable); handlerPromptAgent unavailable — rejected with codex.native-hooks.handler.skipped since 0.147.0 parses but never runs them (#378)
    mcp_tool input expansion, connected-server, sync/non-recursive, timeout Recorded mcpToolExecution unavailable — host runtime behaviour; ${field} expansion, 600 s default, statusMessage documented in row evidence; mcp_tool rejected under SessionEnd (#378)
    async hooks, 8-per-session, session-end cancel, non-controlling output Recorded asyncCommandHooks degraded — authored async admitted, rejected on SessionEnd; concurrency/cancellation/output rules are host behaviour (#378)
    additionalContextLimit spill + diagnostics Implemented/Recorded additionalContextLimit degraded — authored value admitted, rejected with a diagnostic on events that cannot return additionalContext; spill-to-disk is host behaviour (#378)
    commandWindows/command_windows, statusMessage, per-event timeouts Implemented/Recorded commandWindows degraded (admitted; generated wrappers emit one node command per platform), statusMessage degraded, timeoutRules supported — SessionEnd timeouts > 3 s rejected (#378)
    Matcher semantics (ignored matchers, apply_patch aliases, local-function coverage, hosted-tool exclusions) Implemented matcherSemantics supported — per-event matcher targets pinned; matchers on UserPromptSubmit/Stop flagged as ignored; hosted tools excluded from the local function-tool path (#378)
    Trust-by-hash, /hooks, plugin hooks skipped until trusted, managed hooks immutable Recorded trustReview unavailable — host-owned per-user decision; compiler cannot pre-trust (#378)
    Validate event I/O against generated schemas Implemented generatedSchemaValidation supported — all 21 rust-v0.147.0 schemas byte-pinned; wrapper + projection.ts validate against them; Codex tool_input/tool_response accept any JSON and last_assistant_message is nullable, per the pinned schemas (#378, #404)

    Marketplace / install / policy

    Item Status Evidence
    Repo/personal discovery, legacy .claude-plugin/marketplace.json Implemented/Recorded repoMarketplaceDiscovery supported (.agents/plugins/marketplace.json); personalMarketplaceDiscovery unavailable (user home file); legacyClaudeMarketplaceCompatibility unavailable — adapter never emits the Claude path (#392)
    Local, Git root, git-subdir, npm sources; containment, ref/SHA, lifecycle scripts, unresolved entries Implemented marketplace.schema.json admits every documented form with structural validation: contained paths (no .., control chars, or line terminators), Git URLs with valid DNS/IPv4/bracketed-IPv6 hosts, RFC 3986 userinfo, 0–65535 ports and percent-encoded paths, scp-style remotes, git check-ref-format refs, 7–64 hex SHAs, npm names, credential-free HTTPS registries, semver/range/dist-tag versions; marketplaceSources degraded — the adapter only ever emits its own local root (#392)
    Marketplace interface, policy.installation/authentication, category, cache layout, enable state Implemented/Recorded Authored codex.marketplace.displayName/category/policy with codex.marketplace.* diagnostics; installation: NOT_AVAILABLE fails the build with codex.marketplace.policy.installation.not-installable because live codex plugin add refuses it; installCacheLayout and pluginEnableState unavailable (host-owned config.toml) (#392)
    CLI codex plugin / codex plugin marketplace JSON contracts Implemented/Recorded pluginCliLifecycle and marketplaceCliLifecycle degraded — installer drives marketplace add + plugin add; list/remove/upgrade --json shapes pinned from live 0.147.0 probes in isolated CODEX_HOMEs (#392)
    features.plugins, features.hooks, codex_hooks, inline [hooks], requirements.toml Recorded featurePlugins, featureHooks, inlineHooksToml, managedRequirements unavailable — user/admin config layers outside the package (#392)
    allow_managed_hooks_only, restrict_to_allowed_sources Recorded Both unavailable — admin requirements applied at add/install/refresh; emitted hooks cannot opt out (#392)
    Submission/publish as distribution policy Recorded workspacePublishing and manifestPackage.submissionPolicy unavailable — portal-owned, never claimed as compiler behaviour (#352, #392)

    Overview-level rows (comment of 2026-09-01)

    Item Status Evidence
    Optional MCP UI Degraded plugin.overviewSurfaces.mcpUi — compiled MCP server serves ui:// MCP Apps resources per the open standard ChatGPT renders; Codex CLI 0.147.0 renders no components, tools remain usable (#415)
    Browser extensions Unavailable plugin.overviewSurfaces.browserExtensions — no schema-backed authoring field in the pinned manifest/package contract; nothing inferred (#415)
    Scheduled task templates Unavailable plugin.overviewSurfaces.scheduledTaskTemplates — same reason (#415)

    Acceptance

    • No documented Codex surface remains implicit: every checklist item maps to a four-state row with dated evidence above.
    • Requested unsupported behaviour fails before publication: closed hooks object, codex.native-hooks.* and codex.marketplace.* diagnostics, tightened marketplace/plugin schemas.
    • Compile semantic Agent event routes into native host hooks #97 keeps canonical event-route expansion; this issue covered native Codex manifest/hook/lifecycle fidelity only.

    Automated-review thread inventory (found / fixed / replied)

    PR Found Fixed Replied Rounds Notes
    #378 1 1 1 1 Non-object tool_input/tool_response — fixed in follow-up #404
    #404 0 — — 1 Codex review completed with no findings
    #392 11 11 11 6 NOT_AVAILABLE rejection; Git/registry URL structure; line-terminator traversal; port range; IPv4 range; npm version grammar; bracketed IPv6; semver whitespace; dot-prefixed dist-tags; git check-ref-format refs; RFC 3986 userinfo — each with admitted/rejected fixtures
    #415 2 2 2 2 Changeset bump minor → patch; summary ends with (#415)

    Each PR merged only after CI was green and the reviewer's final pass on the head commit reported no findings.

    Known gap outside this issue

    packed-native-smoke.test.ts fails in test support before any Codex logic runs (npm pack --json returns four workspace entries instead of one); it is a harness issue independent of the Codex adapter and is not fixed here.

  9. ScriptedAlchemy commented on Sep 3, 2026

    @ScriptedAlchemy
    ScriptedAlchemy
    on Sep 3, 2026
    OwnerAuthor

    Closing: all checklist items implemented, delegated, or recorded as dated four-state rows (evidence table above). Merged: #378, #404, #392, #415.

  10. ScriptedAlchemy
    closed this as completedon Sep 3, 2026
  11. ScriptedAlchemy
    added 4 commits that reference this issue on Sep 3, 2026

    chore(changeset): record the unified plugin revision as 1.24.0 → 1.25…

    4bb55e9

    chore(changeset): record the unified plugin revision as 1.24.0 → 1.25…

    70620c3

    chore(changeset): record the unified plugin revision as 1.24.0 → 1.25…

    be50997

    feat(cursor): refresh plugin contract coverage against the 2026-09-02…

    60445ec
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesthost-integrationAgent host capabilities, projection, discovery, and lifecyclemeta-frameworkAgent Bundle compiler-coupled meta-framework

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions