docs(specs): background handoffs with in-place review and notifications

[philmerrell]

Summary

A UX pass on docs/specs/agent-handoffs-and-consults.md, the plan for carrying a mid-thread @-mention's work into an Agent's conversation. Docs only; nothing is built yet.

• Renamed "task chips" to handoffs. Shared Projects already uses "task" for a conversation (Tasks tab, "New task", SHARED_TASK#), so a handoff started inside a project task would have put two kinds of "task" on one screen. The spec now uses HANDOFF#, /sessions/{id}/handoffs, HANDOFFS_ENABLED / FEATURES.handoffs and suggest_handoff (new §4.0 glossary).
• Review in place, then run in the background. A mid-thread mention opens a review sheet above the composer: editable request, a collapsible context card, and a full-prompt preview pinned to what the server sends. On Send the target conversation starts as a second stream in the same tab and the user stays in the original thread. No session is created until Send, so cancelling leaves nothing behind.
• A handoff row in the original thread shows running / needs your input / done / stopped and offers Bring back result. It is display-only and never enters the model's history, so the source's cached prefix is untouched.
• Notifications, in three layers: toast and unread dot; the existing Projects in-app inbox (the bell), with new handoff_needs_input / handoff_done / handoff_stopped kinds; and local browser notifications (Notification API) while the page is hidden. Web Push is a follow-up, to be built once with scheduled runs.
• Stated limits. A background handoff lives as long as its tab; a dropped stream is persisted as interrupted and shows as stopped. Durable handoffs need the headless run entrypoint and are a follow-up.
• The Phase 1 gate (§7) now asks whether users bring results back without first opening the target, since background handoffs plus Bring back already cover most of a consult.

Flagged for implementation

• The OAuth, tool-approval, quota and error prompt services must be confirmed to scope to their own session, so a target's prompt never renders over the original thread.
• inference-api needs a new PutItem grant limited to INBOX# rows on the projects table, and the sidenav bell must show with features.handoffs, not only features.projects.

Test plan

• Read-through of §4.0–§4.7, §7, §9 and §10 for consistency with the rest of the spec
• Agree the §7 gate thresholds before Phase 0 ships (open question 6)

🤖 Generated with Claude Code