docs(schema): define AbsolutePath syntax and reject relative cwd (#2629)

Author: benbrandt

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

@@ -51,6 +51,9 @@ use std::{
 };
 
 /// An absolute filesystem path used by the protocol.
+///
+/// Uses the native syntax of the machine the Agent runs on, such as `/home/user/project`,
+/// `C:\Users\user\project`, or `\\server\share\project`. It is not a URI.
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, From)]
 #[serde(transparent)]

docs/protocol/v2/draft/overview.mdx

@@ -214,7 +214,7 @@ Either side can send [`$/cancel_request`](/protocol/v2/draft/cancellation) to ca
 
 ## Argument requirements
 
-- All file paths in the protocol **MUST** be absolute.
+- All file paths in the protocol **MUST** be absolute, in the native syntax of the machine the Agent runs on (for example `/home/user/project`, `C:\Users\user\project`, or `\\server\share\project`), and are not URIs.
 - Line numbers are 1-based
 
 ## Error Handling

docs/protocol/v2/draft/schema.mdx

@@ -1841,6 +1841,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
 
 An absolute filesystem path used by the protocol.
 
+Uses the native syntax of the machine the Agent runs on, such as `/home/user/project`,
+`C:\Users\user\project`, or `\\server\share\project`. It is not a URI.
+
 **Type:** `string`
 
 ## <span class="font-mono">AgentAuthCapabilities</span>

docs/protocol/v2/draft/session-list.mdx

@@ -61,10 +61,11 @@ Clients discover existing sessions by calling the `session/list` method with opt
 All parameters are optional. A request with an empty `params` object returns the first page of sessions.
 
 <ParamField path="cwd" type="string">
-  Filter sessions by working directory. Must be an absolute path. Only sessions
-  whose `cwd` is this same directory are returned; sessions in subdirectories or
-  with it in `additionalDirectories` don't match. Agents **MAY** normalize paths
-  when comparing, for example ignoring a trailing separator.
+  Filter sessions by working directory. Must be an absolute path; Agents reject
+  a relative path with `-32602`. Only sessions whose `cwd` is this same
+  directory are returned; sessions in subdirectories or with it in
+  `additionalDirectories` don't match. Agents **MAY** normalize paths when
+  comparing, for example ignoring a trailing separator.
 </ParamField>
 
 <ParamField path="cursor" type="string">

docs/protocol/v2/draft/session-setup.mdx

@@ -519,7 +519,7 @@ Clients use this ID to:
 
 The `cwd` (current working directory) parameter establishes the primary file system context for the session. This directory:
 
-- **MUST** be an absolute path
+- **MUST** be an absolute path. Agents reject a request with a relative `cwd` with `-32602`.
 - **MUST** be used for the session regardless of where the Agent subprocess was spawned
 - **MUST** remain the base for relative-path resolution
 - **MUST** be part of the session's effective root set

docs/protocol/v2/overview.mdx

@@ -204,7 +204,7 @@ Either side can send [`$/cancel_request`](/protocol/v2/cancellation) to cancel a
 
 ## Argument requirements
 
-- All file paths in the protocol **MUST** be absolute.
+- All file paths in the protocol **MUST** be absolute, in the native syntax of the machine the Agent runs on (for example `/home/user/project`, `C:\Users\user\project`, or `\\server\share\project`), and are not URIs.
 - Line numbers are 1-based
 
 ## Error Handling

docs/protocol/v2/schema.mdx

@@ -1387,6 +1387,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
 
 An absolute filesystem path used by the protocol.
 
+Uses the native syntax of the machine the Agent runs on, such as `/home/user/project`,
+`C:\Users\user\project`, or `\\server\share\project`. It is not a URI.
+
 **Type:** `string`
 
 ## <span class="font-mono">AgentAuthCapabilities</span>

docs/protocol/v2/session-list.mdx

@@ -61,10 +61,11 @@ Clients discover existing sessions by calling the `session/list` method with opt
 All parameters are optional. A request with an empty `params` object returns the first page of sessions.
 
 <ParamField path="cwd" type="string">
-  Filter sessions by working directory. Must be an absolute path. Only sessions
-  whose `cwd` is this same directory are returned; sessions in subdirectories or
-  with it in `additionalDirectories` don't match. Agents **MAY** normalize paths
-  when comparing, for example ignoring a trailing separator.
+  Filter sessions by working directory. Must be an absolute path; Agents reject
+  a relative path with `-32602`. Only sessions whose `cwd` is this same
+  directory are returned; sessions in subdirectories or with it in
+  `additionalDirectories` don't match. Agents **MAY** normalize paths when
+  comparing, for example ignoring a trailing separator.
 </ParamField>
 
 <ParamField path="cursor" type="string">

docs/protocol/v2/session-setup.mdx

@@ -450,7 +450,7 @@ Clients use this ID to:
 
 The `cwd` (current working directory) parameter establishes the primary file system context for the session. This directory:
 
-- **MUST** be an absolute path
+- **MUST** be an absolute path. Agents reject a request with a relative `cwd` with `-32602`.
 - **MUST** be used for the session regardless of where the Agent subprocess was spawned
 - **MUST** remain the base for relative-path resolution
 - **MUST** be part of the session's effective root set

schema/v2/schema.json

@@ -1431,7 +1431,7 @@
       ]
     },
     "AbsolutePath": {
-      "description": "An absolute filesystem path used by the protocol.",
+      "description": "An absolute filesystem path used by the protocol.\n\nUses the native syntax of the machine the Agent runs on, such as `/home/user/project`,\n`C:\\Users\\user\\project`, or `\\\\server\\share\\project`. It is not a URI.",
       "type": "string"
     },
     "DiffPathChange": {