Skip to content

Turns with a background command never export at Stop: absorbed_mid_turn notification keeps the async gate closed #96

Open

Description

@Lazur

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

  1. In one turn, have Claude start a Bash command with run_in_background: true, then keep working (another tool call) until the command finishes, then end the turn.
  2. After Stop, langfuse_hook.log shows Processed 0 turns, and the session's state entry holds the whole turn in open_turn with turn_progress: {}.
  3. 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

  1. Kiko0301 commented on Oct 29, 2026

    @Kiko0301

    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.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions