agent-ops-specs

Principal Handoff Core 0.3

   
Status Draft
Version 0.3 (2026-10-27)
License Apache-2.0
Schemas schemas/
Extensions Acts · Decisions

Abstract

AI agents working for someone keep reaching things only that someone may settle: work only they can do (pay, sign, buy) and choices only they may make (which design, whether to spend). That someone is the agents’ principal. Principal Handoff specifies how such items leave the agents, reach the principal’s own tool (the principal side), and come back settled, when the items outlive every agent session.

The core defines one model for every kind of item. Each item has two registers with different owners: the need, owned by the agent that raised it, and the settlement, owned by the principal side. Every change is an append-only, attributable record that names who made it, under what authority, with what evidence. Assertions by anyone else are claims, which change nothing until the owner of the register records something. The extensions define the two kinds of item: Acts (work only the principal can do, with a Markdown binding for a project’s state document) and Decisions (answers and choices only the principal may make).

Table of contents

  1. Conventions and terminology
  2. Model
  3. Ownership
  4. Records
  5. Authority and evidence
  6. Current state
  7. Claims, relations and notes
  8. Delivery and application
  9. When a person decides
  10. Identifiers, deduplication and ordering
  11. Extensions
  12. Conformance
  13. Security and privacy considerations
  14. Versioning
  15. Scope
  16. Relation to other specifications

1. Conventions and terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here. Sections marked non-normative, examples and notes are informative.

Party identifier
A string that identifies one party (a person, an organisation, an agent, a system) within a deployment, no whitespace, 1–256 characters. This family does not define how parties are authenticated (§13).
Principal
The single party at the root of every delegation chain in a deployment, on whose behalf its agents and delegates act. The principal is identified by the principal identifier, which is configured as in §3 (R6). The principal MUST be a natural person, or a legal person or public body that a natural person is able to act for. A deployment MUST NOT designate a software agent or system as the principal, whatever legal form wraps it. Note (informative): in practice the principal is the party that bears responsibility, under the law or rules that apply, for what is decided in its name. This specification does not determine who that is; §15 says how a future version may revisit the type constraint.
Principal side
The system through which the principal sees and settles items: a personal assistant, a to-do app, an issue tracker. It is an instrument, not a party with authority of its own: when it settles without the principal it does so as a delegate (§5). It is configured with exactly one principal identifier.
Requester
The role of the agents acting for a project, including a registrar acting on their behalf (Acts). Any party the deployment authenticates as holding a project’s requester role may emit need records for that project’s items (§3). Which parties hold which roles is configured per deployment, like the principal identifier.
Delegate
Any agent or system that decides on the principal’s behalf without the principal deciding or confirming, including the principal side itself and agents further up a delegation chain. A delegate is never the principal.
Decider
The party a settlement record names as having made the settlement (§5).
Project
A unit of work the agents work on, identified by a project name unique within one deployment.
Item
One thing only the principal may settle. An item has a kind (defined by an extension: act or decide), a key, a project, terms, and two registers.
Key
The opaque identifier of an item within its project and extension. An item is identified by the triple (extension name, project, key). Extensions say who assigns keys and how.
Terms
What the item asks: its text, and as the extension defines, a due date, options and a working assumption.
Register
One of an item’s two sequences of records: the need register and the settlement register (§2).
Record
An append-only, attributable JSON message about one item (§4).
Claim
A record asserting something about an item’s settlement by a party that does not own the settlement register (§7).
Relation
A record linking an item to another item, inside or outside this family (§7).
Note
A record that carries information without changing any register (§7).

2. Model

                     need register (owner: requester)          settlement register (owner: principal side)
                     ─────────────────────────────────          ───────────────────────────────────────────
  requester ──────▶  raised · amended(terms_rev) · withdrawn    settled(outcome, authority, evidence) · reopened  ◀── principal side
                                    │                                               ▲
                                    └──── terms the settlement saw (terms_rev) ─────┘
       anyone ─────▶  claim · note  (change no register)
  principal side ──▶  relation (same_as)        requester ──▶ relation (derived_from)

Each item has two registers because the two questions they answer have different owners:

An item’s current state (§6) is computed from both registers. Neither register can overwrite the other: a late answer does not undo a withdrawal, and a withdrawal does not settle anything.

3. Ownership

These rules replace any notion that an item is “resolved” by whoever last spoke.

4. Records

Every record is a JSON object (RFC 8259) that validates against schemas/record.schema.json and against the schema its extension assigns to its (type, origin) pair.

Member Type Req. Meaning
ph string yes Core version; "0.3" for this document.
ext string yes Extension name and version, e.g. "acts/0.3", "decisions/0.3".
id string yes Record id, no whitespace, 1–256 characters (§10).
type string yes One of the record types below.
origin string yes The role that emitted it: requester, principal (the principal side), agent (any other agent), or a role the extension defines.
by string yes Party identifier of the emitter.
key string yes Key of the item.
project string yes Project of the item.
ts string yes RFC 3339 date-time at which the record was created.
supersedes array of strings no Ids of records in the same register that this one replaces (§6).
terms object on raised, amended The item’s terms; the members are defined by the extension. text is always present.
terms_rev integer ≥ 1 on raised, amended, settled On need records, the terms version (1 on raised, increasing by one on each amended). On a settlement, the terms version it was made against.
outcome string on settled, claimed What the settlement says or the claim asserts; values defined by the extension.
authority object on settled §5.
evidence object no §5.
relation object on related §7.
reason string on withdrawn Why the requester withdrew; values defined by the extension.
adopts array of strings no On settled: ids of claims this settlement accepts (§7).
about object on note §7.
note string no Free text from the emitter (§8).
context string no Free-form tag for why the record was sent, e.g. bulk-import.

Receivers MUST ignore members they do not recognise. Senders MAY add members; names beginning with x_ are reserved for private extensions.

type Register Allowed origin
raised need requester
amended need requester
withdrawn need requester
settled settlement principal
reopened settlement principal
claimed (claim) any origin except principal
related (relation) per relation kind (§7)
note (note) any

Extensions MAY restrict this table further, and MUST NOT widen it. A receiver selects the schema by ext and the (type, origin) pair as the extension’s table lists, and MUST reject a record whose pair is not listed. A receiver that does not implement the extension or version named in ext MUST NOT act on the record; it SHOULD consume it without error and MAY report it. The schemas use JSON Schema draft 2020-12 restricted to type, required, properties, enum, const, pattern, items and $ref (a relative path), so that a small validator suffices.

5. Authority and evidence

Every settled record carries authority:

Member Req. Meaning
kind yes principal, confirmed, delegated or attested.
decider yes Party identifier of whoever made the settlement.
under for delegated Opaque reference to the mandate or standing instruction relied on. The principal side MUST be able to produce what it refers to.
chain for delegated Party identifiers from the principal to the decider, in order.
representative no For an organisation principal: the natural person who acted for it.

The four kinds:

When the principal is a legal person, a settlement of kind principal or confirmed MUST carry representative, naming the natural person who acted for it, and evidence.proof SHOULD include evidence of their power to represent it.

evidence, when present, is an object:

Member Meaning
presented Digest (sha-256: + lowercase hex) of exactly what was shown to the person who decided or confirmed: the terms at terms_rev and any options or consequences the principal side displayed (§9).
proposal For confirmed: id of the record, or digest of the content, that was confirmed.
basis For attested: what the evidence was.
proof An independently verifiable proof, such as a detached JWS or a verifiable credential, over the record with evidence.proof removed, serialised with the JSON Canonicalization Scheme [RFC 8785].

A settlement of kind principal or confirmed SHOULD carry evidence.proof made with the principal’s own credential on a surface no agent controls. A verifiable principal side (§12) MUST.

6. Current state

Each register is folded separately, over all its records a receiver holds, regardless of arrival order:

A requester’s amended and withdrawn MUST list the item’s current need record in supersedes, and a principal-side settled that replaces an earlier settlement, and every reopened, MUST list it. A receiver that nonetheless holds several heads uses the rule above and reports the conflict.

From the two current records, the item’s state is:

Settlement (current) Need (current) State
settled any, or none settled, with its outcome. It is stale if its terms_rev is lower than the highest terms_rev held in the need register.
none, or reopened raised or amended open
none, or reopened withdrawn by the extension’s policy (§11): open under the keep policy (the principal side keeps presenting it and asks the principal), withdrawn under the stop policy (it is no longer presented)
none, or reopened none unknown: no need record is held yet

In every state the item also reports whether its current need is withdrawn, so that a principal side under the keep policy knows to ask.

Receivers MUST reject an amended whose terms_rev is lower than 2 and a settled whose terms_rev is lower than

  1. Because records may be missing or late, a receiver MUST accept a skipped terms_rev, and a settlement whose terms_rev is higher than any need record it holds (it is not stale). The current terms are those of the current need record.

A stale settlement stays settled. The principal side SHOULD present it to the principal again, and the requester SHOULD treat it as made against outdated terms.

7. Claims, relations and notes

Claims. A claimed record asserts an outcome that the claimant has no authority to record: an agent that heard the principal say “I paid it”, or a registrar that saw a declared line disappear. It SHOULD carry evidence.basis. A claim changes no register. The principal side MAY accept it by recording a settlement that lists the claim’s id in adopts, with kind confirmed if the principal confirmed it and attested otherwise; adopts MUST NOT appear on a settlement of any other kind. A claim never removes an item from the principal’s view.

Relations. A related record carries relation:

Member Meaning
kind same_as or derived_from.
target The other item: {"ext", "project", "key"} (all three) for an item of this family, or {"uri"} for anything else (an A2A task, a bus message, an issue). Exactly one of the two forms MUST be used.
active true, or false to retract an earlier relation of the same kind and target.

Notes. A note record carries information that changes no register: progress, a fact the principal mentioned, a premise that changed. It carries about, either {"key": …} for a keyed item or {"quote": …} with text in the recipient’s own words for something that was never keyed. A note never settles anything. In particular, a note from the principal side saying a premise changed (a moved date) is not an amendment: the requester decides whether to amend its terms.

8. Delivery and application

9. When a person decides

These rules apply to every settlement of kind principal or confirmed, that is, whenever a natural person decides or confirms, whether the principal or an organisation’s representative.

10. Identifiers, deduplication and ordering

11. Extensions

An extension document MUST define:

  1. its name and version (the ext value) and the item kind it covers;
  2. the members of terms, and how keys are assigned;
  3. its outcome values for settlements and claims, and its reason values for withdrawals;
  4. its table of (type, origin) pairs with schemas, restricting §4;
  5. its policy for an item whose need is withdrawn and whose settlement is open (§6);
  6. any binding that applies records mechanically, and what it applies;
  7. its conformance classes and suite.

12. Conformance

13. Security and privacy considerations

14. Versioning

Change log. 0.3 (2026-10-27): the event model of 0.2 is replaced by two registers with owners, claims, relations and notes; resolutions carry an authority kind, a decider and evidence; the principal is defined structurally and configured (R6); Tasks and Questions become the Acts and Decisions extensions. A mapping from every 0.2 event to 0.3 records is in each extension. 0.2 (2026-10-27): split from Human Task Handoff 0.1.

15. Scope

Out of scope, deliberately:

16. Relation to other specifications

Non-normative. The detailed comparison is in RELATED-WORK.md.

Existing protocols that involve a person place the request inside a live unit of work (a call, a task an agent server runs, a run on a thread), and the system that created the unit decides when it is complete. Principal Handoff covers items that outlive every agent run and that only the principal side settles. It is meant to be carried by those protocols and to reference their mandates, not to replace them.

References

This site is open source. Improve this page.