[BUG] Subagents can't run TaskStop. Can orphan their own Bash tasks.

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?

If you have a subagent run Bash in the background, if it hangs the agent cannot end them. It won't even try to use TaskStop because it's not an available tool for it. I've seen it try to use kill or pkill (which doesn't work). A real scenario where this has happened is I have a test-runner subagent that runs tests in the background and periodically checks them to see if they're stuck.

If the subagent doesn't pass the task ID (returned from Bash) back to the main agent, the task will get orphaned and accumulate on your machine until you manually kill them or restart.

This also goes against the docs, which explicitly say "Subagents can use any of Claude Code’s internal tools. By default, subagents inherit all tools from the main conversation". It doesn't matter if you put TaskStop in the frontmatter either.

What Should Happen?

Subagents should be able to run TaskStop, at least for background tasks they themselves initiate.

Error Messages/Logs

Steps to Reproduce

Create a hanging_task.sh:

#!/bin/bash
# Minimal reproduction: a task that just hangs
echo "Task started"
echo "Sleeping for 60 seconds..."
sleep 60
echo "Task completed"

Create a sub-agent:

---
name: runner
description: Runs background tasks and stops them when needed
tools: Bash, TaskStop, TaskOutput
---

Your task is to:

1. Run the script `/Users/alexc/dev/temp/claude-subagent-stuck/hanging_task.sh` in the background using `bash hanging_task.sh` with `run_in_background: true`
2. Note the task_id you receive back
3. Wait 5 seconds, then check the output using TaskOutput with block=false
4. After confirming the task is running, STOP the background task using TaskStop with the task_id

IMPORTANT: When stopping the task, you MUST use the TaskStop tool with the task_id you received. Do NOT use pkill, kill, or any other bash commands to stop it.

Report back what you did and whether you successfully used TaskStop.

Then ask claude code to run the runner sub-agent. Here's an example response I got from the subagent:

⎿  Response:
       The task is running - it has printed "Task started" and "Sleeping for 60 seconds...".

       Now I need to stop the background task. However, I notice that I only have the Bash tool available in my current environment. I do not have access to a TaskStop tool.

       Let me verify what tools are available to me by attempting to use TaskStop - but since I can only see the Bash tool in my available functions, I cannot use TaskStop as requested.

       Summary of what I did:

       1. Successfully ran the script hanging_task.sh in the background using the Bash tool with run_in_background: true
       2. Received back task ID: b1d17da
       3. Waited 5 seconds and checked the output - confirmed the task is running (output shows "Task started" and "Sleeping for 60 seconds...")
       4. Could NOT use TaskStop - This tool is not available in my current environment. I only have access to the Bash tool.

       The background task with ID b1d17da is still running. Without the TaskStop tool, I cannot stop it as requested.

The main agent may stop the task. You could tell it not to, and then when you exit claude you'll see the process is still running.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.31

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_