Docs / Concepts

Policy

Policy is the visible governance rule that decides whether a capability may execute for a caller and context.

Plain English

Policy is the rule at the capability boundary: open, restricted, approval required, audited, or blocked.

Why it exists

Callers should know when a capability is sensitive before they invoke it, and hosts should return denials predictably.

Formal definition

Policy is the host-enforced authorization and governance state attached to a capability, invocation, or context.

Concrete example

Ground the concept before the schema.

manager_approval requires a manager decision before schedule_technician returns a confirmed appointment.

schedule_technicianRestricted

Finds an available qualified technician and reserves a service window.

host: ServiceOpsHostpolicy: approval_requiredv1.0.0

Policy boundary

Approval required

manager_approval

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

Invocation trace

  1. 01 Actor

    Planning Agent

  2. 02 Capability

    schedule_technician

  3. 03 Host

    ServiceOpsHost

  4. 04 Policy

    manager_approval

  5. 05 Context

    job_context

  6. 06 Result

    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"}

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 is declared in manifest metadata and enforced during invocation.

Policy outcomes must be structured and replayable.

Policy state should be visible as text, not only color.

Visual model

  1. 01Caller requests a capability.
  2. 02Host evaluates permission and policy state.
  3. 03Invocation proceeds, pauses, or denies with a protocol outcome.

Implementation notes

  • Expose required entitlements or subject requirements before invocation.
  • Return policy denials as structured outcomes.
  • Separate policy state from host availability.

Common mistakes

  • Hiding policy behind generic authorization errors.
  • Treating approval_required as a successful execution.
  • Using color without visible state labels.

Related concepts

Keep reading through the boundary.

Host →Invocation →Policy →