changes

Persist thread_dynamic_tools in sqlite and read first from it. Fall back
to rollout files if it's not found. Persist dynamic tools to both sqlite
and rollout files.

Saw that new sessions get populated to db correctly & old sessions get
backfilled correctly at startup:
```
celia@com-92114 codex-rs % sqlite3 ~/.codex/state.sqlite \      "select thread_id, position,name,description,input_schema from thread_dynamic_tools;"
019c0cad-ec0d-74b2-a787-e8b33a349117|0|geo_lookup|lookup a city|{"properties":{"city":{"type":"string"}},"required":["city"],"type":"object"}
....
019c10ca-aa4b-7620-ae40-c0919fbd7ea7|0|geo_lookup|lookup a city|{"properties":{"city":{"type":"string"}},"required":["city"],"type":"object"}
```

.github/codex/labels/codex-rust-review.md

@@ -15,10 +15,10 @@ Things to look out for when doing the review:
 
 ## Code Organization
 
-- Each create in the Cargo workspace in `codex-rs` has a specific purpose: make a note if you believe new code is not introduced in the correct crate.
+- Each crate in the Cargo workspace in `codex-rs` has a specific purpose: make a note if you believe new code is not introduced in the correct crate.
 - When possible, try to keep the `core` crate as small as possible. Non-core but shared logic is often a good candidate for `codex-rs/common`.
 - Be wary of large files and offer suggestions for how to break things into more reasonably-sized files.
-- Rust files should generally be organized such that the public parts of the API appear near the top of the file and helper functions go below. This is analagous to the "inverted pyramid" structure that is favored in journalism.
+- Rust files should generally be organized such that the public parts of the API appear near the top of the file and helper functions go below. This is analogous to the "inverted pyramid" structure that is favored in journalism.
 
 ## Assertions in Tests
 

.github/workflows/issue-labeler.yml

@@ -38,9 +38,10 @@ jobs:
             - If applicable, add one of the following labels to specify which sub-product or product surface the issue relates to.
             1. CLI — the Codex command line interface.
             2. extension — VS Code (or other IDE) extension-specific issues.
-            3. codex-web — Issues targeting the Codex web UI/Cloud experience.
-            4. github-action — Issues with the Codex GitHub action.
-            5. iOS — Issues with the Codex iOS app.
+            3. app - Issues related to the Codex desktop application.
+            4. codex-web — Issues targeting the Codex web UI/Cloud experience.
+            5. github-action — Issues with the Codex GitHub action.
+            6. iOS — Issues with the Codex iOS app.
 
             - Additionally add zero or more of the following labels that are relevant to the issue content. Prefer a small set of precise labels over many broad ones.
             1. windows-os — Bugs or friction specific to Windows environments (always when PowerShell is mentioned, path handling, copy/paste, OS-specific auth or tooling failures).

README.md

@@ -1,7 +1,7 @@
 <p align="center"><code>npm i -g @openai/codex</code><br />or <code>brew install --cask codex</code></p>
 <p align="center"><strong>Codex CLI</strong> is a coding agent from OpenAI that runs locally on your computer.
 <p align="center">
-  <img src="./.github/codex-cli-splash.png" alt="Codex CLI splash" width="80%" />
+  <img src="https://github.com/openai/codex/blob/main/.github/codex-cli-splash.png" alt="Codex CLI splash" width="80%" />
 </p>
 </br>
 If you want Codex in your code editor (VS Code, Cursor, Windsurf), <a href="https://developers.openai.com/codex/ide">install in your IDE.</a>

announcement_tip.toml

@@ -14,4 +14,4 @@ target_app = "cli"
 [[announcements]]
 content = "This is a test announcement"
 version_regex = "^0\\.0\\.0$"
-to_date = "2026-01-10"
+to_date = "2026-05-10"

codex-rs/Cargo.toml

@@ -5,15 +5,13 @@ members = [
     "async-utils",
     "app-server",
     "app-server-protocol",
-    "app-server-protocol-stable-export",
-    "app-server-json-schema",
-    "app-server-ts-types",
     "app-server-test-client",
     "debug-client",
     "apply-patch",
     "arg0",
     "feedback",
     "codex-backend-openapi-models",
+    "cloud-requirements",
     "cloud-tasks",
     "cloud-tasks-client",
     "cli",
@@ -45,12 +43,14 @@ members = [
     "utils/cache",
     "utils/image",
     "utils/json-to-toml",
+    "utils/home-dir",
     "utils/pty",
     "utils/readiness",
     "utils/string",
     "codex-client",
     "codex-api",
     "state",
+    "codex-experimental-api-macros",
 ]
 resolver = "2"
 
@@ -69,13 +69,13 @@ app_test_support = { path = "app-server/tests/common" }
 codex-ansi-escape = { path = "ansi-escape" }
 codex-api = { path = "codex-api" }
 codex-app-server = { path = "app-server" }
-codex-app-server-json-schema = { path = "app-server-json-schema" }
 codex-app-server-protocol = { path = "app-server-protocol" }
-codex-app-server-ts-types = { path = "app-server-ts-types" }
+codex-app-server-test-client = { path = "app-server-test-client" }
 codex-apply-patch = { path = "apply-patch" }
 codex-arg0 = { path = "arg0" }
 codex-async-utils = { path = "async-utils" }
 codex-backend-client = { path = "backend-client" }
+codex-cloud-requirements = { path = "cloud-requirements" }
 codex-chatgpt = { path = "chatgpt" }
 codex-cli = { path = "cli"}
 codex-client = { path = "codex-client" }
@@ -83,6 +83,7 @@ codex-common = { path = "common" }
 codex-core = { path = "core" }
 codex-exec = { path = "exec" }
 codex-execpolicy = { path = "execpolicy" }
+codex-experimental-api-macros = { path = "codex-experimental-api-macros" }
 codex-feedback = { path = "feedback" }
 codex-file-search = { path = "file-search" }
 codex-git = { path = "utils/git" }
@@ -105,6 +106,7 @@ codex-utils-cache = { path = "utils/cache" }
 codex-utils-cargo-bin = { path = "utils/cargo-bin" }
 codex-utils-image = { path = "utils/image" }
 codex-utils-json-to-toml = { path = "utils/json-to-toml" }
+codex-utils-home-dir = { path = "utils/home-dir" }
 codex-utils-pty = { path = "utils/pty" }
 codex-utils-readiness = { path = "utils/readiness" }
 codex-utils-string = { path = "utils/string" }
@@ -156,6 +158,7 @@ image = { version = "^0.25.9", default-features = false }
 include_dir = "0.7.4"
 indexmap = "2.12.0"
 insta = "1.46.0"
+inventory = "0.3.19"
 itertools = "0.14.0"
 keyring = { version = "3.6", default-features = false }
 landlock = "0.4.4"

codex-rs/app-server-json-schema/BUILD.bazel

@@ -1,21 +0,0 @@
-load("//:defs.bzl", "codex_rust_crate")
-
-stable_files = glob(
-    include = ["stable/**"],
-    allow_empty = True,
-    exclude = [
-        "**/* *",
-        "BUILD.bazel",
-        "Cargo.toml",
-    ],
-)
-
-codex_rust_crate(
-    name = "app-server-json-schema",
-    compile_data = stable_files,
-    crate_name = "codex_app_server_json_schema",
-    extra_binaries = [
-        "//codex-rs/app-server-protocol-stable-export:codex-app-server-protocol-stable-export",
-    ],
-    test_data_extra = stable_files,
-)

codex-rs/app-server-json-schema/Cargo.toml

@@ -1,17 +0,0 @@
-[package]
-name = "codex-app-server-json-schema"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-
-[lints]
-workspace = true
-
-[dependencies]
-include_dir = { workspace = true }
-
-[dev-dependencies]
-anyhow = { workspace = true }
-codex-utils-cargo-bin = { workspace = true }
-pretty_assertions = { workspace = true }
-tempfile = { workspace = true }

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

@@ -1,39 +0,0 @@
-use std::ffi::OsStr;
-use std::fs;
-use std::io;
-use std::path::Path;
-
-static STABLE_APP_SERVER_JSON_SCHEMA_DIR: include_dir::Dir<'_> =
-    include_dir::include_dir!("$CARGO_MANIFEST_DIR/stable");
-
-/// Write the bundled stable JSON Schema artifacts to `out_dir`.
-pub fn write_stable_json_schema(out_dir: &Path) -> io::Result<()> {
-    fs::create_dir_all(out_dir)?;
-    write_dir_recursive(&STABLE_APP_SERVER_JSON_SCHEMA_DIR, out_dir, "json")
-}
-
-fn write_dir_recursive(
-    dir: &include_dir::Dir<'_>,
-    out_dir: &Path,
-    extension: &str,
-) -> io::Result<()> {
-    for file in dir.files() {
-        if file
-            .path()
-            .extension()
-            .is_some_and(|ext| ext == OsStr::new(extension))
-        {
-            let out_path = out_dir.join(file.path());
-            if let Some(parent) = out_path.parent() {
-                fs::create_dir_all(parent)?;
-            }
-            fs::write(out_path, file.contents())?;
-        }
-    }
-
-    for child in dir.dirs() {
-        write_dir_recursive(child, out_dir, extension)?;
-    }
-
-    Ok(())
-}

codex-rs/app-server-json-schema/stable/v2/LoginAccountParams.json

@@ -1,42 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "oneOf": [
-    {
-      "properties": {
-        "apiKey": {
-          "type": "string"
-        },
-        "type": {
-          "enum": [
-            "apiKey"
-          ],
-          "title": "ApiKeyv2::LoginAccountParamsType",
-          "type": "string"
-        }
-      },
-      "required": [
-        "apiKey",
-        "type"
-      ],
-      "title": "ApiKeyv2::LoginAccountParams",
-      "type": "object"
-    },
-    {
-      "properties": {
-        "type": {
-          "enum": [
-            "chatgpt"
-          ],
-          "title": "Chatgptv2::LoginAccountParamsType",
-          "type": "string"
-        }
-      },
-      "required": [
-        "type"
-      ],
-      "title": "Chatgptv2::LoginAccountParams",
-      "type": "object"
-    }
-  ],
-  "title": "LoginAccountParams"
-}

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

@@ -1,108 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "definitions": {
-    "AskForApproval": {
-      "enum": [
-        "untrusted",
-        "on-failure",
-        "on-request",
-        "never"
-      ],
-      "type": "string"
-    },
-    "Personality": {
-      "enum": [
-        "friendly",
-        "pragmatic"
-      ],
-      "type": "string"
-    },
-    "SandboxMode": {
-      "enum": [
-        "read-only",
-        "workspace-write",
-        "danger-full-access"
-      ],
-      "type": "string"
-    }
-  },
-  "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
-  "properties": {
-    "approvalPolicy": {
-      "anyOf": [
-        {
-          "$ref": "#/definitions/AskForApproval"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "baseInstructions": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "config": {
-      "additionalProperties": true,
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "cwd": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "developerInstructions": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "model": {
-      "description": "Configuration overrides for the resumed thread, if any.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "modelProvider": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "personality": {
-      "anyOf": [
-        {
-          "$ref": "#/definitions/Personality"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "sandbox": {
-      "anyOf": [
-        {
-          "$ref": "#/definitions/SandboxMode"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "threadId": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "threadId"
-  ],
-  "title": "ThreadResumeParams",
-  "type": "object"
-}

codex-rs/app-server-json-schema/tests/stable_artifacts.rs

@@ -1,132 +0,0 @@
-use anyhow::Context;
-use anyhow::Result;
-use anyhow::bail;
-use codex_utils_cargo_bin::cargo_bin;
-use codex_utils_cargo_bin::repo_root;
-use codex_utils_cargo_bin::runfiles_available;
-use pretty_assertions::assert_eq;
-use std::collections::BTreeMap;
-use std::collections::BTreeSet;
-use std::ffi::OsStr;
-use std::fs;
-use std::path::Path;
-use std::path::PathBuf;
-use std::process::Command;
-use tempfile::TempDir;
-
-const STABLE_EXPORT_BIN: &str = "codex-app-server-protocol-stable-export";
-
-#[test]
-fn stable_json_schema_match_generation() -> Result<()> {
-    let repo_root = repo_root()?;
-    let codex_rs = repo_root.join("codex-rs");
-    let hint = "run: just write-app-server-protocol-stable";
-    let expected_dir = codex_utils_cargo_bin::find_resource!("stable").with_context(|| {
-        "failed to resolve stable JSON Schema artifacts in this package; ".to_owned() + hint
-    })?;
-
-    let temp_dir = TempDir::new()?;
-    let out_dir = temp_dir.path().join("generated");
-
-    let output = if option_env!("BAZEL_PACKAGE").is_some() || runfiles_available() {
-        let stable_export_bin = cargo_bin(STABLE_EXPORT_BIN)
-            .context("failed to resolve stable-export binary via cargo_bin")?;
-        Command::new(stable_export_bin)
-            .current_dir(&codex_rs)
-            .args(["--out"])
-            .arg(&out_dir)
-            .output()
-            .context("failed to run stable-export binary to generate artifacts")?
-    } else {
-        // Use a separate cargo invocation with an isolated target dir to avoid
-        // workspace feature unification (notably `codex-experimental-api`).
-        let target_dir = temp_dir.path().join("cargo-target");
-        Command::new("cargo")
-            .current_dir(&codex_rs)
-            .env("CARGO_TARGET_DIR", &target_dir)
-            .args(["run", "-p", STABLE_EXPORT_BIN, "--", "--out"])
-            .arg(&out_dir)
-            .output()
-            .context("failed to run cargo to generate stable app-server protocol artifacts")?
-    };
-
-    if !output.status.success() {
-        let status = output.status;
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        bail!("cargo run failed with status {status}\nstdout:\n{stdout}\nstderr:\n{stderr}");
-    }
-
-    let expected = collect_files(&expected_dir, "json")?;
-    let generated = collect_files(&out_dir, "json")?;
-    let diffs = compare_maps(&expected, &generated, "json");
-
-    let assert_hint = "If this fails, run: just write-app-server-protocol-stable";
-    assert_eq!(diffs, Vec::<String>::new(), "{assert_hint}");
-    Ok(())
-}
-
-fn compare_maps(
-    expected: &BTreeMap<PathBuf, Vec<u8>>,
-    generated: &BTreeMap<PathBuf, Vec<u8>>,
-    label: &str,
-) -> Vec<String> {
-    let expected_paths: BTreeSet<PathBuf> = expected.keys().cloned().collect();
-    let generated_paths: BTreeSet<PathBuf> = generated.keys().cloned().collect();
-
-    let mut diffs = Vec::new();
-    for missing in expected_paths.difference(&generated_paths) {
-        let missing = missing.display();
-        diffs.push(format!("missing generated {label} file: {missing}"));
-    }
-    for extra in generated_paths.difference(&expected_paths) {
-        let extra = extra.display();
-        diffs.push(format!("unexpected generated {label} file: {extra}"));
-    }
-    for path in expected_paths.intersection(&generated_paths) {
-        let Some(expected_bytes) = expected.get(path) else {
-            let path = path.display();
-            diffs.push(format!(
-                "expected {label} artifacts missing intersection file: {path}"
-            ));
-            continue;
-        };
-        let Some(generated_bytes) = generated.get(path) else {
-            let path = path.display();
-            diffs.push(format!(
-                "generated {label} artifacts missing intersection file: {path}"
-            ));
-            continue;
-        };
-        if expected_bytes != generated_bytes {
-            let path = path.display();
-            diffs.push(format!("generated {label} file contents differ: {path}"));
-        }
-    }
-
-    diffs
-}
-
-fn collect_files(root: &Path, extension: &str) -> Result<BTreeMap<PathBuf, Vec<u8>>> {
-    let mut files = BTreeMap::new();
-    let mut stack = vec![root.to_path_buf()];
-    while let Some(dir) = stack.pop() {
-        for entry in fs::read_dir(&dir)? {
-            let entry = entry?;
-            let path = entry.path();
-            if path.is_dir() {
-                stack.push(path);
-                continue;
-            }
-            if path
-                .extension()
-                .is_some_and(|ext| ext == OsStr::new(extension))
-            {
-                let rel_path = path.strip_prefix(root)?;
-                let bytes = fs::read(&path)?;
-                files.insert(rel_path.to_path_buf(), bytes);
-            }
-        }
-    }
-    Ok(files)
-}

codex-rs/app-server-protocol-stable-export/BUILD.bazel

@@ -1,26 +0,0 @@
-# load("//:defs.bzl", "codex_rust_crate")
-load("@rules_rust//rust:defs.bzl", "rust_binary")
-
-# codex_rust_crate(
-#     name = "app-server-protocol-stable-export",
-#     crate_name = "codex_app_server_protocol_stable_export",
-#     alt_deps = {
-#         "//codex-rs/app-server-protocol:app-server-protocol": "//codex-rs/app-server-protocol:app-server-protocol-stable",
-#     },
-# )
-
-rust_binary(
-    name = "codex-app-server-protocol-stable-export",
-    srcs = ["//codex-rs/app-server-protocol-stable-export:src/main.rs"],
-    crate_name = "codex_app_server_protocol_stable_export",
-    crate_root = "//codex-rs/app-server-protocol-stable-export:src/main.rs",
-    generator_function = "codex_rust_crate",
-    generator_location = "codex-rs/app-server-protocol-stable-export/BUILD.bazel:3:17",
-    generator_name = "app-server-protocol-stable-export",
-    visibility = ["//visibility:public"],
-    deps = [
-        "//codex-rs/app-server-protocol:app-server-protocol-stable",
-        "@crates//:anyhow-1.0.100",
-        "@crates//:clap-4.5.54",
-    ],
-)

codex-rs/app-server-protocol-stable-export/Cargo.toml

@@ -1,17 +0,0 @@
-[package]
-name = "codex-app-server-protocol-stable-export"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-
-[[bin]]
-name = "codex-app-server-protocol-stable-export"
-path = "src/main.rs"
-
-[lints]
-workspace = true
-
-[dependencies]
-anyhow = { workspace = true }
-clap = { workspace = true, features = ["derive"] }
-codex-app-server-protocol = { path = "../app-server-protocol", default-features = false }

codex-rs/app-server-protocol-stable-export/src/main.rs

@@ -1,22 +0,0 @@
-use anyhow::Result;
-use clap::Parser;
-use std::path::PathBuf;
-
-#[derive(Parser, Debug)]
-#[command(
-    about = "Generate stable TypeScript bindings and JSON Schemas for the Codex app-server protocol"
-)]
-struct Args {
-    /// Output directory where generated files will be written
-    #[arg(short = 'o', long = "out", value_name = "DIR")]
-    out_dir: PathBuf,
-
-    /// Optional Prettier executable path to format generated TypeScript files
-    #[arg(short = 'p', long = "prettier", value_name = "PRETTIER_BIN")]
-    prettier: Option<PathBuf>,
-}
-
-fn main() -> Result<()> {
-    let args = Args::parse();
-    codex_app_server_protocol::generate_types(&args.out_dir, args.prettier.as_deref())
-}

codex-rs/app-server-protocol/BUILD.bazel

@@ -2,11 +2,6 @@ load("//:defs.bzl", "codex_rust_crate")
 
 codex_rust_crate(
     name = "app-server-protocol",
-    crate_features = ["codex-experimental-api"],
     crate_name = "codex_app_server_protocol",
-    alt_rules = {
-        "app-server-protocol-stable": {
-            "crate_features": [],
-        }
-    }
+    test_data_extra = glob(["schema/**"], allow_empty = True),
 )

codex-rs/app-server-protocol/Cargo.toml

@@ -11,14 +11,11 @@ path = "src/lib.rs"
 [lints]
 workspace = true
 
-[features]
-default = ["codex-experimental-api"]
-codex-experimental-api = []
-
 [dependencies]
 anyhow = { workspace = true }
 clap = { workspace = true, features = ["derive"] }
 codex-protocol = { workspace = true }
+codex-experimental-api-macros = { workspace = true }
 codex-utils-absolute-path = { workspace = true }
 mcp-types = { workspace = true }
 schemars = { workspace = true }
@@ -27,8 +24,12 @@ serde_json = { workspace = true }
 strum_macros = { workspace = true }
 thiserror = { workspace = true }
 ts-rs = { workspace = true }
+inventory = { workspace = true }
 uuid = { workspace = true, features = ["serde", "v7"] }
 
 [dev-dependencies]
 anyhow = { workspace = true }
+codex-utils-cargo-bin = { workspace = true }
 pretty_assertions = { workspace = true }
+similar = { workspace = true }
+tempfile = { workspace = true }

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

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "ChatgptAuthTokensRefreshReason": {
+      "oneOf": [
+        {
+          "description": "Codex attempted a backend request and received `401 Unauthorized`.",
+          "enum": [
+            "unauthorized"
+          ],
+          "type": "string"
+        }
+      ]
+    }
+  },
+  "properties": {
+    "previousAccountId": {
+      "description": "Workspace/account identifier that Codex was previously using.\n\nClients that manage multiple accounts/workspaces can use this as a hint to refresh the token for the correct workspace.\n\nThis may be `null` when the prior ID token did not include a workspace identifier (`chatgpt_account_id`) or when the token could not be parsed.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "reason": {
+      "$ref": "#/definitions/ChatgptAuthTokensRefreshReason"
+    }
+  },
+  "required": [
+    "reason"
+  ],
+  "title": "ChatgptAuthTokensRefreshParams",
+  "type": "object"
+}

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "properties": {
+    "accessToken": {
+      "type": "string"
+    },
+    "idToken": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "accessToken",
+    "idToken"
+  ],
+  "title": "ChatgptAuthTokensRefreshResponse",
+  "type": "object"
+}

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

@@ -9,6 +9,10 @@
       "properties": {
         "conversationId": {
           "$ref": "#/definitions/ThreadId"
+        },
+        "experimentalRawEvents": {
+          "default": false,
+          "type": "boolean"
         }
       },
       "required": [
@@ -156,6 +160,22 @@
       ],
       "type": "object"
     },
+    "CollaborationMode": {
+      "description": "Collaboration mode for a Codex session.",
+      "properties": {
+        "mode": {
+          "$ref": "#/definitions/ModeKind"
+        },
+        "settings": {
+          "$ref": "#/definitions/Settings"
+        }
+      },
+      "required": [
+        "mode",
+        "settings"
+      ],
+      "type": "object"
+    },
     "CommandExecParams": {
       "properties": {
         "command": {
@@ -654,8 +674,29 @@
       ],
       "type": "object"
     },
+    "InitializeCapabilities": {
+      "description": "Client-declared capabilities negotiated during initialize.",
+      "properties": {
+        "experimentalApi": {
+          "default": false,
+          "description": "Opt into receiving experimental API methods and fields.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
     "InitializeParams": {
       "properties": {
+        "capabilities": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/InitializeCapabilities"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "clientInfo": {
           "$ref": "#/definitions/ClientInfo"
         }
@@ -922,6 +963,33 @@
           ],
           "title": "ChatgptLoginAccountParams",
           "type": "object"
+        },
+        {
+          "description": "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE. The access token must contain the same scopes that Codex-managed ChatGPT auth tokens have.",
+          "properties": {
+            "accessToken": {
+              "description": "Access token (JWT) supplied by the client. This token is used for backend API requests.",
+              "type": "string"
+            },
+            "idToken": {
+              "description": "ID token (JWT) supplied by the client.\n\nThis token is used for identity and account metadata (email, plan type, workspace id).",
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "chatgptAuthTokens"
+              ],
+              "title": "ChatgptAuthTokensLoginAccountParamsType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "accessToken",
+            "idToken",
+            "type"
+          ],
+          "title": "ChatgptAuthTokensLoginAccountParams",
+          "type": "object"
         }
       ]
     },
@@ -970,6 +1038,17 @@
       ],
       "type": "string"
     },
+    "ModeKind": {
+      "description": "Initial collaboration mode to use when the TUI starts.",
+      "enum": [
+        "plan",
+        "code",
+        "pair_programming",
+        "execute",
+        "custom"
+      ],
+      "type": "string"
+    },
     "ModelListParams": {
       "properties": {
         "cursor": {
@@ -2031,6 +2110,34 @@
       },
       "type": "object"
     },
+    "Settings": {
+      "description": "Settings for a collaboration mode.",
+      "properties": {
+        "developer_instructions": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model": {
+          "type": "string"
+        },
+        "reasoning_effort": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ReasoningEffort"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "model"
+      ],
+      "type": "object"
+    },
     "SkillsConfigWriteParams": {
       "properties": {
         "enabled": {
@@ -2147,6 +2254,13 @@
             "null"
           ]
         },
+        "path": {
+          "description": "[UNSTABLE] Specify the rollout path to fork from. If specified, the thread_id param will be ignored.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "sandbox": {
           "anyOf": [
             {
@@ -2303,6 +2417,16 @@
             "null"
           ]
         },
+        "history": {
+          "description": "[UNSTABLE] FOR CODEX CLOUD - DO NOT USE. If specified, the thread will be resumed with the provided history instead of loaded from disk.",
+          "items": {
+            "$ref": "#/definitions/ResponseItem"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
         "model": {
           "description": "Configuration overrides for the resumed thread, if any.",
           "type": [
@@ -2316,6 +2440,13 @@
             "null"
           ]
         },
+        "path": {
+          "description": "[UNSTABLE] Specify the rollout path to resume from. If specified, the thread_id param will be ignored.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "personality": {
           "anyOf": [
             {
@@ -2363,6 +2494,21 @@
       ],
       "type": "object"
     },
+    "ThreadSetNameParams": {
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "threadId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "threadId"
+      ],
+      "type": "object"
+    },
     "ThreadSortKey": {
       "enum": [
         "created_at",
@@ -2422,21 +2568,17 @@
             "null"
           ]
         },
-        "dynamicTools": {
-          "items": {
-            "$ref": "#/definitions/DynamicToolSpec"
-          },
-          "type": [
-            "array",
-            "null"
-          ]
-        },
         "ephemeral": {
           "type": [
             "boolean",
             "null"
           ]
         },
+        "experimentalRawEvents": {
+          "default": false,
+          "description": "If true, opt into emitting raw response items on the event stream.\n\nThis is for internal use only (e.g. Codex Cloud). (TODO): Figure out a better way to categorize internal / experimental events & protocols.",
+          "type": "boolean"
+        },
         "model": {
           "type": [
             "string",
@@ -2511,6 +2653,17 @@
           ],
           "description": "Override the approval policy for this turn and subsequent turns."
         },
+        "collaborationMode": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CollaborationMode"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "EXPERIMENTAL - set a pre-set collaboration mode. Takes precedence over model, reasoning_effort, and developer instructions if set."
+        },
         "cwd": {
           "description": "Override the working directory for this turn and subsequent turns.",
           "type": [
@@ -2756,6 +2909,15 @@
       "oneOf": [
         {
           "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
             "query": {
               "type": [
                 "string",
@@ -2968,6 +3130,30 @@
       "title": "Thread/archiveRequest",
       "type": "object"
     },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "thread/name/set"
+          ],
+          "title": "Thread/name/setRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/ThreadSetNameParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Thread/name/setRequest",
+      "type": "object"
+    },
     {
       "properties": {
         "id": {

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

@@ -680,6 +680,14 @@
         {
           "description": "Agent has started a turn. v1 wire format uses `task_started`; accept `turn_started` for v2 interop.",
           "properties": {
+            "collaboration_mode_kind": {
+              "allOf": [
+                {
+                  "$ref": "#/definitions/ModeKind"
+                }
+              ],
+              "default": "code"
+            },
             "model_context_window": {
               "format": "int64",
               "type": [
@@ -1041,12 +1049,14 @@
               "description": "How to sandbox commands executed in the system"
             },
             "session_id": {
-              "allOf": [
-                {
-                  "$ref": "#/definitions/ThreadId"
-                }
-              ],
-              "description": "Name left as session_id instead of thread_id for backwards compatibility."
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "description": "Optional user-facing thread name (may be unset).",
+              "type": [
+                "string",
+                "null"
+              ]
             },
             "type": {
               "enum": [
@@ -1070,6 +1080,33 @@
           "title": "SessionConfiguredEventMsg",
           "type": "object"
         },
+        {
+          "description": "Updated session metadata (e.g., thread name changes).",
+          "properties": {
+            "thread_id": {
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "thread_name_updated"
+              ],
+              "title": "ThreadNameUpdatedEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "thread_id",
+            "type"
+          ],
+          "title": "ThreadNameUpdatedEventMsg",
+          "type": "object"
+        },
         {
           "description": "Incremental MCP startup progress updates.",
           "properties": {
@@ -2131,6 +2168,7 @@
           "properties": {
             "explanation": {
               "default": null,
+              "description": "Arguments for the `update_plan` todo/checklist tool (not plan mode).",
               "type": [
                 "string",
                 "null"
@@ -2356,6 +2394,38 @@
           "title": "AgentMessageContentDeltaEventMsg",
           "type": "object"
         },
+        {
+          "properties": {
+            "delta": {
+              "type": "string"
+            },
+            "item_id": {
+              "type": "string"
+            },
+            "thread_id": {
+              "type": "string"
+            },
+            "turn_id": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "plan_delta"
+              ],
+              "title": "PlanDeltaEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "delta",
+            "item_id",
+            "thread_id",
+            "turn_id",
+            "type"
+          ],
+          "title": "PlanDeltaEventMsg",
+          "type": "object"
+        },
         {
           "properties": {
             "delta": {
@@ -3206,6 +3276,17 @@
         }
       ]
     },
+    "ModeKind": {
+      "description": "Initial collaboration mode to use when the TUI starts.",
+      "enum": [
+        "plan",
+        "code",
+        "pair_programming",
+        "execute",
+        "custom"
+      ],
+      "type": "string"
+    },
     "NetworkAccess": {
       "description": "Represents whether outbound network access is available to the agent.",
       "enum": [
@@ -4912,6 +4993,30 @@
           "title": "AgentMessageTurnItem",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "Plan"
+              ],
+              "title": "PlanTurnItemType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "text",
+            "type"
+          ],
+          "title": "PlanTurnItem",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -5125,6 +5230,15 @@
       "oneOf": [
         {
           "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
             "query": {
               "type": [
                 "string",
@@ -5313,6 +5427,14 @@
     {
       "description": "Agent has started a turn. v1 wire format uses `task_started`; accept `turn_started` for v2 interop.",
       "properties": {
+        "collaboration_mode_kind": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/ModeKind"
+            }
+          ],
+          "default": "code"
+        },
         "model_context_window": {
           "format": "int64",
           "type": [
@@ -5674,12 +5796,14 @@
           "description": "How to sandbox commands executed in the system"
         },
         "session_id": {
-          "allOf": [
-            {
-              "$ref": "#/definitions/ThreadId"
-            }
-          ],
-          "description": "Name left as session_id instead of thread_id for backwards compatibility."
+          "$ref": "#/definitions/ThreadId"
+        },
+        "thread_name": {
+          "description": "Optional user-facing thread name (may be unset).",
+          "type": [
+            "string",
+            "null"
+          ]
         },
         "type": {
           "enum": [
@@ -5703,6 +5827,33 @@
       "title": "SessionConfiguredEventMsg",
       "type": "object"
     },
+    {
+      "description": "Updated session metadata (e.g., thread name changes).",
+      "properties": {
+        "thread_id": {
+          "$ref": "#/definitions/ThreadId"
+        },
+        "thread_name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "type": {
+          "enum": [
+            "thread_name_updated"
+          ],
+          "title": "ThreadNameUpdatedEventMsgType",
+          "type": "string"
+        }
+      },
+      "required": [
+        "thread_id",
+        "type"
+      ],
+      "title": "ThreadNameUpdatedEventMsg",
+      "type": "object"
+    },
     {
       "description": "Incremental MCP startup progress updates.",
       "properties": {
@@ -6764,6 +6915,7 @@
       "properties": {
         "explanation": {
           "default": null,
+          "description": "Arguments for the `update_plan` todo/checklist tool (not plan mode).",
           "type": [
             "string",
             "null"
@@ -6989,6 +7141,38 @@
       "title": "AgentMessageContentDeltaEventMsg",
       "type": "object"
     },
+    {
+      "properties": {
+        "delta": {
+          "type": "string"
+        },
+        "item_id": {
+          "type": "string"
+        },
+        "thread_id": {
+          "type": "string"
+        },
+        "turn_id": {
+          "type": "string"
+        },
+        "type": {
+          "enum": [
+            "plan_delta"
+          ],
+          "title": "PlanDeltaEventMsgType",
+          "type": "string"
+        }
+      },
+      "required": [
+        "delta",
+        "item_id",
+        "thread_id",
+        "turn_id",
+        "type"
+      ],
+      "title": "PlanDeltaEventMsg",
+      "type": "object"
+    },
     {
       "properties": {
         "delta": {

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

@@ -1,6 +1,13 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "properties": {
+    "grantRoot": {
+      "description": "[UNSTABLE] When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "itemId": {
       "type": "string"
     },

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

@@ -257,7 +257,7 @@
       "type": "object"
     },
     "AuthMode": {
-      "description": "Authentication mode for OpenAI-backed providers.\n\nThis is used internally to determine the base URL for generating responses, and to gate ChatGPT-only behaviors like rate limits and available models (as opposed to API key-based auth).",
+      "description": "Authentication mode for OpenAI-backed providers.",
       "oneOf": [
         {
           "description": "OpenAI API key provided by the caller and stored by Codex.",
@@ -272,6 +272,13 @@
             "chatgpt"
           ],
           "type": "string"
+        },
+        {
+          "description": "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE.\n\nChatGPT auth tokens are supplied by an external host app and are only stored in memory. Token refresh must be handled by the external host app.",
+          "enum": [
+            "chatgptAuthTokens"
+          ],
+          "type": "string"
         }
       ]
     },
@@ -1251,6 +1258,14 @@
         {
           "description": "Agent has started a turn. v1 wire format uses `task_started`; accept `turn_started` for v2 interop.",
           "properties": {
+            "collaboration_mode_kind": {
+              "allOf": [
+                {
+                  "$ref": "#/definitions/ModeKind"
+                }
+              ],
+              "default": "code"
+            },
             "model_context_window": {
               "format": "int64",
               "type": [
@@ -1612,12 +1627,14 @@
               "description": "How to sandbox commands executed in the system"
             },
             "session_id": {
-              "allOf": [
-                {
-                  "$ref": "#/definitions/ThreadId"
-                }
-              ],
-              "description": "Name left as session_id instead of thread_id for backwards compatibility."
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "description": "Optional user-facing thread name (may be unset).",
+              "type": [
+                "string",
+                "null"
+              ]
             },
             "type": {
               "enum": [
@@ -1641,6 +1658,33 @@
           "title": "SessionConfiguredEventMsg",
           "type": "object"
         },
+        {
+          "description": "Updated session metadata (e.g., thread name changes).",
+          "properties": {
+            "thread_id": {
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "thread_name_updated"
+              ],
+              "title": "ThreadNameUpdatedEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "thread_id",
+            "type"
+          ],
+          "title": "ThreadNameUpdatedEventMsg",
+          "type": "object"
+        },
         {
           "description": "Incremental MCP startup progress updates.",
           "properties": {
@@ -1796,7 +1840,7 @@
         {
           "properties": {
             "action": {
-              "$ref": "#/definitions/WebSearchAction"
+              "$ref": "#/definitions/WebSearchAction2"
             },
             "call_id": {
               "type": "string"
@@ -2702,6 +2746,7 @@
           "properties": {
             "explanation": {
               "default": null,
+              "description": "Arguments for the `update_plan` todo/checklist tool (not plan mode).",
               "type": [
                 "string",
                 "null"
@@ -2927,6 +2972,38 @@
           "title": "AgentMessageContentDeltaEventMsg",
           "type": "object"
         },
+        {
+          "properties": {
+            "delta": {
+              "type": "string"
+            },
+            "item_id": {
+              "type": "string"
+            },
+            "thread_id": {
+              "type": "string"
+            },
+            "turn_id": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "plan_delta"
+              ],
+              "title": "PlanDeltaEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "delta",
+            "item_id",
+            "thread_id",
+            "turn_id",
+            "type"
+          ],
+          "title": "PlanDeltaEventMsg",
+          "type": "object"
+        },
         {
           "properties": {
             "delta": {
@@ -3980,6 +4057,17 @@
       ],
       "type": "string"
     },
+    "ModeKind": {
+      "description": "Initial collaboration mode to use when the TUI starts.",
+      "enum": [
+        "plan",
+        "code",
+        "pair_programming",
+        "execute",
+        "custom"
+      ],
+      "type": "string"
+    },
     "NetworkAccess": {
       "description": "Represents whether outbound network access is available to the agent.",
       "enum": [
@@ -4166,6 +4254,30 @@
         }
       ]
     },
+    "PlanDeltaNotification": {
+      "description": "EXPERIMENTAL - proposed plan streaming deltas for plan items. Clients should not assume concatenated deltas match the completed plan item content.",
+      "properties": {
+        "delta": {
+          "type": "string"
+        },
+        "itemId": {
+          "type": "string"
+        },
+        "threadId": {
+          "type": "string"
+        },
+        "turnId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "delta",
+        "itemId",
+        "threadId",
+        "turnId"
+      ],
+      "type": "object"
+    },
     "PlanItemArg": {
       "additionalProperties": false,
       "properties": {
@@ -4986,7 +5098,7 @@
             "action": {
               "anyOf": [
                 {
-                  "$ref": "#/definitions/WebSearchAction"
+                  "$ref": "#/definitions/WebSearchAction2"
                 },
                 {
                   "type": "null"
@@ -5924,6 +6036,13 @@
           "description": "Model provider used for this thread (for example, 'openai').",
           "type": "string"
         },
+        "path": {
+          "description": "[UNSTABLE] Path to the thread on disk.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "preview": {
           "description": "Usually the first user message in the thread, if available.",
           "type": "string"
@@ -6018,6 +6137,31 @@
           "title": "AgentMessageThreadItem",
           "type": "object"
         },
+        {
+          "description": "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "plan"
+              ],
+              "title": "PlanThreadItemType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "text",
+            "type"
+          ],
+          "title": "PlanThreadItem",
+          "type": "object"
+        },
         {
           "properties": {
             "content": {
@@ -6286,6 +6430,16 @@
         },
         {
           "properties": {
+            "action": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/WebSearchAction"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
             "id": {
               "type": "string"
             },
@@ -6402,6 +6556,23 @@
         }
       ]
     },
+    "ThreadNameUpdatedNotification": {
+      "properties": {
+        "threadId": {
+          "type": "string"
+        },
+        "threadName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "threadId"
+      ],
+      "type": "object"
+    },
     "ThreadStartedNotification": {
       "properties": {
         "thread": {
@@ -6825,6 +6996,30 @@
           "title": "AgentMessageTurnItem",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "Plan"
+              ],
+              "title": "PlanTurnItemType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "text",
+            "type"
+          ],
+          "title": "PlanTurnItem",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -6862,7 +7057,7 @@
         {
           "properties": {
             "action": {
-              "$ref": "#/definitions/WebSearchAction"
+              "$ref": "#/definitions/WebSearchAction2"
             },
             "id": {
               "type": "string"
@@ -7233,6 +7428,15 @@
       "oneOf": [
         {
           "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
             "query": {
               "type": [
                 "string",
@@ -7257,7 +7461,7 @@
           "properties": {
             "type": {
               "enum": [
-                "open_page"
+                "openPage"
               ],
               "title": "OpenPageWebSearchActionType",
               "type": "string"
@@ -7285,7 +7489,7 @@
             },
             "type": {
               "enum": [
-                "find_in_page"
+                "findInPage"
               ],
               "title": "FindInPageWebSearchActionType",
               "type": "string"
@@ -7321,6 +7525,107 @@
         }
       ]
     },
+    "WebSearchAction2": {
+      "oneOf": [
+        {
+          "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
+            "query": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "search"
+              ],
+              "title": "SearchWebSearchAction2Type",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "title": "SearchWebSearchAction2",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "type": {
+              "enum": [
+                "open_page"
+              ],
+              "title": "OpenPageWebSearchAction2Type",
+              "type": "string"
+            },
+            "url": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "title": "OpenPageWebSearchAction2",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "pattern": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "find_in_page"
+              ],
+              "title": "FindInPageWebSearchAction2Type",
+              "type": "string"
+            },
+            "url": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "title": "FindInPageWebSearchAction2",
+          "type": "object"
+        },
+        {
+          "properties": {
+            "type": {
+              "enum": [
+                "other"
+              ],
+              "title": "OtherWebSearchAction2Type",
+              "type": "string"
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "title": "OtherWebSearchAction2",
+          "type": "object"
+        }
+      ]
+    },
     "WindowsWorldWritableWarningNotification": {
       "properties": {
         "extraCount": {
@@ -7389,6 +7694,26 @@
       "title": "Thread/startedNotification",
       "type": "object"
     },
+    {
+      "properties": {
+        "method": {
+          "enum": [
+            "thread/name/updated"
+          ],
+          "title": "Thread/name/updatedNotificationMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/ThreadNameUpdatedNotification"
+        }
+      },
+      "required": [
+        "method",
+        "params"
+      ],
+      "title": "Thread/name/updatedNotification",
+      "type": "object"
+    },
     {
       "properties": {
         "method": {
@@ -7570,6 +7895,27 @@
       "title": "Item/agentMessage/deltaNotification",
       "type": "object"
     },
+    {
+      "description": "EXPERIMENTAL - proposed plan streaming deltas for plan items.",
+      "properties": {
+        "method": {
+          "enum": [
+            "item/plan/delta"
+          ],
+          "title": "Item/plan/deltaNotificationMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/PlanDeltaNotification"
+        }
+      },
+      "required": [
+        "method",
+        "params"
+      ],
+      "title": "Item/plan/deltaNotification",
+      "type": "object"
+    },
     {
       "properties": {
         "method": {

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

@@ -38,6 +38,35 @@
       ],
       "type": "object"
     },
+    "ChatgptAuthTokensRefreshParams": {
+      "properties": {
+        "previousAccountId": {
+          "description": "Workspace/account identifier that Codex was previously using.\n\nClients that manage multiple accounts/workspaces can use this as a hint to refresh the token for the correct workspace.\n\nThis may be `null` when the prior ID token did not include a workspace identifier (`chatgpt_account_id`) or when the token could not be parsed.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "reason": {
+          "$ref": "#/definitions/ChatgptAuthTokensRefreshReason"
+        }
+      },
+      "required": [
+        "reason"
+      ],
+      "type": "object"
+    },
+    "ChatgptAuthTokensRefreshReason": {
+      "oneOf": [
+        {
+          "description": "Codex attempted a backend request and received `401 Unauthorized`.",
+          "enum": [
+            "unauthorized"
+          ],
+          "type": "string"
+        }
+      ]
+    },
     "CommandAction": {
       "oneOf": [
         {
@@ -345,6 +374,13 @@
     },
     "FileChangeRequestApprovalParams": {
       "properties": {
+        "grantRoot": {
+          "description": "[UNSTABLE] When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "itemId": {
           "type": "string"
         },
@@ -493,6 +529,86 @@
     },
     "ThreadId": {
       "type": "string"
+    },
+    "ToolRequestUserInputOption": {
+      "description": "EXPERIMENTAL. Defines a single selectable option for request_user_input.",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "description",
+        "label"
+      ],
+      "type": "object"
+    },
+    "ToolRequestUserInputParams": {
+      "description": "EXPERIMENTAL. Params sent with a request_user_input event.",
+      "properties": {
+        "itemId": {
+          "type": "string"
+        },
+        "questions": {
+          "items": {
+            "$ref": "#/definitions/ToolRequestUserInputQuestion"
+          },
+          "type": "array"
+        },
+        "threadId": {
+          "type": "string"
+        },
+        "turnId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "itemId",
+        "questions",
+        "threadId",
+        "turnId"
+      ],
+      "type": "object"
+    },
+    "ToolRequestUserInputQuestion": {
+      "description": "EXPERIMENTAL. Represents one request_user_input question and its required options.",
+      "properties": {
+        "header": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "isOther": {
+          "default": false,
+          "type": "boolean"
+        },
+        "isSecret": {
+          "default": false,
+          "type": "boolean"
+        },
+        "options": {
+          "items": {
+            "$ref": "#/definitions/ToolRequestUserInputOption"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "question": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "header",
+        "id",
+        "question"
+      ],
+      "type": "object"
     }
   },
   "description": "Request initiated from the server and sent to the client.",
@@ -547,6 +663,31 @@
       "title": "Item/fileChange/requestApprovalRequest",
       "type": "object"
     },
+    {
+      "description": "EXPERIMENTAL - Request input from the user for a tool call.",
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "item/tool/requestUserInput"
+          ],
+          "title": "Item/tool/requestUserInputRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/ToolRequestUserInputParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Item/tool/requestUserInputRequest",
+      "type": "object"
+    },
     {
       "description": "Execute a dynamic tool call on the client.",
       "properties": {
@@ -572,6 +713,30 @@
       "title": "Item/tool/callRequest",
       "type": "object"
     },
+    {
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/RequestId"
+        },
+        "method": {
+          "enum": [
+            "account/chatgptAuthTokens/refresh"
+          ],
+          "title": "Account/chatgptAuthTokens/refreshRequestMethod",
+          "type": "string"
+        },
+        "params": {
+          "$ref": "#/definitions/ChatgptAuthTokensRefreshParams"
+        }
+      },
+      "required": [
+        "id",
+        "method",
+        "params"
+      ],
+      "title": "Account/chatgptAuthTokens/refreshRequest",
+      "type": "object"
+    },
     {
       "description": "DEPRECATED APIs below Request to approve a patch. This request is used for Turns started via the legacy APIs (i.e. SendUserTurn, SendUserMessage).",
       "properties": {

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

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "ToolRequestUserInputOption": {
+      "description": "EXPERIMENTAL. Defines a single selectable option for request_user_input.",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "description",
+        "label"
+      ],
+      "type": "object"
+    },
+    "ToolRequestUserInputQuestion": {
+      "description": "EXPERIMENTAL. Represents one request_user_input question and its required options.",
+      "properties": {
+        "header": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "isOther": {
+          "default": false,
+          "type": "boolean"
+        },
+        "isSecret": {
+          "default": false,
+          "type": "boolean"
+        },
+        "options": {
+          "items": {
+            "$ref": "#/definitions/ToolRequestUserInputOption"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "question": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "header",
+        "id",
+        "question"
+      ],
+      "type": "object"
+    }
+  },
+  "description": "EXPERIMENTAL. Params sent with a request_user_input event.",
+  "properties": {
+    "itemId": {
+      "type": "string"
+    },
+    "questions": {
+      "items": {
+        "$ref": "#/definitions/ToolRequestUserInputQuestion"
+      },
+      "type": "array"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "itemId",
+    "questions",
+    "threadId",
+    "turnId"
+  ],
+  "title": "ToolRequestUserInputParams",
+  "type": "object"
+}

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

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "ToolRequestUserInputAnswer": {
+      "description": "EXPERIMENTAL. Captures a user's answer to a request_user_input question.",
+      "properties": {
+        "answers": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "answers"
+      ],
+      "type": "object"
+    }
+  },
+  "description": "EXPERIMENTAL. Response payload mapping question ids to answers.",
+  "properties": {
+    "answers": {
+      "additionalProperties": {
+        "$ref": "#/definitions/ToolRequestUserInputAnswer"
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "answers"
+  ],
+  "title": "ToolRequestUserInputResponse",
+  "type": "object"
+}

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

@@ -8,6 +8,10 @@
   "properties": {
     "conversationId": {
       "$ref": "#/definitions/ThreadId"
+    },
+    "experimentalRawEvents": {
+      "default": false,
+      "type": "boolean"
     }
   },
   "required": [

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

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
     "AuthMode": {
-      "description": "Authentication mode for OpenAI-backed providers.\n\nThis is used internally to determine the base URL for generating responses, and to gate ChatGPT-only behaviors like rate limits and available models (as opposed to API key-based auth).",
+      "description": "Authentication mode for OpenAI-backed providers.",
       "oneOf": [
         {
           "description": "OpenAI API key provided by the caller and stored by Codex.",
@@ -17,6 +17,13 @@
             "chatgpt"
           ],
           "type": "string"
+        },
+        {
+          "description": "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE.\n\nChatGPT auth tokens are supplied by an external host app and are only stored in memory. Token refresh must be handled by the external host app.",
+          "enum": [
+            "chatgptAuthTokens"
+          ],
+          "type": "string"
         }
       ]
     }

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

@@ -680,6 +680,14 @@
         {
           "description": "Agent has started a turn. v1 wire format uses `task_started`; accept `turn_started` for v2 interop.",
           "properties": {
+            "collaboration_mode_kind": {
+              "allOf": [
+                {
+                  "$ref": "#/definitions/ModeKind"
+                }
+              ],
+              "default": "code"
+            },
             "model_context_window": {
               "format": "int64",
               "type": [
@@ -1041,12 +1049,14 @@
               "description": "How to sandbox commands executed in the system"
             },
             "session_id": {
-              "allOf": [
-                {
-                  "$ref": "#/definitions/ThreadId"
-                }
-              ],
-              "description": "Name left as session_id instead of thread_id for backwards compatibility."
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "description": "Optional user-facing thread name (may be unset).",
+              "type": [
+                "string",
+                "null"
+              ]
             },
             "type": {
               "enum": [
@@ -1070,6 +1080,33 @@
           "title": "SessionConfiguredEventMsg",
           "type": "object"
         },
+        {
+          "description": "Updated session metadata (e.g., thread name changes).",
+          "properties": {
+            "thread_id": {
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "thread_name_updated"
+              ],
+              "title": "ThreadNameUpdatedEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "thread_id",
+            "type"
+          ],
+          "title": "ThreadNameUpdatedEventMsg",
+          "type": "object"
+        },
         {
           "description": "Incremental MCP startup progress updates.",
           "properties": {
@@ -2131,6 +2168,7 @@
           "properties": {
             "explanation": {
               "default": null,
+              "description": "Arguments for the `update_plan` todo/checklist tool (not plan mode).",
               "type": [
                 "string",
                 "null"
@@ -2356,6 +2394,38 @@
           "title": "AgentMessageContentDeltaEventMsg",
           "type": "object"
         },
+        {
+          "properties": {
+            "delta": {
+              "type": "string"
+            },
+            "item_id": {
+              "type": "string"
+            },
+            "thread_id": {
+              "type": "string"
+            },
+            "turn_id": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "plan_delta"
+              ],
+              "title": "PlanDeltaEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "delta",
+            "item_id",
+            "thread_id",
+            "turn_id",
+            "type"
+          ],
+          "title": "PlanDeltaEventMsg",
+          "type": "object"
+        },
         {
           "properties": {
             "delta": {
@@ -3206,6 +3276,17 @@
         }
       ]
     },
+    "ModeKind": {
+      "description": "Initial collaboration mode to use when the TUI starts.",
+      "enum": [
+        "plan",
+        "code",
+        "pair_programming",
+        "execute",
+        "custom"
+      ],
+      "type": "string"
+    },
     "NetworkAccess": {
       "description": "Represents whether outbound network access is available to the agent.",
       "enum": [
@@ -4912,6 +4993,30 @@
           "title": "AgentMessageTurnItem",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "Plan"
+              ],
+              "title": "PlanTurnItemType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "text",
+            "type"
+          ],
+          "title": "PlanTurnItem",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -5125,6 +5230,15 @@
       "oneOf": [
         {
           "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
             "query": {
               "type": [
                 "string",

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

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
     "AuthMode": {
-      "description": "Authentication mode for OpenAI-backed providers.\n\nThis is used internally to determine the base URL for generating responses, and to gate ChatGPT-only behaviors like rate limits and available models (as opposed to API key-based auth).",
+      "description": "Authentication mode for OpenAI-backed providers.",
       "oneOf": [
         {
           "description": "OpenAI API key provided by the caller and stored by Codex.",
@@ -17,6 +17,13 @@
             "chatgpt"
           ],
           "type": "string"
+        },
+        {
+          "description": "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE.\n\nChatGPT auth tokens are supplied by an external host app and are only stored in memory. Token refresh must be handled by the external host app.",
+          "enum": [
+            "chatgptAuthTokens"
+          ],
+          "type": "string"
         }
       ]
     }

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

@@ -21,9 +21,30 @@
         "version"
       ],
       "type": "object"
+    },
+    "InitializeCapabilities": {
+      "description": "Client-declared capabilities negotiated during initialize.",
+      "properties": {
+        "experimentalApi": {
+          "default": false,
+          "description": "Opt into receiving experimental API methods and fields.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
     }
   },
   "properties": {
+    "capabilities": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/InitializeCapabilities"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "clientInfo": {
       "$ref": "#/definitions/ClientInfo"
     }

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

@@ -775,6 +775,15 @@
       "oneOf": [
         {
           "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
             "query": {
               "type": [
                 "string",

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

@@ -680,6 +680,14 @@
         {
           "description": "Agent has started a turn. v1 wire format uses `task_started`; accept `turn_started` for v2 interop.",
           "properties": {
+            "collaboration_mode_kind": {
+              "allOf": [
+                {
+                  "$ref": "#/definitions/ModeKind"
+                }
+              ],
+              "default": "code"
+            },
             "model_context_window": {
               "format": "int64",
               "type": [
@@ -1041,12 +1049,14 @@
               "description": "How to sandbox commands executed in the system"
             },
             "session_id": {
-              "allOf": [
-                {
-                  "$ref": "#/definitions/ThreadId"
-                }
-              ],
-              "description": "Name left as session_id instead of thread_id for backwards compatibility."
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "description": "Optional user-facing thread name (may be unset).",
+              "type": [
+                "string",
+                "null"
+              ]
             },
             "type": {
               "enum": [
@@ -1070,6 +1080,33 @@
           "title": "SessionConfiguredEventMsg",
           "type": "object"
         },
+        {
+          "description": "Updated session metadata (e.g., thread name changes).",
+          "properties": {
+            "thread_id": {
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "thread_name_updated"
+              ],
+              "title": "ThreadNameUpdatedEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "thread_id",
+            "type"
+          ],
+          "title": "ThreadNameUpdatedEventMsg",
+          "type": "object"
+        },
         {
           "description": "Incremental MCP startup progress updates.",
           "properties": {
@@ -2131,6 +2168,7 @@
           "properties": {
             "explanation": {
               "default": null,
+              "description": "Arguments for the `update_plan` todo/checklist tool (not plan mode).",
               "type": [
                 "string",
                 "null"
@@ -2356,6 +2394,38 @@
           "title": "AgentMessageContentDeltaEventMsg",
           "type": "object"
         },
+        {
+          "properties": {
+            "delta": {
+              "type": "string"
+            },
+            "item_id": {
+              "type": "string"
+            },
+            "thread_id": {
+              "type": "string"
+            },
+            "turn_id": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "plan_delta"
+              ],
+              "title": "PlanDeltaEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "delta",
+            "item_id",
+            "thread_id",
+            "turn_id",
+            "type"
+          ],
+          "title": "PlanDeltaEventMsg",
+          "type": "object"
+        },
         {
           "properties": {
             "delta": {
@@ -3206,6 +3276,17 @@
         }
       ]
     },
+    "ModeKind": {
+      "description": "Initial collaboration mode to use when the TUI starts.",
+      "enum": [
+        "plan",
+        "code",
+        "pair_programming",
+        "execute",
+        "custom"
+      ],
+      "type": "string"
+    },
     "NetworkAccess": {
       "description": "Represents whether outbound network access is available to the agent.",
       "enum": [
@@ -4912,6 +4993,30 @@
           "title": "AgentMessageTurnItem",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "Plan"
+              ],
+              "title": "PlanTurnItemType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "text",
+            "type"
+          ],
+          "title": "PlanTurnItem",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -5125,6 +5230,15 @@
       "oneOf": [
         {
           "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
             "query": {
               "type": [
                 "string",

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

@@ -680,6 +680,14 @@
         {
           "description": "Agent has started a turn. v1 wire format uses `task_started`; accept `turn_started` for v2 interop.",
           "properties": {
+            "collaboration_mode_kind": {
+              "allOf": [
+                {
+                  "$ref": "#/definitions/ModeKind"
+                }
+              ],
+              "default": "code"
+            },
             "model_context_window": {
               "format": "int64",
               "type": [
@@ -1041,12 +1049,14 @@
               "description": "How to sandbox commands executed in the system"
             },
             "session_id": {
-              "allOf": [
-                {
-                  "$ref": "#/definitions/ThreadId"
-                }
-              ],
-              "description": "Name left as session_id instead of thread_id for backwards compatibility."
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "description": "Optional user-facing thread name (may be unset).",
+              "type": [
+                "string",
+                "null"
+              ]
             },
             "type": {
               "enum": [
@@ -1070,6 +1080,33 @@
           "title": "SessionConfiguredEventMsg",
           "type": "object"
         },
+        {
+          "description": "Updated session metadata (e.g., thread name changes).",
+          "properties": {
+            "thread_id": {
+              "$ref": "#/definitions/ThreadId"
+            },
+            "thread_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "thread_name_updated"
+              ],
+              "title": "ThreadNameUpdatedEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "thread_id",
+            "type"
+          ],
+          "title": "ThreadNameUpdatedEventMsg",
+          "type": "object"
+        },
         {
           "description": "Incremental MCP startup progress updates.",
           "properties": {
@@ -2131,6 +2168,7 @@
           "properties": {
             "explanation": {
               "default": null,
+              "description": "Arguments for the `update_plan` todo/checklist tool (not plan mode).",
               "type": [
                 "string",
                 "null"
@@ -2356,6 +2394,38 @@
           "title": "AgentMessageContentDeltaEventMsg",
           "type": "object"
         },
+        {
+          "properties": {
+            "delta": {
+              "type": "string"
+            },
+            "item_id": {
+              "type": "string"
+            },
+            "thread_id": {
+              "type": "string"
+            },
+            "turn_id": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "plan_delta"
+              ],
+              "title": "PlanDeltaEventMsgType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "delta",
+            "item_id",
+            "thread_id",
+            "turn_id",
+            "type"
+          ],
+          "title": "PlanDeltaEventMsg",
+          "type": "object"
+        },
         {
           "properties": {
             "delta": {
@@ -3206,6 +3276,17 @@
         }
       ]
     },
+    "ModeKind": {
+      "description": "Initial collaboration mode to use when the TUI starts.",
+      "enum": [
+        "plan",
+        "code",
+        "pair_programming",
+        "execute",
+        "custom"
+      ],
+      "type": "string"
+    },
     "NetworkAccess": {
       "description": "Represents whether outbound network access is available to the agent.",
       "enum": [
@@ -4912,6 +4993,30 @@
           "title": "AgentMessageTurnItem",
           "type": "object"
         },
+        {
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "text": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "Plan"
+              ],
+              "title": "PlanTurnItemType",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "text",
+            "type"
+          ],
+          "title": "PlanTurnItem",
+          "type": "object"
+        },
         {
           "properties": {
             "id": {
@@ -5125,6 +5230,15 @@
       "oneOf": [
         {
           "properties": {
+            "queries": {
+              "items": {
+                "type": "string"
+              },
+              "type": [
+                "array",
+                "null"
+              ]
+            },
             "query": {
               "type": [
                 "string",

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

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
     "AuthMode": {
-      "description": "Authentication mode for OpenAI-backed providers.\n\nThis is used internally to determine the base URL for generating responses, and to gate ChatGPT-only behaviors like rate limits and available models (as opposed to API key-based auth).",
+      "description": "Authentication mode for OpenAI-backed providers.",
       "oneOf": [
         {
           "description": "OpenAI API key provided by the caller and stored by Codex.",
@@ -17,6 +17,13 @@
             "chatgpt"
           ],
           "type": "string"
+        },
+        {
+          "description": "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE.\n\nChatGPT auth tokens are supplied by an external host app and are only stored in memory. Token refresh must be handled by the external host app.",
+          "enum": [
+            "chatgptAuthTokens"
+          ],
+          "type": "string"
         }
       ]
     }