#18466: fix: suppress recoverable mutating tool errors when agent already replied
agents
size: XS
Cluster:
Tool Execution and Error Handling
## Problem
When a mutating tool (exec, message, etc.) fails with a recoverable error (missing params, invalid input), the agent typically handles it — retrying, working around, or explaining in its reply. Previously, these errors were **always** surfaced as ⚠️ warnings to the user, even when the agent already addressed the situation. This leads to confusing duplicate error messages in the chat.
**Example:** Agent calls `message(action=react)` without a `messageId`, gets an error, then explains in its reply. The user sees both the agent's explanation AND a raw `⚠️ ✉️ Message: react · 💪 failed: messageId required` line.
## Fix
For mutating tool errors, check if the error is recoverable (contains keywords like `required`, `missing`, `invalid`, etc.) AND the agent already produced a user-facing reply. If both are true, suppress the ⚠️ warning — the agent handled it.
Non-recoverable errors (timeouts, connection failures, etc.) still **always** surface for safety.
Also: `suppressToolErrors` config is now respected for all tool types. Previously, mutating tools bypassed this setting entirely.
## Changes
- `src/agents/pi-embedded-runner/run/payloads.ts` — Updated `shouldShowToolErrorWarning` logic
- `src/agents/pi-embedded-runner/run/payloads.e2e.test.ts` — Updated tests to match new behavior, added test for non-recoverable mutating errors with assistant reply
## Risk
Low. Only suppresses errors the agent already handled. Non-recoverable and unhandled errors still surface.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Improved error handling by suppressing recoverable mutating tool errors when the agent has already provided a user-facing reply, eliminating duplicate error messages in chat. The fix distinguishes between recoverable errors (missing/invalid parameters) and non-recoverable errors (timeouts, connection failures), with only the former being suppressed when the agent handled them. Additionally, the `suppressToolErrors` config now properly applies to all tool types, including mutating tools which previously bypassed this setting entirely.
Key changes:
- Modified `shouldShowToolErrorWarning` to check if errors are recoverable AND agent replied before suppressing mutating tool warnings
- Moved `suppressToolErrors` check to apply globally instead of only to non-mutating tools
- Updated tests to reflect new behavior, including new test case for non-recoverable mutating errors with assistant reply
- Minor `.gitignore` addition for log files
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The logic change is well-contained, thoroughly tested, and improves user experience by eliminating confusing duplicate error messages. The fix maintains safety by always surfacing non-recoverable errors and unhandled errors. The test coverage is comprehensive with multiple test cases covering the new behavior including edge cases for recoverable vs non-recoverable errors with/without assistant replies.
- No files require special attention
<sub>Last reviewed commit: 0e679b8</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#19632: fix: suppressToolErrors now suppresses exec tool failure notifications
by Gitjay11 · 2026-02-18
87.6%
#22087: Preserve assistant reply when exec fails under suppressToolErrors
by graysurf · 2026-02-20
86.3%
#20382: fix: move suppressToolErrors check before mutating tool check
by klawdius-noodle · 2026-02-18
85.8%
#17552: fix(agents): suppress tool error warnings when assistant already re...
by AytuncYildizli · 2026-02-15
85.7%
#19235: fix(telegram): tool error warnings no longer overwrite streamed rep...
by gatewaybuddy · 2026-02-17
81.5%
#18708: feat(messages): add suppressToolErrorWarnings config option
by codexGW · 2026-02-17
81.4%
#17024: fix(tool errors): suppress compaction-related tool errors
by Limitless2023 · 2026-02-15
80.9%
#21195: fix: suppress orphaned tool_use/tool_result errors after session co...
by ruslansychov-git · 2026-02-19
80.5%
#18415: fix(agents): suppress benign exec exit code 1 from tool error surfa...
by aldoeliacim · 2026-02-16
80.4%
#13282: fix(agents): instruct agent not to retry lost tool results
by thebtf · 2026-02-10
79.9%