Skip to content

Commit 2da60af

Browse files
authored
docs(protocol): define prompts sent during active work (#2627)
1 parent b82c966 commit 2da60af

2 files changed

Lines changed: 14 additions & 4 deletions

File tree

‎docs/protocol/v2/draft/prompt-lifecycle.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,12 @@ The same insertion boundary applies when [closing the session](/protocol/v2/draf
328328

329329
`running` reports foreground work, not insertion. It may precede insertion, the prompt response, and user-message updates, for example while a foreground hook runs. It does not acknowledge a pending prompt's insertion.
330330

331+
#### Prompts During Active Work
332+
333+
Clients **MAY** send `session/prompt` in any state, including while foreground work is `running` or `requires_action`. The Agent either inserts the prompt right away or holds it and inserts it later. Held prompts are inserted in the order they were received. What inserting during active work means, such as steering the current turn or starting the next one, is up to the Agent. Agents **MUST NOT** reject a prompt only because foreground work is active.
334+
335+
A held prompt's response stays pending until the prompt is inserted. The Client can withdraw it with [`$/cancel_request`](/protocol/v2/draft/cancellation), and [`session/cancel`](#cancellation) and `session/close` answer prompts that haven't been inserted with `-32800`. Future capabilities may let Agents advertise steering or queueing behavior.
336+
331337
#### Prompts that are never inserted
332338

333339
If a request is rejected before insertion, including by a hook or early failure, the Agent **MUST** return a JSON-RPC error response and **MUST NOT** emit user-message updates for that submission. [Request cancellation](/protocol/v2/draft/cancellation) before insertion uses `-32800`.
@@ -1061,8 +1067,7 @@ another foreground interval then begins, it reports an active state again,
10611067
even when the next interval starts immediately. Consecutive completed turns
10621068
therefore have an idle boundary, not a continuous `running` state. Completing
10631069
an individual prompt, command, or tool call while other foreground activity
1064-
continues does not require an idle boundary. This does not require Agents to
1065-
support prompts while work is active.
1070+
continues does not require an idle boundary. For prompts sent while work is active, see [Prompts During Active Work](#prompts-during-active-work).
10661071

10671072
Handling an accepted prompt, including a local slash command that performs no
10681073
model work, **MUST** use the foreground lifecycle. A local command handled from

‎docs/protocol/v2/prompt-lifecycle.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,12 @@ The same insertion boundary applies when [closing the session](/protocol/v2/sess
257257

258258
`running` reports foreground work, not insertion. It may precede insertion, the prompt response, and user-message updates, for example while a foreground hook runs. It does not acknowledge a pending prompt's insertion.
259259

260+
#### Prompts During Active Work
261+
262+
Clients **MAY** send `session/prompt` in any state, including while foreground work is `running` or `requires_action`. The Agent either inserts the prompt right away or holds it and inserts it later. Held prompts are inserted in the order they were received. What inserting during active work means, such as steering the current turn or starting the next one, is up to the Agent. Agents **MUST NOT** reject a prompt only because foreground work is active.
263+
264+
A held prompt's response stays pending until the prompt is inserted. The Client can withdraw it with [`$/cancel_request`](/protocol/v2/cancellation), and [`session/cancel`](#cancellation) and `session/close` answer prompts that haven't been inserted with `-32800`. Future capabilities may let Agents advertise steering or queueing behavior.
265+
260266
#### Prompts that are never inserted
261267

262268
If a request is rejected before insertion, including by a hook or early failure, the Agent **MUST** return a JSON-RPC error response and **MUST NOT** emit user-message updates for that submission. [Request cancellation](/protocol/v2/cancellation) before insertion uses `-32800`.
@@ -935,8 +941,7 @@ another foreground interval then begins, it reports an active state again,
935941
even when the next interval starts immediately. Consecutive completed turns
936942
therefore have an idle boundary, not a continuous `running` state. Completing
937943
an individual prompt, command, or tool call while other foreground activity
938-
continues does not require an idle boundary. This does not require Agents to
939-
support prompts while work is active.
944+
continues does not require an idle boundary. For prompts sent while work is active, see [Prompts During Active Work](#prompts-during-active-work).
940945

941946
Handling an accepted prompt, including a local slash command that performs no
942947
model work, **MUST** use the foreground lifecycle. A local command handled from

0 commit comments

Comments
 (0)