49 Commits

• 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
• [hooks] add non-streaming (non-stdin style) shell-only PreToolUse support (#15211)

  - add `PreToolUse` hook for bash-like tool execution only at first
  - block shell execution before dispatch with deny-only hook behavior
  - introduces common.rs matcher framework for matching when hooks are run
  
  example run:
  
  ```
  › run three parallel echo commands, and the second one should echo "[block-pre-tool-use]" as a test
  
  
  • Running the three echo commands in parallel now and I’ll report the output directly.
  
  • Running PreToolUse hook: name for demo pre tool use hook
  
  • Running PreToolUse hook: name for demo pre tool use hook
  
  • Running PreToolUse hook: name for demo pre tool use hook
  
  PreToolUse hook (completed)
    warning: wizard-tower PreToolUse demo inspected Bash: echo "first parallel echo"
    
  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 "third parallel echo"
  
  • Ran echo "first parallel echo"
    └ first parallel echo
  
  • Ran echo "third parallel echo"
    └ third parallel echo
  
  • Three little waves went out in parallel.
  
    1. printed first parallel echo
    2. was blocked before execution because it contained the exact test string [block-pre-tool-use]
    3. printed third parallel echo
  
    There was also an unrelated macOS defaults warning around the successful commands, but the echoes
    themselves worked fine. If you want, I can rerun the second one with a slightly modified string so
    it passes cleanly.
  ```

  Andrei Eternal · 2026-03-23 14:32:59 -07:00
  73bbb07ba8
• Disable hooks on windows for now (#15252)

  We'll verify a bit later that all of this works correctly and re-enable

  Andrei Eternal · 2026-03-19 21:31:56 -07:00
  cc192763e1
• [hooks] use a user message > developer message for prompt continuation (#14867)

  ## Summary
  
  Persist Stop-hook continuation prompts as `user` messages instead of
  hidden `developer` messages + some requested integration tests
  
  This is a followup to @pakrym 's comment in
  https://github.com/openai/codex/pull/14532 to make sure stop-block
  continuation prompts match training for turn loops
  
  - Stop continuation now writes `<hook_prompt hook_run_id="...">stop
  hook's user prompt<hook_prompt>`
  - Introduces quick-xml dependency, though we already indirectly depended
  on it anyway via syntect
  - This PR only has about 500 lines of actual logic changes, the rest is
  tests/schema
  
  ## Testing
  
  Example run (with a sessionstart hook and 3 stop hooks) - this shows
  context added by session start, then two stop hooks sending their own
  additional prompts in a new turn. The model responds with a single
  message addressing both. Then when that turn ends, the hooks detect that
  they just ran using `stop_hook_active` and decide not to infinite loop
  
  test files for this (unzip, move codex -> .codex):
  [codex.zip](https://github.com/user-attachments/files/26075806/codex.zip)
  
  ```
  › cats
  
  
  • Running SessionStart hook: lighting the observatory
  
  SessionStart hook (completed)
    warning: Hi, I'm a session start hook for wizard-tower (startup).
    hook context: A wimboltine stonpet is an exotic cuisine from hyperspace
  
  • Cats are tiny zen wizards, my friend: equal parts nap, mystery, and chaos. If you want, we can talk
    cat facts, cat breeds, cat names, or build something cat-themed in this repo.
  
  • Running Stop hook: checking the tower wards
  
  • Running Stop hook: sacking the guards
  
  • Running Stop hook: hiring the guards
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook reviewed the completed reply (177 chars).
  
  Stop hook (blocked)
    warning: Wizard Tower Stop hook continuing conversation
    feedback: cook the stonpet
  
  Stop hook (blocked)
    warning: Wizard Tower Stop hook continuing conversation
    feedback: eat the cooked stonpet
  
  • Stonpet’s cooked, aloha style: flash-seared over a blue quasiflame, glazed with nebula salt, and
    rested until the hyperspace juices settle.
  
    Now we eat with gratitude, my friend. One mindful bite in, and the flavor is pure cosmic surf:
    smoky, bright, and totally out of this dimension.
  
  • Running Stop hook: checking the tower wards
  
  • Running Stop hook: sacking the guards
  
  • Running Stop hook: hiring the guards
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook reviewed the completed reply (285 chars).
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook saw a second pass and stayed calm to avoid a loop.
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook saw a second pass and stayed calm to avoid a loop.
  ```

  Andrei Eternal · 2026-03-19 10:53:08 -07:00
  267499bed8
• [hooks] turn_id extension for Stop & UserPromptSubmit (#15118)

  ## Description
  
  Adding an extension to the spec that exposes the turn_id to hook
  scripts. This is a codex-specific mechanic that allows connecting the
  hook runs with particular turns
  
  ## Testing
  
  hooks config / sample hooks to use. Extract this, rename codex ->
  .codex, and place this into a repo or your home folder. It includes:
  config.toml that enables hooks, hooks.json, and sample python hooks:
  
  
  [codex.zip](https://github.com/user-attachments/files/26102671/codex.zip)
  
  example run (note the turn_ids change between turns):
  
  ```
  › hello
  
  
  • Running SessionStart hook: lighting the observatory
  
  SessionStart hook (completed)
    warning: Hi, I'm a session start hook for wizard-tower (startup).
    hook context: Startup context: A wimboltine stonpet is an exotic cuisine from hyperspace
  
  • Running UserPromptSubmit hook: lighting the observatory lanterns
  
  UserPromptSubmit hook (completed)
    warning: wizard-tower UserPromptSubmit demo inspected: hello for turn: 019d036d-c7fa-72d2-b6fd-
  78878bfe34e4
    hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
  phrase 'observatory lanterns lit' near the end.
  
  • Aloha! Grateful to be here and ready to build with you. Show me what you want to tackle in wizard-
    tower, and we’ll surf the next wave together. observatory lanterns lit
  
  • Running Stop hook: back to shore
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook reviewed the completed reply (170 chars) for turn: 019d036d-c7fa-
  72d2-b6fd-78878bfe34e4
  
  
  › what's a stonpet?
  
  
  • Running UserPromptSubmit hook: lighting the observatory lanterns
  
  UserPromptSubmit hook (completed)
    warning: wizard-tower UserPromptSubmit demo inspected: what's a stonpet? for turn: 019d036e-3164-
  72c3-a170-98925564c4fc
    hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
  phrase 'observatory lanterns lit' near the end.
  
  • A stonpet isn’t a standard real-world word, brah. In our shared context here, a wimboltine stonpet
    is an exotic cuisine from hyperspace, so “stonpet” sounds like the dish or food itself.
  
    If you want, we can totally invent the lore for it next. observatory lanterns lit
  
  • Running Stop hook: back to shore
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook reviewed the completed reply (271 chars) for turn: 019d036e-3164-
  72c3-a170-98925564c4fc
  ```

  Andrei Eternal · 2026-03-18 21:48:31 -07:00
  42e932d7bf
• [hooks] userpromptsubmit - hook before user's prompt is executed (#14626)

  - this allows blocking the user's prompts from executing, and also
  prevents them from entering history
  - handles the edge case where you can both prevent the user's prompt AND
  add n amount of additionalContexts
  - refactors some old code into common.rs where hooks overlap
  functionality
  - refactors additionalContext being previously added to user messages,
  instead we use developer messages for them
  - handles queued messages correctly
  
  Sample hook for testing - if you write "[block-user-submit]" this hook
  will stop the thread:
  
  example run
  ```
  › sup
  
  
  • Running UserPromptSubmit hook: reading the observatory notes
  
  UserPromptSubmit hook (completed)
    warning: wizard-tower UserPromptSubmit demo inspected: sup
    hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
  phrase 'observatory lanterns lit' exactly once near the end.
  
  • Just riding the cosmic wave and ready to help, my friend. What are we building today? observatory
    lanterns lit
  
  
  › and [block-user-submit]
  
  
  • Running UserPromptSubmit hook: reading the observatory notes
  
  UserPromptSubmit hook (stopped)
    warning: wizard-tower UserPromptSubmit demo blocked the prompt on purpose.
    stop: Wizard Tower demo block: remove [block-user-submit] to continue.
  ```
  
  .codex/config.toml
  ```
  [features]
  codex_hooks = true
  ```
  
  .codex/hooks.json
  ```
  {
    "hooks": {
      "UserPromptSubmit": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "/usr/bin/python3 .codex/hooks/user_prompt_submit_demo.py",
              "timeoutSec": 10,
              "statusMessage": "reading the observatory notes"
            }
          ]
        }
      ]
    }
  }
  ```
  
  .codex/hooks/user_prompt_submit_demo.py
  ```
  #!/usr/bin/env python3
  
  import json
  import sys
  from pathlib import Path
  
  
  def prompt_from_payload(payload: dict) -> str:
      prompt = payload.get("prompt")
      if isinstance(prompt, str) and prompt.strip():
          return prompt.strip()
  
      event = payload.get("event")
      if isinstance(event, dict):
          user_prompt = event.get("user_prompt")
          if isinstance(user_prompt, str):
              return user_prompt.strip()
  
      return ""
  
  
  def main() -> int:
      payload = json.load(sys.stdin)
      prompt = prompt_from_payload(payload)
      cwd = Path(payload.get("cwd", ".")).name or "wizard-tower"
  
      if "[block-user-submit]" in prompt:
          print(
              json.dumps(
                  {
                      "systemMessage": (
                          f"{cwd} UserPromptSubmit demo blocked the prompt on purpose."
                      ),
                      "decision": "block",
                      "reason": (
                          "Wizard Tower demo block: remove [block-user-submit] to continue."
                      ),
                  }
              )
          )
          return 0
  
      prompt_preview = prompt or "(empty prompt)"
      if len(prompt_preview) > 80:
          prompt_preview = f"{prompt_preview[:77]}..."
  
      print(
          json.dumps(
              {
                  "systemMessage": (
                      f"{cwd} UserPromptSubmit demo inspected: {prompt_preview}"
                  ),
                  "hookSpecificOutput": {
                      "hookEventName": "UserPromptSubmit",
                      "additionalContext": (
                          "Wizard Tower UserPromptSubmit demo fired. "
                          "For this reply only, include the exact phrase "
                          "'observatory lanterns lit' exactly once near the end."
                      ),
                  },
              }
          )
      )
      return 0
  
  
  if __name__ == "__main__":
      raise SystemExit(main())
  ```

  Andrei Eternal · 2026-03-17 22:09:22 -07:00
  6fef421654
• Apply argument comment lint across codex-rs (#14652)

  ## Why
  
  Once the repo-local lint exists, `codex-rs` needs to follow the
  checked-in convention and CI needs to keep it from drifting. This commit
  applies the fallback `/*param*/` style consistently across existing
  positional literal call sites without changing those APIs.
  
  The longer-term preference is still to avoid APIs that require comments
  by choosing clearer parameter types and call shapes. This PR is
  intentionally the mechanical follow-through for the places where the
  existing signatures stay in place.
  
  After rebasing onto newer `main`, the rollout also had to cover newly
  introduced `tui_app_server` call sites. That made it clear the first cut
  of the CI job was too expensive for the common path: it was spending
  almost as much time installing `cargo-dylint` and re-testing the lint
  crate as a representative test job spends running product tests. The CI
  update keeps the full workspace enforcement but trims that extra
  overhead from ordinary `codex-rs` PRs.
  
  ## What changed
  
  - keep a dedicated `argument_comment_lint` job in `rust-ci`
  - mechanically annotate remaining opaque positional literals across
  `codex-rs` with exact `/*param*/` comments, including the rebased
  `tui_app_server` call sites that now fall under the lint
  - keep the checked-in style aligned with the lint policy by using
  `/*param*/` and leaving string and char literals uncommented
  - cache `cargo-dylint`, `dylint-link`, and the relevant Cargo
  registry/git metadata in the lint job
  - split changed-path detection so the lint crate's own `cargo test` step
  runs only when `tools/argument-comment-lint/*` or `rust-ci.yml` changes
  - continue to run the repo wrapper over the `codex-rs` workspace, so
  product-code enforcement is unchanged
  
  Most of the code changes in this commit are intentionally mechanical
  comment rewrites or insertions driven by the lint itself.
  
  ## Verification
  
  - `./tools/argument-comment-lint/run.sh --workspace`
  - `cargo test -p codex-tui-app-server -p codex-tui`
  - parsed `.github/workflows/rust-ci.yml` locally with PyYAML
  
  ---
  
  * -> #14652
  * #14651

  Michael Bolin · 2026-03-16 16:48:15 -07:00
  b77fe8fefe
• [hooks] stop continuation & stop_hook_active mechanics (#14532)

  Stop hooks now receive `stop_hook_active` and enable stop hooks to loop
  forever if they'd like to. In the initial hooks PR, we implemented a
  simpler mechanic that the stop-blocking could only happen once in a row
  
  - support stop hook adding a continuation prompt to add a further task
  - if multiple stop-blocks happen that have continuation prompts, they
  are concatenated
  
  example run:
  ```
  › hey :)
  
  
  • Running SessionStart hook: lighting the observatory
  
  SessionStart hook (completed)
    warning: Hi, I'm a session start hook for wizard-tower (startup).
    hook context: Startup context: A wimboltine stonpet is an exotic cuisine from hyperspace
  
  • Aloha :) Happy to jam with you. What are we building today?
  
  • Running Stop hook: updating the guards
  
  Stop hook (blocked)
    warning: Wizard Tower Stop hook continuing conversation
    feedback: cook the stonpet
  
  • Aloha, here’s the hyperspace move for cooking a wimboltine stonpet:
  
    1. Sear the stonpet in a hot pan with moon-oil until the edges shimmer.
    2. Add star-lime, black salt, and a little fermented nebula paste.
    3. Lower the heat and let it braise for 8 cosmic minutes with a splash of comet broth.
    4. Finish with sky herbs and serve over warm asteroid rice.
  
    The vibe: crispy outside, tender center, deep interdimensional savor.
  
  • Running Stop hook: updating the guards
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook saw a second pass and stayed calm to avoid a loop.
  ```
  
  .codex/config.toml
  ```
  [features]
  codex_hooks = true
  ```
  
  .codex/hooks.json
  ```
  {
    "hooks": {
      "SessionStart": [
        {
          "matcher": "startup|resume",
          "hooks": [
            {
              "type": "command",
              "command": "/usr/bin/python3 .codex/hooks/session_start_demo.py",
              "timeoutSec": 10,
              "statusMessage": "lighting the observatory"
            }
          ]
        }
      ],
      "Stop": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "/usr/bin/python3 .codex/hooks/stop_demo_block.py",
              "timeoutSec": 10,
              "statusMessage": "updating the guards"
            }
          ]
        }
      ]
    }
  }
  ```
  
  .codex/hooks/session_start_demo.py
  ```
  #!/usr/bin/env python3
  
  import json
  import sys
  from pathlib import Path
  
  
  def main() -> int:
      payload = json.load(sys.stdin)
      cwd = Path(payload.get("cwd", ".")).name or "wizard-tower"
      source = payload.get("source", "startup")
      source_label = "resume" if source == "resume" else "startup"
      source_prefix = (
          "Resume context:"
          if source == "resume"
          else "Startup context:"
      )
  
      output = {
          "systemMessage": (
              f"Hi, I'm a session start hook for {cwd} ({source_label})."
          ),
          "hookSpecificOutput": {
              "hookEventName": "SessionStart",
              "additionalContext": (
                  f"{source_prefix} A wimboltine stonpet is an exotic cuisine from hyperspace"
              ),
          },
      }
      print(json.dumps(output))
      return 0
  
  
  if __name__ == "__main__":
      raise SystemExit(main())
  ```
  
  .codex/hooks/stop_demo_block.py
  ```
  #!/usr/bin/env python3
  
  import json
  import sys
  
  
  def main() -> int:
      payload = json.load(sys.stdin)
      stop_hook_active = payload.get("stop_hook_active", False)
      last_assistant_message = payload.get("last_assistant_message") or ""
      char_count = len(last_assistant_message.strip())
  
      if stop_hook_active:
          system_message = (
              "Wizard Tower Stop hook saw a second pass and stayed calm to avoid a loop."
          )
          print(json.dumps({"systemMessage": system_message}))
      else:
          system_message = (
              f"Wizard Tower Stop hook continuing conversation"
          )
          print(json.dumps({"systemMessage": system_message, "decision": "block", "reason": "cook the stonpet"}))
  
      return 0
  
  
  if __name__ == "__main__":
      raise SystemExit(main())
  ```

  Andrei Eternal · 2026-03-13 15:51:19 -07:00
  9a44a7e499
• start of hooks engine (#13276)

  (Experimental)
  
  This PR adds a first MVP for hooks, with SessionStart and Stop
  
  The core design is:
  
  - hooks live in a dedicated engine under codex-rs/hooks
  - each hook type has its own event-specific file
  - hook execution is synchronous and blocks normal turn progression while
  running
  - matching hooks run in parallel, then their results are aggregated into
  a normalized HookRunSummary
  
  On the AppServer side, hooks are exposed as operational metadata rather
  than transcript-native items:
  
  - new live notifications: hook/started, hook/completed
  - persisted/replayed hook results live on Turn.hookRuns
  - we intentionally did not add hook-specific ThreadItem variants
  
  Hooks messages are not persisted, they remain ephemeral. The context
  changes they add are (they get appended to the user's prompt)

  Andrei Eternal · 2026-03-10 04:11:31 +00:00
  244b2d53f4
• notify: include client in legacy hook payload (#12968)

  ## Why
  
  The `notify` hook payload did not identify which Codex client started
  the turn. That meant downstream notification hooks could not distinguish
  between completions coming from the TUI and completions coming from
  app-server clients such as VS Code or Xcode. Now that the Codex App
  provides its own desktop notifications, it would be nice to be able to
  filter those out.
  
  This change adds that context without changing the existing payload
  shape for callers that do not know the client name, and keeps the new
  end-to-end test cross-platform.
  
  ## What changed
  
  - added an optional top-level `client` field to the legacy `notify` JSON
  payload
  - threaded that value through `core` and `hooks`; the internal session
  and turn state now carries it as `app_server_client_name`
  - set the field to `codex-tui` for TUI turns
  - captured `initialize.clientInfo.name` in the app server and applied it
  to subsequent turns before dispatching hooks
  - replaced the notify integration test hook with a `python3` script so
  the test does not rely on Unix shell permissions or `bash`
  - documented the new field in `docs/config.md`
  
  ## Testing
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-tui`
  - `cargo test -p codex-app-server
  suite::v2::initialize::turn_start_notify_payload_includes_initialize_client_name
  -- --exact --nocapture`
  - `cargo test -p codex-core` (`src/lib.rs` passed; `core/tests/all.rs`
  still has unrelated existing failures in this environment)
  
  ## Docs
  
  The public config reference on `developers.openai.com/codex` should
  mention that the legacy `notify` payload may include a top-level
  `client` field. The TUI reports `codex-tui`, and the app server reports
  `initialize.clientInfo.name` when it is available.

  Michael Bolin · 2026-02-26 22:27:34 -08:00
  e6cd75a684
• Allow hooks to error (#11615)

  Allow hooks to return errors. 
  
  We should do this before introducing more hook types, or we'll have to
  migrate them all.

  gt-oai · 2026-02-16 14:11:05 +00:00
  b3095679ed
• Add AfterToolUse hook (#11335)

  Not wired up to config yet. (So we can change the name if we want)
  
  An example payload:
  
  ```
  {
    "session_id": "019c48b7-7098-7b61-bc48-32e82585d451",
    "cwd": "/Users/gt/code/codex/codex-rs",
    "triggered_at": "2026-02-10T18:02:31Z",
    "hook_event": {
      "event_type": "after_tool_use",
      "turn_id": "4",
      "call_id": "call_iuo4DqWgjE7OxQywnL2UzJUE",
      "tool_name": "apply_patch",
      "tool_kind": "custom",
      "tool_input": {
        "input_type": "custom",
        "input": "*** Begin Patch\n*** Update File: README.md\n@@\n-# Codex CLI hello (Rust Implementation)\n+# Codex CLI (Rust Implementation)\n*** End Patch\n"
      },
      "executed": true,
      "success": true,
      "duration_ms": 37,
      "mutating": true,
      "sandbox": "none",
      "sandbox_policy": "danger-full-access",
      "output_preview": "{\"output\":\"Success. Updated the following files:\\nM README.md\\n\",\"metadata\":{\"exit_code\":0,\"duration_seconds\":0.0}}"
    }
  }
  ```

  gt-oai · 2026-02-11 22:25:04 +00:00
  7112e16809
• Extract hooks into dedicated crate (#11311)

  Summary
  - move `core/src/hooks` implementation into a new `codex-hooks` crate
  with its own manifest
  - update `codex-rs` workspace and `codex-core` crate to depend on the
  extracted `hooks` crate and wire up the shared APIs
  - ensure references, modules, and lockfile reflect the new crate layout
  
  Testing
  - Not run (not requested)

  jif-oai · 2026-02-10 13:42:17 +00:00
  d735df1f50