Stop hooks cause conversation to stall in 'Working' state after FinishAction

[xingyaoww]

Bug Description

When a user configures a Stop hook in .openhands/hooks.json, the conversation stalls in the "Working" state after the agent completes (FinishAction). The UI becomes unresponsive — pressing ESC shows "Pausing conversation this may take a few seconds" but never completes.

Steps to Reproduce

1. Configure a stop hook in ~/.openhands/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "python ~/.openhands/stop_hook.py",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

2. Start a conversation and send a message
3. Wait for the agent to respond with FinishAction
4. Observe the UI stays at "Working (Ns • ESC: pause)" with the counter increasing indefinitely

Root Cause Analysis

Two issues in how stop hooks interact with the SDK's run loop:

1. Python exit code 2 treated as "block" → infinite loop

The hook executor treats exit code 2 as "block the operation" (a hook protocol convention). However, Python itself exits with code 2 when it can't find a script file:

$ python /nonexistent.py
python3: can't open file '/nonexistent.py': [Errno 2] No such file or directory
$ echo $?
2

This means if the stop hook script doesn't exist (e.g., path issue, different environment), the hook executor interprets this as "deny the stop". The SDK run loop then:

1. Sets status back to RUNNING
2. Calls agent.step() → agent calls FinishAction again → FINISHED
3. Runs stop hook again → denied again → RUNNING
4. Repeats indefinitely (each iteration involves an LLM call)

2. Stop hooks run while holding the state lock → pause blocked

The SDK's run loop executes stop hooks inside with self._state: (holding the FIFO lock). This means:

• pause() cannot acquire the state lock while the hook runs (up to 30s timeout)
• ESC/pause is effectively blocked during hook execution
• Combined with the infinite loop above, the UI becomes permanently unresponsive

Expected Behavior

• Stop hooks should run without blocking the ability to pause
• A failed/errored stop hook should NOT prevent the conversation from finishing
• Exit code 2 from a missing script should be treated as an error, not a block

Proposed Fix

Strip stop hooks from the HookConfig before passing to the SDK's Conversation, and handle them at the CLI/TUI level after conversation.run() returns. This avoids the state lock issue and gives the CLI control over error handling.

Environment

• CLI version: 1.14.0
• SDK version: 1.16.1
• Issue introduced by SDK bump from 1.11.5 → 1.16.x (which added stop hook handling in the run loop)

This issue was created by an AI assistant (OpenHands) on behalf of the user.

[xingyaoww]

Update: Root Cause Confirmed by Reporter

The reporter (Adrian Tineo) has confirmed the root cause:

I was running the CLI inside the OpenHands SDK repo, which I have checked out. I regularly run the OpenHands CLI there to help me with questions around SDK usage. So the stop hook it invokes is the local one inside the repo, at .openhands/. I am not sure what it does but it hangs and stalls the conversation.

This doesn't happen in other projects, where there's no additional stop hook.

The Specific Hook

The hook causing the stall is the SDK's own on_stop.sh, which:

1. Runs pre-commit run --all-files — can take a long time and fail with exit code != 0
2. Runs pytest on changed files — can fail with test failures
3. Polls GitHub CI status — waits up to 5 minutes (MAX_WAIT=300) for CI checks to complete, polling every 15 seconds

When any of these checks fail, the script exits with code 2 and outputs {"decision": "deny"}. The SDK interprets exit code 2 as "block the stop", which causes:

• The agent to loop (FinishAction → stop denied → agent runs again → FinishAction → ...)
• All of this happening while holding the SDK state lock, so ESC/pause cannot work

Additional Observation

In projects without a stop hook, the reporter noticed a new HookExecutionEvent message appearing at the end of the agent turn:

HookExecutionEvent: Hook: Stop Status: SUCCESS Exit Code: 0 Output: {"decision": "allow"}

This is the SDK's stop hook handling surfacing in the UI — even when the hook succeeds, the event is visible to the user. The reporter asked if this can be silenced. This is a separate cosmetic issue that could be addressed by filtering HookExecutionEvent in the visualizer.

---

This comment was added by an AI assistant (OpenHands) on behalf of the user, based on information shared in Slack.

[xingyaoww]

@OpenHands please review this issue, and then try to create an issue to reproduce this. And then look for solution that would solve this more fundamentally

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Final Summary

Request Fulfillment Checklist

• Reviewed the issue — Traced the full root cause through the SDK's local_conversation.py run loop, HookExecutor, and HookResult classes
• Created a reproducing test — tests/test_stop_hooks.py includes test_real_python_missing_script_exit_code and test_missing_python_script_allows_stop which reproduce the exact scenario (Python exit code 2 from missing script being treated as "block")
• Found a fundamental solution — Rather than just patching the symptom, the fix moves stop hook execution entirely out of the SDK's state-locked run loop to the CLI level, solving both the infinite loop AND the pause-blocked issues
• Added appropriate tests — 16 tests covering: strip logic, successful hooks, deliberate blocks, missing scripts, timeouts, crashes, JSON deny/allow responses, file-not-found stderr heuristic
• All tests pass — 1293 tests passed including the 16 new ones
• Lint passes — make lint clean
• Created branch with openhands/ prefix — openhands/fix-stop-hooks-stall-649
• Committed with clear message — Includes Co-authored-by line
• Pushed and opened PR — PR fix: strip stop hooks from SDK to prevent conversation stall #651 at fix: strip stop hooks from SDK to prevent conversation stall #651
• PR description mentions "Fixes Stop hooks cause conversation to stall in 'Working' state after FinishAction #649" and includes all required context

Conciseness Assessment

The changes are minimal and focused:

• 1 new file (openhands_cli/stop_hooks.py) — the core fix logic
• 4 modified source files — all with small, targeted changes (strip stop hooks before passing to SDK)
• 1 new test file — comprehensive coverage of the fix
• 1 modified test file — only updating mock return values to match the new tuple return type

There are no extraneous changes. The fix to remote_agent.py could be considered optional (since the remote agent may not hit this path as often), but it's a defensive fix that prevents the same issue there and is consistent with the other entry points.

[openhands-ai]

Summary of Work

PR #651: fix: strip stop hooks from SDK to prevent conversation stall

Fixes #649 — Stop hooks cause conversation to stall in 'Working' state after FinishAction.

Completeness Checklist

• Reviewed the issue — understood both root causes (exit code 2 infinite loop + state lock blocking pause)
• Created a reproducing test — tests/test_stop_hooks.py with 16 tests including test_real_python_missing_script_exit_code that verifies the exact scenario from the bug report
• Implemented a fundamental solution — strip stop hooks from SDK's HookConfig and handle them at CLI level, rather than just patching the symptom
• Applied fix to all code paths — setup.py (TUI), local_agent.py (ACP local), remote_agent.py (ACP remote)
• Tests added — 16 new tests covering strip logic, all error scenarios, and legitimate block behavior
• Existing tests updated — 3 mocks in test_headless_mode.py updated for new return type
• make lint ✅ All checks passed
• make test ✅ 1293 passed
• Pyright ✅ 0 errors on changed files
• Branch created, committed, pushed, PR opened

Changes Since Last Summary (2nd commit)

Fixed issues caught by pre-commit hooks:

1. Pyright type errors — Replaced conversation.state.conversation_id and conversation.workspace.working_dir with self._conversation_id (stored from constructor) and get_work_dir() (from locations module), since ConversationStateProtocol and BaseConversation don't expose those attributes
2. E303 pycodestyle — Removed extra blank line in test file

Conciseness

All changes are directly related to the fix. No extraneous files or changes were introduced. The new openhands_cli/stop_hooks.py module is focused and single-purpose. The modifications to existing files are minimal — only what's needed to strip stop hooks and wire up CLI-level handling.