From 8e5996058cb2c98908e32f09edf34d23e176c1e1 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Fri, 23 Oct 2026 23:33:39 +0200 Subject: [PATCH] docs(unstable-v2): note that tool text can stream like message text The v2 tool-call docs described tool_call_content_chunk as streaming "complete" content items, which read as discouraging agents from streaming a tool's text in pieces the way they stream message text. Nothing in the append rules requires that: a chunk appends one item, and clients can present adjacent text items as continuous text, as they do for messages. Drop "complete" from the prompt-lifecycle walkthrough and add a non-normative note to Streaming Content, in both the published and draft v2 pages. --- docs/protocol/v2/draft/prompt-lifecycle.mdx | 2 +- docs/protocol/v2/draft/tool-calls.mdx | 5 +++++ docs/protocol/v2/prompt-lifecycle.mdx | 2 +- docs/protocol/v2/tool-calls.mdx | 5 +++++ 4 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/protocol/v2/draft/prompt-lifecycle.mdx b/docs/protocol/v2/draft/prompt-lifecycle.mdx index 6bdbe36ef..db86229df 100644 --- a/docs/protocol/v2/draft/prompt-lifecycle.mdx +++ b/docs/protocol/v2/draft/prompt-lifecycle.mdx @@ -811,7 +811,7 @@ Once permission is granted (if required), the Agent **SHOULD** invoke the tool a ``` As the tool runs, the Agent **MAY** send additional updates, providing -real-time feedback about tool execution progress. The Agent streams complete +real-time feedback about tool execution progress. The Agent streams incremental content items with `tool_call_content_chunk`: ```json diff --git a/docs/protocol/v2/draft/tool-calls.mdx b/docs/protocol/v2/draft/tool-calls.mdx index da2e36b62..9dbf4da3a 100644 --- a/docs/protocol/v2/draft/tool-calls.mdx +++ b/docs/protocol/v2/draft/tool-calls.mdx @@ -196,6 +196,11 @@ chunks. Later chunks append to that replacement content. A `tool_call_update` with `content: []` or `content: null` clears the tool-call content. A `tool_call_content_chunk`'s `_meta`, when present, is chunk-scoped. +An Agent can stream a tool's text output the way it streams message text, by +sending each piece as a text content item in its own +`tool_call_content_chunk`. Clients can present adjacent text items as one +continuous text. + ## Requesting Permission Permission requests do not by themselves change the session's foreground state. While foreground work is blocked on a permission response, the Agent **SHOULD** report `requires_action`. Once reported, it **MUST** report `running` when foreground progress resumes, or `idle` if the work ends without resuming. Requests for independent background activity may arrive while the session remains `idle`. See [Waiting for User Action](/protocol/v2/draft/prompt-lifecycle#waiting-for-user-action) for concurrent requests and late answers. diff --git a/docs/protocol/v2/prompt-lifecycle.mdx b/docs/protocol/v2/prompt-lifecycle.mdx index f74cac28a..7852e2ba4 100644 --- a/docs/protocol/v2/prompt-lifecycle.mdx +++ b/docs/protocol/v2/prompt-lifecycle.mdx @@ -702,7 +702,7 @@ Once permission is granted (if required), the Agent **SHOULD** invoke the tool a ``` As the tool runs, the Agent **MAY** send additional updates, providing -real-time feedback about tool execution progress. The Agent streams complete +real-time feedback about tool execution progress. The Agent streams incremental content items with `tool_call_content_chunk`: ```json diff --git a/docs/protocol/v2/tool-calls.mdx b/docs/protocol/v2/tool-calls.mdx index 8d711dbdf..3f0682b1c 100644 --- a/docs/protocol/v2/tool-calls.mdx +++ b/docs/protocol/v2/tool-calls.mdx @@ -194,6 +194,11 @@ chunks. Later chunks append to that replacement content. A `tool_call_update` with `content: []` or `content: null` clears the tool-call content. A `tool_call_content_chunk`'s `_meta`, when present, is chunk-scoped. +An Agent can stream a tool's text output the way it streams message text, by +sending each piece as a text content item in its own +`tool_call_content_chunk`. Clients can present adjacent text items as one +continuous text. + ## Requesting Permission Permission requests do not by themselves change the session's foreground state. While foreground work is blocked on a permission response, the Agent **SHOULD** report `requires_action`. Once reported, it **MUST** report `running` when foreground progress resumes, or `idle` if the work ends without resuming. Requests for independent background activity may arrive while the session remains `idle`. See [Waiting for User Action](/protocol/v2/prompt-lifecycle#waiting-for-user-action) for concurrent requests and late answers.