klaude-code 1.2.6__py3-none-any.whl → 1.8.0__py3-none-any.whl

klaude_code/core/tool/file/read_tool.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
+import hashlib
 import os
 from base64 import b64encode
 from dataclasses import dataclass
@@ -9,17 +11,12 @@ from pathlib import Path
 from pydantic import BaseModel, Field
 
 from klaude_code import const
+from klaude_code.core.tool.file._utils import file_exists, is_directory
 from klaude_code.core.tool.tool_abc import ToolABC, load_desc
 from klaude_code.core.tool.tool_context import get_current_file_tracker
 from klaude_code.core.tool.tool_registry import register
 from klaude_code.protocol import llm_param, model, tools
 
-SYSTEM_REMINDER_MALICIOUS = (
-    "<system-reminder>\n"
-    "Whenever you read a file, you should consider whether it looks malicious. If it does, you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer high-level questions about the code behavior.\n"
-    "</system-reminder>"
-)
-
 _IMAGE_MIME_TYPES: dict[str, str] = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -28,24 +25,22 @@ _IMAGE_MIME_TYPES: dict[str, str] = {
     ".webp": "image/webp",
 }
 
-
-def _format_numbered_line(line_no: int, content: str) -> str:
-    # 6-width right-aligned line number followed by a right arrow
-    return f"{line_no:>6}→{content}"
+_BINARY_CHECK_SIZE = 8192
 
 
-def _is_directory(path: str) -> bool:
+def _is_binary_file(file_path: str) -> bool:
+    """Check if a file is binary by looking for null bytes in the first chunk."""
     try:
-        return Path(path).is_dir()
-    except Exception:
+        with open(file_path, "rb") as f:
+            chunk = f.read(_BINARY_CHECK_SIZE)
+            return b"\x00" in chunk
+    except OSError:
         return False
 
 
-def _file_exists(path: str) -> bool:
-    try:
-        return Path(path).exists()
-    except Exception:
-        return False
+def _format_numbered_line(line_no: int, content: str) -> str:
+    # 6-width right-aligned line number followed by a right arrow
+    return f"{line_no:>6}→{content}"
 
 
 @dataclass
@@ -55,6 +50,7 @@ class ReadOptions:
     limit: int | None
     char_limit_per_line: int | None = const.READ_CHAR_LIMIT_PER_LINE
     global_line_cap: int | None = const.READ_GLOBAL_LINE_CAP
+    max_total_chars: int | None = const.READ_MAX_CHARS
 
 
 @dataclass
@@ -63,20 +59,32 @@ class ReadSegmentResult:
     selected_lines: list[tuple[int, str]]
     selected_chars_count: int
     remaining_selected_beyond_cap: int
+    remaining_due_to_char_limit: int
+    content_sha256: str
 
 
 def _read_segment(options: ReadOptions) -> ReadSegmentResult:
     total_lines = 0
     selected_lines_count = 0
     remaining_selected_beyond_cap = 0
+    remaining_due_to_char_limit = 0
     selected_lines: list[tuple[int, str]] = []
     selected_chars = 0
-    with open(options.file_path, "r", encoding="utf-8", errors="replace") as f:
+    char_limit_reached = False
+    hasher = hashlib.sha256()
+
+    with open(options.file_path, encoding="utf-8", errors="replace") as f:
         for line_no, raw_line in enumerate(f, start=1):
             total_lines = line_no
+            hasher.update(raw_line.encode("utf-8"))
             within = line_no >= options.offset and (options.limit is None or selected_lines_count < options.limit)
             if not within:
                 continue
+
+            if char_limit_reached:
+                remaining_due_to_char_limit += 1
+                continue
+
             selected_lines_count += 1
             content = raw_line.rstrip("\n")
             original_len = len(content)
@@ -86,27 +94,41 @@ def _read_segment(options: ReadOptions) -> ReadSegmentResult:
                     content[: options.char_limit_per_line]
                     + f" ... (more {truncated_chars} characters in this line are truncated)"
                 )
-            selected_chars += len(content) + 1
+            line_chars = len(content) + 1
+            selected_chars += line_chars
+
+            if options.max_total_chars is not None and selected_chars > options.max_total_chars:
+                char_limit_reached = True
+                selected_lines.append((line_no, content))
+                continue
+
             if options.global_line_cap is None or len(selected_lines) < options.global_line_cap:
                 selected_lines.append((line_no, content))
             else:
                 remaining_selected_beyond_cap += 1
+
     return ReadSegmentResult(
         total_lines=total_lines,
         selected_lines=selected_lines,
         selected_chars_count=selected_chars,
         remaining_selected_beyond_cap=remaining_selected_beyond_cap,
+        remaining_due_to_char_limit=remaining_due_to_char_limit,
+        content_sha256=hasher.hexdigest(),
     )
 
 
-def _track_file_access(file_path: str) -> None:
+def _track_file_access(file_path: str, *, content_sha256: str | None = None, is_memory: bool = False) -> None:
     file_tracker = get_current_file_tracker()
-    if file_tracker is None or not _file_exists(file_path) or _is_directory(file_path):
+    if file_tracker is None or not file_exists(file_path) or is_directory(file_path):
         return
-    try:
-        file_tracker[file_path] = Path(file_path).stat().st_mtime
-    except Exception:
-        pass
+    with contextlib.suppress(Exception):
+        existing = file_tracker.get(file_path)
+        is_mem = is_memory or (existing.is_memory if existing else False)
+        file_tracker[file_path] = model.FileStatus(
+            mtime=Path(file_path).stat().st_mtime,
+            content_sha256=content_sha256,
+            is_memory=is_mem,
+        )
 
 
 def _is_supported_image_file(file_path: str) -> bool:
@@ -121,12 +143,6 @@ def _image_mime_type(file_path: str) -> str:
     return mime_type
 
 
-def _encode_image_to_data_url(file_path: str, mime_type: str) -> str:
-    with open(file_path, "rb") as image_file:
-        encoded = b64encode(image_file.read()).decode("ascii")
-    return f"data:{mime_type};base64,{encoded}"
-
-
 @register(tools.READ)
 class ReadTool(ToolABC):
     class ReadArguments(BaseModel):
@@ -170,30 +186,24 @@ class ReadTool(ToolABC):
         return await cls.call_with_args(args)
 
     @classmethod
-    def _effective_limits(cls) -> tuple[int | None, int | None, int | None, int | None]:
-        """Return effective limits based on current policy: char_per_line, global_line_cap, max_chars, max_kb"""
+    def _effective_limits(cls) -> tuple[int | None, int | None, int | None]:
         return (
             const.READ_CHAR_LIMIT_PER_LINE,
             const.READ_GLOBAL_LINE_CAP,
             const.READ_MAX_CHARS,
-            const.READ_MAX_KB,
         )
 
     @classmethod
     async def call_with_args(cls, args: ReadTool.ReadArguments) -> model.ToolResultItem:
-        # Accept relative path by resolving to absolute (schema encourages absolute)
         file_path = os.path.abspath(args.file_path)
+        char_per_line, line_cap, max_chars = cls._effective_limits()
 
-        # Get effective limits based on policy
-        char_per_line, line_cap, max_chars, max_kb = cls._effective_limits()
-
-        # Common file errors
-        if _is_directory(file_path):
+        if is_directory(file_path):
             return model.ToolResultItem(
                 status="error",
                 output="<tool_use_error>Illegal operation on a directory. read</tool_use_error>",
             )
-        if not _file_exists(file_path):
+        if not file_exists(file_path):
             return model.ToolResultItem(
                 status="error",
                 output="<tool_use_error>File does not exist.</tool_use_error>",
@@ -204,8 +214,9 @@ class ReadTool(ToolABC):
             return model.ToolResultItem(
                 status="error",
                 output=(
-                    "<tool_use_error>PDF files are not supported by this tool. "
-                    "Please use a Python script with `pdfplumber` to extract text/tables:\n\n"
+                    "<tool_use_error>PDF files are not supported by this tool.\n"
+                    "If there's an available skill for PDF, use it.\n"
+                    "Or use a Python script with `pdfplumber` to extract text/tables:\n\n"
                     "```python\n"
                     "# /// script\n"
                     '# dependencies = ["pdfplumber"]\n'
@@ -219,13 +230,22 @@ class ReadTool(ToolABC):
                 ),
             )
 
-        # If file is too large and no pagination provided (only check if limits are enabled)
+        is_image_file = _is_supported_image_file(file_path)
+        # Check for binary files (skip for images which are handled separately)
+        if not is_image_file and _is_binary_file(file_path):
+            return model.ToolResultItem(
+                status="error",
+                output=(
+                    "<tool_use_error>This appears to be a binary file and cannot be read as text. "
+                    "Use appropriate tools or libraries to handle binary files.</tool_use_error>"
+                ),
+            )
+
         try:
             size_bytes = Path(file_path).stat().st_size
-        except Exception:
+        except OSError:
             size_bytes = 0
 
-        is_image_file = _is_supported_image_file(file_path)
         if is_image_file:
             if size_bytes > const.READ_MAX_IMAGE_BYTES:
                 size_mb = size_bytes / (1024 * 1024)
@@ -237,42 +257,26 @@ class ReadTool(ToolABC):
                 )
             try:
                 mime_type = _image_mime_type(file_path)
-                data_url = _encode_image_to_data_url(file_path, mime_type)
+                with open(file_path, "rb") as image_file:
+                    image_bytes = image_file.read()
+                data_url = f"data:{mime_type};base64,{b64encode(image_bytes).decode('ascii')}"
             except Exception as exc:
                 return model.ToolResultItem(
                     status="error",
                     output=f"<tool_use_error>Failed to read image file: {exc}</tool_use_error>",
                 )
 
-            _track_file_access(file_path)
+            _track_file_access(file_path, content_sha256=hashlib.sha256(image_bytes).hexdigest())
             size_kb = size_bytes / 1024.0 if size_bytes else 0.0
             output_text = f"[image] {Path(file_path).name} ({size_kb:.1f}KB)"
             image_part = model.ImageURLPart(image_url=model.ImageURLPart.ImageURL(url=data_url, id=None))
             return model.ToolResultItem(status="success", output=output_text, images=[image_part])
 
-        if (
-            not is_image_file
-            and max_kb is not None
-            and args.offset is None
-            and args.limit is None
-            and size_bytes > max_kb * 1024
-        ):
-            size_kb = size_bytes / 1024.0
-            return model.ToolResultItem(
-                status="error",
-                output=(
-                    f"File content ({size_kb:.1f}KB) exceeds maximum allowed size ({max_kb}KB). Please use offset and limit parameters to read specific portions of the file, or use the `rg` command to search for specific content."
-                ),
-            )
-
         offset = 1 if args.offset is None or args.offset < 1 else int(args.offset)
         limit = None if args.limit is None else int(args.limit)
         if limit is not None and limit < 0:
             limit = 0
 
-        # Stream file line-by-line and build response
-        read_result: ReadSegmentResult | None = None
-
         try:
             read_result = await asyncio.to_thread(
                 _read_segment,
@@ -282,6 +286,7 @@ class ReadTool(ToolABC):
                     limit=limit,
                     char_limit_per_line=char_per_line,
                     global_line_cap=line_cap,
+                    max_total_chars=max_chars,
                 ),
             )
 
@@ -296,31 +301,26 @@ class ReadTool(ToolABC):
                 output="<tool_use_error>Illegal operation on a directory. read</tool_use_error>",
             )
 
-        # If offset beyond total lines, emit system reminder warning
         if offset > max(read_result.total_lines, 0):
             warn = f"<system-reminder>Warning: the file exists but is shorter than the provided offset ({offset}). The file has {read_result.total_lines} lines.</system-reminder>"
-            # Update FileTracker (we still consider it as a read attempt)
-            _track_file_access(file_path)
+            _track_file_access(file_path, content_sha256=read_result.content_sha256)
             return model.ToolResultItem(status="success", output=warn)
 
-        # After limit/offset, if total selected chars exceed limit, error (only check if limits are enabled)
-        if max_chars is not None and read_result.selected_chars_count > max_chars:
-            return model.ToolResultItem(
-                status="error",
-                output=(
-                    f"File content ({read_result.selected_chars_count} chars) exceeds maximum allowed tokens ({max_chars}). Please use offset and limit parameters to read specific portions of the file, or use the `rg` command to search for specific content."
-                ),
+        lines_out: list[str] = [_format_numbered_line(no, content) for no, content in read_result.selected_lines]
+
+        # Show truncation info with reason
+        if read_result.remaining_due_to_char_limit > 0:
+            lines_out.append(
+                f"... ({read_result.remaining_due_to_char_limit} more lines truncated due to {max_chars} char limit, "
+                f"file has {read_result.total_lines} lines total, use offset/limit to read other parts)"
+            )
+        elif read_result.remaining_selected_beyond_cap > 0:
+            lines_out.append(
+                f"... ({read_result.remaining_selected_beyond_cap} more lines truncated due to {line_cap} line limit, "
+                f"file has {read_result.total_lines} lines total, use offset/limit to read other parts)"
             )
 
-        # Build display with numbering and reminders
-        lines_out: list[str] = [_format_numbered_line(no, content) for no, content in read_result.selected_lines]
-        if read_result.remaining_selected_beyond_cap > 0:
-            lines_out.append(f"... (more {read_result.remaining_selected_beyond_cap} lines are truncated)")
         read_result_str = "\n".join(lines_out)
-        # if read_result_str:
-        # read_result_str += "\n\n" + SYSTEM_REMINDER_MALICIOUS
-
-        # Update FileTracker with last modified time
-        _track_file_access(file_path)
+        _track_file_access(file_path, content_sha256=read_result.content_sha256)
 
         return model.ToolResultItem(status="success", output=read_result_str)

klaude_code/core/tool/file/write_tool.py

@@ -1,44 +1,20 @@
 from __future__ import annotations
 
 import asyncio
-import difflib
+import contextlib
 import os
 from pathlib import Path
 
 from pydantic import BaseModel
 
+from klaude_code.core.tool.file._utils import file_exists, hash_text_sha256, is_directory, read_text, write_text
+from klaude_code.core.tool.file.diff_builder import build_structured_diff
 from klaude_code.core.tool.tool_abc import ToolABC, load_desc
 from klaude_code.core.tool.tool_context import get_current_file_tracker
 from klaude_code.core.tool.tool_registry import register
 from klaude_code.protocol import llm_param, model, tools
 
 
-def _is_directory(path: str) -> bool:
-    try:
-        return Path(path).is_dir()
-    except Exception:
-        return False
-
-
-def _file_exists(path: str) -> bool:
-    try:
-        return Path(path).exists()
-    except Exception:
-        return False
-
-
-def _write_text(path: str, content: str) -> None:
-    parent = Path(path).parent
-    parent.mkdir(parents=True, exist_ok=True)
-    with open(path, "w", encoding="utf-8") as f:
-        f.write(content)
-
-
-def _read_text(path: str) -> str:
-    with open(path, "r", encoding="utf-8", errors="replace") as f:
-        return f.read()
-
-
 class WriteArguments(BaseModel):
     file_path: str
     content: str
@@ -73,74 +49,88 @@ class WriteTool(ToolABC):
     async def call(cls, arguments: str) -> model.ToolResultItem:
         try:
             args = WriteArguments.model_validate_json(arguments)
-        except Exception as e:  # pragma: no cover - defensive
+        except ValueError as e:  # pragma: no cover - defensive
             return model.ToolResultItem(status="error", output=f"Invalid arguments: {e}")
 
         file_path = os.path.abspath(args.file_path)
 
-        if _is_directory(file_path):
+        if is_directory(file_path):
             return model.ToolResultItem(
                 status="error",
                 output="<tool_use_error>Illegal operation on a directory. write</tool_use_error>",
             )
 
         file_tracker = get_current_file_tracker()
-        exists = _file_exists(file_path)
+        exists = file_exists(file_path)
+        tracked_status: model.FileStatus | None = None
 
         if exists:
-            tracked_mtime: float | None = None
-            if file_tracker is not None:
-                tracked_mtime = file_tracker.get(file_path)
-            if tracked_mtime is None:
+            tracked_status = file_tracker.get(file_path) if file_tracker is not None else None
+            if tracked_status is None:
                 return model.ToolResultItem(
                     status="error",
                     output=("File has not been read yet. Read it first before writing to it."),
                 )
-            try:
-                current_mtime = Path(file_path).stat().st_mtime
-            except Exception:
-                current_mtime = tracked_mtime
-            if current_mtime != tracked_mtime:
-                return model.ToolResultItem(
-                    status="error",
-                    output=(
-                        "File has been modified externally. Either by user or a linter. "
-                        "Read it first before writing to it."
-                    ),
-                )
 
-        # Capture previous content (if any) for diff generation
+        # Capture previous content (if any) for diff generation and external-change detection.
         before = ""
+        before_read_ok = False
         if exists:
             try:
-                before = await asyncio.to_thread(_read_text, file_path)
-            except Exception:
+                before = await asyncio.to_thread(read_text, file_path)
+                before_read_ok = True
+            except OSError:
                 before = ""
+                before_read_ok = False
+
+            # Re-check external modifications using content hash when available.
+            if before_read_ok and tracked_status is not None and tracked_status.content_sha256 is not None:
+                current_sha256 = hash_text_sha256(before)
+                if current_sha256 != tracked_status.content_sha256:
+                    return model.ToolResultItem(
+                        status="error",
+                        output=(
+                            "File has been modified externally. Either by user or a linter. "
+                            "Read it first before writing to it."
+                        ),
+                    )
+            elif tracked_status is not None:
+                # Backward-compat: old sessions only stored mtime, or we couldn't hash.
+                try:
+                    current_mtime = Path(file_path).stat().st_mtime
+                except OSError:
+                    current_mtime = tracked_status.mtime
+                if current_mtime != tracked_status.mtime:
+                    return model.ToolResultItem(
+                        status="error",
+                        output=(
+                            "File has been modified externally. Either by user or a linter. "
+                            "Read it first before writing to it."
+                        ),
+                    )
 
         try:
-            await asyncio.to_thread(_write_text, file_path, args.content)
-        except Exception as e:  # pragma: no cover
+            await asyncio.to_thread(write_text, file_path, args.content)
+        except (OSError, UnicodeError) as e:  # pragma: no cover
             return model.ToolResultItem(status="error", output=f"<tool_use_error>{e}</tool_use_error>")
 
         if file_tracker is not None:
-            try:
-                file_tracker[file_path] = Path(file_path).stat().st_mtime
-            except Exception:
-                pass
-
-        # Build diff between previous and new content
-        after = args.content
-        diff_lines = list(
-            difflib.unified_diff(
-                before.splitlines(),
-                after.splitlines(),
-                fromfile=file_path,
-                tofile=file_path,
-                n=3,
-            )
-        )
-        diff_text = "\n".join(diff_lines)
-        ui_extra = model.ToolResultUIExtra(type=model.ToolResultUIExtraType.DIFF_TEXT, diff_text=diff_text)
+            with contextlib.suppress(Exception):
+                existing = file_tracker.get(file_path)
+                is_mem = existing.is_memory if existing else False
+                file_tracker[file_path] = model.FileStatus(
+                    mtime=Path(file_path).stat().st_mtime,
+                    content_sha256=hash_text_sha256(args.content),
+                    is_memory=is_mem,
+                )
+
+        # For markdown files, use MarkdownDocUIExtra to render content as markdown
+        # Otherwise, build diff between previous and new content
+        ui_extra: model.ToolResultUIExtra | None
+        if file_path.endswith(".md"):
+            ui_extra = model.MarkdownDocUIExtra(file_path=file_path, content=args.content)
+        else:
+            ui_extra = build_structured_diff(before, args.content, file_path=file_path)
 
         message = f"File {'overwritten' if exists else 'created'} successfully at: {file_path}"
         return model.ToolResultItem(status="success", output=message, ui_extra=ui_extra)

klaude_code/core/tool/report_back_tool.py

@@ -0,0 +1,84 @@
+"""ReportBackTool for sub-agents to return structured output."""
+
+from typing import Any, ClassVar, cast
+
+from klaude_code.protocol import llm_param, model, tools
+
+
+def _normalize_schema_types(schema: dict[str, Any]) -> dict[str, Any]:
+    """Recursively normalize JSON schema type values to lowercase.
+
+    Some LLMs (e.g., Gemini 3) generate type values in uppercase like "OBJECT", "STRING".
+    Standard JSON Schema requires lowercase type values.
+    """
+    result: dict[str, Any] = {}
+    for key, value in schema.items():
+        if key == "type" and isinstance(value, str):
+            result[key] = value.lower()
+        elif isinstance(value, dict):
+            result[key] = _normalize_schema_types(cast(dict[str, Any], value))
+        elif isinstance(value, list):
+            normalized_list: list[Any] = []
+            for item in cast(list[Any], value):
+                if isinstance(item, dict):
+                    normalized_list.append(_normalize_schema_types(cast(dict[str, Any], item)))
+                else:
+                    normalized_list.append(item)
+            result[key] = normalized_list
+        else:
+            result[key] = value
+    return result
+
+
+class ReportBackTool:
+    """Special tool for sub-agents to return structured output and end the task.
+
+    This tool is dynamically injected when a parent agent calls a sub-agent with
+    an output_schema. The schema for this tool's parameters is defined by the
+    parent agent, allowing structured data to be returned.
+
+    Note: This class does not inherit from ToolABC because it's not registered
+    in the global tool registry. Instead, it's handled specially by the
+    TurnExecutor and SubAgentManager.
+    """
+
+    _schema: ClassVar[dict[str, Any]] = {}
+
+    @classmethod
+    def for_schema(cls, schema: dict[str, Any]) -> type["ReportBackTool"]:
+        """Create a tool class with the specified output schema.
+
+        Args:
+            schema: JSON Schema defining the expected structure of the report_back arguments.
+
+        Returns:
+            A new class with the schema set as a class variable.
+        """
+        normalized = _normalize_schema_types(schema)
+        return type("ReportBackTool", (ReportBackTool,), {"_schema": normalized})
+
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        """Generate the tool schema for this report_back tool."""
+        return llm_param.ToolSchema(
+            name=tools.REPORT_BACK,
+            type="function",
+            description=(
+                "Report the final structured result back to the parent agent. "
+                "Call this when you have completed the task and want to return structured data. "
+                "The task will end after this tool is called."
+            ),
+            parameters=cls._schema,
+        )
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        """Execute the report_back tool.
+
+        The actual handling of report_back results is done by TurnExecutor.
+        This method just returns a success status to maintain the tool call flow.
+        """
+        return model.ToolResultItem(
+            status="success",
+            output="Result reported successfully. Task will end.",
+        )