Add managed command checkpoints requiring fresh human approval (#58045)

## Why

Managed command policies need to require a human decision independently of automatic review, hook allowances, and saved approvals.

## What changed

- Support `decision = "prompt-user"` in managed `requirements.toml` prefix rules, requiring a fresh, one-time human decision for matching commands.
- Add experimental `humanCommand` approval requests for clients advertising both `experimentalApi` and `requiredHumanApproval`. Accept only `accept`, `decline`, or `cancel`; reject commands when no capable client is available.
- Restrict responses to capable clients that received the request, and replay pending prompts to compatible clients on reconnect.
- Enable the capability in the TUI and update protocol schemas and client bindings.

## Testing

Add coverage for fresh decisions overriding saved allowances, hook allowances, and automatic review, plus child-thread approval routing and rejection of responses from incompatible or unrelated clients.

GitOrigin-RevId: 0b95ff6aab7f8a04b7298c8a4329d1fddf6a603e

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

@@ -1760,6 +1760,10 @@
           "default": false,
           "description": "Opt into `attestation/generate` requests for upstream `x-oai-attestation`.",
           "type": "boolean"
+        },
+        "requiredHumanApproval": {
+          "description": "Present `humanCommand` approvals to a person and return only a one-time decision. Requires `experimentalApi`. Pending requests can be replayed to compatible clients.",
+          "type": "boolean"
         }
       },
       "type": "object"

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

@@ -271,11 +271,22 @@
     },
     "CommandExecutionApprovalKind": {
       "description": "Distinguishes a command approval from input sent to an existing terminal.",
-      "enum": [
-        "command",
-        "writeStdin"
-      ],
-      "type": "string"
+      "oneOf": [
+        {
+          "enum": [
+            "command",
+            "writeStdin"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "A managed checkpoint requiring a fresh human decision. Only `accept`, `decline`, and `cancel` are valid. Requires the `requiredHumanApproval` initialize capability. This prompt does not itself start a command execution item.",
+          "enum": [
+            "humanCommand"
+          ],
+          "type": "string"
+        }
+      ]
     },
     "FileSystemAccessMode": {
       "enum": [

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

@@ -340,11 +340,22 @@
     },
     "CommandExecutionApprovalKind": {
       "description": "Distinguishes a command approval from input sent to an existing terminal.",
-      "enum": [
-        "command",
-        "writeStdin"
-      ],
-      "type": "string"
+      "oneOf": [
+        {
+          "enum": [
+            "command",
+            "writeStdin"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "A managed checkpoint requiring a fresh human decision. Only `accept`, `decline`, and `cancel` are valid. Requires the `requiredHumanApproval` initialize capability. This prompt does not itself start a command execution item.",
+          "enum": [
+            "humanCommand"
+          ],
+          "type": "string"
+        }
+      ]
     },
     "CommandExecutionRequestApprovalParams": {
       "properties": {

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

@@ -2840,11 +2840,22 @@
     },
     "CommandExecutionApprovalKind": {
       "description": "Distinguishes a command approval from input sent to an existing terminal.",
-      "enum": [
-        "command",
-        "writeStdin"
-      ],
-      "type": "string"
+      "oneOf": [
+        {
+          "enum": [
+            "command",
+            "writeStdin"
+          ],
+          "type": "string"
+        },
+        {
+          "description": "A managed checkpoint requiring a fresh human decision. Only `accept`, `decline`, and `cancel` are valid. Requires the `requiredHumanApproval` initialize capability. This prompt does not itself start a command execution item.",
+          "enum": [
+            "humanCommand"
+          ],
+          "type": "string"
+        }
+      ]
     },
     "CommandExecutionRequestApprovalParams": {
       "$schema": "http://json-schema.org/draft-07/schema#",
@@ -3437,6 +3448,10 @@
           "default": false,
           "description": "Opt into `attestation/generate` requests for upstream `x-oai-attestation`.",
           "type": "boolean"
+        },
+        "requiredHumanApproval": {
+          "description": "Present `humanCommand` approvals to a person and return only a one-time decision. Requires `experimentalApi`. Pending requests can be replayed to compatible clients.",
+          "type": "boolean"
         }
       },
       "type": "object"

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

@@ -10095,6 +10095,10 @@
           "default": false,
           "description": "Opt into `attestation/generate` requests for upstream `x-oai-attestation`.",
           "type": "boolean"
+        },
+        "requiredHumanApproval": {
+          "description": "Present `humanCommand` approvals to a person and return only a one-time decision. Requires `experimentalApi`. Pending requests can be replayed to compatible clients.",
+          "type": "boolean"
         }
       },
       "type": "object"

codex-rs/app-server-protocol/schema/json/v1/InitializeParams.json

@@ -60,6 +60,10 @@
           "default": false,
           "description": "Opt into `attestation/generate` requests for upstream `x-oai-attestation`.",
           "type": "boolean"
+        },
+        "requiredHumanApproval": {
+          "description": "Present `humanCommand` approvals to a person and return only a one-time decision. Requires `experimentalApi`. Pending requests can be replayed to compatible clients.",
+          "type": "boolean"
         }
       },
       "type": "object"

codex-rs/app-server-protocol/schema/typescript/InitializeCapabilities.ts

@@ -7,6 +7,11 @@ import type { JsonValue } from "./serde_json/JsonValue";
  * Client-declared capabilities negotiated during initialize.
  */
 export type InitializeCapabilities = {
+/**
+ * Present `humanCommand` approvals to a person and return only a one-time decision.
+ * Requires `experimentalApi`. Pending requests can be replayed to compatible clients.
+ */
+requiredHumanApproval?: boolean,
 /**
  * Use explicit gateway OAuth login instead of automatic browser authorization.
  * Applies to this app-server's gateway runtime; later connections cannot undo it.

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

@@ -5,4 +5,4 @@
 /**
  * Distinguishes a command approval from input sent to an existing terminal.
  */
-export type CommandExecutionApprovalKind = "command" | "writeStdin";
+export type CommandExecutionApprovalKind = "command" | "humanCommand" | "writeStdin";

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

@@ -2835,6 +2835,7 @@ mod tests {
                     version: "0.1.0".to_string(),
                 },
                 capabilities: Some(v1::InitializeCapabilities {
+                    required_human_approval: false,
                     explicit_gateway_oauth: false,
                     experimental_api: true,
                     request_attestation: true,
@@ -2923,6 +2924,7 @@ mod tests {
                         version: "0.1.0".to_string(),
                     },
                     capabilities: Some(v1::InitializeCapabilities {
+                        required_human_approval: false,
                         explicit_gateway_oauth: false,
                         experimental_api: true,
                         request_attestation: true,

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

@@ -44,6 +44,10 @@ pub struct ClientInfo {
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct InitializeCapabilities {
+    /// Present `humanCommand` approvals to a person and return only a one-time decision.
+    /// Requires `experimentalApi`. Pending requests can be replayed to compatible clients.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub required_human_approval: bool,
     /// Use explicit gateway OAuth login instead of automatic browser authorization.
     /// Applies to this app-server's gateway runtime; later connections cannot undo it.
     #[serde(default, skip_serializing_if = "std::ops::Not::not")]

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

@@ -1644,6 +1644,10 @@ v2_enum_from_core! {
     pub enum CommandExecutionApprovalKind from CoreExecApprovalKind {
         #[default]
         Command,
+        /// A managed checkpoint requiring a fresh human decision. Only `accept`, `decline`, and
+        /// `cancel` are valid. Requires the `requiredHumanApproval` initialize capability.
+        /// This prompt does not itself start a command execution item.
+        HumanCommand,
         WriteStdin,
     }
 }