refactor: use metadata object for prune tool reason and distillation

Tarquinen · Tarquinen · commit c15df057e8d7 · 2025-12-19T01:47:46.000-05:00
- Replace reason-as-first-id pattern with structured metadata object
- metadata.reason: 'completion' | 'noise' | 'consolidation'
- metadata.distillation: optional object for consolidation findings
- Update prompts to clarify distillation rules per reason type
- Add TUI rendering documentation explaining hidden arguments
diff --git a/docs/opencode-tui-tool-rendering.md b/docs/opencode-tui-tool-rendering.md
@@ -0,0 +1,160 @@
+# OpenCode TUI Tool Rendering: Argument Visibility
+
+This document explains how opencode's TUI determines which tool arguments are displayed to users and how to design custom plugin tools that keep certain arguments hidden.
+
+## Key Files
+
+All rendering logic is located in the opencode reference repository:
+
+- **Main rendering file**: `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx`
+
+## Rendering Flow
+
+### 1. Tool Part Rendering Entry Point (Line 1230)
+
+When a tool call is rendered, the TUI checks the `ToolRegistry` for a custom renderer:
+
+```tsx
+const render = ToolRegistry.render(props.part.tool) ?? GenericTool
+```
+
+If no custom renderer is registered for the tool name, it falls back to the `GenericTool` component.
+
+### 2. GenericTool Component (Lines 1329-1335)
+
+The fallback renderer for all plugin-defined tools:
+
+```tsx
+function GenericTool(props: ToolProps<any>) {
+  return (
+    <ToolTitle icon="⚙" fallback="Writing command..." when={true}>
+      {props.tool} {input(props.input)}
+    </ToolTitle>
+  )
+}
+```
+
+This renders:
+1. The tool name (`props.tool`)
+2. A formatted string of arguments via the `input()` helper function
+
+### 3. The `input()` Helper Function (Lines 1702-1709)
+
+This is the critical "gatekeeper" that determines which arguments appear in the TUI:
+
+```tsx
+function input(input: Record<string, any>, omit?: string[]): string {
+  const primitives = Object.entries(input).filter(([key, value]) => {
+    if (omit?.includes(key)) return false
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+  })
+  if (primitives.length === 0) return ""
+  return `[${primitives.map(([key, value]) => `${key}=${value}`).join(", ")}]`
+}
+```
+
+## Argument Visibility Rules
+
+### Arguments That ARE Displayed
+
+| Type | Example | TUI Output |
+|------|---------|------------|
+| `string` | `reason: "completion"` | `[reason=completion]` |
+| `number` | `count: 5` | `[count=5]` |
+| `boolean` | `force: true` | `[force=true]` |
+
+### Arguments That Are NOT Displayed
+
+| Type | Example | TUI Output |
+|------|---------|------------|
+| `array` | `ids: ["1", "2", "3"]` | *(nothing)* |
+| `object` | `metadata: { reason: "..." }` | *(nothing)* |
+| `null` | `data: null` | *(nothing)* |
+| `undefined` | `data: undefined` | *(nothing)* |
+
+## Designing Hidden Arguments
+
+To keep arguments hidden from the TUI while still passing data to your tool:
+
+### Option 1: Use Arrays
+
+```typescript
+args: {
+  ids: tool.schema.array(tool.schema.string())
+}
+```
+
+Arrays are filtered out by the `input()` function's primitive check.
+
+### Option 2: Use Objects
+
+```typescript
+args: {
+  metadata: tool.schema.object({
+    reason: tool.schema.enum(["a", "b", "c"]),
+    distillation: tool.schema.record(tool.schema.string(), tool.schema.any()).optional()
+  })
+}
+```
+
+Objects are also filtered out, making them ideal for structured hidden data.
+
+### Option 3: Use Records
+
+```typescript
+args: {
+  data: tool.schema.record(tool.schema.string(), tool.schema.any())
+}
+```
+
+Records (key-value maps) are objects and thus hidden.
+
+## Example: The `prune` Tool
+
+The `prune` tool in this plugin uses a combination of these strategies:
+
+```typescript
+args: {
+  ids: tool.schema.array(tool.schema.string()),  // Hidden (array)
+  metadata: tool.schema.object({                  // Hidden (object)
+    reason: tool.schema.enum(["completion", "noise", "consolidation"]),
+    distillation: tool.schema.record(tool.schema.string(), tool.schema.any()).optional()
+  })
+}
+```
+
+**TUI Output**: `⚙ prune`
+
+No arguments are displayed because:
+1. `ids` is an array (filtered out)
+2. `metadata` is an object (filtered out)
+
+## ToolRegistry for Custom Renderers
+
+If you want complete control over how a tool is rendered, you can register a custom renderer:
+
+```tsx
+const ToolRegistry = (() => {
+  const state: Record<string, ToolRegistration> = {}
+  function register<T extends Tool.Info>(input: ToolRegistration<T>) {
+    state[input.name] = input
+    return input
+  }
+  return {
+    register,
+    container(name: string) { return state[name]?.container },
+    render(name: string) { return state[name]?.render },
+  }
+})()
+```
+
+However, plugin-defined tools cannot currently register custom TUI renderers from outside the opencode core package, so the `GenericTool` fallback and the `input()` filter are the primary mechanisms for controlling visibility.
+
+## Summary
+
+| Goal | Strategy |
+|------|----------|
+| Show argument in TUI | Use `string`, `number`, or `boolean` |
+| Hide argument from TUI | Use `array`, `object`, or `record` |
+| Hide structured data | Wrap in a single `object` or `record` argument |
+| Clean TUI output | Ensure all top-level args are non-primitives |
diff --git a/lib/prompts/prune-nudge.txt b/lib/prompts/prune-nudge.txt
@@ -2,9 +2,9 @@
 **CRITICAL CONTEXT WARNING:** Your context window is filling with tool outputs. Strict adherence to context hygiene is required.
 
 **Immediate Actions Required:**
-1. **Garbage Collect:** If you read files or ran commands that yielded no value, prune them NOW. Do not summarize them.
-2. **Task Cleanup:** If a sub-task is complete, prune the tools used.
-3. **Consolidate:** If you are holding valuable raw data, you *must* distill the insights into your narrative and prune the raw entry.
+1. **Task Completion:** If a sub-task is complete, prune the tools used. No distillation.
+2. **Noise Removal:** If you read files or ran commands that yielded no value, prune them NOW. No distillation.
+3. **Consolidation:** If you are holding valuable raw data, you *must* distill the insights into `metadata.distillation` and prune the raw entry.
 
 **Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must prune.
 </instruction>
diff --git a/lib/prompts/prune-system-prompt.txt b/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 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 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
+1. TASK COMPLETION: When work is done, quietly prune the tools that aren't needed anymore. No distillation.
+2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, prune. No distillation.
+3. CONTEXT CONSOLIDATION: When pruning valuable context to the task at hand, you MUST ALWAYS provide the key findings in the `metadata.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 gathered enough information to prune related tools and preserve their value in the `distillation` parameter
+- You have gathered enough information to prune related tools and preserve their value in the `metadata.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)
 
@@ -26,7 +26,7 @@ You MUST NOT prune when:
 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, keep it. Prune frequently yet remain strategic and consolidate your actions.
+When in doubt, keep it. Consolidate your actions and aim for high-impact prunes that significantly reduce context size.
 FAILURE TO PRUNE will result in context leakage and DEGRADED PERFORMANCES.
 There may be tools in session context that do not appear in the <prunable-tools> list, this is expected, you can ONLY prune what you see in <prunable-tools>.
 
diff --git a/lib/prompts/prune-tool-spec.txt b/lib/prompts/prune-tool-spec.txt
@@ -1,4 +1,4 @@
-Prunes tool outputs from context to manage conversation size and reduce noise. For `write` and `edit` tools, the input content is pruned instead of the output.
+Prunes tool outputs from context to manage conversation size and reduce noise.
 
 ## IMPORTANT: The Prunable List
 A `<prunable-tools>` list is injected into user messages showing available tool outputs you can prune when there are tools available for pruning. Each line has the format `ID: tool, parameter` (e.g., `20: read, /path/to/file.ts`). You MUST only use numeric IDs that appear in this list to select which tools to prune.
@@ -7,58 +7,63 @@ A `<prunable-tools>` list is injected into user messages showing available tool
 
 ## 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 specify the reason as the first element of the `ids` array** to indicate which scenario applies.
+You must use this tool in three specific scenarios. The rules for distillation (summarizing findings) differ for each. **You must provide a `metadata` object with a `reason` and optional `distillation`** to indicate which scenario applies.
 
 ### 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:** Use the `distillation` parameter (as an object) to provide a final confirmation that the task is complete (e.g., `{ "status": "Tests passed, file updated" }`).
+**Distillation:** FORBIDDEN. Do not summarize completed work.
 
 ### 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:** NOT REQUIRED for noise.
+**Distillation:** FORBIDDEN. Do not summarize 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.
+**When:** You have gathered useful information. Wait until you have several items or a few large outputs to prune, rather than doing tiny, frequent prunes. Aim for high-impact prunes that significantly reduce context size.
 **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. Use the `distillation` parameter (MUST be an object) to explicitly summarize the key findings from *every* tool you plan to prune.
+**Distillation:** MANDATORY. You MUST provide the distilled findings in the `metadata.distillation` parameter of the `prune` tool (as an object).
    - **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 the `distillation` object, the raw tool output can be safely pruned.
+   - **Consolidate:** When pruning multiple tools, your distillation object MUST aggregate findings from ALL of them. Ensure you capture any information necessary to solve the current task.
+   - Structure: Map the `ID` from the `<prunable-tools>` list to its distilled findings.
+     Example: `{ "20": { "findings": "...", "logic": "..." } }`
+   - Capture all relevant details (function names, logic, constraints) to ensure no signal is lost.
+   - Prioritize information that is essential for the immediate next steps of your plan.
+   - Once distilled into the `metadata` 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.
 
 ## Best Practices
-- **Consolidate your prunes:** Don't prune a single small tool output (like a short bash command) unless it's pure noise. Wait until you have several items or a few large outputs to prune. Aim for high-impact prunes that significantly reduce context size or noise.
-- **Don't wait too long:** Prune frequently to keep the context agile, but balance this with the need for consolidation.
-- **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*.
+- **Strategic Consolidation:** Don't prune single small tool outputs (like short bash commands) unless they are pure noise. Instead, wait until you have several items or large outputs to perform high-impact prunes. This balances the need for an agile context with the efficiency of larger batches.
+- **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.
 
 ## Examples
 
 <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: ["noise", "5"]]
+[Uses prune with ids: ["5"], metadata: { "reason": "noise" }]
 </example_noise>
 
 <example_consolidation>
 Assistant: [Reads 5 different config files]
 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"
+[Uses prune with ids: ["10", "11", "12", "13", "14"], metadata: {
+  "reason": "consolidation",
+  "distillation": {
+    "10": "uses port 3000",
+    "11": "connects to mongo:27017",
+    "12": "defines shared constants",
+    "13": "export defaults",
+    "14": "unused fallback"
+  }
 }]
 </example_consolidation>
 
 <example_completion>
 Assistant: [Runs tests, they pass]
 The tests passed. I'll clean up now.
-[Uses prune with ids: ["completion", "20", "21"], distillation: "Verified feature implementation and passed all tests."]
+[Uses prune with ids: ["20", "21"], metadata: { "reason": "completion" }]
 </example_completion>
 
 <example_keep>
@@ -69,5 +74,5 @@ I've understood the auth flow. I'll need to modify this file to add the new vali
 <example_edit_completion>
 Assistant: [Edits 'auth.ts' to add validation]
 The edit was successful. I no longer need the raw edit content in context.
-[Uses prune with ids: ["completion", "15"]]
+[Uses prune with ids: ["15"], metadata: { "reason": "completion" }]
 </example_edit_completion>
diff --git a/lib/strategies/prune-tool.ts b/lib/strategies/prune-tool.ts
@@ -34,11 +34,14 @@ export function createPruneTool(
             ids: tool.schema.array(
                 tool.schema.string()
             ).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'."
+                "Numeric IDs as strings to prune from the <prunable-tools> list"
             ),
+            metadata: tool.schema.object({
+                reason: tool.schema.enum(["completion", "noise", "consolidation"]).describe("The reason for pruning"),
+                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'."
+                ),
+            }).describe("Metadata about the pruning operation."),
         },
         async execute(args, toolCtx) {
             const { client, state, logger, config, workingDirectory } = ctx
@@ -52,26 +55,20 @@ export function createPruneTool(
                 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 reason = args.ids[0];
-            const validReasons = ["completion", "noise", "consolidation"] as const
-            if (typeof reason !== "string" || !validReasons.includes(reason as any)) {
-                logger.debug("Invalid pruning reason provided: " + reason)
-                return "No valid pruning reason found. Use 'completion', 'noise', or 'consolidation' as the first element."
+            if (!args.metadata || !args.metadata.reason) {
+                logger.debug("Prune tool called without metadata.reason: " + JSON.stringify(args))
+                return "Missing metadata.reason. Provide metadata: { reason: 'completion' | 'noise' | 'consolidation' }"
             }
 
-            const numericToolIds: number[] = args.ids.slice(1)
+            const { reason, distillation } = args.metadata;
+
+            const numericToolIds: number[] = args.ids
                 .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'."
+                return "No numeric IDs provided. Format: ids: [id1, id2, ...]"
             }
 
             // Fetch messages to calculate tokens and find current agent
