wcgw 3.0.7__py3-none-any.whl → 4.1.0__py3-none-any.whl

wcgw/client/tools.py

@@ -7,6 +7,7 @@ import os
 import subprocess
 import traceback
 from dataclasses import dataclass
+from hashlib import sha256
 from os.path import expanduser
 from pathlib import Path
 from tempfile import NamedTemporaryFile
@@ -28,6 +29,11 @@ from pydantic import BaseModel, TypeAdapter, ValidationError
 from syntax_checker import check_syntax
 
 from wcgw.client.bash_state.bash_state import get_status
+from wcgw.client.repo_ops.file_stats import (
+    FileStats,
+    load_workspace_stats,
+    save_workspace_stats,
+)
 
 from ..types_ import (
     BashCommand,
@@ -36,6 +42,7 @@ from ..types_ import (
     Console,
     ContextSave,
     FileEdit,
+    FileWriteOrEdit,
     Initialize,
     Modes,
     ModesConfig,
@@ -48,7 +55,12 @@ from .bash_state.bash_state import (
     execute_bash,
 )
 from .encoder import EncoderDecoder, get_default_encoder
-from .file_ops.search_replace import search_replace_edit
+from .file_ops.search_replace import (
+    DIVIDER_MARKER,
+    REPLACE_MARKER,
+    SEARCH_MARKER,
+    search_replace_edit,
+)
 from .memory import load_memory, save_memory
 from .modes import (
     ARCHITECT_PROMPT,
@@ -92,7 +104,7 @@ def initialize(
     task_id_to_resume: str,
     max_tokens: Optional[int],
     mode: ModesConfig,
-) -> tuple[str, Context]:
+) -> tuple[str, Context, dict[str, list[tuple[int, int]]]]:
     # Expand the workspace path
     any_workspace_path = expand_user(any_workspace_path)
     repo_context = ""
@@ -129,7 +141,8 @@ def initialize(
                 if not read_files_:
                     read_files_ = [any_workspace_path]
                 any_workspace_path = os.path.dirname(any_workspace_path)
-            repo_context, folder_to_start = get_repo_context(any_workspace_path, 50)
+            # Let get_repo_context handle loading the workspace stats
+            repo_context, folder_to_start = get_repo_context(any_workspace_path)
 
             repo_context = f"---\n# Workspace structure\n{repo_context}\n---\n"
 
@@ -151,14 +164,18 @@ def initialize(
     if loaded_state is not None:
         try:
             parsed_state = BashState.parse_state(loaded_state)
+            workspace_root = (
+                str(folder_to_start) if folder_to_start else parsed_state[5]
+            )
             if mode == "wcgw":
                 context.bash_state.load_state(
                     parsed_state[0],
                     parsed_state[1],
                     parsed_state[2],
                     parsed_state[3],
-                    parsed_state[4] + list(context.bash_state.whitelist_for_overwrite),
-                    str(folder_to_start) if folder_to_start else "",
+                    {**parsed_state[4], **context.bash_state.whitelist_for_overwrite},
+                    str(folder_to_start) if folder_to_start else workspace_root,
+                    workspace_root,
                 )
             else:
                 state = modes_to_state(mode)
@@ -167,8 +184,9 @@ def initialize(
                     state[1],
                     state[2],
                     state[3],
-                    parsed_state[4] + list(context.bash_state.whitelist_for_overwrite),
-                    str(folder_to_start) if folder_to_start else "",
+                    {**parsed_state[4], **context.bash_state.whitelist_for_overwrite},
+                    str(folder_to_start) if folder_to_start else workspace_root,
+                    workspace_root,
                 )
         except ValueError:
             context.console.print(traceback.format_exc())
@@ -178,12 +196,14 @@ def initialize(
     else:
         mode_changed = is_mode_change(mode, context.bash_state)
         state = modes_to_state(mode)
+        # Use the provided workspace path as the workspace root
         context.bash_state.load_state(
             state[0],
             state[1],
             state[2],
             state[3],
-            list(context.bash_state.whitelist_for_overwrite),
+            dict(context.bash_state.whitelist_for_overwrite),
+            str(folder_to_start) if folder_to_start else "",
             str(folder_to_start) if folder_to_start else "",
         )
         if type == "first_call" or mode_changed:
@@ -194,6 +214,7 @@ def initialize(
     del mode
 
     initial_files_context = ""
+    initial_paths_with_ranges: dict[str, list[tuple[int, int]]] = {}
     if read_files_:
         if folder_to_start:
             read_files_ = [
@@ -203,9 +224,25 @@ def initialize(
                 else expand_user(f)
                 for f in read_files_
             ]
-        initial_files = read_files(read_files_, max_tokens, context)
+        initial_files, initial_paths_with_ranges, _ = read_files(
+            read_files_, max_tokens, context
+        )
         initial_files_context = f"---\n# Requested files\n{initial_files}\n---\n"
 
+    # Check for CLAUDE.md in the workspace folder on first call
+    alignment_context = ""
+    if folder_to_start:
+        alignment_file_path = os.path.join(folder_to_start, "CLAUDE.md")
+        if os.path.exists(alignment_file_path):
+            try:
+                # Read the CLAUDE.md file content
+                with open(alignment_file_path, "r") as f:
+                    alignment_content = f.read()
+                alignment_context = f"---\n# CLAUDE.md - Project alignment guidelines\n```\n{alignment_content}\n```\n---\n\n"
+            except Exception:
+                # Handle any errors when reading the file
+                alignment_context = ""
+
     uname_sysname = os.uname().sysname
     uname_machine = os.uname().machine
 
@@ -216,9 +253,11 @@ def initialize(
 System: {uname_sysname}
 Machine: {uname_machine}
 Initialized in directory (also cwd): {context.bash_state.cwd}
+User home directory: {expanduser("~")}
 
 {repo_context}
 
+{alignment_context}
 {initial_files_context}
 
 ---
@@ -228,7 +267,7 @@ Initialized in directory (also cwd): {context.bash_state.cwd}
 
     global INITIALIZED
     INITIALIZED = True
-    return output, context
+    return output, context, initial_paths_with_ranges
 
 
 def is_mode_change(mode_config: ModesConfig, bash_state: BashState) -> bool:
@@ -267,7 +306,8 @@ def reset_wcgw(
             file_edit_mode,
             write_if_empty_mode,
             mode,
-            list(context.bash_state.whitelist_for_overwrite),
+            dict(context.bash_state.whitelist_for_overwrite),
+            starting_directory,
             starting_directory,
         )
         mode_prompt = get_mode_prompt(context)
@@ -291,7 +331,8 @@ def reset_wcgw(
             file_edit_mode,
             write_if_empty_mode,
             mode,
-            list(context.bash_state.whitelist_for_overwrite),
+            dict(context.bash_state.whitelist_for_overwrite),
+            starting_directory,
             starting_directory,
         )
     INITIALIZED = True
@@ -405,39 +446,138 @@ def write_file(
     error_on_exist: bool,
     max_tokens: Optional[int],
     context: Context,
-) -> str:
+) -> tuple[
+    str, dict[str, list[tuple[int, int]]]
+]:  # Updated to return message and file paths with line ranges
     # Expand the path before checking if it's absolute
     path_ = expand_user(writefile.file_path)
+
+    workspace_path = context.bash_state.workspace_root
+    stats = load_workspace_stats(workspace_path)
+
+    if path_ not in stats.files:
+        stats.files[path_] = FileStats()
+
+    stats.files[path_].increment_write()
+    save_workspace_stats(workspace_path, stats)
+
     if not os.path.isabs(path_):
-        return f"Failure: file_path should be absolute path, current working directory is {context.bash_state.cwd}"
+        return (
+            f"Failure: file_path should be absolute path, current working directory is {context.bash_state.cwd}",
+            {},  # Return empty dict instead of empty list for type consistency
+        )
 
     error_on_exist_ = (
         error_on_exist and path_ not in context.bash_state.whitelist_for_overwrite
     )
 
+    if error_on_exist and path_ in context.bash_state.whitelist_for_overwrite:
+        # Ensure hash has not changed
+        if os.path.exists(path_):
+            with open(path_, "rb") as f:
+                file_content = f.read()
+                curr_hash = sha256(file_content).hexdigest()
+
+                whitelist_data = context.bash_state.whitelist_for_overwrite[path_]
+
+                # If we haven't fully read the file or hash has changed, require re-reading
+                if curr_hash != whitelist_data.file_hash:
+                    error_on_exist_ = True
+                elif not whitelist_data.is_read_enough():
+                    error_on_exist_ = True
+
     # Validate using write_if_empty_mode after checking whitelist
     allowed_globs = context.bash_state.write_if_empty_mode.allowed_globs
     if allowed_globs != "all" and not any(
         fnmatch.fnmatch(path_, pattern) for pattern in allowed_globs
     ):
-        return f"Error: updating file {path_} not allowed in current mode. Doesn't match allowed globs: {allowed_globs}"
+        return (
+            f"Error: updating file {path_} not allowed in current mode. Doesn't match allowed globs: {allowed_globs}",
+            {},  # Empty dict instead of empty list
+        )
 
-    add_overwrite_warning = ""
     if (error_on_exist or error_on_exist_) and os.path.exists(path_):
         content = Path(path_).read_text().strip()
         if content:
-            content = truncate_if_over(content, max_tokens)
-
             if error_on_exist_:
-                return (
-                    f"Error: can't write to existing file {path_}, use other functions to edit the file"
-                    + f"\nHere's the existing content:\n```\n{content}\n```"
-                )
-            else:
-                add_overwrite_warning = content
-
-    # Since we've already errored once, add this to whitelist
-    context.bash_state.add_to_whitelist_for_overwrite(path_)
+                file_ranges = []
+
+                if path_ not in context.bash_state.whitelist_for_overwrite:
+                    # File hasn't been read at all
+                    msg = f"Error: you need to read existing file {path_} at least once before it can be overwritten.\n\n"
+                    # Read the entire file
+                    file_content_str, truncated, _, _, line_range = read_file(
+                        path_, max_tokens, context, False
+                    )
+                    file_ranges = [line_range]
+
+                    final_message = ""
+                    if not truncated:
+                        final_message = "You can now safely retry writing immediately considering the above information."
+
+                    return (
+                        (
+                            msg
+                            + f"Here's the existing file:\n```\n{file_content_str}\n{final_message}\n```"
+                        ),
+                        {path_: file_ranges},
+                    )
+
+                whitelist_data = context.bash_state.whitelist_for_overwrite[path_]
+
+                if curr_hash != whitelist_data.file_hash:
+                    msg = "Error: the file has changed since last read.\n\n"
+                    # Read the entire file again
+                    file_content_str, truncated, _, _, line_range = read_file(
+                        path_, max_tokens, context, False
+                    )
+                    file_ranges = [line_range]
+
+                    final_message = ""
+                    if not truncated:
+                        final_message = "You can now safely retry writing immediately considering the above information."
+
+                    return (
+                        (
+                            msg
+                            + f"Here's the existing file:\n```\n{file_content_str}\n```\n{final_message}"
+                        ),
+                        {path_: file_ranges},
+                    )
+                else:
+                    # The file hasn't changed, but we haven't read enough of it
+                    unread_ranges = whitelist_data.get_unread_ranges()
+                    # Format the ranges as a string for display
+                    ranges_str = ", ".join(
+                        [f"{start}-{end}" for start, end in unread_ranges]
+                    )
+                    msg = f"Error: you need to read more of the file before it can be overwritten.\nUnread line ranges: {ranges_str}\n\n"
+
+                    # Read just the unread ranges
+                    paths_: list[str] = []
+                    for start, end in unread_ranges:
+                        paths_.append(path_ + ":" + f"{start}-{end}")
+                    paths_readfiles = ReadFiles(
+                        file_paths=paths_, show_line_numbers_reason=""
+                    )
+                    readfiles, file_ranges_dict, truncated = read_files(
+                        paths_readfiles.file_paths,
+                        max_tokens,
+                        context,
+                        show_line_numbers=False,
+                        start_line_nums=paths_readfiles.start_line_nums,
+                        end_line_nums=paths_readfiles.end_line_nums,
+                    )
+
+                    final_message = ""
+                    if not truncated:
+                        final_message = "Now that you have read the rest of the file, you can now safely immediately retry writing but consider the new information above."
+
+                    return (
+                        (msg + "\n" + readfiles + "\n" + final_message),
+                        file_ranges_dict,
+                    )
+    # No need to add to whitelist here - will be handled by get_tool_output
 
     path = Path(path_)
     path.parent.mkdir(parents=True, exist_ok=True)
@@ -446,7 +586,7 @@ def write_file(
         with path.open("w") as f:
             f.write(writefile.file_content)
     except OSError as e:
-        return f"Error: {e}"
+        return f"Error: {e}", {}
 
     extension = Path(path_).suffix.lstrip(".")
 
@@ -478,19 +618,17 @@ Syntax errors:
     except Exception:
         pass
 
-    if add_overwrite_warning:
-        warnings.append(
-            "\n---\nWarning: a file already existed and it's now overwritten. Was it a mistake? If yes please revert your action."
-            "\n---\n"
-            + "Here's the previous content:\n```\n"
-            + add_overwrite_warning
-            + "\n```"
-        )
+    # Count the lines directly from the content we're writing
+    total_lines = writefile.file_content.count("\n") + 1
 
-    return "Success" + "".join(warnings)
+    return "Success" + "".join(warnings), {
+        path_: [(1, total_lines)]
+    }  # Return the file path with line range along with success message
 
 
-def do_diff_edit(fedit: FileEdit, max_tokens: Optional[int], context: Context) -> str:
+def do_diff_edit(
+    fedit: FileEdit, max_tokens: Optional[int], context: Context
+) -> tuple[str, dict[str, list[tuple[int, int]]]]:
     try:
         return _do_diff_edit(fedit, max_tokens, context)
     except Exception as e:
@@ -508,16 +646,28 @@ def do_diff_edit(fedit: FileEdit, max_tokens: Optional[int], context: Context) -
         raise e
 
 
-def _do_diff_edit(fedit: FileEdit, max_tokens: Optional[int], context: Context) -> str:
+def _do_diff_edit(
+    fedit: FileEdit, max_tokens: Optional[int], context: Context
+) -> tuple[str, dict[str, list[tuple[int, int]]]]:
     context.console.log(f"Editing file: {fedit.file_path}")
 
     # Expand the path before checking if it's absolute
     path_ = expand_user(fedit.file_path)
+
     if not os.path.isabs(path_):
         raise Exception(
             f"Failure: file_path should be absolute path, current working directory is {context.bash_state.cwd}"
         )
 
+    workspace_path = context.bash_state.workspace_root
+    stats = load_workspace_stats(workspace_path)
+
+    if path_ not in stats.files:
+        stats.files[path_] = FileStats()
+
+    stats.files[path_].increment_edit()
+    save_workspace_stats(workspace_path, stats)
+
     # Validate using file_edit_mode
     allowed_globs = context.bash_state.file_edit_mode.allowed_globs
     if allowed_globs != "all" and not any(
@@ -527,8 +677,7 @@ def _do_diff_edit(fedit: FileEdit, max_tokens: Optional[int], context: Context)
             f"Error: updating file {path_} not allowed in current mode. Doesn't match allowed globs: {allowed_globs}"
         )
 
-    # The LLM is now aware that the file exists
-    context.bash_state.add_to_whitelist_for_overwrite(path_)
+    # No need to add to whitelist here - will be handled by get_tool_output
 
     if not os.path.exists(path_):
         raise Exception(f"Error: file {path_} does not exist")
@@ -545,6 +694,9 @@ def _do_diff_edit(fedit: FileEdit, max_tokens: Optional[int], context: Context)
         lines, apply_diff_to, context.console.log
     )
 
+    # Count the lines just once - after the edit but before writing
+    total_lines = apply_diff_to.count("\n") + 1
+
     with open(path_, "w") as f:
         f.write(apply_diff_to)
 
@@ -561,29 +713,93 @@ def _do_diff_edit(fedit: FileEdit, max_tokens: Optional[int], context: Context)
                 syntax_errors += "\nNote: Ignore if 'tagged template literals' are used, they may raise false positive errors in tree-sitter."
 
             context.console.print(f"W: Syntax errors encountered: {syntax_errors}")
-            return f"""{comments}
+
+            return (
+                f"""{comments}
 ---
 Warning: tree-sitter reported syntax errors, please re-read the file and fix if there are any errors.
 Syntax errors:
 {syntax_errors}
 
 {context_for_errors}
-"""
+""",
+                {path_: [(1, total_lines)]},
+            )  # Return the file path with line range along with the warning message
     except Exception:
         pass
 
-    return comments
+    return comments, {
+        path_: [(1, total_lines)]
+    }  # Return the file path with line range along with the edit comments
+
+
+def _is_edit(content: str, percentage: int) -> bool:
+    lines = content.lstrip().split("\n")
+    if not lines:
+        return False
+    line = lines[0]
+    if SEARCH_MARKER.match(line):
+        return True
+    if percentage <= 50:
+        for line in lines:
+            if (
+                SEARCH_MARKER.match(line)
+                or DIVIDER_MARKER.match(line)
+                or REPLACE_MARKER.match(line)
+            ):
+                return True
+    return False
+
+
+def file_writing(
+    file_writing_args: FileWriteOrEdit,
+    max_tokens: Optional[int],
+    context: Context,
+) -> tuple[
+    str, dict[str, list[tuple[int, int]]]
+]:  # Updated to return message and file paths with line ranges
+    """
+    Write or edit a file based on percentage of changes.
+    If percentage_changed > 50%, treat content as direct file content.
+    Otherwise, treat content as search/replace blocks.
+    """
+    # Expand the path before checking if it's absolute
+    path_ = expand_user(file_writing_args.file_path)
+    if not os.path.isabs(path_):
+        return (
+            f"Failure: file_path should be absolute path, current working directory is {context.bash_state.cwd}",
+            {},  # Return empty dict instead of empty list for type consistency
+        )
+
+    # If file doesn't exist, always use direct file_content mode
+    content = file_writing_args.file_content_or_search_replace_blocks
+
+    if not _is_edit(content, file_writing_args.percentage_to_change):
+        # Use direct content mode (same as WriteIfEmpty)
+        result, paths = write_file(
+            WriteIfEmpty(
+                file_path=path_,
+                file_content=file_writing_args.file_content_or_search_replace_blocks,
+            ),
+            True,
+            max_tokens,
+            context,
+        )
+        return result, paths
+    else:
+        # File exists and percentage <= 50, use search/replace mode
+        result, paths = do_diff_edit(
+            FileEdit(
+                file_path=path_,
+                file_edit_using_search_replace_blocks=file_writing_args.file_content_or_search_replace_blocks,
+            ),
+            max_tokens,
+            context,
+        )
+        return result, paths
 
 
-TOOLS = (
-    BashCommand
-    | WriteIfEmpty
-    | FileEdit
-    | ReadImage
-    | ReadFiles
-    | Initialize
-    | ContextSave
-)
+TOOLS = BashCommand | FileWriteOrEdit | ReadImage | ReadFiles | Initialize | ContextSave
 
 
 def which_tool(args: str) -> TOOLS:
@@ -594,10 +810,8 @@ def which_tool(args: str) -> TOOLS:
 def which_tool_name(name: str) -> Type[TOOLS]:
     if name == "BashCommand":
         return BashCommand
-    elif name == "WriteIfEmpty":
-        return WriteIfEmpty
-    elif name == "FileEdit":
-        return FileEdit
+    elif name == "FileWriteOrEdit":
+        return FileWriteOrEdit
     elif name == "ReadImage":
         return ReadImage
     elif name == "ReadFiles":
@@ -647,32 +861,80 @@ def get_tool_output(
     output: tuple[str | ImageData, float]
     TOOL_CALLS.append(arg)
 
+    # Initialize a dictionary to track file paths and line ranges
+    file_paths_with_ranges: dict[str, list[tuple[int, int]]] = {}
+
     if isinstance(arg, BashCommand):
         context.console.print("Calling execute bash tool")
         if not INITIALIZED:
             raise Exception("Initialize tool not called yet.")
 
-        output = execute_bash(
+        output_str, cost = execute_bash(
             context.bash_state, enc, arg, max_tokens, arg.wait_for_seconds
         )
+        output = output_str, cost
     elif isinstance(arg, WriteIfEmpty):
         context.console.print("Calling write file tool")
         if not INITIALIZED:
             raise Exception("Initialize tool not called yet.")
 
-        output = write_file(arg, True, max_tokens, context), 0
+        result, write_paths = write_file(arg, True, max_tokens, context)
+        output = result, 0
+        # Add write paths with their ranges to our tracking dictionary
+        for path, ranges in write_paths.items():
+            if path in file_paths_with_ranges:
+                file_paths_with_ranges[path].extend(ranges)
+            else:
+                file_paths_with_ranges[path] = ranges.copy()
     elif isinstance(arg, FileEdit):
         context.console.print("Calling full file edit tool")
         if not INITIALIZED:
             raise Exception("Initialize tool not called yet.")
 
-        output = do_diff_edit(arg, max_tokens, context), 0.0
+        result, edit_paths = do_diff_edit(arg, max_tokens, context)
+        output = result, 0.0
+        # Add edit paths with their ranges to our tracking dictionary
+        for path, ranges in edit_paths.items():
+            if path in file_paths_with_ranges:
+                file_paths_with_ranges[path].extend(ranges)
+            else:
+                file_paths_with_ranges[path] = ranges.copy()
+    elif isinstance(arg, FileWriteOrEdit):
+        context.console.print("Calling file writing tool")
+        if not INITIALIZED:
+            raise Exception("Initialize tool not called yet.")
+
+        result, write_edit_paths = file_writing(arg, max_tokens, context)
+        output = result, 0.0
+        # Add write/edit paths with their ranges to our tracking dictionary
+        for path, ranges in write_edit_paths.items():
+            if path in file_paths_with_ranges:
+                file_paths_with_ranges[path].extend(ranges)
+            else:
+                file_paths_with_ranges[path] = ranges.copy()
     elif isinstance(arg, ReadImage):
         context.console.print("Calling read image tool")
-        output = read_image_from_shell(arg.file_path, context), 0.0
+        image_data = read_image_from_shell(arg.file_path, context)
+        output = image_data, 0.0
     elif isinstance(arg, ReadFiles):
         context.console.print("Calling read file tool")
-        output = read_files(arg.file_paths, max_tokens, context), 0.0
+        # Access line numbers through properties
+        result, file_ranges_dict, _ = read_files(
+            arg.file_paths,
+            max_tokens,
+            context,
+            bool(arg.show_line_numbers_reason),
+            arg.start_line_nums,
+            arg.end_line_nums,
+        )
+        output = result, 0.0
+
+        # Merge the new file ranges into our tracking dictionary
+        for path, ranges in file_ranges_dict.items():
+            if path in file_paths_with_ranges:
+                file_paths_with_ranges[path].extend(ranges)
+            else:
+                file_paths_with_ranges[path] = ranges
     elif isinstance(arg, Initialize):
         context.console.print("Calling initial info tool")
         if arg.type == "user_asked_mode_change" or arg.type == "reset_shell":
@@ -694,7 +956,7 @@ def get_tool_output(
                 0.0,
             )
         else:
-            output_, context = initialize(
+            output_, context, init_paths = initialize(
                 arg.type,
                 context,
                 arg.any_workspace_path,
@@ -704,6 +966,13 @@ def get_tool_output(
                 arg.mode,
             )
             output = output_, 0.0
+            # Since init_paths is already a dictionary mapping file paths to line ranges,
+            # we just need to merge it with our tracking dictionary
+            for path, ranges in init_paths.items():
+                if path not in file_paths_with_ranges and os.path.exists(path):
+                    file_paths_with_ranges[path] = ranges
+                elif path in file_paths_with_ranges:
+                    file_paths_with_ranges[path].extend(ranges)
 
     elif isinstance(arg, ContextSave):
         context.console.print("Calling task memory tool")
@@ -721,7 +990,7 @@ def get_tool_output(
             relevant_files.extend(globs[:1000])
             if not globs:
                 warnings += f"Warning: No files found for the glob: {fglob}\n"
-        relevant_files_data = read_files(relevant_files[:10_000], None, context)
+        relevant_files_data, _, _ = read_files(relevant_files[:10_000], None, context)
         save_path = save_memory(
             arg, relevant_files_data, context.bash_state.serialize()
         )
@@ -736,6 +1005,10 @@ def get_tool_output(
         output = output_, 0.0
     else:
         raise ValueError(f"Unknown tool: {arg}")
+
+    if file_paths_with_ranges:  # Only add to whitelist if we have paths
+        context.bash_state.add_to_whitelist_for_overwrite(file_paths_with_ranges)
+
     if isinstance(output[0], str):
         context.console.print(str(output[0]))
     else:
@@ -749,13 +1022,64 @@ default_enc = get_default_encoder()
 curr_cost = 0.0
 
 
+def range_format(start_line_num: Optional[int], end_line_num: Optional[int]) -> str:
+    st = "" if not start_line_num else str(start_line_num)
+    end = "" if not end_line_num else str(end_line_num)
+    if not st and not end:
+        return ""
+    return f":{st}-{end}"
+
+
 def read_files(
-    file_paths: list[str], max_tokens: Optional[int], context: Context
-) -> str:
+    file_paths: list[str],
+    max_tokens: Optional[int],
+    context: Context,
+    show_line_numbers: bool = False,
+    start_line_nums: Optional[list[Optional[int]]] = None,
+    end_line_nums: Optional[list[Optional[int]]] = None,
+) -> tuple[
+    str, dict[str, list[tuple[int, int]]], bool
+]:  # Updated to return file paths with ranges
     message = ""
+    file_ranges_dict: dict[
+        str, list[tuple[int, int]]
+    ] = {}  # Map file paths to line ranges
+
+    workspace_path = context.bash_state.workspace_root
+    stats = load_workspace_stats(workspace_path)
+
+    for path_ in file_paths:
+        path_ = expand_user(path_)
+        if not os.path.isabs(path_):
+            continue
+        if path_ not in stats.files:
+            stats.files[path_] = FileStats()
+
+        stats.files[path_].increment_read()
+    save_workspace_stats(workspace_path, stats)
+    truncated = False
     for i, file in enumerate(file_paths):
         try:
-            content, truncated, tokens = read_file(file, max_tokens, context)
+            # Use line numbers from parameters if provided
+            start_line_num = None if start_line_nums is None else start_line_nums[i]
+            end_line_num = None if end_line_nums is None else end_line_nums[i]
+
+            # For backward compatibility, we still need to extract line numbers from path
+            # if they weren't provided as parameters
+            content, truncated, tokens, path, line_range = read_file(
+                file,
+                max_tokens,
+                context,
+                show_line_numbers,
+                start_line_num,
+                end_line_num,
+            )
+
+            # Add file path with line range to dictionary
+            if path in file_ranges_dict:
+                file_ranges_dict[path].append(line_range)
+            else:
+                file_ranges_dict[path] = [line_range]
         except Exception as e:
             message += f"\n{file}: {str(e)}\n"
             continue
@@ -763,7 +1087,8 @@ def read_files(
         if max_tokens:
             max_tokens = max_tokens - tokens
 
-        message += f"\n``` {file}\n{content}\n"
+        range_formatted = range_format(start_line_num, end_line_num)
+        message += f"\n{file}{range_formatted}\n```\n{content}\n"
 
         if truncated or (max_tokens and max_tokens <= 0):
             not_reading = file_paths[i + 1 :]
@@ -772,15 +1097,21 @@ def read_files(
             break
         else:
             message += "```"
-
-    return message
+    return message, file_ranges_dict, truncated
 
 
 def read_file(
-    file_path: str, max_tokens: Optional[int], context: Context
-) -> tuple[str, bool, int]:
+    file_path: str,
+    max_tokens: Optional[int],
+    context: Context,
+    show_line_numbers: bool = False,
+    start_line_num: Optional[int] = None,
+    end_line_num: Optional[int] = None,
+) -> tuple[str, bool, int, str, tuple[int, int]]:
     context.console.print(f"Reading file: {file_path}")
 
+    # Line numbers are now passed as parameters, no need to parse from path
+
     # Expand the path before checking if it's absolute
     file_path = expand_user(file_path)
 
@@ -789,28 +1120,83 @@ def read_file(
             f"Failure: file_path should be absolute path, current working directory is {context.bash_state.cwd}"
         )
 
-    context.bash_state.add_to_whitelist_for_overwrite(file_path)
-
     path = Path(file_path)
     if not path.exists():
         raise ValueError(f"Error: file {file_path} does not exist")
 
+    # Read all lines of the file
     with path.open("r") as f:
-        content = f.read(10_000_000)
+        all_lines = f.readlines(10_000_000)
+
+        if all_lines[-1].endswith("\n"):
+            # Special handling of line counts because readlines doesn't consider last empty line as a separate line
+            all_lines[-1] = all_lines[-1][:-1]
+            all_lines.append("")
+
+    total_lines = len(all_lines)
+
+    # Apply line range filtering if specified
+    start_idx = 0
+    if start_line_num is not None:
+        # Convert 1-indexed line number to 0-indexed
+        start_idx = max(0, start_line_num - 1)
+
+    end_idx = len(all_lines)
+    if end_line_num is not None:
+        # end_line_num is inclusive, so we use min to ensure it's within bounds
+        end_idx = min(len(all_lines), end_line_num)
+
+    # Convert back to 1-indexed line numbers for tracking
+    effective_start = start_line_num if start_line_num is not None else 1
+    effective_end = end_line_num if end_line_num is not None else total_lines
+
+    filtered_lines = all_lines[start_idx:end_idx]
+
+    # Create content with or without line numbers
+    if show_line_numbers:
+        content_lines = []
+        for i, line in enumerate(filtered_lines, start=start_idx + 1):
+            content_lines.append(f"{i} {line}")
+        content = "".join(content_lines)
+    else:
+        content = "".join(filtered_lines)
 
     truncated = False
     tokens_counts = 0
+
+    # Handle token limit if specified
     if max_tokens is not None:
         tokens = default_enc.encoder(content)
         tokens_counts = len(tokens)
+
         if len(tokens) > max_tokens:
-            content = default_enc.decoder(tokens[:max_tokens])
-            rest = save_out_of_context(
-                default_enc.decoder(tokens[max_tokens:]), Path(file_path).suffix
-            )
-            content += f"\n(...truncated)\n---\nI've saved the continuation in a new file. You may want to read: `{rest}`"
+            # Truncate at token boundary first
+            truncated_tokens = tokens[:max_tokens]
+            truncated_content = default_enc.decoder(truncated_tokens)
+
+            # Count how many lines we kept
+            line_count = truncated_content.count("\n")
+
+            # Calculate the last line number shown (1-indexed)
+            last_line_shown = start_idx + line_count
+
+            content = truncated_content
+            # Add informative message about truncation with total line count
+            total_lines = len(all_lines)
+            content += f"\n(...truncated) Only showing till line number {last_line_shown} of {total_lines} total lines due to the token limit, please continue reading from {last_line_shown + 1} if required"
             truncated = True
-    return content, truncated, tokens_counts
+
+            # Update effective_end if truncated
+            effective_end = last_line_shown
+
+    # Return the content along with the effective line range that was read
+    return (
+        content,
+        truncated,
+        tokens_counts,
+        file_path,
+        (effective_start, effective_end),
+    )
 
 
 if __name__ == "__main__":
@@ -851,3 +1237,32 @@ if __name__ == "__main__":
                 None,
             )
         )
+
+        print(
+            get_tool_output(
+                Context(BASH_STATE, BASH_STATE.console),
+                ReadFiles(
+                    file_paths=["/Users/arusia/repos/wcgw/src/wcgw/client/tools.py"],
+                    show_line_numbers_reason="true",
+                ),
+                default_enc,
+                0,
+                lambda x, y: ("", 0),
+                15000,
+            )[0][0]
+        )
+
+        print(
+            get_tool_output(
+                Context(BASH_STATE, BASH_STATE.console),
+                FileWriteOrEdit(
+                    file_path="/Users/arusia/repos/wcgw/src/wcgw/client/tools.py",
+                    file_content_or_search_replace_blocks="""test""",
+                    percentage_to_change=100,
+                ),
+                default_enc,
+                0,
+                lambda x, y: ("", 0),
+                800,
+            )[0][0]
+        )