# ADR 0017: Agent Runtime — Claude Code SDK

## Status

Accepted — supersedes the original ADR-0017 (provider-agnostic session).

## Context

The original ADR-0017 mandated a provider-agnostic agent layer: any
OpenAI-compatible model via OpenRouter, custom agent loop built on Vercel AI
SDK's `streamText`. The motivation was to avoid vendor lock-in.

In practice, the hand-rolled agent loop lacked capabilities that a production
agent needs: context compaction (long conversations), tool approval flows,
partial-message streaming, and a battle-tested multi-turn loop. Building these
ourselves meant re-implementing what the Claude Code SDK already provides.

The Feishu integration also proved costly to hand-roll — card schema quirks,
patch limitations, file support — each API quirk cost a round-trip. The
Claude-to-IM library (2.7K stars) has already solved these, but its
LLMProvider interface expects Claude Code SDK's SSE event format. Using it with
a generic provider would require a conversion layer.

## Decision

Adopt `@anthropic-ai/claude-agent-sdk` as the agent runtime. The SDK's `query()`
function owns the agent loop (tool dispatch, compaction, streaming). Built-in
tools (Read, Write, Bash, Glob, Grep) cover the entire tool surface — no custom
tools needed. `cph check` / `cph build` run via Bash.

This means:
- The agent layer is **Anthropic-specific**, not provider-agnostic. Claude Code
  SDK speaks the Anthropic Messages API and cannot be pointed at OpenRouter
  (which is OpenAI-compatible).
- An Anthropic API key (or OAuth via Claude Pro/Max) is required.
- Model selection is within the Anthropic model family (Sonnet, Haiku, Opus),
  not across vendors.

## Consequences

- We lose the ability to route to GLM or other non-Anthropic models via
  OpenRouter. This is the accepted cost of getting a mature agent loop.
- The Vercel AI SDK dependency is dropped.
- Custom tools (read_file, write_file, cph_check, cph_build) are replaced by
  the SDK's built-in Read/Write/Bash/Glob/Grep.
- The SSE event format matches Claude-to-IM's expected protocol natively —
  adopting Claude-to-IM for Feishu integration is a direct fit, no conversion.
- Per-run model selection still works (role→model mapping), but models are
  Anthropic aliases, not OpenRouter routing IDs.
- If provider-agnosticism becomes a hard requirement again, the migration path
  is: replace `query()` with a Vercel AI SDK `streamText` call + an SSE format
  converter (~100 lines). The rest of the architecture (trigger, lock,
  permission, Feishu client) is provider-agnostic already.