Policies

A policy decides, for every tool call of the agents that use it, whether the call is allowed, denied or held for human approval. The Policies area of the dashboard is where you write policies, test them, try them on real recorded calls and roll them out.

This page is a map of that area: what each screen and control does and who can use it. The Policies guide explains the work itself in depth, from writing rules to rolling back.

Who can do what

Management API keys with the policies:write scope can create drafts, set the shadow, edit examples and save simulations, but can never activate, roll back, stop or download the evidence file.

Versions in one paragraph

A policy is a series of versions. A version is immutable: once saved, its document never changes. A new version starts as a Draft; activating it makes it the one Active version that decides calls, and the previously active version becomes Superseded. A rollback never edits history: it creates a new version that is an exact copy of an earlier one and activates it. While a policy has no active version, the Gateway denies every call of its agents. See Versions.

The policy list

Policies lists every policy of the organization with:

• Name;
• Active: the active version and its digest, None active, or an emergency-stop badge;
• Shadow: the shadow version, marked "not enforced" (the column appears when at least one policy has a shadow);
• Agents: how many agents use it, and how many of them are in observe mode;
• Last change: for example "v4 draft saved" or "v3 activated 2 days ago";
• Description (the column appears when at least one policy has one).

When a policy's active version is an emergency stop, a banner above the list names it ("Emergency stop: …") with Review and roll back.

Owners, admins and developers see New policy.

Create a policy

New policy opens Start from, a gallery of templates and a blank start.

• Templates: Support refunds, Coding and deployment, CRM and sales, Finance operations and Read-only research. Each card shows a summary and the recommended rollout; choosing one opens a form with Name, Description (optional) and its Parameters (amounts and currencies, when the template has any), and a Preview of what the template contains, its example calls, a delegation hint and its document, all with the default parameters. Select Create draft: the policy is created with version 1 as a draft, with the template's example calls saved for testing. The page then shows which of your tools the template's rules match and the draft's decision map. Select Open the policy to continue.
• Blank (deny-all): enter a Name (the description is optional) and select Create policy. The policy opens in the Editor tab, starting from a document that denies everything ("default": "deny", no rules). No version exists until you save one.

Templates are examples, not rules for your tools: check the rules against your own tools before activating. Nothing is enforced until an owner or admin activates a version. See Create a policy.

The policy page

The page header shows the policy's name and description. Below it, the facts:

• Active version: Active vn ✓, Emergency stop vn, or "No active version: every call of its agents is denied";
• Activated: when, and by whom;
• Shadow: the shadow version, or None;
• Agents: the number of agents that use the policy, and how many are in observe mode;
• Digest: the active version's digest, with a copy button.

Owners and admins also see, in the header:

• Roll back to v… (for example Roll back to v3): opens the rollback sheet with the previously active version selected;
• a menu with Download evidence (90 days) (a JSON file of the policy's versions, changes, saved simulations, observe windows and decision counts over the last 90 days) and Emergency stop….

The page has six tabs: Rollout, Versions, Editor, Test, Shadow and Simulate. The address keeps the open tab (#editor, #test, …), so you can link to a tab.

Rollout tab

The Rollout tab shows where the policy is in its rollout and the one next step. Its stepper has four stages:

The stage is derived from the policy's state; you do not set it. While no version is active, no stage is marked as current. Under Next step, the tab offers the action that fits, for example Review and activate v1 for a first draft, Shadow v3 for a newer draft, Create the require-approval draft, or Review and promote v3. From the Shadow stage, owners and admins can also skip the require-approval stage with Promote v… directly (for example Promote v3 directly).

The Require approval stage uses a softened copy of the version you are rolling out: every call it would deny by a rule needs an owner or admin approval instead, and every call it would deny by its default needs an approval from an owner, admin or approver. Its own allow and approval decisions stay as they are.

When a shadow version exists, the tab shows the last 24 hours as an advisory check: how many recorded calls would be less or more restricted under the shadow. Advisory checks never block a step. During an emergency stop, the rollout is paused and the next step is a rollback. See Activate, roll out and roll back.

Versions tab

The Versions tab lists every version, newest first, with its status, source (for example a rollback copy or a softened copy), author, note and digest. For each version:

• Open loads it into the editor;
• Diff vs active compares its rules with the active version;
• Simulate opens it in the Simulate tab;
• Shadow makes it the shadow version (owners, admins, developers);
• Activate opens the activation sheet for a draft (owners, admins);
• Roll back to this opens the rollback sheet for a superseded version (owners, admins).

Editor tab

The Editor tab holds the Policy document as JSON (kblock.cloud/policy@1). The editor starts from the active version, else the newest version, else the deny-all document. It is read-only for approvers and viewers.

• Validate on server checks the document and shows Valid with the document's digest and advisory warnings, or the issues found.
• Save as new version stores it as a new draft, with an optional Note for this version. Nothing changes until the draft is activated. Saving a document identical to an existing draft is refused with DRAFT_EXISTS: activate that draft instead.

Rule descriptions are sent to agents with their refusals at the "rule" and "thresholds" disclosure levels (the default level is "rule"), so do not put secrets in them. Beside the editor, Reference lists the exposed tools and actions and the members with an approval role, and What agents see sets this policy's Agent disclosure (owners and admins): inherit the organization's setting, or show less. See Rules, amounts and currencies and What agents are told.

Test tab

The Test tab checks the editor text, before you save it, against calls whose outcome you know.

• Example calls are evaluation inputs (action, tool, amount and currency) with an Expected outcome (Allowed, Requires approval, Denied or No expectation) and optionally the Expected rule. They run against the editor text automatically as you type, and with Run against the editor text. Owners, admins and developers can Add an example (up to 200) and Save examples.
• Try a call evaluates one call against the editor text, and against the active version for comparison: either action, tool and amount, or a tool's exposed name with Arguments (JSON), checked and mapped to an amount the way the Gateway does. Select Evaluate. Nothing is stored or signed, and the arguments are never echoed back.

Saved examples matter at activation: a version whose examples fail cannot be activated unless an owner or admin explicitly acknowledges it. Simulations are rate limited per organization; when the limit is hit, automatic runs pause until you run them again. See Test and simulate.

Shadow and Simulate tabs

• Shadow: Start shadowing, Replace the shadow or Stop the shadow. A shadow version is evaluated on the recorded inputs of real calls next to the active version and never changes which calls execute. The report shows what the shadow would decide and lists the calls it would change, less restricted first.
• Simulate: evaluates a candidate (a saved version or the editor text) on the recorded calls of the last 7, 30 or 90 days and, optionally, on the saved examples (Include the saved examples, Include the decision map). Select Run the simulation. Nothing is stored unless an owner, admin or developer selects Save as evidence (saved versions only; kept for 400 days), which an activation from the same page then cites.

See Observe and shadow and Test and simulate.

The activation sheet

Owners and admins open it with Review and activate, Review and promote, Activate or a direct promotion. Before you confirm, it shows:

• What changes: the rule diff against the active version;
• an automatic simulation over the last 7 days and the saved examples;
• the number of recent calls that become less restricted; when there are any, you must confirm them by checking "I reviewed the … recent calls that become less restricted";
• failing examples, with Activate anyway (recorded with the activation);
• the agents in observe mode;
• Gateways: whether K-Block's Gateways can already evaluate the version. A version that uses newer policy features (rule descriptions or guards) can be activated only once K-Block has enabled those features on every Gateway, because a Gateway that cannot evaluate them would deny every call of the policy. Until then, the activation is refused with GATEWAYS_NOT_UPGRADED: remove those features and save a new version, or try again later. If it is still refused, contact K-Block support with the error code and the time you tried;
• Note (optional; the audit log records that a note was given, not its text). The note you give when you create a version is stored with that version; the note on the activation sheet is not.

Select Activate v… (or Promote v…), for example Activate v4. The activation carries the version you saw active: if someone activated another version meanwhile, it is refused with ACTIVE_VERSION_CHANGED. Other refusals include EXAMPLES_FAILING, IMPACT_CHANGED (more calls became less restricted than you reviewed) and GATEWAYS_NOT_UPGRADED (the Gateways cannot evaluate the version yet, see Gateways above).

The rollback sheet

Choose the Target (by default the version that was active before). The sheet states exactly what happens: "vn will be created as an exact copy of vm and activated immediately", the active version is superseded, and the shadow is cleared if it pointed at the restored version.

Choose whether to Also close the approvals still pending that were requested under the replaced version (or an earlier version of this policy); otherwise they stay pending and a person decides them. Add an optional Note and select Roll back to v… (the target's number).

A rollback is never blocked by examples, simulations or impact checks. Like an activation, it carries the version you saw active and is refused with ACTIVE_VERSION_CHANGED if another version became active meanwhile. If no earlier version was ever active, there is nothing to roll back to: the sheet offers Open the emergency stop instead.

The emergency-stop sheet

Emergency stop… replaces the active version at once with one of two documents:

• Deny all (recommended): every call of the policy's agents is denied;
• Require approval for all: every call waits for a person, which can flood the approvers.

The sheet lists the consequences: a new version is created and activated at once, the next call of every agent using the policy is denied or held, calls already allowed are re-checked before they run, and the observe windows of those agents end.

Under Open actions of the replaced versions, choose what happens to calls that are still open: Close pending approvals and approved calls that have not run (default for deny all), Close pending approvals only, or Keep them (default for require approval). Type the policy's name to confirm, then select Deny every call now or Require approval for every call now.

The stop is never gated by examples, simulations or impact checks. If another version became active after you opened the sheet, the stop is refused with ACTIVE_VERSION_CHANGED and the sheet offers Stop anyway, which replaces whatever is active now. Undo the stop with a rollback once the incident is resolved. See Emergency stop.

Observe mode

Observe is not set on a policy: an owner or admin starts an observe window for one agent at a time, with Start observe… on the agent's page, and only after an owner has enabled observe mode and given the live opt-in in Settings. During a window, calls that the policy's default would deny or hold run anyway and are recorded as relaxed; a window started with The default and approval rules also relaxes approval rules that are not guards. Explicit deny rules, guards and the delegation always apply.

The Policies area shows observe in three places: the Agents count on the list and the policy page ("in observe mode"), the Observe stage of the Rollout tab, and the banner at the top of every organization page. Windows end on their own; end one early from the banner or the agent page. See Observe and shadow.

Related pages