Skip to content

fix(hook): run the Stop hook async so it does not block every turn - #115

Open
kevinb361 wants to merge 1 commit into
langfuse:mainfrom
kevinb361:stop-hook-async
Open

kevinb361 wants to merge 1 commit into
langfuse:mainfrom
kevinb361:stop-hook-async

Conversation

@kevinb361

Copy link
Copy Markdown

The Stop hook blocks the end of every turn for far longer than its work takes. This marks it async so Claude Code no longer waits on it.

Problem

Stop is a synchronous command hook, so Claude Code waits for the process to exit before the turn finishes. On one Linux machine, Claude Code's own hook records (hook_success attachments in the session transcripts) for 42 Stop runs over ~5 days show:

wall time (durationMs)
median 28.6 s
p95 38.9 s
max 49.9 s

For the same runs langfuse_hook.log reports Processed N turns in 0.15s–1.45s. A cold uv run --quiet --script hooks/langfuse_hook.py </dev/null takes 0.47 s, and flush_and_shutdown_langfuse_client() caps flush+shutdown at 5 s. Roughly 20+ s per run therefore goes somewhere after the logged work, presumably in interpreter exit or exporter teardown. I have not pinned down where; doing so would have meant instrumenting real exports. Either way, the turn should not wait on it.

Fix

Add "async": true to the Stop command hook in hooks/hooks.json.

  • Locking is unaffected. Both FileLock sections in emit_new_turns_from_transcript() are released before main() reaches flush_and_shutdown_langfuse_client() in its finally, so the slow tail runs without holding a lock and cannot make an overlapping run time out.
  • Overlap is already handled. Progress is persisted in emitted_keys, so a run that sees nothing new emits nothing.
  • SessionEnd stays synchronous, because of SessionEnd hook is killed during CLI shutdown — "Hook cancelled" shown on every exit #13.

Tradeoff: progress is saved before the SDK flush (the known limitation noted beside the second lock, and #103). If Claude Code ends a still-running async Stop when the session exits, that turn's spans can be lost where today the user would have waited for them. Bounding process exit itself, for example os._exit after the capped flush, would shrink that window; I have left it out to keep this change to one line.

Testing

  • Ran with this change locally (Claude Code 2.1.314, plugin 1.2.0, langfuse 4.18.0, opentelemetry-sdk 1.45.1, Python 3.12 via uv, Linux) across 8 sessions. The hook log shows 41 Processed N turns runs at 0.13–0.30 s with no lock timeout lines, and Claude Code no longer records a blocking Stop hook for those turns.
  • Not verified: that every turn from those sessions reached the server. I did not query the Langfuse API.
  • No unit test: the change is to hook registration, which the test suite does not load.

The Stop hook's wall time (median ~28 s) far exceeds its logged work
(<1.5 s), and Claude Code waits on it at the end of every turn. Both
state locks are released before the flush, so running it async does
not cause lock contention. SessionEnd stays synchronous (langfuse#13).

🤖 Generated with Claude Code

Co-Authored-By: Claude <claude@anthropic.com>

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant