| Status | Draft |
| Version | 0.3 (2026-10-27); formerly Questions 0.1 |
| Extension | decisions/0.3, an extension of Principal Handoff Core 0.3 |
| License | Apache-2.0 |
| Schemas | schemas/ (record schema in ../core/schemas/) |
| Conformance suite | conformance/ |
| Reference | ../reference/ |
Agents working for someone often reach a choice only that someone may make: which of two designs, whether to spend money, what a customer was promised. The agent’s session may end long before the answer comes. This extension of Principal Handoff covers such decisions: how an agent raises one with options and a working assumption, how the principal side records the principal’s answer (or that no answer is needed) with the authority it was made under, how an answer is revised, and how the answer reaches the project rather than a session that may be gone. It builds on the core registers; work only the principal can do is the Acts extension.
The key words in this document are to be interpreted as in the core, which also defines principal, principal side, requester, delegate, item, key, terms, record, claim, relation and note. This extension adds:
decide: an answer or choice only the principal may make.{"text": …, "option"?: …}: free text, and the chosen option’s id if the decision has options.terms.default). It is never an answer (core R4).{"text": …, "options"?: [{"id", "label"}], "default"?: …, "due"?: "YYYY-MM-DD"}. Option ids are unique
within the decision. default is an option id or text.decided (carries answer) and dismissed (no answer is needed; the note SHOULD say
why).decided (carries answer): someone heard the principal decide, for example in the
requester’s own session.settled (the decision was made where it was asked) and not_needed.Records use the core record with ext: "decisions/0.3".
type |
origin |
Schema | Additional requirements |
|---|---|---|---|
raised |
requester |
raised |
terms.text, terms_rev: 1 |
amended |
requester |
amended |
terms, terms_rev |
withdrawn |
requester |
withdrawn |
reason |
settled |
principal |
settled |
outcome; answer when decided; authority; terms_rev |
reopened |
principal |
reopened |
supersedes |
claimed |
agent, requester |
claimed |
outcome: "decided", answer, evidence.basis |
related |
principal (same_as), requester (derived_from) |
related |
relation |
note |
any | note |
about |
If answer.option is present, the principal side MUST make it one of the options at the terms_rev it records. A
receiver that finds it is not, or cannot check because it never saw the terms, MUST still accept the settlement, treat
answer.text as authoritative, and SHOULD report the mismatch: the principal’s answer must not be lost to a validation
error.
raised with id r:<key>, so that a repeated raised is a duplicate of the
first (core §10). A second raised for the same key under another id is a need-register conflict (core §6), which
the principal side SHOULD report. Other record ids are any ids unique per core §10.amended, listing
its current need record in supersedes and increasing terms_rev by one. A settlement made against older terms is stale (core §6).settled with outcome: "decided" and an answer, naming the decider
and authority kind (core §5):
principal: the principal answered.confirmed: the principal confirmed an answer the assistant proposed.delegated: the assistant answered under a standing instruction or mandate (under), without the principal.attested: the answer is taken from evidence, for example something the principal wrote elsewhere.settled with outcome: "dismissed": the principal decided no answer is needed. The requester MUST
NOT keep waiting and SHOULD raise a new decision if the need returns.settled that lists it in supersedes, or reopen it with reopened.
Which settlement is current is defined by core §6.withdrawn when it no longer needs an answer. If the principal answered in the
requester’s own session, the requester SHOULD first send a claimed with that answer and evidence.basis, so that
the principal side can record who decided, and then withdraw with reason: "settled". The principal side MAY adopt
the claim (core §7).derived_from relation to the decision.| Questions 0.1 event | Decisions 0.3 record |
|---|---|
asked |
raised, terms from text, options, default, due; terms_rev: 1 |
answered, decided_by: principal |
settled, outcome: "decided", authority.kind: "principal" |
answered, decided_by: assistant |
settled, outcome: "decided", authority.kind: "delegated" with under, or "attested" with evidence.basis |
dismissed |
settled, outcome: "dismissed" |
supersedes (one id) |
supersedes (array) |
withdrawn, reason: settled |
claimed with the answer, then withdrawn, reason: "settled" |
withdrawn, reason: not_needed |
withdrawn, reason: "not_needed" |
conformance/ holds JSON fixtures; its README documents the formats.
| File | Exercises |
|---|---|
records.json |
§3: record → schema it validates against, or invalid |
lifecycle.json |
core §6 and §4 here: the records one receiver holds for one decision (with duplicates, reordering, revisions, forks, ties, cycles, withdrawals, stale terms and invalid records) → the decision’s state |
The core considerations apply. In addition:
delegated, attested) let routine decisions be made without interrupting the
principal. Requesters SHOULD treat them as revisable and MAY raise a new decision when the stakes are high.Non-normative.
undecided line is a decision nobody has
raised yet.default only pre-fills a form, which matches
the working assumption here. A principal side can expose “ask the principal” as an MCP tool that sends raised.default_if_lapsed when no answer arrives. This extension deliberately does not:
a working assumption never becomes an answer (core R4).input-required pauses one task until its client answers, and does not record who answered. A decision
raised while answering an inquiry from the principal (core §15) carries derived_from with the inquiry’s uri.answer is text plus an option id. Structured answers (numbers, dates, files) are not specified.../core/SPEC.md.