86: Add default limit for tools completions

Gemfile

@@ -13,6 +13,7 @@ group :development do
   gem 'bundler', '>= 2.0'
   gem 'codecov'
   gem 'dotenv'
+  gem 'faker'
   gem 'ferrum'
   gem 'irb'
   gem 'nokogiri'

docs/guides/tools.md

@@ -196,6 +196,44 @@ Proper error handling within your `execute` method is crucial.
 
 See the [Error Handling Guide]({% link guides/error-handling.md %}#handling-errors-within-tools) for more discussion.
 
+## Maximum Tool Completion Limiting
+
+When including tools it is important to consider if the response could trigger unintended recursive calls to the provider. RubyLLM provides built-in protection by providing a default limit of 25, which can be overridden or turned off entirely.
+
+This can be performed on a per chat basis or provided in the global configuration.
+
+```ruby
+# Set a maximum number of tool completions per instantiated chat object
+chat = RubyLLM.chat.with_max_tool_completions(5)
+chat.ask "Question that triggers tools loop"
+# => `execute_tool': Tool completions limit reached: 5 (RubyLLM::ToolCallCompletionsReachedError)
+```
+
+If you wish to remove this safe-guard you can set the max_tool_completions to `nil`.
+```ruby
+chat = RubyLLM.chat.with_max_tool_completions(nil)
+chat.ask "Question that triggers tools loop"
+# Loops until you've used all your credit...
+```
+
+### Global Configuration
+
+You can set a default maximum tool completion limit for all chats through the global configuration:
+
+```ruby
+RubyLLM.configure do |config|
+  # Default is 25 calls per conversation
+  config.max_tool_completions = 10  # Set a more conservative limit
+end
+```
+
+This setting can still be overridden per-chat when needed:
+
+```ruby
+# Override the global setting for this specific chat
+chat = RubyLLM.chat.with_max_tool_completions(5)
+```
+
 ## Security Considerations
 
 {: .warning }
@@ -204,6 +242,7 @@ Treat any arguments passed to your `execute` method as potentially untrusted use
 *   **NEVER** use methods like `eval`, `system`, `send`, or direct SQL interpolation with raw arguments from the AI.
 *   **Validate and Sanitize:** Always validate parameter types, ranges, formats, and allowed values. Sanitize strings to prevent injection attacks if they are used in database queries or system commands (though ideally, avoid direct system commands).
 *   **Principle of Least Privilege:** Ensure the code within `execute` only has access to the resources it absolutely needs.
+*   **Cost-based Denial of Service:** Ensure protection against malicious input or usage, particularly when used in conjunction with tool completions if you remove the default limit
 
 ## Next Steps
 

lib/ruby_llm/active_record/acts_as.rb

@@ -103,6 +103,11 @@ def with_tools(...)
         self
       end
 
+      def with_max_tool_completions(...)
+        to_llm.with_max_tool_completions(...)
+        self
+      end
+
       def with_model(...)
         to_llm.with_model(...)
         self

lib/ruby_llm/chat.rb

@@ -11,7 +11,7 @@ module RubyLLM
   class Chat # rubocop:disable Metrics/ClassLength
     include Enumerable
 
-    attr_reader :model, :messages, :tools
+    attr_reader :model, :messages, :tools, :number_of_tool_completions
 
     def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil) # rubocop:disable Metrics/MethodLength
       if assume_model_exists && !provider
@@ -29,9 +29,13 @@ def initialize(model: nil, provider: nil, assume_model_exists: false, context: n
         new_message: nil,
         end_message: nil
       }
+      @max_tool_completions = config.max_tool_completions
+      @number_of_tool_completions = 0
     end
 
     def ask(message = nil, with: {}, &)
+      @number_of_tool_completions = 0
+
       add_message role: :user, content: Content.new(message, with)
       complete(&)
     end
@@ -60,6 +64,11 @@ def with_tools(*tools)
       self
     end
 
+    def with_max_tool_completions(max_tool_completions)
+      @max_tool_completions = max_tool_completions
+      self
+    end
+
     def with_model(model_id, provider: nil, assume_exists: false)
       @model, @provider = Models.resolve(model_id, provider:, assume_exists:)
       self
@@ -112,14 +121,19 @@ def add_message(message_or_attributes)
 
     private
 
-    def handle_tool_calls(response, &)
+    def handle_tool_calls(response, &) # rubocop:disable Metrics/MethodLength
       response.tool_calls.each_value do |tool_call|
         @on[:new_message]&.call
         result = execute_tool tool_call
         message = add_tool_result tool_call.id, result
         @on[:end_message]&.call(message)
       end
 
+      if max_tool_completions_reached?
+        raise ToolCallCompletionsLimitReachedError, "Tool completions limit reached: #{@max_tool_completions}"
+      end
+
+      @number_of_tool_completions += 1
       complete(&)
     end
 
@@ -136,5 +150,11 @@ def add_tool_result(tool_use_id, result)
         tool_call_id: tool_use_id
       )
     end
+
+    def max_tool_completions_reached?
+      return false unless @max_tool_completions
+
+      @number_of_tool_completions >= @max_tool_completions
+    end
   end
 end

lib/ruby_llm/configuration.rb

@@ -22,6 +22,8 @@ class Configuration
                   :bedrock_session_token,
                   :openrouter_api_key,
                   :ollama_api_base,
+                  # Default tool configuration
+                  :max_tool_completions,
                   # Default models
                   :default_model,
                   :default_embedding_model,
@@ -45,6 +47,7 @@ def initialize
       @default_model = 'gpt-4.1-nano'
       @default_embedding_model = 'text-embedding-3-small'
       @default_image_model = 'dall-e-3'
+      @max_tool_completions = 25
     end
 
     def inspect # rubocop:disable Metrics/MethodLength

lib/ruby_llm/error.rb

@@ -24,6 +24,7 @@ class ConfigurationError < StandardError; end
   class InvalidRoleError < StandardError; end
   class ModelNotFoundError < StandardError; end
   class UnsupportedFunctionsError < StandardError; end
+  class ToolCallCompletionsLimitReachedError < StandardError; end
 
   # Error classes for different HTTP status codes
   class BadRequestError < Error; end