62 Commits

• Respect blocking PostToolUse hooks in code mode (#28365)

  ## 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

  Abhinav · 2026-06-15 15:12:26 -07:00
  d7f298fe20
• build: run buildifier from just fmt (#28125)

  ## Intent
  
  Keep Bazel and Starlark files consistently formatted without requiring
  contributors to install or version buildifier themselves.
  
  ## Implementation
  
  - Add a SHA-256-pinned, cross-platform DotSlash manifest for buildifier
  v8.5.1.
  - Run buildifier from the shared `just fmt` and `just fmt-check` driver,
  with Windows-safe explicit DotSlash invocation.
  - Provision DotSlash in formatting CI and contributor devcontainers, and
  document the source-build prerequisite.
  - Apply the initial mechanical buildifier formatting baseline.

  Adam Perry @ OpenAI · 2026-06-13 21:43:39 -07:00
  740c4f269d
• Warn when hooks.json has unsupported top-level fields (#26426)

  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.

  Abhinav · 2026-06-11 23:08:07 +00:00
  eddc5c75ed
• [codex] Avoid duplicate hooks.json discovery with profiles (#26418)

  ## 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`

  Abhinav · 2026-06-11 15:25:55 -07:00
  0d8dee9427
• Switch runtime to cloud config bundle (#24622)

  ## 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.

  joeflorencio-openai · 2026-06-02 13:18:59 -07:00
  d45cd26248
• Add cloud-managed config layer support (#24620)

  ## 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

  joeflorencio-openai · 2026-05-31 15:54:31 -07:00
  8a556296f0
• Compose requirements layers (#24619)

  ## 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.

  joeflorencio-openai · 2026-05-31 15:14:06 -07:00
  20debf746b
• Tighten hook output event schemas (#24962)

  # 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`

  Abhinav · 2026-05-28 15:55:40 -07:00
  a576be2b73
• Uprev Rust toolchain pins to 1.95.0 (#24684)

  ## 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.

  Adam Perry @ OpenAI · 2026-05-26 20:59:47 -07:00
  cca1e0ba1d
• Add subagent identity to hook inputs (#22882)

  # 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`.

  Abhinav · 2026-05-21 14:54:01 -07:00
  16d85e2708
• Add SubagentStop hook (#22873)

  # 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.

  Abhinav · 2026-05-20 14:59:41 -07:00
  eee3e60db3
• Support compact SessionStart hooks (#21272)

  # 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.

  Abhinav · 2026-05-20 20:46:19 +00:00
  af49d38373
• Add SubagentStart hook (#22782)

  # 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.

  Abhinav · 2026-05-19 12:45:08 -07:00
  d661ab70ed
• feat: add layered --profile-v2 config files (#17141)

  ## Why
  
  `--profile-v2 <name>` gives launchers and runtime entry points a named
  profile config without making each profile duplicate the base user
  config. The base `$CODEX_HOME/config.toml` still loads first, then
  `$CODEX_HOME/<name>.config.toml` layers above it and becomes the active
  writable user config for that session.
  
  That keeps shared defaults, plugin/MCP setup, and managed/user
  constraints in one place while letting a named profile override only the
  pieces that need to differ.
  
  ## What Changed
  
  - Added the shared `--profile-v2 <name>` runtime option with validated
  plain names, now represented by `ProfileV2Name`.
  - Extended config layer state so the base user config and selected
  profile config are both `User` layers; APIs expose the active user layer
  and merged effective user config.
  - Threaded profile selection through runtime entry points: `codex`,
  `codex exec`, `codex review`, `codex resume`, `codex fork`, and `codex
  debug prompt-input`.
  - Made user-facing config writes go to the selected profile file when
  active, including TUI/settings persistence, app-server config writes,
  and MCP/app tool approval persistence.
  - Made plugin, marketplace, MCP, hooks, and config reload paths read
  from the merged user config so base and profile layers both participate.
  - Updated app-server config layer schemas to mark profile-backed user
  layers.
  
  ## Limits
  
  `--profile-v2` is still rejected for config-management subcommands such
  as feature, MCP, and marketplace edits. Those paths remain tied to the
  base `config.toml` until they have explicit profile-selection semantics.
  
  Some adjacent background writes may still update base or global state
  rather than the selected profile:
  
  - marketplace auto-upgrade metadata
  - automatic MCP dependency installs from skills
  - remote plugin sync or uninstall config edits
  - personality migration marker/default writes
  
  ## Verification
  
  Added targeted coverage for profile name validation, layer
  ordering/merging, selected-profile writes, app-server config writes,
  session hot reload, plugin config merging, hooks/config fixture updates,
  and MCP/app approval persistence.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  jif-oai · 2026-05-14 15:16:15 +02:00
  deedf3b2c4
• Spill oversized PreToolUse additionalContext (#22529)

  # Why
  
  `PreToolUse.additionalContext` became model-visible after #20692, but
  the hook-output spilling path from #21069 never picked up that newer
  lane. As a result, oversized `PreToolUse` context could bypass the
  truncation/spill treatment that already applies to the other hook
  outputs Codex forwards to the model.
  
  # What
  
  - Run `PreToolUseOutcome.additional_contexts` through
  `maybe_spill_texts(...)`
  - Add an integration test proving a large `PreToolUse.additionalContext`
  is replaced with a truncated preview plus spill-file pointer, while the
  full text is preserved on disk.

  Abhinav · 2026-05-13 15:21:31 -07:00
  23bb524973
• add --dangerously-bypass-hook-trust CLI flag (#21768)

  # Why
  
  Hook trust happens through the TUI in `/hooks` so it can block
  non-interactive use cases. This flag will allow users that are using
  codex headlessly to bypass hooks when they want to.
  
  # What
  
  This adds one invocation-scoped escape hatch.
  
  - the CLI flag sets a runtime-only `bypass_hook_trust` override; there
  is no durable `config.toml` setting
  - hook discovery still respects normal enablement, so explicitly
  disabled hooks remain disabled
  - we show a `--dangerously-bypass-hook-trust is enabled. Enabled hooks
  may run without review for this invocation.` message on startup so
  accidental use is visible in both interactive and exec flows
  
  This keeps “enabled” and “trusted” as separate concepts in the normal
  path, while giving CI/E2E callers a stable way to opt into the
  exceptional path when they already control the hook set.

  Abhinav · 2026-05-13 07:13:57 +00:00
  392e94e9ea
• Use root repo hooks in linked worktrees (#21969)

  # Why
  
  Linked worktrees currently load their own project hook declarations, so
  the same repo can present different hook definitions depending on which
  checkout is active. https://github.com/openai/codex/pull/21762 tried to
  share trust by giving matching worktree hooks a shared synthetic key,
  but review pointed out that divergent worktree hook definitions would
  then fight over one `trusted_hash`.
  
  Instead of introducing a second trust model, this makes linked worktrees
  use the root checkout as the single source of truth for project hook
  declarations. Worktree-local project config can still diverge for
  unrelated settings, but project hooks now keep one real source path and
  one trust state per repo.
  
  # What
  
  - Teach project config loading to remember the matching root-checkout
  `.codex/` folder for actual linked-worktree project layers.
  - Keep ordinary project config sourced from the worktree, but replace
  project hook declarations with the root checkout's matching layer before
  hook discovery runs, including linked-worktree layers with `.codex/` but
  no local `config.toml`.
  - Make hook discovery use that authoritative hook folder for both
  `hooks.json` and TOML hook source paths, so linked worktrees produce the
  same hook key and trust state as the root checkout.
  - Cover the linked-worktree path plus regressions for missing worktree
  `config.toml` and nested non-worktree project roots.

  Abhinav · 2026-05-13 06:58:58 +00:00
  934a40c7d9
• Add allow_managed_hooks_only hook requirement (#20319)

  ## Why
  
  Enterprise-managed hook policy needs a narrow way to require Codex to
  ignore user-controlled lifecycle hooks without adopting the broader
  trust-precedence model from earlier hook work. This keeps the policy
  anchored in `requirements.toml`, so admins can opt into managed hooks
  only while normal `config.toml` files cannot enable the restriction
  themselves.
  
  ## What changed
  
  - Added `allow_managed_hooks_only` to the requirements data flow and
  preserved explicit `false` values.
  - Also adds it to /debug-config
  - Marked MDM, system, and legacy managed config layers as managed for
  hook discovery.
  - Updated hook discovery so `allow_managed_hooks_only = true`:
    - keeps managed requirements hooks and managed config-layer hooks,
  - skips user/project/session `hooks.json` and `[hooks]` entries with
  concise startup warnings,
    - skips current unmanaged plugin hooks,
  - ignores any `allow_managed_hooks_only` key placed in ordinary
  `config.toml` layers.

  Andrei Eternal · 2026-05-12 19:05:25 -07:00
  913aad4d3c
• Support PreToolUse updatedInput rewrites (#20527)

  ## Why
  
  `PreToolUse` already exposes `updatedInput` in its hook output schema,
  but Codex currently rejects it instead of applying the rewrite. That
  leaves hook authors unable to make the documented pre-execution
  adjustment to a tool call before it runs.
  
  ## What
  
  - Accept `updatedInput` from `PreToolUse` hooks when paired with
  `permissionDecision: "allow"`.
  - Apply the rewritten input before dispatch so the tool executes the
  updated payload, not the original one.
  - Preserve the stable hook-facing compatibility shapes that
  participating tool handlers expose:
  - Bash-like tools (`shell`, `container.exec`, `local_shell`,
  `shell_command`, `exec_command`) use `{ "command": ... }`.
  - `apply_patch` exposes its patch body through the same command-shaped
  hook contract.
    - MCP tools expose their JSON argument object directly.
  - Keep each participating tool handler responsible for translating
  hook-facing `updatedInput` back into its concrete invocation shape.
  
  ## Verification
  
  Direct Bash-like rewrite coverage:
  
  - `pre_tool_use_rewrites_shell_before_execution`
  - `pre_tool_use_rewrites_container_exec_before_execution`
  - `pre_tool_use_rewrites_local_shell_before_execution`
  - `pre_tool_use_rewrites_shell_command_before_execution`
  - `pre_tool_use_rewrites_exec_command_before_execution`
  
  These cases assert that each supported Bash-like surface runs only the
  rewritten command while the hook still observes the original `{
  "command": ... }` input.
  
  `pre_tool_use_rewrites_apply_patch_before_execution`
  
  - Model emits one patch.
  - Hook swaps in a different patch.
  - Asserts only the rewritten file is created, and the hook saw the
  original patch.
  
  `pre_tool_use_rewrites_code_mode_nested_exec_command_before_execution`
  
  - Model runs one nested shell command from code mode.
  - Hook rewrites it.
  - Asserts only the rewritten command runs, and the hook saw the original
  nested input.
  
  `pre_tool_use_rewrites_mcp_tool_before_execution`
  
  - Model calls the RMCP echo tool.
  - Hook rewrites the MCP arguments.
  - Asserts the MCP server receives and returns the rewritten message, not
  the original one.

  Abhinav · 2026-05-11 22:27:24 -04:00
  d08906a944
• Add Windows hook command overrides (#22159)

  # Why
  
  Managed hook configs need a shared cross-platform shape without making
  the existing `command` field polymorphic. The common case is still one
  command string, with Windows needing a different entrypoint only when
  the runtime is actually Windows.
  
  Keeping `command` as the portable/default path and adding an optional
  Windows override keeps the config easier to read, preserves the existing
  scalar shape for non-Windows users, and avoids forcing every caller into
  a `{ unix, windows }` object when only one platform needs special
  handling.
  
  # What
  
  - Add optional `command_windows` / `commandWindows` alongside the
  existing hook `command` field.
  - Resolve `command_windows` only on Windows during hook discovery; other
  platforms continue to use `command` unchanged.
  - Keep trust hashing aligned to the effective command selected for the
  current runtime.
  
  # Docs
  
  The Codex hooks/config reference should document `command_windows` as
  the Windows-only override for command hooks.

  Abhinav · 2026-05-11 22:22:29 +00:00
  9ab7f4e6ac
• Enable --deny-warnings for cargo shear (#21616)

  ## Summary
  
  In https://github.com/openai/codex/pull/21584, we disabled doctests for
  crates that lack any doctests. We can enforce that property via `cargo
  shear --deny-warnings`: crates that lack doctests will be flagged if
  doctests are enabled, and crates with doctests will be flagged if
  doctests are disabled.
  
  A few additional notes:
  
  - By adding `--deny-warnings`, `cargo shear` also flagged a number of
  modules that were not reachable at all. Some of those have been removed.
  - This PR removes a usage of `windows_modules!` (since `cargo shear` and
  `rustfmt` couldn't see through it) in favor of simple `#[cfg(target_os =
  "windows")]` macros. As a consequence, many of these files exhibit churn
  in this PR, since they weren't being formatted by `rustfmt` at all on
  main.
  - Again, to make the code more analyzable, this PR also removes some
  usages of `#[path = "cwd_junction.rs"]` in favor of a more standard
  module structure. The bin sidecar structure is still retained, but,
  e.g., `windows-sandbox-rs/src/bin/command_runner.rs‎` was moved to
  `windows-sandbox-rs/src/bin/command_runner/main.rs`, and so on.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Charlie Marsh · 2026-05-08 20:29:00 +00:00
  7c9731c9af
• [codex] Remove legacy after tool use hooks (#21805)

  ## Why
  
  The legacy `AfterToolUse` hook path was still wired through core tool
  dispatch even though the hooks registry never populated any handlers for
  it. The supported hook surface is `PostToolUse`, so the old
  infrastructure was dead code on the hot path.
  
  ## What changed
  
  - Removed the legacy `AfterToolUse` dispatch from `codex-core` tool
  execution.
  - Removed the unused legacy hook payload types and exports from
  `codex-hooks`.
  - Simplified legacy notify handling now that `HookEvent` only carries
  `AfterAgent`.
  
  ## Validation
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-core registry`

  pakrym-oai · 2026-05-08 13:20:05 -07:00
  46e2250bcf
• Show plugin hooks in plugin details (#21447)

  Supersedes the abandoned #19859, rebuilt on latest `main`.
  
  # Why
  
  PR #19705 adds discovery for hooks bundled with plugins, but `/plugins`
  still only shows skills, apps, and MCP servers. This follow-up makes
  bundled hooks visible in the same plugin detail view so users can
  inspect the full plugin surface in one place.
  
  We also need `PluginHookSummary` to populate Plugin Hooks in the app;
  `hooks/list` is not enough there because plugin detail needs to show
  hooks for disabled plugins too.
  
  # What
  
  - extend `plugin/read` with `PluginHookSummary` entries for bundled
  hooks
  - summarize plugin hooks while loading plugin details
  - render a `Hooks` row in the `/plugins` detail popup
  
  <img width="3456" height="848" alt="CleanShot 2026-04-27 at 11 45 34@2x"
  src="https://github.com/user-attachments/assets/fe3a38d6-a260-4351-8513-fb04c93d725b"
  />

  Abhinav · 2026-05-07 00:21:14 -07:00
  40e282849c
• Add compact lifecycle hooks (started by vincentkoc - external contrib) (#19905)

  Based on work from Vincent K -
  https://github.com/openai/codex/pull/19060
  
  <img width="1836" height="642" alt="CleanShot 2026-04-29 at 20 47 40@2x"
  src="https://github.com/user-attachments/assets/b647bb89-65fe-40c8-80b0-7a6b7c984634"
  />
  
  ## Why
  
  Compaction rewrites the conversation context that future model turns
  receive, but hooks currently have no deterministic lifecycle point
  around that rewrite. This adds compact lifecycle hooks so users can
  audit manual and automatic compaction, surface hook messages in the UI,
  and run post-compaction follow-up without overloading tool or prompt
  hooks.
  
  ## What Changed
  
  - Added `PreCompact` and `PostCompact` hook events across hook config,
  discovery, dispatch, generated schemas, app-server notifications,
  analytics, and TUI hook rendering.
  - Added trigger matching for compact hooks with the documented `manual`
  and `auto` matcher values.
  - Wired `PreCompact` before both local and remote compaction, and
  `PostCompact` after successful local or remote compaction.
  - Kept compact hook command input to lifecycle metadata: session id,
  Codex turn id, transcript path, cwd, hook event name, model, and
  trigger.
  - Made compact stdout handling consistent with other hooks: plain stdout
  is ignored as debug output, while malformed JSON-looking stdout is
  reported as failed hook output.
  - Added integration coverage for compact hook dispatch, trigger
  matching, post-compact execution, and the audited behavior that
  `decision:"block"` does not block compaction.
  
  ## Out of Scope
  
  - Hook-specific compaction blocking is not implemented;
  `decision:"block"` and exit-code-2 blocking semantics are intentionally
  unsupported for `PreCompact`.
  - Custom compaction instructions are not exposed to compact hooks in
  this PR.
  - Compact summaries, summary character counts, and summary previews are
  not exposed to compact hooks in this PR.
  
  ## Verification
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-core
  manual_pre_compact_block_decision_does_not_block_compaction`
  - `cargo test -p codex-app-server hooks_list`
  - `cargo test -p codex-core config_schema_matches_fixture`
  - `cargo test -p codex-tui hooks_browser`
  
  ## Docs
  
  The developer documentation for Codex hooks should be updated alongside
  this feature to document `PreCompact` and `PostCompact`, the
  `manual`/`auto` matcher values, and the compact hook payload fields.
  
  ---------
  
  Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

  Andrei Eternal · 2026-05-06 18:08:31 -07:00
  527d52df03
• hook trust metadata and enforcement (#20321)

  # Why
  
  We want shared hook trust that both the app and the TUI can build on,
  but the metadata is only useful if runtime behavior agrees with it. This
  PR adds a single backend trust model for hooks so unmanaged hooks cannot
  run until the current definition has been reviewed, while managed hooks
  remain runnable and non-configurable.
  
  # What
  
  - persist `trusted_hash` alongside hook state in `config.toml`
  - expose `currentHash` and derived `trustStatus` through `hooks/list`
  - derive trust from normalized hook definitions so equivalent hooks from
  `config.toml` and `hooks.json` share the same trust identity
  - gate unmanaged hooks on trust before they enter the runnable handler
  set
  
  # Reviewer Notes
  
  - key file to review is `codex-rs/hooks/src/engine/discovery.rs`
  - the only **core** change is schema related

  Abhinav · 2026-05-05 19:13:55 +00:00
  0452dca986
• revert legacy notify deprecation (#21152)

  # Why
  
  Revert #20524 for now because the computer use plugin has not migrated
  off legacy `notify` yet. Keeping the deprecation in place today would
  show users a warning before the plugin path is ready to move, so this
  rolls the change back until that migration is complete.
  
  # What
  
  - revert the legacy `notify` deprecation change from #20524
  - restore the prior `notify` behavior and remove the temporary
  deprecation metrics/docs from that change
  
  Once the computer use plugin has migrated, we can land the same
  deprecation again.

  Abhinav · 2026-05-05 10:34:44 -07:00
  13be504063
• Support PreToolUse additionalContext (#20692)

  # Why
  
  `PreToolUse` already exposes `hookSpecificOutput.additionalContext` in
  the generated hook schema, but the runtime still rejected it as
  unsupported. That leaves `PreToolUse` out of step with the other
  context-injecting hooks and prevents hook authors from attaching
  model-visible guidance to a pending tool call before it runs.
  
  # What
  
  - Parse `PreToolUse.additionalContext` and carry it through the hook
  event pipeline.
  - Record `PreToolUse` context at the hook boundary so successful context
  is preserved for both allowed and blocked calls without widening the
  tool registry surface.
  - Preserve existing deny behavior when context is combined with either
  `permissionDecision: "deny"` or the legacy `decision: "block"` shape.

  Abhinav · 2026-05-05 10:29:30 -07:00
  af86be529c
• Spill large hook outputs from context (#21069)

  ## Why
  
  Large hook outputs can enter model-visible context through hook-specific
  paths such as `additionalContext` and `Stop` continuation prompts.
  Without a dedicated cap, one hook can inject a large blob directly into
  conversation history instead of leaving a bounded preview for the model
  and preserving the full text elsewhere.
  
  ## What
  
  - spill hook text once it exceeds a fixed `2_500`-token budget,
  preserving the full output on disk and leaving a head/tail preview plus
  saved path in context
  - add shared hook-output spilling under
  `CODEX_HOME/hook_outputs/<thread_id>/<uuid>.txt`
  - apply the cap to both `additionalContext`, `feedback_message`, and
  `Stop` continuation fragments

  Abhinav · 2026-05-05 05:03:18 +00:00
  dca105cf99
• deprecate legacy notify (#20524)

  # Why
  
  `notify` is the remaining compatibility surface from the legacy hook
  implementation. The newer lifecycle hook engine now owns the active hook
  system, so we should start steering users away from adding new `notify`
  configs before removing the old path entirely. This also adds a
  lightweight watchpoint for the deprecation so we can see how much legacy
  usage remains before the clean drop.
  
  # What
  
  - emit a startup deprecation notice when a non-empty `notify` command is
  configured
  - emit `codex.notify.configured` when a session starts with legacy
  `notify` configured
  - emit `codex.notify.run` when the legacy notify path fires after a
  completed turn
  - mark `notify` as deprecated in the config schema and repo docs
  - remove the orphaned `codex-rs/hooks/src/user_notification.rs` file
  that is no longer compiled
  - add regression coverage for the new deprecation notice
  
  # Next steps
  
  A follow-up PR can remove the legacy notify path entirely once we are
  ready for the clean drop. Before then, we can watch
  `codex.notify.configured` and `codex.notify.run` to understand the
  deprecation impact and remaining active usage. The cleanup PR should
  then delete the `notify` config field, the `legacy_notify`
  implementation, the old compatibility dispatch types and callsites that
  only exist for the legacy path, and the remaining compatibility
  docs/tests.
  
  # Testing
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-config`
  - `cargo test -p codex-core emits_deprecation_notice_for_notify`

  Abhinav · 2026-05-01 17:35:21 +00:00
  78baa20780
• Add /hooks browser for lifecycle hooks (#19882)

  ## Why
  
  `hooks/list` and `hooks/config/write` give us read/write access to hooks
  and their state. This hooks up the TUI as a client so users can inspect
  and manage that state directly.
  
  ## What
  
  - add a two-page `/hooks` browser in the TUI: an event overview with
  installed/active counts, followed by a per-event handler page with
  toggle controls and detail rendering
  - thread managed-state metadata through hook discovery and `hooks/list`
  so the UI can label admin-managed hooks and suppress toggles for them
  - persist hook toggles through the existing config-write path and add
  snapshot coverage for the event list, handler list, managed-hook, and
  empty states
  
  ## Stack
  
  1. openai/codex#19705
  2. openai/codex#19778
  3. openai/codex#19840
  4. This PR - openai/codex#19882
  
  ## Reviewer Notes
  
  - Main UI logic is in
  `codex-rs/tui/src/bottom_pane/hooks_browser_view.rs`; most of the diff
  is the new view plus its snapshot coverage
  - Request / write plumbing for opening the browser and persisting
  toggles is in `codex-rs/tui/src/app/background_requests.rs` and
  `codex-rs/tui/src/chatwidget/hooks.rs`
  - Outside the TUI, the only behavioral change in this PR is threading
  `is_managed` through hook discovery and `hooks/list` so managed hooks
  render as non-toggleable
  - The `codex-rs/tui/src/status/snapshots/` churn is unrelated merge
  fallout from the stacked base branch's newer permission-label rendering
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-30 11:58:27 -07:00
  93d53f655b
• Add persisted hook enablement state (#19840)

  ## Why
  
  After `hooks/list` exposes the hook inventory, clients need a way to
  persist user hook preferences, make those changes effective in
  already-open sessions, and distinguish user-controllable hooks from
  managed requirements without adding another bespoke app-server write
  API.
  
  ## What
  
  - Extends `hooks/list` entries with effective `enabled` state.
  - Persists user-level hook state under `hooks.state.<hook-id>` so the
  model can grow beyond a single boolean over time.
  - Uses the existing `config/batchWrite` path for hook state updates
  instead of introducing a dedicated hook write RPC.
  - Refreshes live session hook engines after config writes so
  already-open threads observe updated enablement without a restart.
  
  ## Stack
  
  1. openai/codex#19705
  2. openai/codex#19778
  3. This PR - openai/codex#19840
  4. openai/codex#19882
  
  ## Reviewer Notes
  
  The generated schema files account for much of the raw diff. The core
  behavior is in:
  
  - `hooks/src/config_rules.rs`, which resolves per-hook user state from
  the config layer stack.
  - `hooks/src/engine/discovery.rs`, which projects effective enablement
  into `hooks/list` from source-derived managedness.
  - `config/src/hook_config.rs`, which defines the new `hooks.state`
  representation.
  - `core/src/session/mod.rs`, which rebuilds live hook state after user
  config reloads.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-30 04:46:32 +00:00
  8f3c06cc97
• Add hooks/list app-server RPC (#19778)

  ## Why
  
  We need a way to list the available hooks to expose via the TUI and App
  so users can view and manage their hooks
  
  ## What
  
  - Adds `hooks/list` for one or more `cwd` values that returns discovered
  hook metadata
  
  ## Stack
  
  1. openai/codex#19705
  2. This PR - openai/codex#19778
  3. openai/codex#19840
  4. openai/codex#19882
  
  ## Review Notes
  
  The generated schema files account for most of the raw diff, these files
  have the core change:
  
  - `hooks/src/engine/discovery.rs` builds the inventory entries during
  hook discovery while leaving runtime handlers focused on execution.
  - `app-server/src/codex_message_processor.rs` wires `hooks/list` into
  the app-server flow for each requested `cwd`.
  - `app-server-protocol/src/protocol/v2.rs` defines the new v2
  request/response payloads exposed on the wire.
  
  ### Core Changes
  
  `core/src/plugins/manager.rs` adds `plugins_for_layer_stack(...)` so
  `skills/list` and `hooks/list`can resolve plugin state for each
  requested `cwd`
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-29 23:39:57 +00:00
  8774229a89
• Support detect and import MCP, Subagents, hooks, commands from external (#19949)

  ## Why
  This PR expands the migration path so Codex can detect and import MCP
  server config, hooks, commands, and subagents configs in a Codex-native
  shape.
  
  ## What changed
  
  - Added a `codex-external-agent-migration` crate that owns conversion
  logic for external-agent MCP servers, hooks, commands, and subagents.
  - Extended the app-server external-agent config detection/import API
  with migration item types for MCP server config, hooks, commands, and
  subagents.
  
  ## Migration strategy
  
  The migration is intentionally conservative: Codex only imports
  external-agent config that can be represented safely in Codex today.
  Unsupported or ambiguous config is skipped instead of being partially
  translated into behavior that may not match the source system.
  
  - **MCP servers**: import supported stdio and HTTP MCP server
  definitions into `mcp_servers`. Disabled servers and servers filtered
  out by source `enabledMcpjsonServers` / `disabledMcpjsonServers` are
  skipped. Project-scoped MCP entries from `.claude.json` are included
  when they match the repo path.
  - **Hooks**: import only supported command hooks into
  `.codex/hooks.json`. Unsupported hook features such as conditional
  groups, async handlers, prompt/http hooks, or unknown fields are
  skipped. Referenced hook scripts are copied into `.codex/hooks/`,
  preserving any existing target scripts.
  - **Commands**: import supported external commands as Codex skills under
  `.agents/skills/source-command-*`. Commands that rely on source runtime
  expansion such as `$ARGUMENTS`, `$1`, `@file` references, shell
  interpolation, or colliding generated names are skipped.
  - **Subagents**: import valid subagent Markdown files into
  `.codex/agents/*.toml` when they have the minimum Codex agent fields.
  Source model names are not migrated, so imported agents keep the user’s
  Codex default model; compatible reasoning effort and sandbox mode are
  migrated when present.
  - **Skills and project guidance**: copy missing skill directories into
  `.agents/skills` and migrate `CLAUDE.md` guidance into `AGENTS.md`,
  rewriting source-agent terminology to Codex terminology where
  appropriate.
  - **Detection details**: detected migration items include lightweight
  details for UI preview, such as MCP server names, hook event names,
  generated command skill names, and subagent names. Import still
  recomputes from disk instead of trusting details as the source of truth.
  
  - Adds focused coverage for the new migration behavior and app-server
  import flow.
  
  ## Verification
  
  - `cargo test -p codex-external-agent-migration`
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-app-server external_agent_config`
  - `just bazel-lock-check`

  alexsong-oai · 2026-04-29 00:45:24 +00:00
  cb8b1bbcd6
• Increase plugin hook env test timeout (#20100)

  # Why
  
  `plugin_hook_sources_run_with_plugin_env_and_plugin_source` can still
  fail on Windows after the earlier file-based assertion cleanup because
  the hook process itself occasionally exceeds the old 5s timeout under CI
  load. When that happens, the hook run ends as `Failed` before the test
  can inspect its structured output.
  
  The Windows Bazel failure showed the hook run itself failing after
  nearly 8 seconds:
  
  ```text
  ---- engine::tests::plugin_hook_sources_run_with_plugin_env_and_plugin_source stdout ----
  thread 'engine::tests::plugin_hook_sources_run_with_plugin_env_and_plugin_source' panicked at hooks/src\engine\mod_tests.rs:428:5:
  assertion failed: `(left == right)`
  Diff < left / right > :
  <Failed
  >Completed
  ...
  test result: FAILED. 78 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 7.96s
  ```
  
  # What
  
  - raise the flaky plugin hook env test timeout from 5s to 10s so it
  matches the other executed hook tests in this module
  
  # Validation
  
  - `cargo test -p codex-hooks`

  Abhinav · 2026-04-28 17:08:12 -07:00
  5b0d9df1d0
• Fix flaky plugin hook env test (#20088)

  The test was flaky because it was checking the right thing in a
  roundabout way.
  
  What it wanted to prove:
  - plugin hooks receive the right environment variables.
  
  What it actually did:
  1. Run a plugin hook.
  2. Have that hook write those env vars into a temporary `env.json` file.
  3. After the hook finished, read `env.json` back from disk.
  
  On Windows, that last file was sometimes not there when the test tried
  to read it, so the test failed with `read env log: file not found`. The
  hook system itself was not what the test failure was directly proving;
  the test was failing on the extra filesystem side effect it introduced.
  
  The fix is to stop using a temp file as the proof mechanism. The hook
  now prints the env values in its normal structured output, and the test
  asserts on the output that the hook engine already captures. So we still
  verify the same behavior, but without depending on a separate file being
  created and read back correctly on Windows.

  Abhinav · 2026-04-28 15:45:26 -07:00
  3291463ff1
• Discover hooks bundled with plugins (#19705)

  ## Why
  
  Plugins can bundle lifecycle hooks, but Codex previously only discovered
  hooks from user, project, and managed config layers. This adds the
  plugin discovery and runtime plumbing needed for plugin-bundled hooks
  while keeping execution behind the `plugin_hooks` feature flag.
  
  ## What
  
  - Discovers plugin hook sources from each plugin's default
  `hooks/hooks.json`.
  - Supports `plugin.json` manifest `hooks` entries as either relative
  paths or inline hook objects.
  - Plumbs discovered plugin hook sources through plugin loading into the
  hook runtime when `plugin_hooks` is enabled.
  - Marks plugin-originated hook runs as `HookSource::Plugin`.
  - Injects `PLUGIN_ROOT` and `CLAUDE_PLUGIN_ROOT` into plugin hook
  command environments.
  - Updates generated schemas and hook source metadata for the plugin hook
  source.
  
  ## Stack
  
  1. This PR - openai/codex#19705
  2. openai/codex#19778
  3. openai/codex#19840
  4. openai/codex#19882
  
  ## Reviewer Notes
  
  - Core logic is in `codex-rs/core-plugins/src/loader.rs` and
  `codex-rs/hooks/src/engine/discovery.rs`
  - Moved existing / adding new tests to
  `codex-rs/core-plugins/src/loader_tests.rs` hence the large diff there
  - Otherwise mostly plumbing and minor schema updates
  
  ### Core Changes
  
  The `codex-rs/core` changes are limited to wiring plugin hook support
  into existing core flows:
  
  - `core/src/session/session.rs` conditionally pulls effective plugin
  hook sources and plugin hook load warnings from `PluginsManager` when
  `plugin_hooks` is enabled, then passes them into `HooksConfig`.
  - `core/src/hook_runtime.rs` adds the `plugin` metric tag for
  `HookSource::Plugin`.
  - `core/config.schema.json` picks up the new `plugin_hooks` feature
  flag, and `core/src/plugins/manager_tests.rs` updates fixtures for the
  added plugin hook fields.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-28 14:17:18 -07:00
  c6e7d564c3
• Support MCP tools in hooks (#18385)

  ## Summary
  
  Lifecycle hooks currently treat `PreToolUse`, `PostToolUse`, and
  `PermissionRequest` as Bash-only flows
  - hook schema constrains `tool_name` to `Bash`
  - hook input assumes a command-shaped `tool_input`
  - core hook dispatch path passes only shell command strings
  
  That means hooks cannot target MCP tools even though MCP tool names are
  model-visible and stable
  
  This change generalizes those hook paths so they can match and receive
  payloads for MCP tools while preserving the existing Bash behavior.
  
  ## Reviewer Notes
  
  I think these are the key files
  - `codex-rs/core/src/tools/handlers/mcp.rs`
  - `codex-rs/core/src/mcp_tool_call.rs`
  
  Otherwise the changes across apply_patch, shell, and unified_exec are
  mainly to rewire everything to be `tool_input` based instead of just
  `command` so that it'll make sense for MCP tools.
  
  ## Changes
  
  - Allow `PreToolUse`, `PostToolUse`, and `PermissionRequest` hook inputs
  to carry arbitrary `tool_name` and `tool_input` values instead of
  hard-coding `Bash` and command-only payloads.
  - Add MCP hook payload support through `McpHandler`, using the
  model-visible tool name from `ToolInvocation` and the raw MCP arguments
  as `tool_input`.
  - Include MCP tool responses in `PostToolUse` by serializing
  `McpToolOutput` into the hook response payload.
  - Run `PermissionRequest` hooks for MCP approval requests after
  remembered approval checks and before falling back to user-facing MCP
  elicitation.
  - Preserve exact matching for literal hook matchers like `Bash` and
  `mcp__memory__create_entities`, while keeping regex matcher support for
  patterns like `mcp__memory__.*` and `mcp__.*__write.*`.
  
  ---------
  
  Co-authored-by: Andrei Eternal <eternal@openai.com>
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-23 07:33:57 +00:00
  305825abd9
• codex: support hooks in config.toml and requirements.toml (#18893)

  ## Summary
  
  Support the existing hooks schema in inline TOML so hooks can be
  configured from both `config.toml` and enterprise-managed
  `requirements.toml` without requiring a separate `hooks.json` payload.
  
  This gives enterprise admins a way to ship managed hook policy through
  the existing requirements channel while still leaving script delivery to
  MDM or other device-management tooling, and it keeps `hooks.json`
  working unchanged for existing users.
  
  This also lays the groundwork for follow-on managed filtering work such
  as #15937, while continuing to respect project trust gating from #14718.
  It does **not** implement `allow_managed_hooks_only` itself.
  
  NOTE: yes, it's a bit unfortunate that the toml isn't formatted as
  closely as normal to our default styling. This is because we're trying
  to stay compatible with the spec for plugins/hooks that we'll need to
  support & the main usecase here is embedding into requirements.toml
  
  ## What changed
  
  - moved the shared hook serde model out of `codex-rs/hooks` into
  `codex-rs/config` so the same schema can power `hooks.json`, inline
  `config.toml` hooks, and managed `requirements.toml` hooks
  - added `hooks` support to both `ConfigToml` and
  `ConfigRequirementsToml`, including requirements-side `managed_dir` /
  `windows_managed_dir`
  - treated requirements-managed hooks as one constrained value via
  `Constrained`, so managed hook policy is merged atomically and cannot
  drift across requirement sources
  - updated hook discovery to load requirements-managed hooks first, then
  per-layer `hooks.json`, then per-layer inline TOML hooks, with a warning
  when a single layer defines both representations
  - threaded managed hook metadata through discovered handlers and exposed
  requirements hooks in app-server responses, generated schemas, and
  `/debug-config`
  - added hook/config coverage in `codex-rs/config`, `codex-rs/hooks`,
  `codex-rs/core/src/config_loader/tests.rs`, and
  `codex-rs/core/tests/suite/hooks.rs`
  
  ## Testing
  
  - `cargo test -p codex-config`
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-app-server config_api`
  
  ## Documentation
  
  Companion updates are needed in the developers website repo for:
  
  - the hooks guide
  - the config reference, sample, basic, and advanced pages
  - the enterprise managed configuration guide
  
  ---------
  
  Co-authored-by: Michael Bolin <mbolin@openai.com>

  Andrei Eternal · 2026-04-22 21:20:09 -07:00
  2b2de3f38b
• hooks: emit Bash PostToolUse when exec_command completes via write_stdin (#18888)

  Fixes #16246.
  
  ## Why
  
  `exec_command` already emits `PreToolUse`, but long-running unified exec
  commands that finish on a later `write_stdin` poll could miss the
  matching `PostToolUse`. That left the Bash hook lifecycle inconsistent,
  broke expectations around `tool_use_id` and `tool_input.command`, and
  meant `PostToolUse` block/replacement feedback could fail to replace the
  final session output before it reached model context.
  
  This keeps the fix scoped to the `exec_command` / `write_stdin`
  lifecycle. Broader non-Bash hook expansion is still out of scope here
  and remains tracked separately in #16732.
  
  ## What changed
  
  - Compute and store `PostToolUsePayload` while handlers still have
  access to their concrete output type, and carry `tool_use_id` through
  that payload.
  - Preserve the original hook-facing `exec_command` string through
  unified exec state (`ExecCommandRequest`, `ProcessEntry`,
  `PreparedProcessHandles`, and `ExecCommandToolOutput`) via
  `hook_command`, and remove the now-unused `session_command` output
  metadata.
  - Emit exactly one Bash `PostToolUse` for long-running `exec_command`
  sessions when a later `write_stdin` poll observes final completion,
  using the original `exec_command` call id and hook-facing command.
  - Keep one-shot `exec_command` behavior aligned with the same payload
  construction, including interactive completions that return a final
  result directly.
  - Apply `PostToolUse` block/replacement feedback before the final
  `write_stdin` completion output is sent back to the model.
  - Keep `write_stdin` itself out of `PreToolUse` matching so it continues
  to act as transport/polling for the original Bash tool call.
  - Restore plain matcher behavior for tool-name matchers such as `Bash`
  and `Edit|Write`, while still treating patterns with regex characters
  (for example `mcp__.*`) as regexes.
  - Add unit coverage for unified exec payload construction and parallel
  session separation, plus a core integration regression that verifies a
  blocked `PostToolUse` replaces the final `write_stdin` output in model
  context.
  
  ## Testing
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-core post_tool_use_payload`
  - `cargo test -p codex-core
  post_tool_use_blocks_when_exec_session_completes_via_write_stdin`

  Andrei Eternal · 2026-04-22 17:14:22 -07:00
  eed0e07825
• fix(core): emit hooks for apply_patch edits (#18391)

  Fixes https://github.com/openai/codex/issues/16732.
  
  ## Why
  
  `apply_patch` is Codex's primary file edit path, but it was not emitting
  `PreToolUse` or `PostToolUse` hook events. That meant hook-based policy,
  auditing, and write coordination could observe shell commands while
  missing the actual file mutation performed by `apply_patch`.
  
  The issue also exposed that the hook runtime serialized command hook
  payloads with `tool_name: "Bash"` unconditionally. Even if `apply_patch`
  supplied hook payloads, hooks would either fail to match it directly or
  receive misleading stdin that identified the edit as a Bash tool call.
  
  ## What Changed
  
  - Added `PreToolUse` and `PostToolUse` payload support to
  `ApplyPatchHandler`.
  - Exposed the raw patch body as `tool_input.command` for both
  JSON/function and freeform `apply_patch` calls.
  - Taught tool hook payloads to carry a handler-supplied hook-facing
  `tool_name`.
  - Preserved existing shell compatibility by continuing to emit `Bash`
  for shell-like tools.
  - Serialized the selected hook `tool_name` into hook stdin instead of
  hardcoding `Bash`.
  - Relaxed the generated hook command input schema so `tool_name` can
  represent tools other than `Bash`.
  
  ## Verification
  
  Added focused handler coverage for:
  
  - JSON/function `apply_patch` calls producing a `PreToolUse` payload.
  - Freeform `apply_patch` calls producing a `PreToolUse` payload.
  - Successful `apply_patch` output producing a `PostToolUse` payload.
  - Shell and `exec_command` handlers continuing to expose `Bash`.
  
  Added end-to-end hook coverage for:
  
  - A `PreToolUse` hook matching `^apply_patch$` blocking the patch before
  the target file is created.
  - A `PostToolUse` hook matching `^apply_patch$` receiving the patch
  input and tool response, then adding context to the follow-up model
  request.
  - Non-participating tools such as the plan tool continuing not to emit
  `PreToolUse`/`PostToolUse` hook events.
  
  Also validated manually with a live `codex exec` smoke test using an
  isolated temp workspace and temp `CODEX_HOME`. The smoke test confirmed
  that a real `apply_patch` edit emits `PreToolUse`/`PostToolUse` with
  `tool_name: "apply_patch"`, a shell command still emits `tool_name:
  "Bash"`, and a denying `PreToolUse` hook prevents the blocked patch file
  from being created.

  Felipe Coury · 2026-04-21 22:00:40 -03:00
  09ebc34f17
• Add PermissionRequest hooks support (#17563)

  ## Why
  
  We need `PermissionRequest` hook support!
  
  Also addresses:
  - https://github.com/openai/codex/issues/16301
  - run a script on Hook to do things like play a sound to draw attention
  but actually no-op so user can still approve
  - can omit the `decision` object from output or just have the script
  exit 0 and print nothing
  - https://github.com/openai/codex/issues/15311
    - let the script approve/deny on its own
    - external UI what will run on Hook and relay decision back to codex
  
  
  ## Reviewer Note
  
  There's a lot of plumbing for the new hook, key files to review are:
  - New hook added in `codex-rs/hooks/src/events/permission_request.rs`
  - Wiring for network approvals
  `codex-rs/core/src/tools/network_approval.rs`
  - Wiring for tool orchestrator `codex-rs/core/src/tools/orchestrator.rs`
  - Wiring for execve
  `codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs`
  
  ## What
  
  - Wires shell, unified exec, and network approval prompts into the
  `PermissionRequest` hook flow.
  - Lets hooks allow or deny approval prompts; quiet or invalid hooks fall
  back to the normal approval path.
  - Uses `tool_input.description` for user-facing context when it helps:
    - shell / `exec_command`: the request justification, when present
    - network approvals: `network-access <domain>`
  - Uses `tool_name: Bash` for shell, unified exec, and network approval
  permission-request hooks.
  - For network approvals, passes the originating command in
  `tool_input.command` when there is a single owning call; otherwise falls
  back to the synthetic `network-access ...` command.
  
  <details>
  <summary>Example `PermissionRequest` hook input for a shell
  approval</summary>
  
  ```json
  {
    "session_id": "<session-id>",
    "turn_id": "<turn-id>",
    "transcript_path": "/path/to/transcript.jsonl",
    "cwd": "/path/to/cwd",
    "hook_event_name": "PermissionRequest",
    "model": "gpt-5",
    "permission_mode": "default",
    "tool_name": "Bash",
    "tool_input": {
      "command": "rm -f /tmp/example"
    }
  }
  ```
  
  </details>
  
  <details>
  <summary>Example `PermissionRequest` hook input for an escalated
  `exec_command` request</summary>
  
  ```json
  {
    "session_id": "<session-id>",
    "turn_id": "<turn-id>",
    "transcript_path": "/path/to/transcript.jsonl",
    "cwd": "/path/to/cwd",
    "hook_event_name": "PermissionRequest",
    "model": "gpt-5",
    "permission_mode": "default",
    "tool_name": "Bash",
    "tool_input": {
      "command": "cp /tmp/source.json /Users/alice/export/source.json",
      "description": "Need to copy a generated file outside the workspace"
    }
  }
  ```
  
  </details>
  
  <details>
  <summary>Example `PermissionRequest` hook input for a network
  approval</summary>
  
  ```json
  {
    "session_id": "<session-id>",
    "turn_id": "<turn-id>",
    "transcript_path": "/path/to/transcript.jsonl",
    "cwd": "/path/to/cwd",
    "hook_event_name": "PermissionRequest",
    "model": "gpt-5",
    "permission_mode": "default",
    "tool_name": "Bash",
    "tool_input": {
      "command": "curl http://codex-network-test.invalid",
      "description": "network-access http://codex-network-test.invalid"
    }
  }
  ```
  
  </details>
  
  ## Follow-ups
  
  - Implement the `PermissionRequest` semantics for `updatedInput`,
  `updatedPermissions`, `interrupt`, and suggestions /
  `permission_suggestions`
  - Add `PermissionRequest` support for the `request_permissions` tool
  path
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-17 14:45:47 +00:00
  8494e5bd7b
• Add codex_hook_run analytics event (#17996)

  # Why
  Add product analytics for hook handler executions so we can understand
  which hooks are running, where they came from, and whether they
  completed, failed, stopped, or blocked work.
  
  # What
  - add the new `codex_hook_run` analytics event and payload plumbing in
  `codex-rs/analytics`
  - emit hook-run analytics from the shared hook completion path in
  `codex-rs/core`
  - classify hook source from the loaded hook path as `system`, `user`,
  `project`, or `unknown`
  
  ```
  {
    "event_type": "codex_hook_run",
    "event_params": {
      "thread_id": "string",
      "turn_id": "string",
      "model_slug": "string",
      "hook_name": "string, // any HookEventName
      "hook_source": "system | user | project | unknown",
      "status": "completed | failed | stopped | blocked"
    }
  }
  ```
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-16 19:43:16 +00:00
  8720b7bdce
• Spread AbsolutePathBuf (#17792)

  Mechanical change to promote absolute paths through code.

  pakrym-oai · 2026-04-14 14:26:10 -07:00
  dd1321d11b
• Support clear SessionStart source (#17073)

  ## Motivation
  
  The `SessionStart` hook already receives `startup` and `resume` sources,
  but sessions created from `/clear` previously looked like normal startup
  sessions. This makes it impossible for hook authors to distinguish
  between these with the matcher.
  
  ## Summary
  
  - Add `InitialHistory::Cleared` so `/clear`-created sessions can be
  distinguished from ordinary startup sessions.
  - Add `SessionStartSource::Clear` and wire it through core, app-server
  thread start params, and TUI clear-session flow.
  - Update app-server protocol schemas, generated TypeScript, docs, and
  related tests.
  
  
  https://github.com/user-attachments/assets/9cae3cb4-41c7-4d06-b34f-966252442e5c

  Abhinav · 2026-04-10 16:05:21 -07:00
  7999b0f60f
• [codex] Improve hook status rendering (#17266)

  # Motivation
  
  Make hook display less noisy and more useful by keeping transient hook
  activity out of permanent history unless there is useful output,
  preserving visibility for meaningful hook work, and making completed
  hook severity easier to scan.
  
  Also addresses some of the concerns in
  https://github.com/openai/codex/issues/15497
  
  # Changes
  
  ## Demo
  
  
  https://github.com/user-attachments/assets/9d8cebd4-a502-4c95-819c-c806c0731288
  
  Reverse spec for the behavior changes in this branch:
  
  ## Hook Lifecycle Rendering
  - Hook start events no longer write permanent history rows like `Running
  PreToolUse hook`.
  - Running hooks now render in a dedicated live hook area above the
  composer. It's similar to the active cell we use for tool calls but its
  a separate lane.
  - Running hook rows use the existing animation setting.
  
  ## Hook Reveal Timing
  - We wait 300ms before showing running hook rows and linger for up to
  600ms once visible.
  - This is so fast hooks don't flash a transient `Running hook` row
  before user can read it every time.
  - If a fast hook completes with meaningful output, only the completed
  hook result is written to history.
  - If a fast hook completes successfully with no output, it leaves no
  visible trace.
  
  ## Completed Hook Output
  - Completed hooks with output are sticky, for example `• SessionStart
  hook (completed)`.
  - Hook output entries are rendered under that row with stable prefixes:
  `warning:`, `stop:`, `feedback:`, `hook context:`, and `error:`.
  - Blocked hooks show feedback entries, for example `• PreToolUse hook
  (blocked)` followed by `feedback: ...`.
  - Failed hooks show error entries, for example `• PostToolUse hook
  (failed)` followed by `error: ...`.
  - Stopped hooks show stop entries and remain visually treated as
  non-success.
  
  ## Parallel Hook Behavior
  - Multiple simultaneously running hooks can be tracked in one live hook
  cell.
  - Adjacent running hooks with the same hook event name and same status
  message collapse into a count, for example `• Running 3 PreToolUse
  hooks: checking command policy`.
  - Running hooks with different event names or different status messages
  remain separate rows.
  
  ## Hook Run Identity
  - `PreToolUse` and `PostToolUse` hook run IDs now include the tool call
  ID which prevents concurrent tool-use hooks from sharing a run ID and
  clobbering each other in the UI.
  - This ID scoping applies to tool-use hooks only; other hook event types
  keep their existing run identity behavior.
  
  ## App-Server Hook Notifications
  - App-server `HookStarted` and `HookCompleted` notifications use the
  same live hook rendering path as core hook events.
  - `UserPromptSubmit` hook notifications now render through the same
  completed hook output format, including warning and stop entries.

  Abhinav · 2026-04-10 14:05:47 -07:00
  87b9275fff
• remove windows gate that disables hooks (#17268)

  they work!

  iceweasel-oai · 2026-04-09 16:54:35 -07:00
  a44645129a
• [codex] Make AbsolutePathBuf joins infallible (#16981)

  Having to check for errors every time join is called is painful and
  unnecessary.

  pakrym-oai · 2026-04-07 10:52:08 -07:00
  f1a2b920f9
• [codex] reduce module visibility (#16978)

  ## Summary
  - reduce public module visibility across Rust crates, preferring private
  or crate-private modules with explicit crate-root public exports
  - update external call sites and tests to use the intended public crate
  APIs instead of reaching through module trees
  - add the module visibility guideline to AGENTS.md
  
  ## Validation
  - `cargo check --workspace --all-targets --message-format=short` passed
  before the final fix/format pass
  - `just fix` completed successfully
  - `just fmt` completed successfully
  - `git diff --check` passed

  pakrym-oai · 2026-04-07 08:03:35 -07:00
  413c1e1fdf
• chore: clean up argument-comment lint and roll out all-target CI on macOS (#16054)

  ## Why
  
  `argument-comment-lint` was green in CI even though the repo still had
  many uncommented literal arguments. The main gap was target coverage:
  the repo wrapper did not force Cargo to inspect test-only call sites, so
  examples like the `latest_session_lookup_params(true, ...)` tests in
  `codex-rs/tui_app_server/src/lib.rs` never entered the blocking CI path.
  
  This change cleans up the existing backlog, makes the default repo lint
  path cover all Cargo targets, and starts rolling that stricter CI
  enforcement out on the platform where it is currently validated.
  
  ## What changed
  
  - mechanically fixed existing `argument-comment-lint` violations across
  the `codex-rs` workspace, including tests, examples, and benches
  - updated `tools/argument-comment-lint/run-prebuilt-linter.sh` and
  `tools/argument-comment-lint/run.sh` so non-`--fix` runs default to
  `--all-targets` unless the caller explicitly narrows the target set
  - fixed both wrappers so forwarded cargo arguments after `--` are
  preserved with a single separator
  - documented the new default behavior in
  `tools/argument-comment-lint/README.md`
  - updated `rust-ci` so the macOS lint lane keeps the plain wrapper
  invocation and therefore enforces `--all-targets`, while Linux and
  Windows temporarily pass `-- --lib --bins`
  
  That temporary CI split keeps the stricter all-targets check where it is
  already cleaned up, while leaving room to finish the remaining Linux-
  and Windows-specific target-gated cleanup before enabling
  `--all-targets` on those runners. The Linux and Windows failures on the
  intermediate revision were caused by the wrapper forwarding bug, not by
  additional lint findings in those lanes.
  
  ## Validation
  
  - `bash -n tools/argument-comment-lint/run.sh`
  - `bash -n tools/argument-comment-lint/run-prebuilt-linter.sh`
  - shell-level wrapper forwarding check for `-- --lib --bins`
  - shell-level wrapper forwarding check for `-- --tests`
  - `just argument-comment-lint`
  - `cargo test` in `tools/argument-comment-lint`
  - `cargo test -p codex-terminal-detection`
  
  ## Follow-up
  
  - Clean up remaining Linux-only target-gated callsites, then switch the
  Linux lint lane back to the plain wrapper invocation.
  - Clean up remaining Windows-only target-gated callsites, then switch
  the Windows lint lane back to the plain wrapper invocation.

  Michael Bolin · 2026-03-27 19:00:44 -07:00
  61dfe0b86c
• [hooks] add non-streaming (non-stdin style) shell-only PostToolUse support (#15531)

  CHAINED PR - note that base is eternal/hooks-pretooluse-bash, not main
  -- so the following PR should be first
  
  Matching post-tool hook to the pre-tool functionality here:
  https://github.com/openai/codex/pull/15211
  
  So, PreToolUse calls for plain shell calls, allows blocking. This
  PostToolUse call runs after the command executed
  
  example run:
  
  ```
  › as a test, run in parallel the following commands:
    - echo 'one'
    - echo '[block-pre-tool-use]'
    - echo '[block-post-tool-use]'
  
  
  ⚠ MCP startup incomplete (failed: notion, linear)
  
  • Cruising through those three commands in parallel now, and I’ll share the exact outputs right after
    they land.
  
  • Running PreToolUse hook: checking the observatory runes
  
  • Running PreToolUse hook: checking the observatory runes
  
  • Running PreToolUse hook: checking the observatory runes
  
  PreToolUse hook (blocked)
    warning: wizard-tower PreToolUse demo blocked a Bash command on purpose.
    feedback: PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.
  
  PreToolUse hook (completed)
    warning: wizard-tower PreToolUse demo inspected Bash: echo 'one'
  
  PreToolUse hook (completed)
    warning: wizard-tower PreToolUse demo inspected Bash: echo '[block-post-tool-use]'
  
  • Ran echo '[block-post-tool-use]'
    └ [block-post-tool-use]
  
  • Ran echo 'one'
    └ one
  
  • Running PostToolUse hook: reading the observatory aftermath
  
  • Running PostToolUse hook: reading the observatory aftermath
  
  PostToolUse hook (blocked)
    warning: wizard-tower PostToolUse demo blocked the Bash follow-through on purpose.
    feedback: PostToolUse demo blocked the result after execution. Remove [block-post-tool-use] to
  continue.
  
  PostToolUse hook (completed)
    warning: wizard-tower PostToolUse demo inspected Bash: echo 'one'
    hook context: PostToolUse demo saw the Bash result. Response preview: one
  
  ──────────────────────────────────────────────────────────────────────────────────────────────────────
  
  • Ran them in parallel. Little wave report:
  
    - echo 'one' completed and returned one.
    - echo '[block-pre-tool-use]' was blocked before execution by the PreToolUse hook.
    - echo '[block-post-tool-use]' ran, but its result was blocked afterward by the PostToolUse hook.
  
    The hook messages were:
  
    - PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.
    - PostToolUse demo blocked the result after execution. Remove [block-post-tool-use] to continue.
  
  
  › for the blocked messages (correctly blocked in this test) did the tool output land back into
    context?
  
  
  • Yeah, from this run:
  
    - PreToolUse block: the command itself did not execute, so no command output landed in context. Only
      the block message did.
    - PostToolUse block: the command did execute, but the actual stdout did not come back into context.
      Only the post-tool block message did.
  
    So the blocked notifications landed in context, but the blocked command payloads themselves did not.
    Nice clean guardrail, aloha.
  ```

  Andrei Eternal · 2026-03-25 19:18:03 -07:00
  c4d9887f9a