ctrlrun 0.6.0

The last check before an AI agent does something it can't undo.
Autonomy belongs to the action, not the agent.
A consequential action happens at most once, exactly as approved, and leaves a receipt — and when the outcome is unknown, CTRLRun says so instead of guessing.

A Python library that sits between the decision to act and the call that acts.
Runs in production on a single file, or on Postgres across hosts. Apache-2.0.

The refund that happened twice

An agent refunds €500. The call reaches the provider and commits. The reply is lost on the way back, so the agent sees an error — and does what every retrying client does. The customer is refunded twice, and nothing in the stack noticed.

The bug is not the retry. It is that the agent had no way to tell this failed from I do not know what happened. Retry libraries, agent frameworks and tool loops collapse those two into one, and a write that may already have committed is retried as though it certainly had not.

CTRLRun does not collapse them. A lost reply is AMBIGUOUS, never FAILED, and a retry against an AMBIGUOUS effect is refused — until a human, or a reconcile hook, says what happened.

pip install ctrlrun && ctrlrun demo

No Python to hand? Break a protected action in your browser: one refund under one policy on the released wheel, in the tab, with nothing sent anywhere. Approve €2,000, execute €5,000, lose a reply, retry — and read what refused you.

What ctrlrun demo shows

Five ways an agent action goes wrong, and what stops each one, in process, in under a second, with no network and no external service. The animation above is the first two. In the first, the refund commits at the remote, the reply is lost, the agent retries, and the retry is refused — remote refund calls: 1, so the customer was refunded once and not twice, and nothing but a human resolving the effect moves it on. In the second, a human approves a €2,000 refund, the agent executes €5,000 under that approval, and the approval matches nothing but the action the human saw.

$ ctrlrun demo
CTRLRun demo — five ways an agent action goes wrong, and what stops it.
Policy: refunds up to €1,000 are autonomous, up to €10,000 need a human, above that are denied.

1. Duplicate effect after a lost response

   refund €500  →  remote commits  →  response lost  →  effect: AMBIGUOUS
   agent retries the same refund
   ✗ BLOCKED — effect may already have committed; blind retry refused
   remote refund calls: 1
   only a human moves it on:  ctrlrun resolve refund:txn_1 --committed|--failed

2. Approval mutation

   agent proposes refund €2,000  →  human approves apr_0aa78e0380ba55d77a601dc782f57095 (bound to the action hash)
   agent executes refund €5,000  →
   ✗ BLOCKED — approved action ≠ requested action (mismatch)

3. Concurrent agents, same effect

   Agent A  reserve refund:txn_123  →  ACQUIRED  →  executes
   Agent B  reserve refund:txn_123  →
   ✗ BLOCKED — already reserved (in_progress)

4. Approval replay

   approval apr_dbc8bc6f06690cdf2e2c55a4e591ef3b used once  →  consumed
   same approval presented again                            →
   ✗ BLOCKED — single-use approval already consumed

5. Authority escalation

   human €100,000 delegable  →  finance agent €25,000  →  support agent €2,000
   support agent's grant: dlg_5f8d41938a3f29972d5489d676cd9edb
   support agent requests €50,000  →
   ✗ BLOCKED — outside the delegated grant (authority_constraint)
   remote refund calls: 0
   finance agent tries to delegate €50,000 under its own €25,000  →  refused (containment: constraints)
   support agent requests €1,500  →  authority permits it, and the policy asks a human (apr_f86eca24dd80206ab5189ccb1b62aa55)
   two axes, and an action needs both: the stricter of the pair wins

Receipts (8): .ctrlrun/demo/receipts.jsonl
Events:       .ctrlrun/demo/events.jsonl

Read them:    CTRLRUN_STATE=.ctrlrun/demo/state.db ctrlrun receipts

Protect your first action

Wrap the call that has the consequence, and let one YAML file say how much autonomy it gets. In a directory with a ctrlrun.yaml (ctrlrun init writes a starter, and the starter already says a namespace delete needs a human):

ctrlrun init

import ctrlrun


def kubectl(*args: str) -> str:  # stand-in for your real client
    return " ".join(args)


@ctrlrun.protect("k8s.delete_namespace", effect="namespace:{cluster}:{name}")
def delete_namespace(cluster: str, name: str) -> str:
    return kubectl("delete", "namespace", name, "--context", cluster)


with ctrlrun.context(agent="deploy-agent"):
    try:
        delete_namespace(cluster="prod-eu", name="checkout")
    except ctrlrun.ApprovalRequired as pending:
        print(f"a human decides:  ctrlrun approve {pending.request_id}")
    else:
        raise SystemExit("the delete ran without a human; the policy is not in force")

The human runs ctrlrun approve <request id> and the agent calls again inside ctrlrun.with_approval(request_id). The approval matches this cluster and this namespace and nothing else; effect names the consequence, so the same delete from a second worker is refused. The same starter file holds a refund by amount, and what it does with one is the rest of the product in six lines:

Protect your first action, end to end with the outputs · Try it in your browser · Policy YAML reference · Cookbook: refunds, deploys, IAM, deletions, email, MCP, each a recipe that runs.

The problem

Agents are getting write access to the real world. The hard part is not deciding whether a tool call is allowed. It is what happens at the boundary between intending an effect and having caused one.

CTRLRun owns that boundary. It sits between the decision to act and the call that acts, and it is the last check before the call goes out.

How it works

Every protected call, whichever way it arrives, goes through the same six steps:

  normalize  →  decide  →  approve  →  reserve  →  execute  →  record

1. Normalize. The call becomes an Action: a name, canonical arguments (sorted keys, no floats), a resource, the principal and the environment. Its SHA-256 is the action hash.
2. Decide. Authority first (may this principal propose this action at all?), then policy (how much autonomy does this action have?). Unknown action, missing policy or missing principal is deny.
3. Approve. If the decision is approve, a human answers against the action hash. The approval is single-use, expires, and matches nothing but that exact action.
4. Reserve. The effect key — refund:txn_1, namespace:prod-eu:checkout — is reserved in one atomic write. A second caller, in another process or on another host, is refused.
5. Execute. Your function runs. Only NotExecuted, raised by you, means FAILED. Any other exception, and every timeout, means AMBIGUOUS, and an AMBIGUOUS effect blocks a blind retry until a human or a reconcile hook says what happened.
6. Record. A portable JSON receipt: who, what, decision, approval, effect key, outcome, and the hash of the policy that decided it, chained to the receipt before it.

Three ways to use it

You probably do not need an adapter. @protect covers anything running in this process: a raw model call, a LangChain tool, a hand-rolled loop, a cron job. The gateway covers anything that reaches its tools over MCP, in any language. Most readers need the decorator and should not look for an adapter; an adapter buys exactly one thing, and it is described last.

The decorator

Shown above in Protect your first action: @ctrlrun.protect(name, effect=...) around the call that acts, ctrlrun.context(agent=...) around the caller, ctrlrun.with_approval(request_id) to present a grant. It needs nothing beyond pip install ctrlrun.

The gateway

No agent changes and no server changes, in any language. Point the MCP client at the gateway instead of at the tool server:

before    agent  ──▶  MCP server
after     agent  ──▶  CTRLRun gateway  ──▶  MCP server

pip install "ctrlrun[gateway]"
ctrlrun gateway --upstream http://localhost:8000/mcp --alias acme --principal refund-agent

Tools become actions named mcp.<alias>.<tool>, decided by the same policy. A tool call has no decorator to carry its effect and resource templates, so they are declared in the policy:

schema: ctrlrun.policy/v2

actions:
  mcp.acme.create_refund:
    effect: "refund:{payment_id}"
    resource: "payment:{payment_id}"
    decision: approve
  mcp.acme.list_payments:
    decision: allow

Everything but tools/call is relayed untouched. ctrlrun.dev/mcp/overview is the MCP section of the documentation: the gateway, this documentation as an MCP server, and what is planned. A lost response over the wire blocks the retry exactly as it does in process, and the gateway prints, on the line that starts it, every action in your policy that has no effect: template, because a write with no effect key is exactly the configuration this exists to prevent.

Adapters

An adapter exists for one reason: to route an approve decision through the framework's own interrupt instead of raising ApprovalRequired past your graph. A human answers where they already answer, and one core provider writes the grant through the same calls ctrlrun approve makes. There is never a second place to say yes.

$ pip install ctrlrun-langgraph

You build the Control with your policy, store, identity provider and authority document, and hand it over: an adapter never constructs one and never supplies a principal. Adapters ship on their own version line, adapters-langgraph-1.0 and never 0.6.1, because an adapter breaks when its framework makes a breaking release, which is not a kernel event. docs/adapters.md has the three ways in and how to write one for a framework not listed here.

Write down what the agent may do

One file. The rule is the same in every domain: cheap to undo is autonomous, anything that leaves the building needs a human, money is by amount with both ends bound, and anything that destroys the evidence is not an agent action at any size. Unknown actions are denied; there is no default-allow.

schema: ctrlrun.policy/v2

actions:
  # Cheap to undo: autonomous.
  crm.update_record:
    effect: "crm:{record_id}:{field}"
    decision: allow
  k8s.rollout_restart:
    effect: "restart:{cluster}:{deployment}"
    decision: allow

  # Leaves the building: a human, every time it reaches somebody or something outside.
  email.send:
    effect: "email:{message_id}"
    rules:
      - when: { to_domain_eq: "example.com" }
        decision: allow
      - decision: approve
  iam.grant_role:
    effect: "grant:{principal}:{role}"
    rules:
      - when: { role_in: [reader, viewer] }
        decision: allow
      - decision: approve
  k8s.delete_namespace:
    effect: "namespace:{cluster}:{name}"
    decision: approve

  # Money: by amount, in integer minor units, with both ends bound. An upper bound alone is
  # not a range, and a refund of a negative amount is a charge.
  stripe.refund:
    effect: "refund:{payment_id}"
    rules:
      - when: { amount_gte: 0, amount_lte: 50000 }       # up to €500.00: autonomous
        decision: allow
      - when: { amount_gte: 0, amount_lte: 500000 }      # up to €5,000.00: a human
        decision: approve
      - decision: deny

  # Destroys the evidence: denied, whoever asks.
  stripe.delete_customer:
    decision: deny
  audit.log.delete:
    decision: deny

Amounts are integer minor units; floats are rejected outright, because 0.1 and 0.10 are the same money and different hashes. The policy cannot see who is asking — deliberately, since v0.1: agent_eq and every other principal-addressing condition is refused at load. Who may ask is the second axis, authority:. It is opt-in, and then fail-closed: a policy with no authority: section behaves exactly as before, and the moment one exists every principal needs a grant and no grant means denied. A grant carries no decision:; the two axes are evaluated separately, authority first, and combine as the stricter of the two. A principal holding a delegable grant can narrow it at runtime with ctrlrun delegate, a delegation is valid only if it is provably a subset of its parent on every dimension, at creation and again at every evaluation, omitting a dimension the parent constrains is rejected rather than inherited, and ctrlrun revoke cuts a chain of any depth with one write. docs/authority.md has it in plain language.

The nine files under examples/policies/ are starting points for payments, devops, HR, legal, security and others. Adapt them; none is a drop-in.

Roll it out with mode: observe first. One top-level line runs every real decision against real traffic and records what would have been blocked, without blocking anything, and ctrlrun stats gives you the numbers before you enforce them. It is not a dry run: it executes.

Prove it holds in your setup

Everything above is proven by this repository's tests against this repository's configurations. What you deploy is your policy, your grants and your store, so ctrlrun verify runs the kernel's own failure scenarios against the configuration in front of it, in a scratch store, with fake executors, and no network. Your .ctrlrun/state.db is byte-identical before and after.

$ ctrlrun verify
CTRLRun verify — ctrlrun 0.6.0, catalogue ctrlrun.guarantees/v2
policy     examples/authority/payments.yaml (ctrlrun.policy/v3, mode: enforce)
authority  same document, 3 grants
store      sqlite, scratch (created and destroyed for this run)

G1   mutated approval refused         PASS  stripe.refund
G2   replayed approval refused        PASS  stripe.refund
G3   duplicate effect refused         PASS  stripe.refund
G4   one winner under concurrency     PASS  stripe.refund (8 processes)
G5   ambiguous blocks a blind retry   PASS  stripe.refund
G6   unknown action refused           PASS
G7   no principal refused             PASS  stripe.refund
G8   expired authority refused        PASS  head-of-support
G9   delegation cannot escalate       PASS  head-of-support (6 of 6 dimensions)
G10  unknown exception is ambiguous   PASS  stripe.refund
G11  an altered receipt is detected   PASS  stripe.refund

11/11 declared guarantees pass. 0 not applicable.

Not applicable is not a pass. A policy with no approve rule cannot exercise the approval-binding guarantees, and one with no effect: templates cannot exercise the effect guarantees, so each is reported N/A with the reason, excluded from the denominator and listed separately: 6/6 (5 not applicable), never 11/11. There is no flag that folds one into the count. The same command against a ctrlrun.policy/v1 document with no templates and no grants:

$ CTRLRUN_CONFIG=examples/policies/payments.yaml ctrlrun verify
CTRLRun verify — ctrlrun 0.6.0, catalogue ctrlrun.guarantees/v2
policy     examples/policies/payments.yaml (ctrlrun.policy/v1, mode: enforce)
authority  none
store      sqlite, scratch (created and destroyed for this run)

G1   mutated approval refused         PASS  stripe.create_payout
G2   replayed approval refused        PASS  stripe.create_payout
G3   duplicate effect refused         N/A   no action declares an `effect:` template
                                            (in a `ctrlrun.policy/v1` document the template lives in
                                            the @protect decorator, which verify does not read)
G4   one winner under concurrency     N/A   no action declares an `effect:` template
G5   ambiguous blocks a blind retry   N/A   no action declares an `effect:` template
G6   unknown action refused           PASS
G7   no principal refused             PASS  invoice.read
G8   expired authority refused        N/A   no authority section
G9   delegation cannot escalate       N/A   no authority section
G10  unknown exception is ambiguous   PASS  invoice.read
G11  an altered receipt is detected   PASS  invoice.read

6/6 declared guarantees pass. 5 not applicable: G3, G4, G5, G8, G9.

The badge at the top of this page means the declared guarantees pass: every guarantee this configuration can exercise was exercised, and none failed. It does not mean secure, safe, compliant, certified or audited, and docs/verify.md says on the same screen what verify cannot see: your executors, your reconcile hooks, where you put the decorator, your deployment, and whether your policy is the right policy. There is a GitHub Action:

      - uses: CTRLRun/ctrlrun@v0.6.0
        with:
          policy: ctrlrun.yaml

The ref pins the action's steps and not the package they install: install defaults to ctrlrun, which is whatever PyPI has that day. Add install: ctrlrun==0.6.0 to pin the tool as well as the workflow.

What it guarantees, and what it can't

The six guarantees, and which of the three ways in carries each:

It guarantees, with a test behind every line in docs/CLAIMS.md, and docs/how-this-is-built.md says how those tests came to exist:

• An approval is bound to the exact action a human saw, is used once, expires, and is refused for a mutated or replayed action.
• One logical effect executes at most once per intent, across threads, processes and hosts. On SQLite that is BEGIN IMMEDIATE; on Postgres (pip install "ctrlrun[postgres]") it is a unique index on the effect key and compare-and-set updates whose row counts are checked, the same StateStore protocol, extended by nothing, and graded by the suite written for SQLite.
• It will not knowingly execute the same logical effect twice, and will never treat an unknown outcome as a failure. Only NotExecuted means FAILED; a timeout, a lost reply, a lost connection during COMMIT and every unexpected exception are AMBIGUOUS, and the store re-reads the row to find out which. A crashed worker's effect stays AMBIGUOUS until a human runs ctrlrun resolve or a reconcile hook asks the remote what happened, the only thing besides a human permitted to move a record out of AMBIGUOUS, and only in the direction its answer points.
• Unknown action, missing policy, malformed policy, missing principal, missing or mismatched approval and inconsistent state are all deny. No flag makes a consequential action permissive by default, and verify has no flag that relaxes a check.
• With authority: on, every principal needs a grant, delegation cannot widen one, and ctrlrun revoke cuts a chain with one write. Identity is consumed, never invented: pip install "ctrlrun[identity]" verifies a bearer token against a JWKS or a pinned key and maps the verified claims onto a principal. CTRLRun issues no credential and defines no identity format.
• Every executed action leaves a portable JSON receipt, and every receipt records which policy decided it: the policy's declared version: and a hash of its canonical content, so a receipt from six months ago says what the rules were rather than what they are now. Where a policy changes between a human approving and an agent executing, the approval is re-checked against the policy in force at execution.
• Each receipt carries the hash of the one before it. An edit, a deletion from the middle, a reordering: each is detected and named, and ctrlrun receipts --verify-chain reports it by seq.
• The schema is versioned and migrations are automatic at open, forward-only, with no flag that opens a database un-migrated. An older binary against a newer schema refuses immediately.
• Releases carry PyPI provenance attestations from GitHub Actions: trusted publishing, no API token anywhere, and an attestation on every distribution naming the workflow that built it.
• ctrlrun approve, deny, resolve, inspect, receipts, effects and stats work from the shell against any store, and ctrlrun mcp-operator exposes those same read and write commands over MCP, so the person who has to answer an approval can answer it from the assistant they are already talking to. It authenticates who answered and records it; it does not check that they were entitled to.
• ctrlrun scan reads a Python tree and a policy document and reports the consequential call sites and policy entries CTRLRun is not covering — the gap between installed and in the path. It reports what it found where it looked, says on every run what it misses by construction, and has no score, no percentage and no badge: a number that improves when the vocabulary is shortened is a number that will be.
• WebhookApprovalProvider sends an approval request to a webhook, such as Slack, and takes the answer back through the same grant calls. pip install "ctrlrun[otel]" exports one OpenTelemetry span per action, one span event per step, and argument values stay out of it unless you ask for them. Receipts in a ctrlrun.policy/v4 document can cite the controls: an action satisfies, and a rule can condition on the data: labels present in an action's arguments.

It can't, and does not claim to:

• CTRLRun cannot guarantee exactly-once execution against external systems it doesn't control. It refuses to knowingly act twice; whether a remote acted is a fact only the remote holds.
• CTRLRun is not a transaction manager: it rolls nothing back and never pretends a remote system's write is undone.
• The receipt chain detects alteration, and alteration is not authorship. Receipts are not signed, the chain is no evidence of who wrote one, and it is not tamper-proof: it does not survive an administrator who can rewrite every row including the chain head, and erasing the end of the log costs two statements. docs/THREAT_MODEL.md states what remains open.
• ctrlrun verify cannot see your executors. An executor that raises NotExecuted after the remote acted turns the one retryable exception into a licence to act twice, and nothing here can check that for you.
• CTRLRun does not detect prompt injection, and nothing here reads the agent's instructions to decide whether they were poisoned. What the table above claims is narrower and is the part that holds: an injected instruction still has to get past a grant the agent does not hold, an amount that needs a human, and an approval bound to the recipient the human saw. That is containment of the consequence, not detection of the cause.
• It does not host models, plan, prompt, retrieve, route, remember or orchestrate. It is not a guardrail library, an IAM system, a workflow engine or a compliance product, and it makes no claim about any standard: docs/OWASP-AGENTIC-TOP10.md is a reading of somebody else's taxonomy against the guarantees, and names the four entries it does not address.

If an agent only reads and answers, you don't need CTRLRun. The moment it can send, pay, refund, delete, deploy, grant, revoke, approve, submit, purchase or cancel, you do.

Running it in production

SQLite is the default and is production-grade on one host. A file, no server, no ops — and the concurrency guarantee is held by BEGIN IMMEDIATE and a unique constraint, across processes and not merely across threads. Postgres is for many hosts: pip install "ctrlrun[postgres]", one URL, the same StateStore protocol extended by nothing, graded by the suite written for SQLite. Choose by how many machines write, not by how serious you are.

• Version 0.6.0, on PyPI, Python 3.11 and later.
• 4,163 tests, every version specified before it was written and every requirement mutation-tested.
• 11 guarantees you can check in your own setup, with ctrlrun verify against your policy, on your store's backend, in a scratch store it creates.
• One host: a file. SQLite, no server, no ops. Many hosts: Postgres, the same guarantees, graded by the same suite.
• Soaked for 20m 0s on postgres: 889,735 actions, 0 unattributed ambiguous outcomes, positive control fired. Nothing here establishes what only accumulates over days. What it does not establish.
• Each receipt carries the hash of the one before it, so an alteration is detected and named.
• Apache-2.0, and the enforcement kernel stays open source. Releases carry PyPI provenance attestations from GitHub Actions.

Not yet:

• No external security audit. (planned for v0.8 or v0.9)
• No third-party review of the kernel. (every review so far was run inside this project)
• No sector packs. (the policy templates are starting points, not a product)

ctrlrun.dev/production/index is the whole section: choosing a store, what reservation does under a lost COMMIT, migrations, recovery after a crash, the receipt chain, the soak, and what to watch once it is running.

Beyond one process

Every guarantee before 0.6 was a guarantee about one process holding one SQLite file. BEGIN IMMEDIATE is a whole-database write lock on a local file; take the file away, put the store on another host, and one effect, once has to be re-earned by a different mechanism.

• Postgres — pip install "ctrlrun[postgres]", one URL. The same StateStore protocol, extended by nothing, graded by the suite written for SQLite rather than one written for it.
• Schema migrations, automatic at open and forward-only, with no flag that opens a database un-migrated. An older binary against a newer schema refuses immediately.
• Recovery after a crash — what a restarted worker may conclude, and what nothing sweeps.
• Receipt integrity — each receipt carries the hash of the one before it, so an edit, a deletion from the middle or a reordering is detected and named by seq. It detects alteration, which is not authorship: receipts are not signed.
• Policy versioning — every receipt records the policy that decided it, so a receipt from six months ago says what the rules were rather than what they are now.
• A store conformance suite, so a second backend is graded rather than described.

CHANGELOG.md has the entry, including the two subcommands that ride along in this release without being part of the milestone: ctrlrun scan and ctrlrun mcp-operator.

Documentation

ctrlrun.dev is the documentation: concepts, guides, a cookbook, the reference, and a browser demo that runs ctrlrun demo with no install.

License

Apache-2.0. The enforcement kernel is and will remain fully open source.