How it works
Permission scope turns delegated authority into enforceable limits. A tool may expose many operations, but the agent should receive access only to the resources and actions required for the current task. The scope belongs to the credential, session, capability, or policy used by the tool connection. It should not depend on the model remembering an instruction.
A useful scope specifies several dimensions:
- Subject: which agent, run, or worker receives the authority.
- Resource: which repository, directory, account, record, queue, or service it may reach.
- Action: whether it may read, create, update, execute, approve, publish, or delete.
- Conditions: limits such as environment, time window, value threshold, branch, or workflow state.
- Delegation: whether the authority may be passed to a subagent or another tool.
At invocation time, the harness sends the request through an enforcement point. That point compares the requested operation with the active scope and either permits it or returns a visible denial. The decision and the effective scope should be recorded with the tool call.
Scope is therefore more than a tool description. A description tells the model what an operation means. Permission scope determines what the system will actually allow, even when the model misunderstands the task, follows hostile context, or constructs an invalid request.
Why it matters in an agent harness
An agent can make a locally plausible decision that is globally wrong. It may select the wrong customer record, confuse staging with production, or treat retrieved text as an instruction. Permission scope limits the consequences before evaluation or human review has a chance to catch the mistake.
The main engineering outcome is failure containment. A deployment agent with permission to update one staging service cannot accidentally alter every production service. A research worker with read-only access cannot turn a bad retrieval result into a destructive write. The model may still fail, but the failure remains inside a boundary chosen by the operator.
Scope also makes approvals meaningful. An approval gate should authorize a concrete expansion of authority, not merely acknowledge that an agent intends to continue. For example, approval might move a run from generating a proposed change to applying that exact change in one repository. It should not silently grant an unrestricted credential for the rest of the session.
Observability improves when every call records both requested and effective authority. Operators can distinguish three cases that otherwise look similar: the agent chose not to act, the harness denied the action, or the provider rejected a permitted request. That distinction matters during incident review and evaluation.
Reversibility depends on scope as well. Rollback is easier when writes are confined to known resources and mutation types. Some operations are not practically reversible, including external messages, destructive deletion, and irreversible publication. Those actions need narrower scopes, stronger preconditions, or separate approval than ordinary reads and drafts.
Permission scope does not prove that an allowed action is correct. It reduces the set of possible actions. Correctness still requires task validation, state checks, evaluation, and recovery design.
Permission scope vs least privilege
The concepts are related but answer different design questions. Permission scope describes the authority actually granted. Least privilege is the policy used to decide how narrow that authority should be.
| Question | Permission scope | Least privilege |
|---|---|---|
| Primary concern | What can this agent do now? | What is the minimum authority it needs? |
| Concrete output | Resource, action, and condition rules | A constraint on how those rules are chosen |
| Evaluation | Compare attempted calls with granted authority | Look for unnecessary authority in the grant |
| Failure signal | A call exceeds its scope | A valid scope is broader than the task requires |
A scope can be explicit and still violate least privilege. Giving a worker documented read-write access to every repository is legible, but it is not narrow. Conversely, invoking least privilege without defining enforceable scopes leaves the principle as guidance rather than a control.
The Rifty take
We treat permission scope as executable task design, not prompt wording. We optimize for small, inspectable grants that can expand at explicit checkpoints, and we accept occasional denied calls as the cost of containing mistakes. Authority that cannot be attributed to a run and revoked without disturbing unrelated work is too broad.
Implementation checks
- Bind authority to the smallest practical agent, run, task, and environment.
- Separate read, write, execute, approve, publish, and delete permissions.
- Enforce scope outside the model and reject out-of-scope calls visibly.
- Record the effective scope and denial reason with each tool invocation.
- Prevent subagents from inheriting more authority than their assigned work requires.
- Make approval expand a named scope for a named operation or bounded interval.
- Test confused-resource, wrong-environment, stale-session, and prompt-injection cases.
- Revoke temporary grants when the run ends, stops, or changes stage.
- Review irreversible actions separately from operations that have a reliable compensating action.
- Treat unexplained permission denials and unexpected successful calls as evaluation failures.
Frequently asked questions
Should permission scope be defined in the system prompt?
No. The prompt may explain the intended boundary, but the actual scope should be enforced by credentials, policy checks, sandboxes, or tool gateways outside the model. Prompt instructions guide behavior; they do not reliably prevent a mistaken or manipulated agent from attempting an unauthorized operation.
How narrow should an agent's permission scope be?
Make it narrow enough that the largest permitted mistake remains tolerable for the task. Scope by resource, action, environment, run, and duration where practical. If the agent later needs more authority, expand it through an explicit stage transition or approval rather than granting speculative access upfront.
Can approval compensate for a broad permission scope?
Only partially. Approval can control when authority becomes available, but a broad grant still creates unnecessary blast radius after approval. Prefer approving a specific operation, resource set, or temporary scope. The approval record should show exactly what changed and when the added authority expires.
What should happen when an agent exceeds its permission scope?
The enforcement point should deny the operation and return a visible, attributable error. The harness can then revise the plan, request a bounded scope expansion, or stop. It should not substitute a broader credential or silently skip the operation while reporting the task as successful.
Should subagents inherit the parent agent's permissions?
Not by default. A subagent should receive a scope derived from its own assignment, capped by the parent's authority. Delegation must never create new authority. Record the derived grant so operators can attribute each call and revoke one worker without disabling the entire run.