rails_console_ai 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89e0f9e402a40af4755fe61d2029f10a90c487c1d957e007032dcdd1f54a1c82
-  data.tar.gz: 7e68825010aed2bd0f7a07cdcd68a39d54edec2616913ab14c9a10aa972e6d4f
+  metadata.gz: db0c0b3b95cc349906845d4058e1eadc6be4ab67e25f32a4b8e4262e61340a87
+  data.tar.gz: 0ba79ae87d8975193b2b6033279dc41a8841cf71e7f015ce8f36dafa6d62d463
 SHA512:
-  metadata.gz: f0efcfa92b22f8cd4df14a643904aba9c0e3c05ac7873de6a303f72fd6cdd4df5c457cf1fdcafb120a02784c7247663e48141500f69214ac5bbfafa945ec9ce0
-  data.tar.gz: 2aed178645529500d0b1d72772e19307d4b42de2a0db586f928a46df2a6503d78f3693cde4222006ad0e4227ea840b4bd510a6ef5631e9395466cf9035db679a
+  metadata.gz: 615da46e5aa24149783309d69a3b739db1170459c1bf6d929c8ecfc875fbc0654117a7c5d15057aaf7d421660afa9959192f4112b25e722e5e224ce3de768fb0
+  data.tar.gz: cf807c3dfc0fae08a79013606c5e00383bc26994461c02e4135f8efb495540a0f677bff62eae01c2f396e9ce2de8ede7c82a95415b69831425447aa93361dbdb

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.26.0]
+
+- Add sub-agent support
+- Add integration tests
+- Increase max conversation rounds
+- Fix sub-agent model resolution
+- Improve plan step failure handling
+
 ## [0.25.0]
 
 - Expand truncation limits

data/README.md

@@ -105,8 +105,69 @@ Say "think harder" in any query to auto-upgrade to the thinking model for that s
 - **History compaction** — `/compact` summarizes long conversations to reduce cost and latency
 - **Output trimming** — older execution outputs are automatically replaced with references; the LLM can recall them on demand via `recall_output`, and you can `/expand <id>` to see them
 - **Debug mode** — `/debug` shows context breakdown, token counts, and per-call cost estimates before and after each LLM call
+- **Sub-agents** — delegate multi-step investigations to a separate LLM context that returns only a concise summary, keeping the main conversation lean
 - **Safe mode** — configurable guards that block side effects (DB writes, HTTP mutations, email delivery) during AI code execution
 
+## Sub-Agents
+
+Sub-agents solve the context bloat problem. When the AI needs to investigate something (find a user's shard, explore model relationships, search code), those intermediate tool calls can inflate the main conversation to 90K+ tokens, causing the LLM to cut corners. Sub-agents fork the investigation into a separate LLM conversation and return only a concise summary.
+
+The AI decides when to use sub-agents via the `delegate_task` tool. It can target a custom agent by name or use a general-purpose investigation.
+
+### Custom Agents
+
+Define agents as markdown files in `.rails_console_ai/agents/`:
+
+```markdown
+---
+name: Find shard
+description: Given a user ID, determines which database shard they are on
+max_rounds: 5
+tools:
+  - execute_code
+  - recall_memory
+---
+
+You are a shard finder for a sharded Rails application.
+
+Steps:
+1. Find the user: User.find(id)
+2. Check user.shard
+3. Report: "User {username} (ID {id}) is on shard {shard}."
+```
+
+**Frontmatter fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Agent name (shown in system prompt, used with `delegate_task`) |
+| `description` | yes | One-line description of what this agent does |
+| `max_rounds` | no | Max tool-use rounds (default: `sub_agent_max_rounds` config, default 15) |
+| `model` | no | Model override (e.g. use Haiku for simple lookups) |
+| `tools` | no | Array of tool names to include (default: all sub-agent tools) |
+
+The markdown body becomes additional system prompt instructions for the sub-agent.
+
+### How It Works
+
+1. Agent summaries appear in the AI's system prompt under `## Agents`
+2. The AI calls `delegate_task(task: "find user 56653's shard", agent: "Find shard")`
+3. A sub-agent spins up with its own context, tools, and provider
+4. It runs the investigation (up to `max_rounds` tool calls)
+5. The main conversation receives only: `"Sub-agent result: User 56653 is on shard 5."`
+
+Sub-agents have access to read-only memory tools (`recall_memory`, `recall_memories`), code execution (`execute_code`), and all schema/code introspection tools. They cannot ask the user questions, write memories, or spawn further sub-agents.
+
+### Configuration
+
+```ruby
+RailsConsoleAi.configure do |config|
+  config.sub_agent_max_rounds = 15         # default max rounds per sub-agent
+  config.sub_agent_model = nil             # nil = same model as main conversation
+  # config.sub_agent_model = 'claude-haiku-4-5-20251001'  # use a cheaper model
+end
+```
+
 ## Safety Guards
 
 Safety guards prevent AI-generated code from causing side effects. When a guard blocks an operation, the user is prompted to re-run with safe mode disabled.

data/lib/rails_console_ai/agent_loader.rb

@@ -0,0 +1,126 @@
+require 'yaml'
+
+module RailsConsoleAi
+  class AgentLoader
+    AGENTS_DIR = 'agents'
+    BUILTIN_DIR = File.expand_path('../agents', __FILE__)
+
+    def initialize(storage = nil)
+      @storage = storage || RailsConsoleAi.storage
+    end
+
+    def load_all_agents
+      agents = load_builtin_agents
+      app_agents = load_app_agents
+      # App-specific agents override built-ins with the same name
+      app_names = app_agents.map { |a| a['name'].to_s.downcase }.to_set
+      agents.reject! { |a| app_names.include?(a['name'].to_s.downcase) }
+      agents.concat(app_agents)
+      agents
+    rescue => e
+      RailsConsoleAi.logger.warn("RailsConsoleAi: failed to load agents: #{e.message}")
+      []
+    end
+
+    def agent_summaries
+      agents = load_all_agents
+      return nil if agents.empty?
+
+      agents.map { |a|
+        "- **#{a['name']}**: #{a['description']}"
+      }
+    end
+
+    def find_agent(name)
+      agents = load_all_agents
+      agents.find { |a| a['name'].to_s.downcase == name.to_s.downcase }
+    end
+
+    def save_agent(name:, description:, body:, max_rounds: nil, model: nil, tools: nil)
+      key = agent_key(name)
+      existing = find_agent(name)
+
+      frontmatter = {
+        'name' => name,
+        'description' => description
+      }
+      frontmatter['max_rounds'] = max_rounds if max_rounds
+      frontmatter['model'] = model if model
+      frontmatter['tools'] = Array(tools) if tools && !tools.empty?
+
+      content = "---\n#{YAML.dump(frontmatter).sub("---\n", '').strip}\n---\n\n#{body}\n"
+      @storage.write(key, content)
+
+      path = @storage.respond_to?(:root_path) ? File.join(@storage.root_path, key) : key
+      if existing
+        "Agent updated: \"#{name}\" (#{path})"
+      else
+        "Agent created: \"#{name}\" (#{path})"
+      end
+    rescue Storage::StorageError => e
+      "FAILED to save agent (#{e.message})."
+    end
+
+    def delete_agent(name:)
+      key = agent_key(name)
+      unless @storage.exists?(key)
+        found = load_all_agents.find { |a| a['name'].to_s.downcase == name.to_s.downcase }
+        return "No agent found: \"#{name}\"" unless found
+        key = agent_key(found['name'])
+      end
+
+      agent = load_agent(key)
+      @storage.delete(key)
+      "Agent deleted: \"#{agent ? agent['name'] : name}\""
+    rescue Storage::StorageError => e
+      "FAILED to delete agent (#{e.message})."
+    end
+
+    private
+
+    def load_builtin_agents
+      return [] unless File.directory?(BUILTIN_DIR)
+      Dir.glob(File.join(BUILTIN_DIR, '*.md')).sort.filter_map do |path|
+        content = File.read(path)
+        agent = parse_agent(content)
+        agent['builtin'] = true if agent
+        agent
+      end
+    rescue => e
+      RailsConsoleAi.logger.debug("RailsConsoleAi: failed to load built-in agents: #{e.message}")
+      []
+    end
+
+    def load_app_agents
+      keys = @storage.list("#{AGENTS_DIR}/*.md")
+      keys.filter_map { |key| load_agent(key) }
+    rescue => e
+      []
+    end
+
+    def agent_key(name)
+      slug = name.downcase.strip
+        .gsub(/[^a-z0-9\s-]/, '')
+        .gsub(/[\s]+/, '-')
+        .gsub(/-+/, '-')
+        .sub(/^-/, '').sub(/-$/, '')
+      "#{AGENTS_DIR}/#{slug}.md"
+    end
+
+    def load_agent(key)
+      content = @storage.read(key)
+      return nil if content.nil? || content.strip.empty?
+      parse_agent(content)
+    rescue => e
+      RailsConsoleAi.logger.warn("RailsConsoleAi: failed to load agent #{key}: #{e.message}")
+      nil
+    end
+
+    def parse_agent(content)
+      return nil unless content =~ /\A---\s*\n(.*?\n)---\s*\n(.*)/m
+      frontmatter = YAML.safe_load($1, permitted_classes: [Time, Date]) || {}
+      body = $2.strip
+      frontmatter.merge('body' => body)
+    end
+  end
+end

data/lib/rails_console_ai/agents/explore-data.md

@@ -0,0 +1,24 @@
+---
+name: Explore data
+description: Run queries to investigate records, follow associations, and gather specific data
+max_rounds: 20
+---
+
+You are a data investigator for a Rails application. Your job is to run queries, check
+records, follow associations, and gather specific data points.
+
+Strategy:
+1. Use describe_model to understand the model's columns and associations before querying
+2. Use execute_code to run ActiveRecord queries
+3. Follow associations to find related data (e.g., user -> booking_pages -> booking_requests)
+4. Use model methods to get computed values — NEVER fabricate URLs, tokens, or derived data manually
+
+Rules:
+- Always use describe_model before querying a model you haven't seen yet.
+- Prefer ActiveRecord over raw SQL.
+- When you find a model has methods that return what you need (check with
+  `.methods.grep(/pattern/)`), USE those methods instead of constructing values yourself.
+- Include specific IDs, values, and counts in your findings.
+
+End with a concise, factual summary of what you found. Include specific record IDs, values,
+and relationships. Keep your summary under 300 words.

data/lib/rails_console_ai/agents/investigate-code.md

@@ -0,0 +1,23 @@
+---
+name: Investigate code
+description: Search and read source code to understand how a feature, pattern, or method works
+max_rounds: 20
+---
+
+You are a code investigator for a Rails application. Your job is to search the codebase,
+read relevant files, and understand how a specific feature or pattern works.
+
+Strategy:
+1. Start with search_code to find where the relevant code lives
+2. Use read_file to examine the key files (read specific sections, not entire files)
+3. Follow the chain: find the method, check what it calls, trace the data flow
+4. Use describe_model if database models are involved
+
+Rules:
+- Be thorough but efficient. Search first, then read specific files.
+- If a search returns too many results, narrow it with a more specific query or directory.
+- Look at actual method implementations, not just where things are called.
+- Note file paths and line numbers in your findings.
+
+End with a concise summary of your findings: key files, classes, methods, and how they
+connect. Keep your summary under 500 words.

data/lib/rails_console_ai/channel/console.rb

@@ -207,6 +207,7 @@ module RailsConsoleAi
           break if input.nil?
 
           input = input.strip
+          input = input.force_encoding('UTF-8') if input.encoding == Encoding::ASCII_8BIT
           break if input.downcase == 'exit' || input.downcase == 'quit'
           next if input.empty?
 

data/lib/rails_console_ai/channel/sub_agent.rb

@@ -0,0 +1,84 @@
+require 'rails_console_ai/channel/base'
+
+module RailsConsoleAi
+  module Channel
+    class SubAgent < Base
+      def initialize(parent_channel:, task_label: nil)
+        @parent = parent_channel
+        @label = task_label
+      end
+
+      def display(text)
+        # Swallowed — sub-agent final text is returned as tool result, not displayed
+      end
+
+      def display_thinking(text)
+        @parent.display_thinking(text)
+      end
+
+      def display_status(text)
+        @parent.display_status(text)
+      end
+
+      def display_warning(text)
+        @parent.display_warning(text)
+      end
+
+      def display_error(text)
+        @parent.display_error(text)
+      end
+
+      def display_tool_call(text)
+        @parent.display_tool_call(text)
+      end
+
+      def display_code(code)
+        # Swallowed — sub-agent auto-executes, no need to show code
+      end
+
+      def display_result_output(output)
+        @parent.display_result_output(output)
+      end
+
+      def display_result(result)
+        # Swallowed — sub-agent return values aren't useful to show
+      end
+
+      def prompt(text)
+        '(sub-agent cannot ask user)'
+      end
+
+      def confirm(text)
+        'y'
+      end
+
+      def user_identity
+        @parent.user_identity
+      end
+
+      def mode
+        'sub_agent'
+      end
+
+      def cancelled?
+        @parent.cancelled?
+      end
+
+      def supports_danger?
+        false  # Sub-agents must never silently bypass safety guards
+      end
+
+      def supports_editing?
+        false
+      end
+
+      def wrap_llm_call(&block)
+        yield
+      end
+
+      def system_instructions
+        nil
+      end
+    end
+  end
+end

data/lib/rails_console_ai/configuration.rb

@@ -31,7 +31,9 @@ module RailsConsoleAi
                   :code_search_paths,
                   :channels,
                   :bypass_guards_for_methods,
-                  :user_extra_info
+                  :user_extra_info,
+                  :sub_agent_max_rounds,
+                  :sub_agent_model
 
     def initialize
       @provider     = :anthropic
@@ -64,6 +66,8 @@ module RailsConsoleAi
       @channels = {}
       @bypass_guards_for_methods = []
       @user_extra_info = {}
+      @sub_agent_max_rounds = 15
+      @sub_agent_model = nil
     end
 
     def resolve_user_extra_info(username)

data/lib/rails_console_ai/context_builder.rb

@@ -20,6 +20,7 @@ module RailsConsoleAi
       parts << guide_context
       parts << trusted_methods_context
       parts << skills_context
+      parts << agents_context
       parts << user_extra_info_context
       parts << pinned_memory_context
       parts << memory_context
@@ -93,6 +94,14 @@ module RailsConsoleAi
           a new skill with a step-by-step recipe. Skills are procedures (how to do X); memories
           are facts (what you learned about X). Do NOT use save_memory when asked to create a skill.
 
+        You have a delegate_task tool to spawn sub-agents for investigation tasks:
+        - Use delegate_task when a task requires multiple tool calls to investigate
+          (e.g., finding a user's shard, exploring how a feature works in the code,
+          gathering data across multiple models).
+        - The sub-agent runs in a separate context and returns only a concise summary.
+        - This keeps your conversation context small and efficient.
+        - If a custom agent is available for the task (see Agents section), specify it by name.
+
         RULES:
         - Give ONE concise answer. Do not offer multiple alternatives or variations.
         - For multi-step tasks, use execute_plan to break the work into small, clear steps.
@@ -145,6 +154,19 @@ module RailsConsoleAi
       nil
     end
 
+    def agents_context
+      require 'rails_console_ai/agent_loader'
+      summaries = RailsConsoleAi::AgentLoader.new.agent_summaries
+      return nil if summaries.nil? || summaries.empty?
+
+      lines = ["## Agents (use delegate_task tool to invoke)"]
+      lines.concat(summaries)
+      lines.join("\n")
+    rescue => e
+      RailsConsoleAi.logger.debug("RailsConsoleAi: agents context failed: #{e.message}")
+      nil
+    end
+
     def user_extra_info_context
       info = @config.resolve_user_extra_info(@user_name)
       return nil if info.nil? || info.strip.empty?

data/lib/rails_console_ai/conversation_engine.rb

@@ -249,7 +249,7 @@ module RailsConsoleAi
       output_id = @executor.store_output(result_str)
       if result_str.length > LARGE_OUTPUT_THRESHOLD
         preview = result_str[0, LARGE_OUTPUT_PREVIEW_CHARS]
-        context_msg += "\n#{preview}\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{result_str.length} chars — use recall_output tool with id #{output_id} to retrieve the full output]"
+        context_msg += "\n#{preview}\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{result_str.length} chars — use explore_output with output_id=#{output_id} for focused queries, or recall_output to expand in place]"
       elsif !output_parts.empty?
         context_msg += "\n#{result_str}"
       end
@@ -332,7 +332,7 @@ module RailsConsoleAi
             context_msg = "Code was executed (safety override). "
             if result_str.length > LARGE_OUTPUT_THRESHOLD
               context_msg += result_str[0, LARGE_OUTPUT_PREVIEW_CHARS]
-              context_msg += "\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{result_str.length} chars — use recall_output tool with id #{output_id} to retrieve the full output]"
+              context_msg += "\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{result_str.length} chars — use explore_output with output_id=#{output_id} for focused queries, or recall_output to expand in place]"
             else
               context_msg += result_str
             end
@@ -360,7 +360,7 @@ module RailsConsoleAi
           context_msg = "Code was executed. "
           if result_str.length > LARGE_OUTPUT_THRESHOLD
             context_msg += result_str[0, LARGE_OUTPUT_PREVIEW_CHARS]
-            context_msg += "\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{result_str.length} chars — use recall_output tool with id #{output_id} to retrieve the full output]"
+            context_msg += "\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{result_str.length} chars — use explore_output with output_id=#{output_id} for focused queries, or recall_output to expand in place]"
           else
             context_msg += result_str
           end
@@ -882,6 +882,17 @@ module RailsConsoleAi
             @channel.display_status("     #{preview}#{cached_tag}")
           end
 
+          # Aggregate sub-agent token usage into parent's cost tracking
+          if tc[:name] == 'delegate_task' && tools.last_sub_agent_usage
+            sa = tools.last_sub_agent_usage
+            @total_input_tokens += sa[:input] || 0
+            @total_output_tokens += sa[:output] || 0
+            if sa[:model]
+              @token_usage[sa[:model]][:input] += sa[:input] || 0
+              @token_usage[sa[:model]][:output] += sa[:output] || 0
+            end
+          end
+
           if RailsConsoleAi.configuration.debug
             $stderr.puts "\e[35m[debug] tool result (#{tool_result.to_s.length} chars)\e[0m"
           end
@@ -892,7 +903,7 @@ module RailsConsoleAi
           tool_msg[:output_id] = output_id
           if full_text.length > LARGE_OUTPUT_THRESHOLD
             truncated = full_text[0, LARGE_OUTPUT_PREVIEW_CHARS]
-            truncated += "\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{full_text.length} chars — use recall_output tool with id #{output_id} to retrieve the full output]"
+            truncated += "\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{full_text.length} chars — use explore_output with output_id=#{output_id} for focused queries, or recall_output to expand in place]"
             tool_msg = provider.format_tool_result(tc[:id], truncated)
             tool_msg[:output_id] = output_id
           end
@@ -1030,9 +1041,18 @@ module RailsConsoleAi
       when 'save_skill'     then "(\"#{args['name']}\")"
       when 'delete_skill'   then "(\"#{args['name']}\")"
       when 'recall_output'   then "(#{args['id']})"
+      when 'explore_output'
+        task_preview = args['task'].to_s[0, 80]
+        task_preview += '...' if args['task'].to_s.length > 80
+        "(id: #{args['output_id']}, \"#{task_preview}\")"
       when 'execute_plan'
         steps = args['steps']
         steps ? "(#{steps.length} steps)" : ''
+      when 'delegate_task'
+        task_preview = args['task'].to_s[0, 100]
+        task_preview += '...' if args['task'].to_s.length > 100
+        agent = args['agent'] ? ", agent: \"#{args['agent']}\"" : ''
+        "(\"#{task_preview}\"#{agent})"
       else ''
       end
     end
@@ -1104,6 +1124,9 @@ module RailsConsoleAi
       when 'execute_plan'
         steps_done = result.scan(/^Step \d+/).length
         steps_done > 0 ? "#{steps_done} steps executed" : truncate(result, 80)
+      when 'delegate_task'
+        # Show the full sub-agent result — this is the whole point of delegation
+        result
       else
         truncate(result, 80)
       end
@@ -1390,7 +1413,7 @@ module RailsConsoleAi
     end
 
     def trim_message(msg)
-      ref = "[Output omitted — use recall_output tool with id #{msg[:output_id]} to retrieve]"
+      ref = "[Output omitted — use explore_output with output_id=#{msg[:output_id]} for focused queries, or recall_output to expand in place]"
 
       if msg[:content].is_a?(Array)
         trimmed_content = msg[:content].map do |block|

data/lib/rails_console_ai/sub_agent.rb

@@ -0,0 +1,229 @@
+require 'rails_console_ai/channel/sub_agent'
+require 'rails_console_ai/tools/registry'
+require 'rails_console_ai/providers/base'
+require 'rails_console_ai/executor'
+
+module RailsConsoleAi
+  class SubAgent
+    LOOP_WARN_THRESHOLD = 3
+    LOOP_BREAK_THRESHOLD = 5
+    LARGE_OUTPUT_THRESHOLD = 10_000
+    LARGE_OUTPUT_PREVIEW_CHARS = 8_000
+
+    attr_reader :input_tokens, :output_tokens, :model_used
+
+    def initialize(task:, agent_config:, binding_context:, parent_channel:, executor:,
+                   output_payload: nil, output_local_name: :output)
+      @task = task
+      @agent_config = agent_config || {}
+      @binding_context = binding_context
+      @parent_channel = parent_channel
+      @parent_executor = executor
+      @output_payload = output_payload
+      @output_local_name = output_local_name
+      @input_tokens = 0
+      @output_tokens = 0
+      @model_used = nil
+    end
+
+    def run
+      channel = Channel::SubAgent.new(
+        parent_channel: @parent_channel,
+        task_label: @agent_config['name']
+      )
+
+      effective_binding =
+        if @output_payload
+          b = @binding_context.eval("proc { binding }.call")
+          b.local_variable_set(@output_local_name, @output_payload)
+          b
+        else
+          @binding_context
+        end
+
+      executor = Executor.new(effective_binding, channel: channel)
+      allowed_tools = @agent_config['tools'] ? Array(@agent_config['tools']) : nil
+      tools = Tools::Registry.new(executor: executor, mode: :sub_agent, channel: channel, allowed_tools: allowed_tools)
+      provider = build_provider
+      system_prompt = build_system_prompt
+      max_rounds = @agent_config['max_rounds'] || RailsConsoleAi.configuration.sub_agent_max_rounds
+
+      messages = [{ role: :user, content: @task }]
+
+      run_tool_loop(messages, system_prompt: system_prompt, tools: tools,
+                    provider: provider, channel: channel, executor: executor,
+                    max_rounds: max_rounds)
+    end
+
+    private
+
+    def run_tool_loop(messages, system_prompt:, tools:, provider:, channel:, executor:, max_rounds:)
+      result = nil
+      tool_call_counts = Hash.new(0)
+      exhausted = false
+      last_thinking = nil
+
+      max_rounds.times do |round|
+        break if channel.cancelled?
+
+        if round == 0
+          channel.display_status("Thinking...")
+        end
+
+        begin
+          result = provider.chat_with_tools(messages, tools: tools, system_prompt: system_prompt)
+        rescue Providers::ProviderError => e
+          raise
+        end
+        @input_tokens += result.input_tokens || 0
+        @output_tokens += result.output_tokens || 0
+
+        break if channel.cancelled?
+        break unless result.tool_use?
+
+        # Display the LLM's reasoning text before executing its tool calls
+        if result.text && !result.text.strip.empty?
+          result.text.strip.split("\n").each do |line|
+            channel.display_thinking("  #{line}")
+          end
+        end
+
+        assistant_msg = provider.format_assistant_message(result)
+        messages << assistant_msg
+
+        result.tool_calls.each do |tc|
+          break if channel.cancelled?
+
+          args_display = tc[:arguments].map { |k, v|
+            val = v.to_s
+            val = val[0, 60] + '...' if val.length > 60
+            "#{k}: #{val.inspect}"
+          }.join(', ')
+          channel.display_tool_call("#{tc[:name]}(#{args_display})")
+
+          tool_result = tools.execute(tc[:name], tc[:arguments])
+
+          preview = tool_result.to_s.lines.first(3).join.strip
+          preview = preview[0, 120] + '...' if preview.length > 120
+          channel.display_status("  #{preview}")
+
+          # Truncate large outputs to keep sub-agent context lean
+          tool_result_str = tool_result.to_s
+          if tool_result_str.length > LARGE_OUTPUT_THRESHOLD
+            tool_result_str = tool_result_str[0, LARGE_OUTPUT_PREVIEW_CHARS] +
+              "\n\n[Output truncated at #{LARGE_OUTPUT_PREVIEW_CHARS} of #{tool_result_str.length} chars]"
+          end
+
+          tool_msg = provider.format_tool_result(tc[:id], tool_result_str)
+          messages << tool_msg
+        end
+
+        # Loop detection
+        result.tool_calls.each do |tc|
+          key = "#{tc[:name]}:#{tc[:arguments].to_json}"
+          tool_call_counts[key] += 1
+
+          if tool_call_counts[key] >= LOOP_BREAK_THRESHOLD
+            channel.display_status("Loop detected — stopping.")
+            exhausted = true
+          elsif tool_call_counts[key] >= LOOP_WARN_THRESHOLD
+            messages << { role: :user, content: "You are repeating the same tool call with the same arguments. Try a different approach or provide your answer now." }
+          end
+        end
+        break if exhausted
+
+        break if executor.last_cancelled?
+
+        exhausted = true if round == max_rounds - 1
+      end
+
+      if exhausted
+        messages << { role: :user, content: "Provide your best answer now based on what you've learned." }
+        result = provider.chat(messages, system_prompt: system_prompt)
+        @input_tokens += result.input_tokens || 0
+        @output_tokens += result.output_tokens || 0
+      end
+
+      result&.text || '(sub-agent returned no result)'
+    end
+
+    def build_provider
+      config = RailsConsoleAi.configuration
+      model_override = @agent_config['model'] || config.sub_agent_model
+
+      if model_override
+        config_dup = config.dup
+        config_dup.model = model_override
+        @model_used = model_override
+        Providers.build(config_dup)
+      else
+        @model_used = config.resolved_model
+        Providers.build(config)
+      end
+    end
+
+    def build_system_prompt
+      parts = []
+      parts << base_instructions
+      parts << guide_context
+      parts << pinned_memory_context
+      parts << @agent_config['body'] if @agent_config['body'] && !@agent_config['body'].strip.empty?
+      parts.compact.join("\n\n")
+    end
+
+    def base_instructions
+      <<~PROMPT.strip
+        You are a sub-agent assistant for a Ruby on Rails application. You have been delegated
+        a specific investigation task. Your job is to use the available tools to find the answer
+        efficiently, then provide a concise summary of your findings.
+
+        RULES:
+        - Focus on the specific task you were given. Do not go on tangents.
+        - Use tools to look up schema/model details rather than guessing.
+        - Prefer ActiveRecord query interface over raw SQL.
+        - Use describe_model to understand models before querying them.
+        - NEVER fabricate URLs, IDs, or data. Always look things up using model methods.
+        - When you find methods on a model (e.g. via .methods.grep), USE them rather than
+          constructing values manually.
+        - End with a concise, factual summary. Include specific IDs, values, and findings.
+        - Keep your final answer under 300 words.
+      PROMPT
+    end
+
+    def guide_context
+      content = RailsConsoleAi.storage.read(RailsConsoleAi::GUIDE_KEY)
+      return nil if content.nil? || content.strip.empty?
+
+      "## Application Guide\n\n#{content.strip}"
+    rescue => e
+      RailsConsoleAi.logger.debug("SubAgent: guide context failed: #{e.message}")
+      nil
+    end
+
+    def pinned_memory_context
+      channel_mode = @parent_channel.respond_to?(:mode) ? @parent_channel.mode : nil
+      # For sub-agents spawned from Slack, use the Slack channel's pinned memories.
+      # For sub-agents spawned from console, use the console channel's pinned memories.
+      # Fall back to 'slack' if the parent is a sub_agent channel (nested, though we block this).
+      effective_mode = channel_mode == 'sub_agent' ? 'slack' : channel_mode
+      return nil unless effective_mode
+
+      channel_cfg = RailsConsoleAi.configuration.channels[effective_mode] || {}
+      pinned_tags = channel_cfg['pinned_memory_tags'] || []
+      return nil if pinned_tags.empty?
+
+      require 'rails_console_ai/tools/memory_tools'
+      sections = pinned_tags.filter_map do |tag|
+        content = Tools::MemoryTools.new.recall_memories(tag: tag)
+        next if content.nil? || content.include?("No memories")
+        content
+      end
+      return nil if sections.empty?
+
+      "## Key Context (from pinned memories)\n\n" + sections.join("\n\n")
+    rescue => e
+      RailsConsoleAi.logger.debug("SubAgent: pinned memory context failed: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/rails_console_ai/tools/model_tools.rb

@@ -37,8 +37,8 @@ module RailsConsoleAi
 
         # Columns and indexes from the database table
         begin
-          if ActiveRecord::Base.connected?
-            conn = ActiveRecord::Base.connection
+          conn = model.connection
+          if conn
             if conn.tables.include?(model.table_name)
               cols = conn.columns(model.table_name).map do |c|
                 parts = ["#{c.name}:#{c.type}"]

data/lib/rails_console_ai/tools/registry.rb

@@ -3,19 +3,21 @@ require 'json'
 module RailsConsoleAi
   module Tools
     class Registry
-      attr_reader :definitions
+      attr_reader :definitions, :last_sub_agent_usage
 
       # Tools that should never be cached (side effects or user interaction)
-      NO_CACHE = %w[ask_user save_memory delete_memory recall_memory execute_code execute_plan activate_skill save_skill delete_skill].freeze
+      NO_CACHE = %w[ask_user save_memory delete_memory recall_memory execute_code execute_plan activate_skill save_skill delete_skill delegate_task explore_output].freeze
 
-      def initialize(executor: nil, mode: :default, channel: nil)
+      def initialize(executor: nil, mode: :default, channel: nil, allowed_tools: nil)
         @executor = executor
         @mode = mode
         @channel = channel
+        @allowed_tools = allowed_tools
         @definitions = []
         @handlers = {}
         @cache = {}
         @last_cached = false
+        @last_sub_agent_usage = nil
         register_all
       end
 
@@ -186,7 +188,7 @@ module RailsConsoleAi
         if @executor
           register(
             name: 'recall_output',
-            description: 'Retrieve a previous code execution output that was omitted or truncated. The output will be expanded in place in the conversation. Use the output id shown in the "[Output omitted]" or "[Output truncated]" placeholder.',
+            description: 'Expand a previously omitted/truncated output back into this conversation\'s context, where it will persist for the rest of the session. Prefer `explore_output` if you only need a specific answer about the output — that keeps this conversation lean. Use `recall_output` only when you need the full content alongside other context here. Use the output id shown in the "[Output omitted]" or "[Output truncated]" placeholder.',
             parameters: {
               'type' => 'object',
               'properties' => {
@@ -202,7 +204,7 @@ module RailsConsoleAi
 
           register(
             name: 'recall_outputs',
-            description: 'Retrieve multiple previous code execution outputs that were omitted from the conversation. Use the output ids shown in "[Output omitted]" or "[Output truncated]" placeholders.',
+            description: 'Expand multiple previously omitted outputs back into this conversation. Prefer `explore_output` per-id for focused queries. Use the output ids shown in "[Output omitted]" or "[Output truncated]" placeholders.',
             parameters: {
               'type' => 'object',
               'properties' => {
@@ -212,26 +214,188 @@ module RailsConsoleAi
             },
             handler: ->(args) { "recall_outputs handled by conversation engine" }
           )
+
+          if @mode != :sub_agent
+            register(
+              name: 'explore_output',
+              description: 'Prefer this over recall_output when you have a specific question about a large omitted/truncated output (e.g. "find the item where X", "how many match Y", "what is the value at index N", "parse the JSON and return field Z"). Spawns a sub-agent with the full output bound to the local Ruby variable `output` (a String); the sub-agent runs execute_code against it and returns a concise answer. The full output does NOT enter this conversation.',
+              parameters: {
+                'type' => 'object',
+                'properties' => {
+                  'output_id' => { 'type' => 'integer', 'description' => 'The output id shown in the "[Output omitted]" or "[Output truncated]" placeholder.' },
+                  'task' => { 'type' => 'string', 'description' => 'The specific question or task. Be concrete — the sub-agent only sees this task and the output.' }
+                },
+                'required' => ['output_id', 'task']
+              },
+              handler: ->(args) { explore_output(args['output_id'].to_i, args['task']) }
+            )
+          end
         end
 
         unless @mode == :init
-          register(
-            name: 'ask_user',
-            description: 'Ask the console user a clarifying question. Use this when you need specific information to write accurate code (e.g. which user they are, which record to target, what value to use). Do NOT generate placeholder values like YOUR_USER_ID — ask instead.',
-            parameters: {
-              'type' => 'object',
-              'properties' => {
-                'question' => { 'type' => 'string', 'description' => 'The question to ask the user' }
+          # Sub-agents get execute_code and read-only memory tools, but not ask_user,
+          # memory writes, skill writes, execute_plan, or delegate_task.
+          if @mode == :sub_agent
+            register_memory_recall_tools
+            register_execute_code
+          else
+            register(
+              name: 'ask_user',
+              description: 'Ask the console user a clarifying question. Use this when you need specific information to write accurate code (e.g. which user they are, which record to target, what value to use). Do NOT generate placeholder values like YOUR_USER_ID — ask instead.',
+              parameters: {
+                'type' => 'object',
+                'properties' => {
+                  'question' => { 'type' => 'string', 'description' => 'The question to ask the user' }
+                },
+                'required' => ['question']
               },
-              'required' => ['question']
+              handler: ->(args) { ask_user(args['question']) }
+            )
+
+            register_memory_tools
+            register_skill_tools
+            register_execute_plan
+            register_delegate_task
+          end
+        end
+      end
+
+      def register_memory_recall_tools
+        return unless RailsConsoleAi.configuration.memories_enabled
+
+        require 'rails_console_ai/tools/memory_tools'
+        memory = MemoryTools.new
+
+        register(
+          name: 'recall_memory',
+          description: 'Retrieve a specific memory by name.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'name' => { 'type' => 'string', 'description' => 'The exact memory name' }
             },
-            handler: ->(args) { ask_user(args['question']) }
-          )
+            'required' => ['name']
+          },
+          handler: ->(args) { memory.recall_memory(name: args['name']) }
+        )
+
+        register(
+          name: 'recall_memories',
+          description: 'Search saved memories about this codebase. Call with no args to list all, or pass a query/tag to filter.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'query' => { 'type' => 'string', 'description' => 'Search term to filter by name, description, or tags' },
+              'tag' => { 'type' => 'string', 'description' => 'Filter by a specific tag' }
+            }
+          },
+          handler: ->(args) { memory.recall_memories(query: args['query'], tag: args['tag']) }
+        )
+      end
+
+      def register_execute_code
+        return unless @executor
+
+        register(
+          name: 'execute_code',
+          description: 'Execute Ruby code in the Rails console and return the result.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'code' => { 'type' => 'string', 'description' => 'Ruby code to execute' }
+            },
+            'required' => ['code']
+          },
+          handler: ->(args) { execute_code(args['code']) }
+        )
+      end
+
+      def register_delegate_task
+        return unless @executor
 
-          register_memory_tools
-          register_skill_tools
-          register_execute_plan
+        register(
+          name: 'delegate_task',
+          description: 'Delegate an investigation to a sub-agent that runs in a separate context. ' \
+            'Use this for tasks that require multiple tool calls to figure out ' \
+            '(e.g., "find which shard user X is on", "search the codebase for how URL generation works", ' \
+            '"describe the relationships between models A, B, and C"). ' \
+            'The sub-agent runs independently and returns only a concise summary, ' \
+            'keeping this conversation\'s context small and efficient.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'task' => { 'type' => 'string', 'description' => 'What to investigate. Be specific about what you need to know.' },
+              'agent' => { 'type' => 'string', 'description' => 'Optional: name of a custom agent to use (see Agents list in system prompt). Omit for general investigation.' }
+            },
+            'required' => ['task']
+          },
+          handler: ->(args) { delegate_task(args['task'], args['agent']) }
+        )
+      end
+
+      EXPLORE_OUTPUT_AGENT_CONFIG = {
+        'name' => 'output-explorer',
+        'tools' => ['execute_code'],
+        'max_rounds' => 8,
+        'body' => <<~PROMPT.freeze
+          You are exploring a single chunk of captured tool output on behalf of the main assistant.
+
+          The full output is bound to the local variable `output` (a String). You do NOT see it
+          directly — it lives in Ruby memory. Use `execute_code` with Ruby to query it:
+            - `output.length`, `output.lines.count`
+            - `output[start, len]`, `output.lines[n]`
+            - `output.scan(/pattern/)`, `output.include?("...")`
+            - `JSON.parse(output)` if it looks like JSON, then drill in
+            - any other Ruby string/collection methods
+
+          Print only the specific slice or summary the task requires — never dump the whole `output`.
+          Return a concise factual answer. No preamble.
+        PROMPT
+      }.freeze
+
+      def explore_output(output_id, task)
+        require 'rails_console_ai/sub_agent'
+
+        payload = @executor.recall_output(output_id)
+        return "No output found with id #{output_id}" unless payload
+
+        sub = SubAgent.new(
+          task: task,
+          agent_config: EXPLORE_OUTPUT_AGENT_CONFIG,
+          binding_context: @executor.binding_context,
+          parent_channel: @channel,
+          executor: @executor,
+          output_payload: payload.dup
+        )
+        result = sub.run
+        @last_sub_agent_usage = { input: sub.input_tokens, output: sub.output_tokens, model: sub.model_used }
+        "Exploration result (#{sub.input_tokens + sub.output_tokens} tokens used, #{payload.length} chars explored):\n#{result}"
+      end
+
+      def delegate_task(task, agent_name = nil)
+        require 'rails_console_ai/sub_agent'
+        require 'rails_console_ai/agent_loader'
+
+        agent_config = nil
+        if agent_name
+          loader = AgentLoader.new
+          agent_config = loader.find_agent(agent_name)
+          unless agent_config
+            available = loader.load_all_agents.map { |a| a['name'] }
+            return "Agent not found: \"#{agent_name}\". Available agents: #{available.join(', ')}"
+          end
         end
+
+        sub = SubAgent.new(
+          task: task,
+          agent_config: agent_config,
+          binding_context: @executor.binding_context,
+          parent_channel: @channel,
+          executor: @executor
+        )
+        result = sub.run
+        @last_sub_agent_usage = { input: sub.input_tokens, output: sub.output_tokens, model: sub.model_used }
+        "Sub-agent result (#{sub.input_tokens + sub.output_tokens} tokens used):\n#{result}"
       end
 
       def register_memory_tools
@@ -412,7 +576,7 @@ module RailsConsoleAi
         # Show the code to the user
         @executor.display_code_block(code)
 
-        exec_result = if @channel&.mode == 'slack' || RailsConsoleAi.configuration.auto_execute
+        exec_result = if @channel&.mode == 'slack' || @channel&.mode == 'sub_agent' || RailsConsoleAi.configuration.auto_execute
                         @executor.execute(code)
                       else
                         @executor.confirm_and_execute(code)
@@ -547,6 +711,13 @@ module RailsConsoleAi
           end
           step_report += "Return value: #{exec_result.inspect}"
           results << step_report
+
+          # Stop on error so the LLM can fix the failed step before continuing
+          if error
+            remaining = steps.length - i - 1
+            results << "PLAN HALTED: Step #{i + 1} failed. #{remaining} remaining step(s) were not executed. Fix the error and retry the remaining steps." if remaining > 0
+            break
+          end
         end
 
         results.join("\n\n")
@@ -609,6 +780,11 @@ module RailsConsoleAi
       end
 
       def register(name:, description:, parameters:, handler:)
+        # When allowed_tools is set (sub-agent with tool filter), skip tools not in the list
+        if @allowed_tools && !@allowed_tools.include?(name)
+          return
+        end
+
         @definitions << {
           name: name,
           description: description,

data/lib/rails_console_ai/tools/schema_tools.rb

@@ -18,18 +18,19 @@ module RailsConsoleAi
         return "Error: table_name is required." if table_name.nil? || table_name.strip.empty?
 
         table_name = table_name.strip
-        unless connection.tables.include?(table_name)
+        conn = connection_for_table(table_name)
+        unless conn.tables.include?(table_name)
           return "Table '#{table_name}' not found. Use list_tables to see available tables."
         end
 
-        cols = connection.columns(table_name).map do |c|
+        cols = conn.columns(table_name).map do |c|
           parts = ["#{c.name}:#{c.type}"]
           parts << "nullable" if c.null
           parts << "default=#{c.default}" unless c.default.nil?
           parts.join(" ")
         end
 
-        indexes = connection.indexes(table_name).map do |idx|
+        indexes = conn.indexes(table_name).map do |idx|
           unique = idx.unique ? "UNIQUE " : ""
           "#{unique}INDEX on (#{idx.columns.join(', ')})"
         end
@@ -52,6 +53,22 @@ module RailsConsoleAi
         defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
       end
 
+      # Find the best connection for a table by checking if any model maps to it.
+      # Models may use a different connection (e.g. sharded databases).
+      def connection_for_table(table_name)
+        if defined?(ActiveRecord::Base) && ActiveRecord::Base.is_a?(Class)
+          base = defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base
+          model = ObjectSpace.each_object(Class).detect { |c|
+            c < base && !c.abstract_class? && c.name &&
+              begin; c.table_name == table_name; rescue; false; end
+          }
+          return model.connection if model
+        end
+        connection
+      rescue
+        connection
+      end
+
       def connection
         ActiveRecord::Base.connection
       end

data/lib/rails_console_ai/version.rb

@@ -1,3 +1,3 @@
 module RailsConsoleAi
-  VERSION = '0.25.0'.freeze
+  VERSION = '0.27.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_console_ai
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Cortfr
@@ -100,9 +100,13 @@ files:
 - lib/generators/rails_console_ai/install_generator.rb
 - lib/generators/rails_console_ai/templates/initializer.rb
 - lib/rails_console_ai.rb
+- lib/rails_console_ai/agent_loader.rb
+- lib/rails_console_ai/agents/explore-data.md
+- lib/rails_console_ai/agents/investigate-code.md
 - lib/rails_console_ai/channel/base.rb
 - lib/rails_console_ai/channel/console.rb
 - lib/rails_console_ai/channel/slack.rb
+- lib/rails_console_ai/channel/sub_agent.rb
 - lib/rails_console_ai/configuration.rb
 - lib/rails_console_ai/console_methods.rb
 - lib/rails_console_ai/context_builder.rb
@@ -123,6 +127,7 @@ files:
 - lib/rails_console_ai/slack_bot.rb
 - lib/rails_console_ai/storage/base.rb
 - lib/rails_console_ai/storage/file_storage.rb
+- lib/rails_console_ai/sub_agent.rb
 - lib/rails_console_ai/tools/code_tools.rb
 - lib/rails_console_ai/tools/memory_tools.rb
 - lib/rails_console_ai/tools/model_tools.rb