From 8f49109520ba531c9dc5fa95a0c7cd5d2f6fc93f Mon Sep 17 00:00:00 2001
From: Lasmar Khalifa <lasmar.khalifa@shopify.com>
Date: Fri, 5 Jun 2026 14:52:06 -0400
Subject: [PATCH] add read tool use formatter

---
 .../cogs/agent/providers/claude/tool_use.rb   | 31 +++++++++++++++++
 .../agent/providers/claude/tool_use_test.rb   | 34 +++++++++++++++++++
 2 files changed, 65 insertions(+)

diff --git a/lib/roast/cogs/agent/providers/claude/tool_use.rb b/lib/roast/cogs/agent/providers/claude/tool_use.rb
index 9d312087..ed6fad87 100644
--- a/lib/roast/cogs/agent/providers/claude/tool_use.rb
+++ b/lib/roast/cogs/agent/providers/claude/tool_use.rb
@@ -60,6 +60,37 @@ def format_bash
               description ? "BASH #{command} (#{description})" : "BASH #{command}"
             end
 
+            # Formats a Read tool-use line.
+            #
+            # Input fields:
+            #   :file_path (String)  – absolute path to read         [required]
+            #   :offset    (Integer) – 1-based first line            [optional]
+            #   :limit     (Integer) – max number of lines to read   [optional]
+            #
+            # Output: "READ <file_path>", with a line range appended when :offset
+            # and/or :limit is given:
+            #   :limit set    → " (lines <start>–<end>)", start = :offset (default
+            #                   1), end = start + :limit - 1
+            #   :offset only  → " (from line <offset>)" (reads to end of file)
+            # With neither, the bare "READ <file_path>".
+            #
+            # Examples:
+            #   READ /app/models/user.rb (lines 30–80)
+            #   READ /app/models/user.rb (from line 30)
+            #   READ /app/models/user.rb
+            #
+            #: () -> String
+            def format_read
+              file_path, offset, limit = input.values_at(:file_path, :offset, :limit)
+              details = if limit
+                offset ||= 1
+                "lines #{offset}–#{offset + limit - 1}"
+              elsif offset
+                "from line #{offset}"
+              end
+              details ? "READ #{file_path} (#{details})" : "READ #{file_path}"
+            end
+
             #: () -> String
             def format_unknown
               "UNKNOWN [#{name}] #{input.inspect}"
diff --git a/test/roast/cogs/agent/providers/claude/tool_use_test.rb b/test/roast/cogs/agent/providers/claude/tool_use_test.rb
index 091027f1..6beff4aa 100644
--- a/test/roast/cogs/agent/providers/claude/tool_use_test.rb
+++ b/test/roast/cogs/agent/providers/claude/tool_use_test.rb
@@ -69,6 +69,40 @@ class ToolUseTest < ActiveSupport::TestCase
               assert_equal "BASH #{truncated} (#{long})", output
             end
 
+            # format_read
+
+            test "format_read shows a closed range when offset and limit are set" do
+              tool_use = ToolUse.new(name: :read, input: { file_path: "/a.rb", offset: 30, limit: 51 })
+
+              output = tool_use.format
+
+              assert_equal "READ /a.rb (lines 30–80)", output
+            end
+
+            test "format_read defaults offset to 1 when only limit is given" do
+              tool_use = ToolUse.new(name: :read, input: { file_path: "/a.rb", limit: 50 })
+
+              output = tool_use.format
+
+              assert_equal "READ /a.rb (lines 1–50)", output
+            end
+
+            test "format_read shows an open-ended range from offset when limit is absent" do
+              tool_use = ToolUse.new(name: :read, input: { file_path: "/a.rb", offset: 30 })
+
+              output = tool_use.format
+
+              assert_equal "READ /a.rb (from line 30)", output
+            end
+
+            test "format_read renders a bare line with only a file path" do
+              tool_use = ToolUse.new(name: :read, input: { file_path: "/a.rb" })
+
+              output = tool_use.format
+
+              assert_equal "READ /a.rb", output
+            end
+
             test "format calls format_unknown for unknown tool" do
               tool_use = ToolUse.new(name: :unknown_tool, input: { arg: "value" })