declare custom subagents inside a plugin manifest (plugin.json)

What variant of Codex are you using?

CLI

What feature would you like to see?

Problem

Currently, custom subagents must be installed as standalone .toml files into $CODEX_HOME/agents/ (or .codex/agents/ for per-repo scope). There is no way to bundle a subagent declaration inside a plugin — the plugin.json manifest has no agents field.

This means plugin authors who ship custom subagents must side-channel them outside the plugin bundle, breaking the "self-contained installable unit" promise of the plugin system. Users have to manually place agent files in the right directory rather than getting them automatically on codex plugin add.

Proposed change

Add an agents key to plugin.json that accepts an array of paths to .toml agent definitions:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "skills": ["./skills/"],
  "agents": ["./agents/my-agent.toml"]
}

On codex plugin add, Codex would install those agent files into the appropriate agents directory alongside the rest of the plugin's components. On codex plugin remove, they'd be cleaned up.

Why this matters

Plugin authors can ship a fully self-contained bundle — skills, MCP servers, app connectors, and agents — in one installable unit.
Users get a single codex plugin add command instead of a multi-step install that mixes plugin + manual file drops.
It makes codex plugin remove a clean uninstall rather than leaving orphaned agent files behind.

Current workaround

Ship agent .toml files separately and document a manual copy step into $CODEX_HOME/agents/. This is what projects like polygraph-skills currently do.

Additional information

_No response_