docs/specification.md

@@ -23641,7 +23641,18 @@ sequenceDiagram
 
 ##### Wire Format
 
-All A2A communication uses **JSON-RPC 2.0** framing:
+All A2A communication uses **JSON-RPC 2.0** framing as defined by the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification). The internal `A2aRequest` and `A2aResponse` domain objects use the **standard JSON-RPC 2.0 field names** — `jsonrpc`, `method`, `id`, `params`, `result`, and `error` — ensuring full protocol compliance and interoperability with any JSON-RPC 2.0 client or tooling.
+
+###### Envelope Field Reference
+
+| Field | Appears In | Type | Description |
+| :---- | :--------- | :--- | :---------- |
+| `jsonrpc` | Request & Response | `"2.0"` (string literal) | Always `"2.0"`. Identifies the JSON-RPC protocol version. |
+| `method` | Request, Notification | string | The A2A operation name (e.g. `message/send`) or `_cleveragents/` extension method. |
+| `id` | Request & Response | integer \| string \| null | Correlates a response to its request. Omitted in notifications (fire-and-forget). |
+| `params` | Request, Notification | object \| array | Method-specific input parameters. Always an object for CleverAgents methods. |
+| `result` | Success Response | any | Present on success; mutually exclusive with `error`. |
+| `error` | Error Response | object | Present on failure; mutually exclusive with `result`. Contains `code` (integer), `message` (string), and optional `data`. |
 
 **Request:**
 ```json
@@ -23649,11 +23660,14 @@ All A2A communication uses **JSON-RPC 2.0** framing:
   "jsonrpc": "2.0",
   "id": 1,
   "method": "message/send",
-  "params": { "message": { "role": "user", "parts": [{ "kind": "text", "text": "Refactor the auth module" }] }, "taskId": "task_01HXR..." }
+  "params": {
+    "message": { "role": "user", "parts": [{ "kind": "text", "text": "Refactor the auth module" }] },
+    "taskId": "task_01HXR..."
+  }
 }
 ```
 
-**Response:**
+**Success response:**
 ```json
 {
   "jsonrpc": "2.0",
@@ -23662,12 +23676,16 @@ All A2A communication uses **JSON-RPC 2.0** framing:
 }
 ```
 
-**Streaming event (SSE via `message/stream`):**
+**Streaming event (SSE notification via `message/stream`):**
 ```json
 {
   "jsonrpc": "2.0",
   "method": "task/statusUpdate",
-  "params": { "taskId": "task_01HXR...", "status": { "state": "working" }, "message": { "role": "agent", "parts": [{ "kind": "text", "text": "I'll start by..." }] } }
+  "params": {
+    "taskId": "task_01HXR...",
+    "status": { "state": "working" },
+    "message": { "role": "agent", "parts": [{ "kind": "text", "text": "I'll start by..." }] }
+  }
 }
 ```
 
@@ -23690,6 +23708,17 @@ All A2A communication uses **JSON-RPC 2.0** framing:
 }
 ```
 
+###### A2aVersionNegotiator
+
+The `A2aVersionNegotiator` component handles backward compatibility when a client and server are running different versions of the CleverAgents A2A extension protocol. On connection establishment, the negotiator:
+
+1. Reads the `_cleveragents.version` field from the server's Agent Card.
+2. Compares it against the client's supported version range.
+3. Selects the highest mutually supported minor version.
+4. Downgrades the request envelope shape if the server is on an older minor version (e.g. omitting fields added in a later minor version).
+
+This ensures that a newer CLI can still communicate with an older server (and vice versa) within the same major version, without requiring simultaneous upgrades of all components.
+
 ##### Authentication
 
 Authentication uses HTTP auth schemes declared in the server's Agent Card: