kward 0.74.0 → 0.75.0

data/lib/kward/config_files.rb

@@ -2,9 +2,12 @@ require "digest"
 require "fileutils"
 require "json"
 require "yaml"
+require_relative "frontmatter"
 require_relative "private_file"
+require_relative "path_guard"
 require_relative "ekwsh"
 require_relative "editor_mode"
+require_relative "diff_view_mode"
 require_relative "prompts/templates"
 require_relative "skills/registry"
 
@@ -41,7 +44,7 @@ module Kward
         {
           "key" => "kward",
           "label" => "Kward",
-          "instruction" => "Your name is Kward, the grim Andruid - robotic keeper of the Forrest of Code, protecting the nature of good engineering priciples. Speak like an old druid, be suspicous of everyone, but with a good intend."
+          "instruction" => "Your name is Kward, the grim Andruid - robotic keeper of the Forest of Code, protecting the nature of good engineering principles. Speak like an old druid, be suspicious of everyone, but with good intent."
         }
       ],
       "default" => "kward"
@@ -49,7 +52,7 @@ module Kward
     OVERLAY_ALIGNMENTS = %w[left center right].freeze
     OVERLAY_WIDTHS = %w[capped maximum].freeze
 
-    Skill = Struct.new(:name, :description, :folder, :path, keyword_init: true)
+    Skill = Struct.new(:name, :description, :folder, :path, :license, :compatibility, :metadata, :allowed_tools, keyword_init: true)
     PromptTemplate = Struct.new(:command, :description, :argument_hint, :body, :path, keyword_init: true) do
       def expand(arguments)
         body.gsub("$ARGUMENTS", arguments.to_s)
@@ -92,6 +95,14 @@ module Kward
       File.join(config_dir, "ekwsh.yml")
     end
 
+    def workspace_hooks_path(root = Dir.pwd)
+      File.join(File.expand_path(root), ".kward", "hooks.json")
+    end
+
+    def trusted_workspace_hooks_path
+      File.join(config_dir, "trusted_workspace_hooks.json")
+    end
+
     def default_config
       {
         "personas" => JSON.parse(JSON.generate(DEFAULT_PERSONAS)),
@@ -109,11 +120,21 @@ module Kward
           "auto_close_pairs" => true,
           "soft_wrap" => true,
           "bar_cursor" => true,
-          "line_numbers" => "absolute"
+          "line_numbers" => "absolute",
+          "diff_view" => "auto"
+        },
+        "overlay" => DEFAULT_OVERLAY_SETTINGS.dup,
+        "web_search" => {
+          "enabled" => true,
+          "provider" => "auto",
+          "allow_model_providers" => false
         },
         "sessions" => {
           "auto_resume" => false
         },
+        "skills" => {
+          "trust_project" => false
+        },
         "enforce_workspace_agents_file" => false,
         "mcpServers" => {},
         "tools" => {
@@ -140,6 +161,10 @@ module Kward
       File.join(cache_dir, "openrouter_models.json")
     end
 
+    def update_check_cache_path
+      File.join(cache_dir, "update_check.json")
+    end
+
     def project_browser_state_path
       File.join(cache_dir, "project_browser_state.json")
     end
@@ -198,6 +223,72 @@ module Kward
       PrivateFile.write_json(path, config)
     end
 
+    def lifecycle_hooks_config(workspace_root = Dir.pwd)
+      config = read_config
+      workspace_config = read_trusted_workspace_hooks_config(workspace_root)
+      return config if workspace_config.empty?
+
+      merge_hooks_config(config, workspace_config)
+    end
+
+    def read_trusted_workspace_hooks_config(workspace_root = Dir.pwd)
+      path = workspace_hooks_path(workspace_root)
+      return {} unless workspace_hooks_trusted?(workspace_root)
+
+      read_config(path)
+    end
+
+    def workspace_hooks_trusted?(workspace_root = Dir.pwd)
+      path = workspace_hooks_path(workspace_root)
+      return false unless File.file?(path)
+
+      trusted = read_trusted_workspace_hooks
+      trusted[File.expand_path(path)] == workspace_hooks_digest(workspace_root)
+    end
+
+    def trust_workspace_hooks!(workspace_root = Dir.pwd)
+      path = workspace_hooks_path(workspace_root)
+      raise "No workspace hook config found: #{path}" unless File.file?(path)
+
+      trusted = read_trusted_workspace_hooks
+      trusted[File.expand_path(path)] = workspace_hooks_digest(workspace_root)
+      PrivateFile.write_json(trusted_workspace_hooks_path, trusted)
+    end
+
+    def untrust_workspace_hooks!(workspace_root = Dir.pwd)
+      path = File.expand_path(workspace_hooks_path(workspace_root))
+      trusted = read_trusted_workspace_hooks
+      trusted.delete(path)
+      PrivateFile.write_json(trusted_workspace_hooks_path, trusted)
+    end
+
+    def workspace_hooks_digest(workspace_root = Dir.pwd)
+      Digest::SHA256.file(workspace_hooks_path(workspace_root)).hexdigest
+    end
+
+    def read_trusted_workspace_hooks
+      config = read_config(trusted_workspace_hooks_path)
+      config.is_a?(Hash) ? config : {}
+    rescue ConfigError
+      {}
+    end
+
+    def merge_hooks_config(config, workspace_config)
+      merged = JSON.parse(JSON.generate(config || {}))
+      merged["hooks"] = merge_hook_maps(merged["hooks"], workspace_config["hooks"] || workspace_config[:hooks])
+      merged
+    end
+
+    def merge_hook_maps(left, right)
+      left = left.is_a?(Hash) ? left : {}
+      right = right.is_a?(Hash) ? right : {}
+      merged = JSON.parse(JSON.generate(left))
+      right.each do |event, entries|
+        merged[event.to_s] = Array(merged[event.to_s]) + Array(entries)
+      end
+      merged
+    end
+
     def read_ekwsh_config(path = ekwsh_config_path)
       path = File.expand_path(path)
       return normalize_ekwsh_config(nil) unless File.exist?(path)
@@ -364,12 +455,24 @@ module Kward
       EditorMode.normalize_line_numbers(editor["line_numbers"])
     end
 
+    # Returns the integrated diff viewer display mode.
+    def diff_view(config = read_config)
+      editor = config["editor"].is_a?(Hash) ? config["editor"] : {}
+      DiffViewMode.normalize(editor["diff_view"])
+    end
+
     # Returns whether file tools must stay inside the active workspace root.
     def workspace_guardrails_enabled?(config = read_config)
       tools = config["tools"].is_a?(Hash) ? config["tools"] : {}
       tools["workspace_guardrails"] != false
     end
 
+    # Returns whether project-level Agent Skills should be loaded from the workspace.
+    def project_skills_trusted?(config = read_config)
+      skills = config["skills"].is_a?(Hash) ? config["skills"] : {}
+      skills["trust_project"] == true
+    end
+
     # Returns whether new frontends should resume the last active session automatically.
     def session_auto_resume_enabled?(config = read_config)
       sessions = config["sessions"].is_a?(Hash) ? config["sessions"] : {}
@@ -399,7 +502,7 @@ module Kward
       raise "Overlay settings must be an object" unless values.is_a?(Hash)
 
       config = read_config
-      overlay = config["overlay"].is_a?(Hash) ? config["overlay"].dup : {}
+      overlay = overlay_settings(config)
       values.each do |key, value|
         key = key.to_s
         value = value.to_s
@@ -674,8 +777,8 @@ module Kward
     # Lists configured skills discovered under the config directory.
     #
     # @return [Array<Skill>] skill metadata available to the model
-    def skills
-      skills_registry.skills
+    def skills(workspace_root: Dir.pwd)
+      skills_registry(workspace_root: workspace_root).skills
     end
 
     # @return [String] trusted user plugin directory
@@ -712,16 +815,18 @@ module Kward
     # @param name [String] configured skill name
     # @param relative_path [String, nil] path inside the skill directory
     # @return [String] file contents or an error string
-    def read_skill_file(name, relative_path = nil)
-      skills_registry.read_skill_file(name, relative_path)
+    def read_skill_file(name, relative_path = nil, workspace_root: Dir.pwd)
+      skills_registry(workspace_root: workspace_root).read_skill_file(name, relative_path)
     end
 
-    def skills_registry
+    def skills_registry(workspace_root: Dir.pwd)
       Skills::Registry.new(
         config_dir: config_dir,
+        workspace_root: workspace_root,
+        project_skills_trusted: project_skills_trusted?,
         skill_class: Skill,
         max_file_bytes: MAX_SKILL_FILE_BYTES,
-        markdown_parser: method(:markdown_parts),
+        markdown_parser: ->(path) { Frontmatter.markdown_parts(path, lenient: true) },
         inside_directory: method(:inside_directory?)
       )
     end
@@ -730,25 +835,12 @@ module Kward
       Prompts::Templates.new(
         config_dir: config_dir,
         template_class: PromptTemplate,
-        markdown_parser: method(:markdown_parts)
+        markdown_parser: ->(path) { Frontmatter.markdown_parts(path) }
       )
     end
 
-    def markdown_parts(path)
-      content = File.read(path)
-      return [{}, content] unless content.start_with?("---\n", "---\r\n")
-
-      _opening, rest = content.split(/\A---\r?\n/, 2)
-      yaml_text, body = rest.to_s.split(/\r?\n---\r?\n/, 2)
-      raise "missing frontmatter closing delimiter" if body.nil?
-
-      data = yaml_text.to_s.empty? ? {} : YAML.safe_load(yaml_text, permitted_classes: [], aliases: false)
-      frontmatter = data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
-      [frontmatter, body]
-    end
-
     def inside_directory?(path, base)
-      path == base || path.start_with?(base + File::SEPARATOR)
+      PathGuard.inside?(path, base)
     end
 
     def presence(value)

data/lib/kward/deep_copy.rb

@@ -0,0 +1,42 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Small recursive copy/freeze helpers for plain Hash/Array payload objects.
+  module DeepCopy
+    module_function
+
+    def dup(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), result| result[key] = dup(item) }
+      when Array
+        value.map { |item| dup(item) }
+      else
+        value.dup
+      end
+    rescue TypeError
+      value
+    end
+
+    def freeze(value)
+      case value
+      when Hash
+        value.each_value { |item| freeze(item) }
+      when Array
+        value.each { |item| freeze(item) }
+      end
+      value.freeze
+    end
+
+    def merge(left, right)
+      left = dup(left)
+      right.each do |key, value|
+        left[key] = if left[key].is_a?(Hash) && value.is_a?(Hash)
+                      merge(left[key], value)
+                    else
+                      dup(value)
+                    end
+      end
+      left
+    end
+  end
+end

data/lib/kward/diff_view_mode.rb

@@ -0,0 +1,36 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Normalizes and resolves the integrated diff viewer display mode.
+  module DiffViewMode
+    AUTO = "auto"
+    UNIFIED = "unified"
+    SIDE_BY_SIDE = "side_by_side"
+    MODES = [AUTO, UNIFIED, SIDE_BY_SIDE].freeze
+    SIDE_BY_SIDE_MIN_WIDTH = 120
+
+    module_function
+
+    def normalize(value)
+      text = value.to_s.downcase.tr("-", "_")
+      MODES.include?(text) ? text : AUTO
+    end
+
+    def label(value)
+      case normalize(value)
+      when SIDE_BY_SIDE
+        "side-by-side"
+      when UNIFIED
+        "unified"
+      else
+        "auto"
+      end
+    end
+
+    def resolve(value, terminal_width: nil)
+      mode = normalize(value)
+      return mode unless mode == AUTO
+
+      terminal_width.to_i >= SIDE_BY_SIDE_MIN_WIDTH ? SIDE_BY_SIDE : UNIFIED
+    end
+  end
+end

data/lib/kward/events.rb

@@ -9,6 +9,7 @@ module Kward
     Steering = Struct.new(:input, :created_at, keyword_init: true)
     SteeringApplied = Struct.new(:count, keyword_init: true)
     ToolCall = Struct.new(:tool_call, keyword_init: true)
+    ToolUpdate = Struct.new(:tool_call, :content, :elapsed_ms, keyword_init: true)
     ToolResult = Struct.new(:tool_call, :content, keyword_init: true)
     Answer = Struct.new(:content, keyword_init: true)
   end

data/lib/kward/export_path.rb

@@ -1,4 +1,5 @@
 require "pathname"
+require_relative "path_guard"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -11,7 +12,7 @@ module Kward
       resolved = File.expand_path(explicit, workspace_root)
       allowed_roots = [workspace_root, session_dir].compact.map { |root| Pathname.new(root).expand_path }
       expanded = Pathname.new(resolved).expand_path
-      unless allowed_roots.any? { |root| inside?(expanded, root) }
+      unless allowed_roots.any? { |root| PathGuard.inside?(expanded, root) }
         raise ArgumentError, "export path outside workspace or session directory: #{path}"
       end
 
@@ -21,10 +22,5 @@ module Kward
 
       resolved
     end
-
-    def self.inside?(path, root)
-      path.to_s == root.to_s || path.to_s.start_with?("#{root}/")
-    end
-    private_class_method :inside?
   end
 end

data/lib/kward/frontmatter.rb

@@ -0,0 +1,43 @@
+require "yaml"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Markdown frontmatter parsing shared by prompt templates and skills.
+  module Frontmatter
+    module_function
+
+    def markdown_parts(path, lenient: false)
+      content = File.read(path)
+      return [{}, content] unless content.start_with?("---\n", "---\r\n")
+
+      _opening, rest = content.split(/\A---\r?\n/, 2)
+      yaml_text, body = rest.to_s.split(/\r?\n---\r?\n/, 2)
+      raise "missing frontmatter closing delimiter" if body.nil?
+
+      data = yaml_text.to_s.empty? ? {} : load_frontmatter(yaml_text, lenient: lenient)
+      frontmatter = data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+      [frontmatter, body]
+    end
+
+    def load_frontmatter(yaml_text, lenient: false)
+      YAML.safe_load(yaml_text, permitted_classes: [], aliases: false)
+    rescue Psych::SyntaxError
+      raise unless lenient
+
+      lenient_frontmatter(yaml_text)
+    end
+
+    def lenient_frontmatter(yaml_text)
+      yaml_text.each_line.each_with_object({}) do |line, result|
+        match = line.chomp.match(/\A([A-Za-z0-9_-]+):\s*(.*)\z/)
+        next unless match
+
+        key = match[1]
+        value = match[2].strip
+        next if value.empty?
+
+        result[key] = value.delete_prefix('"').delete_suffix('"')
+      end
+    end
+  end
+end

data/lib/kward/hooks/audit_log.rb

@@ -0,0 +1,121 @@
+require "fileutils"
+require "json"
+require "time"
+require_relative "../config_files"
+require_relative "../rpc/redactor"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Append-only JSONL audit log for lifecycle hook activity.
+    class AuditLog
+      DEFAULT_MAX_BYTES = 10 * 1024 * 1024
+
+      def initialize(path: nil, config_path: ConfigFiles.config_path, max_bytes: DEFAULT_MAX_BYTES, clock: Time, monotonic_clock: Process, error_output: $stderr)
+        @path = path
+        @config_path = config_path
+        @max_bytes = max_bytes.to_i.positive? ? max_bytes.to_i : DEFAULT_MAX_BYTES
+        @clock = clock
+        @monotonic_clock = monotonic_clock
+        @error_output = error_output
+        @mutex = Mutex.new
+        @warned = false
+      end
+
+      def monotonic_now
+        @monotonic_clock.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def duration_ms(started_at)
+        ((monotonic_now - started_at.to_f) * 1000).round(1)
+      end
+
+      def log_handler(event:, handler:, decision:, duration_ms: nil)
+        write_record(
+          "kind" => "handler",
+          "event_id" => event.id,
+          "event" => event.name,
+          "phase" => event.phase,
+          "hook_id" => handler.id,
+          "source" => handler.source,
+          "decision" => decision.decision,
+          "message" => redact_string(decision.message),
+          "duration_ms" => duration_ms,
+          "payload_keys" => safe_keys(event.payload),
+          "modified_keys" => decision.modify? ? safe_keys(decision.payload) : []
+        )
+      end
+
+      def log_result(event:, result:)
+        write_record(
+          "kind" => "result",
+          "event_id" => event.id,
+          "event" => event.name,
+          "phase" => event.phase,
+          "decision" => result.decision.decision,
+          "message" => redact_string(result.decision.message),
+          "handler_count" => result.decisions.length,
+          "warnings" => result.warnings.map { |warning| redact_string(warning) },
+          "messages" => result.messages.map { |message| redact_string(message) },
+          "payload_keys" => safe_keys(result.payload)
+        )
+      end
+
+      private
+
+      def write_record(payload)
+        @mutex.synchronize do
+          path = current_path
+          FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+          File.open(path, File::WRONLY | File::CREAT | File::APPEND, 0o600) do |file|
+            file.write(JSON.generate(payload.compact.merge("timestamp" => @clock.now.utc.iso8601(3))))
+            file.write("\n")
+          end
+          File.chmod(0o600, path)
+        end
+        true
+      rescue StandardError => e
+        warn_once(e)
+        false
+      end
+
+      def current_path
+        explicit_path = @path || File.join(File.dirname(File.expand_path(@config_path)), "logs", "hooks.jsonl")
+        return explicit_path if writable_log_path?(explicit_path)
+
+        index = 1
+        loop do
+          path = explicit_path.sub(/\.jsonl\z/, "-#{index}.jsonl")
+          return path if writable_log_path?(path)
+
+          index += 1
+        end
+      end
+
+      def writable_log_path?(path)
+        !File.exist?(path) || File.size(path) < @max_bytes
+      end
+
+      def safe_keys(value)
+        return [] unless value.is_a?(Hash)
+
+        value.keys.map(&:to_s).sort
+      end
+
+      def redact_string(value)
+        return nil if value.nil?
+
+        RPC::Redactor.redact_string(value.to_s)[0, 500]
+      end
+
+      def warn_once(error)
+        return if @warned
+
+        @warned = true
+        @error_output&.puts("Warning: hook audit logging failed: #{error.message}")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/kward/hooks/catalog.rb

@@ -0,0 +1,110 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module Hooks
+    # Known lifecycle hook events and their safety defaults.
+    module Catalog
+      DEFAULT_FAILURE_POLICY = "warn"
+      VALID_FAILURE_POLICIES = %w[allow warn deny ask].freeze
+
+      EventDefinition = Struct.new(:name, :failure_policy, :modifiable_fields, keyword_init: true)
+
+      DEFINITIONS = [
+        EventDefinition.new(name: "turn_start", failure_policy: "warn", modifiable_fields: %w[input display_input]),
+        EventDefinition.new(name: "turn_context_build_before", failure_policy: "warn"),
+        EventDefinition.new(name: "turn_context_build_after", failure_policy: "warn"),
+        EventDefinition.new(name: "model_request_before", failure_policy: "warn", modifiable_fields: %w[messages tools provider model reasoning]),
+        EventDefinition.new(name: "turn_model_request_before", failure_policy: "warn"),
+        EventDefinition.new(name: "model_response_after_parse", failure_policy: "warn"),
+        EventDefinition.new(name: "turn_model_response_complete", failure_policy: "warn"),
+        EventDefinition.new(name: "turn_end", failure_policy: "warn"),
+        EventDefinition.new(name: "session_create", failure_policy: "warn"),
+        EventDefinition.new(name: "session_resume", failure_policy: "warn"),
+        EventDefinition.new(name: "session_clone", failure_policy: "warn"),
+        EventDefinition.new(name: "session_fork", failure_policy: "warn"),
+        EventDefinition.new(name: "session_rename", failure_policy: "warn"),
+        EventDefinition.new(name: "session_export_before", failure_policy: "deny"),
+        EventDefinition.new(name: "session_export_after", failure_policy: "warn"),
+        EventDefinition.new(name: "session_compact_before", failure_policy: "deny"),
+        EventDefinition.new(name: "session_compact_after", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_output_compact_before", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_output_compact_after", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_call_before", failure_policy: "deny", modifiable_fields: %w[arguments]),
+        EventDefinition.new(name: "tool_call_after", failure_policy: "warn"),
+        EventDefinition.new(name: "tool_call_error", failure_policy: "warn"),
+        EventDefinition.new(name: "mcp_tool_before", failure_policy: "deny"),
+        EventDefinition.new(name: "mcp_tool_after", failure_policy: "warn"),
+        EventDefinition.new(name: "mcp_tool_error", failure_policy: "warn"),
+        EventDefinition.new(name: "shell_command_before", failure_policy: "deny", modifiable_fields: %w[command timeout_seconds]),
+        EventDefinition.new(name: "shell_command_after", failure_policy: "warn"),
+        EventDefinition.new(name: "file_change_before", failure_policy: "deny"),
+        EventDefinition.new(name: "file_change_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_status_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_diff_before", failure_policy: "deny"),
+        EventDefinition.new(name: "git_diff_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_stage_before", failure_policy: "deny"),
+        EventDefinition.new(name: "git_stage_after", failure_policy: "warn"),
+        EventDefinition.new(name: "git_commit_before", failure_policy: "deny"),
+        EventDefinition.new(name: "git_commit_after", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_create", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_start_before", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_start_after", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_ready_for_review", failure_policy: "warn"),
+        EventDefinition.new(name: "worker_job_failed", failure_policy: "warn")
+      ].each_with_object({}) { |definition, result| result[definition.name] = definition }.freeze
+
+      module_function
+
+      def event_names
+        DEFINITIONS.keys.sort
+      end
+
+      def definition(event_name)
+        DEFINITIONS[event_name.to_s]
+      end
+
+      def known?(event_name)
+        DEFINITIONS.key?(event_name.to_s)
+      end
+
+      def failure_policy(event_name, explicit_policy = nil)
+        normalize_failure_policy(explicit_policy || definition(event_name)&.failure_policy || DEFAULT_FAILURE_POLICY)
+      end
+
+      def normalize_failure_policy(policy)
+        value = policy.to_s
+        return value if VALID_FAILURE_POLICIES.include?(value)
+
+        raise ArgumentError, "Unknown hook failure policy: #{policy}"
+      end
+
+      def modifiable_fields(event_name)
+        Array(definition(event_name)&.modifiable_fields)
+      end
+
+      def filter_modifications(event_name, payload)
+        definition = definition(event_name)
+        return payload unless definition
+
+        fields = Array(definition.modifiable_fields)
+        return {} if fields.empty?
+
+        payload.each_with_object({}) do |(key, value), result|
+          result[key] = value if fields.include?(key.to_s)
+        end
+      end
+
+      def failure_decision(policy, message, metadata: nil)
+        case normalize_failure_policy(policy)
+        when "allow"
+          Decision.allow(message, metadata: metadata)
+        when "warn"
+          Decision.warn(message, metadata: metadata)
+        when "deny"
+          Decision.deny(message, metadata: metadata)
+        when "ask"
+          Decision.ask(message, metadata: metadata)
+        end
+      end
+    end
+  end
+end