ask-agent 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58b285b250efd49063ba2fb5c078ea3107d3ebd583ab33b4c92c07084280a242
-  data.tar.gz: 1d6df4327981ec16e652cedbb864112721db2a6ae1c1c5d7d74ecacfe4a6aa38
+  metadata.gz: e039a90d18224ab29b454dd2094a81628ddf80cc39938419038378182ecbe472
+  data.tar.gz: 8d6d1a8005d2451469a998d36061adea945245beef774876b5b5bc1565f8fd5a
 SHA512:
-  metadata.gz: 1adec012cf31271f1039068e6329c172981d631c221e5d18ce21fe2f19d2449bceac06a4fb4e8845b762c59b263b20ba947cd70463947b389e70f618beda501e
-  data.tar.gz: 84cdadbbf141991d3c294e06ec9f42e689835407bf3a2577d6ce8a9e173bd3eb21030313e0a59b3663f6718bee88b245deab144aaeda440e443ae176877af4cb
+  metadata.gz: 014b65f0247e65970d3d4fa7496744aa7d38f00f2684c53ff02f74ec5c547b6534c906b24dc6594387069e5034b1916e7f4e3a2986c6bf55e42412177ac7a678
+  data.tar.gz: 72f571ba1ffafca8f9e9f181d51891ce9ea315e4ca5ebc15e1bf27557e8c05faf9ed6f3136a0a88a124f6833f096b5bb7d6cc9d7db9b32bc1dc0a27eb6cff1a9

data/CHANGELOG.md

@@ -1,3 +1,40 @@
+## [0.31.0] — 2026-08-06
+
+### Added
+
+- **Permission rules — persisted allow/ask/deny patterns for tool calls.**
+  `Ask::Agent::Policies::PermissionRules` classifies every call before it
+  executes or prompts, so "approve once, remember the pattern" replaces
+  per-call prompting:
+  - DSL in declaration order (first match wins): `allow`, `ask`, `deny`
+    with a tool pattern (String, Symbol, Regexp, or `:all`) and an optional
+    argument pattern (Regexp, substring, or `nil` for any).
+  - Wire in via `Session.new(approval: { rules: rules })`. Rules take
+    precedence over a tool's own `approval_required` / `auto_approvable`
+    declarations: `:deny` blocks, `:allow` proceeds without the queue,
+    `:ask` queues regardless of auto-approvable.
+  - **Dangerous-rule guard**: an unrestricted `:allow` on a code-executing
+    tool (`bash`, `code`, `repl`, or `:all`) is downgraded to `:ask` unless
+    the ruleset is created with `auto_allow_dangerous: true` — "approve
+    once" can't become "approve anything". `dangerous_rules` reports which
+    rules were affected.
+
+## [0.30.1] — 2026-08-06
+
+### Fixed
+
+- **Framework-injected tools are no longer persisted in session metadata.**
+  The built-in `load_skill` tool was saved alongside user tools and could
+  not be auto-instantiated on load (`LoadSkillTool` requires a registry), so
+  the previous 0.30.0 fix skipped it with a broad rescue. Persisted metadata
+  now contains only user-supplied tools (`persisted_tools`); `load_skill` is
+  re-added by `resolve_tools` per session with a proper registry.
+- **`Session.load` no longer swallows tool-restore failures silently.** The
+  safety net now rescues only `NameError` (renamed/removed classes) and
+  `ArgumentError` (constructors with required args), and warns with the
+  tool name instead of failing the whole load — genuine tool bugs surface
+  instead of disappearing.
+
 ## [0.30.0] — 2026-08-06
 
 ### Added

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

@@ -32,13 +32,18 @@ module Ask
         #   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, tools: nil)
+        def initialize(queue:, require_approval: nil, rules: nil, tools: nil)
           @queue = queue
           @require_approval = require_approval
+          @rules = rules
           @tools = Array(tools)
         end
 
@@ -46,12 +51,27 @@ module Ask
         #
         # @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
+        # @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)
 
-          auto_approvable = tool_auto_approvable?(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,
@@ -63,8 +83,6 @@ module Ask
           { 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
 

data/lib/ask/agent/policies/permission_rules.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    module Policies
+      # Persisted, matchable allow/ask/deny patterns for tool calls.
+      #
+      # Rules classify a tool call before it executes or prompts:
+      #
+      #   rules = Ask::Agent::Policies::PermissionRules.new do |r|
+      #     r.allow :bash, /^git (pull|push|status)/
+      #     r.ask   :bash, /^rm -rf/
+      #     r.deny  :write, %r{/\.env(\.local)?$}
+      #     r.ask   :destroy, :all
+      #   end
+      #
+      #   session = Ask::Agent::Session.new(
+      #     model: "gpt-4o",
+      #     approval: { rules: rules }
+      #   )
+      #
+      # Classification is first-match-wins, in declaration order: :allow runs
+      # the tool, :ask queues it for human approval, :deny blocks it. Rules
+      # take precedence over a tool's own `approval_required` / `auto_approvable`
+      # declarations — they are explicit user intent.
+      #
+      # Dangerous-rule guard: an :allow rule for a code-executing tool (bash,
+      # code, repl) whose argument pattern is unrestricted would let the model
+      # run anything without asking. Such rules are downgraded to :ask unless
+      # the ruleset was created with `auto_allow_dangerous: true` — "approve
+      # once, remember the pattern" must not become "approve everything".
+      class PermissionRules
+        # A single rule: tool pattern + optional argument pattern + decision.
+        Rule = Data.define(:tool_pattern, :argument_pattern, :decision) do
+          def matches?(tool_name, arguments)
+            tool_matches?(tool_name) && argument_matches?(arguments)
+          end
+
+          def tool_matches?(tool_name)
+            case tool_pattern
+            when :all then true
+            when Regexp then tool_pattern.match?(tool_name.to_s)
+            else tool_pattern.to_s == tool_name.to_s
+            end
+          end
+
+          def argument_matches?(arguments)
+            return true if argument_pattern.nil?
+
+            text = arguments.is_a?(Hash) ? JSON.generate(arguments) : arguments.to_s
+            case argument_pattern
+            when Regexp then argument_pattern.match?(text)
+            else text.include?(argument_pattern.to_s)
+            end
+          end
+
+          def universal?
+            argument_pattern.nil?
+          end
+        end
+
+        # Tools that execute arbitrary code — an unrestricted :allow rule on
+        # any of these is dangerous.
+        DANGEROUS_TOOLS = %i[bash code repl].freeze
+
+        # @param auto_allow_dangerous [Boolean] keep unrestricted :allow
+        #   rules on code-executing tools (default false — they downgrade to
+        #   :ask)
+        def initialize(auto_allow_dangerous: false, &block)
+          @auto_allow_dangerous = auto_allow_dangerous
+          @rules = []
+          instance_eval(&block) if block
+        end
+
+        # DSL — declare rules in priority order (first match wins).
+        def allow(tool_pattern, argument_pattern = nil)
+          add(:allow, tool_pattern, argument_pattern)
+        end
+
+        def ask(tool_pattern, argument_pattern = nil)
+          add(:ask, tool_pattern, argument_pattern)
+        end
+
+        def deny(tool_pattern, argument_pattern = nil)
+          add(:deny, tool_pattern, argument_pattern)
+        end
+
+        # @return [Array<Rule>] declared rules, in order
+        def rules = @rules.dup
+
+        # Classify a tool call.
+        #
+        # @param tool_name [String]
+        # @param arguments [Hash, String, nil] tool arguments (hash or JSON)
+        # @return [Symbol, nil] :allow, :ask, :deny — or nil when no rule
+        #   matches
+        def classify(tool_name, arguments = nil)
+          rule = @rules.find { |r| r.matches?(tool_name, arguments) }
+          return nil unless rule
+
+          if rule.decision == :allow && dangerous?(rule) && !@auto_allow_dangerous
+            :ask
+          else
+            rule.decision
+          end
+        end
+
+        # @return [Array<Rule>] rules that would allow unrestricted execution
+        #   of a code-executing tool
+        def dangerous_rules
+          @rules.select { |r| dangerous?(r) }
+        end
+
+        private
+
+        def add(decision, tool_pattern, argument_pattern)
+          @rules << Rule.new(tool_pattern, argument_pattern, decision)
+        end
+
+        def dangerous?(rule)
+          return false unless rule.decision == :allow && rule.universal?
+
+          rule.tool_pattern == :all || DANGEROUS_TOOLS.any? { |t| rule.tool_matches?(t) }
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/session.rb

@@ -314,14 +314,16 @@ module Ask
         session = new(
           id: data[:id],
           model: data.dig(:metadata, :model),
-          # Instantiate saved tool classes defensively: tools that cannot be
-          # auto-constructed (e.g. the built-in LoadSkillTool, which needs a
-          # registry) are skipped — resolve_tools re-adds them with a proper
-          # registry. Callers can also pass their own `tools:` after load.
+          # Restore saved user tools by class name. Tools that cannot be
+          # restored — renamed/removed classes (NameError) or constructors
+          # with required args (ArgumentError) — are skipped with a warning
+          # instead of failing the whole load; resolve_tools re-adds the
+          # framework-injected load_skill tool with a proper registry.
           tools: data.dig(:metadata, :tools).to_a.filter_map do |name|
             begin
               name.constantize.new
-            rescue StandardError
+            rescue NameError, ArgumentError => e
+              warn "[ask-agent] Session.load skipped tool '#{name}': #{e.class}: #{e.message}"
               nil
             end
           end,
@@ -553,6 +555,7 @@ module Ask
         policy = Ask::Agent::Policies::ApprovalPolicy.new(
           queue: queue,
           require_approval: policy_opts[:require_approval],
+          rules: policy_opts[:rules],
           tools: @tools
         )
 
@@ -694,6 +697,15 @@ module Ask
         target.instance_variable_set(:@turn_count, data.dig(:metadata, :turn_count) || 0)
       end
 
+      # User-supplied tools only. Framework-injected tools (the built-in
+      # load_skill tool) are re-created by resolve_tools on every session, so
+      # persisting them would leak framework internals into user data — and
+      # they cannot be auto-instantiated on load anyway (LoadSkillTool needs
+      # a registry).
+      def persisted_tools
+        @tools.reject { |t| t.is_a?(Ask::Skills::LoadSkillTool) }
+      end
+
       def persist!
         payload = {
           id: @id,
@@ -707,7 +719,7 @@ module Ask
           },
           metadata: {
             model: @chat.model.respond_to?(:id) ? @chat.model.id : @chat.model,
-            tools: @tools.map { |t| t.class.name },
+            tools: persisted_tools.map { |t| t.class.name },
             max_turns: @max_turns,
             turn_count: @turn_count,
             created_at: @created_at.iso8601,

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.30.0"
+    VERSION = "0.31.0"
   end
 end

data/lib/ask/agent.rb

@@ -35,6 +35,7 @@ module Ask
       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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -189,6 +189,7 @@ files:
 - 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