Agent Hypervisor Execution Control Specification 1.0

This specification defines the execution control model for the Agent Hypervisor — the component that provides hardware-inspired execution isolation for AI agents. Just as an OS kernel uses privilege rings to separate user processes from kernel operations, the Agent Hypervisor assigns agents to execution rings based on their trust scores and enforces resource boundaries at each ring level. All SDK implementations MUST conform to this specification. The key words are interpreted as described in RFC 2119.

Status

Draft

Date

2026-05-17

Conformance Tests

80 tests

Design Principles

Least privilege by default. Unknown agents start at Ring 3 (Sandbox) with minimal resource access.
Ring 0 is system-only. No agent, regardless of trust score, can execute Ring 0 actions without SRE Witness attestation.
Elevation is temporary. Privilege elevation is always time-bounded and automatically expires.
Fail closed. Any enforcement check failure MUST result in denial, never silent permission.
Append-only audit. Session operations form a hash chain that detects tampering.

Execution Ring Definitions

The hypervisor MUST implement exactly four execution rings:

Ring	Value	Name	Description
Ring 0	0	Root	Hypervisor configuration and penalty. System-only.
Ring 1	1	Privileged	Non-reversible actions with full resource access.
Ring 2	2	Standard	Reversible actions with scoped resource access.
Ring 3	3	Sandbox	Read-only actions with minimal resource access. Default.

Ring ordering: Lower value = higher privilege. Ring A is more privileged than Ring B if A.value < B.value. Agents without a computed ring assignment MUST be assigned Ring 3 (Sandbox).

Ring Assignment

Score-Based Assignment

Ring assignment from an effective score (0.0–1.0) MUST follow:

Condition	Assigned Ring
`eff_score > 0.95` AND `has_consensus == true`	Ring 1 (Privileged)
`eff_score > 0.60`	Ring 2 (Standard)
Otherwise	Ring 3 (Sandbox)

Ring 0 is NEVER assigned through score-based computation.

Trust Score Thresholds

Threshold	Value	Purpose
`RING_1_TRUST_THRESHOLD`	0.95	Score-based Ring 1 assignment
`RING_2_TRUST_THRESHOLD`	0.60	Score-based Ring 2 assignment
`RING_1_ENFORCER_THRESHOLD`	0.70	Ring enforcer Ring 1 access

Ring Demotion

An agent SHOULD be demoted when their effective score drops below the threshold for their current ring. The should_demote() check MUST compare the agent’s current ring against the ring that would be computed from their current score.

Action Classification

Required Ring Derivation

The required ring for an action MUST be computed as:

if is_admin:
    → Ring 0 (Root)
elif reversibility == NONE and not is_read_only:
    → Ring 1 (Privileged)
elif is_read_only:
    → Ring 3 (Sandbox)
else:
    → Ring 2 (Standard)

ActionDescriptor Fields

Field	Type	Description
`action_id`	string	Unique identifier (validated format)
`name`	string	Human-readable name (non-empty, max 256 chars)
`execute_api`	string	API path for execution (non-empty, max 2048 chars)
`undo_api`	string or null	API path for undo (if reversible)
`reversibility`	enum	`FULL`, `PARTIAL`, or `NONE`
`undo_window_seconds`	int	Window for undo (0–86400, default 0)
`is_read_only`	bool	Whether the action only reads data
`is_admin`	bool	Whether this is an administrative action

Ring Enforcement

Access Check Algorithm

The ring enforcer MUST perform the following checks in order:

Ring 0 denial: If the action requires Ring 0, the check MUST deny access with requires_sre_witness = true. Ring 0 actions are never available to agents through the standard API.
Ring comparison: If agent_ring.value > required_ring.value (agent has less privilege than required), the check MUST deny access.
Grant: If neither condition above applies, access MUST be granted.

RingCheckResult

Field	Type	Description
`allowed`	bool	Whether access is granted
`required_ring`	ExecutionRing	Ring the action requires
`agent_ring`	ExecutionRing	Agent’s current ring
`eff_score`	float	Agent’s effective score
`reason`	string	Human-readable explanation
`requires_consensus`	bool	Whether consensus is needed
`requires_sre_witness`	bool	Whether SRE attestation is needed
`denied_resources`	list	Resource types that were denied

If a ring is not found in the constraint mapping, Ring 3 (Sandbox) constraints MUST be used as fallback.

Resource Limits Per Ring

Each ring has associated resource constraints:

Ring	Network	Filesystem Scope	Subprocess	Max Concurrent Tools
Ring 0 (Root)	✅ (all)	full	✅	32
Ring 1 (Privileged)	✅ (all)	full	✅	16
Ring 2 (Standard)	✅ (allowlisted)	scoped	❌	8
Ring 3 (Sandbox)	❌	none	❌	4

Resource Constraint Fields

Field	Description
`network_allowed`	Whether network access is permitted
`network_allowlist`	Allowed network destinations (empty = all if network_allowed)
`filesystem_writable`	Whether filesystem writes are permitted
`filesystem_scope`	One of: `"none"`, `"session"`, `"scoped"`, `"full"`
`subprocess_allowed`	Whether subprocess creation is permitted
`max_concurrent_tools`	Maximum concurrent tool executions

Privilege Elevation

Privilege elevation is a time-bounded promotion from a lower ring to a higher ring.

Elevation Rules

Elevation to Ring 0 MUST always be denied via the standard API (reason: "ring_0_forbidden").
Elevation to Ring 1 requires trust_score >= 0.85 AND has_consensus == true.
Elevation durations MUST be time-bounded. The default maximum elevation duration is 3600 seconds.
Elevations MUST expire automatically. The tick() function MUST be called periodically to expire stale elevations.

Given: agent at Ring 2, requests Ring 1, trust_score=0.60
Result: DENIED, reason="insufficient_trust" (Ring 1 requires ≥ 0.85)

Given: agent at Ring 2, requests Ring 0
Result: DENIED, reason="ring_0_forbidden"

Rate Limiting

Rate limiting uses a token bucket algorithm scaled by ring.

Ring	Refill Rate	Burst Capacity
Ring 0	Unlimited	Unlimited
Ring 1	50.0 req/s	100.0
Ring 2	20.0 req/s	40.0
Ring 3	5.0 req/s	10.0

When the token bucket is exhausted, the implementation MUST raise RateLimitExceeded. The maximum bucket count MUST be enforced to prevent memory exhaustion from many agent identifiers.

Saga Orchestration

Sagas provide multi-step distributed transaction support with automatic compensation when steps fail.

Saga Defaults

Parameter	Default	Description
`max_retries`	2	Maximum retries per step
`retry_delay_seconds`	1.0	Base delay between retries
`step_timeout_seconds`	300	Maximum duration for a single step

Saga State Machine

Pending → Executing → Committed (all steps succeed)
                    → Compensating → Aborted (compensation succeeds)
                                   → Escalated (compensation fails — manual intervention)

Step States

State	Description
`Pending`	Not started
`Executing`	Currently running
`Committed`	Completed successfully
`Failed`	Execution failed
`Compensated`	Successfully rolled back
`CompensationFailed`	Rollback failed

Compensation Rule

When a step fails after exhausting retries, the saga orchestrator MUST execute compensation (undo) for all previously completed steps in reverse order. If compensation itself fails, the saga MUST transition to Escalated and record which compensation steps failed.

Kill Switch

The kill switch provides emergency agent termination with step handoff and compensation support.

Kill Switch Behavior

When kill(agent_id, context) is invoked:

All registered handlers for the agent are executed in registration order.
All registered compensations for the agent are executed in registration order.
If a substitute agent is registered, the result includes handoff_agent_id.
A KillSwitchResult record MUST be appended to the kill switch history, even if callbacks fail.

KillSwitchResult Fields

Field	Type	Description
`agent_id`	string	The terminated agent’s DID
`action`	string or null	The action that triggered termination
`reason`	string	Human-readable reason
`killed_at`	datetime	ISO 8601 timestamp
`callbacks_executed`	int	Number of termination handlers executed
`compensations_executed`	int	Number of compensation handlers executed
`handoff_agent_id`	string or null	Substitute agent DID, if registered

Kill switch results MUST be recorded even when callback execution fails. The kill switch MUST NOT raise an exception that prevents the audit record from being written.

Trigger Conditions

The kill switch MUST be triggerable by:

Explicit operator invocation
Ring breach when kill_on_breach = true
Policy engine integration on critical violations
SRE circuit breaker integration

Audit and Hash Chain Integrity

Audit Hash Chain

The session audit log MUST be an append-only hash chain where each entry’s SHA-256 hash covers its content plus the previous entry’s hash:

Entry 0            Entry 1            Entry 2
┌──────────┐       ┌──────────┐       ┌──────────┐
│ hash: A  │──────▶│ prev: A  │──────▶│ prev: B  │
│ prev: 0⁶⁴│       │ hash: B  │       │ hash: C  │
└──────────┘       └──────────┘       └──────────┘
Genesis hash = '0' × 64

What Gets Recorded at Each Ring Boundary

Event Type	Required Audit Fields
Action attempt	`agent_id`, `action`, `ring`, `eff_score`, `timestamp`
Ring check result	`allowed`, `required_ring`, `agent_ring`, `reason`
Rate limit event	`agent_id`, `action`, `bucket_tokens`, `exhausted`
Elevation request	`agent_id`, `target_ring`, `trust_score`, `granted`
Kill switch trigger	`agent_id`, `reason`, `callbacks_executed`, `handoff_agent_id`
Saga step	`saga_id`, `step_id`, `state`, `attempt_count`, `compensated`

The audit hash chain MUST be append-only. Any modification to an entry MUST invalidate all subsequent hashes, enabling tamper detection.

Session Model

Session Configuration Constraints

Field	Type	Constraints
`session_id`	string	MUST match `^[a-zA-Z0-9_-]+$`
`max_participants`	int	1–100
`consistency_mode`	enum	`eventual`, `strong`, `causal`
`min_participants`	int	1–`max_participants`

Session Isolation

Filesystem-level isolation MUST be fail-closed. Path checks MUST resolve to canonical paths before comparison. Path traversal (.. components) MUST be rejected. If a cross-session access request cannot be validated, it MUST be denied.

Quarantine

When an agent is quarantined:

The agent’s ring is demoted to Ring 3 (Sandbox).
All pending actions for the agent are denied.
A quarantine audit entry MUST be appended to the hash chain.
The agent MAY be released from quarantine by an operator with Ring 0 credentials.

Conformance Requirements

A conforming implementation MUST:

Implement exactly four execution rings (0–3) with correct ordering.
Deny Ring 0 to agents via standard enforcement.
Implement score-based ring assignment following threshold rules.
Derive action required-ring following the classification rules.
Enforce ring checks fail-closed on all failures.
Enforce resource constraints per the ring-to-constraint mapping.
Implement time-bounded privilege elevation.
Forbid Ring 0 elevation via the standard API.
Implement token bucket rate limiting with per-ring limits.
Validate session configurations.
Enforce session isolation fail-closed.
Record kill switch results even on callback failure.
Maintain an append-only SHA-256 hash chain for audit.
Validate identifiers against the allowed pattern.

Conformance tests MUST cover: ring assignment from trust scores; action classification to required rings; ring enforcement allow/deny decisions; resource constraint enforcement; elevation approval and denial; rate limiter token consumption and exhaustion; session configuration validation; session isolation path checks; kill switch operation and failure modes; and audit hash chain construction and verification.

Python SDK

Other SDKs

Specifications

Documentation Index

Status

Date

Conformance Tests

​Design Principles

​Execution Ring Definitions

​Ring Assignment

​Score-Based Assignment

​Trust Score Thresholds

​Ring Demotion

​Action Classification

​Required Ring Derivation

​ActionDescriptor Fields

​Ring Enforcement

​Access Check Algorithm

​RingCheckResult

​Resource Limits Per Ring

​Resource Constraint Fields

​Privilege Elevation

​Elevation Rules

​Rate Limiting

​Saga Orchestration

​Saga Defaults

​Saga State Machine

​Step States

​Compensation Rule

​Kill Switch

​Kill Switch Behavior

​KillSwitchResult Fields

​Trigger Conditions

​Audit and Hash Chain Integrity

​Audit Hash Chain

​What Gets Recorded at Each Ring Boundary

​Session Model

​Session Configuration Constraints

​Session Isolation

​Quarantine

​Conformance Requirements

Build docs developers (and LLMs) love

Design Principles

Execution Ring Definitions

Ring Assignment

Score-Based Assignment

Trust Score Thresholds

Ring Demotion

Action Classification

Required Ring Derivation

ActionDescriptor Fields

Ring Enforcement

Access Check Algorithm

RingCheckResult

Resource Limits Per Ring

Resource Constraint Fields

Privilege Elevation

Elevation Rules

Rate Limiting

Saga Orchestration

Saga Defaults

Saga State Machine

Step States

Compensation Rule

Kill Switch

Kill Switch Behavior

KillSwitchResult Fields

Trigger Conditions

Audit and Hash Chain Integrity

Audit Hash Chain

What Gets Recorded at Each Ring Boundary

Session Model

Session Configuration Constraints

Session Isolation

Quarantine

Conformance Requirements