Expose hook capabilities and a session-exit hook for integrations

What problem are you trying to solve?

Tools that integrate with Codex hooks currently have to guess which hook events the active codex binary supports.

For example, a terminal/workspace integration can safely use the existing turn/status hooks to show activity:

• SessionStart
• UserPromptSubmit
• Stop

That works for showing "running" while Codex responds and "idle" after the turn stops.

However, integrations that want reliable session recovery/resume also need a lifecycle signal when the Codex session itself exits, not only when a turn stops. Today there does not appear to be a stable upstream hook event for that session-exit boundary, and there is also no non-interactive way to ask the active codex binary which hook events it supports.

This makes third-party setup brittle:

• If an integration only installs the known upstream hooks, status works but resume-on-exit cannot be implemented reliably.
• If it installs a non-upstream or fork-specific lifecycle hook, it may write config for events the user's Codex build will never emit.
• Detecting support via binary path, version string, package manager, or wrapper scripts is fragile.

Related but distinct: #17333 asks for a task-completion hook. This request is about hook capability introspection and a session/process lifecycle event, not only task completion.

Proposed solution

Add a fast, non-interactive hook capability command, for example:

codex hooks capabilities --json

Example output:

{
  "schema_version": 1,
  "events": [
    "SessionStart",
    "UserPromptSubmit",
    "Stop",
    "SessionEnd"
  ],
  "features": {
    "session_resume_lifecycle": true
  }
}

The exact command/name is not important; the important part is that integrations can ask the active codex binary what it actually supports before writing hook config.

Then integrations can safely do:

1. Probe the active codex binary.
2. Install only hook events reported as supported.
3. Fall back to upstream-safe events if the probe command is missing.

Session-exit / resume hook

It would also be useful to have an upstream lifecycle hook for session exit, conceptually something like SessionEnd, emitted when a Codex session exits or is intentionally closed.

Useful payload fields would include:

{
  "session_id": "...",
  "cwd": "...",
  "reason": "user_requested | interrupted | error | ..."
}

This would let terminal/workspace integrations offer a precise codex resume <session_id> affordance only when appropriate. The current Stop hook is useful for turn completion/status, but it is not a reliable signal that the interactive Codex session/process has ended.

Why this belongs in Codex

Codex is the component that knows which hook events it emits. External integrations should not have to infer that from PATH, package manager state, release versions, or fork-specific wrapper behavior.

A small capability surface would make hook integrations conservative by default while leaving room for new hook events to be adopted safely as Codex evolves.