ADR 0004 · Policy envelope shape

2 min readAcceptedRecorded 2026-05-01

What this ADR decides

That craik.policy_envelope is the stable governance boundary for a task-scoped action context. Capability grants are kept as separate records so they can be linked, expired, denied, or carried into receipts independently.

Status: Accepted.

Policy lives in artifacts, not in code paths. Every action threads a policy envelope id and (where applicable) grant ids.

Context

Craik coordinates agent work across file changes, shell commands, provider calls, memory writes, handoffs, channel ingress, and sandbox backends. Each action needs a stable record of actor, task, profile, grant requirements, redaction posture, and receipt obligations.

Decision

Component

Role

What it records

craik.policy_envelope

envelope

Policy profile · actor · task id · allowed capabilities · fail-open posture · receipt requirements · handoff requirements · redaction requirements.

Capability grant

separate record

Linked to the envelope · can be expired, denied, or carried into receipts independently.

Side-effect surfaces

enforcement

Provider loops · side-effect wrappers · channels · sandboxes · memory workflows must check the envelope and grants before executing.

Consequences

Policy behavior is explicit in artifacts rather than implicit in code paths. This makes receipts and handoffs auditable. The cost is that every new surface must thread policy envelope ids and grant ids through its contracts.

Alternatives considered

Alternative

Disposition

Why rejected

Embed policy decisions in task records

rejected

Policy can vary by actor and action; embedding it in tasks would conflate the two.

Runtime exceptions only

rejected

Would not produce durable evidence for reviewers or future agents.

Retraction: none active.

Retract this ADR if Craik replaces policy envelopes with a formally versioned external authorization service and migration path.

What's next

ReferencePolicy profilesStrict · trusted-local · automation — the shipped profiles.ReferencePolicy testsThe regression harness that keeps envelopes honest.ADR0005 · Receipts and handoffs as public contractsWhy every envelope decision produces durable evidence.