Attention Alerts

Attention Alerts

Attention alerts speak a short request when an agent needs permission or user input. They complement commentary and final status lines; they do not narrate the full prompt, command, answer list, or transcript.

Release note: Attention alerts have been available since v0.6.0 and are included in the current v0.8.3 release. Existing installations keep them disabled until the user opts in.

Turn It On Or Off

Enable:

jarvis-line config set attention_enabled true

Disable only request speech while keeping ordinary Jarvis lines active:

jarvis-line config set attention_enabled false

Disable all speech:

jarvis-line config set speech_enabled false

In the Preview macOS app, use the Attention alerts switch in the menu bar quick panel for an immediate on/off change. The same setting is available under Settings → Speech → Events and in Setup Assistant.

What Triggers Speech

Situation	Built-in Codex behavior
Tool needs approval	Official PermissionRequest hook emits a permission alert
Plan-mode question waits for an answer	Session adapter recognizes structured request_user_input and emits an input-required alert
Plan-mode question has an automatic resolution timer	No alert; the agent can continue without an answer
Agent enters Plan mode	No alert by itself
Agent thinks about asking a question	No alert until a structured request exists
Claude, Gemini, or another agent needs input	Adapter must emit an explicit attention event

If the user answers a recognized Plan question before it starts playing, the queued alert is cancelled when the matching result is observed.

Queue Behavior

• attention jobs expire after 30 seconds
• queued attention is prioritized over queued final and commentary speech
• currently playing audio is never interrupted
• one audio worker prevents overlapping voices across sessions
• final events remove older queued work from the same session
• quiet hours, speech mode, queue limits, maximum length, and TTS fallback still apply

final_only permits enabled attention alerts. speak_mode = off and speech_enabled = false suppress them.

Privacy Boundary

The built-in Codex adapters format a bounded local summary. They do not persist:

• raw tool arguments
• command text
• answer options
• user answers
• file paths or URLs from the original request
• Codex call IDs

The queue temporarily stores only the short line needed for playback, event type, expiry data, and an optional one-way correlation token used to cancel an answered request. Third-party adapters are responsible for keeping the line they submit safe to speak.

Explicit Event Example

An agent adapter can request speech through the versioned protocol:

jarvis-line emit \
  --source claude \
  --session "session-123" \
  --phase attention \
  --attention-type input_required \
  --line "Your deployment choice is required."

Expected output:

Queued Jarvis Line event for claude.

Supported attention types are permission_request and input_required. See the versioned event protocol for the full adapter contract.

If It Does Not Speak

jarvis-line config get attention_enabled
jarvis-line config get speech_enabled
jarvis-line config get speak_mode
jarvis-line doctor
jarvis-line trace --limit 20

Also confirm that the Codex hook installer has been run after updating:

jarvis-line install codex

Plan-question detection is a fail-soft compatibility adapter over Codex's observed session format. If Codex changes that shape, Plan questions may be skipped while official permission hooks and ordinary Jarvis lines continue.