Files
codex/codex-rs/guardian-context/src/entry.rs
T
Ankush Gupta 0637230e89 Include enclosing tool context in nested Guardian approvals (#61946)
## Why

A nested MCP approval can arrive while its enclosing tool invocation is still running. Follow-up Guardian reviews may use a transcript delta that no longer includes that invocation, leaving out the context in which the nested action was requested.

## What changed

- Add the disabled-by-default `guardian_nested_approval_context` feature to include the host-verified enclosing tool name and arguments in synchronous nested approval requests, while preserving the nested action as the action under review.
- Match the enclosing invocation by call ID and omit ambiguous or unavailable evidence. Exclude Node REPL JavaScript preflight requests.
- Admit enclosing-call context only when it fits the remaining fixed or elastic budget, without displacing ordinary transcript evidence or screenshots.

## Testing

Add MCP elicitation coverage and a request-history snapshot for independent nested reviews and transcript deltas. Add tests for call-ID matching, budget-based omission, and screenshot priority.

GitOrigin-RevId: 9c44a0e8f29f84f84a5322b8362f910f2c91ac55
2026-11-17 02:31:45 +00:00

99 lines
4.0 KiB
Rust

//! Structured transcript evidence shared by synchronous and asynchronous Guardian.
//!
//! Entry kinds preserve source attribution for consumer-specific retention and
//! rendering. Both consumers keep originals until request preparation applies caps.
//! Original sizes remain available for accounting.
/// Semantic role of one parent-conversation transcript entry.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum ConversationTranscriptEntryKind {
/// Actual parent-thread user message.
User,
/// Explicit developer message preserving a user-approved action.
Developer,
/// Assistant commentary or an inter-agent message.
Assistant,
/// Final assistant answer eligible for stronger async retention.
ProtectedAssistant,
/// Named tool invocation, including shell and web-search calls.
ToolCall(String),
/// The textual tool call verified by the host to enclose the current approval.
EnclosingToolCall(String),
/// Tool result with a call-derived, explicit, or generic fallback label.
ToolOutput(String),
/// Whole Code Mode exec output selected by its host-recorded nested tool calls.
SelectedExecOutput,
/// Result from a Node REPL-backed tool that may receive a larger sync cap.
NodeReplToolOutput(String),
/// Plaintext model reasoning that the async consumer explicitly enables.
Reasoning,
}
impl ConversationTranscriptEntryKind {
/// Returns the role label currently used in Guardian transcript prompts.
pub fn role(&self) -> &str {
match self {
Self::User => "user",
Self::Developer => "developer",
Self::Assistant | Self::ProtectedAssistant => "assistant",
Self::ToolCall(role)
| Self::EnclosingToolCall(role)
| Self::ToolOutput(role)
| Self::NodeReplToolOutput(role) => role.as_str(),
Self::SelectedExecOutput => "tool exec result",
Self::Reasoning => "reasoning",
}
}
}
/// Collected text, a host-attributed record, or an opaque backend-native message.
#[derive(Clone, PartialEq)]
pub enum TranscriptContent {
Text(String),
/// Original scheduler input, compressed only during request preparation.
ScheduledMessage(ScheduledTranscriptMessage),
/// Host-attributed text prepared by the profile, rendered at delivery.
Record(crate::TranscriptRecord),
NativeMessage(Box<codex_protocol::models::ResponseItem>),
}
impl std::fmt::Debug for TranscriptContent {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(match self {
Self::Text(_) => "Text(..)",
Self::ScheduledMessage(_) => "ScheduledMessage(..)",
Self::Record(_) => "Record(..)",
Self::NativeMessage(_) => "NativeMessage(..)",
})
}
}
/// Structured evidence shared by sync Guardian and async scoring.
#[derive(Clone, Debug, PartialEq)]
pub struct ConversationTranscriptEntry {
/// Semantic role used for consumer-specific retention and truncation.
pub kind: ConversationTranscriptEntryKind,
/// Original captured evidence, or content bounded during preparation.
pub content: TranscriptContent,
/// Size before truncation, retained for omission and truncation accounting.
pub original_bytes: usize,
/// Original source revision and display order, established from host metadata.
pub retained_source: Option<RetainedTranscriptSource>,
}
/// Display ordering is separate from source identity and cannot establish delivery.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RetainedTranscriptSource {
/// Size of the complete role- and order-labeled source, before request admission.
pub rendered_bytes: usize,
pub order: String,
pub source: codex_history::RetainedSource,
}
/// Original scheduler text and the provenance needed to compare heartbeat instructions.
#[derive(Clone, PartialEq)]
pub struct ScheduledTranscriptMessage {
pub(crate) text: String,
pub(crate) heartbeat: Option<crate::preparation::HeartbeatInstruction>,
}