Skip to content

docs(rfd): Initial draft of prompt format change#954

Draft
benbrandt wants to merge 2 commits intomainfrom
prompt-format
Draft

docs(rfd): Initial draft of prompt format change#954
benbrandt wants to merge 2 commits intomainfrom
prompt-format

Conversation

@benbrandt
Copy link
Copy Markdown
Member

@benbrandt benbrandt commented Apr 13, 2026

This is a very early draft with some lingering open questions. But I am
opening now for discussion.

This is a very early draft with some lingering open questions. But I am
opening now for discussion.
Comment thread docs/rfds/v2-prompt.mdx

### What alternative approaches did you consider, and why did you settle on this one?

#### Prompt remains a request
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am kind of torn at the moment of which method I prefer here...

Most of the agent notifications are still needed, it is just a matter of if the client emits session/updates or continues to call methods, but the response lifecycle is different.

Copy link
Copy Markdown
Contributor

@chazcb chazcb Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to prefer that clients use methods for all critical comms so we can confirm the agent received it, but with a {} empty response. Notifications used for non-critical / idempotent client > agent data.

Comment thread docs/rfds/v2-prompt.mdx

This will also be important for queueing messages, depending on how we implement that, so that the client can know if it is still allowed to edit the queued message, or where in the turn order it got inserted.

Even without a new queue, which may allow for editing the queued message, it means that the client doesn't necessarily have to send a `session/cancel` before prompting. This would need some exploration, but potentially the agent could decide whether it cancels the current turn and inserts it immediately, or inserts it at the next convenient break point. This should probably still be defined as "as soon as possible" and queueing would enable some later points, but it could still be more graceful than needing to cancel all current tool calls for example, as is required at the moment.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely interested in what this enables for "steering" messages! That don't require waiting for a full turn completion to be accepted by the agent

Comment thread docs/rfds/v2-prompt.mdx

In order to have a consistent understanding between agent and client on where the user message appears within the session history in relation to other messages, it is important to see when and where the agent has accepted the user message into the feed.

This will also be important for queueing messages, depending on how we implement that, so that the client can know if it is still allowed to edit the queued message, or where in the turn order it got inserted.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the one piece that gives me a little bit of pause

Before this, the structure of ACP messages had the nice effect of tracking exactly the back and forth of the agent and the user. It was a very clean separation of agent state, between runtime (agent) and interface (client). With this change, implementing a client feature like editing a queued message becomes a series of exchanges over the wire for each edit. I guess you can say the same for a config change like plan mode or model? But that state truly does live with the agent; this feels like deferring UI state into the backend

I don't think it's easy to implement something like steering messages without doing either 1. this, or 2. agent can ask to receive a queued message while still in the running state. The later seems uglier!

@CSRessel
Copy link
Copy Markdown
Contributor

I like what this aims to support. In part for multi-client replay, but particularly for agent initiated interactions outside of user prompts 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants