ray
31 lines
2.5 KiB
Markdown
31 lines
2.5 KiB
Markdown
# 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. |