[BUG] Background processes not cleaned up on session exit, causing "file in use" errors on app update

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Summary

Background shell tasks started via Claude Code (Bash tool, run_in_background: true) are not reliably terminated when a session ends or Claude Desktop is closed. Orphaned processes accumulate over time and eventually block Claude Desktop's self-update, failing with "Another process is currently using this file." A full computer restart is currently the only way to clear it.

Environment

• Claude Desktop on Windows 11
• Issue recurring for several days before this report

Evidence observed in one session

• Started several background tasks (a Python/uvicorn server, git clone, npm install/build) via the Bash tool with run_in_background: true.
• Called the tool to stop a tracked background task (equivalent of TaskStop); the task showed as stopped.
• Later, while trying to delete the project folder that task had been running in, deletion of the (by-then-empty) directory itself failed with "Cannot remove the item ... because it is in use" — even after every file inside had been successfully deleted.
• Get-CimInstance Win32_Process showed multiple bash.exe processes chained parent→child (4-5 levels deep) with command lines matching Claude Code's shell-snapshot wrapper, unrelated to any task I was actively running.
• Received two separate system notifications for background tasks reading: "No completion record was found for this background shell command from the previous session. It may have been stopped ... or it may have been running when the previous Claude Code process exited."
• Shortly after, attempting to update Claude Desktop failed repeatedly with "Another process is currently using this file." Restarting the computer (which force-kills all orphaned processes) resolved it.

Suspected root cause

When a Claude Code session ends (normally or via app close/crash/update), background processes it spawned (and their child processes) are not always terminated. These orphaned processes keep running and holding file/directory handles, which can collide with the updater's need to replace files on disk.

Suggested fix

Ensure Claude Code terminates the full process tree of every background task (not just the tracked wrapper shell) when a session ends, and especially before/during an app update or close.

What Should Happen?

Background processes (and their full child-process tree) spawned by a Claude Code session should be fully terminated when that session ends — whether the session closes normally, the app is closed, or Claude Desktop restarts for an update. No orphaned bash.exe/python.exe/server processes should remain running afterward, and Claude Desktop should be able to update itself without hitting file locks left behind by prior sessions.

Error Messages/Logs

Steps to Reproduce

Note: this is a cumulative/intermittent issue rather than a single deterministic repro — it builds up from normal background-task usage over a session or across several days. Steps below show both the leak itself and how it eventually surfaces as an update failure.

1. In Claude Code, run several tasks with run_in_background: true — e.g. start a local dev/API server, run a git clone, run npm install/npm run build.
2. For at least one of them, explicitly stop it via Claude Code's "stop background task" action (equivalent of TaskStop). The tool reports it as stopped.
3. Try to delete or rename the directory that background task was working in.

→ Expected: succeeds immediately.
→ Actual: deletion of files inside succeeds, but the (now-empty) directory itself fails to delete with "Cannot remove the item ... because it is in use," even though the tracked task shows as stopped.

1. Inspect running processes (e.g. Get-CimInstance Win32_Process in PowerShell) filtered to bash.exe / python.exe / any server process you started.

→ Observe multiple chained processes (parent→child, several levels deep) still running, with no active task in Claude Code corresponding to them.

1. Close Claude Desktop entirely (not just the session) and reopen it, or start a new session.

→ Observe a system notification for a previous background task reading: "No completion record was found for this background shell command from the previous session. It may have been stopped ... or it may have been running when the previous Claude Code process exited."

1. Repeat this pattern of background-task usage over normal day-to-day work for a few days without a full computer restart in between.
2. Attempt to update Claude Desktop.

→ Update fails repeatedly with "Another process is currently using this file."

1. Restart the computer (force-terminates all orphaned processes) → update then succeeds.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

1.32885.1

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_