Permission Analysis, Approval, and Monotonic Guards

Conclusion: Authorization Is Layered, and Only the Final Vetoes Are Monotonic

1. Six Concepts That Similar Product Labels Tend to Collapse

The most counterintuitive row is approval/policy = never: it means “never prompt; reject actions that require approval,” not “approve without asking.” A full-access preset works without prompts because the sandbox is already open, not because never is a grant.

2. The End-to-End Decision Graph Has Two Approval Entrances

model tool call
  → durable tool/call already exists
  → detach + freeze arguments
  → tools/pre-execute waterfall ── deny ──────────────→ error result
              │
              ├─ ask → ApprovalService → allowed-once / deny
              │
              └─ allow
                   ↓
             global + scoped monotonic guards ───────→ error result
                   ↓
             around wrappers → tool body
                                  │
                                  └─ shell (bash/pwsh) or fs sandbox_permissions
                                     → strict-wider check
                                     → ApprovalService
                                     → stamp wider mode on this call only
                                  ↓
                           effectful backend execution
                                  ↓
                         post-policy → durable result

The generic entrance asks before guards and before the body. The sandbox entrance lives inside a shell (bash/pwsh) or fs body, but still before a process starts or a mutation executes. Consequently, a generic pre listener and a tool-specific escalation request can both ask about one call; composition should avoid redundant policy. Conversely, guards can reject the frozen escalation arguments before the tool-specific prompt is reached.

3. Risk Is Proposed, Not Centrally Scored

PreToolDecision contains only allow, deny(reason), and ask(reason?). There is no built-in severity scale, numerical risk score, command classifier, or privileged “approve” token. The default end of the waterfall is allow, so deployments that want broad risk classification must compose a listener; the built-in sandbox-aware tools instead use an explicit argument pair: sandbox_permissions plus a nonblank justification.

4. Why tools/pre-execute Is Extensible Policy, Not a Non-bypassable Gate

The pre stage is an asynchronous, scope-routed waterfall. A listener can delegate to next, replace the downstream decision, or short-circuit it. Registration order and prepend therefore matter. That is useful for hooks, deployment policy, and machine reviewers, but it also means a listener-shaped “absolute deny” can be bypassed by an earlier listener that returns allow without delegating.

5. The Approval Service Is a Closed, Fail-closed Question Boundary

At the ToolRuntime seam, a missing ApprovalService and an Agent-less call also deny because there is no auditable Session and no routing identity. Only the exact allowed-once branch proceeds; rejected, cancelled, and unavailable preserve distinct messages for diagnosis. APPROVAL-ASK-MAPPING

6. The Audit Pair Is Durable, but the Live Wait Is Not

open turn
  → append approval/asked { fresh id, toolName, callId?, reason? }
  → await answerer waterfall
  → append approval/decided { same id, closed outcome }
  → return outcome

An approval request is accepted only inside an open turn, because the turn is the Session log's commit/replay boundary. The request deliberately omits arguments: callId links it to the already-recorded and already-presented tool call, avoiding two copies that could drift. Both audit events are log-only rather than model transcript blocks. The model learns standing policy from runtime context and receives the final tool result. APPROVAL-AUDIT-EVENTSAPPROVAL-REQUEST-SHAPEAPPROVAL-AUDIT-REQUEST

7. Cancellation Has Explicit Race Semantics

If the request signal is already aborted, approval resolves cancelled before answerer dispatch. Otherwise the service races the answerer against the signal; cancellation settles immediately and any later answer becomes a no-op. The answerer computation is contained, not forcibly killed.

Tool preparation checks caller cancellation before policy, after approval, and again before dispatch. If cancellation is what cancelled the approval, the result is ABORTED_BEFORE_DISPATCH; a completed policy denial may remain the more informative result. Once a same-process tool body starts, ToolRuntime waits for it to reach quiescence and then converts an otherwise successful outcome to aborted. Tool authors must propagate the signal to subprocesses or providers. APPROVAL-CANCEL-DISPATCH

8. Presets Are Durable Standing Intent Over Two Independent Knobs

A preset table entry contains a machine key, sandbox mode, approval policy, and optional presentation text. custom is reserved for the derived state in which the two effective knobs match no entry; it cannot be configured or selected. The service fails at load when the shell does not advertise confinement, the default does not resolve, or the composed defaults match no preset without an explicit default. APPROVAL-PRESET-CONFIG

Current value is derived from actual knob state. A still-matching recorded selection wins when two names share a bundle; otherwise the first matching table row wins, then custom. Selecting a preset appends intent first and only writes knobs whose effective values change. APPROVAL-PRESET-DERIVEAPPROVAL-PRESET-WRITE

9. “Default for Future Sessions” and “Current Session” Are Separate Mutations

A genuinely fresh Session reads the latest user setting and pins all three permission facts during synchronous session/created publication. This occurs before creation returns, Agent publication, and the first prompt, but not before SessionStore insertion. A seeded, resumed, or partially initialized Session preserves its effective permission and receives only missing facts. Later settings changes therefore affect future Sessions, not existing ones. APPROVAL-PRESET-PIN

The optional permissions projection exposes table options plus the effective current value; absence of the projection key means the capability was not composed, so clients hide the control. The bare /permission command reports current and available values; /permission <key> validates the key and uses the same service write path as the UI. APPROVAL-PRESET-PROJECTION

10. A Per-call Sandbox Grant Is Strictly Wider, Explicit, and Ephemeral

The schema advertises the closed target vocabulary, but runtime checks strict widening against this call's effective standing mode. Both escalation fields must occur together and the justification must be nonblank. A same-level or narrowing request fails before prompting. APPROVAL-ESCALATION-LADDER

The resolver then requires an ApprovalService and Agent, records the target and justification in the reason, and accepts only allowed-once. The returned mode is a local value for one call; it never appends sandbox/mode or changes the preset. APPROVAL-ESCALATION-FLOW

11. Shell and Filesystem Share Choreography, Then Enforce Through Different Backends

Bash and PowerShell both validate arguments, resolve standing policy, await escalation approval when requested, stamp the returned mode onto the request, and only then start a foreground process or commit a background-job starter. Unadvertised escalation keys are still rejected when the mounted executor cannot sandbox, because the object schema is open and presentation alone is not enforcement. APPROVAL-BASH-EXECUTIONAPPROVAL-PWSH-EXECUTION

Filesystem mutation tools use a shared controller that performs the same pairing, standing-policy resolution, approval, and one-call stamp. A provider sandbox denial is converted to a structured error marker plus an exact-retry hint; other provider errors pass through. APPROVAL-FS-ESCALATION

12. Delegated Children Do Not Inherit a Parent's One-shot Grant

At child creation, the runtime synchronously captures only the parent's explicit Session sandbox override—never the deployment default and never a per-call grant—and pins the child's approval policy to never whenever approval exists. Those delegation-sourced events are appended after any fork seed, so stale seed state cannot reopen the child. The child also receives model-facing text saying that approval-requiring operations are rejected. APPROVAL-CHILD-PIN

13. Web Approval Is a Stable Server Request, Not a New Unary RPC

The host emits approval/requested with a stable rpcId, Session id, approval id, tool name, optional call id, and reason. A client response echoes the same rpcId and may supply only allowed-once or rejected; cancellation and unavailability remain host-owned outcomes. APPROVAL-WIRE-CONTRACT

The proxy answerer claims the newest matching, undecided, unclaimed approval/asked event. If it cannot find that audit fact, it delegates instead of inventing an answerable request. Pending entries survive browser disconnects; opening a new mux replays them with the same id. Abort and proxy teardown settle them cancelled. APPROVAL-WEB-REGISTRYAPPROVAL-WEB-REPLAY

Responses are routed by rpcId, parsed, and required to echo the exact Session and approval ids. The first valid response removes the pending entry; malformed, foreign, stale, and late responses are rejected. APPROVAL-WEB-RESPOND

14. The Approval Panel Is One-shot, but Its Evidence Is Not Self-contained

While a request is pending, the conversation UI replaces the composer with a scrollable card containing the reason, optional command, Refuse, and Allow once. Buttons latch after the first click, re-arm on transport failure, and disappear when the resolved frame arrives. The command is parsed only for a root running tool call whose JSON arguments contain a string command; malformed, nested, unpaired, and non-shell calls show no command line. APPROVAL-UI-PANEL

15. Permission Selectors Are Convenience and Acknowledgement, Not the Enforcement Boundary

The current-Session selector filters out custom and submits /permission <key>. The optional command popup does the same. The Settings row writes defaultPreset with an expected revision for future Sessions. APPROVAL-PERMISSION-SETTINGS-WRITE All three consume server-advertised options, but their risk dialog is triggered by one hard-coded machine key: danger-full-access. APPROVAL-PERMISSION-COMPOSERAPPROVAL-PERMISSION-DECORATIONAPPROVAL-PERMISSION-SETTINGS

16. Browser Request Trust Defends Origin Confusion; It Is Explicitly Not Authentication

Every /api request must pass Host validation, explicit cross-site Fetch Metadata rejection, and same-authority Origin validation when Origin exists. This blocks DNS rebinding and ordinary malicious-page cross-site requests. The source explicitly leaves network reachability and authentication out of scope. APPROVAL-WEB-TRUST

17. ACP Is a Machine Answerer with Exact Ownership and One-shot Choices

The ACP bridge claims an approval only when it owns the exact Agent and the request has a call id. It presents two choices—allow once and reject once—and maps cancellation explicitly; every unknown non-allow option becomes rejection. It never converts a response into a durable grant. APPROVAL-ACP-ANSWERER

This illustrates the intended answerer architecture: web UI, ACP, or another provider can occupy the same waterfall seam, while the ApprovalService owns vocabulary, durable audit, cancellation, and the unbypassable never policy.

18. Tests Encode the Negative Paths, Not Just the Happy Prompt

APPROVAL-TOOLS-TESTSAPPROVAL-GUARD-TESTSAPPROVAL-SERVICE-TESTSAPPROVAL-PRESET-TESTSAPPROVAL-ESCALATION-TESTSAPPROVAL-WEB-TESTS

19. Two README Statements Have Drifted Behind Production Source

APPROVAL-DOC-PRESET-DRIFTAPPROVAL-DOC-API-DRIFT

20. Narrow Comparison with Codex: Similar Separation, Different Policy Richness

This comparison uses only OpenAI's public Agent approvals & security and Subagents documentation, retrieved on 2026-08-13. The DeepSeek side is source-level at the pinned commit; the Codex side is documentation-level and current to that retrieval date. No claim is made about private services or undocumented implementation.

21. Design Assessment, Hardening Priorities, and Verification Status