curriculum-project-hub/docs/adr/0017-agent-session-is-provider-bound.md

ADR 0017: Agent Runtime — Claude Code SDK via OpenRouter

Status

Accepted.

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.

Decision

Adopt @anthropic-ai/claude-agent-sdk as the agent runtime, routed through OpenRouter's "Anthropic Skin" (https://openrouter.ai/api).

OpenRouter exposes an Anthropic Messages API-compatible endpoint. Claude Code SDK speaks its native protocol directly to OpenRouter — no proxy, no format conversion. The SDK's query() 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.

The Hub AgentSession is provider/role/model-bound, and it must persist the provider runtime cursor needed to continue a conversation. For Claude Code SDK, that cursor is the result.session_id; store it in AgentSession.metadata as claudeSessionId and pass it back to the next query() call as options.resume. Role is part of the session binding because role prompts and tool surfaces can differ even when the underlying model is the same. A Feishu project group's active binding selects one Organization role for ordinary messages. Switching that selection routes future messages to the selected role's own session; it never mutates or merges provider cursors across roles. Work freezes the selected role when accepted so queued requests cannot drift after a later switch.

Role definitions are Organization-scoped runtime data. A role bundle selects its default model, system prompt, tool allowlist and installed Agent skill versions. PostgreSQL is authoritative for role composition and skill metadata; skill bytes live in a content-addressed persistent store selected only by the recorded SHA-256 digest. Updating a role or binding skills takes effect without a Hub release or process restart. A change to the role's execution surface (model, prompt, tools, selected skill content) archives its active sessions so the next run cannot resume a provider context created under stale instructions; label and ordering-only changes preserve conversational continuity.

Exactly one active role per Organization is the default used when a project group is first bound. The default is configuration data, not a hard-coded role name. Roles are selected through the Hub project console; role ids are not public slash commands. A project participant may change the group's shared selection only when both agent.trigger for the project and role.trigger for the target role authorize that actor. The selection affects every participant's future messages, while already accepted work keeps its frozen role.

Hub slash commands are a closed control-plane protocol. Unknown commands fail explicitly and are never downgraded to Agent text. Claude SDK session commands are invoked only through typed Hub actions. In particular, compaction resumes the selected role session and sends the exact /compact prompt without prepending Feishu context.

Environment variables:

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<OpenRouter API key>
ANTHROPIC_API_KEY=""  # must be explicitly empty

Model routing: ANTHROPIC_DEFAULT_SONNET_MODEL etc. accept OpenRouter model IDs (e.g. z-ai/glm-4.7, anthropic/claude-sonnet-4-20250514). This gives limited OpenRouter-level model routing, but the runtime is still Claude Agent SDK-shaped: non-Claude models are best-effort and may not support every Claude Code feature.

Consequences

• Provider-agnosticism is not fully preserved. OpenRouter can route to GLM, Claude, GPT, etc., but the runtime protocol and agent loop remain Claude Agent SDK-bound.
• The agent loop is Claude Code SDK's (compaction, tool approval, partial message streaming) — not hand-rolled.
• 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.
• Per-run model selection works via role→model mapping; models are OpenRouter IDs, not Anthropic-only aliases.
• OpenRouter recommends setting Anthropic as the top-priority provider for Claude Code; non-Anthropic models may have reduced compatibility with some SDK features (e.g. thinking blocks).