Governed execution
How policy outside the model, capability grants, four distinct identities, protected paths, the circuit breaker and break-glass keep an agent's actions bounded.
Your policy decides. Not the model. A proposed action is not an authorized action.
Policy outside the model
Before any privileged action, the request goes to a policy decision made by a component that is not the model. The result is a DecisionOutcome: DECISION_OUTCOME_ALLOW, DECISION_OUTCOME_DENY or DECISION_OUTCOME_REQUIRE_APPROVAL. A model cannot talk its way to a different answer, because it is not asked. Denials are recorded in evidence like any other decision.
System boundary explorer
What can cross which boundary, and who holds authority?
Claude or Codex harness. 3 connections on the authority, data, credentials layers. Credentials, policy files, and approval rights.
Text description
The customer data plane holds source, artifacts, evidence and credential sources. The vendor control plane is thin and receives references, digests and statuses only. Humans approve through it; the model never does. The fixed trust kernel (policy decision point, capability broker, plugin host, sandbox, evidence writer, circuit breaker) sits outside every grant. The AI harness is replaceable and runs inside the sandbox.
- Vendor control plane (thin · metadata only · outbound-only from the runner): Control plane.
- Customer data plane (your infrastructure · source, artifacts, evidence and credentials stay here): Runner, Engine, Plugins, Artifact store, Evidence store, Source and systems, Credential sources, Egress proxy.
- Fixed trust kernel (not editable by any grant · outside the model): Policy decision point, Capability broker, Plugin host, Sandbox, Evidence writer, Circuit breaker.
- AI harness (replaceable · runs inside the sandbox): Claude or Codex harness.
Connections by layer:
- [A] Engine to Policy decision point: asks before every privileged action.
- [A] Policy decision point to Capability broker: an allow decision derives the grant the broker honours.
- [A] Policy decision point to Evidence writer: every decision and denial is recorded.
- [A] Policy decision point to Sandbox: grant bounds what the run may do.
- [A] Policy decision point to Plugin host: grant bounds which capabilities a provider may serve.
- [A] Sandbox to Claude or Codex harness: contains the harness; the harness cannot edit the grant.
- [A] Claude or Codex harness to Plugin host: requests capabilities, never executes them itself.
- [A] Plugin host to Plugins: launches and mediates providers.
- [A] Control plane to Engine: human approval or rejection, never the model.
- [A] Control plane to Circuit breaker: human trip or reset with reason and principal.
- [A] Circuit breaker to Engine: pauses runs at the next checkpoint.
- [A] Runner to Sandbox: creates and supervises one per work unit.
- [D] Runner to Control plane: references, digests, statuses only (outbound).
- [D] Engine to Artifact store: content moves by reference and sha256.
- [D] Sandbox to Artifact store: candidate output stored by reference.
- [D] Source and systems to Sandbox: worktree mount for the work unit.
- [D] Claude or Codex harness to Egress proxy: all network traffic, no direct route.
- [D] Egress proxy to Source and systems: allow-listed requests, re-originated and logged.
- [D] Evidence writer to Evidence store: append-only records.
- [D] Plugins to Source and systems: provider calls to SCM, CI and cloud.
- [C] Credential sources to Capability broker: source of material, read by the broker only.
- [C] Capability broker to Egress proxy: injection rule per step; sandbox never sees the secret.
- [C] Capability broker to Plugins: scoped handle, TTL bound to the step.
- [C] Circuit breaker to Capability broker: trip revokes outstanding handles.
- [C] Egress proxy to Source and systems: adds bearer headers on re-origination.
Per component, what it holds, what crosses its boundary and what is denied:
- Control plane. Holds: Change status, gate decisions and approvals as metadata; Runner fleet state: versions, profiles, breaker position; Licence state. Crosses: Inbound: human approve / reject / escalate with a human principal; Inbound: runner heartbeats, references, digests, statuses. Denied: Source, diffs, prompts, secrets, evidence content; A remote kill switch: an installed runtime keeps applying policy and exporting evidence.
- Runner. Holds: Host attestation and supervised sandboxes; Signed bundles it pulled for this host; Evidence signing role (the runner identity writes evidence). Crosses: Outbound-only link to the control plane: references, digests, statuses; Starts one sandbox per work unit; supervises broker and egress proxy. Denied: Accepting inbound connections from the vendor; Sending content to the control plane.
- Engine. Holds: Change state machine and per-stage orchestration; References and digests only in orchestration payloads. Crosses: Asks the policy decision point before every privileged action; Reads and writes content only through artifact references. Denied: Raw credentials: the broker is a separate process; Content inside workflow payloads.
- Plugins. Holds: Provider capabilities: SCM, CI, knowledge, verifiers; Declared permissions in a manifest. Crosses: Launched by the plugin host; every call carries an ActionContext; Reach external systems only with broker-issued handles. Denied: Running unsigned or unpinned; Widening their own permissions without re-approval.
- Artifact store. Holds: Source snapshots, diffs, prompts, findings bodies, logs; Everything an orchestration payload points at by reference. Crosses: Read and written by engine and sandbox through references and sha256 digests. Denied: Leaving the customer plane toward the control plane.
- Evidence store. Holds: Signed, hash-chained evidence records; Denials as well as allowed actions. Crosses: Appended only by the evidence writer; Exported for offline verification. Denied: Edits or deletions by any agent identity; Writes from the harness.
- Source and systems. Holds: Repositories, tickets, pipelines, deployed environments; Branch protection and protected paths. Crosses: Worktree mounted into the sandbox; Reached by egress proxy and plugins under a grant. Denied: Direct deploys by an author identity: only the release pipeline deploys.
- Credential sources. Holds: Long-lived secrets and role definitions, in your systems. Crosses: Read by the broker only, to mint a scoped, short-lived handle. Denied: Being copied into the sandbox, the engine or the control plane.
- Egress proxy. Holds: Per-step allow-list pushed by the broker and withdrawn at step end; Header injection rules for scoped credentials. Crosses: Terminates and re-originates sandbox requests, then logs them; Injects bearer material so the sandbox never holds it. Denied: Any host not on the step allow-list; Link-local and metadata-service addresses.
- Policy decision point. Holds: Signed policy bundles and customer floors; Every decision with reasons and a decision id. Crosses: Receives action, actor identity, change state and autonomy level; Returns allow, deny or require approval, with approver rules. Denied: Being overridden by a lower scope or by the model; Approving when approver equals author.
- Capability broker. Holds: Grant-to-credential translation for one step; Handle TTL bounded by the activity timeout. Crosses: Mints scoped handles or egress injection rules from credential sources; Revokes handles on step end or breaker trip. Denied: Returning reusable credentials to the model; Issuing outside the current grant.
- Plugin host. Holds: Manifest and permission checks; The only path from a run to a provider. Crosses: Launches providers; mediates each capability call against the grant. Denied: Loading an extension that fails signature, digest or permission checks.
- Sandbox. Holds: Writable worktree and tmpfs; read-only runtime; Limits from the budget. Crosses: Network namespace routed only to the egress proxy. Denied: Ambient credentials, SSH keys and tokens; Direct network access; Writing protected paths (policy, CI definitions, IAM).
- Evidence writer. Holds: Append path for decisions, denials, gate outcomes and artifacts digests. Crosses: Writes records to the evidence store under the runner identity. Denied: Accepting records from the author agent; A write failure is not ignored: it trips the breaker.
- Circuit breaker. Holds: Position: FULL_AUTO, PR_ONLY, READ_ONLY or STOPPED. Crosses: Revokes handles and pauses runs at the next checkpoint when tripped; Reset needs a human and a reason. Denied: Depending on the control plane; Being reset by an agent.
- Claude or Codex harness. Holds: The model loop for one work unit; A worktree and the tools its grant allows. Crosses: Requests go out only through the egress proxy and the plugin host; Returns a candidate; verification decides what it earns. Denied: Credentials, policy files, and approval rights; Granting itself more authority; Deploying.
Grants and capabilities
A grant is explicit, bounded authority: scope, risk class, environment and expiry. A capability is a typed ability to perform a kind of action through a governed port. Plugins and executors receive capabilities, not ambient access. Operations in the protocol are annotated with a RiskClass (RISK_CLASS_READ, LOW, MEDIUM, HIGH, PRIVILEGED), so the policy knows what an action is before it decides.
Credentials follow the same rule. The design gives providers host-issued credential handles instead of reusable secrets, with an egress proxy applying the token at the boundary. Receipts from those components are chain records.
Four identities and separation of duties
PrincipalKind names who is acting. Four of them carry the separation of duties:
| Identity | Role | Cannot |
|---|---|---|
PRINCIPAL_KIND_AUTHOR_AGENT | Implements work units. | Approve, review or release its own work. |
PRINCIPAL_KIND_REVIEWER_AGENT | Reviews and runs independent verifiers. | Author the change it reviews. |
PRINCIPAL_KIND_RELEASE_PIPELINE | The only identity that deploys. | Author code. |
PRINCIPAL_KIND_HUMAN_APPROVER | Approves gates. | Approve a change they authored. |
Other principals serve the system: PRINCIPAL_KIND_RUNNER writes evidence, and PRINCIPAL_KIND_BROKER and PRINCIPAL_KIND_EGRESS_PROXY handle credentials and network egress. PRINCIPAL_KIND_BREAK_GLASS is described below.
Protected paths
Some paths, such as the policy that governs the agent, CI definitions and the repository's own ownership rules, are protected. An agent can propose a change to them, but cannot apply it through its normal grant. This stops the obvious escape: editing the rules that bound it.
Circuit breaker
The breaker is customer-local, so stopping the system never depends on the vendor. BreakerPosition has four values: BREAKER_POSITION_FULL_AUTO, BREAKER_POSITION_PR_ONLY, BREAKER_POSITION_READ_ONLY and BREAKER_POSITION_STOPPED. Moving to a more restrictive position takes effect over any autonomy level in policy, and in-flight changes pause. Note that PR_ONLY is a breaker position, not a ladder level.
Break-glass
Break-glass is the emergency path, and it is human-only. An agent cannot invoke it, and its use is recorded. It exists so that humans are never locked out by the system's own controls. It is not a way to grant more autonomy.
Failure modes
- An agent requests an action outside its grant: denied, recorded, change continues or escalates.
- An author tries to approve: rejected, since approver and author must differ.
- An extension is unsigned or its digest does not match: it is not loaded.
Next steps
Autonomy levels
The eight-level autonomy ladder, how defaults, rules and floors combine, and why autonomy is qualified and human-accepted before it is raised.
Harnesses versus the runtime
Why agent harnesses own intelligence while the Numinance runtime owns authority, and what an executor adapter promises.