subprocess.run(cmd, shell=True, timeout=1) raises TimeoutExpired but kills only /bin/sh, so whatever the shell started keeps running; start the command with start_new_session=True and call os.killpg(p.pid, signal.SIGKILL) on timeout instead. In my test, ten agent tool calls that each timed out after 1 s left 10 live processes behind, and a background server made a command that printed started instantly block for 5.01 s and then survive the timeout.
This story was written with the assistance of an AI writing program. All numbers come from Python 3.14.4 on Linux 7.0 with dash as /bin/sh and systemd 259; every case ran twice with the same counts.
If you give an LLM agent a shell tool, the timeout is your only brake on what the model runs. subprocess.run makes that brake look solid: the call returns on time and raises the right exception. The process tree underneath is a different story, and nothing in the return value tells you.
What the timeout actually kills
CPython's run() is short. On timeout it does this:
except TimeoutExpired as exc: process.kill() ... process.wait() raise process is the Popen for /bin/sh -c "<cmd>". kill() sends SIGKILL to that one PID. On this box dash did not exec the last command, so even a single python3 -c ... ran as a child of the shell. When the shell dies, the child is reparented, here to PID 1500, which is systemd --user acting as subreaper, and it keeps going.
I checked with ps right after the exception: the parent shell was gone, and the worker sat there with PPID 1500 and its 30-second sleep untouched.
Five cases, one table
Each case starts a tagged python3 -c 'time.sleep(N)' through shell=True and counts survivors with pgrep -f <tag> 0.3 s after run() returns. From the first run:
bg server, capture, timeout=5 after= 5.01s error=TimeoutExpired rc=None survivors=1 bg 8s job, capture, no timeout after= 8.03s error=none rc=0 survivors=0 bg server, >/dev/null, timeout=5 after= 0.00s error=none rc=0 survivors=1 fg 30s chain, capture, timeout=2 after= 2.00s error=TimeoutExpired rc=None survivors=1 10 agent calls, timeout=1 after=10.33s timeouts=10 survivors=10 The foreground line is the plain leak: sleep 30; echo done timed out at 2.00 s and the sleep lived on. A pipeline (cmd | cat) and a single bare command behaved the same, one survivor each. The agent line is the same leak in a loop. A model that retries a slow command ten times does not get ten failures; it gets ten copies still running.
The background server that hung the tool
The first two lines surprised me more. The command was server & echo started. The shell printed started and exited at once, yet run() blocked for 5.01 s and raised TimeoutExpired, and the server survived.
The reason is the pipe. With capture_output=True, the background child inherits the write end of stdout. communicate() reads until EOF, and EOF only comes when every process holding that pipe has closed it. The shell is done; the server is not. Without a timeout, an 8-second background job made the call take 8.03 s for a command whose shell finished instantly.
Redirecting the server's output (>/dev/null 2>&1 &) returned in 0.00 s with exit code 0. That is the honest version of "start a server": the tool returns, and the server keeps running because you asked it to. The failure is the version in between, where the agent thinks the call failed and the server is still bound to its port.
The fix I kept
Put the shell in its own session, so its PID is also a process group ID, and kill the group:
import os import signal import subprocess def run_tool(cmd: str, timeout: float) -> tuple[int | None, str]: p = subprocess.Popen(cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, start_new_session=True) try: out, _ = p.communicate(timeout=timeout) return p.returncode, out except subprocess.TimeoutExpired: os.killpg(p.pid, signal.SIGKILL) # the shell and everything still in its group try: out, _ = p.communicate(timeout=1) except subprocess.TimeoutExpired: # a child escaped with setsid and holds the pipe p.stdout.close() p.wait() out = "" return None, out + f"\n[killed after {timeout}s]" I ran this function as written against the same commands. The foreground chain and the pipeline returned at 2.00–2.01 s, the background server at 5.01 s, and all three left 0 survivors. A fast echo returned rc 0 with its output. The second run matched.
Where killpg stops working
A process group is voluntary. A child that calls setsid leaves it. With setsid python3 -c ...; echo done, my first version of the fix (without the bounded drain) killed the group and then waited on communicate() for the full 30 seconds, because the escaped child still held the pipe. The bounded drain above returns at 3.00 s, but the escaped process is still alive afterwards: 1 survivor.
The only thing I found that caught it was a cgroup. Wrapping the command in systemd-run --user --scope and calling systemctl --user kill --signal=SIGKILL <unit>.scope on timeout ended the call about 2.0 s in, with 0 survivors, setsid included. A container per tool call gets you the same thing. For an agent shell, I treat killpg as the default and a scope or container as the boundary when the model can run arbitrary commands.
Takeaways
-
subprocess.run(..., shell=True, timeout=N)kills the shell, not the command. Check survivors withpgrep, not the exception. -
capture_output=Trueplus a background&blocks until the background process exits or the timeout fires. - Use
start_new_session=Trueandos.killpgon timeout, and bound the secondcommunicate(). -
setsidescapes a process group; a cgroup (systemd-run --scope) or container does not leak. - For agent tools, a timeout that returns on time is not proof that the work stopped.



