The brain proposes, the browser disposes — under guard

🛰️ Satellite — why an agent that can route itself can also lock the user out

The stakes: the agent's flagship power is moving the user around the app — "show me Acme's matters," "filter to open filings," "open this matter's record." But navigation is the one action that, done eagerly, is hostile. An agent that auto-routes rips the page out from under a counsel mid-thought; an agent that string-builds a URL invents routes that don't exist and 404s; an agent that fires a tool against a page the user already left does the right thing to the wrong screen.

The naive fix — "let the brain call router.push(url)" — detonates three ways at once. (1) The brain doesn't know the URL shape; it knows what a page is. Hand it URL-building and every route rename silently breaks the agent. (2) Cross-page jumps with no confirm turn the chat into a trap door. (3) Between the brain reading context and replying, the user navigates — so the instruction is now about a page that isn't on screen. The real fix keeps the brain in the proposing role and gives the browser a guarded disposing role: resolve by key, confirm before crossing pages, and drop anything that went stale.

✈️ Airplane — decide purely, then act; confirm-first across pages, direct on-page

One analogy: the dispatcher is an air-traffic controller, not a pilot. The brain (a pilot) radios a request — "I'd like to taxi to gate Clients." The controller checks the request is for a gate that exists (registry), checks the plane is still where it said it was (staleness), and for a runway crossing (a cross-page jump) hands back a clearance the user must accept — the "Go to Clients →" chip. For an in-cabin action that doesn't cross a runway (an on-page filter), it just lets it happen, using the plane's own controls (the page's registered handler), not a parallel set.

The dispatcher splits into a pure decision core and a thin React glue. The core is a framework-free function over (instruction, live-context reading) → a typed decision. The glue reads the live surface at dispatch time, performs the chosen effect (route / run / confirm / drop), and emits the live thread items.

🔬 Microscopic — the seams that make it correct

Why a pure core and a glue, not one hook

decideClientTool(instruction, live) performs no effect — no router.push, no tool.run, no store write. It returns a discriminated ClientToolDecision. That makes every branch — registry resolution, the confirm-first split, every staleness drop — a plain unit test with no React, no router mock, no DOM. The glue (useClientToolDispatcher) is the only part that touches the world, and it stays small.

Why staleness is read with getState(), not a subscribed value

The whole point of the stale check is "is the surface the brain reasoned over STILL the one in front of the user?" A value captured in a render closure would answer "…as of the last render," which is exactly the stale read we are guarding against. So the glue reads useCpcStore.getState() at the moment of dispatch — the live truth — and compares the intent's echoed surfaceKey/contextVersion against it.

Why the chip is a live item but the marker is stored

A nav chip carries an onConfirm callback — functions can't be serialized, so chips (like proposals) live in the dispatcher's local state and merge after the persisted thread, exactly as the live rail will merge its stream. The resolved navMarker is plain data, so it — and only it — is appended to the thread store and survives a refresh.

The trust boundary: normalize before deciding

clientInstructionFromIntent is where the wire shape is validated and coerced (RFC-APB-002 #1): it drops non-client-plane intents, tolerates snake_case or camelCase envelope keys, pulls only string/number route params, and separates the staleness envelope + display label from the tool's own args. The pure core only ever sees a clean ClientToolInstruction.

Files

Recall: the brain proposes typed intents; the browser disposes them by surface_key — confirm-first across pages, direct on-page, and never against a page the user already left.

Files changed

15 file(s), +827 / -23 lines