kward 0.80.1 → 0.81.0

data/lib/kward/cli.rb

@@ -59,6 +59,8 @@ require_relative "cli/sysprompt"
 require_relative "cli/stats"
 require_relative "cli/openrouter_commands"
 require_relative "cli/runtime_helpers"
+require_relative "cli/project_skills"
+require_relative "cli/project_skills_commands"
 require_relative "cli/slash_commands"
 require_relative "cli/memory_commands"
 require_relative "cli/hook_commands"
@@ -94,6 +96,8 @@ module Kward
     include CLI::Stats
     include CLI::OpenRouterCommands
     include CLI::RuntimeHelpers
+    include CLI::ProjectSkills
+    include CLI::ProjectSkillsCommands
     include CLI::SlashCommands
     include CLI::MemoryCommands
     include CLI::HookCommands
@@ -232,6 +236,16 @@ module Kward
         return
       end
 
+      if @argv.first == "skills"
+        if help_option_arguments?(@argv[1..] || [])
+          print_command_help("skills")
+          return
+        end
+
+        handle_project_skills_cli_command(@argv[1..] || [])
+        return
+      end
+
       if @argv.first == "edit"
         if help_option_arguments?(@argv[1..] || [])
           print_command_help("edit")
@@ -430,7 +444,8 @@ module Kward
     end
 
     def interactive_loop(agent: nil)
-      setup_interactive_prompt
+      setup_interactive_prompt(defer_warnings: true)
+      prepare_interactive_project_skills
       session_store = interactive_session_store(agent)
       @resumed_last_session = false
       if session_store && @prompt.respond_to?(:update_tabs)
@@ -450,8 +465,10 @@ module Kward
 
       print_visual_banner unless @resumed_last_session || @restored_tabs
       render_resumed_last_session_transcript(agent.conversation) if @resumed_last_session
+      enable_interactive_warnings if respond_to?(:enable_interactive_warnings, true)
 
       @pending_inputs = []
+      install_bang_completion_provider(agent)
 
       loop do
         if @pending_inputs.empty? && active_tab&.shell
@@ -543,6 +560,7 @@ module Kward
       runtime_output("Goodbye.")
       active_tab&.agent&.conversation || agent&.conversation
     ensure
+      clear_bang_completion_provider
       begin
         stop_tabs if respond_to?(:stop_tabs, true)
         @prompt.close if prompt_interface?

data/lib/kward/config_files.rb

@@ -917,8 +917,12 @@ module Kward
     # Lists configured skills discovered under the config directory.
     #
     # @return [Array<Skill>] skill metadata available to the model
-    def skills(workspace_root: Dir.pwd, warning_sink: nil)
-      skills_registry(workspace_root: workspace_root, warning_sink: warning_sink).skills
+    def skills(workspace_root: Dir.pwd, warning_sink: nil, project_skill_paths: nil)
+      skills_registry(workspace_root: workspace_root, warning_sink: warning_sink, project_skill_paths: project_skill_paths).skills
+    end
+
+    def project_skill_candidates(workspace_root: Dir.pwd, warning_sink: nil)
+      skills_registry(workspace_root: workspace_root, warning_sink: warning_sink).project_skill_candidates
     end
 
     # @return [String] trusted user plugin directory
@@ -961,7 +965,7 @@ module Kward
       skills_registry(workspace_root: workspace_root).read_skill_file(name, relative_path)
     end
 
-    def skills_registry(workspace_root: Dir.pwd, warning_sink: nil)
+    def skills_registry(workspace_root: Dir.pwd, warning_sink: nil, project_skill_paths: nil)
       Skills::Registry.new(
         config_dir: config_dir,
         workspace_root: workspace_root,
@@ -970,7 +974,8 @@ module Kward
         max_file_bytes: MAX_SKILL_FILE_BYTES,
         markdown_parser: ->(path) { Frontmatter.markdown_parts(path, lenient: true) },
         inside_directory: method(:inside_directory?),
-        warning_sink: warning_sink || @warning_sink
+        warning_sink: warning_sink || @warning_sink,
+        project_skill_paths: project_skill_paths
       )
     end
 

data/lib/kward/conversation.rb

@@ -63,13 +63,16 @@ module Kward
     attr_reader :tool_output_artifacts
     # @return [ContextBudgetMeter] runtime context savings for this conversation
     attr_reader :context_budget_meter
+    # @return [Array<String>, nil] explicitly permitted project skill paths
+    attr_reader :project_skill_paths
 
-    def initialize(system_message: DEFAULT_SYSTEM_MESSAGE, messages: [], read_paths: [], on_append: nil, on_compact: nil, on_tool_execution: nil, on_runtime_update: nil, workspace_root: Dir.pwd, compaction_system_message: DEFAULT_SYSTEM_MESSAGE, provider: nil, model: nil, reasoning_effort: nil, memory_context: nil, session_memories: [], last_memory_retrieval: nil, plugin_registry: nil, execution_profile_context: nil)
+    def initialize(system_message: DEFAULT_SYSTEM_MESSAGE, messages: [], read_paths: [], on_append: nil, on_compact: nil, on_tool_execution: nil, on_runtime_update: nil, workspace_root: Dir.pwd, compaction_system_message: DEFAULT_SYSTEM_MESSAGE, provider: nil, model: nil, reasoning_effort: nil, memory_context: nil, session_memories: [], last_memory_retrieval: nil, plugin_registry: nil, execution_profile_context: nil, project_skill_paths: nil)
       @workspace_root = ConfigFiles.canonical_workspace_root(workspace_root)
       @provider = provider
       @model = model
       @reasoning_effort = reasoning_effort
       @plugin_registry = plugin_registry
+      @project_skill_paths = project_skill_paths
       @execution_profile_context = execution_profile_context.to_s.empty? ? nil : execution_profile_context.to_s.freeze
       @messages = []
       restored_system_message, transcript_messages = split_system_message(messages)
@@ -78,13 +81,13 @@ module Kward
           system_message = restored_system_message
         else
           @last_plugin_prompt_context = plugin_prompt_context
-          system_message = Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, memory_context: memory_context, plugin_context: @last_plugin_prompt_context, execution_profile_context: @execution_profile_context)
+          system_message = Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, memory_context: memory_context, plugin_context: @last_plugin_prompt_context, execution_profile_context: @execution_profile_context, project_skill_paths: @project_skill_paths)
         end
       end
       @system_message = system_message
       @system_message_enabled = !@system_message.nil?
       if compaction_system_message.equal?(DEFAULT_SYSTEM_MESSAGE)
-        compaction_system_message = @system_message_enabled ? Prompts.system_message(workspace_root: @workspace_root, include_workspace_personality: false, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, execution_profile_context: @execution_profile_context) : nil
+        compaction_system_message = @system_message_enabled ? Prompts.system_message(workspace_root: @workspace_root, include_workspace_personality: false, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, execution_profile_context: @execution_profile_context, project_skill_paths: @project_skill_paths) : nil
       end
       @compaction_system_message = compaction_system_message
       @workspace_agents_mtime = workspace_agents_mtime
@@ -188,10 +191,10 @@ module Kward
       return nil unless @system_message_enabled
 
       @last_plugin_prompt_context = plugin_prompt_context
-      replacement = Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, memory_context: @memory_context, plugin_context: @last_plugin_prompt_context, execution_profile_context: @execution_profile_context)
+      replacement = Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, memory_context: @memory_context, plugin_context: @last_plugin_prompt_context, execution_profile_context: @execution_profile_context, project_skill_paths: @project_skill_paths)
       @system_message = replacement
       @on_system_message_change&.call(replacement)
-      @compaction_system_message = Prompts.system_message(workspace_root: @workspace_root, include_workspace_personality: false, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, execution_profile_context: @execution_profile_context)
+      @compaction_system_message = Prompts.system_message(workspace_root: @workspace_root, include_workspace_personality: false, model: @model, reasoning_effort: @reasoning_effort, now: prompt_time, execution_profile_context: @execution_profile_context, project_skill_paths: @project_skill_paths)
       @workspace_agents_mtime = workspace_agents_mtime
       @system_prompt_sources_fingerprint = ConfigFiles.system_prompt_sources_fingerprint
       replacement

data/lib/kward/ekwsh.rb

@@ -13,7 +13,7 @@ module Kward
   class Ekwsh
     Result = Struct.new(:output, :exit_status, :exit_shell, :clear, :open_editor_path, :interactive_command, :streamed, keyword_init: true)
     Completion = Struct.new(:range, :replacement, :candidates, keyword_init: true)
-    BUILTINS = %w[alias cd pwd export unset unalias clear exit logout pty].freeze
+    BUILTINS = %w[alias capture cd pwd export unset unalias clear exit logout pty].freeze
     DEFAULT_SHELL = "/bin/sh"
     DEFAULT_TIMEOUT_SECONDS = 300
     DEFAULT_MAX_OUTPUT_BYTES = 1_048_576
@@ -72,6 +72,23 @@ module Kward
       Completion.new(range: token[:range], replacement: replacement, candidates: candidates)
     end
 
+    def expand_alias(command, interactive: false)
+      words = shell_words(command)
+      return command if words.empty? || BUILTINS.include?(words.first)
+      return command unless @aliases[words.first]
+
+      rest = command.sub(/\A\s*#{Regexp.escape(words.first)}\b\s*/, "")
+      expanded = [@aliases.fetch(words.first), rest].reject(&:empty?).join(" ")
+      interactive ? expanded.sub(/\A\s*(?:capture|pty)(?:\s+|\z)/, "") : expanded
+    rescue ArgumentError
+      command
+    end
+
+    def editor_command_result(command, display_command: command)
+      expanded_command = expand_alias(command, interactive: true)
+      kward_command_result(expanded_command, display_command: display_command)
+    end
+
     private
 
     def configure_rbenv_environment
@@ -276,7 +293,7 @@ module Kward
       Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 2)
     end
 
-    def builtin_result(command, display_command: command)
+    def builtin_result(command, display_command: command, cancellation: nil, &block)
       words = shell_words(command)
       return nil if words.empty?
       assignment_result = persist_assignments(display_command, words)
@@ -297,6 +314,8 @@ module Kward
         unset_variables(display_command, words)
       when "clear"
         Result.new(output: "", exit_status: 0, clear: true)
+      when "capture"
+        captured_command_result(command, display_command: display_command, cancellation: cancellation, &block)
       when "pty"
         interactive_pty_result(command, display_command: display_command)
       else
@@ -306,13 +325,26 @@ module Kward
       Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 2)
     end
 
+    def captured_command_result(command, display_command:, cancellation: nil, &block)
+      captured_command = command.sub(/\A\s*capture(?:\s+|\z)/, "")
+      if captured_command.empty?
+        return Result.new(output: "#{command_echo(display_command)}Usage: capture <command>\n", exit_status: 2)
+      end
+
+      execute(captured_command, display_command: display_command, cancellation: cancellation, &block)
+    end
+
     def interactive_pty_result(command, display_command: command)
       interactive_command = command.sub(/\A\s*pty(?:\s+|\z)/, "")
       if interactive_command.empty?
         return Result.new(output: "#{command_echo(display_command)}Usage: pty <command>\n", exit_status: 2)
       end
 
-      Result.new(output: "#{command_echo(display_command)}[interactive PTY session started]\n", exit_status: 0, interactive_command: interactive_command)
+      interactive_command_result(interactive_command, display_command: display_command)
+    end
+
+    def interactive_command_result(command, display_command: command)
+      Result.new(output: command_echo(display_command), exit_status: 0, interactive_command: command)
     end
 
     def shell_words(command)
@@ -361,29 +393,18 @@ module Kward
       name.to_s.match?(/\A[A-Za-z_][A-Za-z0-9_-]*\z/) && !BUILTINS.include?(name.to_s)
     end
 
-    def expand_alias(command)
-      words = shell_words(command)
-      return command if words.empty? || BUILTINS.include?(words.first)
-      return command unless @aliases[words.first]
-
-      rest = command.sub(/\A\s*#{Regexp.escape(words.first)}\b\s*/, "")
-      [@aliases.fetch(words.first), rest].reject(&:empty?).join(" ")
-    rescue ArgumentError
-      command
-    end
-
     def run_expanded_command(command, cancellation: nil, &block)
       expanded_command = expand_alias(command)
       exit_result = exit_result(expanded_command, display_command: command)
       return exit_result if exit_result
 
-      builtin_result = builtin_result(expanded_command, display_command: command)
+      builtin_result = builtin_result(expanded_command, display_command: command, cancellation: cancellation, &block)
       return builtin_result if builtin_result
 
       kward_result = kward_command_result(expanded_command, display_command: command)
       return kward_result if kward_result
 
-      execute(expanded_command, display_command: command, cancellation: cancellation, &block)
+      interactive_command_result(expanded_command, display_command: command)
     end
 
     def kward_command_result(command, display_command: command)

data/lib/kward/interactive_pty_runner.rb

@@ -9,7 +9,7 @@ module Kward
   # This is intentionally low level: UI orchestration decides when terminal
   # ownership is handed to the child process and how the result is presented.
   class InteractivePtyRunner
-    Result = Struct.new(:exit_status, keyword_init: true)
+    Result = Struct.new(:exit_status, :input_forwarded, keyword_init: true)
 
     READ_SIZE = 4096
 
@@ -18,34 +18,27 @@ module Kward
       @window_size = nil
     end
 
-    def run(*command, env: {}, cwd: Dir.pwd, input: $stdin, output: $stdout)
+    def run(*command, env: {}, cwd: Dir.pwd, input: $stdin, output: $stdout, &block)
       pid = nil
       status = nil
+      writer = nil
+      input_forwarded = false
 
-      PTY.spawn(env.to_h, *command, chdir: cwd.to_s) do |reader, writer, child_pid|
+      PTY.spawn(env.to_h, *command, chdir: cwd.to_s) do |reader, child_writer, child_pid|
         pid = child_pid
+        writer = child_writer
         update_window_size(reader, pid)
         with_raw_input(input) do
           drain_initial_input(input, writer)
-          loop do
-            update_window_size(reader, pid)
-            readable = IO.select([reader, input], nil, nil, 0.02)&.first || []
-            forward_pty_output(reader, output) if readable.include?(reader)
-            forward_input(input, writer) if readable.include?(input)
-            if (finished_status = finished_status(pid))
-              status = finished_status
-              break
-            end
-          rescue Errno::EIO, IOError
-            break
-          end
+          status, input_forwarded = forward_io(reader, writer, pid, input, output, &block)
         end
         status ||= wait_for_status(pid)
-      ensure
-        writer&.close unless writer&.closed?
       end
 
-      Result.new(exit_status: exit_status(status))
+      Result.new(exit_status: exit_status(status), input_forwarded: input_forwarded)
+    ensure
+      writer&.close unless writer&.closed?
+      terminate_and_reap(pid) if pid && status.nil?
     end
 
     private
@@ -53,8 +46,14 @@ module Kward
     def with_raw_input(input)
       return yield unless input.respond_to?(:raw)
 
-      input.raw { yield }
+      yielded = false
+      input.raw do
+        yielded = true
+        yield
+      end
     rescue Errno::ENOTTY
+      raise if yielded
+
       yield
     end
 
@@ -70,22 +69,67 @@ module Kward
       nil
     end
 
+    def forward_io(reader, writer, pid, input, output, &block)
+      input_open = true
+      input_forwarded = false
+      loop do
+        update_window_size(reader, pid)
+        readers = [reader]
+        readers << input if input_open
+        readable = IO.select(readers, nil, nil, 0.02)&.first || []
+        forward_pty_output(reader, output, &block) if readable.include?(reader)
+        if input_open && readable.include?(input)
+          input_open, forwarded = forward_input(input, writer)
+          input_forwarded ||= forwarded
+        end
+
+        status = finished_status(pid)
+        next unless status
+
+        return [finish_stopped_process(pid), input_forwarded] if status.stopped?
+
+        drain_pty_output(reader, output, &block)
+        return [status, input_forwarded]
+      rescue Errno::EIO
+        return [wait_for_status(pid), input_forwarded]
+      end
+    end
+
     def forward_pty_output(reader, output)
       chunk = reader.read_nonblock(READ_SIZE, exception: false)
       return if chunk.nil? || chunk == :wait_readable
 
       output.write(chunk)
       output.flush if output.respond_to?(:flush)
+      yield chunk if block_given?
+    end
+
+    def drain_pty_output(reader, output)
+      loop do
+        readable, = IO.select([reader], nil, nil, 0.02)
+        break unless readable
+
+        chunk = reader.read_nonblock(READ_SIZE, exception: false)
+        break if chunk.nil? || chunk == :wait_readable
+
+        output.write(chunk)
+        yield chunk if block_given?
+      end
+      output.flush if output.respond_to?(:flush)
+    rescue Errno::EIO
+      nil
     end
 
     def forward_input(input, writer)
       chunk = input.read_nonblock(READ_SIZE, exception: false)
-      return if chunk.nil? || chunk == :wait_readable
+      return [false, false] if chunk.nil?
+      return [true, false] if chunk == :wait_readable
 
       writer.write(chunk)
       writer.flush
+      [true, true]
     rescue Errno::EIO, Errno::EPIPE, IOError
-      nil
+      [false, false]
     end
 
     def update_window_size(reader, pid)
@@ -111,12 +155,18 @@ module Kward
     def finished_status(pid)
       return unless pid
 
-      finished_pid, status = Process.wait2(pid, Process::WNOHANG)
+      finished_pid, status = Process.wait2(pid, Process::WNOHANG | Process::WUNTRACED)
       status if finished_pid
     rescue Errno::ECHILD
       nil
     end
 
+    def finish_stopped_process(pid)
+      signal_process("CONT", -pid) || signal_process("CONT", pid)
+      terminate_process_group(pid)
+      wait_for_status(pid)
+    end
+
     def wait_for_status(pid)
       return unless pid
 
@@ -134,6 +184,22 @@ module Kward
       1
     end
 
+    def terminate_and_reap(pid)
+      terminate_process_group(pid)
+      wait_for_status(pid)
+    end
+
+    def terminate_process_group(pid)
+      signal_process("TERM", -pid) || signal_process("TERM", pid)
+      deadline = Time.now + 0.2
+      while Time.now < deadline
+        return unless process_running?(pid)
+
+        sleep 0.02
+      end
+      signal_process("KILL", -pid) || signal_process("KILL", pid)
+    end
+
     def process_running?(pid)
       Process.kill(0, pid)
       true

data/lib/kward/prompt_interface/composer_controller.rb

@@ -256,11 +256,23 @@ module Kward
       def submit_input
         value = submitted_input
         add_history(composer_input)
-        clear_finished_input_locked(reset_history: true)
+        if !@busy && value.strip.empty?
+          @output_io.flush
+          return value
+        end
+
+        clear_submitted_input_locked
         @output_io.flush
         value
       end
 
+      def clear_submitted_input_locked
+        self.composer_input = ""
+        self.composer_cursor = 0
+        @composer.clear_attachments
+        reset_history_search
+      end
+
       def clear_finished_input_locked(reset_history: false)
         if @busy
           clear_prompt_for_output_locked

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

@@ -827,6 +827,10 @@ module Kward
         modifier = sequence[:modifier]
         queue_pending_keys(sequence[:remaining]) if sequence[:remaining] && !sequence[:remaining].empty?
 
+        if ctrl_modifier?(modifier) && ctrl_code(code) == 113
+          return close_editor
+        end
+
         if ctrl_modifier?(modifier) && ctrl_code(code) == 102
           return editor_search_active? ? editor_search_append(key) : editor_search_begin
         end

data/lib/kward/prompt_interface/key_handler.rb

@@ -36,6 +36,9 @@ module Kward
         return true if handle_mouse_reporting_key(key)
         return if handle_bracketed_paste_key(key)
 
+        completion_overlay_result = handle_completion_overlay_key(key)
+        return completion_overlay_result unless completion_overlay_result == false
+
         csi_result = handle_csi_u_key(key)
         return csi_result unless csi_result == false
         return if handle_shift_enter_key(key)
@@ -44,9 +47,6 @@ module Kward
         completion_result = handle_completion_provider_key(key)
         return completion_result unless completion_result == false
 
-        reasoning_result = handle_reasoning_key_binding(key)
-        return reasoning_result unless reasoning_result == false
-
         tab_result = handle_tab_key_binding(key)
         return tab_result unless tab_result == false
 
@@ -81,7 +81,7 @@ module Kward
         when :ctrl_y
           yank_kill_buffer
         when :ctrl_l
-          redraw_screen_locked
+          request_transcript_redraw
         when :ctrl_r
           start_history_search
         when :left
@@ -212,9 +212,6 @@ module Kward
         return true if sequence == "\e" && (dismiss_file_overlay || dismiss_slash_overlay)
         return true if handle_shift_enter_key(sequence)
 
-        reasoning_result = handle_reasoning_key_binding(sequence)
-        return reasoning_result unless reasoning_result == false
-
         tab_result = handle_tab_key_binding(sequence)
         return tab_result unless tab_result == false
 
@@ -323,10 +320,10 @@ module Kward
           if ctrl_modifier?(modifier)
             shift_modifier?(modifier) ? { tab_action: :previous } : { tab_action: :next }
           elsif shift_modifier?(modifier)
-            handle_reasoning_key_binding(key) || handle_tab_completion_key
+            handle_tab_completion_key
           else
             completion_result = handle_completion_provider_key("\t")
-            completion_result == false ? handle_reasoning_key_binding("\t") || handle_tab_completion_key : completion_result
+            completion_result == false ? handle_tab_completion_key : completion_result
           end
         when 13
           if modifier == 2
@@ -447,7 +444,7 @@ module Kward
           when 107
             kill_line_after_cursor
           when 108
-            redraw_screen_locked
+            request_transcript_redraw
           when 114
             start_history_search
           when 117
@@ -580,61 +577,99 @@ module Kward
 
       CTRL_TAB_SEQUENCES = TerminalKeys::CTRL_TAB
       CTRL_SHIFT_TAB_SEQUENCES = TerminalKeys::CTRL_SHIFT_TAB
-      SHIFT_TAB_SEQUENCES = TerminalKeys::SHIFT_TAB
+
+      def handle_completion_overlay_key(key)
+        return false unless @completion_overlay
+
+        return handle_completion_provider_key("\t") if completion_tab_key?(key)
+
+        dismiss_completion_overlay
+        false
+      end
+
+      def completion_tab_key?(key)
+        return true if key == "\t"
+
+        sequence = parse_csi_u_key(key)
+        return false unless sequence && sequence[:code] == 9
+
+        completion = !ctrl_modifier?(sequence[:modifier]) && !shift_modifier?(sequence[:modifier])
+        queue_pending_keys(sequence[:remaining]) if completion && sequence[:remaining] && !sequence[:remaining].empty?
+        completion
+      end
+
+      def dismiss_completion_overlay
+        @completion_overlay = nil
+        @completion_cycle = nil
+      end
 
       def handle_completion_provider_key(key)
         return false unless key == "\t" && @completion_provider
 
+        if (cycle = matching_completion_cycle)
+          cycle_completion(cycle)
+          return true
+        end
+
         result = @completion_provider.call(composer_input, composer_cursor)
+        return false if result == false
         return true unless result
 
         apply_completion_result(result)
         true
       end
 
+      def matching_completion_cycle
+        cycle = @completion_cycle
+        return nil unless cycle
+        return cycle if cycle[:input] == composer_input && cycle[:cursor] == composer_cursor
+
+        @completion_cycle = nil
+        @completion_overlay = nil
+        nil
+      end
+
+      def cycle_completion(cycle)
+        cycle[:index] = (cycle[:index] + 1) % cycle[:candidates].length
+        apply_completion_cycle_candidate(cycle)
+      end
+
       def apply_completion_result(result)
         range = result[:range] || result["range"] || result.range
         replacement = result[:replacement] || result["replacement"] || result.replacement
-        candidates = result[:candidates] || result["candidates"] || result.candidates
+        candidates = (result[:candidates] || result["candidates"] || result.candidates).to_a
         original = composer_input
         before = original[0...range.begin].to_s
         after = original[range.end..].to_s
+
+        if candidates.length > 1
+          @completion_cycle = {
+            candidates: candidates.map(&:to_s),
+            index: 0,
+            before: before,
+            after: after
+          }
+          apply_completion_cycle_candidate(@completion_cycle)
+          show_completion_overlay(candidates)
+          return
+        end
+
+        @completion_cycle = nil
         self.composer_input = "#{before}#{replacement}#{after}"
         self.composer_cursor = before.length + replacement.to_s.length
-        show_completion_candidates(candidates, replacement) if candidates.to_a.length > 1 && replacement.to_s == original[range]
       end
 
-      def show_completion_candidates(candidates, replacement)
-        lines = candidates.to_a.first(40)
-        text = ["completions:", *lines.map { |candidate| "  #{candidate}" }].join("\n")
-        write_completion_transcript_locked(text)
+      def show_completion_overlay(candidates)
+        @completion_overlay = { candidates: candidates.map(&:to_s), index: 0 }
       end
 
-      def write_completion_transcript_locked(text)
-        with_synchronized_output_locked do
-          clear_prompt_for_output_locked
-          write_transcript_text_locked("\n#{text}\n")
-          render_prompt_after_output_locked
-        end
-      end
-
-      def handle_reasoning_key_binding(key)
-        return false if @busy || @select_state || @question_state
-        return false if file_overlay_visible? || slash_overlay_visible?
-        return false if @slash_overlay_dismissed_input && @slash_overlay_dismissed_input == composer_input
-        mention_token = active_file_mention_token
-        open_token = active_file_open_token
-        return false if mention_token && @file_overlay_dismissed_token == mention_token
-        return false if open_token && @file_open_dismissed_token == open_token
-
-        case key
-        when "\t"
-          { reasoning_action: :next }
-        when *SHIFT_TAB_SEQUENCES
-          { reasoning_action: :previous }
-        else
-          false
-        end
+      def apply_completion_cycle_candidate(cycle)
+        replacement = cycle[:candidates][cycle[:index]]
+        self.composer_input = "#{cycle[:before]}#{replacement}#{cycle[:after]}"
+        self.composer_cursor = cycle[:before].length + replacement.length
+        @completion_overlay[:index] = cycle[:index] if @completion_overlay
+        cycle[:input] = composer_input
+        cycle[:cursor] = composer_cursor
       end
 
       def handle_tab_key_binding(key)
@@ -710,7 +745,7 @@ module Kward
         when TerminalKeys::CTRL_K
           kill_line_after_cursor
         when TerminalKeys::CTRL_L
-          redraw_screen_locked
+          request_transcript_redraw
         when TerminalKeys::CTRL_U
           kill_line_before_cursor
         when TerminalKeys::CTRL_W