# Track Specification: Hook API UI State Verification (hook_api_ui_state_verification_20260302)

## Overview
Currently, manual verification of UI widget state is difficult, and automated testing relies heavily on brittle logic. This track will expose internal UI widget states (like `ui_focus_agent`) via a new `/api/gui/state` GET endpoint. It wires critical UI state variables into `_settable_fields` so the `live_gui` fixture can programmatically read and assert exact widget states without requiring user confirmation dialogs.

## Architectural Constraints
- **Idempotent Reads**: The `/api/gui/state` endpoint MUST be read-only and free of side-effects.
- **Thread Safety**: Reading UI state from the HookServer thread MUST use the established locking mechanisms (e.g., querying via thread-safe proxies or safe reads of primitive types).

## Functional Requirements
- **New Endpoint**: Implement a `/api/gui/state` GET endpoint in the headless API.
- **State Wiring**: Expand `_settable_fields` (or create a new `_gettable_fields` mapping) to safely expose internal UI states (combo boxes, checkbox states, active tabs).
- **Integration Testing**: Write `live_gui` based integration tests that mutate the application state and assert the correct UI state via the new endpoint.

## Acceptance Criteria
- [ ] `/api/gui/state` endpoint successfully returns JSON representing the UI state.
- [ ] Key UI variables (like `ui_focus_agent`) are queryable via the Hook Client.
- [ ] New `live_gui` integration tests exist that validate UI state retrieval.