ray
2.5 KiB
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.