fix

## Summary
- fix typo in usage limit banner text
- update error message tests

## Testing
- `just fmt`
- `RUSTC_BOOTSTRAP=1 just fix` *(fails: `let` expressions in this
position are unstable)*
- `RUSTC_BOOTSTRAP=1 cargo test --all-features` *(fails: `let`
expressions in this position are unstable)*

------
https://chatgpt.com/codex/tasks/task_i_689610fc1fe4832081bdd1118779b60b

.github/actions/codex/src/process-label.ts

@@ -91,7 +91,38 @@ async function processLabel(
   labelConfig: LabelConfig,
 ): Promise<void> {
   const template = labelConfig.getPromptTemplate();
-  const populatedTemplate = await renderPromptTemplate(template, ctx);
+
+  // If this is a review label, prepend explicit PR-diff scoping guidance to
+  // reduce out-of-scope feedback. Do this before rendering so placeholders in
+  // the guidance (e.g., {CODEX_ACTION_GITHUB_EVENT_PATH}) are substituted.
+  const isReview = label.toLowerCase().includes("review");
+  const reviewScopeGuidance = `
+PR Diff Scope
+- Only review changes between the PR's merge-base and head; do not comment on commits or files outside this range.
+- Derive the base/head SHAs from the event JSON at {CODEX_ACTION_GITHUB_EVENT_PATH}, then compute and use the PR diff for all analysis and comments.
+
+Commands to determine scope
+- Resolve SHAs:
+  - BASE_SHA=$(jq -r '.pull_request.base.sha // .pull_request.base.ref' "{CODEX_ACTION_GITHUB_EVENT_PATH}")
+  - HEAD_SHA=$(jq -r '.pull_request.head.sha // .pull_request.head.ref' "{CODEX_ACTION_GITHUB_EVENT_PATH}")
+  - BASE_SHA=$(git rev-parse "$BASE_SHA")
+  - HEAD_SHA=$(git rev-parse "$HEAD_SHA")
+- Prefer triple-dot (merge-base) semantics for PR diffs:
+  - Changed commits: git log --oneline "$BASE_SHA...$HEAD_SHA"
+  - Changed files: git diff --name-status "$BASE_SHA...$HEAD_SHA"
+  - Review hunks: git diff -U0 "$BASE_SHA...$HEAD_SHA"
+
+Review rules
+- Anchor every comment to a file and hunk present in git diff "$BASE_SHA...$HEAD_SHA".
+- If you mention context outside the diff, label it as "Follow-up (outside this PR scope)" and keep it brief (<=2 bullets).
+- Do not critique commits or files not reachable in the PR range (merge-base(base, head) → head).
+`.trim();
+
+  const effectiveTemplate = isReview
+    ? `${reviewScopeGuidance}\n\n${template}`
+    : template;
+
+  const populatedTemplate = await renderPromptTemplate(effectiveTemplate, ctx);
 
   // Always run Codex and post the resulting message as a comment.
   let commentBody = await runCodex(populatedTemplate, ctx);

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

@@ -6,18 +6,134 @@ Then provide the **review** (1-2 sentences plus bullet points, friendly tone).
 
 Things to look out for when doing the review:
 
+## General Principles
+
 - **Make sure the pull request body explains the motivation behind the change.** If the author has failed to do this, call it out, and if you think you can deduce the motivation behind the change, propose copy.
 - Ideally, the PR body also contains a small summary of the change. For small changes, the PR title may be sufficient.
 - Each PR should ideally do one conceptual thing. For example, if a PR does a refactoring as well as introducing a new feature, push back and suggest the refactoring be done in a separate PR. This makes things easier for the reviewer, as refactoring changes can often be far-reaching, yet quick to review.
-- If the nature of the change seems to have a visual component (which is often the case for changes to `codex-rs/tui`), recommend including a screenshot or video to demonstrate the change, if appropriate.
-- 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.
-- Encourage the use of small enums or the newtype pattern in Rust if it helps readability without adding significant cognitive load or lines of code.
-- Be wary of large files and offer suggestions for how to break things into more reasonably-sized files.
-- When modifying a `Cargo.toml` file, make sure that dependency lists stay alphabetically sorted. Also consider whether a new dependency is added to the appropriate place (e.g., `[dependencies]` versus `[dev-dependencies]`)
-- If you see opportunities for the changes in a diff to use more idiomatic Rust, please make specific recommendations. For example, favor the use of expressions over `return`.
 - When introducing new code, be on the lookout for code that duplicates existing code. When found, propose a way to refactor the existing code such that it should be reused.
+
+## 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.
 - 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.
+
+## Assertions in Tests
+
+Assert the equality of the entire objects instead of doing "piecemeal comparisons," performing `assert_eq!()` on individual fields.
+
+Note that unit tests also function as "executable documentation." As shown in the following example, "piecemeal comparisons" are often more verbose, provide less coverage, and are not as useful as executable documentation.
+
+For example, suppose you have the following enum:
+
+```rust
+#[derive(Debug, PartialEq)]
+enum Message {
+    Request {
+        id: String,
+        method: String,
+        params: Option<serde_json::Value>,
+    },
+    Notification {
+        method: String,
+        params: Option<serde_json::Value>,
+    },
+}
+```
+
+This is an example of a _piecemeal_ comparison:
+
+```rust
+// BAD: Piecemeal Comparison
+
+#[test]
+fn test_get_latest_messages() {
+    let messages = get_latest_messages();
+    assert_eq!(messages.len(), 2);
+
+    let m0 = &messages[0];
+    match m0 {
+        Message::Request { id, method, params } => {
+            assert_eq!(id, "123");
+            assert_eq!(method, "subscribe");
+            assert_eq!(
+                *params,
+                Some(json!({
+                    "conversation_id": "x42z86"
+                }))
+            )
+        }
+        Message::Notification { .. } => {
+            panic!("expected Request");
+        }
+    }
+
+    let m1 = &messages[1];
+    match m1 {
+        Message::Request { .. } => {
+            panic!("expected Notification");
+        }
+        Message::Notification { method, params } => {
+            assert_eq!(method, "log");
+            assert_eq!(
+                *params,
+                Some(json!({
+                    "level": "info",
+                    "message": "subscribed"
+                }))
+            )
+        }
+    }
+}
+```
+
+This is a _deep_ comparison:
+
+```rust
+// GOOD: Verify the entire structure with a single assert_eq!().
+
+use pretty_assertions::assert_eq;
+
+#[test]
+fn test_get_latest_messages() {
+    let messages = get_latest_messages();
+
+    assert_eq!(
+        vec![
+            Message::Request {
+                id: "123".to_string(),
+                method: "subscribe".to_string(),
+                params: Some(json!({
+                    "conversation_id": "x42z86"
+                })),
+            },
+            Message::Notification {
+                method: "log".to_string(),
+                params: Some(json!({
+                    "level": "info",
+                    "message": "subscribed"
+                })),
+            },
+        ],
+        messages,
+    );
+}
+```
+
+## More Tactical Rust Things To Look Out For
+
+- Do not use `unsafe` (unless you have a really, really good reason like using an operating system API directly and no safe wrapper exists). For example, there are cases where it is tempting to use `unsafe` in order to use `std::env::set_var()`, but this indeed `unsafe` and has led to race conditions on multiple occasions. (When this happens, find a mechanism other than environment variables to use for configuration.)
+- Encourage the use of small enums or the newtype pattern in Rust if it helps readability without adding significant cognitive load or lines of code.
+- If you see opportunities for the changes in a diff to use more idiomatic Rust, please make specific recommendations. For example, favor the use of expressions over `return`.
+- When modifying a `Cargo.toml` file, make sure that dependency lists stay alphabetically sorted. Also consider whether a new dependency is added to the appropriate place (e.g., `[dependencies]` versus `[dev-dependencies]`)
+
+## Pull Request Body
+
+- If the nature of the change seems to have a visual component (which is often the case for changes to `codex-rs/tui`), recommend including a screenshot or video to demonstrate the change, if appropriate.
 - References to existing GitHub issues and PRs are encouraged, where appropriate, though you likely do not have network access, so may not be able to help here.
 
+# PR Information
+
 {CODEX_ACTION_GITHUB_EVENT_PATH} contains the JSON that triggered this GitHub workflow. It contains the `base` and `head` refs that define this PR. Both refs are available locally.

.github/workflows/rust-release.yml

@@ -181,9 +181,9 @@ jobs:
           name: ${{ steps.release_name.outputs.name }}
           tag_name: ${{ github.ref_name }}
           files: dist/**
-          # For now, tag releases as "prerelease" because we are not claiming
-          # the Rust CLI is stable yet.
-          prerelease: true
+          # Mark as prerelease only when the version has a suffix after x.y.z
+          # (e.g. -alpha, -beta). Otherwise publish a normal release.
+          prerelease: ${{ contains(steps.release_name.outputs.name, '-') }}
 
       - uses: facebook/dotslash-publish-release@v2
         env:

README.md

@@ -1,11 +1,12 @@
 <h1 align="center">OpenAI Codex CLI</h1>
-<p align="center">Lightweight coding agent that runs in your terminal</p>
 
 <p align="center"><code>npm i -g @openai/codex</code><br />or <code>brew install codex</code></p>
 
-This is the home of the **Codex CLI**, which is a coding agent from OpenAI that runs locally on your computer. If you are looking for the _cloud-based agent_ from OpenAI, **Codex [Web]**, see <https://chatgpt.com/codex>.
+<p align="center"><strong>Codex CLI</strong> is a coding agent from OpenAI that runs locally on your computer.</br>If you are looking for the <em>cloud-based agent</em> from OpenAI, <strong>Codex Web</strong>, see <a href="https://chatgpt.com/codex">chatgpt.com/codex</a>.</p>
 
-<!-- ![Codex demo GIF using: codex "explain this codebase to me"](./.github/demo.gif) -->
+<p align="center">
+  <img src="./.github/codex-cli-splash.png" alt="Codex CLI splash" width="50%" />
+  </p>
 
 ---
 
@@ -14,21 +15,28 @@ This is the home of the **Codex CLI**, which is a coding agent from OpenAI that
 
 <!-- Begin ToC -->
 
-- [Experimental technology disclaimer](#experimental-technology-disclaimer)
 - [Quickstart](#quickstart)
-  - [OpenAI API Users](#openai-api-users)
-  - [OpenAI Plus/Pro Users](#openai-pluspro-users)
-- [Why Codex?](#why-codex)
-- [Security model & permissions](#security-model--permissions)
+  - [Installing and running Codex CLI](#installing-and-running-codex-cli)
+  - [Updating](#updating)
+  - [Using Codex with your ChatGPT plan](#using-codex-with-your-chatgpt-plan)
+  - [Usage-based billing alternative: Use an OpenAI API key](#usage-based-billing-alternative-use-an-openai-api-key)
+  - [Choosing Codex's level of autonomy](#choosing-codexs-level-of-autonomy)
+    - [**1. Read/write**](#1-readwrite)
+    - [**2. Read-only**](#2-read-only)
+    - [**3. Advanced configuration**](#3-advanced-configuration)
+    - [Can I run without ANY approvals?](#can-i-run-without-any-approvals)
+    - [Fine-tuning in `config.toml`](#fine-tuning-in-configtoml)
+  - [Example prompts](#example-prompts)
+- [Running with a prompt as input](#running-with-a-prompt-as-input)
+- [Using Open Source Models](#using-open-source-models)
   - [Platform sandboxing details](#platform-sandboxing-details)
+- [Experimental technology disclaimer](#experimental-technology-disclaimer)
 - [System requirements](#system-requirements)
 - [CLI reference](#cli-reference)
 - [Memory & project docs](#memory--project-docs)
 - [Non-interactive / CI mode](#non-interactive--ci-mode)
 - [Model Context Protocol (MCP)](#model-context-protocol-mcp)
 - [Tracing / verbose logging](#tracing--verbose-logging)
-- [Recipes](#recipes)
-- [Installation](#installation)
   - [DotSlash](#dotslash)
 - [Configuration](#configuration)
 - [FAQ](#faq)
@@ -53,55 +61,166 @@ This is the home of the **Codex CLI**, which is a coding agent from OpenAI that
 
 ---
 
-## Experimental technology disclaimer
-
-Codex CLI is an experimental project under active development. It is not yet stable, may contain bugs, incomplete features, or undergo breaking changes. We're building it in the open with the community and welcome:
-
-- Bug reports
-- Feature requests
-- Pull requests
-- Good vibes
-
-Help us improve by filing issues or submitting PRs (see the section below for how to contribute)!
-
 ## Quickstart
 
+### Installing and running Codex CLI
+
 Install globally with your preferred package manager:
 
 ```shell
 npm install -g @openai/codex  # Alternatively: `brew install codex`
 ```
 
-Or go to the [latest GitHub Release](https://github.com/openai/codex/releases/latest) and download the appropriate binary for your platform.
+Then simply run `codex` to get started:
 
-### OpenAI API Users
+```shell
+codex
+```
 
-Next, set your OpenAI API key as an environment variable:
+### Updating
+
+Upgrade an existing installation to the latest release:
+
+```shell
+codex update
+```
+
+The command checks for a newer version and will attempt to upgrade automatically if the CLI was installed via npm or Homebrew.
+
+<details>
+<summary>You can also go to the <a href="https://github.com/openai/codex/releases/latest">latest GitHub Release</a> and download the appropriate binary for your platform.</summary>
+
+Each GitHub Release contains many executables, but in practice, you likely want one of these:
+
+- macOS
+  - Apple Silicon/arm64: `codex-aarch64-apple-darwin.tar.gz`
+  - x86_64 (older Mac hardware): `codex-x86_64-apple-darwin.tar.gz`
+- Linux
+  - x86_64: `codex-x86_64-unknown-linux-musl.tar.gz`
+  - arm64: `codex-aarch64-unknown-linux-musl.tar.gz`
+
+Each archive contains a single entry with the platform baked into the name (e.g., `codex-x86_64-unknown-linux-musl`), so you likely want to rename it to `codex` after extracting it.
+
+</details>
+
+### Using Codex with your ChatGPT plan
+
+<p align="center">
+  <img src="./.github/codex-cli-login.png" alt="Codex CLI login" width="50%" />
+  </p>
+
+After you run `codex` select Sign in with ChatGPT. You'll need a Plus, Pro, or Team ChatGPT account, and will get access to our latest models, including `gpt-5`, at no extra cost to your plan. (Enterprise is coming soon.)
+
+> Important: If you've used the Codex CLI before, you'll need to follow these steps to migrate from usage-based billing with your API key:
+>
+> 1. Update the CLI with `codex update` and ensure `codex --version` is greater than 0.13
+> 2. Ensure that there is no `OPENAI_API_KEY` environment variable set. (Check that `env | grep 'OPENAI_API_KEY'` returns empty)
+> 3. Run `codex login` again
+
+If you encounter problems with the login flow, please comment on [this issue](https://github.com/openai/codex/issues/1243).
+
+### Usage-based billing alternative: Use an OpenAI API key
+
+If you prefer to pay-as-you-go, you can still authenticate with your OpenAI API key by setting it as an environment variable:
 
 ```shell
 export OPENAI_API_KEY="your-api-key-here"
 ```
 
-> [!NOTE]
-> This command sets the key only for your current terminal session. You can add the `export` line to your shell's configuration file (e.g., `~/.zshrc`), but we recommend setting it for the session.
+> Note: This command only sets the key for your current terminal session, which we recommend. To set it for all future sessions, you can also add the `export` line to your shell's configuration file (e.g., `~/.zshrc`).
 
-### OpenAI Plus/Pro Users
+### Choosing Codex's level of autonomy
 
-If you have a paid OpenAI account, run the following to start the login process:
+We always recommend running Codex in its default sandbox that gives you strong guardrails around what the agent can do. The default sandbox prevents it from editing files outside its workspace, or from accessing the network.
 
-```
-codex login
+When you launch Codex in a new folder, it detects whether the folder is version controlled and recommends one of two levels of autonomy:
+
+#### **1. Read/write**
+
+- Codex can run commands and write files in the workspace without approval.
+- To write files in other folders, access network, update git or perform other actions protected by the sandbox, Codex will need your permission.
+- By default, the workspace includes the current directory, as well as temporary directories like `/tmp`. You can see what directories are in the workspace with the `/status` command. See the docs for how to customize this behavior.
+- Advanced: You can manually specify this configuration by running `codex --sandbox workspace-write --ask-for-approval on-request`
+- This is the recommended default for version-controlled folders.
+
+#### **2. Read-only**
+
+- Codex can run read-only commands without approval.
+- To edit files, access network, or perform other actions protected by the sandbox, Codex will need your permission.
+- Advanced: You can manually specify this configuration by running `codex --sandbox read-only --ask-for-approval on-request`
+- This is the recommended default non-version-controlled folders.
+
+#### **3. Advanced configuration**
+
+Codex gives you fine-grained control over the sandbox with the `--sandbox` option, and over when it requests approval with the `--ask-for-approval` option. Run `codex help` for more on these options.
+
+#### Can I run without ANY approvals?
+
+Yes, run codex non-interactively with `--ask-for-approval never`. This option works with all `--sandbox` options, so you still have full control over Codex's level of autonomy. It will make its best attempt with whatever contrainsts you provide. For example:
+
+- Use `codex --ask-for-approval never --sandbox read-only` when you are running many agents to answer questions in parallel in the same workspace.
+- Use `codex --ask-for-approval never --sandbox workspace-write` when you want the agent to non-interactively take time to produce the best outcome, with strong guardrails around its behavior.
+- Use `codex --ask-for-approval never --sandbox danger-full-access` to dangerously give the agent full autonomy. Because this disables important safety mechanisms, we recommend against using this unless running Codex in an isolated environment.
+
+#### Fine-tuning in `config.toml`
+
+```toml
+# approval mode
+approval_policy = "untrusted"
+sandbox_mode    = "read-only"
+
+# full-auto mode
+approval_policy = "on-request"
+sandbox_mode    = "workspace-write"
+
+# Optional: allow network in workspace-write mode
+[sandbox_workspace_write]
+network_access = true
 ```
 
-If you complete the process successfully, you should have a `~/.codex/auth.json` file that contains the credentials that Codex will use.
+You can also save presets as **profiles**:
 
-To verify whether you are currently logged in, run:
+```toml
+[profiles.full_auto]
+approval_policy = "on-request"
+sandbox_mode    = "workspace-write"
 
-```
-codex login status
+[profiles.readonly_quiet]
+approval_policy = "never"
+sandbox_mode    = "read-only"
 ```
 
-If you encounter problems with the login flow, please comment on <https://github.com/openai/codex/issues/1243>.
+### Example prompts
+
+Below are a few bite-size examples you can copy-paste. Replace the text in quotes with your own task. See the [prompting guide](https://github.com/openai/codex/blob/main/codex-cli/examples/prompting_guide.md) for more tips and usage patterns.
+
+| ✨  | What you type                                                                   | What happens                                                               |
+| --- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| 1   | `codex "Refactor the Dashboard component to React Hooks"`                       | Codex rewrites the class component, runs `npm test`, and shows the diff.   |
+| 2   | `codex "Generate SQL migrations for adding a users table"`                      | Infers your ORM, creates migration files, and runs them in a sandboxed DB. |
+| 3   | `codex "Write unit tests for utils/date.ts"`                                    | Generates tests, executes them, and iterates until they pass.              |
+| 4   | `codex "Bulk-rename *.jpeg -> *.jpg with git mv"`                               | Safely renames files and updates imports/usages.                           |
+| 5   | `codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"`                      | Outputs a step-by-step human explanation.                                  |
+| 6   | `codex "Carefully review this repo, and propose 3 high impact well-scoped PRs"` | Suggests impactful PRs in the current codebase.                            |
+| 7   | `codex "Look for vulnerabilities and create a security review report"`          | Finds and explains security bugs.                                          |
+
+## Running with a prompt as input
+
+You can also run Codex CLI with a prompt as input:
+
+```shell
+codex "explain this codebase to me"
+```
+
+```shell
+codex --full-auto "create the fanciest todo-list app"
+```
+
+That's it - Codex will scaffold a file, run it inside a sandbox, install any
+missing dependencies, and show you the live result. Approve the changes and
+they'll be committed to your working directory.
+
+## Using Open Source Models
 
 <details>
 <summary><strong>Use <code>--profile</code> to use other models</strong></summary>
@@ -162,68 +281,40 @@ model = "mistral"
 This way, you can specify one command-line argument (.e.g., `--profile o3`, `--profile mistral`) to override multiple settings together.
 
 </details>
-<br />
 
-Run interactively:
+Codex can run fully locally against an OpenAI-compatible OSS host (like Ollama) using the `--oss` flag:
 
-```shell
-codex
+- Interactive UI:
+  - codex --oss
+- Non-interactive (programmatic) mode:
+  - echo "Refactor utils" | codex exec --oss
+
+Model selection when using `--oss`:
+
+- If you omit `-m/--model`, Codex defaults to -m gpt-oss:20b and will verify it exists locally (downloading if needed).
+- To pick a different size, pass one of:
+  - -m "gpt-oss:20b"
+  - -m "gpt-oss:120b"
+
+Point Codex at your own OSS host:
+
+- By default, `--oss` talks to http://localhost:11434/v1.
+- To use a different host, set one of these environment variables before running Codex:
+  - CODEX_OSS_BASE_URL, for example:
+    - CODEX_OSS_BASE_URL="http://my-ollama.example.com:11434/v1" codex --oss -m gpt-oss:20b
+  - or CODEX_OSS_PORT (when the host is localhost):
+    - CODEX_OSS_PORT=11434 codex --oss
+
+Advanced: you can persist this in your config instead of environment variables by overriding the built-in `oss` provider in `~/.codex/config.toml`:
+
+```toml
+[model_providers.oss]
+name = "Open Source"
+base_url = "http://my-ollama.example.com:11434/v1"
 ```
 
-Or, run with a prompt as input (and optionally in `Full Auto` mode):
-
-```shell
-codex "explain this codebase to me"
-```
-
-```shell
-codex --full-auto "create the fanciest todo-list app"
-```
-
-That's it - Codex will scaffold a file, run it inside a sandbox, install any
-missing dependencies, and show you the live result. Approve the changes and
-they'll be committed to your working directory.
-
 ---
 
-## Why Codex?
-
-Codex CLI is built for developers who already **live in the terminal** and want
-ChatGPT-level reasoning **plus** the power to actually run code, manipulate
-files, and iterate - all under version control. In short, it's _chat-driven
-development_ that understands and executes your repo.
-
-- **Zero setup** - bring your OpenAI API key and it just works!
-- **Full auto-approval, while safe + secure** by running network-disabled and directory-sandboxed
-- **Multimodal** - pass in screenshots or diagrams to implement features ✨
-
-And it's **fully open-source** so you can see and contribute to how it develops!
-
----
-
-## Security model & permissions
-
-Codex lets you decide _how much autonomy_ you want to grant the agent. The following options can be configured independently:
-
-- [`approval_policy`](./codex-rs/config.md#approval_policy) determines when you should be prompted to approve whether Codex can execute a command
-- [`sandbox`](./codex-rs/config.md#sandbox) determines the _sandbox policy_ that Codex uses to execute untrusted commands
-
-By default, Codex runs with `--ask-for-approval untrusted` and `--sandbox read-only`, which means that:
-
-- The user is prompted to approve every command not on the set of "trusted" commands built into Codex (`cat`, `ls`, etc.)
-- Approved commands are run outside of a sandbox because user approval implies "trust," in this case.
-
-Running Codex with the `--full-auto` convenience flag changes the configuration to `--ask-for-approval on-failure` and `--sandbox workspace-write`, which means that:
-
-- Codex does not initially ask for user approval before running an individual command.
-- Though when it runs a command, it is run under a sandbox in which:
-  - It can read any file on the system.
-  - It can only write files under the current directory (or the directory specified via `--cd`).
-  - Network requests are completely disabled.
-- Only if the command exits with a non-zero exit code will it ask the user for approval. If granted, it will re-attempt the command outside of the sandbox. (A common case is when Codex cannot `npm install` a dependency because that requires network access.)
-
-Again, these two options can be configured independently. For example, if you want Codex to perform an "exploration" where you are happy for it to read anything it wants but you never want to be prompted, you could run Codex with `--ask-for-approval never` and `--sandbox read-only`.
-
 ### Platform sandboxing details
 
 The mechanism Codex uses to implement the sandbox policy depends on your OS:
@@ -235,6 +326,19 @@ Note that when running Linux in a containerized environment such as Docker, sand
 
 ---
 
+## Experimental technology disclaimer
+
+Codex CLI is an experimental project under active development. It is not yet stable, may contain bugs, incomplete features, or undergo breaking changes. We're building it in the open with the community and welcome:
+
+- Bug reports
+- Feature requests
+- Pull requests
+- Good vibes
+
+Help us improve by filing issues or submitting PRs (see the section below for how to contribute)!
+
+---
+
 ## System requirements
 
 | Requirement                 | Details                                                         |
@@ -247,11 +351,12 @@ Note that when running Linux in a containerized environment such as Docker, sand
 
 ## CLI reference
 
-| Command            | Purpose                            | Example                         |
-| ------------------ | ---------------------------------- | ------------------------------- |
-| `codex`            | Interactive TUI                    | `codex`                         |
-| `codex "..."`      | Initial prompt for interactive TUI | `codex "fix lint errors"`       |
-| `codex exec "..."` | Non-interactive "automation mode"  | `codex exec "explain utils.ts"` |
+| Command            | Purpose                               | Example                         |
+| ------------------ | ------------------------------------- | ------------------------------- |
+| `codex`            | Interactive TUI                       | `codex`                         |
+| `codex "..."`      | Initial prompt for interactive TUI    | `codex "fix lint errors"`       |
+| `codex exec "..."` | Non-interactive "automation mode"     | `codex exec "explain utils.ts"` |
+| `codex update`     | Check for updates and upgrade the CLI | `codex update`                  |
 
 Key flags: `--model/-m`, `--ask-for-approval/-a`.
 
@@ -310,52 +415,6 @@ See the Rust documentation on [`RUST_LOG`](https://docs.rs/env_logger/latest/env
 
 ---
 
-## Recipes
-
-Below are a few bite-size examples you can copy-paste. Replace the text in quotes with your own task. See the [prompting guide](https://github.com/openai/codex/blob/main/codex-cli/examples/prompting_guide.md) for more tips and usage patterns.
-
-| ✨  | What you type                                                                   | What happens                                                               |
-| --- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| 1   | `codex "Refactor the Dashboard component to React Hooks"`                       | Codex rewrites the class component, runs `npm test`, and shows the diff.   |
-| 2   | `codex "Generate SQL migrations for adding a users table"`                      | Infers your ORM, creates migration files, and runs them in a sandboxed DB. |
-| 3   | `codex "Write unit tests for utils/date.ts"`                                    | Generates tests, executes them, and iterates until they pass.              |
-| 4   | `codex "Bulk-rename *.jpeg -> *.jpg with git mv"`                               | Safely renames files and updates imports/usages.                           |
-| 5   | `codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$"`                      | Outputs a step-by-step human explanation.                                  |
-| 6   | `codex "Carefully review this repo, and propose 3 high impact well-scoped PRs"` | Suggests impactful PRs in the current codebase.                            |
-| 7   | `codex "Look for vulnerabilities and create a security review report"`          | Finds and explains security bugs.                                          |
-
----
-
-## Installation
-
-<details open>
-<summary><strong>Install Codex CLI using your preferred package manager.</strong></summary>
-
-From `brew` (recommended, downloads only the binary for your platform):
-
-```bash
-brew install codex
-```
-
-From `npm` (generally more readily available, but downloads binaries for all supported platforms):
-
-```bash
-npm i -g @openai/codex
-```
-
-Or go to the [latest GitHub Release](https://github.com/openai/codex/releases/latest) and download the appropriate binary for your platform.
-
-Admittedly, each GitHub Release contains many executables, but in practice, you likely want one of these:
-
-- macOS
-  - Apple Silicon/arm64: `codex-aarch64-apple-darwin.tar.gz`
-  - x86_64 (older Mac hardware): `codex-x86_64-apple-darwin.tar.gz`
-- Linux
-  - x86_64: `codex-x86_64-unknown-linux-musl.tar.gz`
-  - arm64: `codex-aarch64-unknown-linux-musl.tar.gz`
-
-Each archive contains a single entry with the platform baked into the name (e.g., `codex-x86_64-unknown-linux-musl`), so you likely want to rename it to `codex` after extracting it.
-
 ### DotSlash
 
 The GitHub Release also contains a [DotSlash](https://dotslash-cli.com/) file for the Codex CLI named `codex`. Using a DotSlash file makes it possible to make a lightweight commit to source control to ensure all contributors use the same version of an executable, regardless of what platform they use for development.

codex-cli/src/components/chat/terminal-chat-input.tsx

@@ -854,7 +854,7 @@ export default function TerminalChatInput({
           />
         ) : (
           <Text dimColor>
-            ctrl+c to exit | "/" to see commands | enter to send
+            Ctrl+C to exit | "/" to see commands | Enter to send
             {contextLeftPercent > 25 && (
               <>
                 {" — "}

codex-cli/src/components/help-overlay.tsx

@@ -96,7 +96,7 @@ export default function HelpOverlay({
       </Box>
 
       <Box paddingX={1}>
-        <Text dimColor>esc or q to close</Text>
+        <Text dimColor>Esc or q to close</Text>
       </Box>
     </Box>
   );

codex-cli/src/utils/get-api-key-components.tsx

@@ -68,7 +68,7 @@ export function WaitingForAuth(): JSX.Element {
       <Spinner type="ball" />
       <Text>
         {" "}
-        Waiting for authentication… <Text dimColor>ctrl + c to quit</Text>
+        Waiting for authentication… <Text dimColor>Ctrl + C to quit</Text>
       </Text>
     </Box>
   );

codex-rs/Cargo.lock

@@ -658,10 +658,16 @@ dependencies = [
 name = "codex-common"
 version = "0.0.0"
 dependencies = [
+ "anyhow",
+ "chrono",
  "clap",
  "codex-core",
+ "reqwest",
  "serde",
+ "serde_json",
+ "tokio",
  "toml 0.9.4",
+ "tracing",
 ]
 
 [[package]]
@@ -708,6 +714,7 @@ dependencies = [
  "tokio-test",
  "tokio-util",
  "toml 0.9.4",
+ "toml_edit 0.23.3",
  "tracing",
  "tree-sitter",
  "tree-sitter-bash",
@@ -729,6 +736,7 @@ dependencies = [
  "codex-arg0",
  "codex-common",
  "codex-core",
+ "codex-ollama",
  "owo-colors",
  "predicates",
  "serde_json",
@@ -791,11 +799,14 @@ dependencies = [
 name = "codex-login"
 version = "0.0.0"
 dependencies = [
+ "base64 0.22.1",
  "chrono",
+ "pretty_assertions",
  "reqwest",
  "serde",
  "serde_json",
  "tempfile",
+ "thiserror 2.0.12",
  "tokio",
 ]
 
@@ -831,7 +842,6 @@ dependencies = [
  "tempfile",
  "tokio",
  "tokio-test",
- "tokio-util",
  "toml 0.9.4",
  "tracing",
  "tracing-subscriber",
@@ -839,6 +849,23 @@ dependencies = [
  "wiremock",
 ]
 
+[[package]]
+name = "codex-ollama"
+version = "0.0.0"
+dependencies = [
+ "async-stream",
+ "bytes",
+ "codex-core",
+ "futures",
+ "reqwest",
+ "serde_json",
+ "tempfile",
+ "tokio",
+ "toml 0.9.4",
+ "tracing",
+ "wiremock",
+]
+
 [[package]]
 name = "codex-tui"
 version = "0.0.0"
@@ -853,8 +880,10 @@ dependencies = [
  "codex-core",
  "codex-file-search",
  "codex-login",
+ "codex-ollama",
  "color-eyre",
  "crossterm",
+ "diffy",
  "image",
  "insta",
  "lazy_static",
@@ -865,7 +894,6 @@ dependencies = [
  "ratatui",
  "ratatui-image",
  "regex-lite",
- "reqwest",
  "serde",
  "serde_json",
  "shlex",
@@ -1237,6 +1265,15 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
+[[package]]
+name = "diffy"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b545b8c50194bdd008283985ab0b31dba153cfd5b3066a92770634fbc0d7d291"
+dependencies = [
+ "nu-ansi-term 0.50.1",
+]
+
 [[package]]
 name = "digest"
 version = "0.10.7"
@@ -1475,7 +1512,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "778e2ac28f6c47af28e4907f13ffd1e1ddbd400980a9abd7c8df189bf578a5ad"
 dependencies = [
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -1555,7 +1592,7 @@ checksum = "0ce92ff622d6dadf7349484f42c93271a0d49b7cc4d466a936405bacbe10aa78"
 dependencies = [
  "cfg-if",
  "rustix 1.0.8",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -2338,7 +2375,7 @@ checksum = "e04d7f318608d35d4b61ddd75cbdaee86b023ebe2bd5a66ee0915f0bf93095a9"
 dependencies = [
  "hermit-abi",
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -2814,6 +2851,15 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "nu-ansi-term"
+version = "0.50.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4a28e057d01f97e61255210fcff094d74ed0466038633e95017f5beb68e4399"
+dependencies = [
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "nucleo-matcher"
 version = "0.3.1"
@@ -3233,7 +3279,7 @@ version = "3.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "edce586971a4dfaa28950c6f18ed55e0406c1ab88bbce2c6f6293a7aaba73d35"
 dependencies = [
- "toml_edit",
+ "toml_edit 0.22.27",
 ]
 
 [[package]]
@@ -3722,7 +3768,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys 0.4.15",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -3735,7 +3781,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys 0.9.4",
- "windows-sys 0.52.0",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -4501,7 +4547,7 @@ dependencies = [
  "getrandom 0.3.3",
  "once_cell",
  "rustix 1.0.8",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -4760,7 +4806,7 @@ dependencies = [
  "serde",
  "serde_spanned 0.6.9",
  "toml_datetime 0.6.11",
- "toml_edit",
+ "toml_edit 0.22.27",
 ]
 
 [[package]]
@@ -4810,10 +4856,23 @@ dependencies = [
 ]
 
 [[package]]
-name = "toml_parser"
-version = "1.0.1"
+name = "toml_edit"
+version = "0.23.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97200572db069e74c512a14117b296ba0a80a30123fbbb5aa1f4a348f639ca30"
+checksum = "17d3b47e6b7a040216ae5302712c94d1cf88c95b47efa80e2c59ce96c878267e"
+dependencies = [
+ "indexmap 2.10.0",
+ "toml_datetime 0.7.0",
+ "toml_parser",
+ "toml_writer",
+ "winnow",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b551886f449aa90d4fe2bdaa9f4a2577ad2dde302c61ecf262d80b116db95c10"
 dependencies = [
  "winnow",
 ]
@@ -4942,7 +5001,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e8189decb5ac0fa7bc8b96b7cb9b2701d60d48805aca84a238004d665fcc4008"
 dependencies = [
  "matchers",
- "nu-ansi-term",
+ "nu-ansi-term 0.46.0",
  "once_cell",
  "regex",
  "sharded-slab",
@@ -5360,7 +5419,7 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf221c93e13a30d793f7645a0e7762c55d169dbb0a49671918a2319d289b10bb"
 dependencies = [
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]

codex-rs/Cargo.toml

@@ -14,6 +14,7 @@ members = [
     "mcp-client",
     "mcp-server",
     "mcp-types",
+    "ollama",
     "tui",
 ]
 resolver = "2"

codex-rs/apply-patch/src/lib.rs

@@ -42,6 +42,15 @@ impl From<std::io::Error> for ApplyPatchError {
     }
 }
 
+impl From<&std::io::Error> for ApplyPatchError {
+    fn from(err: &std::io::Error) -> Self {
+        ApplyPatchError::IoError(IoError {
+            context: "I/O error".to_string(),
+            source: std::io::Error::new(err.kind(), err.to_string()),
+        })
+    }
+}
+
 #[derive(Debug, Error)]
 #[error("{context}: {source}")]
 pub struct IoError {
@@ -366,13 +375,21 @@ pub fn apply_hunks(
     match apply_hunks_to_files(hunks) {
         Ok(affected) => {
             print_summary(&affected, stdout).map_err(ApplyPatchError::from)?;
+            Ok(())
         }
         Err(err) => {
-            writeln!(stderr, "{err:?}").map_err(ApplyPatchError::from)?;
+            let msg = err.to_string();
+            writeln!(stderr, "{msg}").map_err(ApplyPatchError::from)?;
+            if let Some(io) = err.downcast_ref::<std::io::Error>() {
+                Err(ApplyPatchError::from(io))
+            } else {
+                Err(ApplyPatchError::IoError(IoError {
+                    context: msg,
+                    source: std::io::Error::other(err),
+                }))
+            }
         }
     }
-
-    Ok(())
 }
 
 /// Applies each parsed patch hunk to the filesystem.
@@ -1238,4 +1255,24 @@ g
             })
         );
     }
+
+    #[test]
+    fn test_apply_patch_fails_on_write_error() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("readonly.txt");
+        fs::write(&path, "before\n").unwrap();
+        let mut perms = fs::metadata(&path).unwrap().permissions();
+        perms.set_readonly(true);
+        fs::set_permissions(&path, perms).unwrap();
+
+        let patch = wrap_patch(&format!(
+            "*** Update File: {}\n@@\n-before\n+after\n*** End Patch",
+            path.display()
+        ));
+
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let result = apply_patch(&patch, &mut stdout, &mut stderr);
+        assert!(result.is_err());
+    }
 }

codex-rs/chatgpt/src/chatgpt_token.rs

@@ -1,3 +1,4 @@
+use codex_login::CodexAuth;
 use std::path::Path;
 use std::sync::LazyLock;
 use std::sync::RwLock;
@@ -18,7 +19,7 @@ pub fn set_chatgpt_token_data(value: TokenData) {
 
 /// Initialize the ChatGPT token from auth.json file
 pub async fn init_chatgpt_token_from_auth(codex_home: &Path) -> std::io::Result<()> {
-    let auth = codex_login::load_auth(codex_home, true)?;
+    let auth = CodexAuth::from_codex_home(codex_home)?;
     if let Some(auth) = auth {
         let token_data = auth.get_token_data().await?;
         set_chatgpt_token_data(token_data);

codex-rs/cli/Cargo.toml

@@ -20,7 +20,7 @@ clap = { version = "4", features = ["derive"] }
 clap_complete = "4"
 codex-arg0 = { path = "../arg0" }
 codex-chatgpt = { path = "../chatgpt" }
-codex-common = { path = "../common", features = ["cli"] }
+codex-common = { path = "../common", features = ["cli", "updates"] }
 codex-core = { path = "../core" }
 codex-exec = { path = "../exec" }
 codex-login = { path = "../login" }

codex-rs/cli/src/login.rs

@@ -4,10 +4,11 @@ use codex_common::CliConfigOverrides;
 use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
 use codex_login::AuthMode;
+use codex_login::CodexAuth;
 use codex_login::OPENAI_API_KEY_ENV_VAR;
-use codex_login::load_auth;
 use codex_login::login_with_api_key;
 use codex_login::login_with_chatgpt;
+use codex_login::logout;
 
 pub async fn run_login_with_chatgpt(cli_config_overrides: CliConfigOverrides) -> ! {
     let config = load_config_or_exit(cli_config_overrides);
@@ -46,11 +47,11 @@ pub async fn run_login_with_api_key(
 pub async fn run_login_status(cli_config_overrides: CliConfigOverrides) -> ! {
     let config = load_config_or_exit(cli_config_overrides);
 
-    match load_auth(&config.codex_home, true) {
+    match CodexAuth::from_codex_home(&config.codex_home) {
         Ok(Some(auth)) => match auth.mode {
-            AuthMode::ApiKey => {
-                if let Some(api_key) = auth.api_key.as_deref() {
-                    eprintln!("Logged in using an API key - {}", safe_format_key(api_key));
+            AuthMode::ApiKey => match auth.get_token().await {
+                Ok(api_key) => {
+                    eprintln!("Logged in using an API key - {}", safe_format_key(&api_key));
 
                     if let Ok(env_api_key) = env::var(OPENAI_API_KEY_ENV_VAR) {
                         if env_api_key == api_key {
@@ -59,11 +60,13 @@ pub async fn run_login_status(cli_config_overrides: CliConfigOverrides) -> ! {
                             );
                         }
                     }
-                } else {
-                    eprintln!("Logged in using an API key");
+                    std::process::exit(0);
                 }
-                std::process::exit(0);
-            }
+                Err(e) => {
+                    eprintln!("Unexpected error retrieving API key: {e}");
+                    std::process::exit(1);
+                }
+            },
             AuthMode::ChatGPT => {
                 eprintln!("Logged in using ChatGPT");
                 std::process::exit(0);
@@ -80,6 +83,25 @@ pub async fn run_login_status(cli_config_overrides: CliConfigOverrides) -> ! {
     }
 }
 
+pub async fn run_logout(cli_config_overrides: CliConfigOverrides) -> ! {
+    let config = load_config_or_exit(cli_config_overrides);
+
+    match logout(&config.codex_home) {
+        Ok(true) => {
+            eprintln!("Successfully logged out");
+            std::process::exit(0);
+        }
+        Ok(false) => {
+            eprintln!("Not logged in");
+            std::process::exit(0);
+        }
+        Err(e) => {
+            eprintln!("Error logging out: {e}");
+            std::process::exit(1);
+        }
+    }
+}
+
 fn load_config_or_exit(cli_config_overrides: CliConfigOverrides) -> Config {
     let cli_overrides = match cli_config_overrides.parse_overrides() {
         Ok(v) => v,

codex-rs/cli/src/main.rs

@@ -10,8 +10,15 @@ use codex_cli::SeatbeltCommand;
 use codex_cli::login::run_login_status;
 use codex_cli::login::run_login_with_api_key;
 use codex_cli::login::run_login_with_chatgpt;
+use codex_cli::login::run_logout;
 use codex_cli::proto;
 use codex_common::CliConfigOverrides;
+use codex_common::updates::check_for_update;
+use codex_common::updates::get_upgrade_version;
+#[cfg(not(debug_assertions))]
+use codex_core::config::Config;
+#[cfg(not(debug_assertions))]
+use codex_core::config::ConfigOverrides;
 use codex_exec::Cli as ExecCli;
 use codex_tui::Cli as TuiCli;
 use std::path::PathBuf;
@@ -48,6 +55,9 @@ enum Subcommand {
     /// Manage login.
     Login(LoginCommand),
 
+    /// Remove stored authentication credentials.
+    Logout(LogoutCommand),
+
     /// Experimental: run Codex as an MCP server.
     Mcp,
 
@@ -64,6 +74,9 @@ enum Subcommand {
     /// Apply the latest diff produced by Codex agent as a `git apply` to your local working tree.
     #[clap(visible_alias = "a")]
     Apply(ApplyCommand),
+
+    /// Check for a newer Codex release and upgrade automatically when possible.
+    Update,
 }
 
 #[derive(Debug, Parser)]
@@ -106,6 +119,12 @@ enum LoginSubcommand {
     Status,
 }
 
+#[derive(Debug, Parser)]
+struct LogoutCommand {
+    #[clap(skip)]
+    config_overrides: CliConfigOverrides,
+}
+
 fn main() -> anyhow::Result<()> {
     arg0_dispatch_or_else(|codex_linux_sandbox_exe| async move {
         cli_main(codex_linux_sandbox_exe).await?;
@@ -121,7 +140,9 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
             let mut tui_cli = cli.interactive;
             prepend_config_flags(&mut tui_cli.config_overrides, cli.config_overrides);
             let usage = codex_tui::run_main(tui_cli, codex_linux_sandbox_exe).await?;
-            println!("{}", codex_core::protocol::FinalOutput::from(usage));
+            if !usage.is_zero() {
+                println!("{}", codex_core::protocol::FinalOutput::from(usage));
+            }
         }
         Some(Subcommand::Exec(mut exec_cli)) => {
             prepend_config_flags(&mut exec_cli.config_overrides, cli.config_overrides);
@@ -145,6 +166,10 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
                 }
             }
         }
+        Some(Subcommand::Logout(mut logout_cli)) => {
+            prepend_config_flags(&mut logout_cli.config_overrides, cli.config_overrides);
+            run_logout(logout_cli.config_overrides).await;
+        }
         Some(Subcommand::Proto(mut proto_cli)) => {
             prepend_config_flags(&mut proto_cli.config_overrides, cli.config_overrides);
             proto::run_main(proto_cli).await?;
@@ -174,6 +199,9 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
             prepend_config_flags(&mut apply_cli.config_overrides, cli.config_overrides);
             run_apply_command(apply_cli, None).await?;
         }
+        Some(Subcommand::Update) => {
+            run_update().await?;
+        }
     }
 
     Ok(())
@@ -195,3 +223,88 @@ fn print_completion(cmd: CompletionCommand) {
     let name = "codex";
     generate(cmd.shell, &mut app, name, &mut std::io::stdout());
 }
+
+#[cfg(not(debug_assertions))]
+async fn run_update() -> anyhow::Result<()> {
+    let overrides = ConfigOverrides {
+        model: None,
+        cwd: None,
+        approval_policy: None,
+        sandbox_mode: None,
+        model_provider: None,
+        config_profile: None,
+        codex_linux_sandbox_exe: None,
+        base_instructions: None,
+        include_plan_tool: None,
+        disable_response_storage: None,
+        show_raw_agent_reasoning: None,
+    };
+
+    let config = Config::load_with_cli_overrides(Vec::new(), overrides)?;
+    let version_file = config.codex_home.join("version.json");
+
+    if let Err(e) = check_for_update(&version_file).await {
+        #[allow(clippy::print_stderr)]
+        eprintln!("Failed to check for updates: {e}");
+    }
+
+    let current_version = env!("CARGO_PKG_VERSION");
+    if let Some(latest_version) = get_upgrade_version(&config) {
+        println!("Current version: {current_version}");
+        println!("Latest version:  {latest_version}");
+        let exe = std::env::current_exe()?;
+        let managed_by_npm = std::env::var_os("CODEX_MANAGED_BY_NPM").is_some();
+        if managed_by_npm {
+            println!("Updating via npm...");
+            match Command::new("npm")
+                .args(["install", "-g", "@openai/codex@latest"])
+                .status()
+            {
+                Ok(status) if status.success() => {
+                    println!("Codex updated successfully.");
+                }
+                Ok(status) => {
+                    println!(
+                        "`npm install` exited with status {status}. Run `npm install -g @openai/codex@latest` manually if needed."
+                    );
+                }
+                Err(err) => {
+                    println!(
+                        "Failed to run npm: {err}. Run `npm install -g @openai/codex@latest` manually."
+                    );
+                }
+            }
+        } else if cfg!(target_os = "macos")
+            && (exe.starts_with("/opt/homebrew") || exe.starts_with("/usr/local"))
+        {
+            println!("Updating via Homebrew...");
+            match Command::new("brew").args(["upgrade", "codex"]).status() {
+                Ok(status) if status.success() => {
+                    println!("Codex updated successfully.");
+                }
+                Ok(status) => {
+                    println!(
+                        "`brew upgrade` exited with status {status}. Run `brew upgrade codex` manually if needed."
+                    );
+                }
+                Err(err) => {
+                    println!("Failed to run Homebrew: {err}. Run `brew upgrade codex` manually.");
+                }
+            }
+        } else {
+            println!(
+                "See https://github.com/openai/codex/releases/latest for the latest releases and installation options."
+            );
+        }
+    } else {
+        println!("Codex {current_version} is up to date.");
+    }
+
+    Ok(())
+}
+
+#[cfg(debug_assertions)]
+async fn run_update() -> anyhow::Result<()> {
+    println!("Update checking is disabled in debug builds.");
+    Ok(())
+}

codex-rs/cli/src/proto.rs

@@ -9,7 +9,7 @@ use codex_core::config::Config;
 use codex_core::config::ConfigOverrides;
 use codex_core::protocol::Submission;
 use codex_core::util::notify_on_sigint;
-use codex_login::load_auth;
+use codex_login::CodexAuth;
 use tokio::io::AsyncBufReadExt;
 use tokio::io::BufReader;
 use tracing::error;
@@ -36,7 +36,7 @@ pub async fn run_main(opts: ProtoCli) -> anyhow::Result<()> {
         .map_err(anyhow::Error::msg)?;
 
     let config = Config::load_with_cli_overrides(overrides_vec, ConfigOverrides::default())?;
-    let auth = load_auth(&config.codex_home, true)?;
+    let auth = CodexAuth::from_codex_home(&config.codex_home)?;
     let ctrl_c = notify_on_sigint();
     let CodexSpawnOk { codex, .. } = Codex::spawn(config, auth, ctrl_c.clone()).await?;
     let codex = Arc::new(codex);

codex-rs/common/Cargo.toml

@@ -7,13 +7,20 @@ version = { workspace = true }
 workspace = true
 
 [dependencies]
+anyhow = { version = "1", optional = true }
+chrono = { version = "0.4", features = ["serde"], optional = true }
 clap = { version = "4", features = ["derive", "wrap_help"], optional = true }
 codex-core = { path = "../core" }
-serde = { version = "1", optional = true }
+reqwest = { version = "0.12", features = ["json"], optional = true }
+serde = { version = "1", features = ["derive"], optional = true }
+serde_json = { version = "1", optional = true }
+tokio = { version = "1", features = ["fs"], optional = true }
 toml = { version = "0.9", optional = true }
+tracing = "0.1.41"
 
 [features]
 # Separate feature so that `clap` is not a mandatory dependency.
 cli = ["clap", "serde", "toml"]
 elapsed = []
 sandbox_summary = []
+updates = ["anyhow", "chrono", "reqwest", "serde", "serde_json", "tokio"]

codex-rs/common/src/approval_mode_cli_arg.rs

@@ -18,6 +18,9 @@ pub enum ApprovalModeCliArg {
     /// will escalate to the user to ask for un-sandboxed execution.
     OnFailure,
 
+    /// The model decides when to ask the user for approval.
+    OnRequest,
+
     /// Never ask for user approval
     /// Execution failures are immediately returned to the model.
     Never,
@@ -28,6 +31,7 @@ impl From<ApprovalModeCliArg> for AskForApproval {
         match value {
             ApprovalModeCliArg::Untrusted => AskForApproval::UnlessTrusted,
             ApprovalModeCliArg::OnFailure => AskForApproval::OnFailure,
+            ApprovalModeCliArg::OnRequest => AskForApproval::OnRequest,
             ApprovalModeCliArg::Never => AskForApproval::Never,
         }
     }

codex-rs/common/src/config_summary.rs

@@ -0,0 +1,29 @@
+use codex_core::WireApi;
+use codex_core::config::Config;
+
+use crate::sandbox_summary::summarize_sandbox_policy;
+
+/// Build a list of key/value pairs summarizing the effective configuration.
+pub fn create_config_summary_entries(config: &Config) -> Vec<(&'static str, String)> {
+    let mut entries = vec![
+        ("workdir", config.cwd.display().to_string()),
+        ("model", config.model.clone()),
+        ("provider", config.model_provider_id.clone()),
+        ("approval", config.approval_policy.to_string()),
+        ("sandbox", summarize_sandbox_policy(&config.sandbox_policy)),
+    ];
+    if config.model_provider.wire_api == WireApi::Responses
+        && config.model_family.supports_reasoning_summaries
+    {
+        entries.push((
+            "reasoning effort",
+            config.model_reasoning_effort.to_string(),
+        ));
+        entries.push((
+            "reasoning summaries",
+            config.model_reasoning_summary.to_string(),
+        ));
+    }
+
+    entries
+}

codex-rs/common/src/fuzzy_match.rs

@@ -0,0 +1,177 @@
+/// Simple case-insensitive subsequence matcher used for fuzzy filtering.
+///
+/// Returns the indices (character positions) of the matched characters in the
+/// ORIGINAL `haystack` string and a score where smaller is better.
+///
+/// Unicode correctness: we perform the match on a lowercased copy of the
+/// haystack and needle but maintain a mapping from each character in the
+/// lowercased haystack back to the original character index in `haystack`.
+/// This ensures the returned indices can be safely used with
+/// `str::chars().enumerate()` consumers for highlighting, even when
+/// lowercasing expands certain characters (e.g., ß → ss, İ → i̇).
+pub fn fuzzy_match(haystack: &str, needle: &str) -> Option<(Vec<usize>, i32)> {
+    if needle.is_empty() {
+        return Some((Vec::new(), i32::MAX));
+    }
+
+    let mut lowered_chars: Vec<char> = Vec::new();
+    let mut lowered_to_orig_char_idx: Vec<usize> = Vec::new();
+    for (orig_idx, ch) in haystack.chars().enumerate() {
+        for lc in ch.to_lowercase() {
+            lowered_chars.push(lc);
+            lowered_to_orig_char_idx.push(orig_idx);
+        }
+    }
+
+    let lowered_needle: Vec<char> = needle.to_lowercase().chars().collect();
+
+    let mut result_orig_indices: Vec<usize> = Vec::with_capacity(lowered_needle.len());
+    let mut last_lower_pos: Option<usize> = None;
+    let mut cur = 0usize;
+    for &nc in lowered_needle.iter() {
+        let mut found_at: Option<usize> = None;
+        while cur < lowered_chars.len() {
+            if lowered_chars[cur] == nc {
+                found_at = Some(cur);
+                cur += 1;
+                break;
+            }
+            cur += 1;
+        }
+        let pos = found_at?;
+        result_orig_indices.push(lowered_to_orig_char_idx[pos]);
+        last_lower_pos = Some(pos);
+    }
+
+    let first_lower_pos = if result_orig_indices.is_empty() {
+        0usize
+    } else {
+        let target_orig = result_orig_indices[0];
+        lowered_to_orig_char_idx
+            .iter()
+            .position(|&oi| oi == target_orig)
+            .unwrap_or(0)
+    };
+    // last defaults to first for single-hit; score = extra span between first/last hit
+    // minus needle len (≥0).
+    // Strongly reward prefix matches by subtracting 100 when the first hit is at index 0.
+    let last_lower_pos = last_lower_pos.unwrap_or(first_lower_pos);
+    let window =
+        (last_lower_pos as i32 - first_lower_pos as i32 + 1) - (lowered_needle.len() as i32);
+    let mut score = window.max(0);
+    if first_lower_pos == 0 {
+        score -= 100;
+    }
+
+    result_orig_indices.sort_unstable();
+    result_orig_indices.dedup();
+    Some((result_orig_indices, score))
+}
+
+/// Convenience wrapper to get only the indices for a fuzzy match.
+pub fn fuzzy_indices(haystack: &str, needle: &str) -> Option<Vec<usize>> {
+    fuzzy_match(haystack, needle).map(|(mut idx, _)| {
+        idx.sort_unstable();
+        idx.dedup();
+        idx
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ascii_basic_indices() {
+        let (idx, score) = match fuzzy_match("hello", "hl") {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        assert_eq!(idx, vec![0, 2]);
+        // 'h' at 0, 'l' at 2 -> window 1; start-of-string bonus applies (-100)
+        assert_eq!(score, -99);
+    }
+
+    #[test]
+    fn unicode_dotted_i_istanbul_highlighting() {
+        let (idx, score) = match fuzzy_match("İstanbul", "is") {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        assert_eq!(idx, vec![0, 1]);
+        // Matches at lowered positions 0 and 2 -> window 1; start-of-string bonus applies
+        assert_eq!(score, -99);
+    }
+
+    #[test]
+    fn unicode_german_sharp_s_casefold() {
+        assert!(fuzzy_match("straße", "strasse").is_none());
+    }
+
+    #[test]
+    fn prefer_contiguous_match_over_spread() {
+        let (_idx_a, score_a) = match fuzzy_match("abc", "abc") {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        let (_idx_b, score_b) = match fuzzy_match("a-b-c", "abc") {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        // Contiguous window -> 0; start-of-string bonus -> -100
+        assert_eq!(score_a, -100);
+        // Spread over 5 chars for 3-letter needle -> window 2; with bonus -> -98
+        assert_eq!(score_b, -98);
+        assert!(score_a < score_b);
+    }
+
+    #[test]
+    fn start_of_string_bonus_applies() {
+        let (_idx_a, score_a) = match fuzzy_match("file_name", "file") {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        let (_idx_b, score_b) = match fuzzy_match("my_file_name", "file") {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        // Start-of-string contiguous -> window 0; bonus -> -100
+        assert_eq!(score_a, -100);
+        // Non-prefix contiguous -> window 0; no bonus -> 0
+        assert_eq!(score_b, 0);
+        assert!(score_a < score_b);
+    }
+
+    #[test]
+    fn empty_needle_matches_with_max_score_and_no_indices() {
+        let (idx, score) = match fuzzy_match("anything", "") {
+            Some(v) => v,
+            None => panic!("empty needle should match"),
+        };
+        assert!(idx.is_empty());
+        assert_eq!(score, i32::MAX);
+    }
+
+    #[test]
+    fn case_insensitive_matching_basic() {
+        let (idx, score) = match fuzzy_match("FooBar", "foO") {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        assert_eq!(idx, vec![0, 1, 2]);
+        // Contiguous prefix match (case-insensitive) -> window 0 with bonus
+        assert_eq!(score, -100);
+    }
+
+    #[test]
+    fn indices_are_deduped_for_multichar_lowercase_expansion() {
+        let needle = "\u{0069}\u{0307}"; // "i" + combining dot above
+        let (idx, score) = match fuzzy_match("İ", needle) {
+            Some(v) => v,
+            None => panic!("expected a match"),
+        };
+        assert_eq!(idx, vec![0]);
+        // Lowercasing 'İ' expands to two chars; contiguous prefix -> window 0 with bonus
+        assert_eq!(score, -100);
+    }
+}

codex-rs/common/src/lib.rs

@@ -23,3 +23,12 @@ mod sandbox_summary;
 
 #[cfg(feature = "sandbox_summary")]
 pub use sandbox_summary::summarize_sandbox_policy;
+
+mod config_summary;
+
+pub use config_summary::create_config_summary_entries;
+// Shared fuzzy matcher (used by TUI selection popups and other UI filtering)
+pub mod fuzzy_match;
+
+#[cfg(any(test, feature = "updates"))]
+pub mod updates;

codex-rs/common/src/sandbox_summary.rs

@@ -7,22 +7,26 @@ pub fn summarize_sandbox_policy(sandbox_policy: &SandboxPolicy) -> String {
         SandboxPolicy::WorkspaceWrite {
             writable_roots,
             network_access,
-            include_default_writable_roots,
+            exclude_tmpdir_env_var,
+            exclude_slash_tmp,
         } => {
             let mut summary = "workspace-write".to_string();
-            if !writable_roots.is_empty() {
-                summary.push_str(&format!(
-                    " [{}]",
-                    writable_roots
-                        .iter()
-                        .map(|p| p.to_string_lossy())
-                        .collect::<Vec<_>>()
-                        .join(", ")
-                ));
+
+            let mut writable_entries = Vec::<String>::new();
+            writable_entries.push("workdir".to_string());
+            if !*exclude_slash_tmp {
+                writable_entries.push("/tmp".to_string());
             }
-            if !*include_default_writable_roots {
-                summary.push_str(" (exact writable roots)");
+            if !*exclude_tmpdir_env_var {
+                writable_entries.push("$TMPDIR".to_string());
             }
+            writable_entries.extend(
+                writable_roots
+                    .iter()
+                    .map(|p| p.to_string_lossy().to_string()),
+            );
+
+            summary.push_str(&format!(" [{}]", writable_entries.join(", ")));
             if *network_access {
                 summary.push_str(" (network access enabled)");
             }

codex-rs/common/src/updates.rs

@@ -1,15 +1,15 @@
-#![cfg(any(not(debug_assertions), test))]
-
 use chrono::DateTime;
 use chrono::Duration;
 use chrono::Utc;
+use codex_core::config::Config;
 use serde::Deserialize;
 use serde::Serialize;
 use std::path::Path;
 use std::path::PathBuf;
+use tracing::error;
 
-use codex_core::config::Config;
-
+/// Returns the latest available version string if it is newer than the current
+/// one, otherwise `None`.
 pub fn get_upgrade_version(config: &Config) -> Option<String> {
     let version_file = version_filepath(config);
     let info = read_version_info(&version_file).ok();
@@ -18,13 +18,11 @@ pub fn get_upgrade_version(config: &Config) -> Option<String> {
         None => true,
         Some(info) => info.last_checked_at < Utc::now() - Duration::hours(20),
     } {
-        // Refresh the cached latest version in the background so TUI startup
-        // isn’t blocked by a network call. The UI reads the previously cached
-        // value (if any) for this run; the next run shows the banner if needed.
+        // Refresh in the background; callers can use the cached value for this run.
         tokio::spawn(async move {
             check_for_update(&version_file)
                 .await
-                .inspect_err(|e| tracing::error!("Failed to update version: {e}"))
+                .inspect_err(|e| error!("Failed to update version: {e}"))
         });
     }
 
@@ -62,7 +60,8 @@ fn read_version_info(version_file: &Path) -> anyhow::Result<VersionInfo> {
     Ok(serde_json::from_str(&contents)?)
 }
 
-async fn check_for_update(version_file: &Path) -> anyhow::Result<()> {
+/// Fetches the latest release info and updates the on-disk cache file.
+pub async fn check_for_update(version_file: &Path) -> anyhow::Result<()> {
     let ReleaseInfo {
         tag_name: latest_tag_name,
     } = reqwest::Client::new()

codex-rs/config.md

@@ -148,12 +148,20 @@ Determines when the user should be prompted to approve whether Codex can execute
 approval_policy = "untrusted"
 ```
 
+If you want to be notified whenever a command fails, use "on-failure":
 ```toml
 # If the command fails when run in the sandbox, Codex asks for permission to
 # retry the command outside the sandbox.
 approval_policy = "on-failure"
 ```
 
+If you want the model to run until it decides that it needs to ask you for escalated permissions, use "on-request":
+```toml
+# The model decides when to escalate
+approval_policy = "on-request"
+```
+
+Alternatively, you can have the model run until it is done, and never ask to run a command with escalated permissions:
 ```toml
 # User is never prompted: if the command fails, Codex will automatically try
 # something out. Note the `exec` subcommand always uses this mode.
@@ -267,9 +275,12 @@ sandbox_mode = "workspace-write"
 
 # Extra settings that only apply when `sandbox = "workspace-write"`.
 [sandbox_workspace_write]
-# By default, only the cwd for the Codex session will be writable (and $TMPDIR
-# on macOS), but you can specify additional writable folders in this array.
-writable_roots = ["/tmp"]
+# By default, the cwd for the Codex session will be writable as well as $TMPDIR
+# (if set) and /tmp (if it exists). Setting the respective options to `true`
+# will override those defaults.
+exclude_tmpdir_env_var = false
+exclude_slash_tmp = false
+
 # Allow the command being run inside the sandbox to make outbound network
 # requests. Disabled by default.
 network_access = false
@@ -328,12 +339,11 @@ disable_response_storage = true
 
 ## shell_environment_policy
 
-Codex spawns subprocesses (e.g. when executing a `local_shell` tool-call suggested by the assistant). By default it passes **only a minimal core subset** of your environment to those subprocesses to avoid leaking credentials. You can tune this behavior via the **`shell_environment_policy`** block in
-`config.toml`:
+Codex spawns subprocesses (e.g. when executing a `local_shell` tool-call suggested by the assistant). By default it now passes **your full environment** to those subprocesses. You can tune this behavior via the **`shell_environment_policy`** block in `config.toml`:
 
 ```toml
 [shell_environment_policy]
-# inherit can be "core" (default), "all", or "none"
+# inherit can be "all" (default), "core", or "none"
 inherit = "core"
 # set to true to *skip* the filter for `"*KEY*"` and `"*TOKEN*"`
 ignore_default_excludes = false
@@ -347,7 +357,7 @@ include_only = ["PATH", "HOME"]
 
 | Field                     | Type                       | Default | Description                                                                                                                                     |
 | ------------------------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `inherit`                 | string                     | `core`  | Starting template for the environment:<br>`core` (`HOME`, `PATH`, `USER`, …), `all` (clone full parent env), or `none` (start empty).           |
+| `inherit`                 | string                     | `all`   | Starting template for the environment:<br>`all` (clone full parent env), `core` (`HOME`, `PATH`, `USER`, …), or `none` (start empty).           |
 | `ignore_default_excludes` | boolean                    | `false` | When `false`, Codex removes any var whose **name** contains `KEY`, `SECRET`, or `TOKEN` (case-insensitive) before other rules run.              |
 | `exclude`                 | array&lt;string&gt;        | `[]`    | Case-insensitive glob patterns to drop after the default filter.<br>Examples: `"AWS_*"`, `"AZURE_*"`.                                           |
 | `set`                     | table&lt;string,string&gt; | `{}`    | Explicit key/value overrides or additions – always win over inherited values.                                                                   |

codex-rs/core/Cargo.toml

@@ -36,6 +36,7 @@ sha1 = "0.10.6"
 shlex = "1.3.0"
 similar = "2.7.0"
 strum_macros = "0.27.2"
+tempfile = "3"
 thiserror = "2.0.12"
 time = { version = "0.3", features = ["formatting", "local-offset", "macros"] }
 tokio = { version = "1", features = [
@@ -47,6 +48,7 @@ tokio = { version = "1", features = [
 ] }
 tokio-util = "0.7.14"
 toml = "0.9.4"
+toml_edit = "0.23.3"
 tracing = { version = "0.1.41", features = ["log"] }
 tree-sitter = "0.25.8"
 tree-sitter-bash = "0.25.0"

codex-rs/core/prompt.md

@@ -1,69 +1,273 @@
-You are operating as and within the Codex CLI, an open-source, terminal-based agentic coding assistant built by OpenAI. It wraps OpenAI models to enable natural language interaction with a local codebase. You are expected to be precise, safe, and helpful.
+You are a coding agent running in the Codex CLI, a terminal-based coding assistant. Codex CLI is an open source project led by OpenAI. You are expected to be precise, safe, and helpful.
 
 Your capabilities:
-- Receive user prompts, project context, and files.
-- Stream responses and emit function calls (e.g., shell commands, code edits).
-- Run commands, like apply_patch, and manage user approvals based on policy.
-- Work inside a workspace with sandboxing instructions specified by the policy described in (## Sandbox environment and approval instructions)
+- Receive user prompts and other context provided by the harness, such as files in the workspace.
+- Communicate with the user by streaming thinking & responses, and by making & updating plans.
+- Emit function calls to run terminal commands and apply patches. Depending on how this specific run is configured, you can request that these function calls be escalated to the user for approval before running. More on this in the "Sandbox and approvals" section.
 
 Within this context, Codex refers to the open-source agentic coding interface (not the old Codex language model built by OpenAI).
 
-## General guidelines
-As a deployed coding agent, please continue working on the user's task until their query is resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the task is solved. If you are not sure about file content or codebase structure pertaining to the user's request, use your tools to read files and gather the relevant information. Do NOT guess or make up an answer.
+# How you work
 
-After a user sends their first message, you should immediately provide a brief message acknowledging their request to set the tone and expectation of future work to be done (no more than 8-10 words). This should be done before performing work like exploring the codebase, writing or reading files, or other tool calls needed to complete the task. Use a natural, collaborative tone similar to how a teammate would receive a task during a pair programming session.
+## Personality
 
-Please resolve the user's task by editing the code files in your current code execution session. Your session allows for you to modify and run code. The repo(s) are already cloned in your working directory, and you must fully solve the problem for your answer to be considered correct.
+Your default personality and tone is concise, direct, and friendly. You communicate efficiently, always keeping the user clearly informed about ongoing actions without unnecessary detail. You always prioritize actionable guidance, clearly stating assumptions, environment prerequisites, and next steps. Unless explicitly asked, you avoid excessively verbose explanations about your work.
 
-### Task execution
-You MUST adhere to the following criteria when executing the task:
+## Responsiveness
 
+### Preamble messages
+
+Before making tool calls, send a brief preamble to the user explaining what you’re about to do. When sending preamble messages, follow these principles and examples:
+
+- **Logically group related actions**: if you’re about to run several related commands, describe them together in one preamble rather than sending a separate note for each.
+- **Keep it concise**: be no more than 1-2 sentences (8–12 words for quick updates).
+- **Build on prior context**: if this is not your first tool call, use the preamble message to connect the dots with what’s been done so far and create a sense of momentum and clarity for the user to understand your next actions.
+- **Keep your tone light, friendly and curious**: add small touches of personality in preambles feel collaborative and engaging.
+
+**Examples:**
+- “I’ve explored the repo; now checking the API route definitions.”
+- “Next, I’ll patch the config and update the related tests.”
+- “I’m about to scaffold the CLI commands and helper functions.”
+- “Ok cool, so I’ve wrapped my head around the repo. Now digging into the API routes.”
+- “Config’s looking tidy. Next up is patching helpers to keep things in sync.”
+- “Finished poking at the DB gateway. I will now chase down error handling.”
+- “Alright, build pipeline order is interesting. Checking how it reports failures.”
+- “Spotted a clever caching util; now hunting where it gets used.”
+
+**Avoiding a preamble for every trivial read (e.g., `cat` a single file) unless it’s part of a larger grouped action.
+- Jumping straight into tool calls without explaining what’s about to happen.
+- Writing overly long or speculative preambles — focus on immediate, tangible next steps.
+
+## Planning
+
+You have access to an `update_plan` tool which tracks steps and progress and renders them to the user. Using the tool helps demonstrate that you've understood the task and convey how you're approaching it. Plans can help to make complex, ambiguous, or multi-phase work clearer and more collaborative for the user. A good plan should break the task into meaningful, logically ordered steps that are easy to verify as you go. Note that plans are not for padding out simple work with filler steps or stating the obvious. Do not repeat the full contents of the plan after an `update_plan` call — the harness already displays it. Instead, summarize the change made and highlight any important context or next step.
+
+Use a plan when:
+- The task is non-trivial and will require multiple actions over a long time horizon.
+- There are logical phases or dependencies where sequencing matters.
+- The work has ambiguity that benefits from outlining high-level goals.
+- You want intermediate checkpoints for feedback and validation.
+- When the user asked you to do more than one thing in a single prompt
+- The user has asked you to use the plan tool (aka "TODOs")
+- You generate additional steps while working, and plan to do them before yielding to the user
+
+Skip a plan when:
+- The task is simple and direct.
+- Breaking it down would only produce literal or trivial steps.
+
+Planning steps are called "steps" in the tool, but really they're more like tasks or TODOs. As such they should be very concise descriptions of non-obvious work that an engineer might do like "Write the API spec", then "Update the backend", then "Implement the frontend". On the other hand, it's obvious that you'll usually have to "Explore the codebase" or "Implement the changes", so those are not worth tracking in your plan.
+
+It may be the case that you complete all steps in your plan after a single pass of implementation. If this is the case, you can simply mark all the planned steps as completed. The content of your plan should not involve doing anything that you aren't capable of doing (i.e. don't try to test things that you can't test). Do not use plans for simple or single-step queries that you can just do or answer immediately.
+
+### Examples
+
+**High-quality plans**
+
+Example 1:
+
+1. Add CLI entry with file args
+2. Parse Markdown via CommonMark library
+3. Apply semantic HTML template
+4. Handle code blocks, images, links
+5. Add error handling for invalid files
+
+Example 2:
+
+1. Define CSS variables for colors
+2. Add toggle with localStorage state
+3. Refactor components to use variables
+4. Verify all views for readability
+5. Add smooth theme-change transition
+
+Example 3:
+
+1. Set up Node.js + WebSocket server
+2. Add join/leave broadcast events
+3. Implement messaging with timestamps
+4. Add usernames + mention highlighting
+5. Persist messages in lightweight DB
+6. Add typing indicators + unread count
+
+**Low-quality plans**
+
+Example 1:
+
+1. Create CLI tool
+2. Add Markdown parser
+3. Convert to HTML
+
+Example 2:
+
+1. Add dark mode toggle
+2. Save preference
+3. Make styles look good
+
+Example 3:
+
+1. Create single-file HTML game
+2. Run quick sanity check
+3. Summarize usage instructions
+
+If you need to write a plan, only write high quality plans, not low quality ones.
+
+## Task execution
+
+You are a coding agent. Please keep going until the query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved. Autonomously resolve the query to the best of your ability, using the tools available to you, before coming back to the user. Do NOT guess or make up an answer.
+
+You MUST adhere to the following criteria when solving queries:
 - Working on the repo(s) in the current environment is allowed, even if they are proprietary.
 - Analyzing code for vulnerabilities is allowed.
 - Showing user code and tool call details is allowed.
-- User instructions may overwrite the _CODING GUIDELINES_ section in this developer message.
-- `user_instructions` are not part of the user's request, but guidance for how to complete the task.
-- Do not cite `user_instructions` back to the user unless a specific piece is relevant.
-- Do not use \`ls -R\`, \`find\`, or \`grep\` - these are slow in large repos. Use \`rg\` and \`rg --files\`.
-- Use the \`apply_patch\` shell command to edit files: {"command":["apply_patch","*** Begin Patch\\n*** Update File: path/to/file.py\\n@@ def example():\\n- pass\\n+ return 123\\n*** End Patch"]}
-- If completing the user's task requires writing or modifying files:
-  - Your code and final answer should follow these _CODING GUIDELINES_:
-    - Fix the problem at the root cause rather than applying surface-level patches, when possible.
-    - Avoid unneeded complexity in your solution.
-      - Ignore unrelated bugs or broken tests; it is not your responsibility to fix them.
-    - Update documentation as necessary.
-    - Keep changes consistent with the style of the existing codebase. Changes should be minimal and focused on the task.
-      - Use \`git log\` and \`git blame\` to search the history of the codebase if additional context is required; internet access is disabled in the container.
-    - NEVER add copyright or license headers unless specifically requested.
-    - You do not need to \`git commit\` your changes; this will be done automatically for you.
-    - If there is a .pre-commit-config.yaml, use \`pre-commit run --files ...\` to check that your changes pass the pre- commit checks. However, do not fix pre-existing errors on lines you didn't touch.
-      - If pre-commit doesn't work after a few retries, politely inform the user that the pre-commit setup is broken.
-    - Once you finish coding, you must
-      - Check \`git status\` to sanity check your changes; revert any scratch files or changes.
-      - Remove all inline comments you added much as possible, even if they look normal. Check using \`git diff\`. Inline comments must be generally avoided, unless active maintainers of the repo, after long careful study of the code and the issue, will still misinterpret the code without the comments.
-      - Check if you accidentally add copyright or license headers. If so, remove them.
-      - Try to run pre-commit if it is available.
-      - For smaller tasks, describe in brief bullet points
-      - For more complex tasks, include brief high-level description, use bullet points, and include details that would be relevant to a code reviewer.
-- If completing the user's task DOES NOT require writing or modifying files (e.g., the user asks a question about the code base):
-  - Respond in a friendly tune as a remote teammate, who is knowledgeable, capable and eager to help with coding.
-- When your task involves writing or modifying files:
-  - Do NOT tell the user to "save the file" or "copy the code into a file" if you already created or modified the file using the `apply_patch` shell command. Instead, reference the file as already saved.
-  - Do NOT show the full contents of large files you have already written, unless the user explicitly asks for them.
+- Use the `apply_patch` tool to edit files (NEVER try `applypatch` or `apply-patch`, only `apply_patch`): {"command":["apply_patch","*** Begin Patch\\n*** Update File: path/to/file.py\\n@@ def example():\\n-  pass\\n+  return 123\\n*** End Patch"]}
 
-## Using the shell command `apply_patch` to edit files
-`apply_patch` is a shell command for editing files. Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:
+If completing the user's task requires writing or modifying files, your code and final answer should follow these coding guidelines, though user instructions (i.e. AGENTS.md) may override these guidelines:
 
-*** Begin Patch
+- Fix the problem at the root cause rather than applying surface-level patches, when possible.
+- Avoid unneeded complexity in your solution.
+- Do not attempt to fix unrelated bugs or broken tests. It is not your responsibility to fix them. (You may mention them to the user in your final message though.)
+- Update documentation as necessary.
+- Keep changes consistent with the style of the existing codebase. Changes should be minimal and focused on the task.
+- Use `git log` and `git blame` to search the history of the codebase if additional context is required.
+- NEVER add copyright or license headers unless specifically requested.
+- Do not waste tokens by re-reading files after calling `apply_patch` on them. The tool call will fail if it didn't work. The same goes for making folders, deleting folders, etc.
+- Do not `git commit` your changes or create new git branches unless explicitly requested.
+- Do not add inline comments within code unless explicitly requested.
+- Do not use one-letter variable names unless explicitly requested.
+- NEVER output inline citations like "【F:README.md†L5-L14】" in your outputs. The CLI is not able to render these so they will just be broken in the UI. Instead, if you output valid filepaths, users will be able to click on them to open the files in their editor.
+
+## Testing your work
+
+If the codebase has tests or the ability to build or run, you should use them to verify that your work is complete. Generally, your testing philosophy should be to start as specific as possible to the code you changed so that you can catch issues efficiently, then make your way to broader tests as you build confidence. If there's no test for the code you changed, and if the adjacent patterns in the codebases show that there's a logical place for you to add a test, you may do so. However, do not add tests to codebases with no tests, or where the patterns don't indicate so.
+
+Once you're confident in correctness, use formatting commands to ensure that your code is well formatted. These commands can take time so you should run them on as precise a target as possible. If there are issues you can iterate up to 3 times to get formatting right, but if you still can't manage it's better to save the user time and present them a correct solution where you call out the formatting in your final message. If the codebase does not have a formatter configured, do not add one.
+
+For all of testing, running, building, and formatting, do not attempt to fix unrelated bugs. It is not your responsibility to fix them. (You may mention them to the user in your final message though.)
+
+## Sandbox and approvals
+
+The Codex CLI harness supports several different sandboxing, and approval configurations that the user can choose from.
+
+Filesystem sandboxing prevents you from editing files without user approval. The options are:
+- *read-only*: You can only read files.
+- *workspace-write*: You can read files. You can write to files in your workspace folder, but not outside it.
+- *danger-full-access*: No filesystem sandboxing.
+
+Network sandboxing prevents you from accessing network without approval. Options are
+- *ON*
+- *OFF*
+
+Approvals are your mechanism to get user consent to perform more privileged actions. Although they introduce friction to the user because your work is paused until the user responds, you should leverage them to accomplish your important work. Do not let these settings or the sandbox deter you from attempting to accomplish the user's task. Approval options are
+- *untrusted*: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands.
+- *on-failure*: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.
+- *on-request*: Commands will be run in the sandbox by default, and you can specify in your tool call if you want to escalate a command to run without sandboxing. (Note that this mode is not always available. If it is, you'll see parameters for it in the `shell` command description.)
+- *never*: This is a non-interactive mode where you may NEVER ask the user for approval to run commands. Instead, you must always persist and work around constraints to solve the task for the user. You MUST do your utmost best to finish the task and validate your work before yielding. If this mode is pared with `danger-full-access`, take advantage of it to deliver the best outcome for the user. Further, in this mode, your default testing philosophy is overridden: Even if you don't see local patterns for testing, you may add tests and scripts to validate your work. Just remove them before yielding.
+
+When you are running with approvals `on-request`, and sandboxing enabled, here are scenarios where you'll need to request approval:
+- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /tmp)
+- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.
+- You are running sandboxed and need to run a command that requires network access (e.g. installing packages)
+- If you run a command that is important to solving the user's query, but it fails because of sandboxing, rerun the command with approval.
+- You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for
+- (For all of these, you should weigh alternative paths that do not require approval.)
+
+Note that when sandboxing is set to read-only, you'll need to request approval for any command that isn't a read.
+
+You will be told what filesystem sandboxing, network sandboxing, and approval mode are active in a developer or user message. If you are not told about this, assume that you are running with workspace-write, network sandboxing ON, and approval on-failure.
+
+## Ambition vs. precision
+
+For tasks that have no prior context (i.e. the user is starting something brand new), you should feel free to be ambitious and demonstrate creativity with your implementation.
+
+If you're operating in an existing codebase, you should make sure you do exactly what the user asks with surgical precision. Treat the surrounding codebase with respect, and don't overstep (i.e. changing filenames or variables unnecessarily). You should balance being sufficiently ambitious and proactive when completing tasks of this nature.
+
+You should use judicious initiative to decide on the right level of detail and complexity to deliver based on the user's needs. This means showing good judgment that you're capable of doing the right extras without gold-plating. This might be demonstrated by high-value, creative touches when scope of the task is vague; while being surgical and targeted when scope is tightly specified.
+
+## Sharing progress updates
+
+For especially longer tasks that you work on (i.e. requiring many tool calls, or a plan with multiple steps), you should provide progress updates back to the user at reasonable intervals. These updates should be structured as a concise sentence or two (no more than 8-10 words long) recapping progress so far in plain language: this update demonstrates your understanding of what needs to be done, progress so far (i.e. files explores, subtasks complete), and where you're going next.
+
+Before doing large chunks of work that may incur latency as experienced by the user (i.e. writing a new file), you should send a concise message to the user with an update indicating what you're about to do to ensure they know what you're spending time on. Don't start editing or writing large files before informing the user what you are doing and why.
+
+The messages you send before tool calls should describe what is immediately about to be done next in very concise language. If there was previous work done, this preamble message should also include a note about the work done so far to bring the user along.
+
+## Presenting your work and final message
+
+Your final message should read naturally, like an update from a concise teammate. For casual conversation, brainstorming tasks, or quick questions from the user, respond in a friendly, conversational tone. You should ask questions, suggest ideas, and adapt to the user’s style. If you've finished a large amount of work, when describing what you've done to the user, you should follow the final answer formatting guidelines to communicate substantive changes. You don't need to add structured formatting for one-word answers, greetings, or purely conversational exchanges.
+
+You can skip heavy formatting for single, simple actions or confirmations. In these cases, respond in plain sentences with any relevant next step or quick option. Reserve multi-section structured responses for results that need grouping or explanation.
+
+The user is working on the same computer as you, and has access to your work. As such there's no need to show the full contents of large files you have already written unless the user explicitly asks for them. Similarly, if you've created or modified files using `apply_patch`, there's no need to tell users to "save the file" or "copy the code into a file"—just reference the file path.
+
+If there's something that you think you could help with as a logical next step, concisely ask the user if they want you to do so. Good examples of this are running tests, committing changes, or building out the next logical component. If there’s something that you couldn't do (even with approval) but that the user might want to do (such as verifying changes by running the app), include those instructions succinctly.
+
+Brevity is very important as a default. You should be very concise (i.e. no more than 10 lines), but can relax this requirement for tasks where additional detail and comprehensiveness is important for the user's understanding.
+
+### Final answer structure and style guidelines
+
+You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
+
+**Section Headers**
+- Use only when they improve clarity — they are not mandatory for every answer.
+- Choose descriptive names that fit the content
+- Keep headers short (1–3 words) and in `**Title Case**`. Always start headers with `**` and end with `**`
+- Leave no blank line before the first bullet under a header.
+- Section headers should only be used where they genuinely improve scanability; avoid fragmenting the answer.
+
+**Bullets**
+- Use `-` followed by a space for every bullet.
+- Bold the keyword, then colon + concise description.
+- Merge related points when possible; avoid a bullet for every trivial detail.
+- Keep bullets to one line unless breaking for clarity is unavoidable.
+- Group into short lists (4–6 bullets) ordered by importance.
+- Use consistent keyword phrasing and formatting across sections.
+
+**Monospace**
+- Wrap all commands, file paths, env vars, and code identifiers in backticks (`` `...` ``).
+- Apply to inline examples and to bullet keywords if the keyword itself is a literal file/command.
+- Never mix monospace and bold markers; choose one based on whether it’s a keyword (`**`) or inline code/path (`` ` ``).
+
+**Structure**
+- Place related bullets together; don’t mix unrelated concepts in the same section.
+- Order sections from general → specific → supporting info.
+- For subsections (e.g., “Binaries” under “Rust Workspace”), introduce with a bolded keyword bullet, then list items under it.
+- Match structure to complexity:
+  - Multi-part or detailed results → use clear headers and grouped bullets.
+  - Simple results → minimal headers, possibly just a short list or paragraph.
+
+**Tone**
+- Keep the voice collaborative and natural, like a coding partner handing off work.
+- Be concise and factual — no filler or conversational commentary and avoid unnecessary repetition
+- Use present tense and active voice (e.g., “Runs tests” not “This will run tests”).
+- Keep descriptions self-contained; don’t refer to “above” or “below”.
+- Use parallel structure in lists for consistency.
+
+**Don’t**
+- Don’t use literal words “bold” or “monospace” in the content.
+- Don’t nest bullets or create deep hierarchies.
+- Don’t output ANSI escape codes directly — the CLI renderer applies them.
+- Don’t cram unrelated keywords into a single bullet; split for clarity.
+- Don’t let keyword lists run long — wrap or reformat for scanability.
+
+Generally, ensure your final answers adapt their shape and depth to the request. For example, answers to code explanations should have a precise, structured explanation with code references that answer the question directly. For tasks with a simple implementation, lead with the outcome and supplement only with what’s needed for clarity. Larger changes can be presented as a logical walkthrough of your approach, grouping related steps, explaining rationale where it adds value, and highlighting next actions to accelerate the user. Your answers should provide the right level of detail while being easily scannable.
+
+For casual greetings, acknowledgements, or other one-off conversational messages that are not delivering substantive information or structured results, respond naturally without section headers or bullet formatting.
+
+# Tools
+
+## `apply_patch`
+
+Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:
+
+**_ Begin Patch
 [ one or more file sections ]
-*** End Patch
+_** End Patch
 
 Within that envelope, you get a sequence of file operations.
 You MUST include a header to specify the action you are taking.
 Each operation starts with one of three headers:
 
-*** Add File: <path> - create a new file. Every following line is a + line (the initial contents).
-*** Delete File: <path> - remove an existing file. Nothing follows.
+**_ Add File: <path> - create a new file. Every following line is a + line (the initial contents).
+_** Delete File: <path> - remove an existing file. Nothing follows.
 \*\*\* Update File: <path> - patch an existing file in place (optionally with a rename).
 
 May be immediately followed by \*\*\* Move to: <new path> if you want to rename the file.
@@ -77,60 +281,46 @@ Within a hunk each line starts with:
   At the end of a truncated hunk you can emit \*\*\* End of File.
 
 Patch := Begin { FileOp } End
-Begin := "*** Begin Patch" NEWLINE
-End := "*** End Patch" NEWLINE
+Begin := "**_ Begin Patch" NEWLINE
+End := "_** End Patch" NEWLINE
 FileOp := AddFile | DeleteFile | UpdateFile
-AddFile := "*** Add File: " path NEWLINE { "+" line NEWLINE }
-DeleteFile := "*** Delete File: " path NEWLINE
-UpdateFile := "*** Update File: " path NEWLINE [ MoveTo ] { Hunk }
-MoveTo := "*** Move to: " newPath NEWLINE
+AddFile := "**_ Add File: " path NEWLINE { "+" line NEWLINE }
+DeleteFile := "_** Delete File: " path NEWLINE
+UpdateFile := "**_ Update File: " path NEWLINE [ MoveTo ] { Hunk }
+MoveTo := "_** Move to: " newPath NEWLINE
 Hunk := "@@" [ header ] NEWLINE { HunkLine } [ "*** End of File" NEWLINE ]
 HunkLine := (" " | "-" | "+") text NEWLINE
 
 A full patch can combine several operations:
 
-*** Begin Patch
-*** Add File: hello.txt
+**_ Begin Patch
+_** Add File: hello.txt
 +Hello world
-*** Update File: src/app.py
-*** Move to: src/main.py
+**_ Update File: src/app.py
+_** Move to: src/main.py
 @@ def greet():
 -print("Hi")
 +print("Hello, world!")
-*** Delete File: obsolete.txt
-*** End Patch
+**_ Delete File: obsolete.txt
+_** End Patch
 
 It is important to remember:
 
 - You must include a header with your intended action (Add/Delete/Update)
 - You must prefix new lines with `+` even when creating a new file
-- You must follow this schema exactly when providing a patch
 
-You can invoke apply_patch with the following shell command:
+You can invoke apply_patch like:
 
 ```
 shell {"command":["apply_patch","*** Begin Patch\n*** Add File: hello.txt\n+Hello, world!\n*** End Patch\n"]}
 ```
 
-## Sandbox environment and approval instructions
+## `update_plan`
 
-You are running in a sandboxed workspace backed by version control. The sandbox might be configured by the user to restrict certain behaviors, like accessing the internet or writing to files outside the current directory.
+A tool named `update_plan` is available to you. You can use it to keep an up‑to‑date, step‑by‑step plan for the task.
 
-Commands that are blocked by sandbox settings will be automatically sent to the user for approval. The result of the request will be returned (i.e. the command result, or the request denial).
-The user also has an opportunity to approve the same command for the rest of the session.
+To create a new plan, call `update_plan` with a short list of 1‑sentence steps (no more than 5-7 words each) with a `status` for each step (`pending`, `in_progress`, or `completed`).
 
-Guidance on running within the sandbox:
-- When running commands that will likely require approval, attempt to use simple, precise commands, to reduce frequency of approval requests.
-- When approval is denied or a command fails due to a permission error, do not retry the exact command in a different way. Move on and continue trying to address the user's request.
-
-
-## Tools available
-### Plan updates
-
-A tool named `update_plan` is available. Use it to keep an up‑to‑date, step‑by‑step plan for the task so you can follow your progress. When making your plans, keep in mind that you are a deployed coding agent - `update_plan` calls should not involve doing anything that you aren't capable of doing. For example, `update_plan` calls should NEVER contain tasks to merge your own pull requests. Only stop to ask the user if you genuinely need their feedback on a change.
-
-- At the start of any nontrivial task, call `update_plan` with an initial plan: a short list of 1‑sentence steps with a `status` for each step (`pending`, `in_progress`, or `completed`). There should always be exactly one `in_progress` step until everything is done.
-- Whenever you finish a step, call `update_plan` again, marking the finished step as `completed` and the next step as `in_progress`.
-- If your plan needs to change, call `update_plan` with the revised steps and include an `explanation` describing the change.
-- When all steps are complete, make a final `update_plan` call with all steps marked `completed`.
+When steps have been completed, use `update_plan` to mark each finished step as `completed` and the next step you are working on as `in_progress`. There should always be exactly one `in_progress` step until everything is done. You can mark multiple items as complete in a single `update_plan` call.
 
+If all steps are complete, ensure you call `update_plan` to mark all steps as `completed`.

codex-rs/core/src/chat_completions.rs

@@ -32,7 +32,6 @@ use crate::util::backoff;
 pub(crate) async fn stream_chat_completions(
     prompt: &Prompt,
     model_family: &ModelFamily,
-    include_plan_tool: bool,
     client: &reqwest::Client,
     provider: &ModelProviderInfo,
 ) -> Result<ResponseStream> {
@@ -42,11 +41,9 @@ pub(crate) async fn stream_chat_completions(
     let full_instructions = prompt.get_full_instructions(model_family);
     messages.push(json!({"role": "system", "content": full_instructions}));
 
-    if let Some(instr) = &prompt.get_formatted_user_instructions() {
-        messages.push(json!({"role": "user", "content": instr}));
-    }
+    let input = prompt.get_formatted_input();
 
-    for item in &prompt.input {
+    for item in &input {
         match item {
             ResponseItem::Message { role, content, .. } => {
                 let mut text = String::new();
@@ -112,8 +109,7 @@ pub(crate) async fn stream_chat_completions(
         }
     }
 
-    let tools_json =
-        create_tools_json_for_chat_completions_api(prompt, model_family, include_plan_tool)?;
+    let tools_json = create_tools_json_for_chat_completions_api(&prompt.tools)?;
     let payload = json!({
         "model": model_family.slug,
         "messages": messages,

codex-rs/core/src/client.rs

@@ -31,16 +31,26 @@ use crate::config_types::ReasoningEffort as ReasoningEffortConfig;
 use crate::config_types::ReasoningSummary as ReasoningSummaryConfig;
 use crate::error::CodexErr;
 use crate::error::Result;
+use crate::error::UsageLimitReachedError;
 use crate::flags::CODEX_RS_SSE_FIXTURE;
 use crate::model_provider_info::ModelProviderInfo;
 use crate::model_provider_info::WireApi;
-use crate::models::ContentItem;
 use crate::models::ResponseItem;
 use crate::openai_tools::create_tools_json_for_responses_api;
 use crate::protocol::TokenUsage;
 use crate::util::backoff;
 use std::sync::Arc;
 
+#[derive(Debug, Deserialize)]
+struct ErrorResponse {
+    error: Error,
+}
+
+#[derive(Debug, Deserialize)]
+struct Error {
+    r#type: String,
+}
+
 #[derive(Clone)]
 pub struct ModelClient {
     config: Arc<Config>,
@@ -83,7 +93,6 @@ impl ModelClient {
                 let response_stream = stream_chat_completions(
                     prompt,
                     &self.config.model_family,
-                    self.config.include_plan_tool,
                     &self.client,
                     &self.provider,
                 )
@@ -132,11 +141,7 @@ impl ModelClient {
         let store = prompt.store && auth_mode != Some(AuthMode::ChatGPT);
 
         let full_instructions = prompt.get_full_instructions(&self.config.model_family);
-        let tools_json = create_tools_json_for_responses_api(
-            prompt,
-            &self.config.model_family,
-            self.config.include_plan_tool,
-        )?;
+        let tools_json = create_tools_json_for_responses_api(&prompt.tools)?;
         let reasoning = create_reasoning_param_for_request(
             &self.config.model_family,
             self.effort,
@@ -151,15 +156,7 @@ impl ModelClient {
             vec![]
         };
 
-        let mut input_with_instructions = Vec::with_capacity(prompt.input.len() + 1);
-        if let Some(ui) = prompt.get_formatted_user_instructions() {
-            input_with_instructions.push(ResponseItem::Message {
-                id: None,
-                role: "user".to_string(),
-                content: vec![ContentItem::InputText { text: ui }],
-            });
-        }
-        input_with_instructions.extend(prompt.input.clone());
+        let input_with_instructions = prompt.get_formatted_input();
 
         let payload = ResponsesApiRequest {
             model: &self.config.model,
@@ -199,7 +196,7 @@ impl ModelClient {
 
             if let Some(auth) = auth.as_ref()
                 && auth.mode == AuthMode::ChatGPT
-                && let Some(account_id) = auth.get_account_id().await
+                && let Some(account_id) = auth.get_account_id()
             {
                 req_builder = req_builder.header("chatgpt-account-id", account_id);
             }
@@ -239,6 +236,14 @@ impl ModelClient {
                 }
                 Ok(res) => {
                     let status = res.status();
+
+                    // Pull out Retry‑After header if present.
+                    let retry_after_secs = res
+                        .headers()
+                        .get(reqwest::header::RETRY_AFTER)
+                        .and_then(|v| v.to_str().ok())
+                        .and_then(|s| s.parse::<u64>().ok());
+
                     // The OpenAI Responses endpoint returns structured JSON bodies even for 4xx/5xx
                     // errors. When we bubble early with only the HTTP status the caller sees an opaque
                     // "unexpected status 400 Bad Request" which makes debugging nearly impossible.
@@ -252,16 +257,29 @@ impl ModelClient {
                         return Err(CodexErr::UnexpectedStatus(status, body));
                     }
 
-                    if attempt > max_retries {
-                        return Err(CodexErr::RetryLimit(status));
+                    if status == StatusCode::TOO_MANY_REQUESTS {
+                        let body = res.json::<ErrorResponse>().await.ok();
+                        if let Some(ErrorResponse {
+                            error: Error { r#type, .. },
+                        }) = body
+                        {
+                            if r#type == "usage_limit_reached" {
+                                return Err(CodexErr::UsageLimitReached(UsageLimitReachedError {
+                                    plan_type: auth.and_then(|a| a.get_plan_type()),
+                                }));
+                            } else if r#type == "usage_not_included" {
+                                return Err(CodexErr::UsageNotIncluded);
+                            }
+                        }
                     }
 
-                    // Pull out Retry‑After header if present.
-                    let retry_after_secs = res
-                        .headers()
-                        .get(reqwest::header::RETRY_AFTER)
-                        .and_then(|v| v.to_str().ok())
-                        .and_then(|s| s.parse::<u64>().ok());
+                    if attempt > max_retries {
+                        if status == StatusCode::INTERNAL_SERVER_ERROR {
+                            return Err(CodexErr::InternalServerError);
+                        }
+
+                        return Err(CodexErr::RetryLimit(status));
+                    }
 
                     let delay = retry_after_secs
                         .map(|s| Duration::from_millis(s * 1_000))
@@ -637,7 +655,7 @@ mod tests {
             request_max_retries: Some(0),
             stream_max_retries: Some(0),
             stream_idle_timeout_ms: Some(1000),
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let events = collect_events(
@@ -697,7 +715,7 @@ mod tests {
             request_max_retries: Some(0),
             stream_max_retries: Some(0),
             stream_idle_timeout_ms: Some(1000),
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let events = collect_events(&[sse1.as_bytes()], provider).await;
@@ -800,7 +818,7 @@ mod tests {
                 request_max_retries: Some(0),
                 stream_max_retries: Some(0),
                 stream_idle_timeout_ms: Some(1000),
-                requires_auth: false,
+                requires_openai_auth: false,
             };
 
             let out = run_sse(evs, provider).await;

codex-rs/core/src/client_common.rs

@@ -2,13 +2,18 @@ use crate::config_types::ReasoningEffort as ReasoningEffortConfig;
 use crate::config_types::ReasoningSummary as ReasoningSummaryConfig;
 use crate::error::Result;
 use crate::model_family::ModelFamily;
+use crate::models::ContentItem;
 use crate::models::ResponseItem;
+use crate::openai_tools::OpenAiTool;
+use crate::protocol::AskForApproval;
+use crate::protocol::SandboxPolicy;
 use crate::protocol::TokenUsage;
 use codex_apply_patch::APPLY_PATCH_TOOL_INSTRUCTIONS;
 use futures::Stream;
 use serde::Serialize;
 use std::borrow::Cow;
-use std::collections::HashMap;
+use std::fmt::Display;
+use std::path::PathBuf;
 use std::pin::Pin;
 use std::task::Context;
 use std::task::Poll;
@@ -18,10 +23,47 @@ use tokio::sync::mpsc;
 /// with this content.
 const BASE_INSTRUCTIONS: &str = include_str!("../prompt.md");
 
+/// wraps environment context message in a tag for the model to parse more easily.
+const ENVIRONMENT_CONTEXT_START: &str = "<environment_context>\n\n";
+const ENVIRONMENT_CONTEXT_END: &str = "\n\n</environment_context>";
+
 /// wraps user instructions message in a tag for the model to parse more easily.
 const USER_INSTRUCTIONS_START: &str = "<user_instructions>\n\n";
 const USER_INSTRUCTIONS_END: &str = "\n\n</user_instructions>";
 
+#[derive(Debug, Clone)]
+pub(crate) struct EnvironmentContext {
+    pub cwd: PathBuf,
+    pub approval_policy: AskForApproval,
+    pub sandbox_policy: SandboxPolicy,
+}
+
+impl Display for EnvironmentContext {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        writeln!(
+            f,
+            "Current working directory: {}",
+            self.cwd.to_string_lossy()
+        )?;
+        writeln!(f, "Approval policy: {}", self.approval_policy)?;
+        writeln!(f, "Sandbox policy: {}", self.sandbox_policy)?;
+
+        let network_access = match self.sandbox_policy.clone() {
+            SandboxPolicy::DangerFullAccess => "enabled",
+            SandboxPolicy::ReadOnly => "restricted",
+            SandboxPolicy::WorkspaceWrite { network_access, .. } => {
+                if network_access {
+                    "enabled"
+                } else {
+                    "restricted"
+                }
+            }
+        };
+        writeln!(f, "Network access: {network_access}")?;
+        Ok(())
+    }
+}
+
 /// API request payload for a single model turn.
 #[derive(Default, Debug, Clone)]
 pub struct Prompt {
@@ -33,10 +75,13 @@ pub struct Prompt {
     /// Whether to store response on server side (disable_response_storage = !store).
     pub store: bool,
 
-    /// Additional tools sourced from external MCP servers. Note each key is
-    /// the "fully qualified" tool name (i.e., prefixed with the server name),
-    /// which should be reported to the model in place of Tool::name.
-    pub extra_tools: HashMap<String, mcp_types::Tool>,
+    /// A list of key-value pairs that will be added as a developer message
+    /// for the model to use
+    pub environment_context: Option<EnvironmentContext>,
+
+    /// Tools available to the model, including additional tools sourced from
+    /// external MCP servers.
+    pub tools: Vec<OpenAiTool>,
 
     /// Optional override for the built-in BASE_INSTRUCTIONS.
     pub base_instructions_override: Option<String>,
@@ -55,11 +100,37 @@ impl Prompt {
         Cow::Owned(sections.join("\n"))
     }
 
-    pub(crate) fn get_formatted_user_instructions(&self) -> Option<String> {
+    fn get_formatted_user_instructions(&self) -> Option<String> {
         self.user_instructions
             .as_ref()
             .map(|ui| format!("{USER_INSTRUCTIONS_START}{ui}{USER_INSTRUCTIONS_END}"))
     }
+
+    fn get_formatted_environment_context(&self) -> Option<String> {
+        self.environment_context
+            .as_ref()
+            .map(|ec| format!("{ENVIRONMENT_CONTEXT_START}{ec}{ENVIRONMENT_CONTEXT_END}"))
+    }
+
+    pub(crate) fn get_formatted_input(&self) -> Vec<ResponseItem> {
+        let mut input_with_instructions = Vec::with_capacity(self.input.len() + 2);
+        if let Some(ec) = self.get_formatted_environment_context() {
+            input_with_instructions.push(ResponseItem::Message {
+                id: None,
+                role: "user".to_string(),
+                content: vec![ContentItem::InputText { text: ec }],
+            });
+        }
+        if let Some(ui) = self.get_formatted_user_instructions() {
+            input_with_instructions.push(ResponseItem::Message {
+                id: None,
+                role: "user".to_string(),
+                content: vec![ContentItem::InputText { text: ui }],
+            });
+        }
+        input_with_instructions.extend(self.input.clone());
+        input_with_instructions
+    }
 }
 
 #[derive(Debug)]

codex-rs/core/src/codex.rs

@@ -37,6 +37,7 @@ use crate::apply_patch::convert_apply_patch_to_protocol;
 use crate::apply_patch::get_writable_roots;
 use crate::apply_patch::{self};
 use crate::client::ModelClient;
+use crate::client_common::EnvironmentContext;
 use crate::client_common::Prompt;
 use crate::client_common::ResponseEvent;
 use crate::config::Config;
@@ -45,6 +46,7 @@ use crate::conversation_history::ConversationHistory;
 use crate::error::CodexErr;
 use crate::error::Result as CodexResult;
 use crate::error::SandboxErr;
+use crate::error::get_error_message_ui;
 use crate::exec::ExecParams;
 use crate::exec::ExecToolCallOutput;
 use crate::exec::SandboxType;
@@ -61,6 +63,8 @@ use crate::models::ReasoningItemReasoningSummary;
 use crate::models::ResponseInputItem;
 use crate::models::ResponseItem;
 use crate::models::ShellToolCallParams;
+use crate::openai_tools::ToolsConfig;
+use crate::openai_tools::get_openai_tools;
 use crate::plan_tool::handle_update_plan;
 use crate::project_doc::get_user_instructions;
 use crate::protocol::AgentMessageDeltaEvent;
@@ -216,6 +220,7 @@ pub(crate) struct Session {
     shell_environment_policy: ShellEnvironmentPolicy,
     pub(crate) writable_roots: Mutex<Vec<PathBuf>>,
     disable_response_storage: bool,
+    tools_config: ToolsConfig,
 
     /// Manager for external MCP servers/tools.
     mcp_connection_manager: McpConnectionManager,
@@ -464,6 +469,57 @@ impl Session {
             }
         }
     }
+    /// Runs the exec tool call and emits events for the begin and end of the
+    /// command even on error.
+    ///
+    /// Returns the output of the exec tool call.
+    async fn run_exec_with_events<'a>(
+        &self,
+        turn_diff_tracker: &mut TurnDiffTracker,
+        begin_ctx: ExecCommandContext,
+        exec_args: ExecInvokeArgs<'a>,
+    ) -> crate::error::Result<ExecToolCallOutput> {
+        let is_apply_patch = begin_ctx.apply_patch.is_some();
+        let sub_id = begin_ctx.sub_id.clone();
+        let call_id = begin_ctx.call_id.clone();
+
+        self.on_exec_command_begin(turn_diff_tracker, begin_ctx.clone())
+            .await;
+
+        let result = process_exec_tool_call(
+            exec_args.params,
+            exec_args.sandbox_type,
+            exec_args.ctrl_c,
+            exec_args.sandbox_policy,
+            exec_args.codex_linux_sandbox_exe,
+            exec_args.stdout_stream,
+        )
+        .await;
+
+        let output_stderr;
+        let borrowed: &ExecToolCallOutput = match &result {
+            Ok(output) => output,
+            Err(e) => {
+                output_stderr = ExecToolCallOutput {
+                    exit_code: -1,
+                    stdout: String::new(),
+                    stderr: get_error_message_ui(e),
+                    duration: Duration::default(),
+                };
+                &output_stderr
+            }
+        };
+        self.on_exec_command_end(
+            turn_diff_tracker,
+            &sub_id,
+            &call_id,
+            borrowed,
+            is_apply_patch,
+        )
+        .await;
+
+        result
+    }
 
     /// Helper that emits a BackgroundEvent with the given message. This keeps
     /// the call‑sites terse so adding more diagnostics does not clutter the
@@ -632,7 +688,7 @@ impl AgentTask {
             let event = Event {
                 id: self.sub_id,
                 msg: EventMsg::Error(ErrorEvent {
-                    message: "Turn interrupted".to_string(),
+                    message: " Turn interrupted".to_string(),
                 }),
             };
             let tx_event = self.sess.tx_event.clone();
@@ -810,6 +866,12 @@ async fn submission_loop(
                 let default_shell = shell::default_user_shell().await;
                 sess = Some(Arc::new(Session {
                     client,
+                    tools_config: ToolsConfig::new(
+                        &config.model_family,
+                        approval_policy,
+                        sandbox_policy.clone(),
+                        config.include_plan_tool,
+                    ),
                     tx_event: tx_event.clone(),
                     ctrl_c: Arc::clone(&ctrl_c),
                     user_instructions,
@@ -1204,13 +1266,22 @@ async fn run_turn(
     sub_id: String,
     input: Vec<ResponseItem>,
 ) -> CodexResult<Vec<ProcessedResponseItem>> {
-    let extra_tools = sess.mcp_connection_manager.list_all_tools();
+    let tools = get_openai_tools(
+        &sess.tools_config,
+        Some(sess.mcp_connection_manager.list_all_tools()),
+    );
+
     let prompt = Prompt {
         input,
         user_instructions: sess.user_instructions.clone(),
         store: !sess.disable_response_storage,
-        extra_tools,
+        tools,
         base_instructions_override: sess.base_instructions.clone(),
+        environment_context: Some(EnvironmentContext {
+            cwd: sess.cwd.clone(),
+            approval_policy: sess.approval_policy,
+            sandbox_policy: sess.sandbox_policy.clone(),
+        }),
     };
 
     let mut retries = 0;
@@ -1219,6 +1290,9 @@ async fn run_turn(
             Ok(output) => return Ok(output),
             Err(CodexErr::Interrupted) => return Err(CodexErr::Interrupted),
             Err(CodexErr::EnvVar(var)) => return Err(CodexErr::EnvVar(var)),
+            Err(e @ (CodexErr::UsageLimitReached(_) | CodexErr::UsageNotIncluded)) => {
+                return Err(e);
+            }
             Err(e) => {
                 // Use the configured provider-specific stream retry budget.
                 let max_retries = sess.client.get_provider().stream_max_retries();
@@ -1436,7 +1510,8 @@ async fn run_compact_task(
         input: turn_input,
         user_instructions: None,
         store: !sess.disable_response_storage,
-        extra_tools: HashMap::new(),
+        environment_context: None,
+        tools: Vec::new(),
         base_instructions_override: Some(compact_instructions.clone()),
     };
 
@@ -1580,6 +1655,8 @@ async fn handle_response_item(
                 command: action.command,
                 workdir: action.working_directory,
                 timeout_ms: action.timeout_ms,
+                with_escalated_permissions: None,
+                justification: None,
             };
             let effective_call_id = match (call_id, id) {
                 (Some(call_id), _) => call_id,
@@ -1668,6 +1745,8 @@ fn to_exec_params(params: ShellToolCallParams, sess: &Session) -> ExecParams {
         cwd: sess.resolve_path(params.workdir.clone()),
         timeout_ms: params.timeout_ms,
         env: create_env(&sess.shell_environment_policy),
+        with_escalated_permissions: params.with_escalated_permissions,
+        justification: params.justification,
     }
 }
 
@@ -1693,6 +1772,15 @@ fn parse_container_exec_arguments(
     }
 }
 
+pub struct ExecInvokeArgs<'a> {
+    pub params: ExecParams,
+    pub sandbox_type: SandboxType,
+    pub ctrl_c: Arc<Notify>,
+    pub sandbox_policy: &'a SandboxPolicy,
+    pub codex_linux_sandbox_exe: &'a Option<PathBuf>,
+    pub stdout_stream: Option<StdoutStream>,
+}
+
 fn maybe_run_with_user_profile(params: ExecParams, sess: &Session) -> ExecParams {
     if sess.shell_environment_policy.use_profile {
         let command = sess
@@ -1768,13 +1856,19 @@ async fn handle_container_exec_with_params(
                 cwd: cwd.clone(),
                 timeout_ms: params.timeout_ms,
                 env: HashMap::new(),
+                with_escalated_permissions: params.with_escalated_permissions,
+                justification: params.justification.clone(),
             };
             let safety = if *user_explicitly_approved_this_action {
                 SafetyCheck::AutoApprove {
                     sandbox_type: SandboxType::None,
                 }
             } else {
-                assess_safety_for_untrusted_command(sess.approval_policy, &sess.sandbox_policy)
+                assess_safety_for_untrusted_command(
+                    sess.approval_policy,
+                    &sess.sandbox_policy,
+                    params.with_escalated_permissions.unwrap_or(false),
+                )
             };
             (
                 params,
@@ -1790,6 +1884,7 @@ async fn handle_container_exec_with_params(
                     sess.approval_policy,
                     &sess.sandbox_policy,
                     &state.approved_commands,
+                    params.with_escalated_permissions.unwrap_or(false),
                 )
             };
             let command_for_display = params.command.clone();
@@ -1806,7 +1901,7 @@ async fn handle_container_exec_with_params(
                     call_id.clone(),
                     params.command.clone(),
                     params.cwd.clone(),
-                    None,
+                    params.justification.clone(),
                 )
                 .await;
             match rx_approve.await.unwrap_or_default() {
@@ -1856,23 +1951,26 @@ async fn handle_container_exec_with_params(
             },
         ),
     };
-    sess.on_exec_command_begin(turn_diff_tracker, exec_command_context.clone())
-        .await;
 
     let params = maybe_run_with_user_profile(params, sess);
-    let output_result = process_exec_tool_call(
-        params.clone(),
-        sandbox_type,
-        sess.ctrl_c.clone(),
-        &sess.sandbox_policy,
-        &sess.codex_linux_sandbox_exe,
-        Some(StdoutStream {
-            sub_id: sub_id.clone(),
-            call_id: call_id.clone(),
-            tx_event: sess.tx_event.clone(),
-        }),
-    )
-    .await;
+    let output_result = sess
+        .run_exec_with_events(
+            turn_diff_tracker,
+            exec_command_context.clone(),
+            ExecInvokeArgs {
+                params: params.clone(),
+                sandbox_type,
+                ctrl_c: sess.ctrl_c.clone(),
+                sandbox_policy: &sess.sandbox_policy,
+                codex_linux_sandbox_exe: &sess.codex_linux_sandbox_exe,
+                stdout_stream: Some(StdoutStream {
+                    sub_id: sub_id.clone(),
+                    call_id: call_id.clone(),
+                    tx_event: sess.tx_event.clone(),
+                }),
+            },
+        )
+        .await;
 
     match output_result {
         Ok(output) => {
@@ -1883,24 +1981,14 @@ async fn handle_container_exec_with_params(
                 duration,
             } = &output;
 
-            sess.on_exec_command_end(
-                turn_diff_tracker,
-                &sub_id,
-                &call_id,
-                &output,
-                exec_command_context.apply_patch.is_some(),
-            )
-            .await;
-
             let is_success = *exit_code == 0;
             let content = format_exec_output(
                 if is_success { stdout } else { stderr },
                 *exit_code,
                 *duration,
             );
-
             ResponseInputItem::FunctionCallOutput {
-                call_id,
+                call_id: call_id.clone(),
                 output: FunctionCallOutputPayload {
                     content,
                     success: Some(is_success),
@@ -1918,16 +2006,13 @@ async fn handle_container_exec_with_params(
             )
             .await
         }
-        Err(e) => {
-            // Handle non-sandbox errors
-            ResponseInputItem::FunctionCallOutput {
-                call_id,
-                output: FunctionCallOutputPayload {
-                    content: format!("execution error: {e}"),
-                    success: None,
-                },
-            }
-        }
+        Err(e) => ResponseInputItem::FunctionCallOutput {
+            call_id: call_id.clone(),
+            output: FunctionCallOutputPayload {
+                content: format!("execution error: {e}"),
+                success: None,
+            },
+        },
     }
 }
 
@@ -1942,15 +2027,32 @@ async fn handle_sandbox_error(
     let call_id = exec_command_context.call_id.clone();
     let sub_id = exec_command_context.sub_id.clone();
     let cwd = exec_command_context.cwd.clone();
-    let is_apply_patch = exec_command_context.apply_patch.is_some();
 
-    // Early out if the user never wants to be asked for approval; just return to the model immediately
-    if sess.approval_policy == AskForApproval::Never {
+    // Early out if either the user never wants to be asked for approval, or
+    // we're letting the model manage escalation requests. Otherwise, continue
+    match sess.approval_policy {
+        AskForApproval::Never | AskForApproval::OnRequest => {
+            return ResponseInputItem::FunctionCallOutput {
+                call_id,
+                output: FunctionCallOutputPayload {
+                    content: format!(
+                        "failed in sandbox {sandbox_type:?} with execution error: {error}"
+                    ),
+                    success: Some(false),
+                },
+            };
+        }
+        AskForApproval::UnlessTrusted | AskForApproval::OnFailure => (),
+    }
+
+    // similarly, if the command timed out, we can simply return this failure to the model
+    if matches!(error, SandboxErr::Timeout) {
         return ResponseInputItem::FunctionCallOutput {
             call_id,
             output: FunctionCallOutputPayload {
                 content: format!(
-                    "failed in sandbox {sandbox_type:?} with execution error: {error}"
+                    "command timed out after {} milliseconds",
+                    params.timeout_duration().as_millis()
                 ),
                 success: Some(false),
             },
@@ -1990,24 +2092,26 @@ async fn handle_sandbox_error(
             sess.notify_background_event(&sub_id, "retrying command without sandbox")
                 .await;
 
-            sess.on_exec_command_begin(turn_diff_tracker, exec_command_context)
-                .await;
-
             // This is an escalated retry; the policy will not be
             // examined and the sandbox has been set to `None`.
-            let retry_output_result = process_exec_tool_call(
-                params,
-                SandboxType::None,
-                sess.ctrl_c.clone(),
-                &sess.sandbox_policy,
-                &sess.codex_linux_sandbox_exe,
-                Some(StdoutStream {
-                    sub_id: sub_id.clone(),
-                    call_id: call_id.clone(),
-                    tx_event: sess.tx_event.clone(),
-                }),
-            )
-            .await;
+            let retry_output_result = sess
+                .run_exec_with_events(
+                    turn_diff_tracker,
+                    exec_command_context.clone(),
+                    ExecInvokeArgs {
+                        params,
+                        sandbox_type: SandboxType::None,
+                        ctrl_c: sess.ctrl_c.clone(),
+                        sandbox_policy: &sess.sandbox_policy,
+                        codex_linux_sandbox_exe: &sess.codex_linux_sandbox_exe,
+                        stdout_stream: Some(StdoutStream {
+                            sub_id: sub_id.clone(),
+                            call_id: call_id.clone(),
+                            tx_event: sess.tx_event.clone(),
+                        }),
+                    },
+                )
+                .await;
 
             match retry_output_result {
                 Ok(retry_output) => {
@@ -2018,15 +2122,6 @@ async fn handle_sandbox_error(
                         duration,
                     } = &retry_output;
 
-                    sess.on_exec_command_end(
-                        turn_diff_tracker,
-                        &sub_id,
-                        &call_id,
-                        &retry_output,
-                        is_apply_patch,
-                    )
-                    .await;
-
                     let is_success = *exit_code == 0;
                     let content = format_exec_output(
                         if is_success { stdout } else { stderr },
@@ -2035,23 +2130,20 @@ async fn handle_sandbox_error(
                     );
 
                     ResponseInputItem::FunctionCallOutput {
-                        call_id,
+                        call_id: call_id.clone(),
                         output: FunctionCallOutputPayload {
                             content,
                             success: Some(is_success),
                         },
                     }
                 }
-                Err(e) => {
-                    // Handle retry failure
-                    ResponseInputItem::FunctionCallOutput {
-                        call_id,
-                        output: FunctionCallOutputPayload {
-                            content: format!("retry failed: {e}"),
-                            success: None,
-                        },
-                    }
-                }
+                Err(e) => ResponseInputItem::FunctionCallOutput {
+                    call_id: call_id.clone(),
+                    output: FunctionCallOutputPayload {
+                        content: format!("retry failed: {e}"),
+                        success: None,
+                    },
+                },
             }
         }
         ReviewDecision::Denied | ReviewDecision::Abort => {

codex-rs/core/src/codex_wrapper.rs

@@ -6,7 +6,7 @@ use crate::config::Config;
 use crate::protocol::Event;
 use crate::protocol::EventMsg;
 use crate::util::notify_on_sigint;
-use codex_login::load_auth;
+use codex_login::CodexAuth;
 use tokio::sync::Notify;
 use uuid::Uuid;
 
@@ -26,7 +26,7 @@ pub struct CodexConversation {
 /// that callers can surface the information to the UI.
 pub async fn init_codex(config: Config) -> anyhow::Result<CodexConversation> {
     let ctrl_c = notify_on_sigint();
-    let auth = load_auth(&config.codex_home, true)?;
+    let auth = CodexAuth::from_codex_home(&config.codex_home)?;
     let CodexSpawnOk {
         codex,
         init_id,

codex-rs/core/src/config.rs

@@ -4,12 +4,11 @@ use crate::config_types::McpServerConfig;
 use crate::config_types::ReasoningEffort;
 use crate::config_types::ReasoningSummary;
 use crate::config_types::SandboxMode;
-use crate::config_types::SandboxWorkplaceWrite;
+use crate::config_types::SandboxWorkspaceWrite;
 use crate::config_types::ShellEnvironmentPolicy;
 use crate::config_types::ShellEnvironmentPolicyToml;
 use crate::config_types::Tui;
 use crate::config_types::UriBasedFileOpener;
-use crate::flags::OPENAI_DEFAULT_MODEL;
 use crate::model_family::ModelFamily;
 use crate::model_family::find_family_for_model;
 use crate::model_provider_info::ModelProviderInfo;
@@ -22,13 +21,19 @@ use serde::Deserialize;
 use std::collections::HashMap;
 use std::path::Path;
 use std::path::PathBuf;
+use tempfile::NamedTempFile;
 use toml::Value as TomlValue;
+use toml_edit::DocumentMut;
+
+const OPENAI_DEFAULT_MODEL: &str = "gpt-5";
 
 /// Maximum number of bytes of the documentation that will be embedded. Larger
 /// files are *silently truncated* to this size so we do not take up too much of
 /// the context window.
 pub(crate) const PROJECT_DOC_MAX_BYTES: usize = 32 * 1024; // 32 KiB
 
+const CONFIG_TOML_FILE: &str = "config.toml";
+
 /// Application configuration loaded from disk and merged with overrides.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Config {
@@ -70,7 +75,7 @@ pub struct Config {
     /// who have opted into Zero Data Retention (ZDR).
     pub disable_response_storage: bool,
 
-    /// User-provided instructions from instructions.md.
+    /// User-provided instructions from AGENTS.md.
     pub user_instructions: Option<String>,
 
     /// Base instructions override.
@@ -191,10 +196,28 @@ impl Config {
     }
 }
 
+pub fn load_config_as_toml_with_cli_overrides(
+    codex_home: &Path,
+    cli_overrides: Vec<(String, TomlValue)>,
+) -> std::io::Result<ConfigToml> {
+    let mut root_value = load_config_as_toml(codex_home)?;
+
+    for (path, value) in cli_overrides.into_iter() {
+        apply_toml_override(&mut root_value, &path, value);
+    }
+
+    let cfg: ConfigToml = root_value.try_into().map_err(|e| {
+        tracing::error!("Failed to deserialize overridden config: {e}");
+        std::io::Error::new(std::io::ErrorKind::InvalidData, e)
+    })?;
+
+    Ok(cfg)
+}
+
 /// Read `CODEX_HOME/config.toml` and return it as a generic TOML value. Returns
 /// an empty TOML table when the file does not exist.
-fn load_config_as_toml(codex_home: &Path) -> std::io::Result<TomlValue> {
-    let config_path = codex_home.join("config.toml");
+pub fn load_config_as_toml(codex_home: &Path) -> std::io::Result<TomlValue> {
+    let config_path = codex_home.join(CONFIG_TOML_FILE);
     match std::fs::read_to_string(&config_path) {
         Ok(contents) => match toml::from_str::<TomlValue>(&contents) {
             Ok(val) => Ok(val),
@@ -214,6 +237,35 @@ fn load_config_as_toml(codex_home: &Path) -> std::io::Result<TomlValue> {
     }
 }
 
+/// Patch `CODEX_HOME/config.toml` project state.
+/// Use with caution.
+pub fn set_project_trusted(codex_home: &Path, project_path: &Path) -> anyhow::Result<()> {
+    let config_path = codex_home.join(CONFIG_TOML_FILE);
+    // Parse existing config if present; otherwise start a new document.
+    let mut doc = match std::fs::read_to_string(config_path.clone()) {
+        Ok(s) => s.parse::<DocumentMut>()?,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => DocumentMut::new(),
+        Err(e) => return Err(e.into()),
+    };
+
+    // Mark the project as trusted. toml_edit is very good at handling
+    // missing properties
+    let project_key = project_path.to_string_lossy().to_string();
+    doc["projects"][project_key.as_str()]["trust_level"] = toml_edit::value("trusted");
+
+    // ensure codex_home exists
+    std::fs::create_dir_all(codex_home)?;
+
+    // create a tmp_file
+    let tmp_file = NamedTempFile::new_in(codex_home)?;
+    std::fs::write(tmp_file.path(), doc.to_string())?;
+
+    // atomically move the tmp file into config.toml
+    tmp_file.persist(config_path)?;
+
+    Ok(())
+}
+
 /// Apply a single dotted-path override onto a TOML value.
 fn apply_toml_override(root: &mut TomlValue, path: &str, value: TomlValue) {
     use toml::value::Table;
@@ -282,7 +334,7 @@ pub struct ConfigToml {
     pub sandbox_mode: Option<SandboxMode>,
 
     /// Sandbox configuration to apply if `sandbox` is `WorkspaceWrite`.
-    pub sandbox_workspace_write: Option<SandboxWorkplaceWrite>,
+    pub sandbox_workspace_write: Option<SandboxWorkspaceWrite>,
 
     /// Disable server-side response storage (sends the full conversation
     /// context with every request). Currently necessary for OpenAI customers
@@ -350,6 +402,13 @@ pub struct ConfigToml {
 
     /// The value for the `originator` header included with Responses API requests.
     pub internal_originator: Option<String>,
+
+    pub projects: Option<HashMap<String, ProjectConfig>>,
+}
+
+#[derive(Deserialize, Debug, Clone, PartialEq, Eq)]
+pub struct ProjectConfig {
+    pub trust_level: Option<String>,
 }
 
 impl ConfigToml {
@@ -361,16 +420,52 @@ impl ConfigToml {
         match resolved_sandbox_mode {
             SandboxMode::ReadOnly => SandboxPolicy::new_read_only_policy(),
             SandboxMode::WorkspaceWrite => match self.sandbox_workspace_write.as_ref() {
-                Some(s) => SandboxPolicy::WorkspaceWrite {
-                    writable_roots: s.writable_roots.clone(),
-                    network_access: s.network_access,
-                    include_default_writable_roots: true,
+                Some(SandboxWorkspaceWrite {
+                    writable_roots,
+                    network_access,
+                    exclude_tmpdir_env_var,
+                    exclude_slash_tmp,
+                }) => SandboxPolicy::WorkspaceWrite {
+                    writable_roots: writable_roots.clone(),
+                    network_access: *network_access,
+                    exclude_tmpdir_env_var: *exclude_tmpdir_env_var,
+                    exclude_slash_tmp: *exclude_slash_tmp,
                 },
                 None => SandboxPolicy::new_workspace_write_policy(),
             },
             SandboxMode::DangerFullAccess => SandboxPolicy::DangerFullAccess,
         }
     }
+
+    pub fn is_cwd_trusted(&self, resolved_cwd: &Path) -> bool {
+        let projects = self.projects.clone().unwrap_or_default();
+
+        projects
+            .get(&resolved_cwd.to_string_lossy().to_string())
+            .map(|p| p.trust_level.clone().unwrap_or("".to_string()) == "trusted")
+            .unwrap_or(false)
+    }
+
+    pub fn get_config_profile(
+        &self,
+        override_profile: Option<String>,
+    ) -> Result<ConfigProfile, std::io::Error> {
+        let profile = override_profile.or_else(|| self.profile.clone());
+
+        match profile {
+            Some(key) => {
+                if let Some(profile) = self.profiles.get(key.as_str()) {
+                    return Ok(profile.clone());
+                }
+
+                Err(std::io::Error::new(
+                    std::io::ErrorKind::NotFound,
+                    format!("config profile `{key}` not found"),
+                ))
+            }
+            None => Ok(ConfigProfile::default()),
+        }
+    }
 }
 
 /// Optional overrides for user configuration (e.g., from CLI flags).
@@ -385,6 +480,8 @@ pub struct ConfigOverrides {
     pub codex_linux_sandbox_exe: Option<PathBuf>,
     pub base_instructions: Option<String>,
     pub include_plan_tool: Option<bool>,
+    pub disable_response_storage: Option<bool>,
+    pub show_raw_agent_reasoning: Option<bool>,
 }
 
 impl Config {
@@ -408,6 +505,8 @@ impl Config {
             codex_linux_sandbox_exe,
             base_instructions,
             include_plan_tool,
+            disable_response_storage,
+            show_raw_agent_reasoning,
         } = overrides;
 
         let config_profile = match config_profile_key.as_ref().or(cfg.profile.as_ref()) {
@@ -525,6 +624,7 @@ impl Config {
             disable_response_storage: config_profile
                 .disable_response_storage
                 .or(cfg.disable_response_storage)
+                .or(disable_response_storage)
                 .unwrap_or(false),
             notify: cfg.notify,
             user_instructions,
@@ -539,7 +639,10 @@ impl Config {
             codex_linux_sandbox_exe,
 
             hide_agent_reasoning: cfg.hide_agent_reasoning.unwrap_or(false),
-            show_raw_agent_reasoning: cfg.show_raw_agent_reasoning.unwrap_or(false),
+            show_raw_agent_reasoning: cfg
+                .show_raw_agent_reasoning
+                .or(show_raw_agent_reasoning)
+                .unwrap_or(false),
             model_reasoning_effort: config_profile
                 .model_reasoning_effort
                 .or(cfg.model_reasoning_effort)
@@ -567,7 +670,7 @@ impl Config {
             None => return None,
         };
 
-        p.push("instructions.md");
+        p.push("AGENTS.md");
         std::fs::read_to_string(&p).ok().and_then(|s| {
             let s = s.trim();
             if s.is_empty() {
@@ -737,8 +840,10 @@ sandbox_mode = "workspace-write"
 
 [sandbox_workspace_write]
 writable_roots = [
-    "/tmp",
+    "/my/workspace",
 ]
+exclude_tmpdir_env_var = true
+exclude_slash_tmp = true
 "#;
 
         let sandbox_workspace_write_cfg = toml::from_str::<ConfigToml>(sandbox_workspace_write)
@@ -746,9 +851,10 @@ writable_roots = [
         let sandbox_mode_override = None;
         assert_eq!(
             SandboxPolicy::WorkspaceWrite {
-                writable_roots: vec![PathBuf::from("/tmp")],
+                writable_roots: vec![PathBuf::from("/my/workspace")],
                 network_access: false,
-                include_default_writable_roots: true,
+                exclude_tmpdir_env_var: true,
+                exclude_slash_tmp: true,
             },
             sandbox_workspace_write_cfg.derive_sandbox_policy(sandbox_mode_override)
         );
@@ -834,7 +940,7 @@ disable_response_storage = true
             request_max_retries: Some(4),
             stream_max_retries: Some(10),
             stream_idle_timeout_ms: Some(300_000),
-            requires_auth: false,
+            requires_openai_auth: false,
         };
         let model_provider_map = {
             let mut model_provider_map = built_in_model_providers();

codex-rs/core/src/config_types.rs

@@ -93,11 +93,15 @@ pub enum SandboxMode {
 }
 
 #[derive(Deserialize, Debug, Clone, PartialEq, Default)]
-pub struct SandboxWorkplaceWrite {
+pub struct SandboxWorkspaceWrite {
     #[serde(default)]
     pub writable_roots: Vec<PathBuf>,
     #[serde(default)]
     pub network_access: bool,
+    #[serde(default)]
+    pub exclude_tmpdir_env_var: bool,
+    #[serde(default)]
+    pub exclude_slash_tmp: bool,
 }
 
 #[derive(Deserialize, Debug, Clone, PartialEq, Default)]
@@ -105,10 +109,10 @@ pub struct SandboxWorkplaceWrite {
 pub enum ShellEnvironmentPolicyInherit {
     /// "Core" environment variables for the platform. On UNIX, this would
     /// include HOME, LOGNAME, PATH, SHELL, and USER, among others.
-    #[default]
     Core,
 
     /// Inherits the full environment from the parent process.
+    #[default]
     All,
 
     /// Do not inherit any environment variables from the parent process.
@@ -167,7 +171,8 @@ pub struct ShellEnvironmentPolicy {
 
 impl From<ShellEnvironmentPolicyToml> for ShellEnvironmentPolicy {
     fn from(toml: ShellEnvironmentPolicyToml) -> Self {
-        let inherit = toml.inherit.unwrap_or(ShellEnvironmentPolicyInherit::Core);
+        // Default to inheriting the full environment when not specified.
+        let inherit = toml.inherit.unwrap_or(ShellEnvironmentPolicyInherit::All);
         let ignore_default_excludes = toml.ignore_default_excludes.unwrap_or(false);
         let exclude = toml
             .exclude

codex-rs/core/src/error.rs

@@ -62,6 +62,17 @@ pub enum CodexErr {
     #[error("unexpected status {0}: {1}")]
     UnexpectedStatus(StatusCode, String),
 
+    #[error("{0}")]
+    UsageLimitReached(UsageLimitReachedError),
+
+    #[error(
+        "To use Codex with your ChatGPT plan, upgrade to Plus: https://openai.com/chatgpt/pricing."
+    )]
+    UsageNotIncluded,
+
+    #[error("We're currently experiencing high demand, which may cause temporary errors.")]
+    InternalServerError,
+
     /// Retry limit exceeded.
     #[error("exceeded retry limit, last status: {0}")]
     RetryLimit(StatusCode),
@@ -104,6 +115,30 @@ pub enum CodexErr {
     EnvVar(EnvVarError),
 }
 
+#[derive(Debug)]
+pub struct UsageLimitReachedError {
+    pub plan_type: Option<String>,
+}
+
+impl std::fmt::Display for UsageLimitReachedError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        if let Some(plan_type) = &self.plan_type
+            && plan_type == "plus"
+        {
+            write!(
+                f,
+                "You've hit your usage limit. Upgrade to Pro (https://openai.com/chatgpt/pricing), or wait for limits to reset (every 5h and every week.)."
+            )?;
+        } else {
+            write!(
+                f,
+                "You've hit your usage limit. Limits reset every 5h and every week."
+            )?;
+        }
+        Ok(())
+    }
+}
+
 #[derive(Debug)]
 pub struct EnvVarError {
     /// Name of the environment variable that is missing.
@@ -132,3 +167,46 @@ impl CodexErr {
         (self as &dyn std::any::Any).downcast_ref::<T>()
     }
 }
+
+pub fn get_error_message_ui(e: &CodexErr) -> String {
+    match e {
+        CodexErr::Sandbox(SandboxErr::Denied(_, _, stderr)) => stderr.to_string(),
+        _ => e.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn usage_limit_reached_error_formats_plus_plan() {
+        let err = UsageLimitReachedError {
+            plan_type: Some("plus".to_string()),
+        };
+        assert_eq!(
+            err.to_string(),
+            "You've hit your usage limit. Upgrade to Pro (https://openai.com/chatgpt/pricing), or wait for limits to reset (every 5h and every week.)."
+        );
+    }
+
+    #[test]
+    fn usage_limit_reached_error_formats_default_when_none() {
+        let err = UsageLimitReachedError { plan_type: None };
+        assert_eq!(
+            err.to_string(),
+            "You've hit your usage limit. Limits reset every 5h and every week."
+        );
+    }
+
+    #[test]
+    fn usage_limit_reached_error_formats_default_for_other_plans() {
+        let err = UsageLimitReachedError {
+            plan_type: Some("pro".to_string()),
+        };
+        assert_eq!(
+            err.to_string(),
+            "You've hit your usage limit. Limits reset every 5h and every week."
+        );
+    }
+}

codex-rs/core/src/exec.rs

@@ -49,6 +49,14 @@ pub struct ExecParams {
     pub cwd: PathBuf,
     pub timeout_ms: Option<u64>,
     pub env: HashMap<String, String>,
+    pub with_escalated_permissions: Option<bool>,
+    pub justification: Option<String>,
+}
+
+impl ExecParams {
+    pub fn timeout_duration(&self) -> Duration {
+        Duration::from_millis(self.timeout_ms.unwrap_or(DEFAULT_TIMEOUT_MS))
+    }
 }
 
 #[derive(Clone, Copy, Debug, PartialEq)]
@@ -83,11 +91,9 @@ pub async fn process_exec_tool_call(
     {
         SandboxType::None => exec(params, sandbox_policy, ctrl_c, stdout_stream.clone()).await,
         SandboxType::MacosSeatbelt => {
+            let timeout = params.timeout_duration();
             let ExecParams {
-                command,
-                cwd,
-                timeout_ms,
-                env,
+                command, cwd, env, ..
             } = params;
             let child = spawn_command_under_seatbelt(
                 command,
@@ -97,14 +103,12 @@ pub async fn process_exec_tool_call(
                 env,
             )
             .await?;
-            consume_truncated_output(child, ctrl_c, timeout_ms, stdout_stream.clone()).await
+            consume_truncated_output(child, ctrl_c, timeout, stdout_stream.clone()).await
         }
         SandboxType::LinuxSeccomp => {
+            let timeout = params.timeout_duration();
             let ExecParams {
-                command,
-                cwd,
-                timeout_ms,
-                env,
+                command, cwd, env, ..
             } = params;
 
             let codex_linux_sandbox_exe = codex_linux_sandbox_exe
@@ -120,7 +124,7 @@ pub async fn process_exec_tool_call(
             )
             .await?;
 
-            consume_truncated_output(child, ctrl_c, timeout_ms, stdout_stream).await
+            consume_truncated_output(child, ctrl_c, timeout, stdout_stream).await
         }
     };
     let duration = start.elapsed();
@@ -255,16 +259,16 @@ pub struct ExecToolCallOutput {
 }
 
 async fn exec(
-    ExecParams {
-        command,
-        cwd,
-        timeout_ms,
-        env,
-    }: ExecParams,
+    params: ExecParams,
     sandbox_policy: &SandboxPolicy,
     ctrl_c: Arc<Notify>,
     stdout_stream: Option<StdoutStream>,
 ) -> Result<RawExecToolCallOutput> {
+    let timeout = params.timeout_duration();
+    let ExecParams {
+        command, cwd, env, ..
+    } = params;
+
     let (program, args) = command.split_first().ok_or_else(|| {
         CodexErr::Io(io::Error::new(
             io::ErrorKind::InvalidInput,
@@ -282,7 +286,7 @@ async fn exec(
         env,
     )
     .await?;
-    consume_truncated_output(child, ctrl_c, timeout_ms, stdout_stream).await
+    consume_truncated_output(child, ctrl_c, timeout, stdout_stream).await
 }
 
 /// Consumes the output of a child process, truncating it so it is suitable for
@@ -290,7 +294,7 @@ async fn exec(
 pub(crate) async fn consume_truncated_output(
     mut child: Child,
     ctrl_c: Arc<Notify>,
-    timeout_ms: Option<u64>,
+    timeout: Duration,
     stdout_stream: Option<StdoutStream>,
 ) -> Result<RawExecToolCallOutput> {
     // Both stdout and stderr were configured with `Stdio::piped()`
@@ -324,7 +328,6 @@ pub(crate) async fn consume_truncated_output(
     ));
 
     let interrupted = ctrl_c.notified();
-    let timeout = Duration::from_millis(timeout_ms.unwrap_or(DEFAULT_TIMEOUT_MS));
     let exit_status = tokio::select! {
         result = tokio::time::timeout(timeout, child.wait()) => {
             match result {

codex-rs/core/src/flags.rs

@@ -3,7 +3,6 @@ use std::time::Duration;
 use env_flags::env_flags;
 
 env_flags! {
-    pub OPENAI_DEFAULT_MODEL: &str = "codex-mini-latest";
     pub OPENAI_API_BASE: &str = "https://api.openai.com/v1";
 
     /// Fallback when the provider-specific key is not set.

codex-rs/core/src/git_info.rs

@@ -9,7 +9,7 @@ use tokio::time::timeout;
 /// Timeout for git commands to prevent freezing on large repositories
 const GIT_COMMAND_TIMEOUT: TokioDuration = TokioDuration::from_secs(5);
 
-#[derive(Serialize, Deserialize, Clone)]
+#[derive(Serialize, Deserialize, Clone, Debug)]
 pub struct GitInfo {
     /// Current commit hash (SHA)
     #[serde(skip_serializing_if = "Option::is_none")]

codex-rs/core/src/lib.rs

@@ -28,9 +28,11 @@ mod mcp_connection_manager;
 mod mcp_tool_call;
 mod message_history;
 mod model_provider_info;
+pub use model_provider_info::BUILT_IN_OSS_MODEL_PROVIDER_ID;
 pub use model_provider_info::ModelProviderInfo;
 pub use model_provider_info::WireApi;
 pub use model_provider_info::built_in_model_providers;
+pub use model_provider_info::create_oss_provider_with_base_url;
 pub mod model_family;
 mod models;
 mod openai_model_info;
@@ -46,6 +48,5 @@ pub mod spawn;
 pub mod turn_diff_tracker;
 mod user_notification;
 pub mod util;
-
 pub use apply_patch::CODEX_APPLY_PATCH_ARG1;
 pub use safety::get_platform_sandbox;

codex-rs/core/src/model_family.rs

@@ -85,8 +85,15 @@ pub fn find_family_for_model(slug: &str) -> Option<ModelFamily> {
         )
     } else if slug.starts_with("gpt-4o") {
         simple_model_family!(slug, "gpt-4o")
+    } else if slug.starts_with("gpt-oss") {
+        simple_model_family!(slug, "gpt-oss")
     } else if slug.starts_with("gpt-3.5") {
         simple_model_family!(slug, "gpt-3.5")
+    } else if slug.starts_with("gpt-5") {
+        model_family!(
+            slug, "gpt-5",
+            supports_reasoning_summaries: true,
+        )
     } else {
         None
     }

codex-rs/core/src/model_provider_info.rs

@@ -9,14 +9,13 @@ use codex_login::AuthMode;
 use codex_login::CodexAuth;
 use serde::Deserialize;
 use serde::Serialize;
-use std::borrow::Cow;
 use std::collections::HashMap;
 use std::env::VarError;
 use std::time::Duration;
 
 use crate::error::EnvVarError;
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS: u64 = 300_000;
-const DEFAULT_STREAM_MAX_RETRIES: u64 = 10;
+const DEFAULT_STREAM_MAX_RETRIES: u64 = 5;
 const DEFAULT_REQUEST_MAX_RETRIES: u64 = 4;
 
 /// Wire protocol that the provider speaks. Most third-party services only
@@ -79,7 +78,7 @@ pub struct ModelProviderInfo {
 
     /// Whether this provider requires some form of standard authentication (API key, ChatGPT token).
     #[serde(default)]
-    pub requires_auth: bool,
+    pub requires_openai_auth: bool,
 }
 
 impl ModelProviderInfo {
@@ -87,26 +86,32 @@ impl ModelProviderInfo {
     /// reqwest Client applying:
     ///   • provider-specific headers (static + env based)
     ///   • Bearer auth header when an API key is available.
+    ///   • Auth token for OAuth.
     ///
-    /// When `require_api_key` is true and the provider declares an `env_key`
-    /// but the variable is missing/empty, returns an [`Err`] identical to the
+    /// If the provider declares an `env_key` but the variable is missing/empty, returns an [`Err`] identical to the
     /// one produced by [`ModelProviderInfo::api_key`].
     pub async fn create_request_builder<'a>(
         &'a self,
         client: &'a reqwest::Client,
         auth: &Option<CodexAuth>,
     ) -> crate::error::Result<reqwest::RequestBuilder> {
-        let auth: Cow<'_, Option<CodexAuth>> = if auth.is_some() {
-            Cow::Borrowed(auth)
-        } else {
-            Cow::Owned(self.get_fallback_auth()?)
+        let effective_auth = match self.api_key() {
+            Ok(Some(key)) => Some(CodexAuth::from_api_key(&key)),
+            Ok(None) => auth.clone(),
+            Err(err) => {
+                if auth.is_some() {
+                    auth.clone()
+                } else {
+                    return Err(err);
+                }
+            }
         };
 
-        let url = self.get_full_url(&auth);
+        let url = self.get_full_url(&effective_auth);
 
         let mut builder = client.post(url);
 
-        if let Some(auth) = auth.as_ref() {
+        if let Some(auth) = effective_auth.as_ref() {
             builder = builder.bearer_auth(auth.get_token().await?);
         }
 
@@ -216,68 +221,105 @@ impl ModelProviderInfo {
             .map(Duration::from_millis)
             .unwrap_or(Duration::from_millis(DEFAULT_STREAM_IDLE_TIMEOUT_MS))
     }
-
-    fn get_fallback_auth(&self) -> crate::error::Result<Option<CodexAuth>> {
-        let api_key = self.api_key()?;
-        if let Some(api_key) = api_key {
-            return Ok(Some(CodexAuth::from_api_key(api_key)));
-        }
-        Ok(None)
-    }
 }
 
+const DEFAULT_OLLAMA_PORT: u32 = 11434;
+
+pub const BUILT_IN_OSS_MODEL_PROVIDER_ID: &str = "oss";
+
 /// Built-in default provider list.
 pub fn built_in_model_providers() -> HashMap<String, ModelProviderInfo> {
     use ModelProviderInfo as P;
 
     // We do not want to be in the business of adjucating which third-party
-    // providers are bundled with Codex CLI, so we only include the OpenAI
-    // provider by default. Users are encouraged to add to `model_providers`
-    // in config.toml to add their own providers.
-    [(
-        "openai",
-        P {
-            name: "OpenAI".into(),
-            // Allow users to override the default OpenAI endpoint by
-            // exporting `OPENAI_BASE_URL`. This is useful when pointing
-            // Codex at a proxy, mock server, or Azure-style deployment
-            // without requiring a full TOML override for the built-in
-            // OpenAI provider.
-            base_url: std::env::var("OPENAI_BASE_URL")
-                .ok()
-                .filter(|v| !v.trim().is_empty()),
-            env_key: None,
-            env_key_instructions: None,
-            wire_api: WireApi::Responses,
-            query_params: None,
-            http_headers: Some(
-                [("version".to_string(), env!("CARGO_PKG_VERSION").to_string())]
+    // providers are bundled with Codex CLI, so we only include the OpenAI and
+    // open source ("oss") providers by default. Users are encouraged to add to
+    // `model_providers` in config.toml to add their own providers.
+    [
+        (
+            "openai",
+            P {
+                name: "OpenAI".into(),
+                // Allow users to override the default OpenAI endpoint by
+                // exporting `OPENAI_BASE_URL`. This is useful when pointing
+                // Codex at a proxy, mock server, or Azure-style deployment
+                // without requiring a full TOML override for the built-in
+                // OpenAI provider.
+                base_url: std::env::var("OPENAI_BASE_URL")
+                    .ok()
+                    .filter(|v| !v.trim().is_empty()),
+                env_key: None,
+                env_key_instructions: None,
+                wire_api: WireApi::Responses,
+                query_params: None,
+                http_headers: Some(
+                    [("version".to_string(), env!("CARGO_PKG_VERSION").to_string())]
+                        .into_iter()
+                        .collect(),
+                ),
+                env_http_headers: Some(
+                    [
+                        (
+                            "OpenAI-Organization".to_string(),
+                            "OPENAI_ORGANIZATION".to_string(),
+                        ),
+                        ("OpenAI-Project".to_string(), "OPENAI_PROJECT".to_string()),
+                    ]
                     .into_iter()
                     .collect(),
-            ),
-            env_http_headers: Some(
-                [
-                    (
-                        "OpenAI-Organization".to_string(),
-                        "OPENAI_ORGANIZATION".to_string(),
-                    ),
-                    ("OpenAI-Project".to_string(), "OPENAI_PROJECT".to_string()),
-                ]
-                .into_iter()
-                .collect(),
-            ),
-            // Use global defaults for retry/timeout unless overridden in config.toml.
-            request_max_retries: None,
-            stream_max_retries: None,
-            stream_idle_timeout_ms: None,
-            requires_auth: true,
-        },
-    )]
+                ),
+                // Use global defaults for retry/timeout unless overridden in config.toml.
+                request_max_retries: None,
+                stream_max_retries: None,
+                stream_idle_timeout_ms: None,
+                requires_openai_auth: true,
+            },
+        ),
+        (BUILT_IN_OSS_MODEL_PROVIDER_ID, create_oss_provider()),
+    ]
     .into_iter()
     .map(|(k, v)| (k.to_string(), v))
     .collect()
 }
 
+pub fn create_oss_provider() -> ModelProviderInfo {
+    // These CODEX_OSS_ environment variables are experimental: we may
+    // switch to reading values from config.toml instead.
+    let codex_oss_base_url = match std::env::var("CODEX_OSS_BASE_URL")
+        .ok()
+        .filter(|v| !v.trim().is_empty())
+    {
+        Some(url) => url,
+        None => format!(
+            "http://localhost:{port}/v1",
+            port = std::env::var("CODEX_OSS_PORT")
+                .ok()
+                .filter(|v| !v.trim().is_empty())
+                .and_then(|v| v.parse::<u32>().ok())
+                .unwrap_or(DEFAULT_OLLAMA_PORT)
+        ),
+    };
+
+    create_oss_provider_with_base_url(&codex_oss_base_url)
+}
+
+pub fn create_oss_provider_with_base_url(base_url: &str) -> ModelProviderInfo {
+    ModelProviderInfo {
+        name: "gpt-oss".into(),
+        base_url: Some(base_url.into()),
+        env_key: None,
+        env_key_instructions: None,
+        wire_api: WireApi::Chat,
+        query_params: None,
+        http_headers: None,
+        env_http_headers: None,
+        request_max_retries: None,
+        stream_max_retries: None,
+        stream_idle_timeout_ms: None,
+        requires_openai_auth: false,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     #![allow(clippy::unwrap_used)]
@@ -302,7 +344,7 @@ base_url = "http://localhost:11434/v1"
             request_max_retries: None,
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
@@ -331,7 +373,7 @@ query_params = { api-version = "2025-04-01-preview" }
             request_max_retries: None,
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
@@ -363,7 +405,7 @@ env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" }
             request_max_retries: None,
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();

codex-rs/core/src/models.rs

@@ -191,6 +191,10 @@ pub struct ShellToolCallParams {
     // The wire format uses `timeout`, which has ambiguous units, so we use
     // `timeout_ms` as the field name so it is clear in code.
     pub timeout_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub with_escalated_permissions: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub justification: Option<String>,
 }
 
 #[derive(Debug, Clone, PartialEq)]
@@ -302,6 +306,8 @@ mod tests {
                 command: vec!["ls".to_string(), "-l".to_string()],
                 workdir: Some("/tmp".to_string()),
                 timeout_ms: Some(1000),
+                with_escalated_permissions: None,
+                justification: None,
             },
             params
         );

codex-rs/core/src/openai_model_info.rs

@@ -14,10 +14,19 @@ pub(crate) struct ModelInfo {
     pub(crate) max_output_tokens: u64,
 }
 
-/// Note details such as what a model like gpt-4o is aliased to may be out of
-/// date.
 pub(crate) fn get_model_info(model_family: &ModelFamily) -> Option<ModelInfo> {
     match model_family.slug.as_str() {
+        // OSS models have a 128k shared token pool.
+        // Arbitrarily splitting it: 3/4 input context, 1/4 output.
+        // https://openai.com/index/gpt-oss-model-card/
+        "gpt-oss-20b" => Some(ModelInfo {
+            context_window: 96_000,
+            max_output_tokens: 32_000,
+        }),
+        "gpt-oss-120b" => Some(ModelInfo {
+            context_window: 96_000,
+            max_output_tokens: 32_000,
+        }),
         // https://platform.openai.com/docs/models/o3
         "o3" => Some(ModelInfo {
             context_window: 200_000,
@@ -68,6 +77,11 @@ pub(crate) fn get_model_info(model_family: &ModelFamily) -> Option<ModelInfo> {
             max_output_tokens: 4_096,
         }),
 
+        "gpt-5" => Some(ModelInfo {
+            context_window: 200_000,
+            max_output_tokens: 100_000,
+        }),
+
         _ => None,
     }
 }

codex-rs/core/src/openai_tools.rs

@@ -1,22 +1,28 @@
+use serde::Deserialize;
 use serde::Serialize;
 use serde_json::json;
 use std::collections::BTreeMap;
+use std::collections::HashMap;
 
-use crate::client_common::Prompt;
 use crate::model_family::ModelFamily;
 use crate::plan_tool::PLAN_TOOL;
+use crate::protocol::AskForApproval;
+use crate::protocol::SandboxPolicy;
 
-#[derive(Debug, Clone, Serialize)]
-pub(crate) struct ResponsesApiTool {
-    pub(crate) name: &'static str,
-    pub(crate) description: &'static str,
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct ResponsesApiTool {
+    pub(crate) name: String,
+    pub(crate) description: String,
+    /// TODO: Validation. When strict is set to true, the JSON schema,
+    /// `required` and `additional_properties` must be present. All fields in
+    /// `properties` must be present in `required`.
     pub(crate) strict: bool,
     pub(crate) parameters: JsonSchema,
 }
 
 /// When serialized as JSON, this produces a valid "Tool" in the OpenAI
 /// Responses API.
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, PartialEq)]
 #[serde(tag = "type")]
 pub(crate) enum OpenAiTool {
     #[serde(rename = "function")]
@@ -25,20 +31,75 @@ pub(crate) enum OpenAiTool {
     LocalShell {},
 }
 
+#[derive(Debug, Clone)]
+pub enum ConfigShellToolType {
+    DefaultShell,
+    ShellWithRequest { sandbox_policy: SandboxPolicy },
+    LocalShell,
+}
+
+#[derive(Debug, Clone)]
+pub struct ToolsConfig {
+    pub shell_type: ConfigShellToolType,
+    pub plan_tool: bool,
+}
+
+impl ToolsConfig {
+    pub fn new(
+        model_family: &ModelFamily,
+        approval_policy: AskForApproval,
+        sandbox_policy: SandboxPolicy,
+        include_plan_tool: bool,
+    ) -> Self {
+        let mut shell_type = if model_family.uses_local_shell_tool {
+            ConfigShellToolType::LocalShell
+        } else {
+            ConfigShellToolType::DefaultShell
+        };
+        if matches!(approval_policy, AskForApproval::OnRequest) {
+            shell_type = ConfigShellToolType::ShellWithRequest {
+                sandbox_policy: sandbox_policy.clone(),
+            }
+        }
+
+        Self {
+            shell_type,
+            plan_tool: include_plan_tool,
+        }
+    }
+}
+
 /// Generic JSON‑Schema subset needed for our tool definitions
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(tag = "type", rename_all = "lowercase")]
 pub(crate) enum JsonSchema {
-    String,
-    Number,
+    Boolean {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        description: Option<String>,
+    },
+    String {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        description: Option<String>,
+    },
+    Number {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        description: Option<String>,
+    },
     Array {
         items: Box<JsonSchema>,
+
+        #[serde(skip_serializing_if = "Option::is_none")]
+        description: Option<String>,
     },
     Object {
         properties: BTreeMap<String, JsonSchema>,
-        required: &'static [&'static str],
-        #[serde(rename = "additionalProperties")]
-        additional_properties: bool,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        required: Option<Vec<String>>,
+        #[serde(
+            rename = "additionalProperties",
+            skip_serializing_if = "Option::is_none"
+        )]
+        additional_properties: Option<bool>,
     },
 }
 
@@ -47,20 +108,126 @@ fn create_shell_tool() -> OpenAiTool {
     properties.insert(
         "command".to_string(),
         JsonSchema::Array {
-            items: Box::new(JsonSchema::String),
+            items: Box::new(JsonSchema::String { description: None }),
+            description: None,
         },
     );
-    properties.insert("workdir".to_string(), JsonSchema::String);
-    properties.insert("timeout".to_string(), JsonSchema::Number);
+    properties.insert(
+        "workdir".to_string(),
+        JsonSchema::String { description: None },
+    );
+    properties.insert(
+        "timeout".to_string(),
+        JsonSchema::Number { description: None },
+    );
 
     OpenAiTool::Function(ResponsesApiTool {
-        name: "shell",
-        description: "Runs a shell command and returns its output",
+        name: "shell".to_string(),
+        description: "Runs a shell command and returns its output".to_string(),
         strict: false,
         parameters: JsonSchema::Object {
             properties,
-            required: &["command"],
-            additional_properties: false,
+            required: Some(vec!["command".to_string()]),
+            additional_properties: Some(false),
+        },
+    })
+}
+
+fn create_shell_tool_for_sandbox(sandbox_policy: &SandboxPolicy) -> OpenAiTool {
+    let mut properties = BTreeMap::new();
+    properties.insert(
+        "command".to_string(),
+        JsonSchema::Array {
+            items: Box::new(JsonSchema::String { description: None }),
+            description: Some("The command to execute".to_string()),
+        },
+    );
+    properties.insert(
+        "workdir".to_string(),
+        JsonSchema::String {
+            description: Some("The working directory to execute the command in".to_string()),
+        },
+    );
+    properties.insert(
+        "timeout".to_string(),
+        JsonSchema::Number {
+            description: Some("The timeout for the command in milliseconds".to_string()),
+        },
+    );
+
+    if matches!(sandbox_policy, SandboxPolicy::WorkspaceWrite { .. }) {
+        properties.insert(
+        "with_escalated_permissions".to_string(),
+        JsonSchema::Boolean {
+            description: Some("Whether to request escalated permissions. Set to true if command needs to be run without sandbox restrictions".to_string()),
+        },
+    );
+        properties.insert(
+        "justification".to_string(),
+        JsonSchema::String {
+            description: Some("Only set if ask_for_escalated_permissions is true. 1-sentence explanation of why we want to run this command.".to_string()),
+        },
+    );
+    }
+
+    let description = match sandbox_policy {
+        SandboxPolicy::WorkspaceWrite {
+            network_access,
+            ..
+        } => {
+            format!(
+                r#"
+The shell tool is used to execute shell commands.
+- When invoking the shell tool, your call will be running in a landlock sandbox, and some shell commands will require escalated privileges:
+  - Types of actions that require escalated privileges:
+    - Reading files outside the current directory
+    - Writing files outside the current directory, and protected folders like .git or .env{}
+  - Examples of commands that require escalated privileges:
+    - git commit
+    - npm install or pnpm install
+    - cargo build
+    - cargo test
+- When invoking a command that will require escalated privileges:
+  - Provide the with_escalated_permissions parameter with the boolean value true
+  - Include a short, 1 sentence explanation for why we need to run with_escalated_permissions in the justification parameter."#,
+                if !network_access {
+                    "\n  - Commands that require network access\n"
+                } else {
+                    ""
+                }
+            )
+        }
+        SandboxPolicy::DangerFullAccess => {
+            "Runs a shell command and returns its output.".to_string()
+        }
+        SandboxPolicy::ReadOnly => {
+            r#"
+The shell tool is used to execute shell commands.
+- When invoking the shell tool, your call will be running in a landlock sandbox, and some shell commands (including apply_patch) will require escalated permissions:
+  - Types of actions that require escalated privileges:
+    - Reading files outside the current directory
+    - Writing files
+    - Applying patches
+  - Examples of commands that require escalated privileges:
+    - apply_patch
+    - git commit
+    - npm install or pnpm install
+    - cargo build
+    - cargo test
+- When invoking a command that will require escalated privileges:
+  - Provide the with_escalated_permissions parameter with the boolean value true
+  - Include a short, 1 sentence explanation for why we need to run with_escalated_permissions in the justification parameter"#.to_string()
+        }
+    };
+
+    OpenAiTool::Function(ResponsesApiTool {
+        name: "shell".to_string(),
+        description,
+        strict: false,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["command".to_string()]),
+            additional_properties: Some(false),
         },
     })
 }
@@ -69,31 +236,13 @@ fn create_shell_tool() -> OpenAiTool {
 /// Responses API:
 /// https://platform.openai.com/docs/guides/function-calling?api-mode=responses
 pub(crate) fn create_tools_json_for_responses_api(
-    prompt: &Prompt,
-    model_family: &ModelFamily,
-    include_plan_tool: bool,
+    tools: &Vec<OpenAiTool>,
 ) -> crate::error::Result<Vec<serde_json::Value>> {
-    // Assemble tool list: built-in tools + any extra tools from the prompt.
-    let mut openai_tools = vec![create_shell_tool()];
-    if model_family.uses_local_shell_tool {
-        openai_tools.push(OpenAiTool::LocalShell {});
-    }
+    let mut tools_json = Vec::new();
 
-    let mut tools_json = Vec::with_capacity(openai_tools.len() + prompt.extra_tools.len() + 1);
-    for tool in openai_tools.iter() {
+    for tool in tools {
         tools_json.push(serde_json::to_value(tool)?);
     }
-    tools_json.extend(
-        prompt
-            .extra_tools
-            .clone()
-            .into_iter()
-            .map(|(name, tool)| mcp_tool_to_openai_tool(name, tool)),
-    );
-
-    if include_plan_tool {
-        tools_json.push(serde_json::to_value(PLAN_TOOL.clone())?);
-    }
 
     Ok(tools_json)
 }
@@ -102,14 +251,11 @@ pub(crate) fn create_tools_json_for_responses_api(
 /// Chat Completions API:
 /// https://platform.openai.com/docs/guides/function-calling?api-mode=chat
 pub(crate) fn create_tools_json_for_chat_completions_api(
-    prompt: &Prompt,
-    model_family: &ModelFamily,
-    include_plan_tool: bool,
+    tools: &Vec<OpenAiTool>,
 ) -> crate::error::Result<Vec<serde_json::Value>> {
     // We start with the JSON for the Responses API and than rewrite it to match
     // the chat completions tool call format.
-    let responses_api_tools_json =
-        create_tools_json_for_responses_api(prompt, model_family, include_plan_tool)?;
+    let responses_api_tools_json = create_tools_json_for_responses_api(tools)?;
     let tools_json = responses_api_tools_json
         .into_iter()
         .filter_map(|mut tool| {
@@ -132,10 +278,10 @@ pub(crate) fn create_tools_json_for_chat_completions_api(
     Ok(tools_json)
 }
 
-fn mcp_tool_to_openai_tool(
+pub(crate) fn mcp_tool_to_openai_tool(
     fully_qualified_name: String,
     tool: mcp_types::Tool,
-) -> serde_json::Value {
+) -> Result<ResponsesApiTool, serde_json::Error> {
     let mcp_types::Tool {
         description,
         mut input_schema,
@@ -150,12 +296,205 @@ fn mcp_tool_to_openai_tool(
         input_schema.properties = Some(serde_json::Value::Object(serde_json::Map::new()));
     }
 
-    // TODO(mbolin): Change the contract of this function to return
-    // ResponsesApiTool.
-    json!({
-        "name": fully_qualified_name,
-        "description": description,
-        "parameters": input_schema,
-        "type": "function",
+    let serialized_input_schema = serde_json::to_value(input_schema)?;
+    let input_schema = serde_json::from_value::<JsonSchema>(serialized_input_schema)?;
+
+    Ok(ResponsesApiTool {
+        name: fully_qualified_name,
+        description: description.unwrap_or_default(),
+        strict: false,
+        parameters: input_schema,
     })
 }
+
+/// Returns a list of OpenAiTools based on the provided config and MCP tools.
+/// Note that the keys of mcp_tools should be fully qualified names. See
+/// [`McpConnectionManager`] for more details.
+pub(crate) fn get_openai_tools(
+    config: &ToolsConfig,
+    mcp_tools: Option<HashMap<String, mcp_types::Tool>>,
+) -> Vec<OpenAiTool> {
+    let mut tools: Vec<OpenAiTool> = Vec::new();
+
+    match &config.shell_type {
+        ConfigShellToolType::DefaultShell => {
+            tools.push(create_shell_tool());
+        }
+        ConfigShellToolType::ShellWithRequest { sandbox_policy } => {
+            tools.push(create_shell_tool_for_sandbox(sandbox_policy));
+        }
+        ConfigShellToolType::LocalShell => {
+            tools.push(OpenAiTool::LocalShell {});
+        }
+    }
+
+    if config.plan_tool {
+        tools.push(PLAN_TOOL.clone());
+    }
+
+    if let Some(mcp_tools) = mcp_tools {
+        for (name, tool) in mcp_tools {
+            match mcp_tool_to_openai_tool(name.clone(), tool.clone()) {
+                Ok(converted_tool) => tools.push(OpenAiTool::Function(converted_tool)),
+                Err(e) => {
+                    tracing::error!("Failed to convert {name:?} MCP tool to OpenAI tool: {e:?}");
+                }
+            }
+        }
+    }
+
+    tools
+}
+
+#[cfg(test)]
+#[allow(clippy::expect_used)]
+mod tests {
+    use crate::model_family::find_family_for_model;
+    use mcp_types::ToolInputSchema;
+
+    use super::*;
+
+    fn assert_eq_tool_names(tools: &[OpenAiTool], expected_names: &[&str]) {
+        let tool_names = tools
+            .iter()
+            .map(|tool| match tool {
+                OpenAiTool::Function(ResponsesApiTool { name, .. }) => name,
+                OpenAiTool::LocalShell {} => "local_shell",
+            })
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            tool_names.len(),
+            expected_names.len(),
+            "tool_name mismatch, {tool_names:?}, {expected_names:?}",
+        );
+        for (name, expected_name) in tool_names.iter().zip(expected_names.iter()) {
+            assert_eq!(
+                name, expected_name,
+                "tool_name mismatch, {name:?}, {expected_name:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn test_get_openai_tools() {
+        let model_family = find_family_for_model("codex-mini-latest")
+            .expect("codex-mini-latest should be a valid model family");
+        let config = ToolsConfig::new(
+            &model_family,
+            AskForApproval::Never,
+            SandboxPolicy::ReadOnly,
+            true,
+        );
+        let tools = get_openai_tools(&config, Some(HashMap::new()));
+
+        assert_eq_tool_names(&tools, &["local_shell", "update_plan"]);
+    }
+
+    #[test]
+    fn test_get_openai_tools_default_shell() {
+        let model_family = find_family_for_model("o3").expect("o3 should be a valid model family");
+        let config = ToolsConfig::new(
+            &model_family,
+            AskForApproval::Never,
+            SandboxPolicy::ReadOnly,
+            true,
+        );
+        let tools = get_openai_tools(&config, Some(HashMap::new()));
+
+        assert_eq_tool_names(&tools, &["shell", "update_plan"]);
+    }
+
+    #[test]
+    fn test_get_openai_tools_mcp_tools() {
+        let model_family = find_family_for_model("o3").expect("o3 should be a valid model family");
+        let config = ToolsConfig::new(
+            &model_family,
+            AskForApproval::Never,
+            SandboxPolicy::ReadOnly,
+            false,
+        );
+        let tools = get_openai_tools(
+            &config,
+            Some(HashMap::from([(
+                "test_server/do_something_cool".to_string(),
+                mcp_types::Tool {
+                    name: "do_something_cool".to_string(),
+                    input_schema: ToolInputSchema {
+                        properties: Some(serde_json::json!({
+                            "string_argument": {
+                                "type": "string",
+                            },
+                            "number_argument": {
+                                "type": "number",
+                            },
+                            "object_argument": {
+                                "type": "object",
+                                "properties": {
+                                    "string_property": { "type": "string" },
+                                    "number_property": { "type": "number" },
+                                },
+                                "required": [
+                                    "string_property",
+                                    "number_property"
+                                ],
+                                "additionalProperties": Some(false),
+                            },
+                        })),
+                        required: None,
+                        r#type: "object".to_string(),
+                    },
+                    output_schema: None,
+                    title: None,
+                    annotations: None,
+                    description: Some("Do something cool".to_string()),
+                },
+            )])),
+        );
+
+        assert_eq_tool_names(&tools, &["shell", "test_server/do_something_cool"]);
+
+        assert_eq!(
+            tools[1],
+            OpenAiTool::Function(ResponsesApiTool {
+                name: "test_server/do_something_cool".to_string(),
+                parameters: JsonSchema::Object {
+                    properties: BTreeMap::from([
+                        (
+                            "string_argument".to_string(),
+                            JsonSchema::String { description: None }
+                        ),
+                        (
+                            "number_argument".to_string(),
+                            JsonSchema::Number { description: None }
+                        ),
+                        (
+                            "object_argument".to_string(),
+                            JsonSchema::Object {
+                                properties: BTreeMap::from([
+                                    (
+                                        "string_property".to_string(),
+                                        JsonSchema::String { description: None }
+                                    ),
+                                    (
+                                        "number_property".to_string(),
+                                        JsonSchema::Number { description: None }
+                                    ),
+                                ]),
+                                required: Some(vec![
+                                    "string_property".to_string(),
+                                    "number_property".to_string(),
+                                ]),
+                                additional_properties: Some(false),
+                            },
+                        ),
+                    ]),
+                    required: None,
+                    additional_properties: None,
+                },
+                description: "Do something cool".to_string(),
+                strict: false,
+            })
+        );
+    }
+}

codex-rs/core/src/plan_tool.rs

@@ -39,23 +39,30 @@ pub struct UpdatePlanArgs {
 
 pub(crate) static PLAN_TOOL: LazyLock<OpenAiTool> = LazyLock::new(|| {
     let mut plan_item_props = BTreeMap::new();
-    plan_item_props.insert("step".to_string(), JsonSchema::String);
-    plan_item_props.insert("status".to_string(), JsonSchema::String);
+    plan_item_props.insert("step".to_string(), JsonSchema::String { description: None });
+    plan_item_props.insert(
+        "status".to_string(),
+        JsonSchema::String { description: None },
+    );
 
     let plan_items_schema = JsonSchema::Array {
+        description: Some("The list of steps".to_string()),
         items: Box::new(JsonSchema::Object {
             properties: plan_item_props,
-            required: &["step", "status"],
-            additional_properties: false,
+            required: Some(vec!["step".to_string(), "status".to_string()]),
+            additional_properties: Some(false),
         }),
     };
 
     let mut properties = BTreeMap::new();
-    properties.insert("explanation".to_string(), JsonSchema::String);
+    properties.insert(
+        "explanation".to_string(),
+        JsonSchema::String { description: None },
+    );
     properties.insert("plan".to_string(), plan_items_schema);
 
     OpenAiTool::Function(ResponsesApiTool {
-        name: "update_plan",
+        name: "update_plan".to_string(),
         description: r#"Use the update_plan tool to keep the user updated on the current plan for the task.
 After understanding the user's task, call the update_plan tool with an initial plan. An example of a plan:
 1. Explore the codebase to find relevant files (status: in_progress)
@@ -66,12 +73,12 @@ Until all the steps are finished, there should always be exactly one in_progress
 Call the update_plan tool whenever you finish a step, marking the completed step as `completed` and marking the next step as `in_progress`.
 Before running a command, consider whether or not you have completed the previous step, and make sure to mark it as completed before moving on to the next step.
 Sometimes, you may need to change plans in the middle of a task: call `update_plan` with the updated plan and make sure to provide an `explanation` of the rationale when doing so.
-When all steps are completed, call update_plan one last time with all steps marked as `completed`."#,
+When all steps are completed, call update_plan one last time with all steps marked as `completed`."#.to_string(),
         strict: false,
         parameters: JsonSchema::Object {
             properties,
-            required: &["plan"],
-            additional_properties: false,
+            required: Some(vec!["plan".to_string()]),
+            additional_properties: Some(false),
         },
     })
 });

codex-rs/core/src/protocol.rs

@@ -139,7 +139,6 @@ pub enum AskForApproval {
     /// Under this policy, only "known safe" commands—as determined by
     /// `is_safe_command()`—that **only read files** are auto‑approved.
     /// Everything else will ask the user to approve.
-    #[default]
     #[serde(rename = "untrusted")]
     #[strum(serialize = "untrusted")]
     UnlessTrusted,
@@ -150,13 +149,18 @@ pub enum AskForApproval {
     /// the user to approve execution without a sandbox.
     OnFailure,
 
+    /// The model decides when to ask the user for approval.
+    #[default]
+    OnRequest,
+
     /// Never ask the user to approve commands. Failures are immediately returned
     /// to the model, and never escalated to the user for approval.
     Never,
 }
 
 /// Determines execution restrictions for model shell commands.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Display)]
+#[strum(serialize_all = "kebab-case")]
 #[serde(tag = "mode", rename_all = "kebab-case")]
 pub enum SandboxPolicy {
     /// No restrictions whatsoever. Use with caution.
@@ -181,11 +185,16 @@ pub enum SandboxPolicy {
         #[serde(default)]
         network_access: bool,
 
-        /// When set to `true`, will include defaults like the current working
-        /// directory and TMPDIR (on macOS). When `false`, only `writable_roots`
-        /// are used. (Mainly used for testing.)
-        #[serde(default = "default_true")]
-        include_default_writable_roots: bool,
+        /// When set to `true`, will NOT include the per-user `TMPDIR`
+        /// environment variable among the default writable roots. Defaults to
+        /// `false`.
+        #[serde(default)]
+        exclude_tmpdir_env_var: bool,
+
+        /// When set to `true`, will NOT include the `/tmp` among the default
+        /// writable roots on UNIX. Defaults to `false`.
+        #[serde(default)]
+        exclude_slash_tmp: bool,
     },
 }
 
@@ -199,10 +208,6 @@ pub struct WritableRoot {
     pub read_only_subpaths: Vec<PathBuf>,
 }
 
-fn default_true() -> bool {
-    true
-}
-
 impl FromStr for SandboxPolicy {
     type Err = serde_json::Error;
 
@@ -224,7 +229,8 @@ impl SandboxPolicy {
         SandboxPolicy::WorkspaceWrite {
             writable_roots: vec![],
             network_access: false,
-            include_default_writable_roots: true,
+            exclude_tmpdir_env_var: false,
+            exclude_slash_tmp: false,
         }
     }
 
@@ -259,27 +265,40 @@ impl SandboxPolicy {
             SandboxPolicy::ReadOnly => Vec::new(),
             SandboxPolicy::WorkspaceWrite {
                 writable_roots,
-                include_default_writable_roots,
-                ..
+                exclude_tmpdir_env_var,
+                exclude_slash_tmp,
+                network_access: _,
             } => {
                 // Start from explicitly configured writable roots.
                 let mut roots: Vec<PathBuf> = writable_roots.clone();
 
-                // Optionally include defaults (cwd and TMPDIR on macOS).
-                if *include_default_writable_roots {
-                    roots.push(cwd.to_path_buf());
+                // Always include defaults: cwd, /tmp (if present on Unix), and
+                // on macOS, the per-user TMPDIR unless explicitly excluded.
+                roots.push(cwd.to_path_buf());
 
-                    // Also include the per-user tmp dir on macOS.
-                    // Note this is added dynamically rather than storing it in
-                    // `writable_roots` because `writable_roots` contains only static
-                    // values deserialized from the config file.
-                    if cfg!(target_os = "macos") {
-                        if let Some(tmpdir) = std::env::var_os("TMPDIR") {
-                            roots.push(PathBuf::from(tmpdir));
-                        }
+                // Include /tmp on Unix unless explicitly excluded.
+                if cfg!(unix) && !exclude_slash_tmp {
+                    let slash_tmp = PathBuf::from("/tmp");
+                    if slash_tmp.is_dir() {
+                        roots.push(slash_tmp);
                     }
                 }
 
+                // Include $TMPDIR unless explicitly excluded. On macOS, TMPDIR
+                // is per-user, so writes to TMPDIR should not be readable by
+                // other users on the system.
+                //
+                // By comparison, TMPDIR is not guaranteed to be defined on
+                // Linux or Windows, but supporting it here gives users a way to
+                // provide the model with their own temporary directory without
+                // having to hardcode it in the config.
+                if !exclude_tmpdir_env_var
+                    && let Some(tmpdir) = std::env::var_os("TMPDIR")
+                    && !tmpdir.is_empty()
+                {
+                    roots.push(PathBuf::from(tmpdir));
+                }
+
                 // For each root, compute subpaths that should remain read-only.
                 roots
                     .into_iter()
@@ -425,6 +444,34 @@ pub struct TokenUsage {
     pub total_tokens: u64,
 }
 
+impl TokenUsage {
+    pub fn is_zero(&self) -> bool {
+        self.total_tokens == 0
+    }
+
+    pub fn cached_input(&self) -> u64 {
+        self.cached_input_tokens.unwrap_or(0)
+    }
+
+    pub fn non_cached_input(&self) -> u64 {
+        self.input_tokens.saturating_sub(self.cached_input())
+    }
+
+    /// Primary count for display as a single absolute value: non-cached input + output.
+    pub fn blended_total(&self) -> u64 {
+        self.non_cached_input() + self.output_tokens
+    }
+
+    /// For estimating what % of the model's context window is used, we need to account
+    /// for reasoning output tokens from prior turns being dropped from the context window.
+    /// We approximate this here by subtracting reasoning output tokens from the total.
+    /// This will be off for the current turn and pending function calls.
+    pub fn tokens_in_context_window(&self) -> u64 {
+        self.total_tokens
+            .saturating_sub(self.reasoning_output_tokens.unwrap_or(0))
+    }
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct FinalOutput {
     pub token_usage: TokenUsage,
@@ -438,17 +485,20 @@ impl From<TokenUsage> for FinalOutput {
 
 impl fmt::Display for FinalOutput {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let u = &self.token_usage;
+        let token_usage = &self.token_usage;
         write!(
             f,
             "Token usage: total={} input={}{} output={}{}",
-            u.total_tokens,
-            u.input_tokens,
-            u.cached_input_tokens
-                .map(|c| format!(" (cached {c})"))
-                .unwrap_or_default(),
-            u.output_tokens,
-            u.reasoning_output_tokens
+            token_usage.blended_total(),
+            token_usage.non_cached_input(),
+            if token_usage.cached_input() > 0 {
+                format!(" (+ {} cached)", token_usage.cached_input())
+            } else {
+                String::new()
+            },
+            token_usage.output_tokens,
+            token_usage
+                .reasoning_output_tokens
                 .map(|r| format!(" (reasoning {r})"))
                 .unwrap_or_default()
         )

codex-rs/core/src/safety.rs

@@ -11,7 +11,7 @@ use crate::is_safe_command::is_known_safe_command;
 use crate::protocol::AskForApproval;
 use crate::protocol::SandboxPolicy;
 
-#[derive(Debug)]
+#[derive(Debug, PartialEq)]
 pub enum SafetyCheck {
     AutoApprove { sandbox_type: SandboxType },
     AskUser,
@@ -31,7 +31,7 @@ pub fn assess_patch_safety(
     }
 
     match policy {
-        AskForApproval::OnFailure | AskForApproval::Never => {
+        AskForApproval::OnFailure | AskForApproval::Never | AskForApproval::OnRequest => {
             // Continue to see if this can be auto-approved.
         }
         // TODO(ragona): I'm not sure this is actually correct? I believe in this case
@@ -76,6 +76,7 @@ pub fn assess_command_safety(
     approval_policy: AskForApproval,
     sandbox_policy: &SandboxPolicy,
     approved: &HashSet<Vec<String>>,
+    with_escalated_permissions: bool,
 ) -> SafetyCheck {
     // A command is "trusted" because either:
     // - it belongs to a set of commands we consider "safe" by default, or
@@ -96,12 +97,13 @@ pub fn assess_command_safety(
         };
     }
 
-    assess_safety_for_untrusted_command(approval_policy, sandbox_policy)
+    assess_safety_for_untrusted_command(approval_policy, sandbox_policy, with_escalated_permissions)
 }
 
 pub(crate) fn assess_safety_for_untrusted_command(
     approval_policy: AskForApproval,
     sandbox_policy: &SandboxPolicy,
+    with_escalated_permissions: bool,
 ) -> SafetyCheck {
     use AskForApproval::*;
     use SandboxPolicy::*;
@@ -113,9 +115,23 @@ pub(crate) fn assess_safety_for_untrusted_command(
             // commands.
             SafetyCheck::AskUser
         }
-        (OnFailure, DangerFullAccess) | (Never, DangerFullAccess) => SafetyCheck::AutoApprove {
+        (OnFailure, DangerFullAccess)
+        | (Never, DangerFullAccess)
+        | (OnRequest, DangerFullAccess) => SafetyCheck::AutoApprove {
             sandbox_type: SandboxType::None,
         },
+        (OnRequest, ReadOnly) | (OnRequest, WorkspaceWrite { .. }) => {
+            if with_escalated_permissions {
+                SafetyCheck::AskUser
+            } else {
+                match get_platform_sandbox() {
+                    Some(sandbox_type) => SafetyCheck::AutoApprove { sandbox_type },
+                    // Fall back to asking since the command is untrusted and
+                    // we do not have a sandbox available
+                    None => SafetyCheck::AskUser,
+                }
+            }
+        }
         (Never, ReadOnly)
         | (Never, WorkspaceWrite { .. })
         | (OnFailure, ReadOnly)
@@ -264,4 +280,47 @@ mod tests {
             &cwd,
         ))
     }
+
+    #[test]
+    fn test_request_escalated_privileges() {
+        // Should not be a trusted command
+        let command = vec!["git commit".to_string()];
+        let approval_policy = AskForApproval::OnRequest;
+        let sandbox_policy = SandboxPolicy::ReadOnly;
+        let approved: HashSet<Vec<String>> = HashSet::new();
+        let request_escalated_privileges = true;
+
+        let safety_check = assess_command_safety(
+            &command,
+            approval_policy,
+            &sandbox_policy,
+            &approved,
+            request_escalated_privileges,
+        );
+
+        assert_eq!(safety_check, SafetyCheck::AskUser);
+    }
+
+    #[test]
+    fn test_request_escalated_privileges_no_sandbox_fallback() {
+        let command = vec!["git".to_string(), "commit".to_string()];
+        let approval_policy = AskForApproval::OnRequest;
+        let sandbox_policy = SandboxPolicy::ReadOnly;
+        let approved: HashSet<Vec<String>> = HashSet::new();
+        let request_escalated_privileges = false;
+
+        let safety_check = assess_command_safety(
+            &command,
+            approval_policy,
+            &sandbox_policy,
+            &approved,
+            request_escalated_privileges,
+        );
+
+        let expected = match get_platform_sandbox() {
+            Some(sandbox_type) => SafetyCheck::AutoApprove { sandbox_type },
+            None => SafetyCheck::AskUser,
+        };
+        assert_eq!(safety_check, expected);
+    }
 }

codex-rs/core/src/seatbelt.rs

@@ -134,6 +134,11 @@ mod tests {
 
     #[test]
     fn create_seatbelt_args_with_read_only_git_subpath() {
+        if cfg!(target_os = "windows") {
+            // /tmp does not exist on Windows, so skip this test.
+            return;
+        }
+
         // Create a temporary workspace with two writable roots: one containing
         // a top-level .git directory and one without it.
         let tmp = TempDir::new().expect("tempdir");
@@ -144,19 +149,21 @@ mod tests {
             root_with_git_git_canon,
             root_without_git_canon,
         } = populate_tmpdir(tmp.path());
+        let cwd = tmp.path().join("cwd");
 
         // Build a policy that only includes the two test roots as writable and
-        // does not automatically include defaults like cwd or TMPDIR.
+        // does not automatically include defaults TMPDIR or /tmp.
         let policy = SandboxPolicy::WorkspaceWrite {
             writable_roots: vec![root_with_git.clone(), root_without_git.clone()],
             network_access: false,
-            include_default_writable_roots: false,
+            exclude_tmpdir_env_var: true,
+            exclude_slash_tmp: true,
         };
 
         let args = create_seatbelt_command_args(
             vec!["/bin/echo".to_string(), "hello".to_string()],
             &policy,
-            tmp.path(),
+            &cwd,
         );
 
         // Build the expected policy text using a raw string for readability.
@@ -169,12 +176,12 @@ mod tests {
 ; allow read-only file operations
 (allow file-read*)
 (allow file-write*
-(require-all (subpath (param "WRITABLE_ROOT_0")) (require-not (subpath (param "WRITABLE_ROOT_0_RO_0"))) ) (subpath (param "WRITABLE_ROOT_1"))
+(require-all (subpath (param "WRITABLE_ROOT_0")) (require-not (subpath (param "WRITABLE_ROOT_0_RO_0"))) ) (subpath (param "WRITABLE_ROOT_1")) (subpath (param "WRITABLE_ROOT_2"))
 )
 "#,
         );
 
-        let expected_args = vec![
+        let mut expected_args = vec![
             "-p".to_string(),
             expected_policy,
             format!(
@@ -189,16 +196,25 @@ mod tests {
                 "-DWRITABLE_ROOT_1={}",
                 root_without_git_canon.to_string_lossy()
             ),
+            format!("-DWRITABLE_ROOT_2={}", cwd.to_string_lossy()),
+        ];
+
+        expected_args.extend(vec![
             "--".to_string(),
             "/bin/echo".to_string(),
             "hello".to_string(),
-        ];
+        ]);
 
-        assert_eq!(args, expected_args);
+        assert_eq!(expected_args, args);
     }
 
     #[test]
     fn create_seatbelt_args_for_cwd_as_git_repo() {
+        if cfg!(target_os = "windows") {
+            // /tmp does not exist on Windows, so skip this test.
+            return;
+        }
+
         // Create a temporary workspace with two writable roots: one containing
         // a top-level .git directory and one without it.
         let tmp = TempDir::new().expect("tempdir");
@@ -215,7 +231,8 @@ mod tests {
         let policy = SandboxPolicy::WorkspaceWrite {
             writable_roots: vec![],
             network_access: false,
-            include_default_writable_roots: true,
+            exclude_tmpdir_env_var: false,
+            exclude_slash_tmp: false,
         };
 
         let args = create_seatbelt_command_args(
@@ -224,17 +241,14 @@ mod tests {
             root_with_git.as_path(),
         );
 
-        let tmpdir_env_var = if cfg!(target_os = "macos") {
-            std::env::var("TMPDIR")
-                .ok()
-                .map(PathBuf::from)
-                .and_then(|p| p.canonicalize().ok())
-                .map(|p| p.to_string_lossy().to_string())
-        } else {
-            None
-        };
+        let tmpdir_env_var = std::env::var("TMPDIR")
+            .ok()
+            .map(PathBuf::from)
+            .and_then(|p| p.canonicalize().ok())
+            .map(|p| p.to_string_lossy().to_string());
+
         let tempdir_policy_entry = if tmpdir_env_var.is_some() {
-            " (subpath (param \"WRITABLE_ROOT_1\"))"
+            r#" (subpath (param "WRITABLE_ROOT_2"))"#
         } else {
             ""
         };
@@ -249,7 +263,7 @@ mod tests {
 ; allow read-only file operations
 (allow file-read*)
 (allow file-write*
-(require-all (subpath (param "WRITABLE_ROOT_0")) (require-not (subpath (param "WRITABLE_ROOT_0_RO_0"))) ){tempdir_policy_entry}
+(require-all (subpath (param "WRITABLE_ROOT_0")) (require-not (subpath (param "WRITABLE_ROOT_0_RO_0"))) ) (subpath (param "WRITABLE_ROOT_1")){tempdir_policy_entry}
 )
 "#,
         );
@@ -265,10 +279,17 @@ mod tests {
                 "-DWRITABLE_ROOT_0_RO_0={}",
                 root_with_git_git_canon.to_string_lossy()
             ),
+            format!(
+                "-DWRITABLE_ROOT_1={}",
+                PathBuf::from("/tmp")
+                    .canonicalize()
+                    .expect("canonicalize /tmp")
+                    .to_string_lossy()
+            ),
         ];
 
         if let Some(p) = tmpdir_env_var {
-            expected_args.push(format!("-DWRITABLE_ROOT_1={p}"));
+            expected_args.push(format!("-DWRITABLE_ROOT_2={p}"));
         }
 
         expected_args.extend(vec![
@@ -277,7 +298,7 @@ mod tests {
             "hello".to_string(),
         ]);
 
-        assert_eq!(args, expected_args);
+        assert_eq!(expected_args, args);
     }
 
     struct PopulatedTmp {

codex-rs/core/src/shell.rs

@@ -215,6 +215,8 @@ mod tests {
                         "HOME".to_string(),
                         temp_home.path().to_str().unwrap().to_string(),
                     )]),
+                    with_escalated_permissions: None,
+                    justification: None,
                 },
                 SandboxType::None,
                 Arc::new(Notify::new()),

codex-rs/core/src/util.rs

@@ -1,3 +1,4 @@
+use std::path::Path;
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -5,10 +6,8 @@ use rand::Rng;
 use tokio::sync::Notify;
 use tracing::debug;
 
-use crate::config::Config;
-
 const INITIAL_DELAY_MS: u64 = 200;
-const BACKOFF_FACTOR: f64 = 1.3;
+const BACKOFF_FACTOR: f64 = 2.0;
 
 /// Make a CancellationToken that is fulfilled when SIGINT occurs.
 pub fn notify_on_sigint() -> Arc<Notify> {
@@ -47,8 +46,8 @@ pub(crate) fn backoff(attempt: u64) -> Duration {
 /// `git worktree add` where the checkout lives outside the main repository
 /// directory. If you need Codex to work from such a checkout simply pass the
 /// `--allow-no-git-exec` CLI flag that disables the repo requirement.
-pub fn is_inside_git_repo(config: &Config) -> bool {
-    let mut dir = config.cwd.to_path_buf();
+pub fn is_inside_git_repo(base_dir: &Path) -> bool {
+    let mut dir = base_dir.to_path_buf();
 
     loop {
         if dir.join(".git").exists() {

codex-rs/core/tests/client.rs

@@ -1,6 +1,5 @@
-use std::path::PathBuf;
+#![allow(clippy::expect_used, clippy::unwrap_used)]
 
-use chrono::Utc;
 use codex_core::Codex;
 use codex_core::CodexSpawnOk;
 use codex_core::ModelProviderInfo;
@@ -11,10 +10,7 @@ use codex_core::protocol::InputItem;
 use codex_core::protocol::Op;
 use codex_core::protocol::SessionConfiguredEvent;
 use codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR;
-use codex_login::AuthDotJson;
-use codex_login::AuthMode;
 use codex_login::CodexAuth;
-use codex_login::TokenData;
 use core_test_support::load_default_config_for_test;
 use core_test_support::load_sse_fixture_with_id;
 use core_test_support::wait_for_event;
@@ -32,6 +28,32 @@ fn sse_completed(id: &str) -> String {
     load_sse_fixture_with_id("tests/fixtures/completed_template.json", id)
 }
 
+fn assert_message_role(request_body: &serde_json::Value, role: &str) {
+    assert_eq!(request_body["role"].as_str().unwrap(), role);
+}
+
+fn assert_message_starts_with(request_body: &serde_json::Value, text: &str) {
+    let content = request_body["content"][0]["text"]
+        .as_str()
+        .expect("invalid message content");
+
+    assert!(
+        content.starts_with(text),
+        "expected message content '{content}' to start with '{text}'"
+    );
+}
+
+fn assert_message_ends_with(request_body: &serde_json::Value, text: &str) {
+    let content = request_body["content"][0]["text"]
+        .as_str()
+        .expect("invalid message content");
+
+    assert!(
+        content.ends_with(text),
+        "expected message content '{content}' to end with '{text}'"
+    );
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn includes_session_id_and_model_headers_in_request() {
     #![allow(clippy::unwrap_used)]
@@ -71,7 +93,7 @@ async fn includes_session_id_and_model_headers_in_request() {
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
     let CodexSpawnOk { codex, .. } = Codex::spawn(
         config,
-        Some(CodexAuth::from_api_key("Test API Key".to_string())),
+        Some(CodexAuth::from_api_key("Test API Key")),
         ctrl_c.clone(),
     )
     .await
@@ -145,7 +167,7 @@ async fn includes_base_instructions_override_in_request() {
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
     let CodexSpawnOk { codex, .. } = Codex::spawn(
         config,
-        Some(CodexAuth::from_api_key("Test API Key".to_string())),
+        Some(CodexAuth::from_api_key("Test API Key")),
         ctrl_c.clone(),
     )
     .await
@@ -204,7 +226,7 @@ async fn originator_config_override_is_used() {
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
     let CodexSpawnOk { codex, .. } = Codex::spawn(
         config,
-        Some(CodexAuth::from_api_key("Test API Key".to_string())),
+        Some(CodexAuth::from_api_key("Test API Key")),
         ctrl_c.clone(),
     )
     .await
@@ -262,13 +284,10 @@ async fn chatgpt_auth_sends_correct_request() {
     let mut config = load_default_config_for_test(&codex_home);
     config.model_provider = model_provider;
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
-    let CodexSpawnOk { codex, .. } = Codex::spawn(
-        config,
-        Some(auth_from_token("Access Token".to_string())),
-        ctrl_c.clone(),
-    )
-    .await
-    .unwrap();
+    let CodexSpawnOk { codex, .. } =
+        Codex::spawn(config, Some(create_dummy_codex_auth()), ctrl_c.clone())
+            .await
+            .unwrap();
 
     codex
         .submit(Op::UserInput {
@@ -345,7 +364,7 @@ async fn includes_user_instructions_message_in_request() {
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
     let CodexSpawnOk { codex, .. } = Codex::spawn(
         config,
-        Some(CodexAuth::from_api_key("Test API Key".to_string())),
+        Some(CodexAuth::from_api_key("Test API Key")),
         ctrl_c.clone(),
     )
     .await
@@ -371,19 +390,12 @@ async fn includes_user_instructions_message_in_request() {
             .unwrap()
             .contains("be nice")
     );
-    assert_eq!(request_body["input"][0]["role"], "user");
-    assert!(
-        request_body["input"][0]["content"][0]["text"]
-            .as_str()
-            .unwrap()
-            .starts_with("<user_instructions>\n\nbe nice")
-    );
-    assert!(
-        request_body["input"][0]["content"][0]["text"]
-            .as_str()
-            .unwrap()
-            .ends_with("</user_instructions>")
-    );
+    assert_message_role(&request_body["input"][0], "user");
+    assert_message_starts_with(&request_body["input"][0], "<environment_context>\n\n");
+    assert_message_ends_with(&request_body["input"][0], "</environment_context>");
+    assert_message_role(&request_body["input"][1], "user");
+    assert_message_starts_with(&request_body["input"][1], "<user_instructions>\n\n");
+    assert_message_ends_with(&request_body["input"][1], "</user_instructions>");
 }
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
@@ -437,7 +449,7 @@ async fn azure_overrides_assign_properties_used_for_responses_url() {
         request_max_retries: None,
         stream_max_retries: None,
         stream_idle_timeout_ms: None,
-        requires_auth: false,
+        requires_openai_auth: false,
     };
 
     // Init session
@@ -460,20 +472,83 @@ async fn azure_overrides_assign_properties_used_for_responses_url() {
     wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
 }
 
-fn auth_from_token(id_token: String) -> CodexAuth {
-    CodexAuth::new(
-        None,
-        AuthMode::ChatGPT,
-        PathBuf::new(),
-        Some(AuthDotJson {
-            openai_api_key: None,
-            tokens: Some(TokenData {
-                id_token,
-                access_token: "Access Token".to_string(),
-                refresh_token: "test".to_string(),
-                account_id: Some("account_id".to_string()),
-            }),
-            last_refresh: Some(Utc::now()),
-        }),
-    )
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn env_var_overrides_loaded_auth() {
+    #![allow(clippy::unwrap_used)]
+
+    let existing_env_var_with_random_value = if cfg!(windows) { "USERNAME" } else { "USER" };
+
+    // Mock server
+    let server = MockServer::start().await;
+
+    // First request – must NOT include `previous_response_id`.
+    let first = ResponseTemplate::new(200)
+        .insert_header("content-type", "text/event-stream")
+        .set_body_raw(sse_completed("resp1"), "text/event-stream");
+
+    // Expect POST to /openai/responses with api-version query param
+    Mock::given(method("POST"))
+        .and(path("/openai/responses"))
+        .and(query_param("api-version", "2025-04-01-preview"))
+        .and(header_regex("Custom-Header", "Value"))
+        .and(header_regex(
+            "Authorization",
+            format!(
+                "Bearer {}",
+                std::env::var(existing_env_var_with_random_value).unwrap()
+            )
+            .as_str(),
+        ))
+        .respond_with(first)
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let provider = ModelProviderInfo {
+        name: "custom".to_string(),
+        base_url: Some(format!("{}/openai", server.uri())),
+        // Reuse the existing environment variable to avoid using unsafe code
+        env_key: Some(existing_env_var_with_random_value.to_string()),
+        query_params: Some(std::collections::HashMap::from([(
+            "api-version".to_string(),
+            "2025-04-01-preview".to_string(),
+        )])),
+        env_key_instructions: None,
+        wire_api: WireApi::Responses,
+        http_headers: Some(std::collections::HashMap::from([(
+            "Custom-Header".to_string(),
+            "Value".to_string(),
+        )])),
+        env_http_headers: None,
+        request_max_retries: None,
+        stream_max_retries: None,
+        stream_idle_timeout_ms: None,
+        requires_openai_auth: false,
+    };
+
+    // Init session
+    let codex_home = TempDir::new().unwrap();
+    let mut config = load_default_config_for_test(&codex_home);
+    config.model_provider = provider;
+
+    let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
+    let CodexSpawnOk { codex, .. } =
+        Codex::spawn(config, Some(create_dummy_codex_auth()), ctrl_c.clone())
+            .await
+            .unwrap();
+
+    codex
+        .submit(Op::UserInput {
+            items: vec![InputItem::Text {
+                text: "hello".into(),
+            }],
+        })
+        .await
+        .unwrap();
+
+    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
+}
+
+fn create_dummy_codex_auth() -> CodexAuth {
+    CodexAuth::create_dummy_chatgpt_auth_for_testing()
 }

codex-rs/core/tests/compact.rs

@@ -145,7 +145,7 @@ async fn summarize_context_three_requests_and_instructions() {
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
     let CodexSpawnOk { codex, .. } = Codex::spawn(
         config,
-        Some(CodexAuth::from_api_key("dummy".to_string())),
+        Some(CodexAuth::from_api_key("dummy")),
         ctrl_c.clone(),
     )
     .await

codex-rs/core/tests/exec.rs

@@ -28,6 +28,8 @@ async fn run_test_cmd(tmp: TempDir, cmd: Vec<&str>, should_be_ok: bool) {
         cwd: tmp.path().to_path_buf(),
         timeout_ms: Some(1000),
         env: HashMap::new(),
+        with_escalated_permissions: None,
+        justification: None,
     };
 
     let ctrl_c = Arc::new(Notify::new());

codex-rs/core/tests/exec_stream_events.rs

@@ -53,6 +53,8 @@ async fn test_exec_stdout_stream_events_echo() {
         cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
         timeout_ms: Some(5_000),
         env: HashMap::new(),
+        with_escalated_permissions: None,
+        justification: None,
     };
 
     let ctrl_c = Arc::new(Notify::new());
@@ -103,6 +105,8 @@ async fn test_exec_stderr_stream_events_echo() {
         cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
         timeout_ms: Some(5_000),
         env: HashMap::new(),
+        with_escalated_permissions: None,
+        justification: None,
     };
 
     let ctrl_c = Arc::new(Notify::new());

codex-rs/core/tests/sandbox.rs

@@ -76,7 +76,8 @@ async fn if_parent_of_repo_is_writable_then_dot_git_folder_is_writable() {
     let policy = SandboxPolicy::WorkspaceWrite {
         writable_roots: vec![test_scenario.repo_parent.clone()],
         network_access: false,
-        include_default_writable_roots: false,
+        exclude_tmpdir_env_var: true,
+        exclude_slash_tmp: true,
     };
 
     test_scenario
@@ -101,7 +102,8 @@ async fn if_git_repo_is_writable_root_then_dot_git_folder_is_read_only() {
     let policy = SandboxPolicy::WorkspaceWrite {
         writable_roots: vec![test_scenario.repo_root.clone()],
         network_access: false,
-        include_default_writable_roots: false,
+        exclude_tmpdir_env_var: true,
+        exclude_slash_tmp: true,
     };
 
     test_scenario

codex-rs/core/tests/stream_no_completed.rs

@@ -90,7 +90,7 @@ async fn retries_on_early_close() {
         request_max_retries: Some(0),
         stream_max_retries: Some(1),
         stream_idle_timeout_ms: Some(2000),
-        requires_auth: false,
+        requires_openai_auth: false,
     };
 
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());
@@ -99,7 +99,7 @@ async fn retries_on_early_close() {
     config.model_provider = model_provider;
     let CodexSpawnOk { codex, .. } = Codex::spawn(
         config,
-        Some(CodexAuth::from_api_key("Test API Key".to_string())),
+        Some(CodexAuth::from_api_key("Test API Key")),
         ctrl_c,
     )
     .await

codex-rs/exec/Cargo.toml

@@ -25,6 +25,7 @@ codex-common = { path = "../common", features = [
     "sandbox_summary",
 ] }
 codex-core = { path = "../core" }
+codex-ollama = { path = "../ollama" }
 owo-colors = "4.2.0"
 serde_json = "1"
 shlex = "1.3.0"

codex-rs/exec/src/cli.rs

@@ -14,6 +14,9 @@ pub struct Cli {
     #[arg(long, short = 'm')]
     pub model: Option<String>,
 
+    #[arg(long = "oss", default_value_t = false)]
+    pub oss: bool,
+
     /// Select the sandbox policy to use when executing model-generated shell
     /// commands.
     #[arg(long = "sandbox", short = 's')]
@@ -31,6 +34,7 @@ pub struct Cli {
     /// EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed.
     #[arg(
         long = "dangerously-bypass-approvals-and-sandbox",
+        alias = "yolo",
         default_value_t = false,
         conflicts_with = "full_auto"
     )]

codex-rs/exec/src/event_processor.rs

@@ -1,7 +1,5 @@
 use std::path::Path;
 
-use codex_common::summarize_sandbox_policy;
-use codex_core::WireApi;
 use codex_core::config::Config;
 use codex_core::protocol::Event;
 
@@ -19,30 +17,6 @@ pub(crate) trait EventProcessor {
     fn process_event(&mut self, event: Event) -> CodexStatus;
 }
 
-pub(crate) fn create_config_summary_entries(config: &Config) -> Vec<(&'static str, String)> {
-    let mut entries = vec![
-        ("workdir", config.cwd.display().to_string()),
-        ("model", config.model.clone()),
-        ("provider", config.model_provider_id.clone()),
-        ("approval", config.approval_policy.to_string()),
-        ("sandbox", summarize_sandbox_policy(&config.sandbox_policy)),
-    ];
-    if config.model_provider.wire_api == WireApi::Responses
-        && config.model_family.supports_reasoning_summaries
-    {
-        entries.push((
-            "reasoning effort",
-            config.model_reasoning_effort.to_string(),
-        ));
-        entries.push((
-            "reasoning summaries",
-            config.model_reasoning_summary.to_string(),
-        ));
-    }
-
-    entries
-}
-
 pub(crate) fn handle_last_message(last_agent_message: Option<&str>, output_file: &Path) {
     let message = last_agent_message.unwrap_or_default();
     write_last_message_file(message, Some(output_file));

codex-rs/exec/src/event_processor_with_human_output.rs

@@ -21,7 +21,6 @@ use codex_core::protocol::PatchApplyBeginEvent;
 use codex_core::protocol::PatchApplyEndEvent;
 use codex_core::protocol::SessionConfiguredEvent;
 use codex_core::protocol::TaskCompleteEvent;
-use codex_core::protocol::TokenUsage;
 use codex_core::protocol::TurnDiffEvent;
 use owo_colors::OwoColorize;
 use owo_colors::Style;
@@ -33,8 +32,8 @@ use std::time::Instant;
 
 use crate::event_processor::CodexStatus;
 use crate::event_processor::EventProcessor;
-use crate::event_processor::create_config_summary_entries;
 use crate::event_processor::handle_last_message;
+use codex_common::create_config_summary_entries;
 
 /// This should be configurable. When used in CI, users may not want to impose
 /// a limit so they can see the full transcript.
@@ -183,8 +182,8 @@ impl EventProcessor for EventProcessorWithHumanOutput {
                 }
                 return CodexStatus::InitiateShutdown;
             }
-            EventMsg::TokenCount(TokenUsage { total_tokens, .. }) => {
-                ts_println!(self, "tokens used: {total_tokens}");
+            EventMsg::TokenCount(token_usage) => {
+                ts_println!(self, "tokens used: {}", token_usage.blended_total());
             }
             EventMsg::AgentMessageDelta(AgentMessageDeltaEvent { delta }) => {
                 if !self.answer_started {

codex-rs/exec/src/event_processor_with_json_output.rs

@@ -9,8 +9,8 @@ use serde_json::json;
 
 use crate::event_processor::CodexStatus;
 use crate::event_processor::EventProcessor;
-use crate::event_processor::create_config_summary_entries;
 use crate::event_processor::handle_last_message;
+use codex_common::create_config_summary_entries;
 
 pub(crate) struct EventProcessorWithJsonOutput {
     last_message_path: Option<PathBuf>,

codex-rs/exec/src/lib.rs

@@ -9,6 +9,7 @@ use std::path::PathBuf;
 use std::sync::Arc;
 
 pub use cli::Cli;
+use codex_core::BUILT_IN_OSS_MODEL_PROVIDER_ID;
 use codex_core::codex_wrapper::CodexConversation;
 use codex_core::codex_wrapper::{self};
 use codex_core::config::Config;
@@ -21,6 +22,7 @@ use codex_core::protocol::InputItem;
 use codex_core::protocol::Op;
 use codex_core::protocol::TaskCompleteEvent;
 use codex_core::util::is_inside_git_repo;
+use codex_ollama::DEFAULT_OSS_MODEL;
 use event_processor_with_human_output::EventProcessorWithHumanOutput;
 use event_processor_with_json_output::EventProcessorWithJsonOutput;
 use tracing::debug;
@@ -34,7 +36,8 @@ use crate::event_processor::EventProcessor;
 pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()> {
     let Cli {
         images,
-        model,
+        model: model_cli_arg,
+        oss,
         config_profile,
         full_auto,
         dangerously_bypass_approvals_and_sandbox,
@@ -114,6 +117,23 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         sandbox_mode_cli_arg.map(Into::<SandboxMode>::into)
     };
 
+    // When using `--oss`, let the bootstrapper pick the model (defaulting to
+    // gpt-oss:20b) and ensure it is present locally. Also, force the built‑in
+    // `oss` model provider.
+    let model = if let Some(model) = model_cli_arg {
+        Some(model)
+    } else if oss {
+        Some(DEFAULT_OSS_MODEL.to_owned())
+    } else {
+        None // No model specified, will use the default.
+    };
+
+    let model_provider = if oss {
+        Some(BUILT_IN_OSS_MODEL_PROVIDER_ID.to_string())
+    } else {
+        None // No specific model provider override.
+    };
+
     // Load configuration and determine approval policy
     let overrides = ConfigOverrides {
         model,
@@ -123,10 +143,12 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         approval_policy: Some(AskForApproval::Never),
         sandbox_mode,
         cwd: cwd.map(|p| p.canonicalize().unwrap_or(p)),
-        model_provider: None,
+        model_provider,
         codex_linux_sandbox_exe,
         base_instructions: None,
         include_plan_tool: None,
+        disable_response_storage: oss.then_some(true),
+        show_raw_agent_reasoning: oss.then_some(true),
     };
     // Parse `-c` overrides.
     let cli_kv_overrides = match config_overrides.parse_overrides() {
@@ -148,12 +170,18 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         ))
     };
 
+    if oss {
+        codex_ollama::ensure_oss_ready(&config)
+            .await
+            .map_err(|e| anyhow::anyhow!("OSS setup failed: {e}"))?;
+    }
+
     // Print the effective configuration and prompt so users can see what Codex
     // is using.
     event_processor.print_config_summary(&config, &prompt);
 
-    if !skip_git_repo_check && !is_inside_git_repo(&config) {
-        eprintln!("Not inside a Git repo and --skip-git-repo-check was not specified.");
+    if !skip_git_repo_check && !is_inside_git_repo(&config.cwd.to_path_buf()) {
+        eprintln!("Not inside a trusted directory and --skip-git-repo-check was not specified.");
         std::process::exit(1);
     }
 
@@ -188,10 +216,16 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
                     res = codex.next_event() => match res {
                         Ok(event) => {
                             debug!("Received event: {event:?}");
+
+                            let is_shutdown_complete = matches!(event.msg, EventMsg::ShutdownComplete);
                             if let Err(e) = tx.send(event) {
                                 error!("Error sending event: {e:?}");
                                 break;
                             }
+                            if is_shutdown_complete {
+                                info!("Received shutdown event, exiting event loop.");
+                                break;
+                            }
                         },
                         Err(e) => {
                             error!("Error receiving event: {e:?}");

codex-rs/linux-sandbox/tests/landlock.rs

@@ -44,12 +44,18 @@ async fn run_cmd(cmd: &[&str], writable_roots: &[PathBuf], timeout_ms: u64) {
         cwd: std::env::current_dir().expect("cwd should exist"),
         timeout_ms: Some(timeout_ms),
         env: create_env_from_core_vars(),
+        with_escalated_permissions: None,
+        justification: None,
     };
 
     let sandbox_policy = SandboxPolicy::WorkspaceWrite {
         writable_roots: writable_roots.to_vec(),
         network_access: false,
-        include_default_writable_roots: true,
+        // Exclude tmp-related folders from writable roots because we need a
+        // folder that is writable by tests but that we intentionally disallow
+        // writing to in the sandbox.
+        exclude_tmpdir_env_var: true,
+        exclude_slash_tmp: true,
     };
     let sandbox_program = env!("CARGO_BIN_EXE_codex-linux-sandbox");
     let codex_linux_sandbox_exe = Some(PathBuf::from(sandbox_program));
@@ -139,6 +145,8 @@ async fn assert_network_blocked(cmd: &[&str]) {
         // do not stall the suite.
         timeout_ms: Some(NETWORK_TIMEOUT_MS),
         env: create_env_from_core_vars(),
+        with_escalated_permissions: None,
+        justification: None,
     };
 
     let sandbox_policy = SandboxPolicy::new_read_only_policy();

codex-rs/login/Cargo.toml

@@ -7,10 +7,12 @@ version = { workspace = true }
 workspace = true
 
 [dependencies]
+base64 = "0.22"
 chrono = { version = "0.4", features = ["serde"] }
 reqwest = { version = "0.12", features = ["json"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+thiserror = "2.0.12"
 tokio = { version = "1", features = [
     "io-std",
     "macros",
@@ -20,4 +22,5 @@ tokio = { version = "1", features = [
 ] }
 
 [dev-dependencies]
+pretty_assertions = "1.4.1"
 tempfile = "3"

codex-rs/login/src/lib.rs

@@ -4,19 +4,27 @@ use chrono::Utc;
 use serde::Deserialize;
 use serde::Serialize;
 use std::env;
+use std::fs::File;
 use std::fs::OpenOptions;
+use std::fs::remove_file;
 use std::io::Read;
 use std::io::Write;
 #[cfg(unix)]
 use std::os::unix::fs::OpenOptionsExt;
 use std::path::Path;
 use std::path::PathBuf;
+use std::process::Child;
 use std::process::Stdio;
 use std::sync::Arc;
 use std::sync::Mutex;
 use std::time::Duration;
 use tokio::process::Command;
 
+pub use crate::token_data::TokenData;
+use crate::token_data::parse_id_token;
+
+mod token_data;
+
 const SOURCE_FOR_PYTHON_SERVER: &str = include_str!("./login_with_chatgpt.py");
 
 const CLIENT_ID: &str = "app_EMoamEEZ73f0CkXaXp7hrann";
@@ -30,8 +38,9 @@ pub enum AuthMode {
 
 #[derive(Debug, Clone)]
 pub struct CodexAuth {
-    pub api_key: Option<String>,
     pub mode: AuthMode,
+
+    api_key: Option<String>,
     auth_dot_json: Arc<Mutex<Option<AuthDotJson>>>,
     auth_file: PathBuf,
 }
@@ -43,33 +52,23 @@ impl PartialEq for CodexAuth {
 }
 
 impl CodexAuth {
-    pub fn new(
-        api_key: Option<String>,
-        mode: AuthMode,
-        auth_file: PathBuf,
-        auth_dot_json: Option<AuthDotJson>,
-    ) -> Self {
-        let auth_dot_json = Arc::new(Mutex::new(auth_dot_json));
+    pub fn from_api_key(api_key: &str) -> Self {
         Self {
-            api_key,
-            mode,
-            auth_file,
-            auth_dot_json,
-        }
-    }
-
-    pub fn from_api_key(api_key: String) -> Self {
-        Self {
-            api_key: Some(api_key),
+            api_key: Some(api_key.to_owned()),
             mode: AuthMode::ApiKey,
             auth_file: PathBuf::new(),
             auth_dot_json: Arc::new(Mutex::new(None)),
         }
     }
 
+    /// Loads the available auth information from the auth.json or
+    /// OPENAI_API_KEY environment variable.
+    pub fn from_codex_home(codex_home: &Path) -> std::io::Result<Option<CodexAuth>> {
+        load_auth(codex_home, true)
+    }
+
     pub async fn get_token_data(&self) -> Result<TokenData, std::io::Error> {
-        #[expect(clippy::unwrap_used)]
-        let auth_dot_json = self.auth_dot_json.lock().unwrap().clone();
+        let auth_dot_json: Option<AuthDotJson> = self.get_current_auth_json();
         match auth_dot_json {
             Some(AuthDotJson {
                 tokens: Some(mut tokens),
@@ -124,65 +123,188 @@ impl CodexAuth {
         }
     }
 
-    pub async fn get_account_id(&self) -> Option<String> {
-        match self.mode {
-            AuthMode::ApiKey => None,
-            AuthMode::ChatGPT => {
-                let token_data = self.get_token_data().await.ok()?;
+    pub fn get_account_id(&self) -> Option<String> {
+        self.get_current_token_data()
+            .and_then(|t| t.account_id.clone())
+    }
 
-                token_data.account_id.clone()
-            }
+    pub fn get_plan_type(&self) -> Option<String> {
+        self.get_current_token_data()
+            .and_then(|t| t.id_token.chatgpt_plan_type.as_ref().map(|p| p.as_string()))
+    }
+
+    fn get_current_auth_json(&self) -> Option<AuthDotJson> {
+        #[expect(clippy::unwrap_used)]
+        self.auth_dot_json.lock().unwrap().clone()
+    }
+
+    fn get_current_token_data(&self) -> Option<TokenData> {
+        self.get_current_auth_json().and_then(|t| t.tokens.clone())
+    }
+
+    /// Consider this private to integration tests.
+    pub fn create_dummy_chatgpt_auth_for_testing() -> Self {
+        let auth_dot_json = AuthDotJson {
+            openai_api_key: None,
+            tokens: Some(TokenData {
+                id_token: Default::default(),
+                access_token: "Access Token".to_string(),
+                refresh_token: "test".to_string(),
+                account_id: Some("account_id".to_string()),
+            }),
+            last_refresh: Some(Utc::now()),
+        };
+
+        let auth_dot_json = Arc::new(Mutex::new(Some(auth_dot_json)));
+        Self {
+            api_key: None,
+            mode: AuthMode::ChatGPT,
+            auth_file: PathBuf::new(),
+            auth_dot_json,
         }
     }
 }
 
-// Loads the available auth information from the auth.json or OPENAI_API_KEY environment variable.
-pub fn load_auth(codex_home: &Path, include_env_var: bool) -> std::io::Result<Option<CodexAuth>> {
+fn load_auth(codex_home: &Path, include_env_var: bool) -> std::io::Result<Option<CodexAuth>> {
+    // First, check to see if there is a valid auth.json file. If not, we fall
+    // back to AuthMode::ApiKey using the OPENAI_API_KEY environment variable
+    // (if it is set).
     let auth_file = get_auth_file(codex_home);
-
-    let auth_dot_json = try_read_auth_json(&auth_file).ok();
-
-    let auth_json_api_key = auth_dot_json
-        .as_ref()
-        .and_then(|a| a.openai_api_key.clone())
-        .filter(|s| !s.is_empty());
-
-    let openai_api_key = if include_env_var {
-        env::var(OPENAI_API_KEY_ENV_VAR)
-            .ok()
-            .filter(|s| !s.is_empty())
-            .or(auth_json_api_key)
-    } else {
-        auth_json_api_key
+    let auth_dot_json = match try_read_auth_json(&auth_file) {
+        Ok(auth) => auth,
+        // If auth.json does not exist, try to read the OPENAI_API_KEY from the
+        // environment variable.
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound && include_env_var => {
+            return match read_openai_api_key_from_env() {
+                Some(api_key) => Ok(Some(CodexAuth::from_api_key(&api_key))),
+                None => Ok(None),
+            };
+        }
+        // Though if auth.json exists but is malformed, do not fall back to the
+        // env var because the user may be expecting to use AuthMode::ChatGPT.
+        Err(e) => {
+            return Err(e);
+        }
     };
 
-    let has_tokens = auth_dot_json
-        .as_ref()
-        .and_then(|a| a.tokens.as_ref())
-        .is_some();
+    let AuthDotJson {
+        openai_api_key: auth_json_api_key,
+        tokens,
+        last_refresh,
+    } = auth_dot_json;
 
-    if openai_api_key.is_none() && !has_tokens {
-        return Ok(None);
+    // If the auth.json has an API key AND does not appear to be on a plan that
+    // should prefer AuthMode::ChatGPT, use AuthMode::ApiKey.
+    if let Some(api_key) = &auth_json_api_key {
+        // Should any of these be AuthMode::ChatGPT with the api_key set?
+        // Does AuthMode::ChatGPT indicate that there is an auth.json that is
+        // "refreshable" even if we are using the API key for auth?
+        match &tokens {
+            Some(tokens) => {
+                if tokens.is_plan_that_should_use_api_key() {
+                    return Ok(Some(CodexAuth::from_api_key(api_key)));
+                } else {
+                    // Ignore the API key and fall through to ChatGPT auth.
+                }
+            }
+            None => {
+                // We have an API key but no tokens in the auth.json file.
+                // Perhaps the user ran `codex login --api-key <KEY>` or updated
+                // auth.json by hand. Either way, let's assume they are trying
+                // to use their API key.
+                return Ok(Some(CodexAuth::from_api_key(api_key)));
+            }
+        }
     }
 
-    let mode = if openai_api_key.is_some() {
-        AuthMode::ApiKey
-    } else {
-        AuthMode::ChatGPT
-    };
-
+    // For the AuthMode::ChatGPT variant, perhaps neither api_key nor
+    // openai_api_key should exist?
     Ok(Some(CodexAuth {
-        api_key: openai_api_key,
-        mode,
+        api_key: None,
+        mode: AuthMode::ChatGPT,
         auth_file,
-        auth_dot_json: Arc::new(Mutex::new(auth_dot_json)),
+        auth_dot_json: Arc::new(Mutex::new(Some(AuthDotJson {
+            openai_api_key: None,
+            tokens,
+            last_refresh,
+        }))),
     }))
 }
 
-fn get_auth_file(codex_home: &Path) -> PathBuf {
+fn read_openai_api_key_from_env() -> Option<String> {
+    env::var(OPENAI_API_KEY_ENV_VAR)
+        .ok()
+        .filter(|s| !s.is_empty())
+}
+
+pub fn get_auth_file(codex_home: &Path) -> PathBuf {
     codex_home.join("auth.json")
 }
 
+/// Delete the auth.json file inside `codex_home` if it exists. Returns `Ok(true)`
+/// if a file was removed, `Ok(false)` if no auth file was present.
+pub fn logout(codex_home: &Path) -> std::io::Result<bool> {
+    let auth_file = get_auth_file(codex_home);
+    match remove_file(&auth_file) {
+        Ok(_) => Ok(true),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(false),
+        Err(err) => Err(err),
+    }
+}
+
+/// Represents a running login subprocess. The child can be killed by holding
+/// the mutex and calling `kill()`.
+#[derive(Debug, Clone)]
+pub struct SpawnedLogin {
+    pub child: Arc<Mutex<Child>>,
+    pub stdout: Arc<Mutex<Vec<u8>>>,
+    pub stderr: Arc<Mutex<Vec<u8>>>,
+}
+
+/// Spawn the ChatGPT login Python server as a child process and return a handle to its process.
+pub fn spawn_login_with_chatgpt(codex_home: &Path) -> std::io::Result<SpawnedLogin> {
+    let mut cmd = std::process::Command::new("python3");
+    cmd.arg("-c")
+        .arg(SOURCE_FOR_PYTHON_SERVER)
+        .env("CODEX_HOME", codex_home)
+        .env("CODEX_CLIENT_ID", CLIENT_ID)
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+
+    let mut child = cmd.spawn()?;
+
+    let stdout_buf = Arc::new(Mutex::new(Vec::new()));
+    let stderr_buf = Arc::new(Mutex::new(Vec::new()));
+
+    if let Some(mut out) = child.stdout.take() {
+        let buf = stdout_buf.clone();
+        std::thread::spawn(move || {
+            let mut tmp = Vec::new();
+            let _ = std::io::copy(&mut out, &mut tmp);
+            if let Ok(mut b) = buf.lock() {
+                b.extend_from_slice(&tmp);
+            }
+        });
+    }
+    if let Some(mut err) = child.stderr.take() {
+        let buf = stderr_buf.clone();
+        std::thread::spawn(move || {
+            let mut tmp = Vec::new();
+            let _ = std::io::copy(&mut err, &mut tmp);
+            if let Ok(mut b) = buf.lock() {
+                b.extend_from_slice(&tmp);
+            }
+        });
+    }
+
+    Ok(SpawnedLogin {
+        child: Arc::new(Mutex::new(child)),
+        stdout: stdout_buf,
+        stderr: stderr_buf,
+    })
+}
+
 /// Run `python3 -c {{SOURCE_FOR_PYTHON_SERVER}}` with the CODEX_HOME
 /// environment variable set to the provided `codex_home` path. If the
 /// subprocess exits 0, read the OPENAI_API_KEY property out of
@@ -234,7 +356,7 @@ pub fn login_with_api_key(codex_home: &Path, api_key: &str) -> std::io::Result<(
 /// Attempt to read and refresh the `auth.json` file in the given `CODEX_HOME` directory.
 /// Returns the full AuthDotJson structure after refreshing if necessary.
 pub fn try_read_auth_json(auth_file: &Path) -> std::io::Result<AuthDotJson> {
-    let mut file = std::fs::File::open(auth_file)?;
+    let mut file = File::open(auth_file)?;
     let mut contents = String::new();
     file.read_to_string(&mut contents)?;
     let auth_dot_json: AuthDotJson = serde_json::from_str(&contents)?;
@@ -265,7 +387,7 @@ async fn update_tokens(
     let mut auth_dot_json = try_read_auth_json(auth_file)?;
 
     let tokens = auth_dot_json.tokens.get_or_insert_with(TokenData::default);
-    tokens.id_token = id_token.to_string();
+    tokens.id_token = parse_id_token(&id_token).map_err(std::io::Error::other)?;
     if let Some(access_token) = access_token {
         tokens.access_token = access_token.to_string();
     }
@@ -336,26 +458,21 @@ pub struct AuthDotJson {
     pub last_refresh: Option<DateTime<Utc>>,
 }
 
-#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Default)]
-pub struct TokenData {
-    /// This is a JWT.
-    pub id_token: String,
-
-    /// This is a JWT.
-    pub access_token: String,
-
-    pub refresh_token: String,
-
-    pub account_id: Option<String>,
-}
-
 #[cfg(test)]
 mod tests {
+    #![expect(clippy::expect_used, clippy::unwrap_used)]
     use super::*;
+    use crate::token_data::IdTokenInfo;
+    use crate::token_data::KnownPlan;
+    use crate::token_data::PlanType;
+    use base64::Engine;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
     use tempfile::tempdir;
 
+    const LAST_REFRESH: &str = "2025-08-06T20:41:36.232376Z";
+
     #[test]
-    #[expect(clippy::unwrap_used)]
     fn writes_api_key_and_loads_auth() {
         let dir = tempdir().unwrap();
         login_with_api_key(dir.path(), "sk-test-key").unwrap();
@@ -365,7 +482,6 @@ mod tests {
     }
 
     #[test]
-    #[expect(clippy::unwrap_used)]
     fn loads_from_env_var_if_env_var_exists() {
         let dir = tempdir().unwrap();
 
@@ -379,45 +495,189 @@ mod tests {
     }
 
     #[tokio::test]
-    #[expect(clippy::unwrap_used)]
-    async fn loads_token_data_from_auth_json() {
-        let dir = tempdir().unwrap();
-        let auth_file = dir.path().join("auth.json");
-        std::fs::write(
-            auth_file,
-            format!(
-                r#"
-        {{
-            "OPENAI_API_KEY": null,
-            "tokens": {{
-                "id_token": "test-id-token",
+    async fn pro_account_with_no_api_key_uses_chatgpt_auth() {
+        let codex_home = tempdir().unwrap();
+        write_auth_file(
+            AuthFileParams {
+                openai_api_key: None,
+                chatgpt_plan_type: "pro".to_string(),
+            },
+            codex_home.path(),
+        )
+        .expect("failed to write auth file");
+
+        let CodexAuth {
+            api_key,
+            mode,
+            auth_dot_json,
+            auth_file: _,
+        } = load_auth(codex_home.path(), false).unwrap().unwrap();
+        assert_eq!(None, api_key);
+        assert_eq!(AuthMode::ChatGPT, mode);
+
+        let guard = auth_dot_json.lock().unwrap();
+        let auth_dot_json = guard.as_ref().expect("AuthDotJson should exist");
+        assert_eq!(
+            &AuthDotJson {
+                openai_api_key: None,
+                tokens: Some(TokenData {
+                    id_token: IdTokenInfo {
+                        email: Some("user@example.com".to_string()),
+                        chatgpt_plan_type: Some(PlanType::Known(KnownPlan::Pro)),
+                    },
+                    access_token: "test-access-token".to_string(),
+                    refresh_token: "test-refresh-token".to_string(),
+                    account_id: None,
+                }),
+                last_refresh: Some(
+                    DateTime::parse_from_rfc3339(LAST_REFRESH)
+                        .unwrap()
+                        .with_timezone(&Utc)
+                ),
+            },
+            auth_dot_json
+        )
+    }
+
+    /// Even if the OPENAI_API_KEY is set in auth.json, if the plan is not in
+    /// [`TokenData::is_plan_that_should_use_api_key`], it should use
+    /// [`AuthMode::ChatGPT`].
+    #[tokio::test]
+    async fn pro_account_with_api_key_still_uses_chatgpt_auth() {
+        let codex_home = tempdir().unwrap();
+        write_auth_file(
+            AuthFileParams {
+                openai_api_key: Some("sk-test-key".to_string()),
+                chatgpt_plan_type: "pro".to_string(),
+            },
+            codex_home.path(),
+        )
+        .expect("failed to write auth file");
+
+        let CodexAuth {
+            api_key,
+            mode,
+            auth_dot_json,
+            auth_file: _,
+        } = load_auth(codex_home.path(), false).unwrap().unwrap();
+        assert_eq!(None, api_key);
+        assert_eq!(AuthMode::ChatGPT, mode);
+
+        let guard = auth_dot_json.lock().unwrap();
+        let auth_dot_json = guard.as_ref().expect("AuthDotJson should exist");
+        assert_eq!(
+            &AuthDotJson {
+                openai_api_key: None,
+                tokens: Some(TokenData {
+                    id_token: IdTokenInfo {
+                        email: Some("user@example.com".to_string()),
+                        chatgpt_plan_type: Some(PlanType::Known(KnownPlan::Pro)),
+                    },
+                    access_token: "test-access-token".to_string(),
+                    refresh_token: "test-refresh-token".to_string(),
+                    account_id: None,
+                }),
+                last_refresh: Some(
+                    DateTime::parse_from_rfc3339(LAST_REFRESH)
+                        .unwrap()
+                        .with_timezone(&Utc)
+                ),
+            },
+            auth_dot_json
+        )
+    }
+
+    /// If the OPENAI_API_KEY is set in auth.json and it is an enterprise
+    /// account, then it should use [`AuthMode::ApiKey`].
+    #[tokio::test]
+    async fn enterprise_account_with_api_key_uses_chatgpt_auth() {
+        let codex_home = tempdir().unwrap();
+        write_auth_file(
+            AuthFileParams {
+                openai_api_key: Some("sk-test-key".to_string()),
+                chatgpt_plan_type: "enterprise".to_string(),
+            },
+            codex_home.path(),
+        )
+        .expect("failed to write auth file");
+
+        let CodexAuth {
+            api_key,
+            mode,
+            auth_dot_json,
+            auth_file: _,
+        } = load_auth(codex_home.path(), false).unwrap().unwrap();
+        assert_eq!(Some("sk-test-key".to_string()), api_key);
+        assert_eq!(AuthMode::ApiKey, mode);
+
+        let guard = auth_dot_json.lock().expect("should unwrap");
+        assert!(guard.is_none(), "auth_dot_json should be None");
+    }
+
+    struct AuthFileParams {
+        openai_api_key: Option<String>,
+        chatgpt_plan_type: String,
+    }
+
+    fn write_auth_file(params: AuthFileParams, codex_home: &Path) -> std::io::Result<()> {
+        let auth_file = get_auth_file(codex_home);
+        // Create a minimal valid JWT for the id_token field.
+        #[derive(Serialize)]
+        struct Header {
+            alg: &'static str,
+            typ: &'static str,
+        }
+        let header = Header {
+            alg: "none",
+            typ: "JWT",
+        };
+        let payload = serde_json::json!({
+            "email": "user@example.com",
+            "email_verified": true,
+            "https://api.openai.com/auth": {
+                "chatgpt_account_id": "bc3618e3-489d-4d49-9362-1561dc53ba53",
+                "chatgpt_plan_type": params.chatgpt_plan_type,
+                "chatgpt_user_id": "user-12345",
+                "user_id": "user-12345",
+            }
+        });
+        let b64 = |b: &[u8]| base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(b);
+        let header_b64 = b64(&serde_json::to_vec(&header)?);
+        let payload_b64 = b64(&serde_json::to_vec(&payload)?);
+        let signature_b64 = b64(b"sig");
+        let fake_jwt = format!("{header_b64}.{payload_b64}.{signature_b64}");
+
+        let auth_json_data = json!({
+            "OPENAI_API_KEY": params.openai_api_key,
+            "tokens": {
+                "id_token": fake_jwt,
                 "access_token": "test-access-token",
                 "refresh_token": "test-refresh-token"
-            }},
-            "last_refresh": "{}"
-        }}
-        "#,
-                Utc::now().to_rfc3339()
-            ),
-        )
-        .unwrap();
+            },
+            "last_refresh": LAST_REFRESH,
+        });
+        let auth_json = serde_json::to_string_pretty(&auth_json_data)?;
+        std::fs::write(auth_file, auth_json)
+    }
 
-        let auth = load_auth(dir.path(), false).unwrap().unwrap();
-        assert_eq!(auth.mode, AuthMode::ChatGPT);
-        assert_eq!(auth.api_key, None);
-        assert_eq!(
-            auth.get_token_data().await.unwrap(),
-            TokenData {
-                id_token: "test-id-token".to_string(),
-                access_token: "test-access-token".to_string(),
-                refresh_token: "test-refresh-token".to_string(),
-                account_id: None,
-            }
-        );
+    #[test]
+    fn id_token_info_handles_missing_fields() {
+        // Payload without email or plan should yield None values.
+        let header = serde_json::json!({"alg": "none", "typ": "JWT"});
+        let payload = serde_json::json!({"sub": "123"});
+        let header_b64 = base64::engine::general_purpose::URL_SAFE_NO_PAD
+            .encode(serde_json::to_vec(&header).unwrap());
+        let payload_b64 = base64::engine::general_purpose::URL_SAFE_NO_PAD
+            .encode(serde_json::to_vec(&payload).unwrap());
+        let signature_b64 = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(b"sig");
+        let jwt = format!("{header_b64}.{payload_b64}.{signature_b64}");
+
+        let info = parse_id_token(&jwt).expect("should parse");
+        assert!(info.email.is_none());
+        assert!(info.chatgpt_plan_type.is_none());
     }
 
     #[tokio::test]
-    #[expect(clippy::unwrap_used)]
     async fn loads_api_key_from_auth_json() {
         let dir = tempdir().unwrap();
         let auth_file = dir.path().join("auth.json");
@@ -439,4 +699,15 @@ mod tests {
 
         assert!(auth.get_token_data().await.is_err());
     }
+
+    #[test]
+    fn logout_removes_auth_file() -> Result<(), std::io::Error> {
+        let dir = tempdir()?;
+        login_with_api_key(dir.path(), "sk-test-key")?;
+        assert!(dir.path().join("auth.json").exists());
+        let removed = logout(dir.path())?;
+        assert!(removed);
+        assert!(!dir.path().join("auth.json").exists());
+        Ok(())
+    }
 }

codex-rs/login/src/login_with_chatgpt.py

@@ -110,7 +110,7 @@ def main() -> None:
                 eprint(f"Failed to open browser: {e}")
 
         eprint(
-            f"If your browser did not open, navigate to this URL to authenticate:\n\n{auth_url}"
+            f". If your browser did not open, navigate to this URL to authenticate: \n\n{auth_url}"
         )
 
         # Run the server in the main thread until `shutdown()` is called by the

codex-rs/login/src/token_data.rs

@@ -0,0 +1,181 @@
+use base64::Engine;
+use serde::Deserialize;
+use serde::Serialize;
+use thiserror::Error;
+
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Default)]
+pub struct TokenData {
+    /// Flat info parsed from the JWT in auth.json.
+    #[serde(deserialize_with = "deserialize_id_token")]
+    pub id_token: IdTokenInfo,
+
+    /// This is a JWT.
+    pub access_token: String,
+
+    pub refresh_token: String,
+
+    pub account_id: Option<String>,
+}
+
+impl TokenData {
+    /// Returns true if this is a plan that should use the traditional
+    /// "metered" billing via an API key.
+    pub(crate) fn is_plan_that_should_use_api_key(&self) -> bool {
+        self.id_token
+            .chatgpt_plan_type
+            .as_ref()
+            .is_none_or(|plan| plan.is_plan_that_should_use_api_key())
+    }
+}
+
+/// Flat subset of useful claims in id_token from auth.json.
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize)]
+pub struct IdTokenInfo {
+    pub email: Option<String>,
+    /// The ChatGPT subscription plan type
+    /// (e.g., "free", "plus", "pro", "business", "enterprise", "edu").
+    /// (Note: ae has not verified that those are the exact values.)
+    pub(crate) chatgpt_plan_type: Option<PlanType>,
+}
+
+impl IdTokenInfo {
+    pub fn get_chatgpt_plan_type(&self) -> Option<String> {
+        self.chatgpt_plan_type.as_ref().map(|t| match t {
+            PlanType::Known(plan) => format!("{plan:?}"),
+            PlanType::Unknown(s) => s.clone(),
+        })
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub(crate) enum PlanType {
+    Known(KnownPlan),
+    Unknown(String),
+}
+
+impl PlanType {
+    fn is_plan_that_should_use_api_key(&self) -> bool {
+        match self {
+            Self::Known(known) => {
+                use KnownPlan::*;
+                !matches!(known, Free | Plus | Pro | Team)
+            }
+            Self::Unknown(_) => {
+                // Unknown plans should use the API key.
+                true
+            }
+        }
+    }
+
+    pub fn as_string(&self) -> String {
+        match self {
+            Self::Known(known) => format!("{known:?}").to_lowercase(),
+            Self::Unknown(s) => s.clone(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub(crate) enum KnownPlan {
+    Free,
+    Plus,
+    Pro,
+    Team,
+    Business,
+    Enterprise,
+    Edu,
+}
+
+#[derive(Deserialize)]
+struct IdClaims {
+    #[serde(default)]
+    email: Option<String>,
+    #[serde(rename = "https://api.openai.com/auth", default)]
+    auth: Option<AuthClaims>,
+}
+
+#[derive(Deserialize)]
+struct AuthClaims {
+    #[serde(default)]
+    chatgpt_plan_type: Option<PlanType>,
+}
+
+#[derive(Debug, Error)]
+pub enum IdTokenInfoError {
+    #[error("invalid ID token format")]
+    InvalidFormat,
+    #[error(transparent)]
+    Base64(#[from] base64::DecodeError),
+    #[error(transparent)]
+    Json(#[from] serde_json::Error),
+}
+
+pub(crate) fn parse_id_token(id_token: &str) -> Result<IdTokenInfo, IdTokenInfoError> {
+    // JWT format: header.payload.signature
+    let mut parts = id_token.split('.');
+    let (_header_b64, payload_b64, _sig_b64) = match (parts.next(), parts.next(), parts.next()) {
+        (Some(h), Some(p), Some(s)) if !h.is_empty() && !p.is_empty() && !s.is_empty() => (h, p, s),
+        _ => return Err(IdTokenInfoError::InvalidFormat),
+    };
+
+    let payload_bytes = base64::engine::general_purpose::URL_SAFE_NO_PAD.decode(payload_b64)?;
+    let claims: IdClaims = serde_json::from_slice(&payload_bytes)?;
+
+    Ok(IdTokenInfo {
+        email: claims.email,
+        chatgpt_plan_type: claims.auth.and_then(|a| a.chatgpt_plan_type),
+    })
+}
+
+fn deserialize_id_token<'de, D>(deserializer: D) -> Result<IdTokenInfo, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    let s = String::deserialize(deserializer)?;
+    parse_id_token(&s).map_err(serde::de::Error::custom)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde::Serialize;
+
+    #[test]
+    #[expect(clippy::expect_used, clippy::unwrap_used)]
+    fn id_token_info_parses_email_and_plan() {
+        // Build a fake JWT with a URL-safe base64 payload containing email and plan.
+        #[derive(Serialize)]
+        struct Header {
+            alg: &'static str,
+            typ: &'static str,
+        }
+        let header = Header {
+            alg: "none",
+            typ: "JWT",
+        };
+        let payload = serde_json::json!({
+            "email": "user@example.com",
+            "https://api.openai.com/auth": {
+                "chatgpt_plan_type": "pro"
+            }
+        });
+
+        fn b64url_no_pad(bytes: &[u8]) -> String {
+            base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes)
+        }
+
+        let header_b64 = b64url_no_pad(&serde_json::to_vec(&header).unwrap());
+        let payload_b64 = b64url_no_pad(&serde_json::to_vec(&payload).unwrap());
+        let signature_b64 = b64url_no_pad(b"sig");
+        let fake_jwt = format!("{header_b64}.{payload_b64}.{signature_b64}");
+
+        let info = parse_id_token(&fake_jwt).expect("should parse");
+        assert_eq!(info.email.as_deref(), Some("user@example.com"));
+        assert_eq!(
+            info.chatgpt_plan_type,
+            Some(PlanType::Known(KnownPlan::Pro))
+        );
+    }
+}

codex-rs/mcp-server/Cargo.toml

@@ -31,7 +31,6 @@ tokio = { version = "1", features = [
     "rt-multi-thread",
     "signal",
 ] }
-tokio-util = { version = "0.7" }
 toml = "0.9"
 tracing = { version = "0.1.41", features = ["log"] }
 tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }

codex-rs/mcp-server/src/codex_tool_config.rs

@@ -158,6 +158,8 @@ impl CodexToolCallParam {
             codex_linux_sandbox_exe,
             base_instructions,
             include_plan_tool,
+            disable_response_storage: None,
+            show_raw_agent_reasoning: None,
         };
 
         let cli_overrides = cli_overrides

codex-rs/mcp-server/src/codex_tool_runner.rs

@@ -15,6 +15,7 @@ use codex_core::protocol::EventMsg;
 use codex_core::protocol::ExecApprovalRequestEvent;
 use codex_core::protocol::InputItem;
 use codex_core::protocol::Op;
+use codex_core::protocol::Submission;
 use codex_core::protocol::TaskCompleteEvent;
 use mcp_types::CallToolResult;
 use mcp_types::ContentBlock;
@@ -78,18 +79,27 @@ pub async fn run_codex_tool_session(
         )
         .await;
 
+    // Use the original MCP request ID as the `sub_id` for the Codex submission so that
+    // any events emitted for this tool-call can be correlated with the
+    // originating `tools/call` request.
+    let sub_id = match &id {
+        RequestId::String(s) => s.clone(),
+        RequestId::Integer(n) => n.to_string(),
+    };
     running_requests_id_to_codex_uuid
         .lock()
         .await
         .insert(id.clone(), session_id);
-    if let Err(e) = codex
-        .submit(Op::UserInput {
+    let submission = Submission {
+        id: sub_id.clone(),
+        op: Op::UserInput {
             items: vec![InputItem::Text {
                 text: initial_prompt.clone(),
             }],
-        })
-        .await
-    {
+        },
+    };
+
+    if let Err(e) = codex.submit_with_id(submission).await {
         tracing::error!("Failed to submit initial prompt: {e}");
         // unregister the id so we don't keep it in the map
         running_requests_id_to_codex_uuid.lock().await.remove(&id);
@@ -141,7 +151,10 @@ async fn run_codex_tool_session_inner(
     request_id: RequestId,
     running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, Uuid>>>,
 ) {
-    let request_id_str = crate::request_id::request_id_to_string(&request_id);
+    let request_id_str = match &request_id {
+        RequestId::String(s) => s.clone(),
+        RequestId::Integer(n) => n.to_string(),
+    };
 
     // Stream events until the task needs to pause for user interaction or
     // completes.

codex-rs/mcp-server/src/conversation_loop.rs

@@ -1,369 +1,124 @@
-use std::collections::HashMap;
-use std::path::PathBuf;
 use std::sync::Arc;
 
+use crate::exec_approval::handle_exec_approval_request;
+use crate::outgoing_message::OutgoingMessageSender;
+use crate::outgoing_message::OutgoingNotificationMeta;
+use crate::patch_approval::handle_patch_approval_request;
 use codex_core::Codex;
-use codex_core::error::Result as CodexResult;
 use codex_core::protocol::AgentMessageEvent;
 use codex_core::protocol::ApplyPatchApprovalRequestEvent;
-use codex_core::protocol::Event;
 use codex_core::protocol::EventMsg;
 use codex_core::protocol::ExecApprovalRequestEvent;
-use codex_core::protocol::FileChange;
-use codex_core::protocol::InputItem;
-use codex_core::protocol::Op;
 use mcp_types::RequestId;
-use tokio::sync::Mutex;
-// no streaming watch channel; streaming is toggled via set_streaming on the struct
-use tokio_util::sync::CancellationToken;
 use tracing::error;
-use uuid::Uuid;
 
-use crate::exec_approval::handle_exec_approval_request;
-use crate::mcp_protocol::CodexEventNotificationParams;
-use crate::mcp_protocol::ConversationId;
-use crate::mcp_protocol::InitialStateNotificationParams;
-use crate::mcp_protocol::InitialStatePayload;
-use crate::mcp_protocol::NotificationMeta;
-use crate::mcp_protocol::ServerNotification;
-use crate::outgoing_message::OutgoingMessageSender;
-use crate::patch_approval::handle_patch_approval_request;
-use crate::request_id::request_id_to_string;
-
-/// Conversation struct that owns the Codex session and all per-conversation state.
-pub(crate) struct Conversation {
+pub async fn run_conversation_loop(
     codex: Arc<Codex>,
-    session_id: Uuid,
     outgoing: Arc<OutgoingMessageSender>,
     request_id: RequestId,
-    state: Mutex<ConversationState>,
-    cancel: CancellationToken,
-}
+) {
+    let request_id_str = match &request_id {
+        RequestId::String(s) => s.clone(),
+        RequestId::Integer(n) => n.to_string(),
+    };
 
-struct ConversationState {
-    streaming_enabled: bool,
-    buffered_events: Vec<CodexEventNotificationParams>,
-    pending_elicitations: Vec<PendingElicitation>,
-}
-
-impl Conversation {
-    pub(crate) fn new(
-        codex: Arc<Codex>,
-        outgoing: Arc<OutgoingMessageSender>,
-        request_id: RequestId,
-        session_id: Uuid,
-    ) -> Arc<Self> {
-        let conv = Arc::new(Self {
-            codex,
-            session_id,
-            outgoing,
-            request_id,
-            state: Mutex::new(ConversationState {
-                streaming_enabled: false,
-                buffered_events: Vec::new(),
-                pending_elicitations: Vec::new(),
-            }),
-            cancel: CancellationToken::new(),
-        });
-        // Detach a background loop tied to this Conversation
-        spawn_conversation_loop(conv.clone());
-        conv
-    }
-
-    pub(crate) async fn set_streaming(&self, enabled: bool) {
-        if enabled {
-            let (events_snapshot, pending_snapshot) = {
-                let mut st = self.state.lock().await;
-                st.streaming_enabled = true;
-                (
-                    st.buffered_events.clone(),
-                    std::mem::take(&mut st.pending_elicitations),
-                )
-            };
-            self.emit_initial_state_with(events_snapshot).await;
-            self.drain_pending_elicitations_from(pending_snapshot).await;
-        } else {
-            let mut st = self.state.lock().await;
-            st.streaming_enabled = false;
-        }
-    }
-
-    pub(crate) fn codex(&self) -> Arc<Codex> {
-        self.codex.clone()
-    }
-
-    pub(crate) async fn try_submit_user_input(
-        &self,
-        request_id: RequestId,
-        items: Vec<InputItem>,
-    ) -> CodexResult<()> {
-        let _ = request_id; // request_id is not used to enforce uniqueness; Codex generates ids.
-        self.codex.submit(Op::UserInput { items }).await.map(|_| ())
-    }
-
-    async fn handle_event(&self, event: Event) {
-        {
-            let mut st = self.state.lock().await;
-            st.buffered_events.push(CodexEventNotificationParams {
-                meta: None,
-                msg: event.msg.clone(),
-            });
-        }
-        self.stream_event_if_enabled(&event.msg).await;
-
-        match event.msg {
-            EventMsg::ExecApprovalRequest(ExecApprovalRequestEvent {
-                command,
-                cwd,
-                call_id,
-                reason: _,
-            }) => {
-                self.process_exec_request(command, cwd, call_id, event.id.clone())
-                    .await;
-            }
-            EventMsg::Error(err) => {
-                error!("Codex runtime error: {}", err.message);
-            }
-            EventMsg::ApplyPatchApprovalRequest(ApplyPatchApprovalRequestEvent {
-                call_id,
-                reason,
-                grant_root,
-                changes,
-            }) => {
-                self.start_patch_approval(PatchRequest {
-                    call_id,
-                    reason,
-                    grant_root,
-                    changes,
-                    event_id: event.id.clone(),
-                })
-                .await;
-            }
-            EventMsg::TaskComplete(_) => {}
-            EventMsg::TaskStarted => {}
-            EventMsg::SessionConfigured(ev) => {
-                error!("unexpected SessionConfigured event: {:?}", ev);
-            }
-            EventMsg::AgentMessageDelta(_) => {}
-            EventMsg::AgentReasoningDelta(_) => {}
-            EventMsg::AgentMessage(AgentMessageEvent { .. }) => {}
-            EventMsg::TokenCount(_)
-            | EventMsg::AgentReasoning(_)
-            | EventMsg::AgentReasoningRawContent(_)
-            | EventMsg::AgentReasoningRawContentDelta(_)
-            | EventMsg::McpToolCallBegin(_)
-            | EventMsg::McpToolCallEnd(_)
-            | EventMsg::ExecCommandBegin(_)
-            | EventMsg::ExecCommandEnd(_)
-            | EventMsg::BackgroundEvent(_)
-            | EventMsg::ExecCommandOutputDelta(_)
-            | EventMsg::PatchApplyBegin(_)
-            | EventMsg::PatchApplyEnd(_)
-            | EventMsg::GetHistoryEntryResponse(_)
-            | EventMsg::PlanUpdate(_)
-            | EventMsg::TurnDiff(_)
-            | EventMsg::ShutdownComplete => {}
-        }
-    }
-
-    async fn emit_initial_state_with(&self, events: Vec<CodexEventNotificationParams>) {
-        let params = InitialStateNotificationParams {
-            meta: Some(NotificationMeta {
-                conversation_id: Some(ConversationId(self.session_id)),
-                request_id: None,
-            }),
-            initial_state: InitialStatePayload { events },
-        };
-        self.outgoing
-            .send_server_notification(ServerNotification::InitialState(params))
-            .await;
-    }
-
-    async fn drain_pending_elicitations_from(&self, items: Vec<PendingElicitation>) {
-        for item in items {
-            match item {
-                PendingElicitation::ExecRequest(ExecRequest {
-                    command,
-                    cwd,
-                    event_id,
-                    call_id,
-                }) => {
-                    handle_exec_approval_request(
-                        command,
-                        cwd,
-                        self.outgoing.clone(),
-                        self.codex.clone(),
-                        self.request_id.clone(),
-                        request_id_to_string(&self.request_id),
-                        event_id,
-                        call_id,
+    // Stream events until the task needs to pause for user interaction or
+    // completes.
+    loop {
+        match codex.next_event().await {
+            Ok(event) => {
+                outgoing
+                    .send_event_as_notification(
+                        &event,
+                        Some(OutgoingNotificationMeta::new(Some(request_id.clone()))),
                     )
                     .await;
-                }
-                PendingElicitation::PatchRequest(PatchRequest {
-                    call_id,
-                    reason,
-                    grant_root,
-                    changes,
-                    event_id,
-                }) => {
-                    handle_patch_approval_request(
+
+                match event.msg {
+                    EventMsg::ExecApprovalRequest(ExecApprovalRequestEvent {
+                        command,
+                        cwd,
+                        call_id,
+                        reason: _,
+                    }) => {
+                        handle_exec_approval_request(
+                            command,
+                            cwd,
+                            outgoing.clone(),
+                            codex.clone(),
+                            request_id.clone(),
+                            request_id_str.clone(),
+                            event.id.clone(),
+                            call_id,
+                        )
+                        .await;
+                        continue;
+                    }
+                    EventMsg::Error(_) => {
+                        error!("Codex runtime error");
+                    }
+                    EventMsg::ApplyPatchApprovalRequest(ApplyPatchApprovalRequestEvent {
                         call_id,
                         reason,
                         grant_root,
                         changes,
-                        self.outgoing.clone(),
-                        self.codex.clone(),
-                        self.request_id.clone(),
-                        request_id_to_string(&self.request_id),
-                        event_id,
-                    )
-                    .await;
-                }
-            }
-        }
-    }
-
-    async fn process_exec_request(
-        &self,
-        command: Vec<String>,
-        cwd: PathBuf,
-        call_id: String,
-        event_id: String,
-    ) {
-        let should_stream = {
-            let st = self.state.lock().await;
-            st.streaming_enabled
-        };
-        if should_stream {
-            handle_exec_approval_request(
-                command,
-                cwd,
-                self.outgoing.clone(),
-                self.codex.clone(),
-                self.request_id.clone(),
-                request_id_to_string(&self.request_id),
-                event_id,
-                call_id,
-            )
-            .await;
-        } else {
-            let mut st = self.state.lock().await;
-            st.pending_elicitations
-                .push(PendingElicitation::ExecRequest(ExecRequest {
-                    command,
-                    cwd,
-                    event_id,
-                    call_id,
-                }));
-        }
-    }
-
-    async fn start_patch_approval(&self, req: PatchRequest) {
-        let PatchRequest {
-            call_id,
-            reason,
-            grant_root,
-            changes,
-            event_id,
-        } = req;
-        let should_stream = {
-            let st = self.state.lock().await;
-            st.streaming_enabled
-        };
-        if should_stream {
-            handle_patch_approval_request(
-                call_id,
-                reason,
-                grant_root,
-                changes,
-                self.outgoing.clone(),
-                self.codex.clone(),
-                self.request_id.clone(),
-                request_id_to_string(&self.request_id),
-                event_id,
-            )
-            .await;
-        } else {
-            let mut st = self.state.lock().await;
-            st.pending_elicitations
-                .push(PendingElicitation::PatchRequest(PatchRequest {
-                    call_id,
-                    reason,
-                    grant_root,
-                    changes,
-                    event_id,
-                }));
-        }
-    }
-
-    async fn stream_event_if_enabled(&self, msg: &EventMsg) {
-        if !{ self.state.lock().await.streaming_enabled } {
-            return;
-        }
-        let method = msg.to_string();
-        let params = CodexEventNotificationParams {
-            meta: None,
-            msg: msg.clone(),
-        };
-        match serde_json::to_value(&params) {
-            Ok(params_val) => {
-                self.outgoing
-                    .send_custom_notification(&method, params_val)
-                    .await;
-            }
-            Err(err) => {
-                error!("Failed to serialize event params: {err:?}");
-            }
-        }
-    }
-}
-
-enum PendingElicitation {
-    ExecRequest(ExecRequest),
-    PatchRequest(PatchRequest),
-}
-
-struct PatchRequest {
-    call_id: String,
-    reason: Option<String>,
-    grant_root: Option<PathBuf>,
-    changes: HashMap<PathBuf, FileChange>,
-    event_id: String,
-}
-
-struct ExecRequest {
-    command: Vec<String>,
-    cwd: PathBuf,
-    event_id: String,
-    call_id: String,
-}
-
-impl Drop for Conversation {
-    fn drop(&mut self) {
-        self.cancel.cancel();
-    }
-}
-
-fn spawn_conversation_loop(this: Arc<Conversation>) {
-    tokio::spawn(async move {
-        let codex = this.codex.clone();
-        let cancel = this.cancel.clone();
-        loop {
-            tokio::select! {
-                _ = cancel.cancelled() => {
-                    break;
-                }
-                res = codex.next_event() => {
-                    match res {
-                        Ok(event) => this.handle_event(event).await,
-                        Err(e) => {
-                            error!("Codex next_event error (session {}): {e}", this.session_id);
-                            break;
-                        }
+                    }) => {
+                        handle_patch_approval_request(
+                            call_id,
+                            reason,
+                            grant_root,
+                            changes,
+                            outgoing.clone(),
+                            codex.clone(),
+                            request_id.clone(),
+                            request_id_str.clone(),
+                            event.id.clone(),
+                        )
+                        .await;
+                        continue;
+                    }
+                    EventMsg::TaskComplete(_) => {}
+                    EventMsg::SessionConfigured(_) => {
+                        tracing::error!("unexpected SessionConfigured event");
+                    }
+                    EventMsg::AgentMessageDelta(_) => {
+                        // TODO: think how we want to support this in the MCP
+                    }
+                    EventMsg::AgentReasoningDelta(_) => {
+                        // TODO: think how we want to support this in the MCP
+                    }
+                    EventMsg::AgentMessage(AgentMessageEvent { .. }) => {
+                        // TODO: think how we want to support this in the MCP
+                    }
+                    EventMsg::AgentReasoningRawContent(_)
+                    | EventMsg::AgentReasoningRawContentDelta(_)
+                    | EventMsg::TaskStarted
+                    | EventMsg::TokenCount(_)
+                    | EventMsg::AgentReasoning(_)
+                    | EventMsg::McpToolCallBegin(_)
+                    | EventMsg::McpToolCallEnd(_)
+                    | EventMsg::ExecCommandBegin(_)
+                    | EventMsg::ExecCommandEnd(_)
+                    | EventMsg::TurnDiff(_)
+                    | EventMsg::BackgroundEvent(_)
+                    | EventMsg::ExecCommandOutputDelta(_)
+                    | EventMsg::PatchApplyBegin(_)
+                    | EventMsg::PatchApplyEnd(_)
+                    | EventMsg::GetHistoryEntryResponse(_)
+                    | EventMsg::PlanUpdate(_)
+                    | EventMsg::ShutdownComplete => {
+                        // For now, we do not do anything extra for these
+                        // events. Note that
+                        // send(codex_event_to_notification(&event)) above has
+                        // already dispatched these events as notifications,
+                        // though we may want to do give different treatment to
+                        // individual events in the future.
                     }
                 }
             }
+            Err(e) => {
+                error!("Codex runtime error: {e}");
+            }
         }
-    });
+    }
 }

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

@@ -24,7 +24,6 @@ pub mod mcp_protocol;
 pub(crate) mod message_processor;
 mod outgoing_message;
 mod patch_approval;
-mod request_id;
 pub(crate) mod tool_handlers;
 
 use crate::message_processor::MessageProcessor;

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

@@ -1,4 +1,5 @@
 use std::collections::HashMap;
+use std::collections::HashSet;
 use std::path::PathBuf;
 use std::sync::Arc;
 
@@ -12,11 +13,10 @@ use crate::mcp_protocol::ToolCallResponseResult;
 use crate::outgoing_message::OutgoingMessageSender;
 use crate::tool_handlers::create_conversation::handle_create_conversation;
 use crate::tool_handlers::send_message::handle_send_message;
-use crate::tool_handlers::stream_conversation;
-use crate::tool_handlers::stream_conversation::handle_stream_conversation;
 
 use codex_core::Codex;
 use codex_core::config::Config as CodexConfig;
+use codex_core::protocol::Submission;
 use mcp_types::CallToolRequest;
 use mcp_types::CallToolRequestParams;
 use mcp_types::CallToolResult;
@@ -43,10 +43,8 @@ pub(crate) struct MessageProcessor {
     initialized: bool,
     codex_linux_sandbox_exe: Option<PathBuf>,
     session_map: Arc<Mutex<HashMap<Uuid, Arc<Codex>>>>,
-    conversation_map: Arc<Mutex<HashMap<Uuid, Arc<crate::conversation_loop::Conversation>>>>,
     running_requests_id_to_codex_uuid: Arc<Mutex<HashMap<RequestId, Uuid>>>,
-    /// Track request IDs to the original ToolCallRequestParams for cancellation handling
-    tool_request_map: Arc<Mutex<HashMap<RequestId, ToolCallRequestParams>>>,
+    running_session_ids: Arc<Mutex<HashSet<Uuid>>>,
 }
 
 impl MessageProcessor {
@@ -61,22 +59,23 @@ impl MessageProcessor {
             initialized: false,
             codex_linux_sandbox_exe,
             session_map: Arc::new(Mutex::new(HashMap::new())),
-            conversation_map: Arc::new(Mutex::new(HashMap::new())),
             running_requests_id_to_codex_uuid: Arc::new(Mutex::new(HashMap::new())),
-            tool_request_map: Arc::new(Mutex::new(HashMap::new())),
+            running_session_ids: Arc::new(Mutex::new(HashSet::new())),
         }
     }
 
-    pub(crate) fn conversation_map(
-        &self,
-    ) -> Arc<Mutex<HashMap<Uuid, Arc<crate::conversation_loop::Conversation>>>> {
-        self.conversation_map.clone()
+    pub(crate) fn session_map(&self) -> Arc<Mutex<HashMap<Uuid, Arc<Codex>>>> {
+        self.session_map.clone()
     }
 
     pub(crate) fn outgoing(&self) -> Arc<OutgoingMessageSender> {
         self.outgoing.clone()
     }
 
+    pub(crate) fn running_session_ids(&self) -> Arc<Mutex<HashSet<Uuid>>> {
+        self.running_session_ids.clone()
+    }
+
     pub(crate) async fn process_request(&mut self, request: JSONRPCRequest) {
         // Hold on to the ID so we can respond.
         let request_id = request.id.clone();
@@ -354,11 +353,6 @@ impl MessageProcessor {
         }
     }
     async fn handle_new_tool_calls(&self, request_id: RequestId, params: ToolCallRequestParams) {
-        // Track the request to allow graceful cancellation routing later.
-        {
-            let mut tool_request_map = self.tool_request_map.lock().await;
-            tool_request_map.insert(request_id.clone(), params.clone());
-        }
         match params {
             ToolCallRequestParams::ConversationCreate(args) => {
                 handle_create_conversation(self, request_id, args).await;
@@ -366,9 +360,6 @@ impl MessageProcessor {
             ToolCallRequestParams::ConversationSendMessage(args) => {
                 handle_send_message(self, request_id, args).await;
             }
-            ToolCallRequestParams::ConversationStream(args) => {
-                handle_stream_conversation(self, request_id, args).await;
-            }
             _ => {
                 let result = CallToolResult {
                     content: vec![ContentBlock::TextContent(TextContent {
@@ -593,72 +584,23 @@ impl MessageProcessor {
     // ---------------------------------------------------------------------
     // Notification handlers
     // ---------------------------------------------------------------------
+
     async fn handle_cancelled_notification(
         &self,
         params: <mcp_types::CancelledNotification as mcp_types::ModelContextProtocolNotification>::Params,
     ) {
         let request_id = params.request_id;
+        // Create a stable string form early for logging and submission id.
+        let request_id_string = match &request_id {
+            RequestId::String(s) => s.clone(),
+            RequestId::Integer(i) => i.to_string(),
+        };
 
-        if let Some(orig) = {
-            let mut tool_request_map = self.tool_request_map.lock().await;
-            tool_request_map.remove(&request_id)
-        } {
-            self.handle_mcp_protocol_cancelled_notification(request_id, orig)
-                .await;
-        } else {
-            self.handle_legacy_cancelled_notification(request_id).await;
-        }
-    }
-
-    async fn handle_mcp_protocol_cancelled_notification(
-        &self,
-        request_id: RequestId,
-        orig: ToolCallRequestParams,
-    ) {
-        match orig {
-            ToolCallRequestParams::ConversationStream(args) => {
-                stream_conversation::handle_cancel(self, &args).await;
-            }
-            ToolCallRequestParams::ConversationSendMessage(args) => {
-                // Cancel in-flight user input for this conversation by interrupting the session.
-
-                let session_id = args.conversation_id.0;
-                let codex_arc = {
-                    let sessions_guard = self.conversation_map.lock().await;
-                    match sessions_guard.get(&session_id) {
-                        Some(conv) => conv.codex().clone(),
-                        None => {
-                            tracing::warn!(
-                                "Cancel send_message: session not found for session_id: {session_id}"
-                            );
-                            return;
-                        }
-                    }
-                };
-
-                if let Err(e) = codex_arc.submit(codex_core::protocol::Op::Interrupt).await {
-                    tracing::error!("Failed to submit interrupt for send_message cancel: {e}");
-                }
-            }
-            ToolCallRequestParams::ConversationCreate(_)
-            | ToolCallRequestParams::ConversationsList(_) => {
-                // Likely fast/non-streaming; nothing to cancel currently.
-                tracing::debug!(
-                    "Cancel conversationsList received for request_id: {:?} (no-op)",
-                    request_id
-                );
-            }
-        }
-    }
-
-    async fn handle_legacy_cancelled_notification(&self, request_id: RequestId) {
-        use crate::request_id::request_id_to_string;
-        let request_id_string = request_id_to_string(&request_id);
-
+        // Obtain the session_id while holding the first lock, then release.
         let session_id = {
             let map_guard = self.running_requests_id_to_codex_uuid.lock().await;
             match map_guard.get(&request_id) {
-                Some(id) => *id,
+                Some(id) => *id, // Uuid is Copy
                 None => {
                     tracing::warn!("Session not found for request_id: {}", request_id_string);
                     return;
@@ -667,6 +609,7 @@ impl MessageProcessor {
         };
         tracing::info!("session_id: {session_id}");
 
+        // Obtain the Codex Arc while holding the session_map lock, then release.
         let codex_arc = {
             let sessions_guard = self.session_map.lock().await;
             match sessions_guard.get(&session_id) {
@@ -678,11 +621,18 @@ impl MessageProcessor {
             }
         };
 
-        if let Err(e) = codex_arc.submit(codex_core::protocol::Op::Interrupt).await {
+        // Submit interrupt to Codex.
+        let err = codex_arc
+            .submit_with_id(Submission {
+                id: request_id_string,
+                op: codex_core::protocol::Op::Interrupt,
+            })
+            .await;
+        if let Err(e) = err {
             tracing::error!("Failed to submit interrupt to Codex: {e}");
             return;
         }
-
+        // unregister the id so we don't keep it in the map
         self.running_requests_id_to_codex_uuid
             .lock()
             .await

codex-rs/mcp-server/src/outgoing_message.rs

@@ -109,7 +109,7 @@ impl OutgoingMessageSender {
 
     // should be backwards compatible.
     // it will replace send_event_as_notification eventually.
-    pub(crate) async fn send_event_as_notification_new_schema(
+    async fn send_event_as_notification_new_schema(
         &self,
         event: &Event,
         params: Option<serde_json::Value>,
@@ -124,37 +124,6 @@ impl OutgoingMessageSender {
         let outgoing_message = OutgoingMessage::Error(OutgoingError { id, error });
         let _ = self.sender.send(outgoing_message).await;
     }
-
-    /// Send a custom notification with an explicit method name and params object.
-    pub(crate) async fn send_custom_notification(&self, method: &str, params: serde_json::Value) {
-        let outgoing_message = OutgoingMessage::Notification(OutgoingNotification {
-            method: method.to_string(),
-            params: Some(params),
-        });
-        let _ = self.sender.send(outgoing_message).await;
-    }
-
-    /// Send a typed server notification by serializing it into a method/params pair.
-    pub(crate) async fn send_server_notification(
-        &self,
-        notification: crate::mcp_protocol::ServerNotification,
-    ) {
-        match serde_json::to_value(notification) {
-            Ok(serde_json::Value::Object(mut map)) => {
-                let method = map
-                    .remove("method")
-                    .and_then(|v| v.as_str().map(|s| s.to_string()));
-                let params = map.remove("params").unwrap_or(serde_json::Value::Null);
-                if let Some(method) = method {
-                    self.send_custom_notification(&method, params).await;
-                } else {
-                    warn!("ServerNotification missing method after serialization");
-                }
-            }
-            Ok(_) => warn!("ServerNotification did not serialize to an object"),
-            Err(err) => warn!("Failed to serialize ServerNotification: {err:?}"),
-        }
-    }
 }
 
 /// Outgoing message from the server to the client.

codex-rs/mcp-server/src/request_id.rs

@@ -1,9 +0,0 @@
-use mcp_types::RequestId;
-
-/// Utility to convert an MCP `RequestId` into a `String`.
-pub(crate) fn request_id_to_string(id: &RequestId) -> String {
-    match id {
-        RequestId::String(s) => s.clone(),
-        RequestId::Integer(i) => i.to_string(),
-    }
-}

codex-rs/mcp-server/src/tool_handlers/create_conversation.rs

@@ -1,14 +1,18 @@
+use std::collections::HashMap;
 use std::path::PathBuf;
 use std::sync::Arc;
 
+use codex_core::Codex;
 use codex_core::codex_wrapper::init_codex;
 use codex_core::config::Config as CodexConfig;
 use codex_core::config::ConfigOverrides;
 use codex_core::protocol::EventMsg;
 use codex_core::protocol::SessionConfiguredEvent;
 use mcp_types::RequestId;
+use tokio::sync::Mutex;
+use uuid::Uuid;
 
-use crate::conversation_loop::Conversation;
+use crate::conversation_loop::run_conversation_loop;
 use crate::json_to_toml::json_to_toml;
 use crate::mcp_protocol::ConversationCreateArgs;
 use crate::mcp_protocol::ConversationCreateResult;
@@ -55,6 +59,8 @@ pub(crate) async fn handle_create_conversation(
         codex_linux_sandbox_exe: None,
         base_instructions,
         include_plan_tool: None,
+        disable_response_storage: None,
+        show_raw_agent_reasoning: None,
     };
 
     let cfg: CodexConfig = match CodexConfig::load_with_cli_overrides(cli_overrides, overrides) {
@@ -117,17 +123,24 @@ pub(crate) async fn handle_create_conversation(
     let session_id = codex_conversation.session_id;
     let codex_arc = Arc::new(codex_conversation.codex);
 
-    // Construct conversation and start its loop, store it, then reply with id and model
+    // Store session for future calls
+    insert_session(
+        session_id,
+        codex_arc.clone(),
+        message_processor.session_map(),
+    )
+    .await;
+    // Run the conversation loop in the background so this request can return immediately.
     let outgoing = message_processor.outgoing();
-    let conversation = Conversation::new(codex_arc.clone(), outgoing, id.clone(), session_id);
-    let conv_map = message_processor.conversation_map();
-    {
-        let mut guard = conv_map.lock().await;
-        guard.insert(session_id, conversation);
-    }
+    let spawn_id = id.clone();
+    tokio::spawn(async move {
+        run_conversation_loop(codex_arc.clone(), outgoing, spawn_id).await;
+    });
+
+    // Reply with the new conversation id and effective model
     message_processor
         .send_response_with_optional_error(
-            id.clone(),
+            id,
             Some(ToolCallResponseResult::ConversationCreate(
                 ConversationCreateResult::Ok {
                     conversation_id: ConversationId(session_id),
@@ -138,3 +151,12 @@ pub(crate) async fn handle_create_conversation(
         )
         .await;
 }
+
+async fn insert_session(
+    session_id: Uuid,
+    codex: Arc<Codex>,
+    session_map: Arc<Mutex<HashMap<Uuid, Arc<Codex>>>>,
+) {
+    let mut guard = session_map.lock().await;
+    guard.insert(session_id, codex);
+}

codex-rs/mcp-server/src/tool_handlers/mod.rs

@@ -1,3 +1,2 @@
 pub(crate) mod create_conversation;
 pub(crate) mod send_message;
-pub(crate) mod stream_conversation;

codex-rs/mcp-server/src/tool_handlers/send_message.rs

@@ -1,11 +1,13 @@
 use std::collections::HashMap;
 use std::sync::Arc;
 
+use codex_core::Codex;
+use codex_core::protocol::Op;
+use codex_core::protocol::Submission;
 use mcp_types::RequestId;
 use tokio::sync::Mutex;
 use uuid::Uuid;
 
-use crate::conversation_loop::Conversation;
 use crate::mcp_protocol::ConversationSendMessageArgs;
 use crate::mcp_protocol::ConversationSendMessageResult;
 use crate::mcp_protocol::ToolCallResponseResult;
@@ -39,8 +41,7 @@ pub(crate) async fn handle_send_message(
     }
 
     let session_id = conversation_id.0;
-    let Some(conversation) = get_session(session_id, message_processor.conversation_map()).await
-    else {
+    let Some(codex) = get_session(session_id, message_processor.session_map()).await else {
         message_processor
             .send_response_with_optional_error(
                 id,
@@ -55,15 +56,46 @@ pub(crate) async fn handle_send_message(
         return;
     };
 
-    let res = conversation.try_submit_user_input(id.clone(), items).await;
+    let running = {
+        let running_sessions = message_processor.running_session_ids();
+        let mut running_sessions = running_sessions.lock().await;
+        !running_sessions.insert(session_id)
+    };
 
-    if let Err(e) = res {
+    if running {
         message_processor
             .send_response_with_optional_error(
                 id,
                 Some(ToolCallResponseResult::ConversationSendMessage(
                     ConversationSendMessageResult::Error {
-                        message: e.to_string(),
+                        message: "Session is already running".to_string(),
+                    },
+                )),
+                Some(true),
+            )
+            .await;
+        return;
+    }
+
+    let request_id_string = match &id {
+        RequestId::String(s) => s.clone(),
+        RequestId::Integer(i) => i.to_string(),
+    };
+
+    let submit_res = codex
+        .submit_with_id(Submission {
+            id: request_id_string,
+            op: Op::UserInput { items },
+        })
+        .await;
+
+    if let Err(e) = submit_res {
+        message_processor
+            .send_response_with_optional_error(
+                id,
+                Some(ToolCallResponseResult::ConversationSendMessage(
+                    ConversationSendMessageResult::Error {
+                        message: format!("Failed to submit user input: {e}"),
                     },
                 )),
                 Some(true),
@@ -85,8 +117,8 @@ pub(crate) async fn handle_send_message(
 
 pub(crate) async fn get_session(
     session_id: Uuid,
-    conversation_map: Arc<Mutex<HashMap<Uuid, Arc<Conversation>>>>,
-) -> Option<Arc<Conversation>> {
-    let guard = conversation_map.lock().await;
+    session_map: Arc<Mutex<HashMap<Uuid, Arc<Codex>>>>,
+) -> Option<Arc<Codex>> {
+    let guard = session_map.lock().await;
     guard.get(&session_id).cloned()
 }

codex-rs/mcp-server/src/tool_handlers/stream_conversation.rs

@@ -1,57 +0,0 @@
-use mcp_types::RequestId;
-
-use crate::mcp_protocol::ConversationStreamArgs;
-use crate::mcp_protocol::ConversationStreamResult;
-use crate::mcp_protocol::ToolCallResponseResult;
-use crate::message_processor::MessageProcessor;
-use crate::tool_handlers::send_message::get_session;
-
-/// Handles the ConversationStream tool call: verifies the session and
-/// enables streaming for the session, replying with an OK result.
-pub(crate) async fn handle_stream_conversation(
-    message_processor: &MessageProcessor,
-    id: RequestId,
-    arguments: ConversationStreamArgs,
-) {
-    let ConversationStreamArgs { conversation_id } = arguments;
-
-    let session_id = conversation_id.0;
-
-    // Ensure the session exists
-    let conv = get_session(session_id, message_processor.conversation_map()).await;
-
-    if conv.is_none() {
-        // Return an error with no result payload per MCP error pattern
-        message_processor
-            .send_response_with_optional_error(id, None, Some(true))
-            .await;
-        return;
-    }
-
-    message_processor
-        .send_response_with_optional_error(
-            id,
-            Some(ToolCallResponseResult::ConversationStream(
-                ConversationStreamResult {},
-            )),
-            Some(false),
-        )
-        .await;
-
-    if let Some(conv) = conv {
-        tokio::spawn(async move {
-            conv.set_streaming(true).await;
-        });
-    }
-}
-
-/// Handles cancellation for ConversationStream by disabling streaming for the session.
-pub(crate) async fn handle_cancel(
-    message_processor: &MessageProcessor,
-    args: &ConversationStreamArgs,
-) {
-    let session_id = args.conversation_id.0;
-    if let Some(conv) = get_session(session_id, message_processor.conversation_map()).await {
-        conv.set_streaming(false).await;
-    }
-}

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

@@ -1,26 +0,0 @@
-use std::path::Path;
-
-/// Write a minimal Codex config.toml pointing at the provided mock server URI.
-/// Used by tests that don't exercise approval/sandbox variations.
-pub fn create_config_toml(codex_home: &Path, server_uri: &str) -> std::io::Result<()> {
-    let config_toml = codex_home.join("config.toml");
-    std::fs::write(
-        config_toml,
-        format!(
-            r#"
-model = "mock-model"
-approval_policy = "never"
-sandbox_mode = "danger-full-access"
-
-model_provider = "mock_provider"
-
-[model_providers.mock_provider]
-name = "Mock provider for test"
-base_url = "{server_uri}/v1"
-wire_api = "chat"
-request_max_retries = 0
-stream_max_retries = 0
-"#
-        ),
-    )
-}

codex-rs/mcp-server/tests/common/lib.rs

@@ -1,9 +1,7 @@
-mod config;
 mod mcp_process;
 mod mock_model_server;
 mod responses;
 
-pub use config::create_config_toml;
 pub use mcp_process::McpProcess;
 pub use mock_model_server::create_mock_chat_completions_server;
 pub use responses::create_apply_patch_sse_response;

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

@@ -2,7 +2,6 @@ use std::path::Path;
 use std::process::Stdio;
 use std::sync::atomic::AtomicI64;
 use std::sync::atomic::Ordering;
-use std::time::Duration;
 use tokio::io::AsyncBufReadExt;
 use tokio::io::AsyncWriteExt;
 use tokio::io::BufReader;
@@ -18,7 +17,6 @@ use codex_mcp_server::CodexToolCallReplyParam;
 use codex_mcp_server::mcp_protocol::ConversationCreateArgs;
 use codex_mcp_server::mcp_protocol::ConversationId;
 use codex_mcp_server::mcp_protocol::ConversationSendMessageArgs;
-use codex_mcp_server::mcp_protocol::ConversationStreamArgs;
 use codex_mcp_server::mcp_protocol::ToolCallRequestParams;
 
 use mcp_types::CallToolRequestParams;
@@ -203,20 +201,6 @@ impl McpProcess {
         .await
     }
 
-    pub async fn send_conversation_stream_tool_call(
-        &mut self,
-        session_id: &str,
-    ) -> anyhow::Result<i64> {
-        let params = ToolCallRequestParams::ConversationStream(ConversationStreamArgs {
-            conversation_id: ConversationId(Uuid::parse_str(session_id)?),
-        });
-        self.send_request(
-            mcp_types::CallToolRequest::METHOD,
-            Some(serde_json::to_value(params)?),
-        )
-        .await
-    }
-
     pub async fn send_conversation_create_tool_call(
         &mut self,
         prompt: &str,
@@ -252,83 +236,6 @@ impl McpProcess {
         .await
     }
 
-    /// Create a conversation and return its conversation_id as a string.
-    pub async fn create_conversation_and_get_id(
-        &mut self,
-        prompt: &str,
-        model: &str,
-        cwd: &str,
-    ) -> anyhow::Result<String> {
-        let req_id = self
-            .send_conversation_create_tool_call(prompt, model, cwd)
-            .await?;
-        let resp = self
-            .read_stream_until_response_message(RequestId::Integer(req_id))
-            .await?;
-        let conv_id = resp.result["structuredContent"]["conversation_id"]
-            .as_str()
-            .ok_or_else(|| anyhow::format_err!("missing conversation_id"))?
-            .to_string();
-        Ok(conv_id)
-    }
-
-    /// Connect stream for a conversation and wait for the initial_state notification.
-    /// Returns (requestId, params) where params are the initial_state notification params.
-    pub async fn connect_stream_and_expect_initial_state(
-        &mut self,
-        session_id: &str,
-    ) -> anyhow::Result<(i64, serde_json::Value)> {
-        let req_id = self.send_conversation_stream_tool_call(session_id).await?;
-        // Wait for stream() tool-call response first
-        let _ = self
-            .read_stream_until_response_message(RequestId::Integer(req_id))
-            .await?;
-        // Then the initial_state notification
-        let note = self
-            .read_stream_until_notification_method("notifications/initial_state")
-            .await?;
-        let params = note
-            .params
-            .ok_or_else(|| anyhow::format_err!("initial_state must have params"))?;
-        Ok((req_id, params))
-    }
-
-    /// Wait for an agent_message with a bounded timeout. Returns Some(params) if received, None on timeout.
-    pub async fn maybe_wait_for_agent_message(
-        &mut self,
-        dur: Duration,
-    ) -> anyhow::Result<Option<serde_json::Value>> {
-        match tokio::time::timeout(dur, self.wait_for_agent_message()).await {
-            Ok(Ok(v)) => Ok(Some(v)),
-            Ok(Err(e)) => Err(e),
-            Err(_elapsed) => Ok(None),
-        }
-    }
-
-    /// Send a user message to a conversation and wait for the OK tool-call response.
-    pub async fn send_user_message_and_wait_ok(
-        &mut self,
-        message: &str,
-        session_id: &str,
-    ) -> anyhow::Result<()> {
-        let req_id = self
-            .send_user_message_tool_call(message, session_id)
-            .await?;
-        let _ = self
-            .read_stream_until_response_message(RequestId::Integer(req_id))
-            .await?;
-        Ok(())
-    }
-
-    /// Wait until an agent_message notification arrives; returns its params.
-    pub async fn wait_for_agent_message(&mut self) -> anyhow::Result<serde_json::Value> {
-        let note = self
-            .read_stream_until_notification_method("agent_message")
-            .await?;
-        note.params
-            .ok_or_else(|| anyhow::format_err!("agent_message missing params"))
-    }
-
     async fn send_request(
         &mut self,
         method: &str,
@@ -422,51 +329,53 @@ impl McpProcess {
         }
     }
 
-    pub async fn read_stream_until_notification_method(
-        &mut self,
-        method: &str,
-    ) -> anyhow::Result<JSONRPCNotification> {
-        loop {
-            let message = self.read_jsonrpc_message().await?;
-            match message {
-                JSONRPCMessage::Notification(n) => {
-                    if n.method == method {
-                        return Ok(n);
-                    }
-                }
-                JSONRPCMessage::Request(_) => {
-                    // ignore
-                }
-                JSONRPCMessage::Error(_) => {
-                    anyhow::bail!("unexpected JSONRPCMessage::Error: {message:?}");
-                }
-                JSONRPCMessage::Response(_) => {
-                    // ignore
-                }
-            }
-        }
-    }
-
     pub async fn read_stream_until_configured_response_message(
         &mut self,
     ) -> anyhow::Result<String> {
+        let mut sid_old: Option<String> = None;
+        let mut sid_new: Option<String> = None;
         loop {
             let message = self.read_jsonrpc_message().await?;
             eprint!("message: {message:?}");
 
             match message {
                 JSONRPCMessage::Notification(notification) => {
-                    if notification.method == "session_configured" {
-                        if let Some(params) = notification.params {
+                    if let Some(params) = notification.params {
+                        // Back-compat schema: method == "codex/event" and msg.type == "session_configured"
+                        if notification.method == "codex/event" {
+                            if let Some(msg) = params.get("msg") {
+                                if msg.get("type").and_then(|v| v.as_str())
+                                    == Some("session_configured")
+                                {
+                                    if let Some(session_id) =
+                                        msg.get("session_id").and_then(|v| v.as_str())
+                                    {
+                                        sid_old = Some(session_id.to_string());
+                                    }
+                                }
+                            }
+                        }
+                        // New schema: method is the Display of EventMsg::SessionConfigured => "SessionConfigured"
+                        if notification.method == "session_configured" {
                             if let Some(msg) = params.get("msg") {
                                 if let Some(session_id) =
                                     msg.get("session_id").and_then(|v| v.as_str())
                                 {
-                                    return Ok(session_id.to_string());
+                                    sid_new = Some(session_id.to_string());
                                 }
                             }
                         }
                     }
+
+                    if sid_old.is_some() && sid_new.is_some() {
+                        // Both seen, they must match
+                        assert_eq!(
+                            sid_old.as_ref().unwrap(),
+                            sid_new.as_ref().unwrap(),
+                            "session_id mismatch between old and new schema"
+                        );
+                        return Ok(sid_old.unwrap());
+                    }
                 }
                 JSONRPCMessage::Request(_) => {
                     anyhow::bail!("unexpected JSONRPCMessage::Request: {message:?}");

codex-rs/mcp-server/tests/create_conversation.rs

@@ -1,7 +1,8 @@
 #![allow(clippy::expect_used, clippy::unwrap_used)]
 
+use std::path::Path;
+
 use mcp_test_support::McpProcess;
-use mcp_test_support::create_config_toml;
 use mcp_test_support::create_final_assistant_message_sse_response;
 use mcp_test_support::create_mock_chat_completions_server;
 use mcp_types::JSONRPCResponse;
@@ -102,4 +103,26 @@ async fn test_conversation_create_and_send_message_ok() {
     drop(server);
 }
 
-// create_config_toml is provided by tests/common
+// Helper to create a config.toml pointing at the mock model server.
+fn create_config_toml(codex_home: &Path, server_uri: &str) -> std::io::Result<()> {
+    let config_toml = codex_home.join("config.toml");
+    std::fs::write(
+        config_toml,
+        format!(
+            r#"
+model = "mock-model"
+approval_policy = "never"
+sandbox_mode = "danger-full-access"
+
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "chat"
+request_max_retries = 0
+stream_max_retries = 0
+"#
+        ),
+    )
+}

codex-rs/mcp-server/tests/interrupt.rs

@@ -1,17 +1,17 @@
 #![cfg(unix)]
 // Support code lives in the `mcp_test_support` crate under tests/common.
 
+use std::path::Path;
+
 use codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR;
 use codex_mcp_server::CodexToolCallParam;
 use mcp_types::JSONRPCResponse;
-use mcp_types::ModelContextProtocolNotification;
 use mcp_types::RequestId;
 use serde_json::json;
 use tempfile::TempDir;
 use tokio::time::timeout;
 
 use mcp_test_support::McpProcess;
-use mcp_test_support::create_config_toml;
 use mcp_test_support::create_mock_chat_completions_server;
 use mcp_test_support::create_shell_sse_response;
 
@@ -66,7 +66,7 @@ async fn shell_command_interruption() -> anyhow::Result<()> {
 
     // Create Codex configuration
     let codex_home = TempDir::new()?;
-    create_config_toml(codex_home.path(), &server.uri())?;
+    create_config_toml(codex_home.path(), server.uri())?;
     let mut mcp_process = McpProcess::new(codex_home.path()).await?;
     timeout(DEFAULT_READ_TIMEOUT, mcp_process.initialize()).await??;
 
@@ -95,7 +95,7 @@ async fn shell_command_interruption() -> anyhow::Result<()> {
     // Send interrupt notification
     mcp_process
         .send_notification(
-            mcp_types::CancelledNotification::METHOD,
+            "notifications/cancelled",
             Some(json!({ "requestId": codex_request_id })),
         )
         .await?;
@@ -126,7 +126,7 @@ async fn shell_command_interruption() -> anyhow::Result<()> {
     // Send interrupt notification
     mcp_process
         .send_notification(
-            mcp_types::CancelledNotification::METHOD,
+            "notifications/cancelled",
             Some(json!({ "requestId": codex_reply_request_id })),
         )
         .await?;
@@ -148,3 +148,30 @@ async fn shell_command_interruption() -> anyhow::Result<()> {
     );
     Ok(())
 }
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+fn create_config_toml(codex_home: &Path, server_uri: String) -> std::io::Result<()> {
+    let config_toml = codex_home.join("config.toml");
+    std::fs::write(
+        config_toml,
+        format!(
+            r#"
+model = "mock-model"
+approval_policy = "never"
+sandbox_mode = "danger-full-access"
+
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "chat"
+request_max_retries = 0
+stream_max_retries = 0
+"#
+        ),
+    )
+}

codex-rs/mcp-server/tests/send_message.rs

@@ -1,10 +1,11 @@
 #![allow(clippy::expect_used)]
 
+use std::path::Path;
 use std::thread::sleep;
 use std::time::Duration;
 
+use codex_mcp_server::CodexToolCallParam;
 use mcp_test_support::McpProcess;
-use mcp_test_support::create_config_toml;
 use mcp_test_support::create_final_assistant_message_sse_response;
 use mcp_test_support::create_mock_chat_completions_server;
 use mcp_types::JSONRPC_VERSION;
@@ -17,11 +18,13 @@ use tokio::time::timeout;
 
 const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+#[tokio::test]
 async fn test_send_message_success() {
-    // Spin up a mock completions server that ends the Codex turn for the send-user-message call.
+    // Spin up a mock completions server that immediately ends the Codex turn.
+    // Two Codex turns hit the mock model (session start + send-user-message). Provide two SSE responses.
     let responses = vec![
         create_final_assistant_message_sse_response("Done").expect("build mock assistant message"),
+        create_final_assistant_message_sse_response("Done").expect("build mock assistant message"),
     ];
     let server = create_mock_chat_completions_server(responses).await;
 
@@ -38,11 +41,29 @@ async fn test_send_message_success() {
         .expect("init timed out")
         .expect("init failed");
 
-    // Create a conversation using the tool and get its conversation_id
-    let session_id = mcp_process
-        .create_conversation_and_get_id("", "mock-model", "/repo")
+    // Kick off a Codex session so we have a valid session_id.
+    let codex_request_id = mcp_process
+        .send_codex_tool_call(CodexToolCallParam {
+            prompt: "Start a session".to_string(),
+            ..Default::default()
+        })
         .await
-        .expect("create conversation");
+        .expect("send codex tool call");
+
+    // Wait for the session_configured event to get the session_id.
+    let session_id = mcp_process
+        .read_stream_until_configured_response_message()
+        .await
+        .expect("read session_configured");
+
+    // The original codex call will finish quickly given our mock; consume its response.
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp_process.read_stream_until_response_message(RequestId::Integer(codex_request_id)),
+    )
+    .await
+    .expect("codex response timeout")
+    .expect("codex response error");
 
     // Now exercise the send-user-message tool.
     let send_msg_request_id = mcp_process
@@ -78,13 +99,13 @@ async fn test_send_message_success() {
         response
     );
     // wait for the server to hear the user message
-    sleep(Duration::from_secs(1));
+    sleep(Duration::from_secs(5));
 
     // Ensure the server and tempdir live until end of test
     drop(server);
 }
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+#[tokio::test]
 async fn test_send_message_session_not_found() {
     // Start MCP without creating a Codex session
     let codex_home = TempDir::new().expect("tempdir");
@@ -114,4 +135,29 @@ async fn test_send_message_session_not_found() {
     assert_eq!(result["isError"], json!(true));
 }
 
-// Helpers are provided by tests/common
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+fn create_config_toml(codex_home: &Path, server_uri: &str) -> std::io::Result<()> {
+    let config_toml = codex_home.join("config.toml");
+    std::fs::write(
+        config_toml,
+        format!(
+            r#"
+model = "mock-model"
+approval_policy = "never"
+sandbox_mode = "danger-full-access"
+
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "chat"
+request_max_retries = 0
+stream_max_retries = 0
+"#
+        ),
+    )
+}

codex-rs/mcp-server/tests/stream_conversation.rs

@@ -1,251 +0,0 @@
-#![allow(clippy::expect_used, clippy::unwrap_used)]
-
-use mcp_test_support::McpProcess;
-use mcp_test_support::create_config_toml;
-use mcp_test_support::create_final_assistant_message_sse_response;
-use mcp_test_support::create_mock_chat_completions_server;
-use mcp_types::JSONRPCNotification;
-use mcp_types::ModelContextProtocolNotification;
-use pretty_assertions::assert_eq;
-use serde_json::json;
-use tempfile::TempDir;
-use tokio::time::timeout;
-
-const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(3);
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn test_connect_then_send_receives_initial_state_and_notifications() {
-    let responses = vec![
-        create_final_assistant_message_sse_response("Done").expect("build mock assistant message"),
-    ];
-    let server = create_mock_chat_completions_server(responses).await;
-
-    let codex_home = TempDir::new().expect("create temp dir");
-    create_config_toml(codex_home.path(), &server.uri()).expect("write config.toml");
-
-    let mut mcp = McpProcess::new(codex_home.path())
-        .await
-        .expect("spawn mcp process");
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize())
-        .await
-        .expect("init timeout")
-        .expect("init failed");
-
-    // Create conversation
-    let conv_id = mcp
-        .create_conversation_and_get_id("", "o3", "/repo")
-        .await
-        .expect("create conversation");
-
-    // Connect the stream
-    let (_stream_req, params) = mcp
-        .connect_stream_and_expect_initial_state(&conv_id)
-        .await
-        .expect("initial_state params");
-    let expected_params = json!({
-        "_meta": {
-            "conversationId": conv_id.as_str(),
-        },
-        "initial_state": {
-            "events": []
-        }
-    });
-    assert_eq!(params, expected_params);
-
-    // Send a message and expect a subsequent notification (non-initial_state)
-    mcp.send_user_message_and_wait_ok("Hello there", &conv_id)
-        .await
-        .expect("send message ok");
-
-    // Read until we see an event notification (new schema example: agent_message)
-    let params = mcp.wait_for_agent_message().await.expect("agent message");
-    let expected_params = json!({
-        "msg": {
-            "type": "agent_message",
-            "message": "Done"
-        }
-    });
-    assert_eq!(params, expected_params);
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn test_send_then_connect_receives_initial_state_with_message() {
-    let responses = vec![
-        create_final_assistant_message_sse_response("Done").expect("build mock assistant message"),
-    ];
-    let server = create_mock_chat_completions_server(responses).await;
-
-    let codex_home = TempDir::new().expect("create temp dir");
-    create_config_toml(codex_home.path(), &server.uri()).expect("write config.toml");
-
-    let mut mcp = McpProcess::new(codex_home.path())
-        .await
-        .expect("spawn mcp process");
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize())
-        .await
-        .expect("init timeout")
-        .expect("init failed");
-
-    // Create conversation
-    let conv_id = mcp
-        .create_conversation_and_get_id("", "o3", "/repo")
-        .await
-        .expect("create conversation");
-
-    // Send a message BEFORE connecting stream
-    mcp.send_user_message_and_wait_ok("Hello world", &conv_id)
-        .await
-        .expect("send message ok");
-
-    // Now connect stream and expect InitialState with the prior message included
-    let (_stream_req, params) = mcp
-        .connect_stream_and_expect_initial_state(&conv_id)
-        .await
-        .expect("initial_state params");
-    let events = params["initial_state"]["events"]
-        .as_array()
-        .expect("events array");
-    if !events.iter().any(|ev| {
-        ev.get("msg")
-            .and_then(|m| m.get("type"))
-            .and_then(|t| t.as_str())
-            == Some("agent_message")
-            && ev
-                .get("msg")
-                .and_then(|m| m.get("message"))
-                .and_then(|t| t.as_str())
-                == Some("Done")
-    }) {
-        // Fallback to live notification if not present in initial state
-        let note: JSONRPCNotification = timeout(
-            DEFAULT_READ_TIMEOUT,
-            mcp.read_stream_until_notification_method("agent_message"),
-        )
-        .await
-        .expect("event note timeout")
-        .expect("event note err");
-        let params = note.params.expect("params");
-        let expected_params = json!({
-            "msg": {
-                "type": "agent_message",
-                "message": "Done"
-            }
-        });
-        assert_eq!(params, expected_params);
-    }
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn test_cancel_stream_then_reconnect_catches_up_initial_state() {
-    // One response is sufficient for the assertions in this test
-    let responses = vec![
-        create_final_assistant_message_sse_response("Done 1")
-            .expect("build mock assistant message"),
-        create_final_assistant_message_sse_response("Done 2")
-            .expect("build mock assistant message"),
-    ];
-    let server = create_mock_chat_completions_server(responses).await;
-
-    let codex_home = TempDir::new().expect("create temp dir");
-    create_config_toml(codex_home.path(), &server.uri()).expect("write config.toml");
-
-    let mut mcp = McpProcess::new(codex_home.path())
-        .await
-        .expect("spawn mcp process");
-    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize())
-        .await
-        .expect("init timeout")
-        .expect("init failed");
-
-    // Create and connect stream A
-    let conv_id = mcp
-        .create_conversation_and_get_id("", "o3", "/repo")
-        .await
-        .expect("create");
-    let (stream_a_id, _params) = mcp
-        .connect_stream_and_expect_initial_state(&conv_id)
-        .await
-        .expect("stream A initial_state");
-
-    // Send M1 and ensure we get live agent_message
-    mcp.send_user_message_and_wait_ok("Hello M1", &conv_id)
-        .await
-        .expect("send M1");
-    let _params = mcp.wait_for_agent_message().await.expect("agent M1");
-
-    // Ensure the first task has fully completed before cancelling the stream
-    // so that the session is no longer marked as running.
-    let _ = mcp
-        .read_stream_until_notification_method("task_complete")
-        .await
-        .expect("task complete");
-
-    // Cancel stream A
-    mcp.send_notification(
-        mcp_types::CancelledNotification::METHOD,
-        Some(json!({ "requestId": stream_a_id })),
-    )
-    .await
-    .expect("send cancelled");
-
-    // Send M2 while stream is cancelled; we should NOT get agent_message live
-    mcp.send_user_message_and_wait_ok("Hello M2", &conv_id)
-        .await
-        .expect("send M2");
-    let maybe = mcp
-        .maybe_wait_for_agent_message(std::time::Duration::from_millis(300))
-        .await
-        .expect("maybe wait");
-    assert!(
-        maybe.is_none(),
-        "should not get live agent_message after cancel"
-    );
-
-    // Connect stream B and expect initial_state that includes the response
-    let (_stream_req, params) = mcp
-        .connect_stream_and_expect_initial_state(&conv_id)
-        .await
-        .expect("stream B initial_state");
-    let events = params["initial_state"]["events"]
-        .as_array()
-        .expect("events array");
-    let expected = vec![
-        json!({
-            "msg": {
-                "type": "task_started",
-            },
-        }),
-        json!({
-            "msg": {
-                "message": "Done 1",
-                "type": "agent_message",
-            },
-        }),
-        json!({
-            "msg": {
-                "last_agent_message": "Done 1",
-                "type": "task_complete",
-            },
-        }),
-        json!({
-            "msg": {
-                "type": "task_started",
-            },
-        }),
-        json!({
-            "msg": {
-                "message": "Done 2",
-                "type": "agent_message",
-            },
-        }),
-        json!({
-            "msg": {
-                "last_agent_message": "Done 2",
-                "type": "task_complete",
-            },
-        }),
-    ];
-    assert_eq!(*events, expected);
-}
-
-//

codex-rs/ollama/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+edition = "2024"
+name = "codex-ollama"
+version = { workspace = true }
+
+[lib]
+name = "codex_ollama"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+async-stream = "0.3"
+bytes = "1.10.1"
+codex-core = { path = "../core" }
+futures = "0.3"
+reqwest = { version = "0.12", features = ["json", "stream"] }
+serde_json = "1"
+tokio = { version = "1", features = [
+    "io-std",
+    "macros",
+    "process",
+    "rt-multi-thread",
+    "signal",
+] }
+toml = "0.9.2"
+tracing = { version = "0.1.41", features = ["log"] }
+wiremock = "0.6"
+
+[dev-dependencies]
+tempfile = "3"

codex-rs/ollama/src/client.rs

@@ -0,0 +1,351 @@
+use bytes::BytesMut;
+use futures::StreamExt;
+use futures::stream::BoxStream;
+use serde_json::Value as JsonValue;
+use std::collections::VecDeque;
+use std::io;
+
+use crate::parser::pull_events_from_value;
+use crate::pull::PullEvent;
+use crate::pull::PullProgressReporter;
+use crate::url::base_url_to_host_root;
+use crate::url::is_openai_compatible_base_url;
+use codex_core::BUILT_IN_OSS_MODEL_PROVIDER_ID;
+use codex_core::ModelProviderInfo;
+use codex_core::WireApi;
+use codex_core::config::Config;
+
+const OLLAMA_CONNECTION_ERROR: &str = "No running Ollama server detected. Start it with: `ollama serve` (after installing). Install instructions: https://github.com/ollama/ollama?tab=readme-ov-file#ollama";
+
+/// Client for interacting with a local Ollama instance.
+pub struct OllamaClient {
+    client: reqwest::Client,
+    host_root: String,
+    uses_openai_compat: bool,
+}
+
+impl OllamaClient {
+    /// Construct a client for the built‑in open‑source ("oss") model provider
+    /// and verify that a local Ollama server is reachable. If no server is
+    /// detected, returns an error with helpful installation/run instructions.
+    pub async fn try_from_oss_provider(config: &Config) -> io::Result<Self> {
+        // Note that we must look up the provider from the Config to ensure that
+        // any overrides the user has in their config.toml are taken into
+        // account.
+        let provider = config
+            .model_providers
+            .get(BUILT_IN_OSS_MODEL_PROVIDER_ID)
+            .ok_or_else(|| {
+                io::Error::new(
+                    io::ErrorKind::NotFound,
+                    format!("Built-in provider {BUILT_IN_OSS_MODEL_PROVIDER_ID} not found",),
+                )
+            })?;
+
+        Self::try_from_provider(provider).await
+    }
+
+    #[cfg(test)]
+    async fn try_from_provider_with_base_url(base_url: &str) -> io::Result<Self> {
+        let provider = codex_core::create_oss_provider_with_base_url(base_url);
+        Self::try_from_provider(&provider).await
+    }
+
+    /// Build a client from a provider definition and verify the server is reachable.
+    async fn try_from_provider(provider: &ModelProviderInfo) -> io::Result<Self> {
+        #![allow(clippy::expect_used)]
+        let base_url = provider
+            .base_url
+            .as_ref()
+            .expect("oss provider must have a base_url");
+        let uses_openai_compat = is_openai_compatible_base_url(base_url)
+            || matches!(provider.wire_api, WireApi::Chat)
+                && is_openai_compatible_base_url(base_url);
+        let host_root = base_url_to_host_root(base_url);
+        let client = reqwest::Client::builder()
+            .connect_timeout(std::time::Duration::from_secs(5))
+            .build()
+            .unwrap_or_else(|_| reqwest::Client::new());
+        let client = Self {
+            client,
+            host_root,
+            uses_openai_compat,
+        };
+        client.probe_server().await?;
+        Ok(client)
+    }
+
+    /// Probe whether the server is reachable by hitting the appropriate health endpoint.
+    async fn probe_server(&self) -> io::Result<()> {
+        let url = if self.uses_openai_compat {
+            format!("{}/v1/models", self.host_root.trim_end_matches('/'))
+        } else {
+            format!("{}/api/tags", self.host_root.trim_end_matches('/'))
+        };
+        let resp = self.client.get(url).send().await.map_err(|err| {
+            tracing::warn!("Failed to connect to Ollama server: {err:?}");
+            io::Error::other(OLLAMA_CONNECTION_ERROR)
+        })?;
+        if resp.status().is_success() {
+            Ok(())
+        } else {
+            tracing::warn!(
+                "Failed to probe server at {}: HTTP {}",
+                self.host_root,
+                resp.status()
+            );
+            Err(io::Error::other(OLLAMA_CONNECTION_ERROR))
+        }
+    }
+
+    /// Return the list of model names known to the local Ollama instance.
+    pub async fn fetch_models(&self) -> io::Result<Vec<String>> {
+        let tags_url = format!("{}/api/tags", self.host_root.trim_end_matches('/'));
+        let resp = self
+            .client
+            .get(tags_url)
+            .send()
+            .await
+            .map_err(io::Error::other)?;
+        if !resp.status().is_success() {
+            return Ok(Vec::new());
+        }
+        let val = resp.json::<JsonValue>().await.map_err(io::Error::other)?;
+        let names = val
+            .get("models")
+            .and_then(|m| m.as_array())
+            .map(|arr| {
+                arr.iter()
+                    .filter_map(|v| v.get("name").and_then(|n| n.as_str()))
+                    .map(|s| s.to_string())
+                    .collect::<Vec<_>>()
+            })
+            .unwrap_or_default();
+        Ok(names)
+    }
+
+    /// Start a model pull and emit streaming events. The returned stream ends when
+    /// a Success event is observed or the server closes the connection.
+    pub async fn pull_model_stream(
+        &self,
+        model: &str,
+    ) -> io::Result<BoxStream<'static, PullEvent>> {
+        let url = format!("{}/api/pull", self.host_root.trim_end_matches('/'));
+        let resp = self
+            .client
+            .post(url)
+            .json(&serde_json::json!({"model": model, "stream": true}))
+            .send()
+            .await
+            .map_err(io::Error::other)?;
+        if !resp.status().is_success() {
+            return Err(io::Error::other(format!(
+                "failed to start pull: HTTP {}",
+                resp.status()
+            )));
+        }
+
+        let mut stream = resp.bytes_stream();
+        let mut buf = BytesMut::new();
+        let _pending: VecDeque<PullEvent> = VecDeque::new();
+
+        // Using an async stream adaptor backed by unfold-like manual loop.
+        let s = async_stream::stream! {
+            while let Some(chunk) = stream.next().await {
+                match chunk {
+                    Ok(bytes) => {
+                        buf.extend_from_slice(&bytes);
+                        while let Some(pos) = buf.iter().position(|b| *b == b'\n') {
+                            let line = buf.split_to(pos + 1);
+                            if let Ok(text) = std::str::from_utf8(&line) {
+                                let text = text.trim();
+                                if text.is_empty() { continue; }
+                                if let Ok(value) = serde_json::from_str::<JsonValue>(text) {
+                                    for ev in pull_events_from_value(&value) { yield ev; }
+                                    if let Some(err_msg) = value.get("error").and_then(|e| e.as_str()) {
+                                        yield PullEvent::Error(err_msg.to_string());
+                                        return;
+                                    }
+                                    if let Some(status) = value.get("status").and_then(|s| s.as_str()) {
+                                        if status == "success" { yield PullEvent::Success; return; }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    Err(_) => {
+                        // Connection error: end the stream.
+                        return;
+                    }
+                }
+            }
+        };
+
+        Ok(Box::pin(s))
+    }
+
+    /// High-level helper to pull a model and drive a progress reporter.
+    pub async fn pull_with_reporter(
+        &self,
+        model: &str,
+        reporter: &mut dyn PullProgressReporter,
+    ) -> io::Result<()> {
+        reporter.on_event(&PullEvent::Status(format!("Pulling model {model}...")))?;
+        let mut stream = self.pull_model_stream(model).await?;
+        while let Some(event) = stream.next().await {
+            reporter.on_event(&event)?;
+            match event {
+                PullEvent::Success => {
+                    return Ok(());
+                }
+                PullEvent::Error(err) => {
+                    // Empirically, ollama returns a 200 OK response even when
+                    // the output stream includes an error message. Verify with:
+                    //
+                    // `curl -i http://localhost:11434/api/pull -d '{ "model": "foobarbaz" }'`
+                    //
+                    // As such, we have to check the event stream, not the
+                    // HTTP response status, to determine whether to return Err.
+                    return Err(io::Error::other(format!("Pull failed: {err}")));
+                }
+                PullEvent::ChunkProgress { .. } | PullEvent::Status(_) => {
+                    continue;
+                }
+            }
+        }
+        Err(io::Error::other(
+            "Pull stream ended unexpectedly without success.",
+        ))
+    }
+
+    /// Low-level constructor given a raw host root, e.g. "http://localhost:11434".
+    #[cfg(test)]
+    fn from_host_root(host_root: impl Into<String>) -> Self {
+        let client = reqwest::Client::builder()
+            .connect_timeout(std::time::Duration::from_secs(5))
+            .build()
+            .unwrap_or_else(|_| reqwest::Client::new());
+        Self {
+            client,
+            host_root: host_root.into(),
+            uses_openai_compat: false,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::expect_used, clippy::unwrap_used)]
+    use super::*;
+
+    // Happy-path tests using a mock HTTP server; skip if sandbox network is disabled.
+    #[tokio::test]
+    async fn test_fetch_models_happy_path() {
+        if std::env::var(codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR).is_ok() {
+            tracing::info!(
+                "{} is set; skipping test_fetch_models_happy_path",
+                codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR
+            );
+            return;
+        }
+
+        let server = wiremock::MockServer::start().await;
+        wiremock::Mock::given(wiremock::matchers::method("GET"))
+            .and(wiremock::matchers::path("/api/tags"))
+            .respond_with(
+                wiremock::ResponseTemplate::new(200).set_body_raw(
+                    serde_json::json!({
+                        "models": [ {"name": "llama3.2:3b"}, {"name":"mistral"} ]
+                    })
+                    .to_string(),
+                    "application/json",
+                ),
+            )
+            .mount(&server)
+            .await;
+
+        let client = OllamaClient::from_host_root(server.uri());
+        let models = client.fetch_models().await.expect("fetch models");
+        assert!(models.contains(&"llama3.2:3b".to_string()));
+        assert!(models.contains(&"mistral".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_probe_server_happy_path_openai_compat_and_native() {
+        if std::env::var(codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR).is_ok() {
+            tracing::info!(
+                "{} set; skipping test_probe_server_happy_path_openai_compat_and_native",
+                codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR
+            );
+            return;
+        }
+
+        let server = wiremock::MockServer::start().await;
+
+        // Native endpoint
+        wiremock::Mock::given(wiremock::matchers::method("GET"))
+            .and(wiremock::matchers::path("/api/tags"))
+            .respond_with(wiremock::ResponseTemplate::new(200))
+            .mount(&server)
+            .await;
+        let native = OllamaClient::from_host_root(server.uri());
+        native.probe_server().await.expect("probe native");
+
+        // OpenAI compatibility endpoint
+        wiremock::Mock::given(wiremock::matchers::method("GET"))
+            .and(wiremock::matchers::path("/v1/models"))
+            .respond_with(wiremock::ResponseTemplate::new(200))
+            .mount(&server)
+            .await;
+        let ollama_client =
+            OllamaClient::try_from_provider_with_base_url(&format!("{}/v1", server.uri()))
+                .await
+                .expect("probe OpenAI compat");
+        ollama_client
+            .probe_server()
+            .await
+            .expect("probe OpenAI compat");
+    }
+
+    #[tokio::test]
+    async fn test_try_from_oss_provider_ok_when_server_running() {
+        if std::env::var(codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR).is_ok() {
+            tracing::info!(
+                "{} set; skipping test_try_from_oss_provider_ok_when_server_running",
+                codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR
+            );
+            return;
+        }
+
+        let server = wiremock::MockServer::start().await;
+
+        // OpenAI‑compat models endpoint responds OK.
+        wiremock::Mock::given(wiremock::matchers::method("GET"))
+            .and(wiremock::matchers::path("/v1/models"))
+            .respond_with(wiremock::ResponseTemplate::new(200))
+            .mount(&server)
+            .await;
+
+        OllamaClient::try_from_provider_with_base_url(&format!("{}/v1", server.uri()))
+            .await
+            .expect("client should be created when probe succeeds");
+    }
+
+    #[tokio::test]
+    async fn test_try_from_oss_provider_err_when_server_missing() {
+        if std::env::var(codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR).is_ok() {
+            tracing::info!(
+                "{} set; skipping test_try_from_oss_provider_err_when_server_missing",
+                codex_core::spawn::CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR
+            );
+            return;
+        }
+
+        let server = wiremock::MockServer::start().await;
+        let err = OllamaClient::try_from_provider_with_base_url(&format!("{}/v1", server.uri()))
+            .await
+            .err()
+            .expect("expected error");
+        assert_eq!(OLLAMA_CONNECTION_ERROR, err.to_string());
+    }
+}

codex-rs/ollama/src/lib.rs

@@ -0,0 +1,44 @@
+mod client;
+mod parser;
+mod pull;
+mod url;
+
+pub use client::OllamaClient;
+use codex_core::config::Config;
+pub use pull::CliProgressReporter;
+pub use pull::PullEvent;
+pub use pull::PullProgressReporter;
+pub use pull::TuiProgressReporter;
+
+/// Default OSS model to use when `--oss` is passed without an explicit `-m`.
+pub const DEFAULT_OSS_MODEL: &str = "gpt-oss:20b";
+
+/// Prepare the local OSS environment when `--oss` is selected.
+///
+/// - Ensures a local Ollama server is reachable.
+/// - Checks if the model exists locally and pulls it if missing.
+pub async fn ensure_oss_ready(config: &Config) -> std::io::Result<()> {
+    // Only download when the requested model is the default OSS model (or when -m is not provided).
+    let model = config.model.as_ref();
+
+    // Verify local Ollama is reachable.
+    let ollama_client = crate::OllamaClient::try_from_oss_provider(config).await?;
+
+    // If the model is not present locally, pull it.
+    match ollama_client.fetch_models().await {
+        Ok(models) => {
+            if !models.iter().any(|m| m == model) {
+                let mut reporter = crate::CliProgressReporter::new();
+                ollama_client
+                    .pull_with_reporter(model, &mut reporter)
+                    .await?;
+            }
+        }
+        Err(err) => {
+            // Not fatal; higher layers may still proceed and surface errors later.
+            tracing::warn!("Failed to query local models from Ollama: {}.", err);
+        }
+    }
+
+    Ok(())
+}

codex-rs/ollama/src/parser.rs

@@ -0,0 +1,82 @@
+use serde_json::Value as JsonValue;
+
+use crate::pull::PullEvent;
+
+// Convert a single JSON object representing a pull update into one or more events.
+pub(crate) fn pull_events_from_value(value: &JsonValue) -> Vec<PullEvent> {
+    let mut events = Vec::new();
+    if let Some(status) = value.get("status").and_then(|s| s.as_str()) {
+        events.push(PullEvent::Status(status.to_string()));
+        if status == "success" {
+            events.push(PullEvent::Success);
+        }
+    }
+    let digest = value
+        .get("digest")
+        .and_then(|d| d.as_str())
+        .unwrap_or("")
+        .to_string();
+    let total = value.get("total").and_then(|t| t.as_u64());
+    let completed = value.get("completed").and_then(|t| t.as_u64());
+    if total.is_some() || completed.is_some() {
+        events.push(PullEvent::ChunkProgress {
+            digest,
+            total,
+            completed,
+        });
+    }
+    events
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_pull_events_decoder_status_and_success() {
+        let v: JsonValue = serde_json::json!({"status":"verifying"});
+        let events = pull_events_from_value(&v);
+        assert!(matches!(events.as_slice(), [PullEvent::Status(s)] if s == "verifying"));
+
+        let v2: JsonValue = serde_json::json!({"status":"success"});
+        let events2 = pull_events_from_value(&v2);
+        assert_eq!(events2.len(), 2);
+        assert!(matches!(events2[0], PullEvent::Status(ref s) if s == "success"));
+        assert!(matches!(events2[1], PullEvent::Success));
+    }
+
+    #[test]
+    fn test_pull_events_decoder_progress() {
+        let v: JsonValue = serde_json::json!({"digest":"sha256:abc","total":100});
+        let events = pull_events_from_value(&v);
+        assert_eq!(events.len(), 1);
+        match &events[0] {
+            PullEvent::ChunkProgress {
+                digest,
+                total,
+                completed,
+            } => {
+                assert_eq!(digest, "sha256:abc");
+                assert_eq!(*total, Some(100));
+                assert_eq!(*completed, None);
+            }
+            _ => panic!("expected ChunkProgress"),
+        }
+
+        let v2: JsonValue = serde_json::json!({"digest":"sha256:def","completed":42});
+        let events2 = pull_events_from_value(&v2);
+        assert_eq!(events2.len(), 1);
+        match &events2[0] {
+            PullEvent::ChunkProgress {
+                digest,
+                total,
+                completed,
+            } => {
+                assert_eq!(digest, "sha256:def");
+                assert_eq!(*total, None);
+                assert_eq!(*completed, Some(42));
+            }
+            _ => panic!("expected ChunkProgress"),
+        }
+    }
+}

codex-rs/ollama/src/pull.rs

@@ -0,0 +1,147 @@
+use std::collections::HashMap;
+use std::io;
+use std::io::Write;
+
+/// Events emitted while pulling a model from Ollama.
+#[derive(Debug, Clone)]
+pub enum PullEvent {
+    /// A human-readable status message (e.g., "verifying", "writing").
+    Status(String),
+    /// Byte-level progress update for a specific layer digest.
+    ChunkProgress {
+        digest: String,
+        total: Option<u64>,
+        completed: Option<u64>,
+    },
+    /// The pull finished successfully.
+    Success,
+
+    /// Error event with a message.
+    Error(String),
+}
+
+/// A simple observer for pull progress events. Implementations decide how to
+/// render progress (CLI, TUI, logs, ...).
+pub trait PullProgressReporter {
+    fn on_event(&mut self, event: &PullEvent) -> io::Result<()>;
+}
+
+/// A minimal CLI reporter that writes inline progress to stderr.
+pub struct CliProgressReporter {
+    printed_header: bool,
+    last_line_len: usize,
+    last_completed_sum: u64,
+    last_instant: std::time::Instant,
+    totals_by_digest: HashMap<String, (u64, u64)>,
+}
+
+impl Default for CliProgressReporter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl CliProgressReporter {
+    pub fn new() -> Self {
+        Self {
+            printed_header: false,
+            last_line_len: 0,
+            last_completed_sum: 0,
+            last_instant: std::time::Instant::now(),
+            totals_by_digest: HashMap::new(),
+        }
+    }
+}
+
+impl PullProgressReporter for CliProgressReporter {
+    fn on_event(&mut self, event: &PullEvent) -> io::Result<()> {
+        let mut out = std::io::stderr();
+        match event {
+            PullEvent::Status(status) => {
+                // Avoid noisy manifest messages; otherwise show status inline.
+                if status.eq_ignore_ascii_case("pulling manifest") {
+                    return Ok(());
+                }
+                let pad = self.last_line_len.saturating_sub(status.len());
+                let line = format!("\r{status}{}", " ".repeat(pad));
+                self.last_line_len = status.len();
+                out.write_all(line.as_bytes())?;
+                out.flush()
+            }
+            PullEvent::ChunkProgress {
+                digest,
+                total,
+                completed,
+            } => {
+                if let Some(t) = *total {
+                    self.totals_by_digest
+                        .entry(digest.clone())
+                        .or_insert((0, 0))
+                        .0 = t;
+                }
+                if let Some(c) = *completed {
+                    self.totals_by_digest
+                        .entry(digest.clone())
+                        .or_insert((0, 0))
+                        .1 = c;
+                }
+
+                let (sum_total, sum_completed) = self
+                    .totals_by_digest
+                    .values()
+                    .fold((0u64, 0u64), |acc, (t, c)| (acc.0 + *t, acc.1 + *c));
+                if sum_total > 0 {
+                    if !self.printed_header {
+                        let gb = (sum_total as f64) / (1024.0 * 1024.0 * 1024.0);
+                        let header = format!("Downloading model: total {gb:.2} GB\n");
+                        out.write_all(b"\r\x1b[2K")?;
+                        out.write_all(header.as_bytes())?;
+                        self.printed_header = true;
+                    }
+                    let now = std::time::Instant::now();
+                    let dt = now
+                        .duration_since(self.last_instant)
+                        .as_secs_f64()
+                        .max(0.001);
+                    let dbytes = sum_completed.saturating_sub(self.last_completed_sum) as f64;
+                    let speed_mb_s = dbytes / (1024.0 * 1024.0) / dt;
+                    self.last_completed_sum = sum_completed;
+                    self.last_instant = now;
+
+                    let done_gb = (sum_completed as f64) / (1024.0 * 1024.0 * 1024.0);
+                    let total_gb = (sum_total as f64) / (1024.0 * 1024.0 * 1024.0);
+                    let pct = (sum_completed as f64) * 100.0 / (sum_total as f64);
+                    let text =
+                        format!("{done_gb:.2}/{total_gb:.2} GB ({pct:.1}%) {speed_mb_s:.1} MB/s");
+                    let pad = self.last_line_len.saturating_sub(text.len());
+                    let line = format!("\r{text}{}", " ".repeat(pad));
+                    self.last_line_len = text.len();
+                    out.write_all(line.as_bytes())?;
+                    out.flush()
+                } else {
+                    Ok(())
+                }
+            }
+            PullEvent::Error(_) => {
+                // This will be handled by the caller, so we don't do anything
+                // here or the error will be printed twice.
+                Ok(())
+            }
+            PullEvent::Success => {
+                out.write_all(b"\n")?;
+                out.flush()
+            }
+        }
+    }
+}
+
+/// For now the TUI reporter delegates to the CLI reporter. This keeps UI and
+/// CLI behavior aligned until a dedicated TUI integration is implemented.
+#[derive(Default)]
+pub struct TuiProgressReporter(CliProgressReporter);
+
+impl PullProgressReporter for TuiProgressReporter {
+    fn on_event(&mut self, event: &PullEvent) -> io::Result<()> {
+        self.0.on_event(event)
+    }
+}

codex-rs/ollama/src/url.rs

@@ -0,0 +1,39 @@
+/// Identify whether a base_url points at an OpenAI-compatible root (".../v1").
+pub(crate) fn is_openai_compatible_base_url(base_url: &str) -> bool {
+    base_url.trim_end_matches('/').ends_with("/v1")
+}
+
+/// Convert a provider base_url into the native Ollama host root.
+/// For example, "http://localhost:11434/v1" -> "http://localhost:11434".
+pub fn base_url_to_host_root(base_url: &str) -> String {
+    let trimmed = base_url.trim_end_matches('/');
+    if trimmed.ends_with("/v1") {
+        trimmed
+            .trim_end_matches("/v1")
+            .trim_end_matches('/')
+            .to_string()
+    } else {
+        trimmed.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_base_url_to_host_root() {
+        assert_eq!(
+            base_url_to_host_root("http://localhost:11434/v1"),
+            "http://localhost:11434"
+        );
+        assert_eq!(
+            base_url_to_host_root("http://localhost:11434"),
+            "http://localhost:11434"
+        );
+        assert_eq!(
+            base_url_to_host_root("http://localhost:11434/"),
+            "http://localhost:11434"
+        );
+    }
+}

codex-rs/scripts/create_github_release.sh

@@ -19,7 +19,33 @@ if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --o
 fi
 
 # Fail if in a detached HEAD state.
-CURRENT_BRANCH=$(git symbolic-ref --short -q HEAD)
+CURRENT_BRANCH=$(git symbolic-ref --short -q HEAD 2>/dev/null || true)
+if [ -z "${CURRENT_BRANCH:-}" ]; then
+  echo "ERROR: Could not determine the current branch (detached HEAD?)." >&2
+  echo "       Please run this script from a checked-out branch." >&2
+  exit 1
+fi
+
+# Ensure we are on the 'main' branch before proceeding.
+if [ "${CURRENT_BRANCH}" != "main" ]; then
+  echo "ERROR: Releases must be created from the 'main' branch (current: '${CURRENT_BRANCH}')." >&2
+  echo "       Please switch to 'main' and try again." >&2
+  exit 1
+fi
+
+# Ensure the current local commit on 'main' is present on 'origin/main'.
+# This guarantees we only create releases from commits that are already on
+# the canonical repository (https://github.com/openai/codex).
+if ! git fetch --quiet origin main; then
+  echo "ERROR: Failed to fetch 'origin/main'. Ensure the 'origin' remote is configured and reachable." >&2
+  exit 1
+fi
+
+if ! git merge-base --is-ancestor HEAD origin/main; then
+  echo "ERROR: Your local 'main' HEAD commit is not present on 'origin/main'." >&2
+  echo "       Please push your commits first (git push origin main) or check out a commit on 'origin/main'." >&2
+  exit 1
+fi
 
 # Create a new branch for the release and make a commit with the new version.
 if [ $# -ge 1 ]; then

codex-rs/tui/Cargo.toml

@@ -29,12 +29,15 @@ codex-common = { path = "../common", features = [
     "cli",
     "elapsed",
     "sandbox_summary",
+    "updates",
 ] }
 codex-core = { path = "../core" }
 codex-file-search = { path = "../file-search" }
 codex-login = { path = "../login" }
+codex-ollama = { path = "../ollama" }
 color-eyre = "0.6.3"
 crossterm = { version = "0.28.1", features = ["bracketed-paste"] }
+diffy = "0.4.2"
 image = { version = "^0.25.6", default-features = false, features = ["jpeg"] }
 lazy_static = "1"
 mcp-types = { path = "../mcp-types" }
@@ -46,7 +49,6 @@ ratatui = { version = "0.29.0", features = [
 ] }
 ratatui-image = "8.0.0"
 regex-lite = "0.1"
-reqwest = { version = "0.12", features = ["json"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1", features = ["preserve_order"] }
 shlex = "1.3.0"
@@ -71,10 +73,9 @@ unicode-width = "0.1"
 uuid = "1"
 
 
-
 [dev-dependencies]
+chrono = { version = "0.4", features = ["serde"] }
 insta = "1.43.1"
 pretty_assertions = "1"
 rand = "0.8"
-chrono = { version = "0.4", features = ["serde"] }
 vt100 = "0.16.2"

codex-rs/tui/prompt_for_init_command.md

@@ -0,0 +1,40 @@
+Generate a file named AGENTS.md that serves as a contributor guide for this repository.
+Your goal is to produce a clear, concise, and well-structured document with descriptive headings and actionable explanations for each section.
+Follow the outline below, but adapt as needed — add sections if relevant, and omit those that do not apply to this project.
+
+Document Requirements
+
+- Title the document "Repository Guidelines".
+- Use Markdown headings (#, ##, etc.) for structure.
+- Keep the document concise. 200-400 words is optimal.
+- Keep explanations short, direct, and specific to this repository.
+- Provide examples where helpful (commands, directory paths, naming patterns).
+- Maintain a professional, instructional tone.
+
+Recommended Sections
+
+Project Structure & Module Organization
+
+- Outline the project structure, including where the source code, tests, and assets are located.
+
+Build, Test, and Development Commands
+
+- List key commands for building, testing, and running locally (e.g., npm test, make build).
+- Briefly explain what each command does.
+
+Coding Style & Naming Conventions
+
+- Specify indentation rules, language-specific style preferences, and naming patterns.
+- Include any formatting or linting tools used.
+
+Testing Guidelines
+
+- Identify testing frameworks and coverage requirements.
+- State test naming conventions and how to run tests.
+
+Commit & Pull Request Guidelines
+
+- Summarize commit message conventions found in the project’s Git history.
+- Outline pull request requirements (descriptions, linked issues, screenshots, etc.).
+
+(Optional) Add other sections if relevant, such as Security & Configuration Tips, Architecture Overview, or Agent-Specific Instructions.

codex-rs/tui/src/app.rs

@@ -3,8 +3,10 @@ use crate::app_event_sender::AppEventSender;
 use crate::chatwidget::ChatWidget;
 use crate::file_search::FileSearchManager;
 use crate::get_git_diff::get_git_diff;
-use crate::git_warning_screen::GitWarningOutcome;
-use crate::git_warning_screen::GitWarningScreen;
+use crate::onboarding::onboarding_screen::KeyboardHandler;
+use crate::onboarding::onboarding_screen::OnboardingScreen;
+use crate::onboarding::onboarding_screen::OnboardingScreenArgs;
+use crate::should_show_login_screen;
 use crate::slash_command::SlashCommand;
 use crate::tui;
 use codex_core::config::Config;
@@ -35,14 +37,15 @@ const REDRAW_DEBOUNCE: Duration = Duration::from_millis(10);
 /// Top-level application state: which full-screen view is currently active.
 #[allow(clippy::large_enum_variant)]
 enum AppState<'a> {
+    Onboarding {
+        screen: OnboardingScreen,
+    },
     /// The main chat UI is visible.
     Chat {
         /// Boxed to avoid a large enum variant and reduce the overall size of
         /// `AppState`.
         widget: Box<ChatWidget<'a>>,
     },
-    /// The start-up warning that recommends running codex inside a Git repo.
-    GitWarning { screen: GitWarningScreen },
 }
 
 pub(crate) struct App<'a> {
@@ -60,18 +63,14 @@ pub(crate) struct App<'a> {
 
     pending_history_lines: Vec<Line<'static>>,
 
-    /// Stored parameters needed to instantiate the ChatWidget later, e.g.,
-    /// after dismissing the Git-repo warning.
-    chat_args: Option<ChatWidgetArgs>,
-
     enhanced_keys_supported: bool,
 }
 
 /// Aggregate parameters needed to create a `ChatWidget`, as creation may be
 /// deferred until after the Git warning screen is dismissed.
-#[derive(Clone)]
-struct ChatWidgetArgs {
-    config: Config,
+#[derive(Clone, Debug)]
+pub(crate) struct ChatWidgetArgs {
+    pub(crate) config: Config,
     initial_prompt: Option<String>,
     initial_images: Vec<PathBuf>,
     enhanced_keys_supported: bool,
@@ -81,8 +80,8 @@ impl App<'_> {
     pub(crate) fn new(
         config: Config,
         initial_prompt: Option<String>,
-        show_git_warning: bool,
         initial_images: Vec<std::path::PathBuf>,
+        show_trust_screen: bool,
     ) -> Self {
         let (app_event_tx, app_event_rx) = channel();
         let app_event_tx = AppEventSender::new(app_event_tx);
@@ -133,18 +132,24 @@ impl App<'_> {
             });
         }
 
-        let (app_state, chat_args) = if show_git_warning {
-            (
-                AppState::GitWarning {
-                    screen: GitWarningScreen::new(),
-                },
-                Some(ChatWidgetArgs {
-                    config: config.clone(),
-                    initial_prompt,
-                    initial_images,
-                    enhanced_keys_supported,
+        let show_login_screen = should_show_login_screen(&config);
+        let app_state = if show_login_screen || show_trust_screen {
+            let chat_widget_args = ChatWidgetArgs {
+                config: config.clone(),
+                initial_prompt,
+                initial_images,
+                enhanced_keys_supported,
+            };
+            AppState::Onboarding {
+                screen: OnboardingScreen::new(OnboardingScreenArgs {
+                    event_tx: app_event_tx.clone(),
+                    codex_home: config.codex_home.clone(),
+                    cwd: config.cwd.clone(),
+                    show_login_screen,
+                    show_trust_screen,
+                    chat_widget_args,
                 }),
-            )
+            }
         } else {
             let chat_widget = ChatWidget::new(
                 config.clone(),
@@ -153,12 +158,9 @@ impl App<'_> {
                 initial_images,
                 enhanced_keys_supported,
             );
-            (
-                AppState::Chat {
-                    widget: Box::new(chat_widget),
-                },
-                None,
-            )
+            AppState::Chat {
+                widget: Box::new(chat_widget),
+            }
         };
 
         let file_search = FileSearchManager::new(config.cwd.clone(), app_event_tx.clone());
@@ -170,7 +172,6 @@ impl App<'_> {
             config,
             file_search,
             pending_redraw,
-            chat_args,
             enhanced_keys_supported,
         }
     }
@@ -227,14 +228,22 @@ impl App<'_> {
                             modifiers: crossterm::event::KeyModifiers::CONTROL,
                             kind: KeyEventKind::Press,
                             ..
+                        } => match &mut self.app_state {
+                            AppState::Chat { widget } => {
+                                widget.on_ctrl_c();
+                            }
+                            AppState::Onboarding { .. } => {
+                                self.app_event_tx.send(AppEvent::ExitRequest);
+                            }
+                        },
+                        KeyEvent {
+                            code: KeyCode::Char('z'),
+                            modifiers: crossterm::event::KeyModifiers::CONTROL,
+                            kind: KeyEventKind::Press,
+                            ..
                         } => {
-                            match &mut self.app_state {
-                                AppState::Chat { widget } => {
-                                    widget.on_ctrl_c();
-                                }
-                                AppState::GitWarning { .. } => {
-                                    // No-op.
-                                }
+                            if let AppState::Chat { widget } = &mut self.app_state {
+                                widget.on_ctrl_z();
                             }
                         }
                         KeyEvent {
@@ -254,7 +263,7 @@ impl App<'_> {
                                         self.dispatch_key_event(key_event);
                                     }
                                 }
-                                AppState::GitWarning { .. } => {
+                                AppState::Onboarding { .. } => {
                                     self.app_event_tx.send(AppEvent::ExitRequest);
                                 }
                             }
@@ -281,14 +290,15 @@ impl App<'_> {
                 }
                 AppEvent::CodexOp(op) => match &mut self.app_state {
                     AppState::Chat { widget } => widget.submit_op(op),
-                    AppState::GitWarning { .. } => {}
+                    AppState::Onboarding { .. } => {}
                 },
                 AppEvent::LatestLog(line) => match &mut self.app_state {
                     AppState::Chat { widget } => widget.update_latest_log(line),
-                    AppState::GitWarning { .. } => {}
+                    AppState::Onboarding { .. } => {}
                 },
                 AppEvent::DispatchCommand(command) => match command {
                     SlashCommand::New => {
+                        // User accepted – switch to chat view.
                         let new_widget = Box::new(ChatWidget::new(
                             self.config.clone(),
                             self.app_event_tx.clone(),
@@ -299,6 +309,13 @@ impl App<'_> {
                         self.app_state = AppState::Chat { widget: new_widget };
                         self.app_event_tx.send(AppEvent::RequestRedraw);
                     }
+                    SlashCommand::Init => {
+                        // Guard: do not run if a task is active.
+                        if let AppState::Chat { widget } = &mut self.app_state {
+                            const INIT_PROMPT: &str = include_str!("../prompt_for_init_command.md");
+                            widget.submit_text_message(INIT_PROMPT.to_string());
+                        }
+                    }
                     SlashCommand::Compact => {
                         if let AppState::Chat { widget } = &mut self.app_state {
                             widget.clear_token_usage();
@@ -308,6 +325,12 @@ impl App<'_> {
                     SlashCommand::Quit => {
                         break;
                     }
+                    SlashCommand::Logout => {
+                        if let Err(e) = codex_login::logout(&self.config.codex_home) {
+                            tracing::error!("failed to logout: {e}");
+                        }
+                        break;
+                    }
                     SlashCommand::Diff => {
                         let (is_git_repo, diff_text) = match get_git_diff() {
                             Ok(v) => v,
@@ -329,6 +352,16 @@ impl App<'_> {
                             widget.add_diff_output(text);
                         }
                     }
+                    SlashCommand::Status => {
+                        if let AppState::Chat { widget } = &mut self.app_state {
+                            widget.add_status_output();
+                        }
+                    }
+                    SlashCommand::Prompts => {
+                        if let AppState::Chat { widget } = &mut self.app_state {
+                            widget.add_prompts_output();
+                        }
+                    }
                     #[cfg(debug_assertions)]
                     SlashCommand::TestApproval => {
                         use std::collections::HashMap;
@@ -369,8 +402,31 @@ impl App<'_> {
                         }));
                     }
                 },
+                AppEvent::OnboardingAuthComplete(result) => {
+                    if let AppState::Onboarding { screen } = &mut self.app_state {
+                        screen.on_auth_complete(result);
+                    }
+                }
+                AppEvent::OnboardingComplete(ChatWidgetArgs {
+                    config,
+                    enhanced_keys_supported,
+                    initial_images,
+                    initial_prompt,
+                }) => {
+                    self.app_state = AppState::Chat {
+                        widget: Box::new(ChatWidget::new(
+                            config,
+                            app_event_tx.clone(),
+                            initial_prompt,
+                            initial_images,
+                            enhanced_keys_supported,
+                        )),
+                    }
+                }
                 AppEvent::StartFileSearch(query) => {
-                    self.file_search.on_user_query(query);
+                    if !query.is_empty() {
+                        self.file_search.on_user_query(query);
+                    }
                 }
                 AppEvent::FileSearchResult { query, matches } => {
                     if let AppState::Chat { widget } = &mut self.app_state {
@@ -387,7 +443,7 @@ impl App<'_> {
     pub(crate) fn token_usage(&self) -> codex_core::protocol::TokenUsage {
         match &self.app_state {
             AppState::Chat { widget } => widget.token_usage().clone(),
-            AppState::GitWarning { .. } => codex_core::protocol::TokenUsage::default(),
+            AppState::Onboarding { .. } => codex_core::protocol::TokenUsage::default(),
         }
     }
 
@@ -415,7 +471,7 @@ impl App<'_> {
         let size = terminal.size()?;
         let desired_height = match &self.app_state {
             AppState::Chat { widget } => widget.desired_height(size.width),
-            AppState::GitWarning { .. } => 10,
+            AppState::Onboarding { .. } => size.height,
         };
 
         let mut area = terminal.viewport_area;
@@ -445,7 +501,7 @@ impl App<'_> {
                 }
                 frame.render_widget_ref(&**widget, frame.area())
             }
-            AppState::GitWarning { screen } => frame.render_widget_ref(&*screen, frame.area()),
+            AppState::Onboarding { screen } => frame.render_widget_ref(&*screen, frame.area()),
         })?;
         Ok(())
     }
@@ -457,30 +513,11 @@ impl App<'_> {
             AppState::Chat { widget } => {
                 widget.handle_key_event(key_event);
             }
-            AppState::GitWarning { screen } => match screen.handle_key_event(key_event) {
-                GitWarningOutcome::Continue => {
-                    // User accepted – switch to chat view.
-                    let args = match self.chat_args.take() {
-                        Some(args) => args,
-                        None => panic!("ChatWidgetArgs already consumed"),
-                    };
-
-                    let widget = Box::new(ChatWidget::new(
-                        args.config,
-                        self.app_event_tx.clone(),
-                        args.initial_prompt,
-                        args.initial_images,
-                        args.enhanced_keys_supported,
-                    ));
-                    self.app_state = AppState::Chat { widget };
-                    self.app_event_tx.send(AppEvent::RequestRedraw);
-                }
-                GitWarningOutcome::Quit => {
+            AppState::Onboarding { screen } => match key_event.code {
+                KeyCode::Char('q') => {
                     self.app_event_tx.send(AppEvent::ExitRequest);
                 }
-                GitWarningOutcome::None => {
-                    // do nothing
-                }
+                _ => screen.handle_key_event(key_event),
             },
         }
     }
@@ -488,14 +525,14 @@ impl App<'_> {
     fn dispatch_paste_event(&mut self, pasted: String) {
         match &mut self.app_state {
             AppState::Chat { widget } => widget.handle_paste(pasted),
-            AppState::GitWarning { .. } => {}
+            AppState::Onboarding { .. } => {}
         }
     }
 
     fn dispatch_codex_event(&mut self, event: Event) {
         match &mut self.app_state {
             AppState::Chat { widget } => widget.handle_codex_event(event),
-            AppState::GitWarning { .. } => {}
+            AppState::Onboarding { .. } => {}
         }
     }
 }

codex-rs/tui/src/app_event.rs

@@ -3,6 +3,7 @@ use codex_file_search::FileMatch;
 use crossterm::event::KeyEvent;
 use ratatui::text::Line;
 
+use crate::app::ChatWidgetArgs;
 use crate::slash_command::SlashCommand;
 
 #[allow(clippy::large_enum_variant)]
@@ -48,4 +49,8 @@ pub(crate) enum AppEvent {
     },
 
     InsertHistory(Vec<Line<'static>>),
+
+    /// Onboarding: result of login_with_chatgpt.
+    OnboardingAuthComplete(Result<(), String>),
+    OnboardingComplete(ChatWidgetArgs),
 }

codex-rs/tui/src/app_event_sender.rs

@@ -4,7 +4,7 @@ use crate::app_event::AppEvent;
 
 #[derive(Clone, Debug)]
 pub(crate) struct AppEventSender {
-    app_event_tx: Sender<AppEvent>,
+    pub app_event_tx: Sender<AppEvent>,
 }
 
 impl AppEventSender {

codex-rs/tui/src/bottom_pane/chat_composer.rs

@@ -8,6 +8,7 @@ use ratatui::layout::Layout;
 use ratatui::layout::Margin;
 use ratatui::layout::Rect;
 use ratatui::style::Color;
+use ratatui::style::Modifier;
 use ratatui::style::Style;
 use ratatui::style::Styled;
 use ratatui::style::Stylize;
@@ -30,7 +31,7 @@ use crate::bottom_pane::textarea::TextAreaState;
 use codex_file_search::FileMatch;
 use std::cell::RefCell;
 
-const BASE_PLACEHOLDER_TEXT: &str = "...";
+const BASE_PLACEHOLDER_TEXT: &str = "Ask Codex to do anything";
 /// If the pasted content exceeds this number of characters, replace it with a
 /// placeholder in the UI.
 const LARGE_PASTE_CHAR_THRESHOLD: usize = 1000;
@@ -42,7 +43,8 @@ pub enum InputResult {
 }
 
 struct TokenUsageInfo {
-    token_usage: TokenUsage,
+    total_token_usage: TokenUsage,
+    last_token_usage: TokenUsage,
     model_context_window: Option<u64>,
 }
 
@@ -126,11 +128,13 @@ impl ChatComposer {
     /// context when the composer is empty.
     pub(crate) fn set_token_usage(
         &mut self,
-        token_usage: TokenUsage,
+        total_token_usage: TokenUsage,
+        last_token_usage: TokenUsage,
         model_context_window: Option<u64>,
     ) {
         self.token_usage_info = Some(TokenUsageInfo {
-            token_usage,
+            total_token_usage,
+            last_token_usage,
             model_context_window,
         });
     }
@@ -331,8 +335,9 @@ impl ChatComposer {
     /// - The cursor may be anywhere *inside* the token (including on the
     ///   leading `@`). It does **not** need to be at the end of the line.
     /// - A token is delimited by ASCII whitespace (space, tab, newline).
-    /// - If the token under the cursor starts with `@` and contains at least
-    ///   one additional character, that token (without `@`) is returned.
+    /// - If the token under the cursor starts with `@`, that token is
+    ///   returned without the leading `@`. This includes the case where the
+    ///   token is just "@" (empty query), which is used to trigger a UI hint
     fn current_at_token(textarea: &TextArea) -> Option<String> {
         let cursor_offset = textarea.cursor();
         let text = textarea.text();
@@ -403,14 +408,20 @@ impl ChatComposer {
         };
 
         let left_at = token_left
-            .filter(|t| t.starts_with('@') && t.len() > 1)
+            .filter(|t| t.starts_with('@'))
             .map(|t| t[1..].to_string());
         let right_at = token_right
-            .filter(|t| t.starts_with('@') && t.len() > 1)
+            .filter(|t| t.starts_with('@'))
             .map(|t| t[1..].to_string());
 
         if at_whitespace {
-            return right_at.or(left_at);
+            if right_at.is_some() {
+                return right_at;
+            }
+            if token_left.is_some_and(|t| t == "@") {
+                return None;
+            }
+            return left_at;
         }
         if after_cursor.starts_with('@') {
             return right_at.or(left_at);
@@ -453,6 +464,8 @@ impl ChatComposer {
         new_text.push_str(&text[end_idx..]);
 
         self.textarea.set_text(&new_text);
+        let new_cursor = start_idx.saturating_add(path.len()).saturating_add(1);
+        self.textarea.set_cursor(new_cursor);
     }
 
     /// Handle key event when no popup is visible.
@@ -605,16 +618,26 @@ impl ChatComposer {
             return;
         }
 
-        self.app_event_tx
-            .send(AppEvent::StartFileSearch(query.clone()));
+        if !query.is_empty() {
+            self.app_event_tx
+                .send(AppEvent::StartFileSearch(query.clone()));
+        }
 
         match &mut self.active_popup {
             ActivePopup::File(popup) => {
-                popup.set_query(&query);
+                if query.is_empty() {
+                    popup.set_empty_prompt();
+                } else {
+                    popup.set_query(&query);
+                }
             }
             _ => {
                 let mut popup = FileSearchPopup::new();
-                popup.set_query(&query);
+                if query.is_empty() {
+                    popup.set_empty_prompt();
+                } else {
+                    popup.set_query(&query);
+                }
                 self.active_popup = ActivePopup::File(popup);
             }
         }
@@ -647,7 +670,7 @@ impl WidgetRef for &ChatComposer {
             ActivePopup::None => {
                 let bottom_line_rect = popup_rect;
                 let key_hint_style = Style::default().fg(Color::Cyan);
-                let hint = if self.ctrl_c_quit_hint {
+                let mut hint = if self.ctrl_c_quit_hint {
                     vec![
                         Span::from(" "),
                         "Ctrl+C again".set_style(key_hint_style),
@@ -669,6 +692,33 @@ impl WidgetRef for &ChatComposer {
                         Span::from(" quit"),
                     ]
                 };
+
+                // Append token/context usage info to the footer hints when available.
+                if let Some(token_usage_info) = &self.token_usage_info {
+                    let token_usage = &token_usage_info.total_token_usage;
+                    hint.push(Span::from("   "));
+                    hint.push(
+                        Span::from(format!("{} tokens used", token_usage.total_tokens))
+                            .style(Style::default().add_modifier(Modifier::DIM)),
+                    );
+                    let last_token_usage = &token_usage_info.last_token_usage;
+                    if let Some(context_window) = token_usage_info.model_context_window {
+                        let percent_remaining: u8 = if context_window > 0 {
+                            let percent = 100.0
+                                - (last_token_usage.total_tokens as f32 / context_window as f32
+                                    * 100.0);
+                            percent.clamp(0.0, 100.0) as u8
+                        } else {
+                            100
+                        };
+                        hint.push(Span::from("   "));
+                        hint.push(
+                            Span::from(format!("{percent_remaining}% context left"))
+                                .style(Style::default().add_modifier(Modifier::DIM)),
+                        );
+                    }
+                }
+
                 Line::from(hint)
                     .style(Style::default().dim())
                     .render_ref(bottom_line_rect, buf);
@@ -690,37 +740,11 @@ impl WidgetRef for &ChatComposer {
         let mut textarea_rect = textarea_rect;
         textarea_rect.width = textarea_rect.width.saturating_sub(1);
         textarea_rect.x += 1;
+
         let mut state = self.textarea_state.borrow_mut();
         StatefulWidgetRef::render_ref(&(&self.textarea), textarea_rect, buf, &mut state);
         if self.textarea.text().is_empty() {
-            let placeholder = if let Some(token_usage_info) = &self.token_usage_info {
-                let token_usage = &token_usage_info.token_usage;
-                let model_context_window = token_usage_info.model_context_window;
-                match (token_usage.total_tokens, model_context_window) {
-                    (total_tokens, Some(context_window)) => {
-                        let percent_remaining: u8 = if context_window > 0 {
-                            // Calculate the percentage of context left.
-                            let percent =
-                                100.0 - (total_tokens as f32 / context_window as f32 * 100.0);
-                            percent.clamp(0.0, 100.0) as u8
-                        } else {
-                            // If we don't have a context window, we cannot compute the
-                            // percentage.
-                            100
-                        };
-                        // When https://github.com/openai/codex/issues/1257 is resolved,
-                        // check if `percent_remaining < 25`, and if so, recommend
-                        // /compact.
-                        format!("{BASE_PLACEHOLDER_TEXT} — {percent_remaining}% context left")
-                    }
-                    (total_tokens, None) => {
-                        format!("{BASE_PLACEHOLDER_TEXT} — {total_tokens} tokens used")
-                    }
-                }
-            } else {
-                BASE_PLACEHOLDER_TEXT.to_string()
-            };
-            Line::from(placeholder)
+            Line::from(BASE_PLACEHOLDER_TEXT)
                 .style(Style::default().dim())
                 .render_ref(textarea_rect.inner(Margin::new(1, 0)), buf);
         }
@@ -729,6 +753,7 @@ impl WidgetRef for &ChatComposer {
 
 #[cfg(test)]
 mod tests {
+    use crate::app_event::AppEvent;
     use crate::bottom_pane::AppEventSender;
     use crate::bottom_pane::ChatComposer;
     use crate::bottom_pane::InputResult;
@@ -770,7 +795,12 @@ mod tests {
             ("@👍", 2, Some("👍".to_string()), "Emoji token"),
             // Invalid cases (should return None)
             ("hello", 2, None, "No @ symbol"),
-            ("@", 1, None, "Only @ symbol"),
+            (
+                "@",
+                1,
+                Some("".to_string()),
+                "Only @ symbol triggers empty query",
+            ),
             ("@ hello", 2, None, "@ followed by space"),
             ("test @ world", 6, None, "@ with spaces around"),
         ];
@@ -804,7 +834,7 @@ mod tests {
                 "Second token",
             ),
             // Edge cases
-            ("@", 0, None, "Only @ symbol"),
+            ("@", 0, Some("".to_string()), "Only @ symbol"),
             ("@a", 2, Some("a".to_string()), "Single character after @"),
             ("", 0, None, "Empty input"),
         ];
@@ -1004,6 +1034,49 @@ mod tests {
         }
     }
 
+    #[test]
+    fn slash_init_dispatches_command_and_does_not_submit_literal_text() {
+        use crossterm::event::KeyCode;
+        use crossterm::event::KeyEvent;
+        use crossterm::event::KeyModifiers;
+        use std::sync::mpsc::TryRecvError;
+
+        let (tx, rx) = std::sync::mpsc::channel();
+        let sender = AppEventSender::new(tx);
+        let mut composer = ChatComposer::new(true, sender, false);
+
+        // Type the slash command.
+        for ch in [
+            '/', 'i', 'n', 'i', 't', // "/init"
+        ] {
+            let _ = composer.handle_key_event(KeyEvent::new(KeyCode::Char(ch), KeyModifiers::NONE));
+        }
+
+        // Press Enter to dispatch the selected command.
+        let (result, _needs_redraw) =
+            composer.handle_key_event(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE));
+
+        // When a slash command is dispatched, the composer should not submit
+        // literal text and should clear its textarea.
+        match result {
+            InputResult::None => {}
+            InputResult::Submitted(text) => {
+                panic!("expected command dispatch, but composer submitted literal text: {text}")
+            }
+        }
+        assert!(composer.textarea.is_empty(), "composer should be cleared");
+
+        // Verify a DispatchCommand event for the "init" command was sent.
+        match rx.try_recv() {
+            Ok(AppEvent::DispatchCommand(cmd)) => {
+                assert_eq!(cmd.command(), "init");
+            }
+            Ok(_other) => panic!("unexpected app event"),
+            Err(TryRecvError::Empty) => panic!("expected a DispatchCommand event for '/init'"),
+            Err(TryRecvError::Disconnected) => panic!("app event channel disconnected"),
+        }
+    }
+
     #[test]
     fn test_multiple_pastes_submission() {
         use crossterm::event::KeyCode;