rubyn-code 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5cbf6f4737790408893a904d64412c2dd695e81a2cd2e5960b4da3196e48f4f
-  data.tar.gz: f0e9b80f10c77d6eb6c357db7518851344670653546d5eca2784d017d490608c
+  metadata.gz: 7696c779b900fe4dca806aa73d7fcca79309ebe58a242d16e2d5309b43d44ec4
+  data.tar.gz: 2d8d4c8905255ce11e98569f86f4c2d788c620ea30c513fd6771b3c58bb98073
 SHA512:
-  metadata.gz: bc4553f04fbac43903e1515cec43cf595245d36223bca70342ddafb2a2920f38f502b356eb353b4b6e5284d128688e07c015e0a3ebb4aa06f7029fac0ba42a37
-  data.tar.gz: b9f8ab09a40e073bff1657ef9d829b7551a5ca56ce9f77b65bd59b835d079665d3663faf92ccf44fd84d4ff3674f835c09d102b4f449c175c77bcafb466dd934
+  metadata.gz: c5d2b5f15b21d7e02b2f6c2252248eb6e933337b3f4c491135f5453c1ddf4ce47c48605aaeb6e26180a38324c8effc7a149e528c794ca9391ec8c43febbc2bdb
+  data.tar.gz: 15c9aa06c02dd8c105116b403cba0f36cb5a2b91c8690b66b6320a289011cf6f2986a308fdaacad933fbd221646de84b7f774a47709a7c8409fdc5bddca5b671

data/README.md

@@ -15,7 +15,7 @@
   <a href="https://github.com/MatthewSuttles/rubyn-code/actions/workflows/ci.yml"><img src="https://github.com/MatthewSuttles/rubyn-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
 </p>
 
-Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code for anti-patterns, and build entire features — all context-aware with your schema, routes, and specs. Powered by Claude Opus 4.6, running on your existing Claude subscription.
+Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code for anti-patterns, and build entire features — all context-aware with your schema, routes, and specs. Powered by Claude Opus 4.8, running on your existing Claude subscription.
 
 <img width="1230" height="280" alt="image" src="https://github.com/user-attachments/assets/14e07ce8-def0-4a8f-ac89-46661361a4eb" />
 
@@ -69,6 +69,22 @@ Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code f
 - **IDE-ready** — works in the terminal and inside VS Code with full bidirectional communication
 - **Extensible** — connect external tool servers via MCP, add custom skills, or wire up your own providers
 
+## Claude Code Feature Parity
+
+Phase 4 ships nine parity features with Claude Code:
+
+- **Extended thinking** — `/think <budget>` toggles per-session reasoning; the Anthropic adapter emits `thinking: {type: 'adaptive'}` on Claude 4.6+ models (`{type: 'enabled', budget_tokens}` on older ones).
+- **Reasoning effort** — `/effort <low|medium|high|xhigh|max>` sets the request-level reasoning depth; the Anthropic adapter emits `output_config: {effort}` on the wire. GA on Claude 4.6+ (Opus 4.6/4.7/4.8, Sonnet 4.6/5, Fable 5); `xhigh` needs Opus 4.7+ / Sonnet 5 / Fable 5. Model default is `high`.
+- **Task budgets (beta)** — the agent loop's remaining token budget is sent as `output_config: {task_budget: {type: 'tokens', total}}` on supported models (Fable 5, Sonnet 5, Opus 4.7/4.8), advisory pacing only — `max_tokens` stays the enforced per-response cap.
+- **Image / vision input** — `@chart.png` (and `.jpg` / `.jpeg` / `.gif` / `.webp`) becomes a real image content block attached to the user turn; Anthropic and OpenAI each emit their native shape.
+- **TodoWrite live checklist** — `TodoWrite` tool; the checklist refreshes above the spinner on every tool result so you see in-turn progress at a glance.
+- **Custom-command frontmatter** — `argument-hint`, `allowed-tools`, and `model:` keys in `~/.rubyn-code/commands/*.md`; the loop honors the per-prompt tool restriction and model override.
+- **`.mcp.json` auto-discovery** — project-root MCP servers flow into the REPL automatically; `/mcp` shows entries prefixed `[project]` or `[user]`. OAuth for URL transports is still deferred.
+- **`/export` transcript** — `/export <path>` writes the conversation as Markdown (default) or `--jsonl` for tooling.
+- **Fable 5 refusal handling** — a declined request (`stop_reason: "refusal"`) surfaces a clear message instead of an empty turn; `claude-fable-5` / `claude-mythos-5` requests opt into a server-side Opus 4.8 fallback by default, so most refusals are transparently re-served in the same call.
+
+See `docs/04-feature-parity/` for per-feature design + tasks docs.
+
 ## Install
 
 Requires **Ruby 4.0.2+**. Install with your latest Ruby, then pin it so it works in every project:

data/lib/rubyn_code/agent/conversation.rb

@@ -14,7 +14,10 @@ module RubynCode
 
       # Append a user turn to the conversation.
       #
-      # @param content [String]
+      # @param content [String, Array<Hash>] either a plain string or an
+      #   array of content blocks (text, image, etc.). Strings get wrapped
+      #   as `[{ type: 'text', text: content }]` only if there's a planned
+      #   Array; we keep raw String for backward compatibility with the API.
       # @return [Hash] the appended message
       def add_user_message(content)
         message = { role: 'user', content: content }
@@ -155,6 +158,13 @@ module RubynCode
         reset_derived_state!
       end
 
+      # Alias for `messages`. Common shorthand for callers that want to
+      # treat the conversation as an Array of message hashes.
+      def to_a
+        @messages
+      end
+      alias to_ary to_a
+
       private
 
       # Derived bookkeeping kept in sync with @messages so hot paths stay

data/lib/rubyn_code/agent/dynamic_tool_schema.rb

@@ -8,7 +8,7 @@ module RubynCode
     # prompt overhead by 30-50%.
     module DynamicToolSchema
       BASE_TOOLS = %w[
-        read_file write_file edit_file glob grep bash
+        read_file write_file edit_file glob grep code_graph bash
       ].freeze
 
       TASK_TOOLS = {

data/lib/rubyn_code/agent/llm_caller.rb

@@ -25,7 +25,7 @@ module RubynCode
       def build_llm_opts
         opts = {
           messages: @conversation.to_api_format,
-          tools: @plan_mode ? read_only_tool_definitions : tool_definitions,
+          tools: filtered_tool_definitions,
           system: build_system_prompt,
           on_text: @on_text
         }
@@ -36,6 +36,8 @@ module RubynCode
             total: UsageTracker::TASK_BUDGET_TOTAL, remaining: @task_budget_remaining
           }
         end
+        budget = @llm_client.respond_to?(:thinking_budget_tokens) ? @llm_client.thinking_budget_tokens.to_i : 0
+        opts[:thinking] = { budget_tokens: budget } if budget.positive?
         opts
       end
 
@@ -45,6 +47,8 @@ module RubynCode
       # Falls back to nil (use client's default) if routing fails.
       # -- guard clauses for provider/mode checks
       def routed_model
+        return @model_override if @model_override
+
         return nil if manual_model_mode?
 
         last_user = last_user_message_text

data/lib/rubyn_code/agent/loop.rb

@@ -53,8 +53,11 @@ module RubynCode
       # response is produced or the iteration limit is reached.
       #
       # @param user_input [String]
+      # @param blocks [Array<Hash>, nil] extra content blocks to attach to the
+      #   user message (e.g. image blocks from @-mentions). When non-empty the
+      #   user message is stored as a mixed content array instead of a string.
       # @return [String] the final assistant text response
-      def send_message(user_input)
+      def send_message(user_input, blocks: nil)
         initialize_session!
         check_user_feedback(user_input)
         drain_background_notifications
@@ -62,7 +65,7 @@ module RubynCode
         @decision_compactor&.detect_topic_switch(user_input)
         @skill_ttl&.tick!
         autoload_triggered_skills(user_input)
-        @conversation.add_user_message(user_input)
+        append_user_message(user_input, blocks)
         reset_system_prompt_cache!
         reset_iteration_state
 
@@ -79,8 +82,38 @@ module RubynCode
         max_iterations_warning(iteration)
       end
 
+      # Append the user turn to the conversation. If image blocks were passed
+      # via `blocks:`, the message is stored as a mixed content array with a
+      # leading text block and the image blocks appended in order.
+      def append_user_message(user_input, blocks)
+        if blocks.is_a?(Array) && !blocks.empty?
+          content = [{ type: 'text', text: user_input.to_s }, *blocks]
+          @conversation.add_user_message(content)
+        else
+          @conversation.add_user_message(user_input)
+        end
+      end
+
+      # @return [Tools::TodoStore] shared checklist store, exposed for the REPL renderer
+      attr_reader :todo_store
+
+      # Apply a one-shot model override for the duration of the next LLM call.
+      # Used by `Context#with_optional_model` for custom-command frontmatter.
+      def model_override=(model_name)
+        stripped = model_name.to_s.strip
+        @model_override = stripped.empty? ? nil : stripped
+      end
+
+      # Restrict the available tool set for the next LLM call only.
+      # @param allowed [Array<String>, nil] tool names, or nil to clear the override.
+      def allowed_tools_override=(allowed)
+        @allowed_tools_override = allowed.is_a?(Array) && !allowed.empty? ? allowed : nil
+      end
+
       private
 
+      # Overrides the region above. The internal helpers below are private.
+
       # Decide whether the loop should run another iteration after `iteration`
       # turns. Normally capped at MAX_ITERATIONS, but while a Stop hook (e.g. an
       # active /goal) is keeping the agent alive we extend up to a hard ceiling
@@ -119,6 +152,8 @@ module RubynCode
         @tool_wrapper       = opts[:tool_wrapper]
         @decision_compactor = build_decision_compactor
         @skill_ttl          = Skills::TtlManager.new
+        @todo_store         = opts.fetch(:todo_store, Tools::TodoStore.new)
+        @tool_executor.todo_store = @todo_store
         @session_initialized = false
       end
 
@@ -133,6 +168,7 @@ module RubynCode
       def initialize_session!
         return if @session_initialized || !@project_root
 
+        @todo_store&.clear
         @session_initialized = true
         build_project_profile!
         build_codebase_index!
@@ -168,13 +204,17 @@ module RubynCode
         @output_recovery_count = 0
         @task_budget_remaining = nil
         @stop_block_active     = false # true while a Stop hook keeps us going
+        @allowed_tools_override = nil   # set by Context#with_allowed_tools
+        @model_override         = nil   # set by Context#with_optional_model
       end
 
       def run_iteration(iteration)
         log_iteration(iteration)
         @context_manager.advance_turn!
         compact_if_needed # ensure context is under threshold before LLM call
-        response   = call_llm
+        response = call_llm
+        return handle_refusal(response) if extract_stop_reason(response) == 'refusal'
+
         tool_calls = extract_tool_calls(response)
         log_response(response, tool_calls)
 
@@ -183,6 +223,20 @@ module RubynCode
         handle_tool_response(response, tool_calls, iteration)
       end
 
+      # Claude's safety classifiers declined the request outright (HTTP 200,
+      # stop_reason: "refusal"). Surface a clear message instead of falling
+      # through to text/empty-response handling, which would misread the
+      # empty or partial content as "waiting on background jobs".
+      def handle_refusal(response)
+        details = extract_stop_details(response)
+        category = details.is_a?(Hash) ? (details['category'] || details[:category]) : nil
+        RubynCode::Debug.llm("Refusal: category=#{category || 'unknown'}")
+
+        message = "Claude's safety system declined this request (category: #{category || 'unknown'})."
+        @conversation.add_assistant_message([{ type: 'text', text: message }])
+        message
+      end
+
       def log_iteration(iteration)
         RubynCode::Debug.loop_tick(
           "iteration=#{iteration} messages=#{@conversation.length} " \

data/lib/rubyn_code/agent/response_parser.rb

@@ -61,6 +61,14 @@ module RubynCode
         end
       end
 
+      def extract_stop_details(response)
+        if response.respond_to?(:stop_details)
+          response.stop_details
+        elsif response.is_a?(Hash)
+          response[:stop_details] || response['stop_details']
+        end
+      end
+
       def recover_truncated_response(response)
         @max_tokens_override ||= Config::Defaults::ESCALATED_MAX_OUTPUT_TOKENS
         @conversation.add_assistant_message(response_content(response))

data/lib/rubyn_code/agent/system_prompt_builder.rb

@@ -101,6 +101,9 @@ module RubynCode
         return unless index&.nodes&.any?
 
         parts << "\n## #{index.to_structural_summary}"
+        parts << 'This project has a code graph. To locate or understand code, call `code_graph` FIRST — ' \
+                 'it returns matching symbols with source, callers, and callees in one call. ' \
+                 'Fall back to grep/glob only when code_graph finds nothing.'
       rescue StandardError
         nil
       end

data/lib/rubyn_code/agent/tool_processor.rb

@@ -52,6 +52,16 @@ module RubynCode
         Tools::Registry.all.select { |t| PLAN_MODE_RISK_LEVELS.include?(t::RISK_LEVEL) }.map(&:to_schema)
       end
 
+      # Tool definitions for the next LLM call: plan mode narrows to
+      # read-only tools; a per-turn allowed-tools override (custom-command
+      # frontmatter, set via Loop#allowed_tools_override=) narrows by name.
+      def filtered_tool_definitions
+        defs = @plan_mode ? read_only_tool_definitions : tool_definitions
+        return defs unless @allowed_tools_override
+
+        DynamicToolSchema.filter(defs, active_names: @allowed_tools_override)
+      end
+
       # -- tool dispatch with budget + signals
       def process_tool_calls(tool_calls)
         aggregate_chars = 0

data/lib/rubyn_code/autonomous/daemon.rb

@@ -212,7 +212,7 @@ module RubynCode
         tokens = extract_token_counts(cm)
         return if tokens.values.all?(&:zero?)
 
-        model = @llm_client.respond_to?(:model) ? @llm_client.model : 'claude-sonnet-4-6'
+        model = @llm_client.respond_to?(:model) ? @llm_client.model : 'claude-sonnet-5'
         @total_cost += Observability::CostCalculator.calculate(model: model, **tokens)
       rescue StandardError
         # Non-critical — cost tracking is best-effort

data/lib/rubyn_code/cli/commands/context.rb

@@ -40,6 +40,33 @@ module RubynCode
 
         # @return [Boolean]
         def plan_mode? = plan_mode
+
+        # Restrict the tool set for a single agent invocation. The next
+        # `send_message` call inside the block sees only the tools in
+        # `allowed`; the override is cleared after the call.
+        def with_allowed_tools(allowed = nil, &block)
+          apply_loop_override(:allowed_tools_override=, allowed, &block)
+        end
+
+        # Apply a one-shot model override for the duration of a block.
+        def with_optional_model(model_name = nil, &block)
+          apply_loop_override(:model_override=, model_name, &block)
+        end
+
+        private
+
+        # Set an override on the agent loop (when one is wired in) for the
+        # duration of the block, then clear it. Custom commands without
+        # a loop (e.g. test doubles) fall through to a plain yield.
+        def apply_loop_override(method, value)
+          loop = agent_loop
+          return yield unless loop.respond_to?(method)
+
+          loop.public_send(method, value)
+          yield
+        ensure
+          loop&.public_send(method, nil) if loop.respond_to?(method)
+        end
       end
     end
   end

data/lib/rubyn_code/cli/commands/custom_command.rb

@@ -14,13 +14,24 @@ module RubynCode
         attr_reader :name
         # @return [String] one-line description for /help
         attr_reader :description
+        # @return [String, nil] argument hint shown next to the name in /help
+        attr_reader :argument_hint
+        # @return [Array<String>, nil] tool names the command restricts to
+        attr_reader :allowed_tools
+        # @return [String, nil] model override for this prompt
+        attr_reader :model
         # @return [String, nil] originating file path
         attr_reader :source
 
-        def initialize(name:, description:, body:, source: nil)
+        def initialize(name:, description:, body:, # rubocop:disable Metrics/ParameterLists -- explicit kwargs document the frontmatter surface
+                       source: nil,
+                       argument_hint: nil, allowed_tools: nil, model: nil)
           @name = name
           @description = description
           @template = CommandTemplate.new(body)
+          @argument_hint = argument_hint
+          @allowed_tools = allowed_tools
+          @model = model
           @source = source
         end
 
@@ -29,11 +40,42 @@ module RubynCode
         def hidden? = false
         def all_names = [command_name].freeze
 
+        # Render the help label, including [hint] when frontmatter provides one.
+        # The argument_hint is expected to be the placeholder text already wrapped
+        # in [ ] (e.g. "[env]") — we don't add another set of brackets.
+        def help_label
+          hint = @argument_hint.to_s.strip
+          hint.empty? ? description : "#{description}  #{hint}"
+        end
+
+        # @return [Boolean] true if the frontmatter restricted the tool set
+        def restricts_tools?
+          !@allowed_tools.nil? && !@allowed_tools.empty?
+        end
+
+        # @return [Boolean] true if the frontmatter overrode the model
+        def overrides_model?
+          !@model.to_s.strip.empty?
+        end
+
         # @param args [Array<String>]
         # @param ctx [Commands::Context]
         # @return [nil]
         def execute(args, ctx)
-          ctx.send_message(@template.render(args))
+          rendered = @template.render(args)
+          if restricts_tools?
+            ctx.with_allowed_tools(@allowed_tools) do
+              ctx.with_optional_model(@model) do
+                ctx.send_message(rendered)
+              end
+            end
+          elsif overrides_model?
+            ctx.with_optional_model(@model) do
+              ctx.send_message(rendered)
+            end
+          else
+            ctx.send_message(rendered)
+          end
           nil
         end
       end

data/lib/rubyn_code/cli/commands/custom_loader.rb

@@ -40,9 +40,18 @@ module RubynCode
             name = File.basename(path, '.md').strip
             return nil unless name.match?(NAME)
 
-            description, body = parse(File.read(path))
-            description = "Custom command: /#{name}" if description.to_s.strip.empty?
-            CustomCommand.new(name: name, description: description, body: body, source: path)
+            meta, body = parse(File.read(path))
+            description = meta['description'].to_s
+            description = "Custom command: /#{name}" if description.strip.empty?
+            CustomCommand.new(
+              name: name,
+              description: description,
+              body: body,
+              source: path,
+              argument_hint: blank_to_nil(stringify(meta['argument_hint'] || meta['argument-hint'])),
+              allowed_tools: list_of_tools(meta['allowed_tools'] || meta['allowed-tools']),
+              model: blank_to_nil(stringify(meta['model']))
+            )
           rescue StandardError => e
             RubynCode::Debug.warn("Failed to load custom command #{path}: #{e.message}")
             nil
@@ -51,13 +60,35 @@ module RubynCode
           def parse(content)
             if (match = FRONTMATTER.match(content))
               frontmatter = YAML.safe_load(match[1]) || {}
-              [frontmatter['description'].to_s, match[2].to_s.strip]
+              [frontmatter, match[2].to_s.strip]
             else
               body = content.to_s.strip
-              [first_line(body), body]
+              [{ 'description' => first_line(body) }, body]
             end
           end
 
+          def blank_to_nil(value)
+            value.to_s.strip.empty? ? nil : value
+          end
+
+          def stringify(value)
+            return '' if value.nil?
+
+            # YAML's flow-style `[env]` is parsed as a single-element array.
+            # Stringify the array element directly so users see exactly the
+            # characters they typed.
+            str = value.is_a?(Array) ? value.join : value
+            str.to_s.strip
+          end
+
+          def list_of_tools(value)
+            return nil if value.nil?
+
+            arr = value.is_a?(Array) ? value : value.to_s.split(',')
+            cleaned = arr.map { |name| name.to_s.strip }.reject(&:empty?)
+            cleaned.empty? ? nil : cleaned
+          end
+
           def first_line(body)
             line = body.lines.first.to_s.strip
             line.sub(/\A#+\s*/, '')[0, 80]

data/lib/rubyn_code/cli/commands/effort.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # Set or clear the reasoning effort level (output_config.effort).
+      #
+      #   /effort             # show current value
+      #   /effort off         # clear back to model default
+      #   /effort <level>     # low | medium | high | xhigh | max
+      class Effort < Base
+        LEVELS = %w[low medium high xhigh max].freeze
+
+        def self.command_name = '/effort'
+        def self.description = 'Set reasoning effort (low/medium/high/xhigh/max)'
+
+        def execute(args, ctx)
+          arg = args.first
+
+          current = ctx.llm_client.respond_to?(:effort) ? ctx.llm_client.effort : nil
+
+          case arg
+          when nil
+            show_status(current, ctx)
+          when 'off'
+            ctx.llm_client.effort = nil
+            ctx.renderer.info('Reasoning effort cleared — using model default 🎚️')
+          when *LEVELS
+            ctx.llm_client.effort = arg
+            ctx.renderer.info("Reasoning effort set to #{arg} 🎚️")
+          else
+            ctx.renderer.warning("Usage: /effort [off|#{LEVELS.join('|')}]. Got: #{arg}")
+          end
+        end
+
+        private
+
+        def show_status(current, ctx)
+          state = current || 'not set (model default: high on 4.6+)'
+          ctx.renderer.info("Reasoning effort: #{state}")
+          ctx.renderer.info("Usage: /effort <level>  levels: #{LEVELS.join(', ')}   (or /effort off)")
+          ctx.renderer.info('Supported on Claude 4.6+ models; xhigh requires Opus 4.7+ / Sonnet 5 / Fable 5.')
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/export.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module RubynCode
+  module CLI
+    module Commands
+      # Export the current conversation transcript to a file.
+      #
+      #   /export path/to/transcript.md              # markdown (default)
+      #   /export --format jsonl path/to/transcript.jsonl
+      #   /export path/to/transcript.md --force      # overwrite existing
+      class Export < Base
+        def self.command_name = '/export'
+        def self.description = 'Export conversation transcript to markdown or JSONL'
+
+        MAX_LINE_LENGTH = 100
+
+        # -- CLI arg parsing is intrinsically procedural
+        def execute(args, ctx)
+          opts = parse_args(args)
+          return unless opts
+
+          messages = ctx.conversation.to_a
+          if messages.empty?
+            ctx.renderer.warning('No messages to export.')
+            return
+          end
+
+          path = File.expand_path(opts[:path])
+          dir  = File.dirname(path)
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+          if File.exist?(path) && !opts[:force] && !tty_yes?(ctx, "File exists at #{path}. Overwrite? [y/N]")
+            ctx.renderer.info('Export cancelled.')
+            return
+          end
+
+          body = opts[:format] == 'jsonl' ? render_jsonl(messages) : render_markdown(messages)
+          File.write(path, body)
+          plural = messages.size == 1 ? '' : 's'
+          ctx.renderer.info("Exported #{messages.size} message#{plural} to #{path}")
+        end
+
+        private
+
+        # @return [Hash{Symbol=>Object}, nil] nil on bad input
+        # -- arg parsing is intrinsically branchy
+        def parse_args(args) # rubocop:disable Metrics/MethodLength -- arg parsing is intrinsically procedural
+          format = 'markdown'
+          force  = false
+          path   = nil
+
+          if (idx = args.index('--format') || args.index('-f'))
+            format = args[idx + 1].to_s
+          end
+          format = case format
+                   when 'md' then 'markdown'
+                   else format
+                   end
+
+          args.each do |a|
+            case a
+            when '--jsonl'
+              format = 'jsonl'
+            when '--markdown', '--md'
+              format = 'markdown'
+            when '--format', '-f'
+              # already handled above
+            when '--force', '-y'
+              force = true
+            when /\A--.+/
+              next
+            else
+              path ||= a
+            end
+          end
+
+          return nil if path.to_s.empty?
+
+          { path: path, format: format, force: force }
+        end
+
+        def render_markdown(messages)
+          title  = 'Rubyn transcript'
+          buffer = String.new
+          buffer << "# #{title}\n\n"
+          buffer << "_Exported at #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}_\n\n"
+          messages.each { |msg| render_markdown_message(buffer, msg) }
+          buffer
+        end
+
+        def render_markdown_message(buffer, msg)
+          role = msg[:role] || msg['role']
+          case role
+          when 'user'
+            text = render_user_text(msg[:content] || msg['content'])
+            buffer << "## User\n\n#{text}\n\n"
+          when 'assistant'
+            render_assistant_blocks(buffer, msg[:content] || msg['content'])
+          when 'tool'
+            buffer << "### tool result\n\n```\n#{msg[:content] || msg['content']}\n```\n\n"
+          end
+        end
+
+        def render_user_text(content)
+          blocks = normalize_content(content)
+          if blocks.any? { |b| block_type(b) == 'image' }
+            blocks.map { |b| block_type(b) == 'image' ? '_(image attachment)_' : text_of(b) }.join("\n")
+          else
+            blocks.map { |b| text_of(b) }.join("\n")
+          end
+        end
+
+        def render_assistant_blocks(buffer, content)
+          blocks = normalize_content(content)
+          if blocks.empty?
+            buffer << "## Assistant\n\n_(empty response)_\n\n"
+            return
+          end
+          blocks.each do |b|
+            render_assistant_block(buffer, b)
+          end
+        end
+
+        def render_assistant_block(buffer, b) # rubocop:disable Naming/MethodParameterName -- short names are clearer here than "block"
+          case block_type(b)
+          when 'text'
+            buffer << "## Assistant\n\n#{text_of(b)}\n\n"
+          when 'thinking'
+            buffer << "<details><summary>thinking</summary>\n\n#{text_of(b)}\n\n</details>\n\n"
+          when 'tool_use'
+            buffer << "[tool: #{b[:name] || b['name']}]\n\n```json\n#{JSON.pretty_generate(input_of(b))}\n```\n\n"
+          end
+        end
+
+        def render_jsonl(messages)
+          lines = messages.map do |msg|
+            role    = msg[:role] || msg['role']
+            raw     = msg[:content] || msg['content']
+            content = raw.is_a?(String) ? raw : normalize_content(raw)
+            "#{JSON.generate(role: role, content: content, timestamp: Time.now.utc.iso8601)}\n"
+          end
+          lines.join
+        end
+
+        # Wrap a String content into a single text block so we can render uniformly.
+        def normalize_content(content)
+          return [{ type: 'text', text: content.to_s }] if content.is_a?(String)
+          return [{ type: 'text', text: '' }] if content.nil?
+
+          content
+        end
+
+        def block_type(block)
+          block[:type] || block['type']
+        end
+
+        def text_of(block)
+          (block[:text] || block['text']).to_s
+        end
+
+        def input_of(block)
+          (block[:input] || block['input']) || {}
+        end
+
+        def tty_yes?(ctx, prompt)
+          ctx.renderer.respond_to?(:ask) ? ctx.renderer.ask(prompt, default: false) : true
+        end
+      end
+    end
+  end
+end