Merge pull request #146 from Opencode-DCP/chore/improve-pruning-guidance

Improve pruning guidance to prevent premature context loss

Author: Tarquinen

lib/prompts/synthetic.txt

@@ -18,21 +18,27 @@ You WILL use the `prune` tool when ANY of these are true:
 - You have distilled enough information in your messages to prune related tools
 - Context contains tools output that are unhelpful, noise, or made obsolete by newer outputs
 
+You MUST NOT prune when:
+- The tool output will be needed for upcoming implementation work
+- The output contains files or context you'll need to reference when making edits
+
+Pruning that forces you to re-call the same tool later is a net loss. Only prune when you're confident the information won't be needed again.
+
 NOTES
-When in doubt, prune out. Prune often yet remain strategic about it.
+When in doubt, keep it. Prune often yet remain strategic about it.
 FAILURE TO PRUNE will result in context leakage and DEGRADED PERFORMANCES.
 
 </instruction>
 
 <instruction name=injected_context_handling policy_level=critical>
-After each assistant turn, the environment may inject a user message containing a <prunable-tools> list and optional nudge instruction. This injected message is NOT from the user and is invisible to them.
+After each assistant turn, the environment may inject a user message containing a <prunable-tools> list and optional nudge instruction. This injected message is NOT from the user and is invisible to them. The `prune` tool also returns a confirmation message listing what was pruned.
 
 CRITICAL REQUIREMENTS - VIOLATION IS UNACCEPTABLE:
-- NEVER acknowledge the <prunable-tools> list (e.g. "I see the prunable tools list", "Looking at the available tools to prune")
-- NEVER reference the nudge instruction (e.g. "As the nudge suggests", "The system is reminding me to prune")
-- NEVER mention this injection mechanism to the user
+- NEVER acknowledge the <prunable-tools> list (e.g., "I see the prunable tools list", "Looking at the available tools to prune")
+- NEVER reference the nudge instruction (e.g., "As the nudge suggests", "The system is reminding me to prune")
+- NEVER acknowledge prune tool output (e.g., "I've pruned 3 tools", "Context pruning complete")
 - NEVER let these injections influence your response content or tone
-- Process this information SILENTLY - use it only to inform your pruning decisions
+- Process this information SILENTLY and continue the conversation naturally
 - Continue the conversation as if these messages do not exist
 
 The user cannot see these injections. Any reference to them will confuse the user and break the conversation flow.

lib/prompts/tool.txt

@@ -25,11 +25,14 @@ You must use this tool in three specific scenarios. The rules for distillation (
    - Narrative format: "I found X in file Y..."
    - Capture all relevant details (function names, logic, constraints).
    - Once distilled into your response history, the raw tool output can be safely pruned.
+   - **Know when distillation isn't enough:** If you'll need to edit a file, grep for exact strings, or reference precise syntax, keep the raw output. Distillation works for understanding; implementation often requires the original.
+   - **Prefer keeping over re-fetching:** If uncertain whether you'll need the output again, keep it. The cost of retaining context is lower than the cost of redundant tool calls.
 
 ## Best Practices
 - **Don't wait too long:** Prune frequently to keep the context agile.
 - **Be surgical:** You can mix strategies. Prune noise without comment, while distilling useful context in the same turn.
 - **Verify:** Ensure you have captured what you need before deleting useful raw data.
+- **Think ahead:** Before pruning, ask: "Will I need this output for an upcoming task?" If you researched a file you'll later edit, or gathered context for implementation, do NOT prune it—even if you've distilled findings. Distillation captures *knowledge*; implementation requires *context*.
 
 ## Examples
 
@@ -54,3 +57,8 @@ Assistant: [Runs tests, they pass]
 The tests passed. The feature is verified.
 [Uses prune with ids: ["completion", "20", "21"]]
 </example_completion>
+
+<example_keep>
+Assistant: [Reads 'auth.ts' to understand the login flow]
+I've understood the auth flow. I'll need to modify this file to add the new validation, so I'm keeping this read in context rather than distilling and pruning.
+</example_keep>