v0.31.0

Syncs the gem with Python SDK 0.2.147 (from 0.2.134). The intervening Python releases only bump the CLI binary Python vendors; this gem doesn't ship a CLI, so all functional work comes from 0.2.137 and 0.2.140.

Added

• ConversationResetMessage (Python #1196) — the CLI's conversation_reset frame, previously dropped by the parser's forward-compat fallthrough, so apps never saw a /clear. A reset also zeroes the running totals on later ResultMessages — snapshot them here.
• origin on UserMessage / ResultMessage (Python #1199) — tells your own prompts apart from turns the session injects (background-task notifications, scheduled triggers, MCP channel messages, peer sessions). Keys are Symbols with the CLI's camelCase preserved (origin[:fromSession]), unlike the Python SDK's string-keyed equivalent.
• forward_subagent_text (Python #1206) — forward a subagent's text and thinking blocks, not just its tool calls, to render the full nested transcript.
• resume_drops_turn (Python #1198) — completes the truncating-resume pair with resume_session_at: the CLI refuses the resume if anything past the fork point isn't attributable to the turn you meant to discard, so a queued message or task notification absorbed mid-turn isn't dropped silently.
• ResultError (Python #1205) — a typed exception carrying subtype, errors, result, api_error_status, terminal_reason, session_id and the raw payload, so you can branch on why a run failed instead of matching strings. Subclasses ProcessError, so existing handlers keep working.
• SessionMessage#parent_agent_id, and parent_tool_use_id is now populated for subagent transcripts (Python #1207) — both were nil for every subagent message before.

Changed

• can_use_tool now works with a String prompt (Python #1204) and with ClaudeAgentSDK.query, not just Client. It previously raised ArgumentError.

Fixed

• can_use_tool permission requests were being cut off when it was the only bidirectional feature in use — an Enumerator prompt with no hooks and no SDK MCP servers closed stdin as soon as input ended, and later permission requests failed CLI-side with "Stream closed". This broke an already-supported path.
• A refused resume reported a bare "exit code 1" to the in-flight handshake, discarding the CLI's actual reason.
• Store-backed resume now seeds settings.json / cowork_settings.json (Python #1197) — without it, a host authenticating solely via apiKeyHelper failed with "Not logged in" the moment it resumed from a store.
• An unusable subagent metadata sidecar no longer breaks every later resume. Ruby's JSON.parse is lenient about illegal bytes in a UTF-8-tagged document, so garbage was persisted into the store and every subsequent resume then died with an opaque JSON::GeneratorError — permanently, until the entry was repaired by hand. (Ruby-only: Python's decode raises up front.)
• settings.json with a lone surrogate escape is no longer copied through unstripped — Ruby's parser rejects lone surrogates where Python's accepts them, so enabledPlugins survived and the resumed CLI kept network-installing marketplaces on every resume.
• Regular-file guards before opening optional config and sidecar files, so a FIFO can't hang a resume or get_subagent_messages forever, and redacting .credentials.json no longer aborts a resume on a serialization failure.

Compatibility

ConversationResetMessage widens the Message union with a frame that was previously dropped silently — code that raises on an unrecognized message class will now see it, on the first /clear of a long-lived session.

Usage

begin
  ClaudeAgentSDK.query(prompt: "...") { |m| handle(m) }
rescue ClaudeAgentSDK::ResultError => e
  retry_later  if e.terminal_reason == 'api_error'
  widen_budget if e.subtype == 'error_max_turns'
  raise
end

What's changed

• #55 Sync with Python SDK 0.2.147 (0.2.137 + 0.2.140 feature releases) — @ya-luotao

Full Changelog: v0.30.0...v0.31.0

---

gem install claude-agent-sdk -v 0.31.0