# Agent permission model

What an agent's token can and cannot do, what needs a person, what is recorded and what can be undone, covering merging, purging, branch rules and the audit log.

An agent on Sailfork is a token acting as the account that owns it. It has no powers of its own. It can do what that account's access level allows, narrowed by the token's scopes, repositories, branches and paths, narrowed again by the organization's agent controls, with the same branch and merge rules as a person. This page answers the questions a security review asks first, then lists every control.

## The short answers

### Do token scopes limit purge and merge?

Yes, each by a scope of its own. `repo:merge` is needed to merge a pull request, turn on auto-merge, queue it or merge a stack. `repo:purge` (with `repo:admin`) is needed to ask for a repository purge. No other scope includes either one: `repo:admin` does not purge, and `repo:write` does not merge. A token without the scope gets 403 `insufficient_scope`.

An assistant connected through MCP never gets `repo:purge`, `repo:admin` or `org:admin`. At the consent step the person chooses read only or read and write, and with write three more choices, each off until chosen: run code in sandboxes, merge pull requests and publish sandbox previews. An app's installation token never carries `repo:purge` or `sandbox:expose`.

One exception to know about: a token made before `repo:merge`, `repo:purge` and `sandbox:expose` existed was given each of them if it could already do that. Check old tokens under Settings, Keys and tokens.

### Is a person required to approve before an agent merges?

In an organization's repositories, yes by default. Under Agents in the organization's Security settings, Hold merges for a person is on. A token's merge, auto-merge or stack merge then answers 202 `HELD FOR A PERSON` and changes nothing until a person approves it in the browser. The answer carries the request's id, so the agent can wait for the decision with `sailfork wait held <id>` (MCP: `wait` with `kind: "held"`) and then repeat the merge. An approval covers one request for that exact head commit and lasts 24 hours. See [Held merges and previews](#held-merges-and-previews).

Three limits on that answer:

- An owner can turn the switch off, and it is per organization. A personal repository has no such setting, so there a token with `repo:merge` merges at once, as long as the merge rules allow it.
- Browser sessions are never held, and neither is a workflow's `GITHUB_TOKEN`.
- Separately from this hold, the merge rules still decide whether a pull request can merge at all. See [Branch protection and merge rules](#branch-protection-and-merge-rules).

### Do branch protections apply to agents?

Yes. Branch rules are checked on every push over HTTPS and SSH, every branch delete and every merge, by whatever credential makes it, and a caisson's writes meet the same branch protection as a push. Merge rules (approvals from people, resolved threads, required checks, the merge queue) decide every merge, an agent's included. Two things differ for a token:

- An admin skips only the **Pull requests only** rule, and a token acts as its owner, so an admin's token can push to a branch with that rule. The other rules still bind it, and so do the token's own branch limits. Give an agent token `branches` globs, or `agent: true`, to keep it off protected branches.
- Merging past the merge queue or the code owners' approval takes a reason from a repository admin. A token cannot give one: the API answers 403 `bypass_needs_person`.

### Is the audit log immutable?

It is append-only in the application, not tamper-evident. No route and no code path edits an audit row, and none deletes one except retention: an organization's or account's audit log is deleted after 730 days, the tool-call record after 180 days, unless a legal hold covers the row. Rows also go when the organization or account that owns the log is deleted. There is no signature or hash chain on the rows, and a person with direct access to the database could change them. Streaming the log to your own tools is not available yet, so export it on a schedule if you need a copy kept elsewhere. See [What is recorded](#what-is-recorded).

### Can a purge be undone?

It depends on who asks. A purge asked for with an access token deletes nothing: the repository stays scheduled for deletion, hidden from readers, and the date moves to at least 30 days away, so a person can restore it. A purge from a browser session deletes at once and cannot be undone. Scheduling a repository for deletion, which a token can do with `repo:admin`, keeps everything for 14 days. See [Undo, purge and deletion](#undo-purge-and-deletion).

## What an agent token is

| Credential | Made by | Reaches | Lasts |
| --- | --- | --- | --- |
| Personal access token | You, in Settings or with `sailfork token create` | What its scopes, repositories, branches and paths allow, in every organization you belong to | Until its expiry. The form sets one; the CLI sets none unless you pass `--expires`. |
| CLI login | `sailfork auth login`, named `CLI on <hostname>` | Every scope unless you passed `--scopes` | 90 days |
| MCP connection (OAuth) | The person approving the assistant | Read, and with write the scopes the person chose, on the MCP endpoint only, for the repositories chosen | An access token lasts an hour and its refresh token 30 days |
| Installation token | An app, from its client secret | One installation's repositories, with the permissions the installation was granted | An hour |
| `GITHUB_TOKEN` | A CI job | Its own repository, within the job's `permissions:` | Until the job ends |
| Sandbox token | A sandbox created with `token: "inherit"`, or a test run that asks for it | The sandbox's repository only, with the creating token's `repo:read` and `repo:write`, branches and paths. Never `sandbox`, `repo:merge`, `repo:admin` or `org:admin` | Until the sandbox ends or expires, and no later than the creating token |

An app's installation token only moves refs when the installation has `contents: write`, whatever its other permissions.

### Identity is a label, not authentication

The CLI and the MCP server name the agent tool in `X-Sailfork-Agent`, an id for the run in `X-Sailfork-Session` and the route in `X-Sailfork-Surface`. The server uses them to label pull requests, comments, commits and the record of tool calls. Nothing is decided by them: a caller can send any name, so no limit keys on it. Every limit keys on the token. An installation token always speaks as its app. Turning off Track agent work in Settings makes your tokens read as you in labels, and changes no limit.

## Limits on one token

| Limit | How to set it | What it does |
| --- | --- | --- |
| Scopes | `--scopes`, or the checkboxes | A scope only removes abilities. `repo:read`, `repo:write`, `repo:merge`, `repo:admin`, `repo:purge`, `org:read`, `org:admin`, `sandbox`, `sandbox:expose` and `user`. See [Access tokens](https://sailfork.com/docs/tokens#scopes). |
| Repositories | `--repos owner/name`, or `repos` in the API | Every other repository answers 403, and so do account routes. You must be able to read each one. |
| Branches | `branches` globs in the API, or `agent: true` for `agent/**` | The only refs the token may move, by push, web edit, merge, branch delete and caisson. Tags count as refs. Reads are unaffected, and a branch-limited token cannot make tokens. |
| Paths | `paths` globs in the API | The token can only `git push`, and a push is refused when any new commit changes a file outside them. |
| Read only | Scopes without `repo:write`, the read-only MCP address or `--read-only`, or the organization's Read only | Reads work and writes are refused. |
| Expiry | `--expires`, the form's choice | The API answers 401 after it. A token can only make tokens that expire no later than itself. |
| Refusal by age | The organization's Oldest token accepted | See [Organization controls](#organization-controls-for-agents). |

A token never goes beyond its owner. If you lose write access to a repository, so does every token of yours.

## Organization controls for agents

An owner sets these under Agents in the organization's Security settings, in the browser. A token cannot change them, whatever its scopes (`PATCH /api/orgs/{org}/agent-policy`). The server checks them on every token request that names the organization, its repositories, caissons or sandboxes, so a change applies from the next request. They do not affect browser sessions or a workflow's `GITHUB_TOKEN`. The change limits apply to every caisson write made with an access token in an organization's repositories. They do not apply to browser sessions, git pushes or personal repositories. Every change is written to the organization's audit log.

| Control | API field | Effect |
| --- | --- | --- |
| Access tokens: read and write, read only, stopped | `access` | Read only refuses every write, push, caisson edit and sandbox command by a token. Stopped refuses every token request that names the organization. Both answer 403 with the code `agent_policy`. |
| Oldest token accepted | `maxTokenDays` (1 to 365, or `null`) | A token made more than that many days ago is refused in this organization, whatever its own expiry. An MCP connection counts from the day it was connected. |
| Hold merges for a person | `holdMerges` (default `true`) | A token's merge, auto-merge and stack merge wait for a person. |
| Keep an approval when the head moves | `mergeApprovalFollowsPull` (default `false`) | Off, an approval covers only the head the person saw, so a rebase after a conflict asks again. On, an approved merge counts for any later head of the same pull request for 24 hours, so new commits merge without a second look. Either way, a declined merge stays declined for 24 hours on every head of that pull request, so a new commit cannot get around it. |
| Hold sandbox previews for a person | `holdPreviews` (default `true`) | A token's request to publish a sandbox port as a link waits for a person. |
| Monthly agent change limit | `monthlyChangeCap` (1 to 100,000,000, or `null` for none) | Counts every caisson write made with an access token in the organization's repositories, labeled as an agent's or not. At the limit, those writes answer 402 `agent_change_cap` until an owner raises it. Owners get an inbox notice and an email at 80% and again at 100% of the month's limit. |
| Agent changes per minute | `changesPerMinute` (1 to 10,000, or `null` for none) | Past that many such writes a minute in the organization, they answer 429 with `Retry-After`. |
| Agent pushes must be signed | `requireSignedCommits` (default `false`) | A git push made with an access token is refused unless every new commit on every branch has an SSH signature from a verified signing key of the pusher or the author. SSH pushes use a person's own key and are not affected. |

The three limits that live in an organization's other settings also apply to agents: [merge rules](https://sailfork.com/docs/branches#merge-rules), [branch rules and rulesets](https://sailfork.com/docs/branches#branch-protection-rules) and the [caisson policy](https://sailfork.com/docs/caissons#writes-held-for-a-person).

### Held merges and previews

A merge and a sandbox preview cannot be undone, so they wait for a person when the organization holds them.

1. The agent's request answers 202 with `held`, `kind`, `summary` and a message that starts `HELD FOR A PERSON`. Nothing has happened. The MCP tools and the CLI (exit code 11) tell the agent to stop and ask the user.
2. People who can decide it get an inbox notice and an email. A merge is decided by someone with write access to the repository, the token's owner included. A preview is decided by a member of the organization.
3. The person approves or declines under Agent requests in the sidebar, or on the pull request's own page for a merge (`POST /api/held/{id}`). A token is refused there, so an agent cannot answer its own request. The decision is written to the audit log.
4. After an approval, the agent repeats the same request and it goes through once. The approval names the pull request's head commit, or the sandbox and port: a branch that moved after the approval is held again. It expires after 24 hours.
5. After a decline, the same request answers 403 `held_declined` for 24 hours.

A merge into a repository that is not in an organization, a browser session and a `GITHUB_TOKEN` are not held. Auto-merge is held when it is turned on, and the later merge then runs as the person who turned it on, with their agent token's label.

## Branch protection and merge rules

These are the same rules people meet. An agent does not get a separate set, and gets no exemption.

| Rule | For an agent's token |
| --- | --- |
| Pull requests only | Applies unless the token's owner is a repository admin. Use a token's branch limit to cover that case. |
| Block force pushes, block deletion | Apply to everyone. |
| Who may push, who may merge | Apply to the token's owner. Admins are not exempt. |
| Signed commits, blocked secrets, verified emails, blocked extensions, largest file | Checked on every git push before any ref moves. They read pushes, not caisson commits. |
| Approvals from people | A pull request needs approvals from people who are not its author. An approval counts by the account that gave it, so a token of another person's account counts as that person. An app's bot counts only where the repository trusts that app. |
| Required checks, resolved threads, up to date | Decide every merge. |
| Merge queue, code owners' approval | Apply. Merging past them takes an admin's reason, and a token cannot give one (403 `bypass_needs_person`). |
| A pull request that adds a database migration | Needs a person's approval. |

The branch limit `agent/**` is the simplest way to keep an agent token off every branch outside `agent/`. See [Branches and protection](https://sailfork.com/docs/branches).

## Caissons

A caisson is where an agent edits code on the server. Writes through it are checked before they land.

- **Path rules.** The repository's owner (you, or the organization) marks paths as Ask me or Never. A path with no rule is allowed. A write under a Never rule is refused with a 403 that names the rule. Some rules are fixed: `migrations/**` always asks and `.sailfork/**` is always never.
- **Held writes.** A write under an Ask me rule answers 202, the caisson moves to `waiting`, and the write lands only when a person approves it in the browser. No token can approve one.
- **Scope.** A caisson takes 1 to 50 path entries, and a write outside them is refused.
- **Review before shipping.** The caisson policy can require a review of the exact code before the pull request opens and again before it merges.
- **Signed commits.** A commit made from a caisson is signed by the server with an SSH signature. You stay the author and committer, and the message ends with `Sailfork-Caisson`, and, when they apply, `Sailfork-Token` (the token's name and id) and `Sailfork-Agent` trailers that the signature covers. Anyone can check one against the public key at `/.well-known/sailfork/allowed_signers`. See [Caissons](https://sailfork.com/docs/caissons).
- **Lockdown.** The MCP server hides what people without push access wrote from the model: titles, bodies and comments on issues and pull requests, where a prompt injection would sit. It is on by default for public repositories and off for private ones. `?lockdown=on` extends it to every repository and `?lockdown=off` turns it off. It applies to what the model reads through MCP tools, not to the REST API.

## What is recorded

| Record | What it holds | Who reads it | Kept |
| --- | --- | --- | --- |
| Tool-call record | One row per API request an access token made under an MCP tool: the tool, the route without its query string, the status, the repository, the client and session. Never the arguments. | An organization's owners for its repositories (`GET /api/orgs/{org}/audit/tool-calls`, and an NDJSON export), and you for your own calls (`GET /api/me/audit/tool-calls`) | 180 days |
| Organization audit log | Changes to members, rules, access, the agent controls, held-request decisions, merges past a rule, repository deletions and purges, with the actor and whether an agent did it | The organization's owners, in the browser or over the API with `org:read`, and as an NDJSON export | 730 days |
| Your audit log | Moderation and access changes on your personal repositories | You | 730 days |
| Security log | Your sign-ins, SSH key and token creation and use | You | 2 years |

Two things the record does not cover. An ordinary action by an agent, such as a comment or a push, is not an audit event: it shows as the work itself, labeled as agent work, and in the tool-call record when it came through an MCP tool. And a request made with a token by the CLI or the REST API rather than an MCP tool carries no tool name, so it is not in the tool-call record.

The tool-call record is written after the response, never blocks a request and is skipped for browser sessions and `GITHUB_TOKEN` runs. When the account turned off agent tracking, its rows keep the tool and the route and leave the client, session and surface empty.

Immutability, exactly: the application inserts audit rows and reads them. The only code that deletes them is the hourly retention job, which skips rows under a legal hold, and the cascade that removes an organization's or account's rows when it is deleted. A deleted account's handle stays in an organization's log, as the log's actor name. Nothing signs the rows, and the database itself is not append-only, so a log is only as trustworthy as the access to that database.

## Undo, purge and deletion

| Action | How long it can be reversed | By whom |
| --- | --- | --- |
| Many agent actions: an issue or pull request comment, an issue or pull request update, a pull request merge, a caisson file delete, a branch delete, a token created | 24 hours, once (`sailfork undo`). A merge undoes only while the base has not moved past it. | The account the agent acted as |
| Scheduling a repository for deletion (`repo:admin`) | 14 days: restore it in Settings, or with `DELETE /api/repos/{owner}/{repo}/deletion`. Once the purge has started it cannot be cancelled. | A repository admin |
| Purge asked for with an access token (`repo:admin` and `repo:purge`) | 30 days. The repository stays scheduled and hidden, and the hourly job deletes it no sooner than 30 days after the request. | A repository admin, in the browser or with a token |
| Purge from a browser session | Not at all: the repository's data and row are deleted at once. | |
| Held write, merge or preview | Not applied until approved, so nothing to undo. | |

A repository under a legal hold cannot be purged, and a repository with forks is purged only after they are gone.

## What a token can never do

Some actions need a browser session whatever the token's scopes: approving or declining a held write, merge or preview, changing the caisson policy or the organization's agent controls, merging past the merge queue or code owners' approval, signing sessions out, passkeys and recovery codes, changing an email address, deleting an account or an organization, transferring a repository, changing a plan and exporting your data. See [Roles and permissions](https://sailfork.com/docs/permissions#what-agents-can-and-cannot-do).

---

Every docs page: https://sailfork.com/llms.txt
