feat: desktop notifications when a Claude session needs input

[ishaankalra]

What

Fires a macOS banner whenever a Claude session blocks on input, titled with the flow task resolved from the payload's session_id. Clicking it brings that tab to the front. Autonomous flow do --auto runs also notify when they finish or die.

Questions asked across many open flow tabs currently go unnoticed and stall tasks — this collapses the discovery gap to a glance and a click.

How it works

• internal/notify — prefers terminal-notifier (a signed .app bundle with its own bundle id, which is what lets -execute attach a click action), degrading to osascript when absent. osascript banners cannot carry a custom action, so the fallback posts without a click; knowing which task is asking is still most of the value.
• flow hook notification — filters to permission_prompt / idle_prompt. The other types (auth_success, elicitation_*, agent_needs_input, agent_completed) would be noise across many tabs. settings.json carries a matcher so Claude Code filters server-side; the in-code check covers a hand-edited config. Always exits 0 — a Notification hook can't block anything, and one that errors every prompt is worse than none.
• flow focus <session-id|task-slug> — the CLI surface the click invokes. FocusSession was previously reachable only from inside flow do.
• Banners group per session, so a chatty task replaces its own banner rather than burying the others.
• flow skill install auto-installs terminal-notifier via brew when missing — soft in every direction (no brew / non-darwin skips it, brew failure warns and continues, delivery re-checks at runtime).

Two pre-existing bugs fixed

1. spawner.FocusSession sent Warp and Ghostty to iTerm2. Its default: arm meant both backends drove iTerm2's AppleScript dictionary despite having working SpawnTab paths — and neither package implemented FocusSession at all. Both now have real implementations, and every backend dispatches explicitly so a new Backend constant can't silently inherit the wrong one.

2. iterm.focusByTTY used tell application "iTerm2", which macOS rejects with -1728 — the bundle registers as "iTerm". SpawnTab always had it right, so iTerm2 click-to-focus could never have worked. Verified against a live session; a regression test now pins both scripts to the same name.

Terminal support

Backend	Click-to-focus
iTerm2, Terminal.app, kitty, zellij	Focuses the exact tab
Ghostty	Works once 1.4.0 ships — the tty property it needs (#11922) isn't in 1.3.x, so it probes and degrades
Warp	Foregrounds the app only — Warp exposes no scripting surface for selecting a tab, so it reports an honest miss rather than claiming a focus

Security

terminal-notifier hands -execute to a shell, so the session id reaching that string is validated against a strict UUID shape rather than quoted. Anything else produces no click action at all, leaving no character a shell could act on. Covered by TestFocusCommandRejectsNonUUID.

Testing

Full suite green, go vet clean. Beyond ~40 new unit tests, verified against real sessions:

• A live session going idle fired the hook organically and produced a correct banner (flow: notify-probe2 / Notify live probe 2 / Claude is waiting for your input).
• Both auto-run branches confirmed with real headless runs — completed and dead (the latter carrying the log path).
• Noise types produce zero banners; malformed payloads exit 0 silently.
• Install/uninstall are idempotent and leave sibling hooks byte-identical.
• tty extraction verified against verbatim ps -axo pid,tty,command output from a live flow do session.

Note for reviewers

Notification payloads carry a generic message ("Claude needs your permission"), so the task name in the title is what identifies the tab, not the body text.

🤖 Generated with Claude Code