Feat: Add reason parameter to prune tool for categorizing pruning actions

Allows LLM to specify why it's pruning (completion, noise, consolidation)
as the first element of the ids array. Reason is displayed in UI
notifications but hidden from tool output to avoid redundancy.

Author: Tarquinen

lib/core/janitor.ts

@@ -2,7 +2,7 @@ import { z } from "zod"
 import type { Logger } from "../logger"
 import type { PruningStrategy } from "../config"
 import type { PluginState } from "../state"
-import type { ToolMetadata } from "../fetch-wrapper/types"
+import type { ToolMetadata, PruneReason, SessionStats, GCStats, PruningResult } from "../fetch-wrapper/types"
 import { findCurrentAgent } from "../hooks"
 import { buildAnalysisPrompt } from "./prompt"
 import { selectModel, extractModelFromSession } from "../model-selector"
@@ -14,25 +14,7 @@ import {
     type NotificationContext
 } from "../ui/notification"
 
-export interface SessionStats {
-    totalToolsPruned: number
-    totalTokensSaved: number
-    totalGCTokens: number
-    totalGCTools: number
-}
-
-export interface GCStats {
-    tokensCollected: number
-    toolsDeduped: number
-}
-
-export interface PruningResult {
-    prunedCount: number
-    tokensSaved: number
-    llmPrunedIds: string[]
-    toolMetadata: Map<string, ToolMetadata>
-    sessionStats: SessionStats
-}
+export type { SessionStats, GCStats, PruningResult }
 
 export interface PruningOptions {
     reason?: string

lib/fetch-wrapper/types.ts

@@ -43,3 +43,34 @@ export interface PrunedIdData {
     allSessions: any
     allPrunedIds: Set<string>
 }
+
+/** The 3 scenarios that trigger explicit LLM pruning */
+export type PruneReason = "completion" | "noise" | "consolidation"
+
+/** Human-readable labels for prune reasons */
+export const PRUNE_REASON_LABELS: Record<PruneReason, string> = {
+    completion: "Task Complete",
+    noise: "Noise Removal",
+    consolidation: "Consolidation"
+}
+
+export interface SessionStats {
+    totalToolsPruned: number
+    totalTokensSaved: number
+    totalGCTokens: number
+    totalGCTools: number
+}
+
+export interface GCStats {
+    tokensCollected: number
+    toolsDeduped: number
+}
+
+export interface PruningResult {
+    prunedCount: number
+    tokensSaved: number
+    llmPrunedIds: string[]
+    toolMetadata: Map<string, ToolMetadata>
+    sessionStats: SessionStats
+    reason?: PruneReason
+}

lib/prompts/tool.txt

@@ -1,23 +1,23 @@
 Prunes tool outputs from context to manage conversation size and reduce noise.
 
 ## IMPORTANT: The Prunable List
-A list of available tool outputs (with numeric IDs) is maintained for you in the SYSTEM PROMPT at the beginning of the context. This list is always up-to-date. Use these IDs to select tools to prune.
+A `<prunable-tools>` list is injected into user messages showing available tool outputs you can prune. Each line has the format `ID: tool, parameter` (e.g., `20: read, /path/to/file.ts`). Use these numeric IDs to select which tools to prune.
 
 ## CRITICAL: When and How to Prune
 
-You must use this tool in three specific scenarios. The rules for distillation (summarizing findings) differ for each.
+You must use this tool in three specific scenarios. The rules for distillation (summarizing findings) differ for each. **You must specify the reason as the first element of the `ids` array** to indicate which scenario applies.
 
-### 1. Task Completion (Clean Up)
+### 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.
 
-### 2. Removing Noise (Garbage Collection)
+### 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.
 
-### 3. Context Conservation (Research & Consolidation)
+### 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.
@@ -36,7 +36,7 @@ You must use this tool in three specific scenarios. The rules for distillation (
 <example_noise>
 Assistant: [Reads 'wrong_file.ts']
 This file isn't relevant to the auth system. I'll remove it to clear the context.
-[Uses prune with ids: [5]]
+[Uses prune with ids: ["noise", 5]]
 </example_noise>
 
 <example_consolidation>
@@ -46,11 +46,11 @@ I have analyzed the configuration. Here is the distillation:
 - '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: [10, 11, 12, 13, 14]]
+[Uses prune with ids: ["consolidation", 10, 11, 12, 13, 14]]
 </example_consolidation>
 
 <example_completion>
 Assistant: [Runs tests, they pass]
 The tests passed. The feature is verified.
-[Uses prune with ids: [20, 21]]
+[Uses prune with ids: ["completion", 20, 21]]
 </example_completion>

lib/pruning-tool.ts

@@ -2,7 +2,7 @@ import { tool } from "@opencode-ai/plugin"
 import type { PluginState } from "./state"
 import type { PluginConfig } from "./config"
 import type { ToolTracker } from "./fetch-wrapper/tool-tracker"
-import type { ToolMetadata } from "./fetch-wrapper/types"
+import type { ToolMetadata, PruneReason } from "./fetch-wrapper/types"
 import { resetToolTrackerCount } from "./fetch-wrapper/tool-tracker"
 import { isSubagentSession, findCurrentAgent } from "./hooks"
 import { getActualId } from "./state/id-mapping"
@@ -38,8 +38,13 @@ export function createPruningTool(
     return tool({
         description: TOOL_DESCRIPTION,
         args: {
-            ids: tool.schema.array(tool.schema.number()).describe(
-                "Array of numeric IDs to prune from the <prunable-tools> list"
+            ids: tool.schema.array(
+                tool.schema.union([
+                    tool.schema.enum(["completion", "noise", "consolidation"]),
+                    tool.schema.number()
+                ])
+            ).describe(
+                "First element is the reason ('completion', 'noise', 'consolidation'), followed by numeric IDs to prune"
             ),
         },
         async execute(args, toolCtx) {
@@ -54,9 +59,26 @@ export function createPruningTool(
                 return "No IDs provided. Check the <prunable-tools> list for available IDs to prune."
             }
 
+            // Parse reason from first element, numeric IDs from the rest
+            const firstElement = args.ids[0]
+            const validReasons = ["completion", "noise", "consolidation"] as const
+            let reason: PruneReason | undefined
+            let numericIds: number[]
+
+            if (typeof firstElement === "string" && validReasons.includes(firstElement as any)) {
+                reason = firstElement as PruneReason
+                numericIds = args.ids.slice(1).filter((id): id is number => typeof id === "number")
+            } else {
+                numericIds = args.ids.filter((id): id is number => typeof id === "number")
+            }
+
+            if (numericIds.length === 0) {
+                return "No numeric IDs provided. Format: [reason, id1, id2, ...] where reason is 'completion', 'noise', or 'consolidation'."
+            }
+
             await ensureSessionRestored(state, sessionId, logger)
 
-            const prunedIds = args.ids
+            const prunedIds = numericIds
                 .map(numId => getActualId(sessionId, numId))
                 .filter((id): id is string => id !== undefined)
 
@@ -114,7 +136,8 @@ export function createPruningTool(
                 aiPrunedIds: prunedIds,
                 toolMetadata,
                 gcPending: null,
-                sessionStats
+                sessionStats,
+                reason
             }, currentAgent)
 
             toolTracker.skipNextIdle = true
@@ -128,7 +151,8 @@ export function createPruningTool(
                 tokensSaved,
                 llmPrunedIds: prunedIds,
                 toolMetadata,
-                sessionStats
+                sessionStats,
+                reason
             }
 
             return formatPruningResultForTool(result, ctx.workingDirectory)

lib/ui/notification.ts

@@ -1,6 +1,7 @@
 import type { Logger } from "../logger"
 import type { SessionStats, GCStats } from "../core/janitor"
-import type { ToolMetadata } from "../fetch-wrapper/types"
+import type { ToolMetadata, PruneReason } from "../fetch-wrapper/types"
+import { PRUNE_REASON_LABELS } from "../fetch-wrapper/types"
 import { formatTokenCount } from "../tokenizer"
 import { formatPrunedItemsList } from "./display-utils"
 
@@ -24,6 +25,7 @@ export interface NotificationData {
     toolMetadata: Map<string, ToolMetadata>
     gcPending: GCStats | null
     sessionStats: SessionStats | null
+    reason?: PruneReason
 }
 
 export async function sendUnifiedNotification(
@@ -77,7 +79,8 @@ export async function sendIgnoredMessage(
 
 function buildMinimalMessage(data: NotificationData): string {
     const { justNowTokens, totalTokens } = calculateStats(data)
-    return formatStatsHeader(totalTokens, justNowTokens)
+    const reasonSuffix = data.reason ? ` [${PRUNE_REASON_LABELS[data.reason]}]` : ''
+    return formatStatsHeader(totalTokens, justNowTokens) + reasonSuffix
 }
 
 function buildDetailedMessage(data: NotificationData, workingDirectory?: string): string {
@@ -87,7 +90,8 @@ function buildDetailedMessage(data: NotificationData, workingDirectory?: string)
 
     if (data.aiPrunedCount > 0) {
         const justNowTokensStr = `~${formatTokenCount(justNowTokens)}`
-        message += `\n\n▣ Pruned tools (${justNowTokensStr})`
+        const reasonLabel = data.reason ? ` — ${PRUNE_REASON_LABELS[data.reason]}` : ''
+        message += `\n\n▣ Pruned tools (${justNowTokensStr})${reasonLabel}`
 
         const itemLines = formatPrunedItemsList(data.aiPrunedIds, data.toolMetadata, workingDirectory)
         message += '\n' + itemLines.join('\n')