docs: add install script for release binaries

## Summary
- Prioritize provider-specific API keys over default Codex auth when
building requests
- Add test to ensure provider env var auth overrides default auth

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

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

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

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

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

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

.github/workflows/rust-release.yml

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

README.md

@@ -379,18 +379,35 @@ From `npm` (generally more readily available, but downloads binaries for all sup
 npm i -g @openai/codex
 ```
 
-Or go to the [latest GitHub Release](https://github.com/openai/codex/releases/latest) and download the appropriate binary for your platform.
+Or run the following script to download the appropriate pre-built binary from the
+[latest GitHub Release](https://github.com/openai/codex/releases/latest). It
+installs to `~/.local/bin` by default; set `INSTALL_DIR` to override:
 
-Admittedly, each GitHub Release contains many executables, but in practice, you likely want one of these:
+```bash
+set -euo pipefail
 
-- macOS
-  - Apple Silicon/arm64: `codex-aarch64-apple-darwin.tar.gz`
-  - x86_64 (older Mac hardware): `codex-x86_64-apple-darwin.tar.gz`
-- Linux
-  - x86_64: `codex-x86_64-unknown-linux-musl.tar.gz`
-  - arm64: `codex-aarch64-unknown-linux-musl.tar.gz`
+case "$(uname -s)" in
+  Darwin) os="apple-darwin" ;;
+  Linux) os="unknown-linux-musl" ;;
+  *) echo "unsupported OS" >&2; exit 1 ;;
+esac
 
-Each archive contains a single entry with the platform baked into the name (e.g., `codex-x86_64-unknown-linux-musl`), so you likely want to rename it to `codex` after extracting it.
+case "$(uname -m)" in
+  x86_64|amd64) arch="x86_64" ;;
+  arm64|aarch64) arch="aarch64" ;;
+  *) echo "unsupported architecture" >&2; exit 1 ;;
+esac
+
+tarball="codex-${arch}-${os}.tar.gz"
+tmpdir="$(mktemp -d)"
+curl -L "https://github.com/openai/codex/releases/latest/download/${tarball}" |
+  tar -xz -C "$tmpdir"
+install_dir="${INSTALL_DIR:-$HOME/.local/bin}"
+mkdir -p "$install_dir"
+install -m755 "$tmpdir/codex-${arch}-${os}" "$install_dir/codex"
+rm -r "$tmpdir"
+echo "Codex installed to $install_dir/codex"
+```
 
 ### DotSlash
 

codex-rs/common/src/approval_mode_cli_arg.rs

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

codex-rs/common/src/config_summary.rs

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

codex-rs/common/src/lib.rs

@@ -23,3 +23,7 @@ mod sandbox_summary;
 
 #[cfg(feature = "sandbox_summary")]
 pub use sandbox_summary::summarize_sandbox_policy;
+
+mod config_summary;
+
+pub use config_summary::create_config_summary_entries;

codex-rs/config.md

@@ -148,12 +148,20 @@ Determines when the user should be prompted to approve whether Codex can execute
 approval_policy = "untrusted"
 ```
 
+If you want to be notified whenever a command fails, use "on-failure":
 ```toml
 # If the command fails when run in the sandbox, Codex asks for permission to
 # retry the command outside the sandbox.
 approval_policy = "on-failure"
 ```
 
+If you want the model to run until it decides that it needs to ask you for escalated permissions, use "on-request":
+```toml
+# The model decides when to escalate
+approval_policy = "on-request"
+```
+
+Alternatively, you can have the model run until it is done, and never ask to run a command with escalated permissions:
 ```toml
 # User is never prompted: if the command fails, Codex will automatically try
 # something out. Note the `exec` subcommand always uses this mode.

codex-rs/core/src/chat_completions.rs

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

codex-rs/core/src/client.rs

@@ -34,7 +34,6 @@ use crate::error::Result;
 use crate::flags::CODEX_RS_SSE_FIXTURE;
 use crate::model_provider_info::ModelProviderInfo;
 use crate::model_provider_info::WireApi;
-use crate::models::ContentItem;
 use crate::models::ResponseItem;
 use crate::openai_tools::create_tools_json_for_responses_api;
 use crate::protocol::TokenUsage;
@@ -83,7 +82,6 @@ impl ModelClient {
                 let response_stream = stream_chat_completions(
                     prompt,
                     &self.config.model_family,
-                    self.config.include_plan_tool,
                     &self.client,
                     &self.provider,
                 )
@@ -132,11 +130,7 @@ impl ModelClient {
         let store = prompt.store && auth_mode != Some(AuthMode::ChatGPT);
 
         let full_instructions = prompt.get_full_instructions(&self.config.model_family);
-        let tools_json = create_tools_json_for_responses_api(
-            prompt,
-            &self.config.model_family,
-            self.config.include_plan_tool,
-        )?;
+        let tools_json = create_tools_json_for_responses_api(&prompt.tools)?;
         let reasoning = create_reasoning_param_for_request(
             &self.config.model_family,
             self.effort,
@@ -151,15 +145,7 @@ impl ModelClient {
             vec![]
         };
 
-        let mut input_with_instructions = Vec::with_capacity(prompt.input.len() + 1);
-        if let Some(ui) = prompt.get_formatted_user_instructions() {
-            input_with_instructions.push(ResponseItem::Message {
-                id: None,
-                role: "user".to_string(),
-                content: vec![ContentItem::InputText { text: ui }],
-            });
-        }
-        input_with_instructions.extend(prompt.input.clone());
+        let input_with_instructions = prompt.get_formatted_input();
 
         let payload = ResponsesApiRequest {
             model: &self.config.model,
@@ -637,7 +623,7 @@ mod tests {
             request_max_retries: Some(0),
             stream_max_retries: Some(0),
             stream_idle_timeout_ms: Some(1000),
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let events = collect_events(
@@ -697,7 +683,7 @@ mod tests {
             request_max_retries: Some(0),
             stream_max_retries: Some(0),
             stream_idle_timeout_ms: Some(1000),
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let events = collect_events(&[sse1.as_bytes()], provider).await;
@@ -800,7 +786,7 @@ mod tests {
                 request_max_retries: Some(0),
                 stream_max_retries: Some(0),
                 stream_idle_timeout_ms: Some(1000),
-                requires_auth: false,
+                requires_openai_auth: false,
             };
 
             let out = run_sse(evs, provider).await;

codex-rs/core/src/client_common.rs

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

codex-rs/core/src/codex.rs

@@ -37,6 +37,7 @@ use crate::apply_patch::convert_apply_patch_to_protocol;
 use crate::apply_patch::get_writable_roots;
 use crate::apply_patch::{self};
 use crate::client::ModelClient;
+use crate::client_common::EnvironmentContext;
 use crate::client_common::Prompt;
 use crate::client_common::ResponseEvent;
 use crate::config::Config;
@@ -61,6 +62,8 @@ use crate::models::ReasoningItemReasoningSummary;
 use crate::models::ResponseInputItem;
 use crate::models::ResponseItem;
 use crate::models::ShellToolCallParams;
+use crate::openai_tools::ToolsConfig;
+use crate::openai_tools::get_openai_tools;
 use crate::plan_tool::handle_update_plan;
 use crate::project_doc::get_user_instructions;
 use crate::protocol::AgentMessageDeltaEvent;
@@ -216,6 +219,7 @@ pub(crate) struct Session {
     shell_environment_policy: ShellEnvironmentPolicy,
     pub(crate) writable_roots: Mutex<Vec<PathBuf>>,
     disable_response_storage: bool,
+    tools_config: ToolsConfig,
 
     /// Manager for external MCP servers/tools.
     mcp_connection_manager: McpConnectionManager,
@@ -810,6 +814,12 @@ async fn submission_loop(
                 let default_shell = shell::default_user_shell().await;
                 sess = Some(Arc::new(Session {
                     client,
+                    tools_config: ToolsConfig::new(
+                        &config.model_family,
+                        approval_policy,
+                        sandbox_policy.clone(),
+                        config.include_plan_tool,
+                    ),
                     tx_event: tx_event.clone(),
                     ctrl_c: Arc::clone(&ctrl_c),
                     user_instructions,
@@ -1204,13 +1214,22 @@ async fn run_turn(
     sub_id: String,
     input: Vec<ResponseItem>,
 ) -> CodexResult<Vec<ProcessedResponseItem>> {
-    let extra_tools = sess.mcp_connection_manager.list_all_tools();
+    let tools = get_openai_tools(
+        &sess.tools_config,
+        Some(sess.mcp_connection_manager.list_all_tools()),
+    );
+
     let prompt = Prompt {
         input,
         user_instructions: sess.user_instructions.clone(),
         store: !sess.disable_response_storage,
-        extra_tools,
+        tools,
         base_instructions_override: sess.base_instructions.clone(),
+        environment_context: Some(EnvironmentContext {
+            cwd: sess.cwd.clone(),
+            approval_policy: sess.approval_policy,
+            sandbox_policy: sess.sandbox_policy.clone(),
+        }),
     };
 
     let mut retries = 0;
@@ -1436,7 +1455,8 @@ async fn run_compact_task(
         input: turn_input,
         user_instructions: None,
         store: !sess.disable_response_storage,
-        extra_tools: HashMap::new(),
+        environment_context: None,
+        tools: Vec::new(),
         base_instructions_override: Some(compact_instructions.clone()),
     };
 
@@ -1580,6 +1600,8 @@ async fn handle_response_item(
                 command: action.command,
                 workdir: action.working_directory,
                 timeout_ms: action.timeout_ms,
+                with_escalated_permissions: None,
+                justification: None,
             };
             let effective_call_id = match (call_id, id) {
                 (Some(call_id), _) => call_id,
@@ -1668,6 +1690,8 @@ fn to_exec_params(params: ShellToolCallParams, sess: &Session) -> ExecParams {
         cwd: sess.resolve_path(params.workdir.clone()),
         timeout_ms: params.timeout_ms,
         env: create_env(&sess.shell_environment_policy),
+        with_escalated_permissions: params.with_escalated_permissions,
+        justification: params.justification,
     }
 }
 
@@ -1768,13 +1792,19 @@ async fn handle_container_exec_with_params(
                 cwd: cwd.clone(),
                 timeout_ms: params.timeout_ms,
                 env: HashMap::new(),
+                with_escalated_permissions: params.with_escalated_permissions,
+                justification: params.justification.clone(),
             };
             let safety = if *user_explicitly_approved_this_action {
                 SafetyCheck::AutoApprove {
                     sandbox_type: SandboxType::None,
                 }
             } else {
-                assess_safety_for_untrusted_command(sess.approval_policy, &sess.sandbox_policy)
+                assess_safety_for_untrusted_command(
+                    sess.approval_policy,
+                    &sess.sandbox_policy,
+                    params.with_escalated_permissions.unwrap_or(false),
+                )
             };
             (
                 params,
@@ -1790,6 +1820,7 @@ async fn handle_container_exec_with_params(
                     sess.approval_policy,
                     &sess.sandbox_policy,
                     &state.approved_commands,
+                    params.with_escalated_permissions.unwrap_or(false),
                 )
             };
             let command_for_display = params.command.clone();
@@ -1806,7 +1837,7 @@ async fn handle_container_exec_with_params(
                     call_id.clone(),
                     params.command.clone(),
                     params.cwd.clone(),
-                    None,
+                    params.justification.clone(),
                 )
                 .await;
             match rx_approve.await.unwrap_or_default() {
@@ -1944,13 +1975,31 @@ async fn handle_sandbox_error(
     let cwd = exec_command_context.cwd.clone();
     let is_apply_patch = exec_command_context.apply_patch.is_some();
 
-    // Early out if the user never wants to be asked for approval; just return to the model immediately
-    if sess.approval_policy == AskForApproval::Never {
+    // Early out if either the user never wants to be asked for approval, or
+    // we're letting the model manage escalation requests. Otherwise, continue
+    match sess.approval_policy {
+        AskForApproval::Never | AskForApproval::OnRequest => {
+            return ResponseInputItem::FunctionCallOutput {
+                call_id,
+                output: FunctionCallOutputPayload {
+                    content: format!(
+                        "failed in sandbox {sandbox_type:?} with execution error: {error}"
+                    ),
+                    success: Some(false),
+                },
+            };
+        }
+        AskForApproval::UnlessTrusted | AskForApproval::OnFailure => (),
+    }
+
+    // similarly, if the command timed out, we can simply return this failure to the model
+    if matches!(error, SandboxErr::Timeout) {
         return ResponseInputItem::FunctionCallOutput {
             call_id,
             output: FunctionCallOutputPayload {
                 content: format!(
-                    "failed in sandbox {sandbox_type:?} with execution error: {error}"
+                    "command timed out after {} milliseconds",
+                    params.timeout_duration().as_millis()
                 ),
                 success: Some(false),
             },

codex-rs/core/src/config.rs

@@ -70,7 +70,7 @@ pub struct Config {
     /// who have opted into Zero Data Retention (ZDR).
     pub disable_response_storage: bool,
 
-    /// User-provided instructions from instructions.md.
+    /// User-provided instructions from AGENTS.md.
     pub user_instructions: Option<String>,
 
     /// Base instructions override.
@@ -385,8 +385,8 @@ pub struct ConfigOverrides {
     pub codex_linux_sandbox_exe: Option<PathBuf>,
     pub base_instructions: Option<String>,
     pub include_plan_tool: Option<bool>,
-    pub default_disable_response_storage: Option<bool>,
-    pub default_show_raw_agent_reasoning: Option<bool>,
+    pub disable_response_storage: Option<bool>,
+    pub show_raw_agent_reasoning: Option<bool>,
 }
 
 impl Config {
@@ -410,8 +410,8 @@ impl Config {
             codex_linux_sandbox_exe,
             base_instructions,
             include_plan_tool,
-            default_disable_response_storage,
-            default_show_raw_agent_reasoning,
+            disable_response_storage,
+            show_raw_agent_reasoning,
         } = overrides;
 
         let config_profile = match config_profile_key.as_ref().or(cfg.profile.as_ref()) {
@@ -529,7 +529,7 @@ impl Config {
             disable_response_storage: config_profile
                 .disable_response_storage
                 .or(cfg.disable_response_storage)
-                .or(default_disable_response_storage)
+                .or(disable_response_storage)
                 .unwrap_or(false),
             notify: cfg.notify,
             user_instructions,
@@ -546,7 +546,7 @@ impl Config {
             hide_agent_reasoning: cfg.hide_agent_reasoning.unwrap_or(false),
             show_raw_agent_reasoning: cfg
                 .show_raw_agent_reasoning
-                .or(default_show_raw_agent_reasoning)
+                .or(show_raw_agent_reasoning)
                 .unwrap_or(false),
             model_reasoning_effort: config_profile
                 .model_reasoning_effort
@@ -575,7 +575,7 @@ impl Config {
             None => return None,
         };
 
-        p.push("instructions.md");
+        p.push("AGENTS.md");
         std::fs::read_to_string(&p).ok().and_then(|s| {
             let s = s.trim();
             if s.is_empty() {
@@ -842,7 +842,7 @@ disable_response_storage = true
             request_max_retries: Some(4),
             stream_max_retries: Some(10),
             stream_idle_timeout_ms: Some(300_000),
-            requires_auth: false,
+            requires_openai_auth: false,
         };
         let model_provider_map = {
             let mut model_provider_map = built_in_model_providers();

codex-rs/core/src/exec.rs

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

codex-rs/core/src/git_info.rs

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

codex-rs/core/src/lib.rs

@@ -48,6 +48,5 @@ pub mod spawn;
 pub mod turn_diff_tracker;
 mod user_notification;
 pub mod util;
-
 pub use apply_patch::CODEX_APPLY_PATCH_ARG1;
 pub use safety::get_platform_sandbox;

codex-rs/core/src/model_provider_info.rs

@@ -9,7 +9,6 @@ use codex_login::AuthMode;
 use codex_login::CodexAuth;
 use serde::Deserialize;
 use serde::Serialize;
-use std::borrow::Cow;
 use std::collections::HashMap;
 use std::env::VarError;
 use std::time::Duration;
@@ -79,7 +78,7 @@ pub struct ModelProviderInfo {
 
     /// Whether this provider requires some form of standard authentication (API key, ChatGPT token).
     #[serde(default)]
-    pub requires_auth: bool,
+    pub requires_openai_auth: bool,
 }
 
 impl ModelProviderInfo {
@@ -87,26 +86,32 @@ impl ModelProviderInfo {
     /// reqwest Client applying:
     ///   • provider-specific headers (static + env based)
     ///   • Bearer auth header when an API key is available.
+    ///   • Auth token for OAuth.
     ///
-    /// When `require_api_key` is true and the provider declares an `env_key`
-    /// but the variable is missing/empty, returns an [`Err`] identical to the
+    /// If the provider declares an `env_key` but the variable is missing/empty, returns an [`Err`] identical to the
     /// one produced by [`ModelProviderInfo::api_key`].
     pub async fn create_request_builder<'a>(
         &'a self,
         client: &'a reqwest::Client,
         auth: &Option<CodexAuth>,
     ) -> crate::error::Result<reqwest::RequestBuilder> {
-        let auth: Cow<'_, Option<CodexAuth>> = if auth.is_some() {
-            Cow::Borrowed(auth)
-        } else {
-            Cow::Owned(self.get_fallback_auth()?)
+        let effective_auth = match self.api_key() {
+            Ok(Some(key)) => Some(CodexAuth::from_api_key(key)),
+            Ok(None) => auth.clone(),
+            Err(err) => {
+                if auth.is_some() {
+                    auth.clone()
+                } else {
+                    return Err(err);
+                }
+            }
         };
 
-        let url = self.get_full_url(&auth);
+        let url = self.get_full_url(&effective_auth);
 
         let mut builder = client.post(url);
 
-        if let Some(auth) = auth.as_ref() {
+        if let Some(auth) = effective_auth.as_ref() {
             builder = builder.bearer_auth(auth.get_token().await?);
         }
 
@@ -216,14 +221,6 @@ impl ModelProviderInfo {
             .map(Duration::from_millis)
             .unwrap_or(Duration::from_millis(DEFAULT_STREAM_IDLE_TIMEOUT_MS))
     }
-
-    fn get_fallback_auth(&self) -> crate::error::Result<Option<CodexAuth>> {
-        let api_key = self.api_key()?;
-        if let Some(api_key) = api_key {
-            return Ok(Some(CodexAuth::from_api_key(api_key)));
-        }
-        Ok(None)
-    }
 }
 
 const DEFAULT_OLLAMA_PORT: u32 = 11434;
@@ -275,7 +272,7 @@ pub fn built_in_model_providers() -> HashMap<String, ModelProviderInfo> {
                 request_max_retries: None,
                 stream_max_retries: None,
                 stream_idle_timeout_ms: None,
-                requires_auth: true,
+                requires_openai_auth: true,
             },
         ),
         (BUILT_IN_OSS_MODEL_PROVIDER_ID, create_oss_provider()),
@@ -319,7 +316,7 @@ pub fn create_oss_provider_with_base_url(base_url: &str) -> ModelProviderInfo {
         request_max_retries: None,
         stream_max_retries: None,
         stream_idle_timeout_ms: None,
-        requires_auth: false,
+        requires_openai_auth: false,
     }
 }
 
@@ -347,7 +344,7 @@ base_url = "http://localhost:11434/v1"
             request_max_retries: None,
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
@@ -376,7 +373,7 @@ query_params = { api-version = "2025-04-01-preview" }
             request_max_retries: None,
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
@@ -408,7 +405,7 @@ env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" }
             request_max_retries: None,
             stream_max_retries: None,
             stream_idle_timeout_ms: None,
-            requires_auth: false,
+            requires_openai_auth: false,
         };
 
         let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();

codex-rs/core/src/models.rs

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

codex-rs/core/src/openai_model_info.rs

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

codex-rs/core/src/openai_tools.rs

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

codex-rs/core/src/plan_tool.rs

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

codex-rs/core/src/protocol.rs

@@ -150,13 +150,17 @@ pub enum AskForApproval {
     /// the user to approve execution without a sandbox.
     OnFailure,
 
+    /// The model decides when to ask the user for approval.
+    OnRequest,
+
     /// Never ask the user to approve commands. Failures are immediately returned
     /// to the model, and never escalated to the user for approval.
     Never,
 }
 
 /// Determines execution restrictions for model shell commands.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Display)]
+#[strum(serialize_all = "kebab-case")]
 #[serde(tag = "mode", rename_all = "kebab-case")]
 pub enum SandboxPolicy {
     /// No restrictions whatsoever. Use with caution.

codex-rs/core/src/safety.rs

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

codex-rs/core/src/shell.rs

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

codex-rs/core/tests/client.rs

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

codex-rs/core/tests/exec.rs

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

codex-rs/core/tests/exec_stream_events.rs

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

codex-rs/core/tests/stream_no_completed.rs

@@ -90,7 +90,7 @@ async fn retries_on_early_close() {
         request_max_retries: Some(0),
         stream_max_retries: Some(1),
         stream_idle_timeout_ms: Some(2000),
-        requires_auth: false,
+        requires_openai_auth: false,
     };
 
     let ctrl_c = std::sync::Arc::new(tokio::sync::Notify::new());

codex-rs/exec/src/event_processor.rs

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

codex-rs/exec/src/event_processor_with_human_output.rs

@@ -33,8 +33,8 @@ use std::time::Instant;
 
 use crate::event_processor::CodexStatus;
 use crate::event_processor::EventProcessor;
-use crate::event_processor::create_config_summary_entries;
 use crate::event_processor::handle_last_message;
+use codex_common::create_config_summary_entries;
 
 /// This should be configurable. When used in CI, users may not want to impose
 /// a limit so they can see the full transcript.

codex-rs/exec/src/event_processor_with_json_output.rs

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

codex-rs/exec/src/lib.rs

@@ -147,8 +147,8 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         codex_linux_sandbox_exe,
         base_instructions: None,
         include_plan_tool: None,
-        default_disable_response_storage: oss.then_some(true),
-        default_show_raw_agent_reasoning: oss.then_some(true),
+        disable_response_storage: oss.then_some(true),
+        show_raw_agent_reasoning: oss.then_some(true),
     };
     // Parse `-c` overrides.
     let cli_kv_overrides = match config_overrides.parse_overrides() {
@@ -216,10 +216,16 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
                     res = codex.next_event() => match res {
                         Ok(event) => {
                             debug!("Received event: {event:?}");
+
+                            let is_shutdown_complete = matches!(event.msg, EventMsg::ShutdownComplete);
                             if let Err(e) = tx.send(event) {
                                 error!("Error sending event: {e:?}");
                                 break;
                             }
+                            if is_shutdown_complete {
+                                info!("Received shutdown event, exiting event loop.");
+                                break;
+                            }
                         },
                         Err(e) => {
                             error!("Error receiving event: {e:?}");

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

@@ -44,6 +44,8 @@ async fn run_cmd(cmd: &[&str], writable_roots: &[PathBuf], timeout_ms: u64) {
         cwd: std::env::current_dir().expect("cwd should exist"),
         timeout_ms: Some(timeout_ms),
         env: create_env_from_core_vars(),
+        with_escalated_permissions: None,
+        justification: None,
     };
 
     let sandbox_policy = SandboxPolicy::WorkspaceWrite {
@@ -139,6 +141,8 @@ async fn assert_network_blocked(cmd: &[&str]) {
         // do not stall the suite.
         timeout_ms: Some(NETWORK_TIMEOUT_MS),
         env: create_env_from_core_vars(),
+        with_escalated_permissions: None,
+        justification: None,
     };
 
     let sandbox_policy = SandboxPolicy::new_read_only_policy();

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

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

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

@@ -59,8 +59,8 @@ pub(crate) async fn handle_create_conversation(
         codex_linux_sandbox_exe: None,
         base_instructions,
         include_plan_tool: None,
-        default_disable_response_storage: None,
-        default_show_raw_agent_reasoning: None,
+        disable_response_storage: None,
+        show_raw_agent_reasoning: None,
     };
 
     let cfg: CodexConfig = match CodexConfig::load_with_cli_overrides(cli_overrides, overrides) {

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

@@ -18,7 +18,7 @@ use tokio::time::timeout;
 
 const DEFAULT_READ_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+#[tokio::test]
 async fn test_send_message_success() {
     // Spin up a mock completions server that immediately ends the Codex turn.
     // Two Codex turns hit the mock model (session start + send-user-message). Provide two SSE responses.
@@ -99,13 +99,13 @@ async fn test_send_message_success() {
         response
     );
     // wait for the server to hear the user message
-    sleep(Duration::from_secs(1));
+    sleep(Duration::from_secs(5));
 
     // Ensure the server and tempdir live until end of test
     drop(server);
 }
 
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+#[tokio::test]
 async fn test_send_message_session_not_found() {
     // Start MCP without creating a Codex session
     let codex_home = TempDir::new().expect("tempdir");

codex-rs/scripts/create_github_release.sh

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

codex-rs/tui/prompt_for_init_command.md

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

codex-rs/tui/src/app.rs

@@ -233,7 +233,8 @@ impl App<'_> {
                                     widget.on_ctrl_c();
                                 }
                                 AppState::GitWarning { .. } => {
-                                    // No-op.
+                                    // Allow exiting the app with Ctrl+C from the warning screen.
+                                    self.app_event_tx.send(AppEvent::ExitRequest);
                                 }
                             }
                         }
@@ -299,6 +300,13 @@ impl App<'_> {
                         self.app_state = AppState::Chat { widget: new_widget };
                         self.app_event_tx.send(AppEvent::RequestRedraw);
                     }
+                    SlashCommand::Init => {
+                        // Guard: do not run if a task is active.
+                        if let AppState::Chat { widget } = &mut self.app_state {
+                            const INIT_PROMPT: &str = include_str!("../prompt_for_init_command.md");
+                            widget.submit_text_message(INIT_PROMPT.to_string());
+                        }
+                    }
                     SlashCommand::Compact => {
                         if let AppState::Chat { widget } = &mut self.app_state {
                             widget.clear_token_usage();
@@ -329,6 +337,11 @@ impl App<'_> {
                             widget.add_diff_output(text);
                         }
                     }
+                    SlashCommand::Status => {
+                        if let AppState::Chat { widget } = &mut self.app_state {
+                            widget.add_status_output();
+                        }
+                    }
                     #[cfg(debug_assertions)]
                     SlashCommand::TestApproval => {
                         use std::collections::HashMap;
@@ -415,7 +428,7 @@ impl App<'_> {
         let size = terminal.size()?;
         let desired_height = match &self.app_state {
             AppState::Chat { widget } => widget.desired_height(size.width),
-            AppState::GitWarning { .. } => 10,
+            AppState::GitWarning { .. } => size.height,
         };
 
         let mut area = terminal.viewport_area;

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

@@ -729,6 +729,7 @@ impl WidgetRef for &ChatComposer {
 
 #[cfg(test)]
 mod tests {
+    use crate::app_event::AppEvent;
     use crate::bottom_pane::AppEventSender;
     use crate::bottom_pane::ChatComposer;
     use crate::bottom_pane::InputResult;
@@ -1004,6 +1005,49 @@ mod tests {
         }
     }
 
+    #[test]
+    fn slash_init_dispatches_command_and_does_not_submit_literal_text() {
+        use crossterm::event::KeyCode;
+        use crossterm::event::KeyEvent;
+        use crossterm::event::KeyModifiers;
+        use std::sync::mpsc::TryRecvError;
+
+        let (tx, rx) = std::sync::mpsc::channel();
+        let sender = AppEventSender::new(tx);
+        let mut composer = ChatComposer::new(true, sender, false);
+
+        // Type the slash command.
+        for ch in [
+            '/', 'i', 'n', 'i', 't', // "/init"
+        ] {
+            let _ = composer.handle_key_event(KeyEvent::new(KeyCode::Char(ch), KeyModifiers::NONE));
+        }
+
+        // Press Enter to dispatch the selected command.
+        let (result, _needs_redraw) =
+            composer.handle_key_event(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE));
+
+        // When a slash command is dispatched, the composer should not submit
+        // literal text and should clear its textarea.
+        match result {
+            InputResult::None => {}
+            InputResult::Submitted(text) => {
+                panic!("expected command dispatch, but composer submitted literal text: {text}")
+            }
+        }
+        assert!(composer.textarea.is_empty(), "composer should be cleared");
+
+        // Verify a DispatchCommand event for the "init" command was sent.
+        match rx.try_recv() {
+            Ok(AppEvent::DispatchCommand(cmd)) => {
+                assert_eq!(cmd.command(), "init");
+            }
+            Ok(_other) => panic!("unexpected app event"),
+            Err(TryRecvError::Empty) => panic!("expected a DispatchCommand event for '/init'"),
+            Err(TryRecvError::Disconnected) => panic!("app event channel disconnected"),
+        }
+    }
+
     #[test]
     fn test_multiple_pastes_submission() {
         use crossterm::event::KeyCode;

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

@@ -188,3 +188,38 @@ impl WidgetRef for CommandPopup {
         table.render(area, buf);
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn filter_includes_init_when_typing_prefix() {
+        let mut popup = CommandPopup::new();
+        // Simulate the composer line starting with '/in' so the popup filters
+        // matching commands by prefix.
+        popup.on_composer_text_change("/in".to_string());
+
+        // Access the filtered list via the selected command and ensure that
+        // one of the matches is the new "init" command.
+        let matches = popup.filtered_commands();
+        assert!(
+            matches.iter().any(|cmd| cmd.command() == "init"),
+            "expected '/init' to appear among filtered commands"
+        );
+    }
+
+    #[test]
+    fn selecting_init_by_exact_match() {
+        let mut popup = CommandPopup::new();
+        popup.on_composer_text_change("/init".to_string());
+
+        // When an exact match exists, the selected command should be that
+        // command by default.
+        let selected = popup.selected_command();
+        match selected {
+            Some(cmd) => assert_eq!(cmd.command(), "init"),
+            None => panic!("expected a selected command for exact match"),
+        }
+    }
+}

codex-rs/tui/src/chatwidget.rs

@@ -12,6 +12,7 @@ use codex_core::protocol::AgentReasoningEvent;
 use codex_core::protocol::AgentReasoningRawContentDeltaEvent;
 use codex_core::protocol::AgentReasoningRawContentEvent;
 use codex_core::protocol::ApplyPatchApprovalRequestEvent;
+use codex_core::protocol::BackgroundEventEvent;
 use codex_core::protocol::ErrorEvent;
 use codex_core::protocol::Event;
 use codex_core::protocol::EventMsg;
@@ -25,14 +26,18 @@ use codex_core::protocol::Op;
 use codex_core::protocol::PatchApplyBeginEvent;
 use codex_core::protocol::TaskCompleteEvent;
 use codex_core::protocol::TokenUsage;
+use codex_core::protocol::TurnDiffEvent;
 use crossterm::event::KeyEvent;
 use crossterm::event::KeyEventKind;
 use ratatui::buffer::Buffer;
+use ratatui::layout::Constraint;
+use ratatui::layout::Layout;
 use ratatui::layout::Rect;
 use ratatui::widgets::Widget;
 use ratatui::widgets::WidgetRef;
 use tokio::sync::mpsc::UnboundedSender;
 use tokio::sync::mpsc::unbounded_channel;
+use tracing::info;
 
 use crate::app_event::AppEvent;
 use crate::app_event_sender::AppEventSender;
@@ -59,6 +64,7 @@ pub(crate) struct ChatWidget<'a> {
     app_event_tx: AppEventSender,
     codex_op_tx: UnboundedSender<Op>,
     bottom_pane: BottomPane<'a>,
+    active_history_cell: Option<HistoryCell>,
     config: Config,
     initial_user_message: Option<UserMessage>,
     token_usage: TokenUsage,
@@ -104,6 +110,17 @@ fn create_initial_user_message(text: String, image_paths: Vec<PathBuf>) -> Optio
 }
 
 impl ChatWidget<'_> {
+    fn layout_areas(&self, area: Rect) -> [Rect; 2] {
+        Layout::vertical([
+            Constraint::Max(
+                self.active_history_cell
+                    .as_ref()
+                    .map_or(0, |c| c.desired_height(area.width)),
+            ),
+            Constraint::Min(self.bottom_pane.desired_height(area.width)),
+        ])
+        .areas(area)
+    }
     fn emit_stream_header(&mut self, kind: StreamKind) {
         use ratatui::text::Line as RLine;
         if self.stream_header_emitted {
@@ -175,6 +192,7 @@ impl ChatWidget<'_> {
                 has_input_focus: true,
                 enhanced_keys_supported,
             }),
+            active_history_cell: None,
             config,
             initial_user_message: create_initial_user_message(
                 initial_prompt.unwrap_or_default(),
@@ -194,6 +212,10 @@ impl ChatWidget<'_> {
 
     pub fn desired_height(&self, width: u16) -> u16 {
         self.bottom_pane.desired_height(width)
+            + self
+                .active_history_cell
+                .as_ref()
+                .map_or(0, |c| c.desired_height(width))
     }
 
     pub(crate) fn handle_key_event(&mut self, key_event: KeyEvent) {
@@ -422,9 +444,11 @@ impl ChatWidget<'_> {
                         cwd: cwd.clone(),
                     },
                 );
-                self.add_to_history(HistoryCell::new_active_exec_command(command));
+                self.active_history_cell = Some(HistoryCell::new_active_exec_command(command));
+            }
+            EventMsg::ExecCommandOutputDelta(_) => {
+                // TODO
             }
-            EventMsg::ExecCommandOutputDelta(_) => {}
             EventMsg::PatchApplyBegin(PatchApplyBeginEvent {
                 call_id: _,
                 auto_approved,
@@ -435,6 +459,13 @@ impl ChatWidget<'_> {
                     changes,
                 ));
             }
+            EventMsg::PatchApplyEnd(event) => {
+                self.add_to_history(HistoryCell::new_patch_apply_end(
+                    event.stdout,
+                    event.stderr,
+                    event.success,
+                ));
+            }
             EventMsg::ExecCommandEnd(ExecCommandEndEvent {
                 call_id,
                 exit_code,
@@ -444,6 +475,7 @@ impl ChatWidget<'_> {
             }) => {
                 // Compute summary before moving stdout into the history cell.
                 let cmd = self.running_commands.remove(&call_id);
+                self.active_history_cell = None;
                 self.add_to_history(HistoryCell::new_completed_exec_command(
                     cmd.map(|cmd| cmd.command).unwrap_or_else(|| vec![call_id]),
                     CommandOutput {
@@ -492,10 +524,11 @@ impl ChatWidget<'_> {
             EventMsg::ShutdownComplete => {
                 self.app_event_tx.send(AppEvent::ExitRequest);
             }
-            event => {
-                let text = format!("{event:?}");
-                self.add_to_history(HistoryCell::new_background_event(text.clone()));
-                self.update_latest_log(text);
+            EventMsg::TurnDiff(TurnDiffEvent { unified_diff }) => {
+                info!("TurnDiffEvent: {unified_diff}");
+            }
+            EventMsg::BackgroundEvent(BackgroundEventEvent { message }) => {
+                info!("BackgroundEvent: {message}");
             }
         }
     }
@@ -515,6 +548,13 @@ impl ChatWidget<'_> {
         self.add_to_history(HistoryCell::new_diff_output(diff_output.clone()));
     }
 
+    pub(crate) fn add_status_output(&mut self) {
+        self.add_to_history(HistoryCell::new_status_output(
+            &self.config,
+            &self.token_usage,
+        ));
+    }
+
     /// Forward file-search results to the bottom pane.
     pub(crate) fn apply_file_search_result(&mut self, query: String, matches: Vec<FileMatch>) {
         self.bottom_pane.on_file_search_result(query, matches);
@@ -529,6 +569,7 @@ impl ChatWidget<'_> {
             CancellationEvent::Ignored => {}
         }
         if self.bottom_pane.is_task_running() {
+            self.active_history_cell = None;
             self.bottom_pane.clear_ctrl_c_quit_hint();
             self.submit_op(Op::Interrupt);
             self.bottom_pane.set_task_running(false);
@@ -561,6 +602,16 @@ impl ChatWidget<'_> {
         }
     }
 
+    /// Programmatically submit a user text message as if typed in the
+    /// composer. The text will be added to conversation history and sent to
+    /// the agent.
+    pub(crate) fn submit_text_message(&mut self, text: String) {
+        if text.is_empty() {
+            return;
+        }
+        self.submit_user_message(text.into());
+    }
+
     pub(crate) fn token_usage(&self) -> &TokenUsage {
         &self.token_usage
     }
@@ -572,7 +623,8 @@ impl ChatWidget<'_> {
     }
 
     pub fn cursor_pos(&self, area: Rect) -> Option<(u16, u16)> {
-        self.bottom_pane.cursor_pos(area)
+        let [_, bottom_pane_area] = self.layout_areas(area);
+        self.bottom_pane.cursor_pos(bottom_pane_area)
     }
 }
 
@@ -676,10 +728,11 @@ impl ChatWidget<'_> {
 
 impl WidgetRef for &ChatWidget<'_> {
     fn render_ref(&self, area: Rect, buf: &mut Buffer) {
-        // In the hybrid inline viewport mode we only draw the interactive
-        // bottom pane; history entries are injected directly into scrollback
-        // via `Terminal::insert_before`.
-        (&self.bottom_pane).render(area, buf);
+        let [active_cell_area, bottom_pane_area] = self.layout_areas(area);
+        (&self.bottom_pane).render(bottom_pane_area, buf);
+        if let Some(cell) = &self.active_history_cell {
+            cell.render_ref(active_cell_area, buf);
+        }
     }
 }
 

codex-rs/tui/src/history_cell.rs

@@ -3,9 +3,8 @@ use crate::text_block::TextBlock;
 use crate::text_formatting::format_and_truncate_tool_result;
 use base64::Engine;
 use codex_ansi_escape::ansi_escape_line;
+use codex_common::create_config_summary_entries;
 use codex_common::elapsed::format_duration;
-use codex_common::summarize_sandbox_policy;
-use codex_core::WireApi;
 use codex_core::config::Config;
 use codex_core::plan_tool::PlanItemArg;
 use codex_core::plan_tool::StepStatus;
@@ -13,6 +12,7 @@ use codex_core::plan_tool::UpdatePlanArgs;
 use codex_core::protocol::FileChange;
 use codex_core::protocol::McpInvocation;
 use codex_core::protocol::SessionConfiguredEvent;
+use codex_core::protocol::TokenUsage;
 use image::DynamicImage;
 use image::ImageReader;
 use mcp_types::EmbeddedResourceResource;
@@ -23,6 +23,9 @@ use ratatui::style::Modifier;
 use ratatui::style::Style;
 use ratatui::text::Line as RtLine;
 use ratatui::text::Span as RtSpan;
+use ratatui::widgets::Paragraph;
+use ratatui::widgets::WidgetRef;
+use ratatui::widgets::Wrap;
 use std::collections::HashMap;
 use std::io::Cursor;
 use std::path::PathBuf;
@@ -95,6 +98,9 @@ pub(crate) enum HistoryCell {
     /// Output from the `/diff` command.
     GitDiffOutput { view: TextBlock },
 
+    /// Output from the `/status` command.
+    StatusOutput { view: TextBlock },
+
     /// Error event from the backend.
     ErrorEvent { view: TextBlock },
 
@@ -109,6 +115,9 @@ pub(crate) enum HistoryCell {
     /// A human‑friendly rendering of the model's current plan and step
     /// statuses provided via the `update_plan` tool.
     PlanUpdate { view: TextBlock },
+
+    /// Result of applying a patch (success or failure) with optional output.
+    PatchApplyResult { view: TextBlock },
 }
 
 const TOOL_CALL_MAX_LINES: usize = 5;
@@ -123,12 +132,14 @@ impl HistoryCell {
             | HistoryCell::UserPrompt { view }
             | HistoryCell::BackgroundEvent { view }
             | HistoryCell::GitDiffOutput { view }
+            | HistoryCell::StatusOutput { view }
             | HistoryCell::ErrorEvent { view }
             | HistoryCell::SessionInfo { view }
             | HistoryCell::CompletedExecCommand { view }
             | HistoryCell::CompletedMcpToolCall { view }
             | HistoryCell::PendingPatch { view }
             | HistoryCell::PlanUpdate { view }
+            | HistoryCell::PatchApplyResult { view }
             | HistoryCell::ActiveExecCommand { view, .. }
             | HistoryCell::ActiveMcpToolCall { view, .. } => {
                 view.lines.iter().map(line_to_static).collect()
@@ -139,6 +150,15 @@ impl HistoryCell {
             ],
         }
     }
+
+    pub(crate) fn desired_height(&self, width: u16) -> u16 {
+        Paragraph::new(Text::from(self.plain_lines()))
+            .wrap(Wrap { trim: false })
+            .line_count(width)
+            .try_into()
+            .unwrap_or(0)
+    }
+
     pub(crate) fn new_session_info(
         config: &Config,
         event: SessionConfiguredEvent,
@@ -168,26 +188,7 @@ impl HistoryCell {
                 ]),
             ];
 
-            let mut entries = vec![
-                ("workdir", config.cwd.display().to_string()),
-                ("model", config.model.clone()),
-                ("provider", config.model_provider_id.clone()),
-                ("approval", config.approval_policy.to_string()),
-                ("sandbox", summarize_sandbox_policy(&config.sandbox_policy)),
-            ];
-            if config.model_provider.wire_api == WireApi::Responses
-                && config.model_family.supports_reasoning_summaries
-            {
-                entries.push((
-                    "reasoning effort",
-                    config.model_reasoning_effort.to_string(),
-                ));
-                entries.push((
-                    "reasoning summaries",
-                    config.model_reasoning_summary.to_string(),
-                ));
-            }
-            for (key, value) in entries {
+            for (key, value) in create_config_summary_entries(config) {
                 lines.push(Line::from(vec![format!("{key}: ").bold(), value.into()]));
             }
             lines.push(Line::from(""));
@@ -444,6 +445,49 @@ impl HistoryCell {
         }
     }
 
+    pub(crate) fn new_status_output(config: &Config, usage: &TokenUsage) -> Self {
+        let mut lines: Vec<Line<'static>> = Vec::new();
+        lines.push(Line::from("/status".magenta()));
+
+        // Config
+        for (key, value) in create_config_summary_entries(config) {
+            lines.push(Line::from(vec![format!("{key}: ").bold(), value.into()]));
+        }
+
+        // Token usage
+        lines.push(Line::from(""));
+        lines.push(Line::from("token usage".bold()));
+        lines.push(Line::from(vec![
+            "  input: ".bold(),
+            usage.input_tokens.to_string().into(),
+        ]));
+        lines.push(Line::from(vec![
+            "  cached input: ".bold(),
+            usage.cached_input_tokens.unwrap_or(0).to_string().into(),
+        ]));
+        lines.push(Line::from(vec![
+            "  output: ".bold(),
+            usage.output_tokens.to_string().into(),
+        ]));
+        lines.push(Line::from(vec![
+            "  reasoning output: ".bold(),
+            usage
+                .reasoning_output_tokens
+                .unwrap_or(0)
+                .to_string()
+                .into(),
+        ]));
+        lines.push(Line::from(vec![
+            "  total: ".bold(),
+            usage.total_tokens.to_string().into(),
+        ]));
+
+        lines.push(Line::from(""));
+        HistoryCell::StatusOutput {
+            view: TextBlock::new(lines),
+        }
+    }
+
     pub(crate) fn new_error_event(message: String) -> Self {
         let lines: Vec<Line<'static>> = vec![
             vec!["ERROR: ".red().bold(), message.into()].into(),
@@ -550,7 +594,10 @@ impl HistoryCell {
             PatchEventType::ApplyBegin {
                 auto_approved: false,
             } => {
-                let lines = vec![Line::from("patch applied".magenta().bold())];
+                let lines: Vec<Line<'static>> = vec![
+                    Line::from("applying patch".magenta().bold()),
+                    Line::from(""),
+                ];
                 return Self::PendingPatch {
                     view: TextBlock::new(lines),
                 };
@@ -598,6 +645,62 @@ impl HistoryCell {
             view: TextBlock::new(lines),
         }
     }
+
+    pub(crate) fn new_patch_apply_end(stdout: String, stderr: String, success: bool) -> Self {
+        let mut lines: Vec<Line<'static>> = Vec::new();
+
+        let status = if success {
+            RtSpan::styled("patch applied", Style::default().fg(Color::Green))
+        } else {
+            RtSpan::styled(
+                "patch failed",
+                Style::default().fg(Color::Red).add_modifier(Modifier::BOLD),
+            )
+        };
+        lines.push(RtLine::from(vec![
+            "patch".magenta().bold(),
+            " ".into(),
+            status,
+        ]));
+
+        let src = if success {
+            if stdout.trim().is_empty() {
+                &stderr
+            } else {
+                &stdout
+            }
+        } else if stderr.trim().is_empty() {
+            &stdout
+        } else {
+            &stderr
+        };
+
+        if !src.trim().is_empty() {
+            lines.push(Line::from(""));
+            let mut iter = src.lines();
+            for raw in iter.by_ref().take(TOOL_CALL_MAX_LINES) {
+                lines.push(ansi_escape_line(raw).dim());
+            }
+            let remaining = iter.count();
+            if remaining > 0 {
+                lines.push(Line::from(format!("... {remaining} additional lines")).dim());
+            }
+        }
+
+        lines.push(Line::from(""));
+
+        HistoryCell::PatchApplyResult {
+            view: TextBlock::new(lines),
+        }
+    }
+}
+
+impl WidgetRef for &HistoryCell {
+    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
+        Paragraph::new(Text::from(self.plain_lines()))
+            .wrap(Wrap { trim: false })
+            .render(area, buf);
+    }
 }
 
 fn create_diff_summary(changes: HashMap<PathBuf, FileChange>) -> Vec<String> {

codex-rs/tui/src/lib.rs

@@ -101,8 +101,8 @@ pub async fn run_main(
             codex_linux_sandbox_exe,
             base_instructions: None,
             include_plan_tool: Some(true),
-            default_disable_response_storage: cli.oss.then_some(true),
-            default_show_raw_agent_reasoning: cli.oss.then_some(true),
+            disable_response_storage: cli.oss.then_some(true),
+            show_raw_agent_reasoning: cli.oss.then_some(true),
         };
         // Parse `-c` overrides from the CLI.
         let cli_kv_overrides = match cli.config_overrides.parse_overrides() {
@@ -287,7 +287,7 @@ fn restore() {
 
 #[allow(clippy::unwrap_used)]
 fn should_show_login_screen(config: &Config) -> bool {
-    if config.model_provider.requires_auth {
+    if config.model_provider.requires_openai_auth {
         // Reading the OpenAI API key is an async operation because it may need
         // to refresh the token. Block on it.
         let codex_home = config.codex_home.clone();

codex-rs/tui/src/slash_command.rs

@@ -13,8 +13,10 @@ pub enum SlashCommand {
     // DO NOT ALPHA-SORT! Enum order is presentation order in the popup, so
     // more frequently used commands should be listed first.
     New,
+    Init,
     Compact,
     Diff,
+    Status,
     Quit,
     #[cfg(debug_assertions)]
     TestApproval,
@@ -24,12 +26,12 @@ impl SlashCommand {
     /// User-visible description shown in the popup.
     pub fn description(self) -> &'static str {
         match self {
-            SlashCommand::New => "Start a new chat.",
-            SlashCommand::Compact => "Compact the chat history.",
-            SlashCommand::Quit => "Exit the application.",
-            SlashCommand::Diff => {
-                "Show git diff of the working directory (including untracked files)"
-            }
+            SlashCommand::New => "Start a new chat",
+            SlashCommand::Init => "Create an AGENTS.md file with instructions for Codex.",
+            SlashCommand::Compact => "Compact the chat history",
+            SlashCommand::Quit => "Exit the application",
+            SlashCommand::Diff => "Show git diff (including untracked files)",
+            SlashCommand::Status => "Show current session configuration and token usage",
             #[cfg(debug_assertions)]
             SlashCommand::TestApproval => "Test approval request",
         }

codex-rs/tui/src/tui.rs

@@ -3,11 +3,14 @@ use std::io::Stdout;
 use std::io::stdout;
 
 use codex_core::config::Config;
+use crossterm::cursor::MoveTo;
 use crossterm::event::DisableBracketedPaste;
 use crossterm::event::EnableBracketedPaste;
 use crossterm::event::KeyboardEnhancementFlags;
 use crossterm::event::PopKeyboardEnhancementFlags;
 use crossterm::event::PushKeyboardEnhancementFlags;
+use crossterm::terminal::Clear;
+use crossterm::terminal::ClearType;
 use ratatui::backend::CrosstermBackend;
 use ratatui::crossterm::execute;
 use ratatui::crossterm::terminal::disable_raw_mode;
@@ -36,6 +39,9 @@ pub fn init(_config: &Config) -> Result<Tui> {
     )?;
     set_panic_hook();
 
+    // Clear screen and move cursor to top-left before drawing UI
+    execute!(stdout(), Clear(ClearType::All), MoveTo(0, 0))?;
+
     let backend = CrosstermBackend::new(stdout());
     let tui = Terminal::with_options(backend)?;
     Ok(tui)

codex-rs/tui/src/user_approval_widget.rs

@@ -47,6 +47,8 @@ pub(crate) enum ApprovalRequest {
 }
 
 /// Options displayed in the *select* mode.
+///
+/// The `key` is matched case-insensitively.
 struct SelectOption {
     label: Line<'static>,
     description: &'static str,
@@ -187,6 +189,16 @@ impl UserApprovalWidget<'_> {
         }
     }
 
+    /// Normalize a key for comparison.
+    /// - For `KeyCode::Char`, converts to lowercase for case-insensitive matching.
+    /// - Other key codes are returned unchanged.
+    fn normalize_keycode(code: KeyCode) -> KeyCode {
+        match code {
+            KeyCode::Char(c) => KeyCode::Char(c.to_ascii_lowercase()),
+            other => other,
+        }
+    }
+
     /// Handle Ctrl-C pressed by the user while the modal is visible.
     /// Behaves like pressing Escape: abort the request and close the modal.
     pub(crate) fn on_ctrl_c(&mut self) {
@@ -210,7 +222,12 @@ impl UserApprovalWidget<'_> {
                 self.send_decision(ReviewDecision::Abort);
             }
             other => {
-                if let Some(opt) = self.select_options.iter().find(|opt| opt.key == other) {
+                let normalized = Self::normalize_keycode(other);
+                if let Some(opt) = self
+                    .select_options
+                    .iter()
+                    .find(|opt| Self::normalize_keycode(opt.key) == normalized)
+                {
                     self.send_decision(opt.decision);
                 }
             }
@@ -330,3 +347,59 @@ impl WidgetRef for &UserApprovalWidget<'_> {
             );
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crossterm::event::KeyCode;
+    use crossterm::event::KeyEvent;
+    use crossterm::event::KeyModifiers;
+    use std::path::PathBuf;
+    use std::sync::mpsc::channel;
+
+    #[test]
+    fn lowercase_shortcut_is_accepted() {
+        let (tx_raw, rx) = channel::<AppEvent>();
+        let tx = AppEventSender::new(tx_raw);
+        let req = ApprovalRequest::Exec {
+            id: "1".to_string(),
+            command: vec!["echo".to_string()],
+            cwd: PathBuf::new(),
+            reason: None,
+        };
+        let mut widget = UserApprovalWidget::new(req, tx);
+        widget.handle_key_event(KeyEvent::new(KeyCode::Char('y'), KeyModifiers::NONE));
+        assert!(widget.is_complete());
+        let events: Vec<AppEvent> = rx.try_iter().collect();
+        assert!(events.iter().any(|e| matches!(
+            e,
+            AppEvent::CodexOp(Op::ExecApproval {
+                decision: ReviewDecision::Approved,
+                ..
+            })
+        )));
+    }
+
+    #[test]
+    fn uppercase_shortcut_is_accepted() {
+        let (tx_raw, rx) = channel::<AppEvent>();
+        let tx = AppEventSender::new(tx_raw);
+        let req = ApprovalRequest::Exec {
+            id: "2".to_string(),
+            command: vec!["echo".to_string()],
+            cwd: PathBuf::new(),
+            reason: None,
+        };
+        let mut widget = UserApprovalWidget::new(req, tx);
+        widget.handle_key_event(KeyEvent::new(KeyCode::Char('Y'), KeyModifiers::NONE));
+        assert!(widget.is_complete());
+        let events: Vec<AppEvent> = rx.try_iter().collect();
+        assert!(events.iter().any(|e| matches!(
+            e,
+            AppEvent::CodexOp(Op::ExecApproval {
+                decision: ReviewDecision::Approved,
+                ..
+            })
+        )));
+    }
+}