Expose goal status to external notify hooks

What variant of Codex are you using?

App

Observed on Codex App 26.506.31421 (2620) on macOS (Darwin 25.4.0 arm64 arm).

What feature would you like to see?

Please expose /goal state to the external notify hook, or provide an equivalent goal-aware notification policy.

The concrete user need is: for long-running /goal work, notify when the goal finishes, but do not notify on every intermediate autonomous turn while the goal is still active or paused.

A minimal extension to the existing agent-turn-complete payload would be enough:

{
  "type": "agent-turn-complete",
  "thread-id": "...",
  "turn-id": "...",
  "goal": {
    "status": "active | paused | budget_limited | complete",
    "id": "..."
  }
}

goal could be null or omitted for non-goal threads. The exact field names do not matter much; the important part is a supported, machine-readable distinction between:

• no goal on this thread
• goal still running (active, paused, budget_limited)
• goal finished (complete)

An alternate solution would also work, for example a config option such as:

notifications_goal_mode = "complete-only"

Additional information

This is related to, but narrower than, #16484 and #19921. Those ask for a broader external event surface / more notify event types. This request is specifically about making the existing completion notification usable with /goal without requiring users to inspect Codex internals.

Current workaround: a local notify wrapper can query ~/.codex/state_5.sqlite, table thread_goals, by thread-id. That table already has the useful state shape:

active | paused | budget_limited | complete

The workaround works for personal use, but it depends on an internal SQLite schema and is therefore not a stable integration contract.

Why this seems worth exposing: /goal is specifically for longer-running work, which makes normal turn-completion notifications noisy. The useful alert is usually the terminal state: goal completed, budget-limited, or blocked/paused. A structured goal status in the existing hook would let users implement quiet, reliable goal-completion alerts without Codex needing to ship any particular downstream notification backend.