kward 0.75.0 → 0.77.0

data/lib/kward/rpc/session_manager.rb

@@ -62,10 +62,11 @@ module Kward
       RPC_IMAGE_MIME_TYPES = AttachmentNormalizer::IMAGE_MIME_TYPES
       STREAMING_BEHAVIORS = ["newTurn", "followUp", "steer"].freeze
       FOOTER_REFRESH_INTERVAL = 1.0
+      WORKER_STOP_TIMEOUT = 2.0
       WORKER_STOP = Object.new.freeze
 
       RpcSession = Struct.new(:id, :workspace_root, :store, :session, :conversation, :agent, :tool_registry, :prompt, :plugin_output, :queue, :worker, :running_turn_id, :footer_worker, :last_footer_text, keyword_init: true)
-      Turn = Struct.new(:id, :session_id, :input, :display_input, :status, :cancel_requested, :cancellation, :created_at, :started_at, :finished_at, :events, :next_sequence, :error, :streaming_behavior, :plugin_command_name, :plugin_arguments, :steering, :options, :tool_registry, keyword_init: true)
+      Turn = Struct.new(:id, :session_id, :input, :display_input, :status, :cancel_requested, :cancellation, :created_at, :started_at, :finished_at, :events, :next_sequence, :error, :streaming_behavior, :plugin_command_name, :plugin_arguments, :steering, :options, :tool_registry, :mutex, keyword_init: true)
 
       # Creates an object for RPC session lifecycle and turn coordination.
       def initialize(
@@ -74,7 +75,8 @@ module Kward
         config_dir: ConfigFiles.config_dir,
         config_manager: ConfigManager.new(config_path: File.join(config_dir, "config.json")),
         context_usage: ContextUsage.new,
-        session_trash: SessionTrash.new
+        session_trash: SessionTrash.new,
+        worker_stop_timeout: WORKER_STOP_TIMEOUT
       )
         @server = server
         @client = client
@@ -83,6 +85,7 @@ module Kward
         @context_usage = context_usage
         @session_metrics = SessionMetrics.new(context_usage: context_usage)
         @session_trash = session_trash
+        @worker_stop_timeout = worker_stop_timeout
         @sessions = {}
         @turns = {}
         @mutex = Mutex.new
@@ -140,7 +143,11 @@ module Kward
         store = SessionStore.new(config_dir: @config_dir, cwd: root)
         requested_limit = limit.to_i if limit
         requested_limit = nil unless requested_limit&.positive?
-        store.recent(limit: requested_limit, keep_empty_path: current_session_path)
+        live_paths = @mutex.synchronize do
+          @sessions.values.filter_map { |rpc_session| rpc_session.session.path if rpc_session.workspace_root == root }
+        end
+        live_paths << current_session_path unless current_session_path.to_s.empty?
+        store.recent(limit: requested_limit, keep_empty_path: live_paths)
              .map { |info| session_info_payload(info, workspace_root: root) }
       end
 
@@ -325,7 +332,7 @@ module Kward
       # Stops all live RPC session workers during server shutdown.
       def shutdown_sessions
         rpc_sessions = @mutex.synchronize { @sessions.values.dup }
-        rpc_sessions.reverse_each { |rpc_session| close_rpc_session(rpc_session) if session_idle?(rpc_session) }
+        rpc_sessions.reverse_each { |rpc_session| close_rpc_session(rpc_session) }
         { closed: true }
       end
 
@@ -368,7 +375,8 @@ module Kward
           plugin_command_name: plugin_command&.name,
           plugin_arguments: plugin_arguments,
           options: normalized_options,
-          tool_registry: scoped_tool_registry(rpc_session, normalized_options)
+          tool_registry: scoped_tool_registry(rpc_session, normalized_options),
+          mutex: Mutex.new
         )
         @mutex.synchronize { @turns[turn.id] = turn }
         rpc_session.queue << turn.id
@@ -379,12 +387,13 @@ module Kward
 
       def cancel_turn(turn_id:)
         turn = fetch_turn(turn_id)
-        turn.cancel_requested = true
-        turn.cancellation&.cancel!
-        emit_turn_event(turn, "turnCancelRequested", {})
-        if turn.status == "queued"
-          finish_turn(turn, "canceled")
+        queued, event = turn.mutex.synchronize do
+          turn.cancel_requested = true
+          [turn.status == "queued", append_turn_event_locked(turn, "turnCancelRequested", {})]
         end
+        @server.notify("turn/event", event)
+        turn.cancellation&.cancel!
+        finish_turn(turn, "canceled") if queued
         turn_payload(turn)
       end
 
@@ -395,10 +404,12 @@ module Kward
       def turn_events(turn_id:, after_sequence: 0)
         turn = fetch_turn(turn_id)
         after_sequence = after_sequence.to_i
-        {
-          turn: turn_payload(turn),
-          events: turn.events.select { |event| event[:sequence].to_i > after_sequence }
-        }
+        turn.mutex.synchronize do
+          {
+            turn: turn_payload_unlocked(turn),
+            events: turn.events.select { |event| event[:sequence].to_i > after_sequence }
+          }
+        end
       end
 
       def list_turns(session_id: nil, active: false)
@@ -1043,6 +1054,8 @@ module Kward
       end
 
       def close_rpc_session(rpc_session, delete_unused: true)
+        turns = cancel_session_turns(rpc_session)
+        turns.each { |turn| finish_turn(turn, "canceled") } if stop_worker(rpc_session, wait: true)
         remove_live_session(rpc_session)
         rpc_session.session.delete_if_unused if delete_unused && rpc_session.session.respond_to?(:delete_if_unused)
       end
@@ -1066,12 +1079,28 @@ module Kward
         stop_footer_worker(rpc_session)
       end
 
-      def stop_worker(rpc_session)
+      def stop_worker(rpc_session, wait: false)
         worker = rpc_session.worker
-        return unless worker&.alive?
-        return if worker == Thread.current
+        return false unless worker&.alive?
+        return false if worker == Thread.current
 
         rpc_session.queue << WORKER_STOP
+        return false unless wait
+
+        worker.join(@worker_stop_timeout)
+        return false unless worker.alive?
+
+        worker.kill
+        worker.join
+        true
+      end
+
+      def cancel_session_turns(rpc_session)
+        turns = @mutex.synchronize do
+          @turns.values.select { |turn| turn.session_id == rpc_session.id && ["queued", "running"].include?(turn.status) }
+        end
+        turns.each { |turn| cancel_turn(turn_id: turn.id) }
+        turns
       end
 
       def start_footer_worker(rpc_session)
@@ -1128,11 +1157,18 @@ module Kward
       def run_turn(rpc_session, turn)
         previous_turn_id = Thread.current[:kward_rpc_turn_id]
         Thread.current[:kward_rpc_turn_id] = turn.id
+        started, event = turn.mutex.synchronize do
+          next [false, nil] if turn.status == "canceled"
+
+          turn.status = "running"
+          turn.started_at = now
+          [true, append_turn_event_locked(turn, "turnStarted", { status: "running" })]
+        end
+        return unless started
+
+        @server.notify("turn/event", event)
         rpc_session.running_turn_id = turn.id
         turn.steering = build_steering(turn) if supports_in_flight_steer? && !turn.plugin_command_name
-        turn.status = "running"
-        turn.started_at = now
-        emit_turn_event(turn, "turnStarted", { status: "running" })
 
         if turn.cancel_requested
           finish_turn(turn, "canceled")
@@ -1256,6 +1292,8 @@ module Kward
         case event
         when Events::ReasoningDelta
           emit_turn_event(turn, "reasoningDelta", { delta: event.delta })
+        when Events::ReasoningBoundary
+          emit_turn_event(turn, "reasoningBoundary", {})
         when Events::AssistantDelta
           emit_turn_event(turn, "assistantDelta", { delta: event.delta })
         when Events::AssistantMessage
@@ -1290,11 +1328,16 @@ module Kward
       end
 
       def finish_turn(turn, status)
-        return if ["completed", "failed", "canceled"].include?(turn.status)
+        event = turn.mutex.synchronize do
+          next nil if ["completed", "failed", "canceled"].include?(turn.status)
+
+          turn.status = status
+          turn.finished_at = now
+          append_turn_event_locked(turn, "turnFinished", { status: status, error: turn.error })
+        end
+        return unless event
 
-        turn.status = status
-        turn.finished_at = now
-        emit_turn_event(turn, "turnFinished", { status: status, error: turn.error })
+        @server.notify("turn/event", event)
         rpc_session = @mutex.synchronize { @sessions[turn.session_id] }
         emit_footer_update(rpc_session) if rpc_session
       end
@@ -1324,6 +1367,12 @@ module Kward
       end
 
       def emit_turn_event(turn, type, payload)
+        event = turn.mutex.synchronize { append_turn_event_locked(turn, type, payload) }
+        @server.notify("turn/event", event)
+        event
+      end
+
+      def append_turn_event_locked(turn, type, payload)
         event = {
           sequence: turn.next_sequence,
           timestamp: now,
@@ -1335,7 +1384,6 @@ module Kward
         turn.next_sequence += 1
         turn.events << event
         turn.events.shift while turn.events.length > RECENT_EVENT_LIMIT
-        @server.notify("turn/event", event)
         event
       end
 
@@ -1349,6 +1397,10 @@ module Kward
       end
 
       def turn_payload(turn)
+        turn.mutex.synchronize { turn_payload_unlocked(turn) }
+      end
+
+      def turn_payload_unlocked(turn)
         {
           id: turn.id,
           sessionId: turn.session_id,

data/lib/kward/rpc/tool_event_normalizer.rb

@@ -65,6 +65,8 @@ module Kward
           if mutation_tool?
             diff = ToolMetadata.extract_unified_diff(text)
             result[:diff] = diff if diff
+            first_changed_line = ToolMetadata.first_changed_line(diff)
+            result[:firstChangedLine] = first_changed_line if first_changed_line
           end
 
           files = changed_files

data/lib/kward/rpc/tool_metadata.rb

@@ -75,6 +75,29 @@ module Kward
         index ? text.to_s[index..] : nil
       end
 
+      # Returns the first changed line in the post-edit file from a unified diff.
+      # A deletion-only hunk uses the next surviving new-file line as its anchor.
+      def first_changed_line(diff)
+        new_line = nil
+
+        diff.to_s.each_line do |line|
+          if (match = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/))
+            new_line = match[1].to_i
+          elsif new_line
+            case line
+            when /^\+[^+]/
+              return new_line
+            when /^-[^-]/
+              return new_line
+            when /^ /
+              new_line += 1
+            end
+          end
+        end
+
+        nil
+      end
+
       def changed_files_from_result(text, matching_call = nil)
         path = matching_call&.dig(:arguments, :path) || matching_call&.dig(:arguments, "path")
         return [path] if path

data/lib/kward/rpc/transcript_normalizer.rb

@@ -157,18 +157,19 @@ module Kward
       end
 
       def response_item_content(message)
-        response_items(message).filter_map do |item|
-          next unless item.is_a?(Hash)
+        response_items(message).flat_map do |item|
+          next [] unless item.is_a?(Hash)
 
           case ToolCall.value(item, :type).to_s
           when "reasoning"
-            thinking = reasoning_item_text(item)
-            { type: "thinking", thinking: thinking } unless thinking.empty?
+            reasoning_item_blocks(item).map { |thinking| { type: "thinking", thinking: thinking } }
           when "message"
-            next if ToolCall.value(item, :phase).to_s == "commentary"
+            next [] if ToolCall.value(item, :phase).to_s == "commentary"
 
             text = response_message_item_text(item)
-            { type: "text", text: text } unless text.empty?
+            text.empty? ? [] : [{ type: "text", text: text }]
+          else
+            []
           end
         end
       end
@@ -177,10 +178,9 @@ module Kward
         MessageAccess.response_items(message)
       end
 
-      def reasoning_item_text(item)
-        summary = ToolCall.value(item, :summary)
-        content = ToolCall.value(item, :content)
-        response_text_parts(summary).empty? ? response_text_parts(content).join("\n\n") : response_text_parts(summary).join("\n\n")
+      def reasoning_item_blocks(item)
+        summary = response_text_parts(ToolCall.value(item, :summary))
+        summary.empty? ? response_text_parts(ToolCall.value(item, :content)) : summary
       end
 
       def response_message_item_text(item)
@@ -246,6 +246,8 @@ module Kward
 
         diff = details[:diff] || details["diff"] || ToolMetadata.extract_unified_diff(text)
         details[:diff] = diff if diff
+        first_changed_line = details[:firstChangedLine] || details["firstChangedLine"] || ToolMetadata.first_changed_line(diff)
+        details[:firstChangedLine] = first_changed_line if first_changed_line
 
         changed_files = details[:changedFiles] || details["changedFiles"] || ToolMetadata.changed_files_from_result(text, matching_call)
         details[:changedFiles] = changed_files if changed_files && !changed_files.empty?
@@ -257,6 +259,8 @@ module Kward
         allowed = {}
         diff = ToolCall.value(details, :diff)
         allowed[:diff] = diff if diff
+        first_changed_line = ToolCall.value(details, :firstChangedLine) || ToolCall.value(details, :first_changed_line)
+        allowed[:firstChangedLine] = first_changed_line if first_changed_line.is_a?(Integer) && first_changed_line.positive?
         changed_files = ToolCall.value(details, :changedFiles) || ToolCall.value(details, :changed_files)
         allowed[:changedFiles] = changed_files if changed_files.is_a?(Array)
         allowed

data/lib/kward/session_store.rb

@@ -309,11 +309,10 @@ module Kward
     # Lists recent non-empty sessions for this workspace.
     #
     # @param limit [Integer, nil] maximum number of sessions, or nil for all
-    # @param keep_empty_path [String, nil] empty session path to keep visible
+    # @param keep_empty_path [String, Array<String>, nil] live empty session path(s) to preserve while omitting them from results
     # @return [Array<SessionInfo>] newest sessions first
     def recent(limit: 20, keep_empty_path: nil)
-      sessions = recent_sessions(keep_empty_path: keep_empty_path)
-      limit ? sessions.first(limit) : sessions
+      recent_sessions(limit: limit, keep_empty_path: keep_empty_path)
     end
 
     # Persists the last active session pointer for workspace auto-resume.
@@ -344,9 +343,7 @@ module Kward
     #
     # @return [Array<SessionInfo>] recent sessions with tree depth fields
     def recent_tree(limit: 20, keep_empty_path: nil)
-      sessions = recent_sessions(keep_empty_path: keep_empty_path)
-      sessions = sessions.first(limit) if limit
-      decorate_tree(sessions)
+      decorate_tree(recent_sessions(limit: limit, keep_empty_path: keep_empty_path))
     end
 
     # Deletes an empty unnamed session file.
@@ -770,20 +767,30 @@ module Kward
       nil
     end
 
-    def recent_sessions(keep_empty_path: nil)
-      keep_empty_path = File.expand_path(keep_empty_path) unless keep_empty_path.to_s.empty?
-      Dir.glob(File.join(session_dir, "*.jsonl")).filter_map do |path|
-        info = session_info(path)
-        next unless info
-        next if delete_empty_unnamed_session_info(info, keep_empty_path: keep_empty_path)
+    def recent_sessions(limit: nil, keep_empty_path: nil)
+      keep_empty_paths = Array(keep_empty_path).filter_map do |path|
+        File.expand_path(path) unless path.to_s.empty?
+      end
+      paths = Dir.glob(File.join(session_dir, "*.jsonl")).sort_by { |path| session_file_mtime(path) }.reverse
+      sessions = []
+
+      paths.each do |path|
+        if limit.nil? || sessions.length < limit
+          info = session_info(path)
+          next unless info
+          next if delete_empty_unnamed_session_info(info, keep_empty_paths: keep_empty_paths)
 
-        info
-      end.sort_by { |info| info.modified_at || Time.at(0) }.reverse
+          sessions << info
+        else
+          delete_empty_unnamed_session_path(path, keep_empty_paths: keep_empty_paths)
+        end
+      end
+      sessions
     end
 
-    def delete_empty_unnamed_session_info(info, keep_empty_path: nil)
+    def delete_empty_unnamed_session_info(info, keep_empty_paths: [])
       return false unless info.name.to_s.strip.empty? && info.message_count.to_i.zero?
-      return true if keep_empty_path && File.expand_path(info.path) == keep_empty_path
+      return true if keep_empty_paths.include?(File.expand_path(info.path))
 
       File.delete(info.path)
       true
@@ -791,6 +798,38 @@ module Kward
       false
     end
 
+    def session_file_mtime(path)
+      File.mtime(path)
+    rescue StandardError
+      Time.at(0)
+    end
+
+    def delete_empty_unnamed_session_path(path, keep_empty_paths: [])
+      return false unless empty_unnamed_session_path?(path)
+      return true if keep_empty_paths.include?(File.expand_path(path))
+
+      File.delete(path)
+      true
+    rescue StandardError
+      false
+    end
+
+    def empty_unnamed_session_path?(path)
+      header = false
+      name = nil
+      File.foreach(path) do |line|
+        record = JSON.parse(line)
+        header = true if record["type"] == "session" && !record["id"].to_s.empty?
+        name = record["name"] if record["type"] == "session_info" && record.key?("name")
+        next unless record["type"] == "message"
+
+        return false if ["user", "assistant", "tool"].include?(message_role(record["message"] || {}))
+      end
+      header && name.to_s.strip.empty?
+    rescue JSON::ParserError
+      false
+    end
+
     def decorate_tree(sessions)
       by_parent = Hash.new { |hash, key| hash[key] = [] }
       ids = sessions.map(&:id).to_h { |id| [id, true] }

data/lib/kward/skills/registry.rb

@@ -4,7 +4,13 @@ require "pathname"
 module Kward
   # Skill discovery and metadata parsing from configured skill folders.
   module Skills
-    # Parsed skill metadata and instruction path.
+    # Discovers Agent Skills and reads their bounded instruction resources.
+    #
+    # Project sources are included only when the caller marks them trusted. If
+    # duplicate skill names exist, the first source in documented precedence
+    # order wins.
+    #
+    # @api public
     class Registry
       SkillSource = Struct.new(:root, :label, :scope, :precedence, keyword_init: true)
 
@@ -18,6 +24,10 @@ module Kward
         @inside_directory = inside_directory
       end
 
+      # Returns discovered, validated skills in precedence order.
+      #
+      # @return [Array<ConfigFiles::Skill>]
+      # @api public
       def skills
         seen = {}
         skill_sources.flat_map do |source|
@@ -39,6 +49,16 @@ module Kward
         []
       end
 
+      # Reads a skill's main instructions or a bounded relative resource.
+      #
+      # Absolute paths, paths escaping the skill folder, missing files, and files
+      # above the configured size limit return user-facing error strings.
+      #
+      # @param name [String, #to_s] discovered skill name
+      # @param relative_path [String, nil] file relative to the skill directory;
+      #   defaults to `SKILL.md`
+      # @return [String] skill content or an error message
+      # @api public
       def read_skill_file(name, relative_path = nil)
         skill = skills.find { |candidate| candidate.name == name.to_s }
         return "Error: unknown skill: #{name}" unless skill

data/lib/kward/tools/base.rb

@@ -3,11 +3,22 @@ module Kward
   # Model-callable tool wrappers and their argument schemas.
   module Tools
     # Base class for model-callable tools and their JSON schemas.
+    #
+    # Concrete built-in tools initialize this class with their model-facing name,
+    # description, and strict argument schema, then implement `call` to perform
+    # the operation. Tool execution is coordinated by {Kward::ToolRegistry}.
+    #
+    # @api public
     class Base
       # @return [String] function name exposed to the model
       attr_reader :name
 
       # Creates a tool schema definition shared by all concrete tool wrappers.
+      #
+      # @param name [String] function name exposed to the model
+      # @param description [String] model-facing description of the operation
+      # @param properties [Hash] JSON Schema properties keyed by argument name
+      # @param required [Array<String, Symbol>] required argument names
       def initialize(name, description, properties: {}, required: [])
         @name = name
         @description = description
@@ -16,6 +27,9 @@ module Kward
       end
 
       # Returns the strict JSON schema advertised to model providers.
+      #
+      # @return [Hash] function schema with additional properties disabled
+      # @api public
       def schema
         {
           type: "function",

data/lib/kward/tools/registry.rb

@@ -46,11 +46,12 @@ module Kward
   # individual tools, and legacy-compatible shapes are accepted where already
   # supported. Required fields and invalid required values should still return
   # explicit tool errors.
+  # @api public
   class ToolRegistry
     # Tool schemas advertised to the model for the current frontend and config.
     #
     # @return [Array<Hash>] tool schemas currently advertised to the model
-    attr_reader :schemas, :writer_id
+    attr_reader :schemas
 
     # Builds tool objects and the schema list for the current frontend/config.
     #
@@ -63,7 +64,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, tool_approval: nil, hook_manager: nil, hook_context: 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, 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
@@ -73,8 +74,6 @@ module Kward
       @web_search_enabled = web_search_enabled
       @ask_user_question_enabled = ask_user_question_enabled
       @allowed_tool_names = allowed_tool_names&.map(&:to_s)
-      @write_lock = write_lock
-      @writer_id = writer_id
       @tool_output_compactor = tool_output_compactor
       @telemetry_logger = telemetry_logger
       @context_budget_meter = context_budget_meter
@@ -115,8 +114,6 @@ module Kward
                              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
@@ -148,6 +145,14 @@ module Kward
       model_content
     end
 
+    # Returns frontend discovery metadata for a tool name.
+    #
+    # Unknown names return metadata with an unknown source rather than raising,
+    # which lets RPC clients render restored or unsupported tool calls safely.
+    #
+    # @param name [String, #to_s] exposed tool name
+    # @return [Hash] source, display name, and optional MCP identity
+    # @api public
     def metadata_for(name)
       tool = @tools[name.to_s]
       return unknown_tool_metadata(name) unless tool
@@ -415,22 +420,12 @@ module Kward
       (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
-
-      @write_lock.owned_by?(@writer_id)
-    end
-
     def build_tools
       tools = all_tools
       tools = tools.select { |tool| @allowed_tool_names.include?(tool.name) } if @allowed_tool_names

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

@@ -1,4 +1,4 @@
-require "cgi"
+require "cgi/escape"
 require "fileutils"
 require "json"
 require "net/http"

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

@@ -1,4 +1,4 @@
-require "cgi"
+require "cgi/escape"
 require "json"
 require "net/http"
 require "nokogiri"

data/lib/kward/tools/tool_call.rb

@@ -67,10 +67,6 @@ module Kward
       TOOL_NAME_MAP[name.to_s]
     end
 
-    def write_lock_required?(name)
-      %w[edit_file write_file run_shell_command edit write bash].include?(name.to_s)
-    end
-
     def file_change_tool?(name)
       %w[edit_file write_file edit write].include?(name.to_s)
     end

data/lib/kward/transcript_export.rb

@@ -1,4 +1,4 @@
-require "cgi"
+require "cgi/escape"
 require_relative "markdown_transcript"
 
 # Namespace for the Kward CLI agent runtime.

data/lib/kward/update_check.rb

@@ -29,15 +29,11 @@ module Kward
       true
     end
 
-    def notice
+    def notice(refresh: false)
       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)
+      refresh_if_stale if refresh
+      notice_from_cache
     end
 
     def refresh_if_stale
@@ -69,6 +65,15 @@ module Kward
       cache["dismissed_version"].to_s
     end
 
+    def notice_from_cache
+      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 stale?
       checked_at = Time.iso8601(cache["checked_at"].to_s)
       (@now - checked_at) >= CHECK_INTERVAL_SECONDS

data/lib/kward/version.rb

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