kward 0.83.0 → 0.85.0

data/lib/kward/tools/list_directory.rb

@@ -7,19 +7,19 @@ module Kward
     # Tool wrapper for listing workspace directory entries.
     class ListDirectory < 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(
           "list_directory",
           "List workspace directory entries.",
-          properties: { path: { type: "string", description: "Workspace-relative directory." } },
+          properties: targeted_properties(path: { type: "string", description: "Workspace-relative directory." }),
           required: ["path"]
         )
       end
 
       # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
-        @workspace.list_directory(argument(args, :path, "."))
+        workspace_for(args).list_directory(argument(args, :path, "."))
       end
     end
   end

data/lib/kward/tools/open_editor.rb

@@ -0,0 +1,41 @@
+require_relative "base"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Tool wrapper for opening a workspace file in the integrated editor.
+    class OpenEditor < Base
+      # Builds the tool schema and stores the execution dependencies.
+      def initialize(workspace:, prompt:)
+        @workspace = workspace
+        @prompt = prompt
+        super(
+          "open_editor",
+          "Open a workspace file in Kward's integrated editor for the user. Use this when the user explicitly asks to open or edit a file in the built-in editor. This does not itself modify or save the file; the user controls those actions in the editor.",
+          properties: {
+            path: { type: "string", description: "Workspace-relative path of the file to open." }
+          },
+          required: ["path"]
+        )
+      end
+
+      # Opens the requested file and returns after the editor closes.
+      def call(args, _conversation, cancellation: nil)
+        cancellation&.raise_if_cancelled!
+        return "Error: open_editor requires interactive editor support." unless @prompt.respond_to?(:edit_file)
+
+        path = argument(args, :path, "").to_s
+        return "Error: open_editor requires a file path." if path.empty?
+
+        resolved_path = @workspace.resolved_path(path)
+        return "Error: not a file: #{path}" unless File.file?(resolved_path)
+
+        opened = @prompt.edit_file(resolved_path, base_dir: @workspace.root, allow_new: false)
+        opened ? "Opened #{path} in the integrated editor." : "Error: could not open #{path} in the integrated editor."
+      rescue SecurityError, StandardError => e
+        "Error: could not open #{path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/kward/tools/plugin_tool.rb

@@ -0,0 +1,41 @@
+require_relative "base"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Adapts a trusted plugin tool registration to the normal tool interface.
+    class PluginTool < Base
+      attr_reader :plugin_path
+
+      def initialize(registration:, context_factory:)
+        @description = registration.description
+        @parameters = registration.schema
+        @plugin_path = registration.path
+        @handler = registration.handler
+        @context_factory = context_factory
+        super(registration.name, registration.description)
+      end
+
+      # Returns the strict JSON schema declared by the plugin.
+      def schema
+        {
+          type: "function",
+          function: {
+            name: name,
+            description: @description,
+            parameters: @parameters
+          }
+        }
+      end
+
+      # Executes trusted plugin code with parsed model arguments and scoped context.
+      def call(args, conversation, cancellation: nil)
+        context = @context_factory.call(conversation, cancellation)
+        result = @handler.call(args, context)
+        cancellation&.raise_if_cancelled!
+        result.to_s
+      end
+    end
+  end
+end

data/lib/kward/tools/prepare_shell_command.rb

@@ -1,5 +1,5 @@
 require_relative "base"
-require_relative "../shell_prompt_session"
+require_relative "../shell/prompt_session"
 
 # Namespace for the Kward agent runtime.
 module Kward

data/lib/kward/tools/read_file.rb

@@ -7,18 +7,18 @@ module Kward
     # Tool wrapper for bounded workspace file reads.
     class ReadFile < 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(
           "read_file",
           "Read a workspace text file. Output is capped; use offset/limit or mode to control context budget.",
-          properties: {
+          properties: targeted_properties(
             path: { type: "string", description: "Workspace-relative path." },
             limit: { type: "integer", description: "Maximum lines to return." },
             max_bytes: { type: "integer", description: "Optional byte budget for this read, capped by Kward's workspace read limit." },
             mode: { type: "string", enum: %w[preview outline range full], description: "Context mode. preview returns a short slice, outline returns source declarations, range reads offset/limit, full reads until Kward's cap." },
             offset: { type: "integer", description: "1-indexed start line." }
-          },
+          ),
           required: ["path"]
         )
       end
@@ -30,8 +30,9 @@ module Kward
         limit = argument(args, :limit)
         mode = argument(args, :mode)
         max_bytes = argument(args, :max_bytes)
-        content = @workspace.read_file(path, offset: offset, limit: limit, mode: mode, max_bytes: max_bytes)
-        conversation.mark_read(@workspace.resolved_path(path)) unless content.start_with?("Error:")
+        workspace = workspace_for(args)
+        content = workspace.read_file(path, offset: offset, limit: limit, mode: mode, max_bytes: max_bytes)
+        conversation.mark_read(workspace.resolved_path(path)) unless content.start_with?("Error:")
         content
       end
     end

data/lib/kward/tools/registry.rb

@@ -11,14 +11,18 @@ 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"
 require_relative "search/code"
 require_relative "search/web"
@@ -28,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
@@ -65,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
@@ -73,20 +101,24 @@ 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 prompt [Object, nil] interactive prompt bridge; must implement
-    #   `ask_user_question` before that tool is advertised
+    # @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
     # @param web_fetch [WebFetch] specific URL fetch implementation
     # @param code_search [CodeSearch] public source/package search implementation
     # @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
@@ -96,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)
@@ -113,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
@@ -162,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}")
@@ -253,11 +299,13 @@ module Kward
       case tool
       when Tools::MCPTool
         "mcp"
+      when Tools::PluginTool
+        "plugin"
       when Tools::WebSearch, Tools::FetchContent, Tools::FetchRaw
         "web"
       when Tools::ReadSkill
         "skill"
-      when Tools::AskUserQuestion
+      when Tools::AskUserQuestion, Tools::OpenEditor
         "ui"
       else
         "builtin"
@@ -490,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
 
@@ -513,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
@@ -522,10 +582,13 @@ module Kward
     def build_schema_tools
       tools = @tools.values_at(*CORE_TOOL_NAMES)
       tools << @tools["replace_editor_buffer"] if @tools["replace_editor_buffer"]
+      tools << @tools["open_editor"] if @tools["open_editor"]
       tools << @tools["prepare_shell_command"] if @tools["prepare_shell_command"]
       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
@@ -533,30 +596,32 @@ 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
       ]
       tools << Tools::ReplaceEditorBuffer.new(editor_prompt_session: @editor_prompt_session) if @editor_prompt_session
+      tools << Tools::OpenEditor.new(workspace: @workspace, prompt: @prompt) if editor_available?
       tools << Tools::PrepareShellCommand.new(shell_prompt_session: @shell_prompt_session) if @shell_prompt_session
       tools
     end
@@ -565,10 +630,14 @@ 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
 
+    def editor_available?
+      @prompt&.respond_to?(:edit_file)
+    end
+
     def editor_prompt_tool_names
       readonly_tools = CORE_TOOL_NAMES - %w[write_file edit_file run_shell_command]
       readonly_tools + ["replace_editor_buffer"]
@@ -576,7 +645,9 @@ module Kward
 
     def shell_prompt_tool_names
       readonly_tools = CORE_TOOL_NAMES - %w[write_file edit_file run_shell_command]
-      readonly_tools + %w[run_shell_command prepare_shell_command]
+      tools = readonly_tools + %w[run_shell_command prepare_shell_command]
+      tools << "open_editor" if editor_available?
+      tools
     end
 
     def web_search_available?
@@ -602,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

@@ -26,7 +26,9 @@ module Kward
       "fetch_raw" => "fetch_raw",
       "git_commit" => "git_commit",
       "read_skill" => "read_skill",
-      "ask_user_question" => "ask_user_question"
+      "ask_user_question" => "ask_user_question",
+      "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