Add explicit command approval purpose

codex-rs/app-server-protocol/schema/json/CommandExecutionRequestApprovalParams.json

@@ -273,6 +273,14 @@
         }
       ]
     },
+    "CommandExecutionApprovalPurpose": {
+      "enum": [
+        "initial",
+        "execve",
+        "sandboxRetry"
+      ],
+      "type": "string"
+    },
     "FileSystemAccessMode": {
       "enum": [
         "read",
@@ -527,6 +535,17 @@
         "null"
       ]
     },
+    "approvalPurpose": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/CommandExecutionApprovalPurpose"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Semantic purpose of this approval request. Compatibility events may omit it."
+    },
     "command": {
       "description": "The command to be executed.",
       "type": [

codex-rs/app-server-protocol/schema/json/ServerRequest.json

@@ -342,6 +342,14 @@
         }
       ]
     },
+    "CommandExecutionApprovalPurpose": {
+      "enum": [
+        "initial",
+        "execve",
+        "sandboxRetry"
+      ],
+      "type": "string"
+    },
     "CommandExecutionRequestApprovalParams": {
       "properties": {
         "approvalId": {
@@ -351,6 +359,17 @@
             "null"
           ]
         },
+        "approvalPurpose": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CommandExecutionApprovalPurpose"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Semantic purpose of this approval request. Compatibility events may omit it."
+        },
         "command": {
           "description": "The command to be executed.",
           "type": [

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json

@@ -2371,6 +2371,14 @@
         }
       ]
     },
+    "CommandExecutionApprovalPurpose": {
+      "enum": [
+        "initial",
+        "execve",
+        "sandboxRetry"
+      ],
+      "type": "string"
+    },
     "CommandExecutionRequestApprovalParams": {
       "$schema": "http://json-schema.org/draft-07/schema#",
       "properties": {
@@ -2381,6 +2389,17 @@
             "null"
           ]
         },
+        "approvalPurpose": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CommandExecutionApprovalPurpose"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Semantic purpose of this approval request. Compatibility events may omit it."
+        },
         "command": {
           "description": "The command to be executed.",
           "type": [

codex-rs/app-server-protocol/schema/typescript/v2/CommandExecutionApprovalPurpose.ts

@@ -0,0 +1,5 @@
+// GENERATED CODE! DO NOT MODIFY BY HAND!
+
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type CommandExecutionApprovalPurpose = "initial" | "execve" | "sandboxRetry";

codex-rs/app-server-protocol/schema/typescript/v2/CommandExecutionRequestApprovalParams.ts

@@ -3,6 +3,7 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 import type { LegacyAppPathString } from "../LegacyAppPathString";
 import type { CommandAction } from "./CommandAction";
+import type { CommandExecutionApprovalPurpose } from "./CommandExecutionApprovalPurpose";
 import type { ExecPolicyAmendment } from "./ExecPolicyAmendment";
 import type { NetworkApprovalContext } from "./NetworkApprovalContext";
 import type { NetworkPolicyAmendment } from "./NetworkPolicyAmendment";
@@ -18,6 +19,9 @@ startedAtMs: number, /**
  * present. Absence is a legacy/cacheable compatibility path.
  */
 approvalId?: string | null, /**
+ * Semantic purpose of this approval request. Compatibility events may omit it.
+ */
+approvalPurpose?: CommandExecutionApprovalPurpose | null, /**
  * Environment in which the command will run.
  */
 environmentId: string | null, /**

codex-rs/app-server-protocol/schema/typescript/v2/index.ts

@@ -63,6 +63,7 @@ export type { CommandExecTerminateResponse } from "./CommandExecTerminateRespons
 export type { CommandExecWriteParams } from "./CommandExecWriteParams";
 export type { CommandExecWriteResponse } from "./CommandExecWriteResponse";
 export type { CommandExecutionApprovalDecision } from "./CommandExecutionApprovalDecision";
+export type { CommandExecutionApprovalPurpose } from "./CommandExecutionApprovalPurpose";
 export type { CommandExecutionOutputDeltaNotification } from "./CommandExecutionOutputDeltaNotification";
 export type { CommandExecutionRequestApprovalParams } from "./CommandExecutionRequestApprovalParams";
 export type { CommandExecutionRequestApprovalResponse } from "./CommandExecutionRequestApprovalResponse";

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -3693,6 +3693,7 @@ mod tests {
             item_id: "call_123".to_string(),
             started_at_ms: 0,
             approval_id: None,
+            approval_purpose: None,
             environment_id: None,
             reason: None,
             network_approval_context: None,

codex-rs/app-server-protocol/src/protocol/v2/item.rs

@@ -11,6 +11,7 @@ use super::shared::v2_enum_from_core;
 use crate::protocol::item_builders::command_actions_for_path_uri;
 use crate::protocol::item_builders::convert_patch_changes;
 use codex_experimental_api_macros::ExperimentalApi;
+use codex_protocol::approvals::ExecApprovalPurpose as CoreExecApprovalPurpose;
 use codex_protocol::approvals::GuardianAssessmentAction as CoreGuardianAssessmentAction;
 use codex_protocol::approvals::GuardianAssessmentDecisionSource as CoreGuardianAssessmentDecisionSource;
 use codex_protocol::approvals::GuardianCommandSource as CoreGuardianCommandSource;
@@ -72,6 +73,14 @@ pub enum CommandExecutionApprovalDecision {
     Cancel,
 }
 
+v2_enum_from_core! {
+    pub enum CommandExecutionApprovalPurpose from CoreExecApprovalPurpose {
+        Initial,
+        Execve,
+        SandboxRetry,
+    }
+}
+
 impl From<CoreReviewDecision> for CommandExecutionApprovalDecision {
     fn from(value: CoreReviewDecision) -> Self {
         match value {
@@ -1452,6 +1461,10 @@ pub struct CommandExecutionRequestApprovalParams {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     #[ts(optional = nullable)]
     pub approval_id: Option<String>,
+    /// Semantic purpose of this approval request. Compatibility events may omit it.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[ts(optional = nullable)]
+    pub approval_purpose: Option<CommandExecutionApprovalPurpose>,
     /// Environment in which the command will run.
     #[serde(default)]
     pub environment_id: Option<String>,