kward 0.84.0 → 0.85.0

data/lib/kward/tools/registry.rb

@@ -11,13 +11,16 @@ require_relative "fetch_raw"
 require_relative "git_commit"
 require_relative "list_directory"
 require_relative "mcp_tool"
+require_relative "plugin_tool"
 require_relative "read_file"
 require_relative "read_skill"
 require_relative "run_shell_command"
 require_relative "prepare_shell_command"
 require_relative "summarize_file_structure"
+require_relative "typesafe_evaluate"
 require_relative "retrieve_tool_output"
 require_relative "web_search"
+require_relative "workspace_targets"
 require_relative "write_file"
 require_relative "open_editor"
 require_relative "replace_editor_buffer"
@@ -29,7 +32,7 @@ require_relative "../mcp/server_config"
 require_relative "../permissions/policy"
 require_relative "../telemetry/logger"
 require_relative "../tool_output_compactor"
-require_relative "../workspace"
+require_relative "../workspace/workspace"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -66,6 +69,30 @@ module Kward
       retrieve_tool_output
     ].freeze
 
+    TARGETED_WORKSPACE_TOOLS = %w[
+      list_directory
+      read_file
+      write_file
+      edit_file
+      run_shell_command
+      summarize_file_structure
+      context_for_task
+      git_commit
+    ].freeze
+
+    BUILTIN_TOOL_NAMES = (CORE_TOOL_NAMES + %w[
+      git_commit
+      web_search
+      fetch_content
+      fetch_raw
+      read_skill
+      ask_user_question
+      replace_editor_buffer
+      open_editor
+      prepare_shell_command
+      typesafe_evaluate
+    ]).freeze
+
     # Tool schemas advertised to the model for the current frontend and config.
     #
     # @return [Array<Hash>] tool schemas currently advertised to the model
@@ -74,6 +101,7 @@ module Kward
     # Builds tool objects and the schema list for the current frontend/config.
     #
     # @param workspace [Workspace] filesystem/shell boundary used by local tools
+    # @param workspace_targets [Tools::WorkspaceTargets, nil] additional host-scoped worktree roles
     # @param prompt [Object, nil] interactive prompt bridge; tools such as
     #   `ask_user_question` and `open_editor` are advertised only when supported
     # @param web_search [WebSearch] live web search implementation
@@ -82,12 +110,15 @@ 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, editor_prompt_session: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, approval_for_allowed_tools: false, permission_policy: nil, hook_manager: nil, hook_context: nil, git_committer: nil)
+    # @param plugin_tools [Array<PluginRegistry::Tool>] trusted plugin tool registrations
+    def initialize(workspace: Workspace.new, workspace_targets: nil, 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, editor_prompt_session: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, plugin_tools: [], typesafe_client: TypeSafeClient.new, tool_approval: nil, approval_for_allowed_tools: false, permission_policy: nil, hook_manager: nil, hook_context: nil, git_committer: nil)
       @workspace = workspace
+      @workspace_targets = workspace_targets || Tools::WorkspaceTargets.new(active: workspace)
       @prompt = prompt
       @web_search = web_search
       @web_fetch = web_fetch
       @code_search = code_search
+      @typesafe_client = typesafe_client
       @skills = skills
       @web_search_enabled = web_search_enabled
       @ask_user_question_enabled = ask_user_question_enabled
@@ -97,6 +128,7 @@ module Kward
       @tool_output_compactor = tool_output_compactor
       @telemetry_logger = telemetry_logger
       @context_budget_meter = context_budget_meter
+      @plugin_tools = Array(plugin_tools)
       @tool_approval = tool_approval
       @approval_for_allowed_tools = approval_for_allowed_tools == true
       @permission_policy = permission_policy || Permissions::Policy.from_config(ConfigFiles.read_config)
@@ -114,6 +146,16 @@ module Kward
       @schemas = build_schema_tools.map { |tool| schema_with_metadata(tool) }.freeze
     end
 
+    # Replaces plugin registrations while preserving this registry's frontend,
+    # workspace, permission, hook, and execution-profile restrictions.
+    def replace_plugin_tools!(plugin_tools)
+      @plugin_tools = Array(plugin_tools)
+      @plugin_tool_values = nil
+      @tools = build_tools.freeze
+      @schemas = build_schema_tools.map { |tool| schema_with_metadata(tool) }.freeze
+      self
+    end
+
     # Builds a registry scoped to one editor prompt turn.
     #
     # Editor prompts may inspect the workspace, but their only write operation
@@ -163,7 +205,10 @@ module Kward
       original_content = if tool
                            before_tool = run_hook("tool_call_before", conversation, payload: tool_payload(name, args, tool_call))
                            args = hook_arguments(before_tool, args)
-                           if before_tool.denied?
+                           target_error = workspace_target_error(name, args)
+                           if target_error
+                             target_error
+                           elsif before_tool.denied?
                              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}")
@@ -254,6 +299,8 @@ module Kward
       case tool
       when Tools::MCPTool
         "mcp"
+      when Tools::PluginTool
+        "plugin"
       when Tools::WebSearch, Tools::FetchContent, Tools::FetchRaw
         "web"
       when Tools::ReadSkill
@@ -491,6 +538,13 @@ module Kward
       (metadata[:source] || metadata["source"]).to_s == "mcp"
     end
 
+    def workspace_target_error(name, args)
+      return nil unless TARGETED_WORKSPACE_TOOLS.include?(name.to_s)
+      return nil if @workspace_targets.valid?(args)
+
+      "Error: Unknown workspace target: #{@workspace_targets.target_name(args)}"
+    end
+
     def permission_approval_result(tool_call, name, args, cancellation)
       return false unless @tool_approval
 
@@ -514,6 +568,11 @@ module Kward
       tools = all_tools
       tools = tools.select { |tool| @allowed_tool_names.include?(tool.name) } if @allowed_tool_names
       tools.each_with_object({}) do |tool, result|
+        if tool.is_a?(Tools::PluginTool) && (BUILTIN_TOOL_NAMES.include?(tool.name) || result.key?(tool.name))
+          source = tool.plugin_path.to_s.empty? ? "" : " (#{tool.plugin_path})"
+          ConfigFiles.emit_warning("Warning: skipping Kward plugin tool #{tool.name}#{source}: duplicate tool name")
+          next
+        end
         raise ArgumentError, "Duplicate tool name: #{tool.name}" if result.key?(tool.name)
 
         result[tool.name] = tool
@@ -528,6 +587,8 @@ module Kward
       tools << @tools["git_commit"] if @tools["git_commit"]
       tools.concat(@tools.values_at("web_search", "fetch_content", "fetch_raw")) if web_search_available?
       tools.concat(@tools.values.select { |tool| tool.is_a?(Tools::MCPTool) })
+      tools.concat(@tools.values.select { |tool| tool.is_a?(Tools::PluginTool) })
+      tools << @tools["typesafe_evaluate"] if @tools["typesafe_evaluate"]
       tools << @tools["read_skill"] if skills_available?
       tools << @tools["ask_user_question"] if ask_user_question_available?
       tools.compact
@@ -535,26 +596,27 @@ module Kward
 
     def all_tools
       tools = core_tools
-      tools << Tools::GitCommit.new(committer: @git_committer) if @git_committer
-      tools + [
+      tools << Tools::GitCommit.new(committer: @git_committer, workspace_targets: @workspace_targets) if @git_committer
+      (tools + [
+        (Tools::TypeSafeEvaluate.new(client: @typesafe_client) if @typesafe_client&.available?),
         Tools::WebSearch.new(web_search: @web_search),
         Tools::FetchContent.new(web_fetch: @web_fetch),
         Tools::FetchRaw.new(web_fetch: @web_fetch),
         Tools::ReadSkill.new(skills: discovered_skills),
         Tools::AskUserQuestion.new(prompt: @prompt)
-      ] + mcp_tool_values
+      ]).compact + mcp_tool_values + plugin_tool_values
     end
 
     def core_tools
       tools = [
-        Tools::ListDirectory.new(workspace: @workspace),
-        Tools::ReadFile.new(workspace: @workspace),
-        Tools::WriteFile.new(workspace: @workspace),
-        Tools::EditFile.new(workspace: @workspace),
+        Tools::ListDirectory.new(workspace: @workspace, workspace_targets: @workspace_targets),
+        Tools::ReadFile.new(workspace: @workspace, workspace_targets: @workspace_targets),
+        Tools::WriteFile.new(workspace: @workspace, workspace_targets: @workspace_targets),
+        Tools::EditFile.new(workspace: @workspace, workspace_targets: @workspace_targets),
         shell_command_tool,
         Tools::CodeSearch.new(code_search: @code_search),
-        Tools::SummarizeFileStructure.new(workspace: @workspace),
-        Tools::ContextForTask.new(workspace: @workspace),
+        Tools::SummarizeFileStructure.new(workspace: @workspace, workspace_targets: @workspace_targets),
+        Tools::ContextForTask.new(workspace: @workspace, workspace_targets: @workspace_targets),
         Tools::ContextBudgetStats.new(context_budget_meter: @context_budget_meter),
         Tools::RetrieveToolOutput.new
       ]
@@ -568,7 +630,7 @@ module Kward
       if @shell_prompt_session
         Tools::RunShellCommand.new(shell_prompt_session: @shell_prompt_session)
       else
-        Tools::RunShellCommand.new(workspace: @workspace)
+        Tools::RunShellCommand.new(workspace: @workspace, workspace_targets: @workspace_targets)
       end
     end
 
@@ -611,6 +673,27 @@ module Kward
       @mcp_tool_values ||= build_mcp_tools
     end
 
+    def plugin_tool_values
+      @plugin_tool_values ||= @plugin_tools.map do |registration|
+        Tools::PluginTool.new(
+          registration: registration,
+          context_factory: method(:plugin_tool_context)
+        )
+      end
+    end
+
+    def plugin_tool_context(conversation, cancellation)
+      if @hook_context.respond_to?(:for_tool)
+        @hook_context.for_tool(conversation: conversation, cancellation: cancellation)
+      else
+        PluginRegistry::Context.new(
+          conversation: conversation,
+          workspace_root: @workspace.respond_to?(:root) ? @workspace.root.to_s : Dir.pwd,
+          cancellation: cancellation
+        )
+      end
+    end
+
     def build_mcp_tools
       Array(@mcp_clients).flat_map do |client|
         client.list_tools.map do |tool|

data/lib/kward/tools/run_shell_command.rb

@@ -1,5 +1,5 @@
 require_relative "base"
-require_relative "../workspace"
+require_relative "../workspace/workspace"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -8,11 +8,11 @@ module Kward
     # Tool wrapper for bounded shell commands in the workspace or active shell.
     class RunShellCommand < Base
       # Builds the tool schema and stores the execution dependency.
-      def initialize(workspace: nil, shell_prompt_session: nil)
+      def initialize(workspace: nil, workspace_targets: nil, shell_prompt_session: nil)
         raise ArgumentError, "RunShellCommand requires a workspace or shell session" unless workspace || shell_prompt_session
         raise ArgumentError, "RunShellCommand accepts only one execution target" if workspace && shell_prompt_session
 
-        @workspace = workspace
+        configure_workspace_targets(workspace, workspace_targets) if workspace
         @shell_prompt_session = shell_prompt_session
         description = shell_prompt_session ?
           "Run a bounded noninteractive command in the active embedded shell session." :
@@ -20,13 +20,15 @@ module Kward
         timeout_description = shell_prompt_session ?
           "Timeout seconds; defaults to the embedded shell setting." :
           "Timeout seconds; default 30."
+        properties = {
+          command: { type: "string", description: "Command to run." },
+          timeout_seconds: { type: "integer", description: timeout_description }
+        }
+        properties = targeted_properties(properties) if workspace
         super(
           "run_shell_command",
           description,
-          properties: {
-            command: { type: "string", description: "Command to run." },
-            timeout_seconds: { type: "integer", description: timeout_description }
-          },
+          properties: properties,
           required: ["command"]
         )
       end
@@ -43,7 +45,7 @@ module Kward
         if @shell_prompt_session
           @shell_prompt_session.run(command, timeout_seconds: timeout_seconds, cancellation: cancellation)
         else
-          @workspace.run_shell_command(command, timeout_seconds: timeout_seconds, cancellation: cancellation)
+          workspace_for(args).run_shell_command(command, timeout_seconds: timeout_seconds, cancellation: cancellation)
         end
       end
     end

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

@@ -5,7 +5,7 @@ require "net/http"
 require "open3"
 require "pathname"
 require "uri"
-require_relative "../../path_guard"
+require_relative "../../workspace/path_guard"
 require_relative "../../config_files"
 require_relative "web"
 

data/lib/kward/tools/summarize_file_structure.rb

@@ -7,14 +7,14 @@ module Kward
     # Returns a compact symbol outline for a workspace source file.
     class SummarizeFileStructure < Base
       # Builds the tool schema and stores the execution dependency.
-      def initialize(workspace:)
-        @workspace = workspace
+      def initialize(workspace:, workspace_targets: nil)
+        configure_workspace_targets(workspace, workspace_targets)
         super(
           "summarize_file_structure",
           "Return a compact outline of classes, modules, methods, and functions in a workspace source file.",
-          properties: {
+          properties: targeted_properties(
             path: { type: "string", description: "Workspace-relative source file path." }
-          },
+          ),
           required: ["path"]
         )
       end
@@ -22,7 +22,7 @@ module Kward
       # Executes the structure summary tool.
       def call(args, _conversation, cancellation: nil)
         cancellation&.raise_if_cancelled!
-        @workspace.summarize_file_structure(argument(args, :path, ""))
+        workspace_for(args).summarize_file_structure(argument(args, :path, ""))
       end
     end
   end

data/lib/kward/tools/tool_call.rb

@@ -27,7 +27,8 @@ module Kward
       "git_commit" => "git_commit",
       "read_skill" => "read_skill",
       "ask_user_question" => "ask_user_question",
-      "open_editor" => "open_editor"
+      "open_editor" => "open_editor",
+      "typesafe_evaluate" => "typesafe_evaluate"
     }.freeze
 
     module_function

data/lib/kward/tools/typesafe_evaluate.rb

@@ -0,0 +1,81 @@
+require "json"
+require_relative "base"
+require_relative "../model/typesafe_client"
+
+module Kward
+  module Tools
+    # Evaluates bounded state with TypeSafe's typed decision model.
+    class TypeSafeEvaluate < Base
+      def initialize(client: TypeSafeClient.new)
+        @client = client
+        super(
+          "typesafe_evaluate",
+          "Evaluate text with TypeSafe and return typed decisions, probabilities, and confidence. Use for classification, scoring, routing, or verification; this does not generate text.",
+          properties: {
+            state: {
+              type: "string",
+              description: "The text or structured state to evaluate; do not include secrets unless explicitly requested."
+            },
+            model: {
+              type: "string",
+              description: "TypeSafe model ID or alias; defaults to jev-latest."
+            },
+            questions: {
+              type: "object",
+              description: "Named typed questions. Each value must be a noul, choice, or score question.",
+              additionalProperties: {
+                type: "object",
+                properties: {
+                  type: { type: "string", enum: %w[noul choice score] },
+                  instructions: { type: "string" },
+                  criteria: { type: ["object", "array"] }
+                },
+                required: %w[type instructions],
+                additionalProperties: false
+              }
+            }
+          },
+          required: %w[state questions]
+        )
+      end
+
+      def call(args, _conversation, cancellation: nil)
+        state = argument(args, "state").to_s
+        questions = argument(args, "questions")
+        error = validate(state, questions)
+        return "Error: #{error}" if error
+
+        response = @client.evaluate(
+          state: state,
+          questions: questions,
+          model: argument(args, "model") || TypeSafeClient::DEFAULT_MODEL,
+          cancellation: cancellation
+        )
+        JSON.pretty_generate(response)
+      rescue TypeSafeClient::RequestError => e
+        "Error: #{e.message}"
+      rescue JSON::GeneratorError, TypeError => e
+        "Error: invalid TypeSafe response: #{e.message}"
+      end
+
+      private
+
+      def validate(state, questions)
+        return "state must be a non-empty string" if state.empty?
+        return "state exceeds #{TypeSafeClient::MAX_STATE_BYTES} bytes" if state.bytesize > TypeSafeClient::MAX_STATE_BYTES
+        return "questions must be an object" unless questions.is_a?(Hash)
+        return "questions must contain 1-#{TypeSafeClient::MAX_QUESTIONS} entries" if questions.empty? || questions.length > TypeSafeClient::MAX_QUESTIONS
+
+        questions.each do |name, question|
+          return "question names must be non-empty strings" unless name.is_a?(String) && !name.empty?
+          return "question #{name.inspect} must be an object" unless question.is_a?(Hash)
+          type = argument(question, "type").to_s
+          return "question #{name.inspect} has unsupported type" unless %w[noul choice score].include?(type)
+          return "question #{name.inspect} needs instructions" if argument(question, "instructions").to_s.empty?
+          return "question #{name.inspect} needs criteria" if %w[choice score].include?(type) && !argument(question, "criteria")
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/kward/tools/workspace_targets.rb

@@ -0,0 +1,58 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Resolves a small host-scoped set of workspace roles for local tools.
+    # Target names are supplied by trusted runtime orchestration, never by the
+    # model, so selecting a target cannot escape into an arbitrary filesystem
+    # path.
+    class WorkspaceTargets
+      ACTIVE = "active"
+
+      def initialize(active:, targets: {})
+        @workspaces = { ACTIVE => active }
+        targets.each do |name, workspace|
+          name = name.to_s
+          raise ArgumentError, "Workspace target name is required" if name.empty?
+          raise ArgumentError, "Workspace target #{ACTIVE.inspect} is reserved" if name == ACTIVE
+
+          @workspaces[name] = workspace
+        end
+        @workspaces.freeze
+      end
+
+      def workspace_for(args)
+        @workspaces.fetch(target_name(args)) do |name|
+          raise ArgumentError, "Unknown workspace target: #{name}"
+        end
+      end
+
+      def target_name(args)
+        value = if args.respond_to?(:key?)
+                  args[:target] || args["target"]
+                end
+        value.to_s.empty? ? ACTIVE : value.to_s
+      end
+
+      def valid?(args)
+        @workspaces.key?(target_name(args))
+      end
+
+      def properties(properties)
+        return properties if @workspaces.length == 1
+
+        properties.merge(
+          target: {
+            type: "string",
+            enum: @workspaces.keys,
+            description: "Workspace role. Defaults to active; origin is the host repository worktree."
+          }
+        )
+      end
+
+      def without_target(args)
+        args.reject { |key, _value| key.to_s == "target" }
+      end
+    end
+  end
+end

data/lib/kward/tools/write_file.rb

@@ -7,15 +7,15 @@ module Kward
     # Tool wrapper for guarded full-file writes.
     class WriteFile < Base
       # Builds the tool schema and stores the execution dependency.
-      def initialize(workspace:)
-        @workspace = workspace
+      def initialize(workspace:, workspace_targets: nil)
+        configure_workspace_targets(workspace, workspace_targets)
         super(
           "write_file",
           "Write a workspace file. Existing files must be read first.",
-          properties: {
+          properties: targeted_properties(
             path: { type: "string", description: "Workspace-relative path." },
             content: { type: "string", description: "Complete file content." }
-          },
+          ),
           required: ["path", "content"]
         )
       end
@@ -25,8 +25,11 @@ module Kward
         path = argument(args, :path, "")
         content = argument(args, :content, "")
 
-        result = @workspace.write_file(path, content, read_paths: conversation.read_paths)
-        conversation.refresh_system_message! if agents_file_changed?(@workspace, path, result)
+        workspace = workspace_for(args)
+        result = workspace.write_file(path, content, read_paths: conversation.read_paths)
+        if workspace.equal?(@workspace) && agents_file_changed?(workspace, path, result)
+          conversation.refresh_system_message!
+        end
         result
       end
     end

data/lib/kward/{export_path.rb → transcripts/export_path.rb}

@@ -1,5 +1,5 @@
 require "pathname"
-require_relative "path_guard"
+require_relative "../workspace/path_guard"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward

data/lib/kward/{markdown_transcript.rb → transcripts/markdown_transcript.rb}

@@ -1,5 +1,5 @@
-require_relative "message_access"
-require_relative "message_text"
+require_relative "../message_access"
+require_relative "../message_text"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward