Policy Rules: Control What Agents Can Do

Author allow/block policy rules with targets, identities, rate limits, and approvals. Rules evaluate first-match, stage as a draft, and enforce on publish.

Policy rules control what your agents are allowed to do. Instead of giving an agent unrestricted access to every service it has credentials for, you set boundaries: block operations, require human approval, or cap usage, all in one ordered list your whole team can read.

Why rules matter

Credentials get an agent through the door. Rules decide what it can do once inside.

Without rules, an agent with Gmail credentials can read, send, and delete emails with no limit. That’s useful, but it’s also how you get an agent mass-deleting an inbox before anyone can stop it. Rules let you say things like “this agent can use Gmail, but sending requires approval.”

Deterministic enforcement, not prompts

You can tell an agent “never delete emails without my approval” in a system prompt. But a prompt is a suggestion, not a guarantee. Agents are non-deterministic. They can be manipulated through prompt injection, they can misinterpret instructions, or they can be too eager to please and take actions you didn’t intend.

Rules are different. They’re enforced outside the agent, at the gateway level, before the request ever reaches the external service. No amount of prompt manipulation, jailbreaking, or overly helpful behavior can bypass a rule. If a rule blocks Gmail deletes, that request is blocked. Every time, deterministically, regardless of what the agent was told or tricked into doing.

How the policy engine works

Every request an agent makes passes through the gateway, which evaluates the scope’s rules top-down, first match wins:

1. Organization rules run first: org-wide guardrails an individual project cannot loosen.
2. Project rules run next: refinements for that project’s agents.
3. Each level ends in a Default Rule, which decides what happens when nothing matched (Allow or Block).

A request is allowed only when both levels permit it. The first rule whose identities and targets match decides; later rules never run, so order matters (drag rules in the console, or reorder via the API).

Draft and publish

Edits never take effect immediately. Changes stage into a draft; the gateway keeps enforcing the last published set until you press Apply Changes (or call the publish API). Publishing snapshots the entire draft (including changes staged by teammates), so review the pending list before applying.

Anatomy of a rule

A rule pairs who (identities) with what (targets), and applies an action with optional modifiers.

• Identities: who the rule applies to. Project rules target a specific agent or all agents; organization rules target agent groups, users, or user groups. Empty means everyone.
• Targets: at least one destination:
  • an app ({"kind":"app","provider":"gmail","tools":["send_email"]}), optionally narrowed to specific catalog tools, or the whole app when tools is omitted;
  • a connection ({"kind":"connection","connectionId":"..."}): one specific connected account;
  • a secret ({"kind":"secret","secretId":"..."}): a stored credential and its host;
  • a network pattern ({"kind":"network","hostPattern":"api.example.com","pathPattern":"/v1/*","method":"POST"}).
• Action: allow or block.
• Modifiers (allow rules only): requireApproval holds matching requests for a human decision; rateLimit plus rateLimitWindow cap usage, with each agent tracking its own counter.

Migrating from the legacy model? The old rate_limit and manual_approval actions became modifiers on allow rules, and the flat host/path/method fields moved into a network target.

Creating rules

From the console: Policy → Add Rule. From the CLI:

onecli policy rules create \
  --name "Gmail sends need approval" \
  --action allow \
  --targets '[{"kind":"app","provider":"gmail","tools":["send_email"]}]' \
  --require-approval

{
  "rule": {
    "id": "9f2c1b8a",
    "scope": "project",
    "status": "draft",
    "generation": 0,
    "priority": 3,
    "enabled": true,
    "isDefault": false,
    "logicalId": "b41a77c2",
    "source": "custom",
    "name": "Gmail sends need approval",
    "description": null,
    "action": "allow",
    "rateLimit": null,
    "rateLimitWindow": null,
    "requireApproval": true,
    "identities": [],
    "targets": [{ "kind": "app", "provider": "gmail", "tools": ["send_email"] }],
    "createdAt": "2026-07-21T09:15:00.000Z"
  },
  "published": true,
  "generation": 7
}

CLI writes auto-publish when the draft has no other staged changes; otherwise the publish is withheld (publishSkipped appears in the output) so you never accidentally ship a teammate’s half-finished edits. Review with onecli policy status, then onecli policy publish, or pass --publish-all. Use --no-publish to stage deliberately.

The same rule via the API (an org key needs the X-Project-Id header; a project key scopes itself):

curl -X POST https://api.onecli.sh/v1/policy/rules \
  -H "Authorization: Bearer $ONECLI_API_KEY" \
  -H "X-Project-Id: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gmail sends need approval",
    "action": "allow",
    "requireApproval": true,
    "targets": [{"kind":"app","provider":"gmail","tools":["send_email"]}]
  }'

Then make it enforce with POST /v1/policy/publish, or Apply Changes in the console. Read the enforced set with GET /v1/policy/rules?status=published, and compare draft against published rules by logicalId (published row ids regenerate on every publish).

Examples

Block a destructive operation everywhere (an org rule, applies to everyone):

onecli org policy rules create \
  --name "Never delete repos" \
  --action block \
  --targets '[{"kind":"network","hostPattern":"api.github.com","pathPattern":"/repos/*","method":"DELETE"}]'

{
  "rule": {
    "id": "c81f3a20",
    "scope": "organization",
    "status": "draft",
    "generation": 0,
    "priority": 0,
    "enabled": true,
    "isDefault": false,
    "logicalId": "e63d09b7",
    "source": "custom",
    "name": "Never delete repos",
    "description": null,
    "action": "block",
    "rateLimit": null,
    "rateLimitWindow": null,
    "requireApproval": false,
    "identities": [],
    "targets": [
      {
        "kind": "network",
        "hostPattern": "api.github.com",
        "pathPattern": "/repos/*",
        "method": "DELETE"
      }
    ],
    "createdAt": "2026-07-21T09:20:00.000Z"
  },
  "published": true,
  "generation": 3
}

Cap an expensive API (allow plus a rate limit; each agent gets its own counter):

onecli policy rules create \
  --name "Limit Anthropic calls" \
  --action allow \
  --targets '[{"kind":"network","hostPattern":"api.anthropic.com"}]' \
  --rate-limit 100 --rate-limit-window hour

{
  "rule": {
    "id": "1d40b7ce",
    "scope": "project",
    "status": "draft",
    "generation": 0,
    "priority": 4,
    "enabled": true,
    "isDefault": false,
    "logicalId": "a90c55f1",
    "source": "custom",
    "name": "Limit Anthropic calls",
    "description": null,
    "action": "allow",
    "rateLimit": 100,
    "rateLimitWindow": "hour",
    "requireApproval": false,
    "identities": [],
    "targets": [{ "kind": "network", "hostPattern": "api.anthropic.com" }],
    "createdAt": "2026-07-21T09:22:00.000Z"
  },
  "published": true,
  "generation": 8
}

Scope one agent to read-only Gmail (block that agent from the write tools):

onecli policy rules create \
  --name "Reporter agent: no Gmail writes" \
  --action block \
  --identities '[{"type":"agent","id":"agent_abc123"}]' \
  --targets '[{"kind":"app","provider":"gmail","tools":["write_all"]}]'

{
  "rule": {
    "id": "7b2e91d4",
    "scope": "project",
    "status": "draft",
    "generation": 0,
    "priority": 5,
    "enabled": true,
    "isDefault": false,
    "logicalId": "f17ab3c8",
    "source": "custom",
    "name": "Reporter agent: no Gmail writes",
    "description": null,
    "action": "block",
    "rateLimit": null,
    "rateLimitWindow": null,
    "requireApproval": false,
    "identities": [{ "type": "agent", "id": "agent_abc123" }],
    "targets": [{ "kind": "app", "provider": "gmail", "tools": ["write_all"] }],
    "createdAt": "2026-07-21T09:24:00.000Z"
  },
  "published": true,
  "generation": 9
}

Discover an app’s tool ids (including group wildcards like read_all and write_all where the app supports them). Output abridged to a few tools per group; the real catalog lists every tool:

onecli apps permission-definition --provider gmail --fields groups

{
  "groups": [
    {
      "category": "read",
      "tools": [
        { "id": "search_messages", "name": "Search messages", "description": "Search and list messages matching a query" },
        { "id": "get_message", "name": "Read message", "description": "Retrieve a specific email message" }
      ],
      "wildcard": {
        "id": "read_all",
        "name": "All read operations",
        "description": "Search, read, and list emails, threads, drafts, labels, and settings"
      }
    },
    {
      "category": "write",
      "tools": [
        { "id": "send_email", "name": "Send email", "description": "Send email on your behalf" }
      ],
      "wildcard": {
        "id": "write_all",
        "name": "All write operations",
        "description": "Send, import, create drafts, modify labels, trash, and delete emails and threads"
      }
    }
  ]
}

Conditions

Conditions narrow a rule beyond its targets by inspecting the request body. Each condition names a target (body), an operator (contains), a value, and an optional key to scope the match to one JSON field; multiple conditions are ANDed.

onecli policy rules create \
  --name "Approve large charges" \
  --action allow --require-approval \
  --targets '[{"kind":"network","hostPattern":"api.stripe.com","pathPattern":"/v1/charges","method":"POST"}]' \
  --conditions '[{"target":"body","operator":"contains","value":"10000","key":"amount"}]'

{
  "rule": {
    "id": "5e8c02af",
    "scope": "project",
    "status": "draft",
    "generation": 0,
    "priority": 6,
    "enabled": true,
    "isDefault": false,
    "logicalId": "d24f18e0",
    "source": "custom",
    "name": "Approve large charges",
    "description": null,
    "action": "allow",
    "rateLimit": null,
    "rateLimitWindow": null,
    "requireApproval": true,
    "conditions": [
      { "target": "body", "operator": "contains", "value": "10000", "key": "amount" }
    ],
    "identities": [],
    "targets": [
      {
        "kind": "network",
        "hostPattern": "api.stripe.com",
        "pathPattern": "/v1/charges",
        "method": "POST"
      }
    ],
    "createdAt": "2026-07-21T09:26:00.000Z"
  },
  "published": true,
  "generation": 10
}

Allow rules with a single specific connection target instead accept a session policy object for resource scoping: {"repositories": ["org/repo"]} (GitHub) or {"folders": ["/exports"]} (file providers), restricting which resources that connection can touch.

Manual approval

An allow rule with requireApproval holds matching requests until a human decides. The gateway keeps the agent’s connection open (up to 5 minutes) while it waits; unanswered requests are denied. The reviewer sees the method and URL, sanitized headers, and a body preview, so they can judge exactly what the agent is trying to do.

Decisions flow through the console, or programmatically via the SDK:

const handle = onecli.configureManualApproval(async (request) => {
  console.log(`${request.method} ${request.url}`);
  return "approve"; // or "deny"
});

See the Node SDK reference for the org-wide variant.

App permissions are rules

Per-tool app permissions (“block Gmail sends”, “GitHub pushes need approval”) are ordinary policy rules with an app target, exactly like the examples above. The per-app App Permissions panel shows the effective result per tool (Allowed, Needs approval, Blocked, or Not managed) and links to the Policy console, which is where you edit.

Read the current per-tool state from the API (available on OneCLI Cloud and Enterprise self-hosted releases):

curl "https://api.onecli.sh/v1/policy/effective-app-permissions?provider=gmail" \
  -H "Authorization: Bearer $ONECLI_API_KEY" \
  -H "X-Project-Id: $PROJECT_ID"

How rules interact with credentials

Rules evaluate before credential injection. A blocked request is rejected at the gateway: the credential is never attached, and the upstream service never sees the request. Allow rules that name a specific connection or secret also drive which credential is injected.

Self-hosted deployments

Self-hosted servers that have not yet cut over to the policy engine keep the legacy /v1/rules model: legacy writes work there, and /v1/policy writes return 403 until the cutover release. On OneCLI Cloud the policy engine is live; legacy rule writes return 410 Gone pointing here.

Coming soon

• Monitor action: log matching requests without blocking, useful for auditing before enforcing
• Time-bound access: grant access only during specific time windows