#12965: fix: suggest /clear in context overflow error message
agents
stale
Cluster:
Context Management Enhancements
## Summary
Adds actionable recovery guidance to context overflow errors by suggesting `/clear` as an immediate fix.
Closes #12940
## Changes
Updated error message from:
```
Context overflow: prompt too large for the model. Try again with less input or a larger-context model.
```
To:
```
Context overflow: prompt too large for the model. Try /clear to reset session history, or use a larger-context model.
```
## Why
- Users hitting context overflow on messaging channels (Telegram, etc.) had no clear recovery path
- Gateway restarts don't help (session history persists)
- `/compact` fails when context is already overflowed
- `/clear` is the immediate fix that works
## Test plan
- [x] `pnpm vitest run src/agents/pi-embedded-helpers.sanitizeuserfacingtext.test.ts` → 10/10 pass
- [x] Updated test expectation to match new message
## AI Disclosure 🤖
Built with Claude Opus 4.5 as coding assistant. Lightly tested (unit tests pass). I understand the change: it's a simple string replacement in 3 locations with corresponding test update.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This change updates the user-facing “context overflow” recovery text in the embedded PI agent to recommend `/clear` as the immediate remediation, and adjusts the sanitizer unit test to match. The message is emitted from both the generic assistant-error formatting path (`src/agents/pi-embedded-helpers/errors.ts`) and the embedded runner’s context-overflow recovery flow (`src/agents/pi-embedded-runner/run.ts`), ensuring users see consistent guidance when the session history itself prevents retries/compaction.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk.
- The changes are limited to updating a static, user-facing error message in three call sites plus a matching unit test expectation; no control flow or parsing logic was modified.
- No files require special attention
<!-- 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
#15749: fix: improve context overflow error with diagnostic details
by superlowburn · 2026-02-13
85.1%
#18997: fix: improve context overflow error messages and docs
by realhoratiobot · 2026-02-17
82.9%
#10792: Agents: avoid context overflow false positives
by arunsanna · 2026-02-07
77.7%
#7975: feat(commands): add /reset-context command
by sergi039 · 2026-02-03
76.6%
#13318: fix(agents): prevent sanitizeUserFacingText from rewriting conversa...
by hleliofficiel · 2026-02-10
75.6%
#8896: fix: improve compaction fallback message with recovery hints
by joetomasone · 2026-02-04
74.3%
#10273: fix(agents): detect and auto-compact mid-run context overflow
by terryops · 2026-02-06
74.2%
#8661: fix: display rate limit errors correctly instead of as context over...
by dbottme · 2026-02-04
73.9%
#9173: Fix: Improve error messaging for API rate limits and billing errors
by vishaltandale00 · 2026-02-04
73.8%
#5360: fix(compaction): add emergency pruning for context overflow
by sgwannabe · 2026-01-31
73.6%