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]]
1---2name: 471-2026-01-26-boundary-contracts-not-enforced-3ce89fbf3description: Summary4---56## Summary78Boundary 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.910## Context1112Recent refactors established clean import direction and layer ordering, but contract surfaces (callbacks, tool factories, and state accessors) remain loosely typed in a few places.1314## Root Cause1516Contracts 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.1718## Changes1920- Pending: define explicit callback type aliases for tool results, plan approval, and streaming.21- Pending: narrow `StateManagerProtocol` into per-tool protocols (todo, plan approval, authorization).22- Pending: update tool factories and UI hooks to accept only the minimal protocols and callbacks.2324## Behavioral Impact2526**What users notice:**27- No immediate behavior change, but boundary leaks can manifest as subtle UI/core coupling and harder-to-debug callback misuse.2829**What didn't change:**30- Runtime behavior and tool execution flow remain unchanged.3132## Related Cards3334- [[tool-registry-todo-alignment]]
Run npx skillmds@latest add tools-only/471-2026-01-26-boundary-contracts-not-enforced-3ce89fbf in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Summary It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.
tools-only