Codex CLI 0.153: Make Remote Plugins a First-Class Part of Your Agent’s Supply-Chain Policy

Codex CLI 0.153 introduces a plugin command that can list, install, and remove plugins from remote marketplaces and improves session reconnection behavior. That changes the security question from whether an agent can call a tool to which external extension code is allowed into the runtime and how in‑flight work survives reconnects. This tutorial turns those platform changes into a repeatable developer workflow for safe installation, validation, rollback and recovery testing.

Key takeaways

  • Codex CLI 0.153 adds remote plugin management and improved session reconnection.
  • Treat plugin installs as supply‑chain events: record version, immutable digest, capabilities, approver and removal command.
  • Test reconnect scenarios: classify calls as Prepared, In flight, Accepted, Unknown, Reconciled and reconcile before retrying side effects.

Outcome and prerequisites

Outcome: after following this guide you will have a reproducible process to install remote Codex plugins safely, record their provenance for later rollback, and test reconnection and reconciliation semantics for side‑effecting tool calls.

Prerequisites

  • Codex CLI 0.153.0 installed in the environment (release notes list the plugin CLI and reconnect behavior).
  • A disposable workspace or container to test plugin installs without affecting production data.
  • Access to the remote plugin marketplace client (the release adds a plugin marketplace client).
  • A destination service for testing side effects that supports idempotency keys or readback queries (e.g., an API that returns resource IDs).

Why supply‑chain policy matters for remote plugins

The plugin marketplace client reduces friction for installing extensions, but it also makes plugin provenance part of the runtime’s security model. A plugin that claims to “format code” can still reach files, spawn shells, or call network endpoints through host integrations. Therefore a simple name‑based allowlist is insufficient: policy should include immutable artifact digests, capability mapping (filesystem/network/credentials), approver metadata and an explicit rollback path that does not depend on the plugin itself.

Record these fields outside the plugin bundle so removal and rollback do not depend on the plugin:

  • plugin_name — marketplace package name
  • marketplace_url — canonical source
  • version — exact version string
  • immutable_digest — commit SHA or content digest when available
  • effective_capabilities — filesystem paths, network destinations, and credential scopes the plugin can reach
  • approver — person or policy that approved the installation
  • approval_expiry — date/time when re‑approval is required
  • removal_command — recorded CLI command or script to uninstall and purge persisted state

Step-by-step: safe plugin install workflow

  1. Prepare a disposable workspace
    1. Launch a container or VM snapshot to test installs. Do not use production accounts or credentials.
  2. Pin the CLI and capture the release commit
    1. Record the Codex CLI version and release commit used to perform installs so you can reproduce behavior later (the release notes show the plugin CLI feature added in 0.153.0).
  3. List marketplace metadata before installing
    1. Use the new plugin command to list available plugins and their metadata. Capture the marketplace URL, version and any reported digest fields.
  4. Inspect the plugin’s effective capabilities
    1. Before install, request or review the plugin manifest and map what hosts and API surfaces it uses: filesystem paths, exec hooks, outbound network endpoints and credential access points. Treat this mapping as the plugin’s effective_capabilities.
  5. Require and record approval
    1. Have an approver (person or policy) sign off and record approver, approval_expiry and approval scope. Store this outside the plugin (in a config repository or policy database).
  6. Install and capture immutable identifiers
    1. Install the plugin with the CLI. Immediately capture the installed version and any immutable digest produced by the marketplace. Store the removal_command (the CLI uninstall invocation) in your policy record.
  7. Verify runtime isolation and credential scoping
    1. Confirm the plugin runs with the least privilege necessary. Ensure it cannot access credentials beyond its declared scope. If host integration requires executable hooks, verify the host path context used for permission preapproval.

Testing reconnect and side‑effect reconciliation

Codex CLI 0.153 improves TUI reconnection so drafts and transcripts survive an app‑server disconnect, but preserved state does not guarantee safe replay of in‑flight tool calls. Treat reconnect as state recovery, not proof that an action is safe to repeat. Use the following tests:

  1. Simulate a disconnect during a side‑effecting call
    1. In your disposable workspace, initiate a tool call that performs a real action (e.g., create a test resource). Kill or stop the app‑server mid‑call to force an “unknown” state.
  2. Confirm draft and transcript recovery
    1. Reconnect the TUI. Verify the draft and transcript are preserved and that queued or uncertain submissions remain paused for review (the release notes say reconnect preserves drafts and transcripts while pausing uncertain submissions).
  3. Classify execution state and reconcile
    1. Adopt the execution state model: Prepared, In flight, Accepted (destination returned durable ID), Unknown (response lost), Reconciled (external state confirmed).
    2. For any call classified as Unknown, perform reconciliation: query the external service for the resource or use an idempotency key before retrying. Do not blindly replay.
  4. Verify idempotency and readback
    1. Where possible, include idempotency keys in requests and verify that retrying with the same key does not create duplicates. If the destination supports no idempotency, implement a readback that verifies whether the intended side effect already occurred before performing it again.

Rollback and uninstall testing

Record a removal and rollback path that does not depend on the plugin itself. Tests should confirm uninstallation clears persisted state.

  1. Execute recorded removal_command in the disposable workspace.
  2. Verify that plugin files, persisted config and any host‑side hooks are removed.
  3. Test that the agent no longer invokes the plugin’s capabilities and that any approvals tied to its name or digest are revoked.

Common failures and troubleshooting

  • Missing immutable digest: Marketplace metadata may not include an immutable digest. If absent, require stricter approval (manual code review or reject installs) or mirror the plugin artifact in an internal registry where a digest can be computed.
  • Plugin can access unexpected paths: Tighten the effective_capabilities mapping and revalidate host integration contexts. On macOS, be aware of relative path issues when spawning MCP servers; confirm the executor path context used for permission preapproval.
  • Reconnected session shows drafts but side effects already happened: Treat these as Unknown→Reconciled workflow; query the destination for evidence before retrying. Do not rely on reconnect to mean the external action failed or succeeded.
  • Removal command fails to clear state: Ensure the recorded removal_command includes steps to purge persisted state. If the plugin stores state externally, include explicit cleanup steps in the policy record.

Practical trade‑offs

Adding strict policy controls increases deployment friction but reduces risk from unvetted code entering a privileged runtime. Mirroring artifacts internally adds storage and release‑management overhead but gives immutable digests and consistent installs. Idempotency and readback add implementation cost to destination services but are necessary to safely reconcile unknown states after reconnects.

Quick checklist

  • Pin Codex CLI version and record the release commit.
  • Install plugins only in disposable workspaces first.
  • Capture marketplace URL, version and immutable_digest when available.
  • Map effective_capabilities and scope credentials tightly.
  • Require recorded approval with an expiry.
  • Record an explicit removal_command and test rollback.
  • Test reconnection during side effects; use idempotency/readback before retrying.

FAQ

Does reconnect mean it’s safe to retry every request?

No. Reconnect preserves the agent’s draft and transcript state but does not prove whether an in‑flight external call succeeded. Use idempotency keys or readback reconciliation before retrying.

Is a name-based allowlist sufficient?

No. Two versions of the same plugin can differ. Record the immutable digest and effective capabilities for each installation, and require reapproval on version changes or on expiry.

What if the marketplace doesn’t provide digests?

Mirror the plugin artifact in an internal registry where you compute and record a digest, or require additional manual review before approving installs.

Short closing note

Codex CLI 0.153 makes extension provenance and session recovery explicit concerns for agent operators. Treat remote plugins as code entering a privileged runtime: enforce provenance, capability boundaries and rollback, and treat reconnect as state recovery that requires reconciliation before retrying side effects.

Stay in Touch

spot_img

Related Articles