Lightweight coding agent that runs in your terminal
Rust
Notify parent agents when Guardian stops a subagent (#49312)
jif63475131ce5f
diff --git a/codex-rs/core/src/agent/api.rs b/codex-rs/core/src/agent/api.rsindex e2ef8de4b5..e4d434667f 100644--- a/codex-rs/core/src/agent/api.rs+++ b/codex-rs/core/src/agent/api.rs@@ -19,6 +19,7 @@ use codex_protocol::SessionId;use codex_protocol::ThreadId;use codex_protocol::error::Result;use codex_protocol::protocol::AgentStatus;+use codex_protocol::protocol::CodexErrorInfo;use codex_protocol::protocol::MultiAgentVersion;use codex_protocol::protocol::SessionSource;use codex_protocol::protocol::TokenUsage;@@ -225,6 +226,8 @@ pub struct AgentTurnOutcome {pub parent_turn_id: Option<String>,pub initiating_agent_path: Option<AgentPath>,pub status: AgentStatus,+ /// Typed reason used to choose guidance in the parent notification.+ pub error_info: Option<CodexErrorInfo>,}/// Settings shared by the tree. A service tier of `None` restores the default tier.diff --git a/codex-rs/core/src/agent/control/completion.rs b/codex-rs/core/src/agent/control/completion.rsindex 0f09257a97..8e041dcf70 100644--- a/codex-rs/core/src/agent/control/completion.rs+++ b/codex-rs/core/src/agent/control/completion.rs@@ -8,10 +8,12 @@ use crate::TurnStartOptions;use crate::agent::api::AgentTurnOutcome;use crate::agent_communication::AgentCommunicationContext;use crate::agent_communication::AgentCommunicationKind;+use crate::session_prefix::format_guardian_interruption_message;use crate::session_prefix::format_inter_agent_completion_message;use codex_protocol::AgentPath;use codex_protocol::items::SubAgentActivityItem;use codex_protocol::protocol::AgentStatus;+use codex_protocol::protocol::CodexErrorInfo;use codex_protocol::protocol::InterAgentCommunication;use codex_protocol::protocol::SessionSource;use codex_protocol::protocol::SubAgentActivityKind;@@ -85,11 +87,21 @@ impl LocalAgentControl {}}- let Some(message) = format_inter_agent_completion_message(- parent_agent_path.clone(),- child_agent_path.clone(),- &status,- ) else {+ let message = match (&status, outcome.error_info) {+ (AgentStatus::Errored(error), Some(CodexErrorInfo::TooManyDenials)) => {+ Some(format_guardian_interruption_message(+ parent_agent_path.clone(),+ child_agent_path.clone(),+ error,+ ))+ }+ _ => format_inter_agent_completion_message(+ parent_agent_path.clone(),+ child_agent_path.clone(),+ &status,+ ),+ };+ let Some(message) = message else {return;};// `communication` owns the message. Keep a second copy only when thediff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rsindex fbeea01823..99066080af 100644--- a/codex-rs/core/src/session/mod.rs+++ b/codex-rs/core/src/session/mod.rs@@ -2319,6 +2319,7 @@ impl Session {return;};+ let mut error_info = None;let status = match turn_context.terminal_error.lock().await.take() {Some(error) => {let status = AgentStatus::Errored(error.message);@@ -2326,10 +2327,21 @@ impl Session {status}None => {- let Some(status) = agent_status_from_event(msg) else {- return;- };- status+ if let EventMsg::TurnAborted(event) = msg+ && event.reason == TurnAbortReason::Interrupted+ && let Some(error) = &event.error+ && error.codex_error_info == Some(CodexErrorInfo::TooManyDenials)+ {+ // Report the safety stop to the parent without changing the child's+ // interrupted status or notifying for ordinary interruptions.+ error_info = error.codex_error_info.clone();+ AgentStatus::Errored(error.message.clone())+ } else {+ let Some(status) = agent_status_from_event(msg) else {+ return;+ };+ status+ }}};if !is_final(&status) {@@ -2349,6 +2361,7 @@ impl Session {.initiating_agent_path().cloned(),status,+ error_info,},&self.services.rollout_thread_trace,)diff --git a/codex-rs/core/src/session_prefix.rs b/codex-rs/core/src/session_prefix.rsindex 315ef1cabf..8e0bbf5a06 100644--- a/codex-rs/core/src/session_prefix.rs+++ b/codex-rs/core/src/session_prefix.rs@@ -11,6 +11,7 @@ const COMPLETION_MESSAGE_ENVELOPE_TOKEN_RESERVE: usize = 100;const ERROR_MAX_TOKENS: usize =COMPLETION_MESSAGE_MAX_TOKENS - COMPLETION_MESSAGE_ENVELOPE_TOKEN_RESERVE;const ERROR_NEXT_ACTION: &str = "This agent's turn failed. If you still need this agent, use the available collaboration tools to give it another task.";+const GUARDIAN_NEXT_ACTION: &str = "Tell the user this agent stopped after repeated Guardian denials. Do not resume this agent or retry its blocked work until the user explicitly confirms that it should continue.";// Helpers for model-visible session state markers that are stored in user-role// messages but are not user intent.@@ -35,6 +36,16 @@ pub(crate) fn format_inter_agent_completion_message(Some(InterAgentCompletionMessage::new(task_name, sender, payload).render())}+pub(crate) fn format_guardian_interruption_message(+ task_name: AgentPath,+ sender: AgentPath,+ error: &str,+) -> String {+ let error = truncate_text(error, TruncationPolicy::Tokens(ERROR_MAX_TOKENS));+ let payload = format!("Agent interrupted by Guardian: {error}\n\n{GUARDIAN_NEXT_ACTION}");+ InterAgentCompletionMessage::new(task_name, sender, payload).render()+}+#[cfg(test)]#[path = "session_prefix_tests.rs"]mod tests;diff --git a/codex-rs/core/src/session_prefix_tests.rs b/codex-rs/core/src/session_prefix_tests.rsindex 6a658ce852..227f0aa54a 100644--- a/codex-rs/core/src/session_prefix_tests.rs+++ b/codex-rs/core/src/session_prefix_tests.rs@@ -4,6 +4,8 @@ use codex_utils_output_truncation::approx_token_count;use super::COMPLETION_MESSAGE_MAX_TOKENS;use super::ERROR_NEXT_ACTION;+use super::GUARDIAN_NEXT_ACTION;+use super::format_guardian_interruption_message;use super::format_inter_agent_completion_message;#[test]@@ -18,3 +20,15 @@ fn error_completion_message_stays_below_manual_review_threshold() {assert!(approx_token_count(&message) < COMPLETION_MESSAGE_MAX_TOKENS);assert!(message.contains(ERROR_NEXT_ACTION));}++#[test]+fn guardian_interruption_message_stays_below_manual_review_threshold() {+ let message = format_guardian_interruption_message(+ AgentPath::root(),+ AgentPath::try_from("/root/worker").expect("valid agent path"),+ &"Action is not authorized. ".repeat(1_000),+ );++ assert!(approx_token_count(&message) < COMPLETION_MESSAGE_MAX_TOKENS);+ assert!(message.contains(GUARDIAN_NEXT_ACTION));+}diff --git a/codex-rs/core/tests/suite/guardian_subagent_notification_tests.rs b/codex-rs/core/tests/suite/guardian_subagent_notification_tests.rsnew file mode 100644index 0000000000..495ae98065--- /dev/null+++ b/codex-rs/core/tests/suite/guardian_subagent_notification_tests.rs@@ -0,0 +1,271 @@+//! Guardian circuit breakers notify the parent without changing the child's interrupted state.++use super::*;+use codex_config::config_toml::CircuitBreakAction;+use codex_core::config::Constrained;+use codex_extension_api::ExtensionRegistryBuilder;+use codex_protocol::config_types::ApprovalsReviewer;+use codex_protocol::protocol::CodexErrorInfo;+use codex_protocol::protocol::ErrorEvent;+use codex_protocol::protocol::MultiAgentVersion;+use codex_protocol::protocol::TurnAbortReason;+use core_test_support::ThreadIdle;+use core_test_support::streaming_sse::StreamingSseChunk;+use core_test_support::streaming_sse::start_streaming_sse_server;+use pretty_assertions::assert_eq;+use std::sync::Arc;+use test_case::test_case;+use tokio::sync::oneshot;++#[test_case(CircuitBreakAction::Strict; "strict_notifies_parent")]+#[test_case(CircuitBreakAction::Default; "default_stays_silent")]+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn guardian_circuit_breaker_notifies_parent(action: CircuitBreakAction) -> Result<()> {+ skip_if_no_network!(Ok(()));+ let server = start_mock_server().await;+ let mut extensions = ExtensionRegistryBuilder::new();+ extensions.thread_lifecycle_contributor(Arc::new(ThreadIdle));+ let test = test_codex()+ .with_model_info_override("test-gpt-5.1-codex", |model| {+ model.multi_agent_version = Some(MultiAgentVersion::V2);+ model.auto_review_model_override = Some(model.slug.clone());+ })+ .with_extensions(Arc::new(extensions.build()))+ .with_config(move |config| {+ for feature in [+ Feature::Collab,+ Feature::MultiAgentV2,+ Feature::GuardianApproval,+ ] {+ config+ .features+ .enable(feature)+ .expect("enable test feature");+ }+ config.permissions.approval_policy = Constrained::allow_any(AskForApproval::OnRequest);+ config.approvals_reviewer = ApprovalsReviewer::AutoReview;+ config.guardian_circuit_break_action = action;+ config.model_provider.stream_max_retries = Some(0);+ })+ .build_with_auto_env(&server)+ .await?;+ let root = test.session_configured.thread_id;+ let is_root = move |request: &wiremock::Request| {+ decoded_body(request)+ .and_then(|body| serde_json::from_slice::<Value>(&body).ok())+ .is_some_and(|body| body["client_metadata"]["thread_id"] == json!(root))+ };+ let is_worker = move |request: &wiremock::Request| {+ decoded_body(request)+ .and_then(|body| serde_json::from_slice::<Value>(&body).ok())+ .is_some_and(|body| {+ body["client_metadata"]["x-codex-parent-thread-id"] == json!(root)+ && body["client_metadata"]["x-openai-subagent"] != "guardian"+ })+ };+ let spawn = mount_sse_once_match(+ &server,+ is_root,+ sse(vec![+ ev_function_call_with_namespace(+ SPAWN_CALL_ID,+ MULTI_AGENT_V2_NAMESPACE,+ "spawn_agent",+ &json!({+ "task_name": "worker", "fork_turns": "none", "message": "Run the checks."+ })+ .to_string(),+ ),+ ev_completed("spawn-worker"),+ ]),+ )+ .await;+ let parent_idle =+ mount_sse_once_match(&server, is_root, sse(vec![ev_completed("parent-idle")])).await;+ let mut calls = Vec::new();+ let mut reviews = Vec::new();+ for call in ["first", "second", "third"] {+ calls.push(+ mount_sse_once_match(+ &server,+ is_worker,+ sse(vec![+ ev_function_call(+ call,+ "exec_command",+ &json!({+ "cmd": format!("echo {call}"),+ "sandbox_permissions": "require_escalated",+ "justification": "Exercise Guardian review."+ })+ .to_string(),+ ),+ ev_completed(call),+ ]),+ )+ .await,+ );+ reviews.push(mount_sse_once_match(+ &server,+ |request: &wiremock::Request| {+ decoded_body(request)+ .and_then(|body| serde_json::from_slice::<Value>(&body).ok())+ .is_some_and(|body| body["client_metadata"]["x-openai-subagent"] == "guardian")+ },+ sse(vec![+ ev_assistant_message(+ "denied",+ r#"{"risk_level":"high","user_authorization":"low","outcome":"deny","rationale":"Action is not authorized."}"#,+ ),+ ev_completed("review-denied"),+ ]),+ ).await);+ }+ // A continuation can race the third denial's interruption. Keep it pending so+ // only the actual Guardian circuit breaker can end the child's turn.+ let (_release, gate) = oneshot::channel();+ let (pending, _) = start_streaming_sse_server(vec![vec![StreamingSseChunk {+ gate: Some(gate),+ body: sse(vec![ev_completed("unexpected-worker-completion")]),+ }]])+ .await;+ Mock::given(method("POST"))+ .and(path("/v1/responses"))+ .and(is_worker)+ .respond_with(+ wiremock::ResponseTemplate::new(/*s*/ 307)+ .insert_header("location", format!("{}/v1/responses", pending.uri())),+ )+ .with_priority(/*priority*/ 20)+ .mount(&server)+ .await;++ let mut created = test.thread_manager.subscribe_thread_created();+ test.submit_text_turn("Spawn a worker to run the checks.")+ .await?;+ ThreadIdle::wait(&test.codex).await;+ let worker = test+ .thread_manager+ .get_thread(created.recv().await?)+ .await?;+ let warning = wait_for_event_match(&worker, |event| match event {+ EventMsg::GuardianWarning(warning) if warning.message.contains("3 consecutive") => {+ Some(warning.message.clone())+ }+ _ => None,+ })+ .await;+ let aborted = wait_for_event_match(&worker, |event| match event {+ EventMsg::TurnAborted(aborted) => Some(aborted.clone()),+ _ => None,+ })+ .await;+ ThreadIdle::wait(&worker).await;+ assert_eq!(+ (aborted.reason, aborted.error, worker.agent_status().await),+ (+ TurnAbortReason::Interrupted,+ (action == CircuitBreakAction::Strict).then_some(ErrorEvent {+ message: warning.clone(),+ codex_error_info: Some(CodexErrorInfo::TooManyDenials),+ misalignment: None,+ }),+ AgentStatus::Interrupted,+ ),+ );++ // Delivery is queued. If the parent samples before draining its mailbox,+ // wait_agent must observe the notification before the next model request.+ let _wait = if action == CircuitBreakAction::Strict {+ Some(+ mount_sse_once_match(+ &server,+ move |request: &wiremock::Request| {+ is_root(request) && !body_contains(request, "Agent interrupted by Guardian:")+ },+ sse(vec![+ ev_function_call_with_namespace(+ "wait-worker",+ MULTI_AGENT_V2_NAMESPACE,+ "wait_agent",+ "{}",+ ),+ ev_completed("parent-wait"),+ ]),+ )+ .await,+ )+ } else {+ None+ };+ let continued = mount_sse_once_match(+ &server,+ move |request: &wiremock::Request| {+ is_root(request)+ && (action == CircuitBreakAction::Default+ || body_contains(request, "Agent interrupted by Guardian:"))+ },+ sse(vec![ev_completed("parent-continued")]),+ )+ .await;+ test.submit_text_turn("Report the worker's status.").await?;+ let continued_request = continued.single_request();+ let messages = continued_request.inputs_of_type("agent_message");+ let expected = if action == CircuitBreakAction::Strict {+ vec![json!({+ "type": "agent_message",+ "author": "/root/worker",+ "recipient": "/root",+ "content": [{+ "type": "input_text",+ "text": format!(+ "Message Type: FINAL_ANSWER\nTask name: /root\nSender: /root/worker\nPayload:\nAgent interrupted by Guardian: {warning}\n\nTell the user this agent stopped after repeated Guardian denials. Do not resume this agent or retry its blocked work until the user explicitly confirms that it should continue."+ ),+ }],+ })]+ } else {+ Vec::new()+ };+ assert_eq!(+ strip_response_item_ids_from_json(strip_metadata_from_json(json!(messages))),+ json!(expected),+ );+ assert_eq!(+ spawn.single_request().body_json()["client_metadata"]["thread_id"],+ json!(root)+ );+ assert!(parent_idle.requests().iter().any(|request| {+ request.body_json()["client_metadata"]["thread_id"] == json!(root)+ && request.function_call_output(SPAWN_CALL_ID)["output"].is_string()+ }));+ assert_eq!(+ reviews+ .iter()+ .map(|review| review+ .requests()+ .into_iter()+ .filter(|request| {+ request.body_json()["client_metadata"]["x-openai-subagent"] == "guardian"+ })+ .count())+ .collect::<Vec<_>>(),+ vec![1, 1, 1],+ );+ assert_eq!(+ calls+ .iter()+ .map(|call| call+ .requests()+ .into_iter()+ .filter(|request| {+ request.body_json()["client_metadata"]["x-codex-parent-thread-id"]+ == json!(root)+ && request.body_json()["client_metadata"]["x-openai-subagent"] != "guardian"+ })+ .count())+ .collect::<Vec<_>>(),+ vec![1, 1, 1]+ );+ pending.shutdown().await;+ Ok(())+}diff --git a/codex-rs/core/tests/suite/subagent_notifications.rs b/codex-rs/core/tests/suite/subagent_notifications.rsindex ccd44bb92d..89deaae707 100644--- a/codex-rs/core/tests/suite/subagent_notifications.rs+++ b/codex-rs/core/tests/suite/subagent_notifications.rs@@ -80,6 +80,9 @@ use super::direct_tool_metadata::tool_call_metadata;#[path = "spawn_settings_tests.rs"]mod spawn_settings_tests;+#[path = "guardian_subagent_notification_tests.rs"]+mod guardian_subagent_notification_tests;+const SPAWN_CALL_ID: &str = "spawn-call-1";const MULTI_AGENT_V1_NAMESPACE: &str = "multi_agent_v1";const MULTI_AGENT_V2_NAMESPACE: &str = "collaboration";