kward 0.67.1 → 0.68.0

data/lib/kward/session_store.rb

@@ -10,17 +10,51 @@ require_relative "rpc/tool_event_normalizer"
 require_relative "tools/tool_call"
 require_relative "workspace"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # JSONL-backed persistence for CLI and RPC conversations.
+  #
+  # A session file is an append-only event log: a header record, message/tree
+  # records, metadata changes, memory state, tool execution metadata, labels, and
+  # branch navigation. `SessionStore` owns disk layout and reconstruction of a
+  # `Conversation`; frontends own when to create, resume, clone, compact, or
+  # delete sessions.
+  #
+  # The tree fields (`id`, `parentId`, leaf records, labels) are part of the
+  # persisted user-data contract. Keep backward compatibility in mind before
+  # changing record shapes, and prefer adding records over rewriting existing
+  # files.
   class SessionStore
     VERSION = 2
     LAST_SESSION_FILENAME = "last_session.json"
 
     SessionInfo = Struct.new(:id, :path, :cwd, :created_at, :modified_at, :name, :first_message, :message_count, :parent_id, :parent_path, :depth, :is_last, :ancestor_continues, keyword_init: true)
 
+    # Live handle that attaches persistence callbacks to a conversation.
+    #
+    # Once attached, every append/compact/tool execution writes a JSONL record and
+    # advances `leaf_id` for session tree navigation. Avoid mutating the attached
+    # conversation directly without these callbacks unless deliberately importing
+    # or reconstructing history.
     class Session
-      attr_reader :id, :path, :cwd, :created_at, :parent_id, :parent_path
-      attr_accessor :name, :leaf_id
-
+      # @return [String] stable persisted session id from the JSONL header
+      attr_reader :id
+      # @return [String] absolute JSONL session file path
+      attr_reader :path
+      # @return [String] workspace directory recorded when the session was created
+      attr_reader :cwd
+      # @return [Time] creation timestamp used for sorting and filenames
+      attr_reader :created_at
+      # @return [String, nil] source session id when this session was cloned or forked
+      attr_reader :parent_id
+      # @return [String, nil] source session path when this session was cloned or forked
+      attr_reader :parent_path
+      # @return [String, nil] user-visible session name persisted as metadata records
+      attr_accessor :name
+      # @return [String, nil] active tree leaf id used to restore the selected branch
+      attr_accessor :leaf_id
+
+      # Creates an object for JSONL session persistence.
       def initialize(store:, id:, path:, cwd:, created_at:, name: nil, parent_id: nil, parent_path: nil, leaf_id: nil)
         @store = store
         @id = id
@@ -33,29 +67,39 @@ module Kward
         @leaf_id = leaf_id
       end
 
+      # Installs persistence callbacks on `conversation`.
+      #
+      # The callbacks are intentionally simple lambdas so `Conversation` remains
+      # storage-agnostic while `SessionStore` remains the only owner of JSONL
+      # record shape.
       def attach(conversation)
         conversation.on_append = lambda { |message| append_message(message) }
         conversation.on_compact = lambda { |message| compact(message) }
         conversation.on_tool_execution = lambda { |tool_call, content| append_tool_execution(tool_call, content) }
+        conversation.on_runtime_update = lambda { |provider:, model:, reasoning_effort:| update_runtime(provider: provider, model: model, reasoning_effort: reasoning_effort) }
         self
       end
 
+      # Persists a message as a tree entry and advances the session leaf.
       def append_message(message)
         record = @store.build_tree_record(@path, "message", @leaf_id, message: message)
         @leaf_id = record[:id]
         @store.append_record(@path, record)
       end
 
+      # Persists a compaction summary entry and makes it the active leaf.
       def compact(message)
         record = @store.build_tree_record(@path, "compaction", @leaf_id, message: message)
         @leaf_id = record[:id]
         @store.append_record(@path, record)
       end
 
+      # Persists normalized tool execution metadata alongside transcript messages.
       def append_tool_execution(tool_call, content)
         @store.append_record(@path, RPC::ToolEventNormalizer.new(tool_call, content: content).execution_record)
       end
 
+      # Persists the session memory snapshot used when the session is restored.
       def update_memory_state(session_memories:, last_retrieval: nil)
         @store.append_record(@path, {
           type: "memory_state",
@@ -65,6 +109,7 @@ module Kward
         })
       end
 
+      # Persists a user-visible session name without rewriting earlier records.
       def rename(name)
         @name = name.to_s.strip.empty? ? nil : name.to_s.strip
         @store.append_record(@path, {
@@ -74,19 +119,23 @@ module Kward
         })
       end
 
+      # Moves the active leaf to an existing entry so future messages fork there.
       def branch(entry_id)
         @leaf_id = entry_id.to_s.empty? ? nil : entry_id.to_s
         @store.append_leaf_change(@path, @leaf_id)
       end
 
+      # Clears the active leaf so the next append starts a fresh root branch.
       def reset_leaf
         branch(nil)
       end
 
+      # Persists a display label override for one tree entry.
       def append_label_change(entry_id, label)
         @store.append_label_change(@path, entry_id, label)
       end
 
+      # Adds a branch-summary node under `parent_id` and selects it as the leaf.
       def append_branch_summary(parent_id, from_id:, summary:, details: {})
         record = @store.build_tree_record(@path, "branch_summary", parent_id, fromId: from_id, summary: summary, details: details || {})
         @leaf_id = record[:id]
@@ -94,29 +143,38 @@ module Kward
         record[:id]
       end
 
-      def update_runtime(model:, reasoning_effort:)
+      # Persists model/runtime metadata so restored sessions keep their context.
+      def update_runtime(provider: nil, model:, reasoning_effort:)
         @store.append_record(@path, {
           type: "session_info",
           timestamp: Time.now.utc.iso8601(3),
           name: @name,
+          provider: provider.to_s,
           model: model.to_s,
           reasoningEffort: reasoning_effort.to_s
         }.delete_if { |_key, value| value.to_s.empty? })
       end
 
+      # Removes this session file when it is still empty and unnamed.
       def delete_if_unused
         @store.delete_unused_session(self)
       end
     end
 
+    # Creates an object for JSONL session persistence.
     def initialize(config_dir: ConfigFiles.config_dir, cwd: Dir.pwd)
       @config_dir = config_dir
       @cwd = File.expand_path(cwd)
     end
 
+    # @return [String] workspace directory this store lists and creates sessions for
     attr_reader :cwd
 
-    def create(model: nil, reasoning_effort: nil, parent_id: nil, parent_path: nil)
+    # Creates a new empty session file for the store's workspace directory.
+    #
+    # Parent fields record clone/fork ancestry; they do not imply live coupling
+    # between files after creation.
+    def create(provider: nil, model: nil, reasoning_effort: nil, parent_id: nil, parent_path: nil)
       dir = session_dir
       FileUtils.mkdir_p(dir, mode: 0o700)
       created_at = Time.now.utc
@@ -128,6 +186,7 @@ module Kward
         id: id,
         timestamp: created_at.iso8601(3),
         cwd: @cwd,
+        provider: provider.to_s,
         model: model.to_s,
         reasoningEffort: reasoning_effort.to_s,
         parentId: parent_id.to_s,
@@ -144,7 +203,7 @@ module Kward
     end
 
     def create_from_conversation(conversation, parent_session: nil)
-      session = create(model: conversation.model, reasoning_effort: conversation.reasoning_effort, parent_id: parent_session&.id, parent_path: parent_session&.path)
+      session = create(provider: conversation.provider, model: conversation.model, reasoning_effort: conversation.reasoning_effort, parent_id: parent_session&.id, parent_path: parent_session&.path)
       session.rename(parent_session.name) unless parent_session&.name.to_s.strip.empty?
       persisted_messages(conversation).each { |message| session.append_message(message) }
       session.attach(conversation)
@@ -155,22 +214,35 @@ module Kward
       create_independent_from_messages(
         persisted_messages(conversation),
         read_paths: Array(conversation.read_paths),
+        provider: conversation.provider,
         model: conversation.model,
         reasoning_effort: conversation.reasoning_effort,
         parent_session: parent_session
       )
     end
 
-    def create_independent_from_messages(messages, read_paths: [], model: nil, reasoning_effort: nil, parent_session: nil)
-      session = create(model: model, reasoning_effort: reasoning_effort, parent_id: parent_session&.id, parent_path: parent_session&.path)
+    # Creates a new session containing an independent copy of selected messages.
+    #
+    # Used by clone/fork flows where the new conversation must preserve selected
+    # history but then diverge without mutating the source session file.
+    #
+    # @param messages [Array<Hash>] messages to persist into the new session
+    # @param read_paths [Array<String>] restored read-before-write paths
+    # @param parent_session [Session, nil] optional source session metadata
+    # @return [Array(Session, Conversation)] new session handle and attached conversation
+    def create_independent_from_messages(messages, read_paths: [], provider: nil, model: nil, reasoning_effort: nil, parent_session: nil)
+      session = create(provider: provider, model: model, reasoning_effort: reasoning_effort, parent_id: parent_session&.id, parent_path: parent_session&.path)
       session.rename(parent_session.name) unless parent_session&.name.to_s.strip.empty?
       persisted = deep_copy(messages)
       persisted.each { |message| session.append_message(message) }
-      conversation = Conversation.new(messages: deep_copy(persisted), read_paths: read_paths, workspace_root: @cwd, model: model, reasoning_effort: reasoning_effort)
+      conversation = Conversation.new(messages: deep_copy(persisted), read_paths: read_paths, workspace_root: @cwd, provider: provider, model: model, reasoning_effort: reasoning_effort)
       session.attach(conversation)
       [session, conversation]
     end
 
+    # Resolves a user-provided path and returns the stored workspace location.
+    #
+    # @return [Hash] `:path` and `:cwd` for loading the session safely
     def session_location(path)
       resolved_path = resolve_session_path(path)
       records = records_from_file(resolved_path)
@@ -178,7 +250,12 @@ module Kward
       { path: resolved_path, cwd: header["cwd"].to_s.empty? ? @cwd : header["cwd"].to_s }
     end
 
-    def load(path, workspace: Workspace.new, model: nil, reasoning_effort: nil)
+    # Loads a session file and reconstructs its current conversation leaf.
+    #
+    # `workspace` is used both for the active root and to restore read-before-write
+    # paths from successful read tool results. If a session moved workspaces, load
+    # it through `session_location` first so the original cwd is respected.
+    def load(path, workspace: Workspace.new, provider: nil, model: nil, reasoning_effort: nil)
       resolved_path = resolve_session_path(path)
       records = records_from_file(resolved_path)
       header = session_header(records, resolved_path)
@@ -194,6 +271,7 @@ module Kward
         messages: messages,
         read_paths: read_paths,
         workspace_root: workspace.root,
+        provider: runtime["provider"] || provider,
         model: runtime["model"] || model,
         reasoning_effort: runtime["reasoningEffort"] || reasoning_effort,
         session_memories: memory_state["sessionMemories"],
@@ -215,11 +293,17 @@ module Kward
       [session, conversation]
     end
 
+    # Lists recent non-empty sessions for this workspace.
+    #
+    # @param limit [Integer, nil] maximum number of sessions, or nil for all
+    # @param keep_empty_path [String, nil] empty session path to keep visible
+    # @return [Array<SessionInfo>] newest sessions first
     def recent(limit: 20, keep_empty_path: nil)
       sessions = recent_sessions(keep_empty_path: keep_empty_path)
       limit ? sessions.first(limit) : sessions
     end
 
+    # Persists the last active session pointer for workspace auto-resume.
     def remember_last_session(session)
       return unless session&.path
 
@@ -231,6 +315,7 @@ module Kward
       File.join(session_dir, LAST_SESSION_FILENAME)
     end
 
+    # @return [String, nil] remembered session path when the file still exists
     def remembered_last_session_path
       return nil unless File.file?(last_session_path)
 
@@ -242,12 +327,18 @@ module Kward
       nil
     end
 
+    # Lists recent sessions decorated with parent/branch display metadata.
+    #
+    # @return [Array<SessionInfo>] recent sessions with tree depth fields
     def recent_tree(limit: 20, keep_empty_path: nil)
       sessions = recent_sessions(keep_empty_path: keep_empty_path)
       sessions = sessions.first(limit) if limit
       decorate_tree(sessions)
     end
 
+    # Deletes an empty unnamed session file.
+    #
+    # @return [Boolean] true when a file was removed
     def delete_unused_session(session)
       path = session.path
       return false if session_named?(session)
@@ -264,6 +355,9 @@ module Kward
     end
 
 
+    # Builds a persisted tree record and assigns a stable entry id to messages.
+    #
+    # @return [Hash] JSONL-ready tree record
     def build_tree_record(path, type, parent_id, fields = {})
       message = fields[:message]
       id = message_entry_id(message) || next_entry_id(path)
@@ -294,11 +388,13 @@ module Kward
       })
     end
 
+    # @return [Array<Hash>] nested session tree roots for the given session file
     def session_tree(path)
       records = records_from_file(resolve_session_path(path))
       build_session_tree(records)
     end
 
+    # @return [Array<Hash>] flat tree records with resolved labels attached
     def session_entries(path)
       records = records_from_file(resolve_session_path(path))
       labels = labels_by_target(records)
@@ -312,10 +408,14 @@ module Kward
       end
     end
 
+    # Finds one persisted tree entry by id.
+    #
+    # @return [Hash, nil]
     def session_entry(path, entry_id)
       session_entries(path).find { |record| record["id"].to_s == entry_id.to_s }
     end
 
+    # @return [String, nil] current active tree leaf id
     def current_leaf(path)
       current_leaf_id(records_from_file(resolve_session_path(path)))
     end
@@ -351,16 +451,10 @@ module Kward
     end
 
     def normalize_tree_records(records)
-      parent_id = nil
-      entry_index = 0
       records.each do |record|
-        next unless tree_entry_record?(record)
+        next unless tree_entry_record?(record) && !record["id"].to_s.empty?
 
-        record["id"] = "message:#{entry_index}" if record["id"].to_s.empty?
-        record["parentId"] = parent_id unless record.key?("parentId")
         assign_message_entry_id(record["message"], record["id"]) if record["message"].is_a?(Hash) && message_entry_id(record["message"]).to_s.empty?
-        parent_id = record["id"]
-        entry_index += 1
       end
       records
     end
@@ -414,12 +508,14 @@ module Kward
 
     def session_runtime(records, header)
       result = {
+        "provider" => header["provider"],
         "model" => header["model"],
         "reasoningEffort" => header["reasoningEffort"]
       }
       records.each do |record|
         next unless record["type"] == "session_info"
 
+        result["provider"] = record["provider"] if record.key?("provider")
         result["model"] = record["model"] if record.key?("model")
         result["reasoningEffort"] = record["reasoningEffort"] if record.key?("reasoningEffort")
       end
@@ -471,9 +567,7 @@ module Kward
     end
 
     def branch_records(records)
-      return legacy_branch_records(records) unless records.any? { |record| tree_entry_record?(record) && !record["id"].to_s.empty? }
-
-      entries = records.select { |record| tree_entry_record?(record) }
+      entries = records.select { |record| tree_entry_record?(record) && !record["id"].to_s.empty? }
       by_id = entries.to_h { |record| [record["id"].to_s, record] }
       leaf_id = current_leaf_id(records)
       return [] if leaf_id.nil?
@@ -490,10 +584,6 @@ module Kward
       branch.reverse
     end
 
-    def legacy_branch_records(records)
-      records.select { |record| ["message", "compaction"].include?(record["type"]) }
-    end
-
     def current_leaf_id(records)
       latest = records.reverse.find { |record| record["type"] == "leaf" || (tree_entry_record?(record) && !record["id"].to_s.empty?) }
       return nil unless latest

data/lib/kward/session_trash.rb

@@ -1,6 +1,7 @@
 require "open3"
 require "rbconfig"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Best-effort session file remover. Uses the OS trash/recycle bin when a
   # supported platform tool is available, and falls back to permanent deletion.

data/lib/kward/session_tree_renderer.rb

@@ -1,8 +1,11 @@
-require "json"
 require_relative "message_access"
+require_relative "message_text"
+require_relative "session_tree_tool_display"
 require_relative "tools/tool_call"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Terminal renderer for persisted session tree choices.
   class SessionTreeRenderer
     def initialize(roots:, current_leaf_id:)
       @roots = roots
@@ -173,45 +176,18 @@ module Kward
 
     def session_tree_tool_display(message, tool_calls_by_id)
       tool_call = tool_calls_by_id[session_tree_message_tool_call_id(message).to_s]
-      return session_tree_format_tool_call(tool_call) if tool_call
+      return SessionTreeToolDisplay.label(tool_call) if tool_call
 
       name = session_tree_message_tool_name(message).to_s
       "[#{name.empty? ? 'tool' : name}]"
     end
 
     def session_tree_message_tool_call_id(message)
-      message_tool_call_id(message) || MessageAccess.value(message, :toolCallId)
+      message_tool_call_id(message)
     end
 
     def session_tree_message_tool_name(message)
-      message_name(message) || MessageAccess.value(message, :toolName)
-    end
-
-    def session_tree_format_tool_call(tool_call)
-      name = ToolCall.display_name(tool_call)
-      args = tool_call_args(tool_call)
-      case name
-      when "read"
-        path = args["path"] || args[:path] || args["file_path"] || args[:file_path]
-        offset = args["offset"] || args[:offset]
-        limit = args["limit"] || args[:limit]
-        display = path.to_s
-        if offset || limit
-          start_line = offset || 1
-          end_line = limit ? start_line.to_i + limit.to_i - 1 : nil
-          display += ":#{start_line}#{end_line ? "-#{end_line}" : ""}"
-        end
-        "[read: #{display}]"
-      when "write", "edit"
-        path = args["path"] || args[:path] || args["file_path"] || args[:file_path]
-        "[#{name}: #{path}]"
-      when "bash"
-        command = (args["command"] || args[:command]).to_s.gsub(/[\n\t]/, " ").strip
-        "[bash: #{command.length > 50 ? "#{command.slice(0, 50)}..." : command}]"
-      else
-        serialized = JSON.dump(args)
-        "[#{name}: #{serialized.length > 40 ? "#{serialized.slice(0, 40)}..." : serialized}]"
-      end
+      message_name(message)
     end
 
     def display_message_text(message)
@@ -224,13 +200,7 @@ module Kward
     end
 
     def full_message_text(message)
-      content = message_content(message)
-      text = if content.is_a?(Array)
-               content.filter_map { |part| MessageAccess.value(part, :text) }.join("\n")
-             else
-               content.to_s
-             end
-      text.strip
+      MessageText.full_text(message)
     end
 
     def message_role(message)
@@ -257,8 +227,5 @@ module Kward
       ToolCall.id(tool_call)
     end
 
-    def tool_call_args(tool_call)
-      ToolCall.arguments(tool_call)
-    end
   end
 end

data/lib/kward/session_tree_tool_display.rb

@@ -0,0 +1,56 @@
+require "json"
+require_relative "tools/tool_call"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Formats persisted tool calls for compact session tree rows.
+  #
+  # Both the terminal session tree and the RPC session tree need the same short
+  # labels for tool result nodes. Keeping that display rule here prevents the two
+  # frontends from drifting while leaving each frontend free to render its own
+  # tree prefixes and wire payloads.
+  module SessionTreeToolDisplay
+    module_function
+
+    # Returns a concise bracketed label for a tool call.
+    #
+    # @param tool_call [Hash] OpenAI/Codex-style tool call hash
+    # @return [String] label such as `[read: README.md:2-4]`
+    def label(tool_call)
+      name = ToolCall.display_name(tool_call)
+      args = ToolCall.arguments(tool_call)
+      case name
+      when "read"
+        read_label(args)
+      when "write", "edit"
+        path = args["path"] || args[:path] || args["file_path"] || args[:file_path]
+        "[#{name}: #{path}]"
+      when "bash"
+        command = (args["command"] || args[:command]).to_s.gsub(/[\n\t]/, " ").strip
+        "[bash: #{truncate(command, 50)}]"
+      else
+        serialized = JSON.dump(args)
+        "[#{name}: #{truncate(serialized, 40)}]"
+      end
+    end
+
+    def read_label(args)
+      path = args["path"] || args[:path] || args["file_path"] || args[:file_path]
+      offset = args["offset"] || args[:offset]
+      limit = args["limit"] || args[:limit]
+      display = path.to_s
+      if offset || limit
+        start_line = offset || 1
+        end_line = limit ? start_line.to_i + limit.to_i - 1 : nil
+        display += ":#{start_line}#{end_line ? "-#{end_line}" : ""}"
+      end
+      "[read: #{display}]"
+    end
+    private_class_method :read_label
+
+    def truncate(text, length)
+      text.length > length ? "#{text.slice(0, length)}..." : text
+    end
+    private_class_method :truncate
+  end
+end

data/lib/kward/skills/registry.rb

@@ -1,7 +1,10 @@
 require "pathname"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Skill discovery and metadata parsing from configured skill folders.
   module Skills
+    # Parsed skill metadata and instruction path.
     class Registry
       def initialize(config_dir:, skill_class:, max_file_bytes:, markdown_parser:, inside_directory:)
         @config_dir = config_dir

data/lib/kward/starter_pack_installer.rb

@@ -7,6 +7,7 @@ require "uri"
 require "zlib"
 require_relative "config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Installs Kward's starter prompt/instruction files into the user config dir.
   class StarterPackInstaller

data/lib/kward/steering.rb

@@ -1,7 +1,9 @@
 require "thread"
 require "time"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Thread-safe queue for in-flight user steering events.
   class Steering
     Event = Struct.new(:input, :created_at, keyword_init: true)
 

data/lib/kward/telemetry/logger.rb

@@ -4,7 +4,9 @@ require "time"
 require_relative "../config_files"
 require_relative "../rpc/redactor"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Append-only JSONL telemetry logger with secret-conscious error payloads.
   class TelemetryLogger
     CATEGORIES = %w[tokens performance tools errors].freeze
     ENV_KEYS = {
@@ -16,6 +18,7 @@ module Kward
     }.freeze
     DEFAULT_MAX_BYTES = 10 * 1024 * 1024
 
+    # Creates an object for telemetry event logging.
     def initialize(config_path: ConfigFiles.config_path, log_dir: nil, max_bytes: DEFAULT_MAX_BYTES, clock: Time, monotonic_clock: Process, error_output: $stderr)
       @config_path = config_path
       @log_dir = log_dir

data/lib/kward/telemetry/stats.rb

@@ -3,7 +3,9 @@ require "time"
 require_relative "../config_files"
 require_relative "logger"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Aggregates local telemetry logs into token and usage statistics.
   class TelemetryStats
     DEFAULT_RANGE = "1 week"
     UNITS = %w[minute hour day week month year].freeze
@@ -34,6 +36,7 @@ module Kward
       end
     end
 
+    # Creates an object for telemetry statistics aggregation.
     def initialize(telemetry_logger: TelemetryLogger.new, clock: Time)
       @telemetry_logger = telemetry_logger
       @clock = clock

data/lib/kward/tools/ask_user_question.rb

@@ -1,8 +1,13 @@
+require_relative "../question_contract"
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for structured clarification questions to the user.
     class AskUserQuestion < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(prompt:)
         @prompt = prompt
         super(
@@ -42,6 +47,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         return "Error: ask_user_question requires interactive prompt support." unless @prompt.respond_to?(:ask_user_question)
 
@@ -67,40 +73,22 @@ module Kward
       end
 
       def validated_questions(args)
-        questions = argument(args, :questions)
-        return "Error: ask_user_question requires questions." unless questions.is_a?(Array)
-        return "Error: ask_user_question requires 1 to 4 questions." unless questions.length.between?(1, 4)
-
-        questions.map.with_index(1) do |question, index|
-          return "Error: question #{index} must be an object." unless question.respond_to?(:key?)
-          return "Error: question #{index} uses unsupported multiSelect." if question.key?("multiSelect") || question.key?(:multiSelect)
-
-          text = question_value(question, :question).to_s.strip
-          header = question_value(question, :header).to_s.strip
-          options = question_value(question, :options)
-          return "Error: question #{index} requires question and header." if text.empty? || header.empty?
-          return "Error: question #{index} requires 2 to 4 options." unless options.is_a?(Array) && options.length.between?(2, 4)
-
-          normalized_options = options.map.with_index(1) do |option, option_index|
-            return "Error: question #{index} option #{option_index} must be an object." unless option.respond_to?(:key?)
-            return "Error: question #{index} option #{option_index} uses unsupported preview." if option.key?("preview") || option.key?(:preview)
-
-            label = question_value(option, :label).to_s.strip
-            description = question_value(option, :description).to_s.strip
-            return "Error: question #{index} option #{option_index} requires label and description." if label.empty? || description.empty?
-
-            { label: label, description: description }
-          end
-
-          { question: text, header: header, options: normalized_options }
-        end
+        QuestionContract.normalize_questions(argument(args, :questions))
+      rescue ArgumentError => e
+        "Error: #{tool_error_message(e.message)}."
       end
 
-      def question_value(object, key)
-        return object[key] if object.key?(key)
-        return object[key.to_s] if object.key?(key.to_s)
-
-        nil
+      def tool_error_message(message)
+        case message
+        when "questions must be an array"
+          "ask_user_question requires questions"
+        when "ui/question requires 1-4 questions"
+          "ask_user_question requires 1 to 4 questions"
+        else
+          message.gsub("2-4", "2 to 4")
+                 .gsub("multiSelect is unsupported", "uses unsupported multiSelect")
+                 .gsub("preview is unsupported", "uses unsupported preview")
+        end
       end
     end
   end