File System API alternatives in v2?

[appleton]

Sorry for the duplication, I posted this as a reply on https://github.com/orgs/agentclientprotocol/discussions/1379 but I think it's easy to miss there and warrants a fuller discussion.

---

Hey there, I'm working on a family of GUI clients for open source release (VSCode, Visual Studio, Desktop app) all of which share the same file versioning underpinnings and using the v1 file system APIs to capture agent edits.

If these go away in v2 I'll need to find an alternative, would you be willing to share the options you're considering for Zed?

Off the top of my head I've got three ideas but I'm not totally sure about any of them:

1. Something based around file watchers or LSP document sync but I can't see how those would differentiate between a manual user edit and an agent edit.
2. Observe diff contents as events are published to the client but I can quickly think of ways that might break down too - for a start it relies on the agent actually publishing diffs.
3. Doing some kind of syscall interceptor wrapper around agent servers to peek at the files being edited by the process. This would have the advantage of also capturing edits performed via a shell command rather than a direct edit tool.

I'd love to hear your thoughts if you're open to sharing?

[starkmarkus]

This is a good question, and I think it is worth separating two use cases that the v1 filesystem API currently mixes together:

1. giving the agent access to client/editor state, including unsaved buffers;
2. giving the client a reliable attribution boundary for “this edit was made by the agent”.

For your versioning use case, the second part seems like the critical one.

I would be hesitant to rely only on file watchers or LSP document sync for this. They can tell you that a file changed, but they usually cannot tell you why it changed. A user typing, an agent edit tool, a formatter, a shell command, and a build step can all look similar from the outside.

Diff events are better for UI/review, but they also feel insufficient as the only source of truth. They depend on the agent publishing the right diff information, and they may miss edits made indirectly through shell commands or other tools.

A syscall/file-interceptor wrapper is probably the most complete from an observation perspective, because it can see writes made by the agent process and by subprocesses. But it is also the most platform-specific and probably the hardest to make portable across VS Code, Visual Studio, and a desktop app. It may also be awkward for remote agents.

My instinct would be that ACP v2 should ideally expose a protocol-level edit attribution mechanism, even if it does not keep the v1 client filesystem API. For example, something like:

• session-scoped “agent is about to edit / finished editing” boundaries;
• explicit file-change notifications with origin: agent | user | external;
• a stable operation/edit id that can connect tool calls, diffs, and resulting file changes;
• optional before/after content hashes so clients can verify what actually changed;
• a way to represent edits caused indirectly by shell/tool execution.

That would let clients implement versioning and review without requiring the agent to perform all writes through a client filesystem API.

So from the three options you listed, I would probably rank them like this:

1. Best long-term: protocol-level edit/file-change attribution in ACP v2.
2. Best practical fallback: file watcher + snapshot/diffing around agent tool-call boundaries.
3. Most complete but heavy fallback: process/syscall interception for local agents.

For my own client, I would probably avoid building the core model around “the agent must publish diffs correctly”. I would treat published diffs as presentation hints, and use filesystem snapshots/change events as the verification layer. But without a protocol-level attribution boundary, it is hard to make that robust.