fix: stale PostToolUse notifications and background task output leak

[timvisher-dd]

Problem

Two independent bugs caused stale or garbled output in ACP clients (agent-shell):

1. PostToolUse hook race: The SDK fires PostToolUse hooks ~42ms before the streaming handler registers callbacks, causing "No onPostToolUseHook found" errors and lost session/update notifications. For subagent child tool uses, the gap is 10-60+ seconds.

2. Background task output leak: When a run_in_background Bash task completes, the SDK emits a task_notification followed by an internal model turn after the result message. prompt() returned at the first result, leaving the internal turn in the iterator buffer. The next prompt() call processed stale background task output instead of the user's actual input — the model responded to its own background task completion rather than "yes".

Root Cause Analysis

Bug 1: PostToolUse hook timing

The SDK fires hooks synchronously from its tool execution path, but streaming events that trigger registerHookCallback() are consumed asynchronously from the query iterator. For fast tools, the hook fires before the content_block_start event is processed (~42ms gap). For subagent child tools, the gap is 10-60+ seconds because messages are relayed only when the subagent finishes.

Bug 2: SDK internal turns from background tasks

Reading the minified SDK source revealed the root cause: the SDK's iP() function (minified; likely hasRunningDeferrableTasks() or shouldDeferResult() based on usage) checks whether to defer the result message for running background tasks, but only includes local_agent tasks — NOT local_bash tasks. Similarly, the internal queue class q4 (likely InputStreamQueue or MessageBuffer) is where we peek for buffered task_notification messages. When a background Bash task completes after the turn's result, the SDK emits:

[148] result/success         ← prompt() returns here (premature)
[149] system/task_notification ← bg task completed
[150] system/init            ← internal turn starts
[151-167] stream_event deltas ← model responds to task completion
[168] assistant message
[172] result/success         ← internal turn ends (leaked to next prompt)

Verified: the Claude TUI hides this by rendering internal turns inline, but ACP clients can't — they see the stale output on the next prompt.

Independence Proof

Empirically verified both fixes are independently necessary:

• Reverted fire-and-stash → 10 PostToolUse tests fail, bg-task-leak tests pass
• Reverted internal turn fix → bg-task-leak tests fail, PostToolUse tests pass

Fix 1: Non-blocking fire-and-stash (tools.ts)

When the hook fires before registration:

1. Stash { toolInput, toolResponse } and return { continue: true } immediately
2. When registerHookCallback() runs later, find stash, execute callback, clean up
3. Periodic sweep (60s, 5min TTL, unref()) cleans orphaned entries

Handles both the 42ms race and 10-60s subagent delay with zero blocking.

Fix 2: Internal turn consumption (acp-agent.ts)

After receiving a result/success:

1. Track local_bash background tasks via task_started messages (ignore local_agent — SDK handles those)
2. Yield to event loop (setTimeout(0) macrotask) to let the SDK enqueue task_notification
3. Peek at SDK's internal queue (inputStream.queue[0]) for task_notification
4. If found: save the prompt response, continue consuming the internal turn
5. If not found: log warning with task IDs, return (best-effort — upstream SDK fix needed)

Known limitation

The setTimeout(0) yield is best-effort. If task_notification arrives later than one macrotask tick, the internal turn can still leak. A warning is logged with the unresolved task IDs for observability. The proper fix requires an upstream SDK change to either defer local_bash results (like local_agent) or expose an idle/hasPending signal on the Query interface.

Changes

Source

• src/tools.ts: Fire-and-stash mechanism replacing blocking Promise.race
• src/acp-agent.ts: Internal turn detection (task_started tracking, queue peek, savedPromptResponse)
• src/embed.d.ts: Type declaration shim for single-file bun build module

Tests (151 pass, 0 flaky)

• src/tests/bg-task-leak.test.ts (13 tests): Full SDK message sequence from real trace data
  • Sync/async internal turn consumption
  • Cross-prompt stale message isolation
  • local_agent vs local_bash filtering
  • Warning path (notification never arrives)
  • Terminal statuses (completed/failed/stopped)
  • error_during_execution known limitation
  • Multiple back-to-back internal turns
• src/tests/tools.test.ts (10 new tests): Fire-and-stash contract
  • Happy path, 42ms race, subagent delay, batch, error handling
  • All deterministic (fake timers + microtask flushing, zero real delays)

Infrastructure

• bin/test: Local CI mirror — parses .github/workflows/ci.yml with yq
• src/tests/authorization.test.ts: Type fix for auth extension property
• Build fixes: SDK import path correction, embed module declaration

E2E Verification

Standalone harness (x.bg-task-leak-harness.mjs) spawns real ACP agent, launches background Bash tasks via subagents, and validates Turn B responds to "yes" (not stale background output):

• Pre-fix: 3/3 leak detected — Turn B returned in 1ms with "The background task completed... still waiting on your answer"
• Post-fix: 3/3 clean — Turn B returned in 9-19s with file creation tool calls

Risk

Low for fire-and-stash: Happy path unchanged. Stash path replaces 5s block with immediate return.

Medium for internal turn fix: Accesses SDK internals (inputStream.queue) not in public API. The task_type === "local_bash" filter relies on an untyped SDK field verified by reading the minified SDK source. Both are documented as workarounds pending upstream SDK changes.

Test plan

• bin/test — format, lint, build (0 errors), 151 tests pass
• E2E harness: 3/3 iterations clean (background task consumed during Turn A)
• 4 rounds of Codex review — all findings addressed or documented as known limitations
• Fire-and-stash independence empirically proven (revert → 10 tests fail)
• Manual: verify no [hook-trace] errors in agent-shell during subagent workloads
• Upstream: file SDK issue for local_bash result deferral

[benbrandt]

@timvisher-dd how did you testing go/

[timvisher-dd]

@timvisher-dd how did you testing go/

Still working through it! Do you mind if I leave this open in Draft?

[benbrandt]

All good, thanks for testing!

[timvisher-dd]

@benbrandt I'd like to do a bit of manual testing tomorrow with this change but I'm confident that it's directionally correct. Does that seem right to you?

[timvisher-dd]

@benbrandt This is feeling pretty good to me. Definitely give it a critical eye because it's a whack-a-mole style problem but I've been running it all day in this state and haven't seen a spurious Notice or odd shell behavior from agent-shell.

[timvisher-dd]

Actually I guess I take that back again. Even on my dev integration branches I still see problems with this every now and then. I'm clearly not understanding the full scope of the interactions. I'll drop this back to draft because it's helpful to remind me to keep pressing on it it but if y'all'd rather it be closed for now I'd be fine with that, too. Sorry for the noise here. (－‸ლ)

[timvisher-dd]

Actually I guess I take that back again. Even on my dev integration branches I still see problems with this every now and then. I'm clearly not understanding the full scope of the interactions. I'll drop this back to draft because it's helpful to remind me to keep pressing on it it but if y'all'd rather it be closed for now I'd be fine with that, too. Sorry for the noise here. (－‸ლ)

LOL globdammit actually I think the issue was that my local integration branch wasn't including this fix this morning. (ﾉಥ益ಥ）ﾉ ┻━┻

[timvisher-dd]

@benbrandt The latest code here is behaving promisingly. I think I may finally have cracked something. xD