fs.read

The fs.read tool reads the contents of a file within the agent's capability-scoped paths.

Capabilities Required

tool.invoke:fs.read
fs.read:<path-glob>

Both capabilities are required. tool.invoke:fs.read grants access to the tool; fs.read:<path> grants access to specific paths.

Input Schema

{
  "type": "object",
  "required": ["path"],
  "properties": {
    "path": {
      "type": "string",
      "description": "Absolute path to the file to read."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "content": { "type": "string",  "description": "File contents (UTF-8)." },
    "size":    { "type": "integer", "description": "File size in bytes." },
    "mime":    { "type": "string",  "description": "Detected MIME type." }
  }
}

Examples

#![allow(unused)]
fn main() {
let result = agent.invoke_tool("fs.read", json!({
    "path": "/workspace/report.md"
})).await?;

println!("{}", result["content"]);
println!("Size: {} bytes", result["size"]);
}

ash tools invoke <agent-id> fs.read '{"path": "/workspace/report.md"}'

Path Scoping

The path is validated against the agent's fs.read:<glob> capabilities. If the path does not match any declared scope, the call fails with access denied.

Examples:

spec:
  capabilities:
    - tool.invoke:fs.read
    - fs.read:/workspace/**           # read anything in /workspace/
    - fs.read:/etc/config.json        # read exactly this file

Workspace Isolation

Within the agent's workspace (overlay filesystem), reads see the agent's merged view (upper layer + base layer). The agent cannot read outside its workspace unless explicitly granted.

Cost

Estimated cost: 0.1

Error Cases