Clarify sandbox permission override helper semantics

[charley-oai]

Summary

Today SandboxPermissions::requires_additional_permissions() does not actually mean "is WithAdditionalPermissions". It returns true for any non-default sandbox override, including RequireEscalated. That broad behavior is relied on in multiple main callsites.

The naming is security-sensitive because SandboxPermissions is used on shell-like tool calls to tell the executor how a single command should relate to the turn sandbox:

• UseDefault: run with the turn sandbox unchanged
• RequireEscalated: request execution outside the sandbox
• WithAdditionalPermissions: stay sandboxed but widen permissions for that command only

Problem

The old helper name reads as if it only applies to the WithAdditionalPermissions variant. In practice it means "this command requested any explicit sandbox override."

That ambiguity made it easy to read production checks incorrectly and made the guardian change look like a standalone main fix when it is not.

On main today:

• shell and unified_exec intentionally reject any explicit sandbox_permissions request unless approval policy is OnRequest
• exec_policy intentionally treats any explicit sandbox override as prompt-worthy in restricted sandboxes
• tests intentionally serialize both RequireEscalated and WithAdditionalPermissions as explicit sandbox override requests

So changing those callsites from the broad helper to a narrow WithAdditionalPermissions check would be a behavior change, not a pure cleanup.

What This PR Does

• documents SandboxPermissions as a per-command sandbox override, not a generic permissions bag
• adds requests_sandbox_override() for the broad meaning: anything except UseDefault
• adds uses_additional_permissions() for the narrow meaning: only WithAdditionalPermissions
• keeps requires_additional_permissions() as a compatibility alias to the broad meaning for now
• updates the current broad callsites to use the accurately named broad helper
• adds unit coverage that locks in the semantics of all three helpers

What This PR Does Not Do

This PR does not change runtime behavior. That is intentional.

[charley-oai]

@codex review this

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep them coming!

ℹ️ 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".

[charley-oai]

@codex review this

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bd55d3c640

ℹ️ 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".

[dylan-hurd-oai]

naming is hard - good suggestion!