Python API - CTRLRun

The names below are the ones the specifications freeze: ctrlrun.__all__, the entry points of the extras, and ctrlrun.verify.run. Each page is rendered from the docstring; a name with no docstring fails a test, so every page has one.

Name	Kind	Summary
`ctrlrun.Action`	class	A proposed agent action: what, with which arguments, by whom, on what.
`ctrlrun.ActionDenied`	class	The action may not run. `reason` says why, e.g. `unknown_action` (SPEC-v0.1 §3.4).
`ctrlrun.AmbiguousEffect`	class	The outcome of this effect is unknown; only a human may resolve it (SPEC-v0.1 §5.4).
`ctrlrun.Approval`	class	A human’s grant, bound to one `action_hash` (SPEC-v0.1 §4.1).
`ctrlrun.ApprovalAnswer`	class	A human’s answer, and who gave it (SPEC-v0.5 §2.2, §3.4).
`ctrlrun.ApprovalMismatch`	class	The presented approval does not authorize this action (SPEC-v0.1 §4.2).
`ctrlrun.ApprovalProvider`	class	How a human is asked, and how the answer comes back (SPEC-v0.1 §4.3).
`ctrlrun.ApprovalRequest`	class	A pending question for a human: may this exact action run? (SPEC-v0.1 §4.1)
`ctrlrun.ApprovalRequired`	class	The action needs a human. `request_id` is what `ctrlrun approve` takes (SPEC §4.3).
`ctrlrun.ApprovalTimeout`	class	Nobody answered the approval request in time (SPEC-v0.1 §4.3).
`ctrlrun.Authority`	class	The `authority:` section, loaded and evaluable (SPEC-v0.3 §4).
`ctrlrun.AuthorityDenied`	class	The principal holds no grant that covers this action (SPEC-v0.3 §4.3).
`ctrlrun.AuthorityEscalation`	class	A delegation that may not exist: it is not contained in its parent (SPEC-v0.3 §5.3).
`ctrlrun.AuthorityResult`	class	What the authority axis decided, and which grant it decided on (§4.8).
`ctrlrun.CTRLRunError`	class	Base class for every error raised by CTRLRun.
`ctrlrun.Condition`	class	One `<argument>_<op>: operand` test against an action’s arguments (SPEC-v0.1 §3.2).
`ctrlrun.Control`	class	Policy, state and evidence composed around a single action (SPEC-v0.1 §8).
`ctrlrun.Decision`	class	What may happen to an action: exactly three outcomes in v0.1 (SPEC-v0.1 §3.3).
`ctrlrun.Delegation`	class	A grant created at runtime by a principal who already holds one (SPEC-v0.3 §5.1).
`ctrlrun.DelegationRecord`	class	One row of the `delegations` table (SPEC-v0.3 §5.2).
`ctrlrun.DuplicateEffect`	class	This logical effect already happened, or is happening now (SPEC-v0.1 §5.4).
`ctrlrun.EffectKeyError`	class	An effect template cannot be resolved to a key (SPEC-v0.1 §5.1).
`ctrlrun.EffectRecord`	class	What a StateStore holds for one effect key (ARCHITECTURE §5).
`ctrlrun.EffectState`	class	Where a logical effect stands (SPEC-v0.1 §5.2).
`ctrlrun.Event`	class	One ordered step in the life of an action (SPEC-v0.1 §6.2).
`ctrlrun.EventSink`	class	Somewhere a copy of every `Event` and `Receipt` goes (SPEC-v0.2 §4.1).
`ctrlrun.FrameworkInterrupt`	class	One framework’s human-in-the-loop primitive, and nothing else (SPEC-v0.5 §2.1).
`ctrlrun.Grant`	class	One permission: this subject may propose these actions, under these limits (§4.2).
`ctrlrun.HeaderIdentityProvider`	class	The principal named by a trusted HTTP header (§3.3).
`ctrlrun.IdentityContext`	class	What a provider is told about the call it is resolving a principal for (§3.1).
`ctrlrun.IdentityError`	class	A credential was offered and rejected (SPEC-v0.3 §3.2).
`ctrlrun.IdentityProvider`	class	Resolves the principal for one action (SPEC-v0.3 §3.1).
`ctrlrun.InMemoryStateStore`	class	Everything held in process memory: for tests and `ctrlrun demo`.
`ctrlrun.InterruptApprovalProvider`	class	An `ApprovalProvider` whose `wait()` routes through a framework’s own primitive.
`ctrlrun.InvalidArgument`	class	An argument cannot be accepted as given.
`ctrlrun.JSONLEventSink`	class	The JSONL half of the evidence: two append-only files in one directory (SPEC §6).
`ctrlrun.LocalApprovalProvider`	class	Requests go to the StateStore; `wait()` polls it (SPEC-v0.1 §4.3).
`ctrlrun.MissingDependency`	class	An optional extra is not installed (SPEC-v0.2 §1.1, §11).
`ctrlrun.NotExecuted`	class	Raised by an executor to assert the remote side did nothing (SPEC-v0.1 §5.5).
`ctrlrun.PendingApproval`	class	What the framework’s interrupt is handed, and the only thing it is (SPEC-v0.5 §2.3).
`ctrlrun.Policy`	class	Action-level autonomy policy: which actions may run, and under which conditions.
`ctrlrun.PolicyError`	class	The policy is missing, unreadable, or malformed. Raised at load time (SPEC-v0.1 §3.4).
`ctrlrun.Principal`	class	Who is acting: an agent, optionally on behalf of a human.
`ctrlrun.Receipt`	class	Portable evidence of one action that reached a terminal state (SPEC-v0.1 §6.1).
`ctrlrun.ReconcileOutcome`	attribute	What a `reconcile` hook may answer about an effect key (SPEC-v0.2 §2).
`ctrlrun.SQLiteStateStore`	class	Approvals, effects and evidence in one SQLite file (ARCHITECTURE §5).
`ctrlrun.SchemaMismatch`	class	A store met a database it does not recognise, in either direction (SPEC-v0.6 §3.3).
`ctrlrun.ScriptedApprovalProvider`	class	A human replaced by a fixed script: for tests and `ctrlrun demo` (SPEC-v0.1 §4.3).
`ctrlrun.StateStore`	class	Durable state behind a `Control` (SPEC-v0.1 §5.3): approvals, effects, evidence.
`ctrlrun.StaticIdentityProvider`	class	A fixed principal, for development, tests and single-tenant demonstrations (§3.3).
`ctrlrun.Subject`	class	Who a grant is addressed to: an agent pattern, a user pattern, or both (§4.2).
`ctrlrun.Suspended`	class	Raised by an executor: the remote asked for something before it will finish.
`ctrlrun.WebhookApprovalProvider`	class	Notify a human system on `APPROVAL_REQUESTED`, and let it answer (SPEC-v0.2 §7).
`ctrlrun.action_hash`	function	Return the action hash used to bind approvals to an exact action (SPEC-v0.1 §2.3).
`ctrlrun.banner`	function	Log SPEC-v0.3 §6.5’s observe banner, once per `Control`. An adapter MUST call it (§3.6).
`ctrlrun.canonical_bytes`	function	The canonical form of an arbitrary mapping: UTF-8 JSON, sorted keys, no whitespace.
`ctrlrun.canonicalize`	function	Return the canonical form of an Action: UTF-8 JSON, sorted keys, no whitespace.
`ctrlrun.context`	function	Bind the principal for calls made inside the block.
`ctrlrun.needs_approval`	function	Does this call need a human? For a framework that asks before it invokes (SPEC-v0.5 §3.5).
`ctrlrun.parse_conditions`	function	Parse a `when:`-shaped mapping into conditions, keyed by the raw condition key.
`ctrlrun.protect`	function	Bind a function to an action name: every call becomes a decided, recorded Action.
`ctrlrun.with_approval`	function	Present a granted approval to the calls made inside the block (SPEC-v0.1 §4.3).
`ctrlrun.postgres.PostgresStateStore`	class	Approvals, effects and evidence in a Postgres schema (SPEC-v0.6 §4).
`ctrlrun.otel.OTelEventSink`	class	Export every `Event` and `Receipt` as OpenTelemetry spans (SPEC-v0.2 §8).
`ctrlrun.jwt_identity.JWTIdentityProvider`	class	Verify a bearer JWT and map its verified claims onto a `Principal` (SPEC-v0.3 §3.4).
`ctrlrun.acs.AcsControlHook`	class	Answer ACS `steps/*` hooks with CTRLRun’s decisions and outcomes.
`ctrlrun.gateway.serve`	function	Run a gateway in front of one upstream MCP server (SPEC-v0.2 §6.1).
`ctrlrun.verify.run`	function	Run the applicable guarantees against this configuration and report (§9.1).
`ctrlrun.conformance.run`	function	Drive every suite through `adapter` and report what each came to (SPEC-v0.5 §5).
`ctrlrun.conformance.store.run`	function	Drive every case against `backend` and report what each came to (SPEC-v0.6 §2).

Next

CLI reference.
Get started · Why.

Related topics

Action Approval Event Grant Policy