kward 0.67.1 → 0.68.0

data/lib/kward/tools/base.rb

@@ -1,8 +1,13 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Base class for model-callable tools and their JSON schemas.
     class Base
+      # @return [String] function name exposed to the model
       attr_reader :name
 
+      # Creates a tool schema definition shared by all concrete tool wrappers.
       def initialize(name, description, properties: {}, required: [])
         @name = name
         @description = description
@@ -10,6 +15,7 @@ module Kward
         @required = required
       end
 
+      # Returns the strict JSON schema advertised to model providers.
       def schema
         {
           type: "function",
@@ -28,6 +34,7 @@ module Kward
 
       private
 
+      # Reads a tool argument while accepting symbol or string keys from restored calls.
       def argument(args, key, default = nil)
         return args[key] if args.key?(key)
         return args[key.to_s] if args.key?(key.to_s)
@@ -35,6 +42,7 @@ module Kward
         default
       end
 
+      # Detects successful AGENTS.md writes so callers can refresh prompt context.
       def agents_file_changed?(workspace, path, result)
         result.to_s.start_with?("Wrote ", "Edited ") && File.basename(path.to_s) == "AGENTS.md" && workspace.resolved_path(path) == File.join(workspace.root.to_s, "AGENTS.md")
       rescue StandardError

data/lib/kward/tools/code_search.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Package lookup and GitHub repository cache/search implementation.
     class CodeSearch < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(code_search:)
         @code_search = code_search
         super(
@@ -56,6 +60,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         cancellation&.raise_if_cancelled!
         @code_search.call(args)

data/lib/kward/tools/edit_file.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for exact block replacement edits.
     class EditFile < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -28,6 +32,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, conversation, cancellation: nil)
         path = argument(args, :path, "")
         edits = argument(args, :edits, [])

data/lib/kward/tools/list_directory.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for listing workspace directory entries.
     class ListDirectory < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -13,6 +17,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         @workspace.list_directory(argument(args, :path, "."))
       end

data/lib/kward/tools/read_file.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for bounded workspace file reads.
     class ReadFile < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -17,6 +21,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, conversation, cancellation: nil)
         path = argument(args, :path, "")
         offset = argument(args, :offset)

data/lib/kward/tools/read_skill.rb

@@ -1,9 +1,13 @@
 require_relative "base"
 require_relative "../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for reading configured skill instructions.
     class ReadSkill < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize
         super(
           "read_skill",
@@ -16,6 +20,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         name = argument(args, :name, "")
         path = argument(args, :path)

data/lib/kward/tools/registry.rb

@@ -13,15 +13,42 @@ require_relative "search/web"
 require_relative "tool_call"
 require_relative "../workspace"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Exposes local workspace, search, skill, and interaction tools to the model
-  # and dispatches approved tool calls into the active conversation.
+  # and dispatches tool calls into the active conversation.
+  #
+  # `ToolRegistry` is the boundary between model-requested function calls and
+  # Ruby tool objects. It owns schema exposure and transcript persistence for
+  # tool results; individual tools own validation and side effects. Keep frontend
+  # policy outside this class by passing dependencies such as `workspace` and
+  # `prompt` from CLI or RPC setup.
+  #
+  # A tool may exist in `@tools` but not be advertised in `schemas`. This allows
+  # restored transcripts or compatibility callers to dispatch known tools while
+  # config and frontend capability checks decide what the model can request next.
+  #
+  # Tool schemas are the strict output contract advertised to models and clients.
+  # Incoming calls are intentionally more tolerant: extra fields are ignored by
+  # individual tools, and legacy-compatible shapes are accepted where already
+  # supported. Required fields and invalid required values should still return
+  # explicit tool errors.
   class ToolRegistry
     # Tool schemas advertised to the model for the current frontend and config.
     #
-    # @return [Array<Hash>]
+    # @return [Array<Hash>] tool schemas currently advertised to the model
     attr_reader :schemas
 
+    # Builds tool objects and the schema list for the current frontend/config.
+    #
+    # @param workspace [Workspace] filesystem/shell boundary used by local tools
+    # @param prompt [Object, nil] interactive prompt bridge; must implement
+    #   `ask_user_question` before that tool is advertised
+    # @param web_search [WebSearch] live web search implementation
+    # @param code_search [CodeSearch] public source/package search implementation
+    # @param web_search_enabled [Boolean, nil] override for web search exposure
+    # @param skills [Array<ConfigFiles::Skill>, nil] override discovered skills
+    # @param ask_user_question_enabled [Boolean, nil] override question exposure
     def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil)
       @workspace = workspace
       @prompt = prompt
@@ -37,6 +64,10 @@ module Kward
     # Executes a model-requested tool call and appends the result to the
     # conversation transcript.
     #
+    # Unknown tools are recorded as tool results instead of raising. That keeps
+    # the conversation valid for the model and lets the assistant recover by
+    # choosing an advertised tool on the next turn.
+    #
     # @param tool_call [Hash] model tool call payload
     # @param conversation [Conversation] active conversation
     # @return [String] tool output content appended to the conversation

data/lib/kward/tools/run_shell_command.rb

@@ -1,9 +1,13 @@
 require_relative "base"
 require_relative "../workspace"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for bounded shell commands in the workspace.
     class RunShellCommand < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -17,6 +21,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         command = argument(args, :command, "")
         timeout_seconds = argument(args, :timeout_seconds, Workspace::DEFAULT_COMMAND_TIMEOUT_SECONDS)

data/lib/kward/tools/search/code.rb

@@ -7,7 +7,9 @@ require "pathname"
 require "uri"
 require_relative "../../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Package lookup and GitHub repository cache/search implementation.
   class CodeSearch
     DEFAULT_MAX_RESULTS = 10
     MAX_MAX_RESULTS = 50
@@ -21,6 +23,7 @@ module Kward
     ECOSYSTEMS = %w[rubygems npm pypi crates go].freeze
     ACTIONS = %w[package_search github_search repo_clone repo_search repo_read list_cache refresh_cache clear_cache].freeze
 
+    # Creates an object for code search and repository cache operations.
     def initialize(cache_root: nil, http_client: NetHttpClient.new, git_runner: GitRunner.new, max_output_bytes: MAX_OUTPUT_BYTES)
       @cache_root = File.expand_path(cache_root || ConfigFiles.code_search_cache_dir)
       @http_client = http_client
@@ -46,6 +49,7 @@ module Kward
       "Error: code_search failed: #{redact(e.message)}"
     end
 
+    # HTTP adapter used by code search registry/package lookups.
     class NetHttpClient
       def get_json(url, headers: {})
         JSON.parse(get_text(url, headers: headers.merge("Accept" => "application/json")))
@@ -65,6 +69,7 @@ module Kward
       end
     end
 
+    # Git command adapter used by repository cache operations.
     class GitRunner
       def run(*args, chdir: nil)
         command = ["git", *args]
@@ -410,6 +415,7 @@ module Kward
       text[%r{https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\.git)?}]
     end
 
+    # Returns GitHub API headers, including an optional token when configured.
     def github_headers
       token = ENV["GITHUB_TOKEN"] || ENV["GH_TOKEN"]
       token.to_s.empty? ? {} : { "Authorization" => "Bearer #{token}" }
@@ -422,6 +428,7 @@ module Kward
       nil
     end
 
+    # Returns a cache file path relative to the cloned repository root.
     def relative_path(root, path)
       Pathname.new(path).relative_path_from(Pathname.new(root)).to_s
     end

data/lib/kward/tools/search/web.rb

@@ -5,7 +5,9 @@ require "nokogiri"
 require "uri"
 require_relative "../../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Live web-search implementation with provider fallbacks.
   class WebSearch
     DEFAULT_MAX_RESULTS = 5
     MAX_MAX_RESULTS = 20
@@ -27,11 +29,12 @@ module Kward
       "https://search.inetol.net",
       "https://searx.tiekoetter.com"
     ].freeze
-    PROVIDERS = %w[auto exa perplexity gemini legacy duckduckgo].freeze
+    PROVIDERS = %w[auto exa perplexity gemini duckduckgo].freeze
 
     Result = Struct.new(:title, :url, :excerpt, :provider, keyword_init: true)
     SearchResponse = Struct.new(:answer, :results, :provider, :note, keyword_init: true)
 
+    # Creates an object for web search provider operations.
     def initialize(http_client: NetHttpClient.new, searxng_instances: PUBLIC_SEARXNG_INSTANCES, max_output_bytes: MAX_OUTPUT_BYTES, config: nil)
       @http_client = http_client
       @searxng_instances = searxng_instances
@@ -92,8 +95,8 @@ module Kward
                        perplexity_search(query, options)
                      when "gemini"
                        gemini_search(query, options)
-                     when "legacy"
-                       legacy_search(query, options)
+                     when "duckduckgo"
+                       duckduckgo_provider_search(query, options)
                      end
           return [response, errors.empty? ? nil : errors.join("; ")] if successful_response?(response)
           errors << "#{provider}: no results"
@@ -105,6 +108,7 @@ module Kward
       [nil, errors.join("; ")]
     end
 
+    # Returns the configured provider fallback order for a query.
     def provider_order(provider)
       case provider
       when "auto"
@@ -113,10 +117,10 @@ module Kward
           order << "perplexity" if api_key("perplexity")
           order << "gemini" if api_key("gemini")
         end
-        order << "legacy"
+        order << "duckduckgo"
         order
       when "duckduckgo"
-        ["legacy"]
+        ["duckduckgo"]
       else
         [provider]
       end
@@ -352,15 +356,15 @@ module Kward
       SearchResponse.new(answer: answer, results: results, provider: "gemini")
     end
 
-    def legacy_search(query, options)
-      legacy_query = query_with_domain_filter(query, options[:domain_filter])
-      results, error = legacy_search_query(legacy_query, options[:max_results], options[:recency_filter])
+    def duckduckgo_provider_search(query, options)
+      duckduckgo_query = query_with_domain_filter(query, options[:domain_filter])
+      results, error = duckduckgo_provider_query(duckduckgo_query, options[:max_results], options[:recency_filter])
       raise error if results.empty? && error
 
-      SearchResponse.new(answer: "", results: results, provider: results.first&.provider || "legacy", note: error)
+      SearchResponse.new(answer: "", results: results, provider: results.first&.provider || "duckduckgo", note: error)
     end
 
-    def legacy_search_query(query, max_results, recency_filter)
+    def duckduckgo_provider_query(query, max_results, recency_filter)
       begin
         duckduckgo_results = duckduckgo_search(query, max_results, recency_filter)
         return [duckduckgo_results, nil] unless duckduckgo_results.empty?
@@ -576,6 +580,7 @@ module Kward
       text
     end
 
+    # Returns browser-like headers used for HTML search fallbacks.
     def browser_headers(accept)
       {
         "Accept" => accept,
@@ -604,19 +609,16 @@ module Kward
     end
 
     def web_config
-      value = config["web_search"] || config["webSearch"] || config["web_research"] || config["webResearch"] || {}
-      value.is_a?(Hash) ? value : {}
+      ConfigFiles.web_search_config(config)
     end
 
     def config_value(key)
       snake = key.to_s
       camel = snake.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
       prefixed = "web_search_#{snake}"
-      legacy_prefixed = "web_research_#{snake}"
       return web_config[snake] if web_config.key?(snake)
       return web_config[camel] if web_config.key?(camel)
       return config[prefixed] if config.key?(prefixed)
-      return config[legacy_prefixed] if config.key?(legacy_prefixed)
       return config[snake] if config.key?(snake)
       return config[camel] if config.key?(camel)
 
@@ -711,6 +713,7 @@ module Kward
       { "day" => "d", "week" => "w", "month" => "m", "year" => "y" }[filter]
     end
 
+    # HTTP adapter used by web-search providers and fallbacks.
     class NetHttpClient
       Response = Struct.new(:code, :body, keyword_init: true)
 

data/lib/kward/tools/tool_call.rb

@@ -1,6 +1,14 @@
 require "json"
+require_relative "../message_access"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Reads and normalizes model tool-call hashes.
+  #
+  # Tool calls arrive from several providers and may be restored from session
+  # files. This module keeps provider/string/symbol compatibility in one place
+  # and exposes small helpers used by the agent loop, tool registry, transcript
+  # formatters, and RPC event normalizers.
   module ToolCall
     TOOL_NAME_MAP = {
       "read_file" => "read",
@@ -8,6 +16,7 @@ module Kward
       "write_file" => "write",
       "run_shell_command" => "bash",
       "list_directory" => "list_directory",
+      "code_search" => "code_search",
       "web_search" => "web_search",
       "read_skill" => "read_skill",
       "ask_user_question" => "ask_user_question"
@@ -15,19 +24,27 @@ module Kward
 
     module_function
 
+    # @return [String, nil] provider tool-call id
     def id(tool_call)
       value(tool_call, :id)
     end
 
+    # @return [String, nil] requested tool/function name
     def name(tool_call)
       value(function(tool_call), :name)
     end
 
+    # Returns the short name used in compact UI labels.
+    #
+    # @return [String] display label such as `read`, `edit`, or `bash`
     def display_name(tool_call)
       raw_name = name(tool_call)
       normalized_name(raw_name) || raw_name || "unknown_tool"
     end
 
+    # Parses the requested tool arguments.
+    #
+    # @return [Hash] decoded argument object, or an empty hash for invalid JSON
     def arguments(tool_call)
       parse_arguments(raw_arguments(tool_call))
     end
@@ -44,6 +61,10 @@ module Kward
       TOOL_NAME_MAP[name.to_s]
     end
 
+    # Converts provider argument payloads into hashes.
+    #
+    # Providers normally send JSON strings, while tests and compatibility callers
+    # may pass hashes directly.
     def parse_arguments(arguments)
       return {} if arguments.nil? || (arguments.respond_to?(:empty?) && arguments.empty?)
       return arguments if arguments.is_a?(Hash)
@@ -53,6 +74,9 @@ module Kward
       {}
     end
 
+    # Recursively converts snake_case hash keys to camelCase symbols.
+    #
+    # @return [Hash] camelized copy of `args`
     def camelize_args(args)
       return {} unless args.is_a?(Hash)
 
@@ -62,11 +86,7 @@ module Kward
     end
 
     def value(object, key)
-      return nil unless object.respond_to?(:key?)
-      return object[key] if object.key?(key)
-      return object[key.to_s] if object.key?(key.to_s)
-
-      nil
+      MessageAccess.value(object, key)
     end
 
     def camelize_value(item)

data/lib/kward/tools/web_search.rb

@@ -1,8 +1,13 @@
 require_relative "base"
+require_relative "search/web"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Live web-search implementation with provider fallbacks.
     class WebSearch < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(web_search:)
         @web_search = web_search
         super(
@@ -22,7 +27,7 @@ module Kward
             },
             provider: {
               type: "string",
-              enum: %w[auto exa perplexity gemini legacy duckduckgo],
+              enum: Kward::WebSearch::PROVIDERS,
               description: "Provider override; default auto."
             },
             recency_filter: {
@@ -40,6 +45,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         @web_search.search(args)
       end

data/lib/kward/tools/write_file.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for guarded full-file writes.
     class WriteFile < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -16,6 +20,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, conversation, cancellation: nil)
         path = argument(args, :path, "")
         content = argument(args, :content, "")

data/lib/kward/transcript_export.rb

@@ -1,7 +1,9 @@
 require "cgi"
 require_relative "markdown_transcript"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Serializes conversations for transcript export formats.
   class TranscriptExport
     SUPPORTED_FORMATS = ["markdown", "html"].freeze
 

data/lib/kward/version.rb

@@ -1,4 +1,5 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Current gem version.
-  VERSION = "0.67.1"
+  VERSION = "0.68.0"
 end

data/lib/kward/workspace.rb

@@ -3,7 +3,19 @@ require "pathname"
 require "timeout"
 require_relative "session_diff"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Filesystem and shell-command boundary for workspace tools.
+  #
+  # `Workspace` is deliberately low-level: it validates paths, enforces output
+  # limits, applies exact edits, writes files, and runs shell commands from one
+  # root directory. It should not know about model prompts, sessions, telemetry,
+  # or UI confirmation. Tool wrappers and frontends provide those policies.
+  #
+  # Guardrails are enabled by default and require all file paths to resolve under
+  # `root`. RPC may report when guardrails are disabled, but callers should avoid
+  # bypassing this class for local filesystem mutation so read-before-write and
+  # path safety remain consistent.
   class Workspace
     MAX_FILE_BYTES = 256 * 1024
     MAX_READ_OUTPUT_BYTES = 50 * 1024
@@ -12,6 +24,7 @@ module Kward
     MAX_EDIT_DIFF_BYTES = 8 * 1024
     DEFAULT_COMMAND_TIMEOUT_SECONDS = 30
 
+    # Creates an object for workspace filesystem and shell operations.
     def initialize(root: Dir.pwd, max_file_bytes: MAX_FILE_BYTES, max_read_output_bytes: MAX_READ_OUTPUT_BYTES, max_read_output_lines: MAX_READ_OUTPUT_LINES, max_command_output_bytes: MAX_COMMAND_OUTPUT_BYTES, guardrails: true)
       @root = Pathname.new(root).realpath
       @guardrails = guardrails
@@ -21,8 +34,10 @@ module Kward
       @max_command_output_bytes = max_command_output_bytes
     end
 
+    # @return [Pathname] canonical workspace root used as the base for file and shell tools
     attr_reader :root
 
+    # Lists immediate directory children after resolving `path` through workspace guardrails.
     def list_directory(path)
       resolved = workspace_path(path)
       return "Error: not a directory: #{path}" unless File.directory?(resolved)
@@ -34,6 +49,11 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Reads a bounded text slice from a workspace file.
+    #
+    # The returned string is user/model-facing and includes continuation notices
+    # when output is truncated. Errors are returned as `"Error: ..."` strings so
+    # tool calls can be persisted in the conversation without raising.
     def read_file(path, offset: nil, limit: nil)
       resolved = workspace_path(path)
       return "Error: not a file: #{path}" unless File.file?(resolved)
@@ -41,11 +61,20 @@ module Kward
       size = File.size(resolved)
       return "Error: file too large: #{path} is #{size} bytes; limit is #{@max_file_bytes} bytes" if size > @max_file_bytes
 
-      read_file_slice(File.read(resolved), offset: offset, limit: limit)
+      content = File.read(resolved)
+      return "Error: not a text file: #{path}" if binary_content?(content)
+
+      read_file_slice(content, offset: offset, limit: limit)
     rescue SecurityError, Errno::ENOENT => e
       "Error: #{e.message}"
     end
 
+    # Writes complete file content after enforcing read-before-write for
+    # existing files.
+    #
+    # `read_paths` must contain resolved paths previously observed by
+    # `ReadFile`; this keeps tool-driven edits explicit and prevents overwriting
+    # unseen user files.
     def write_file(path, content, read_paths:)
       resolved = workspace_write_path(path)
 
@@ -53,10 +82,6 @@ module Kward
         return "Error: existing file must be read before writing: #{path}"
       end
 
-      if block_given? && !yield(relative_path(resolved), content.bytesize)
-        return "Declined: write_file was not approved for #{path}"
-      end
-
       old_content = File.exist?(resolved) ? File.read(resolved) : nil
       File.write(resolved, content)
       output = "Wrote #{content.bytesize} bytes to #{path}"
@@ -66,6 +91,11 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Applies exact non-overlapping replacements to a previously read file.
+    #
+    # Each `old_text` must match exactly once. This favors predictable model edits
+    # over fuzzy patching and returns readable error strings when more context is
+    # needed.
     def edit_file(path, edits, read_paths:)
       resolved = workspace_path(path)
       return "Error: not a file: #{path}" unless File.file?(resolved)
@@ -84,6 +114,11 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Runs a shell command from the workspace root with timeout, cancellation,
+    # and bounded combined output.
+    #
+    # This method intentionally does not ask for confirmation; CLI/RPC policy
+    # must decide whether a command is allowed before reaching this boundary.
     def run_shell_command(command, timeout_seconds: DEFAULT_COMMAND_TIMEOUT_SECONDS, cancellation: nil)
       command = command.to_s.strip
       return "Error: command is required" if command.empty?
@@ -114,6 +149,7 @@ module Kward
       "Error: #{e.message}"
     end
 
+    # Resolves a path with the same guardrails used by file tools.
     def resolved_path(path)
       workspace_path(path)
     end
@@ -189,6 +225,10 @@ module Kward
       output
     end
 
+    def binary_content?(content)
+      content.include?("\x00")
+    end
+
     def read_start_index(offset)
       return 0 if offset.nil?