Workspace State

Pain Signals — You Need This Pattern When:

• Agent edits a file based on a stale view; the file changed since the read and the edit clobbers external work
• cd foo in one bash call has no effect on the next — agent gets confused about cwd
• Edit tool replaces text that no longer exists in the file (hallucinated stale content)
• Two parallel tool calls both edit the same file; one wins silently
• User edits a file in their editor while the agent is mid-task; no one notices the conflict
• Agent re-reads the same file three times because it cannot remember what it has seen

The workspace is shared mutable state. The agent, the user, and any background processes all touch it. Without tracking, races and stale views are routine.

Core Principle

The harness maintains a shadow map of workspace state — what has been read, when, with what content hash. Tool calls consult and update this map. Edits assert preconditions; reads update the map; external changes are detectable.