# SDK bump — claude-agent-sdk 0.1.59 → 0.2.88

> Point-in-time snapshot (2026-06-03). Not maintained. See `CARDS/` for living docs.

## What & why

`requirements.txt` pinned `claude-agent-sdk>=0.1.59`. The floor allowed installs
from the stale `0.1.x` series. We bumped the floor to `>=0.2.88` (latest on PyPI).

This matters for **cost reporting**: the dashboard never computes prices from
per-token rates — it reads `total_cost_usd` straight from the SDK
(`src/agent/session.py`). There are **no hardcoded price tables anywhere in the
repo**, so token pricing stays correct only as long as the SDK floor is current.
The thing to keep up to date is the SDK version, not a rate table.

- Bump commit: `c783305` (`requirements.txt:5`), merged to `main`.
- Full suite (1063 tests) passes on 0.2.88.

## Notable SDK changes across the range

### Breaking (introduced at 0.2.0 — already absorbed; tests pass)
- `ClaudeCodeOptions` → **`ClaudeAgentOptions`** (rename). We already use the new name.
- `custom_system_prompt` + `append_system_prompt` merged into **`system_prompt`**.
- Claude Code system prompt no longer default → opt in via
  `system_prompt={"type":"preset","preset":"claude_code"}`.
- Filesystem settings / `CLAUDE.md` / subagents no longer loaded by default →
  opt in via `setting_sources=["user","project","local"]`. We pass
  `setting_sources=["project"]` already.

### New features we adopted (see "What was done")
- **`ResultMessage.api_error_status`** (0.1.74) — HTTP status (429/500/529) of a
  failing API call; safe-to-log classifier for API vs. agent/task errors.
- **`ServerToolUseBlock` / `ServerToolResultBlock`** (0.1.65) — server-executed
  tool calls (advisor, web_search) and their results. Previously *silently
  dropped*, so advisor-only messages arrived as empty `AssistantMessage`.

### New features available but NOT yet adopted
- File checkpointing + `rewind_files()` (`enable_file_checkpointing`) — natural
  fit for the review→reject flow (revert an agent's changes to a checkpoint).
- Session forking / `SessionStore` adapters (`fork_session`, `delete_session`,
  S3/Redis/Postgres) — could back "copy agent" / persistent resume.
- Thinking display control (`display` on `ThinkingConfig`) — we run a 32k thinking
  budget; this can surface *summarized* thinking text for the UI.
- Hook event streaming (`include_hook_events` → `HookEventMessage`) — richer
  per-agent activity timeline.
- `task_budget` (token cap per task), `strict_mcp_config`, `xhigh` effort level.

0.2.83–0.2.88 are almost entirely bundled Claude CLI bumps (2.1.142 → 2.1.161)
plus trio-compat and stderr-callback fixes — no new API surface.

## What was done

Edits in `src/agent/session.py`:

1. **`api_error_status` surfaced** — added `api_error_status: int | None` to the
   `AgentResult` dataclass; the `ResultMessage` handler reads it (guarded to a
   real `int`) and prefixes errored runs as `[HTTP <status>] <message>`.
2. **Server tool blocks un-dropped** — imported `ServerToolUseBlock` /
   `ServerToolResultBlock`; the receive loop now routes `ServerToolUseBlock` to
   `on_tool_use` (advisor/web_search shows in the activity feed) and flattens
   `ServerToolResultBlock` via new `_server_result_text()` into an `[advisor] …`
   message via `on_message`.

## TODO / status

- [x] Bump `requirements.txt` floor to `>=0.2.88`
- [x] Run full suite on 0.2.88 (1063 passed)
- [x] Commit + merge the bump to `main` (`c783305`)
- [x] Surface `api_error_status` into `AgentResult` (`src/agent/session.py`)
- [x] Un-drop `ServerToolUseBlock` / `ServerToolResultBlock` in the receive loop
- [x] **Thread `api_error_status` through `on_complete`** (`workflow_service`) →
      migration **026** adds `api_error_status` to `token_usage`;
      `save_token_usage` persists it (and now saves when only the status is
      present); `_add_failure_notification` classifies transient codes
      (429/500/502/503/529) as retryable in the UI toast. Tests in
      `test_api_error_status_026.py`, `test_database_service.py`,
      `test_workflow_service.py`. Suite now 1093 passing.
- [ ] Decide UI treatment for `[advisor]` results (reuses the assistant-text
      `on_message` channel today; a distinct channel may read better).
- [x] Add unit tests for the two parsing changes (server blocks + HTTP-prefixed
      error) — `tests/unit/test_session.py` (+15 tests: `_server_result_text`
      helper, `ServerToolUseBlock`/`ServerToolResultBlock` branches, HTTP-status
      prefixing, success/no-status paths). Suite now 1078 passing.
- [x] (Optional) Evaluate `enable_file_checkpointing` + `rewind_files()` for the
      review→reject flow → **decided NO** (lifecycle mismatch: rewind needs a
      live session, review happens post-disconnect; and git worktrees already
      provide a stronger, durable, cross-session undo). See
      [`EVAL_file_checkpointing_2026-06-03.md`](EVAL_file_checkpointing_2026-06-03.md).

> Note: the two `session.py` changes are **unstaged on `main`** as of this
> snapshot — only the `requirements.txt` bump is committed.
