Extensions, Plugins, and Capabilities
Overview
This area is the Codex extension surface: typed extension hooks, plugin/package discovery, built-in capability extensions, MCP client/server plumbing, and capability-specific helper crates. The central contract is codex-rs/…/lib.rs, which re-exports the host-facing API: ExtensionRegistryBuilder, ExtensionRegistry, typed lifecycle contributor traits, ExtensionData, ToolExecutor/ToolCall/ToolSpec from the tool layer, MCP types from codex-rs/…/lib.rs, and model/request interception types. Host code installs extensions by adding trait objects to ExtensionRegistryBuilder in codex-rs/…/registry.rs; the immutable registry preserves registration order and exposes contributor slices for thread, turn, prompt/world-state, MCP, turn-input, tool, model-request, message, approval, token, skill-invocation, and turn-item phases.
Extension state is explicit and scoped. codex-rs/…/state.rs stores type-erased Arc<T> attachments in ExtensionData for session, thread, turn, and step scopes; contributors communicate by inserting and reading typed values rather than holding core runtime objects. codex-rs/…/contributors.rs defines the execution shape: ThreadLifecycleContributor seeds and flushes thread state, TurnLifecycleContributor refreshes catalogs and observes turn stop/abort/error, ContextContributor adds prompt/world-state fragments, TurnInputContributor adds model-visible per-turn fragments, ToolContributor prepares step state and returns native tools, and ToolLifecycleContributor observes dispatch/start/finish/timing without owning execution. codex-rs/…/session_isolation.rs lets internal sessions opt out of inherited extensions and instructions through SessionIsolation::Isolated and supply an explicit isolated registry.
Plugin metadata is split between inert shared models and host/runtime loaders. codex-rs/…/manifest.rs defines the generic PluginManifest<Resource> shape: name/version/description/keywords, paths for skills, onboarding skill, MCP servers, apps, hooks, and optional UI/model interface metadata. codex-rs/…/provider.rs turns a manifest into an authority-bound ResolvedPlugin whose PluginResourceLocator keeps the owning environment and URI with every resource. Local plugin IDs and installed-package rules live in codex-rs/…/lib.rs; codex-rs/…/lib.rs adds public identifiers, loaded-plugin summaries, app declarations, hook-source metadata, and telemetry metadata.
codex-rs/…/lib.rs is the main plugin manager facade. Runtime loading starts in codex-rs/…/manager.rs: PluginsManager::plugins_for_config derives a cache key from effective plugin config, plugin policy, skill rules, remote-catalog state, and account identity, then calls load_plugins_from_layer_stack in codex-rs/…/loader.rs. The loader merges configured local plugins with remote-installed plugins, enforces plugin policy, loads up to eight plugins concurrently while preserving configured-name order, parses manifests, resolves skill roots, MCP server configs, app declarations, and hooks, and emits PluginLoadOutcome. Hooks can be loaded alone through load_plugin_hooks_from_layer_stack, which intentionally skips skills/MCP/apps. codex-rs/…/manifest.rs parses both legacy manifests and agent-plugin manifests, validates manifest-relative ./... paths, rejects ../absolute escapes, and maps URI manifests for executor-owned plugins. codex-rs/…/executor_provider.rs resolves selected capability roots in executor filesystems into ResolvedExecutorPlugin, keeping the exact ExecutorFileSystem used to read later plugin resources. Source-neutral cloud/executor plugin catalogs are merged in codex-rs/…/catalog.rs, where complete cloud catalogs can disable unmatched remote entries while partial catalogs preserve executor-only entries.
MCP support has two layers. codex-rs/…/lib.rs wraps the official rmcp SDK and exposes RmcpClient, transports, OAuth helpers, request cancellation, auth status, event notifications, and user verification. The implementation in codex-rs/…/rmcp_client.rs supports in-process, stdio, streamable HTTP, OAuth-managed HTTP, and access-token-only HTTP transports. It performs initialization once, stores a RunningService, lists tools/resources/templates, reads resources, calls tools, sends custom requests/notifications, opens event streams, persists/refetches OAuth tokens, applies read-only tool metadata, and routes modern request-scoped elicitation only on protocol 2026-07-28. codex-rs/…/lib.rs builds on this client to provide Codex MCP runtime/catalog/resource APIs, app-hosted server configuration, server conflict handling, connector metadata recovery, sandbox/network metadata, authorization elicitation, OAuth scope discovery, tool request metadata, and backwards-compatible Codex Apps runtime aliases.
The default hosted Apps MCP contribution is installed by codex-rs/…/lib.rs. HostedPluginRuntimeExtension contributes CODEX_APPS_MCP_SERVER_NAME using hosted_plugin_runtime_mcp_server_config when Feature::Apps is enabled and returns a remove contribution when it is not. The same crate also exposes plugin-provider installation and event-stream management. A separate MCP adapter in codex-rs/…/lib.rs binds existing message-board tools to an MCP server per caller; request metadata never selects identity, and MessageBoardMcpServer::new fixes the caller thread/path and board instance. Its detached HTTP binary in codex-rs/…/main.rs opens Codex SQLite state, validates a configured bearer token, and serves /mcp with allowed-host checks.
Built-in capability extensions register through the same extension API:
- codex-rs/…/extension.rs installs thread lifecycle, config, prompt/world-state, turn-input, skill-invocation, turn-lifecycle telemetry, and tool contributors. It seeds
SkillsSessionState/SkillsThreadState, renders available-skill catalog fragments, prepares step catalogs, injects explicit skill prompts, tracks implicit/explicit invocations, and returns namespacedskillstools from codex-rs/…/mod.rs (list,read, and discovery-v2installations). The standalone skill library in codex-rs/…/lib.rs parses skill metadata/frontmatter, extracts explicit/implicit mentions, loads skill roots, resolves interface files, and installs embedded system skills underCODEX_HOME/skills/.systemwith a fingerprint marker. - codex-rs/…/extension.rs installs memory prompt context and optional dedicated memory tools when
Feature::MemoryToolandconfig.memories.use_memoriesare enabled. It freezes the selectedMemoryVersionon config changes so the prompt summary and tool namespace stay aligned. codex-rs/…/mod.rs exposes namespacedmemoriestools for ad-hoc note creation, listing, reading, and searching againstLocalMemoriesBackend. codex-rs/…/lib.rs owns read-path helpers andmemory_root; codex-rs/…/lib.rs owns the startup write pipeline, memory workspace layout, rollout summaries, raw memory file, extension resources, pruning, and symlink cleanup. - codex-rs/…/plugin_app.rs loads app declarations from executor-resolved plugins by reading the manifest's
paths.appsthrough the plugin'sExecutorFileSystemand parsing it withcodex_connectors::parse_plugin_app_config. Connector directory and runtime data live in codex-rs/…/lib.rs: it caches directory listings in memory and on disk for one hour, merges public and workspace connector pages, normalizes names/descriptions/install URLs, parses plugin app config, projects installed connector runtimes, stores metadata, and evaluates app tool policy. - codex-rs/…/extension.rs contributes a
web.run-style tool when the provider supports standalone search and the step'sWebSearchModeis not disabled. It copies location/filter/search-size config, chooses OpenAI/provider auth from thread state or the extension'sAuthManager, and writes extension items defined in codex-rs/…/lib.rs underweb.search. - codex-rs/…/extension.rs contributes the
image_gen.imagegentool for OpenAI-compatible providers, resolves an optional save root from config, and emitsimage_gen.generationitems from codex-rs/…/lib.rs. - codex-rs/…/lib.rs registers a caller-owned
QueuedItemServiceas a thread lifecycle contributor and spawns its external-message watcher so queued user input can be dispatched when a thread becomes idle. - codex-rs/…/lib.rs starts resolved agent invocations by spawning a legacy subagent thread through
ThreadManager::spawn_legacy_subagentand submitting the rendered prompt as the initial user input. codex-rs/…/lib.rs installs board-backed tools overcodex_message_boardand selects theagent_message_boardstorage namespace. - codex-rs/…/lib.rs, codex-rs/…/lib.rs, and codex-rs/…/lib.rs cover Guardian review integration. V2 installs async scoring and synchronous approval review; V3 owns durable evidence boards in the
guardiannamespace; the reviewer crate owns review prompts, routing, retries, deadlines, evidence records, and review outcomes independently of the host runtime. - codex-rs/…/lib.rs, codex-rs/…/lib.rs, codex-rs/…/lib.rs, and codex-rs/…/lib.rs are smaller extension crates for goal tools/runtime, history-note tools, cross-environment file copy, and git attribution world-state respectively. Git attribution resolves a policy over the configured ChatGPT base URL and caches retry state in extension stores.
Other covered crates are support capabilities rather than registry-installed extensions. codex-rs/…/lib.rs and its submodules manage a dedicated V8 plugin helper process: PluginProcess::spawn launches an absolute helper path with --codex-ui-plugin-process, clears the environment, waits for the codex-ui-plugin-process/3 ready frame, frames stdin/stdout with a 1 MiB little-endian length-delimited codec, captures only the last 16 KiB of stderr, and tears down the process group or Windows job on close/drop. codex-rs/…/protocol.rs defines the narrow ABI (Initialize, Dispatch, Close; Initialized, Pending, Reply, Error, Closed) and size/quota constants. codex-rs/…/lib.rs imports external-agent MCP, hooks, memory, subagents, plugins, and sessions into Codex config. codex-rs/…/lib.rs is a bounded terminal renderer for a subset of Mermaid diagrams. codex-rs/…/lib.rs embeds default and plan collaboration prompts. codex-rs/…/lib.rs derives ExperimentalApi by generating field/variant presence checks and inventory registrations for fields marked #[experimental("reason")] or nested fields marked #[experimental(nested)].
Path routing notes for this doc:
codex-rs/ext/extension-api/**owns the extension API contract and registry; othercodex-rs/ext/*/**crates are built-in extensions/capabilities.codex-rs/plugin/**,codex-rs/core-plugin-common/**,codex-rs/core-plugins/**, andcodex-rs/plugin-host/**own plugin manifests, identities, marketplaces/cache/loading, executor plugin resolution, and helper-process IPC.codex-rs/codex-mcp/**,codex-rs/rmcp-client/**, andcodex-rs/message-board-mcp/**own MCP runtime/client/server behavior.codex-rs/skills/**andcodex-rs/memories/**are lower-level skill and memory libraries used by the corresponding extension crates.codex-rs/connectors/**is connector/app directory and runtime support;codex-rs/ext/connectors/**adapts plugin app declarations into the extension/plugin flow.codex-rs/external-agent-migration/**,codex-rs/collaboration-mode-templates/**,codex-rs/mermaid/**, andcodex-rs/codex-experimental-api-macros/**are adjacent capabilities covered here because they participate in extension/plugin-facing features or model-visible capability surfaces.
Coupling
- If adding a new extension lifecycle hook in codex-rs/…/contributors.rs, also update codex-rs/…/registry.rs and codex-rs/…/lib.rs; otherwise extensions can implement a trait that hosts cannot register or hosts cannot access.
- If changing
ExtensionDatasemantics in codex-rs/…/state.rs, audit built-in extensions that rely on typed cross-phase state: skills in codex-rs/…/extension.rs, memories in codex-rs/…/extension.rs, web search in codex-rs/…/extension.rs, image generation in codex-rs/…/extension.rs, and git attribution in codex-rs/…/lib.rs. - If changing plugin manifest path rules in codex-rs/…/manifest.rs, verify executor plugin resolution in codex-rs/…/executor_provider.rs and shared descriptors in codex-rs/…/provider.rs; host and executor sources are expected to parse the same manifest while retaining different resource authorities.
- If changing plugin capability fields in codex-rs/…/manifest.rs or codex-rs/…/lib.rs, update loading/projection in codex-rs/…/loader.rs, details/telemetry in codex-rs/…/manager.rs, and app declaration parsing in codex-rs/…/plugin_app.rs when the field points at connector resources.
- If changing MCP protocol-mode or request-scoped input behavior in codex-rs/…/rmcp_client.rs, also verify codex-rs/…/lib.rs exports and the hosted Apps contribution in codex-rs/…/lib.rs; modern tool/resource elicitation is deliberately rejected for legacy sessions.
- If changing skill catalog or tool authority in codex-rs/…/extension.rs or codex-rs/…/mod.rs, verify lower-level parsing/loading in codex-rs/…/lib.rs and plugin skill-root loading in codex-rs/…/loader.rs; plugin skill roots and host/executor/cloud authority determine whether a skill can be read directly or must be read through MCP/executor resources.
- If changing memory versioning or tool enablement in codex-rs/…/extension.rs, verify codex-rs/…/lib.rs and codex-rs/…/lib.rs; the extension intentionally preserves the original
MemoryVersionacross config changes so read instructions and tools use the same on-disk namespace. - If changing plugin-host framing or protocol constants in codex-rs/…/framing.rs, codex-rs/…/protocol.rs, or codex-rs/…/lib.rs, update the V8 helper process in lockstep; the Rust host expects the exact ready frame and bounded packet schema before it will send plugin messages.
Risks
- codex-rs/…/process.rs clears the helper environment, requires an absolute canonical helper path, and kills the whole helper process group/job on drop. If helper startup begins depending on inherited environment variables or child processes retain stderr writers, startup can fail with only a bounded stderr tail or teardown can hang until process cleanup finishes.
- codex-rs/…/rmcp_client.rs multiplexes shared MCP connections, OAuth refresh, recovery retries, cancellation, and request-scoped elicitation. If a call path uses cached capabilities or a stale service rather than the current
RunningService, a recovered HTTP/stdout session can send tool metadata or elicitation to the wrong MCP session. - codex-rs/…/manager.rs caches loaded plugins by config, policy, skill rules, remote-catalog activity, and auth identity. If new plugin-affecting configuration is not included in
PluginLoadCacheKey, users can see stale skills/MCP servers/apps until the cache is manually cleared. - codex-rs/…/loader.rs preserves configured-name order for duplicate MCP server precedence while loading plugins concurrently. If that ordered consumption is changed, the winning plugin for a duplicate server name can become nondeterministic.
- codex-rs/…/extension.rs reads skill prompts through different authorities for host, executor, cloud, and custom sources. If a new skill source bypasses
SkillToolAuthority/SkillReadContextchecks, model-visible skill reads can cross environment or MCP authority boundaries. - codex-rs/…/extension.rs intentionally keeps the initial memory version after config changes. If this freeze is removed, a thread can render memory instructions for one layout while exposing tools against another layout, causing missing or stale memory reads.