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
What is the documentation issue?
The Codex hooks documentation appears to be internally inconsistent about the possible values for the
SessionStarteventsourcefield.On the Hooks page, the matcher table says:
The examples directly below it also include:
But the
SessionStartevent-specific field table says:Why this matters
Hook configurations commonly use
matcheragainst theSessionStart.sourcevalue. If someone follows the event-specific field table, they may configure a matcher such asstartup|resumeand unintentionally skip hooks after/clear, even though the matcher section documentsclearas a current runtime value.One concrete example is a startup hook that runs
bd primeto load workspace issue-tracker context. Withmatcher: "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.sourcefield description to includeclear, or otherwise clarify whetherclearis a supported public runtime value forSessionStart.Relevant docs page: https://developers.openai.com/codex/hooks#sessionstart