## Why
MCP request failures and tool errors reported only through `codex/telemetry` metadata previously received an `unknown` error code, obscuring the failure category.
## What changed
- Classify typed request failures into bounded codes such as `request_timeout`, `transport_closed`, and `protocol_error`, and carry them into MCP call metrics and spans before errors become strings.
- Preserve typed timeouts when a prepared tool call exhausts its deadline during trusted access lookup.
- Accept allowlisted `error_code` values from `codex/telemetry` as a fallback after structured content and connector authentication metadata. Keep model output unchanged and ignore unrecognized metadata codes.
## Testing
Add coverage for typed errors wrapped in context, prepared-call timeout classification, metadata precedence and rejection, unchanged model output, and exported span error attributes.
GitOrigin-RevId: d7a440a6c9119b8a07a7f1fad697eb25af506f00
## Why
MCP servers must forward sandbox policy unchanged to `codex sandbox --sandbox-state-json`, while interpreting launcher information to find the Codex CLI. Keep those contracts separate so consumers can preserve unknown policy fields.
## What changed
- Accept the experimental `codex/sandbox-state` capability alongside the deprecated `codex/sandbox-state-meta` capability, and send identical policy values under both `_meta` keys.
- Move `codexExecutable` out of the policy into `codex/sandbox-launcher`, supplied only when a verified CLI path is available for a local stdio server.
- Replace stale sandbox metadata while retaining unrelated entries, and remove stale launcher metadata when no launcher is available.
- Document the metadata contract and how servers should forward policy and retain authority for long-lived subprocesses.
## Testing
Update unit and integration coverage for policy serialization, identical state aliases, launcher availability across execution environments, and stale metadata replacement.
GitOrigin-RevId: e544c06e6e023953b1fc8069b7b1affa065262d1
## Why
MCP servers receiving sandbox state need a usable Codex executable to launch commands with the issuing call's policy. HTTP and remote servers cannot assume access to the host's filesystem.
## What changed
- Include optional `codexExecutable` metadata for local stdio servers when the host supplies an absolute, UTF-8 path to a CLI supporting `sandbox --sandbox-state-json`. Cache capability probes by executable path and bound them to five seconds.
- Document forwarding the sandbox state unchanged and requiring an explicit opt-out rather than silently falling back to PATH lookup or unsandboxed execution when the launcher is absent.
- Honor `useMxc` from forwarded sandbox state when selecting the Windows sandbox backend and network proxy policies, preserving a parent's selection made through CLI overrides.
## Testing
Add coverage for launcher eligibility across local, remote, and HTTP servers, invalid or missing executable paths, and binaries without sandbox-state support. Extend metadata integration and serialization tests to cover the optional launcher field, legacy state, and unknown future fields.
GitOrigin-RevId: ea8cd3770616e5a620b423a01052a7bc828bceb9
## Why
Prepared MCP calls cloned `ToolInfo` already stored in the binding's model-visible catalog, duplicating tool metadata.
## What changed
Store the binding catalog in an `Arc<[ToolInfo]>` and let prepared calls reference its entries by index. Keep separately owned metadata for tools hidden from the model and calls prepared outside the binding catalog.
## Testing
Extend the binding test to assert that advertised and prepared tool metadata share the same address, while preserving ready-client catalog selection and hidden-tool behavior when tool names collide.
GitOrigin-RevId: 24b92f7e1dbb421c9ebce875b9b1024f7d697c5e
## What changed
Prepare each MCP call from the selected server's current client and catalog instead of building a full runtime binding. Match the advertised tool by server, tool name, and connector ID, and enforce current tool filters and model visibility.
Preserve the advertised `callable_namespace` and `callable_name` while using current schema, annotations, approval metadata, timeout, and permission authority for execution.
GitOrigin-RevId: 703a90926fc72bd446d83ac974162aee6439f363
## Why
Idle Apps clients and cached MCP bindings can retain replaced tool definitions. Shared catalog updates can also invalidate prepared calls even when the current definitions match the captured catalog, including after tools are restored while a call awaits approval.
## What changed
- Share immutable tool arrays across equivalent live discovery contexts and reuse storage for equal results. Let unused providers and cached bindings expire.
- Include requested capabilities and initialization results in the sharing scope, and detach servers that disable catalog caching from live sharing.
- Capture catalog snapshots for prepared calls. Accept equivalent shared catalogs regardless of tool-list order, while rejecting changed definitions and calls captured before an explicit refresh on that client.
## Testing
Add regression coverage for shared storage and scope isolation, release of replaced tools and unused bindings, equivalent catalog restoration, explicit refresh invalidation, and an Apps call completing after catalog restoration while awaiting approval.
GitOrigin-RevId: a0516186e4286d0ff13405fafbab6fcf3f1f3773
## Why
Refreshed Apps catalogs need to survive connection reuse. Catalog revisions scoped to the connection set can lose refreshed tools during reconciliation and invalidate prepared calls for unrelated servers.
## What changed
- Store tools, revisions, and refresh coordination on each MCP client, and key cached bindings by client identity and revision.
- Preserve existing binding snapshots while rejecting stale calls before preparation. Wait for active calls to finish before publishing a refreshed catalog.
- Add `CodexThread::refresh_codex_apps_tools` to reconcile the runtime and return the refreshed client's raw Apps inventory alongside tool names eligible under that runtime's generic MCP policy. Keep hidden and disabled tools in the inventory for callers to apply app-specific policy.
## Testing
Add regression coverage for refreshed catalogs surviving client reuse, unrelated calls remaining valid, binding cache invalidation, and refresh snapshots retaining the client's own inventory when another client wins the shared-cache race. Update stale-call and preparation tests to use client-owned catalogs.
GitOrigin-RevId: f2308c81f7474eb31f3380c091c977030123cda2
## What changed
- Add a positive `output_token_limit` setting to each entry under an MCP server's `tools` configuration.
- Apply the most restrictive limit when plugin and user policies overlap, while keeping approval policy independent.
- Carry the effective MCP output budget in conversation history so tool output, post-tool hook responses, and resumed sessions use the same truncation limit.
## Testing
- Cover configuration parsing, serialization, schema validation, and plugin policy merging.
- Cover MCP output below and above the configured limit, post-tool hook responses, and session resume.
GitOrigin-RevId: d0beb4fca9ba6055d9e1d31c137373b465d50d61
## What changed
- Fetch ChatGPT account access and attach `cyber_trusted_access` under
`openai/entitlementContext` when an installed or selected plugin explicitly
requests it from a local, read-only stdio tool with no arguments.
- Reject caller-supplied entitlement context on direct MCP calls, and fall back
to an `unknown` status when access cannot be verified or the account changes
during the lookup.
- Count entitlement lookup time against the MCP tool-call timeout.
## Testing
- Cover eligible calls plus unowned, remote, HTTP, mutable, argument-bearing,
API-key, undeclared, direct, and account-switch cases in core and app-server
integration tests.
GitOrigin-RevId: 303b61585ef4530276c373d914a2d0ccef1f4ac2
## What changed
- Add optional `McpToolContext` metadata to `ToolStartInput`, exposing the
model-visible MCP tool details and its source classification without exposing
the executable client.
- Classify MCP calls as connectors, configured servers, plugin servers,
executor-selected plugins, or other registrations based on the prepared call.
- Prepare each MCP call before notifying tool lifecycle contributors and reuse
that same call for execution so the callback describes the call that runs.
## Testing
- Cover host-owned connector calls and extension-owned Apps server calls,
including their distinct provenance and executed tool names.
GitOrigin-RevId: efd23f511b1045ffdd96349d621ad62365569b2b
## Why
MCP servers attached to executor environments must retain their owner's
permission profile instead of inheriting the thread-wide sandbox authority.
## What changed
- Resolve and capture a permission profile for each enabled MCP server when
publishing the runtime, and reject calls or elicitations when that authority
is unavailable.
- Use the captured server profile for tool approval decisions, elicitation, and
sandbox metadata, including after runtime refreshes.
- Materialize `:workspace_roots` from `PathUri` values so permissions preserve
the path convention of remote executor environments.
- Give threadless app discovery and resource reads an explicit default
permission profile.
## Testing
Added coverage for per-server elicitation authority, unresolved attachments,
runtime refreshes, restricted tool calls, and foreign-platform workspace roots.
GitOrigin-RevId: 6b188d4b08b29e9971ff7aa68a7785a0cdf9e394
## What changed
- Execute `mcp_tool` hook handlers through the session's shared MCP runtime, including managed hook configurations.
- Restrict hook calls to already-connected, cataloged, and policy-allowed tools. Unavailable servers fail immediately without starting or reconnecting them.
- Pass session metadata to hook tools, cap hook timeouts by the server timeout, and invoke hooks without model-tool approval or recursive hook dispatch.
- Record handler type and execution mode in hook telemetry, and mark memory as externally influenced after successful or blocking MCP hooks when configured.
## Testing
- Added end-to-end coverage for prompt interpolation, hidden tools, blocking decisions, unavailable servers, thread metadata, approval bypass, and memory-mode handling.
- Added MCP runtime coverage for startup readiness, tool filters, catalog revisions, and managed connector policy.
GitOrigin-RevId: 1647cb801ebc5fa385c7bda9d9c266a389c611b8
## Why
App widgets need to read resources using the app and account context of the
tool call that produced them, including after a thread is restored.
## What changed
- Add an optional `originCallId` to `mcpServer/resource/read` requests and
return it on successful scoped reads.
- Track bounded provenance for successful app tool calls in thread history and
use the current tool binding, account link, and app policy when reading the
associated widget resource.
- Reject missing, mismatched, failed, or ambiguous origins, while keeping
app-only tools available for widget reads without exposing them to the model.
## Testing
Add app-server coverage for scoped widget reads across both history modes,
ephemeral and persistent threads, server restarts, app-only visibility, and
invalid origin cases.
GitOrigin-RevId: 11eaefc066b2a3b639599e4cbdef680233d150a2
## What changed
- Cache an `McpBinding` on each published MCP runtime once server startup has
settled and the tool catalog revision is stable.
- Reuse the cached binding while the catalog revision remains unchanged, and
rebuild it after a runtime publish or catalog change.
- Treat terminal failures from optional servers as stable, while continuing to
wait for required servers and reconnecting Codex Apps servers.
## Testing
- Cover binding reuse within one published runtime and invalidation after a
republish.
- Cover stability checks for pending, failed optional, required, and
reconnected servers.
GitOrigin-RevId: 783a6b04897f6c484a6d56fd9cee542814041759
## Why
App-server clients need to advertise structured MCP extension settings, including supported MCP App UI MIME types, rather than only opting into OpenAI form elicitation with a boolean.
## What changed
- Add an `extensions` map to initialize capabilities and preserve `mcpServerOpenaiFormElicitation` as a legacy alias for `openai/form`.
- Capture the declared extension profile when a thread is started, resumed, or forked, propagate it to subagents, and advertise it to downstream MCP servers during initialization.
- Keep the profile stable for the lifetime of the loaded session instead of changing it on later turns or direct tool calls.
## Testing
- Cover extension conversion, downstream MCP initialization, session isolation, legacy form support, and subagent inheritance.
GitOrigin-RevId: fbcedbb74ce788e574b0f884a4c45c4cedb9de54
## Why
A pending optional MCP server can delay the first model request even when the
turn does not need that server.
## What changed
- Give optional MCP servers a shared one-second startup grace, then omit servers
that are still pending from the captured tool catalog.
- Continue waiting when the turn explicitly requires a server through a plugin,
skill dependency, or `mcp://` mention, and preserve this behavior for input
received between sampling steps.
- Route direct resource requests to the live connection set when a pending
server was omitted from the binding, while keeping all-server resource
discovery non-blocking.
## Testing
- Cover the shared grace period and resource behavior for pending optional
servers.
- Verify plugin, plugin-skill, and direct MCP mentions wait for startup.
- Verify an Apps-enabled turn proceeds without tools from an unrelated pending
optional server.
GitOrigin-RevId: b5f895c5a5362fe73f7d33250367662d4a217e4d
## What changed
- Make `McpRuntime` own the published MCP configuration, connections, elicitation routing, and selected capability roots for a thread.
- Capture immutable MCP bindings for model steps and tool calls so in-flight work keeps a consistent connection set and approval authority while refreshed state is published atomically.
- Mark MCP state dirty when relevant configuration, plugins, environments, authentication, or elicitation capabilities change, then rebuild it before the next sampling request or out-of-band MCP operation.
- Separate config reloads from server invalidation: `ReloadMcpConfig` applies resolved MCP inputs, while `RefreshMcpServers` requests reinitialization from the thread's latest state.
## Testing
- Cover refreshed state visibility for existing turns, stable step bindings, current approval authority, cancelled refresh retries, resource-client reconciliation, and Apps recovery between sampling requests.
GitOrigin-RevId: 59eabb1aa8dc083426bd18ef4d3630508f376401
## What changed
- Make `McpResourceClient` resolve resource operations and cache identity from
the latest `McpRuntime` connection snapshot.
- Remove step-bound resource clients from `McpBinding` and the associated
per-binding client identity tracking.
GitOrigin-RevId: ee59f5867308c5a63e6e232384a50cf1e0c2a011
## What changed
- Use `McpConnectionSet` as the primary name for the collection of active MCP
server connections throughout `codex-mcp` and its callers.
- Keep `McpConnectionManager` as a backward-compatible type alias.
GitOrigin-RevId: 9753838b4fd0a0b6429a9c4af0c077137616f388
## Why
An MCP connection or tool catalog can change after a model step captures its
available tools. Calls from that step must not be rerouted to a replacement
client or run against a catalog revision the model did not see.
## What changed
- Add `McpBinding` to capture the ready clients, visible tools, resources, and
server metadata for one sampling request.
- Prepare calls against the captured client and reject them if the tool catalog
changes before call preparation and execution finish.
- Keep resource access and cache identity tied to the binding's exact connection
set, and omit servers that do not have a ready client.
- Preserve each client's unfiltered tool catalog so bindings can apply the
current filter consistently.
## Testing
Add coverage for connection replacement, stale catalog rejection, serialized
call preparation and refresh, ready-client capture, and binding-scoped resource
identity.
GitOrigin-RevId: a25da4d2c7f5ed06c41caa0c6d15c464c1698314
Anthony Tafoya