Background shell reminders persist after KillShell, causing context exhaustion

Resolved 💬 6 comments Opened Dec 7, 2025 by diegocconsolini Closed Feb 7, 2026

Bug Description

When a background shell is started with run_in_background: true and later killed with KillShell, the system continues to inject reminder messages on every single turn for the rest of the conversation. This rapidly exhausts context and makes long sessions unusable.

Steps to Reproduce

  1. Start a background shell:
{
  "command": "npm run dev",
  "run_in_background": true
}
  1. Receive response: Command running in background with ID: f0f238
  1. Kill the shell:
{
  "shell_id": "f0f238"
}
  1. Receive confirmation: Successfully killed shell: f0f238
  1. Bug: On every subsequent turn, system injects reminders like:
Shell f0f238 has new output available. Use BashOutput to retrieve it.

Impact

  • Context exhaustion: Each reminder adds ~150-200 chars per zombie shell
  • Accumulates rapidly: With multiple background shells, adds 1000+ chars per message
  • Cannot be cleared: No way to stop reminders without starting new conversation
  • Session unusable: Long debugging sessions become impossible

Root Cause Analysis

Investigated the issue thoroughly:

  1. Background shell state is stored in conversation context (JSONL file)
  2. KillShell kills the process but doesn't update conversation state
  3. Conversation is append-only - past entries cannot be modified
  4. Reminder system checks conversation history, finds backgroundTaskId, sends reminder
  5. Even though shell is dead, the historical reference triggers reminders forever

Evidence from Conversation Log

// Shell started
{"backgroundTaskId":"f0f238"}

// Shell killed (success)
{"message":"Successfully killed shell: f0f238","shell_id":"f0f238"}

// But reminders continue on EVERY turn after this

Expected Behavior

After KillShell succeeds:

  • No more reminders for that shell ID
  • Shell should be marked as terminated in tracking state
  • BashOutput for killed shell should return "Shell was terminated" not trigger reminders

Workarounds (None Effective)

| Attempted | Result |
|-----------|--------|
| KillShell | Process dies, reminders continue |
| fuser -k <port> | Process dies, reminders continue |
| Delete ~/.claude/shell-snapshots/* | No effect |
| Delete ~/.claude/session-env/* | No effect |
| Any settings change | No relevant setting exists |

Only fix: Start a completely new conversation (loses all context).

Suggested Fix

  1. Track killed shells in session state (not just conversation history)
  2. Before sending background shell reminders, check if shell was killed
  3. Or: Add a way to clear/acknowledge background shell notifications
  4. Or: Add setting to disable background shell reminders entirely

Environment

  • Claude Code version: 2.0.60
  • OS: Linux (WSL2)
  • Shell: bash

Severity

High - This makes background shells essentially unusable for any session longer than a few turns. The workaround in docs says "don't use background shells" but that defeats the purpose of having the feature.

View original on GitHub ↗

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