Route approvals through the extension decision API (#43432)

## What changed

- Let approval extensions choose between cached approval, synchronous review, and a user prompt for tool and permission requests, while core enforces mandatory Guardian and fresh-review requirements.
- Carry an optional `review_reason` on Guardian assessment events and use it to trigger strict-review notifications, retaining the fallback for older events.
- Require synchronous review when cached evidence has an unusable encrypted parent compaction.

## Testing

Add regression coverage for manual prompts and cached approvals with non-UTF-8 working directories. Update approval contributors in existing tests to use the decision API.

GitOrigin-RevId: a4e66416070bdaa881daa41429c49021629f44c1
This commit is contained in:
jif authored and copyberry committed 2026-09-07 11:07:28 +00:00
1 parent 0df39752cb
commit e1eb98461c
24 files changed
+605 -250

No files matched your search

+33
View File
@@ -0,0 +1,33 @@
//! Supplies action categories to the review extension and enforces host-owned requirements.
use super::GuardianApprovalRequest;
use crate::tools::sandboxing::ApprovalAction;
use codex_protocol::openai_models::GuardianScope;
impl GuardianApprovalRequest {
pub(crate) fn guardian_scope(&self) -> GuardianScope {
match self {
Self::ExecCommand { .. } | Self::WriteStdin { .. } => GuardianScope::Shell,
#[cfg(unix)]
Self::Execve { .. } => GuardianScope::Shell,
Self::ApplyPatch { .. } => GuardianScope::FileChanges,
Self::McpToolCall { server, .. } => GuardianScope::for_mcp_server(server),
Self::NetworkAccess { .. } => GuardianScope::Network,
Self::RequestPermissions { .. } => GuardianScope::Permissions,
}
}
}
impl ApprovalAction {
pub(crate) fn guardian_scope(&self) -> GuardianScope {
match self {
Self::ExecCommand { .. } | Self::WriteStdin { .. } => GuardianScope::Shell,
#[cfg(unix)]
Self::Execve { .. } => GuardianScope::Shell,
Self::ApplyPatch { .. } => GuardianScope::FileChanges,
Self::McpToolCall { server, .. } => GuardianScope::for_mcp_server(server),
Self::NetworkAccess { .. } => GuardianScope::Network,
Self::RequestPermissions { .. } => GuardianScope::Permissions,
}
}
}
+184
View File
@@ -0,0 +1,184 @@
//! Calls the decision extension for each approval and enforces host constraints.
//! The synchronous service captures one action; no outcome is stored by tool-call ID.
use codex_async_utils::THREAD_STACK_SIZE_BYTES;
use codex_extension_api::ApprovalDecision;
use codex_extension_api::ApprovalDecisionInput;
use codex_extension_api::SynchronousApprovalReviewer;
use codex_protocol::approvals::GuardianReviewReason;
use codex_protocol::protocol::ReviewDecision;
use std::sync::Arc;
use tokio::sync::oneshot;
use tokio_util::sync::CancellationToken;
use super::ApprovalRequestReasons;
use super::GuardianApprovalRequest;
use super::GuardianReviewContext;
use super::GuardianReviewOptions;
use super::review::record_guardian_non_denial;
use super::runtime::ReviewAction;
use super::runtime::ReviewRuntime;
use crate::session::session::Session;
pub(crate) fn spawn_approval_decision(
session: Arc<Session>,
context: impl Into<GuardianReviewContext>,
review_id: String,
request: impl Into<super::ReviewAction>,
reasons: ApprovalRequestReasons,
options: GuardianReviewOptions,
) -> oneshot::Receiver<Option<ReviewDecision>> {
let context: GuardianReviewContext = context.into();
let request: ReviewAction = request.into();
let (tx, rx) = oneshot::channel();
let runtime = session.services.runtime_handle.clone();
let spawn_result = std::thread::Builder::new()
.name("codex-approval-review".to_string())
.stack_size(THREAD_STACK_SIZE_BYTES)
.spawn(move || {
let decision = runtime.block_on(decide_approval(
session, context, review_id, request, reasons, options,
));
let _ = tx.send(decision);
});
if let Err(err) = spawn_result {
tracing::error!(%err, "failed to spawn automatic approval review worker");
}
rx
}
/// `None` requests the existing user flow. No contributor is never an implicit allow.
pub(crate) async fn decide_approval(
session: Arc<Session>,
context: impl Into<GuardianReviewContext>,
review_id: String,
request: impl Into<ReviewAction>,
reasons: ApprovalRequestReasons,
options: GuardianReviewOptions,
) -> Option<ReviewDecision> {
let context = context.into();
let request = request.into();
let turn = context.turn();
let requirements = turn.config.config_layer_stack.requirements();
let model_requires_review =
requirements.auto_review_required_for_model(&turn.model_info().slug);
let require_guardian = options.require_guardian
|| model_requires_review
|| requirements
.approvals_reviewer
.can_set(&codex_protocol::config_types::ApprovalsReviewer::User)
.is_err();
let require_fresh_review = options.require_synchronous_review
|| model_requires_review
&& !turn
.config
.features
.enabled(codex_features::Feature::GuardianV2)
|| options
.external_cancel
.as_ref()
.is_some_and(CancellationToken::is_cancelled)
|| reasons.retry.is_some()
|| request.request.as_ref().is_ok_and(|request| {
super::approval_request::format_guardian_action_compact(request).is_err()
})
|| matches!(&request.request, Ok(GuardianApprovalRequest::ExecCommand { sandbox_permissions, .. })
if sandbox_permissions.requires_escalated_permissions());
let full_access = context.environments().has_full_access(
context.approval_policy,
&turn.config.permissions.effective_permission_profile(),
);
if full_access {
return Some(if let Err(decision) = request.validate(&context) {
decision
} else if options
.external_cancel
.as_ref()
.is_some_and(CancellationToken::is_cancelled)
{
ReviewDecision::Abort
} else {
ReviewDecision::Approved
});
}
let action = match &request.action {
Ok(action) => action,
Err(_) => {
return Some(ReviewDecision::denied(
"automatic approval review could not prepare the action",
));
}
};
let runtime = ReviewRuntime {
session: Arc::clone(&session),
context: context.clone(),
review_id: review_id.clone(),
request: request.clone(),
reasons,
options,
};
let input = ApprovalDecisionInput {
approval_id: &review_id,
action,
thread_id: session.thread_id,
thread_store: &session.services.thread_extension_data,
category: request.category,
approval_policy: context.approval_policy,
approvals_reviewer: context.approvals_reviewer,
require_guardian,
require_fresh_review,
full_access,
metrics: Some(crate::session::extension_metrics::from_session_telemetry(
turn.session_telemetry.clone(),
)),
synchronous_reviewer: &runtime,
};
match session.services.extensions.decide_approval(&input).await {
Some(ApprovalDecision::Reviewed(decision)) => Some(decision),
Some(ApprovalDecision::Allow) if !require_fresh_review => {
let request = match request.validate(&context) {
Ok(request) => request,
Err(decision) => return Some(decision),
};
let turn_id = super::approval_request::guardian_request_turn_id(request, &turn.sub_id);
if session
.services
.thread_extension_data
.get::<codex_extension_api::GuardianV2Enabled>()
.is_some()
{
session
.services
.analytics_events_client
.track_guardian_v2_event(codex_analytics::GuardianV2Event {
thread_id: session.thread_id.to_string(),
turn_id: turn_id.to_owned(),
item_id: super::approval_request::guardian_request_target_item_id(request)
.map(str::to_owned),
model: Some(turn.model_info().slug.clone()),
occurred_at_ms: codex_analytics::now_unix_millis(),
kind: codex_analytics::GuardianV2EventKind::FastDecision {
decision: "approved",
},
});
}
record_guardian_non_denial(&session, turn_id).await;
Some(ReviewDecision::Approved)
}
Some(ApprovalDecision::Allow) => {
Some(runtime.review(GuardianReviewReason::FreshRequired).await)
}
Some(ApprovalDecision::AskUser) if !require_guardian => None,
None if !require_guardian
&& !super::review::routes_approval_policy_to_guardian(
context.approval_policy,
context.approvals_reviewer,
) =>
{
None
}
None | Some(ApprovalDecision::AskUser) => {
Some(runtime.review(GuardianReviewReason::Policy).await)
}
}
}
+10 -17
View File
@@ -1,18 +1,10 @@
//! Guardian review decides whether an `on-request` approval should be granted
//! automatically instead of shown to the user.
//! Full Access (`never` approvals with a disabled sandbox) approves without review.
//!
//! High-level approach:
//! 1. Reconstruct a compact transcript that preserves user intent plus the most
//! relevant recent assistant and tool context.
//! 2. Ask a dedicated guardian review session to assess the exact planned
//! action and return strict JSON.
//! The guardian clones the parent config, so it inherits any managed
//! network proxy / allowlist that the parent turn already had.
//! 3. Fail closed on timeout, execution failure, or malformed output.
//! 4. Apply the guardian's explicit allow/deny outcome.
//! Hosts approval decisions and the isolated synchronous reviewer.
//! The extension chooses policy and evidence; core enforces permissions and mandatory
//! review requirements. Each approval retains its issuing context and cancellation.
mod approval_request;
mod coverage;
mod decision;
mod feedback;
mod metrics;
mod prompt;
@@ -43,6 +35,8 @@ pub(crate) use approval_request::GuardianMcpAnnotations;
pub(crate) use approval_request::GuardianNetworkAccessTrigger;
#[cfg(test)]
pub(crate) use approval_request::guardian_approval_request_to_json;
pub(crate) use decision::decide_approval;
pub(crate) use decision::spawn_approval_decision;
pub(crate) use prompt::BUNDLED_GUARDIAN_POLICY;
pub(crate) use prompt::BUNDLED_GUARDIAN_POLICY_TEMPLATE;
pub(crate) use prompt::guardian_truncate_text;
@@ -52,13 +46,14 @@ pub(crate) use review::is_basic_session_source;
pub(crate) use review::new_guardian_review_id;
#[cfg(test)]
pub(crate) use review::record_guardian_denial_for_test;
#[cfg(test)]
pub(crate) use review::review_approval_request;
pub(crate) use review::review_approval_request_with_cancel;
pub(crate) use review::routes_approval_policy_to_guardian;
pub(crate) use review::routes_approval_to_guardian;
pub(crate) use review::spawn_approval_request_review;
pub(crate) use review_session::GuardianReviewSessionManager;
pub(crate) use review_session::prompt_cache_key_override_for_review_session;
pub(crate) use runtime::ReviewAction;
pub(crate) const GUARDIAN_REVIEW_TIMEOUT: Duration = Duration::from_secs(90);
pub(crate) const GUARDIAN_REVIEWER_NAME: &str = "guardian";
@@ -83,9 +78,7 @@ const GUARDIAN_RECENT_ENTRY_LIMIT: usize = 40;
/// Background network approvals and Unix interception use the active task's resolved settings.
/// Startup reviewer prewarming intentionally uses turn-only inputs because it has no issuing step.
///
/// MCP elicitation reviews still use turn-only inputs.
/// 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)
/// MCP elicitation reviews continue to use turn-only inputs.
#[derive(Clone)]
pub(crate) struct GuardianReviewContext {
/// The response currently handled in this execution context.
+19 -36
View File
@@ -7,7 +7,6 @@ use codex_analytics::GuardianReviewTrackContext;
use codex_analytics::GuardianReviewedAction;
use codex_analytics::GuardianV2Event;
use codex_analytics::GuardianV2EventKind;
use codex_async_utils::THREAD_STACK_SIZE_BYTES;
use codex_core_plugins::PluginCommandAttribution;
use codex_extension_api::GuardianV2Enabled;
use codex_extension_api::ThreadIdleCause;
@@ -29,10 +28,10 @@ use codex_protocol::protocol::SessionSource;
use codex_protocol::protocol::SubAgentSource;
use codex_protocol::protocol::TurnAbortReason;
use codex_protocol::protocol::WarningEvent;
#[cfg(test)]
use futures::future::BoxFuture;
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::oneshot;
use tokio::time::Instant;
use tokio::time::sleep_until;
use tokio_util::sync::CancellationToken;
@@ -268,7 +267,7 @@ fn track_guardian_review(
.track_guardian_review(tracking, result, completed_at_ms);
}
async fn record_guardian_non_denial(session: &Arc<Session>, turn_id: &str) {
pub(super) async fn record_guardian_non_denial(session: &Arc<Session>, turn_id: &str) {
session
.services
.guardian_rejection_circuit_breaker
@@ -432,21 +431,17 @@ async fn run_guardian_review(
session,
context,
review_id,
request,
request: request.into(),
reasons,
options,
};
codex_extension_api::SynchronousApprovalReviewer::review(
&runtime,
codex_protocol::approvals::GuardianReviewReason::Policy,
)
.await
run_synchronous_review(runtime, /*review_reason*/ None).await
}
/// Runs the existing synchronous reviewer without choosing policy or reusing a score.
pub(super) async fn run_synchronous_review(
runtime: super::runtime::ReviewRuntime,
_review_reason: codex_protocol::approvals::GuardianReviewReason,
review_reason: Option<codex_protocol::approvals::GuardianReviewReason>,
) -> ReviewDecision {
let super::runtime::ReviewRuntime {
session,
@@ -456,12 +451,17 @@ pub(super) async fn run_synchronous_review(
reasons,
options,
} = runtime;
let request = match request.validate(&context) {
Ok(request) => request.clone(),
Err(decision) => return decision,
};
let turn = Arc::clone(context.turn());
let GuardianReviewOptions {
plugin_attribution_override,
approval_request_source,
external_cancel,
require_synchronous_review: _,
require_guardian: _,
} = options;
// Bound executor attribution and the Guardian session with one review deadline.
let deadline = Instant::now() + GUARDIAN_REVIEW_TIMEOUT;
@@ -518,6 +518,7 @@ pub(super) async fn run_synchronous_review(
.send_event(
turn.as_ref(),
EventMsg::GuardianAssessment(GuardianAssessmentEvent {
review_reason,
id: review_id.clone(),
target_item_id: target_item_id.clone(),
plugin_id: plugin_id.clone(),
@@ -557,6 +558,7 @@ pub(super) async fn run_synchronous_review(
.send_event(
turn.as_ref(),
EventMsg::GuardianAssessment(GuardianAssessmentEvent {
review_reason,
id: review_id,
target_item_id,
plugin_id: plugin_id.clone(),
@@ -696,6 +698,7 @@ pub(super) async fn run_synchronous_review(
.send_event(
turn.as_ref(),
EventMsg::GuardianAssessment(GuardianAssessmentEvent {
review_reason,
id: review_id,
target_item_id,
plugin_id: plugin_id.clone(),
@@ -733,6 +736,7 @@ pub(super) async fn run_synchronous_review(
.send_event(
turn.as_ref(),
EventMsg::GuardianAssessment(GuardianAssessmentEvent {
review_reason,
id: review_id,
target_item_id,
plugin_id: plugin_id.clone(),
@@ -818,6 +822,7 @@ pub(super) async fn run_synchronous_review(
GuardianAssessmentStatus::Denied
};
let assessment_event = GuardianAssessmentEvent {
review_reason,
id: review_id,
target_item_id,
plugin_id: plugin_id.clone(),
@@ -879,6 +884,8 @@ pub(super) async fn run_synchronous_review(
#[derive(Clone)]
pub(crate) struct GuardianReviewOptions {
/// Requires Guardian rather than a manual approval; cached evidence may still satisfy it.
pub(crate) require_guardian: bool,
pub(crate) plugin_attribution_override: Option<PluginCommandAttribution>,
pub(crate) approval_request_source: GuardianApprovalRequestSource,
pub(crate) external_cancel: Option<CancellationToken>,
@@ -887,6 +894,7 @@ pub(crate) struct GuardianReviewOptions {
}
/// Public entrypoint for approval requests that should be reviewed by guardian.
#[cfg(test)]
pub(crate) async fn review_approval_request(
session: &Arc<Session>,
context: impl Into<GuardianReviewContext>,
@@ -902,6 +910,7 @@ pub(crate) async fn review_approval_request(
request,
reasons,
GuardianReviewOptions {
require_guardian: false,
plugin_attribution_override: None,
approval_request_source: GuardianApprovalRequestSource::MainTurn,
external_cancel: None,
@@ -933,32 +942,6 @@ pub(crate) async fn review_approval_request_with_cancel(
.await
}
pub(crate) fn spawn_approval_request_review(
session: Arc<Session>,
context: impl Into<GuardianReviewContext>,
review_id: String,
request: GuardianApprovalRequest,
reasons: ApprovalRequestReasons,
options: GuardianReviewOptions,
) -> oneshot::Receiver<ReviewDecision> {
let context = context.into();
let (tx, rx) = oneshot::channel();
let runtime = session.services.runtime_handle.clone();
let spawn_result = std::thread::Builder::new()
.name("codex-approval-review".to_string())
.stack_size(THREAD_STACK_SIZE_BYTES)
.spawn(move || {
let decision = runtime.block_on(run_guardian_review(
session, context, review_id, request, reasons, options,
));
let _ = tx.send(decision);
});
if let Err(err) = spawn_result {
tracing::error!(%err, "failed to spawn automatic approval review worker");
}
rx
}
pub(super) struct GuardianReviewSessionConfig {
pub(super) spawn_config: crate::config::Config,
pub(super) node_repl_policy: GuardianNodeReplPolicy,
+65 -3
View File
@@ -1,4 +1,4 @@
//! Binds the existing synchronous reviewer to one captured approval action.
//! Binds the existing synchronous reviewer to one approval action.
use codex_extension_api::ExtensionFuture;
use codex_extension_api::SynchronousApprovalReviewer;
@@ -9,15 +9,77 @@ use super::ApprovalRequestReasons;
use super::GuardianApprovalRequest;
use super::GuardianReviewContext;
use super::GuardianReviewOptions;
use super::approval_request::guardian_approval_request_to_json;
use super::review::run_synchronous_review;
use crate::session::session::Session;
/// Carries the original action even when the legacy synchronous renderer cannot handle its paths.
/// This lets the extension return AskUser before invoking that renderer.
#[derive(Clone)]
pub(crate) struct ReviewAction {
pub(super) action: Result<serde_json::Value, String>,
pub(super) category: codex_protocol::openai_models::GuardianScope,
pub(super) request: Result<GuardianApprovalRequest, String>,
}
impl From<GuardianApprovalRequest> for ReviewAction {
fn from(request: GuardianApprovalRequest) -> Self {
Self {
action: guardian_approval_request_to_json(&request).map_err(|error| error.to_string()),
category: request.guardian_scope(),
request: Ok(request),
}
}
}
impl ReviewAction {
pub(crate) fn from_approval_action(
action: crate::tools::sandboxing::ApprovalAction,
exec_command_cwd_convention: Option<codex_utils_path_uri::PathConvention>,
) -> Self {
let category = action.guardian_scope();
let original = serde_json::to_value(&action).map_err(|error| error.to_string());
match action.into_guardian_request(exec_command_cwd_convention) {
Ok(request) => Self::from(request),
Err(error) => Self {
action: original,
category,
request: Err(error.to_string()),
},
}
}
}
impl ReviewAction {
/// Preserve the checks previously made before entering Guardian from tool approvals.
pub(super) fn validate(
&self,
context: &GuardianReviewContext,
) -> Result<&GuardianApprovalRequest, ReviewDecision> {
let request = self.request.as_ref().map_err(|error| {
tracing::error!(%error, "failed to build automatic approval action");
ReviewDecision::denied("automatic approval review could not prepare the action")
})?;
if let GuardianApprovalRequest::WriteStdin { environment_id, .. } = request
&& !context
.environments()
.turn_environments()
.any(|environment| environment.selection.environment_id == *environment_id)
{
return Err(ReviewDecision::denied(
"automatic approval review cannot access the terminal's environment; select it before retrying",
));
}
Ok(request)
}
}
#[derive(Clone)]
pub(super) struct ReviewRuntime {
pub(super) session: Arc<Session>,
pub(super) context: GuardianReviewContext,
pub(super) review_id: String,
pub(super) request: GuardianApprovalRequest,
pub(super) request: ReviewAction,
pub(super) reasons: ApprovalRequestReasons,
pub(super) options: GuardianReviewOptions,
}
@@ -27,6 +89,6 @@ impl SynchronousApprovalReviewer for ReviewRuntime {
&self,
reason: codex_protocol::approvals::GuardianReviewReason,
) -> ExtensionFuture<'_, ReviewDecision> {
Box::pin(run_synchronous_review(self.clone(), reason))
Box::pin(run_synchronous_review(self.clone(), Some(reason)))
}
}
+1
View File
@@ -1696,6 +1696,7 @@ async fn cancelled_guardian_review_emits_terminal_abort_without_warning() {
},
/*retry_reason*/ None,
GuardianReviewOptions {
require_guardian: false,
plugin_attribution_override: None,
approval_request_source: GuardianApprovalRequestSource::MainTurn,
external_cancel: Some(cancel_token),