Agent Attention Prompts: Design Exploration

Status: Design exploration for Agent attention prompts (Phase 2, Reactive Daemon Program) — not yet implemented.

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

The end state, from the operator's seat:

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.
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.
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.
Per-workspace mute: operators in deep-focus mode can mute notifications for a workspace temporarily without losing the launch-time policy.
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"

Attention prompts should not own state detection. They consume the agent runtime status authority, 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

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 crates/jackin-capsule/src/runtime_setup.rs 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 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 v1 launch contract. Other terminal emulators get a notification without click focus until their adapters are deliberately added.

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 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

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

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

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

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

Remote operator: when jackin❯ grows to support remote agents (Kubernetes phase, see the Why jackin❯ 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)

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."

Agent attention prompts — the roadmap item this design exploration supports.
jackin❯ daemon — host-side process this feature would plug into.
Live bidirectional auth sync — sibling feature plugging into the same daemon; sets the precedent for per-axis adapters.
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 — canonical source for blocked, derived done, idle, working, unknown, and stuck diagnostics.
Agent Orchestration Program → Live agent observability — adjacent work on surfacing what the agent is doing in real time; attention prompts would close the loop the other direction.

Agent Attention Prompts: Design Exploration

On this page