# Policy rules and argument conditions

> What a policy rule can match, how to hold or block a tool only when a number in its arguments crosses a limit, and what happens when the argument is missing, not a number or spelled differently.

Source: https://docs.atensecurity.com/docs/operations/policy-rules

A policy rule says what Thoth does with a tool call: hold it for a person (`review`) or deny it
(`block`); `monitor` records the rule without holding or denying. A rule names a tool and can also check a number in that tool's arguments,
for example "hold `approve_expense` when `amount` is over 100".

A rule is made in dev or prod, simulated, approved by an org admin and then applies at once. Every path
reaches the same rule: the `thoth_policy` Terraform resource (also in the Pulumi provider),
`thothctl governance policies`, the MCP server's `preview_policy_rule`, the dashboard and Ask Thoth.

## What a rule matches

A rule's `rules` object holds one of `tool` (one tool name), `tool_names` (a list), `model_name`,
`model_provider`, `purpose`, `data_classification`, `min_token_count` or `min_estimated_cost_usd`, or the
overlay keys `blocked_tools` and `allowed_tools`. A rule holds one of these conditions. Tool names match
without regard to case.

## Argument conditions

A rule that names a tool (`tool` or `tool_names`) can carry up to five `argument_conditions`. All of them
must hold, together with the tool match.

```json
{
  "tool": "approve_expense",
  "argument_conditions": [
    { "argument": "amount", "operator": "gt", "value": 100 }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `argument` | An argument name, or a dotted path to a nested object (`expense.amount`): at most 4 names, each letters, digits, `_` or `-`, starting with a letter. Matching is on the exact name, with case |
| `operator` | `gt`, `gte`, `lt`, `lte` or `eq` |
| `value` | A number between -1e15 and 1e15 |
| `when_missing` | Optional, `match` or `no_match`. What a call that leaves the argument out does. Unset: a `review` or `block` rule matches it, a `monitor` rule does not |

Argument conditions need a `tool` or `tool_names` match, and cannot be combined with `blocked_tools` or
`allowed_tools`, which apply to every call to the tool whatever its arguments say.

### Terraform, thothctl and MCP

```hcl
resource "thoth_policy" "large_expenses" {
  environment = "prod"
  name        = "Hold large expenses"
  type        = "scope"
  enforcement = "review"
  applied_to  = ["all"]
  rules_json  = jsonencode({ tool = "approve_expense" })

  argument_conditions = [
    { argument = "amount", operator = "gt", value = 100 },
  ]
}
```

```bash
thothctl governance policies create --environment prod --name "Hold large expenses" \
  --type scope --enforcement review \
  --rules '{"tool": "approve_expense"}' --argument-condition 'amount>100'
```

`--argument-condition` takes `ARGUMENT OP NUMBER` with `>`, `>=`, `<`, `<=` or `==`, and an optional
`,when-missing=match` or `,when-missing=no_match`. It can be repeated. The same conditions can be written
inside `--rules` (or Terraform's `rules_json`) as `argument_conditions`; use one place or the other.

Thoth previews the rule in plain words before anything is applied, and you can try it with
`thothctl governance policies simulate --tool approve_expense --params '{"amount": 150}'`.

## What a call that does not look like the rule does

Arguments come from the agent, and an agent can omit a value or send it in an unexpected form. Hold and
block rules fail closed, so a call is not let through unreviewed because the rule could not read it.

| The call | What a `review` or `block` rule does |
| --- | --- |
| The argument is a number (`150`) or a plain decimal in text (`"150"`, `"-3.50"`) | Compared as a number. A match applies the rule's own action |
| The argument is left out, or is `null` | Matches (`when_missing` unset or `match`), so the call is held or denied. `when_missing: no_match` opts out |
| The argument is present but not a plain number: `"$150"`, `"1e3"`, `" 150"`, `"+150"`, `"1,500"`, a boolean, a list or an object | The call is **held for review**, even for a `block` rule, because Thoth cannot tell whether the rule would have matched |
| A key that differs from the rule's only in case, `-`, `_`, `.` or spaces, or in a Unicode compatibility form (`Amount`, `AMOUNT`, `amount `), is present next to or instead of the exact one | **Held for review**, unless the exact key is present, readable and matches, in which case the rule's own action applies |
| The agent withheld argument values (hash, redact or drop in its data handling) | Held for review |

A `monitor` rule does not hold or deny, so its argument conditions change nothing about what happens to
the call.

A hold from an argument that could not be read has the reason code `argument_unreadable` and an
explanation that says an argument a rule checks could not be read as a number. It names the rule, never
the value or the key. Such a hold never replaces a deny: if another rule, the agent's blocklist or another
check would deny the call, it is denied.

Think of the **exact argument name** as part of the rule. Thoth does not guess synonyms: `amt`,
`total` and `amount_usd` are different names. Use the argument names the tool declares. If an agent
may send the amount under several names, write a condition for each (up to five), or hold the tool
whatever its arguments say.

## Limits

- Matching is deterministic and reads only what the call sent. It compares numbers; it does not judge
  what a value means, convert units (cents against dollars) or check the total across several calls.
- A rule reads at most four levels of nested objects and never looks inside a list: a value inside an
  array of objects is not read, so an `amount` there is treated as left out.
- A key written with look-alike letters from another script (a Cyrillic `а` for `a`) is a different key
  and is not detected. With `when_missing` unset the call is still held as left out.
- If an agent's JSON has the same key twice, the parser keeps one value; Thoth cannot see the other.
- `when_missing: no_match` lets through any call that does not carry the argument under its exact name.
  Use it only where that is what you want.
- Raising or lowering a limit changes what is held from then on; it does not change decisions already
  made. `thothctl governance policies replay` estimates what a change would have decided over recent
  captured decisions, for calls whose arguments were stored.
