agent-filesystem

agent-filesystem is the host filesystem provider for the agent system.

It exposes admitted, scoped filesystem capabilities. It is not an ambient disk-access backdoor.

Purpose

agent-filesystem owns host filesystem operations for provider/plugin use:

• scoped file reads
• scoped file writes
• directory listing
• metadata/stat inspection
• safe create/update flows
• atomic write/replace helpers
• bounded content reads
• explicit delete/move/copy operations when admitted
• filesystem audit events

Authority boundaries

agent-filesystem is not the action authority.

• agent-core-system owns action admission, approval, policy, audit, execution envelopes, and host-admitted filesystem scopes.
• rpc-plugin-system owns substrate runtime, transport, lifecycle, plugin identity/generation, and supervision.
• agent-keyring owns credentials and secrets; filesystem access must not become secret exfiltration.
• agent-filesystem owns filesystem operation mechanics, scope enforcement, and local path safety.

Filesystem access is not automatically authorized because a process can reach the host disk. All filesystem operations must be scoped and admitted.

Provider diagnostics

Filesystem provider diagnostics are structured, redacted observability facts emitted through the inherited rpc-plugin-system SDK/helper path. They may report provider/plugin generation, capability, operation, correlation IDs, bounded status, coarse error/degraded classes, counts, sizes, and non-authoritative digest facts.

They must not contain raw request paths, normalized backend paths, admitted roots, provider-private paths, file descriptors, path handles, COW/trash/snapshot storage paths, reusable rollback/artifact refs, raw authority_use_ref values, sockets, sessions, credentials, read/write/patch payload bytes, upstream bodies, or reusable handles. Diagnostics do not grant filesystem authority and do not replace agent-core-system admission.

Non-goals

• Do not provide ambient root filesystem access.
• Do not bypass agent-core-system admission.
• Do not silently follow symlinks across scope boundaries.
• Do not treat path strings from models/providers as trusted.
• Do not store credentials here.
• Do not hide destructive operations behind convenience helpers.

First useful implementation slice

1. Define filesystem capability contracts.
2. Define host-admitted filesystem scope model.
3. Define path normalization and symlink policy.
4. Add fake filesystem backend tests.
5. Add local backend only after scope checks are tested.
6. Add rpc-plugin-system plugin wiring after contract stability.