# Tool-Usage Pitfalls (SPQ-v2 sessions)

Lessons from real sessions that bit the agent. Read this before heavy editing sessions on spq-v2.

## read_file dedup guard

The `read_file` tool caches by path. Calling it again on the same path WITHOUT an `offset`/`limit` is treated as a duplicate and BLOCKED after 5 repeats, halting your turn.

**Symptom**: "BLOCKED: You have called read_file on this exact region N times and the file has NOT changed."

**What went wrong (2026-07-08 session)**: After reading ROForm.tsx (lines 1-500) and RODetailModal.tsx (full), I called `read_file` on the same paths again without offset to "get the rest". The dedup guard fired, blocked the call 5+ times, and triggered a hard-stop guardrail. The user saw repeated identical failures and expressed frustration ("why are you making so many mistakes").

**Fix**: If you already have content from a prior read and need a different region, pass `offset` + `limit` to read a specific slice. Never repeat the bare path call. If you hit the block, stop immediately and change strategy — do not retry the identical call.

**Prevention**: Track which files you have already read in the session. When you need more of a large file, use `offset` to skip already-read lines.

## patch requires all 3 params

The `patch` tool hard-fails after 6 retries if `path` is omitted, even when `old_string` and `new_string` are correct.

**Symptom**: "Tool loop hard stop: same_tool_failure_halt; Stopped patch: it failed 6 times this turn."

**What went wrong (2026-07-08 session)**: While adding the Financial tab, I called `patch` with only `mode`, `old_string`, and `new_string` but forgot `path`. The tool kept failing, I kept retrying with the same missing param, and it hit the hard-stop guardrail after 6 attempts.

**Fix**: Always include `path`, `old_string`, AND `new_string` together in a single call. Do not attempt to "batch" patches by omitting `path` — it will not work.

## User frustration signals

When the user says "why are you making so many mistakes" or "i need you to not make mistakes", this is a FIRST-CLASS signal that your tool usage has become repetitive and error-prone. Stop immediately, acknowledge the specific failure, and change strategy — do not attempt to justify or retry the failing approach.

Ray's preference: He is tolerant of exploration and wrong turns, but repeated identical tool failures (especially guardrail hits) frustrate him. When you hit a tool guardrail, the correct response is to acknowledge it and switch tools, not retry.