How Policies Are Evaluated

When your agent attempts an action, Gatekeeper doesn't check one rule — it walks through several layers of policy in a fixed order. Understanding that order is the difference between a policy that does what you meant and one that quietly never fires.

The layers

Evaluation runs top down. The first layer to return a decision wins — which means a broad rule high in the chain beats a precise rule lower down.

Kill switch. Sits above everything else. While it's active, requests stop regardless of what any rule below would have decided. It's the control you reach for when something is going wrong and you want agent activity to stop now, not after you've worked out which rule to change. It shows as Inactive in normal operation.

Org rules. Apply across every service your organization has connected. Two kinds live here: limits, which throttle volume rather than actions — a rate limit in requests per minute, a daily request cap, and a daily data cap in megabytes — and custom rules, written as JavaScript policy functions.

Service rules. Apply to one connected service, for everyone in the organization. This is where most day-to-day policy lives: what agents may do in HubSpot, what they may do in GitHub.

User rules. Overrides for a specific person or bot. Useful for granting someone broader access than the service rule allows, or for tightening an unattended bot beyond everyone else.

Org default. The terminal layer. If nothing above matched, this decides — and it's whichever posture you chose during setup, Allow or Deny. You can change it later, and set it per service.

Select any layer on the Policies page to configure it.

How a decision gets made

Each chain returns one of four things:

The first layer that returns anything other than Pass decides the outcome. A deny at any layer blocks the request outright — there is no layer below that can overturn it.

That first point is the one that catches people out. A broad rule sitting in an early layer will decide the request before a narrower, more carefully written rule further down ever gets to run. Order beats specificity — always.

If you need an exception to survive, it has to sit in the same layer as the rule it's excepting, or an earlier one. Putting it lower doesn't work.

Worked example

An agent tries to create a HubSpot contact. The verdict trail looks like this:

chain "default"      → pass
chain "svc-hubspot"  → allow   (rule: svc-default)

Gatekeeper refers to layers as chains in raw output like this. The org layer had nothing to say, so evaluation moved on. The HubSpot service layer allowed it, and evaluation stopped. Any user rule further down was never consulted.

What your rules can see

Policies are evaluated against a context object describing the request. The fields available to you include:

• Request — the service, the tool being called, and the full parameters submitted
• Client — who is making the request, and which organisation they belong to
• Credential — whether the stored credential is still valid and when it expires
• Connection — source IP address and client user agent
• Activity — how many requests this agent has made in the last minute and today, and how many bytes it has moved today
• Time — the current timestamp

The activity fields are what make volume rules possible, and they're the same measurements behind the org-level limits. If a simple threshold is all you need, set a limit rather than writing a rule. Reach for a custom rule when the condition is more specific than a count — approval beyond a threshold only for write actions, for instance.

The timestamp makes time-window rules possible, so you can deny calls outside working hours.

Before writing a rule against any of these fields, check what's actually present for the request you care about — see Testing a Policy Before You Deploy It.

Practical guidance

• Put broad guardrails high, exceptions low — and expect the broad rule to win. If an exception needs to survive, it belongs in the same layer as the rule it's excepting, or an earlier one.
• Use Pass deliberately. A layer that returns Pass is delegating, not permitting. That's usually what you want at the org level, so per-service rules can do the detailed work.
• Know what your org default is. It's the layer that decides every request nothing else matched, and it's easy to forget you set it during onboarding.
• Simulate before you save. Layer interactions are the most common source of "my policy isn't working" tickets