fix(unstable): Update additionalDirectories guidance (#1227)

In the implementation phase it has become clear most agents treat this
as optional data in their persistence, and it is ok to change on
resume/load. Given this, loosening the requirements of the RFD.

Remove additional-root filter from session list as well, since it is
best-effort anyway, and probably more of a footgun than not.

Author: benbrandt

docs/protocol/draft/file-system.mdx

@@ -13,7 +13,7 @@ authorize those paths against the session's effective root set.
 - by default, the effective root set is just `cwd`
 - if the unstable `sessionCapabilities.additionalDirectories` capability is in use, the effective root set becomes `[cwd, ...additionalDirectories]`
 - `cwd` remains the base for relative paths; additional roots only expand filesystem scope
-- when a Client discovers a session through `session/list`, it SHOULD treat `cwd` plus `SessionInfo.additionalDirectories` as the authoritative current root set until a later lifecycle request changes it
+- when a Client discovers a session through `session/list`, it SHOULD use `SessionInfo.additionalDirectories` together with `cwd` as the current root set when the field is present; if omitted, the Agent is not reporting additional-root state, and any later `session/load` or `session/resume` request establishes the root set explicitly
 
 Because ACP filesystem methods are client-mediated, the Client remains
 responsible for enforcing those root boundaries.

docs/protocol/draft/schema-v2.mdx

@@ -1164,17 +1164,6 @@ these keys.
 
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
 
-</ResponseField>
-<ResponseField name="additionalDirectories" type={<><span>"string"</span><span>[]</span></>} >
-  **UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
-Filter sessions by the exact ordered additional workspace roots. Each path must be absolute.
-
-This filter applies only when the field is present and non-empty. When
-omitted or empty, no additional-root filter is applied.
-
 </ResponseField>
 <ResponseField name="cursor" type={"string | null"} >
   Opaque cursor token from a previous response's nextCursor field for cursor-based pagination
@@ -1251,7 +1240,8 @@ Additional workspace roots to activate for this session. Each path must be absol
 
 When omitted or empty, no additional roots are activated. When non-empty,
 this is the complete resulting additional-root list for the loaded
-session.
+session. It may differ from any previously used or reported list as long as
+the request `cwd` matches the session's `cwd`.
 
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
@@ -1544,7 +1534,8 @@ Additional workspace roots to activate for this session. Each path must be absol
 
 When omitted or empty, no additional roots are activated. When non-empty,
 this is the complete resulting additional-root list for the resumed
-session.
+session. It may differ from any previously used or reported list as long as
+the request `cwd` matches the session's `cwd`.
 
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
@@ -6530,8 +6521,10 @@ This capability is not part of the spec yet, and may be removed or changed at an
 
 Capabilities for additional session directories support.
 
-By supplying `\{\}` it means that the agent supports the `additionalDirectories` field on
-supported session lifecycle requests and `session/list`.
+By supplying `\{\}` it means that the agent supports the `additionalDirectories`
+field on supported session lifecycle requests. Agents that also support
+`session/list` may return `SessionInfo.additionalDirectories` when they track
+that state.
 
 **Type:** Object
 
@@ -6575,7 +6568,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 
 This capability is not part of the spec yet, and may be removed or changed at any point.
 
-Whether the agent supports `additionalDirectories` on supported session lifecycle requests and `session/list`.
+Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
+
+Agents that also support `session/list` may return
+`SessionInfo.additionalDirectories` when they track that state.
 
 </ResponseField>
 <ResponseField name="close" type={<><span><a href="#sessionclosecapabilities">SessionCloseCapabilities</a></span><span> | null</span></>} >
@@ -6933,9 +6929,11 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 
 This capability is not part of the spec yet, and may be removed or changed at any point.
 
-Authoritative ordered additional workspace roots for this session. Each path must be absolute.
+Additional workspace roots for this session, if the Agent reports them. Each path must be absolute.
 
-When omitted or empty, there are no additional roots for the session.
+Agents may omit this field when they do not track or surface additional-root
+state. When present, this is the complete additional-root list known to
+the Agent for the session.
 
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>

docs/protocol/draft/schema.mdx

@@ -1164,17 +1164,6 @@ these keys.
 
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
 
-</ResponseField>
-<ResponseField name="additionalDirectories" type={<><span>"string"</span><span>[]</span></>} >
-  **UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
-Filter sessions by the exact ordered additional workspace roots. Each path must be absolute.
-
-This filter applies only when the field is present and non-empty. When
-omitted or empty, no additional-root filter is applied.
-
 </ResponseField>
 <ResponseField name="cursor" type={"string | null"} >
   Opaque cursor token from a previous response's nextCursor field for cursor-based pagination
@@ -1251,7 +1240,8 @@ Additional workspace roots to activate for this session. Each path must be absol
 
 When omitted or empty, no additional roots are activated. When non-empty,
 this is the complete resulting additional-root list for the loaded
-session.
+session. It may differ from any previously used or reported list as long as
+the request `cwd` matches the session's `cwd`.
 
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
@@ -1544,7 +1534,8 @@ Additional workspace roots to activate for this session. Each path must be absol
 
 When omitted or empty, no additional roots are activated. When non-empty,
 this is the complete resulting additional-root list for the resumed
-session.
+session. It may differ from any previously used or reported list as long as
+the request `cwd` matches the session's `cwd`.
 
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
@@ -6530,8 +6521,10 @@ This capability is not part of the spec yet, and may be removed or changed at an
 
 Capabilities for additional session directories support.
 
-By supplying `\{\}` it means that the agent supports the `additionalDirectories` field on
-supported session lifecycle requests and `session/list`.
+By supplying `\{\}` it means that the agent supports the `additionalDirectories`
+field on supported session lifecycle requests. Agents that also support
+`session/list` may return `SessionInfo.additionalDirectories` when they track
+that state.
 
 **Type:** Object
 
@@ -6575,7 +6568,10 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 
 This capability is not part of the spec yet, and may be removed or changed at any point.
 
-Whether the agent supports `additionalDirectories` on supported session lifecycle requests and `session/list`.
+Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
+
+Agents that also support `session/list` may return
+`SessionInfo.additionalDirectories` when they track that state.
 
 </ResponseField>
 <ResponseField name="close" type={<><span><a href="#sessionclosecapabilities">SessionCloseCapabilities</a></span><span> | null</span></>} >
@@ -6933,9 +6929,11 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 
 This capability is not part of the spec yet, and may be removed or changed at any point.
 
-Authoritative ordered additional workspace roots for this session. Each path must be absolute.
+Additional workspace roots for this session, if the Agent reports them. Each path must be absolute.
 
-When omitted or empty, there are no additional roots for the session.
+Agents may omit this field when they do not track or surface additional-root
+state. When present, this is the complete additional-root list known to
+the Agent for the session.
 
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>

docs/protocol/draft/session-list.mdx

@@ -55,10 +55,8 @@ If `sessionCapabilities.list` is not present, the Agent does not support listing
 
 <Note>
   If the Agent also advertises the unstable
-  `sessionCapabilities.additionalDirectories` capability, `session/list`
-  supports filtering by `additionalDirectories`, and any returned
-  `SessionInfo.additionalDirectories` value is the authoritative additional-root
-  list for that session.
+  `sessionCapabilities.additionalDirectories` capability, returned `SessionInfo`
+  objects may include `additionalDirectories` when the Agent tracks that state.
 </Note>
 
 <Note>
@@ -90,13 +88,6 @@ All parameters are optional. A request with an empty `params` object returns the
   with a matching `cwd` are returned.
 </ParamField>
 
-<ParamField path="additionalDirectories" type="string[]">
-  If the Agent advertises `sessionCapabilities.additionalDirectories`, filter
-  sessions by the exact ordered additional-root list when this field is present
-  and non-empty. Omitting the field or providing an empty array means no
-  additional-root filter is applied.
-</ParamField>
-
 <ParamField path="cursor" type="string">
   Opaque cursor token from a previous response's `nextCursor` field for
   cursor-based pagination. See [Pagination](#pagination).
@@ -148,10 +139,12 @@ The Agent **MUST** respond with a list of sessions and optional pagination metad
       Working directory for the session. Always an absolute path.
     </ResponseField>
     <ResponseField name="additionalDirectories" type="string[]">
-      If the Agent advertises `sessionCapabilities.additionalDirectories`, this
-      is the authoritative ordered additional-root list for the session when
-      present. Omitting the field or returning an empty array means there are no
-      additional roots.
+      If the Agent advertises `sessionCapabilities.additionalDirectories`, it
+      MAY include this field when it tracks additional-root state for the
+      session. When present, this is the complete ordered additional-root list
+      known to the Agent for that session. Omitting the field means the Agent is
+      not reporting additional-root state; an explicit empty array means the
+      Agent is reporting no additional roots.
     </ResponseField>
 
     <ResponseField name="title" type="string">

docs/protocol/draft/session-setup.mdx

@@ -367,7 +367,7 @@ When present, `additionalDirectories` has the following behavior:
 - `cwd` remains the primary working directory and the base for relative paths
 - each `additionalDirectories` entry **MUST** be an absolute path
 - omitting the field or providing an empty array activates no additional roots for the resulting session
-- on `session/load` and `session/resume`, Clients must send the full intended additional-root list again because omitting the field or providing an empty array does not restore stored roots implicitly
+- on `session/load` and `session/resume`, Clients must send the full intended additional-root list again; that list may differ from any previous or reported list as long as the request `cwd` matches the session's `cwd`, and omitting the field or providing an empty array does not restore stored roots implicitly
 
 ## Session ID