Claude Code hangs after workflow completion - stop_reason: null in API response

Description

Claude Code hangs for several minutes after a workflow completes successfully. The UI shows "Churned for 2m 49s" followed by "Forging... (2m 29s · ↓ 0 tokens)" even though all work is done.

Environment

• Claude Code version: 2.1.15 (Homebrew)
• OS: macOS (Darwin 24.6.0)
• Model: claude-opus-4-5-20251101

Steps to Reproduce

1. Run a workflow that spawns multiple background agents (e.g., a codebase mapping workflow with 4 parallel agents)
2. Wait for all agents to complete and workflow to finish
3. Observe the hang after the completion message is displayed

Expected Behavior

Claude Code should return to the prompt immediately after displaying the workflow completion message.

Actual Behavior

Claude Code hangs for several minutes showing:

• "Churned for 2m 49s"
• "Forging... (2m 29s · ↓ 0 tokens)"

The user must press esc to break out, even though the workflow completed successfully.

Root Cause Analysis

Examined the session logs and found the issue:

Session log entries show stop_reason: null on API responses:

{
  "message": {
    "model": "claude-opus-4-5-20251101",
    "content": [{"type": "text", "text": "Codebase mapping complete..."}],
    "stop_reason": null,
    "stop_sequence": null,
    "usage": {"output_tokens": 2}
  }
}

Key observations:

• stop_reason: null instead of "end_turn"
• output_tokens: 2 despite the response containing much more text
• This pattern appears on multiple assistant responses in the session

Debug log shows 4-minute gap:

20:35:40 - SubagentStop triggered (last agent completed)
20:39:38 - Next log entry (4 MINUTE GAP with no activity)

Claude Code appears to be waiting for a proper stop signal from the API that never arrives.

Session Artifacts

• Debug log: ~/.claude/debug/537bbf30-fc4d-434e-9a1f-e2c7171c45bb.txt (15,989 lines)
• Session log: ~/.claude/projects/-Users-macuser-code-get-shit-done/537bbf30-fc4d-434e-9a1f-e2c7171c45bb.jsonl

Workaround

Press esc when the hang occurs - the work is complete, the client is just waiting for a signal that won't come.

Additional Context

This was observed during a /gsd:map-codebase workflow that spawns 4 parallel gsd-codebase-mapper agents using the Task tool with run_in_background: true. All agents completed successfully and wrote their output files. The hang occurred after the orchestrator displayed the completion summary.