Use `LazyLock` to compile the placeholder regex once and reuse it across
argument strings, avoiding repeated compilation during template expansion.
Preserve regex error propagation and placeholder substitution behavior.
GitOrigin-RevId: 2ac8aec86de3430335c068e47d09422dcd276f7c
## Why
Hook dispatch recompiles regex matchers for each input even though discovery already validates them.
## What changed
Store compiled `HookMatcher` values on configured handlers and reuse them during dispatch. Preserve match-all, exact-name, pipe-alternative, and regex matching semantics, along with the original pattern spelling for configuration equality. Invalid regexes continue to be rejected during discovery.
GitOrigin-RevId: 117a8a19c7bc0e55ccbedcd5940b806a17ebba10
## Why
Background helpers launched from a detached Windows process can allocate console windows. Job Object launches and containment fallbacks need to preserve console suppression as well.
## What changed
- Add `codex_utils_process::background_command` to set `CREATE_NO_WINDOW` on Windows, and use it across background subprocess launches, including Git, plugins, authentication, diagnostics, and sandbox helpers.
- Centralize console suppression in Job Object launches. Keep `CREATE_NO_WINDOW` when retrying without containment, and clear `CREATE_SUSPENDED` so the fallback child can run.
- Preserve console inheritance for interactive shell launches and interactive AWS authentication refreshes.
## Testing
Add Windows regression tests covering console-free launches from detached parents through standard and Tokio commands, stdout/stderr capture, successful containment, Job Object creation and assignment failures, and sandbox setup refresh helpers.
GitOrigin-RevId: b2c238fa7d4f9fbd868e5adf7d4be9958ff01e6c
## Why
Passing extra descriptors to a PTY previously selected behavior intended for inherited escalation sockets: no EOF on stdin close, different signal exit statuses, and no default `SHELL`. Launch attachments need ordinary PTY behavior and must survive execution even when marked `FD_CLOEXEC`.
## What changed
- Add `ChildFds::Attached` alongside `ChildFds::Inherited` to distinguish launch attachments from legacy inherited descriptors.
- Preserve ordinary EOF, default `SHELL`, and signal exit status behavior for PTY attachments.
- Allow explicitly supplied close-on-exec descriptors through pipe and PTY launches without changing the parent's descriptor flags, using child-side flag updates and macOS spawn inheritance actions.
- Update existing callers to use `ChildFds::Inherited`.
## Testing
Add Unix coverage for attachment accessibility, unchanged parent descriptor flags, default `SHELL`, and signal exit statuses. Extend the PTY stdin-draining test to cover attachments and EOF delivery.
GitOrigin-RevId: 864aedc6c5717d8b43c9d71057c9f54409834509
## Why
Unix command hooks use a `pre_exec` callback to detach from the controlling terminal, forcing the launcher to fork. Native spawn attributes can create the detached session without that callback.
## What changed
- Route Unix hooks through `codex_utils_pty::Command` with `ProcessMode::NewSession`.
- Extend the native `posix_spawn` launcher to detached Linux sessions, retaining compatibility fallbacks for unsupported libc features and executable handling.
- Preserve the session environment snapshot, hook overrides, and restricted-variable filtering.
## Testing
Add regression coverage for launches without parent forks, terminal detachment, environment and argument handling, Linux `PATH` lookup, and executable compatibility. Cover process-group cleanup on cancellation and timeout, including descendants holding output pipes open, and preservation of background descendants after completed hooks.
GitOrigin-RevId: dbe2cf12d84aa79868cfb55ace40c7d5b5282703
## Why
Forked threads reported `startup`, causing startup hooks to run again even when their context was inherited from the parent. Resuming with supplied history also reported `startup` instead of `resume`.
## What changed
- Add `fork` as a `SessionStart` source and expose it in the hook input schema.
- Report `fork` for histories with a fork parent and `resume` for supplied histories without one.
- Continue dispatching `SubagentStart` for spawned subagents with either fresh or forked context.
## Testing
Add regression coverage for fork hook matching without duplicate startup context, resume hooks with supplied history, and `SubagentStart` context injection for fresh and forked subagents.
GitOrigin-RevId: 5ac1ae4ab8adcbbbceb8cb0ffb9b32b6402c585b
Run `hook_drains_output_and_times_out_while_stdin_is_blocked` with
`cmd.exe /D /C` on Windows and `/bin/sh -c` elsewhere to keep user shell
startup files out of the test.
GitOrigin-RevId: 296e65cf76b74543e91c9ed9024ba2442e7e33af
## Why
Writing hook input before draining output can deadlock when pipe buffers fill. Stdin writes also ran outside the hook timeout, allowing hooks that never read input to hang indefinitely.
## What changed
Write stdin concurrently with draining stdout and stderr, and apply the configured timeout to both input delivery and command completion. Preserve handling of broken pipes and distinct stdin and wait errors.
## Testing
Add a regression test that sends a large input to a hook that fills stdout and stderr without reading stdin. Verify that output drains and the hook reports its configured two-second timeout.
GitOrigin-RevId: 48cf33a2acfebbc5122a4522660d7a6b3fb1e9b0
## Why
Shell startup code that accesses the controlling terminal can stop a hook on background terminal I/O, preventing the hook command from running.
## What changed
Use `detach_from_tty` before executing Unix hook commands to avoid inheriting the controlling terminal while preserving process-group cleanup.
## Testing
Add a Unix regression test that runs under a controlling terminal and uses `BASH_ENV` to invoke `stty` during shell startup. Verify that the hook completes successfully and produces the expected output.
GitOrigin-RevId: 231125d4b169fb1bd828e3f8e96476a13bd25d26
## Why
Plugin updates made by another process do not notify a loaded session's hook runtime, leaving it with stale hooks.
## What changed
Compare the current plugin hook sources and load warnings with those retained by the hook runtime during turn construction. Refresh hooks when either differs so existing sessions pick up external plugin updates.
## Testing
Add an app-server regression test that updates the shared plugin store without notifying the server and verifies that successive turns in the same thread run the installed hooks across an upgrade and a rollback.
GitOrigin-RevId: d3a2653ac4c069d9d8a02f30e21e4506d76a091c
## What changed
- Centralize the allowlist for bundled MCP cleanup hooks and use it for both local and executor-discovered plugins, including `unified-computer-use` cleanup through `cua_repl`.
- Mark matching cleanup hooks as trusted built-ins so they run without saved hook trust and remain active when regular hooks or their per-hook state are disabled. Plugin enablement and managed-only policy still apply.
- Hide built-in cleanup hooks from hook listings and lifecycle notifications while retaining their metrics. Keep the built-in classification out of serialized protocol data.
## Testing
- Cover allowlist boundaries, trust and enablement behavior, inline and file-based hook declarations, MCP success and error responses, hook listing, lifecycle notifications, metrics, and protocol serialization.
GitOrigin-RevId: f93b7bc99f4ed9694f529def8ec383b45f31430e
## What changed
- Admit the curated remote Browser plugin's `Stop` and `SubagentStop` hooks when its listed `browser.turn_ended` tool matches the expected connector and is enabled by app policy.
- Carry trusted app routing metadata and the MCP environment through hook registration and execution.
- Register hooks from multiple executor environments, while deduplicating cleanup calls that share an event, MCP environment, server, and tool.
## Testing
- Cover Browser and Computer Use cleanup through separate MCP routes, including user- and managed-policy disablement.
- Verify routing metadata, environment selection, multi-environment registration, and target deduplication.
GitOrigin-RevId: 66de088fd201b9ed0db8b97c23d33de88135120d
## Why
Executor-scoped cleanup hooks need to observe an interrupted turn as well as a
normally completed one.
## What changed
- Allow bundled executor plugins to register the allowlisted `Interrupt` hook
alongside `Stop`, while preserving multiple allowed hook entries from the
selected executor environment.
- Run interrupt hooks with the interrupted turn's last step discovery and turn
metadata. Turns without a step context do not reuse discovery from an earlier
turn.
- Keep executor-scoped interrupt hooks asynchronous and omit public hook
lifecycle events for them, matching executor `Stop` hook behavior.
## Testing
Added coverage for hook filtering and registration, interrupt execution and
metadata propagation, environment selection, and turns without a step context.
GitOrigin-RevId: f0c536b3382a37cf3bf693c4573d21f6f66ace4e
## Why
Background memory consolidation must honor managed completion policies without
running project completion checks or sending user-facing notifications.
## What changed
- Add a memory-consolidation stop target that selects managed policy hooks and
executor-scoped cleanup while excluding user, project, session, and plugin
stop hooks.
- End memory consolidation with an error when a managed stop hook rejects it,
and propagate that turn error into agent status.
- Disable legacy completion notifications for the background memory worker.
## Testing
- Cover hook selection, executor cleanup, managed rejection, agent error
status, and notification suppression.
GitOrigin-RevId: be350679ddcde2dde8a408b0972f08facff01a37
## What changed
- Add an `Interrupt` hook event that runs for an active top-level turn before its
interrupted abort event is emitted.
- Flush the turn transcript before invoking the hook and provide the session,
turn, transcript, working directory, model, and permission mode in its input.
- Support command and MCP handlers, including asynchronous commands, with a
one-second default timeout and a three-second maximum.
- Expose the event through hook configuration, managed requirements, app-server
notifications, generated schemas, analytics, and the TUI hook views.
## Testing
- Cover handler discovery, timeout normalization, output parsing, protocol
compatibility, TUI rendering, and interrupt execution ordering.
GitOrigin-RevId: 163fa7c098d94ac2775f6d137f8e916f8ea9b6eb
## Testing
- Verify an executor plugin's `Stop` hook starts running after its environment
attaches and stops after disconnection.
- Confirm hook calls carry the expected session, thread, turn, model, and request
metadata.
- Reject hooks whose MCP server belongs to a different executor environment.
- Cover the current restriction to the first executor environment and handler.
GitOrigin-RevId: ef13baf61379997f117cc57515363cc9880d3724
## What changed
- Scope executor-provided stop-hook calls to the MCP server environment that registered the hook, and reject calls when that environment does not match.
- Forward turn metadata with executor stop-hook requests while retaining the hook call's `threadId` metadata.
## Testing
- Cover environment matching for MCP tool calls and verify executor stop hooks receive their environment ID and request metadata.
GitOrigin-RevId: b544ea3a6ca1f61389fb4597978ed7aac27d529a
## What changed
- Discover inline hooks from executor-provided plugin manifests and accept only
the bundled Computer Use `Stop` hook for `node_repl.turn_ended`.
- Add the accepted hook to the current step's hook engine with
executor-scoped provenance.
- Run executor-scoped hooks in the background after regular stop-hook
decisions, without delaying turn completion, applying control effects, or
exposing them in hook summaries. Skip them when regular hooks only block
continuation.
## Testing
- Added coverage for manifest filtering and option preservation.
- Added coverage for background execution, interaction with regular stop
hooks, and non-blocking turn completion.
GitOrigin-RevId: c0f75f83a23ba8a83bb3a5d5997c4882aacc32d6
## What changed
- Capture the process environment when the hook registry is created and reuse
that snapshot across configuration reloads.
- Clear the live environment before launching command hooks and legacy notify
commands, then apply hook-specific overrides and scrub non-inheritable
credentials.
- Resolve the default shell from the captured environment.
## Testing
Add coverage for snapshot replay, overrides, credential scrubbing, default
shell selection, non-Unicode values, and runtime reconfiguration.
GitOrigin-RevId: fee60c88e842980cdfc1bd49b14b62b9a56b08cd
## 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
`CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN` is an execution-server credential and
must not be exposed to model-reachable commands or command hooks, including
when shell environment policy explicitly sets a case variant of the name.
## What changed
- Add `CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN` to the shared list of
non-inheritable environment variables.
- Keep the environment variable constant in `codex-protocol` so the exec
server and environment scrubber use the same definition.
- Verify case-insensitive removal after policy overrides for shell commands
and command hooks.
GitOrigin-RevId: 759b224b6a7fb4f56f7b1a6d94ffbb0b188c658f
## What changed
- Discover synchronous `mcp_tool` hook handlers and invoke their configured MCP server and tool through a supplied executor.
- Expand nested hook-event placeholders in MCP tool inputs while preserving JSON types, and process tool output through the existing hook output contract.
- Represent hook details as handler-specific metadata in `hooks/list`, including MCP server and tool fields, and show those details in the TUI hooks browser.
- Skip unsupported `SessionEnd` MCP hooks and runtimes without MCP invocation support with startup warnings.
## Testing
- Cover argument expansion, missing placeholders, MCP invocation and hook decisions, discovery warnings, `hooks/list` metadata, and TUI rendering.
GitOrigin-RevId: 295b845471fe92bd7ad7cd272fbcd2c3713912e0
## Why
Hooks supplied as managed requirements must not be silently skipped when their
handlers cannot be loaded.
## What changed
- Fail session and app-server thread startup when an enabled managed requirement
contains an invalid matcher, an empty command, or an unsupported handler type.
- Keep load failures for ordinary managed configuration hooks as warnings, and do
not enforce managed hook requirements while the hooks feature is disabled.
## Testing
Added hook-engine, core session, and app-server coverage for valid and invalid
managed hook requirements.
GitOrigin-RevId: 91a23b0c1d85e143aba6aabe874c5274e52fc6b2
## What changed
- Load an optional package-supplied config file as the lowest-precedence
configuration layer, so every existing layer can override its values.
- Report the layer as `packagedDefaults`, including its source path, through
config diagnostics and the app-server protocol.
- Return an error when a configured packaged defaults file is missing.
## Testing
- Cover precedence across packaged, system, user, and session layers.
- Cover the missing-file error path.
GitOrigin-RevId: 52406890f4d580eedabc90bf2a9ee3affa36fee1
## What changed
- Represent configured handlers by handler kind and route execution through the
hooks engine, while preserving command hook behavior.
- Reject MCP tool inputs containing values such as `null` that cannot be
represented in TOML for trust hashing.
## Testing
- Add coverage for rejecting `null` at the top level and within nested MCP tool
input objects and arrays.
GitOrigin-RevId: 3854a349c2a721691450467592f99cf57e6260ef
## Why
Model-reachable child processes should not inherit Codex launch context.
## What changed
- Treat `OPENAI_FEDERATION_RULE_ID` and `OPENAI_IDENTITY_TOKEN_FILE` as non-inheritable environment variables, with case-insensitive matching.
- Remove them after shell environment policy overrides and before spawning commands across execution, MCP, hooks, Git helpers, and remote helper processes.
## Testing
- Cover inherited and explicitly configured variants, including mixed-case names.
- Verify the variables are absent from real child environments and app-server command and process execution.
GitOrigin-RevId: 2535527893985fef0995617f4c5b2462bea7c136
## What changed
- Add `executionMode` to `HookMetadata` returned by `hooks/list`, with `sync` as the default for compatibility.
- Propagate each discovered hook's `sync` or `async` mode through the app-server protocol and generated schemas.
- Show the execution mode in the TUI hooks browser.
## Testing
- Cover async and default-sync modes in `hooks/list` tests and TUI snapshots.
GitOrigin-RevId: 9c9f2890798fe417face76c15847616b2dea9db4
## Why
Hook configurations can mark command handlers as asynchronous, but Codex previously skipped those handlers outside `SessionEnd`.
## What changed
- Run asynchronous command hooks in the background with a per-session concurrency limit, while keeping `SessionEnd` hooks synchronous.
- Prevent asynchronous hooks from blocking, stopping, rewriting, or otherwise controlling the operation that launched them.
- Deliver warnings and additional context at safe turn boundaries: inject results into an active turn after sampling, or buffer them ahead of the next user prompt when the session is idle.
- Preserve in-flight hooks across configuration reloads, scope spilled output to the thread, and abort outstanding work during session shutdown.
## Testing
Add unit and integration coverage for background scheduling, concurrency, output parsing, active and idle result delivery, configuration reloads, and shutdown cleanup.
GitOrigin-RevId: 8094552e4afe7b47b09a61bb575bb20f4e491d8d
## Why
Timing out a command hook can leave descendant processes running after the hook itself is stopped.
## What changed
- Run hook commands in a process group on Unix and a job object on Windows.
- Terminate the full process tree when hook execution is cancelled or fails, with `taskkill` as a Windows fallback.
- Preserve descendants when a hook completes successfully so intentionally detached helpers can continue running.
GitOrigin-RevId: 1a18653d34c6f1685ef8c4f8e8546663b276292a
## What changed
- Parse `mcp_tool` hook handlers with a server, tool, JSON input, and optional timeout and status message.
- Return managed MCP tool hooks from `configRequirements/read` and include the handler in the generated protocol schemas.
- Skip MCP tool hooks during discovery with an explicit warning until execution is supported.
## Testing
- Cover MCP tool hook deserialization, including nested and null JSON input values.
- Extend the config requirements RPC test to verify the new handler shape.
GitOrigin-RevId: ff7e2d12b75b486c54d63469af547a29f9b31418
## What changed
- Replace the ordering enum and `include_disabled` boolean with named
`ConfigLayerStack` iterators for each precedence direction.
- Keep enabled-only iteration separate from `all_layers_*` iteration, which
includes disabled layers.
- Update config consumers to use the iterator matching their precedence and
disabled-layer requirements without allocating an intermediate `Vec`.
## Testing
- Add coverage that verifies ordering and disabled-layer filtering for all four
iterators.
GitOrigin-RevId: d14df3db4a2eae80ba97cdec246bff405e6c5f3d
## What changed
- Forward remote managed-network policy requests to the controller-side decider when Guardian review is enabled.
- Bound callbacks using the configured permission-hook and Guardian review timeouts, restore trusted execution attribution, and recheck live baseline policy before requesting a decision.
- Cancel pending decisions when the process or execution scope ends, and propagate EOF across the sandbox proxy bridge with half-closes.
## Testing
- Cover callback enablement, strict allowlist behavior, live policy updates, trusted attribution, and execution-scope cancellation.
GitOrigin-RevId: 83b47657c8c4546dfe98eec8b272833e96a46b7e
## Why
A hook can exit successfully without consuming its JSON input. If it closes
stdin while Codex is still writing, the resulting broken pipe should not hide
the hook's exit status and output.
## What changed
Ignore broken-pipe errors when writing hook stdin and continue waiting for the
process result. Other stdin write errors remain failures.
## Testing
Add a cross-platform regression test that sends a large input to a
fast-exiting hook and verifies that its successful status and stdout are
preserved.
GitOrigin-RevId: e1b6e7c6ac5e39232e49b45245ea0df9d34d1fe6
## What changed
- Assert truncated audio history through `ContextManager::raw_items()`.
- Initialize `additional_context_limit` in the quoted Windows hook command test.
GitOrigin-RevId: 43c19804e558b7a11fc17590506ec6ec7f3a9897
## What changed
- Add `additionalContextLimit` to command hook configuration for events that can emit `additionalContext`.
- Apply the limit independently to each hook's context before it is sent to the model. Unset values retain the 2,500-token default, while `0` disables spilling for that hook.
- Expose configured limits through app-server hook and requirements responses, and show them in the TUI hooks browser.
## Testing
- Cover JSON and TOML parsing, discovery and hashing, per-hook spilling behavior, app-server responses, and TUI rendering.
GitOrigin-RevId: 55ddc2dbbdf9067dceee3e1968c03617bbf6bcea
## Why
Windows hook commands whose executable paths contain spaces fail when their
outer quotes are escaped during argument construction.
## What changed
- Pass hook command strings as raw arguments to the default Windows shell.
- Do the same for configured shells that use the case-insensitive `/c` flag,
while retaining normal argument handling for other shells.
## Testing
Add a Windows regression test that runs a quoted `.cmd` hook from a directory
with spaces through both the default shell and an explicit `COMSPEC /c` shell.
GitOrigin-RevId: 0e7ce44203e01d3823daaaec750c2aeadfcd34b7
## What changed
- Add the `SessionEnd` hook event to hook configuration, protocol schemas, analytics, and the hooks browser.
- Run matching hooks for root threads during shutdown, including app-server archive, delete, idle unload, and graceful shutdown. Flush the transcript first and provide the session ID, transcript path, working directory, and `reason: "other"`.
- Keep teardown bounded: hook output is advisory, the default timeout is one second, configured timeouts are capped at three seconds, and async hooks run synchronously with a warning.
## Testing
- Cover transcript availability, matcher selection, timeout normalization, ignored control output, subagent exclusion, archive/delete ordering, and graceful shutdown of multiple loaded threads.
GitOrigin-RevId: 5d19a658677a137caf836ed5042dcb43f5eb6d1a
Adds a single trace span around configured hook command execution so
slow installed hooks are visible directly in traces.
The span records low-cardinality hook metadata and command outcome
without command text, hook input, stdout, or stderr.
## Summary
Make blocking hook behavior reliable for tools invoked from code mode.
Previously, a `PostToolUse` hook could block a completed tool result,
but code mode would still return the original typed result to
JavaScript. The hook appeared blocked in hook telemetry while the
running script continued with the result.
This change:
- rejects the nested JavaScript tool promise when `PostToolUse` blocks
- normalizes `decision: "block"` and exit code 2 to the same blocking
behavior
- surfaces the hook feedback as the rejected promise's error
- adds end-to-end coverage for the relevant PreToolUse and PostToolUse
interactions
## Hook semantics in code mode
| Hook behavior | Code-mode result |
|---|---|
| PreToolUse block | Reject the promise before the tool executes |
| PreToolUse `updatedInput` | Execute the rewritten invocation and
return its result |
| PostToolUse `decision: "block"` | Execute the tool, then reject the
promise with the hook reason |
| PostToolUse exit code 2 | Same behavior as `decision: "block"` |
| PostToolUse `continue: false` | Preserve the existing feedback-only
behavior; do not reject the promise |
## Test coverage
Added or strengthened end-to-end coverage proving that:
- a PreToolUse block rejects the JavaScript promise before execution
- a PreToolUse input rewrite executes only the rewritten command
- JavaScript receives the rewritten command's result
- PostToolUse `decision: "block"` rejects after the command executes
- PostToolUse exit code 2 has the same behavior
- the hook observes the original completed tool response
- the blocked original result does not reach JavaScript
- existing direct-mode replacement behavior remains intact
- `continue: false` without a reason produces deterministic fallback
feedback
Addresses #25875.
## Summary
`hooks.json` accepted unknown top-level fields. A file with
`SessionStart` at the root parsed as an empty hook configuration without
warning.
## Repro
```json
{ "SessionStart": [...] }
```
Previously: zero hooks, zero warnings.
Now:
```text
unknown field `SessionStart`, expected `hooks`
```
The supported shape remains:
```json
{ "hooks": { "SessionStart": [...] } }
```
## Fix
Reject unknown top-level fields and surface the parse warning in human
and JSONL `codex exec` output.
## Summary
V2 profiles add both `config.toml` and `<profile>.config.toml` to the
config stack. Because both user layers resolve hook discovery to the
same Codex home, Codex loaded the same `hooks.json` twice. This
duplicated hook rows and caused each matching command to run twice.
Deduplicate JSON hook discovery by absolute config folder within each
effective config stack. TOML hooks remain layer-specific, and multi-cwd
`hooks/list` results remain independently resolved per cwd.
## Reproduction
1. Add `config.toml` and `work.config.toml` under `$CODEX_HOME`.
2. Add one command hook to `$CODEX_HOME/hooks.json`.
3. Run Codex with `--profile work`.
4. Trigger the hook.
Before this change, one declaration creates two handlers. Afterward, it
creates one.
Fixes#25645 and addresses the single-cwd duplication in #25437.
## Validation
- `cargo nextest run -p codex-hooks`
- `just fix -p codex-hooks`
- `just fmt`
- `just argument-comment-lint -p codex-hooks`
## Summary
- Adapts the moved `codex-cloud-config` crate from the legacy cloud
requirements endpoint to the new config bundle endpoint.
- Switches runtime consumers from `CloudRequirementsLoader` to
`CloudConfigBundleLoader` so one shared bundle supplies cloud-delivered
config and requirements.
- Removes the legacy cloud requirements domain loader path.
## Details
This intentionally keeps `codex-cloud-config` monolithic for review
lineage: the previous PR establishes the crate move, and this PR shows
the behavior change against that moved implementation. A follow-up PR
splits the module back into focused files.
The new bundle path preserves the important cloud requirements loader
semantics where intended: account-scoped signed cache, 30 minute TTL, 5
minute refresh cadence, retry/backoff, auth recovery, and fail-closed
startup loading. The cached payload changes from a single requirements
TOML string to the backend-delivered bundle, and validation rejects
malformed config or requirements fragments before cache write/use.
## Summary
PR 3 of 5 in the cloud-managed config client stack.
Adds enterprise-managed cloud config as a first-class config layer
source. The layer metadata is preserved through config loading,
diagnostics, debug output, hook attribution, and app-server protocol
surfaces.
## Details
- Enterprise-managed config becomes a normal config layer source with
backend-supplied `id` and display `name` attached for provenance.
- These layers are designed to behave like non-file managed config: they
can surface syntax/type diagnostics by layer name even though there is
no physical config file.
- Relative path settings are resolved from a stored config base so
cloud-delivered config remains consistent with existing MDM-delivered
config semantics.
- Hook attribution distinguishes config-delivered hooks from
requirements-delivered hooks via `HookSource::CloudManagedConfig`.
- This remains pull-based and snapshot-oriented; the PR adds layer
identity/diagnostics, not dynamic reload behavior.
## Validation
Validated through the targeted stack checks after rebasing onto current
`main`:
- Rust crate tests for
config/hooks/cloud-config/backend-client/app-server-protocol
- Filtered `codex-core` and `codex-app-server` `cloud_config_bundle`
tests
- Python generated-file contract test
- `cargo shear --deny-warnings`
- Targeted `argument-comment-lint` for config/hooks
## Summary
PR 2 of 5 in the cloud-managed config client stack.
Adds a shared requirements-layer composition engine. The composer
defines how ordered requirements layers combine, with focused tests for
the merge semantics and provenance behavior. The final PR in the stack
wires runtime requirements sources into this path.
## Details
- Mental model: requirements layers are ordered lowest priority first,
matching `ConfigLayerStack`; lower-priority layers provide defaults
while higher-priority layers win scalar/list conflicts.
- Regular fields use config-style TOML merging, including recursive
table merging, so requirements layering follows the same broad model as
`config.toml` layering.
- Domain-specific fields keep explicit semantics: `rules.prefix_rules`
and hooks preserve high-priority-first output, hooks fail closed on
active managed-dir conflicts, and `permissions.filesystem.deny_read`
dedupes as a stable high-priority-first union.
- `remote_sandbox_config` is evaluated within each layer before the
regular TOML merge, so host-specific sandbox constraints do not leak
across layers.
- Provenance points at the exact source when one layer owns a value and
uses composite provenance when a table field is assembled from multiple
layers.
## Validation
Local validation:
- `just fmt`
- `cargo check -p codex-config`
- `just test -p codex-config requirements_composition`
- `git diff --check`
CI will run the broader test matrix.
# Why
Fixes#23993.
Hook command output schemas are published as the contract for hook
authors and schema-driven tooling. The event-specific output schemas
previously described `hookSpecificOutput.hookEventName` as the global
`HookEventNameWire` enum, so a `pre-tool-use.command.output` schema
would validate mismatched values like `PostToolUse`. That made the
schemas less precise than the intended event-specific contract.
# What
Constrain each hook-specific output schema to the matching literal
`hookEventName` value, mirroring the existing input-schema shape.
Also split `SubagentStartHookSpecificOutputWire` from the session-start
output wire so `subagent-start.command.output.schema.json` can emit
`const: "SubagentStart"` instead of sharing the session-start
definition.
# Verification
- `cargo nextest run -p codex-hooks`
- `just fix -p codex-hooks`
- `just argument-comment-lint -p codex-hooks -- --all-targets`
## Summary
- Bump the workspace Rust toolchain from `1.93.0` to `1.95.0` across
Cargo, Bazel, CI, release workflows, devcontainers, and the Codex
environment config.
- Refresh `MODULE.bazel.lock` so the Bazel Rust toolchain artifacts
match the new version.
- Leave purpose-specific toolchains unchanged, including the
`argument-comment-lint` nightly and the upstream `rusty_v8` `1.91.0`
build pin.
- Includes fixes for new lints from `just fix` and a few codex-authored
fixes for lints without a suggestion.
# What
When a normal hook fires inside a thread-spawned subagent, Codex now
includes these optional top-level fields in the hook input:
- `agent_id`: the child thread id
- `agent_type`: the subagent role
Root-agent hook inputs omit these fields. `SubagentStart` and
`SubagentStop` keep their existing required `agent_id` and `agent_type`
fields because those events are inherently subagent-scoped.
This does not change matcher behavior. Tool hooks still match on tool
name, compact hooks still match on trigger, and `UserPromptSubmit` still
ignores matchers. Only `SubagentStart` and `SubagentStop` match on
`agent_type`.
# What
<img width="1792" height="1024" alt="image"
src="https://github.com/user-attachments/assets/8f81d232-5813-4994-a61d-e42a05a93a3e"
/>
`SubagentStop` runs when a thread-spawned subagent turn is about to
finish. Thread-spawned subagents use `SubagentStop` instead of the
normal root-agent `Stop` hook.
Configured handlers match on `agent_type`. Hook input includes the
normal stop fields plus:
- `agent_id`: the child thread id.
- `agent_type`: the resolved subagent type.
- `agent_transcript_path`: the child subagent transcript path.
- `transcript_path`: the parent thread transcript path.
- `last_assistant_message`: the final assistant message from the child
turn, when available.
- `stop_hook_active`: `true` when the child is already continuing
because an earlier stop-like hook blocked completion.
`SubagentStop` shares the same completion-control semantics as `Stop`,
scoped to the child turn:
- No decision allows the child turn to finish.
- `decision: "block"` with a non-empty `reason` records that reason as
hook feedback and continues the child with that prompt.
- `continue: false` stops the child turn. If `stopReason` is present,
Codex surfaces it as the stop reason.
# Lifecycle Scope
Only thread-spawned subagents run `SubagentStop`.
Internal/system subagents such as Review, Compact, MemoryConsolidation,
and Other do not run normal `Stop` hooks and do not run `SubagentStop`.
This avoids exposing synthetic matcher labels for internal
implementation paths.
# Stack
1. #22782: add `SubagentStart`.
2. This PR: add `SubagentStop`.
3. #22882: add subagent identity to normal hook inputs.
# Why
Compaction replaces the live conversation history, so hooks that use
`SessionStart` to re-inject durable model context need a way to run
again after that rewrite.
Related - #19905 adds dedicated compact lifecycle hooks
# What
- add `compact` as a supported `SessionStart` source and matcher value
- change pending `SessionStart` state from a single slot to a small FIFO
queue so `resume` / `startup` / `clear` can be preserved alongside a
later `compact`
- drain all queued `SessionStart` sources before the next model request,
preserving their original order
# Testing
The new integration coverage verifies both the basic `compact` matcher
path and the stacked `resume` -> `compact` case where both hooks
contribute `additionalContext` to the next model turn.
# What
`SubagentStart` runs once when Codex creates a thread-spawned subagent,
before that child sends its first model request. Thread-spawned
subagents use `SubagentStart` instead of the normal root-agent
`SessionStart` hook.
Configured handlers match on the subagent `agent_type`, using the same
value passed to `spawn_agent`. When no agent type is specified, Codex
uses the default agent type.
Hook input includes the normal session-start fields plus:
- `agent_id`: the child thread id.
- `agent_type`: the resolved subagent type.
`SubagentStart` may return `hookSpecificOutput.additionalContext`. That
context is added to the child conversation before the first model
request.
# Lifecycle Scope
Only thread-spawned subagents run `SubagentStart`.
Internal/system subagents such as Review, Compact, MemoryConsolidation,
and Other do not run normal `SessionStart` hooks and do not run
`SubagentStart`. This avoids exposing synthetic matcher labels for
internal implementation paths.
Also the `SessionStart` hook no longer fires for subagents, this matches
behavior with other coding agents' implementation
# Stack
1. This PR: add `SubagentStart`.
2. #22873: add `SubagentStop`.
3. #22882: add subagent identity to normal hook inputs.
jif