claude-sdk-integration

claude-sdk-integration

Purpose: Make every interaction with Anthropic's Python SDKs robust, cache-friendly, and contract-compliant. The meta-repo dispatches Claude sub-sessions via claude-agent-sdk; agents editing this surface must preserve the protocol that src/core/thinking_os/dispatcher.py defines.

Read when: editing any of:

• src/adapters/claude/sdk_dispatcher.py — the SDK dispatcher.
• src/adapters/claude/install.sh — adapter scaffold (when changing SDK options).
• src/core/thinking_os/dispatcher.py — the protocol the dispatcher implements.
• src/core/thinking_os/formula_composer.py — when changing how chains spawn sub-sessions.
• src/core/thinking_os/cognition.py — when wiring cos_dispatch_formula_run.

Skip when: editing tests under tests/test_*sdk*, mock fixtures.

Two libraries, two scopes

anthropic       — raw Claude API (Messages, tool use, streaming)
claude-agent-sdk — high-level: spawns a Claude Code sub-session as a
                   coroutine, handles tool-use loop, session lifecycle

src/adapters/claude/sdk_dispatcher.py uses claude-agent-sdk (high level). For raw API work (cognition tools that build prompts), use anthropic.

Dispatcher protocol contract

src/core/thinking_os/dispatcher.py defines:

class AgentDispatcher(Protocol):
    def available(self) -> bool: ...
    async def dispatch(self, request: DispatchRequest) -> DispatchResult: ...

Any adapter dispatcher (Claude, Codex, …) MUST implement this. Breaking the signature breaks every cognition flow.

Hard rules

1. Prompt caching (SDK + raw)

Cache markers on stable prefixes:

messages = [
    {"role": "user", "content": [
        {"type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}},
        {"type": "text", "text": dynamic_question},
    ]}
]

Goal: ≥80% cache hit rate on repeated dispatches. The dispatcher should keep the system prompt + tool list + role context BEFORE the question — never interleave dynamic content into the cached prefix.