Implement Smart Binary File Handling in read_file Tool

[marutilai]

Issue Description:

Currently, the read_file tool attempts to read all files as plain text. When the agent tries to read a binary file (e.g., an image, executable, or compressed file), this results in one of two failure modes:

1. A UnicodeDecodeError if the file contains byte sequences that are not valid UTF-8.
2. A stream of garbled, non-human-readable text being sent to the LLM, which can cause confusion, hallucinations, and wasted context window space.

This issue proposes upgrading read_file to intelligently detect binary files and handle them gracefully, preventing errors and providing a clear signal to the agent about the file's nature.

Action Items:

1. Add Binary Detection Library:

   • The project needs a reliable way to determine if a file is binary or text. The isbinary library is a good lightweight option.
     • Add isbinary to the project’s dependencies (e.g., in pyproject.toml).

2. Integrate Detection into read_file:

   • File: src/katalyst/coding_agent/tools/read_file.py
   • After validating that the file path exists, but before attempting to open and read it, the tool must use the binary detection library to check the file type.

     from isbinary import is_binary
     if is_binary(abs_path): ...

3. Implement Graceful Handling Logic:

   • If is_binary(abs_path) returns True, the tool should not attempt to read the file content.
   • Instead, it should immediately return a structured JSON response indicating that the file is binary.

4. Define the JSON Output for Binary Files:

   • The JSON response must be consistent with the tool’s existing output format but should omit the content field.
   • It must include a new info field with a clear message.
   • Example JSON output for a binary file:

     {
       "path": "/path/to/image.png",
       "content": "",
       "info": "[Binary file, content not displayed]"
     }

Developer Notes:

• This check should be one of the first things the tool does after path validation to prevent unnecessary processing.
• The error/info message returned to the LLM should be clear and unambiguous so it understands why it did not receive content and can adjust its plan accordingly.