MetaMynd Agentic Governance Protocol (MAGP)

Specification — Version 1.0 Status: Stable · Date: 2026-08-20 · Editors: MetaMynd

A protocol for authorizing the actions of autonomous AI agents. An agent presents a signed description of what it is about to do; a verifier evaluates that action against the agent's identity, the authority delegated to it, and the policies in force; and returns a decision the agent must obey. Every decision produces evidence a third party can verify without trusting the verifier.

Status of this document

Version 1.0 supersedes the 0.x drafts. It describes what is built and running: every normative clause below corresponds to code in the reference implementation. Work not yet built is listed in Appendix D — Future directions. If it is in the body, it exists.

This specification states what an implementer needs in order to interoperate. How a particular gate stores state, schedules work or recovers from faults is out of scope.

Scope

MAGP is the interoperability surface. The test for inclusion is narrow and worth stating, because it is what keeps this document implementable:

A thing belongs in MAGP if an independent implementer needs it to reach the same verdict on the same request, or to verify the same evidence without access to the platform that produced it.

That test admits identity, the canonical signed message, the order of checks, reason codes, mandate and delegation semantics, policy-bundle distribution, and the evidence and proof formats. It excludes the governance surfaces a platform builds on top — supervisory access for regulators, sandbox programmes, incident routing, the trust graph, document ingestion. Those are real and specified in the companion document MetaMynd Platform Governance; they are not things a second implementation must reproduce to interoperate.

Conformance language

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119.

Table of contents

1. Terminology
2. Roles and entities
3. Architecture
4. Identity
5. Authority: mandates, resource scope, delegation
6. Policy artifacts
7. Agent posture: containment, operating mode, reassessment
8. The authorize protocol
9. Secondary controls: rate limits and circuit breakers
10. Escalation resolution
11. Payment execution binding (x402)
12. Effects and reconciliation
13. Evidence and anchoring
14. Decision records and the governance envelope
15. Privacy-preserving verification
16. Discovery and channels
17. Security considerations
18. Extensibility and versioning
19. Conformance
20. Reference endpoints

• Appendix A — Reason codes
• Appendix B — Canonical examples
• Appendix C — Atom catalog
• Appendix D — Future directions

1. Terminology

Agent — an autonomous software actor that proposes and performs actions. Identified by a DID.

Principal — the legal person or organisation on whose behalf an agent acts. The delegation root: the chain of authority terminates here, at a named legal entity whose verification status — and how it was verified — is reported on every read (§4.4).

Owner — the tenant account that administers an agent. Distinct from the principal: an owner may administer agents acting for several principals.

Mandate — the authority delegated to an agent, expressed as an ODRL policy and issued as a verifiable credential. Says which actions, within which constraints, for how long.

Standard — a published, versioned rule pack an organisation binds agents to. Enforced.

SOP — a standard operating procedure: an organisation's own rule pack, scoped to its agents.

Molecule — one rule within a Standard or SOP: a set of atoms (pure predicates over request context) and the decision to emit when they all hold.

Gate — the verifier. Evaluates a proposed action and returns a verdict. Server- authoritative: the agent does not decide, and a guard that evaluates locally reaches the same verdict from the same signed inputs.

Verdict — the gate's answer: a disposition plus a reason code (§8.6, Appendix A).

Evidence — the record of a governance decision, in a form a third party can verify independently of the platform that produced it.

2. Roles and entities

An MCP server is a counterparty that exposes tools. Where it holds its own DID and mandate it is simultaneously an agent, and this protocol treats it as one.

3. Architecture

Two planes.

The control plane issues and publishes: identities, mandates, standards, SOPs, signed policy bundles. It is not on the hot path.

The data plane is the authorize exchange. It MAY be executed:

• against the gate — the central verifier, which owns the stateful parts (nonce consumption, spend reservation, evidence);
• at the edge by a guard — deterministic evaluation against a signed policy bundle, with no round trip;
• at the counterparty — a trustless re-check, so an agent that skips its own guard still cannot get the counterparty to act.

All three MUST produce the same disposition from the same inputs. Where they cannot — because a check is inherently stateful — the edge MUST fail closed and defer (§8.5).

4. Identity

4.1 Agent DID methods

An implementation MUST support at least one of:

• did:hedera — anchored on an HCS topic. The DID document is derived from the anchor; the agent's Ed25519 public key is the verification method.
• did:key — self-certifying. The Ed25519 key is the identifier; no anchor, no issuance ceremony, control provable from the identifier alone.

4.2 Proof of possession

4.2.1. An agent whose key was supplied by its holder (BYOK) MUST prove control before the gate accepts any action from it. The gate issues a challenge; the agent signs it; the gate verifies against the key in the DID and stamps the identity as proven.

4.2.2. Until control is proven the gate MUST deny with AGENT_KEY_UNVERIFIED. This is not advisory: an unproven key means the signature check (§8.5 step 5) is meaningless, because nobody has demonstrated that the key belongs to the party claiming it.

4.2.3. Where the platform generated the keypair and returned the private key once, control is established at issuance and no challenge is required.

4.2.4. Proof is per key. A DID minted by rotation or for a second network has its own keypair, so the gate MUST judge possession of the key the request is verified with — that DID's own proof — not the proof recorded for the agent's original key.

4.3 Resolution

4.3.1. A verifier MUST resolve the agent's public key from the DID rather than trusting any key material in the request.

4.3.2. GET /did/{did} returns a W3C DID document for both supported methods.

4.3.3. Identity rotation. Rotating an agent's identity on a network (key-loss recovery) replaces its DID and key there. Every mandate active under the old DID is reissued under the new one with the same terms and cumulative spend; a delegated mandate is reissued delegated and re-validated against its delegator, or else revoked (5.4.11). The old DID no longer verifies: the gate refuses a request signed as it IDENTITY_ROTATED, and GET /did/{did} answers 410 Gone with didDocumentMetadata.deactivated: true (the HTTP binding of W3C DID Resolution). The old DID's Authority Manifest carries retired: { reasonCode: "IDENTITY_ROTATED" }. Neither public read names the replacement DID; the IDENTITY_ROTATED refusal carries it as replacementDid, outside the digested verdict, and only to a request validly signed with the replaced key.

4.4 Principal assurance

4.4.1. Every mandate MUST name an authorizing principal, and an absent one is refused. Beyond that, how much the principal's verification matters depends on the network the agent is on:

• Testnet and did:key agents — verification is reported, not required. The principal's authority holds whether or not it is verified, and a sandbox or evaluation needs no KYC/KYB. The verdict and the registry carry the principal's status (4.4.2) so a counterparty applies its own risk policy.
• Mainnet agents — the principal MUST be verified by a mainnet-eligible provider to create the identity at all, and the principal's authority holds only within the platform's limits for its plan. Beyond them the gate refuses with PRINCIPAL_UNVERIFIED. A testnet or did:key agent is never refused with it.

The mainnet check precedes signature verification, because it is a question about the policy rather than about the requester.

4.4.2. The registry (GET /magp/manifest/{did}, GET /policy/mandate/{ref}/status) MUST expose the authorizing principal's current verification status on every read, and every authorize verdict MUST carry it alongside the decision — so a counterparty applies its own risk policy to an unverified-backed mandate rather than assuming verification.

4.4.2a. The public Authority Manifest (GET /magp/manifest/{did}) MUST also expose the agent's live containment (7.1) as a sibling of the manifest — containment: { status, since }, status one of suspended, quarantined, decommissioned, or null when the agent is active. The manifest states the authority the agent was granted; containment does not change that, it stops the agent using any of it, so a rendering of a contained agent's manifest MUST NOT present its granted actions as currently permitted. The containment reason is the owner's and MUST NOT be published. The manifest endpoint itself MUST NOT be served from a cache, and a cached public projection of it (a README badge) SHOULD reflect a containment within a minute.

4.4.3. Verified does not mean identity-checked. The registry's principal block reports not only verified but the basis of the verification — the weakest across the principals behind the agent's active mandates:

A counterparty that needs a real identity check MUST require provider or manual_review, not merely verified: true. The block also carries identityChecked, which is true only when verified is true and the basis is provider or manual_review. A self-approved principal reads verified: true, basis: "self_approved", identityChecked: false.

5. Authority

5.1 Mandates

5.1.1. A mandate is an ODRL policy carried in a verifiable credential. It names a target action and carries permissions and prohibitions, each with constraints.

5.1.2. Evaluation order within a mandate is: validity window, then prohibitions, then a matching permission whose constraints all hold. A prohibition that fires outranks any permission.

5.2 Constraints

A constraint is { leftOperand, operator, rightOperand }. Operators are a fixed set — new scenarios add operands, not operators:

eq · neq · lt · lteq · gt · gteq · isAnyOf · isNoneOf · isPartOf · before · after

5.2.1. An unknown operator MUST fail closed.

5.2.2. Well-known operands map to stable reason codes so a denial names its cause: mm:payAmount and mm:cumulativeSpend → SPEND_LIMIT_EXCEEDED; mm:merchant → MERCHANT_NOT_ALLOWED; mm:route → ROUTE_NOT_ALLOWED; mm:counterparty → COUNTERPARTY_NOT_ALLOWED; mm:jurisdiction → JURISDICTION_REQUIRED when the request has no effective jurisdiction, JURISDICTION_NOT_ALLOWED when it has one outside the list (§5.2.3). Any other operand denies with CONSTRAINT_FAILED:<operand>.

5.2.2a. A cumulative cap is per currency. Its limit is a bare number, so the committed spend it is checked against MUST count only holds in the request's currency (compared case-insensitively); summing two currencies has no meaning without a rate, and none is applied. A hold with no recorded currency counts against every currency, so the check fails closed. This changes nothing for a single-currency mandate; for one that allows several currencies (or any), the cap applies to each separately.

5.2.3. Allowed jurisdictions. A mandate MAY restrict the jurisdictions an action may be performed in. Issuance (POST /policy/mandate) takes an optional allowedJurisdictions: a list of ISO 3166-1 alpha-2 codes, trimmed, upper-cased, de-duplicated and sorted; the group code EU expands to the 27 member states. An empty or malformed list is refused (400 MALFORMED_REQUEST); omitting it means no restriction. The term is stored as an ordinary constraint on the permission:

{ "leftOperand": "mm:jurisdiction", "operator": "isAnyOf", "rightOperand": ["DE", "FR", "SG"] }

• It is judged on the request's effective jurisdiction (§8.3.12) — the country the owner registered for the payee, else the signed top-level jurisdiction — never on an itinerary value. With no effective jurisdiction the request is blocked JURISDICTION_REQUIRED; outside the list, JURISDICTION_NOT_ALLOWED.
• GET /policy/mandate/{ref}/status returns it as allowedJurisdictions (null = no restriction).
• A reissue (identity rotation, resource-scope pin, payload-binding toggle) MUST carry the term. A jurisdiction constraint that cannot be read back as an allow-list (a hand-authored isNoneOf, say) refuses the reissue of that mandate rather than dropping the restriction.
• A delegated mandate inherits or narrows it (§5.4.5).
• The zero-knowledge path proves membership in the same list (§15.1.2).

5.3 Resource scope

5.3.1. Authority over actions does not answer which systems and data an agent may reach. A resource scope is expressed as an ordinary constraint over the resource operand, which the request declares in its context:

{ "leftOperand": "resource", "operator": "isAnyOf",
  "rightOperand": ["crm.contacts", "ledger.postings"] }

5.3.2. The resource is part of the signed message (§8.3): it is cryptographically committed the same way merchant already is (and a top-level jurisdiction is, §8.3.12), not merely asserted the way tool or an itinerary value is. A counterparty relaying a buildSignedRequest()-built request cannot substitute a different resource without invalidating the signature.

5.3.3. An action that declares no resource, evaluated against a mandate carrying a resource constraint, MUST be denied: an action that will not say what it touches cannot be checked against a scope.

5.4 Delegation

5.4.1. An agent MAY delegate a narrowed subset of its own authority to another agent. The delegated mandate is an ordinary mandate; nothing downstream special-cases it.

5.4.2. Narrowing invariant. A delegated mandate MUST NOT widen its parent. Narrowing is asymmetric per operator, and an implementation that gets this wrong grants authority nobody issued:

5.4.3. A parent constraint the child omits is a widening, not a simplification. A child that drops its parent's spend cap holds more authority than its parent.

5.4.4. A child MUST NOT outlive its parent's validity window, and MUST retain every prohibition the parent carried.

5.4.5. Constraints the parent did not have MAY be added freely: they can only remove authority. The same holds for the permission-level settings that are not constraints: a child MUST NOT lower or drop its parent's riskTier (§6.3), nor drop its parent's requirePayloadBinding (§8.3.9), and a value of either that is not a recognised one is refused rather than read as "not set". Nor may it drop or widen its parent's argument policy (§8.3.14): each of the child's allow paths MUST sit at or below one of the parent's, and each of the parent's sensitive paths MUST appear in the child with the same mode or redact.

• Allowed jurisdictions (§5.2.3). A child that states no allowedJurisdictions inherits its parent's list, and the implementation MUST store it on the child explicitly (so the child's own document carries the restriction, and a later change to the parent cannot widen it). A child that states a list has it normalised as at issuance (EU expanded) and it MUST be a subset of the parent's (isAnyOf narrowing, 5.4.2) — otherwise the delegation is refused CONSTRAINT_WIDENED (operand mm:jurisdiction). A child of an unrestricted parent MAY add a list. A reissue of a delegated mandate carries its list and re-checks it against the parent's current terms (5.4.11): a list no longer within the parent's is DELEGATION_NARROWING_FAILED.

5.4.6. The chain MUST terminate at a bounded depth (reference implementation: 3).

5.4.7. The delegation root MUST remain the original principal at every depth, so an accountability walk from any descendant terminates at the principal that issued the root mandate — a named legal entity, whose verification status and basis (§4.4.3) are reported.

5.4.8. Narrowing SHOULD be verified at issuance. A stored child that has been proven no wider than its parent costs nothing extra to evaluate.

5.4.9. Revoking a mandate revokes everything delegated from it. A child holds authority only because its parent did, so revoking a mandate — directly (POST /policy/mandate/{ref}/revoke), as a chain (POST /policy/mandate/{policyId}/revoke-chain), or by decommissioning its agent — MUST revoke every mandate delegated from it, at every depth, and each one MUST be revoked exactly as a directly revoked mandate is (8.7.15): made inactive, its pending reviews closed (10.4.2), its unclaimed holds released. This holds for a reissue too: every mandate delegated from the superseded mandate is revoked, and the delegator re-delegates if it still wants to.

5.4.10. A delegated mandate is only as live as its chain. Independently of the cascade, a gate MUST refuse to use a delegated mandate unless every mandate it was delegated from, up to the root, is active — at authorize, at an escalation approval or a reviewer's MODIFY (10.4.1), and on a claim or a capture of an unclaimed hold under it (8.7.15): MANDATE_REVOKED when an ancestor is inactive, and DELEGATION_CHAIN_BROKEN when the chain cannot be walked to a root (a parent that no longer exists, a cycle, or a chain deeper than the bound of 5.4.6). The walk MUST be bounded and cycle-safe.

5.4.11. A reissued delegated mandate stays delegated. When a delegated mandate is reissued — the delegate's identity is rotated (4.3.3), a resource scope is pinned into it, its payload-binding requirement is switched — the new mandate MUST keep the delegation: the same parent (and delegating agent), the same depth, the delegator's tenant as its owner and the same root principal (5.4.7). Its terms are the delegated mandate's own terms with only that change applied. Before it is issued it MUST be re-validated as a delegation is at issuance: every mandate above it active (5.4.10), and the changed terms a narrowing (5.4.2–5.4.5) of the parent's current terms. On failure (MANDATE_REVOKED, DELEGATION_CHAIN_BROKEN or DELEGATION_NARROWING_FAILED) nothing is issued: an owner's change is refused and the delegated mandate stays as it was, while an identity rotation revokes it (8.7.15). A reissue is never a way out of a chain.

6. Policy artifacts

6.1 Standards and SOPs

6.1.1. A rule pack is a set of molecules. A molecule fires when all its atoms hold, and emits its declared decision and reason code.

6.1.2. Atoms are pure predicates over request context — no clock, no network, no model. Determinism is what allows the edge and the gate to agree. The catalog is Appendix C.

6.1.3. Across all molecules of all bound packs the most restrictive decision wins.

6.2 Signed policy bundles

6.2.1. GET /policy/bundle/{did} returns the agent's evaluable policy, signed by the issuer. GET /magp/policy/pubkey publishes the verification key.

6.2.2. A guard MUST verify the signature before evaluating, and MUST reject a bundle whose signature is invalid for any action. A guard holding a pinned verification key MUST also reject a bundle whose signature is absent, for any action — an amount-0 action included. The issuer never serves an unsigned bundle, so under a pin one can only have been stripped in transit, and an amount-0 action is not necessarily a read: a non-financial agent's every action carries no amount.

6.2.3. Bundles carry a maxStaleness. A value-bearing action MUST fail closed on an unsigned, tampered or stale bundle (POLICY_BUNDLE_UNSIGNED, POLICY_BUNDLE_SIGNATURE_INVALID, POLICY_BUNDLE_STALE). A guard holding a pinned key MUST fail closed on a stale bundle for any action, since the issuer re-issues every copy it serves and a stale one is a replay of authority that may since have been withdrawn. Only a guard with no pinned key (6.2.4) MAY let an amount-0 action proceed on an unsigned or stale bundle.

6.2.4. A guard that has no pinned verification key cannot perform 6.2.2 and is trusting the transport instead. It MUST NOT permit a value-bearing action on a bundle that arrived over an unauthenticated transport (plain http://) — POLICY_BUNDLE_UNVERIFIED — unless its operator has explicitly opted out for local development. Over TLS it SHOULD warn that the bundle is trusted on the strength of TLS alone.

6.2.5. maxStaleness bounds the age of the copy a guard holds, measured from the bundle's issuedAt. The issuer therefore MUST serve a bundle whose issuedAt is the time it is served, signed at that time — not the time its rules were last compiled, which can be arbitrarily old for rules that have not changed. A compiled bundle is re-issued on every fetch: issuedAt is the serve time, and compiledAt and compiledSignature (the compile's own signature, the one anchored on the agent's topic as policy-update.sigDigest, §5.3.1) are carried inside the re-signed content. The compiled bundle is recovered by setting issuedAt to compiledAt, removing those two fields and verifying compiledSignature over the result; a guard confirming the bundle is the latest anchored one compares the anchor with sha256(compiledSignature), or with sha256(proof.signature) for a bundle that carries no compiledSignature.

6.2.6. Revoked actions. A bundle MAY carry revokedActions: the actions the agent was granted a mandate for and no longer holds one for, every mandate for them having been revoked. It is part of the signed content, and the issuer omits it when it would be empty. A guard that finds no mandate for an action listed there MUST refuse it MANDATE_REVOKED rather than NO_MANDATE or NO_PERMISSION_FOR_ACTION, as the gate does (§8.5): the authority was granted and withdrawn, which is not the same fact as never granted. The field names the refusal and never decides it, since the action is refused either way. A guard reading a bundle without it refuses as before. An action granted again is in mandates and is not listed.

6.2.7. Owner. A bundle carries ownerPrincipal: the public DID of the principal that owns the agent — its organisation principal, else its owner's oldest verified principal — signed with the rest, and omitted only when the agent has none (it then cannot act: the gate requires a verified principal). It is how a Service bound to the owner of its credentials (16.3) checks that an admitted agent belongs to that owner. It never carries the platform's internal owner identifier.

6.2.8. Policy commitment. The policy-update op a compile anchors on the agent's topic SHOULD carry policyRoot and policyParts: a salted commitment to the compiled bundle's parts, so the owner can show an auditor one part of the policy issued to the agent, with proof it was in that policy, and nothing else. The parts are each mandate (id = action:hash), each SOP (id), each pinned standard (id = key@version), and one subject part naming the agent, the version label, the owner principal and the sorted revoked actions; parts sharing an id are numbered #2, #3… in content order, skipping any number another part's id already bears. Each is a leaf

sha256( "MAGP-POLICY-PART-v1" ‖ 0x00 ‖ kind ‖ 0x00 ‖ id ‖ 0x00 ‖ canonical(content) ‖ 0x00 ‖ salt )

where canonical is JSON with object keys sorted and undefined members dropped, and salt is the lower-case hex of an HMAC-SHA256 under the issuer's secret over the bundle hash, the kind and the id. Leaves are ordered by (kind, id) and policyRoot is "sha256:" followed by their Merkle root, built as the evidence tree is (13.2): a lone last node is paired with itself. policyParts is the leaf count. The salt is per part and per bundle, so a disclosed part reveals nothing about the others, and a part cannot be confirmed by guessing its content: a mandate from a template differs from its neighbours only in a cap or a counterparty, and an unsalted hash of it could be found by trying the few candidates. An issuer with no secret to salt with MUST NOT anchor a commitment. The salts are derived, not stored, so an issuer that replaces its secret can no longer open the commitments anchored under the old one. policyParts is public: it reveals how many parts the policy has, never which.

The owner obtains an opening from GET /agent-identity/{ref}/policy-disclosure (bundleHash selects a compiled bundle, else the active one; kind and id select the part, and without them the response names the parts there are to open). The opening is { did, bundleHash, policyRoot, policyParts, disclosure: { kind, id, content, salt, proof } }. A verifier recomputes the leaf, walks the proof to policyRoot, refuses a proof whose length does not fit a tree of policyParts leaves or whose positions name a leaf beyond it (the duplicated last node is not a further part), and finds a policy-update op for the same DID carrying that root, bundle hash and count. The op's consensus timestamp is when that policy took effect, and a decision is placed against it by bundle hash. magp-evidence verifyPolicyDisclosure does all of this with the issuer offline.

6.3 Context provenance

6.3.1. The context the atoms judge is assembled from sources of very different trust, and a rule that judges what the agent said about itself has judged nothing. A signature does not help: it says who asserted a value, not that it is true, and the counterparty re-check reads the same claim. So every context field MUST carry a provenance — where its value came from — attached only by the party assembling the context, never by the request:

An unlabelled field is agent_asserted: no context, however it was built, reads as more trusted than the agent's own word. An agent cannot set a label — provenance is not part of any request, and a value the agent sends under a key named "provenance" is just another unsigned field.

6.3.2. Assembly. Sources are applied in order of trust, each later source winning a collision: unsigned < signed < gateway-derived < server-derived. This is §17.2 extended to the two derived sources.

6.3.3. Risk is a floor, never a ceiling. riskLevel is an ordered, restrictive field, so it is merged, not overridden: the effective value is the maximum of every trusted source and the agent's own claim. Trusted sources are the mandate owner's riskTier on the permission (authoritative), a value the gateway derived from the request (gateway_derived) and a server-derived one (authoritative). An agent may raise its stated risk; it can never lower it below what a trusted source says. The effective value takes the provenance of the most trusted source present. A trusted source that states an unusable riskLevel has said nothing: it neither overwrites the agent's claim nor lends it the trusted source's label. riskTier is part of the signed mandate, so the gate and every guard apply the same floor, and a delegated mandate (§5.4) MUST NOT drop or lower its parent's tier — a lower tier is less scrutiny, a widening — nor carry a tier that is not a recognised level (refused, never read as "no floor"). riskLevel is read case- and whitespace-insensitively ("HIGH " is high); the levels are low, medium, high, critical.

6.3.4. Fail closed on the atoms that judge risk. A molecule containing a risk-at-or-above atom MUST NOT pass when riskLevel is missing, or is present but not one of the four levels: it MUST decide at least escalate, with reason code CONTEXT_UNVERIFIABLE, whatever its combinator (a none rule must not read absence as "nothing wrong"). If the molecule fires on its own, its own decision and reason code stand (an observe is raised to escalate). A molecule that could not be judged escalates even if another of its atoms would have kept it from firing.

6.3.5. Policies declare the trust they need. A molecule MAY declare requireProvenance: { field: level }. For each named field the molecule needs a well-formed value whose provenance is at least level; otherwise it decides at least escalate (CONTEXT_UNVERIFIABLE). An unknown level is read as the strictest (attested), and a document declaring one is rejected at authoring, so a typo can only make a rule refuse more. A molecule that declares nothing behaves exactly as before, except as 6.3.4 requires.

6.3.6. Counterparty derivation. A guard SHOULD let the service supply trustedContext — context the service derived from the real call, never from the agent — which is applied over the agent's claim and labelled gateway_derived. A trustedContext the service configured but that yields nothing usable — not an object, or a riskLevel that is not a level (a lookup that missed and returned nothing) — means its deriver is broken, and the request MUST be refused; it MUST NOT fall back to the agent's word. The operating-mode gate (§7.2) judges the effective risk, so an agent in supervised mode cannot skip the high-risk escalation by claiming low.

6.3.7. What this does and does not establish. It closes omission, garbling and understating where a trusted source exists. It does not make an agent's claim true: with no owner riskTier, no gateway derivation and no requireProvenance, riskLevel is still the agent's word — only hiding or garbling it is now refused. The other agent-supplied fields (tool, model, consent, …) keep their documented absent-field behaviour (Appendix C); a rule that must not depend on the agent's word about them declares requireProvenance. jurisdiction is no longer one of them: the gate enforces only the effective jurisdiction of §8.3.12 (registered payee country, else the signed field), and an itinerary jurisdiction is ignored.

6.3.8. Owner-keyed operations (non-financial risk). A financial action has risk the issuer derives from facts the agent cannot fake (the amount against the cap, a first payment to an unvetted merchant). A non-financial action has no amount, so unless the owner configures otherwise, whether it escalates depends on the riskLevel the agent declares — an agent that labels op: "delete-all" as low is not reviewed. The owner closes this by keying a rule on what is being done: the context-value-in atom fires when a context field (a dot path such as op or params.op) has one of the owner's values, and context-value-not-in fires when it has a value not on an allow-list (Appendix C). Both are pure, so the gate and every guard bundle reach the same verdict. Values are compared after Unicode NFKC, removal of invisible characters, lower-casing, folding of common Cyrillic/Greek look-alikes of Latin letters, and removal of whitespace, hyphens and underscores; a value that is an object or a nested list is unjudgeable and MUST fire; a list fires if any element would; a field that is absent fires only when the atom is configured missing: "fire". A deny-list cannot foresee every spelling, so an allow-list is the stronger form when the safe operations are known. When a refusing or escalating molecule fires on such an atom, the gate SHOULD report it with the decision as a risk signal { signal: "context-value", level: "high", detail } (e.g. op=delete-all is owner-marked for review), alongside the financial signals, so the review shows the risk was derived from the request rather than declared by the agent. The field is only as good as the executor's binding of it: it must be the field the executor acts on, and the approved context is bound at claim (8.7.20).

7. Agent posture

Three per-agent states that bias or override evaluation. All are gate-side facts; a guard learns them through the bundle.

7.1 Containment

7.1.1. A contained agent is denied all actions until reinstated — AGENT_SUSPENDED, AGENT_QUARANTINED, or AGENT_DECOMMISSIONED. Containment is checked before any action-specific evaluation.

7.1.2. Containment MAY be applied automatically by a firing rule (suspend/quarantine), or manually by an owner (suspend/quarantine/decommission). Reinstating a suspended or quarantined agent restores gate access, but not mandates or SOP assignments revoked meanwhile. Decommission retires the agent: it revokes every active mandate and unassigns every SOP, and it is final — an implementation MUST NOT reinstate a decommissioned agent, nor lower its containment to suspended or quarantined (which would make it reinstatable); such a request is refused AGENT_DECOMMISSIONED (HTTP 409). Its work is taken over by a newly provisioned agent.

7.1.3. "All actions" includes the ones already authorized: an unclaimed hold of a contained agent cannot be claimed or captured, and is voided, so a reinstatement never revives an authorization granted before the containment (8.7.17).

7.2 Operating modes

7.2.1. Four rungs, least to most autonomous: read_only · restricted · supervised · autonomous.

7.2.2. read_only denies any value-bearing action up front (MODE_READ_ONLY).

7.2.3. restricted and supervised do not deny. They impose an escalate floor applied after deterministic evaluation: an action the rules would otherwise permit is routed to a human instead. A rule-driven block or escalate already outranks the floor, so applying it earlier would only mask a more specific reason.

7.2.4. The effective rung is the operator's manual pin when set, otherwise the trust-derived rung. Mode changes SHOULD be audited.

7.3 Reassessment

7.3.1. A material change to an agent's authority (for example a large increase in a payment cap) invalidates its current assurance. A flagged agent's value-bearing actions escalate with REASSESSMENT_PENDING until an owner clears the flag.

8. The authorize protocol

8.1 Endpoint

POST /policy/mandate/authorize                          (PUBLIC, unauthenticated)
POST /policy/mandate/authorize/{authorizationId}/capture
POST /policy/mandate/authorize/{authorizationId}/void

The gate is public by design: any counterparty may check any agent's authority. Authority to act comes from the mandate, not from an API key.

8.2 Request

{
  "agentDid":  "did:hedera:testnet:...",
  "action":    "flight-purchase",
  "amount":    150,
  "currency":  "USD",
  "merchant":  "skyward-air",
  "resource":  "crm.contacts",
  "jurisdiction": "SG",
  "itinerary": { "tool": "book-flight", "riskLevel": "low" },
  "nonce":     "b1c2…(8–128 chars)",
  "issuedAt":  "2026-07-10T05:12:00Z",
  "signature": "<hex Ed25519>"
}

• merchant and resource are top-level signed fields (§8.3.1), each optional and each the empty string in the signed message when absent. resource names what the action touches and is checked against a resource-scoped mandate. The signed values are applied last, so they always take precedence over a same-named key in the unsigned itinerary: a resource placed there cannot satisfy a resource scope.
• jurisdiction (optional, ISO 3166-1 alpha-2) is a top-level signed field too; a request that carries it is signed over the v2 message (§8.3.12). It is the only jurisdiction the gate enforces — one placed in the itinerary is ignored.
• itinerary carries request context — the atom inputs beyond the signed core. It is unsigned: every value in it, riskLevel included, is an agent's own claim and is treated as one (§6.3).
• amount and currency may be omitted together for a non-financial action; a mandate that carries a spend constraint still requires a real amount.
• nonce is single-use; issuedAt bounds freshness.
• An optional trace object correlates a multi-step workflow.

8.3 Canonical signed message

8.3.1. The signature MUST be an Ed25519 signature over the UTF-8 string formed by joining these eight fields, in this order, with | (U+007C), substituting the empty string for an absent merchant or resource:

agentDid | action | amount | currency | merchant | resource | nonce | issuedAt

8.3.2. Verifiers MUST reconstruct the message from the fields received, never trust a client-supplied message, and verify against the key resolved from agentDid.

The three clauses that follow exist because each fails as SIGNATURE_INVALID and as nothing else — a well-formed request, a correct key, and bytes that simply differ from the ones the verifier rebuilds.

8.3.3. Private key encoding. Managed provisioning issues the key as hex-encoded DER PKCS#8 (ASN.1 SEQUENCE tag 30), not a raw 32-byte seed. An implementation SHOULD accept either and MUST NOT assume the raw form.

8.3.4. Number stringification. amount is signed as text, so its rendering is part of the protocol. The canonical rendering is ECMAScript String(n): an integral value carries no fractional part (150.0 → "150"). Languages whose default float formatting keeps a trailing .0 MUST normalise. The disagreement is not only the trailing .0: outside 1e-6 ≤ |n| < 1e21 ECMAScript uses exponent form with its own spelling (5e-7 is "5e-7", 1e21 is "1e+21"), and below 1e-4 a language's default may already differ — Python's repr(0.00005) is "5e-05" where ECMAScript writes "0.00005". A verifier reconstructs this text from the JSON number it parsed, so an integer beyond 2^53 is signed as the double a JSON parser holds, not as its exact digits. Values ≥ 1e21 SHOULD NOT be sent.

8.3.5. Field identity. Every field is signed as the literal string transmitted. Any RFC 3339 rendering of issuedAt a verifier can parse is acceptable, but the signed and transmitted renderings MUST be byte-identical. Formatting a timestamp twice — once for the message, once for the body — is the common violation, and at second precision it fails only when a second happens to tick between the two calls.

8.3.6. A verifier MAY attach a non-normative hint to a SIGNATURE_INVALID verdict naming §8.3.3–§8.3.5 as usual causes. The hint is diagnostic only and MUST NOT enter the digested decision content.

8.3.7. A verifier MAY distinguish a request that verifies against a prior canonical message shape (e.g. the seven-field message from before resource existed) from a genuinely invalid signature, returning CLIENT_PROTOCOL_VERSION_UNSUPPORTED instead of SIGNATURE_INVALID — still refusing the request either way, but naming the real cause (an outdated client) rather than implying a broken or rotated key.

8.3.8. Conformance vectors. docs/protocol/authorize-vectors.json publishes known-answer vectors for the signed message: for each, the eight input fields, the exact message, and the Ed25519 signature a fixed public test key produces over its UTF-8 bytes (Ed25519 is deterministic, so every implementation must reproduce the same bytes). The vectors cover the cases that have each broken a client — an integral float (150.0 → 150), a fractional amount, a sub-cent amount (0.00005), the exponent forms (1.5e-7, 1e+21), an integer beyond 2^53, an amount near 1e21, an absent merchant and resource, resource alone, a literal | and \ in a field, and non-ASCII text. An implementation SHOULD reproduce every vector before it is trusted with a real request.

8.3.9. Payload binding (optional). The eight signed fields do not cover a payee, an account number, a passenger list, a route — every other field a real tool takes. A gateway can compare amount, merchant and resource in what it forwards, but a field the signature never mentioned is either refused (the tool cannot be used) or allowed and unbound. An agent that wants the WHOLE payload held to what it authorized signs a digest of it:

payloadDigest    = "sha256:" + lower-case-hex( SHA-256( UTF-8( canonical(payload) ) ) )
payloadSignature = Ed25519( UTF-8( MAGP-PAYLOAD-v1 | agentDid | action | nonce | issuedAt | payloadDigest ) )

• canonical is RFC 8785 (JSON Canonicalization Scheme): object keys sorted by UTF-16 code unit, no insignificant whitespace, ECMAScript number and string serialisation (§8.3.4 applies to every number in the payload). The input is JSON. undefined, NaN, Infinity, functions, BigInt and an unpaired surrogate are refused, not normalised: two languages would normalise them differently, and a digest they compute differently is a binding that silently never matches. A payload nested deeper than 32 levels or larger than 256 KiB once canonical is refused too. The digest is of the JSON the executing side RECEIVES, so a value a language holds differently from JSON (a Python 250.0, an integer beyond 2^53) is digested as the JSON number it becomes.
• The fields are escaped exactly as in §8.3.1, and the message is domain-separated from the §8.3.1 message and from the service messages of §8.7.6: a signature made for one purpose cannot be replayed for another. It names the agent, action, nonce and issuedAt of the authorize request it accompanies, so a digest cannot be lifted from one authorization onto another.
• payloadDigest and payloadSignature are two optional top-level request fields, both or neither. They are not a ninth field of §8.3.1, which every existing client signs as eight; a request that carries neither is exactly what it always was.
• A verifier MUST, once the §8.3.1 signature verifies (check 5, §8.5), verify the payloadSignature under the same key, and MUST block a request whose binding is present but not valid — a digest with no signature, a signature with no digest, a digest that is not sha256: and 64 lower-case hex, or a signature that does not verify — with PAYLOAD_BINDING_INVALID. A digest nobody signed binds nothing, so it is refused, never stored.
• The verifier MUST store the digest with the hold, and with an escalation when the action is held for a human, so that an approved hold keeps it.
• Acknowledgement. An allow, observe or escalate verdict for a request that carried a binding MUST state the digest the authorization is bound to (data.payloadDigest, null for an unbound one), outside the digested decision content. The binding is not covered by the §8.3.1 signature, so a hop could strip it. An agent that sent a digest MUST treat a permit or escalation whose payloadDigest is not the digest it sent — including an absent one — as not bound: refuse it (PAYLOAD_BINDING_NOT_CONFIRMED) and release the hold it was given.
• A reviewer's MODIFY decision (§10) changes the action the agent signed, so the hold it mints carries no digest until the agent binds the payload of the action that will run (§8.3.11). The review's status reports payloadBound (a boolean, present only when there is a hold) so the agent knows it still has to bind.
• Owner requirement. A mandate's permission may carry requirePayloadBinding: true (issued with the mandate, carried in the signed mandate, never dropped by a delegation, §5.4). For such an action the verifier MUST block a request that carries no binding — after the §8.3.1 signature verifies, so only the agent learns the setting — with PAYLOAD_BINDING_REQUIRED, and MUST refuse to grant a claim (§8.7.11) on a hold that carries no digest, with the same code, until the agent has bound one (§8.3.11). Without it, binding stays the agent's or the executor's choice: an agent, or a hop that strips the two fields, can leave a hold unbound.
• The comparison that gives the binding its force is made at the claim (§8.7.11).

8.3.10. Payload-binding vectors. docs/protocol/payload-binding-vectors.json publishes known-answer vectors for §8.3.9: canonical forms and digests (key order, whitespace, numbers in every exponent form, integers beyond 2^53, string escapes, non-ASCII text, key order beyond the Basic Multilingual Plane), inputs that MUST be refused, and complete bindings — message and the Ed25519 signature a fixed public test key produces over it. The same file holds the vectors for §8.3.11.

8.3.11. Binding a payload to a hold that already exists. A hold can exist with no digest: a reviewer's MODIFY changes the action the agent signed (§8.3.9), so the hold minted for the modified action has none. The agent binds the payload of the action that will run with

POST /policy/mandate/authorize/{authorizationId}/payload-binding
{ agentDid, action, nonce, issuedAt, payloadDigest, payloadSignature }
payloadSignature = Ed25519( UTF-8( MAGP-PAYLOAD-REBIND-v1 | agentDid | action | authorizationId | nonce | issuedAt | payloadDigest ) )

The endpoint is public: the agent's signature is the credential, exactly as for /authorize.

• The message is the §8.3.9 message with the authorization id added, under a domain of its own (MAGP-PAYLOAD-REBIND-v1, escaped as §8.3.1). It names the hold, so a digest cannot be lifted onto another one, and no signature made for one of the two messages can verify as the other.
• The verifier MUST check that the hold exists; that payloadDigest is sha256: and 64 lower-case hex; and that payloadSignature verifies under the key agentDid resolves to — and only THEN say anything about the hold: that it was issued to agentDid and (when its mandate names an action) to action, so an unauthenticated caller cannot probe a hold's owner or action by authorization id. It MUST then check that issuedAt is fresh and consume nonce once, in that order, so a forged request cannot burn a victim's nonce.
• An agent that is contained (suspended, quarantined or decommissioned, §7.1) is refused with its containment code (AGENT_SUSPENDED, AGENT_QUARANTINED, AGENT_DECOMMISSIONED, 403): it is denied everything at /authorize and does not get to keep arranging what its existing holds will execute. Checked once the signature has proven it is that agent asking, so a stranger learns nothing about the agent's status.
• It MUST apply the digest only while the hold is live, unclaimed and carrying no digest, atomically against a claim and against a second binding. A digest is never overwritten.
• The same digest already on the hold is an idempotent success (200, alreadyBound: true): a retry of a binding whose response was lost — but only for a hold that is otherwise still live; a voided or lapsed hold is reported as such first. A different digest is refused.
• The response echoes the digest it now holds (data.payloadDigest). An agent MUST treat a success that does not echo the digest it sent as not bound.

A hold that was bound at authorize time cannot be re-bound. Binding does not change what the hold authorizes (amount, merchant, action): it only names the payload the agent is willing to have executed under it.

8.3.12. Signed jurisdiction (message v2). A request MAY carry a top-level jurisdiction: an ISO 3166-1 alpha-2 code, sent upper-case. A request that carries it MUST be signed over the v2 message — the eight §8.3.1 fields, then the literal version tag MAGP-AUTH-v2, then the jurisdiction exactly as transmitted, ten fields, each escaped as in §8.3.1:

agentDid | action | amount | currency | merchant | resource | nonce | issuedAt | MAGP-AUTH-v2 | jurisdiction

• A request that does not carry it is signed over the §8.3.1 message, byte for byte as before: every existing client keeps verifying.
• A verifier MUST choose the message from the request itself — jurisdiction present → v2, absent → v1 — and MUST NOT try the other. Adding the field to a v1-signed request, changing it, or stripping it from a v2-signed one therefore fails SIGNATURE_INVALID. A present value that is not two ASCII letters is refused (MALFORMED_REQUEST).
• The effective jurisdiction of a request is, in order: the country the mandate's owner registered for the request's payee (the signed merchant's active entries in the owner's payee directory, PUT /policy/payees/country), when it has one — the registry is authoritative; else its signed jurisdiction, upper-cased; else none. It is the ONLY value the gate enforces: the mandate's allowed-jurisdictions term (an mm:jurisdiction isAnyOf constraint) and the jurisdiction-not-allowed atom are both judged on it. An itinerary jurisdiction / mm:jurisdiction is the agent's unsigned word and is ignored for enforcement.
• A registered country stands in for a missing signed value (so a registered payee satisfies the requirement below). A signed jurisdiction that differs from it — or entries for one payee that name more than one country — is blocked JURISDICTION_MISMATCH, a hard block, whether or not the mandate restricts jurisdictions. The decision record's jurisdiction control names the source (signed | registered), and the rule context labels the value agent_signed or authoritative accordingly.
• When the mandate restricts jurisdictions for the action, or an enforced (non-observe) SOP or Standard molecule judges jurisdiction-not-allowed, a request with no effective jurisdiction is blocked JURISDICTION_REQUIRED; one outside the mandate's list is blocked JURISDICTION_NOT_ALLOWED. Both are hard blocks and outrank an escalate (§8.5). With neither a restriction nor such a rule, a request behaves exactly as before, with or without the field.
• The verifier MUST store the signed jurisdiction with an escalation; a reviewer cannot change it. An approval or a MODIFY (§10) resolves the effective jurisdiction again from it and the payee registry AS OF the approval — so an owner who changed the payee's country since the review opened is heard: a stored signed value that now contradicts it is refused JURISDICTION_MISMATCH. With no effective jurisdiction, a review under a jurisdiction-restricted mandate, or under an enforced jurisdiction rule, is refused APPROVAL_INPUT_UNAVAILABLE.
• docs/protocol/authorize-v2-vectors.json publishes known-answer vectors for the v2 message under the §8.3.8 test key; a separate file, so a client that pins the eight-field vectors keeps passing until it implements v2.
• POST /magp/private-authorize (§15) is unchanged: it never sees the jurisdiction, and proves membership in the mandate's list in zero knowledge.

8.3.13. Context signature (optional). The itinerary, trace and materiality are not in the signed message, so anything between the agent and a verifier can rewrite them. A request MAY carry envelopeSignature: an Ed25519 signature, by the same key as signature, over the UTF-8 bytes of the request's envelope hash — the lower-case hex SHA-256 of the GovernanceEnvelope built from the request as transmitted (no defaults applied; context = the itinerary, omitted when absent or null, present when {}), minus its integrity block, with object keys sorted recursively and undefined values dropped. resource and jurisdiction are not in it; the §8.3.1 / §8.3.12 message signs them.

• A verifier MUST check a present envelopeSignature after signature (§8.5 step 5) and before any rule reads the context, over the very itinerary object it will evaluate. One that does not verify — the context was altered after signing, or it was signed with another key — is refused CONTEXT_SIGNATURE_INVALID, fail closed.
• Absent, the request is judged as before: the signature is optional on the wire (the reference clients send it by default). A relay can also strip it, so a counterparty that relies on the context SHOULD require it, refusing an unsigned context with CONTEXT_SIGNATURE_REQUIRED. That code is receiver-only: the gate has no such option.
• It attributes the context to the agent; it does not make it true (§17.4).
• docs/protocol/context-signature-vectors.json publishes known-answer vectors under the §8.3.8 test key: the request, the canonical envelope, its hash and the signature.

8.3.14. Argument policy (optional). The signed fields and the rules do not see the arguments a tool runs with, so a call within its cap can still carry a field nothing judged. A mandate's permission MAY carry arguments: { allow, sensitive? }, issued with the mandate and carried in the signed bundle:

• allow lists the JSON Pointer (RFC 6901) paths the arguments may carry; a listed path permits everything below it, and a * segment matches any one key or array index. The root is not a path. Every value in the arguments MUST sit at or below a listed path, or the call is refused ARGUMENT_NOT_ALLOWED, naming the offending path. Keys are compared exactly: a renamed or re-cased key is refused.
• sensitive lists { path, mode }. Before the call leaves the verifier, a value at a redact path is replaced with "[REDACTED]", and a value at an hmac path with hmac-sha256: followed by the lower-case hex HMAC-SHA256, under the executor's own key, of the value's canonical JSON (object keys sorted). Where both apply, redact wins. A verifier with no key MUST refuse a call that needs one (SENSITIVE_ARGUMENT_UNPROTECTED) rather than send the value in the clear. The hash is over the value alone, so under one key an equal value hashes equally in every field and tool: that is what lets a tool match values it cannot read. An owner who does not want values linked uses redact.
• It is enforced by the executor that holds the arguments (the MCP guard; the HTTP gateway's JSON body; the A2A guard, where a task's arguments are its one data part), not at authorize, on a verdict that could run the call and before any claim (§8.7.11), so a refused call spends no hold. Arguments it cannot check — not a single JSON object, deeper than 32 or larger than 10,000 values, not given to it, or a malformed policy — are refused ARGUMENTS_UNCHECKABLE. Every policy covering the action applies.
• An agent that runs its own tool in-process holds the tool to it too. The gate never sees the arguments, so it names the policy instead: a permit carries argumentPolicies (the action's policies, [] for none: always stated, so an agent can tell "none" from an issuer that predates the field), and so does an approved escalation's status (§9a), so a resume is held to the same policy before its one resume is taken (§9a.6). This is cooperative, as the in-process wrapper is; the boundary remains an executor in another process.
• The owner may set, change or remove a deployed agent's policy for one action; like any change to the mandate's terms it reissues that mandate (§8.7.15). A delegated mandate may only narrow its delegator's policy.
• The payload digest (§8.3.9) is taken over the arguments the agent sent, which is what it signed; the tool receives the sanitized copy.
• An executor that predates this field ignores it. An owner relying on it SHOULD require executors that state they enforce it (checksArguments).

8.4 Response

200 on a permitting disposition; 403 on a refusing one. Body is { success, message, data } where data is the verdict:

{ "decision": "allow", "reasonCode": "AUTHORIZED",
  "authorizationId": "…", "remaining": 350, "proofRef": "…",
  "expiresAt": null, "escalationId": null,
  "envelopeId": "env:…", "envelopeHash": "sha256:…" }

proofRef is the ledger anchor of the hold. An implementation MAY anchor after answering, so that the ledger round trip is not part of the request; proofRef is then null in the response, and the anchor is recorded on the hold when it lands. The same applies to proofRef on capture. A hold refused at the cap check is not anchored. An implementation that anchors after answering MUST NOT lose an anchor it owes.

8.5 Order of checks (normative)

A conformant evaluation MUST apply these in order and MUST stop at the first that fails, returning its reason code — with one exception: an escalate at steps 11–12 is not a failure that stops evaluation (see Escalation never outranks a hard block below).

Notes on the ordering, each of which is a security property rather than an accident:

• Steps 1–3 precede signature verification because they are questions about the policy, not the requester.
• Nonce consumption (8) MUST follow signature verification (5), or a forged request could burn a victim's nonce.
• Containment (6) precedes everything action-specific, so a contained agent cannot reach evaluation at all.
• The mode escalate floor (15) follows deterministic evaluation, so a specific rule denial is reported instead of a generic mode reason.
• Escalation never outranks a hard block. A Standard or SOP molecule that escalates (step 11 or 12) — including CONTEXT_UNVERIFIABLE, a rule that could not get a trustworthy value for a field it needs, such as a missing riskLevel (§6.4.3) — MUST NOT end evaluation. The escalate is carried; the remaining rule stages and the mandate evaluation (13) still run, and any block, suspend or quarantine among them (an SOP cap, the mandate's per-transaction or cumulative cap, an action the mandate never granted) is the verdict. The carried escalate is the verdict only when everything after it would otherwise permit (or itself escalates), and it keeps its own reason code. Escalation can therefore only lift a would-be permit to human review, never downgrade a block: otherwise an agent could turn any hard cap into a review by omitting a field. A molecule's own block still stops evaluation at its stage, as before.
• Jurisdiction is one resolved value, judged in three places. After the signature (5) — which covers a top-level jurisdiction through the v2 message (§8.3.12), a malformed value being MALFORMED_REQUEST — the gate resolves the request's effective jurisdiction, in this order: (a) the country the mandate's owner registered for the signed merchant in the payee directory, when it has one — authoritative; (b) else the signed jurisdiction, upper-cased; (c) else none. The itinerary's jurisdiction / mm:jurisdiction is removed before any rule or the mandate sees the context, so it can neither satisfy nor fail a check. Three refusals follow, all hard blocks that outrank a carried escalate:
  • JURISDICTION_MISMATCH (step 8, before any rule runs): a signed value that differs from the registered country, or a registry naming two countries for one payee. It applies whether or not anything restricts jurisdictions.
  • JURISDICTION_REQUIRED: no effective jurisdiction while one is needed — the mandate's allowed-jurisdictions term (step 13), or an enforced (non-observe) Standard or SOP rule that judges jurisdiction-not-allowed (end of step 12; the atom itself does not fire on a missing value, so without this the rule would pass silently).
  • JURISDICTION_NOT_ALLOWED (step 13): an effective jurisdiction outside the mandate's list. (An effective jurisdiction outside an SOP/Standard allow-list fires the molecule, with that molecule's own disposition and code.)
• An approval cannot exceed the hard caps either (§10). Approving an escalation, or a reviewer's MODIFY that re-enters the gate, re-runs the deterministic layers on the request as it stands at the moment of the decision, with every input the live gate has — the mandate (1: still active and still the agent's current one for the action), the principal (2), Standards compliance (3), the agent's key, containment and mode (4, 6, 7), the rate window (9) including the callCount a rule reads, circuit breakers (10), committed spend, counterparty trust, the Standard and SOP molecules (11, 12) and the mandate (13) with the signed operands, resource included. Only transport authentication (5, 8) is not repeated. Any block-class verdict refuses the approval with that reason code — the review stays pending, and the reviewer may still deny it — and only escalates are disregarded, being what the reviewer is approving. An input that cannot be reconstructed refuses the approval (APPROVAL_INPUT_UNAVAILABLE); it is never skipped. The atomic reservation (16) then still applies (CAP_EXCEEDED).
• The floors of step 15 only ever lift a permit to escalate, never downgrade a stricter verdict. The spend-anomaly and runtime-assurance floors are opt-in.
• Reservation (16) is last and atomic: it is the only step that mutates shared budget, and a lost race MUST return CAP_EXCEEDED.
• Steps 9 and 10 are secondary controls (§9).

8.6 Dispositions

8.6.1. Six: allow · observe · block · escalate · suspend · quarantine.

8.6.2. observe permits the action and flags it for monitoring. It does not fail fast; it is collected across the rule and SOP layers and folded in most-restrictive-wins, lifting an otherwise-allow verdict.

8.6.3. allow and observe permit execution. Everything else MUST stop the action.

8.6.4. escalate is a hold, not a denial — the action waits for a human (§10). A caller MUST NOT treat it as permission, and an agent MUST NOT self-approve.

8.6.5. An unknown disposition MUST be treated as a block.

8.7 Spend cap and settlement

A permitting verdict for a value-bearing action creates a hold: a reservation against the mandate's cap, identified by the authorizationId. This section specifies the hold as the agent and the executing counterparty see it.

8.7.1. On a permitting verdict for a value-bearing action the evaluator MUST atomically reserve the amount against the mandate's cap.

8.7.2. After the real-world charge settles the actor SHOULD capture with the actual amount. A hold that no counterparty has claimed expires and auto-voids.

8.7.3. A claimed hold is a commitment. Once a counterparty has claimed a hold for execution (POST /policy/mandate/authorize/{id}/effect/dispatching) the effect may already have happened, so the reservation MUST remain against the cap until it is settled or the claimer releases it. It MUST NOT lapse with the hold window, and only the claimer may lower or release it.

8.7.4. Settling a hold. POST .../capture { amountCharged, bookingRef?, settlementTxHash?, claimToken? } settles a hold; POST .../void { reason?, claimToken? } releases one. The authorization id is not a credential (the agent hands it to every Service it asks to execute), so:

• Settling a claimed hold below its authorized amount, or voiding it, MUST come from its claimer: its signature (8.7.6) or, for an anonymous claim, the claim token that claim returned (data.claimToken). Settling at the full authorized amount needs no token.
• Settling or voiding an unclaimed hold MUST come from the hold's own agent, with agentProof: { agentDid, nonce, issuedAt, signature } — its signature over MAGP-SETTLE-v1|verb|agentDid|authorizationId|nonce|issuedAt|...fields (verb capture or void; fields as in 8.7.6; each escaped as in 8.3.1), fresh and single-use like an authorize request — or from a counterparty signing as itself (8.7.6) that the owner's registry (8.7.10) would let claim it. An anonymous settlement of an unclaimed hold MUST be refused.

8.7.5. A claim is single-use and MUST be arbitrated atomically: of any number of simultaneous claimants exactly one succeeds. Every other claim of that authorization MUST be refused AUTHORIZATION_ALREADY_CLAIMED (HTTP 409) and carry no claim token. EFFECT_TRANSITION_CONTENDED means the claim did not land and the hold is still claimable; the claimant SHOULD retry it once. The hold window is enforced by the claim itself.

8.7.6. Counterparty identity. A claim token is a bearer secret: it proves "I made the claim", not who the claimer is. A counterparty that holds a key SHOULD instead sign its settlement calls with a did:key or did:hedera identity it controls. The signed message is MAGP-SERVICE-v1|action|authorizationId|field…|nonce|issuedAt, where action is one of claim, dispatched, unknown, capture, void, refund, reconcile, and the fields are those of the call:

Each field is escaped for \ and |. The signature is Ed25519, carried in the headers x-magp-service-did, x-magp-service-nonce, x-magp-service-issued-at and x-magp-service-signature.

• The verifier MUST check the signature against the key the DID commits to, reject a stale or future issuedAt, and consume the nonce once. An identity that fails any check MUST be refused with a COUNTERPARTY_* code; it MUST NOT fall back to anonymous handling.
• The identity that signs the claim is the claimer. Every later call that lowers or releases the hold MUST be signed by the same identity (COUNTERPARTY_MISMATCH, HTTP 403, otherwise). No claim token is issued to an authenticated claimer.
• An implementation MAY require an authenticated claimer for every claim (COUNTERPARTY_AUTH_REQUIRED).

Refund. POST .../refund { amount?, reason?, claimToken? } records a reversal of a captured hold: no money moves, but the cumulative cap counts less. It MUST be accepted only from the hold's claimer (its refund signature, or its claim token), the mandate's owner, or a platform operator (COUNTERPARTY_MISMATCH otherwise).

8.7.7. Idempotent claim. A claimant whose claim response was lost MAY retry with the same Idempotency-Key header: 32–128 characters of [A-Za-z0-9._:~-] with at least 128 bits of randomness, chosen per claim call. A malformed key, or one that contains the authorization id, is refused IDEMPOTENCY_KEY_INVALID (400). A retry by the same identity while the effect is still dispatching is answered 200 with the original grant and replayed: true; once the effect has moved on it is an ordinary AUTHORIZATION_ALREADY_CLAIMED. A gateway SHOULD send the authorization id to the upstream as its Idempotency-Key, and MUST NOT forward one the agent supplied.

8.7.8. Outcome lookup. GET /policy/mandate/authorize/{id}/effect (public, keyed by the authorization id) answers what became of an authorization:

retrySafe is the only safe basis for issuing a fresh authorization for the same intent. To retry a not_started hold, void it first and read not_executed. An unknown or in_flight outcome MUST NOT be retried blindly. The response also carries claimed, claimedAt, currency, authorizedAmount, settledAmount and settlementEvidence (8.7.9); never a claim token or the claimer's identity.

Capture and void are not idempotent the way a claim is. A capture of a hold that is no longer held answers 409 NOT_HELD; a void of one answers 200 { voided: false, reasonCode: "NOT_HELD" }. A caller that retries either after a timeout or a 5xx MUST read the outcome first: the first call has usually landed.

A refused capture, void or refund is a 4xx whose message is the bare reason code and whose data is { captured | voided | refunded: false, authorizationId, reasonCode, detail }. A client MUST branch on reasonCode, never on detail. The same code has the same HTTP status on every call. The codes are listed in Appendix A.

8.7.9. Authorized and settled amounts. The authorized amount is recorded once and never overwritten; the settled amount is what the cumulative cap then counts, and MUST NOT exceed it (AMOUNT_EXCEEDS_AUTHORIZED). Every settlement states what it rests on as settlementEvidence: unattested, unclaimed_lowered, counterparty_attested, independently_confirmed, operator_resolved or reconciled_at_authorized. Where the deployment observes the remote system, a claimer's lowered settlement or release MUST be supported by that observation, and is refused otherwise (SETTLEMENT_NOT_CONFIRMED, SETTLEMENT_AMOUNT_MISMATCH, SETTLEMENT_NOT_FOUND); the claimer can still settle in full or mark the effect unknown.

8.7.10. Trusted counterparties. An owner MAY register the counterparty DIDs that may claim their holds, each optionally limited to named merchants. An owner with any registered counterparty — and every hold of a mainnet agent — accepts only a claim signed by an active, registered identity (COUNTERPARTY_AUTH_REQUIRED, COUNTERPARTY_NOT_REGISTERED, COUNTERPARTY_NOT_ALLOWED_FOR_MERCHANT, HTTP 403). A refused claim leaves the hold claimable.

An entry's purpose is claim or report (a Service registered only to report what it did, 16.4). A report entry is never a claimant, except for an approval claim (8.7.18) of a zero-amount hold of an agent it was registered for.

A registration carries the service's own acceptance: the service signs MAGP-COUNTERPARTY-ACCEPT-v1|<registrant principal DID>|<service DID>|<purpose>|<nonce>|<expiresAt> (fields escaped as in 8.3) over a challenge the owner obtained, with the key its DID embeds. A service MUST sign only a well-formed acceptance naming its own DID — never free text (16.2).

8.7.11. Payload comparison at the claim. A hold whose authorization carried a payload binding (8.3.9) is claimed with the digest of exactly what the claimant is about to execute, in the x-magp-payload-digest header and, for an authenticated claim, as the signed field payload=<digest>. The issuer compares it with the digest it stored at authorize, before recording the claim:

Every refusal leaves the hold unclaimed. The comparison is against the digest the issuer stored, never only against the signed request the executor was handed.

The executor SHOULD also compare the digest of what it will execute with the signed request before it claims. It MUST refuse, rather than skip the check for, a payload it cannot digest (PAYLOAD_NOT_CANONICALIZABLE), and MUST NOT forward a URL query string, path parameter or fragment the signature does not cover (QUERY_NOT_BOUND) unless its operator listed that key as unbound. A JSON body that two readers could read differently — a repeated key, a number a double cannot hold exactly, invalid UTF-8, a byte-order mark — MUST be refused, not digested.

8.7.12. Who may push a claimed hold along. Marking an outcome unknown (POST .../effect/unknown) and asking for reconciliation (POST .../effect/reconcile) are accepted only from the claimer, the mandate's owner, or an operator (COUNTERPARTY_MISMATCH, RECONCILE_NOT_PERMITTED).

8.7.13. Owner-forced reconciliation. An owner MAY force a claimed hold into reconciliation (POST .../effect/force-reconcile). The claimer then loses every power over it, including capture and void (HOLD_UNDER_RECONCILIATION, 409), and the hold settles only on what reconciliation establishes.

8.7.14. Payee directory. An owner MAY register the accounts each merchant is paid into. A lowered settlement for a merchant with a registered account MUST name one of them as payTo (PAYEE_NOT_REGISTERED, PAYEE_NOT_VERIFIED).

8.7.15. Revocation and holds. Revoking a mandate — directly, through its delegation chain (5.4.9), by reissue or by decommissioning the agent — releases every hold under it that no counterparty has claimed, and leaves every claimed hold to settle by the claimed-hold rules. A claim or capture of an unclaimed hold under an inactive mandate, or under a delegated mandate with an inactive ancestor, is refused MANDATE_REVOKED or DELEGATION_CHAIN_BROKEN (409).

8.7.16. Rules changed while a hold waits. A change to the agent's SOPs or bound Standards applies to holds that are not yet claimed. Before an unclaimed hold is claimed or captured, the gate MUST evaluate the current rules over the context the hold was granted on. If they no longer permit it, the claim is refused AUTHORIZATION_RULES_CHANGED (409) and the hold voided; if they cannot be evaluated, it is refused CONTROL_UNAVAILABLE (409) and the hold left unclaimed. A hold minted by a person's approval is not refused for an escalate. A claimed hold is never re-judged.

8.7.17. Containment and holds. Containment (7.1) stops what the agent was already allowed to do. A claim or capture of an unclaimed hold of a contained agent is refused with the containment code — AGENT_SUSPENDED, AGENT_QUARANTINED or AGENT_DECOMMISSIONED (409) — and the hold voided, whoever offers to execute it. Reinstating the agent does not revive the hold.

8.7.18. Executing an approved escalation. An executor that re-evaluates the agent's policy reaches escalate again for a request a person has already approved. When its own verdict is escalate and the request carries an authorizationId, the executor MAY claim that hold with requireHumanApproval: true. The issuer grants such a claim only for a hold minted by a person's approval, and otherwise refuses ESCALATION_NOT_APPROVED (409). Every grant carries approvedByHuman; the executor MUST permit only on approvedByHuman: true, and only over an integrity-protected channel to the issuer. Only an escalate is lifted this way; a block, suspend or quarantine is never overridden. Every other claim check still applies. A modified approval carries no payload digest, so it is refused PAYLOAD_BINDING_REQUIRED until the agent binds the payload of what will run (8.3.11).

8.7.19. Claim expectations. A claim SHOULD state what the executor is about to execute as expect: { agentDid, action, amount, currency, merchant }. The issuer MUST compare these with the hold before granting and refuse a difference — AUTHORIZATION_AGENT_MISMATCH, AUTHORIZATION_ACTION_MISMATCH, AUTHORIZATION_AMOUNT_MISMATCH, AUTHORIZATION_CURRENCY_MISMATCH or AUTHORIZATION_MERCHANT_MISMATCH (403) — leaving the hold unclaimed. A malformed expect is refused CLAIM_EXPECTATION_INVALID (400); an unknown key is ignored. An executor that still finds a mismatch after a grant MUST release the claim before refusing.

8.7.20. Approved-context binding. A hold a person approved is for the request that person reviewed, including its context. The approved context's digest is sha256: + hex SHA-256 of the RFC 8785 canonical JSON of { "MAGP-APPROVED-CONTEXT-v1": context } (an absent context is {}; for a MODIFY that changed the itinerary, the reviewer's itinerary), pinned by docs/protocol/resume-binding-vectors.json (contextVectors). A claim MUST state the digest of the context it is about to execute as expect.contextDigest. For a person-approved hold the issuer refuses a difference AUTHORIZATION_CONTEXT_MISMATCH (403) and a missing digest AUTHORIZATION_CONTEXT_REQUIRED (403). The grant names the digest it compared (contextDigest); the executor MUST release the claim and refuse when it differs from its own. An executor that runs a body other than the itinerary SHOULD require payload binding (8.3.9).

8.7.21. In-process resume claim. An SDK that runs an approved escalation's tool in its own process takes the approval's one resume at the issuer before it runs: POST /policy/escalations/{escalationId}/resume-claim with { agentDid, nonce, issuedAt, requestDigest, contextDigest, signature }. requestDigest is the resume binding digest (MAGP-RESUME-BIND-v1) and contextDigest the approved-context digest (8.7.20), both computed from the SDK's own arguments. The agent signs MAGP-RESUME-CLAIM-v2|escalationId|authorizationId|agentDid|requestDigest|contextDigest|nonce|issuedAt (each field escaped as in 8.3), pinned by docs/protocol/resume-binding-vectors.json (claimVectors). The issuer refuses a request difference ESCALATION_REQUEST_MISMATCH (403) and a context difference AUTHORIZATION_CONTEXT_MISMATCH (403). Exactly one valid claim is granted; others are refused AUTHORIZATION_IN_USE (409) while the resume may still be running, and AUTHORIZATION_VOIDED or AUTHORIZATION_ALREADY_USED (409) once its hold is voided or settled. An issuer that requires v2 says so on the escalation's status (resumeClaimVersion: 2); an SDK MUST sign v2 when it is present.

9. Secondary controls

Controls that protect the system rather than express authority. Both are optional. A deployment chooses whether they fail open or closed when they cannot run; failing closed, a rate counter or breaker lookup that errors blocks with CONTROL_UNAVAILABLE, and the spend-anomaly and assurance floors escalate with it. A request MUST NOT be able to cause that error itself: a scope value that cannot be looked up is refused MALFORMED_REQUEST.

9.1 Rate limits

9.1.1. Per agent, max calls per rolling windowSec. max = 0 disables it.

9.1.2. The running count is server-derived and MUST be injected into rule context signed-last, so a rule-authored rate atom evaluates the same number the built-in ceiling does and an unsigned itinerary cannot shadow it.

9.2 Circuit breakers

9.2.1. Scoped to agent, tenant, tool or counterparty. An open breaker denies with CIRCUIT_BREAKER_OPEN.

10. Escalation resolution

10.1. escalate parks a pending record. No budget is held.

10.2. GET /policy/escalations/{id}/status is public and keyed by the escalation id, which is itself the capability. An agent holds no user token and needs none to ask about its own held action. It returns status, reasonCode, authorizationId, expiresAt, approvals, required, and the digests of 8.7.20; it names no principal and no budget. With an authorization it also reports executed, executedAt and outcome (as GET /policy/mandate/authorize/{id}/effect reports it). status stays approved after the action ran.

10.2a. GET /policy/mandate/{ref}/status is public as a registry read (4.4.2), and minimized: an unauthenticated caller gets policyId, agentDid, status, principalVerified, principalTierReason, allowedJurisdictions, vcHash, mandateStoreRef, anchorRef and expiresAt. The principal's DID and the budget (cap, spent, remaining, byCurrency) are returned only to the mandate's owner. The response says which it is (view: "public" | "owner").

10.3. Approval requires M of N distinct approvers, configurable per agent, defaulting to

1. An approver MAY be required to hold a named role and a minimum authority level.

10.4. On approval the gate re-runs the deterministic checks and mints an authorizationId. Approval does not bypass the budget, nor any hard block: containment, an action the mandate does not grant, a Standard or SOP block (e.g. an SOP per-transaction cap) and the mandate's per-transaction and cumulative caps are all re-evaluated on the escalated request, and any of them refuses the approval with its own reason code (the cumulative cap as CAP_EXCEEDED); the escalation stays pending and may still be denied. Escalates are disregarded — they are what is being approved (§8.5). The minted hold starts its effect lifecycle at authorized, so it is claimable like any other. A MODIFY re-enters the gate under the same precedence.

10.4.1. The re-evaluation uses the gate's inputs as of the approval, never those of the moment the review opened, and every one the live gate uses except transport authentication (signature, freshness, nonce — satisfied by the agent's original request):

• The mandate. It MUST still be active, and for a delegated mandate so must every mandate above it (MANDATE_REVOKED otherwise, DELEGATION_CHAIN_BROKEN for a chain that cannot be walked, 5.4.10), and still the agent's current mandate for the action (MANDATE_SUPERSEDED if a newer one has been issued). Reviews do not migrate to a reissued mandate: a review raised under the old one cannot be approved, and the agent asks again under the new one (10.4.2).
• Principal, compliance and the agent — steps 2, 3, 4, 6 and 7 of §8.5 as they stand now.
• The rate window (§9.1) and circuit breakers (§9.2).
• Committed spend and counterparty trust, applied as server-derived fields (§6.3), so the review's stored itinerary cannot supply them.
• The signed operands, resource included; the unsigned itinerary never stands in for them.
• The jurisdiction (§8.3.12): the stored signed value, resolved again against the payee registry as of the decision. A reviewer cannot change it, and a MODIFY cannot move the action to another jurisdiction.

An input that cannot be reconstructed refuses the approval with APPROVAL_INPUT_UNAVAILABLE; the review stays pending. A MODIFY receives the same inputs; its block closes the review as modified.

10.4.2. Revoking a mandate closes its pending reviews. Every review still pending under a revoked mandate becomes denied, with the reason MANDATE_REVOKED — or MANDATE_SUPERSEDED when the mandate was reissued — and an evidence event is recorded. The status route reports that code as the review's reasonCode, so a polling agent learns it must ask again. A closed review can never be approved (ALREADY_DENIED), and no hold is minted on a revoked mandate.

10.5. An unresolved escalation expires — ESCALATION_EXPIRED. The hold an approval mints carries its own window from the moment of approval.

10.6. Callers MUST poll to resolution and act only on an approved status carrying an authorizationId.

11. Payment execution binding (x402)

11.1. Authorize before pay. Payment MUST be bound to an authorizationId issued by a permitting verdict.

11.2. The binding is amount-exact and single-use. A payment whose amount differs from the authorized amount MUST be refused with AMOUNT_MISMATCH; a reused authorization MUST be refused.

11.3. Settlement is reconciled by capture, carrying the settlement reference.

11.4. No custody. The protocol never holds funds.

12. Effects and reconciliation

12.1. A permitted action has a real-world effect whose outcome may not be known synchronously. Effect state transitions are recorded on a hash-chained ledger: each transition commits to the digest of the previous one plus its own canonical content.

12.2. A verifier MUST reject an invalid transition, a sequence gap, a broken chain link or a digest mismatch — INVALID_EFFECT_TRANSITION, SEQUENCE_GAP, CHAIN_LINK_BROKEN, DIGEST_MISMATCH.

12.3. An effect whose outcome is genuinely unknown is recorded as such rather than guessed, and resolved by reconciliation.

13. Evidence and anchoring

13.1. Every decision MUST produce an evidence record.

13.2. Records MAY be anchored individually or batched. In batch mode records are accumulated, hashed into a Merkle tree, and a single root is anchored.

13.3. GET /magp/evidence/{id}/proof returns an inclusion proof: the leaf, the path, and the anchored root.

13.4. A verifier MUST be able to check inclusion offline, given only the leaf, the proof and the anchored root. Verification MUST NOT require the platform.

13.5. Leaf stability. The set of fields in a leaf is part of the protocol. Adding one changes every digest and invalidates previously anchored proofs; a change to leaf composition is therefore a breaking change (§18).

13.6. Execution Receipt. A second, separate signed-proof artifact, issued after a value-bearing action settles: POST .../capture best-effort issues one binding what was actually charged back to the Action Passport (§8) the action was authorized against (actionPassportId, authorizedPayloadDigest), alongside a digest of what was actually executed (executedPayloadDigest) and whether the two are within the authorized bound (payloadMatch). Unlike the Merkle-anchored evidence above, a receipt is a standalone Ed25519 signature over a canonical (sorted-key JSON) message — verifiable with no anchored root, no Merkle path, just the issuer's published public key (GET /action-passport/pubkey).

• GET /action-passport/receipt/verify/{authorizationId} (public) answers integrityValid (the signature checks out), payloadMatch, outcomeStatus, and settlementEvidence (below) for any relying party, with no authentication and no state about who is asking.
• receiptVersion. The receipt's field set is versioned, and a verifier reconstructs the exact message each version signed, never adding a later version's fields. Version 1 signs executionReceiptId, actionPassportId, authorizationId, agentDid, authorizedPayloadDigest, executedPayloadDigest, payloadMatch, outcomeStatus and issuedAt; version 2 adds settlementEvidence (8.7.9).

14. Decision records and the governance envelope

14.1. Alongside the anchored leaf, an implementation SHOULD record an off-leaf decision record: per-control results, stage timestamps, and the names of context fields evaluated.

14.2. Context field names are recorded; values MUST NOT be. A conformance assessment needs to distinguish "the control held" from "the situation never arose" — a spend-cap clause that never saw an amount was not tested, and scoring it as passed would be a false assurance. The values themselves are the tenant's.

14.3. The governance envelope is a canonical view over the request, carrying an envelopeId and an integrity hash so a caller can bind a decision to the exact action submitted.

14.4. Decision records are best-effort and MUST NOT affect the verdict.

14.5. Where the anchored leaf carries a commitment to the decision record (a single hash covering both, rather than anchoring twice), and the request carried a payload binding (§8.3.9) that has been VERIFIED — never one merely claimed — the payload digest SHOULD be folded into that same commitment, so a verifier holding the anchored digest can also prove which payload the decision was bound to. A new field folded into an existing digest MUST be additive: omitted from the hashed content entirely when absent (never written as an explicit null), so a record with nothing to add digests identically to one computed before the field existed. Anything covered by this digest that has not yet been proven true — e.g. PAYLOAD_BINDING_INVALID, where the very point of the code is that the claimed digest was never shown to be the agent's — MUST NOT be included.

15. Privacy-preserving verification

Optional. Where a counterparty must verify a property without learning the underlying value.

15.1. Range proofs. An amount may be proven within a mandate's cap without revealing it (ZK_AMOUNT_PROOF_INVALID, ZK_JURISDICTION_PROOF_INVALID, ZK_POLICY_OK).

15.1.1. Who may ask, and against which terms. A private-authorize request (POST /magp/private-authorize) MUST be signed by the agent's own DID key, with the same key resolution (including rotated and promoted DIDs), single-use nonce and freshness window as a cleartext authorization (§8.3). The signed message is MAGP-PRIVATE-AUTHORIZE-v1| followed by the hex SHA-256 of the canonical JSON (RFC 8785-style) of agentDid, action, nonce, issuedAt, currency, both commitments, both proofs, transactionCommitment and sessionBindingDigest (absent members as null). Its own domain means a signature made for it never verifies as an authorize signature, or the reverse. transactionCommitment is REQUIRED: a request without one is refused (ZK_TRANSACTION_COMMITMENT_REQUIRED, HTTP 400) before anything else is checked, so every permitting verdict carries a capability bound to the transaction it authorizes (§15.3).

15.1.2. The cap and the jurisdiction allow-list MUST be read from the agent's active mandate for the action, never from the request. The cap is the permission's per-transaction bound (mm:payAmount lteq, else mm:cumulativeSpend), floored to whole units of its currency; the allow-list is an mm:jurisdiction isAnyOf constraint, in its stored order — the allowed-jurisdictions term of §5.2.3. The blind path proves the agent's committed jurisdiction against it and does not consult the payee registry. A request that carries its own cap or allowedJurisdictions MUST be refused (ZK_CALLER_POLICY_REJECTED), not silently re-interpreted. A range proof built against any other cap is refused (ZK_CAP_MISMATCH); a term the mandate carries whose proof is missing is refused (ZK_AMOUNT_PROOF_REQUIRED, ZK_JURISDICTION_PROOF_REQUIRED). A mandate with no jurisdiction term has nothing to prove about jurisdiction — a membership proof is then not evaluated, and the response and capability say so; a mandate with neither term, or with one in a form set membership or a range proof cannot express, is refused (ZK_MANDATE_TERMS_UNSUPPORTED).

15.1.3. A contained agent, an inactive (never issued, or revoked) or expired mandate, a principal whose authority does not hold, and an unmet enforced Standard are refused with the codes a cleartext authorization uses. Because the amount is hidden and nothing is held, an agent whose operating mode routes value to a human is refused (MODE_READ_ONLY, ZK_HUMAN_REVIEW_UNAVAILABLE), as is an action whose mandate requires payload binding (PAYLOAD_BINDING_REQUIRED) — a transaction commitment is not a payload binding.

15.1.4. What a private-authorize verdict does not establish, and MUST state: it reserves no hold, so it does not draw down or check the cumulative budget; it does not evaluate merchant, resource or other constraints, prohibitions, Standards or SOP rules. The response lists these under notEvaluated. A counterparty that relies on it still has to enforce them.

15.2. Selective disclosure. BBS presentations prove selected credential attributes — for example that assurance meets a threshold — without disclosing the rest (BBS_PROOF_INVALID, BBS_KYC_LEVEL_TOO_LOW, BBS_PRESENTATION_OK).

15.3. Capability tokens. A permitting verdict MAY be returned as a signed capability bound to a transaction commitment and a session, verifiable offline. Authorizing transaction A and executing transaction B MUST fail with COMMITMENT_MISMATCH; a capability used outside its session fails with SESSION_MISMATCH; an expired one with CAPABILITY_EXPIRED.

15.3.1. A capability minted by a private authorization (payload v: 2) also names its subject: agentDid, mandateId, action, currency, network, and the mandate terms proven (cap, jurisdictions; null = the mandate had no such term). A verifier SHOULD check at least that agentDid is the agent it authenticated; presented by another agent the capability fails with CAPABILITY_AGENT_MISMATCH, and against a different expected mandate, action or currency with CAPABILITY_SCOPE_MISMATCH. A verifier that requires a subject field MUST fail a capability that lacks it (a v: 1 capability) rather than accept it.

16. Discovery and channels

16.1. HTTPS is the baseline transport. A DID document's serviceEndpoint locates a peer.

16.2. Peers MUST mutually verify DIDs before transacting. A counterparty SHOULD independently re-evaluate a caller's authority rather than trusting that the caller's own guard ran (§3). Mutual verification has each peer sign the OTHER peer's nonce with its own key, so a peer MUST sign only a nonce that is a plain random token (16–128 characters of A–Z a–z 0–9 _ -) and refuse anything else: a nonce that is free text makes the signer an oracle — a malicious peer sends a canonical authorize message (8.3), or a MAGP-SERVICE-v1 claim, as its nonce and obtains a valid signature on it. Every MAGP message that authorizes anything contains |, which a token cannot.

16.3. Whom a Service acts for. A counterparty's re-evaluation (16.2) judges the caller by the caller's own policy — written by the caller's owner. It answers "may this agent do this?", never "is this an agent I act for?". A Service that executes with one owner's credentials (an agent's own tool gateway, an executor holding one owner's API key) MUST therefore also establish that the owner of those credentials admitted the caller:

• Admission. The Service MUST be configured with the agents it acts for, and MUST refuse a validly signed request from any other agent with AGENT_NOT_ADMITTED — after verifying the request signature, and before fetching the caller's policy or claiming any authorization (8.7.6). An unconfigured admission list is a startup error, never "admit everyone"; a malformed one likewise.
• Owner binding. The Service MUST be bound to the principal that owns its credentials (gatewayOwnerPrincipal), a startup error when absent (GATEWAY_OWNER_UNBOUND). The policy bundle names the agent's owning principal (ownerPrincipal, signed with the rest); an admitted agent whose bundle names any other owner, or none, MUST be refused GATEWAY_OWNER_MISMATCH before any claim. An agent of another owner can be admitted only by a bilateral delegation the gateway owner grants — not by its own mandate, and not by being listed.
• Credential profiles. Admission to the Service is not access to every credential it holds: a route, tool or skill MAY admit fewer agents, and an admitted agent outside it MUST be refused CREDENTIAL_PROFILE_NOT_PERMITTED, also before its policy is fetched or anything claimed.

A Service that holds no one owner's credentials — a public tool, or one that resolves each caller's own credential — MAY admit every governed agent, but only by saying so explicitly ('any'), never by omission, and it then takes no owner binding.

16.4. Reporting what a Service did. A Service that executes without claiming an authorization, or refuses a request itself, SHOULD report each governed request it answers to POST /policy/gateway-reports: { servedAgentDid, outcome: "executed" | "refused", reasonCode, httpStatus, request, reportId, occurrences }.

• request is the agent's signed request as received (8.3). The authorization it named is presentedAuthorizationId; authorizationId is set only when the Service claimed that authorization for this request.
• reportId (8–64 characters of [A-Za-z0-9_-]) is the Service's own id for the report, kept across retries; occurrences is how many identical refusals the report stands for (always 1 for executed, REPORT_OCCURRENCES_INVALID otherwise).
• The report is signed as the Service (MAGP-SERVICE-v1, action report, the request's nonce in the authorization-id slot, fields servedAgentDid | callerAgentDid | action | outcome | reasonCode | httpStatus | reportId | occurrences).
• The issuer records it only when the signature verifies and the served agent's owner registered the signing DID as a counterparty of either purpose (8.7.10), and files it under that owner. An executed report MUST carry a request whose agent signature verifies (REPORT_CALLER_UNVERIFIED). A resent report is answered ALREADY_RECORDED; the issuer MAY limit reports per Service (REPORT_RATE_LIMITED, 429).

Reports are visibility only: they never change a decision, a hold or a cap.

17. Security considerations

17.1. Fail closed. An unreachable gate means block. A guard that cannot verify a bundle for a value-bearing action means block. Only the secondary controls of §9 fail open, only on internal error, and only where the deployment has not configured them to fail closed.

17.2. Signed-last precedence. Server-derived, gateway-derived and signed operands MUST be applied over the unsigned itinerary, so a client-supplied key cannot shadow a signed amount or a server-counted rate (§6.3.2).

17.3. Nonce discipline. Single-use, consumed atomically, only after signature verification.

17.4. The unsigned context is an assertion. tool, jurisdiction and riskLevel are claims by the agent (resource is signed, §8.3; a jurisdiction the gate enforces is the signed top-level one, §8.3.12, never the itinerary's). A signature attributes a claim; it does not verify it, and the counterparty re-check reads the same claim — so a re-check does not, by itself, catch a lie. The defence is §6.3: every field carries a provenance, an owner-set riskTier and a gateway-derived value are floors the agent cannot lower, a rule can require a trusted source with requireProvenance, and a missing or unrecognised risk fails closed. The optional context signature (§8.3.13) stops a relay rewriting the claim; it does not make it true. Adding these fields to the signed message would break every deployed client and every anchored proof, and would still only attribute them; it is not proposed.

17.5. Escalation is not permission. See §8.6.4.

17.6. Delegation cannot widen. See §5.4. An implementation that reverses the isNoneOf rule silently grants authority nobody issued.

18. Extensibility and versioning

18.1. New operands and atoms extend the protocol. New operators do not.

18.2. An unknown reason code MUST be treated as a block (§8.6.5). An unknown atom MUST NOT silently pass.

18.3. Additive fields on the request or verdict are minor changes. Changes to the canonical message (§8.3), to leaf composition (§13.5), or to the order of checks (§8.5) are breaking.

18.4. GET /magp/schema publishes the request, verdict and rule-pack JSON Schemas, the reason-code registry with SAFR aliases, the control namespaces and the atom catalog. It is the machine-readable companion to this document.

19. Conformance

An implementation is conformant if it:

1. resolves agent keys from the DID (§4.3.1);
2. rebuilds and verifies the canonical message exactly (§8.3);
3. applies the order of checks in §8.5, stopping at the first failure;
4. treats allow and observe as the only permitting dispositions (§8.6.3);
5. never treats escalate as permission (§8.6.4);
6. fails closed as §17.1 requires;
7. enforces the narrowing invariant on any delegated mandate it accepts (§5.4);
8. emits reason codes from Appendix A, or documents extensions;
9. produces evidence verifiable offline (§13.4).

A guard need not implement the stateful steps (8, 9, 10, 16). It MUST defer them to the gate and MUST NOT report a permitting verdict on their behalf for a value-bearing action.

20. Reference endpoints

Appendix A — Reason codes

Generated from the reference implementation's registry, which is also published at GET /magp/schema. The SAFR §30 alias column maps each code to the canonical SAFR vocabulary where one exists; — marks a permit/lifecycle code or a MetaMynd-specific extension beyond the SAFR floor.

Permit / lifecycle (no SAFR deny alias)

Request validation

Identity (SAFR §6)

Envelope integrity (SAFR §5)

Mandate (SAFR §7)

Exposure / counterparty (SAFR §22/§23)

Policy / SOP / standards (SAFR §8)

Evidence-quality controls (SAFR §24). Author-facing codes for the evidence atoms.

Containment / circuit breaker (SAFR §21)

Human review (SAFR §12)

Decision token / capability binding (SAFR §20)

Evidence quality (SAFR §24)

MetaMynd-specific extensions beyond the SAFR floor (no §30 alias)

Action Passport (MetaMynd Governed Execution scope, Module E/F)

Platform rule packs

Automated containment (MetaMynd Governed Execution scope, Module H)

Claim, resume and settlement (an executor's or SDK's refusal)

Fail-closed executor and guard errors

Rules MetaMynd writes for you: the Controlled Testing plans and the SOP compiler's drafts

MCP tool-call policies (the built-in policy catalog)

HTTP gateway refusals (agentsafe-http-gateway)

Guard and SDK fail-closed refusals

Claim payload and x402 settlement binding

Capture, release and refund of a hold

Counterparty authentication (a claim, settlement or outcome report signed by an executor)

Effect reconciliation and compensation

Owner actions on the evidence trail

Appendix B — Canonical examples

Canonical message

did:hedera:testnet:zEEZ…|flight-purchase|150|USD|skyward-air|9f2c…|2026-07-10T05:12:00Z

A narrowing delegation — parent caps at 500 across two merchants; the child caps at 50 against one of them, and repeats the parent's cumulative constraint because omitting it would widen:

{ "target": "flight-purchase",
  "permission": [{ "target": "flight-purchase", "constraint": [
    { "leftOperand": "mm:payAmount",       "operator": "lteq",    "rightOperand": 50 },
    { "leftOperand": "mm:cumulativeSpend", "operator": "lteq",    "rightOperand": 500 },
    { "leftOperand": "mm:merchant",        "operator": "isAnyOf", "rightOperand": ["skyward-air"] }
  ]}]}

A refused widening — the same child with mm:payAmount raised to 5000 is rejected at issuance with CONSTRAINT_WIDENED; omitting mm:payAmount entirely is rejected with CONSTRAINT_DROPPED.

Appendix C — Atom catalog

Atoms are pure predicates over request context. Generated from the reference implementation; GET /standards/atoms returns the live catalog and is authoritative. New governance requirements are added as new atoms, which does not require a protocol version bump (§18.1).

Appendix D — Future directions

Not implemented at 1.0. Recorded so implementers know the intended direction, and kept out of the normative text so nothing in the body is aspirational.

• Content-addressed rule packs. Each published rule-pack version addressed by content hash, so a bundle can name an exact immutable pack.
• HCS-10 channels. An on-chain, auditable channel binding for peers that require message-level durability rather than TLS request/response.
• WebSocket transport. A duplex binding for streaming interactions.
• HCS-2 registry discovery. Trustless discovery of DIDs and service endpoints via a mirror node, with the issuer offline.
• Signed bundle staleness enforcement at the edge, beyond the risk-tiered rules of §6.2.

Changes from 0.4

• The order of checks (§8.5) has 16 steps, adding containment, operating modes, rate limits, circuit breakers, OBSERVE folding and the reassessment floor.
• Reason codes are generated from the registry (Appendix A).
• New: resource scope (§5.3), delegation and the narrowing invariant (§5.4), agent posture (§7), secondary controls (§9), effects and reconciliation (§12), decision records and the governance envelope (§14), privacy-preserving verification (§15).
• Platform governance surfaces moved to MetaMynd Platform Governance.

1.0 editorial revision (2026-10-20). Implementation detail that an interoperating party does not need was removed. No requirement on the wire, the order of checks or the reason codes changed.