mcp: session-notes — Dispatch replacement architecture and Anthropic billing reality

Sources/Dev/2026-05-10-dispatch-replacement-architecture-and-anthropic-billing-reality.md

@@ -0,0 +1,46 @@
+---
+created: '2026-05-10'
+path: Sources/Dev
+project: dispatch-replacement
+status: active
+tags:
+- dispatch
+- claude-code
+- mcp
+- automation
+type: session-notes
+updated: '2026-05-10'
+---
+
+## Outcome
+
+Worked through what a Dispatch replacement actually requires given the April 2026 Anthropic policy change blocking subscription auth in third-party tools. Landed on a two-layer architecture that splits dispatch (API-billed) from agent execution (CLI subprocess on subscription). Pi evaluated and set aside as a possible engine, not the harness frame. No code written this session — pure design.
+
+## Topics Covered
+
+- Pi as a candidate harness; what it actually does (terminal coding agent with session tree, extension-based context engineering, multi-provider) vs. what it doesn't (mobile interface, subscription auth post-April 2026)
+- Anthropic's April 4, 2026 policy: subscription OAuth tokens restricted to first-party products only; Claude Code and Claude.ai exempt
+- Why the policy exists: prompt-cache efficiency in first-party tools, telemetry, and protecting the customer relationship from harnesses that abstract Anthropic into swappable infrastructure
+- Auth mechanism distinctions: OAuth tokens (in-process, restricted) vs. CLI subprocess (process boundary, harness never touches credentials) vs. Agent SDK (in-process, API-key-only by Anthropic policy)
+- Prompt caching mechanics: automatic vs. explicit breakpoints, 0.1x cache reads, 1.25x cache writes, 5-minute default TTL, prefix-based hashing
+- Caching gotcha for subprocess pattern: per-spawn dynamic headers in `claude -p` reduce cache hit rates vs. interactive sessions; long-lived `--input-format stream-json` recovers most of it
+- Cost modeling: heavy daily API usage with good caching ≈ $300/month, light usage ≈ $60/month; subscription pricing assumes human-paced consumption that automation defeats
+- Final architecture: dispatch layer (harness, API + caching) handles phone-driven conversation and long-term context; agent layer (CLI subprocess on subscription) handles task execution
+
+## Key Learnings
+
+- **Subscription pricing is structurally a different product from API pricing.** Subscriptions price for human typing speed; harnesses defeat that assumption regardless of caching efficiency. No clever workaround makes API billing match subscription cost at heavy use.
+- **The subprocess vs. SDK distinction is meaningful, not just technical.** Subprocess keeps auth inside Claude Code's process boundary; the harness never possesses subscription credentials. SDK is in-process and explicitly API-key-only by Anthropic policy. The boundary maps to what Anthropic actually cares about.
+- **Pi's value is in the engine layer, not the harness frame.** Strong session model, real context-injection hooks via extensions, MCP support — but no mobile interface and the OAuth path it advertises is now per-token billed for Anthropic. It's a candidate component, not the answer.
+- **Two-layer split is naturally good engineering, not just a billing hack.** Dispatch wants long-lived state, harness-controlled context, structured tool use over a small token volume. Agent execution wants fresh per-task context, codebase awareness, heavy tool use within bursts. Different layers want different model interfaces; the auth/billing situation happens to align with that split.
+- **Cache structure for the dispatch layer is textbook-friendly.** Stable system prompt → cached tool definitions → cached long-term context (wiki/OpenBrain) → conversation tail. High-90s hit rates achievable for personal-scale usage.
+- **`list_vault_projects` MCP tool has a sort bug** — fails with `'<' not supported between instances of 'str' and 'datetime.date'` when frontmatter dates aren't consistently typed. Lovebug task.
+
+## Follow-ons
+
+- [ ] File Lovebug ticket for `list_vault_projects` date-sort bug
+- [ ] Decide on mobile interface approach for dispatch layer (Telegram/Discord bot vs. simple web UI on `herbydev` over Tailscale vs. ntfy-style push)
+- [ ] Sketch dispatch ↔ agent task-brief contract (what context gets passed when dispatch spawns Claude Code)
+- [ ] Design the dispatch layer's prompt structure with explicit cache breakpoints (system → tools → long-term context → conversation tail)
+- [ ] Decide how the dispatch layer reads from wiki/OpenBrain — direct MCP, fetched at turn time, or pre-assembled
+- [ ] Revisit Pi-as-engine question once dispatch layer shape is concrete; may end up using its RPC mode rather than building from scratch