ask-agent 0.40.29 → 0.41.0

data/lib/ask/agent/session_adapter.rb

@@ -94,6 +94,12 @@ module Ask
           )
         end
         agent.instance_variable_set(:@messages, agent.chat.messages.dup)
+        restore_persisted_approvals(
+          agent,
+          payload[:approvals] || payload["approvals"],
+          payload[:plan_approvals] || payload["plan_approvals"],
+          payload[:session_grants] || payload["session_grants"]
+        )
 
         new(agent: agent, host: host, session_id: session_id, create: false)
       end
@@ -238,10 +244,122 @@ module Ask
       def build_snapshot
         {
           messages: (@agent.messages || []).map(&:to_h),
-          turn_count: @agent.turn_count || 0
+          turn_count: @agent.turn_count || 0,
+          # Durable permission state: JSON-safe v1 queue snapshots when the
+          # agent exposes a queue supporting the shared Permissions API.
+          # Nil when approval is off or unsupported (compatibility fallback
+          # — nothing durable to persist, so nothing to strand). Snapshot
+          # failures raise SessionAdapter::Error with queue context.
+          approvals: self.class.queue_snapshot_for(@agent, :approval_queue),
+          plan_approvals: self.class.queue_snapshot_for(@agent, :plan_queue),
+          session_grants: self.class.grants_snapshot_for(@agent)
         }
       end
 
+      def self.queue_snapshot_for(agent, queue_name)
+        return nil unless agent.respond_to?(queue_name)
+
+        queue = agent.public_send(queue_name)
+        return nil unless queue
+        return nil unless queue.respond_to?(:snapshot)
+
+        begin
+          queue.snapshot
+        rescue StandardError => e
+          raise Error, "Failed to snapshot #{queue_name} queue (#{queue.class}): #{e.class}: #{e.message}"
+        end
+      end
+
+      def self.grants_snapshot_for(agent)
+        return nil unless agent.respond_to?(:session_grants)
+        grants = agent.public_send(:session_grants)
+        grants&.respond_to?(:snapshot) ? grants.snapshot : nil
+      rescue StandardError => e
+        raise Error, "Failed to snapshot session grants (#{grants.class}): #{e.class}: #{e.message}"
+      end
+
+      # Restore persisted queue snapshots into the agent without firing
+      # callbacks or emitting approval-required events. For real Sessions
+      # this delegates to the session's silent restore (which also rebuilds
+      # pending-tool registrations so approve/reject completes exactly
+      # once); for generic agents it restores directly when the surface
+      # allows.
+      #
+      # Compatibility fallback (cannot strand): nil snapshots and empty
+      # pending_actions lists are safe no-ops. Any other unrestorable state
+      # — non-Hash snapshot, missing/non-Array pendings, missing queue or
+      # queue without restore support while pendings exist, a non-empty
+      # target queue, or a restore_pending failure — raises
+      # SessionAdapter::Error (or Ask::Agent::Error from the session
+      # delegate) with queue context instead of silently dropping actions.
+      def self.restore_persisted_approvals(agent, approvals_snapshot, plan_snapshot, grants_snapshot = nil)
+        if agent.respond_to?(:restore_persisted_approvals, true)
+          agent.send(:restore_persisted_approvals, approvals_snapshot, plan_snapshot, grants_snapshot)
+          return
+        end
+
+        { approval_queue: approvals_snapshot, plan_queue: plan_snapshot }.each do |queue_name, snapshot|
+          restore_into_generic_queue(agent, queue_name, snapshot)
+        end
+        return if grants_snapshot.nil?
+
+        unless grants_snapshot.is_a?(Hash)
+          raise Error, "Cannot restore session grants: snapshot must be a Hash, got #{grants_snapshot.class}"
+        end
+        tools = grants_snapshot[:granted_tools] || grants_snapshot["granted_tools"]
+        unless tools.is_a?(Array) && tools.all? { |tool| tool.is_a?(String) && !tool.empty? }
+          raise Error, "Cannot restore session grants: granted_tools must be an Array of non-empty Strings"
+        end
+        return if tools.empty?
+        unless agent.respond_to?(:session_grants)
+          raise Error, "Cannot restore session grants: agent has no session grants surface"
+        end
+
+        grants = agent.public_send(:session_grants)
+        raise Error, "Cannot restore session grants: agent has no grants store" unless grants
+        begin
+          grants.restore_snapshot(grants_snapshot)
+        rescue StandardError => e
+          raise Error, "Cannot restore session grants: #{e.class}: #{e.message}"
+        end
+      end
+
+      def self.restore_into_generic_queue(agent, queue_name, snapshot)
+        return nil if snapshot.nil?
+
+        unless snapshot.is_a?(Hash)
+          raise Error, "Cannot restore #{queue_name} queue: snapshot must be a Hash, got #{snapshot.class}"
+        end
+
+        pendings = snapshot[:pending_actions] || snapshot["pending_actions"]
+        if pendings.nil?
+          raise Error, "Cannot restore #{queue_name} queue: snapshot missing pending_actions"
+        end
+        unless pendings.is_a?(Array)
+          raise Error, "Cannot restore #{queue_name} queue: pending_actions must be an Array, got #{pendings.class}"
+        end
+        return nil if pendings.empty?
+        return nil unless agent.respond_to?(queue_name)
+
+        queue = agent.public_send(queue_name)
+        unless queue
+          raise Error, "Cannot restore #{queue_name} queue: agent has no #{queue_name} queue but snapshot carries #{pendings.size} pending action(s)"
+        end
+        unless queue.respond_to?(:restore_pending) && queue.respond_to?(:pending_actions)
+          raise Error, "Cannot restore #{queue_name} queue: #{queue.class} does not support restore_pending"
+        end
+        if queue.respond_to?(:any_pending?) && queue.any_pending?
+          raise Error, "Cannot restore #{queue_name} queue: target queue already holds pending actions"
+        end
+
+        begin
+          queue.restore_pending(snapshot)
+        rescue StandardError => e
+          raise Error, "Cannot restore #{queue_name} queue: #{e.class}: #{e.message}"
+        end
+        nil
+      end
+
       def self.deserialize_content(content)
         content.is_a?(Array) ? content.map { |block| Ask::Content.from_h(block) } : content
       end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.40.29"
+    VERSION = "0.41.0"
   end
 end

data/lib/ask/agent.rb

@@ -9,6 +9,7 @@ require "ask-llm-providers"
 require "ask-tools"
 require "ask-state-providers"
 require "ask-runtime"
+require "ask/permissions"
 
 module Ask
   module Agent
@@ -29,15 +30,12 @@ module Ask
     # swap them freely (see Ask::Agent::Hooks for the seam).
     #
     # A policy is NOT core machinery. Core mechanisms live on Session — the
-    # approval queue, the :pending result status, and the `approval: true`
-    # option are core; Policies::ApprovalPolicy is the reference
-    # classification policy wired on top of them.
+    # :pending result status and the `approval: true` option are core;
+    # Ask::Permissions::ApprovalPolicy (from the ask-permissions gem) is the
+    # reference classification policy wired on top of them.
     module Policies
-      autoload :Permissions, "ask/agent/policies/permissions"
       autoload :RateLimiter, "ask/agent/policies/rate_limiter"
       autoload :AuditLog, "ask/agent/policies/audit_log"
-      autoload :ApprovalPolicy, "ask/agent/policies/approval_policy"
-      autoload :PermissionRules, "ask/agent/policies/permission_rules"
     end
 
     autoload :ToolCallRepair, "ask/agent/tool_call_repair"
@@ -223,7 +221,6 @@ 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.40.29
+  version: 0.41.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -135,6 +135,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: ask-permissions
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -192,7 +206,6 @@ files:
 - exe/askr
 - lib/ask-agent.rb
 - lib/ask/agent.rb
-- lib/ask/agent/approval_queue.rb
 - lib/ask/agent/artifact_store.rb
 - lib/ask/agent/chat.rb
 - lib/ask/agent/checkpoint_store.rb
@@ -221,11 +234,8 @@ files:
 - lib/ask/agent/output_read.rb
 - lib/ask/agent/persistence/base.rb
 - lib/ask/agent/persistence/in_memory.rb
-- lib/ask/agent/policies/approval_policy.rb
 - lib/ask/agent/policies/audit_log.rb
 - lib/ask/agent/policies/audit_log/active_record_writer.rb
-- lib/ask/agent/policies/permission_rules.rb
-- lib/ask/agent/policies/permissions.rb
 - lib/ask/agent/policies/rate_limiter.rb
 - lib/ask/agent/reflector.rb
 - lib/ask/agent/scheduler.rb

data/lib/ask/agent/approval_queue.rb

@@ -1,249 +0,0 @@
-# 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.
-      # @!attribute [rw] on_approve
-      #   Called with an {Action} when it is approved and applied. The
-      #   session wires this to execute the real tool call; can be replaced
-      #   after construction (e.g. by queue subclasses that also emit events).
-      # @!attribute [rw] on_reject
-      #   Called with an {Action} when it is rejected.
-      # @!attribute [rw] on_submit
-      #   Called with the new {Action} when it is submitted — BEFORE the
-      #   auto-approval drain runs, so subscribers can register the pending
-      #   call before it is applied. The session wires this to register the
-      #   pending tool call, closing the race where an approval lands while
-      #   the executor is still in flight.
-      attr_accessor :on_approve, :on_reject, :on_submit
-
-      def initialize(on_approve: nil, on_reject: nil, auto_approve: nil, on_submit: nil)
-        @on_approve = on_approve
-        @on_reject = on_reject
-        @on_submit = on_submit
-        @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
-
-        # Notify BEFORE the drain: an auto-approvable action is applied
-        # (and possibly completed) inside drain, and listeners need to
-        # observe the submission first.
-        @on_submit&.call(action)
-
-        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/policies/approval_policy.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Agent
-    module Policies
-      # 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::Policies::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 rules [Ask::Agent::Policies::PermissionRules, nil] persisted
-        #   allow/ask/deny patterns. Rules classify first and take precedence
-        #   over tool declarations: :deny blocks, :allow proceeds without the
-        #   queue, :ask queues regardless of auto-approvable.
-        # @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, rules: nil, tools: nil)
-          @queue = queue
-          @require_approval = require_approval
-          @rules = rules
-          @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, {action: :pending,
-        #   action_id:, reason:} to queue for approval, or {action: :block,
-        #   reason:} to refuse
-        def before_tool_call(tool_call, _context)
-          case @rules&.classify(tool_call.name, tool_call.arguments)
-          when :deny
-            return { action: :block, reason: "Denied by permission rules: '#{tool_call.name}'" }
-          when :allow
-            return { action: :proceed }
-          when :ask
-            return queue_for_approval(tool_call, auto_approvable: false)
-          end
-
-          return { action: :proceed } unless approval_required?(tool_call.name)
-
-          queue_for_approval(tool_call, auto_approvable: tool_auto_approvable?(tool_call.name))
-        end
-
-        private
-
-        def queue_for_approval(tool_call, auto_approvable:)
-          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
-
-        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