# Operator Attention And Unblock

OpenScout should treat "needs the human" as a first-class product state, not as a side effect of whichever harness happened to print the prompt.

This doc records the current posture and the next implementation steps for approvals, questions, waiting states, permission prompts, and notifications.

## Principle

Scout can only own data that enters Scout. Session events, broker messages, collaboration records, and Scout-created invocation state are first-party data. Native harness prompts that happen above Scout, such as an MCP client asking whether to allow a tool call, are not visible until the host forwards them or exposes a hook.

The operator-attention model should make that boundary explicit:

- Project attention from first-party session state when Scout already sees the event.
- Ingest host-level permission prompts through a host integration, not by pretending the MCP server can see a request that the host intercepted before the server was called.
- Record durable broker unblock requests for anything that can outlive a single session frame.
- Route notifications from the broker/session attention model, with dedupe and clear ownership.

## Alertable Events

Session attention already covers:

- `approval`: an action block is awaiting approval and can be approved or denied.
- `question`: an agent question is awaiting an answer.
- `failed_action`: a recent action failed.
- `failed_turn`: a recent turn failed.
- `session_error`: the session itself is in error.
- `native_attention`: adapter/provider metadata says the native harness needs input.

Broker and collaboration attention should cover:

- `question.open`: an answer is owed.
- `question.answered`: the asker needs to close or reopen.
- `work_item.waiting`: a named dependency or actor owns the next move.
- `work_item.review`: a reviewer owes accept/reopen feedback.
- `flight.failed` / `flight.cancelled`: an ask did not complete.
- `flight.completed`: notify only when the caller requested callback semantics.

Host-level unblock attention still needs explicit ingress:

- Codex approval prompts raised by the Codex host.
- Claude permission prompts raised by the Claude host or companion integration.
- MCP client pre-tool permission prompts.
- Local system permissions needed by Scout itself, such as notifications or APNs setup.

## Current Coverage

Implemented now:

- Runtime session attention projection exists in `packages/runtime/src/session-attention.ts`.
- Protocol and runtime support broker-owned durable `unblock_request` records
  and unblock request events.
- Mobile bridge inbox now uses session attention instead of approvals only.
- Bridge websocket now emits `operator:notify` for any projected session attention item.
- APNs alert routing now sends inbox alerts for any projected item.
- iOS Inbox can decode and display approvals, questions, failures, session errors, and native attention.
- Approval actions remain approve/deny.
- Non-approval attention items provide `Open Session` and local `Dismiss`, following the no-dead-end UI rule in `docs/eng/no-dead-end-ui.md`.
- The iOS tRPC route map includes `question/answer`, so timeline question blocks can use the existing answer-question bridge path.
- Scout MCP `ask` supports `replyMode: "notify"` and emits `notifications/scout/reply`.
- Web operator attention reads active broker unblock requests.
- Managed Claude sessions rely on host or companion permission capture; Scout
  does not install Claude project hooks.

Not done yet:

- Answering `question` items from the iOS Inbox.
- Host-level capture for Claude, Codex, and MCP permission prompts.
- Desktop/web notification sinks for operator attention.
- Cross-device read/dismiss/decision synchronization beyond the current inbox item refresh. Current non-approval dismiss is intentionally local-only.

## Practical Recovery Guidance

When an operator prompt appears stuck, first classify where the prompt lives:

- Scout-owned session question or action approval: answer or decide it through
  the Scout surface that rendered it.
- Broker unblock request: use the rendered action, or inspect the request by id
  before dismissing it.
- Host-side approval prompt: open the host UI or rely on a host integration that
  forwards the prompt into Scout. An MCP server cannot observe a prompt the host
  intercepted before the tool call reached the server.
- Long-running agent work: mark the work item or flight waiting with the human
  or dependency as next owner instead of leaving the caller blocked.

## Durable Unblock Model

Scout uses broker-owned unblock records for human actions that may outlive a
single websocket frame.

Fields include:

- `id`
- `source`: `session`, `broker`, `host`, or `system`
- `kind`: `approval`, `question`, `permission`, `waiting`, `review`, `failure`, or `setup`
- `status`: `open`, `notified`, `resolved`, `denied`, `expired`, or `dismissed`
- `ownerId`: usually `operator`
- `sourceRef`: session/turn/block, flight, work item, or host request ids
- `title`, `summary`, `detail`
- `risk`
- `actions`: typed action affordances such as approve, deny, answer, open, retry, or dismiss
- `createdAt`, `updatedAt`, `resolvedAt`

The session inbox can continue projecting lightweight items, but durable host and broker waits should be represented by this record so a reconnect, another device, or a later agent can reason about what is still open.

## Implementation Path

1. Keep session attention as the fast path for first-party pairing events.
2. Expand broker attention/unblock projection from collaboration records and flights.
3. Expand host ingress for permission prompts:
   - Codex: surface host approval requests into Scout as unblock records.
   - Claude: use a host integration that forwards permission prompts without a
     project-wide pre-tool gate.
   - MCP: document that server-side tools cannot see client-side approval prompts unless the host forwards them.
4. Route all unblock records through a notification router:
   - `interrupt`: approval, question, host permission, failure.
   - `badge`: requested completion callbacks, review-needed, waiting states.
   - `silent`: ordinary progress/status.
5. Add action handling:
   - approvals call existing `actionDecide`.
   - questions call existing answer-question plumbing, with Inbox needing structured options before it can answer in-place.
   - host permissions call host-specific grant/deny callbacks.
   - work/review items call collaboration update APIs.
6. Add stale sweeps for `waiting`, `review`, and unresolved host permissions.