[FEATURE] Add output mode options to BashOutput tool for incremental/stateful monitoring
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
- Performance: Reduces token usage when monitoring long-running processes
- Usability: Makes it practical to check on background tasks frequently without output duplication
- Clarity: Easier to spot new output vs. re-reading everything
- Documentation alignment: Makes actual behavior match the described behavior
- 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)
This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗