feat: add permission profile list api (#23412)

## Why

Clients need a typed permission-profile catalog instead of
reconstructing that state from config internals.

## What changed

- Added `permissionProfile/list` to the app-server v2 protocol with
cursor pagination and optional `cwd`.
- The list response includes built-in permission profiles plus
config-defined `[permissions.<id>]` profiles from the effective config
for the request context.
- Permission profiles keep optional `description` metadata for display
purposes.
- App-server docs and schema fixtures are updated for the new RPC.

codex-rs/app-server/README.md

@@ -189,6 +189,7 @@ Example with notification opt-out:
 - `model/list` — list available models (set `includeHidden: true` to include entries with `hidden: true`), with reasoning effort options, `additionalSpeedTiers`, optional legacy `upgrade` model ids, optional `upgradeInfo` metadata (`model`, `upgradeCopy`, `modelLink`, `migrationMarkdown`), and optional `availabilityNux` metadata.
 - `modelProvider/capabilities/read` — read provider-level capabilities for the currently configured model provider.
 - `experimentalFeature/list` — list feature flags with stage metadata (`beta`, `underDevelopment`, `stable`, etc.), enabled/default-enabled state, and cursor pagination. Pass `threadId` when showing feature state for an existing loaded thread so `enabled` is computed from that thread's refreshed config, including project-local config for the thread's cwd; if omitted, the server uses its default config resolution context. For non-beta flags, `displayName`/`description`/`announcement` are `null`.
+- `permissionProfile/list` — beta; list available permission profile ids with optional display `description` text, using cursor pagination. Pass `cwd` when the caller needs project-local `[permissions.<id>]` entries to be included in the current catalog view.
 - `experimentalFeature/enablement/set` — patch the in-memory process-wide runtime feature enablement for the currently supported feature keys (`apps`, `memories`, `plugins`, `tool_suggest`, `tool_call_mcp_elicitation`). For each feature, precedence is: cloud requirements > --enable <feature_name> > config.toml > experimentalFeature/enablement/set (new) > code default.
 - `environment/add` — experimental; add or replace a named remote environment by `environmentId` and `execServerUrl` for later selection by `thread/start` or `turn/start`; returns `{}` and does not change the default environment.
 - `collaborationMode/list` — list available collaboration mode presets (experimental, no pagination). Built-in presets do not select a model; the Plan preset selects medium reasoning effort. This response omits built-in developer instructions; clients should either pass `settings.developer_instructions: null` when setting a mode to use Codex's built-in instructions, or provide their own instructions explicitly.

codex-rs/app-server/src/message_processor.rs

@@ -1149,6 +1149,9 @@ impl MessageProcessor {
                     .experimental_feature_list(params)
                     .await
             }
+            ClientRequest::PermissionProfileList { params, .. } => {
+                self.catalog_processor.permission_profile_list(params).await
+            }
             ClientRequest::CollaborationModeList { params, .. } => {
                 self.catalog_processor.collaboration_mode_list(params).await
             }

codex-rs/app-server/src/request_processors.rs

@@ -103,6 +103,9 @@ use codex_app_server_protocol::MockExperimentalMethodParams;
 use codex_app_server_protocol::MockExperimentalMethodResponse;
 use codex_app_server_protocol::ModelListParams;
 use codex_app_server_protocol::ModelListResponse;
+use codex_app_server_protocol::PermissionProfileListParams;
+use codex_app_server_protocol::PermissionProfileListResponse;
+use codex_app_server_protocol::PermissionProfileSummary;
 use codex_app_server_protocol::PluginDetail;
 use codex_app_server_protocol::PluginInstallParams;
 use codex_app_server_protocol::PluginInstallResponse;
@@ -357,6 +360,9 @@ use codex_protocol::error::CodexErr;
 use codex_protocol::error::Result as CodexResult;
 #[cfg(test)]
 use codex_protocol::items::TurnItem;
+use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS;
+use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_READ_ONLY;
+use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_WORKSPACE;
 use codex_protocol::models::ResponseItem;
 #[cfg(test)]
 use codex_protocol::permissions::FileSystemSandboxPolicy;

codex-rs/app-server/src/request_processors/catalog_processor.rs

@@ -1,4 +1,5 @@
 use super::*;
+use codex_config::config_toml::ConfigToml;
 use futures::StreamExt;
 
 #[derive(Clone)]
@@ -155,6 +156,15 @@ impl CatalogRequestProcessor {
             .map(|response| Some(response.into()))
     }
 
+    pub(crate) async fn permission_profile_list(
+        &self,
+        params: PermissionProfileListParams,
+    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError> {
+        self.permission_profile_list_response(params)
+            .await
+            .map(|response| Some(response.into()))
+    }
+
     pub(crate) async fn collaboration_mode_list(
         &self,
         params: CollaborationModeListParams,
@@ -389,6 +399,78 @@ impl CatalogRequestProcessor {
         Ok(ExperimentalFeatureListResponse { data, next_cursor })
     }
 
+    async fn permission_profile_list_response(
+        &self,
+        params: PermissionProfileListParams,
+    ) -> Result<PermissionProfileListResponse, JSONRPCErrorError> {
+        let PermissionProfileListParams { cursor, limit, cwd } = params;
+        let config_layer_stack = match cwd {
+            Some(cwd) => {
+                let cwd = PathBuf::from(cwd);
+                let (_, config_layer_stack) = self
+                    .resolve_cwd_config(&cwd)
+                    .await
+                    .map_err(|err| internal_error(format!("failed to reload config: {err}")))?;
+                config_layer_stack
+            }
+            None => self
+                .config_manager
+                .load_config_layers(/*cwd*/ None)
+                .await
+                .map_err(|err| internal_error(format!("failed to reload config: {err}")))?,
+        };
+        let effective_config: ConfigToml = config_layer_stack
+            .effective_config()
+            .try_into()
+            .map_err(|err| internal_error(format!("failed to read effective config: {err}")))?;
+        let mut profiles = vec![
+            PermissionProfileSummary {
+                id: BUILT_IN_PERMISSION_PROFILE_READ_ONLY.to_string(),
+                description: None,
+            },
+            PermissionProfileSummary {
+                id: BUILT_IN_PERMISSION_PROFILE_WORKSPACE.to_string(),
+                description: None,
+            },
+            PermissionProfileSummary {
+                id: BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS.to_string(),
+                description: None,
+            },
+        ];
+        let mut configured_profiles = effective_config
+            .permissions
+            .into_iter()
+            .flat_map(|permissions| permissions.entries)
+            .map(|(id, profile)| PermissionProfileSummary {
+                id,
+                description: profile.description,
+            })
+            .collect::<Vec<_>>();
+        configured_profiles.sort_by(|left, right| left.id.cmp(&right.id));
+        profiles.extend(configured_profiles);
+        let total = profiles.len();
+        let effective_limit = limit.unwrap_or(total as u32).max(1) as usize;
+        let effective_limit = effective_limit.min(total);
+        let start = match cursor {
+            Some(cursor) => cursor
+                .parse::<usize>()
+                .map_err(|_| invalid_request(format!("invalid cursor: {cursor}")))?,
+            None => 0,
+        };
+
+        if start > total {
+            return Err(invalid_request(format!(
+                "cursor {start} exceeds total permission profiles {total}"
+            )));
+        }
+
+        let end = start.saturating_add(effective_limit).min(total);
+        let data = profiles[start..end].to_vec();
+        let next_cursor = (end < total).then_some(end.to_string());
+
+        Ok(PermissionProfileListResponse { data, next_cursor })
+    }
+
     async fn mock_experimental_method_inner(
         &self,
         params: MockExperimentalMethodParams,

codex-rs/app-server/tests/common/mcp_process.rs

@@ -56,6 +56,7 @@ use codex_app_server_protocol::McpServerToolCallParams;
 use codex_app_server_protocol::MockExperimentalMethodParams;
 use codex_app_server_protocol::ModelListParams;
 use codex_app_server_protocol::ModelProviderCapabilitiesReadParams;
+use codex_app_server_protocol::PermissionProfileListParams;
 use codex_app_server_protocol::PluginInstallParams;
 use codex_app_server_protocol::PluginInstalledParams;
 use codex_app_server_protocol::PluginListParams;
@@ -561,6 +562,15 @@ impl McpProcess {
         self.send_request("experimentalFeature/list", params).await
     }
 
+    /// Send a `permissionProfile/list` JSON-RPC request.
+    pub async fn send_permission_profile_list_request(
+        &mut self,
+        params: PermissionProfileListParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("permissionProfile/list", params).await
+    }
+
     /// Send an `experimentalFeature/enablement/set` JSON-RPC request.
     pub async fn send_experimental_feature_enablement_set_request(
         &mut self,

codex-rs/app-server/tests/suite/v2/mod.rs

@@ -29,6 +29,7 @@ mod memory_reset;
 mod model_list;
 mod model_provider_capabilities_read;
 mod output_schema;
+mod permission_profile_list;
 mod plan_item;
 mod plugin_install;
 mod plugin_list;

codex-rs/app-server/tests/suite/v2/permission_profile_list.rs

@@ -0,0 +1,233 @@
+use std::time::Duration;
+
+use anyhow::Result;
+use app_test_support::McpProcess;
+use app_test_support::to_response;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::PermissionProfileListParams;
+use codex_app_server_protocol::PermissionProfileListResponse;
+use codex_app_server_protocol::PermissionProfileSummary;
+use codex_app_server_protocol::RequestId;
+use codex_core::config::set_project_trust_level;
+use codex_protocol::config_types::TrustLevel;
+use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS;
+use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_READ_ONLY;
+use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_WORKSPACE;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use tokio::time::timeout;
+
+const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
+
+#[tokio::test]
+async fn permission_profile_list_returns_builtin_and_configured_profiles() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    std::fs::write(
+        codex_home.path().join("config.toml"),
+        r#"
+default_permissions = "dev"
+
+[permissions.dev]
+description = "Day-to-day coding work."
+
+[permissions.dev.filesystem]
+":workspace_roots" = "write"
+
+[permissions.audit]
+description = "Inspect without writes."
+
+[permissions.audit.filesystem]
+":workspace_roots" = "read"
+"#,
+    )?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_TIMEOUT, mcp.initialize()).await??;
+
+    let request_id = mcp
+        .send_permission_profile_list_request(PermissionProfileListParams {
+            cursor: None,
+            limit: None,
+            cwd: None,
+        })
+        .await?;
+    let actual = read_response::<PermissionProfileListResponse>(&mut mcp, request_id).await?;
+
+    assert_eq!(
+        actual,
+        PermissionProfileListResponse {
+            data: vec![
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_READ_ONLY.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_WORKSPACE.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: "audit".to_string(),
+                    description: Some("Inspect without writes.".to_string()),
+                },
+                PermissionProfileSummary {
+                    id: "dev".to_string(),
+                    description: Some("Day-to-day coding work.".to_string()),
+                },
+            ],
+            next_cursor: None,
+        }
+    );
+    Ok(())
+}
+
+#[tokio::test]
+async fn permission_profile_list_resolves_project_profiles_and_paginates() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let workspace = TempDir::new()?;
+    let project_config_dir = workspace.path().join(".codex");
+    std::fs::create_dir_all(&project_config_dir)?;
+    std::fs::write(
+        codex_home.path().join("config.toml"),
+        r#"
+default_permissions = ":workspace"
+"#,
+    )?;
+    std::fs::write(
+        project_config_dir.join("config.toml"),
+        r#"
+[permissions.project]
+description = "Project-scoped profile."
+
+[permissions.project.filesystem]
+":workspace_roots" = "write"
+"#,
+    )?;
+    set_project_trust_level(codex_home.path(), workspace.path(), TrustLevel::Trusted)?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_TIMEOUT, mcp.initialize()).await??;
+
+    let first_request_id = mcp
+        .send_permission_profile_list_request(PermissionProfileListParams {
+            cursor: None,
+            limit: Some(3),
+            cwd: Some(workspace.path().to_string_lossy().into_owned()),
+        })
+        .await?;
+    let first = read_response::<PermissionProfileListResponse>(&mut mcp, first_request_id).await?;
+    assert_eq!(
+        first,
+        PermissionProfileListResponse {
+            data: vec![
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_READ_ONLY.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_WORKSPACE.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS.to_string(),
+                    description: None,
+                },
+            ],
+            next_cursor: Some("3".to_string()),
+        }
+    );
+
+    let second_request_id = mcp
+        .send_permission_profile_list_request(PermissionProfileListParams {
+            cursor: first.next_cursor,
+            limit: Some(3),
+            cwd: Some(workspace.path().to_string_lossy().into_owned()),
+        })
+        .await?;
+    let second =
+        read_response::<PermissionProfileListResponse>(&mut mcp, second_request_id).await?;
+    assert_eq!(
+        second,
+        PermissionProfileListResponse {
+            data: vec![PermissionProfileSummary {
+                id: "project".to_string(),
+                description: Some("Project-scoped profile.".to_string()),
+            }],
+            next_cursor: None,
+        }
+    );
+    Ok(())
+}
+
+#[tokio::test]
+async fn permission_profile_list_discovers_project_profiles_without_default_selection() -> Result<()>
+{
+    let codex_home = TempDir::new()?;
+    let workspace = TempDir::new()?;
+    let project_config_dir = workspace.path().join(".codex");
+    std::fs::create_dir_all(&project_config_dir)?;
+    std::fs::write(
+        project_config_dir.join("config.toml"),
+        r#"
+[permissions.project]
+description = "Project-scoped profile."
+
+[permissions.project.filesystem]
+":workspace_roots" = "write"
+"#,
+    )?;
+    set_project_trust_level(codex_home.path(), workspace.path(), TrustLevel::Trusted)?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_TIMEOUT, mcp.initialize()).await??;
+
+    let request_id = mcp
+        .send_permission_profile_list_request(PermissionProfileListParams {
+            cursor: None,
+            limit: None,
+            cwd: Some(workspace.path().to_string_lossy().into_owned()),
+        })
+        .await?;
+    let actual = read_response::<PermissionProfileListResponse>(&mut mcp, request_id).await?;
+
+    assert_eq!(
+        actual,
+        PermissionProfileListResponse {
+            data: vec![
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_READ_ONLY.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_WORKSPACE.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS.to_string(),
+                    description: None,
+                },
+                PermissionProfileSummary {
+                    id: "project".to_string(),
+                    description: Some("Project-scoped profile.".to_string()),
+                },
+            ],
+            next_cursor: None,
+        }
+    );
+    Ok(())
+}
+
+async fn read_response<T: serde::de::DeserializeOwned>(
+    mcp: &mut McpProcess,
+    request_id: i64,
+) -> Result<T> {
+    let response: JSONRPCResponse = timeout(
+        DEFAULT_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    to_response(response)
+}