kward 0.74.0 → 0.76.0

data/lib/kward/plugin_registry.rb

@@ -1,4 +1,6 @@
 require_relative "config_files"
+require_relative "deep_copy"
+require_relative "hooks"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -39,6 +41,9 @@ module Kward
       end
     end
 
+    # Registered lifecycle hook handler.
+    HookHandler = Struct.new(:event, :id, :description, :path, :order, :match, :failure_policy, :handler, keyword_init: true)
+
     # Read-only transcript view exposed to plugin code.
     class Transcript
       # Creates an object for trusted plugin loading and dispatch.
@@ -50,7 +55,7 @@ module Kward
       #
       # @return [Array<Hash>] immutable transcript message data
       def messages
-        PluginRegistry.deep_freeze(PluginRegistry.deep_dup(@conversation.messages))
+        DeepCopy.freeze(DeepCopy.dup(@conversation.messages))
       end
     end
 
@@ -102,6 +107,34 @@ module Kward
         @conversation.refresh_system_message! if @conversation.respond_to?(:refresh_system_message!)
         nil
       end
+
+      def allow(message = nil, metadata: nil)
+        Hooks::Decision.allow(message, metadata: metadata)
+      end
+
+      def deny(message = nil, metadata: nil)
+        Hooks::Decision.deny(message, metadata: metadata)
+      end
+
+      def ask(message = nil, metadata: nil)
+        Hooks::Decision.ask(message, metadata: metadata)
+      end
+
+      def modify(payload, message: nil, metadata: nil)
+        Hooks::Decision.modify(payload, message: message, metadata: metadata)
+      end
+
+      def warn(message = nil, metadata: nil)
+        Hooks::Decision.warn(message, metadata: metadata)
+      end
+
+      def retry(message = nil, payload: nil, metadata: nil)
+        Hooks::Decision.retry(message, payload: payload, metadata: metadata)
+      end
+
+      def defer(message = nil, payload: nil, metadata: nil)
+        Hooks::Decision.defer(message, payload: payload, metadata: metadata)
+      end
     end
 
     # Public DSL object yielded by `Kward.plugin` blocks.
@@ -165,6 +198,25 @@ module Kward
         @registry.register_transcript_event(path: @path, &block)
       end
 
+      # Registers a lifecycle hook handler.
+      #
+      # Hooks are deterministic runtime callbacks around Kward lifecycle events.
+      # They can return a {Hooks::Decision}, a decision hash, a decision string,
+      # or nil to allow the operation.
+      #
+      # @param event [String, #to_s] lifecycle event name
+      # @param id [String, nil] stable hook identifier for logs and diagnostics
+      # @param description [String] short human-readable purpose
+      # @param order [Integer] lower values run first
+      # @param match [Hash, nil] optional event selector
+      # @yieldparam event [Hooks::Event] immutable lifecycle event
+      # @yieldparam ctx [Context] plugin execution context and decision helpers
+      # @return [void]
+      # @api public
+      def hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, &block)
+        @registry.register_hook(event, id: id, description: description, order: order, match: match, failure_policy: failure_policy, path: @path, &block)
+      end
+
       # Registers prompt context text injected into future system prompts.
       #
       # Keep this text short and never include secrets. The returned string can
@@ -205,29 +257,6 @@ module Kward
         paths.each { |path| registry.load_file(path) }
         registry
       end
-
-      def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) { |(key, item), result| result[key] = deep_dup(item) }
-        when Array
-          value.map { |item| deep_dup(item) }
-        else
-          value.dup
-        end
-      rescue TypeError
-        value
-      end
-
-      def deep_freeze(value)
-        case value
-        when Hash
-          value.each_value { |item| deep_freeze(item) }
-        when Array
-          value.each { |item| deep_freeze(item) }
-        end
-        value.freeze
-      end
     end
 
     # Creates an object for trusted plugin loading and dispatch.
@@ -239,6 +268,7 @@ module Kward
       @footer_path = nil
       @transcript_event_handlers = []
       @prompt_context_renderers = []
+      @hook_handlers = []
       @paths = []
     end
 
@@ -276,6 +306,20 @@ module Kward
       @prompt_context_renderers.map { |entry| entry[:renderer] }
     end
 
+    def hook_handlers
+      @hook_handlers.dup
+    end
+
+    def hook_manager
+      manager = Hooks::Manager.new
+      @hook_handlers.each do |hook|
+        manager.register(hook.event, id: hook.id, source: hook.path, order: hook.order, match: hook.match, failure_policy: hook.failure_policy) do |event, context|
+          hook.handler.call(event, context)
+        end
+      end
+      manager
+    end
+
     def prompt_context(context)
       parts = []
       @prompt_context_renderers.each do |entry|
@@ -387,12 +431,31 @@ module Kward
       @prompt_context_renderers << { path: path, renderer: renderer }
     end
 
+    def register_hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, path: nil, &handler)
+      event = event.to_s
+      raise "Plugin hook event is required" if event.empty?
+      raise "Plugin hook #{event} requires a handler" unless handler
+
+      @hook_handlers << HookHandler.new(
+        event: event,
+        id: id&.to_s || "#{File.basename(path.to_s.empty? ? "plugin" : path)}:#{event}:#{@hook_handlers.length + 1}",
+        description: description.to_s,
+        path: path,
+        order: order.to_i,
+        match: match,
+        failure_policy: failure_policy,
+        handler: handler
+      )
+    end
+
     private
 
     def transcript_event_for(event)
       case event.class.name
       when "Kward::Events::ReasoningDelta"
         transcript_event("reasoning_delta", delta: event.delta)
+      when "Kward::Events::ReasoningBoundary"
+        transcript_event("reasoning_boundary")
       when "Kward::Events::AssistantDelta"
         transcript_event("assistant_delta", delta: event.delta)
       when "Kward::Events::AssistantMessage"
@@ -422,7 +485,7 @@ module Kward
     def transcript_event(type, payload)
       TranscriptEvent.new(
         type: type,
-        payload: PluginRegistry.deep_freeze(PluginRegistry.deep_dup(payload))
+        payload: DeepCopy.freeze(DeepCopy.dup(payload))
       ).freeze
     end
   end

data/lib/kward/prompt_interface/editor/controller.rb

@@ -112,7 +112,9 @@ module Kward
       end
 
       def open_diff_viewer(path, content)
-        @editor_state = EditorState.new(path: path.to_s, content: content.to_s, new_file: true, editor_mode: current_editor_mode, readonly: true, diff_view: true)
+        diff_view_mode = current_diff_view_mode
+        viewer_content = diff_view_mode == DiffViewMode::SIDE_BY_SIDE ? side_by_side_diff_content(content.to_s) : content.to_s
+        @editor_state = EditorState.new(path: path.to_s, content: viewer_content, new_file: true, editor_mode: current_editor_mode, readonly: true, diff_view: diff_view_mode)
         @prompt_label = "Diff>"
         self.composer_input = ""
         self.composer_cursor = 0
@@ -131,6 +133,63 @@ module Kward
         @editor_mode
       end
 
+      def current_diff_view_mode
+        configured = @diff_view_source.respond_to?(:call) ? @diff_view_source.call : @diff_view
+        DiffViewMode.resolve(configured, terminal_width: screen_width)
+      rescue StandardError
+        DiffViewMode.resolve(@diff_view, terminal_width: screen_width)
+      end
+
+      def side_by_side_diff_content(content)
+        width = side_by_side_diff_column_width
+        rows = []
+        pending_deletions = []
+
+        content.to_s.each_line(chomp: true) do |line|
+          if side_by_side_diff_metadata_line?(line)
+            rows.concat(flush_side_by_side_deletions(pending_deletions, width))
+            rows << line
+          elsif line.start_with?("-")
+            pending_deletions << line[1..].to_s
+          elsif line.start_with?("+")
+            deleted = pending_deletions.shift
+            rows << side_by_side_diff_row(deleted && "- #{deleted}", "+ #{line[1..]}", width)
+          else
+            rows.concat(flush_side_by_side_deletions(pending_deletions, width))
+            text = line.start_with?(" ") ? line[1..].to_s : line
+            rows << side_by_side_diff_row("  #{text}", "  #{text}", width)
+          end
+        end
+
+        rows.concat(flush_side_by_side_deletions(pending_deletions, width))
+        rows.join("\n")
+      end
+
+      def side_by_side_diff_metadata_line?(line)
+        line.start_with?("diff --git", "index ", "---", "+++", "@@")
+      end
+
+      def flush_side_by_side_deletions(lines, width)
+        lines.shift(lines.length).map { |line| side_by_side_diff_row("- #{line}", nil, width) }
+      end
+
+      def side_by_side_diff_row(left, right, width)
+        left_text = side_by_side_diff_cell(left, width)
+        right_text = side_by_side_diff_cell(right, width)
+        "#{left_text.ljust(width)} │ #{right_text}"
+      end
+
+      def side_by_side_diff_cell(text, width)
+        value = text.nil? ? "" : text.to_s
+        visible_truncate(value, width)
+      end
+
+      def side_by_side_diff_column_width
+        content_width = [screen_width - 4, 1].max
+        gutter_width = [[999.to_s.length, 4].max + 3, 1].max
+        [[(content_width - gutter_width - 3) / 2, 10].max, 80].min
+      end
+
       def current_editor_soft_wrap?
         return @editor_soft_wrap_source.call != false if @editor_soft_wrap_source.respond_to?(:call)
 

data/lib/kward/prompt_interface/editor/renderer.rb

@@ -174,6 +174,7 @@ module Kward
 
       def editor_render_diff_line(line)
         text = line.to_s
+        return editor_render_side_by_side_diff_line(text) if @editor_state.side_by_side_diff_view?
         return colored(text, :green) if text.start_with?("+") && !text.start_with?("+++")
         return colored(text, :red) if text.start_with?("-") && !text.start_with?("---")
         return colored(text, :cyan) if text.start_with?("@@")
@@ -181,6 +182,16 @@ module Kward
         text
       end
 
+      def editor_render_side_by_side_diff_line(text)
+        return colored(text, :cyan) if text.start_with?("@@")
+        return text unless text.include?(" │ ")
+
+        left, right = text.split(" │ ", 2)
+        rendered_left = left.start_with?("-") ? colored(left, :red) : left
+        rendered_right = right.start_with?("+") ? colored(right, :green) : right
+        "#{rendered_left} │ #{rendered_right}"
+      end
+
       def editor_line_number_gutter_width
         [[@editor_state.lines.length.to_s.length, 4].max + 3, 1].max
       end

data/lib/kward/prompt_interface/editor/state.rb

@@ -373,7 +373,11 @@ module Kward
       end
 
       def diff_view?
-        @diff_view == true
+        !@diff_view.nil? && @diff_view != false
+      end
+
+      def side_by_side_diff_view?
+        @diff_view == DiffViewMode::SIDE_BY_SIDE
       end
 
       def modern?

data/lib/kward/prompt_interface/selection_prompt.rb

@@ -73,6 +73,8 @@ module Kward
         queue_pending_keys(sequence[:remaining]) if sequence[:remaining] && !sequence[:remaining].empty?
 
         case code
+        when 9
+          modified_tab_sequence?(sequence) ? true : select_toggle_search
         when 13
           select_input_active? ? select_input_action_result : select_current_choice
         when 27
@@ -501,25 +503,43 @@ module Kward
 
       def select_typed_key(key)
         return select_insert_key(key) if select_input_active?
-        return select_begin_search if key == "/" && !select_search_active?
+        return select_toggle_search if select_search_toggle_key?(key)
         return select_action_key(key) unless select_search_active?
 
         select_insert_key(key)
       end
 
+      def select_search_toggle_key?(key)
+        TerminalKeys::TAB.include?(key)
+      end
+
+      def modified_tab_sequence?(sequence)
+        modifier = sequence[:modifier]
+        modifier && modifier != 1
+      end
+
+      def select_toggle_search
+        select_search_active? ? select_pause_search : select_begin_search
+      end
+
       def select_begin_search
         return unless @select_state
 
         @select_state[:search_active] = true
-        self.composer_input = ""
-        self.composer_cursor = 0
         true
       end
 
-      def select_cancel_search
+      def select_pause_search
         return unless @select_state
 
         @select_state[:search_active] = false
+        true
+      end
+
+      def select_cancel_search
+        return unless @select_state
+
+        select_pause_search
         self.composer_input = ""
         self.composer_cursor = 0
         @select_state[:selection_index] = 0
@@ -607,7 +627,7 @@ module Kward
 
       def selection_matches
         choices = @select_state ? @select_state[:choices] : []
-        filter = select_search_active? ? composer_input.downcase.strip : ""
+        filter = (select_search_active? || !composer_input.strip.empty?) ? composer_input.downcase.strip : ""
         matches = filter.empty? ? choices : choices.select { |choice| choice.downcase.include?(filter) }
         clamp_selection_index(matches.length)
         matches
@@ -666,7 +686,7 @@ module Kward
         return "Renaming · Enter save · Esc cancel" if select_input_active?
 
         text = "↑/↓ select · Enter open"
-        text = "#{text} · / search" unless select_search_active?
+        text = "#{text} · Tab search" unless select_search_active?
         action_keys = @select_state ? @select_state[:action_keys].to_h : {}
         action_keys.each do |key, action|
           text = "#{text} · #{key} #{action[:action]}"

data/lib/kward/prompt_interface/transcript_renderer.rb

@@ -15,7 +15,7 @@ module Kward
             @stream_state.start_block(label)
           end
           write_transcript_text_locked(delta) unless delta.empty?
-          write_transcript_text_locked("\n") if finish && @stream_state.block
+          write_transcript_text_locked("\n") if finish && @stream_state.block && !@transcript_buffer.end_with?("\n")
           @stream_state.finish_block if finish
           restore_composer_cursor_locked unless @restoring_transcript
         end

data/lib/kward/prompt_interface.rb

@@ -12,6 +12,7 @@ require_relative "ansi"
 require_relative "terminal_sequences"
 require_relative "terminal_keys"
 require_relative "editor_mode"
+require_relative "diff_view_mode"
 require_relative "prompt_interface/banner"
 require_relative "prompt_interface/composer_state"
 require_relative "prompt_interface/editor/state"
@@ -125,7 +126,7 @@ module Kward
       end
     end
 
-    def initialize(input: $stdin, output: $stdout, slash_commands: [], overlay_settings: nil, footer: nil, composer_status: nil, busy_help: true, attachment_badges: nil, attachment_parser: nil, banner_message: nil, tab_keybindings: nil, prompt_history: nil, editor_mode: nil, editor_mode_source: nil, editor_auto_indent: true, editor_auto_indent_source: nil, editor_auto_close_pairs: true, editor_auto_close_pairs_source: nil, editor_soft_wrap: true, editor_soft_wrap_source: nil, editor_bar_cursor: true, editor_bar_cursor_source: nil, editor_line_numbers: "absolute", editor_line_numbers_source: nil)
+    def initialize(input: $stdin, output: $stdout, slash_commands: [], overlay_settings: nil, footer: nil, composer_status: nil, busy_help: true, attachment_badges: nil, attachment_parser: nil, banner_message: nil, tab_keybindings: nil, prompt_history: nil, editor_mode: nil, editor_mode_source: nil, editor_auto_indent: true, editor_auto_indent_source: nil, editor_auto_close_pairs: true, editor_auto_close_pairs_source: nil, editor_soft_wrap: true, editor_soft_wrap_source: nil, editor_bar_cursor: true, editor_bar_cursor_source: nil, editor_line_numbers: "absolute", editor_line_numbers_source: nil, diff_view: "auto", diff_view_source: nil)
       @input_io = input
       @output_io = output
       @reader = TTY::Reader.new(input: input, output: output, interrupt: :error)
@@ -206,6 +207,8 @@ module Kward
       @editor_bar_cursor_source = editor_bar_cursor_source
       @editor_line_numbers = normalize_editor_line_numbers(editor_line_numbers)
       @editor_line_numbers_source = editor_line_numbers_source
+      @diff_view = DiffViewMode.normalize(diff_view)
+      @diff_view_source = diff_view_source
     end
 
     def start(render: true)

data/lib/kward/prompts/commands.rb

@@ -8,9 +8,8 @@ module Kward
       { name: "exit", description: "Exit the interactive session.", argument_hint: "" },
       { name: "quit", description: "Exit the interactive session.", argument_hint: "" },
       { name: "new", description: "Start a new session.", argument_hint: "" },
-      { name: "sessions", description: "Open the saved sessions picker.", argument_hint: "[path]" },
-      { name: "resume", description: "Alias for /sessions.", argument_hint: "[path]" },
-      { name: "name", description: "Name or clear the current session.", argument_hint: "[name]" },
+      { name: "session", description: "Open saved sessions or name the current session.", argument_hint: "[path]|name [name]" },
+      { name: "resume", description: "Alias for /session.", argument_hint: "[path]" },
       { name: "rename", description: "Rename the current session.", argument_hint: "<name>" },
       { name: "clone", description: "Clone the current session.", argument_hint: "" },
       { name: "fork", description: "Fork from an earlier prompt into a new session.", argument_hint: "" },
@@ -36,6 +35,7 @@ module Kward
       { name: "tab", description: "Manage tabs.", argument_hint: "[1-n|move|close|new|name]" },
       { name: "status", description: "Show the current status message.", argument_hint: "" },
       { name: "stats", description: "Show telemetry logging stats.", argument_hint: "[range]" },
+      { name: "hooks", description: "Inspect lifecycle hooks.", argument_hint: "[list|events|logs|doctor|trust|untrust]" },
       { name: "memory", description: "Inspect and manage Kward memory.", argument_hint: "[enable|disable|auto-summary|core|add|list|forget|promote|relax|inspect|why|summarize]" }
     ].freeze
     BUILTIN_RESERVED_COMMAND_NAMES = BUILTIN_COMMANDS.map { |command| command[:name] }.freeze

data/lib/kward/prompts.rb

@@ -25,7 +25,8 @@ module Kward
         sections << prompt_section("Persona", persona_prompt(workspace_root, model: model, reasoning_effort: reasoning_effort, now: now))
         sections << prompt_section("Plugin context", plugin_context) unless plugin_context.to_s.empty?
       end
-      sections << prompt_section("Configured skills", skills_prompt, source: ConfigFiles.skills.empty? ? nil : File.join(ConfigFiles.config_dir, "skills"))
+      skills = ConfigFiles.skills(workspace_root: workspace_root)
+      sections << prompt_section("Configured skills", skills_prompt(skills), source: skills.empty? ? nil : File.join(ConfigFiles.config_dir, "skills"))
       sections << prompt_section(workspace_agents_context_label(workspace_root), workspace_agents_context(workspace_root), source: ConfigFiles.workspace_agents_file?(workspace_root) ? ConfigFiles.workspace_agents_path(workspace_root) : nil)
       sections.compact
     end
@@ -97,18 +98,17 @@ module Kward
       { label: label, content: content, source: source }
     end
 
-    def skills_prompt
-      skills = ConfigFiles.skills
+    def skills_prompt(skills = ConfigFiles.skills)
       return nil if skills.empty?
 
       lines = [
-        "Configured skills are available in the Kward config directory.",
-        "When a task matches a skill, use read_skill to load its instructions before proceeding.",
+        "Agent Skills are available.",
+        "When a task matches a skill's description, use read_skill to load its instructions before proceeding.",
+        "Use read_skill with a relative path to read referenced files inside a skill directory.",
         "Available skills:"
       ]
       skills.each do |skill|
-        description = skill.description.empty? ? "No description provided." : skill.description
-        lines << "- #{skill.name}: #{description}"
+        lines << "- #{skill.name}: #{skill.description}"
       end
       lines.join("\n")
     end

data/lib/kward/rpc/mcp_status.rb

@@ -0,0 +1,50 @@
+require_relative "../mcp/server_config"
+require_relative "redactor"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # JSON-RPC backend namespace used by UI clients.
+  module RPC
+    # Builds RPC-visible MCP server status payloads.
+    class MCPStatus
+      def initialize(config_manager:)
+        @config_manager = config_manager
+      end
+
+      def to_h
+        config = @config_manager.read(redacted: false)
+        clients = MCP::ServerConfig.clients_from_config(config).to_h { |client| [client.name, client] }
+        servers = MCP::ServerConfig.configured_servers(config).map do |name, settings|
+          server_status(name, settings, clients[name.to_s])
+        end
+        { servers: servers }
+      end
+
+      private
+
+      def server_status(name, settings, client)
+        base = { name: name.to_s, transport: "stdio", toolCount: 0 }
+        unless client
+          return base.merge(status: "unavailable", error: "command not configured") if settings["command"].to_s.empty?
+
+          return base.merge(status: "unavailable", error: "unsupported MCP server configuration")
+        end
+
+        tools = client.list_tools
+        base.merge(status: "available", toolCount: tools.length)
+      rescue StandardError => e
+        base.merge(status: "unavailable", toolCount: 0, error: redacted_error(e.message, client))
+      ensure
+        client&.close
+      end
+
+      def redacted_error(message, client)
+        text = Redactor.redact_string(message.to_s)
+        command = client&.transport&.respond_to?(:command) ? client.transport.command.to_s : ""
+        return text if command.empty?
+
+        text.gsub(command, File.basename(command))
+      end
+    end
+  end
+end

data/lib/kward/rpc/prompt_bridge.rb

@@ -17,6 +17,32 @@ module Kward
         @pending_requests = {}
       end
 
+      def request_tool_approval(tool_call_id:, tool_name:, args:, cancellation: nil)
+        request_id = SecureRandom.uuid
+        @mutex.synchronize { @pending_requests[request_id] = true }
+        cancellation&.on_cancel { cancel_request(request_id) }
+        unless cancellation&.cancelled?
+          @server.notify("tool/approvalRequested", {
+            sessionId: @session_id,
+            approvalRequestId: request_id,
+            toolCallId: tool_call_id,
+            toolName: tool_name,
+            args: args
+          })
+        end
+
+        @mutex.synchronize do
+          @condition.wait(@mutex) until @answers.key?(request_id)
+          answer = @answers.delete(request_id)
+          @pending_requests.delete(request_id)
+          approved_answer?(answer)
+        end
+      end
+
+      def answer_tool_approval(request_id, approved:)
+        answer_raw(request_id, !!approved)
+      end
+
       def ask_user_question(questions, cancellation: nil)
         questions = validate_questions(questions)
         request_id = SecureRandom.uuid
@@ -41,28 +67,36 @@ module Kward
       end
 
       def answer(request_id, answers)
+        answer_raw(request_id, normalize_answers(answers))
+      end
+
+      def cancel_request(request_id)
         @mutex.synchronize do
           request_id = request_id.to_s
           return unless @pending_requests.key?(request_id)
           return if @answers.key?(request_id)
 
-          @answers[request_id] = normalize_answers(answers)
+          @answers[request_id] = nil
           @condition.broadcast
         end
       end
 
-      def cancel_request(request_id)
+      private
+
+      def answer_raw(request_id, value)
         @mutex.synchronize do
           request_id = request_id.to_s
           return unless @pending_requests.key?(request_id)
           return if @answers.key?(request_id)
 
-          @answers[request_id] = nil
+          @answers[request_id] = value
           @condition.broadcast
         end
       end
 
-      private
+      def approved_answer?(answer)
+        answer == true
+      end
 
       def normalize_answers(answers)
         return nil if answers.nil?

data/lib/kward/rpc/runtime_payloads.rb

@@ -2,7 +2,7 @@
 module Kward
   # JSON-RPC backend namespace used by UI clients.
   module RPC
-    # Builders for Tauren-compatible runtime state payloads.
+    # Builders for frontend-neutral runtime state payloads.
     module RuntimePayloads
       module_function