feat(app-server): transport permission preset requests

Add the v2 `item/permissionPreset/requestApproval` server request and
thread it through app-server delivery for clients that opt into the
matching `supportedServerRequests` capability.

Keep the flow backward compatible by failing closed when a connection
does not advertise support, reject it explicitly in `codex exec`, and
update the docs, schemas, and request transport tests.
This commit is contained in:
Felipe Coury
2026-04-13 14:45:50 -03:00
parent bbf656dcf3
commit 88e46f7459
19 changed files with 1187 additions and 9 deletions
@@ -0,0 +1,299 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"AbsolutePathBuf": {
"description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
"type": "string"
},
"ApprovalsReviewer": {
"description": "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `guardian_subagent` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request.",
"enum": [
"user",
"guardian_subagent"
],
"type": "string"
},
"AskForApproval": {
"oneOf": [
{
"enum": [
"untrusted",
"on-failure",
"on-request",
"never"
],
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"granular": {
"properties": {
"mcp_elicitations": {
"type": "boolean"
},
"request_permissions": {
"default": false,
"type": "boolean"
},
"rules": {
"type": "boolean"
},
"sandbox_approval": {
"type": "boolean"
},
"skill_approval": {
"default": false,
"type": "boolean"
}
},
"required": [
"mcp_elicitations",
"rules",
"sandbox_approval"
],
"type": "object"
}
},
"required": [
"granular"
],
"title": "GranularAskForApproval",
"type": "object"
}
]
},
"NetworkAccess": {
"enum": [
"restricted",
"enabled"
],
"type": "string"
},
"PermissionPresetId": {
"description": "A built-in permission-mode preset that app clients can confirm.",
"enum": [
"auto",
"full-access",
"read-only",
"guardian-approvals"
],
"type": "string"
},
"ReadOnlyAccess": {
"oneOf": [
{
"properties": {
"includePlatformDefaults": {
"default": true,
"type": "boolean"
},
"readableRoots": {
"default": [],
"items": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": "array"
},
"type": {
"enum": [
"restricted"
],
"title": "RestrictedReadOnlyAccessType",
"type": "string"
}
},
"required": [
"type"
],
"title": "RestrictedReadOnlyAccess",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"fullAccess"
],
"title": "FullAccessReadOnlyAccessType",
"type": "string"
}
},
"required": [
"type"
],
"title": "FullAccessReadOnlyAccess",
"type": "object"
}
]
},
"SandboxPolicy": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"dangerFullAccess"
],
"title": "DangerFullAccessSandboxPolicyType",
"type": "string"
}
},
"required": [
"type"
],
"title": "DangerFullAccessSandboxPolicy",
"type": "object"
},
{
"properties": {
"access": {
"allOf": [
{
"$ref": "#/definitions/ReadOnlyAccess"
}
],
"default": {
"type": "fullAccess"
}
},
"networkAccess": {
"default": false,
"type": "boolean"
},
"type": {
"enum": [
"readOnly"
],
"title": "ReadOnlySandboxPolicyType",
"type": "string"
}
},
"required": [
"type"
],
"title": "ReadOnlySandboxPolicy",
"type": "object"
},
{
"properties": {
"networkAccess": {
"allOf": [
{
"$ref": "#/definitions/NetworkAccess"
}
],
"default": "restricted"
},
"type": {
"enum": [
"externalSandbox"
],
"title": "ExternalSandboxSandboxPolicyType",
"type": "string"
}
},
"required": [
"type"
],
"title": "ExternalSandboxSandboxPolicy",
"type": "object"
},
{
"properties": {
"excludeSlashTmp": {
"default": false,
"type": "boolean"
},
"excludeTmpdirEnvVar": {
"default": false,
"type": "boolean"
},
"networkAccess": {
"default": false,
"type": "boolean"
},
"readOnlyAccess": {
"allOf": [
{
"$ref": "#/definitions/ReadOnlyAccess"
}
],
"default": {
"type": "fullAccess"
}
},
"type": {
"enum": [
"workspaceWrite"
],
"title": "WorkspaceWriteSandboxPolicyType",
"type": "string"
},
"writableRoots": {
"default": [],
"items": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": "array"
}
},
"required": [
"type"
],
"title": "WorkspaceWriteSandboxPolicy",
"type": "object"
}
]
}
},
"description": "Request sent to app clients when a model asks to switch permission modes.\n\nCore resolves the requested preset before emitting this payload, so clients should render the provided settings and label rather than recomputing policy choices from the preset id.",
"properties": {
"approvalPolicy": {
"$ref": "#/definitions/AskForApproval"
},
"approvalsReviewer": {
"$ref": "#/definitions/ApprovalsReviewer"
},
"description": {
"type": "string"
},
"itemId": {
"type": "string"
},
"label": {
"type": "string"
},
"preset": {
"$ref": "#/definitions/PermissionPresetId"
},
"reason": {
"type": [
"string",
"null"
]
},
"sandboxPolicy": {
"$ref": "#/definitions/SandboxPolicy"
},
"threadId": {
"type": "string"
},
"turnId": {
"type": "string"
}
},
"required": [
"approvalPolicy",
"approvalsReviewer",
"description",
"itemId",
"label",
"preset",
"sandboxPolicy",
"threadId",
"turnId"
],
"title": "PermissionPresetRequestApprovalParams",
"type": "object"
}
@@ -0,0 +1,37 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"PermissionPresetApprovalDecision": {
"enum": [
"accepted",
"declined"
],
"type": "string"
},
"PermissionPresetId": {
"description": "A built-in permission-mode preset that app clients can confirm.",
"enum": [
"auto",
"full-access",
"read-only",
"guardian-approvals"
],
"type": "string"
}
},
"description": "Response from an app client after the permission preset picker resolves.",
"properties": {
"decision": {
"$ref": "#/definitions/PermissionPresetApprovalDecision"
},
"preset": {
"$ref": "#/definitions/PermissionPresetId"
}
},
"required": [
"decision",
"preset"
],
"title": "PermissionPresetRequestApprovalResponse",
"type": "object"
}
@@ -101,6 +101,64 @@
],
"type": "object"
},
"ApprovalsReviewer": {
"description": "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `guardian_subagent` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request.",
"enum": [
"user",
"guardian_subagent"
],
"type": "string"
},
"AskForApproval": {
"oneOf": [
{
"enum": [
"untrusted",
"on-failure",
"on-request",
"never"
],
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"granular": {
"properties": {
"mcp_elicitations": {
"type": "boolean"
},
"request_permissions": {
"default": false,
"type": "boolean"
},
"rules": {
"type": "boolean"
},
"sandbox_approval": {
"type": "boolean"
},
"skill_approval": {
"default": false,
"type": "boolean"
}
},
"required": [
"mcp_elicitations",
"rules",
"sandbox_approval"
],
"type": "object"
}
},
"required": [
"granular"
],
"title": "GranularAskForApproval",
"type": "object"
}
]
},
"ChatgptAuthTokensRefreshParams": {
"properties": {
"previousAccountId": {
@@ -1187,6 +1245,13 @@
],
"type": "object"
},
"NetworkAccess": {
"enum": [
"restricted",
"enabled"
],
"type": "string"
},
"NetworkApprovalContext": {
"properties": {
"host": {
@@ -1351,6 +1416,66 @@
],
"type": "string"
},
"PermissionPresetId": {
"description": "A built-in permission-mode preset that app clients can confirm.",
"enum": [
"auto",
"full-access",
"read-only",
"guardian-approvals"
],
"type": "string"
},
"PermissionPresetRequestApprovalParams": {
"description": "Request sent to app clients when a model asks to switch permission modes.\n\nCore resolves the requested preset before emitting this payload, so clients should render the provided settings and label rather than recomputing policy choices from the preset id.",
"properties": {
"approvalPolicy": {
"$ref": "#/definitions/AskForApproval"
},
"approvalsReviewer": {
"$ref": "#/definitions/ApprovalsReviewer"
},
"description": {
"type": "string"
},
"itemId": {
"type": "string"
},
"label": {
"type": "string"
},
"preset": {
"$ref": "#/definitions/PermissionPresetId"
},
"reason": {
"type": [
"string",
"null"
]
},
"sandboxPolicy": {
"$ref": "#/definitions/SandboxPolicy"
},
"threadId": {
"type": "string"
},
"turnId": {
"type": "string"
}
},
"required": [
"approvalPolicy",
"approvalsReviewer",
"description",
"itemId",
"label",
"preset",
"sandboxPolicy",
"threadId",
"turnId"
],
"type": "object"
},
"PermissionsRequestApprovalParams": {
"properties": {
"itemId": {
@@ -1388,6 +1513,53 @@
],
"type": "object"
},
"ReadOnlyAccess": {
"oneOf": [
{
"properties": {
"includePlatformDefaults": {
"default": true,
"type": "boolean"
},
"readableRoots": {
"default": [],
"items": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": "array"
},
"type": {
"enum": [
"restricted"
],
"title": "RestrictedReadOnlyAccessType",
"type": "string"
}
},
"required": [
"type"
],
"title": "RestrictedReadOnlyAccess",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"fullAccess"
],
"title": "FullAccessReadOnlyAccessType",
"type": "string"
}
},
"required": [
"type"
],
"title": "FullAccessReadOnlyAccess",
"type": "object"
}
]
},
"RequestId": {
"anyOf": [
{
@@ -1425,6 +1597,125 @@
},
"type": "object"
},
"SandboxPolicy": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"dangerFullAccess"
],
"title": "DangerFullAccessSandboxPolicyType",
"type": "string"
}
},
"required": [
"type"
],
"title": "DangerFullAccessSandboxPolicy",
"type": "object"
},
{
"properties": {
"access": {
"allOf": [
{
"$ref": "#/definitions/ReadOnlyAccess"
}
],
"default": {
"type": "fullAccess"
}
},
"networkAccess": {
"default": false,
"type": "boolean"
},
"type": {
"enum": [
"readOnly"
],
"title": "ReadOnlySandboxPolicyType",
"type": "string"
}
},
"required": [
"type"
],
"title": "ReadOnlySandboxPolicy",
"type": "object"
},
{
"properties": {
"networkAccess": {
"allOf": [
{
"$ref": "#/definitions/NetworkAccess"
}
],
"default": "restricted"
},
"type": {
"enum": [
"externalSandbox"
],
"title": "ExternalSandboxSandboxPolicyType",
"type": "string"
}
},
"required": [
"type"
],
"title": "ExternalSandboxSandboxPolicy",
"type": "object"
},
{
"properties": {
"excludeSlashTmp": {
"default": false,
"type": "boolean"
},
"excludeTmpdirEnvVar": {
"default": false,
"type": "boolean"
},
"networkAccess": {
"default": false,
"type": "boolean"
},
"readOnlyAccess": {
"allOf": [
{
"$ref": "#/definitions/ReadOnlyAccess"
}
],
"default": {
"type": "fullAccess"
}
},
"type": {
"enum": [
"workspaceWrite"
],
"title": "WorkspaceWriteSandboxPolicyType",
"type": "string"
},
"writableRoots": {
"default": [],
"items": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": "array"
}
},
"required": [
"type"
],
"title": "WorkspaceWriteSandboxPolicy",
"type": "object"
}
]
},
"ThreadId": {
"type": "string"
},
@@ -1636,6 +1927,31 @@
"title": "Item/permissions/requestApprovalRequest",
"type": "object"
},
{
"description": "Request the client to open its permission preset picker.",
"properties": {
"id": {
"$ref": "#/definitions/RequestId"
},
"method": {
"enum": [
"item/permissionPreset/requestApproval"
],
"title": "Item/permissionPreset/requestApprovalRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/PermissionPresetRequestApprovalParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Item/permissionPreset/requestApprovalRequest",
"type": "object"
},
{
"description": "Execute a dynamic tool call on the client.",
"properties": {
@@ -3270,6 +3270,93 @@
],
"type": "string"
},
"PermissionPresetApprovalDecision": {
"enum": [
"accepted",
"declined"
],
"type": "string"
},
"PermissionPresetId": {
"description": "A built-in permission-mode preset that app clients can confirm.",
"enum": [
"auto",
"full-access",
"read-only",
"guardian-approvals"
],
"type": "string"
},
"PermissionPresetRequestApprovalParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Request sent to app clients when a model asks to switch permission modes.\n\nCore resolves the requested preset before emitting this payload, so clients should render the provided settings and label rather than recomputing policy choices from the preset id.",
"properties": {
"approvalPolicy": {
"$ref": "#/definitions/v2/AskForApproval"
},
"approvalsReviewer": {
"$ref": "#/definitions/v2/ApprovalsReviewer"
},
"description": {
"type": "string"
},
"itemId": {
"type": "string"
},
"label": {
"type": "string"
},
"preset": {
"$ref": "#/definitions/PermissionPresetId"
},
"reason": {
"type": [
"string",
"null"
]
},
"sandboxPolicy": {
"$ref": "#/definitions/v2/SandboxPolicy"
},
"threadId": {
"type": "string"
},
"turnId": {
"type": "string"
}
},
"required": [
"approvalPolicy",
"approvalsReviewer",
"description",
"itemId",
"label",
"preset",
"sandboxPolicy",
"threadId",
"turnId"
],
"title": "PermissionPresetRequestApprovalParams",
"type": "object"
},
"PermissionPresetRequestApprovalResponse": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Response from an app client after the permission preset picker resolves.",
"properties": {
"decision": {
"$ref": "#/definitions/PermissionPresetApprovalDecision"
},
"preset": {
"$ref": "#/definitions/PermissionPresetId"
}
},
"required": [
"decision",
"preset"
],
"title": "PermissionPresetRequestApprovalResponse",
"type": "object"
},
"PermissionsRequestApprovalParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
@@ -4637,6 +4724,31 @@
"title": "Item/permissions/requestApprovalRequest",
"type": "object"
},
{
"description": "Request the client to open its permission preset picker.",
"properties": {
"id": {
"$ref": "#/definitions/v2/RequestId"
},
"method": {
"enum": [
"item/permissionPreset/requestApproval"
],
"title": "Item/permissionPreset/requestApprovalRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/PermissionPresetRequestApprovalParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Item/permissionPreset/requestApprovalRequest",
"type": "object"
},
{
"description": "Execute a dynamic tool call on the client.",
"properties": {