klaude-code 1.2.6__py3-none-any.whl

klaude_code/core/tool/file/multi_edit_tool.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import asyncio
+import difflib
+import os
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from klaude_code.core.tool.file.edit_tool import EditTool
+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 _read_text(path: str) -> str:
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+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)
+
+
+@register(tools.MULTI_EDIT)
+class MultiEditTool(ToolABC):
+    class MultiEditEditItem(BaseModel):
+        old_string: str
+        new_string: str
+        replace_all: bool = Field(default=False)
+
+    class MultiEditArguments(BaseModel):
+        file_path: str
+        edits: list[MultiEditTool.MultiEditEditItem]
+
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.MULTI_EDIT,
+            type="function",
+            description=load_desc(Path(__file__).parent / "multi_edit_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "The absolute path to the file to modify",
+                    },
+                    "edits": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "old_string": {
+                                    "type": "string",
+                                    "description": "The text to replace",
+                                },
+                                "new_string": {
+                                    "type": "string",
+                                    "description": "The text to replace it with",
+                                },
+                                "replace_all": {
+                                    "type": "boolean",
+                                    "default": False,
+                                    "description": "Replace all occurences of old_string (default false).",
+                                },
+                            },
+                            "required": ["old_string", "new_string"],
+                            "additionalProperties": False,
+                        },
+                        "minItems": 1,
+                        "description": "Array of edit operations to perform sequentially on the file",
+                    },
+                },
+                "required": ["file_path", "edits"],
+                "additionalProperties": False,
+            },
+        )
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        try:
+            args = MultiEditTool.MultiEditArguments.model_validate_json(arguments)
+        except Exception as e:  # pragma: no cover - defensive
+            return model.ToolResultItem(status="error", output=f"Invalid arguments: {e}")
+
+        file_path = os.path.abspath(args.file_path)
+
+        # Directory error first
+        if _is_directory(file_path):
+            return model.ToolResultItem(
+                status="error",
+                output="<tool_use_error>Illegal operation on a directory. multi_edit</tool_use_error>",
+            )
+
+        file_tracker = get_current_file_tracker()
+
+        # FileTracker check:
+        if _file_exists(file_path):
+            if file_tracker is not None:
+                tracked = file_tracker.get(file_path)
+                if tracked 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
+                if current_mtime != tracked:
+                    return model.ToolResultItem(
+                        status="error",
+                        output=(
+                            "File has been modified externally. Either by user or a linter. Read it first before writing to it."
+                        ),
+                    )
+        else:
+            # Allow creation only if first edit is creating content (old_string == "")
+            if not args.edits or args.edits[0].old_string != "":
+                return model.ToolResultItem(
+                    status="error",
+                    output=("File has not been read yet. Read it first before writing to it."),
+                )
+
+        # Load initial content (empty for new file case)
+        if _file_exists(file_path):
+            before = await asyncio.to_thread(_read_text, file_path)
+        else:
+            before = ""
+
+        # Validate all edits atomically against staged content
+        staged = before
+        for edit in args.edits:
+            err = EditTool.valid(
+                content=staged,
+                old_string=edit.old_string,
+                new_string=edit.new_string,
+                replace_all=edit.replace_all,
+            )
+            if err is not None:
+                return model.ToolResultItem(status="error", output=err)
+            # Apply to staged content
+            staged = EditTool.execute(
+                content=staged,
+                old_string=edit.old_string,
+                new_string=edit.new_string,
+                replace_all=edit.replace_all,
+            )
+
+        # All edits valid; write to disk
+        try:
+            await asyncio.to_thread(_write_text, file_path, staged)
+        except Exception as e:  # pragma: no cover
+            return model.ToolResultItem(status="error", output=f"<tool_use_error>{e}</tool_use_error>")
+
+        # Prepare UI extra: unified diff
+        diff_lines = list(
+            difflib.unified_diff(
+                before.splitlines(),
+                staged.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)
+
+        # Update tracker
+        if file_tracker is not None:
+            try:
+                file_tracker[file_path] = Path(file_path).stat().st_mtime
+            except Exception:
+                pass
+
+        # Build output message
+        lines = [f"Applied {len(args.edits)} edits to {file_path}:"]
+        for i, edit in enumerate(args.edits, start=1):
+            lines.append(f'{i}. Replaced "{edit.old_string}" with "{edit.new_string}"')
+        return model.ToolResultItem(status="success", output="\n".join(lines), ui_extra=ui_extra)

klaude_code/core/tool/file/read_tool.md

@@ -0,0 +1,14 @@
+Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 lines starting from the beginning of the file
+- This tool allows you to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as you are a multimodal LLM.
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- Any lines longer than 2000 characters will be truncated
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
+- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful. 
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
+- This tool does NOT support reading PDF files. Use a Python script with `pdfplumber` (for text/tables) or `pypdf` (for basic operations) to extract content from PDFs.

klaude_code/core/tool/file/read_tool.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from base64 import b64encode
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from klaude_code import const
+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",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".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}"
+
+
+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
+
+
+@dataclass
+class ReadOptions:
+    file_path: str
+    offset: int
+    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
+
+
+@dataclass
+class ReadSegmentResult:
+    total_lines: int
+    selected_lines: list[tuple[int, str]]
+    selected_chars_count: int
+    remaining_selected_beyond_cap: int
+
+
+def _read_segment(options: ReadOptions) -> ReadSegmentResult:
+    total_lines = 0
+    selected_lines_count = 0
+    remaining_selected_beyond_cap = 0
+    selected_lines: list[tuple[int, str]] = []
+    selected_chars = 0
+    with open(options.file_path, "r", encoding="utf-8", errors="replace") as f:
+        for line_no, raw_line in enumerate(f, start=1):
+            total_lines = line_no
+            within = line_no >= options.offset and (options.limit is None or selected_lines_count < options.limit)
+            if not within:
+                continue
+            selected_lines_count += 1
+            content = raw_line.rstrip("\n")
+            original_len = len(content)
+            if options.char_limit_per_line is not None and original_len > options.char_limit_per_line:
+                truncated_chars = original_len - options.char_limit_per_line
+                content = (
+                    content[: options.char_limit_per_line]
+                    + f" ... (more {truncated_chars} characters in this line are truncated)"
+                )
+            selected_chars += len(content) + 1
+            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,
+    )
+
+
+def _track_file_access(file_path: str) -> None:
+    file_tracker = get_current_file_tracker()
+    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
+
+
+def _is_supported_image_file(file_path: str) -> bool:
+    return Path(file_path).suffix.lower() in _IMAGE_MIME_TYPES
+
+
+def _image_mime_type(file_path: str) -> str:
+    suffix = Path(file_path).suffix.lower()
+    mime_type = _IMAGE_MIME_TYPES.get(suffix)
+    if mime_type is None:
+        raise ValueError(f"Unsupported image file extension: {suffix}")
+    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):
+        file_path: str
+        offset: int | None = Field(default=None)
+        limit: int | None = Field(default=None)
+
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.READ,
+            type="function",
+            description=load_desc(Path(__file__).parent / "read_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "The absolute path to the file to read",
+                    },
+                    "offset": {
+                        "type": "number",
+                        "description": "The line number to start reading from. Only provide if the file is too large to read at once",
+                    },
+                    "limit": {
+                        "type": "number",
+                        "description": "The number of lines to read. Only provide if the file is too large to read at once.",
+                    },
+                },
+                "required": ["file_path"],
+                "additionalProperties": False,
+            },
+        )
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        try:
+            args = ReadTool.ReadArguments.model_validate_json(arguments)
+        except Exception as e:  # pragma: no cover - defensive
+            return model.ToolResultItem(status="error", output=f"Invalid arguments: {e}")
+        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"""
+        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)
+
+        # 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):
+            return model.ToolResultItem(
+                status="error",
+                output="<tool_use_error>Illegal operation on a directory. read</tool_use_error>",
+            )
+        if not _file_exists(file_path):
+            return model.ToolResultItem(
+                status="error",
+                output="<tool_use_error>File does not exist.</tool_use_error>",
+            )
+
+        # Check for PDF files
+        if Path(file_path).suffix.lower() == ".pdf":
+            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"
+                    "```python\n"
+                    "# /// script\n"
+                    '# dependencies = ["pdfplumber"]\n'
+                    "# ///\n"
+                    "import pdfplumber\n\n"
+                    "with pdfplumber.open('file.pdf') as pdf:\n"
+                    "    for page in pdf.pages:\n"
+                    "        print(page.extract_text())\n"
+                    "```\n"
+                    "</tool_use_error>"
+                ),
+            )
+
+        # If file is too large and no pagination provided (only check if limits are enabled)
+        try:
+            size_bytes = Path(file_path).stat().st_size
+        except Exception:
+            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)
+                return model.ToolResultItem(
+                    status="error",
+                    output=(
+                        f"<tool_use_error>Image size ({size_mb:.2f}MB) exceeds maximum supported size (4.00MB) for inline transfer.</tool_use_error>"
+                    ),
+                )
+            try:
+                mime_type = _image_mime_type(file_path)
+                data_url = _encode_image_to_data_url(file_path, mime_type)
+            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)
+            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,
+                ReadOptions(
+                    file_path=file_path,
+                    offset=offset,
+                    limit=limit,
+                    char_limit_per_line=char_per_line,
+                    global_line_cap=line_cap,
+                ),
+            )
+
+        except FileNotFoundError:
+            return model.ToolResultItem(
+                status="error",
+                output="<tool_use_error>File does not exist.</tool_use_error>",
+            )
+        except IsADirectoryError:
+            return model.ToolResultItem(
+                status="error",
+                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)
+            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."
+                ),
+            )
+
+        # 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)
+
+        return model.ToolResultItem(status="success", output=read_result_str)

klaude_code/core/tool/file/write_tool.md

@@ -0,0 +1,8 @@
+Writes a file to the local filesystem.
+
+Usage:
+This tool will overwrite the existing file if there is one at the provided path.
+If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.