anthropics / anthropics/claude-code
[BUG] Every background Agent-tool completion delivers two separate parent-turn events (SubagentHandback + redundant task-notification)
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 147k
- Forks
- 24k
- PR merge metrics
- PR metrics pending
Description
Preflight Checklist
- I have searched existing issues, including closed ones (searched: "SubagentHandback", "task-notification agent-message", "duplicate background task notification")
- This is a single bug report
- I am using a current version of Claude Code (2.1.277, latest published)
What's Wrong?
This is plain (non-agent-teams) background dispatch via the Agent tool — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is not set. Every background sub-agent I dispatch (e.g. subagent_type: "researcher", or one of my own role-scoped read-only reviewer agent definitions), when it finishes, delivers two separate events to the parent session, each waking a full assistant turn, for one genuine completion:
- An
agent-messagefrom the sub-agent, wrapping itsSubagentHandbackcall, containing the full final report body. - A separate
<task-notification>system-reminder for the sametask-id, arriving as its own later turn. Its own<result>content is just a pointer: "This agent's report was delivered to you as a message from<agentId>… Read it there; it is not repeated here."
Both events carry the same task-id. The second is pure overhead — it has no report content of its own, exists only to say "go re-read the first one," and still consumes a full parent turn. With several parallel sub-agents dispatched in one message (I routinely run 3-4 for a peer-review round), this doubles the number of parent turns for the same amount of actual information delivered.
This is distinct from #92244 (agent-teams idle_notification/message redelivered several times with an identical timestamp field — a true redelivery bug) and from #67784 (a background task silently resumes and produces a second/third notification with different, uncommissioned content). Here there is no team, no resumption, and no identical-content redelivery: it is a single completion, split by design into two sequential delivery events of different shape, both required to reach the same information.
What Should Happen?
One event, one parent turn, per background sub-agent completion. If the SubagentHandback agent-message already carries the full report, the follow-up <task-notification> for the same task-id should either be suppressed, or folded into the same delivery so it does not cost a second parent turn.
Error Messages/Logs
Sanitised example from a single dispatch of 4 parallel reviewer sub-agents in one Agent tool call — each of the 4 produced this exact two-event pattern:
# Event 1 — full content, as an agent-message
<agent-message from="ab4ce0cc35f2197c6">
[Subagent hand-back] The text below is the final report of a subagent this session delegated to. ...
FINDINGS (0 blockers, 2 amendments, 4 nits) — ...
[... full report body ...]
</agent-message>
# Event 2 — separate later turn, same task-id, no new content
<task-notification>
<task-id>ab4ce0cc35f2197c6</task-id>
<tool-use-id>toolu_01GmicFnRxKD8gMiQGuQRfcN</tool-use-id>
<output-file>/tmp/claude-1000/.../tasks/ab4ce0cc35f2197c6.output</output-file>
<status>completed</status>
<summary>Agent "Spec-compliance review T-415b11" finished</summary>
<note>A task-notification fires each time this agent stops with no live background children of its own. The user can send it another message and resume it, so the same task-id may notify more than once.</note>
<result>This agent's report was delivered to you as a message from "ab4ce0cc35f2197c6" (its SubagentHandback call). Read it there; it is not repeated here.
</result>
<usage><subagent_tokens>103510</subagent_tokens><tool_uses>26</tool_uses><duration_ms>357079</duration_ms></usage>
</task-notification>
The <note> on the second event ("the same task-id may notify more than once") suggests this second delivery is intentional/by-design rather than a transient bug, which is why I'm filing it as a UX/efficiency issue distinct from the redelivery bugs above rather than assuming it will be caught by the same fix.
Steps to Reproduce
- Do NOT enable agent teams.
- From a normal session, dispatch one or more sub-agents via the
Agenttool withsubagent_typeset to any non-forktype (built-in or a project-defined.claude/agents/*.mdrole), each doing a bounded task that ends in a final report. - Let each sub-agent run to completion.
- Observe two events land in the parent transcript for each completed sub-agent: the
agent-message/SubagentHandbackcontent, then a separate<task-notification>for the sametask-id.
Frequency: 100% reproducible, on every background sub-agent completion observed in this session.
Claude Model
claude-sonnet-5 (parent session)
Is this a regression?
Not sure — no prior-version comparison available in this session, but a user reported that earlier Claude Code versions delivered only a single event per finished sub-agent, with no separate intermediate/duplicate notification.
Version
2.1.277 (Claude Code), Linux
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the non-agent-teams background Agent flow described in the issue and trace the Agent tool's completion delivery using the search terms SubagentHandback, agent-message, task-notification, and task-id. Compare the two events for one completion; done means each sub-agent produces one parent-session event or one folded delivery without the redundant follow-up turn.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli, developer-experience
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100