feat: additional directories

Cargo.toml

@@ -19,6 +19,7 @@ unstable = [
     "unstable_cancel_request",
     "unstable_elicitation",
     "unstable_logout",
+    "unstable_session_additional_directories",
     "unstable_session_fork",
     "unstable_session_model",
     "unstable_session_resume",
@@ -31,6 +32,7 @@ unstable_auth_methods = []
 unstable_cancel_request = []
 unstable_elicitation = []
 unstable_logout = []
+unstable_session_additional_directories = []
 unstable_session_fork = []
 unstable_session_model = []
 unstable_session_resume = []

docs/docs.json

@@ -82,6 +82,9 @@
                 "group": "Draft: In Progress and May Change",
                 "hidden": true,
                 "pages": [
+                  "protocol/draft/session-setup",
+                  "protocol/draft/session-list",
+                  "protocol/draft/file-system",
                   "protocol/draft/cancellation",
                   "protocol/draft/schema"
                 ]

docs/protocol/draft/file-system.mdx

@@ -0,0 +1,131 @@
+---
+title: "File System"
+description: "Client filesystem access methods"
+---
+
+The filesystem methods allow Agents to read and write text files within the Client's environment. These methods enable Agents to access unsaved editor state and allow Clients to track file modifications made during agent execution.
+
+## Session Root Scope
+
+Filesystem methods always operate on absolute paths, but the Client **MUST**
+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
+
+Because ACP filesystem methods are client-mediated, the Client remains
+responsible for enforcing those root boundaries.
+
+## Checking Support
+
+Before attempting to use filesystem methods, Agents **MUST** verify that the Client supports these capabilities by checking the [Client Capabilities](/protocol/initialization#client-capabilities) field in the `initialize` response:
+
+```json highlight={8,9}
+{
+  "jsonrpc": "2.0",
+  "id": 0,
+  "result": {
+    "protocolVersion": 1,
+    "clientCapabilities": {
+      "fs": {
+        "readTextFile": true,
+        "writeTextFile": true
+      }
+    }
+  }
+}
+```
+
+If `readTextFile` or `writeTextFile` is `false` or not present, the Agent **MUST NOT** attempt to call the corresponding filesystem method.
+
+## Reading Files
+
+The `fs/read_text_file` method allows Agents to read text file contents from the Client's filesystem, including unsaved changes in the editor.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "fs/read_text_file",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "path": "/home/user/project/src/main.py",
+    "line": 10,
+    "limit": 50
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The [Session ID](/protocol/session-setup#session-id) for this request. The
+  session determines which filesystem roots are in scope for the path.
+</ParamField>
+
+<ParamField path="path" type="string" required>
+  Absolute path to the file to read
+</ParamField>
+
+<ParamField path="line" type="number">
+  Optional line number to start reading from (1-based)
+</ParamField>
+
+<ParamField path="limit" type="number">
+  Optional maximum number of lines to read
+</ParamField>
+
+The Client responds with the file contents:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": "def hello_world():\n    print('Hello, world!')\n"
+  }
+}
+```
+
+## Writing Files
+
+The `fs/write_text_file` method allows Agents to write or update text files in the Client's filesystem.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "method": "fs/write_text_file",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "path": "/home/user/project/config.json",
+    "content": "{\n  \"debug\": true,\n  \"version\": \"1.0.0\"\n}"
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The [Session ID](/protocol/session-setup#session-id) for this request. The
+  session determines which filesystem roots are in scope for the path.
+</ParamField>
+
+<ParamField path="path" type="string" required>
+Absolute path to the file to write.
+
+The Client **MUST** create the file if it doesn't exist.
+
+</ParamField>
+
+<ParamField path="content" type="string" required>
+  The text content to write to the file
+</ParamField>
+
+The Client responds with an empty result on success:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "result": null
+}
+```

docs/protocol/draft/schema.mdx

@@ -355,6 +355,18 @@ 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.
+
+Additional workspace roots to activate for this session. Each path must be absolute.
+
+When omitted or empty, no additional roots are activated. When non-empty,
+this is the complete resulting additional-root list for the forked
+session.
+
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
   The working directory for this session.
@@ -433,6 +445,17 @@ 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
@@ -499,6 +522,18 @@ 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.
+
+Additional workspace roots to activate for this session. Each path must be absolute.
+
+When omitted or empty, no additional roots are activated. When non-empty,
+this is the complete resulting additional-root list for the loaded
+session.
+
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
   The working directory for this session.
@@ -578,6 +613,18 @@ 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.
+
+Additional workspace roots for this session. Each path must be absolute.
+
+These expand the session's filesystem scope without changing `cwd`, which
+remains the base for relative paths. When omitted or empty, no
+additional roots are activated for the new session.
+
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
   The working directory for this session. Must be an absolute path.
@@ -776,6 +823,18 @@ 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.
+
+Additional workspace roots to activate for this session. Each path must be absolute.
+
+When omitted or empty, no additional roots are activated. When non-empty,
+this is the complete resulting additional-root list for the resumed
+session.
+
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
   The working directory for this session.
@@ -4165,6 +4224,30 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
   The ID of the option the user selected.
 </ResponseField>
 
+## <span class="font-mono">SessionAdditionalDirectoriesCapabilities</span>
+
+**UNSTABLE**
+
+This capability is not part of the spec yet, and may be removed or changed at any point.
+
+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`.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="_meta" type={"object | null"} >
+  The _meta property is reserved by ACP to allow clients and agents to attach additional
+metadata to their interactions. Implementations MUST NOT make assumptions about values at
+these keys.
+
+See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
+
+</ResponseField>
+
 ## <span class="font-mono">SessionCapabilities</span>
 
 Session capabilities supported by the agent.
@@ -4188,6 +4271,14 @@ these keys.
 
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
 
+</ResponseField>
+<ResponseField name="additionalDirectories" type={<><span><a href="#sessionadditionaldirectoriescapabilities">SessionAdditionalDirectoriesCapabilities</a></span><span> | null</span></>} >
+  **UNSTABLE**
+
+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`.
+
 </ResponseField>
 <ResponseField name="close" type={<><span><a href="#sessionclosecapabilities">SessionCloseCapabilities</a></span><span> | null</span></>} >
   **UNSTABLE**
@@ -4493,6 +4584,16 @@ 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.
+
+Authoritative ordered additional workspace roots for this session. Each path must be absolute.
+
+When omitted or empty, there are no additional roots for the session.
+
 </ResponseField>
 <ResponseField name="cwd" type={"string"} required>
   The working directory for this session. Must be an absolute path.