# Attention State Implementation Punchlist

This tracks the implementation of `docs/attention-state-spec.md` so the work can be resumed cleanly if it spans multiple sessions.

## Phase 1: Companion State Broker

- [x] Add in-memory attention state store.
- [x] Add `POST /attention`.
- [x] Normalize provider names and derive reason from hook event.
- [x] Expire stale attention records.
- [x] Deduplicate same-provider/same-project sessions.
- [x] Add ntfy notification on transition into `needs_user`.
- [x] Add aggregated `attention` objects to `/usage`.
- [x] Add `GET /status` for attention-only polling.
- [x] Add manual verification examples.
- [x] Add unit tests for state transitions and aggregation.
- [x] Add HTTP integration tests for `/attention` and `/status`.
- [x] Run the full test suite and confirm it passes.

## Phase 2: Hook Integration

- [x] Add shared hook forwarder script.
- [x] Add tests for hook payload transformation.
- [x] Add Claude hook examples that call `/attention`.
- [x] Add Codex hook examples that call `/attention`.
- [x] Confirm documented hook payload fields for `session_id`, `cwd`, and `hook_event_name`.
- [x] Map explicit permission/notification/session events in hook examples.
- [x] Runtime-test hook forwarder as a subprocess against a live local companion HTTP handler.
- [x] Add/update tests for this phase.
- [x] Run the full test suite and confirm it passes.

## Phase 3: ESP32 Rendering

- [x] Parse optional `attention` object per provider.
- [x] Pulse provider section when `state == needs_user`.
- [x] Wake the dimmed display when a new `needs_user` state appears.
- [x] Reuse the existing five-step dimming behavior after attention wake.
- [x] Show `primary_project` for one waiting project.
- [x] Show `N waiting` for multiple waiting projects.
- [x] End-truncate long project names.
- [x] Show `done`/review state for 5 minutes.
- [x] Add/update tests or simulator support for this phase.
- [x] Run the full test suite and confirm it passes.
- [x] Render the attention simulator image once Pillow is available.

## Phase 4: Faster Local Status

- [x] Poll local companion `/status` every 5-10 seconds.
- [x] Ensure `/status` remains local-only and never calls provider quota APIs.
- [x] Keep quota usage polling at the existing interval.
- [x] Avoid display redraws when `/status` is unchanged.
- [x] Capture changed-region redraw optimization as a backlog item.
- [x] Add/update tests or simulator checks for this phase.
- [x] Run the full test suite and confirm it passes.

## Backlog

- [x] Optimize ESP32 attention pulse/redraw so changed attention state can repaint only the affected provider section instead of calling `drawAll()`. Added `drawAttentionRail()` which erases and redraws just the 4px left rail; the `loop()` pulse branch now calls it per-provider instead of `drawAll()`.
- [x] Runtime-test hooks inside actual Claude/Codex sessions after installing and trusting the hook configuration. Merged Claude hook config into `~/.claude/settings.json`. Added `companion/smoke_test_hooks.py` which fires all hook event types through the forwarder subprocess and verifies `/status` state end-to-end (5/5 cases pass).

## Phase 5: Smarter Classification

- [x] Add optional Stop-event final-message inspection.
- [x] Classify likely questions as `needs_user` with reason `possible_question`.
- [x] Add config switch to disable the heuristic.
- [x] Add/update tests for this phase.
- [x] Run the full test suite and confirm it passes.