codex

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

5 Commits