The report's diagnosis checks out, but its fix wouldn't work on its own. Fixing launch detection (suggestions 1 and 2) would still capture nothing, because Claude's SubagentStop event in 2.1.288 doesn't include a tool_use_id, so the stop handler can't find the record it's supposed to finish.

What I confirmed

The misclassification is real. isBackgroundLaunch (cmd/entire/cli/hooks.go:65) only reads a boolean run_in_background from tool_input. If it's absent or is the string "true", the launch is treated as foreground. The launch is then finished immediately by completeSubagentTaskRecord, which skips at lifecycle.go:1972 because nothing has changed yet. That matches the report.

There's a better signal than tool_input. The Claude transcripts for both runs record the async launch result as:

So suggestion 2 is the right one. Check tool_response.isAsync (or status == "async_launched"), not the text "Async agent launched successfully". postToolHookInputRaw (agent/claudecode/types.go:66) currently parses only agentId from tool_response, so isAsync needs adding there.

What the report missed

The warning it calls "the same warning pair" is the bigger problem. In agent-scenarios/.entire/logs/entire.log, every SubagentStop logs has_tool_use_id:false, and the warning that follows logs tool_use_id:"". handleSubagentStopFinal looks up the in-flight record with state.FindTaskRecord(event.ToolUseID) (lifecycle.go:1678), and that lookup matches on ToolUseID only (session/state.go:677).

So even if the launch were correctly classified as background and the record were saved, SubagentStop would look for "", miss it, and drop the event. The completion step CompleteTaskRecord is also keyed by tool_use_id. The payload does include agent_id, and it matches the agentId in the launch result (for example a0ea1ded02cddc066 appears in both).

The fix needs three parts:

1. Detect background launches from tool_response.isAsync. Keep reading tool_input, but accept both true and "true" there.
2. In handleSubagentStopFinal, when ToolUseID is empty, look up the record by AgentID.
3. Then fill in event.ToolUseID from that record, so the completion and the tasks/<tool_use_id>/ path line up.

I'd push back on suggestion 3 (completing without a record, like CompletionWithoutLaunch does). With no tool_use_id it would write into tasks//. It would also capture a second time any foreground subagent that was already recorded at launch. Parts 1 and 2 above make it unnecessary.

One more thing: the has_tool_use_id check is described in a comment as "structurally impossible for a well-formed payload". That's no longer true, and the comment should change along with the code.

Codex part

The code matches the report. Codex's provisional stop (lifecycle.go:1557-1582) writes only to SubagentInventory. DeclaredTranscriptPath only reaches the task record through the inventory refresh or SessionEnd (around :1302 and :1346). resolveTaskTranscriptPath (manual_commit_condensation.go:281) knows only Claude's directory layout. Of the two suggested fixes, I'd copy the inventory's resolved path onto the matching task record before condensation. Teaching the strategy package to look up Codex rollouts by session_meta.id would add Codex-specific logic to a package that currently copies Claude's layout only because of an import cycle. I didn't reproduce this checkpoint myself; this part is from reading the code.

Attribution

I didn't check whether the attribution numbers come from the missing record, so that link is still unconfirmed.

I saved the missing-tool_use_id finding to memory. Next I can write the fix (TDD: a SubagentStop fixture without tool_use_id, plus an async tool_response launch) and re-record the two Claude scenarios.

Because the hook that fires when the Agent tool returns (PostToolUse) means different things in the two cases, and the code depends on that timing.

Foreground: the parent waits until the subagent finishes, so PostToolUse fires after the subagent's work is done. That makes it a safe moment to capture. Nothing else is editing while the parent waits, so every worktree change since the pre-task snapshot belongs to the subagent. The foreground path therefore diffs the whole worktree (DetectFileChanges) and records the task right away.

Background: PostToolUse fires a few seconds after launch, when the subagent has done nothing yet. Capturing then would record an empty task. That's exactly what's happening in this bug. So faa9a540df (2026-08-17) added the split. On a background launch, Entire records an in-flight marker and waits for SubagentStop, the first event that comes after the real work. The background path also differs in two other ways:

• It uses only the files the subagent says it changed (analyzerFilesOnly). The parent keeps working at the same time, so a worktree-wide diff would credit the parent's edits to the subagent.
• It always writes a record (bypassNoChangesSkip), even for a read-only subagent, because SubagentStop is its only chance to save the transcript. The foreground path still drops read-only subagents.

Could we drop the split?

Partly. The foreground path is the only one most agents have. Cursor, Factory Droid and Vogon send only a launch-time SubagentEnd with no completion event. Codex goes through its own provisional-stop and inventory handling. Only Claude Code (claudecode/lifecycle.go:247) and Copilot CLI (copilotcli/lifecycle.go:227) send a final completion event. So for most agents, "capture when the tool returns" has to stay.

For Claude, the code suggests SubagentStop fires for foreground subagents too. The "foreground dedup" in that warning is exactly that duplicate stop event being dropped. I haven't checked that against a real payload. If it holds, Claude could skip the launch-time classification and always capture at SubagentStop:

• Record a marker for every launch, keyed by tool_use_id and agentId, and complete it at SubagentStop. Misclassification would then stop mattering, and read-only foreground subagents would be captured too.
• Keep the worktree-wide diff for foreground launches. A background launch can't safely use it, so at that point it's an optional extra, not a separate capture path.

That's a bigger change than the bug fix. The tool_use_id gap applies either way: completion would have to look records up by agent_id. Before choosing it, I'd confirm from a real foreground run's log that SubagentStop fires and includes agent_id.

SubagentStop does fire for foreground subagents too. But my "capture everything at SubagentStop" idea doesn't work, because in foreground mode SubagentStop arrives before the event that links it to a tool_use_id.

What I ran

In a throwaway repo I hooked every subagent-related event with a script that only dumps the payload, then ran claude -p (2.1.288, Haiku). One run launched the subagent in the foreground and one in the background. Order of events:

Foreground (run_in_background: false):

Background (run_in_background: true):

What that means

• SubagentStop never includes tool_use_id, in either mode. The "structurally impossible" check is wrong for every Claude subagent. The "no in-flight marker" warning also fires for every foreground subagent, so it's noise.
• PostToolUse is the only event that carries both IDs. In foreground mode it comes after SubagentStop, so the stop handler doesn't know the tool_use_id yet. Matching PreToolUse to SubagentStart by order instead would break as soon as two subagents launch in parallel. So the foreground path stays where it is, at PostToolUse, which also fires once the subagent has finished.
• tool_response.status is the reliable way to tell the two apart. It's "completed" for foreground and "async_launched" for background, whatever the model put in tool_input. In my local history, all 316 Agent launches (2.1.221 to 2.1.288) were async. run_in_background was absent in 310 and the string "true" in 5, never the boolean isBackgroundLaunch checks for. So on my machine the background path has effectively never run on real Claude data.

Revised fix

1. At PostToolUse, classify by tool_response.status, not tool_input. "async_launched" records an in-flight marker with AgentID from tool_response.agentId. "completed" captures right away, as foreground does today. For other agents, or a missing status, keep today's tool_input parsing.
2. At SubagentStop, look up the marker by agent_id and copy its ToolUseID onto the event before completing the record.
3. Lower the two warnings to Debug for Claude and fix their comments. Missing tool_use_id is normal, and finding no marker at SubagentStop is expected for foreground subagents.

Separately, the foreground path still drops read-only subagents because of the no-changes check. A "completed" status is reliable enough to record those too, but that's a product decision, so I've left it out of the bug fix.

I saved the payload dumps in the scratchpad (fgprobe/) and updated the memory note with the event order. Do you want me to implement this, with tests built from these real payloads?

I built the tests first, then the fix. Everything passes except two failures that have nothing to do with this change. Nothing is committed yet.

Tests (written first)

The test payloads are copied from the real Claude Code 2.1.288 hooks I captured earlier.

• Payload parsing (agent/claudecode/lifecycle_test.go): an async launch, a foreground completion, a "completed" status overriding run_in_background: true, and a response with no status, which stays unknown. Also SubagentStop without a tool_use_id.
• TestIsBackgroundLaunch (hooks_test.go): "true" and "false" as strings, an unrecognized value, and the launch mode Claude reports taking priority in both directions.
• FindTaskRecordByAgentID (session/state_test.go): an empty ID never matches.
• Lifecycle (lifecycle_test.go):
  • A launch Claude reports as background, with no run_in_background in its input, records an in-flight marker.
  • A launch Claude reports as foreground completes immediately, even with run_in_background: true.
  • A SubagentStop without tool_use_id completes the marker it finds by agent ID.
  • A SubagentStop that matches no marker creates nothing, so there's no tasks//.
• Integration (integration_test/subagent_checkpoints_test.go): both real event orders, sent through the actual hook binary.
  • Background: the subagent's transcript ends up under tasks/<tool_use_id>/ in the checkpoint. This test failed before the fix with "must leave an in-flight marker".
  • Foreground: SubagentStop arrives first, then PostToolUse with "completed". This one already passed on the old code. It stops a later change from treating the string "true" as background without checking the response status.

Fix

• agent/event.go: new Event.SubagentLaunch field: Unknown, Foreground or Background.
• agent/claudecode: parses tool_response.status and isAsync. "async_launched" or isAsync means Background; "completed" means Foreground. The SubagentStop warning now fires only when session_id is missing, since a missing tool_use_id is normal.
• hooks.go: isBackgroundLaunch now takes the event. The mode Claude reports wins. Otherwise it falls back to run_in_background, accepting a boolean or a boolean string. An unrecognized value is logged as a Warn instead of Debug.
• lifecycle.go: when a SubagentStop has no ToolUseID, it finds the record by agent ID and uses that record's ToolUseID. The "no in-flight marker" warning is skipped for events without a ToolUseID, because that's every foreground Claude subagent.

Verification

Format, lint (0 issues), integration tests, and the canary (Vogon and roger-roger) all pass. mise run check still exits non-zero because of two unrelated failures:

• TestProbeConfigDir_AsksClaude starts the real claude binary and timed out after 5s under full-suite load. It passes when run alone.
• TestOpenCodeSeedRepoPlantsDeps is the known local failure when the OpenCode deps bootstrap hasn't run.

Not done

• Re-recording the scenarios. I haven't re-recorded the two agent-scenarios runs with real Claude. That's the true end-to-end check, and it costs a little in API calls.
• Codex "transcript path unresolvable". That half of the report isn't touched; it's a separate change.
• Unrealistic test payloads. The existing SimulateSubagentStop helper still sends a tool_use_id, and the existing foreground test sends the stop after PostToolUse, which is the reverse of the real order. Those tests still pass but don't match real payloads.

Do you want me to commit and open a PR, re-record the scenarios first, or both?

The integration test harness now sends the hook payloads Claude Code really sends. Seven existing background-subagent tests fail on the old code and pass with the fix. Before, they all passed on the old code, because the payloads they sent hid the bug.

What changed in the tests

The integration test harness (integration_test/hooks.go):

• SubagentStopInput no longer has a ToolUseID field, because Claude never sends one in that event. Every SubagentStop in the suite now has to be matched by agent ID.
• PostTaskInput.RunInBackground is now Background. It controls tool_response: "async_launched" with isAsync: true for background, "completed" for foreground. tool_input no longer carries run_in_background in either case.
• Updated the callers in read_only_session_test.go, subagent_commit_in_turn_test.go and subagent_checkpoints_test.go.

TestSubagentCheckpoints_ForegroundDoubleFire_CapturesOnce now uses the real foreground order:

1. SubagentStop arrives first and creates no record.
2. PostToolUse with "completed" captures the subagent.
3. A repeated SubagentStop finds the finished record by agent ID and changes nothing: no new commit, and the record is completed only once.

Claude parser unit tests: the SubagentStop payloads no longer include tool_use_id, and the PostToolUse fixture now includes a status.

Removed duplicates: I dropped the two raw-payload integration tests I added in the last round, plus their helper. The rewritten harness tests cover the same thing. The "true"-string case is still covered by unit tests in the parser, isBackgroundLaunch, and the lifecycle.

Verification

I temporarily reverted only the non-test code. Seven integration tests then failed:

• the background-capture test
• turn end followed by SubagentStop
• two review-session tests
• three commit-linking tests

With the fix re-applied, the full integration suite, the unit suites and lint (0 issues) all pass.

The two Claude scenarios in agent-scenarios still haven't been re-recorded with real Claude. Nothing is committed yet.

I fixed both findings, test first: each new test failed before its fix and passes after it.

P2: a resumed subagent could match an old finished record.

• Test: a session/state_test.go subtest builds a finished record and an in-flight record that share an agent ID. The lookup must return the in-flight one. Once both are finished, it must return the finished one, so a repeated SubagentStop is still skipped.
• Test: TestHandleLifecycleSubagentEnd_SubagentStop_WithoutToolUseID_ResumedSubagent checks that the stop completes the resumed run's record and leaves the first run's record untouched. Before the fix, the stop matched the old record and the new one was never completed.
• Fix: FindTaskRecordByAgentID (session/state.go) now prefers a record that is still in flight. It returns a finished record only when no in-flight one exists. The doc comment explains why.
• Caveat: I didn't confirm that Claude really reuses the agent ID when a subagent is resumed. The change is correct either way.

P2: the raw run_in_background value was logged as-is.

• Test: TestIsBackgroundLaunch_UnrecognizedValueNotLogged sends a secret-looking string and an object containing a token. It reads back the real log file and asserts the value never appears and only its type does. Before the fix, the object was logged in full.
• Fix: hooks.go now logs only the value's Go type, via %T. I first used a hand-written type switch, but its "string" literal tripped the repo's goconst lint check, and %T was simpler anyway. The log shows "type":"string" or "type":"map[string]interface {}".

Lint reports 0 issues, the Windows vet is clean, and the cli, session and integration suites all pass. Nothing is committed yet.

The trail is open: https://entire.io/gh/entireio/cli/trails/1469

The work is one commit, b6fe9c90df, on the new branch soph/claude-async-subagent-capture, pushed to origin. The trail description lays out the two causes, the real hook order from the captured payloads, the fix, the tests, and what's left out.

• Checks: mise run check still exits non-zero because of the same two failures as before, neither related to this change. TestProbeConfigDir_AsksClaude times out under full-suite load and passes when run alone. TestOpenCodeSeedRepoPlantsDeps needs the OpenCode deps set up locally. Lint, integration tests and the canary all pass.
• Trail findings: none yet. The automated review has probably not finished, so I'll check again before calling it done if you want.
• Not done: the real-Claude re-recording of the two agent-scenarios runs. It's the true end-to-end check and makes paid API calls, so I'll only run it if you ask.

I posted the trail body as the description of PR #2644: https://github.com/entireio/cli/pull/2644

It replaces only Entire's placeholder sentence ("This draft pull request was opened by Entire…"). I kept three things that tools rely on:

• the trail-link block at the top, which keeps the PR and trail connected
• the hidden entire-shadow-pr marker
• the Cursor Bugbot summary, which the bot updates itself

The PR is still a draft, and I didn't change its title or status.

Copilot left two comments. The docs one is valid. The resume one assumes something that doesn't happen, and the same false assumption was behind the earlier review comment I already fixed.

1. "A late duplicate SubagentStop can complete a resumed subagent's record" (rated high)

I ran the dump-only hook probe again (2.1.288, Haiku). It launched a background subagent, waited for it to finish, then continued the same subagent:

A resume goes through the SendMessage tool, not a new Agent call. There's no new tool_use_id and no Agent PostToolUse, so no second task record is ever created for that agent ID. Copilot's scenario needs a finished record and an in-flight record sharing an agent ID, and that can't happen. The earlier reviewer's premise ("a resume reuses the agent ID under a new tool-use ID") is wrong for the same reason.

The probe also found a real gap, which neither this PR nor the code before it handles. The resumed run's SubagentStop finds the already-finished record and is skipped, so its edits (e.txt) aren't credited to the subagent. The transcript is partly saved anyway: the record points at the same agent-<id>.jsonl file, so if the checkpoint is written after the resume, it includes the resumed part. Fixing this would mean treating a second SubagentStart for a known agent ID as a new run. That belongs in a separate change.

What I'd do:

• Keep the in-flight-first lookup. It's harmless with only one record per agent ID.
• Correct its comment. It currently says a resume reuses the agent ID "under a new tool_use_id", which is false.
• Reply to Copilot with the probe results instead of adding duplicate-stop tracking.
• Track the resumed-run gap separately.

2. "Docs describe the old event contract" (rated low)

Valid. Both docs are out of date:

• docs/architecture/agent-guide.md:506 lists ToolUseID as required on SubagentEnd, and it isn't on Claude's SubagentStop. It also doesn't mention SubagentLaunch.
• docs/architecture/sessions-and-checkpoints.md:362-375 says background mode comes from run_in_background: true, and describes SubagentStop as completing "the live record" without explaining how it's found by agent ID.

Next step

I can push one commit with the docs update and the corrected comment, and draft a reply to the first comment for you to review before I post anything. Should I go ahead, and do you want the resumed-run gap added to your priorities list or opened as an issue?

I shelved the resume gap as #MV3YSFR (priority 3, seen 1 time). It's linked to checkpoint 01M41DGV4TCJ2Q2NQ19B99RCQN, so this session's log can be reopened with entire priority explain MV3YSFR. The entry records the problem, the SendMessage hook order from the probe, the likely fix, and that it came up on PR #2644.

My earlier suggestion for the two Copilot comments is still waiting on you. It's one commit with the docs update and the corrected comment, plus a draft reply to the first comment for you to review before I post it. Should I go ahead?

Pushed. Posting the short reply on Copilot's resume comment: