[Bug]: /pause reports PAUSED while an ACP agent keeps executing tool calls

Summary

POST /api/conversations/{id}/pause flips execution_status to paused immediately, but an ACP-driven agent keeps executing tool calls for the rest of its turn. The reported state and the actual state of the workspace diverge for as long as the in-flight prompt() runs, which can be minutes or hours.

POST /interrupt stops the work as documented. The problem is specific to /pause.

Environment

• openhands-agent-server / openhands-sdk / openhands-tools 1.47.0, installed from PyPI
• Python 3.12.13, macOS (Apple Silicon), server bound to loopback
• Agent: ACPAgent, acp_server: claude-code, acp_command: ["npx","-y","--prefer-offline","@agentclientprotocol/claude-agent-acp@0.63.0"], acp_model: sonnet

Reproduction

Start a conversation whose task is a long sequence of separate tool calls, so progress is observable on disk independently of the API:

Do this strictly one step at a time, never in a loop, never batched.
For i from 1 to 40: run sh -c 'sleep 3; echo step-$i >> steps2.txt' as its own separate tool call, then continue to the next i.

Then, while it is running:

1. POST /api/conversations/{id}/pause
2. Poll GET /api/conversations/{id} and wc -l steps2.txt every 5 s for 40 s
3. POST /api/conversations/{id}/interrupt, poll again for 40 s

Observed

[ 16.1s] before pause: status=running lines=2
[ 16.1s] POST /pause -> 200; status now paused
[ 56.4s] [paused] 40s window: lines 2 -> 10 (grew=True)
         samples (status, lines): paused/3 paused/4 paused/5 paused/6
                                  paused/7 paused/8 paused/9 paused/10
[ 56.4s] POST /interrupt -> 200; status now paused
[ 96.7s] [interrupted] 40s window: lines 10 -> 10 (grew=False)
[ 96.7s] POST /run -> 200; status now running
[127.0s] [resumed] 30s window: lines 10 -> 15 (grew=True)

Eight more shell commands ran, each writing to the workspace, during 40 consecutive seconds in which the API reported paused.

In a separate run, POST /run against a conversation in this "paused but still working" state returned 409, so the server itself does not consider it stopped either.

Expected

Either of:

• /pause actually stops the ACP turn (e.g. by routing to ACP session/cancel, which OpenHands/OpenHands#15912 already assumes it does), or
• execution_status does not become paused until the in-flight prompt has actually stopped — a distinct transitional value such as pausing would make the divergence visible to clients.

Root cause

LocalConversation.pause() is cooperative at the run-loop step boundary, and says so:

The pause will take effect at the next iteration of the run loop (between agent steps).
Note: If called during an LLM completion, the pause will not take effect until the current LLM call completes.

For an LLM-direct agent, a "step" is one completion, so the window is short and bounded. For ACPAgent, one step is an entire prompt() call, inside which the external CLI may run an unbounded number of tool calls. pause() still sets execution_status = PAUSED and emits PauseEvent synchronously, so the status flips while the subprocess keeps going for the rest of the turn.

Impact

The reported paused state is not a safety property for ACP agents. Any orchestrator that gates on it — "pause the agent, then take an approval decision / touch a shared resource / inspect the workspace" — is operating on a workspace that is still being modified. We hit this while building an external scheduler on top of the Agent Server and had to map our Pause operation onto /interrupt instead.

Related

• OpenHands/OpenHands#15912 — Canvas-side pause/resume/cancel UI; states that /pause routes to ACP session/cancel, which does not match the behaviour measured here.
• #4829 — interrupt / steer / queue control plane for user messages. Related area, different problem (message delivery semantics rather than the state reported by /pause).
• #3327 — ACP lifecycle primitives (closed).

Happy to supply the full driver script or test other versions if useful.

Start with LocalConversation.pause() and the ACPAgent prompt() run-loop boundary, then reproduce the issue using the documented pause, status polling, and interrupt sequence. Trace when execution_status changes relative to the in-flight prompt; done means /pause no longer reports a settled paused state while ACP tool calls continue, with behavior covered by an appropriate regression test.