Put one door between your agent and its tools.

2 · A policy

Policies are data, not code.

One entry per action type: its tier, bounds, caps, effects, how to undo it, and whether it rehearses first. Changing what is allowed never means changing the engine. This is the transfer rule from the shipped examples.

policies:
  - action_type: payments.transfer
    tier: 2                              # runs without asking, up to its caps
    dry_run: false
    compensating_command: payments.reverse   # no undo, no auto-execution
    cost_param: amount_eur
    undo_window_seconds: 900
    caps:
      eur_day: 500.00
      eur_month: 5000.00
    effects: [money.egress]              # shares a budget and tier floor with every action with this effect
    bounds:
      required: [amount_eur, destination_account]
      strict_params: true                # any other parameter is refused
      numeric:
        amount_eur: { min: 0.01, max: 2000.00 }

4 · Approvals and the kill switch

Operator acts live behind a different key.

Listing, approving, granting and denying approvals, and the kill switch, need an admin key (ONEDOOR_ADMIN_KEYS). Decide keys cannot reach them.

curl -s localhost:8099/v1/approvals -H "Authorization: Bearer root"
curl -s -X POST localhost:8099/v1/approvals/1/approve -H "Authorization: Bearer root"   # either: approve and resume
curl -s -X POST localhost:8099/v1/approvals/1/grant   -H "Authorization: Bearer root"   # or: approve only; the proposer resumes later by reference
curl -s -X POST localhost:8099/v1/approvals/1/deny    -H "Authorization: Bearer root"   # or: deny
curl -s -X POST localhost:8099/v1/killswitch -H "Authorization: Bearer root" -H "Content-Type: application/json" -d '{"engaged":true}'

With the switch engaged, the same €40 transfer that was permitted a moment earlier:

{"decision":"denied","reason":"kill_switch","detail":"kill switch engaged; not proposed",...}

Releasing it reports whether the policy version changed while the door was shut (policy_change_while_engaged). Approve, grant and deny are alternatives: once one has acted, the others answer "not pending". In the shipped examples, payouts.schedule sets no dry_run: false, so approving it runs a rehearsal ("would have executed"), not a payout. A person cannot approve their own proposal, and an approval presented by reference can be used only by the caller that proposed the action. Set ONEDOOR_APPROVAL_WEBHOOK to send tier-3 proposals to a Slack-compatible webhook.

6 · With onetrace (optional)

Each gated step cites the decision that allowed it.

Set ONEDOOR_ISSUER to a name for your deployment and each decision that permits, denies or proposes carries a decision_ref (dry-runs and tier-0 reads carry none). Pass it to ot.decision() inside a step you declared as gated. Requires onetrace 0.5.0 or later; this was run with 0.6.0.

export ONEDOOR_ISSUER=https://payments.example/onedoor     # before starting the service

import json, uuid, urllib.request
import onetrace as ot

ONEDOOR = "http://127.0.0.1:8099"

def call(path, body):
    req = urllib.request.Request(ONEDOOR + path, data=json.dumps(body).encode(),
        headers={"Authorization": "Bearer dev", "Content-Type": "application/json"})
    with urllib.request.urlopen(req) as r:
        return json.load(r)

@ot.stage("approve_payment", instrument=ot.pkg("pay-invoice", "onetrace", kind="tool"))
def approve_payment(invoice, amount_eur):
    answer = call("/v1/decide", {"request_id": str(uuid.uuid4()), "action_type": "payments.transfer",
        "params": {"amount_eur": amount_eur, "destination_account": "acct-1"},
        "source": "llm", "rationale": f"pay {invoice}"})
    ot.decision(answer["decision_ref"])          # recorded in this step's receipt
    if answer["decision"] != "permitted":
        raise RuntimeError(f"onedoor said {answer['decision']}: {answer['reason']}")
    # ... move the money here ...
    call("/v1/report", {"intent_audit_id": answer["intent_audit_id"], "outcome": "success"})
    return {"paid": invoice}

@ot.run(stages=["approve_payment"], gated_stages=["approve_payment"])
def main(invoice, amount_eur):
    print(approve_payment(invoice, amount_eur))

if __name__ == "__main__":
    main("INV-0001", 40.00)

Run it, export onedoor's ledger, and verify the run against the export:

python pay.py
python -m onedoor.export --store onedoor.db --out decisions.jsonl     # writes decisions.jsonl.sha256 beside it
onetrace-verify --require-artifacts --decisions decisions.jsonl runs/<run id>

[PASS   ] decisions: gated steps cite a decision -- 1 gated step(s), each citing a decision
[PASS   ] decisions: references are well formed -- 1 reference(s), each a well-formed onedoor-decision-ref/1
[PASS   ] decisions: a step that acted cites a permitting decision -- 1 acting step(s), each citing a permitting decision
[NOT-RUN] decisions: the permit covers the recorded action -- no permit recorded
[PASS   ] decisions: the decision is in the export -- 1 reference(s), each matching a row in the export by digest

59 pass, 0 fail, 3 not-run  ->  PASS

A step that acts on a deny, or a gated step that cites nothing, fails its row by name. A reference can also be checked on its own, with onedoor alone: python -m onedoor.decision_ref check --export decisions.jsonl --ref ref.json answers matches, digest mismatch, not in export, malformed ref or export damaged, each with its own exit code.

8 · Other surfaces

The same checks, wherever your agent calls tools.

Next: how it works, the check order and what each record proves.