Read what a Claude Code notification means before calling it 'needs you' (#306)

[scgopi]

The defect

graphcode's Notification hook for Claude Code reported presence=awaitingInput for every notification, without reading the payload. Claude Code fires a notification about sixty seconds after a turn ends — notification_type: idle_prompt, meaning still idle — so every resting loop flipped to "needs a human" a minute after it stopped, and stayed there. Staged --follow-up messages and Mailroom watch wakes deliver only on presence == idle (deliversLater, drainPendingFollowUps), so for any Claude Code loop idle over a minute — most loops, most of the time — they were parked for good. MailWatcher measured it: two loops flipping at 60.0 s and 60.1 s, 0 of 18 watched posts typed in, all 18 staged.

The change

A notification.sh reporter beside activity.sh and usage.sh — the Notification hook is the one whose meaning depends on its payload. It reads notification_type and maps:

kind	presence	why
idle_prompt	idle (activity cleared)	"still idle" confirms idle rather than leaving it
permission_prompt, elicitation_dialog	awaitingInput	a real question to the human — the state the sidebar shows so a person learns a loop needs them
auth_success	unchanged	says nothing about presence
anything else, or no kind at all	awaitingInput	today's behaviour, on purpose: the mirror failure — a loop that genuinely needs someone, invisible — is worse than the one fixed

The hook command runs the reporter and, if the script is unreadable, falls back to today's report (awaitingInput), never to nothing. Remote hosts are handed the reporter beside the settings that name it, as with the other two scripts.

Audit of what keys off awaitingInput: the drain and deliversLater (the bug); and every NEEDS-YOU surface — the sidebar pill, the canvas attention rail, the titlebar indicator, AttentionRollup — which has therefore been over-reporting for every loop idle past a minute: the second symptom, now gone with the first. MessageBus.deliverability keys on LoopState.awaitingInput (a turn-based check), not on presence, and is unaffected — which is why a plain node send still arrived while --follow-up did not. The OpenCode plugin's question tool and Copilot's log reader map genuine prompts only and are untouched.

Verification

Gate: full Xcode suite (gate on this head in flight; numbers and exit codes in a comment when it completes), swiftlint 0 errors, swift-format clean, graphcoded and graphcode-cli schemes build; SwiftPM build and CLI smoke pass; Linux green.

NotificationPresenceTests runs the real generated reporter under /bin/sh with the payload on stdin against a zmx that records what it was asked to set — the shape PresenceReportingTests established, because the risk is a sed surviving Swift, JSON and shell: idle_prompt → presence=idle with the activity cleared; permission_prompt and elicitation_dialog → awaitingInput; an unknown kind and an absent field → awaitingInput; auth_success → nothing set; no $ZMX_SESSION → nothing set; the hook JSON runs the reporter and falls back to awaitingInput; the remote fragment carries the script. And the end-to-end path MailWatcher measured: a store with a watch armed, a matching post and a --follow-up staged for a busy loop delivers nothing on the presence the reporter writes for a permission prompt, and both on the presence it writes for idle_prompt.

Closes #306. Related: #304 (what the drain then did wrong to the backlog once it ran).

🤖 Generated with Claude Code

https://claude.ai/code/session_01DeGL2CxuGmq16RSZpJYm2N

[scgopi]

Gate on d956d34, private DerivedData: xcodebuild test exit 0 — 1659 tests / 174 suites / 0 failures; graphcode-cli build exit 0; graphcoded build exit 0; swiftlint 0 errors; swift-format clean; Linux green on this head (with the CLI smoke).

The one amendment since opening: the end-to-end test attached a bare /dev/null descriptor for the poll's connection, which the suite's descriptor reuse can drop as "disconnected" so the poll never drains — it passed focused and failed once in a full run. It now attaches through a socketpair with a reader draining it and closes the daemon end through OutboundChannels. Source unchanged.