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
+2
View File
@@ -63,10 +63,12 @@ pub use json_schema::parse_tool_input_schema;
pub use local_tool::CommandToolOptions;
pub use local_tool::ShellToolOptions;
pub use local_tool::create_exec_command_tool;
pub use local_tool::create_request_permission_preset_tool;
pub use local_tool::create_request_permissions_tool;
pub use local_tool::create_shell_command_tool;
pub use local_tool::create_shell_tool;
pub use local_tool::create_write_stdin_tool;
pub use local_tool::request_permission_preset_tool_description;
pub use local_tool::request_permissions_tool_description;
pub use mcp_resource_tool::create_list_mcp_resource_templates_tool;
pub use mcp_resource_tool::create_list_mcp_resources_tool;
+50 -1
View File
@@ -275,6 +275,16 @@ pub fn create_request_permissions_tool(description: String) -> ToolSpec {
)),
),
("permissions".to_string(), permission_profile_schema()),
(
"scope".to_string(),
JsonSchema::string_enum(
vec![json!("turn"), json!("session")],
Some(
"How long the granted permissions should apply. Use \"session\" when the user explicitly asks for access in this session; defaults to \"turn\"."
.to_string(),
),
),
),
]);
ToolSpec::Function(ResponsesApiTool {
@@ -292,7 +302,46 @@ pub fn create_request_permissions_tool(description: String) -> ToolSpec {
}
pub fn request_permissions_tool_description() -> String {
"Request additional filesystem or network permissions from the user and wait for the client to grant a subset of the requested permission profile. Granted permissions apply automatically to later shell-like commands in the current turn, or for the rest of the session if the client approves them at session scope."
"Open a permissions request for specific filesystem or network access, such as writing to a named path like ~/Downloads. Use this immediately when the user conversationally asks to allow access to a specific path or network permission. The returned result means the user has already approved or denied the request in the UI. Granted permissions apply automatically to later shell-like commands in the current turn, or for the rest of the session when scope is \"session\" and the client approves them at session scope. After the tool returns, do not ask the user to approve the same request again."
.to_string()
}
pub fn create_request_permission_preset_tool(available_preset_ids: Vec<&'static str>) -> ToolSpec {
let properties = BTreeMap::from([
(
"preset".to_string(),
JsonSchema::string_enum(
available_preset_ids
.into_iter()
.map(|id| json!(id))
.collect(),
Some("Built-in permission preset to request from the user.".to_string()),
),
),
(
"reason".to_string(),
JsonSchema::string(Some(
"Optional short explanation for why the permission mode should change.".to_string(),
)),
),
]);
ToolSpec::Function(ResponsesApiTool {
name: "request_permission_preset".to_string(),
description: request_permission_preset_tool_description(),
strict: false,
defer_loading: None,
parameters: JsonSchema::object(
properties,
Some(vec!["preset".to_string()]),
Some(false.into()),
),
output_schema: None,
})
}
pub fn request_permission_preset_tool_description() -> String {
"Open the permission-mode picker with a built-in preset such as Default or Full Access preselected. Use this immediately when the user says things like \"make this session full access\", \"switch to read-only\", or otherwise conversationally asks to change sandboxing, approval, or permission mode. The session only changes if the user selects a permission mode in the picker."
.to_string()
}
+18
View File
@@ -308,6 +308,16 @@ fn request_permissions_tool_includes_full_permission_schema() {
)),
),
("permissions".to_string(), permission_profile_schema()),
(
"scope".to_string(),
JsonSchema::string_enum(
vec![serde_json::json!("turn"), serde_json::json!("session")],
Some(
"How long the granted permissions should apply. Use \"session\" when the user explicitly asks for access in this session; defaults to \"turn\"."
.to_string(),
),
),
),
]);
assert_eq!(
@@ -327,6 +337,14 @@ fn request_permissions_tool_includes_full_permission_schema() {
);
}
#[test]
fn request_permissions_tool_description_marks_returned_decision_as_resolved() {
let description = request_permissions_tool_description();
assert!(description.contains("the user has already approved or denied the request"));
assert!(description.contains("do not ask the user to approve the same request again"));
}
#[test]
fn shell_command_tool_matches_expected_spec() {
let tool = create_shell_command_tool(CommandToolOptions {
+7
View File
@@ -97,6 +97,8 @@ pub struct ToolsConfig {
pub tool_suggest: bool,
pub exec_permission_approvals_enabled: bool,
pub request_permissions_tool_enabled: bool,
pub request_permission_preset_tool_enabled: bool,
pub guardian_approval_enabled: bool,
pub code_mode_enabled: bool,
pub code_mode_only_enabled: bool,
pub js_repl_enabled: bool,
@@ -161,6 +163,9 @@ impl ToolsConfig {
&& supports_image_generation(model_info);
let exec_permission_approvals_enabled = features.enabled(Feature::ExecPermissionApprovals);
let request_permissions_tool_enabled = features.enabled(Feature::RequestPermissionsTool);
let request_permission_preset_tool_enabled =
features.enabled(Feature::RequestPermissionPresetTool);
let guardian_approval_enabled = features.enabled(Feature::GuardianApproval);
let shell_command_backend =
if features.enabled(Feature::ShellTool) && features.enabled(Feature::ShellZshFork) {
ShellCommandBackendConfig::ZshFork
@@ -218,6 +223,8 @@ impl ToolsConfig {
tool_suggest: include_tool_suggest,
exec_permission_approvals_enabled,
request_permissions_tool_enabled,
request_permission_preset_tool_enabled,
guardian_approval_enabled,
code_mode_enabled: include_code_mode,
code_mode_only_enabled: include_code_mode_only,
js_repl_enabled: include_js_repl,
+21
View File
@@ -34,6 +34,7 @@ use crate::create_list_mcp_resources_tool;
use crate::create_local_shell_tool;
use crate::create_read_mcp_resource_tool;
use crate::create_report_agent_job_result_tool;
use crate::create_request_permission_preset_tool;
use crate::create_request_permissions_tool;
use crate::create_request_user_input_tool;
use crate::create_resume_agent_tool;
@@ -61,6 +62,7 @@ use crate::request_user_input_tool_description;
use crate::tool_registry_plan_types::agent_type_description;
use codex_protocol::openai_models::ApplyPatchToolType;
use codex_protocol::openai_models::ConfigShellToolType;
use codex_utils_approval_presets::builtin_permission_presets;
use rmcp::model::Tool as McpTool;
use std::collections::BTreeMap;
@@ -247,6 +249,25 @@ pub fn build_tool_registry_plan(
plan.register_handler("request_permissions", ToolHandlerKind::RequestPermissions);
}
if config.request_permission_preset_tool_enabled {
let available_preset_ids = builtin_permission_presets(
cfg!(target_os = "windows"),
config.guardian_approval_enabled,
)
.into_iter()
.map(|preset| preset.id)
.collect();
plan.push_spec(
create_request_permission_preset_tool(available_preset_ids),
/*supports_parallel_tool_calls*/ false,
config.code_mode_enabled,
);
plan.register_handler(
"request_permission_preset",
ToolHandlerKind::RequestPermissionPreset,
);
}
if config.search_tool
&& let Some(deferred_mcp_tools) = params.deferred_mcp_tools
{
+90 -23
View File
@@ -123,10 +123,19 @@ fn test_full_toolset_specs_for_gpt5_codex_unified_exec_web_search() {
expected.insert(spec.name().to_string(), spec);
}
if config.exec_permission_approvals_enabled {
if config.request_permissions_tool_enabled {
let spec = create_request_permissions_tool(request_permissions_tool_description());
expected.insert(spec.name().to_string(), spec);
}
if config.request_permission_preset_tool_enabled {
let available_preset_ids = if cfg!(target_os = "windows") {
vec!["auto", "full-access", "read-only"]
} else {
vec!["auto", "full-access"]
};
let spec = create_request_permission_preset_tool(available_preset_ids);
expected.insert(spec.name().to_string(), spec);
}
assert_eq!(
actual.keys().collect::<Vec<_>>(),
@@ -560,7 +569,7 @@ fn request_user_input_description_reflects_default_mode_feature_flag() {
}
#[test]
fn request_permissions_requires_feature_flag() {
fn request_permissions_is_enabled_by_default_and_can_be_disabled() {
let model_info = model_info();
let features = Features::with_defaults();
let available_models = Vec::new();
@@ -580,31 +589,85 @@ fn request_permissions_requires_feature_flag() {
/*deferred_mcp_tools*/ None,
&[],
);
assert_lacks_tool_name(&tools, "request_permissions");
let mut features = Features::with_defaults();
features.enable(Feature::RequestPermissionsTool);
let tools_config = ToolsConfig::new(&ToolsConfigParams {
model_info: &model_info,
available_models: &available_models,
features: &features,
image_generation_tool_auth_allowed: true,
web_search_mode: Some(WebSearchMode::Cached),
session_source: SessionSource::Cli,
sandbox_policy: &SandboxPolicy::DangerFullAccess,
windows_sandbox_level: WindowsSandboxLevel::Disabled,
});
let (tools, _) = build_specs(
&tools_config,
/*mcp_tools*/ None,
/*deferred_mcp_tools*/ None,
&[],
);
let request_permissions_tool = find_tool(&tools, "request_permissions");
assert_eq!(
request_permissions_tool.spec,
create_request_permissions_tool(request_permissions_tool_description())
);
let mut features = Features::with_defaults();
features.disable(Feature::RequestPermissionsTool);
let tools_config = ToolsConfig::new(&ToolsConfigParams {
model_info: &model_info,
available_models: &available_models,
features: &features,
image_generation_tool_auth_allowed: true,
web_search_mode: Some(WebSearchMode::Cached),
session_source: SessionSource::Cli,
sandbox_policy: &SandboxPolicy::DangerFullAccess,
windows_sandbox_level: WindowsSandboxLevel::Disabled,
});
let (tools, _) = build_specs(
&tools_config,
/*mcp_tools*/ None,
/*deferred_mcp_tools*/ None,
&[],
);
assert_lacks_tool_name(&tools, "request_permissions");
}
#[test]
fn request_permission_preset_requires_feature_flag() {
let model_info = model_info();
let mut features = Features::with_defaults();
features.disable(Feature::RequestPermissionPresetTool);
let available_models = Vec::new();
let tools_config = ToolsConfig::new(&ToolsConfigParams {
model_info: &model_info,
available_models: &available_models,
features: &features,
image_generation_tool_auth_allowed: true,
web_search_mode: Some(WebSearchMode::Cached),
session_source: SessionSource::Cli,
sandbox_policy: &SandboxPolicy::DangerFullAccess,
windows_sandbox_level: WindowsSandboxLevel::Disabled,
});
let (tools, _) = build_specs(
&tools_config,
/*mcp_tools*/ None,
/*deferred_mcp_tools*/ None,
&[],
);
assert_lacks_tool_name(&tools, "request_permission_preset");
let mut features = Features::with_defaults();
features.enable(Feature::RequestPermissionPresetTool);
let tools_config = ToolsConfig::new(&ToolsConfigParams {
model_info: &model_info,
available_models: &available_models,
features: &features,
image_generation_tool_auth_allowed: true,
web_search_mode: Some(WebSearchMode::Cached),
session_source: SessionSource::Cli,
sandbox_policy: &SandboxPolicy::DangerFullAccess,
windows_sandbox_level: WindowsSandboxLevel::Disabled,
});
let (tools, _) = build_specs(
&tools_config,
/*mcp_tools*/ None,
/*deferred_mcp_tools*/ None,
&[],
);
let request_permission_preset_tool = find_tool(&tools, "request_permission_preset");
let available_preset_ids = if cfg!(target_os = "windows") {
vec!["auto", "full-access", "read-only"]
} else {
vec!["auto", "full-access"]
};
assert_eq!(
request_permission_preset_tool.spec,
create_request_permission_preset_tool(available_preset_ids)
);
}
#[test]
@@ -630,7 +693,11 @@ fn request_permissions_tool_is_independent_from_additional_permissions() {
&[],
);
assert_lacks_tool_name(&tools, "request_permissions");
let request_permissions_tool = find_tool(&tools, "request_permissions");
assert_eq!(
request_permissions_tool.spec,
create_request_permissions_tool(request_permissions_tool_description())
);
}
#[test]
@@ -26,6 +26,7 @@ pub enum ToolHandlerKind {
Mcp,
McpResource,
Plan,
RequestPermissionPreset,
RequestPermissions,
RequestUserInput,
ResumeAgentV1,