Protocol extensibility

docs/docs.json

@@ -58,6 +58,7 @@
           "protocol/file-system",
           "protocol/terminals",
           "protocol/agent-plan",
+          "protocol/extensibility",
           "protocol/schema"
         ]
       },

docs/protocol/extensibility.mdx

@@ -0,0 +1,127 @@
+---
+title: "Extensibility"
+description: "Adding custom data and capabilities"
+---
+
+The Agent Client Protocol provides built-in extension mechanisms that allow implementations to add custom functionality while maintaining compatibility with the core protocol. These mechanisms ensure that Agents and Clients can innovate without breaking interoperability.
+
+## The `_meta` Field
+
+All types in the protocol include a `_meta` field that implementations can use to attach custom information. This includes requests, responses, notifications, and even nested types like content blocks, tool calls, plan entries, and capability objects.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "session/prompt",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "prompt": [
+      {
+        "type": "text",
+        "text": "Hello, world!"
+      }
+    ],
+    "_meta": {
+      "zed.dev/debugMode": true
+    }
+  }
+}
+```
+
+Implementations **MUST NOT** add any custom fields at the root of a type that's part of the specification. All possible names are reserved for future protocol versions.
+
+## Extension Methods
+
+The protocol reserves any method name starting with an underscore (`_`) for custom extensions. This allows implementations to add new functionality without the risk of conflicting with future protocol versions.
+
+Extension methods follow standard [JSON-RPC 2.0](https://www.jsonrpc.org/specification) semantics:
+
+- **[Requests](https://www.jsonrpc.org/specification#request_object)** - Include an `id` field and expect a response
+- **[Notifications](https://www.jsonrpc.org/specification#notification)** - Omit the `id` field and are one-way (fire-and-forget)
+
+### Custom Requests
+
+In addition to the requests specified by the protocol, implementations **MAY** expose and call custom JSON-RPC requests as long as their name starts with an underscore (`_`).
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "_zed.dev/workspace/buffers",
+  "params": {
+    "language": "rust"
+  }
+}
+```
+
+Upon receiveing a custom request, implementations **MUST** respond accordingly with the provided `id`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "buffers": [
+      { "id": 0, "path": "/home/user/project/src/main.rs" },
+      { "id": 1, "path": "/home/user/project/src/editor.rs" }
+    ]
+  }
+}
+```
+
+If the receiveing end doesn't recognize the custom method name, it should respond with the standard "Method not found" error:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32601,
+    "message": "Method not found"
+  }
+}
+```
+
+To avoid such cases, extensions **SHOULD** advertise their [custom capabilities](#advertising-custom-capabilities) so that callers can check their availability first and adapt their interface accordingly.
+
+### Custom Notifications
+
+Custom notifications are regular JSON-RPC notifications that start with an underscore (`_`). Like all notifications, they omit the `id` field:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "_zed.dev/file_opened",
+  "params": {
+    "path": "/home/user/project/src/editor.rs"
+  }
+}
+```
+
+Unlike with custom requests, implementations **SHOULD** ignore unrecognized notifications.
+
+## Advertising Custom Capabilities
+
+Implementations **SHOULD** use the `_meta` field in capability objects to advertise support for extensions and their methods:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "result": {
+    "protocolVersion": 1,
+    "agentCapabilities": {
+      "loadSession": true,
+      "_meta": {
+        "zed.dev": {
+          "workspace": true,
+          "fileNotifications": true
+        }
+      }
+    }
+  }
+}
+```
+
+This allows implementations to negotiate custom features during initialization without breaking compatibility with standard Clients and Agents.

docs/protocol/initialization.mdx

@@ -99,6 +99,8 @@ Capabilities are high-level and are not attached to a specific base protocol con
 
 Capabilities may specify the availability of protocol methods, notifications, or a subset of their parameters. They may also signal behaviors of the Agent or Client implementation.
 
+Implementations can also [advertise custom capabilities](./extensibility#advertising-custom-capabilities) using the `_meta` field to indicate support for protocol extensions.
+
 ### Client Capabilities
 
 The Client **SHOULD** specify whether it supports the following capabilities:

docs/protocol/overview.mdx

@@ -149,8 +149,19 @@ All methods follow standard JSON-RPC 2.0 [error handling](https://www.jsonrpc.or
 - Errors include an `error` object with `code` and `message`
 - Notifications never receive responses (success or error)
 
+## Extensibility
+
+The protocol provides built-in mechanisms for adding custom functionality while maintaining compatibility:
+
+- Add custom data using `_meta` fields
+- Create custom methods with `_method` and `_notification`
+- Advertise custom capabilities during initialization
+
+Learn about [protocol extensibility](./extensibility) to understand how to use these mechanisms.
+
 ## Next Steps
 
 - Learn about [Initialization](./initialization) to understand version and capability negotiation
 - Understand [Session Setup](./session-setup) for creating and loading sessions
 - Review the [Prompt Turn](./prompt-turn) lifecycle
+- Explore [Extensibility](./extensibility) to add custom features