# On-demand tools, observed targets and incremental observations

Read this when interpreting a delta, recovering a replaced UIA control, or diagnosing tool visibility.

## Tool visibility

With progressiveTools enabled, idle Agents see computer_use_activate, computer_ctrl and computer_ask. A successful computer-use skill load, receipt acknowledgement or activation exposes the 18 existing tools to that Agent; the activation entry remains available too. Other Agents and children activate independently. The operating policy, skill receipt, cycle ownership and human brakes continue to govern execution. Capability activation itself performs no desktop call. A legacy host can set progressiveTools:false to retain the original global tool surface.

## Native target recovery

1. Query a known window, for example computer_uia {hwnd:321,role:"Button",name:"Save"}.
   Recovery handles are generated by default for scoped name/id queries. Broad inventories skip this extra native work; use targets:true with a concrete hwnd when handles for the whole list are needed, or targets:false to disable them. Ordinary fields and incremental observations remain available either way.
2. Select the intended result using its visible label, context and task. Pass its opaque target to computer_uia_act {target:"<returned handle>",action:"invoke"}.
3. If the native control was replaced while the task/context remains valid, rebind:true allows a new bounded scan. A unique AutomationId must retain the recorded semantics and ancestors. If that identifier disappeared, a unique name/role/class/pattern/ancestor match may be used. A changed meaning, duplicate identity, ambiguous semantics, incomplete scan, changed window title/geometry/process or expired handle refuses before action.

Targets are scoped to this Agent's retained observations and the native worker's cache (512 identities; five minutes from observation). Handles cannot survive worker restart. No coordinates are guessed during UIA recovery. This feature applies to UIA pattern actions; M-mark clicks remain snapshot/geometry checked and still require refreshing after scrolling/navigation. A recovered control is not proof of the business outcome: inspect readback or query the relevant state.

## Incremental queries and full retrieval

The first query returns mode:"full" and observation:"O…". Repeat every original query parameter and add since:"O…" for a fresh comparison. Changes are returned in delta.elements for computer_uia, or delta.windows/delta.uiaFlat for computer_state.

- added and changed contain {key,element}, with the complete current element, not just a changed field.
- removed contains identity keys. Delete those records; replace changed records; insert added records.
- order is supplied whenever array membership/order changed, and lists the resulting key order.
- An element key is its target handle when supplied, otherwise uia:<pid>:<runtimeId>. A window key is window:<pid>:<hwnd>.
- Non-array metadata is always the current metadata. The next observation ID identifies the reconstructed complete state and can be the next since base.

The result contains no hidden duplicate full element array. The plugin keeps the complete provider result internally for both full and diff outputs, including all returned fields. computer_uia {snapshot:"O…"} or computer_state {snapshot:"O…"} retrieves that exact retained full snapshot. This retrieval is historical and performs no capture. The bounded cache holds 64 observations per Agent; expired/missing snapshots report unavailable. Request a fresh query to replace them. A missing since base instead automatically returns a fresh full result with resetReason.

Truncated observations, missing/duplicate element identities and scope changes use a full response. The plugin also chooses full when a delta would be larger. This is a bounded observation of what the UIA provider returned; it does not claim that a truncated UIA tree contains every control in the application.