docs(design): discuss cache-stable tool discovery

[tt-a1i]

Problem

Mid-session OpenPI tool activation (setActiveTools / toolsAdded after bg_start, plus lifecycle and context_pivot toggles) changes the tool list at the front of the prompt. Providers that cannot anchor late tools reprocess the cached prefix. The reported Terminal-Bench overlap (about 59% cache hit versus about 90% for opencode) is treated as a discussion input, not a rerun.

Value

Gives maintainers a single discussion record: why deferred declaration fights prompt caching, how Pi Code Mode and MCP already avoid that, and five redesigns with cache, first-turn cost, MCP fit, and migration risk. No runtime behavior changes.

Approach

Add docs/design/tool-discovery-redesign.md only. It separates source facts from inferences, compares static declaration, eager group freeze, Pi deferred / tool_search, Code Mode discovery, and a search-and-execute gateway, and recommends a direction for discussion rather than a decision. The design index is intentionally not updated.

Validation

• Source inspection of the tool surface, capability loading, background-terminal lifecycle, Code Mode activation, and the Cursor/Antigravity transcript projection at 708a44b.
• Public Pi 1.2, Anthropic, OpenAI, Codex, Cloudflare Code Mode, and OpenCode documents read on 2026-10-17.
• Not run: Harbor, Terminal-Bench, provider calls, bun run check, bun run test. No code changed.

Impact

• User-visible behavior: none.
• Model-visible context/tools: none.
• Runtime/lifecycle: none.
• Persisted config/data: none.
• Compatibility or risk: none. This draft is not an accepted Decision.