Merge branch 'main' into etraut/concurrent_refresh

2026-11-05 20:10:33 +00:00 · 2026-01-05 15:56:54 -07:00
parent 896e9ed212 5f8776d34d
commit ef60a312c5
151 changed files with 6862 additions and 3817 deletions
@@ -12,6 +12,8 @@ permissions:

 jobs:
  close-stale-contributor-prs:
+    # Prevent scheduled runs on forks
+    if: github.repository == 'openai/codex'
    runs-on: ubuntu-latest
    steps:
      - name: Close inactive PRs from contributors
@@ -9,7 +9,8 @@ on:
 jobs:
  gather-duplicates:
    name: Identify potential duplicates
-    if: ${{ github.event.action == 'opened' || (github.event.action == 'labeled' && github.event.label.name == 'codex-deduplicate') }}
+    # Prevent runs on forks (requires OpenAI API key, wastes Actions minutes)
+    if: github.repository == 'openai/codex' && (github.event.action == 'opened' || (github.event.action == 'labeled' && github.event.label.name == 'codex-deduplicate'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
@@ -9,7 +9,8 @@ on:
 jobs:
  gather-labels:
    name: Generate label suggestions
-    if: ${{ github.event.action == 'opened' || (github.event.action == 'labeled' && github.event.label.name == 'codex-label') }}
+    # Prevent runs on forks (requires OpenAI API key, wastes Actions minutes)
+    if: github.repository == 'openai/codex' && (github.event.action == 'opened' || (github.event.action == 'labeled' && github.event.label.name == 'codex-label'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
@@ -14,6 +14,8 @@ permissions:

 jobs:
  prepare:
+    # Prevent scheduled runs on forks (no secrets, wastes Actions minutes)
+    if: github.repository == 'openai/codex'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
@@ -1,13 +1,11 @@
 <p align="center"><code>npm i -g @openai/codex</code><br />or <code>brew install --cask codex</code></p>
-
 <p align="center"><strong>Codex CLI</strong> is a coding agent from OpenAI that runs locally on your computer.
-</br>
-</br>If you want Codex in your code editor (VS Code, Cursor, Windsurf), <a href="https://developers.openai.com/codex/ide">install in your IDE</a>
-</br>If you are looking for the <em>cloud-based agent</em> from OpenAI, <strong>Codex Web</strong>, go to <a href="https://chatgpt.com/codex">chatgpt.com/codex</a></p>
-
 <p align="center">
  <img src="./.github/codex-cli-splash.png" alt="Codex CLI splash" width="80%" />
-  </p>
+</p>
+</br>
+If you want Codex in your code editor (VS Code, Cursor, Windsurf), <a href="https://developers.openai.com/codex/ide">install in your IDE.</a>
+</br>If you are looking for the <em>cloud-based agent</em> from OpenAI, <strong>Codex Web</strong>, go to <a href="https://chatgpt.com/codex">chatgpt.com/codex</a>.</p>

 ---

@@ -15,25 +13,19 @@

 ### Installing and running Codex CLI

-Install globally with your preferred package manager. If you use npm:
+Install globally with your preferred package manager:

 ```shell
+# Install using npm
 npm install -g @openai/codex
 ```

-Alternatively, if you use Homebrew:
-
 ```shell
+# Install using Homebrew
 brew install --cask codex
 ```

-Then simply run `codex` to get started:
-
-```shell
-codex
-```
-
-If you're running into upgrade issues with Homebrew, see the [FAQ entry on brew upgrade codex](./docs/faq.md#brew-upgrade-codex-isnt-upgrading-me).
+Then simply run `codex` to get started.

 <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>
@@ -53,60 +45,15 @@ Each archive contains a single entry with the platform baked into the name (e.g.

 ### Using Codex with your ChatGPT plan

-<p align="center">
-  <img src="./.github/codex-cli-login.png" alt="Codex CLI login" width="80%" />
-  </p>
-
 Run `codex` and select **Sign in with ChatGPT**. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. [Learn more about what's included in your ChatGPT plan](https://help.openai.com/en/articles/11369540-codex-in-chatgpt).

-You can also use Codex with an API key, but this requires [additional setup](./docs/authentication.md#usage-based-billing-alternative-use-an-openai-api-key). If you previously used an API key for usage-based billing, see the [migration steps](./docs/authentication.md#migrating-from-usage-based-billing-api-key). If you're having trouble with login, please comment on [this issue](https://github.com/openai/codex/issues/1243).
+You can also use Codex with an API key, but this requires [additional setup](https://developers.openai.com/codex/auth#sign-in-with-an-api-key).

-### Model Context Protocol (MCP)
+## Docs

-Codex can access MCP servers. To configure them, refer to the [config docs](./docs/config.md#mcp_servers).
-
-### Configuration
-
-Codex CLI supports a rich set of configuration options, with preferences stored in `~/.codex/config.toml`. For full configuration options, see [Configuration](./docs/config.md).
-
-### Execpolicy
-
-See the [Execpolicy quickstart](./docs/execpolicy.md) to set up rules that govern what commands Codex can execute.
-
-### Docs & FAQ
-
- [**Getting started**](./docs/getting-started.md)
-  - [CLI usage](./docs/getting-started.md#cli-usage)
-  - [Slash Commands](./docs/slash_commands.md)
-  - [Running with a prompt as input](./docs/getting-started.md#running-with-a-prompt-as-input)
-  - [Example prompts](./docs/getting-started.md#example-prompts)
-  - [Custom prompts](./docs/prompts.md)
-  - [Memory with AGENTS.md](./docs/getting-started.md#memory-with-agentsmd)
- [**Configuration**](./docs/config.md)
-  - [Example config](./docs/example-config.md)
- [**Sandbox & approvals**](./docs/sandbox.md)
- [**Execpolicy quickstart**](./docs/execpolicy.md)
- [**Authentication**](./docs/authentication.md)
-  - [Auth methods](./docs/authentication.md#forcing-a-specific-auth-method-advanced)
-  - [Login on a "Headless" machine](./docs/authentication.md#connecting-on-a-headless-machine)
- **Automating Codex**
-  - [GitHub Action](https://github.com/openai/codex-action)
-  - [TypeScript SDK](./sdk/typescript/README.md)
-  - [Non-interactive mode (`codex exec`)](./docs/exec.md)
- [**Advanced**](./docs/advanced.md)
-  - [Tracing / verbose logging](./docs/advanced.md#tracing--verbose-logging)
-  - [Model Context Protocol (MCP)](./docs/advanced.md#model-context-protocol-mcp)
- [**Zero data retention (ZDR)**](./docs/zdr.md)
+- [**Codex Documentation**](https://developers.openai.com/codex)
 - [**Contributing**](./docs/contributing.md)
- [**Install & build**](./docs/install.md)
-  - [System Requirements](./docs/install.md#system-requirements)
-  - [DotSlash](./docs/install.md#dotslash)
-  - [Build from source](./docs/install.md#build-from-source)
- [**FAQ**](./docs/faq.md)
+- [**Installing & building**](./docs/install.md)
 - [**Open source fund**](./docs/open-source-fund.md)

---
-
-## License
-
 This repository is licensed under the [Apache-2.0 License](LICENSE).
@@ -42,7 +42,7 @@ dependencies = [
 "bitflags 2.10.0",
 "bytes",
 "bytestring",
- "derive_more 2.0.1",
+ "derive_more 2.1.1",
 "encoding_rs",
 "foldhash 0.1.5",
 "futures-core",
@@ -137,7 +137,7 @@ dependencies = [
 "bytes",
 "bytestring",
 "cfg-if",
- "derive_more 2.0.1",
+ "derive_more 2.1.1",
 "encoding_rs",
 "foldhash 0.1.5",
 "futures-core",
@@ -360,7 +360,7 @@ dependencies = [
 "objc2-foundation",
 "parking_lot",
 "percent-encoding",
- "windows-sys 0.60.2",
+ "windows-sys 0.52.0",
 "wl-clipboard-rs",
 "x11rb",
 ]
@@ -912,9 +912,9 @@ dependencies = [

 [[package]]
 name = "clap_complete"
-version = "4.5.57"
+version = "4.5.64"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4d9501bd3f5f09f7bbee01da9a511073ed30a80cd7a509f1214bb74eadea71ad"
+checksum = "4c0da80818b2d95eca9aa614a30783e42f62bf5fdfee24e68cfb960b071ba8d1"
 dependencies = [
 "clap",
 ]
@@ -1433,7 +1433,7 @@ dependencies = [
 "allocative",
 "anyhow",
 "clap",
- "derive_more 2.0.1",
+ "derive_more 2.1.1",
 "env_logger",
 "log",
 "multimap",
@@ -1454,6 +1454,7 @@ dependencies = [
 "codex-protocol",
 "pretty_assertions",
 "sentry",
+ "tracing",
 "tracing-subscriber",
 ]

@@ -1609,7 +1610,6 @@ dependencies = [
 "serde_json",
 "strum_macros 0.27.2",
 "tokio",
- "tonic",
 "tracing",
 "tracing-opentelemetry",
 "tracing-subscriber",
@@ -1732,7 +1732,7 @@ dependencies = [
 "codex-windows-sandbox",
 "color-eyre",
 "crossterm",
- "derive_more 2.0.1",
+ "derive_more 2.1.1",
 "diffy",
 "dirs",
 "dunce",
@@ -1805,7 +1805,7 @@ dependencies = [
 "codex-windows-sandbox",
 "color-eyre",
 "crossterm",
- "derive_more 2.0.1",
+ "derive_more 2.1.1",
 "diffy",
 "dirs",
 "dunce",
@@ -1820,6 +1820,7 @@ dependencies = [
 "pulldown-cmark",
 "rand 0.9.2",
 "ratatui",
+ "ratatui-core",
 "ratatui-macros",
 "regex-lite",
 "reqwest",
@@ -1841,6 +1842,7 @@ dependencies = [
 "tracing-subscriber",
 "tree-sitter-bash",
 "tree-sitter-highlight",
+ "tui-scrollbar",
 "unicode-segmentation",
 "unicode-width 0.2.1",
 "url",
@@ -2005,6 +2007,20 @@ dependencies = [
 "static_assertions",
 ]

+[[package]]
+name = "compact_str"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3fdb1325a1cece981e8a296ab8f0f9b63ae357bd0784a9faaf548cc7b480707a"
+dependencies = [
+ "castaway",
+ "cfg-if",
+ "itoa",
+ "rustversion",
+ "ryu",
+ "static_assertions",
+]
+
 [[package]]
 name = "concurrent-queue"
 version = "2.5.0"
@@ -2026,6 +2042,18 @@ dependencies = [
 "windows-sys 0.59.0",
 ]

+[[package]]
+name = "const-hex"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3bb320cac8a0750d7f25280aa97b09c26edfe161164238ecbbb31092b079e735"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "proptest",
+ "serde_core",
+]
+
 [[package]]
 name = "convert_case"
 version = "0.6.0"
@@ -2037,9 +2065,9 @@ dependencies = [

 [[package]]
 name = "convert_case"
-version = "0.7.1"
+version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bb402b8d4c85569410425650ce3eddc7d698ed96d39a73f941b08fb63082f1e7"
+checksum = "633458d4ef8c78b72454de2d54fd6ab2e60f9e02be22f3c6104cdc8a4e0fceb9"
 dependencies = [
 "unicode-segmentation",
 ]
@@ -2426,11 +2454,11 @@ dependencies = [

 [[package]]
 name = "derive_more"
-version = "2.0.1"
+version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "093242cf7570c207c83073cf82f79706fe7b8317e98620a47d5be7c3d8497678"
+checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
 dependencies = [
- "derive_more-impl 2.0.1",
+ "derive_more-impl 2.1.1",
 ]

 [[package]]
@@ -2448,13 +2476,14 @@ dependencies = [

 [[package]]
 name = "derive_more-impl"
-version = "2.0.1"
+version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bda628edc44c4bb645fbe0f758797143e4e07926f7ebf4e9bdfbd3d2ce621df3"
+checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
 dependencies = [
- "convert_case 0.7.1",
+ "convert_case 0.10.0",
 "proc-macro2",
 "quote",
+ "rustc_version",
 "syn 2.0.104",
 "unicode-xid",
 ]
@@ -2570,6 +2599,15 @@ version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10"

+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
 [[package]]
 name = "dotenvy"
 version = "0.15.7"
@@ -2743,7 +2781,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "778e2ac28f6c47af28e4907f13ffd1e1ddbd400980a9abd7c8df189bf578a5ad"
 dependencies = [
 "libc",
- "windows-sys 0.60.2",
+ "windows-sys 0.52.0",
 ]

 [[package]]
@@ -2851,7 +2889,7 @@ checksum = "0ce92ff622d6dadf7349484f42c93271a0d49b7cc4d466a936405bacbe10aa78"
 dependencies = [
 "cfg-if",
 "rustix 1.0.8",
- "windows-sys 0.59.0",
+ "windows-sys 0.52.0",
 ]

 [[package]]
@@ -3736,13 +3774,14 @@ dependencies = [

 [[package]]
 name = "insta"
-version = "1.44.3"
+version = "1.46.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5c943d4415edd8153251b6f197de5eb1640e56d84e8d9159bea190421c73698"
+checksum = "1b66886d14d18d420ab5052cbff544fc5d34d0b2cdd35eb5976aaa10a4a472e5"
 dependencies = [
 "console",
 "once_cell",
 "similar",
+ "tempfile",
 ]

 [[package]]
@@ -3791,7 +3830,7 @@ checksum = "e04d7f318608d35d4b61ddd75cbdaee86b023ebe2bd5a66ee0915f0bf93095a9"
 dependencies = [
 "hermit-abi",
 "libc",
- "windows-sys 0.59.0",
+ "windows-sys 0.52.0",
 ]

 [[package]]
@@ -3895,6 +3934,16 @@ dependencies = [
 "wasm-bindgen",
 ]

+[[package]]
+name = "kasuari"
+version = "0.4.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fe90c1150662e858c7d5f945089b7517b0a80d8bf7ba4b1b5ffc984e7230a5b"
+dependencies = [
+ "hashbrown 0.16.0",
+ "thiserror 2.0.17",
+]
+
 [[package]]
 name = "keyring"
 version = "3.6.3"
@@ -4040,6 +4089,12 @@ version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "241eaef5fd12c88705a01fc1066c48c4b36e0dd4377dcdc7ec3942cea7a69956"

+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
 [[package]]
 name = "local-waker"
 version = "0.1.4"
@@ -4661,9 +4716,9 @@ dependencies = [

 [[package]]
 name = "opentelemetry"
-version = "0.30.0"
+version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aaf416e4cb72756655126f7dd7bb0af49c674f4c1b9903e80c009e0c37e552e6"
+checksum = "b84bcd6ae87133e903af7ef497404dda70c60d0ea14895fc8a5e6722754fc2a0"
 dependencies = [
 "futures-core",
 "futures-sink",
@@ -4675,9 +4730,9 @@ dependencies = [

 [[package]]
 name = "opentelemetry-appender-tracing"
-version = "0.30.1"
+version = "0.31.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e68f63eca5fad47e570e00e893094fc17be959c80c79a7d6ec1abdd5ae6ffc16"
+checksum = "ef6a1ac5ca3accf562b8c306fa8483c85f4390f768185ab775f242f7fe8fdcc2"
 dependencies = [
 "opentelemetry",
 "tracing",
@@ -4687,9 +4742,9 @@ dependencies = [

 [[package]]
 name = "opentelemetry-http"
-version = "0.30.0"
+version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "50f6639e842a97dbea8886e3439710ae463120091e2e064518ba8e716e6ac36d"
+checksum = "d7a6d09a73194e6b66df7c8f1b680f156d916a1a942abf2de06823dd02b7855d"
 dependencies = [
 "async-trait",
 "bytes",
@@ -4700,9 +4755,9 @@ dependencies = [

 [[package]]
 name = "opentelemetry-otlp"
-version = "0.30.0"
+version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dbee664a43e07615731afc539ca60c6d9f1a9425e25ca09c57bc36c87c55852b"
+checksum = "7a2366db2dca4d2ad033cad11e6ee42844fd727007af5ad04a1730f4cb8163bf"
 dependencies = [
 "http 1.3.1",
 "opentelemetry",
@@ -4720,30 +4775,32 @@ dependencies = [

 [[package]]
 name = "opentelemetry-proto"
-version = "0.30.0"
+version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e046fd7660710fe5a05e8748e70d9058dc15c94ba914e7c4faa7c728f0e8ddc"
+checksum = "a7175df06de5eaee9909d4805a3d07e28bb752c34cab57fa9cff549da596b30f"
 dependencies = [
 "base64",
- "hex",
+ "const-hex",
 "opentelemetry",
 "opentelemetry_sdk",
 "prost",
 "serde",
+ "serde_json",
 "tonic",
+ "tonic-prost",
 ]

 [[package]]
 name = "opentelemetry-semantic-conventions"
-version = "0.30.0"
+version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83d059a296a47436748557a353c5e6c5705b9470ef6c95cfc52c21a8814ddac2"
+checksum = "e62e29dfe041afb8ed2a6c9737ab57db4907285d999ef8ad3a59092a36bdc846"

 [[package]]
 name = "opentelemetry_sdk"
-version = "0.30.0"
+version = "0.31.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11f644aa9e5e31d11896e024305d7e3c98a88884d9f8919dbf37a9991bc47a4b"
+checksum = "e14ae4f5991976fd48df6d843de219ca6d31b01daaab2dad5af2badeded372bd"
 dependencies = [
 "futures-channel",
 "futures-executor",
@@ -4751,7 +4808,6 @@ dependencies = [
 "opentelemetry",
 "percent-encoding",
 "rand 0.9.2",
- "serde_json",
 "thiserror 2.0.17",
 "tokio",
 "tokio-stream",
@@ -5134,10 +5190,25 @@ dependencies = [
 ]

 [[package]]
-name = "prost"
-version = "0.13.5"
+name = "proptest"
+version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2796faa41db3ec313a31f7624d9286acf277b52de526150b7e69f3debf891ee5"
+checksum = "bee689443a2bd0a16ab0348b52ee43e3b2d1b1f931c8aa5c9f8de4c86fbe8c40"
+dependencies = [
+ "bitflags 2.10.0",
+ "num-traits",
+ "rand 0.9.2",
+ "rand_chacha 0.9.0",
+ "rand_xorshift",
+ "regex-syntax 0.8.5",
+ "unarray",
+]
+
+[[package]]
+name = "prost"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7231bd9b3d3d33c86b58adbac74b5ec0ad9f496b19d22801d773636feaa95f3d"
 dependencies = [
 "bytes",
 "prost-derive",
@@ -5145,9 +5216,9 @@ dependencies = [

 [[package]]
 name = "prost-derive"
-version = "0.13.5"
+version = "0.14.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a56d757972c98b346a9b766e3f02746cde6dd1cd1d1d563472929fdd74bec4d"
+checksum = "9120690fafc389a67ba3803df527d0ec9cbbc9cc45e4cc20b332996dfb672425"
 dependencies = [
 "anyhow",
 "itertools 0.14.0",
@@ -5260,7 +5331,7 @@ dependencies = [
 "once_cell",
 "socket2 0.6.1",
 "tracing",
- "windows-sys 0.60.2",
+ "windows-sys 0.52.0",
 ]

 [[package]]
@@ -5347,6 +5418,15 @@ dependencies = [
 "getrandom 0.3.3",
 ]

+[[package]]
+name = "rand_xorshift"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
+dependencies = [
+ "rand_core 0.9.3",
+]
+
 [[package]]
 name = "ratatui"
 version = "0.29.0"
@@ -5354,7 +5434,7 @@ source = "git+https://github.com/nornagon/ratatui?branch=nornagon-v0.29.0-patch#
 dependencies = [
 "bitflags 2.10.0",
 "cassowary",
- "compact_str",
+ "compact_str 0.8.1",
 "crossterm",
 "indoc",
 "instability",
@@ -5363,7 +5443,27 @@ dependencies = [
 "paste",
 "strum 0.26.3",
 "unicode-segmentation",
- "unicode-truncate",
+ "unicode-truncate 1.1.0",
+ "unicode-width 0.2.1",
+]
+
+[[package]]
+name = "ratatui-core"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ef8dea09a92caaf73bff7adb70b76162e5937524058a7e5bff37869cbbec293"
+dependencies = [
+ "bitflags 2.10.0",
+ "compact_str 0.9.0",
+ "hashbrown 0.16.0",
+ "indoc",
+ "itertools 0.14.0",
+ "kasuari",
+ "lru 0.16.2",
+ "strum 0.27.2",
+ "thiserror 2.0.17",
+ "unicode-segmentation",
+ "unicode-truncate 2.0.0",
 "unicode-width 0.2.1",
 ]

@@ -5610,7 +5710,7 @@ dependencies = [
 "errno",
 "libc",
 "linux-raw-sys 0.4.15",
- "windows-sys 0.59.0",
+ "windows-sys 0.52.0",
 ]

 [[package]]
@@ -5623,7 +5723,7 @@ dependencies = [
 "errno",
 "libc",
 "linux-raw-sys 0.9.4",
- "windows-sys 0.60.2",
+ "windows-sys 0.52.0",
 ]

 [[package]]
@@ -6530,6 +6630,9 @@ name = "strum"
 version = "0.27.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "af23d6f6c1a224baef9d3f61e287d2761385a5b88fdab4eb4c6f11aeb54c4bcf"
+dependencies = [
+ "strum_macros 0.27.2",
+]

 [[package]]
 name = "strum_macros"
@@ -6969,9 +7072,9 @@ dependencies = [

 [[package]]
 name = "tokio-stream"
-version = "0.1.17"
+version = "0.1.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eca58d7bba4a75707817a2c44174253f9236b2d5fbd055602e9d5c07c139a047"
+checksum = "32da49809aab5c3bc678af03902d4ccddea2a87d028d86392a4b1560c6906c70"
 dependencies = [
 "futures-core",
 "pin-project-lite",
@@ -7082,15 +7185,13 @@ checksum = "ab16f14aed21ee8bfd8ec22513f7287cd4a91aa92e44edfe2c17ddd004e92607"

 [[package]]
 name = "tonic"
-version = "0.13.1"
+version = "0.14.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7e581ba15a835f4d9ea06c55ab1bd4dce26fc53752c69a04aac00703bfb49ba9"
+checksum = "eb7613188ce9f7df5bfe185db26c5814347d110db17920415cf2fbcad85e7203"
 dependencies = [
 "async-trait",
- "axum",
 "base64",
 "bytes",
- "h2",
 "http 1.3.1",
 "http-body",
 "http-body-util",
@@ -7099,9 +7200,8 @@ dependencies = [
 "hyper-util",
 "percent-encoding",
 "pin-project",
- "prost",
 "rustls-native-certs",
- "socket2 0.5.10",
+ "sync_wrapper",
 "tokio",
 "tokio-rustls",
 "tokio-stream",
@@ -7111,6 +7211,17 @@ dependencies = [
 "tracing",
 ]

+[[package]]
+name = "tonic-prost"
+version = "0.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66bd50ad6ce1252d87ef024b3d64fe4c3cf54a86fb9ef4c631fdd0ded7aeaa67"
+dependencies = [
+ "bytes",
+ "prost",
+ "tonic",
+]
+
 [[package]]
 name = "tower"
 version = "0.5.2"
@@ -7228,15 +7339,16 @@ dependencies = [

 [[package]]
 name = "tracing-opentelemetry"
-version = "0.31.0"
+version = "0.32.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ddcf5959f39507d0d04d6413119c04f33b623f4f951ebcbdddddfad2d0623a9c"
+checksum = "1e6e5658463dd88089aba75c7791e1d3120633b1bfde22478b28f625a9bb1b8e"
 dependencies = [
 "js-sys",
- "once_cell",
 "opentelemetry",
 "opentelemetry_sdk",
+ "rustversion",
 "smallvec",
+ "thiserror 2.0.17",
 "tracing",
 "tracing-core",
 "tracing-log",
@@ -7367,6 +7479,16 @@ dependencies = [
 "termcolor",
 ]

+[[package]]
+name = "tui-scrollbar"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c42613099915b2e30e9f144670666e858e2538366f77742e1cf1c2f230efcacd"
+dependencies = [
+ "document-features",
+ "ratatui-core",
+]
+
 [[package]]
 name = "typenum"
 version = "1.18.0"
@@ -7393,6 +7515,12 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
 [[package]]
 name = "unicase"
 version = "2.8.1"
@@ -7428,6 +7556,17 @@ dependencies = [
 "unicode-width 0.1.14",
 ]

+[[package]]
+name = "unicode-truncate"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fbf03860ff438702f3910ca5f28f8dac63c1c11e7efb5012b8b175493606330"
+dependencies = [
+ "itertools 0.13.0",
+ "unicode-segmentation",
+ "unicode-width 0.2.1",
+]
+
 [[package]]
 name = "unicode-width"
 version = "0.1.14"
@@ -7872,7 +8011,7 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf221c93e13a30d793f7645a0e7762c55d169dbb0a49671918a2319d289b10bb"
 dependencies = [
- "windows-sys 0.59.0",
+ "windows-sys 0.52.0",
 ]

 [[package]]
@@ -145,7 +145,7 @@ ignore = "0.4.23"
 image = { version = "^0.25.9", default-features = false }
 include_dir = "0.7.4"
 indexmap = "2.12.0"
-insta = "1.44.3"
+insta = "1.46.0"
 itertools = "0.14.0"
 keyring = { version = "3.6", default-features = false }
 landlock = "0.4.4"
@@ -160,12 +160,12 @@ notify = "8.2.0"
 nucleo-matcher = "0.3.1"
 once_cell = "1.20.2"
 openssl-sys = "*"
-opentelemetry = "0.30.0"
-opentelemetry-appender-tracing = "0.30.0"
-opentelemetry-otlp = "0.30.0"
-opentelemetry-semantic-conventions = "0.30.0"
-opentelemetry_sdk = "0.30.0"
-tracing-opentelemetry = "0.31.0"
+opentelemetry = "0.31.0"
+opentelemetry-appender-tracing = "0.31.0"
+opentelemetry-otlp = "0.31.0"
+opentelemetry-semantic-conventions = "0.31.0"
+opentelemetry_sdk = "0.31.0"
+tracing-opentelemetry = "0.32.0"
 os_info = "3.12.0"
 owo-colors = "4.2.0"
 path-absolutize = "3.1.1"
@@ -176,6 +176,7 @@ pretty_assertions = "1.4.1"
 pulldown-cmark = "0.10"
 rand = "0.9"
 ratatui = "0.29.0"
+ratatui-core = "0.1.0"
 ratatui-macros = "0.6.0"
 regex = "1.12.2"
 regex-lite = "0.1.8"
@@ -206,12 +207,11 @@ thiserror = "2.0.17"
 time = "0.3"
 tiny_http = "0.12"
 tokio = "1"
-tokio-stream = "0.1.17"
+tokio-stream = "0.1.18"
 tokio-test = "0.4"
 tokio-util = "0.7.16"
 toml = "0.9.5"
 toml_edit = "0.24.0"
-tonic = "0.13.1"
 tracing = "0.1.43"
 tracing-appender = "0.2.3"
 tracing-subscriber = "0.3.22"
@@ -220,6 +220,7 @@ tree-sitter = "0.25.10"
 tree-sitter-bash = "0.25"
 tree-sitter-highlight = "0.25.10"
 ts-rs = "11"
+tui-scrollbar = "0.2.1"
 uds_windows = "1.1.0"
 unicode-segmentation = "1.12.0"
 unicode-width = "0.2"
@@ -15,8 +15,8 @@ You can also install via Homebrew (`brew install --cask codex`) or download a pl

 ## Documentation quickstart

- First run with Codex? Follow the walkthrough in [`docs/getting-started.md`](../docs/getting-started.md) for prompts, keyboard shortcuts, and session management.
- Already shipping with Codex and want deeper control? Jump to [`docs/advanced.md`](../docs/advanced.md) and the configuration reference at [`docs/config.md`](../docs/config.md).
+- First run with Codex? Start with [`docs/getting-started.md`](../docs/getting-started.md) (links to the walkthrough for prompts, keyboard shortcuts, and session management).
+- Want deeper control? See [`docs/config.md`](../docs/config.md) and [`docs/install.md`](../docs/install.md).

 ## What's new in the Rust CLI

@@ -30,7 +30,7 @@ Codex supports a rich set of configuration options. Note that the Rust CLI uses

 #### MCP client

-Codex CLI functions as an MCP client that allows the Codex CLI and IDE extension to connect to MCP servers on startup. See the [`configuration documentation`](../docs/config.md#mcp_servers) for details.
+Codex CLI functions as an MCP client that allows the Codex CLI and IDE extension to connect to MCP servers on startup. See the [`configuration documentation`](../docs/config.md#connecting-to-mcp-servers) for details.

 #### MCP server (experimental)

@@ -384,6 +384,8 @@ pub struct SendUserTurnParams {
    pub model: String,
    pub effort: Option<ReasoningEffort>,
    pub summary: ReasoningSummary,
+    /// Optional JSON Schema used to constrain the final assistant message for this turn.
+    pub output_schema: Option<serde_json::Value>,
 }

 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
@@ -1319,6 +1319,8 @@ pub struct TurnStartParams {
    pub effort: Option<ReasoningEffort>,
    /// Override the reasoning summary for this turn and subsequent turns.
    pub summary: Option<ReasoningSummary>,
+    /// Optional JSON Schema used to constrain the final assistant message for this turn.
+    pub output_schema: Option<JsonValue>,
 }

 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
@@ -162,7 +162,7 @@ Turns attach user input (text or images) to a thread and trigger Codex generatio
 - `{"type":"image","url":"https://…png"}`
 - `{"type":"localImage","path":"/tmp/screenshot.png"}`

-You can optionally specify config overrides on the new turn. If specified, these settings become the default for subsequent turns on the same thread.
+You can optionally specify config overrides on the new turn. If specified, these settings become the default for subsequent turns on the same thread. `outputSchema` applies only to the current turn.

 ```json
 { "method": "turn/start", "id": 30, "params": {
@@ -178,7 +178,14 @@ You can optionally specify config overrides on the new turn. If specified, these
    },
    "model": "gpt-5.1-codex",
    "effort": "medium",
-    "summary": "concise"
+    "summary": "concise",
+    // Optional JSON Schema to constrain the final assistant message for this turn.
+    "outputSchema": {
+        "type": "object",
+        "properties": { "answer": { "type": "string" } },
+        "required": ["answer"],
+        "additionalProperties": false
+    }
 } }
 { "id": 30, "result": { "turn": {
    "id": "turn_456",
@@ -2579,6 +2579,7 @@ impl CodexMessageProcessor {
        let _ = conversation
            .submit(Op::UserInput {
                items: mapped_items,
+                final_output_json_schema: None,
            })
            .await;

@@ -2598,6 +2599,7 @@ impl CodexMessageProcessor {
            model,
            effort,
            summary,
+            output_schema,
        } = params;

        let Ok(conversation) = self
@@ -2632,7 +2634,7 @@ impl CodexMessageProcessor {
                model,
                effort,
                summary,
-                final_output_json_schema: None,
+                final_output_json_schema: output_schema,
            })
            .await;

@@ -2650,19 +2652,17 @@ impl CodexMessageProcessor {
        };

        let skills_manager = self.conversation_manager.skills_manager();
-        let data = cwds
-            .into_iter()
-            .map(|cwd| {
-                let outcome = skills_manager.skills_for_cwd_with_options(&cwd, force_reload);
-                let errors = errors_to_info(&outcome.errors);
-                let skills = skills_to_info(&outcome.skills);
-                codex_app_server_protocol::SkillsListEntry {
-                    cwd,
-                    skills,
-                    errors,
-                }
-            })
-            .collect();
+        let mut data = Vec::new();
+        for cwd in cwds {
+            let outcome = skills_manager.skills_for_cwd(&cwd, force_reload).await;
+            let errors = errors_to_info(&outcome.errors);
+            let skills = skills_to_info(&outcome.skills);
+            data.push(codex_app_server_protocol::SkillsListEntry {
+                cwd,
+                skills,
+                errors,
+            });
+        }
        self.outgoing
            .send_response(request_id, SkillsListResponse { data })
            .await;
@@ -2741,6 +2741,7 @@ impl CodexMessageProcessor {
        let turn_id = conversation
            .submit(Op::UserInput {
                items: mapped_items,
+                final_output_json_schema: params.output_schema,
            })
            .await;

@@ -17,13 +17,11 @@ use tokio::io::BufReader;
 use tokio::io::{self};
 use tokio::sync::mpsc;
 use toml::Value as TomlValue;
-use tracing::Level;
 use tracing::debug;
 use tracing::error;
 use tracing::info;
 use tracing_subscriber::EnvFilter;
 use tracing_subscriber::Layer;
-use tracing_subscriber::filter::Targets;
 use tracing_subscriber::layer::SubscriberExt;
 use tracing_subscriber::util::SubscriberInitExt;

@@ -103,11 +101,8 @@ pub async fn run_main(
        .with_span_events(tracing_subscriber::fmt::format::FmtSpan::FULL)
        .with_filter(EnvFilter::from_default_env());

-    let feedback_layer = tracing_subscriber::fmt::layer()
-        .with_writer(feedback.make_writer())
-        .with_ansi(false)
-        .with_target(false)
-        .with_filter(Targets::new().with_default(Level::TRACE));
+    let feedback_layer = feedback.logger_layer();
+    let feedback_metadata_layer = feedback.metadata_layer();

    let otel_logger_layer = otel.as_ref().and_then(|o| o.logger_layer());

@@ -116,6 +111,7 @@ pub async fn run_main(
    let _ = tracing_subscriber::registry()
        .with(stderr_fmt)
        .with(feedback_layer)
+        .with(feedback_metadata_layer)
        .with(otel_logger_layer)
        .with(otel_tracing_layer)
        .try_init();
@@ -305,6 +305,7 @@ async fn test_send_user_turn_changes_approval_policy_behavior() -> Result<()> {
            model: "mock-model".to_string(),
            effort: Some(ReasoningEffort::Medium),
            summary: ReasoningSummary::Auto,
+            output_schema: None,
        })
        .await?;
    // Acknowledge sendUserTurn
@@ -418,6 +419,7 @@ async fn test_send_user_turn_updates_sandbox_and_cwd_between_turns() -> Result<(
            model: model.clone(),
            effort: Some(ReasoningEffort::Medium),
            summary: ReasoningSummary::Auto,
+            output_schema: None,
        })
        .await?;
    timeout(
@@ -443,6 +445,7 @@ async fn test_send_user_turn_updates_sandbox_and_cwd_between_turns() -> Result<(
            model: model.clone(),
            effort: Some(ReasoningEffort::Medium),
            summary: ReasoningSummary::Auto,
+            output_schema: None,
        })
        .await?;
    timeout(
@@ -7,6 +7,7 @@ mod fuzzy_file_search;
 mod interrupt;
 mod list_resume;
 mod login;
+mod output_schema;
 mod send_message;
 mod set_default_model;
 mod user_agent;
@@ -0,0 +1,282 @@
+use anyhow::Result;
+use app_test_support::McpProcess;
+use app_test_support::to_response;
+use codex_app_server_protocol::AddConversationListenerParams;
+use codex_app_server_protocol::InputItem;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::NewConversationParams;
+use codex_app_server_protocol::NewConversationResponse;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::SendUserTurnParams;
+use codex_app_server_protocol::SendUserTurnResponse;
+use codex_core::protocol::AskForApproval;
+use codex_core::protocol::SandboxPolicy;
+use codex_protocol::config_types::ReasoningSummary;
+use codex_protocol::openai_models::ReasoningEffort;
+use core_test_support::responses;
+use core_test_support::skip_if_no_network;
+use pretty_assertions::assert_eq;
+use std::path::Path;
+use tempfile::TempDir;
+use tokio::time::timeout;
+
+const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
+
+#[tokio::test]
+async fn send_user_turn_accepts_output_schema_v1() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp-1"),
+        responses::ev_assistant_message("msg-1", "Done"),
+        responses::ev_completed("resp-1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let new_conv_id = mcp
+        .send_new_conversation_request(NewConversationParams {
+            ..Default::default()
+        })
+        .await?;
+    let new_conv_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(new_conv_id)),
+    )
+    .await??;
+    let NewConversationResponse {
+        conversation_id, ..
+    } = to_response::<NewConversationResponse>(new_conv_resp)?;
+
+    let listener_id = mcp
+        .send_add_conversation_listener_request(AddConversationListenerParams {
+            conversation_id,
+            experimental_raw_events: false,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(listener_id)),
+    )
+    .await??;
+
+    let output_schema = serde_json::json!({
+        "type": "object",
+        "properties": {
+            "answer": { "type": "string" }
+        },
+        "required": ["answer"],
+        "additionalProperties": false
+    });
+
+    let send_turn_id = mcp
+        .send_send_user_turn_request(SendUserTurnParams {
+            conversation_id,
+            items: vec![InputItem::Text {
+                text: "Hello".to_string(),
+            }],
+            cwd: codex_home.path().to_path_buf(),
+            approval_policy: AskForApproval::Never,
+            sandbox_policy: SandboxPolicy::new_read_only_policy(),
+            model: "mock-model".to_string(),
+            effort: Some(ReasoningEffort::Medium),
+            summary: ReasoningSummary::Auto,
+            output_schema: Some(output_schema.clone()),
+        })
+        .await?;
+    let _send_turn_resp: SendUserTurnResponse = to_response::<SendUserTurnResponse>(
+        timeout(
+            DEFAULT_READ_TIMEOUT,
+            mcp.read_stream_until_response_message(RequestId::Integer(send_turn_id)),
+        )
+        .await??,
+    )?;
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("codex/event/task_complete"),
+    )
+    .await??;
+
+    let request = response_mock.single_request();
+    let payload = request.body_json();
+    let text = payload.get("text").expect("request missing text field");
+    let format = text
+        .get("format")
+        .expect("request missing text.format field");
+    assert_eq!(
+        format,
+        &serde_json::json!({
+            "name": "codex_output_schema",
+            "type": "json_schema",
+            "strict": true,
+            "schema": output_schema,
+        })
+    );
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn send_user_turn_output_schema_is_per_turn_v1() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = responses::start_mock_server().await;
+    let body1 = responses::sse(vec![
+        responses::ev_response_created("resp-1"),
+        responses::ev_assistant_message("msg-1", "Done"),
+        responses::ev_completed("resp-1"),
+    ]);
+    let response_mock1 = responses::mount_sse_once(&server, body1).await;
+
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let new_conv_id = mcp
+        .send_new_conversation_request(NewConversationParams {
+            ..Default::default()
+        })
+        .await?;
+    let new_conv_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(new_conv_id)),
+    )
+    .await??;
+    let NewConversationResponse {
+        conversation_id, ..
+    } = to_response::<NewConversationResponse>(new_conv_resp)?;
+
+    let listener_id = mcp
+        .send_add_conversation_listener_request(AddConversationListenerParams {
+            conversation_id,
+            experimental_raw_events: false,
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(listener_id)),
+    )
+    .await??;
+
+    let output_schema = serde_json::json!({
+        "type": "object",
+        "properties": {
+            "answer": { "type": "string" }
+        },
+        "required": ["answer"],
+        "additionalProperties": false
+    });
+
+    let send_turn_id = mcp
+        .send_send_user_turn_request(SendUserTurnParams {
+            conversation_id,
+            items: vec![InputItem::Text {
+                text: "Hello".to_string(),
+            }],
+            cwd: codex_home.path().to_path_buf(),
+            approval_policy: AskForApproval::Never,
+            sandbox_policy: SandboxPolicy::new_read_only_policy(),
+            model: "mock-model".to_string(),
+            effort: Some(ReasoningEffort::Medium),
+            summary: ReasoningSummary::Auto,
+            output_schema: Some(output_schema.clone()),
+        })
+        .await?;
+    let _send_turn_resp: SendUserTurnResponse = to_response::<SendUserTurnResponse>(
+        timeout(
+            DEFAULT_READ_TIMEOUT,
+            mcp.read_stream_until_response_message(RequestId::Integer(send_turn_id)),
+        )
+        .await??,
+    )?;
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("codex/event/task_complete"),
+    )
+    .await??;
+
+    let payload1 = response_mock1.single_request().body_json();
+    assert_eq!(
+        payload1.pointer("/text/format"),
+        Some(&serde_json::json!({
+            "name": "codex_output_schema",
+            "type": "json_schema",
+            "strict": true,
+            "schema": output_schema,
+        }))
+    );
+
+    let body2 = responses::sse(vec![
+        responses::ev_response_created("resp-2"),
+        responses::ev_assistant_message("msg-2", "Done"),
+        responses::ev_completed("resp-2"),
+    ]);
+    let response_mock2 = responses::mount_sse_once(&server, body2).await;
+
+    let send_turn_id_2 = mcp
+        .send_send_user_turn_request(SendUserTurnParams {
+            conversation_id,
+            items: vec![InputItem::Text {
+                text: "Hello again".to_string(),
+            }],
+            cwd: codex_home.path().to_path_buf(),
+            approval_policy: AskForApproval::Never,
+            sandbox_policy: SandboxPolicy::new_read_only_policy(),
+            model: "mock-model".to_string(),
+            effort: Some(ReasoningEffort::Medium),
+            summary: ReasoningSummary::Auto,
+            output_schema: None,
+        })
+        .await?;
+    let _send_turn_resp_2: SendUserTurnResponse = to_response::<SendUserTurnResponse>(
+        timeout(
+            DEFAULT_READ_TIMEOUT,
+            mcp.read_stream_until_response_message(RequestId::Integer(send_turn_id_2)),
+        )
+        .await??,
+    )?;
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("codex/event/task_complete"),
+    )
+    .await??;
+
+    let payload2 = response_mock2.single_request().body_json();
+    assert_eq!(payload2.pointer("/text/format"), None);
+
+    Ok(())
+}
+
+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 = "read-only"
+
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "responses"
+request_max_retries = 0
+stream_max_retries = 0
+"#
+        ),
+    )
+}
@@ -1,6 +1,7 @@
 mod account;
 mod config_rpc;
 mod model_list;
+mod output_schema;
 mod rate_limits;
 mod review;
 mod thread_archive;
@@ -0,0 +1,231 @@
+use anyhow::Result;
+use app_test_support::McpProcess;
+use app_test_support::to_response;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::ThreadStartParams;
+use codex_app_server_protocol::ThreadStartResponse;
+use codex_app_server_protocol::TurnStartParams;
+use codex_app_server_protocol::TurnStartResponse;
+use codex_app_server_protocol::UserInput as V2UserInput;
+use core_test_support::responses;
+use core_test_support::skip_if_no_network;
+use pretty_assertions::assert_eq;
+use std::path::Path;
+use tempfile::TempDir;
+use tokio::time::timeout;
+
+const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
+
+#[tokio::test]
+async fn turn_start_accepts_output_schema_v2() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp-1"),
+        responses::ev_assistant_message("msg-1", "Done"),
+        responses::ev_completed("resp-1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let thread_req = mcp
+        .send_thread_start_request(ThreadStartParams {
+            ..Default::default()
+        })
+        .await?;
+    let thread_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(thread_req)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response::<ThreadStartResponse>(thread_resp)?;
+
+    let output_schema = serde_json::json!({
+        "type": "object",
+        "properties": {
+            "answer": { "type": "string" }
+        },
+        "required": ["answer"],
+        "additionalProperties": false
+    });
+
+    let turn_req = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id.clone(),
+            input: vec![V2UserInput::Text {
+                text: "Hello".to_string(),
+            }],
+            output_schema: Some(output_schema.clone()),
+            ..Default::default()
+        })
+        .await?;
+    let turn_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_req)),
+    )
+    .await??;
+    let _turn: TurnStartResponse = to_response::<TurnStartResponse>(turn_resp)?;
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let request = response_mock.single_request();
+    let payload = request.body_json();
+    let text = payload.get("text").expect("request missing text field");
+    let format = text
+        .get("format")
+        .expect("request missing text.format field");
+    assert_eq!(
+        format,
+        &serde_json::json!({
+            "name": "codex_output_schema",
+            "type": "json_schema",
+            "strict": true,
+            "schema": output_schema,
+        })
+    );
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn turn_start_output_schema_is_per_turn_v2() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = responses::start_mock_server().await;
+    let body1 = responses::sse(vec![
+        responses::ev_response_created("resp-1"),
+        responses::ev_assistant_message("msg-1", "Done"),
+        responses::ev_completed("resp-1"),
+    ]);
+    let response_mock1 = responses::mount_sse_once(&server, body1).await;
+
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let thread_req = mcp
+        .send_thread_start_request(ThreadStartParams {
+            ..Default::default()
+        })
+        .await?;
+    let thread_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(thread_req)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response::<ThreadStartResponse>(thread_resp)?;
+
+    let output_schema = serde_json::json!({
+        "type": "object",
+        "properties": {
+            "answer": { "type": "string" }
+        },
+        "required": ["answer"],
+        "additionalProperties": false
+    });
+
+    let turn_req_1 = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id.clone(),
+            input: vec![V2UserInput::Text {
+                text: "Hello".to_string(),
+            }],
+            output_schema: Some(output_schema.clone()),
+            ..Default::default()
+        })
+        .await?;
+    let turn_resp_1: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_req_1)),
+    )
+    .await??;
+    let _turn: TurnStartResponse = to_response::<TurnStartResponse>(turn_resp_1)?;
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let payload1 = response_mock1.single_request().body_json();
+    assert_eq!(
+        payload1.pointer("/text/format"),
+        Some(&serde_json::json!({
+            "name": "codex_output_schema",
+            "type": "json_schema",
+            "strict": true,
+            "schema": output_schema,
+        }))
+    );
+
+    let body2 = responses::sse(vec![
+        responses::ev_response_created("resp-2"),
+        responses::ev_assistant_message("msg-2", "Done"),
+        responses::ev_completed("resp-2"),
+    ]);
+    let response_mock2 = responses::mount_sse_once(&server, body2).await;
+
+    let turn_req_2 = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id.clone(),
+            input: vec![V2UserInput::Text {
+                text: "Hello again".to_string(),
+            }],
+            output_schema: None,
+            ..Default::default()
+        })
+        .await?;
+    let turn_resp_2: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_req_2)),
+    )
+    .await??;
+    let _turn: TurnStartResponse = to_response::<TurnStartResponse>(turn_resp_2)?;
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let payload2 = response_mock2.single_request().body_json();
+    assert_eq!(payload2.pointer("/text/format"), None);
+
+    Ok(())
+}
+
+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 = "read-only"
+
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "responses"
+request_max_retries = 0
+stream_max_retries = 0
+"#
+        ),
+    )
+}
@@ -540,6 +540,7 @@ async fn turn_start_updates_sandbox_and_cwd_between_turns_v2() -> Result<()> {
            model: Some("mock-model".to_string()),
            effort: Some(ReasoningEffort::Medium),
            summary: Some(ReasoningSummary::Auto),
+            output_schema: None,
        })
        .await?;
    timeout(
@@ -566,6 +567,7 @@ async fn turn_start_updates_sandbox_and_cwd_between_turns_v2() -> Result<()> {
            model: Some("mock-model".to_string()),
            effort: Some(ReasoningEffort::Medium),
            summary: Some(ReasoningSummary::Auto),
+            output_schema: None,
        })
        .await?;
    timeout(
@@ -59,3 +59,61 @@ prefix_rule(

    Ok(())
 }
+
+#[test]
+fn execpolicy_check_includes_justification_when_present() -> Result<(), Box<dyn std::error::Error>>
+{
+    let codex_home = TempDir::new()?;
+    let policy_path = codex_home.path().join("rules").join("policy.rules");
+    fs::create_dir_all(
+        policy_path
+            .parent()
+            .expect("policy path should have a parent"),
+    )?;
+    fs::write(
+        &policy_path,
+        r#"
+prefix_rule(
+    pattern = ["git", "push"],
+    decision = "forbidden",
+    justification = "pushing is blocked in this repo",
+)
+"#,
+    )?;
+
+    let output = Command::new(codex_utils_cargo_bin::cargo_bin("codex")?)
+        .env("CODEX_HOME", codex_home.path())
+        .args([
+            "execpolicy",
+            "check",
+            "--rules",
+            policy_path
+                .to_str()
+                .expect("policy path should be valid UTF-8"),
+            "git",
+            "push",
+            "origin",
+            "main",
+        ])
+        .output()?;
+
+    assert!(output.status.success());
+    let result: serde_json::Value = serde_json::from_slice(&output.stdout)?;
+    assert_eq!(
+        result,
+        json!({
+            "decision": "forbidden",
+            "matchedRules": [
+                {
+                    "prefixRuleMatch": {
+                        "matchedPrefix": ["git", "push"],
+                        "decision": "forbidden",
+                        "justification": "pushing is blocked in this repo"
+                    }
+                }
+            ]
+        })
+    );
+
+    Ok(())
+}
@@ -59,6 +59,7 @@ pub enum ResponseEvent {
        summary_index: i64,
    },
    RateLimits(RateLimitSnapshot),
+    ModelsEtag(String),
 }

 #[derive(Debug, Serialize, Clone)]
@@ -152,6 +152,9 @@ impl Stream for AggregatedStream {
                Poll::Ready(Some(Ok(ResponseEvent::RateLimits(snapshot)))) => {
                    return Poll::Ready(Some(Ok(ResponseEvent::RateLimits(snapshot))));
                }
+                Poll::Ready(Some(Ok(ResponseEvent::ModelsEtag(etag)))) => {
+                    return Poll::Ready(Some(Ok(ResponseEvent::ModelsEtag(etag))));
+                }
                Poll::Ready(Some(Ok(ResponseEvent::Completed {
                    response_id,
                    token_usage,
@@ -5,6 +5,7 @@ use crate::provider::Provider;
 use crate::telemetry::run_with_request_telemetry;
 use codex_client::HttpTransport;
 use codex_client::RequestTelemetry;
+use codex_protocol::openai_models::ModelInfo;
 use codex_protocol::openai_models::ModelsResponse;
 use http::HeaderMap;
 use http::Method;
@@ -41,7 +42,7 @@ impl<T: HttpTransport, A: AuthProvider> ModelsClient<T, A> {
        &self,
        client_version: &str,
        extra_headers: HeaderMap,
-    ) -> Result<ModelsResponse, ApiError> {
+    ) -> Result<(Vec<ModelInfo>, Option<String>), ApiError> {
        let builder = || {
            let mut req = self.provider.build_request(Method::GET, self.path());
            req.headers.extend(extra_headers.clone());
@@ -66,7 +67,7 @@ impl<T: HttpTransport, A: AuthProvider> ModelsClient<T, A> {
            .and_then(|value| value.to_str().ok())
            .map(ToString::to_string);

-        let ModelsResponse { models, etag } = serde_json::from_slice::<ModelsResponse>(&resp.body)
+        let ModelsResponse { models } = serde_json::from_slice::<ModelsResponse>(&resp.body)
            .map_err(|e| {
                ApiError::Stream(format!(
                    "failed to decode models response: {e}; body: {}",
@@ -74,9 +75,7 @@ impl<T: HttpTransport, A: AuthProvider> ModelsClient<T, A> {
                ))
            })?;

-        let etag = header_etag.unwrap_or(etag);
-
-        Ok(ModelsResponse { models, etag })
+        Ok((models, header_etag))
    }
 }

@@ -102,16 +101,15 @@ mod tests {
    struct CapturingTransport {
        last_request: Arc<Mutex<Option<Request>>>,
        body: Arc<ModelsResponse>,
+        etag: Option<String>,
    }

    impl Default for CapturingTransport {
        fn default() -> Self {
            Self {
                last_request: Arc::new(Mutex::new(None)),
-                body: Arc::new(ModelsResponse {
-                    models: Vec::new(),
-                    etag: String::new(),
-                }),
+                body: Arc::new(ModelsResponse { models: Vec::new() }),
+                etag: None,
            }
        }
    }
@@ -122,8 +120,8 @@ mod tests {
            *self.last_request.lock().unwrap() = Some(req);
            let body = serde_json::to_vec(&*self.body).unwrap();
            let mut headers = HeaderMap::new();
-            if !self.body.etag.is_empty() {
-                headers.insert(ETAG, self.body.etag.parse().unwrap());
+            if let Some(etag) = &self.etag {
+                headers.insert(ETAG, etag.parse().unwrap());
            }
            Ok(Response {
                status: StatusCode::OK,
@@ -166,14 +164,12 @@ mod tests {

    #[tokio::test]
    async fn appends_client_version_query() {
-        let response = ModelsResponse {
-            models: Vec::new(),
-            etag: String::new(),
-        };
+        let response = ModelsResponse { models: Vec::new() };

        let transport = CapturingTransport {
            last_request: Arc::new(Mutex::new(None)),
            body: Arc::new(response),
+            etag: None,
        };

        let client = ModelsClient::new(
@@ -182,12 +178,12 @@ mod tests {
            DummyAuth,
        );

-        let result = client
+        let (models, _) = client
            .list_models("0.99.0", HeaderMap::new())
            .await
            .expect("request should succeed");

-        assert_eq!(result.models.len(), 0);
+        assert_eq!(models.len(), 0);

        let url = transport
            .last_request
@@ -231,12 +227,12 @@ mod tests {
                }))
                .unwrap(),
            ],
-            etag: String::new(),
        };

        let transport = CapturingTransport {
            last_request: Arc::new(Mutex::new(None)),
            body: Arc::new(response),
+            etag: None,
        };

        let client = ModelsClient::new(
@@ -245,27 +241,25 @@ mod tests {
            DummyAuth,
        );

-        let result = client
+        let (models, _) = client
            .list_models("0.99.0", HeaderMap::new())
            .await
            .expect("request should succeed");

-        assert_eq!(result.models.len(), 1);
-        assert_eq!(result.models[0].slug, "gpt-test");
-        assert_eq!(result.models[0].supported_in_api, true);
-        assert_eq!(result.models[0].priority, 1);
+        assert_eq!(models.len(), 1);
+        assert_eq!(models[0].slug, "gpt-test");
+        assert_eq!(models[0].supported_in_api, true);
+        assert_eq!(models[0].priority, 1);
    }

    #[tokio::test]
    async fn list_models_includes_etag() {
-        let response = ModelsResponse {
-            models: Vec::new(),
-            etag: "\"abc\"".to_string(),
-        };
+        let response = ModelsResponse { models: Vec::new() };

        let transport = CapturingTransport {
            last_request: Arc::new(Mutex::new(None)),
            body: Arc::new(response),
+            etag: Some("\"abc\"".to_string()),
        };

        let client = ModelsClient::new(
@@ -274,12 +268,12 @@ mod tests {
            DummyAuth,
        );

-        let result = client
+        let (models, etag) = client
            .list_models("0.1.0", HeaderMap::new())
            .await
            .expect("request should succeed");

-        assert_eq!(result.models.len(), 0);
-        assert_eq!(result.etag, "\"abc\"");
+        assert_eq!(models.len(), 0);
+        assert_eq!(etag, Some("\"abc\"".to_string()));
    }
 }
@@ -204,24 +204,16 @@ impl<'a> ChatRequestBuilder<'a> {
                    call_id,
                    ..
                } => {
-                    let mut msg = json!({
-                        "role": "assistant",
-                        "content": null,
-                        "tool_calls": [{
-                            "id": call_id,
-                            "type": "function",
-                            "function": {
-                                "name": name,
-                                "arguments": arguments,
-                            }
-                        }]
+                    let reasoning = reasoning_by_anchor_index.get(&idx).map(String::as_str);
+                    let tool_call = json!({
+                        "id": call_id,
+                        "type": "function",
+                        "function": {
+                            "name": name,
+                            "arguments": arguments,
+                        }
                    });
-                    if let Some(reasoning) = reasoning_by_anchor_index.get(&idx)
-                        && let Some(obj) = msg.as_object_mut()
-                    {
-                        obj.insert("reasoning".to_string(), json!(reasoning));
-                    }
-                    messages.push(msg);
+                    push_tool_call_message(&mut messages, tool_call, reasoning);
                }
                ResponseItem::LocalShellCall {
                    id,
@@ -229,22 +221,14 @@ impl<'a> ChatRequestBuilder<'a> {
                    status,
                    action,
                } => {
-                    let mut msg = json!({
-                        "role": "assistant",
-                        "content": null,
-                        "tool_calls": [{
-                            "id": id.clone().unwrap_or_default(),
-                            "type": "local_shell_call",
-                            "status": status,
-                            "action": action,
-                        }]
+                    let reasoning = reasoning_by_anchor_index.get(&idx).map(String::as_str);
+                    let tool_call = json!({
+                        "id": id.clone().unwrap_or_default(),
+                        "type": "local_shell_call",
+                        "status": status,
+                        "action": action,
                    });
-                    if let Some(reasoning) = reasoning_by_anchor_index.get(&idx)
-                        && let Some(obj) = msg.as_object_mut()
-                    {
-                        obj.insert("reasoning".to_string(), json!(reasoning));
-                    }
-                    messages.push(msg);
+                    push_tool_call_message(&mut messages, tool_call, reasoning);
                }
                ResponseItem::FunctionCallOutput { call_id, output } => {
                    let content_value = if let Some(items) = &output.content_items {
@@ -277,18 +261,16 @@ impl<'a> ChatRequestBuilder<'a> {
                    input,
                    status: _,
                } => {
-                    messages.push(json!({
-                        "role": "assistant",
-                        "content": null,
-                        "tool_calls": [{
-                            "id": id,
-                            "type": "custom",
-                            "custom": {
-                                "name": name,
-                                "input": input,
-                            }
-                        }]
-                    }));
+                    let tool_call = json!({
+                        "id": id,
+                        "type": "custom",
+                        "custom": {
+                            "name": name,
+                            "input": input,
+                        }
+                    });
+                    let reasoning = reasoning_by_anchor_index.get(&idx).map(String::as_str);
+                    push_tool_call_message(&mut messages, tool_call, reasoning);
                }
                ResponseItem::CustomToolCallOutput { call_id, output } => {
                    messages.push(json!({
@@ -328,11 +310,50 @@ impl<'a> ChatRequestBuilder<'a> {
    }
 }

+fn push_tool_call_message(messages: &mut Vec<Value>, tool_call: Value, reasoning: Option<&str>) {
+    // Chat Completions requires that tool calls are grouped into a single assistant message
+    // (with `tool_calls: [...]`) followed by tool role responses.
+    if let Some(Value::Object(obj)) = messages.last_mut()
+        && obj.get("role").and_then(Value::as_str) == Some("assistant")
+        && obj.get("content").is_some_and(Value::is_null)
+        && let Some(tool_calls) = obj.get_mut("tool_calls").and_then(Value::as_array_mut)
+    {
+        tool_calls.push(tool_call);
+        if let Some(reasoning) = reasoning {
+            if let Some(Value::String(existing)) = obj.get_mut("reasoning") {
+                if !existing.is_empty() {
+                    existing.push('\n');
+                }
+                existing.push_str(reasoning);
+            } else {
+                obj.insert(
+                    "reasoning".to_string(),
+                    Value::String(reasoning.to_string()),
+                );
+            }
+        }
+        return;
+    }
+
+    let mut msg = json!({
+        "role": "assistant",
+        "content": null,
+        "tool_calls": [tool_call],
+    });
+    if let Some(reasoning) = reasoning
+        && let Some(obj) = msg.as_object_mut()
+    {
+        obj.insert("reasoning".to_string(), json!(reasoning));
+    }
+    messages.push(msg);
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
    use crate::provider::RetryConfig;
    use crate::provider::WireApi;
+    use codex_protocol::models::FunctionCallOutputPayload;
    use codex_protocol::protocol::SessionSource;
    use codex_protocol::protocol::SubAgentSource;
    use http::HeaderValue;
@@ -385,4 +406,89 @@ mod tests {
            Some(&HeaderValue::from_static("review"))
        );
    }
+
+    #[test]
+    fn groups_consecutive_tool_calls_into_a_single_assistant_message() {
+        let prompt_input = vec![
+            ResponseItem::Message {
+                id: None,
+                role: "user".to_string(),
+                content: vec![ContentItem::InputText {
+                    text: "read these".to_string(),
+                }],
+            },
+            ResponseItem::FunctionCall {
+                id: None,
+                name: "read_file".to_string(),
+                arguments: r#"{"path":"a.txt"}"#.to_string(),
+                call_id: "call-a".to_string(),
+            },
+            ResponseItem::FunctionCall {
+                id: None,
+                name: "read_file".to_string(),
+                arguments: r#"{"path":"b.txt"}"#.to_string(),
+                call_id: "call-b".to_string(),
+            },
+            ResponseItem::FunctionCall {
+                id: None,
+                name: "read_file".to_string(),
+                arguments: r#"{"path":"c.txt"}"#.to_string(),
+                call_id: "call-c".to_string(),
+            },
+            ResponseItem::FunctionCallOutput {
+                call_id: "call-a".to_string(),
+                output: FunctionCallOutputPayload {
+                    content: "A".to_string(),
+                    ..Default::default()
+                },
+            },
+            ResponseItem::FunctionCallOutput {
+                call_id: "call-b".to_string(),
+                output: FunctionCallOutputPayload {
+                    content: "B".to_string(),
+                    ..Default::default()
+                },
+            },
+            ResponseItem::FunctionCallOutput {
+                call_id: "call-c".to_string(),
+                output: FunctionCallOutputPayload {
+                    content: "C".to_string(),
+                    ..Default::default()
+                },
+            },
+        ];
+
+        let req = ChatRequestBuilder::new("gpt-test", "inst", &prompt_input, &[])
+            .build(&provider())
+            .expect("request");
+
+        let messages = req
+            .body
+            .get("messages")
+            .and_then(|v| v.as_array())
+            .expect("messages array");
+        // system + user + assistant(tool_calls=[...]) + 3 tool outputs
+        assert_eq!(messages.len(), 6);
+
+        assert_eq!(messages[0]["role"], "system");
+        assert_eq!(messages[1]["role"], "user");
+
+        let tool_calls_msg = &messages[2];
+        assert_eq!(tool_calls_msg["role"], "assistant");
+        assert_eq!(tool_calls_msg["content"], serde_json::Value::Null);
+        let tool_calls = tool_calls_msg["tool_calls"]
+            .as_array()
+            .expect("tool_calls array");
+        assert_eq!(tool_calls.len(), 3);
+        assert_eq!(tool_calls[0]["id"], "call-a");
+        assert_eq!(tool_calls[1]["id"], "call-b");
+        assert_eq!(tool_calls[2]["id"], "call-c");
+
+        assert_eq!(messages[3]["role"], "tool");
+        assert_eq!(messages[3]["tool_call_id"], "call-a");
+        assert_eq!(messages[4]["role"], "tool");
+        assert_eq!(messages[4]["tool_call_id"], "call-b");
+        assert_eq!(messages[5]["role"], "tool");
+        assert_eq!(messages[5]["tool_call_id"], "call-c");
+    }
 }
@@ -30,6 +30,21 @@ pub(crate) fn spawn_chat_stream(
    ResponseStream { rx_event }
 }

+/// Processes Server-Sent Events from the legacy Chat Completions streaming API.
+///
+/// The upstream protocol terminates a streaming response with a final sentinel event
+/// (`data: [DONE]`). Historically, some of our test stubs have emitted `data: DONE`
+/// (without brackets) instead.
+///
+/// `eventsource_stream` delivers these sentinels as regular events rather than signaling
+/// end-of-stream. If we try to parse them as JSON, we log and skip them, then keep
+/// polling for more events.
+///
+/// On servers that keep the HTTP connection open after emitting the sentinel (notably
+/// wiremock on Windows), skipping the sentinel means we never emit `ResponseEvent::Completed`.
+/// Higher-level workflows/tests that wait for completion before issuing subsequent model
+/// calls will then stall, which shows up as "expected N requests, got 1" verification
+/// failures in the mock server.
 pub async fn process_chat_sse<S>(
    stream: S,
    tx_event: mpsc::Sender<Result<ResponseEvent, ApiError>>,
@@ -57,6 +72,31 @@ pub async fn process_chat_sse<S>(
    let mut reasoning_item: Option<ResponseItem> = None;
    let mut completed_sent = false;

+    async fn flush_and_complete(
+        tx_event: &mpsc::Sender<Result<ResponseEvent, ApiError>>,
+        reasoning_item: &mut Option<ResponseItem>,
+        assistant_item: &mut Option<ResponseItem>,
+    ) {
+        if let Some(reasoning) = reasoning_item.take() {
+            let _ = tx_event
+                .send(Ok(ResponseEvent::OutputItemDone(reasoning)))
+                .await;
+        }
+
+        if let Some(assistant) = assistant_item.take() {
+            let _ = tx_event
+                .send(Ok(ResponseEvent::OutputItemDone(assistant)))
+                .await;
+        }
+
+        let _ = tx_event
+            .send(Ok(ResponseEvent::Completed {
+                response_id: String::new(),
+                token_usage: None,
+            }))
+            .await;
+    }
+
    loop {
        let start = Instant::now();
        let response = timeout(idle_timeout, stream.next()).await;
@@ -70,24 +110,8 @@ pub async fn process_chat_sse<S>(
                return;
            }
            Ok(None) => {
-                if let Some(reasoning) = reasoning_item {
-                    let _ = tx_event
-                        .send(Ok(ResponseEvent::OutputItemDone(reasoning)))
-                        .await;
-                }
-
-                if let Some(assistant) = assistant_item {
-                    let _ = tx_event
-                        .send(Ok(ResponseEvent::OutputItemDone(assistant)))
-                        .await;
-                }
                if !completed_sent {
-                    let _ = tx_event
-                        .send(Ok(ResponseEvent::Completed {
-                            response_id: String::new(),
-                            token_usage: None,
-                        }))
-                        .await;
+                    flush_and_complete(&tx_event, &mut reasoning_item, &mut assistant_item).await;
                }
                return;
            }
@@ -101,16 +125,25 @@ pub async fn process_chat_sse<S>(

        trace!("SSE event: {}", sse.data);

-        if sse.data.trim().is_empty() {
+        let data = sse.data.trim();
+
+        if data.is_empty() {
            continue;
        }

-        let value: serde_json::Value = match serde_json::from_str(&sse.data) {
+        if data == "[DONE]" || data == "DONE" {
+            if !completed_sent {
+                flush_and_complete(&tx_event, &mut reasoning_item, &mut assistant_item).await;
+            }
+            return;
+        }
+
+        let value: serde_json::Value = match serde_json::from_str(data) {
            Ok(val) => val,
            Err(err) => {
                debug!(
                    "Failed to parse ChatCompletions SSE event: {err}, data: {}",
-                    &sse.data
+                    data
                );
                continue;
            }
@@ -362,6 +395,16 @@ mod tests {
        body
    }

+    /// Regression test: the stream should complete when we see a `[DONE]` sentinel.
+    ///
+    /// This is important for tests/mocks that don't immediately close the underlying
+    /// connection after emitting the sentinel.
+    #[tokio::test]
+    async fn completes_on_done_sentinel_without_json() {
+        let events = collect_events("event: message\ndata: [DONE]\n\n").await;
+        assert_matches!(&events[..], [ResponseEvent::Completed { .. }]);
+    }
+
    async fn collect_events(body: &str) -> Vec<ResponseEvent> {
        let reader = ReaderStream::new(std::io::Cursor::new(body.to_string()))
            .map_err(|err| codex_client::TransportError::Network(err.to_string()));
@@ -51,11 +51,19 @@ pub fn spawn_response_stream(
    telemetry: Option<Arc<dyn SseTelemetry>>,
 ) -> ResponseStream {
    let rate_limits = parse_rate_limit(&stream_response.headers);
+    let models_etag = stream_response
+        .headers
+        .get("X-Models-Etag")
+        .and_then(|v| v.to_str().ok())
+        .map(ToString::to_string);
    let (tx_event, rx_event) = mpsc::channel::<Result<ResponseEvent, ApiError>>(1600);
    tokio::spawn(async move {
        if let Some(snapshot) = rate_limits {
            let _ = tx_event.send(Ok(ResponseEvent::RateLimits(snapshot))).await;
        }
+        if let Some(etag) = models_etag {
+            let _ = tx_event.send(Ok(ResponseEvent::ModelsEtag(etag))).await;
+        }
        process_sse(stream_response.bytes, tx_event, idle_timeout, telemetry).await;
    });

@@ -86,7 +86,6 @@ async fn models_client_hits_models_endpoint() {
            context_window: None,
            experimental_supported_tools: Vec::new(),
        }],
-        etag: String::new(),
    };

    Mock::given(method("GET"))
@@ -102,13 +101,13 @@ async fn models_client_hits_models_endpoint() {
    let transport = ReqwestTransport::new(reqwest::Client::new());
    let client = ModelsClient::new(transport, provider(&base_url), DummyAuth);

-    let result = client
+    let (models, _) = client
        .list_models("0.1.0", HeaderMap::new())
        .await
        .expect("models request should succeed");

-    assert_eq!(result.models.len(), 1);
-    assert_eq!(result.models[0].slug, "gpt-test");
+    assert_eq!(models.len(), 1);
+    assert_eq!(models[0].slug, "gpt-test");

    let received = server
        .received_requests()
@@ -69,6 +69,15 @@ impl ReqwestTransport {
 #[async_trait]
 impl HttpTransport for ReqwestTransport {
    async fn execute(&self, req: Request) -> Result<Response, TransportError> {
+        if enabled!(Level::TRACE) {
+            trace!(
+                "{} to {}: {}",
+                req.method,
+                req.url,
+                req.body.as_ref().unwrap_or_default()
+            );
+        }
+
        let builder = self.build(req)?;
        let resp = builder.send().await.map_err(Self::map_error)?;
        let status = resp.status();
@@ -88,6 +88,7 @@ use crate::error::Result as CodexResult;
 #[cfg(test)]
 use crate::exec::StreamOutput;
 use crate::exec_policy::ExecPolicyUpdateError;
+use crate::feedback_tags;
 use crate::mcp::auth::compute_auth_statuses;
 use crate::mcp_connection_manager::McpConnectionManager;
 use crate::model_provider_info::CHAT_WIRE_API_DEPRECATION_SUMMARY;
@@ -217,10 +218,11 @@ impl Codex {
        let (tx_sub, rx_sub) = async_channel::bounded(SUBMISSION_CHANNEL_CAPACITY);
        let (tx_event, rx_event) = async_channel::unbounded();

-        let loaded_skills = config
-            .features
-            .enabled(Feature::Skills)
-            .then(|| skills_manager.skills_for_cwd(&config.cwd));
+        let loaded_skills = if config.features.enabled(Feature::Skills) {
+            Some(skills_manager.skills_for_config(&config))
+        } else {
+            None
+        };

        if let Some(outcome) = &loaded_skills {
            for err in &outcome.errors {
@@ -246,7 +248,9 @@ impl Codex {

        let config = Arc::new(config);
        if config.features.enabled(Feature::RemoteModels)
-            && let Err(err) = models_manager.refresh_available_models(&config).await
+            && let Err(err) = models_manager
+                .refresh_available_models_with_cache(&config)
+                .await
        {
            error!("failed to refresh available models: {err:?}");
        }
@@ -808,6 +812,13 @@ impl Session {
                        .await;
                }

+                // Seed usage info from the recorded rollout so UIs can show token counts
+                // immediately on resume/fork.
+                if let Some(info) = Self::last_token_info_from_rollout(&rollout_items) {
+                    let mut state = self.state.lock().await;
+                    state.set_token_info(Some(info));
+                }
+
                // If persisting, persist all rollout items as-is (recorder filters)
                if persist && !rollout_items.is_empty() {
                    self.persist_rollout_items(&rollout_items).await;
@@ -818,6 +829,13 @@ impl Session {
        }
    }

+    fn last_token_info_from_rollout(rollout_items: &[RolloutItem]) -> Option<TokenUsageInfo> {
+        rollout_items.iter().rev().find_map(|item| match item {
+            RolloutItem::EventMsg(EventMsg::TokenCount(ev)) => ev.info.clone(),
+            _ => None,
+        })
+    }
+
    pub(crate) async fn update_settings(
        &self,
        updates: SessionSettingsUpdate,
@@ -1759,7 +1777,16 @@ mod handlers {
                    final_output_json_schema: Some(final_output_json_schema),
                },
            ),
-            Op::UserInput { items } => (items, SessionSettingsUpdate::default()),
+            Op::UserInput {
+                items,
+                final_output_json_schema,
+            } => (
+                items,
+                SessionSettingsUpdate {
+                    final_output_json_schema: Some(final_output_json_schema),
+                    ..Default::default()
+                },
+            ),
            _ => unreachable!(),
        };

@@ -1961,18 +1988,18 @@ mod handlers {
        };
        let skills = if sess.enabled(Feature::Skills) {
            let skills_manager = &sess.services.skills_manager;
-            cwds.into_iter()
-                .map(|cwd| {
-                    let outcome = skills_manager.skills_for_cwd_with_options(&cwd, force_reload);
-                    let errors = super::errors_to_info(&outcome.errors);
-                    let skills = super::skills_to_info(&outcome.skills);
-                    SkillsListEntry {
-                        cwd,
-                        skills,
-                        errors,
-                    }
-                })
-                .collect()
+            let mut entries = Vec::new();
+            for cwd in cwds {
+                let outcome = skills_manager.skills_for_cwd(&cwd, force_reload).await;
+                let errors = super::errors_to_info(&outcome.errors);
+                let skills = super::skills_to_info(&outcome.skills);
+                entries.push(SkillsListEntry {
+                    cwd,
+                    skills,
+                    errors,
+                });
+            }
+            entries
        } else {
            cwds.into_iter()
                .map(|cwd| SkillsListEntry {
@@ -2051,7 +2078,7 @@ mod handlers {
        review_request: ReviewRequest,
    ) {
        let turn_context = sess.new_default_turn_with_sub_id(sub_id.clone()).await;
-        match resolve_review_request(review_request, config.cwd.as_path()) {
+        match resolve_review_request(review_request, turn_context.cwd.as_path()) {
            Ok(resolved) => {
                spawn_review_thread(
                    Arc::clone(sess),
@@ -2226,11 +2253,16 @@ pub(crate) async fn run_task(
    });
    sess.send_event(&turn_context, event).await;

-    let skills_outcome = sess.enabled(Feature::Skills).then(|| {
-        sess.services
-            .skills_manager
-            .skills_for_cwd(&turn_context.cwd)
-    });
+    let skills_outcome = if sess.enabled(Feature::Skills) {
+        Some(
+            sess.services
+                .skills_manager
+                .skills_for_cwd(&turn_context.cwd, false)
+                .await,
+        )
+    } else {
+        None
+    };

    let SkillInjections {
        items: skill_items,
@@ -2523,6 +2555,15 @@ async fn try_run_turn(
        truncation_policy: Some(turn_context.truncation_policy.into()),
    });

+    feedback_tags!(
+        model = turn_context.client.get_model(),
+        approval_policy = turn_context.approval_policy,
+        sandbox_policy = turn_context.sandbox_policy,
+        effort = turn_context.client.get_reasoning_effort(),
+        auth_mode = sess.services.auth_manager.get_auth_mode(),
+        features = sess.features.enabled_features(),
+    );
+
    sess.persist_rollout_items(&[rollout_item]).await;
    let mut stream = turn_context
        .client
@@ -2613,6 +2654,13 @@ async fn try_run_turn(
                // token usage is available to avoid duplicate TokenCount events.
                sess.update_rate_limits(&turn_context, snapshot).await;
            }
+            ResponseEvent::ModelsEtag(etag) => {
+                // Update internal state with latest models etag
+                sess.services
+                    .models_manager
+                    .refresh_if_new_etag(etag, sess.features.enabled(Feature::RemoteModels))
+                    .await;
+            }
            ResponseEvent::Completed {
                response_id: _,
                token_usage,
@@ -2753,6 +2801,9 @@ mod tests {
    use crate::protocol::RateLimitSnapshot;
    use crate::protocol::RateLimitWindow;
    use crate::protocol::ResumedHistory;
+    use crate::protocol::TokenCountEvent;
+    use crate::protocol::TokenUsage;
+    use crate::protocol::TokenUsageInfo;
    use crate::state::TaskKind;
    use crate::tasks::SessionTask;
    use crate::tasks::SessionTaskContext;
@@ -2807,6 +2858,83 @@ mod tests {
        assert_eq!(expected, actual);
    }

+    #[tokio::test]
+    async fn record_initial_history_seeds_token_info_from_rollout() {
+        let (session, turn_context) = make_session_and_context().await;
+        let (mut rollout_items, _expected) = sample_rollout(&session, &turn_context);
+
+        let info1 = TokenUsageInfo {
+            total_token_usage: TokenUsage {
+                input_tokens: 10,
+                cached_input_tokens: 0,
+                output_tokens: 20,
+                reasoning_output_tokens: 0,
+                total_tokens: 30,
+            },
+            last_token_usage: TokenUsage {
+                input_tokens: 3,
+                cached_input_tokens: 0,
+                output_tokens: 4,
+                reasoning_output_tokens: 0,
+                total_tokens: 7,
+            },
+            model_context_window: Some(1_000),
+        };
+        let info2 = TokenUsageInfo {
+            total_token_usage: TokenUsage {
+                input_tokens: 100,
+                cached_input_tokens: 50,
+                output_tokens: 200,
+                reasoning_output_tokens: 25,
+                total_tokens: 375,
+            },
+            last_token_usage: TokenUsage {
+                input_tokens: 10,
+                cached_input_tokens: 0,
+                output_tokens: 20,
+                reasoning_output_tokens: 5,
+                total_tokens: 35,
+            },
+            model_context_window: Some(2_000),
+        };
+
+        rollout_items.push(RolloutItem::EventMsg(EventMsg::TokenCount(
+            TokenCountEvent {
+                info: Some(info1),
+                rate_limits: None,
+            },
+        )));
+        rollout_items.push(RolloutItem::EventMsg(EventMsg::TokenCount(
+            TokenCountEvent {
+                info: None,
+                rate_limits: None,
+            },
+        )));
+        rollout_items.push(RolloutItem::EventMsg(EventMsg::TokenCount(
+            TokenCountEvent {
+                info: Some(info2.clone()),
+                rate_limits: None,
+            },
+        )));
+        rollout_items.push(RolloutItem::EventMsg(EventMsg::TokenCount(
+            TokenCountEvent {
+                info: None,
+                rate_limits: None,
+            },
+        )));
+
+        session
+            .record_initial_history(InitialHistory::Resumed(ResumedHistory {
+                conversation_id: ConversationId::default(),
+                history: rollout_items,
+                rollout_path: PathBuf::from("/tmp/resume.jsonl"),
+            }))
+            .await;
+
+        let actual = session.state.lock().await.token_info();
+        assert_eq!(actual, Some(info2));
+    }
+
    #[tokio::test]
    async fn record_initial_history_reconstructs_forked_transcript() {
        let (session, turn_context) = make_session_and_context().await;
@@ -3140,7 +3268,7 @@ mod tests {
            exec_policy,
            auth_manager: auth_manager.clone(),
            otel_manager: otel_manager.clone(),
-            models_manager,
+            models_manager: Arc::clone(&models_manager),
            tool_approvals: Mutex::new(ApprovalStore::default()),
            skills_manager,
        };
@@ -3227,7 +3355,7 @@ mod tests {
            exec_policy,
            auth_manager: Arc::clone(&auth_manager),
            otel_manager: otel_manager.clone(),
-            models_manager,
+            models_manager: Arc::clone(&models_manager),
            tool_approvals: Mutex::new(ApprovalStore::default()),
            skills_manager,
        };
@@ -118,7 +118,11 @@ pub(crate) async fn run_codex_conversation_one_shot(
    .await?;

    // Send the initial input to kick off the one-shot turn.
-    io.submit(Op::UserInput { items: input }).await?;
+    io.submit(Op::UserInput {
+        items: input,
+        final_output_json_schema: None,
+    })
+    .await?;

    // Bridge events so we can observe completion and shut down automatically.
    let (tx_bridge, rx_bridge) = async_channel::bounded(SUBMISSION_CHANNEL_CAPACITY);
@@ -184,6 +188,10 @@ async fn forward_events(
                        id: _,
                        msg: EventMsg::AgentMessageDelta(_) | EventMsg::AgentReasoningDelta(_),
                    } => {}
+                    Event {
+                        id: _,
+                        msg: EventMsg::TokenCount(_),
+                    } => {}
                    Event {
                        id: _,
                        msg: EventMsg::SessionConfigured(_),
@@ -2050,6 +2050,7 @@ trust_level = "trusted"
            managed_config_path: Some(managed_path.clone()),
            #[cfg(target_os = "macos")]
            managed_preferences_base64: None,
+            macos_managed_config_requirements_base64: None,
        };

        let cwd = AbsolutePathBuf::try_from(codex_home.path())?;
@@ -2170,6 +2171,7 @@ trust_level = "trusted"
            managed_config_path: Some(managed_path),
            #[cfg(target_os = "macos")]
            managed_preferences_base64: None,
+            macos_managed_config_requirements_base64: None,
        };

        let cwd = AbsolutePathBuf::try_from(codex_home.path())?;
@@ -755,6 +755,7 @@ remote_compaction = true
                managed_config_path: Some(managed_path.clone()),
                #[cfg(target_os = "macos")]
                managed_preferences_base64: None,
+                macos_managed_config_requirements_base64: None,
            },
        );

@@ -835,6 +836,7 @@ remote_compaction = true
                managed_config_path: Some(managed_path.clone()),
                #[cfg(target_os = "macos")]
                managed_preferences_base64: None,
+                macos_managed_config_requirements_base64: None,
            },
        );

@@ -937,6 +939,7 @@ remote_compaction = true
                managed_config_path: Some(managed_path.clone()),
                #[cfg(target_os = "macos")]
                managed_preferences_base64: None,
+                macos_managed_config_requirements_base64: None,
            },
        );

@@ -984,6 +987,7 @@ remote_compaction = true
                managed_config_path: Some(managed_path.clone()),
                #[cfg(target_os = "macos")]
                managed_preferences_base64: None,
+                macos_managed_config_requirements_base64: None,
            },
        );

@@ -1029,6 +1033,7 @@ remote_compaction = true
                managed_config_path: Some(managed_path.clone()),
                #[cfg(target_os = "macos")]
                managed_preferences_base64: None,
+                macos_managed_config_requirements_base64: None,
            },
        );

@@ -33,11 +33,13 @@ pub(super) async fn load_config_layers_internal(
    let LoaderOverrides {
        managed_config_path,
        managed_preferences_base64,
+        ..
    } = overrides;

    #[cfg(not(target_os = "macos"))]
    let LoaderOverrides {
        managed_config_path,
+        ..
    } = overrides;

    let managed_config_path = AbsolutePathBuf::from_absolute_path(
@@ -1,3 +1,4 @@
+use super::config_requirements::ConfigRequirementsToml;
 use base64::Engine;
 use base64::prelude::BASE64_STANDARD;
 use core_foundation::base::TCFType;
@@ -10,6 +11,7 @@ use toml::Value as TomlValue;

 const MANAGED_PREFERENCES_APPLICATION_ID: &str = "com.openai.codex";
 const MANAGED_PREFERENCES_CONFIG_KEY: &str = "config_toml_base64";
+const MANAGED_PREFERENCES_REQUIREMENTS_KEY: &str = "requirements_toml_base64";

 pub(crate) async fn load_managed_admin_config_layer(
    override_base64: Option<&str>,
@@ -19,82 +21,126 @@ pub(crate) async fn load_managed_admin_config_layer(
        return if trimmed.is_empty() {
            Ok(None)
        } else {
-            parse_managed_preferences_base64(trimmed).map(Some)
+            parse_managed_config_base64(trimmed).map(Some)
        };
    }

-    const LOAD_ERROR: &str = "Failed to load managed preferences configuration";
-
    match task::spawn_blocking(load_managed_admin_config).await {
        Ok(result) => result,
        Err(join_err) => {
            if join_err.is_cancelled() {
-                tracing::error!("Managed preferences load task was cancelled");
+                tracing::error!("Managed config load task was cancelled");
            } else {
-                tracing::error!("Managed preferences load task failed: {join_err}");
+                tracing::error!("Managed config load task failed: {join_err}");
            }
-            Err(io::Error::other(LOAD_ERROR))
+            Err(io::Error::other("Failed to load managed config"))
        }
    }
 }

 fn load_managed_admin_config() -> io::Result<Option<TomlValue>> {
+    load_managed_preference(MANAGED_PREFERENCES_CONFIG_KEY)?
+        .as_deref()
+        .map(str::trim)
+        .map(parse_managed_config_base64)
+        .transpose()
+}
+
+pub(crate) async fn load_managed_admin_requirements_toml(
+    target: &mut ConfigRequirementsToml,
+    override_base64: Option<&str>,
+) -> io::Result<()> {
+    if let Some(encoded) = override_base64 {
+        let trimmed = encoded.trim();
+        if !trimmed.is_empty() {
+            target.merge_unset_fields(parse_managed_requirements_base64(trimmed)?);
+        }
+        return Ok(());
+    }
+
+    match task::spawn_blocking(load_managed_admin_requirements).await {
+        Ok(result) => {
+            if let Some(requirements) = result? {
+                target.merge_unset_fields(requirements);
+            }
+            Ok(())
+        }
+        Err(join_err) => {
+            if join_err.is_cancelled() {
+                tracing::error!("Managed requirements load task was cancelled");
+            } else {
+                tracing::error!("Managed requirements load task failed: {join_err}");
+            }
+            Err(io::Error::other("Failed to load managed requirements"))
+        }
+    }
+}
+
+fn load_managed_admin_requirements() -> io::Result<Option<ConfigRequirementsToml>> {
+    load_managed_preference(MANAGED_PREFERENCES_REQUIREMENTS_KEY)?
+        .as_deref()
+        .map(str::trim)
+        .map(parse_managed_requirements_base64)
+        .transpose()
+}
+
+fn load_managed_preference(key_name: &str) -> io::Result<Option<String>> {
    #[link(name = "CoreFoundation", kind = "framework")]
    unsafe extern "C" {
        fn CFPreferencesCopyAppValue(key: CFStringRef, application_id: CFStringRef) -> *mut c_void;
    }

-    let application_id = CFString::new(MANAGED_PREFERENCES_APPLICATION_ID);
-    let key = CFString::new(MANAGED_PREFERENCES_CONFIG_KEY);
-
    let value_ref = unsafe {
        CFPreferencesCopyAppValue(
-            key.as_concrete_TypeRef(),
-            application_id.as_concrete_TypeRef(),
+            CFString::new(key_name).as_concrete_TypeRef(),
+            CFString::new(MANAGED_PREFERENCES_APPLICATION_ID).as_concrete_TypeRef(),
        )
    };

    if value_ref.is_null() {
        tracing::debug!(
-            "Managed preferences for {} key {} not found",
-            MANAGED_PREFERENCES_APPLICATION_ID,
-            MANAGED_PREFERENCES_CONFIG_KEY
+            "Managed preferences for {MANAGED_PREFERENCES_APPLICATION_ID} key {key_name} not found",
        );
        return Ok(None);
    }

-    let value = unsafe { CFString::wrap_under_create_rule(value_ref as _) };
-    let contents = value.to_string();
-    let trimmed = contents.trim();
-
-    parse_managed_preferences_base64(trimmed).map(Some)
+    let value = unsafe { CFString::wrap_under_create_rule(value_ref as _) }.to_string();
+    Ok(Some(value))
 }

-fn parse_managed_preferences_base64(encoded: &str) -> io::Result<TomlValue> {
-    let decoded = BASE64_STANDARD.decode(encoded.as_bytes()).map_err(|err| {
-        tracing::error!("Failed to decode managed preferences as base64: {err}");
-        io::Error::new(io::ErrorKind::InvalidData, err)
-    })?;
-
-    let decoded_str = String::from_utf8(decoded).map_err(|err| {
-        tracing::error!("Managed preferences base64 contents were not valid UTF-8: {err}");
-        io::Error::new(io::ErrorKind::InvalidData, err)
-    })?;
-
-    match toml::from_str::<TomlValue>(&decoded_str) {
+fn parse_managed_config_base64(encoded: &str) -> io::Result<TomlValue> {
+    match toml::from_str::<TomlValue>(&decode_managed_preferences_base64(encoded)?) {
        Ok(TomlValue::Table(parsed)) => Ok(TomlValue::Table(parsed)),
        Ok(other) => {
-            tracing::error!(
-                "Managed preferences TOML must have a table at the root, found {other:?}",
-            );
+            tracing::error!("Managed config TOML must have a table at the root, found {other:?}",);
            Err(io::Error::new(
                io::ErrorKind::InvalidData,
-                "managed preferences root must be a table",
+                "managed config root must be a table",
            ))
        }
        Err(err) => {
-            tracing::error!("Failed to parse managed preferences TOML: {err}");
+            tracing::error!("Failed to parse managed config TOML: {err}");
            Err(io::Error::new(io::ErrorKind::InvalidData, err))
        }
    }
 }
+
+fn parse_managed_requirements_base64(encoded: &str) -> io::Result<ConfigRequirementsToml> {
+    toml::from_str::<ConfigRequirementsToml>(&decode_managed_preferences_base64(encoded)?).map_err(
+        |err| {
+            tracing::error!("Failed to parse managed requirements TOML: {err}");
+            io::Error::new(io::ErrorKind::InvalidData, err)
+        },
+    )
+}
+
+fn decode_managed_preferences_base64(encoded: &str) -> io::Result<String> {
+    String::from_utf8(BASE64_STANDARD.decode(encoded.as_bytes()).map_err(|err| {
+        tracing::error!("Failed to decode managed value as base64: {err}",);
+        io::Error::new(io::ErrorKind::InvalidData, err)
+    })?)
+    .map_err(|err| {
+        tracing::error!("Managed value base64 contents were not valid UTF-8: {err}",);
+        io::Error::new(io::ErrorKind::InvalidData, err)
+    })
+}
@@ -78,8 +78,14 @@ pub async fn load_config_layers_state(
 ) -> io::Result<ConfigLayerStack> {
    let mut config_requirements_toml = ConfigRequirementsToml::default();

-    // TODO(gt): Support an entry in MDM for config requirements and use it
-    // with `config_requirements_toml.merge_unset_fields(...)`, if present.
+    #[cfg(target_os = "macos")]
+    macos::load_managed_admin_requirements_toml(
+        &mut config_requirements_toml,
+        overrides
+            .macos_managed_config_requirements_base64
+            .as_deref(),
+    )
+    .await?;

    // Honor /etc/codex/requirements.toml.
    if cfg!(unix) {
@@ -101,8 +107,6 @@ pub async fn load_config_layers_state(

    let mut layers = Vec::<ConfigLayerEntry>::new();

-    // TODO(gt): Honor managed preferences (macOS only).
-
    // Include an entry for the "system" config folder, loading its config.toml,
    // if it exists.
    let system_config_toml_file = if cfg!(unix) {
@@ -12,11 +12,14 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 use toml::Value as TomlValue;

+/// LoaderOverrides overrides managed configuration inputs (primarily for tests).
 #[derive(Debug, Default, Clone)]
 pub struct LoaderOverrides {
    pub managed_config_path: Option<PathBuf>,
+    //TODO(gt): Add a macos_ prefix to this field and remove the target_os check.
    #[cfg(target_os = "macos")]
    pub managed_preferences_base64: Option<String>,
+    pub macos_managed_config_requirements_base64: Option<String>,
 }

 #[derive(Debug, Clone, PartialEq)]
@@ -9,6 +9,8 @@ use crate::config_loader::config_requirements::ConfigRequirementsToml;
 use crate::config_loader::fingerprint::version_for_toml;
 use crate::config_loader::load_requirements_toml;
 use codex_protocol::protocol::AskForApproval;
+#[cfg(target_os = "macos")]
+use codex_protocol::protocol::SandboxPolicy;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use pretty_assertions::assert_eq;
 use tempfile::tempdir;
@@ -43,6 +45,7 @@ extra = true
        managed_config_path: Some(managed_path),
        #[cfg(target_os = "macos")]
        managed_preferences_base64: None,
+        macos_managed_config_requirements_base64: None,
    };

    let cwd = AbsolutePathBuf::try_from(tmp.path()).expect("cwd");
@@ -73,10 +76,12 @@ extra = true
 async fn returns_empty_when_all_layers_missing() {
    let tmp = tempdir().expect("tempdir");
    let managed_path = tmp.path().join("managed_config.toml");
+
    let overrides = LoaderOverrides {
        managed_config_path: Some(managed_path),
        #[cfg(target_os = "macos")]
        managed_preferences_base64: None,
+        macos_managed_config_requirements_base64: None,
    };

    let cwd = AbsolutePathBuf::try_from(tmp.path()).expect("cwd");
@@ -141,12 +146,6 @@ async fn returns_empty_when_all_layers_missing() {
 async fn managed_preferences_take_highest_precedence() {
    use base64::Engine;

-    let managed_payload = r#"
-[nested]
-value = "managed"
-flag = false
-"#;
-    let encoded = base64::prelude::BASE64_STANDARD.encode(managed_payload.as_bytes());
    let tmp = tempdir().expect("tempdir");
    let managed_path = tmp.path().join("managed_config.toml");

@@ -168,7 +167,17 @@ flag = true

    let overrides = LoaderOverrides {
        managed_config_path: Some(managed_path),
-        managed_preferences_base64: Some(encoded),
+        managed_preferences_base64: Some(
+            base64::prelude::BASE64_STANDARD.encode(
+                r#"
+[nested]
+value = "managed"
+flag = false
+"#
+                .as_bytes(),
+            ),
+        ),
+        macos_managed_config_requirements_base64: None,
    };

    let cwd = AbsolutePathBuf::try_from(tmp.path()).expect("cwd");
@@ -192,6 +201,108 @@ flag = true
    assert_eq!(nested.get("flag"), Some(&TomlValue::Boolean(false)));
 }

+#[cfg(target_os = "macos")]
+#[tokio::test]
+async fn managed_preferences_requirements_are_applied() -> anyhow::Result<()> {
+    use base64::Engine;
+
+    let tmp = tempdir()?;
+
+    let state = load_config_layers_state(
+        tmp.path(),
+        Some(AbsolutePathBuf::try_from(tmp.path())?),
+        &[] as &[(String, TomlValue)],
+        LoaderOverrides {
+            managed_config_path: Some(tmp.path().join("managed_config.toml")),
+            managed_preferences_base64: Some(String::new()),
+            macos_managed_config_requirements_base64: Some(
+                base64::prelude::BASE64_STANDARD.encode(
+                    r#"
+allowed_approval_policies = ["never"]
+allowed_sandbox_modes = ["read-only"]
+"#
+                    .as_bytes(),
+                ),
+            ),
+        },
+    )
+    .await?;
+
+    assert_eq!(
+        state.requirements().approval_policy.value(),
+        AskForApproval::Never
+    );
+    assert_eq!(
+        *state.requirements().sandbox_policy.get(),
+        SandboxPolicy::ReadOnly
+    );
+    assert!(
+        state
+            .requirements()
+            .approval_policy
+            .can_set(&AskForApproval::OnRequest)
+            .is_err()
+    );
+    assert!(
+        state
+            .requirements()
+            .sandbox_policy
+            .can_set(&SandboxPolicy::WorkspaceWrite {
+                writable_roots: Vec::new(),
+                network_access: false,
+                exclude_tmpdir_env_var: false,
+                exclude_slash_tmp: false,
+            })
+            .is_err()
+    );
+
+    Ok(())
+}
+
+#[cfg(target_os = "macos")]
+#[tokio::test]
+async fn managed_preferences_requirements_take_precedence() -> anyhow::Result<()> {
+    use base64::Engine;
+
+    let tmp = tempdir()?;
+    let managed_path = tmp.path().join("managed_config.toml");
+
+    tokio::fs::write(&managed_path, "approval_policy = \"on-request\"\n").await?;
+
+    let state = load_config_layers_state(
+        tmp.path(),
+        Some(AbsolutePathBuf::try_from(tmp.path())?),
+        &[] as &[(String, TomlValue)],
+        LoaderOverrides {
+            managed_config_path: Some(managed_path),
+            managed_preferences_base64: Some(String::new()),
+            macos_managed_config_requirements_base64: Some(
+                base64::prelude::BASE64_STANDARD.encode(
+                    r#"
+allowed_approval_policies = ["never"]
+"#
+                    .as_bytes(),
+                ),
+            ),
+        },
+    )
+    .await?;
+
+    assert_eq!(
+        state.requirements().approval_policy.value(),
+        AskForApproval::Never
+    );
+    assert!(
+        state
+            .requirements()
+            .approval_policy
+            .can_set(&AskForApproval::OnRequest)
+            .is_err()
+    );
+
+    Ok(())
+}
+
 #[tokio::test(flavor = "current_thread")]
 async fn load_requirements_toml_produces_expected_constraints() -> anyhow::Result<()> {
    let tmp = tempdir()?;
@@ -28,11 +28,10 @@ use crate::features::Feature;
 use crate::features::Features;
 use crate::sandboxing::SandboxPermissions;
 use crate::tools::sandboxing::ExecApprovalRequirement;
+use shlex::try_join as shlex_try_join;

-const FORBIDDEN_REASON: &str = "execpolicy forbids this command";
 const PROMPT_CONFLICT_REASON: &str =
-    "execpolicy requires approval for this command, but AskForApproval is set to Never";
-const PROMPT_REASON: &str = "execpolicy requires approval for this command";
+    "approval required by policy, but AskForApproval is set to Never";
 const RULES_DIR_NAME: &str = "rules";
 const RULE_EXTENSION: &str = "rules";
 const DEFAULT_POLICY_FILE: &str = "default.rules";
@@ -128,7 +127,7 @@ impl ExecPolicyManager {

        match evaluation.decision {
            Decision::Forbidden => ExecApprovalRequirement::Forbidden {
-                reason: FORBIDDEN_REASON.to_string(),
+                reason: derive_forbidden_reason(command, &evaluation),
            },
            Decision::Prompt => {
                if matches!(approval_policy, AskForApproval::Never) {
@@ -137,7 +136,7 @@ impl ExecPolicyManager {
                    }
                } else {
                    ExecApprovalRequirement::NeedsApproval {
-                        reason: derive_prompt_reason(&evaluation),
+                        reason: derive_prompt_reason(command, &evaluation),
                        proposed_execpolicy_amendment: if features.enabled(Feature::ExecPolicy) {
                            try_derive_execpolicy_amendment_for_prompt_rules(
                                &evaluation.matched_rules,
@@ -299,15 +298,69 @@ fn try_derive_execpolicy_amendment_for_allow_rules(
        })
 }

-/// Only return PROMPT_REASON when an execpolicy rule drove the prompt decision.
-fn derive_prompt_reason(evaluation: &Evaluation) -> Option<String> {
-    evaluation.matched_rules.iter().find_map(|rule_match| {
-        if is_policy_match(rule_match) && rule_match.decision() == Decision::Prompt {
-            Some(PROMPT_REASON.to_string())
-        } else {
-            None
+/// Only return a reason when a policy rule drove the prompt decision.
+fn derive_prompt_reason(command_args: &[String], evaluation: &Evaluation) -> Option<String> {
+    let command = render_shlex_command(command_args);
+
+    let most_specific_prompt = evaluation
+        .matched_rules
+        .iter()
+        .filter_map(|rule_match| match rule_match {
+            RuleMatch::PrefixRuleMatch {
+                matched_prefix,
+                decision: Decision::Prompt,
+                justification,
+                ..
+            } => Some((matched_prefix.len(), justification.as_deref())),
+            _ => None,
+        })
+        .max_by_key(|(matched_prefix_len, _)| *matched_prefix_len);
+
+    match most_specific_prompt {
+        Some((_matched_prefix_len, Some(justification))) => {
+            Some(format!("`{command}` requires approval: {justification}"))
        }
-    })
+        Some((_matched_prefix_len, None)) => {
+            Some(format!("`{command}` requires approval by policy"))
+        }
+        None => None,
+    }
+}
+
+fn render_shlex_command(args: &[String]) -> String {
+    shlex_try_join(args.iter().map(String::as_str)).unwrap_or_else(|_| args.join(" "))
+}
+
+/// Derive a string explaining why the command was forbidden. If `justification`
+/// is set by the user, this can contain instructions with recommended
+/// alternatives, for example.
+fn derive_forbidden_reason(command_args: &[String], evaluation: &Evaluation) -> String {
+    let command = render_shlex_command(command_args);
+
+    let most_specific_forbidden = evaluation
+        .matched_rules
+        .iter()
+        .filter_map(|rule_match| match rule_match {
+            RuleMatch::PrefixRuleMatch {
+                matched_prefix,
+                decision: Decision::Forbidden,
+                justification,
+                ..
+            } => Some((matched_prefix, justification.as_deref())),
+            _ => None,
+        })
+        .max_by_key(|(matched_prefix, _)| matched_prefix.len());
+
+    match most_specific_forbidden {
+        Some((_matched_prefix, Some(justification))) => {
+            format!("`{command}` rejected: {justification}")
+        }
+        Some((matched_prefix, None)) => {
+            let prefix = render_shlex_command(matched_prefix);
+            format!("`{command}` rejected: policy forbids commands starting with `{prefix}`")
+        }
+        None => format!("`{command}` rejected: blocked by policy"),
+    }
 }

 async fn collect_policy_files(dir: impl AsRef<Path>) -> Result<Vec<PathBuf>, ExecPolicyError> {
@@ -450,7 +503,8 @@ mod tests {
                decision: Decision::Forbidden,
                matched_rules: vec![RuleMatch::PrefixRuleMatch {
                    matched_prefix: vec!["rm".to_string()],
-                    decision: Decision::Forbidden
+                    decision: Decision::Forbidden,
+                    justification: None,
                }],
            },
            policy.check_multiple(command.iter(), &|_| Decision::Allow)
@@ -528,7 +582,8 @@ mod tests {
                decision: Decision::Forbidden,
                matched_rules: vec![RuleMatch::PrefixRuleMatch {
                    matched_prefix: vec!["rm".to_string()],
-                    decision: Decision::Forbidden
+                    decision: Decision::Forbidden,
+                    justification: None,
                }],
            },
            policy.check_multiple([vec!["rm".to_string()]].iter(), &|_| Decision::Allow)
@@ -538,7 +593,8 @@ mod tests {
                decision: Decision::Prompt,
                matched_rules: vec![RuleMatch::PrefixRuleMatch {
                    matched_prefix: vec!["ls".to_string()],
-                    decision: Decision::Prompt
+                    decision: Decision::Prompt,
+                    justification: None,
                }],
            },
            policy.check_multiple([vec!["ls".to_string()]].iter(), &|_| Decision::Allow)
@@ -560,7 +616,7 @@ prefix_rule(pattern=["rm"], decision="forbidden")
        let forbidden_script = vec![
            "bash".to_string(),
            "-lc".to_string(),
-            "rm -rf /tmp".to_string(),
+            "rm -rf /some/important/folder".to_string(),
        ];

        let manager = ExecPolicyManager::new(policy);
@@ -577,7 +633,45 @@ prefix_rule(pattern=["rm"], decision="forbidden")
        assert_eq!(
            requirement,
            ExecApprovalRequirement::Forbidden {
-                reason: FORBIDDEN_REASON.to_string()
+                reason: "`bash -lc 'rm -rf /some/important/folder'` rejected: policy forbids commands starting with `rm`".to_string()
+            }
+        );
+    }
+
+    #[tokio::test]
+    async fn justification_is_included_in_forbidden_exec_approval_requirement() {
+        let policy_src = r#"
+prefix_rule(
+    pattern=["rm"],
+    decision="forbidden",
+    justification="destructive command",
+)
+"#;
+        let mut parser = PolicyParser::new();
+        parser
+            .parse("test.rules", policy_src)
+            .expect("parse policy");
+        let policy = Arc::new(parser.build());
+
+        let manager = ExecPolicyManager::new(policy);
+        let requirement = manager
+            .create_exec_approval_requirement_for_command(
+                &Features::with_defaults(),
+                &[
+                    "rm".to_string(),
+                    "-rf".to_string(),
+                    "/some/important/folder".to_string(),
+                ],
+                AskForApproval::OnRequest,
+                &SandboxPolicy::DangerFullAccess,
+                SandboxPermissions::UseDefault,
+            )
+            .await;
+
+        assert_eq!(
+            requirement,
+            ExecApprovalRequirement::Forbidden {
+                reason: "`rm -rf /some/important/folder` rejected: destructive command".to_string()
            }
        );
    }
@@ -606,7 +700,7 @@ prefix_rule(pattern=["rm"], decision="forbidden")
        assert_eq!(
            requirement,
            ExecApprovalRequirement::NeedsApproval {
-                reason: Some(PROMPT_REASON.to_string()),
+                reason: Some("`rm` requires approval by policy".to_string()),
                proposed_execpolicy_amendment: None,
            }
        );
@@ -824,7 +918,7 @@ prefix_rule(pattern=["rm"], decision="forbidden")
        assert_eq!(
            requirement,
            ExecApprovalRequirement::NeedsApproval {
-                reason: Some(PROMPT_REASON.to_string()),
+                reason: Some("`rm` requires approval by policy".to_string()),
                proposed_execpolicy_amendment: None,
            }
        );
@@ -255,6 +255,10 @@ impl Features {

        features
    }
+
+    pub fn enabled_features(&self) -> Vec<Feature> {
+        self.enabled.iter().copied().collect()
+    }
 }

 /// Keys accepted in `[features]` tables.
@@ -79,26 +79,60 @@ pub const DEFAULT_STARTUP_TIMEOUT: Duration = Duration::from_secs(10);
 /// Default timeout for individual tool calls.
 const DEFAULT_TOOL_TIMEOUT: Duration = Duration::from_secs(60);

+/// The Responses API requires tool names to match `^[a-zA-Z0-9_-]+$`.
+/// MCP server/tool names are user-controlled, so sanitize the fully-qualified
+/// name we expose to the model by replacing any disallowed character with `_`.
+fn sanitize_responses_api_tool_name(name: &str) -> String {
+    let mut sanitized = String::with_capacity(name.len());
+    for c in name.chars() {
+        if c.is_ascii_alphanumeric() || c == '_' || c == '-' {
+            sanitized.push(c);
+        } else {
+            sanitized.push('_');
+        }
+    }
+
+    if sanitized.is_empty() {
+        "_".to_string()
+    } else {
+        sanitized
+    }
+}
+
+fn sha1_hex(s: &str) -> String {
+    let mut hasher = Sha1::new();
+    hasher.update(s.as_bytes());
+    let sha1 = hasher.finalize();
+    format!("{sha1:x}")
+}
+
 fn qualify_tools<I>(tools: I) -> HashMap<String, ToolInfo>
 where
    I: IntoIterator<Item = ToolInfo>,
 {
    let mut used_names = HashSet::new();
+    let mut seen_raw_names = HashSet::new();
    let mut qualified_tools = HashMap::new();
    for tool in tools {
-        let mut qualified_name = format!(
+        let qualified_name_raw = format!(
            "mcp{}{}{}{}",
            MCP_TOOL_NAME_DELIMITER, tool.server_name, MCP_TOOL_NAME_DELIMITER, tool.tool_name
        );
+        if !seen_raw_names.insert(qualified_name_raw.clone()) {
+            warn!("skipping duplicated tool {}", qualified_name_raw);
+            continue;
+        }
+
+        // Start from a "pretty" name (sanitized), then deterministically disambiguate on
+        // collisions by appending a hash of the *raw* (unsanitized) qualified name. This
+        // ensures tools like `foo.bar` and `foo_bar` don't collapse to the same key.
+        let mut qualified_name = sanitize_responses_api_tool_name(&qualified_name_raw);
+
+        // Enforce length constraints early; use the raw name for the hash input so the
+        // output remains stable even when sanitization changes.
        if qualified_name.len() > MAX_TOOL_NAME_LENGTH {
-            let mut hasher = Sha1::new();
-            hasher.update(qualified_name.as_bytes());
-            let sha1 = hasher.finalize();
-            let sha1_str = format!("{sha1:x}");
-
-            // Truncate to make room for the hash suffix
+            let sha1_str = sha1_hex(&qualified_name_raw);
            let prefix_len = MAX_TOOL_NAME_LENGTH - sha1_str.len();
-
            qualified_name = format!("{}{}", &qualified_name[..prefix_len], sha1_str);
        }

@@ -1035,6 +1069,28 @@ mod tests {
        );
    }

+    #[test]
+    fn test_qualify_tools_sanitizes_invalid_characters() {
+        let tools = vec![create_test_tool("server.one", "tool.two")];
+
+        let qualified_tools = qualify_tools(tools);
+
+        assert_eq!(qualified_tools.len(), 1);
+        let (qualified_name, tool) = qualified_tools.into_iter().next().expect("one tool");
+        assert_eq!(qualified_name, "mcp__server_one__tool_two");
+
+        // The key is sanitized for OpenAI, but we keep original parts for the actual MCP call.
+        assert_eq!(tool.server_name, "server.one");
+        assert_eq!(tool.tool_name, "tool.two");
+
+        assert!(
+            qualified_name
+                .chars()
+                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-'),
+            "qualified name must be Responses API compatible: {qualified_name:?}"
+        );
+    }
+
    #[test]
    fn tool_filter_allows_by_default() {
        let filter = ToolFilter::default();
@@ -77,7 +77,7 @@ impl ModelsManager {
    }

    /// Fetch the latest remote models, using the on-disk cache when still fresh.
-    pub async fn refresh_available_models(&self, config: &Config) -> CoreResult<()> {
+    pub async fn refresh_available_models_with_cache(&self, config: &Config) -> CoreResult<()> {
        if !config.features.enabled(Feature::RemoteModels)
            || self.auth_manager.get_auth_mode() == Some(AuthMode::ApiKey)
        {
@@ -86,7 +86,17 @@ impl ModelsManager {
        if self.try_load_cache().await {
            return Ok(());
        }
+        self.refresh_available_models_no_cache(config.features.enabled(Feature::RemoteModels))
+            .await
+    }

+    pub(crate) async fn refresh_available_models_no_cache(
+        &self,
+        remote_models_feature: bool,
+    ) -> CoreResult<()> {
+        if !remote_models_feature || self.auth_manager.get_auth_mode() == Some(AuthMode::ApiKey) {
+            return Ok(());
+        }
        let auth = self.auth_manager.auth();
        let api_provider = self.provider.to_api_provider(Some(AuthMode::ChatGPT))?;
        let api_auth = auth_provider_from_auth(auth.clone(), &self.provider).await?;
@@ -94,13 +104,11 @@ impl ModelsManager {
        let client = ModelsClient::new(transport, api_provider, api_auth);

        let client_version = format_client_version_to_whole();
-        let ModelsResponse { models, etag } = client
+        let (models, etag) = client
            .list_models(&client_version, HeaderMap::new())
            .await
            .map_err(map_api_error)?;

-        let etag = (!etag.is_empty()).then_some(etag);
-
        self.apply_remote_models(models.clone()).await;
        *self.etag.write().await = etag.clone();
        self.persist_cache(&models, etag).await;
@@ -108,7 +116,7 @@ impl ModelsManager {
    }

    pub async fn list_models(&self, config: &Config) -> Vec<ModelPreset> {
-        if let Err(err) = self.refresh_available_models(config).await {
+        if let Err(err) = self.refresh_available_models_with_cache(config).await {
            error!("failed to refresh available models: {err}");
        }
        let remote_models = self.remote_models(config).await;
@@ -135,7 +143,7 @@ impl ModelsManager {
        if let Some(model) = model.as_ref() {
            return model.to_string();
        }
-        if let Err(err) = self.refresh_available_models(config).await {
+        if let Err(err) = self.refresh_available_models_with_cache(config).await {
            error!("failed to refresh available models: {err}");
        }
        // if codex-auto-balanced exists & signed in with chatgpt mode, return it, otherwise return the default model
@@ -153,6 +161,18 @@ impl ModelsManager {
        }
        OPENAI_DEFAULT_API_MODEL.to_string()
    }
+    pub async fn refresh_if_new_etag(&self, etag: String, remote_models_feature: bool) {
+        let current_etag = self.get_etag().await;
+        if current_etag.clone().is_some() && current_etag.as_deref() == Some(etag.as_str()) {
+            return;
+        }
+        if let Err(err) = self
+            .refresh_available_models_no_cache(remote_models_feature)
+            .await
+        {
+            error!("failed to refresh available models: {err}");
+        }
+    }

    #[cfg(any(test, feature = "test-support"))]
    pub fn get_model_offline(model: Option<&str>) -> String {
@@ -165,6 +185,10 @@ impl ModelsManager {
        Self::find_family_for_model(model).with_config_overrides(config)
    }

+    async fn get_etag(&self) -> Option<String> {
+        self.etag.read().await.clone()
+    }
+
    /// Replace the cached remote models and rebuild the derived presets list.
    async fn apply_remote_models(&self, models: Vec<ModelInfo>) {
        *self.remote_models.write().await = models;
@@ -288,26 +312,14 @@ impl ModelsManager {

 /// Convert a client version string to a whole version string (e.g. "1.2.3-alpha.4" -> "1.2.3")
 fn format_client_version_to_whole() -> String {
-    format_client_version_from_parts(
+    format!(
+        "{}.{}.{}",
        env!("CARGO_PKG_VERSION_MAJOR"),
        env!("CARGO_PKG_VERSION_MINOR"),
-        env!("CARGO_PKG_VERSION_PATCH"),
+        env!("CARGO_PKG_VERSION_PATCH")
    )
 }

-fn format_client_version_from_parts(major: &str, minor: &str, patch: &str) -> String {
-    const DEV_VERSION: &str = "0.0.0";
-    const FALLBACK_VERSION: &str = "99.99.99";
-
-    let normalized = format!("{major}.{minor}.{patch}");
-
-    if normalized == DEV_VERSION {
-        FALLBACK_VERSION.to_string()
-    } else {
-        normalized
-    }
-}
-
 #[cfg(test)]
 mod tests {
    use super::cache::ModelsCache;
@@ -388,7 +400,6 @@ mod tests {
            &server,
            ModelsResponse {
                models: remote_models.clone(),
-                etag: String::new(),
            },
        )
        .await;
@@ -406,7 +417,7 @@ mod tests {
        let manager = ModelsManager::with_provider(auth_manager, provider);

        manager
-            .refresh_available_models(&config)
+            .refresh_available_models_with_cache(&config)
            .await
            .expect("refresh succeeds");
        let cached_remote = manager.remote_models(&config).await;
@@ -445,7 +456,6 @@ mod tests {
            &server,
            ModelsResponse {
                models: remote_models.clone(),
-                etag: String::new(),
            },
        )
        .await;
@@ -466,7 +476,7 @@ mod tests {
        let manager = ModelsManager::with_provider(auth_manager, provider);

        manager
-            .refresh_available_models(&config)
+            .refresh_available_models_with_cache(&config)
            .await
            .expect("first refresh succeeds");
        assert_eq!(
@@ -477,7 +487,7 @@ mod tests {

        // Second call should read from cache and avoid the network.
        manager
-            .refresh_available_models(&config)
+            .refresh_available_models_with_cache(&config)
            .await
            .expect("cached refresh succeeds");
        assert_eq!(
@@ -500,7 +510,6 @@ mod tests {
            &server,
            ModelsResponse {
                models: initial_models.clone(),
-                etag: String::new(),
            },
        )
        .await;
@@ -521,7 +530,7 @@ mod tests {
        let manager = ModelsManager::with_provider(auth_manager, provider);

        manager
-            .refresh_available_models(&config)
+            .refresh_available_models_with_cache(&config)
            .await
            .expect("initial refresh succeeds");

@@ -541,13 +550,12 @@ mod tests {
            &server,
            ModelsResponse {
                models: updated_models.clone(),
-                etag: String::new(),
            },
        )
        .await;

        manager
-            .refresh_available_models(&config)
+            .refresh_available_models_with_cache(&config)
            .await
            .expect("second refresh succeeds");
        assert_eq!(
@@ -575,7 +583,6 @@ mod tests {
            &server,
            ModelsResponse {
                models: initial_models,
-                etag: String::new(),
            },
        )
        .await;
@@ -594,7 +601,7 @@ mod tests {
        manager.cache_ttl = Duration::ZERO;

        manager
-            .refresh_available_models(&config)
+            .refresh_available_models_with_cache(&config)
            .await
            .expect("initial refresh succeeds");

@@ -604,13 +611,12 @@ mod tests {
            &server,
            ModelsResponse {
                models: refreshed_models,
-                etag: String::new(),
            },
        )
        .await;

        manager
-            .refresh_available_models(&config)
+            .refresh_available_models_with_cache(&config)
            .await
            .expect("second refresh succeeds");

@@ -513,9 +513,9 @@ mod tests {
        )
        .unwrap_or_else(|_| cfg.codex_home.join("skills/pdf-processing/SKILL.md"));
        let expected_path_str = expected_path.to_string_lossy().replace('\\', "/");
-        let usage_rules = "- Discovery: Available skills are listed in project docs and may also appear in a runtime \"## Skills\" section (name + description + file path). These are the sources of truth; skill bodies live on disk at the listed paths.\n- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.\n- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.\n- How to use a skill (progressive disclosure):\n  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.\n  2) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.\n  3) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.\n  4) If `assets/` or templates exist, reuse them instead of recreating from scratch.\n- Description as trigger: The YAML `description` in `SKILL.md` is the primary trigger signal; rely on it to decide applicability. If unsure, ask a brief clarification before proceeding.\n- Coordination and sequencing:\n  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.\n  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.\n- Context hygiene:\n  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.\n  - Avoid deeply nested references; prefer one-hop files explicitly linked from `SKILL.md`.\n  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.\n- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.";
+        let usage_rules = "- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.\n- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.\n- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.\n- How to use a skill (progressive disclosure):\n  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.\n  2) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.\n  3) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.\n  4) If `assets/` or templates exist, reuse them instead of recreating from scratch.\n- Coordination and sequencing:\n  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.\n  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.\n- Context hygiene:\n  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.\n  - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.\n  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.\n- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.";
        let expected = format!(
-            "base doc\n\n## Skills\nThese skills are discovered at startup from multiple local sources. Each entry includes a name, description, and file path so you can open the source for full instructions.\n- pdf-processing: extract from pdfs (file: {expected_path_str})\n{usage_rules}"
+            "base doc\n\n## Skills\nA skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.\n### Available skills\n- pdf-processing: extract from pdfs (file: {expected_path_str})\n### How to use skills\n{usage_rules}"
        );
        assert_eq!(res, expected);
    }
@@ -537,9 +537,9 @@ mod tests {
            dunce::canonicalize(cfg.codex_home.join("skills/linting/SKILL.md").as_path())
                .unwrap_or_else(|_| cfg.codex_home.join("skills/linting/SKILL.md"));
        let expected_path_str = expected_path.to_string_lossy().replace('\\', "/");
-        let usage_rules = "- Discovery: Available skills are listed in project docs and may also appear in a runtime \"## Skills\" section (name + description + file path). These are the sources of truth; skill bodies live on disk at the listed paths.\n- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.\n- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.\n- How to use a skill (progressive disclosure):\n  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.\n  2) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.\n  3) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.\n  4) If `assets/` or templates exist, reuse them instead of recreating from scratch.\n- Description as trigger: The YAML `description` in `SKILL.md` is the primary trigger signal; rely on it to decide applicability. If unsure, ask a brief clarification before proceeding.\n- Coordination and sequencing:\n  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.\n  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.\n- Context hygiene:\n  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.\n  - Avoid deeply nested references; prefer one-hop files explicitly linked from `SKILL.md`.\n  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.\n- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.";
+        let usage_rules = "- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.\n- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.\n- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.\n- How to use a skill (progressive disclosure):\n  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.\n  2) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.\n  3) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.\n  4) If `assets/` or templates exist, reuse them instead of recreating from scratch.\n- Coordination and sequencing:\n  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.\n  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.\n- Context hygiene:\n  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.\n  - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.\n  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.\n- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.";
        let expected = format!(
-            "## Skills\nThese skills are discovered at startup from multiple local sources. Each entry includes a name, description, and file path so you can open the source for full instructions.\n- linting: run clippy (file: {expected_path_str})\n{usage_rules}"
+            "## Skills\nA skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.\n### Available skills\n- linting: run clippy (file: {expected_path_str})\n### How to use skills\n{usage_rules}"
        );
        assert_eq!(res, expected);
    }
@@ -1,9 +1,10 @@
 use crate::config::Config;
-use crate::git_info::resolve_root_git_project_for_trust;
+use crate::config_loader::ConfigLayerStack;
 use crate::skills::model::SkillError;
 use crate::skills::model::SkillLoadOutcome;
 use crate::skills::model::SkillMetadata;
 use crate::skills::system::system_cache_root_dir;
+use codex_app_server_protocol::ConfigLayerSource;
 use codex_protocol::protocol::SkillScope;
 use dunce::canonicalize as normalize_path;
 use serde::Deserialize;
@@ -32,8 +33,6 @@ struct SkillFrontmatterMetadata {

 const SKILLS_FILENAME: &str = "SKILL.md";
 const SKILLS_DIR_NAME: &str = "skills";
-const REPO_ROOT_CONFIG_DIR_NAME: &str = ".codex";
-const ADMIN_SKILLS_ROOT: &str = "/etc/codex/skills";
 const MAX_NAME_LEN: usize = 64;
 const MAX_DESCRIPTION_LEN: usize = 1024;
 const MAX_SHORT_DESCRIPTION_LEN: usize = MAX_DESCRIPTION_LEN;
@@ -88,86 +87,81 @@ where
        .skills
        .retain(|skill| seen.insert(skill.name.clone()));

-    outcome
-        .skills
-        .sort_by(|a, b| a.name.cmp(&b.name).then_with(|| a.path.cmp(&b.path)));
-
-    outcome
-}
-
-pub(crate) fn user_skills_root(codex_home: &Path) -> SkillRoot {
-    SkillRoot {
-        path: codex_home.join(SKILLS_DIR_NAME),
-        scope: SkillScope::User,
-    }
-}
-
-pub(crate) fn system_skills_root(codex_home: &Path) -> SkillRoot {
-    SkillRoot {
-        path: system_cache_root_dir(codex_home),
-        scope: SkillScope::System,
-    }
-}
-
-pub(crate) fn admin_skills_root() -> SkillRoot {
-    SkillRoot {
-        path: PathBuf::from(ADMIN_SKILLS_ROOT),
-        scope: SkillScope::Admin,
-    }
-}
-
-pub(crate) fn repo_skills_root(cwd: &Path) -> Option<SkillRoot> {
-    let base = if cwd.is_dir() { cwd } else { cwd.parent()? };
-    let base = normalize_path(base).unwrap_or_else(|_| base.to_path_buf());
-
-    let repo_root =
-        resolve_root_git_project_for_trust(&base).map(|root| normalize_path(&root).unwrap_or(root));
-
-    let scope = SkillScope::Repo;
-    if let Some(repo_root) = repo_root.as_deref() {
-        for dir in base.ancestors() {
-            let skills_root = dir.join(REPO_ROOT_CONFIG_DIR_NAME).join(SKILLS_DIR_NAME);
-            if skills_root.is_dir() {
-                return Some(SkillRoot {
-                    path: skills_root,
-                    scope,
-                });
-            }
-
-            if dir == repo_root {
-                break;
-            }
+    fn scope_rank(scope: SkillScope) -> u8 {
+        // Higher-priority scopes first (matches dedupe priority order).
+        match scope {
+            SkillScope::Repo => 0,
+            SkillScope::User => 1,
+            SkillScope::System => 2,
+            SkillScope::Admin => 3,
        }
-        return None;
    }

-    let skills_root = base.join(REPO_ROOT_CONFIG_DIR_NAME).join(SKILLS_DIR_NAME);
-    skills_root.is_dir().then_some(SkillRoot {
-        path: skills_root,
-        scope,
-    })
+    outcome.skills.sort_by(|a, b| {
+        scope_rank(a.scope)
+            .cmp(&scope_rank(b.scope))
+            .then_with(|| a.name.cmp(&b.name))
+            .then_with(|| a.path.cmp(&b.path))
+    });
+
+    outcome
 }

-pub(crate) fn skill_roots_for_cwd(codex_home: &Path, cwd: &Path) -> Vec<SkillRoot> {
+fn skill_roots_from_layer_stack_inner(config_layer_stack: &ConfigLayerStack) -> Vec<SkillRoot> {
    let mut roots = Vec::new();

-    if let Some(repo_root) = repo_skills_root(cwd) {
-        roots.push(repo_root);
-    }
+    for layer in config_layer_stack.layers_high_to_low() {
+        let Some(config_folder) = layer.config_folder() else {
+            continue;
+        };

-    // Load order matters: we dedupe by name, keeping the first occurrence.
-    // Priority order: repo, user, system, then admin.
-    roots.push(user_skills_root(codex_home));
-    roots.push(system_skills_root(codex_home));
-    if cfg!(unix) {
-        roots.push(admin_skills_root());
+        match &layer.name {
+            ConfigLayerSource::Project { .. } => {
+                roots.push(SkillRoot {
+                    path: config_folder.as_path().join(SKILLS_DIR_NAME),
+                    scope: SkillScope::Repo,
+                });
+            }
+            ConfigLayerSource::User { .. } => {
+                // `$CODEX_HOME/skills` (user-installed skills).
+                roots.push(SkillRoot {
+                    path: config_folder.as_path().join(SKILLS_DIR_NAME),
+                    scope: SkillScope::User,
+                });
+
+                // Embedded system skills are cached under `$CODEX_HOME/skills/.system` and are a
+                // special case (not a config layer).
+                roots.push(SkillRoot {
+                    path: system_cache_root_dir(config_folder.as_path()),
+                    scope: SkillScope::System,
+                });
+            }
+            ConfigLayerSource::System { .. } => {
+                // The system config layer lives under `/etc/codex/` on Unix, so treat
+                // `/etc/codex/skills` as admin-scoped skills.
+                roots.push(SkillRoot {
+                    path: config_folder.as_path().join(SKILLS_DIR_NAME),
+                    scope: SkillScope::Admin,
+                });
+            }
+            ConfigLayerSource::Mdm { .. }
+            | ConfigLayerSource::SessionFlags
+            | ConfigLayerSource::LegacyManagedConfigTomlFromFile { .. }
+            | ConfigLayerSource::LegacyManagedConfigTomlFromMdm => {}
+        }
    }

    roots
 }

 fn skill_roots(config: &Config) -> Vec<SkillRoot> {
-    skill_roots_for_cwd(&config.codex_home, &config.cwd)
+    skill_roots_from_layer_stack_inner(&config.config_layer_stack)
+}
+
+pub(crate) fn skill_roots_from_layer_stack(
+    config_layer_stack: &ConfigLayerStack,
+) -> Vec<SkillRoot> {
+    skill_roots_from_layer_stack_inner(config_layer_stack)
 }

 fn discover_skills_under_root(root: &Path, scope: SkillScope, outcome: &mut SkillLoadOutcome) {
@@ -318,21 +312,91 @@ fn extract_frontmatter(contents: &str) -> Option<String> {
 mod tests {
    use super::*;
    use crate::config::ConfigBuilder;
+    use crate::config::ConfigOverrides;
+    use crate::config_loader::ConfigLayerEntry;
+    use crate::config_loader::ConfigLayerStack;
+    use crate::config_loader::ConfigRequirements;
    use codex_protocol::protocol::SkillScope;
+    use codex_utils_absolute_path::AbsolutePathBuf;
    use pretty_assertions::assert_eq;
    use std::path::Path;
-    use std::process::Command;
    use tempfile::TempDir;
+    use toml::Value as TomlValue;
+
+    const REPO_ROOT_CONFIG_DIR_NAME: &str = ".codex";

    async fn make_config(codex_home: &TempDir) -> Config {
-        let mut config = ConfigBuilder::default()
+        make_config_for_cwd(codex_home, codex_home.path().to_path_buf()).await
+    }
+
+    async fn make_config_for_cwd(codex_home: &TempDir, cwd: PathBuf) -> Config {
+        let harness_overrides = ConfigOverrides {
+            cwd: Some(cwd),
+            ..Default::default()
+        };
+
+        ConfigBuilder::default()
            .codex_home(codex_home.path().to_path_buf())
+            .harness_overrides(harness_overrides)
            .build()
            .await
-            .expect("defaults for test should always succeed");
+            .expect("defaults for test should always succeed")
+    }

-        config.cwd = codex_home.path().to_path_buf();
-        config
+    fn mark_as_git_repo(dir: &Path) {
+        // Config/project-root discovery only checks for the presence of `.git` (file or dir),
+        // so we can avoid shelling out to `git init` in tests.
+        fs::write(dir.join(".git"), "gitdir: fake\n").unwrap();
+    }
+
+    fn normalized(path: &Path) -> PathBuf {
+        normalize_path(path).unwrap_or_else(|_| path.to_path_buf())
+    }
+
+    #[test]
+    fn skill_roots_from_layer_stack_maps_user_to_user_and_system_cache_and_system_to_admin()
+    -> anyhow::Result<()> {
+        let tmp = tempfile::tempdir()?;
+
+        let system_folder = tmp.path().join("etc/codex");
+        let user_folder = tmp.path().join("home/codex");
+        fs::create_dir_all(&system_folder)?;
+        fs::create_dir_all(&user_folder)?;
+
+        // The file path doesn't need to exist; it's only used to derive the config folder.
+        let system_file = AbsolutePathBuf::from_absolute_path(system_folder.join("config.toml"))?;
+        let user_file = AbsolutePathBuf::from_absolute_path(user_folder.join("config.toml"))?;
+
+        let layers = vec![
+            ConfigLayerEntry::new(
+                ConfigLayerSource::System { file: system_file },
+                TomlValue::Table(toml::map::Map::new()),
+            ),
+            ConfigLayerEntry::new(
+                ConfigLayerSource::User { file: user_file },
+                TomlValue::Table(toml::map::Map::new()),
+            ),
+        ];
+        let stack = ConfigLayerStack::new(layers, ConfigRequirements::default())?;
+
+        let got = skill_roots_from_layer_stack(&stack)
+            .into_iter()
+            .map(|root| (root.scope, root.path))
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            got,
+            vec![
+                (SkillScope::User, user_folder.join("skills")),
+                (
+                    SkillScope::System,
+                    user_folder.join("skills").join(".system")
+                ),
+                (SkillScope::Admin, system_folder.join("skills")),
+            ]
+        );
+
+        Ok(())
    }

    fn write_skill(codex_home: &TempDir, dir: &str, name: &str, description: &str) -> PathBuf {
@@ -368,7 +432,7 @@ mod tests {
    #[tokio::test]
    async fn loads_valid_skill() {
        let codex_home = tempfile::tempdir().expect("tempdir");
-        write_skill(&codex_home, "demo", "demo-skill", "does things\ncarefully");
+        let skill_path = write_skill(&codex_home, "demo", "demo-skill", "does things\ncarefully");
        let cfg = make_config(&codex_home).await;

        let outcome = load_skills(&cfg);
@@ -377,15 +441,15 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        let skill = &outcome.skills[0];
-        assert_eq!(skill.name, "demo-skill");
-        assert_eq!(skill.description, "does things carefully");
-        assert_eq!(skill.short_description, None);
-        let path_str = skill.path.to_string_lossy().replace('\\', "/");
-        assert!(
-            path_str.ends_with("skills/demo/SKILL.md"),
-            "unexpected path {path_str}"
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "demo-skill".to_string(),
+                description: "does things carefully".to_string(),
+                short_description: None,
+                path: normalized(&skill_path),
+                scope: SkillScope::User,
+            }]
        );
    }

@@ -395,7 +459,8 @@ mod tests {
        let skill_dir = codex_home.path().join("skills/demo");
        fs::create_dir_all(&skill_dir).unwrap();
        let contents = "---\nname: demo-skill\ndescription: long description\nmetadata:\n  short-description: short summary\n---\n\n# Body\n";
-        fs::write(skill_dir.join(SKILLS_FILENAME), contents).unwrap();
+        let skill_path = skill_dir.join(SKILLS_FILENAME);
+        fs::write(&skill_path, contents).unwrap();

        let cfg = make_config(&codex_home).await;
        let outcome = load_skills(&cfg);
@@ -404,10 +469,15 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
        assert_eq!(
-            outcome.skills[0].short_description,
-            Some("short summary".to_string())
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "demo-skill".to_string(),
+                description: "long description".to_string(),
+                short_description: Some("short summary".to_string()),
+                path: normalized(&skill_path),
+                scope: SkillScope::User,
+            }]
        );
    }

@@ -493,22 +563,14 @@ mod tests {
    async fn loads_skills_from_repo_root() {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let repo_dir = tempfile::tempdir().expect("tempdir");
-
-        let status = Command::new("git")
-            .arg("init")
-            .current_dir(repo_dir.path())
-            .status()
-            .expect("git init");
-        assert!(status.success(), "git init failed");
+        mark_as_git_repo(repo_dir.path());

        let skills_root = repo_dir
            .path()
            .join(REPO_ROOT_CONFIG_DIR_NAME)
            .join(SKILLS_DIR_NAME);
-        write_skill_at(&skills_root, "repo", "repo-skill", "from repo");
-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = repo_dir.path().to_path_buf();
-        let repo_root = normalize_path(&skills_root).unwrap_or_else(|_| skills_root.clone());
+        let skill_path = write_skill_at(&skills_root, "repo", "repo-skill", "from repo");
+        let cfg = make_config_for_cwd(&codex_home, repo_dir.path().to_path_buf()).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -516,28 +578,28 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        let skill = &outcome.skills[0];
-        assert_eq!(skill.name, "repo-skill");
-        assert!(skill.path.starts_with(&repo_root));
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "repo-skill".to_string(),
+                description: "from repo".to_string(),
+                short_description: None,
+                path: normalized(&skill_path),
+                scope: SkillScope::Repo,
+            }]
+        );
    }

    #[tokio::test]
-    async fn loads_skills_from_nearest_codex_dir_under_repo_root() {
+    async fn loads_skills_from_all_codex_dirs_under_project_root() {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let repo_dir = tempfile::tempdir().expect("tempdir");
-
-        let status = Command::new("git")
-            .arg("init")
-            .current_dir(repo_dir.path())
-            .status()
-            .expect("git init");
-        assert!(status.success(), "git init failed");
+        mark_as_git_repo(repo_dir.path());

        let nested_dir = repo_dir.path().join("nested/inner");
        fs::create_dir_all(&nested_dir).unwrap();

-        write_skill_at(
+        let root_skill_path = write_skill_at(
            &repo_dir
                .path()
                .join(REPO_ROOT_CONFIG_DIR_NAME)
@@ -546,7 +608,7 @@ mod tests {
            "root-skill",
            "from root",
        );
-        write_skill_at(
+        let nested_skill_path = write_skill_at(
            &repo_dir
                .path()
                .join("nested")
@@ -557,8 +619,7 @@ mod tests {
            "from nested",
        );

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = nested_dir;
+        let cfg = make_config_for_cwd(&codex_home, nested_dir).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -566,8 +627,25 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "nested-skill");
+        assert_eq!(
+            outcome.skills,
+            vec![
+                SkillMetadata {
+                    name: "nested-skill".to_string(),
+                    description: "from nested".to_string(),
+                    short_description: None,
+                    path: normalized(&nested_skill_path),
+                    scope: SkillScope::Repo,
+                },
+                SkillMetadata {
+                    name: "root-skill".to_string(),
+                    description: "from root".to_string(),
+                    short_description: None,
+                    path: normalized(&root_skill_path),
+                    scope: SkillScope::Repo,
+                },
+            ]
+        );
    }

    #[tokio::test]
@@ -575,7 +653,7 @@ mod tests {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let work_dir = tempfile::tempdir().expect("tempdir");

-        write_skill_at(
+        let skill_path = write_skill_at(
            &work_dir
                .path()
                .join(REPO_ROOT_CONFIG_DIR_NAME)
@@ -585,8 +663,7 @@ mod tests {
            "from cwd",
        );

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = work_dir.path().to_path_buf();
+        let cfg = make_config_for_cwd(&codex_home, work_dir.path().to_path_buf()).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -594,25 +671,26 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "local-skill");
-        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "local-skill".to_string(),
+                description: "from cwd".to_string(),
+                short_description: None,
+                path: normalized(&skill_path),
+                scope: SkillScope::Repo,
+            }]
+        );
    }

    #[tokio::test]
    async fn deduplicates_by_name_preferring_repo_over_user() {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let repo_dir = tempfile::tempdir().expect("tempdir");
+        mark_as_git_repo(repo_dir.path());

-        let status = Command::new("git")
-            .arg("init")
-            .current_dir(repo_dir.path())
-            .status()
-            .expect("git init");
-        assert!(status.success(), "git init failed");
-
-        write_skill(&codex_home, "user", "dupe-skill", "from user");
-        write_skill_at(
+        let _user_skill_path = write_skill(&codex_home, "user", "dupe-skill", "from user");
+        let repo_skill_path = write_skill_at(
            &repo_dir
                .path()
                .join(REPO_ROOT_CONFIG_DIR_NAME)
@@ -622,8 +700,7 @@ mod tests {
            "from repo",
        );

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = repo_dir.path().to_path_buf();
+        let cfg = make_config_for_cwd(&codex_home, repo_dir.path().to_path_buf()).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -631,17 +708,25 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "dupe-skill");
-        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "dupe-skill".to_string(),
+                description: "from repo".to_string(),
+                short_description: None,
+                path: normalized(&repo_skill_path),
+                scope: SkillScope::Repo,
+            }]
+        );
    }

    #[tokio::test]
    async fn loads_system_skills_when_present() {
        let codex_home = tempfile::tempdir().expect("tempdir");

-        write_system_skill(&codex_home, "system", "dupe-skill", "from system");
-        write_skill(&codex_home, "user", "dupe-skill", "from user");
+        let _system_skill_path =
+            write_system_skill(&codex_home, "system", "dupe-skill", "from system");
+        let user_skill_path = write_skill(&codex_home, "user", "dupe-skill", "from user");

        let cfg = make_config(&codex_home).await;
        let outcome = load_skills(&cfg);
@@ -650,9 +735,16 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].description, "from user");
-        assert_eq!(outcome.skills[0].scope, SkillScope::User);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "dupe-skill".to_string(),
+                description: "from user".to_string(),
+                short_description: None,
+                path: normalized(&user_skill_path),
+                scope: SkillScope::User,
+            }]
+        );
    }

    #[tokio::test]
@@ -672,15 +764,9 @@ mod tests {
            "from outer",
        );

-        let status = Command::new("git")
-            .arg("init")
-            .current_dir(&repo_dir)
-            .status()
-            .expect("git init");
-        assert!(status.success(), "git init failed");
+        mark_as_git_repo(&repo_dir);

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = repo_dir;
+        let cfg = make_config_for_cwd(&codex_home, repo_dir).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -695,15 +781,9 @@ mod tests {
    async fn loads_skills_when_cwd_is_file_in_repo() {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let repo_dir = tempfile::tempdir().expect("tempdir");
+        mark_as_git_repo(repo_dir.path());

-        let status = Command::new("git")
-            .arg("init")
-            .current_dir(repo_dir.path())
-            .status()
-            .expect("git init");
-        assert!(status.success(), "git init failed");
-
-        write_skill_at(
+        let skill_path = write_skill_at(
            &repo_dir
                .path()
                .join(REPO_ROOT_CONFIG_DIR_NAME)
@@ -715,8 +795,7 @@ mod tests {
        let file_path = repo_dir.path().join("some-file.txt");
        fs::write(&file_path, "contents").unwrap();

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = file_path;
+        let cfg = make_config_for_cwd(&codex_home, file_path).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -724,9 +803,16 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "repo-skill");
-        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "repo-skill".to_string(),
+                description: "from repo".to_string(),
+                short_description: None,
+                path: normalized(&skill_path),
+                scope: SkillScope::Repo,
+            }]
+        );
    }

    #[tokio::test]
@@ -746,8 +832,7 @@ mod tests {
            "from outer",
        );

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = nested_dir;
+        let cfg = make_config_for_cwd(&codex_home, nested_dir).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -763,10 +848,9 @@ mod tests {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let work_dir = tempfile::tempdir().expect("tempdir");

-        write_system_skill(&codex_home, "system", "system-skill", "from system");
+        let skill_path = write_system_skill(&codex_home, "system", "system-skill", "from system");

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = work_dir.path().to_path_buf();
+        let cfg = make_config_for_cwd(&codex_home, work_dir.path().to_path_buf()).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -774,9 +858,16 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "system-skill");
-        assert_eq!(outcome.skills[0].scope, SkillScope::System);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "system-skill".to_string(),
+                description: "from system".to_string(),
+                short_description: None,
+                path: normalized(&skill_path),
+                scope: SkillScope::System,
+            }]
+        );
    }

    #[tokio::test]
@@ -800,8 +891,10 @@ mod tests {
        let system_dir = tempfile::tempdir().expect("tempdir");
        let admin_dir = tempfile::tempdir().expect("tempdir");

-        write_skill_at(system_dir.path(), "system", "dupe-skill", "from system");
-        write_skill_at(admin_dir.path(), "admin", "dupe-skill", "from admin");
+        let system_skill_path =
+            write_skill_at(system_dir.path(), "system", "dupe-skill", "from system");
+        let _admin_skill_path =
+            write_skill_at(admin_dir.path(), "admin", "dupe-skill", "from admin");

        let outcome = load_skills_from_roots([
            SkillRoot {
@@ -819,9 +912,16 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "dupe-skill");
-        assert_eq!(outcome.skills[0].scope, SkillScope::System);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "dupe-skill".to_string(),
+                description: "from system".to_string(),
+                short_description: None,
+                path: normalized(&system_skill_path),
+                scope: SkillScope::System,
+            }]
+        );
    }

    #[tokio::test]
@@ -829,11 +929,11 @@ mod tests {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let work_dir = tempfile::tempdir().expect("tempdir");

-        write_skill(&codex_home, "user", "dupe-skill", "from user");
-        write_system_skill(&codex_home, "system", "dupe-skill", "from system");
+        let user_skill_path = write_skill(&codex_home, "user", "dupe-skill", "from user");
+        let _system_skill_path =
+            write_system_skill(&codex_home, "system", "dupe-skill", "from system");

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = work_dir.path().to_path_buf();
+        let cfg = make_config_for_cwd(&codex_home, work_dir.path().to_path_buf()).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -841,24 +941,25 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "dupe-skill");
-        assert_eq!(outcome.skills[0].scope, SkillScope::User);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "dupe-skill".to_string(),
+                description: "from user".to_string(),
+                short_description: None,
+                path: normalized(&user_skill_path),
+                scope: SkillScope::User,
+            }]
+        );
    }

    #[tokio::test]
    async fn deduplicates_by_name_preferring_repo_over_system() {
        let codex_home = tempfile::tempdir().expect("tempdir");
        let repo_dir = tempfile::tempdir().expect("tempdir");
+        mark_as_git_repo(repo_dir.path());

-        let status = Command::new("git")
-            .arg("init")
-            .current_dir(repo_dir.path())
-            .status()
-            .expect("git init");
-        assert!(status.success(), "git init failed");
-
-        write_skill_at(
+        let repo_skill_path = write_skill_at(
            &repo_dir
                .path()
                .join(REPO_ROOT_CONFIG_DIR_NAME)
@@ -867,10 +968,10 @@ mod tests {
            "dupe-skill",
            "from repo",
        );
-        write_system_skill(&codex_home, "system", "dupe-skill", "from system");
+        let _system_skill_path =
+            write_system_skill(&codex_home, "system", "dupe-skill", "from system");

-        let mut cfg = make_config(&codex_home).await;
-        cfg.cwd = repo_dir.path().to_path_buf();
+        let cfg = make_config_for_cwd(&codex_home, repo_dir.path().to_path_buf()).await;

        let outcome = load_skills(&cfg);
        assert!(
@@ -878,8 +979,66 @@ mod tests {
            "unexpected errors: {:?}",
            outcome.errors
        );
-        assert_eq!(outcome.skills.len(), 1);
-        assert_eq!(outcome.skills[0].name, "dupe-skill");
-        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+        assert_eq!(
+            outcome.skills,
+            vec![SkillMetadata {
+                name: "dupe-skill".to_string(),
+                description: "from repo".to_string(),
+                short_description: None,
+                path: normalized(&repo_skill_path),
+                scope: SkillScope::Repo,
+            }]
+        );
+    }
+
+    #[tokio::test]
+    async fn deduplicates_by_name_preferring_nearest_project_codex_dir() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let repo_dir = tempfile::tempdir().expect("tempdir");
+        mark_as_git_repo(repo_dir.path());
+
+        let nested_dir = repo_dir.path().join("nested/inner");
+        fs::create_dir_all(&nested_dir).unwrap();
+
+        let _root_skill_path = write_skill_at(
+            &repo_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "root",
+            "dupe-skill",
+            "from root",
+        );
+        let nested_skill_path = write_skill_at(
+            &repo_dir
+                .path()
+                .join("nested")
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "nested",
+            "dupe-skill",
+            "from nested",
+        );
+
+        let cfg = make_config_for_cwd(&codex_home, nested_dir).await;
+        let outcome = load_skills(&cfg);
+
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        let expected_path =
+            normalize_path(&nested_skill_path).unwrap_or_else(|_| nested_skill_path.clone());
+        assert_eq!(
+            vec![SkillMetadata {
+                name: "dupe-skill".to_string(),
+                description: "from nested".to_string(),
+                short_description: None,
+                path: expected_path,
+                scope: SkillScope::Repo,
+            }],
+            outcome.skills
+        );
    }
 }
@@ -3,10 +3,17 @@ use std::path::Path;
 use std::path::PathBuf;
 use std::sync::RwLock;

+use codex_utils_absolute_path::AbsolutePathBuf;
+use toml::Value as TomlValue;
+
+use crate::config::Config;
+use crate::config_loader::LoaderOverrides;
+use crate::config_loader::load_config_layers_state;
 use crate::skills::SkillLoadOutcome;
 use crate::skills::loader::load_skills_from_roots;
-use crate::skills::loader::skill_roots_for_cwd;
+use crate::skills::loader::skill_roots_from_layer_stack;
 use crate::skills::system::install_system_skills;
+
 pub struct SkillsManager {
    codex_home: PathBuf,
    cache_by_cwd: RwLock<HashMap<PathBuf, SkillLoadOutcome>>,
@@ -24,11 +31,32 @@ impl SkillsManager {
        }
    }

-    pub fn skills_for_cwd(&self, cwd: &Path) -> SkillLoadOutcome {
-        self.skills_for_cwd_with_options(cwd, false)
+    /// Load skills for an already-constructed [`Config`], avoiding any additional config-layer
+    /// loading. This also seeds the per-cwd cache for subsequent lookups.
+    pub fn skills_for_config(&self, config: &Config) -> SkillLoadOutcome {
+        let cwd = &config.cwd;
+        let cached = match self.cache_by_cwd.read() {
+            Ok(cache) => cache.get(cwd).cloned(),
+            Err(err) => err.into_inner().get(cwd).cloned(),
+        };
+        if let Some(outcome) = cached {
+            return outcome;
+        }
+
+        let roots = skill_roots_from_layer_stack(&config.config_layer_stack);
+        let outcome = load_skills_from_roots(roots);
+        match self.cache_by_cwd.write() {
+            Ok(mut cache) => {
+                cache.insert(cwd.to_path_buf(), outcome.clone());
+            }
+            Err(err) => {
+                err.into_inner().insert(cwd.to_path_buf(), outcome.clone());
+            }
+        }
+        outcome
    }

-    pub fn skills_for_cwd_with_options(&self, cwd: &Path, force_reload: bool) -> SkillLoadOutcome {
+    pub async fn skills_for_cwd(&self, cwd: &Path, force_reload: bool) -> SkillLoadOutcome {
        let cached = match self.cache_by_cwd.read() {
            Ok(cache) => cache.get(cwd).cloned(),
            Err(err) => err.into_inner().get(cwd).cloned(),
@@ -37,7 +65,41 @@ impl SkillsManager {
            return outcome;
        }

-        let roots = skill_roots_for_cwd(&self.codex_home, cwd);
+        let cwd_abs = match AbsolutePathBuf::try_from(cwd) {
+            Ok(cwd_abs) => cwd_abs,
+            Err(err) => {
+                return SkillLoadOutcome {
+                    errors: vec![crate::skills::model::SkillError {
+                        path: cwd.to_path_buf(),
+                        message: err.to_string(),
+                    }],
+                    ..Default::default()
+                };
+            }
+        };
+
+        let cli_overrides: Vec<(String, TomlValue)> = Vec::new();
+        let config_layer_stack = match load_config_layers_state(
+            &self.codex_home,
+            Some(cwd_abs),
+            &cli_overrides,
+            LoaderOverrides::default(),
+        )
+        .await
+        {
+            Ok(config_layer_stack) => config_layer_stack,
+            Err(err) => {
+                return SkillLoadOutcome {
+                    errors: vec![crate::skills::model::SkillError {
+                        path: cwd.to_path_buf(),
+                        message: err.to_string(),
+                    }],
+                    ..Default::default()
+                };
+            }
+        };
+
+        let roots = skill_roots_from_layer_stack(&config_layer_stack);
        let outcome = load_skills_from_roots(roots);
        match self.cache_by_cwd.write() {
            Ok(mut cache) => {
@@ -50,3 +112,52 @@ impl SkillsManager {
        outcome
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::ConfigBuilder;
+    use crate::config::ConfigOverrides;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+    use tempfile::TempDir;
+
+    fn write_user_skill(codex_home: &TempDir, dir: &str, name: &str, description: &str) {
+        let skill_dir = codex_home.path().join("skills").join(dir);
+        fs::create_dir_all(&skill_dir).unwrap();
+        let content = format!("---\nname: {name}\ndescription: {description}\n---\n\n# Body\n");
+        fs::write(skill_dir.join("SKILL.md"), content).unwrap();
+    }
+
+    #[tokio::test]
+    async fn skills_for_config_seeds_cache_by_cwd() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let cwd = tempfile::tempdir().expect("tempdir");
+
+        let cfg = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .harness_overrides(ConfigOverrides {
+                cwd: Some(cwd.path().to_path_buf()),
+                ..Default::default()
+            })
+            .build()
+            .await
+            .expect("defaults for test should always succeed");
+
+        let skills_manager = SkillsManager::new(codex_home.path().to_path_buf());
+
+        write_user_skill(&codex_home, "a", "skill-a", "from a");
+        let outcome1 = skills_manager.skills_for_config(&cfg);
+        assert!(
+            outcome1.skills.iter().any(|s| s.name == "skill-a"),
+            "expected skill-a to be discovered"
+        );
+
+        // Write a new skill after the first call; the second call should hit the cache and not
+        // reflect the new file.
+        write_user_skill(&codex_home, "b", "skill-b", "from b");
+        let outcome2 = skills_manager.skills_for_config(&cfg);
+        assert_eq!(outcome2.errors, outcome1.errors);
+        assert_eq!(outcome2.skills, outcome1.skills);
+    }
+}
@@ -7,7 +7,8 @@ pub fn render_skills_section(skills: &[SkillMetadata]) -> Option<String> {

    let mut lines: Vec<String> = Vec::new();
    lines.push("## Skills".to_string());
-    lines.push("These skills are discovered at startup from multiple local sources. Each entry includes a name, description, and file path so you can open the source for full instructions.".to_string());
+    lines.push("A skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.".to_string());
+    lines.push("### Available skills".to_string());

    for skill in skills {
        let path_str = skill.path.to_string_lossy().replace('\\', "/");
@@ -16,22 +17,22 @@ pub fn render_skills_section(skills: &[SkillMetadata]) -> Option<String> {
        lines.push(format!("- {name}: {description} (file: {path_str})"));
    }

+    lines.push("### How to use skills".to_string());
    lines.push(
-        r###"- Discovery: Available skills are listed in project docs and may also appear in a runtime "## Skills" section (name + description + file path). These are the sources of truth; skill bodies live on disk at the listed paths.
- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
+        r###"- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
+- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
 - Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.
 - How to use a skill (progressive disclosure):
  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.
  2) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.
  3) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.
  4) If `assets/` or templates exist, reuse them instead of recreating from scratch.
- Description as trigger: The YAML `description` in `SKILL.md` is the primary trigger signal; rely on it to decide applicability. If unsure, ask a brief clarification before proceeding.
 - Coordination and sequencing:
  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.
  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.
 - Context hygiene:
  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
-  - Avoid deeply nested references; prefer one-hop files explicitly linked from `SKILL.md`.
+  - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.
  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
 - Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue."###
            .to_string(),
@@ -47,7 +47,7 @@ use super::session::OutputBuffer;
 use super::session::OutputHandles;
 use super::session::UnifiedExecSession;

-const UNIFIED_EXEC_ENV: [(&str, &str); 8] = [
+const UNIFIED_EXEC_ENV: [(&str, &str); 9] = [
    ("NO_COLOR", "1"),
    ("TERM", "dumb"),
    ("LANG", "C.UTF-8"),
@@ -56,6 +56,7 @@ const UNIFIED_EXEC_ENV: [(&str, &str); 8] = [
    ("COLORTERM", ""),
    ("PAGER", "cat"),
    ("GIT_PAGER", "cat"),
+    ("GH_PAGER", "cat"),
 ];

 fn apply_unified_exec_env(mut env: HashMap<String, String>) -> HashMap<String, String> {
@@ -679,6 +680,7 @@ mod tests {
            ("COLORTERM".to_string(), String::new()),
            ("PAGER".to_string(), "cat".to_string()),
            ("GIT_PAGER".to_string(), "cat".to_string()),
+            ("GH_PAGER".to_string(), "cat".to_string()),
        ]);

        assert_eq!(env, expected);
@@ -9,6 +9,31 @@ use tracing::error;
 const INITIAL_DELAY_MS: u64 = 200;
 const BACKOFF_FACTOR: f64 = 2.0;

+/// Emit structured feedback metadata as key/value pairs.
+///
+/// This logs a tracing event with `target: "feedback_tags"`. If
+/// `codex_feedback::CodexFeedback::metadata_layer()` is installed, these fields are captured and
+/// later attached as tags when feedback is uploaded.
+///
+/// Values are wrapped with [`tracing::field::DebugValue`], so the expression only needs to
+/// implement [`std::fmt::Debug`].
+///
+/// Example:
+///
+/// ```rust
+/// codex_core::feedback_tags!(model = "gpt-5", cached = true);
+/// codex_core::feedback_tags!(provider = provider_id, request_id = request_id);
+/// ```
+#[macro_export]
+macro_rules! feedback_tags {
+    ($( $key:ident = $value:expr ),+ $(,)?) => {
+        ::tracing::info!(
+            target: "feedback_tags",
+            $( $key = ::tracing::field::debug(&$value) ),+
+        );
+    };
+}
+
 pub(crate) fn backoff(attempt: u64) -> Duration {
    let exp = BACKOFF_FACTOR.powi(attempt.saturating_sub(1) as i32);
    let base = (INITIAL_DELAY_MS as f64 * exp) as u64;
@@ -74,4 +99,12 @@ mod tests {
        let message = try_parse_error_message(text);
        assert_eq!(message, r#"{"message": "test"}"#);
    }
+
+    #[test]
+    fn feedback_tags_macro_compiles() {
+        #[derive(Debug)]
+        struct OnlyDebug;
+
+        feedback_tags!(model = "gpt-5", cached = true, debug_only = OnlyDebug);
+    }
 }
@@ -670,6 +670,25 @@ pub async fn mount_models_once(server: &MockServer, body: ModelsResponse) -> Mod
    models_mock
 }

+pub async fn mount_models_once_with_etag(
+    server: &MockServer,
+    body: ModelsResponse,
+    etag: &str,
+) -> ModelsMock {
+    let (mock, models_mock) = models_mock();
+    mock.respond_with(
+        ResponseTemplate::new(200)
+            .insert_header("content-type", "application/json")
+            // ModelsClient reads the ETag header, not a JSON field.
+            .insert_header("ETag", etag)
+            .set_body_json(body.clone()),
+    )
+    .up_to_n_times(1)
+    .mount(server)
+    .await;
+    models_mock
+}
+
 pub async fn start_mock_server() -> MockServer {
    let server = MockServer::builder()
        .body_print_limit(BodyPrintLimit::Limited(80_000))
@@ -677,14 +696,7 @@ pub async fn start_mock_server() -> MockServer {
        .await;

    // Provide a default `/models` response so tests remain hermetic when the client queries it.
-    let _ = mount_models_once(
-        &server,
-        ModelsResponse {
-            models: Vec::new(),
-            etag: String::new(),
-        },
-    )
-    .await;
+    let _ = mount_models_once(&server, ModelsResponse { models: Vec::new() }).await;

    server
 }
@@ -49,6 +49,7 @@ async fn interrupt_long_running_tool_emits_turn_aborted() {
            items: vec![UserInput::Text {
                text: "start sleep".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -101,6 +102,7 @@ async fn interrupt_tool_records_history_entries() {
            items: vec![UserInput::Text {
                text: "start history recording".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -117,6 +119,7 @@ async fn interrupt_tool_records_history_entries() {
            items: vec![UserInput::Text {
                text: "follow up".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -290,6 +290,7 @@ async fn resume_includes_initial_messages_and_sends_prior_items() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -365,6 +366,7 @@ async fn includes_conversation_id_and_model_headers_in_request() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -424,6 +426,7 @@ async fn includes_base_instructions_override_in_request() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -488,6 +491,7 @@ async fn chatgpt_auth_sends_correct_request() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -582,6 +586,7 @@ async fn prefers_apikey_when_config_prefers_apikey_even_with_chatgpt_tokens() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -622,6 +627,7 @@ async fn includes_user_instructions_message_in_request() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -692,6 +698,7 @@ async fn skills_append_to_instructions() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -741,6 +748,7 @@ async fn includes_configured_effort_in_request() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -777,6 +785,7 @@ async fn includes_no_effort_in_request() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -811,6 +820,7 @@ async fn includes_default_reasoning_effort_in_request_when_defined_by_model_fami
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -849,6 +859,7 @@ async fn configured_reasoning_summary_is_sent() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -887,6 +898,7 @@ async fn reasoning_summary_is_omitted_when_disabled() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -919,6 +931,7 @@ async fn includes_default_verbosity_in_request() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -958,6 +971,7 @@ async fn configured_verbosity_not_sent_for_models_without_support() -> anyhow::R
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -996,6 +1010,7 @@ async fn configured_verbosity_is_sent() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1050,6 +1065,7 @@ async fn includes_developer_instructions_message_in_request() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1280,6 +1296,7 @@ async fn token_count_includes_rate_limits_snapshot() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1437,6 +1454,7 @@ async fn usage_limit_error_emits_rate_limit_event() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .expect("submission should succeed while emitting usage limit error events");
@@ -1506,6 +1524,7 @@ async fn context_window_error_sets_total_tokens_to_model_window() -> anyhow::Res
            items: vec![UserInput::Text {
                text: "seed turn".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -1516,6 +1535,7 @@ async fn context_window_error_sets_total_tokens_to_model_window() -> anyhow::Res
            items: vec![UserInput::Text {
                text: "trigger context window".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -1635,6 +1655,7 @@ async fn azure_overrides_assign_properties_used_for_responses_url() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1717,6 +1738,7 @@ async fn env_var_overrides_loaded_auth() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1800,6 +1822,7 @@ async fn history_dedupes_streamed_and_final_messages_across_turns() {
    codex
        .submit(Op::UserInput {
            items: vec![UserInput::Text { text: "U1".into() }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1809,6 +1832,7 @@ async fn history_dedupes_streamed_and_final_messages_across_turns() {
    codex
        .submit(Op::UserInput {
            items: vec![UserInput::Text { text: "U2".into() }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1818,6 +1842,7 @@ async fn history_dedupes_streamed_and_final_messages_across_turns() {
    codex
        .submit(Op::UserInput {
            items: vec![UserInput::Text { text: "U3".into() }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -8,11 +8,14 @@ use codex_core::compact::SUMMARIZATION_PROMPT;
 use codex_core::compact::SUMMARY_PREFIX;
 use codex_core::config::Config;
 use codex_core::features::Feature;
+use codex_core::protocol::AskForApproval;
 use codex_core::protocol::EventMsg;
 use codex_core::protocol::Op;
 use codex_core::protocol::RolloutItem;
 use codex_core::protocol::RolloutLine;
+use codex_core::protocol::SandboxPolicy;
 use codex_core::protocol::WarningEvent;
+use codex_protocol::config_types::ReasoningSummary;
 use codex_protocol::user_input::UserInput;
 use core_test_support::load_default_config_for_test;
 use core_test_support::responses::ev_local_shell_call;
@@ -158,6 +161,7 @@ async fn summarize_context_three_requests_and_instructions() {
            items: vec![UserInput::Text {
                text: "hello world".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -178,6 +182,7 @@ async fn summarize_context_three_requests_and_instructions() {
            items: vec![UserInput::Text {
                text: THIRD_USER_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -577,6 +582,7 @@ async fn multiple_auto_compact_per_task_runs_after_token_limit_hit() {
            items: vec![UserInput::Text {
                text: user_message.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .expect("submit user input");
@@ -1081,6 +1087,7 @@ async fn auto_compact_runs_after_token_limit_hit() {
            items: vec![UserInput::Text {
                text: FIRST_AUTO_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1092,6 +1099,7 @@ async fn auto_compact_runs_after_token_limit_hit() {
            items: vec![UserInput::Text {
                text: SECOND_AUTO_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1103,6 +1111,7 @@ async fn auto_compact_runs_after_token_limit_hit() {
            items: vec![UserInput::Text {
                text: POST_AUTO_USER_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1228,6 +1237,117 @@ async fn auto_compact_runs_after_token_limit_hit() {
    );
 }

+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn auto_compact_runs_after_resume_when_token_usage_is_over_limit() {
+    skip_if_no_network!();
+
+    let server = start_mock_server().await;
+
+    let limit = 200_000;
+    let over_limit_tokens = 250_000;
+    let remote_summary = "REMOTE_COMPACT_SUMMARY";
+
+    let compacted_history = vec![
+        codex_protocol::models::ResponseItem::Message {
+            id: None,
+            role: "assistant".to_string(),
+            content: vec![codex_protocol::models::ContentItem::OutputText {
+                text: remote_summary.to_string(),
+            }],
+        },
+        codex_protocol::models::ResponseItem::Compaction {
+            encrypted_content: "ENCRYPTED_COMPACTION_SUMMARY".to_string(),
+        },
+    ];
+    let compact_mock =
+        mount_compact_json_once(&server, serde_json::json!({ "output": compacted_history })).await;
+
+    let mut builder = test_codex().with_config(move |config| {
+        set_test_compact_prompt(config);
+        config.model_auto_compact_token_limit = Some(limit);
+        config.features.enable(Feature::RemoteCompaction);
+    });
+    let initial = builder.build(&server).await.unwrap();
+    let home = initial.home.clone();
+    let rollout_path = initial.session_configured.rollout_path.clone();
+
+    // A single over-limit completion should not auto-compact until the next user message.
+    mount_sse_once(
+        &server,
+        sse(vec![
+            ev_assistant_message("m1", FIRST_REPLY),
+            ev_completed_with_tokens("r1", over_limit_tokens),
+        ]),
+    )
+    .await;
+    initial.submit_turn("OVER_LIMIT_TURN").await.unwrap();
+
+    assert!(
+        compact_mock.requests().is_empty(),
+        "remote compaction should not run before the next user message"
+    );
+
+    let mut resume_builder = test_codex().with_config(move |config| {
+        set_test_compact_prompt(config);
+        config.model_auto_compact_token_limit = Some(limit);
+        config.features.enable(Feature::RemoteCompaction);
+    });
+    let resumed = resume_builder
+        .resume(&server, home, rollout_path)
+        .await
+        .unwrap();
+
+    let follow_up_user = "AFTER_RESUME_USER";
+    let sse_follow_up = sse(vec![
+        ev_assistant_message("m2", FINAL_REPLY),
+        ev_completed("r2"),
+    ]);
+
+    let follow_up_matcher = move |req: &wiremock::Request| {
+        let body = std::str::from_utf8(&req.body).unwrap_or("");
+        body.contains(follow_up_user) && body.contains(remote_summary)
+    };
+    mount_sse_once_match(&server, follow_up_matcher, sse_follow_up).await;
+
+    resumed
+        .codex
+        .submit(Op::UserTurn {
+            items: vec![UserInput::Text {
+                text: follow_up_user.into(),
+            }],
+            final_output_json_schema: None,
+            cwd: resumed.cwd.path().to_path_buf(),
+            approval_policy: AskForApproval::Never,
+            sandbox_policy: SandboxPolicy::DangerFullAccess,
+            model: resumed.session_configured.model.clone(),
+            effort: None,
+            summary: ReasoningSummary::Auto,
+        })
+        .await
+        .unwrap();
+
+    wait_for_event(&resumed.codex, |event| {
+        matches!(event, EventMsg::ContextCompacted(_))
+    })
+    .await;
+    wait_for_event(&resumed.codex, |event| {
+        matches!(event, EventMsg::TaskComplete(_))
+    })
+    .await;
+
+    let compact_requests = compact_mock.requests();
+    assert_eq!(
+        compact_requests.len(),
+        1,
+        "remote compaction should run once after resume"
+    );
+    assert_eq!(
+        compact_requests[0].path(),
+        "/v1/responses/compact",
+        "remote compaction should hit the compact endpoint"
+    );
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn auto_compact_persists_rollout_entries() {
    skip_if_no_network!();
@@ -1304,6 +1424,7 @@ async fn auto_compact_persists_rollout_entries() {
            items: vec![UserInput::Text {
                text: FIRST_AUTO_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1314,6 +1435,7 @@ async fn auto_compact_persists_rollout_entries() {
            items: vec![UserInput::Text {
                text: SECOND_AUTO_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1324,6 +1446,7 @@ async fn auto_compact_persists_rollout_entries() {
            items: vec![UserInput::Text {
                text: POST_AUTO_USER_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1415,6 +1538,7 @@ async fn manual_compact_retries_after_context_window_error() {
            items: vec![UserInput::Text {
                text: "first turn".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1547,6 +1671,7 @@ async fn manual_compact_twice_preserves_latest_user_messages() {
            items: vec![UserInput::Text {
                text: first_user_message.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1560,6 +1685,7 @@ async fn manual_compact_twice_preserves_latest_user_messages() {
            items: vec![UserInput::Text {
                text: second_user_message.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1573,6 +1699,7 @@ async fn manual_compact_twice_preserves_latest_user_messages() {
            items: vec![UserInput::Text {
                text: final_user_message.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1752,6 +1879,7 @@ async fn auto_compact_allows_multiple_attempts_when_interleaved_with_other_turn_
        codex
            .submit(Op::UserInput {
                items: vec![UserInput::Text { text: user.into() }],
+                final_output_json_schema: None,
            })
            .await
            .unwrap();
@@ -1864,6 +1992,7 @@ async fn auto_compact_triggers_after_function_call_over_95_percent_usage() {
            items: vec![UserInput::Text {
                text: FUNCTION_CALL_LIMIT_MSG.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1875,6 +2004,7 @@ async fn auto_compact_triggers_after_function_call_over_95_percent_usage() {
            items: vec![UserInput::Text {
                text: follow_up_user.into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1989,6 +2119,7 @@ async fn auto_compact_counts_encrypted_reasoning_before_last_user() {
        codex
            .submit(Op::UserInput {
                items: vec![UserInput::Text { text: user.into() }],
+                final_output_json_schema: None,
            })
            .await
            .unwrap();
@@ -74,6 +74,7 @@ async fn remote_compact_replaces_history_for_followups() -> Result<()> {
            items: vec![UserInput::Text {
                text: "hello remote compact".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -86,6 +87,7 @@ async fn remote_compact_replaces_history_for_followups() -> Result<()> {
            items: vec![UserInput::Text {
                text: "after compact".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -191,6 +193,7 @@ async fn remote_compact_runs_automatically() -> Result<()> {
            items: vec![UserInput::Text {
                text: "hello remote compact".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    let message = wait_for_event_match(&codex, |ev| match ev {
@@ -263,6 +266,7 @@ async fn remote_compact_persists_replacement_history_in_rollout() -> Result<()>
            items: vec![UserInput::Text {
                text: "needs compaction".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -884,6 +884,7 @@ async fn user_turn(conversation: &Arc<CodexConversation>, text: &str) {
    conversation
        .submit(Op::UserInput {
            items: vec![UserInput::Text { text: text.into() }],
+            final_output_json_schema: None,
        })
        .await
        .expect("submit user turn");
@@ -97,7 +97,7 @@ async fn execpolicy_blocks_shell_invocation() -> Result<()> {

    assert!(
        end.aggregated_output
-            .contains("execpolicy forbids this command"),
+            .contains("policy forbids commands starting with `echo`"),
        "unexpected output: {}",
        end.aggregated_output
    );
@@ -74,6 +74,7 @@ async fn fork_conversation_twice_drops_to_first_message() {
                items: vec![UserInput::Text {
                    text: text.to_string(),
                }],
+                final_output_json_schema: None,
            })
            .await
            .unwrap();
@@ -43,6 +43,7 @@ async fn user_message_item_is_emitted() -> anyhow::Result<()> {
            items: (vec![UserInput::Text {
                text: "please inspect sample.txt".into(),
            }]),
+            final_output_json_schema: None,
        })
        .await?;

@@ -99,6 +100,7 @@ async fn assistant_message_item_is_emitted() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "please summarize results".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -155,6 +157,7 @@ async fn reasoning_item_is_emitted() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "explain your reasoning".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -213,6 +216,7 @@ async fn web_search_item_is_emitted() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "find the weather".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -265,6 +269,7 @@ async fn agent_message_content_delta_has_item_metadata() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "please stream text".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -330,6 +335,7 @@ async fn reasoning_content_delta_has_item_metadata() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "reason through it".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -387,6 +393,7 @@ async fn reasoning_raw_content_delta_respects_flag() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "show raw reasoning".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -37,6 +37,7 @@ mod list_models;
 mod live_cli;
 mod model_overrides;
 mod model_tools;
+mod models_etag_responses;
 mod otel;
 mod prompt_caching;
 mod quota_exceeded;
@@ -0,0 +1,139 @@
+#![cfg(not(target_os = "windows"))]
+
+use std::sync::Arc;
+
+use anyhow::Result;
+use codex_core::CodexAuth;
+use codex_core::features::Feature;
+use codex_core::protocol::AskForApproval;
+use codex_core::protocol::EventMsg;
+use codex_core::protocol::Op;
+use codex_core::protocol::SandboxPolicy;
+use codex_protocol::config_types::ReasoningSummary;
+use codex_protocol::openai_models::ModelsResponse;
+use codex_protocol::user_input::UserInput;
+use core_test_support::responses;
+use core_test_support::responses::ev_assistant_message;
+use core_test_support::responses::ev_completed;
+use core_test_support::responses::ev_local_shell_call;
+use core_test_support::responses::ev_response_created;
+use core_test_support::responses::sse;
+use core_test_support::responses::sse_response;
+use core_test_support::skip_if_no_network;
+use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
+use pretty_assertions::assert_eq;
+use wiremock::MockServer;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn refresh_models_on_models_etag_mismatch_and_avoid_duplicate_models_fetch() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    const ETAG_1: &str = "\"models-etag-1\"";
+    const ETAG_2: &str = "\"models-etag-2\"";
+    const CALL_ID: &str = "local-shell-call-1";
+
+    let server = MockServer::start().await;
+
+    // 1) On spawn, Codex fetches /models and stores the ETag.
+    let spawn_models_mock = responses::mount_models_once_with_etag(
+        &server,
+        ModelsResponse { models: Vec::new() },
+        ETAG_1,
+    )
+    .await;
+
+    let auth = CodexAuth::create_dummy_chatgpt_auth_for_testing();
+    let mut builder = test_codex()
+        .with_auth(auth)
+        .with_model("gpt-5")
+        .with_config(|config| {
+            config.features.enable(Feature::RemoteModels);
+            // Keep this test deterministic: no request retries, and a small stream retry budget.
+            config.model_provider.request_max_retries = Some(0);
+            config.model_provider.stream_max_retries = Some(1);
+        });
+
+    let test = builder.build(&server).await?;
+    let codex = Arc::clone(&test.codex);
+    let cwd = Arc::clone(&test.cwd);
+    let session_model = test.session_configured.model.clone();
+
+    assert_eq!(spawn_models_mock.requests().len(), 1);
+    assert_eq!(spawn_models_mock.single_request_path(), "/v1/models");
+
+    // 2) If the server sends a different X-Models-Etag on /responses, Codex refreshes /models.
+    let refresh_models_mock = responses::mount_models_once_with_etag(
+        &server,
+        ModelsResponse { models: Vec::new() },
+        ETAG_2,
+    )
+    .await;
+
+    // First /responses request (user message) succeeds and returns a tool call.
+    // It also includes a mismatched X-Models-Etag, which should trigger a /models refresh.
+    let first_response_body = sse(vec![
+        ev_response_created("resp-1"),
+        ev_local_shell_call(CALL_ID, "completed", vec!["/bin/echo", "etag ok"]),
+        ev_completed("resp-1"),
+    ]);
+    responses::mount_response_once(
+        &server,
+        sse_response(first_response_body).insert_header("X-Models-Etag", ETAG_2),
+    )
+    .await;
+
+    // Second /responses request (tool output) includes the same X-Models-Etag; Codex should not
+    // refetch /models again after it has already refreshed the catalog.
+    let completion_response_body = sse(vec![
+        ev_response_created("resp-2"),
+        ev_assistant_message("msg-1", "done"),
+        ev_completed("resp-2"),
+    ]);
+    let tool_output_mock = responses::mount_response_once(
+        &server,
+        sse_response(completion_response_body).insert_header("X-Models-Etag", ETAG_2),
+    )
+    .await;
+
+    codex
+        .submit(Op::UserTurn {
+            items: vec![UserInput::Text {
+                text: "please run a tool".into(),
+            }],
+            final_output_json_schema: None,
+            cwd: cwd.path().to_path_buf(),
+            approval_policy: AskForApproval::Never,
+            sandbox_policy: SandboxPolicy::DangerFullAccess,
+            model: session_model,
+            effort: None,
+            summary: ReasoningSummary::Auto,
+        })
+        .await?;
+
+    let _ = wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
+
+    // Assert /models was refreshed exactly once after the X-Models-Etag mismatch.
+    assert_eq!(refresh_models_mock.requests().len(), 1);
+    assert_eq!(refresh_models_mock.single_request_path(), "/v1/models");
+    let refresh_req = refresh_models_mock
+        .requests()
+        .into_iter()
+        .next()
+        .expect("one request");
+    // Ensure Codex includes client_version on refresh. (This is a stable signal that we're using the /models client.)
+    assert!(
+        refresh_req
+            .url
+            .query_pairs()
+            .any(|(k, _)| k == "client_version"),
+        "expected /models refresh to include client_version query param"
+    );
+
+    // Assert the tool output /responses request succeeded and did not trigger another /models fetch.
+    let tool_req = tool_output_mock.single_request();
+    let _ = tool_req.function_call_output(CALL_ID);
+    assert_eq!(refresh_models_mock.requests().len(), 1);
+
+    Ok(())
+}
@@ -46,6 +46,7 @@ async fn responses_api_emits_api_request_event() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -87,6 +88,7 @@ async fn process_sse_emits_tracing_for_output_item() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -125,6 +127,7 @@ async fn process_sse_emits_failed_event_on_parse_error() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -164,6 +167,7 @@ async fn process_sse_records_failed_event_when_stream_closes_without_completed()
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -223,6 +227,7 @@ async fn process_sse_failed_event_records_response_error_message() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -280,6 +285,7 @@ async fn process_sse_failed_event_logs_parse_error() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -324,6 +330,7 @@ async fn process_sse_failed_event_logs_missing_error() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -377,6 +384,7 @@ async fn process_sse_failed_event_logs_response_completed_parse_error() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -427,6 +435,7 @@ async fn process_sse_emits_completed_telemetry() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -494,6 +503,7 @@ async fn handle_responses_span_records_response_kind_and_tool_name() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -558,6 +568,7 @@ async fn record_responses_sets_span_fields_for_response_events() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -637,6 +648,7 @@ async fn handle_response_item_records_tool_result_for_custom_tool_call() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -704,6 +716,7 @@ async fn handle_response_item_records_tool_result_for_function_call() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -781,6 +794,7 @@ async fn handle_response_item_records_tool_result_for_local_shell_missing_ids()
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -842,6 +856,7 @@ async fn handle_response_item_records_tool_result_for_local_shell_call() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -946,6 +961,7 @@ async fn handle_container_exec_autoapprove_from_config_records_tool_decision() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -994,6 +1010,7 @@ async fn handle_container_exec_user_approved_records_tool_decision() {
            items: vec![UserInput::Text {
                text: "approved".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1052,6 +1069,7 @@ async fn handle_container_exec_user_approved_for_session_records_tool_decision()
            items: vec![UserInput::Text {
                text: "persist".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1110,6 +1128,7 @@ async fn handle_sandbox_error_user_approves_retry_records_tool_decision() {
            items: vec![UserInput::Text {
                text: "retry".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1168,6 +1187,7 @@ async fn handle_container_exec_user_denies_records_tool_decision() {
            items: vec![UserInput::Text {
                text: "deny".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1226,6 +1246,7 @@ async fn handle_sandbox_error_user_approves_for_session_records_tool_decision()
            items: vec![UserInput::Text {
                text: "persist".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -1285,6 +1306,7 @@ async fn handle_sandbox_error_user_denies_records_tool_decision() {
            items: vec![UserInput::Text {
                text: "deny".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -102,6 +102,7 @@ async fn prompt_tools_are_consistent_across_requests() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello 1".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -111,6 +112,7 @@ async fn prompt_tools_are_consistent_across_requests() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello 2".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -175,6 +177,7 @@ async fn codex_mini_latest_tools() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello 1".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -184,6 +187,7 @@ async fn codex_mini_latest_tools() -> anyhow::Result<()> {
            items: vec![UserInput::Text {
                text: "hello 2".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -238,6 +242,7 @@ async fn prefixes_context_and_instructions_once_and_consistently_across_requests
            items: vec![UserInput::Text {
                text: "hello 1".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -247,6 +252,7 @@ async fn prefixes_context_and_instructions_once_and_consistently_across_requests
            items: vec![UserInput::Text {
                text: "hello 2".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -307,6 +313,7 @@ async fn overrides_turn_context_but_keeps_cached_prefix_and_key_constant() -> an
            items: vec![UserInput::Text {
                text: "hello 1".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -334,6 +341,7 @@ async fn overrides_turn_context_but_keeps_cached_prefix_and_key_constant() -> an
            items: vec![UserInput::Text {
                text: "hello 2".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -412,6 +420,7 @@ async fn override_before_first_turn_emits_environment_context() -> anyhow::Resul
            items: vec![UserInput::Text {
                text: "first message".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -504,6 +513,7 @@ async fn per_turn_overrides_keep_cached_prefix_and_key_constant() -> anyhow::Res
            items: vec![UserInput::Text {
                text: "hello 1".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -44,6 +44,7 @@ async fn quota_exceeded_emits_single_error_event() -> Result<()> {
            items: vec![UserInput::Text {
                text: "quota?".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -89,7 +89,6 @@ async fn remote_models_remote_model_uses_unified_exec() -> Result<()> {
        &server,
        ModelsResponse {
            models: vec![remote_model],
-            etag: String::new(),
        },
    )
    .await;
@@ -226,7 +225,6 @@ async fn remote_models_apply_remote_base_instructions() -> Result<()> {
        &server,
        ModelsResponse {
            models: vec![remote_model],
-            etag: String::new(),
        },
    )
    .await;
@@ -304,7 +302,6 @@ async fn remote_models_preserve_builtin_presets() -> Result<()> {
        &server,
        ModelsResponse {
            models: vec![remote_model.clone()],
-            etag: String::new(),
        },
    )
    .await;
@@ -324,7 +321,7 @@ async fn remote_models_preserve_builtin_presets() -> Result<()> {
    );

    manager
-        .refresh_available_models(&config)
+        .refresh_available_models_with_cache(&config)
        .await
        .expect("refresh succeeds");

@@ -362,7 +359,6 @@ async fn remote_models_hide_picker_only_models() -> Result<()> {
        &server,
        ModelsResponse {
            models: vec![remote_model],
-            etag: String::new(),
        },
    )
    .await;
@@ -37,6 +37,7 @@ async fn resume_includes_initial_messages_from_rollout_events() -> Result<()> {
            items: vec![UserInput::Text {
                text: "Record some messages".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -89,6 +90,7 @@ async fn resume_includes_initial_messages_from_reasoning_events() -> Result<()>
            items: vec![UserInput::Text {
                text: "Record reasoning messages".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;

@@ -665,6 +665,7 @@ async fn review_history_surfaces_in_parent_session() {
            items: vec![UserInput::Text {
                text: followup.clone(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -709,6 +710,105 @@ async fn review_history_surfaces_in_parent_session() {
    server.verify().await;
 }

+/// `/review` should use the session's current cwd (including runtime overrides)
+/// when resolving base-branch review prompts (merge-base computation).
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn review_uses_overridden_cwd_for_base_branch_merge_base() {
+    skip_if_no_network!();
+
+    let sse_raw = r#"[{"type":"response.completed", "response": {"id": "__ID__"}}]"#;
+    let server = start_responses_server_with_sse(sse_raw, 1).await;
+
+    let initial_cwd = TempDir::new().unwrap();
+
+    let repo_dir = TempDir::new().unwrap();
+    let repo_path = repo_dir.path();
+
+    fn run_git(repo_path: &std::path::Path, args: &[&str]) {
+        let output = std::process::Command::new("git")
+            .arg("-C")
+            .arg(repo_path)
+            .args(args)
+            .output()
+            .expect("spawn git");
+        assert!(
+            output.status.success(),
+            "git {:?} failed: stdout={:?} stderr={:?}",
+            args,
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    run_git(repo_path, &["init", "-b", "main"]);
+    run_git(repo_path, &["config", "user.email", "test@example.com"]);
+    run_git(repo_path, &["config", "user.name", "Test User"]);
+    std::fs::write(repo_path.join("file.txt"), "hello\n").unwrap();
+    run_git(repo_path, &["add", "."]);
+    run_git(repo_path, &["commit", "-m", "initial"]);
+
+    let head_sha = std::process::Command::new("git")
+        .arg("-C")
+        .arg(repo_path)
+        .args(["rev-parse", "HEAD"])
+        .output()
+        .expect("rev-parse HEAD");
+    assert!(head_sha.status.success());
+    let head_sha = String::from_utf8(head_sha.stdout)
+        .expect("utf8 sha")
+        .trim()
+        .to_string();
+
+    let codex_home = TempDir::new().unwrap();
+    let codex = new_conversation_for_server(&server, &codex_home, |config| {
+        config.cwd = initial_cwd.path().to_path_buf();
+    })
+    .await;
+
+    codex
+        .submit(Op::OverrideTurnContext {
+            cwd: Some(repo_path.to_path_buf()),
+            approval_policy: None,
+            sandbox_policy: None,
+            model: None,
+            effort: None,
+            summary: None,
+        })
+        .await
+        .unwrap();
+
+    codex
+        .submit(Op::Review {
+            review_request: ReviewRequest {
+                target: ReviewTarget::BaseBranch {
+                    branch: "main".to_string(),
+                },
+                user_facing_hint: None,
+            },
+        })
+        .await
+        .unwrap();
+
+    let _entered = wait_for_event(&codex, |ev| matches!(ev, EventMsg::EnteredReviewMode(_))).await;
+    let _complete = wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
+
+    let requests = get_responses_requests(&server).await;
+    assert_eq!(requests.len(), 1);
+    let body = requests[0].body_json::<serde_json::Value>().unwrap();
+    let input = body["input"].as_array().expect("input array");
+
+    let saw_merge_base_sha = input
+        .iter()
+        .filter_map(|msg| msg["content"][0]["text"].as_str())
+        .any(|text| text.contains(&head_sha));
+    assert!(
+        saw_merge_base_sha,
+        "expected review prompt to include merge-base sha {head_sha}"
+    );
+
+    server.verify().await;
+}
+
 /// Start a mock Responses API server and mount the given SSE stream body.
 async fn start_responses_server_with_sse(sse_raw: &str, expected_requests: usize) -> MockServer {
    let server = MockServer::start().await;
@@ -89,6 +89,7 @@ async fn continue_after_stream_error() {
            items: vec![UserInput::Text {
                text: "first message".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -106,6 +107,7 @@ async fn continue_after_stream_error() {
            items: vec![UserInput::Text {
                text: "follow up".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -96,6 +96,7 @@ async fn retries_on_early_close() {
            items: vec![UserInput::Text {
                text: "hello".into(),
            }],
+            final_output_json_schema: None,
        })
        .await
        .unwrap();
@@ -61,6 +61,7 @@ echo -n "${@: -1}" > $(dirname "${0}")/notify.txt"#,
            items: vec![UserInput::Text {
                text: "hello world".into(),
            }],
+            final_output_json_schema: None,
        })
        .await?;
    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
@@ -70,7 +70,9 @@ Response: `{ conversationId, model, reasoningEffort?, rolloutPath }`
 Send input to the active turn:

 - `sendUserMessage` → enqueue items to the conversation
- `sendUserTurn` → structured turn with explicit `cwd`, `approvalPolicy`, `sandboxPolicy`, `model`, optional `effort`, and `summary`
+- `sendUserTurn` → structured turn with explicit `cwd`, `approvalPolicy`, `sandboxPolicy`, `model`, optional `effort`, `summary`, and optional `outputSchema` (JSON Schema for the final assistant message)
+
+For v2 threads, `turn/start` also accepts `outputSchema` to constrain the final assistant message for that turn.

 Interrupt a running turn: `interruptConversation`.

@@ -11,11 +11,17 @@ pub struct Cli {
    pub command: Option<Command>,

    /// Optional image(s) to attach to the initial prompt.
-    #[arg(long = "image", short = 'i', value_name = "FILE", value_delimiter = ',', num_args = 1..)]
+    #[arg(
+        long = "image",
+        short = 'i',
+        value_name = "FILE",
+        value_delimiter = ',',
+        num_args = 1..
+    )]
    pub images: Vec<PathBuf>,

    /// Model the agent should use.
-    #[arg(long, short = 'm')]
+    #[arg(long, short = 'm', global = true)]
    pub model: Option<String>,

    /// Use open-source provider.
@@ -37,7 +43,7 @@ pub struct Cli {
    pub config_profile: Option<String>,

    /// Convenience alias for low-friction sandboxed automatic execution (-a on-request, --sandbox workspace-write).
-    #[arg(long = "full-auto", default_value_t = false)]
+    #[arg(long = "full-auto", default_value_t = false, global = true)]
    pub full_auto: bool,

    /// Skip all confirmation prompts and execute commands without sandboxing.
@@ -46,6 +52,7 @@ pub struct Cli {
        long = "dangerously-bypass-approvals-and-sandbox",
        alias = "yolo",
        default_value_t = false,
+        global = true,
        conflicts_with = "full_auto"
    )]
    pub dangerously_bypass_approvals_and_sandbox: bool,
@@ -55,7 +62,7 @@ pub struct Cli {
    pub cwd: Option<PathBuf>,

    /// Allow running Codex outside a Git repository.
-    #[arg(long = "skip-git-repo-check", default_value_t = false)]
+    #[arg(long = "skip-git-repo-check", global = true, default_value_t = false)]
    pub skip_git_repo_check: bool,

    /// Additional directories that should be writable alongside the primary workspace.
@@ -74,7 +81,12 @@ pub struct Cli {
    pub color: Color,

    /// Print events to stdout as JSONL.
-    #[arg(long = "json", alias = "experimental-json", default_value_t = false)]
+    #[arg(
+        long = "json",
+        alias = "experimental-json",
+        default_value_t = false,
+        global = true
+    )]
    pub json: bool,

    /// Specifies file where the last message from the agent should be written.
@@ -107,6 +119,16 @@ pub struct ResumeArgs {
    #[arg(long = "last", default_value_t = false)]
    pub last: bool,

+    /// Optional image(s) to attach to the prompt sent after resuming.
+    #[arg(
+        long = "image",
+        short = 'i',
+        value_name = "FILE",
+        value_delimiter = ',',
+        num_args = 1
+    )]
+    pub images: Vec<PathBuf>,
+
    /// Prompt to send after resuming the session. If `-` is used, read from stdin.
    #[arg(value_name = "PROMPT", value_hint = clap::ValueHint::Other)]
    pub prompt: Option<String>,
@@ -335,6 +335,7 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
            let prompt_text = resolve_prompt(prompt_arg);
            let mut items: Vec<UserInput> = imgs
                .into_iter()
+                .chain(args.images.into_iter())
                .map(|path| UserInput::LocalImage { path })
                .collect();
            items.push(UserInput::Text {
@@ -1,6 +1,7 @@
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 use anyhow::Context;
 use core_test_support::test_codex_exec::test_codex_exec;
+use pretty_assertions::assert_eq;
 use serde_json::Value;
 use std::path::Path;
 use std::string::ToString;
@@ -69,6 +70,39 @@ fn extract_conversation_id(path: &std::path::Path) -> String {
        .to_string()
 }

+fn last_user_image_count(path: &std::path::Path) -> usize {
+    let content = std::fs::read_to_string(path).unwrap_or_default();
+    let mut last_count = 0;
+    for line in content.lines() {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let Ok(item): Result<Value, _> = serde_json::from_str(line) else {
+            continue;
+        };
+        if item.get("type").and_then(|t| t.as_str()) != Some("response_item") {
+            continue;
+        }
+        let Some(payload) = item.get("payload") else {
+            continue;
+        };
+        if payload.get("type").and_then(|t| t.as_str()) != Some("message") {
+            continue;
+        }
+        if payload.get("role").and_then(|r| r.as_str()) != Some("user") {
+            continue;
+        }
+        let Some(content_items) = payload.get("content").and_then(|v| v.as_array()) else {
+            continue;
+        };
+        last_count = content_items
+            .iter()
+            .filter(|entry| entry.get("type").and_then(|t| t.as_str()) == Some("input_image"))
+            .count();
+    }
+    last_count
+}
+
 #[test]
 fn exec_resume_last_appends_to_existing_file() -> anyhow::Result<()> {
    let test = test_codex_exec();
@@ -177,6 +211,41 @@ fn exec_resume_last_accepts_prompt_after_flag_in_json_mode() -> anyhow::Result<(
    Ok(())
 }

+#[test]
+fn exec_resume_accepts_global_flags_after_subcommand() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let fixture =
+        Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/cli_responses_fixture.sse");
+
+    // Seed a session.
+    test.cmd()
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("echo seed-resume-session")
+        .assert()
+        .success();
+
+    // Resume while passing global flags after the subcommand to ensure clap accepts them.
+    test.cmd()
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("resume")
+        .arg("--last")
+        .arg("--json")
+        .arg("--model")
+        .arg("gpt-5.2-codex")
+        .arg("--config")
+        .arg("reasoning_level=xhigh")
+        .arg("--dangerously-bypass-approvals-and-sandbox")
+        .arg("--skip-git-repo-check")
+        .arg("echo resume-with-global-flags-after-subcommand")
+        .assert()
+        .success();
+
+    Ok(())
+}
+
 #[test]
 fn exec_resume_by_id_appends_to_existing_file() -> anyhow::Result<()> {
    let test = test_codex_exec();
@@ -309,3 +378,64 @@ fn exec_resume_preserves_cli_configuration_overrides() -> anyhow::Result<()> {
    assert!(content.contains(&marker2));
    Ok(())
 }
+
+#[test]
+fn exec_resume_accepts_images_after_subcommand() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let fixture =
+        Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/cli_responses_fixture.sse");
+
+    let marker = format!("resume-image-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    test.cmd()
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    let image_path = test.cwd_path().join("resume_image.png");
+    let image_path_2 = test.cwd_path().join("resume_image_2.png");
+    let image_bytes: &[u8] = &[
+        0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44,
+        0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1F,
+        0x15, 0xC4, 0x89, 0x00, 0x00, 0x00, 0x0A, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9C, 0x63, 0x00,
+        0x01, 0x00, 0x00, 0x05, 0x00, 0x01, 0x0D, 0x0A, 0x2D, 0xB4, 0x00, 0x00, 0x00, 0x00, 0x49,
+        0x45, 0x4E, 0x44, 0xAE, 0x42, 0x60, 0x82,
+    ];
+    std::fs::write(&image_path, image_bytes)?;
+    std::fs::write(&image_path_2, image_bytes)?;
+
+    let marker2 = format!("resume-image-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+    test.cmd()
+        .env("CODEX_RS_SSE_FIXTURE", &fixture)
+        .env("OPENAI_BASE_URL", "http://unused.local")
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(env!("CARGO_MANIFEST_DIR"))
+        .arg("resume")
+        .arg("--last")
+        .arg("--image")
+        .arg(&image_path)
+        .arg("--image")
+        .arg(&image_path_2)
+        .arg(&prompt2)
+        .assert()
+        .success();
+
+    let sessions_dir = test.home_path().join("sessions");
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no session file found after resume with images");
+    let image_count = last_user_image_count(&resumed_path);
+    assert_eq!(
+        image_count, 2,
+        "resume prompt should include both attached images"
+    );
+
+    Ok(())
+}
@@ -1,52 +1,65 @@
 # codex-execpolicy

 ## Overview
- Policy engine and CLI built around `prefix_rule(pattern=[...], decision?, match?, not_match?)`.
+
+- Policy engine and CLI built around `prefix_rule(pattern=[...], decision?, justification?, match?, not_match?)`.
 - This release covers the prefix-rule subset of the execpolicy language; a richer language will follow.
 - Tokens are matched in order; any `pattern` element may be a list to denote alternatives. `decision` defaults to `allow`; valid values: `allow`, `prompt`, `forbidden`.
+- `justification` is an optional human-readable rationale for why a rule exists. It can be provided for any `decision` and may be surfaced in different contexts (for example, in approval prompts or rejection messages). When `decision = "forbidden"` is used, include a recommended alternative in the `justification`, when appropriate (e.g., ``"Use `jj` instead of `git`."``).
 - `match` / `not_match` supply example invocations that are validated at load time (think of them as unit tests); examples can be token arrays or strings (strings are tokenized with `shlex`).
 - The CLI always prints the JSON serialization of the evaluation result.
 - The legacy rule matcher lives in `codex-execpolicy-legacy`.

 ## Policy shapes
+
 - Prefix rules use Starlark syntax:
+
 ```starlark
 prefix_rule(
    pattern = ["cmd", ["alt1", "alt2"]], # ordered tokens; list entries denote alternatives
    decision = "prompt",                 # allow | prompt | forbidden; defaults to allow
+    justification = "explain why this rule exists",
    match = [["cmd", "alt1"], "cmd alt2"],           # examples that must match this rule
    not_match = [["cmd", "oops"], "cmd alt3"],       # examples that must not match this rule
 )
 ```

 ## CLI
+
 - From the Codex CLI, run `codex execpolicy check` subcommand with one or more policy files (for example `src/default.rules`) to check a command:
+
 ```bash
 codex execpolicy check --rules path/to/policy.rules git status
 ```
+
 - Pass multiple `--rules` flags to merge rules, evaluated in the order provided, and use `--pretty` for formatted JSON.
 - You can also run the standalone dev binary directly during development:
+
 ```bash
 cargo run -p codex-execpolicy -- check --rules path/to/policy.rules git status
 ```
+
 - Example outcomes:
  - Match: `{"matchedRules":[{...}],"decision":"allow"}`
  - No match: `{"matchedRules":[]}`

 ## Response shape
+
 ```json
 {
  "matchedRules": [
    {
      "prefixRuleMatch": {
        "matchedPrefix": ["<token>", "..."],
-        "decision": "allow|prompt|forbidden"
+        "decision": "allow|prompt|forbidden",
+        "justification": "..."
      }
    }
  ],
  "decision": "allow|prompt|forbidden"
 }
 ```
+
 - When no rules match, `matchedRules` is an empty array and `decision` is omitted.
 - `matchedRules` lists every rule whose prefix matched the command; `matchedPrefix` is the exact prefix that matched.
 - The effective `decision` is the strictest severity across all matches (`forbidden` > `prompt` > `allow`).
@@ -4,6 +4,7 @@
 prefix_rule(
    pattern = ["git", "reset", "--hard"],
    decision = "forbidden",
+    justification = "destructive operation",
    match = [
        ["git", "reset", "--hard"],
    ],
@@ -11,6 +11,8 @@ pub enum Error {
    InvalidPattern(String),
    #[error("invalid example: {0}")]
    InvalidExample(String),
+    #[error("invalid rule: {0}")]
+    InvalidRule(String),
    #[error(
        "expected every example to match at least one rule. rules: {rules:?}; unmatched examples: \
         {examples:?}"
@@ -212,6 +212,7 @@ fn policy_builtins(builder: &mut GlobalsBuilder) {
        decision: Option<&'v str>,
        r#match: Option<UnpackList<Value<'v>>>,
        not_match: Option<UnpackList<Value<'v>>>,
+        justification: Option<&'v str>,
        eval: &mut Evaluator<'v, '_, '_>,
    ) -> anyhow::Result<NoneType> {
        let decision = match decision {
@@ -219,6 +220,14 @@ fn policy_builtins(builder: &mut GlobalsBuilder) {
            None => Decision::Allow,
        };

+        let justification = match justification {
+            Some(raw) if raw.trim().is_empty() => {
+                return Err(Error::InvalidRule("justification cannot be empty".to_string()).into());
+            }
+            Some(raw) => Some(raw.to_string()),
+            None => None,
+        };
+
        let pattern_tokens = parse_pattern(pattern)?;

        let matches: Vec<Vec<String>> =
@@ -246,6 +255,7 @@ fn policy_builtins(builder: &mut GlobalsBuilder) {
                        rest: rest.clone(),
                    },
                    decision,
+                    justification: justification.clone(),
                }) as RuleRef
            })
            .collect();
@@ -46,6 +46,7 @@ impl Policy {
                    .into(),
            },
            decision,
+            justification: None,
        });

        self.rules_by_program.insert(first_token.clone(), rule);
@@ -63,6 +63,12 @@ pub enum RuleMatch {
        #[serde(rename = "matchedPrefix")]
        matched_prefix: Vec<String>,
        decision: Decision,
+        /// Optional rationale for why this rule exists.
+        ///
+        /// This can be supplied for any decision and may be surfaced in different contexts
+        /// (e.g., prompt reasons or rejection messages).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        justification: Option<String>,
    },
    HeuristicsRuleMatch {
        command: Vec<String>,
@@ -83,6 +89,7 @@ impl RuleMatch {
 pub struct PrefixRule {
    pub pattern: PrefixPattern,
    pub decision: Decision,
+    pub justification: Option<String>,
 }

 pub trait Rule: Any + Debug + Send + Sync {
@@ -104,6 +111,7 @@ impl Rule for PrefixRule {
            .map(|matched_prefix| RuleMatch::PrefixRuleMatch {
                matched_prefix,
                decision: self.decision,
+                justification: self.justification.clone(),
            })
    }
 }
@@ -64,6 +64,7 @@ prefix_rule(
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["git", "status"]),
                decision: Decision::Allow,
+                justification: None,
            }],
        },
        evaluation
@@ -71,6 +72,84 @@ prefix_rule(
    Ok(())
 }

+#[test]
+fn justification_is_attached_to_forbidden_matches() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["rm"],
+    decision = "forbidden",
+    justification = "destructive command",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let evaluation = policy.check(
+        &tokens(&["rm", "-rf", "/some/important/folder"]),
+        &allow_all,
+    );
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Forbidden,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["rm"]),
+                decision: Decision::Forbidden,
+                justification: Some("destructive command".to_string()),
+            }],
+        },
+        evaluation
+    );
+    Ok(())
+}
+
+#[test]
+fn justification_can_be_used_with_allow_decision() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["ls"],
+    decision = "allow",
+    justification = "safe and commonly used",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let evaluation = policy.check(&tokens(&["ls", "-l"]), &prompt_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["ls"]),
+                decision: Decision::Allow,
+                justification: Some("safe and commonly used".to_string()),
+            }],
+        },
+        evaluation
+    );
+    Ok(())
+}
+
+#[test]
+fn justification_cannot_be_empty() {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["ls"],
+    decision = "prompt",
+    justification = "   ",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    let err = parser
+        .parse("test.rules", policy_src)
+        .expect_err("expected parse error");
+    assert!(
+        err.to_string()
+            .contains("invalid rule: justification cannot be empty")
+    );
+}
+
 #[test]
 fn add_prefix_rule_extends_policy() -> Result<()> {
    let mut policy = Policy::empty();
@@ -84,17 +163,19 @@ fn add_prefix_rule_extends_policy() -> Result<()> {
                rest: vec![PatternToken::Single(String::from("-l"))].into(),
            },
            decision: Decision::Prompt,
+            justification: None,
        })],
        rules
    );

-    let evaluation = policy.check(&tokens(&["ls", "-l", "/tmp"]), &allow_all);
+    let evaluation = policy.check(&tokens(&["ls", "-l", "/some/important/folder"]), &allow_all);
    assert_eq!(
        Evaluation {
            decision: Decision::Prompt,
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["ls", "-l"]),
                decision: Decision::Prompt,
+                justification: None,
            }],
        },
        evaluation
@@ -142,6 +223,7 @@ prefix_rule(
                    rest: Vec::<PatternToken>::new().into(),
                },
                decision: Decision::Prompt,
+                justification: None,
            }),
            RuleSnapshot::Prefix(PrefixRule {
                pattern: PrefixPattern {
@@ -149,6 +231,7 @@ prefix_rule(
                    rest: vec![PatternToken::Single("commit".to_string())].into(),
                },
                decision: Decision::Forbidden,
+                justification: None,
            }),
        ],
        git_rules
@@ -161,6 +244,7 @@ prefix_rule(
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["git"]),
                decision: Decision::Prompt,
+                justification: None,
            }],
        },
        status_eval
@@ -174,10 +258,12 @@ prefix_rule(
                RuleMatch::PrefixRuleMatch {
                    matched_prefix: tokens(&["git"]),
                    decision: Decision::Prompt,
+                    justification: None,
                },
                RuleMatch::PrefixRuleMatch {
                    matched_prefix: tokens(&["git", "commit"]),
                    decision: Decision::Forbidden,
+                    justification: None,
                },
            ],
        },
@@ -211,6 +297,7 @@ prefix_rule(
                rest: vec![PatternToken::Alts(vec!["-c".to_string(), "-l".to_string()])].into(),
            },
            decision: Decision::Allow,
+            justification: None,
        })],
        bash_rules
    );
@@ -221,6 +308,7 @@ prefix_rule(
                rest: vec![PatternToken::Alts(vec!["-c".to_string(), "-l".to_string()])].into(),
            },
            decision: Decision::Allow,
+            justification: None,
        })],
        sh_rules
    );
@@ -232,6 +320,7 @@ prefix_rule(
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["bash", "-c"]),
                decision: Decision::Allow,
+                justification: None,
            }],
        },
        bash_eval
@@ -244,6 +333,7 @@ prefix_rule(
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["sh", "-l"]),
                decision: Decision::Allow,
+                justification: None,
            }],
        },
        sh_eval
@@ -277,6 +367,7 @@ prefix_rule(
                .into(),
            },
            decision: Decision::Allow,
+            justification: None,
        })],
        rules
    );
@@ -288,6 +379,7 @@ prefix_rule(
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["npm", "i", "--legacy-peer-deps"]),
                decision: Decision::Allow,
+                justification: None,
            }],
        },
        npm_i
@@ -303,6 +395,7 @@ prefix_rule(
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["npm", "install", "--no-save"]),
                decision: Decision::Allow,
+                justification: None,
            }],
        },
        npm_install
@@ -332,6 +425,7 @@ prefix_rule(
            matched_rules: vec![RuleMatch::PrefixRuleMatch {
                matched_prefix: tokens(&["git", "status"]),
                decision: Decision::Allow,
+                justification: None,
            }],
        },
        match_eval
@@ -378,10 +472,12 @@ prefix_rule(
                RuleMatch::PrefixRuleMatch {
                    matched_prefix: tokens(&["git"]),
                    decision: Decision::Prompt,
+                    justification: None,
                },
                RuleMatch::PrefixRuleMatch {
                    matched_prefix: tokens(&["git", "commit"]),
                    decision: Decision::Forbidden,
+                    justification: None,
                },
            ],
        },
@@ -419,14 +515,17 @@ prefix_rule(
                RuleMatch::PrefixRuleMatch {
                    matched_prefix: tokens(&["git"]),
                    decision: Decision::Prompt,
+                    justification: None,
                },
                RuleMatch::PrefixRuleMatch {
                    matched_prefix: tokens(&["git"]),
                    decision: Decision::Prompt,
+                    justification: None,
                },
                RuleMatch::PrefixRuleMatch {
                    matched_prefix: tokens(&["git", "commit"]),
                    decision: Decision::Forbidden,
+                    justification: None,
                },
            ],
        },
@@ -8,6 +8,7 @@ license.workspace = true
 anyhow = { workspace = true }
 codex-protocol = { workspace = true }
 sentry = { version = "0.46" }
+tracing = { workspace = true }
 tracing-subscriber = { workspace = true }

 [dev-dependencies]
@@ -1,4 +1,6 @@
+use std::collections::BTreeMap;
 use std::collections::VecDeque;
+use std::collections::btree_map::Entry;
 use std::fs;
 use std::io::Write;
 use std::io::{self};
@@ -11,12 +13,20 @@ use anyhow::Result;
 use anyhow::anyhow;
 use codex_protocol::ConversationId;
 use codex_protocol::protocol::SessionSource;
+use tracing::Event;
+use tracing::Level;
+use tracing::field::Visit;
+use tracing_subscriber::Layer;
+use tracing_subscriber::filter::Targets;
 use tracing_subscriber::fmt::writer::MakeWriter;
+use tracing_subscriber::registry::LookupSpan;

 const DEFAULT_MAX_BYTES: usize = 4 * 1024 * 1024; // 4 MiB
 const SENTRY_DSN: &str =
    "https://ae32ed50620d7a7792c1ce5df38b3e3e@o33249.ingest.us.sentry.io/4510195390611458";
 const UPLOAD_TIMEOUT_SECS: u64 = 10;
+const FEEDBACK_TAGS_TARGET: &str = "feedback_tags";
+const MAX_FEEDBACK_TAGS: usize = 64;

 #[derive(Clone)]
 pub struct CodexFeedback {
@@ -46,13 +56,50 @@ impl CodexFeedback {
        }
    }

+    /// Returns a [`tracing_subscriber`] layer that captures full-fidelity logs into this feedback
+    /// ring buffer.
+    ///
+    /// This is intended for initialization code so call sites don't have to duplicate the exact
+    /// `fmt::layer()` configuration and filter logic.
+    pub fn logger_layer<S>(&self) -> impl Layer<S> + Send + Sync + 'static
+    where
+        S: tracing::Subscriber + for<'a> LookupSpan<'a>,
+    {
+        tracing_subscriber::fmt::layer()
+            .with_writer(self.make_writer())
+            .with_ansi(false)
+            .with_target(false)
+            // Capture everything, regardless of the caller's `RUST_LOG`, so feedback includes the
+            // full trace when the user uploads a report.
+            .with_filter(Targets::new().with_default(Level::TRACE))
+    }
+
+    /// Returns a [`tracing_subscriber`] layer that collects structured metadata for feedback.
+    ///
+    /// Events with `target: "feedback_tags"` are treated as key/value tags to attach to feedback
+    /// uploads later.
+    pub fn metadata_layer<S>(&self) -> impl Layer<S> + Send + Sync + 'static
+    where
+        S: tracing::Subscriber + for<'a> LookupSpan<'a>,
+    {
+        FeedbackMetadataLayer {
+            inner: self.inner.clone(),
+        }
+        .with_filter(Targets::new().with_target(FEEDBACK_TAGS_TARGET, Level::TRACE))
+    }
+
    pub fn snapshot(&self, session_id: Option<ConversationId>) -> CodexLogSnapshot {
        let bytes = {
            let guard = self.inner.ring.lock().expect("mutex poisoned");
            guard.snapshot_bytes()
        };
+        let tags = {
+            let guard = self.inner.tags.lock().expect("mutex poisoned");
+            guard.clone()
+        };
        CodexLogSnapshot {
            bytes,
+            tags,
            thread_id: session_id
                .map(|id| id.to_string())
                .unwrap_or("no-active-thread-".to_string() + &ConversationId::new().to_string()),
@@ -62,12 +109,14 @@ impl CodexFeedback {

 struct FeedbackInner {
    ring: Mutex<RingBuffer>,
+    tags: Mutex<BTreeMap<String, String>>,
 }

 impl FeedbackInner {
    fn new(max_bytes: usize) -> Self {
        Self {
            ring: Mutex::new(RingBuffer::new(max_bytes)),
+            tags: Mutex::new(BTreeMap::new()),
        }
    }
 }
@@ -152,6 +201,7 @@ impl RingBuffer {

 pub struct CodexLogSnapshot {
    bytes: Vec<u8>,
+    tags: BTreeMap<String, String>,
    pub thread_id: String,
 }

@@ -212,6 +262,22 @@ impl CodexLogSnapshot {
            tags.insert(String::from("reason"), r.to_string());
        }

+        let reserved = [
+            "thread_id",
+            "classification",
+            "cli_version",
+            "session_source",
+            "reason",
+        ];
+        for (key, value) in &self.tags {
+            if reserved.contains(&key.as_str()) {
+                continue;
+            }
+            if let Entry::Vacant(entry) = tags.entry(key.clone()) {
+                entry.insert(value.clone());
+            }
+        }
+
        let level = match classification {
            "bug" | "bad_result" => Level::Error,
            _ => Level::Info,
@@ -280,9 +346,80 @@ fn display_classification(classification: &str) -> String {
    }
 }

+#[derive(Clone)]
+struct FeedbackMetadataLayer {
+    inner: Arc<FeedbackInner>,
+}
+
+impl<S> Layer<S> for FeedbackMetadataLayer
+where
+    S: tracing::Subscriber + for<'a> LookupSpan<'a>,
+{
+    fn on_event(&self, event: &Event<'_>, _ctx: tracing_subscriber::layer::Context<'_, S>) {
+        // This layer is filtered by `Targets`, but keep the guard anyway in case it is used without
+        // the filter.
+        if event.metadata().target() != FEEDBACK_TAGS_TARGET {
+            return;
+        }
+
+        let mut visitor = FeedbackTagsVisitor::default();
+        event.record(&mut visitor);
+        if visitor.tags.is_empty() {
+            return;
+        }
+
+        let mut guard = self.inner.tags.lock().expect("mutex poisoned");
+        for (key, value) in visitor.tags {
+            if guard.len() >= MAX_FEEDBACK_TAGS && !guard.contains_key(&key) {
+                continue;
+            }
+            guard.insert(key, value);
+        }
+    }
+}
+
+#[derive(Default)]
+struct FeedbackTagsVisitor {
+    tags: BTreeMap<String, String>,
+}
+
+impl Visit for FeedbackTagsVisitor {
+    fn record_i64(&mut self, field: &tracing::field::Field, value: i64) {
+        self.tags
+            .insert(field.name().to_string(), value.to_string());
+    }
+
+    fn record_u64(&mut self, field: &tracing::field::Field, value: u64) {
+        self.tags
+            .insert(field.name().to_string(), value.to_string());
+    }
+
+    fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
+        self.tags
+            .insert(field.name().to_string(), value.to_string());
+    }
+
+    fn record_f64(&mut self, field: &tracing::field::Field, value: f64) {
+        self.tags
+            .insert(field.name().to_string(), value.to_string());
+    }
+
+    fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
+        self.tags
+            .insert(field.name().to_string(), value.to_string());
+    }
+
+    fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
+        self.tags
+            .insert(field.name().to_string(), format!("{value:?}"));
+    }
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
+    use tracing_subscriber::layer::SubscriberExt;
+    use tracing_subscriber::util::SubscriberInitExt;

    #[test]
    fn ring_buffer_drops_front_when_full() {
@@ -296,4 +433,18 @@ mod tests {
        // Capacity 8: after writing 10 bytes, we should keep the last 8.
        pretty_assertions::assert_eq!(std::str::from_utf8(snap.as_bytes()).unwrap(), "cdefghij");
    }
+
+    #[test]
+    fn metadata_layer_records_tags_from_feedback_target() {
+        let fb = CodexFeedback::new();
+        let _guard = tracing_subscriber::registry()
+            .with(fb.metadata_layer())
+            .set_default();
+
+        tracing::info!(target: FEEDBACK_TAGS_TARGET, model = "gpt-5", cached = true, "tags");
+
+        let snap = fb.snapshot(None);
+        pretty_assertions::assert_eq!(snap.tags.get("model").map(String::as_str), Some("gpt-5"));
+        pretty_assertions::assert_eq!(snap.tags.get("cached").map(String::as_str), Some("true"));
+    }
 }
@@ -137,26 +137,27 @@ async fn poll_for_token(
    }
 }

-fn print_device_code_prompt(code: &str) {
+fn print_device_code_prompt(code: &str, issuer_base_url: &str) {
    println!(
        "\nWelcome to Codex [v{ANSI_GRAY}{version}{ANSI_RESET}]\n{ANSI_GRAY}OpenAI's command-line coding agent{ANSI_RESET}\n\
 \nFollow these steps to sign in with ChatGPT using device code authorization:\n\
-\n1. Open this link in your browser and sign in to your account\n   {ANSI_BLUE}https://auth.openai.com/codex/device{ANSI_RESET}\n\
+\n1. Open this link in your browser and sign in to your account\n   {ANSI_BLUE}{issuer_base_url}/codex/device{ANSI_RESET}\n\
 \n2. Enter this one-time code {ANSI_GRAY}(expires in 15 minutes){ANSI_RESET}\n   {ANSI_BLUE}{code}{ANSI_RESET}\n\
 \n{ANSI_GRAY}Device codes are a common phishing target. Never share this code.{ANSI_RESET}\n",
        version = env!("CARGO_PKG_VERSION"),
-        code = code
+        code = code,
+        issuer_base_url = issuer_base_url
    );
 }

 /// Full device code login flow.
 pub async fn run_device_code_login(opts: ServerOptions) -> std::io::Result<()> {
    let client = reqwest::Client::new();
-    let base_url = opts.issuer.trim_end_matches('/');
-    let api_base_url = format!("{}/api/accounts", opts.issuer.trim_end_matches('/'));
+    let issuer_base_url = opts.issuer.trim_end_matches('/');
+    let api_base_url = format!("{issuer_base_url}/api/accounts");
    let uc = request_user_code(&client, &api_base_url, &opts.client_id).await?;

-    print_device_code_prompt(&uc.user_code);
+    print_device_code_prompt(&uc.user_code, issuer_base_url);

    let code_resp = poll_for_token(
        &client,
@@ -171,10 +172,10 @@ pub async fn run_device_code_login(opts: ServerOptions) -> std::io::Result<()> {
        code_verifier: code_resp.code_verifier,
        code_challenge: code_resp.code_challenge,
    };
-    let redirect_uri = format!("{base_url}/deviceauth/callback");
+    let redirect_uri = format!("{issuer_base_url}/deviceauth/callback");

    let tokens = crate::server::exchange_code_for_tokens(
-        base_url,
+        issuer_base_url,
        &opts.client_id,
        &redirect_uri,
        &pkce,
@@ -94,6 +94,7 @@ pub async fn run_codex_tool_session(
            items: vec![UserInput::Text {
                text: initial_prompt.clone(),
            }],
+            final_output_json_schema: None,
        },
    };

@@ -128,6 +129,7 @@ pub async fn run_codex_tool_session_reply(
    if let Err(e) = conversation
        .submit(Op::UserInput {
            items: vec![UserInput::Text { text: prompt }],
+            final_output_json_schema: None,
        })
        .await
    {
@@ -44,11 +44,6 @@ serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 strum_macros = { workspace = true }
 tokio = { workspace = true }
-tonic = { workspace = true, features = [
-    "transport",
-    "tls-native-roots",
-    "tls-ring",
-] }
 tracing = { workspace = true }
 tracing-opentelemetry = { workspace = true }
 tracing-subscriber = { workspace = true }
@@ -70,7 +70,7 @@ impl OtelManager {
        let session_span = trace_span!("new_session", conversation_id = %conversation_id, session_source = %session_source);

        if let Some(context) = traceparent_context_from_env() {
-            session_span.set_parent(context);
+            let _ = session_span.set_parent(context);
        }

        Self {
@@ -511,6 +511,7 @@ impl OtelManager {
                "reasoning_summary_part_added".into()
            }
            ResponseEvent::RateLimits(_) => "rate_limits".into(),
+            ResponseEvent::ModelsEtag(_) => "models_etag".into(),
        }
    }

@@ -22,6 +22,10 @@ use opentelemetry_otlp::SpanExporter;
 use opentelemetry_otlp::WithExportConfig;
 use opentelemetry_otlp::WithHttpConfig;
 use opentelemetry_otlp::WithTonicConfig;
+use opentelemetry_otlp::tonic_types::metadata::MetadataMap;
+use opentelemetry_otlp::tonic_types::transport::Certificate as TonicCertificate;
+use opentelemetry_otlp::tonic_types::transport::ClientTlsConfig;
+use opentelemetry_otlp::tonic_types::transport::Identity as TonicIdentity;
 use opentelemetry_sdk::Resource;
 use opentelemetry_sdk::logs::SdkLoggerProvider;
 use opentelemetry_sdk::propagation::TraceContextPropagator;
@@ -44,10 +48,6 @@ use std::io::{self};
 use std::path::PathBuf;
 use std::sync::OnceLock;
 use std::time::Duration;
-use tonic::metadata::MetadataMap;
-use tonic::transport::Certificate as TonicCertificate;
-use tonic::transport::ClientTlsConfig;
-use tonic::transport::Identity as TonicIdentity;
 use tracing::debug;
 use tracing::level_filters::LevelFilter;
 use tracing::warn;
@@ -102,7 +102,7 @@ impl OtelProvider {
            .map(|provider| provider.tracer(settings.service_name.clone()));

        if let Some(provider) = tracer_provider.clone() {
-            let _ = global::set_tracer_provider(provider);
+            global::set_tracer_provider(provider);
            global::set_text_map_propagator(TraceContextPropagator::new());
        }
        if tracer.is_some() {
@@ -416,7 +416,6 @@ impl Serialize for FunctionCallOutputPayload {
    where
        S: Serializer,
    {
-        tracing::debug!("Function call output payload: {:?}", self);
        if let Some(items) = &self.content_items {
            items.serialize(serializer)
        } else {
@@ -187,8 +187,6 @@ pub struct ModelInfo {
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema, Default)]
 pub struct ModelsResponse {
    pub models: Vec<ModelInfo>,
-    #[serde(default)]
-    pub etag: String,
 }

 // convert ModelInfo to ModelPreset
@@ -74,6 +74,9 @@ pub enum Op {
    UserInput {
        /// User input items, see `InputItem`
        items: Vec<UserInput>,
+        /// Optional JSON Schema used to constrain the final assistant message for this turn.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        final_output_json_schema: Option<Value>,
    },

    /// Similar to [`Op::UserInput`], but contains additional context required
@@ -844,7 +847,7 @@ pub struct TaskStartedEvent {
    pub model_context_window: Option<i64>,
 }

-#[derive(Debug, Clone, Deserialize, Serialize, Default, JsonSchema, TS)]
+#[derive(Debug, Clone, Deserialize, Serialize, Default, PartialEq, Eq, JsonSchema, TS)]
 pub struct TokenUsage {
    #[ts(type = "number")]
    pub input_tokens: i64,
@@ -858,7 +861,7 @@ pub struct TokenUsage {
    pub total_tokens: i64,
 }

-#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
 pub struct TokenUsageInfo {
    pub total_token_usage: TokenUsage,
    pub last_token_usage: TokenUsage,
@@ -1928,6 +1931,62 @@ mod tests {
        assert!(event.as_legacy_events(false).is_empty());
    }

+    #[test]
+    fn user_input_serialization_omits_final_output_json_schema_when_none() -> Result<()> {
+        let op = Op::UserInput {
+            items: Vec::new(),
+            final_output_json_schema: None,
+        };
+
+        let json_op = serde_json::to_value(op)?;
+        assert_eq!(json_op, json!({ "type": "user_input", "items": [] }));
+
+        Ok(())
+    }
+
+    #[test]
+    fn user_input_deserializes_without_final_output_json_schema_field() -> Result<()> {
+        let op: Op = serde_json::from_value(json!({ "type": "user_input", "items": [] }))?;
+
+        assert_eq!(
+            op,
+            Op::UserInput {
+                items: Vec::new(),
+                final_output_json_schema: None,
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn user_input_serialization_includes_final_output_json_schema_when_some() -> Result<()> {
+        let schema = json!({
+            "type": "object",
+            "properties": {
+                "answer": { "type": "string" }
+            },
+            "required": ["answer"],
+            "additionalProperties": false
+        });
+        let op = Op::UserInput {
+            items: Vec::new(),
+            final_output_json_schema: Some(schema.clone()),
+        };
+
+        let json_op = serde_json::to_value(op)?;
+        assert_eq!(
+            json_op,
+            json!({
+                "type": "user_input",
+                "items": [],
+                "final_output_json_schema": schema,
+            })
+        );
+
+        Ok(())
+    }
+
    /// Serialize Event to verify that its JSON representation has the expected
    /// amount of nesting.
    #[test]
@@ -372,10 +372,6 @@ impl App {
        }

        let enhanced_keys_supported = tui.enhanced_keys_supported();
-        let model_family = conversation_manager
-            .get_models_manager()
-            .construct_model_family(model.as_str(), &config)
-            .await;
        let mut chat_widget = match resume_selection {
            ResumeSelection::StartFresh | ResumeSelection::Exit => {
                let init = crate::chatwidget::ChatWidgetInit {
@@ -389,7 +385,7 @@ impl App {
                    models_manager: conversation_manager.get_models_manager(),
                    feedback: feedback.clone(),
                    is_first_run,
-                    model_family: model_family.clone(),
+                    model: model.clone(),
                };
                ChatWidget::new(init, conversation_manager.clone())
            }
@@ -415,7 +411,7 @@ impl App {
                    models_manager: conversation_manager.get_models_manager(),
                    feedback: feedback.clone(),
                    is_first_run,
-                    model_family: model_family.clone(),
+                    model: model.clone(),
                };
                ChatWidget::new_from_existing(
                    init,
@@ -582,7 +578,7 @@ impl App {
                    models_manager: self.server.get_models_manager(),
                    feedback: self.feedback.clone(),
                    is_first_run: false,
-                    model_family: model_family.clone(),
+                    model: self.current_model.clone(),
                };
                self.chat_widget = ChatWidget::new(init, self.server.clone());
                self.current_model = model_family.get_model_slug().to_string();
@@ -632,7 +628,7 @@ impl App {
                                    models_manager: self.server.get_models_manager(),
                                    feedback: self.feedback.clone(),
                                    is_first_run: false,
-                                    model_family: model_family.clone(),
+                                    model: self.current_model.clone(),
                                };
                                self.chat_widget = ChatWidget::new_from_existing(
                                    init,
@@ -767,12 +763,7 @@ impl App {
                self.on_update_reasoning_effort(effort);
            }
            AppEvent::UpdateModel(model) => {
-                let model_family = self
-                    .server
-                    .get_models_manager()
-                    .construct_model_family(&model, &self.config)
-                    .await;
-                self.chat_widget.set_model(&model, model_family);
+                self.chat_widget.set_model(&model);
                self.current_model = model;
            }
            AppEvent::OpenReasoningPopup { model } => {
@@ -1357,7 +1348,7 @@ mod tests {
    async fn make_test_app() -> App {
        let (chat_widget, app_event_tx, _rx, _op_rx) = make_chatwidget_manual_with_sender().await;
        let config = chat_widget.config_ref().clone();
-        let current_model = chat_widget.get_model_family().get_model_slug().to_string();
+        let current_model = "gpt-5.2-codex".to_string();
        let server = Arc::new(ConversationManager::with_models_provider(
            CodexAuth::from_api_key("Test API Key"),
            config.model_provider.clone(),
@@ -1396,7 +1387,7 @@ mod tests {
    ) {
        let (chat_widget, app_event_tx, rx, op_rx) = make_chatwidget_manual_with_sender().await;
        let config = chat_widget.config_ref().clone();
-        let current_model = chat_widget.get_model_family().get_model_slug().to_string();
+        let current_model = "gpt-5.2-codex".to_string();
        let server = Arc::new(ConversationManager::with_models_provider(
            CodexAuth::from_api_key("Test API Key"),
            config.model_provider.clone(),
@@ -338,10 +338,9 @@ impl App {
    ) {
        let conv = new_conv.conversation;
        let session_configured = new_conv.session_configured;
-        let model_family = self.chat_widget.get_model_family();
        let init = crate::chatwidget::ChatWidgetInit {
            config: cfg,
-            model_family: model_family.clone(),
+            model: self.current_model.clone(),
            frame_requester: tui.frame_requester(),
            app_event_tx: self.app_event_tx.clone(),
            initial_prompt: None,
@@ -354,7 +353,6 @@ impl App {
        };
        self.chat_widget =
            crate::chatwidget::ChatWidget::new_from_existing(init, conv, session_configured);
-        self.current_model = model_family.get_model_slug().to_string();
        // Trim transcript up to the selected user message and re-render it.
        self.trim_transcript_for_backtrack(nth_user_message);
        self.render_transcript_once(tui);
@@ -15,7 +15,6 @@ use codex_core::features::Feature;
 use codex_core::git_info::current_branch_name;
 use codex_core::git_info::local_git_branches;
 use codex_core::models_manager::manager::ModelsManager;
-use codex_core::models_manager::model_family::ModelFamily;
 use codex_core::project_doc::DEFAULT_PROJECT_DOC_FILENAME;
 use codex_core::protocol::AgentMessageDeltaEvent;
 use codex_core::protocol::AgentMessageEvent;
@@ -291,7 +290,7 @@ pub(crate) struct ChatWidgetInit {
    pub(crate) models_manager: Arc<ModelsManager>,
    pub(crate) feedback: codex_feedback::CodexFeedback,
    pub(crate) is_first_run: bool,
-    pub(crate) model_family: ModelFamily,
+    pub(crate) model: String,
 }

 #[derive(Default)]
@@ -316,7 +315,7 @@ pub(crate) struct ChatWidget {
    bottom_pane: BottomPane,
    active_cell: Option<Box<dyn HistoryCell>>,
    config: Config,
-    model_family: ModelFamily,
+    model: String,
    auth_manager: Arc<AuthManager>,
    models_manager: Arc<ModelsManager>,
    session_header: SessionHeader,
@@ -608,12 +607,10 @@ impl ChatWidget {
    }

    fn context_remaining_percent(&self, info: &TokenUsageInfo) -> Option<i64> {
-        info.model_context_window
-            .or(self.model_family.context_window)
-            .map(|window| {
-                info.last_token_usage
-                    .percent_of_context_window_remaining(window)
-            })
+        info.model_context_window.map(|window| {
+            info.last_token_usage
+                .percent_of_context_window_remaining(window)
+        })
    }

    fn context_used_tokens(&self, info: &TokenUsageInfo, percent_known: bool) -> Option<i64> {
@@ -681,7 +678,7 @@ impl ChatWidget {

            if high_usage
                && !self.rate_limit_switch_prompt_hidden()
-                && self.model_family.get_model_slug() != NUDGE_MODEL_SLUG
+                && self.model != NUDGE_MODEL_SLUG
                && !matches!(
                    self.rate_limit_switch_prompt,
                    RateLimitSwitchPromptState::Shown
@@ -715,9 +712,6 @@ impl ChatWidget {
        self.stream_controller = None;
        self.maybe_show_pending_rate_limit_prompt();
    }
-    pub(crate) fn get_model_family(&self) -> ModelFamily {
-        self.model_family.clone()
-    }

    fn on_error(&mut self, message: String) {
        self.finalize_turn();
@@ -1420,11 +1414,10 @@ impl ChatWidget {
            models_manager,
            feedback,
            is_first_run,
-            model_family,
+            model,
        } = common;
-        let model_slug = model_family.get_model_slug().to_string();
        let mut config = config;
-        config.model = Some(model_slug.clone());
+        config.model = Some(model.clone());
        let mut rng = rand::rng();
        let placeholder = EXAMPLE_PROMPTS[rng.random_range(0..EXAMPLE_PROMPTS.len())].to_string();
        let codex_op_tx = spawn_agent(config.clone(), app_event_tx.clone(), conversation_manager);
@@ -1445,10 +1438,10 @@ impl ChatWidget {
            }),
            active_cell: None,
            config,
-            model_family,
+            model: model.clone(),
            auth_manager,
            models_manager,
-            session_header: SessionHeader::new(model_slug),
+            session_header: SessionHeader::new(model),
            initial_user_message: create_initial_user_message(
                initial_prompt.unwrap_or_default(),
                initial_images,
@@ -1506,10 +1499,9 @@ impl ChatWidget {
            auth_manager,
            models_manager,
            feedback,
-            model_family,
+            model,
            ..
        } = common;
-        let model_slug = model_family.get_model_slug().to_string();
        let mut rng = rand::rng();
        let placeholder = EXAMPLE_PROMPTS[rng.random_range(0..EXAMPLE_PROMPTS.len())].to_string();

@@ -1532,10 +1524,10 @@ impl ChatWidget {
            }),
            active_cell: None,
            config,
-            model_family,
+            model: model.clone(),
            auth_manager,
            models_manager,
-            session_header: SessionHeader::new(model_slug),
+            session_header: SessionHeader::new(model),
            initial_user_message: create_initial_user_message(
                initial_prompt.unwrap_or_default(),
                initial_images,
@@ -1961,7 +1953,10 @@ impl ChatWidget {
        }

        self.codex_op_tx
-            .send(Op::UserInput { items })
+            .send(Op::UserInput {
+                items,
+                final_output_json_schema: None,
+            })
            .unwrap_or_else(|e| {
                tracing::error!("failed to send message: {e}");
            });
@@ -2249,22 +2244,20 @@ impl ChatWidget {

    pub(crate) fn add_status_output(&mut self) {
        let default_usage = TokenUsage::default();
-        let (total_usage, context_usage) = if let Some(ti) = &self.token_info {
-            (&ti.total_token_usage, Some(&ti.last_token_usage))
-        } else {
-            (&default_usage, Some(&default_usage))
-        };
+        let token_info = self.token_info.as_ref();
+        let total_usage = token_info
+            .map(|ti| &ti.total_token_usage)
+            .unwrap_or(&default_usage);
        self.add_to_history(crate::status::new_status_output(
            &self.config,
            self.auth_manager.as_ref(),
-            &self.model_family,
+            token_info,
            total_usage,
-            context_usage,
            &self.conversation_id,
            self.rate_limit_snapshot.as_ref(),
            self.plan_type,
            Local::now(),
-            self.model_family.get_model_slug(),
+            &self.model,
        ));
    }

@@ -2417,7 +2410,6 @@ impl ChatWidget {
    /// Open a popup to choose a quick auto model. Selecting "All models"
    /// opens the full picker with every available preset.
    pub(crate) fn open_model_popup(&mut self) {
-        let current_model = self.model_family.get_model_slug().to_string();
        let presets: Vec<ModelPreset> =
            // todo(aibrahim): make this async function
            match self.models_manager.try_list_models(&self.config) {
@@ -2434,9 +2426,9 @@ impl ChatWidget {

        let current_label = presets
            .iter()
-            .find(|preset| preset.model == current_model)
+            .find(|preset| preset.model == self.model)
            .map(|preset| preset.display_name.to_string())
-            .unwrap_or_else(|| current_model.clone());
+            .unwrap_or_else(|| self.model.clone());

        let (mut auto_presets, other_presets): (Vec<ModelPreset>, Vec<ModelPreset>) = presets
            .into_iter()
@@ -2462,7 +2454,7 @@ impl ChatWidget {
                SelectionItem {
                    name: preset.display_name.clone(),
                    description,
-                    is_current: model == current_model,
+                    is_current: model == self.model,
                    is_default: preset.is_default,
                    actions,
                    dismiss_on_select: true,
@@ -2525,12 +2517,11 @@ impl ChatWidget {
            return;
        }

-        let current_model = self.model_family.get_model_slug().to_string();
        let mut items: Vec<SelectionItem> = Vec::new();
        for preset in presets.into_iter() {
            let description =
                (!preset.description.is_empty()).then_some(preset.description.to_string());
-            let is_current = preset.model == current_model;
+            let is_current = preset.model == self.model;
            let single_supported_effort = preset.supported_reasoning_efforts.len() == 1;
            let preset_for_action = preset.clone();
            let actions: Vec<SelectionAction> = vec![Box::new(move |tx| {
@@ -2656,7 +2647,7 @@ impl ChatWidget {
            .or(Some(default_effort));

        let model_slug = preset.model.to_string();
-        let is_current_model = self.model_family.get_model_slug() == preset.model;
+        let is_current_model = self.model == preset.model;
        let highlight_choice = if is_current_model {
            self.config.model_reasoning_effort
        } else {
@@ -3246,9 +3237,9 @@ impl ChatWidget {
    }

    /// Set the model in the widget's config copy.
-    pub(crate) fn set_model(&mut self, model: &str, model_family: ModelFamily) {
+    pub(crate) fn set_model(&mut self, model: &str) {
        self.session_header.set_model(model);
-        self.model_family = model_family;
+        self.model = model.to_string();
    }

    pub(crate) fn add_info_message(&mut self, message: String, hint: Option<String>) {
@@ -313,7 +313,6 @@ async fn helpers_are_available_and_do_not_panic() {
    let tx = AppEventSender::new(tx_raw);
    let cfg = test_config().await;
    let resolved_model = ModelsManager::get_model_offline(cfg.model.as_deref());
-    let model_family = ModelsManager::construct_model_family_offline(&resolved_model, &cfg);
    let conversation_manager = Arc::new(ConversationManager::with_models_provider(
        CodexAuth::from_api_key("test"),
        cfg.model_provider.clone(),
@@ -330,7 +329,7 @@ async fn helpers_are_available_and_do_not_panic() {
        models_manager: conversation_manager.get_models_manager(),
        feedback: codex_feedback::CodexFeedback::new(),
        is_first_run: true,
-        model_family,
+        model: resolved_model,
    };
    let mut w = ChatWidget::new(init, conversation_manager);
    // Basic construction sanity.
@@ -371,11 +370,11 @@ async fn make_chatwidget_manual(
        codex_op_tx: op_tx,
        bottom_pane: bottom,
        active_cell: None,
-        config: cfg.clone(),
-        model_family: ModelsManager::construct_model_family_offline(&resolved_model, &cfg),
+        config: cfg,
+        model: resolved_model.clone(),
        auth_manager: auth_manager.clone(),
        models_manager: Arc::new(ModelsManager::new(auth_manager)),
-        session_header: SessionHeader::new(resolved_model.clone()),
+        session_header: SessionHeader::new(resolved_model),
        initial_user_message: None,
        token_info: None,
        rate_limit_snapshot: None,
@@ -29,7 +29,6 @@ use std::path::PathBuf;
 use tracing::error;
 use tracing_appender::non_blocking;
 use tracing_subscriber::EnvFilter;
-use tracing_subscriber::filter::Targets;
 use tracing_subscriber::prelude::*;

 mod additional_dirs;
@@ -282,13 +281,8 @@ pub async fn run_main(
        .with_filter(env_filter());

    let feedback = codex_feedback::CodexFeedback::new();
-    let targets = Targets::new().with_default(tracing::Level::TRACE);
-
-    let feedback_layer = tracing_subscriber::fmt::layer()
-        .with_writer(feedback.make_writer())
-        .with_ansi(false)
-        .with_target(false)
-        .with_filter(targets);
+    let feedback_layer = feedback.logger_layer();
+    let feedback_metadata_layer = feedback.metadata_layer();

    if cli.oss && model_provider_override.is_some() {
        // We're in the oss section, so provider_id should be Some
@@ -323,6 +317,7 @@ pub async fn run_main(
    let _ = tracing_subscriber::registry()
        .with(file_layer)
        .with(feedback_layer)
+        .with(feedback_metadata_layer)
        .with(otel_logger_layer)
        .with(otel_tracing_layer)
        .try_init();
@@ -279,6 +279,12 @@ impl AuthModeWidget {
            lines.push("".into());
            lines.push(Line::from(state.auth_url.as_str().cyan().underlined()));
            lines.push("".into());
+            lines.push(Line::from(vec![
+                "  On a remote or headless machine? Use ".into(),
+                "codex login --device-auth".cyan(),
+                " instead".into(),
+            ]));
+            lines.push("".into());
        }

        lines.push("  Press Esc to cancel".dim().into());
@@ -7,10 +7,10 @@ use chrono::DateTime;
 use chrono::Local;
 use codex_common::create_config_summary_entries;
 use codex_core::config::Config;
-use codex_core::models_manager::model_family::ModelFamily;
 use codex_core::protocol::NetworkAccess;
 use codex_core::protocol::SandboxPolicy;
 use codex_core::protocol::TokenUsage;
+use codex_core::protocol::TokenUsageInfo;
 use codex_protocol::ConversationId;
 use codex_protocol::account::PlanType;
 use ratatui::prelude::*;
@@ -72,9 +72,8 @@ struct StatusHistoryCell {
 pub(crate) fn new_status_output(
    config: &Config,
    auth_manager: &AuthManager,
-    model_family: &ModelFamily,
+    token_info: Option<&TokenUsageInfo>,
    total_usage: &TokenUsage,
-    context_usage: Option<&TokenUsage>,
    session_id: &Option<ConversationId>,
    rate_limits: Option<&RateLimitSnapshotDisplay>,
    plan_type: Option<PlanType>,
@@ -85,9 +84,8 @@ pub(crate) fn new_status_output(
    let card = StatusHistoryCell::new(
        config,
        auth_manager,
-        model_family,
+        token_info,
        total_usage,
-        context_usage,
        session_id,
        rate_limits,
        plan_type,
@@ -103,9 +101,8 @@ impl StatusHistoryCell {
    fn new(
        config: &Config,
        auth_manager: &AuthManager,
-        model_family: &ModelFamily,
+        token_info: Option<&TokenUsageInfo>,
        total_usage: &TokenUsage,
-        context_usage: Option<&TokenUsage>,
        session_id: &Option<ConversationId>,
        rate_limits: Option<&RateLimitSnapshotDisplay>,
        plan_type: Option<PlanType>,
@@ -134,12 +131,15 @@ impl StatusHistoryCell {
        let agents_summary = compose_agents_summary(config);
        let account = compose_account_display(auth_manager, plan_type);
        let session_id = session_id.as_ref().map(std::string::ToString::to_string);
-        let context_window = model_family.context_window.and_then(|window| {
-            context_usage.map(|usage| StatusContextWindowData {
-                percent_remaining: usage.percent_of_context_window_remaining(window),
-                tokens_in_context: usage.tokens_in_context_window(),
-                window,
-            })
+        let default_usage = TokenUsage::default();
+        let (context_usage, context_window) = match token_info {
+            Some(info) => (&info.last_token_usage, info.model_context_window),
+            None => (&default_usage, config.model_context_window),
+        };
+        let context_window = context_window.map(|window| StatusContextWindowData {
+            percent_remaining: context_usage.percent_of_context_window_remaining(window),
+            tokens_in_context: context_usage.tokens_in_context_window(),
+            window,
        });

        let token_usage = StatusTokenUsageData {
@@ -348,6 +348,7 @@ impl HistoryCell for StatusHistoryCell {
        if self.token_usage.context_window.is_some() {
            push_label(&mut labels, &mut seen, "Context window");
        }
+
        self.collect_rate_limit_labels(&mut seen, &mut labels);

        let formatter = FieldFormatter::from_labels(labels.iter().map(String::as_str));
@@ -8,12 +8,12 @@ use codex_core::AuthManager;
 use codex_core::config::Config;
 use codex_core::config::ConfigBuilder;
 use codex_core::models_manager::manager::ModelsManager;
-use codex_core::models_manager::model_family::ModelFamily;
 use codex_core::protocol::CreditsSnapshot;
 use codex_core::protocol::RateLimitSnapshot;
 use codex_core::protocol::RateLimitWindow;
 use codex_core::protocol::SandboxPolicy;
 use codex_core::protocol::TokenUsage;
+use codex_core::protocol::TokenUsageInfo;
 use codex_protocol::config_types::ReasoningSummary;
 use codex_protocol::openai_models::ReasoningEffort;
 use insta::assert_snapshot;
@@ -37,8 +37,15 @@ fn test_auth_manager(config: &Config) -> AuthManager {
    )
 }

-fn test_model_family(model_slug: &str, config: &Config) -> ModelFamily {
-    ModelsManager::construct_model_family_offline(model_slug, config)
+fn token_info_for(model_slug: &str, config: &Config, usage: &TokenUsage) -> TokenUsageInfo {
+    let context_window = ModelsManager::construct_model_family_offline(model_slug, config)
+        .context_window
+        .or(config.model_context_window);
+    TokenUsageInfo {
+        total_token_usage: usage.clone(),
+        last_token_usage: usage.clone(),
+        model_context_window: context_window,
+    }
 }

 fn render_lines(lines: &[Line<'static>]) -> Vec<String> {
@@ -132,14 +139,13 @@ async fn status_snapshot_includes_reasoning_details() {
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);

    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -190,13 +196,12 @@ async fn status_snapshot_includes_monthly_limit() {
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -235,13 +240,12 @@ async fn status_snapshot_shows_unlimited_credits() {
    };
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);
    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -279,13 +283,12 @@ async fn status_snapshot_shows_positive_credits() {
    };
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);
    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -323,13 +326,12 @@ async fn status_snapshot_hides_zero_credits() {
    };
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);
    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -365,13 +367,12 @@ async fn status_snapshot_hides_when_has_no_credits_flag() {
    };
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);
    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -407,13 +408,12 @@ async fn status_card_token_usage_excludes_cached_tokens() {
        .expect("timestamp");

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        None,
        None,
@@ -464,13 +464,12 @@ async fn status_snapshot_truncates_in_narrow_terminal() {
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -510,13 +509,12 @@ async fn status_snapshot_shows_missing_limits_message() {
        .expect("timestamp");

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        None,
        None,
@@ -574,13 +572,12 @@ async fn status_snapshot_includes_credits_and_limits() {
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -626,13 +623,12 @@ async fn status_snapshot_shows_empty_limits_message() {
    let rate_display = rate_limit_snapshot_display(&snapshot, captured_at);

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -687,13 +683,12 @@ async fn status_snapshot_shows_stale_limits_message() {
    let now = captured_at + ChronoDuration::minutes(20);

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -752,13 +747,12 @@ async fn status_snapshot_cached_limits_hide_credits_without_flag() {
    let now = captured_at + ChronoDuration::minutes(20);

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = token_info_for(&model_slug, &config, &usage);
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &usage,
-        Some(&usage),
        &None,
        Some(&rate_display),
        None,
@@ -803,13 +797,16 @@ async fn status_context_window_uses_last_usage() {
        .expect("timestamp");

    let model_slug = ModelsManager::get_model_offline(config.model.as_deref());
-    let model_family = test_model_family(&model_slug, &config);
+    let token_info = TokenUsageInfo {
+        total_token_usage: total_usage.clone(),
+        last_token_usage: last_usage,
+        model_context_window: config.model_context_window,
+    };
    let composite = new_status_output(
        &config,
        &auth_manager,
-        &model_family,
+        Some(&token_info),
        &total_usage,
-        Some(&last_usage),
        &None,
        None,
        None,
--- a/Show More
+++ b/Show More