kward 0.74.0 → 0.75.0

data/lib/kward/tools/registry.rb

@@ -1,5 +1,6 @@
 require_relative "../config_files"
 require_relative "../conversation"
+require_relative "../hooks"
 require_relative "ask_user_question"
 require_relative "code_search"
 require_relative "context_budget_stats"
@@ -62,7 +63,7 @@ module Kward
     # @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, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, allowed_tool_names: nil, write_lock: nil, writer_id: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil)
+    def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil, allowed_tool_names: nil, write_lock: nil, writer_id: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, hook_manager: nil, hook_context: nil)
       @workspace = workspace
       @prompt = prompt
       @web_search = web_search
@@ -77,6 +78,9 @@ module Kward
       @tool_output_compactor = tool_output_compactor
       @telemetry_logger = telemetry_logger
       @context_budget_meter = context_budget_meter
+      @tool_approval = tool_approval
+      @hook_manager = hook_manager
+      @hook_context = hook_context
       @mcp_clients = if mcp_clients
                        mcp_clients
                      elsif @allowed_tool_names
@@ -85,7 +89,7 @@ module Kward
                        MCP::ServerConfig.clients_from_config(ConfigFiles.read_config)
                      end
       @tools = build_tools.freeze
-      @schemas = build_schema_tools.map(&:schema).freeze
+      @schemas = build_schema_tools.map { |tool| schema_with_metadata(tool) }.freeze
     end
 
     # Executes a model-requested tool call and appends the result to the
@@ -105,10 +109,18 @@ module Kward
       tool = @tools[name]
 
       original_content = if tool
-                           if mutation_tool?(name) && !write_lock_owned?
+                           before_tool = run_hook("tool_call_before", conversation, payload: tool_payload(name, args, tool_call))
+                           args = hook_arguments(before_tool, args)
+                           if before_tool.denied?
+                             hook_denied_content(before_tool, "tool call denied: #{name}")
+                           elsif before_tool.approval_required? && hook_approval_denied?(before_tool, tool_call, name, args, cancellation)
+                             hook_denied_content(before_tool, "tool call approval denied: #{name}")
+                           elsif mutation_tool?(name) && !write_lock_owned?
                              "Workspace write denied: another worker owns the write lock."
+                           elsif tool_approval_denied?(tool_call, name, args, cancellation)
+                             "Declined: tool execution denied by user: #{name}"
                            else
-                             tool.call(args, conversation, cancellation: cancellation)
+                             execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
                            end
                          else
                            "Unknown tool: #{name}"
@@ -121,7 +133,7 @@ module Kward
       end
 
       artifact_id = nil
-      model_content = @tool_output_compactor.compact(name, content) do
+      model_content = compact_tool_output(name, content, original_content, conversation) do
         artifact_id ||= conversation.store_tool_output_artifact(tool_name: name, content: original_content)
       end
       record_context_budget(conversation, name, before: original_content, after: model_content)
@@ -136,8 +148,73 @@ module Kward
       model_content
     end
 
+    def metadata_for(name)
+      tool = @tools[name.to_s]
+      return unknown_tool_metadata(name) unless tool
+
+      tool_metadata(tool)
+    end
+
     private
 
+    def schema_with_metadata(tool)
+      tool.schema.merge(metadata: tool_metadata(tool))
+    end
+
+    def tool_metadata(tool)
+      if tool.is_a?(Tools::MCPTool)
+        {
+          source: "mcp",
+          displayName: tool.display_name,
+          serverName: tool.server_name,
+          remoteName: tool.remote_name
+        }
+      else
+        {
+          source: source_for_tool(tool),
+          displayName: tool.name
+        }
+      end
+    end
+
+    def source_for_tool(tool)
+      case tool
+      when Tools::WebSearch, Tools::FetchContent, Tools::FetchRaw
+        "web"
+      when Tools::ReadSkill
+        "skill"
+      when Tools::AskUserQuestion
+        "ui"
+      else
+        "builtin"
+      end
+    end
+
+    def unknown_tool_metadata(name)
+      {
+        source: "unknown",
+        displayName: name.to_s
+      }
+    end
+
+    def compact_tool_output(name, content, original_content, conversation, &store_artifact)
+      before = run_hook("tool_output_compact_before", conversation, payload: {
+        tool_name: name,
+        bytes: content.bytesize,
+        duplicate: content != original_content
+      })
+      return content if before.denied? || before.approval_required?
+
+      compacted = @tool_output_compactor.compact(name, content, &store_artifact)
+      run_hook("tool_output_compact_after", conversation, payload: {
+        tool_name: name,
+        bytes_before: content.bytesize,
+        bytes_after: compacted.bytesize,
+        compacted: compacted != content
+      }) if compacted != content
+      compacted
+    end
+
     def record_context_budget(conversation, name, before:, after:)
       meter = conversation.respond_to?(:context_budget_meter) ? conversation.context_budget_meter : @context_budget_meter
       return unless meter
@@ -170,10 +247,184 @@ module Kward
       )
     end
 
+    def execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
+      args = run_shell_before_hooks(name, args, tool_call, conversation, cancellation)
+      run_file_change_before_hooks(name, args, tool_call, conversation, cancellation)
+      run_mcp_before_hooks(name, args, tool_call, conversation, cancellation)
+      content = tool.call(args, conversation, cancellation: cancellation)
+      run_mcp_after_hooks(name, args, content, conversation)
+      run_shell_after_hooks(name, args, content, conversation)
+      run_file_change_after_hooks(name, args, content, conversation)
+      run_hook("tool_call_after", conversation, payload: tool_payload(name, args, tool_call).merge(content: content.to_s))
+      content
+    rescue HookDenied => e
+      e.message
+    rescue StandardError => e
+      run_mcp_error_hooks(name, args, e, conversation)
+      run_hook("tool_call_error", conversation, payload: tool_payload(name, args, tool_call).merge(error: e.message))
+      raise
+    end
+
+    def run_mcp_before_hooks(name, args, tool_call, conversation, cancellation)
+      return unless mcp_tool?(name)
+
+      result = run_hook("mcp_tool_before", conversation, payload: mcp_payload(name, args))
+      if result.denied?
+        raise HookDenied, hook_denied_content(result, "MCP tool denied")
+      end
+      if result.approval_required? && hook_approval_denied?(result, tool_call, name, args, cancellation)
+        raise HookDenied, hook_denied_content(result, "MCP tool approval denied")
+      end
+    end
+
+    def run_mcp_after_hooks(name, args, content, conversation)
+      return unless mcp_tool?(name)
+
+      run_hook("mcp_tool_after", conversation, payload: mcp_payload(name, args).merge(content: content.to_s))
+    end
+
+    def run_mcp_error_hooks(name, args, error, conversation)
+      return unless mcp_tool?(name)
+
+      run_hook("mcp_tool_error", conversation, payload: mcp_payload(name, args).merge(error: error.message))
+    end
+
+    def run_shell_before_hooks(name, args, tool_call, conversation, cancellation)
+      return args unless name.to_s == "run_shell_command"
+
+      result = run_hook("shell_command_before", conversation, payload: shell_payload(args))
+      if result.denied?
+        raise HookDenied, hook_denied_content(result, "shell command denied")
+      end
+      if result.approval_required? && hook_approval_denied?(result, tool_call, name, args, cancellation)
+        raise HookDenied, hook_denied_content(result, "shell command approval denied")
+      end
+      shell_arguments(result.payload, args)
+    end
+
+    def run_shell_after_hooks(name, args, content, conversation)
+      return unless name.to_s == "run_shell_command"
+
+      run_hook("shell_command_after", conversation, payload: shell_payload(args).merge(content: content.to_s))
+    end
+
+    def run_file_change_before_hooks(name, args, tool_call, conversation, cancellation)
+      return unless ToolCall.file_change_tool?(name)
+
+      result = run_hook("file_change_before", conversation, payload: file_change_payload(name, args))
+      if result.denied?
+        raise HookDenied, hook_denied_content(result, "file change denied")
+      end
+      if result.approval_required? && hook_approval_denied?(result, tool_call, name, args, cancellation)
+        raise HookDenied, hook_denied_content(result, "file change approval denied")
+      end
+    end
+
+    def run_file_change_after_hooks(name, args, content, conversation)
+      return unless ToolCall.file_change_tool?(name)
+      return unless content.to_s.start_with?("Wrote ", "Edited ")
+
+      run_hook("file_change_after", conversation, payload: file_change_payload(name, args).merge(content: content.to_s))
+    end
+
+    HookDenied = Class.new(StandardError)
+
+    def run_hook(name, conversation, payload: {})
+      return Hooks::Manager::Result.new(event: nil, decision: Hooks::Decision.allow, decisions: [], warnings: [], messages: [], payload: payload) unless @hook_manager
+
+      @hook_manager.run(Hooks::Event.new(
+        name: name,
+        workspace: { root: @workspace.respond_to?(:root) ? @workspace.root.to_s : nil },
+        payload: payload
+      ), context: @hook_context || default_hook_context(conversation))
+    end
+
+    def default_hook_context(conversation)
+      return nil unless defined?(PluginRegistry::Context)
+
+      PluginRegistry::Context.new(conversation: conversation, workspace_root: @workspace.respond_to?(:root) ? @workspace.root.to_s : Dir.pwd)
+    end
+
+    def tool_payload(name, args, tool_call)
+      metadata = metadata_for(name)
+      {
+        tool_name: name,
+        arguments: args,
+        tool_call_id: tool_call["id"] || tool_call[:id],
+        source: metadata[:source] || metadata["source"],
+        server_name: metadata[:serverName] || metadata["serverName"],
+        remote_name: metadata[:remoteName] || metadata["remoteName"]
+      }.compact
+    end
+
+    def hook_arguments(result, fallback)
+      payload_arguments = result.payload[:arguments] || result.payload["arguments"]
+      payload_arguments.is_a?(Hash) ? payload_arguments : fallback
+    end
+
+    def mcp_payload(name, args)
+      tool_payload(name, args, {}).slice(:tool_name, :arguments, :source, :server_name, :remote_name)
+    end
+
+    def shell_payload(args)
+      {
+        tool_name: "run_shell_command",
+        command: args[:command] || args["command"],
+        timeout_seconds: args[:timeout_seconds] || args["timeout_seconds"] || Workspace::DEFAULT_COMMAND_TIMEOUT_SECONDS,
+        cwd: @workspace.respond_to?(:root) ? @workspace.root.to_s : nil
+      }.compact
+    end
+
+    def file_change_payload(name, args)
+      operation = name.to_s.start_with?("edit") ? "edit" : "write"
+      path = args[:path] || args["path"]
+      payload = {
+        tool_name: name,
+        operation: operation,
+        path: path,
+        files: [{ path: path, operation: operation }]
+      }
+      if operation == "edit"
+        payload[:edits] = args[:edits] || args["edits"]
+      else
+        payload[:content] = args[:content] || args["content"]
+      end
+      payload.compact
+    end
+
+    def shell_arguments(payload, fallback)
+      fallback.merge(
+        command: payload[:command] || payload["command"] || fallback[:command] || fallback["command"],
+        timeout_seconds: payload[:timeout_seconds] || payload["timeout_seconds"] || fallback[:timeout_seconds] || fallback["timeout_seconds"]
+      )
+    end
+
+    def hook_denied_content(result, fallback)
+      "Declined: #{result.decision.message || fallback}"
+    end
+
+    def hook_approval_denied?(result, tool_call, name, args, cancellation)
+      return true unless @tool_approval
+
+      approval_args = args.merge("hook_message" => result.decision.message)
+      @tool_approval.call(tool_call: tool_call, name: name, args: approval_args, cancellation: cancellation) == false
+    end
+
+    def mcp_tool?(name)
+      metadata = metadata_for(name)
+      (metadata[:source] || metadata["source"]).to_s == "mcp"
+    end
+
     def mutation_tool?(name)
       ToolCall.write_lock_required?(name)
     end
 
+    def tool_approval_denied?(tool_call, name, args, cancellation)
+      return false unless @tool_approval
+
+      @tool_approval.call(tool_call: tool_call, name: name, args: args, cancellation: cancellation) == false
+    end
+
     def write_lock_owned?
       return true unless @write_lock
 
@@ -202,7 +453,7 @@ module Kward
         Tools::WebSearch.new(web_search: @web_search),
         Tools::FetchContent.new(web_fetch: @web_fetch),
         Tools::FetchRaw.new(web_fetch: @web_fetch),
-        Tools::ReadSkill.new,
+        Tools::ReadSkill.new(skills: discovered_skills),
         Tools::AskUserQuestion.new(prompt: @prompt)
       ] + mcp_tool_values
     end
@@ -229,9 +480,16 @@ module Kward
       true
     end
 
+    def discovered_skills(workspace_root: nil)
+      return @skills unless @skills.nil?
+
+      @discovered_skills ||= {}
+      root = workspace_root || (@workspace.respond_to?(:root) ? @workspace.root : Dir.pwd)
+      @discovered_skills[root] ||= ConfigFiles.skills(workspace_root: root)
+    end
+
     def skills_available?
-      skills = @skills.nil? ? ConfigFiles.skills : @skills
-      skills.any?
+      discovered_skills.any?
     end
 
     def mcp_tool_values

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

@@ -5,7 +5,9 @@ require "net/http"
 require "open3"
 require "pathname"
 require "uri"
+require_relative "../../path_guard"
 require_relative "../../config_files"
+require_relative "web"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -24,7 +26,7 @@ module Kward
     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)
+    def initialize(cache_root: nil, http_client: WebSearch::NetHttpClient.new(user_agent: "Kward code_search"), 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
       @git_runner = git_runner
@@ -49,26 +51,6 @@ 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")))
-      end
-
-      def get_text(url, headers: {})
-        uri = URI(url)
-        request = Net::HTTP::Get.new(uri)
-        request["User-Agent"] = "Kward code_search"
-        headers.each { |key, val| request[key] = val }
-        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: HTTP_TIMEOUT_SECONDS, read_timeout: HTTP_TIMEOUT_SECONDS) do |http|
-          http.request(request)
-        end
-        raise "HTTP #{response.code} from #{uri.host}" unless response.is_a?(Net::HTTPSuccess)
-
-        response.body
-      end
-    end
-
     # Git command adapter used by repository cache operations.
     class GitRunner
       def run(*args, chdir: nil)
@@ -376,7 +358,7 @@ module Kward
     end
 
     def inside_root?(root, path)
-      path == root || path.start_with?(root + File::SEPARATOR)
+      PathGuard.inside?(path, root)
     end
 
     def inside_cache?(path)

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

@@ -54,7 +54,10 @@ module Kward
       return "Error: queries must be an array with 1-#{MAX_QUERIES} strings" unless valid_queries?(queries)
 
       max_results = bounded_max_results(args_value(args, "max_results") || args_value(args, "num_results"))
-      provider = normalize_provider(args_value(args, "provider") || config_value("provider") || "auto")
+      provider_value = args_value(args, "provider")
+      provider_value = config_value("provider") if provider_value.nil?
+      provider_value = "auto" if provider_value.nil? || provider_value.to_s.empty?
+      provider = normalize_provider(provider_value)
       return "Error: provider must be one of: #{PROVIDERS.join(", ")}" unless provider
 
       options = {
@@ -549,8 +552,10 @@ module Kward
 
     def args_value(args, key)
       return nil unless args.is_a?(Hash)
+      return args[key] if args.key?(key)
+      return args[key.to_sym] if args.key?(key.to_sym)
 
-      args[key] || args[key.to_sym]
+      nil
     end
 
     def success?(response)
@@ -717,10 +722,26 @@ module Kward
     class NetHttpClient
       Response = Struct.new(:code, :body, :headers, keyword_init: true)
 
+      def initialize(user_agent: nil)
+        @user_agent = user_agent
+      end
+
       def get(url, headers: {})
         request(url, Net::HTTP::Get, headers: headers)
       end
 
+      def get_json(url, headers: {})
+        JSON.parse(get_text(url, headers: headers.merge("Accept" => "application/json")))
+      end
+
+      def get_text(url, headers: {})
+        uri = URI.parse(url)
+        response = get(uri.to_s, headers: headers)
+        raise "HTTP #{response.code} from #{uri.host}" unless success?(response.code)
+
+        response.body
+      end
+
       def post(url, form:, headers: {})
         request(url, Net::HTTP::Post, headers: headers) do |http_request|
           http_request.set_form_data(form)
@@ -739,12 +760,17 @@ module Kward
         uri = URI.parse(url)
         Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: HTTP_TIMEOUT_SECONDS, read_timeout: HTTP_TIMEOUT_SECONDS) do |http|
           http_request = request_class.new(uri)
+          http_request["User-Agent"] = @user_agent if @user_agent
           headers.each { |key, value| http_request[key] = value }
           yield http_request if block_given?
           response = http.request(http_request)
           Response.new(code: response.code, body: response.body, headers: response.each_header.to_h)
         end
       end
+
+      def success?(code)
+        code.to_i.between?(200, 299)
+      end
     end
   end
 end

data/lib/kward/update_check.rb

@@ -0,0 +1,117 @@
+require "fileutils"
+require "json"
+require "net/http"
+require "time"
+require "uri"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Cached RubyGems update check for the interactive startup screen.
+  class UpdateCheck
+    CHECK_INTERVAL_SECONDS = 24 * 60 * 60
+    LATEST_VERSION_URL = URI("https://rubygems.org/api/v1/versions/kward/latest.json")
+
+    Notice = Struct.new(:latest_version, keyword_init: true)
+
+    def initialize(current_version:, config: ConfigFiles.read_config, path: ConfigFiles.update_check_cache_path, now: Time.now)
+      @current_version = current_version.to_s
+      @config = config
+      @path = path
+      @now = now
+    end
+
+    def enabled?
+      return false if disabled_by_environment?
+
+      updates = @config["updates"]
+      return false if updates.is_a?(Hash) && updates["check"] == false
+
+      true
+    end
+
+    def notice
+      return nil unless enabled?
+
+      latest_version = cache["latest_version"].to_s
+      return nil if latest_version.empty?
+      return nil if dismissed_version == latest_version
+      return nil unless newer_than_current?(latest_version)
+
+      Notice.new(latest_version: latest_version)
+    end
+
+    def refresh_if_stale
+      return false unless enabled?
+      return false unless stale?
+
+      refresh
+    end
+
+    def refresh
+      latest_version = fetch_latest_version
+      write_cache(cache.merge(
+        "checked_at" => @now.utc.iso8601,
+        "latest_version" => latest_version
+      ))
+      true
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def disabled_by_environment?
+      value = ENV["KWARD_DISABLE_UPDATE_CHECK"].to_s.strip.downcase
+      ["1", "true", "yes", "on"].include?(value)
+    end
+
+    def dismissed_version
+      cache["dismissed_version"].to_s
+    end
+
+    def stale?
+      checked_at = Time.iso8601(cache["checked_at"].to_s)
+      (@now - checked_at) >= CHECK_INTERVAL_SECONDS
+    rescue ArgumentError, TypeError
+      true
+    end
+
+    def cache
+      @cache ||= read_cache
+    end
+
+    def read_cache
+      return {} unless File.file?(@path)
+
+      data = JSON.parse(File.read(@path))
+      data.is_a?(Hash) ? data : {}
+    rescue JSON::ParserError, SystemCallError
+      {}
+    end
+
+    def write_cache(data)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, JSON.pretty_generate(data) + "\n")
+      @cache = data
+    end
+
+    def fetch_latest_version
+      request = Net::HTTP::Get.new(LATEST_VERSION_URL)
+      request["User-Agent"] = "kward/#{Kward::VERSION}"
+      response = Net::HTTP.start(LATEST_VERSION_URL.hostname, LATEST_VERSION_URL.port, use_ssl: true, open_timeout: 2, read_timeout: 2) do |http|
+        http.request(request)
+      end
+      return "" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)["version"].to_s
+    rescue JSON::ParserError
+      ""
+    end
+
+    def newer_than_current?(version)
+      Gem::Version.new(version) > Gem::Version.new(@current_version)
+    rescue ArgumentError
+      false
+    end
+  end
+end

data/lib/kward/version.rb

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