Install a reviewed plugin release under an existing marketplace identity without changing its source checkout

What variant of Codex are you using?

Codex CLI 0.153.4 on macOS (native Intel).

What feature would you like to see?

Allow one installation to select a reviewed immutable plugin payload or exact revision under an existing plugin/marketplace identity, without editing that marketplace entry or changing the development checkout.

For example, a user-managed marketplace registers example-plugin@personal from a local development directory. Development has advanced beyond the release selected for installation. codex plugin add example-plugin@personal reads the registered source; there is no plugin-add argument to select that release's separate verified payload.

A downstream installer can temporarily check out the release at the registered path and restore the development branch afterward. That requires checkout ownership, original-HEAD checks and interruption recovery. Redirecting the catalog to a staged directory or updating a Git pin introduces catalog mutation and recovery instead. An install-time selector would remove this coupling.

The requested behavior is:

• Accept an explicitly selected, validated release directory or supported exact revision for a user-managed plugin; bind the installation to the reviewed content and refuse a changed or mismatched input.
• Preserve the existing plugin ID, enabled state, unchanged approval settings and unrelated catalog entries. Leave the registered source entry and development HEAD/worktree untouched.
• Apply existing source restrictions and trust checks to the selected payload. Reusing a plugin name must not grant trust to arbitrary replacement code; require any new approval that policy calls for.
• Return the actual installed path, version and resolved source provenance in JSON, so the caller can verify which payload was installed. Document failure and interrupted-install outcomes.
• Keep ordinary plugin add behavior unchanged when no selector is supplied.

The exact interface is flexible. This request does not require automatic MCP reload, active-cache deletion, runtime dependency installation or a broader update transaction.

Additional information

Checked the installed CLI's help and offline generated protocol schema:

• plugin add --help exposes the plugin selector, marketplace selection and JSON output, but no per-install payload or revision selector.
• Git pinning already exists: plugin marketplace add --ref and Git-backed plugin entries with ref/sha are documented. They select the registered source; updating that source is the state change this use case seeks to avoid. See the CLI reference and marketplace metadata.
• Generated PluginInstallParams contains pluginName, marketplacePath, remoteMarketplaceName and installAttemptId. It has no alternate payload/revision field. The App Server docs also mark plugin installation APIs as under development, not for production clients.

Useful acceptance coverage: development checkout and catalog remain unchanged; installed bytes match the selected payload; identity/version mismatches and changed inputs are refused; unrelated settings survive; failure/readback identifies the actual installed state.

Related requests reviewed:

• #36347 changes marketplace source/ref transactionally. This request keeps the registration unchanged.
• #36540 proposes a full source/cache/configuration/MCP update transaction. This request concerns only the install source selector.
• #40457 loads a live development directory for one session. This request installs a selected release into the normal durable cache.

Start with codex plugin add --help and the generated PluginInstallParams schema, then review the existing marketplace source and trust-check behavior described in the CLI and marketplace documentation. The work is done when an install-time payload or revision selector preserves the registered checkout and catalog state, rejects mismatches, and reports the installed path, version, and provenance in JSON with failure outcomes.