Add PermissionRequest hooks support

[abhinav-oai]

Why

We need PermissionRequest hook support!

Also addresses:

• hooks: add permission request event for parity with claude code's auto-approve flow #16301
  • run a script on Hook to do things like play a sound to draw attention but actually no-op so user can still approve
  • can omit the decision object from output or just have the script exit 0 and print nothing
• Add blocking PermissionRequest hook for external approval UIs #15311
  • let the script approve/deny on its own
  • external UI what will run on Hook and relay decision back to codex

Reviewer Note

There's a lot of plumbing for the new hook, key files to review are:

• New hook added in codex-rs/hooks/src/events/permission_request.rs
• Wiring for network approvals codex-rs/core/src/tools/network_approval.rs
• Wiring for tool orchestrator codex-rs/core/src/tools/orchestrator.rs
• Wiring for execve codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs

What

• Wires shell, unified exec, and network approval prompts into the PermissionRequest hook flow.
• Lets hooks allow or deny approval prompts; quiet or invalid hooks fall back to the normal approval path.
• Uses tool_input.description for user-facing context when it helps:
  • shell / exec_command: the request justification, when present
  • network approvals: network-access <domain>
• Uses tool_name: Bash for shell, unified exec, and network approval permission-request hooks.
• For network approvals, passes the originating command in tool_input.command when there is a single owning call; otherwise falls back to the synthetic network-access ... command.

Example `PermissionRequest` hook input for a shell approval

{
  "session_id": "<session-id>",
  "turn_id": "<turn-id>",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/cwd",
  "hook_event_name": "PermissionRequest",
  "model": "gpt-5",
  "permission_mode": "default",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -f /tmp/example"
  }
}

Example `PermissionRequest` hook input for an escalated `exec_command` request

{
  "session_id": "<session-id>",
  "turn_id": "<turn-id>",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/cwd",
  "hook_event_name": "PermissionRequest",
  "model": "gpt-5",
  "permission_mode": "default",
  "tool_name": "Bash",
  "tool_input": {
    "command": "cp /tmp/source.json /Users/alice/export/source.json",
    "description": "Need to copy a generated file outside the workspace"
  }
}

Example `PermissionRequest` hook input for a network approval

{
  "session_id": "<session-id>",
  "turn_id": "<turn-id>",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/cwd",
  "hook_event_name": "PermissionRequest",
  "model": "gpt-5",
  "permission_mode": "default",
  "tool_name": "Bash",
  "tool_input": {
    "command": "curl http://codex-network-test.invalid",
    "description": "network-access http://codex-network-test.invalid"
  }
}

Follow-ups

• Implement the PermissionRequest semantics for updatedInput, updatedPermissions, interrupt, and suggestions / permission_suggestions
• Add PermissionRequest support for the request_permissions tool path

[abhinav-oai]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1bf5222fbb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[abhinav-oai]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7e4869308c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Treat null reserved fields as invalid in PermissionRequest

unsupported_permission_request_hook_specific_output only checks is_some() on updated_input/updated_permissions. With Serde, explicitly sending "updatedInput": null (or updatedPermissions) deserializes to None, so the hook output is accepted instead of failing closed. This contradicts the documented intent that these reserved fields are unsupported when present.

Useful? React with 👍 / 👎.

[eternal-openai]

Codex notes: "PermissionRequest universal hook controls are handled incorrectly. The Claude hooks contract applies fields like continue and stopReason across hook events, but this implementation rejects them for PermissionRequest and falls back to normal approval instead of honoring the hook’s stop behavior."

Still reading otherwise

[eternal-openai]

Looks good aside from that note above! Will approve after that's resolved

[abhinav-oai]

Looks good aside from that note above! Will approve after that's resolved

implemented but ended up backing the changes out so this PR is easier to review

continue:false is also unimplemented for the PreToolUse hook so I think it makes sense to add them in one go in a follow up

here's the current draft, need to tie in PreToolUse and clean it up #17864

[abhinav-oai]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".