ctrlrun Adds Execution Safety Controls for AI Agents

Summary

ctrlrun is an Apache-2.0 Python library and MCP gateway that sits between an AI agent’s decision and a consequential tool call. It evaluates each action against explicit policy and authority rules, allowing permitted calls, sending sensitive ones for human approval, and denying forbidden or unknown actions; there is no default allow. Approvals are bound to the exact action hash, expire, and can be consumed only once, so changing arguments or replaying a grant is refused. An effect key is reserved atomically across threads, processes, and, with Postgres, hosts, while an uncertain provider outcome is recorded as AMBIGUOUS rather than FAILED and blocks blind retries until reconciliation. Every attempt, including refusals, produces a chained JSON receipt containing the actor, action, decision, approval, effect, outcome, and policy hash. The included demo models refunds: amounts up to €500 run autonomously, amounts up to €10,000 require a person, and higher amounts are denied; it also demonstrates duplicate-effect, approval-mutation, concurrency, replay, and delegation-escalation failures. The library supports a Python decorator, an MCP gateway for tools in any language, and adapters for selected agent frameworks. It can use SQLite by default or Postgres across hosts, and includes a local verification command. The project explicitly says it does not detect prompt injection, cannot guarantee exactly-once behavior at an uncontrolled remote, does not roll back actions, and does not make receipts proof of authorship or certification.