ask-agent 0.27.1 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1728d64a66438d1ff5ed51490420b7f9f87d806fc8a5bd98317d9c4de44e68e
-  data.tar.gz: 2172947edba0c5a906ebdc01643eaa0adda23d1405d22dcb0dd5a662c71e4944
+  metadata.gz: 11cf486fa2d955d92cc6f8268f30e5a418b6f0567cdfb6fe6eac015a3352c74b
+  data.tar.gz: 5b4990efc0b66de943f6e5c3b7940d31cca6295c54c40fafef485c6004433601
 SHA512:
-  metadata.gz: cb6be0c48b35c3b7e68ba73edc98fbe9209ffcdc58ee2a7524dd12ea0d3202b0d62397f449579d4b8154b97876cfc57da1031eb004a02fb25c61765b11e764bd
-  data.tar.gz: e2d4f5c8fa6808c0d1e73e9d237c56d8e48fb4bc8630b9bf0feb89309bab872a1bca8a42d603030dafadeeb30d203e35e413a533dded5d3a9086e8b8031ef3fc
+  metadata.gz: 3adf87ccd9b0cbb606133cb91b8baf9e24a328f96e4ed8f77266258883b13663762cbd16a3e1e34475ec0b93ab763518c4b661fa675fba37985144c01435a736
+  data.tar.gz: b6093801427cf4c8bc56fd9b6b0bf6f9fd6bc5252ce336731149413984b5f83862e4cfeae2e9705b2517bb73e3063091950293f74cdb32109624965e52ccc760

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [0.29.0] — 2026-08-06
+
+### Added
+
+- **Tool-call repair** — malformed tool calls get one internal LLM round-trip
+  to fix them before execution. When a model emits a call with unparseable
+  arguments or an unknown tool name, the loop asks the model to re-emit it
+  corrected and executes the corrected version instead of burning a turn on
+  the error. Enable with `Session.new(tool_call_repair: true)` (built-in
+  repair prompt) or pass a callable for full control:
+  `Session.new(tool_call_repair: ->(chat, calls, tools) { ... })`.
+  - Corrections are remapped to the original call ids, so tool results stay
+    consistent with the conversation history; the internal repair exchange
+    is stripped from history.
+  - Calls the model cannot correct are dropped (the model saw them in the
+    repair prompt); repair is best-effort — a failing round-trip drops the
+    malformed calls instead of failing the turn.
+  - `Events::ToolCallRepaired` fires with name, id, original and corrected
+    arguments.
+
+## [0.28.0] — 2026-08-06
+
+### Changed (breaking)
+
+- **`Ask::Agent::Extensions` is now `Ask::Agent::Policies`.** The
+  tool-lifecycle policy classes — `ApprovalPolicy`, `Permissions`,
+  `RateLimiter`, `AuditLog` — moved from `lib/ask/agent/extensions/` to
+  `lib/ask/agent/policies/` and are namespaced under `Ask::Agent::Policies`.
+  The folder is now named after its seam (like `middleware`,
+  `stream_transforms`, `persistence`) instead of "extra stuff".
+  `Ask::Agent.load_extensions` → `Ask::Agent.load_policies`.
+  Update references: `Ask::Agent::Extensions::X` → `Ask::Agent::Policies::X`.
+
+  **What this means for the taxonomy:** policies are opt-in, replaceable
+  implementations of the tool-lifecycle hook seam — the agent loop runs
+  without them, and users can swap in their own implementations. Core
+  mechanisms are unchanged and stay 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.
+
+### Added
+
+- **`Ask::Agent.load_policies`** — replaces `load_extensions` (same
+  behavior: eagerly requires every policy in the policies directory).
+
 ## [0.27.1] — 2026-08-06
 
 ### Fixed

data/lib/ask/agent/events.rb

@@ -16,6 +16,9 @@ module Ask
       MessageEnd = Data.define(:tool_calls)
 
       ToolExecutionStart = Data.define(:name, :arguments, :id)
+      # Emitted when a malformed tool call (unparseable arguments or unknown
+      # tool) was repaired by the model before execution.
+      ToolCallRepaired = Data.define(:name, :id, :original_arguments, :corrected_arguments)
       # Emitted when a tool returns Ask::Result.pending (async work started).
       ToolPending = Data.define(:name, :id)
       # Emitted when a pending (async) tool's background work completes.

data/lib/ask/agent/loop.rb

@@ -17,7 +17,7 @@ module Ask
       @max_consecutive_tool_turns = max_consecutive_tool_turns
       end
 
-      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil, persist: nil)
+      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil, persist: nil, tool_call_repair: nil)
         raise MaxTurnsExceeded if @turn_count >= @max_turns
 
         event_emitter.emit(Events::TurnStart.new)
@@ -86,6 +86,10 @@ module Ask
         user_tool_calls = response.tool_calls.reject { |id, _| provider_results.key?(id) }
 
         if user_tool_calls.any?
+          # Repair malformed calls (unparseable arguments, unknown tool
+          # names) with one internal LLM round-trip before executing.
+          user_tool_calls = repair_malformed_calls(user_tool_calls, tools, chat, event_emitter, tool_call_repair)
+
           # Execute user tool calls locally
           # Respect the session's parallel_tools setting: parallel tools run
           # in threads (with the caller's thread-local context inherited);
@@ -162,7 +166,8 @@ module Ask
           hooks: hooks,
           event_emitter: event_emitter,
           session_id: session_id,
-          persist: persist
+          persist: persist,
+          tool_call_repair: tool_call_repair
         )
       end
 
@@ -174,6 +179,43 @@ module Ask
 
       private
 
+      # Repair malformed tool calls before execution. Calls with corrected
+      # versions execute in place of the originals (same ids); calls the
+      # model could not correct are dropped — the model saw them in the
+      # repair prompt. Best-effort: a failing repair round-trip drops the
+      # malformed calls instead of failing the turn.
+      def repair_malformed_calls(user_tool_calls, tools, chat, event_emitter, tool_call_repair)
+        return user_tool_calls if tool_call_repair.nil? || user_tool_calls.empty?
+
+        repairer = if tool_call_repair == true
+          @tool_call_repair ||= ToolCallRepair.new
+        elsif tool_call_repair.respond_to?(:call)
+          ToolCallRepair.new(tool_call_repair)
+        end
+        return user_tool_calls unless repairer
+
+        malformed, _valid = user_tool_calls.partition do |_id, tc|
+          ToolCallRepair.repair_info(tc, tools)
+        end
+        return user_tool_calls if malformed.empty?
+
+        corrections = repairer.call(chat: chat, calls: malformed.to_h, tools: tools)
+
+        corrections.each do |id, corrected|
+          event_emitter.emit(Events::ToolCallRepaired.new(
+            name: corrected.name,
+            id: id,
+            original_arguments: user_tool_calls[id].arguments,
+            corrected_arguments: corrected.arguments
+          ))
+          user_tool_calls[id] = corrected
+        end
+
+        malformed_ids = malformed.map(&:first)
+        user_tool_calls.reject! { |id, _| malformed_ids.include?(id) && !corrections.key?(id) }
+        user_tool_calls
+      end
+
       # Whether the session asked the loop to stop (barge-in). Emitters that
       # don't support aborting (plain stubs) are treated as never aborted.
       def aborted?(event_emitter)

data/lib/ask/agent/{extensions → policies}/approval_policy.rb

@@ -2,7 +2,7 @@
 
 module Ask
   module Agent
-    module Extensions
+    module Policies
       # Approval policy hook: classifies tool calls as approval-required and
       # routes them into an {Ask::Agent::ApprovalQueue}.
       #
@@ -15,7 +15,7 @@ module Ask
       #
       # @example
       #   queue = Ask::Agent::ApprovalQueue.new
-      #   policy = Ask::Agent::Extensions::ApprovalPolicy.new(queue: queue)
+      #   policy = Ask::Agent::Policies::ApprovalPolicy.new(queue: queue)
       #   session = Ask::Agent::Session.new(
       #     model: "gpt-4o",
       #     tools: [SendEmail],

data/lib/ask/agent/{extensions → policies}/audit_log/active_record_writer.rb

@@ -3,7 +3,7 @@ require "time"
 
 module Ask
   module Agent
-    module Extensions
+    module Policies
       class AuditLog
         # ActiveRecord adapter for the audit log.
         # Auto-creates the +ask_audit_logs+ table on first write using

data/lib/ask/agent/{extensions → policies}/audit_log.rb

@@ -5,7 +5,7 @@ require "time"
 
 module Ask
   module Agent
-    module Extensions
+    module Policies
       # Event-driven audit log for agent sessions.
       #
       # Subscribes to all session events and writes them to a configurable
@@ -93,16 +93,16 @@ module Ask
 
           case adapter
           when :active_record
-            require "ask/agent/extensions/audit_log/active_record_writer"
+            require "ask/agent/policies/audit_log/active_record_writer"
             AuditLog::ActiveRecordWriter.new
           when Hash
             resolve(adapter[:adapter] || adapter[:writer])
           when Symbol, String
             # Try to load adapter by convention:
-            # :active_record → ask/agent/extensions/audit_log/active_record_writer
+            # :active_record → ask/agent/policies/audit_log/active_record_writer
             name = adapter.to_s
             begin
-              require "ask/agent/extensions/audit_log/#{name}_writer"
+              require "ask/agent/policies/audit_log/#{name}_writer"
               klass_name = name.split("_").map(&:capitalize).join
               klass = AuditLog.const_get(klass_name)
               klass.new

data/lib/ask/agent/{extensions → policies}/permissions.rb

@@ -2,7 +2,7 @@
 
 module Ask
   module Agent
-    module Extensions
+    module Policies
       class Permissions
         DEFAULT_TOOLS = %i[write edit bash destroy].freeze
 

data/lib/ask/agent/{extensions → policies}/rate_limiter.rb

@@ -2,7 +2,7 @@
 
 module Ask
   module Agent
-    module Extensions
+    module Policies
       class RateLimiter
         def initialize(max_calls_per_minute: 20, max_tool_calls_per_turn: 5)
           @max_calls_per_minute = max_calls_per_minute

data/lib/ask/agent/session.rb

@@ -22,7 +22,8 @@ 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, approval: nil, **chat_options)
+                     skills_disclosure: true, approval: nil,
+                     tool_call_repair: nil, **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -54,6 +55,7 @@ module Ask
         @hooks = Hooks.new(hooks)
         @audit_log = build_audit_log(audit_log)
         @approval_queue = build_approval(approval)
+        @tool_call_repair = tool_call_repair
 
         @system_context = build_system_context(system_prompt)
         apply_system_context
@@ -129,6 +131,7 @@ module Ask
 	            hooks: @hooks,
 	            event_emitter: self,
 	            session_id: @id,
+            tool_call_repair: @tool_call_repair,
 	            persist: @state ? method(:persist!) : nil
 	          )
 
@@ -202,7 +205,8 @@ module Ask
               compactor: @compactor,
               hooks: @hooks,
               event_emitter: self,
-              session_id: @id
+              session_id: @id,
+              tool_call_repair: @tool_call_repair
             )
 
             @total_input_tokens += @loop.last_input_tokens.to_i
@@ -241,7 +245,8 @@ module Ask
               compactor: @compactor,
               hooks: @hooks,
               event_emitter: self,
-              session_id: @id
+              session_id: @id,
+              tool_call_repair: @tool_call_repair
             )
 
             @total_input_tokens += @loop.last_input_tokens.to_i
@@ -421,7 +426,7 @@ module Ask
       def build_audit_log(config)
           config ||= Ask::Agent.configuration.audit_log
           return nil unless config
-          Ask::Agent::Extensions::AuditLog.new(self, adapter: config)
+          Ask::Agent::Policies::AuditLog.new(self, adapter: config)
         end
 
       # Build the approval queue + policy when approval is enabled.
@@ -451,7 +456,7 @@ module Ask
           )
         end
 
-        policy = Ask::Agent::Extensions::ApprovalPolicy.new(
+        policy = Ask::Agent::Policies::ApprovalPolicy.new(
           queue: queue,
           require_approval: policy_opts[:require_approval],
           tools: @tools

data/lib/ask/agent/tool_call_repair.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    # Repairs malformed tool calls before they execute.
+    #
+    # When a model emits a tool call with unparseable arguments or an unknown
+    # tool name, execution currently fails and the model burns a turn seeing
+    # the error. Repair intercepts those calls before execution, asks the
+    # model to re-emit them corrected (one internal LLM round-trip), and
+    # executes the corrected versions — remapped to the original call ids so
+    # tool results stay consistent with the conversation history.
+    #
+    # Enable with `Session.new(tool_call_repair: true)` for the built-in
+    # repair prompt, or pass a callable for full control:
+    #
+    #   Session.new(tool_call_repair: ->(chat, calls, tools) {
+    #     { calls.keys.first => ToolCallInfo.new(
+    #         id: calls.keys.first, name: "bash", arguments: "{}"
+    #       ) }
+    #   })
+    #
+    # The callable receives the chat, the malformed calls hash (id =>
+    # ToolCallInfo), and the available tools; it returns a hash of
+    # corrections keyed by the ORIGINAL call ids. Calls without a correction
+    # are dropped — the model saw them in the prompt and declined to fix
+    # them.
+    class ToolCallRepair
+      # @param tool_call [ToolCallInfo]
+      # @param tools [Array<Object>]
+      # @return [String, nil] why the call is repairable, or nil when it is
+      #   well-formed and executable
+      def self.repair_info(tool_call, tools)
+        unless tools.any? { |t| t.respond_to?(:name) && t.name == tool_call.name }
+          return "unknown tool '#{tool_call.name}'"
+        end
+
+        args = tool_call.arguments
+        return nil if args.is_a?(Hash)
+
+        parsed = JSON.parse(args.to_s)
+        return nil if parsed.is_a?(Hash)
+
+        "arguments must be a JSON object, got #{parsed.class}"
+      rescue JSON::ParserError => e
+        "arguments are not valid JSON: #{e.message}"
+      end
+
+      # @param callable [Proc, nil] custom repair function; nil uses the
+      #   built-in repair prompt
+      def initialize(callable = nil)
+        @callable = callable
+      end
+
+      # Ask the model to correct the malformed calls.
+      #
+      # @param chat [Ask::Agent::Chat] the session chat (history is restored
+      #   after the internal round-trip)
+      # @param calls [Hash{String => ToolCallInfo}] malformed calls by id
+      # @param tools [Array<Object>]
+      # @return [Hash{String => ToolCallInfo}] corrections keyed by the
+      #   original call ids
+      def call(chat:, calls:, tools:)
+        if @callable
+          normalize(@callable.call(chat, calls, tools))
+        else
+          built_in(chat, calls, tools)
+        end
+      end
+
+      private
+
+      def built_in(chat, calls, tools)
+        size = chat.messages.size
+        response = chat.ask(repair_prompt(calls, tools))
+        # Remove the internal repair exchange from the conversation so the
+        # history stays clean and the model never sees it.
+        chat.messages.slice!(size..)
+
+        corrections = {}
+        response.tool_calls.values.each_with_index do |tc, index|
+          original_id = calls.keys[index]
+          break unless original_id
+
+          corrections[original_id] = ToolCallInfo.new(
+            id: original_id, name: tc.name, arguments: tc.arguments
+          )
+        end
+        corrections
+      rescue StandardError
+        # Repair is best-effort: on any failure, drop the malformed calls
+        # rather than failing the turn. Restore history either way.
+        chat.messages.slice!(size..) rescue nil
+        {}
+      end
+
+      # Normalize a custom callable's result to the corrections contract
+      # (original id => ToolCallInfo), dropping anything malformed.
+      def normalize(result)
+        return {} unless result.respond_to?(:each)
+
+        result.each_with_object({}) do |(id, tc), acc|
+          next unless tc.respond_to?(:name)
+
+          acc[id] = ToolCallInfo.new(id: id, name: tc.name, arguments: tc.arguments)
+        end
+      end
+
+      def repair_prompt(calls, tools)
+        lines = calls.map.with_index do |(id, tc), i|
+          reason = self.class.repair_info(tc, tools) || "invalid"
+          "#{i + 1}. call id \"#{id}\", tool \"#{tc.name}\", " \
+            "arguments: #{tc.arguments.inspect} — #{reason}"
+        end
+        tool_list = tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s }.join(", ")
+
+        <<~PROMPT.strip
+          Some tool calls from your last message were invalid and could not be executed:
+          #{lines.join("\n")}
+
+          Available tools: #{tool_list.empty? ? "(none)" : tool_list}
+
+          Reply by calling the tools again with corrected arguments, in the same order as listed above. Call ONLY the tools listed above that you can correct; if a tool truly does not exist or cannot be corrected, do not call it.
+        PROMPT
+      end
+    end
+  end
+end

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.27.1"
+    VERSION = "0.29.0"
   end
 end

data/lib/ask/agent.rb

@@ -21,13 +21,24 @@ module Ask
 
     class UnknownAgent < Error; end
 
-    module Extensions
-      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"
+    # Policies are opt-in, replaceable implementations of the tool-lifecycle
+    # hook seam (before_tool / after_tool). The agent loop runs without them
+    # and their semantics are unchanged by their absence; users compose and
+    # 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.
+    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"
     end
 
+    autoload :ToolCallRepair, "ask/agent/tool_call_repair"
+
     module Middleware
       autoload :Base, "ask/agent/middleware/base"
       autoload :Pipeline, "ask/agent/middleware/pipeline"
@@ -236,8 +247,8 @@ module Ask
       yield configuration
     end
 
-    def self.load_extensions
-      Dir[File.expand_path("agent/extensions/*.rb", __dir__)].each { |f| require f }
+    def self.load_policies
+      Dir[File.expand_path("agent/policies/*.rb", __dir__)].each { |f| require f }
     rescue Errno::ENOENT
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.29.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -174,11 +174,6 @@ 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
-- lib/ask/agent/extensions/rate_limiter.rb
 - lib/ask/agent/hooks.rb
 - lib/ask/agent/loop.rb
 - lib/ask/agent/meta_agent.rb
@@ -190,6 +185,11 @@ files:
 - lib/ask/agent/middleware/retry_on_failure.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/permissions.rb
+- lib/ask/agent/policies/rate_limiter.rb
 - lib/ask/agent/reflector.rb
 - lib/ask/agent/scheduler.rb
 - lib/ask/agent/session.rb
@@ -204,6 +204,7 @@ files:
 - lib/ask/agent/telemetry.rb
 - lib/ask/agent/test.rb
 - lib/ask/agent/tool_abort_controller.rb
+- lib/ask/agent/tool_call_repair.rb
 - lib/ask/agent/tool_executor.rb
 - lib/ask/agent/version.rb
 homepage: https://github.com/ask-rb/ask-agent