Root Cause

Summary

Boundary contracts between UI, core, and tools are partially implicit: several callbacks and tool entry points are typed as Any or use broad protocols, so the contract is not enforced by typing or tests. This makes boundary drift harder to detect and allows accidental coupling across layers.

Context

Recent refactors established clean import direction and layer ordering, but contract surfaces (callbacks, tool factories, and state accessors) remain loosely typed in a few places.

Root Cause

Contracts were defined informally via usage instead of explicit callback type aliases and minimal protocols. We missed it because there is no boundary-contract audit or type gate for these callback signatures; prevention is to encode contracts in types/ and add a focused type/check step.

Changes

• Pending: define explicit callback type aliases for tool results, plan approval, and streaming.
• Pending: narrow StateManagerProtocol into per-tool protocols (todo, plan approval, authorization).
• Pending: update tool factories and UI hooks to accept only the minimal protocols and callbacks.

Behavioral Impact

What users notice:

• No immediate behavior change, but boundary leaks can manifest as subtle UI/core coupling and harder-to-debug callback misuse.

What didn't change:

• Runtime behavior and tool execution flow remain unchanged.

Related Cards

• [[tool-registry-todo-alignment]]