#15749: fix: improve context overflow error with diagnostic details
agents
stale
size: XS
Cluster:
Context Management Enhancements
## Summary
- Replaces the generic "Context overflow: prompt too large" message with diagnostic details
- Now includes provider/model name, context window limit, session identifier, and message count
- Adds actionable recovery steps (run /reset, switch model, adjust contextTokens)
**Before:**
```
Context overflow: prompt too large for the model. Try /reset (or /new) to start a fresh session, or use a larger-context model.
```
**After:**
```
Context overflow (anthropic/claude-opus-4-5, limit: 200,000 tokens)
Session: discord:channel:123456789
Messages: 47
Actions:
• Run /reset to clear context and start fresh
• Or switch to a model with a larger context window
• Consider lowering contextTokens in config to trigger earlier compaction
```
Closes #9409
## Test plan
- [x] Lint passes (oxlint, no warnings/errors)
- [x] Existing e2e tests check `isError: true` and `error.kind`, not exact text — unchanged
- [ ] Manual test: trigger a context overflow and verify the new message format
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This change updates the embedded PI agent’s context-overflow handling to return a multi-line error message with diagnostics (provider/model, context-window limit, session label, message count) and suggested recovery actions instead of the previous generic one-liner.
The behavior lives in `src/agents/pi-embedded-runner/run.ts` inside the overflow/compaction recovery branch, and affects what end users see when the runner detects a context overflow and can’t recover via auto-compaction/tool-result truncation.
<h3>Confidence Score: 3/5</h3>
- This PR is close to safe to merge but has a couple of user-facing error-handling edge cases to fix first.
- Core change is localized and straightforward, but the new formatting can throw if the context limit isn’t a number, and it may expose sensitive session identifiers and mislabel compaction failures as context overflows.
- src/agents/pi-embedded-runner/run.ts
<sub>Last reviewed commit: 281f021</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#18997: fix: improve context overflow error messages and docs
by realhoratiobot · 2026-02-17
89.1%
#12965: fix: suggest /clear in context overflow error message
by asklee-klawd · 2026-02-10
85.1%
#20539: fix: detect additional context overflow error patterns to prevent l...
by echoVic · 2026-02-19
82.2%
#10273: fix(agents): detect and auto-compact mid-run context overflow
by terryops · 2026-02-06
80.1%
#9620: fix: increase auto-compaction reserve buffer to 40k tokens
by Arlo83963 · 2026-02-05
80.1%
#6353: fix(agents): detect Anthropic 'exceed context limit' error for auto...
by Glucksberg · 2026-02-01
80.0%
#5360: fix(compaction): add emergency pruning for context overflow
by sgwannabe · 2026-01-31
79.2%
#8661: fix: display rate limit errors correctly instead of as context over...
by dbottme · 2026-02-04
78.5%
#10792: Agents: avoid context overflow false positives
by arunsanna · 2026-02-07
78.3%
#11999: fix: add session-growth guard to prevent unbounded session store gr...
by reverendrewind · 2026-02-08
78.0%