elicitation.pending v1

An agent is blocked on a person’s answer, or a broker approval request waits on one. Pushed by SuperPipeline and read back by the carrier’s sweep, from one builder. Mirrors SuperPipeline’s ElicitationPendingBody (apps/api/src/board/views.ts). Readers ignore properties they do not know.

CloudEvents

Every event below carries dataschema https://raw.githubusercontent.com/SuperJackfruitLabs/treaty/main/schemas/superpipeline/elicitation.pending.v1.json.

Body `event`	CloudEvents `type`	Subject
`elicitation.pending`	`com.superjackfruit.superpipeline.elicitation.pending.v1`	`evt.<workspace>.superpipeline.elicitation.pending`

The subject is the NATS subject the relay files it under; <workspace> is the board’s workspace. See the envelope and subjects.

Who sends it, who reads it

Produced by SuperPipeline, through the relay.
Consumed by:
- SuperExchange: Posts it to the board’s room, for the boards it carries. Receives it through the relay.
- AgentPod: The hub’s board chat posts it, for the boards it still carries.
- SuperDispatch: Takes it as a nudge to look at the board soon, on a board opted into scheduling. Reads nothing from its data.

Fields

Readers ignore properties they do not know, so a field may be added without a new version.

Field	Type	Required	Description	Constraints
`event`	`"elicitation.pending"`	yes
`boardId`	string or null	yes
`boardName`	string	yes
`cardId`	string	yes
`cardTitle`	string	yes
`elicitationId`	string	yes
`runId`	string	yes
`stageKey`	string	yes
`agentId`	string	yes	The agent that waits, and the one identity that may not answer.
`question`	string	yes	May be empty: an agent can stop on options alone.
`options`	array of object	yes	In the order the agent offered them. May be empty, and the body is still sent.
`options[].id`	string	yes
`options[].label`	string	yes
`options[].meaning`	one of `"approve"`, `"reject"`, `"revise"`, `"choose"`, `"defer"`	yes	What choosing the option does (gate.v2 §2).
`options[].needsComment`	`false`	yes
`options[].scope`	one of `"once"`, `"run"`, `"always"`	no
`options[].requires`	`"workspace-admin"`	no
`approvalSubject`	object	no	A subject as a decision envelope carries it (gate.v2 §3): identity, expiry and the kind’s bounded preview. The canonical payload stays behind the authenticated route.
`approvalSubject.id`	string	yes
`approvalSubject.digest`	string	yes
`approvalSubject.schema`	string	yes
`approvalSubject.revision`	integer	yes		at least 0
`approvalSubject.expiresAt`	string or null	yes
`approvalSubject.preview`	array of object (type = “text”) or object (type = “field”) or object (type = “link”)	yes
`approvalSubject.preview[].type`	`"text"`	yes		in the `type = "text"` shape
`approvalSubject.preview[].label`	string	no		in the `type = "text"` shape
`approvalSubject.preview[].text`	string	yes		in the `type = "text"` shape
`approvalSubject.preview[].type`	`"field"`	yes		in the `type = "field"` shape
`approvalSubject.preview[].label`	string	yes		in the `type = "field"` shape
`approvalSubject.preview[].value`	string	yes		in the `type = "field"` shape
`approvalSubject.preview[].type`	`"link"`	yes		in the `type = "link"` shape
`approvalSubject.preview[].label`	string	yes		in the `type = "link"` shape
`approvalSubject.preview[].url`	string	yes		in the `type = "link"` shape
`approvalSubject.previewComplete`	boolean	yes	False when the preview was cut to its bounds; no approving option may then be offered.
`freeText`	object	no	Only on a question with no options: answered by typing, up to maxLength.
`freeText.maxLength`	integer	yes		at least 1
`approvalRequestId`	string	no	Only on a broker approval request: the same id as elicitationId. cardId, runId and stageKey are then empty strings.
`deadline`	object	no	When the decision is reminded about and escalated. Absent when its stage sets no timeout.
`deadline.remindAt`	string	no		format `date-time`
`deadline.escalateAt`	string	no		format `date-time`
`ts`	string	yes		format `date-time`

Example

From fixtures/superpipeline-events/examples.json, case “options”:

{
  "event": "elicitation.pending",
  "boardId": "brd_134a0ddb6d434478",
  "boardName": "Developer Experience",
  "cardId": "crd_0f3c9a2b7d4e4a11",
  "cardTitle": "Research this",
  "elicitationId": "eli_1a2b3c4d5e6f7081",
  "runId": "run_0123456789abcdef",
  "stageKey": "research",
  "agentId": "agt_9e8d7c6b5a493827",
  "question": "May I run the migration?",
  "options": [
    {
      "id": "allow_once",
      "label": "Allow once",
      "meaning": "approve",
      "needsComment": false,
      "scope": "once"
    },
    {
      "id": "allow_always",
      "label": "Always allow",
      "meaning": "approve",
      "needsComment": false,
      "scope": "always",
      "requires": "workspace-admin"
    },
    {
      "id": "deny",
      "label": "Deny",
      "meaning": "reject",
      "needsComment": false
    }
  ],
  "ts": "2026-11-10T09:30:00.000Z"
}

The corpus has 4 valid cases in all:

free-text

{
  "event": "elicitation.pending",
  "boardId": "brd_134a0ddb6d434478",
  "boardName": "Developer Experience",
  "cardId": "crd_0f3c9a2b7d4e4a11",
  "cardTitle": "Research this",
  "elicitationId": "eli_2b3c4d5e6f708192",
  "runId": "run_0123456789abcdef",
  "stageKey": "research",
  "agentId": "agt_9e8d7c6b5a493827",
  "question": "Which branch should I base this on?",
  "options": [],
  "ts": "2026-11-10T09:30:00.000Z",
  "freeText": {
    "maxLength": 2000
  }
}

no-options-no-question

{
  "event": "elicitation.pending",
  "boardId": "brd_134a0ddb6d434478",
  "boardName": "Developer Experience",
  "cardId": "crd_0f3c9a2b7d4e4a11",
  "cardTitle": "Research this",
  "elicitationId": "eli_3c4d5e6f70819203",
  "runId": "run_0123456789abcdef",
  "stageKey": "research",
  "agentId": "agt_9e8d7c6b5a493827",
  "question": "",
  "options": [],
  "ts": "2026-11-10T09:30:00.000Z"
}

approval-request

{
  "event": "elicitation.pending",
  "boardId": null,
  "boardName": "Developer Experience",
  "cardId": "",
  "cardTitle": "",
  "elicitationId": "apr_4d5e6f7081920314",
  "runId": "",
  "stageKey": "",
  "agentId": "prn_0123456789abcdef0123",
  "question": "May I run the migration?",
  "options": [
    {
      "id": "allow_once",
      "label": "Allow once",
      "meaning": "approve",
      "needsComment": false,
      "scope": "once"
    },
    {
      "id": "allow_always",
      "label": "Always allow",
      "meaning": "approve",
      "needsComment": false,
      "scope": "always",
      "requires": "workspace-admin"
    },
    {
      "id": "deny",
      "label": "Deny",
      "meaning": "reject",
      "needsComment": false
    }
  ],
  "ts": "2026-11-10T09:30:00.000Z",
  "approvalRequestId": "apr_4d5e6f7081920314",
  "approvalSubject": {
    "id": "sub_7d6c5b4a39281706",
    "digest": "sha256:4f2a0c1e9b8d7f6a5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7",
    "schema": "stk-capability/v1",
    "revision": 1,
    "expiresAt": "2026-11-11T09:30:00.000Z",
    "preview": [
      {
        "type": "text",
        "label": "Post",
        "text": "We shipped the decision envelope."
      },
      {
        "type": "field",
        "label": "Account",
        "value": "@example"
      },
      {
        "type": "link",
        "label": "Draft",
        "url": "https://example.com/draft"
      }
    ],
    "previewComplete": true
  },
  "deadline": {
    "remindAt": "2026-11-10T10:30:00.000Z"
  }
}

Refused

Each of these must fail. The corpus says why:

an elicitation option never asks for a comment
scope is once, run or always
agentId is required
freeText has a maxLength

Source

Schema: schemas/superpipeline/elicitation.pending.v1.json
In the package: import schema from "@superjackfruitlabs/treaty-event-schemas/superpipeline/elicitation.pending.v1.json" with { type: "json" };