feat(bash): add output_filter parameter for build command filtering

Add output_filter parameter that captures regex-matching lines inline
while streaming full output to file. Useful for build commands where only
warnings/errors matter.

When a filter is provided:
- Full output still streams to temp file (for later inspection)
- Only matching lines are returned inline to the LLM
- Filter stats (matchCount, filteredBytes) are tracked incrementally

Example usage:
  output_filter: "^(warning|error|WARN|ERROR):"

This avoids the LLM having to grep through large build outputs to find
the relevant diagnostics.

Assisted-by: OpenCode (Claude Sonnet 4)

Author: cgwalters

packages/opencode/src/cli/cmd/tui/routes/session/index.tsx

@@ -30,6 +30,7 @@ import { Prompt, type PromptRef } from "@tui/component/prompt"
 import type { AssistantMessage, Part, ToolPart, UserMessage, TextPart, ReasoningPart } from "@opencode-ai/sdk/v2"
 import { useLocal } from "@tui/context/local"
 import { Locale } from "@/util/locale"
+import { formatSize } from "@/util/format"
 import type { Tool } from "@/tool/tool"
 import type { ReadTool } from "@/tool/read"
 import type { WriteTool } from "@/tool/write"
@@ -1608,6 +1609,14 @@ function Bash(props: ToolProps<typeof BashTool>) {
     return [...lines().slice(0, 10), "…"].join("\n")
   })
 
+  const filterInfo = createMemo(() => {
+    if (!props.metadata.filtered) return undefined
+    const total = formatSize(props.metadata.totalBytes ?? 0)
+    const omitted = formatSize(props.metadata.omittedBytes ?? 0)
+    const matches = props.metadata.matchCount ?? 0
+    return `Filtered: ${matches} match${matches === 1 ? "" : "es"} from ${total} (${omitted} omitted)`
+  })
+
   const workdirDisplay = createMemo(() => {
     const workdir = props.input.workdir
     if (!workdir || workdir === ".") return undefined
@@ -1644,6 +1653,9 @@ function Bash(props: ToolProps<typeof BashTool>) {
           <box gap={1}>
             <text fg={theme.text}>$ {props.input.command}</text>
             <text fg={theme.text}>{limited()}</text>
+            <Show when={filterInfo()}>
+              <text fg={theme.textMuted}>{filterInfo()}</text>
+            </Show>
             <Show when={overflow()}>
               <text fg={theme.textMuted}>{expanded() ? "Click to collapse" : "Click to expand"}</text>
             </Show>

packages/opencode/src/tool/bash.ts

@@ -27,6 +27,11 @@ export interface BashMetadata {
   description: string
   truncated?: boolean
   outputPath?: string
+  filtered?: boolean
+  filterPattern?: string
+  matchCount?: number
+  totalBytes?: number
+  omittedBytes?: number
 }
 
 const resolveWasm = (asset: string) => {
@@ -75,6 +80,12 @@ export const BashTool = Tool.define("bash", async () => {
           `The working directory to run the command in. Defaults to ${Instance.directory}. Use this instead of 'cd' commands.`,
         )
         .optional(),
+      output_filter: z
+        .string()
+        .describe(
+          `Optional regex pattern to filter output. When set, full output streams to a file while lines matching the pattern are returned inline. Useful for build commands where you only care about warnings/errors. Example: "^(warning|error|WARN|ERROR):.*" to capture compiler diagnostics. The regex is matched against each line.`,
+        )
+        .optional(),
       description: z
         .string()
         .describe(
@@ -88,6 +99,15 @@ export const BashTool = Tool.define("bash", async () => {
       }
       const timeout = params.timeout ?? DEFAULT_TIMEOUT
 
+      // Parse output_filter regex if provided
+      let filter: RegExp | undefined
+      if (params.output_filter) {
+        try {
+          filter = new RegExp(params.output_filter)
+        } catch (e) {
+          throw new Error(`Invalid output_filter regex: ${params.output_filter}. ${e}`)
+        }
+      }
       const tree = await parser().then((p) => p.parse(params.command))
       if (!tree) {
         throw new Error("Failed to parse command")
@@ -162,7 +182,7 @@ export const BashTool = Tool.define("bash", async () => {
         })
       }
 
-      const streaming = new StreamingOutput()
+      const streaming = new StreamingOutput({ filter })
 
       const proc = spawn(params.command, {
         shell,
@@ -258,6 +278,30 @@ export const BashTool = Tool.define("bash", async () => {
         streaming.appendMetadata("\n\n<bash_metadata>\n" + resultMetadata.join("\n") + "\n</bash_metadata>")
       }
 
+      // If using filter, return filtered lines
+      if (streaming.hasFilter) {
+        const output = streaming.truncated
+          ? `${streaming.filteredOutput}\n${streaming.finalize(params.output_filter)}`
+          : streaming.finalize(params.output_filter)
+
+        return {
+          title: params.description,
+          metadata: {
+            output: streaming.filteredOutput || `[no matches for filter: ${params.output_filter}]`,
+            exit: proc.exitCode,
+            description: params.description,
+            truncated: streaming.truncated,
+            outputPath: streaming.outputPath,
+            filtered: true,
+            filterPattern: params.output_filter,
+            matchCount: streaming.matchCount,
+            totalBytes: streaming.totalBytes,
+            omittedBytes: streaming.omittedBytes,
+          } as BashMetadata,
+          output,
+        }
+      }
+
       // If we streamed to a file (threshold exceeded), return truncated result
       if (streaming.truncated) {
         return {
@@ -268,6 +312,7 @@ export const BashTool = Tool.define("bash", async () => {
             description: params.description,
             truncated: true,
             outputPath: streaming.outputPath,
+            totalBytes: streaming.totalBytes,
           } as BashMetadata,
           output: streaming.finalize(),
         }

packages/opencode/src/tool/bash.txt

@@ -25,6 +25,7 @@ Usage notes:
   - You can specify an optional timeout in milliseconds. If not specified, commands will time out after 120000ms (2 minutes).
   - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
   - If the output exceeds ${maxLines} lines or ${maxBytes} bytes, it will be truncated and the full output will be written to a file. You can use Read with offset/limit to read specific sections or Grep to search the full content. Because of this, you do NOT need to use `head`, `tail`, or other truncation commands to limit output - just run the command directly.
+  - For build commands (make, cargo build, npm run build, tsc, etc.) that produce lots of output where you only care about warnings/errors, use the `output_filter` parameter with a regex like "^(warning|error|WARN|ERROR):". This streams full output to a file while returning only matching lines inline, saving you from having to grep the output afterward.
 
   - Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or when these commands are truly necessary for the task. Instead, always prefer using the dedicated tools for these commands:
     - File search: Use Glob (NOT find or ls)

packages/opencode/src/tool/truncation.ts

@@ -12,21 +12,32 @@ const log = Log.create({ service: "truncation" })
 
 export interface StreamingOutputOptions {
   threshold?: number
+  /** Optional regex to filter output lines. Matching lines are collected separately. */
+  filter?: RegExp
 }
 
 /**
  * Streaming output accumulator that spills to disk when threshold is exceeded.
  * Avoids O(n²) memory growth from string concatenation.
+ *
+ * Optionally supports line filtering - when a filter regex is provided, matching
+ * lines are collected separately while full output still streams to file.
  */
 export class StreamingOutput {
   private output = ""
   private outputBytes = 0
   private streamFile: { fd: number; path: string } | undefined
   private streamedBytes = 0
   private threshold: number
+  private filter?: RegExp
+  private filtered = ""
+  private filteredBytes = 0
+  private filteredCount = 0
+  private lineBuffer = ""
 
   constructor(options: StreamingOutputOptions = {}) {
     this.threshold = options.threshold ?? Truncate.MAX_BYTES
+    this.filter = options.filter
   }
 
   /** Append a chunk of output. Returns the current preview string. */
@@ -46,11 +57,30 @@ export class StreamingOutput {
       this.output += text
     }
 
+    // Process filter if active
+    if (this.filter) {
+      this.lineBuffer += text
+      const lines = this.lineBuffer.split("\n")
+      this.lineBuffer = lines.pop() || ""
+      for (const line of lines) {
+        if (this.filter.test(line)) {
+          const entry = line + "\n"
+          this.filtered += entry
+          this.filteredBytes += Buffer.byteLength(entry, "utf-8")
+          this.filteredCount++
+        }
+      }
+    }
+
     return this.preview()
   }
 
-  /** Get current preview - either full output or streaming indicator */
+  /** Get current preview - either full output, streaming indicator, or filter status */
   preview(): string {
+    if (this.filter) {
+      if (this.filtered) return this.filtered
+      return `[filtering: ${this.outputBytes} bytes, ${this.matchCount} matches...]\n`
+    }
     if (this.streamFile) {
       return `[streaming to file: ${this.streamedBytes} bytes written...]\n`
     }
@@ -77,8 +107,37 @@ export class StreamingOutput {
     return this.output
   }
 
+  /** Get filtered output (only when filter is active) */
+  get filteredOutput(): string {
+    return this.filtered
+  }
+
+  /** Number of lines matching the filter */
+  get matchCount(): number {
+    return this.filteredCount
+  }
+
+  /** Bytes omitted by filtering */
+  get omittedBytes(): number {
+    return this.totalBytes - this.filteredBytes
+  }
+
+  /** Whether a filter is active */
+  get hasFilter(): boolean {
+    return this.filter !== undefined
+  }
+
   /** Close the stream file if open. Call this after command completes. */
   close(): void {
+    // Process any remaining content in line buffer
+    if (this.filter && this.lineBuffer) {
+      if (this.filter.test(this.lineBuffer)) {
+        const entry = this.lineBuffer + "\n"
+        this.filtered += entry
+        this.filteredBytes += Buffer.byteLength(entry, "utf-8")
+        this.filteredCount++
+      }
+    }
     if (this.streamFile) {
       fsSync.closeSync(this.streamFile.fd)
     }
@@ -94,7 +153,13 @@ export class StreamingOutput {
   }
 
   /** Get final output string (for non-truncated) or hint message (for truncated) */
-  finalize(): string {
+  finalize(filterPattern?: string): string {
+    if (this.filter) {
+      if (this.streamFile) {
+        return `Filtered ${this.matchCount} matching lines from ${this.totalBytes} bytes of output.\nFull output saved to: ${this.streamFile.path}\nUse Grep to search or Read with offset/limit to view specific sections.\nNote: This file will be deleted after a few more commands. Copy it if you need to preserve it.`
+      }
+      return this.filtered || `[no matches for filter: ${filterPattern}]`
+    }
     if (this.streamFile) {
       return `The command output was ${this.streamedBytes} bytes and was truncated (inline limit: ${this.threshold} bytes).\nFull output saved to: ${this.streamFile.path}\nUse Grep to search the full content or Read with offset/limit to view specific sections.\nNote: This file will be deleted after a few more commands. Copy it if you need to preserve it.`
     }

packages/opencode/test/tool/bash.test.ts

@@ -408,4 +408,109 @@ describe("tool.bash truncation", () => {
       },
     })
   })
+
+  test("output_filter captures matching lines in memory for small output", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        // Small build output with warnings/errors - stays in memory
+        const result = await bash.execute(
+          {
+            command: `echo "compiling..."; echo "warning: unused variable"; echo "done"; echo "error: type mismatch"`,
+            output_filter: "^(warning|error):",
+            description: "Build with filter (small)",
+          },
+          ctx,
+        )
+
+        // Should NOT be truncated (small output stays in memory)
+        expect((result.metadata as any).truncated).toBe(false)
+        expect((result.metadata as any).filtered).toBe(true)
+        expect((result.metadata as any).matchCount).toBe(2)
+
+        // The output should contain only the filtered lines
+        expect(result.output).toContain("warning: unused variable")
+        expect(result.output).toContain("error: type mismatch")
+        expect(result.output).not.toContain("compiling...")
+        expect(result.output).not.toContain("done")
+      },
+    })
+  })
+
+  test("output_filter streams to file when output exceeds threshold", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        // Generate large output that exceeds threshold
+        const byteCount = Truncate.MAX_BYTES * 2
+        const result = await bash.execute(
+          {
+            command: `head -c ${byteCount} /dev/zero | tr '\\0' 'x'; echo ""; echo "warning: this is a warning"`,
+            output_filter: "^warning:",
+            description: "Build with filter (large)",
+          },
+          ctx,
+        )
+
+        // Should be truncated (large output spills to file)
+        expect((result.metadata as any).truncated).toBe(true)
+        expect((result.metadata as any).filtered).toBe(true)
+        const filepath = (result.metadata as any).outputPath
+        expect(filepath).toBeTruthy()
+
+        // The inline output should contain only the filtered line
+        expect(result.output).toContain("warning: this is a warning")
+        expect(result.output).toContain("Filtered 1 matching line")
+
+        // The full output file should contain everything
+        const saved = await Bun.file(filepath).text()
+        expect(saved.length).toBeGreaterThan(byteCount)
+        expect(saved).toContain("warning: this is a warning")
+      },
+    })
+  })
+
+  test("output_filter with no matches returns empty filtered output", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        const result = await bash.execute(
+          {
+            command: `echo "all good"; echo "no problems here"`,
+            output_filter: "^(warning|error):",
+            description: "Build with no matches",
+          },
+          ctx,
+        )
+
+        // Small output stays in memory, no truncation
+        expect((result.metadata as any).truncated).toBe(false)
+        expect((result.metadata as any).filtered).toBe(true)
+        expect((result.metadata as any).matchCount).toBe(0)
+        expect(result.output).toContain("[no matches for filter:")
+      },
+    })
+  })
+
+  test("invalid output_filter regex throws error", async () => {
+    await Instance.provide({
+      directory: projectRoot,
+      fn: async () => {
+        const bash = await BashTool.init()
+        await expect(
+          bash.execute(
+            {
+              command: `echo test`,
+              output_filter: "[invalid(regex",
+              description: "Invalid regex test",
+            },
+            ctx,
+          ),
+        ).rejects.toThrow("Invalid output_filter regex")
+      },
+    })
+  })
 })