Skip to content

fix(hook): capture mid-turn task notifications from queued attachments - #113

Open
Kiko0301 wants to merge 2 commits into
langfuse:mainfrom
Kiko0301:fix/mid-turn-task-notification
Open

Kiko0301 wants to merge 2 commits into
langfuse:mainfrom
Kiko0301:fix/mid-turn-task-notification

Conversation

@Kiko0301

@Kiko0301 Kiko0301 commented Oct 29, 2026 •

Copy link
Copy Markdown

Summary

Background Bash and MCP tasks notify with a <task-notification> row. When the notification arrives while the turn is still running, Claude Code 2.1.x does not write a user row: it attaches the notification to the running turn as a queued_command attachment, then removes it from the queue with reason: absorbed_mid_turn.

The hook only recognized user and queue-operation rows, so the attachment was ignored. The launching Tool observation kept the "moved to the background" output, and the <result> body never appeared anywhere in the trace (#109). The same absorbed notification also kept the async gate closed, so the turn only shipped at the next prompt (#96).

Changes

  • Read the notification body from attachment.prompt when the attachment is a queued_command with commandMode: task-notification, and recognize it as a task notification.
  • Background Bash/MCP notifications carry only a <task-id>, unlike agent notifications. Build a task_id -> tool_use_id map by finding the same task id in the launching tool result (including structured toolUseResult.backgroundTaskId), and merge it into the map used by turn assembly.
  • The existing notification path then fills the Tool observation's final_content and timestamp.
  • The attachment counts as delivery for the async gate, and a content-bearing queue-operation remove row now also counts as delivery. An absorbed notification no longer holds the turn open until the next prompt. A remove row without content still keeps the gate closed, preserving the conservative behavior for older transcript shapes.
  • Merge the background-task map when re-assembling the held open turn as well, so emission from emit_ready_observations_of_open_turn sees the same attribution.

Tests

Added in tests/unit/test_task_notifications.py and tests/unit/test_emission_gate.py:

  • a queued_command attachment is detected as a task notification; other attachment types are not
  • a background task id maps to the launching tool_use, and build_turns sets final_content / final_timestamp
  • transcript assembly resolves the attachment without an externally supplied map
  • attachment delivery, attachment + absorbed_mid_turn remove, and a content-bearing remove alone all clear the async gate
  • a remove row without content keeps the gate closed

Local verification:

  • uv run --group dev pytest -q: 281 passed, 7 failed, 1 skipped. The 7 failures are pre-existing Windows-only tests (POSIX lock/permission, HOME/~ expansion, log encoding) and fail identically on unmodified main.
  • Targeted files: 45 passed.
  • uvx ruff check --select F,E9 .: all checks passed.
  • echo '{}' | uv run --script hooks/langfuse_hook.py: starts cleanly.

Fixes #109. Fixes #96.

Claude Code 2.1.x attaches a task completion notification to the running
turn as a queued_command attachment instead of writing a user row when a
background Bash or MCP task finishes mid-turn. The hook only recognized
user and queue-operation rows, so the notification never reached turn
assembly: the tool observation kept the "moved to the background" output
and the result body never appeared in the trace.

Read the notification body from the attachment, map its <task-id> to the
launching tool_use by finding the same id in the tool result, and let the
existing notification path fill the tool observation's final content. The
attachment also counts as delivery for the async gate, so an absorbed
notification no longer keeps the turn held until the next prompt.

Fixes langfuse#109.

@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.

…moved

A content-bearing queue-operation remove row proves the notification left
the queue; it can no longer continue the turn. Treat it as delivered so
the turn ships at its own Stop, matching the attachment path. Remove rows
without content stay conservative because they cannot be matched.

Refs langfuse#96.
@LinusLuo666

Copy link
Copy Markdown

We hit this in production and can confirm #113 fixes a case not described in the PR: an agent notification that is persisted before its launch row.

What happened (Claude Code 2.1.220, real session):

  1. An assistant message launched a background agent (tool result status: async_launched), then stalled until API Error: The operation timed out about 5 minutes later.
  2. From what we can read in the 2.1.220 bundle, Claude Code holds an unfinished assistant message (stop_reason: null) back from the transcript, but writes queue-operation rows right away. The agent finished during the stall, so its enqueue/remove rows landed in the file before the launch tool_use and its async_launched tool result. The parentUuid chain is intact; only the file order is reversed.
  3. On main, turn assembly records the notification first, then the launch tool result overwrites that entry (add_tool_result_row), dropping final_content.
  4. The notification was then delivered only as a queued_command attachment, which main ignores. The agent stays pending and the turn is deferred forever under Stop. Three other background agents in the same turn did deliver normally, but they were held with it.

Replaying the real transcript offline (fake Langfuse client, flush_deferred_agent_turns=False):

held turns tool observations emitted
main (v1.2.2) 1 349
#113 0 495 (matches the transcript)

Replaying the same session incrementally, with the slice sizes our Stop hook actually sent (124 firings), also leaves nothing held with #113. Four other sessions with background and nested agents emit the same counts on main and on #113. A fifth emits nothing on main and 645 observations on #113; that one is the remove-row change in be137bf.

The attachment sits after the launch row, so recognizing it restores the completion that the launch row overwrote. We are running #113 in our deployment until it lands.

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

Labels

None yet

Projects

None yet

2 participants