Improve tool output formatting and add usage examples to context_pruning description

- Add detailed usage guidance and examples to context_pruning tool description
- Extract shared formatting helpers in janitor (groupDeduplicationDetails, formatDeduplicationLines, formatToolSummaryLines)
- Add formatPruningResultForTool method for structured tool output
- Remove unused protectedTools parameter from buildAnalysisPrompt
- Update janitor to use 'ai-analysis' strategy name

Author: Tarquinen

index.ts

@@ -4,7 +4,7 @@ import { tool } from "@opencode-ai/plugin"
 import { getConfig } from "./lib/config"
 import { Logger } from "./lib/logger"
 import { Janitor, type SessionStats } from "./lib/janitor"
-import { formatTokenCount } from "./lib/tokenizer"
+
 import { checkForUpdates } from "./lib/version-checker"
 
 /**
@@ -149,7 +149,7 @@ const plugin: Plugin = (async (ctx) => {
     })
 
     // Check for updates on launch (fire and forget)
-    checkForUpdates(ctx.client, logger).catch(() => {})
+    checkForUpdates(ctx.client, logger).catch(() => { })
 
     // Show migration toast if config was migrated (delayed to not overlap with version toast)
     if (migrations.length > 0) {
@@ -177,7 +177,7 @@ const plugin: Plugin = (async (ctx) => {
             if (event.type === "session.status" && event.properties.status.type === "idle") {
                 // Skip pruning for subagent sessions
                 if (await isSubagentSession(ctx.client, event.properties.sessionID)) return
-                
+
                 // Skip if no idle strategies configured
                 if (config.strategies.onIdle.length === 0) return
 
@@ -191,7 +191,7 @@ const plugin: Plugin = (async (ctx) => {
         /**
          * Chat Params Hook: Caches model info for janitor
          */
-        "chat.params": async (input, output) => {
+        "chat.params": async (input, _output) => {
             const sessionId = input.sessionID
 
             // Cache model information for this session so janitor can access it
@@ -217,11 +217,37 @@ const plugin: Plugin = (async (ctx) => {
          */
         tool: config.strategies.onTool.length > 0 ? {
             context_pruning: tool({
-                description: "Performs semantic pruning on session tool outputs that are no longer " +
-                    "relevant to the current task. Use this to declutter the conversation context and " +
-                    "filter signal from noise when you notice the context is getting cluttered with " +
-                    "outdated information (e.g., after completing a debugging session, switching to a " +
-                    "new task, or when old file reads are no longer needed).",
+                description: `Performs semantic pruning on session tool outputs that are no longer relevant to the current task. Use this to declutter the conversation context and filter signal from noise when you notice the context is getting cluttered with outdated information.
+
+## When to Use This Tool
+
+- After completing a debugging session or fixing a bug
+- When switching focus to a new task or feature
+- After exploring multiple files that didn't lead to changes
+- When you've been iterating on a difficult problem and some approaches didn't pan out
+- When old file reads, greps, or bash outputs are no longer relevant
+
+## Examples
+
+<example>
+Working through a list of bugs to fix:
+User: Please fix these 5 type errors in the codebase.
+Assistant: I'll work through each error. [Fixes first error]
+First error fixed. Let me prune the debugging context before moving to the next one.
+[Uses context_pruning with reason: "first bug fixed, moving to next task"]
+</example>
+
+<example>
+After exploring the codebase to understand it:
+Assistant: I've reviewed the relevant files. Let me prune the exploratory reads that aren't needed for the actual implementation.
+[Uses context_pruning with reason: "exploration complete, pruning unrelated file reads"]
+</example>
+
+<example>
+After trying multiple approaches that didn't work:
+Assistant: I've been trying several approaches to fix this issue. Let me prune the failed attempts to keep focus on the working solution.
+[Uses context_pruning with reason: "pruning failed iteration attempts, keeping working solution context"]
+</example>`,
                 args: {
                     reason: tool.schema.string().optional().describe(
                         "Brief reason for triggering pruning (e.g., 'task complete', 'switching focus')"
@@ -238,7 +264,7 @@ const plugin: Plugin = (async (ctx) => {
                         return "No prunable tool outputs found. Context is already optimized."
                     }
 
-                    return `Context pruning complete. Pruned ${result.prunedCount} tool outputs (~${formatTokenCount(result.tokensSaved)} tokens saved).`
+                    return janitor.formatPruningResultForTool(result)
                 },
             }),
         } : undefined,

lib/janitor.ts

@@ -70,7 +70,7 @@ export class Janitor {
      * Convenience method for idle-triggered pruning (sends notification automatically)
      */
     async runOnIdle(sessionID: string, strategies: PruningStrategy[]): Promise<void> {
-        const result = await this.runWithStrategies(sessionID, strategies, { trigger: 'idle' })
+        await this.runWithStrategies(sessionID, strategies, { trigger: 'idle' })
         // Notification is handled inside runWithStrategies
     }
 
@@ -196,7 +196,7 @@ export class Janitor {
             // ============================================================
             let llmPrunedIds: string[] = []
 
-            if (strategies.includes('llm-analysis')) {
+            if (strategies.includes('ai-analysis')) {
                 // Filter out duplicates and protected tools
                 const protectedToolCallIds: string[] = []
                 const prunableToolCallIds = unprunedToolCallIds.filter(id => {
@@ -253,7 +253,6 @@ export class Janitor {
                     const analysisPrompt = buildAnalysisPrompt(
                         prunableToolCallIds,
                         sanitizedMessages,
-                        this.protectedTools,
                         allPrunedSoFar,
                         protectedToolCallIds,
                         options.reason
@@ -342,8 +341,8 @@ export class Janitor {
             this.statsState.set(sessionID, sessionStats)
 
             // Determine notification mode based on which strategies ran
-            const hasLlmAnalysis = strategies.includes('llm-analysis')
-            
+            const hasLlmAnalysis = strategies.includes('ai-analysis')
+
             if (hasLlmAnalysis) {
                 await this.sendSmartModeNotification(
                     sessionID,
@@ -377,13 +376,13 @@ export class Janitor {
             const keptCount = candidateCount - prunedCount
             const hasBoth = deduplicatedIds.length > 0 && llmPrunedIds.length > 0
             const breakdown = hasBoth ? ` (${deduplicatedIds.length} duplicate, ${llmPrunedIds.length} llm)` : ""
-            
+
             // Build log metadata
             const logMeta: Record<string, any> = { trigger: options.trigger }
             if (options.reason) {
                 logMeta.reason = options.reason
             }
-            
+
             this.logger.info("janitor", `Pruned ${prunedCount}/${candidateCount} tools${breakdown}, ${keptCount} kept (~${formatTokenCount(tokensSaved)} tokens)`, logMeta)
 
             return {
@@ -568,6 +567,73 @@ export class Janitor {
         return toolsSummary
     }
 
+    /**
+     * Group deduplication details by tool type
+     * Shared helper used by notifications and tool output formatting
+     */
+    private groupDeduplicationDetails(
+        deduplicationDetails: Map<string, any>
+    ): Map<string, Array<{ count: number, key: string }>> {
+        const grouped = new Map<string, Array<{ count: number, key: string }>>()
+
+        for (const [_, details] of deduplicationDetails) {
+            const { toolName, parameterKey, duplicateCount } = details
+            if (!grouped.has(toolName)) {
+                grouped.set(toolName, [])
+            }
+            grouped.get(toolName)!.push({
+                count: duplicateCount,
+                key: this.shortenPath(parameterKey)
+            })
+        }
+
+        return grouped
+    }
+
+    /**
+     * Format grouped deduplication results as lines
+     * Shared helper for building deduplication summaries
+     */
+    private formatDeduplicationLines(
+        grouped: Map<string, Array<{ count: number, key: string }>>,
+        indent: string = '  '
+    ): string[] {
+        const lines: string[] = []
+
+        for (const [toolName, items] of grouped.entries()) {
+            for (const item of items) {
+                const removedCount = item.count - 1
+                lines.push(`${indent}${toolName}: ${item.key} (${removedCount}× duplicate)`)
+            }
+        }
+
+        return lines
+    }
+
+    /**
+     * Format tool summary (from buildToolsSummary) as lines
+     * Shared helper for building LLM-pruned summaries
+     */
+    private formatToolSummaryLines(
+        toolsSummary: Map<string, string[]>,
+        indent: string = '  '
+    ): string[] {
+        const lines: string[] = []
+
+        for (const [toolName, params] of toolsSummary.entries()) {
+            if (params.length === 1) {
+                lines.push(`${indent}${toolName}: ${params[0]}`)
+            } else if (params.length > 1) {
+                lines.push(`${indent}${toolName} (${params.length}):`)
+                for (const param of params) {
+                    lines.push(`${indent}  ${param}`)
+                }
+            }
+        }
+
+        return lines
+    }
+
     /**
      * Send minimal summary notification (just tokens saved and count)
      */
@@ -625,21 +691,10 @@ export class Janitor {
         }
         message += '\n'
 
-        // Group by tool type
-        const grouped = new Map<string, Array<{ count: number, key: string }>>()
+        // Group by tool type using shared helper
+        const grouped = this.groupDeduplicationDetails(deduplicationDetails)
 
-        for (const [_, details] of deduplicationDetails) {
-            const { toolName, parameterKey, duplicateCount } = details
-            if (!grouped.has(toolName)) {
-                grouped.set(toolName, [])
-            }
-            grouped.get(toolName)!.push({
-                count: duplicateCount,
-                key: this.shortenPath(parameterKey)
-            })
-        }
-
-        // Display grouped results
+        // Display grouped results (with UI-specific formatting: total dupes header, limit to 5)
         for (const [toolName, items] of grouped.entries()) {
             const totalDupes = items.reduce((sum, item) => sum + (item.count - 1), 0)
             message += `\n${toolName} (${totalDupes} duplicate${totalDupes > 1 ? 's' : ''}):\n`
@@ -657,6 +712,33 @@ export class Janitor {
         await this.sendIgnoredMessage(sessionID, message.trim())
     }
 
+    /**
+     * Format pruning result for tool output (returned to AI)
+     * Uses shared helpers for consistency with UI notifications
+     */
+    formatPruningResultForTool(result: PruningResult): string {
+        const lines: string[] = []
+        lines.push(`Context pruning complete. Pruned ${result.prunedCount} tool outputs.`)
+        lines.push('')
+
+        // Section 1: Deduplicated tools
+        if (result.deduplicatedIds.length > 0 && result.deduplicationDetails.size > 0) {
+            lines.push(`Duplicates removed (${result.deduplicatedIds.length}):`)
+            const grouped = this.groupDeduplicationDetails(result.deduplicationDetails)
+            lines.push(...this.formatDeduplicationLines(grouped))
+            lines.push('')
+        }
+
+        // Section 2: LLM-pruned tools
+        if (result.llmPrunedIds.length > 0) {
+            lines.push(`Semantically pruned (${result.llmPrunedIds.length}):`)
+            const toolsSummary = this.buildToolsSummary(result.llmPrunedIds, result.toolMetadata)
+            lines.push(...this.formatToolSummaryLines(toolsSummary))
+        }
+
+        return lines.join('\n').trim()
+    }
+
     /**
      * Smart mode notification - shows both deduplication and LLM analysis results
      */
@@ -695,20 +777,7 @@ export class Janitor {
         // Section 1: Deduplicated tools
         if (deduplicatedIds.length > 0 && deduplicationDetails) {
             message += `\n📦 Duplicates removed (${deduplicatedIds.length}):\n`
-
-            // Group by tool type
-            const grouped = new Map<string, Array<{ count: number, key: string }>>()
-
-            for (const [_, details] of deduplicationDetails) {
-                const { toolName, parameterKey, duplicateCount } = details
-                if (!grouped.has(toolName)) {
-                    grouped.set(toolName, [])
-                }
-                grouped.get(toolName)!.push({
-                    count: duplicateCount,
-                    key: this.shortenPath(parameterKey)
-                })
-            }
+            const grouped = this.groupDeduplicationDetails(deduplicationDetails)
 
             for (const [toolName, items] of grouped.entries()) {
                 message += `  ${toolName}:\n`
@@ -722,8 +791,6 @@ export class Janitor {
         // Section 2: LLM-pruned tools
         if (llmPrunedIds.length > 0) {
             message += `\n🤖 LLM analysis (${llmPrunedIds.length}):\n`
-
-            // Use buildToolsSummary logic
             const toolsSummary = this.buildToolsSummary(llmPrunedIds, toolMetadata)
 
             for (const [toolName, params] of toolsSummary.entries()) {

lib/prompt.ts

@@ -106,7 +106,6 @@ function minimizeMessages(messages: any[], alreadyPrunedIds?: string[], protecte
 export function buildAnalysisPrompt(
     unprunedToolCallIds: string[],
     messages: any[],
-    protectedTools: string[],
     alreadyPrunedIds?: string[],
     protectedToolCallIds?: string[],
     reason?: string  // Optional reason from tool call