🤖 feat: add polling detection to bash_output tool (#1098)

When agents call `bash_output` 3+ times on a running process without
using `filter_exclude`, return a note instructing them to use
`filter_exclude` with a longer timeout instead of polling repeatedly.

## Changes

- Track `getOutputCallCount` per background process
- Return a `note` field with guidance when polling detected (3+ calls,
no filter_exclude, process still running)
- Simplified tool description (runtime now handles the guidance
dynamically)

## Example note returned

```
STOP POLLING. You've called bash_output 3+ times on this process. This wastes tokens and clutters the conversation. Instead, make ONE call with: filter='⏳|progress|waiting|\.\.\.', filter_exclude=true, timeout_secs=120. This blocks until meaningful output arrives.
```

## Tests

Added 3 tests covering:
1. Note appears after 3+ calls without filter_exclude on running process
2. Note does NOT appear when filter_exclude is used  
3. Note does NOT appear when process has exited

_Generated with `mux`_

Author: ammar-agent

src/common/utils/tools/toolDefinitions.ts

@@ -244,8 +244,7 @@ export const TOOL_DEFINITIONS = {
       "Returns stdout and stderr output along with process status. " +
       "Supports optional regex filtering to show only lines matching a pattern. " +
       "WARNING: When using filter, non-matching lines are permanently discarded. " +
-      "Use timeout to wait for output instead of polling repeatedly. " +
-      "If you've called this 3+ times on the same process, use filter_exclude with a longer timeout instead.",
+      "Use timeout to wait for output instead of polling repeatedly.",
     schema: z.object({
       process_id: z.string().describe("The ID of the background process to retrieve output from"),
       filter: z

src/node/services/backgroundProcessManager.test.ts

@@ -870,4 +870,80 @@ describe("BackgroundProcessManager", () => {
       expect(exitCodeContent.trim()).toBe("42");
     });
   });
+
+  describe("polling detection", () => {
+    it("should return note after 3+ calls without filter_exclude on running process", async () => {
+      // Long-running process
+      const result = await manager.spawn(
+        runtime,
+        testWorkspaceId,
+        "while true; do echo 'tick'; sleep 0.5; done",
+        { cwd: process.cwd(), displayName: "test", timeoutSecs: 30 }
+      );
+
+      expect(result.success).toBe(true);
+      if (!result.success) return;
+
+      // First two calls should not have a note
+      const output1 = await manager.getOutput(result.processId, undefined, undefined, 0.1);
+      expect(output1.success).toBe(true);
+      if (!output1.success) return;
+      expect(output1.note).toBeUndefined();
+
+      const output2 = await manager.getOutput(result.processId, undefined, undefined, 0.1);
+      expect(output2.success).toBe(true);
+      if (!output2.success) return;
+      expect(output2.note).toBeUndefined();
+
+      // Third call should have the suggestion note
+      const output3 = await manager.getOutput(result.processId, undefined, undefined, 0.1);
+      expect(output3.success).toBe(true);
+      if (!output3.success) return;
+      expect(output3.note).toContain("filter_exclude");
+      expect(output3.note).toContain("3+ times");
+    });
+
+    it("should NOT return note when filter_exclude is already used", async () => {
+      const result = await manager.spawn(
+        runtime,
+        testWorkspaceId,
+        "while true; do echo 'tick'; sleep 0.5; done",
+        { cwd: process.cwd(), displayName: "test", timeoutSecs: 30 }
+      );
+
+      expect(result.success).toBe(true);
+      if (!result.success) return;
+
+      // Make 3+ calls with filter_exclude
+      for (let i = 0; i < 4; i++) {
+        const output = await manager.getOutput(result.processId, "nomatch", true, 0.1);
+        expect(output.success).toBe(true);
+        if (!output.success) return;
+        // Should never get the note since we're using filter_exclude
+        expect(output.note).toBeUndefined();
+      }
+    });
+
+    it("should NOT return note when process has exited", async () => {
+      const result = await manager.spawn(runtime, testWorkspaceId, "echo done; exit 0", {
+        cwd: process.cwd(),
+        displayName: "test",
+      });
+
+      expect(result.success).toBe(true);
+      if (!result.success) return;
+
+      // Wait for process to exit
+      await new Promise((resolve) => setTimeout(resolve, 200));
+
+      // Make 3+ calls on exited process
+      for (let i = 0; i < 4; i++) {
+        const output = await manager.getOutput(result.processId, undefined, undefined, 0.1);
+        expect(output.success).toBe(true);
+        if (!output.success) return;
+        // Should not get note since process is not running
+        expect(output.note).toBeUndefined();
+      }
+    });
+  });
 });

src/node/services/backgroundProcessManager.ts

@@ -44,6 +44,8 @@ export interface BackgroundProcess {
   /** Mutex to serialize getOutput() calls (prevents race condition when
    * parallel tool calls read from same offset before position is updated) */
   outputLock: AsyncMutex;
+  /** Tracks how many times getOutput() has been called (for polling detection) */
+  getOutputCallCount: number;
 }
 
 /**
@@ -219,6 +221,7 @@ export class BackgroundProcessManager extends EventEmitter<BackgroundProcessMana
       isForeground: config.isForeground ?? false,
       outputBytesRead: 0,
       outputLock: new AsyncMutex(),
+      getOutputCallCount: 0,
     };
 
     // Store process in map
@@ -327,6 +330,7 @@ export class BackgroundProcessManager extends EventEmitter<BackgroundProcessMana
       isForeground: false, // Now in background
       outputBytesRead: 0,
       outputLock: new AsyncMutex(),
+      getOutputCallCount: 0,
     };
 
     // Store process in map
@@ -458,6 +462,7 @@ export class BackgroundProcessManager extends EventEmitter<BackgroundProcessMana
         output: string;
         exitCode?: number;
         elapsed_ms: number;
+        note?: string;
       }
     | { success: false; error: string }
   > {
@@ -481,8 +486,12 @@ export class BackgroundProcessManager extends EventEmitter<BackgroundProcessMana
     // the same offset before either updates the read position.
     await using _lock = await proc.outputLock.acquire();
 
+    // Track call count for polling detection
+    proc.getOutputCallCount++;
+    const callCount = proc.getOutputCallCount;
+
     log.debug(
-      `BackgroundProcessManager.getOutput: proc.outputDir=${proc.outputDir}, offset=${proc.outputBytesRead}`
+      `BackgroundProcessManager.getOutput: proc.outputDir=${proc.outputDir}, offset=${proc.outputBytesRead}, callCount=${callCount}`
     );
 
     // Pre-compile regex if filter is provided
@@ -564,6 +573,10 @@ export class BackgroundProcessManager extends EventEmitter<BackgroundProcessMana
 
     const filteredOutput = applyFilter(accumulatedRaw);
 
+    // Suggest filter_exclude if polling too frequently on a running process
+    const shouldSuggestFilterExclude =
+      callCount >= 3 && !filterExclude && currentStatus === "running";
+
     return {
       success: true,
       status: currentStatus,
@@ -573,6 +586,12 @@ export class BackgroundProcessManager extends EventEmitter<BackgroundProcessMana
           ? ((await this.getProcess(processId))?.exitCode ?? undefined)
           : undefined,
       elapsed_ms: Date.now() - startTime,
+      note: shouldSuggestFilterExclude
+        ? "STOP POLLING. You've called bash_output 3+ times on this process. " +
+          "This wastes tokens and clutters the conversation. " +
+          "Instead, make ONE call with: filter='⏳|progress|waiting|\\\\.\\\\.\\\\.', " +
+          "filter_exclude=true, timeout_secs=120. This blocks until meaningful output arrives."
+        : undefined,
     };
   }