Claude adapter: Stop hook + idle detection re-entrant loop prevents session from ending

[tronghieu]

Description

When a Claude Code session running under bmad-loop finishes its work and enters the "Leavening" phase (stop hooks execution), a re-entrant loop can occur that prevents the session from ever properly ending.

Steps to reproduce

1. Configure a Claude Code project with Stop hooks that take more than ~5 seconds to complete (e.g., a hook that runs gh CLI commands or a test suite)
2. Run bmad-loop run with a story
3. Let the dev/review session complete its work and attempt to stop

What happens

1. Session finishes work → enters "Leavening" phase → stop hooks begin executing
2. Claude Code shows running stop hooks… 0/N (the counter never progresses past 0)
3. After ~5 seconds of hooks not completing, bmad-loop idle detection fires and writes "You appear idle in bmad-loop automation mode" into the TTY
4. Claude sees this message as user input → tries to respond/explain → this triggers the Stop hooks AGAIN
5. The cycle repeats: stop hooks run → idle detection → Claude responds → stop hooks run again → ...

Observed behavior

• The stop hook counter stays at 0/N indefinitely
• bmad_loop_hook.py Stop completes successfully each iteration (Stop events are written to the run directory)
• But the session never transitions to session-end in the journal
• The Claude process remains alive with an open API connection, stuck in this loop
• Tokens continue to be consumed as Claude re-processes the idle message each cycle

Expected behavior

Stop hooks should either:

• Complete (or timeout) before idle detection can fire, OR
• Idle detection should not inject messages into the TTY while stop hooks are in progress, OR
• The session should eventually end after a finite number of idle detection cycles

Environment

• bmad-loop 0.8.0
• Claude Code adapter
• macOS

Impact

Sessions that are functionally complete (all work done, verification passing, commits made) cannot terminate, consuming tokens and requiring manual intervention to kill the process.

[coderabbitai]

🔗 Related PRs

#122 - fix(adapters): disable Claude Code background tasks in the shipped profile [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[pbean]

Thanks for the detailed report — validated, and the fix is up in #151. A few findings from the investigation that refine the mechanism:

Confirmed root cause (the loop). The wake nudge is delivered as a submitted turn (tmux send-keys + Enter), so answering it always ends in another Stop. On every fresh result-less Stop the adapter refills the per-silence nudge budget (it reads a turn-end as proof of cooperative progress), so nudge → reply → Stop → refill repeats until session_timeout_min. A monotonic total cap already existed for injected workflow sessions (workflow_stall_nudges_cap, 0.8.0) but dev/review sessions were deliberately left uncapped — that exemption is what #151 removes ([limits] dev_stall_nudges_cap, default 6; after that the session is declared stalled, and the post-kill reconcile still rescues it as completed if its terminal artifact is on disk).

One correction to the timeline. The "~5 seconds" you observed isn't the idle threshold — that's the adapter's event-poll tick. The nudge only fires after dev_stall_grace_s (default 600 s) of pane-log silence following a result-less Stop, so slow Stop hooks alone never trigger it at defaults. If you saw nudges within seconds, check whether your policy.toml lowers dev_stall_grace_s. Either way the loop itself was real and unbounded; the cap bounds it regardless of the configured grace.

The remaining question — why was the Stop result-less at all? Your session was functionally complete (commits made, verification passing), yet the adapter's artifact read-back found no terminal result on any Stop; that's the precondition for the whole loop, and today it's invisible. #151 adds a diagnostic breadcrumb for exactly this: every result-less Stop appends {ts, verdict, detail} to <run-dir>/tasks/<task_id>/resultless-stops.jsonl (verdicts: pending / not-terminal / stale-mtime / ambiguous / no-artifact / no-result-json). If you can reproduce on a build with #151, that file will say precisely why the completed work wasn't recognized (most likely a spec whose frontmatter status never reached a terminal value) — worth a follow-up issue with that output if it recurs.