# Permissions and trust

> What a run may do, who decides, what each built-in tool needs, the Rule of Two, and what a trusted source changes

A run can do only what three things allow together: the **agent** it runs as, the agent's
**role**, and the **loop**. This page says how they combine, what each built-in tool needs, why
plutonium.io refuses some combinations (the **Rule of Two**), and what marking a source
**trusted** changes. It describes the rules as they work today. A rule that is still coming is
labelled **Coming**.

## The Permissions screen

**Permissions**, in the console's Account group, shows what your account's published loops and
pages may do:

- **Your loops**: each published loop that is not archived, with each permission its record holds,
  in the words its approval card used, and who reaches it (visitors through the chat on your
  sites, or a server of yours with an API key). A permission the loop may widen during a run says
  that it asks before reaching further, and who answers. **Change it on its loop** opens the loop.
- **Your pages**: each published page, with who can open it and who can change its rows.
  **Change it on its page** opens the page. The screen reads the first 12 pages in full; for any
  page after those it shows who can open it, and the page itself shows who can change it.
- **Reactor's own loops**: the loops Reactor runs in your account, such as its assistants, with
  the permissions each one holds. They are Reactor's, so you cannot change them.

A draft, an unpublished page and an archived loop may do nothing, so the screen does not list
them. The services
Reactor can reach as you are on **Connections**.

## Permissions

A **permission** (a *capability* in a loop's record) is one kind of thing a run may do.
plutonium.io defines the list, and it is closed: a loop, a model or a tool cannot add one. The
console names each one in words; a loop's record names it by the word in the first column.

Each permission also carries up to three **marks**, which the Rule of Two below adds up:

- **Outside content** — it can bring text that plutonium.io did not write into the model's
  context: a web page, a search result, what a stranger types.
- **Your data** — it can read or change your account's data or secrets.
- **Acts outside** — it can cause an effect outside Reactor that the person did not ask for
  turn by turn. Sending you a notification is not this; sending mail to somebody else is.

| Permission | What it lets a run do | Marks |
| --- | --- | --- |
| `read_web` | Read any page on the web | Outside content |
| `call_endpoint` | Call the addresses of your own tools | Outside content |
| `read_workspace` | Read your files | Outside content, Your data |
| `write_workspace` | Write to your files | Your data |
| `read_records` | Read your collections | Outside content, Your data |
| `write_records` | Write to your collections | Your data |
| `search_indexes` | Search your indexes and read their documents | Outside content, Your data |
| `notify` | Send the person a notification | — |
| `install_automations` | Install an automation that runs on its own | Your data |
| `install_loops` | Install a loop | Your data |
| `install_tools` | Install a tool your loops can call | Your data |
| `install_agents` | Install an agent your loops can run as | Your data |
| `install_pages` | Draft a page your members can read | Your data |
| `read_connection` | Read from a service you have connected | Outside content, Your data |
| `write_connection` | Change things in a service you have connected | Your data, Acts outside |
| `send_external` | Send things outside Reactor | Acts outside |
| `serve_records` | Serve your collections to an outside caller with an API key | Your data, Acts outside |
| `spawn_tasks` | Start further runs | — |
| `run_code` | Run code | Acts outside |
| `read_own_results` | Read back results it already received | Outside content |
| `rehearse_claim` | Try an automation once on the live site, saving nothing | Outside content |
| `client_navigate` | Open a page of your app for the person it talks to | Outside content |
| `client_act` | Act in your app as the person it talks to, once they confirm each use | Outside content, Acts outside |
| `host_read` | Read from your own machine, where you run rxr and allow it | Outside content |
| `host_act` | Run a command or write a file on your own machine, where you run rxr and allow it | Outside content, Acts outside |

The install permissions carry no **Acts outside** mark because every install tool asks a person
first, each time (see the table of tools below).

## Three layers decide what a run may call

1. **The agent's tools.** An agent lists the tools it knows how to use. A tool that is not on the
   list is not something a run can call at all.
2. **The role's permissions.** An agent has a default **role**, a named set of permissions —
   one that plutonium.io defines, or one an owner of your account defines from the permissions
   above ([Agents](/docs/guide/agents.md) lists the platform's and says how to define your own).
   **The role is the outer bound, in every run:** a tool runs only when the role holds every
   permission the tool needs, and neither a loop nor a card can add one the role does not allow.
   A tool that needs one is left out of the run, and a call to it is refused in words that name
   the role and the permission — to give an agent more, change its role on the Agents page.
   **Six permissions are the loop's, not a role's:** `spawn_tasks`, `client_navigate`,
   `client_act`, `call_endpoint`, `host_read` and `host_act` name something only a loop has — its
   other agents, the page that hosts it, its own endpoint tools, the machine its host tools
   name — so no role holds them, the loop's `capabilities` give
   them to its runs, and a run outside a loop never holds them. **In your own run on the
   console**, a card asks you only what the role leaves to you: which site, when a role allows
   reading the web a host at a time, and which connection, when it allows using one. While a
   card waits, the run's activity line for it quotes what the agent said it was about to do, in
   its own words; the card itself states only what the platform computed. A published loop keeps
   the role as it was when you published.
   **A role's limits travel with it into a loop's run.** A role can hold a permission only within
   limits — `web_reader` reads two job sites and writes files under `docs/` only. A grant in a
   loop's run gives back no more than those limits, and a `grantable` entry that names wider ones
   is narrowed to them. A path outside a write limit is refused and nobody is asked. A site outside
   the role's list is refused too, unless the loop's `grantable` declares a `widen` for that
   permission: then the person that entry names is asked about that one site. A role whose list
   is EMPTY (the `general` agent reads no site until someone allows one) can read nothing in a
   loop without that `widen`, so saving or publishing such a loop is refused, naming the entry to
   add: `grantable: [{capability: read_web, kind: widen, approve: user}]`, or `read_web` taken out
   of the loop's `capabilities`.
3. **The loop's `capabilities`.** A loop's record lists the permissions its runs may hold — the
   **ceiling**. A loop only narrows the role: a run holds what the role allows **and** the
   ceiling lists (plus the four loop permissions above, when the ceiling lists them). A run never
   holds a permission outside the ceiling, whatever the role grants, and a tool that needs one is
   left out of the run — unless the loop's `grantable` lets the run ask for that permission
   (below), which it can only when the agent's role allows it.

**An example.** The `librarian` role holds `write_records`, and `records_put` needs
`write_records`. A loop whose `capabilities` lists `read_records` but not `write_records`, and
whose `grantable` does not name it, runs a librarian agent without `records_put`: the role allows
it, the ceiling does not, so the run cannot write a record and nothing offers to.

When a run calls a tool anyway, the refusal tells the model which layer stopped it:

- **Not one of this agent's tools** — no grant can add a tool to an agent, so the model does
  something else.
- **Not allowed by this agent's role, or held back by the loop** — the refusal says which, and
  names the permission. No grant can change it inside the run: the owner changes the agent's
  role on the Agents page, or the loop's `capabilities`.
- **Needs a permission this run does not hold** — only a person can grant one. In a loop's run
  this is a permission the role allows and the loop's `capabilities` hold back, or one of the
  four loop permissions (inside the `capabilities`, the published version grants that one at the
  call). If the loop's
  `grantable` names that permission, the run asks: a card asks the person in the conversation
  (`approve: user`), parks for you on **All runs** (`approve: operator`), or waits for your callback
  (`approve: external`). If the loop's `grantable` does not name it, nobody is asked. An entry
  in `grantable` grants nothing until somebody says yes, and publish refuses an entry that no
  agent of the loop could use, or that no agent's role allows.

## What each built-in tool needs

A loop's own tools say what they need in their `requires`
([Tools](/docs/guide/tools.md)). These are the built-in tools. A tool marked **asks first** always
asks a person before each call, even when the run holds what it needs.

| Tool | Needs | Asks first |
| --- | --- | --- |
| `ask_user` | `notify` | |
| `request_inputs` | `notify` | |
| `notify_user` | `notify` | |
| `escalate` | `notify` | |
| `finish` | nothing | |
| `read_file` | `read_workspace` | |
| `list_dir` | `read_workspace` | |
| `write_file` | `write_workspace` | |
| `records_query` | `read_records` | |
| `records_put` | `write_records` | |
| `search` | `search_indexes` | |
| `read_document` | `search_indexes` | |
| `read_result` | `read_own_results` | |
| `web_fetch` | `read_web` | |
| `web_fetch_source` | `read_web` | |
| `web_extract` | `read_web` | |
| `rehearse_claim` | `rehearse_claim`, `read_web` | |
| `github_search_issues` | `read_connection` | |
| `gmail_list_messages` | `read_connection` | |
| `calendar_list_events` | `read_connection` | |
| `spawn_tasks` | `spawn_tasks` | |
| `read_collection` | `install_loops` | |
| `read_loop` | `install_loops` | |
| `read_page` | `install_pages` | |
| `read_tool` | `install_tools` | |
| `propose_loop` | `install_loops` | asks first |
| `propose_tool` | `install_tools` | asks first |
| `propose_agent` | `install_agents` | asks first |
| `propose_page` | `install_pages` | asks first |
| `propose_collection` | `install_pages` | asks first |
| `publish_loop` | `install_loops` | asks first |
| `publish_page` | `install_pages` | asks first |
| `propose_claim` | `install_automations` | asks first |

`escalate` and `finish` are on no role's list: plutonium.io offers them to a run itself.
`finish` needs nothing, because ending a run sends nothing: every run with a person in the
conversation holds it, whatever the loop's capabilities. No
built-in tool needs `call_endpoint`, `write_connection`, `run_code`, `serve_records`,
`client_navigate`, `client_act`, `host_read` or `host_act`; only a loop's own tools reach those.

## The Rule of Two

**No agent may hold all three marks at once.** An agent that reads outside content, touches your
data and can act outside is one that a web page or a stranger's message can steer into doing
something with your data that you never asked for. Any two of the marks are allowed; all three
are not.

plutonium.io adds up the marks of everything an agent can hold — its role's permissions, the
loop's own tools, and anything the loop lets it ask for. A loop that declares any `delivery` (the
embed, the SDK, the API) is **public**: what its users type is outside content too, so every agent
of such a loop already carries that mark.

Where the rule applies:

- **Publish refuses** a version in which one agent could hold all three, and names the agent, the
  tool and the marks: for example, *"tool `send_report` takes agent `analyst` to all three trust
  properties …"*. A `grantable` entry that could only be answered by breaking the rule is refused
  too, because nobody could ever say yes to it.
- **In a loop's run, the ask is refused before anybody sees a card.** The model is told that an
  action with external effects belongs to a separate agent that reads nothing.
- **In a person's own run on the console**, the card that asks for a permission warns and names
  which permission brings which mark; the person may still approve it. **Once that run holds all
  three, every action with an outside effect waits for you** on a card that shows what it will
  send, before it runs. No card asks when you turned on yolo, or when the loop's published
  version answers its permissions itself. A visitor's run never gets this card: there the ask is
  refused, as above.
- **Approving an automation warns** in the same words and does not refuse.

The two usual fixes:

1. **Split the work across two agents.** One agent reads and decides; a second agent, which reads
   nothing, sends, given what it needs as arguments. The `outbound_writer` role (`send_external`
   and `notify`) exists for that second agent.
2. **Narrow the role or the loop.** Remove the permission that brings the third mark from the
   loop's `capabilities`, or from a tool's `requires`.

## Trusted and untrusted

Some things a run reads can be marked **trusted** — content you vouch for. Untrusted is always the
default.

- **A loop's sources** (`sources[].trusted`). A file you upload is stored with that mark. When a
  run reads it, `read_file` reports the mark, and a file with no mark counts as untrusted. The
  model's instructions label each source *trusted* or *untrusted* and tell it to treat an
  untrusted source as data, never as instructions.
- **A tool's answers** (`output.trusted` on a loop's own tool). An untrusted answer is read first
  by a separate model that has no tools, and only what that reader extracts reaches the run's
  model. A trusted answer reaches the model directly. A client tool's answer is never trusted, and
  a version that LoopAssistant proposes cannot make a tool's answers trusted: only you can.
- **An index** (off by default). An **owner** of the account marks it on the index's page:
  press **Mark trusted…**, read what the mark changes, and confirm. A member sees the mark and
  cannot change it, and the account's audit log records each change with its old and new value.
  A search result from an index that is not trusted is marked untrusted.
- **The run journal** ends each untrusted answer's line with *[untrusted]*.

**What the index marks change in the Rule of Two.** Searching an index adds *outside content*
unless the index is trusted, and adds *your data* unless it is public. A site crawl is public,
because the crawl sends no login; uploaded files and a collection's records never are. So searching
a trusted crawl adds neither mark. The loop's publish review names each index's marks and what a
search of it adds. Publish checks the marks as they are and the version keeps them: marking an
index trusted counts from the loop's next publish, and marking it untrusted counts at once. See
[What an index lets a loop do](/docs/guide/search-indexes.md#what-an-index-lets-a-loop-do).

**What the trusted mark does not change yet.** `read_workspace` and `read_records` always count as
*outside content* and *your data*, whatever their sources say.

## Connections

A **connection** lets plutonium.io reach another service as you, and it is not a permission: a run
may use that reach only with a grant that names it. Connections have their own page, **Connections**
in the console: see [Connections](/docs/guide/connections.md).
