[codex] Add new context window tool (#27488)

## Why

The token budget feature tells the model how much room remains in the
current context window. When the model decides the current window is no
longer useful, it needs a way to ask Codex to start over with a fresh
context window without spending tokens on a compaction summary.

This PR adds that model-requestable escape hatch on top of #27438.

## What changed

- Added a direct-model-only `new_context` tool behind
`Feature::TokenBudget`.
- Stores the tool request on `AutoCompactWindow` and consumes it after
sampling so the next follow-up request in the same turn starts in the
new window.
- Starts the new window as a no-summary compaction checkpoint that
contains only fresh initial context, not preserved conversation history.
- Keeps the new window aligned with token-budget startup context,
including the `Current context window Z` message.
- Added integration coverage and a snapshot showing the same-turn
`new_context` flow into a fresh full-context follow-up request.

## Validation

- `just test -p codex-core token_budget`

codex-rs/core/src/tools/handlers/mod.rs

@@ -13,6 +13,8 @@ pub(crate) mod multi_agents;
 pub(crate) mod multi_agents_common;
 pub(crate) mod multi_agents_spec;
 pub(crate) mod multi_agents_v2;
+mod new_context_window;
+pub(crate) mod new_context_window_spec;
 mod plan;
 pub(crate) mod plan_spec;
 mod request_permissions;
@@ -56,6 +58,7 @@ pub use mcp::McpHandler;
 pub use mcp_resource::ListMcpResourceTemplatesHandler;
 pub use mcp_resource::ListMcpResourcesHandler;
 pub use mcp_resource::ReadMcpResourceHandler;
+pub use new_context_window::NewContextWindowHandler;
 pub use plan::PlanHandler;
 pub use request_permissions::RequestPermissionsHandler;
 pub use request_plugin_install::RequestPluginInstallHandler;

codex-rs/core/src/tools/handlers/new_context_window.rs

@@ -0,0 +1,45 @@
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::FunctionToolOutput;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolPayload;
+use crate::tools::context::boxed_tool_output;
+use crate::tools::handlers::new_context_window_spec::NEW_CONTEXT_WINDOW_TOOL_NAME;
+use crate::tools::handlers::new_context_window_spec::create_new_context_window_tool;
+use crate::tools::registry::CoreToolRuntime;
+use crate::tools::registry::ToolExecutor;
+use codex_tools::ToolName;
+use codex_tools::ToolSpec;
+
+pub(crate) const NEW_CONTEXT_WINDOW_MESSAGE: &str =
+    "A new context window will start without summarizing conversation history.";
+
+pub struct NewContextWindowHandler;
+
+impl ToolExecutor<ToolInvocation> for NewContextWindowHandler {
+    fn tool_name(&self) -> ToolName {
+        ToolName::plain(NEW_CONTEXT_WINDOW_TOOL_NAME)
+    }
+
+    fn spec(&self) -> ToolSpec {
+        create_new_context_window_tool()
+    }
+
+    fn handle(&self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'_> {
+        Box::pin(async move {
+            if !matches!(invocation.payload, ToolPayload::Function { .. }) {
+                return Err(FunctionCallError::RespondToModel(
+                    "new_context handler received unsupported payload".to_string(),
+                ));
+            }
+
+            invocation.session.request_new_context_window().await;
+
+            Ok(boxed_tool_output(FunctionToolOutput::from_text(
+                NEW_CONTEXT_WINDOW_MESSAGE.to_string(),
+                Some(true),
+            )))
+        })
+    }
+}
+
+impl CoreToolRuntime for NewContextWindowHandler {}

codex-rs/core/src/tools/handlers/new_context_window_spec.rs

@@ -0,0 +1,17 @@
+use codex_tools::JsonSchema;
+use codex_tools::ResponsesApiTool;
+use codex_tools::ToolSpec;
+use std::collections::BTreeMap;
+
+pub(crate) const NEW_CONTEXT_WINDOW_TOOL_NAME: &str = "new_context";
+
+pub fn create_new_context_window_tool() -> ToolSpec {
+    ToolSpec::Function(ResponsesApiTool {
+        name: NEW_CONTEXT_WINDOW_TOOL_NAME.to_string(),
+        description: "Start a new context window.".to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::object(BTreeMap::new(), /*required*/ None, Some(false.into())),
+        output_schema: None,
+    })
+}

codex-rs/core/src/tools/spec_plan.rs

@@ -13,6 +13,7 @@ use crate::tools::handlers::ListAvailablePluginsToInstallHandler;
 use crate::tools::handlers::ListMcpResourceTemplatesHandler;
 use crate::tools::handlers::ListMcpResourcesHandler;
 use crate::tools::handlers::McpHandler;
+use crate::tools::handlers::NewContextWindowHandler;
 use crate::tools::handlers::PlanHandler;
 use crate::tools::handlers::ReadMcpResourceHandler;
 use crate::tools::handlers::RequestPermissionsHandler;
@@ -659,6 +660,10 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut
         planned_tools.add(RequestPermissionsHandler);
     }
 
+    if features.enabled(Feature::TokenBudget) {
+        planned_tools.add_with_exposure(NewContextWindowHandler, ToolExposure::DirectModelOnly);
+    }
+
     if tool_suggest_enabled(turn_context)
         && let Some(discoverable_tools) =
             context.discoverable_tools.filter(|tools| !tools.is_empty())