Handle Claude Code StopFailure Events

I reviewed trail #1477 and I'd approve it. I didn't find any blocking issues.

What it changes: b6b6d4774 touches 2 files (+19/−3). In analyzeRolloutForTurns (cmd/entire/cli/agent/codex/transcript.go:605), a turn_aborted event now ends a Codex turn the same way task_complete does, with the same turn-id checks. Before this, an aborted turn stayed open forever. The next task_started then looked like an overlapping start, so the whole rollout was treated as having no ended turns. The child task never got a CompletedAt before session end.

Why it's correct:

• Consumer: the only code that uses the result is refreshCodexInventory (lifecycle.go:1347). It finalizes a turn only if a native hook already saw that turn ID, and only once (FinalizeSubagentTurn).
• Interrupt, then a new turn: while the new turn is running, the analyzer still reports nothing because a turn is open. That's how a normal multi-turn child already behaves, so this adds no new in-between state.
• Turn IDs: a missing turn_id on the abort is allowed, and a wrong one invalidates the rollout. Both match the task_complete rules and both have tests.
• Coverage: this is the only place that parses turn-end events, so nothing else needs the same fix.
• Tests: go test ./cmd/entire/cli/agent/codex/ passes on the trail head (run in a temporary worktree, since removed). CI is green and the findings gate is clear.

Minor, non-blocking:

1. New strictness on stray aborts. Before, turn_aborted was ignored entirely. Now one that arrives with no open turn invalidates all ended turns in the rollout. That's only a problem if Codex ever writes an abort with no turn open, or writes both turn_aborted and task_complete for one turn. As far as I know Codex writes one or the other, and failing closed fits this function's style. It's still worth knowing the change cuts both ways.
2. Synthetic test data only. The new tests build events with the taskEvent helper, and the repo has no recorded Codex rollout containing a real turn_aborted event. Adding one would confirm that real Codex writes the event to the rollout file with turn_id in the expected shape. Otherwise the fix depends on an assumption about Codex's output.
3. Aborted counts as completed. The task record now gets CompletedAt for an interrupted child, and nothing marks it as aborted rather than finished. That's acceptable for the in-flight bug being fixed, but anything downstream that reads CompletedAt as "succeeded" will be wrong for interrupted children.
4. Nit: the trail has no description. The commit message explains the change well and could be copied in.

I haven't posted anything to the trail. Do you want me to post this as a comment, or approve it?

You're right that an abort isn't a success. But in this codebase, CompletedAt already means "the child has stopped and its record can be saved", not "it succeeded". There's no field anywhere for how it ended, so this PR doesn't create the mislabel. It just applies the existing one earlier.

What happens when a child gets turn_aborted with this PR:

1. analyzeRolloutForTurns reports the aborted turn as ended (transcript.go:605).
2. refreshCodexInventory (lifecycle.go:1347) finalizes that turn, but only if a native hook had already seen that turn ID. If no hook fired for the aborted turn, nothing happens yet.
3. If finalized, the task record gets CompletedAt = now, plus the child's exact file list and token usage as of the abort. Those files are added to the session's FilesTouched.
4. At the next condensation, the record is written to the checkpoint's task.json with completed_at set, then removed from session state (removeCompletedTaskRecords, manual_commit_git.go:555).
5. While it's still pending, entire lists it as "Completed …" (FormatSubagentEndMessage, messages.go:35).

What happens today without the PR:

The record stays shown as running until session end. Then finalizeCodexObservedAtSessionEnd (lifecycle.go:1275) marks it completed anyway, with the same CompletedAt = time.Now(). It also doesn't refresh files or tokens at that point; it keeps whatever earlier turns had captured.

So the aborted child gets labelled "completed" either way. The PR changes when that happens (right away instead of at session end), and the record carries a more accurate file and token snapshot. The bug it fixes is real: one interrupt left the child showing as running for the rest of the session, even if it later resumed and finished.

Where your concern does hold:

• The stored task.json and the pending list can't tell "the user stopped it" apart from "it finished".
• Files the child edited before the interrupt are counted as its work. That's arguably right, since the edits are on disk, but nobody reviewing the checkpoint can see the work was cut off.

If you want the outcome recorded, it would be a separate, larger change. As far as I know, the Codex turn_aborted event carries a reason (e.g. interrupted, replaced), but this code doesn't parse it, and the repo has no recorded rollout to confirm the shape. The change would be:

• add an outcome field to TaskRecord, taskRecordMetadata and the matching API types;
• record the abort and its reason in analyzeRolloutForTurns;
• show "Interrupted" instead of "Completed" in the pending list.

That touches the persisted checkpoint format, so it's a product call. My suggestion: approve #1477 as is, since it's strictly better than today. Raise the outcome field as a follow-up comment on the trail rather than a blocker. Want me to post that comment?

Yes, nothing weird. An aborted child gets the same handling it already gets at session end today. The only differences are that it happens right away, and the record carries the child's file list and token usage as of the abort.

The one gap is the label: it says "Completed", and nothing records that the user interrupted it. That was already true before this PR, so the PR doesn't add it.

No, StopFailure isn't handled anywhere on main. The Claude Code integration installs only SessionStart, SessionEnd, Stop, SubagentStop and UserPromptSubmit (agent/claudecode/hooks.go:184-188), plus the tool-use hooks.

StopFailure also isn't the Claude Code version of turn_aborted. According to the docs, it fires when a turn ends because of an API error: rate limit, overload, auth or billing failure, max output tokens, and similar. It doesn't fire when the user interrupts. It's observe-only, since its output and exit code are ignored, and the docs don't say whether it fires for subagents. The docs also don't say what fires when the user presses Esc.

What we do today when a Claude Code turn ends without Stop, whether from an API error or an interrupt:

• The session stays ACTIVE. Nothing is condensed at that point.
• The next UserPromptSubmit is treated as "Ctrl-C recovery: agent crashed or user interrupted mid-turn" (session/phase.go:195). The session stays ACTIVE and the new turn simply carries on.
• If no prompt follows, the session end path picks it up. That includes the existing check for an agent that "died without a stop hook" (lifecycle.go:301).

So nothing is lost, but the failed turn's checkpoint waits for the next prompt or session end, just like an interrupt.

What handling it would add: you could map StopFailure to EventTurnEnd. The turn would then close and condense right away instead of waiting for the next prompt. It's a small change: one hook entry plus a handler that reuses the stop path. One open question is whether to save a checkpoint for a turn that failed partway, possibly with half-applied edits. I'd say yes, because the file changes are real either way.

I haven't checked how subagents behave on interrupts or API errors, which would be the closer Claude Code parallel to #1477. Want me to look into that, or draft the StopFailure change?

Yes, you're right, and that's the real cost of not handling StopFailure. After an API error, Claude Code is waiting for the user's next prompt, so the session should be IDLE. Not ENDED, though, because the session is still open. Entire never gets a turn-end event, so it keeps the session ACTIVE until the next prompt or session end.

Consequences of a session stuck in ACTIVE:

• Turn-end work is skipped. Whatever normally runs on Stop doesn't run for the failed turn. That includes saving the turn's checkpoint step and marking the session idle. Those edits are picked up later: on the next turn, at a commit, or at session end.
• Commits treat it as a session that's still producing work. shouldCondenseWithOverlapCheck (manual_commit_hooks.go:943) gives an ACTIVE session with recent activity live-session handling. That includes the read-only skip rule and the overlap logic. The 24h freshness check on LastInteractionTime keeps this from lasting forever, but in the meantime the session looks live.
• Shadow branches stay pinned. An ACTIVE session that hasn't been condensed keeps its shadow branch around after a commit (manual_commit_hooks.go:1789). The comment there describes this same "ghost ACTIVE session" problem seen with Antigravity.
• What users see is wrong. doctor, clean, attach and the resume picker all check IsActive(), so they report a session as active when the agent is really idle after an error.

None of this loses data. The next UserPromptSubmit goes through the "Ctrl-C recovery" path (ACTIVE to ACTIVE), and session end tidies up. The cost is that the session state is wrong in between, and for a rate limit or billing error that could be a long time.

So handling StopFailure is worth doing. It's a small change: install the hook and send it through the same turn-end path as Stop, so the session goes to IDLE and the turn's step is saved. A user interrupt (Esc) may leave the same gap, but the docs don't say what fires then. I'd need to test that in a real Claude Code session.

Want me to draft the StopFailure change on a branch?

I've opened the PR: https://github.com/entireio/cli/pull/2656 (branch victor/claude-stop-failure, one commit). Like #1477, it's a small change: Entire now listens for StopFailure and treats it the same as Stop, so a turn that ends on an API error ends cleanly.

What changed:

• New hook: a stop-failure hook verb that ends the turn, which moves the session from ACTIVE to IDLE (agent/claudecode/lifecycle.go).
• Install/uninstall: entire enable installs it and uninstall removes it. I also added it to the repo's own .claude/settings.json; an existing test fails if that file is out of date.
• Drift check: a settings file without the StopFailure hook now shows as outdated. That's how a missing SubagentStop is already handled, but it means every existing install will be flagged until someone re-runs entire enable. I called this out in the PR as a product decision.
• Tests and docs: new parse and drift tests, the integration test's hook count goes from 8 to 9, and the TurnEnd row in the agent guide now lists the new verb.
• Timing: if Claude Code doesn't write its end-of-turn marker after an API error, Entire waits at most 3 seconds for the transcript to settle, so the hook can't hang.

Verification: lint is clean and mise run test:ci passes except one test, TestPlugin_SpawnsHooksUnderNode (opencode). It fails because the local mise setup has no node version configured, and it fails the same way on main, so it's unrelated. It should pass in CI.

The trail and its agent findings don't exist yet; the trail should appear once the PR syncs. A background job is watching for it. When the review finishes, I'll fix any real findings and resolve them.

Not covered: what Claude Code fires when the user presses Esc. The docs don't say, so that needs a test in a real session.

The agent review on the new trail (#1480) found nothing: the findings gate passed with no findings. When I checked, CI was still running (7 passed, 9 running, 0 failed of 16).

PR: https://github.com/entireio/cli/pull/2656

Copilot left two comments on PR #2656; I've replied to both on GitHub and resolved both threads.

1. "Only add StopFailure on Claude Code 2.1.78+" (rated high): I didn't change the code, since we only support the latest agent version. My reply says Entire currently targets the latest Claude Code release, which has StopFailure (added in 2.1.78), and that we aren't detecting older or pinned versions for now.
2. "Test that uninstall removes the new hook" (rated low): fixed and pushed as b8be384b4. TestUninstallHooks now checks the StopFailure hook is there before uninstall and gone after. I removed the cleanup line temporarily and the new check failed, so it guards against that.

Lint is clean. mise run test:ci has the same single local failure as before, the opencode test that needs a node version configured in mise. A background job is waiting for the trail's agent review of the new commit to finish.

Yes, both GitHub review threads on #2656 are resolved: the version-gating one and the uninstall-test one.

The trail isn't finished yet. Its agent review of the new head (b8be384b) is still pending, and so far it has no findings. CI was also still running (2 passed, 13 running, 0 failed). A background job will tell me when the review finishes, and I'll fix and resolve anything it flags.

Another Claude session reviewed trail #1480 and found no bugs. Its two "before approval" items were already handled before the review arrived:

1. Uninstall test: already pushed in b8be384b4.
2. Older Claude Code versions: you decided we support only the latest release, so there's still no version check.

I made its smaller suggestions and pushed them as 93a81c71b:

• Integration test: TestStopFailure_EndsTurn sends a prompt, then the stop-failure hook, and checks the session ends IDLE with one step saved. With the new hook mapping removed, it fails with the original bug: the session stays "active" instead of "idle".
• Transcript wait: before reading the transcript, Entire looks for the text "hooks claude-code stop". That text also matches stop-failure, which is what we want. I added a comment saying so and a test that fails if someone later tightens the match.
• Tidy-ups: the two "missing hook makes the config outdated" tests are now one table test that starts from a real install. The agent-guide table cell now reads "stop, stop-failure".
• Trail description: I wrote one; the trail had none.

I sent the reviewing session a summary of the above.

Lint is clean. mise run test:ci has the same single local failure as before: the opencode node test, which also fails on main.

Still waiting on:

• Findings: the trail's agent review of 93a81c71b. I'm watching for it and will fix anything it flags.
• Approval: the only failing gate. It needs a reviewer to approve.

The reviewing session checked 93a81c71b: all its points are addressed and it has nothing more to raise. It had missed b8be384b4 because it was reading an out-of-date copy of the branch.

Still open on trail #1480:

• CI and the agent review: both still running on the new commit. A background job is watching the review and will tell me when it finishes.
• Approval: the trail needs a human reviewer to approve it.

The agent review of 93a81c71b on trail #1480 passed with no findings. When I checked, CI was still running (5 passed, 10 running, 0 failed). The approval gate is the only one failing; it needs a human reviewer.

PR: https://github.com/entireio/cli/pull/2656

All three points are fair. Here's where I land on each. I haven't changed anything.

1. Transcript-wait comment and test: correct, and that's my mistake. I checked locally: none of the 60 most recent Claude Code transcripts on this machine (Claude Code 2.1.289) contain a hook_progress entry. So the "hooks claude-code stop" marker the wait looks for never shows up, and both Stop and StopFailure always use the "file size stopped changing" fallback. The existing comment on the wait already admits the marker is "not reliably present". I took the earlier reviewer's suggestion without checking whether that code path ever runs.

The comment I added, saying API-error turns "flush the same way", describes something never observed. The test protects a speedup that can't happen. I'd:

• reword the comment to say the marker is legacy and the fallback is what actually runs;
• drop TestCheckStopSentinel_MatchesBothTurnEndHooks.

Removing the marker check entirely is a fair cleanup, but it belongs in its own PR, not this one.

2. Stale PR body: correct. I wrote it with the first commit and only updated the trail description afterwards. The PR's Testing section is missing:

• the integration test;
• the uninstall assertion;
• the "latest Claude Code only, StopFailure since 2.1.78" decision.

The fix is to copy the trail description into the PR body.

3. "Outdated" on existing installs: still your call. I'd keep it.

• Why keep it: that warning is the only thing that tells existing users to re-run entire enable. Without it, nothing tells existing users to pick up the new hook, so they'd keep hitting the stuck-ACTIVE bug. It's also how the SubagentStop hook was rolled out.
• Cost: a one-time warning in status and doctor for everyone with Claude Code installed, cleared by re-running entire enable.
• Alternative: only flag it as outdated after a delay, or leave it unflagged. That's quieter, but most users would never get the fix.

If you agree, I'll make the changes for points 1 and 2 and note the decision on point 3 in the PR.

Yes, one item still needs a code change. PR #2656 was merged on 2026-10-05 with its three commits, so none of the feedback was acted on before merge.

1. Misleading transcript-wait comment and test (worth a small follow-up PR). Both are on main:

   • the comment at cmd/entire/cli/agent/claudecode/lifecycle.go:276, claiming API-error turns "flush the same way";
   • TestCheckStopSentinel_MatchesBothTurnEndHooks in lifecycle_test.go:687.

   The 60 recent transcripts I checked contain no hook_progress entries at all. So the "hooks claude-code stop" marker the wait looks for never appears, and every turn uses the "file size stopped changing" fallback. The follow-up would reword the comment to say the marker is legacy and the fallback is what actually runs, and delete the test. Removing the marker check entirely could go in the same PR or its own.

2. Stale PR body: nothing to fix now. The merged PR still only lists the 8→9 install count under testing. The trail description has the full picture, so the record exists; editing a merged PR's text adds little.

3. "Outdated" warning on existing installs: decided by the merge. Every existing Claude Code install will now show as outdated in status and doctor until the user re-runs entire enable. Two things to watch:

   • The release notes should tell users to re-run entire enable, so the warning doesn't look like a regression. Your memory notes the 0.11.4 changelog is in progress, so this could go there.
   • If the warning turns out too noisy, soften it later. That would be a separate change.

Want me to open the PR for item 1?

I opened the follow-up PR: https://github.com/entireio/cli/pull/2678 (branch victor/stop-sentinel-comment, one commit).

What it changes:

• Comment reworded: the comments in claudecode/lifecycle.go now call the "hooks claude-code stop" marker a legacy shortcut. They also say current Claude Code no longer writes it, so the "file size stopped changing" fallback is what ends the wait for both Stop and StopFailure.
• Test removed: TestCheckStopSentinel_MatchesBothTurnEndHooks is gone, since it protected a shortcut that never runs.

It doesn't change behavior. Removing the marker check itself is left out, as a separate decision.

Lint is clean. mise run test:ci has the same single local failure as before, the opencode test that needs a node version configured in mise.

I'm still waiting on the trail's agent review of this branch. A background job is watching it, and I'll fix anything it flags.

The agent review of the follow-up PR passed with no findings (trail #1499). When I checked, CI was still running (7 passed, 10 running, 0 failed). It needs a reviewer's approval to merge.

PR: https://github.com/entireio/cli/pull/2678

The feedback (point 1 of the review you pasted): #2656 added a comment and a test about the transcript wait, and both described something that never happens.

• When a turn ends, Entire waits for Claude Code to finish writing the transcript. One way it can tell is by spotting a marker line containing "hooks claude-code stop". That marker would also match stop-failure.
• My comment claimed this was on purpose, so API-error turns would end the wait the same quick way. My test, TestCheckStopSentinel_MatchesBothTurnEndHooks, checked that both verbs match.
• The reviewer pointed out that current Claude Code doesn't write that marker line at all. They found none in 60 recent transcripts, and none in 40 earlier ones on Claude Code 2.1.231. I checked 60 recent transcripts here on 2.1.289 and also found none.
• So the wait always ends the other way: when the file size stops changing. The comment described something never observed, and the test protected a shortcut that never runs.

My change (#2678, comments and test only, no behavior change):

• Comments in claudecode/lifecycle.go: they now call the marker a legacy shortcut that current Claude Code no longer writes. They say the "file size stopped changing" check is what ends the wait, for both Stop and StopFailure.
• Test: TestCheckStopSentinel_MatchesBothTurnEndHooks is removed.
• Not done: removing the marker check itself. I left it out of this PR as a separate decision.

Right, I didn't remove it, and the feedback didn't ask for that. Its suggestion, quoted: "I'd remove both, or reword the comment to say the sentinel is legacy and the fallback is what actually runs." "Both" meant the comment and the test I added in #2656, not the marker check in the code. I took the second option for the comment and deleted the test.

Removing the marker check itself (stopHookSentinel and checkStopSentinel in claudecode/lifecycle.go) was my own suggestion. I kept it out to keep #2678 to comments and tests only.

Removing it is reasonable, though:

• For: since we only support the latest Claude Code, and current versions never write the marker, the check is dead code. Each turn end still reads the end of the transcript every 50ms looking for a line that never appears.
• Against: none in practice. It would only matter for an old Claude Code version that still writes the marker, and those aren't supported. Those versions would still end the wait, just through the slower "file size stopped changing" check.

Want me to add the removal to #2678? It's a small change: delete the constant and the function, drop the call in the wait loop, and update the comments to match.

No, "never used" isn't right. The marker did its job at one point; current Claude Code just stopped writing it.

Evidence it was used:

• It was added in 3c906fdf7 (2026-02-09). The commit message says Claude Code "writes a hook_progress entry to the transcript when launching hooks."
• A real Claude Code transcript stored as a test fixture (transcript/compact/testdata/claude_full.jsonl, Claude Code 2.1.78, March 2026) contains three Stop entries whose command is exactly entire hooks claude-code stop. So on 2.1.78, the check could find the marker.

Evidence it's gone now:

• I searched all 113 Claude Code transcripts on this machine, which cover versions 2.1.281 to 2.1.291 (since Sep 24). None contain a hook_progress entry.
• That matches the reviewer's finding of none in 40 transcripts on 2.1.231.

When it stopped: the transcripts can't pin it down, because there's nothing local between 2.1.78 and 2.1.281. The Claude Code changelog has no entry saying hook progress is no longer written. The most likely cause is in 2.1.97: "Improved session transcript size by skipping empty hook entries". Entire's hooks print nothing, so their progress entries would count as empty. That's an inference, not confirmed.

What this means:

• The PR's comment is accurate: the marker is a legacy shortcut that current Claude Code doesn't write.
• My earlier summary to you overstated the reviewer's point. "Never observed on current versions" is right; "never used" is not.
• Removing the check is still safe, since we only support the latest Claude Code. On an old version that still writes the marker, the wait would end through the slower file-size check, usually within a second.

Should I add the removal to #2678, or leave the PR as comments and tests only?

Here's the plain version, since I muddled it before.

What the code does. When a Claude Code turn ends, Entire has to wait for Claude Code to finish writing the transcript file before reading it. That wait is waitForTranscriptFlush in claudecode/lifecycle.go. It has two ways to decide the file is done:

1. Marker check (legacy): read the last 4KB of the transcript and look for a line containing hooks claude-code stop. Claude Code 2.1.78 wrote that line when it ran our Stop hook. Current Claude Code doesn't write it, so this check runs every 50ms and never finds anything.
2. Size check (what actually runs): if the file size hasn't changed for 500ms, assume it's done. This is what ends every wait today.

"Legacy" means only #1.

What to delete, all in cmd/entire/cli/agent/claudecode/lifecycle.go:

• the stopHookSentinel constant (line 278);
• the checkStopSentinel function (line 376 onward, about 45 lines);
• the call to it inside the wait loop (lines 340–347);
• the tailBytes and maxSkew constants, which only that check uses;
• the comment text describing the marker.

What stays: the size check, the 3s maximum wait, and the "file is old or missing, skip waiting" shortcut. The hookStartTime parameter stays too, because the debug logs use it.

Effect: none on current Claude Code, because the deleted check never finds the marker now. It only removes a file read every 50ms during each turn end. The test I already removed in #2678 was the only test for the marker check, so no other tests change.

Want me to add this deletion to #2678?

No, the hook calls are still in the transcript, and the stop text is too. I had this wrong: Claude Code changed the entry format, not whether hooks get recorded.

What's in a current transcript (Claude Code 2.1.289, from this session):

• Stop hook: a system entry with subtype stop_hook_summary. It lists each hook that ran, with its full command (… exec entire hooks claude-code stop), how long it took (durationMs: 625), any errors, and so on.
• SessionStart and UserPromptSubmit hooks: hook_success entries with the command, stdout, stderr and exit code.
• Gone: the old hook_progress entries ("hook started"). That's the only change.

Why the marker check still never fires, even though the text is there. The check looks for any line containing hooks claude-code stop, and the new summary entry does contain it. But the summary is written after our Stop hook finishes; that's why it can record the duration. The marker check runs inside our Stop hook, so the summary for the current turn never exists yet while we're looking. The old hook_progress entry was written when the hook started, which is why it could work then.

One edge case that favours deleting it. The check accepts any matching line timestamped within 2 seconds of when the hook started. If a turn ends less than about 2 seconds after the previous turn's Stop hook finished, it could match the previous turn's summary. The wait would then end immediately, possibly before the transcript is fully written. That's unlikely, since it needs a very fast turn, but it's a way for this dead code to do harm, not just nothing.

So the conclusion is the same, for a more accurate reason. The marker check can't help on current Claude Code, and in that rare case it could end the wait too early. Delete the constant, the function and its call, and keep the file-size check.

Should I add the deletion to #2678, with the PR description fixed to say "the text now only appears after the hook finishes" rather than "Claude Code doesn't write it"?

Yes, and it's better than the old marker. Current Claude Code gives a direct signal for "the turn's final message has been written".

The signal:

• The Stop hook payload names the final message. According to the hooks docs, the payload now includes last_assistant_message, and that object has the message's id (msg_…) and its content blocks.
• The transcript records that same id. Every assistant entry carries message.id, and the last ones in a turn have stop_reason: "end_turn". In this session's transcript, every turn ended the same way: one or two end_turn entries sharing one message id, written 50 to 700ms before the Stop hook ran.

So the wait can watch the end of the transcript until entries with that exact id appear. One detail: a message is written as one entry per content block (for example, thinking and then text), and the entries share the id. To be sure the whole message is there, count the entries with that id until the count matches the number of blocks in last_assistant_message.content.

Why it's better than what we have:

• Old marker: gone from current Claude Code, and in the rare fast-turn case it can match the previous turn's summary.
• File-size check: only a guess. A pause of more than 500ms mid-write would be mistaken for "done", and it always costs at least 500ms.
• Message id: names exactly what must be on disk, so the wait can end as soon as it's there, usually immediately, since the entries land before the hook runs.

Things to know:

• Payload shape is unverified. The last_assistant_message shape comes from the docs. I haven't seen a real Stop payload, because Entire doesn't log it. The first step would be to confirm it on 2.1.289 by logging the payload's field names at debug level, like the subagent-stop handler already does.
• StopFailure probably won't have it. A turn that ended on an API error may have no final message. Keep the file-size check as the fallback whenever the field is missing or never matches. The 3s maximum stays as it is.
• Claude Code's own advice: the docs say the transcript "may lag" when hooks run, and suggest reading last_assistant_message from the payload instead. Entire needs the whole transcript for the checkpoint, so waiting for the id to appear is the right use of it.

Suggested plan: turn #2678 into "replace the stop marker with a message-id check".

1. Delete the old marker check, as discussed.
2. Parse last_assistant_message (its id and number of content blocks) from the Stop payload into the event.
3. In the wait loop, return as soon as the end of the transcript has every entry for that id.
4. Fall back to the file-size check when the id is missing or never appears.
5. Add tests for: the id found, an incomplete message, no id (StopFailure), and an old-format transcript.

That's a behavior change, not just a cleanup, so it needs your go-ahead. Should I do it in #2678, or keep #2678 as comments only and do this as a separate PR?

I've pushed the change to #2678 as 3cc1d593e and updated the PR title and description: https://github.com/entireio/cli/pull/2678

The plan changed partway: there's no message id. I captured a real Stop payload from a one-line Haiku run on Claude Code 2.1.291. last_assistant_message is just the final text as a string ("ok"). The docs summary I'd relied on, which said it was an object with an id, was wrong. So the check matches on text instead.

How it works now:

• New check: the wait ends as soon as the end of the transcript holds a final (end_turn) assistant entry whose text matches last_assistant_message, with no user entry after it. A later user entry, whether a prompt or a tool result, means another step followed. That's how it avoids matching a previous turn that ended with the same words.
• Fallback, unchanged: the "file size unchanged for 500ms" check and the 3s maximum still apply. They cover StopFailure (which has no final text), the other callers that don't come through the Stop hook, and any case where the entry isn't found.
• Deleted: the old marker constant and its check. This also removes the rare case where a previous turn's summary entry could end the wait too early.
• Plumbing: the wait didn't have access to the payload. Turn end now uses a new capability, TurnEndTranscriptPreparer, that only built-in agents can implement, and it receives the event. The event gains one field, FinalAssistantText. If the field arrives in an unexpected shape, it's ignored and the hook doesn't fail.

Testing:

• New tests: cover the transcript cases (the message written; only part of it written; the turn still on tool calls; the previous turn ending with the same words; a partly written line), payload parsing, and the final message ending the wait while the file keeps growing.
• Checking the tests catch real bugs: removing the "user entry after it" rule makes the previous-turn test fail.
• Real data: on the real 2.1.291 transcript, the check matches the right text and rejects other text.
• Suite: lint is clean, and test:ci has only the known local opencode node failure.

The trail's agent review of the new commit is still running. A background job is watching it, and I'll fix anything it flags.

The trail review on #2678 found one low-severity issue, which I've fixed in dade73c27 and resolved on the trail.

The finding: the transcript check accepted a match if any final text block matched the end of last_assistant_message. That meant an earlier block could still count after a later, different block had been written. Claude Code writes one block per entry today, so this was unlikely in practice, but the rule was wrong.

The fix: the most recent final text block in the transcript now decides the result, so a later block that doesn't match cancels an earlier match. I added two test cases: a later block in the same entry, and a later entry. Both fail on the previous code and pass now.

Lint is clean, and test:ci has only the known local opencode node failure. A background job is watching the trail's re-review of the new commit.

The trail's re-review on #2678 raised a second, medium-severity finding. I've fixed it in e7b84035e and resolved it.

The finding: if the turn's final text matched, and an entry from a later assistant message came after it, the match still counted. That later entry could be thinking-only or a tool call, and either means the matched message wasn't the turn's last.

The fix: each assistant message has an id that all of its entries share. Any entry with a different id now clears an earlier match. Further entries of the matched message itself keep it. That matters because real transcripts write a message's thinking entry before its text entry.

Testing:

• New test cases: a later message that starts with thinking, a later tool call, and a trailing entry of the matched message. The first two fail on the previous code and all three pass now.
• Real data: the real 2.1.291 transcript still matches the right text and rejects other text.
• Suite: lint is clean, and test:ci has only the known local opencode node failure.

The re-review of e7b84035e is still running in the background, and I'll handle anything it raises.