Clay Seal

Clay Seal

Incorporating business-process-logic constraints into AI systems.

Your agent has a $1,000 refund ceiling. It issues eleven refunds of $900. Every call is inside the per-refund limit, so every per-call check passes, and $9,900 goes out the door. Nothing that looks at one call at a time can see this.

Clay Seal sits in front of your tools and judges each call against the whole session: the grant, the running totals, where the arguments came from, and what the agent has already done.

Contents

Working on the code? docs/INTEGRATION.md names which modules the shipped gateway actually executes, which is the fastest way to tell the live path from the parts that are not wired in. The decision itself is SessionBroker._authorize_locked in clayseal/capabilities/broker.py; most refusals come from _floor in the same file.

Start here

If you are a coding agent, skip to the deploy runbook.

pip install clayseal

clayseal try

clayseal try takes about a minute. It runs two attacks in front of you and shows the gateway stopping them. There is nothing to configure, no key to get and nothing leaves your machine.

Every verdict there is decided live by the same gateway you would deploy. The picture is generated from a real run by python scripts/render_try_svg.py, and a test fails if it drifts from what the command prints, so it cannot become a screenshot of something that used to work.

Python 3.10 to 3.14. Two dependencies, cryptography and pyyaml.

On names. The directory is agentauth-capabilities, the package is

clayseal, and the import is clayseal.capabilities. The project was renamed

at 0.6; agentauth still imports as a deprecation shim. See

Naming at the end for the detail.

If you are an agent

Do this in the project you are editing, in order:

clayseal try --fast

clayseal howto clayseal policy new > policy.yaml

rename your_* tools; put mailboxes in egress.recipients; then:

clayseal policy lint policy.yaml clayseal skill --write

Python functions: Guardrail.from_policy_file("policy.yaml").wrap_all({...}) and bind the wrappers. Keys must match tools.allow. Construct one Guardrail per session (a new one resets ceilings). Catch Refused (budget / not granted) and StepUpRequired (held — typical for off-list email). Non-file tools go in paths.pathless.

Already an MCP server (Claude Desktop / Cursor): clayseal proxy, not clayseal serve. Do not point proxy at a plain .py file. clayseal howto is the runbook.

Use it in two lines

Wrap the tools you already have. Nothing else about your agent changes.

from clayseal.capabilities import Guardrail, Refused, StepUpRequired

def list_open_refunds(): return [{"invoice": "INV-001", "amount": 900.0}, {"invoice": "INV-002", "amount": 900.0}]

def issue_refund(invoice, amount): return f"refunded {invoice} ${amount:.2f}"

guard = Guardrail.from_dict({ "version": 1, "goal": {"id": "refund-run", "summary": "Refund the invoices the customer disputed."}, "expires_at": "2030-01-01T00:00:00Z", "tools": {"allow": ["list_open_refunds", "issue_refund"], "harmless": ["list_open_refunds"], "effects": {"list_open_refunds": "read", "issue_refund": "transfer"}}, "paths": {"pathless": ["list_open_refunds", "issue_refund"]}, "budgets": {"value": {"ceilings": {"refunds": "1000.00"}, "tracked": {"issue_refund": {"arg": "amount", "budget": "refunds"}}}}, }) tools = guard.wrap_all({"list_open_refunds": list_open_refunds, "issue_refund": issue_refund})

Call them exactly as before. The gateway decides before the tool runs.

for row in tools"list_open_refunds": try: print(tools["issue_refund"](invoice=row["invoice"], amount=row["amount"])) except Refused as exc: print("refused:", exc.reasons) # hand the reason back to the agent except StepUpRequired as exc: print("needs a human:", exc.reasons)

The first refund goes through. The second is refused, because the $1,000 session ceiling is already spent. Neither call reached your function.

The policy is inline here so you can paste the whole thing into a file and run it. In a real deployment it lives in its own YAML, where a security team can review it and a pull request can gate it. clayseal policy new > policy.yaml writes a commented one to start from, and Guardrail.from_policy_file loads it.

The wrappers keep the name, docstring and signature of your originals, so any framework that introspects them sees the tool it saw before. That covers LangGraph, the OpenAI Agents SDK, CrewAI and hand-written loops. Call the wrappers the same way you called the originals, positionally or by name.

Or put it in front of an MCP server

No code change at all. The gateway speaks MCP, so it sits between your agent and the server:

clayseal proxy --policy policy.yaml -- npx @your-org/mcp-server

Or paste this into Claude Desktop's MCP config, Cursor's MCP settings, or .cursor/mcp.json. The agent talks to Clay Seal; Clay Seal talks to the server:

{

"mcpServers": { "billing": { "command": "clayseal", "args": ["proxy", "--policy", "policy.yaml", "--", "npx", "@your-org/mcp-server"] } } }

Tools the policy does not grant are removed from the catalogue, so the agent is never told they exist.

Write the policy

This is a whole policy. It lints clean.

version: 1

goal: id: refund-run summary: Refund the invoices the customer disputed.

expires_at: 2027-12-31T00:00:00Z

tools: allow: [list_open_refunds, issue_refund] harmless: [list_open_refunds] # a read spends nothing effects: {list_open_refunds: read, issue_refund: transfer}

paths: pathless: [list_open_refunds, issue_refund] # these act on invoices, not files

egress: domains: [acme.example] recipients: [ops@acme.example] # a domain alone is every mailbox bind_recipients: true

budgets: value: ceilings: {refunds: "1000.00"} # dollars, for the whole session tracked: issue_refund: {arg: amount, budget: refunds}

Run clayseal policy lint policy.yaml before you ship. It catches the mistake that matters most: a tool that can spend money but debits no budget. On the file above it reports no errors and one warning (the ceiling is per session unless you bind a principal), which names a real decision you have not made yet.

Full reference: docs/POLICY.md.

See it stop the attack

From a checkout. examples/ has seven, each runnable with no key and no network:

python examples/02_the_proxy.py

tools advertised to the agent: list_open_refunds, issue_refund

(the server offers wire_funds; the policy does not grant it, so the agent is never told it exists)

ok issue_refund INV-001 paid INV-001 $900.00 DENY issue_refund INV-002 refused by policy: value_budget_exceeded ... DENY issue_refund INV-011 refused by policy: value_budget_exceeded DENY wire_funds ops-float refused by policy: tool 'wire_funds' is not in this session's policy

the server executed 2 call(s): list_open_refunds {} issue_refund {"amount": 900.0, "invoice": "INV-001"}

clayseal proxy: 2 allowed, 11 denied, 0 held for approval; withheld from the catalog: wire_funds

Read the last block. A JSON-RPC error proves the agent was told no; the server's own ledger proves the refund did not happen, and those are different claims. The same run on the command line, which is the deployment shape a deployment actually uses:

clayseal proxy --policy examples/refund.yaml -- python examples/refund_server.py

How it works

You give the gateway a policy file and a goal for the session. It seals the goal at the start, so nothing the agent reads later can widen what was approved. Every tool call then goes through one decision point before it runs.

flowchart LR

P["policy.yaml reviewed and diffed like any other file"] A["your agent"] G{{"Clay Seal"}} T["your tools or MCP server"] H["a person"] X["never runs"] S[("session state: running totals, where arguments came from")]

A -- "tool call" --> G P -. "sealed at session start" .-> G G -- "allow" --> T G -- "step up" --> H G -- "deny" --> X H -- "yes, once, for these arguments" --> T T -- "result" --> S S -. "the next call is judged against all of this" .-> G

That loop at the bottom is the whole idea. The gateway does not just check a call, it checks a call against everything the session has already done.

A call gets one of three answers:

• allow and the call goes to the tool
• step up and the call waits for a person to approve it
• deny and the call never runs

Step-up exists because a wrong refusal is expensive. An autonomous attacker is stopped just as hard by a call that waits for approval as by one that is refused, and a legitimate agent is not stopped permanently. Denial is reserved for cases with positive evidence of a problem.

The checks that produce those answers run in a fixed order, cheapest and strictest first, so a call refused early never reaches the expensive layers.

1. Floor. The flat rules: has the grant expired, is this tool allowed, is this path in scope, is this destination on the egress list, is there budget left. Fastest and most of the denials.
2. Declaration. If the agent states a plan up front, the plan is checked against the sealed goal before any of it runs.
3. Content. Checks that a declared write matches the goal, and inspects the payload of a write that has an effect. Produces a step-up, nev