[FEATURE] Add output mode options to BashOutput tool for incremental/stateful monitoring

Resolved 💬 5 comments Opened Oct 20, 2025 by TweedBeetle Closed Jan 9, 2026

Summary

The BashOutput tool currently returns the complete output from the beginning every time it's called, which can be inefficient for monitoring long-running background processes. This behavior also contradicts the tool's own description, which states it "always returns only new output since the last check."

Proposed Enhancement

Add an output_mode parameter to BashOutput with the following options:

Option 1: output_mode="incremental" (Stateful)

  • Returns only new output lines since the last check
  • Maintains state per shell_id to track what's been read
  • Most efficient for monitoring long-running processes
  • Suggested as new default to match documented behavior

Option 2: output_mode="full"

  • Returns complete output from start (current behavior)
  • Useful when you need to review entire output history
  • Maintains backward compatibility if set as default

Option 3: output_mode="tail:N"

  • Returns last N lines of output
  • Useful for checking recent status without full history

Optional: reset parameter

  • Boolean flag to reset stateful tracking
  • Allows re-reading from beginning when using incremental mode

Use Cases

Long-running deployments

# Check progress incrementally without re-reading entire deployment log
BashOutput(bash_id="deploy_123", output_mode="incremental")

Build monitoring

# Track build progress efficiently
BashOutput(bash_id="build_456", output_mode="incremental")

# Later, review full output if build fails
BashOutput(bash_id="build_456", output_mode="full")

Quick status checks

# Just see the most recent 20 lines
BashOutput(bash_id="server_789", output_mode="tail:20")

Benefits

  1. Performance: Reduces token usage when monitoring long-running processes
  2. Usability: Makes it practical to check on background tasks frequently without output duplication
  3. Clarity: Easier to spot new output vs. re-reading everything
  4. Documentation alignment: Makes actual behavior match the described behavior
  5. Backward compatibility: Can maintain current behavior while adding new modes

Current Workaround

Currently, users must manually track which output they've seen or accept reading the entire output repeatedly, which becomes inefficient for long-running processes with significant output.

Testing

I verified the current behavior by running a background command that outputs timestamped messages over 10 seconds, then checking output multiple times. Each check returned the complete output from the beginning, not incremental updates.

Platform

All platforms (macOS, Linux, Windows)

View original on GitHub ↗

This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗