Agent permissions

Also known as: tool permissions

On this page 8

Agent permissions are the rules that determine which tools, data sources and actions an AI agent may use, under what conditions, and when a person must approve a step first. In AI agents, permissions, often called tool permissions, form the control layer between a language model that proposes actions and the systems that execute them.

Because an agent decides its own next step at run time, the model itself cannot be trusted to stay within bounds. Permissions are therefore enforced outside the model, in the agent harness, the tool layer or the operating environment, and they turn an open-ended capability into a bounded, auditable one.

How agent permissions are enforced

Agent permissions work by intercepting every tool call before it runs. The model emits a structured request, such as a file write or an API call, and a policy engine in the harness compares it with the configured rules. The request is then allowed, denied, or paused for human-in-the-loop approval.

Enforcement happens at several layers at once. The tool schema limits what a call can express, the harness applies allow and deny rules, the agent sandbox restricts the file system and network, and the downstream service checks the credentials the agent presents. This defense in depth means a single misconfigured layer does not expose everything.

LayerMechanismWhat it prevents
Tool exposureOnly listed tools reach the modelCalls to capabilities never granted
Policy rulesAllow, ask and deny patternsUnapproved commands or arguments
SandboxContainer, file and network isolationEffects outside the workspace
CredentialsScoped tokens and service accountsAccess beyond the assigned role
Audit logRecorded calls and decisionsUntraceable or deniable actions
Enforcement layers and what each one controls

Permission scopes and granularity

Permissions can be defined at very different levels of granularity, from an entire tool down to a single argument value. Coarse rules such as allowing a whole shell are easy to configure but grant far more than a task needs. Fine-grained rules, such as allowing only read commands inside one directory, follow the principle of least privilege at the cost of more configuration.

Scopes also differ in duration and reach. A grant may apply to one call, one session, one project or every session of a user, and broad long-lived grants are the most common source of unintended access.

DimensionNarrow settingBroad setting
ToolOne named functionAny tool on a server
ArgumentsSpecific path or command prefixAny argument
ResourceOne repository or mailbox folderAll accessible data
DurationSingle callPersistent across sessions
NetworkAllow-listed domains onlyUnrestricted internet access
Typical scope dimensions

Permission modes and autonomy levels

Most agent frameworks offer permission modes that set the default answer for actions not covered by a specific rule. These modes map closely to levels of agent autonomy: the more actions run without asking, the more the agent behaves as a background or long-running agent rather than an assistant under direct supervision.

Choosing a mode is a trade-off between safety and throughput. Frequent prompts protect the user but cause approval fatigue, where people click through requests without reading them, which erodes the protection that prompts were meant to give.

ModeDefault behaviorSuitable for
Read-onlyOnly observation tools allowedAnalysis, research and planning
Ask every timeEach side effect needs approvalUnfamiliar tasks and sensitive systems
Accept editsWorkspace edits allowed, commands askSupervised coding work
Allow-listed autonomyPre-approved actions run freelyRepetitive, well-understood workflows
Fully autonomousAll actions run inside a sandboxIsolated, disposable environments
Common permission modes

Agent permissions overlap with, but are not identical to, access control for the agent identity. Identity and access management decides what a service account may do in a target system, while agent permissions decide what the agent may attempt in the first place. Both are needed, because an agent acting with a user’s credentials inherits all of that user’s rights unless the harness narrows them.

Guardrails on model output and content filters are also different: they inspect text for policy violations, whereas permissions govern actions with side effects. Sandboxing limits blast radius after a call is allowed, and permissions decide whether the call is allowed at all.

Designing a permission policy

A sound policy starts from deny by default and adds explicit grants for what a task needs. Teams usually classify actions by their reversibility and impact: reading is low risk, editing local files is recoverable, while sending messages, deleting data, spending money or deploying code are irreversible or externally visible and warrant approval.

  • Separate read from write tools so observation never implies modification.
  • Scope credentials per task instead of reusing a personal administrator token.
  • Require approval for irreversible actions such as deletion, payment or publication.
  • Log every decision with the call, arguments, rule and approver.
  • Review grants regularly and expire those no longer needed.

Policies for multi-agent systems need extra care, because a subagent or agent handoff can otherwise pass on broader rights than the receiving agent requires. Each agent should receive its own minimal scope, not the union of its parent’s permissions.

Risks and common failure modes

The most serious threat is prompt injection, in which instructions hidden in a web page, file or email persuade the agent to call a tool the user never intended. Permissions cannot stop the model from being misled, but they limit what a misled agent can do, which is why they remain effective even when the model fails.

Failure modeExampleMitigation
Over-broad grantWildcard shell accessRestrict to command prefixes
Data exfiltrationUploading secrets to an outside URLNetwork allow-list and egress rules
Confused deputyAgent uses user rights for injected goalPer-task scoped credentials
Approval fatigueUser approves without readingFewer, clearer, risk-ranked prompts
Rule bypassEquivalent command not matched by ruleSandbox as a second barrier
Failure modes and mitigations

Stripped to the essentials

An AI agent is software that can take actions on its own, such as editing files or sending emails. Agent permissions are the house rules for that software. They say what it may do freely, what it must ask about first, and what it may never do.

Think of a new employee with a key card that opens only certain doors. The card does not depend on the employee always making good choices. In the same way, permissions keep an agent safe even when it makes a mistake.

Where it is applied

A software company lets a coding agent fix failing tests in its main repository. The team configures it to read and edit files only inside the project folder, run the test command and version control status freely, and ask before any network request, package installation or push to the shared server. Deleting branches and changing deployment settings are denied outright.

During one task the agent reads a dependency file containing a hidden instruction to upload environment variables to an outside address. The harness blocks the request because the domain is not on the allow-list, and the attempt appears in the audit log. The agent still completes the test fix, and a developer reviews a small, contained change before merging it.