Follow Python SDK #1331/#1332: hook types, raw hook input, init fields

[ya-luotao]

Summary

Follows the two unreleased Python SDK changes on main (anthropics/claude-agent-sdk-python#1331, #1332), and fixes the Ruby-side gap that made the first one matter: typed hook inputs used to drop every field the SDK did not list by hand.

Hook inputs

• Query#parse_hook_input was a 27-branch case that copied a fixed field list per event, so any field a newer CLI added (prompt_id, effort, duration_ms, ...) never reached the callback. It is now an event → class table (HOOK_INPUT_CLASSES, like MessageParser::SYSTEM_MESSAGE_CLASSES) built with the lenient from_hash, and every hook input keeps the payload as #raw_input (previously UnknownHookInput only). #inspect shows raw_input on an UnknownHookInput only, as typed system messages leave out data: a typed input already prints those fields as attributes.
• New fields: prompt_id, effort (all inputs); duration_ms (PostToolUse / PostToolUseFailure); session_title, source (UserPromptSubmit); session_title, seconds_since_last_response, prompt_cache_likely_expired, context_tokens, estimated_cache_write_usd (SessionStart); parent_file_path (InstructionsLoaded).
• New typed inputs for PostToolBatch, UserPromptExpansion, PreModelSwitch, PostModelSwitch, DirectoryAdded, MessageDisplay; HOOK_EVENTS now matches the CLI's 33 events. The two model-switch inputs read every field of the CLI schema, cache_ttl and pricing included.
• Fields beyond Python's list come from the hook input schemas in the Claude Code 2.1.273 and 2.1.295 binaries. mcp_server (new in 2.1.295, marked @internal) is left to raw_input.

Hook-specific outputs

• Each *HookSpecificOutput class declares its fields with attr_accessor (so YARD documents them) and a small @api private HookSpecificOutputFields helper adds the event name, #initialize and a #to_h that takes wire keys from HookOutputKeys::HOOK_SPECIFIC, so the table is the single vocabulary instead of being kept in step with 12 hand-written #to_hs. A YARD macro documents the generated members.
• Adds the 10 output classes from #1331 (PostToolBatch, UserPromptExpansion, Stop, SubagentStop, PreModelSwitch, PostModelSwitch, Elicitation, ElicitationResult, WorktreeCreate, MessageDisplay) and the new UserPromptSubmit / SessionStart fields. Hash outputs could already send these keys; the typed classes raised ArgumentError.

InitMessage

• capabilities, plugin_errors, terminal_slash_commands, fast_mode_disabled_reason (#1332's SystemInitData).

Behavior changes (in CHANGELOG)

• PermissionDeniedHookSpecificOutput#retry defaults to nil and is omitted (was false, always sent; the CLI reads both the same).
• An output field set to false is now sent; only nil is omitted (most fields used to drop false too).

sig/, docs/hooks-and-permissions.md (new output-class table), docs/types.md and CHANGELOG are updated; README, the skill (both copies), the plugin manifest and the lifecycle example now say 33 hook events and list the 22 output classes.

Test plan

• bundle exec rspec: 4314 examples, 0 failures (query_hook_input_spec now has rows for all 33 events, checks raw_input, and covers an unknown event)
• bundle exec rubocop: no offenses
• bundle exec rake rbs:validate rbs:test: 3903 examples, 0 failures
• yard doc: every *HookSpecificOutput page lists its fields, #hook_event_name, #initialize and #to_h; no warning from types/hooks.rb
• Real session against CLI 2.1.295: InitMessage#capabilities / #fast_mode_disabled_reason populated, UserPromptSubmitHookInput#prompt_id received, typed UserPromptSubmitHookSpecificOutput(session_title:) accepted. Tool-use and Stop hooks were not exercised live (the test account's API credit was exhausted).

https://ampcode.com/threads/T-01a127a8-ad00-706d-a216-afc5c6d86e27