Allow model catalogs to customize approval instruction headings (#57581)

## What changed

Add optional `request_permissions` and `auto_review_suffix` fields to catalog approval messages. Use them to customize the permission tool heading and introduce automatic review guidance while preserving the bundled instruction bodies and existing policy gates. Accept `request_permissions_tool` as a deserialization alias.

Limit headings to 500 UTF-8 bytes on a single line and fall back to bundled text for missing or invalid values. Complete catalog approval messages retain precedence.

## Testing

Add coverage for heading validation, serialization aliases, policy gates, fallback behavior, and complete-message precedence. Integration tests verify that model switches append the selected model's headings without rewriting history or repeating unchanged instructions.

GitOrigin-RevId: 3311591a464cc086783fe25271a352dd5a229790
This commit is contained in:
goodman-oai
2026-10-27 22:26:12 +00:00
committed by copyberry
parent e343a12d5c
commit 133c11db43
17 changed files with 658 additions and 23 deletions
@@ -26,6 +26,7 @@ pub(crate) const DENIED_READS_TEMPLATE: &str = "## Denied filesystem reads\n{{ d
/// Resolved approval-policy text; policy and tool selection remain with the consumer.
#[derive(Debug, Clone, Copy)]
pub(crate) struct ResolvedApprovalMessages<'a> {
pub(crate) catalog: Option<&'a ApprovalMessages>,
pub(crate) never: ResolvedMessage<'a>,
pub(crate) on_request: ResolvedMessage<'a>,
pub(crate) on_request_auto_review: ResolvedMessage<'a>,
@@ -35,6 +36,7 @@ pub(crate) struct ResolvedApprovalMessages<'a> {
impl<'a> ResolvedApprovalMessages<'a> {
pub(crate) fn new(messages: Option<&'a ApprovalMessages>) -> Self {
Self {
catalog: messages,
never: ResolvedMessage::new(
messages.and_then(|m| m.never.as_deref()),
APPROVAL_POLICY_NEVER,
@@ -10,6 +10,7 @@ use crate::model_messages::permissions::READ_ONLY_TEMPLATE;
use crate::model_messages::permissions::ResolvedApprovalMessages;
use crate::model_messages::permissions::ResolvedPermissionMessages;
use crate::model_messages::permissions::WORKSPACE_WRITE_TEMPLATE;
use approval_instructions::ApprovalInstructions;
use codex_context_fragments::ContextualUserFragment;
use codex_execpolicy::Policy;
use codex_protocol::config_types::ApprovalsReviewer;
@@ -32,6 +33,7 @@ use std::path::Path;
use std::sync::LazyLock;
use writable_roots::writable_roots_text;
mod approval_instructions;
mod path_warnings;
mod writable_roots;
@@ -332,30 +334,31 @@ fn approval_text(
}
ResolvedMessage::Bundled(text) => text,
};
let instructions = ApprovalInstructions::new(approval_context);
let text = match approval_policy {
AskForApproval::Never => return base.to_string(),
AskForApproval::UnlessTrusted => {
if request_permissions_tool_enabled {
format!("{base}\n\n{REQUEST_PERMISSIONS_TOOL}")
format!("{base}\n\n{}", instructions.tool())
} else {
base.to_string()
}
}
AskForApproval::OnRequest => {
let rule = if exec_permission_approvals_enabled {
REQUEST_PERMISSION_RULE
let mut sections = vec![if exec_permission_approvals_enabled {
REQUEST_PERMISSION_RULE.to_string()
} else {
base
};
let mut sections = vec![rule.to_string()];
base.to_string()
}];
if request_permissions_tool_enabled {
sections.push(REQUEST_PERMISSIONS_TOOL.to_string());
sections.push(instructions.tool());
}
sections.extend(render_prefixes());
sections.join("\n\n")
}
AskForApproval::Granular(granular_config) => granular_instructions(
granular_config,
approval_context,
render_prefixes(),
exec_permission_approvals_enabled,
request_permissions_tool_enabled,
@@ -363,7 +366,7 @@ fn approval_text(
};
if approval_context.reviewer == ApprovalsReviewer::AutoReview {
format!("{text}\n\n{AUTO_REVIEW_SUFFIX}")
format!("{text}\n\n{}", instructions.auto_review())
} else {
text
}
@@ -398,10 +401,12 @@ fn approved_command_prefixes_text(prefixes: &[Vec<String>], template: &str) -> O
fn granular_instructions(
granular_config: GranularApprovalConfig,
approval_context: ApprovalPromptContext<'_>,
approved_command_prefixes: Option<String>,
exec_permission_approvals_enabled: bool,
request_permissions_tool_enabled: bool,
) -> String {
let instructions = ApprovalInstructions::new(approval_context);
let sandbox_approval_prompts_allowed = granular_config.allows_sandbox_approval();
let shell_permission_requests_available =
exec_permission_approvals_enabled && sandbox_approval_prompts_allowed;
@@ -456,7 +461,7 @@ fn granular_instructions(
}
if request_permissions_tool_prompts_allowed {
sections.push(REQUEST_PERMISSIONS_TOOL.to_string());
sections.push(instructions.tool());
}
sections.extend(approved_command_prefixes);
@@ -0,0 +1,59 @@
//! Selects bounded catalog headings while preserving all permission and review guidance.
use super::AUTO_REVIEW_SUFFIX;
use super::ApprovalPromptContext;
use super::PermissionsInstructions;
use super::REQUEST_PERMISSIONS_TOOL;
use codex_context_fragments::ContextualUserFragment;
use codex_protocol::openai_models::ApprovalMessages;
pub(super) struct ApprovalInstructions<'a>(Option<&'a ApprovalMessages>);
impl<'a> ApprovalInstructions<'a> {
pub(super) fn new(context: ApprovalPromptContext<'a>) -> Self {
Self(context.messages.catalog)
}
pub(super) fn tool(&self) -> String {
with_heading(
self.0.and_then(|m| m.request_permissions.as_deref()),
REQUEST_PERMISSIONS_TOOL,
)
}
pub(super) fn auto_review(&self) -> String {
match self
.0
.and_then(|m| m.auto_review_suffix.as_deref())
.filter(|s| valid_heading(s))
{
Some(heading) => format!("{heading}\n\n{AUTO_REVIEW_SUFFIX}"),
None => AUTO_REVIEW_SUFFIX.to_owned(),
}
}
}
fn with_heading(heading: Option<&str>, bundled: &str) -> String {
match (
heading.filter(|s| valid_heading(s)),
bundled.find(['\r', '\n']),
) {
(Some(heading), Some(end)) => format!("{heading}{}", &bundled[end..]),
_ => bundled.to_owned(),
}
}
// One single-line heading can add at most 500 UTF-8 bytes plus its paragraph separator.
fn valid_heading(text: &str) -> bool {
let (open, close) = PermissionsInstructions::type_markers();
text.len() <= 500
&& !text.trim().is_empty()
&& !text.chars().any(char::is_control)
&& !text.contains(['{', '}', '\u{2028}', '\u{2029}'])
&& !text.contains(open)
&& !text.contains(close)
}
#[cfg(test)]
#[path = "approval_instructions_tests.rs"]
mod tests;
@@ -0,0 +1,34 @@
//! Verifies catalog heading bounds and preservation of bundled instruction line endings.
#![cfg(test)]
use super::*;
use pretty_assertions::assert_eq;
#[test]
fn replacing_heading_preserves_the_bundled_line_endings() {
let bundled = "Heading\r\n\r\nRequired instructions.\r\n";
assert_eq!(
with_heading(Some("Catalog"), bundled),
"Catalog\r\n\r\nRequired instructions.\r\n"
);
}
#[test]
fn accepts_bounded_heading_and_rejects_malformed_presentation() {
let boundary = "é".repeat(250);
assert!(valid_heading(&boundary));
let (open, close) = PermissionsInstructions::type_markers();
for invalid in [
"",
" ",
&format!("{boundary}a"),
open,
close,
"{{ policy }}",
"title\nbody",
"title\u{2028}body",
] {
assert!(!valid_heading(invalid), "accepted {invalid:?}");
}
}
@@ -427,6 +427,7 @@ fn catalog_approval_messages_select_reviewer_variant() {
never: Some("never catalog approvals".to_string()),
unless_trusted: Some("unless-trusted catalog approvals".to_string()),
granular: None,
..Default::default()
};
for (approval_policy, reviewer, expected) in [
@@ -476,6 +477,7 @@ fn empty_catalog_approval_message_suppresses_legacy_approval_section() {
never: None,
unless_trusted: None,
granular: None,
..Default::default()
};
let approved_command_prefixes = vec![vec!["git".to_string(), "pull".to_string()]];
let writable_root = "/tmp/repo".to_string();
@@ -517,6 +519,7 @@ fn missing_catalog_key_uses_legacy_approval_text() {
never: None,
unless_trusted: None,
granular: None,
..Default::default()
},
),
(
@@ -527,6 +530,7 @@ fn missing_catalog_key_uses_legacy_approval_text() {
never: None,
unless_trusted: None,
granular: None,
..Default::default()
},
),
] {
@@ -571,6 +575,7 @@ fn empty_catalog_non_on_request_approval_messages_suppress_legacy_approval_text(
never: Some(String::new()),
unless_trusted: Some(String::new()),
granular: None,
..Default::default()
};
for approval_policy in [AskForApproval::Never, AskForApproval::UnlessTrusted] {
@@ -641,6 +646,79 @@ const ALL_PROMPTED_CATEGORIES: &str =
- `skill_approval`
- `mcp_elicitations`";
#[test]
fn granular_approval_headings_follow_independent_tool_and_sandbox_gates() {
let messages = ApprovalMessages {
request_permissions: Some("Catalog permission tool".into()),
auto_review_suffix: Some("Catalog reviewer".into()),
..Default::default()
};
let context = ApprovalPromptContext {
messages: ResolvedApprovalMessages::new(Some(&messages)),
..user_approval_context()
};
for (sandbox_allowed, tool_allowed) in
[(true, false), (false, true), (true, true), (false, false)]
{
let text = approval_text(
AskForApproval::Granular(GranularApprovalConfig {
sandbox_approval: sandbox_allowed,
request_permissions: tool_allowed,
..ALL_APPROVALS_ENABLED
}),
context,
&[],
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ true,
);
assert_eq!(text.contains(REQUEST_PERMISSION_RULE), sandbox_allowed);
assert_eq!(text.contains("Catalog permission tool"), tool_allowed);
assert!(!text.contains("Catalog reviewer"));
}
}
#[test]
fn catalog_heading_fallback_and_policy_selection_are_independent() {
let messages = ApprovalMessages {
request_permissions: Some("Catalog permission tool".into()),
auto_review_suffix: Some("{{ unknown }}".into()),
..Default::default()
};
let bundled = ApprovalPromptContext::new(
ApprovalsReviewer::AutoReview,
ResolvedModelMessages::bundled(),
);
let catalog = ApprovalPromptContext {
messages: ResolvedApprovalMessages::new(Some(&messages)),
..bundled
};
for policy in [
AskForApproval::Never,
AskForApproval::UnlessTrusted,
AskForApproval::OnRequest,
] {
for tool_enabled in [false, true] {
let render = |context| {
approval_text(
policy,
context,
&[],
/*exec_permission_approvals_enabled*/ true,
tool_enabled,
)
};
let default = render(bundled);
let expected = if tool_enabled && policy != AskForApproval::Never {
assert!(default.contains("# request_permissions Tool"));
default.replace("# request_permissions Tool", "Catalog permission tool")
} else {
default
};
assert_eq!(render(catalog), expected);
}
}
}
#[test]
fn granular_policy_lists_prompted_and_rejected_categories_separately() {
let text = approval_text(
@@ -740,6 +818,7 @@ fn preserves_supplied_path_spellings_and_order() {
never: None,
unless_trusted: None,
granular: None,
..Default::default()
};
let permission_messages = PermissionMessages {
danger_full_access: None,