klaude-code 2.4.2__py3-none-any.whl → 2.5.0__py3-none-any.whl

klaude_code/core/tool/offload.py

@@ -0,0 +1,311 @@
+"""Tool Output Offload & Truncation Strategies
+==============================================
+
+This module manages how tool outputs are truncated and offloaded to files
+to reduce LLM context usage while preserving access to full content.
+
+Design Principles
+-----------------
+Different tools have different output characteristics, so we apply
+tool-specific strategies:
+
+┌─────────────┬─────────────────────────┬─────────────────┬────────────────────────────┐
+│ Tool        │ Truncation Style        │ Offload Policy  │ Rationale                  │
+├─────────────┼─────────────────────────┼─────────────────┼────────────────────────────┤
+│ Read        │ Head-focused            │ Never           │ Source file already exists │
+│             │ (line/char limits)      │                 │ on filesystem; use offset/ │
+│             │                         │                 │ limit to paginate          │
+├─────────────┼─────────────────────────┼─────────────────┼────────────────────────────┤
+│ Others      │ Head + Tail             │ On threshold    │ Generic fallback strategy  │
+│             │ (lines first, then      │                 │ (2000 lines or 40k chars)  │
+│             │ chars as fallback)      │                 │                            │
+└─────────────┴─────────────────────────┴─────────────────┴────────────────────────────┘
+
+Implementation Notes
+--------------------
+- Read tool handles its own truncation internally (see read_tool.py)
+- WebFetch handles its own file saving internally (see web_fetch_tool.py)
+- All offload decisions are centralized in this module
+"""
+
+from __future__ import annotations
+
+import secrets
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum, auto
+from pathlib import Path
+from typing import Protocol
+
+from klaude_code.const import (
+    TOOL_OUTPUT_DISPLAY_HEAD,
+    TOOL_OUTPUT_DISPLAY_HEAD_LINES,
+    TOOL_OUTPUT_DISPLAY_TAIL,
+    TOOL_OUTPUT_DISPLAY_TAIL_LINES,
+    TOOL_OUTPUT_MAX_LENGTH,
+    TOOL_OUTPUT_MAX_LINES,
+    TOOL_OUTPUT_TRUNCATION_DIR,
+)
+from klaude_code.protocol import tools
+
+
+class ToolCallLike(Protocol):
+    """Protocol for tool call objects."""
+
+    @property
+    def tool_name(self) -> str: ...
+
+
+# =============================================================================
+# Data Structures
+# =============================================================================
+
+
+class OffloadPolicy(Enum):
+    """When to offload full output to filesystem."""
+
+    NEVER = auto()  # Never offload (e.g., Read - source file exists)
+    ON_THRESHOLD = auto()  # Offload only when exceeding size threshold
+
+
+class TruncationStyle(Enum):
+    """How to truncate content that exceeds limits."""
+
+    HEAD_ONLY = auto()  # Keep head, discard tail (important content at top)
+    HEAD_TAIL = auto()  # Keep head and tail, discard middle (errors at end)
+
+
+@dataclass
+class OffloadResult:
+    """Result of offload/truncation operation."""
+
+    output: str
+    was_truncated: bool
+    offloaded_path: str | None = None
+    original_length: int = 0
+    truncated_chars: int = 0
+
+
+# =============================================================================
+# Strategy Interface
+# =============================================================================
+
+
+class OffloadStrategy(ABC):
+    """Base class for tool-specific offload strategies."""
+
+    @property
+    @abstractmethod
+    def offload_policy(self) -> OffloadPolicy:
+        """When to offload content to file."""
+        ...
+
+    @property
+    @abstractmethod
+    def truncation_style(self) -> TruncationStyle:
+        """How to truncate content."""
+        ...
+
+    @abstractmethod
+    def process(self, output: str, tool_call: ToolCallLike | None = None) -> OffloadResult:
+        """Process tool output: truncate and optionally offload."""
+        ...
+
+
+# =============================================================================
+# Strategy Implementations
+# =============================================================================
+
+
+class ReadToolStrategy(OffloadStrategy):
+    """Strategy for Read tool output.
+
+    - Truncation: Head-focused (handled internally by read_tool.py)
+    - Offload: Never (source file already on filesystem)
+
+    This strategy is a pass-through since Read tool handles its own truncation.
+    """
+
+    @property
+    def offload_policy(self) -> OffloadPolicy:
+        return OffloadPolicy.NEVER
+
+    @property
+    def truncation_style(self) -> TruncationStyle:
+        return TruncationStyle.HEAD_ONLY
+
+    def process(self, output: str, tool_call: ToolCallLike | None = None) -> OffloadResult:
+        return OffloadResult(output=output, was_truncated=False, original_length=len(output))
+
+
+class HeadTailOffloadStrategy(OffloadStrategy):
+    """Strategy for Bash and generic tools.
+
+    - Truncation: Head + Tail (preserve both ends, errors often at end)
+    - Offload: Configurable (default: on threshold)
+    """
+
+    def __init__(
+        self,
+        max_length: int = TOOL_OUTPUT_MAX_LENGTH,
+        head_chars: int = TOOL_OUTPUT_DISPLAY_HEAD,
+        tail_chars: int = TOOL_OUTPUT_DISPLAY_TAIL,
+        max_lines: int = TOOL_OUTPUT_MAX_LINES,
+        head_lines: int = TOOL_OUTPUT_DISPLAY_HEAD_LINES,
+        tail_lines: int = TOOL_OUTPUT_DISPLAY_TAIL_LINES,
+        offload_dir: str | None = None,
+        policy: OffloadPolicy = OffloadPolicy.ON_THRESHOLD,
+    ):
+        self.max_length = max_length
+        self.head_chars = head_chars
+        self.tail_chars = tail_chars
+        self.max_lines = max_lines
+        self.head_lines = head_lines
+        self.tail_lines = tail_lines
+        self.offload_dir = Path(offload_dir or TOOL_OUTPUT_TRUNCATION_DIR)
+        self._policy = policy
+
+    @property
+    def offload_policy(self) -> OffloadPolicy:
+        return self._policy
+
+    @property
+    def truncation_style(self) -> TruncationStyle:
+        return TruncationStyle.HEAD_TAIL
+
+    def _save_to_file(self, output: str, tool_call: ToolCallLike | None) -> str | None:
+        """Save full output to file. Returns path or None on failure."""
+        try:
+            self.offload_dir.mkdir(parents=True, exist_ok=True)
+            tool_name = (tool_call.tool_name if tool_call else "unknown").replace("/", "_").lower()
+            random_hex = secrets.token_hex(8)
+            filename = f"klaude-{tool_name}-{random_hex}.log"
+            file_path = self.offload_dir / filename
+            file_path.write_text(output, encoding="utf-8")
+            return str(file_path)
+        except OSError:
+            return None
+
+    def _should_offload(self, needs_truncation: bool) -> bool:
+        """Determine if content should be offloaded based on policy."""
+        if self._policy == OffloadPolicy.NEVER:
+            return False
+        # ON_THRESHOLD: offload only when truncating
+        return needs_truncation
+
+    def _truncate_by_lines(self, output: str, lines: list[str], offloaded_path: str | None) -> tuple[str, int]:
+        """Truncate by lines. Returns (truncated_output, hidden_lines)."""
+        total_lines = len(lines)
+        hidden_lines = total_lines - self.head_lines - self.tail_lines
+        head = "\n".join(lines[: self.head_lines])
+        tail = "\n".join(lines[-self.tail_lines :])
+
+        if offloaded_path:
+            header = (
+                f"<system-reminder>Output truncated due to length. "
+                f"Showing first {self.head_lines} and last {self.tail_lines} lines of {total_lines} lines. "
+                f"Full output saved to: {offloaded_path} </system-reminder>\n\n"
+            )
+        else:
+            header = (
+                f"<system-reminder>Output truncated due to length. "
+                f"Showing first {self.head_lines} and last {self.tail_lines} lines of {total_lines} lines."
+                f"</system-reminder>\n\n"
+            )
+
+        truncated_output = f"{header}{head}\n\n<...{hidden_lines} lines omitted...>\n\n{tail}"
+        return truncated_output, hidden_lines
+
+    def _truncate_by_chars(self, output: str, offloaded_path: str | None) -> tuple[str, int]:
+        """Truncate by characters. Returns (truncated_output, hidden_chars)."""
+        original_length = len(output)
+        hidden_chars = original_length - self.head_chars - self.tail_chars
+        head = output[: self.head_chars]
+        tail = output[-self.tail_chars :]
+
+        if offloaded_path:
+            header = (
+                f"<system-reminder>Output truncated due to length. "
+                f"Showing first {self.head_chars} and last {self.tail_chars} chars of {original_length} chars. "
+                f"Full output saved to: {offloaded_path} </system-reminder>\n\n"
+            )
+        else:
+            header = (
+                f"<system-reminder>Output truncated due to length. "
+                f"Showing first {self.head_chars} and last {self.tail_chars} chars of {original_length} chars."
+                f"</system-reminder>\n\n"
+            )
+
+        truncated_output = f"{header}{head}\n\n<...{hidden_chars} chars omitted...>\n\n{tail}"
+        return truncated_output, hidden_chars
+
+    def process(self, output: str, tool_call: ToolCallLike | None = None) -> OffloadResult:
+        original_length = len(output)
+        lines = output.splitlines()
+        total_lines = len(lines)
+
+        # Check if truncation is needed (by lines or by chars)
+        needs_line_truncation = total_lines > self.max_lines
+        needs_char_truncation = original_length > self.max_length
+        needs_truncation = needs_line_truncation or needs_char_truncation
+
+        # No truncation needed
+        if not needs_truncation:
+            return OffloadResult(
+                output=output,
+                was_truncated=False,
+                original_length=original_length,
+            )
+
+        # Truncation needed - offload if policy allows
+        offloaded_path = None
+        if self._should_offload(needs_truncation):
+            offloaded_path = self._save_to_file(output, tool_call)
+
+        # Prefer line-based truncation if line limit exceeded
+        if needs_line_truncation:
+            truncated_output, hidden = self._truncate_by_lines(output, lines, offloaded_path)
+        else:
+            truncated_output, hidden = self._truncate_by_chars(output, offloaded_path)
+
+        return OffloadResult(
+            output=truncated_output,
+            was_truncated=True,
+            offloaded_path=offloaded_path,
+            original_length=original_length,
+            truncated_chars=hidden,
+        )
+
+
+# =============================================================================
+# Strategy Registry
+# =============================================================================
+
+_STRATEGY_REGISTRY: dict[str, OffloadStrategy] = {
+    tools.READ: ReadToolStrategy(),
+}
+
+_DEFAULT_STRATEGY = HeadTailOffloadStrategy()
+
+
+def get_strategy(tool_name: str | None) -> OffloadStrategy:
+    """Get the appropriate strategy for a tool."""
+    if tool_name and tool_name in _STRATEGY_REGISTRY:
+        return _STRATEGY_REGISTRY[tool_name]
+    return _DEFAULT_STRATEGY
+
+
+# =============================================================================
+# Public API
+# =============================================================================
+
+
+def offload_tool_output(output: str, tool_call: ToolCallLike | None = None) -> OffloadResult:
+    """Process tool output with appropriate offload/truncation strategy.
+
+    This is the main entry point. It selects the right strategy based on
+    the tool type and applies truncation/offload as needed.
+    """
+    tool_name = tool_call.tool_name if tool_call else None
+    strategy = get_strategy(tool_name)
+    return strategy.process(output, tool_call)

klaude_code/core/tool/shell/bash_tool.md

@@ -1,43 +1 @@
-Runs a shell command and returns its output.
-
-### Usage Notes
-- When searching for text or files, prefer using `rg`, `rg --files` or `fd` respectively because `rg` and `fd` is much faster than alternatives like `grep` and `find`. (If these command is not found, then use alternatives.)
-
-### Committing changes with git
-Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
-
-Git Safety Protocol:
-- NEVER update the git config
-- NEVER run destructive/irreversible git commands (like push --force, hard reset, etc) unless the user explicitly requests them 
-- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
-- NEVER run force push to main/master, warn the user if they request it
-- Avoid git commit --amend.  ONLY use --amend when either (1) user explicitly requested amend OR (2) adding edits from pre-commit hook (additional instructions below) 
-- Before amending: ALWAYS check authorship (git log -1 --format='%an %ae')
-- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
-
-1. You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, batch your tool calls together for optimal performance. run the following bash commands in parallel, each using the Bash tool:
-  - Run a git status command to see all untracked files.
-  - Run a git diff command to see both staged and unstaged changes that will be committed.
-  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
-2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
-  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
-  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
-  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
-  - Ensure it accurately reflects the changes and their purpose
-3. You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, batch your tool calls together for optimal performance. run the following commands in parallel:
-   - Add relevant untracked files to the staging area.
-   - Run git status to make sure the commit succeeded.
-4. If the commit fails due to pre-commit hook changes, retry the commit ONCE to include these automated changes. If it fails again, it usually means a pre-commit hook is preventing the commit. If the commit succeeds but you notice that files were modified by the pre-commit hook, you MUST amend your commit to include them.
-
-Important notes:
-- NEVER run additional commands to read or explore code, besides git bash commands
-- NEVER use the TodoWrite or Task tools
-- DO NOT push to the remote repository unless the user explicitly asks you to do so
-- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
-- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
-- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:<example>
-git commit -m "$(cat <<'EOF'
-   Commit message here.
-   EOF
-   )"
-</example>
+Runs a shell command and returns stdout and stderr.

klaude_code/core/tool/sub_agent_tool.py

@@ -111,6 +111,7 @@ class SubAgentTool(ToolABC):
                     generation=generation_dict,
                 ),
                 context.record_sub_agent_session_id,
+                context.register_sub_agent_metadata_getter,
             )
         except asyncio.CancelledError:
             raise

klaude_code/core/tool/todo/todo_write_tool.md

@@ -1,25 +1,2 @@
 Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
 It also helps the user understand the progress of the task and overall progress of their requests.
-
-#### When to Use This Tool
-Use this tool proactively in these scenarios:
-
-1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
-2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
-3. User explicitly requests todo list - When the user directly asks you to use the todo list
-4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
-5. After receiving new instructions - Immediately capture user requirements as todos
-6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
-7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
-
-#### When NOT to Use This Tool
-
-Skip using this tool when:
-1. There is only a single, straightforward task
-2. The task is trivial and tracking it provides no organizational benefit
-3. The task can be completed in less than 3 trivial steps
-4. The task is purely conversational or informational
-
-NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
-
-When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.

klaude_code/core/tool/tool_runner.py

@@ -4,9 +4,9 @@ from dataclasses import dataclass
 
 from klaude_code.const import CANCEL_OUTPUT
 from klaude_code.core.tool.context import ToolContext
+from klaude_code.core.tool.offload import offload_tool_output
 from klaude_code.core.tool.report_back_tool import ReportBackTool
 from klaude_code.core.tool.tool_abc import ToolABC, ToolConcurrencyPolicy
-from klaude_code.core.tool.truncation import truncate_tool_output
 from klaude_code.protocol import message, model, tools
 
 
@@ -52,14 +52,8 @@ async def run_tool(
         tool_result.call_id = tool_call.call_id
         tool_result.tool_name = tool_call.tool_name
         if tool_result.output_text:
-            truncation_result = truncate_tool_output(tool_result.output_text, tool_call)
-            tool_result.output_text = truncation_result.output
-            if truncation_result.was_truncated and truncation_result.saved_file_path:
-                tool_result.ui_extra = model.TruncationUIExtra(
-                    saved_file_path=truncation_result.saved_file_path,
-                    original_length=truncation_result.original_length,
-                    truncated_length=truncation_result.truncated_length,
-                )
+            offload_result = offload_tool_output(tool_result.output_text, tool_call)
+            tool_result.output_text = offload_result.output
         return tool_result
     except asyncio.CancelledError:
         # Propagate cooperative cancellation so outer layers can handle interrupts correctly.
@@ -126,6 +120,7 @@ class ToolExecutor:
         self._call_event_emitted: set[str] = set()
         self._concurrent_tasks: set[asyncio.Task[list[ToolExecutorEvent]]] = set()
         self._sub_agent_session_ids: dict[str, str] = {}
+        self._sub_agent_metadata_getters: dict[str, Callable[[], model.TaskMetadata | None]] = {}
 
     async def run_tools(self, tool_calls: list[ToolCallRequest]) -> AsyncGenerator[ToolExecutorEvent]:
         """Run the given tool calls and yield execution events.
@@ -219,12 +214,16 @@ class ToolExecutor:
         unfinished = list(self._unfinished_calls.items())
         for idx, (call_id, tool_call) in enumerate(unfinished):
             session_id = self._sub_agent_session_ids.get(call_id)
+            # Get partial metadata from sub-agent if available
+            metadata_getter = self._sub_agent_metadata_getters.get(call_id)
+            task_metadata = metadata_getter() if metadata_getter is not None else None
             cancel_result = message.ToolResultMessage(
                 call_id=tool_call.call_id,
                 output_text=CANCEL_OUTPUT,
                 status="aborted",
                 tool_name=tool_call.tool_name,
                 ui_extra=model.SessionIdUIExtra(session_id=session_id) if session_id else None,
+                task_metadata=task_metadata,
             )
 
             if call_id not in self._call_event_emitted:
@@ -242,6 +241,7 @@ class ToolExecutor:
             self._append_history([cancel_result])
             self._unfinished_calls.pop(call_id, None)
             self._sub_agent_session_ids.pop(call_id, None)
+            self._sub_agent_metadata_getters.pop(call_id, None)
 
         return events_to_yield
 
@@ -278,7 +278,11 @@ class ToolExecutor:
             if tool_call.call_id not in self._sub_agent_session_ids:
                 self._sub_agent_session_ids[tool_call.call_id] = session_id
 
+        def _register_metadata_getter(getter: Callable[[], model.TaskMetadata | None]) -> None:
+            self._sub_agent_metadata_getters[tool_call.call_id] = getter
+
         call_context = self._context.with_record_sub_agent_session_id(_record_sub_agent_session_id)
+        call_context = call_context.with_register_sub_agent_metadata_getter(_register_metadata_getter)
         tool_result: message.ToolResultMessage = await run_tool(tool_call, self._registry, call_context)
 
         self._append_history([tool_result])
@@ -287,6 +291,7 @@ class ToolExecutor:
 
         self._unfinished_calls.pop(tool_call.call_id, None)
         self._sub_agent_session_ids.pop(tool_call.call_id, None)
+        self._sub_agent_metadata_getters.pop(tool_call.call_id, None)
 
         extra_events = self._build_tool_side_effect_events(tool_result)
         return [result_event, *extra_events]

klaude_code/core/tool/web/web_fetch_tool.md

@@ -5,4 +5,4 @@ The tool automatically processes the response based on Content-Type:
 - JSON responses are formatted with indentation
 - Markdown and other text content is returned as-is
 
-Content is always saved to a local file. The file path is included at the start of the output in a `<file_saved>` tag. For large content that gets truncated, you can read the saved file directly.
+Content is always saved to a local file. The file path is shown at the start of the output in `[Web content saved to ...]` format. For large content that gets truncated, you can read the saved file directly.

klaude_code/core/tool/web/web_fetch_tool.py

@@ -1,7 +1,6 @@
 import asyncio
 import json
 import re
-import time
 import urllib.error
 import urllib.request
 from http.client import HTTPResponse
@@ -21,7 +20,7 @@ from klaude_code.core.tool.tool_abc import ToolABC, ToolConcurrencyPolicy, ToolM
 from klaude_code.core.tool.tool_registry import register
 from klaude_code.protocol import llm_param, message, tools
 
-WEB_FETCH_SAVE_DIR = Path(TOOL_OUTPUT_TRUNCATION_DIR) / "web"
+WEB_FETCH_SAVE_DIR = Path(TOOL_OUTPUT_TRUNCATION_DIR)
 
 
 def _encode_url(url: str) -> str:
@@ -29,7 +28,6 @@ def _encode_url(url: str) -> str:
     parsed = urlparse(url)
     encoded_path = quote(parsed.path, safe="/-_.~")
     encoded_query = quote(parsed.query, safe="=&-_.~")
-    # Handle IDN (Internationalized Domain Names) by encoding to punycode
     try:
         netloc = parsed.netloc.encode("idna").decode("ascii")
     except UnicodeError:
@@ -55,38 +53,30 @@ def _extract_content_type_and_charset(response: HTTPResponse) -> tuple[str, str
 
 def _detect_encoding(data: bytes, declared_charset: str | None) -> str:
     """Detect the encoding of the data."""
-    # 1. Use declared charset from HTTP header if available
     if declared_charset:
         return declared_charset
 
-    # 2. Try to detect from HTML meta tags (check first 2KB)
     head = data[:2048].lower()
-    # <meta charset="xxx">
     if match := re.search(rb'<meta[^>]+charset=["\']?([^"\'\s>]+)', head):
         return match.group(1).decode("ascii", errors="ignore")
-    # <meta http-equiv="Content-Type" content="text/html; charset=xxx">
     if match := re.search(rb'content=["\'][^"\']*charset=([^"\'\s;]+)', head):
         return match.group(1).decode("ascii", errors="ignore")
 
-    # 3. Use chardet for automatic detection
     import chardet
 
     result = chardet.detect(data)
     if result["encoding"] and result["confidence"] and result["confidence"] > 0.7:
         return result["encoding"]
 
-    # 4. Default to UTF-8
     return "utf-8"
 
 
 def _decode_content(data: bytes, declared_charset: str | None) -> str:
     """Decode bytes to string with automatic encoding detection."""
     encoding = _detect_encoding(data, declared_charset)
-
     try:
         return data.decode(encoding)
     except (UnicodeDecodeError, LookupError):
-        # Fallback: try UTF-8 with replacement for invalid chars
         return data.decode("utf-8", errors="replace")
 
 
@@ -117,29 +107,27 @@ def _extract_url_filename(url: str) -> str:
     return name[:URL_FILENAME_MAX_LENGTH] if len(name) > URL_FILENAME_MAX_LENGTH else name
 
 
-def _save_web_content(url: str, content: str, extension: str = ".md") -> str | None:
-    """Save web content to file. Returns file path or None on failure."""
+def _save_binary_content(url: str, data: bytes, extension: str = ".bin") -> str | None:
+    """Save binary content to file. Returns file path or None on failure."""
     try:
         WEB_FETCH_SAVE_DIR.mkdir(parents=True, exist_ok=True)
-        timestamp = int(time.time())
         identifier = _extract_url_filename(url)
-        filename = f"{identifier}-{timestamp}{extension}"
+        filename = f"klaude-webfetch-{identifier}{extension}"
         file_path = WEB_FETCH_SAVE_DIR / filename
-        file_path.write_text(content, encoding="utf-8")
+        file_path.write_bytes(data)
         return str(file_path)
     except OSError:
         return None
 
 
-def _save_binary_content(url: str, data: bytes, extension: str = ".bin") -> str | None:
-    """Save binary content to file. Returns file path or None on failure."""
+def _save_text_content(url: str, content: str) -> str | None:
+    """Save text content to file. Returns file path or None on failure."""
     try:
         WEB_FETCH_SAVE_DIR.mkdir(parents=True, exist_ok=True)
-        timestamp = int(time.time())
         identifier = _extract_url_filename(url)
-        filename = f"{identifier}-{timestamp}{extension}"
+        filename = f"klaude-webfetch-{identifier}.txt"
         file_path = WEB_FETCH_SAVE_DIR / filename
-        file_path.write_bytes(data)
+        file_path.write_text(content, encoding="utf-8")
         return str(file_path)
     except OSError:
         return None
@@ -164,15 +152,7 @@ def _process_content(content_type: str, text: str) -> str:
 
 
 def _fetch_url(url: str, timeout: int = WEB_FETCH_DEFAULT_TIMEOUT_SEC) -> tuple[str, bytes, str | None]:
-    """
-    Fetch URL content synchronously.
-
-    Returns:
-        Tuple of (content_type, raw_data, charset)
-
-    Raises:
-        Various exceptions on failure
-    """
+    """Fetch URL content synchronously."""
     headers = {
         "Accept": "text/markdown, */*",
         "User-Agent": WEB_FETCH_USER_AGENT,
@@ -229,7 +209,6 @@ class WebFetchTool(ToolABC):
         del context
         url = args.url
 
-        # Basic URL validation
         if not url.startswith(("http://", "https://")):
             return message.ToolResultMessage(
                 status="error",
@@ -239,7 +218,7 @@ class WebFetchTool(ToolABC):
         try:
             content_type, data, charset = await asyncio.to_thread(_fetch_url, url)
 
-            # Handle PDF files
+            # Handle PDF files - must save binary content
             if content_type == "application/pdf" or _is_pdf_url(url):
                 saved_path = _save_binary_content(url, data, ".pdf")
                 if saved_path:
@@ -252,15 +231,11 @@ class WebFetchTool(ToolABC):
                     output_text=f"Failed to save PDF file (url={url})",
                 )
 
-            # Handle text content
+            # Handle text content - save to file and return with path hint
             text = _decode_content(data, charset)
             processed = _process_content(content_type, text)
-
-            # Always save content to file
-            saved_path = _save_web_content(url, processed)
-
-            # Build output with file path info
-            output = f"<file_saved>{saved_path}</file_saved>\n\n{processed}" if saved_path else processed
+            saved_path = _save_text_content(url, processed)
+            output = f"[Web content saved to {saved_path}]\n\n{processed}" if saved_path else processed
 
             return message.ToolResultMessage(
                 status="success",