Should edit guidance explicitly prohibit parallel edits to the same file?

[HandleCoding]

Summary

Should the model-facing edit guidance explicitly state that edits targeting the same file must be dispatched sequentially, while edits targeting different files may run in parallel?

The filesystem backend already behaves safely: mutations are locked per targetKey, and guarded edits use the last observed file version. The native tool scheduler also keeps mutation tools exclusive. However, an orchestration layer or parallel-call wrapper can still fan out several edit calls before the first call records its new observed version. Those calls share one stale version basis; after one mutation advances the file version, the remaining calls can fail with FS_STALE_VERSION.

This is not a request to weaken the stale guard. The guard is correctly preventing lost updates. The question is whether the safe-use constraint should also be made explicit to the model.

Current model-visible guidance

The current tool:edit prompt on master explains literal matching, replace_all, and the read-before-edit requirement, but does not mention same-file parallelism:

Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-observation-policy requires it), unless you just created or edited it in this session.

The tool description is similarly concise:

Edit an existing UTF-8 text file by replacing literal text.

Reproduction

Using a generic file such as /tmp/edit-probe.txt:

1. Read the file once.
2. Through an orchestration layer that can fan out tool calls concurrently, dispatch multiple edit calls targeting different unique regions of that same file.
3. The calls can obtain the same observed version before entering the backend's per-target mutation lock.
4. One edit advances the version; later guarded calls reject with FS_STALE_VERSION.
5. Re-read and run the edits sequentially; they succeed.

This is consistent with the current implementation:

• fs-observation-policy supplies the session's observed version as the edit intent.
• fs-local serializes mutations per targetKey and rejects an old expected version.
• tool-fs records the new version after a successful edit.
• The native scheduler keeps mutation tools exclusive, but external or higher-level fan-out surfaces may not preserve that scheduling contract.

Proposed minimal change

Add one sentence to the tool:edit system-prompt guidance, for example:

Never invoke multiple edit calls targeting the same file in parallel. Execute edits to the same file sequentially; edits to different files may run in parallel. If an edit fails with FS_STALE_VERSION, re-read the file and retry.

Optionally add a shorter version to the tool description so the constraint remains visible wherever tool-owned prompt sections are omitted.

Why document it if native scheduling is already exclusive?

• Models can use orchestration tools or wrappers whose fan-out semantics are separate from the native scheduler.
• “Parallelize independent work” is a common agent heuristic; edits to different regions may look independent even though their freshness basis is file-wide.
• The failure is expected but avoidable, and the recovery costs another read/tool round.
• The wording preserves useful parallelism across different files instead of discouraging all parallel edits.

Alternatives

1. Keep the current behavior and rely entirely on the native exclusive scheduler.
2. Have parallel orchestration surfaces detect identical canonical targets and serialize them automatically.
3. Reject same-target fan-out before dispatch with a more specific diagnostic.

I would avoid automatic blind retries after FS_STALE_VERSION: after another edit changes the file, the original literal replacement may no longer represent the same intent. Re-read plus model reconsideration is safer.

Questions

1. Is same-file serialization intended to be part of the model-facing edit contract, or only an internal scheduler property?
2. Should tool-owned guidance mention constraints introduced by common higher-level orchestration surfaces?
3. Would maintainers prefer prompt guidance only, or target-aware serialization in orchestration layers as well?