[codex] Define and validate native Codex support for plugin agents #1161

Problem

The repository publishes .codex-plugin/plugin.json manifests containing GitHub-style agents entries and ships .agent.md files with tools and handoffs, but those constructs are not portable Agent Plugins 1.0 components and are not documented as native OpenAI Codex plugin agent packaging.

Current specifications distinguish these systems:

• Agent Plugins 1.0 defines portable Skills and MCP servers.
• OpenAI's plugin extension documents skills, MCP, apps/UI, and hooks, but not packaged custom agents or static handoff graphs.
• Native Codex custom agents use .codex/agents/*.toml with developer_instructions and model/tool configuration.
• GitHub Copilot custom agents use .agent.md and host-specific frontmatter.

The validator's agent tool-portability table currently covers Copilot, Claude Code, and Gemini CLI, but not native Codex. #1127 demonstrates that a Codex-specific manifest incompatibility can pass repository validation and silently remove functionality.

Impact

Users can reasonably assume that installing the Codex marketplace plugin exposes the same agents and handoffs as Copilot, even though current documentation does not establish that behavior. Tool aliases and metadata may also be silently ignored or misinterpreted.

Proposed work

• Document the supported Codex surface explicitly: portable skills/MCP versus host-specific agents.
• Decide whether native Codex agent definitions should be generated or maintained separately under a supported .codex/agents/*.toml installation path.
• Define how dynamic delegation replaces Copilot/IDE handoffs where static handoffs are unavailable.
• Add Codex-specific manifest/schema validation instead of assuming root, Claude, and Codex manifests can always be identical.
• Add an integration lane using a supported Codex CLI version to verify plugin installation, skill discovery, MCP parsing, and any claimed agent behavior.
• Extend tool portability validation only after mapping official Codex tool/config semantics.

Acceptance criteria

• Repository documentation does not imply .agent.md portability to native Codex.
• Every feature claimed for Codex is covered by a native Codex installation/discovery test.
• Unsupported top-level manifest fields are rejected or moved under an appropriate host extension.
• Codex-specific tool and MCP configuration is validated against a supported Codex parser.
• The relationship among portable skills, Copilot custom agents, native Codex custom agents, and Agents SDK handoffs is documented.