Skip to content

armgit / codex

Public Imported from GitHub
0

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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(&parameters)
diff --git a/codex-rs/prompts/src/model_messages.rs b/codex-rs/prompts/src/model_messages.rs
index 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.rs
index 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.