ask-agent 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d32526c4ac8d8daa60b4f4b63e5787617c2070154cb854f6fff61222f880185d
-  data.tar.gz: cd528117e7577374e8c41a423ec72c9fd1560980017f968d215f674b1a916e3c
+  metadata.gz: f67174ee80499aad6a21ff621f02c341daf0e992392996d577218aec2d8987ab
+  data.tar.gz: 25b21cc738b1e106730330b3ec28b118545f96a296898e4e9b3e337b4a2bf9a0
 SHA512:
-  metadata.gz: 4c210ccc2a08d0ed0d2bb60a560aac06635633c816bfd4d5b9ae21b2139af3ae5729b37fb46b795e48b0bbc2975c33e855cea695b507ad306ce04187330605a7
-  data.tar.gz: fb3954229781a8e34a517a0e8d81369e55579ae4c18f041ffb4c99b3295c628bb0e5b49d9f08d080b4cd6d556614ddb5b5cac685b9c7d5813bfb0371281d1e54
+  metadata.gz: 74fdca8fecf20a3707bf162a319a0b4fa910f3718745fa8276235200e66e98ddd9a005cd7d4ce4bb5fc7d74321a1a86983934cc17041e6a20e58bce48156ce75
+  data.tar.gz: 78250a88b07fe2265e276ab5f156dd1c712315585eb906d81a198825c63450cf470ec48702bfbab2ac4b4d757523ff53a86d28646293e21809891626af4616c7

data/CHANGELOG.md

@@ -1,3 +1,56 @@
+## [0.27.0] — 2026-08-06
+
+### Added
+
+- **Human-in-the-loop tool approval — `Ask::Agent::ApprovalQueue`.** Tools
+  declared `approval_required` (ask-tools) are queued instead of executed:
+  the agent receives a pending result and continues, and the tool runs only
+  after a human approves it. Built on the async-tools seam
+  (`Ask::Result.pending` → `register_pending_tool` → `complete_pending_tool`).
+
+  ```ruby
+  session = Ask::Agent::Session.new(
+    model: "gpt-4o",
+    tools: [SendEmail],          # SendEmail.approval_required true
+    approval: { auto_approve: {} }
+  )
+  session.run("Email bob about the launch")
+
+  # Later, when the user decides:
+  session.approval_queue.pending_actions   # inspect what's waiting
+  session.approval_queue.approve_all       # or approve(id) / reject(id)
+  ```
+
+  - `approval: true` enables with defaults; a Hash accepts
+    `require_approval:` (tool names / regexps / `:all`) and `auto_approve:`
+    (user-enabled rules keyed by tool name). A custom `ApprovalQueue`
+    instance is accepted too.
+  - **Auto-approval is a dual signal** — a tool marked `auto_approvable`
+    AND a user rule enabling it. Nothing is silently applied past a manual
+    (non-auto-approvable) gate; eligible actions drain in id order with a
+    single-flight guard (no double-apply).
+  - **Approving executes the real tool** and feeds the result into the
+    conversation; **rejecting** injects a "rejected by the user" message and
+    the agent adapts. Failed applies leave the action pending for retry.
+  - `Session#approval_queue` returns the queue (nil when approval is off).
+
+- **`Ask::Agent::Extensions::ApprovalPolicy`** — the classification hook.
+  Queues calls for tools whose class declares `approval_required`, or whose
+  name matches rule-based lists, or (with `require_approval: :all`) every
+  call. Usable standalone as a `before_tool` hook.
+
+### Changed
+
+- `ToolExecutor` before-tool hooks now support a `:pending` action alongside
+  `:block` and `:short_circuit`, returning a pending tool result.
+
+## [0.26.1] - 2026-08-05
+
+### Added
+
+- **`Session#pending_tools?`** — true while any async tool is still running;
+  the voice seam uses it to tell the worker a completion is coming.
+
 ## [0.26.0] - 2026-08-05
 
 ### Added

data/lib/ask/agent/approval_queue.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    # A queue of tool actions awaiting human approval.
+    #
+    # When an agent calls a tool that requires approval, the action is queued
+    # instead of executed — the agent gets a pending result and continues.
+    # The user approves or rejects actions later, in bulk or one-by-one.
+    #
+    #   queue = Ask::Agent::ApprovalQueue.new
+    #   id = queue.submit(tool_call_id: "call_1", tool_name: "send_email",
+    #                     args: { "to" => "x@y.com" }, auto_approvable: false)
+    #   queue.pending_actions   # => [{id: 1, tool_name: "send_email", ...}]
+    #   queue.approve(1)        # applies action 1 via the on_approve callback
+    #   queue.reject(1)
+    #
+    # Auto-approval is a dual signal: the action must be marked
+    # +auto_approvable+ (by the tool) AND the queue must have a matching
+    # auto-approval rule enabled by the user. Otherwise the action queues for
+    # human review.
+    #
+    # Actions are applied in id order and the drainer never applies past a
+    # non-auto-approvable (manual) gate — nothing is silently approved.
+    class ApprovalQueue
+      # One queued action.
+      #
+      # @!attribute [r] id
+      #   @return [Integer] sequential id assigned by the queue
+      # @!attribute [r] tool_call_id
+      #   @return [String] the original tool call id from the LLM
+      # @!attribute [r] tool_name
+      #   @return [String] tool name
+      # @!attribute [r] args
+      #   @return [Hash] arguments to pass to the tool when applied
+      # @!attribute [r] auto_approvable
+      #   @return [Boolean] per-action verdict (tool's declaration)
+      # @!attribute [r] status
+      #   @return [Symbol] :pending, :applying, :approved, :rejected
+      # @!attribute [r] submitted_at
+      #   @return [Time]
+      # @!attribute [r] message
+      #   @return [String, nil] human-readable description of the action
+      Action = Data.define(:id, :tool_call_id, :tool_name, :args,
+                           :auto_approvable, :status, :submitted_at, :message)
+
+      # Create a new approval queue.
+      #
+      # @param on_approve [Proc, nil] called with an {Action} when it is
+      #   approved and applied. The session wires this to execute the real
+      #   tool call.
+      # @param on_reject [Proc, nil] called with an {Action} when it is
+      #   rejected. The session wires this to notify the conversation.
+      # @param auto_approve [Hash{String => Boolean}, nil] user-enabled
+      #   auto-approval rules keyed by tool name. An action is auto-applied
+      #   only when its tool is listed here with +true+ AND the action itself
+      #   is marked auto_approvable.
+      def initialize(on_approve: nil, on_reject: nil, auto_approve: nil)
+        @on_approve = on_approve
+        @on_reject = on_reject
+        @auto_approve = auto_approve || {}
+        @actions = {}
+        @next_id = 1
+        @mutex = Mutex.new
+        @draining = false
+      end
+
+      # Queue a tool action for approval.
+      #
+      # @param tool_call_id [String] original tool call id from the LLM
+      # @param tool_name [String] tool name
+      # @param args [Hash] arguments for the tool
+      # @param auto_approvable [Boolean] whether the tool permits auto-approval
+      # @param message [String, nil] human-readable description
+      # @return [Integer] the action id
+      def submit(tool_call_id:, tool_name:, args: {}, auto_approvable: false, message: nil)
+        action = @mutex.synchronize do
+          action = Action.new(
+            id: @next_id,
+            tool_call_id: tool_call_id,
+            tool_name: tool_name,
+            args: args || {},
+            auto_approvable: auto_approvable,
+            status: :pending,
+            submitted_at: Time.now,
+            message: message
+          )
+          @next_id += 1
+          @actions[action.id] = action
+          action
+        end
+
+        drain
+        action.id
+      end
+
+      # All actions still awaiting a decision, in id order.
+      #
+      # @return [Array<Action>]
+      def pending_actions
+        @mutex.synchronize do
+          @actions.values.select { |a| a.status == :pending }.sort_by(&:id)
+        end
+      end
+
+      # @param id [Integer]
+      # @return [Boolean] whether the action is still awaiting a decision
+      def pending?(id)
+        @mutex.synchronize do
+          a = @actions[id]
+          a && a.status == :pending
+        end
+      end
+
+      # @return [Boolean] true while at least one action awaits a decision
+      def any_pending?
+        pending_actions.any?
+      end
+
+      # Look up an action by id.
+      #
+      # @param id [Integer]
+      # @return [Action, nil]
+      def [](id)
+        @mutex.synchronize { @actions[id] }
+      end
+
+      # Approve specific actions (by id), applying them in id order.
+      #
+      # @param ids [Array<Integer>]
+      # @return [Array<Action>] the actions that were approved
+      def approve(*ids)
+        actions = ids.flatten.filter_map { |id| @mutex.synchronize { @actions[id] } }
+        actions.select! { |a| a.status == :pending }
+        actions.sort_by!(&:id)
+        actions.each { |a| apply(a) }
+        actions
+      end
+
+      # Reject specific actions (by id).
+      #
+      # @param ids [Array<Integer>]
+      # @return [Array<Action>] the actions that were rejected
+      def reject(*ids)
+        actions = ids.flatten.filter_map { |id| @mutex.synchronize { @actions[id] } }
+        actions.select! { |a| a.status == :pending }
+        actions.sort_by!(&:id)
+        actions.each { |a| reject_action(a) }
+        actions
+      end
+
+      # Approve all currently pending actions, in id order.
+      #
+      # @return [Array<Action>]
+      def approve_all
+        approve(*pending_actions.map(&:id))
+      end
+
+      # Reject all currently pending actions, in id order.
+      #
+      # @return [Array<Action>]
+      def reject_all
+        reject(*pending_actions.map(&:id))
+      end
+
+      private
+
+      # Apply eligible pending actions in id order, stopping at the first
+      # action that is NOT auto-eligible (a manual gate) — nothing is
+      # silently applied past a human review point. Single-flight guard so
+      # concurrent drains cannot double-apply.
+      def drain
+        return if @mutex.synchronize { @draining }
+        @mutex.synchronize { @draining = true }
+
+        begin
+          loop do
+            action = @mutex.synchronize do
+              @actions.values.select { |a| a.status == :pending }
+                .sort_by(&:id)
+                .first
+            end
+            break unless action
+
+            if auto_approvable?(action)
+              apply(action)
+            else
+              break # manual gate — stop, never skip ahead
+            end
+          end
+        ensure
+          @mutex.synchronize { @draining = false }
+        end
+      end
+
+      def auto_approvable?(action)
+        action.auto_approvable && @auto_approve[action.tool_name] == true
+      end
+
+      def apply(action)
+        claimed = @mutex.synchronize do
+          return false unless action.status == :pending
+          @actions[action.id] = action.with(status: :applying)
+        end
+        @on_approve&.call(claimed)
+        @mutex.synchronize do
+          @actions[action.id] = claimed.with(status: :approved)
+        end
+        true
+      rescue StandardError
+        # Failed apply: leave the action pending so the user can retry or
+        # reject it. Re-raise so the caller (approve/drain) surfaces it.
+        @mutex.synchronize do
+          @actions[action.id] = action.with(status: :pending) if @actions[action.id]&.status == :applying
+        end
+        raise
+      end
+
+      def reject_action(action)
+        return false unless @mutex.synchronize { action.status == :pending }
+        @on_reject&.call(action)
+        @mutex.synchronize do
+          @actions[action.id] = action.with(status: :rejected)
+        end
+        true
+      end
+    end
+  end
+end

data/lib/ask/agent/extensions/approval_policy.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Ask
+  module Agent
+    module Extensions
+      # Approval policy hook: classifies tool calls as approval-required and
+      # routes them into an {Ask::Agent::ApprovalQueue}.
+      #
+      # Wire it as a +before_tool+ hook on a Session (or enable it with
+      # `Session.new(approval: true)`), and any tool whose class declares
+      # `approval_required true` — or whose name matches the policy's
+      # rule-based lists — is queued for human approval instead of executed.
+      # The agent receives a pending result and continues; the tool runs only
+      # after a human approves it.
+      #
+      # @example
+      #   queue = Ask::Agent::ApprovalQueue.new
+      #   policy = Ask::Agent::Extensions::ApprovalPolicy.new(queue: queue)
+      #   session = Ask::Agent::Session.new(
+      #     model: "gpt-4o",
+      #     tools: [SendEmail],
+      #     hooks: { before_tool: [policy.method(:before_tool_call)] }
+      #   )
+      #
+      #   # Later, when the user decides:
+      #   session.approval_queue.approve_all
+      class ApprovalPolicy
+        # @param queue [Ask::Agent::ApprovalQueue] the queue actions go into.
+        #   The queue owns the user-enabled auto-approval rules; this policy
+        #   only reports each tool's own declaration.
+        # @param require_approval [Array<String, Regexp>, :all, nil] extra
+        #   rule-based classification on top of the tool's own declaration.
+        #   Strings match tool names exactly, Regexps match against the name,
+        #   and :all requires approval for every tool call.
+        # @param tools [Array<Object>, nil] the session's resolved tool
+        #   instances, used to read class-level declarations
+        #   (`approval_required`, `auto_approvable`). When nil, only the
+        #   rule-based lists classify calls.
+        def initialize(queue:, require_approval: nil, tools: nil)
+          @queue = queue
+          @require_approval = require_approval
+          @tools = Array(tools)
+        end
+
+        # Hook entry point — matches the +before_tool+ hook signature.
+        #
+        # @param tool_call [Ask::Agent::ToolCallInfo]
+        # @param _context [Hash]
+        # @return [Hash] {action: :proceed} to run, or
+        #   {action: :pending, action_id:, reason:} to queue for approval
+        def before_tool_call(tool_call, _context)
+          return { action: :proceed } unless approval_required?(tool_call.name)
+
+          auto_approvable = tool_auto_approvable?(tool_call.name)
+          action_id = @queue.submit(
+            tool_call_id: tool_call.id,
+            tool_name: tool_call.name,
+            args: tool_call.arguments,
+            auto_approvable: auto_approvable,
+            message: "Calling \"#{tool_call.name}\" requires approval"
+          )
+
+          { action: :pending, action_id: action_id, reason: "Tool '#{tool_call.name}' requires approval" }
+        end
+
+        private
+
+        def approval_required?(tool_name)
+          return true if @require_approval == :all
+
+          rule_matches?(@require_approval, tool_name) || tool_declares_approval?(tool_name)
+        end
+
+        def rule_matches?(rules, tool_name)
+          Array(rules).any? do |rule|
+            rule == tool_name || (rule.is_a?(Regexp) && rule.match?(tool_name))
+          end
+        end
+
+        def tool_declares_approval?(tool_name)
+          tool = tool_for(tool_name)
+          tool&.respond_to?(:approval_required?) && tool.approval_required?
+        end
+
+        def tool_auto_approvable?(tool_name)
+          tool = tool_for(tool_name)
+          tool&.respond_to?(:auto_approvable?) && tool.auto_approvable?
+        end
+
+        def tool_for(tool_name)
+          @tools.find { |t| t.respond_to?(:name) && t.name == tool_name }
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/session.rb

@@ -22,7 +22,7 @@ module Ask
                      id: nil, system_prompt: nil, parallel_tools: true,
                      reflector: nil, telemetry: true, meta_agent: nil,
                      agent_dir: nil, evaluator: nil, audit_log: nil,
-                     skills_disclosure: true, **chat_options)
+                     skills_disclosure: true, approval: nil, **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -53,6 +53,7 @@ module Ask
         @compactor = compactor ? build_compactor(compactor) : nil
         @hooks = Hooks.new(hooks)
         @audit_log = build_audit_log(audit_log)
+        @approval_queue = build_approval(approval)
 
         @system_context = build_system_context(system_prompt)
         apply_system_context
@@ -88,6 +89,13 @@ module Ask
         end
       end
 
+      # The approval queue backing this session, or nil when the session was
+      # created without approval support. Use it to inspect pending actions
+      # and approve/reject them.
+      #
+      # @return [Ask::Agent::ApprovalQueue, nil]
+      attr_reader :approval_queue
+
       def run(message, tools: nil, reset: true)
         raise "Session deleted" if @deleted
         raise "Session already running" if @running
@@ -336,6 +344,11 @@ module Ask
         nil
       end
 
+      # @return [Boolean] true while at least one async tool is running
+      def pending_tools?
+        @pending_mutex.synchronize { !@pending_tools.empty? }
+      end
+
       # Completes a pending (async) tool call from a background thread.
       #
       # Adds the tool result to the conversation and, when the session is
@@ -411,6 +424,48 @@ module Ask
           Ask::Agent::Extensions::AuditLog.new(self, adapter: config)
         end
 
+      # Build the approval queue + policy when approval is enabled.
+      #
+      # `approval` accepts:
+      #   - true            → queue with defaults
+      #   - a Hash          → { require_approval:, auto_approve: } for the policy
+      #   - an ApprovalQueue → uses it, with policy options from
+      #                        approval[:policy] if given
+      #
+      # When enabled, an ApprovalPolicy hook is prepended to the session's
+      # before_tool hooks so approval-required tools queue instead of running.
+      def build_approval(approval)
+        return nil unless approval
+
+        policy_opts = approval.is_a?(Hash) ? approval : {}
+
+        queue = if approval.is_a?(Ask::Agent::ApprovalQueue)
+          approval
+        elsif policy_opts[:queue].is_a?(Ask::Agent::ApprovalQueue)
+          policy_opts[:queue]
+        else
+          Ask::Agent::ApprovalQueue.new(
+            auto_approve: policy_opts[:auto_approve],
+            on_approve: ->(action) { apply_approved_action(action) },
+            on_reject: ->(action) { reject_pending_action(action) }
+          )
+        end
+
+        policy = Ask::Agent::Extensions::ApprovalPolicy.new(
+          queue: queue,
+          require_approval: policy_opts[:require_approval],
+          tools: @tools
+        )
+
+        # Prepend the approval gate so it runs before user hooks
+        @hooks = Hooks.new(
+          before_tool: [policy.method(:before_tool_call)] + Array(@hooks.instance_variable_get(:@before_tool)),
+          after_tool: @hooks.instance_variable_get(:@after_tool)
+        )
+
+        queue
+      end
+
       def build_chat(model, system_prompt, tools, **chat_options)
         if model.respond_to?(:ask)
           model
@@ -421,6 +476,48 @@ module Ask
         end
       end
 
+      # Execute an approved action's tool call and complete the pending tool,
+      # so the follow-up turn voices the outcome.
+      def apply_approved_action(action)
+        tool = @tools.find { |t| t.name == action.tool_name }
+        if tool
+          result = tool.call(action.args)
+          status = result.respond_to?(:ok?) ? (result.ok? ? "success" : "error") : "success"
+          complete_pending_tool(
+            tool_call_id: action.tool_call_id,
+            result: {
+              tool_name: action.tool_name,
+              message: result.to_s,
+              status: status,
+              is_error: status == "error"
+            }
+          )
+        else
+          complete_pending_tool(
+            tool_call_id: action.tool_call_id,
+            result: {
+              tool_name: action.tool_name,
+              message: "Tool not found: #{action.tool_name}",
+              status: "error",
+              is_error: true
+            }
+          )
+        end
+      end
+
+      # Notify the conversation that an action was rejected by the user.
+      def reject_pending_action(action)
+        complete_pending_tool(
+          tool_call_id: action.tool_call_id,
+          result: {
+            tool_name: action.tool_name,
+            message: "Action '#{action.tool_name}' was rejected by the user.",
+            status: "rejected",
+            is_error: false
+          }
+        )
+      end
+
       def resolve_tools(tools)
         resolved = tools.map do |tool|
           tool.is_a?(Class) ? tool.new : tool

data/lib/ask/agent/tool_executor.rb

@@ -115,6 +115,17 @@ module Ask
           return { tool_name: tool_call.name, message: hook_result[:reason], status: "blocked", is_error: true }
         when :short_circuit
           return { tool_name: tool_call.name, **hook_result[:result], status: "short_circuited" }
+        when :pending
+          # Queued for human approval — the loop hands the turn back with an
+          # interim reply; the action runs later via ApprovalQueue#approve.
+          return {
+            tool_name: tool_call.name,
+            message: hook_result[:reason] || "Pending approval",
+            status: "pending",
+            is_error: false,
+            tool_call_id: tool_call.id,
+            action_id: hook_result[:action_id]
+          }
         end
 
         return aborted_result(tool_call) if abort_controller&.aborted?

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.26.0"
+    VERSION = "0.27.0"
   end
 end

data/lib/ask/agent.rb

@@ -25,6 +25,7 @@ module Ask
       autoload :Permissions, "ask/agent/extensions/permissions"
       autoload :RateLimiter, "ask/agent/extensions/rate_limiter"
       autoload :AuditLog, "ask/agent/extensions/audit_log"
+      autoload :ApprovalPolicy, "ask/agent/extensions/approval_policy"
     end
 
     module Middleware
@@ -257,6 +258,7 @@ require_relative "agent/evaluator"
 require_relative "agent/tool_executor"
 require_relative "agent/compactor"
 require_relative "agent/hooks"
+require_relative "agent/approval_queue"
 require_relative "agent/configuration"
 require_relative "agent/meta_agent"
 require_relative "agent/persistence/base"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -164,6 +164,7 @@ files:
 - exe/askr
 - lib/ask-agent.rb
 - lib/ask/agent.rb
+- lib/ask/agent/approval_queue.rb
 - lib/ask/agent/chat.rb
 - lib/ask/agent/cli.rb
 - lib/ask/agent/compactor.rb
@@ -173,6 +174,7 @@ files:
 - lib/ask/agent/definition.rb
 - lib/ask/agent/evaluator.rb
 - lib/ask/agent/events.rb
+- lib/ask/agent/extensions/approval_policy.rb
 - lib/ask/agent/extensions/audit_log.rb
 - lib/ask/agent/extensions/audit_log/active_record_writer.rb
 - lib/ask/agent/extensions/permissions.rb