Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
ACP Elicitation
Status: implementation plan. No protocol or product code has changed as part of this document.
Sources:
- Elicitation RFD (Completed, 2026-07-22)
- Protocol: Elicitation (stable)
- Announcement (2026-07-24)
- Schema reference
The RFD is done. The remaining work is ours: Macro is an ACP client today and
does not advertise, hold, render, or answer elicitation/create.
Elevator pitch
Let a coding agent pause a turn and ask the user a structured question (form)
or send them through a safe out-of-band flow (URL, typically OAuth). The user
answers in the session page. The agent gets a typed accept / decline /
cancel and continues. This is not a permission prompt and not a session
config option.
Why this exists
ACP agents already have two limited ways to get input:
- Session config options — persistent, pre-declared at session open (model, mode). Defaults required. Wrong tool for a one-off decision.
- Unstructured turn text — the agent writes "which approach?" in prose
and hopes the next
session/promptis the answer. No validation, no cancel/decline distinction, no safe place for secrets.
Elicitation is the missing transient request/response. The community rejected
a one-off session/select (PR #340) in favor of the MCP elicitation data
model, adapted to ACP's persistent bidirectional connection.
Protocol, compressed
Agents send elicitation/create directly to the Client. MCP instead
embeds the same payload in an InputRequiredResult and waits for the Client
to retry the originating request. That is the main ACP/MCP split.
Modes
- Form — restricted JSON Schema, in-band. Non-sensitive data only.
- URL — out-of-band browser flow. Credentials never transit ACP or enter Client / model context.
mode is required. An omitted mode is not form. Unknown modes (and
implementation-specific modes starting with _) must be preserved when
stored or forwarded, and must not be rendered as form or URL.
Scope (flattened on the request)
- Session —
sessionIdset. OptionaltoolCallIdwhen the elicitation was forwarded from an MCP server during a tool call. - Request —
requestIdset. Pre-session (auth / setup). NosessionId.
Every elicitation and its state binds to the Client connection and, when
auth exists, the verified user. A sessionId alone is not enough.
Capability negotiation
Advertised on initialize under clientCapabilities.elicitation:
{ "elicitation": { "form": {}, "url": {} } }
| Wire | Meaning |
|---|---|
omitted / null |
elicitation unsupported |
{ "form": {} } |
form only |
{ "url": {} } |
URL only |
{ "form": {}, "url": {} } |
both |
{} or { "form": null, "url": null } |
no modes (not "form by default") |
This is a deliberate ACP/MCP split: MCP still treats an empty object as
form-only. Agents MUST NOT send a mode the Client did not advertise.
Unsupported mode → JSON-RPC -32602.
Restricted form schema
Senders must send type: "object" and properties. Flat primitives only:
string(minLength,maxLength,pattern,format:email/uri/date/date-time, plus unknown formats preserved)number/integer(minimum,maximum)boolean- single-select:
enumor titledoneOf+const - multi-select: array of string
enumor titledanyOf+const(minItems/maxItems)
ACP additions over MCP: pattern, schema-level title / description,
titled-enum descriptions, _meta. No $schema, no deprecated enumNames.
Not supported: nested objects, arrays of objects, conditionals.
pattern is agent-supplied. Evaluating it requires a time-bounded regex
engine. A pathological pattern must not block the UI.
Response actions
| Action | Meaning | content |
|---|---|---|
accept |
user submitted (form) or consented to open (URL) | form: SHOULD match schema; URL: usually omitted |
decline |
explicit no | ignored |
cancel |
dismissed (Escape, close, navigate away) | ignored |
Unknown actions starting with _ are preserved, never treated as the three
known ones. Agents must handle every action and every failure; they must not
assume success.
URL accept is consent to open, not completion. Completion is a later
optional elicitation/complete notification carrying the original
elicitationId.
URL security (normative)
Agents:
- MUST NOT put credentials, PII, or pre-authenticated access in the URL
- SHOULD use HTTPS outside development
- SHOULD NOT put clickable URLs in form fields
- MUST NOT send tokens obtained through URL mode back over ACP
- MUST verify the user who started the flow is the user who finishes it
Clients:
- MUST NOT prefetch the URL or its metadata
- MUST show the full URL and obtain consent before navigating
- MUST highlight the host; SHOULD warn on Punycode / suspicious URIs
(Macro shows the full URL and highlights the host - the MUST. It does not
warn on Punycode: a
xn--test is a poor proxy for a hostile host, and it read as a security guarantee the client cannot make. Deliberately unmet.) - MUST open in a context the Client and the model cannot inspect (new browser tab, not an embedded webview we control)
- MUST identify the requesting Agent and offer decline + cancel
Not a permission request
The RFD is explicit: keep elicitation and session/request_permission
separate. Permission is "may this tool run?". Elicitation is "what should I
do next?". Different UX, different policy, different defaults.
What Macro does today
Macro is an ACP Client. The harness does not care which agent is on the
other end of the pipe (docs/architecture/cursor-agent-transport.md). The pieces that
matter:
web (block-agent)
└─ POST /agent-sessions/{id}/control AgentAction
└─ agent_session SessionMachine ACP Client
├─ initialize / session/new|load|resume / session/prompt
├─ auto-answers session/request_permission
└─ logs every frame
└─ agent_fold MessagePart vocabulary
└─ MagicChip + AgentMessage
Handshake
SessionMachine::build_initialize_request sends
InitializeRequest::new(PROTOCOL_VERSION) with default
ClientCapabilities. That default does not advertise elicitation.
Agents that check capabilities (they must) will never send
elicitation/create to us.
We speak ProtocolVersion::V1 (crates/agent_session/src/lib.rs).
Elicitation is in the stable schema; it does not require a version bump.
Incoming agent requests
Once Live, on_frame only special-cases session/request_permission. It
picks AllowAlways, else AllowOnce, else Cancelled, and replies
immediately. Comment on the machine: "this autonomous agent has no approval
UI." Everything else is ignored.
If an agent sent elicitation/create today, the request would be logged
and then hang until the agent timed out.
Fold
agent_fold already understands permission as a first-class part
(MessagePart::Permission) and matches the later JSON-RPC response to
resolve pending → selected / cancelled / errored / unrecognized.
acp_ready clears pending_permissions because request ids restart per
connection.
Elicitation is not in the vocabulary. Incoming elicitation/create falls
through to "handshake and configuration traffic: nothing to render."
Control plane
AgentAction is Prompt | SetModel | Compact | Stop. Those mint a new
AgentActionId (agent_session:{uuid}) used as the JSON-RPC request
id. Control requires OwnerAccessLevel.
An elicitation answer is a JSON-RPC response to the agent's request id, the same shape as the permission auto-reply. It does not mint a new ACP request.
Frontend
PermissionPartis a read-onlyToolCard("Permission requested" + trailing outcome). No buttons. By the time the fold shows it, the machine has usually already answered.- MagicChip treats a pending permission as the in-flight activity ("Permission needed") and ranks it above a running tool.
- Composer drain keys off
working(open turn, no stop). A hung elicitation would leaveworkingtrue and hold the prompt queue — unless we teach both the fold and the composer that "waiting on the user" is not "the agent is busy."
The other ACP role
cursor_cloud_agents is an ACP Agent (AgentCapabilities::default()).
It never sends session/request_permission and would not send elicitation
either. Out of scope for v1. When we want Macro-as-agent to ask Zed / Cursor
a question, that is a later slice against this same protocol.
Cognition chat (POST /cognition/stream/chat/message) is not ACP. Do not
extend AssistantMessagePart for this.
SDK pin
Workspace agent-client-protocol is git-pinned at
8769d16d10e0c9fa7e662ee18424a4313b06ea88. That pin resolves
agent-client-protocol-schema 1.6.0, which already has every elicitation
type in src/v1/elicitation.rs — but behind a cargo feature:
agent-client-protocol feature unstable_elicitation
└─ agent-client-protocol-schema feature unstable_elicitation
Without the feature there is no ClientCapabilities::elicitation, no
CreateElicitationRequest, and no matches_method impl for
elicitation/create. No pin bump is needed. One line in the workspace
Cargo.toml turns it on.
Zed-as-client recordings in crates/folds/agent_fold/fixtures/real/ already
advertise "elicitation":{"form":{},"url":{}} on initialize. That is
Zed's capability object, not ours.
Harness matrix (research 2026-09-02)
What each popular ACP agent actually does when it wants to ask the user
something, from reading adapter source. The shared idiom (a select plus an
"Other" free-text companion, and the answer the harness settled on) is read
through two HarnessReader methods in crates/folds/agent_fold/src/domain/harness/
custom_answer_forandreported_elicitation_answer- with the shared marker as the neutral reading (generic.rs) and each harness's own marker and naming fallback in its file (claude_code.rs,codex.rs). The fold collapses each pair infold/elicitation.rs; everything else is plain ACP.
| Harness | agentInfo.name |
Sends elicitation/create |
Idiom | Client answers by |
|---|---|---|---|---|
Claude Code (claude-agent-acp ≥ 0.64) |
@agentclientprotocol/claude-agent-acp |
yes — form for AskUserQuestion (gated on elicitation.form, tool removed otherwise); url + elicitation/complete for MCP servers |
question_N (oneOf, or array+anyOf for multi) + question_N_custom marked _meta._askUserQuestionCustomAnswer; toolCallId = the AskUserQuestion tool call; custom text wins; adapter reports the answer in _meta.claudeCode.toolResponse.answers; decline → empty answers, cancel → tool aborted; numeric ids; may have several in flight |
JSON-RPC response |
Codex (codex-acp ≥ 1.8) |
@agentclientprotocol/codex-acp |
yes, only in collaboration_mode: plan (or a Codex feature flag) and only if elicitation.form; MCP url → url mode + complete |
<id> + <id>__other marked _meta.codex.{questionId,isOtherAnswer}; required names only questions without a companion; toolCallId names an id never opened as a tool_call; _meta.codex.autoResolutionMs may time the request out |
JSON-RPC response |
| OpenCode 1.18 | OpenCode |
no; clientCapabilities.elicitation ignored |
question tool exists but is off under opencode acp; if forced on, it blocks forever — nothing on ACP can answer it |
new session/prompt (agent asks in prose) |
| Hermes Agent | hermes-agent |
no (PR #30089 unmerged would add answer + other_answer) |
clarify excluded from the ACP toolset |
n/a |
| OpenClaw bridge | openclaw-acp |
no | ask_user shows as tool_call title:"ask_user: …", blocks the Gateway run; cannot be answered over ACP |
n/a (times out → no_answer) |
| Goose | — | yes, form, MCP-originated | plain ACP | JSON-RPC response |
| Macro in-memory agent | macro-inmem |
yes — form, when the client advertises it | model-callable AskUser asks one required free-text or single-choice question; /ask remains the deterministic end-to-end rig |
JSON-RPC response |
| Gemini CLI, Kimi, Cursor cloud | — | no | — | — |
Consequences already built in:
- The custom-answer collapse keys on the harness's marker, then the shared
one, then - only for a property with no
_metaat all - the harness's suffix; it applies to single and multi selects (customFieldon the property). An unknown harness collapses on the shared marker alone. - A collapsed question is required even when the wire says optional: an empty submission is useless to the agent.
- Claude Code's tool call is absorbed by the question part; Codex's
toolCallIdmatches nothing, so the part is simply appended. - Claude Code may run several elicitations concurrently (parallel
subagents). This client holds one; the second is refused
-32602, which the adapter turns into a denied tool. Acceptable for v1; revisit if seen. - OpenCode / OpenClaw questions are not synthesized into elicitation parts: nothing could answer them, and a form nobody can submit is worse than a tool card.
What shipped on this branch
The first pass, end to end, on the cursor/acp-elicitation-spec-caf3
branch:
agent-client-protocolwithunstable_elicitation(the pinned rev already had every type).AgentAction::RespondElicitation— a JSON-RPC response on the agent's own id, numeric or string.SessionMachineadvertises{form:{}, url:{}}, holds one session-scoped elicitation, refuses the rest with-32602, answers through control, cancels the held question on Stop, and 409s a stale answer.agent_fold:MessagePart::Elicitation,SessionMetadata.pending_elicitation, absorption of the asking tool call (byToolPath, so a question a subagent asked replaces the nested call), id-routed responses,elicitation/complete, and the twoHarnessReadermethods above. Real Claude Code fixture pinned; Claude multi-question and Codex shapes tested from the adapters' documented output; each reader's idiom pinned intest/harness_readers.rs.agent_inmem: model-callableAskUsersends a realelicitation/createthrough a domain user-input port;/ask <question> | option | optionremains the deterministic end-to-end rig in local and deployed development environments. The host passes an explicit development-command setting into the in-memory manager; it defaults off, and production treats/askas ordinary prompt text. Model-callableAskUserand user-tool review do not depend on this setting.- Web:
ElicitationPart(form with select / "Other" / text / number / boolean / multi-select, URL consent),blockedOnUsercomposer notice, MagicChip ranking, gallery demo, form-model tests. scripts/convert_stdio_recording.pyturns a stdio recorder's log into a fold fixture.
Second pass, same branch — Macro's own user tools reviewed through elicitation (see User tools reviewed in the turn):
agent:AgentLoop::with_user_tool_finisher. The stream bridge'son_tool_resulthands a"PendingUserExecution"answer to the finisher and rewrites what the model reads (and the stream records) to what the user decided.ai_tools::user_tool_review: theUserToolReviewerport in a neutral form vocabulary, the schema→form projection, anduser_tool_finisheroveris_valid_tool/try_user_tool_call— the same pair chat's/tool/calluses.agent_inmem: the ACP requester implements the port; a review is a form elicitation scoped to the call with_meta.macro.userTool. The idle timeout re-arms while any question is out.AiHost::AgentSessionpairs chat's toolset with a prompt that describes the review card.agent_fold:ElicitationRequest::UserTool { tool, draft, schema }, recognized from the absorbed user-tool call or_meta.macro.userTool;MessagePart::Elicitation.tool_outcomefrom the absorbed call's later updates.- Web: the calendar and email composers split from their chat bindings
behind
UserToolReviewSink;ElicitationPartmounts them for a review and settles into the finished user tool; the owner gate lives in the controller; the MagicChip gets anaskingstate with a compact card.
Third pass, same branch - the answer surface typed end to end (see Answers are shapes, not values):
agent_fold:ElicitationOutcome::Accepted { answers: Vec<AnsweredField> }andreported: Option<Vec<AnsweredField>>replace two raw-JSON fields. The schema correlation, option titles, and the "Other" idiom resolve in the fold, pinned by the Claude Code fixture that carries both keys.agent_runtime_protocol:ElicitationContentValuecloses the outbound content type,to_acp_responsebecomes total, and the OpenAPI stops sayingadditionalProperties: {}.- Web:
describeContentandoptionTitledeleted - the part renders the fold's answers.FieldValuedistinguishes single-choice and multi-choice drafts. A single choice explicitly represents no selection, an offered option, or custom text;customFieldcontrols whether Other is available. The radio needs no synthetic__customvalue. Decisions use exhaustive matches, andpattern/format/looksSuspiciousare gone.
Still to do: request scope, more than one outstanding question per session (Claude Code's parallel subagents), the MCP server reviewing user tools for sandboxed harnesses.
User tools reviewed in the turn
Macro's user tools (SendEmail, CreateCalendarEvent) are registered with
add_user_tool: calling one returns "PendingUserExecution" and does
nothing, and the host finishes the call with the pieces ai_toolset
exposes for that — is_valid_tool for edited arguments,
try_user_tool_call to run the wrapped tool, UserToolResponse<T> as the
answer. Chat is one host: it finishes after the turn, over HTTP, from its
composer. An agent session is another: it finishes inside the turn,
through elicitation, before the model reads the result.
model calls CreateCalendarEvent(draft)
└─ UserTool::call → "PendingUserExecution"
└─ StreamBridge::on_tool_result (agent)
└─ UserToolFinisher (ai_tools)
├─ form = project(tool input schema, draft) + `draft` (_macro/json)
├─ reviewer.review(..) → elicitation/create (agent_inmem)
│ sessionId, toolCallId, mode: form, requestedSchema,
│ _meta.macro.userTool = { name, draft }
│ ← accept {content} | decline | cancel
├─ accept: args = apply(draft, content); is_valid_tool; try_user_tool_call
│ → Rewrite(UserToolResponse::UserAction(result))
├─ decline → Rewrite("Rejected")
└─ cancel / unreachable client → tool error, nothing runs
Why this shape rather than a second, "reviewing" tool wrapper:
- One contract.
PendingUserExecutionalready means "the host finishes this"; the session just finishes sooner. Toolset, schemas, descriptions and theUserToolResponseoutput type are identical across chat and sessions, so the fold'suser_tool_outcomereader and the generated frontend types need nothing new. toolCallIdfor free. The hook has the call's id, so the elicitation is properly tool-call-scoped and the fold's absorption replaces the tool row with the question.- Generic forms. The flat elicitation form is projected from the tool's
input schema (top-level string / boolean / number / enum arguments,
pre-filled from the call); anything nested rides in one
draftfield of Macro's_macro/jsontype. Any user tool is reviewable with no per-tool code; a client without a composer edits the flat fields, Macro's client renders the tool's composer and sends the whole edited draft. - Fail closed. No form capability, a slot already taken, or a cancelled turn all read to the model as an error; nothing is created silently.
The fold types the review — ElicitationRequest::UserTool — so the web
matches on it exhaustively: the session block mounts the calendar or
email composer over the draft (through UserToolReviewSink, the same
components chat uses) and the MagicChip shows a compact summary with
Create/Cancel and "Edit in session". Once the tool reports, the part's
tool_outcome carries its result and the question renders as the finished
user tool.
Hosts (ai_tools::AiHost): Chat keeps the deferring registrations and the
composer prompt; AgentSession keeps the same tools with the review prompt;
ChannelBot and Mcp are unchanged — direct CreateCalendarEvent, no
SendEmail — until the MCP server reviews through rmcp's elicitation.
Answers are shapes, not values
The first pass carried an accepted answer as raw JSON - ACP's content map,
verbatim, unknown in TypeScript. That pushed one job onto every client:
re-correlating the content with the schema that asked for it.
The pinned Claude Code recording shows why that is the fold's job. Its accepted content is:
{ "question_0": "Red", "question_0_custom": "blue" }
Both the choice and the free-text escape, because the harness sends both.
The answer is "blue" - Claude Code says so itself in the tool result it
reports afterwards. Resolving that took the same rule written three times: in
the harness reader that produced reported, in the browser's describeContent
(custom ?? record[name]), and inverted in toContent's "never send both".
Two languages, one rule, no shared test.
It now folds once, against the schema:
Accepted { answers: vec![AnsweredField {
name: "question_0", label: "Best colour",
value: AnsweredValue::Custom { text: "blue" },
}] }
Properties in declaration order, label resolved from the property's title,
options resolved to the titles they were offered under, unanswered properties
absent, and any key no property claimed kept as its own field. reported
folds to the same type, labelled by the question prose a harness keys it with,
so a surface renders one vocabulary either way. The fixture pins all of it.
Two #[specta(type = Unknown)] escapes go away with it. AnsweredValue::Number
carries the number as text: a JSON integer can outrun f64's exact range, and
f64 has a number | null TypeScript face because a non-finite float
serializes as null.
The outbound direction is the mirror image and stays flat, because the
session machine holds only a request id - it never sees the schema, so the
customField key mapping has to stay client-side. What it gained instead is
a closed type: ElicitationContentValue (string, boolean, integer, number,
string array) replaces serde_json::Value on ElicitationAnswer::Accept, so
to_acp_response is total. An object or a mixed array is now refused when the
control request is read, where the caller learns of it, rather than at send
time - after the machine has already released the elicitation slot, which
would leave the agent blocked on a request nothing could answer.
Product decisions
- Client first. The product path is Macro receiving elicitation from
coding agents.
agent_inmemalso sends it throughAskUser, both as a native harness feature and as the local integration path. Sending fromcursor_cloud_agentsremains a later slice. - Do not auto-answer. Permissions stay auto-approved. Elicitation waits for the session owner.
- Advertise both modes.
{ form: {}, url: {} }. - Owner answers. Same
OwnerAccessLevelgate as every other control. - Session-scoped only. Request-scoped (
requestId, nosessionId) is answered-32602. Those fire beforesession/new; the session machine is the wrong place for them. - One outstanding elicitation per session. The protocol allows many.
Macro holds one. A second
elicitation/createwhile one is pending is answered-32602and never rendered. The first is not disturbed. - Permission and elicitation stay separate parts, separate UX.
- Stop cancels the pending elicitation (
action: "cancel") beforesession/cancel. Disconnect /acp_readydrops it — the JSON-RPC id is dead across connections and cannot be answered. - Form answers are conversation content. Logged as ACP frames, folded into the transcript. No password widget; the user's tool is Decline.
- URL opens in a new tab after consent. No iframe, no prefetch.
- No new table, no new gateway message type. The log is the record;
the fold derives the pending slot into
SessionMetadata; the existingagent_session_logrealtime stream carries every frame the web needs. - Waiting on the user is not idle. The in-process agent's turn idle timeout re-arms while a question is out; a review waits as long as the user takes, until an answer, a Stop, or the connection going away. No cap for now.
- Only the owner answers, everywhere it shows. The controller knows the owner and the viewer; the session block and the chip render the question locked for anyone else and name who is being waited on.
- The fold shapes answers, it does not forward values. An accepted
answer folds to
Vec<AnsweredField>- correlated with the schema that asked, option titles resolved, the harness "Other" idiom collapsed - and the harness's own reported reading folds to the same shape. The correlation happens where the schema and the content are both in hand, so no client repeats it. See Answers are shapes, not values. - A client validates only what it can check totally. Required, lengths,
bounds, membership, item counts. Not
pattern, notformat: the agent enforces both on every answer, and an agent-supplied regex has no place on the browser's main thread.
What changes
Five layers, inner to outer. Each has a type-surface diff and a behavior diff.
Cargo.toml feature flag
agent_runtime_protocol AgentAction::RespondElicitation
agent_session advertise · hold one slot · answer · stop-cancel
agent_fold MessagePart::Elicitation · SessionMetadata.pending_elicitation
apps/web ElicitationPart · composer blockedOnUser · MagicChip
0. Cargo
# Cargo.toml [workspace.dependencies]
agent-client-protocol = { git = "…", rev = "8769d16…", features = ["unstable_elicitation"] }
Unlocks, all in agent_client_protocol::schema::v1:
| Type | Shape (fields that matter) |
|---|---|
ElicitationCapabilities |
form: Option<ElicitationFormCapabilities>, url: Option<ElicitationUrlCapabilities> |
ClientCapabilities::elicitation(..) |
builder |
CreateElicitationRequest |
mode: ElicitationMode (flattened), message: String |
ElicitationMode |
Form(ElicitationFormMode) | Url(ElicitationUrlMode) | Other(..) — tagged mode |
ElicitationFormMode |
scope: ElicitationScope, requested_schema: ElicitationSchema |
ElicitationUrlMode |
scope, elicitation_id: ElicitationId, url: String |
ElicitationScope |
Session { session_id, tool_call_id: Option } | Request { request_id } |
ElicitationSchema |
properties: BTreeMap<String, ElicitationPropertySchema>, required: Option<Vec<String>>, title, description |
ElicitationPropertySchema |
String | Number | Integer | Boolean | Array(MultiSelect) | Other { type_, fields } — tagged type |
CreateElicitationResponse |
action: ElicitationAction (flattened) |
ElicitationAction |
Accept(ElicitationAcceptAction { content: Option<BTreeMap<String, ElicitationContentValue>> }) | Decline | Cancel | Other — tagged action |
ElicitationContentValue |
untagged String | Integer(i64) | Number(f64) | Boolean | StringArray |
CompleteElicitationNotification |
elicitation_id: ElicitationId |
CreateElicitationRequest::matches_method / CompleteElicitationNotification::matches_method |
from the SDK's impl_jsonrpc_* macros |
Everything is #[non_exhaustive], so every match in our code needs a
wildcard arm, same as PermissionOutcome today.
Wasm: agent_fold builds for wasm32. The schema crate is pure serde; the
feature adds no native deps. just ensure-agent-fold-wasm in apps/web
is the check.
1. agent_runtime_protocol — the action
crates/agent_runtime_protocol/src/domain/action.rs.
/// A JSON-RPC request id as the agent sent it, carried whole so the answer
/// echoes the exact id back. `null` is not a valid id for a request that
/// expects a response, so it is not representable here.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[serde(untagged)]
pub enum ElicitationRequestId {
Number(i64),
Str(String),
}
impl ElicitationRequestId {
pub fn from_request_id(id: &RequestId) -> Option<Self>; // Null → None
pub fn to_request_id(&self) -> RequestId;
}
/// What the user decided. Mirrors ACP's three actions; there is no
/// `Other` because we never originate an unknown action.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[serde(tag = "action", rename_all = "snake_case")]
pub enum ElicitationAnswer {
Accept {
/// Form: the submitted values, keyed by property. URL: omitted.
#[serde(default, skip_serializing_if = "Option::is_none")]
content: Option<BTreeMap<String, serde_json::Value>>,
},
Decline,
Cancel,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[serde(rename_all = "camelCase")]
pub struct AgentRespondElicitationAction {
/// The agent's `elicitation/create` request id, not an AgentActionId.
pub request_id: ElicitationRequestId,
#[serde(flatten)]
pub answer: ElicitationAnswer,
}
pub enum AgentAction {
Prompt(AgentPromptAction),
SetModel(AgentSetModelAction),
Compact,
Stop,
RespondElicitation(AgentRespondElicitationAction), // new
}
Wire body on POST /agent-sessions/{id}/control:
{ "type": "respondElicitation", "requestId": 43, "action": "accept",
"content": { "strategy": "balanced" } }
{ "type": "respondElicitation", "requestId": "el-7", "action": "decline" }
Behavior:
supersedes_queued()→false.to_runtime(session_id, minted_id)→ ignoresminted_idand buildsRawJsonRpcMessage::response(request_id.to_request_id(), Ok(CreateElicitationResponse)).contentvalues are convertedserde_json::Value → ElicitationContentValue; a value that is not string / integer / number / boolean / string-array isActionError::Acp(..). This is the onlyAgentActionthat emits a Response frame rather than a Request or Notification; the doc comment on the variant says so.control_from_runtime→ recognizes ato_runtimeResponse whose id is in the fold's pending-elicitation map. The fold does this itself (see §3);control_from_runtimereturnsNonefor responses, unchanged.
Tests (action/test.rs): serde round trip for all three answers; to_runtime
emits a Response with the echoed id and a body that deserializes as
CreateElicitationResponse; non-primitive content is rejected.
2. agent_session — advertise, hold, answer
Types (domain/session/types.rs)
/// The one elicitation this connection is holding for the user.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct PendingElicitation {
pub(super) request_id: RequestId,
}
Nothing else. Message, schema and mode live in the log; the machine only needs to know which id it may answer.
SessionPhase::Live grows the slot:
Live { session_id: SessionId, elicitation: Option<PendingElicitation> }
Effect is unchanged. Answers go out as Effect::Send.
Error (domain/error.rs)
#[error("agent session {0} has no pending elicitation matching that request id")]
ElicitationNotPending(AgentSessionId),
HTTP mapping in inbound/axum_router.rs: 409 CONFLICT (a stale or
double answer, same class as "runtime not attached").
Machine (domain/session/session.rs)
build_initialize_request:
InitializeRequest::new(PROTOCOL_VERSION).client_capabilities(
ClientCapabilities::new().elicitation(
ElicitationCapabilities::new()
.form(ElicitationFormCapabilities::new())
.url(ElicitationUrlCapabilities::new()),
),
)
on_frame while Live — today only respond_to_permission_request. Add
hold_or_refuse_elicitation:
Request with method elicitation/create
parse CreateElicitationRequest
parse fails → JSON-RPC -32602 "invalid elicitation"
mode is Other → -32602 "unsupported elicitation mode"
scope is Request → -32602 "request-scoped elicitation unsupported"
slot already Some → -32602 "one elicitation at a time"
scope.session_id != live session_id → -32602 "elicitation for another session"
otherwise → slot = Some(request.id); no Send
Notification elicitation/complete → nothing (fold handles it)
Every refusal is an Effect::Send of RawJsonRpcMessage::response(id, Err(Error::invalid_params())),
which the actor logs before sending like any other outbound frame — so the
refusal is in the transcript too.
on_command while Live, new arm before the generic enqueue:
RespondElicitation(action)
slot is None or slot.request_id != action.request_id
→ Effect::Complete { Err(ElicitationNotPending) } (nothing sent, nothing logged)
else
→ slot = None; enqueue + flush as usual (to_runtime builds the Response)
Stop (already supersedes_queued): before drop_pending, if the slot
is Some, push Effect::Send { from: <stopper>, Response(id, Ok(Cancel)) }
and clear the slot. Then the existing cancel notification.
Slot lifetime: set on hold; cleared on answer, on stop, and on die. A
new acp_ready builds a fresh machine, so there is nothing to clear
there. The machine keeps the slot across a session/prompt response
(the agent may still be waiting). The fold, not the machine, decides
whether to keep offering the form once the turn has ended — see §3.
Tests (session/tests.rs), in the style of the permission tests:
- initialize frame carries
"elicitation":{"form":{},"url":{}} - form create is held (no Send), status stays Live
- url create is held
- second create while held →
-32602, first slot intact - request-scoped →
-32602;Othermode →-32602 - respond with matching id → Response frame with
action: acceptand content; slot empty; a repeat →ElicitationNotPending - respond with wrong id →
ElicitationNotPending, slot intact - stop with a slot → cancel Response then
session/cancel, in that order - close with a slot → no frame, no panic
Actor (actors.rs): no change. deliver already logs then sends;
acp_method returns None for a Response, so the span simply lacks
rpc.method for an answer. Acceptable; note it.
Harness test agent (agent_harness/src/testing/helpers/agent.rs): the
ClientRequest::parse_message match is over client→agent requests and is
unaffected. Add a helper sends_elicitation(request) -> RequestId and
elicitation_response(id) -> Option<CreateElicitationResponse> so
service-level tests can drive the loop end-to-end.
3. agent_fold — the type surface
crates/folds/agent_fold/src/domain/model.rs. Everything here is
Serialize + specta::Type and lands in
apps/web/src/lib/service-clients/service-agent-fold/generated/types.ts
via just gen-agent-fold-types.
New: the elicitation vocabulary
/// The agent's JSON-RPC id for an elicitation, as the answer must echo it.
/// Re-exported from agent_runtime_protocol so the control body and the
/// fold agree byte-for-byte.
pub use agent_runtime_protocol::domain::action::ElicitationRequestId;
// TS: string | number
/// What the agent asked for.
#[serde(tag = "mode", rename_all = "snake_case")]
pub enum ElicitationRequest {
Form { schema: ElicitationSchema },
Url { elicitation_id: String, url: String },
/// A mode this fold does not know. Kept raw so nothing is lost; never
/// rendered as form or url.
Unrecognized { mode: String, #[specta(type = Unknown)] raw: serde_json::Value },
}
/// ACP's restricted form schema, mirrored so the browser gets a typed
/// union instead of `unknown`.
#[serde(rename_all = "camelCase")]
pub struct ElicitationSchema {
pub title: Option<String>,
pub description: Option<String>,
/// In the agent's order. BTreeMap on the wire is alphabetical; the fold
/// re-reads the raw `properties` object to keep declaration order.
pub properties: Vec<ElicitationProperty>,
pub required: Vec<String>,
}
#[serde(rename_all = "camelCase")]
pub struct ElicitationProperty {
pub name: String,
pub title: Option<String>,
pub description: Option<String>,
pub schema: ElicitationPropertySchema,
}
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ElicitationPropertySchema {
String {
min_length: Option<u32>, max_length: Option<u32>,
pattern: Option<String>, format: Option<ElicitationStringFormat>,
default: Option<String>,
/// Single-select: `enum` (untitled) or `oneOf` (titled). Empty when free text.
options: Vec<ElicitationOption>,
},
Number { minimum: Option<f64>, maximum: Option<f64>, default: Option<f64> },
Integer { minimum: Option<i64>, maximum: Option<i64>, default: Option<i64> },
Boolean { default: Option<bool> },
/// Multi-select. `anyOf` (titled) and `items.enum` (untitled) both land here.
MultiSelect {
min_items: Option<u64>, max_items: Option<u64>,
options: Vec<ElicitationOption>, default: Vec<String>,
},
/// A property type this fold does not know. The browser renders a
/// "cannot display" row; Decline / Cancel still work.
Unrecognized { #[serde(rename = "type")] type_name: String, #[specta(type = Unknown)] raw: serde_json::Value },
}
#[serde(rename_all = "snake_case")]
pub enum ElicitationStringFormat { Email, Uri, Date, DateTime, Other(String) }
#[serde(rename_all = "camelCase")]
pub struct ElicitationOption { pub value: String, pub title: Option<String>, pub description: Option<String> }
/// How the request has resolved so far. `Pending` is a legitimate final
/// state on a dead session, like an unanswered permission.
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ElicitationOutcome {
Pending,
Accepted {
/// The submitted form values (absent for URL accept).
#[specta(type = Unknown)] content: Option<serde_json::Value>,
},
Declined,
Cancelled,
/// URL only: `elicitation/complete` arrived after Accepted.
Completed,
/// Answered with a JSON-RPC error — including our own -32602 refusals.
Errored { message: String },
Unrecognized,
}
Changed: MessagePart
pub enum MessagePart {
Text { .. }, Thought { .. }, ToolUse { .. }, Permission { .. }, Control { .. }, Plan { .. },
/// The agent asking the user a question. // new
Elicitation {
#[serde(rename = "requestId")] request_id: ElicitationRequestId,
#[serde(rename = "toolCall")] tool_call: Option<ToolUseId>,
message: String,
request: ElicitationRequest,
outcome: ElicitationOutcome,
},
}
Changed: SessionMetadata
pub struct SessionMetadata {
pub model, supported_models, title, available_commands, status, // unchanged
/// The one elicitation the user can answer right now. `None` when
/// nothing is pending, the turn that asked has ended, or the
/// connection that asked is gone.
pub pending_elicitation: Option<PendingElicitation>, // new
}
#[serde(rename_all = "camelCase")]
pub struct PendingElicitation {
pub request_id: ElicitationRequestId,
/// Where the matching `MessagePart::Elicitation` lives, so a surface
/// can scroll to it or dedupe against the transcript.
pub turn: u32,
pub tool_call: Option<ToolUseId>,
pub message: String,
pub request: ElicitationRequest,
}
The part is the history; the metadata is the live pointer. The web reads
metadata.pendingElicitation to decide whether to show a form, and the
part to render the transcript row. The channel MagicChip already receives
metadata and can say "Waiting for your input" without folding parts.
Fold state (domain/fold.rs)
struct FoldState {
..,
/// Outstanding elicitations by the agent's request id: where the part
/// sits (message, part), so a response can resolve it.
pending_elicitations: HashMap<RequestId, (usize, usize)>, // new
/// URL elicitations that were accepted and may still `complete`.
completable_elicitations: HashMap<String /* elicitationId */, (usize, usize)>, // new
}
Dispatch additions, each one arm in step:
| Frame | Handler | Effect |
|---|---|---|
to_server Request elicitation/create |
request_elicitation |
push part Pending; record in pending_elicitations; set metadata.pending_elicitation (only if none set — a second one, which the machine refuses, still gets a part so the refusal is visible, but never the slot) |
to_runtime Response Result whose id ∈ pending_elicitations |
resolve_elicitation |
outcome ← Accepted / Declined / Cancelled / Unrecognized; clear slot if it was this id; if URL + Accepted, record in completable_elicitations |
to_runtime Response Error whose id ∈ pending_elicitations |
resolve_elicitation |
outcome ← Errored { message }; clear slot |
to_server Notification elicitation/complete |
complete_elicitation |
if id ∈ completable_elicitations and part is Accepted → Completed; else ignore |
session/prompt Response (turn end) |
existing end_turn |
additionally: metadata.pending_elicitation = None if set. The part stays Pending. |
acp_ready event |
existing | additionally clear pending_elicitations, completable_elicitations, and the metadata slot |
Dispatch ordering caveat: today a to_runtime Response::Result is
routed to resolve_permission. Route by id: try pending_elicitations
first, then pending_permissions. Both maps are keyed by the agent's
request ids, which the agent keeps unique, so there is no ambiguity.
request_elicitation decoding rules, so the TS side never sees a
half-typed schema:
ElicitationMode::Form→ElicitationRequest::Form, mapping eachElicitationPropertySchemavariant 1:1;Other→Unrecognized.- Declaration order: the SDK's
propertiesis aBTreeMap, which sorts keys. Re-readparams.requestedSchema.propertiesas aserde_json::Mapto recover the agent's order —workspace-hackenablesserde_json/preserve_order, so that map is insertion-ordered everywhere in this workspace, wasm included. ElicitationMode::Url→ElicitationRequest::Url.ElicitationMode::Other→ElicitationRequest::Unrecognized.scopeRequest → still folded (the part exists, the machine will have refused it, the Error response resolves it toErrored). The metadata slot is never set for it.
Turn gains nothing: positions are held in FoldState maps like
pending_controls, not per turn, because an answer can legally arrive
after the turn that asked has ended.
Tests (domain/test/fold.rs, plus a fixture in testing/fixtures.rs):
- form create → part Pending, metadata slot set with same id
- accept with content → part Accepted{content}, slot None
- decline / cancel → part, slot None
- error response → Errored, slot None
- url accept then complete → Completed; complete for unknown id ignored
- second create while pending → second part exists, slot still first id
- turn ends with pending → part Pending, slot None
acp_ready→ maps cleared, slot NoneOthermode andOtherproperty type → Unrecognized, raw preserved- interrupted log → Pending is a legal final state
export_typesoutput diff is reviewed by hand once
Wire (inbound/wire.rs)
No change. FoldedStreamEvent::Metadata already carries the whole
SessionMetadata, so the new field streams for free.
4. apps/web
Regenerate first, then code against the types:
just gen-agent-fold-types # fold model → service-agent-fold/generated/types.ts
bun run gen-api # harness openapi → AgentAction incl. respondElicitation
Service client
agentHarnessServiceClient.control(sessionId, request) already takes the
generated ControlRequest = AgentAction. Nothing to add; the union grows.
Feed / context (features/block-agent)
create-agent-session-feed.ts already exposes metadata. Add one
derived accessor on AgentSessionContext:
pendingElicitation: Accessor<PendingElicitation | undefined> // metadata()?.pendingElicitation ?? undefined
Composer (state/composer-state.ts, context/create-composer-controller.ts)
ComposerFacts is unchanged. agentWorking stays "newest turn has no
stop"; a pending elicitation happens mid-turn, so the drain already holds
and queued prompts already wait. That is correct.
Add to the controller's return, read off metadata:
/** The agent is waiting on the user, not generating. Stop still works;
* the send button must not spin. */
blockedOnUser: Accessor<boolean>
AgentInput uses it to swap the spinner for a static "Waiting for your
answer" state while keeping the stop square. No change to isBusy.
Add:
respondElicitation: (answer: ElicitationAnswer) => Promise<void>
which POSTs { type: 'respondElicitation', requestId, ...answer } with
requestId from pendingElicitation(). A 409 means the slot is gone
(someone else answered, or the agent moved on): toast and let the
metadata refresh clear the form. No queueing — the answer is not a
prompt and must not sit behind one.
stop() is unchanged on the client; the server cancels the slot.
Rendering
component/parts/ElicitationPart.tsx, routed from AgentMessage.tsx's
match(...).exhaustive() (a new arm is mandatory or tsc fails):
outcome.kind === 'pending'andpendingElicitation()?.requestId === part.requestId→ interactive card (this is the only place a form is live).pendingbut not the slot (turn ended, or a refused second request that has not resolved yet) → read-only "Not answered".accepted→ read-only key/value ofcontent, or "Opened" for URL.declined/cancelled/completed/errored/unrecognized→ read-only label.
Form renderer, one component per ElicitationPropertySchema variant:
string (text / select when options non-empty), number, integer,
boolean, multi_select (checkbox group), unrecognized (disabled row).
Client validation before POST: required, min/max length, min/max, item
count, format for email/uri/date/date-time, pattern via new RegExp
wrapped in a try and a 50 ms budget check (fail closed to "invalid").
URL card: message, full URL monospace, host highlighted, warning when
host starts with xn--, buttons Open / Decline / Cancel. Open →
respondElicitation({ action: 'accept' }) then
window.open(url, '_blank', 'noopener,noreferrer'). Never fetch the URL.
ui/index.ts gets ElicitationCard next to ToolCard.
MagicChip (LexicalMarkdown/.../MagicChip/presentation.ts)
partActivity gets elicitation arms (.exhaustive() forces it):
pending → { label: 'Waiting for your input', busy: false }; resolved →
'Resuming work' busy. turnInFlightActivity ranks a pending
elicitation with pending permission, above a running tool.
create-magic-chip-model.ts already subscribes to metadata; no change.
Debug gallery
debug/Gallery.tsx gets one form and one URL fixture so the card can be
eyeballed without an agent.
Agent guide
docs/agent-guide/ai-chat.md: one paragraph — an agent session may show
a form or a link-consent card; answer it or press Stop; queued messages
send after the agent finishes.
5. Out of scope, restated
No Postgres table. No new connection-gateway message type. No
request-scoped elicitation. No Macro-as-Agent sending. No change to
permissions or session/request_permission.
Order of work
Each step compiles and passes on its own. 0–3 are backend and can be one PR; 4 is the web PR against the regenerated types.
| # | Step | Gate |
|---|---|---|
| 0 | Cargo feature | cargo check -p agent_session -p agent_fold -p agent_runtime_protocol; just ensure-agent-fold-wasm |
| 1 | AgentAction::RespondElicitation + tests |
cargo test -p agent_runtime_protocol |
| 2 | Machine: advertise, hold, answer, stop-cancel, error, HTTP 409 + tests | cargo test -p agent_session (bash .cursor/infra.sh first — postgres tests) |
| 3 | Fold: model, state, dispatch, tests; regenerate TS | cargo test -p agent_fold; just gen-agent-fold-types; diff review |
| 4 | Web: context accessor, composer, part, chip, gallery, guide | bun run check, bun run test, bun run lint |
| 5 | End-to-end: agent_inmem or a mock agent sends elicitation/create mid-turn; answer from the session page; agent continues |
manual, recorded |
Steps 0–2 must ship together. Advertising a capability with nothing holding the request wedges every agent that uses it.
Risks
- Advertise without hold. Covered by shipping 0–2 as one unit.
- Wrong response routing in the fold. Elicitation and permission
responses both arrive as
to_runtimeResults. Route by id map, test the interleaving (permission pending, elicitation pending, answer both). - Property order. Recovered from the raw
propertiesobject;preserve_orderis already on viaworkspace-hack. A test pins that a schema declaredb, afolds asb, a. - Regex from the agent. Bounded on the client; the server never
evaluates
pattern. - Stale answer after failover. The slot lives in the machine on the
owning replica. A replica change means a new connection → new machine →
no slot →
409. The fold's metadata slot clears on the nextacp_ready. - Composer confusion.
agentWorkingmust stay true while blocked, or queued prompts would fire into the agent's question.blockedOnUseris presentational only.
Open questions (decide before step 4)
- Should Stop cancel the elicitation, or only the model? Plan says both.
- Should a viewer (non-owner) see the form disabled, or hidden? Plan says disabled with "Only the session owner can answer".
- URL accept: fire the POST before or after
window.open? Plan says before, so the agent learns consent even if the popup is blocked; the card then shows the link as a fallback.