Repository navigation
Description
Problem
A turn that runs a background command (Bash with run_in_background: true) is never exported at its own Stop if the command finishes while the turn is still running. The hook logs Processed 0 turns, and the turn stays in open_turn with empty turn_progress. It reaches Langfuse only when the next prompt closes it. If the session ends there, the turn is stranded, because SessionEnd is usually cancelled during shutdown (#13). Once #93 merges, the stranded rows are dropped after the TTL and the turn is lost for good.
This is common in any workflow that uses background commands, such as a curl trigger for a debugger, a dev server or a long test run.
Seen with plugin 1.2.0 (b521100; the hook is unchanged on main at 8870487) and Claude Code 2.1.281 (VS Code extension) on macOS.
Reproduce
- In one turn, have Claude start a
Bashcommand withrun_in_background: true, then keep working (another tool call) until the command finishes, then end the turn. - After
Stop,langfuse_hook.logshowsProcessed 0 turns, and the session's state entry holds the whole turn inopen_turnwithturn_progress: {}. - Nothing appears in Langfuse until another prompt is sent in that session.
What Claude Code writes
When the notification lands mid-turn, Claude Code 2.1.281 doesn't deliver it as a user row with origin.kind == "task-notification". It attaches it to the running turn and removes it from the queue. The remove row repeats the notification and states why it was removed (rows trimmed):
{"type":"queue-operation","operation":"enqueue","content":"<task-notification>\n<task-id>b0hs0t91w</task-id>\n<tool-use-id>toolu_012iw63cVuYeyEP3rV2ahmem</tool-use-id>\n…<status>completed</status>…</task-notification>"}
{"type":"attachment","attachment":{"type":"queued_command","prompt":"<task-notification>…</task-notification>","commandMode":"task-notification"}}
{"type":"queue-operation","operation":"remove","reason":"absorbed_mid_turn","content":"<task-notification>\n<task-id>b0hs0t91w</task-id>\n<tool-use-id>toolu_012iw63cVuYeyEP3rV2ahmem</tool-use-id>…</task-notification>"}Root cause
get_undelivered_queued_notification_ids() treats every queue-operation row that names a notification as queued, and counts a notification as delivered only when a matching non-queue row arrives. Its docstring assumes that remove rows carry no content and so can't be matched, but this remove row repeats the notification. The hook therefore counts it as a second queued entry. No delivery row ever follows, because the notification was absorbed into the turn. turn_has_unresolved_async_activity() stays true, so emit_ready_observations_of_open_turn() holds the turn until something closes it.
Proposed fix
Count a remove row that names the notification as resolved. Once the notification has left the queue it can't continue the turn, whether it was absorbed mid-turn or dropped. Removes without content still can't be matched, so older Claude Code versions keep the current conservative behaviour.
diff --git a/hooks/langfuse_hook.py b/hooks/langfuse_hook.py
index e1dbe6d..04106e6 100644
--- a/hooks/langfuse_hook.py
+++ b/hooks/langfuse_hook.py
@@ -1177,9 +1177,13 @@ def get_undelivered_queued_notification_ids(rows: List[Dict[str, Any]]) -> List[
A queued result already fills the launch entry's final_content, so the
pending-agents check goes clean — yet the turn provably continues: the
delivery row and Claude's follow-up response are still outstanding.
- Queue remove rows carry no notification content and cannot be matched, so
- a removed notification keeps the gate closed until the turn ends — the
- safe direction (close-time emission is always correct).
+ A notification that arrives mid-turn is attached to the running turn (a
+ queued_command attachment row) and then leaves the queue with a remove
+ row that repeats its content (reason "absorbed_mid_turn"); a removed
+ notification can no longer continue the turn, so it counts as delivered.
+ Remove rows without content (older Claude Code) cannot be matched, so they
+ keep the gate closed until the turn ends — the safe direction (close-time
+ emission is always correct).
"""
queued: List[str] = []
delivered = set()
@@ -1189,7 +1193,7 @@ def get_undelivered_queued_notification_ids(rows: List[Dict[str, Any]]) -> List[
tool_use_id = get_tool_use_id_from_task_notification(row)
if not tool_use_id:
continue
- if row.get("type") == "queue-operation":
+ if row.get("type") == "queue-operation" and row.get("operation") != "remove":
queued.append(tool_use_id)
else:
delivered.add(tool_use_id)Tests
I added two unit tests to tests/unit/test_emission_gate.py: an absorbed notification counts as delivered, and a remove without content keeps the gate closed. I also added one integration test to tests/integration/test_emit_new_turns_from_transcript.py, built from the 2.1.281 row shapes above. It checks that the turn ships at its own Stop. The full suite passes with the fix (282 passed). Without it, the absorbed-notification unit test and the integration test fail.
Test diff
diff --git a/tests/integration/test_emit_new_turns_from_transcript.py b/tests/integration/test_emit_new_turns_from_transcript.py
index 3ae7f6a..174db15 100644
--- a/tests/integration/test_emit_new_turns_from_transcript.py
+++ b/tests/integration/test_emit_new_turns_from_transcript.py
@@ -250,3 +250,66 @@ def test_only_the_turn_root_span_is_marked_as_root(
# Children explicitly opt out of the SDK's app-root auto-marking, so the
# events view never lists them as root observations.
assert all(o._otel_span.attributes.get("langfuse.internal.is_app_root") is False for o in children)
+
+
+def test_background_bash_turn_ships_at_its_stop_when_notification_is_absorbed_mid_turn(
+ hook_module,
+ fake_langfuse,
+ isolated_hook_state,
+ tmp_path,
+):
+ """A run_in_background Bash whose completion notification is absorbed into
+ the running turn (enqueue -> queued_command attachment -> remove) leaves
+ nothing pending, so the turn ships at its own Stop. Row shapes are
+ harvested from a real Claude Code 2.1.281 session."""
+ notification = (
+ "<task-notification>\n<task-id>b0hs0t91w</task-id>\n"
+ "<tool-use-id>toolu_bg1</tool-use-id>\n"
+ "<output-file>/tmp/tasks/b0hs0t91w.output</output-file>\n"
+ "<status>completed</status>\n"
+ "<summary>Background command \"curl\" completed (exit code 0)</summary>\n"
+ "</task-notification>"
+ )
+ rows = [
+ {"type": "user", "uuid": "user-1", "timestamp": "2026-01-01T00:00:00.000Z",
+ "sessionId": "s", "message": {"role": "user", "content": "Trigger the request and debug it."}},
+ {"type": "assistant", "uuid": "a-1", "timestamp": "2026-01-01T00:00:01.000Z",
+ "message": {"id": "msg-1", "role": "assistant", "model": "claude-test",
+ "content": [{"type": "tool_use", "id": "toolu_bg1", "name": "Bash",
+ "input": {"command": "curl -s https://example.test/",
+ "run_in_background": True}}]}},
+ {"type": "user", "uuid": "tr-1", "timestamp": "2026-01-01T00:00:02.000Z",
+ "toolUseResult": {"stdout": "", "stderr": "", "interrupted": False,
+ "backgroundTaskId": "b0hs0t91w"},
+ "message": {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_bg1",
+ "content": "Command running in background with ID: b0hs0t91w."}]}},
+ {"type": "assistant", "uuid": "a-2", "timestamp": "2026-01-01T00:00:03.000Z",
+ "message": {"id": "msg-2", "role": "assistant", "model": "claude-test",
+ "content": [{"type": "tool_use", "id": "toolu_wait", "name": "mcp__debug__wait",
+ "input": {}}]}},
+ {"type": "queue-operation", "operation": "enqueue",
+ "timestamp": "2026-01-01T00:00:04.000Z", "content": notification},
+ {"type": "user", "uuid": "tr-2", "timestamp": "2026-01-01T00:00:05.000Z",
+ "message": {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_wait",
+ "content": "exited"}]}},
+ {"type": "attachment", "uuid": "att-1", "timestamp": "2026-01-01T00:00:04.000Z",
+ "attachment": {"type": "queued_command", "prompt": notification,
+ "commandMode": "task-notification"}},
+ {"type": "queue-operation", "operation": "remove", "reason": "absorbed_mid_turn",
+ "timestamp": "2026-01-01T00:00:05.500Z", "content": notification},
+ {"type": "assistant", "uuid": "a-3", "timestamp": "2026-01-01T00:00:06.000Z",
+ "message": {"id": "msg-3", "role": "assistant", "model": "claude-test",
+ "content": [{"type": "text", "text": "Request finished; breakpoint hit."}]}},
+ ]
+ transcript = tmp_path / "transcript.jsonl"
+ transcript.write_text("\n".join(json.dumps(r) for r in rows) + "\n", encoding="utf-8")
+ config = hook_module.LangfuseConfig("public", "secret", "https://example.test", "user-1")
+
+ def roots():
+ return [o for o in fake_langfuse.observations if o.name == "Conversational Turn"]
+
+ # The turn's only Stop: nothing is pending, so it ships now rather than at
+ # the next prompt or a SessionEnd that Claude Code usually cancels (#13).
+ hook_module.emit_new_turns_from_transcript(fake_langfuse, config, "session-bg", transcript)
+ assert len(roots()) == 1
+ assert roots()[0].output == {"role": "assistant", "content": "Request finished; breakpoint hit."}
diff --git a/tests/unit/test_emission_gate.py b/tests/unit/test_emission_gate.py
index b42fc99..0d71248 100644
--- a/tests/unit/test_emission_gate.py
+++ b/tests/unit/test_emission_gate.py
@@ -28,3 +28,24 @@ def test_rows_without_notifications_pass_the_gate(hook_module):
{"type": "queue-operation", "operation": "remove", "content": None},
]
assert hook_module.get_undelivered_queued_notification_ids(rows) == []
+
+
+def test_mid_turn_absorbed_notification_counts_as_delivered(hook_module):
+ # Claude Code 2.1.281: a notification that lands mid-turn is attached to the
+ # running turn and leaves the queue with a remove row repeating its content.
+ rows = [
+ {"type": "queue-operation", "operation": "enqueue", "content": NOTIFICATION},
+ {"type": "attachment", "attachment": {"type": "queued_command", "prompt": NOTIFICATION,
+ "commandMode": "task-notification"}},
+ {"type": "queue-operation", "operation": "remove", "content": NOTIFICATION,
+ "reason": "absorbed_mid_turn"},
+ ]
+ assert hook_module.get_undelivered_queued_notification_ids(rows) == []
+
+
+def test_removal_without_content_keeps_the_gate_closed(hook_module):
+ rows = [
+ {"type": "queue-operation", "operation": "enqueue", "content": NOTIFICATION},
+ {"type": "queue-operation", "operation": "remove", "content": None},
+ ]
+ assert hook_module.get_undelivered_queued_notification_ids(rows) == ["toolu_X"]
Activity
fix(hook): release the async gate when an absorbed notification is re…
Kiko0301 commentedon Oct 29, 2026
Thanks for the detailed row shapes. #113 now treats a content-bearing \queue-operation\
emove\ row as delivery for the async gate (a remove without content still stays conservative), and also handles the mid-turn \queued_command\ attachment that carries the result. The regression test covers the enqueue -> attachment -> \�bsorbed_mid_turn\ remove sequence, so the turn ships at its own Stop. This should cover the case reported here once #113 merges.