Expose effective approval reviewer to PermissionRequest hooks or support explicit defer

What variant of Codex are you using?

Codex CLI and Codex Desktop / app-server approval flows.

What feature would you like to see?

Please expose the effective approval reviewer for the current turn in PermissionRequest hook input, or provide an explicit hook response that defers the request back to Codex's native approval path.

Today external approval UIs can observe and answer PermissionRequest hooks, but they cannot reliably tell whether a given request is supposed to be handled by the user directly or by Codex's native auto-review path.

A minimal hook payload addition could be:

{
  "hook_event_name": "PermissionRequest",
  "permission_mode": "default",
  "approvals_reviewer": "auto_review"
}

Possible values could match the existing app-server / config enum:

user | auto_review | guardian_subagent

Alternatively, support an explicit hook output such as:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": { "behavior": "defer_to_native" }
  }
}

or defer_to_user, if that naming better matches the internal approval model.

Why this matters

External approval UIs and local observability tools need to avoid stealing approvals that Codex can already handle natively.

Right now permission_mode is not enough. In current hook input, permission_mode = "default" can represent both ordinary user approval and auto-review-backed approval. bypassPermissions is enough to identify full-access / no-approval mode, but there is no equivalent hook-level signal for auto-review.

Codex already exposes related state in other places:

• app-server ThreadStartResponse / ThreadResumeResponse include approvalsReviewer
• TurnStartParams accepts approvalsReviewer
• app-server emits item/autoApprovalReview/started and item/autoApprovalReview/completed

Those are useful, but they do not solve the hook-time routing problem for a passive external UI that receives a PermissionRequest hook from an existing CLI/Desktop conversation. The hook needs either the effective per-turn reviewer, or a first-class way to say "I observed this request; continue with the native approval flow."

Concrete use case

A desktop overlay or local approval daemon receives a PermissionRequest hook.

If the effective reviewer is user, it should show its own approval UI and return allow/deny.

If the effective reviewer is auto_review, it should not show a duplicate approval UI. It should defer immediately so Codex's native auto-review path can continue.

Without a reliable signal, external tools must choose between two bad options:

• always intercept, which can duplicate or preempt Codex Auto Review
• always defer, which loses the value of external approval UIs for normal user-reviewed requests

Suggested contract

The highest-value fix would be to add an advisory field to every PermissionRequest hook input:

{
  "approval_context": {
    "approvals_reviewer": "auto_review",
    "source": "turn"
  }
}

The source value is optional, but it would be useful to distinguish a real turn snapshot from global config defaults. The important part is that this should be the effective reviewer for the current request/turn, not only the user's global config preference.

If exposing the reviewer is not desirable, an explicit defer response would still help by giving hooks a documented no-decision path rather than relying on quiet output / implementation details.

Related issues / PRs

• #21753 tracks broader hook parity and notes that PermissionRequest still needs a complete payload contract.
• #15311 added the blocking PermissionRequest hook for external approval UIs.
• #17997 proposed external approval reviewers and included an observability/defer use case.
• #17564 explored passing guardian review context into PermissionRequest hooks.
• #21975 discusses auto-review fallback behavior, which is adjacent to the same reviewer-routing boundary.