Writing pitfalls: files, parallel edits and lost deliverables
A success report written by a sub-agent proves nothing about the real state of files, since it starts in an isolated context with no access to what the main agent has already read or written, and the only reliable proof remains a diff checked afterwards, not the text of the report.
A sub-agent starts with a context that is isolated and fresh on every call, except for a fork, which instead inherits the whole conversation in progress. It sees neither the main conversation's history, nor the skills already invoked, nor the files the main agent has already read. This isolation does not stop it from checking the disk itself: it has the same reading and execution tools as the main conversation, and can very well run a git diff or reread a file to check its own work. What is missing is an outside eye: a success report remains text produced by the same agent that has just acted, never an independent check, and nothing guarantees it matches a real write to disk until someone else has checked it.
The text report is not the proof
Documented good practice is to ask for a verifiable diff rather than trusting the text of the report. A diff shows the lines actually changed in a real file, a success report is only a sentence generated by the same agent claiming to have succeeded.
mkdir -p /tmp/demo-diff
echo "version initiale" > /tmp/demo-diff/avant.txt
echo "version modifiee" > /tmp/demo-diff/apres.txt
diff /tmp/demo-diff/avant.txt /tmp/demo-diff/apres.txt
# result: the changed line appears, the proof is in the diff, not in a sentenceA text report claiming that apres.txt has been updated adds nothing beyond this diff, and without it, nothing distinguishes a real write from a made up sentence. A one line script containing backticks runs into a related trap: the shell running it can interpret them before the command reaches its target, and what shows up afterwards looks like a success even though the command actually run was truncated. Rereading the command exactly as the shell received it, not just as it was typed, answers the same need for proof as the diff.
Two writes to the same file are never independent
Two edits sent together on the same file, whether by two sub-agents or by two calls of the edit tool in the same turn, apply one after the other on the content the tool finds at the moment it acts, never on two separate copies merged afterwards. The second edit can therefore fail to find the text it was looking for, because the first has already changed it. Sending the two edits in sequence, rereading the file in between, reduces this risk and makes each step verifiable on its own.
The same principle of verifiable proof applies to a long deliverable: content spanning several paragraphs that only exists in the displayed reply disappears with it as soon as the conversation continues. Writing it to a real file before displaying it, as with structured output in headless mode, guarantees it stays accessible independently of the conversation thread, exactly as a diff stays readable independently of the report that comes with it.
Success report against verifiable proof
| Proof that a write actually happened | What produces it | What it shows | How to check it |
|---|---|---|---|
| Text success report | Generated by the same agent claiming to have succeeded | A sentence claiming the file has been updated | Nothing to check, the sentence takes itself as proof |
| Diff of the real file | Produced by a command that reads the file's content on disk | The exact lines that changed, or no line if nothing changed | Rereads independently of what the agent claims |
A developer asks a sub-agent to add a configuration line to a file, receives a reply announcing that the change is done, then opens the file himself on disk and reads its content.
Write, in one sentence, what this situation establishes, and in one sentence what it does not establish.
What this establishes: This situation establishes that the developer took the step of rereading the file on disk rather than stopping at the sub-agent's reply.
What this does not establish: It does not establish whether the expected configuration line is actually present in the file, since the content read is not described.
The three most common miscalibrations
- Too broad This situation establishes that the change requested from the sub-agent has indeed been applied in the file.
- Too narrow This situation establishes nothing at all, since only one file was checked on a single machine.
- Off target This situation shows that the file in question already contained several configuration lines before the instruction was even sent.
- A sub-agent starts with an isolated context, with no access to the main conversation's history, to the skills already invoked, or to the files already read by the main agent.
- A sub-agent can read the disk just like the main conversation, but its report remains text produced by the same agent that acted, never an independent check, hence the risk that it does not match any real write.
- A diff of the lines actually changed is verifiable proof, a text report claiming success is not.
- Two edits sent together on the same file apply one after the other on the content found at the moment of the action, never on two copies merged afterwards.
- A long deliverable written only in the displayed reply disappears with it, writing it to a real file makes it accessible independently of the conversation thread.
Open a file you recently asked a sub-agent or a tool to write, run a diff or a direct reread of its content on disk, and confirm that what you find there exactly matches the success report you received.
Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.
- Claude Code, sub-agents, isolated context and freshness consultée le 2026-09-02