---
title: policy operations
---

The exact fields each `policy.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/docs/ko/reference/http-api#request) its namespace and agent; see [identities and namespaces](/docs/ko/concepts/identities-and-namespaces). The [operations index](/docs/ko/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `policy.check`

A hypothetical call: what would the rules decide right now?

`POST /v1/policy.check` · MCP `loom_policy_check` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `operation` | `str` | required | the operation the call would invoke |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `session_id` | `str` | `'-'` | The session or conversation the row belongs to; `'-'` for none. |
| `args` | `dict[str, Any]` | *(computed)* | the call's arguments (projected the same way agent_events.args is) |
| `at` | `datetime \| None` | `None` | decision time; default now (past-only, closed windows) |
| `rules` | `list[dict[str, Any]] \| None` | `None` | Evaluate these rules instead of the stored ones — validate a rule before storing it, or replay a stored trace against a candidate rule. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `decision` | `Literal['allow', 'deny']` | Rule denials, ordinary write errors or enforcing protected UNKNOWN deny; otherwise allow. |
| `would_enforce` | `bool` | The same verdict as a boolean: true when an enforcing gate would block the call. |
| `mode` | `str` | The deployment's `LOOM_POLICY_MODE`; dry runs evaluate inherited rules in enforce mode. |
| `write_shaped` | `bool \| None` | Whether the operation writes, which controls ordinary backend-error refusal; null when the operation name is unknown. |
| `determining_rules` | `list[str]` | Ids of the rules that deny the call; empty when none does. |
| `errors` | `list[str]` | Leaf errors, including fixed protected-history UNKNOWN without a leaf value. |
| `rules` | `list[dict[str, Any]]` | Per applicable rule: effect, mode, whether the condition held, whether it denies, and each ordinary leaf's value (null for protected UNKNOWN). |
| `latency_ms` | `int` | Milliseconds the evaluation took. |

## `policy.decisions`

List the recorded history-policy decisions for a namespace, optionally one verdict.

`POST /v1/policy.decisions` · MCP `loom_policy_decisions` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `decision` | `Literal['allow', 'deny'] \| None` | `None` | Only decisions with this verdict; None returns both. |
| `limit` | `int` | `100` | At most this many rows, 1-1000, newest first. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[PolicyDecisionRow]` | Recorded gate decisions for the namespace, newest first. |

## `policy.delete`

Remove a history-policy rule (tombstoned, so its past decisions stay explainable).

`POST /v1/policy.delete` · MCP `loom_policy_delete` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `policy_id` | `str` | required | The rule to remove; it is tombstoned, so past decisions naming it stay readable. |
| `removed_by` | `str` | `''` | Written as the rule's `created_by` only when the stored row has none; no remover is recorded otherwise. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `removed` | `bool` | False when no live rule has that id. |
| `widening` | `bool` | True when deleting it widened what agents may do (an enabled rule); a `policy.widened` audit row is written then. |

## `policy.list`

The namespace's policy rules and the enforcement mode.

`POST /v1/policy.list` · MCP `loom_policy_list` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `include_disabled` | `bool` | `True` | False leaves out rules with `enabled` false; deleted rules never appear. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rules` | `list[PolicyRuleOut]` | The namespace's live rules, ordered by `policy_id`. |
| `mode` | `str` | The deployment's `LOOM_POLICY_MODE`: `off`, `shadow` or `enforce`. |

## `policy.set`

Create or replace a namespace history-policy rule (effect, actions, condition).

`POST /v1/policy.set` · MCP `loom_policy_set` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `policy_id` | `str` | required | The rule's id in the namespace (letters, digits, `_.:-`); an existing id is replaced. |
| `effect` | `Literal['forbid', 'require']` | required | `forbid` denies the call when the condition holds; `require` denies it when the condition does not hold. |
| `actions` | `list[str]` | required | operation names or globs this rule applies to ('memory.delete', 'memory.*') |
| `condition` | `dict[str, Any]` | required | history condition: {op: formerly\|count_within\|not_since\|all\|any\|not, ...}; leaves take within ('1h'), operation, key (agent\|session\|user), success, args_equal |
| `description` | `str` | `''` | Free text stored with the rule. |
| `enabled` | `bool` | `True` | False keeps the rule stored but skips it at evaluation. |
| `mode` | `Literal['inherit', 'shadow', 'enforce']` | `'inherit'` | Per-rule enforcement: inherit the deployment's LOOM_POLICY_MODE, or override — shadow (record only, even when the deployment enforces) / enforce (block, even when it only shadows). |
| `created_by` | `str` | `''` | Author recorded only when the call has no authenticated principal to stamp. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rule` | `PolicyRuleOut` | The rule as stored. |
| `leaf_count` | `int` | How many history leaves the condition has; each is one query per evaluation. |
| `widening` | `bool` | Did this change WIDEN what agents may do (raise a cap, drop a correlation, disable, downgrade mode)? |
| `change` | `list[str]` | What changed against the stored version, one phrase per difference (`rule created` for a new id; `(widens)` / `(unknown)` mark widening ones). |

<!-- prettier-ignore-end -->
