policy operations

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

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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

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']	deny when a rule denies the call, or a rule errored on a write-shaped operation; allow otherwise.
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; the dry run evaluates as if every rule enforced.
write_shaped	bool \| None	Whether the operation writes (a rule error then fails closed); 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 evaluation errors; a rule that errored neither allows nor denies.
rules	list[dict[str, Any]]	Per applicable rule: effect, mode, whether the condition held, whether it denies, and each leaf's value.
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).