claude-code - 💡(How to fix) Fix Stop hook false-positive: stale subagent IDs block session end [2 comments, 2 participants]

Stop:Callback hook blocking error from command: "callback": Background subagents are still running. Use TaskOutput task_id="..." block=true to wait for their results before ending your turn. 6. Actual: The runtime's internal pre-stop check detects stale agent IDs and blocks with the "Background subagents are still running" error. The Stop hook never fires because the runtime blocks first. The user can continue chatting past the error. The session isn't truly stuck — it just can't cleanly stop until the stale IDs are somehow cleared.

TL;DR

The most likely fix is to clear the stale agent IDs from the task lifecycle tracking registry to prevent the runtime's internal pre-stop check from blocking the Stop hook.

Guidance

• Investigate the task lifecycle tracking registry to understand how completed agent/task IDs are retained and how they can be cleaned up.
• Verify that the TaskOutput command is correctly reporting "No task found" for every agent ID, indicating that the tasks are genuinely completed.
• Consider implementing a mechanism to automatically clean up completed agent IDs from the registry when the Stop hook blocks and forces a new turn.
• Review the Stop hook's logic to ensure it is not inadvertently causing the runtime's pre-stop check to detect stale agent IDs.

Example

No code snippet is provided as the issue does not contain sufficient information about the specific code implementation.

Notes

The provided workaround of continuing to chat past the error is not a reliable solution, as it does not address the underlying issue of stale agent IDs. A more robust solution would involve cleaning up the task lifecycle tracking registry.

Recommendation

Apply a workaround to clear the stale agent IDs from the task lifecycle tracking registry, as upgrading to a fixed version is not mentioned in the issue. This is because the issue seems to be related to the specific implementation of the task lifecycle tracking registry and the Stop hook, rather than a version-specific bug.