docs: reconcile v1.15 spec text, unstable RFDs and the proxy-chains RFD (#2743)

* docs(schema): restore the v1 meaning of Implementation.title and the tool-call intro

The plain-language pass (#2730) changed two v1 passages beyond wording:

- `Implementation.title` said it "should be readable by people", which adds
  a should-statement to the stable v1 spec and schema. Restore the v1.14.0
  meaning ("optimized to be human-readable and easily understood") without
  the em dash. The v2 copy uses the same text.
- The v1 tool-calls intro said Agents may use Client capabilities "while
  running a tool call", which reads as a new timing limit. Drop the temporal
  clause and keep the original "or".

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(protocol): align v2 session/cancel text with the background-work rules

#2738 narrowed `session/cancel` so listed background work keeps running and
its permission requests stay open, but several v2 passages still stated the
old rule. Update them in the stable and draft pages and the v2 schema:

- prompt-lifecycle: add the missing "or" in the announce-before-listing
  rule (stable only, the draft already had it), scope "stop all tool call
  invocations" to the cancelled foreground work, put the `-32800` rule next
  to the prompts it covers, and state that a `subject` the Client does not
  recognize, such as a custom subject type, is answered with `cancelled`.
- tool-calls, cancellation, migration: answer pending permission requests
  for the cancelled foreground work, not every request in the session.
- Schema: `RequestPermissionOutcome::Cancelled`, the
  `session/request_permission` request and the `session/cancel`
  notification descriptions now state the narrowed rule and the custom
  subject case.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(unstable): reconcile session/status, auth/status and session/set_title with their RFDs

- session/status: keep `-32002` for sessions the Agent does not know, and
  state the RFD's exception in the schema, the draft error pages and the
  RFD's own error rule: an Agent that cannot cheaply tell a saved session
  from an unknown one may return `saved`, and the later resume or load gets
  `-32002`.
- auth/status: add it to the draft v2 list of requests that do not fail
  with `auth_required`, and put the RFD's MUST NOT in the schema.
- session/set_title: refusing a session the Agent cannot safely update
  returns `-32602`, as an explicit exception to retitling any listed
  session, in the schema, the draft error pages and the RFD.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(rfd): resolve proxy-chains ambiguities and match the reference conductor

Define, in the proxy-chains RFD and the proxy schema descriptions:

- Errors the conductor returns itself (before initialization, failed
  chain start, `proxy/initialize` from outside, misplaced `proxy/successor`,
  malformed envelopes, a component that exited), separate from the
  pass-through rule for wrapped results.
- Hop-local cancellation: `$/cancel_request` names a request on its own
  connection, is never forwarded, and each hop re-issues it.
- Envelope `_meta` is hop-local and not copied into the unwrapped message.
- Version selection along the chain, the proxy's obligation to forward
  `initialize` before answering, the proxy/initialize result built from the
  successor's (same `protocolVersion`), and repeated `proxy/initialize`.
- "Unchanged" results and errors mean the same JSON value.
- Wrapped `params` is an object, an array, or `null`.
- Forwarding of unknown requests and notifications and where `-32601`
  comes from.

Also link version negotiation for v1 and v2, replace the old
`sacp-conductor` name, drop crash-handling claims the reference conductor
does not implement, and add a revision-history entry.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(unstable): drop the saved-for-unknown and retitle-refusal exceptions

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(protocol): let the Agent cancel permission requests on session/cancel in v2

The Agent knows which work each permission request belongs to, so on
session/cancel it stops waiting for the cancelled work's requests and
cancels them with $/cancel_request, as it already does for elicitations.
Clients MAY answer them early. session/close cancels every pending
permission request the same way. This removes the subject-based rules
for which requests the Client answers.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: benbrandt

agent-client-protocol-schema/src/v1/agent.rs

@@ -207,7 +207,8 @@ pub struct Implementation {
     /// Intended for programmatic or logical use, but can be used as a display
     /// name fallback if title isn't present.
     pub name: String,
-    /// Intended for UI and end-user contexts, so it should be readable by people.
+    /// Intended for UI and end-user contexts and optimized to be human-readable
+    /// and easily understood.
     ///
     /// If not provided, the name should be used for display.
     #[serde_as(deserialize_as = "DefaultOnError")]
@@ -241,7 +242,8 @@ impl Implementation {
         }
     }
 
-    /// Intended for UI and end-user contexts, so it should be readable by people.
+    /// Intended for UI and end-user contexts and optimized to be human-readable
+    /// and easily understood.
     ///
     /// If not provided, the name should be used for display.
     #[must_use]
@@ -453,6 +455,9 @@ crate::serde_util::default_on_null! {
     /// Request parameters for the `auth/status` method.
     ///
     /// Queries the agent's current authentication state without changing it.
+    ///
+    /// Agents MUST NOT reject it with `auth_required` (`-32000`), since Clients call it to learn
+    /// whether authentication is required.
     #[serde_as]
     #[skip_serializing_none]
     #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
@@ -6465,7 +6470,7 @@ pub enum ClientRequest {
     /// Queries the agent's current authentication state.
     ///
     /// This method is only available if the agent advertises the `auth.status` capability.
-    /// It MUST NOT change any agent state.
+    /// It MUST NOT change any agent state, and agents MUST NOT reject it with `auth_required`.
     #[cfg(feature = "unstable_auth_status")]
     AuthStatusRequest(AuthStatusRequest),
     /// Creates a new conversation session with the agent.

agent-client-protocol-schema/src/v1/proxy.rs

@@ -25,6 +25,10 @@ use crate::IntoOption;
 /// successor, which tells the component to run as a proxy. The params and the response are
 /// the same as for `initialize`. A conductor sends `initialize` to the final agent.
 ///
+/// The params carry the protocol version the conductor selected: the client's requested
+/// version, unless the conductor supports only a lower one. Before answering successfully,
+/// the proxy MUST forward an `initialize` request to its successor through `proxy/successor`.
+///
 /// See the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains).
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
@@ -56,8 +60,9 @@ impl From<InitializeRequest> for InitializeProxyRequest {
 ///
 /// Response to `proxy/initialize`.
 ///
-/// The same as the `initialize` response. The proxy answers with the capabilities of the
-/// chain from itself onward.
+/// The same as the `initialize` response. The proxy builds it from its successor's
+/// `initialize` response and answers with the capabilities of the chain from itself onward.
+/// It MUST NOT change `protocolVersion`.
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "proxy", "x-method" = PROXY_INITIALIZE_METHOD_NAME)))]
@@ -94,8 +99,12 @@ impl From<InitializeResponse> for InitializeProxyResponse {
 /// deliver a message from the successor to the proxy. The envelope wraps one request: `method`
 /// and `params` are the wrapped request's method and params.
 ///
-/// The result or error of the wrapped request is returned unchanged as the result or error
-/// of the `proxy/successor` request.
+/// The result or error of the wrapped request is returned unchanged, as the same JSON value,
+/// as the result or error of the `proxy/successor` request. Errors the conductor returns
+/// itself, for example because the successor has exited, are not wrapped results.
+///
+/// To cancel it, the sender sends `$/cancel_request` with the ID of this `proxy/successor`
+/// request on the same connection. Cancellation is never forwarded to another hop.
 ///
 /// See the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains).
 #[serde_as]
@@ -111,12 +120,14 @@ pub struct ProxySuccessorRequest {
     /// Params of the wrapped request, forwarded unchanged.
     ///
     /// Optional. Omitted and `null` are equivalent and mean the wrapped request has no params.
+    /// When present, it MUST be a JSON object or array, as JSON-RPC requires.
     /// The wrapped request's own `_meta` stays inside these params.
     #[cfg_attr(feature = "schemars", schemars(with = "Option<serde_json::Value>"))]
     #[serde(default)]
     pub params: Option<Arc<RawValue>>,
     /// Metadata for the `proxy/successor` envelope itself, separate from the wrapped
-    /// message's `_meta`.
+    /// message's `_meta`. It is hop-local: the conductor does not copy it into the message
+    /// it unwraps.
     ///
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
@@ -184,12 +195,14 @@ pub struct ProxySuccessorNotification {
     /// Params of the wrapped notification, forwarded unchanged.
     ///
     /// Optional. Omitted and `null` are equivalent and mean the wrapped notification has no params.
+    /// When present, it MUST be a JSON object or array, as JSON-RPC requires.
     /// The wrapped notification's own `_meta` stays inside these params.
     #[cfg_attr(feature = "schemars", schemars(with = "Option<serde_json::Value>"))]
     #[serde(default)]
     pub params: Option<Arc<RawValue>>,
     /// Metadata for the `proxy/successor` envelope itself, separate from the wrapped
-    /// message's `_meta`.
+    /// message's `_meta`. It is hop-local: the conductor does not copy it into the message
+    /// it unwraps.
     ///
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Implementations MUST NOT make assumptions about values at

agent-client-protocol-schema/src/v2/agent.rs

@@ -198,7 +198,8 @@ pub struct Implementation {
     /// Intended for programmatic or logical use, but can be used as a display
     /// name fallback if title isn't present.
     pub name: String,
-    /// Intended for UI and end-user contexts, so it should be readable by people.
+    /// Intended for UI and end-user contexts and optimized to be human-readable
+    /// and easily understood.
     ///
     /// If not provided, the name should be used for display.
     ///
@@ -234,7 +235,8 @@ impl Implementation {
         }
     }
 
-    /// Intended for UI and end-user contexts, so it should be readable by people.
+    /// Intended for UI and end-user contexts and optimized to be human-readable
+    /// and easily understood.
     ///
     /// If not provided, the name should be used for display.
     #[must_use]
@@ -454,6 +456,9 @@ crate::serde_util::default_on_null! {
     /// Request parameters for the `auth/status` method.
     ///
     /// Queries the agent's current authentication state without changing it.
+    ///
+    /// Agents MUST NOT reject it with `auth_required` (`-32000`), since Clients call it to learn
+    /// whether authentication is required.
     #[serde_as]
     #[skip_serializing_none]
     #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
@@ -7202,7 +7207,7 @@ pub enum ClientRequest {
     /// Queries the agent's current authentication state.
     ///
     /// This method is only available if the agent advertises the `auth.status` capability.
-    /// It MUST NOT change any agent state.
+    /// It MUST NOT change any agent state, and agents MUST NOT reject it with `auth_required`.
     #[cfg(feature = "unstable_auth_status")]
     AuthStatusRequest(Box<AuthStatusRequest>),
     /// Creates a new conversation session with the agent.
@@ -7459,10 +7464,16 @@ pub enum AgentResponse {
 pub enum ClientNotification {
     /// Cancels a session's foreground work and its prompts not yet inserted.
     ///
-    /// Background work is not covered, but the Agent MAY stop it too.
+    /// Work in the latest `background` list is not covered and keeps running. The
+    /// Agent MAY stop background activity it does not list.
     ///
     /// Upon receiving this notification, the Agent SHOULD stop all language model
-    /// requests and all tool call invocations as soon as possible.
+    /// requests and all tool call invocations of the cancelled foreground work as soon
+    /// as possible.
+    ///
+    /// The Agent MUST stop waiting for pending `session/request_permission` requests of
+    /// the cancelled work and treat them as not approved. It SHOULD cancel each of them
+    /// with `$/cancel_request`.
     ///
     /// After all ongoing operations have been successfully aborted and pending
     /// updates have been sent, the Agent MUST send an idle `state_update` session

agent-client-protocol-schema/src/v2/client.rs

@@ -3530,10 +3530,10 @@ pub enum RequestPermissionOutcome {
     /// cancelled, the user dismissed the prompt, or the client declined it by policy.
     /// Agents MUST NOT proceed with the operation.
     ///
-    /// When a client sends a `session/cancel` notification, it MUST respond to all
-    /// pending `session/request_permission` requests in that session with this
-    /// `cancelled` outcome, without answering any request twice. Requests in other
-    /// sessions are unaffected.
+    /// The client answers a request the agent cancels with `$/cancel_request` with
+    /// this outcome. After sending `session/cancel`, the client MAY also send it
+    /// without waiting for `$/cancel_request`, for a request it knows belongs to the
+    /// cancelled foreground work.
     ///
     /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#cancellation)
     Cancelled(CancelledPermissionOutcome),
@@ -3977,8 +3977,9 @@ pub enum AgentRequest {
     /// a potentially sensitive operation. The client should present the options
     /// to the user and return their decision.
     ///
-    /// If the client cancels active session work via `session/cancel`, it MUST
-    /// respond to this request with the `cancelled` outcome.
+    /// After `session/cancel`, the agent stops waiting for requests of the cancelled
+    /// foreground work and SHOULD cancel them with `$/cancel_request`. The client
+    /// answers a cancelled request with the `cancelled` outcome.
     ///
     /// See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v2/tool-calls#requesting-permission)
     RequestPermissionRequest(Box<RequestPermissionRequest>),

agent-client-protocol-schema/src/v2/proxy.rs

@@ -25,6 +25,10 @@ use crate::IntoOption;
 /// successor, which tells the component to run as a proxy. The params and the response are
 /// the same as for `initialize`. A conductor sends `initialize` to the final agent.
 ///
+/// The params carry the protocol version the conductor selected: the client's requested
+/// version, unless the conductor supports only a lower one. Before answering successfully,
+/// the proxy MUST forward an `initialize` request to its successor through `proxy/successor`.
+///
 /// See the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains).
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
@@ -56,8 +60,9 @@ impl From<InitializeRequest> for InitializeProxyRequest {
 ///
 /// Response to `proxy/initialize`.
 ///
-/// The same as the `initialize` response. The proxy answers with the capabilities of the
-/// chain from itself onward.
+/// The same as the `initialize` response. The proxy builds it from its successor's
+/// `initialize` response and answers with the capabilities of the chain from itself onward.
+/// It MUST NOT change `protocolVersion`.
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "proxy", "x-method" = PROXY_INITIALIZE_METHOD_NAME)))]
@@ -94,8 +99,12 @@ impl From<InitializeResponse> for InitializeProxyResponse {
 /// deliver a message from the successor to the proxy. The envelope wraps one request: `method`
 /// and `params` are the wrapped request's method and params.
 ///
-/// The result or error of the wrapped request is returned unchanged as the result or error
-/// of the `proxy/successor` request.
+/// The result or error of the wrapped request is returned unchanged, as the same JSON value,
+/// as the result or error of the `proxy/successor` request. Errors the conductor returns
+/// itself, for example because the successor has exited, are not wrapped results.
+///
+/// To cancel it, the sender sends `$/cancel_request` with the ID of this `proxy/successor`
+/// request on the same connection. Cancellation is never forwarded to another hop.
 ///
 /// See the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains).
 #[serde_as]
@@ -111,12 +120,14 @@ pub struct ProxySuccessorRequest {
     /// Params of the wrapped request, forwarded unchanged.
     ///
     /// Optional. Omitted and `null` are equivalent and mean the wrapped request has no params.
+    /// When present, it MUST be a JSON object or array, as JSON-RPC requires.
     /// The wrapped request's own `_meta` stays inside these params.
     #[cfg_attr(feature = "schemars", schemars(with = "Option<serde_json::Value>"))]
     #[serde(default)]
     pub params: Option<Arc<RawValue>>,
     /// Metadata for the `proxy/successor` envelope itself, separate from the wrapped
-    /// message's `_meta`.
+    /// message's `_meta`. It is hop-local: the conductor does not copy it into the message
+    /// it unwraps.
     ///
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
@@ -184,12 +195,14 @@ pub struct ProxySuccessorNotification {
     /// Params of the wrapped notification, forwarded unchanged.
     ///
     /// Optional. Omitted and `null` are equivalent and mean the wrapped notification has no params.
+    /// When present, it MUST be a JSON object or array, as JSON-RPC requires.
     /// The wrapped notification's own `_meta` stays inside these params.
     #[cfg_attr(feature = "schemars", schemars(with = "Option<serde_json::Value>"))]
     #[serde(default)]
     pub params: Option<Arc<RawValue>>,
     /// Metadata for the `proxy/successor` envelope itself, separate from the wrapped
-    /// message's `_meta`.
+    /// message's `_meta`. It is hop-local: the conductor does not copy it into the message
+    /// it unwraps.
     ///
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
     /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.

docs/protocol/v1/draft/initialization.mdx

@@ -357,9 +357,9 @@ Both Clients and Agents **SHOULD** provide information about their implementatio
 </ParamField>
 
 <ParamField path="title" type="string">
-  Intended for UI and end-user contexts, so it should be readable by people.
-  Optional. Omitted and `null` are equivalent. If not provided, the name should
-  be used for display.
+  Intended for UI and end-user contexts and optimized to be human-readable and
+  easily understood. Optional. Omitted and `null` are equivalent. If not
+  provided, the name should be used for display.
 </ParamField>
 
 <ParamField path="version" type="string" required>