---
name: filesystem
description: "Account-scoped file access. Read, write, edit, list, glob, and grep files under the session's own account directory; the house admin may reach any sub-account's files by naming targetAccountId, gated fail-closed and confined to that account's directory."
tools:
  - name: file-read
    publicAllowlist: false
    adminAllowlist: true
    riskClass: read
  - name: file-write
    publicAllowlist: false
    adminAllowlist: true
    riskClass: write_local
  - name: file-edit
    publicAllowlist: false
    adminAllowlist: true
    riskClass: write_local
  - name: file-list
    publicAllowlist: false
    adminAllowlist: true
    riskClass: read
  - name: file-glob
    publicAllowlist: false
    adminAllowlist: true
    riskClass: read
  - name: file-grep
    publicAllowlist: false
    adminAllowlist: true
    riskClass: read
metadata: {"platform":{"always":false,"embed":[],"pluginKey":"filesystem"}}
mcp:
  command: node
  args:
    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
    - ${PLATFORM_ROOT}/plugins/filesystem/mcp/dist/index.js
  env:
    MCP_SPAWN_TEE_NAME: filesystem
    LOG_DIR: ${LOG_DIR}
    PLATFORM_ROOT: ${PLATFORM_ROOT}
    ACCOUNT_ID: ${ACCOUNT_ID}
    SESSION_ID: ${SESSION_ID}
    AGENT_SLUG: ${AGENT_SLUG}
mcp-manifest: auto
---

# Filesystem

Direct access to the account working directory (`data/accounts/<id>/`) — `SOUL.md`, generated documents, screenshots, and arbitrary files. These tools complement the native Read/Write/Edit tools, which are locked to your own account; only these tools can reach another account's files, and only for the house admin.

## Own account

Omit `targetAccountId`. Every tool takes a `path` relative to your account directory. `file-read`, `file-write`, `file-edit`, `file-list`, `file-glob`, and `file-grep` behave like their native counterparts but always resolve inside your account root.

## Cross-account (house admin only)

Pass `targetAccountId` to operate on a sub-account's directory. This is honoured only for a house-scoped admin session. A sub-account, specialist, or public session that passes `targetAccountId` is refused with `cross-account-denied`; an account id that is not provisioned on disk is refused with `cross-account-target-not-provisioned`. The validity check re-scans the accounts dir on a miss, so a sub-account created at runtime this session resolves without a service restart (a stale boot-time cache no longer masks it). Use this to inspect or repair a client account's files from the house session without switching accounts.

## Boundaries

Every path is confined to the resolved account directory. A path that escapes it — `../`, an absolute path outside the account root, or a symlink pointing out — is rejected before any filesystem operation. Reads and greps skip files over 5 MB; grep skips binary files.

## Tools

- `file-read` — Read a UTF-8 file. Args: `path`, optional `targetAccountId`.
- `file-write` — Create or overwrite a UTF-8 file, making parent directories. Args: `path`, `content`, optional `targetAccountId`.
- `file-edit` — Replace one unique occurrence of `oldString` with `newString`. Fails if `oldString` is missing or not unique. Args: `path`, `oldString`, `newString`, optional `targetAccountId`.
- `file-list` — List a directory's entries with their type. Args: optional `path` (defaults to the account root), optional `targetAccountId`.
- `file-glob` — List files matching a glob (`**`, `*`, `?`). Args: `pattern`, optional `targetAccountId`.
- `file-grep` — Search file contents for a JavaScript regular expression, returning `file:line:preview`. Args: `pattern`, optional `path`, optional `targetAccountId`.