# Agent Attention Prompts: Design Exploration (https://jackin.tailrocks.com/reference/research/agent-orchestration/agent-attention-prompts-design/) **Status**: Design exploration for [Agent attention prompts](/roadmap/agent-attention-prompts/) (Phase 2, Reactive Daemon Program) — not yet implemented. ## Problem [#problem] The biggest hidden cost of running AI coding agents today is idle wall-clock. Agents finish work, hit a confirmation prompt, run into an ambiguous decision, or stop on a long-running command and silently wait for the operator to come back to the terminal. The operator, meanwhile, is heads-down on something else — reviewing a PR, in a meeting, on another machine — with no signal that anything wants their attention. Every minute the agent waits is a minute of compounding throughput loss across however many agents the operator is running in parallel. The point of jackin❯ is to make running many agents safe and convenient; "many agents" is only a real win if the operator can stay in flow and only context-switch when an agent actually needs them. The proposal: an opt-in, per-workspace, per-role notification channel that fires a host-side OS notification when an agent inside a Capsule-managed role container is waiting on operator input, with optional escalation to sound and a click action that focuses the right terminal tab. ## What the operator gets [#what-the-operator-gets] The end state, from the operator's seat: 1. A passive notification, on the host, when an agent stops to wait. macOS Notification Center / Linux desktop notification / Windows toast. Title names the workspace, role, and (optionally) the question the agent is asking. No visible jackin window required — the operator can be anywhere on the host. 2. Optional escalation: when the operator has set a per-workspace policy "if I don't respond in N seconds, start playing a sound", jackin❯ escalates from a silent toast to an audible cue. Configurable per workspace and per role; off by default. 3. Click-to-focus: clicking the notification opens or focuses the terminal tab the agent is running in. The Desktop Agent Hub v1 should wire this for Ghostty first; kitty, iTerm2, WezTerm, gnome-terminal, and other adapters are later additions once the Ghostty contract is solid. 4. Per-workspace mute: operators in deep-focus mode can mute notifications for a workspace temporarily without losing the launch-time policy. 5. Per-axis toggle: notify on idle waiting, on agent finished work, on sensitive-mount confirmation requested, etc. — operators choose which classes of attention prompts they care about. ## How jackin❯ knows "I'm waiting" [#how-jackin-knows-im-waiting] Attention prompts should not own state detection. They consume the [agent runtime status authority](/roadmap/agent-runtime-status/), which runs inside `jackin-capsule` and arbitrates semantic runtime reports, foreground-process ownership, visible-screen signals, shell markers, OSC evidence, process evidence, and output recency as watchdog input. A notification should fire only after that authority produces an effective `blocked` or derived `done` transition. This avoids the failure mode where a notification feature invents its own "no output for N seconds means waiting" heuristic. Silence is evidence, not truth. The state authority is the single place that decides whether a quiet agent is blocked, still working, idle, done, unknown, or stuck. The proposed `jackin-attention` MCP server is useful only as an enrichment channel, not the state source. It would let an agent attach reason text, urgency, or "ready for review" context to the current state: * `attention.note(reason: string, urgency?: low | normal | high)` — attach operator-facing context to a pending `blocked` or `done` transition. * `attention.clear()` — clear the note when it no longer applies. If a runtime cannot report semantic state through hooks/plugins and cannot use the MCP enrichment path, jackin❯ would still fall back to the in-container process/screen detector. Unsupported agents remain usable; they just produce fewer high-confidence notifications. ## How the notification would reach the host [#how-the-notification-would-reach-the-host] The proposed pieces: * **Agent-state event stream.** `jackin-capsule` emits effective state transitions over the per-container control channel. The daemon would subscribe to `blocked`, `done`, `idle`, `working`, and stuck-diagnostic events instead of scraping PTY output from the host. * **Optional `jackin-attention` MCP server.** Static binary baked into the construct image, registered automatically in each agent's MCP config at container launch — extending the registration pattern already uses for the Claude runtime's `tirith` / `shellfirm` to every supported runtime. When the agent adds attention context, the MCP server would push metadata over the same per-container control channel. It would not replace the state authority. * **The jackin❯ daemon dispatches the host-side notification.** Per the [jackin❯ daemon](/roadmap/jackin-daemon/) plug-in surface, this feature is one adapter that listens for state/attention events from any running container and translates them to OS-native notifications: macOS via `osascript -e 'display notification …'` or the `UserNotifications` framework via a small Swift helper (sound escalation via `afplay` / `NSSound`); Linux via `notify-send` (libnotify) or the org.freedesktop.Notifications D-Bus API (sound via `paplay` / `aplay`); Windows out of scope for the first phase. * **Click-to-focus adapter.** The notification would carry an action that, when activated, runs a host-side command to focus the right terminal tab. The first Desktop slice should implement Ghostty only, matching the [jackin❯ Desktop Agent Hub](/reference/research/desktop/agent-hub/jackin-desktop-agent-hub/) v1 launch contract. Other terminal emulators get a notification without click focus until their adapters are deliberately added. ## Why a daemon [#why-a-daemon] Same answer as live auth sync: this feature can't run from a CLI that exits between commands. The daemon adapter would need to subscribe to the per-container control channels for attention events, track per-event timers (sound-escalation deadlines), hold the per-workspace mute state, talk to the OS notification API, and receive click events back from the OS to run the focus-tab action. The lifecycle, install, and security posture this needs are the same ones the [jackin❯ daemon](/roadmap/jackin-daemon/) item has to decide first. This feature would be an adapter against that daemon; it does not introduce its own long-running shape. ## Open design questions [#open-design-questions] ### MCP server contract [#mcp-server-contract] * Tool surface: just `attention.waiting` / `attention.resolved`? Or a richer set (`attention.progress(message)` for "I'm still working, here's what I'm doing")? * Auto-resolve vs explicit resolve: does the next tool call from the agent count as "operator unblocked the agent" (auto-resolve), or does the agent have to call `attention.resolved` explicitly? * Urgency taxonomy: `low / normal / high` is a starting point; do we need an `error` level for crashes vs `interactive` for confirmations? The smaller the taxonomy, the better. ### Inference fallback [#inference-fallback] * State-confidence threshold: which effective states are notification-worthy? Candidate default: notify on high-confidence `blocked` and background `done`; show weak/unknown/stuck diagnostics in the console without a desktop notification until the operator opts into noisier alerts. * False-positive backoff: when the operator confirms a notification was a false positive (clicks "this wasn't really waiting"), should the daemon debounce that container for a while? ### Click-to-focus across terminals [#click-to-focus-across-terminals] * Detection: the v1 contract is Ghostty-first. What if the operator switches terminals after launch, closes Ghostty, or starts a session outside the Desktop launcher? The click action should degrade gracefully to a notification with no click action. * Adapter scope: Ghostty is the first supported adapter. Other terminals are explicitly deferred until the Desktop Agent Hub proves the product shape. ### Notification de-duplication [#notification-de-duplication] * Multiple agents waiting at once: five agents idle in five containers — five notifications? One grouped notification? A digest the operator can drill into? * Notification fatigue: what's the rate-limit policy? After N notifications in M seconds, fall back to a digest? ### Cross-host [#cross-host] * Remote operator: when jackin❯ grows to support remote agents (Kubernetes phase, see the [Why jackin❯](/getting-started/why/) page), notifications need to reach the operator wherever they are. Out of scope for v1; revisit when remote-agent work lands. ## Why this matters (illustrative, not measured) [#why-this-matters-illustrative-not-measured] Illustratively: an operator running four agents in parallel could plausibly lose a meaningful fraction of total work time to "I didn't notice the agent was waiting." Even a partial reduction in idle-wait time would justify the implementation effort within a few weeks of operator usage, on top of the qualitative win of staying in flow on the work the operator actually came to do. These numbers are not measured; they are the motivating hypothesis, not a shipped result. The bet of jackin❯ is that running many agents safely and conveniently changes how operators work. Attention prompts are meant to be the difference between "I have ten agents running, but I have to babysit them" and "I have ten agents running, and they ping me when they need me." ## Related work [#related-work] * [Agent attention prompts](/roadmap/agent-attention-prompts/) — the roadmap item this design exploration supports. * [jackin❯ daemon](/roadmap/jackin-daemon/) — host-side process this feature would plug into. * [Live bidirectional auth sync](/roadmap/live-auth-sync/) — sibling feature plugging into the same daemon; sets the precedent for per-axis adapters. * [jackin❯ Desktop Agent Hub](/reference/research/desktop/agent-hub/jackin-desktop-agent-hub/) — native macOS surface that should display attention/ready-for-review state and would own the first Ghostty click-to-focus UX. * [Agent runtime status authority](/roadmap/agent-runtime-status/) — canonical source for `blocked`, derived `done`, `idle`, `working`, `unknown`, and stuck diagnostics. * [Agent Orchestration Program → Live agent observability](/reference/research/agent-orchestration/program-research/) — adjacent work on surfacing what the agent is doing in real time; attention prompts would close the loop the other direction.