# Scope Grammar Specification (SGS) **Draft 0.9 — Request for Comment** *A canonical grammar for declaring AI agent authorization scopes, shared by VCAP and PTP.* --- **Authors:** Odysseus Melchizedek Shiloh, WellSpr.ing · Claude Opus 4.7, Anthropic **Status:** Draft 0.9, open for comment **Date:** April 17, 2026 **Canonical URL:** https://wellspr.ing/protocols/sgs **Sibling protocols:** Vaulted Covenanted Agent Protocol (VCAP) at https://wellspr.ing/protocols/vcap; Presence Token Protocol (PTP) at https://wellspr.ing/protocols/ptp **Comment channel:** https://wellspr.ing/protocols/sgs/rfc --- ## What this is A short specification defining the canonical grammar used to declare what an AI agent is authorized to do. The grammar is referenced by two sibling protocols: the Vaulted Covenanted Agent Protocol uses it in the `canonical_scopes` field of agent attestations to declare the bounds of an agent's authorization, and the Presence Token Protocol uses it in the `scope` field of presence tokens to request specific operational grants within those bounds. The grammar is deliberately simple. It has four components separated by colons, each drawn from a controlled vocabulary with versioning and an extension process. The match semantics are literal string matching with wildcard rules. An adversary cannot argue their way into a scope; either the requested scope string matches a declared scope string (possibly via wildcards) or it does not. The protocol-level decision is machine-checkable. ## The grammar A scope string has the form: ``` {action}:{recipient-category}:{geography}:{purpose-category} ``` All four components are required. None may be empty. Each component is drawn from the canonical vocabulary defined in Section 3 of this document, extended through the process defined in Section 4. Wildcards are permitted per the rules in Section 5. ## The canonical vocabulary The four components draw from the following vocabularies. Each vocabulary is versioned (the version of this document is the version of the vocabulary) and extensible through the process in Section 4. ### Action verbs The action verb declares what kind of operation the agent will perform on the recipient. - **`message`** — send a message to recipients. The message is delivered once per recipient; no expectation of response. - **`converse`** — initiate a bidirectional conversation with recipients. The conversation may span multiple turns; the recipient may decline at any turn. - **`query`** — ask recipients a structured question expecting a structured answer. The query is typically information-seeking and does not commit the recipient to further interaction. - **`transact`** — conduct a commercial transaction with recipients. This action carries the highest stakes and requires additional attestations (reasoning attestation is mandatory; additional PTP-level safeguards apply). - **`receive`** — accept inbound contact from recipients. This is the reverse-discovery case: the agent is not initiating, it is preparing to be found. - **`broker`** — introduce two recipients to each other on each other's behalf. The agent acts as an intermediary; both parties must be within authorized scope. - **`publish`** — make content available to recipients without personalization. This is one-to-many announcement, not one-to-one message. ### Recipient categories The recipient category declares what kind of entity is being contacted. - **`covenanted-persons`** — individuals who have received a covenant name through a Calling Interview or equivalent process. - **`covenanted-agents`** — other AI agents holding current VCAP attestations. - **`merchants`** — commercial businesses at which individuals or households transact. - **`faith-orgs`** — religious congregations, dioceses, denominations, and affiliated bodies. - **`civic-bodies`** — municipal governments, civic associations, neighborhood councils, and similar. - **`academic-institutions`** — universities, research institutes, and affiliated scholarly bodies. - **`healthcare-providers`** — clinics, hospitals, practitioners, and affiliated health-service bodies. - **`media-organizations`** — newsrooms, publications, independent journalists, and affiliated media bodies. - **`professional-associations`** — guilds, licensing bodies, and peer-association organizations of professional practice. - **`nonprofit-orgs`** — 501(c)(3)-equivalent organizations not covered by other categories. - **`individuals`** — people not affiliated with a specific organization for the purposes of this contact. *This category requires additional safeguards under PTP; see SGS Appendix B.* - **`minors`** — people under 18 or the applicable legal age in the relevant jurisdiction. *This category is reserved for future use and is not yet authorized under Draft 0.9. See Section 7 for the open question.* - **`reverse-discovery`** — the generic recipient category used with the `receive` action; denotes any inbound party that arrives on their own errand. ### Geography Geography declares the geographic bounds within which the action is authorized. The grammar supports standard identifiers in descending specificity. - **ISO 3166-1 alpha-2 country codes** (`us`, `gb`, `de`, `jp`, etc.) - **ISO 3166-2 subdivision codes** (`us-wa`, `us-ny`, `gb-eng`, etc.) - **Municipality names** (`poughkeepsie-ny`, `seattle-wa`, `issaquah-wa`) — lowercased, hyphen-separated, suffixed with the subdivision code. - **Area codes** (`425`, `206`, `212`) — for use with the NNN.today civic portal network and equivalent. - **`global`** — worldwide, no geographic restriction. Geography components are validated against a published canonical list maintained alongside this specification. Unknown geography strings are rejected. ### Purpose categories Purpose category declares the high-level purpose under which the action is undertaken. - **`first-contact`** — initial outreach with no prior relationship between sender and recipient. - **`follow-up`** — continuation of an explicitly-invited prior contact. - **`civic-outreach`** — community-interest action without commercial intent. - **`commercial-inquiry`** — commercial action with recipient consent expected. - **`pastoral-contact`** — faith-based or spiritual-care action, typically requiring faith-org recipient categorization. - **`journalistic-investigation`** — information-gathering in the public interest with editorial accountability. - **`academic-research`** — information-gathering or collaboration in research contexts under institutional review. - **`healthcare-coordination`** — care-team or patient-care-coordination action requiring healthcare-provider recipient categorization. - **`emergency`** — time-critical action justified by immediate safety concerns. *This category requires additional attestations and is subject to post-hoc review.* - **`daily-assistance`** — routine agentic assistance to a covenanted person within their own affairs. - **`reverse-discovery-receipt`** — receiving inbound contact via the `receive` action. ## Extending the vocabulary The vocabulary is extensible. New components may be proposed through the following process: 1. **Proposal** — a new vocabulary entry is proposed via the SGS RFC channel at https://wellspr.ing/protocols/sgs/rfc. The proposal includes: the proposed identifier, which component vocabulary it extends, a precise semantic definition, example use cases, and any safeguards or restrictions that should apply. 2. **Review** — proposals are reviewed for collision with existing entries, clarity of semantics, and necessity. Reviews are public. A proposal that overlaps substantially with an existing entry is declined in favor of the existing entry. 3. **Provisional adoption** — accepted proposals are added to the vocabulary with a provisional status in the next minor version of this specification. Provisional entries may be used in attestations but are flagged as subject to refinement. 4. **Stabilization** — after a review period (default: 6 months), provisional entries are promoted to stable status in the next version. 5. **Deprecation** — entries may be deprecated if they are found to be ambiguous, dangerous, or superseded. Deprecated entries remain valid in existing attestations but cannot be used in new ones after the deprecation date. Vouching institutions and agent operators are free to use private vocabulary extensions prefixed with their own identifier (for example, `message:wellspring-private:poughkeepsie-ny:civic-introduction`). Private extensions do not go through the public review process but are not interoperable across institutions. ## Match semantics and wildcards Scope matching is used in two places: when a VCAP attestation declares authorization, and when a PTP token requests authorization. The matching rules are: ### Literal match A requested scope matches a declared scope if every component is string-identical. `message:merchants:poughkeepsie-ny:civic-outreach` matches `message:merchants:poughkeepsie-ny:civic-outreach` exactly and nothing else. ### Wildcard match Declared scopes may use the wildcard `*` in any component to indicate "any value from the vocabulary for this component." Requested scopes may not use wildcards — a request must be for a specific scope. - `message:merchants:*:civic-outreach` declares authorization for civic-outreach messaging to merchants in any geography. A request for `message:merchants:poughkeepsie-ny:civic-outreach` matches; a request for `message:merchants:poughkeepsie-ny:commercial-inquiry` does not. - `message:*:poughkeepsie-ny:civic-outreach` declares authorization for civic-outreach messaging to any recipient category in Poughkeepsie. This is broader and should be used with care. - `*:covenanted-persons:*:daily-assistance` declares authorization for any action on covenanted persons for daily assistance in any geography. This is appropriate for a covenanted personal assistant agent. ### Wildcard restrictions Some components may not be wildcarded at all, and some combinations of wildcards are restricted: - The `action` component may not be wildcarded in combination with `transact` being a valid action, since `*` would include `transact` (the highest-stakes action). If the agent is authorized for `transact` operations, the scope must declare `transact` explicitly; `*` for action does not grant `transact` authority. - The `recipient-category` component may not be wildcarded if the authorized scope would include the `minors` category (once that category is unreserved). Minor-facing authorizations must always be explicit. - Double wildcards are permitted but strongly discouraged; well-governed vouching institutions will flag attestations with more than one `*` component for additional review. - Triple wildcards (authorizing any action on any recipient in any geography for any purpose with only the purpose component specific) are not acceptable for any routine attestation and should be rejected by well-governed vouching institutions. ### Case sensitivity and normalization All scope strings are lowercased and trimmed before matching. Unicode normalization follows NFC. Whitespace is not permitted in any component; identifiers use hyphens for word separation. ## Scope categorization by stakes Scopes are categorized by stakes level for downstream policy purposes: - **Low stakes** — `receive`, `publish`, `query` with academic or public-information purposes. Reasoning attestation is recommended but not required. Additional PTP safeguards are minimal. - **Medium stakes** — `message`, `converse` with civic, commercial, or academic purposes to non-vulnerable recipient categories. Reasoning attestation is required. Standard PTP safeguards apply. - **High stakes** — `transact`, `broker`, `message` or `converse` with pastoral, healthcare, or emergency purposes; any action involving healthcare-providers, faith-orgs as recipients (for pastoral-contact), or individuals (as recipients for non-low-stakes purposes). Reasoning attestation is required. Enhanced PTP safeguards apply: shorter token lifetimes, stricter scope-matching, mandatory dual-sided audit. - **Reserved** — `minors` as recipient category. Not authorized under Draft 0.9. The stakes categorization is normative and is used by PTP to set token lifetime defaults, audit requirements, and additional-safeguard triggers. ## Open questions in Draft 0.9 - **Minor-facing scopes.** The `minors` recipient category is reserved. Draft 1.0 must either specify the additional safeguards that make minor-facing scopes safe (parental consent attestations, age-appropriate-content scope qualifiers, mandatory human-supervision flags) or declare that such scopes are out of protocol scope. Comment welcome. - **Temporal qualifiers.** Scopes currently do not encode time-of-day or day-of-week restrictions (for example, "no outreach on Sabbath"). These may be useful enough to warrant a fifth component, or may be better handled at the PTP level via token expiry. Comment welcome. - **Compound scopes.** Some legitimate authorizations span multiple simple scopes (for example, an agent that both messages merchants and receives inquiries from them). Draft 0.9 handles this by declaring multiple entries in `canonical_scopes`. Whether this is sufficient or whether an explicit "compound scope" construct is needed is open. - **Vocabulary governance at federation scale.** If many vouching institutions add private vocabulary extensions, cross-institutional interop degrades. Draft 1.0 may need to specify a lightweight shared-extension process (a common vocabulary that institutions can contribute to) distinct from the institution-private-prefix pattern. ## Appendix A: Reference vocabulary tables (Appendix contains the full canonical list of action verbs, recipient categories, geographies, and purpose categories as of the current version. In practice this would be a separate machine-readable JSON file; reproduced here for completeness.) Machine-readable form at: https://wellspr.ing/protocols/sgs/vocabulary-v0.9.json ## Appendix B: Individuals as recipients Scopes with `individuals` as the recipient category require special care. Individuals are typically not represented by a vouching institution in the way that faith-orgs or merchants are, and they are more vulnerable to unsolicited contact than institutional recipients. When an agent requests authorization to contact individuals: 1. The VCAP attestation must include a reasoning attestation explaining why individual-recipient contact is necessary for the agent's purpose. 2. The PTP token must carry a shorter default lifetime (default: 4 hours, not 24). 3. The receiving individual must have a way to decline future contact that is honored by both VCAP and PTP (the absence-default and "stop on request" commitments must be architectural, not merely stated). 4. The vouching institution should require an additional layer of WellKeeper review for `individuals` scopes, and the institution's revocation policy should specifically address individual-complaint-triggered revocation. These requirements are normative. ## Co-authored attribution This specification was developed by Odysseus Melchizedek Shiloh, operating as founder and principal architect of WellSpr.ing, in extended dialogue with Claude Opus 4.7, developed by Anthropic. Offered freely as a public good. No license required. **Peace to this work.**