Lightweight coding agent that runs in your terminal
Rust
Support model-specific descriptions for agent message board tools (#47670)
eknight-oaif2654ea6c9a3
diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rsindex 815c350519..c644f072f1 100644--- a/codex-rs/core/src/session/mod.rs+++ b/codex-rs/core/src/session/mod.rs@@ -3860,6 +3860,15 @@ impl Session {.await;let extension_data =codex_extension_api::ExtensionData::new(turn_context.sub_id.clone());+ if let Some(messages) = settings+ .model_info+ .model_messages+ .as_ref()+ .and_then(|messages| messages.tools.as_ref())+ .and_then(|tools| tools.multi_agent.as_ref())+ {+ extension_data.insert(messages.clone());+ }extension_data.insert(selected_capability_roots.clone());if let Some(discovery) = &executor_capability_discovery {extension_data.insert(discovery.as_ref().clone());diff --git a/codex-rs/core/tests/suite/multi_agent_tool_descriptions.rs b/codex-rs/core/tests/suite/multi_agent_tool_descriptions.rsindex c30ea46c1b..21448bff82 100644--- a/codex-rs/core/tests/suite/multi_agent_tool_descriptions.rs+++ b/codex-rs/core/tests/suite/multi_agent_tool_descriptions.rs@@ -266,3 +266,118 @@ async fn multi_agent_catalog_messages_change_only_selected_tool_fields(assert_eq!(actual, expected);Ok(())}++#[test_case(Exposure::Namespaced; "namespaced")]+#[test_case(Exposure::CodeMode; "code_mode")]+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn channel_catalog_descriptions_change_only_selected_tools(exposure: Exposure) -> Result<()> {+ skip_if_no_network!(Ok(()));++ let names = [+ "create_channel",+ "get_channels",+ "list_threads",+ "search_posts",+ "read_thread",+ "read_post",+ "subscribe",+ "unsubscribe",+ "post",+ ];+ let all: serde_json::Map<String, Value> = names+ .into_iter()+ .map(|name| {+ (+ name.into(),+ json!({"description": format!("Catalog {name}.")}),+ )+ })+ .collect();+ let messages = [+ Value::Null,+ json!({"multi_agent": all}),+ json!({"multi_agent": {+ "post": {"description": "Catalog post."},+ "subscribe": {"description": ""},+ "read_thread": {"description": null},+ "read_post": {"parameters": CATALOG_PARAMETERS}+ }}),+ ];++ let server = start_mock_server().await;+ let response = mount_sse_sequence(+ &server,+ vec![+ sse_completed("default"),+ sse_completed("all"),+ sse_completed("sparse"),+ ],+ )+ .await;+ for message in &messages {+ let message = serde_json::from_value::<Option<ToolMessages>>(message.clone())?;+ let test = test_codex()+ .with_model_info_override("gpt-5.2", move |model| {+ model.multi_agent_version = Some(MultiAgentVersion::V2);+ model.model_messages.as_mut().expect("model messages").tools = message;+ })+ .with_config(move |config| {+ config.ephemeral = false;+ config+ .features+ .enable(Feature::MultiAgentV2)+ .expect("enable V2");+ config+ .features+ .enable(Feature::AgentMessageBoard)+ .expect("enable channels");+ config.multi_agent_v2.tool_namespace = Some("delegation".into());+ if matches!(exposure, Exposure::CodeMode) {+ config+ .features+ .enable(Feature::CodeMode)+ .expect("enable Code Mode");+ config.code_mode.disable_in_process_fallback = true;+ config.multi_agent_v2.non_code_mode_only = false;+ }+ })+ .build_with_auto_env(&server)+ .await?;+ test.submit_turn("Inspect the available tools.").await?;+ }++ let requests = response.requests();+ assert_eq!(requests.len(), messages.len());+ let default = requests[0].body_json()["tools"].clone();+ for (request, message) in requests.iter().zip(&messages).skip(1) {+ let mut expected = default.clone();+ let channel_tools = expected+ .as_array_mut()+ .expect("tools")+ .iter_mut()+ .find(|tool| tool["name"] == "delegation")+ .expect("delegation namespace")["tools"]+ .as_array_mut()+ .expect("namespace tools");+ for name in names {+ let tool = channel_tools+ .iter_mut()+ .find(|tool| tool["name"] == name)+ .expect(name);+ let bundled = tool["description"].as_str().expect("bundled description");+ if let Some(description) = message["multi_agent"][name]["description"].as_str() {+ let declaration = if matches!(exposure, Exposure::CodeMode) {+ let offset = bundled+ .find("\n\nexec tool declaration:")+ .expect("Code Mode declaration");+ &bundled[offset..]+ } else {+ ""+ };+ tool["description"] = json!(format!("{description}{declaration}"));+ }+ }+ assert_eq!(request.body_json()["tools"], expected);+ }+ Ok(())+}diff --git a/codex-rs/core/tests/suite/step_settings.rs b/codex-rs/core/tests/suite/step_settings.rsindex 04e2bea4c2..833c6299fd 100644--- a/codex-rs/core/tests/suite/step_settings.rs+++ b/codex-rs/core/tests/suite/step_settings.rs@@ -2280,6 +2280,11 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {.features.enable(Feature::MultiAgentV2).expect("test config should allow feature update");+ config+ .features+ .enable(Feature::AgentMessageBoard)+ .expect("test config should allow channel tools");+ config.ephemeral = false;config.multi_agent_v2.expose_spawn_agent_model_overrides = false;config.multi_agent_v2.non_code_mode_only = true;config.code_mode.disable_in_process_fallback = true;@@ -2316,6 +2321,8 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {wait_agent: tool_message("wait_agent"),interrupt_agent: tool_message("interrupt_agent"),list_agents: tool_message("list_agents"),+ post: tool_message("post"),+ ..Default::default()}),code_mode: Some(CodeModeToolMessages {exec: Some(ToolMessage {@@ -2369,10 +2376,13 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {"parameters": tool["parameters"],}))}).into_iter().collect::<serde_json::Map<String, Value>>();+ let channel_post = namespace_child_tool(&body, "collaboration", "post").expect("post");json!({"model": body["model"],"async_description": tool("request_user_input_async")["description"],"multi_agent_messages": multi_agent_messages,+ "channel_post_description": channel_post["description"].as_str().expect("post description").lines().next(),+ "channel_post_required": channel_post["parameters"]["required"],"exec_description": tool("exec")["description"],"wait_description": tool("wait")["description"],"wait_parameters": tool("wait")["parameters"],@@ -2390,6 +2400,8 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {}))).into_iter().collect::<serde_json::Map<String, Value>>(),+ "channel_post_description": format!("post description for {model}."),+ "channel_post_required": ["text"],"exec_description": format!("Exec description for {model}."),"wait_description": format!("Wait description for {model}."),"wait_parameters": wait_parameters(model),diff --git a/codex-rs/ext/agent-message-board/src/extension.rs b/codex-rs/ext/agent-message-board/src/extension.rsindex e18cd7e123..4c3b7f0cde 100644--- a/codex-rs/ext/agent-message-board/src/extension.rs+++ b/codex-rs/ext/agent-message-board/src/extension.rs@@ -5,7 +5,7 @@//! Tool namespaces follow the host's configuration at runtime startup.use crate::AgentMessageBoard;-use crate::message_board_tools;+use crate::tools::message_board_tools_with_descriptions;use codex_extension_api::ExtensionData;use codex_extension_api::ExtensionEventSink;use codex_extension_api::ExtensionFuture;@@ -19,6 +19,7 @@ use codex_protocol::SessionId;use codex_protocol::ThreadId;use codex_protocol::error::CodexErr;use codex_protocol::error::Result;+use codex_protocol::openai_models::MultiAgentToolMessages;use codex_tools::ToolCall;use codex_tools::ToolExecutor;use futures::future::BoxFuture;@@ -88,16 +89,37 @@ impl<C: Sync> ToolContributor for BoardExtension<C> {&self,_session_store: &ExtensionData,thread_store: &ExtensionData,+ ) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {+ self.tools_with_descriptions(thread_store, /*tool_messages*/ None)+ }++ fn tools_for_step(+ &self,+ _session_store: &ExtensionData,+ thread_store: &ExtensionData,+ step_store: &ExtensionData,+ ) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {+ let tool_messages = step_store.get::<MultiAgentToolMessages>();+ self.tools_with_descriptions(thread_store, tool_messages.as_deref())+ }+}++impl<C> BoardExtension<C> {+ fn tools_with_descriptions(+ &self,+ thread_store: &ExtensionData,+ tool_messages: Option<&MultiAgentToolMessages>,) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {thread_store.get::<Binding>().map_or_else(Vec::new, |binding| {- message_board_tools(+ message_board_tools_with_descriptions(binding.board.clone(),binding.caller,binding.path.clone(),binding.namespace.as_deref(),self.namespace_description,+ tool_messages,)})}diff --git a/codex-rs/ext/agent-message-board/src/tools.rs b/codex-rs/ext/agent-message-board/src/tools.rsindex 39815c83a9..eef7cea000 100644--- a/codex-rs/ext/agent-message-board/src/tools.rs+++ b/codex-rs/ext/agent-message-board/src/tools.rs@@ -20,6 +20,7 @@ use crate::ThreadQuery;use crate::ThreadSort;use codex_protocol::AgentPath;use codex_protocol::ThreadId;+use codex_protocol::openai_models::MultiAgentToolMessages;use codex_tools::FunctionCallError;use codex_tools::JsonToolOutput;use codex_tools::ToolCall;@@ -46,10 +47,35 @@ pub fn message_board_tools(caller_path: AgentPath,namespace: Option<&str>,namespace_description: &str,+) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {+ message_board_tools_with_descriptions(+ board,+ caller,+ caller_path,+ namespace,+ namespace_description,+ /*tool_messages*/ None,+ )+}++pub(crate) fn message_board_tools_with_descriptions(+ board: Arc<dyn AgentMessageBoard>,+ caller: ThreadId,+ caller_path: AgentPath,+ namespace: Option<&str>,+ namespace_description: &str,+ tool_messages: Option<&MultiAgentToolMessages>,) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {spec::NAMES.into_iter().map(|name| {+ let tool_message = tool_messages.and_then(|tools| tools.by_name(name));+ if tool_message.is_some_and(|tool| tool.parameters.is_some()) {+ tracing::warn!(+ tool = name,+ "Channel tool parameters cannot be overridden; using bundled parameters"+ );+ }Arc::new(BoardTool {board: board.clone(),caller,@@ -57,6 +83,7 @@ pub fn message_board_tools(name,namespace: namespace.map(str::to_owned),namespace_description: namespace_description.to_owned(),+ description: tool_message.and_then(|tool| tool.description.clone()),}) as Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>}).collect()@@ -69,6 +96,7 @@ struct BoardTool {name: &'static str,namespace: Option<String>,namespace_description: String,+ description: Option<String>,}impl<'call> ToolExecutor<ToolCall<'call>> for BoardTool {@@ -80,6 +108,7 @@ impl<'call> ToolExecutor<ToolCall<'call>> for BoardTool {self.name,self.namespace.as_deref(),&self.namespace_description,+ self.description.as_deref(),)}fn supports_parallel_tool_calls(&self) -> bool {diff --git a/codex-rs/ext/agent-message-board/src/tools/spec.rs b/codex-rs/ext/agent-message-board/src/tools/spec.rsindex c9b4410785..956494a717 100644--- a/codex-rs/ext/agent-message-board/src/tools/spec.rs+++ b/codex-rs/ext/agent-message-board/src/tools/spec.rs@@ -19,20 +19,25 @@ pub(super) const NAMES: [&str; 9] = ["post",];-pub(super) fn tool(name: &str, namespace: Option<&str>, namespace_description: &str) -> ToolSpec {+pub(super) fn tool(+ name: &str,+ namespace: Option<&str>,+ namespace_description: &str,+ description_override: Option<&str>,+) -> ToolSpec {let (description, fields, required): (&str, &[&str], &[&str]) = match name {"create_channel" => (- "Create a channel shared by this agent tree. Subscribe to new discussion roots by default.",+ "Create a channel where all agents in this collaboration can read and post messages. You are subscribed to new top-level posts by default.",&["channel_name", "subscribe"],&["channel_name"],),"get_channels" => (- "Find channels by case-insensitive name substring, ordered by activity.",+ "List channels, most recently active first, or search by a case-insensitive part of the name. Creating a channel or posting in it counts as activity.",&["query", "recent_first", "limit", "cursor"],&[],),"list_threads" => (- "List discussion roots with bounded previews; sort by created (default) or activity.",+ "List a channel's threads with previews of the first post and latest reply. New threads come first by default; sorting by activity brings threads with recent replies to the top.",&["channel_name","sort",@@ -44,7 +49,7 @@ pub(super) fn tool(name: &str, namespace: Option<&str>, namespace_description: &&["channel_name"],),"search_posts" => (- "Search posts by case-insensitive text substring, newest first. Filters combine. Agent references may be absolute or relative to you.",+ "Search top-level posts and replies, newest first. Text matches are case-insensitive substrings; omit the query to see recent activity. You can narrow by channel, author, or posts after a message ID. Results are previews; read_post can retrieve the full text.",&["channel_name","query",@@ -57,22 +62,27 @@ pub(super) fn tool(name: &str, namespace: Option<&str>, namespace_description: &&[],),"read_thread" => (- "Read a discussion root and newest replies. The root repeats on each page; the cursor advances replies.",+ "Read a thread using its first post's message ID. Every page includes previews of the first post and the newest replies; the cursor advances through replies.",&["thread_id", "limit", "cursor", "max_chars_per_post"],&["thread_id"],),"read_post" => (- "Read part of one post. Offsets and lengths count Unicode characters; continue at next_offset_chars until n_chars.",+ "Read a post or reply by message ID, without needing its channel. Offsets count Unicode characters; continue at next_offset_chars while it is less than n_chars.",&["message_id", "offset_chars", "limit_chars"],&["message_id"],),- "subscribe" | "unsubscribe" => (- "Change a channel OR discussion subscription, optionally for another tree member. Channel subscriptions notify new roots; thread subscriptions notify replies. Notices only reach currently running turns, with no later backlog.",+ "subscribe" => (+ "Subscribe yourself or another agent to a channel for new top-level posts, or to a thread for replies. Provide exactly one of channel_name or thread_id. Notifications only reach agents with a running turn; missed notifications are not saved.",+ &["channel_name", "thread_id", "target_agent"],+ &[],+ ),+ "unsubscribe" => (+ "Unsubscribe yourself or another agent from a channel or thread. Provide exactly one of channel_name or thread_id. Posting again does not undo a thread unsubscribe. Agents explicitly named on a post can still receive that notification.",&["channel_name", "thread_id", "target_agent"],&[],),"post" => (- "Post to exactly one existing channel, new channel, or discussion thread. Posting follows the discussion unless you unsubscribed. Explicit agent recipients get a notice without subscribing. Notices never start idle agents. Returns metadata, not the post body.",+ "Start a thread in an existing or new channel, or reply using the first post's message ID as thread_id. Exactly one destination is required. Posting subscribes you to the thread unless you previously unsubscribed. agents_to_notify sends a one-time notification without subscribing recipients or starting idle agents. Returns metadata, not the post text.",&["text","channel_name",@@ -91,7 +101,10 @@ pub(super) fn tool(name: &str, namespace: Option<&str>, namespace_description: &json!({"type":"string","description":"Create and subscribe to this channel."})}"subscribe" => {- json!({"type":"boolean","description":"Subscribe to new roots. Default true."})+ json!({"type":"boolean","description":"Subscribe to new top-level posts. Default true."})+ }+ "author" | "target_agent" => {+ json!({"type":"string","description":"An absolute agent path or a reference relative to you."})}"recent_first" => json!({"type":"boolean","description":"Newest first by default."}),"limit" => {@@ -115,7 +128,7 @@ pub(super) fn tool(name: &str, namespace: Option<&str>, namespace_description: &let parameters = json!({"type":"object","properties":properties,"required":required,"additionalProperties":false});let tool = ResponsesApiTool {name: name.into(),- description: description.into(),+ description: description_override.unwrap_or(description).into(),strict: false,defer_loading: None,parameters: parse_tool_input_schema(¶meters)diff --git a/codex-rs/prompts/src/model_messages.rs b/codex-rs/prompts/src/model_messages.rsindex d7b7ef8298..3d68ec518c 100644--- a/codex-rs/prompts/src/model_messages.rs+++ b/codex-rs/prompts/src/model_messages.rs@@ -166,20 +166,10 @@ impl<'a> ResolvedModelMessages<'a> {}fn multi_agent_tool(self, tool_name: &str) -> Option<&'a ToolMessage> {- let tools = self- .catalog_messages+ self.catalog_messages.and_then(|messages| messages.tools.as_ref())- .and_then(|tools| tools.multi_agent.as_ref())?;- let tool = match tool_name {- "spawn_agent" => &tools.spawn_agent,- "send_message" => &tools.send_message,- "followup_task" => &tools.followup_task,- "wait_agent" => &tools.wait_agent,- "interrupt_agent" => &tools.interrupt_agent,- "list_agents" => &tools.list_agents,- _ => return None,- };- tool.as_ref()+ .and_then(|tools| tools.multi_agent.as_ref())?+ .by_name(tool_name)}/// Selects indirect tool guidance; tool rendering owns namespace mapping and normalization.diff --git a/codex-rs/protocol/src/openai_models.rs b/codex-rs/protocol/src/openai_models.rsindex 7f4578180f..05c38eec98 100644--- a/codex-rs/protocol/src/openai_models.rs+++ b/codex-rs/protocol/src/openai_models.rs@@ -622,6 +622,7 @@ pub struct ToolMessage {}/// Model-owned descriptions and parameters for Multi-Agent V2 tools, independent of their namespace.+/// Channel tools consume only the description; their parameter schemas are fixed.#[derive(Debug, Default, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]pub struct MultiAgentToolMessages {/// Replaces the static description. Missing or null uses the bundled text; an empty string@@ -638,6 +639,49 @@ pub struct MultiAgentToolMessages {pub interrupt_agent: Option<ToolMessage>,#[serde(default, skip_serializing_if = "Option::is_none")]pub list_agents: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub create_channel: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub get_channels: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub list_threads: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub search_posts: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub read_thread: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub read_post: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub subscribe: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub unsubscribe: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub post: Option<ToolMessage>,+}++impl MultiAgentToolMessages {+ /// Returns the catalog entry for a tool, independently of its runtime namespace.+ pub fn by_name(&self, name: &str) -> Option<&ToolMessage> {+ match name {+ "spawn_agent" => &self.spawn_agent,+ "send_message" => &self.send_message,+ "followup_task" => &self.followup_task,+ "wait_agent" => &self.wait_agent,+ "interrupt_agent" => &self.interrupt_agent,+ "list_agents" => &self.list_agents,+ "create_channel" => &self.create_channel,+ "get_channels" => &self.get_channels,+ "list_threads" => &self.list_threads,+ "search_posts" => &self.search_posts,+ "read_thread" => &self.read_thread,+ "read_post" => &self.read_post,+ "subscribe" => &self.subscribe,+ "unsubscribe" => &self.unsubscribe,+ "post" => &self.post,+ _ => return None,+ }+ .as_ref()+ }}/// Model-owned instructions for Code Mode's exec and wait tools.