Merge branch 'main' into stack/instructions

- Changed `requires_mcp_tool_approval` to apply MCP spec defaults when
annotations are missing.
- Unannotated tools now default to:
  - `readOnlyHint = false`
  - `destructiveHint = true`
  - `openWorldHint = true`
- This means unannotated MCP tools now go through approval/ARC
monitoring instead of silently bypassing it.
- Explicitly read-only tools still skip approval unless they are also
explicitly marked destructive.

**Previous behavior**
Failed open for missing annotations, which was unsafe for custom MCP
tools that omitted or forgot annotations.

---------

Co-authored-by: colby-oai <228809017+colby-oai@users.noreply.github.com>

codex-rs/Cargo.lock

@@ -1883,6 +1883,7 @@ dependencies = [
  "codex-features",
  "codex-git-utils",
  "codex-hooks",
+ "codex-instructions",
  "codex-login",
  "codex-network-proxy",
  "codex-otel",
@@ -2174,6 +2175,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"

codex-rs/Cargo.toml

@@ -25,6 +25,7 @@ members = [
     "skills",
     "core",
     "hooks",
+    "instructions",
     "secrets",
     "exec",
     "exec-server",
@@ -122,6 +123,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" }

codex-rs/core/Cargo.toml

@@ -42,6 +42,7 @@ 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-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/mcp_tool_call.rs

@@ -495,7 +495,7 @@ async fn maybe_request_mcp_tool_approval(
     approval_mode: AppToolApproval,
 ) -> Option<McpToolApprovalDecision> {
     let annotations = metadata.and_then(|metadata| metadata.annotations.as_ref());
-    let approval_required = annotations.is_some_and(requires_mcp_tool_approval);
+    let approval_required = requires_mcp_tool_approval(annotations);
     let mut monitor_reason = None;
     let auto_approved_by_policy = approval_mode == AppToolApproval::Approve
         || (approval_mode == AppToolApproval::Auto && is_full_access_mode(turn_context));
@@ -1299,12 +1299,23 @@ async fn persist_codex_app_tool_approval(
         .await
 }
 
-fn requires_mcp_tool_approval(annotations: &ToolAnnotations) -> bool {
-    if annotations.destructive_hint == Some(true) {
+fn requires_mcp_tool_approval(annotations: Option<&ToolAnnotations>) -> bool {
+    let destructive_hint = annotations.and_then(|annotations| annotations.destructive_hint);
+    if destructive_hint == Some(true) {
         return true;
     }
 
-    annotations.read_only_hint == Some(false) && annotations.open_world_hint == Some(true)
+    let read_only_hint = annotations
+        .and_then(|annotations| annotations.read_only_hint)
+        .unwrap_or(false);
+    if read_only_hint {
+        return false;
+    }
+
+    destructive_hint.unwrap_or(true)
+        || annotations
+            .and_then(|annotations| annotations.open_world_hint)
+            .unwrap_or(true)
 }
 
 async fn notify_mcp_tool_call_skip(

codex-rs/core/src/mcp_tool_call_tests.rs

@@ -64,19 +64,30 @@ fn prompt_options(
 #[test]
 fn approval_required_when_read_only_false_and_destructive() {
     let annotations = annotations(Some(false), Some(true), None);
-    assert_eq!(requires_mcp_tool_approval(&annotations), true);
+    assert_eq!(requires_mcp_tool_approval(Some(&annotations)), true);
 }
 
 #[test]
 fn approval_required_when_read_only_false_and_open_world() {
     let annotations = annotations(Some(false), None, Some(true));
-    assert_eq!(requires_mcp_tool_approval(&annotations), true);
+    assert_eq!(requires_mcp_tool_approval(Some(&annotations)), true);
 }
 
 #[test]
 fn approval_required_when_destructive_even_if_read_only_true() {
     let annotations = annotations(Some(true), Some(true), Some(true));
-    assert_eq!(requires_mcp_tool_approval(&annotations), true);
+    assert_eq!(requires_mcp_tool_approval(Some(&annotations)), true);
+}
+
+#[test]
+fn approval_required_when_annotations_are_absent() {
+    assert_eq!(requires_mcp_tool_approval(None), true);
+}
+
+#[test]
+fn approval_not_required_when_read_only_and_other_hints_are_absent() {
+    let annotations = annotations(Some(true), None, None);
+    assert_eq!(requires_mcp_tool_approval(Some(&annotations)), false);
 }
 
 #[test]
@@ -1067,6 +1078,75 @@ async fn approve_mode_blocks_when_arc_returns_interrupt_for_model() {
     );
 }
 
+#[tokio::test]
+async fn approve_mode_blocks_when_arc_returns_interrupt_without_annotations() {
+    use wiremock::Mock;
+    use wiremock::MockServer;
+    use wiremock::ResponseTemplate;
+    use wiremock::matchers::method;
+    use wiremock::matchers::path;
+
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/codex/safety/arc"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+            "outcome": "steer-model",
+            "short_reason": "needs approval",
+            "rationale": "high-risk action",
+            "risk_score": 96,
+            "risk_level": "critical",
+            "evidence": [{
+                "message": "dangerous_tool",
+                "why": "high-risk action",
+            }],
+        })))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let (session, mut turn_context) = make_session_and_context().await;
+    turn_context.auth_manager = Some(crate::test_support::auth_manager_from_auth(
+        crate::CodexAuth::create_dummy_chatgpt_auth_for_testing(),
+    ));
+    let mut config = (*turn_context.config).clone();
+    config.chatgpt_base_url = server.uri();
+    turn_context.config = Arc::new(config);
+
+    let session = Arc::new(session);
+    let turn_context = Arc::new(turn_context);
+    let invocation = McpInvocation {
+        server: CODEX_APPS_MCP_SERVER_NAME.to_string(),
+        tool: "dangerous_tool".to_string(),
+        arguments: Some(serde_json::json!({ "id": 1 })),
+    };
+    let metadata = McpToolApprovalMetadata {
+        annotations: None,
+        connector_id: Some("calendar".to_string()),
+        connector_name: Some("Calendar".to_string()),
+        connector_description: Some("Manage events".to_string()),
+        tool_title: Some("Dangerous Tool".to_string()),
+        tool_description: Some("Performs a risky action.".to_string()),
+        codex_apps_meta: None,
+    };
+
+    let decision = maybe_request_mcp_tool_approval(
+        &session,
+        &turn_context,
+        "call-3",
+        &invocation,
+        Some(&metadata),
+        AppToolApproval::Approve,
+    )
+    .await;
+
+    assert_eq!(
+        decision,
+        Some(McpToolApprovalDecision::BlockedBySafetyMonitor(
+            "Tool call was cancelled because of safety risks: high-risk action".to_string(),
+        ))
+    );
+}
+
 #[tokio::test]
 async fn full_access_auto_mode_blocks_when_arc_returns_interrupt_for_model() {
     use wiremock::Mock;

codex-rs/core/src/tools/handlers/unified_exec.rs

@@ -25,6 +25,8 @@ use crate::unified_exec::UnifiedExecProcessManager;
 use crate::unified_exec::WriteStdinRequest;
 use async_trait::async_trait;
 use codex_features::Feature;
+use codex_otel::SessionTelemetry;
+use codex_otel::metrics::names::TOOL_CALL_UNIFIED_EXEC_METRIC;
 use codex_protocol::models::PermissionProfile;
 use serde::Deserialize;
 use std::path::PathBuf;
@@ -260,6 +262,7 @@ impl ToolHandler for UnifiedExecHandler {
                     });
                 }
 
+                emit_unified_exec_tty_metric(&turn.session_telemetry, tty);
                 manager
                     .exec_command(
                         ExecCommandRequest {
@@ -323,6 +326,14 @@ impl ToolHandler for UnifiedExecHandler {
     }
 }
 
+fn emit_unified_exec_tty_metric(session_telemetry: &SessionTelemetry, tty: bool) {
+    session_telemetry.counter(
+        TOOL_CALL_UNIFIED_EXEC_METRIC,
+        /*inc*/ 1,
+        &[("tty", if tty { "true" } else { "false" })],
+    );
+}
+
 pub(crate) fn get_command(
     args: &ExecCommandArgs,
     session_shell: Arc<Shell>,

codex-rs/core/tests/common/apps_test_server.rs

@@ -185,6 +185,11 @@ impl Respond for CodexAppsJsonRpcResponder {
                             {
                                 "name": "calendar_create_event",
                                 "description": "Create a calendar event.",
+                                "annotations": {
+                                    "readOnlyHint": false,
+                                    "destructiveHint": false,
+                                    "openWorldHint": false
+                                },
                                 "inputSchema": {
                                     "type": "object",
                                     "properties": {
@@ -209,6 +214,9 @@ impl Respond for CodexAppsJsonRpcResponder {
                             {
                                 "name": "calendar_list_events",
                                 "description": "List calendar events.",
+                                "annotations": {
+                                    "readOnlyHint": true
+                                },
                                 "inputSchema": {
                                     "type": "object",
                                     "properties": {
@@ -241,6 +249,9 @@ impl Respond for CodexAppsJsonRpcResponder {
                         tools.push(json!({
                             "name": format!("calendar_timezone_option_{index}"),
                             "description": format!("Read timezone option {index}."),
+                            "annotations": {
+                                "readOnlyHint": true
+                            },
                             "inputSchema": {
                                 "type": "object",
                                 "properties": {

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/otel/src/metrics/names.rs

@@ -1,5 +1,6 @@
 pub const TOOL_CALL_COUNT_METRIC: &str = "codex.tool.call";
 pub const TOOL_CALL_DURATION_METRIC: &str = "codex.tool.call.duration_ms";
+pub const TOOL_CALL_UNIFIED_EXEC_METRIC: &str = "codex.tool.unified_exec";
 pub const API_CALL_COUNT_METRIC: &str = "codex.api_request";
 pub const API_CALL_DURATION_METRIC: &str = "codex.api_request.duration_ms";
 pub const SSE_EVENT_COUNT_METRIC: &str = "codex.sse_event";

codex-rs/rmcp-client/src/bin/test_stdio_server.rs

@@ -22,6 +22,7 @@ use rmcp::model::ResourceTemplate;
 use rmcp::model::ServerCapabilities;
 use rmcp::model::ServerInfo;
 use rmcp::model::Tool;
+use rmcp::model::ToolAnnotations;
 use serde::Deserialize;
 use serde_json::json;
 use tokio::task;
@@ -85,11 +86,13 @@ impl TestToolServer {
         }))
         .expect("echo tool schema should deserialize");
 
-        Tool::new(
+        let mut tool = Tool::new(
             Cow::Borrowed(name),
             Cow::Borrowed(description),
             Arc::new(schema),
-        )
+        );
+        tool.annotations = Some(ToolAnnotations::new().read_only(true));
+        tool
     }
 
     fn image_tool() -> Tool {
@@ -101,11 +104,13 @@ impl TestToolServer {
         }))
         .expect("image tool schema should deserialize");
 
-        Tool::new(
+        let mut tool = Tool::new(
             Cow::Borrowed("image"),
             Cow::Borrowed("Return a single image content block."),
             Arc::new(schema),
-        )
+        );
+        tool.annotations = Some(ToolAnnotations::new().read_only(true));
+        tool
     }
 
     /// Tool intended for manual testing of Codex TUI rendering for MCP image tool results.
@@ -154,13 +159,15 @@ impl TestToolServer {
         }))
         .expect("image_scenario tool schema should deserialize");
 
-        Tool::new(
+        let mut tool = Tool::new(
             Cow::Borrowed("image_scenario"),
             Cow::Borrowed(
                 "Return content blocks for manual testing of MCP image rendering scenarios.",
             ),
             Arc::new(schema),
-        )
+        );
+        tool.annotations = Some(ToolAnnotations::new().read_only(true));
+        tool
     }
 
     fn memo_resource() -> Resource {

codex-rs/rmcp-client/src/bin/test_streamable_http_server.rs

@@ -38,6 +38,7 @@ use rmcp::model::ResourceTemplate;
 use rmcp::model::ServerCapabilities;
 use rmcp::model::ServerInfo;
 use rmcp::model::Tool;
+use rmcp::model::ToolAnnotations;
 use rmcp::transport::StreamableHttpServerConfig;
 use rmcp::transport::StreamableHttpService;
 use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
@@ -84,11 +85,13 @@ impl TestToolServer {
         }))
         .expect("echo tool schema should deserialize");
 
-        Tool::new(
+        let mut tool = Tool::new(
             Cow::Borrowed("echo"),
             Cow::Borrowed("Echo back the provided message and include environment data."),
             Arc::new(schema),
-        )
+        );
+        tool.annotations = Some(ToolAnnotations::new().read_only(true));
+        tool
     }
 
     fn memo_resource() -> Resource {

codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md

@@ -26,6 +26,15 @@ python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-nam
 python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace
 ```
 
+For a home-local plugin, treat `<home>` as the root and use:
+
+```bash
+python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
+  --path ~/plugins \
+  --marketplace-path ~/.agents/plugins/marketplace.json \
+  --with-marketplace
+```
+
 4. Generate/adjust optional companion folders as needed:
 
 ```bash
@@ -37,6 +46,7 @@ python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin -
 
 ## What this skill creates
 
+- If the user has not made the plugin location explicit, ask whether they want a repo-local plugin or a home-local plugin before generating marketplace entries.
 - Creates plugin root at `/<parent-plugin-directory>/<plugin-name>/`.
 - Always creates `/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json`.
 - Fills the manifest with the full schema shape, placeholder values, and the complete `interface` section.
@@ -58,6 +68,8 @@ python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin -
 ## Marketplace workflow
 
 - `marketplace.json` always lives at `<repo-root>/.agents/plugins/marketplace.json`.
+- For a home-local plugin, use the same convention with `<home>` as the root:
+  `~/.agents/plugins/marketplace.json` plus `./plugins/<plugin-name>`.
 - Marketplace root metadata supports top-level `name` plus optional `interface.displayName`.
 - Treat plugin order in `plugins[]` as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
 - `displayName` belongs inside the marketplace `interface` object, not individual `plugins[]` entries.

codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md

@@ -115,8 +115,10 @@
         "source": "local",
         "path": "./plugins/linear"
       },
-      "installPolicy": "AVAILABLE",
-      "authPolicy": "ON_INSTALL",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
       "category": "Productivity"
     }
   ]
@@ -142,7 +144,9 @@
   - `source` (`string`): Use `local` for this repo workflow.
   - `path` (`string`): Relative plugin path based on the marketplace root.
     - Repo plugin: `./plugins/<plugin-name>`
-    - Local plugin in `~/.agents/plugins/marketplace.json`: `./.codex/plugins/<plugin-name>`
+    - Local plugin in `~/.agents/plugins/marketplace.json`: `./plugins/<plugin-name>`
+  - The same relative path convention is used for both repo-rooted and home-rooted marketplaces.
+    - Example: with `~/.agents/plugins/marketplace.json`, `./plugins/<plugin-name>` resolves to `~/plugins/<plugin-name>`.
 - `policy` (`object`): Marketplace policy block. Always include it.
   - `installation` (`string`): Availability policy.
     - Allowed values: `NOT_AVAILABLE`, `AVAILABLE`, `INSTALLED_BY_DEFAULT`

codex-rs/skills/src/assets/samples/plugin-creator/scripts/create_basic_plugin.py

@@ -191,7 +191,10 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--path",
         default=str(DEFAULT_PLUGIN_PARENT),
-        help="Parent directory for plugin creation (defaults to <cwd>/plugins)",
+        help=(
+            "Parent directory for plugin creation (defaults to <cwd>/plugins). "
+            "When using a home-rooted marketplace, use <home>/plugins."
+        ),
     )
     parser.add_argument("--with-skills", action="store_true", help="Create skills/ directory")
     parser.add_argument("--with-hooks", action="store_true", help="Create hooks/ directory")
@@ -202,12 +205,19 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--with-marketplace",
         action="store_true",
-        help="Create or update <cwd>/.agents/plugins/marketplace.json",
+        help=(
+            "Create or update <cwd>/.agents/plugins/marketplace.json. "
+            "Marketplace entries always point to ./plugins/<plugin-name> relative to the "
+            "marketplace root."
+        ),
     )
     parser.add_argument(
         "--marketplace-path",
         default=str(DEFAULT_MARKETPLACE_PATH),
-        help="Path to marketplace.json (defaults to <cwd>/.agents/plugins/marketplace.json)",
+        help=(
+            "Path to marketplace.json (defaults to <cwd>/.agents/plugins/marketplace.json). "
+            "For a home-rooted marketplace, use <home>/.agents/plugins/marketplace.json."
+        ),
     )
     parser.add_argument(
         "--install-policy",