ask-tools 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 549044a60c0528c6cd72c66bdcada359b56e106a169237d17661841f751a090f
-  data.tar.gz: e315d06d73942a45c0cf0835069e403f221d89322ed2f456ea1ac7879db21ab8
+  metadata.gz: b7722a402e1411950d63a055707c676b7c68af27550284f56a7d3cb5b316af78
+  data.tar.gz: 19012fdeba501720ae891cc7b62b1a797482170a3ccbfef5cee59218d8446c59
 SHA512:
-  metadata.gz: 4145513e16e503594071295d6e244ce6afad3fa55b83dbe33d88620226e0f4e152ec8837560fb85d89a5c992e19ce345fcc93775396af7e9471517cbc3c9ca91
-  data.tar.gz: 19a7e533b4d2614ff2842cbcac201393c79bc7d4fafe63e1b3c72592b63bddc887f6d517b726aabad51bbc19d916df4b06d688dd9818172c5f0ba40c4c525443
+  metadata.gz: 18cc40a7fe9902a71b658aa857693f1734d25456dc1c03d38334596e1b840e80b605f0401a3237a7009423903c890a577a2829c12a59dfea2debc22d832823b4
+  data.tar.gz: 5a9c6578a61fed0c87210332be3efe8d3d98a1fa2a16bfa0546bba6a0de8b713c1ab5eacdb6bedc8883451a9f911ca6eee0a12733cdb37af90f21cbfe2060a20

data/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [0.6.0] — 2026-08-06
+
+### Added
+
+- **`Ask::Tool.approval_required` — declare that a tool needs human approval.**
+  Combined with `Ask::Agent::ApprovalQueue` (ask-agent), calls to the tool are
+  queued instead of executed — the agent gets a pending result and continues,
+  and the tool only runs after a human approves it. Defaults to false; the
+  flag is not inherited by subclasses.
+
+  ```ruby
+  class SendEmail < Ask::Tool
+    approval_required true
+    def execute(to:, body:) ... end
+  end
+  ```
+
+- **`Ask::Tool.auto_approvable` — declare that a tool may be auto-approved.**
+  A per-action verdict only: the session's user-enabled rule is still the
+  binding gate (dual signal). A tool that requires approval but is NOT marked
+  auto-approvable always queues for human review.
+
+  ```ruby
+  class Ping < Ask::Tool
+    approval_required true
+    auto_approvable true
+    def execute ... end
+  end
+  ```
+
+- Instance predicates `#approval_required?` and `#auto_approvable?`.
+
 ## [0.5.0] — 2026-08-03
 
 ### Changed

data/lib/ask/tools/tool.rb

@@ -21,6 +21,8 @@ module Ask
         subclass.instance_variable_set(:@parameters, {})
         subclass.instance_variable_set(:@params_schema_definition, nil)
         subclass.instance_variable_set(:@tool_name, nil)
+        subclass.instance_variable_set(:@approval_required, nil)
+        subclass.instance_variable_set(:@auto_approvable, nil)
       end
 
       def description(text = nil)
@@ -41,6 +43,49 @@ module Ask
         end
       end
 
+      # Declare that calling this tool requires human approval.
+      #
+      # The tool is still registered and described to the LLM normally, but
+      # when an agent session runs with an approval queue enabled, calls to
+      # it are queued instead of executed — the agent gets a pending result,
+      # and the tool only runs after a human approves it.
+      #
+      # Called with no argument returns the current value (default false).
+      #
+      # @example
+      #   class SendEmail < Ask::Tool
+      #     approval_required true
+      #     def execute(to:, body:) ... end
+      #   end
+      #
+      # @param value [Boolean, nil]
+      # @return [Boolean]
+      def approval_required(value = :_no_arg_given)
+        if value == :_no_arg_given
+          @approval_required == true
+        else
+          @approval_required = !!value
+        end
+      end
+
+      # Declare that this tool may be auto-approved when the session's
+      # approval policy has auto-approval enabled for it. This is a
+      # per-action verdict only — the session-level user rule is still the
+      # binding gate. A tool that requires approval but is NOT marked
+      # auto-approvable always queues for human review.
+      #
+      # Called with no argument returns the current value (default false).
+      #
+      # @param value [Boolean, nil]
+      # @return [Boolean]
+      def auto_approvable(value = :_no_arg_given)
+        if value == :_no_arg_given
+          @auto_approvable == true
+        else
+          @auto_approvable = !!value
+        end
+      end
+
       def param(name, type:, desc: nil, description: nil, required: true)
         type = type.to_s.downcase.to_sym
         validate_param_type!(type, name)
@@ -54,8 +99,32 @@ module Ask
         @params_schema_definition = schema || block
       end
 
+      # The tool's declared parameters — or, when none are declared,
+      # inferred from the execute signature so a tool is never silently
+      # uncallable: a tool whose execute takes keyword arguments but
+      # declares no params would otherwise reject every call ("unknown
+      # parameters"). Inference is a fallback, never an override: an
+      # explicit `params`/`param` declaration wins.
       def parameters
         @parameters ||= {}
+        if @parameters.empty? && @params_schema_definition.nil? && !@parameters_inferred
+          infer_parameters_from_execute
+        end
+        @parameters
+      end
+
+      # Derive parameters from `def execute(project_id:, title:, ...)`:
+      # required keywords become required string parameters. Ruby types
+      # aren't introspectable, so everything infers as string (JSON
+      # numbers coerce); tools that need real types declare `params`.
+      def infer_parameters_from_execute
+        @parameters_inferred = true
+        instance_method(:execute).parameters.each do |kind, name|
+          next unless %i[keyreq key opt].include?(kind)
+          next if name.nil? || name == :_abort_controller
+
+          @parameters[name] = Parameter.new(name: name, type: "string", required: kind == :keyreq)
+        end
       end
 
       def provider_params
@@ -66,7 +135,7 @@ module Ask
         @params_schema ||= begin
           if @params_schema_definition
             deep_stringify_keys(resolve_params_schema(@params_schema_definition))
-          elsif @parameters && @parameters.any?
+          elsif parameters.any?
             build_schema_from_params
           else
             nil
@@ -149,6 +218,17 @@ module Ask
       self.class.parameters
     end
 
+    # @return [Boolean] whether calling this tool requires human approval
+    def approval_required?
+      self.class.approval_required
+    end
+
+    # @return [Boolean] whether this tool may be auto-approved under a
+    #   session-level auto-approval rule
+    def auto_approvable?
+      self.class.auto_approvable
+    end
+
       def call(args = {}, abort_controller = nil)
       normalized = normalize_args(args)
       validation = validate(normalized)
@@ -189,8 +269,42 @@ module Ask
       "#<#{self.class.name} name=#{name.inspect}>"
     end
 
+    # Validate normalized (symbol-keyed) arguments. Returns nil when
+    # valid, or an actionable message — one that names what was expected
+    # — so the model (or a repair pass) can correct the call instead of
+    # guessing. Public: ask-agent's tool-call repair validates through
+    # this. Tools with a declared `params` block validate against the
+    # resolved schema (required keys + unknown keys when strict).
+    def validate(normalized)
+      return validate_against_schema(normalized) if params_schema_definition
+
+      expected = self.class.parameters.keys
+      missing = expected.select { |name| self.class.parameters[name].required && !normalized.key?(name) }
+      return "missing required parameters: #{missing.map(&:inspect).join(', ')} — expected: #{expected.map(&:inspect).join(', ')}" unless missing.empty?
+
+      unknown = normalized.keys - expected
+      return "unknown parameters: #{unknown.map(&:inspect).join(', ')} — expected: #{expected.map(&:inspect).join(', ')}" unless unknown.empty?
+
+      nil
+    end
+
     private
 
+    def validate_against_schema(normalized)
+      schema = params_schema || {}
+      expected = Array(schema["required"])
+      missing = expected - normalized.keys.map(&:to_s)
+      return "missing required parameters: #{missing.map(&:inspect).join(', ')} — expected: #{expected.map(&:inspect).join(', ')}" unless missing.empty?
+
+      properties = schema["properties"] || {}
+      if schema["additionalProperties"] == false
+        unknown = normalized.keys.map(&:to_s) - properties.keys
+        return "unknown parameters: #{unknown.map(&:inspect).join(', ')} — expected: #{properties.keys.map(&:inspect).join(', ')}" unless unknown.empty?
+      end
+
+      nil
+    end
+
     def params_schema_definition
       self.class.instance_variable_get(:@params_schema_definition)
     end
@@ -238,15 +352,6 @@ module Ask
       args.respond_to?(:transform_keys) ? args.transform_keys(&:to_sym) : {}
     end
 
-    def validate(normalized)
-      return nil if params_schema_definition
-      missing = self.class.parameters.select { |_, p| p.required && !normalized.key?(p.name) }
-      return "missing required parameters: #{missing.keys.map(&:inspect).join(', ')}" unless missing.empty?
-      unknown = normalized.keys - self.class.parameters.keys
-      return "unknown parameters: #{unknown.map(&:inspect).join(', ')}" unless unknown.empty?
-      nil
-    end
-
     VALID_JSON_SCHEMA_TYPES = %i[string integer number boolean array object].freeze
 
     class Parameter

data/lib/ask/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Tools
-    VERSION = "0.5.0"
+    VERSION = "0.6.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tools
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -115,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Tool framework for the ask-rb ecosystem
 test_files: []