Skip to content

keelgate.approvals

Stability of each symbol (stable or provisional) is listed in the API contract. Narrative and semantics are in the integration contract.

Human-in-the-loop approval requests and the queue that serves them.

The REST surface lives in keelgate.approvals.rest and needs the server extra; it is not imported here so the core stays dependency-light.

ApprovalError

Bases: Exception

Base class. code is stable and safe to show to a model or an API client.

ApprovalExpiredError

Bases: ApprovalError

The approval request expired before it was decided or used.

ApprovalNotAuthorisedError

Bases: ApprovalError

The approver may not decide this request: wrong tenant, tier too low, or the requester itself.

ApprovalNotFoundError

Bases: ApprovalError

No such request for this tenant. Another tenant's request is reported the same way.

ApprovalNotPendingError

Bases: ApprovalError

The request was already decided.

ApprovalNotUsableError

Bases: ApprovalError

The request exists but cannot back this execution (wrong state or action).

ApprovalQueue

The human-in-the-loop approval queue (SQLite-backed).

Requests are submitted with an evidence bundle, decided by a human of sufficient tier (never the requester), and spent exactly once for exactly the arguments that were approved.

consume 

consume(
    *,
    tenant_id: str,
    request_id: str,
    agent_id: str,
    tool_name: str,
    args_hash: str,
) -> ApprovalRequest

Spend an approval, once, for exactly this agent, tool and arguments.

ApprovalRequest

Bases: BaseModel

A call parked for a human: the exact arguments' hash, the tier required, the evidence bundle, and the request's status and decision.

signoff_code property 

signoff_code: str

Short code derived from the evidence, echoed back for EXPLICIT_SIGNOFF.

ApprovalSignoffError

Bases: ApprovalError

An explicit sign-off was required and the code supplied was missing or wrong.

ApprovalStatus

Bases: StrEnum

Where an approval request is: pending, approved, rejected, expired or consumed.

ApprovalTier

Bases: StrEnum

How much human attention an action needs.

AUTO: no human; the policy allowed it outright. ONE_CLICK: one authorised approver confirms. EXPLICIT_SIGNOFF: one authorised approver confirms and echoes a code derived from the evidence, so approval cannot be a blind click.

covers 

covers(required: ApprovalTier) -> bool

True if an approver cleared for self may decide a required request.

Approver

Bases: BaseModel

A human cleared to decide requests in one tenant up to max_tier.

EvidenceBundle

Bases: BaseModel

What an approver needs to decide, and what their decision is bound to.

EvidenceSource

Bases: BaseModel

A source cited in an approval's evidence: where it came from, when it was retrieved, and a hash of its content.

action_hash 

action_hash(tool: str, args: dict[str, Any]) -> str

Hash of exactly what will run. An approval is bound to this value.

sanitize_for_display 

sanitize_for_display(text: str) -> str

Strip control characters so model-derived text cannot drive a terminal.