future.result(timeout=1) raises TimeoutError after one second, but the thread keeps running the call to the end, and future.cancel() returns False because the work already started; if a tool call must really stop, run it in a child process and terminate that process on timeout. In my test, four agent tool calls that each "timed out" after 1 s all ran their full 5 s, and the next 0.1 s call on the same pool waited 1.10 s for a free thread.
This story was written with the assistance of an AI writing program. All numbers come from CPython 3.14.4 on Linux 7.0, and both scripts ran twice with identical output.
Here is the version that actually stops the work. It is the code I now use for agent tools that wrap slow, uncooperative functions:
import multiprocessing as mp
import time
def tool(secs):
time.sleep(secs)
return "ok"
def run_tool(fn, *args, timeout):
ctx = mp.get_context("spawn")
with ctx.Pool(1) as pool:
res = pool.apply_async(fn, args)
return res.get(timeout=timeout) # leaving the with-block terminates the worker
The rest of this post is why the thread version cannot do this, and what it costs you when you try.
The setup
Yesterday I wrote about subprocess.run(timeout=1) leaving orphans behind. The same question applies one layer up. A lot of agent frameworks run tool functions in a ThreadPoolExecutor so the event loop stays free, then put a timeout on the future. I wanted to know what that timeout actually does.
The test is small: a tool that sleeps 5 seconds and records when it finishes, a pool with four workers, and four calls, each awaited with result(timeout=1). Then a fresh 0.1 s call on the same pool, then the asyncio equivalent, asyncio.wait_for(asyncio.to_thread(...), timeout=1).
What the output says
From the first run, unedited:
result(timeout=1): 4 TimeoutError by 4.00s, cancel()=False, running=4, threads=5
fresh 0.1s call on same pool returned after 1.10s
wait_for(to_thread, timeout=1): TimeoutError at 1.00s
asyncio.run returned at 8.10s
completed in background: [('call0', 5.0), ('call1', 5.0), ('call2', 5.0), ('call3', 5.0), ('fresh', 5.1), ('async', 8.1)]
Every timeout fired on schedule. None of them stopped anything. All four calls finished at 5.0 s and wrote their results into a list nobody was reading. If those calls had been sending emails or writing rows, all four side effects would have happened after the caller had already logged "tool timed out".
Why cancel() returns False
The concurrent.futures docs are honest about this: "If the call is currently being executed or finished running and cannot be cancelled then the method will return False." In other words, it removes queued work, nothing else. Python has no supported way to kill a thread. The timeout on result() is a timeout on your wait, not on the work.
That distinction is easy to miss because the exception type looks like a verdict. TimeoutError reads as "the call was stopped". It means "I stopped waiting".
The hidden cost: a saturated pool
The second line is the one that would hurt in production. After four timeouts the pool looked idle from the caller's side, but all four workers were still busy. A 0.1 s call submitted at that point sat in the queue until a worker came free at the 5 s mark and returned after 1.10 s.
Scale that up. An agent that retries a slow tool a few times can fill the pool with zombie calls, and then every fast tool queues behind them. Nothing errors. Latency just climbs, and the traces show "timeout" on the slow calls and "slow" on the fast ones, which points you at the wrong thing.
asyncio.wait_for has the same hole, plus one more
asyncio.wait_for(asyncio.to_thread(tool, 3), timeout=1) raised at 1.00 s, as advertised. The thread kept going. Then asyncio.run() itself did not return until 8.10 s, because on shutdown it waits for the default executor's threads to finish. So the "1 second" timeout turned into a 2 s stall at exit, well after the caller moved on. In a CLI agent that is the "why does it hang after printing the answer" bug.
Processes can actually be stopped
The fix at the top swaps the thread for a one-worker process pool. On timeout, leaving the with block calls terminate() on the worker, so the work really ends. Its output, twice:
TimeoutError at 1.04s, children left: 0
ok 0.16s
The price is about 0.15 s of spawn start-up per call and the usual pickling rules for arguments and results. For tools that call slow external code, that is cheap. For tools that are just HTTP requests, a better fix is a real timeout inside the call, such as an httpx timeout or asyncio.timeout around an async client, because cooperative cancellation never leaves a half-done write behind a killed process.
Takeaways
-
future.result(timeout=N)andasyncio.wait_for(to_thread(...))time out your wait, not the work. The function runs to completion. -
future.cancel()returnsFalseonce the call has started. Do not treat it as a kill switch. - Timed-out calls still hold pool workers, so fast calls queue behind them. Watch queue time, not only call time.
-
asyncio.run()waits for executor threads at exit, so a timed-out thread can stall shutdown. - If work must stop, put it in a process you can terminate, or give the call its own internal timeout.
Top comments (0)