Docs: SessionStart source field omits clear value

Open 💬 2 comments Opened Apr 26, 2026 by jozefizso

What is the documentation issue?

The Codex hooks documentation appears to be internally inconsistent about the possible values for the SessionStart event source field.

On the Hooks page, the matcher table says:

SessionStart start source: Current runtime values are startup, resume, and clear

The examples directly below it also include:

startup|resume|clear

But the SessionStart event-specific field table says:

source string: How the session started: startup or resume

Why this matters

Hook configurations commonly use matcher against the SessionStart.source value. If someone follows the event-specific field table, they may configure a matcher such as startup|resume and unintentionally skip hooks after /clear, even though the matcher section documents clear as a current runtime value.

One concrete example is a startup hook that runs bd prime to load workspace issue-tracker context. With matcher: "startup|resume", the hook runs on normal startup and resume, but not after /clear, leaving the session without the expected context.

Suggested fix

Update the SessionStart.source field description to include clear, or otherwise clarify whether clear is a supported public runtime value for SessionStart.

Relevant docs page: https://developers.openai.com/codex/hooks#sessionstart

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗