fs.write

The fs.write tool writes or appends content to a file within the agent's capability-scoped paths.

Capabilities Required

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

Input Schema

{
  "type": "object",
  "required": ["path", "content"],
  "properties": {
    "path": {
      "type": "string",
      "description": "Absolute path to write."
    },
    "content": {
      "type": "string",
      "description": "Content to write (UTF-8)."
    },
    "append": {
      "type": "boolean",
      "description": "If true, append to existing file. Default: false (overwrite)."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "written": { "type": "integer", "description": "Bytes written." }
  }
}

Examples

#![allow(unused)]
fn main() {
// Write a new file
let result = agent.invoke_tool("fs.write", json!({
    "path": "/workspace/report.md",
    "content": "# Report\n\nHello world.\n"
})).await?;
println!("Wrote {} bytes", result["written"]);

// Append to existing file
agent.invoke_tool("fs.write", json!({
    "path": "/workspace/log.txt",
    "content": "New log entry\n",
    "append": true
})).await?;
}

Workspace Isolation

All writes go to the agent's overlayfs upper layer. The base filesystem is never modified. Changes are visible to the agent immediately but not to other agents. Use ash workspace commit to promote changes permanently.

Creating Directories

fs.write creates parent directories automatically if they don't exist, provided the path is within the agent's write scope.

Capability Declaration

spec:
  capabilities:
    - tool.invoke:fs.write
    - fs.write:/workspace/**          # write anything in /workspace/
    - fs.write:/tmp/output.txt        # write exactly this file

Cost

Estimated cost: 0.2

Error Cases