kward 0.76.0 → 0.78.0

data/lib/kward/cli/tabs.rb

@@ -1,3 +1,4 @@
+require "json"
 require "thread"
 require_relative "../cancellation"
 
@@ -10,6 +11,7 @@ module Kward
       TabRuntime = Struct.new(
         :session,
         :agent,
+        :driver,
         :diff,
         :snapshot,
         :status,
@@ -58,6 +60,28 @@ module Kward
         def ask_user_question(questions, cancellation: nil)
           @cli.send(:ask_tab_user_question, @tab, questions, cancellation: cancellation)
         end
+
+        def ask_tool_approval(tool_name:, args:, reason: nil)
+          answers = ask_user_question([
+            {
+              header: "Approval required · #{tool_name.to_s.tr("_", " ").capitalize}",
+              question: (["The agent wants to use #{tool_name}.", "Arguments:\n#{JSON.pretty_generate(args.to_h)}", reason].compact).join("\n"),
+              options: [
+                { label: "Allow once", description: "Run this tool call." },
+                { label: "Allow this tool for this session", description: "Run this call and future calls to #{tool_name}." },
+                { label: "Deny", description: "Do not run this tool call." }
+              ]
+            }
+          ])
+          answer = answers&.first
+          return { denied_message: answer[:answer] } if answer&.fetch(:custom, false) && !answer[:answer].to_s.empty?
+
+          case answer&.fetch(:answer, nil)
+          when "Allow once" then true
+          when "Allow this tool for this session" then :allow_for_session
+          else false
+          end
+        end
       end
 
       private
@@ -72,8 +96,8 @@ module Kward
         return restored if restored
 
         if agent.nil? && (resumed_agent = resume_last_session(session_store))
-          release_implementation_writer
-          @tabs << build_tab(@active_session, build_tab_agent(resumed_agent.conversation, @active_session), label: default_tab_label(0))
+          restored_agent = build_tab_agent(resumed_agent.conversation, @active_session)
+          @tabs << build_tab(@active_session, restored_agent, driver: SessionTabDriver.new(session: @active_session, agent: restored_agent), label: default_tab_label(0))
           return activate_tab(0, render: false)
         end
 
@@ -87,19 +111,18 @@ module Kward
           @active_session.attach(conversation)
           tab_agent = build_tab_agent(conversation, @active_session)
         end
-        @tabs << build_tab(@active_session, tab_agent, label: default_tab_label(0))
+        @tabs << build_tab(@active_session, tab_agent, driver: SessionTabDriver.new(session: @active_session, agent: tab_agent), label: default_tab_label(0))
         activate_tab(0, render: false)
       end
 
       def restore_tabs(session_store)
         data = @tab_store&.load || {}
-        paths = Array(data["session_paths"]).map(&:to_s)
-        return nil if paths.empty?
+        descriptors = Array(data["tabs"])
+        return nil if descriptors.empty?
 
-        paths.each_with_index do |path, index|
-          session, conversation = restore_tab_session(session_store, path)
-          tab = build_tab(session, build_tab_agent(conversation, session), label: restored_tab_label(data, index))
-          @tabs << tab
+        descriptors.each_with_index do |_descriptor, index|
+          tab = build_tab_from_descriptor(data.fetch("tabs")[index], session_store, label: restored_tab_label(data, index))
+          @tabs << tab if tab
         rescue StandardError
           next
         end
@@ -110,6 +133,47 @@ module Kward
         activate_tab(@active_tab_index)
       end
 
+      def build_tab_from_descriptor(descriptor, session_store, label: nil)
+        descriptor = descriptor.transform_keys(&:to_s)
+        if descriptor["kind"] == "session"
+          session, conversation = restore_tab_session(session_store, descriptor.fetch("session_path"))
+          agent = build_tab_agent(conversation, session)
+          return build_tab(session, agent, driver: SessionTabDriver.new(session: session, agent: agent), label: label)
+        end
+
+        tab_type = plugin_registry.tab_type_for_id(descriptor["plugin_tab_type"])
+        driver = if tab_type
+          host = PluginTabHost.new(client: @client, workspace_root: session_store.cwd)
+          tab_type.handler.call(host, descriptor)
+        else
+          UnavailableTabDriver.new(descriptor: descriptor, message: "Plugin tab #{descriptor["plugin_tab_type"].inspect} is unavailable.")
+        end
+        raise "Plugin tab #{descriptor["plugin_tab_type"].inspect} did not return a tab driver." unless driver
+        build_tab(nil, nil, driver: driver, label: label || descriptor["label"] || tab_type&.title)
+      end
+
+      def open_plugin_tab(name, session_store)
+        tab_type = plugin_registry.tab_type_for(name)
+        return runtime_output("Plugin tab #{name.inspect} is not available.") unless tab_type
+
+        if tab_type.singleton == :global && (existing = @tabs.find { |tab| tab.driver.descriptor["plugin_tab_type"] == tab_type.id })
+          return switch_tab(@tabs.index(existing))
+        end
+
+        save_active_tab_state
+        stop_tab_live_view
+        descriptor = { "kind" => "plugin", "plugin_tab_type" => tab_type.id, "label" => tab_type.title }
+        host = PluginTabHost.new(client: @client, workspace_root: session_store.cwd)
+        driver = tab_type.handler.call(host, descriptor)
+        raise "Plugin tab #{name.inspect} did not return a tab driver." unless driver
+
+        @tabs << build_tab(nil, nil, driver: driver, label: tab_type.title)
+        @active_tab_index = @tabs.length - 1
+        activate_tab(@active_tab_index)
+      rescue StandardError => e
+        runtime_output("Could not open plugin tab #{name.inspect}: #{e.message}")
+      end
+
       def restore_tab_session(session_store, path)
         if File.file?(path)
           session, conversation = session_store.load(path, workspace: configured_workspace(root: session_store.cwd), provider: current_model_provider, model: current_model_id, reasoning_effort: current_reasoning_effort)
@@ -131,6 +195,7 @@ module Kward
         tool_registry = ToolRegistry.new(
           workspace: workspace,
           prompt: prompt,
+          tool_approval: tab_tool_approval_callback(prompt),
           hook_manager: hook_manager,
           hook_context: hook_context
         )
@@ -147,10 +212,20 @@ module Kward
         agent
       end
 
-      def build_tab(session, agent, label: nil)
+      def tab_tool_approval_callback(prompt)
+        return nil unless ConfigFiles.permission_policy(safely_read_config.to_h).enabled?
+
+        lambda do |tool_call:, name:, args:, cancellation:|
+          prompt.ask_tool_approval(tool_name: name, args: args, reason: args["hook_message"] || args[:hook_message])
+        end
+      end
+
+      def build_tab(session, agent, driver: nil, label: nil)
+        driver ||= SessionTabDriver.new(session: session, agent: agent)
         TabRuntime.new(
           session: session,
           agent: agent,
+          driver: driver,
           diff: session&.path ? SessionDiff.from_session_file(session.path) : SessionDiff.new,
           snapshot: nil,
           status: "idle",
@@ -162,7 +237,7 @@ module Kward
           steering: nil,
           error: nil,
           answer: nil,
-          stream_state: new_tab_stream_state(agent),
+          stream_state: new_tab_stream_state(driver),
           markdown_chunks: [],
           label: label,
           unread: false,
@@ -177,6 +252,17 @@ module Kward
         @tabs && @tabs[@active_tab_index]
       end
 
+      def plugin_tab?(tab = active_tab)
+        tab && tab.session.nil?
+      end
+
+      def plugin_tab_command_allowed?(command)
+        name, = parse_slash_command(command)
+        return true if %w[tab exit quit].include?(name)
+
+        active_tab.driver.respond_to?(:handles_command?) && active_tab.driver.handles_command?(command)
+      end
+
       def assign_tab_question_prompt(agent, tab)
         prompt = agent.instance_variable_get(:@tab_question_prompt) if agent
         prompt.tab = tab if prompt.respond_to?(:tab=)
@@ -243,7 +329,8 @@ module Kward
         session = track_session(session_store.create(provider: current_model_provider, model: current_model_id, reasoning_effort: current_reasoning_effort))
         conversation = new_conversation(workspace_root: session_store.cwd)
         session.attach(conversation)
-        @tabs << build_tab(session, build_tab_agent(conversation, session), label: default_tab_label(@tabs.length))
+        agent = build_tab_agent(conversation, session)
+        @tabs << build_tab(session, agent, driver: SessionTabDriver.new(session: session, agent: agent), label: default_tab_label(@tabs.length))
         @active_tab_index = @tabs.length - 1
         activate_tab(@active_tab_index)
       end
@@ -263,6 +350,7 @@ module Kward
 
         stop_tab_live_view
         tab.session&.delete_if_unused if tab&.session.respond_to?(:delete_if_unused)
+        tab.driver.close if tab.driver.respond_to?(:close)
         @tabs.delete_at(@active_tab_index)
         @active_tab_index = [@active_tab_index, @tabs.length - 1].min
         activate_tab(@active_tab_index)
@@ -285,6 +373,7 @@ module Kward
 
         tab.session = @active_session
         tab.agent = build_tab_agent(agent.conversation, tab.session)
+        tab.driver = SessionTabDriver.new(session: tab.session, agent: tab.agent)
         assign_tab_question_prompt(tab.agent, tab)
         tab.diff = @session_diff || (tab.session&.path ? SessionDiff.from_session_file(tab.session.path) : SessionDiff.new)
         tab.snapshot = nil
@@ -298,7 +387,7 @@ module Kward
         tab.queued_inputs.clear
         tab.steering = nil
         tab.shell = nil
-        tab.stream_state = new_tab_stream_state(tab.agent)
+        tab.stream_state = new_tab_stream_state(tab.driver)
         tab.markdown_chunks.clear
         update_prompt_tabs
         persist_tabs
@@ -323,11 +412,19 @@ module Kward
 
         @active_session = tab.session
         @session_diff = tab.diff || SessionDiff.new
-        @footer_conversation = tab.agent.conversation
-        @footer_tool_registry = tab.agent.tool_registry if tab.agent.respond_to?(:tool_registry)
-        update_assistant_prompt(tab.agent.conversation)
+        if tab.agent
+          @footer_conversation = tab.agent.conversation
+          @footer_tool_registry = tab.agent.tool_registry if tab.agent.respond_to?(:tool_registry)
+          update_assistant_prompt(tab.agent.conversation)
+        else
+          @footer_conversation = nil
+          @footer_tool_registry = nil
+          @assistant_prompt = "#{tab.driver.assistant_label || "Plugin"}>"
+          @prompt.update_assistant_label(assistant_prompt_name) if @prompt.respond_to?(:update_assistant_label)
+        end
         tab.unread = false
         restore_tab_composer_snapshot(tab.snapshot)
+        update_plugin_tab_slash_commands(tab)
         update_prompt_tabs
         render_tab(tab) if render
         start_tab_live_view(tab) if tab.running?
@@ -344,10 +441,10 @@ module Kward
         end
 
         restore_prompt_transcript do
-          if empty_tab_conversation?(tab.agent.conversation)
+          if tab.agent && empty_tab_conversation?(tab.agent.conversation)
             print_visual_banner
           else
-            render_conversation_transcript(tab.agent.conversation)
+            render_transcript_messages(tab.driver.messages)
           end
           report_tab_runtime_error(tab) if %w[failed cancelled].include?(tab.status.to_s)
         end
@@ -404,20 +501,19 @@ module Kward
       end
 
       def start_tab_turn(tab, input, display_input: nil)
-        stop_live_worker_view if respond_to?(:stop_live_worker_view, true)
         prepare_memory_context(tab.agent.conversation, input) if tab.agent.respond_to?(:conversation)
         print_user_transcript(input, display_input: display_input) if prompt_interface?
         tab.status = "queued"
         tab.unread = false
         tab.cancellation = Cancellation.new
-        tab.steering = steering_supported? ? Steering.new : nil
+        tab.steering = tab.driver.supports_steering? && steering_supported? ? Steering.new : nil
         tab.error = nil
         tab.answer = nil
         tab.error_reported = false
         tab.event_history.clear
         tab.seen_events = 0
         tab.markdown_chunks.clear
-        tab.stream_state = new_tab_stream_state(tab.agent)
+        tab.stream_state = new_tab_stream_state(tab.driver)
         update_prompt_tabs
         tab.thread = Thread.new { run_tab_turn(tab, input, display_input: display_input) }
         tab.thread.report_on_exception = false
@@ -425,12 +521,9 @@ module Kward
       end
 
       def run_tab_turn(tab, input, display_input: nil)
-        options = agent_display_options(display_input)
-        options[:cancellation] = tab.cancellation
-        options[:steering] = tab.steering if tab.steering
         tab.status = "running"
         update_prompt_tabs
-        tab.answer = tab.agent.ask(input, **options) do |event|
+        tab.answer = tab.driver.submit(input, display_input: display_input, cancellation: tab.cancellation, steering: tab.steering) do |event|
           tab.record_event(event)
         end
         tab.status = "ready"
@@ -489,7 +582,7 @@ module Kward
             tab.queued_inputs << "/exit"
             @prompt.set_queued_count(tab.queued_inputs.length) if @prompt.respond_to?(:set_queued_count)
           when String
-            handle_tab_busy_input(tab, poll_result)
+            return { tab_action: :busy_command } if handle_tab_busy_input(tab, poll_result) == :active_tab_changed
           end
           return next_tab_queued_input(tab) if tab.idle? && !tab.queued_inputs.empty?
           return :tab_idle if tab.idle?
@@ -512,6 +605,15 @@ module Kward
           tab.queued_inputs << input
           @prompt.set_queued_count(tab.queued_inputs.length) if @prompt.respond_to?(:set_queued_count)
           return
+        elsif busy_tab_command?(input)
+          handle_tab_command(input.to_s.strip.sub(%r{\A/tab(?:\s+|\z)}, ""), @session_store)
+          unless active_tab.equal?(tab)
+            @prompt.finish_busy_input if @prompt.respond_to?(:finish_busy_input)
+            return :active_tab_changed
+          end
+
+          restore_busy_input_prompt
+          return
         elsif slash_command_input?(input)
           # Slash commands are local control actions. Running or queuing them
           # from the busy composer is surprising because the state they act on
@@ -532,6 +634,10 @@ module Kward
         @prompt.set_queued_count(tab.queued_inputs.length) if @prompt.respond_to?(:set_queued_count)
       end
 
+      def busy_tab_command?(input)
+        input.to_s.strip.match?(%r{\A/tab(?:\s|\z)})
+      end
+
       def refresh_active_tab
         tab = active_tab
         return unless tab
@@ -562,10 +668,10 @@ module Kward
         renderer = tab_live_renderer(tab)
         until @tab_live_view_stop
           events = tab.event_history[tab.seen_events..] || []
-          events.each { |event| renderer.call(event, tab.agent) }
+          events.each { |event| renderer.call(event, tab.driver) }
           tab.seen_events += events.length
           if tab.idle?
-            renderer.call(:flush, tab.agent)
+            renderer.call(:flush, tab.driver)
             break
           end
           sleep 0.05
@@ -575,7 +681,7 @@ module Kward
       end
 
       def tab_live_renderer(tab)
-        lambda do |event, agent|
+        lambda do |event, driver|
           if event == :flush
             flush_interactive_markdown_deltas(tab.markdown_chunks, tab.stream_state, force: true)
             render_tab_answer(tab)
@@ -583,7 +689,11 @@ module Kward
             next
           end
 
-          notify_plugin_transcript_event(event, agent.respond_to?(:conversation) ? agent.conversation : nil)
+          if driver.respond_to?(:conversation)
+            notify_plugin_transcript_event(event, driver.conversation)
+          elsif plugin_tab_type_for(driver)&.transcript_events
+            notify_plugin_tab_transcript_event(event, driver)
+          end
           handle_interactive_event(event, tab.markdown_chunks, tab.stream_state)
           flush_interactive_markdown_deltas(tab.markdown_chunks, tab.stream_state)
         rescue StandardError => e
@@ -591,6 +701,10 @@ module Kward
         end
       end
 
+      def plugin_tab_type_for(driver)
+        plugin_registry.tab_type_for_id(driver.descriptor["plugin_tab_type"])
+      end
+
       def render_tab_answer(tab)
         return unless tab.status == "ready"
         return if tab.stream_state[:streamed]
@@ -599,13 +713,13 @@ module Kward
         @prompt.say("\n#{colored(assistant_output_prompt, :green, :bold)} #{render_markdown_transcript(tab.answer)}\n")
       end
 
-      def new_tab_stream_state(agent)
+      def new_tab_stream_state(driver)
         {
           streamed: false,
           last_flush: monotonic_now,
           stream_block_open: false,
           markdown_streams: {},
-          defer_assistant_streaming: defer_assistant_streaming?(agent)
+          defer_assistant_streaming: driver.respond_to?(:conversation) && defer_assistant_streaming?(driver.agent)
         }
       end
 
@@ -638,7 +752,7 @@ module Kward
         action, value = argument.to_s.strip.split(/\s+/, 2)
         case action
         when nil, ""
-          runtime_output("Usage: /tab 1-n | /tab move 1-n|left|right | /tab close | /tab new | /tab name <label>")
+          runtime_output("Usage: /tab 1-n | /tab move 1-n|left|right | /tab close | /tab new | /tab open <plugin-tab> | /tab name <label>")
           nil
         when /^\d+$/
           switch_tab_number(action)
@@ -652,11 +766,16 @@ module Kward
         when "new"
           open_new_tab(session_store)
           active_tab&.agent
+        when "open"
+          return runtime_output("Usage: /tab open <plugin-tab>") if value.to_s.strip.empty?
+
+          open_plugin_tab(value.strip, session_store)
+          active_tab&.agent
         when "name", "rename"
           rename_active_tab(value)
           active_tab&.agent
         else
-          runtime_output("Usage: /tab 1-n | /tab move 1-n|left|right | /tab close | /tab new | /tab name <label>")
+          runtime_output("Usage: /tab 1-n | /tab move 1-n|left|right | /tab close | /tab new | /tab open <plugin-tab> | /tab name <label>")
           nil
         end
       end
@@ -731,8 +850,7 @@ module Kward
         return unless @tab_store
 
         @tab_store.save(
-          session_paths: @tabs.map { |tab| tab.session&.path }.compact,
-          labels: @tabs.map { |tab| tab.label.to_s },
+          tabs: @tabs.map { |tab| tab.driver.descriptor.merge("label" => tab.label.to_s) },
           active_index: @active_tab_index
         )
       end

data/lib/kward/cli.rb

@@ -35,12 +35,12 @@ require_relative "session_diff"
 require_relative "session_store"
 require_relative "session_naming"
 require_relative "tab_store"
+require_relative "tab_driver"
 require_relative "session_trash"
 require_relative "session_tree_renderer"
 require_relative "starter_pack_installer"
 require_relative "steering"
 require_relative "update_check"
-require_relative "workers"
 require_relative "tools/tool_call"
 require_relative "tools/registry"
 require_relative "telemetry/stats"
@@ -114,8 +114,6 @@ module Kward
       @prompt_delimited = false
       @requested_mode = "auto"
       @skip_config = false
-      @experimental_workers = false
-      @foreground_turn_active = false
       @pending_reasoning_config = nil
       @pending_reasoning_config_mutex = Mutex.new
       @color_enabled = ANSI.enabled?($stdout)
@@ -253,7 +251,7 @@ module Kward
         raise ArgumentError, command_usage("rpc") unless @argv.length == 1
 
         ensure_client!
-        Kward::RPC::Server.new(input: @stdin, output: $stdout, client: @client, experimental_workers: @experimental_workers).run
+        Kward::RPC::Server.new(input: @stdin, output: $stdout, client: @client).run
         return
       end
 
@@ -441,13 +439,15 @@ module Kward
         if input.is_a?(Hash) && input[:tab_action]
           tab_result = handle_tab_action(input, session_store)
           break if tab_result == PromptInterface::EXIT_INPUT
-          agent = active_tab.agent if active_tab
+          agent = active_tab.agent if active_tab&.agent
           next
         end
         if input.is_a?(Hash) && input[:reasoning_action]
+          next if active_tab && plugin_tab?
+
           conversation = active_tab ? active_tab.agent.conversation : agent.conversation
           cycle_reasoning(conversation, direction: input[:reasoning_action], persist: :debounced)
-          agent = active_tab.agent if active_tab
+          agent = active_tab.agent if active_tab&.agent
           next
         end
         next if input == :tab_idle
@@ -467,31 +467,37 @@ module Kward
             display_input = input if display_input
           end
           break if ["/exit", "/quit"].include?(command)
+          if active_tab && plugin_tab? && command.start_with?("/")
+            unless plugin_tab_command_allowed?(command)
+              runtime_output("#{command.split.first} is unavailable in this plugin tab.")
+              next
+            end
+            if active_tab.driver.respond_to?(:handle_command) && active_tab.driver.handles_command?(command)
+              output = active_tab.driver.handle_command(command)
+              runtime_output(output) unless output.to_s.empty?
+              next
+            end
+          end
           handled, replacement_agent = handle_local_slash_command(command, agent, session_store)
           if replacement_agent?(replacement_agent)
             agent = active_tab ? replace_active_tab_agent(replacement_agent) : replacement_agent
+          elsif active_tab&.agent
+            agent = active_tab.agent
           end
         end
         next if handled
-        request_handled, request_replacement = handle_request_worker_input(command_input, agent, session_store)
-        if request_handled
-          if replacement_agent?(request_replacement)
-            agent = active_tab ? replace_active_tab_agent(request_replacement) : request_replacement
-          end
-          next
-        end
         next if shell_command_input?(command_input) && handle_interactive_shell_command(command_input, agent)
 
-        flush_pending_reasoning_config(conversation: agent.conversation)
+        flush_pending_reasoning_config(conversation: active_tab.agent.conversation) if active_tab&.agent
+        flush_pending_reasoning_config(conversation: agent.conversation) unless active_tab
         expanded_input = expand_prompt_template(input)
         display_input = display_input || input if expanded_input
         input = expanded_input || input
-        agent = refresh_implementation_writer(agent)
-        @footer_conversation = agent.conversation
+        @footer_conversation = active_tab.agent.conversation if active_tab&.agent
+        @footer_conversation = agent.conversation unless active_tab
         begin
           @rewind_return_leaf_id = nil
-          auto_name_active_session(display_input || input)
-          @foreground_turn_active = true if @active_worker_role == "implementation"
+          auto_name_active_session(display_input || input) unless active_tab && plugin_tab?
           if active_tab
             submit_tab_input(active_tab, input, display_input: display_input)
             pending_inputs = []
@@ -503,22 +509,20 @@ module Kward
           pending_inputs.reverse_each { |pending_input| @pending_inputs.unshift(pending_input) }
         rescue StandardError => e
           runtime_output("Error: #{e.message}")
-        ensure
-          @foreground_turn_active = false if @active_worker_role == "implementation"
-          release_implementation_writer if @active_worker_role == "implementation"
         end
       end
 
-      flush_pending_reasoning_config(conversation: agent.conversation)
-      agent.conversation
+      flush_pending_reasoning_config(conversation: active_tab.agent.conversation) if active_tab&.agent
+      flush_pending_reasoning_config(conversation: agent.conversation) unless active_tab
+      active_tab&.agent&.conversation || agent.conversation
     rescue Interrupt
-      flush_pending_reasoning_config(conversation: agent&.conversation)
+      flush_pending_reasoning_config(conversation: active_tab.agent.conversation) if active_tab&.agent
+      flush_pending_reasoning_config(conversation: agent&.conversation) unless active_tab
       runtime_output("Goodbye.")
-      agent&.conversation
+      active_tab&.agent&.conversation || agent&.conversation
     ensure
       begin
         stop_tabs if respond_to?(:stop_tabs, true)
-        stop_live_worker_view if respond_to?(:stop_live_worker_view, true)
         @prompt.close if prompt_interface?
       ensure
         cleanup_unused_sessions

data/lib/kward/compactor.rb

@@ -37,7 +37,7 @@ module Kward
 
     Cut = Struct.new(:first_kept_index, :messages_to_summarize, :turn_prefix_messages, :split_turn, :preserved_messages, :preserved_start_index, keyword_init: true)
 
-    # Interactive settings menu actions mixed into the CLI frontend.
+    # Configuration for manual and automatic conversation compaction.
     class Settings
       DEFAULT_ENABLED = true
       DEFAULT_RESERVE_TOKENS = 16_384
@@ -731,7 +731,7 @@ module Kward
     SummarizationFailed = Compaction::SummarizationFailed
 
     AUTO_COMPACTION_GUARD_RATIO = 0.10
-    AUTO_COMPACTION_EXTRA_GUARD_CAP = 12_000
+    AUTO_COMPACTION_EXTRA_GUARD_FLOOR = 12_000
 
     # Creates an object for conversation compaction.
     def initialize(conversation:, client:, tool_result_summarizer: nil, settings: nil, summarizer: nil)
@@ -805,7 +805,7 @@ module Kward
     def self.auto_compaction_reserve_tokens(context_window:, configured_reserve_tokens:)
       context_window_i = context_window.to_i
       dynamic_guard = (context_window_i * AUTO_COMPACTION_GUARD_RATIO).to_i
-      [configured_reserve_tokens.to_i, dynamic_guard, AUTO_COMPACTION_EXTRA_GUARD_CAP].max
+      [configured_reserve_tokens.to_i, dynamic_guard, AUTO_COMPACTION_EXTRA_GUARD_FLOOR].max
     end
 
     def compaction_messages(custom_instructions = nil)

data/lib/kward/config_files.rb

@@ -5,6 +5,7 @@ require "yaml"
 require_relative "frontmatter"
 require_relative "private_file"
 require_relative "path_guard"
+require_relative "permissions/policy"
 require_relative "ekwsh"
 require_relative "editor_mode"
 require_relative "diff_view_mode"
@@ -24,7 +25,9 @@ module Kward
   # Keep path decisions here. Higher-level code should ask `ConfigFiles` for
   # config, prompt, skill, plugin, cache, memory, and session locations instead of
   # reconstructing `~/.kward` paths independently.
+  # @api public
   module ConfigFiles
+    # Raised when a user configuration file cannot be parsed.
     class ConfigError < StandardError
       attr_reader :path, :format, :detail
 
@@ -39,6 +42,7 @@ module Kward
     MAX_SKILL_FILE_BYTES = 100_000
     MAX_PROMPT_FILE_BYTES = 32 * 1024
     DEFAULT_OVERLAY_SETTINGS = { "alignment" => "center", "width" => "maximum" }.freeze
+    PROJECT_BROWSER_ICON_THEMES = %w[off nerd-font].freeze
     DEFAULT_PERSONAS = {
       "characters" => [
         {
@@ -87,10 +91,12 @@ module Kward
       File.expand_path(ENV["KWARD_CONFIG_PATH"] || File.join(config_dir, "config.json"))
     end
 
+    # @return [String] directory containing reusable local caches
     def cache_dir
       File.join(config_dir, "cache")
     end
 
+    # @return [String] embedded-shell YAML config path
     def ekwsh_config_path
       File.join(config_dir, "ekwsh.yml")
     end
@@ -103,6 +109,9 @@ module Kward
       File.join(config_dir, "trusted_workspace_hooks.json")
     end
 
+    # Returns a fresh default config suitable for first-run persistence.
+    #
+    # @return [Hash] deep-mutable config defaults
     def default_config
       {
         "personas" => JSON.parse(JSON.generate(DEFAULT_PERSONAS)),
@@ -124,6 +133,9 @@ module Kward
           "diff_view" => "auto"
         },
         "overlay" => DEFAULT_OVERLAY_SETTINGS.dup,
+        "project_browser" => {
+          "icons" => "off"
+        },
         "web_search" => {
           "enabled" => true,
           "provider" => "auto",
@@ -142,6 +154,10 @@ module Kward
         "mcpServers" => {},
         "tools" => {
           "workspace_guardrails" => true
+        },
+        "permissions" => {
+          "enabled" => false,
+          "mode" => "ask"
         }
       }
     end
@@ -409,6 +425,13 @@ module Kward
       settings
     end
 
+    # Returns the project browser icon theme, or off when unset or invalid.
+    def project_browser_icon_theme(config = read_config)
+      browser = config["project_browser"].is_a?(Hash) ? config["project_browser"] : {}
+      theme = browser["icons"].to_s
+      PROJECT_BROWSER_ICON_THEMES.include?(theme) ? theme : "off"
+    end
+
     # Returns whether the composer should show busy-state keyboard help.
     def composer_busy_help?(config = read_config)
       composer = config["composer"].is_a?(Hash) ? config["composer"] : {}
@@ -470,6 +493,11 @@ module Kward
       tools["workspace_guardrails"] != false
     end
 
+    # Builds the opt-in model-tool permission policy from persisted configuration.
+    def permission_policy(config = read_config)
+      Permissions::Policy.from_config(config)
+    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"] : {}

data/lib/kward/ekwsh.rb

@@ -551,9 +551,5 @@ module Kward
       ANSI.sanitize_transcript(text)
     end
 
-    def clean_output(value)
-      text = clean_chunk(value)
-      text.end_with?("\n") || text.empty? ? text : "#{text}\n"
-    end
   end
 end