codex: fix CI failure on PR #15747

Co-authored-by: Codex <noreply@openai.com>

codex-rs/Cargo.lock

@@ -1883,9 +1883,11 @@ dependencies = [
  "codex-features",
  "codex-git-utils",
  "codex-hooks",
+ "codex-instructions",
  "codex-login",
  "codex-network-proxy",
  "codex-otel",
+ "codex-plugin",
  "codex-protocol",
  "codex-rmcp-client",
  "codex-rollout",
@@ -1904,6 +1906,7 @@ dependencies = [
  "codex-utils-image",
  "codex-utils-output-truncation",
  "codex-utils-path",
+ "codex-utils-plugins",
  "codex-utils-pty",
  "codex-utils-readiness",
  "codex-utils-stream-parser",
@@ -2174,6 +2177,15 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "codex-instructions"
+version = "0.0.0"
+dependencies = [
+ "codex-protocol",
+ "pretty_assertions",
+ "serde",
+]
+
 [[package]]
 name = "codex-keyring-store"
 version = "0.0.0"
@@ -2383,6 +2395,17 @@ dependencies = [
  "zip",
 ]
 
+[[package]]
+name = "codex-plugin"
+version = "0.0.0"
+dependencies = [
+ "codex-utils-absolute-path",
+ "codex-utils-plugins",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "codex-process-hardening"
 version = "0.0.0"
@@ -2937,6 +2960,15 @@ dependencies = [
  "tempfile",
 ]
 
+[[package]]
+name = "codex-utils-plugins"
+version = "0.0.0"
+dependencies = [
+ "serde",
+ "serde_json",
+ "tempfile",
+]
+
 [[package]]
 name = "codex-utils-pty"
 version = "0.0.0"

codex-rs/Cargo.toml

@@ -25,6 +25,7 @@ members = [
     "skills",
     "core",
     "hooks",
+    "instructions",
     "secrets",
     "exec",
     "exec-server",
@@ -68,6 +69,7 @@ members = [
     "utils/oss",
     "utils/output-truncation",
     "utils/path-utils",
+    "utils/plugins",
     "utils/fuzzy-match",
     "utils/stream-parser",
     "codex-client",
@@ -77,6 +79,7 @@ members = [
     "codex-experimental-api-macros",
     "test-macros",
     "package-manager",
+    "plugin",
     "artifacts",
 ]
 resolver = "2"
@@ -122,6 +125,7 @@ codex-features = { path = "features" }
 codex-file-search = { path = "file-search" }
 codex-git-utils = { path = "git-utils" }
 codex-hooks = { path = "hooks" }
+codex-instructions = { path = "instructions" }
 codex-keyring-store = { path = "keyring-store" }
 codex-linux-sandbox = { path = "linux-sandbox" }
 codex-lmstudio = { path = "lmstudio" }
@@ -130,6 +134,7 @@ codex-mcp-server = { path = "mcp-server" }
 codex-network-proxy = { path = "network-proxy" }
 codex-ollama = { path = "ollama" }
 codex-otel = { path = "otel" }
+codex-plugin = { path = "plugin" }
 codex-process-hardening = { path = "process-hardening" }
 codex-protocol = { path = "protocol" }
 codex-rollout = { path = "rollout" }
@@ -160,6 +165,7 @@ codex-utils-json-to-toml = { path = "utils/json-to-toml" }
 codex-utils-oss = { path = "utils/oss" }
 codex-utils-output-truncation = { path = "utils/output-truncation" }
 codex-utils-path = { path = "utils/path-utils" }
+codex-utils-plugins = { path = "utils/plugins" }
 codex-utils-pty = { path = "utils/pty" }
 codex-utils-readiness = { path = "utils/readiness" }
 codex-utils-rustls-provider = { path = "utils/rustls-provider" }

codex-rs/core/Cargo.toml

@@ -42,9 +42,11 @@ codex-skills = { workspace = true }
 codex-execpolicy = { workspace = true }
 codex-git-utils = { workspace = true }
 codex-hooks = { workspace = true }
+codex-instructions = { workspace = true }
 codex-network-proxy = { workspace = true }
 codex-otel = { workspace = true }
 codex-artifacts = { workspace = true }
+codex-plugin = { workspace = true }
 codex-protocol = { workspace = true }
 codex-rollout = { workspace = true }
 codex-rmcp-client = { workspace = true }
@@ -57,6 +59,7 @@ codex-utils-image = { workspace = true }
 codex-utils-home-dir = { workspace = true }
 codex-utils-output-truncation = { workspace = true }
 codex-utils-path = { workspace = true }
+codex-utils-plugins = { workspace = true }
 codex-utils-pty = { workspace = true }
 codex-utils-readiness = { workspace = true }
 codex-secrets = { workspace = true }

codex-rs/core/src/contextual_user_message.rs

@@ -1,14 +1,12 @@
+use codex_instructions::AGENTS_MD_FRAGMENT;
+use codex_instructions::ContextualUserFragmentDefinition;
+use codex_instructions::SKILL_FRAGMENT;
 use codex_protocol::items::HookPromptItem;
 use codex_protocol::items::parse_hook_prompt_fragment;
 use codex_protocol::models::ContentItem;
-use codex_protocol::models::ResponseItem;
 use codex_protocol::protocol::ENVIRONMENT_CONTEXT_CLOSE_TAG;
 use codex_protocol::protocol::ENVIRONMENT_CONTEXT_OPEN_TAG;
 
-pub(crate) const AGENTS_MD_START_MARKER: &str = "# AGENTS.md instructions for ";
-pub(crate) const AGENTS_MD_END_MARKER: &str = "</INSTRUCTIONS>";
-pub(crate) const SKILL_OPEN_TAG: &str = "<skill>";
-pub(crate) const SKILL_CLOSE_TAG: &str = "</skill>";
 pub(crate) const USER_SHELL_COMMAND_OPEN_TAG: &str = "<user_shell_command>";
 pub(crate) const USER_SHELL_COMMAND_CLOSE_TAG: &str = "</user_shell_command>";
 pub(crate) const TURN_ABORTED_OPEN_TAG: &str = "<turn_aborted>";
@@ -16,64 +14,11 @@ pub(crate) const TURN_ABORTED_CLOSE_TAG: &str = "</turn_aborted>";
 pub(crate) const SUBAGENT_NOTIFICATION_OPEN_TAG: &str = "<subagent_notification>";
 pub(crate) const SUBAGENT_NOTIFICATION_CLOSE_TAG: &str = "</subagent_notification>";
 
-#[derive(Clone, Copy)]
-pub(crate) struct ContextualUserFragmentDefinition {
-    start_marker: &'static str,
-    end_marker: &'static str,
-}
-
-impl ContextualUserFragmentDefinition {
-    pub(crate) const fn new(start_marker: &'static str, end_marker: &'static str) -> Self {
-        Self {
-            start_marker,
-            end_marker,
-        }
-    }
-
-    pub(crate) fn matches_text(&self, text: &str) -> bool {
-        let trimmed = text.trim_start();
-        let starts_with_marker = trimmed
-            .get(..self.start_marker.len())
-            .is_some_and(|candidate| candidate.eq_ignore_ascii_case(self.start_marker));
-        let trimmed = trimmed.trim_end();
-        let ends_with_marker = trimmed
-            .get(trimmed.len().saturating_sub(self.end_marker.len())..)
-            .is_some_and(|candidate| candidate.eq_ignore_ascii_case(self.end_marker));
-        starts_with_marker && ends_with_marker
-    }
-
-    pub(crate) const fn start_marker(&self) -> &'static str {
-        self.start_marker
-    }
-
-    pub(crate) const fn end_marker(&self) -> &'static str {
-        self.end_marker
-    }
-
-    pub(crate) fn wrap(&self, body: String) -> String {
-        format!("{}\n{}\n{}", self.start_marker, body, self.end_marker)
-    }
-
-    pub(crate) fn into_message(self, text: String) -> ResponseItem {
-        ResponseItem::Message {
-            id: None,
-            role: "user".to_string(),
-            content: vec![ContentItem::InputText { text }],
-            end_turn: None,
-            phase: None,
-        }
-    }
-}
-
-pub(crate) const AGENTS_MD_FRAGMENT: ContextualUserFragmentDefinition =
-    ContextualUserFragmentDefinition::new(AGENTS_MD_START_MARKER, AGENTS_MD_END_MARKER);
 pub(crate) const ENVIRONMENT_CONTEXT_FRAGMENT: ContextualUserFragmentDefinition =
     ContextualUserFragmentDefinition::new(
         ENVIRONMENT_CONTEXT_OPEN_TAG,
         ENVIRONMENT_CONTEXT_CLOSE_TAG,
     );
-pub(crate) const SKILL_FRAGMENT: ContextualUserFragmentDefinition =
-    ContextualUserFragmentDefinition::new(SKILL_OPEN_TAG, SKILL_CLOSE_TAG);
 pub(crate) const USER_SHELL_COMMAND_FRAGMENT: ContextualUserFragmentDefinition =
     ContextualUserFragmentDefinition::new(
         USER_SHELL_COMMAND_OPEN_TAG,

codex-rs/core/src/contextual_user_message_tests.rs

@@ -1,6 +1,7 @@
 use super::*;
 use codex_protocol::items::HookPromptFragment;
 use codex_protocol::items::build_hook_prompt_message;
+use codex_protocol::models::ResponseItem;
 
 #[test]
 fn detects_environment_context_fragment() {

codex-rs/core/src/instructions/mod.rs

@@ -1,5 +1,3 @@
-mod user_instructions;
-
-pub(crate) use user_instructions::SkillInstructions;
-pub use user_instructions::USER_INSTRUCTIONS_PREFIX;
-pub(crate) use user_instructions::UserInstructions;
+pub(crate) use codex_instructions::SkillInstructions;
+pub use codex_instructions::USER_INSTRUCTIONS_PREFIX;
+pub(crate) use codex_instructions::UserInstructions;

codex-rs/core/src/mention_syntax.rs

@@ -1,4 +1,2 @@
-// Default plaintext sigil for tools.
-pub const TOOL_MENTION_SIGIL: char = '$';
-// Plugins use `@` in linked plaintext outside TUI.
-pub const PLUGIN_TEXT_MENTION_SIGIL: char = '@';
+pub use codex_utils_plugins::mention_syntax::PLUGIN_TEXT_MENTION_SIGIL;
+pub use codex_utils_plugins::mention_syntax::TOOL_MENTION_SIGIL;

codex-rs/core/src/plugins/manager.rs

@@ -1,3 +1,5 @@
+use super::LoadedPlugin;
+use super::PluginLoadOutcome;
 use super::PluginManifestPaths;
 use super::curated_plugins_repo_path;
 use super::load_plugin_manifest;
@@ -20,14 +22,11 @@ use super::remote::fetch_remote_featured_plugin_ids;
 use super::remote::fetch_remote_plugin_status;
 use super::remote::uninstall_remote_plugin;
 use super::startup_sync::start_startup_remote_plugin_sync_once;
-use super::store::PluginId;
-use super::store::PluginIdError;
 use super::store::PluginInstallResult as StorePluginInstallResult;
 use super::store::PluginStore;
 use super::store::PluginStoreError;
 use super::sync_openai_plugins_repo;
 use crate::AuthManager;
-use crate::analytics_client::AnalyticsEventsClient;
 use crate::auth::CodexAuth;
 use crate::config::Config;
 use crate::config::ConfigService;
@@ -46,6 +45,12 @@ use crate::skills::loader::load_skills_from_roots;
 use codex_app_server_protocol::ConfigValueWriteParams;
 use codex_app_server_protocol::MergeStrategy;
 use codex_features::Feature;
+use codex_plugin::AppConnectorId;
+use codex_plugin::PluginCapabilitySummary;
+use codex_plugin::PluginId;
+use codex_plugin::PluginIdError;
+use codex_plugin::PluginTelemetryMetadata;
+use codex_plugin::prompt_safe_plugin_description;
 use codex_protocol::protocol::Product;
 use codex_protocol::protocol::SkillScope;
 use codex_utils_absolute_path::AbsolutePathBuf;
@@ -68,12 +73,13 @@ use toml_edit::value;
 use tracing::info;
 use tracing::warn;
 
+use crate::AnalyticsEventsClient;
+
 const DEFAULT_SKILLS_DIR_NAME: &str = "skills";
 const DEFAULT_MCP_CONFIG_FILE: &str = ".mcp.json";
 const DEFAULT_APP_CONFIG_FILE: &str = ".app.json";
 pub const OPENAI_CURATED_MARKETPLACE_NAME: &str = "openai-curated";
 static CURATED_REPO_SYNC_STARTED: AtomicBool = AtomicBool::new(false);
-const MAX_CAPABILITY_SUMMARY_DESCRIPTION_LEN: usize = 1024;
 const FEATURED_PLUGIN_IDS_CACHE_TTL: std::time::Duration =
     std::time::Duration::from_secs(60 * 60 * 3);
 
@@ -114,9 +120,6 @@ fn featured_plugin_ids_cache_key(
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub struct AppConnectorId(pub String);
-
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginInstallRequest {
     pub plugin_name: String,
@@ -185,89 +188,6 @@ pub struct ConfiguredMarketplaceListOutcome {
     pub errors: Vec<MarketplaceListError>,
 }
 
-#[derive(Debug, Clone, PartialEq)]
-pub struct LoadedPlugin {
-    pub config_name: String,
-    pub manifest_name: Option<String>,
-    pub manifest_description: Option<String>,
-    pub root: AbsolutePathBuf,
-    pub enabled: bool,
-    pub skill_roots: Vec<PathBuf>,
-    pub disabled_skill_paths: HashSet<PathBuf>,
-    pub has_enabled_skills: bool,
-    pub mcp_servers: HashMap<String, McpServerConfig>,
-    pub apps: Vec<AppConnectorId>,
-    pub error: Option<String>,
-}
-
-impl LoadedPlugin {
-    fn is_active(&self) -> bool {
-        self.enabled && self.error.is_none()
-    }
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
-pub struct PluginCapabilitySummary {
-    pub config_name: String,
-    pub display_name: String,
-    pub description: Option<String>,
-    pub has_skills: bool,
-    pub mcp_server_names: Vec<String>,
-    pub app_connector_ids: Vec<AppConnectorId>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct PluginTelemetryMetadata {
-    pub plugin_id: PluginId,
-    pub capability_summary: Option<PluginCapabilitySummary>,
-}
-
-impl PluginTelemetryMetadata {
-    pub fn from_plugin_id(plugin_id: &PluginId) -> Self {
-        Self {
-            plugin_id: plugin_id.clone(),
-            capability_summary: None,
-        }
-    }
-}
-
-impl PluginCapabilitySummary {
-    fn from_plugin(plugin: &LoadedPlugin) -> Option<Self> {
-        if !plugin.is_active() {
-            return None;
-        }
-
-        let mut mcp_server_names: Vec<String> = plugin.mcp_servers.keys().cloned().collect();
-        mcp_server_names.sort_unstable();
-
-        let summary = Self {
-            config_name: plugin.config_name.clone(),
-            display_name: plugin
-                .manifest_name
-                .clone()
-                .unwrap_or_else(|| plugin.config_name.clone()),
-            description: prompt_safe_plugin_description(plugin.manifest_description.as_deref()),
-            has_skills: plugin.has_enabled_skills,
-            mcp_server_names,
-            app_connector_ids: plugin.apps.clone(),
-        };
-
-        (summary.has_skills
-            || !summary.mcp_server_names.is_empty()
-            || !summary.app_connector_ids.is_empty())
-        .then_some(summary)
-    }
-
-    pub fn telemetry_metadata(&self) -> Option<PluginTelemetryMetadata> {
-        PluginId::parse(&self.config_name)
-            .ok()
-            .map(|plugin_id| PluginTelemetryMetadata {
-                plugin_id,
-                capability_summary: Some(self.clone()),
-            })
-    }
-}
-
 impl From<PluginDetail> for PluginCapabilitySummary {
     fn from(value: PluginDetail) -> Self {
         let has_skills = value.skills.iter().any(|skill| {
@@ -286,95 +206,6 @@ impl From<PluginDetail> for PluginCapabilitySummary {
     }
 }
 
-fn prompt_safe_plugin_description(description: Option<&str>) -> Option<String> {
-    let description = description?
-        .split_whitespace()
-        .collect::<Vec<_>>()
-        .join(" ");
-    if description.is_empty() {
-        return None;
-    }
-
-    Some(
-        description
-            .chars()
-            .take(MAX_CAPABILITY_SUMMARY_DESCRIPTION_LEN)
-            .collect(),
-    )
-}
-
-#[derive(Debug, Clone, PartialEq)]
-pub struct PluginLoadOutcome {
-    plugins: Vec<LoadedPlugin>,
-    capability_summaries: Vec<PluginCapabilitySummary>,
-}
-
-impl Default for PluginLoadOutcome {
-    fn default() -> Self {
-        Self::from_plugins(Vec::new())
-    }
-}
-
-impl PluginLoadOutcome {
-    fn from_plugins(plugins: Vec<LoadedPlugin>) -> Self {
-        let capability_summaries = plugins
-            .iter()
-            .filter_map(PluginCapabilitySummary::from_plugin)
-            .collect::<Vec<_>>();
-        Self {
-            plugins,
-            capability_summaries,
-        }
-    }
-
-    pub fn effective_skill_roots(&self) -> Vec<PathBuf> {
-        let mut skill_roots: Vec<PathBuf> = self
-            .plugins
-            .iter()
-            .filter(|plugin| plugin.is_active())
-            .flat_map(|plugin| plugin.skill_roots.iter().cloned())
-            .collect();
-        skill_roots.sort_unstable();
-        skill_roots.dedup();
-        skill_roots
-    }
-
-    pub fn effective_mcp_servers(&self) -> HashMap<String, McpServerConfig> {
-        let mut mcp_servers = HashMap::new();
-        for plugin in self.plugins.iter().filter(|plugin| plugin.is_active()) {
-            for (name, config) in &plugin.mcp_servers {
-                mcp_servers
-                    .entry(name.clone())
-                    .or_insert_with(|| config.clone());
-            }
-        }
-        mcp_servers
-    }
-
-    pub fn effective_apps(&self) -> Vec<AppConnectorId> {
-        let mut apps = Vec::new();
-        let mut seen_connector_ids = std::collections::HashSet::new();
-
-        for plugin in self.plugins.iter().filter(|plugin| plugin.is_active()) {
-            for connector_id in &plugin.apps {
-                if seen_connector_ids.insert(connector_id.clone()) {
-                    apps.push(connector_id.clone());
-                }
-            }
-        }
-
-        apps
-    }
-
-    pub fn capability_summaries(&self) -> &[PluginCapabilitySummary] {
-        &self.capability_summaries
-    }
-
-    pub fn plugins(&self) -> &[LoadedPlugin] {
-        &self.plugins
-    }
-}
-
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct RemotePluginSyncResult {
     /// Plugin ids newly installed into the local plugin cache.
@@ -575,6 +406,19 @@ impl PluginsManager {
         *cached_enabled_outcome = None;
     }
 
+    /// Resolve plugin skill roots for a config layer stack without touching the plugins cache.
+    pub fn effective_skill_roots_for_layer_stack(
+        &self,
+        config_layer_stack: &ConfigLayerStack,
+        plugins_feature_enabled: bool,
+    ) -> Vec<PathBuf> {
+        if !plugins_feature_enabled {
+            return Vec::new();
+        }
+        load_plugins_from_layer_stack(config_layer_stack, &self.store, self.restriction_product)
+            .effective_skill_roots()
+    }
+
     fn cached_enabled_outcome(&self) -> Option<PluginLoadOutcome> {
         match self.cached_enabled_outcome.read() {
             Ok(cache) => cache.clone(),
@@ -1174,7 +1018,7 @@ impl PluginsManager {
                         }
                     })
                     .collect::<Vec<_>>();
-            configured_curated_plugin_ids.sort_unstable_by_key(super::store::PluginId::as_key);
+            configured_curated_plugin_ids.sort_unstable_by_key(PluginId::as_key);
             self.start_curated_repo_sync(configured_curated_plugin_ids);
             start_startup_remote_plugin_sync_once(
                 Arc::clone(self),
@@ -1341,7 +1185,7 @@ impl PluginUninstallError {
 
 fn log_plugin_load_errors(outcome: &PluginLoadOutcome) {
     for plugin in outcome
-        .plugins
+        .plugins()
         .iter()
         .filter(|plugin| plugin.error.is_some())
     {
@@ -1413,16 +1257,6 @@ pub(crate) fn load_plugins_from_layer_stack(
     PluginLoadOutcome::from_plugins(plugins)
 }
 
-pub(crate) fn plugin_namespace_for_skill_path(path: &Path) -> Option<String> {
-    for ancestor in path.ancestors() {
-        if let Some(manifest) = load_plugin_manifest(ancestor) {
-            return Some(manifest.name);
-        }
-    }
-
-    None
-}
-
 fn refresh_curated_plugin_cache(
     codex_home: &Path,
     plugin_version: &str,

codex-rs/core/src/plugins/manager_tests.rs

@@ -7,7 +7,9 @@ use crate::config_loader::ConfigLayerEntry;
 use crate::config_loader::ConfigLayerStack;
 use crate::config_loader::ConfigRequirements;
 use crate::config_loader::ConfigRequirementsToml;
+use crate::plugins::LoadedPlugin;
 use crate::plugins::MarketplacePluginInstallPolicy;
+use crate::plugins::PluginLoadOutcome;
 use crate::plugins::test_support::TEST_CURATED_PLUGIN_SHA;
 use crate::plugins::test_support::write_curated_plugin_sha_with as write_curated_plugin_sha;
 use crate::plugins::test_support::write_file;
@@ -26,6 +28,8 @@ use wiremock::matchers::method;
 use wiremock::matchers::path;
 use wiremock::matchers::query_param;
 
+const MAX_CAPABILITY_SUMMARY_DESCRIPTION_LEN: usize = 1024;
+
 fn write_plugin(root: &Path, dir_name: &str, manifest_name: &str) {
     let plugin_root = root.join(dir_name);
     fs::create_dir_all(plugin_root.join(".codex-plugin")).unwrap();
@@ -130,7 +134,7 @@ fn load_plugins_loads_default_skills_and_mcp_servers() {
     let outcome = load_plugins_from_config(&plugin_config_toml(true, true), codex_home.path());
 
     assert_eq!(
-        outcome.plugins,
+        outcome.plugins(),
         vec![LoadedPlugin {
             config_name: "sample@test".to_string(),
             manifest_name: Some("sample".to_string()),
@@ -220,10 +224,10 @@ enabled = true
     let skill_path = dunce::canonicalize(skill_path).expect("skill path should canonicalize");
 
     assert_eq!(
-        outcome.plugins[0].disabled_skill_paths,
+        outcome.plugins()[0].disabled_skill_paths,
         HashSet::from([skill_path])
     );
-    assert!(!outcome.plugins[0].has_enabled_skills);
+    assert!(!outcome.plugins()[0].has_enabled_skills);
     assert!(outcome.capability_summaries().is_empty());
 }
 
@@ -256,8 +260,8 @@ enabled = true
 "#;
     let outcome = load_plugins_from_config(config_toml, codex_home.path());
 
-    assert!(outcome.plugins[0].disabled_skill_paths.is_empty());
-    assert!(outcome.plugins[0].has_enabled_skills);
+    assert!(outcome.plugins()[0].disabled_skill_paths.is_empty());
+    assert!(outcome.plugins()[0].has_enabled_skills);
     assert_eq!(
         outcome.capability_summaries(),
         &[PluginCapabilitySummary {
@@ -338,7 +342,7 @@ fn capability_summary_sanitizes_plugin_descriptions_to_one_line() {
     let outcome = load_plugins_from_config(&plugin_config_toml(true, true), codex_home.path());
 
     assert_eq!(
-        outcome.plugins[0].manifest_description.as_deref(),
+        outcome.plugins()[0].manifest_description.as_deref(),
         Some("Plugin that\n includes   the sample\tserver")
     );
     assert_eq!(
@@ -373,7 +377,7 @@ fn capability_summary_truncates_overlong_plugin_descriptions() {
     let outcome = load_plugins_from_config(&plugin_config_toml(true, true), codex_home.path());
 
     assert_eq!(
-        outcome.plugins[0].manifest_description.as_deref(),
+        outcome.plugins()[0].manifest_description.as_deref(),
         Some(too_long.as_str())
     );
     assert_eq!(
@@ -453,14 +457,14 @@ fn load_plugins_uses_manifest_configured_component_paths() {
     let outcome = load_plugins_from_config(&plugin_config_toml(true, true), codex_home.path());
 
     assert_eq!(
-        outcome.plugins[0].skill_roots,
+        outcome.plugins()[0].skill_roots,
         vec![
             plugin_root.join("custom-skills"),
             plugin_root.join("skills")
         ]
     );
     assert_eq!(
-        outcome.plugins[0].mcp_servers,
+        outcome.plugins()[0].mcp_servers,
         HashMap::from([(
             "custom".to_string(),
             McpServerConfig {
@@ -483,7 +487,7 @@ fn load_plugins_uses_manifest_configured_component_paths() {
         )])
     );
     assert_eq!(
-        outcome.plugins[0].apps,
+        outcome.plugins()[0].apps,
         vec![AppConnectorId("connector_custom".to_string())]
     );
 }
@@ -559,11 +563,11 @@ fn load_plugins_ignores_manifest_component_paths_without_dot_slash() {
     let outcome = load_plugins_from_config(&plugin_config_toml(true, true), codex_home.path());
 
     assert_eq!(
-        outcome.plugins[0].skill_roots,
+        outcome.plugins()[0].skill_roots,
         vec![plugin_root.join("skills")]
     );
     assert_eq!(
-        outcome.plugins[0].mcp_servers,
+        outcome.plugins()[0].mcp_servers,
         HashMap::from([(
             "default".to_string(),
             McpServerConfig {
@@ -586,7 +590,7 @@ fn load_plugins_ignores_manifest_component_paths_without_dot_slash() {
         )])
     );
     assert_eq!(
-        outcome.plugins[0].apps,
+        outcome.plugins()[0].apps,
         vec![AppConnectorId("connector_default".to_string())]
     );
 }
@@ -618,7 +622,7 @@ fn load_plugins_preserves_disabled_plugins_without_effective_contributions() {
     let outcome = load_plugins_from_config(&plugin_config_toml(false, true), codex_home.path());
 
     assert_eq!(
-        outcome.plugins,
+        outcome.plugins(),
         vec![LoadedPlugin {
             config_name: "sample@test".to_string(),
             manifest_name: None,
@@ -805,24 +809,6 @@ fn capability_index_filters_inactive_and_zero_capability_plugins() {
     );
 }
 
-#[test]
-fn plugin_namespace_for_skill_path_uses_manifest_name() {
-    let codex_home = TempDir::new().unwrap();
-    let plugin_root = codex_home.path().join("plugins/sample");
-    let skill_path = plugin_root.join("skills/search/SKILL.md");
-
-    write_file(
-        &plugin_root.join(".codex-plugin/plugin.json"),
-        r#"{"name":"sample"}"#,
-    );
-    write_file(&skill_path, "---\ndescription: search\n---\n");
-
-    assert_eq!(
-        plugin_namespace_for_skill_path(&skill_path),
-        Some("sample".to_string())
-    );
-}
-
 #[test]
 fn load_plugins_returns_empty_when_feature_disabled() {
     let codex_home = TempDir::new().unwrap();
@@ -880,9 +866,9 @@ fn load_plugins_rejects_invalid_plugin_keys() {
         codex_home.path(),
     );
 
-    assert_eq!(outcome.plugins.len(), 1);
+    assert_eq!(outcome.plugins().len(), 1);
     assert_eq!(
-        outcome.plugins[0].error.as_deref(),
+        outcome.plugins()[0].error.as_deref(),
         Some("invalid plugin key `sample`; expected <plugin>@<marketplace>")
     );
     assert!(outcome.effective_skill_roots().is_empty());

codex-rs/core/src/plugins/manifest.rs

@@ -1,11 +1,10 @@
 use codex_utils_absolute_path::AbsolutePathBuf;
+pub(crate) use codex_utils_plugins::PLUGIN_MANIFEST_PATH;
 use serde::Deserialize;
 use serde_json::Value as JsonValue;
 use std::fs;
 use std::path::Component;
 use std::path::Path;
-
-pub(crate) const PLUGIN_MANIFEST_PATH: &str = ".codex-plugin/plugin.json";
 const MAX_DEFAULT_PROMPT_COUNT: usize = 3;
 const MAX_DEFAULT_PROMPT_LEN: usize = 128;
 

codex-rs/core/src/plugins/marketplace.rs

@@ -1,10 +1,10 @@
 use super::PluginManifestInterface;
 use super::load_plugin_manifest;
-use super::store::PluginId;
-use super::store::PluginIdError;
 use codex_app_server_protocol::PluginAuthPolicy;
 use codex_app_server_protocol::PluginInstallPolicy;
 use codex_git_utils::get_git_repo_root;
+use codex_plugin::PluginId;
+use codex_plugin::PluginIdError;
 use codex_protocol::protocol::Product;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use dirs::home_dir;

codex-rs/core/src/plugins/mod.rs

@@ -1,3 +1,5 @@
+use crate::config::types::McpServerConfig;
+
 mod discoverable;
 mod injection;
 mod manager;
@@ -11,31 +13,36 @@ mod store;
 pub(crate) mod test_support;
 mod toggles;
 
+pub use codex_plugin::AppConnectorId;
+pub use codex_plugin::EffectiveSkillRoots;
+pub use codex_plugin::PluginCapabilitySummary;
+pub use codex_plugin::PluginId;
+pub use codex_plugin::PluginIdError;
+pub use codex_plugin::PluginTelemetryMetadata;
+
+pub type LoadedPlugin = codex_plugin::LoadedPlugin<McpServerConfig>;
+pub type PluginLoadOutcome = codex_plugin::PluginLoadOutcome<McpServerConfig>;
+
+pub(crate) use codex_plugin::plugin_namespace_for_skill_path;
 pub(crate) use discoverable::list_tool_suggest_discoverable_plugins;
 pub(crate) use injection::build_plugin_injections;
-pub use manager::AppConnectorId;
 pub use manager::ConfiguredMarketplace;
 pub use manager::ConfiguredMarketplaceListOutcome;
 pub use manager::ConfiguredMarketplacePlugin;
-pub use manager::LoadedPlugin;
 pub use manager::OPENAI_CURATED_MARKETPLACE_NAME;
-pub use manager::PluginCapabilitySummary;
 pub use manager::PluginDetail;
 pub use manager::PluginInstallError;
 pub use manager::PluginInstallOutcome;
 pub use manager::PluginInstallRequest;
-pub use manager::PluginLoadOutcome;
 pub use manager::PluginReadOutcome;
 pub use manager::PluginReadRequest;
 pub use manager::PluginRemoteSyncError;
-pub use manager::PluginTelemetryMetadata;
 pub use manager::PluginUninstallError;
 pub use manager::PluginsManager;
 pub use manager::RemotePluginSyncResult;
 pub use manager::installed_plugin_telemetry_metadata;
 pub use manager::load_plugin_apps;
 pub use manager::load_plugin_mcp_servers;
-pub(crate) use manager::plugin_namespace_for_skill_path;
 pub use manager::plugin_telemetry_metadata_from_root;
 pub use manifest::PluginManifestInterface;
 pub(crate) use manifest::PluginManifestPaths;
@@ -53,5 +60,4 @@ pub(crate) use render::render_plugins_section;
 pub(crate) use startup_sync::curated_plugins_repo_path;
 pub(crate) use startup_sync::read_curated_plugins_sha;
 pub(crate) use startup_sync::sync_openai_plugins_repo;
-pub use store::PluginId;
 pub use toggles::collect_plugin_enabled_candidates;

codex-rs/core/src/plugins/store.rs

@@ -1,6 +1,8 @@
 use super::load_plugin_manifest;
-use super::manifest::PLUGIN_MANIFEST_PATH;
+use codex_plugin::PluginId;
+use codex_plugin::validate_plugin_segment;
 use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_plugins::PLUGIN_MANIFEST_PATH;
 use std::fs;
 use std::io;
 use std::path::Path;
@@ -9,53 +11,6 @@ use std::path::PathBuf;
 pub(crate) const DEFAULT_PLUGIN_VERSION: &str = "local";
 pub(crate) const PLUGINS_CACHE_DIR: &str = "plugins/cache";
 
-#[derive(Debug, thiserror::Error)]
-pub enum PluginIdError {
-    #[error("{0}")]
-    Invalid(String),
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct PluginId {
-    pub plugin_name: String,
-    pub marketplace_name: String,
-}
-
-impl PluginId {
-    pub fn new(plugin_name: String, marketplace_name: String) -> Result<Self, PluginIdError> {
-        validate_plugin_segment(&plugin_name, "plugin name").map_err(PluginIdError::Invalid)?;
-        validate_plugin_segment(&marketplace_name, "marketplace name")
-            .map_err(PluginIdError::Invalid)?;
-        Ok(Self {
-            plugin_name,
-            marketplace_name,
-        })
-    }
-
-    pub fn parse(plugin_key: &str) -> Result<Self, PluginIdError> {
-        let Some((plugin_name, marketplace_name)) = plugin_key.rsplit_once('@') else {
-            return Err(PluginIdError::Invalid(format!(
-                "invalid plugin key `{plugin_key}`; expected <plugin>@<marketplace>"
-            )));
-        };
-        if plugin_name.is_empty() || marketplace_name.is_empty() {
-            return Err(PluginIdError::Invalid(format!(
-                "invalid plugin key `{plugin_key}`; expected <plugin>@<marketplace>"
-            )));
-        }
-
-        Self::new(plugin_name.to_string(), marketplace_name.to_string()).map_err(|err| match err {
-            PluginIdError::Invalid(message) => {
-                PluginIdError::Invalid(format!("{message} in `{plugin_key}`"))
-            }
-        })
-    }
-
-    pub fn as_key(&self) -> String {
-        format!("{}@{}", self.plugin_name, self.marketplace_name)
-    }
-}
-
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginInstallResult {
     pub plugin_id: PluginId,
@@ -221,21 +176,6 @@ fn plugin_name_for_source(source_path: &Path) -> Result<String, PluginStoreError
         .map(|_| plugin_name)
 }
 
-fn validate_plugin_segment(segment: &str, kind: &str) -> Result<(), String> {
-    if segment.is_empty() {
-        return Err(format!("invalid {kind}: must not be empty"));
-    }
-    if !segment
-        .chars()
-        .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_')
-    {
-        return Err(format!(
-            "invalid {kind}: only ASCII letters, digits, `_`, and `-` are allowed"
-        ));
-    }
-    Ok(())
-}
-
 fn remove_existing_target(path: &Path) -> Result<(), PluginStoreError> {
     if !path.exists() {
         return Ok(());

codex-rs/core/src/plugins/store_tests.rs

@@ -1,4 +1,5 @@
 use super::*;
+use codex_plugin::PluginId;
 use pretty_assertions::assert_eq;
 use tempfile::tempdir;
 

codex-rs/core/src/snapshots/codex_core__codex_tests__fork_startup_context_then_first_turn_diff.snap

@@ -6,10 +6,8 @@ expression: snapshot
 Scenario: First request after fork when startup preserves the parent baseline, the fork changes approval policy, and the first forked turn enters plan mode.
 
 ## First Forked Turn Request
-00:message/developer:<PERMISSIONS_INSTRUCTIONS>
-01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
-02:message/user:fork seed
-03:message/developer[2]:
+00:message/developer[2]:
     [01] <PERMISSIONS_INSTRUCTIONS>
     [02] <collaboration_mode>Fork turn collaboration instructions.</collaboration_mode>
-04:message/user:after fork
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
+02:message/user:after fork

codex-rs/instructions/BUILD.bazel

@@ -0,0 +1,16 @@
+load("//:defs.bzl", "codex_rust_crate")
+
+codex_rust_crate(
+    name = "instructions",
+    crate_name = "codex_instructions",
+    compile_data = glob(
+        include = ["**"],
+        exclude = [
+            "BUILD.bazel",
+            "Cargo.toml",
+        ],
+        allow_empty = True,
+    ) + [
+        "//codex-rs:node-version.txt",
+    ],
+)

codex-rs/instructions/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+edition.workspace = true
+license.workspace = true
+name = "codex-instructions"
+version.workspace = true
+
+[lib]
+doctest = false
+name = "codex_instructions"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+codex-protocol = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+
+[dev-dependencies]
+pretty_assertions = { workspace = true }

codex-rs/instructions/src/fragment.rs

@@ -0,0 +1,61 @@
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+
+pub const AGENTS_MD_START_MARKER: &str = "# AGENTS.md instructions for ";
+pub const AGENTS_MD_END_MARKER: &str = "</INSTRUCTIONS>";
+pub const SKILL_OPEN_TAG: &str = "<skill>";
+pub const SKILL_CLOSE_TAG: &str = "</skill>";
+
+#[derive(Clone, Copy)]
+pub struct ContextualUserFragmentDefinition {
+    start_marker: &'static str,
+    end_marker: &'static str,
+}
+
+impl ContextualUserFragmentDefinition {
+    pub const fn new(start_marker: &'static str, end_marker: &'static str) -> Self {
+        Self {
+            start_marker,
+            end_marker,
+        }
+    }
+
+    pub fn matches_text(&self, text: &str) -> bool {
+        let trimmed = text.trim_start();
+        let starts_with_marker = trimmed
+            .get(..self.start_marker.len())
+            .is_some_and(|candidate| candidate.eq_ignore_ascii_case(self.start_marker));
+        let trimmed = trimmed.trim_end();
+        let ends_with_marker = trimmed
+            .get(trimmed.len().saturating_sub(self.end_marker.len())..)
+            .is_some_and(|candidate| candidate.eq_ignore_ascii_case(self.end_marker));
+        starts_with_marker && ends_with_marker
+    }
+
+    pub const fn start_marker(&self) -> &'static str {
+        self.start_marker
+    }
+
+    pub const fn end_marker(&self) -> &'static str {
+        self.end_marker
+    }
+
+    pub fn wrap(&self, body: String) -> String {
+        format!("{}\n{}\n{}", self.start_marker, body, self.end_marker)
+    }
+
+    pub fn into_message(self, text: String) -> ResponseItem {
+        ResponseItem::Message {
+            id: None,
+            role: "user".to_string(),
+            content: vec![ContentItem::InputText { text }],
+            end_turn: None,
+            phase: None,
+        }
+    }
+}
+
+pub const AGENTS_MD_FRAGMENT: ContextualUserFragmentDefinition =
+    ContextualUserFragmentDefinition::new(AGENTS_MD_START_MARKER, AGENTS_MD_END_MARKER);
+pub const SKILL_FRAGMENT: ContextualUserFragmentDefinition =
+    ContextualUserFragmentDefinition::new(SKILL_OPEN_TAG, SKILL_CLOSE_TAG);

codex-rs/instructions/src/lib.rs

@@ -0,0 +1,15 @@
+//! User and skill instruction payloads and contextual user fragment markers for Codex prompts.
+
+mod fragment;
+mod user_instructions;
+
+pub use fragment::AGENTS_MD_END_MARKER;
+pub use fragment::AGENTS_MD_FRAGMENT;
+pub use fragment::AGENTS_MD_START_MARKER;
+pub use fragment::ContextualUserFragmentDefinition;
+pub use fragment::SKILL_CLOSE_TAG;
+pub use fragment::SKILL_FRAGMENT;
+pub use fragment::SKILL_OPEN_TAG;
+pub use user_instructions::SkillInstructions;
+pub use user_instructions::USER_INSTRUCTIONS_PREFIX;
+pub use user_instructions::UserInstructions;

codex-rs/instructions/src/user_instructions.rs

@@ -3,20 +3,21 @@ use serde::Serialize;
 
 use codex_protocol::models::ResponseItem;
 
-use crate::contextual_user_message::AGENTS_MD_FRAGMENT;
-use crate::contextual_user_message::SKILL_FRAGMENT;
+use crate::fragment::AGENTS_MD_FRAGMENT;
+use crate::fragment::AGENTS_MD_START_MARKER;
+use crate::fragment::SKILL_FRAGMENT;
 
-pub const USER_INSTRUCTIONS_PREFIX: &str = "# AGENTS.md instructions for ";
+pub const USER_INSTRUCTIONS_PREFIX: &str = AGENTS_MD_START_MARKER;
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename = "user_instructions", rename_all = "snake_case")]
-pub(crate) struct UserInstructions {
+pub struct UserInstructions {
     pub directory: String,
     pub text: String,
 }
 
 impl UserInstructions {
-    pub(crate) fn serialize_to_text(&self) -> String {
+    pub fn serialize_to_text(&self) -> String {
         format!(
             "{prefix}{directory}\n\n<INSTRUCTIONS>\n{contents}\n{suffix}",
             prefix = AGENTS_MD_FRAGMENT.start_marker(),
@@ -35,14 +36,12 @@ impl From<UserInstructions> for ResponseItem {
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename = "skill_instructions", rename_all = "snake_case")]
-pub(crate) struct SkillInstructions {
+pub struct SkillInstructions {
     pub name: String,
     pub path: String,
     pub contents: String,
 }
 
-impl SkillInstructions {}
-
 impl From<SkillInstructions> for ResponseItem {
     fn from(si: SkillInstructions) -> Self {
         SKILL_FRAGMENT.into_message(SKILL_FRAGMENT.wrap(format!(

codex-rs/instructions/src/user_instructions_tests.rs

@@ -1,7 +1,11 @@
 use super::*;
 use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
 use pretty_assertions::assert_eq;
 
+use crate::fragment::AGENTS_MD_FRAGMENT;
+use crate::fragment::SKILL_FRAGMENT;
+
 #[test]
 fn test_user_instructions() {
     let user_instructions = UserInstructions {

codex-rs/plugin/BUILD.bazel

@@ -0,0 +1,15 @@
+load("//:defs.bzl", "codex_rust_crate")
+
+codex_rust_crate(
+    name = "plugin",
+    crate_name = "codex_plugin",
+    compile_data = glob(
+        include = ["**"],
+        exclude = [
+            "**/* *",
+            "BUILD.bazel",
+            "Cargo.toml",
+        ],
+        allow_empty = True,
+    ),
+)

codex-rs/plugin/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+edition.workspace = true
+license.workspace = true
+name = "codex-plugin"
+version.workspace = true
+
+[lib]
+doctest = false
+name = "codex_plugin"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+codex-utils-absolute-path = { workspace = true }
+codex-utils-plugins = { workspace = true }
+thiserror = { workspace = true }

codex-rs/plugin/src/lib.rs

@@ -0,0 +1,55 @@
+//! Shared plugin identifiers and telemetry-facing summaries.
+
+pub use codex_utils_plugins::PLUGIN_MANIFEST_PATH;
+pub use codex_utils_plugins::mention_syntax;
+pub use codex_utils_plugins::plugin_namespace_for_skill_path;
+
+mod load_outcome;
+mod plugin_id;
+
+pub use load_outcome::EffectiveSkillRoots;
+pub use load_outcome::LoadedPlugin;
+pub use load_outcome::PluginLoadOutcome;
+pub use load_outcome::prompt_safe_plugin_description;
+pub use plugin_id::PluginId;
+pub use plugin_id::PluginIdError;
+pub use plugin_id::validate_plugin_segment;
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct AppConnectorId(pub String);
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct PluginCapabilitySummary {
+    pub config_name: String,
+    pub display_name: String,
+    pub description: Option<String>,
+    pub has_skills: bool,
+    pub mcp_server_names: Vec<String>,
+    pub app_connector_ids: Vec<AppConnectorId>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginTelemetryMetadata {
+    pub plugin_id: PluginId,
+    pub capability_summary: Option<PluginCapabilitySummary>,
+}
+
+impl PluginTelemetryMetadata {
+    pub fn from_plugin_id(plugin_id: &PluginId) -> Self {
+        Self {
+            plugin_id: plugin_id.clone(),
+            capability_summary: None,
+        }
+    }
+}
+
+impl PluginCapabilitySummary {
+    pub fn telemetry_metadata(&self) -> Option<PluginTelemetryMetadata> {
+        PluginId::parse(&self.config_name)
+            .ok()
+            .map(|plugin_id| PluginTelemetryMetadata {
+                plugin_id,
+                capability_summary: Some(self.clone()),
+            })
+    }
+}

codex-rs/plugin/src/load_outcome.rs

@@ -0,0 +1,163 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::path::PathBuf;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use crate::AppConnectorId;
+use crate::PluginCapabilitySummary;
+
+const MAX_CAPABILITY_SUMMARY_DESCRIPTION_LEN: usize = 1024;
+
+/// A plugin that was loaded from disk, including merged MCP server definitions.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LoadedPlugin<M> {
+    pub config_name: String,
+    pub manifest_name: Option<String>,
+    pub manifest_description: Option<String>,
+    pub root: AbsolutePathBuf,
+    pub enabled: bool,
+    pub skill_roots: Vec<PathBuf>,
+    pub disabled_skill_paths: HashSet<PathBuf>,
+    pub has_enabled_skills: bool,
+    pub mcp_servers: HashMap<String, M>,
+    pub apps: Vec<AppConnectorId>,
+    pub error: Option<String>,
+}
+
+impl<M> LoadedPlugin<M> {
+    pub fn is_active(&self) -> bool {
+        self.enabled && self.error.is_none()
+    }
+}
+
+fn plugin_capability_summary_from_loaded<M>(
+    plugin: &LoadedPlugin<M>,
+) -> Option<PluginCapabilitySummary> {
+    if !plugin.is_active() {
+        return None;
+    }
+
+    let mut mcp_server_names: Vec<String> = plugin.mcp_servers.keys().cloned().collect();
+    mcp_server_names.sort_unstable();
+
+    let summary = PluginCapabilitySummary {
+        config_name: plugin.config_name.clone(),
+        display_name: plugin
+            .manifest_name
+            .clone()
+            .unwrap_or_else(|| plugin.config_name.clone()),
+        description: prompt_safe_plugin_description(plugin.manifest_description.as_deref()),
+        has_skills: plugin.has_enabled_skills,
+        mcp_server_names,
+        app_connector_ids: plugin.apps.clone(),
+    };
+
+    (summary.has_skills
+        || !summary.mcp_server_names.is_empty()
+        || !summary.app_connector_ids.is_empty())
+    .then_some(summary)
+}
+
+/// Normalizes plugin descriptions for inclusion in model-facing capability summaries.
+pub fn prompt_safe_plugin_description(description: Option<&str>) -> Option<String> {
+    let description = description?
+        .split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ");
+    if description.is_empty() {
+        return None;
+    }
+
+    Some(
+        description
+            .chars()
+            .take(MAX_CAPABILITY_SUMMARY_DESCRIPTION_LEN)
+            .collect(),
+    )
+}
+
+/// Outcome of loading configured plugins (skills roots, MCP, apps, errors).
+#[derive(Debug, Clone, PartialEq)]
+pub struct PluginLoadOutcome<M> {
+    plugins: Vec<LoadedPlugin<M>>,
+    capability_summaries: Vec<PluginCapabilitySummary>,
+}
+
+impl<M: Clone> Default for PluginLoadOutcome<M> {
+    fn default() -> Self {
+        Self::from_plugins(Vec::new())
+    }
+}
+
+impl<M: Clone> PluginLoadOutcome<M> {
+    pub fn from_plugins(plugins: Vec<LoadedPlugin<M>>) -> Self {
+        let capability_summaries = plugins
+            .iter()
+            .filter_map(plugin_capability_summary_from_loaded)
+            .collect::<Vec<_>>();
+        Self {
+            plugins,
+            capability_summaries,
+        }
+    }
+
+    pub fn effective_skill_roots(&self) -> Vec<PathBuf> {
+        let mut skill_roots: Vec<PathBuf> = self
+            .plugins
+            .iter()
+            .filter(|plugin| plugin.is_active())
+            .flat_map(|plugin| plugin.skill_roots.iter().cloned())
+            .collect();
+        skill_roots.sort_unstable();
+        skill_roots.dedup();
+        skill_roots
+    }
+
+    pub fn effective_mcp_servers(&self) -> HashMap<String, M> {
+        let mut mcp_servers = HashMap::new();
+        for plugin in self.plugins.iter().filter(|plugin| plugin.is_active()) {
+            for (name, config) in &plugin.mcp_servers {
+                mcp_servers
+                    .entry(name.clone())
+                    .or_insert_with(|| config.clone());
+            }
+        }
+        mcp_servers
+    }
+
+    pub fn effective_apps(&self) -> Vec<AppConnectorId> {
+        let mut apps = Vec::new();
+        let mut seen_connector_ids = HashSet::new();
+
+        for plugin in self.plugins.iter().filter(|plugin| plugin.is_active()) {
+            for connector_id in &plugin.apps {
+                if seen_connector_ids.insert(connector_id.clone()) {
+                    apps.push(connector_id.clone());
+                }
+            }
+        }
+
+        apps
+    }
+
+    pub fn capability_summaries(&self) -> &[PluginCapabilitySummary] {
+        &self.capability_summaries
+    }
+
+    pub fn plugins(&self) -> &[LoadedPlugin<M>] {
+        &self.plugins
+    }
+}
+
+/// Implemented by [`PluginLoadOutcome`] so callers (e.g. skills) can depend on `codex-plugin`
+/// without naming the MCP config type parameter.
+pub trait EffectiveSkillRoots {
+    fn effective_skill_roots(&self) -> Vec<PathBuf>;
+}
+
+impl<M: Clone> EffectiveSkillRoots for PluginLoadOutcome<M> {
+    fn effective_skill_roots(&self) -> Vec<PathBuf> {
+        PluginLoadOutcome::effective_skill_roots(self)
+    }
+}

codex-rs/plugin/src/plugin_id.rs

@@ -0,0 +1,64 @@
+//! Stable plugin identifier parsing and validation shared with the plugin cache.
+
+#[derive(Debug, thiserror::Error)]
+pub enum PluginIdError {
+    #[error("{0}")]
+    Invalid(String),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginId {
+    pub plugin_name: String,
+    pub marketplace_name: String,
+}
+
+impl PluginId {
+    pub fn new(plugin_name: String, marketplace_name: String) -> Result<Self, PluginIdError> {
+        validate_plugin_segment(&plugin_name, "plugin name").map_err(PluginIdError::Invalid)?;
+        validate_plugin_segment(&marketplace_name, "marketplace name")
+            .map_err(PluginIdError::Invalid)?;
+        Ok(Self {
+            plugin_name,
+            marketplace_name,
+        })
+    }
+
+    pub fn parse(plugin_key: &str) -> Result<Self, PluginIdError> {
+        let Some((plugin_name, marketplace_name)) = plugin_key.rsplit_once('@') else {
+            return Err(PluginIdError::Invalid(format!(
+                "invalid plugin key `{plugin_key}`; expected <plugin>@<marketplace>"
+            )));
+        };
+        if plugin_name.is_empty() || marketplace_name.is_empty() {
+            return Err(PluginIdError::Invalid(format!(
+                "invalid plugin key `{plugin_key}`; expected <plugin>@<marketplace>"
+            )));
+        }
+
+        Self::new(plugin_name.to_string(), marketplace_name.to_string()).map_err(|err| match err {
+            PluginIdError::Invalid(message) => {
+                PluginIdError::Invalid(format!("{message} in `{plugin_key}`"))
+            }
+        })
+    }
+
+    pub fn as_key(&self) -> String {
+        format!("{}@{}", self.plugin_name, self.marketplace_name)
+    }
+}
+
+/// Validates a single path segment used in plugin IDs and cache layout.
+pub fn validate_plugin_segment(segment: &str, kind: &str) -> Result<(), String> {
+    if segment.is_empty() {
+        return Err(format!("invalid {kind}: must not be empty"));
+    }
+    if !segment
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_')
+    {
+        return Err(format!(
+            "invalid {kind}: only ASCII letters, digits, `_`, and `-` are allowed"
+        ));
+    }
+    Ok(())
+}

codex-rs/utils/plugins/BUILD.bazel

@@ -0,0 +1,6 @@
+load("//:defs.bzl", "codex_rust_crate")
+
+codex_rust_crate(
+    name = "plugins",
+    crate_name = "codex_utils_plugins",
+)

codex-rs/utils/plugins/Cargo.toml

@@ -0,0 +1,21 @@
+
+[package]
+edition.workspace = true
+license.workspace = true
+name = "codex-utils-plugins"
+version.workspace = true
+
+[lib]
+doctest = false
+name = "codex_utils_plugins"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+
+[dev-dependencies]
+tempfile = { workspace = true }

codex-rs/utils/plugins/src/lib.rs

@@ -0,0 +1,7 @@
+//! Plugin path resolution and plaintext mention sigils shared across Codex crates.
+
+pub mod mention_syntax;
+pub mod plugin_namespace;
+
+pub use plugin_namespace::PLUGIN_MANIFEST_PATH;
+pub use plugin_namespace::plugin_namespace_for_skill_path;

codex-rs/utils/plugins/src/mention_syntax.rs

@@ -0,0 +1,7 @@
+//! Sigils for tool/plugin mentions in plaintext (shared across Codex crates).
+
+/// Default plaintext sigil for tools.
+pub const TOOL_MENTION_SIGIL: char = '$';
+
+/// Plugins use `@` in linked plaintext outside TUI.
+pub const PLUGIN_TEXT_MENTION_SIGIL: char = '@';

codex-rs/utils/plugins/src/plugin_namespace.rs

@@ -0,0 +1,70 @@
+//! Resolve plugin namespace from skill file paths by walking ancestors for `plugin.json`.
+
+use std::fs;
+use std::path::Path;
+
+/// Relative path from a plugin root to its manifest file.
+pub const PLUGIN_MANIFEST_PATH: &str = ".codex-plugin/plugin.json";
+
+#[derive(serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct RawPluginManifestName {
+    #[serde(default)]
+    name: String,
+}
+
+fn plugin_manifest_name(plugin_root: &Path) -> Option<String> {
+    let manifest_path = plugin_root.join(PLUGIN_MANIFEST_PATH);
+    if !manifest_path.is_file() {
+        return None;
+    }
+    let contents = fs::read_to_string(&manifest_path).ok()?;
+    let RawPluginManifestName { name: raw_name } = serde_json::from_str(&contents).ok()?;
+    Some(
+        plugin_root
+            .file_name()
+            .and_then(|entry| entry.to_str())
+            .filter(|_| raw_name.trim().is_empty())
+            .unwrap_or(raw_name.as_str())
+            .to_string(),
+    )
+}
+
+/// Returns the plugin manifest `name` for the nearest ancestor of `path` that contains a valid
+/// plugin manifest (same `name` rules as full manifest loading in codex-core).
+pub fn plugin_namespace_for_skill_path(path: &Path) -> Option<String> {
+    for ancestor in path.ancestors() {
+        if let Some(name) = plugin_manifest_name(ancestor) {
+            return Some(name);
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::plugin_namespace_for_skill_path;
+    use std::fs;
+    use tempfile::tempdir;
+
+    #[test]
+    fn uses_manifest_name() {
+        let tmp = tempdir().expect("tempdir");
+        let plugin_root = tmp.path().join("plugins/sample");
+        let skill_path = plugin_root.join("skills/search/SKILL.md");
+
+        fs::create_dir_all(skill_path.parent().expect("parent")).expect("mkdir");
+        fs::create_dir_all(plugin_root.join(".codex-plugin")).expect("mkdir manifest");
+        fs::write(
+            plugin_root.join(".codex-plugin/plugin.json"),
+            r#"{"name":"sample"}"#,
+        )
+        .expect("write manifest");
+        fs::write(&skill_path, "---\ndescription: search\n---\n").expect("write skill");
+
+        assert_eq!(
+            plugin_namespace_for_skill_path(&skill_path),
+            Some("sample".to_string())
+        );
+    }
+}