Policies

Policies is where you say what may be done, what may be spent, and who is allowed to change either.

Everything here is checked before an action reaches an app and before any credential is unlocked. A refusal therefore costs nothing: nothing was sent, nothing was charged, and the refusal is recorded like any other outcome.

One document, replaced whole

The rules are a single document. There is no partial edit: read it, change it, write it back. Each write gets a version number, so you can see when it last moved and what it was before.

A project that has never written one behaves exactly like a project with no rules. An empty allow list allows everything, and a denial always beats a permission, so the starting position is permissive and every restriction is one you added deliberately.

Writing takes an approver key. An agent key that tries is refused. The reason is worth stating plainly: an assistant that could rewrite the rules could delete the approval gate, the denials, the permission caps, and the spending ceilings in one call, and every one of them would be advice rather than enforcement.

What you can say

They are checked in a fixed order: denials, then permissions, then per-person visibility, then the approval gate, then the rate ceilings.

The codes those produce are deliberately different from each other. A rule denial and a rate refusal call for different behaviour from whatever is calling: one should stop and one should wait. See Error codes and Limits.

Per-person visibility

This is how you decide what each of your users is offered.

await approver.policy.setPolicy({
  policy: {
    entityVisibility: [
      { toolkitSlug: "stripe", entityIds: ["admin-1"] },
      { toolkitSlug: "github", toolSlug: "github.delete_repo", entityIds: [] },
    ],
  },
});

Three conventions are worth committing to memory. A tool nobody has written an entry for is visible to everybody, so an empty list changes nothing. An entry naming one tool decides for that tool and overrides the entry for its app. An entry naming nobody hides its target from everybody, which is how you switch something off without deleting it.

Both halves of the system read it: a hidden tool is dropped from search results, and a hidden tool called by name is refused before any credential is unlocked. Somebody cannot reach a hidden tool by guessing its name.

This shapes what your users see. It is not a wall against whoever holds your own key.

Rate ceilings

A rate ceiling is a bucket of calls that refills over a window, counted per project, per person, or per tool.

velocityLimits: [
  { scope: Scope.PROJECT, maxCalls: 1000, perSeconds: 3600n },
  { scope: Scope.TOOL, toolSlug: "gmail.send_message", maxCalls: 20, perSeconds: 3600n },
]

Two ceilings on the same scope with different numbers are separate buckets, so a broad limit and a tight one on something sensitive can coexist. Every applicable one is tested before any of them is spent, so a call refused by one does not drain the others.

Writing a new document drops the counters for that project, so a changed ceiling starts against a fresh window rather than against an old count.

Spending ceilings

A spending ceiling bounds what may be spent over a window, for the project or for one person. Work that would exceed it is refused with the instant the window resets, rather than being run and billed.

Jobs read the same ceilings, so a plan whose estimate exceeds what is left is stopped before it starts rather than halfway through. See Jobs.

The approval gate

The one rule that pauses rather than refuses, and the one with enough moving parts to have its own page. See Approvals and questions.

Permission caps

Permission caps are the one rule read at connect time rather than at call time, because once somebody has agreed to a permission the grant is real whatever happens afterwards. See Connect an app.