---
id: PX-RESEARCH-F52C8906
type: research
title: Klaus Provider Evolution
---

## Scope

This is historical research, not a current specification, plan, checklist, or delivery commitment.
Recovery sources: `docs/super/specs/2026-08-21-klaus-plan-spec.md` and `docs/super/specs/2026-09-17-klaus-live-child-reuse-spec.md`, recoverable from Git commit `88660125c313dd5eff4f8c4dee431caa8e0ddd22`.

## Historical design retained

Klaus was designed as a Pi-native provider over Anthropic's public Claude Agent SDK and MCP APIs, not as a replacement agent harness or reverse proxy.
Pi remains canonical for visible history, tools, permissions, compaction, hooks, scheduling, UI, cwd, and outer control flow, while Claude state is opaque derived cache.
Opaque cache entries must never be semantically repaired or used as authority because cache loss may cost performance but must not alter Pi behavior.
Canonical replay of visible user, assistant, tool, image, and model-facing result content is the correctness fallback for cache loss, incompatible lineage, edits, branches, and compaction transitions.
The design isolated SDK and MCP dependencies behind Klaus-owned validated request, event, cache, and error boundaries to make exact-version upgrades replace adapters rather than spread compatibility branches.
One query-owned in-process MCP bridge preserves Pi tool names and schemas while Pi remains the only tool validation, permission, and execution boundary.
Tool-call IDs, query ownership, terminal cleanup, and concurrent session isolation are protocol invariants because guessed ordering or shared state would corrupt Pi authority.
Pi-managed Anthropic OAuth is passed only through the child boundary, never persisted or exposed through logs, cache, fixtures, or a proxy.
Child isolation uses an extension-owned Claude configuration directory and restrictive environment allowlist, avoiding normal `~/.claude` state and ambient credentials.
Subscription routing can report API-equivalent cost for Pi telemetry without claiming it equals subscription billing, while Fable can carry separate usage-credit risk.

## Historical reuse evolution

The later reuse design rejected speculative prewarming and instead kept one completed compatible child per session for a bounded idle window.
Reuse required exact lineage and option compatibility, while mismatches closed the child and returned to public resume or canonical replay.
A tool-list-only change became a live bridge replacement through a fresh MCP server identity, avoiding stale tool definitions without rewriting history.
The recorded benchmark treated latency reduction as a retention gate, making reuse an evidence-backed optimization rather than a semantic shortcut.

## Verified current behavior

`extensions/klaus/README.md`, `index.ts`, `src/coordinator.ts`, `src/agent-sdk.ts`, `src/models.ts`, and `package.json` verify that Klaus remains an active provider using Agent SDK `0.3.281` and MCP SDK `1.29.0`.
Current registration projects current non-snapshot Anthropic catalog models into `klaus`, preserves Pi catalog metadata where safe, and excludes transport-owned configuration.
Klaus accepts only Pi-resolved Anthropic OAuth, mirrors persisted primary-session cache under `.klaus/`, and documents that cache is plaintext derived conversation data with manual retention.
The coordinator retains an eligible completed child for a two-minute reuse lease, sends an exact next user-turn delta through the live input stream, and discards incompatible children.
Current reuse checks model, cwd, effective system prompt, thinking, token limit, headers, child environment, lineage, and exactly one new text user message.
Current tool swapping creates a fresh named MCP bridge through `setMcpServers()` before sending a reused turn, with failure falling back to a cold path.
Session switch, fork, compaction, shutdown, abort, timeout, and protocol failure close active queries, preserving Pi authority over lifecycle boundaries.

## Lessons

Derived-cache acceleration is safe only when canonical replay remains complete and every reuse predicate is explicit.
Public integration seams plus exact dependency pins turn upstream runtime drift into observable adapter and E2E work instead of hidden behavioral coupling.
Performance work needs an equivalence proof at the outbound boundary and a measured threshold before it changes lifecycle complexity.