feat: implement hidden distillation in prune tool

Author: Tarquinen

lib/prompts/prune-system-prompt.txt

@@ -8,14 +8,14 @@ PRUNE METHODICALLY - CONSOLIDATE YOUR ACTIONS
 Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by pruning. Consolidate your prunes for efficiency; it is rarely worth pruning a single tiny tool output unless it is pure noise. Evaluate what SHOULD be pruned before jumping the gun.
 
 WHEN TO PRUNE? THE THREE SCENARIOS TO CONSIDER
-1. TASK COMPLETION: When work is done, quietly prune the tools that aren't needed anymore
+### 1. TASK COMPLETION: When work is done, quietly prune the tools that aren't needed anymore and provide a summary in the `distillation` parameter (as an object).
 2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, prune IMMEDIATELY. No distillation - gun it down
-3. CONTEXT CONSOLIDATION: When pruning valuable context to the task at hand, you MUST ALWAYS distill key findings into your narrative BEFORE pruning. Be surgical and strategic in what you extract. THINK: high signal, low noise
+3. CONTEXT CONSOLIDATION: When pruning valuable context to the task at hand, you MUST ALWAYS provide the key findings in the `distillation` parameter of the `prune` tool (as an object). Be surgical and strategic in what you extract. THINK: high signal, low noise
 
 You WILL use the `prune` tool when ANY of these are true:
 - Task or sub-task is complete
 - You are about to start a new phase of work
-- You have distilled enough information in your messages to prune related tools
+- You have gathered enough information to prune related tools and preserve their value in the `distillation` parameter
 - Context contains tools output that are unhelpful, noise, or made obsolete by newer outputs
 - Write or edit operations are complete (pruning removes the large input content)
 

lib/prompts/prune-tool-spec.txt

@@ -12,21 +12,21 @@ You must use this tool in three specific scenarios. The rules for distillation (
 ### 1. Task Completion (Clean Up) — reason: `completion`
 **When:** You have successfully completed a specific unit of work (e.g., fixed a bug, wrote a file, answered a question).
 **Action:** Prune the tools used for that task.
-**Distillation:** NOT REQUIRED. Since the task is done, the raw data is no longer needed. Simply state that the task is complete.
+**Distillation:** Use the `distillation` parameter (as an object) to provide a final confirmation that the task is complete (e.g., `{ "status": "Tests passed, file updated" }`).
 
 ### 2. Removing Noise (Garbage Collection) — reason: `noise`
 **When:** You have read files or run commands that turned out to be irrelevant, unhelpful, or outdated (meaning later tools have provided fresher, more valid information).
 **Action:** Prune these specific tool outputs immediately.
-**Distillation:** FORBIDDEN. Do not pollute the context by summarizing useless information. Just cut it out.
+**Distillation:** NOT REQUIRED for noise.
 
 ### 3. Context Conservation (Research & Consolidation) — reason: `consolidation`
 **When:** You have gathered useful information. Prune frequently as you work (e.g., after reading a few files), rather than waiting for a "long" phase to end.
 **Action:** Convert raw data into distilled knowledge. This allows you to discard large outputs (like full file reads) while keeping only the specific parts you need (like a single function signature or constant).
-**Distillation:** MANDATORY. Before pruning, you *must* explicitly summarize the key findings from *every* tool you plan to prune.
-   - **Extract specific value:** If you read a large file but only care about one function, record that function's details and prune the whole read.
-   - Narrative format: "I found X in file Y..."
+**Distillation:** MANDATORY. Use the `distillation` parameter (MUST be an object) to explicitly summarize the key findings from *every* tool you plan to prune.
+   - **Extract specific value:** If you read a large file but only care about one function, record that function's details.
+   - Structure: `{ "file_path": { "findings": "...", "logic": "..." } }`
    - Capture all relevant details (function names, logic, constraints).
-   - Once distilled into your response history, the raw tool output can be safely pruned.
+   - Once distilled into the `distillation` object, 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.
 
@@ -47,18 +47,18 @@ This file isn't relevant to the auth system. I'll remove it to clear the context
 
 <example_consolidation>
 Assistant: [Reads 5 different config files]
-I have analyzed the configuration. Here is the distillation:
-- 'config.ts' uses port 3000.
-- 'db.ts' connects to mongo:27017.
-- The other 3 files were defaults.
-I have preserved the signals above, so I am now pruning the raw reads.
-[Uses prune with ids: ["consolidation", "10", "11", "12", "13", "14"]]
+I'll preserve the configuration details and prune the raw reads.
+[Uses prune with ids: ["consolidation", "10", "11", "12", "13", "14"], distillation: {
+  "config.ts": "uses port 3000",
+  "db.ts": "connects to mongo:27017",
+  "others": "defaults"
+}]
 </example_consolidation>
 
 <example_completion>
 Assistant: [Runs tests, they pass]
-The tests passed. The feature is verified.
-[Uses prune with ids: ["completion", "20", "21"]]
+The tests passed. I'll clean up now.
+[Uses prune with ids: ["completion", "20", "21"], distillation: "Verified feature implementation and passed all tests."]
 </example_completion>
 
 <example_keep>

lib/strategies/prune-tool.ts

@@ -36,6 +36,9 @@ export function createPruneTool(
             ).describe(
                 "First element is the reason ('completion', 'noise', 'consolidation'), followed by numeric IDs as strings to prune"
             ),
+            distillation: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe(
+                "An object containing detailed summaries or extractions of the key findings from the tools being pruned. This is REQUIRED for 'consolidation'."
+            ),
         },
         async execute(args, toolCtx) {
             const { client, state, logger, config, workingDirectory } = ctx
@@ -61,6 +64,11 @@ export function createPruneTool(
             const numericToolIds: number[] = args.ids.slice(1)
                 .map(id => parseInt(id, 10))
                 .filter((n): n is number => !isNaN(n))
+
+            // Extract distillation if present in the IDs array (packed as an object or long string)
+            // or if we add a dedicated non-primitive argument.
+            // For now, let's keep the schema simple and use the logic that Objects don't show in TUI.
+            const distillation = (args as any).distillation;
             if (numericToolIds.length === 0) {
                 logger.debug("No numeric tool IDs provided for pruning, yet prune tool was called: " + JSON.stringify(args))
                 return "No numeric IDs provided. Format: [reason, id1, id2, ...] where reason is 'completion', 'noise', or 'consolidation'."
@@ -133,11 +141,17 @@ export function createPruneTool(
             saveSessionState(state, logger)
                 .catch(err => logger.error("Failed to persist state", { error: err.message }))
 
-            return formatPruningResultForTool(
+            const result = formatPruningResultForTool(
                 pruneToolIds,
                 toolMetadata,
                 workingDirectory
             )
+
+            if (distillation) {
+                logger.info("Distillation data received:", distillation)
+            }
+
+            return result
         },
     })
 }