fix(collab-stack): reconcile refreshed stack integration

Allow codex exec to fork an existing thread by id while preserving startup session metadata from the fork response.

This refreshes the branch on top of current origin/main, keeps the new exec CLI and tests, and updates the thread-response mapping to the current approvals_reviewer shape used upstream.

codex-rs/.config/nextest.toml

@@ -27,3 +27,9 @@ test-group = 'app_server_protocol_codegen'
 # Keep the library unit tests parallel.
 filter = 'package(codex-app-server) & kind(test)'
 test-group = 'app_server_integration'
+
+[[profile.default.overrides]]
+# Schema fixture generation can take longer than the default timeout on slower
+# Windows runners when app-server protocol fixture sets grow.
+filter = 'test(schema_fixtures_match_generated)'
+slow-timeout = { period = "1m", terminate-after = 2 }

codex-rs/Cargo.lock

@@ -1462,6 +1462,7 @@ dependencies = [
  "tracing-opentelemetry",
  "tracing-subscriber",
  "uuid",
+ "walkdir",
  "wiremock",
 ]
 

codex-rs/README.md

@@ -51,6 +51,7 @@ You can enable notifications by configuring a script that is run whenever the ag
 ### `codex exec` to run Codex programmatically/non-interactively
 
 To run Codex non-interactively, run `codex exec PROMPT` (you can also pass the prompt via `stdin`) and Codex will work on your task until it decides that it is done and exits. Output is printed to the terminal directly. You can set the `RUST_LOG` environment variable to see more about what's going on.
+Use `codex exec --fork <SESSION_ID> PROMPT` to fork an existing session without launching the interactive picker/UI.
 Use `codex exec --ephemeral ...` to run without persisting session rollout files to disk.
 
 ### Experimenting with the Codex Sandbox

codex-rs/app-server-client/src/lib.rs

@@ -179,6 +179,8 @@ impl InProcessClientStartArgs {
             self.config.as_ref(),
             auth_manager.clone(),
             self.session_source.clone(),
+            self.config.model_catalog.clone(),
+            self.config.custom_models.clone(),
             CollaborationModesConfig {
                 default_mode_request_user_input: self
                     .config
@@ -843,6 +845,8 @@ mod tests {
             &config,
             auth_manager.clone(),
             SessionSource::Exec,
+            config.model_catalog.clone(),
+            config.custom_models.clone(),
             CollaborationModesConfig {
                 default_mode_request_user_input: config
                     .features

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

@@ -5,6 +5,14 @@
       "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"
+    },
     "AppsListParams": {
       "description": "EXPERIMENTAL - list available apps/connectors.",
       "properties": {
@@ -634,6 +642,164 @@
       ],
       "type": "object"
     },
+    "FsCopyParams": {
+      "description": "Copy a file or directory tree on the host filesystem.",
+      "properties": {
+        "destinationPath": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute destination path."
+        },
+        "recursive": {
+          "description": "Required for directory copies; ignored for file copies.",
+          "type": "boolean"
+        },
+        "sourcePath": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute source path."
+        }
+      },
+      "required": [
+        "destinationPath",
+        "sourcePath"
+      ],
+      "type": "object"
+    },
+    "FsCreateDirectoryParams": {
+      "description": "Create a directory on the host filesystem.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute directory path to create."
+        },
+        "recursive": {
+          "description": "Whether parent directories should also be created. Defaults to `true`.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "type": "object"
+    },
+    "FsGetMetadataParams": {
+      "description": "Request metadata for an absolute path.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to inspect."
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "type": "object"
+    },
+    "FsReadDirectoryParams": {
+      "description": "List direct child names for a directory.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute directory path to read."
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "type": "object"
+    },
+    "FsReadFileParams": {
+      "description": "Read a file from the host filesystem.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to read."
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "type": "object"
+    },
+    "FsRemoveParams": {
+      "description": "Remove a file or directory tree from the host filesystem.",
+      "properties": {
+        "force": {
+          "description": "Whether missing paths should be ignored. Defaults to `true`.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to remove."
+        },
+        "recursive": {
+          "description": "Whether directory removal should recurse. Defaults to `true`.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "type": "object"
+    },
+    "FsWriteFileParams": {
+      "description": "Write a file on the host filesystem.",
+      "properties": {
+        "dataBase64": {
+          "description": "File contents encoded as base64.",
+          "type": "string"
+        },
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to write."
+        }
+      },
+      "required": [
+        "dataBase64",
+        "path"
+      ],
+      "type": "object"
+    },
     "FunctionCallOutputBody": {
       "anyOf": [
         {
@@ -2350,6 +2516,17 @@
             }
           ]
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+        },
         "baseInstructions": {
           "type": [
             "string",
@@ -2630,6 +2807,17 @@
             }
           ]
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+        },
         "baseInstructions": {
           "type": [
             "string",
@@ -2781,6 +2969,17 @@
             }
           ]
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+        },
         "baseInstructions": {
           "type": [
             "string",
@@ -2920,6 +3119,17 @@
           ],
           "description": "Override the approval policy for this turn and subsequent turns."
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this turn and subsequent turns."
+        },
         "cwd": {
           "description": "Override the working directory for this turn and subsequent turns.",
           "type": [
@@ -3670,6 +3880,174 @@
       "title": "App/listRequest",
       "type": "object"
     },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "fs/readFile"
+          ],
+          "title": "Fs/readFileRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/FsReadFileParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Fs/readFileRequest",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "fs/writeFile"
+          ],
+          "title": "Fs/writeFileRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/FsWriteFileParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Fs/writeFileRequest",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "fs/createDirectory"
+          ],
+          "title": "Fs/createDirectoryRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/FsCreateDirectoryParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Fs/createDirectoryRequest",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "fs/getMetadata"
+          ],
+          "title": "Fs/getMetadataRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/FsGetMetadataParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Fs/getMetadataRequest",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "fs/readDirectory"
+          ],
+          "title": "Fs/readDirectoryRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/FsReadDirectoryParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Fs/readDirectoryRequest",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "fs/remove"
+          ],
+          "title": "Fs/removeRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/FsRemoveParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Fs/removeRequest",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "fs/copy"
+          ],
+          "title": "Fs/copyRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/FsCopyParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Fs/copyRequest",
+      "type": "object"
+    },
     {
       "properties": {
         "id": {

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

@@ -1056,6 +1056,61 @@
       },
       "type": "object"
     },
+    "GuardianApprovalReview": {
+      "description": "[UNSTABLE] Temporary guardian approval review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+      "properties": {
+        "rationale": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "riskLevel": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/GuardianRiskLevel"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "riskScore": {
+          "format": "uint8",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "status": {
+          "$ref": "#/definitions/GuardianApprovalReviewStatus"
+        }
+      },
+      "required": [
+        "status"
+      ],
+      "type": "object"
+    },
+    "GuardianApprovalReviewStatus": {
+      "description": "[UNSTABLE] Lifecycle state for a guardian approval review.",
+      "enum": [
+        "inProgress",
+        "approved",
+        "denied",
+        "aborted"
+      ],
+      "type": "string"
+    },
+    "GuardianRiskLevel": {
+      "description": "[UNSTABLE] Risk level assigned by guardian approval review.",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "type": "string"
+    },
     "HookCompletedNotification": {
       "properties": {
         "run": {
@@ -1253,6 +1308,56 @@
       ],
       "type": "object"
     },
+    "ItemGuardianApprovalReviewCompletedNotification": {
+      "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+      "properties": {
+        "action": true,
+        "review": {
+          "$ref": "#/definitions/GuardianApprovalReview"
+        },
+        "targetItemId": {
+          "type": "string"
+        },
+        "threadId": {
+          "type": "string"
+        },
+        "turnId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "review",
+        "targetItemId",
+        "threadId",
+        "turnId"
+      ],
+      "type": "object"
+    },
+    "ItemGuardianApprovalReviewStartedNotification": {
+      "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+      "properties": {
+        "action": true,
+        "review": {
+          "$ref": "#/definitions/GuardianApprovalReview"
+        },
+        "targetItemId": {
+          "type": "string"
+        },
+        "threadId": {
+          "type": "string"
+        },
+        "turnId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "review",
+        "targetItemId",
+        "threadId",
+        "turnId"
+      ],
+      "type": "object"
+    },
     "ItemStartedNotification": {
       "properties": {
         "item": {
@@ -3706,6 +3811,46 @@
       "title": "Item/startedNotification",
       "type": "object"
     },
+    {
+      "properties": {
+        "method": {
+          "enum": [
+            "item/autoApprovalReview/started"
+          ],
+          "title": "Item/autoApprovalReview/startedNotificationMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/ItemGuardianApprovalReviewStartedNotification"
+        }
+      },
+      "required": [
+        "method",
+        "params"
+      ],
+      "title": "Item/autoApprovalReview/startedNotification",
+      "type": "object"
+    },
+    {
+      "properties": {
+        "method": {
+          "enum": [
+            "item/autoApprovalReview/completed"
+          ],
+          "title": "Item/autoApprovalReview/completedNotificationMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/ItemGuardianApprovalReviewCompletedNotification"
+        }
+      },
+      "required": [
+        "method",
+        "params"
+      ],
+      "title": "Item/autoApprovalReview/completedNotification",
+      "type": "object"
+    },
     {
       "properties": {
         "method": {

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

@@ -739,6 +739,174 @@
           "title": "App/listRequest",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/readFile"
+              ],
+              "title": "Fs/readFileRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/FsReadFileParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/readFileRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/writeFile"
+              ],
+              "title": "Fs/writeFileRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/FsWriteFileParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/writeFileRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/createDirectory"
+              ],
+              "title": "Fs/createDirectoryRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/FsCreateDirectoryParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/createDirectoryRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/getMetadata"
+              ],
+              "title": "Fs/getMetadataRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/FsGetMetadataParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/getMetadataRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/readDirectory"
+              ],
+              "title": "Fs/readDirectoryRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/FsReadDirectoryParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/readDirectoryRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/remove"
+              ],
+              "title": "Fs/removeRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/FsRemoveParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/removeRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/v2/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/copy"
+              ],
+              "title": "Fs/copyRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/FsCopyParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/copyRequest",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -3619,6 +3787,46 @@
           "title": "Item/startedNotification",
           "type": "object"
         },
+        {
+          "properties": {
+            "method": {
+              "enum": [
+                "item/autoApprovalReview/started"
+              ],
+              "title": "Item/autoApprovalReview/startedNotificationMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/ItemGuardianApprovalReviewStartedNotification"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "title": "Item/autoApprovalReview/startedNotification",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "method": {
+              "enum": [
+                "item/autoApprovalReview/completed"
+              ],
+              "title": "Item/autoApprovalReview/completedNotificationMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/v2/ItemGuardianApprovalReviewCompletedNotification"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "title": "Item/autoApprovalReview/completedNotification",
+          "type": "object"
+        },
         {
           "properties": {
             "method": {
@@ -5120,6 +5328,14 @@
       "AppToolsConfig": {
         "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"
+      },
       "AppsConfig": {
         "properties": {
           "_default": {
@@ -6016,6 +6232,17 @@
               }
             ]
           },
+          "approvals_reviewer": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "[UNSTABLE] Optional default for where approval requests are routed for review."
+          },
           "compact_prompt": {
             "type": [
               "string",
@@ -7191,6 +7418,290 @@
         ],
         "type": "string"
       },
+      "FsCopyParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Copy a file or directory tree on the host filesystem.",
+        "properties": {
+          "destinationPath": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute destination path."
+          },
+          "recursive": {
+            "description": "Required for directory copies; ignored for file copies.",
+            "type": "boolean"
+          },
+          "sourcePath": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute source path."
+          }
+        },
+        "required": [
+          "destinationPath",
+          "sourcePath"
+        ],
+        "title": "FsCopyParams",
+        "type": "object"
+      },
+      "FsCopyResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Successful response for `fs/copy`.",
+        "title": "FsCopyResponse",
+        "type": "object"
+      },
+      "FsCreateDirectoryParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Create a directory on the host filesystem.",
+        "properties": {
+          "path": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute directory path to create."
+          },
+          "recursive": {
+            "description": "Whether parent directories should also be created. Defaults to `true`.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "title": "FsCreateDirectoryParams",
+        "type": "object"
+      },
+      "FsCreateDirectoryResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Successful response for `fs/createDirectory`.",
+        "title": "FsCreateDirectoryResponse",
+        "type": "object"
+      },
+      "FsGetMetadataParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Request metadata for an absolute path.",
+        "properties": {
+          "path": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute path to inspect."
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "title": "FsGetMetadataParams",
+        "type": "object"
+      },
+      "FsGetMetadataResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Metadata returned by `fs/getMetadata`.",
+        "properties": {
+          "createdAtMs": {
+            "description": "File creation time in Unix milliseconds when available, otherwise `0`.",
+            "format": "int64",
+            "type": "integer"
+          },
+          "isDirectory": {
+            "description": "Whether the path currently resolves to a directory.",
+            "type": "boolean"
+          },
+          "isFile": {
+            "description": "Whether the path currently resolves to a regular file.",
+            "type": "boolean"
+          },
+          "modifiedAtMs": {
+            "description": "File modification time in Unix milliseconds when available, otherwise `0`.",
+            "format": "int64",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "createdAtMs",
+          "isDirectory",
+          "isFile",
+          "modifiedAtMs"
+        ],
+        "title": "FsGetMetadataResponse",
+        "type": "object"
+      },
+      "FsReadDirectoryEntry": {
+        "description": "A directory entry returned by `fs/readDirectory`.",
+        "properties": {
+          "fileName": {
+            "description": "Direct child entry name only, not an absolute or relative path.",
+            "type": "string"
+          },
+          "isDirectory": {
+            "description": "Whether this entry resolves to a directory.",
+            "type": "boolean"
+          },
+          "isFile": {
+            "description": "Whether this entry resolves to a regular file.",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "fileName",
+          "isDirectory",
+          "isFile"
+        ],
+        "type": "object"
+      },
+      "FsReadDirectoryParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "List direct child names for a directory.",
+        "properties": {
+          "path": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute directory path to read."
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "title": "FsReadDirectoryParams",
+        "type": "object"
+      },
+      "FsReadDirectoryResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Directory entries returned by `fs/readDirectory`.",
+        "properties": {
+          "entries": {
+            "description": "Direct child entries in the requested directory.",
+            "items": {
+              "$ref": "#/definitions/v2/FsReadDirectoryEntry"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "entries"
+        ],
+        "title": "FsReadDirectoryResponse",
+        "type": "object"
+      },
+      "FsReadFileParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Read a file from the host filesystem.",
+        "properties": {
+          "path": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute path to read."
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "title": "FsReadFileParams",
+        "type": "object"
+      },
+      "FsReadFileResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Base64-encoded file contents returned by `fs/readFile`.",
+        "properties": {
+          "dataBase64": {
+            "description": "File contents encoded as base64.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "dataBase64"
+        ],
+        "title": "FsReadFileResponse",
+        "type": "object"
+      },
+      "FsRemoveParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Remove a file or directory tree from the host filesystem.",
+        "properties": {
+          "force": {
+            "description": "Whether missing paths should be ignored. Defaults to `true`.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "path": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute path to remove."
+          },
+          "recursive": {
+            "description": "Whether directory removal should recurse. Defaults to `true`.",
+            "type": [
+              "boolean",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "path"
+        ],
+        "title": "FsRemoveParams",
+        "type": "object"
+      },
+      "FsRemoveResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Successful response for `fs/remove`.",
+        "title": "FsRemoveResponse",
+        "type": "object"
+      },
+      "FsWriteFileParams": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Write a file on the host filesystem.",
+        "properties": {
+          "dataBase64": {
+            "description": "File contents encoded as base64.",
+            "type": "string"
+          },
+          "path": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/AbsolutePathBuf"
+              }
+            ],
+            "description": "Absolute path to write."
+          }
+        },
+        "required": [
+          "dataBase64",
+          "path"
+        ],
+        "title": "FsWriteFileParams",
+        "type": "object"
+      },
+      "FsWriteFileResponse": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "Successful response for `fs/writeFile`.",
+        "title": "FsWriteFileResponse",
+        "type": "object"
+      },
       "FunctionCallOutputBody": {
         "anyOf": [
           {
@@ -7395,6 +7906,61 @@
         },
         "type": "object"
       },
+      "GuardianApprovalReview": {
+        "description": "[UNSTABLE] Temporary guardian approval review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+        "properties": {
+          "rationale": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "riskLevel": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/v2/GuardianRiskLevel"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "riskScore": {
+            "format": "uint8",
+            "minimum": 0.0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "status": {
+            "$ref": "#/definitions/v2/GuardianApprovalReviewStatus"
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "type": "object"
+      },
+      "GuardianApprovalReviewStatus": {
+        "description": "[UNSTABLE] Lifecycle state for a guardian approval review.",
+        "enum": [
+          "inProgress",
+          "approved",
+          "denied",
+          "aborted"
+        ],
+        "type": "string"
+      },
+      "GuardianRiskLevel": {
+        "description": "[UNSTABLE] Risk level assigned by guardian approval review.",
+        "enum": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "type": "string"
+      },
       "HazelnutScope": {
         "enum": [
           "example",
@@ -7635,6 +8201,60 @@
         "title": "ItemCompletedNotification",
         "type": "object"
       },
+      "ItemGuardianApprovalReviewCompletedNotification": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+        "properties": {
+          "action": true,
+          "review": {
+            "$ref": "#/definitions/v2/GuardianApprovalReview"
+          },
+          "targetItemId": {
+            "type": "string"
+          },
+          "threadId": {
+            "type": "string"
+          },
+          "turnId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "review",
+          "targetItemId",
+          "threadId",
+          "turnId"
+        ],
+        "title": "ItemGuardianApprovalReviewCompletedNotification",
+        "type": "object"
+      },
+      "ItemGuardianApprovalReviewStartedNotification": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+        "properties": {
+          "action": true,
+          "review": {
+            "$ref": "#/definitions/v2/GuardianApprovalReview"
+          },
+          "targetItemId": {
+            "type": "string"
+          },
+          "threadId": {
+            "type": "string"
+          },
+          "turnId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "review",
+          "targetItemId",
+          "threadId",
+          "turnId"
+        ],
+        "title": "ItemGuardianApprovalReviewStartedNotification",
+        "type": "object"
+      },
       "ItemStartedNotification": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "properties": {
@@ -8946,6 +9566,17 @@
               }
             ]
           },
+          "approvals_reviewer": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "[UNSTABLE] Optional profile-level override for where approval requests are routed for review. If omitted, the enclosing config default is used."
+          },
           "chatgpt_base_url": {
             "type": [
               "string",
@@ -11201,6 +11832,17 @@
               }
             ]
           },
+          "approvalsReviewer": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+          },
           "baseInstructions": {
             "type": [
               "string",
@@ -11285,6 +11927,14 @@
           "approvalPolicy": {
             "$ref": "#/definitions/v2/AskForApproval"
           },
+          "approvalsReviewer": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              }
+            ],
+            "description": "Reviewer currently used for approval requests on this thread."
+          },
           "cwd": {
             "type": "string"
           },
@@ -11323,6 +11973,7 @@
         },
         "required": [
           "approvalPolicy",
+          "approvalsReviewer",
           "cwd",
           "model",
           "modelProvider",
@@ -12319,6 +12970,17 @@
               }
             ]
           },
+          "approvalsReviewer": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+          },
           "baseInstructions": {
             "type": [
               "string",
@@ -12410,6 +13072,14 @@
           "approvalPolicy": {
             "$ref": "#/definitions/v2/AskForApproval"
           },
+          "approvalsReviewer": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              }
+            ],
+            "description": "Reviewer currently used for approval requests on this thread."
+          },
           "cwd": {
             "type": "string"
           },
@@ -12448,6 +13118,7 @@
         },
         "required": [
           "approvalPolicy",
+          "approvalsReviewer",
           "cwd",
           "model",
           "modelProvider",
@@ -12552,6 +13223,17 @@
               }
             ]
           },
+          "approvalsReviewer": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+          },
           "baseInstructions": {
             "type": [
               "string",
@@ -12648,6 +13330,14 @@
           "approvalPolicy": {
             "$ref": "#/definitions/v2/AskForApproval"
           },
+          "approvalsReviewer": {
+            "allOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              }
+            ],
+            "description": "Reviewer currently used for approval requests on this thread."
+          },
           "cwd": {
             "type": "string"
           },
@@ -12686,6 +13376,7 @@
         },
         "required": [
           "approvalPolicy",
+          "approvalsReviewer",
           "cwd",
           "model",
           "modelProvider",
@@ -13195,6 +13886,17 @@
             ],
             "description": "Override the approval policy for this turn and subsequent turns."
           },
+          "approvalsReviewer": {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/v2/ApprovalsReviewer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Override where approval requests are routed for review on this turn and subsequent turns."
+          },
           "cwd": {
             "description": "Override the working directory for this turn and subsequent turns.",
             "type": [

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

@@ -532,6 +532,14 @@
     "AppToolsConfig": {
       "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"
+    },
     "AppsConfig": {
       "properties": {
         "_default": {
@@ -1258,6 +1266,174 @@
           "title": "App/listRequest",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/readFile"
+              ],
+              "title": "Fs/readFileRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/FsReadFileParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/readFileRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/writeFile"
+              ],
+              "title": "Fs/writeFileRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/FsWriteFileParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/writeFileRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/createDirectory"
+              ],
+              "title": "Fs/createDirectoryRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/FsCreateDirectoryParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/createDirectoryRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/getMetadata"
+              ],
+              "title": "Fs/getMetadataRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/FsGetMetadataParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/getMetadataRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/readDirectory"
+              ],
+              "title": "Fs/readDirectoryRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/FsReadDirectoryParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/readDirectoryRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/remove"
+              ],
+              "title": "Fs/removeRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/FsRemoveParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/removeRequest",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "id": {
+              "$ref": "#/definitions/RequestId"
+            },
+            "method": {
+              "enum": [
+                "fs/copy"
+              ],
+              "title": "Fs/copyRequestMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/FsCopyParams"
+            }
+          },
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "title": "Fs/copyRequest",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -2657,6 +2833,17 @@
             }
           ]
         },
+        "approvals_reviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "[UNSTABLE] Optional default for where approval requests are routed for review."
+        },
         "compact_prompt": {
           "type": [
             "string",
@@ -3832,6 +4019,290 @@
       ],
       "type": "string"
     },
+    "FsCopyParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Copy a file or directory tree on the host filesystem.",
+      "properties": {
+        "destinationPath": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute destination path."
+        },
+        "recursive": {
+          "description": "Required for directory copies; ignored for file copies.",
+          "type": "boolean"
+        },
+        "sourcePath": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute source path."
+        }
+      },
+      "required": [
+        "destinationPath",
+        "sourcePath"
+      ],
+      "title": "FsCopyParams",
+      "type": "object"
+    },
+    "FsCopyResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Successful response for `fs/copy`.",
+      "title": "FsCopyResponse",
+      "type": "object"
+    },
+    "FsCreateDirectoryParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Create a directory on the host filesystem.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute directory path to create."
+        },
+        "recursive": {
+          "description": "Whether parent directories should also be created. Defaults to `true`.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FsCreateDirectoryParams",
+      "type": "object"
+    },
+    "FsCreateDirectoryResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Successful response for `fs/createDirectory`.",
+      "title": "FsCreateDirectoryResponse",
+      "type": "object"
+    },
+    "FsGetMetadataParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Request metadata for an absolute path.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to inspect."
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FsGetMetadataParams",
+      "type": "object"
+    },
+    "FsGetMetadataResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Metadata returned by `fs/getMetadata`.",
+      "properties": {
+        "createdAtMs": {
+          "description": "File creation time in Unix milliseconds when available, otherwise `0`.",
+          "format": "int64",
+          "type": "integer"
+        },
+        "isDirectory": {
+          "description": "Whether the path currently resolves to a directory.",
+          "type": "boolean"
+        },
+        "isFile": {
+          "description": "Whether the path currently resolves to a regular file.",
+          "type": "boolean"
+        },
+        "modifiedAtMs": {
+          "description": "File modification time in Unix milliseconds when available, otherwise `0`.",
+          "format": "int64",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "createdAtMs",
+        "isDirectory",
+        "isFile",
+        "modifiedAtMs"
+      ],
+      "title": "FsGetMetadataResponse",
+      "type": "object"
+    },
+    "FsReadDirectoryEntry": {
+      "description": "A directory entry returned by `fs/readDirectory`.",
+      "properties": {
+        "fileName": {
+          "description": "Direct child entry name only, not an absolute or relative path.",
+          "type": "string"
+        },
+        "isDirectory": {
+          "description": "Whether this entry resolves to a directory.",
+          "type": "boolean"
+        },
+        "isFile": {
+          "description": "Whether this entry resolves to a regular file.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "fileName",
+        "isDirectory",
+        "isFile"
+      ],
+      "type": "object"
+    },
+    "FsReadDirectoryParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "List direct child names for a directory.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute directory path to read."
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FsReadDirectoryParams",
+      "type": "object"
+    },
+    "FsReadDirectoryResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Directory entries returned by `fs/readDirectory`.",
+      "properties": {
+        "entries": {
+          "description": "Direct child entries in the requested directory.",
+          "items": {
+            "$ref": "#/definitions/FsReadDirectoryEntry"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "entries"
+      ],
+      "title": "FsReadDirectoryResponse",
+      "type": "object"
+    },
+    "FsReadFileParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Read a file from the host filesystem.",
+      "properties": {
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to read."
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FsReadFileParams",
+      "type": "object"
+    },
+    "FsReadFileResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Base64-encoded file contents returned by `fs/readFile`.",
+      "properties": {
+        "dataBase64": {
+          "description": "File contents encoded as base64.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "dataBase64"
+      ],
+      "title": "FsReadFileResponse",
+      "type": "object"
+    },
+    "FsRemoveParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Remove a file or directory tree from the host filesystem.",
+      "properties": {
+        "force": {
+          "description": "Whether missing paths should be ignored. Defaults to `true`.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to remove."
+        },
+        "recursive": {
+          "description": "Whether directory removal should recurse. Defaults to `true`.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FsRemoveParams",
+      "type": "object"
+    },
+    "FsRemoveResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Successful response for `fs/remove`.",
+      "title": "FsRemoveResponse",
+      "type": "object"
+    },
+    "FsWriteFileParams": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Write a file on the host filesystem.",
+      "properties": {
+        "dataBase64": {
+          "description": "File contents encoded as base64.",
+          "type": "string"
+        },
+        "path": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AbsolutePathBuf"
+            }
+          ],
+          "description": "Absolute path to write."
+        }
+      },
+      "required": [
+        "dataBase64",
+        "path"
+      ],
+      "title": "FsWriteFileParams",
+      "type": "object"
+    },
+    "FsWriteFileResponse": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "Successful response for `fs/writeFile`.",
+      "title": "FsWriteFileResponse",
+      "type": "object"
+    },
     "FunctionCallOutputBody": {
       "anyOf": [
         {
@@ -4136,6 +4607,61 @@
       },
       "type": "object"
     },
+    "GuardianApprovalReview": {
+      "description": "[UNSTABLE] Temporary guardian approval review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+      "properties": {
+        "rationale": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "riskLevel": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/GuardianRiskLevel"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "riskScore": {
+          "format": "uint8",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "status": {
+          "$ref": "#/definitions/GuardianApprovalReviewStatus"
+        }
+      },
+      "required": [
+        "status"
+      ],
+      "type": "object"
+    },
+    "GuardianApprovalReviewStatus": {
+      "description": "[UNSTABLE] Lifecycle state for a guardian approval review.",
+      "enum": [
+        "inProgress",
+        "approved",
+        "denied",
+        "aborted"
+      ],
+      "type": "string"
+    },
+    "GuardianRiskLevel": {
+      "description": "[UNSTABLE] Risk level assigned by guardian approval review.",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "type": "string"
+    },
     "HazelnutScope": {
       "enum": [
         "example",
@@ -4420,6 +4946,60 @@
       "title": "ItemCompletedNotification",
       "type": "object"
     },
+    "ItemGuardianApprovalReviewCompletedNotification": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+      "properties": {
+        "action": true,
+        "review": {
+          "$ref": "#/definitions/GuardianApprovalReview"
+        },
+        "targetItemId": {
+          "type": "string"
+        },
+        "threadId": {
+          "type": "string"
+        },
+        "turnId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "review",
+        "targetItemId",
+        "threadId",
+        "turnId"
+      ],
+      "title": "ItemGuardianApprovalReviewCompletedNotification",
+      "type": "object"
+    },
+    "ItemGuardianApprovalReviewStartedNotification": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+      "properties": {
+        "action": true,
+        "review": {
+          "$ref": "#/definitions/GuardianApprovalReview"
+        },
+        "targetItemId": {
+          "type": "string"
+        },
+        "threadId": {
+          "type": "string"
+        },
+        "turnId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "review",
+        "targetItemId",
+        "threadId",
+        "turnId"
+      ],
+      "title": "ItemGuardianApprovalReviewStartedNotification",
+      "type": "object"
+    },
     "ItemStartedNotification": {
       "$schema": "http://json-schema.org/draft-07/schema#",
       "properties": {
@@ -5731,6 +6311,17 @@
             }
           ]
         },
+        "approvals_reviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "[UNSTABLE] Optional profile-level override for where approval requests are routed for review. If omitted, the enclosing config default is used."
+        },
         "chatgpt_base_url": {
           "type": [
             "string",
@@ -7479,6 +8070,46 @@
           "title": "Item/startedNotification",
           "type": "object"
         },
+        {
+          "properties": {
+            "method": {
+              "enum": [
+                "item/autoApprovalReview/started"
+              ],
+              "title": "Item/autoApprovalReview/startedNotificationMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/ItemGuardianApprovalReviewStartedNotification"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "title": "Item/autoApprovalReview/startedNotification",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "method": {
+              "enum": [
+                "item/autoApprovalReview/completed"
+              ],
+              "title": "Item/autoApprovalReview/completedNotificationMethod",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/definitions/ItemGuardianApprovalReviewCompletedNotification"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "title": "Item/autoApprovalReview/completedNotification",
+          "type": "object"
+        },
         {
           "properties": {
             "method": {
@@ -8918,6 +9549,17 @@
             }
           ]
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+        },
         "baseInstructions": {
           "type": [
             "string",
@@ -9002,6 +9644,14 @@
         "approvalPolicy": {
           "$ref": "#/definitions/AskForApproval"
         },
+        "approvalsReviewer": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            }
+          ],
+          "description": "Reviewer currently used for approval requests on this thread."
+        },
         "cwd": {
           "type": "string"
         },
@@ -9040,6 +9690,7 @@
       },
       "required": [
         "approvalPolicy",
+        "approvalsReviewer",
         "cwd",
         "model",
         "modelProvider",
@@ -10036,6 +10687,17 @@
             }
           ]
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+        },
         "baseInstructions": {
           "type": [
             "string",
@@ -10127,6 +10789,14 @@
         "approvalPolicy": {
           "$ref": "#/definitions/AskForApproval"
         },
+        "approvalsReviewer": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            }
+          ],
+          "description": "Reviewer currently used for approval requests on this thread."
+        },
         "cwd": {
           "type": "string"
         },
@@ -10165,6 +10835,7 @@
       },
       "required": [
         "approvalPolicy",
+        "approvalsReviewer",
         "cwd",
         "model",
         "modelProvider",
@@ -10269,6 +10940,17 @@
             }
           ]
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+        },
         "baseInstructions": {
           "type": [
             "string",
@@ -10365,6 +11047,14 @@
         "approvalPolicy": {
           "$ref": "#/definitions/AskForApproval"
         },
+        "approvalsReviewer": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            }
+          ],
+          "description": "Reviewer currently used for approval requests on this thread."
+        },
         "cwd": {
           "type": "string"
         },
@@ -10403,6 +11093,7 @@
       },
       "required": [
         "approvalPolicy",
+        "approvalsReviewer",
         "cwd",
         "model",
         "modelProvider",
@@ -10912,6 +11603,17 @@
           ],
           "description": "Override the approval policy for this turn and subsequent turns."
         },
+        "approvalsReviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Override where approval requests are routed for review on this turn and subsequent turns."
+        },
         "cwd": {
           "description": "Override the working directory for this turn and subsequent turns.",
           "type": [

codex-rs/app-server-protocol/schema/json/v2/ConfigReadResponse.json

@@ -96,6 +96,14 @@
     "AppToolsConfig": {
       "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"
+    },
     "AppsConfig": {
       "properties": {
         "_default": {
@@ -202,6 +210,17 @@
             }
           ]
         },
+        "approvals_reviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "[UNSTABLE] Optional default for where approval requests are routed for review."
+        },
         "compact_prompt": {
           "type": [
             "string",
@@ -578,6 +597,17 @@
             }
           ]
         },
+        "approvals_reviewer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ApprovalsReviewer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "[UNSTABLE] Optional profile-level override for where approval requests are routed for review. If omitted, the enclosing config default is used."
+        },
         "chatgpt_base_url": {
           "type": [
             "string",

codex-rs/app-server-protocol/schema/json/v2/FsCopyParams.json

@@ -0,0 +1,38 @@
+{
+  "$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"
+    }
+  },
+  "description": "Copy a file or directory tree on the host filesystem.",
+  "properties": {
+    "destinationPath": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute destination path."
+    },
+    "recursive": {
+      "description": "Required for directory copies; ignored for file copies.",
+      "type": "boolean"
+    },
+    "sourcePath": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute source path."
+    }
+  },
+  "required": [
+    "destinationPath",
+    "sourcePath"
+  ],
+  "title": "FsCopyParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsCopyResponse.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Successful response for `fs/copy`.",
+  "title": "FsCopyResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsCreateDirectoryParams.json

@@ -0,0 +1,32 @@
+{
+  "$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"
+    }
+  },
+  "description": "Create a directory on the host filesystem.",
+  "properties": {
+    "path": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute directory path to create."
+    },
+    "recursive": {
+      "description": "Whether parent directories should also be created. Defaults to `true`.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "path"
+  ],
+  "title": "FsCreateDirectoryParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsCreateDirectoryResponse.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Successful response for `fs/createDirectory`.",
+  "title": "FsCreateDirectoryResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsGetMetadataParams.json

@@ -0,0 +1,25 @@
+{
+  "$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"
+    }
+  },
+  "description": "Request metadata for an absolute path.",
+  "properties": {
+    "path": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute path to inspect."
+    }
+  },
+  "required": [
+    "path"
+  ],
+  "title": "FsGetMetadataParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsGetMetadataResponse.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Metadata returned by `fs/getMetadata`.",
+  "properties": {
+    "createdAtMs": {
+      "description": "File creation time in Unix milliseconds when available, otherwise `0`.",
+      "format": "int64",
+      "type": "integer"
+    },
+    "isDirectory": {
+      "description": "Whether the path currently resolves to a directory.",
+      "type": "boolean"
+    },
+    "isFile": {
+      "description": "Whether the path currently resolves to a regular file.",
+      "type": "boolean"
+    },
+    "modifiedAtMs": {
+      "description": "File modification time in Unix milliseconds when available, otherwise `0`.",
+      "format": "int64",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "createdAtMs",
+    "isDirectory",
+    "isFile",
+    "modifiedAtMs"
+  ],
+  "title": "FsGetMetadataResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsReadDirectoryParams.json

@@ -0,0 +1,25 @@
+{
+  "$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"
+    }
+  },
+  "description": "List direct child names for a directory.",
+  "properties": {
+    "path": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute directory path to read."
+    }
+  },
+  "required": [
+    "path"
+  ],
+  "title": "FsReadDirectoryParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsReadDirectoryResponse.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "FsReadDirectoryEntry": {
+      "description": "A directory entry returned by `fs/readDirectory`.",
+      "properties": {
+        "fileName": {
+          "description": "Direct child entry name only, not an absolute or relative path.",
+          "type": "string"
+        },
+        "isDirectory": {
+          "description": "Whether this entry resolves to a directory.",
+          "type": "boolean"
+        },
+        "isFile": {
+          "description": "Whether this entry resolves to a regular file.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "fileName",
+        "isDirectory",
+        "isFile"
+      ],
+      "type": "object"
+    }
+  },
+  "description": "Directory entries returned by `fs/readDirectory`.",
+  "properties": {
+    "entries": {
+      "description": "Direct child entries in the requested directory.",
+      "items": {
+        "$ref": "#/definitions/FsReadDirectoryEntry"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "entries"
+  ],
+  "title": "FsReadDirectoryResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsReadFileParams.json

@@ -0,0 +1,25 @@
+{
+  "$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"
+    }
+  },
+  "description": "Read a file from the host filesystem.",
+  "properties": {
+    "path": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute path to read."
+    }
+  },
+  "required": [
+    "path"
+  ],
+  "title": "FsReadFileParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsReadFileResponse.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Base64-encoded file contents returned by `fs/readFile`.",
+  "properties": {
+    "dataBase64": {
+      "description": "File contents encoded as base64.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "dataBase64"
+  ],
+  "title": "FsReadFileResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsRemoveParams.json

@@ -0,0 +1,39 @@
+{
+  "$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"
+    }
+  },
+  "description": "Remove a file or directory tree from the host filesystem.",
+  "properties": {
+    "force": {
+      "description": "Whether missing paths should be ignored. Defaults to `true`.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "path": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute path to remove."
+    },
+    "recursive": {
+      "description": "Whether directory removal should recurse. Defaults to `true`.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "path"
+  ],
+  "title": "FsRemoveParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsRemoveResponse.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Successful response for `fs/remove`.",
+  "title": "FsRemoveResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsWriteFileParams.json

@@ -0,0 +1,30 @@
+{
+  "$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"
+    }
+  },
+  "description": "Write a file on the host filesystem.",
+  "properties": {
+    "dataBase64": {
+      "description": "File contents encoded as base64.",
+      "type": "string"
+    },
+    "path": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/AbsolutePathBuf"
+        }
+      ],
+      "description": "Absolute path to write."
+    }
+  },
+  "required": [
+    "dataBase64",
+    "path"
+  ],
+  "title": "FsWriteFileParams",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/FsWriteFileResponse.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Successful response for `fs/writeFile`.",
+  "title": "FsWriteFileResponse",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/ItemGuardianApprovalReviewCompletedNotification.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "GuardianApprovalReview": {
+      "description": "[UNSTABLE] Temporary guardian approval review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+      "properties": {
+        "rationale": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "riskLevel": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/GuardianRiskLevel"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "riskScore": {
+          "format": "uint8",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "status": {
+          "$ref": "#/definitions/GuardianApprovalReviewStatus"
+        }
+      },
+      "required": [
+        "status"
+      ],
+      "type": "object"
+    },
+    "GuardianApprovalReviewStatus": {
+      "description": "[UNSTABLE] Lifecycle state for a guardian approval review.",
+      "enum": [
+        "inProgress",
+        "approved",
+        "denied",
+        "aborted"
+      ],
+      "type": "string"
+    },
+    "GuardianRiskLevel": {
+      "description": "[UNSTABLE] Risk level assigned by guardian approval review.",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "type": "string"
+    }
+  },
+  "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+  "properties": {
+    "action": true,
+    "review": {
+      "$ref": "#/definitions/GuardianApprovalReview"
+    },
+    "targetItemId": {
+      "type": "string"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "review",
+    "targetItemId",
+    "threadId",
+    "turnId"
+  ],
+  "title": "ItemGuardianApprovalReviewCompletedNotification",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/ItemGuardianApprovalReviewStartedNotification.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "GuardianApprovalReview": {
+      "description": "[UNSTABLE] Temporary guardian approval review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+      "properties": {
+        "rationale": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "riskLevel": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/GuardianRiskLevel"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "riskScore": {
+          "format": "uint8",
+          "minimum": 0.0,
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "status": {
+          "$ref": "#/definitions/GuardianApprovalReviewStatus"
+        }
+      },
+      "required": [
+        "status"
+      ],
+      "type": "object"
+    },
+    "GuardianApprovalReviewStatus": {
+      "description": "[UNSTABLE] Lifecycle state for a guardian approval review.",
+      "enum": [
+        "inProgress",
+        "approved",
+        "denied",
+        "aborted"
+      ],
+      "type": "string"
+    },
+    "GuardianRiskLevel": {
+      "description": "[UNSTABLE] Risk level assigned by guardian approval review.",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "type": "string"
+    }
+  },
+  "description": "[UNSTABLE] Temporary notification payload for guardian automatic approval review. This shape is expected to change soon.\n\nTODO(ccunningham): Attach guardian review state to the reviewed tool item's lifecycle instead of sending separate standalone review notifications so the app-server API can persist and replay review state via `thread/read`.",
+  "properties": {
+    "action": true,
+    "review": {
+      "$ref": "#/definitions/GuardianApprovalReview"
+    },
+    "targetItemId": {
+      "type": "string"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "review",
+    "targetItemId",
+    "threadId",
+    "turnId"
+  ],
+  "title": "ItemGuardianApprovalReviewStartedNotification",
+  "type": "object"
+}

codex-rs/app-server-protocol/schema/json/v2/ThreadForkParams.json

@@ -1,6 +1,14 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "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": [
         {
@@ -79,6 +87,17 @@
         }
       ]
     },
+    "approvalsReviewer": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+    },
     "baseInstructions": {
       "type": [
         "string",

codex-rs/app-server-protocol/schema/json/v2/ThreadForkResponse.json

@@ -5,6 +5,14 @@
       "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": [
         {
@@ -1955,6 +1963,14 @@
     "approvalPolicy": {
       "$ref": "#/definitions/AskForApproval"
     },
+    "approvalsReviewer": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        }
+      ],
+      "description": "Reviewer currently used for approval requests on this thread."
+    },
     "cwd": {
       "type": "string"
     },
@@ -1993,6 +2009,7 @@
   },
   "required": [
     "approvalPolicy",
+    "approvalsReviewer",
     "cwd",
     "model",
     "modelProvider",

codex-rs/app-server-protocol/schema/json/v2/ThreadResumeParams.json

@@ -1,6 +1,14 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "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": [
         {
@@ -1002,6 +1010,17 @@
         }
       ]
     },
+    "approvalsReviewer": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+    },
     "baseInstructions": {
       "type": [
         "string",

codex-rs/app-server-protocol/schema/json/v2/ThreadResumeResponse.json

@@ -5,6 +5,14 @@
       "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": [
         {
@@ -1955,6 +1963,14 @@
     "approvalPolicy": {
       "$ref": "#/definitions/AskForApproval"
     },
+    "approvalsReviewer": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        }
+      ],
+      "description": "Reviewer currently used for approval requests on this thread."
+    },
     "cwd": {
       "type": "string"
     },
@@ -1993,6 +2009,7 @@
   },
   "required": [
     "approvalPolicy",
+    "approvalsReviewer",
     "cwd",
     "model",
     "modelProvider",

codex-rs/app-server-protocol/schema/json/v2/ThreadStartParams.json

@@ -1,6 +1,14 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "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": [
         {
@@ -103,6 +111,17 @@
         }
       ]
     },
+    "approvalsReviewer": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Override where approval requests are routed for review on this thread and subsequent turns."
+    },
     "baseInstructions": {
       "type": [
         "string",

codex-rs/app-server-protocol/schema/json/v2/ThreadStartResponse.json

@@ -5,6 +5,14 @@
       "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": [
         {
@@ -1955,6 +1963,14 @@
     "approvalPolicy": {
       "$ref": "#/definitions/AskForApproval"
     },
+    "approvalsReviewer": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        }
+      ],
+      "description": "Reviewer currently used for approval requests on this thread."
+    },
     "cwd": {
       "type": "string"
     },
@@ -1993,6 +2009,7 @@
   },
   "required": [
     "approvalPolicy",
+    "approvalsReviewer",
     "cwd",
     "model",
     "modelProvider",

codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json

@@ -5,6 +5,14 @@
       "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": [
         {
@@ -502,6 +510,17 @@
       ],
       "description": "Override the approval policy for this turn and subsequent turns."
     },
+    "approvalsReviewer": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Override where approval requests are routed for review on this turn and subsequent turns."
+    },
     "cwd": {
       "description": "Override the working directory for this turn and subsequent turns.",
       "type": [

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

@@ -20,6 +20,13 @@ import type { ExperimentalFeatureListParams } from "./v2/ExperimentalFeatureList
 import type { ExternalAgentConfigDetectParams } from "./v2/ExternalAgentConfigDetectParams";
 import type { ExternalAgentConfigImportParams } from "./v2/ExternalAgentConfigImportParams";
 import type { FeedbackUploadParams } from "./v2/FeedbackUploadParams";
+import type { FsCopyParams } from "./v2/FsCopyParams";
+import type { FsCreateDirectoryParams } from "./v2/FsCreateDirectoryParams";
+import type { FsGetMetadataParams } from "./v2/FsGetMetadataParams";
+import type { FsReadDirectoryParams } from "./v2/FsReadDirectoryParams";
+import type { FsReadFileParams } from "./v2/FsReadFileParams";
+import type { FsRemoveParams } from "./v2/FsRemoveParams";
+import type { FsWriteFileParams } from "./v2/FsWriteFileParams";
 import type { GetAccountParams } from "./v2/GetAccountParams";
 import type { ListMcpServerStatusParams } from "./v2/ListMcpServerStatusParams";
 import type { LoginAccountParams } from "./v2/LoginAccountParams";
@@ -55,4 +62,4 @@ import type { WindowsSandboxSetupStartParams } from "./v2/WindowsSandboxSetupSta
 /**
  * Request from the client to the server.
  */
-export type ClientRequest ={ "method": "initialize", id: RequestId, params: InitializeParams, } | { "method": "thread/start", id: RequestId, params: ThreadStartParams, } | { "method": "thread/resume", id: RequestId, params: ThreadResumeParams, } | { "method": "thread/fork", id: RequestId, params: ThreadForkParams, } | { "method": "thread/archive", id: RequestId, params: ThreadArchiveParams, } | { "method": "thread/unsubscribe", id: RequestId, params: ThreadUnsubscribeParams, } | { "method": "thread/name/set", id: RequestId, params: ThreadSetNameParams, } | { "method": "thread/metadata/update", id: RequestId, params: ThreadMetadataUpdateParams, } | { "method": "thread/unarchive", id: RequestId, params: ThreadUnarchiveParams, } | { "method": "thread/compact/start", id: RequestId, params: ThreadCompactStartParams, } | { "method": "thread/rollback", id: RequestId, params: ThreadRollbackParams, } | { "method": "thread/list", id: RequestId, params: ThreadListParams, } | { "method": "thread/loaded/list", id: RequestId, params: ThreadLoadedListParams, } | { "method": "thread/read", id: RequestId, params: ThreadReadParams, } | { "method": "skills/list", id: RequestId, params: SkillsListParams, } | { "method": "plugin/list", id: RequestId, params: PluginListParams, } | { "method": "plugin/read", id: RequestId, params: PluginReadParams, } | { "method": "skills/remote/list", id: RequestId, params: SkillsRemoteReadParams, } | { "method": "skills/remote/export", id: RequestId, params: SkillsRemoteWriteParams, } | { "method": "app/list", id: RequestId, params: AppsListParams, } | { "method": "skills/config/write", id: RequestId, params: SkillsConfigWriteParams, } | { "method": "plugin/install", id: RequestId, params: PluginInstallParams, } | { "method": "plugin/uninstall", id: RequestId, params: PluginUninstallParams, } | { "method": "turn/start", id: RequestId, params: TurnStartParams, } | { "method": "turn/steer", id: RequestId, params: TurnSteerParams, } | { "method": "turn/interrupt", id: RequestId, params: TurnInterruptParams, } | { "method": "review/start", id: RequestId, params: ReviewStartParams, } | { "method": "model/list", id: RequestId, params: ModelListParams, } | { "method": "experimentalFeature/list", id: RequestId, params: ExperimentalFeatureListParams, } | { "method": "mcpServer/oauth/login", id: RequestId, params: McpServerOauthLoginParams, } | { "method": "config/mcpServer/reload", id: RequestId, params: undefined, } | { "method": "mcpServerStatus/list", id: RequestId, params: ListMcpServerStatusParams, } | { "method": "windowsSandbox/setupStart", id: RequestId, params: WindowsSandboxSetupStartParams, } | { "method": "account/login/start", id: RequestId, params: LoginAccountParams, } | { "method": "account/login/cancel", id: RequestId, params: CancelLoginAccountParams, } | { "method": "account/logout", id: RequestId, params: undefined, } | { "method": "account/rateLimits/read", id: RequestId, params: undefined, } | { "method": "feedback/upload", id: RequestId, params: FeedbackUploadParams, } | { "method": "command/exec", id: RequestId, params: CommandExecParams, } | { "method": "command/exec/write", id: RequestId, params: CommandExecWriteParams, } | { "method": "command/exec/terminate", id: RequestId, params: CommandExecTerminateParams, } | { "method": "command/exec/resize", id: RequestId, params: CommandExecResizeParams, } | { "method": "config/read", id: RequestId, params: ConfigReadParams, } | { "method": "externalAgentConfig/detect", id: RequestId, params: ExternalAgentConfigDetectParams, } | { "method": "externalAgentConfig/import", id: RequestId, params: ExternalAgentConfigImportParams, } | { "method": "config/value/write", id: RequestId, params: ConfigValueWriteParams, } | { "method": "config/batchWrite", id: RequestId, params: ConfigBatchWriteParams, } | { "method": "configRequirements/read", id: RequestId, params: undefined, } | { "method": "account/read", id: RequestId, params: GetAccountParams, } | { "method": "getConversationSummary", id: RequestId, params: GetConversationSummaryParams, } | { "method": "gitDiffToRemote", id: RequestId, params: GitDiffToRemoteParams, } | { "method": "getAuthStatus", id: RequestId, params: GetAuthStatusParams, } | { "method": "fuzzyFileSearch", id: RequestId, params: FuzzyFileSearchParams, };
+export type ClientRequest ={ "method": "initialize", id: RequestId, params: InitializeParams, } | { "method": "thread/start", id: RequestId, params: ThreadStartParams, } | { "method": "thread/resume", id: RequestId, params: ThreadResumeParams, } | { "method": "thread/fork", id: RequestId, params: ThreadForkParams, } | { "method": "thread/archive", id: RequestId, params: ThreadArchiveParams, } | { "method": "thread/unsubscribe", id: RequestId, params: ThreadUnsubscribeParams, } | { "method": "thread/name/set", id: RequestId, params: ThreadSetNameParams, } | { "method": "thread/metadata/update", id: RequestId, params: ThreadMetadataUpdateParams, } | { "method": "thread/unarchive", id: RequestId, params: ThreadUnarchiveParams, } | { "method": "thread/compact/start", id: RequestId, params: ThreadCompactStartParams, } | { "method": "thread/rollback", id: RequestId, params: ThreadRollbackParams, } | { "method": "thread/list", id: RequestId, params: ThreadListParams, } | { "method": "thread/loaded/list", id: RequestId, params: ThreadLoadedListParams, } | { "method": "thread/read", id: RequestId, params: ThreadReadParams, } | { "method": "skills/list", id: RequestId, params: SkillsListParams, } | { "method": "plugin/list", id: RequestId, params: PluginListParams, } | { "method": "plugin/read", id: RequestId, params: PluginReadParams, } | { "method": "skills/remote/list", id: RequestId, params: SkillsRemoteReadParams, } | { "method": "skills/remote/export", id: RequestId, params: SkillsRemoteWriteParams, } | { "method": "app/list", id: RequestId, params: AppsListParams, } | { "method": "fs/readFile", id: RequestId, params: FsReadFileParams, } | { "method": "fs/writeFile", id: RequestId, params: FsWriteFileParams, } | { "method": "fs/createDirectory", id: RequestId, params: FsCreateDirectoryParams, } | { "method": "fs/getMetadata", id: RequestId, params: FsGetMetadataParams, } | { "method": "fs/readDirectory", id: RequestId, params: FsReadDirectoryParams, } | { "method": "fs/remove", id: RequestId, params: FsRemoveParams, } | { "method": "fs/copy", id: RequestId, params: FsCopyParams, } | { "method": "skills/config/write", id: RequestId, params: SkillsConfigWriteParams, } | { "method": "plugin/install", id: RequestId, params: PluginInstallParams, } | { "method": "plugin/uninstall", id: RequestId, params: PluginUninstallParams, } | { "method": "turn/start", id: RequestId, params: TurnStartParams, } | { "method": "turn/steer", id: RequestId, params: TurnSteerParams, } | { "method": "turn/interrupt", id: RequestId, params: TurnInterruptParams, } | { "method": "review/start", id: RequestId, params: ReviewStartParams, } | { "method": "model/list", id: RequestId, params: ModelListParams, } | { "method": "experimentalFeature/list", id: RequestId, params: ExperimentalFeatureListParams, } | { "method": "mcpServer/oauth/login", id: RequestId, params: McpServerOauthLoginParams, } | { "method": "config/mcpServer/reload", id: RequestId, params: undefined, } | { "method": "mcpServerStatus/list", id: RequestId, params: ListMcpServerStatusParams, } | { "method": "windowsSandbox/setupStart", id: RequestId, params: WindowsSandboxSetupStartParams, } | { "method": "account/login/start", id: RequestId, params: LoginAccountParams, } | { "method": "account/login/cancel", id: RequestId, params: CancelLoginAccountParams, } | { "method": "account/logout", id: RequestId, params: undefined, } | { "method": "account/rateLimits/read", id: RequestId, params: undefined, } | { "method": "feedback/upload", id: RequestId, params: FeedbackUploadParams, } | { "method": "command/exec", id: RequestId, params: CommandExecParams, } | { "method": "command/exec/write", id: RequestId, params: CommandExecWriteParams, } | { "method": "command/exec/terminate", id: RequestId, params: CommandExecTerminateParams, } | { "method": "command/exec/resize", id: RequestId, params: CommandExecResizeParams, } | { "method": "config/read", id: RequestId, params: ConfigReadParams, } | { "method": "externalAgentConfig/detect", id: RequestId, params: ExternalAgentConfigDetectParams, } | { "method": "externalAgentConfig/import", id: RequestId, params: ExternalAgentConfigImportParams, } | { "method": "config/value/write", id: RequestId, params: ConfigValueWriteParams, } | { "method": "config/batchWrite", id: RequestId, params: ConfigBatchWriteParams, } | { "method": "configRequirements/read", id: RequestId, params: undefined, } | { "method": "account/read", id: RequestId, params: GetAccountParams, } | { "method": "getConversationSummary", id: RequestId, params: GetConversationSummaryParams, } | { "method": "gitDiffToRemote", id: RequestId, params: GitDiffToRemoteParams, } | { "method": "getAuthStatus", id: RequestId, params: GetAuthStatusParams, } | { "method": "fuzzyFileSearch", id: RequestId, params: FuzzyFileSearchParams, };

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

@@ -18,6 +18,8 @@ import type { FileChangeOutputDeltaNotification } from "./v2/FileChangeOutputDel
 import type { HookCompletedNotification } from "./v2/HookCompletedNotification";
 import type { HookStartedNotification } from "./v2/HookStartedNotification";
 import type { ItemCompletedNotification } from "./v2/ItemCompletedNotification";
+import type { ItemGuardianApprovalReviewCompletedNotification } from "./v2/ItemGuardianApprovalReviewCompletedNotification";
+import type { ItemGuardianApprovalReviewStartedNotification } from "./v2/ItemGuardianApprovalReviewStartedNotification";
 import type { ItemStartedNotification } from "./v2/ItemStartedNotification";
 import type { McpServerOauthLoginCompletedNotification } from "./v2/McpServerOauthLoginCompletedNotification";
 import type { McpToolCallProgressNotification } from "./v2/McpToolCallProgressNotification";
@@ -52,4 +54,4 @@ import type { WindowsWorldWritableWarningNotification } from "./v2/WindowsWorldW
 /**
  * Notification sent from the server to the client.
  */
-export type ServerNotification = { "method": "error", "params": ErrorNotification } | { "method": "thread/started", "params": ThreadStartedNotification } | { "method": "thread/status/changed", "params": ThreadStatusChangedNotification } | { "method": "thread/archived", "params": ThreadArchivedNotification } | { "method": "thread/unarchived", "params": ThreadUnarchivedNotification } | { "method": "thread/closed", "params": ThreadClosedNotification } | { "method": "skills/changed", "params": SkillsChangedNotification } | { "method": "thread/name/updated", "params": ThreadNameUpdatedNotification } | { "method": "thread/tokenUsage/updated", "params": ThreadTokenUsageUpdatedNotification } | { "method": "turn/started", "params": TurnStartedNotification } | { "method": "hook/started", "params": HookStartedNotification } | { "method": "turn/completed", "params": TurnCompletedNotification } | { "method": "hook/completed", "params": HookCompletedNotification } | { "method": "turn/diff/updated", "params": TurnDiffUpdatedNotification } | { "method": "turn/plan/updated", "params": TurnPlanUpdatedNotification } | { "method": "item/started", "params": ItemStartedNotification } | { "method": "item/completed", "params": ItemCompletedNotification } | { "method": "rawResponseItem/completed", "params": RawResponseItemCompletedNotification } | { "method": "item/agentMessage/delta", "params": AgentMessageDeltaNotification } | { "method": "item/plan/delta", "params": PlanDeltaNotification } | { "method": "command/exec/outputDelta", "params": CommandExecOutputDeltaNotification } | { "method": "item/commandExecution/outputDelta", "params": CommandExecutionOutputDeltaNotification } | { "method": "item/commandExecution/terminalInteraction", "params": TerminalInteractionNotification } | { "method": "item/fileChange/outputDelta", "params": FileChangeOutputDeltaNotification } | { "method": "serverRequest/resolved", "params": ServerRequestResolvedNotification } | { "method": "item/mcpToolCall/progress", "params": McpToolCallProgressNotification } | { "method": "mcpServer/oauthLogin/completed", "params": McpServerOauthLoginCompletedNotification } | { "method": "account/updated", "params": AccountUpdatedNotification } | { "method": "account/rateLimits/updated", "params": AccountRateLimitsUpdatedNotification } | { "method": "app/list/updated", "params": AppListUpdatedNotification } | { "method": "item/reasoning/summaryTextDelta", "params": ReasoningSummaryTextDeltaNotification } | { "method": "item/reasoning/summaryPartAdded", "params": ReasoningSummaryPartAddedNotification } | { "method": "item/reasoning/textDelta", "params": ReasoningTextDeltaNotification } | { "method": "thread/compacted", "params": ContextCompactedNotification } | { "method": "model/rerouted", "params": ModelReroutedNotification } | { "method": "deprecationNotice", "params": DeprecationNoticeNotification } | { "method": "configWarning", "params": ConfigWarningNotification } | { "method": "fuzzyFileSearch/sessionUpdated", "params": FuzzyFileSearchSessionUpdatedNotification } | { "method": "fuzzyFileSearch/sessionCompleted", "params": FuzzyFileSearchSessionCompletedNotification } | { "method": "thread/realtime/started", "params": ThreadRealtimeStartedNotification } | { "method": "thread/realtime/itemAdded", "params": ThreadRealtimeItemAddedNotification } | { "method": "thread/realtime/outputAudio/delta", "params": ThreadRealtimeOutputAudioDeltaNotification } | { "method": "thread/realtime/error", "params": ThreadRealtimeErrorNotification } | { "method": "thread/realtime/closed", "params": ThreadRealtimeClosedNotification } | { "method": "windows/worldWritableWarning", "params": WindowsWorldWritableWarningNotification } | { "method": "windowsSandbox/setupCompleted", "params": WindowsSandboxSetupCompletedNotification } | { "method": "account/login/completed", "params": AccountLoginCompletedNotification };
+export type ServerNotification = { "method": "error", "params": ErrorNotification } | { "method": "thread/started", "params": ThreadStartedNotification } | { "method": "thread/status/changed", "params": ThreadStatusChangedNotification } | { "method": "thread/archived", "params": ThreadArchivedNotification } | { "method": "thread/unarchived", "params": ThreadUnarchivedNotification } | { "method": "thread/closed", "params": ThreadClosedNotification } | { "method": "skills/changed", "params": SkillsChangedNotification } | { "method": "thread/name/updated", "params": ThreadNameUpdatedNotification } | { "method": "thread/tokenUsage/updated", "params": ThreadTokenUsageUpdatedNotification } | { "method": "turn/started", "params": TurnStartedNotification } | { "method": "hook/started", "params": HookStartedNotification } | { "method": "turn/completed", "params": TurnCompletedNotification } | { "method": "hook/completed", "params": HookCompletedNotification } | { "method": "turn/diff/updated", "params": TurnDiffUpdatedNotification } | { "method": "turn/plan/updated", "params": TurnPlanUpdatedNotification } | { "method": "item/started", "params": ItemStartedNotification } | { "method": "item/autoApprovalReview/started", "params": ItemGuardianApprovalReviewStartedNotification } | { "method": "item/autoApprovalReview/completed", "params": ItemGuardianApprovalReviewCompletedNotification } | { "method": "item/completed", "params": ItemCompletedNotification } | { "method": "rawResponseItem/completed", "params": RawResponseItemCompletedNotification } | { "method": "item/agentMessage/delta", "params": AgentMessageDeltaNotification } | { "method": "item/plan/delta", "params": PlanDeltaNotification } | { "method": "command/exec/outputDelta", "params": CommandExecOutputDeltaNotification } | { "method": "item/commandExecution/outputDelta", "params": CommandExecutionOutputDeltaNotification } | { "method": "item/commandExecution/terminalInteraction", "params": TerminalInteractionNotification } | { "method": "item/fileChange/outputDelta", "params": FileChangeOutputDeltaNotification } | { "method": "serverRequest/resolved", "params": ServerRequestResolvedNotification } | { "method": "item/mcpToolCall/progress", "params": McpToolCallProgressNotification } | { "method": "mcpServer/oauthLogin/completed", "params": McpServerOauthLoginCompletedNotification } | { "method": "account/updated", "params": AccountUpdatedNotification } | { "method": "account/rateLimits/updated", "params": AccountRateLimitsUpdatedNotification } | { "method": "app/list/updated", "params": AppListUpdatedNotification } | { "method": "item/reasoning/summaryTextDelta", "params": ReasoningSummaryTextDeltaNotification } | { "method": "item/reasoning/summaryPartAdded", "params": ReasoningSummaryPartAddedNotification } | { "method": "item/reasoning/textDelta", "params": ReasoningTextDeltaNotification } | { "method": "thread/compacted", "params": ContextCompactedNotification } | { "method": "model/rerouted", "params": ModelReroutedNotification } | { "method": "deprecationNotice", "params": DeprecationNoticeNotification } | { "method": "configWarning", "params": ConfigWarningNotification } | { "method": "fuzzyFileSearch/sessionUpdated", "params": FuzzyFileSearchSessionUpdatedNotification } | { "method": "fuzzyFileSearch/sessionCompleted", "params": FuzzyFileSearchSessionCompletedNotification } | { "method": "thread/realtime/started", "params": ThreadRealtimeStartedNotification } | { "method": "thread/realtime/itemAdded", "params": ThreadRealtimeItemAddedNotification } | { "method": "thread/realtime/outputAudio/delta", "params": ThreadRealtimeOutputAudioDeltaNotification } | { "method": "thread/realtime/error", "params": ThreadRealtimeErrorNotification } | { "method": "thread/realtime/closed", "params": ThreadRealtimeClosedNotification } | { "method": "windows/worldWritableWarning", "params": WindowsWorldWritableWarningNotification } | { "method": "windowsSandbox/setupCompleted", "params": WindowsSandboxSetupCompletedNotification } | { "method": "account/login/completed", "params": AccountLoginCompletedNotification };

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

@@ -0,0 +1,12 @@
+// 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.
+
+/**
+ * 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.
+ */
+export type ApprovalsReviewer = "user" | "guardian_subagent";

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

@@ -9,10 +9,15 @@ import type { Verbosity } from "../Verbosity";
 import type { WebSearchMode } from "../WebSearchMode";
 import type { JsonValue } from "../serde_json/JsonValue";
 import type { AnalyticsConfig } from "./AnalyticsConfig";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { ProfileV2 } from "./ProfileV2";
 import type { SandboxMode } from "./SandboxMode";
 import type { SandboxWorkspaceWrite } from "./SandboxWorkspaceWrite";
 import type { ToolsV2 } from "./ToolsV2";
 
-export type Config = {model: string | null, review_model: string | null, model_context_window: bigint | null, model_auto_compact_token_limit: bigint | null, model_provider: string | null, approval_policy: AskForApproval | null, sandbox_mode: SandboxMode | null, sandbox_workspace_write: SandboxWorkspaceWrite | null, forced_chatgpt_workspace_id: string | null, forced_login_method: ForcedLoginMethod | null, web_search: WebSearchMode | null, tools: ToolsV2 | null, profile: string | null, profiles: { [key in string]?: ProfileV2 }, instructions: string | null, developer_instructions: string | null, compact_prompt: string | null, model_reasoning_effort: ReasoningEffort | null, model_reasoning_summary: ReasoningSummary | null, model_verbosity: Verbosity | null, service_tier: ServiceTier | null, analytics: AnalyticsConfig | null} & ({ [key in string]?: number | string | boolean | Array<JsonValue> | { [key in string]?: JsonValue } | null });
+export type Config = {model: string | null, review_model: string | null, model_context_window: bigint | null, model_auto_compact_token_limit: bigint | null, model_provider: string | null, approval_policy: AskForApproval | null, /**
+ * [UNSTABLE] Optional default for where approval requests are routed for
+ * review.
+ */
+approvals_reviewer: ApprovalsReviewer | null, sandbox_mode: SandboxMode | null, sandbox_workspace_write: SandboxWorkspaceWrite | null, forced_chatgpt_workspace_id: string | null, forced_login_method: ForcedLoginMethod | null, web_search: WebSearchMode | null, tools: ToolsV2 | null, profile: string | null, profiles: { [key in string]?: ProfileV2 }, instructions: string | null, developer_instructions: string | null, compact_prompt: string | null, model_reasoning_effort: ReasoningEffort | null, model_reasoning_summary: ReasoningSummary | null, model_verbosity: Verbosity | null, service_tier: ServiceTier | null, analytics: AnalyticsConfig | null} & ({ [key in string]?: number | string | boolean | Array<JsonValue> | { [key in string]?: JsonValue } | null });

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

@@ -0,0 +1,21 @@
+// 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.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+/**
+ * Copy a file or directory tree on the host filesystem.
+ */
+export type FsCopyParams = { 
+/**
+ * Absolute source path.
+ */
+sourcePath: AbsolutePathBuf, 
+/**
+ * Absolute destination path.
+ */
+destinationPath: AbsolutePathBuf, 
+/**
+ * Required for directory copies; ignored for file copies.
+ */
+recursive?: boolean, };

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

@@ -0,0 +1,8 @@
+// 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.
+
+/**
+ * Successful response for `fs/copy`.
+ */
+export type FsCopyResponse = Record<string, never>;

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

@@ -0,0 +1,17 @@
+// 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.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+/**
+ * Create a directory on the host filesystem.
+ */
+export type FsCreateDirectoryParams = { 
+/**
+ * Absolute directory path to create.
+ */
+path: AbsolutePathBuf, 
+/**
+ * Whether parent directories should also be created. Defaults to `true`.
+ */
+recursive?: boolean | null, };

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

@@ -0,0 +1,8 @@
+// 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.
+
+/**
+ * Successful response for `fs/createDirectory`.
+ */
+export type FsCreateDirectoryResponse = Record<string, never>;

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

@@ -0,0 +1,13 @@
+// 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.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+/**
+ * Request metadata for an absolute path.
+ */
+export type FsGetMetadataParams = { 
+/**
+ * Absolute path to inspect.
+ */
+path: AbsolutePathBuf, };

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

@@ -0,0 +1,24 @@
+// 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.
+
+/**
+ * Metadata returned by `fs/getMetadata`.
+ */
+export type FsGetMetadataResponse = { 
+/**
+ * Whether the path currently resolves to a directory.
+ */
+isDirectory: boolean, 
+/**
+ * Whether the path currently resolves to a regular file.
+ */
+isFile: boolean, 
+/**
+ * File creation time in Unix milliseconds when available, otherwise `0`.
+ */
+createdAtMs: number, 
+/**
+ * File modification time in Unix milliseconds when available, otherwise `0`.
+ */
+modifiedAtMs: number, };

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

@@ -0,0 +1,20 @@
+// 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.
+
+/**
+ * A directory entry returned by `fs/readDirectory`.
+ */
+export type FsReadDirectoryEntry = { 
+/**
+ * Direct child entry name only, not an absolute or relative path.
+ */
+fileName: string, 
+/**
+ * Whether this entry resolves to a directory.
+ */
+isDirectory: boolean, 
+/**
+ * Whether this entry resolves to a regular file.
+ */
+isFile: boolean, };

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

@@ -0,0 +1,13 @@
+// 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.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+/**
+ * List direct child names for a directory.
+ */
+export type FsReadDirectoryParams = { 
+/**
+ * Absolute directory path to read.
+ */
+path: AbsolutePathBuf, };

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

@@ -0,0 +1,13 @@
+// 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.
+import type { FsReadDirectoryEntry } from "./FsReadDirectoryEntry";
+
+/**
+ * Directory entries returned by `fs/readDirectory`.
+ */
+export type FsReadDirectoryResponse = { 
+/**
+ * Direct child entries in the requested directory.
+ */
+entries: Array<FsReadDirectoryEntry>, };

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

@@ -0,0 +1,13 @@
+// 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.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+/**
+ * Read a file from the host filesystem.
+ */
+export type FsReadFileParams = { 
+/**
+ * Absolute path to read.
+ */
+path: AbsolutePathBuf, };

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

@@ -0,0 +1,12 @@
+// 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.
+
+/**
+ * Base64-encoded file contents returned by `fs/readFile`.
+ */
+export type FsReadFileResponse = { 
+/**
+ * File contents encoded as base64.
+ */
+dataBase64: string, };

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

@@ -0,0 +1,21 @@
+// 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.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+/**
+ * Remove a file or directory tree from the host filesystem.
+ */
+export type FsRemoveParams = { 
+/**
+ * Absolute path to remove.
+ */
+path: AbsolutePathBuf, 
+/**
+ * Whether directory removal should recurse. Defaults to `true`.
+ */
+recursive?: boolean | null, 
+/**
+ * Whether missing paths should be ignored. Defaults to `true`.
+ */
+force?: boolean | null, };

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

@@ -0,0 +1,8 @@
+// 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.
+
+/**
+ * Successful response for `fs/remove`.
+ */
+export type FsRemoveResponse = Record<string, never>;

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

@@ -0,0 +1,17 @@
+// 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.
+import type { AbsolutePathBuf } from "../AbsolutePathBuf";
+
+/**
+ * Write a file on the host filesystem.
+ */
+export type FsWriteFileParams = { 
+/**
+ * Absolute path to write.
+ */
+path: AbsolutePathBuf, 
+/**
+ * File contents encoded as base64.
+ */
+dataBase64: string, };

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

@@ -0,0 +1,8 @@
+// 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.
+
+/**
+ * Successful response for `fs/writeFile`.
+ */
+export type FsWriteFileResponse = Record<string, never>;

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

@@ -0,0 +1,12 @@
+// 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.
+import type { GuardianApprovalReviewStatus } from "./GuardianApprovalReviewStatus";
+import type { GuardianRiskLevel } from "./GuardianRiskLevel";
+
+/**
+ * [UNSTABLE] Temporary guardian approval review payload used by
+ * `item/autoApprovalReview/*` notifications. This shape is expected to change
+ * soon.
+ */
+export type GuardianApprovalReview = { status: GuardianApprovalReviewStatus, riskScore: number | null, riskLevel: GuardianRiskLevel | null, rationale: string | null, };

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

@@ -0,0 +1,8 @@
+// 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.
+
+/**
+ * [UNSTABLE] Lifecycle state for a guardian approval review.
+ */
+export type GuardianApprovalReviewStatus = "inProgress" | "approved" | "denied" | "aborted";

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

@@ -0,0 +1,8 @@
+// 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.
+
+/**
+ * [UNSTABLE] Risk level assigned by guardian approval review.
+ */
+export type GuardianRiskLevel = "low" | "medium" | "high";

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

@@ -0,0 +1,15 @@
+// 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.
+import type { JsonValue } from "../serde_json/JsonValue";
+import type { GuardianApprovalReview } from "./GuardianApprovalReview";
+
+/**
+ * [UNSTABLE] Temporary notification payload for guardian automatic approval
+ * review. This shape is expected to change soon.
+ *
+ * TODO(ccunningham): Attach guardian review state to the reviewed tool item's
+ * lifecycle instead of sending separate standalone review notifications so the
+ * app-server API can persist and replay review state via `thread/read`.
+ */
+export type ItemGuardianApprovalReviewCompletedNotification = { threadId: string, turnId: string, targetItemId: string, review: GuardianApprovalReview, action: JsonValue | null, };

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

@@ -0,0 +1,15 @@
+// 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.
+import type { JsonValue } from "../serde_json/JsonValue";
+import type { GuardianApprovalReview } from "./GuardianApprovalReview";
+
+/**
+ * [UNSTABLE] Temporary notification payload for guardian automatic approval
+ * review. This shape is expected to change soon.
+ *
+ * TODO(ccunningham): Attach guardian review state to the reviewed tool item's
+ * lifecycle instead of sending separate standalone review notifications so the
+ * app-server API can persist and replay review state via `thread/read`.
+ */
+export type ItemGuardianApprovalReviewStartedNotification = { threadId: string, turnId: string, targetItemId: string, review: GuardianApprovalReview, action: JsonValue | null, };

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

@@ -7,7 +7,13 @@ import type { ServiceTier } from "../ServiceTier";
 import type { Verbosity } from "../Verbosity";
 import type { WebSearchMode } from "../WebSearchMode";
 import type { JsonValue } from "../serde_json/JsonValue";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { ToolsV2 } from "./ToolsV2";
 
-export type ProfileV2 = { model: string | null, model_provider: string | null, approval_policy: AskForApproval | null, service_tier: ServiceTier | null, model_reasoning_effort: ReasoningEffort | null, model_reasoning_summary: ReasoningSummary | null, model_verbosity: Verbosity | null, web_search: WebSearchMode | null, tools: ToolsV2 | null, chatgpt_base_url: string | null, } & ({ [key in string]?: number | string | boolean | Array<JsonValue> | { [key in string]?: JsonValue } | null });
+export type ProfileV2 = {model: string | null, model_provider: string | null, approval_policy: AskForApproval | null, /**
+ * [UNSTABLE] Optional profile-level override for where approval requests
+ * are routed for review. If omitted, the enclosing config default is
+ * used.
+ */
+approvals_reviewer: ApprovalsReviewer | null, service_tier: ServiceTier | null, model_reasoning_effort: ReasoningEffort | null, model_reasoning_summary: ReasoningSummary | null, model_verbosity: Verbosity | null, web_search: WebSearchMode | null, tools: ToolsV2 | null, chatgpt_base_url: string | null} & ({ [key in string]?: number | string | boolean | Array<JsonValue> | { [key in string]?: JsonValue } | null });

codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.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 { ServiceTier } from "../ServiceTier";
 import type { JsonValue } from "../serde_json/JsonValue";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { SandboxMode } from "./SandboxMode";
 
@@ -22,7 +23,11 @@ export type ThreadForkParams = {threadId: string, /**
 path?: string | null, /**
  * Configuration overrides for the forked thread, if any.
  */
-model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier | null | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, ephemeral?: boolean, /**
+model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier | null | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, /**
+ * Override where approval requests are routed for review on this thread
+ * and subsequent turns.
+ */
+approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, ephemeral?: boolean, /**
  * If true, persist additional rollout EventMsg variants required to
  * reconstruct a richer thread history on subsequent resume/fork/read.
  */

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

@@ -3,8 +3,13 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 import type { ReasoningEffort } from "../ReasoningEffort";
 import type { ServiceTier } from "../ServiceTier";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { SandboxPolicy } from "./SandboxPolicy";
 import type { Thread } from "./Thread";
 
-export type ThreadForkResponse = { thread: Thread, model: string, modelProvider: string, serviceTier: ServiceTier | null, cwd: string, approvalPolicy: AskForApproval, sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null, };
+export type ThreadForkResponse = { thread: Thread, model: string, modelProvider: string, serviceTier: ServiceTier | null, cwd: string, approvalPolicy: AskForApproval, 
+/**
+ * Reviewer currently used for approval requests on this thread.
+ */
+approvalsReviewer: ApprovalsReviewer, sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null, };

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

@@ -5,6 +5,7 @@ import type { Personality } from "../Personality";
 import type { ResponseItem } from "../ResponseItem";
 import type { ServiceTier } from "../ServiceTier";
 import type { JsonValue } from "../serde_json/JsonValue";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { SandboxMode } from "./SandboxMode";
 
@@ -31,7 +32,11 @@ history?: Array<ResponseItem> | null, /**
 path?: string | null, /**
  * Configuration overrides for the resumed thread, if any.
  */
-model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier | null | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, /**
+model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier | null | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, /**
+ * Override where approval requests are routed for review on this thread
+ * and subsequent turns.
+ */
+approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, /**
  * If true, persist additional rollout EventMsg variants required to
  * reconstruct a richer thread history on subsequent resume/fork/read.
  */

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

@@ -3,8 +3,13 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 import type { ReasoningEffort } from "../ReasoningEffort";
 import type { ServiceTier } from "../ServiceTier";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { SandboxPolicy } from "./SandboxPolicy";
 import type { Thread } from "./Thread";
 
-export type ThreadResumeResponse = { thread: Thread, model: string, modelProvider: string, serviceTier: ServiceTier | null, cwd: string, approvalPolicy: AskForApproval, sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null, };
+export type ThreadResumeResponse = { thread: Thread, model: string, modelProvider: string, serviceTier: ServiceTier | null, cwd: string, approvalPolicy: AskForApproval, 
+/**
+ * Reviewer currently used for approval requests on this thread.
+ */
+approvalsReviewer: ApprovalsReviewer, sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null, };

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

@@ -4,10 +4,15 @@
 import type { Personality } from "../Personality";
 import type { ServiceTier } from "../ServiceTier";
 import type { JsonValue } from "../serde_json/JsonValue";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { SandboxMode } from "./SandboxMode";
 
-export type ThreadStartParams = {model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier | null | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, serviceName?: string | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, ephemeral?: boolean | null, /**
+export type ThreadStartParams = {model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier | null | null, cwd?: string | null, approvalPolicy?: AskForApproval | null, /**
+ * Override where approval requests are routed for review on this thread
+ * and subsequent turns.
+ */
+approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, serviceName?: string | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, ephemeral?: boolean | null, /**
  * If true, opt into emitting raw Responses API items on the event stream.
  * This is for internal use only (e.g. Codex Cloud).
  */

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

@@ -3,8 +3,13 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 import type { ReasoningEffort } from "../ReasoningEffort";
 import type { ServiceTier } from "../ServiceTier";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { SandboxPolicy } from "./SandboxPolicy";
 import type { Thread } from "./Thread";
 
-export type ThreadStartResponse = { thread: Thread, model: string, modelProvider: string, serviceTier: ServiceTier | null, cwd: string, approvalPolicy: AskForApproval, sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null, };
+export type ThreadStartResponse = { thread: Thread, model: string, modelProvider: string, serviceTier: ServiceTier | null, cwd: string, approvalPolicy: AskForApproval, 
+/**
+ * Reviewer currently used for approval requests on this thread.
+ */
+approvalsReviewer: ApprovalsReviewer, sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null, };

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

@@ -7,6 +7,7 @@ import type { ReasoningEffort } from "../ReasoningEffort";
 import type { ReasoningSummary } from "../ReasoningSummary";
 import type { ServiceTier } from "../ServiceTier";
 import type { JsonValue } from "../serde_json/JsonValue";
+import type { ApprovalsReviewer } from "./ApprovalsReviewer";
 import type { AskForApproval } from "./AskForApproval";
 import type { SandboxPolicy } from "./SandboxPolicy";
 import type { UserInput } from "./UserInput";
@@ -18,6 +19,10 @@ cwd?: string | null, /**
  * Override the approval policy for this turn and subsequent turns.
  */
 approvalPolicy?: AskForApproval | null, /**
+ * Override where approval requests are routed for review on this turn and
+ * subsequent turns.
+ */
+approvalsReviewer?: ApprovalsReviewer | null, /**
  * Override the sandbox policy for this turn and subsequent turns.
  */
 sandboxPolicy?: SandboxPolicy | null, /**

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

@@ -19,6 +19,7 @@ export type { AppScreenshot } from "./AppScreenshot";
 export type { AppSummary } from "./AppSummary";
 export type { AppToolApproval } from "./AppToolApproval";
 export type { AppToolsConfig } from "./AppToolsConfig";
+export type { ApprovalsReviewer } from "./ApprovalsReviewer";
 export type { AppsConfig } from "./AppsConfig";
 export type { AppsDefaultConfig } from "./AppsDefaultConfig";
 export type { AppsListParams } from "./AppsListParams";
@@ -95,12 +96,30 @@ export type { FileChangeOutputDeltaNotification } from "./FileChangeOutputDeltaN
 export type { FileChangeRequestApprovalParams } from "./FileChangeRequestApprovalParams";
 export type { FileChangeRequestApprovalResponse } from "./FileChangeRequestApprovalResponse";
 export type { FileUpdateChange } from "./FileUpdateChange";
+export type { FsCopyParams } from "./FsCopyParams";
+export type { FsCopyResponse } from "./FsCopyResponse";
+export type { FsCreateDirectoryParams } from "./FsCreateDirectoryParams";
+export type { FsCreateDirectoryResponse } from "./FsCreateDirectoryResponse";
+export type { FsGetMetadataParams } from "./FsGetMetadataParams";
+export type { FsGetMetadataResponse } from "./FsGetMetadataResponse";
+export type { FsReadDirectoryEntry } from "./FsReadDirectoryEntry";
+export type { FsReadDirectoryParams } from "./FsReadDirectoryParams";
+export type { FsReadDirectoryResponse } from "./FsReadDirectoryResponse";
+export type { FsReadFileParams } from "./FsReadFileParams";
+export type { FsReadFileResponse } from "./FsReadFileResponse";
+export type { FsRemoveParams } from "./FsRemoveParams";
+export type { FsRemoveResponse } from "./FsRemoveResponse";
+export type { FsWriteFileParams } from "./FsWriteFileParams";
+export type { FsWriteFileResponse } from "./FsWriteFileResponse";
 export type { GetAccountParams } from "./GetAccountParams";
 export type { GetAccountRateLimitsResponse } from "./GetAccountRateLimitsResponse";
 export type { GetAccountResponse } from "./GetAccountResponse";
 export type { GitInfo } from "./GitInfo";
 export type { GrantedMacOsPermissions } from "./GrantedMacOsPermissions";
 export type { GrantedPermissionProfile } from "./GrantedPermissionProfile";
+export type { GuardianApprovalReview } from "./GuardianApprovalReview";
+export type { GuardianApprovalReviewStatus } from "./GuardianApprovalReviewStatus";
+export type { GuardianRiskLevel } from "./GuardianRiskLevel";
 export type { HazelnutScope } from "./HazelnutScope";
 export type { HookCompletedNotification } from "./HookCompletedNotification";
 export type { HookEventName } from "./HookEventName";
@@ -113,6 +132,8 @@ export type { HookRunSummary } from "./HookRunSummary";
 export type { HookScope } from "./HookScope";
 export type { HookStartedNotification } from "./HookStartedNotification";
 export type { ItemCompletedNotification } from "./ItemCompletedNotification";
+export type { ItemGuardianApprovalReviewCompletedNotification } from "./ItemGuardianApprovalReviewCompletedNotification";
+export type { ItemGuardianApprovalReviewStartedNotification } from "./ItemGuardianApprovalReviewStartedNotification";
 export type { ItemStartedNotification } from "./ItemStartedNotification";
 export type { ListMcpServerStatusParams } from "./ListMcpServerStatusParams";
 export type { ListMcpServerStatusResponse } from "./ListMcpServerStatusResponse";

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

@@ -312,6 +312,34 @@ client_request_definitions! {
         params: v2::AppsListParams,
         response: v2::AppsListResponse,
     },
+    FsReadFile => "fs/readFile" {
+        params: v2::FsReadFileParams,
+        response: v2::FsReadFileResponse,
+    },
+    FsWriteFile => "fs/writeFile" {
+        params: v2::FsWriteFileParams,
+        response: v2::FsWriteFileResponse,
+    },
+    FsCreateDirectory => "fs/createDirectory" {
+        params: v2::FsCreateDirectoryParams,
+        response: v2::FsCreateDirectoryResponse,
+    },
+    FsGetMetadata => "fs/getMetadata" {
+        params: v2::FsGetMetadataParams,
+        response: v2::FsGetMetadataResponse,
+    },
+    FsReadDirectory => "fs/readDirectory" {
+        params: v2::FsReadDirectoryParams,
+        response: v2::FsReadDirectoryResponse,
+    },
+    FsRemove => "fs/remove" {
+        params: v2::FsRemoveParams,
+        response: v2::FsRemoveResponse,
+    },
+    FsCopy => "fs/copy" {
+        params: v2::FsCopyParams,
+        response: v2::FsCopyResponse,
+    },
     SkillsConfigWrite => "skills/config/write" {
         params: v2::SkillsConfigWriteParams,
         response: v2::SkillsConfigWriteResponse,
@@ -856,6 +884,8 @@ server_notification_definitions! {
     TurnDiffUpdated => "turn/diff/updated" (v2::TurnDiffUpdatedNotification),
     TurnPlanUpdated => "turn/plan/updated" (v2::TurnPlanUpdatedNotification),
     ItemStarted => "item/started" (v2::ItemStartedNotification),
+    ItemGuardianApprovalReviewStarted => "item/autoApprovalReview/started" (v2::ItemGuardianApprovalReviewStartedNotification),
+    ItemGuardianApprovalReviewCompleted => "item/autoApprovalReview/completed" (v2::ItemGuardianApprovalReviewCompletedNotification),
     ItemCompleted => "item/completed" (v2::ItemCompletedNotification),
     /// This event is internal-only. Used by Codex Cloud.
     RawResponseItemCompleted => "rawResponseItem/completed" (v2::RawResponseItemCompletedNotification),
@@ -921,8 +951,17 @@ mod tests {
     use serde_json::json;
     use std::path::PathBuf;
 
+    fn absolute_path_string(path: &str) -> String {
+        let trimmed = path.trim_start_matches('/');
+        if cfg!(windows) {
+            format!(r"C:\{}", trimmed.replace('/', "\\"))
+        } else {
+            format!("/{trimmed}")
+        }
+    }
+
     fn absolute_path(path: &str) -> AbsolutePathBuf {
-        AbsolutePathBuf::from_absolute_path(path).expect("absolute path")
+        AbsolutePathBuf::from_absolute_path(absolute_path_string(path)).expect("absolute path")
     }
 
     #[test]
@@ -1419,6 +1458,27 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn serialize_fs_get_metadata() -> Result<()> {
+        let request = ClientRequest::FsGetMetadata {
+            request_id: RequestId::Integer(9),
+            params: v2::FsGetMetadataParams {
+                path: absolute_path("tmp/example"),
+            },
+        };
+        assert_eq!(
+            json!({
+                "method": "fs/getMetadata",
+                "id": 9,
+                "params": {
+                    "path": absolute_path_string("tmp/example")
+                }
+            }),
+            serde_json::to_value(&request)?,
+        );
+        Ok(())
+    }
+
     #[test]
     fn serialize_list_experimental_features() -> Result<()> {
         let request = ClientRequest::ExperimentalFeatureList {

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

@@ -184,6 +184,7 @@ impl ThreadHistoryBuilder {
             RolloutItem::Compacted(payload) => self.handle_compacted(payload),
             RolloutItem::TurnContext(_)
             | RolloutItem::SessionMeta(_)
+            | RolloutItem::ForkReference(_)
             | RolloutItem::ResponseItem(_) => {}
         }
     }
@@ -2382,6 +2383,7 @@ mod tests {
                 prompt: "inspect the repo".into(),
                 model: "gpt-5.4-mini".into(),
                 reasoning_effort: codex_protocol::openai_models::ReasoningEffort::Medium,
+                spawn_mode: codex_protocol::protocol::AgentSpawnMode::Spawn,
                 status: AgentStatus::Running,
             }),
         ];

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

@@ -13,6 +13,7 @@ use codex_protocol::approvals::NetworkApprovalContext as CoreNetworkApprovalCont
 use codex_protocol::approvals::NetworkApprovalProtocol as CoreNetworkApprovalProtocol;
 use codex_protocol::approvals::NetworkPolicyAmendment as CoreNetworkPolicyAmendment;
 use codex_protocol::approvals::NetworkPolicyRuleAction as CoreNetworkPolicyRuleAction;
+use codex_protocol::config_types::ApprovalsReviewer as CoreApprovalsReviewer;
 use codex_protocol::config_types::CollaborationMode;
 use codex_protocol::config_types::CollaborationModeMask as CoreCollaborationModeMask;
 use codex_protocol::config_types::ForcedLoginMethod;
@@ -51,6 +52,7 @@ use codex_protocol::protocol::CodexErrorInfo as CoreCodexErrorInfo;
 use codex_protocol::protocol::CreditsSnapshot as CoreCreditsSnapshot;
 use codex_protocol::protocol::ExecCommandStatus as CoreExecCommandStatus;
 use codex_protocol::protocol::GranularApprovalConfig as CoreGranularApprovalConfig;
+use codex_protocol::protocol::GuardianRiskLevel as CoreGuardianRiskLevel;
 use codex_protocol::protocol::HookEventName as CoreHookEventName;
 use codex_protocol::protocol::HookExecutionMode as CoreHookExecutionMode;
 use codex_protocol::protocol::HookHandlerType as CoreHookHandlerType;
@@ -256,6 +258,37 @@ impl From<CoreAskForApproval> for AskForApproval {
     }
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "snake_case")]
+#[ts(rename_all = "snake_case", export_to = "v2/")]
+/// 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.
+pub enum ApprovalsReviewer {
+    User,
+    GuardianSubagent,
+}
+
+impl ApprovalsReviewer {
+    pub fn to_core(self) -> CoreApprovalsReviewer {
+        match self {
+            ApprovalsReviewer::User => CoreApprovalsReviewer::User,
+            ApprovalsReviewer::GuardianSubagent => CoreApprovalsReviewer::GuardianSubagent,
+        }
+    }
+}
+
+impl From<CoreApprovalsReviewer> for ApprovalsReviewer {
+    fn from(value: CoreApprovalsReviewer) -> Self {
+        match value {
+            CoreApprovalsReviewer::User => ApprovalsReviewer::User,
+            CoreApprovalsReviewer::GuardianSubagent => ApprovalsReviewer::GuardianSubagent,
+        }
+    }
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
 #[serde(rename_all = "kebab-case")]
 #[ts(rename_all = "kebab-case", export_to = "v2/")]
@@ -519,6 +552,11 @@ pub struct ProfileV2 {
     pub model_provider: Option<String>,
     #[experimental(nested)]
     pub approval_policy: Option<AskForApproval>,
+    /// [UNSTABLE] Optional profile-level override for where approval requests
+    /// are routed for review. If omitted, the enclosing config default is
+    /// used.
+    #[experimental("config/read.approvalsReviewer")]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
     pub service_tier: Option<ServiceTier>,
     pub model_reasoning_effort: Option<ReasoningEffort>,
     pub model_reasoning_summary: Option<ReasoningSummary>,
@@ -618,6 +656,10 @@ pub struct Config {
     pub model_provider: Option<String>,
     #[experimental(nested)]
     pub approval_policy: Option<AskForApproval>,
+    /// [UNSTABLE] Optional default for where approval requests are routed for
+    /// review.
+    #[experimental("config/read.approvalsReviewer")]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
     pub sandbox_mode: Option<SandboxMode>,
     pub sandbox_workspace_write: Option<SandboxWorkspaceWrite>,
     pub forced_chatgpt_workspace_id: Option<String>,
@@ -2068,6 +2110,157 @@ pub struct FeedbackUploadResponse {
     pub thread_id: String,
 }
 
+/// Read a file from the host filesystem.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsReadFileParams {
+    /// Absolute path to read.
+    pub path: AbsolutePathBuf,
+}
+
+/// Base64-encoded file contents returned by `fs/readFile`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsReadFileResponse {
+    /// File contents encoded as base64.
+    pub data_base64: String,
+}
+
+/// Write a file on the host filesystem.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsWriteFileParams {
+    /// Absolute path to write.
+    pub path: AbsolutePathBuf,
+    /// File contents encoded as base64.
+    pub data_base64: String,
+}
+
+/// Successful response for `fs/writeFile`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsWriteFileResponse {}
+
+/// Create a directory on the host filesystem.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsCreateDirectoryParams {
+    /// Absolute directory path to create.
+    pub path: AbsolutePathBuf,
+    /// Whether parent directories should also be created. Defaults to `true`.
+    #[ts(optional = nullable)]
+    pub recursive: Option<bool>,
+}
+
+/// Successful response for `fs/createDirectory`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsCreateDirectoryResponse {}
+
+/// Request metadata for an absolute path.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsGetMetadataParams {
+    /// Absolute path to inspect.
+    pub path: AbsolutePathBuf,
+}
+
+/// Metadata returned by `fs/getMetadata`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsGetMetadataResponse {
+    /// Whether the path currently resolves to a directory.
+    pub is_directory: bool,
+    /// Whether the path currently resolves to a regular file.
+    pub is_file: bool,
+    /// File creation time in Unix milliseconds when available, otherwise `0`.
+    #[ts(type = "number")]
+    pub created_at_ms: i64,
+    /// File modification time in Unix milliseconds when available, otherwise `0`.
+    #[ts(type = "number")]
+    pub modified_at_ms: i64,
+}
+
+/// List direct child names for a directory.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsReadDirectoryParams {
+    /// Absolute directory path to read.
+    pub path: AbsolutePathBuf,
+}
+
+/// A directory entry returned by `fs/readDirectory`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsReadDirectoryEntry {
+    /// Direct child entry name only, not an absolute or relative path.
+    pub file_name: String,
+    /// Whether this entry resolves to a directory.
+    pub is_directory: bool,
+    /// Whether this entry resolves to a regular file.
+    pub is_file: bool,
+}
+
+/// Directory entries returned by `fs/readDirectory`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsReadDirectoryResponse {
+    /// Direct child entries in the requested directory.
+    pub entries: Vec<FsReadDirectoryEntry>,
+}
+
+/// Remove a file or directory tree from the host filesystem.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsRemoveParams {
+    /// Absolute path to remove.
+    pub path: AbsolutePathBuf,
+    /// Whether directory removal should recurse. Defaults to `true`.
+    #[ts(optional = nullable)]
+    pub recursive: Option<bool>,
+    /// Whether missing paths should be ignored. Defaults to `true`.
+    #[ts(optional = nullable)]
+    pub force: Option<bool>,
+}
+
+/// Successful response for `fs/remove`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsRemoveResponse {}
+
+/// Copy a file or directory tree on the host filesystem.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsCopyParams {
+    /// Absolute source path.
+    pub source_path: AbsolutePathBuf,
+    /// Absolute destination path.
+    pub destination_path: AbsolutePathBuf,
+    /// Required for directory copies; ignored for file copies.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub recursive: bool,
+}
+
+/// Successful response for `fs/copy`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct FsCopyResponse {}
+
 /// PTY size in character cells for `command/exec` PTY sessions.
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
@@ -2271,6 +2464,10 @@ pub struct ThreadStartParams {
     #[experimental(nested)]
     #[ts(optional = nullable)]
     pub approval_policy: Option<AskForApproval>,
+    /// Override where approval requests are routed for review on this thread
+    /// and subsequent turns.
+    #[ts(optional = nullable)]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
     #[ts(optional = nullable)]
     pub sandbox: Option<SandboxMode>,
     #[ts(optional = nullable)]
@@ -2333,6 +2530,8 @@ pub struct ThreadStartResponse {
     pub cwd: PathBuf,
     #[experimental(nested)]
     pub approval_policy: AskForApproval,
+    /// Reviewer currently used for approval requests on this thread.
+    pub approvals_reviewer: ApprovalsReviewer,
     pub sandbox: SandboxPolicy,
     pub reasoning_effort: Option<ReasoningEffort>,
 }
@@ -2385,6 +2584,10 @@ pub struct ThreadResumeParams {
     #[experimental(nested)]
     #[ts(optional = nullable)]
     pub approval_policy: Option<AskForApproval>,
+    /// Override where approval requests are routed for review on this thread
+    /// and subsequent turns.
+    #[ts(optional = nullable)]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
     #[ts(optional = nullable)]
     pub sandbox: Option<SandboxMode>,
     #[ts(optional = nullable)]
@@ -2413,6 +2616,8 @@ pub struct ThreadResumeResponse {
     pub cwd: PathBuf,
     #[experimental(nested)]
     pub approval_policy: AskForApproval,
+    /// Reviewer currently used for approval requests on this thread.
+    pub approvals_reviewer: ApprovalsReviewer,
     pub sandbox: SandboxPolicy,
     pub reasoning_effort: Option<ReasoningEffort>,
 }
@@ -2456,6 +2661,10 @@ pub struct ThreadForkParams {
     #[experimental(nested)]
     #[ts(optional = nullable)]
     pub approval_policy: Option<AskForApproval>,
+    /// Override where approval requests are routed for review on this thread
+    /// and subsequent turns.
+    #[ts(optional = nullable)]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
     #[ts(optional = nullable)]
     pub sandbox: Option<SandboxMode>,
     #[ts(optional = nullable)]
@@ -2484,6 +2693,8 @@ pub struct ThreadForkResponse {
     pub cwd: PathBuf,
     #[experimental(nested)]
     pub approval_policy: AskForApproval,
+    /// Reviewer currently used for approval requests on this thread.
+    pub approvals_reviewer: ApprovalsReviewer,
     pub sandbox: SandboxPolicy,
     pub reasoning_effort: Option<ReasoningEffort>,
 }
@@ -3607,6 +3818,10 @@ pub struct TurnStartParams {
     #[experimental(nested)]
     #[ts(optional = nullable)]
     pub approval_policy: Option<AskForApproval>,
+    /// Override where approval requests are routed for review on this turn and
+    /// subsequent turns.
+    #[ts(optional = nullable)]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
     /// Override the sandbox policy for this turn and subsequent turns.
     #[ts(optional = nullable)]
     pub sandbox_policy: Option<SandboxPolicy>,
@@ -4043,6 +4258,53 @@ impl ThreadItem {
     }
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+/// [UNSTABLE] Lifecycle state for a guardian approval review.
+pub enum GuardianApprovalReviewStatus {
+    InProgress,
+    Approved,
+    Denied,
+    Aborted,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "lowercase")]
+#[ts(export_to = "v2/")]
+/// [UNSTABLE] Risk level assigned by guardian approval review.
+pub enum GuardianRiskLevel {
+    Low,
+    Medium,
+    High,
+}
+
+impl From<CoreGuardianRiskLevel> for GuardianRiskLevel {
+    fn from(value: CoreGuardianRiskLevel) -> Self {
+        match value {
+            CoreGuardianRiskLevel::Low => Self::Low,
+            CoreGuardianRiskLevel::Medium => Self::Medium,
+            CoreGuardianRiskLevel::High => Self::High,
+        }
+    }
+}
+
+/// [UNSTABLE] Temporary guardian approval review payload used by
+/// `item/autoApprovalReview/*` notifications. This shape is expected to change
+/// soon.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct GuardianApprovalReview {
+    pub status: GuardianApprovalReviewStatus,
+    #[serde(alias = "risk_score")]
+    #[ts(type = "number | null")]
+    pub risk_score: Option<u8>,
+    #[serde(alias = "risk_level")]
+    pub risk_level: Option<GuardianRiskLevel>,
+    pub rationale: Option<String>,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
 #[serde(tag = "type", rename_all = "camelCase")]
 #[ts(tag = "type", rename_all = "camelCase")]
@@ -4474,6 +4736,40 @@ pub struct ItemStartedNotification {
     pub turn_id: String,
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+/// [UNSTABLE] Temporary notification payload for guardian automatic approval
+/// review. This shape is expected to change soon.
+///
+/// TODO(ccunningham): Attach guardian review state to the reviewed tool item's
+/// lifecycle instead of sending separate standalone review notifications so the
+/// app-server API can persist and replay review state via `thread/read`.
+pub struct ItemGuardianApprovalReviewStartedNotification {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub target_item_id: String,
+    pub review: GuardianApprovalReview,
+    pub action: Option<JsonValue>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+/// [UNSTABLE] Temporary notification payload for guardian automatic approval
+/// review. This shape is expected to change soon.
+///
+/// TODO(ccunningham): Attach guardian review state to the reviewed tool item's
+/// lifecycle instead of sending separate standalone review notifications so the
+/// app-server API can persist and replay review state via `thread/read`.
+pub struct ItemGuardianApprovalReviewCompletedNotification {
+    pub thread_id: String,
+    pub turn_id: String,
+    pub target_item_id: String,
+    pub review: GuardianApprovalReview,
+    pub action: Option<JsonValue>,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
@@ -5535,13 +5831,22 @@ mod tests {
     use serde_json::json;
     use std::path::PathBuf;
 
-    fn test_absolute_path() -> AbsolutePathBuf {
-        let path = if cfg!(windows) {
-            r"C:\readable"
+    fn absolute_path_string(path: &str) -> String {
+        let trimmed = path.trim_start_matches('/');
+        if cfg!(windows) {
+            format!(r"C:\{}", trimmed.replace('/', "\\"))
         } else {
-            "/readable"
-        };
-        AbsolutePathBuf::from_absolute_path(path).expect("path must be absolute")
+            format!("/{trimmed}")
+        }
+    }
+
+    fn absolute_path(path: &str) -> AbsolutePathBuf {
+        AbsolutePathBuf::from_absolute_path(absolute_path_string(path))
+            .expect("path must be absolute")
+    }
+
+    fn test_absolute_path() -> AbsolutePathBuf {
+        absolute_path("readable")
     }
 
     #[test]
@@ -5891,6 +6196,134 @@ mod tests {
         assert_eq!(response.scope, PermissionGrantScope::Turn);
     }
 
+    #[test]
+    fn fs_get_metadata_response_round_trips_minimal_fields() {
+        let response = FsGetMetadataResponse {
+            is_directory: false,
+            is_file: true,
+            created_at_ms: 123,
+            modified_at_ms: 456,
+        };
+
+        let value = serde_json::to_value(&response).expect("serialize fs/getMetadata response");
+        assert_eq!(
+            value,
+            json!({
+                "isDirectory": false,
+                "isFile": true,
+                "createdAtMs": 123,
+                "modifiedAtMs": 456,
+            })
+        );
+
+        let decoded = serde_json::from_value::<FsGetMetadataResponse>(value)
+            .expect("deserialize fs/getMetadata response");
+        assert_eq!(decoded, response);
+    }
+
+    #[test]
+    fn fs_read_file_response_round_trips_base64_data() {
+        let response = FsReadFileResponse {
+            data_base64: "aGVsbG8=".to_string(),
+        };
+
+        let value = serde_json::to_value(&response).expect("serialize fs/readFile response");
+        assert_eq!(
+            value,
+            json!({
+                "dataBase64": "aGVsbG8=",
+            })
+        );
+
+        let decoded = serde_json::from_value::<FsReadFileResponse>(value)
+            .expect("deserialize fs/readFile response");
+        assert_eq!(decoded, response);
+    }
+
+    #[test]
+    fn fs_read_file_params_round_trip() {
+        let params = FsReadFileParams {
+            path: absolute_path("tmp/example.txt"),
+        };
+
+        let value = serde_json::to_value(&params).expect("serialize fs/readFile params");
+        assert_eq!(
+            value,
+            json!({
+                "path": absolute_path_string("tmp/example.txt"),
+            })
+        );
+
+        let decoded = serde_json::from_value::<FsReadFileParams>(value)
+            .expect("deserialize fs/readFile params");
+        assert_eq!(decoded, params);
+    }
+
+    #[test]
+    fn fs_create_directory_params_round_trip_with_default_recursive() {
+        let params = FsCreateDirectoryParams {
+            path: absolute_path("tmp/example"),
+            recursive: None,
+        };
+
+        let value = serde_json::to_value(&params).expect("serialize fs/createDirectory params");
+        assert_eq!(
+            value,
+            json!({
+                "path": absolute_path_string("tmp/example"),
+                "recursive": null,
+            })
+        );
+
+        let decoded = serde_json::from_value::<FsCreateDirectoryParams>(value)
+            .expect("deserialize fs/createDirectory params");
+        assert_eq!(decoded, params);
+    }
+
+    #[test]
+    fn fs_write_file_params_round_trip_with_base64_data() {
+        let params = FsWriteFileParams {
+            path: absolute_path("tmp/example.bin"),
+            data_base64: "AAE=".to_string(),
+        };
+
+        let value = serde_json::to_value(&params).expect("serialize fs/writeFile params");
+        assert_eq!(
+            value,
+            json!({
+                "path": absolute_path_string("tmp/example.bin"),
+                "dataBase64": "AAE=",
+            })
+        );
+
+        let decoded = serde_json::from_value::<FsWriteFileParams>(value)
+            .expect("deserialize fs/writeFile params");
+        assert_eq!(decoded, params);
+    }
+
+    #[test]
+    fn fs_copy_params_round_trip_with_recursive_directory_copy() {
+        let params = FsCopyParams {
+            source_path: absolute_path("tmp/source"),
+            destination_path: absolute_path("tmp/destination"),
+            recursive: true,
+        };
+
+        let value = serde_json::to_value(&params).expect("serialize fs/copy params");
+        assert_eq!(
+            value,
+            json!({
+                "sourcePath": absolute_path_string("tmp/source"),
+                "destinationPath": absolute_path_string("tmp/destination"),
+                "recursive": true,
+            })
+        );
+
+        let decoded =
+            serde_json::from_value::<FsCopyParams>(value).expect("deserialize fs/copy params");
+        assert_eq!(decoded, params);
+    }
+
     #[test]
     fn command_exec_params_default_optional_streaming_flags() {
         let params = serde_json::from_value::<CommandExecParams>(json!({
@@ -6312,6 +6745,7 @@ mod tests {
                 request_permissions: true,
                 mcp_elicitations: false,
             }),
+            approvals_reviewer: None,
             service_tier: None,
             model_reasoning_effort: None,
             model_reasoning_summary: None,
@@ -6340,6 +6774,7 @@ mod tests {
                 request_permissions: false,
                 mcp_elicitations: true,
             }),
+            approvals_reviewer: None,
             sandbox_mode: None,
             sandbox_workspace_write: None,
             forced_chatgpt_workspace_id: None,
@@ -6363,6 +6798,39 @@ mod tests {
         assert_eq!(reason, Some("askForApproval.granular"));
     }
 
+    #[test]
+    fn config_approvals_reviewer_is_marked_experimental() {
+        let reason = crate::experimental_api::ExperimentalApi::experimental_reason(&Config {
+            model: None,
+            review_model: None,
+            model_context_window: None,
+            model_auto_compact_token_limit: None,
+            model_provider: None,
+            approval_policy: None,
+            approvals_reviewer: Some(ApprovalsReviewer::GuardianSubagent),
+            sandbox_mode: None,
+            sandbox_workspace_write: None,
+            forced_chatgpt_workspace_id: None,
+            forced_login_method: None,
+            web_search: None,
+            tools: None,
+            profile: None,
+            profiles: HashMap::new(),
+            instructions: None,
+            developer_instructions: None,
+            compact_prompt: None,
+            model_reasoning_effort: None,
+            model_reasoning_summary: None,
+            model_verbosity: None,
+            service_tier: None,
+            analytics: None,
+            apps: None,
+            additional: HashMap::new(),
+        });
+
+        assert_eq!(reason, Some("config/read.approvalsReviewer"));
+    }
+
     #[test]
     fn config_nested_profile_granular_approval_policy_is_marked_experimental() {
         let reason = crate::experimental_api::ExperimentalApi::experimental_reason(&Config {
@@ -6372,6 +6840,7 @@ mod tests {
             model_auto_compact_token_limit: None,
             model_provider: None,
             approval_policy: None,
+            approvals_reviewer: None,
             sandbox_mode: None,
             sandbox_workspace_write: None,
             forced_chatgpt_workspace_id: None,
@@ -6391,6 +6860,7 @@ mod tests {
                         request_permissions: false,
                         mcp_elicitations: true,
                     }),
+                    approvals_reviewer: None,
                     service_tier: None,
                     model_reasoning_effort: None,
                     model_reasoning_summary: None,
@@ -6416,6 +6886,55 @@ mod tests {
         assert_eq!(reason, Some("askForApproval.granular"));
     }
 
+    #[test]
+    fn config_nested_profile_approvals_reviewer_is_marked_experimental() {
+        let reason = crate::experimental_api::ExperimentalApi::experimental_reason(&Config {
+            model: None,
+            review_model: None,
+            model_context_window: None,
+            model_auto_compact_token_limit: None,
+            model_provider: None,
+            approval_policy: None,
+            approvals_reviewer: None,
+            sandbox_mode: None,
+            sandbox_workspace_write: None,
+            forced_chatgpt_workspace_id: None,
+            forced_login_method: None,
+            web_search: None,
+            tools: None,
+            profile: None,
+            profiles: HashMap::from([(
+                "default".to_string(),
+                ProfileV2 {
+                    model: None,
+                    model_provider: None,
+                    approval_policy: None,
+                    approvals_reviewer: Some(ApprovalsReviewer::GuardianSubagent),
+                    service_tier: None,
+                    model_reasoning_effort: None,
+                    model_reasoning_summary: None,
+                    model_verbosity: None,
+                    web_search: None,
+                    tools: None,
+                    chatgpt_base_url: None,
+                    additional: HashMap::new(),
+                },
+            )]),
+            instructions: None,
+            developer_instructions: None,
+            compact_prompt: None,
+            model_reasoning_effort: None,
+            model_reasoning_summary: None,
+            model_verbosity: None,
+            service_tier: None,
+            analytics: None,
+            apps: None,
+            additional: HashMap::new(),
+        });
+
+        assert_eq!(reason, Some("config/read.approvalsReviewer"));
+    }
+
     #[test]
     fn config_requirements_granular_allowed_approval_policy_is_marked_experimental() {
         let reason =
@@ -6826,6 +7345,46 @@ mod tests {
         );
     }
 
+    #[test]
+    fn automatic_approval_review_deserializes_legacy_snake_case_risk_fields() {
+        let review: GuardianApprovalReview = serde_json::from_value(json!({
+            "status": "denied",
+            "risk_score": 91,
+            "risk_level": "high",
+            "rationale": "too risky"
+        }))
+        .expect("legacy snake_case automatic review should deserialize");
+        assert_eq!(
+            review,
+            GuardianApprovalReview {
+                status: GuardianApprovalReviewStatus::Denied,
+                risk_score: Some(91),
+                risk_level: Some(GuardianRiskLevel::High),
+                rationale: Some("too risky".to_string()),
+            }
+        );
+    }
+
+    #[test]
+    fn automatic_approval_review_deserializes_aborted_status() {
+        let review: GuardianApprovalReview = serde_json::from_value(json!({
+            "status": "aborted",
+            "riskScore": null,
+            "riskLevel": null,
+            "rationale": null
+        }))
+        .expect("aborted automatic review should deserialize");
+        assert_eq!(
+            review,
+            GuardianApprovalReview {
+                status: GuardianApprovalReviewStatus::Aborted,
+                risk_score: None,
+                risk_level: None,
+                rationale: None,
+            }
+        );
+    }
+
     #[test]
     fn core_turn_item_into_thread_item_converts_supported_variants() {
         let user_item = TurnItem::UserMessage(UserMessageItem {
@@ -7132,6 +7691,7 @@ mod tests {
             input: vec![],
             cwd: None,
             approval_policy: None,
+            approvals_reviewer: None,
             sandbox_policy: None,
             model: None,
             service_tier: None,

codex-rs/app-server/Cargo.toml

@@ -68,6 +68,7 @@ tokio-tungstenite = { workspace = true }
 tracing = { workspace = true, features = ["log"] }
 tracing-subscriber = { workspace = true, features = ["env-filter", "fmt", "json"] }
 uuid = { workspace = true, features = ["serde", "v7"] }
+walkdir = { workspace = true }
 
 [dev-dependencies]
 app_test_support = { workspace = true }

codex-rs/app-server/README.md

@@ -68,7 +68,7 @@ Use the thread APIs to create, list, or archive conversations. Drive a conversat
 - Initialize once per connection: Immediately after opening a transport connection, send an `initialize` request with your client metadata, then emit an `initialized` notification. Any other request on that connection before this handshake gets rejected.
 - Start (or resume) a thread: Call `thread/start` to open a fresh conversation. The response returns the thread object and you’ll also get a `thread/started` notification. If you’re continuing an existing conversation, call `thread/resume` with its ID instead. If you want to branch from an existing conversation, call `thread/fork` to create a new thread id with copied history. Like `thread/start`, `thread/fork` also accepts `ephemeral: true` for an in-memory temporary thread.
   The returned `thread.ephemeral` flag tells you whether the session is intentionally in-memory only; when it is `true`, `thread.path` is `null`.
-- Begin a turn: To send user input, call `turn/start` with the target `threadId` and the user's input. Optional fields let you override model, cwd, sandbox policy, etc. This immediately returns the new turn object. The app-server emits `turn/started` when that turn actually begins running.
+- Begin a turn: To send user input, call `turn/start` with the target `threadId` and the user's input. Optional fields let you override model, cwd, sandbox policy, approval policy, approvals reviewer, etc. This immediately returns the new turn object. The app-server emits `turn/started` when that turn actually begins running.
 - Stream events: After `turn/start`, keep reading JSON-RPC notifications on stdout. You’ll see `item/started`, `item/completed`, deltas like `item/agentMessage/delta`, tool progress, etc. These represent streaming model output plus any side effects (commands, tool calls, reasoning notes).
 - Finish the turn: When the model is done (or the turn is interrupted via making the `turn/interrupt` call), the server sends `turn/completed` with the final turn state and token usage.
 
@@ -153,6 +153,13 @@ Example with notification opt-out:
 - `command/exec/resize` — resize a running PTY-backed `command/exec` session by `processId`; returns `{}`.
 - `command/exec/terminate` — terminate a running `command/exec` session by `processId`; returns `{}`.
 - `command/exec/outputDelta` — notification emitted for base64-encoded stdout/stderr chunks from a streaming `command/exec` session.
+- `fs/readFile` — read an absolute file path and return `{ dataBase64 }`.
+- `fs/writeFile` — write an absolute file path from base64-encoded `{ dataBase64 }`; returns `{}`.
+- `fs/createDirectory` — create an absolute directory path; `recursive` defaults to `true`.
+- `fs/getMetadata` — return metadata for an absolute path: `isDirectory`, `isFile`, `createdAtMs`, and `modifiedAtMs`.
+- `fs/readDirectory` — list direct child entries for an absolute directory path; each entry contains `fileName`, `isDirectory`, and `isFile`, and `fileName` is just the child name, not a path.
+- `fs/remove` — remove an absolute file or directory tree; `recursive` and `force` default to `true`.
+- `fs/copy` — copy between absolute paths; directory copies require `recursive: true`.
 - `model/list` — list available models (set `includeHidden: true` to include entries with `hidden: true`), with reasoning effort options, optional legacy `upgrade` model ids, optional `upgradeInfo` metadata (`model`, `upgradeCopy`, `modelLink`, `migrationMarkdown`), and optional `availabilityNux` metadata.
 - `experimentalFeature/list` — list feature flags with stage metadata (`beta`, `underDevelopment`, `stable`, etc.), enabled/default-enabled state, and cursor pagination. For non-beta flags, `displayName`/`description`/`announcement` are `null`.
 - `collaborationMode/list` — list available collaboration mode presets (experimental, no pagination). 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.
@@ -221,7 +228,7 @@ Start a fresh thread when you need a new Codex conversation.
 
 Valid `personality` values are `"friendly"`, `"pragmatic"`, and `"none"`. When `"none"` is selected, the personality placeholder is replaced with an empty string.
 
-To continue a stored session, call `thread/resume` with the `thread.id` you previously recorded. The response shape matches `thread/start`, and no additional notifications are emitted. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:
+To continue a stored session, call `thread/resume` with the `thread.id` you previously recorded. The response shape matches `thread/start`, and no additional notifications are emitted. You can also pass the same configuration overrides supported by `thread/start`, including `approvalsReviewer`:
 
 ```json
 { "method": "thread/resume", "id": 11, "params": {
@@ -414,6 +421,11 @@ Turns attach user input (text or images) to a thread and trigger Codex generatio
 
 You can optionally specify config overrides on the new turn. If specified, these settings become the default for subsequent turns on the same thread. `outputSchema` applies only to the current turn.
 
+`approvalsReviewer` accepts:
+
+- `"user"` — default. Review approval requests directly in the client.
+- `"guardian_subagent"` — route approval requests to a carefully prompted subagent that gathers relevant context and applies a risk-based decision framework before approving or denying the request.
+
 ```json
 { "method": "turn/start", "id": 30, "params": {
     "threadId": "thr_123",
@@ -711,6 +723,46 @@ Streaming stdin/stdout uses base64 so PTY sessions can carry arbitrary bytes:
 - `command/exec.params.env` overrides the server-computed environment per key; set a key to `null` to unset an inherited variable.
 - `command/exec/resize` is only supported for PTY-backed `command/exec` sessions.
 
+### Example: Filesystem utilities
+
+These methods operate on absolute paths on the host filesystem and cover reading, writing, directory traversal, copying, removal, and change notifications.
+
+All filesystem paths in this section must be absolute.
+
+```json
+{ "method": "fs/createDirectory", "id": 40, "params": {
+    "path": "/tmp/example/nested",
+    "recursive": true
+} }
+{ "id": 40, "result": {} }
+{ "method": "fs/writeFile", "id": 41, "params": {
+    "path": "/tmp/example/nested/note.txt",
+    "dataBase64": "aGVsbG8="
+} }
+{ "id": 41, "result": {} }
+{ "method": "fs/getMetadata", "id": 42, "params": {
+    "path": "/tmp/example/nested/note.txt"
+} }
+{ "id": 42, "result": {
+    "isDirectory": false,
+    "isFile": true,
+    "createdAtMs": 1730910000000,
+    "modifiedAtMs": 1730910000000
+} }
+{ "method": "fs/readFile", "id": 43, "params": {
+    "path": "/tmp/example/nested/note.txt"
+} }
+{ "id": 43, "result": {
+    "dataBase64": "aGVsbG8="
+} }
+```
+
+- `fs/getMetadata` returns whether the path currently resolves to a directory or regular file, plus `createdAtMs` and `modifiedAtMs` in Unix milliseconds. If a timestamp is unavailable on the current platform, that field is `0`.
+- `fs/createDirectory` defaults `recursive` to `true` when omitted.
+- `fs/remove` defaults both `recursive` and `force` to `true` when omitted.
+- `fs/readFile` always returns base64 bytes via `dataBase64`, and `fs/writeFile` always expects base64 bytes in `dataBase64`.
+- `fs/copy` handles both file copies and directory-tree copies; it requires `recursive: true` when `sourcePath` is a directory. Recursive copies traverse regular files, directories, and symlinks; other entry types are skipped.
+
 ## Events
 
 Event notifications are the server-initiated event stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading stdout for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/closed`, `turn/*`, and `item/*` notifications.
@@ -785,10 +837,14 @@ Today both notifications carry an empty `items` array even when item events were
 - `contextCompaction` — `{id}` emitted when codex compacts the conversation history. This can happen automatically.
 - `compacted` - `{threadId, turnId}` when codex compacts the conversation history. This can happen automatically. **Deprecated:** Use `contextCompaction` instead.
 
-All items emit two shared lifecycle events:
+All items emit shared lifecycle events:
 
 - `item/started` — emits the full `item` when a new unit of work begins so the UI can render it immediately; the `item.id` in this payload matches the `itemId` used by deltas.
-- `item/completed` — sends the final `item` once that work finishes (e.g., after a tool call or message completes); treat this as the authoritative state.
+- `item/completed` — sends the final `item` once that work itself finishes (for example, after a tool call or message completes); treat this as the authoritative execution/result state.
+- `item/autoApprovalReview/started` — [UNSTABLE] temporary guardian notification carrying `{threadId, turnId, targetItemId, review, action?}` when guardian approval review begins. This shape is expected to change soon.
+- `item/autoApprovalReview/completed` — [UNSTABLE] temporary guardian notification carrying `{threadId, turnId, targetItemId, review, action?}` when guardian approval review resolves. This shape is expected to change soon.
+
+`review` is [UNSTABLE] and currently has `{status, riskScore?, riskLevel?, rationale?}`, where `status` is one of `inProgress`, `approved`, `denied`, or `aborted`. `action` is the guardian action summary payload from core when available and is intended to support temporary standalone pending-review UI. These notifications are separate from the target item's own `item/completed` lifecycle and are intentionally temporary while the guardian app protocol is still being designed.
 
 There are additional item-specific events:
 

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

@@ -43,10 +43,14 @@ use codex_app_server_protocol::FileChangeRequestApprovalParams;
 use codex_app_server_protocol::FileChangeRequestApprovalResponse;
 use codex_app_server_protocol::FileUpdateChange;
 use codex_app_server_protocol::GrantedPermissionProfile as V2GrantedPermissionProfile;
+use codex_app_server_protocol::GuardianApprovalReview;
+use codex_app_server_protocol::GuardianApprovalReviewStatus;
 use codex_app_server_protocol::HookCompletedNotification;
 use codex_app_server_protocol::HookStartedNotification;
 use codex_app_server_protocol::InterruptConversationResponse;
 use codex_app_server_protocol::ItemCompletedNotification;
+use codex_app_server_protocol::ItemGuardianApprovalReviewCompletedNotification;
+use codex_app_server_protocol::ItemGuardianApprovalReviewStartedNotification;
 use codex_app_server_protocol::ItemStartedNotification;
 use codex_app_server_protocol::JSONRPCErrorError;
 use codex_app_server_protocol::McpServerElicitationAction;
@@ -114,6 +118,7 @@ use codex_protocol::protocol::Event;
 use codex_protocol::protocol::EventMsg;
 use codex_protocol::protocol::ExecApprovalRequestEvent;
 use codex_protocol::protocol::ExecCommandEndEvent;
+use codex_protocol::protocol::GuardianAssessmentEvent;
 use codex_protocol::protocol::McpToolCallBeginEvent;
 use codex_protocol::protocol::McpToolCallEndEvent;
 use codex_protocol::protocol::Op;
@@ -183,6 +188,66 @@ async fn resolve_server_request_on_thread_listener(
     }
 }
 
+fn guardian_auto_approval_review_notification(
+    conversation_id: &ThreadId,
+    event_turn_id: &str,
+    assessment: &GuardianAssessmentEvent,
+) -> ServerNotification {
+    // TODO(ccunningham): Attach guardian review state to the reviewed tool
+    // item's lifecycle instead of sending standalone review notifications so
+    // the app-server API can persist and replay review state via `thread/read`.
+    let turn_id = if assessment.turn_id.is_empty() {
+        event_turn_id.to_string()
+    } else {
+        assessment.turn_id.clone()
+    };
+    let review = GuardianApprovalReview {
+        status: match assessment.status {
+            codex_protocol::protocol::GuardianAssessmentStatus::InProgress => {
+                GuardianApprovalReviewStatus::InProgress
+            }
+            codex_protocol::protocol::GuardianAssessmentStatus::Approved => {
+                GuardianApprovalReviewStatus::Approved
+            }
+            codex_protocol::protocol::GuardianAssessmentStatus::Denied => {
+                GuardianApprovalReviewStatus::Denied
+            }
+            codex_protocol::protocol::GuardianAssessmentStatus::Aborted => {
+                GuardianApprovalReviewStatus::Aborted
+            }
+        },
+        risk_score: assessment.risk_score,
+        risk_level: assessment.risk_level.map(Into::into),
+        rationale: assessment.rationale.clone(),
+    };
+    match assessment.status {
+        codex_protocol::protocol::GuardianAssessmentStatus::InProgress => {
+            ServerNotification::ItemGuardianApprovalReviewStarted(
+                ItemGuardianApprovalReviewStartedNotification {
+                    thread_id: conversation_id.to_string(),
+                    turn_id,
+                    target_item_id: assessment.id.clone(),
+                    review,
+                    action: assessment.action.clone(),
+                },
+            )
+        }
+        codex_protocol::protocol::GuardianAssessmentStatus::Approved
+        | codex_protocol::protocol::GuardianAssessmentStatus::Denied
+        | codex_protocol::protocol::GuardianAssessmentStatus::Aborted => {
+            ServerNotification::ItemGuardianApprovalReviewCompleted(
+                ItemGuardianApprovalReviewCompletedNotification {
+                    thread_id: conversation_id.to_string(),
+                    turn_id,
+                    target_item_id: assessment.id.clone(),
+                    review,
+                    action: assessment.action.clone(),
+                },
+            )
+        }
+    }
+}
+
 #[allow(clippy::too_many_arguments)]
 pub(crate) async fn apply_bespoke_event_handling(
     event: Event,
@@ -245,6 +310,16 @@ pub(crate) async fn apply_bespoke_event_handling(
             }
         }
         EventMsg::Warning(_warning_event) => {}
+        EventMsg::GuardianAssessment(assessment) => {
+            if let ApiVersion::V2 = api_version {
+                let notification = guardian_auto_approval_review_notification(
+                    &conversation_id,
+                    &event_turn_id,
+                    &assessment,
+                );
+                outgoing.send_server_notification(notification).await;
+            }
+        }
         EventMsg::ModelReroute(event) => {
             if let ApiVersion::V2 = api_version {
                 let notification = ModelReroutedNotification {
@@ -2645,6 +2720,7 @@ mod tests {
     use anyhow::Result;
     use anyhow::anyhow;
     use anyhow::bail;
+    use codex_app_server_protocol::GuardianApprovalReviewStatus;
     use codex_app_server_protocol::JSONRPCErrorError;
     use codex_app_server_protocol::TurnPlanStepStatus;
     use codex_protocol::mcp::CallToolResult;
@@ -2664,6 +2740,7 @@ mod tests {
     use pretty_assertions::assert_eq;
     use rmcp::model::Content;
     use serde_json::Value as JsonValue;
+    use serde_json::json;
     use std::time::Duration;
     use tokio::sync::Mutex;
     use tokio::sync::mpsc;
@@ -2685,6 +2762,120 @@ mod tests {
         }
     }
 
+    #[test]
+    fn guardian_assessment_started_uses_event_turn_id_fallback() {
+        let conversation_id = ThreadId::new();
+        let action = json!({
+            "tool": "shell",
+            "command": "rm -rf /tmp/example.sqlite",
+        });
+        let notification = guardian_auto_approval_review_notification(
+            &conversation_id,
+            "turn-from-event",
+            &GuardianAssessmentEvent {
+                id: "item-1".to_string(),
+                turn_id: String::new(),
+                status: codex_protocol::protocol::GuardianAssessmentStatus::InProgress,
+                risk_score: None,
+                risk_level: None,
+                rationale: None,
+                action: Some(action.clone()),
+            },
+        );
+
+        match notification {
+            ServerNotification::ItemGuardianApprovalReviewStarted(payload) => {
+                assert_eq!(payload.thread_id, conversation_id.to_string());
+                assert_eq!(payload.turn_id, "turn-from-event");
+                assert_eq!(payload.target_item_id, "item-1");
+                assert_eq!(
+                    payload.review.status,
+                    GuardianApprovalReviewStatus::InProgress
+                );
+                assert_eq!(payload.review.risk_score, None);
+                assert_eq!(payload.review.risk_level, None);
+                assert_eq!(payload.review.rationale, None);
+                assert_eq!(payload.action, Some(action));
+            }
+            other => panic!("unexpected notification: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn guardian_assessment_completed_emits_review_payload() {
+        let conversation_id = ThreadId::new();
+        let action = json!({
+            "tool": "shell",
+            "command": "rm -rf /tmp/example.sqlite",
+        });
+        let notification = guardian_auto_approval_review_notification(
+            &conversation_id,
+            "turn-from-event",
+            &GuardianAssessmentEvent {
+                id: "item-2".to_string(),
+                turn_id: "turn-from-assessment".to_string(),
+                status: codex_protocol::protocol::GuardianAssessmentStatus::Denied,
+                risk_score: Some(91),
+                risk_level: Some(codex_protocol::protocol::GuardianRiskLevel::High),
+                rationale: Some("too risky".to_string()),
+                action: Some(action.clone()),
+            },
+        );
+
+        match notification {
+            ServerNotification::ItemGuardianApprovalReviewCompleted(payload) => {
+                assert_eq!(payload.thread_id, conversation_id.to_string());
+                assert_eq!(payload.turn_id, "turn-from-assessment");
+                assert_eq!(payload.target_item_id, "item-2");
+                assert_eq!(payload.review.status, GuardianApprovalReviewStatus::Denied);
+                assert_eq!(payload.review.risk_score, Some(91));
+                assert_eq!(
+                    payload.review.risk_level,
+                    Some(codex_app_server_protocol::GuardianRiskLevel::High)
+                );
+                assert_eq!(payload.review.rationale.as_deref(), Some("too risky"));
+                assert_eq!(payload.action, Some(action));
+            }
+            other => panic!("unexpected notification: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn guardian_assessment_aborted_emits_completed_review_payload() {
+        let conversation_id = ThreadId::new();
+        let action = json!({
+            "tool": "network_access",
+            "target": "api.openai.com:443",
+        });
+        let notification = guardian_auto_approval_review_notification(
+            &conversation_id,
+            "turn-from-event",
+            &GuardianAssessmentEvent {
+                id: "item-3".to_string(),
+                turn_id: "turn-from-assessment".to_string(),
+                status: codex_protocol::protocol::GuardianAssessmentStatus::Aborted,
+                risk_score: None,
+                risk_level: None,
+                rationale: None,
+                action: Some(action.clone()),
+            },
+        );
+
+        match notification {
+            ServerNotification::ItemGuardianApprovalReviewCompleted(payload) => {
+                assert_eq!(payload.thread_id, conversation_id.to_string());
+                assert_eq!(payload.turn_id, "turn-from-assessment");
+                assert_eq!(payload.target_item_id, "item-3");
+                assert_eq!(payload.review.status, GuardianApprovalReviewStatus::Aborted);
+                assert_eq!(payload.review.risk_score, None);
+                assert_eq!(payload.review.risk_level, None);
+                assert_eq!(payload.review.rationale, None);
+                assert_eq!(payload.action, Some(action));
+            }
+            other => panic!("unexpected notification: {other:?}"),
+        }
+    }
+
     #[test]
     fn file_change_accept_for_session_maps_to_approved_for_session() {
         let (decision, completion_status) =

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

@@ -214,6 +214,7 @@ use codex_core::features::FEATURES;
 use codex_core::features::Feature;
 use codex_core::features::Stage;
 use codex_core::find_archived_thread_path_by_id_str;
+use codex_core::find_or_unarchive_thread_path_by_id_str;
 use codex_core::find_thread_name_by_id;
 use codex_core::find_thread_names_by_ids;
 use codex_core::find_thread_path_by_id_str;
@@ -233,6 +234,7 @@ use codex_core::plugins::PluginUninstallError as CorePluginUninstallError;
 use codex_core::plugins::load_plugin_apps;
 use codex_core::read_head_for_summary;
 use codex_core::read_session_meta_line;
+use codex_core::resolve_fork_reference_rollout_path;
 use codex_core::rollout_date_parts;
 use codex_core::sandboxing::SandboxPermissions;
 use codex_core::skills::remote::export_remote_skill;
@@ -899,6 +901,15 @@ impl CodexMessageProcessor {
             | ClientRequest::ConfigBatchWrite { .. } => {
                 warn!("Config request reached CodexMessageProcessor unexpectedly");
             }
+            ClientRequest::FsReadFile { .. }
+            | ClientRequest::FsWriteFile { .. }
+            | ClientRequest::FsCreateDirectory { .. }
+            | ClientRequest::FsGetMetadata { .. }
+            | ClientRequest::FsReadDirectory { .. }
+            | ClientRequest::FsRemove { .. }
+            | ClientRequest::FsCopy { .. } => {
+                warn!("Filesystem request reached CodexMessageProcessor unexpectedly");
+            }
             ClientRequest::ConfigRequirementsRead { .. } => {
                 warn!("ConfigRequirementsRead request reached CodexMessageProcessor unexpectedly");
             }
@@ -1845,6 +1856,7 @@ impl CodexMessageProcessor {
             service_tier,
             cwd,
             approval_policy,
+            approvals_reviewer,
             sandbox,
             config,
             service_name,
@@ -1863,6 +1875,7 @@ impl CodexMessageProcessor {
             service_tier,
             cwd,
             approval_policy,
+            approvals_reviewer,
             sandbox,
             base_instructions,
             developer_instructions,
@@ -2086,6 +2099,7 @@ impl CodexMessageProcessor {
                     service_tier: config_snapshot.service_tier,
                     cwd: config_snapshot.cwd,
                     approval_policy: config_snapshot.approval_policy.into(),
+                    approvals_reviewer: config_snapshot.approvals_reviewer.into(),
                     sandbox: config_snapshot.sandbox_policy.into(),
                     reasoning_effort: config_snapshot.reasoning_effort,
                 };
@@ -2131,6 +2145,7 @@ impl CodexMessageProcessor {
         service_tier: Option<Option<codex_protocol::config_types::ServiceTier>>,
         cwd: Option<String>,
         approval_policy: Option<codex_app_server_protocol::AskForApproval>,
+        approvals_reviewer: Option<codex_app_server_protocol::ApprovalsReviewer>,
         sandbox: Option<SandboxMode>,
         base_instructions: Option<String>,
         developer_instructions: Option<String>,
@@ -2143,6 +2158,8 @@ impl CodexMessageProcessor {
             cwd: cwd.map(PathBuf::from),
             approval_policy: approval_policy
                 .map(codex_app_server_protocol::AskForApproval::to_core),
+            approvals_reviewer: approvals_reviewer
+                .map(codex_app_server_protocol::ApprovalsReviewer::to_core),
             sandbox_mode: sandbox.map(SandboxMode::to_core),
             codex_linux_sandbox_exe: self.arg0_paths.codex_linux_sandbox_exe.clone(),
             main_execve_wrapper_exe: self.arg0_paths.main_execve_wrapper_exe.clone(),
@@ -3142,8 +3159,18 @@ impl CodexMessageProcessor {
         } else {
             read_summary_from_state_db_by_thread_id(&self.config, thread_uuid).await
         };
+        let loaded_rollout_path = loaded_thread
+            .as_ref()
+            .and_then(|thread| thread.rollout_path());
         let mut rollout_path = db_summary.as_ref().map(|summary| summary.path.clone());
-        if rollout_path.is_none() || include_turns {
+        if rollout_path.is_none()
+            && let Some(path) = loaded_rollout_path.as_ref()
+            && tokio::fs::try_exists(path).await.unwrap_or(false)
+        {
+            rollout_path = Some(path.clone());
+        }
+        let should_lookup_rollout = rollout_path.is_none() && loaded_thread.is_none();
+        if should_lookup_rollout {
             rollout_path =
                 match find_thread_path_by_id_str(&self.config.codex_home, &thread_uuid.to_string())
                     .await
@@ -3204,7 +3231,6 @@ impl CodexMessageProcessor {
                 return;
             };
             let config_snapshot = thread.config_snapshot().await;
-            let loaded_rollout_path = thread.rollout_path();
             if include_turns && loaded_rollout_path.is_none() {
                 self.send_invalid_request_error(
                     request_id,
@@ -3350,6 +3376,7 @@ impl CodexMessageProcessor {
             service_tier,
             cwd,
             approval_policy,
+            approvals_reviewer,
             sandbox,
             config: request_overrides,
             base_instructions,
@@ -3383,6 +3410,7 @@ impl CodexMessageProcessor {
             service_tier,
             cwd,
             approval_policy,
+            approvals_reviewer,
             sandbox,
             base_instructions,
             developer_instructions,
@@ -3482,6 +3510,7 @@ impl CodexMessageProcessor {
                     service_tier: session_configured.service_tier,
                     cwd: session_configured.cwd,
                     approval_policy: session_configured.approval_policy.into(),
+                    approvals_reviewer: session_configured.approvals_reviewer.into(),
                     sandbox: session_configured.sandbox_policy.into(),
                     reasoning_effort: session_configured.reasoning_effort,
                 };
@@ -3522,7 +3551,7 @@ impl CodexMessageProcessor {
                 if path.exists() {
                     path
                 } else {
-                    match find_thread_path_by_id_str(
+                    match find_or_unarchive_thread_path_by_id_str(
                         &self.config.codex_home,
                         &existing_thread_id.to_string(),
                     )
@@ -3548,7 +3577,7 @@ impl CodexMessageProcessor {
                     }
                 }
             } else {
-                match find_thread_path_by_id_str(
+                match find_or_unarchive_thread_path_by_id_str(
                     &self.config.codex_home,
                     &existing_thread_id.to_string(),
                 )
@@ -3705,7 +3734,7 @@ impl CodexMessageProcessor {
                 }
             };
 
-            match find_thread_path_by_id_str(
+            match find_or_unarchive_thread_path_by_id_str(
                 &self.config.codex_home,
                 &existing_thread_id.to_string(),
             )
@@ -3821,6 +3850,7 @@ impl CodexMessageProcessor {
             service_tier,
             cwd,
             approval_policy,
+            approvals_reviewer,
             sandbox,
             config: cli_overrides,
             base_instructions,
@@ -3902,6 +3932,7 @@ impl CodexMessageProcessor {
             service_tier,
             cwd,
             approval_policy,
+            approvals_reviewer,
             sandbox,
             base_instructions,
             developer_instructions,
@@ -4070,6 +4101,7 @@ impl CodexMessageProcessor {
             service_tier: session_configured.service_tier,
             cwd: session_configured.cwd,
             approval_policy: session_configured.approval_policy.into(),
+            approvals_reviewer: session_configured.approvals_reviewer.into(),
             sandbox: session_configured.sandbox_policy.into(),
             reasoning_effort: session_configured.reasoning_effort,
         };
@@ -5859,6 +5891,7 @@ impl CodexMessageProcessor {
 
         let has_any_overrides = params.cwd.is_some()
             || params.approval_policy.is_some()
+            || params.approvals_reviewer.is_some()
             || params.sandbox_policy.is_some()
             || params.model.is_some()
             || params.service_tier.is_some()
@@ -5876,6 +5909,9 @@ impl CodexMessageProcessor {
                     Op::OverrideTurnContext {
                         cwd: params.cwd,
                         approval_policy: params.approval_policy.map(AskForApproval::to_core),
+                        approvals_reviewer: params
+                            .approvals_reviewer
+                            .map(codex_app_server_protocol::ApprovalsReviewer::to_core),
                         sandbox_policy: params.sandbox_policy.map(|p| p.to_core()),
                         windows_sandbox_level: None,
                         model: params.model,
@@ -7182,6 +7218,7 @@ async fn handle_pending_thread_resume_request(
         model_provider_id,
         service_tier,
         approval_policy,
+        approvals_reviewer,
         sandbox_policy,
         cwd,
         reasoning_effort,
@@ -7194,6 +7231,7 @@ async fn handle_pending_thread_resume_request(
         service_tier,
         cwd,
         approval_policy: approval_policy.into(),
+        approvals_reviewer: approvals_reviewer.into(),
         sandbox: sandbox_policy.into(),
         reasoning_effort,
     };
@@ -7332,6 +7370,15 @@ fn collect_resume_override_mismatches(
             ));
         }
     }
+    if let Some(requested_review_policy) = request.approvals_reviewer.as_ref() {
+        let active_review_policy: codex_app_server_protocol::ApprovalsReviewer =
+            config_snapshot.approvals_reviewer.into();
+        if requested_review_policy != &active_review_policy {
+            mismatch_details.push(format!(
+                "approvals_reviewer requested={requested_review_policy:?} active={active_review_policy:?}"
+            ));
+        }
+    }
     if let Some(requested_sandbox) = request.sandbox.as_ref() {
         let sandbox_matches = matches!(
             (requested_sandbox, &config_snapshot.sandbox_policy),
@@ -7886,13 +7933,17 @@ pub(crate) async fn read_summary_from_rollout(
         .unwrap_or_else(|| fallback_provider.to_string());
     let git_info = git.as_ref().map(map_git_info);
     let updated_at = updated_at.or_else(|| timestamp.clone());
+    let preview = read_rollout_items_from_rollout(path)
+        .await
+        .map(|items| preview_from_rollout_items(&items))
+        .unwrap_or_default();
 
     Ok(ConversationSummary {
         conversation_id: session_meta.id,
         timestamp,
         updated_at,
         path: path.to_path_buf(),
-        preview: String::new(),
+        preview,
         model_provider,
         cwd: session_meta.cwd,
         cli_version: session_meta.cli_version,
@@ -7910,7 +7961,7 @@ pub(crate) async fn read_rollout_items_from_rollout(
         InitialHistory::Resumed(resumed) => resumed.history,
     };
 
-    Ok(items)
+    Ok(materialize_rollout_items_for_replay(codex_home_from_rollout_path(path), &items).await)
 }
 
 fn extract_conversation_summary(
@@ -8011,6 +8062,137 @@ fn preview_from_rollout_items(items: &[RolloutItem]) -> String {
         .unwrap_or_default()
 }
 
+fn user_message_positions_in_rollout(items: &[RolloutItem]) -> Vec<usize> {
+    let mut user_positions = Vec::new();
+    for (idx, item) in items.iter().enumerate() {
+        match item {
+            RolloutItem::ResponseItem(item)
+                if matches!(
+                    codex_core::parse_turn_item(item),
+                    Some(TurnItem::UserMessage(_))
+                ) =>
+            {
+                user_positions.push(idx);
+            }
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(rollback)) => {
+                let num_turns = usize::try_from(rollback.num_turns).unwrap_or(usize::MAX);
+                let new_len = user_positions.len().saturating_sub(num_turns);
+                user_positions.truncate(new_len);
+            }
+            RolloutItem::ResponseItem(_) => {}
+            RolloutItem::SessionMeta(_)
+            | RolloutItem::ForkReference(_)
+            | RolloutItem::Compacted(_)
+            | RolloutItem::TurnContext(_)
+            | RolloutItem::EventMsg(_) => {}
+        }
+    }
+    user_positions
+}
+
+fn truncate_rollout_before_nth_user_message_from_start(
+    items: &[RolloutItem],
+    n_from_start: usize,
+) -> Vec<RolloutItem> {
+    if n_from_start == usize::MAX {
+        return items.to_vec();
+    }
+
+    let user_positions = user_message_positions_in_rollout(items);
+    if user_positions.len() <= n_from_start {
+        return Vec::new();
+    }
+
+    let cut_idx = user_positions[n_from_start];
+    items[..cut_idx].to_vec()
+}
+
+fn codex_home_from_rollout_path(path: &Path) -> Option<&Path> {
+    path.ancestors().find_map(|ancestor| {
+        let name = ancestor.file_name().and_then(OsStr::to_str)?;
+        if name == codex_core::SESSIONS_SUBDIR || name == codex_core::ARCHIVED_SESSIONS_SUBDIR {
+            ancestor.parent()
+        } else {
+            None
+        }
+    })
+}
+
+async fn materialize_rollout_items_for_replay(
+    codex_home: Option<&Path>,
+    rollout_items: &[RolloutItem],
+) -> Vec<RolloutItem> {
+    const MAX_FORK_REFERENCE_DEPTH: usize = 8;
+
+    let mut materialized = Vec::new();
+    let mut stack: Vec<(Vec<RolloutItem>, usize, usize)> = vec![(rollout_items.to_vec(), 0, 0)];
+
+    while let Some((items, mut idx, depth)) = stack.pop() {
+        while idx < items.len() {
+            match &items[idx] {
+                RolloutItem::ForkReference(reference) => {
+                    if depth >= MAX_FORK_REFERENCE_DEPTH {
+                        warn!(
+                            "skipping fork reference recursion at depth {} for {:?}",
+                            depth, reference.rollout_path
+                        );
+                        idx += 1;
+                        continue;
+                    }
+
+                    let resolved_rollout_path = if let Some(codex_home) = codex_home {
+                        match resolve_fork_reference_rollout_path(
+                            codex_home,
+                            &reference.rollout_path,
+                        )
+                        .await
+                        {
+                            Ok(path) => path,
+                            Err(err) => {
+                                warn!(
+                                    "failed to resolve fork reference rollout {:?}: {err}",
+                                    reference.rollout_path
+                                );
+                                idx += 1;
+                                continue;
+                            }
+                        }
+                    } else {
+                        reference.rollout_path.clone()
+                    };
+                    let parent_history = match RolloutRecorder::get_rollout_history(
+                        &resolved_rollout_path,
+                    )
+                    .await
+                    {
+                        Ok(history) => history,
+                        Err(err) => {
+                            warn!(
+                                "failed to load fork reference rollout {:?} (resolved from {:?}): {err}",
+                                resolved_rollout_path, reference.rollout_path
+                            );
+                            idx += 1;
+                            continue;
+                        }
+                    };
+                    let parent_items = truncate_rollout_before_nth_user_message_from_start(
+                        &parent_history.get_rollout_items(),
+                        reference.nth_user_message,
+                    );
+
+                    stack.push((items, idx + 1, depth));
+                    stack.push((parent_items, 0, depth + 1));
+                    break;
+                }
+                item => materialized.push(item.clone()),
+            }
+            idx += 1;
+        }
+    }
+
+    materialized
+}
+
 fn with_thread_spawn_agent_metadata(
     source: codex_protocol::protocol::SessionSource,
     agent_nickname: Option<String>,
@@ -8237,6 +8419,7 @@ mod tests {
             service_tier: Some(Some(codex_protocol::config_types::ServiceTier::Fast)),
             cwd: None,
             approval_policy: None,
+            approvals_reviewer: None,
             sandbox: None,
             config: None,
             base_instructions: None,
@@ -8249,9 +8432,11 @@ mod tests {
             model_provider_id: "openai".to_string(),
             service_tier: Some(codex_protocol::config_types::ServiceTier::Flex),
             approval_policy: codex_protocol::protocol::AskForApproval::OnRequest,
+            approvals_reviewer: codex_protocol::config_types::ApprovalsReviewer::User,
             sandbox_policy: codex_protocol::protocol::SandboxPolicy::DangerFullAccess,
             cwd: PathBuf::from("/tmp"),
             ephemeral: false,
+            agent_use_function_call_inbox: false,
             reasoning_effort: None,
             personality: None,
             session_source: SessionSource::Cli,

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

@@ -0,0 +1,365 @@
+use crate::error_code::INTERNAL_ERROR_CODE;
+use crate::error_code::INVALID_REQUEST_ERROR_CODE;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD;
+use codex_app_server_protocol::FsCopyParams;
+use codex_app_server_protocol::FsCopyResponse;
+use codex_app_server_protocol::FsCreateDirectoryParams;
+use codex_app_server_protocol::FsCreateDirectoryResponse;
+use codex_app_server_protocol::FsGetMetadataParams;
+use codex_app_server_protocol::FsGetMetadataResponse;
+use codex_app_server_protocol::FsReadDirectoryEntry;
+use codex_app_server_protocol::FsReadDirectoryParams;
+use codex_app_server_protocol::FsReadDirectoryResponse;
+use codex_app_server_protocol::FsReadFileParams;
+use codex_app_server_protocol::FsReadFileResponse;
+use codex_app_server_protocol::FsRemoveParams;
+use codex_app_server_protocol::FsRemoveResponse;
+use codex_app_server_protocol::FsWriteFileParams;
+use codex_app_server_protocol::FsWriteFileResponse;
+use codex_app_server_protocol::JSONRPCErrorError;
+use std::io;
+use std::path::Component;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::SystemTime;
+use std::time::UNIX_EPOCH;
+use walkdir::WalkDir;
+
+#[derive(Clone, Default)]
+pub(crate) struct FsApi;
+
+impl FsApi {
+    pub(crate) async fn read_file(
+        &self,
+        params: FsReadFileParams,
+    ) -> Result<FsReadFileResponse, JSONRPCErrorError> {
+        let bytes = tokio::fs::read(params.path).await.map_err(map_io_error)?;
+        Ok(FsReadFileResponse {
+            data_base64: STANDARD.encode(bytes),
+        })
+    }
+
+    pub(crate) async fn write_file(
+        &self,
+        params: FsWriteFileParams,
+    ) -> Result<FsWriteFileResponse, JSONRPCErrorError> {
+        let bytes = STANDARD.decode(params.data_base64).map_err(|err| {
+            invalid_request(format!(
+                "fs/writeFile requires valid base64 dataBase64: {err}"
+            ))
+        })?;
+        tokio::fs::write(params.path, bytes)
+            .await
+            .map_err(map_io_error)?;
+        Ok(FsWriteFileResponse {})
+    }
+
+    pub(crate) async fn create_directory(
+        &self,
+        params: FsCreateDirectoryParams,
+    ) -> Result<FsCreateDirectoryResponse, JSONRPCErrorError> {
+        if params.recursive.unwrap_or(true) {
+            tokio::fs::create_dir_all(params.path)
+                .await
+                .map_err(map_io_error)?;
+        } else {
+            tokio::fs::create_dir(params.path)
+                .await
+                .map_err(map_io_error)?;
+        }
+        Ok(FsCreateDirectoryResponse {})
+    }
+
+    pub(crate) async fn get_metadata(
+        &self,
+        params: FsGetMetadataParams,
+    ) -> Result<FsGetMetadataResponse, JSONRPCErrorError> {
+        let metadata = tokio::fs::metadata(params.path)
+            .await
+            .map_err(map_io_error)?;
+        Ok(FsGetMetadataResponse {
+            is_directory: metadata.is_dir(),
+            is_file: metadata.is_file(),
+            created_at_ms: metadata.created().ok().map_or(0, system_time_to_unix_ms),
+            modified_at_ms: metadata.modified().ok().map_or(0, system_time_to_unix_ms),
+        })
+    }
+
+    pub(crate) async fn read_directory(
+        &self,
+        params: FsReadDirectoryParams,
+    ) -> Result<FsReadDirectoryResponse, JSONRPCErrorError> {
+        let mut entries = Vec::new();
+        let mut read_dir = tokio::fs::read_dir(params.path)
+            .await
+            .map_err(map_io_error)?;
+        while let Some(entry) = read_dir.next_entry().await.map_err(map_io_error)? {
+            let metadata = tokio::fs::metadata(entry.path())
+                .await
+                .map_err(map_io_error)?;
+            entries.push(FsReadDirectoryEntry {
+                file_name: entry.file_name().to_string_lossy().into_owned(),
+                is_directory: metadata.is_dir(),
+                is_file: metadata.is_file(),
+            });
+        }
+        Ok(FsReadDirectoryResponse { entries })
+    }
+
+    pub(crate) async fn remove(
+        &self,
+        params: FsRemoveParams,
+    ) -> Result<FsRemoveResponse, JSONRPCErrorError> {
+        let path = params.path.as_path();
+        let recursive = params.recursive.unwrap_or(true);
+        let force = params.force.unwrap_or(true);
+        match tokio::fs::symlink_metadata(path).await {
+            Ok(metadata) => {
+                let file_type = metadata.file_type();
+                if file_type.is_dir() {
+                    if recursive {
+                        tokio::fs::remove_dir_all(path)
+                            .await
+                            .map_err(map_io_error)?;
+                    } else {
+                        tokio::fs::remove_dir(path).await.map_err(map_io_error)?;
+                    }
+                } else {
+                    tokio::fs::remove_file(path).await.map_err(map_io_error)?;
+                }
+                Ok(FsRemoveResponse {})
+            }
+            Err(err) if err.kind() == io::ErrorKind::NotFound && force => Ok(FsRemoveResponse {}),
+            Err(err) => Err(map_io_error(err)),
+        }
+    }
+
+    pub(crate) async fn copy(
+        &self,
+        params: FsCopyParams,
+    ) -> Result<FsCopyResponse, JSONRPCErrorError> {
+        let FsCopyParams {
+            source_path,
+            destination_path,
+            recursive,
+        } = params;
+        tokio::task::spawn_blocking(move || -> Result<(), JSONRPCErrorError> {
+            let metadata =
+                std::fs::symlink_metadata(source_path.as_path()).map_err(map_io_error)?;
+            let file_type = metadata.file_type();
+
+            if file_type.is_dir() {
+                if !recursive {
+                    return Err(invalid_request(
+                        "fs/copy requires recursive: true when sourcePath is a directory",
+                    ));
+                }
+                if destination_is_same_or_descendant_of_source(
+                    source_path.as_path(),
+                    destination_path.as_path(),
+                )
+                .map_err(map_io_error)?
+                {
+                    return Err(invalid_request(
+                        "fs/copy cannot copy a directory to itself or one of its descendants",
+                    ));
+                }
+                copy_dir_recursive(source_path.as_path(), destination_path.as_path())
+                    .map_err(map_io_error)?;
+                return Ok(());
+            }
+
+            if file_type.is_symlink() {
+                copy_symlink(source_path.as_path(), destination_path.as_path())
+                    .map_err(map_io_error)?;
+                return Ok(());
+            }
+
+            if file_type.is_file() {
+                std::fs::copy(source_path.as_path(), destination_path.as_path())
+                    .map_err(map_io_error)?;
+                return Ok(());
+            }
+
+            Err(invalid_request(
+                "fs/copy only supports regular files, directories, and symlinks",
+            ))
+        })
+        .await
+        .map_err(map_join_error)??;
+        Ok(FsCopyResponse {})
+    }
+}
+
+fn copy_dir_recursive(source: &Path, target: &Path) -> io::Result<()> {
+    for entry in WalkDir::new(source) {
+        let entry = entry.map_err(|err| {
+            if let Some(io_err) = err.io_error() {
+                io::Error::new(io_err.kind(), io_err.to_string())
+            } else {
+                io::Error::other(err.to_string())
+            }
+        })?;
+        let relative_path = entry.path().strip_prefix(source).map_err(|err| {
+            io::Error::other(format!(
+                "failed to compute relative path for {} under {}: {err}",
+                entry.path().display(),
+                source.display()
+            ))
+        })?;
+        let target_path = target.join(relative_path);
+        let file_type = entry.file_type();
+
+        if file_type.is_dir() {
+            std::fs::create_dir_all(&target_path)?;
+            continue;
+        }
+
+        if file_type.is_file() {
+            std::fs::copy(entry.path(), &target_path)?;
+            continue;
+        }
+
+        if file_type.is_symlink() {
+            copy_symlink(entry.path(), &target_path)?;
+            continue;
+        }
+
+        // For now ignore special files such as FIFOs, sockets, and device nodes during recursive copies.
+    }
+    Ok(())
+}
+
+fn destination_is_same_or_descendant_of_source(
+    source: &Path,
+    destination: &Path,
+) -> io::Result<bool> {
+    let source = std::fs::canonicalize(source)?;
+    let destination = resolve_copy_destination_path(destination)?;
+    Ok(destination.starts_with(&source))
+}
+
+fn resolve_copy_destination_path(path: &Path) -> io::Result<PathBuf> {
+    let mut normalized = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::Prefix(prefix) => normalized.push(prefix.as_os_str()),
+            Component::RootDir => normalized.push(component.as_os_str()),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                normalized.pop();
+            }
+            Component::Normal(part) => normalized.push(part),
+        }
+    }
+
+    let mut unresolved_suffix = Vec::new();
+    let mut existing_path = normalized.as_path();
+    while !existing_path.exists() {
+        let Some(file_name) = existing_path.file_name() else {
+            break;
+        };
+        unresolved_suffix.push(file_name.to_os_string());
+        let Some(parent) = existing_path.parent() else {
+            break;
+        };
+        existing_path = parent;
+    }
+
+    let mut resolved = std::fs::canonicalize(existing_path)?;
+    for file_name in unresolved_suffix.iter().rev() {
+        resolved.push(file_name);
+    }
+    Ok(resolved)
+}
+
+fn copy_symlink(source: &Path, target: &Path) -> io::Result<()> {
+    let link_target = std::fs::read_link(source)?;
+    #[cfg(unix)]
+    {
+        std::os::unix::fs::symlink(&link_target, target)
+    }
+    #[cfg(windows)]
+    {
+        if symlink_points_to_directory(source)? {
+            std::os::windows::fs::symlink_dir(&link_target, target)
+        } else {
+            std::os::windows::fs::symlink_file(&link_target, target)
+        }
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = link_target;
+        let _ = target;
+        Err(io::Error::new(
+            io::ErrorKind::Unsupported,
+            "copying symlinks is unsupported on this platform",
+        ))
+    }
+}
+
+#[cfg(windows)]
+fn symlink_points_to_directory(source: &Path) -> io::Result<bool> {
+    use std::os::windows::fs::FileTypeExt;
+
+    Ok(std::fs::symlink_metadata(source)?
+        .file_type()
+        .is_symlink_dir())
+}
+
+fn system_time_to_unix_ms(time: SystemTime) -> i64 {
+    time.duration_since(UNIX_EPOCH)
+        .ok()
+        .and_then(|duration| i64::try_from(duration.as_millis()).ok())
+        .unwrap_or(0)
+}
+
+pub(crate) fn invalid_request(message: impl Into<String>) -> JSONRPCErrorError {
+    JSONRPCErrorError {
+        code: INVALID_REQUEST_ERROR_CODE,
+        message: message.into(),
+        data: None,
+    }
+}
+
+fn map_join_error(err: tokio::task::JoinError) -> JSONRPCErrorError {
+    JSONRPCErrorError {
+        code: INTERNAL_ERROR_CODE,
+        message: format!("filesystem task failed: {err}"),
+        data: None,
+    }
+}
+
+pub(crate) fn map_io_error(err: io::Error) -> JSONRPCErrorError {
+    JSONRPCErrorError {
+        code: INTERNAL_ERROR_CODE,
+        message: err.to_string(),
+        data: None,
+    }
+}
+
+#[cfg(all(test, windows))]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn symlink_points_to_directory_handles_dangling_directory_symlinks() -> io::Result<()> {
+        use std::os::windows::fs::symlink_dir;
+
+        let temp_dir = tempfile::TempDir::new()?;
+        let source_dir = temp_dir.path().join("source");
+        let link_path = temp_dir.path().join("source-link");
+        std::fs::create_dir(&source_dir)?;
+
+        if symlink_dir(&source_dir, &link_path).is_err() {
+            return Ok(());
+        }
+
+        std::fs::remove_dir(&source_dir)?;
+
+        assert_eq!(symlink_points_to_directory(&link_path)?, true);
+        Ok(())
+    }
+}

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

@@ -65,6 +65,7 @@ mod dynamic_tools;
 mod error_code;
 mod external_agent_config_api;
 mod filters;
+mod fs_api;
 mod fuzzy_file_search;
 pub mod in_process;
 mod message_processor;

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

@@ -10,6 +10,7 @@ use crate::codex_message_processor::CodexMessageProcessorArgs;
 use crate::config_api::ConfigApi;
 use crate::error_code::INVALID_REQUEST_ERROR_CODE;
 use crate::external_agent_config_api::ExternalAgentConfigApi;
+use crate::fs_api::FsApi;
 use crate::outgoing_message::ConnectionId;
 use crate::outgoing_message::ConnectionRequestId;
 use crate::outgoing_message::OutgoingMessageSender;
@@ -29,6 +30,13 @@ use codex_app_server_protocol::ConfigWarningNotification;
 use codex_app_server_protocol::ExperimentalApi;
 use codex_app_server_protocol::ExternalAgentConfigDetectParams;
 use codex_app_server_protocol::ExternalAgentConfigImportParams;
+use codex_app_server_protocol::FsCopyParams;
+use codex_app_server_protocol::FsCreateDirectoryParams;
+use codex_app_server_protocol::FsGetMetadataParams;
+use codex_app_server_protocol::FsReadDirectoryParams;
+use codex_app_server_protocol::FsReadFileParams;
+use codex_app_server_protocol::FsRemoveParams;
+use codex_app_server_protocol::FsWriteFileParams;
 use codex_app_server_protocol::InitializeResponse;
 use codex_app_server_protocol::JSONRPCError;
 use codex_app_server_protocol::JSONRPCErrorError;
@@ -139,6 +147,7 @@ pub(crate) struct MessageProcessor {
     codex_message_processor: CodexMessageProcessor,
     config_api: ConfigApi,
     external_agent_config_api: ExternalAgentConfigApi,
+    fs_api: FsApi,
     auth_manager: Arc<AuthManager>,
     config: Arc<Config>,
     config_warnings: Arc<Vec<ConfigWarningNotification>>,
@@ -200,6 +209,8 @@ impl MessageProcessor {
                     config.as_ref(),
                     auth_manager.clone(),
                     session_source,
+                    config.model_catalog.clone(),
+                    config.custom_models.clone(),
                     CollaborationModesConfig {
                         default_mode_request_user_input: config
                             .features
@@ -244,12 +255,14 @@ impl MessageProcessor {
             analytics_events_client,
         );
         let external_agent_config_api = ExternalAgentConfigApi::new(config.codex_home.clone());
+        let fs_api = FsApi;
 
         Self {
             outgoing,
             codex_message_processor,
             config_api,
             external_agent_config_api,
+            fs_api,
             auth_manager,
             config,
             config_warnings: Arc::new(config_warnings),
@@ -666,6 +679,76 @@ impl MessageProcessor {
                 })
                 .await;
             }
+            ClientRequest::FsReadFile { request_id, params } => {
+                self.handle_fs_read_file(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
+            ClientRequest::FsWriteFile { request_id, params } => {
+                self.handle_fs_write_file(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
+            ClientRequest::FsCreateDirectory { request_id, params } => {
+                self.handle_fs_create_directory(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
+            ClientRequest::FsGetMetadata { request_id, params } => {
+                self.handle_fs_get_metadata(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
+            ClientRequest::FsReadDirectory { request_id, params } => {
+                self.handle_fs_read_directory(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
+            ClientRequest::FsRemove { request_id, params } => {
+                self.handle_fs_remove(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
+            ClientRequest::FsCopy { request_id, params } => {
+                self.handle_fs_copy(
+                    ConnectionRequestId {
+                        connection_id,
+                        request_id,
+                    },
+                    params,
+                )
+                .await;
+            }
             other => {
                 // Box the delegated future so this wrapper's async state machine does not
                 // inline the full `CodexMessageProcessor::process_request` future, which
@@ -752,6 +835,71 @@ impl MessageProcessor {
             Err(error) => self.outgoing.send_error(request_id, error).await,
         }
     }
+
+    async fn handle_fs_read_file(&self, request_id: ConnectionRequestId, params: FsReadFileParams) {
+        match self.fs_api.read_file(params).await {
+            Ok(response) => self.outgoing.send_response(request_id, response).await,
+            Err(error) => self.outgoing.send_error(request_id, error).await,
+        }
+    }
+
+    async fn handle_fs_write_file(
+        &self,
+        request_id: ConnectionRequestId,
+        params: FsWriteFileParams,
+    ) {
+        match self.fs_api.write_file(params).await {
+            Ok(response) => self.outgoing.send_response(request_id, response).await,
+            Err(error) => self.outgoing.send_error(request_id, error).await,
+        }
+    }
+
+    async fn handle_fs_create_directory(
+        &self,
+        request_id: ConnectionRequestId,
+        params: FsCreateDirectoryParams,
+    ) {
+        match self.fs_api.create_directory(params).await {
+            Ok(response) => self.outgoing.send_response(request_id, response).await,
+            Err(error) => self.outgoing.send_error(request_id, error).await,
+        }
+    }
+
+    async fn handle_fs_get_metadata(
+        &self,
+        request_id: ConnectionRequestId,
+        params: FsGetMetadataParams,
+    ) {
+        match self.fs_api.get_metadata(params).await {
+            Ok(response) => self.outgoing.send_response(request_id, response).await,
+            Err(error) => self.outgoing.send_error(request_id, error).await,
+        }
+    }
+
+    async fn handle_fs_read_directory(
+        &self,
+        request_id: ConnectionRequestId,
+        params: FsReadDirectoryParams,
+    ) {
+        match self.fs_api.read_directory(params).await {
+            Ok(response) => self.outgoing.send_response(request_id, response).await,
+            Err(error) => self.outgoing.send_error(request_id, error).await,
+        }
+    }
+
+    async fn handle_fs_remove(&self, request_id: ConnectionRequestId, params: FsRemoveParams) {
+        match self.fs_api.remove(params).await {
+            Ok(response) => self.outgoing.send_response(request_id, response).await,
+            Err(error) => self.outgoing.send_error(request_id, error).await,
+        }
+    }
+
+    async fn handle_fs_copy(&self, request_id: ConnectionRequestId, params: FsCopyParams) {
+        match self.fs_api.copy(params).await {
+            Ok(response) => self.outgoing.send_response(request_id, response).await,
+            Err(error) => self.outgoing.send_error(request_id, error).await,
+        }
+    }
 }
 
 #[cfg(test)]

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

@@ -282,26 +282,6 @@ fn find_rpc_span_with_trace<'a>(
         })
 }
 
-fn find_span_with_trace<'a, F>(
-    spans: &'a [SpanData],
-    trace_id: TraceId,
-    description: &str,
-    predicate: F,
-) -> &'a SpanData
-where
-    F: Fn(&SpanData) -> bool,
-{
-    spans
-        .iter()
-        .find(|span| span.span_context.trace_id() == trace_id && predicate(span))
-        .unwrap_or_else(|| {
-            panic!(
-                "missing span matching {description} for trace={trace_id}; exported spans:\n{}",
-                format_spans(spans)
-            )
-        })
-}
-
 fn format_spans(spans: &[SpanData]) -> String {
     spans
         .iter()
@@ -346,19 +326,6 @@ fn span_depth_from_ancestor(
     None
 }
 
-fn assert_span_descends_from(spans: &[SpanData], child: &SpanData, ancestor: &SpanData) {
-    if span_depth_from_ancestor(spans, child, ancestor).is_some() {
-        return;
-    }
-
-    panic!(
-        "span {} does not descend from {}; exported spans:\n{}",
-        child.name,
-        ancestor.name,
-        format_spans(spans)
-    );
-}
-
 fn assert_has_internal_descendant_at_min_depth(
     spans: &[SpanData],
     ancestor: &SpanData,
@@ -593,6 +560,7 @@ async fn turn_start_jsonrpc_span_parents_core_turn_spans() -> Result<()> {
                     cwd: None,
                     approval_policy: None,
                     sandbox_policy: None,
+                    approvals_reviewer: None,
                     model: None,
                     service_tier: None,
                     effort: None,
@@ -610,24 +578,23 @@ async fn turn_start_jsonrpc_span_parents_core_turn_spans() -> Result<()> {
             span.span_kind == SpanKind::Server
                 && span_attr(span, "rpc.method") == Some("turn/start")
                 && span.span_context.trace_id() == remote_trace_id
-        }) && spans.iter().any(|span| {
-            span_attr(span, "codex.op") == Some("user_input")
-                && span.span_context.trace_id() == remote_trace_id
         })
     })
     .await;
 
     let server_request_span =
         find_rpc_span_with_trace(&spans, SpanKind::Server, "turn/start", remote_trace_id);
-    let core_turn_span =
-        find_span_with_trace(&spans, remote_trace_id, "codex.op=user_input", |span| {
-            span_attr(span, "codex.op") == Some("user_input")
-        });
 
     assert_eq!(server_request_span.parent_span_id, remote_parent_span_id);
     assert!(server_request_span.parent_span_is_remote);
     assert_eq!(server_request_span.span_context.trace_id(), remote_trace_id);
-    assert_span_descends_from(&spans, core_turn_span, server_request_span);
+    assert!(
+        spans.iter().any(|span| {
+            span.span_kind == SpanKind::Internal && span.span_context.trace_id() == remote_trace_id
+        }),
+        "expected at least one internal turn-processing span to inherit the remote trace; exported spans:\n{}",
+        format_spans(&spans)
+    );
     harness.shutdown().await;
 
     Ok(())

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

@@ -49,6 +49,11 @@ stream_max_retries = 0
 "#
         )
     };
+    let openai_base_url_line = if model_provider_id == "openai" {
+        format!("openai_base_url = \"{server_uri}/v1\"\n")
+    } else {
+        String::new()
+    };
     // Phase 3: write the final config file.
     let config_toml = codex_home.join("config.toml");
     std::fs::write(
@@ -62,6 +67,7 @@ compact_prompt = "{compact_prompt}"
 model_auto_compact_token_limit = {auto_compact_limit}
 
 model_provider = "{model_provider_id}"
+{openai_base_url_line}
 
 [features]
 {feature_entries}

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

@@ -25,6 +25,13 @@ use codex_app_server_protocol::ConfigReadParams;
 use codex_app_server_protocol::ConfigValueWriteParams;
 use codex_app_server_protocol::ExperimentalFeatureListParams;
 use codex_app_server_protocol::FeedbackUploadParams;
+use codex_app_server_protocol::FsCopyParams;
+use codex_app_server_protocol::FsCreateDirectoryParams;
+use codex_app_server_protocol::FsGetMetadataParams;
+use codex_app_server_protocol::FsReadDirectoryParams;
+use codex_app_server_protocol::FsReadFileParams;
+use codex_app_server_protocol::FsRemoveParams;
+use codex_app_server_protocol::FsWriteFileParams;
 use codex_app_server_protocol::GetAccountParams;
 use codex_app_server_protocol::GetAuthStatusParams;
 use codex_app_server_protocol::GetConversationSummaryParams;
@@ -709,6 +716,56 @@ impl McpProcess {
         self.send_request("config/batchWrite", params).await
     }
 
+    pub async fn send_fs_read_file_request(
+        &mut self,
+        params: FsReadFileParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("fs/readFile", params).await
+    }
+
+    pub async fn send_fs_write_file_request(
+        &mut self,
+        params: FsWriteFileParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("fs/writeFile", params).await
+    }
+
+    pub async fn send_fs_create_directory_request(
+        &mut self,
+        params: FsCreateDirectoryParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("fs/createDirectory", params).await
+    }
+
+    pub async fn send_fs_get_metadata_request(
+        &mut self,
+        params: FsGetMetadataParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("fs/getMetadata", params).await
+    }
+
+    pub async fn send_fs_read_directory_request(
+        &mut self,
+        params: FsReadDirectoryParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("fs/readDirectory", params).await
+    }
+
+    pub async fn send_fs_remove_request(&mut self, params: FsRemoveParams) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("fs/remove", params).await
+    }
+
+    pub async fn send_fs_copy_request(&mut self, params: FsCopyParams) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("fs/copy", params).await
+    }
+
     /// Send an `account/logout` JSON-RPC request.
     pub async fn send_logout_account_request(&mut self) -> anyhow::Result<i64> {
         self.send_request("account/logout", None).await

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

@@ -15,6 +15,7 @@ use std::path::Path;
 fn preset_to_info(preset: &ModelPreset, priority: i32) -> ModelInfo {
     ModelInfo {
         slug: preset.id.clone(),
+        request_model: None,
         display_name: preset.display_name.clone(),
         description: Some(preset.description.clone()),
         default_reasoning_level: Some(preset.default_reasoning_effort),

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

@@ -158,15 +158,7 @@ async fn auto_compaction_remote_emits_started_and_completed_items() -> Result<()
         AuthCredentialsStoreMode::File,
     )?;
 
-    let server_base_url = format!("{}/v1", server.uri());
-    let mut mcp = McpProcess::new_with_env(
-        codex_home.path(),
-        &[
-            ("OPENAI_BASE_URL", Some(server_base_url.as_str())),
-            ("OPENAI_API_KEY", None),
-        ],
-    )
-    .await?;
+    let mut mcp = McpProcess::new_with_env(codex_home.path(), &[("OPENAI_API_KEY", None)]).await?;
     timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
 
     let thread_id = start_thread(&mut mcp).await?;

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

@@ -0,0 +1,613 @@
+use anyhow::Context;
+use anyhow::Result;
+use app_test_support::McpProcess;
+use app_test_support::to_response;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD;
+use codex_app_server_protocol::FsCopyParams;
+use codex_app_server_protocol::FsGetMetadataResponse;
+use codex_app_server_protocol::FsReadDirectoryEntry;
+use codex_app_server_protocol::FsReadFileResponse;
+use codex_app_server_protocol::FsWriteFileParams;
+use codex_app_server_protocol::RequestId;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use std::path::PathBuf;
+use tempfile::TempDir;
+use tokio::time::Duration;
+use tokio::time::timeout;
+
+#[cfg(unix)]
+use std::os::unix::fs::symlink;
+#[cfg(unix)]
+use std::process::Command;
+
+const DEFAULT_READ_TIMEOUT: Duration = Duration::from_secs(10);
+
+async fn initialized_mcp(codex_home: &TempDir) -> Result<McpProcess> {
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+    Ok(mcp)
+}
+
+async fn expect_error_message(
+    mcp: &mut McpProcess,
+    request_id: i64,
+    expected_message: &str,
+) -> Result<()> {
+    let error = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_error_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert_eq!(error.error.message, expected_message);
+    Ok(())
+}
+
+#[allow(clippy::expect_used)]
+fn absolute_path(path: PathBuf) -> AbsolutePathBuf {
+    assert!(
+        path.is_absolute(),
+        "path must be absolute: {}",
+        path.display()
+    );
+    AbsolutePathBuf::try_from(path).expect("path should be absolute")
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_get_metadata_returns_only_used_fields() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let file_path = codex_home.path().join("note.txt");
+    std::fs::write(&file_path, "hello")?;
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let request_id = mcp
+        .send_fs_get_metadata_request(codex_app_server_protocol::FsGetMetadataParams {
+            path: absolute_path(file_path.clone()),
+        })
+        .await?;
+    let response = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+
+    let result = response
+        .result
+        .as_object()
+        .context("fs/getMetadata result should be an object")?;
+    let mut keys = result.keys().cloned().collect::<Vec<_>>();
+    keys.sort();
+    assert_eq!(
+        keys,
+        vec![
+            "createdAtMs".to_string(),
+            "isDirectory".to_string(),
+            "isFile".to_string(),
+            "modifiedAtMs".to_string(),
+        ]
+    );
+
+    let stat: FsGetMetadataResponse = to_response(response)?;
+    assert_eq!(
+        stat,
+        FsGetMetadataResponse {
+            is_directory: false,
+            is_file: true,
+            created_at_ms: stat.created_at_ms,
+            modified_at_ms: stat.modified_at_ms,
+        }
+    );
+    assert!(
+        stat.modified_at_ms > 0,
+        "modifiedAtMs should be populated for existing files"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_methods_cover_current_fs_utils_surface() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let source_dir = codex_home.path().join("source");
+    let nested_dir = source_dir.join("nested");
+    let source_file = source_dir.join("root.txt");
+    let copied_dir = codex_home.path().join("copied");
+    let copy_file_path = codex_home.path().join("copy.txt");
+    let nested_file = nested_dir.join("note.txt");
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+
+    let create_directory_request_id = mcp
+        .send_fs_create_directory_request(codex_app_server_protocol::FsCreateDirectoryParams {
+            path: absolute_path(nested_dir.clone()),
+            recursive: None,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(create_directory_request_id)),
+    )
+    .await??;
+
+    let write_request_id = mcp
+        .send_fs_write_file_request(FsWriteFileParams {
+            path: absolute_path(nested_file.clone()),
+            data_base64: STANDARD.encode("hello from app-server"),
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(write_request_id)),
+    )
+    .await??;
+
+    let root_write_request_id = mcp
+        .send_fs_write_file_request(FsWriteFileParams {
+            path: absolute_path(source_file.clone()),
+            data_base64: STANDARD.encode("hello from source root"),
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(root_write_request_id)),
+    )
+    .await??;
+
+    let read_request_id = mcp
+        .send_fs_read_file_request(codex_app_server_protocol::FsReadFileParams {
+            path: absolute_path(nested_file.clone()),
+        })
+        .await?;
+    let read_response: FsReadFileResponse = to_response(
+        timeout(
+            DEFAULT_READ_TIMEOUT,
+            mcp.read_stream_until_response_message(RequestId::Integer(read_request_id)),
+        )
+        .await??,
+    )?;
+    assert_eq!(
+        read_response,
+        FsReadFileResponse {
+            data_base64: STANDARD.encode("hello from app-server"),
+        }
+    );
+
+    let copy_file_request_id = mcp
+        .send_fs_copy_request(FsCopyParams {
+            source_path: absolute_path(nested_file.clone()),
+            destination_path: absolute_path(copy_file_path.clone()),
+            recursive: false,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(copy_file_request_id)),
+    )
+    .await??;
+    assert_eq!(
+        std::fs::read_to_string(&copy_file_path)?,
+        "hello from app-server"
+    );
+
+    let copy_dir_request_id = mcp
+        .send_fs_copy_request(FsCopyParams {
+            source_path: absolute_path(source_dir.clone()),
+            destination_path: absolute_path(copied_dir.clone()),
+            recursive: true,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(copy_dir_request_id)),
+    )
+    .await??;
+    assert_eq!(
+        std::fs::read_to_string(copied_dir.join("nested").join("note.txt"))?,
+        "hello from app-server"
+    );
+
+    let read_directory_request_id = mcp
+        .send_fs_read_directory_request(codex_app_server_protocol::FsReadDirectoryParams {
+            path: absolute_path(source_dir.clone()),
+        })
+        .await?;
+    let readdir_response = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(read_directory_request_id)),
+    )
+    .await??;
+    let mut entries =
+        to_response::<codex_app_server_protocol::FsReadDirectoryResponse>(readdir_response)?
+            .entries;
+    entries.sort_by(|left, right| left.file_name.cmp(&right.file_name));
+    assert_eq!(
+        entries,
+        vec![
+            FsReadDirectoryEntry {
+                file_name: "nested".to_string(),
+                is_directory: true,
+                is_file: false,
+            },
+            FsReadDirectoryEntry {
+                file_name: "root.txt".to_string(),
+                is_directory: false,
+                is_file: true,
+            },
+        ]
+    );
+
+    let remove_request_id = mcp
+        .send_fs_remove_request(codex_app_server_protocol::FsRemoveParams {
+            path: absolute_path(copied_dir.clone()),
+            recursive: None,
+            force: None,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(remove_request_id)),
+    )
+    .await??;
+    assert!(
+        !copied_dir.exists(),
+        "fs/remove should default to recursive+force for directory trees"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_write_file_accepts_base64_bytes() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let file_path = codex_home.path().join("blob.bin");
+    let bytes = [0_u8, 1, 2, 255];
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let write_request_id = mcp
+        .send_fs_write_file_request(FsWriteFileParams {
+            path: absolute_path(file_path.clone()),
+            data_base64: STANDARD.encode(bytes),
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(write_request_id)),
+    )
+    .await??;
+    assert_eq!(std::fs::read(&file_path)?, bytes);
+
+    let read_request_id = mcp
+        .send_fs_read_file_request(codex_app_server_protocol::FsReadFileParams {
+            path: absolute_path(file_path),
+        })
+        .await?;
+    let read_response: FsReadFileResponse = to_response(
+        timeout(
+            DEFAULT_READ_TIMEOUT,
+            mcp.read_stream_until_response_message(RequestId::Integer(read_request_id)),
+        )
+        .await??,
+    )?;
+    assert_eq!(
+        read_response,
+        FsReadFileResponse {
+            data_base64: STANDARD.encode(bytes),
+        }
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_write_file_rejects_invalid_base64() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let file_path = codex_home.path().join("blob.bin");
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let request_id = mcp
+        .send_fs_write_file_request(FsWriteFileParams {
+            path: absolute_path(file_path),
+            data_base64: "%%%".to_string(),
+        })
+        .await?;
+    let error = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_error_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert!(
+        error
+            .error
+            .message
+            .starts_with("fs/writeFile requires valid base64 dataBase64:"),
+        "unexpected error message: {}",
+        error.error.message
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_methods_reject_relative_paths() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let absolute_file = codex_home.path().join("absolute.txt");
+    std::fs::write(&absolute_file, "hello")?;
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+
+    let read_id = mcp
+        .send_raw_request("fs/readFile", Some(json!({ "path": "relative.txt" })))
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        read_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    let write_id = mcp
+        .send_raw_request(
+            "fs/writeFile",
+            Some(json!({
+                "path": "relative.txt",
+                "dataBase64": STANDARD.encode("hello"),
+            })),
+        )
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        write_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    let create_directory_id = mcp
+        .send_raw_request(
+            "fs/createDirectory",
+            Some(json!({
+                "path": "relative-dir",
+                "recursive": null,
+            })),
+        )
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        create_directory_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    let get_metadata_id = mcp
+        .send_raw_request("fs/getMetadata", Some(json!({ "path": "relative.txt" })))
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        get_metadata_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    let read_directory_id = mcp
+        .send_raw_request("fs/readDirectory", Some(json!({ "path": "relative-dir" })))
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        read_directory_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    let remove_id = mcp
+        .send_raw_request(
+            "fs/remove",
+            Some(json!({
+                "path": "relative.txt",
+                "recursive": null,
+                "force": null,
+            })),
+        )
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        remove_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    let copy_source_id = mcp
+        .send_raw_request(
+            "fs/copy",
+            Some(json!({
+                "sourcePath": "relative.txt",
+                "destinationPath": absolute_file.clone(),
+                "recursive": false,
+            })),
+        )
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        copy_source_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    let copy_destination_id = mcp
+        .send_raw_request(
+            "fs/copy",
+            Some(json!({
+                "sourcePath": absolute_file,
+                "destinationPath": "relative-copy.txt",
+                "recursive": false,
+            })),
+        )
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        copy_destination_id,
+        "Invalid request: AbsolutePathBuf deserialized without a base path",
+    )
+    .await?;
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_copy_rejects_directory_without_recursive() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let source_dir = codex_home.path().join("source");
+    std::fs::create_dir_all(&source_dir)?;
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let request_id = mcp
+        .send_fs_copy_request(FsCopyParams {
+            source_path: absolute_path(source_dir),
+            destination_path: absolute_path(codex_home.path().join("dest")),
+            recursive: false,
+        })
+        .await?;
+    let error = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_error_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert_eq!(
+        error.error.message,
+        "fs/copy requires recursive: true when sourcePath is a directory"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_copy_rejects_copying_directory_into_descendant() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let source_dir = codex_home.path().join("source");
+    std::fs::create_dir_all(source_dir.join("nested"))?;
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let request_id = mcp
+        .send_fs_copy_request(FsCopyParams {
+            source_path: absolute_path(source_dir.clone()),
+            destination_path: absolute_path(source_dir.join("nested").join("copy")),
+            recursive: true,
+        })
+        .await?;
+    let error = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_error_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+    assert_eq!(
+        error.error.message,
+        "fs/copy cannot copy a directory to itself or one of its descendants"
+    );
+
+    Ok(())
+}
+
+#[cfg(unix)]
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_copy_preserves_symlinks_in_recursive_copy() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let source_dir = codex_home.path().join("source");
+    let nested_dir = source_dir.join("nested");
+    let copied_dir = codex_home.path().join("copied");
+    std::fs::create_dir_all(&nested_dir)?;
+    symlink("nested", source_dir.join("nested-link"))?;
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let request_id = mcp
+        .send_fs_copy_request(FsCopyParams {
+            source_path: absolute_path(source_dir),
+            destination_path: absolute_path(copied_dir.clone()),
+            recursive: true,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+
+    let copied_link = copied_dir.join("nested-link");
+    let metadata = std::fs::symlink_metadata(&copied_link)?;
+    assert!(metadata.file_type().is_symlink());
+    assert_eq!(std::fs::read_link(copied_link)?, PathBuf::from("nested"));
+
+    Ok(())
+}
+
+#[cfg(unix)]
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_copy_ignores_unknown_special_files_in_recursive_copy() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let source_dir = codex_home.path().join("source");
+    let copied_dir = codex_home.path().join("copied");
+    std::fs::create_dir_all(&source_dir)?;
+    std::fs::write(source_dir.join("note.txt"), "hello")?;
+    let fifo_path = source_dir.join("named-pipe");
+    let output = Command::new("mkfifo").arg(&fifo_path).output()?;
+    if !output.status.success() {
+        anyhow::bail!(
+            "mkfifo failed: stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout).trim(),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let request_id = mcp
+        .send_fs_copy_request(FsCopyParams {
+            source_path: absolute_path(source_dir),
+            destination_path: absolute_path(copied_dir.clone()),
+            recursive: true,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+
+    assert_eq!(
+        std::fs::read_to_string(copied_dir.join("note.txt"))?,
+        "hello"
+    );
+    assert!(!copied_dir.join("named-pipe").exists());
+
+    Ok(())
+}
+
+#[cfg(unix)]
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn fs_copy_rejects_standalone_fifo_source() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let fifo_path = codex_home.path().join("named-pipe");
+    let output = Command::new("mkfifo").arg(&fifo_path).output()?;
+    if !output.status.success() {
+        anyhow::bail!(
+            "mkfifo failed: stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout).trim(),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+
+    let mut mcp = initialized_mcp(&codex_home).await?;
+    let request_id = mcp
+        .send_fs_copy_request(FsCopyParams {
+            source_path: absolute_path(fifo_path),
+            destination_path: absolute_path(codex_home.path().join("copied")),
+            recursive: false,
+        })
+        .await?;
+    expect_error_message(
+        &mut mcp,
+        request_id,
+        "fs/copy only supports regular files, directories, and symlinks",
+    )
+    .await?;
+
+    Ok(())
+}

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

@@ -19,11 +19,17 @@ use core_test_support::fs_wait;
 use pretty_assertions::assert_eq;
 use serde_json::Value;
 use std::path::Path;
-use std::time::Duration;
 use tempfile::TempDir;
 use tokio::time::timeout;
 
+#[cfg(windows)]
+const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(25);
+#[cfg(not(windows))]
 const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
+#[cfg(windows)]
+const DEFAULT_NOTIFY_FILE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(25);
+#[cfg(not(windows))]
+const DEFAULT_NOTIFY_FILE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
 
 #[tokio::test]
 async fn initialize_uses_client_info_name_as_originator() -> Result<()> {
@@ -263,9 +269,9 @@ async fn turn_start_notify_payload_includes_initialize_client_name() -> Result<(
         mcp.read_stream_until_notification_message("turn/completed"),
     )
     .await??;
-
-    fs_wait::wait_for_path_exists(&notify_file, Duration::from_secs(5)).await?;
-    let payload_raw = tokio::fs::read_to_string(&notify_file).await?;
+    let notify_file = Path::new(&notify_file);
+    fs_wait::wait_for_path_exists(notify_file, DEFAULT_NOTIFY_FILE_TIMEOUT).await?;
+    let payload_raw = tokio::fs::read_to_string(notify_file).await?;
     let payload: Value = serde_json::from_str(&payload_raw)?;
     assert_eq!(payload["client"], "xcode");
 

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

@@ -66,7 +66,7 @@ const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs
 const CONNECTOR_ID: &str = "calendar";
 const CONNECTOR_NAME: &str = "Calendar";
 const TOOL_NAME: &str = "calendar_confirm_action";
-const QUALIFIED_TOOL_NAME: &str = "mcp__codex_apps__calendar-confirm-action";
+const QUALIFIED_TOOL_NAME: &str = "mcp__codex_apps__calendar_confirm_action";
 const TOOL_CALL_ID: &str = "call-calendar-confirm";
 const ELICITATION_MESSAGE: &str = "Allow this request?";
 

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

@@ -12,6 +12,7 @@ mod connection_handling_websocket_unix;
 mod dynamic_tools;
 mod experimental_api;
 mod experimental_feature_list;
+mod fs;
 mod initialize;
 mod mcp_server_elicitation;
 mod model_list;

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

@@ -233,6 +233,7 @@ async fn skills_changed_notification_is_emitted_after_skill_change() -> Result<(
             service_tier: None,
             cwd: None,
             approval_policy: None,
+            approvals_reviewer: None,
             sandbox: None,
             config: None,
             service_name: None,

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

@@ -7,6 +7,10 @@ use codex_app_server_protocol::JSONRPCError;
 use codex_app_server_protocol::JSONRPCResponse;
 use codex_app_server_protocol::RequestId;
 use codex_app_server_protocol::SessionSource;
+use codex_app_server_protocol::ThreadArchiveParams;
+use codex_app_server_protocol::ThreadArchiveResponse;
+use codex_app_server_protocol::ThreadForkParams;
+use codex_app_server_protocol::ThreadForkResponse;
 use codex_app_server_protocol::ThreadItem;
 use codex_app_server_protocol::ThreadListParams;
 use codex_app_server_protocol::ThreadListResponse;
@@ -20,6 +24,8 @@ use codex_app_server_protocol::ThreadSetNameResponse;
 use codex_app_server_protocol::ThreadStartParams;
 use codex_app_server_protocol::ThreadStartResponse;
 use codex_app_server_protocol::ThreadStatus;
+use codex_app_server_protocol::ThreadUnarchiveParams;
+use codex_app_server_protocol::ThreadUnarchiveResponse;
 use codex_app_server_protocol::TurnStartParams;
 use codex_app_server_protocol::TurnStartResponse;
 use codex_app_server_protocol::TurnStatus;
@@ -152,6 +158,150 @@ async fn thread_read_can_include_turns() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn thread_read_include_turns_keeps_fork_history_after_parent_archive_and_unarchive()
+-> Result<()> {
+    let server = create_mock_responses_server_repeating_assistant("Done").await;
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let start_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            model: Some("mock-model".to_string()),
+            ..Default::default()
+        })
+        .await?;
+    let start_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
+    )
+    .await??;
+    let ThreadStartResponse { thread: parent, .. } =
+        to_response::<ThreadStartResponse>(start_resp)?;
+
+    let turn_start_id = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: parent.id.clone(),
+            input: vec![UserInput::Text {
+                text: "parent message".to_string(),
+                text_elements: Vec::new(),
+            }],
+            ..Default::default()
+        })
+        .await?;
+    let turn_start_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_start_id)),
+    )
+    .await??;
+    let _: TurnStartResponse = to_response::<TurnStartResponse>(turn_start_resp)?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let fork_id = mcp
+        .send_thread_fork_request(ThreadForkParams {
+            thread_id: parent.id.clone(),
+            ..Default::default()
+        })
+        .await?;
+    let fork_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(fork_id)),
+    )
+    .await??;
+    let ThreadForkResponse { thread: child, .. } = to_response::<ThreadForkResponse>(fork_resp)?;
+
+    let read_child_id = mcp
+        .send_thread_read_request(ThreadReadParams {
+            thread_id: child.id.clone(),
+            include_turns: true,
+        })
+        .await?;
+    let read_child_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(read_child_id)),
+    )
+    .await??;
+    let ThreadReadResponse {
+        thread: child_before_archive,
+    } = to_response::<ThreadReadResponse>(read_child_resp)?;
+    assert_eq!(child_before_archive.turns.len(), 1);
+
+    let archive_id = mcp
+        .send_thread_archive_request(ThreadArchiveParams {
+            thread_id: parent.id.clone(),
+        })
+        .await?;
+    let archive_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(archive_id)),
+    )
+    .await??;
+    let _: ThreadArchiveResponse = to_response::<ThreadArchiveResponse>(archive_resp)?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("thread/archived"),
+    )
+    .await??;
+
+    let read_child_id = mcp
+        .send_thread_read_request(ThreadReadParams {
+            thread_id: child.id.clone(),
+            include_turns: true,
+        })
+        .await?;
+    let read_child_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(read_child_id)),
+    )
+    .await??;
+    let ThreadReadResponse {
+        thread: child_after_archive,
+    } = to_response::<ThreadReadResponse>(read_child_resp)?;
+    assert_eq!(child_after_archive.turns, child_before_archive.turns);
+
+    let unarchive_id = mcp
+        .send_thread_unarchive_request(ThreadUnarchiveParams {
+            thread_id: parent.id,
+        })
+        .await?;
+    let unarchive_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(unarchive_id)),
+    )
+    .await??;
+    let _: ThreadUnarchiveResponse = to_response::<ThreadUnarchiveResponse>(unarchive_resp)?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("thread/unarchived"),
+    )
+    .await??;
+
+    let read_child_id = mcp
+        .send_thread_read_request(ThreadReadParams {
+            thread_id: child.id,
+            include_turns: true,
+        })
+        .await?;
+    let read_child_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(read_child_id)),
+    )
+    .await??;
+    let ThreadReadResponse {
+        thread: child_after_unarchive,
+    } = to_response::<ThreadReadResponse>(read_child_resp)?;
+    assert_eq!(child_after_unarchive.turns, child_before_archive.turns);
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn thread_read_loaded_thread_returns_precomputed_path_before_materialization() -> Result<()> {
     let server = create_mock_responses_server_repeating_assistant("Done").await;
@@ -407,6 +557,62 @@ async fn thread_read_include_turns_rejects_unmaterialized_loaded_thread() -> Res
     Ok(())
 }
 
+#[tokio::test]
+async fn thread_read_loaded_ephemeral_thread_ignores_unrelated_rollout_mentions() -> Result<()> {
+    let server = create_mock_responses_server_repeating_assistant("Done").await;
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let start_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            model: Some("mock-model".to_string()),
+            ephemeral: Some(true),
+            ..Default::default()
+        })
+        .await?;
+    let start_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response::<ThreadStartResponse>(start_resp)?;
+
+    let unrelated_preview = thread.id.clone();
+    let _unrelated_rollout_id = create_fake_rollout_with_text_elements(
+        codex_home.path(),
+        "2025-01-05T13-00-00",
+        "2025-01-05T13:00:00Z",
+        &unrelated_preview,
+        vec![],
+        Some("mock_provider"),
+        None,
+    )?;
+
+    let read_id = mcp
+        .send_thread_read_request(ThreadReadParams {
+            thread_id: thread.id.clone(),
+            include_turns: false,
+        })
+        .await?;
+    let read_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(read_id)),
+    )
+    .await??;
+    let ThreadReadResponse { thread: read } = to_response::<ThreadReadResponse>(read_resp)?;
+
+    assert_eq!(read.id, thread.id);
+    assert!(read.ephemeral);
+    assert_eq!(read.path, None);
+    assert!(read.preview.is_empty());
+    assert_eq!(read.status, ThreadStatus::Idle);
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn thread_read_reports_system_error_idle_flag_after_failed_turn() -> Result<()> {
     let server = responses::start_mock_server().await;

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

@@ -62,6 +62,7 @@ use std::path::Path;
 use std::path::PathBuf;
 use std::process::Command;
 use tempfile::TempDir;
+use tokio::time::sleep;
 use tokio::time::timeout;
 use uuid::Uuid;
 use wiremock::Mock;
@@ -70,39 +71,12 @@ use wiremock::ResponseTemplate;
 use wiremock::matchers::method;
 use wiremock::matchers::path;
 
+#[cfg(windows)]
+const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(25);
+#[cfg(not(windows))]
 const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
 const CODEX_5_2_INSTRUCTIONS_TEMPLATE_DEFAULT: &str = "You are Codex, a coding agent based on GPT-5. You and the user share the same workspace and collaborate to achieve the user's goals.";
 
-async fn wait_for_responses_request_count(
-    server: &wiremock::MockServer,
-    expected_count: usize,
-) -> Result<()> {
-    timeout(DEFAULT_READ_TIMEOUT, async {
-        loop {
-            let Some(requests) = server.received_requests().await else {
-                anyhow::bail!("wiremock did not record requests");
-            };
-            let responses_request_count = requests
-                .iter()
-                .filter(|request| {
-                    request.method == "POST" && request.url.path().ends_with("/responses")
-                })
-                .count();
-            if responses_request_count == expected_count {
-                return Ok::<(), anyhow::Error>(());
-            }
-            if responses_request_count > expected_count {
-                anyhow::bail!(
-                    "expected exactly {expected_count} /responses requests, got {responses_request_count}"
-                );
-            }
-            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
-        }
-    })
-    .await??;
-    Ok(())
-}
-
 #[tokio::test]
 async fn thread_resume_rejects_unmaterialized_thread() -> Result<()> {
     let server = create_mock_responses_server_repeating_assistant("Done").await;
@@ -224,6 +198,62 @@ async fn thread_resume_returns_rollout_history() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn thread_resume_unarchives_archived_rollout() -> Result<()> {
+    let server = create_mock_responses_server_repeating_assistant("Done").await;
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let filename_ts = "2025-01-05T12-00-00";
+    let conversation_id = create_fake_rollout_with_text_elements(
+        codex_home.path(),
+        filename_ts,
+        "2025-01-05T12:00:00Z",
+        "Saved user message",
+        Vec::new(),
+        Some("mock_provider"),
+        None,
+    )?;
+    let active_rollout_path = rollout_path(codex_home.path(), filename_ts, &conversation_id);
+    let archived_rollout_path = codex_home.path().join("archived_sessions/2025/01/05").join(
+        active_rollout_path
+            .file_name()
+            .expect("active rollout file name"),
+    );
+    std::fs::create_dir_all(
+        archived_rollout_path
+            .parent()
+            .expect("archived rollout parent directory"),
+    )?;
+    std::fs::rename(&active_rollout_path, &archived_rollout_path)?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let resume_id = mcp
+        .send_thread_resume_request(ThreadResumeParams {
+            thread_id: conversation_id.clone(),
+            ..Default::default()
+        })
+        .await?;
+    let resume_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(resume_id)),
+    )
+    .await??;
+    let ThreadResumeResponse { thread, .. } = to_response::<ThreadResumeResponse>(resume_resp)?;
+
+    assert_eq!(thread.id, conversation_id);
+    assert!(active_rollout_path.exists());
+    assert!(!archived_rollout_path.exists());
+    assert_eq!(
+        std::fs::canonicalize(thread.path.as_ref().expect("thread path"))?,
+        std::fs::canonicalize(&active_rollout_path)?
+    );
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn thread_resume_prefers_persisted_git_metadata_for_local_threads() -> Result<()> {
     let server = create_mock_responses_server_repeating_assistant("Done").await;
@@ -1014,16 +1044,7 @@ async fn thread_resume_rejoins_running_thread_even_with_override_mismatch() -> R
 async fn thread_resume_replays_pending_command_execution_request_approval() -> Result<()> {
     let responses = vec![
         create_final_assistant_message_sse_response("seeded")?,
-        create_shell_command_sse_response(
-            vec![
-                "python3".to_string(),
-                "-c".to_string(),
-                "print(42)".to_string(),
-            ],
-            None,
-            Some(5000),
-            "call-1",
-        )?,
+        create_shell_command_sse_response(fast_shell_command(), None, Some(1000), "call-1")?,
         create_final_assistant_message_sse_response("done")?,
     ];
     let server = create_mock_responses_server_sequence_unchecked(responses).await;
@@ -1141,7 +1162,7 @@ async fn thread_resume_replays_pending_command_execution_request_approval() -> R
         primary.read_stream_until_notification_message("turn/completed"),
     )
     .await??;
-    wait_for_responses_request_count(&server, 3).await?;
+    wait_for_mock_request_count(&server, 3).await?;
 
     Ok(())
 }
@@ -1307,11 +1328,50 @@ async fn thread_resume_replays_pending_file_change_request_approval() -> Result<
         primary.read_stream_until_notification_message("turn/completed"),
     )
     .await??;
-    wait_for_responses_request_count(&server, 3).await?;
+    wait_for_mock_request_count(&server, 3).await?;
 
     Ok(())
 }
 
+fn fast_shell_command() -> Vec<String> {
+    if cfg!(windows) {
+        vec![
+            "cmd".to_string(),
+            "/d".to_string(),
+            "/c".to_string(),
+            "echo 42".to_string(),
+        ]
+    } else {
+        vec![
+            "python3".to_string(),
+            "-c".to_string(),
+            "print(42)".to_string(),
+        ]
+    }
+}
+
+async fn wait_for_mock_request_count(server: &MockServer, expected: usize) -> Result<()> {
+    let deadline = tokio::time::Instant::now() + DEFAULT_READ_TIMEOUT;
+    loop {
+        let requests = server
+            .received_requests()
+            .await
+            .ok_or_else(|| anyhow::anyhow!("failed to fetch received requests"))?;
+        if requests.len() >= expected {
+            return Ok(());
+        }
+
+        if tokio::time::Instant::now() >= deadline {
+            anyhow::bail!(
+                "expected at least {expected} mock requests, observed {}",
+                requests.len()
+            );
+        }
+
+        sleep(std::time::Duration::from_millis(50)).await;
+    }
+}
+
 #[tokio::test]
 async fn thread_resume_with_overrides_defers_updated_at_until_turn_start() -> Result<()> {
     let server = create_mock_responses_server_repeating_assistant("Done").await;

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

@@ -33,6 +33,9 @@ use pretty_assertions::assert_eq;
 use tempfile::TempDir;
 use tokio::time::timeout;
 
+#[cfg(windows)]
+const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(25);
+#[cfg(not(windows))]
 const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
 
 async fn wait_for_responses_request_count_to_stabilize(
@@ -192,6 +195,10 @@ async fn thread_unsubscribe_during_turn_interrupts_turn_and_emits_thread_closed(
         wait_for_command_execution_item_started(&mut mcp),
     )
     .await??;
+    // `item/started` can arrive before the spawned command reports a process id.
+    // Give the runtime a brief moment to finish wiring the command so unsubscribe
+    // consistently exercises the shutdown path on slower CI runners.
+    tokio::time::sleep(std::time::Duration::from_millis(250)).await;
 
     let unsubscribe_id = mcp
         .send_thread_unsubscribe_request(ThreadUnsubscribeParams {

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

@@ -1026,27 +1026,9 @@ async fn turn_start_exec_approval_toggle_v2() -> Result<()> {
     // Mock server: first turn requests a shell call (elicitation), then completes.
     // Second turn same, but we'll set approval_policy=never to avoid elicitation.
     let responses = vec![
-        create_shell_command_sse_response(
-            vec![
-                "python3".to_string(),
-                "-c".to_string(),
-                "print(42)".to_string(),
-            ],
-            None,
-            Some(5000),
-            "call1",
-        )?,
+        create_shell_command_sse_response(fast_shell_command(), None, Some(1000), "call1")?,
         create_final_assistant_message_sse_response("done 1")?,
-        create_shell_command_sse_response(
-            vec![
-                "python3".to_string(),
-                "-c".to_string(),
-                "print(42)".to_string(),
-            ],
-            None,
-            Some(5000),
-            "call2",
-        )?,
+        create_shell_command_sse_response(fast_shell_command(), None, Some(1000), "call2")?,
         create_final_assistant_message_sse_response("done 2")?,
     ];
     let server = create_mock_responses_server_sequence(responses).await;
@@ -1171,6 +1153,23 @@ async fn turn_start_exec_approval_toggle_v2() -> Result<()> {
     Ok(())
 }
 
+fn fast_shell_command() -> Vec<String> {
+    if cfg!(windows) {
+        vec![
+            "cmd".to_string(),
+            "/d".to_string(),
+            "/c".to_string(),
+            "echo 42".to_string(),
+        ]
+    } else {
+        vec![
+            "python3".to_string(),
+            "-c".to_string(),
+            "print(42)".to_string(),
+        ]
+    }
+}
+
 #[tokio::test]
 async fn turn_start_exec_approval_decline_v2() -> Result<()> {
     skip_if_no_network!(Ok(()));
@@ -1380,6 +1379,7 @@ async fn turn_start_updates_sandbox_and_cwd_between_turns_v2() -> Result<()> {
             }],
             cwd: Some(first_cwd.clone()),
             approval_policy: Some(codex_app_server_protocol::AskForApproval::Never),
+            approvals_reviewer: None,
             sandbox_policy: Some(codex_app_server_protocol::SandboxPolicy::WorkspaceWrite {
                 writable_roots: vec![first_cwd.try_into()?],
                 read_only_access: codex_app_server_protocol::ReadOnlyAccess::FullAccess,
@@ -1418,6 +1418,7 @@ async fn turn_start_updates_sandbox_and_cwd_between_turns_v2() -> Result<()> {
             }],
             cwd: Some(second_cwd.clone()),
             approval_policy: Some(codex_app_server_protocol::AskForApproval::Never),
+            approvals_reviewer: None,
             sandbox_policy: Some(codex_app_server_protocol::SandboxPolicy::DangerFullAccess),
             model: Some("mock-model".to_string()),
             effort: Some(ReasoningEffort::Medium),

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

@@ -11,6 +11,7 @@ use app_test_support::McpProcess;
 use app_test_support::create_final_assistant_message_sse_response;
 use app_test_support::create_mock_responses_server_sequence;
 use app_test_support::create_mock_responses_server_sequence_unchecked;
+use app_test_support::create_shell_command_sse_response;
 use app_test_support::to_response;
 use codex_app_server_protocol::CommandAction;
 use codex_app_server_protocol::CommandExecutionApprovalDecision;
@@ -34,11 +35,9 @@ use codex_core::features::Feature;
 use core_test_support::responses;
 use core_test_support::skip_if_no_network;
 use pretty_assertions::assert_eq;
-use serde_json::json;
 use std::collections::BTreeMap;
 use std::path::Path;
 use tempfile::TempDir;
-use tokio::time::sleep;
 use tokio::time::timeout;
 
 #[cfg(windows)]
@@ -63,14 +62,19 @@ async fn turn_start_shell_zsh_fork_executes_command_v2() -> Result<()> {
     };
     eprintln!("using zsh path for zsh-fork test: {}", zsh_path.display());
 
-    // Keep the exec command in flight until we interrupt it. A fast command
+    // Keep the shell command in flight until we interrupt it. A fast command
     // like `echo hi` can finish before the interrupt arrives on faster runners,
     // which turns this into a test for post-command follow-up behavior instead
     // of interrupting an active zsh-fork command.
     let release_marker_escaped = release_marker.to_string_lossy().replace('\'', r#"'\''"#);
     let wait_for_interrupt =
         format!("while [ ! -f '{release_marker_escaped}' ]; do sleep 0.01; done");
-    let response = create_zsh_fork_exec_command_sse_response(&wait_for_interrupt, "call-zsh-fork")?;
+    let response = create_shell_command_sse_response(
+        vec!["/bin/sh".to_string(), "-c".to_string(), wait_for_interrupt],
+        None,
+        Some(5000),
+        "call-zsh-fork",
+    )?;
     let no_op_response = responses::sse(vec![
         responses::ev_response_created("resp-2"),
         responses::ev_completed("resp-2"),
@@ -87,7 +91,7 @@ async fn turn_start_shell_zsh_fork_executes_command_v2() -> Result<()> {
         "never",
         &BTreeMap::from([
             (Feature::ShellZshFork, true),
-            (Feature::UnifiedExec, true),
+            (Feature::UnifiedExec, false),
             (Feature::ShellSnapshot, false),
         ]),
         &zsh_path,
@@ -159,7 +163,7 @@ async fn turn_start_shell_zsh_fork_executes_command_v2() -> Result<()> {
     assert_eq!(id, "call-zsh-fork");
     assert_eq!(status, CommandExecutionStatus::InProgress);
     assert!(command.starts_with(&zsh_path.display().to_string()));
-    assert!(command.contains(" -lc "));
+    assert!(command.contains("/bin/sh -c"));
     assert!(command.contains("sleep 0.01"));
     assert!(command.contains(&release_marker.display().to_string()));
     assert_eq!(cwd, workspace);
@@ -187,8 +191,14 @@ async fn turn_start_shell_zsh_fork_exec_approval_decline_v2() -> Result<()> {
     eprintln!("using zsh path for zsh-fork test: {}", zsh_path.display());
 
     let responses = vec![
-        create_zsh_fork_exec_command_sse_response(
-            "python3 -c 'print(42)'",
+        create_shell_command_sse_response(
+            vec![
+                "python3".to_string(),
+                "-c".to_string(),
+                "print(42)".to_string(),
+            ],
+            None,
+            Some(5000),
             "call-zsh-fork-decline",
         )?,
         create_final_assistant_message_sse_response("done")?,
@@ -200,14 +210,17 @@ async fn turn_start_shell_zsh_fork_exec_approval_decline_v2() -> Result<()> {
         "untrusted",
         &BTreeMap::from([
             (Feature::ShellZshFork, true),
-            (Feature::UnifiedExec, true),
+            (Feature::UnifiedExec, false),
             (Feature::ShellSnapshot, false),
         ]),
         &zsh_path,
     )?;
+    // This flow can require several sequential approval round-trips on slower
+    // macOS runners before the parent command reaches a terminal state.
+    let read_timeout = std::time::Duration::from_secs(20);
 
     let mut mcp = create_zsh_test_mcp_process(&codex_home, &workspace).await?;
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+    timeout(read_timeout, mcp.initialize()).await??;
 
     let start_id = mcp
         .send_thread_start_request(ThreadStartParams {
@@ -217,7 +230,7 @@ async fn turn_start_shell_zsh_fork_exec_approval_decline_v2() -> Result<()> {
         })
         .await?;
     let start_resp: JSONRPCResponse = timeout(
-        DEFAULT_READ_TIMEOUT,
+        read_timeout,
         mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
     )
     .await??;
@@ -316,8 +329,14 @@ async fn turn_start_shell_zsh_fork_exec_approval_cancel_v2() -> Result<()> {
     };
     eprintln!("using zsh path for zsh-fork test: {}", zsh_path.display());
 
-    let responses = vec![create_zsh_fork_exec_command_sse_response(
-        "python3 -c 'print(42)'",
+    let responses = vec![create_shell_command_sse_response(
+        vec![
+            "python3".to_string(),
+            "-c".to_string(),
+            "print(42)".to_string(),
+        ],
+        None,
+        Some(5000),
         "call-zsh-fork-cancel",
     )?];
     let server = create_mock_responses_server_sequence(responses).await;
@@ -327,14 +346,17 @@ async fn turn_start_shell_zsh_fork_exec_approval_cancel_v2() -> Result<()> {
         "untrusted",
         &BTreeMap::from([
             (Feature::ShellZshFork, true),
-            (Feature::UnifiedExec, true),
+            (Feature::UnifiedExec, false),
             (Feature::ShellSnapshot, false),
         ]),
         &zsh_path,
     )?;
+    // This flow can require several sequential approval round-trips on slower
+    // macOS runners before the parent command reaches a terminal state.
+    let read_timeout = std::time::Duration::from_secs(20);
 
     let mut mcp = create_zsh_test_mcp_process(&codex_home, &workspace).await?;
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+    timeout(read_timeout, mcp.initialize()).await??;
 
     let start_id = mcp
         .send_thread_start_request(ThreadStartParams {
@@ -344,7 +366,7 @@ async fn turn_start_shell_zsh_fork_exec_approval_cancel_v2() -> Result<()> {
         })
         .await?;
     let start_resp: JSONRPCResponse = timeout(
-        DEFAULT_READ_TIMEOUT,
+        read_timeout,
         mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
     )
     .await??;
@@ -425,204 +447,6 @@ async fn turn_start_shell_zsh_fork_exec_approval_cancel_v2() -> Result<()> {
     Ok(())
 }
 
-#[tokio::test]
-async fn turn_start_shell_zsh_fork_interrupt_kills_approved_subcommand_v2() -> Result<()> {
-    skip_if_no_network!(Ok(()));
-
-    let tmp = TempDir::new()?;
-    let codex_home = tmp.path().join("codex_home");
-    std::fs::create_dir(&codex_home)?;
-    let workspace = tmp.path().join("workspace");
-    std::fs::create_dir(&workspace)?;
-    let launch_marker = workspace.join("approved-subcommand.started");
-    let leaked_marker = workspace.join("approved-subcommand.leaked");
-    let launch_marker_display = launch_marker.display().to_string();
-    assert!(
-        !launch_marker_display.contains('\''),
-        "test workspace path should not contain single quotes: {launch_marker_display}"
-    );
-    let leaked_marker_display = leaked_marker.display().to_string();
-    assert!(
-        !leaked_marker_display.contains('\''),
-        "test workspace path should not contain single quotes: {leaked_marker_display}"
-    );
-
-    let Some(zsh_path) = find_test_zsh_path()? else {
-        eprintln!("skipping zsh fork interrupt cleanup test: no zsh executable found");
-        return Ok(());
-    };
-    if !supports_exec_wrapper_intercept(&zsh_path) {
-        eprintln!(
-            "skipping zsh fork interrupt cleanup test: zsh does not support EXEC_WRAPPER intercepts ({})",
-            zsh_path.display()
-        );
-        return Ok(());
-    }
-    let zsh_path_display = zsh_path.display().to_string();
-    eprintln!("using zsh path for zsh-fork test: {zsh_path_display}");
-
-    let shell_command = format!(
-        "/bin/sh -c 'echo started > \"{launch_marker_display}\" && /bin/sleep 0.5 && echo leaked > \"{leaked_marker_display}\" && exec /bin/sleep 100'"
-    );
-    let tool_call_arguments = serde_json::to_string(&json!({
-        "cmd": shell_command,
-        "yield_time_ms": 30_000,
-    }))?;
-    let response = responses::sse(vec![
-        responses::ev_response_created("resp-1"),
-        responses::ev_function_call(
-            "call-zsh-fork-interrupt-cleanup",
-            "exec_command",
-            &tool_call_arguments,
-        ),
-        responses::ev_completed("resp-1"),
-    ]);
-    let no_op_response = responses::sse(vec![
-        responses::ev_response_created("resp-2"),
-        responses::ev_completed("resp-2"),
-    ]);
-    let server =
-        create_mock_responses_server_sequence_unchecked(vec![response, no_op_response]).await;
-    create_config_toml(
-        &codex_home,
-        &server.uri(),
-        "untrusted",
-        &BTreeMap::from([
-            (Feature::ShellZshFork, true),
-            (Feature::UnifiedExec, true),
-            (Feature::ShellSnapshot, false),
-        ]),
-        &zsh_path,
-    )?;
-
-    let mut mcp = create_zsh_test_mcp_process(&codex_home, &workspace).await?;
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
-
-    let start_id = mcp
-        .send_thread_start_request(ThreadStartParams {
-            model: Some("mock-model".to_string()),
-            cwd: Some(workspace.to_string_lossy().into_owned()),
-            ..Default::default()
-        })
-        .await?;
-    let start_resp: JSONRPCResponse = timeout(
-        DEFAULT_READ_TIMEOUT,
-        mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
-    )
-    .await??;
-    let ThreadStartResponse { thread, .. } = to_response::<ThreadStartResponse>(start_resp)?;
-
-    let turn_id = mcp
-        .send_turn_start_request(TurnStartParams {
-            thread_id: thread.id.clone(),
-            input: vec![V2UserInput::Text {
-                text: "run the long-lived command".to_string(),
-                text_elements: Vec::new(),
-            }],
-            cwd: Some(workspace.clone()),
-            approval_policy: Some(codex_app_server_protocol::AskForApproval::UnlessTrusted),
-            sandbox_policy: Some(codex_app_server_protocol::SandboxPolicy::WorkspaceWrite {
-                writable_roots: vec![workspace.clone().try_into()?],
-                read_only_access: codex_app_server_protocol::ReadOnlyAccess::FullAccess,
-                network_access: false,
-                exclude_tmpdir_env_var: false,
-                exclude_slash_tmp: false,
-            }),
-            model: Some("mock-model".to_string()),
-            effort: Some(codex_protocol::openai_models::ReasoningEffort::Medium),
-            summary: Some(codex_protocol::config_types::ReasoningSummary::Auto),
-            ..Default::default()
-        })
-        .await?;
-    let turn_resp: JSONRPCResponse = timeout(
-        DEFAULT_READ_TIMEOUT,
-        mcp.read_stream_until_response_message(RequestId::Integer(turn_id)),
-    )
-    .await??;
-    let TurnStartResponse { turn } = to_response::<TurnStartResponse>(turn_resp)?;
-
-    let mut saw_target_approval = false;
-    while !saw_target_approval {
-        let server_req = timeout(
-            DEFAULT_READ_TIMEOUT,
-            mcp.read_stream_until_request_message(),
-        )
-        .await??;
-        let ServerRequest::CommandExecutionRequestApproval { request_id, params } = server_req
-        else {
-            panic!("expected CommandExecutionRequestApproval request");
-        };
-        let approval_command = params.command.clone().unwrap_or_default();
-        saw_target_approval = approval_command.contains("/bin/sh")
-            && approval_command.contains(&launch_marker_display)
-            && !approval_command.contains(&zsh_path_display);
-        mcp.send_response(
-            request_id,
-            serde_json::to_value(CommandExecutionRequestApprovalResponse {
-                decision: CommandExecutionApprovalDecision::Accept,
-            })?,
-        )
-        .await?;
-    }
-
-    let started_command = timeout(DEFAULT_READ_TIMEOUT, async {
-        loop {
-            let notif = mcp
-                .read_stream_until_notification_message("item/started")
-                .await?;
-            let started: ItemStartedNotification =
-                serde_json::from_value(notif.params.clone().expect("item/started params"))?;
-            if let ThreadItem::CommandExecution { .. } = started.item {
-                return Ok::<ThreadItem, anyhow::Error>(started.item);
-            }
-        }
-    })
-    .await??;
-    let ThreadItem::CommandExecution {
-        id,
-        process_id,
-        status,
-        command,
-        cwd,
-        ..
-    } = started_command
-    else {
-        unreachable!("loop ensures we break on command execution items");
-    };
-    assert_eq!(id, "call-zsh-fork-interrupt-cleanup");
-    assert_eq!(status, CommandExecutionStatus::InProgress);
-    assert!(command.starts_with(&zsh_path.display().to_string()));
-    assert!(command.contains(" -lc "));
-    assert!(command.contains(&launch_marker_display));
-    assert_eq!(cwd, workspace);
-    assert!(process_id.is_some(), "process id should be present");
-
-    timeout(DEFAULT_READ_TIMEOUT, async {
-        loop {
-            if launch_marker.exists() {
-                return Ok::<(), anyhow::Error>(());
-            }
-            sleep(std::time::Duration::from_millis(20)).await;
-        }
-    })
-    .await??;
-
-    mcp.interrupt_turn_and_wait_for_aborted(
-        thread.id.clone(),
-        turn.id.clone(),
-        DEFAULT_READ_TIMEOUT,
-    )
-    .await?;
-
-    sleep(std::time::Duration::from_millis(750)).await;
-    assert!(
-        !leaked_marker.exists(),
-        "expected interrupt to stop approved subcommand before it wrote {leaked_marker_display}"
-    );
-
-    Ok(())
-}
-
 #[tokio::test]
 async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2() -> Result<()> {
     skip_if_no_network!(Ok(()));
@@ -654,15 +478,16 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
         first_file.display(),
         second_file.display()
     );
-    let tool_call_arguments = serde_json::to_string(&json!({
-        "cmd": shell_command,
-        "yield_time_ms": 5000,
+    let tool_call_arguments = serde_json::to_string(&serde_json::json!({
+        "command": shell_command,
+        "workdir": serde_json::Value::Null,
+        "timeout_ms": 5000
     }))?;
     let response = responses::sse(vec![
         responses::ev_response_created("resp-1"),
         responses::ev_function_call(
             "call-zsh-fork-subcommand-decline",
-            "exec_command",
+            "shell_command",
             &tool_call_arguments,
         ),
         responses::ev_completed("resp-1"),
@@ -683,14 +508,15 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
         "untrusted",
         &BTreeMap::from([
             (Feature::ShellZshFork, true),
-            (Feature::UnifiedExec, true),
+            (Feature::UnifiedExec, false),
             (Feature::ShellSnapshot, false),
         ]),
         &zsh_path,
     )?;
+    let read_timeout = std::time::Duration::from_secs(20);
 
     let mut mcp = create_zsh_test_mcp_process(&codex_home, &workspace).await?;
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+    timeout(read_timeout, mcp.initialize()).await??;
 
     let start_id = mcp
         .send_thread_start_request(ThreadStartParams {
@@ -700,7 +526,7 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
         })
         .await?;
     let start_resp: JSONRPCResponse = timeout(
-        DEFAULT_READ_TIMEOUT,
+        read_timeout,
         mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
     )
     .await??;
@@ -729,7 +555,7 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
         })
         .await?;
     let turn_resp: JSONRPCResponse = timeout(
-        DEFAULT_READ_TIMEOUT,
+        read_timeout,
         mcp.read_stream_until_response_message(RequestId::Integer(turn_id)),
     )
     .await??;
@@ -747,11 +573,7 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
     let second_file_str = second_file.to_string_lossy().into_owned();
     let parent_shell_hint = format!("&& {}", &first_file_str);
     while target_decision_index < target_decisions.len() || !saw_parent_approval {
-        let server_req = timeout(
-            DEFAULT_READ_TIMEOUT,
-            mcp.read_stream_until_request_message(),
-        )
-        .await??;
+        let server_req = timeout(read_timeout, mcp.read_stream_until_request_message()).await??;
         let ServerRequest::CommandExecutionRequestApproval { request_id, params } = server_req
         else {
             panic!("expected CommandExecutionRequestApproval request");
@@ -821,7 +643,7 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
     assert_eq!(approved_subcommand_strings.len(), 2);
     assert!(approved_subcommand_strings[0].contains(&first_file.display().to_string()));
     assert!(approved_subcommand_strings[1].contains(&second_file.display().to_string()));
-    let parent_completed_command_execution = timeout(DEFAULT_READ_TIMEOUT, async {
+    let parent_completed_command_execution = timeout(read_timeout, async {
         loop {
             let completed_notif = mcp
                 .read_stream_until_notification_message("item/completed")
@@ -863,7 +685,7 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
             }
 
             match timeout(
-                DEFAULT_READ_TIMEOUT,
+                read_timeout,
                 mcp.read_stream_until_notification_message("turn/completed"),
             )
             .await
@@ -886,7 +708,7 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
                     mcp.interrupt_turn_and_wait_for_aborted(
                         thread.id.clone(),
                         turn.id.clone(),
-                        DEFAULT_READ_TIMEOUT,
+                        read_timeout,
                     )
                     .await?;
                 }
@@ -899,7 +721,7 @@ async fn turn_start_shell_zsh_fork_subcommand_decline_marks_parent_declined_v2()
             // sandbox failures can also complete the turn before the parent
             // completion item is observed.
             let completed_notif = timeout(
-                DEFAULT_READ_TIMEOUT,
+                read_timeout,
                 mcp.read_stream_until_notification_message("turn/completed"),
             )
             .await??;
@@ -925,21 +747,6 @@ async fn create_zsh_test_mcp_process(codex_home: &Path, zdotdir: &Path) -> Resul
     McpProcess::new_with_env(codex_home, &[("ZDOTDIR", Some(zdotdir.as_str()))]).await
 }
 
-fn create_zsh_fork_exec_command_sse_response(
-    command: &str,
-    call_id: &str,
-) -> anyhow::Result<String> {
-    let tool_call_arguments = serde_json::to_string(&json!({
-        "cmd": command,
-        "yield_time_ms": 5000,
-    }))?;
-    Ok(responses::sse(vec![
-        responses::ev_response_created("resp-1"),
-        responses::ev_function_call(call_id, "exec_command", &tool_call_arguments),
-        responses::ev_completed("resp-1"),
-    ]))
-}
-
 fn create_config_toml(
     codex_home: &Path,
     server_uri: &str,

codex-rs/cli/src/main.rs

@@ -578,7 +578,11 @@ async fn cli_main(arg0_paths: Arg0DispatchPaths) -> anyhow::Result<()> {
             let exit_info = run_interactive_tui(interactive, arg0_paths.clone()).await?;
             handle_app_exit(exit_info)?;
         }
-        Some(Subcommand::Exec(mut exec_cli)) => {
+        Some(Subcommand::Exec(exec_cli)) => {
+            let mut exec_cli = match exec_cli.validate() {
+                Ok(exec_cli) => exec_cli,
+                Err(err) => err.exit(),
+            };
             prepend_config_flags(
                 &mut exec_cli.config_overrides,
                 root_config_overrides.clone(),
@@ -1203,6 +1207,40 @@ mod tests {
         assert_eq!(args.session_id.as_deref(), Some("session-123"));
         assert_eq!(args.prompt.as_deref(), Some("re-review"));
     }
+    #[test]
+    fn exec_fork_accepts_prompt_positional() {
+        let cli = MultitoolCli::try_parse_from([
+            "codex",
+            "exec",
+            "--json",
+            "--fork",
+            "session-123",
+            "2+2",
+        ])
+        .expect("parse should succeed");
+
+        let Some(Subcommand::Exec(exec)) = cli.subcommand else {
+            panic!("expected exec subcommand");
+        };
+
+        assert_eq!(exec.fork_session_id.as_deref(), Some("session-123"));
+        assert!(exec.command.is_none());
+        assert_eq!(exec.prompt.as_deref(), Some("2+2"));
+    }
+
+    #[test]
+    fn exec_fork_conflicts_with_resume_subcommand() {
+        let cli =
+            MultitoolCli::try_parse_from(["codex", "exec", "--fork", "session-123", "resume"])
+                .expect("parse should succeed");
+
+        let Some(Subcommand::Exec(exec)) = cli.subcommand else {
+            panic!("expected exec subcommand");
+        };
+
+        let validate_result = exec.validate();
+        assert!(validate_result.is_err());
+    }
 
     fn app_server_from_args(args: &[&str]) -> AppServerCommand {
         let cli = MultitoolCli::try_parse_from(args).expect("parse");

codex-rs/codex-api/src/endpoint/realtime_websocket/methods.rs

@@ -14,6 +14,7 @@ use crate::endpoint::realtime_websocket::protocol::SessionAudio;
 use crate::endpoint::realtime_websocket::protocol::SessionAudioFormat;
 use crate::endpoint::realtime_websocket::protocol::SessionAudioInput;
 use crate::endpoint::realtime_websocket::protocol::SessionAudioOutput;
+use crate::endpoint::realtime_websocket::protocol::SessionAudioVoice;
 use crate::endpoint::realtime_websocket::protocol::SessionFunctionTool;
 use crate::endpoint::realtime_websocket::protocol::SessionUpdateSession;
 use crate::endpoint::realtime_websocket::protocol::parse_realtime_event;
@@ -47,7 +48,6 @@ use tungstenite::protocol::WebSocketConfig;
 use url::Url;
 
 const REALTIME_AUDIO_SAMPLE_RATE: u32 = 24_000;
-const REALTIME_AUDIO_VOICE: &str = "fathom";
 const REALTIME_V1_SESSION_TYPE: &str = "quicksilver";
 const REALTIME_V2_SESSION_TYPE: &str = "realtime";
 const REALTIME_V2_CODEX_TOOL_NAME: &str = "codex";
@@ -353,34 +353,36 @@ impl RealtimeWebsocketWriter {
                     RealtimeEventParser::V1 => REALTIME_V1_SESSION_TYPE.to_string(),
                     RealtimeEventParser::RealtimeV2 => REALTIME_V2_SESSION_TYPE.to_string(),
                 };
-                (
-                    kind,
-                    Some(instructions),
-                    Some(SessionAudioOutput {
-                        voice: REALTIME_AUDIO_VOICE.to_string(),
-                    }),
-                )
+                let voice = match self.event_parser {
+                    RealtimeEventParser::V1 => SessionAudioVoice::Fathom,
+                    RealtimeEventParser::RealtimeV2 => SessionAudioVoice::Alloy,
+                };
+                (kind, Some(instructions), Some(SessionAudioOutput { voice }))
             }
             RealtimeSessionMode::Transcription => ("transcription".to_string(), None, None),
         };
-        let tools = match self.event_parser {
-            RealtimeEventParser::RealtimeV2 => Some(vec![SessionFunctionTool {
-                kind: "function".to_string(),
-                name: REALTIME_V2_CODEX_TOOL_NAME.to_string(),
-                description: REALTIME_V2_CODEX_TOOL_DESCRIPTION.to_string(),
-                parameters: json!({
-                    "type": "object",
-                    "properties": {
-                        "prompt": {
-                            "type": "string",
-                            "description": "Prompt text for the delegated Codex task."
-                        }
-                    },
-                    "required": ["prompt"],
-                    "additionalProperties": false
-                }),
-            }]),
-            RealtimeEventParser::V1 => None,
+        let tools = match (self.event_parser, session_mode) {
+            (RealtimeEventParser::RealtimeV2, RealtimeSessionMode::Conversational) => {
+                Some(vec![SessionFunctionTool {
+                    kind: "function".to_string(),
+                    name: REALTIME_V2_CODEX_TOOL_NAME.to_string(),
+                    description: REALTIME_V2_CODEX_TOOL_DESCRIPTION.to_string(),
+                    parameters: json!({
+                        "type": "object",
+                        "properties": {
+                            "prompt": {
+                                "type": "string",
+                                "description": "Prompt text for the delegated Codex task."
+                            }
+                        },
+                        "required": ["prompt"],
+                        "additionalProperties": false
+                    }),
+                }])
+            }
+            (RealtimeEventParser::RealtimeV2, RealtimeSessionMode::Transcription)
+            | (RealtimeEventParser::V1, RealtimeSessionMode::Conversational)
+            | (RealtimeEventParser::V1, RealtimeSessionMode::Transcription) => None,
         };
         self.send_json(RealtimeOutboundMessage::SessionUpdate {
             session: SessionUpdateSession {
@@ -1384,6 +1386,10 @@ mod tests {
                 first_json["session"]["type"],
                 Value::String("realtime".to_string())
             );
+            assert_eq!(
+                first_json["session"]["audio"]["output"]["voice"],
+                Value::String("alloy".to_string())
+            );
             assert_eq!(
                 first_json["session"]["tools"][0]["type"],
                 Value::String("function".to_string())
@@ -1533,10 +1539,7 @@ mod tests {
             );
             assert!(first_json["session"].get("instructions").is_none());
             assert!(first_json["session"]["audio"].get("output").is_none());
-            assert_eq!(
-                first_json["session"]["tools"][0]["name"],
-                Value::String("codex".to_string())
-            );
+            assert!(first_json["session"].get("tools").is_none());
 
             ws.send(Message::Text(
                 json!({

codex-rs/codex-api/src/endpoint/realtime_websocket/protocol.rs

@@ -77,7 +77,15 @@ pub(super) struct SessionAudioFormat {
 
 #[derive(Debug, Clone, Serialize)]
 pub(super) struct SessionAudioOutput {
-    pub(super) voice: String,
+    pub(super) voice: SessionAudioVoice,
+}
+
+#[derive(Debug, Clone, Copy, Serialize)]
+pub(super) enum SessionAudioVoice {
+    #[serde(rename = "fathom")]
+    Fathom,
+    #[serde(rename = "alloy")]
+    Alloy,
 }
 
 #[derive(Debug, Clone, Serialize)]

codex-rs/codex-api/tests/models_integration.rs

@@ -54,6 +54,7 @@ async fn models_client_hits_models_endpoint() {
     let response = ModelsResponse {
         models: vec![ModelInfo {
             slug: "gpt-test".to_string(),
+            request_model: None,
             display_name: "gpt-test".to_string(),
             description: Some("desc".to_string()),
             default_reasoning_level: Some(ReasoningEffort::Medium),

codex-rs/core/config.schema.json

@@ -6,6 +6,13 @@
       "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"
     },
+    "AgentRoleSpawnMode": {
+      "enum": [
+        "spawn",
+        "fork"
+      ],
+      "type": "string"
+    },
     "AgentRoleToml": {
       "additionalProperties": false,
       "properties": {
@@ -21,12 +28,24 @@
           "description": "Human-facing role documentation used in spawn tool guidance. Required unless supplied by the referenced agent role file.",
           "type": "string"
         },
+        "model": {
+          "description": "Optional model override applied by this role.",
+          "type": "string"
+        },
         "nickname_candidates": {
           "description": "Candidate nicknames for agents spawned with this role.",
           "items": {
             "type": "string"
           },
           "type": "array"
+        },
+        "spawn_mode": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/AgentRoleSpawnMode"
+            }
+          ],
+          "description": "Optional default spawn mode when `spawn_agent` omits `spawn_mode`."
         }
       },
       "type": "object"
@@ -53,6 +72,11 @@
           "format": "uint",
           "minimum": 1.0,
           "type": "integer"
+        },
+        "use_function_call_inbox": {
+          "default": false,
+          "description": "Deliver inbound agent messages to non-subagent threads as a synthetic function_call/function_call_output pair instead of plain user input.",
+          "type": "boolean"
         }
       },
       "type": "object"
@@ -168,6 +192,14 @@
       "description": "Tool settings for a single app.",
       "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"
+    },
     "AppsConfigToml": {
       "additionalProperties": {
         "$ref": "#/definitions/AppConfig"
@@ -304,6 +336,9 @@
         "approval_policy": {
           "$ref": "#/definitions/AskForApproval"
         },
+        "approvals_reviewer": {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        },
         "chatgpt_base_url": {
           "type": "string"
         },
@@ -321,6 +356,15 @@
           "default": null,
           "description": "Optional feature toggles scoped to this profile.",
           "properties": {
+            "agent_function_call_inbox": {
+              "type": "boolean"
+            },
+            "agent_prompt_injection": {
+              "type": "boolean"
+            },
+            "agent_watchdog": {
+              "type": "boolean"
+            },
             "apply_patch_freeform": {
               "type": "boolean"
             },
@@ -387,9 +431,6 @@
             "fast_mode": {
               "type": "boolean"
             },
-            "guardian_approval": {
-              "type": "boolean"
-            },
             "image_detail_original": {
               "type": "boolean"
             },
@@ -468,6 +509,9 @@
             "skill_mcp_dependency_install": {
               "type": "boolean"
             },
+            "smart_approvals": {
+              "type": "boolean"
+            },
             "sqlite": {
               "type": "boolean"
             },
@@ -595,6 +639,34 @@
       },
       "type": "object"
     },
+    "CustomModelToml": {
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "description": "Provider-facing model slug used on API requests.",
+          "type": "string"
+        },
+        "model_auto_compact_token_limit": {
+          "description": "Optional auto-compaction token limit override applied when this alias is selected.",
+          "format": "int64",
+          "type": "integer"
+        },
+        "model_context_window": {
+          "description": "Optional context window override applied when this alias is selected.",
+          "format": "int64",
+          "type": "integer"
+        },
+        "name": {
+          "description": "User-facing alias shown in the model picker.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "model",
+        "name"
+      ],
+      "type": "object"
+    },
     "FeedbackConfigToml": {
       "additionalProperties": false,
       "properties": {
@@ -1769,6 +1841,14 @@
       ],
       "description": "Default approval policy for executing commands."
     },
+    "approvals_reviewer": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/ApprovalsReviewer"
+        }
+      ],
+      "description": "Configures who approval requests are routed to for review once they have been escalated. This does not disable separate safety checks such as ARC."
+    },
     "apps": {
       "allOf": [
         {
@@ -1818,6 +1898,14 @@
       "description": "Compact prompt used for history compaction.",
       "type": "string"
     },
+    "custom_models": {
+      "default": [],
+      "description": "User-defined model aliases that can override model context settings.",
+      "items": {
+        "$ref": "#/definitions/CustomModelToml"
+      },
+      "type": "array"
+    },
     "default_permissions": {
       "description": "Default named permissions profile to apply from the `[permissions]` table.",
       "type": "string"
@@ -1865,6 +1953,15 @@
       "default": null,
       "description": "Centralized feature flags (new). Prefer this over individual toggles.",
       "properties": {
+        "agent_function_call_inbox": {
+          "type": "boolean"
+        },
+        "agent_prompt_injection": {
+          "type": "boolean"
+        },
+        "agent_watchdog": {
+          "type": "boolean"
+        },
         "apply_patch_freeform": {
           "type": "boolean"
         },
@@ -1931,9 +2028,6 @@
         "fast_mode": {
           "type": "boolean"
         },
-        "guardian_approval": {
-          "type": "boolean"
-        },
         "image_detail_original": {
           "type": "boolean"
         },
@@ -2012,6 +2106,9 @@
         "skill_mcp_dependency_install": {
           "type": "boolean"
         },
+        "smart_approvals": {
+          "type": "boolean"
+        },
         "sqlite": {
           "type": "boolean"
         },
@@ -2204,7 +2301,7 @@
         "$ref": "#/definitions/ModelProviderInfo"
       },
       "default": {},
-      "description": "User-defined provider entries that extend/override the built-in list.",
+      "description": "User-defined provider entries that extend the built-in list. Built-in IDs cannot be overridden.",
       "type": "object"
     },
     "model_reasoning_effort": {
@@ -2241,6 +2338,10 @@
       },
       "type": "array"
     },
+    "openai_base_url": {
+      "description": "Base URL override for the built-in `openai` model provider.",
+      "type": "string"
+    },
     "oss_provider": {
       "description": "Preferred OSS provider for local models, e.g. \"lmstudio\" or \"ollama\".",
       "type": "string"
@@ -2418,6 +2519,11 @@
       ],
       "description": "Collection of settings that are specific to the TUI."
     },
+    "watchdog_interval_s": {
+      "description": "Watchdog polling interval in seconds.",
+      "format": "int64",
+      "type": "integer"
+    },
     "web_search": {
       "allOf": [
         {

codex-rs/core/root_agent_prompt.md

@@ -0,0 +1,99 @@
+# You are the Root Agent
+
+You are the **root agent** in a multi-agent Codex session. Until you see `# You are a Subagent`, these instructions define your role. If this thread was created from the root thread with `spawn_mode = "fork"` (a forked child), you may see both sets of instructions; apply subagent instructions as local role guidance while root instructions remain governing system-level rules.
+
+## Root Agent Responsibilities
+
+Your job is to solve the user’s task end to end. You are the coordinator, integrator, and final quality gate.
+
+- Understand the real problem being solved, not just the latest sentence.
+- Own the plan, the sequencing, and the final outcome.
+- Coordinate subagents so their work does not overlap or conflict.
+- Verify results with formatting, linting, and targeted tests.
+
+Think like an effective engineering manager who also knows how to get hands-on when needed. Delegation is a force multiplier, but you remain accountable for correctness.
+
+Root agents should not outsource core understanding. Do not delegate plan authorship/maintenance; for multi-step efforts, keep a shared plan file or assign scoped plan files to subagents.
+
+## Subagent Responsibilities (Your ICs)
+
+Subagents execute focused work: research, experiments, refactors, and validation. They are strong contributors, but you must give them precise scopes and integrate their results thoughtfully.
+
+Subagents can become confused if the world changes while they are idle. Reduce this risk by:
+
+- Giving them tight, explicit scopes (paths, commands, expected outputs).
+- Providing updates when you change course.
+- Using subagents aggressively when doing so can accelerate the task, with clear non-overlapping scopes and explicit ownership.
+
+## Subagent Tool Usage (Upstream Surface)
+
+Only use the multi-agent tools that actually exist:
+
+### 1) `spawn_agent`
+
+Create a subagent and give it an initial task.
+
+Parameters:
+- `message` (required): the task description.
+- `agent_type` (optional): the role to assign (`default`, `explorer`, `fast-worker`, or `worker`).
+- `spawn_mode` (optional): one of `spawn` or `fork`.
+
+Guidance:
+- When `spawn_mode` is omitted, the default is `fork` unless the selected role overrides it.
+- Use `agent_type = "explorer"` for specific codebase questions; it defaults to context-free `spawn`.
+- Use `agent_type = "fast-worker"` for tightly constrained execution work that can run from a self-contained prompt; it also defaults to context-free `spawn`.
+- Use `agent_type = "worker"` for broader implementation work that should inherit current-thread context; it defaults to `fork`.
+- Choose `fork` vs `spawn` by context requirements first (not by task shape).
+- Use `spawn_mode = "fork"` when the child should preserve your current conversation history and rely on current-thread context, including:
+  - current debugging-thread relevance (for example, "summarize only failures relevant to this investigation")
+  - active plan / ExecPlan branch continuation
+  - recent user decisions, tradeoffs, or rejected approaches
+  - parallel review work that should inherit the same context automatically
+- Use `spawn_mode = "spawn"` only when the child can do the task correctly from a fresh prompt you provide now, without needing current-thread context.
+- For `spawn`, make the task, inputs, and expected output explicit (especially for independent, output-heavy work where you want the child to distill results and keep the root thread context clean).
+- Needle-in-a-haystack searches are strong `spawn` candidates when the child can search from a precise prompt without current-thread context.
+- Do not choose `spawn` solely because work is output-heavy or command-heavy if it still depends on current-thread context.
+
+### 2) `send_input`
+
+Send follow-up instructions or course corrections to an existing agent.
+
+Guidance:
+- Use `interrupt = true` sparingly. Prefer to let agents complete coherent chunks of work.
+- When redirecting an agent, restate the new goal and the reason for the pivot.
+- Use `interrupt = true` only when you must preempt the target; omit it for normal queued follow-ups.
+- Subagents can call `send_input` without an `id` (or with `id = "parent"` / `id = "root"`). In this runtime those forms resolve to the immediate parent thread.
+- Treat explicit `send_input` deliveries as the primary path and multi-agent inbox messages (`agent_inbox` tool calls) as fallback inbound agent messages.
+
+### 3) `wait`
+
+Wait for one or more agents to complete or report status.
+
+Guidance:
+- You do not need to wait after every spawn. Do useful parallel work, then wait when you need results.
+- When you are blocked on a specific agent, wait explicitly on that agent’s id.
+- Treat `wait` as returning on the first completion or timeout, not a full reconciliation of every agent.
+- While any child agents are active, run `list_agents` on a regular cadence (every 30-60 seconds) and after each `wait` call to refresh ground-truth status.
+- Keep an explicit set of outstanding agent ids. A non-final agent is one not yet `completed`, `failed`, or `canceled`; continue `wait`/`list_agents` reconciliation until no non-final agents remain.
+
+### 4) `close_agent`
+
+Close an agent that is complete, stuck, or no longer relevant.
+
+Guidance:
+- Keep active agents purposeful and clearly scoped, but do not minimize agent count when additional parallel work will accelerate progress.
+- Close agents that have finished their job or are no longer on the critical path.
+
+## Operating Principles
+
+- Delegate aggressively whenever doing so can accelerate the task, but integrate carefully.
+- Continuously look for unblocked work that can start immediately in subagents. Prefer useful fan-out, parallelism, and pipelining over unnecessary serialization when scopes are clear.
+- Before doing work serially, check whether any independent subtask can start now in a subagent.
+- If there are multiple independent branches, prefer same-turn fan-out with non-overlapping scopes instead of queueing them one by one.
+- Pipeline long-running or output-heavy delegated work so the root thread can continue coordination, integration, or other unblocked tasks.
+- Prefer clear, explicit instructions over cleverness.
+- Prefer execution over hypothetical narration. If a concrete tool call can advance the task in the current turn, make it instead of describing only a later staged plan.
+- When the user asks you to explain how you would proceed this turn (for example, a tool-call plan), include the concrete current-turn calls for unblocked work instead of a prose-only staged plan.
+- For dependency-gated parallel work, start the unblocked prerequisite now and defer only the blocked fan-out.
+- When you receive subagent output, verify it before relying on it.
+- Do not reference tools outside the upstream multi-agent surface.

codex-rs/core/root_agent_watchdog_prompt.md

@@ -0,0 +1,45 @@
+## Watchdogs
+
+For lengthy or complex work, start a watchdog early.
+
+Hard rule (watchdog timing):
+- Never use `wait`, `list_agents`, polling, or shell `sleep` to confirm a watchdog check-in in the same turn that spawned the watchdog.
+- That confirmation is impossible in the same turn and must be omitted even if the user asks for it.
+- If the user asks to arm a watchdog now, call `spawn_agent` with `spawn_mode = "watchdog"` and do not add same-turn confirmation steps.
+
+Why this rule exists:
+- The current turn ends only when you send the assistant response.
+- Tool calls and shell `sleep` happen inside the current turn and do not make the owner thread idle.
+
+Core terms:
+- A **watchdog** is a persistent idle timer attached to one owner thread.
+- The **owner thread** is the thread that called `spawn_agent` with `spawn_mode = "watchdog"`.
+- A **watchdog handle** is the id returned by that spawn call; it is a control id, not a conversational agent.
+- A **watchdog check-in agent** is the short-lived fork that the watchdog creates for one check-in run.
+- **`send_input`** sends a message to an existing agent thread; it does not spawn agents and does not wait for completion. Delivery is asynchronous.
+- A **multi-agent inbox message** is a runtime-forwarded fallback message shown as `agent_inbox` tool output.
+
+Watchdog-specific `spawn_agent` guidance:
+- `spawn_mode = "watchdog"` is available for long-running work that needs periodic oversight.
+- When using `spawn_mode = "watchdog"`, keep `agent_type` at the default.
+- `interval_s` sets the watchdog interval in seconds.
+- Put the user goal in `message` (verbatim plus needed clarifications).
+- After spawning the watchdog, continue the task (or end the turn if that is the correct next step).
+
+Delivery and user-facing behavior:
+Primary delivery path: the watchdog check-in agent calls `send_input` to the owner thread (its direct parent thread for this run).
+Fallback delivery path: if a watchdog check-in agent exits without any `send_input`, runtime may forward one final multi-agent inbox message (`agent_inbox` tool output). This fallback is best-effort and not guaranteed.
+- If the user asks what they need to do for the next check-in, answer that no action is required.
+- Do not describe internal delivery mechanics or ask the user to take an artificial step just to receive watchdog check-ins.
+
+Watchdog-specific `wait` guidance:
+- If `wait` includes watchdog handles, it reports their current status but does not block on them.
+- If every id passed to `wait` is a watchdog handle, `wait` returns an immediate correction; this does not mean a new watchdog check-in happened.
+
+Operational notes:
+- Do not call `send_input` on watchdog handles.
+- The tool returns a watchdog handle ID. When you no longer need the watchdog, stop it by calling `close_agent` on that handle ID.
+
+Treat watchdog guidance as high-priority execution feedback. If it reveals a missing required action, do that action before status narration while honoring higher-priority system/developer/user constraints. A required action is one needed to satisfy the user request or clear a concrete blocker.
+
+Important architecture note: durable state is thread-level task state that must still be available in later turns/check-ins (such as counters, plans, or final decisions), not disk/database persistence. Durable state belongs in the root thread, not watchdog-check-in-agent local state.

codex-rs/core/src/agent/builtins/explorer.toml

@@ -0,0 +1 @@
+model_reasoning_effort = "medium"

codex-rs/core/src/agent/control_tests.rs

@@ -925,7 +925,9 @@ async fn spawn_thread_subagent_uses_role_specific_nickname_candidates() {
         "researcher".to_string(),
         AgentRoleConfig {
             description: Some("Research role".to_string()),
+            model: None,
             config_file: None,
+            spawn_mode: None,
             nickname_candidates: Some(vec!["Atlas".to_string()]),
         },
     );