fix: bump the agent SDK to 0.3.281, and unstick Opus from a superseded release

[saucam]

Bumps @anthropic-ai/claude-agent-sdk 0.3.258 → 0.3.281, so opus runs Opus 5.5.

Why the bump is what unlocks the model

The SDK version tracks the bundled Claude Code CLI 1:1, and the model list comes from that CLI at runtime — not from the package. So I ran both and compared what the live backend reports:

SDK	opus / default reports as
0.3.258	Opus 5 with 1M context
0.3.281	Opus 5.5 with 1M context

An opus turn on 0.3.281 reports init.model = claude-opus-5-5, with canonicalModel: "claude-opus-5-5" and contextWindow: 1000000 in modelUsage.

Breaking-change check: the sdk.d.ts diff is purely additive — new optional fields (omitClaudeMd, mcpServer, defaultToNo, suppressAlwaysAllowRule) and new exported types (McpServerProvenance, SDKStartupFailureReason, SDKUsageReport). Nothing codeoid calls changed shape.

Two stale things behind it — both the second occurrence of #315

1. MODEL_CATALOG still pinned opus → claude-opus-5.

The catalog is only the pre-first-report fallback (the live list wins), but a session created before the backend has reported its list gets pinned to whatever it says. That is exactly how the alias came to run claude-opus-4-8 after Opus 5 shipped. Now claude-opus-5-5, live-verified rather than guessed.

2. contextWindowForModel had no opus-5 family — so a 1M model measured as 200k.

Not cosmetic. Once the SDK reports the concrete id back, SessionInfo.model carries a value the table doesn't know:

before:  claude-opus-5-5 → 200000     claude-opus-5 → 200000
after:   claude-opus-5-5 → 1000000    claude-opus-5 → 1000000

modelUsage says the real window is 1,000,000, so every consumer was off by 5×: the percent-of-window display, the fork seed budget, and the auto-rotate occupancy that decides when a session rolls — meaning auto-rotate fired at about a fifth of real capacity. claude-opus-5 was already broken this way from #315, which moved the catalog id without adding the family.

The guard that would have caught it

The two tables are now cross-checked: every catalog entry's declared contextWindow must equal what contextWindowForModel derives from its id and from its alias. It fails if either table moves without the other — mutation-verified: dropping opus-5 from the family list turns it red.

The resolveAgainstList fixture is refreshed from the real 0.3.281 payload, which also changed shape: Fable is now reported bare (claude-fable-5-1) where 0.3.258 reported it suffixed (claude-fable-5-1[1m]). The suffix-stripping test now builds its own local fixture rather than leaning on the shared one, so the shared fixture stays verbatim-honest — a fixture that flattered the code is why #315's bug survived a test that looked like it covered it.

Deliberately not in this PR

The root cause. The SDK already reports modelUsage[model].contextWindow on every turn and codeoid throws it away — providers/claude/index.ts types the payload as { inputTokens?, outputTokens? } and reads only the key to derive the model name. That is why a hardcoded table existed to go stale.

It can't simply be deleted, for two reasons I verified rather than assumed:

• ModelInfo (the supported-models list codeoid caches) carries no contextWindow, so the number is unknown until a turn completes — a fresh or just-resumed session still needs one to render.
• Some backends report none; the qwen provider's own comment records modelUsage as "observed empty against the Bailian gateway".

So the correct shape is: consume the provider's number as authoritative, demote the static tables to a pre-first-turn bootstrap. That touches ProviderResult/LLMCallUsage, the claude provider's result parsing, session state and every other backend's equivalent — a provider-interface change, kept separate so this dependency bump stays independently revertable. providers/context-windows.ts already anticipated it in its header ("or later from provider-reported ModelInfo").

Verification

• Ran the live backend on both SDK versions to establish the model-name change, rather than reading it off the package.
• init.model / modelUsage read directly from a real opus turn for the id and the window.
• Catalog↔window cross-check mutation-tested.
• bun run typecheck · bun run lint · bun test → 2593 pass, 19 skip, 0 fail.

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​anthropic-ai/​claude-agent-sdk@​0.3.258 ⏵ 0.3.281	+1

View full report