feat(core): add conversational permission preset foundation

Add the opt-in `request_permission_preset` flow across `codex-core`, `codex-protocol`, and `codex-tools`, including preset definitions, request state, tool wiring, and focused regression coverage for preset-driven permission changes.

Validate preset responses against pending call ids before applying them, re-resolve accepted presets against the current session, and record turn-local overrides only after `update_settings` succeeds so stale or rejected replies cannot widen permissions.
This commit is contained in:
Felipe Coury
2026-04-12 21:08:51 -03:00
parent 46ab9974dc
commit ffa0ea303d
41 changed files with 1626 additions and 41 deletions
+1
View File
@@ -21,6 +21,7 @@ pub mod parse_command;
pub mod permissions;
pub mod plan_tool;
pub mod protocol;
pub mod request_permission_preset;
pub mod request_permissions;
pub mod request_user_input;
pub mod user_input;
+126 -7
View File
@@ -391,6 +391,7 @@ struct PermissionsPromptConfig<'a> {
exec_policy: &'a Policy,
exec_permission_approvals_enabled: bool,
request_permissions_tool_enabled: bool,
request_permission_preset_tool_enabled: bool,
}
impl DeveloperInstructions {
@@ -404,13 +405,17 @@ impl DeveloperInstructions {
exec_policy: &Policy,
exec_permission_approvals_enabled: bool,
request_permissions_tool_enabled: bool,
request_permission_preset_tool_enabled: bool,
) -> DeveloperInstructions {
let with_request_permissions_tool = |text: &str| {
let append_permission_tool_sections = |text: &str| {
let mut sections = vec![text.to_string()];
if request_permissions_tool_enabled {
format!("{text}\n\n{}", request_permissions_tool_prompt_section())
} else {
text.to_string()
sections.push(request_permissions_tool_prompt_section().to_string());
}
if request_permission_preset_tool_enabled {
sections.push(request_permission_preset_tool_prompt_section().to_string());
}
sections.join("\n\n")
};
let on_request_instructions = || {
let on_request_rule = if exec_permission_approvals_enabled {
@@ -422,6 +427,9 @@ impl DeveloperInstructions {
if request_permissions_tool_enabled {
sections.push(request_permissions_tool_prompt_section().to_string());
}
if request_permission_preset_tool_enabled {
sections.push(request_permission_preset_tool_prompt_section().to_string());
}
if let Some(prefixes) = approved_command_prefixes_text(exec_policy) {
sections.push(format!(
"## Approved command prefixes\nThe following prefix rules have already been approved: {prefixes}"
@@ -432,15 +440,18 @@ impl DeveloperInstructions {
let text = match approval_policy {
AskForApproval::Never => APPROVAL_POLICY_NEVER.to_string(),
AskForApproval::UnlessTrusted => {
with_request_permissions_tool(APPROVAL_POLICY_UNLESS_TRUSTED)
append_permission_tool_sections(APPROVAL_POLICY_UNLESS_TRUSTED)
}
AskForApproval::OnFailure => {
append_permission_tool_sections(APPROVAL_POLICY_ON_FAILURE)
}
AskForApproval::OnFailure => with_request_permissions_tool(APPROVAL_POLICY_ON_FAILURE),
AskForApproval::OnRequest => on_request_instructions(),
AskForApproval::Granular(granular_config) => granular_instructions(
granular_config,
exec_policy,
exec_permission_approvals_enabled,
request_permissions_tool_enabled,
request_permission_preset_tool_enabled,
),
};
@@ -498,6 +509,7 @@ impl DeveloperInstructions {
DeveloperInstructions::new(message)
}
#[allow(clippy::too_many_arguments)]
pub fn from_policy(
sandbox_policy: &SandboxPolicy,
approval_policy: AskForApproval,
@@ -506,6 +518,7 @@ impl DeveloperInstructions {
cwd: &Path,
exec_permission_approvals_enabled: bool,
request_permissions_tool_enabled: bool,
request_permission_preset_tool_enabled: bool,
) -> Self {
let network_access = if sandbox_policy.has_full_network_access() {
NetworkAccess::Enabled
@@ -532,6 +545,7 @@ impl DeveloperInstructions {
exec_policy,
exec_permission_approvals_enabled,
request_permissions_tool_enabled,
request_permission_preset_tool_enabled,
},
writable_roots,
)
@@ -570,6 +584,7 @@ impl DeveloperInstructions {
config.exec_policy,
config.exec_permission_approvals_enabled,
config.request_permissions_tool_enabled,
config.request_permission_preset_tool_enabled,
))
.concat(DeveloperInstructions::from_writable_roots(writable_roots))
.concat(end_tag)
@@ -621,7 +636,11 @@ fn granular_prompt_intro_text() -> &'static str {
}
fn request_permissions_tool_prompt_section() -> &'static str {
"# request_permissions Tool\n\nThe built-in `request_permissions` tool is available in this session. Invoke it when you need to request additional `network` or `file_system` permissions before later shell-like commands need them. Request only the specific permissions required for the task."
"# request_permissions Tool\n\nThe built-in `request_permissions` tool is available in this session. Invoke it immediately when the user asks conversationally to allow specific filesystem or network access, for example \"allow writing to ~/Downloads in this session\" or \"grant access to /tmp/output\". Request only the specific permissions required. Set `scope` to `session` when the user explicitly asks for session-long access; otherwise use `turn`. After this tool returns, the user has already approved or denied the request in the UI. If permissions were granted, treat them as active now; do not say \"once you approve\" or ask the user to approve the same request again. If no permissions were granted, say the request was not approved."
}
fn request_permission_preset_tool_prompt_section() -> &'static str {
"# request_permission_preset Tool\n\nThe built-in `request_permission_preset` tool is available in this session. Invoke it immediately when the user asks conversationally to change the broad sandboxing, approval, or permission mode, for example \"make this session full access\", \"switch to full access\", \"make the session read-only\", or \"use guardian approvals\". The tool opens the permission-mode picker with the requested preset preselected; the session only changes if the user selects a mode there. Do not claim the mode changed until the tool returns an accepted decision. Use `request_permissions` instead for named paths or narrow filesystem/network grants; never use the preset picker for requests like \"allow writing to ~/Downloads\"."
}
fn granular_instructions(
@@ -629,12 +648,15 @@ fn granular_instructions(
exec_policy: &Policy,
exec_permission_approvals_enabled: bool,
request_permissions_tool_enabled: bool,
request_permission_preset_tool_enabled: bool,
) -> String {
let sandbox_approval_prompts_allowed = granular_config.allows_sandbox_approval();
let shell_permission_requests_available =
exec_permission_approvals_enabled && sandbox_approval_prompts_allowed;
let request_permissions_tool_prompts_allowed =
request_permissions_tool_enabled && granular_config.allows_request_permissions();
let request_permission_preset_tool_prompts_allowed =
request_permission_preset_tool_enabled && granular_config.allows_request_permissions();
let categories = [
Some((
granular_config.allows_sandbox_approval(),
@@ -646,6 +668,10 @@ fn granular_instructions(
granular_config.allows_request_permissions(),
"`request_permissions`",
)),
request_permission_preset_tool_enabled.then_some((
granular_config.allows_request_permissions(),
"`request_permission_preset`",
)),
Some((
granular_config.allows_mcp_elicitations(),
"`mcp_elicitations`",
@@ -686,6 +712,9 @@ fn granular_instructions(
if request_permissions_tool_prompts_allowed {
sections.push(request_permissions_tool_prompt_section().to_string());
}
if request_permission_preset_tool_prompts_allowed {
sections.push(request_permission_preset_tool_prompt_section().to_string());
}
if let Some(prefixes) = approved_command_prefixes_text(exec_policy) {
sections.push(format!(
@@ -1693,6 +1722,7 @@ mod tests {
exec_policy: &Policy::empty(),
exec_permission_approvals_enabled: false,
request_permissions_tool_enabled: false,
request_permission_preset_tool_enabled: false,
},
/*writable_roots*/ None,
);
@@ -1726,6 +1756,7 @@ mod tests {
&PathBuf::from("/tmp"),
/*exec_permission_approvals_enabled*/ false,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ false,
);
let text = instructions.into_text();
assert!(text.contains("Network access is enabled."));
@@ -1750,6 +1781,7 @@ mod tests {
exec_policy: &exec_policy,
exec_permission_approvals_enabled: false,
request_permissions_tool_enabled: false,
request_permission_preset_tool_enabled: false,
},
/*writable_roots*/ None,
);
@@ -1771,6 +1803,7 @@ mod tests {
exec_policy: &Policy::empty(),
exec_permission_approvals_enabled: false,
request_permissions_tool_enabled: true,
request_permission_preset_tool_enabled: false,
},
/*writable_roots*/ None,
);
@@ -1778,6 +1811,8 @@ mod tests {
let text = instructions.into_text();
assert!(text.contains("`approval_policy` is `unless-trusted`"));
assert!(text.contains("# request_permissions Tool"));
assert!(text.contains("After this tool returns, the user has already approved or denied"));
assert!(text.contains("do not say \"once you approve\""));
}
#[test]
@@ -1791,6 +1826,7 @@ mod tests {
exec_policy: &Policy::empty(),
exec_permission_approvals_enabled: false,
request_permissions_tool_enabled: true,
request_permission_preset_tool_enabled: false,
},
/*writable_roots*/ None,
);
@@ -1811,6 +1847,7 @@ mod tests {
exec_policy: &Policy::empty(),
exec_permission_approvals_enabled: true,
request_permissions_tool_enabled: false,
request_permission_preset_tool_enabled: false,
},
/*writable_roots*/ None,
);
@@ -1831,6 +1868,7 @@ mod tests {
exec_policy: &Policy::empty(),
exec_permission_approvals_enabled: false,
request_permissions_tool_enabled: true,
request_permission_preset_tool_enabled: false,
},
/*writable_roots*/ None,
);
@@ -1840,6 +1878,33 @@ mod tests {
assert!(
text.contains("The built-in `request_permissions` tool is available in this session.")
);
assert!(text.contains("allow writing to ~/Downloads in this session"));
assert!(text.contains("Set `scope` to `session`"));
}
#[test]
fn includes_request_permission_preset_tool_instructions_when_enabled() {
let instructions = DeveloperInstructions::from_permissions_with_network(
SandboxMode::WorkspaceWrite,
NetworkAccess::Enabled,
PermissionsPromptConfig {
approval_policy: AskForApproval::OnRequest,
approvals_reviewer: ApprovalsReviewer::User,
exec_policy: &Policy::empty(),
exec_permission_approvals_enabled: false,
request_permissions_tool_enabled: false,
request_permission_preset_tool_enabled: true,
},
/*writable_roots*/ None,
);
let text = instructions.into_text();
assert!(text.contains("# request_permission_preset Tool"));
assert!(text.contains(
"asks conversationally to change the broad sandboxing, approval, or permission mode"
));
assert!(text.contains("Use `request_permissions` instead for named paths"));
assert!(text.contains("never use the preset picker"));
}
#[test]
@@ -1853,6 +1918,7 @@ mod tests {
exec_policy: &Policy::empty(),
exec_permission_approvals_enabled: true,
request_permissions_tool_enabled: true,
request_permission_preset_tool_enabled: false,
},
/*writable_roots*/ None,
);
@@ -1870,6 +1936,7 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ false,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
@@ -1885,6 +1952,7 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ false,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
@@ -1900,6 +1968,7 @@ mod tests {
rejected_categories: &[&str],
include_shell_permission_request_instructions: bool,
include_request_permissions_tool_section: bool,
include_request_permission_preset_tool_section: bool,
) -> String {
let mut sections = vec![granular_prompt_intro_text().to_string()];
if !prompted_categories.is_empty() {
@@ -1920,6 +1989,9 @@ mod tests {
if include_request_permissions_tool_section {
sections.push(request_permissions_tool_prompt_section().to_string());
}
if include_request_permission_preset_tool_section {
sections.push(request_permission_preset_tool_prompt_section().to_string());
}
sections.join("\n\n")
}
@@ -1937,6 +2009,7 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
@@ -1971,6 +2044,7 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
@@ -1986,6 +2060,7 @@ mod tests {
&[],
/*include_shell_permission_request_instructions*/ true,
/*include_request_permissions_tool_section*/ false,
/*include_request_permission_preset_tool_section*/ false,
)
);
}
@@ -2004,6 +2079,7 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ false,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
@@ -2019,6 +2095,7 @@ mod tests {
&[],
/*include_shell_permission_request_instructions*/ false,
/*include_request_permissions_tool_section*/ false,
/*include_request_permission_preset_tool_section*/ false,
)
);
}
@@ -2037,6 +2114,7 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ true,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
assert!(allowed.contains("# request_permissions Tool"));
@@ -2053,11 +2131,51 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ true,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
assert!(!rejected.contains("# request_permissions Tool"));
}
#[test]
fn granular_policy_includes_request_permission_preset_tool_only_when_that_prompt_can_still_fire()
{
let allowed = DeveloperInstructions::from(
AskForApproval::Granular(GranularApprovalConfig {
sandbox_approval: true,
rules: true,
skill_approval: true,
request_permissions: true,
mcp_elicitations: true,
}),
ApprovalsReviewer::User,
&Policy::empty(),
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ true,
)
.into_text();
assert!(allowed.contains("# request_permission_preset Tool"));
let rejected = DeveloperInstructions::from(
AskForApproval::Granular(GranularApprovalConfig {
sandbox_approval: true,
rules: true,
skill_approval: true,
request_permissions: false,
mcp_elicitations: true,
}),
ApprovalsReviewer::User,
&Policy::empty(),
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ true,
)
.into_text();
assert!(!rejected.contains("# request_permission_preset Tool"));
assert!(rejected.contains("- `request_permission_preset`"));
}
#[test]
fn granular_policy_lists_request_permissions_category_without_tool_section_when_tool_is_unavailable()
{
@@ -2073,6 +2191,7 @@ mod tests {
&Policy::empty(),
/*exec_permission_approvals_enabled*/ true,
/*request_permissions_tool_enabled*/ false,
/*request_permission_preset_tool_enabled*/ false,
)
.into_text();
+13
View File
@@ -45,6 +45,8 @@ use crate::num_format::format_with_separators;
use crate::openai_models::ReasoningEffort as ReasoningEffortConfig;
use crate::parse_command::ParsedCommand;
use crate::plan_tool::UpdatePlanArgs;
use crate::request_permission_preset::RequestPermissionPresetEvent;
use crate::request_permission_preset::RequestPermissionPresetResponse;
use crate::request_permissions::RequestPermissionsEvent;
use crate::request_permissions::RequestPermissionsResponse;
use crate::request_user_input::RequestUserInputResponse;
@@ -574,6 +576,14 @@ pub enum Op {
response: RequestPermissionsResponse,
},
/// Resolve a request_permission_preset tool call.
RequestPermissionPresetResponse {
/// Call id for the in-flight request.
id: String,
/// User decision for the requested permission preset.
response: RequestPermissionPresetResponse,
},
/// Resolve a dynamic tool call request.
DynamicToolResponse {
/// Call id for the in-flight request.
@@ -744,6 +754,7 @@ impl Op {
Self::ResolveElicitation { .. } => "resolve_elicitation",
Self::UserInputAnswer { .. } => "user_input_answer",
Self::RequestPermissionsResponse { .. } => "request_permissions_response",
Self::RequestPermissionPresetResponse { .. } => "request_permission_preset_response",
Self::DynamicToolResponse { .. } => "dynamic_tool_response",
Self::AddToHistory { .. } => "add_to_history",
Self::GetHistoryEntryRequest { .. } => "get_history_entry_request",
@@ -1471,6 +1482,8 @@ pub enum EventMsg {
RequestPermissions(RequestPermissionsEvent),
RequestPermissionPreset(RequestPermissionPresetEvent),
RequestUserInput(RequestUserInputEvent),
DynamicToolCallRequest(DynamicToolCallRequest),
@@ -0,0 +1,91 @@
//! Protocol types for conversational permission-mode preset requests.
//!
//! These messages represent the narrow bridge between a model tool call and a
//! client-owned confirmation UI. Core resolves a requested preset into concrete
//! sandbox, approval, and reviewer settings before emitting the event, and the
//! settings only become active after the client returns an accepted response.
use crate::config_types::ApprovalsReviewer;
use crate::protocol::AskForApproval;
use crate::protocol::SandboxPolicy;
use schemars::JsonSchema;
use serde::Deserialize;
use serde::Serialize;
use ts_rs::TS;
/// A built-in permission-mode preset that can be requested conversationally.
#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "kebab-case")]
#[ts(rename_all = "kebab-case")]
pub enum PermissionPresetId {
Auto,
FullAccess,
ReadOnly,
GuardianApprovals,
}
impl PermissionPresetId {
/// Returns the stable kebab-case identifier used in tool arguments and UI payloads.
pub fn as_str(self) -> &'static str {
match self {
Self::Auto => "auto",
Self::FullAccess => "full-access",
Self::ReadOnly => "read-only",
Self::GuardianApprovals => "guardian-approvals",
}
}
/// Parses a stable preset identifier into a permission preset enum value.
pub fn from_id(id: &str) -> Option<Self> {
match id {
"auto" => Some(Self::Auto),
"full-access" => Some(Self::FullAccess),
"read-only" => Some(Self::ReadOnly),
"guardian-approvals" => Some(Self::GuardianApprovals),
_ => None,
}
}
}
/// Arguments passed by the model when it asks the client to open the preset picker.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
pub struct RequestPermissionPresetArgs {
pub preset: PermissionPresetId,
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
}
/// The user's completed decision from the permission preset confirmation UI.
#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "snake_case")]
pub enum RequestPermissionPresetDecision {
Accepted,
Declined,
}
/// The result returned to the model after the permission preset picker is resolved.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
pub struct RequestPermissionPresetResponse {
pub decision: RequestPermissionPresetDecision,
pub preset: PermissionPresetId,
pub message: String,
}
/// Event sent from core to a client so the client can confirm a preset change.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
pub struct RequestPermissionPresetEvent {
/// Responses API call id for the associated tool call, if available.
pub call_id: String,
/// Turn ID that this request belongs to.
/// Uses `#[serde(default)]` for backwards compatibility.
#[serde(default)]
pub turn_id: String,
pub preset: PermissionPresetId,
pub label: String,
pub description: String,
pub approval_policy: AskForApproval,
pub approvals_reviewer: ApprovalsReviewer,
pub sandbox_policy: SandboxPolicy,
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
}
@@ -1,3 +1,10 @@
//! Protocol types for conversational requests to grant narrow permissions.
//!
//! These messages are scoped to concrete filesystem and network grants, not
//! broad sandbox-mode changes. The model asks for a specific permission profile,
//! core normalizes it, and the client returns the permissions the user actually
//! granted so partial approvals and denials stay explicit.
use crate::models::FileSystemPermissions;
use crate::models::NetworkPermissions;
use crate::models::PermissionProfile;
@@ -6,6 +13,7 @@ use serde::Deserialize;
use serde::Serialize;
use ts_rs::TS;
/// How long an approved narrow permission grant should remain active.
#[derive(Debug, Clone, Copy, Default, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "snake_case")]
pub enum PermissionGrantScope {
@@ -14,6 +22,7 @@ pub enum PermissionGrantScope {
Session,
}
/// A narrow permission profile that can be requested through the confirmation UI.
#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
#[serde(deny_unknown_fields)]
pub struct RequestPermissionProfile {
@@ -22,6 +31,7 @@ pub struct RequestPermissionProfile {
}
impl RequestPermissionProfile {
/// Returns true when no filesystem or network permission was requested or granted.
pub fn is_empty(&self) -> bool {
self.network.is_none() && self.file_system.is_none()
}
@@ -45,13 +55,17 @@ impl From<PermissionProfile> for RequestPermissionProfile {
}
}
/// Arguments passed by the model when it asks the client to grant specific permissions.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
pub struct RequestPermissionsArgs {
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
pub permissions: RequestPermissionProfile,
#[serde(default)]
pub scope: PermissionGrantScope,
}
/// The permissions the user granted after resolving the confirmation UI.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
pub struct RequestPermissionsResponse {
pub permissions: RequestPermissionProfile,
@@ -59,6 +73,7 @@ pub struct RequestPermissionsResponse {
pub scope: PermissionGrantScope,
}
/// Event sent from core to a client so the client can confirm a narrow permission grant.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
pub struct RequestPermissionsEvent {
/// Responses API call id for the associated tool call, if available.
@@ -70,4 +85,6 @@ pub struct RequestPermissionsEvent {
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
pub permissions: RequestPermissionProfile,
#[serde(default)]
pub suggested_scope: PermissionGrantScope,
}