fix(tools): enforce read-before-write guard for write_file

[nsalvacao]

TLDR

Prevents write_file from overwriting existing files with hallucinated/truncated content by adding a 3-layer defense: system prompt instruction, tool description warning, and a runtime content-loss guard that blocks writes when proposed content is significantly shorter than the original.

Screenshots / Video Demo

Before (the problem): The agent calls write_file on an existing 200-line file without reading it first, replacing it with ~20 lines of hallucinated content. Data loss.

After (the fix): When the proposed content is <50% of the original file length, the write is blocked with an educational error:

Warning: Proposed content (17 chars) is significantly shorter than the existing file
(200 chars), which may indicate data loss. Please use read_file to read the current
file content before overwriting. If you intend to replace the file with shorter
content, read the file first to confirm your intent.

The original file is preserved. The LLM is guided to read first, then retry.

Dive Deeper

Approach & Rationale

Problem: write_file is stateless — no instruction or mechanism tells the LLM to read before writing. The edit tool avoids this by design (its old_string param forces knowledge of current content), but write_file has no equivalent.

Alternatives considered:

1. Session-level read tracking — Track which files the LLM has read and refuse writes to unread files. Rejected: requires architectural changes to the tool system (shared state across tool invocations) that are beyond the scope of a bugfix.
2. Pre-hook validation — Use the hook system to intercept write_file calls. Rejected: hooks are user-configurable, not a reliable default safeguard.
3. Content-loss heuristic (chosen) — Compare proposed content length to original. Simple, stateless, catches the most damaging case. Combined with prompt-level instructions for broader coverage.

Decision: Defense-in-depth with 3 complementary layers, each independently useful:

Layer	File	What
System prompt	prompts.ts	"Read Before Write" mandate in Core Mandates
Tool description	write-file.ts	Warning in schema, following edit tool pattern
Runtime guard	write-file.ts	Block writes when proposed.length / original.length < 0.5 (files ≥100 chars)

Guard bypass conditions: new files, small files (<100 chars), empty files, user-modified content.

Reviewer Test Plan

1. Run unit tests: npx vitest run packages/core/src/tools/write-file.test.ts (6 new tests for the guard)
2. Run prompt snapshot tests: npx vitest run packages/core/src/core/prompts.test.ts
3. Manual test:
   • Create a file with >100 chars of content
   • Ask the agent to write to that file with significantly shorter content (without reading first)
   • Expected: write blocked with content-loss warning
   • Then ask the agent to read the file first, then write
   • Expected: write proceeds normally

Edge case	Guard behavior
New file creation	Skipped (file doesn't exist)
Empty existing file	Skipped (length < 100)
Small file (<100 chars)	Skipped (below threshold)
Content >50% of original	Skipped (ratio check passes)
User-modified content	Skipped (explicit bypass)

Testing Matrix

	🍏	🪟	🐧
npm run	❓	❓	✅
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

Fixes #2499