feat: add read_command_output tool for retrieving truncated command output

Implements a new tool that allows the LLM to retrieve full command output
when execute_command produces output exceeding the preview threshold.

Key components:
- ReadCommandOutputTool: Reads persisted output with search/pagination
- OutputInterceptor: Intercepts and persists large command outputs to disk
- Terminal settings UI: Configuration for output interception behavior
- Type definitions for output interception settings

The tool supports:
- Reading full output beyond the truncated preview
- Search/filtering with regex patterns (like grep)
- Pagination through large outputs using offset/limit

Includes comprehensive tests for ReadCommandOutputTool and OutputInterceptor.

Author: hannesrudolph

packages/types/src/global-settings.ts

@@ -29,6 +29,42 @@ export const DEFAULT_WRITE_DELAY_MS = 1000
  */
 export const DEFAULT_TERMINAL_OUTPUT_CHARACTER_LIMIT = 50_000
 
+/**
+ * Terminal output preview size options for persisted command output.
+ *
+ * Controls how much command output is kept in memory as a "preview" before
+ * the LLM decides to retrieve more via `read_command_output`. Larger previews
+ * mean more immediate context but consume more of the context window.
+ *
+ * - `small`: 2KB preview - Best for long-running commands with verbose output
+ * - `medium`: 4KB preview - Balanced default for most use cases
+ * - `large`: 8KB preview - Best when commands produce critical info early
+ *
+ * @see OutputInterceptor - Uses this setting to determine when to spill to disk
+ * @see PersistedCommandOutput - Contains the resulting preview and artifact reference
+ */
+export type TerminalOutputPreviewSize = "small" | "medium" | "large"
+
+/**
+ * Byte limits for each terminal output preview size.
+ *
+ * Maps preview size names to their corresponding byte thresholds.
+ * When command output exceeds these thresholds, the excess is persisted
+ * to disk and made available via the `read_command_output` tool.
+ */
+export const TERMINAL_PREVIEW_BYTES: Record<TerminalOutputPreviewSize, number> = {
+	small: 2048, // 2KB
+	medium: 4096, // 4KB
+	large: 8192, // 8KB
+}
+
+/**
+ * Default terminal output preview size.
+ * The "medium" (4KB) setting provides a good balance between immediate
+ * visibility and context window conservation for most use cases.
+ */
+export const DEFAULT_TERMINAL_OUTPUT_PREVIEW_SIZE: TerminalOutputPreviewSize = "medium"
+
 /**
  * Minimum checkpoint timeout in seconds.
  */
@@ -149,6 +185,7 @@ export const globalSettingsSchema = z.object({
 
 	terminalOutputLineLimit: z.number().optional(),
 	terminalOutputCharacterLimit: z.number().optional(),
+	terminalOutputPreviewSize: z.enum(["small", "medium", "large"]).optional(),
 	terminalShellIntegrationTimeout: z.number().optional(),
 	terminalShellIntegrationDisabled: z.boolean().optional(),
 	terminalCommandDelay: z.number().optional(),

packages/types/src/terminal.ts

@@ -32,3 +32,69 @@ export const commandExecutionStatusSchema = z.discriminatedUnion("status", [
 ])
 
 export type CommandExecutionStatus = z.infer<typeof commandExecutionStatusSchema>
+
+/**
+ * PersistedCommandOutput
+ *
+ * Represents the result of a terminal command execution that may have been
+ * truncated and persisted to disk.
+ *
+ * When command output exceeds the configured preview threshold, the full
+ * output is saved to a disk artifact file. The LLM receives this structure
+ * which contains:
+ * - A preview of the output (for immediate display in context)
+ * - Metadata about the full output (size, truncation status)
+ * - A path to the artifact file for later retrieval via `read_command_output`
+ *
+ * ## Usage in execute_command Response
+ *
+ * The response format depends on whether truncation occurred:
+ *
+ * **Not truncated** (output fits in preview):
+ * ```json
+ * {
+ *   "preview": "full output here...",
+ *   "totalBytes": 1234,
+ *   "artifactPath": null,
+ *   "truncated": false
+ * }
+ * ```
+ *
+ * **Truncated** (output exceeded threshold):
+ * ```json
+ * {
+ *   "preview": "first 4KB of output...",
+ *   "totalBytes": 1048576,
+ *   "artifactPath": "/path/to/tasks/123/command-output/cmd-1706119234567.txt",
+ *   "truncated": true
+ * }
+ * ```
+ *
+ * @see OutputInterceptor - Creates these results during command execution
+ * @see ReadCommandOutputTool - Retrieves full content from artifact files
+ */
+export interface PersistedCommandOutput {
+	/**
+	 * Preview of the command output, truncated to the preview threshold.
+	 * Always contains the beginning of the output, even if truncated.
+	 */
+	preview: string
+
+	/**
+	 * Total size of the command output in bytes.
+	 * Useful for determining if additional reads are needed.
+	 */
+	totalBytes: number
+
+	/**
+	 * Absolute path to the artifact file containing full output.
+	 * `null` if output wasn't truncated (no artifact was created).
+	 */
+	artifactPath: string | null
+
+	/**
+	 * Whether the output was truncated (exceeded preview threshold).
+	 * When `true`, use `read_command_output` to retrieve full content.
+	 */
+	truncated: boolean
+}

packages/types/src/tool.ts

@@ -17,6 +17,7 @@ export type ToolGroup = z.infer<typeof toolGroupsSchema>
 export const toolNames = [
 	"execute_command",
 	"read_file",
+	"read_command_output",
 	"write_to_file",
 	"apply_diff",
 	"search_and_replace",

packages/types/src/vscode-extension-host.ts

@@ -304,6 +304,7 @@ export type ExtensionState = Pick<
 	| "maxConcurrentFileReads"
 	| "terminalOutputLineLimit"
 	| "terminalOutputCharacterLimit"
+	| "terminalOutputPreviewSize"
 	| "terminalShellIntegrationTimeout"
 	| "terminalShellIntegrationDisabled"
 	| "terminalCommandDelay"

pnpm-lock.yaml

@@ -17,6 +17,7 @@ import { Task } from "../task/Task"
 import { fetchInstructionsTool } from "../tools/FetchInstructionsTool"
 import { listFilesTool } from "../tools/ListFilesTool"
 import { readFileTool } from "../tools/ReadFileTool"
+import { readCommandOutputTool } from "../tools/ReadCommandOutputTool"
 import { writeToFileTool } from "../tools/WriteToFileTool"
 import { searchAndReplaceTool } from "../tools/SearchAndReplaceTool"
 import { searchReplaceTool } from "../tools/SearchReplaceTool"
@@ -395,8 +396,10 @@ export async function presentAssistantMessage(cline: Task) {
 						return `[${block.name}]`
 					case "switch_mode":
 						return `[${block.name} to '${block.params.mode_slug}'${block.params.reason ? ` because: ${block.params.reason}` : ""}]`
-					case "codebase_search": // Add case for the new tool
+					case "codebase_search":
 						return `[${block.name} for '${block.params.query}']`
+					case "read_command_output":
+						return `[${block.name} for '${block.params.artifact_id}']`
 					case "update_todo_list":
 						return `[${block.name}]`
 					case "new_task": {
@@ -833,6 +836,13 @@ export async function presentAssistantMessage(cline: Task) {
 						pushToolResult,
 					})
 					break
+				case "read_command_output":
+					await readCommandOutputTool.handle(cline, block as ToolUse<"read_command_output">, {
+						askApproval,
+						handleError,
+						pushToolResult,
+					})
+					break
 				case "use_mcp_tool":
 					await useMcpToolTool.handle(cline, block as ToolUse<"use_mcp_tool">, {
 						askApproval,
@@ -1075,6 +1085,7 @@ function containsXmlToolMarkup(text: string): boolean {
 		"generate_image",
 		"list_files",
 		"new_task",
+		"read_command_output",
 		"read_file",
 		"search_and_replace",
 		"search_files",

src/core/assistant-message/presentAssistantMessage.ts

@@ -1,7 +1,10 @@
+import * as path from "path"
 import { Task } from "../task/Task"
 import { ClineMessage } from "@roo-code/types"
 import { ApiMessage } from "../task-persistence/apiMessages"
 import { cleanupAfterTruncation } from "../condense"
+import { OutputInterceptor } from "../../integrations/terminal/OutputInterceptor"
+import { getTaskDirectoryPath } from "../../utils/storage"
 
 export interface RewindOptions {
 	/** Whether to include the target message in deletion (edit=true, delete=false) */
@@ -207,6 +210,32 @@ export class MessageManager {
 			apiHistory = cleanupAfterTruncation(apiHistory)
 		}
 
+		// Step 6: Cleanup orphaned command output artifacts
+		// Collect timestamps from remaining messages to identify valid artifact IDs
+		// Artifacts whose IDs don't match any remaining message timestamp will be removed
+		if (!skipCleanup) {
+			const validIds = new Set<string>()
+
+			// Collect timestamps from remaining clineMessages
+			for (const msg of this.task.clineMessages) {
+				if (msg.ts) {
+					validIds.add(String(msg.ts))
+				}
+			}
+
+			// Collect timestamps from remaining apiHistory
+			for (const msg of apiHistory) {
+				if (msg.ts) {
+					validIds.add(String(msg.ts))
+				}
+			}
+
+			// Cleanup artifacts asynchronously (fire-and-forget with error handling)
+			this.cleanupOrphanedArtifacts(validIds).catch((error) => {
+				console.error("[MessageManager] Error cleaning up orphaned command output artifacts:", error)
+			})
+		}
+
 		// Only write if the history actually changed
 		const historyChanged =
 			apiHistory.length !== originalHistory.length || apiHistory.some((msg, i) => msg !== originalHistory[i])
@@ -215,4 +244,28 @@ export class MessageManager {
 			await this.task.overwriteApiConversationHistory(apiHistory)
 		}
 	}
+
+	/**
+	 * Cleanup orphaned command output artifacts.
+	 * Removes artifact files whose execution IDs don't match any remaining message timestamps.
+	 */
+	private async cleanupOrphanedArtifacts(validIds: Set<string>): Promise<void> {
+		try {
+			// Access globalStoragePath and taskId through the task reference
+			const task = this.task as any // Access private member
+			const globalStoragePath = task.globalStoragePath
+			const taskId = task.taskId
+
+			if (!globalStoragePath || !taskId) {
+				return
+			}
+
+			const taskDir = await getTaskDirectoryPath(globalStoragePath, taskId)
+			const outputDir = path.join(taskDir, "command-output")
+			await OutputInterceptor.cleanupByIds(outputDir, validIds)
+		} catch (error) {
+			// Silently fail - cleanup is best-effort
+			console.debug("[MessageManager] Artifact cleanup skipped:", error)
+		}
+	}
 }

src/core/message-manager/index.ts

@@ -11,6 +11,7 @@ import fetchInstructions from "./fetch_instructions"
 import generateImage from "./generate_image"
 import listFiles from "./list_files"
 import newTask from "./new_task"
+import readCommandOutput from "./read_command_output"
 import { createReadFileTool, type ReadFileToolOptions } from "./read_file"
 import runSlashCommand from "./run_slash_command"
 import searchAndReplace from "./search_and_replace"
@@ -65,6 +66,7 @@ export function getNativeTools(options: NativeToolsOptions = {}): OpenAI.Chat.Ch
 		generateImage,
 		listFiles,
 		newTask,
+		readCommandOutput,
 		createReadFileTool(readFileOptions),
 		runSlashCommand,
 		searchAndReplace,

src/core/prompts/tools/native-tools/index.ts

@@ -0,0 +1,77 @@
+import type OpenAI from "openai"
+
+/**
+ * Native tool definition for read_command_output.
+ *
+ * This tool allows the LLM to retrieve full command output that was truncated
+ * during execute_command. When command output exceeds the preview threshold,
+ * the full output is persisted to disk and an artifact_id is provided. The
+ * LLM can then use this tool to read the full content or search within it.
+ */
+
+const READ_COMMAND_OUTPUT_DESCRIPTION = `Retrieve the full output from a command that was truncated in execute_command. Use this tool when:
+1. The execute_command result shows "[OUTPUT TRUNCATED - Full output saved to artifact: cmd-XXXX.txt]"
+2. You need to see more of the command output beyond the preview
+3. You want to search for specific content in large command output
+
+The tool supports two modes:
+- **Read mode**: Read output starting from a byte offset with optional limit
+- **Search mode**: Filter lines matching a regex or literal pattern (like grep)
+
+Parameters:
+- artifact_id: (required) The artifact filename from the truncated output message (e.g., "cmd-1706119234567.txt")
+- search: (optional) Pattern to filter lines. Supports regex or literal strings. Case-insensitive.
+- offset: (optional) Byte offset to start reading from. Default: 0. Use for pagination.
+- limit: (optional) Maximum bytes to return. Default: 32KB.
+
+Example: Reading truncated command output
+{ "artifact_id": "cmd-1706119234567.txt" }
+
+Example: Reading with pagination (after first 32KB)
+{ "artifact_id": "cmd-1706119234567.txt", "offset": 32768 }
+
+Example: Searching for errors in build output
+{ "artifact_id": "cmd-1706119234567.txt", "search": "error|failed|Error" }
+
+Example: Finding specific test failures
+{ "artifact_id": "cmd-1706119234567.txt", "search": "FAIL" }`
+
+const ARTIFACT_ID_DESCRIPTION = `The artifact filename from the truncated command output (e.g., "cmd-1706119234567.txt")`
+
+const SEARCH_DESCRIPTION = `Optional regex or literal pattern to filter lines (case-insensitive, like grep)`
+
+const OFFSET_DESCRIPTION = `Byte offset to start reading from (default: 0, for pagination)`
+
+const LIMIT_DESCRIPTION = `Maximum bytes to return (default: 32KB)`
+
+export default {
+	type: "function",
+	function: {
+		name: "read_command_output",
+		description: READ_COMMAND_OUTPUT_DESCRIPTION,
+		strict: true,
+		parameters: {
+			type: "object",
+			properties: {
+				artifact_id: {
+					type: "string",
+					description: ARTIFACT_ID_DESCRIPTION,
+				},
+				search: {
+					type: ["string", "null"],
+					description: SEARCH_DESCRIPTION,
+				},
+				offset: {
+					type: ["number", "null"],
+					description: OFFSET_DESCRIPTION,
+				},
+				limit: {
+					type: ["number", "null"],
+					description: LIMIT_DESCRIPTION,
+				},
+			},
+			required: ["artifact_id", "search", "offset", "limit"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool