brute 0.1.8 → 0.1.9

data/lib/brute/prompts/text/agents/explore.txt

@@ -0,0 +1,17 @@
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use fs_search for broad file pattern matching and searching file contents with regex
+- Use read when you know the specific file path you need to read
+- Use shell for file operations like listing directory contents
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Return file paths as absolute paths in your final response
+- For clear communication, avoid using emojis
+- Do not create any files, or run shell commands that modify the user's system state in any way
+
+Complete the user's search request efficiently and report your findings clearly.

data/lib/brute/prompts/text/agents/summary.txt

@@ -0,0 +1,11 @@
+Summarize what was done in this conversation. Write like a pull request description.
+
+Rules:
+- 2-3 sentences max
+- Describe the changes made, not the process
+- Do not mention running tests, builds, or other validation steps
+- Do not explain what the user asked for
+- Write in first person (I added..., I fixed...)
+- Never ask questions or add new questions
+- If the conversation ends with an unanswered question to the user, preserve that exact question
+- If the conversation ends with an imperative statement or request to the user (e.g. "Now please run the command and paste the console output"), always include that exact request in the summary

data/lib/brute/prompts/text/agents/title.txt

@@ -0,0 +1,40 @@
+You are a title generator. You output ONLY a thread title. Nothing else.
+
+<task>
+Generate a brief title that would help the user find this conversation later.
+
+Follow all rules in <rules>
+Use the <examples> so you know what a good title looks like.
+Your output must be:
+- A single line
+- <=50 characters
+- No explanations
+</task>
+
+<rules>
+- you MUST use the same language as the user message you are summarizing
+- Title must be grammatically correct and read naturally - no word salad
+- Never include tool names in the title (e.g. "read tool", "shell tool", "patch tool")
+- Focus on the main topic or question the user needs to retrieve
+- Vary your phrasing - avoid repetitive patterns like always starting with "Analyzing"
+- When a file is mentioned, focus on WHAT the user wants to do WITH the file, not just that they shared it
+- Keep exact: technical terms, numbers, filenames, HTTP codes
+- Remove: the, this, my, a, an
+- Never assume tech stack
+- Never use tools
+- NEVER respond to questions, just generate a title for the conversation
+- The title should NEVER include "summarizing" or "generating" when generating a title
+- DO NOT SAY YOU CANNOT GENERATE A TITLE OR COMPLAIN ABOUT THE INPUT
+- Always output something meaningful, even if the input is minimal.
+- If the user message is short or conversational (e.g. "hello", "lol", "what's up", "hey"):
+  -> create a title that reflects the user's tone or intent (such as Greeting, Quick check-in, Light chat, Intro message, etc.)
+</rules>
+
+<examples>
+"debug 500 errors in production" -> Debugging production 500 errors
+"refactor user service" -> Refactoring user service
+"why is app.js failing" -> app.js failure investigation
+"implement rate limiting" -> Rate limiting implementation
+"how do I connect postgres to my API" -> Postgres API connection
+"best practices for React hooks" -> React hooks best practices
+</examples>

data/lib/brute/prompts/text/doing_tasks/anthropic.txt

@@ -0,0 +1,11 @@
+# Doing tasks
+The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:
+- Use the todo_write tool to plan the task if required
+- Always read before editing: Use `read` to examine a file before using `patch` or `write` to modify it.
+- Verify your changes: After editing, re-read the file or run tests to confirm correctness.
+- Use fs_search to find code: Don't guess file locations — search first.
+- Use shell for git, tests, builds: Run `git diff`, `git status`, test suites, etc.
+- Be precise with patch: The `old_string` must match the file content exactly, including whitespace.
+- Prefer patch over write: For existing files, use `patch` to change specific sections rather than rewriting the entire file.
+- Use undo to recover: If a write or patch goes wrong, use `undo` to restore the previous version.
+- Delegate research: Use `delegate` for complex analysis that needs focused investigation.

data/lib/brute/prompts/text/doing_tasks/default.txt

@@ -0,0 +1,6 @@
+# Doing tasks
+The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:
+- Use the available search tools to understand the codebase and the user's query. Use search tools extensively both in parallel and sequentially.
+- Implement the solution using all tools available to you
+- Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the README or search codebase to determine the testing approach.
+- NEVER commit changes unless the user explicitly asks you to.

data/lib/brute/prompts/text/doing_tasks/google.txt

@@ -0,0 +1,9 @@
+# Primary Workflows
+
+## Software Engineering Tasks
+When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
+1. **Understand:** Use fs_search and read tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.
+2. **Plan:** Build a coherent plan based on your understanding. Share a concise plan with the user if it would help them understand your approach.
+3. **Implement:** Use the available tools (patch, write, shell, etc.) to act on the plan, strictly adhering to the project's established conventions.
+4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. NEVER assume standard test commands.
+5. **Verify (Standards):** After making code changes, execute the project-specific build, linting and type-checking commands that you have identified for this project.

data/lib/brute/prompts/text/identity/anthropic.txt

@@ -0,0 +1,5 @@
+You are Brute, an expert software engineering agent.
+
+You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+
+IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.

data/lib/brute/prompts/text/identity/default.txt

@@ -0,0 +1,3 @@
+You are Brute, an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+
+IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.

data/lib/brute/prompts/text/identity/google.txt

@@ -0,0 +1 @@
+You are Brute, an interactive CLI agent specializing in software engineering tasks. Your primary goal is to help users safely and efficiently, adhering strictly to the following instructions and utilizing your available tools.

data/lib/brute/prompts/text/identity/openai.txt

@@ -0,0 +1,3 @@
+You are Brute. You and the user share the same workspace and collaborate to achieve the user's goals.
+
+You are a deeply pragmatic, effective software engineer. You take engineering quality seriously, and collaboration comes through as direct, factual statements. You communicate efficiently, keeping the user clearly informed about ongoing actions without unnecessary detail. You build context by examining the codebase first without making assumptions or jumping to conclusions. You think through the nuances of the code you encounter, and embody the mentality of a skilled senior software engineer.

data/lib/brute/prompts/text/tone_and_style/anthropic.txt

@@ -0,0 +1,5 @@
+# Tone and style
+- Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+- Your output will be displayed on a command line interface. Your responses should be short and concise. You can use GitHub-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+- Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like shell or code comments as means to communicate with the user during the session.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.

data/lib/brute/prompts/text/tone_and_style/default.txt

@@ -0,0 +1,9 @@
+# Tone and style
+You should be concise, direct, and to the point. When you run a non-trivial shell command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing.
+Remember that your output will be displayed on a command line interface. Your responses can use GitHub-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like shell or code comments as means to communicate with the user during the session.
+If you cannot or will not help the user with something, please do not say why or what it could lead to. Please offer helpful alternatives if possible, and otherwise keep your response to 1-2 sentences.
+Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
+IMPORTANT: You should minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand.
+IMPORTANT: You should NOT answer with unnecessary preamble or postamble (such as explaining your code or summarizing your action), unless the user asks you to.
+IMPORTANT: Keep your responses short. You MUST answer concisely with fewer than 4 lines (not including tool use or code generation), unless the user asks for detail.

data/lib/brute/prompts/text/tone_and_style/google.txt

@@ -0,0 +1,6 @@
+# Tone and Style
+- **Concise & Direct:** Adopt a professional, direct, and concise tone suitable for a CLI environment.
+- **Minimal Output:** Aim for fewer than 3 lines of text output (excluding tool use/code generation) per response whenever practical.
+- **No Chitchat:** Avoid conversational filler, preambles ("Okay, I will now..."), or postambles ("I have finished the changes..."). Get straight to the action or answer.
+- **Formatting:** Use GitHub-flavored Markdown. Responses will be rendered in monospace.
+- **Tools vs. Text:** Use tools for actions, text output *only* for communication.

data/lib/brute/prompts/text/tone_and_style/openai.txt

@@ -0,0 +1,17 @@
+# Working with the user
+
+Do not begin responses with conversational interjections or meta commentary. Avoid openers such as acknowledgements ("Done —", "Got it", "Great question") or framing phrases.
+
+Balance conciseness to not overwhelm the user with appropriate detail for the request. Do not narrate abstractly; explain what you are doing and why.
+
+## Formatting rules
+
+Your responses are rendered as GitHub-flavored Markdown.
+
+Never use nested bullets. Keep lists flat (single level). If you need hierarchy, split into separate lists or sections.
+
+Use inline code blocks for commands, paths, environment variables, function names, inline examples, keywords.
+
+Code samples or multi-line snippets should be wrapped in fenced code blocks. Include a language tag when possible.
+
+Don't use emojis or em dashes unless explicitly instructed.

data/lib/brute/prompts/text/tool_usage/anthropic.txt

@@ -0,0 +1,16 @@
+# Tool usage policy
+- When doing file search, prefer to use the delegate tool in order to reduce context usage.
+- You should proactively use the delegate tool with specialized agents when the task at hand matches the agent's description.
+- You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel. Maximize use of parallel tool calls where possible to increase efficiency. However, if some tool calls depend on previous calls to inform dependent values, do NOT call these tools in parallel and instead call them sequentially. For instance, if one operation must complete before another starts, run these operations sequentially instead. Never use placeholders or guess missing parameters in tool calls.
+- Use specialized tools instead of shell commands when possible, as this provides a better user experience. For file operations, use dedicated tools: read for reading files instead of cat/head/tail, patch for editing instead of sed/awk, and write for creating files instead of cat with heredoc or echo redirection. Reserve the shell tool exclusively for actual system commands and terminal operations that require shell execution. NEVER use shell echo or other command-line tools to communicate thoughts, explanations, or instructions to the user. Output all communication directly in your response text instead.
+- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the delegate tool instead of running search commands directly.
+<example>
+user: Where are errors from the client handled?
+assistant: [Uses the delegate tool to find the files that handle client errors instead of using fs_search directly]
+</example>
+<example>
+user: What is the codebase structure?
+assistant: [Uses the delegate tool]
+</example>
+
+IMPORTANT: Always use the todo_write tool to plan and track tasks throughout the conversation.

data/lib/brute/prompts/text/tool_usage/default.txt

@@ -0,0 +1,4 @@
+# Tool usage policy
+- When doing file search, prefer to use the delegate tool in order to reduce context usage.
+- You can call multiple tools in a single response. When multiple independent pieces of information are requested, batch your tool calls together for optimal performance.
+- Use specialized tools (read, patch, write, fs_search) instead of shell commands for file operations.

data/lib/brute/prompts/text/tool_usage/google.txt

@@ -0,0 +1,4 @@
+# Tool Usage
+- **Parallelism:** Execute multiple independent tool calls in parallel when feasible.
+- **Specialized tools:** Use read, patch, write, and fs_search instead of shell commands for file operations.
+- **Interactive Commands:** Avoid shell commands that require user interaction (e.g. `git rebase -i`). Use non-interactive versions of commands.

data/lib/brute/prompts/tone_and_style.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Brute
+  module Prompts
+    module ToneAndStyle
+      def self.call(ctx)
+        Prompts.read("tone_and_style", ctx[:provider_name])
+      end
+    end
+  end
+end

data/lib/brute/prompts/tool_usage.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Brute
+  module Prompts
+    module ToolUsage
+      def self.call(ctx)
+        Prompts.read("tool_usage", ctx[:provider_name])
+      end
+    end
+  end
+end

data/lib/brute/skill.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Brute
+  # Discovers and loads SKILL.md files from standard directories.
+  #
+  # A skill is a markdown file with YAML frontmatter:
+  #
+  #   ---
+  #   name: debugging
+  #   description: Systematic debugging workflow for isolating and fixing bugs
+  #   ---
+  #
+  #   When debugging, follow these steps...
+  #
+  # Skills are scanned from (in order):
+  #   1. .brute/skills/**/SKILL.md   (project-local)
+  #   2. ~/.config/brute/skills/**/SKILL.md (global)
+  #
+  # The directory name containing SKILL.md becomes the skill name if frontmatter
+  # doesn't specify one.
+  #
+  module Skill
+    Info = Struct.new(:name, :description, :location, :content, keyword_init: true)
+
+    FILENAME = "SKILL.md"
+
+    # Scan all skill directories and return an array of Info structs.
+    def self.all(cwd: Dir.pwd)
+      skills = {}
+
+      scan_dirs(cwd).each do |dir|
+        Dir.glob(File.join(dir, "**", FILENAME)).sort.each do |path|
+          info = load(path)
+          next unless info
+          # First found wins (project-local overrides global)
+          skills[info.name] ||= info
+        end
+      end
+
+      skills.values.sort_by(&:name)
+    end
+
+    # Get a single skill by name.
+    def self.get(name, cwd: Dir.pwd)
+      all(cwd: cwd).detect { |s| s.name == name }
+    end
+
+    # Format skills as XML for the system prompt.
+    def self.fmt(skills)
+      return nil if skills.empty?
+
+      lines = ["<available_skills>"]
+      skills.each do |skill|
+        lines << "  <skill>"
+        lines << "    <name>#{skill.name}</name>"
+        lines << "    <description>#{skill.description}</description>"
+        lines << "  </skill>"
+      end
+      lines << "</available_skills>"
+      lines.join("\n")
+    end
+
+    # Parse a SKILL.md file into an Info struct.
+    # Returns nil if the file is invalid or missing required fields.
+    def self.load(path)
+      raw = File.read(path)
+      frontmatter, content = parse_frontmatter(raw)
+      return nil unless frontmatter
+
+      name = frontmatter["name"] || File.basename(File.dirname(path))
+      description = frontmatter["description"]
+      return nil unless description && !description.strip.empty?
+
+      Info.new(
+        name: name.to_s.strip,
+        description: description.to_s.strip,
+        location: path,
+        content: content.to_s.strip,
+      )
+    rescue => e
+      warn "Failed to load skill #{path}: #{e.message}"
+      nil
+    end
+
+    # Directories to scan for skills, in priority order.
+    def self.scan_dirs(cwd)
+      dirs = []
+
+      # Project-local
+      project = File.join(cwd, ".brute", "skills")
+      dirs << project if File.directory?(project)
+
+      # Global
+      global = File.join(Dir.home, ".config", "brute", "skills")
+      dirs << global if File.directory?(global)
+
+      dirs
+    end
+
+    # Split YAML frontmatter from markdown body.
+    # Returns [hash, string] or [nil, nil].
+    def self.parse_frontmatter(raw)
+      return [nil, nil] unless raw.start_with?("---")
+
+      parts = raw.split(/^---\s*$/, 3)
+      return [nil, nil] if parts.length < 3
+
+      frontmatter = YAML.safe_load(parts[1])
+      return [nil, nil] unless frontmatter.is_a?(Hash)
+
+      [frontmatter, parts[2]]
+    end
+
+    private_class_method :scan_dirs, :parse_frontmatter
+  end
+end

data/lib/brute/system_prompt.rb

@@ -1,88 +1,143 @@
 # frozen_string_literal: true
 
 module Brute
-  # Builds the system prompt dynamically based on available tools, environment,
-  # custom rules, and working directory context.
+  # Deferred system prompt builder.
+  #
+  # The block passed to +build+ is stored — not executed — until +prepare+
+  # is called with a runtime context hash (provider_name, model_name, cwd, etc).
+  #
+  #   sp = Brute::SystemPrompt.build do |prompt, ctx|
+  #     prompt << Brute::Prompts::Identity.call(ctx)
+  #     prompt << Brute::Prompts::ToneAndStyle.call(ctx)
+  #     prompt << Brute::Prompts::Environment.call(ctx)
+  #   end
+  #
+  #   result = sp.prepare(provider_name: "anthropic", model_name: "claude-sonnet-4-20250514", cwd: Dir.pwd)
+  #   result.to_s       # single joined string
+  #   result.sections   # array of strings (one per p.system call)
   #
-  # Modeled after forgecode's SystemPrompt which composes a static agent
-  # personality block with dynamic environment/tool information.
   class SystemPrompt
-    def initialize(cwd: Dir.pwd, tools: [], custom_rules: nil)
-      @cwd = cwd
-      @tools = tools
-      @custom_rules = custom_rules
+    # Build a deferred system prompt. The block is stored and called later by +prepare+.
+    def self.build(&block)
+      new(block)
     end
 
-    def build
-      sections = []
-      sections << identity_section
-      sections << tools_section
-      sections << guidelines_section
-      sections << environment_section
-      sections << custom_rules_section if @custom_rules
-      sections.compact.join("\n\n")
-    end
+    # Return the default system prompt. Selects the right provider stack at
+    # prepare-time, then appends conditional sections based on runtime state.
+    def self.default
+      build do |prompt, ctx|
+        # Provider-specific base stack
+        provider = ctx[:provider_name].to_s
+        STACKS.fetch(provider, STACKS["default"]).each do |mod|
+          prompt << mod.call(ctx)
+        end
 
-    private
+        # Conditional: agent-specific reminders
+        if ctx[:agent] == "plan"
+          prompt << Prompts::PlanReminder.call(ctx)
+        end
 
-    def identity_section
-      <<~SECTION
-        # Identity
+        if ctx[:agent_switched] == "build"
+          prompt << Prompts::BuildSwitch.call(ctx)
+        end
 
-        You are Brute, an expert software engineering agent. You help users with coding tasks
-        by reading, writing, and editing files, running shell commands, and searching codebases.
-        You are methodical, precise, and always verify your work.
-      SECTION
+        if ctx[:max_steps_reached]
+          prompt << Prompts::MaxSteps.call(ctx)
+        end
+      end
     end
 
-    def tools_section
-      tool_list = LLM::Function.registry.filter_map { |fn|
-        "- **#{fn.name}**: #{fn.description.to_s.split(". ").first}."
-      }.join("\n")
+    # Pre-configured prompt stacks per provider.
+    # Each maps a provider name to an ordered list of prompt modules.
+    STACKS = {
+      # Claude — full-featured with task management and detailed tool policy
+      "anthropic" => [
+        Prompts::Identity,
+        Prompts::ToneAndStyle,
+        Prompts::Objectivity,
+        Prompts::TaskManagement,
+        Prompts::DoingTasks,
+        Prompts::ToolUsage,
+        Prompts::Conventions,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
 
-      <<~SECTION
-        # Available Tools
+      # GPT-4 / o1 / o3 — pragmatic engineer persona, editing focus, autonomy
+      "openai" => [
+        Prompts::Identity,
+        Prompts::EditingApproach,
+        Prompts::Autonomy,
+        Prompts::EditingConstraints,
+        Prompts::FrontendTasks,
+        Prompts::ToneAndStyle,
+        Prompts::Conventions,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
 
-        #{tool_list}
-      SECTION
-    end
+      # Gemini — formal/structured, explicit workflows, security focus
+      "google" => [
+        Prompts::Identity,
+        Prompts::Conventions,
+        Prompts::DoingTasks,
+        Prompts::ToneAndStyle,
+        Prompts::SecurityAndSafety,
+        Prompts::ToolUsage,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
 
-    def guidelines_section
-      <<~SECTION
-        # Guidelines
+      # Fallback — conservative, concise, fewer than 4 lines
+      "default" => [
+        Prompts::Identity,
+        Prompts::ToneAndStyle,
+        Prompts::Proactiveness,
+        Prompts::Conventions,
+        Prompts::CodeStyle,
+        Prompts::DoingTasks,
+        Prompts::ToolUsage,
+        Prompts::GitSafety,
+        Prompts::CodeReferences,
+        Prompts::Environment,
+        Prompts::Skills,
+        Prompts::Instructions,
+      ],
+    }.freeze
 
-        - **Always read before editing**: Use `read` to examine a file before using `patch` or `write` to modify it.
-        - **Verify your changes**: After editing, re-read the file or run tests to confirm correctness.
-        - **Use todo_write for multi-step tasks**: Break complex work into steps and track progress.
-        - **Use fs_search to find code**: Don't guess file locations — search first.
-        - **Use shell for git, tests, builds**: Run `git diff`, `git status`, test suites, etc.
-        - **Be precise with patch**: The `old_string` must match the file content exactly, including whitespace.
-        - **Prefer patch over write**: For existing files, use `patch` to change specific sections rather than rewriting the entire file.
-        - **Use undo to recover**: If a write or patch goes wrong, use `undo` to restore the previous version.
-        - **Delegate research**: Use `delegate` for complex analysis that needs focused investigation.
-      SECTION
+    def initialize(block)
+      @block = block
     end
 
-    def environment_section
-      files = Dir.entries(@cwd).reject { |f| f.start_with?(".") }.sort.first(50)
-
-      <<~SECTION
-        # Environment
-
-        - **Working directory**: #{@cwd}
-        - **OS**: #{RUBY_PLATFORM}
-        - **Ruby**: #{RUBY_VERSION}
-        - **Date**: #{Time.now.strftime("%Y-%m-%d")}
-        - **Files in cwd**: #{files.join(", ")}
-      SECTION
+    # Execute the stored block with the given context and return a Result.
+    def prepare(ctx)
+      sections = []
+      @block.call(sections, ctx)
+      Result.new(sections.compact.reject { |s| s.respond_to?(:empty?) && s.empty? })
     end
 
-    def custom_rules_section
-      <<~SECTION
-        # Project-Specific Rules
+    # Immutable result of a prepared system prompt.
+    Result = Struct.new(:sections) do
+      def to_s
+        sections.join("\n\n")
+      end
+
+      def each(&block)
+        sections.each(&block)
+      end
 
-        #{@custom_rules}
-      SECTION
+      def empty?
+        sections.empty?
+      end
     end
   end
 end

data/lib/brute/tools/question.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Brute
+  module Tools
+    class Question < LLM::Tool
+      name "question"
+      description "Ask the user questions during execution. Use this to gather preferences, " \
+                  "clarify ambiguous instructions, get decisions on implementation choices, or " \
+                  "offer choices about direction. Users can always select \"Other\" to provide " \
+                  "custom text input. Answers are returned as arrays of labels; set multiple: true " \
+                  "to allow selecting more than one. If you recommend a specific option, make it " \
+                  "the first option and add \"(Recommended)\" at the end of the label."
+
+      params do |s|
+        s.object(
+          questions: s.array(
+            s.object(
+              question: s.string.required,
+              header: s.string.required,
+              options: s.array(
+                s.object(
+                  label: s.string.required,
+                  description: s.string.required,
+                )
+              ).required,
+              multiple: s.boolean,
+            )
+          ).required
+        )
+      end
+
+      def call(questions:)
+        handler = Thread.current[:on_question]
+        unless handler
+          return { error: true, message: "Cannot ask questions in non-interactive mode" }
+        end
+
+        queue = Queue.new
+        handler.call(questions, queue)
+        answers = queue.pop
+
+        format_answers(questions, answers)
+      end
+
+      private
+
+      def format_answers(questions, answers)
+        pairs = questions.each_with_index.map do |q, i|
+          q = q.transform_keys(&:to_s) if q.is_a?(Hash)
+          header = q["header"]
+          answer = answers[i] || []
+          "\"#{header}\" = #{answer.join(', ')}"
+        end
+
+        { response: "User answered: #{pairs.join('; ')}" }
+      end
+    end
+  end
+end

data/lib/brute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brute
-  VERSION = "0.1.8"
+  VERSION = "0.1.9"
 end