Align specs

codex-rs/core/gpt-5.1-codex-max_prompt.md

@@ -23,17 +23,17 @@ You are Codex, based on GPT-5. You are running as a coding agent in the Codex CL
 If the `collaboration_*` tools are present, agent profiles are loaded from `$CODEX_HOME/agents.toml` and your session is the `main` agent (agent 0).
 
 You can spawn and coordinate child agents using these tools (only on this model):
-- `collaboration_init_agent`: create a direct child by agent profile name. `agent` is required (and schema-enforced to the allowed `sub_agents` for the calling agent). No initial message is sent at this point.
-- `collaboration_send`: send a user-message to your direct children by id. You can only send messages to previously initialized agents using `collaboration_init_agent`. If the target child is already running, the call fails; `wait` first.
-- `collaboration_wait`: wait up to `max_duration` milliseconds (wall time) for running children to finish and surface their last message/status. You can only wait on direct child agents.
-- `collaboration_get_state`: see the calling agent’s direct children, their statuses, and last messages.
-- `collaboration_close`: close specific children (and their descendants). Only do that when you are done with a child agent.
+- `collaboration_init_agent`: create a direct child by agent profile name. `agent` defaults to the caller’s agent type; `context_strategy` and `message` are optional. If you pass a non-empty `message`, the child starts immediately; otherwise follow with `collaboration_send`.
+- `collaboration_send`: send a user-message to your direct children by id (string). You can only send messages to previously initialized agents using `collaboration_init_agent`. If the target child is already running, the call fails; `wait` first.
+- `collaboration_wait`: wait up to `max_duration` milliseconds (wall time) for running children to finish and surface their latest state. You can only wait on direct child agents (optionally specify `agent_idx`).
+- `collaboration_get_state`: see the calling agent’s direct children (or a provided `agent_idx` list), their statuses, and latest messages via `state`.
+- `collaboration_close`: close specific children (and their descendants). Use `return_states` if you want the pre-close states.
 
-Each agent uses its own profile `prompt` (no prompt inheritance). An agent’s model and sandbox policy come from its profile (`model` defaults to the main model; `read_only` selects a read-only sandbox vs the session default). Always `wait` after `send` to drive children forward; keep communication concise and include the expected output format. Use `get_state` if unsure about child ids/status.
+Each agent uses its own profile `instructions` (no prompt inheritance). An agent’s model and sandbox policy come from its profile (`model` defaults to the main model; `read_only` selects a read-only sandbox vs the session default). Always `wait` after `send` (or after init with `message`) to drive children forward; keep communication concise and include the expected output format. Use `get_state` if unsure about child ids/status.
 
 Use collaboration only for larger, multi-step tasks; simple requests should stay single-agent.
 
-A `collaboration_send` is always necessary after a `collaboration_init_agent` to start the child agent working. 
+If you did not include a `message` in `collaboration_init_agent`, follow with `collaboration_send` to start the child agent working.
 
 ## Plan tool
 

codex-rs/core/src/agents.rs

@@ -1,16 +1,18 @@
 use std::collections::HashMap;
 use std::path::Path;
 
+use codex_protocol::openai_models::ReasoningEffort;
 use serde::Deserialize;
 use tracing::warn;
 
 #[derive(Debug, Clone)]
 pub(crate) struct AgentDefinition {
     pub(crate) name: String,
-    pub(crate) prompt: Option<String>,
+    pub(crate) instructions: Option<String>,
     pub(crate) sub_agents: Vec<String>,
     pub(crate) read_only: bool,
     pub(crate) model: Option<String>,
+    pub(crate) reasoning_effort: Option<ReasoningEffort>,
 }
 
 #[derive(Debug, Clone)]
@@ -20,14 +22,16 @@ pub(crate) struct AgentsConfig {
 
 #[derive(Debug, Deserialize)]
 struct RawAgentDefinition {
-    #[serde(default)]
-    prompt: Option<String>,
+    #[serde(default, alias = "prompt")]
+    instructions: Option<String>,
     #[serde(default)]
     sub_agents: Vec<String>,
     #[serde(default)]
     read_only: bool,
     #[serde(default)]
     model: Option<String>,
+    #[serde(default)]
+    reasoning_effort: Option<ReasoningEffort>,
 }
 
 impl AgentsConfig {
@@ -65,21 +69,22 @@ impl AgentsConfig {
                 return Err(format!("agent {name}: model must be non-empty when set"));
             }
 
-            let prompt = agent.prompt.and_then(|prompt| {
-                if prompt.trim().is_empty() {
+            let instructions = agent.instructions.and_then(|instructions| {
+                if instructions.trim().is_empty() {
                     None
                 } else {
-                    Some(prompt)
+                    Some(instructions)
                 }
             });
             agents.insert(
                 name.clone(),
                 AgentDefinition {
                     name,
-                    prompt,
+                    instructions,
                     sub_agents: agent.sub_agents,
                     read_only: agent.read_only,
                     model: agent.model,
+                    reasoning_effort: agent.reasoning_effort,
                 },
             );
         }

codex-rs/core/src/codex.rs

@@ -639,11 +639,14 @@ impl Session {
         let mut session_configuration = session_configuration;
         if let Some(agents_config) = agents_config.as_ref() {
             let main = agents_config.main();
-            session_configuration.developer_instructions = main.prompt.clone();
+            session_configuration.developer_instructions = main.instructions.clone();
             session_configuration.user_instructions = None;
             if let Some(model) = main.model.clone() {
                 session_configuration.model = model;
             }
+            if let Some(effort) = main.reasoning_effort {
+                session_configuration.model_reasoning_effort = Some(effort);
+            }
             if main.read_only {
                 session_configuration.sandbox_policy = SandboxPolicy::ReadOnly;
             }

codex-rs/core/src/state/collaboration.rs

@@ -53,7 +53,7 @@ pub(crate) enum AgentLifecycleState {
 pub(crate) enum ContextStrategy {
     New,
     Fork,
-    Replace { history: Vec<ResponseItem> },
+    Replace(Vec<ResponseItem>),
 }
 
 impl Default for ContextStrategy {