ask-tools 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 549044a60c0528c6cd72c66bdcada359b56e106a169237d17661841f751a090f
-  data.tar.gz: e315d06d73942a45c0cf0835069e403f221d89322ed2f456ea1ac7879db21ab8
+  metadata.gz: aff9f4752095dc3224f21ed08a1bc6768ff211af1f48dcfc51bb1b7c41cab0e3
+  data.tar.gz: acccd4fc9f40e57520e51c55cb71faf302dfd05fa4c7ca4159ffacf4da8b8d19
 SHA512:
-  metadata.gz: 4145513e16e503594071295d6e244ce6afad3fa55b83dbe33d88620226e0f4e152ec8837560fb85d89a5c992e19ce345fcc93775396af7e9471517cbc3c9ca91
-  data.tar.gz: 19a7e533b4d2614ff2842cbcac201393c79bc7d4fafe63e1b3c72592b63bddc887f6d517b726aabad51bbc19d916df4b06d688dd9818172c5f0ba40c4c525443
+  metadata.gz: 5f37ccab34db3b16d504eb980830dae8ae1acb27c9de568fd3654a4da8604efcf5e27d6b917f280a74c4e6d3815862d54ebcd4bb6e9d2395ecbde0c3aa5730f3
+  data.tar.gz: ca97d4e8122b3d3ae161318f23780b0539c64d450d746a05e88fe56ab32a791ed3d161568ad8288d3d8ef4913a0b7e3bc7812e9c90ab68bb87df1630634bd20c

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)
@@ -149,6 +194,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)

data/lib/ask/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Tools
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   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.0
 platform: ruby
 authors:
 - Kaka Ruto