Allow per-tool approval reviewers for Codex apps (#62360)

## Why

A connected account or app can choose an approval reviewer, but that
setting applies across its tools. Users may want to review calendar
event creation themselves while keeping automatic review for other tools.

## What changed

Set `approvals_reviewer` on an individual app tool in `config.toml`:

```toml
[apps.calendar.tools.calendar_create_event]
approvals_reviewer = "user"
```

Codex matches the tool by raw name first and falls back to its title.
The tool's reviewer takes precedence over the connected account, app,
app defaults, and session settings, subject to managed requirements.
This applies to tool-call approval prompts and MCP approval requests
that match a verified app tool invocation. The app-server
`config/read` response also exposes the per-tool setting.

## Testing

Extend coverage for reviewer precedence, tool title fallback, managed
review requirements, tool-call approval routing, strict MCP elicitation,
and app-server config reads.

GitOrigin-RevId: c92bd39b9e708dada9d314c19a446b4c580edf91
This commit is contained in:
jameswt-oai
2026-11-18 20:42:18 +00:00
committed by copyberry
parent 5387162ef0
commit 1b80bd9412
20 changed files with 204 additions and 60 deletions
@@ -8219,6 +8219,16 @@
}
]
},
"approvals_reviewer": {
"anyOf": [
{
"$ref": "#/definitions/v2/ApprovalsReviewer"
},
{
"type": "null"
}
]
},
"enabled": {
"type": [
"boolean",
@@ -1283,6 +1283,16 @@
}
]
},
"approvals_reviewer": {
"anyOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
},
{
"type": "null"
}
]
},
"enabled": {
"type": [
"boolean",
@@ -153,6 +153,16 @@
}
]
},
"approvals_reviewer": {
"anyOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
},
{
"type": "null"
}
]
},
"enabled": {
"type": [
"boolean",
@@ -2,5 +2,6 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { AppToolApproval } from "./AppToolApproval";
import type { ApprovalsReviewer } from "./ApprovalsReviewer";
export type AppToolsConfig = { [key in string]?: { enabled: boolean | null, approval_mode: AppToolApproval | null, } };
export type AppToolsConfig = { [key in string]?: { enabled: boolean | null, approval_mode: AppToolApproval | null, approvals_reviewer: ApprovalsReviewer | null, } };
@@ -203,6 +203,7 @@ pub struct AppsDefaultConfig {
pub struct AppToolConfig {
pub enabled: Option<bool>,
pub approval_mode: Option<AppToolApproval>,
pub approvals_reviewer: Option<ApprovalsReviewer>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
@@ -1416,6 +1416,7 @@ omit_tools_from = ["deferred"]
approvals_reviewer = "user"
destructive_enabled = false
default_tools_approval_mode = "prompt"
tools.list.approvals_reviewer = "auto_review"
[apps.app1.links.link_work]
approvals_reviewer = "auto_review"
@@ -1463,6 +1464,10 @@ enabled = false
response["config"]["apps"]["app_with_empty_links"].get("links"),
Some(&json!({})),
);
assert_eq!(
response["config"]["apps"]["app1"]["tools"]["list"].get("approvals_reviewer"),
Some(&json!("auto_review")),
);
let ConfigReadResponse {
config,
origins,
@@ -1490,7 +1495,9 @@ enabled = false
open_world_enabled: None,
default_tools_approval_mode: Some(AppToolApproval::Prompt),
default_tools_enabled: None,
tools: Some(serde_json::from_value(json!({"list": {"enabled": false}}))?),
tools: Some(serde_json::from_value(json!({
"list": {"enabled": false, "approvals_reviewer": "auto_review"}
}))?),
links: Some(AppLinksConfig {
links: std::collections::HashMap::from([
(
@@ -127,6 +127,7 @@ enum StrictReviewScenario {
ManagedGuardianDisabled,
ManagedReviewerForbidden,
AppReviewerUser,
ToolReviewerUser,
AppReviewerNoncanonicalId,
AppReviewerSpoofedId,
AppReviewerSpoofedAction,
@@ -149,6 +150,7 @@ impl StrictReviewScenario {
| Self::ManagedGuardianDisabled
| Self::ManagedReviewerForbidden
| Self::AppReviewerUser
| Self::ToolReviewerUser
| Self::AppReviewerNoncanonicalId
| Self::AppReviewerSpoofedId
| Self::AppReviewerSpoofedAction
@@ -319,6 +321,7 @@ async fn mcp_server_openai_elicitation_form_round_trip() -> Result<()> {
#[test_case(Review::ManagedGuardianDisabled; "managed_guardian_disabled")]
#[test_case(Review::ManagedReviewerForbidden; "managed_reviewer_forbidden")]
#[test_case(Review::AppReviewerUser; "app_reviewer_user")]
#[test_case(Review::ToolReviewerUser; "tool_reviewer_user")]
#[test_case(Review::AppReviewerNoncanonicalId; "app_reviewer_noncanonical_id")]
#[test_case(Review::AppReviewerSpoofedId; "app_reviewer_spoofed_id")]
#[test_case(Review::AppReviewerSpoofedAction; "app_reviewer_spoofed_action")]
@@ -658,6 +661,15 @@ impl ElicitationRoundTripFixture {
format!("apps.{CONNECTOR_ID}.approvals_reviewer"),
json!("user"),
);
} else if strict == Review::ToolReviewerUser {
config.insert(
format!("apps.{CONNECTOR_ID}.approvals_reviewer"),
json!("auto_review"),
);
config.insert(
format!("apps.{CONNECTOR_ID}.tools.{TOOL_NAME}.approvals_reviewer"),
json!("user"),
);
} else if strict == Review::AppDefaultReviewerUser {
config.insert(
"apps._default.approvals_reviewer".to_string(),
+13
View File
@@ -499,6 +499,10 @@ pub struct AppToolConfig {
/// Approval mode for this tool.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub approval_mode: Option<AppToolApproval>,
/// Reviewer for this tool's approval prompts, overriding link-level and app-level settings.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub approvals_reviewer: Option<ApprovalsReviewer>,
}
/// Tool settings for a single app.
@@ -510,6 +514,15 @@ pub struct AppToolsConfig {
pub tools: HashMap<String, AppToolConfig>,
}
impl AppToolsConfig {
/// Match a tool by its raw name first and use its title as a fallback.
pub fn for_tool(&self, name: &str, title: Option<&str>) -> Option<&AppToolConfig> {
self.tools
.get(name)
.or_else(|| title.and_then(|title| self.tools.get(title)))
}
}
/// Approval settings for a connected account within an app.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
#[schemars(deny_unknown_fields)]
+1 -6
View File
@@ -246,12 +246,7 @@ fn app_tool_policy_from_apps_config(
.connector_id
.and_then(|connector_id| apps_config.apps.get(connector_id));
let tools = app.and_then(|app| app.tools.as_ref());
let tool_config = tools.and_then(|tools| {
tools
.tools
.get(input.tool_name)
.or_else(|| input.tool_title.and_then(|title| tools.tools.get(title)))
});
let tool_config = tools.and_then(|tools| tools.for_tool(input.tool_name, input.tool_title));
let approval = managed_approval
.or_else(|| tool_config.and_then(|tool| tool.approval_mode))
.or_else(|| {
@@ -123,6 +123,7 @@ fn evaluator_reuses_one_snapshot_across_tools() {
AppToolConfig {
enabled: Some(true),
approval_mode: Some(AppToolApproval::Prompt),
approvals_reviewer: None,
},
)]),
}),
@@ -546,6 +547,7 @@ fn managed_approval_overrides_user_tool_approval() {
AppToolConfig {
enabled: None,
approval_mode: Some(AppToolApproval::Prompt),
approvals_reviewer: None,
},
)]),
}),
@@ -698,6 +700,7 @@ fn per_tool_enable_overrides_app_level_hints() {
AppToolConfig {
enabled: Some(true),
approval_mode: None,
approvals_reviewer: None,
},
)]),
}),
@@ -871,6 +874,7 @@ fn evaluator_matches_tool_title_for_user_config() {
AppToolConfig {
enabled: Some(true),
approval_mode: Some(AppToolApproval::Approve),
approvals_reviewer: None,
},
)]),
}),
+8
View File
@@ -237,6 +237,14 @@
],
"description": "Approval mode for this tool."
},
"approvals_reviewer": {
"allOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
}
],
"description": "Reviewer for this tool's approval prompts, overriding link-level and app-level settings."
},
"enabled": {
"description": "Whether this tool is enabled. `Some(true)` explicitly allows this tool.",
"type": "boolean"
+9 -3
View File
@@ -508,6 +508,7 @@ pub fn with_app_plugin_sources(
connectors
}
#[expect(clippy::too_many_arguments)]
pub(crate) fn mcp_approvals_reviewer_from_layers(
config_layer_stack: &codex_config::ConfigLayerStack,
requirements: &ConfigRequirements,
@@ -516,6 +517,7 @@ pub(crate) fn mcp_approvals_reviewer_from_layers(
server_name: &str,
connector_id: Option<&str>,
link_id: Option<&str>,
tool: Option<(&str, Option<&str>)>,
) -> ApprovalsReviewer {
if model.is_some_and(|model| requirements.auto_review_required_for_model(model)) {
return ApprovalsReviewer::AutoReview;
@@ -524,9 +526,13 @@ pub(crate) fn mcp_approvals_reviewer_from_layers(
let app_reviewer = if server_name == CODEX_APPS_MCP_SERVER_NAME {
apps_config_from_layer_stack(config_layer_stack).and_then(|apps_config| {
let app = connector_id.and_then(|connector_id| apps_config.apps.get(connector_id));
link_id
.and_then(|link_id| app?.links.as_ref()?.links.get(link_id))
.and_then(|link| link.approvals_reviewer)
tool.and_then(|(name, title)| app?.tools.as_ref()?.for_tool(name, title))
.and_then(|tool| tool.approvals_reviewer)
.or_else(|| {
link_id
.and_then(|link_id| app?.links.as_ref()?.links.get(link_id))
.and_then(|link| link.approvals_reviewer)
})
.or_else(|| app.and_then(|app| app.approvals_reviewer))
.or_else(|| {
apps_config
+47 -7
View File
@@ -305,7 +305,7 @@ fn accessible_connectors_from_mcp_tools_preserves_description() {
}
#[tokio::test]
async fn app_approvals_reviewer_uses_link_then_app_then_default_then_global() {
async fn app_approvals_reviewer_uses_tool_then_link_then_app_then_default_then_global() {
for (global, app_default, app, expected_global, expected_default, expected_app) in [
(
"user",
@@ -340,7 +340,16 @@ approvals_reviewer = "{app}"
[apps.calendar.links.link_calendar]
approvals_reviewer = "{app_default}"
[apps.calendar.links.link_without_privacy]
[apps.calendar.links.other_calendar]
approvals_reviewer = "{app}"
[apps.calendar.links.link_without_reviewer]
[apps.calendar.tools."events/create"]
approvals_reviewer = "{app_default}"
[apps.calendar.tools."events/list"]
enabled = true
[apps.drive.links.link_drive]
approvals_reviewer = "{app_default}"
@@ -362,11 +371,13 @@ approvals_reviewer = "{app}"
.await
.expect("config should build");
for (link_id, expected) in [
(Some("link_calendar"), expected_default),
(Some("link_without_privacy"), expected_app),
(Some("link_drive"), expected_app),
(None, expected_app),
for (link_id, tool_name, expected) in [
(Some("link_calendar"), "events/list", expected_default),
(Some("other_calendar"), "events/create", expected_default),
(Some("link_without_reviewer"), "events/list", expected_app),
(Some("link_drive"), "events/list", expected_app),
(None, "events/create", expected_default),
(None, "events/list", expected_app),
] {
assert_eq!(
mcp_approvals_reviewer_from_layers(
@@ -377,6 +388,26 @@ approvals_reviewer = "{app}"
CODEX_APPS_MCP_SERVER_NAME,
Some("calendar"),
link_id,
Some((tool_name, None)),
),
expected
);
}
// The title supplies the reviewer only when there is no entry for the raw name.
for (name, expected) in [
("calendar_create_event", expected_default),
("events/list", expected_app),
] {
assert_eq!(
mcp_approvals_reviewer_from_layers(
&config.config_layer_stack,
config.config_layer_stack.requirements(),
config.approvals_reviewer,
config.model.as_deref(),
CODEX_APPS_MCP_SERVER_NAME,
Some("calendar"),
/*link_id*/ None,
Some((name, Some("events/create"))),
),
expected
);
@@ -391,6 +422,7 @@ approvals_reviewer = "{app}"
CODEX_APPS_MCP_SERVER_NAME,
Some(connector_id),
Some("link_calendar"),
Some(("events/create", None)),
),
expected_app
);
@@ -404,6 +436,7 @@ approvals_reviewer = "{app}"
CODEX_APPS_MCP_SERVER_NAME,
Some("drive"),
/*link_id*/ None,
Some(("events/create", None)),
),
expected_default
);
@@ -416,6 +449,7 @@ approvals_reviewer = "{app}"
CODEX_APPS_MCP_SERVER_NAME,
/*connector_id*/ None,
/*link_id*/ None,
/*tool*/ None,
),
expected_default
);
@@ -428,6 +462,7 @@ approvals_reviewer = "{app}"
"custom_server",
Some("calendar"),
Some("link_calendar"),
Some(("events/create", None)),
),
expected_global
);
@@ -467,6 +502,7 @@ approvals_reviewer = "user"
CODEX_APPS_MCP_SERVER_NAME,
Some("calendar"),
/*link_id*/ None,
/*tool*/ None,
),
ApprovalsReviewer::AutoReview
);
@@ -485,6 +521,9 @@ approvals_reviewer = "user"
[apps.calendar.links.link_calendar]
approvals_reviewer = "user"
[apps.calendar.tools."events/create"]
approvals_reviewer = "user"
"#,
)
.expect("write config");
@@ -509,6 +548,7 @@ approvals_reviewer = "user"
CODEX_APPS_MCP_SERVER_NAME,
Some("calendar"),
link_id,
Some(("events/create", None)),
),
ApprovalsReviewer::AutoReview
);
+2 -1
View File
@@ -1362,7 +1362,7 @@ pub(crate) struct McpToolApprovalMetadata {
connector_description: Option<String>,
connected_account_email: Option<String>,
plugin_id: Option<String>,
tool_title: Option<String>,
pub(crate) tool_title: Option<String>,
tool_description: Option<String>,
mcp_app_resource_uri: Option<String>,
mcp_app_ui: Option<McpAppUi>,
@@ -1759,6 +1759,7 @@ async fn prepare_mcp_tool_approval(
&invocation.server,
metadata.connector_id.as_deref(),
metadata.link_id.as_deref(),
Some((&invocation.tool, metadata.tool_title.as_deref())),
);
let action = ApprovalAction::McpToolCall {
id: call_id.to_string(),
+2
View File
@@ -2609,6 +2609,7 @@ async fn persist_codex_app_tool_approval_writes_tool_override() {
AppToolConfig {
enabled: None,
approval_mode: Some(AppToolApproval::Approve),
approvals_reviewer: None,
},
)]),
}),
@@ -2822,6 +2823,7 @@ async fn maybe_persist_mcp_tool_approval_reloads_session_config() {
&AppToolConfig {
enabled: None,
approval_mode: Some(AppToolApproval::Approve),
approvals_reviewer: None,
}
);
}
+31 -25
View File
@@ -1207,34 +1207,38 @@ async fn review_guardian_mcp_elicitation(
.and_then(|meta| meta.get(MCP_ELICITATION_STRICT_AUTO_REVIEW_KEY)),
Some(Value::Bool(true))
);
let connector_id = elicitation_connector_id(&request.elicitation);
// A live Browser invocation can review a nested action with its own identity.
// Other hosted connectors must still review their registered outer invocation.
let review_outer_invocation =
request.server_name == CODEX_APPS_MCP_SERVER_NAME && originating_call_id.is_none();
let requested_tool = request
.elicitation
.meta()
.and_then(|meta| metadata_str(meta, MCP_ELICITATION_TOOL_NAME_KEY));
let verified_invocation = if review_outer_invocation
&& let Some(call_id) = call_id
&& let Some(McpToolApprovalContext {
invocation: Some(invocation),
metadata,
..
}) = approval_context.as_deref()
&& invocation.server == request.server_name
&& metadata.connector_id.as_deref() == connector_id
&& requested_tool == Some(invocation.tool.as_str())
{
Some((call_id, invocation, metadata))
} else {
None
};
let tool = verified_invocation.map(|(_, invocation, metadata)| {
(invocation.tool.as_str(), metadata.tool_title.as_deref())
});
let mut guardian_request: crate::guardian::ReviewAction = if strict_auto_review {
let connector_id = elicitation_connector_id(&request.elicitation);
// A live Browser invocation can review a nested action with its own identity.
// Other hosted connectors must still review their registered outer invocation.
let review_outer_invocation =
request.server_name == CODEX_APPS_MCP_SERVER_NAME && originating_call_id.is_none();
let trusted_guardian_request = if review_outer_invocation {
let Some(call_id) = call_id else {
let Some((call_id, invocation, metadata)) = verified_invocation else {
return Ok(None);
};
let Some(McpToolApprovalContext {
invocation: Some(invocation),
metadata,
..
}) = approval_context.as_deref()
else {
return Ok(None);
};
if invocation.server != request.server_name
|| connector_id != metadata.connector_id.as_deref()
|| request
.elicitation
.meta()
.and_then(|meta| metadata_str(meta, MCP_ELICITATION_TOOL_NAME_KEY))
!= Some(invocation.tool.as_str())
{
return Ok(None);
}
Some(
crate::mcp_tool_call::build_guardian_mcp_tool_review_request(
call_id,
@@ -1258,6 +1262,7 @@ async fn review_guardian_mcp_elicitation(
request.server_name.as_str(),
connector_id,
/*link_id*/ None,
tool,
) != ApprovalsReviewer::AutoReview
|| request
.elicitation
@@ -1329,8 +1334,9 @@ async fn review_guardian_mcp_elicitation(
requested_reviewer,
Some(review_context.model_info.slug.as_str()),
request.server_name.as_str(),
elicitation_connector_id(&request.elicitation),
connector_id,
/*link_id*/ None,
tool,
);
review_context.approval_policy = approval_policy;
review_context.approvals_reviewer = approvals_reviewer;
+25 -8
View File
@@ -537,14 +537,32 @@ async fn wait_for_mcp_tool_call_item(
.await
}
const DEFAULT_USER_REVIEWER_CONFIG: &str = r#"
[apps._default]
default_tools_approval_mode = "prompt"
approvals_reviewer = "user"
"#;
const CALENDAR_TOOL_USER_REVIEWER_CONFIG: &str = r#"
[apps.calendar]
default_tools_approval_mode = "prompt"
approvals_reviewer = "auto_review"
[apps.calendar.tools.calendar_create_event]
approvals_reviewer = "user"
"#;
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
#[test_case(false; "without strict auto review")]
#[test_case(true; "with strict auto review")]
#[test_case(false, DEFAULT_USER_REVIEWER_CONFIG; "without strict auto review")]
#[test_case(true, DEFAULT_USER_REVIEWER_CONFIG; "with strict auto review")]
#[test_case(false, CALENDAR_TOOL_USER_REVIEWER_CONFIG; "tool reviewer overrides app reviewer")]
async fn approved_mcp_tool_call_metadata_records_prior_user_input_request(
strict_auto_review: bool,
apps_config_toml: &str,
) -> Result<()> {
skip_if_no_network!(Ok(()));
let apps_config = toml::from_str(apps_config_toml)?;
let server = start_mock_server().await;
let apps_server = AppsTestServer::mount(&server).await?;
let call_id = "calendar-call-approval";
@@ -628,11 +646,10 @@ async fn approved_mcp_tool_call_metadata_records_prior_user_input_request(
.enable(Feature::RequestPermissionsTool)
.expect("test config should allow feature update");
}
set_default_app_approval_mode_and_reviewer(
config,
AppToolApproval::Prompt,
ApprovalsReviewer::User,
);
config.config_layer_stack = config
.config_layer_stack
.with_user_config(&config.codex_home.join("config.toml").abs(), apps_config)
.expect("apps user config should be valid");
});
let test = builder.build(&server).await?;
let root_turn_id = "originating-calendar-turn";
@@ -711,7 +728,7 @@ async fn approved_mcp_tool_call_metadata_records_prior_user_input_request(
})
.await
else {
panic!("expected apps._default user to route the app approval to the user");
panic!("expected the configured reviewer to route the app approval to the user");
};
test.codex
@@ -263,14 +263,6 @@ class AppToolApproval(Enum):
approve = "approve"
class AppToolConfig(BaseModel):
model_config = ConfigDict(
populate_by_name=True,
)
approval_mode: AppToolApproval | None = None
enabled: bool | None = None
class AppToolSummary(BaseModel):
model_config = ConfigDict(
populate_by_name=True,
@@ -7594,6 +7586,15 @@ class AppTemplateSummary(BaseModel):
template_id: Annotated[str, Field(alias="templateId")]
class AppToolConfig(BaseModel):
model_config = ConfigDict(
populate_by_name=True,
)
approval_mode: AppToolApproval | None = None
approvals_reviewer: ApprovalsReviewer | None = None
enabled: bool | None = None
class ApplicationNetworkRequirements(BaseModel):
model_config = ConfigDict(
populate_by_name=True,