File System method docs

Author: agu-z

docs/docs.json

@@ -44,7 +44,10 @@
     "groups": [
       {
         "group": "Overview",
-        "pages": ["overview/introduction", "overview/architecture"]
+        "pages": [
+          "overview/introduction",
+          "overview/architecture"
+        ]
       },
       {
         "group": "Protocol",
@@ -55,17 +58,24 @@
           "protocol/prompt-turn",
           "protocol/content",
           "protocol/tool-calls",
+          "protocol/file-system",
           "protocol/agent-plan",
           "protocol/schema"
         ]
       },
       {
         "group": "Libraries",
-        "pages": ["libraries/typescript", "libraries/rust"]
+        "pages": [
+          "libraries/typescript",
+          "libraries/rust"
+        ]
       },
       {
         "group": "Community",
-        "pages": ["community/contributing", "community/versioning"]
+        "pages": [
+          "community/contributing",
+          "community/versioning"
+        ]
       }
     ]
   },
@@ -85,6 +95,9 @@
     }
   },
   "contextual": {
-    "options": ["copy", "view"]
+    "options": [
+      "copy",
+      "view"
+    ]
   }
 }

docs/protocol/file-system.mdx

@@ -0,0 +1,114 @@
+---
+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.
+
+## Checking Support
+
+Before attempting to use filesystem methods, Agents **MUST** verify that the Client supports these capabilities by checking the [Client Capabilities](./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": "src/main.py",
+    "line": 10,
+    "limit": 50
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The [Session ID](./session-setup#session-id) for this request
+</ParamField>
+
+<ParamField path="path" type="string" required>
+  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": "config.json",
+    "content": "{\n  \"debug\": true,\n  \"version\": \"1.0.0\"\n}"
+  }
+}
+```
+
+<ParamField path="sessionId" type="SessionId" required>
+  The [Session ID](./session-setup#session-id) for this request
+</ParamField>
+
+<ParamField path="path" type="string" required>
+  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/tool-calls.mdx

@@ -7,7 +7,7 @@ Tool calls represent actions that language models request Agents to perform duri
 
 Agents report tool calls through [`session/update`](./prompt-turn#3-agent-reports-output) notifications, allowing Clients to display real-time progress and results to users.
 
-While Agents handle the actual execution, they may leverage Client capabilities like permission requests or file system access to provide a richer, more integrated experience.
+While Agents handle the actual execution, they may leverage Client capabilities like [permission requests](#requesting-permission) or [file system access](./file-system) to provide a richer, more integrated experience.
 
 ## Creating