docs(schema): define session/list cwd matching (#2609)

Author: benbrandt

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

@@ -1743,6 +1743,9 @@ crate::serde_util::default_on_null! {
     pub struct ListSessionsRequest {
         /// Filter sessions by working directory. Must be an absolute path.
         ///
+        /// Only sessions whose `cwd` is this same directory match; subdirectories and
+        /// `additionalDirectories` don't. Agents MAY normalize paths when comparing.
+        ///
         /// Omitted and `null` are equivalent and mean sessions are not filtered by working directory.
         #[serde(default)]
         pub cwd: Option<AbsolutePath>,

docs/protocol/v2/draft/schema.mdx

@@ -743,6 +743,9 @@ Omitted and `null` are equivalent and mean the first page is requested.
 <ResponseField name="cwd" type={<><span><a href="#absolutepath">AbsolutePath</a></span><span> | null</span></>} >
   Filter sessions by working directory. Must be an absolute path.
 
+Only sessions whose `cwd` is this same directory match; subdirectories and
+`additionalDirectories` don't. Agents MAY normalize paths when comparing.
+
 Omitted and `null` are equivalent and mean sessions are not filtered by working directory.
 
 </ResponseField>

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

@@ -62,7 +62,9 @@ All parameters are optional. A request with an empty `params` object returns the
 
 <ParamField path="cwd" type="string">
   Filter sessions by working directory. Must be an absolute path. Only sessions
-  with a matching `cwd` are returned.
+  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/schema.mdx

@@ -413,6 +413,9 @@ Omitted and `null` are equivalent and mean the first page is requested.
 <ResponseField name="cwd" type={<><span><a href="#absolutepath">AbsolutePath</a></span><span> | null</span></>} >
   Filter sessions by working directory. Must be an absolute path.
 
+Only sessions whose `cwd` is this same directory match; subdirectories and
+`additionalDirectories` don't. Agents MAY normalize paths when comparing.
+
 Omitted and `null` are equivalent and mean sessions are not filtered by working directory.
 
 </ResponseField>

docs/protocol/v2/session-list.mdx

@@ -62,7 +62,9 @@ All parameters are optional. A request with an empty `params` object returns the
 
 <ParamField path="cwd" type="string">
   Filter sessions by working directory. Must be an absolute path. Only sessions
-  with a matching `cwd` are returned.
+  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">

schema/v2/schema.json

@@ -6792,7 +6792,7 @@
       "type": "object",
       "properties": {
         "cwd": {
-          "description": "Filter sessions by working directory. Must be an absolute path.\n\nOmitted and `null` are equivalent and mean sessions are not filtered by working directory.",
+          "description": "Filter sessions by working directory. Must be an absolute path.\n\nOnly sessions whose `cwd` is this same directory match; subdirectories and\n`additionalDirectories` don't. Agents MAY normalize paths when comparing.\n\nOmitted and `null` are equivalent and mean sessions are not filtered by working directory.",
           "anyOf": [
             {
               "$ref": "#/$defs/AbsolutePath"

schema/v2/schema.unstable.json

@@ -8040,7 +8040,7 @@
       "type": "object",
       "properties": {
         "cwd": {
-          "description": "Filter sessions by working directory. Must be an absolute path.\n\nOmitted and `null` are equivalent and mean sessions are not filtered by working directory.",
+          "description": "Filter sessions by working directory. Must be an absolute path.\n\nOnly sessions whose `cwd` is this same directory match; subdirectories and\n`additionalDirectories` don't. Agents MAY normalize paths when comparing.\n\nOmitted and `null` are equivalent and mean sessions are not filtered by working directory.",
           "anyOf": [
             {
               "$ref": "#/$defs/AbsolutePath"