Cursor Agent Mode: Tool Call Stuck Pending (Fix)

Q: Why does every single terminal command hang, even `ls`?

Almost always your shell startup file (`.zshrc` / `.bashrc`) loading an interactive theme or plugin that breaks completion detection. Apply the `CURSOR_AGENT` guard clause in Step 3.

Q: What's the difference between Stop, Skip, and Move to background?

**Stop** signals the model to stop generating (it won't kill a hung shell). **Skip** abandons the stuck command and lets the agent continue. **Move to background** keeps the command running detached while the agent proceeds.

Cursor agent shows a spinner forever on a tool call. Nine times out of ten it is a shell command waiting on input — most often your own .zshrc. Here is the fast fix and the full diagnosis.

Published: May 23, 2026 Updated: Jun 18, 2026 Author: AI Productivity Guide Team 🌐 查看中文版本

Cursor’s agent runs a tool call and the UI shows a spinner that never resolves. The “Stop” button does nothing, the chat is frozen, and sending a new message just queues behind the dead call. Underneath that spinner is almost always one of four things: a shell command waiting for input you can’t see (usually triggered by your own .zshrc / .bashrc), a network request blocked by a firewall or VPN, a permission decision that scrolled off screen, or a long command that hasn’t finished yet.

Fastest fix: hover the stuck terminal block and click Move to background (or Skip). If those aren’t there, press Reload Window (Cmd/Ctrl+R). Then read on, because if it keeps happening the root cause is usually a slow or interactive shell startup file — and there’s a one-line fix for that.

None of these are solved by waiting longer. This article walks the diagnosis and the cleanest way to break the deadlock without losing chat history. (Settings paths and version behavior below are current as of June 2026, with Auto-review the default run mode.)

30-second decision aid

What you see	Most likely cause	Jump to
Terminal block spins, you ran an editor/`-i` command	Interactive command, no TTY	Cause 1 / Step 2
Every terminal command hangs, even `ls`	Slow/interactive shell startup (`.zshrc`)	Cause 2 / Step 3
`web_search` / `fetch` spins, terminal is fine	Network blocked (VPN/proxy/firewall)	Cause 3 / Step 4
Spinner but no buttons, chat fully frozen	Permission prompt missed, or renderer hung	Cause 4 / Step 5
`mcp_<name>` call spins forever	Broken/timeout-less MCP server	Cause 6 / Step 6

Common causes

1. Shell command is waiting for interactive input

The agent ran git rebase -i, npm init (without -y), gh auth login, or anything that opens a pager (git log, less) — commands that pause for input. The agent terminal is a non-interactive shell with no TTY for you to type into, so the process sits forever. A telltale sign: Cursor offers a Pop out terminal button, and after you pop it out you can see a half-drawn editor or a (END) pager prompt waiting.

How to judge: open a real terminal and run ps aux | grep <command>. If the process is there with state S+ and its parent is Cursor, that’s the hang.

2. Your shell startup file hangs the agent terminal (most common)

This is the cause most people never find. The agent runs each command in a fresh login shell that sources ~/.zshrc (or ~/.bashrc). If that file loads an interactive prompt theme (Powerlevel10k, Oh My Zsh plugins, nvm auto-use, conda init, anything that prints to the terminal or waits), Cursor can’t reliably detect when the actual command finished. Result: even a trivial ls spins, or every command hangs after it prints output. Reports of this spiked after Cursor’s terminal rework and it’s still common as of June 2026.

The agent sets distinctive environment variables that a normal interactive shell never sees, so you can detect and skip the heavy startup. As of June 2026 the reliable markers inside the integrated agent terminal are:

PAGER=head -n 10000 | cat
COMPOSER_NO_INTERACTION=1
PIP_NO_INPUT=true
CURSOR_AGENT (set in cloud/background and CLI agents; not always present in the integrated terminal, so don’t rely on it alone)
CURSOR_SANDBOX, CURSOR_ORIG_UID, CURSOR_ORIG_GID (injected into sandboxed child processes, per Cursor’s terminal docs)

How to judge: in a real terminal, time your startup: time zsh -i -c exit. If it’s over ~0.5s, or if commands hang only inside Cursor but not in a normal terminal, your startup file is the culprit. Fix is in Step 3.

3. Tool call is blocked by network

The agent called web_search or fetch to a domain your VPN, firewall, or corporate proxy blocks. The request never completes and never errors — it just sits.

How to judge: open Cursor’s developer tools (Help > Toggle Developer Tools > Network tab). You’ll see a pending request stuck on a domain you can’t reach.

4. Permission prompt was dismissed or missed

Even with Auto-review (Cursor 3.6+, the default run mode as of June 2026), some calls fall through to a manual decision: a command that can’t be sandboxed and isn’t on your allowlist gets surfaced to you. If you scrolled past or clicked outside that dialog, the agent waits for a decision it never gets.

How to judge: scroll the chat all the way down — is there a faded Run / Skip / Add to allowlist prompt you forgot to answer?

5. Long-running command (build / install) that legitimately takes minutes

npm install on a fresh node_modules can take 3-5 minutes; cargo build --release on a big crate can take 10+. The agent shows “running” with no progress bar. Note the opposite failure also exists: as of June 2026 Cursor applies its own timeout to foreground terminal commands and decides when to stop them, and across versions users have reported it cutting commands off early (some builds report being killed in tens of seconds). So a genuinely long build may get force-stopped, not just appear stuck. Either way the fix is the same — run it detached (Step 7).

How to judge: open a real terminal, run the same command. If it also takes 5 minutes there, the agent isn’t stuck — it’s slow, and you should run it in the background (Step 7).

6. MCP server has no timeout

If the hang is on an mcp_<name> tool, the MCP server itself is usually the problem — most commonly one that spawns a subprocess on every call with no timeout, so a single bad call blocks the whole agent.

How to judge: expand the tool call; if it’s mcp_<something> and the same MCP server worked yesterday, restart Cursor and test that server in isolation.

7. Cursor renderer / process is genuinely hung

A bug in agent mode, a memory spike, or a locked Electron renderer. The Stop button doesn’t respond and CPU stays flat at 0% (a live process shows some activity).

How to judge: Activity Monitor / Task Manager — a Cursor helper process at 0% CPU with no I/O is a likely hang. Fix: Step 5.

Before you start

Note which kind of tool call is stuck (terminal, file edit, web search, MCP) — the fix differs.
Don’t click Stop repeatedly. Stop signals the model to stop generating; it won’t kill a hung shell process.
The chat is saved to disk per project, so reloading or restarting won’t lose it.

Information to collect

The exact tool call name and parameters shown in the chat (click the tool-call header to expand).
Roughly how long the spinner has been spinning.
Cursor version (Cursor > About Cursor).
Any VPN / proxy / firewall in use.
Output of ps aux | grep -i cursor on macOS / Linux, or Task Manager on Windows.
Help > Toggle Developer Tools > Console errors.

Step-by-step fix

Step 1: Identify what kind of tool call is stuck

In the chat, expand the pending tool call. Common types:

run_terminal_cmd — shell command in Cursor’s integrated terminal.
web_search / fetch — network request.
edit_file / read_file — file system operation.
mcp_<name> — Model Context Protocol tool.

The hang pattern differs for each, so match it to a cause in the table above.

Step 2: Move to background, Skip, or Pop out the terminal

For a stuck terminal call, the buttons on the terminal block are your fastest exit:

Move to background — releases the agent to keep going while the command runs detached. Use this for a real long build.
Skip — abandons the command and lets the agent proceed. Use this when the command is hung on input.
Pop out terminal — opens the command in a real interactive terminal so you can see (and answer) whatever it’s waiting on, or press Ctrl+C / Enter to break it.

If clicking those does nothing, kill the underlying process directly.

On macOS / Linux:

ps aux | grep -E "node|npm|cargo|git" | grep -v grep
kill -TERM <pid>
# If TERM does not work in 5 seconds:
kill -KILL <pid>

On Windows (PowerShell):

Get-Process | Where-Object {$_.ProcessName -match "node|npm|cargo"} | Stop-Process

Once the underlying process dies, Cursor usually receives the close event within ~30 seconds and the spinner clears.

Step 3: The .zshrc / .bashrc fix (for recurring terminal hangs)

If every terminal command hangs — even ls — your shell startup file is interfering with Cursor’s completion detection. Add a guard clause at the very top of ~/.zshrc (or ~/.bashrc) so the agent shell skips the heavy interactive setup. This matches the community-verified fix on Cursor’s forum:

# Skip interactive shell init inside Cursor's agent terminal
if [[ "$PAGER" == "head -n 10000 | cat" || "$COMPOSER_NO_INTERACTION" == "1" ]]; then
  return
fi

Those two markers are the reliable ones inside the integrated agent terminal as of June 2026 (CURSOR_AGENT is set in CLI/cloud/background agents but not always in the integrated terminal, so don’t gate on it alone). To also cover VS Code-style integrated terminals:

if [[ "$TERM_PROGRAM" == "vscode" || "$TERM_PROGRAM" == "cursor" ]]; then
  return
fi

This skips loading the rest of your config only inside the agent shell. Your interactive terminal (Ctrl+`), iTerm, and Terminal.app keep full Oh My Zsh / Powerlevel10k behavior.

If you want Powerlevel10k to keep working everywhere and only fix completion detection, the lighter alternative is to source Cursor’s shell integration instead of bailing out — let your config load fully, but make sure the agent can still detect when a command ends. Bailing out early (the return above) is the simplest reliable fix; the shell-integration route is for people who refuse to lose their prompt theme inside the agent terminal.

On Windows, if commands hang in PowerShell or Cmd, switch the agent’s terminal profile to Git Bash — several users report that alone fixes it.

Step 4: For stuck network calls, check connectivity and bypass

Open a real terminal:

curl -v https://api.cursor.sh/ 2>&1 | head -20
curl -v https://api.openai.com/ 2>&1 | head -20

If either hangs or fails:

Disable your VPN temporarily and retest.
Check for a corporate proxy: echo $HTTP_PROXY $HTTPS_PROXY.
Allowlist Cursor’s domains in your firewall: *.cursor.sh, api.anthropic.com, api.openai.com.

Step 5: Reload the window without losing chat

Cursor menu > Developer > Reload Window (Cmd/Ctrl+R). This restarts the renderer process but keeps your chat history on disk, so the pending tool call clears and you can retry.

If Reload Window also hangs:

Force-quit Cursor entirely.
Reopen Cursor.
Open the same project; the chat sidebar should still show your previous conversation.

Step 6: Disable the problematic MCP server

If the hang is on an mcp_<name> tool, the MCP server itself may be broken:

# Project-scoped config:
cat .cursor/mcp.json
# Global config:
cat ~/.cursor/mcp.json

Comment out the suspect server (or toggle it off in Cursor Settings > MCP & Integrations), restart Cursor, and retry. The usual culprit is an MCP server that spawns a subprocess on every call without a timeout.

Step 7: Run long commands in the background

For commands you know take minutes (npm install, cargo build), tell the agent up front to run them detached so it never blocks:

Run `npm install` in the background and check back in 60 seconds.
Do not block on the install output.

The agent’s terminal tool supports a background mode (the same thing the Move to background button does), so it won’t wait for the command to finish before continuing.

How to confirm it’s fixed

Open a fresh chat and re-run the same prompt — it should complete normally.
Run a known-fast tool call (ls, a simple file read) to confirm tool calls work in general.
If the cause was a terminal hang, time your shell again: time zsh -i -c exit should now be fast, and a one-off echo ok in agent mode should return instantly.
Check Help > Toggle Developer Tools > Console for clean output with no pending promises.
If an MCP server was involved, run a single manual call to it and confirm it returns.

Long-term prevention

Add the CURSOR_AGENT guard clause to your shell startup file (Step 3) — this prevents the single most common recurring hang.
Never ask the agent to run interactive commands (git rebase -i, vim, nano, npm init without -y); use non-interactive equivalents and pipe pagers to cat.
Configure long-running commands to run in the background from the start.
Watch the Run / Skip / Add to allowlist prompt after each turn — under Auto-review most calls run automatically, but the ones that fall through pause silently if you don’t answer.
Give your own MCP servers a 5-minute timeout; an infinite default is the most common MCP hang cause.
Update Cursor regularly; agent timeout and cancel bugs are actively being fixed.

Common pitfalls

Closing the chat tab while a tool call is pending — the underlying process keeps running and can lock the next chat.
Force-quitting Cursor without killing child processes first; orphaned node / npm processes hold ports and confuse the next session.
Running multiple agent chats in parallel; tool-call queues can deadlock if both touch the same file.
Approving one prompt then walking away — the agent may still be waiting on a follow-up confirmation.
Assuming Auto-run sandbox is a safety boundary; per Cursor’s own docs it’s a best-effort convenience feature, not a security guarantee.

FAQ

Q: Does Cursor have a built-in tool-call timeout? A: Network calls time out (around 120s). Foreground terminal commands have a soft limit too — they generally get stopped around the 10-minute mark as of June 2026, and some shorter commands hit a ~30s wait — but a truly hung shell can sit past that, so kill it yourself or click Skip.

Q: Why does every single terminal command hang, even ls? A: Almost always your shell startup file (.zshrc / .bashrc) loading an interactive theme or plugin that breaks completion detection. Apply the CURSOR_AGENT guard clause in Step 3.

Q: Will Reload Window lose my chat? A: No. Chats are persisted to disk per project; Reload Window only restarts the renderer.

Q: What’s the difference between Stop, Skip, and Move to background? A: Stop signals the model to stop generating (it won’t kill a hung shell). Skip abandons the stuck command and lets the agent continue. Move to background keeps the command running detached while the agent proceeds.

Q: Can I see exactly what command the agent ran? A: Yes — click the tool-call header in chat to expand its parameters and stdout.

Tags: #Cursor #ide #Troubleshooting