ya-luotao/claude-agent-sdk-ruby/claude-agent-ruby

Claude Agent Ruby SDK

Overview

Use this skill to build or refactor Ruby integrations with Claude Code via claude-agent-sdk, favoring the gem's README, the docs/ topic subpages, and lib/ types for exact APIs.

Decision Guide

• Choose ClaudeAgentSDK.ask(prompt, options:) when only the final answer matters: it runs query to completion and returns the ResultMessage (#result is the text); an optional block still sees every message.
• Choose ClaudeAgentSDK.query for one-shot queries or streaming input. It runs the same control protocol as Client, so hooks, can_use_tool and SDK MCP tools work with it (and with ask).
• Choose ClaudeAgentSDK::Client for multi-turn sessions and for control calls while a session runs: interrupt, model or permission-mode switching, MCP server control, file rewind. Prefer ClaudeAgentSDK::Client.open(options: ...) { |client| ... } — it creates its own reactor and always disconnects (return a value instead of break outside a reactor); use Client.new + connect / ensure disconnect only inside an existing Async block.
• Choose SDK MCP servers (create_tool, create_sdk_mcp_server) for in-process tools; choose external MCP configs for subprocess/HTTP servers.
• Choose ClaudeAgentSDK.list_sessions / ClaudeAgentSDK.get_session_messages for browsing previous session transcripts (pure filesystem, no CLI needed).

Implementation Checklist

• Confirm prerequisites (Ruby 3.2+, Node.js, Claude Code CLI).
• Build ClaudeAgentSDK::ClaudeAgentOptions and pass it to query or Client.new.
• Handle messages by type — the SDK has 28 typed message classes:
• Core: AssistantMessage, UserMessage, ResultMessage, StreamEvent, RateLimitEvent
• Conversation reset: ConversationResetMessage (the conversation was replaced mid-session, e.g. /clear — see references/message-handling.md)
• System init: InitMessage (session start / /clear — carries uuid, session_id, tools, model, cwd, agents, betas, claude_code_version, permission_mode, slash_commands, output_style, skills, plugins, fast_mode_state)
• Compaction: CompactBoundaryMessage (uuid, session_id, compact_metadata with pre_tokens, trigger, preserved_segment)
• Status: StatusMessage (compacting status, permission mode changes)
• Tasks: TaskStartedMessage (+ workflow_name, prompt, subagent_type, is_backgrounded, spawn_depth, skip_transcript, ambient), TaskProgressMessage (+ summary, subagent_type), TaskNotificationMessage (+ reason, resource_links, skip_transcript, ambient), TaskUpdatedMessage (lifecycle state change; status — and is_backgrounded, error, end_time, total_paused_ms, description — derived from patch, task_id always a String — clear active-task tracking when status is in TERMINAL_TASK_STATUSES). Optional booleans keep nil (absent) distinct from false: is_backgrounded == false means foreground/blocking
• Subagent UI: BackgroundTasksChangedMessage (tasks — the full live background set, REPLACE semantics; reset on CLI restart), PermissionDeniedMessage (auto-denied tool call; best-effort advisory — ResultMessage#permission_denials is authoritative). See docs/subagents.md
• Hooks: HookStartedMessage, HookProgressMessage, HookResponseMessage
• Sessions: SessionStateChangedMessage (idle/running/requires_action) — only reaches your code when you set CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1 in env; the frames the SDK requests for itself (to know when a query() run is over) are hidden
• Tools: ToolProgressMessage (elapsed_time_seconds per tool), ToolUseSummaryMessage
• Auth: AuthStatusMessage (isAuthenticating, output, error)
• Files: FilesPersistedMessage (files, failed, processed_at)
• API: APIRetryMessage (attempt, max_retries, retry_delay_ms, error_status)
• Session store: MirrorErrorMessage (a SessionStore append failed terminally — timeouts immediately, other failures after up to three attempts; session continues; local transcript stays durable)
• Other: LocalCommandOutputMessage, ElicitationCompleteMessage, PromptSuggestionMessage
• Unknown message types return nil (forward-compatible)
• Handle content blocks: TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock, UnknownBlock
• AssistantMessage carries: content, model, parent_tool_use_id, error, usage, message_id (API message ID), stop_reason, session_id, uuid (transcript UUID)
• ResultMessage carries: stop_reason, model_usage (per-model breakdown), permission_denials, errors (on error subtypes), uuid, fast_mode_state, terminal_reason (why the query loop ended; aborted_streaming/aborted_tools mean interrupted)
• Use output_format for JSON schema structured output
• Use thinking: ThinkingConfigAdaptive.new and control depth with effort:. ThinkingConfigEnabled(budget_tokens:) is only for older models that take a fixed budget; ThinkingConfigDisabled turns thinking off.

Hooks (33 events)

All hook events: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, Notification, UserPromptSubmit, UserPromptExpansion, SessionStart, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop, PreCompact, PostCompact, PreModelSwitch, PostModelSwitch, PermissionRequest, PermissionDenied, Setup, TeammateIdle, TaskCreated, TaskCompleted, Elicitation, ElicitationResult, ConfigChange, WorktreeCreate, WorktreeRemove, InstructionsLoaded, CwdChanged, FileChanged, DirectoryAdded, MessageDisplay.

Every hook input also keeps the payload exactly as the CLI sent it in raw_input (Symbol keys), so a field this SDK version has no reader for is still readable; an event it does not know arrives as an UnknownHookInput.

Define hooks as Ruby procs/lambdas. Do not combine can_use_tool with permission_prompt_tool_name. Tool-lifecycle hooks carry agent_id and agent_type when firing inside subagents. StopHookInput and SubagentStopHookInput include last_assistant_message plus optional background_tasks / session_crons snapshots of the parent session's background work (nil = not provided, [] = explicitly empty; not a registry of all agents). Every dispatched hook and can_use_tool callback gets context.request_id and context.signal (a ClaudeAgentSDK::CancellationSignal: cancelled? / wait(timeout:)) — cancellation is cooperative (CLI cancel, EOF, disconnect, callback failure, hook timeout), default :thread callbacks are never force-killed, and a decision returned after cancellation is discarded, never sent as an allow.

Hook-specific outputs with to_h (fields per class: docs/hooks-and-permissions.md): PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, PostToolBatchHookSpecificOutput, UserPromptSubmitHookSpecificOutput, UserPromptExpansionHookSpecificOutput, SessionStartHookSpecificOutput, SetupHookSpecificOutput, NotificationHookSpecificOutput, SubagentStartHookSpecificOutput, StopHookSpecificOutput, SubagentStopHookSpecificOutput, PermissionRequestHookSpecificOutput, PermissionDeniedHookSpecificOutput, PreModelSwitchHookSpecificOutput, PostModelSwitchHookSpecificOutput, ElicitationHookSpecificOutput, ElicitationResultHookSpecificOutput, CwdChangedHookSpecificOutput, FileChangedHookSpecificOutput, WorktreeCreateHookSpecificOutput, MessageDisplayHookSpecificOutput.

Bare Mode

Use bare: true for minimal startup — skips hooks, LSP, plugin sync, CLAUDE.md auto-discovery, auto-memory, keychain reads. Explicitly provide context via system_prompt, add_dirs, setting_sources, allowed_tools.

options = ClaudeAgentSDK::ClaudeAgentOptions.new(
  bare: true,
  system_prompt: 'You are a code reviewer.',
  permission_mode: 'bypassPermissions'
)

Sandbox Settings (full CC parity)

• SandboxSettings: enabled, fail_if_unavailable, auto_allow_bash_if_sandboxed, excluded_commands, allow_unsandboxed_commands, network, filesystem, ignore_violations (Hash), enable_weaker_nested_sandbox, enable_weaker_network_isolation, ripgrep
• SandboxNetworkConfig: allowed_domains, denied_domains, allow_managed_domains_only, allow_unix_sockets, allow_all_unix_sockets, allow_local_binding, allow_mach_lookup, http_proxy_port, socks_proxy_port
• SandboxFilesystemConfig: allow_write, deny_write, deny_read, allow_read, allow_managed_read_paths_only

SDK MCP Tools

• Include mcp__<server>__<tool> in allowed_tools
• Use annotations: on create_tool for MCP tool annotations
• Use meta: on create_tool for _meta field forwarding (e.g., { 'anthropic/maxResultSizeChars' => 100000 } to prevent truncation of large results)
• If annotations[:maxResultSizeChars] is set, _meta is auto-populated with it; an explicit meta: is merged with that hint, and a key set in meta: wins
• Both symbol-keyed and string-keyed input_schema hashes are accepted