ask-tools 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e0b16a246eee9282788e5ec82210cacc6a507d83591645aca2ce87d17e0e129
-  data.tar.gz: 546cf192269daacbbf48e7e1fe4a188ad42d3e5f8e9e50ccaeb3d96ca24803be
+  metadata.gz: aff9f4752095dc3224f21ed08a1bc6768ff211af1f48dcfc51bb1b7c41cab0e3
+  data.tar.gz: acccd4fc9f40e57520e51c55cb71faf302dfd05fa4c7ca4159ffacf4da8b8d19
 SHA512:
-  metadata.gz: 9b6cab4332f8f76e36ccfe1024976578d739258125cdad49567cc9eb0ab21334bff1b28a5c61aee3bdaf21d375e9ac5d78ae2f248f717b1d6c942a0d75b8a51c
-  data.tar.gz: 9a08ac4432817ceb9917f1490a2e1b5c0905609feac8181b9de4404097c1b366b185cd653315e116cf658a655ee48089dec662ce1e5b611024feb0fcde4f2660
+  metadata.gz: 5f37ccab34db3b16d504eb980830dae8ae1acb27c9de568fd3654a4da8604efcf5e27d6b917f280a74c4e6d3815862d54ebcd4bb6e9d2395ecbde0c3aa5730f3
+  data.tar.gz: ca97d4e8122b3d3ae161318f23780b0539c64d450d746a05e88fe56ab32a791ed3d161568ad8288d3d8ef4913a0b7e3bc7812e9c90ab68bb87df1630634bd20c

data/CHANGELOG.md

@@ -1,3 +1,59 @@
+## [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
+
+- **`Ask::Result` now comes from ask-core.** The duplicated `Ask::Result`
+  definition in this gem is removed; ask-tools depends on ask-core
+  (>= 0.9.0), which owns the single result type for the whole ecosystem with
+  both the foundational API (`success`/`failure`/`aborted`/`blocked`) and the
+  tool API (`ok`/`error`/`output`/`ok?`/`error_message`). Previously the two
+  gems' incompatible constructors meant whichever loaded last broke the
+  other's factories (`Ask::Result.success` raised `ArgumentError` in any app
+  loading both).
+
+  The tool API is unchanged:
+
+  ```ruby
+  Ask::Result.ok(data: "hello").output    # => "hello"
+  Ask::Result.error(message: "fail").error  # => "fail"
+  ```
+
+### Tested
+
+- 71 tests, 159 assertions, 0 failures.
+
 ## [0.4.0] — 2026-07-26
 
 ### Added

data/README.md

@@ -1,23 +1,15 @@
 # ask-tools
 
-The foundational gem for the ask-rb ecosystem. Defines `Ask::Tool` — the base class every tool inherits from — along with `Ask::Result` (standardized return value), tool discovery/registration, and a scaffold generator.
+[![Gem Version](https://badge.fury.io/rb/ask-tools.svg)](https://badge.fury.io/rb/ask-tools)
 
-This gem does **not** ship any executable tools. It only provides the contract that tool gems (e.g., `ask-tools-shell`, `ask-tools-filesystem`) implement.
+The tool framework for the ask-rb ecosystem. Defines `Ask::Tool` (the base class every tool inherits from), `Ask::Result` (standardized return value), and the `Ask::Tools` registry. This gem ships no executable tools; tool gems such as ask-tools-shell implement them.
 
 ## Installation
 
-Add this line to your `Gemfile`:
-
 ```ruby
 gem "ask-tools"
 ```
 
-Or install it directly:
-
-```bash
-gem install ask-tools
-```
-
 ## Quick Start
 
 ```ruby
@@ -32,174 +24,60 @@ class Greeter < Ask::Tool
   end
 end
 
-# Use it
-tool = Greeter.new
-tool.name          # => "greeter"
-tool.description   # => "Greets a person by name"
-
-result = tool.call(name: "World")
-result.ok?         # => true
-result.output      # => "Hello, World!"
+result = Greeter.new.call(name: "World")
+result.ok?      # => true
+result.output   # => "Hello, World!"
 ```
 
-## API Reference
-
-### `Ask::Tool` — Base Class
-
-Subclass `Ask::Tool` to define a tool that an LLM can call.
-
-#### Class DSL
-
-| Method | Description |
-|--------|-------------|
-| `description(text)` | Sets or retrieves the tool's human-readable description. Alias: `desc` |
-| `param(name, type:, desc:, required:)` | Declares a parameter. `type` must be a valid JSON Schema type (`:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`) |
-
-#### Instance Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `name` | `String` | Auto-derived from the class name: CamelCase → snake_case, strips `_tool` suffix |
-| `description` | `String?, nil` | The tool's description |
-| `parameters` | `Hash{Symbol => Parameter}` | Declared parameter definitions |
-| `call(args = {})` | `Ask::Result` | Normalizes args (symbolizes keys), validates required params, delegates to `execute`. Catches `Halt` and `StandardError` |
-| `execute(**args)` | `Ask::Result` | **Override this.** Implement the tool's logic. |
-| `params_schema` | `Hash?, nil` | JSON Schema hash for LLM function-calling APIs. Returns `nil` when no params declared |
-| `tool_definition` | `Hash` | Full tool definition hash with `:name`, `:description`, and `:input_schema` |
-
-#### Error Handling
+## Essential API
 
-- **`Ask::Tool::Halt`** — Raise this inside `execute` to signal the conversation loop should stop after this tool's result. `call` returns an `Ask::Result` with `metadata[:halted] = true`.
-- **`StandardError`** — Any other exception raised in `execute` is caught by `call` and returned as an error `Ask::Result`.
+### Ask::Tool
 
-### `Ask::Result` — Return Value
+| Method | Purpose |
+|---|---|
+| `description "..."` (alias `desc`) | Set the tool description |
+| `param :name, type: :string, desc: "...", required: true` | Declare a parameter. `type` must be a JSON Schema type (`:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`) |
+| `name "custom_tool"` | Set a custom tool name (default: derived from the class name, CamelCase to snake_case, `_tool` suffix stripped) |
+| `params do ... end` | Declare parameters with the ask-schema DSL |
 
-A value object representing the outcome of a tool execution.
+Override `execute(**args)` with the tool logic. `call(args)` normalizes input (JSON strings and hash keys), validates required parameters, and returns an `Ask::Result`. Raising `Ask::Tool::Halt` inside `execute` yields a success result with `metadata[:halted] = true`; any other exception becomes a failure result.
 
-#### Factory Methods
+### Ask::Result
 
 ```ruby
-# Successful result
 Ask::Result.ok(data: "output", metadata: { key: "val" })
-
-# Failed result
 Ask::Result.error(message: "Something went wrong", metadata: { code: 500 })
+Ask::Result.failure("Something went wrong")
+
+result.ok?       # => true
+result.output    # => "output"
+result.error     # => nil
+result.metadata  # => { key: "val" }
+result.to_s      # => "output"
+result.to_h      # => { ok: true, output: "output", error: nil, metadata: { key: "val" } }
 ```
 
-#### Attributes
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `ok?` / `ok` | `Boolean` | Whether the tool completed successfully |
-| `output` | `Object?, nil` | Output data (success) |
-| `error` | `String?, nil` | Error message (failure) |
-| `metadata` | `Hash` | Arbitrary metadata |
-
-#### Instance Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `to_s` | `String` | Returns `output.to_s` for success, `error` for failure |
-| `to_h` | `Hash` | Serialized hash with `:ok`, `:output`, `:error`, `:metadata` |
-| `inspect` | `String` | Human-readable representation |
-
-### `Ask::Tool::Parameter` — Parameter Definition
-
-Internal value object describing a declared parameter. Accessible via `Tool.parameters[name]`.
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `name` | `Symbol` | Parameter name |
-| `type` | `String` | JSON Schema type string |
-| `description` | `String?, nil` | Human-readable description |
-| `required` / `required?` | `Boolean` | Whether the parameter is mandatory |
-
-### `Ask::Tools` — Registry & Discovery
-
-Central registry for tool classes.
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `.register(tool_class)` | `void` | Manually register a tool class |
-| `.all` | `Array<Tool>` | Instantiated list of all registered tools |
-| `.discover` | `Array<Class>` | Auto-discover loaded `Ask::Tool` subclasses via `ObjectSpace` |
-| `.[](name)` | `Tool?, nil` | Find a registered tool by its derived name |
-| `.clear` | `void` | Remove all registered tools |
-| `.count` | `Integer` | Number of registered tool classes |
-
-```ruby
-# Manual registration
-Ask::Tools.register(MyTool)
-
-# Auto-discover all loaded Ask::Tool subclasses
-Ask::Tools.discover
-
-# Find by name
-tool = Ask::Tools["my_tool"]
-tool.call(input: "hello")
-
-# List all
-Ask::Tools.all.each { |t| puts t.name }
-```
-
-## Defining a Custom Tool
+### Ask::Tools registry
 
-```ruby
-class SearchTool < Ask::Tool
-  description "Searches a knowledge base"
-  param :query, type: :string, desc: "Search query", required: true
-  param :limit, type: :integer, desc: "Max results", required: false
-
-  def execute(query:, limit: 10)
-    results = perform_search(query, limit)
-    Ask::Result.ok(data: results)
-  rescue SearchError => e
-    Ask::Result.error(message: e.message)
-  end
+| Method | Purpose |
+|---|---|
+| `Ask::Tools.register(ToolClass)` | Register a tool class manually |
+| `Ask::Tools.all` | Instances of all registered tools |
+| `Ask::Tools.discover` | Auto-register loaded `Ask::Tool` subclasses via ObjectSpace |
+| `Ask::Tools["name"]` | Find a tool instance by derived name |
+| `Ask::Tools.clear` / `Ask::Tools.count` | Reset and count the registry |
 
-  private
+## Full documentation
 
-  def perform_search(query, limit)
-    # ... implementation
-  end
-end
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-tools in depth](https://ask-rb.github.io/ask-docs/core/tools) covers the tool contract, parameter schemas, and custom tool examples. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
-# Install dependencies
-bundle install
-
-# Run tests
-bundle exec rake test
-
-# Build the gem
-gem build ask-tools.gemspec
 ```
-
-## Testing
-
-ask-tools uses **Minitest** with **Mocha** for mocking.
-
-```bash
-# Run the full test suite
+bundle install
 bundle exec rake test
 ```
 
-## Release Process
-
-1. Update `CHANGELOG.md`
-2. Update `lib/ask/version.rb` if needed
-3. Build the gem: `gem build ask-tools.gemspec`
-4. Push to GitHub Packages: `gem push ask-tools-*.gem`
-
 ## License
 
-MIT — see [LICENSE](LICENSE).
-
-## Links
-
-- **Source:** https://github.com/ask-rb/ask-tools
-- **Issues:** https://github.com/ask-rb/ask-tools/issues
-- **Docs:** https://github.com/ask-rb/ask-docs
+MIT

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.4.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/ask-tools.rb

@@ -2,7 +2,7 @@
 
 require_relative "ask/version"
 require_relative "ask/tools"
-require_relative "ask/tools/result"
+require "ask"  # ask-core: the shared Ask::Result lives here
 require_relative "ask/tools/tool"
 
 module Ask

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tools
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: ask-schema
   requirement: !ruby/object:Gem::Requirement
@@ -65,7 +79,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Defines Ask::Tool (base class), Ask::Result, and tool discovery.
+description: Defines Ask::Tool (base class), tool discovery, and the Ask::Result returned
+  by tools.
 email:
 - kaka@myrrlabs.com
 executables: []
@@ -77,7 +92,6 @@ files:
 - README.md
 - lib/ask-tools.rb
 - lib/ask/tools.rb
-- lib/ask/tools/result.rb
 - lib/ask/tools/tool.rb
 - lib/ask/version.rb
 homepage: https://github.com/ask-rb/ask-tools

data/lib/ask/tools/result.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  # Standardized return value for tool execution.
-  #
-  # Every tool's #execute method should return an Ask::Result.
-  # Use the factory methods +.ok+ and +.error+ for common cases.
-  #
-  #   Ask::Result.ok(data: "hello world")
-  #   Ask::Result.error(message: "something went wrong")
-  #
-  class Result
-    # @return [Boolean] whether the tool completed successfully
-    attr_reader :ok
-
-    # @return [Object, nil] the output data when the tool succeeded
-    attr_reader :output
-
-    # @return [String, nil] the error message when the tool failed
-    attr_reader :error
-
-    # @return [Hash] arbitrary metadata attached to the result
-    attr_reader :metadata
-
-    alias ok? ok
-
-    # @return [Boolean] whether the tool failed
-    def error?
-      !ok
-    end
-
-    # @return [String, nil] the error message (alias for +error+)
-    alias error_message error
-
-    def initialize(ok:, output: nil, error: nil, metadata: {})
-      @ok = ok
-      @output = output
-      @error = error
-      @metadata = metadata
-    end
-
-    # Create a successful result.
-    #
-    # @param data [Object] the tool's output
-    # @param metadata [Hash] optional metadata
-    # @return [Ask::Result]
-    def self.ok(data:, metadata: {})
-      new(ok: true, output: data, error: nil, metadata: metadata)
-    end
-
-    # Create a failed result (positional message form, used by Tool#call).
-    #
-    # @param message [String] description of the failure
-    # @param metadata [Hash] optional metadata
-    # @return [Ask::Result]
-    def self.failure(message, metadata: {})
-      new(ok: false, output: nil, error: message, metadata: metadata)
-    end
-
-    # Create a failed result.
-    #
-    # @param message [String] description of the failure
-    # @param metadata [Hash] optional metadata
-    # @return [Ask::Result]
-    def self.error(message:, metadata: {})
-      new(ok: false, output: nil, error: message, metadata: metadata)
-    end
-
-    # Human-readable representation.
-    # Returns the output for success or the error message for failure.
-    #
-    # @return [String]
-    def to_s
-      ok? ? output.to_s : error.to_s
-    end
-
-    # Hash representation suitable for serialization.
-    #
-    # @return [Hash]
-    def to_h
-      {
-        ok: ok,
-        output: output,
-        error: error,
-        metadata: metadata
-      }
-    end
-
-    # @return [String] inspect string
-    def inspect
-      if ok?
-        "#<Ask::Result ok=true output=#{output.inspect}>"
-      else
-        "#<Ask::Result ok=false error=#{error.inspect}>"
-      end
-    end
-  end
-end