fix(server): update Claude Agent SDK to 0.3.260

[t3dotgg]

Problem

The server pinned @anthropic-ai/claude-agent-sdk 0.3.170 while users run Claude Code 2.1.260. The adapter spawns the user's installed CLI, so it already receives frames the old types did not declare. Two of those gaps are user-visible:

• The CLI now stamps terminal_reason values such as api_error and malformed_tool_use_exhausted on results with an empty error list. The adapter read those as clean completions, so a turn that died looked done.
• Six message types the SDK now declares (background_tasks_changed, control_request_progress, informational, model_refusal_no_fallback, worker_shutting_down, conversation_reset) tripped the adapter's exhaustive switches at typecheck time.

Fix

• Bump the SDK to 0.3.260 (parity with Claude Code 2.1.260). The 0.3.259 and 0.3.260 releases only add optional fields (user_message_uuids, permissionPrompts, extra timing fields, managedMcpServers in settings) and need no adapter change.
• Consume background_tasks_changed, control_request_progress, worker_shutting_down, and conversation_reset silently. The task lifecycle events and session close path already carry what the UI needs.
• Surface warning-level informational notes (for example a Stop hook that refused continuation) and model_refusal_no_fallback as work-log warnings.
• Mark results whose terminal_reason is one of the CLI's dead-turn reasons (api_error, malformed_tool_use_exhausted, budget_exhausted, structured_output_retry_exhausted, tool_deferred_unavailable, turn_setup_failed, blocking_limit, rapid_refill_breaker, prompt_too_long, image_error, model_error) as failed turns with a plain error message. Name a 529 overload when the error list is empty.
• Add the now-required requestId to canUseTool test fixtures.

Verified with vp test run on the Claude adapter and provider tests (85 passed) and a clean server typecheck after rebasing onto main.

Made with Claude Fable 5.1 in Claude Code.

---

Note

Medium Risk
Changes turn outcome classification for Claude agent sessions—previously “successful” dead turns will now show as failed—which is correct but affects user-visible runtime state and error messaging.

Overview
Upgrades @anthropic-ai/claude-agent-sdk to ^0.3.260 (lockfile + workspace exclude) so server types match newer Claude Code wire messages.

Turn completion no longer treats “success” results with empty errors as done when the CLI signals failure via api_error_status: 529 or terminal_reason in a fixed dead-turn set (api_error, budget/limit errors, prompt too long, model/image errors, etc.). Those paths now emit failed turns with specific user-facing messages from resultUserFacingError.

SDK message handling adds explicit handling for newer system subtypes: silent consumption for control_request_progress, worker_shutting_down, and top-level conversation_reset; runtime warnings for warning-level informational and model_refusal_no_fallback. Tests cover dead-turn reasons, 529 overload, expanded warning filtering, and required requestId on permission/dialog callbacks.

^{Reviewed by Cursor Bugbot for commit d00caa1. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Update Claude Agent SDK to 0.3.260 and classify dead-turn terminal reasons as failures

• Bumps Claude Agent SDK to 0.3.260 in package.json and excludes it from the workspace minimum-release-age policy in pnpm-workspace.yaml
• ClaudeAdapter.resultUserFacingError now maps terminal reasons (usage limits, context-size failures, image/model errors, retry exhaustion, setup failure, blocking limits, overlong prompts, etc.) to user-facing error messages even when the SDK reports a success subtype or only diagnostic errors
• ClaudeAdapter.isOverloadedResult detects success-subtype SDK results with HTTP 529 and turnStatusFromResult marks both overload and dead-turn terminal-reason results as failed rather than completed
• ClaudeAdapter.handleSystemMessage emits runtime warnings for warning-level informational messages and no-fallback model refusals; conversation-reset and other non-warning system messages are now silently consumed instead of hitting the unknown-message warning path
• Behavioral Change: SDK results that previously completed successfully may now fail the turn — specifically 529 overload results and any terminal reason in the FAILED_TERMINAL_REASONS set in ClaudeAdapter.ts

^{Macroscope summarized d00caa1.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.6 KiB	13.7 KiB	+174 B (+1.3%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.0 KiB	−1 B (−0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.7 KiB	+175 B (+2.6%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.0 KiB	58.5 KiB	+1.5 KiB (+2.6%)	66.4 KiB	✅
Codex	Live turn messages	9	10	+1 (+11.1%)	21	✅
Claude	Total thread wire	13.6 KiB	13.6 KiB	−17 B (−0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.0 KiB	7.0 KiB	+2 B (+0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.6 KiB	6.6 KiB	−19 B (−0.3%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.9 KiB	57.9 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	10	10	0 (0.0%)	21	✅

Baseline: 01f3e50 · PR result: d00caa1 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Approved at d00caa1

Macroscope's review found this PR approvable — This is a focused Claude SDK compatibility and error-reporting fix. Runtime changes are confined to existing Claude turn classification and message handling, with targeted tests covering the new SDK signals and no product-default, schema, security, billing, or deployment changes.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate 5d174be

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5d174be. Configure here.}

[t3dotgg]

Note

🤖 Claude Fable 5.1 responding on behalf of Theo

The Macroscope verdict at 5d174be describes changes this PR does not contain. The diff against main is five files: the SDK version in apps/server/package.json, the lockfile, one minimumReleaseAgeExclude line, ClaudeAdapter.ts, and its test. There is no skill dispatch, replay, streaming, or web highlighter change here. Those landed on main separately and the bot appears to have read the rebase range as PR content.

The one real point, the missing dead-turn reasons, is fixed in 0b40ae3.

Dismissing prior approval to re-evaluate d00caa1