Permissions UX for agents: how to show and adjust what the agent can do
Permissions UX for agents defines how a person understands and adjusts what an AI agent may do: modes, rules, the scope of decisions and common design mistakes.
Why are permissions an experience, not just a setting?
A permission defines the agent’s room to act, but the person lives that room through every prompt. If the prompts are confusing, the person approves without reading. If the limits are hidden, they do not know why the agent stopped. If changes are hard, they stop adjusting and keep the setting they had on day one.
That is why permissions are an interaction design matter: what is asked, when, with what information and with which options. Technical controls, such as access rules, support that experience but do not replace it. Isolation of the environment, which limits the damage even when a permission fails, is covered in sandboxing and permissions, and the underlying question of which steps need a person is in human-in-the-loop.
What permission modes exist?
Claude Code, in its permissions documentation, offers several modes that show a typical balance between convenience and oversight. They are a reference for designing your own:
| Mode | What runs without asking | What it is for |
|---|---|---|
| Default | Reads only | Reviewing every action, sensitive work |
| Accept edits | Reads, file edits and common filesystem commands (mkdir, mv, cp) | Iterating on code you are reviewing |
| Plan | Read-only; proposes a plan without making changes | Analyzing and proposing before editing |
| Skip permissions | Almost everything | Only in isolated environments, such as containers or virtual machines |
The table teaches something important: each mode answers a different question. The person should be able to switch modes without restarting the session, and always see which one is active. In Claude Code you switch with Shift+Tab or with a command-line option at startup. The documentation adds two more modes: one that only lets through what a rule has pre-approved, and an automatic one where a classifier decides, available only if your account meets certain requirements.
Modes also have an order of risk. A “skip permissions” mode should be hard to turn on by accident, and in a shared environment it helps if an administrator can disable it. That is a design recommendation, not something every tool offers.
How is a rule presented?
Permission rules usually have three outcomes: allow, ask or deny. Their visible design matters as much as their logic:
- See the active rules. The person should be able to review what is allowed, in what scope and since when.
- Understand precedence. If one rule allows and another denies, it must be clear which one wins. In Claude Code, rules are evaluated in the order deny, ask, allow, and the first match wins: a broad deny rule blocks the call even if a more specific allow rule exists.
- Edit without code. A panel with options suits most people. A configuration file suits teams. In Claude Code, the
/permissionscommand lists the rules and the settings file each one comes from.
Claude Code’s prompts let you approve once or save the decision. According to its documentation, a permanent approval of a command is saved as a rule in .claude/settings.local.json at the repository root and applies to future sessions anywhere in that repository. File-edit approvals, by contrast, last only until the session ends. Those are two different scopes behind the same button, and the design must show which one is being chosen before the person confirms.
What scope should decisions have?
A “don’t ask again” decision is powerful and risky. Its scope is what makes it safe or not. Some useful dimensions:
- Tool type. Allowing test commands does not mean allowing network commands.
- Exact command or pattern. “Run
npm test” is narrower than “run npm”. - Project or repository. A decision in one repository should not apply in another.
- One call or the whole run. In the OpenAI Agents SDK, a normal approval covers only that one call. If you set
always_approve, the decision carries over to later calls to that tool for the rest of the run, and the approval surface also covers agents reached through a handoff. Whoever designs the prompt should make clear which of the two options the person is choosing.
The principle is simple: a decision should apply only to what the person actually saw.
How should the system fail?
A permission system should fail toward denial. If a rule cannot be evaluated, or data is missing from the action, the answer should be to ask for approval or block, not to run by default. The OpenAI SDK describes that behavior: when it cannot safely inspect the arguments of a call, the rule is not evaluated and the call requires manual approval.
The opposite case exists too: in that same documentation, approval for the local shell tool is opt-in and off by default. A good design does not let the limit depend on someone remembering to turn it on.
That same logic should reach the screen, in the form of each approval question and in the barriers that guardrails describe for what the agent must never do. A notice that says “I could not verify whether this action is allowed; approve it?” is more honest than a silent run.
Example
Illustrative example: a design team uses an agent to prepare prototypes. At first, the agent asks permission for every edit, and designers approve without looking. The team switches to “accept edits” inside the prototype folder, and keeps asking for anything outside that folder and for network commands.
The first time the agent tries to write to the shared brand folder, the prompt appears with the exact path and a sentence: “This folder is outside the project. Allow this time?”. Designers now read the prompt, because it is rare. The control is where it should be.
When should you NOT give broad permissions?
- When the agent works with personal or customer data and there is no record of actions.
- When the environment is shared and the person cannot revert other people’s changes.
- When the “skip everything” mode is used on the main work machine, with access to credentials.
In those cases, an isolated environment with narrow permissions is better than a free agent on your computer.
Common mistakes
- Hiding the current mode, so the person does not know what permissions they run with.
- Offering “always allow” without showing what it applies to.
- Asking permission for every action and ending up with automatic approvals.
- Letting a decision made in one project apply everywhere.
- Letting the system run by default when it cannot evaluate a rule.