Plugin capability grants

2 min readReferenceUpdated 2026-05-19

What you'll find here

The craik.plugin_capability_grant contract — runtime authority scoped to one plugin descriptor, with explicit operations, expiry, and approval state.

Least-privilege only.

A plugin that only needs read access receives only read, even if the underlying policy profile could allow broader authority. Grants must name explicit operations and a scoped target; broad operations such as * or all are rejected.

What it records

Task and plugin descriptor

Policy envelope

Capability name

Target paths and exclusions

Allowed operations

Grant status

Approval requirement & approver

Expiry

Evidence and receipt links

States

State

Required

Notes

allowed

expiry

If approval is required, approved_by is also required.

denied

no approver

Must not include approved_by.

expired

expires_at

Required.

approval_required

pending

Must set approval_required and must not include approved_by until a human or policy decision approves.

Runtime callers can use permits_operation(operation, at=...) to check whether a grant currently authorizes one operation. The helper returns false for denied, expired, and approval-required grants, for operations outside the grant, and for allowed grants past their expiry.

What's next

ReferencePlugin descriptorsThe descriptor a grant attaches to.ReferencePlugin probationHow new descriptors enter trusted use.ReferencePlugin receiptsThe receipt every plugin action produces.