kward 0.77.0 → 0.78.0

data/lib/kward/cli/plugins.rb

@@ -102,6 +102,17 @@ module Kward
         end
       end
 
+      def update_plugin_tab_slash_commands(tab)
+        return unless @prompt.respond_to?(:update_slash_commands)
+
+        entries = if tab&.driver&.respond_to?(:slash_command_entries)
+          tab.driver.slash_command_entries
+        else
+          []
+        end
+        @prompt.update_slash_commands(slash_command_entries + Array(entries))
+      end
+
       def slash_command_entries
         prompt_entries = prompt_templates.map do |template|
           {
@@ -192,6 +203,17 @@ module Kward
         plugin_registry.notify_transcript_event(event, plugin_context(conversation, ""))
       end
 
+      def notify_plugin_tab_transcript_event(event, driver)
+        return if plugin_registry.transcript_event_handlers.empty?
+
+        context = PluginRegistry::Context.new(
+          conversation: driver,
+          workspace_root: current_workspace_root,
+          say_callback: lambda { |message| runtime_output(message) }
+        )
+        plugin_registry.notify_transcript_event(event, context)
+      end
+
     end
   end
 end

data/lib/kward/cli/rendering.rb

@@ -7,9 +7,15 @@ module Kward
       private
 
       def render_conversation_transcript(conversation)
+        render_transcript_messages(conversation.messages)
+      end
+
+      # Renders a transcript supplied by either a Kward conversation or a
+      # plugin-owned tab driver.
+      def render_transcript_messages(messages)
         tool_calls_by_id = {}
         @prompt.say("\n#{colored("Transcript", :gray, :bold)}\n")
-        conversation.messages.each do |message|
+        Array(messages).each do |message|
           role = message_role(message)
           next if role == "system"
 

data/lib/kward/cli/runtime_helpers.rb

@@ -50,6 +50,7 @@ module Kward
         tool_registry = ToolRegistry.new(
           workspace: workspace,
           prompt: @prompt,
+          tool_approval: interactive_tool_approval_callback,
           hook_manager: hook_manager,
           hook_context: hook_context
         )
@@ -64,6 +65,19 @@ module Kward
         )
       end
 
+      def interactive_tool_approval_callback
+        return nil unless @prompt.respond_to?(:ask_tool_approval)
+        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 handle_interactive_shell_command(input, agent)
         command = input.to_s.sub(/\A!\s*/, "")
         if command.strip.empty?

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
@@ -409,14 +506,14 @@ module Kward
         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
@@ -424,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"
@@ -574,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
@@ -587,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)
@@ -595,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
@@ -603,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]
@@ -611,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
 
@@ -650,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)
@@ -664,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
@@ -743,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,6 +35,7 @@ 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"
@@ -438,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
@@ -464,22 +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
         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
-        @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)
+          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 = []
@@ -494,12 +512,14 @@ module Kward
         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)

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"
@@ -153,6 +154,10 @@ module Kward
         "mcpServers" => {},
         "tools" => {
           "workspace_guardrails" => true
+        },
+        "permissions" => {
+          "enabled" => false,
+          "mode" => "ask"
         }
       }
     end
@@ -488,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/hooks/http_handler.rb

@@ -3,6 +3,7 @@ require "net/http"
 require "uri"
 require_relative "catalog"
 require_relative "decision"
+require_relative "../http"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -33,7 +34,7 @@ module Kward
       private
 
       def post(body)
-        request = Net::HTTP::Post.new(@uri)
+        request = Http.apply_user_agent(Net::HTTP::Post.new(@uri))
         request["Content-Type"] = "application/json"
         request["Accept"] = "application/json"
         @headers.each { |key, value| request[key] = value }

data/lib/kward/http.rb

@@ -0,0 +1,18 @@
+require_relative "version"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Shared HTTP request headers for Kward-owned network traffic.
+  module Http
+    module_function
+
+    def user_agent
+      "Kward/#{VERSION}"
+    end
+
+    def apply_user_agent(request)
+      request["User-Agent"] = user_agent
+      request
+    end
+  end
+end