Skip to content

feat: support Codex hooks engine (v0.114.0+) SessionStart/Stop events#61

Merged
boxp merged 4 commits intomainfrom
feat/codex-hooks-v0.114.0
Mar 12, 2026
Merged

feat: support Codex hooks engine (v0.114.0+) SessionStart/Stop events#61
boxp merged 4 commits intomainfrom
feat/codex-hooks-v0.114.0

Conversation

@boxp
Copy link
Copy Markdown
Owner

@boxp boxp commented Mar 12, 2026

Summary

  • Add Codex hooks (v0.114.0+) SessionStart / Stop event support to ceeker hook handler
  • Existing notify mechanism preserved as fallback for pre-v0.114.0 Codex versions
  • README (en/ja) updated with Codex hooks configuration example using async execution

Why hooks support now

Codex rust-v0.114.0 introduced an experimental hooks engine with SessionStart and Stop hook events. This enables ceeker to receive session lifecycle events via stdin JSON (same mechanism as Claude Code hooks), providing a cleaner integration path compared to the notify argv-based approach.

Hooks vs notify fallback strategy

  • Hooks (recommended): ~/.codex/hooks.json — stdin JSON payload with session_id, cwd, hook_event_name, last_assistant_message
  • Notify (fallback): ~/.codex/config.toml notify array — argv-based JSON payload
  • Both pathways share the same normalization pipeline (codex-event-fields, extract-codex-identity)
  • The handler uses hook_event_name field (present in hooks payloads) as a new resolution source in resolve-codex-event

Async config choice

The README config examples use async: true so ceeker hooks run in the background and do not block the Codex agent loop. A note warns that async may not be supported in all versions and provides a sync fallback.

Changes

  • handler.clj: Add SessionStart, Stop (PascalCase) to codex-event-fields; hook_event_name fallback in resolve-codex-event; session_start to SessionStart mapping in codex-type->event; last_assistant_message capture on Stop
  • handler_test.clj: 7 new tests covering hooks SessionStart/Stop normalization, hook_event_name fallback, lifecycle E2E, snake_case mapping, notify regression
  • README.md / README.ja.md: Codex hooks (recommended) + notify (fallback) sections

Tests

  • Codex hooks SessionStart normalization: running, no message
  • Codex hooks Stop normalization: completed, captures last_assistant_message
  • Codex hooks Stop without message: falls back to "session ended"
  • hook_event_name fallback resolution (no explicit CLI event-type)
  • Full SessionStart to Stop lifecycle E2E with store verification
  • session_start snake_case via type field mapping
  • Notify pathway regression test

Residual risk / review points

  • Codex hooks engine is experimental — config format may change in future releases
  • async: true may produce a warning in current Codex versions (noted in README)
  • Only SessionStart and Stop events are available; no Notification equivalent yet in Codex hooks
  • ceeker hook handler is intentionally kept lightweight to minimize sync execution impact

@boxp boxp merged commit e8e0836 into main Mar 12, 2026
6 checks passed
@boxp boxp deleted the feat/codex-hooks-v0.114.0 branch March 12, 2026 04:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant