Proposal: Add PermissionDecision hook observability

Summary

Add a notification-only PermissionDecision command hook that runs after every dispatched PermissionRequest is resolved.

This gives hook authors a reliable way to observe the final approval outcome without allowing the post-decision hook to change it.

Motivation

PermissionRequest runs before the final approval is known. Today, a hook can participate in resolving a request, but there is no paired event that consistently reports the final result when it is resolved by:

• the user
• automatic review
• a PermissionRequest hook
• interruption or timeout

The new event closes that observability gap.

It also clarifies why PermissionRequest.reviewer only contains user and auto_review: that field represents the effective reviewer selected before hook execution. A hook may resolve the request, but hook is a decision source rather than an effective reviewer, so it belongs in PermissionDecision.decision_source.

Proposed behavior

• Emit exactly one PermissionDecision event for every dispatched PermissionRequest.
• Emit it after the approval result is final, including abort and timed_out.
• Match handlers using the same tool name and aliases as the paired permission request.
• Treat it as notification-only: it cannot change the resolved approval.
• Honor only systemMessage from its structured output.
• Include the originating tool-use ID when one exists.

Schema enums

PermissionRequest.reviewer

• user
• auto_review

PermissionDecision.decision

• approved
• approved_for_session
• denied
• abort
• timed_out

PermissionDecision.decision_source

• user
• auto_review
• hook

PermissionDecision.permission_mode

• default
• accept_edits
• plan
• dont_ask
• delegate
• bypass_permissions

Integration surface

The implementation wires the event through:

• hook configuration and managed-hook requirements
• generated hook input/output schemas
• app-server JSON and TypeScript schemas
• approval paths for regular tools, MCP tools, network approvals, and Unix escalation
• analytics
• TUI hook diagnostics and snapshots
• integration and unit tests

Reference implementation

An implementation is available here:

• Branch: https://github.com/bob-zebedy/codex/tree/feat/permission-hooks-observability
• Commit: https://github.com/bob-zebedy/codex/commit/3a80dfa6cc

The implementation is being submitted as an issue because repository policy currently limits pull-request creation to collaborators.

Validation

• regenerated config, hooks, and app-server schemas
• relevant eight-crate nextest run: 7,868 tests passed
• reviewed and accepted the expected TUI snapshot updates
• isolated snapshot/environment-sensitive cases were rerun successfully
• just fix
• just fmt