Use step environments for Guardian approval reviews (#37618)

## Why

Deferred environments can become ready after a turn starts. Guardian approval
reviews must use the environment selected for the current step so their working
directory and permission context are not taken from the stale turn snapshot.

## What changed

- Carry `StepContext` through tool execution and approval handling.
- Add a Guardian review context that pairs the parent turn with the current
  step's environment snapshot.
- Use that snapshot for Guardian prompts, reviewer sessions, and delegated
  reviewer threads while retaining turn-level fallbacks for callers without a
  step context.

## Testing

Added an integration test that makes a deferred remote environment ready before
an escalated command and verifies Guardian receives that environment's working
directory and denied-read policy instead of the initial local environment's.

GitOrigin-RevId: 779096bc7d0e0c7453a009c02141029714b9b407
This commit is contained in:
sayan-oai authored and copyberry committed 2026-08-08 20:07:27 +00:00
1 parent 936f5eb3ee
commit dd43a9967f
29 files changed
+387 -131

No files matched your search

+49
View File
@@ -17,12 +17,16 @@ mod prompt;
mod review;
mod review_session;
use std::sync::Arc;
use std::time::Duration;
use codex_protocol::protocol::GuardianAssessmentOutcome;
use serde::Deserialize;
use serde::Serialize;
use crate::environment_selection::TurnEnvironmentSnapshot;
use crate::session::step_context::StepContext;
use crate::session::turn_context::TurnContext;
use crate::tools::sandboxing::ApprovalRequestReasons;
pub(crate) use approval_request::GuardianApprovalRequest;
@@ -62,6 +66,51 @@ const GUARDIAN_MAX_ACTION_STRING_TOKENS: usize = 16_000;
const GUARDIAN_RECENT_ENTRY_LIMIT: usize = 40;
const TRUNCATION_TAG: &str = "truncated";
/// Built from the originating StepContext when available.
/// There are currently two exceptions-- turn-only callers (background network approvals, reviewer
/// prewarming, etc.) and interactive Unix shells that can outlive the step that started them.
/// TODO(sayan): See if we can find a way to model those as StepContext as well without holding
/// step-scoped things past their lifetime (like MCP bindings)
#[derive(Clone)]
pub(crate) struct GuardianReviewContext {
turn: Arc<TurnContext>,
environments: TurnEnvironmentSnapshot,
}
impl GuardianReviewContext {
pub(crate) fn turn(&self) -> &Arc<TurnContext> {
&self.turn
}
pub(crate) fn environments(&self) -> &TurnEnvironmentSnapshot {
&self.environments
}
}
impl From<&Arc<StepContext>> for GuardianReviewContext {
fn from(step: &Arc<StepContext>) -> Self {
Self {
turn: Arc::clone(&step.turn),
environments: step.environments.clone(),
}
}
}
impl From<Arc<TurnContext>> for GuardianReviewContext {
fn from(turn: Arc<TurnContext>) -> Self {
Self {
environments: turn.environments.clone(),
turn,
}
}
}
impl From<&Arc<TurnContext>> for GuardianReviewContext {
fn from(turn: &Arc<TurnContext>) -> Self {
Self::from(Arc::clone(turn))
}
}
/// Structured output contract that the guardian reviewer must satisfy.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub(crate) struct GuardianAssessment {
+7 -7
View File
@@ -11,7 +11,6 @@ use serde_json::Value;
use crate::compact::content_items_to_text;
use crate::event_mapping::is_contextual_user_message_content;
use crate::session::session::Session;
use crate::session::turn_context::TurnContext;
use crate::session::turn_context::TurnEnvironment;
use codex_utils_output_truncation::TruncationPolicy;
use codex_utils_output_truncation::approx_bytes_for_tokens;
@@ -28,6 +27,7 @@ use super::GUARDIAN_MAX_TOOL_TRANSCRIPT_TOKENS;
use super::GUARDIAN_RECENT_ENTRY_LIMIT;
use super::GuardianApprovalRequest;
use super::GuardianAssessment;
use super::GuardianReviewContext;
use super::TRUNCATION_TAG;
use super::approval_request::format_guardian_action_pretty;
@@ -103,7 +103,7 @@ pub(crate) async fn build_guardian_prompt_items(
) -> serde_json::Result<GuardianPromptItems> {
build_guardian_prompt_items_with_parent_turn(
session,
/*parent_turn*/ None,
/*parent_context*/ None,
ApprovalRequestReasons {
approval: None,
retry: retry_reason,
@@ -116,7 +116,7 @@ pub(crate) async fn build_guardian_prompt_items(
pub(crate) async fn build_guardian_prompt_items_with_parent_turn(
session: &Session,
parent_turn: Option<&TurnContext>,
parent_context: Option<&GuardianReviewContext>,
reasons: ApprovalRequestReasons,
request: GuardianApprovalRequest,
mode: GuardianPromptMode,
@@ -201,7 +201,7 @@ pub(crate) async fn build_guardian_prompt_items_with_parent_turn(
if let Some(note) = omission_note {
push_text(format!("\n{note}\n"));
}
if let Some(denied_reads_context) = parent_turn.and_then(parent_turn_denied_reads_context) {
if let Some(denied_reads_context) = parent_context.and_then(parent_turn_denied_reads_context) {
push_text("\n>>> PARENT TURN PERMISSION CONTEXT START\n".to_string());
push_text(denied_reads_context);
push_text(">>> PARENT TURN PERMISSION CONTEXT END\n".to_string());
@@ -254,9 +254,9 @@ pub(crate) async fn build_guardian_prompt_items_with_parent_turn(
})
}
fn parent_turn_denied_reads_context(turn: &TurnContext) -> Option<String> {
// TODO(sayan): Pass StepContext through Guardian so it sees environments that become ready mid-turn.
let environment = turn.environments.primary();
fn parent_turn_denied_reads_context(context: &GuardianReviewContext) -> Option<String> {
let turn = context.turn();
let environment = context.environments().primary();
#[allow(deprecated)]
let cwd = environment
.and_then(|environment| environment.cwd().to_abs_path().ok())
+17 -12
View File
@@ -41,6 +41,7 @@ use super::GuardianAssessment;
use super::GuardianAssessmentOutcome;
use super::GuardianRejectionCircuitBreakerAction;
use super::GuardianRejectionCircuitBreakerPolicy;
use super::GuardianReviewContext;
use super::approval_request::guardian_assessment_action;
use super::approval_request::guardian_request_target_item_id;
use super::approval_request::guardian_request_turn_id;
@@ -303,12 +304,13 @@ pub(crate) async fn record_guardian_denial_for_test(
/// caller as distinct from explicit guardian denials.
async fn run_guardian_review(
session: Arc<Session>,
turn: Arc<TurnContext>,
context: GuardianReviewContext,
review_id: String,
request: GuardianApprovalRequest,
reasons: ApprovalRequestReasons,
options: GuardianReviewOptions,
) -> ReviewDecision {
let turn = Arc::clone(context.turn());
let GuardianReviewOptions {
plugin_attribution_override,
approval_request_source,
@@ -401,7 +403,7 @@ async fn run_guardian_review(
let terminal_action = action_summary.clone();
let (outcome, analytics_result) = Box::pin(run_guardian_review_session_with_retry(
session.clone(),
turn.clone(),
context,
request,
reasons,
schema,
@@ -643,7 +645,7 @@ pub(crate) struct GuardianReviewOptions {
/// Public entrypoint for approval requests that should be reviewed by guardian.
pub(crate) async fn review_approval_request(
session: &Arc<Session>,
turn: &Arc<TurnContext>,
context: impl Into<GuardianReviewContext>,
review_id: String,
request: GuardianApprovalRequest,
reasons: ApprovalRequestReasons,
@@ -652,7 +654,7 @@ pub(crate) async fn review_approval_request(
// guardian session state machine into their own async stack.
Box::pin(run_guardian_review(
Arc::clone(session),
Arc::clone(turn),
context.into(),
review_id,
request,
reasons,
@@ -667,7 +669,7 @@ pub(crate) async fn review_approval_request(
pub(crate) async fn review_approval_request_with_cancel(
session: &Arc<Session>,
turn: &Arc<TurnContext>,
context: impl Into<GuardianReviewContext>,
review_id: String,
request: GuardianApprovalRequest,
retry_reason: Option<String>,
@@ -675,7 +677,7 @@ pub(crate) async fn review_approval_request_with_cancel(
) -> ReviewDecision {
run_guardian_review(
Arc::clone(session),
Arc::clone(turn),
context.into(),
review_id,
request,
ApprovalRequestReasons {
@@ -689,12 +691,13 @@ pub(crate) async fn review_approval_request_with_cancel(
pub(crate) fn spawn_approval_request_review(
session: Arc<Session>,
turn: Arc<TurnContext>,
context: impl Into<GuardianReviewContext>,
review_id: String,
request: GuardianApprovalRequest,
retry_reason: Option<String>,
options: GuardianReviewOptions,
) -> oneshot::Receiver<ReviewDecision> {
let context = context.into();
let (tx, rx) = oneshot::channel();
let spawn_result = std::thread::Builder::new()
.name("codex-approval-review".to_string())
@@ -710,7 +713,7 @@ pub(crate) fn spawn_approval_request_review(
};
let decision = runtime.block_on(review_approval_request_with_cancel(
&session,
&turn,
context,
review_id,
request,
retry_reason,
@@ -842,13 +845,14 @@ pub(super) async fn guardian_review_session_config(
/// rules.
async fn run_guardian_review_session_before_deadline(
session: Arc<Session>,
turn: Arc<TurnContext>,
context: GuardianReviewContext,
request: GuardianApprovalRequest,
reasons: ApprovalRequestReasons,
schema: serde_json::Value,
external_cancel: Option<CancellationToken>,
deadline: Instant,
) -> (GuardianReviewOutcome, GuardianReviewAnalyticsResult) {
let turn = context.turn();
let session_config = match guardian_review_session_config(session.as_ref(), turn.as_ref()).await
{
Ok(session_config) => session_config,
@@ -864,7 +868,7 @@ async fn run_guardian_review_session_before_deadline(
.guardian_review_session
.run_review(GuardianReviewSessionParams {
parent_session: Arc::clone(&session),
parent_turn: turn.clone(),
parent_context: context.clone(),
spawn_config: session_config.spawn_config,
request,
reasons,
@@ -936,20 +940,21 @@ async fn run_guardian_review_session_before_deadline(
pub(super) async fn run_guardian_review_session_with_retry(
session: Arc<Session>,
turn: Arc<TurnContext>,
context: impl Into<GuardianReviewContext>,
request: GuardianApprovalRequest,
reasons: ApprovalRequestReasons,
schema: serde_json::Value,
external_cancel: Option<CancellationToken>,
max_attempts: i64,
) -> (GuardianReviewOutcome, GuardianReviewAnalyticsResult) {
let context = context.into();
assert!(max_attempts > 0, "guardian review must run at least once");
let deadline = Instant::now() + GUARDIAN_REVIEW_TIMEOUT;
let mut attempt_count = 1;
loop {
let (outcome, mut analytics_result) = run_guardian_review_session_before_deadline(
Arc::clone(&session),
Arc::clone(&turn),
context.clone(),
request.clone(),
reasons.clone(),
schema.clone(),
+19 -14
View File
@@ -56,6 +56,7 @@ use codex_utils_path_uri::PathUri;
use super::ApprovalRequestReasons;
use super::GUARDIAN_REVIEWER_NAME;
use super::GuardianApprovalRequest;
use super::GuardianReviewContext;
use super::prompt::BUNDLED_GUARDIAN_POLICY;
use super::prompt::BUNDLED_GUARDIAN_POLICY_TEMPLATE;
use super::prompt::GuardianPromptMode;
@@ -79,7 +80,7 @@ pub(crate) enum GuardianReviewSessionOutcome {
pub(crate) struct GuardianReviewSessionParams {
pub(crate) parent_session: Arc<Session>,
pub(crate) parent_turn: Arc<TurnContext>,
pub(crate) parent_context: GuardianReviewContext,
pub(crate) spawn_config: Config,
pub(crate) request: GuardianApprovalRequest,
pub(crate) reasons: ApprovalRequestReasons,
@@ -358,7 +359,7 @@ impl GuardianReviewSessionManager {
let spawn_cancel_guard = spawn_cancel_token.clone().drop_guard();
let review_session = spawn_guardian_review_session(
&parent_session,
&parent_turn,
&GuardianReviewContext::from(parent_turn),
spawn_config,
reuse_key,
spawn_cancel_token.clone(),
@@ -459,7 +460,7 @@ impl GuardianReviewSessionManager {
&spawn_cancel_token,
Box::pin(spawn_guardian_review_session(
&params.parent_session,
&params.parent_turn,
&params.parent_context,
params.spawn_config.clone(),
next_reuse_key.clone(),
spawn_cancel_token.clone(),
@@ -678,7 +679,7 @@ impl GuardianReviewSessionManager {
&spawn_cancel_token,
Box::pin(spawn_guardian_review_session(
&params.parent_session,
&params.parent_turn,
&params.parent_context,
fork_config,
reuse_key,
spawn_cancel_token.clone(),
@@ -721,7 +722,7 @@ impl GuardianReviewSessionManager {
async fn spawn_guardian_review_session(
parent_session: &Arc<Session>,
parent_turn: &Arc<TurnContext>,
parent_context: &GuardianReviewContext,
spawn_config: Config,
reuse_key: GuardianReviewSessionReuseKey,
cancel_token: CancellationToken,
@@ -746,7 +747,8 @@ async fn spawn_guardian_review_session(
parent_session.services.auth_manager.clone(),
parent_session.services.models_manager.clone(),
Arc::clone(parent_session),
Arc::clone(parent_turn),
Arc::clone(parent_context.turn()),
parent_context.environments().clone(),
cancel_token.clone(),
SubAgentSource::Other(GUARDIAN_REVIEWER_NAME.to_string()),
initial_history,
@@ -836,7 +838,7 @@ async fn run_review_on_session(
build_guardian_prompt_items_with_parent_turn(
params.parent_session.as_ref(),
Some(params.parent_turn.as_ref()),
Some(&params.parent_context),
params.reasons.clone(),
params.request.clone(),
prompt_mode,
@@ -867,15 +869,15 @@ async fn run_review_on_session(
.await
.unwrap_or_default();
let guardian_permission_profile = PermissionProfile::read_only();
let parent_turn_environments = params.parent_turn.environments.to_selections();
let parent_turn_environments = params.parent_context.environments().to_selections();
// TODO(anp): Migrate guardian review thread settings to a PathUri fallback cwd so foreign
// parent environments do not fall back to the host-native config cwd.
let parent_turn_legacy_fallback_cwd = params
.parent_turn
.environments
.parent_context
.environments()
.primary()
.and_then(|environment| environment.cwd().to_abs_path().ok())
.unwrap_or_else(|| params.parent_turn.config.cwd.clone());
.unwrap_or_else(|| params.parent_context.turn().config.cwd.clone());
let submission = review_session.io.submit_with_trace(
Op::UserInput {
@@ -905,7 +907,7 @@ async fn run_review_on_session(
},
},
/*trace*/ None,
Some(params.parent_turn.sub_id.clone()),
Some(params.parent_context.turn().sub_id.clone()),
);
let submit_result = run_before_review_deadline(
deadline,
@@ -1308,7 +1310,7 @@ mod tests {
GuardianReviewSessionParams {
parent_session: Arc::new(session),
parent_turn: Arc::new(turn),
parent_context: GuardianReviewContext::from(Arc::new(turn)),
spawn_config,
request: GuardianApprovalRequest::Shell {
id: "shell-1".to_string(),
@@ -1338,7 +1340,10 @@ mod tests {
let params = test_review_params().await;
let manager = GuardianReviewSessionManager::default();
manager
.initialize(params.parent_session, params.parent_turn)
.initialize(
params.parent_session,
Arc::clone(params.parent_context.turn()),
)
.await
.expect("initialize Guardian session");
let mode = manager
+6 -3
View File
@@ -487,10 +487,11 @@ async fn build_guardian_prompt_full_mode_preserves_initial_review_format() -> an
async fn build_guardian_prompt_prefers_retry_reason_over_approval_reason() -> anyhow::Result<()> {
let (session, turn) = guardian_test_session_and_turn_with_base_url("http://localhost").await;
seed_guardian_parent_history(&session, &turn).await;
let context = GuardianReviewContext::from(&turn);
let prompt = build_guardian_prompt_items_with_parent_turn(
session.as_ref(),
Some(turn.as_ref()),
Some(&context),
ApprovalRequestReasons {
approval: Some("A policy rule requires approval.".to_string()),
retry: Some("The sandbox blocked the initial command.".to_string()),
@@ -518,6 +519,7 @@ async fn build_guardian_prompt_prefers_retry_reason_over_approval_reason() -> an
async fn build_guardian_prompt_truncates_oversized_approval_reason() -> anyhow::Result<()> {
let (session, turn) = guardian_test_session_and_turn_with_base_url("http://localhost").await;
seed_guardian_parent_history(&session, &turn).await;
let context = GuardianReviewContext::from(&turn);
let approval_reason = format!("policy-start {} policy-end", "x".repeat(10_000));
let expected_reason = codex_utils_output_truncation::truncate_text(
&approval_reason,
@@ -526,7 +528,7 @@ async fn build_guardian_prompt_truncates_oversized_approval_reason() -> anyhow::
let prompt = build_guardian_prompt_items_with_parent_turn(
session.as_ref(),
Some(turn.as_ref()),
Some(&context),
ApprovalRequestReasons {
approval: Some(approval_reason),
retry: None,
@@ -618,10 +620,11 @@ async fn build_guardian_prompt_includes_parent_turn_denied_reads() -> anyhow::Re
let session = Arc::new(session);
let turn = Arc::new(turn);
seed_guardian_parent_history(&session, &turn).await;
let context = GuardianReviewContext::from(&turn);
let prompt = build_guardian_prompt_items_with_parent_turn(
session.as_ref(),
Some(turn.as_ref()),
Some(&context),
ApprovalRequestReasons {
approval: None,
retry: Some("Sandbox denied reading /repo/private/secret.txt.".to_string()),