Skip to content

symmetric-fs-capabilities.mdx

Latest commit

 

History

History
113 lines (83 loc) · 6.48 KB

symmetric-fs-capabilities.mdx

File metadata and controls

113 lines (83 loc) · 6.48 KB
title
Symmetric filesystem capabilities

Elevator pitch

What are you proposing to change?

Require that writeTextFile: true implies readTextFile: true in client capabilities. No client uses them asymmetrically, and the split creates confusion for agent developers without serving a use case.

Status quo

How do things work today and what problems does this cause? Why would we change things?

The file system spec defines readTextFile and writeTextFile as independent booleans in clientCapabilities.fs, both defaulting to false. This creates four possible combinations, but only two occur in practice across all known open-source clients:

Client readTextFile writeTextFile
acp.nvim true true
ACP UI true true
agent-shell true true
agentic.nvim true true
AionUi true true
avante.nvim true true
Chrome ACP true true
codecompanion.nvim true true
deepchat true true
marimo true true
Mitto true true
UnityAgentClient true true
vscode-acp true true
Zed true true
agent-client-kernel false false
agent-review false false
Agent Studio false false
cmd false false
duckdb-acp false false
forge-core false false
mcpc false false
obsidian-agent-client false false
tidewave_app false false

No client sends readTextFile: true, writeTextFile: false or vice versa. The unused combinations create a buffer consistency problem: if a client advertises write but not read, agents read stale on-disk content via local tools and then write through ACP to the editor buffer, overwriting unsaved state based on stale input (goose discussion).

The four-way matrix adds complexity for agent developers who must handle combinations that never occur in practice.

What we propose to do about it

What are you proposing to improve the situation?

Add a normative statement to the file system documentation:

Agents MUST treat writeTextFile: true as implying readTextFile: true. Clients SHOULD set both capabilities symmetrically.

This is a no-op for existing implementations since no client sends an asymmetric combination.

Shiny future

How will things will play out once this feature exists?

Agent developers handle two cases (fs supported or not) instead of four. The buffer consistency question is eliminated by definition.

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

Why not collapse into a single fs boolean?

That matches what every client already does, but it is a breaking schema change. Write-implies-read is additive: existing clients already comply since none send an asymmetric combination.

Why not just document it as a recommendation?

Recommendations do not remove the confusion. Agent developers still need to consider whether asymmetric clients exist. A MUST requirement removes the question.

What alternative approaches did you consider, and why did you settle on this one?

  1. Single fs boolean - Simpler but breaking. Requires schema migration and SDK updates.
  2. SHOULD instead of MUST - Does not solve the problem. Agent developers still handle the asymmetric case defensively.
  3. Do nothing - Leaves unnecessary complexity for every new agent implementation.

Write-implies-read codifies existing practice with zero migration cost.

Revision history

  • 2026-03-06: Initial draft