Try free

Last updated 13 October 2026

How to cancel a running Claude Code subagent

The Escape key as a primary brake

The Escape key provides the fastest way to interrupt a subagent when it starts behaving unexpectedly in Claude Code. When you see the terminal outputting file changes or shell commands that do not match your intent, press Escape once. This signal tells the agent to halt the current tool execution, whether it is a long running Bash command or an Edit operation across multiple lines. The agent will usually stop its current sequence and wait for your next input.

After you press Escape, the agent often provides a short summary of what it was attempting to do. It might also ask for clarification on why the process was stopped. This immediate feedback loop is essential for saving tokens and preventing the agent from making unnecessary changes to your repository. It allows you to correct the course of the conversation before the subagent proceeds further down a wrong path.

Stepping back in time with double Escape

If a subagent has already made several mistakes before you could stop it, you can use a double press of the Escape key. This action opens a history navigation menu within the Claude Code interface. It allows you to scroll back through previous messages and tool outputs to find a point where the session was still on track. By selecting an earlier state, you effectively rewind the entire conversation and remove the faulty logic from the agent context.

This rewind feature is more powerful than a simple undo because it also reverts the internal state of the agent. It clears the memory of the failed subagent task so that it does not influence future suggestions. This is particularly useful when a subagent creates a series of dependencies or temporary files that would be difficult to clean up manually. Returning to a known good state ensures your development environment remains consistent and predictable.

Forcing a hard exit with terminal commands

In situations where the interactive interface does not respond to the Escape key, you can use Ctrl+C to force the session to quit. This is a standard terminal command that terminates the Claude Code process and all its active subagents immediately. While this is a more abrupt method than using the built-in interrupt, it is a reliable way to stop a runaway process that might be consuming excessive CPU or memory on your machine.

After quitting with Ctrl+C, you can return to your work by typing claude --continue or claude -c in the same directory. This command resumes the most recent session. If you need to go back to a specific older session instead, use claude --resume or claude -r to see a list of available session IDs. These commands ensure that even if you have to kill the process, you do not lose the progress you made before the subagent went off track.

Controlling subagents with permission modes

Changing the permission mode is another way to manage subagents and prevent them from running tasks without your oversight. You can use Shift+Tab to cycle through modes like default, acceptEdits, plan, and bypassPermissions. If you switch to plan mode, the subagent will outline its intended actions without executing any tools. This gives you a chance to review the logic and cancel the task if the proposed plan does not meet your requirements.

The plan mode is a safe environment for exploring complex changes where you are not yet sure of the outcome. If you decide the subagent is heading in the right direction, you can switch back to default or acceptEdits to let it proceed. If the plan is flawed, you can simply provide a new prompt to redirect the agent. This proactive approach reduces the need for emergency interruptions because you are verifying the work before it happens.

Cleaning the environment after a cancellation

After you cancel a subagent, you might want to clean up the conversation to prevent old errors from cluttering the context window. The /clear command is designed for this purpose. It restarts the session in the same folder but wipes the previous exchange. This is helpful when a subagent run was so messy that you would rather start from a blank slate than try to fix the existing conversation.

If you want to keep the history but need more space for new tasks, use the /compact command. This command summarizes the session so far and removes the raw tool outputs, which often take up a lot of context space. By summarizing the failed subagent run, you keep the lessons learned without the baggage of every single line of code that was read or written. This keeps the agent efficient and focused on the next task you assign.

Managing multiple subagent tasks with adhdTerminal

When managing multiple coding tasks across different repositories, keeping track of every subagent can be difficult. This is a practical problem that adhdTerminal solves for developers on macOS and Windows. The app, made by MINDBALANCER OU in Estonia and not affiliated with Anthropic, runs many Claude Code sessions side by side, presenting each one as a tile on a wall. A tile has a colour, a number and a name, shows whether it is working, waiting for you, done or idle, shows the last exchanges of its conversation, and can show numbers and headlines the project publishes.

If a subagent in one tile starts producing strange output, you can see the last exchanges of its conversation directly on the tile without having to switch terminal tabs. Tiles reopen in the same place after a restart and resume the same session. A free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task. It costs 99 dollars once, one key runs one computer at a time and can be moved, with a 7 day free trial and no account. This visual overview allows you to monitor for runaway processes across your entire project list. You can quickly jump into any session to hit the Escape key if a subagent needs to be stopped.

Using hooks to automate subagent stops

Claude Code supports hook events that trigger at specific points in the lifecycle of a task. You can use the SubagentStop and Stop hooks to run custom scripts or notifications when an agent finishes or is interrupted. While these do not cancel the subagent themselves, they provide a way to clean up temporary files or reset environment variables that a subagent might have left behind after you hit Escape.

These hooks are defined in your configuration and allow for a more disciplined development workflow. For example, a PostToolUse hook could check for certain conditions and alert you if a subagent is performing too many Write operations in a short period. This acts as an automated monitoring system that complements your manual control over the subagent execution.

Configuring subagent behavior in settings files

Your configuration files are the best place to set limits on subagent behavior before you ever have to hit the cancel key. You can define specific permissions in .claude/settings.json or ~/.claude/settings.json. For instance, you can set the permissions for the Bash or WebSearch tools to require manual approval for every call. This ensures that no subagent can run a shell script or fetch external data without you seeing it first.

If you are working on a specific part of a repository, you can create a CLAUDE.md file in that subdirectory to give the subagent more localized instructions. This can include warnings about which files it should never touch or which tools it should avoid using. By providing clear boundaries in your project documentation and settings, you make it much less likely that a subagent will start a task that eventually requires a manual stop.

Identifying runaway subagents via status commands

Monitoring the agent status is a good habit to develop if you want to catch runaway subagents early. Use the /status command to see the current state of the agent and its pending tasks. If the status reveals a long list of unnecessary Glob or Grep operations, it is a clear sign that the subagent has lost its way and needs to be interrupted. You can also use /cost and /usage to monitor the financial impact of a subagent run.

If you notice the costs rising faster than the progress warrants, use the Escape key to stop the subagent and review your instructions. Sometimes a small change in the prompt can prevent a subagent from entering a costly and unproductive loop. Regularly checking the /status and tool output ensures that you remain the pilot of the coding process, while the subagent remains an assistant that you can dismiss or redirect as needed.

Questions people ask

What happens to my files if I interrupt an Edit tool?

When you press Escape to stop an Edit tool, Claude Code usually stops writing to the file immediately. Depending on how much was already written, the file might be in a partially edited state. You should review the file manually or use the double Escape shortcut to rewind the session and undo those changes.

Can I resume a subagent after pressing Escape?

Once you press Escape, the subagent stops its current task and returns control to you. You cannot directly resume the exact same tool execution from where it left off. However, you can give a new prompt to the agent asking it to continue the work or finish what it started, and it will try to pick up the task using its current context.

How do I prevent subagents from starting in the first place?

You can prevent subagents from executing tools by using the plan permission mode. Press Shift+Tab until you reach the plan mode before submitting your prompt. This forces the agent to describe its intended steps without actually starting any subagents or modifying your files, giving you full control over the initiation of the task.

Read next

More on claude code basics·All posts