How the gate works

Ony.ai does not add a second permission system on top of your agent. It inherits the agent’s own decision surface. The rule to keep in mind:

Ony.ai rings exactly when the agent itself would stop and ask you. It never rings for work you already pre-authorized.

Pure inheritance on Claude Code

On Claude Code, the gate rides the PermissionRequest hook, which Claude fires at the precise moment it decides to show you a permission dialog. That has one important consequence: work Claude would run without asking never reaches Ony.ai at all.

• Allowlisted commands - never fire the hook, so Ony.ai never rings for them.
• Accept-edits mode - pre-approved file edits never fire the hook.
• Bypass-permissions mode - the whole class of pre-authorized actions never fires the hook.

So installing Ony.ai’s hooks changes nothing about how Claude Code behaves on its own. The gate only engages where Claude was already going to stop and ask. What Ony.ai does at that moment depends on your mode: away answers every ask by phone, on answers only the high-risk ones, and off stands aside entirely.

The allowlist is the kill switch

Because inheritance is faithful, an allowlisted command that happens to be high-risk stays silent even in on mode - Claude never asks, so Ony.ai never rings. The phone-level kill switch is simple: do not allowlist commands you would want a phone call for.

The 5-step loop

When the agent does stop to ask, here is what happens:

1. The hook raises a handoff. It sends the tool call to the Ony.ai server and blocks, waiting for a decision.
2. The server classifies the risk. Risk is re-derived server-side from a closed taxonomy. The agent’s own risk hint is never trusted, so a mislabeled action cannot talk its way past policy.
3. Your phone rings. Ony.ai reads out the action, or the question and its options as a phone menu.
4. You decide on the keypad. Approve, deny, or pick an option. Never by voice.
5. The signed verdict returns. The hook receives it, verifies the signature, and honors it. The agent proceeds or is blocked, and the exchange is appended to the audit chain.

Every verdict is signed and bound

A decision is never trusted just because it arrived over a channel. The server signs each verdict with an HMAC over the fields that identify the exact call being decided:

{ handoff_id, session_id, tool_name, decision, risk, exp }

The hook only honors a verdict whose signature verifies against your device’s decision key and whose binding matches this exact handoff, session, and tool. This is what stops a verdict for one action from being relabeled onto a different one. There is no approval cache: every gated call creates its own handoff and verifies its own fresh, expiring verdict. A missing, invalid, or expired signature is not honored.

Every handoff and its verdict land in a tamper-evident audit chain, so the full history of what was asked and what you decided is verifiable after the fact.

Fail-closed by design

If Ony.ai cannot resolve a gate - the server is unreachable, or a verdict fails signature or expiry checks - it does not fail open into a silent approval.

• On the PermissionRequest gate, Ony.ai stands aside and leaves your own terminal dialog up as the fail-closed backstop. Nothing runs ungated; you answer the prompt you would have gotten anyway.
• On the headless and Codex pre-execution gate (below), an owed-but-unresolved gate is forced to a prompt (Claude) or a deny (Codex), never a silent run.

Notes for other surfaces

• Headless Claude (claude -p) does not fire PermissionRequest. Headless installs opt into a full pre-execution gate on the PreToolUse hook with ony hooks install --headless. Without the opt-in, headless permission-needing calls are auto-denied by Claude itself - visible and fail-closed, never ungated.
• Multiple-choice questions (AskUserQuestion) are handled on PreToolUse in away mode: Ony.ai reads each option as a phone menu, marks the recommended one, and delivers your keypad choice back as the answer.
• OpenAI Codex has no PermissionRequest surface, so its hook is a deny-only PreToolUse gate (a phone denial blocks; an approval defers to Codex). See the Codex guide.
• OpenCode is attach-based: Ony.ai answers each permission ask one decision at a time, never a standing grant. See the OpenCode guide.

Next steps

• The /ony modes - off, on, away, here, and project scope.
• Quickstart - wire it up in a couple of minutes.