Docs / Reference

Policy states

Policy states communicate whether a capability is open, restricted, approval required, audited, blocked, or revoked.

Plain English

Policy state is the visible rule status before a caller asks the host to act.

Why it exists

Independent callers need to distinguish safe execution from expected denial, audit, approval, or blocked behavior.

Formal definition

Policy states are host-declared and host-enforced governance labels that shape invocation outcomes and evidence.

Concrete example

Ground the concept before the schema.

manager_approval is approval_required for schedule_technician.

Policy boundary

Approval required

manager_approval

A manager must approve technician scheduling before the host returns a confirmed appointment.

outcome.json
json
{  "invocation_id": "inv_session_abc_001",  "capability_id": "schedule_technician",  "capability_version": "1.0.0",  "correlation": { "correlation_id": "session-abc" },  "outcome": "denied",  "success": false,  "data": null,  "error": null,  "denial": {    "code": "approval_required",    "message": "manager_approval must approve before execution.",    "retryable": true,    "details": { "policy": "manager_approval" }  },  "evidence_ids": ["evt_8f3a1c"],  "started_at": null,  "completed_at": "2026-06-16T15:14:22.104Z"}

Developer reference

Policy state reference

CHP v0.1 leaves full policy engines to hosts, but policy state still needs stable manifest metadata, denial records, and evidence semantics.

Statev0.1 representationInvocation behavior
openpolicy.auth_required = false

Execute after normal schema, lifecycle, and mode validation.

restrictedpolicy.auth_required = true

Require host-recognized subject attributes, grants, or entitlements before execution.

approval_requiredpolicy.approval_required = true

Return a denied result with denial.code approval_required until approval exists.

auditedemits[] and assurance metadata

Allow execution but require evidence records suitable for review and replay.

blockedinvariant or host policy denial

Return a denied result before side effects, commonly with policy_block_pattern_matched or invariant_failed.

revokedhost trust or entitlement state

Deny a previously authorized subject with entitlement_denied and details explaining the revoked grant.

Relationships

Where this sits in the protocol.

Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.

Policy state is part of the manifest and registry view.

Policy enforcement happens during invocation validation.

Policy outcomes should be reflected in evidence.

Visual model

  1. 01Open permits execution after validation.
  2. 02Restricted requires entitlement.
  3. 03Approval required pauses or denies until approved.
  4. 04Blocked returns a structured denial.

Implementation notes

  • Keep policy labels visible as text.
  • Use stable denial codes for blocked and approval_required.
  • Plan revoked state before product surfaces depend on policy tables.

Common mistakes

  • Using color as the only policy signal.
  • Merging approval_required and blocked.
  • Failing open when policy metadata is missing.

Related concepts

Keep reading through the boundary.

Policy →Govern invocation →Conformance →