feat(context): prune historical verbose tool results with tool protection (#2078)

[Cobies]

Linked issue

Closes #2078

PR type

• Bug fix
• New feature
• Documentation only
• Code refactoring
• Maintenance/tooling
• Breaking change

Summary

• Introduces lib/context-pruning.ts providing non-destructive rolling-window tool result pruning connected to the native pi.on("context") event hook in extensions/gentle-ai.ts.
• Preserves 100% of raw tool outputs for recent user turns (default recentTurnsToKeep = 2).
• Uses a conservative threshold (DEFAULT_MAX_RETAINED_CHARS = 4_000) for older turns, omitting bulky terminal dumps (like multi-thousand-line git diff outputs) while retaining error summaries if isError: true.
• Strictly exempts critical lifecycle and orchestration tools from pruning (PROTECTED_TOOL_NAMES: subagent_run, subagent_result, subagent_status, gentle_review*, mem_*, todo, ask_user_*).
• Filters synthetic subagent notifications (role: "user", Subagent <agent> (task <id>, ...) finished.) so background task arrivals never prematurely advance the human user turn window.
• Fully non-destructive (only filters transient model API payloads; disk session history and terminal UI remain untouched) and can be disabled via GENTLE_PI_CONTEXT_PRUNING=off.

Changes

File	Change
lib/context-pruning.ts	Rolling-window pruning logic, tool whitelist (PROTECTED_TOOL_NAMES), synthetic notification detector, and formatting.
extensions/gentle-ai.ts	Wire pi.on("context") hook to invoke pruneContextMessages.
tests/context-pruning.test.ts	Unit tests covering turn retention, size boundaries, error excerpts, protected tools, synthetic notifications, and idempotence.
tests/gentle-ai.test.ts	Integration test verifying the context event hook registration and selective pruning behavior.

Test plan

• Ran unit tests: node --test tests/context-pruning.test.ts (12 pass, 0 fail).
• Ran integration tests: GENTLE_PI_AGENTS_CHILD= node --test tests/gentle-ai.test.ts (124 pass, 0 fail).
• Ran type check: node scripts/check-types.mjs (0 recorded diagnostics, no regressions).
• Verified git diff --check clean.

Contributor checklist

• Linked an approved/reported issue (feat(context): prune historical verbose tool results with tool protection and turn filtering #2078).
• Creation applies exactly one type:* label: type:feature.
• Conventional commits; no attribution or Co-Authored-By trailers.
• Minimal atomic change targeting main.

Summary by CodeRabbit

• New Features
  • Older, oversized tool outputs are now shortened in conversation context, while the two most recent user turns remain intact.
  • Error outputs retain a brief excerpt, and protected tool outputs are not shortened.
  • Configure the number of recent turns to keep and the output length limit, or disable pruning through settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: a114deed-2b3e-4601-9052-b1efe4a79037

---

📥 Commits

Reviewing files that changed from the base of the PR and between d672066 and 51fb186.

---

📒 Files selected for processing (4)

• extensions/gentle-ai.ts
• lib/context-pruning.ts
• tests/context-pruning.test.ts
• tests/gentle-ai.test.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The change adds rolling-window pruning for older oversized tool results. It preserves recent turns and protected tool results, supports configuration and an environment opt-out, and connects pruning to the context event.

Changes

Context pruning

Layer / File(s)	Summary
Pruning rules and validation lib/context-pruning.ts, tests/context-pruning.test.ts	Adds configurable pruning with defaults of two recent user turns and 4,000 characters. Synthetic subagent notifications do not count as user turns. Older oversized tool results are replaced with omission notices, except protected results. Tests cover configuration, error excerpts, non-text content, and unchanged results.
Context-event integration extensions/gentle-ai.ts, tests/gentle-ai.test.ts	The context handler prunes nonempty message arrays and returns the result only when pruning changes the array or a message identity. The regression test checks that the oldest of three verbose bash results is pruned.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Pi
  participant GentleAI as gentle-ai context handler
  participant Pruner as pruneContextMessages
  Pi->>GentleAI: context event with messages
  GentleAI->>Pruner: prune messages
  Pruner-->>GentleAI: pruned messages
  GentleAI-->>Pi: changed messages or undefined

Loading

Suggested reviewers: alan-thegentleman

---

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: pruning historical verbose tool results with protected tools. It is specific and related to the pull request.
Linked Issues check		Issue #2078 is directly linked and remains open. lib/context-pruning.ts implements the rolling window with defaults of 2 turns and 4,000 characters. It prunes only older toolResult messages, prese…
Out of Scope Changes check		The changes are limited to the context-pruning implementation, its pi.on("context") integration, and focused unit and integration tests. The additional orchestration tool protections support issue #…

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}